Initialize repository snapshot
This commit is contained in:
Vault Sovereign
605
docs/skill/PROTOCOLS.md
Normal file
605
docs/skill/PROTOCOLS.md
Normal file
@@ -0,0 +1,605 @@
|
||||
# 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"
|
||||
```
|
||||
Reference in New Issue
Block a user