docs consolidation

docs/airgap/proof-chain-verification.md

@@ -14,7 +14,8 @@ Proof chains in StellaOps consist of cryptographically-linked attestations:
 1. **Evidence statements** - Raw vulnerability findings
 2. **Reasoning statements** - Policy evaluation traces
 3. **VEX verdict statements** - Final vulnerability status determinations
-4. **Proof spine** - Merkle tree aggregating all components
+4. **Graph root statements** - Merkle root commitments to graph analysis results
+5. **Proof spine** - Merkle tree aggregating all components
 
 In online mode, proof chains include Rekor inclusion proofs for transparency. In air-gap mode, verification proceeds without Rekor but maintains cryptographic integrity.
 
@@ -244,6 +245,174 @@ stellaops proof verify-batch \
 
 ---
 
+## Graph Root Attestation Verification (Offline)
+
+Graph root attestations provide tamper-evident commitment to graph analysis results. In air-gap mode, these attestations can be verified without network access.
+
+### Verify Graph Root Attestation
+
+```bash
+# Verify a single graph root attestation
+stellaops graph-root verify --offline \
+  --envelope graph-root.dsse \
+  --anchor-file trust-anchors.json
+
+# Expected output:
+# Graph Root Verification
+# ═══════════════════════
+# ✓ DSSE signature verified
+# ✓ Predicate type: graph-root.stella/v1
+# ✓ Graph type: ReachabilityGraph
+# ✓ Canon version: stella:canon:v1
+# ⊘ Rekor verification skipped (offline mode)
+#
+# Overall: VERIFIED (offline)
+```
+
+### Verify with Node/Edge Reconstruction
+
+When you have the original graph data, you can recompute and verify the Merkle root:
+
+```bash
+# Verify with reconstruction
+stellaops graph-root verify --offline \
+  --envelope graph-root.dsse \
+  --nodes nodes.json \
+  --edges edges.json \
+  --anchor-file trust-anchors.json
+
+# Expected output:
+# Graph Root Verification (with reconstruction)
+# ═════════════════════════════════════════════
+# ✓ DSSE signature verified
+# ✓ Nodes canonicalized: 1234 entries
+# ✓ Edges canonicalized: 5678 entries
+# ✓ Merkle root recomputed: sha256:abc123...
+# ✓ Merkle root matches claimed: sha256:abc123...
+#
+# Overall: VERIFIED (reconstructed)
+```
+
+### Graph Data File Formats
+
+**nodes.json** - Array of node identifiers:
+```json
+{
+  "canonVersion": "stella:canon:v1",
+  "nodes": [
+    "pkg:npm/lodash@4.17.21",
+    "pkg:npm/express@4.18.2",
+    "pkg:npm/body-parser@1.20.0"
+  ]
+}
+```
+
+**edges.json** - Array of edge identifiers:
+```json
+{
+  "canonVersion": "stella:canon:v1",
+  "edges": [
+    "pkg:npm/express@4.18.2->pkg:npm/body-parser@1.20.0",
+    "pkg:npm/express@4.18.2->pkg:npm/lodash@4.17.21"
+  ]
+}
+```
+
+### Verification Steps (Detailed)
+
+The offline graph root verification algorithm:
+
+1. **Parse DSSE envelope** - Extract payload and signatures
+2. **Decode in-toto statement** - Parse subject and predicate
+3. **Verify signature** - Check DSSE signature against trust anchor allowed keys
+4. **Validate predicate type** - Confirm `graph-root.stella/v1`
+5. **Extract Merkle root** - Get claimed root from predicate
+6. **If reconstruction requested**:
+   - Load nodes.json and edges.json
+   - Verify canon version matches predicate
+   - Sort nodes lexicographically
+   - Sort edges lexicographically
+   - Concatenate sorted lists
+   - Build SHA-256 Merkle tree
+   - Compare computed root to claimed root
+7. **Emit verification result**
+
+### Programmatic Verification (.NET)
+
+```csharp
+using StellaOps.Attestor.GraphRoot;
+
+// Load trust anchors
+var anchors = await TrustAnchors.LoadFromFileAsync("trust-anchors.json");
+
+// Create verifier
+var verifier = new GraphRootAttestor(signer, canonicalJsonSerializer);
+
+// Load envelope
+var envelope = await DsseEnvelope.LoadAsync("graph-root.dsse");
+
+// Verify without reconstruction
+var result = await verifier.VerifyAsync(
+    envelope,
+    trustAnchors: anchors,
+    verifyRekor: false);
+
+// Verify with reconstruction
+var nodeIds = new[] { "pkg:npm/lodash@4.17.21", "pkg:npm/express@4.18.2" };
+var edgeIds = new[] { "pkg:npm/express@4.18.2->pkg:npm/lodash@4.17.21" };
+
+var fullResult = await verifier.VerifyAsync(
+    envelope,
+    nodeIds: nodeIds,
+    edgeIds: edgeIds,
+    trustAnchors: anchors,
+    verifyRekor: false);
+
+Console.WriteLine($"Verified: {fullResult.IsValid}");
+Console.WriteLine($"Merkle root: {fullResult.MerkleRoot}");
+```
+
+### Integration with Proof Spine
+
+Graph roots can be included in proof spines for comprehensive verification:
+
+```bash
+# Export proof bundle with graph roots
+stellaops proof export \
+  --entry sha256:abc123:pkg:npm/lodash@4.17.21 \
+  --include-graph-roots \
+  --output proof-bundle.zip
+
+# Bundle now includes:
+# proof-bundle.zip
+# ├── proof-spine.json
+# ├── evidence/
+# ├── reasoning.json
+# ├── vex-verdict.json
+# ├── graph-roots/           # Graph root attestations
+# │   ├── reachability.dsse
+# │   └── dependency.dsse
+# ├── envelopes/
+# └── VERIFY.md
+
+# Verify with graph roots
+stellaops proof verify --offline \
+  --bundle-file proof-bundle.zip \
+  --verify-graph-roots \
+  --anchor-file trust-anchors.json
+```
+
+### Determinism Requirements
+
+For offline verification to succeed:
+
+1. **Same canonicalization** - Use `stella:canon:v1` consistently
+2. **Same ordering** - Lexicographic sort for nodes and edges
+3. **Same encoding** - UTF-8 for all string operations
+4. **Same hash algorithm** - SHA-256 for Merkle tree
+
+---
+
 ## Key Rotation in Air-Gap Mode
 
 When keys are rotated, trust anchor updates must be distributed: