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

package/src/delegation/vc-verifier.ts

@@ -1,568 +0,0 @@
-/**
- * Delegation Credential Verifier (Platform-Agnostic)
- *
- * Progressive enhancement verification for W3C Delegation Credentials.
- * Follows the Edge-Delegation-Verification.md pattern:
- *
- * Stage 1: Fast basic checks (no network, early rejection)
- * Stage 2: Parallel advanced checks (signature, status)
- * Stage 3: Combined results
- *
- * Related Spec: MCP-I §4.3, W3C VC Data Model 1.1
- * Python Reference: Edge-Delegation-Verification.md
- */
-
-import type {
-  DelegationCredential,
-  CredentialStatus,
-} from '@kya-os/contracts';
-import {
-  isDelegationCredentialExpired,
-  isDelegationCredentialNotYetValid,
-  validateDelegationCredential,
-} from '@kya-os/contracts';
-
-/**
- * Verification result for delegation credentials
- */
-export interface DelegationVCVerificationResult {
-  /** Whether the delegation credential is valid */
-  valid: boolean;
-
-  /** Reason for invalid result (if valid=false) */
-  reason?: string;
-
-  /** Stage at which verification completed */
-  stage: 'basic' | 'signature' | 'status' | 'complete';
-
-  /** Whether result came from cache */
-  cached?: boolean;
-
-  /** Performance metrics */
-  metrics?: {
-    basicCheckMs?: number;
-    signatureCheckMs?: number;
-    statusCheckMs?: number;
-    totalMs: number;
-  };
-
-  /** Details about what was checked */
-  checks?: {
-    basicValid?: boolean;
-    signatureValid?: boolean;
-    statusValid?: boolean;
-  };
-}
-
-/**
- * Options for verification
- */
-export interface VerifyDelegationVCOptions {
-  /** Skip cache and force fresh verification */
-  skipCache?: boolean;
-
-  /** Skip signature verification (faster, less secure) */
-  skipSignature?: boolean;
-
-  /** Skip status checking (faster, may miss revocations) */
-  skipStatus?: boolean;
-
-  /** DID resolver for fetching public keys */
-  didResolver?: DIDResolver;
-
-  /** Status list resolver for checking revocation */
-  statusListResolver?: StatusListResolver;
-}
-
-/**
- * DID Resolver interface
- */
-export interface DIDResolver {
-  /**
-   * Resolve a DID to get the DID Document
-   * @param did - The DID to resolve
-   * @returns DID Document with verification methods
-   */
-  resolve(did: string): Promise<DIDDocument | null>;
-}
-
-/**
- * DID Document (simplified)
- */
-export interface DIDDocument {
-  id: string;
-  verificationMethod?: VerificationMethod[];
-  authentication?: (string | VerificationMethod)[];
-  assertionMethod?: (string | VerificationMethod)[];
-}
-
-/**
- * Verification Method
- */
-export interface VerificationMethod {
-  id: string;
-  type: string;
-  controller: string;
-  publicKeyJwk?: any; // JWK type
-  publicKeyBase58?: string;
-  publicKeyMultibase?: string;
-}
-
-/**
- * Status List Resolver interface
- */
-export interface StatusListResolver {
-  /**
-   * Check if a credential is revoked via StatusList2021
-   * @param status - The credential status entry
-   * @returns true if revoked, false otherwise
-   */
-  checkStatus(status: CredentialStatus): Promise<boolean>;
-}
-
-/**
- * Signature verification function interface
- *
- * Platform-specific implementations provide this function.
- */
-export interface SignatureVerificationFunction {
-  /**
-   * Verify an Ed25519 signature on a VC
-   *
-   * @param vc - The VC to verify
-   * @param publicKeyJwk - The public key in JWK format
-   * @returns Verification result
-   */
-  (vc: DelegationCredential, publicKeyJwk: any): Promise<{
-    valid: boolean;
-    reason?: string;
-  }>;
-}
-
-/**
- * Delegation Credential Verifier (Platform-Agnostic)
- *
- * Implements progressive enhancement pattern from Edge-Delegation-Verification.md:
- * 1. Fast basic checks (no network) - early rejection
- * 2. Parallel advanced checks (signature + status)
- * 3. Combined results
- */
-export class DelegationCredentialVerifier {
-  private didResolver?: DIDResolver;
-  private statusListResolver?: StatusListResolver;
-  private signatureVerifier?: SignatureVerificationFunction;
-  private cache = new Map<
-    string,
-    { result: DelegationVCVerificationResult; expiresAt: number }
-  >();
-  private cacheTtl: number;
-
-  constructor(options?: {
-    didResolver?: DIDResolver;
-    statusListResolver?: StatusListResolver;
-    signatureVerifier?: SignatureVerificationFunction;
-    cacheTtl?: number;
-  }) {
-    this.didResolver = options?.didResolver;
-    this.statusListResolver = options?.statusListResolver;
-    this.signatureVerifier = options?.signatureVerifier;
-    this.cacheTtl = options?.cacheTtl || 60_000; // 1 minute default
-  }
-
-  /**
-   * Verify a delegation credential with progressive enhancement
-   *
-   * Per Edge-Delegation-Verification.md:41-102
-   *
-   * @param vc - The delegation credential to verify
-   * @param options - Verification options
-   * @returns Verification result
-   */
-  async verifyDelegationCredential(
-    vc: DelegationCredential,
-    options: VerifyDelegationVCOptions = {}
-  ): Promise<DelegationVCVerificationResult> {
-    const startTime = Date.now();
-
-    // Check cache first
-    if (!options.skipCache) {
-      const cached = this.getFromCache(vc.id || '');
-      if (cached) {
-        return { ...cached, cached: true };
-      }
-    }
-
-    // ===================================================================
-    // STAGE 1: Fast Basic Checks (no network calls)
-    // Per Edge-Delegation-Verification.md:152-186
-    // ===================================================================
-    const basicCheckStart = Date.now();
-    const basicValidation = this.validateBasicProperties(vc);
-    const basicCheckMs = Date.now() - basicCheckStart;
-
-    if (!basicValidation.valid) {
-      const result: DelegationVCVerificationResult = {
-        valid: false,
-        reason: basicValidation.reason,
-        stage: 'basic',
-        metrics: {
-          basicCheckMs,
-          totalMs: Date.now() - startTime,
-        },
-        checks: {
-          basicValid: false,
-        },
-      };
-      return result;
-    }
-
-    // ===================================================================
-    // STAGE 2: Parallel Advanced Checks
-    // Per Edge-Delegation-Verification.md:281-301
-    // ===================================================================
-
-    // Start signature verification (if not skipped)
-    const signaturePromise = !options.skipSignature
-      ? this.verifySignature(vc, options.didResolver || this.didResolver)
-      : Promise.resolve<{
-          valid: boolean;
-          reason?: string;
-          durationMs?: number;
-        }>({
-          valid: true,
-          durationMs: 0,
-        });
-
-    // Start status checking (if not skipped)
-    const statusPromise =
-      !options.skipStatus && vc.credentialStatus
-        ? this.checkCredentialStatus(
-            vc.credentialStatus,
-            options.statusListResolver || this.statusListResolver
-          )
-        : Promise.resolve<{
-            valid: boolean;
-            reason?: string;
-            durationMs?: number;
-          }>({
-            valid: true,
-            durationMs: 0,
-          });
-
-    // Wait for both checks in parallel
-    const [signatureResult, statusResult] = await Promise.all([
-      signaturePromise,
-      statusPromise,
-    ]);
-
-    const signatureCheckMs = signatureResult.durationMs || 0;
-    const statusCheckMs = statusResult.durationMs || 0;
-
-    // ===================================================================
-    // STAGE 3: Combined Results
-    // Per Edge-Delegation-Verification.md:82-94
-    // ===================================================================
-
-    const allValid =
-      basicValidation.valid && signatureResult.valid && statusResult.valid;
-
-    const result: DelegationVCVerificationResult = {
-      valid: allValid,
-      reason: !allValid
-        ? signatureResult.reason || statusResult.reason || 'Unknown failure'
-        : undefined,
-      stage: 'complete',
-      metrics: {
-        basicCheckMs,
-        signatureCheckMs,
-        statusCheckMs,
-        totalMs: Date.now() - startTime,
-      },
-      checks: {
-        basicValid: basicValidation.valid,
-        signatureValid: signatureResult.valid,
-        statusValid: statusResult.valid,
-      },
-    };
-
-    // Cache successful verifications
-    if (result.valid && vc.id) {
-      this.setInCache(vc.id, result);
-    }
-
-    return result;
-  }
-
-  /**
-   * Stage 1: Validate basic properties (no network calls)
-   *
-   * Fast path for early rejection of invalid delegations.
-   * Per Edge-Delegation-Verification.md:155-186
-   *
-   * @param vc - The delegation credential
-   * @returns Validation result
-   */
-  private validateBasicProperties(
-    vc: DelegationCredential
-  ): { valid: boolean; reason?: string } {
-    // 1. Validate schema
-    const schemaValidation = validateDelegationCredential(vc);
-    if (!schemaValidation.success) {
-      return {
-        valid: false,
-        reason: `Schema validation failed: ${schemaValidation.error.message}`,
-      };
-    }
-
-    // 2. Check expiration
-    if (isDelegationCredentialExpired(vc)) {
-      return { valid: false, reason: 'Delegation credential expired' };
-    }
-
-    // 3. Check not yet valid
-    if (isDelegationCredentialNotYetValid(vc)) {
-      return { valid: false, reason: 'Delegation credential not yet valid' };
-    }
-
-    // 4. Check delegation status
-    const delegation = vc.credentialSubject.delegation;
-    if (delegation.status === 'revoked') {
-      return { valid: false, reason: 'Delegation status is revoked' };
-    }
-    if (delegation.status === 'expired') {
-      return { valid: false, reason: 'Delegation status is expired' };
-    }
-
-    // 5. Check required fields
-    if (!delegation.issuerDid || !delegation.subjectDid) {
-      return { valid: false, reason: 'Missing issuer or subject DID' };
-    }
-
-    // 6. Check proof exists (we'll verify it later)
-    if (!vc.proof) {
-      return { valid: false, reason: 'Missing proof' };
-    }
-
-    return { valid: true };
-  }
-
-  /**
-   * Stage 2a: Verify signature
-   *
-   * Per Edge-Delegation-Verification.md:191-234
-   *
-   * @param vc - The delegation credential
-   * @param didResolver - Optional DID resolver
-   * @returns Verification result
-   */
-  private async verifySignature(
-    vc: DelegationCredential,
-    didResolver?: DIDResolver
-  ): Promise<{ valid: boolean; reason?: string; durationMs?: number }> {
-    const startTime = Date.now();
-
-    try {
-      // Get issuer DID
-      const issuerDid =
-        typeof vc.issuer === 'string' ? vc.issuer : vc.issuer.id;
-
-      // If no DID resolver or signature verifier, skip verification
-      if (!didResolver || !this.signatureVerifier) {
-        return {
-          valid: true, // Trust but don't verify (no resolver/verifier available)
-          reason:
-            'No DID resolver or signature verifier available, skipping signature verification',
-          durationMs: Date.now() - startTime,
-        };
-      }
-
-      // Resolve issuer DID to get public key
-      const didDoc = await didResolver.resolve(issuerDid);
-      if (!didDoc) {
-        return {
-          valid: false,
-          reason: `Could not resolve issuer DID: ${issuerDid}`,
-          durationMs: Date.now() - startTime,
-        };
-      }
-
-      // Find verification method from proof
-      if (!vc.proof) {
-        return {
-          valid: false,
-          reason: 'Proof is missing',
-          durationMs: Date.now() - startTime,
-        };
-      }
-
-      const verificationMethodId = vc.proof.verificationMethod;
-      if (!verificationMethodId) {
-        return {
-          valid: false,
-          reason: 'Proof missing verificationMethod',
-          durationMs: Date.now() - startTime,
-        };
-      }
-
-      const verificationMethod = this.findVerificationMethod(
-        didDoc,
-        verificationMethodId
-      );
-      if (!verificationMethod) {
-        return {
-          valid: false,
-          reason: `Verification method ${verificationMethodId} not found`,
-          durationMs: Date.now() - startTime,
-        };
-      }
-
-      // Extract public key
-      const publicKeyJwk = verificationMethod.publicKeyJwk;
-      if (!publicKeyJwk) {
-        return {
-          valid: false,
-          reason: 'Verification method missing publicKeyJwk',
-          durationMs: Date.now() - startTime,
-        };
-      }
-
-      // Verify signature using platform-specific verifier
-      const verificationResult = await this.signatureVerifier(vc, publicKeyJwk);
-
-      return {
-        valid: verificationResult.valid,
-        reason: verificationResult.reason,
-        durationMs: Date.now() - startTime,
-      };
-    } catch (error) {
-      return {
-        valid: false,
-        reason: `Signature verification error: ${
-          error instanceof Error ? error.message : 'Unknown error'
-        }`,
-        durationMs: Date.now() - startTime,
-      };
-    }
-  }
-
-  /**
-   * Stage 2b: Check credential status via StatusList2021
-   *
-   * @param status - The credential status entry
-   * @param statusListResolver - Optional status list resolver
-   * @returns Status check result
-   */
-  private async checkCredentialStatus(
-    status: CredentialStatus,
-    statusListResolver?: StatusListResolver
-  ): Promise<{ valid: boolean; reason?: string; durationMs?: number }> {
-    const startTime = Date.now();
-
-    try {
-      // If no status list resolver, we can't check the status
-      if (!statusListResolver) {
-        return {
-          valid: true, // Trust but don't verify (no resolver available)
-          reason: 'No status list resolver available, skipping status check',
-          durationMs: Date.now() - startTime,
-        };
-      }
-
-      // Check if credential is revoked/suspended
-      const isRevoked = await statusListResolver.checkStatus(status);
-
-      if (isRevoked) {
-        return {
-          valid: false,
-          reason: `Credential revoked via StatusList2021 (${status.statusPurpose})`,
-          durationMs: Date.now() - startTime,
-        };
-      }
-
-      return {
-        valid: true,
-        durationMs: Date.now() - startTime,
-      };
-    } catch (error) {
-      return {
-        valid: false,
-        reason: `Status check error: ${
-          error instanceof Error ? error.message : 'Unknown error'
-        }`,
-        durationMs: Date.now() - startTime,
-      };
-    }
-  }
-
-  /**
-   * Find verification method in DID document
-   *
-   * @param didDoc - The DID document
-   * @param verificationMethodId - The verification method ID
-   * @returns Verification method or undefined
-   */
-  private findVerificationMethod(
-    didDoc: DIDDocument,
-    verificationMethodId: string
-  ): VerificationMethod | undefined {
-    return didDoc.verificationMethod?.find(
-      (vm) => vm.id === verificationMethodId
-    );
-  }
-
-  /**
-   * Get from cache
-   */
-  private getFromCache(id: string): DelegationVCVerificationResult | null {
-    const entry = this.cache.get(id);
-    if (!entry) return null;
-
-    if (Date.now() > entry.expiresAt) {
-      this.cache.delete(id);
-      return null;
-    }
-
-    return entry.result;
-  }
-
-  /**
-   * Set in cache
-   */
-  private setInCache(id: string, result: DelegationVCVerificationResult): void {
-    this.cache.set(id, {
-      result,
-      expiresAt: Date.now() + this.cacheTtl,
-    });
-  }
-
-  /**
-   * Clear cache
-   */
-  clearCache(): void {
-    this.cache.clear();
-  }
-
-  /**
-   * Clear cache entry for specific VC
-   */
-  clearCacheEntry(id: string): void {
-    this.cache.delete(id);
-  }
-}
-
-/**
- * Create a delegation credential verifier
- *
- * Convenience factory function.
- *
- * @param options - Verifier options
- * @returns DelegationCredentialVerifier instance
- */
-export function createDelegationVerifier(options?: {
-  didResolver?: DIDResolver;
-  statusListResolver?: StatusListResolver;
-  signatureVerifier?: SignatureVerificationFunction;
-  cacheTtl?: number;
-}): DelegationCredentialVerifier {
-  return new DelegationCredentialVerifier(options);
-}