docs consolidation

2025-12-24 21:45:46 +02:00
parent 4231305fec
commit 43e2af88f6
76 changed files with 2887 additions and 796 deletions
--- a/docs/modules/attestor/proof-chain-specification.md
+++ b/docs/modules/attestor/proof-chain-specification.md
@@ -90,6 +90,68 @@ This specification defines the implementation of a cryptographically verifiable
 5. **Numbers in shortest form**
 6. **Deterministic array ordering** (by semantic key: bom-ref, purl)

+### Canonicalization Versioning
+
+Content-addressed identifiers embed a canonicalization version marker to prevent hash collisions when the canonicalization algorithm evolves. This ensures that:
+
+- **Forward compatibility**: Future algorithm changes won't invalidate existing hashes.
+- **Verifier clarity**: Verifiers know exactly which algorithm to use.
+- **Auditability**: Hash provenance is cryptographically bound to algorithm version.
+
+**Version Marker Format:**
+
+```json
+{
+  "_canonVersion": "stella:canon:v1",
+  "sbomEntryId": "...",
+  "vulnerabilityId": "..."
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `_canonVersion` | Underscore prefix ensures lexicographic first position after sorting |
+| Value format | `stella:canon:v<N>` where N is the version number |
+| Current version | `stella:canon:v1` (RFC 8785 JSON canonicalization) |
+
+**V1 Algorithm Specification:**
+
+| Property | Behavior |
+|----------|----------|
+| Standard | RFC 8785 (JSON Canonicalization Scheme) |
+| Key sorting | Ordinal string comparison |
+| Whitespace | None (compact JSON) |
+| Encoding | UTF-8 without BOM |
+| Numbers | IEEE 754, shortest representation |
+| Escaping | Minimal (only required characters) |
+
+**Version Detection:**
+
+```csharp
+// Detect if canonical JSON includes version marker
+public static bool IsVersioned(ReadOnlySpan<byte> canonicalJson)
+{
+    return canonicalJson.Length > 20 &&
+           canonicalJson.StartsWith("{\"_canonVersion\":"u8);
+}
+
+// Extract version from versioned canonical JSON
+public static string? ExtractVersion(ReadOnlySpan<byte> canonicalJson)
+{
+    // Parse and return the _canonVersion value, or null if not versioned
+}
+```
+
+**Migration Strategy:**
+
+| Phase | Behavior | Timeline |
+|-------|----------|----------|
+| Phase 1 (Current) | Generate v1 hashes; accept both legacy and v1 for verification | Now |
+| Phase 2 | Log deprecation warnings for legacy hashes | +6 months |
+| Phase 3 | Reject legacy hashes; require v1 | +12 months |
+
+See also: [Canonicalization Migration Guide](../../operations/canon-version-migration.md)
+
 ## DSSE Predicate Types

 ### 1. Evidence Statement (`evidence.stella/v1`)
@@ -194,6 +256,101 @@ This specification defines the implementation of a cryptographically verifiable
 ```
 **Signer**: Generator key

+### 7. Graph Root Statement (`graph-root.stella/v1`)
+
+The Graph Root attestation provides tamper-evident commitment to graph analysis results (dependency graphs, call graphs, reachability graphs) by computing a Merkle root over canonicalized node and edge identifiers.
+
+```json
+{
+  "_type": "https://in-toto.io/Statement/v1",
+  "subject": [
+    {
+      "name": "graph-root://<graphType>/<merkleRoot>",
+      "digest": {
+        "sha256": "<merkle-root-hex>"
+      }
+    }
+  ],
+  "predicateType": "https://stella-ops.org/predicates/graph-root/v1",
+  "predicate": {
+    "graphType": "DependencyGraph|CallGraph|ReachabilityGraph|...",
+    "merkleRoot": "sha256:<hex>",
+    "nodeCount": 1234,
+    "edgeCount": 5678,
+    "canonVersion": "stella:canon:v1",
+    "inputs": {
+      "sbomDigest": "sha256:<hex>",
+      "analyzerDigest": "sha256:<hex>",
+      "configDigest": "sha256:<hex>"
+    },
+    "createdAt": "2025-01-12T10:30:00Z"
+  }
+}
+```
+
+**Signer**: Graph Analyzer key
+
+#### Supported Graph Types
+
+| Graph Type | Use Case |
+|------------|----------|
+| `DependencyGraph` | Package/library dependency analysis |
+| `CallGraph` | Function-level call relationships |
+| `ReachabilityGraph` | Vulnerability reachability analysis |
+| `DataFlowGraph` | Data flow and taint tracking |
+| `ControlFlowGraph` | Code execution paths |
+| `InheritanceGraph` | OOP class hierarchies |
+| `ModuleGraph` | Module/namespace dependencies |
+| `BuildGraph` | Build system dependencies |
+| `ContainerLayerGraph` | Container layer relationships |
+
+#### Merkle Root Computation
+
+The Merkle root is computed deterministically:
+
+1. **Canonicalize Node IDs**: Sort all node identifiers lexicographically
+2. **Canonicalize Edge IDs**: Sort all edge identifiers (format: `{source}->{target}`)
+3. **Combine**: Concatenate sorted nodes + sorted edges
+4. **Binary Tree**: Build SHA-256 Merkle tree with odd-node duplication
+5. **Root**: Extract 32-byte root as `sha256:<hex>`
+
+```
+Merkle Tree Structure:
+        [root]
+       /      \
+    [h01]    [h23]
+    /   \    /   \
+  [n0] [n1] [n2] [n3]
+```
+
+#### Integration with Proof Spine
+
+Graph root attestations can be referenced in proof spines:
+
+```json
+{
+  "predicateType": "proofspine.stella/v1",
+  "predicate": {
+    "sbomEntryId": "<SBOMEntryID>",
+    "evidenceIds": ["<ID1>", "<ID2>"],
+    "reasoningId": "<ID>",
+    "vexVerdictId": "<ID>",
+    "graphRootIds": ["<GraphRootID1>"],
+    "policyVersion": "v2.3.1",
+    "proofBundleId": "<ProofBundleID>"
+  }
+}
+```
+
+#### Verification Steps
+
+1. Parse DSSE envelope and verify signature against allowed keys
+2. Extract predicate and Merkle root
+3. Re-canonicalize provided node/edge IDs using `stella:canon:v1`
+4. Recompute Merkle root from canonicalized inputs
+5. Compare computed root to claimed root
+6. If Rekor entry exists, verify transparency log inclusion
+
 ## Database Schema

 ### Tables
@@ -205,6 +362,7 @@ This specification defines the implementation of a cryptographically verifiable
 | `proofchain.spines` | Proof spine aggregations linking evidence to verdicts |
 | `proofchain.trust_anchors` | Trust anchor configurations for verification |
 | `proofchain.rekor_entries` | Rekor transparency log entries |
+| `proofchain.graph_roots` | Graph root attestations with Merkle roots |
 | `proofchain.key_history` | Key lifecycle history for rotation |
 | `proofchain.key_audit_log` | Audit log for key operations |

@@ -282,6 +440,7 @@ The 13-step verification algorithm:
 - [Database Schema Sprint](../../implplan/SPRINT_0501_0006_0001_proof_chain_database_schema.md)
 - [CLI Integration Sprint](../../implplan/SPRINT_0501_0007_0001_proof_chain_cli_integration.md)
 - [Key Rotation Sprint](../../implplan/SPRINT_0501_0008_0001_proof_chain_key_rotation.md)
+- [Graph Root Attestation](./graph-root-attestation.md)
 - [Attestor Architecture](./architecture.md)
 - [Signer Architecture](../signer/architecture.md)
 - [Database Specification](../../db/SPECIFICATION.md)