@kya-os/mcp-i-core 1.3.7-canary.0 → 1.3.7-canary.clientinfo.20251126041014

package/src/services/tool-protection.service.ts

@@ -0,0 +1,982 @@
+/**
+ * ToolProtectionService - Fetches and caches tool protection configurations
+ *
+ * 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 with configurable TTL (default 5 minutes)
+ * 3. Falls back to local config if API unavailable
+ * 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,
+  DelegationRequiredError,
+} from "../types/tool-protection.js";
+import type { ToolProtectionCache } from "../cache/tool-protection-cache.js";
+import { InMemoryToolProtectionCache } from "../cache/tool-protection-cache.js";
+
+/**
+ * Response from AgentShield API bouncer endpoints
+ *
+ * Supports multiple endpoint formats:
+ * 1. New endpoint (/projects/{projectId}/tool-protections): { data: { toolProtections: { [toolName]: {...} } } } }
+ * 2. Old endpoint (/config?agent_did=...): { data: { tools: [{ name: string, ... }] } }
+ * 3. Legacy format: { data: { tools: { [toolName]: {...} } } }
+ */
+interface BouncerConfigApiResponse {
+  success: boolean;
+  data: {
+    agent_did?: string;
+    // New endpoint format: toolProtections object
+    toolProtections?: Record<
+      string,
+      {
+        requiresDelegation?: boolean;
+        requires_delegation?: boolean;
+        requiredScopes?: string[];
+        required_scopes?: string[];
+        scopes?: string[];
+        riskLevel?: string;
+        risk_level?: string;
+        oauthProvider?: string; // Phase 2: Tool-specific OAuth provider
+        oauth_provider?: string; // Phase 2: snake_case variant
+      }
+    >;
+    // Old endpoint format: tools array or object
+    tools?:
+      | Array<{
+          name: string;
+          requiresDelegation?: boolean;
+          requires_delegation?: boolean;
+          scopes?: string[];
+          required_scopes?: string[];
+          oauthProvider?: string; // Phase 2: Tool-specific OAuth provider
+          oauth_provider?: string; // Phase 2: snake_case variant
+        }>
+      | Record<
+          string,
+          {
+            requiresDelegation?: boolean;
+            requires_delegation?: boolean;
+            scopes?: string[];
+            required_scopes?: string[];
+            oauthProvider?: string; // Phase 2: Tool-specific OAuth provider
+            oauth_provider?: string; // Phase 2: snake_case variant
+          }
+        >;
+    reputation_threshold?: number;
+    denied_agents?: string[];
+  };
+  metadata?: {
+    requestId?: string;
+    timestamp?: string;
+    cachedUntil?: string;
+  };
+}
+
+/**
+ * Service for fetching and checking tool protection configurations
+ */
+export class ToolProtectionService {
+  private config: ToolProtectionServiceConfig;
+  private cache: ToolProtectionCache;
+
+  constructor(config: ToolProtectionServiceConfig, cache: ToolProtectionCache) {
+    this.config = config;
+    this.cache = cache;
+  }
+
+  /**
+   * Get the project ID from the service configuration
+   * @returns Project ID or undefined if not configured
+   */
+  getProjectId(): string | undefined {
+    return this.config.projectId;
+  }
+
+  /**
+   * 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 async getStaleCache(
+    cacheKey: string
+  ): Promise<ToolProtectionConfig | null> {
+    // Only check stale cache if enabled
+    if (this.config.allowStaleCache === false) {
+      return null;
+    }
+
+    // Only works with InMemoryToolProtectionCache
+    if (!(this.cache instanceof InMemoryToolProtectionCache)) {
+      return null;
+    }
+
+    // Use public method to get stale cache entry
+    const staleConfig = this.cache.getStale(cacheKey);
+    if (!staleConfig) {
+      return null;
+    }
+
+    // Check if stale cache is within maxStaleCacheAge
+    const expiresAt = this.cache.getExpiresAt(cacheKey);
+    if (!expiresAt) {
+      return null;
+    }
+
+    const now = Date.now();
+    const maxStaleAge = this.config.maxStaleCacheAge ?? 86400000; // Default 24 hours
+
+    // Check if expired but within maxStaleCacheAge
+    if (now > expiresAt && now - expiresAt <= maxStaleAge) {
+      if (this.config.debug) {
+        console.log("[ToolProtectionService] Using stale cache", {
+          cacheKey,
+          expiredAt: new Date(expiresAt).toISOString(),
+          staleAgeMs: now - expiresAt,
+          maxStaleAgeMs: maxStaleAge,
+        });
+      }
+      return staleConfig;
+    }
+
+    return null;
+  }
+
+  /**
+   * 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
+   */
+  async getToolProtectionConfig(
+    agentDid: string
+  ): Promise<ToolProtectionConfig> {
+    // Use project-scoped cache key if projectId is available (preferred)
+    // Falls back to agent-scoped key for backward compatibility
+    // The cache implementation (KVToolProtectionCache) will add any necessary prefix
+    const cacheKey = this.config.projectId
+      ? `config:tool-protections:${this.config.projectId}`
+      : `agent:${agentDid}`;
+
+    // 1. Check cache
+    const cached = await this.cache.get(cacheKey);
+    if (cached) {
+      const ttl = this.config.cacheTtl ?? 300000;
+      const cachedUntil = new Date(Date.now() + ttl).toISOString();
+
+      if (this.config.debug) {
+        console.log("[ToolProtectionService] Cache hit", {
+          source: "cache",
+          cacheKey,
+          agentDid: agentDid.slice(0, 20) + "...",
+          projectId: this.config.projectId || "none",
+          toolCount: Object.keys(cached.toolProtections).length,
+          protectedTools: Object.entries(cached.toolProtections)
+            .filter(([_, config]: [string, ToolProtection]) => config.requiresDelegation)
+            .map(([name]) => name),
+          cacheTtlMs: ttl,
+          cachedUntil,
+        });
+      }
+      return cached;
+    }
+
+    if (this.config.debug) {
+      console.log("[ToolProtectionService] Cache miss, fetching from API", {
+        source: "api-fetch-start",
+        cacheKey,
+        agentDid: agentDid.slice(0, 20) + "...",
+        projectId: this.config.projectId || "none",
+        apiUrl: this.config.apiUrl,
+        endpoint: this.config.projectId
+          ? `/api/v1/bouncer/projects/${this.config.projectId}/tool-protections`
+          : `/api/v1/bouncer/config?agent_did=${agentDid}`,
+      });
+    }
+
+    // 3. Fetch from API
+    try {
+      const response = await this.fetchFromApi(agentDid);
+
+      if (this.config.debug) {
+        console.log("[ToolProtectionService] API response received", {
+          source: "api-fetch-complete",
+          agentDid: agentDid.slice(0, 20) + "...",
+          projectId: this.config.projectId || "none",
+          responseKeys: Object.keys(response),
+          dataKeys: response.data ? Object.keys(response.data) : [],
+          rawToolProtections: response.data?.toolProtections || null,
+          rawTools: response.data?.tools || null,
+          responseMetadata: response.metadata || null,
+        });
+      }
+
+      // Transform API response format to internal format
+      // Supports multiple response formats:
+      // 1. New endpoint: { data: { toolProtections: { greet: { requiresDelegation: true, ... } } } }
+      // 2. Old endpoint (array): { data: { tools: [{ name: "greet", requiresDelegation: true, ... }] } }
+      // 3. Old endpoint (object): { data: { tools: { greet: { requiresDelegation: true, ... } } } }
+      const toolProtections: Record<string, ToolProtection> = {};
+
+      // Check for new endpoint format first (toolProtections)
+      if (response.data.toolProtections) {
+        // New endpoint format: object with tool names as keys
+        // Prefer camelCase over snake_case when both present
+        for (const [toolName, toolConfig] of Object.entries(
+          response.data.toolProtections
+        )) {
+          const requiresDelegation =
+            (toolConfig as any).requiresDelegation ??
+            (toolConfig as any).requires_delegation ??
+            false;
+          const requiredScopes =
+            (toolConfig as any).requiredScopes ??
+            (toolConfig as any).required_scopes ??
+            (toolConfig as any).scopes ??
+            [];
+          
+          // NEW: Parse oauthProvider (camelCase and snake_case support)
+          const oauthProvider =
+            (toolConfig as any).oauthProvider ??
+            (toolConfig as any).oauth_provider ??
+            undefined;
+          
+          const riskLevel =
+            (toolConfig as any).riskLevel ??
+            (toolConfig as any).risk_level ??
+            undefined;
+
+          toolProtections[toolName] = {
+            requiresDelegation,
+            requiredScopes,
+            ...(oauthProvider && { oauthProvider }), // Only include if present
+            ...(riskLevel && { riskLevel }), // Only include if present
+          };
+        }
+      } else if (response.data.tools) {
+        // Old endpoint format: array or object
+        if (Array.isArray(response.data.tools)) {
+          // Array format: [{ name: "greet", requiresDelegation: true, ... }]
+          for (const tool of response.data.tools) {
+            const toolName = tool.name;
+            if (!toolName) {
+              if (this.config.debug) {
+                console.warn(
+                  "[ToolProtectionService] Tool missing name in array format",
+                  tool
+                );
+              }
+              continue;
+            }
+
+            // Prefer camelCase over snake_case when both present
+            const requiresDelegation =
+              (tool as any).requiresDelegation ??
+              (tool as any).requires_delegation ??
+              false;
+            const requiredScopes =
+              (tool as any).requiredScopes ??
+              (tool as any).required_scopes ??
+              (tool as any).scopes ??
+              [];
+            
+            // NEW: Parse oauthProvider
+            const oauthProvider =
+              (tool as any).oauthProvider ??
+              (tool as any).oauth_provider ??
+              undefined;
+            
+            const riskLevel =
+              (tool as any).riskLevel ??
+              (tool as any).risk_level ??
+              undefined;
+
+            toolProtections[toolName] = {
+              requiresDelegation,
+              requiredScopes,
+              ...(oauthProvider && { oauthProvider }),
+              ...(riskLevel && { riskLevel }),
+            };
+          }
+        } else {
+          // Object format: { greet: { requiresDelegation: true, ... } }
+          for (const [toolName, toolConfig] of Object.entries(
+            response.data.tools
+          )) {
+            // Prefer camelCase over snake_case when both present
+            const requiresDelegation =
+              (toolConfig as any).requiresDelegation ??
+              (toolConfig as any).requires_delegation ??
+              false;
+            const requiredScopes =
+              (toolConfig as any).requiredScopes ??
+              (toolConfig as any).required_scopes ??
+              (toolConfig as any).scopes ??
+              [];
+            
+            // NEW: Parse oauthProvider
+            const oauthProvider =
+              (toolConfig as any).oauthProvider ??
+              (toolConfig as any).oauth_provider ??
+              undefined;
+            
+            const riskLevel =
+              (toolConfig as any).riskLevel ??
+              (toolConfig as any).risk_level ??
+              undefined;
+
+            toolProtections[toolName] = {
+              requiresDelegation,
+              requiredScopes,
+              ...(oauthProvider && { oauthProvider }),
+              ...(riskLevel && { riskLevel }),
+            };
+          }
+        }
+      }
+
+      // Merge with fallback config (local config takes priority over API)
+      // This allows users to override API responses with local configuration
+      // Note: Fallback config is also used when API fails, but here we merge even when API succeeds
+      const mergedToolProtections = { ...toolProtections };
+      if (this.config.fallbackConfig?.toolProtections) {
+        for (const [toolName, localConfig] of Object.entries(
+          this.config.fallbackConfig.toolProtections
+        )) {
+          // Skip if localConfig is empty or not a valid ToolProtection object
+          // This prevents empty objects from corrupting the merged config
+          if (!localConfig || typeof localConfig !== 'object' || Object.keys(localConfig).length === 0) {
+            if (this.config.debug) {
+              console.log(
+                "[ToolProtectionService] Skipping empty/invalid fallback config entry",
+                { tool: toolName }
+              );
+            }
+            continue;
+          }
+          
+          // Ensure requiredScopes exists (default to empty array if missing)
+          const validConfig: ToolProtection = {
+            requiresDelegation: (localConfig as any).requiresDelegation ?? false,
+            requiredScopes: (localConfig as any).requiredScopes ?? [],
+          };
+          
+          // Local config overrides API config for this tool
+          mergedToolProtections[toolName] = validConfig;
+          if (this.config.debug) {
+            console.log(
+              "[ToolProtectionService] Overriding API config with local config",
+              {
+                tool: toolName,
+                localConfig: validConfig,
+              }
+            );
+          }
+        }
+      }
+
+      const config: ToolProtectionConfig = {
+        toolProtections: mergedToolProtections,
+      };
+
+      // 3. Cache the response
+      const ttl = this.config.cacheTtl ?? 300000; // Default 5 minutes
+      const cacheExpiration = new Date(Date.now() + ttl);
+
+      await this.cache.set(cacheKey, config, ttl);
+
+      // Always log tool count and protection status (critical for debugging)
+      console.log("[ToolProtectionService] Config loaded from API", {
+        source: "api",
+        toolCount: Object.keys(mergedToolProtections).length,
+          protectedTools: Object.entries(mergedToolProtections)
+          .filter(([_, config]: [string, ToolProtection]) => config.requiresDelegation)
+          .map(([name]) => name),
+        agentDid: agentDid.slice(0, 20) + "...",
+        projectId: this.config.projectId || "none",
+        cacheTtlMs: ttl,
+        cacheExpiresAt: cacheExpiration.toISOString(),
+      });
+
+      if (this.config.debug) {
+        console.log(
+          "[ToolProtectionService] API fetch successful, config cached",
+          {
+            source: "cache-write",
+            agentDid: agentDid.slice(0, 20) + "...",
+            cacheKey,
+            toolCount: Object.keys(mergedToolProtections).length,
+            tools: Object.entries(mergedToolProtections).map(
+              ([name, config]) => ({
+                name,
+                requiresDelegation: config.requiresDelegation,
+                scopeCount: (config.requiredScopes || []).length, // Safe access
+              })
+            ),
+            ttlMs: ttl,
+            ttlMinutes: Math.round(ttl / 60000),
+            expiresAt: cacheExpiration.toISOString(),
+            expiresIn: `${Math.round(ttl / 1000)}s`,
+          }
+        );
+      }
+
+      return config;
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+
+      // Re-throw API key validation errors (don't fallback)
+      if (errorMessage.includes("API key is missing or empty")) {
+        throw error;
+      }
+
+      // Re-throw HTTP errors (4xx, 5xx) - these indicate API issues, not network failures
+      // Exception: 429 (rate limit) should fallback if fallback config is available
+      if (errorMessage.includes("Failed to fetch bouncer config:")) {
+        const status = (error as any).status;
+        // Allow 429 to fallback (rate limiting is temporary, fallback is acceptable)
+        if (status === 429 && this.config.fallbackConfig) {
+          // Will fall through to fallback logic below
+        } else {
+          throw error;
+        }
+      }
+
+      // Re-throw JSON parsing errors
+      if (errorMessage.includes("Failed to parse API response:")) {
+        throw error;
+      }
+
+      // Re-throw API success: false errors
+      if (errorMessage.includes("API returned success: false")) {
+        throw error;
+      }
+
+      if (this.config.debug) {
+        console.error("[ToolProtectionService] API fetch failed", {
+          agentDid: agentDid.slice(0, 20) + "...",
+          error: errorMessage,
+        });
+      }
+
+      // 4. Fallback to stale cache if available (before fallback config)
+      const staleCache = await this.getStaleCache(cacheKey);
+      if (staleCache) {
+        console.warn(
+          "[ToolProtectionService] API fetch failed, using stale cache",
+          {
+            agentDid: agentDid.slice(0, 20) + "...",
+            error: errorMessage,
+            cacheKey,
+          }
+        );
+        return staleCache;
+      }
+
+      // 5. Fallback to local config (only for network errors, not API errors)
+      if (this.config.fallbackConfig) {
+        // Always warn when using fallback (not just debug mode)
+        console.warn(
+          "[ToolProtectionService] API fetch failed, using fallback config",
+          {
+            agentDid: agentDid.slice(0, 20) + "...",
+            error: errorMessage,
+          }
+        );
+
+        // Cache the fallback config to avoid repeated API calls
+        const ttl = this.config.cacheTtl ?? 300000; // Default 5 minutes
+        await this.cache.set(cacheKey, this.config.fallbackConfig, ttl);
+
+        return this.config.fallbackConfig;
+      }
+
+      // 6. Fail-safe behavior: deny-all by default (secure)
+      const failSafeBehavior = this.config.failSafeBehavior ?? "deny-all";
+
+      if (failSafeBehavior === "deny-all") {
+        console.error(
+          "[ToolProtectionService] API fetch failed, no fallback, failing closed (deny-all)",
+          {
+            agentDid: agentDid.slice(0, 20) + "...",
+            error: errorMessage,
+            cacheKey,
+          }
+        );
+
+        // Create deny-all config (wildcard requires delegation for all tools)
+        const denyAllConfig: ToolProtectionConfig = {
+          toolProtections: {
+            "*": {
+              requiresDelegation: true,
+              requiredScopes: [],
+            },
+          },
+        };
+
+        // Cache deny-all config to avoid repeated API calls
+        const ttl = this.config.cacheTtl ?? 300000; // Default 5 minutes
+        await this.cache.set(cacheKey, denyAllConfig, ttl);
+
+        return denyAllConfig;
+      } else {
+        // failSafeBehavior === 'allow-all' (insecure, not recommended)
+        console.warn(
+          "[ToolProtectionService] API fetch failed, no fallback, failing open (allow-all)",
+          {
+            agentDid: agentDid.slice(0, 20) + "...",
+            error: errorMessage,
+            cacheKey,
+          }
+        );
+
+        // Cache empty config to avoid repeated API calls
+        const emptyConfig: ToolProtectionConfig = { toolProtections: {} };
+        const ttl = this.config.cacheTtl ?? 300000; // Default 5 minutes
+        await this.cache.set(cacheKey, emptyConfig, ttl);
+
+        return emptyConfig;
+      }
+    }
+  }
+
+  /**
+   * 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
+   */
+  async checkToolProtection(
+    toolName: string,
+    agentDid: string
+  ): Promise<ToolProtection | null> {
+    const config = await this.getToolProtectionConfig(agentDid);
+
+    // Check for specific tool protection first
+    let protection = config.toolProtections[toolName];
+
+    // If not found, check for wildcard protection (fail-safe deny-all)
+    if (!protection && config.toolProtections["*"]) {
+      protection = config.toolProtections["*"];
+    }
+
+    // Always log the check result (critical for debugging)
+    if (this.config.debug || !protection || protection.requiresDelegation) {
+      console.log("[ToolProtectionService] Protection check", {
+        tool: toolName,
+        agentDid: agentDid.slice(0, 20) + "...",
+        found: !!protection,
+        isWildcard: protection === config.toolProtections["*"],
+        requiresDelegation: protection?.requiresDelegation ?? false,
+        availableTools: Object.keys(config.toolProtections),
+      });
+    }
+
+    if (!protection || !protection.requiresDelegation) {
+      return null;
+    }
+
+    return protection;
+  }
+
+  /**
+   * Fetch tool protection config from AgentShield API
+   * 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 options Optional fetch options
+   * @param options.bypassCDNCache When true, adds cache-busting to bypass CDN caches (used by clearAndRefresh)
+   */
+  private async fetchFromApi(
+    agentDid: string,
+    options?: { bypassCDNCache?: boolean }
+  ): Promise<BouncerConfigApiResponse> {
+    // Prefer new project-scoped endpoint: /api/v1/bouncer/projects/{projectId}/tool-protections
+    // Falls back to old endpoint: /api/v1/bouncer/config?agent_did={did} for backward compatibility
+    let url: string;
+    let useNewEndpoint = false;
+
+    if (this.config.projectId) {
+      // ✅ NEW ENDPOINT: Project-scoped, returns toolProtections object
+      url = `${this.config.apiUrl}/api/v1/bouncer/projects/${encodeURIComponent(this.config.projectId)}/tool-protections`;
+      useNewEndpoint = true;
+    } else {
+      // ⚠️ OLD ENDPOINT: Agent-scoped, returns tools array (backward compatibility)
+      url = `${this.config.apiUrl}/api/v1/bouncer/config?agent_did=${encodeURIComponent(agentDid)}`;
+    }
+
+    // Add cache-busting query param when bypassing CDN cache
+    // This is used during cache invalidation (clearAndRefresh) to ensure we get fresh data
+    // from the origin server, not stale CDN-cached data
+    if (options?.bypassCDNCache) {
+      const separator = url.includes("?") ? "&" : "?";
+      url = `${url}${separator}_t=${Date.now()}`;
+    }
+
+    // Debug: Log API key status (masked for security)
+    // Format: sk_live... (prefix up to first underscore after type, then ...)
+    const apiKeyMasked = this.config.apiKey
+      ? (() => {
+          const parts = this.config.apiKey.split("_");
+          if (parts.length >= 2) {
+            return `${parts[0]}_${parts[1]}...`;
+          }
+          return `${this.config.apiKey.substring(0, 8)}...`;
+        })()
+      : "(empty)";
+    const apiKeyLength = this.config.apiKey?.length || 0;
+
+    if (this.config.debug) {
+      console.log("[ToolProtectionService] Fetching from API:", url, {
+        method: useNewEndpoint
+          ? "projects/{projectId}/tool-protections (new)"
+          : "config?agent_did (old)",
+        projectId: this.config.projectId || "none",
+        apiKeyPresent: !!this.config.apiKey,
+        apiKeyLength,
+        apiKeyMasked,
+      });
+    }
+
+    // Validate API key is present
+    if (!this.config.apiKey || this.config.apiKey.trim() === "") {
+      const error = "API key is missing or empty";
+      if (this.config.debug) {
+        console.error("[ToolProtectionService]", error, {
+          apiKeyPresent: !!this.config.apiKey,
+          apiKeyLength,
+        });
+      }
+      throw new Error(
+        `ToolProtectionService: ${error}. Check AGENTSHIELD_API_KEY in .dev.vars or wrangler.toml [vars]`
+      );
+    }
+
+    // Build headers - new endpoint uses X-API-Key, old endpoint uses Authorization Bearer
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+
+    if (useNewEndpoint) {
+      // ✅ New endpoint headers
+      headers["X-API-Key"] = this.config.apiKey;
+      if (this.config.projectId) {
+        headers["X-Project-Id"] = this.config.projectId;
+      }
+    } else {
+      // ⚠️ Old endpoint headers (backward compatibility)
+      headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+    }
+
+    // Add cache-control header when bypassing CDN cache
+    // This tells any intermediate caches (CDN, proxies) not to serve cached content
+    if (options?.bypassCDNCache) {
+      headers["Cache-Control"] = "no-cache, no-store, must-revalidate";
+      headers["Pragma"] = "no-cache"; // HTTP/1.0 backward compatibility
+    }
+
+    const response = await fetch(url, {
+      method: "GET",
+      headers,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "Unknown error");
+      const error = new Error(
+        `Failed to fetch bouncer config: ${response.status} ${response.statusText} - ${errorText}`
+      );
+      (error as any).status = response.status;
+      throw error;
+    }
+
+    let data: BouncerConfigApiResponse;
+    try {
+      data = (await response.json()) as BouncerConfigApiResponse;
+    } catch (jsonError) {
+      throw new Error(
+        `Failed to parse API response: ${jsonError instanceof Error ? jsonError.message : String(jsonError)}`
+      );
+    }
+
+    if (!data.success) {
+      throw new Error("API returned success: false");
+    }
+
+    return data;
+  }
+
+  /**
+   * 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)
+   */
+  async clearCache(agentDid: string): Promise<void> {
+    // Use same cache key strategy as getToolProtectionConfig
+    const cacheKey = this.config.projectId
+      ? `config:tool-protections:${this.config.projectId}`
+      : `agent:${agentDid}`;
+
+    if (this.config.debug) {
+      console.log("[ToolProtectionService] Clearing cache", {
+        cacheKey,
+        projectId: this.config.projectId || "none",
+        agentDid: agentDid.slice(0, 20) + "...",
+      });
+    }
+
+    await this.cache.delete(cacheKey);
+  }
+
+  /**
+   * 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
+   */
+  async clearAndRefresh(agentDid: string): Promise<{
+    config: ToolProtectionConfig;
+    cacheKey: string;
+    source: 'api' | 'fallback';
+  }> {
+    const cacheKey = this.config.projectId
+      ? `config:tool-protections:${this.config.projectId}`
+      : `agent:${agentDid}`;
+
+    console.log("[ToolProtectionService] clearAndRefresh starting", {
+      cacheKey,
+      projectId: this.config.projectId || "none",
+      agentDid: agentDid.slice(0, 20) + "...",
+    });
+
+    // 1. Delete the cache entry
+    await this.cache.delete(cacheKey);
+
+    console.log("[ToolProtectionService] Cache entry deleted", { cacheKey });
+
+    // 2. Fetch fresh config from API with CDN cache bypass
+    // This ensures we get fresh data from origin, not stale CDN data
+    try {
+      const response = await this.fetchFromApi(agentDid, { bypassCDNCache: true });
+
+      // Transform API response to internal format (same logic as getToolProtectionConfig)
+      const toolProtections: Record<string, ToolProtection> = {};
+
+      if (response.data.toolProtections) {
+        for (const [toolName, toolConfig] of Object.entries(
+          response.data.toolProtections
+        )) {
+          const requiresDelegation =
+            (toolConfig as any).requiresDelegation ??
+            (toolConfig as any).requires_delegation ??
+            false;
+          const requiredScopes =
+            (toolConfig as any).requiredScopes ??
+            (toolConfig as any).required_scopes ??
+            (toolConfig as any).scopes ??
+            [];
+          const oauthProvider =
+            (toolConfig as any).oauthProvider ??
+            (toolConfig as any).oauth_provider ??
+            undefined;
+          const riskLevel =
+            (toolConfig as any).riskLevel ??
+            (toolConfig as any).risk_level ??
+            undefined;
+
+          toolProtections[toolName] = {
+            requiresDelegation,
+            requiredScopes,
+            ...(oauthProvider && { oauthProvider }),
+            ...(riskLevel && { riskLevel }),
+          };
+        }
+      } else if (response.data.tools) {
+        if (Array.isArray(response.data.tools)) {
+          for (const tool of response.data.tools) {
+            const toolName = (tool as any).name;
+            if (!toolName) continue;
+            const requiresDelegation =
+              (tool as any).requiresDelegation ?? (tool as any).requires_delegation ?? false;
+            const requiredScopes =
+              (tool as any).requiredScopes ??
+              (tool as any).required_scopes ??
+              (tool as any).scopes ??
+              [];
+            const oauthProvider =
+              (tool as any).oauthProvider ?? (tool as any).oauth_provider ?? undefined;
+            const riskLevel = (tool as any).riskLevel ?? (tool as any).risk_level ?? undefined;
+
+            toolProtections[toolName] = {
+              requiresDelegation,
+              requiredScopes,
+              ...(oauthProvider && { oauthProvider }),
+              ...(riskLevel && { riskLevel }),
+            };
+          }
+        } else {
+          for (const [toolName, toolConfig] of Object.entries(
+            response.data.tools
+          )) {
+            const requiresDelegation =
+              (toolConfig as any).requiresDelegation ??
+              (toolConfig as any).requires_delegation ??
+              false;
+            const requiredScopes =
+              (toolConfig as any).requiredScopes ??
+              (toolConfig as any).required_scopes ??
+              (toolConfig as any).scopes ??
+              [];
+            const oauthProvider =
+              (toolConfig as any).oauthProvider ??
+              (toolConfig as any).oauth_provider ??
+              undefined;
+            const riskLevel =
+              (toolConfig as any).riskLevel ??
+              (toolConfig as any).risk_level ??
+              undefined;
+
+            toolProtections[toolName] = {
+              requiresDelegation,
+              requiredScopes,
+              ...(oauthProvider && { oauthProvider }),
+              ...(riskLevel && { riskLevel }),
+            };
+          }
+        }
+      }
+
+      // Construct fresh config (ToolProtectionConfig type)
+      const freshConfig: ToolProtectionConfig = {
+        toolProtections,
+      };
+
+      // 3. Write fresh config to cache
+      const ttl = this.config.cacheTtl ?? 300000;
+      await this.cache.set(cacheKey, freshConfig, ttl);
+
+      console.log("[ToolProtectionService] Fresh config fetched and cached", {
+        cacheKey,
+        toolCount: Object.keys(toolProtections).length,
+        protectedTools: Object.entries(toolProtections)
+          .filter(([_, cfg]) => cfg.requiresDelegation)
+          .map(([name]) => name),
+        source: "api",
+      });
+
+      return { config: freshConfig, cacheKey, source: 'api' };
+    } catch (error) {
+      console.warn("[ToolProtectionService] API fetch failed during refresh, using fallback", {
+        error: error instanceof Error ? error.message : String(error),
+        cacheKey,
+      });
+
+      // Use fallback config if API fails
+      const fallbackConfig: ToolProtectionConfig = this.config.fallbackConfig || {
+        toolProtections: {},
+      };
+
+      return { config: fallbackConfig, cacheKey, source: 'fallback' };
+    }
+  }
+}