@kya-os/mcp-i-core 1.2.3-canary.6 → 1.3.0

package/docs/W3C_VC_DELEGATION_GUIDE.md

@@ -0,0 +1,710 @@
+# W3C Verifiable Credentials Delegation Guide
+
+## Overview
+
+The `@kya-os/mcp-i-core` package provides a production-ready implementation of W3C Verifiable Credentials for delegation in MCP-I systems. This guide explains how to issue, verify, and revoke delegation credentials.
+
+## Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Architecture](#architecture)
+3. [Issuing Delegation Credentials](#issuing-delegation-credentials)
+4. [Verifying Delegations](#verifying-delegations)
+5. [Revocation with StatusList2021](#revocation-with-statuslist2021)
+6. [Cascading Revocation](#cascading-revocation)
+7. [Tool Protection](#tool-protection)
+8. [Best Practices](#best-practices)
+
+## Quick Start
+
+```typescript
+import {
+  createDelegationIssuer,
+  createDelegationVerifier,
+  createStatusListManager,
+} from '@kya-os/mcp-i-core';
+
+// 1. Create issuer
+const issuer = createDelegationIssuer({
+  identityProvider: {
+    getDID: async () => 'did:key:z6Mk...',
+    getKeyId: async () => 'did:key:z6Mk...#key-1',
+    getPrivateKey: async () => privateKeyBase64,
+  },
+  signVC: async (vc) => {
+    // Sign the VC using Ed25519Signature2020
+    return signedVC;
+  },
+});
+
+// 2. Issue delegation
+const delegation = await issuer.issue({
+  subjectDid: 'did:key:z6Mkp...',
+  constraints: {
+    scope: {
+      allowedTools: ['read_file', 'write_file'],
+      allowedResources: ['/documents/*'],
+    },
+    budget: {
+      maxCost: 100,
+      currency: 'USD',
+    },
+    time: {
+      notBefore: new Date().toISOString(),
+      notAfter: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
+    },
+  },
+  audience: 'https://api.example.com',
+});
+
+// 3. Verify delegation
+const verifier = createDelegationVerifier({
+  resolveDID: async (did) => {
+    // Resolve DID to DID Document
+    return didDocument;
+  },
+  verifySignature: async (vc, publicKey) => {
+    // Verify signature
+    return true;
+  },
+});
+
+const result = await verifier.verify(delegation);
+console.log(result.valid); // true
+```
+
+## Architecture
+
+The delegation system consists of several key components:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Delegation System                         │
+├─────────────────────────────────────────────────────────────┤
+│                                                               │
+│  ┌───────────────────┐      ┌────────────────────┐         │
+│  │ Delegation        │      │ Delegation         │         │
+│  │ Issuer            │─────▶│ Credential (VC)    │         │
+│  │ (Ed25519)         │      │ - Constraints      │         │
+│  └───────────────────┘      │ - Proof            │         │
+│                              │ - Status           │         │
+│                              └────────────────────┘         │
+│                                      │                       │
+│                                      ▼                       │
+│  ┌───────────────────┐      ┌────────────────────┐         │
+│  │ Delegation        │◀─────│ StatusList2021     │         │
+│  │ Verifier          │      │ Manager            │         │
+│  │ (DID Resolution)  │      │ (Revocation)       │         │
+│  └───────────────────┘      └────────────────────┘         │
+│          │                           │                       │
+│          ▼                           ▼                       │
+│  ┌───────────────────┐      ┌────────────────────┐         │
+│  │ Tool Protection   │      │ Cascading          │         │
+│  │ Service           │      │ Revocation         │         │
+│  │ (Access Control)  │      │ (Graph-based)      │         │
+│  └───────────────────┘      └────────────────────┘         │
+│                                                               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Core Components
+
+1. **DelegationCredentialIssuer**: Creates W3C VC delegation credentials
+2. **DelegationCredentialVerifier**: Verifies delegation credentials
+3. **StatusList2021Manager**: Manages revocation lists efficiently
+4. **DelegationGraphManager**: Tracks delegation chains
+5. **CascadingRevocationManager**: Handles chain revocation
+6. **ToolProtectionService**: Enforces delegation requirements
+
+## Issuing Delegation Credentials
+
+### Basic Issuance
+
+```typescript
+import { DelegationCredentialIssuer } from '@kya-os/mcp-i-core';
+
+const issuer = new DelegationCredentialIssuer({
+  identityProvider: {
+    getDID: async () => 'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK',
+    getKeyId: async () => 'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#key-1',
+    getPrivateKey: async () => privateKeyBase64,
+  },
+  signVC: async (vc) => {
+    // Implement Ed25519Signature2020 signing
+    const signature = await ed25519.sign(canonicalJson, privateKey);
+    return {
+      ...vc,
+      proof: {
+        type: 'Ed25519Signature2020',
+        created: new Date().toISOString(),
+        verificationMethod: keyId,
+        proofPurpose: 'assertionMethod',
+        proofValue: `z${base58btc.encode(signature)}`,
+      },
+    };
+  },
+});
+```
+
+### CRISP Constraints
+
+Delegation credentials use CRISP constraints (Cost, Resource, Identity, Scope, Purpose):
+
+```typescript
+const constraints: DelegationConstraints = {
+  // Budget constraint (C - Cost)
+  budget: {
+    maxCost: 100,
+    currency: 'USD',
+    costPer: 'call', // or 'hour', 'day', 'month'
+  },
+
+  // Scope constraint (S - Scope)
+  scope: {
+    allowedTools: ['read_file', 'write_file', 'list_directory'],
+    allowedResources: [
+      '/documents/*',
+      '/public/data/*.json',
+    ],
+    deniedTools: ['delete_all'], // Explicit denials
+  },
+
+  // Time constraint (implicit P - Purpose)
+  time: {
+    notBefore: '2025-10-17T00:00:00Z',
+    notAfter: '2025-10-18T00:00:00Z',
+    maxDuration: 3600, // seconds
+  },
+};
+
+const delegation = await issuer.issue({
+  subjectDid: 'did:key:z6Mkp...',
+  constraints,
+  audience: 'https://api.example.com',
+});
+```
+
+### With Revocation Support
+
+```typescript
+// First, create a status list
+const statusListManager = createStatusListManager({
+  identityProvider,
+  storage: new MemoryStatusListStorage(), // or your storage backend
+  signVC,
+});
+
+const statusListId = await statusListManager.createStatusList('revocation');
+const statusListUrl = `https://status.example.com/lists/${statusListId}`;
+
+// Issue with revocation support
+const delegation = await issuer.issue({
+  subjectDid: 'did:key:z6Mkp...',
+  constraints,
+  audience: 'https://api.example.com',
+  credentialStatus: {
+    id: `${statusListUrl}#0`,
+    type: 'StatusList2021Entry',
+    statusPurpose: 'revocation',
+    statusListIndex: '0',
+    statusListCredential: statusListUrl,
+  },
+});
+```
+
+## Verifying Delegations
+
+### Basic Verification
+
+```typescript
+import { DelegationCredentialVerifier } from '@kya-os/mcp-i-core';
+
+const verifier = new DelegationCredentialVerifier({
+  // DID resolution
+  resolveDID: async (did: string) => {
+    const response = await fetch(`https://did-resolver.example.com/${did}`);
+    return await response.json();
+  },
+
+  // Signature verification
+  verifySignature: async (vc: VerifiableCredential, publicKey: string) => {
+    const proof = vc.proof as Ed25519Signature2020Proof;
+    const payload = canonicalizeVC(vc);
+    const signature = base58btc.decode(proof.proofValue.slice(1)); // Remove 'z'
+    return await ed25519.verify(signature, payload, publicKey);
+  },
+
+  // Status list resolution (for revocation checks)
+  resolveStatusList: async (url: string) => {
+    const response = await fetch(url);
+    return await response.json();
+  },
+});
+
+const result = await verifier.verify(delegation);
+
+if (result.valid) {
+  console.log('✅ Delegation is valid');
+  console.log('Subject:', delegation.credentialSubject.id);
+  console.log('Allowed tools:', delegation.credentialSubject.delegation.constraints.scope.allowedTools);
+} else {
+  console.error('❌ Delegation is invalid');
+  console.error('Errors:', result.errors);
+}
+```
+
+### Verification Result
+
+```typescript
+interface DelegationVCVerificationResult {
+  valid: boolean;
+  checks: {
+    structure: boolean;        // W3C VC structure valid
+    signature: boolean;        // Cryptographic signature valid
+    expiration: boolean;       // Not expired
+    notBefore: boolean;        // Currently active
+    revocation?: boolean;      // Not revoked (if status list present)
+    didResolution: boolean;    // DID resolved successfully
+  };
+  errors: string[];            // List of errors if invalid
+  warnings: string[];          // Non-fatal warnings
+}
+```
+
+### Constraint Validation
+
+```typescript
+// Check if delegation allows specific tool
+function canExecuteTool(delegation: DelegationCredential, toolName: string): boolean {
+  const constraints = delegation.credentialSubject.delegation.constraints;
+
+  // Check scope
+  if (constraints.scope.allowedTools && !constraints.scope.allowedTools.includes(toolName)) {
+    return false;
+  }
+
+  if (constraints.scope.deniedTools?.includes(toolName)) {
+    return false;
+  }
+
+  return true;
+}
+
+// Check budget remaining
+function checkBudget(delegation: DelegationCredential, usedCost: number): boolean {
+  const budget = delegation.credentialSubject.delegation.constraints.budget;
+  if (!budget) return true;
+
+  return usedCost < budget.maxCost;
+}
+```
+
+## Revocation with StatusList2021
+
+StatusList2021 provides efficient, privacy-preserving credential revocation using compressed bitstrings.
+
+### Creating Status Lists
+
+```typescript
+import { StatusList2021Manager } from '@kya-os/mcp-i-core';
+
+const manager = createStatusListManager({
+  identityProvider,
+  storage, // Implement StatusListStorageProvider
+  signVC,
+});
+
+// Create revocation list
+const revocationListId = await manager.createStatusList('revocation');
+
+// Create suspension list (optional)
+const suspensionListId = await manager.createStatusList('suspension');
+```
+
+### Revoking Credentials
+
+```typescript
+// Revoke a specific credential by its status list index
+await manager.setStatus(revocationListId, 42, true); // Index 42 is now revoked
+
+// Check status
+const isRevoked = await manager.getStatus(revocationListId, 42);
+console.log('Revoked:', isRevoked); // true
+
+// Un-revoke (rare, but possible)
+await manager.setStatus(revocationListId, 42, false);
+```
+
+### Bulk Operations
+
+```typescript
+// Revoke multiple credentials efficiently
+const indicesToRevoke = [0, 5, 10, 42, 100, 1000];
+
+for (const index of indicesToRevoke) {
+  await manager.setStatus(revocationListId, index, true);
+}
+
+// The bitstring is automatically compressed (gzip + base64)
+// Very efficient: 131,072 credentials = ~16KB compressed
+```
+
+### Status List Credentials
+
+The status list itself is a W3C Verifiable Credential:
+
+```json
+{
+  "@context": [
+    "https://www.w3.org/2018/credentials/v1",
+    "https://w3id.org/vc/status-list/2021/v1"
+  ],
+  "id": "https://status.example.com/lists/revocation-123",
+  "type": ["VerifiableCredential", "StatusList2021Credential"],
+  "issuer": "did:key:z6Mk...",
+  "issuanceDate": "2025-10-17T00:00:00Z",
+  "credentialSubject": {
+    "id": "https://status.example.com/lists/revocation-123#list",
+    "type": "StatusList2021",
+    "statusPurpose": "revocation",
+    "encodedList": "H4sIAAAAAAAAA-3BMQEAAADCoPVP..."
+  },
+  "proof": { ... }
+}
+```
+
+## Cascading Revocation
+
+When a delegation is revoked, all sub-delegations should also be revoked.
+
+### Setting Up Delegation Graph
+
+```typescript
+import {
+  DelegationGraphManager,
+  CascadingRevocationManager
+} from '@kya-os/mcp-i-core';
+
+// Create delegation graph
+const graph = createDelegationGraph({
+  storage: new MemoryDelegationGraphStorage(), // or your storage
+});
+
+// Track delegations
+await graph.addDelegation({
+  id: 'delegation-root',
+  issuerDid: 'did:key:issuer',
+  subjectDid: 'did:key:delegate1',
+  parentId: null,
+  issuedAt: new Date().toISOString(),
+  expiresAt: new Date(Date.now() + 86400000).toISOString(),
+  statusListUrl: 'https://status.example.com/lists/123',
+  statusListIndex: 0,
+});
+
+await graph.addDelegation({
+  id: 'delegation-sub',
+  issuerDid: 'did:key:delegate1',
+  subjectDid: 'did:key:delegate2',
+  parentId: 'delegation-root', // Link to parent
+  issuedAt: new Date().toISOString(),
+  expiresAt: new Date(Date.now() + 43200000).toISOString(),
+  statusListUrl: 'https://status.example.com/lists/123',
+  statusListIndex: 1,
+});
+```
+
+### Cascading Revocation
+
+```typescript
+const cascadingRevocation = createCascadingRevocationManager({
+  delegationGraph: graph,
+  statusListManager: manager,
+  issuerIdentity: identityProvider,
+  signVC,
+});
+
+// Revoke with cascade
+const revokedIds = await cascadingRevocation.revoke('delegation-root', {
+  cascade: true,
+  reason: 'Security incident',
+});
+
+console.log('Revoked delegations:', revokedIds);
+// ['delegation-root', 'delegation-sub']
+```
+
+### Revocation Hooks
+
+```typescript
+// Register hook for custom logic
+cascadingRevocation.onRevoke(async (event) => {
+  console.log('Revoked:', event.credentialId);
+  console.log('Reason:', event.reason);
+  console.log('Cascade:', event.cascade);
+
+  // Send notification
+  await notifyUser(event.credentialId, event.reason);
+
+  // Log to audit trail
+  await auditLog.record({
+    action: 'delegation.revoke',
+    credentialId: event.credentialId,
+    timestamp: new Date(),
+  });
+});
+```
+
+## Tool Protection
+
+Enforce delegation requirements on sensitive tools:
+
+```typescript
+import {
+  ToolProtectionService,
+  InMemoryToolProtectionCache
+} from '@kya-os/mcp-i-core';
+
+const toolProtection = new ToolProtectionService({
+  cache: new InMemoryToolProtectionCache(),
+  delegationVerifier: verifier,
+});
+
+// Configure protection
+await toolProtection.setProtection('delete_database', {
+  requiresDelegation: true,
+  requiredScopes: ['admin', 'delete'],
+  budgetLimit: 1000,
+  rateLimit: {
+    maxCalls: 10,
+    windowSeconds: 3600,
+  },
+});
+
+// Check access
+try {
+  const hasAccess = await toolProtection.checkAccess(
+    'delete_database',
+    'did:key:z6Mkp...',
+    delegation
+  );
+
+  if (hasAccess) {
+    // Execute tool
+    await deleteDatabase();
+
+    // Track usage
+    await toolProtection.trackUsage('delete_database', 'did:key:z6Mkp...', {
+      cost: 100,
+      timestamp: Date.now(),
+    });
+  }
+} catch (error) {
+  console.error('Access denied:', error.message);
+}
+```
+
+## Best Practices
+
+### 1. Key Management
+
+```typescript
+// ✅ DO: Use secure key storage
+import { SecureKeyStore } from './secure-storage';
+
+const identityProvider = {
+  getDID: async () => await keyStore.getDID(),
+  getPrivateKey: async () => await keyStore.getPrivateKey(),
+};
+
+// ❌ DON'T: Hardcode private keys
+const identityProvider = {
+  getDID: async () => 'did:key:z6Mk...',
+  getPrivateKey: async () => 'my-private-key-123', // NEVER DO THIS
+};
+```
+
+### 2. Principle of Least Privilege
+
+```typescript
+// ✅ DO: Minimal scope
+const constraints = {
+  scope: {
+    allowedTools: ['read_public_data'], // Only what's needed
+    allowedResources: ['/public/*.json'], // Specific paths
+  },
+  time: {
+    notBefore: now,
+    notAfter: now + 3600000, // 1 hour only
+  },
+};
+
+// ❌ DON'T: Over-permission
+const constraints = {
+  scope: {
+    allowedTools: ['*'], // Too broad
+  },
+  time: {
+    notAfter: now + 31536000000, // 1 year is too long
+  },
+};
+```
+
+### 3. Always Enable Revocation
+
+```typescript
+// ✅ DO: Include revocation support
+const delegation = await issuer.issue({
+  subjectDid,
+  constraints,
+  credentialStatus: statusEntry, // Always include this
+});
+
+// ❌ DON'T: Skip revocation
+const delegation = await issuer.issue({
+  subjectDid,
+  constraints,
+  // No credentialStatus = can't revoke!
+});
+```
+
+### 4. Verify Before Use
+
+```typescript
+// ✅ DO: Always verify
+async function executeTool(toolName: string, delegation: DelegationCredential) {
+  const result = await verifier.verify(delegation);
+  if (!result.valid) {
+    throw new Error(`Invalid delegation: ${result.errors.join(', ')}`);
+  }
+
+  // Now execute tool
+  return await tools[toolName]();
+}
+
+// ❌ DON'T: Trust without verification
+async function executeTool(toolName: string, delegation: DelegationCredential) {
+  // Skipping verification = security vulnerability
+  return await tools[toolName]();
+}
+```
+
+### 5. Monitor Usage
+
+```typescript
+// ✅ DO: Track and alert
+toolProtection.onUsage(async (event) => {
+  await metrics.record({
+    tool: event.toolName,
+    user: event.userDid,
+    cost: event.cost,
+    timestamp: event.timestamp,
+  });
+
+  // Alert on suspicious patterns
+  if (event.cost > 1000) {
+    await alerting.send(`High cost usage: ${event.cost}`);
+  }
+});
+```
+
+## Complete Example
+
+```typescript
+import {
+  createDelegationIssuer,
+  createDelegationVerifier,
+  createStatusListManager,
+  createCascadingRevocationManager,
+  createDelegationGraph,
+  ToolProtectionService,
+  InMemoryToolProtectionCache,
+  MemoryStatusListStorage,
+  MemoryDelegationGraphStorage,
+} from '@kya-os/mcp-i-core';
+
+// Setup
+const issuer = createDelegationIssuer({ identityProvider, signVC });
+const verifier = createDelegationVerifier({ resolveDID, verifySignature, resolveStatusList });
+const statusListManager = createStatusListManager({ identityProvider, storage: new MemoryStatusListStorage(), signVC });
+const delegationGraph = createDelegationGraph({ storage: new MemoryDelegationGraphStorage() });
+const cascadingRevocation = createCascadingRevocationManager({
+  delegationGraph,
+  statusListManager,
+  issuerIdentity: identityProvider,
+  signVC,
+});
+const toolProtection = new ToolProtectionService({
+  cache: new InMemoryToolProtectionCache(),
+  delegationVerifier: verifier,
+});
+
+// 1. Issue delegation
+const statusListId = await statusListManager.createStatusList('revocation');
+const delegation = await issuer.issue({
+  subjectDid: 'did:key:delegate',
+  constraints: {
+    scope: { allowedTools: ['read', 'write'] },
+    budget: { maxCost: 100, currency: 'USD' },
+    time: {
+      notBefore: new Date().toISOString(),
+      notAfter: new Date(Date.now() + 3600000).toISOString(),
+    },
+  },
+  audience: 'https://api.example.com',
+  credentialStatus: {
+    id: `https://status.example.com/lists/${statusListId}#0`,
+    type: 'StatusList2021Entry',
+    statusPurpose: 'revocation',
+    statusListIndex: '0',
+    statusListCredential: `https://status.example.com/lists/${statusListId}`,
+  },
+});
+
+// 2. Track in graph
+await delegationGraph.addDelegation({
+  id: delegation.id!,
+  issuerDid: await identityProvider.getDID(),
+  subjectDid: 'did:key:delegate',
+  parentId: null,
+  issuedAt: delegation.issuanceDate,
+  expiresAt: delegation.expirationDate!,
+  statusListUrl: `https://status.example.com/lists/${statusListId}`,
+  statusListIndex: 0,
+});
+
+// 3. Configure tool protection
+await toolProtection.setProtection('write', {
+  requiresDelegation: true,
+  requiredScopes: ['write'],
+  budgetLimit: 50,
+});
+
+// 4. Execute tool with delegation
+const result = await verifier.verify(delegation);
+if (result.valid) {
+  const hasAccess = await toolProtection.checkAccess('write', 'did:key:delegate', delegation);
+  if (hasAccess) {
+    // Execute tool
+    await executeWriteTool();
+
+    // Track usage
+    await toolProtection.trackUsage('write', 'did:key:delegate', {
+      cost: 10,
+      timestamp: Date.now(),
+    });
+  }
+}
+
+// 5. Revoke if needed
+await cascadingRevocation.revoke(delegation.id!, {
+  cascade: true,
+  reason: 'Project completed',
+});
+```
+
+## Next Steps
+
+- [StatusList2021 Guide](./STATUSLIST2021_GUIDE.md) - Deep dive into revocation
+- [Compliance Matrix](./COMPLIANCE_MATRIX.md) - Schema compliance status
+- [API Reference](./API_REFERENCE.md) - Complete API documentation