@kya-os/mcp-i-core 1.3.7-canary.0 → 1.3.7-canary.clientinfo.20251126041014

package/docs/API_REFERENCE.md

@@ -0,0 +1,1362 @@
+# 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/)