@kya-os/mcp-i-core 1.3.23 → 1.3.25

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

@@ -5,11 +5,23 @@
  * 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
- * 2. Caches responses with configurable TTL (default 5 minutes)
- * 3. Falls back to local config if API unavailable
+ * 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:
@@ -131,7 +143,7 @@ class ToolProtectionService {
         // Check if expired but within maxStaleCacheAge
         if (now > expiresAt && now - expiresAt <= maxStaleAge) {
             if (this.config.debug) {
-                console.log("[ToolProtectionService] Using stale cache", {
+                console.error("[ToolProtectionService] Using stale cache", {
                     cacheKey,
                     expiredAt: new Date(expiresAt).toISOString(),
                     staleAgeMs: now - expiresAt,
@@ -166,7 +178,7 @@ class ToolProtectionService {
             const ttl = this.config.cacheTtl ?? 300000;
             const cachedUntil = new Date(Date.now() + ttl).toISOString();
             if (this.config.debug) {
-                console.log("[ToolProtectionService] Cache hit", {
+                console.error("[ToolProtectionService] Cache hit", {
                     source: "cache",
                     cacheKey,
                     agentDid: agentDid.slice(0, 20) + "...",
@@ -182,7 +194,7 @@ class ToolProtectionService {
             return cached;
         }
         if (this.config.debug) {
-            console.log("[ToolProtectionService] Cache miss, fetching from API", {
+            console.error("[ToolProtectionService] Cache miss, fetching from API", {
                 source: "api-fetch-start",
                 cacheKey,
                 agentDid: agentDid.slice(0, 20) + "...",
@@ -197,7 +209,7 @@ class ToolProtectionService {
         try {
             const response = await this.fetchFromApi(agentDid);
             if (this.config.debug) {
-                console.log("[ToolProtectionService] API response received", {
+                console.error("[ToolProtectionService] API response received", {
                     source: "api-fetch-complete",
                     agentDid: agentDid.slice(0, 20) + "...",
                     projectId: this.config.projectId || "none",
@@ -205,166 +217,70 @@ class ToolProtectionService {
                     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 = {};
-            // 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.requiresDelegation ??
-                        toolConfig.requires_delegation ??
-                        false;
-                    const requiredScopes = toolConfig.requiredScopes ??
-                        toolConfig.required_scopes ??
-                        toolConfig.scopes ??
-                        [];
-                    const oauthProvider = toolConfig.oauthProvider ??
-                        toolConfig.oauth_provider ??
-                        undefined;
-                    const riskLevel = toolConfig.riskLevel ??
-                        toolConfig.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.requiresDelegation ??
-                        toolConfig.requires_delegation ??
-                        false;
-                    const requiredScopes = toolConfig.requiredScopes ??
-                        toolConfig.required_scopes ??
-                        toolConfig.scopes ??
-                        [];
-                    // NEW: Parse oauthProvider (camelCase and snake_case support)
-                    const oauthProvider = toolConfig.oauthProvider ??
-                        toolConfig.oauth_provider ??
-                        undefined;
-                    const riskLevel = toolConfig.riskLevel ??
-                        toolConfig.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.requiresDelegation ??
-                            tool.requires_delegation ??
-                            false;
-                        const requiredScopes = tool.requiredScopes ??
-                            tool.required_scopes ??
-                            tool.scopes ??
-                            [];
-                        // NEW: Parse oauthProvider
-                        const oauthProvider = tool.oauthProvider ??
-                            tool.oauth_provider ??
-                            undefined;
-                        const riskLevel = tool.riskLevel ?? tool.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.requiresDelegation ??
-                            toolConfig.requires_delegation ??
-                            false;
-                        const requiredScopes = toolConfig.requiredScopes ??
-                            toolConfig.required_scopes ??
-                            toolConfig.scopes ??
-                            [];
-                        // NEW: Parse oauthProvider
-                        const oauthProvider = toolConfig.oauthProvider ??
-                            toolConfig.oauth_provider ??
-                            undefined;
-                        const riskLevel = toolConfig.riskLevel ??
-                            toolConfig.risk_level ??
-                            undefined;
-                        toolProtections[toolName] = {
-                            requiresDelegation,
-                            requiredScopes,
-                            ...(oauthProvider && { oauthProvider }),
-                            ...(riskLevel && { riskLevel }),
-                        };
-                    }
-                }
+            // 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 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)) {
+            // 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.log("[ToolProtectionService] Skipping empty/invalid fallback config entry", { tool: toolName });
+                            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,
+                        }),
                     };
-                    // Local config overrides API config for this tool
                     mergedToolProtections[toolName] = validConfig;
                     if (this.config.debug) {
-                        console.log("[ToolProtectionService] Overriding API config with local config", {
+                        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,
             };
@@ -373,7 +289,7 @@ class ToolProtectionService {
             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", {
+            console.error("[ToolProtectionService] Config loaded from API", {
                 source: "api",
                 toolCount: Object.keys(mergedToolProtections).length,
                 protectedTools: Object.entries(mergedToolProtections)
@@ -385,7 +301,7 @@ class ToolProtectionService {
                 cacheExpiresAt: cacheExpiration.toISOString(),
             });
             if (this.config.debug) {
-                console.log("[ToolProtectionService] API fetch successful, config cached", {
+                console.error("[ToolProtectionService] API fetch successful, config cached", {
                     source: "cache-write",
                     agentDid: agentDid.slice(0, 20) + "...",
                     cacheKey,
@@ -414,11 +330,11 @@ class ToolProtectionService {
                 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
+            // 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.fallbackConfig) {
+                if (status === 429 && this.config.offlineFallbackConfig) {
                     // Will fall through to fallback logic below
                 }
                 else {
@@ -449,22 +365,26 @@ class ToolProtectionService {
                 });
                 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", {
+            // 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.fallbackConfig, ttl);
-                return this.config.fallbackConfig;
+                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 fallback, failing closed (deny-all)", {
+                console.error("[ToolProtectionService] API fetch failed, no offline fallback, failing closed (deny-all)", {
                     agentDid: agentDid.slice(0, 20) + "...",
                     error: errorMessage,
                     cacheKey,
@@ -485,7 +405,7 @@ class ToolProtectionService {
             }
             else {
                 // failSafeBehavior === 'allow-all' (insecure, not recommended)
-                console.warn("[ToolProtectionService] API fetch failed, no fallback, failing open (allow-all)", {
+                console.warn("[ToolProtectionService] API fetch failed, no offline fallback, failing open (allow-all)", {
                     agentDid: agentDid.slice(0, 20) + "...",
                     error: errorMessage,
                     cacheKey,
@@ -515,7 +435,7 @@ class ToolProtectionService {
         }
         // Always log the check result (critical for debugging)
         if (this.config.debug || !protection || protection.requiresDelegation) {
-            console.log("[ToolProtectionService] Protection check", {
+            console.error("[ToolProtectionService] Protection check", {
                 tool: toolName,
                 agentDid: agentDid.slice(0, 20) + "...",
                 found: !!protection,
@@ -579,7 +499,7 @@ class ToolProtectionService {
             : "(empty)";
         const apiKeyLength = this.config.apiKey?.length || 0;
         if (this.config.debug) {
-            console.log("[ToolProtectionService] Fetching from API:", url, {
+            console.error("[ToolProtectionService] Fetching from API:", url, {
                 method: useMergedEndpoint
                     ? "projects/{projectId}/config (merged)"
                     : "config?agent_did (legacy)",
@@ -641,20 +561,53 @@ class ToolProtectionService {
         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;
     }
+    /**
+     * 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)
      *
@@ -669,7 +622,7 @@ class ToolProtectionService {
             ? `config:tool-protections:${this.config.projectId}`
             : `agent:${agentDid}`;
         if (this.config.debug) {
-            console.log("[ToolProtectionService] Clearing cache", {
+            console.error("[ToolProtectionService] Clearing cache", {
                 cacheKey,
                 projectId: this.config.projectId || "none",
                 agentDid: agentDid.slice(0, 20) + "...",
@@ -701,105 +654,64 @@ class ToolProtectionService {
         const cacheKey = this.config.projectId
             ? `config:tool-protections:${this.config.projectId}`
             : `agent:${agentDid}`;
-        console.log("[ToolProtectionService] clearAndRefresh starting", {
+        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.log("[ToolProtectionService] Cache entry deleted", { 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,
             });
-            // Transform API response to internal format (same logic as getToolProtectionConfig)
-            const toolProtections = {};
-            if (response.data.toolProtections) {
-                for (const [toolName, toolConfig] of Object.entries(response.data.toolProtections)) {
-                    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 riskLevel = toolConfig.riskLevel ??
-                        toolConfig.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.name;
-                        if (!toolName)
-                            continue;
-                        const requiresDelegation = tool.requiresDelegation ??
-                            tool.requires_delegation ??
-                            false;
-                        const requiredScopes = tool.requiredScopes ??
-                            tool.required_scopes ??
-                            tool.scopes ??
-                            [];
-                        const oauthProvider = tool.oauthProvider ??
-                            tool.oauth_provider ??
-                            undefined;
-                        const riskLevel = tool.riskLevel ?? tool.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.requiresDelegation ??
-                            toolConfig.requires_delegation ??
-                            false;
-                        const requiredScopes = toolConfig.requiredScopes ??
-                            toolConfig.required_scopes ??
-                            toolConfig.scopes ??
-                            [];
-                        const oauthProvider = toolConfig.oauthProvider ??
-                            toolConfig.oauth_provider ??
-                            undefined;
-                        const riskLevel = toolConfig.riskLevel ??
-                            toolConfig.risk_level ??
-                            undefined;
-                        toolProtections[toolName] = {
-                            requiresDelegation,
-                            requiredScopes,
-                            ...(oauthProvider && { oauthProvider }),
-                            ...(riskLevel && { riskLevel }),
+            // 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,
+                toolProtections: mergedToolProtections,
             };
             // 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", {
+            console.error("[ToolProtectionService] Fresh config fetched and cached", {
                 cacheKey,
-                toolCount: Object.keys(toolProtections).length,
-                protectedTools: Object.entries(toolProtections)
+                toolCount: Object.keys(mergedToolProtections).length,
+                protectedTools: Object.entries(mergedToolProtections)
                     .filter(([_, cfg]) => cfg.requiresDelegation)
                     .map(([name]) => name),
                 source: "api",
@@ -807,16 +719,16 @@ class ToolProtectionService {
             return { config: freshConfig, cacheKey, source: "api" };
         }
         catch (error) {
-            console.warn("[ToolProtectionService] API fetch failed during refresh, using fallback", {
+            console.warn("[ToolProtectionService] API fetch failed during refresh, using offline fallback", {
                 error: error instanceof Error ? error.message : String(error),
                 cacheKey,
             });
-            // Use fallback config if API fails
-            const fallbackConfig = this.config
-                .fallbackConfig || {
+            // Use offline fallback config if API fails
+            const offlineFallback = this.config
+                .offlineFallbackConfig || {
                 toolProtections: {},
             };
-            return { config: fallbackConfig, cacheKey, source: "fallback" };
+            return { config: offlineFallback, cacheKey, source: "fallback" };
         }
     }
 }

package/dist/types/tool-protection.d.ts

@@ -46,17 +46,40 @@ export interface ToolProtectionServiceConfig {
      */
     cacheTtl?: number;
     /**
-     * Fallback configuration to use if API is unavailable
+     * Local/default configuration (LOWEST priority after defaults)
+     *
+     * This config serves as a base that gets OVERRIDDEN by remote config.
+     * Use this for development defaults or project-specific base settings.
+     *
+     * Precedence order (highest to lowest):
+     * 1. Remote config (AgentShield API) - WINS
+     * 2. Local config (this field)
+     * 3. Framework defaults
+     *
      * @optional
      */
-    fallbackConfig?: ToolProtectionConfig;
+    localConfig?: ToolProtectionConfig;
     /**
-     * Fail-safe behavior when API is unavailable and no fallback is provided
+     * Offline fallback configuration (ONLY used when API is unavailable)
+     *
+     * Unlike localConfig, this is NOT merged with remote config.
+     * It's only used as a complete replacement when the API cannot be reached.
+     *
+     * Fallback order when API fails:
+     * 1. Stale cache (if allowStaleCache=true and within maxStaleCacheAge)
+     * 2. This offlineFallbackConfig
+     * 3. failSafeBehavior (deny-all or allow-all)
+     *
+     * @optional
+     */
+    offlineFallbackConfig?: ToolProtectionConfig;
+    /**
+     * Fail-safe behavior when API is unavailable and no offline fallback is provided
      * - 'deny-all': Block all tools by default (secure, recommended for production)
      * - 'allow-all': Allow all tools (insecure, not recommended for production)
      * @default 'deny-all'
      */
-    failSafeBehavior?: 'deny-all' | 'allow-all';
+    failSafeBehavior?: "deny-all" | "allow-all";
     /**
      * Maximum age (in milliseconds) for stale cache to be used during outages
      * Stale cache is used when API fails and no fallback is provided