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

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

@@ -1,1070 +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.
- *
- * 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 /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,
-  DelegationRequiredError,
-} from "../types/tool-protection.js";
-import type { ToolProtectionCache } from "../cache/tool-protection-cache.js";
-import { InMemoryToolProtectionCache } from "../cache/tool-protection-cache.js";
-
-/**
- * Tool protection data structure in API responses
- */
-interface ToolProtectionData {
-  requiresDelegation?: boolean;
-  requires_delegation?: boolean;
-  requiredScopes?: string[];
-  required_scopes?: string[];
-  scopes?: string[];
-  riskLevel?: string;
-  risk_level?: string;
-  oauthProvider?: string;
-  oauth_provider?: string;
-  authorization?: {
-    type: string;
-    provider?: string;
-    issuer?: string;
-    credentialType?: string;
-  };
-}
-
-/**
- * Response from AgentShield API bouncer endpoints
- *
- * Supports multiple endpoint formats:
- * 1. Merged config (/projects/{projectId}/config): { data: { config: { toolProtection: { tools: {...} } } } }
- * 2. Legacy tool-protections endpoint: { data: { toolProtections: { [toolName]: {...} } } }
- * 3. Old config endpoint (/config?agent_did=...): { data: { tools: [{ name: string, ... }] } }
- * 4. Legacy format: { data: { tools: { [toolName]: {...} } } }
- */
-interface BouncerConfigApiResponse {
-  success: boolean;
-  data: {
-    agent_did?: string;
-    
-    // NEW: Merged config format (v1.6.0+) - preferred format
-    // The entire config is returned with tools embedded at config.toolProtection.tools
-    config?: {
-      toolProtection?: {
-        source?: string;
-        tools?: Record<string, ToolProtectionData>;
-      };
-      // Other config fields we don't need to parse
-      [key: string]: unknown;
-    };
-    
-    // DEPRECATED: Top-level toolProtections (backward compatibility during transition)
-    toolProtections?: Record<string, ToolProtectionData>;
-    
-    // Legacy endpoint formats
-    tools?:
-      | Array<{
-          name: string;
-          requiresDelegation?: boolean;
-          requires_delegation?: boolean;
-          scopes?: string[];
-          required_scopes?: string[];
-          oauthProvider?: string;
-          oauth_provider?: string;
-        }>
-      | Record<string, ToolProtectionData>;
-    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}/config`
-          : `/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) : [],
-          rawConfig: response.data?.config || null,
-          rawConfigToolProtection: response.data?.config?.toolProtection || null,
-          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 (in priority order):
-      // 1. Merged config endpoint: { data: { config: { toolProtection: { tools: {...} } } } }
-      // 2. Legacy toolProtections: { data: { toolProtections: { greet: { requiresDelegation: true, ... } } } }
-      // 3. Old endpoint (array): { data: { tools: [{ name: "greet", requiresDelegation: true, ... }] } }
-      // 4. Old endpoint (object): { data: { tools: { greet: { requiresDelegation: true, ... } } } }
-      const toolProtections: Record<string, ToolProtection> = {};
-
-      // Check for merged config format first (data.config.toolProtection.tools)
-      if (response.data.config?.toolProtection?.tools) {
-        // Merged config endpoint format: object with tool names as keys
-        if (this.config.debug) {
-          console.log("[ToolProtectionService] Using merged config format (data.config.toolProtection.tools)");
-        }
-        for (const [toolName, toolConfig] of Object.entries(
-          response.data.config.toolProtection.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 }),
-          };
-        }
-      } else if (response.data.toolProtections) {
-        // Legacy toolProtections format: object with tool names as keys
-        if (this.config.debug) {
-          console.log("[ToolProtectionService] Using legacy toolProtections format (data.toolProtections)");
-        }
-        // 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 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 async fetchFromApi(
-    agentDid: string,
-    options?: { bypassCDNCache?: boolean }
-  ): Promise<BouncerConfigApiResponse> {
-    // Use the merged /config endpoint which includes embedded tool protections
-    // This endpoint returns config.toolProtection.tools with all tool rules
-    let url: string;
-    let useMergedEndpoint = false;
-
-    if (this.config.projectId) {
-      // ✅ MERGED CONFIG ENDPOINT: Returns config with embedded toolProtection.tools
-      url = `${this.config.apiUrl}/api/v1/bouncer/projects/${encodeURIComponent(this.config.projectId)}/config`;
-      useMergedEndpoint = true;
-    } else {
-      // ⚠️ LEGACY 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: useMergedEndpoint
-          ? "projects/{projectId}/config (merged)"
-          : "config?agent_did (legacy)",
-        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 - merged endpoint uses X-API-Key, legacy uses Authorization Bearer
-    const headers: Record<string, string> = {
-      "Content-Type": "application/json",
-    };
-
-    if (useMergedEndpoint) {
-      // ✅ Merged config endpoint headers
-      headers["X-API-Key"] = this.config.apiKey;
-      if (this.config.projectId) {
-        headers["X-Project-Id"] = this.config.projectId;
-      }
-    } else {
-      // ⚠️ Legacy 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");
-    }
-
-    // Transform merged config format to normalized format
-    // If response contains config.toolProtection.tools, extract them to data.toolProtections
-    if (useMergedEndpoint && data.data.config?.toolProtection?.tools) {
-      // Extract embedded tools to the standard toolProtections field
-      data.data.toolProtections = data.data.config.toolProtection.tools;
-      if (this.config.debug) {
-        console.log("[ToolProtectionService] Extracted tools from merged config", {
-          toolCount: Object.keys(data.data.toolProtections).length,
-          tools: Object.keys(data.data.toolProtections),
-        });
-      }
-    }
-
-    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" };
-    }
-  }
-}