@kya-os/mcp-i-core 1.2.3-canary.6 → 1.3.0

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

@@ -0,0 +1,268 @@
+/**
+ * Tests for Remote Configuration Fetching
+ *
+ * Validates that remote config fetching works correctly with caching
+ * and fallback behavior.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  fetchRemoteConfig,
+  type RemoteConfigOptions,
+  type RemoteConfigCache
+} from '../remote-config.js';
+import type { MCPIConfig } from '@kya-os/contracts/config';
+
+describe('fetchRemoteConfig', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+  let mockCache: RemoteConfigCache;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    mockCache = {
+      get: vi.fn(),
+      set: vi.fn()
+    };
+  });
+
+  describe('Cache hit scenario', () => {
+    it('should return cached config if available and not expired', async () => {
+      const cachedConfig: MCPIConfig = {
+        environment: 'production',
+        identity: { enabled: true, environment: 'production' }
+      };
+
+      vi.mocked(mockCache.get).mockResolvedValue(
+        JSON.stringify({
+          config: cachedConfig,
+          expiresAt: Date.now() + 60000 // 1 minute in future
+        })
+      );
+
+      const options: RemoteConfigOptions = {
+        apiUrl: 'https://kya.vouched.id',
+        apiKey: 'test-key',
+        projectId: 'test-project',
+        fetchProvider: mockFetch
+      };
+
+      const result = await fetchRemoteConfig(options, mockCache);
+
+      expect(result).toEqual(cachedConfig);
+      expect(mockCache.get).toHaveBeenCalledWith('config:project:test-project');
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+
+    it('should fetch fresh config if cache expired', async () => {
+      const cachedConfig: MCPIConfig = {
+        environment: 'production'
+      };
+
+      vi.mocked(mockCache.get).mockResolvedValue(
+        JSON.stringify({
+          config: cachedConfig,
+          expiresAt: Date.now() - 1000 // Expired
+        })
+      );
+
+      const freshConfig: MCPIConfig = {
+        environment: 'production',
+        identity: { enabled: true, environment: 'production' }
+      };
+
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: async () => ({ success: true, data: freshConfig })
+      } 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).toEqual(freshConfig);
+      expect(mockFetch).toHaveBeenCalled();
+    });
+  });
+
+  describe('Cache miss scenario', () => {
+    it('should fetch from API when cache is empty', async () => {
+      vi.mocked(mockCache.get).mockResolvedValue(null);
+
+      const config: MCPIConfig = {
+        environment: 'production',
+        identity: { enabled: true, environment: 'production' }
+      };
+
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: async () => ({ success: true, data: config })
+      } 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).toEqual(config);
+      expect(mockCache.set).toHaveBeenCalled();
+    });
+
+    it('should use agentDid when projectId not available', async () => {
+      vi.mocked(mockCache.get).mockResolvedValue(null);
+
+      const config: MCPIConfig = {
+        environment: 'production'
+      };
+
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: async () => ({ success: true, data: config })
+      } as Response);
+
+      const options: RemoteConfigOptions = {
+        apiUrl: 'https://kya.vouched.id',
+        apiKey: 'test-key',
+        agentDid: 'did:key:test',
+        fetchProvider: mockFetch
+      };
+
+      const result = await fetchRemoteConfig(options, mockCache);
+
+      expect(result).toEqual(config);
+      expect(mockCache.get).toHaveBeenCalledWith('config:agent:did:key:test');
+    });
+  });
+
+  describe('Error handling', () => {
+    it('should return null if API request fails', async () => {
+      vi.mocked(mockCache.get).mockResolvedValue(null);
+
+      mockFetch.mockResolvedValue({
+        ok: false,
+        status: 404,
+        statusText: 'Not Found'
+      } 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).toBeNull();
+    });
+
+    it('should return null if API throws error', async () => {
+      vi.mocked(mockCache.get).mockResolvedValue(null);
+
+      mockFetch.mockRejectedValue(new Error('Network error'));
+
+      const options: RemoteConfigOptions = {
+        apiUrl: 'https://kya.vouched.id',
+        apiKey: 'test-key',
+        projectId: 'test-project',
+        fetchProvider: mockFetch
+      };
+
+      const result = await fetchRemoteConfig(options, mockCache);
+
+      expect(result).toBeNull();
+    });
+
+    it('should return null if neither projectId nor agentDid provided', async () => {
+      const options: RemoteConfigOptions = {
+        apiUrl: 'https://kya.vouched.id',
+        apiKey: 'test-key',
+        fetchProvider: mockFetch
+      };
+
+      const result = await fetchRemoteConfig(options, mockCache);
+
+      expect(result).toBeNull();
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+
+    it('should handle cache read errors gracefully', async () => {
+      vi.mocked(mockCache.get).mockRejectedValue(new Error('Cache error'));
+
+      const config: MCPIConfig = {
+        environment: 'production'
+      };
+
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: async () => ({ success: true, data: config })
+      } 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).toEqual(config);
+    });
+  });
+
+  describe('Response format handling', () => {
+    it('should handle different API response formats', async () => {
+      vi.mocked(mockCache.get).mockResolvedValue(null);
+
+      const config: MCPIConfig = {
+        environment: 'production'
+      };
+
+      // Format 1: { config: {...} }
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ config })
+      } as Response);
+
+      const options: RemoteConfigOptions = {
+        apiUrl: 'https://kya.vouched.id',
+        apiKey: 'test-key',
+        projectId: 'test-project',
+        fetchProvider: mockFetch
+      };
+
+      const result1 = await fetchRemoteConfig(options, mockCache);
+      expect(result1).toEqual(config);
+
+      // Format 2: { data: { config: {...} } }
+      mockCache.get.mockResolvedValue(null);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ data: { config } })
+      } as Response);
+
+      const result2 = await fetchRemoteConfig(options, mockCache);
+      expect(result2).toEqual(config);
+
+      // Format 3: { success: true, data: {...} }
+      mockCache.get.mockResolvedValue(null);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ success: true, data: config })
+      } as Response);
+
+      const result3 = await fetchRemoteConfig(options, mockCache);
+      expect(result3).toEqual(config);
+    });
+  });
+});
+

package/src/config/remote-config.ts

@@ -0,0 +1,174 @@
+/**
+ * Remote Configuration Fetching
+ *
+ * Service for fetching configuration from remote APIs (AgentShield dashboard)
+ * with caching support for performance optimization.
+ *
+ * @module @kya-os/mcp-i-core/config/remote-config
+ */
+
+import type { MCPIConfig } from '@kya-os/contracts/config';
+import { AGENTSHIELD_ENDPOINTS } from '@kya-os/contracts/agentshield-api';
+
+/**
+ * Options for fetching remote configuration
+ */
+export interface RemoteConfigOptions {
+  /**
+   * API base URL
+   * @example 'https://kya.vouched.id'
+   */
+  apiUrl: string;
+
+  /**
+   * API key for authentication
+   */
+  apiKey: string;
+
+  /**
+   * Project ID (optional, preferred over agentDid)
+   * Used for project-scoped configuration
+   */
+  projectId?: string;
+
+  /**
+   * Agent DID (optional, used when projectId not available)
+   * Used for agent-scoped configuration
+   */
+  agentDid?: string;
+
+  /**
+   * Cache TTL in milliseconds
+   * @default 300000 (5 minutes)
+   */
+  cacheTtl?: number;
+
+  /**
+   * Fetch provider function
+   * Platform-agnostic fetch implementation
+   */
+  fetchProvider: (url: string, options: RequestInit) => Promise<Response>;
+}
+
+/**
+ * Cache interface for remote configuration
+ * Abstracts platform-specific caching (KV, Redis, Memory, etc.)
+ */
+export interface RemoteConfigCache {
+  /**
+   * Get a cached value
+   */
+  get(key: string): Promise<string | null>;
+
+  /**
+   * Set a cached value with TTL
+   */
+  set(key: string, value: string, ttl: number): Promise<void>;
+}
+
+/**
+ * Fetch configuration from remote API (AgentShield dashboard)
+ *
+ * Attempts to fetch configuration from the AgentShield API with caching support.
+ * Falls back gracefully if remote fetch fails.
+ *
+ * @param options - Remote config options
+ * @param cache - Optional cache implementation
+ * @returns Configuration object or null if fetch fails
+ */
+export async function fetchRemoteConfig(
+  options: RemoteConfigOptions,
+  cache?: RemoteConfigCache
+): Promise<MCPIConfig | null> {
+  const { apiUrl, apiKey, projectId, agentDid, cacheTtl = 300000, fetchProvider } = options;
+
+  // Generate cache key
+  const cacheKey = projectId 
+    ? `config:project:${projectId}`
+    : agentDid 
+    ? `config:agent:${agentDid}`
+    : null;
+
+  // Try cache first
+  if (cache && cacheKey) {
+    try {
+      const cached = await cache.get(cacheKey);
+      if (cached) {
+        try {
+          const parsed = JSON.parse(cached) as { config: MCPIConfig; expiresAt: number };
+          if (parsed.expiresAt > Date.now()) {
+            return parsed.config;
+          }
+        } catch {
+          // Invalid cache entry, continue to fetch
+        }
+      }
+    } catch (error) {
+      // Cache read failed, continue to fetch
+      console.warn('[RemoteConfig] Cache read failed:', error);
+    }
+  }
+
+  // Fetch from API
+  try {
+    // Build API URL
+    let url: string;
+    if (projectId) {
+      // Use project-scoped endpoint (preferred)
+      url = `${apiUrl}${AGENTSHIELD_ENDPOINTS.CONFIG(projectId)}`;
+    } else if (agentDid) {
+      // Use agent-scoped endpoint
+      url = `${apiUrl}/api/v1/bouncer/config?agent_did=${encodeURIComponent(agentDid)}`;
+    } else {
+      console.warn('[RemoteConfig] Neither projectId nor agentDid provided');
+      return null;
+    }
+
+    const response = await fetchProvider(url, {
+      headers: {
+        'Authorization': `Bearer ${apiKey}`,
+        'Content-Type': 'application/json'
+      }
+    });
+
+    if (!response.ok) {
+      console.warn(`[RemoteConfig] API returned ${response.status}: ${response.statusText}`);
+      return null;
+    }
+
+    const data = await response.json();
+    
+    // Extract config from API response
+    // API response format: { success: boolean, data: { config: MCPIConfig } }
+    const responseData = data as { config?: MCPIConfig; data?: { config?: MCPIConfig }; success?: boolean };
+    const config = responseData.config || responseData.data?.config || (responseData.success ? responseData.data as MCPIConfig | null : null) as MCPIConfig | null;
+
+    if (!config) {
+      console.warn('[RemoteConfig] No config found in API response');
+      return null;
+    }
+
+    // Cache the result
+    if (cache && cacheKey) {
+      try {
+        await cache.set(
+          cacheKey,
+          JSON.stringify({
+            config,
+            expiresAt: Date.now() + cacheTtl
+          }),
+          cacheTtl
+        );
+      } catch (error) {
+        // Cache write failed, but we got the config so continue
+        console.warn('[RemoteConfig] Cache write failed:', error);
+      }
+    }
+
+    return config as MCPIConfig;
+  } catch (error) {
+    console.warn('[RemoteConfig] Failed to fetch config:', error);
+    return null;
+  }
+}
+