Initialize repository snapshot

docs/VAULTMESH-PROOFBUNDLE-PLAYBOOK.md

@@ -0,0 +1,169 @@
+# How to Verify a VaultMesh ProofBundle
+_Version 1.0 – Regulator Playbook_
+
+This Playbook explains how to verify a VaultMesh **ProofBundle** using only a JSON file and an open-source Python script. No network access to VaultMesh is required.
+
+---
+
+## 1. What a ProofBundle Proves
+
+A VaultMesh ProofBundle is an offline evidence package that demonstrates:
+
+1. **Authenticity of receipts**
+   Each event (e.g. document download) is represented as a receipt with a BLAKE3 hash.
+
+2. **Continuity of the hash-chain**
+   Each receipt's `previous_hash` links to the `root_hash` of the prior receipt, forming a tamper-evident chain.
+
+3. **Attribution to cryptographic identities and sealed state**
+   Actor and system identities are expressed as DIDs (e.g. `did:vm:human:…`, `did:vm:portal:…`), and the chain is linked to a sealed ledger state via Guardian anchor information.
+
+---
+
+## 2. What You Need
+
+**Environment**
+
+- Python **3.10+**
+- Internet access **not** required
+
+**Python dependency**
+
+```bash
+pip install blake3
+```
+
+**Files you receive**
+
+From the audited party you should receive:
+
+- `proofbundle-*.json`
+  A JSON file containing the ProofBundle (e.g. `proofbundle-dl-20251206T174556.json`)
+
+- `vm_verify_proofbundle.py`
+  The open-source verifier script (or a link to its public source)
+
+---
+
+## 3. Verification in 3 Steps
+
+### Step 1 – Place files in a working directory
+
+```bash
+mkdir vaultmesh-proof
+cd vaultmesh-proof
+
+# Copy the bundle and verifier here, for example:
+# proofbundle-dl-20251206T174556.json
+# vm_verify_proofbundle.py
+```
+
+### Step 2 – Install the BLAKE3 dependency
+
+```bash
+pip install blake3
+```
+
+This provides the BLAKE3 hash function used by VaultMesh receipts.
+
+### Step 3 – Run the verifier
+
+```bash
+python3 vm_verify_proofbundle.py proofbundle-dl-20251206T174556.json
+```
+
+The script will:
+
+1. Load the bundle JSON.
+2. Recompute BLAKE3 over each receipt.
+3. Compare computed hashes against `root_hash`.
+4. Walk the `previous_hash` chain to ensure the chain is contiguous.
+5. Compare its own verification result with the bundle's declared `chain.ok` flag.
+
+---
+
+## 4. Example Outputs
+
+### 4.1 Valid bundle
+
+Typical output for a valid bundle:
+
+```
+ProofBundle: pb-20251206174603-dl-20251206T174556-b5bb3d
+Document : 001 AI Governance Policy
+File     : VM-AI-GOV-001_AI_Governance_Policy.docx
+Actor    : did:vm:human:karol (Karol S)
+Portal   : did:vm:portal:shield (shield)
+
+Receipts : 7
+Hash check     : OK
+Chain linkage  : OK
+Bundle chain.ok: True (matches computed: True)
+
+Result: OK – chain of 7 receipts is contiguous and valid.
+```
+
+**Interpretation:**
+
+- All receipt hashes are correct.
+- The hash-chain is unbroken from the first event to the document download.
+- The bundle's own `chain.ok` value is honest.
+- The ProofBundle can be relied on as an integrity-preserving trace of events.
+
+---
+
+### 4.2 Tampered bundle
+
+If any receipt is modified (for example, a timestamp, actor DID, or type), the verifier will detect it:
+
+```
+ProofBundle: pb-20251206174603-dl-20251206T174556-b5bb3d
+Document : 001 AI Governance Policy
+File     : VM-AI-GOV-001_AI_Governance_Policy.docx
+Actor    : did:vm:human:karol (Karol S)
+Portal   : did:vm:portal:shield (shield)
+
+Receipts : 7
+Hash check     : FAIL
+Chain linkage  : OK
+Bundle chain.ok: True (matches computed: False)
+
+Result: FAIL – ProofBundle verification failed.
+
+Details:
+  - receipt[2] root_hash mismatch: expected blake3:4e7cf7...4209f, computed blake3:9a2b1c...77e3d
+  - bundle chain.ok (True) does not match computed result (False)
+```
+
+The verifier does not attempt to repair or reinterpret the chain. Any mismatch means the bundle has been altered or is inconsistent with the original VaultMesh ledger.
+
+---
+
+## 5. Interpreting Outcomes
+
+| Exit Code | Meaning |
+|-----------|---------|
+| **0** | **Valid** – The ProofBundle's chain is intact, hashes match, and the declared `chain.ok` flag is truthful. |
+| **1** | **Invalid** – At least one of: a receipt's `root_hash` does not match its contents, the `previous_hash` chain is broken, or the bundle's `chain.ok` flag disagrees with the verifier's result. |
+| **2** | **Error** – The verifier could not process the bundle (e.g. malformed JSON, missing fields, unsupported schema version). Treat as verification failed. |
+
+---
+
+## 6. Security Notes
+
+- **Verification is fully offline**: no VaultMesh node, API, or network connectivity is required.
+- The ProofBundle contains **cryptographic DIDs** for actors and systems; these can be cross-checked against identity documentation provided separately (e.g. key attestations).
+- The **Guardian anchor** and scroll roots in the bundle allow a deeper, optional verification against a running VaultMesh node, but this is not required for basic bundle integrity checks.
+
+---
+
+## Short Version
+
+If the verifier script returns **`Result: OK`** with **exit code 0**, you have a tamper-evident, DID-attributed trace from initial checks to the specific document download event.
+
+**No VaultMesh access required — verification is fully offline.**
+
+---
+
+_VaultMesh ProofBundle Verification Playbook v1.0_
+_Sovereign Infrastructure for the Digital Age_