@kya-os/mcp-i-core 1.2.3-canary.7 → 1.3.1

package/docs/COMPLIANCE_MATRIX.md

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