Initialize repository snapshot

2025-12-27 00:10:32 +00:00
commit 110d644e10
281 changed files with 40331 additions and 0 deletions
--- a/docs/VAULTMESH-FEDERATION-PROTOCOL.md
+++ b/docs/VAULTMESH-FEDERATION-PROTOCOL.md
@@ -0,0 +1,560 @@
+# VAULTMESH-FEDERATION-PROTOCOL.md
+**Cross-Mesh Trust and Receipt Sharing**
+
+> *Sovereign meshes that verify each other become civilizations that remember together.*
+
+The Federation Protocol defines how independent VaultMesh deployments establish trust, share receipts, and create a network of mutually-witnessing civilization ledgers.
+
+---
+
+## 1. Federation Philosophy
+
+### 1.1 Sovereignty First
+
+Each VaultMesh instance is **sovereign** — it controls its own:
+- Identity roots
+- Anchor backends
+- Governance rules
+- Data retention
+- Access policies
+
+Federation doesn't compromise sovereignty. It creates **voluntary witness relationships** where meshes choose to verify and attest to each other's receipts.
+
+### 1.2 The Witness Network
+
+```
+┌─────────────────┐         ┌─────────────────┐
+│  VaultMesh-A    │◄───────►│  VaultMesh-B    │
+│  (Dublin)       │ witness │  (Berlin)       │
+└────────┬────────┘         └────────┬────────┘
+         │                           │
+         │         witness           │
+         │    ┌─────────────────┐    │
+         └───►│  VaultMesh-C    │◄───┘
+              │  (Singapore)    │
+              └─────────────────┘
+```
+
+When Mesh-A anchors a root, Mesh-B and Mesh-C can:
+1. Verify the anchor independently
+2. Record their verification as a receipt
+3. Include Mesh-A's root in their own anchor cycles
+
+This creates **redundant civilizational memory** — even if one mesh is compromised or lost, the others retain witnessed evidence.
+
+### 1.3 Trust Levels
+
+| Level | Name | Description | Use Case |
+|-------|------|-------------|----------|
+| 0 | `isolated` | No federation | Air-gapped deployments |
+| 1 | `observe` | Read-only witness | Public audit |
+| 2 | `verify` | Mutual verification | Partner organizations |
+| 3 | `attest` | Cross-attestation | Compliance networks |
+| 4 | `integrate` | Shared scrolls | Tight federation |
+
+---
+
+## 2. Federation Scroll
+
+| Property | Value |
+|----------|-------|
+| **Scroll Name** | `Federation` |
+| **JSONL Path** | `receipts/federation/federation_events.jsonl` |
+| **Root File** | `ROOT.federation.txt` |
+| **Receipt Types** | `fed_trust_proposal`, `fed_trust_established`, `fed_trust_revoked`, `fed_witness_event`, `fed_cross_anchor`, `fed_schema_sync` |
+
+---
+
+## 3. Trust Establishment Protocol
+
+### 3.1 Phase 1: Discovery
+
+Meshes discover each other via:
+- Manual configuration
+- DNS-based discovery (`_vaultmesh._tcp.example.com`)
+- DHT announcement (for public meshes)
+
+**Discovery Record**:
+```json
+{
+  "mesh_id": "did:vm:mesh:vaultmesh-berlin",
+  "display_name": "VaultMesh Berlin Node",
+  "endpoints": {
+    "federation": "https://federation.vaultmesh-berlin.io",
+    "verification": "https://verify.vaultmesh-berlin.io"
+  },
+  "public_key": "ed25519:z6Mk...",
+  "scrolls_available": ["Drills", "Compliance", "Treasury"],
+  "trust_policy": {
+    "accepts_proposals": true,
+    "min_trust_level": 1,
+    "requires_mutual": true
+  },
+  "attestations": [
+    {
+      "attester": "did:vm:mesh:vaultmesh-dublin",
+      "attested_at": "2025-06-01T00:00:00Z",
+      "attestation_type": "identity_verified"
+    }
+  ]
+}
+```
+
+### 3.2 Phase 2: Proposal
+
+Mesh-A proposes federation to Mesh-B:
+
+**Trust Proposal**:
+```json
+{
+  "proposal_id": "fed-proposal-2025-12-06-001",
+  "proposer": "did:vm:mesh:vaultmesh-dublin",
+  "target": "did:vm:mesh:vaultmesh-berlin",
+  "proposed_at": "2025-12-06T10:00:00Z",
+  "expires_at": "2025-12-13T10:00:00Z",
+  "proposed_trust_level": 2,
+  "proposed_terms": {
+    "scrolls_to_share": ["Compliance"],
+    "verification_frequency": "hourly",
+    "retention_period_days": 365,
+    "data_jurisdiction": "EU",
+    "audit_rights": true
+  },
+  "proposer_attestations": {
+    "identity_proof": "...",
+    "capability_proof": "...",
+    "compliance_credentials": ["ISO27001", "SOC2"]
+  },
+  "signature": {
+    "algorithm": "Ed25519",
+    "value": "z58D..."
+  }
+}
+```
+
+### 3.3 Phase 3: Negotiation
+
+Target mesh reviews and may counter-propose:
+
+**Counter-Proposal**:
+```json
+{
+  "proposal_id": "fed-proposal-2025-12-06-001",
+  "response_type": "counter",
+  "responder": "did:vm:mesh:vaultmesh-berlin",
+  "responded_at": "2025-12-06T14:00:00Z",
+  "counter_terms": {
+    "scrolls_to_share": ["Compliance", "Drills"],
+    "verification_frequency": "daily",
+    "retention_period_days": 180,
+    "additional_requirement": "quarterly_audit_call"
+  },
+  "signature": "z47C..."
+}
+```
+
+### 3.4 Phase 4: Establishment
+
+Both parties sign the final agreement:
+
+**Federation Agreement**:
+```json
+{
+  "agreement_id": "fed-agreement-2025-12-06-001",
+  "parties": [
+    "did:vm:mesh:vaultmesh-dublin",
+    "did:vm:mesh:vaultmesh-berlin"
+  ],
+  "established_at": "2025-12-06T16:00:00Z",
+  "trust_level": 2,
+  "terms": {
+    "scrolls_shared": ["Compliance", "Drills"],
+    "verification_frequency": "daily",
+    "retention_period_days": 180,
+    "data_jurisdiction": "EU",
+    "audit_rights": true,
+    "dispute_resolution": "arbitration_zurich"
+  },
+  "key_exchange": {
+    "dublin_federation_key": "ed25519:z6MkDublin...",
+    "berlin_federation_key": "ed25519:z6MkBerlin..."
+  },
+  "signatures": {
+    "did:vm:mesh:vaultmesh-dublin": {
+      "signed_at": "2025-12-06T15:30:00Z",
+      "signature": "z58D..."
+    },
+    "did:vm:mesh:vaultmesh-berlin": {
+      "signed_at": "2025-12-06T16:00:00Z",
+      "signature": "z47C..."
+    }
+  },
+  "agreement_hash": "blake3:abc123..."
+}
+```
+
+### 3.5 Phase 5: Activation
+
+Both meshes:
+1. Store the agreement in their Federation scroll
+2. Exchange current Merkle roots
+3. Begin scheduled verification cycles
+4. Emit `fed_trust_established` receipt
+
+---
+
+## 4. Witness Protocol
+
+### 4.1 Verification Cycle
+
+```
+┌─────────────┐                    ┌─────────────┐
+│  Mesh-A     │                    │  Mesh-B     │
+│  (Dublin)   │                    │  (Berlin)   │
+└──────┬──────┘                    └──────┬──────┘
+       │                                  │
+       │  1. Anchor cycle completes       │
+       │     ROOT.compliance.txt updated  │
+       │                                  │
+       │  2. POST /federation/notify      │
+       │────────────────────────────────►│
+       │  {                               │
+       │    scroll: "Compliance",         │
+       │    root: "blake3:aaa...",        │
+       │    anchor_proof: {...}           │
+       │  }                               │
+       │                                  │
+       │                                  │ 3. Verify anchor proof
+       │                                  │    against known backends
+       │                                  │
+       │                                  │ 4. Optionally fetch
+       │                                  │    receipt samples
+       │                                  │
+       │  5. POST /federation/witness     │
+       │◄────────────────────────────────│
+       │  {                               │
+       │    witnessed_root: "blake3:aaa",│
+       │    witness_result: "verified",   │
+       │    witness_signature: "z47C..."  │
+       │  }                               │
+       │                                  │
+       │  6. Store witness receipt        │
+       │                                  │
+       └──────────────────────────────────┘
+```
+
+### 4.2 Witness Receipt
+
+```json
+{
+  "type": "fed_witness_event",
+  "witness_id": "witness-2025-12-06-001",
+  "witnessed_mesh": "did:vm:mesh:vaultmesh-dublin",
+  "witnessing_mesh": "did:vm:mesh:vaultmesh-berlin",
+  "timestamp": "2025-12-06T12:05:00Z",
+  "scroll": "Compliance",
+  "witnessed_root": "blake3:aaa111...",
+  "witnessed_anchor": {
+    "backend": "ethereum",
+    "tx_hash": "0x123...",
+    "block_number": 12345678
+  },
+  "verification_method": "anchor_proof_validation",
+  "verification_result": "verified",
+  "samples_checked": 5,
+  "discrepancies": [],
+  "witness_signature": "z47C...",
+  "tags": ["federation", "witness", "compliance", "verified"],
+  "root_hash": "blake3:bbb222..."
+}
+```
+
+### 4.3 Cross-Anchor
+
+At trust level 3+, meshes can include each other's roots in their anchor cycles:
+
+**Cross-Anchor Receipt**:
+```json
+{
+  "type": "fed_cross_anchor",
+  "cross_anchor_id": "cross-anchor-2025-12-06-001",
+  "anchoring_mesh": "did:vm:mesh:vaultmesh-berlin",
+  "anchored_mesh": "did:vm:mesh:vaultmesh-dublin",
+  "timestamp": "2025-12-06T12:10:00Z",
+  "dublin_roots_included": {
+    "Compliance": "blake3:aaa111...",
+    "Drills": "blake3:bbb222..."
+  },
+  "combined_root": "blake3:ccc333...",
+  "anchor_proof": {
+    "backend": "bitcoin",
+    "tx_hash": "abc123...",
+    "merkle_path": [...]
+  },
+  "tags": ["federation", "cross-anchor", "bitcoin"],
+  "root_hash": "blake3:ddd444..."
+}
+```
+
+This means Dublin's receipts are now anchored on **both** Dublin's chosen backend **and** Berlin's Bitcoin anchor — double civilizational durability.
+
+---
+
+## 5. Federation API
+
+### 5.1 Endpoints
+
+```yaml
+# Federation API Specification
+openapi: 3.0.0
+info:
+  title: VaultMesh Federation API
+  version: 1.0.0
+
+paths:
+  /federation/discovery:
+    get:
+      summary: Get mesh discovery record
+      responses:
+        200:
+          description: Discovery record
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DiscoveryRecord'
+
+  /federation/proposals:
+    post:
+      summary: Submit trust proposal
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TrustProposal'
+      responses:
+        202:
+          description: Proposal received
+
+  /federation/proposals/{id}:
+    get:
+      summary: Get proposal status
+    put:
+      summary: Respond to proposal (accept/reject/counter)
+
+  /federation/agreements:
+    get:
+      summary: List active federation agreements
+
+  /federation/agreements/{id}:
+    get:
+      summary: Get agreement details
+    delete:
+      summary: Revoke federation (with notice period)
+
+  /federation/notify:
+    post:
+      summary: Notify of new anchor (push)
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AnchorNotification'
+
+  /federation/witness:
+    post:
+      summary: Submit witness attestation
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WitnessAttestation'
+
+  /federation/roots:
+    get:
+      summary: Get current Merkle roots for all scrolls
+      parameters:
+        - name: scrolls
+          in: query
+          schema:
+            type: array
+            items:
+              type: string
+
+  /federation/receipts/{scroll}:
+    get:
+      summary: Fetch receipt samples for verification
+      parameters:
+        - name: scroll
+          in: path
+          required: true
+        - name: from
+          in: query
+          schema:
+            type: string
+            format: date-time
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 100
+
+  /federation/verify:
+    post:
+      summary: Request verification of specific receipt
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                receipt_hash:
+                  type: string
+                scroll:
+                  type: string
+```
+
+### 5.2 Authentication
+
+Federation API uses mutual TLS + signed requests:
+
+```
+POST /federation/notify HTTP/1.1
+Host: federation.vaultmesh-berlin.io
+Content-Type: application/json
+X-Mesh-ID: did:vm:mesh:vaultmesh-dublin
+X-Timestamp: 2025-12-06T12:00:00Z
+X-Signature: z58D...
+
+{
+  "scroll": "Compliance",
+  "root": "blake3:aaa111...",
+  ...
+}
+```
+
+Signature covers: `${method}|${path}|${timestamp}|${body_hash}`
+
+---
+
+## 6. Conflict Resolution
+
+### 6.1 Discrepancy Types
+
+| Type | Description | Severity |
+|------|-------------|----------|
+| `root_mismatch` | Claimed root doesn't match computed | Critical |
+| `anchor_invalid` | Anchor proof fails verification | Critical |
+| `timestamp_drift` | Timestamps outside tolerance (>5min) | Warning |
+| `schema_incompatible` | Receipt schema version mismatch | Warning |
+| `sample_missing` | Requested receipt not found | Info |
+
+### 6.2 Discrepancy Protocol
+
+```json
+{
+  "type": "fed_discrepancy",
+  "discrepancy_id": "discrepancy-2025-12-06-001",
+  "reporting_mesh": "did:vm:mesh:vaultmesh-berlin",
+  "reported_mesh": "did:vm:mesh:vaultmesh-dublin",
+  "timestamp": "2025-12-06T12:15:00Z",
+  "discrepancy_type": "root_mismatch",
+  "severity": "critical",
+  "details": {
+    "scroll": "Compliance",
+    "claimed_root": "blake3:aaa111...",
+    "computed_root": "blake3:xxx999...",
+    "sample_receipts_checked": 50,
+    "first_divergence_at": "receipt-sequence-4721"
+  },
+  "evidence_hash": "blake3:evidence...",
+  "resolution_requested": true
+}
+```
+
+### 6.3 Resolution Workflow
+
+1. **Automatic**: Re-sync and recompute
+2. **Manual**: Human review of divergence
+3. **Arbitration**: Third-party mesh verification
+4. **Escalation**: Federation suspension pending resolution
+
+---
+
+## 7. Schema Synchronization
+
+Federated meshes must agree on receipt schemas:
+
+**Schema Sync Receipt**:
+```json
+{
+  "type": "fed_schema_sync",
+  "sync_id": "schema-sync-2025-12-06-001",
+  "meshes": ["did:vm:mesh:vaultmesh-dublin", "did:vm:mesh:vaultmesh-berlin"],
+  "timestamp": "2025-12-06T10:00:00Z",
+  "schemas_synced": {
+    "Compliance": {
+      "version": "1.2.0",
+      "hash": "blake3:schema1..."
+    },
+    "Drills": {
+      "version": "1.1.0",
+      "hash": "blake3:schema2..."
+    }
+  },
+  "backward_compatible": true,
+  "migration_required": false,
+  "tags": ["federation", "schema", "sync"],
+  "root_hash": "blake3:eee555..."
+}
+```
+
+---
+
+## 8. CLI Commands
+
+```bash
+# Discovery
+vm-federation discover --mesh vaultmesh-berlin.io
+vm-federation list-known
+
+# Proposals
+vm-federation propose \
+  --target did:vm:mesh:vaultmesh-berlin \
+  --trust-level 2 \
+  --scrolls Compliance,Drills \
+  --terms federation-terms.json
+
+vm-federation proposals list
+vm-federation proposals show fed-proposal-2025-12-06-001
+vm-federation proposals accept fed-proposal-2025-12-06-001
+vm-federation proposals reject fed-proposal-2025-12-06-001 --reason "incompatible_jurisdiction"
+vm-federation proposals counter fed-proposal-2025-12-06-001 --terms counter-terms.json
+
+# Agreements
+vm-federation agreements list
+vm-federation agreements show fed-agreement-2025-12-06-001
+vm-federation agreements revoke fed-agreement-2025-12-06-001 --notice-days 30
+
+# Verification
+vm-federation verify --mesh vaultmesh-berlin --scroll Compliance
+vm-federation witness-history --mesh vaultmesh-berlin --last 30d
+
+# Status
+vm-federation status
+vm-federation health --all-peers
+```
+
+---
+
+## 9. Design Gate Checklist
+
+| Question | Federation Answer |
+|----------|-------------------|
+| Clear entrypoint? | ✅ CLI (`vm-federation`), Federation API |
+| Contract produced? | ✅ `federation_agreement.json` |
+| State object? | ✅ Agreement + witness state |
+| Receipts emitted? | ✅ Six receipt types |
+| Append-only JSONL? | ✅ `receipts/federation/federation_events.jsonl` |
+| Merkle root? | ✅ `ROOT.federation.txt` |
+| Guardian anchor path? | ✅ Federation root included in ProofChain |
+| Query tool? | ✅ `vm-federation` CLI |