170 lines
5.0 KiB
Markdown
170 lines
5.0 KiB
Markdown
# 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_
|