vm-core/docs/VAULTMESH-PROOFBUNDLE-PLAYBOOK.md

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

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

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

pip install blake3

This provides the BLAKE3 hash function used by VaultMesh receipts.

Step 3 – Run the verifier

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