Initialize repository snapshot
This commit is contained in:
Vault Sovereign
201
docs/VAULTMESH-STANDARDS-INDEX.md
Normal file
201
docs/VAULTMESH-STANDARDS-INDEX.md
Normal file
@@ -0,0 +1,201 @@
|
||||
# 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_
|
||||
Reference in New Issue
Block a user