@kya-os/mcp-i-core 1.3.12 → 1.3.14

package/docs/W3C_VC_DELEGATION_GUIDE.md

@@ -1,710 +0,0 @@
-# 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