# 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_