@kya-os/mcp-i-core 1.3.13 → 1.3.15

package/src/services/oauth-token-retrieval.service.ts

@@ -1,245 +0,0 @@
-/**
- * OAuth Token Retrieval Service
- *
- * Retrieves OAuth tokens from AgentShield after receiving delegation token.
- * Implements the two-step token flow for Phase 3 custom IDP support.
- *
- * @package @kya-os/mcp-i-core
- */
-
-import type { IdpTokens } from "@kya-os/contracts/config";
-
-/**
- * Configuration for OAuthTokenRetrievalService
- */
-export interface OAuthTokenRetrievalServiceConfig {
-  /** AgentShield API base URL */
-  baseUrl: string;
-  /** Fetch implementation */
-  fetchProvider: typeof fetch;
-  /** Optional logger callback */
-  logger?: (message: string, data?: any) => void;
-  /** Optional retry configuration */
-  retryConfig?: {
-    maxRetries?: number;
-    retryDelay?: number; // milliseconds
-    retryBackoff?: number; // multiplier for exponential backoff
-  };
-}
-
-/**
- * Response from AgentShield token retrieval endpoint
- */
-interface OAuthTokenRetrievalResponse {
-  success: true;
-  data: {
-    oauth_access_token: string;
-    oauth_refresh_token: string | null;
-    oauth_expires_at: string | null; // ISO 8601 datetime string
-    oauth_expires_in: number | null; // seconds
-    oauth_token_type: string;
-    oauth_scope: string | null;
-  };
-  metadata?: {
-    requestId?: string;
-    timestamp?: string; // ISO 8601
-  };
-}
-
-/**
- * Error response from AgentShield
- */
-interface OAuthTokenRetrievalErrorResponse {
-  success: false;
-  error: {
-    code: string;
-    message: string;
-    details?: any;
-  };
-}
-
-/**
- * Service for retrieving OAuth tokens from AgentShield
- */
-export class OAuthTokenRetrievalService {
-  private config: Required<OAuthTokenRetrievalServiceConfig> & {
-    retryConfig: Required<NonNullable<OAuthTokenRetrievalServiceConfig["retryConfig"]>>;
-  };
-
-  constructor(config: OAuthTokenRetrievalServiceConfig) {
-    const defaultRetryConfig = {
-      maxRetries: 3,
-      retryDelay: 1000,
-      retryBackoff: 2,
-    };
-
-    this.config = {
-      ...config,
-      logger: config.logger || (() => {}),
-      retryConfig: {
-        ...defaultRetryConfig,
-        ...config.retryConfig,
-      },
-    } as Required<OAuthTokenRetrievalServiceConfig> & {
-      retryConfig: Required<NonNullable<OAuthTokenRetrievalServiceConfig["retryConfig"]>>;
-    };
-  }
-
-  /**
-   * Retrieve OAuth tokens from AgentShield
-   *
-   * @param delegationId - Delegation ID from token exchange response
-   * @param delegationToken - Delegation token (JWT) for authorization
-   * @returns OAuth tokens mapped to IdpTokens format, or null if unavailable
-   */
-  async retrieveTokens(
-    delegationId: string,
-    delegationToken: string
-  ): Promise<IdpTokens | null> {
-    const endpoint = `${this.config.baseUrl}/api/v1/bouncer/delegations/${delegationId}/tokens`;
-
-    this.config.logger("[OAuthTokenRetrievalService] Retrieving OAuth tokens", {
-      delegationId,
-      endpoint,
-    });
-
-    let lastError: Error | null = null;
-    let attempt = 0;
-
-    // Retry logic for transient failures
-    while (attempt <= this.config.retryConfig.maxRetries) {
-      try {
-        const response = await this.config.fetchProvider(endpoint, {
-          method: "GET",
-          headers: {
-            Authorization: `Bearer ${delegationToken}`,
-            Accept: "application/json",
-          },
-        });
-
-        if (!response.ok) {
-          const errorData = await response.json().catch(() => ({})) as
-            | OAuthTokenRetrievalErrorResponse
-            | { error?: string; message?: string };
-
-          if (response.status === 404 || response.status === 401) {
-            // Token unavailable or unauthorized - don't retry
-            this.config.logger(
-              "[OAuthTokenRetrievalService] Tokens unavailable",
-              {
-                status: response.status,
-                delegationId,
-                error: errorData,
-              }
-            );
-            return null;
-          }
-
-          // Transient error - retry
-          const errorMessage =
-            (errorData as OAuthTokenRetrievalErrorResponse).error?.message ||
-            (errorData as any).error ||
-            (errorData as any).message ||
-            `HTTP ${response.status}`;
-
-          throw new Error(`Token retrieval failed: ${errorMessage}`);
-        }
-
-        const result = (await response.json()) as
-          | OAuthTokenRetrievalResponse
-          | OAuthTokenRetrievalErrorResponse;
-
-        if (!result.success) {
-          this.config.logger(
-            "[OAuthTokenRetrievalService] Token retrieval error response",
-            {
-              delegationId,
-              error: result.error,
-            }
-          );
-          return null;
-        }
-
-        // Map response to IdpTokens format
-        const tokens = this.mapToIdpTokens(result.data);
-
-        this.config.logger(
-          "[OAuthTokenRetrievalService] OAuth tokens retrieved successfully",
-          {
-            delegationId,
-            expiresAt: new Date(tokens.expires_at).toISOString(),
-            hasRefreshToken: !!tokens.refresh_token,
-          }
-        );
-
-        return tokens;
-      } catch (error) {
-        lastError = error instanceof Error ? error : new Error(String(error));
-
-        if (attempt < this.config.retryConfig.maxRetries) {
-          const delay =
-            this.config.retryConfig.retryDelay *
-            Math.pow(this.config.retryConfig.retryBackoff, attempt);
-
-          this.config.logger(
-            "[OAuthTokenRetrievalService] Retry attempt failed, retrying",
-            {
-              attempt: attempt + 1,
-              maxRetries: this.config.retryConfig.maxRetries,
-              delay,
-              error: lastError.message,
-            }
-          );
-
-          await new Promise((resolve) => setTimeout(resolve, delay));
-          attempt++;
-        } else {
-          // Max retries exceeded
-          this.config.logger(
-            "[OAuthTokenRetrievalService] Max retries exceeded",
-            {
-              delegationId,
-              error: lastError.message,
-              attempts: attempt + 1,
-            }
-          );
-          // Return null instead of throwing - delegation token still valid
-          return null;
-        }
-      }
-    }
-
-    return null;
-  }
-
-  /**
-   * Map AgentShield response to IdpTokens format
-   *
-   * @param data - Response data from AgentShield
-   * @returns IdpTokens object
-   */
-  private mapToIdpTokens(
-    data: OAuthTokenRetrievalResponse["data"]
-  ): IdpTokens {
-    // Convert ISO 8601 string to milliseconds timestamp
-    let expiresAt: number;
-    if (data.oauth_expires_at) {
-      expiresAt = new Date(data.oauth_expires_at).getTime();
-    } else if (data.oauth_expires_in) {
-      expiresAt = Date.now() + data.oauth_expires_in * 1000;
-    } else {
-      // Default to 1 hour if neither provided
-      expiresAt = Date.now() + 3600 * 1000;
-    }
-
-    return {
-      access_token: data.oauth_access_token,
-      refresh_token: data.oauth_refresh_token || undefined,
-      expires_in: data.oauth_expires_in || undefined,
-      expires_at: expiresAt,
-      token_type: data.oauth_token_type || "Bearer",
-      scope: data.oauth_scope || undefined,
-    };
-  }
-}
-

package/src/services/proof-verifier.ts

@@ -1,478 +0,0 @@
-/**
- * ProofVerifier
- *
- * Centralized proof verification service that validates DetachedProof
- * signatures, enforces nonce replay protection, and checks timestamp skew.
- */
-
-import { CryptoService, type Ed25519JWK } from "./crypto.service.js";
-import { CryptoProvider } from "../providers/base.js";
-import { ClockProvider } from "../providers/base.js";
-import { NonceCacheProvider } from "../providers/base.js";
-import { FetchProvider } from "../providers/base.js";
-import {
-  DetachedProofSchema,
-  type DetachedProof,
-} from "@kya-os/contracts/proof";
-import { canonicalize } from "json-canonicalize";
-import {
-  ProofVerificationError,
-  PROOF_VERIFICATION_ERROR_CODES,
-  type ProofVerificationErrorCode,
-} from "./errors.js";
-
-export interface ProofVerificationResult {
-  valid: boolean;
-  reason?: string;
-  error?: Error;
-  errorCode?: ProofVerificationErrorCode;
-  details?: Record<string, unknown>;
-}
-
-export interface ProofVerifierConfig {
-  cryptoProvider: CryptoProvider;
-  clockProvider: ClockProvider;
-  nonceCacheProvider: NonceCacheProvider;
-  fetchProvider: FetchProvider;
-  timestampSkewSeconds?: number;
-  nonceTtlSeconds?: number;
-}
-
-export class ProofVerifier {
-  private cryptoService: CryptoService;
-  private clock: ClockProvider;
-  private nonceCache: NonceCacheProvider;
-  private fetch: FetchProvider;
-  private timestampSkewSeconds: number;
-  private nonceTtlSeconds: number;
-
-  constructor(config: ProofVerifierConfig) {
-    this.cryptoService = new CryptoService(config.cryptoProvider);
-    this.clock = config.clockProvider;
-    this.nonceCache = config.nonceCacheProvider;
-    this.fetch = config.fetchProvider;
-    this.timestampSkewSeconds = config.timestampSkewSeconds ?? 120; // Default 2 minutes
-    this.nonceTtlSeconds = config.nonceTtlSeconds ?? 300; // Default 5 minutes
-  }
-
-  /**
-   * Verify a DetachedProof
-   * Automatically reconstructs canonical payload from proof.meta for signature verification
-   * @param proof - The proof to verify
-   * @param publicKeyJwk - Ed25519 public key in JWK format (from DID document)
-   * @returns Verification result
-   */
-  async verifyProof(
-    proof: DetachedProof,
-    publicKeyJwk: Ed25519JWK
-  ): Promise<ProofVerificationResult> {
-    try {
-      // 1. Validate proof structure
-      const structureValidation = await this.validateProofStructure(proof);
-      if (!structureValidation.valid) {
-        return structureValidation;
-      }
-      const validatedProof = structureValidation.proof!;
-
-      // 2. Check nonce replay protection (scoped to agent DID to prevent cross-agent replay attacks)
-      const nonceValidation = await this.validateNonce(
-        validatedProof.meta.nonce,
-        validatedProof.meta.did
-      );
-      if (!nonceValidation.valid) {
-        return nonceValidation;
-      }
-
-      // 3. Check timestamp skew
-      const timestampValidation = await this.validateTimestamp(
-        validatedProof.meta.ts
-      );
-      if (!timestampValidation.valid) {
-        return timestampValidation;
-      }
-
-      // 4. Reconstruct canonical payload from proof meta
-      const canonicalPayloadString = this.buildCanonicalPayload(
-        validatedProof.meta
-      );
-      const canonicalPayloadBytes = new TextEncoder().encode(
-        canonicalPayloadString
-      );
-
-      // 5. Verify JWS signature with detached canonical payload
-      const signatureValidation = await this.verifySignature(
-        validatedProof.jws,
-        publicKeyJwk,
-        canonicalPayloadBytes,
-        validatedProof.meta.kid
-      );
-      if (!signatureValidation.valid) {
-        return signatureValidation;
-      }
-
-      // 6. Add nonce to cache to prevent replay (scoped to agent DID)
-      await this.addNonceToCache(
-        validatedProof.meta.nonce,
-        validatedProof.meta.did
-      );
-
-      return {
-        valid: true,
-      };
-    } catch (error) {
-      // Security-safe failure: never throw, always return error result
-      return {
-        valid: false,
-        reason: "Proof verification error",
-        errorCode: PROOF_VERIFICATION_ERROR_CODES.VERIFICATION_ERROR,
-        error: error instanceof Error ? error : new Error(String(error)),
-        details: {
-          errorMessage: error instanceof Error ? error.message : String(error),
-        },
-      };
-    }
-  }
-
-  /**
-   * Verify proof with detached payload (for CLI/verifier compatibility)
-   * @param proof - The proof to verify
-   * @param canonicalPayload - Canonical JSON payload (for detached JWS) as string or Uint8Array
-   * @param publicKeyJwk - Ed25519 public key in JWK format
-   * @returns Verification result
-   */
-  async verifyProofDetached(
-    proof: DetachedProof,
-    canonicalPayload: string | Uint8Array,
-    publicKeyJwk: Ed25519JWK
-  ): Promise<ProofVerificationResult> {
-    try {
-      // 1. Validate proof structure
-      const structureValidation = await this.validateProofStructure(proof);
-      if (!structureValidation.valid) {
-        return structureValidation;
-      }
-      const validatedProof = structureValidation.proof!;
-
-      // 2. Check nonce replay protection (scoped to agent DID to prevent cross-agent replay attacks)
-      const nonceValidation = await this.validateNonce(
-        validatedProof.meta.nonce,
-        validatedProof.meta.did
-      );
-      if (!nonceValidation.valid) {
-        return nonceValidation;
-      }
-
-      // 3. Check timestamp skew
-      const timestampValidation = await this.validateTimestamp(
-        validatedProof.meta.ts
-      );
-      if (!timestampValidation.valid) {
-        return timestampValidation;
-      }
-
-      // 4. Convert canonical payload to Uint8Array if needed
-      const canonicalPayloadBytes =
-        canonicalPayload instanceof Uint8Array
-          ? canonicalPayload
-          : new TextEncoder().encode(canonicalPayload);
-
-      // 5. Verify JWS signature with detached payload
-      const signatureValidation = await this.verifySignature(
-        validatedProof.jws,
-        publicKeyJwk,
-        canonicalPayloadBytes,
-        validatedProof.meta.kid
-      );
-      if (!signatureValidation.valid) {
-        return signatureValidation;
-      }
-
-      // 6. Add nonce to cache (scoped to agent DID)
-      await this.addNonceToCache(
-        validatedProof.meta.nonce,
-        validatedProof.meta.did
-      );
-
-      return {
-        valid: true,
-      };
-    } catch (error) {
-      // Security-safe failure: never throw, always return error result
-      return {
-        valid: false,
-        reason: "Proof verification error",
-        errorCode: PROOF_VERIFICATION_ERROR_CODES.VERIFICATION_ERROR,
-        error: error instanceof Error ? error : new Error(String(error)),
-        details: {
-          errorMessage: error instanceof Error ? error.message : String(error),
-        },
-      };
-    }
-  }
-
-  /**
-   * Validate proof structure using Zod schema
-   * @private
-   */
-  private async validateProofStructure(
-    proof: DetachedProof
-  ): Promise<ProofVerificationResult & { proof?: DetachedProof }> {
-    const validationResult = DetachedProofSchema.safeParse(proof);
-    if (!validationResult.success) {
-      return {
-        valid: false,
-        reason: "Invalid proof structure",
-        errorCode: PROOF_VERIFICATION_ERROR_CODES.INVALID_PROOF_STRUCTURE,
-        error: new Error(
-          `Proof validation failed: ${validationResult.error.message}`
-        ),
-        details: {
-          zodErrors: validationResult.error.errors,
-        },
-      };
-    }
-    return {
-      valid: true,
-      proof: validationResult.data,
-    };
-  }
-
-  /**
-   * Validate nonce replay protection
-   * @private
-   */
-  private async validateNonce(
-    nonce: string,
-    agentDid?: string
-  ): Promise<ProofVerificationResult> {
-    const nonceUsed = await this.nonceCache.has(nonce, agentDid);
-    if (nonceUsed) {
-      return {
-        valid: false,
-        reason: "Nonce already used (replay attack detected)",
-        errorCode: PROOF_VERIFICATION_ERROR_CODES.NONCE_REPLAY_DETECTED,
-        details: {
-          nonce,
-          agentDid,
-        },
-      };
-    }
-    return { valid: true };
-  }
-
-  /**
-   * Validate timestamp skew
-   * @private
-   */
-  private async validateTimestamp(
-    timestamp: number
-  ): Promise<ProofVerificationResult> {
-    // Convert seconds to milliseconds for clock provider (which uses Date.now())
-    const timestampMs = timestamp * 1000;
-    if (!this.clock.isWithinSkew(timestampMs, this.timestampSkewSeconds)) {
-      return {
-        valid: false,
-        reason: `Timestamp out of skew window (skew: ${this.timestampSkewSeconds}s)`,
-        errorCode: PROOF_VERIFICATION_ERROR_CODES.TIMESTAMP_SKEW_EXCEEDED,
-        details: {
-          timestamp,
-          timestampMs,
-          skewSeconds: this.timestampSkewSeconds,
-          currentTime: this.clock.now(),
-        },
-      };
-    }
-    return { valid: true };
-  }
-
-  /**
-   * Verify JWS signature
-   * @private
-   */
-  private async verifySignature(
-    jws: string,
-    publicKeyJwk: Ed25519JWK,
-    canonicalPayloadBytes: Uint8Array,
-    expectedKid?: string
-  ): Promise<ProofVerificationResult> {
-    const signatureValid = await this.cryptoService.verifyJWS(
-      jws,
-      publicKeyJwk,
-      {
-        detachedPayload: canonicalPayloadBytes,
-        expectedKid,
-        alg: "EdDSA",
-      }
-    );
-
-    if (!signatureValid) {
-      return {
-        valid: false,
-        reason: "Invalid JWS signature",
-        errorCode: PROOF_VERIFICATION_ERROR_CODES.INVALID_JWS_SIGNATURE,
-        details: {
-          jwsLength: jws.length,
-          expectedKid,
-          actualKid: publicKeyJwk.kid,
-        },
-      };
-    }
-
-    return { valid: true };
-  }
-
-  /**
-   * Add nonce to cache to prevent replay (scoped to agent DID)
-   * @private
-   */
-  private async addNonceToCache(
-    nonce: string,
-    agentDid: string
-  ): Promise<void> {
-    // Pass TTL in seconds, not absolute timestamp
-    await this.nonceCache.add(nonce, this.nonceTtlSeconds, agentDid);
-  }
-
-  /**
-   * Fetch public key from DID document
-   * @param did - DID to resolve
-   * @param kid - Key ID (optional, defaults to first verification method)
-   * @returns Ed25519 JWK or null if not found
-   * @throws {ProofVerificationError} If DID resolution fails with specific error code
-   */
-  async fetchPublicKeyFromDID(
-    did: string,
-    kid?: string
-  ): Promise<Ed25519JWK | null> {
-    try {
-      const didDoc = await this.fetch.resolveDID(did);
-
-      if (!didDoc) {
-        throw new ProofVerificationError(
-          PROOF_VERIFICATION_ERROR_CODES.DID_DOCUMENT_NOT_FOUND,
-          `DID document not found: ${did}`,
-          { did }
-        );
-      }
-
-      if (
-        !didDoc.verificationMethod ||
-        didDoc.verificationMethod.length === 0
-      ) {
-        throw new ProofVerificationError(
-          PROOF_VERIFICATION_ERROR_CODES.VERIFICATION_METHOD_NOT_FOUND,
-          `No verification methods found in DID document: ${did}`,
-          { did }
-        );
-      }
-
-      // Find verification method by kid or use first one
-      let verificationMethod:
-        | { id: string; publicKeyJwk?: unknown }
-        | undefined;
-      if (kid) {
-        const kidWithHash = kid.startsWith("#") ? kid : `#${kid}`;
-        verificationMethod = didDoc.verificationMethod.find(
-          (vm: { id: string }) =>
-            vm.id === kidWithHash || vm.id === `${did}${kidWithHash}`
-        );
-
-        if (!verificationMethod) {
-          throw new ProofVerificationError(
-            PROOF_VERIFICATION_ERROR_CODES.VERIFICATION_METHOD_NOT_FOUND,
-            `Verification method not found for kid: ${kid}`,
-            {
-              did,
-              kid,
-              availableKids: didDoc.verificationMethod.map(
-                (vm: { id: string }) => vm.id
-              ),
-            }
-          );
-        }
-      } else {
-        verificationMethod = didDoc.verificationMethod[0];
-      }
-
-      if (!verificationMethod?.publicKeyJwk) {
-        throw new ProofVerificationError(
-          PROOF_VERIFICATION_ERROR_CODES.PUBLIC_KEY_NOT_FOUND,
-          `Public key JWK not found in verification method`,
-          { did, kid, verificationMethodId: verificationMethod?.id }
-        );
-      }
-
-      const jwk = verificationMethod.publicKeyJwk as {
-        kty?: string;
-        crv?: string;
-        x?: string;
-        [key: string]: unknown;
-      };
-
-      // Validate it's an Ed25519 key
-      if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || !jwk.x) {
-        throw new ProofVerificationError(
-          PROOF_VERIFICATION_ERROR_CODES.INVALID_JWK_FORMAT,
-          `Unsupported key type or curve: kty=${jwk.kty}, crv=${jwk.crv}`,
-          { did, kid, jwk: { kty: jwk.kty, crv: jwk.crv } }
-        );
-      }
-
-      return jwk as Ed25519JWK;
-    } catch (error) {
-      if (error instanceof ProofVerificationError) {
-        throw error;
-      }
-      console.error(
-        "[ProofVerifier] Failed to fetch public key from DID:",
-        error
-      );
-      throw new ProofVerificationError(
-        PROOF_VERIFICATION_ERROR_CODES.DID_RESOLUTION_FAILED,
-        `DID resolution failed: ${error instanceof Error ? error.message : String(error)}`,
-        {
-          did,
-          kid,
-          originalError: error instanceof Error ? error.message : String(error),
-        }
-      );
-    }
-  }
-
-  /**
-   * Build canonical payload from proof meta
-   *
-   * CRITICAL: This must reconstruct the exact JWS payload structure that was originally signed.
-   * The original JWS payload uses standard JWT claims (aud, sub, iss) plus custom proof claims,
-   * NOT the proof.meta structure directly.
-   *
-   * @param meta - Proof metadata
-   * @returns Canonical JSON string matching the original JWS payload structure
-   */
-  buildCanonicalPayload(meta: DetachedProof["meta"]): string {
-    // Reconstruct the original JWS payload structure that was signed
-    // This matches the structure used in proof generation (proof.ts, proof-generator.ts)
-    const payload = {
-      // Standard JWT claims (RFC 7519) - these are what was actually signed
-      aud: meta.audience, // Audience (who the token is for)
-      sub: meta.did, // Subject (agent DID)
-      iss: meta.did, // Issuer (agent DID - self-issued)
-
-      // Custom MCP-I proof claims
-      requestHash: meta.requestHash,
-      responseHash: meta.responseHash,
-      ts: meta.ts,
-      nonce: meta.nonce,
-      sessionId: meta.sessionId,
-
-      // Optional claims (only include if present)
-      ...(meta.scopeId && { scopeId: meta.scopeId }),
-      ...(meta.delegationRef && { delegationRef: meta.delegationRef }),
-      ...(meta.clientDid && { clientDid: meta.clientDid }),
-    };
-
-    // Canonicalize the reconstructed payload using the same function as proof generation
-    // CRITICAL: Must use json-canonicalize canonicalize() to match proof.ts exactly
-    return canonicalize(payload);
-  }
-}