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

package/docs/COMPLIANCE_MATRIX.md

@@ -1,691 +0,0 @@
-# Schema Compliance Matrix
-
-## Overview
-
-This document tracks MCP-I Core's compliance with canonical schemas from [schemas.kya-os.ai](https://schemas.kya-os.ai). We use JSON Schema draft-07 validation to ensure 100% compatibility with the W3C VC and DID standards.
-
-## Current Compliance Status
-
-Last Updated: **2025-10-17**
-
-### Critical Schemas (100% Required)
-
-| Schema | Compliance | Status | Source |
-|--------|-----------|--------|--------|
-| `delegation-credential` | 100% ✅ | Production Ready | [schemas.kya-os.ai](https://schemas.kya-os.ai/delegation-credential.schema.json) |
-| `delegation-constraints` | 100% ✅ | Production Ready | [schemas.kya-os.ai](https://schemas.kya-os.ai/delegation-constraints.schema.json) |
-| `handshake-request` | 100% ✅ | Production Ready | [schemas.kya-os.ai](https://schemas.kya-os.ai/handshake-request.schema.json) |
-| `session-context` | 100% ✅ | Production Ready | [schemas.kya-os.ai](https://schemas.kya-os.ai/session-context.schema.json) |
-| `detached-proof` | 100% ✅ | Production Ready | [schemas.kya-os.ai](https://schemas.kya-os.ai/detached-proof.schema.json) |
-| `proof-meta` | 100% ✅ | Production Ready | [schemas.kya-os.ai](https://schemas.kya-os.ai/proof-meta.schema.json) |
-| `audit-record` | 100% ✅ | Production Ready | [schemas.kya-os.ai](https://schemas.kya-os.ai/audit-record.schema.json) |
-| `status-list-2021` | 100% ✅ | Production Ready | [W3C Spec](https://www.w3.org/TR/vc-status-list-2021/) |
-
-### Supporting Schemas (High Priority)
-
-| Schema | Compliance | Status | Notes |
-|--------|-----------|--------|-------|
-| `canonical-hashes` | 100% ✅ | Production Ready | SHA-256 and SHA-512 support |
-| `nonce-cache-entry` | 100% ✅ | Production Ready | Memory, Redis, DynamoDB |
-
-### Summary
-
-```
-┌─────────────────────────────────────────────────────────┐
-│          MCP-I Core Schema Compliance Report            │
-├─────────────────────────────────────────────────────────┤
-│ Critical Schemas (8):          8/8  (100%) ✅           │
-│ Supporting Schemas (2):        2/2  (100%) ✅           │
-│ Total Schemas:                10/10 (100%) ✅           │
-│                                                          │
-│ Status: PRODUCTION READY                                │
-└─────────────────────────────────────────────────────────┘
-```
-
-## Schema Details
-
-### 1. Delegation Credential
-
-**Schema URL:** https://schemas.kya-os.ai/delegation-credential.schema.json
-
-**Compliance:** 100% ✅
-
-**Required Fields:**
-- ✅ `@context` (array) - JSON-LD context
-- ✅ `type` (array) - Must include "VerifiableCredential" and "DelegationCredential"
-- ✅ `issuer` (string) - DID of issuing agent
-- ✅ `issuanceDate` (string, ISO 8601)
-- ✅ `credentialSubject` (object) - Subject DID and constraints
-- ✅ `proof` (object) - Ed25519Signature2020
-
-**Implementation:** `src/delegation/issuer.ts`
-
-**Example:**
-```typescript
-import { DelegationIssuer } from '@kya-os/mcp-i-core';
-
-const delegation = await issuer.issue({
-  subjectDid: 'did:key:z6Mkr...',
-  constraints: {
-    scope: {
-      allowedTools: ['read_file'],
-      allowedResources: ['/documents/*'],
-    },
-  },
-});
-```
-
-### 2. Delegation Constraints (CRISP)
-
-**Schema URL:** https://schemas.kya-os.ai/delegation-constraints.schema.json
-
-**Compliance:** 100% ✅
-
-**Constraint Types:**
-- ✅ **Cost** (`budget`): maxCost, currency
-- ✅ **Resource** (`resources`): quotas, rate limits
-- ✅ **Identity** (`identity`): authentication requirements
-- ✅ **Scope** (`scope`): allowedTools, allowedResources
-- ✅ **Purpose** (`purpose`): intended use description
-
-**Implementation:** `src/delegation/constraints.ts`
-
-**Example:**
-```typescript
-const constraints: DelegationConstraints = {
-  budget: {
-    maxCost: 100,
-    currency: 'USD',
-  },
-  scope: {
-    allowedTools: ['read_file', 'write_file'],
-    allowedResources: ['/documents/*', '/tmp/*'],
-  },
-  resources: {
-    maxRequests: 1000,
-    maxTokens: 100000,
-  },
-  time: {
-    notBefore: '2025-10-17T00:00:00Z',
-    notAfter: '2025-10-18T00:00:00Z',
-  },
-};
-```
-
-### 3. Handshake Request
-
-**Schema URL:** https://schemas.kya-os.ai/handshake-request.schema.json
-
-**Compliance:** 100% ✅
-
-**Required Fields:**
-- ✅ `nonce` (string) - Cryptographic nonce
-- ✅ `audience` (string) - Target service URL
-- ✅ `timestamp` (integer) - Unix timestamp
-- ✅ `agentDid` (string) - Agent's DID
-
-**Implementation:** `src/session/handshake.ts`
-
-**Example:**
-```typescript
-const handshake: HandshakeRequest = {
-  nonce: 'nonce-' + crypto.randomUUID(),
-  audience: 'https://api.example.com',
-  timestamp: Date.now(),
-  agentDid: 'did:key:z6Mkr...',
-};
-```
-
-### 4. Session Context
-
-**Schema URL:** https://schemas.kya-os.ai/session-context.schema.json
-
-**Compliance:** 100% ✅
-
-**Required Fields:**
-- ✅ `sessionId` (string) - Unique session identifier
-- ✅ `audience` (string) - Target service URL
-- ✅ `nonce` (string) - Handshake nonce
-- ✅ `timestamp` (integer) - Session creation time
-- ✅ `createdAt` (integer) - Unix timestamp
-- ✅ `lastActivity` (integer) - Last activity timestamp
-- ✅ `ttlMinutes` (integer) - Time-to-live in minutes
-- ✅ `agentDid` (string) - Agent's DID
-
-**Implementation:** `src/session/manager.ts`
-
-**Example:**
-```typescript
-const session: SessionContext = {
-  sessionId: 'session-' + crypto.randomUUID(),
-  audience: 'https://api.example.com',
-  nonce: 'nonce-123',
-  timestamp: Date.now(),
-  createdAt: Date.now(),
-  lastActivity: Date.now(),
-  ttlMinutes: 30,
-  agentDid: 'did:key:z6Mkr...',
-};
-```
-
-### 5. Detached Proof
-
-**Schema URL:** https://schemas.kya-os.ai/detached-proof.schema.json
-
-**Compliance:** 100% ✅
-
-**Required Fields:**
-- ✅ `type` (string) - "Ed25519Signature2020"
-- ✅ `verificationMethod` (string) - DID verification method
-- ✅ `proofPurpose` (string) - "assertionMethod"
-- ✅ `proofValue` (string) - Multibase-encoded signature
-- ✅ `created` (string, ISO 8601) - Proof creation time
-
-**Implementation:** `src/crypto/proof.ts`
-
-**Example:**
-```typescript
-const proof: DetachedProof = {
-  type: 'Ed25519Signature2020',
-  verificationMethod: 'did:key:z6Mkr...#z6Mkr...',
-  proofPurpose: 'assertionMethod',
-  proofValue: 'z58DAdFfa9SkqZ...',
-  created: new Date().toISOString(),
-};
-```
-
-### 6. Proof Metadata
-
-**Schema URL:** https://schemas.kya-os.ai/proof-meta.schema.json
-
-**Compliance:** 100% ✅
-
-**Required Fields:**
-- ✅ `did` (string) - Agent's DID
-- ✅ `kid` (string) - Key ID
-- ✅ `ts` (integer) - Unix timestamp
-- ✅ `nonce` (string) - Request nonce
-- ✅ `audience` (string) - Target audience
-- ✅ `sessionId` (string) - Session identifier
-- ✅ `requestHash` (string) - SHA-256 hash of request
-- ✅ `responseHash` (string) - SHA-256 hash of response
-
-**Optional Fields:**
-- ✅ `scopeId` (string) - Scope identifier
-- ✅ `delegationRef` (string) - Delegation credential reference
-
-**Implementation:** `src/crypto/proof-meta.ts`
-
-**Example:**
-```typescript
-const proofMeta: ProofMeta = {
-  did: 'did:key:z6Mkr...',
-  kid: 'did:key:z6Mkr...#z6Mkr...',
-  ts: Date.now(),
-  nonce: 'nonce-123',
-  audience: 'https://api.example.com',
-  sessionId: 'session-123',
-  requestHash: 'sha256:abc123...',
-  responseHash: 'sha256:def456...',
-  scopeId: 'scope-123',
-  delegationRef: 'urn:uuid:delegation-123',
-};
-```
-
-### 7. Audit Record
-
-**Schema URL:** https://schemas.kya-os.ai/audit-record.schema.json
-
-**Compliance:** 100% ✅
-
-**Required Fields:**
-- ✅ `version` (string) - "audit.v1"
-- ✅ `ts` (integer) - Unix timestamp
-- ✅ `session` (string) - Session ID
-- ✅ `audience` (string) - Target audience
-- ✅ `did` (string) - Agent's DID
-- ✅ `kid` (string) - Key ID
-- ✅ `reqHash` (string) - Request hash
-- ✅ `resHash` (string) - Response hash
-- ✅ `verified` (string) - "yes" | "no" | "pending"
-- ✅ `scope` (string) - Operation scope
-
-**Implementation:** `src/audit/logger.ts`
-
-**Example:**
-```typescript
-const auditRecord: AuditRecord = {
-  version: 'audit.v1',
-  ts: Date.now(),
-  session: 'session-123',
-  audience: 'https://api.example.com',
-  did: 'did:key:z6Mkr...',
-  kid: 'did:key:z6Mkr...#z6Mkr...',
-  reqHash: 'sha256:abc123...',
-  resHash: 'sha256:def456...',
-  verified: 'yes',
-  scope: 'tool-execution',
-};
-```
-
-### 8. StatusList2021 Credential
-
-**Schema URL:** https://www.w3.org/TR/vc-status-list-2021/
-
-**Compliance:** 100% ✅
-
-**Required Fields:**
-- ✅ `@context` - Includes status-list context
-- ✅ `type` - Includes "StatusList2021Credential"
-- ✅ `credentialSubject.encodedList` - GZIP-compressed bitstring
-- ✅ `credentialSubject.statusPurpose` - "revocation" | "suspension"
-
-**Implementation:** `src/status/statuslist-2021.ts`
-
-**Example:**
-```typescript
-const statusListVC = await statusListManager.createStatusList({
-  id: 'https://issuer.example.com/status/1',
-  purpose: 'revocation',
-});
-```
-
-### 9. Canonical Hashes
-
-**Schema URL:** https://schemas.kya-os.ai/canonical-hashes.schema.json
-
-**Compliance:** 100% ✅
-
-**Supported Algorithms:**
-- ✅ SHA-256 (primary)
-- ✅ SHA-512 (optional)
-
-**Format:** `algorithm:hexdigest`
-
-**Implementation:** `src/crypto/hash.ts`
-
-**Example:**
-```typescript
-const hash = await canonicalHash(data, 'sha256');
-// Returns: "sha256:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3"
-```
-
-### 10. Nonce Cache Entry
-
-**Schema URL:** https://schemas.kya-os.ai/nonce-cache-entry.schema.json
-
-**Compliance:** 100% ✅
-
-**Required Fields:**
-- ✅ `nonce` (string) - Cryptographic nonce
-- ✅ `sessionId` (string) - Associated session
-- ✅ `expiresAt` (integer) - Expiration timestamp
-
-**Implementation:** `src/cache/nonce-cache.ts`
-
-**Providers:**
-- ✅ In-Memory Cache
-- ✅ Redis Cache
-- ✅ DynamoDB Cache
-
-**Example:**
-```typescript
-await nonceCache.store({
-  nonce: 'nonce-123',
-  sessionId: 'session-456',
-  expiresAt: Date.now() + 300000, // 5 minutes
-});
-```
-
-## Running Compliance Audits
-
-### Automated Audit Script
-
-Run the compliance audit script to verify implementation against canonical schemas:
-
-```bash
-cd packages/mcp-i-core
-pnpm audit:compliance
-```
-
-**Output:**
-```
-╔════════════════════════════════════════════════════════════════╗
-║        MCP-I Core Schema Compliance Audit Report               ║
-╚════════════════════════════════════════════════════════════════╝
-
-┌──────────────────────────────────────────────────────────────┐
-│ Critical Schemas                                              │
-├──────────────────────────────────────────────────────────────┤
-│ delegation-credential        100.0%  ✅ (8/8 fields)          │
-│ delegation-constraints       100.0%  ✅ (5/5 fields)          │
-│ handshake-request            100.0%  ✅ (4/4 fields)          │
-│ session-context              100.0%  ✅ (8/8 fields)          │
-│ detached-proof               100.0%  ✅ (5/5 fields)          │
-│ proof-meta                   100.0%  ✅ (8/8 fields)          │
-│ audit-record                 100.0%  ✅ (10/10 fields)        │
-│ status-list-2021             100.0%  ✅ (4/4 fields)          │
-├──────────────────────────────────────────────────────────────┤
-│ Supporting Schemas                                            │
-├──────────────────────────────────────────────────────────────┤
-│ canonical-hashes             100.0%  ✅ (2/2 fields)          │
-│ nonce-cache-entry            100.0%  ✅ (3/3 fields)          │
-└──────────────────────────────────────────────────────────────┘
-
-Overall Compliance: 100% (57/57 fields)
-Status: PRODUCTION READY ✅
-```
-
-### Manual Verification
-
-Use the `SchemaVerifier` class to validate your own implementations:
-
-```typescript
-import { createSchemaVerifier } from '@kya-os/mcp-i-core';
-
-// Create verifier
-const verifier = createSchemaVerifier();
-
-// Register schema
-await verifier.registerSchema(
-  'my-schema',
-  'https://schemas.kya-os.ai/my-schema.schema.json'
-);
-
-// Verify implementation
-const myImplementation = {
-  field1: 'value1',
-  field2: 42,
-};
-
-const report = await verifier.verifySchema('my-schema', myImplementation);
-
-if (report.compliant) {
-  console.log('✅ 100% compliant');
-} else {
-  console.log(`❌ ${report.compliancePercentage}% compliant`);
-  console.log('Missing fields:', report.missingFields);
-  console.log('Type mismatches:', report.typeMismatches);
-}
-```
-
-## SchemaVerifier API
-
-### Features
-
-The `SchemaVerifier` class provides full JSON Schema draft-07 support:
-
-- **$ref Resolution**: Supports `#/definitions/`, `#/$defs/`, and `#` root references
-- **Union Types**: `oneOf`, `anyOf`, `allOf`
-- **Type Validation**: Including `integer` vs `number` distinction
-- **Nested Objects**: Recursive validation
-- **Arrays**: Tuple and array validation
-- **Patterns**: Regex pattern matching
-- **Enums**: Enumeration validation
-- **Formats**: String format validation
-- **Required Fields**: Required property checking
-
-### Example: Complete Validation
-
-```typescript
-import { createSchemaVerifier, type SchemaComplianceReport } from '@kya-os/mcp-i-core';
-
-async function validateDelegation(delegation: any): Promise<void> {
-  const verifier = createSchemaVerifier();
-
-  // Register delegation schema
-  await verifier.registerSchema(
-    'delegation-credential',
-    'https://schemas.kya-os.ai/delegation-credential.schema.json'
-  );
-
-  // Verify
-  const report: SchemaComplianceReport = await verifier.verifySchema(
-    'delegation-credential',
-    delegation
-  );
-
-  // Check results
-  if (!report.compliant) {
-    console.error('Delegation validation failed!');
-
-    // Show missing required fields
-    if (report.missingFields.length > 0) {
-      console.error('Missing required fields:', report.missingFields);
-    }
-
-    // Show type mismatches
-    for (const [field, result] of Object.entries(report.fieldCompliance)) {
-      if (result.typeMatch === 'mismatch') {
-        console.error(`Field '${field}' type mismatch:`);
-        console.error(`  Expected: ${result.expectedType}`);
-        console.error(`  Actual: ${result.actualType}`);
-      }
-    }
-
-    // Show extra fields
-    if (report.extraFields.length > 0) {
-      console.warn('Extra fields (not in schema):', report.extraFields);
-    }
-
-    throw new Error('Delegation does not conform to schema');
-  }
-
-  console.log('✅ Delegation is 100% compliant');
-}
-```
-
-### Example: Field-Level Analysis
-
-```typescript
-const report = await verifier.verifySchema('proof-meta', proofMeta);
-
-// Analyze each field
-for (const [field, result] of Object.entries(report.fieldCompliance)) {
-  console.log(`Field: ${field}`);
-  console.log(`  Present: ${result.present}`);
-  console.log(`  Expected Type: ${result.expectedType}`);
-  console.log(`  Actual Type: ${result.actualType}`);
-  console.log(`  Type Match: ${result.typeMatch}`);
-  console.log(`  Value Match: ${result.valueMatch}`);
-
-  if (result.typeMatch === 'mismatch') {
-    console.error(`  ❌ Type mismatch!`);
-  } else {
-    console.log(`  ✅ Compliant`);
-  }
-}
-```
-
-## Continuous Compliance
-
-### CI/CD Integration
-
-Add compliance checks to your CI/CD pipeline:
-
-```yaml
-# .github/workflows/compliance.yml
-name: Schema Compliance
-
-on: [push, pull_request]
-
-jobs:
-  compliance:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-
-      - name: Setup Node
-        uses: actions/setup-node@v3
-        with:
-          node-version: '20'
-
-      - name: Install dependencies
-        run: pnpm install
-
-      - name: Run compliance audit
-        run: pnpm audit:compliance
-
-      - name: Fail if not 100% compliant
-        run: |
-          if ! pnpm audit:compliance | grep -q "100%"; then
-            echo "❌ Schema compliance is not 100%"
-            exit 1
-          fi
-```
-
-### Pre-commit Hook
-
-Add a Git pre-commit hook to verify compliance before commits:
-
-```bash
-#!/bin/bash
-# .git/hooks/pre-commit
-
-echo "Running schema compliance audit..."
-cd packages/mcp-i-core
-pnpm audit:compliance
-
-if [ $? -ne 0 ]; then
-  echo "❌ Schema compliance check failed!"
-  echo "Please fix compliance issues before committing."
-  exit 1
-fi
-
-echo "✅ Schema compliance check passed!"
-```
-
-## Schema Evolution
-
-### Versioning Strategy
-
-When canonical schemas are updated:
-
-1. **Backward Compatible Changes** (additions only):
-   - Update implementation to support new fields
-   - Mark new fields as optional initially
-   - Run compliance audit to verify
-
-2. **Breaking Changes** (field removals or type changes):
-   - Create new schema version (e.g., `delegation-credential-v2`)
-   - Support both versions during transition period
-   - Deprecate old version with migration guide
-
-### Migration Example
-
-```typescript
-// Support both v1 and v2 during transition
-async function issueDelegation(constraints: any, version: 'v1' | 'v2' = 'v2') {
-  if (version === 'v1') {
-    // Use legacy schema
-    await verifier.verifySchema('delegation-credential-v1', constraints);
-  } else {
-    // Use current schema
-    await verifier.verifySchema('delegation-credential', constraints);
-  }
-
-  // Issue credential with appropriate schema
-  return await issuer.issue(constraints, { schemaVersion: version });
-}
-```
-
-## Best Practices
-
-### 1. Validate Early
-
-Validate data structures as early as possible:
-
-```typescript
-// Good: Validate at API boundary
-app.post('/delegate', async (req, res) => {
-  const verifier = createSchemaVerifier();
-  const report = await verifier.verifySchema('delegation-request', req.body);
-
-  if (!report.compliant) {
-    return res.status(400).json({
-      error: 'Invalid delegation request',
-      details: report,
-    });
-  }
-
-  // Proceed with validated data
-  const delegation = await issueDelegation(req.body);
-  res.json(delegation);
-});
-```
-
-### 2. Cache Schema Definitions
-
-Avoid fetching schemas repeatedly:
-
-```typescript
-// Good: Reuse verifier instance
-const globalVerifier = createSchemaVerifier();
-
-// Register schemas once at startup
-await globalVerifier.registerSchema(
-  'delegation-credential',
-  'https://schemas.kya-os.ai/delegation-credential.schema.json'
-);
-
-// Reuse throughout application
-export { globalVerifier };
-```
-
-### 3. Include Schemas in Error Messages
-
-Help developers fix validation errors:
-
-```typescript
-if (!report.compliant) {
-  throw new Error(
-    `Schema validation failed for '${schemaName}':\n` +
-    `  Missing fields: ${report.missingFields.join(', ')}\n` +
-    `  Type mismatches: ${JSON.stringify(report.typeMismatches, null, 2)}\n` +
-    `  Compliance: ${report.compliancePercentage}%\n` +
-    `  Schema URL: ${report.schemaUrl}`
-  );
-}
-```
-
-### 4. Monitor Compliance in Production
-
-Track compliance metrics:
-
-```typescript
-import { createSchemaVerifier } from '@kya-os/mcp-i-core';
-
-async function trackCompliance(data: any, schemaName: string) {
-  const verifier = createSchemaVerifier();
-  const report = await verifier.verifySchema(schemaName, data);
-
-  // Send metrics to monitoring system
-  metrics.gauge('schema_compliance', report.compliancePercentage, {
-    schema: schemaName,
-    compliant: report.compliant ? 'true' : 'false',
-  });
-
-  if (!report.compliant) {
-    logger.warn('Schema compliance issue', {
-      schema: schemaName,
-      compliance: report.compliancePercentage,
-      missingFields: report.missingFields,
-    });
-  }
-
-  return report;
-}
-```
-
-## References
-
-- [JSON Schema draft-07 Specification](https://json-schema.org/draft-07/json-schema-release-notes.html)
-- [schemas.kya-os.ai](https://schemas.kya-os.ai) - Canonical schema repository
-- [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/)
-- [W3C StatusList2021](https://www.w3.org/TR/vc-status-list-2021/)
-
-## Next Steps
-
-1. Review the [W3C VC Delegation Guide](./W3C_VC_DELEGATION_GUIDE.md) for delegation workflows
-2. Read the [StatusList2021 Guide](./STATUSLIST2021_GUIDE.md) for revocation patterns
-3. Explore the [API Reference](./API_REFERENCE.md) for detailed API documentation