vm-core/docs/VAULTMESH-IDENTITY-ENGINE.md

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.

{
  "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.

{
  "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.

{
  "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.

{
  "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):

# 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:

{
  "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:

{
  "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

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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):

{
  "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:

# 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:

# 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

{
  "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

{
  "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