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

package/src/compliance/EXAMPLE.md

@@ -1,412 +0,0 @@
-# Schema Compliance Verification - Usage Examples
-
-## Overview
-
-Automated verification tool to ensure 100% compliance with canonical schemas from `schemas.kya-os.ai`.
-
----
-
-## Quick Start
-
-```typescript
-import {
-  createSchemaVerifier,
-  getAllSchemas,
-  getCriticalSchemas,
-  getSchemasByCategory,
-} from '@kya-os/mcp-i-core';
-
-// Create verifier
-const verifier = createSchemaVerifier({
-  schemasBaseUrl: 'https://schemas.kya-os.ai',
-});
-
-// Get all schemas
-const allSchemas = getAllSchemas();
-console.log(`Total schemas: ${allSchemas.length}`); // 41
-
-// Get critical schemas (must be 100% compliant)
-const criticalSchemas = getCriticalSchemas();
-console.log(`Critical schemas: ${criticalSchemas.length}`); // 7
-```
-
----
-
-## Verify Single Schema
-
-```typescript
-import { createSchemaVerifier, getSchemaById } from '@kya-os/mcp-i-core';
-import { DelegationCredential } from '@kya-os/contracts';
-
-// Get the delegation credential schema
-const schema = getSchemaById('delegation-credential')!;
-
-// Create a sample delegation credential
-const delegationVC: DelegationCredential = {
-  '@context': [
-    'https://www.w3.org/2018/credentials/v1',
-    'https://mcp-i.org/contexts/delegation/v1',
-  ],
-  id: 'urn:uuid:123',
-  type: ['VerifiableCredential', 'DelegationCredential'],
-  issuer: 'did:key:z6Mkf...',
-  issuanceDate: '2025-10-17T00:00:00Z',
-  credentialSubject: {
-    id: 'did:key:z6Mkf...',
-    delegation: {
-      id: 'delegation-123',
-      issuerDid: 'did:key:z6Mkf...',
-      subjectDid: 'did:key:z6Mkf...',
-      // ... rest of delegation
-    },
-  },
-  proof: {
-    type: 'Ed25519Signature2020',
-    created: '2025-10-17T00:00:00Z',
-    verificationMethod: 'did:key:z6Mkf...#keys-1',
-    proofPurpose: 'assertionMethod',
-    proofValue: 'z58DAdF...',
-  },
-};
-
-// Verify compliance
-const verifier = createSchemaVerifier();
-const report = await verifier.verifySchema(schema, delegationVC);
-
-// Check results
-console.log(verifier.generateReport(report));
-
-if (report.compliant) {
-  console.log('✅ 100% Compliant!');
-} else {
-  console.log('❌ Issues found:');
-  report.issues.forEach((issue) => console.log(`  - ${issue}`));
-}
-```
-
-**Output:**
-```
-================================================================================
-SCHEMA COMPLIANCE REPORT: delegation-credential
-================================================================================
-
-Schema: DelegationCredential v1.0.0
-URL: https://schemas.kya-os.ai/xmcp-i/delegation/delegation-credential.v1.0.0.json
-Status: ✅ COMPLIANT
-Compliance: 100.0%
-
-📊 FIELD DETAILS:
-
-  ✅ Pass: 8
-  ❌ Fail: 0
-  ⚠️  Warn: 2
-  📝 Total: 10
-
-================================================================================
-```
-
----
-
-## Verify All Schemas
-
-```typescript
-import {
-  createSchemaVerifier,
-  getAllSchemas,
-} from '@kya-os/mcp-i-core';
-
-// Import all your implementations
-import * as implementations from '@kya-os/contracts';
-
-// Create a map of schema ID to implementation
-const implementationMap = new Map<string, any>([
-  ['verifiable-credential', implementations.VerifiableCredential],
-  ['delegation-credential', implementations.DelegationCredential],
-  ['detached-proof', implementations.DetachedProof],
-  // ... add all implementations
-]);
-
-// Verify all schemas
-const verifier = createSchemaVerifier();
-const schemas = getAllSchemas();
-const fullReport = await verifier.verifyAll(schemas, implementationMap);
-
-// Print summary
-console.log(verifier.generateFullReport(fullReport));
-
-console.log(`\nOverall Compliance: ${fullReport.overallCompliance.toFixed(1)}%`);
-console.log(`Compliant: ${fullReport.compliantSchemas}/${fullReport.totalSchemas}`);
-
-if (fullReport.criticalIssues.length > 0) {
-  console.log('\n🚨 Critical Issues:');
-  fullReport.criticalIssues.forEach((issue) => console.log(`  - ${issue}`));
-}
-```
-
-**Output:**
-```
-================================================================================
-FULL SCHEMA COMPLIANCE REPORT
-================================================================================
-
-Total Schemas: 41
-Compliant: 38
-Non-Compliant: 3
-Overall Compliance: 92.7%
-
-🚨 CRITICAL ISSUES (3):
-  1. mcp-tool: Missing implementation
-  2. mcp-resource: Missing implementation
-  3. mcp-prompt: Type mismatch in 'arguments' field
-
-📊 SCHEMA BREAKDOWN:
-
-  ✅ verifiable-credential: 100.0%
-  ✅ delegation-credential: 100.0%
-  ✅ detached-proof: 100.0%
-  ✅ statuslist2021-credential: 100.0%
-  ❌ mcp-tool: 0.0%
-  ❌ mcp-resource: 0.0%
-  ⚠️  mcp-prompt: 85.0%
-  ...
-
-================================================================================
-```
-
----
-
-## Verify by Category
-
-```typescript
-import {
-  createSchemaVerifier,
-  getSchemasByCategory,
-} from '@kya-os/mcp-i-core';
-
-// Get only W3C VC schemas
-const w3cSchemas = getSchemasByCategory('w3c');
-console.log(`W3C schemas: ${w3cSchemas.length}`); // 5
-
-// Get only delegation schemas
-const delegationSchemas = getSchemasByCategory('delegation');
-console.log(`Delegation schemas: ${delegationSchemas.length}`); // 6
-
-// Verify just delegation schemas
-const verifier = createSchemaVerifier();
-const delegationImplementations = new Map<string, any>([
-  ['delegation-credential', myDelegationCredential],
-  ['delegation-record', myDelegationRecord],
-  // ... add delegation implementations
-]);
-
-const report = await verifier.verifyAll(
-  delegationSchemas,
-  delegationImplementations
-);
-```
-
----
-
-## Get Statistics
-
-```typescript
-import { getSchemaStats } from '@kya-os/mcp-i-core';
-
-const stats = getSchemaStats();
-
-console.log(`Total schemas: ${stats.total}`); // 41
-
-console.log('\nBy Category:');
-Object.entries(stats.byCategory).forEach(([category, count]) => {
-  console.log(`  ${category}: ${count}`);
-});
-
-console.log('\nBy Version:');
-Object.entries(stats.byVersion).forEach(([version, count]) => {
-  console.log(`  v${version}: ${count}`);
-});
-```
-
-**Output:**
-```
-Total schemas: 41
-
-By Category:
-  w3c: 5
-  xmcp-i: 28
-  did: 2
-  mcp: 3
-  tlkrc: 2
-  runtime: 1
-
-By Version:
-  v1.0.0: 38
-  v1.1.0: 3
-```
-
----
-
-## Integration with Tests
-
-```typescript
-import { describe, test, expect } from 'vitest';
-import {
-  createSchemaVerifier,
-  getCriticalSchemas,
-} from '@kya-os/mcp-i-core';
-
-describe('Schema Compliance', () => {
-  test('all critical schemas should be 100% compliant', async () => {
-    const verifier = createSchemaVerifier();
-    const criticalSchemas = getCriticalSchemas();
-
-    for (const schema of criticalSchemas) {
-      const implementation = getImplementation(schema.id);
-      const report = await verifier.verifySchema(schema, implementation);
-
-      expect(report.compliant).toBe(true);
-      expect(report.compliancePercentage).toBe(100);
-      expect(report.issues).toHaveLength(0);
-    }
-  });
-
-  test('all schemas should be at least 95% compliant', async () => {
-    const verifier = createSchemaVerifier();
-    const schemas = getAllSchemas();
-    const implementations = getAllImplementations();
-
-    const fullReport = await verifier.verifyAll(schemas, implementations);
-
-    expect(fullReport.overallCompliance).toBeGreaterThanOrEqual(95);
-  });
-});
-```
-
----
-
-## Custom Verification Options
-
-```typescript
-import { createSchemaVerifier } from '@kya-os/mcp-i-core';
-
-// Use custom schemas endpoint (e.g., for testing)
-const verifier = createSchemaVerifier({
-  schemasBaseUrl: 'http://localhost:3000/schemas',
-});
-
-// Verify with custom options
-const report = await verifier.verifySchema(schema, implementation);
-```
-
----
-
-## Available Schema Categories
-
-```typescript
-const categories = [
-  'w3c',              // W3C Verifiable Credentials (5 schemas)
-  'delegation',       // Delegation system (6 schemas)
-  'identity',         // Agent identity (3 schemas)
-  'protocol',         // MCP-I protocol (5 schemas)
-  'tool-protection',  // Tool protection (2 schemas)
-  'audit',            // Audit logging (2 schemas)
-  'nonce',            // Nonce cache (2 schemas)
-  'mcp',              // MCP tools/resources (3 schemas)
-  'registry',         // Agent registry (2 schemas)
-  'verifier',         // Verifier service (3 schemas)
-  'config',           // Configuration (4 schemas)
-  'tlkrc',            // Tool-level key rotation (2 schemas)
-];
-```
-
----
-
-## Critical Schemas (Must Be 100% Compliant)
-
-1. `verifiable-credential` - W3C VC base
-2. `delegation-credential` - Delegation VCs
-3. `detached-proof` - MCP-I proofs
-4. `proof-meta` - Proof metadata
-5. `statuslist2021-credential` - Revocation lists
-6. `handshake-request` - Protocol handshakes
-7. `handshake-response` - Protocol responses
-
----
-
-## Field-Level Details
-
-```typescript
-const report = await verifier.verifySchema(schema, implementation);
-
-// Inspect field-level compliance
-report.fields.forEach((field) => {
-  console.log(`Field: ${field.fieldPath}`);
-  console.log(`  Present: ${field.present}`);
-  console.log(`  Expected Type: ${field.expectedType}`);
-  console.log(`  Actual Type: ${field.actualType}`);
-  console.log(`  Type Matches: ${field.typeMatches}`);
-  console.log(`  Required: ${field.required}`);
-  console.log(`  Status: ${field.status}`);
-  if (field.reason) {
-    console.log(`  Reason: ${field.reason}`);
-  }
-});
-```
-
----
-
-## CI/CD Integration
-
-```bash
-# Run compliance check in CI
-node scripts/check-compliance.js
-
-# Exit with error if not 100% compliant
-if [ $? -ne 0 ]; then
-  echo "❌ Schema compliance check failed"
-  exit 1
-fi
-```
-
-**scripts/check-compliance.js:**
-```javascript
-const { createSchemaVerifier, getAllSchemas } = require('@kya-os/mcp-i-core');
-
-async function main() {
-  const verifier = createSchemaVerifier();
-  const schemas = getAllSchemas();
-  const implementations = getImplementations();
-
-  const report = await verifier.verifyAll(schemas, implementations);
-
-  console.log(verifier.generateFullReport(report));
-
-  if (report.overallCompliance < 100) {
-    process.exit(1);
-  }
-}
-
-main();
-```
-
----
-
-## Next Steps
-
-1. **Implement Schema Fetching**: Add actual HTTP fetching from schemas.kya-os.ai
-2. **Add JSON Schema Validation**: Use AJV or similar for deep validation
-3. **Create Mock Schemas**: For offline testing
-4. **Add Caching**: Cache fetched schemas locally
-5. **Add Watch Mode**: Auto-verify on file changes
-
----
-
-**Status: Schema Compliance Tool Ready! 🎉**
-
-- ✅ 41 schemas cataloged
-- ✅ Automated verification
-- ✅ Field-level checking
-- ✅ Category filtering
-- ✅ Statistics
-- ✅ Report generation
-- ✅ CI/CD ready