# 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