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

package/docs/API_REFERENCE.md

@@ -1,1362 +0,0 @@
-# API Reference
-
-Complete API reference for `@kya-os/mcp-i-core` package.
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Core Classes](#core-classes)
-  - [DelegationIssuer](#delegationissuer)
-  - [DelegationVerifier](#delegationverifier)
-  - [DelegationGraph](#delegationgraph)
-- [StatusList2021](#statuslist2021)
-  - [StatusList2021Manager](#statuslist2021manager)
-  - [StatusList2021Storage](#statuslist2021storage)
-- [Schema Verification](#schema-verification)
-  - [SchemaVerifier](#schemaverifier)
-  - [SchemaRegistry](#schemaregistry)
-- [Types](#types)
-- [Utilities](#utilities)
-
-## Installation
-
-```bash
-npm install @kya-os/mcp-i-core
-# or
-pnpm add @kya-os/mcp-i-core
-# or
-yarn add @kya-os/mcp-i-core
-```
-
-## Core Classes
-
-### DelegationIssuer
-
-Issues W3C Verifiable Credentials for delegation.
-
-#### Constructor
-
-```typescript
-new DelegationIssuer(options: DelegationIssuerOptions)
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `options.issuerDid` | `string` | DID of the issuing agent |
-| `options.privateKeyJwk` | `JsonWebKey` | Private key in JWK format |
-| `options.statusListManager?` | `StatusList2021Manager` | Optional status list manager for revocation |
-
-**Example:**
-
-```typescript
-import { DelegationIssuer } from '@kya-os/mcp-i-core';
-
-const issuer = new DelegationIssuer({
-  issuerDid: 'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK',
-  privateKeyJwk: {
-    kty: 'OKP',
-    crv: 'Ed25519',
-    d: 'base64-encoded-private-key',
-    x: 'base64-encoded-public-key',
-  },
-});
-```
-
-#### Methods
-
-##### `issue()`
-
-Issue a delegation credential.
-
-```typescript
-async issue(options: DelegationIssuanceOptions): Promise<DelegationCredential>
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `options.subjectDid` | `string` | DID of the delegate (recipient) |
-| `options.constraints` | `DelegationConstraints` | CRISP constraints for the delegation |
-| `options.audience?` | `string` | Target audience URL |
-| `options.expirationDate?` | `string` | ISO 8601 expiration date |
-| `options.credentialStatus?` | `CredentialStatus` | StatusList2021 entry |
-| `options.parentDelegation?` | `string` | Parent delegation ID for chains |
-
-**Returns:** `Promise<DelegationCredential>` - The issued delegation credential
-
-**Example:**
-
-```typescript
-const delegation = await issuer.issue({
-  subjectDid: 'did:key:z6MkrWXJPkxPCuQF7RqeKZFdZqBXz3oCG7PUty5dXLKGzELj',
-  constraints: {
-    budget: {
-      maxCost: 100,
-      currency: 'USD',
-    },
-    scope: {
-      allowedTools: ['read_file', 'write_file'],
-      allowedResources: ['/documents/*'],
-    },
-    time: {
-      notBefore: new Date().toISOString(),
-      notAfter: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
-    },
-  },
-  audience: 'https://api.example.com',
-});
-
-console.log('Delegation ID:', delegation.id);
-```
-
-##### `issueWithStatus()`
-
-Issue a delegation with automatic status list integration.
-
-```typescript
-async issueWithStatus(options: DelegationIssuanceOptions): Promise<DelegationCredential>
-```
-
-**Parameters:** Same as `issue()` but `credentialStatus` is automatically generated.
-
-**Returns:** `Promise<DelegationCredential>` - The issued delegation credential with status
-
-**Example:**
-
-```typescript
-const delegation = await issuer.issueWithStatus({
-  subjectDid: 'did:key:z6MkrWXJPkxPCuQF7RqeKZFdZqBXz3oCG7PUty5dXLKGzELj',
-  constraints: {
-    scope: {
-      allowedTools: ['read_file'],
-    },
-  },
-});
-
-// Automatically includes credentialStatus field
-console.log('Status index:', delegation.credentialStatus?.statusListIndex);
-```
-
----
-
-### DelegationVerifier
-
-Verifies delegation credentials.
-
-#### Constructor
-
-```typescript
-new DelegationVerifier(options?: DelegationVerifierOptions)
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `options.didResolver?` | `DIDResolver` | Custom DID resolver |
-| `options.statusListFetcher?` | `StatusListFetcher` | Custom status list fetcher |
-| `options.checkStatus?` | `boolean` | Enable status checking (default: true) |
-| `options.checkExpiration?` | `boolean` | Enable expiration checking (default: true) |
-
-**Example:**
-
-```typescript
-import { DelegationVerifier } from '@kya-os/mcp-i-core';
-
-const verifier = new DelegationVerifier({
-  checkStatus: true,
-  checkExpiration: true,
-});
-```
-
-#### Methods
-
-##### `verify()`
-
-Verify a delegation credential.
-
-```typescript
-async verify(options: DelegationVerificationOptions): Promise<DelegationVerificationResult>
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `options.credential` | `DelegationCredential` | The delegation to verify |
-| `options.expectedAudience?` | `string` | Expected audience (must match) |
-| `options.expectedSubject?` | `string` | Expected subject DID (must match) |
-| `options.checkChain?` | `boolean` | Verify entire delegation chain |
-| `options.now?` | `Date` | Current time for expiration checks |
-
-**Returns:** `Promise<DelegationVerificationResult>` - Verification result
-
-**Example:**
-
-```typescript
-const result = await verifier.verify({
-  credential: delegation,
-  expectedAudience: 'https://api.example.com',
-  checkChain: true,
-});
-
-if (result.verified) {
-  console.log('✅ Delegation is valid');
-  console.log('Subject:', result.subject);
-  console.log('Issuer:', result.issuer);
-  console.log('Constraints:', result.constraints);
-} else {
-  console.error('❌ Verification failed:', result.error);
-  if (result.statusRevoked) {
-    console.error('  Reason: Credential revoked');
-  }
-  if (result.expired) {
-    console.error('  Reason: Credential expired');
-  }
-}
-```
-
-##### `verifyChain()`
-
-Verify a complete delegation chain.
-
-```typescript
-async verifyChain(delegation: DelegationCredential): Promise<ChainVerificationResult>
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `delegation` | `DelegationCredential` | The delegation at the end of the chain |
-
-**Returns:** `Promise<ChainVerificationResult>` - Chain verification result
-
-**Example:**
-
-```typescript
-// Verify multi-level delegation chain
-const result = await verifier.verifyChain(leafDelegation);
-
-if (result.valid) {
-  console.log('✅ Chain is valid');
-  console.log('Chain length:', result.chain.length);
-  console.log('Root issuer:', result.rootIssuer);
-
-  // Print chain
-  for (const [i, delegation] of result.chain.entries()) {
-    console.log(`  Level ${i}: ${delegation.issuer} → ${delegation.credentialSubject.id}`);
-  }
-} else {
-  console.error('❌ Chain verification failed');
-  console.error('  Invalid at level:', result.invalidAtLevel);
-  console.error('  Reason:', result.error);
-}
-```
-
----
-
-### DelegationGraph
-
-Manages delegation relationships and cascading revocation.
-
-#### Constructor
-
-```typescript
-new DelegationGraph(options?: DelegationGraphOptions)
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `options.storage?` | `GraphStorage` | Custom graph storage backend |
-
-**Example:**
-
-```typescript
-import { DelegationGraph } from '@kya-os/mcp-i-core';
-
-const graph = new DelegationGraph();
-```
-
-#### Methods
-
-##### `addDelegation()`
-
-Add a delegation to the graph.
-
-```typescript
-async addDelegation(delegation: DelegationCredential): Promise<void>
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `delegation` | `DelegationCredential` | The delegation to add |
-
-**Example:**
-
-```typescript
-// Build delegation graph
-await graph.addDelegation(parentDelegation);
-await graph.addDelegation(childDelegation1);
-await graph.addDelegation(childDelegation2);
-
-console.log('Graph size:', await graph.size());
-```
-
-##### `getChildren()`
-
-Get all direct children of a delegation.
-
-```typescript
-async getChildren(delegationId: string): Promise<DelegationCredential[]>
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `delegationId` | `string` | ID of the parent delegation |
-
-**Returns:** `Promise<DelegationCredential[]>` - Array of child delegations
-
-**Example:**
-
-```typescript
-const children = await graph.getChildren(parentDelegation.id);
-console.log(`Found ${children.length} children`);
-
-for (const child of children) {
-  console.log(`  - ${child.id} (issued to ${child.credentialSubject.id})`);
-}
-```
-
-##### `getDescendants()`
-
-Get all descendants (recursive) of a delegation.
-
-```typescript
-async getDescendants(delegationId: string): Promise<DelegationCredential[]>
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `delegationId` | `string` | ID of the ancestor delegation |
-
-**Returns:** `Promise<DelegationCredential[]>` - Array of all descendants
-
-**Example:**
-
-```typescript
-// Get entire subtree
-const descendants = await graph.getDescendants(rootDelegation.id);
-console.log(`Total descendants: ${descendants.length}`);
-```
-
-##### `revokeDelegation()`
-
-Revoke a delegation and optionally all descendants.
-
-```typescript
-async revokeDelegation(
-  delegationId: string,
-  statusListManager: StatusList2021Manager,
-  options?: RevocationOptions
-): Promise<RevocationResult>
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `delegationId` | `string` | ID of delegation to revoke |
-| `statusListManager` | `StatusList2021Manager` | Status list manager |
-| `options.cascade?` | `boolean` | Revoke all descendants (default: true) |
-
-**Returns:** `Promise<RevocationResult>` - Revocation result with list of revoked IDs
-
-**Example:**
-
-```typescript
-// Revoke parent and all children
-const result = await graph.revokeDelegation(
-  parentDelegation.id,
-  statusListManager,
-  { cascade: true }
-);
-
-console.log('Revoked delegations:', result.revokedIds.length);
-for (const id of result.revokedIds) {
-  console.log(`  - ${id}`);
-}
-```
-
-##### `getPath()`
-
-Get the path from root to a delegation.
-
-```typescript
-async getPath(delegationId: string): Promise<DelegationCredential[]>
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `delegationId` | `string` | ID of target delegation |
-
-**Returns:** `Promise<DelegationCredential[]>` - Array of delegations from root to target
-
-**Example:**
-
-```typescript
-const path = await graph.getPath(leafDelegation.id);
-
-console.log('Delegation chain:');
-for (const [i, delegation] of path.entries()) {
-  console.log(`  ${i + 1}. ${delegation.issuer} → ${delegation.credentialSubject.id}`);
-}
-```
-
----
-
-## StatusList2021
-
-### StatusList2021Manager
-
-Manages StatusList2021 credentials for revocation.
-
-#### Constructor
-
-```typescript
-new StatusList2021Manager(options: StatusList2021ManagerOptions)
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `options.issuerDid` | `string` | DID of the status list issuer |
-| `options.statusListUrl` | `string` | Public URL where status list will be hosted |
-| `options.storage` | `StatusList2021Storage` | Storage backend for bitstrings |
-| `options.privateKeyJwk?` | `JsonWebKey` | Private key for signing status lists |
-
-**Example:**
-
-```typescript
-import { StatusList2021Manager, InMemoryStatusListStorage } from '@kya-os/mcp-i-core';
-
-const manager = new StatusList2021Manager({
-  issuerDid: 'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK',
-  statusListUrl: 'https://issuer.example.com/status/1',
-  storage: new InMemoryStatusListStorage(),
-  privateKeyJwk: issuerPrivateKey,
-});
-```
-
-#### Methods
-
-##### `createStatusList()`
-
-Create a new status list credential.
-
-```typescript
-async createStatusList(options: CreateStatusListOptions): Promise<StatusListCredential>
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `options.id` | `string` | Status list credential ID (URL) |
-| `options.purpose` | `'revocation' \| 'suspension'` | Purpose of the status list |
-| `options.length?` | `number` | Initial bitstring length (default: 131072) |
-
-**Returns:** `Promise<StatusListCredential>` - The status list credential
-
-**Example:**
-
-```typescript
-const statusListVC = await manager.createStatusList({
-  id: 'https://issuer.example.com/status/1',
-  purpose: 'revocation',
-});
-
-console.log('Status list created:', statusListVC.id);
-```
-
-##### `allocateIndex()`
-
-Allocate the next available index in the status list.
-
-```typescript
-async allocateIndex(): Promise<number>
-```
-
-**Returns:** `Promise<number>` - The allocated index
-
-**Example:**
-
-```typescript
-const index = await manager.allocateIndex();
-console.log('Allocated index:', index);
-
-// Use in credential
-const credentialStatus = {
-  id: `${statusListUrl}#${index}`,
-  type: 'StatusList2021Entry',
-  statusPurpose: 'revocation',
-  statusListIndex: index.toString(),
-  statusListCredential: statusListUrl,
-};
-```
-
-##### `revokeCredential()`
-
-Revoke a credential by setting its status list bit to 1.
-
-```typescript
-async revokeCredential(index: number): Promise<void>
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `index` | `number` | Status list index to revoke |
-
-**Example:**
-
-```typescript
-await manager.revokeCredential(42);
-console.log('Credential at index 42 revoked');
-```
-
-##### `unrevokeCredential()`
-
-Unrevoke a credential by setting its status list bit to 0.
-
-```typescript
-async unrevokeCredential(index: number): Promise<void>
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `index` | `number` | Status list index to unrevoke |
-
-**Example:**
-
-```typescript
-await manager.unrevokeCredential(42);
-console.log('Credential at index 42 restored');
-```
-
-##### `batchRevoke()`
-
-Revoke multiple credentials atomically.
-
-```typescript
-async batchRevoke(indexes: number[]): Promise<void>
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `indexes` | `number[]` | Array of indexes to revoke |
-
-**Example:**
-
-```typescript
-await manager.batchRevoke([42, 100, 250, 1337]);
-console.log('4 credentials revoked');
-```
-
-##### `checkStatus()`
-
-Check if a credential is revoked.
-
-```typescript
-async checkStatus(index: number): Promise<boolean>
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `index` | `number` | Status list index to check |
-
-**Returns:** `Promise<boolean>` - `true` if revoked, `false` if valid
-
-**Example:**
-
-```typescript
-const isRevoked = await manager.checkStatus(42);
-if (isRevoked) {
-  console.log('Credential is revoked');
-} else {
-  console.log('Credential is valid');
-}
-```
-
-##### `getStatusList()`
-
-Get the current status list credential.
-
-```typescript
-async getStatusList(url: string): Promise<StatusListCredential>
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `url` | `string` | Status list URL |
-
-**Returns:** `Promise<StatusListCredential>` - The status list credential
-
-**Example:**
-
-```typescript
-const statusListVC = await manager.getStatusList(
-  'https://issuer.example.com/status/1'
-);
-
-console.log('Encoded bitstring:', statusListVC.credentialSubject.encodedList);
-```
-
-##### `getMetrics()`
-
-Get status list metrics.
-
-```typescript
-async getMetrics(): Promise<StatusListMetrics>
-```
-
-**Returns:** `Promise<StatusListMetrics>` - Status list metrics
-
-**Example:**
-
-```typescript
-const metrics = await manager.getMetrics();
-
-console.log('Metrics:', {
-  allocatedIndexes: metrics.allocatedIndexes,
-  revokedCount: metrics.revokedCount,
-  revocationRate: (metrics.revokedCount / metrics.allocatedIndexes * 100).toFixed(2) + '%',
-  compressedSize: (metrics.compressedSize / 1024).toFixed(2) + 'KB',
-  compressionRatio: (metrics.uncompressedSize / metrics.compressedSize).toFixed(2) + 'x',
-});
-```
-
----
-
-### StatusList2021Storage
-
-Storage interface for status list bitstrings.
-
-#### Interface
-
-```typescript
-interface StatusList2021Storage {
-  getBitstring(statusListId: string): Promise<Uint8Array | null>;
-  setBitstring(statusListId: string, bitstring: Uint8Array): Promise<void>;
-  deleteBitstring(statusListId: string): Promise<void>;
-}
-```
-
-#### Implementations
-
-##### InMemoryStatusListStorage
-
-In-memory storage (for development/testing).
-
-```typescript
-import { InMemoryStatusListStorage } from '@kya-os/mcp-i-core';
-
-const storage = new InMemoryStatusListStorage();
-```
-
-##### RedisStatusListStorage
-
-Redis-backed storage (for production).
-
-```typescript
-import { RedisStatusListStorage } from '@kya-os/mcp-i-core';
-import Redis from 'ioredis';
-
-const redis = new Redis(process.env.REDIS_URL);
-const storage = new RedisStatusListStorage({
-  client: redis,
-  keyPrefix: 'statuslist:',
-  ttl: 86400, // 24 hours
-});
-```
-
-##### DynamoDBStatusListStorage
-
-AWS DynamoDB storage (for production).
-
-```typescript
-import { DynamoDBStatusListStorage } from '@kya-os/mcp-i-core';
-import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
-
-const dynamodb = new DynamoDBClient({ region: 'us-east-1' });
-const storage = new DynamoDBStatusListStorage({
-  client: dynamodb,
-  tableName: 'StatusLists',
-  ttl: 86400,
-});
-```
-
----
-
-## Schema Verification
-
-### SchemaVerifier
-
-Verifies implementations against JSON Schema draft-07 schemas.
-
-#### Constructor
-
-```typescript
-new SchemaVerifier(options?: SchemaVerifierOptions)
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `options.schemaRegistry?` | `SchemaRegistry` | Custom schema registry |
-| `options.strictMode?` | `boolean` | Enable strict validation (default: true) |
-
-**Example:**
-
-```typescript
-import { SchemaVerifier } from '@kya-os/mcp-i-core';
-
-const verifier = new SchemaVerifier({
-  strictMode: true,
-});
-```
-
-#### Methods
-
-##### `registerSchema()`
-
-Register a schema for validation.
-
-```typescript
-async registerSchema(name: string, schemaUrl: string): Promise<void>
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `name` | `string` | Schema identifier |
-| `schemaUrl` | `string` | URL to JSON Schema |
-
-**Example:**
-
-```typescript
-await verifier.registerSchema(
-  'delegation-credential',
-  'https://schemas.kya-os.ai/delegation-credential.schema.json'
-);
-```
-
-##### `verifySchema()`
-
-Verify an implementation against a registered schema.
-
-```typescript
-async verifySchema(schemaName: string, implementation: any): Promise<SchemaComplianceReport>
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `schemaName` | `string` | Registered schema name |
-| `implementation` | `any` | Implementation to verify |
-
-**Returns:** `Promise<SchemaComplianceReport>` - Compliance report
-
-**Example:**
-
-```typescript
-const report = await verifier.verifySchema('delegation-credential', myDelegation);
-
-if (report.compliant) {
-  console.log('✅ 100% compliant');
-} else {
-  console.log(`❌ ${report.compliancePercentage}% compliant`);
-
-  // Show issues
-  console.log('Missing fields:', report.missingFields);
-
-  for (const [field, result] of Object.entries(report.fieldCompliance)) {
-    if (result.typeMatch === 'mismatch') {
-      console.log(`Field '${field}':`);
-      console.log(`  Expected: ${result.expectedType}`);
-      console.log(`  Actual: ${result.actualType}`);
-    }
-  }
-}
-```
-
-##### `verifyAll()`
-
-Verify implementation against multiple schemas.
-
-```typescript
-async verifyAll(
-  schemas: string[],
-  implementation: any
-): Promise<FullComplianceReport>
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `schemas` | `string[]` | Array of schema names |
-| `implementation` | `any` | Implementation to verify |
-
-**Returns:** `Promise<FullComplianceReport>` - Compliance report for all schemas
-
-**Example:**
-
-```typescript
-const report = await verifier.verifyAll(
-  ['delegation-credential', 'delegation-constraints'],
-  myDelegation
-);
-
-console.log(`Overall compliance: ${report.overallCompliance}%`);
-
-for (const [schema, result] of Object.entries(report.schemaResults)) {
-  console.log(`${schema}: ${result.compliancePercentage}%`);
-}
-```
-
----
-
-### SchemaRegistry
-
-Registry for managing schemas.
-
-#### Constructor
-
-```typescript
-new SchemaRegistry(options?: SchemaRegistryOptions)
-```
-
-**Example:**
-
-```typescript
-import { SchemaRegistry } from '@kya-os/mcp-i-core';
-
-const registry = new SchemaRegistry();
-```
-
-#### Methods
-
-##### `register()`
-
-Register a schema.
-
-```typescript
-async register(name: string, schema: any): Promise<void>
-```
-
-##### `get()`
-
-Get a registered schema.
-
-```typescript
-async get(name: string): Promise<any>
-```
-
-##### `has()`
-
-Check if schema is registered.
-
-```typescript
-async has(name: string): Promise<boolean>
-```
-
-##### `list()`
-
-List all registered schemas.
-
-```typescript
-async list(): Promise<string[]>
-```
-
----
-
-## Types
-
-### DelegationCredential
-
-W3C Verifiable Credential for delegation.
-
-```typescript
-interface DelegationCredential {
-  '@context': string[];
-  id: string;
-  type: string[];
-  issuer: string;
-  issuanceDate: string;
-  expirationDate?: string;
-  credentialSubject: {
-    id: string;
-    constraints: DelegationConstraints;
-  };
-  credentialStatus?: CredentialStatus;
-  proof: Ed25519Proof;
-}
-```
-
-### DelegationConstraints
-
-CRISP constraints for delegation.
-
-```typescript
-interface DelegationConstraints {
-  // Cost constraints
-  budget?: {
-    maxCost: number;
-    currency: string;
-  };
-
-  // Resource constraints
-  resources?: {
-    maxRequests?: number;
-    maxTokens?: number;
-    maxStorage?: number;
-  };
-
-  // Identity constraints
-  identity?: {
-    requiredDid?: string;
-    allowedIssuers?: string[];
-  };
-
-  // Scope constraints
-  scope?: {
-    allowedTools?: string[];
-    allowedResources?: string[];
-    deniedTools?: string[];
-    deniedResources?: string[];
-  };
-
-  // Purpose constraints
-  purpose?: {
-    description: string;
-    category?: string;
-  };
-
-  // Time constraints
-  time?: {
-    notBefore?: string;
-    notAfter?: string;
-    maxDuration?: number;
-  };
-}
-```
-
-### DelegationVerificationResult
-
-Result of delegation verification.
-
-```typescript
-interface DelegationVerificationResult {
-  verified: boolean;
-  error?: string;
-  subject?: string;
-  issuer?: string;
-  constraints?: DelegationConstraints;
-  statusRevoked?: boolean;
-  expired?: boolean;
-  signatureValid?: boolean;
-}
-```
-
-### CredentialStatus
-
-StatusList2021 credential status.
-
-```typescript
-interface CredentialStatus {
-  id: string;
-  type: 'StatusList2021Entry';
-  statusPurpose: 'revocation' | 'suspension';
-  statusListIndex: string;
-  statusListCredential: string;
-}
-```
-
-### StatusListCredential
-
-StatusList2021 credential.
-
-```typescript
-interface StatusListCredential {
-  '@context': string[];
-  id: string;
-  type: string[];
-  issuer: string;
-  issuanceDate: string;
-  credentialSubject: {
-    id: string;
-    type: 'StatusList2021';
-    statusPurpose: 'revocation' | 'suspension';
-    encodedList: string;
-  };
-  proof: Ed25519Proof;
-}
-```
-
-### SchemaComplianceReport
-
-Schema compliance verification report.
-
-```typescript
-interface SchemaComplianceReport {
-  schemaName: string;
-  schemaUrl: string;
-  compliant: boolean;
-  compliancePercentage: number;
-  totalFields: number;
-  compliantFields: number;
-  fieldCompliance: Record<string, FieldComplianceResult>;
-  missingFields: string[];
-  extraFields: string[];
-  typeMismatches: Record<string, { expected: string; actual: string }>;
-}
-```
-
-### FieldComplianceResult
-
-Field-level compliance result.
-
-```typescript
-interface FieldComplianceResult {
-  present: boolean;
-  expectedType: string;
-  actualType: string | null;
-  typeMatch: 'match' | 'mismatch' | 'absent';
-  valueMatch: 'match' | 'mismatch' | 'absent';
-}
-```
-
----
-
-## Utilities
-
-### `createSchemaVerifier()`
-
-Factory function to create a SchemaVerifier with default settings.
-
-```typescript
-function createSchemaVerifier(options?: SchemaVerifierOptions): SchemaVerifier
-```
-
-**Example:**
-
-```typescript
-import { createSchemaVerifier } from '@kya-os/mcp-i-core';
-
-const verifier = createSchemaVerifier();
-await verifier.registerSchema('my-schema', 'https://example.com/schema.json');
-```
-
-### `verifyDelegation()`
-
-Helper function to verify a delegation credential.
-
-```typescript
-async function verifyDelegation(
-  options: DelegationVerificationOptions
-): Promise<DelegationVerificationResult>
-```
-
-**Example:**
-
-```typescript
-import { verifyDelegation } from '@kya-os/mcp-i-core';
-
-const result = await verifyDelegation({
-  credential: delegation,
-  expectedAudience: 'https://api.example.com',
-  checkStatus: true,
-});
-
-if (result.verified) {
-  console.log('✅ Valid delegation');
-}
-```
-
-### `parseDID()`
-
-Parse a DID string into components.
-
-```typescript
-function parseDID(did: string): ParsedDID
-```
-
-**Example:**
-
-```typescript
-import { parseDID } from '@kya-os/mcp-i-core';
-
-const parsed = parseDID('did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK');
-
-console.log({
-  method: parsed.method, // 'key'
-  id: parsed.id,         // 'z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK'
-  full: parsed.full,     // full DID string
-});
-```
-
-### `canonicalHash()`
-
-Create a canonical hash of data.
-
-```typescript
-async function canonicalHash(
-  data: any,
-  algorithm: 'sha256' | 'sha512'
-): Promise<string>
-```
-
-**Example:**
-
-```typescript
-import { canonicalHash } from '@kya-os/mcp-i-core';
-
-const hash = await canonicalHash({ foo: 'bar' }, 'sha256');
-console.log(hash); // "sha256:abc123..."
-```
-
----
-
-## Error Handling
-
-All async methods may throw errors. Always use try-catch:
-
-```typescript
-import { DelegationIssuer, DelegationError } from '@kya-os/mcp-i-core';
-
-try {
-  const delegation = await issuer.issue({
-    subjectDid: 'did:key:z6Mkr...',
-    constraints: { /* ... */ },
-  });
-} catch (error) {
-  if (error instanceof DelegationError) {
-    console.error('Delegation error:', error.message);
-    console.error('Code:', error.code);
-  } else {
-    console.error('Unexpected error:', error);
-  }
-}
-```
-
-### Common Error Codes
-
-| Code | Description |
-|------|-------------|
-| `INVALID_DID` | DID format is invalid |
-| `INVALID_CONSTRAINTS` | Constraints do not meet schema requirements |
-| `SIGNATURE_FAILED` | Cryptographic signature verification failed |
-| `STATUS_REVOKED` | Credential has been revoked |
-| `EXPIRED` | Credential has expired |
-| `CHAIN_INVALID` | Delegation chain verification failed |
-| `SCHEMA_INVALID` | Schema validation failed |
-| `STATUS_LIST_UNAVAILABLE` | Cannot fetch status list |
-
----
-
-## Complete Examples
-
-### Example 1: Full Delegation Lifecycle
-
-```typescript
-import {
-  DelegationIssuer,
-  DelegationVerifier,
-  StatusList2021Manager,
-  InMemoryStatusListStorage,
-} from '@kya-os/mcp-i-core';
-
-async function delegationLifecycle() {
-  // 1. Setup
-  const issuerDid = 'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK';
-  const delegateDid = 'did:key:z6MkrWXJPkxPCuQF7RqeKZFdZqBXz3oCG7PUty5dXLKGzELj';
-
-  // 2. Create status list manager
-  const statusListManager = new StatusList2021Manager({
-    issuerDid,
-    statusListUrl: 'https://issuer.example.com/status/1',
-    storage: new InMemoryStatusListStorage(),
-  });
-
-  await statusListManager.createStatusList({
-    id: 'https://issuer.example.com/status/1',
-    purpose: 'revocation',
-  });
-
-  // 3. Create issuer
-  const issuer = new DelegationIssuer({
-    issuerDid,
-    privateKeyJwk: issuerPrivateKey,
-    statusListManager,
-  });
-
-  // 4. Issue delegation
-  const delegation = await issuer.issueWithStatus({
-    subjectDid: delegateDid,
-    constraints: {
-      scope: {
-        allowedTools: ['read_file'],
-        allowedResources: ['/documents/*'],
-      },
-      time: {
-        notAfter: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
-      },
-    },
-  });
-
-  console.log('✅ Delegation issued:', delegation.id);
-
-  // 5. Verify delegation
-  const verifier = new DelegationVerifier();
-  const result1 = await verifier.verify({
-    credential: delegation,
-    checkStatus: true,
-    statusListFetcher: async (url) => {
-      return await statusListManager.getStatusList(url);
-    },
-  });
-
-  console.log('✅ Verification 1:', result1.verified);
-
-  // 6. Revoke delegation
-  const statusIndex = parseInt(delegation.credentialStatus!.statusListIndex);
-  await statusListManager.revokeCredential(statusIndex);
-
-  console.log('🔒 Delegation revoked');
-
-  // 7. Verify again (should fail)
-  const result2 = await verifier.verify({
-    credential: delegation,
-    checkStatus: true,
-    statusListFetcher: async (url) => {
-      return await statusListManager.getStatusList(url);
-    },
-  });
-
-  console.log('❌ Verification 2:', result2.verified); // false
-  console.log('   Status revoked:', result2.statusRevoked); // true
-}
-```
-
-### Example 2: Delegation Chains
-
-```typescript
-import {
-  DelegationIssuer,
-  DelegationGraph,
-  StatusList2021Manager,
-} from '@kya-os/mcp-i-core';
-
-async function delegationChains() {
-  const issuer = new DelegationIssuer({ /* ... */ });
-  const graph = new DelegationGraph();
-  const statusListManager = new StatusList2021Manager({ /* ... */ });
-
-  // Issue root delegation
-  const root = await issuer.issue({
-    subjectDid: 'did:key:alice',
-    constraints: {
-      scope: { allowedTools: ['*'] },
-    },
-  });
-
-  // Issue child delegation
-  const child = await issuer.issue({
-    subjectDid: 'did:key:bob',
-    constraints: {
-      scope: { allowedTools: ['read_file'] },
-    },
-    parentDelegation: root.id,
-  });
-
-  // Issue grandchild delegation
-  const grandchild = await issuer.issue({
-    subjectDid: 'did:key:charlie',
-    constraints: {
-      scope: { allowedTools: ['read_file'] },
-    },
-    parentDelegation: child.id,
-  });
-
-  // Build graph
-  await graph.addDelegation(root);
-  await graph.addDelegation(child);
-  await graph.addDelegation(grandchild);
-
-  // Get chain
-  const chain = await graph.getPath(grandchild.id);
-  console.log('Chain length:', chain.length); // 3
-
-  // Revoke root (cascades to all children)
-  await graph.revokeDelegation(root.id, statusListManager, { cascade: true });
-  console.log('All delegations revoked');
-}
-```
-
----
-
-## TypeScript Configuration
-
-For best TypeScript experience, use these settings:
-
-```json
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "commonjs",
-    "lib": ["ES2020"],
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true
-  }
-}
-```
-
----
-
-## Further Reading
-
-- [W3C VC Delegation Guide](./W3C_VC_DELEGATION_GUIDE.md)
-- [StatusList2021 Guide](./STATUSLIST2021_GUIDE.md)
-- [Compliance Matrix](./COMPLIANCE_MATRIX.md)
-- [W3C Verifiable Credentials](https://www.w3.org/TR/vc-data-model/)
-- [W3C StatusList2021](https://www.w3.org/TR/vc-status-list-2021/)