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

package/dist/services/tool-protection.service.js

@@ -1,736 +0,0 @@
-"use strict";
-/**
- * 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
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolProtectionService = void 0;
-const tool_protection_cache_js_1 = require("../cache/tool-protection-cache.js");
-/**
- * Service for fetching and checking tool protection configurations
- */
-class ToolProtectionService {
-    config;
-    cache;
-    constructor(config, cache) {
-        this.config = config;
-        this.cache = cache;
-    }
-    /**
-     * Get the project ID from the service configuration
-     * @returns Project ID or undefined if not configured
-     */
-    getProjectId() {
-        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
-     */
-    async getStaleCache(cacheKey) {
-        // Only check stale cache if enabled
-        if (this.config.allowStaleCache === false) {
-            return null;
-        }
-        // Only works with InMemoryToolProtectionCache
-        if (!(this.cache instanceof tool_protection_cache_js_1.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.error("[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) {
-        // 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.error("[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]) => config.requiresDelegation)
-                        .map(([name]) => name),
-                    cacheTtlMs: ttl,
-                    cachedUntil,
-                });
-            }
-            return cached;
-        }
-        if (this.config.debug) {
-            console.error("[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.error("[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,
-                    responseMetadata: response.metadata || null,
-                });
-            }
-            // Transform API response to internal format
-            // Uses merged config endpoint: { data: { config: { toolProtection: { tools: {...} } } } }
-            const toolProtections = this.parseToolProtectionsFromResponse(response);
-            if (this.config.debug && Object.keys(toolProtections).length > 0) {
-                console.error("[ToolProtectionService] Parsed tool protections from merged config", {
-                    toolCount: Object.keys(toolProtections).length,
-                    tools: Object.keys(toolProtections),
-                });
-            }
-            // Merge with local config (REMOTE API takes priority over local)
-            // Standard precedence: Default < Local < Remote
-            // Remote (AgentShield dashboard) is the source of truth and WINS over local config
-            const mergedToolProtections = {};
-            // Step 1: Apply local config as base (if provided)
-            if (this.config.localConfig?.toolProtections) {
-                for (const [toolName, localConfig] of Object.entries(this.config.localConfig.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.error("[ToolProtectionService] Skipping empty/invalid local config entry", { tool: toolName });
-                        }
-                        continue;
-                    }
-                    // Ensure requiredScopes exists (default to empty array if missing)
-                    // Also preserve optional fields like oauthProvider, riskLevel, authorization
-                    const validConfig = {
-                        requiresDelegation: localConfig.requiresDelegation ?? false,
-                        requiredScopes: localConfig.requiredScopes ?? [],
-                        ...(localConfig.oauthProvider && {
-                            oauthProvider: localConfig.oauthProvider,
-                        }),
-                        ...(localConfig.riskLevel && {
-                            riskLevel: localConfig.riskLevel,
-                        }),
-                        ...(localConfig.authorization && {
-                            authorization: localConfig.authorization,
-                        }),
-                    };
-                    mergedToolProtections[toolName] = validConfig;
-                    if (this.config.debug) {
-                        console.error("[ToolProtectionService] Applied local config as base", {
-                            tool: toolName,
-                            localConfig: validConfig,
-                        });
-                    }
-                }
-            }
-            // Step 2: Apply API config (OVERWRITES local config - remote wins)
-            for (const [toolName, apiConfig] of Object.entries(toolProtections)) {
-                mergedToolProtections[toolName] = apiConfig;
-                if (this.config.debug &&
-                    this.config.localConfig?.toolProtections?.[toolName]) {
-                    console.error("[ToolProtectionService] Remote config overrides local config", {
-                        tool: toolName,
-                        remoteConfig: apiConfig,
-                    });
-                }
-            }
-            const config = {
-                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.error("[ToolProtectionService] Config loaded from API", {
-                source: "api",
-                toolCount: Object.keys(mergedToolProtections).length,
-                protectedTools: Object.entries(mergedToolProtections)
-                    .filter(([_, config]) => 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.error("[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 projectId required errors (security fix - don't fallback)
-            if (errorMessage.includes("projectId is required")) {
-                throw error;
-            }
-            // Re-throw HTTP errors (4xx, 5xx) - these indicate API issues, not network failures
-            // Exception: 429 (rate limit) should fallback if offline fallback config is available
-            if (errorMessage.includes("Failed to fetch bouncer config:")) {
-                const status = error.status;
-                // Allow 429 to fallback (rate limiting is temporary, fallback is acceptable)
-                if (status === 429 && this.config.offlineFallbackConfig) {
-                    // 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 offline config (only used when API is unavailable)
-            // Note: offlineFallbackConfig is separate from localConfig
-            // - localConfig: Merged with remote (remote wins), used always
-            // - offlineFallbackConfig: Only used when API is completely unavailable
-            if (this.config.offlineFallbackConfig) {
-                // Always warn when using offline fallback (not just debug mode)
-                console.warn("[ToolProtectionService] API fetch failed, using offline 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.offlineFallbackConfig, ttl);
-                return this.config.offlineFallbackConfig;
-            }
-            // 6. Fail-safe behavior: deny-all by default (secure)
-            // This is the last resort when: API fails AND no stale cache AND no offlineFallbackConfig
-            const failSafeBehavior = this.config.failSafeBehavior ?? "deny-all";
-            if (failSafeBehavior === "deny-all") {
-                console.error("[ToolProtectionService] API fetch failed, no offline 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 = {
-                    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 offline fallback, failing open (allow-all)", {
-                    agentDid: agentDid.slice(0, 20) + "...",
-                    error: errorMessage,
-                    cacheKey,
-                });
-                // Cache empty config to avoid repeated API calls
-                const emptyConfig = { 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, agentDid) {
-        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.error("[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)
-     */
-    async fetchFromApi(agentDid, options) {
-        // Use the merged /config endpoint which includes embedded tool protections
-        // This endpoint returns config.toolProtection.tools with all tool rules
-        let url;
-        let useMergedEndpoint = false;
-        // ❌ REMOVED: Legacy agent-scoped endpoint fallback
-        // Agent-only scoping causes cross-user delegation leakage (Priority 3 fallback issue)
-        // projectId is now REQUIRED for proper user isolation
-        if (!this.config.projectId) {
-            const error = new Error("[ToolProtectionService] projectId is required for user-scoped delegation. " +
-                "Agent-only scoping has been deprecated due to security concerns (cross-user delegation leakage). " +
-                "Please configure AGENTSHIELD_PROJECT_ID environment variable.");
-            console.error("[ToolProtectionService]", error.message);
-            throw error;
-        }
-        // ✅ PROJECT-SCOPED ENDPOINT: Returns config with embedded toolProtection.tools
-        // This endpoint ensures delegations are properly scoped to user+agent
-        url = `${this.config.apiUrl}/api/v1/bouncer/projects/${encodeURIComponent(this.config.projectId)}/config`;
-        useMergedEndpoint = true;
-        // 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.error("[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 = {
-            "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.status = response.status;
-            throw error;
-        }
-        let data;
-        try {
-            data = (await response.json());
-        }
-        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;
-    }
-    /**
-     * 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
-     */
-    parseToolProtectionsFromResponse(response) {
-        const toolProtections = {};
-        // Extract from merged config format: data.config.toolProtection.tools
-        const tools = response.data.config?.toolProtection?.tools;
-        if (!tools) {
-            return toolProtections;
-        }
-        for (const [toolName, toolConfig] of Object.entries(tools)) {
-            // Support both camelCase and snake_case for backward compatibility with DB data
-            const requiresDelegation = toolConfig.requiresDelegation ??
-                toolConfig.requires_delegation ??
-                false;
-            const requiredScopes = toolConfig.requiredScopes ??
-                toolConfig.required_scopes ??
-                toolConfig.scopes ??
-                [];
-            const oauthProvider = toolConfig.oauthProvider ?? toolConfig.oauth_provider ?? undefined;
-            const rawRiskLevel = toolConfig.riskLevel ?? toolConfig.risk_level ?? undefined;
-            // Type-safe cast for riskLevel enum
-            const riskLevel = rawRiskLevel &&
-                ["low", "medium", "high", "critical"].includes(rawRiskLevel)
-                ? rawRiskLevel
-                : undefined;
-            // Cast authorization to proper discriminated union type
-            // The API returns the correct shape, we just need to help TypeScript
-            const authorization = toolConfig.authorization;
-            toolProtections[toolName] = {
-                requiresDelegation,
-                requiredScopes,
-                ...(oauthProvider && { oauthProvider }),
-                ...(riskLevel && { riskLevel }),
-                ...(authorization && { authorization }),
-            };
-        }
-        return toolProtections;
-    }
-    /**
-     * 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) {
-        // 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.error("[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) {
-        const cacheKey = this.config.projectId
-            ? `config:tool-protections:${this.config.projectId}`
-            : `agent:${agentDid}`;
-        console.error("[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.error("[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,
-            });
-            // Use shared parsing logic for consistency
-            const toolProtections = this.parseToolProtectionsFromResponse(response);
-            // Apply same merge logic as getToolProtectionConfig:
-            // Step 1: Apply localConfig as base (if provided)
-            // Step 2: Apply API config (OVERWRITES local config - remote wins)
-            const mergedToolProtections = {};
-            // Step 1: Apply local config as base
-            if (this.config.localConfig?.toolProtections) {
-                for (const [toolName, localConfig] of Object.entries(this.config.localConfig.toolProtections)) {
-                    if (localConfig &&
-                        typeof localConfig === "object" &&
-                        Object.keys(localConfig).length > 0) {
-                        const validConfig = {
-                            requiresDelegation: localConfig.requiresDelegation ?? false,
-                            requiredScopes: localConfig.requiredScopes ?? [],
-                            ...(localConfig.oauthProvider && {
-                                oauthProvider: localConfig.oauthProvider,
-                            }),
-                            ...(localConfig.riskLevel && {
-                                riskLevel: localConfig.riskLevel,
-                            }),
-                            ...(localConfig.authorization && {
-                                authorization: localConfig.authorization,
-                            }),
-                        };
-                        mergedToolProtections[toolName] = validConfig;
-                    }
-                }
-            }
-            // Step 2: Apply API config (OVERWRITES local config - remote wins)
-            for (const [toolName, apiConfig] of Object.entries(toolProtections)) {
-                mergedToolProtections[toolName] = apiConfig;
-            }
-            // Construct fresh config (ToolProtectionConfig type)
-            const freshConfig = {
-                toolProtections: mergedToolProtections,
-            };
-            // 3. Write fresh config to cache
-            const ttl = this.config.cacheTtl ?? 300000;
-            await this.cache.set(cacheKey, freshConfig, ttl);
-            console.error("[ToolProtectionService] Fresh config fetched and cached", {
-                cacheKey,
-                toolCount: Object.keys(mergedToolProtections).length,
-                protectedTools: Object.entries(mergedToolProtections)
-                    .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 offline fallback", {
-                error: error instanceof Error ? error.message : String(error),
-                cacheKey,
-            });
-            // Use offline fallback config if API fails
-            const offlineFallback = this.config
-                .offlineFallbackConfig || {
-                toolProtections: {},
-            };
-            return { config: offlineFallback, cacheKey, source: "fallback" };
-        }
-    }
-}
-exports.ToolProtectionService = ToolProtectionService;
-//# sourceMappingURL=tool-protection.service.js.map