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

package/src/services/tool-context-builder.ts

@@ -1,237 +0,0 @@
-/**
- * Tool Context Builder
- *
- * Builds ToolExecutionContext for tool handlers by resolving IDP tokens
- * based on tool protection configuration and user identity.
- *
- * Updated for CRED-003: Builds idpHeaders based on tokenUsage metadata
- * to support credential providers with custom token usage patterns.
- *
- * @package @kya-os/mcp-i-core
- */
-
-import type { ToolExecutionContext } from "@kya-os/contracts/config";
-import type { IdpTokenResolver } from "../identity/idp-token-resolver.js";
-import type { IdpTokensWithMetadata } from "../identity/idp-token-storage.interface.js";
-import type { ToolProtection } from "../types/tool-protection.js";
-import type { OAuthConfigService } from "./oauth-config.service.js";
-import type { ProviderResolver } from "./provider-resolver.js";
-import { OAuthRequiredError } from "../types/oauth-required-error.js";
-
-export interface ToolContextBuilderConfig {
-  /** IDP token resolver for resolving tokens from User DID */
-  tokenResolver: IdpTokenResolver;
-
-  /** OAuth config service for fetching provider configurations */
-  configService: OAuthConfigService;
-
-  /** Provider resolver for resolving OAuth providers for tools */
-  providerResolver: ProviderResolver;
-
-  /** Project ID for fetching OAuth config */
-  projectId: string;
-
-  /** Optional logger callback for diagnostics */
-  logger?: (message: string, data?: unknown) => void;
-}
-
-/**
- * Builder for tool execution context
- *
- * Resolves IDP tokens and builds context for tool handlers.
- * Phase 1: Uses configured provider as temporary fallback.
- * Phase 2+: Requires explicit oauthProvider on tool protection.
- */
-export class ToolContextBuilder {
-  private config: Required<Omit<ToolContextBuilderConfig, "logger">> & {
-    logger: (message: string, data?: unknown) => void;
-  };
-
-  constructor(config: ToolContextBuilderConfig) {
-    this.config = {
-      tokenResolver: config.tokenResolver,
-      configService: config.configService,
-      providerResolver: config.providerResolver,
-      projectId: config.projectId,
-      logger: config.logger || (() => {}),
-    };
-  }
-
-  /**
-   * Build tool execution context
-   *
-   * @param toolName - Name of the tool being executed
-   * @param userDid - User DID (optional, required for OAuth/credentials)
-   * @param sessionId - Session ID (optional)
-   * @param delegationToken - Delegation token (optional)
-   * @param toolProtection - Tool protection configuration (optional)
-   * @returns Tool execution context or undefined if not needed
-   */
-  async buildContext(
-    toolName: string,
-    userDid: string | undefined,
-    sessionId: string | undefined,
-    delegationToken: string | undefined,
-    toolProtection: ToolProtection | null
-  ): Promise<ToolExecutionContext | undefined> {
-    // Only build context if tool requires OAuth/credentials
-    if (!toolProtection?.requiredScopes?.length || !userDid) {
-      return undefined;
-    }
-
-    // Phase 2: Resolve provider using ProviderResolver
-    // ProviderResolver handles priority-based resolution with fallbacks
-    let provider: string;
-    try {
-      provider = await this.resolveProvider(toolProtection);
-    } catch (error) {
-      // Provider resolution failed - cannot build context
-      this.config.logger("[ToolContextBuilder] Provider not resolved", {
-        toolName,
-        userDid: userDid.substring(0, 20) + "...",
-        error: error instanceof Error ? error.message : String(error),
-      });
-      return undefined;
-    }
-
-    // CRED-003: Resolve full token data (not just access_token)
-    // This includes tokenUsage, cookieFormat, apiHeaders for credential providers
-    const tokenData = await this.config.tokenResolver.resolveTokenDataFromDid(
-      userDid,
-      provider,
-      toolProtection.requiredScopes
-    );
-
-    if (!tokenData) {
-      // Token not available - throw OAuthRequiredError to trigger auth flow
-      this.config.logger("[ToolContextBuilder] Token not available, throwing OAuthRequiredError", {
-        toolName,
-        userDid: userDid.substring(0, 20) + "...",
-        provider,
-        scopes: toolProtection.requiredScopes,
-      });
-      
-      // Throw error with provider and scopes info
-      // Auth URL will be built by the Cloudflare layer (agent.ts)
-      throw new OAuthRequiredError({
-        toolName,
-        requiredScopes: toolProtection.requiredScopes,
-        provider,
-        oauthUrl: "", // Will be populated by Cloudflare layer
-        userDid,
-        sessionId,
-      });
-    }
-
-    // CRED-003: Build headers based on tokenUsage
-    const idpHeaders = this.buildAuthHeaders(tokenData);
-
-    // Build context with token and headers
-    const context: ToolExecutionContext = {
-      idpToken: tokenData.access_token,
-      idpHeaders,
-      provider,
-      scopes: toolProtection.requiredScopes,
-      userDid,
-      sessionId,
-      delegationToken,
-    };
-
-    this.config.logger("[ToolContextBuilder] Context built successfully", {
-      toolName,
-      userDid: userDid.substring(0, 20) + "...",
-      provider,
-      hasToken: !!tokenData.access_token,
-      tokenUsage: tokenData.tokenUsage,
-      headerKeys: Object.keys(idpHeaders),
-    });
-
-    return context;
-  }
-
-  /**
-   * Build authentication headers based on token usage metadata (CRED-003)
-   *
-   * Supports three modes:
-   * - "cookie": Cookie header (with optional cookieFormat template)
-   * - "bearer": Authorization: Bearer xxx
-   * - "header": Custom header name
-   *
-   * Also includes any apiHeaders from provider config.
-   *
-   * @param tokenData - Token data with usage metadata
-   * @returns Headers object for API calls
-   */
-  private buildAuthHeaders(tokenData: IdpTokensWithMetadata): Record<string, string> {
-    const authHeaders: Record<string, string> = {};
-
-    const tokenUsage = tokenData.tokenUsage || "bearer"; // Default to bearer for OAuth
-    const token = tokenData.access_token;
-
-    switch (tokenUsage) {
-      case "cookie":
-        // Use cookieFormat if specified, otherwise send raw token
-        if (tokenData.cookieFormat) {
-          authHeaders["Cookie"] = tokenData.cookieFormat.replace(
-            /\{\{token\}\}/g,
-            token
-          );
-        } else {
-          authHeaders["Cookie"] = token;
-        }
-        break;
-
-      case "bearer":
-        authHeaders["Authorization"] = `Bearer ${token}`;
-        break;
-
-      case "header":
-        const headerName = tokenData.tokenHeader || "X-Session-Token";
-        authHeaders[headerName] = token;
-        break;
-
-      default:
-        // Unknown usage - default to bearer
-        authHeaders["Authorization"] = `Bearer ${token}`;
-    }
-
-    // Add any additional API headers from provider config
-    if (tokenData.apiHeaders) {
-      Object.assign(authHeaders, tokenData.apiHeaders);
-    }
-
-    return authHeaders;
-  }
-
-  /**
-   * Resolve OAuth provider for a tool
-   *
-   * Phase 2: Uses ProviderResolver with priority-based resolution
-   *
-   * @param toolProtection - Tool protection configuration
-   * @returns Provider name or throws error if not found
-   */
-  private async resolveProvider(
-    toolProtection: ToolProtection
-  ): Promise<string> {
-    try {
-      const provider = await this.config.providerResolver.resolveProvider(
-        toolProtection,
-        this.config.projectId
-      );
-
-      this.config.logger("[ToolContextBuilder] Provider resolved", {
-        provider,
-      });
-
-      return provider;
-    } catch (error) {
-      this.config.logger("[ToolContextBuilder] Provider resolution failed", {
-        error: error instanceof Error ? error.message : String(error),
-        projectId: this.config.projectId,
-      });
-      throw error; // Re-throw to let caller handle
-    }
-  }
-}
-