606 lines
17 KiB
Markdown
606 lines
17 KiB
Markdown
# VaultMesh Federation & Governance Protocols
|
|
|
|
## Federation Protocol
|
|
|
|
### Trust Establishment Flow
|
|
|
|
```
|
|
┌──────────────┐ ┌──────────────┐
|
|
│ MESH-A │ │ MESH-B │
|
|
│ (Dublin) │ │ (Berlin) │
|
|
└──────┬───────┘ └──────┬───────┘
|
|
│ │
|
|
│ 1. Discovery │
|
|
│ GET /federation/discovery │
|
|
│──────────────────────────────────►│
|
|
│ │
|
|
│ 2. Proposal │
|
|
│ POST /federation/proposals │
|
|
│──────────────────────────────────►│
|
|
│ │
|
|
│ 3. Counter/Accept │
|
|
│◄──────────────────────────────────│
|
|
│ │
|
|
│ 4. Mutual Signature │
|
|
│◄─────────────────────────────────►│
|
|
│ │
|
|
│ 5. Begin Witness Cycle │
|
|
│◄─────────────────────────────────►│
|
|
│ │
|
|
```
|
|
|
|
### Trust Levels
|
|
|
|
| Level | Name | Capabilities |
|
|
|-------|------|--------------|
|
|
| 0 | `isolated` | No federation |
|
|
| 1 | `observe` | Read-only witness, public receipts only |
|
|
| 2 | `verify` | Mutual verification, receipt sampling |
|
|
| 3 | `attest` | Cross-attestation, shared roots |
|
|
| 4 | `integrate` | Shared scrolls, joint governance |
|
|
|
|
### Discovery Record
|
|
|
|
```json
|
|
{
|
|
"mesh_id": "did:vm:mesh:vaultmesh-dublin",
|
|
"display_name": "VaultMesh Dublin",
|
|
"endpoints": {
|
|
"federation": "https://federation.vaultmesh-dublin.io",
|
|
"verification": "https://verify.vaultmesh-dublin.io"
|
|
},
|
|
"public_key": "ed25519:z6Mk...",
|
|
"scrolls_available": ["Compliance", "Drills"],
|
|
"trust_policy": {
|
|
"accepts_proposals": true,
|
|
"min_trust_level": 1,
|
|
"requires_mutual": true
|
|
},
|
|
"attestations": []
|
|
}
|
|
```
|
|
|
|
### 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": "...",
|
|
"compliance_credentials": ["ISO27001", "SOC2"]
|
|
},
|
|
"signature": "z58D..."
|
|
}
|
|
```
|
|
|
|
### 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..."
|
|
}
|
|
```
|
|
|
|
### Witness Protocol
|
|
|
|
```
|
|
Anchor Completes → Notify Peer → Peer Verifies → Witness Receipt
|
|
```
|
|
|
|
**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..."
|
|
}
|
|
```
|
|
|
|
### Cross-Anchor
|
|
|
|
At trust level 3+, meshes include each other's roots:
|
|
|
|
```json
|
|
{
|
|
"type": "fed_cross_anchor",
|
|
"anchoring_mesh": "did:vm:mesh:vaultmesh-berlin",
|
|
"anchored_mesh": "did:vm:mesh:vaultmesh-dublin",
|
|
"dublin_roots_included": {
|
|
"Compliance": "blake3:aaa111...",
|
|
"Drills": "blake3:bbb222..."
|
|
},
|
|
"combined_root": "blake3:ccc333...",
|
|
"anchor_proof": {
|
|
"backend": "bitcoin",
|
|
"tx_hash": "abc123..."
|
|
}
|
|
}
|
|
```
|
|
|
|
### Federation API Endpoints
|
|
|
|
| Endpoint | Method | Purpose |
|
|
|----------|--------|---------|
|
|
| `/federation/discovery` | GET | Get mesh discovery record |
|
|
| `/federation/proposals` | POST | Submit trust proposal |
|
|
| `/federation/proposals/{id}` | GET, PUT | View/respond to proposal |
|
|
| `/federation/agreements` | GET | List active agreements |
|
|
| `/federation/agreements/{id}` | GET, DELETE | View/revoke agreement |
|
|
| `/federation/notify` | POST | Notify of new anchor |
|
|
| `/federation/witness` | POST | Submit witness attestation |
|
|
| `/federation/roots` | GET | Get current Merkle roots |
|
|
| `/federation/receipts/{scroll}` | GET | Fetch receipt samples |
|
|
| `/federation/verify` | POST | Request receipt verification |
|
|
|
|
### 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
|
|
|
|
vm-federation proposals list
|
|
vm-federation proposals accept fed-proposal-001
|
|
vm-federation proposals reject fed-proposal-001 --reason "..."
|
|
|
|
# Agreements
|
|
vm-federation agreements list
|
|
vm-federation agreements revoke fed-agreement-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
|
|
```
|
|
|
|
---
|
|
|
|
## Constitutional Governance
|
|
|
|
### Hierarchy
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ IMMUTABLE AXIOMS │
|
|
│ (Cannot be changed, ever) │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ CONSTITUTIONAL ARTICLES │
|
|
│ (Amendable with supermajority + ratification) │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ STATUTORY RULES │
|
|
│ (Changeable with standard procedures) │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ EXECUTIVE ORDERS │
|
|
│ (Issued by authorized actors) │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Immutable Axioms
|
|
|
|
| ID | Name | Statement |
|
|
|----|------|-----------|
|
|
| AXIOM-001 | Append-Only Receipts | Receipts, once written, shall never be modified or deleted |
|
|
| AXIOM-002 | Cryptographic Integrity | All receipts include cryptographic hashes |
|
|
| AXIOM-003 | Universal Receipting | All significant changes produce receipts |
|
|
| AXIOM-004 | Constitutional Supremacy | No action may violate the Constitution |
|
|
| AXIOM-005 | Axiom Immutability | These axioms cannot be amended |
|
|
|
|
### Constitutional Articles
|
|
|
|
| Article | Name | Content |
|
|
|---------|------|---------|
|
|
| I | Governance Structure | Sovereign authority, engine authorities, agent delegation |
|
|
| II | Amendment Procedure | Proposal, deliberation, ratification |
|
|
| III | Engine Governance | Engine registry, boundaries, lifecycle |
|
|
| IV | Rights and Protections | Audit rights, data sovereignty, due process |
|
|
| V | Federation | Authority, limits, termination |
|
|
| VI | Emergency Powers | Declaration, powers, duration |
|
|
|
|
### Amendment Workflow
|
|
|
|
```
|
|
PROPOSAL → DELIBERATION (7+ days) → VOTING → RATIFICATION → ACTIVATION
|
|
↘ REJECTED → Archive
|
|
```
|
|
|
|
### Proposal Receipt
|
|
|
|
```json
|
|
{
|
|
"type": "gov_proposal",
|
|
"proposal_id": "PROP-2025-12-001",
|
|
"proposal_type": "amendment",
|
|
"title": "Add Data Retention Article",
|
|
"author": "did:vm:human:sovereign",
|
|
"submitted_at": "2025-12-06T10:00:00Z",
|
|
"deliberation_ends": "2025-12-13T10:00:00Z",
|
|
"content": {
|
|
"target": "ARTICLE-VII",
|
|
"action": "add",
|
|
"text": {
|
|
"id": "ARTICLE-VII",
|
|
"name": "Data Retention",
|
|
"sections": [...]
|
|
}
|
|
},
|
|
"rationale": "Compliance with EU regulations",
|
|
"status": "deliberation"
|
|
}
|
|
```
|
|
|
|
### Vote Receipt
|
|
|
|
```json
|
|
{
|
|
"type": "gov_vote",
|
|
"vote_id": "VOTE-2025-12-001-sovereign",
|
|
"proposal_id": "PROP-2025-12-001",
|
|
"voter": "did:vm:human:sovereign",
|
|
"voted_at": "2025-12-14T10:00:00Z",
|
|
"vote": "approve",
|
|
"weight": 1.0,
|
|
"comments": "Essential for compliance",
|
|
"signature": "z58D..."
|
|
}
|
|
```
|
|
|
|
### Ratification Receipt
|
|
|
|
```json
|
|
{
|
|
"type": "gov_ratification",
|
|
"ratification_id": "RAT-2025-12-001",
|
|
"proposal_id": "PROP-2025-12-001",
|
|
"ratified_at": "2025-12-14T12:00:00Z",
|
|
"ratified_by": "did:vm:human:sovereign",
|
|
"vote_summary": {
|
|
"approve": 1,
|
|
"reject": 0,
|
|
"abstain": 0
|
|
},
|
|
"quorum_met": true,
|
|
"constitution_version_before": "1.0.0",
|
|
"constitution_version_after": "1.1.0"
|
|
}
|
|
```
|
|
|
|
### Amendment Receipt
|
|
|
|
```json
|
|
{
|
|
"type": "gov_amendment",
|
|
"amendment_id": "AMEND-2025-12-001",
|
|
"proposal_id": "PROP-2025-12-001",
|
|
"effective_at": "2025-12-14T14:00:00Z",
|
|
"anchor_proof": {
|
|
"backend": "ethereum",
|
|
"tx_hash": "0x123..."
|
|
},
|
|
"constitution_hash_before": "blake3:const_v1.0...",
|
|
"constitution_hash_after": "blake3:const_v1.1..."
|
|
}
|
|
```
|
|
|
|
### Executive Orders
|
|
|
|
For operational decisions without full amendment:
|
|
|
|
```json
|
|
{
|
|
"type": "gov_executive_order",
|
|
"order_id": "EO-2025-12-001",
|
|
"title": "Temporary Rate Limit Increase",
|
|
"issued_by": "did:vm:human:sovereign",
|
|
"issued_at": "2025-12-06T15:00:00Z",
|
|
"authority": "ARTICLE-I.1",
|
|
"order_type": "parameter_change",
|
|
"content": {
|
|
"parameter": "guardian.anchor_rate_limit",
|
|
"old_value": "100/day",
|
|
"new_value": "500/day"
|
|
},
|
|
"duration": {
|
|
"type": "temporary",
|
|
"expires_at": "2026-01-01T00:00:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Emergency Declaration
|
|
|
|
```json
|
|
{
|
|
"type": "gov_executive_order",
|
|
"order_id": "EO-2025-12-002",
|
|
"title": "Security Emergency",
|
|
"issued_by": "did:vm:human:sovereign",
|
|
"authority": "ARTICLE-VI.1",
|
|
"order_type": "emergency",
|
|
"content": {
|
|
"emergency_type": "security_incident",
|
|
"threat_description": "Active intrusion on BRICK-02",
|
|
"powers_invoked": [
|
|
"Suspend authentication delays",
|
|
"Enhanced logging",
|
|
"Immediate capability revocation"
|
|
]
|
|
},
|
|
"duration": {
|
|
"type": "emergency",
|
|
"expires_at": "2025-12-09T03:50:00Z",
|
|
"renewable": true
|
|
}
|
|
}
|
|
```
|
|
|
|
### Violation Detection
|
|
|
|
```json
|
|
{
|
|
"type": "gov_violation",
|
|
"violation_id": "VIOL-2025-12-001",
|
|
"detected_at": "2025-12-06T16:00:00Z",
|
|
"detected_by": "engine:guardian",
|
|
"violation_type": "unauthorized_action",
|
|
"severity": "high",
|
|
"details": {
|
|
"actor": "did:vm:agent:automation-01",
|
|
"action_attempted": "modify_receipt",
|
|
"rule_violated": "AXIOM-001",
|
|
"action_result": "blocked"
|
|
},
|
|
"evidence": {
|
|
"log_entries": ["..."],
|
|
"request_hash": "blake3:..."
|
|
}
|
|
}
|
|
```
|
|
|
|
### Enforcement Action
|
|
|
|
```json
|
|
{
|
|
"type": "gov_enforcement",
|
|
"enforcement_id": "ENF-2025-12-001",
|
|
"violation_id": "VIOL-2025-12-001",
|
|
"enforced_at": "2025-12-06T16:05:00Z",
|
|
"enforcement_type": "capability_suspension",
|
|
"target": "did:vm:agent:automation-01",
|
|
"action_taken": {
|
|
"capability_suspended": "write",
|
|
"scope": "all_scrolls",
|
|
"duration": "pending_review"
|
|
},
|
|
"review_required": true,
|
|
"review_deadline": "2025-12-07T16:05:00Z"
|
|
}
|
|
```
|
|
|
|
### CLI Commands
|
|
|
|
```bash
|
|
# Constitution
|
|
vm-gov constitution show
|
|
vm-gov constitution version
|
|
vm-gov constitution diff v1.0.0 v1.1.0
|
|
|
|
# Proposals
|
|
vm-gov proposal create --type amendment --file proposal.json
|
|
vm-gov proposal list --status deliberation
|
|
vm-gov proposal show PROP-2025-12-001
|
|
|
|
# Voting
|
|
vm-gov vote PROP-2025-12-001 --vote approve
|
|
vm-gov vote PROP-2025-12-001 --vote reject --reason "..."
|
|
|
|
# Ratification
|
|
vm-gov ratify PROP-2025-12-001
|
|
|
|
# Executive Orders
|
|
vm-gov order create --type parameter_change --file order.json
|
|
vm-gov order list --active
|
|
vm-gov order revoke EO-2025-12-001
|
|
|
|
# Emergencies
|
|
vm-gov emergency declare --type security_incident --description "..."
|
|
vm-gov emergency status
|
|
vm-gov emergency extend --hours 24
|
|
vm-gov emergency end
|
|
|
|
# Violations
|
|
vm-gov violations list --severity high,critical
|
|
vm-gov violations review VIOL-2025-12-001 --decision dismiss
|
|
|
|
# Enforcement
|
|
vm-gov enforcement list --pending-review
|
|
vm-gov enforcement review ENF-2025-12-001 --decision uphold
|
|
```
|
|
|
|
---
|
|
|
|
## Engine Registry
|
|
|
|
All engines must be registered in the Constitution:
|
|
|
|
```json
|
|
{
|
|
"registered_engines": [
|
|
{
|
|
"engine_id": "engine:drills",
|
|
"name": "Security Drills",
|
|
"scroll": "Drills",
|
|
"authority": "Security training and exercise management",
|
|
"status": "active"
|
|
},
|
|
{
|
|
"engine_id": "engine:oracle",
|
|
"name": "Compliance Oracle",
|
|
"scroll": "Compliance",
|
|
"authority": "Compliance question answering",
|
|
"status": "active"
|
|
},
|
|
{
|
|
"engine_id": "engine:guardian",
|
|
"name": "Guardian",
|
|
"scroll": "Guardian",
|
|
"authority": "Anchoring and sentinel",
|
|
"status": "active"
|
|
},
|
|
{
|
|
"engine_id": "engine:treasury",
|
|
"name": "Treasury",
|
|
"scroll": "Treasury",
|
|
"authority": "Financial tracking",
|
|
"status": "active"
|
|
},
|
|
{
|
|
"engine_id": "engine:mesh",
|
|
"name": "Mesh",
|
|
"scroll": "Mesh",
|
|
"authority": "Topology management",
|
|
"status": "active"
|
|
},
|
|
{
|
|
"engine_id": "engine:offsec",
|
|
"name": "OffSec",
|
|
"scroll": "OffSec",
|
|
"authority": "Security operations",
|
|
"status": "active"
|
|
},
|
|
{
|
|
"engine_id": "engine:identity",
|
|
"name": "Identity",
|
|
"scroll": "Identity",
|
|
"authority": "DID and capability management",
|
|
"status": "active"
|
|
},
|
|
{
|
|
"engine_id": "engine:observability",
|
|
"name": "Observability",
|
|
"scroll": "Observability",
|
|
"authority": "Telemetry monitoring",
|
|
"status": "active"
|
|
},
|
|
{
|
|
"engine_id": "engine:automation",
|
|
"name": "Automation",
|
|
"scroll": "Automation",
|
|
"authority": "Workflow execution",
|
|
"status": "active"
|
|
},
|
|
{
|
|
"engine_id": "engine:psi",
|
|
"name": "Ψ-Field",
|
|
"scroll": "PsiField",
|
|
"authority": "Consciousness tracking",
|
|
"status": "active"
|
|
},
|
|
{
|
|
"engine_id": "engine:federation",
|
|
"name": "Federation",
|
|
"scroll": "Federation",
|
|
"authority": "Cross-mesh trust",
|
|
"status": "active"
|
|
},
|
|
{
|
|
"engine_id": "engine:governance",
|
|
"name": "Governance",
|
|
"scroll": "Governance",
|
|
"authority": "Constitutional enforcement",
|
|
"status": "active"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Adding New Engines
|
|
|
|
New engines require constitutional amendment:
|
|
|
|
1. Draft proposal with engine specification
|
|
2. 7-day deliberation period
|
|
3. Sovereign approval
|
|
4. Anchor confirmation activates engine
|
|
|
|
```bash
|
|
vm-gov proposal create \
|
|
--type add_engine \
|
|
--engine-id engine:analytics \
|
|
--name "Analytics" \
|
|
--scroll Analytics \
|
|
--authority "Data analysis and insights"
|
|
```
|