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

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

@@ -0,0 +1,172 @@
+/**
+ * Tool Context Builder
+ *
+ * Builds ToolExecutionContext for tool handlers by resolving IDP tokens
+ * based on tool protection configuration and user identity.
+ *
+ * @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 { 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)
+   * @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
+    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;
+    }
+
+    // Resolve IDP token
+    const idpToken = await this.config.tokenResolver.resolveTokenFromDid(
+      userDid,
+      provider,
+      toolProtection.requiredScopes
+    );
+
+    if (!idpToken) {
+      // Token not available - throw OAuthRequiredError to trigger OAuth 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
+      // OAuth 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,
+      });
+    }
+
+    // Build context with token
+    const context: ToolExecutionContext = {
+      idpToken,
+      provider,
+      scopes: toolProtection.requiredScopes,
+      userDid,
+      sessionId,
+      delegationToken,
+    };
+
+    this.config.logger("[ToolContextBuilder] Context built successfully", {
+      toolName,
+      userDid: userDid.substring(0, 20) + "...",
+      provider,
+      hasToken: !!idpToken,
+    });
+
+    return context;
+  }
+
+  /**
+   * 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
+    }
+  }
+}
+