202 lines
6.3 KiB
Markdown
202 lines
6.3 KiB
Markdown
# VaultMesh Standards Index
|
||
|
||
> Canonical index of normative and supporting artifacts for the VaultMesh
|
||
> ProofBundle and ledger evidence model.
|
||
|
||
This document provides a single entry point for regulators, auditors, and
|
||
integration partners who need to understand which documents and tools are
|
||
**normative** (MUST be followed) and which are **supporting** (helpful
|
||
for implementation and interpretation).
|
||
|
||
---
|
||
|
||
## 1. Scope
|
||
|
||
This index currently covers the **ProofBundle** family of artifacts:
|
||
|
||
- The way VaultMesh packages evidence for a single document access
|
||
- The cryptographic verification model for that evidence
|
||
- The offline tooling used by regulators to validate bundles
|
||
|
||
Future VaultMesh standards (e.g. Treasury, Mesh Federation) SHOULD be
|
||
added to this index as they are formalized.
|
||
|
||
---
|
||
|
||
## 2. Normative Artifacts
|
||
|
||
These artifacts define the behavior and structure that MUST be followed
|
||
for ProofBundle implementations and verifiers.
|
||
|
||
### 2.1 ProofBundle Specification
|
||
|
||
- **Title:** VaultMesh ProofBundle Specification
|
||
- **File:** `docs/VAULTMESH-PROOFBUNDLE-SPEC.md`
|
||
- **Version:** `1.1.0`
|
||
- **Status:** Normative
|
||
|
||
Defines:
|
||
|
||
- JSON schema for ProofBundle exports (`bundle_id`, `schema_version`,
|
||
`document`, `actor`, `portal`, `chain`, `guardian_anchor`,
|
||
`proofchain`, `meta`)
|
||
- Use of BLAKE3 for `root_hash` and `previous_hash`
|
||
- Hash-chain semantics and verification rules
|
||
- Threat model & non-goals
|
||
- AI Act Annex IX compliance crosswalk
|
||
- Versioning and extensibility rules
|
||
|
||
**Implementers MUST** treat this SPEC as the source of truth for what a
|
||
valid ProofBundle is and how it is verified.
|
||
|
||
### 2.2 ProofBundle Offline Verifier
|
||
|
||
- **Title:** VaultMesh ProofBundle Verifier
|
||
- **File:** `burocrat/app/tools/vm_verify_proofbundle.py`
|
||
- **Status:** Normative reference implementation
|
||
|
||
Implements:
|
||
|
||
- Canonical JSON encoding (`sort_keys=True`, compact separators)
|
||
- BLAKE3 verification of each receipt's `root_hash`
|
||
- Hash-chain verification via `previous_hash`
|
||
- Consistency checks against `chain.ok`, `chain.length`,
|
||
`chain.start`, `chain.end`
|
||
- Exit codes:
|
||
- `0` – valid bundle
|
||
- `1` – structural / hash-chain failure
|
||
- `2` – I/O or parse error
|
||
|
||
**Regulators MAY** use this tool directly or as a reference when
|
||
building their own independent verifier.
|
||
|
||
---
|
||
|
||
## 3. Supporting Artifacts
|
||
|
||
These artifacts are not strictly required for correctness, but they
|
||
explain how to use the normative pieces in practice.
|
||
|
||
### 3.1 ProofBundle Playbook
|
||
|
||
- **Title:** How to Verify a VaultMesh ProofBundle
|
||
- **File:** `docs/VAULTMESH-PROOFBUNDLE-PLAYBOOK.md`
|
||
- **Version:** `1.0`
|
||
- **Status:** Informative
|
||
|
||
Audience: compliance officers, lawyers, auditors, procurement teams.
|
||
|
||
Provides:
|
||
|
||
- Plain-language explanation of what a ProofBundle proves
|
||
- Prerequisites (Python, `blake3` package)
|
||
- 3-step verification walkthrough
|
||
- Example output (valid vs tampered bundle)
|
||
- Operational guidance (no VaultMesh access required)
|
||
|
||
### 3.2 HTML ProofBundle Viewer
|
||
|
||
- **Title:** ProofBundle HTML Viewer
|
||
- **File:** `burocrat/app/src/views/proofbundle.ejs`
|
||
- **Status:** Informative
|
||
|
||
Provides:
|
||
|
||
- Human-readable rendering of a ProofBundle
|
||
- Chain visualization and anchor details
|
||
- Print-to-PDF option for dossier filing
|
||
- Footer note pointing to the offline verifier
|
||
|
||
This viewer **MUST NOT** be considered a substitute for cryptographic
|
||
verification; it is a convenience layer on top of the normative JSON +
|
||
verifier.
|
||
|
||
### 3.3 ProofBundle Conformance Test Pack
|
||
|
||
- **Title:** ProofBundle Conformance Test Pack
|
||
- **Path:** `testvectors/proofbundle/`
|
||
- **Version:** `1.0`
|
||
- **Status:** Informative
|
||
|
||
Provides:
|
||
|
||
- `proofbundle-valid.json` – Known-good bundle (exit 0)
|
||
- `proofbundle-tampered-body.json` – Modified body, hash mismatch (exit 1)
|
||
- `proofbundle-tampered-root.json` – Wrong root_hash (exit 1)
|
||
- `proofbundle-broken-chain.json` – Broken previous_hash linkage (exit 1)
|
||
- `README.md` – Standalone usage instructions
|
||
|
||
Implementers SHOULD verify their verifier passes all test vectors before
|
||
claiming conformance.
|
||
|
||
---
|
||
|
||
## 4. Current Version Matrix
|
||
|
||
| Component | File | Version |
|
||
|----------------------|------------------------------------------------|----------|
|
||
| ProofBundle SPEC | `docs/VAULTMESH-PROOFBUNDLE-SPEC.md` | `1.1.0` |
|
||
| ProofBundle Playbook | `docs/VAULTMESH-PROOFBUNDLE-PLAYBOOK.md` | `1.0` |
|
||
| Offline Verifier | `burocrat/app/tools/vm_verify_proofbundle.py` | `1.1.0*` |
|
||
| Conformance Test Pack | `testvectors/proofbundle/` | `1.0` |
|
||
| HTML Viewer | `burocrat/app/src/views/proofbundle.ejs` | n/a |
|
||
|
||
\* The verifier tracks the SPEC's `schema_version`. For
|
||
`schema_version = "1.1.0"` bundles, this script is considered the
|
||
reference.
|
||
|
||
---
|
||
|
||
## 5. Citing ProofBundle
|
||
|
||
ProofBundle can be cited in assessments, audit reports, and compliance
|
||
documentation using the following reference:
|
||
|
||
> This assessment relies on VaultMesh ProofBundle, specified in
|
||
> **"VAULTMESH-PROOFBUNDLE-SPEC v1.1.0"**, with verification performed
|
||
> using the reference tool `vm_verify_proofbundle.py v1.1.0` and validated
|
||
> against the **VaultMesh ProofBundle Conformance Test Pack v1.0**.
|
||
|
||
The git tag `proofbundle-v1.1.0` in the VaultMesh repository marks the
|
||
reference implementation state for this version.
|
||
|
||
---
|
||
|
||
## 6. Implementation Notes
|
||
|
||
- **Producers of ProofBundles:**
|
||
- MUST include `schema_version` in every bundle and follow the
|
||
rules in the SPEC.
|
||
- SHOULD keep this index updated when bumping versions or adding
|
||
new normative documents.
|
||
|
||
- **Verifiers:**
|
||
- MUST reject unknown major versions (e.g. `2.x.x`) by default.
|
||
- MAY accept minor extensions (`1.2.x`) if all required fields
|
||
validate according to the `1.1.0` SPEC.
|
||
|
||
---
|
||
|
||
## 7. Roadmap for Future Standards
|
||
|
||
Future VaultMesh standards that SHOULD be added here:
|
||
|
||
| Standard | Scroll | Status |
|
||
|----------|--------|--------|
|
||
| Treasury Receipt SPEC | Treasury | Planned |
|
||
| Mesh Federation SPEC | Mesh | Planned |
|
||
| Identity & Capability SPEC | Identity | Planned |
|
||
| Guardian Anchoring & External ProofChain SPEC | Guardian | Planned |
|
||
|
||
Each new standard SHOULD define:
|
||
|
||
1. A normative SPEC document under `docs/`
|
||
2. A reference implementation (Rust and/or Python)
|
||
3. Optional Playbook for non-technical stakeholders
|
||
4. Clear versioning and deprecation rules
|
||
|
||
---
|
||
|
||
_VaultMesh Standards Index_
|
||
_Sovereign Infrastructure for the Digital Age_
|