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-IDENTITY-ENGINE.md
+++ b/docs/VAULTMESH-IDENTITY-ENGINE.md
@@ -0,0 +1,635 @@
+# VAULTMESH-IDENTITY-ENGINE.md
+
+**Civilization Ledger Identity Primitive**
+
+> *Every actor has a provenance. Every credential has a receipt.*
+
+Identity is VaultMesh's trust anchor — managing decentralized identifiers (DIDs), verifiable credentials, authentication events, and authorization decisions with cryptographic proof chains.
+
+---
+
+## 1. Scroll Definition
+
+| Property              | Value                                                                                                                                           |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Scroll Name**       | `Identity`                                                                                                                                      |
+| **JSONL Path**        | `receipts/identity/identity_events.jsonl`                                                                                                       |
+| **Root File**         | `ROOT.identity.txt`                                                                                                                             |
+| **Receipt Types**     | `identity_did_create`, `identity_did_rotate`, `identity_did_revoke`, `identity_credential_issue`, `identity_credential_revoke`, `identity_auth_event`, `identity_authz_decision` |
+
+---
+
+## 2. Core Concepts
+
+### 2.1 Decentralized Identifiers (DIDs)
+
+A **DID** is a self-sovereign identifier for any entity in the VaultMesh ecosystem.
+
+```json
+{
+  "did": "did:vm:user:sovereign",
+  "did_document": {
+    "@context": ["https://www.w3.org/ns/did/v1", "https://vaultmesh.io/ns/did/v1"],
+    "id": "did:vm:user:sovereign",
+    "controller": "did:vm:user:sovereign",
+    "verificationMethod": [
+      {
+        "id": "did:vm:user:sovereign#key-1",
+        "type": "Ed25519VerificationKey2020",
+        "controller": "did:vm:user:sovereign",
+        "publicKeyMultibase": "z6Mkf5rGMoatrSj1f..."
+      }
+    ],
+    "authentication": ["did:vm:user:sovereign#key-1"],
+    "assertionMethod": ["did:vm:user:sovereign#key-1"],
+    "capabilityInvocation": ["did:vm:user:sovereign#key-1"],
+    "capabilityDelegation": ["did:vm:user:sovereign#key-1"]
+  },
+  "created_at": "2025-01-15T00:00:00Z",
+  "updated_at": "2025-12-06T10:00:00Z",
+  "status": "active",
+  "metadata": {
+    "display_name": "Sovereign Operator",
+    "roles": ["admin", "operator"],
+    "organization": "did:vm:org:vaultmesh-hq"
+  }
+}
+```
+
+**DID types** (method-specific):
+- `did:vm:user:*` — human operators
+- `did:vm:node:*` — infrastructure nodes (BRICKs, portals)
+- `did:vm:service:*` — automated services, agents
+- `did:vm:org:*` — organizations, teams
+- `did:vm:device:*` — hardware devices, HSMs, YubiKeys
+
+### 2.2 Verifiable Credentials
+
+**Credentials** are signed attestations about a subject, issued by trusted parties.
+
+```json
+{
+  "credential_id": "vc:vm:2025-12-001",
+  "@context": [
+    "https://www.w3.org/2018/credentials/v1",
+    "https://vaultmesh.io/ns/credentials/v1"
+  ],
+  "type": ["VerifiableCredential", "VaultMeshOperatorCredential"],
+  "issuer": "did:vm:org:vaultmesh-hq",
+  "issuanceDate": "2025-12-01T00:00:00Z",
+  "expirationDate": "2026-12-01T00:00:00Z",
+  "credentialSubject": {
+    "id": "did:vm:user:sovereign",
+    "role": "administrator",
+    "permissions": ["anchor", "admin", "oracle"],
+    "clearance_level": "full",
+    "jurisdiction": ["eu-west", "us-east"]
+  },
+  "credentialStatus": {
+    "id": "https://vaultmesh.io/credentials/status/2025-12-001",
+    "type": "RevocationList2023"
+  },
+  "proof": {
+    "type": "Ed25519Signature2020",
+    "created": "2025-12-01T00:00:00Z",
+    "verificationMethod": "did:vm:org:vaultmesh-hq#key-1",
+    "proofPurpose": "assertionMethod",
+    "proofValue": "z3FXQjecWufY..."
+  }
+}
+```
+
+**Credential types**:
+- `VaultMeshOperatorCredential` — human operator authorization
+- `VaultMeshNodeCredential` — node identity and capabilities
+- `VaultMeshServiceCredential` — service authentication
+- `VaultMeshComplianceCredential` — compliance attestations
+- `VaultMeshDelegationCredential` — delegated authority
+
+### 2.3 Authentication Events
+
+Every authentication attempt is logged with full context.
+
+```json
+{
+  "auth_event_id": "auth-2025-12-06-001",
+  "timestamp": "2025-12-06T14:30:00Z",
+  "subject": "did:vm:user:sovereign",
+  "method": "ed25519_challenge",
+  "result": "success",
+  "session_id": "session-abc123...",
+  "client": {
+    "ip": "10.77.1.100",
+    "user_agent": "VaultMesh-CLI/1.0",
+    "device_fingerprint": "blake3:fff..."
+  },
+  "node": "did:vm:node:portal-01",
+  "mfa_used": true,
+  "mfa_method": "yubikey",
+  "risk_score": 0.1,
+  "tags": ["cli", "internal", "mfa"]
+}
+```
+
+**Authentication methods**:
+- `ed25519_challenge` — cryptographic challenge-response
+- `passkey` — WebAuthn/FIDO2
+- `yubikey` — hardware security key
+- `totp` — time-based OTP (fallback)
+- `mtls` — mutual TLS (node-to-node)
+- `api_key` — service accounts (with rotation)
+
+### 2.4 Authorization Decisions
+
+Every access control decision is logged for audit trails.
+
+```json
+{
+  "authz_event_id": "authz-2025-12-06-001",
+  "timestamp": "2025-12-06T14:30:05Z",
+  "subject": "did:vm:user:sovereign",
+  "action": "anchor_submit",
+  "resource": "scroll:treasury",
+  "decision": "allow",
+  "policy_matched": "policy:admin-full-access",
+  "context": {
+    "session_id": "session-abc123...",
+    "node": "did:vm:node:portal-01",
+    "request_id": "req-xyz789..."
+  },
+  "credentials_presented": ["vc:vm:2025-12-001"],
+  "evaluation_time_ms": 2
+}
+```
+
+---
+
+## 3. Mapping to Eternal Pattern
+
+### 3.1 Experience Layer (L1)
+
+**CLI** (`vm-identity`):
+```bash
+# DID operations
+vm-identity did create --type user --name "operator-alpha"
+vm-identity did show did:vm:user:sovereign
+vm-identity did list --type user --status active
+vm-identity did rotate --did did:vm:user:sovereign --reason "scheduled rotation"
+vm-identity did revoke --did did:vm:user:operator-alpha --reason "offboarded"
+
+# Key management
+vm-identity key list --did did:vm:user:sovereign
+vm-identity key add --did did:vm:user:sovereign --type ed25519 --purpose authentication
+vm-identity key revoke --did did:vm:user:sovereign --key-id key-2 --reason "compromised"
+
+# Credential operations
+vm-identity credential issue --subject did:vm:user:operator-alpha --type operator --role viewer
+vm-identity credential list --subject did:vm:user:sovereign
+vm-identity credential verify vc:vm:2025-12-001
+vm-identity credential revoke vc:vm:2025-12-001 --reason "role change"
+
+# Authentication
+vm-identity auth login --method passkey
+vm-identity auth logout
+vm-identity auth sessions --did did:vm:user:sovereign
+vm-identity auth revoke-session session-abc123
+
+# Authorization
+vm-identity authz check --subject did:vm:user:sovereign --action anchor_submit --resource scroll:treasury
+vm-identity authz policies list
+vm-identity authz policy show policy:admin-full-access
+
+# Audit
+vm-identity audit --did did:vm:user:sovereign --from 2025-12-01
+vm-identity audit --type auth_event --result failure --last 24h
+```
+
+**MCP Tools**:
+- `identity_did_resolve` — resolve DID to DID document
+- `identity_credential_verify` — verify credential validity
+- `identity_auth_status` — current session status
+- `identity_authz_check` — check authorization
+- `identity_audit_query` — query identity events
+
+**Portal HTTP**:
+- `GET /identity/dids` — list DIDs
+- `GET /identity/dids/{did}` — resolve DID
+- `POST /identity/dids` — create DID
+- `POST /identity/dids/{did}/rotate` — rotate keys
+- `DELETE /identity/dids/{did}` — revoke DID
+- `GET /identity/credentials` — list credentials
+- `POST /identity/credentials` — issue credential
+- `GET /identity/credentials/{id}/verify` — verify credential
+- `DELETE /identity/credentials/{id}` — revoke credential
+- `POST /identity/auth/challenge` — initiate auth
+- `POST /identity/auth/verify` — verify auth response
+- `GET /identity/sessions` — list sessions
+- `DELETE /identity/sessions/{id}` — revoke session
+
+---
+
+### 3.2 Engine Layer (L2)
+
+#### Step 1 — Plan → `identity_operation_contract.json`
+
+**DID Creation Contract**:
+```json
+{
+  "operation_id": "identity-op-2025-12-06-001",
+  "operation_type": "did_create",
+  "initiated_by": "did:vm:user:sovereign",
+  "initiated_at": "2025-12-06T10:00:00Z",
+  "target": {
+    "did_type": "user",
+    "display_name": "Operator Bravo",
+    "initial_roles": ["operator"],
+    "key_type": "ed25519"
+  },
+  "approval_required": true,
+  "approvers": ["did:vm:user:sovereign"],
+  "constraints": {
+    "credential_auto_issue": true,
+    "credential_type": "VaultMeshOperatorCredential",
+    "credential_expiry": "365d"
+  }
+}
+```
+
+**Credential Issuance Contract**:
+```json
+{
+  "operation_id": "identity-op-2025-12-06-002",
+  "operation_type": "credential_issue",
+  "initiated_by": "did:vm:org:vaultmesh-hq",
+  "initiated_at": "2025-12-06T11:00:00Z",
+  "credential": {
+    "type": "VaultMeshOperatorCredential",
+    "subject": "did:vm:user:operator-bravo",
+    "claims": {
+      "role": "operator",
+      "permissions": ["storage", "compute"],
+      "jurisdiction": ["eu-west"]
+    },
+    "validity_period": "365d"
+  },
+  "approval_required": false
+}
+```
+
+#### Step 2 — Execute → `identity_operation_state.json`
+
+```json
+{
+  "operation_id": "identity-op-2025-12-06-001",
+  "status": "completed",
+  "created_at": "2025-12-06T10:00:00Z",
+  "updated_at": "2025-12-06T10:05:00Z",
+  "steps": [
+    {
+      "step": "generate_keypair",
+      "status": "completed",
+      "completed_at": "2025-12-06T10:01:00Z",
+      "result": {
+        "public_key": "z6Mkf5rGMoatrSj1f...",
+        "key_id": "key-1"
+      }
+    },
+    {
+      "step": "create_did_document",
+      "status": "completed",
+      "completed_at": "2025-12-06T10:02:00Z",
+      "result": {
+        "did": "did:vm:user:operator-bravo"
+      }
+    },
+    {
+      "step": "register_did",
+      "status": "completed",
+      "completed_at": "2025-12-06T10:03:00Z",
+      "result": {
+        "registered": true,
+        "registry_hash": "blake3:aaa..."
+      }
+    },
+    {
+      "step": "issue_credential",
+      "status": "completed",
+      "completed_at": "2025-12-06T10:04:00Z",
+      "result": {
+        "credential_id": "vc:vm:2025-12-002"
+      }
+    }
+  ],
+  "approvals": {
+    "did:vm:user:sovereign": {
+      "approved_at": "2025-12-06T10:00:30Z",
+      "signature": "ed25519:..."
+    }
+  }
+}
+```
+
+#### Step 3 — Seal → Receipts
+
+**DID Creation Receipt**:
+```json
+{
+  "type": "identity_did_create",
+  "did": "did:vm:user:operator-bravo",
+  "did_type": "user",
+  "timestamp": "2025-12-06T10:03:00Z",
+  "created_by": "did:vm:user:sovereign",
+  "operation_id": "identity-op-2025-12-06-001",
+  "public_key_fingerprint": "SHA256:abc123...",
+  "did_document_hash": "blake3:bbb222...",
+  "initial_roles": ["operator"],
+  "tags": ["identity", "did", "create", "user"],
+  "root_hash": "blake3:ccc333..."
+}
+```
+
+**DID Key Rotation Receipt**:
+```json
+{
+  "type": "identity_did_rotate",
+  "did": "did:vm:user:sovereign",
+  "timestamp": "2025-12-06T15:00:00Z",
+  "rotated_by": "did:vm:user:sovereign",
+  "old_key_fingerprint": "SHA256:old123...",
+  "new_key_fingerprint": "SHA256:new456...",
+  "reason": "scheduled rotation",
+  "old_key_status": "revoked",
+  "tags": ["identity", "did", "rotate", "key"],
+  "root_hash": "blake3:ddd444..."
+}
+```
+
+**Credential Issuance Receipt**:
+```json
+{
+  "type": "identity_credential_issue",
+  "credential_id": "vc:vm:2025-12-002",
+  "credential_type": "VaultMeshOperatorCredential",
+  "timestamp": "2025-12-06T10:04:00Z",
+  "issuer": "did:vm:org:vaultmesh-hq",
+  "subject": "did:vm:user:operator-bravo",
+  "claims_hash": "blake3:eee555...",
+  "expires_at": "2026-12-06T00:00:00Z",
+  "operation_id": "identity-op-2025-12-06-001",
+  "tags": ["identity", "credential", "issue", "operator"],
+  "root_hash": "blake3:fff666..."
+}
+```
+
+**Credential Revocation Receipt**:
+```json
+{
+  "type": "identity_credential_revoke",
+  "credential_id": "vc:vm:2025-12-002",
+  "timestamp": "2025-12-06T18:00:00Z",
+  "revoked_by": "did:vm:user:sovereign",
+  "reason": "role change",
+  "revocation_list_updated": true,
+  "tags": ["identity", "credential", "revoke"],
+  "root_hash": "blake3:ggg777..."
+}
+```
+
+**Authentication Event Receipt**:
+```json
+{
+  "type": "identity_auth_event",
+  "auth_event_id": "auth-2025-12-06-001",
+  "timestamp": "2025-12-06T14:30:00Z",
+  "subject": "did:vm:user:sovereign",
+  "method": "passkey",
+  "result": "success",
+  "session_id": "session-abc123...",
+  "node": "did:vm:node:portal-01",
+  "client_fingerprint": "blake3:hhh888...",
+  "mfa_used": true,
+  "risk_score": 0.1,
+  "tags": ["identity", "auth", "success", "mfa"],
+  "root_hash": "blake3:iii999..."
+}
+```
+
+**Authorization Decision Receipt** (for sensitive operations):
+```json
+{
+  "type": "identity_authz_decision",
+  "authz_event_id": "authz-2025-12-06-001",
+  "timestamp": "2025-12-06T14:30:05Z",
+  "subject": "did:vm:user:sovereign",
+  "action": "capability_grant",
+  "resource": "did:vm:node:brick-03",
+  "decision": "allow",
+  "policy_matched": "policy:admin-full-access",
+  "credentials_verified": ["vc:vm:2025-12-001"],
+  "tags": ["identity", "authz", "allow", "sensitive"],
+  "root_hash": "blake3:jjj000..."
+}
+```
+
+---
+
+### 3.3 Ledger Layer (L3)
+
+**Receipt Types**:
+
+| Type                        | When Emitted                          |
+| --------------------------- | ------------------------------------- |
+| `identity_did_create`       | New DID registered                    |
+| `identity_did_rotate`       | DID keys rotated                      |
+| `identity_did_revoke`       | DID revoked/deactivated               |
+| `identity_credential_issue` | New credential issued                 |
+| `identity_credential_revoke`| Credential revoked                    |
+| `identity_auth_event`       | Authentication attempt (success/fail) |
+| `identity_authz_decision`   | Sensitive authorization decision      |
+
+**Merkle Coverage**:
+- All receipts append to `receipts/identity/identity_events.jsonl`
+- `ROOT.identity.txt` updated after each append
+- Guardian anchors Identity root in anchor cycles
+
+---
+
+## 4. Query Interface
+
+`identity_query_events.py`:
+
+```bash
+# DID history
+vm-identity query --did did:vm:user:sovereign
+
+# All auth events for a subject
+vm-identity query --type auth_event --subject did:vm:user:sovereign
+
+# Failed authentications
+vm-identity query --type auth_event --result failure --last 7d
+
+# Credentials issued by an org
+vm-identity query --type credential_issue --issuer did:vm:org:vaultmesh-hq
+
+# Authorization denials
+vm-identity query --type authz_decision --decision deny
+
+# Date range
+vm-identity query --from 2025-12-01 --to 2025-12-06
+
+# Export for compliance audit
+vm-identity query --from 2025-01-01 --format csv > identity_audit_2025.csv
+```
+
+**DID Resolution History**:
+```bash
+# Show all versions of a DID document
+vm-identity did history did:vm:user:sovereign
+
+# Output:
+# Version 1: 2025-01-15T00:00:00Z (created)
+#   - Key: key-1 (ed25519)
+# Version 2: 2025-06-15T00:00:00Z (key rotation)
+#   - Key: key-1 (revoked), key-2 (ed25519)
+# Version 3: 2025-12-06T15:00:00Z (key rotation)
+#   - Key: key-2 (revoked), key-3 (ed25519)
+```
+
+---
+
+## 5. Design Gate Checklist
+
+| Question              | Identity Answer                                                  |
+| --------------------- | ---------------------------------------------------------------- |
+| Clear entrypoint?     | ✅ CLI (`vm-identity`), MCP tools, Portal HTTP                   |
+| Contract produced?    | ✅ `identity_operation_contract.json` for DID/credential ops     |
+| State object?         | ✅ `identity_operation_state.json` tracking multi-step operations |
+| Receipts emitted?     | ✅ Seven receipt types covering all identity events              |
+| Append-only JSONL?    | ✅ `receipts/identity/identity_events.jsonl`                     |
+| Merkle root?          | ✅ `ROOT.identity.txt`                                           |
+| Guardian anchor path? | ✅ Identity root included in ProofChain                          |
+| Query tool?           | ✅ `identity_query_events.py` + DID history                      |
+
+---
+
+## 6. Key Management
+
+### 6.1 Key Hierarchy
+
+```
+Root of Trust (Hardware)
+├── Organization Master Key (HSM-protected)
+│   ├── Node Signing Keys
+│   │   ├── did:vm:node:brick-01#key-1
+│   │   ├── did:vm:node:brick-02#key-1
+│   │   └── did:vm:node:portal-01#key-1
+│   ├── Service Keys
+│   │   ├── did:vm:service:guardian#key-1
+│   │   └── did:vm:service:oracle#key-1
+│   └── Credential Issuing Keys
+│       └── did:vm:org:vaultmesh-hq#issuer-key-1
+└── User Keys (Self-custodied)
+    ├── did:vm:user:sovereign#key-1
+    └── did:vm:user:operator-bravo#key-1
+```
+
+### 6.2 Key Rotation Policy
+
+| Key Type            | Rotation Period | Trigger Events                    |
+| ------------------- | --------------- | --------------------------------- |
+| User keys           | 365 days        | Compromise, role change           |
+| Node keys           | 180 days        | Compromise, node migration        |
+| Service keys        | 90 days         | Compromise, version upgrade       |
+| Credential issuers  | 730 days        | Compromise, policy change         |
+| Organization master | Manual only     | Compromise, leadership change     |
+
+### 6.3 Recovery Procedures
+
+```json
+{
+  "recovery_id": "recovery-2025-12-06-001",
+  "did": "did:vm:user:operator-bravo",
+  "reason": "lost_device",
+  "initiated_at": "2025-12-06T09:00:00Z",
+  "recovery_method": "social_recovery",
+  "guardians_required": 3,
+  "guardians_responded": [
+    {"guardian": "did:vm:user:sovereign", "approved_at": "2025-12-06T09:15:00Z"},
+    {"guardian": "did:vm:user:operator-alpha", "approved_at": "2025-12-06T09:20:00Z"},
+    {"guardian": "did:vm:user:operator-charlie", "approved_at": "2025-12-06T09:25:00Z"}
+  ],
+  "status": "completed",
+  "new_key_registered_at": "2025-12-06T09:30:00Z"
+}
+```
+
+---
+
+## 7. Policy Engine
+
+### 7.1 Policy Definition
+
+```json
+{
+  "policy_id": "policy:admin-full-access",
+  "name": "Administrator Full Access",
+  "description": "Full access to all VaultMesh operations",
+  "version": 1,
+  "effect": "allow",
+  "subjects": {
+    "match": "credential",
+    "credential_type": "VaultMeshOperatorCredential",
+    "claims": {
+      "role": "administrator"
+    }
+  },
+  "actions": ["*"],
+  "resources": ["*"],
+  "conditions": {
+    "mfa_required": true,
+    "allowed_hours": {"start": "00:00", "end": "23:59"},
+    "allowed_nodes": ["*"]
+  }
+}
+```
+
+### 7.2 Policy Evaluation
+
+```
+Request:
+  Subject: did:vm:user:sovereign
+  Action: anchor_submit
+  Resource: scroll:treasury
+
+Evaluation:
+  1. Resolve subject credentials
+  2. Match policies by subject claims
+  3. Check action/resource match
+  4. Evaluate conditions (MFA, time, location)
+  5. Log decision with full context
+  6. Return allow/deny with reason
+```
+
+---
+
+## 8. Integration Points
+
+| System           | Integration                                                                |
+| ---------------- | -------------------------------------------------------------------------- |
+| **Guardian**     | Uses Identity for anchor authentication; alerts on suspicious auth events |
+| **Mesh**         | Node DIDs registered via Identity; capability grants require valid credentials |
+| **Treasury**     | Account ownership linked to DIDs; transaction signing uses Identity keys  |
+| **Oracle**       | Oracle queries authenticated via Identity; responses signed with service DID |
+| **OffSec**       | Incident response can trigger emergency credential revocations            |
+| **Observability**| All identity events flow to observability for correlation                 |
+
+---
+
+## 9. Future Extensions
+
+- **Biometric binding**: Link credentials to biometric templates
+- **Delegation chains**: Transitive capability delegation with constraints
+- **Anonymous credentials**: Zero-knowledge proofs for privacy-preserving auth
+- **Cross-mesh identity**: Federated identity across VaultMesh instances
+- **Hardware attestation**: TPM/Secure Enclave binding for high-assurance
+- **Identity recovery DAO**: Decentralized recovery governance