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

package/dist/services/batch-delegation.service.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * Batch Delegation Service
+ *
+ * Groups tools by OAuth provider for batch delegation flows.
+ * Enables single OAuth flow for multiple tools requiring the same provider.
+ *
+ * @package @kya-os/mcp-i-core
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BatchDelegationService = void 0;
+/**
+ * Service for grouping tools by OAuth provider
+ */
+class BatchDelegationService {
+    providerResolver;
+    toolProtectionService;
+    constructor(providerResolver, toolProtectionService) {
+        this.providerResolver = providerResolver;
+        this.toolProtectionService = toolProtectionService;
+    }
+    /**
+     * Group tools by OAuth provider
+     *
+     * Returns a map of provider → tools that require that provider.
+     * Tools that don't require delegation are skipped.
+     *
+     * @param toolNames - Array of tool names to group
+     * @param projectId - Project ID for provider resolution
+     * @param agentDid - Agent DID for fetching tool protections
+     * @returns Map of provider name to ToolGroup
+     */
+    async groupToolsByProvider(toolNames, projectId, agentDid) {
+        const groups = new Map();
+        for (const toolName of toolNames) {
+            const protection = await this.toolProtectionService.checkToolProtection(toolName, agentDid);
+            if (!protection?.requiresDelegation) {
+                continue; // Skip tools that don't require delegation
+            }
+            // Resolve provider for this tool
+            let provider;
+            try {
+                provider = await this.providerResolver.resolveProvider(protection, projectId);
+            }
+            catch (error) {
+                console.warn(`[BatchDelegation] Could not resolve provider for tool "${toolName}", skipping`, error instanceof Error ? error.message : String(error));
+                continue;
+            }
+            // Get or create group for this provider
+            if (!groups.has(provider)) {
+                groups.set(provider, {
+                    provider,
+                    tools: [],
+                    scopes: [],
+                    riskLevel: "medium", // Default
+                });
+            }
+            const group = groups.get(provider);
+            group.tools.push(toolName);
+            // Merge scopes (deduplicate)
+            const allScopes = new Set([
+                ...group.scopes,
+                ...(protection.requiredScopes || []),
+            ]);
+            group.scopes = Array.from(allScopes);
+            // Use highest risk level
+            if (protection.riskLevel) {
+                const riskOrder = { low: 1, medium: 2, high: 3, critical: 4 };
+                const currentRisk = riskOrder[group.riskLevel] || 1;
+                const toolRisk = riskOrder[protection.riskLevel] || 1;
+                if (toolRisk > currentRisk) {
+                    // Map critical to high for ToolGroup interface
+                    group.riskLevel = protection.riskLevel === "critical" ? "high" : protection.riskLevel;
+                }
+            }
+        }
+        return groups;
+    }
+    /**
+     * Get all tools that require a specific provider
+     *
+     * @param provider - Provider name to filter by
+     * @param projectId - Project ID for provider resolution
+     * @param agentDid - Agent DID for fetching tool protections
+     * @returns Array of tool names requiring the specified provider
+     */
+    async getToolsForProvider(provider, projectId, agentDid) {
+        // This would require fetching all tool protections
+        // For now, return empty array (can be enhanced later)
+        // TODO: Implement if needed for Phase 4 batch delegation UI
+        return [];
+    }
+}
+exports.BatchDelegationService = BatchDelegationService;
+//# sourceMappingURL=batch-delegation.service.js.map

package/dist/services/batch-delegation.service.js.map

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

package/dist/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/dist/services/oauth-config.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-config.service.d.ts","sourceRoot":"","sources":["../../src/services/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/dist/services/oauth-config.service.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAuthConfigService = void 0;
+const oauth_config_cache_js_1 = require("../cache/oauth-config-cache.js");
+/**
+ * Service for fetching OAuth provider configurations from AgentShield API
+ */
+class OAuthConfigService {
+    config;
+    constructor(config) {
+        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 oauth_config_cache_js_1.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) {
+        // 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();
+            // Validate response structure
+            if (!result.success || !result.data) {
+                throw new Error("Invalid API response: missing success or data field");
+            }
+            // Parse providers object
+            const providers = result.data.providers || {};
+            if (typeof providers !== "object" || Array.isArray(providers)) {
+                throw new Error("Invalid API response: providers must be an object, not an array");
+            }
+            // Build OAuthConfig object
+            // Note: API does NOT return defaultProvider field (Phase 1 architecture)
+            // Phase 1 uses configured provider as temporary fallback
+            // Phase 2+ requires tools to explicitly specify oauthProvider
+            const config = {
+                providers: providers,
+            };
+            // 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),
+                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) {
+        await this.config.cache.delete(projectId);
+        this.config.logger("[OAuthConfigService] Cache cleared", { projectId });
+    }
+    /**
+     * Clear all cached configs
+     */
+    async clearAllCache() {
+        await this.config.cache.clear();
+        this.config.logger("[OAuthConfigService] All cache cleared");
+    }
+}
+exports.OAuthConfigService = OAuthConfigService;
+//# sourceMappingURL=oauth-config.service.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-config.service.js","sourceRoot":"","sources":["../../src/services/oauth-config.service.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAKH,0EAA0E;AAsB1E;;GAEG;AACH,MAAa,kBAAkB;IACrB,MAAM,CAGZ;IAEF,YAAY,MAAgC;QAC1C,IAAI,CAAC,MAAM,GAAG;YACZ,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,EAAE,oBAAoB;YAChE,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC;YACnC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,IAAI,gDAAwB,EAAE;SACtD,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,cAAc,CAAC,SAAiB;QACpC,cAAc;QACd,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACtD,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,gCAAgC,EAAE;gBACnD,SAAS;aACV,CAAC,CAAC;YACH,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,6BAA6B;QAC7B,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,4BAA4B,kBAAkB,CAAC,SAAS,CAAC,YAAY,CAAC;QAExG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,+CAA+C,EAAE;YAClE,SAAS;YACT,GAAG;SACJ,CAAC,CAAC;QAEH,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,GAAG,EAAE;gBAC1D,MAAM,EAAE,KAAK;gBACb,OAAO,EAAE;oBACP,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE;oBAC7C,cAAc,EAAE,kBAAkB;iBACnC;aACF,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,CAAC;gBACrE,MAAM,IAAI,KAAK,CACb,iCAAiC,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,MAAM,SAAS,EAAE,CACzF,CAAC;YACJ,CAAC;YAED,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,EAKjC,CAAC;YAEF,8BAA8B;YAC9B,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;gBACpC,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;YACzE,CAAC;YAED,yBAAyB;YACzB,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC;YAC9C,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC9D,MAAM,IAAI,KAAK,CACb,iEAAiE,CAClE,CAAC;YACJ,CAAC;YAED,2BAA2B;YAC3B,yEAAyE;YACzE,yDAAyD;YACzD,8DAA8D;YAC9D,MAAM,MAAM,GAAgB;gBAC1B,SAAS,EAAE,SAA0C;aACtD,CAAC;YAEF,eAAe;YACf,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAErE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,gDAAgD,EAAE;gBACnE,SAAS;gBACT,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM;gBAC5C,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC;gBACjC,SAAS,EAAE,IAAI,IAAI,CACjB,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAClC,CAAC,WAAW,EAAE;aAChB,CAAC,CAAC;YAEH,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,uCAAuC,EAAE;gBAC1D,SAAS;gBACT,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aAC9D,CAAC,CAAC;YACH,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,UAAU,CAAC,SAAiB;QAChC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,oCAAoC,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,aAAa;QACjB,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QAChC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,wCAAwC,CAAC,CAAC;IAC/D,CAAC;CACF;AA/HD,gDA+HC"}

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

@@ -0,0 +1,77 @@
+/**
+ * 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 declare class OAuthProviderRegistry {
+    private configService;
+    private validator?;
+    private providers;
+    constructor(configService: OAuthConfigService, validator?: ProviderValidator | undefined);
+    /**
+     * 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[];
+    /**
+     * 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;
+    /**
+     * 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;
+}
+//# sourceMappingURL=oauth-provider-registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-provider-registry.d.ts","sourceRoot":"","sources":["../../src/services/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;AACpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE;;;;;GAKG;AACH,qBAAa,qBAAqB;IAI9B,OAAO,CAAC,aAAa;IACrB,OAAO,CAAC,SAAS,CAAC;IAJpB,OAAO,CAAC,SAAS,CAAyC;gBAGhD,aAAa,EAAE,kBAAkB,EACjC,SAAS,CAAC,EAAE,iBAAiB,YAAA;IAGvC;;;;;;;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;IAI5B;;;;;;OAMG;IACH,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI;IAUnE;;;;;;;;OAQG;IACH,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;CAU1D"}

package/dist/services/oauth-provider-registry.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAuthProviderRegistry = void 0;
+/**
+ * Registry for OAuth providers
+ *
+ * Wraps OAuthConfigService to provide a simple lookup interface
+ * for provider configurations.
+ */
+class OAuthProviderRegistry {
+    configService;
+    validator;
+    providers = new Map();
+    constructor(configService, validator) {
+        this.configService = configService;
+        this.validator = validator;
+    }
+    /**
+     * 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
+     */
+    async loadFromAgentShield(projectId) {
+        const config = await this.configService.getOAuthConfig(projectId);
+        // Clear existing providers
+        this.providers.clear();
+        // Register all providers from config
+        for (const [name, providerConfig] of Object.entries(config.providers)) {
+            this.providers.set(name, providerConfig);
+        }
+    }
+    /**
+     * Get provider by name
+     *
+     * @param name - Provider name (e.g., "github", "google")
+     * @returns Provider configuration or null if not found
+     */
+    getProvider(name) {
+        return this.providers.get(name) || null;
+    }
+    /**
+     * Get all providers
+     *
+     * @returns Array of all registered provider configurations
+     */
+    getAllProviders() {
+        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) {
+        return this.providers.has(name);
+    }
+    /**
+     * Get all provider names
+     *
+     * @returns Array of provider names
+     */
+    getProviderNames() {
+        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, provider) {
+        // 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) {
+        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;
+    }
+}
+exports.OAuthProviderRegistry = OAuthProviderRegistry;
+//# sourceMappingURL=oauth-provider-registry.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-provider-registry.js","sourceRoot":"","sources":["../../src/services/oauth-provider-registry.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAMH;;;;;GAKG;AACH,MAAa,qBAAqB;IAItB;IACA;IAJF,SAAS,GAA+B,IAAI,GAAG,EAAE,CAAC;IAE1D,YACU,aAAiC,EACjC,SAA6B;QAD7B,kBAAa,GAAb,aAAa,CAAoB;QACjC,cAAS,GAAT,SAAS,CAAoB;IACpC,CAAC;IAEJ;;;;;;;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;IAED;;;;;;OAMG;IACH,sBAAsB,CAAC,IAAY,EAAE,QAAuB;QAC1D,4DAA4D;QAC5D,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC1C,CAAC;QAED,oBAAoB;QACpB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACrC,CAAC;IAED;;;;;;;;OAQG;IACH,qBAAqB,CAAC,IAAY;QAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,IAAI,CAAC;QACd,CAAC;QAED,iEAAiE;QACjE,yEAAyE;QACzE,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF;AAtGD,sDAsGC"}

package/dist/services/oauth-service.d.ts

@@ -0,0 +1,77 @@
+/**
+ * OAuth Service
+ *
+ * Handles OAuth token exchange and refresh using PKCE (Proof Key for Code Exchange).
+ * Supports both direct PKCE exchange with OAuth providers and proxy mode via AgentShield.
+ *
+ * @package @kya-os/mcp-i-core
+ */
+import type { FetchProvider } from "../providers/base.js";
+import type { OAuthConfigService } from "./oauth-config.service.js";
+import type { IdpTokens } from "@kya-os/contracts/config";
+export interface OAuthServiceConfig {
+    /** OAuth config service for fetching provider configurations */
+    configService: OAuthConfigService;
+    /** Fetch provider for making HTTP requests */
+    fetchProvider: FetchProvider;
+    /** AgentShield API URL (for proxy mode) */
+    agentShieldApiUrl: string;
+    /** AgentShield API key (for proxy mode) */
+    agentShieldApiKey: string;
+    /** Project ID for fetching OAuth config */
+    projectId: string;
+    /** Optional logger callback for diagnostics */
+    logger?: (message: string, data?: unknown) => void;
+}
+/**
+ * Service for OAuth token exchange and refresh
+ */
+export declare class OAuthService {
+    private config;
+    constructor(config: OAuthServiceConfig);
+    /**
+     * Exchange authorization code for IDP tokens using PKCE
+     *
+     * For PKCE providers: Exchanges code directly with OAuth provider (no client secret)
+     * For proxy mode: Exchanges code via AgentShield API
+     *
+     * @param provider - OAuth provider name (e.g., "github", "google")
+     * @param code - Authorization code from OAuth callback
+     * @param codeVerifier - PKCE code verifier (optional for non-PKCE providers in proxy mode)
+     * @param redirectUri - Redirect URI used in authorization request
+     * @returns IDP tokens (access_token, refresh_token, expires_at, etc.)
+     */
+    exchangeToken(provider: string, code: string, codeVerifier?: string, redirectUri?: string): Promise<IdpTokens>;
+    /**
+     * Exchange token directly with OAuth provider using PKCE
+     */
+    private exchangeTokenPKCE;
+    /**
+     * Exchange token via AgentShield proxy (for providers that require proxy mode)
+     *
+     * Note: For Phase 3 two-step flow, OAuth tokens are retrieved separately via
+     * OAuthTokenRetrievalService in the callback handler. This method maintains
+     * backward compatibility for direct proxy mode usage.
+     */
+    private exchangeTokenProxy;
+    /**
+     * Refresh IDP access token using refresh token
+     *
+     * For PKCE providers: Refreshes directly with OAuth provider
+     * For proxy mode: Refreshes via AgentShield API
+     *
+     * @param provider - OAuth provider name
+     * @param refreshToken - Refresh token from previous token exchange
+     * @returns New IDP tokens or null if refresh failed
+     */
+    refreshToken(provider: string, refreshToken: string): Promise<IdpTokens | null>;
+    /**
+     * Refresh token directly with OAuth provider using PKCE
+     */
+    private refreshTokenPKCE;
+    /**
+     * Refresh token via AgentShield proxy
+     */
+    private refreshTokenProxy;
+}
+//# sourceMappingURL=oauth-service.d.ts.map

package/dist/services/oauth-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-service.d.ts","sourceRoot":"","sources":["../../src/services/oauth-service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAiB,MAAM,0BAA0B,CAAC;AAEzE,MAAM,WAAW,kBAAkB;IACjC,gEAAgE;IAChE,aAAa,EAAE,kBAAkB,CAAC;IAElC,8CAA8C;IAC9C,aAAa,EAAE,aAAa,CAAC;IAE7B,2CAA2C;IAC3C,iBAAiB,EAAE,MAAM,CAAC;IAE1B,2CAA2C;IAC3C,iBAAiB,EAAE,MAAM,CAAC;IAE1B,2CAA2C;IAC3C,SAAS,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,YAAY;IACvB,OAAO,CAAC,MAAM,CAEZ;gBAEU,MAAM,EAAE,kBAAkB;IAWtC;;;;;;;;;;;OAWG;IACG,aAAa,CACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,YAAY,CAAC,EAAE,MAAM,EACrB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,SAAS,CAAC;IAyCrB;;OAEG;YACW,iBAAiB;IAoF/B;;;;;;OAMG;YACW,kBAAkB;IAyGhC;;;;;;;;;OASG;IACG,YAAY,CAChB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IA2B5B;;OAEG;YACW,gBAAgB;IAuE9B;;OAEG;YACW,iBAAiB;CAkFhC"}