# 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