@kya-os/mcp-i-core 1.2.3-canary.7 → 1.3.1

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

@@ -0,0 +1,245 @@
+/**
+ * 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

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