@kya-os/mcp-i-core 1.3.10-canary.clientinfo.20251126124133 → 1.3.11

package/src/config/__tests__/merged-config.spec.ts

@@ -0,0 +1,445 @@
+/**
+ * Tests for Merged Configuration Handling
+ *
+ * TDD tests for the merged config API response format where tool protections
+ * are embedded in the config at `toolProtection.tools`.
+ *
+ * These tests document the expected behavior BEFORE implementation.
+ *
+ * @since 1.6.0
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  fetchRemoteConfig,
+  type RemoteConfigOptions,
+  type RemoteConfigCache
+} from '../remote-config.js';
+import type { MergedMCPIServerConfig } from '@kya-os/contracts/dashboard-config';
+
+describe('fetchRemoteConfig - Merged Config Format', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+  let mockCache: RemoteConfigCache;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    mockCache = {
+      get: vi.fn(),
+      set: vi.fn()
+    };
+  });
+
+  describe('Embedded tool protections', () => {
+    it('should handle merged config with toolProtection.tools field', async () => {
+      vi.mocked(mockCache.get).mockResolvedValue(null);
+
+      const mergedConfig: MergedMCPIServerConfig = {
+        identity: {
+          serverDid: 'did:key:test',
+          environment: 'production',
+          storageLocation: 'cloudflare-kv'
+        },
+        proofing: {
+          enabled: true,
+          destinations: [],
+          batchQueue: { maxBatchSize: 10, flushIntervalMs: 5000, maxRetries: 3 }
+        },
+        delegation: {
+          enabled: true,
+          enforceStrictly: true,
+          verifier: { type: 'agentshield' },
+          authorization: {}
+        },
+        toolProtection: {
+          source: 'agentshield',
+          tools: {
+            greet: {
+              requiresDelegation: true,
+              requiredScopes: ['greeting:write'],
+              riskLevel: 'low'
+            },
+            checkout: {
+              requiresDelegation: true,
+              requiredScopes: ['checkout:execute', 'payment:write'],
+              riskLevel: 'high'
+            }
+          }
+        },
+        audit: {
+          enabled: true,
+          includeProofHashes: true,
+          includePayloads: false
+        },
+        session: {
+          timestampSkewSeconds: 120,
+          ttlMinutes: 30
+        },
+        platform: {
+          type: 'cloudflare'
+        },
+        metadata: {
+          version: '1.6.0',
+          lastUpdated: new Date().toISOString(),
+          source: 'dashboard'
+        }
+      };
+
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          success: true,
+          data: { config: mergedConfig }
+        })
+      } as Response);
+
+      const options: RemoteConfigOptions = {
+        apiUrl: 'https://kya.vouched.id',
+        apiKey: 'test-key',
+        projectId: 'test-project',
+        fetchProvider: mockFetch
+      };
+
+      const result = await fetchRemoteConfig(options, mockCache);
+
+      expect(result).toBeDefined();
+      // The toolProtection.tools should be accessible
+      expect(result?.toolProtection?.tools).toBeDefined();
+      expect(result?.toolProtection?.tools?.greet).toEqual({
+        requiresDelegation: true,
+        requiredScopes: ['greeting:write'],
+        riskLevel: 'low'
+      });
+      expect(result?.toolProtection?.tools?.checkout).toEqual({
+        requiresDelegation: true,
+        requiredScopes: ['checkout:execute', 'payment:write'],
+        riskLevel: 'high'
+      });
+    });
+
+    it('should handle empty tools object when no tools discovered', async () => {
+      vi.mocked(mockCache.get).mockResolvedValue(null);
+
+      const mergedConfig = {
+        identity: {
+          serverDid: 'did:key:test',
+          environment: 'production',
+          storageLocation: 'cloudflare-kv'
+        },
+        proofing: {
+          enabled: false,
+          destinations: [],
+          batchQueue: { maxBatchSize: 10, flushIntervalMs: 5000, maxRetries: 3 }
+        },
+        delegation: {
+          enabled: false,
+          enforceStrictly: false,
+          verifier: { type: 'memory' },
+          authorization: {}
+        },
+        toolProtection: {
+          source: 'agentshield',
+          tools: {} // Empty - no tools discovered yet
+        },
+        audit: {
+          enabled: false,
+          includeProofHashes: false,
+          includePayloads: false
+        },
+        session: {
+          timestampSkewSeconds: 120,
+          ttlMinutes: 30
+        },
+        platform: {
+          type: 'node'
+        },
+        metadata: {
+          version: '1.6.0',
+          lastUpdated: new Date().toISOString(),
+          source: 'dashboard'
+        }
+      };
+
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          success: true,
+          data: { config: mergedConfig }
+        })
+      } as Response);
+
+      const options: RemoteConfigOptions = {
+        apiUrl: 'https://kya.vouched.id',
+        apiKey: 'test-key',
+        projectId: 'test-project',
+        fetchProvider: mockFetch
+      };
+
+      const result = await fetchRemoteConfig(options, mockCache);
+
+      expect(result).toBeDefined();
+      expect(result?.toolProtection?.tools).toEqual({});
+    });
+
+    it('should gracefully handle missing tools field for backward compatibility', async () => {
+      vi.mocked(mockCache.get).mockResolvedValue(null);
+
+      // Old API format without tools field
+      const oldFormatConfig = {
+        identity: {
+          serverDid: 'did:key:test',
+          environment: 'production',
+          storageLocation: 'cloudflare-kv'
+        },
+        proofing: {
+          enabled: false,
+          destinations: [],
+          batchQueue: { maxBatchSize: 10, flushIntervalMs: 5000, maxRetries: 3 }
+        },
+        delegation: {
+          enabled: false,
+          enforceStrictly: false,
+          verifier: { type: 'memory' },
+          authorization: {}
+        },
+        toolProtection: {
+          source: 'agentshield'
+          // No tools field - old format
+        },
+        audit: {
+          enabled: false,
+          includeProofHashes: false,
+          includePayloads: false
+        },
+        session: {
+          timestampSkewSeconds: 120,
+          ttlMinutes: 30
+        },
+        platform: {
+          type: 'node'
+        },
+        metadata: {
+          version: '1.5.0',
+          lastUpdated: new Date().toISOString(),
+          source: 'dashboard'
+        }
+      };
+
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          success: true,
+          data: { config: oldFormatConfig }
+        })
+      } as Response);
+
+      const options: RemoteConfigOptions = {
+        apiUrl: 'https://kya.vouched.id',
+        apiKey: 'test-key',
+        projectId: 'test-project',
+        fetchProvider: mockFetch
+      };
+
+      const result = await fetchRemoteConfig(options, mockCache);
+
+      // Should not throw and should return config (implementation will add empty tools)
+      expect(result).toBeDefined();
+      // Current implementation doesn't handle this - test documents expected behavior
+      // After implementation, toolProtection.tools should default to {}
+    });
+  });
+
+  describe('Response format with embedded tools', () => {
+    it('should handle response with deprecated top-level toolProtections field', async () => {
+      vi.mocked(mockCache.get).mockResolvedValue(null);
+
+      const mergedConfig = {
+        identity: {
+          serverDid: 'did:key:test',
+          environment: 'production',
+          storageLocation: 'cloudflare-kv'
+        },
+        proofing: {
+          enabled: false,
+          destinations: [],
+          batchQueue: { maxBatchSize: 10, flushIntervalMs: 5000, maxRetries: 3 }
+        },
+        delegation: {
+          enabled: false,
+          enforceStrictly: false,
+          verifier: { type: 'memory' },
+          authorization: {}
+        },
+        toolProtection: {
+          source: 'agentshield',
+          tools: {
+            greet: { requiresDelegation: true, requiredScopes: ['greeting:write'] }
+          }
+        },
+        audit: {
+          enabled: false,
+          includeProofHashes: false,
+          includePayloads: false
+        },
+        session: {
+          timestampSkewSeconds: 120,
+          ttlMinutes: 30
+        },
+        platform: {
+          type: 'node'
+        },
+        metadata: {
+          version: '1.6.0',
+          lastUpdated: new Date().toISOString(),
+          source: 'dashboard'
+        }
+      };
+
+      // Response includes both embedded tools and deprecated top-level field
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          success: true,
+          data: {
+            config: mergedConfig,
+            // Deprecated: This field exists for backward compatibility
+            toolProtections: {
+              greet: { requiresDelegation: true, requiredScopes: ['greeting:write'] }
+            }
+          },
+          metadata: {
+            timestamp: new Date().toISOString(),
+            cachedUntil: new Date(Date.now() + 60000).toISOString()
+          }
+        })
+      } as Response);
+
+      const options: RemoteConfigOptions = {
+        apiUrl: 'https://kya.vouched.id',
+        apiKey: 'test-key',
+        projectId: 'test-project',
+        fetchProvider: mockFetch
+      };
+
+      const result = await fetchRemoteConfig(options, mockCache);
+
+      expect(result).toBeDefined();
+      // Should use config.toolProtection.tools (embedded), not top-level toolProtections
+      expect(result?.toolProtection?.tools?.greet).toEqual({
+        requiresDelegation: true,
+        requiredScopes: ['greeting:write']
+      });
+    });
+  });
+
+  describe('Caching with merged config', () => {
+    it('should cache merged config correctly', async () => {
+      vi.mocked(mockCache.get).mockResolvedValue(null);
+
+      const mergedConfig = {
+        identity: {
+          serverDid: 'did:key:test',
+          environment: 'production',
+          storageLocation: 'cloudflare-kv'
+        },
+        proofing: {
+          enabled: false,
+          destinations: [],
+          batchQueue: { maxBatchSize: 10, flushIntervalMs: 5000, maxRetries: 3 }
+        },
+        delegation: {
+          enabled: false,
+          enforceStrictly: false,
+          verifier: { type: 'memory' },
+          authorization: {}
+        },
+        toolProtection: {
+          source: 'agentshield',
+          tools: {
+            greet: { requiresDelegation: true, requiredScopes: ['greeting:write'] }
+          }
+        },
+        audit: {
+          enabled: false,
+          includeProofHashes: false,
+          includePayloads: false
+        },
+        session: {
+          timestampSkewSeconds: 120,
+          ttlMinutes: 30
+        },
+        platform: {
+          type: 'node'
+        },
+        metadata: {
+          version: '1.6.0',
+          lastUpdated: new Date().toISOString(),
+          source: 'dashboard'
+        }
+      };
+
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          success: true,
+          data: { config: mergedConfig }
+        })
+      } as Response);
+
+      const options: RemoteConfigOptions = {
+        apiUrl: 'https://kya.vouched.id',
+        apiKey: 'test-key',
+        projectId: 'test-project',
+        fetchProvider: mockFetch,
+        cacheTtl: 300000
+      };
+
+      await fetchRemoteConfig(options, mockCache);
+
+      expect(mockCache.set).toHaveBeenCalledWith(
+        'config:project:test-project',
+        expect.stringContaining('toolProtection'),
+        300000
+      );
+    });
+
+    it('should return cached merged config with embedded tools', async () => {
+      const cachedConfig = {
+        identity: {
+          serverDid: 'did:key:test',
+          environment: 'production',
+          storageLocation: 'cloudflare-kv'
+        },
+        toolProtection: {
+          source: 'agentshield',
+          tools: {
+            greet: { requiresDelegation: true, requiredScopes: ['greeting:write'] }
+          }
+        },
+        // ... other fields
+      };
+
+      vi.mocked(mockCache.get).mockResolvedValue(
+        JSON.stringify({
+          config: cachedConfig,
+          expiresAt: Date.now() + 60000
+        })
+      );
+
+      const options: RemoteConfigOptions = {
+        apiUrl: 'https://kya.vouched.id',
+        apiKey: 'test-key',
+        projectId: 'test-project',
+        fetchProvider: mockFetch
+      };
+
+      const result = await fetchRemoteConfig(options, mockCache);
+
+      expect(result?.toolProtection?.tools?.greet).toEqual({
+        requiresDelegation: true,
+        requiredScopes: ['greeting:write']
+      });
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+  });
+});
+

package/src/config/remote-config.ts

@@ -8,6 +8,8 @@
  */
 
 import type { MCPIConfig } from '@kya-os/contracts/config';
+import type { MergedMCPIServerConfig } from '@kya-os/contracts/dashboard-config';
+import type { ToolProtection, ToolProtectionMap } from '@kya-os/contracts/tool-protection';
 import { AGENTSHIELD_ENDPOINTS } from '@kya-os/contracts/agentshield-api';
 
 /**
@@ -172,3 +174,91 @@ export async function fetchRemoteConfig(
   }
 }
 
+/**
+ * Get tool protection for a specific tool from a merged config
+ *
+ * This helper function extracts tool protection from a merged config response.
+ * It handles both the new format (toolProtection.tools) and returns null
+ * for unprotected or unknown tools.
+ *
+ * @param config - Merged config object (must have toolProtection.tools)
+ * @param toolName - Name of the tool to look up
+ * @returns Tool protection or null if tool not protected or not found
+ *
+ * @since 1.6.0
+ */
+export function getToolProtection(
+  config: { toolProtection?: { tools?: ToolProtectionMap } },
+  toolName: string
+): ToolProtection | null {
+  const tools = config?.toolProtection?.tools;
+  
+  if (!tools) {
+    return null;
+  }
+
+  // Check for specific tool protection first
+  let protection = tools[toolName];
+  
+  // Fall back to wildcard protection if specific tool not found
+  if (!protection && tools['*']) {
+    protection = tools['*'];
+  }
+  
+  // Return null for unprotected tools (requiresDelegation: false) or unknown tools
+  if (!protection || !protection.requiresDelegation) {
+    return null;
+  }
+  
+  return protection;
+}
+
+/**
+ * Extract tool protections map from merged config
+ *
+ * This helper function extracts the tool protections map from a merged config.
+ * Returns an empty object if no tools are found.
+ *
+ * @param config - Config object that may contain toolProtection.tools
+ * @returns Tool protection map or empty object
+ *
+ * @since 1.6.0
+ */
+export function extractToolProtections(
+  config: { toolProtection?: { tools?: ToolProtectionMap } } | null | undefined
+): ToolProtectionMap {
+  if (!config?.toolProtection?.tools) {
+    return {};
+  }
+  return config.toolProtection.tools;
+}
+
+/**
+ * Check if config has embedded tool protections
+ *
+ * Utility to check if a config response is in the new merged format
+ * with embedded tool protections.
+ *
+ * @param config - Config object to check
+ * @returns True if config has embedded tools, false otherwise
+ *
+ * @since 1.6.0
+ */
+export function hasMergedToolProtections(
+  config: unknown
+): config is { toolProtection: { tools: ToolProtectionMap } } {
+  if (!config || typeof config !== 'object') {
+    return false;
+  }
+  
+  const c = config as { toolProtection?: { tools?: unknown } };
+  return (
+    c.toolProtection !== undefined &&
+    typeof c.toolProtection === 'object' &&
+    c.toolProtection !== null &&
+    'tools' in c.toolProtection &&
+    typeof c.toolProtection.tools === 'object' &&
+    c.toolProtection.tools !== null // typeof null === 'object' in JS
+  );
+}
+

package/src/config.ts

@@ -274,6 +274,9 @@ export type {
  */
 export {
   fetchRemoteConfig,
+  getToolProtection,
+  extractToolProtections,
+  hasMergedToolProtections,
   type RemoteConfigOptions,
   type RemoteConfigCache
 } from './config/remote-config';