@kya-os/mcp-i-core 1.7.0 → 1.8.1

package/dist/services/tool-context-builder.js

@@ -1,215 +0,0 @@
-"use strict";
-/**
- * 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
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolContextBuilder = void 0;
-const oauth_required_error_js_1 = require("../types/oauth-required-error.js");
-const provider_resolver_js_1 = require("./provider-resolver.js");
-/**
- * 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.
- */
-class ToolContextBuilder {
-    config;
-    constructor(config) {
-        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, userDid, sessionId, delegationToken, toolProtection) {
-        // 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;
-        try {
-            provider = await this.resolveProvider(toolProtection);
-        }
-        catch (error) {
-            // ConsentOnlyModeError and CredentialAuthModeError are NOT errors
-            // They're signals about what auth flow to use - re-throw for caller to handle
-            if (error instanceof provider_resolver_js_1.ConsentOnlyModeError ||
-                error instanceof provider_resolver_js_1.CredentialAuthModeError) {
-                this.config.logger("[ToolContextBuilder] Special auth mode detected, re-throwing", {
-                    toolName,
-                    errorType: error.name,
-                    message: error.message,
-                });
-                throw error;
-            }
-            // Other provider resolution errors - 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) {
-            // IDP token not available - check if delegation token exists
-            // If delegation exists, tool can still execute without IDP token
-            // (the tool handler should check for idpToken if it needs external API access)
-            if (delegationToken) {
-                this.config.logger("[ToolContextBuilder] IDP token not found, but delegation exists - returning minimal context", {
-                    toolName,
-                    userDid: userDid.substring(0, 20) + "...",
-                    provider,
-                    scopes: toolProtection.requiredScopes,
-                    note: "Tool can execute with delegation-only authorization",
-                });
-                // Return minimal context with delegation info
-                // Tools that need IDP token for external API calls should check for idpToken
-                return {
-                    provider,
-                    scopes: toolProtection.requiredScopes,
-                    userDid,
-                    sessionId,
-                    delegationToken,
-                };
-            }
-            // No delegation token either - 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 oauth_required_error_js_1.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
-        // Include userId from token metadata (extracted from credential provider response)
-        const context = {
-            idpToken: tokenData.access_token,
-            idpHeaders,
-            provider,
-            scopes: toolProtection.requiredScopes,
-            userDid,
-            sessionId,
-            delegationToken,
-            // CRED-003: Include userId from credential provider's extracted user ID
-            userId: tokenData.userId,
-        };
-        this.config.logger("[ToolContextBuilder] Context built successfully", {
-            toolName,
-            userDid: userDid.substring(0, 20) + "...",
-            provider,
-            hasToken: !!tokenData.access_token,
-            hasUserId: !!tokenData.userId,
-            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
-     */
-    buildAuthHeaders(tokenData) {
-        const authHeaders = {};
-        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
-     */
-    async resolveProvider(toolProtection) {
-        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
-        }
-    }
-}
-exports.ToolContextBuilder = ToolContextBuilder;
-//# sourceMappingURL=tool-context-builder.js.map

package/dist/services/tool-protection.service.d.ts

@@ -1,193 +0,0 @@
-/**
- * ToolProtectionService - Fetches and caches tool protection configurations
- *
- * This service manages tool protection configuration from AgentShield API with
- * efficient caching and automatic synchronization support.
- *
- * CONFIGURATION PRECEDENCE (highest to lowest):
- * ---------------------------------------------
- * 1. Remote config (AgentShield API) - WINS (source of truth)
- * 2. Local config (localConfig) - Base defaults, overridden by remote
- * 3. Framework defaults
- *
- * OFFLINE FALLBACK (only when API unavailable):
- * ---------------------------------------------
- * 1. Stale cache (if allowStaleCache=true and within maxStaleCacheAge)
- * 2. offlineFallbackConfig (explicit offline-only config)
- * 3. failSafeBehavior (deny-all or allow-all)
- *
- * CORE FUNCTIONALITY:
- * -------------------
- * 1. Fetches tool protection config from AgentShield API (remote wins)
- * 2. Merges with local config (local serves as base defaults)
- * 3. Caches responses with configurable TTL (default 5 minutes)
- * 4. Provides delegation requirement checking before tool execution
- *
- * SYNCHRONIZATION WITH AGENTSHIELD:
- * ----------------------------------
- * When you update tool protection settings in the AgentShield dashboard:
- *
- * 1. Dashboard sends PATCH /api/internal/bouncer/tools/{projectId}/{toolName}
- * 2. AgentShield updates the database immediately (PostgreSQL JSONB column)
- * 3. Dashboard sends POST /admin/clear-cache to this service (automatic)
- * 4. This service clears the cached config from KV storage
- * 5. Next tool call fetches fresh config from AgentShield API
- * 6. New config is cached for the configured TTL period
- *
- * CACHE INVALIDATION:
- * -------------------
- * Cache is invalidated via POST /admin/clear-cache endpoint:
- * - Triggered automatically by AgentShield dashboard when tool protection changes
- * - Can be triggered manually for testing/debugging
- * - Requires API key authentication for security
- *
- * If cache is NOT cleared:
- * - Stale config is served until TTL expires (default 5 minutes)
- * - Configure shorter TTL via TOOL_PROTECTION_CACHE_TTL env var for faster updates
- * - Set to 0 for no cache (not recommended for production)
- *
- * TOOL DISCOVERY PREREQUISITE:
- * ----------------------------
- * IMPORTANT: Tools must be discovered before they can be protected!
- *
- * Discovery happens when:
- * - Agent makes first tool call with proof submission
- * - AgentShield extracts tool info from cryptographic proof
- * - Tool is added to bouncerConfigs.discoveredTools in database
- *
- * If tool not discovered:
- * - Tool won't appear in dashboard
- * - Protection settings can't be configured
- * - GET /config returns empty toolProtection.tools object
- *
- * DEBUGGING:
- * ----------
- * Enable debug logging with:
- *   toolProtection: { debug: true }
- *
- * Debug logs show:
- * - Cache hits vs API fetches
- * - Full API responses
- * - Tool protection status for each tool
- * - Cache TTL and expiration times
- * - Source of config data (cache, api, or fallback)
- *
- * TROUBLESHOOTING:
- * ----------------
- * Problem: Dashboard shows protection but tool still executes
- * Cause: Stale cache not invalidated
- * Solution: POST /admin/clear-cache or wait for TTL expiration
- *
- * Problem: Empty toolProtections returned from API
- * Cause: Tool not discovered yet (no proof submissions)
- * Solution: Make at least one tool call to trigger discovery
- *
- * Problem: Updates take 5+ minutes to apply
- * Cause: Long cache TTL and cache clear failed
- * Solution: Configure MCP server URL in AgentShield for auto cache clear
- *
- * @see https://github.com/modelcontextprotocol-identity/agent-shield/docs/bouncer/tool-protection-sync.md
- * @package @kya-os/mcp-i-core
- */
-import type { ToolProtection, ToolProtectionConfig, ToolProtectionServiceConfig } from "../types/tool-protection.js";
-import type { ToolProtectionCache } from "../cache/tool-protection-cache.js";
-/**
- * Service for fetching and checking tool protection configurations
- */
-export declare class ToolProtectionService {
-    private config;
-    private cache;
-    constructor(config: ToolProtectionServiceConfig, cache: ToolProtectionCache);
-    /**
-     * Get the project ID from the service configuration
-     * @returns Project ID or undefined if not configured
-     */
-    getProjectId(): string | undefined;
-    /**
-     * Get stale cache entry if available and within maxStaleCacheAge
-     * Only works with InMemoryToolProtectionCache (has internal access to expiresAt)
-     *
-     * NOTE: This checks stale cache BEFORE calling cache.get() to avoid deletion of expired entries
-     *
-     * @param cacheKey Cache key to check
-     * @returns Stale cache entry or null if not available/too old
-     */
-    private getStaleCache;
-    /**
-     * Get tool protection configuration for the agent
-     *
-     * Flow:
-     * 1. Check cache (project-scoped if projectId available)
-     * 2. If cache miss, fetch from API
-     * 3. If API fails, use fallback config
-     * 4. Cache successful API responses
-     *
-     * @param agentDid DID of the agent to fetch config for
-     */
-    getToolProtectionConfig(agentDid: string): Promise<ToolProtectionConfig>;
-    /**
-     * Check if a tool requires delegation
-     *
-     * @param toolName Name of the tool to check
-     * @param agentDid DID of the agent executing the tool
-     * @returns Tool protection config or null if no protection required
-     */
-    checkToolProtection(toolName: string, agentDid: string): Promise<ToolProtection | null>;
-    /**
-     * Fetch tool protection config from AgentShield API
-     *
-     * Uses the merged /config endpoint which returns tool protections embedded
-     * at config.toolProtection.tools. Falls back to legacy formats for backward
-     * compatibility.
-     *
-     * @param agentDid DID of the agent to fetch config for
-     * @param options Optional fetch options
-     * @param options.bypassCDNCache When true, adds cache-busting to bypass CDN caches (used by clearAndRefresh)
-     */
-    private fetchFromApi;
-    /**
-     * Parse tool protections from API response
-     *
-     * Extracts tool protection configs from merged config format:
-     * { data: { config: { toolProtection: { tools: {...} } } } }
-     *
-     * @param response API response from AgentShield
-     * @returns Record of tool name to ToolProtection
-     */
-    private parseToolProtectionsFromResponse;
-    /**
-     * Clear the cache for a project or agent (useful for testing or manual refresh)
-     *
-     * If projectId is configured, clears project-scoped cache.
-     * Otherwise, clears agent-scoped cache.
-     *
-     * @param agentDid DID of the agent (used for fallback if projectId not available)
-     */
-    clearCache(agentDid: string): Promise<void>;
-    /**
-     * Clear cache and immediately fetch fresh config from API
-     *
-     * This method is designed for Cloudflare Workers where KV has edge caching.
-     * After clearing the KV entry, it fetches fresh data from the API and writes
-     * it back to KV. This ensures:
-     * 1. The global KV entry is deleted
-     * 2. Fresh data is fetched from API (with CDN cache bypass!)
-     * 3. New data is written to KV (updating edge cache)
-     *
-     * The next request from the same edge location will get the fresh data.
-     *
-     * IMPORTANT: This method uses bypassCDNCache to ensure we get fresh data
-     * from AgentShield's origin server, not stale CDN-cached data. This is
-     * critical for instant cache invalidation when tool protection settings
-     * are changed in the AgentShield dashboard.
-     *
-     * @param agentDid DID of the agent (used for cache key)
-     * @returns The fresh tool protection config from API
-     */
-    clearAndRefresh(agentDid: string): Promise<{
-        config: ToolProtectionConfig;
-        cacheKey: string;
-        source: "api" | "fallback";
-    }>;
-}
-//# sourceMappingURL=tool-protection.service.d.ts.map