@kya-os/mcp-i-core 1.2.3-canary.6 → 1.3.0

package/src/delegation/vc-verifier.ts

@@ -0,0 +1,568 @@
+/**
+ * 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);
+}

package/src/identity/idp-token-resolver.ts

@@ -0,0 +1,147 @@
+/**
+ * IDP Token Resolver
+ *
+ * Resolves User DID to IDP access token (MH-7 requirement).
+ * Handles token lookup, expiration checking, and automatic refresh.
+ *
+ * @package @kya-os/mcp-i-core
+ */
+
+import type { IdpTokens } from "@kya-os/contracts/config";
+import type { IIdpTokenStorage } from "./idp-token-storage.interface.js";
+
+export interface IdpTokenResolverConfig {
+  /** Token storage implementation */
+  tokenStorage: IIdpTokenStorage;
+
+  /** OAuth service for token refresh */
+  oauthService: {
+    refreshToken(provider: string, refreshToken: string): Promise<IdpTokens | null>;
+  };
+
+  /** Optional logger callback for diagnostics */
+  logger?: (message: string, data?: unknown) => void;
+}
+
+/**
+ * Service for resolving User DID to IDP access token
+ *
+ * MH-7 Requirement: resolveTokenFromDid(userDid: string): Promise<string>
+ *
+ * This service implements the core MH-7 functionality:
+ * - Resolves User DID to IDP access token
+ * - Handles token expiration and automatic refresh
+ * - Supports multiple IDP providers
+ */
+export class IdpTokenResolver {
+  private config: Required<Omit<IdpTokenResolverConfig, "logger">> & {
+    logger: (message: string, data?: unknown) => void;
+  };
+
+  constructor(config: IdpTokenResolverConfig) {
+    this.config = {
+      tokenStorage: config.tokenStorage,
+      oauthService: config.oauthService,
+      logger: config.logger || (() => {}),
+    };
+  }
+
+  /**
+   * Resolve User DID to IDP access token
+   *
+   * MH-7 Requirement: resolveTokenFromDid(userDid: string): Promise<string>
+   *
+   * Flow:
+   * 1. Look up token from storage
+   * 2. Check expiration
+   * 3. Auto-refresh if expired and refresh_token available
+   * 4. Update storage after refresh
+   * 5. Return access_token or null
+   *
+   * @param userDid - User DID to resolve
+   * @param provider - OAuth provider name (e.g., "github", "google")
+   * @param scopes - Required scopes for token
+   * @returns Access token or null if not found/expired
+   */
+  async resolveTokenFromDid(
+    userDid: string,
+    provider: string,
+    scopes: string[]
+  ): Promise<string | null> {
+    // 1. Look up token from storage
+    const storedToken = await this.config.tokenStorage.getToken(
+      userDid,
+      provider,
+      scopes
+    );
+
+    if (!storedToken) {
+      this.config.logger("[IdpTokenResolver] Token not found", {
+        userDid: userDid.substring(0, 20) + "...",
+        provider,
+        scopes,
+      });
+      return null;
+    }
+
+    // 2. Check expiration
+    const now = Date.now();
+    if (storedToken.expires_at < now) {
+      this.config.logger("[IdpTokenResolver] Token expired, attempting refresh", {
+        userDid: userDid.substring(0, 20) + "...",
+        provider,
+        expiresAt: new Date(storedToken.expires_at).toISOString(),
+        hasRefreshToken: !!storedToken.refresh_token,
+      });
+
+      // 3. Refresh if refresh_token available
+      if (storedToken.refresh_token) {
+        const refreshed = await this.config.oauthService.refreshToken(
+          provider,
+          storedToken.refresh_token
+        );
+
+        if (refreshed) {
+          // 4. Update storage with new tokens
+          await this.config.tokenStorage.storeToken(
+            userDid,
+            provider,
+            scopes,
+            refreshed
+          );
+
+          this.config.logger("[IdpTokenResolver] Token refreshed successfully", {
+            userDid: userDid.substring(0, 20) + "...",
+            provider,
+            expiresAt: new Date(refreshed.expires_at).toISOString(),
+          });
+
+          // 5. Return new access_token
+          return refreshed.access_token;
+        } else {
+          this.config.logger("[IdpTokenResolver] Token refresh failed", {
+            userDid: userDid.substring(0, 20) + "...",
+            provider,
+          });
+          return null;
+        }
+      } else {
+        this.config.logger("[IdpTokenResolver] Token expired and no refresh token", {
+          userDid: userDid.substring(0, 20) + "...",
+          provider,
+        });
+        return null;
+      }
+    }
+
+    // 4. Return valid access_token
+    this.config.logger("[IdpTokenResolver] Token resolved successfully", {
+      userDid: userDid.substring(0, 20) + "...",
+      provider,
+      expiresAt: new Date(storedToken.expires_at).toISOString(),
+    });
+
+    return storedToken.access_token;
+  }
+}
+