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

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

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolContextBuilder = void 0;
+const oauth_required_error_js_1 = require("../types/oauth-required-error.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)
+     * @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
+        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) {
+            // 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 oauth_required_error_js_1.OAuthRequiredError({
+                toolName,
+                requiredScopes: toolProtection.requiredScopes,
+                provider,
+                oauthUrl: "", // Will be populated by Cloudflare layer
+                userDid,
+                sessionId,
+            });
+        }
+        // Build context with token
+        const context = {
+            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
+     */
+    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-context-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-context-builder.js","sourceRoot":"","sources":["../../src/services/tool-context-builder.ts"],"names":[],"mappings":"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"}

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

@@ -1,12 +1,80 @@
 /**
  * ToolProtectionService - Fetches and caches tool protection configurations
  *
- * This service:
+ * This service manages tool protection configuration from AgentShield API with
+ * efficient caching and automatic synchronization support.
+ *
+ * CORE FUNCTIONALITY:
+ * -------------------
  * 1. Fetches tool protection config from AgentShield API
- * 2. Caches responses to reduce API calls
+ * 2. Caches responses with configurable TTL (default 5 minutes)
  * 3. Falls back to local config if API unavailable
- * 4. Provides delegation checking logic
+ * 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 /tool-protections returns empty 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";
@@ -58,7 +126,6 @@ export declare class ToolProtectionService {
      * Uses projectId endpoint if available (preferred, project-scoped), otherwise falls back to agent_did query param
      *
      * @param agentDid DID of the agent to fetch config for
-     * @param bypassCache If true, adds Cache-Control header to bypass AgentShield's cache
      */
     private fetchFromApi;
     /**
@@ -71,14 +138,24 @@ export declare class ToolProtectionService {
      */
     clearCache(agentDid: string): Promise<void>;
     /**
-     * Refresh cache immediately from API, bypassing both local and AgentShield cache
+     * 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
+     * 3. New data is written to KV (updating edge cache)
      *
-     * This method clears the local cache and fetches fresh config from the API
-     * with Cache-Control headers to bypass AgentShield's 5-minute cache.
+     * The next request from the same edge location will get the fresh data.
      *
-     * @param agentDid DID of the agent to refresh config for
-     * @returns Fresh tool protection config
+     * @param agentDid DID of the agent (used for cache key)
+     * @returns The fresh tool protection config from API
      */
-    refreshCache(agentDid: string): Promise<ToolProtectionConfig>;
+    clearAndRefresh(agentDid: string): Promise<{
+        config: ToolProtectionConfig;
+        cacheKey: string;
+        source: 'api' | 'fallback';
+    }>;
 }
 //# sourceMappingURL=tool-protection.service.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tool-protection.service.d.ts","sourceRoot":"","sources":["../../src/services/tool-protection.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,2BAA2B,EAE5B,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAwD7E;;GAEG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,KAAK,CAAsB;gBAEvB,MAAM,EAAE,2BAA2B,EAAE,KAAK,EAAE,mBAAmB;IAK3E;;;OAGG;IACH,YAAY,IAAI,MAAM,GAAG,SAAS;IAIlC;;;;;;;;OAQG;YACW,aAAa;IA4C3B;;;;;;;;;;OAUG;IACG,uBAAuB,CAC3B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,oBAAoB,CAAC;IAgRhC;;;;;;OAMG;IACG,mBAAmB,CACvB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IA8BjC;;;;;;OAMG;YACW,YAAY;IA+H1B;;;;;;;OAOG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBjD;;;;;;;;OAQG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAuGpE"}
+{"version":3,"file":"tool-protection.service.d.ts","sourceRoot":"","sources":["../../src/services/tool-protection.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,2BAA2B,EAE5B,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AA8D7E;;GAEG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,KAAK,CAAsB;gBAEvB,MAAM,EAAE,2BAA2B,EAAE,KAAK,EAAE,mBAAmB;IAK3E;;;OAGG;IACH,YAAY,IAAI,MAAM,GAAG,SAAS;IAIlC;;;;;;;;OAQG;YACW,aAAa;IA4C3B;;;;;;;;;;OAUG;IACG,uBAAuB,CAC3B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,oBAAoB,CAAC;IAuYhC;;;;;;OAMG;IACG,mBAAmB,CACvB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IA8BjC;;;;;OAKG;YACW,YAAY;IAsG1B;;;;;;;OAOG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBjD;;;;;;;;;;;;;;OAcG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAC/C,MAAM,EAAE,oBAAoB,CAAC;QAC7B,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,KAAK,GAAG,UAAU,CAAC;KAC5B,CAAC;CA4IH"}