@kya-os/mcp-i-core 1.3.7-canary.0 → 1.3.7-canary.clientinfo.20251126041014

package/src/services/oauth-config.service.d.ts

@@ -0,0 +1,53 @@
+/**
+ * OAuth Config Service
+ *
+ * Fetches and caches OAuth provider configurations from AgentShield API.
+ * Provides caching with TTL to reduce API calls.
+ *
+ * @package @kya-os/mcp-i-core
+ */
+import type { FetchProvider } from "../providers/base.js";
+import type { OAuthConfig } from "@kya-os/contracts/config";
+import type { OAuthConfigCache } from "../cache/oauth-config-cache.js";
+export interface OAuthConfigServiceConfig {
+    /** Base URL for AgentShield API (e.g., "https://kya.vouched.id") */
+    baseUrl: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Fetch provider for making HTTP requests */
+    fetchProvider: FetchProvider;
+    /** Cache implementation (defaults to in-memory) */
+    cache?: OAuthConfigCache;
+    /** Cache TTL in milliseconds (default: 5 minutes) */
+    cacheTtl?: number;
+    /** Optional logger callback for diagnostics */
+    logger?: (message: string, data?: unknown) => void;
+}
+/**
+ * Service for fetching OAuth provider configurations from AgentShield API
+ */
+export declare class OAuthConfigService {
+    private config;
+    constructor(config: OAuthConfigServiceConfig);
+    /**
+     * Get OAuth configuration for a project
+     *
+     * Fetches from AgentShield API: GET /api/v1/bouncer/projects/{projectId}/providers
+     * Caches responses with TTL to reduce API calls.
+     *
+     * @param projectId - Project ID to fetch config for
+     * @returns OAuth configuration with providers object
+     */
+    getOAuthConfig(projectId: string): Promise<OAuthConfig>;
+    /**
+     * Clear cached config for a project
+     *
+     * @param projectId - Project ID to clear cache for
+     */
+    clearCache(projectId: string): Promise<void>;
+    /**
+     * Clear all cached configs
+     */
+    clearAllCache(): Promise<void>;
+}
+//# sourceMappingURL=oauth-config.service.d.ts.map

package/src/services/oauth-config.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-config.service.d.ts","sourceRoot":"","sources":["oauth-config.service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAiB,MAAM,0BAA0B,CAAC;AAC3E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAGvE,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAEhB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IAEf,8CAA8C;IAC9C,aAAa,EAAE,aAAa,CAAC;IAE7B,mDAAmD;IACnD,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAEzB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACpD;AAED;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAGZ;gBAEU,MAAM,EAAE,wBAAwB;IAW5C;;;;;;;;OAQG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAoF7D;;;;OAIG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlD;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;CAIrC"}

package/src/services/oauth-config.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-config.service.js","sourceRoot":"","sources":["oauth-config.service.ts"],"names":[],"mappings":"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"}

package/src/services/oauth-config.service.ts

@@ -0,0 +1,192 @@
+/**
+ * OAuth Config Service
+ *
+ * Fetches and caches OAuth provider configurations from AgentShield API.
+ * Provides caching with TTL to reduce API calls.
+ *
+ * @package @kya-os/mcp-i-core
+ */
+
+import type { FetchProvider } from "../providers/base.js";
+import type { OAuthConfig, OAuthProvider } from "@kya-os/contracts/config";
+import type { OAuthConfigCache } from "../cache/oauth-config-cache.js";
+import { InMemoryOAuthConfigCache } from "../cache/oauth-config-cache.js";
+
+export interface OAuthConfigServiceConfig {
+  /** Base URL for AgentShield API (e.g., "https://kya.vouched.id") */
+  baseUrl: string;
+
+  /** API key for authentication */
+  apiKey: string;
+
+  /** Fetch provider for making HTTP requests */
+  fetchProvider: FetchProvider;
+
+  /** Cache implementation (defaults to in-memory) */
+  cache?: OAuthConfigCache;
+
+  /** Cache TTL in milliseconds (default: 5 minutes) */
+  cacheTtl?: number;
+
+  /** Optional logger callback for diagnostics */
+  logger?: (message: string, data?: unknown) => void;
+}
+
+/**
+ * Service for fetching OAuth provider configurations from AgentShield API
+ */
+export class OAuthConfigService {
+  private config: Required<Omit<OAuthConfigServiceConfig, "logger" | "cache">> & {
+    logger: (message: string, data?: unknown) => void;
+    cache: OAuthConfigCache;
+  };
+
+  constructor(config: OAuthConfigServiceConfig) {
+    this.config = {
+      baseUrl: config.baseUrl,
+      apiKey: config.apiKey,
+      fetchProvider: config.fetchProvider,
+      cacheTtl: config.cacheTtl ?? 5 * 60 * 1000, // Default 5 minutes
+      logger: config.logger || (() => {}),
+      cache: config.cache || new InMemoryOAuthConfigCache(),
+    };
+  }
+
+  /**
+   * Get OAuth configuration for a project
+   *
+   * Fetches from AgentShield API: GET /api/v1/bouncer/projects/{projectId}/providers
+   * Caches responses with TTL to reduce API calls.
+   *
+   * @param projectId - Project ID to fetch config for
+   * @returns OAuth configuration with providers object
+   */
+  async getOAuthConfig(projectId: string): Promise<OAuthConfig> {
+    // Check cache
+    const cached = await this.config.cache.get(projectId);
+    if (cached) {
+      this.config.logger("[OAuthConfigService] Cache hit", {
+        projectId,
+      });
+      return cached;
+    }
+
+    // Fetch from AgentShield API
+    const url = `${this.config.baseUrl}/api/v1/bouncer/projects/${encodeURIComponent(projectId)}/providers`;
+
+    this.config.logger("[OAuthConfigService] Fetching config from API", {
+      projectId,
+      url,
+    });
+
+    try {
+      const response = await this.config.fetchProvider.fetch(url, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${this.config.apiKey}`,
+          "Content-Type": "application/json",
+        },
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text().catch(() => "Unknown error");
+        throw new Error(
+          `Failed to fetch OAuth config: ${response.status} ${response.statusText} - ${errorText}`
+        );
+      }
+
+      const result = await response.json() as {
+        success: boolean;
+        data?: {
+          providers?: Record<string, unknown>;
+          configuredProvider?: string | null;
+        };
+      };
+
+      // Validate response structure
+      if (!result.success || !result.data) {
+        throw new Error("Invalid API response: missing success or data field");
+      }
+
+      // Parse providers object with snake_case → camelCase mapping
+      // AgentShield API may return snake_case fields, but OAuthProvider interface uses camelCase
+      const rawProviders = result.data.providers || {};
+      if (typeof rawProviders !== "object" || Array.isArray(rawProviders)) {
+        throw new Error(
+          "Invalid API response: providers must be an object, not an array"
+        );
+      }
+
+      // Map each provider's fields from snake_case to camelCase
+      const providers: Record<string, OAuthProvider> = {};
+      for (const [name, raw] of Object.entries(rawProviders)) {
+        const p = raw as Record<string, unknown>;
+        providers[name] = {
+          clientId: (p.clientId ?? p.client_id ?? "") as string,
+          clientSecret: (p.clientSecret ?? p.client_secret ?? null) as string | null,
+          authorizationUrl: (p.authorizationUrl ?? p.authorization_url ?? "") as string,
+          tokenUrl: (p.tokenUrl ?? p.token_url ?? "") as string,
+          userInfoUrl: (p.userInfoUrl ?? p.user_info_url) as string | undefined,
+          supportsPKCE: (p.supportsPKCE ?? p.supports_pkce ?? false) as boolean,
+          requiresClientSecret: (p.requiresClientSecret ?? p.requires_client_secret ?? true) as boolean,
+          scopes: (p.scopes ?? []) as string[],
+          defaultScopes: (p.defaultScopes ?? p.default_scopes) as string[] | undefined,
+          proxyMode: (p.proxyMode ?? p.proxy_mode ?? false) as boolean,
+          customParams: (p.customParams ?? p.custom_params) as Record<string, string> | undefined,
+          tokenEndpointAuthMethod: (p.tokenEndpointAuthMethod ?? p.token_endpoint_auth_method) as "client_secret_post" | "client_secret_basic" | undefined,
+          responseType: (p.responseType ?? p.response_type) as string | undefined,
+          grantType: (p.grantType ?? p.grant_type) as string | undefined,
+        };
+      }
+
+      // Build OAuthConfig object
+      // Extract configuredProvider from API response - this indicates which provider
+      // the user has actually configured in AgentShield dashboard
+      const configuredProvider = result.data.configuredProvider ?? (result.data as any).configured_provider ?? null;
+      const config: OAuthConfig = {
+        providers,
+        configuredProvider,
+      };
+
+      // Cache config
+      await this.config.cache.set(projectId, config, this.config.cacheTtl);
+
+      this.config.logger("[OAuthConfigService] Config fetched and cached", {
+        projectId,
+        providerCount: Object.keys(providers).length,
+        providers: Object.keys(providers),
+        configuredProvider,
+        expiresAt: new Date(
+          Date.now() + this.config.cacheTtl
+        ).toISOString(),
+      });
+
+      return config;
+    } catch (error) {
+      this.config.logger("[OAuthConfigService] API fetch failed", {
+        projectId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Clear cached config for a project
+   *
+   * @param projectId - Project ID to clear cache for
+   */
+  async clearCache(projectId: string): Promise<void> {
+    await this.config.cache.delete(projectId);
+    this.config.logger("[OAuthConfigService] Cache cleared", { projectId });
+  }
+
+  /**
+   * Clear all cached configs
+   */
+  async clearAllCache(): Promise<void> {
+    await this.config.cache.clear();
+    this.config.logger("[OAuthConfigService] All cache cleared");
+  }
+}
+

package/src/services/oauth-provider-registry.d.ts

@@ -0,0 +1,57 @@
+/**
+ * OAuth Provider Registry
+ *
+ * Manages OAuth provider configurations loaded from AgentShield API.
+ * Provides efficient lookup and caching of provider configurations.
+ *
+ * @package @kya-os/mcp-i-core
+ */
+import type { OAuthProvider } from "@kya-os/contracts/config";
+import type { OAuthConfigService } from "./oauth-config.service.js";
+/**
+ * Registry for OAuth providers
+ *
+ * Wraps OAuthConfigService to provide a simple lookup interface
+ * for provider configurations.
+ */
+export declare class OAuthProviderRegistry {
+    private configService;
+    private providers;
+    constructor(configService: OAuthConfigService);
+    /**
+     * Load providers from AgentShield API
+     *
+     * Fetches OAuth configuration and caches providers in memory.
+     * Clears existing providers before loading new ones.
+     *
+     * @param projectId - Project ID to load providers for
+     */
+    loadFromAgentShield(projectId: string): Promise<void>;
+    /**
+     * Get provider by name
+     *
+     * @param name - Provider name (e.g., "github", "google")
+     * @returns Provider configuration or null if not found
+     */
+    getProvider(name: string): OAuthProvider | null;
+    /**
+     * Get all providers
+     *
+     * @returns Array of all registered provider configurations
+     */
+    getAllProviders(): OAuthProvider[];
+    /**
+     * Check if provider exists
+     *
+     * @param name - Provider name to check
+     * @returns True if provider is registered, false otherwise
+     */
+    hasProvider(name: string): boolean;
+    /**
+     * Get all provider names
+     *
+     * @returns Array of provider names
+     */
+    getProviderNames(): string[];
+}
+//# sourceMappingURL=oauth-provider-registry.d.ts.map

package/src/services/oauth-provider-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-provider-registry.d.ts","sourceRoot":"","sources":["oauth-provider-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEpE;;;;;GAKG;AACH,qBAAa,qBAAqB;IAGpB,OAAO,CAAC,aAAa;IAFjC,OAAO,CAAC,SAAS,CAAyC;gBAEtC,aAAa,EAAE,kBAAkB;IAErD;;;;;;;OAOG;IACG,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY3D;;;;;OAKG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAI/C;;;;OAIG;IACH,eAAe,IAAI,aAAa,EAAE;IAIlC;;;;;OAKG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIlC;;;;OAIG;IACH,gBAAgB,IAAI,MAAM,EAAE;CAG7B"}

package/src/services/oauth-provider-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-provider-registry.js","sourceRoot":"","sources":["oauth-provider-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;;;;GAKG;AACH,MAAM,OAAO,qBAAqB;IAGZ;IAFZ,SAAS,GAA+B,IAAI,GAAG,EAAE,CAAC;IAE1D,YAAoB,aAAiC;QAAjC,kBAAa,GAAb,aAAa,CAAoB;IAAG,CAAC;IAEzD;;;;;;;OAOG;IACH,KAAK,CAAC,mBAAmB,CAAC,SAAiB;QACzC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;QAElE,2BAA2B;QAC3B,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QAEvB,qCAAqC;QACrC,KAAK,MAAM,CAAC,IAAI,EAAE,cAAc,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;YACtE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,WAAW,CAAC,IAAY;QACtB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACH,eAAe;QACb,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;OAKG;IACH,WAAW,CAAC,IAAY;QACtB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACH,gBAAgB;QACd,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3C,CAAC;CACF"}

package/src/services/oauth-provider-registry.ts

@@ -0,0 +1,141 @@
+/**
+ * OAuth Provider Registry
+ *
+ * Manages OAuth provider configurations loaded from AgentShield API.
+ * Provides efficient lookup and caching of provider configurations.
+ *
+ * @package @kya-os/mcp-i-core
+ */
+
+import type { OAuthProvider } from "@kya-os/contracts/config";
+import type { OAuthConfigService } from "./oauth-config.service.js";
+import type { ProviderValidator } from "./provider-validator.js";
+
+/**
+ * Registry for OAuth providers
+ *
+ * Wraps OAuthConfigService to provide a simple lookup interface
+ * for provider configurations.
+ */
+export class OAuthProviderRegistry {
+  private providers: Map<string, OAuthProvider> = new Map();
+  private _configuredProvider: string | null = null;
+
+  constructor(
+    private configService: OAuthConfigService,
+    private validator?: ProviderValidator
+  ) {}
+
+  /**
+   * Load providers from AgentShield API
+   *
+   * Fetches OAuth configuration and caches providers in memory.
+   * Clears existing providers before loading new ones.
+   * Also stores the configured provider from the API response.
+   *
+   * @param projectId - Project ID to load providers for
+   */
+  async loadFromAgentShield(projectId: string): Promise<void> {
+    const config = await this.configService.getOAuthConfig(projectId);
+
+    // Clear existing providers
+    this.providers.clear();
+
+    // Store the configured provider from API response
+    // This is the provider the user has explicitly configured in AgentShield dashboard
+    this._configuredProvider = config.configuredProvider || null;
+
+    // Register all providers from config
+    for (const [name, providerConfig] of Object.entries(config.providers)) {
+      this.providers.set(name, providerConfig);
+    }
+  }
+
+  /**
+   * Get the explicitly configured provider for this project
+   *
+   * Returns the provider that the user has configured in AgentShield dashboard.
+   * Used by ProviderResolver as fallback when tool doesn't specify oauthProvider.
+   *
+   * @returns Configured provider name, or null if no provider is configured
+   */
+  getConfiguredProvider(): string | null {
+    return this._configuredProvider;
+  }
+
+  /**
+   * Get provider by name
+   *
+   * @param name - Provider name (e.g., "github", "google")
+   * @returns Provider configuration or null if not found
+   */
+  getProvider(name: string): OAuthProvider | null {
+    return this.providers.get(name) || null;
+  }
+
+  /**
+   * Get all providers
+   *
+   * @returns Array of all registered provider configurations
+   */
+  getAllProviders(): OAuthProvider[] {
+    return Array.from(this.providers.values());
+  }
+
+  /**
+   * Check if provider exists
+   *
+   * @param name - Provider name to check
+   * @returns True if provider is registered, false otherwise
+   */
+  hasProvider(name: string): boolean {
+    return this.providers.has(name);
+  }
+
+  /**
+   * Get all provider names
+   *
+   * @returns Array of provider names
+   */
+  getProviderNames(): string[] {
+    return Array.from(this.providers.keys());
+  }
+
+  /**
+   * Register a custom provider with validation
+   *
+   * @param name - Provider name (e.g., "custom-idp")
+   * @param provider - Provider configuration
+   * @throws ProviderValidationError if validation fails
+   */
+  registerCustomProvider(name: string, provider: OAuthProvider): void {
+    // Validate provider configuration if validator is available
+    if (this.validator) {
+      this.validator.validate(provider, name);
+    }
+
+    // Register provider
+    this.providers.set(name, provider);
+  }
+
+  /**
+   * Get provider with custom parameters merged
+   *
+   * Convenience method that returns provider config with custom parameters
+   * already applied to authorization URL building context.
+   *
+   * @param name - Provider name
+   * @returns Provider configuration with custom params, or null if not found
+   */
+  getProviderWithParams(name: string): OAuthProvider | null {
+    const provider = this.getProvider(name);
+    if (!provider) {
+      return null;
+    }
+
+    // Return provider as-is (customParams are already in the config)
+    // This method exists for future extensibility if we need to merge params
+    return provider;
+  }
+}
+