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

package/src/services/provider-resolver.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Provider Resolver
+ *
+ * Resolves OAuth provider for tools using priority-based resolution strategy.
+ * Supports Phase 2+ tool-specific providers with backward compatibility for Phase 1.
+ *
+ * @package @kya-os/mcp-i-core
+ */
+import type { ToolProtection } from "@kya-os/contracts/tool-protection";
+import type { OAuthProviderRegistry } from "./oauth-provider-registry.js";
+import type { OAuthConfigService } from "./oauth-config.service.js";
+/**
+ * Resolves OAuth provider for tools with priority-based fallback strategy
+ *
+ * Priority order:
+ * 1. Tool-specific oauthProvider field (Phase 2+ preferred)
+ * 2. Scope prefix inference (fallback)
+ * 3. First configured provider (Phase 1 compatibility fallback)
+ * 4. Error if no provider can be resolved
+ */
+export declare class ProviderResolver {
+    private registry;
+    private configService;
+    constructor(registry: OAuthProviderRegistry, configService: OAuthConfigService);
+    /**
+     * Resolve OAuth provider for a tool
+     *
+     * @param toolProtection - Tool protection configuration
+     * @param projectId - Project ID for fetching provider config
+     * @returns Provider name (never null - throws if cannot resolve)
+     * @throws Error if provider cannot be resolved
+     */
+    resolveProvider(toolProtection: ToolProtection, projectId: string): Promise<string>;
+    /**
+     * Infer provider from scope prefixes
+     *
+     * Used as Priority 2 fallback when oauthProvider is not specified.
+     * Examples:
+     * - github:repo:read → github
+     * - gmail:read → google
+     * - microsoft:calendar:read → microsoft
+     *
+     * @param scopes - Required scopes for the tool
+     * @returns Provider name if uniquely inferred, null otherwise
+     */
+    private inferProviderFromScopes;
+}
+//# sourceMappingURL=provider-resolver.d.ts.map

package/src/services/provider-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-resolver.d.ts","sourceRoot":"","sources":["provider-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEpE;;;;;;;;GAQG;AACH,qBAAa,gBAAgB;IAEzB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,aAAa;gBADb,QAAQ,EAAE,qBAAqB,EAC/B,aAAa,EAAE,kBAAkB;IAG3C;;;;;;;OAOG;IACG,eAAe,CACnB,cAAc,EAAE,cAAc,EAC9B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC;IA6ClB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,uBAAuB;CAoChC"}

package/src/services/provider-resolver.js

@@ -0,0 +1,106 @@
+/**
+ * Provider Resolver
+ *
+ * Resolves OAuth provider for tools using priority-based resolution strategy.
+ * Supports Phase 2+ tool-specific providers with backward compatibility for Phase 1.
+ *
+ * @package @kya-os/mcp-i-core
+ */
+/**
+ * Resolves OAuth provider for tools with priority-based fallback strategy
+ *
+ * Priority order:
+ * 1. Tool-specific oauthProvider field (Phase 2+ preferred)
+ * 2. Scope prefix inference (fallback)
+ * 3. First configured provider (Phase 1 compatibility fallback)
+ * 4. Error if no provider can be resolved
+ */
+export class ProviderResolver {
+    registry;
+    configService;
+    constructor(registry, configService) {
+        this.registry = registry;
+        this.configService = configService;
+    }
+    /**
+     * Resolve OAuth provider for a tool
+     *
+     * @param toolProtection - Tool protection configuration
+     * @param projectId - Project ID for fetching provider config
+     * @returns Provider name (never null - throws if cannot resolve)
+     * @throws Error if provider cannot be resolved
+     */
+    async resolveProvider(toolProtection, projectId) {
+        // Priority 1: Tool-specific provider (Phase 2+ preferred)
+        if (toolProtection.oauthProvider) {
+            if (!this.registry.hasProvider(toolProtection.oauthProvider)) {
+                throw new Error(`Provider "${toolProtection.oauthProvider}" not configured for project "${projectId}". ` +
+                    `Add provider in project settings.`);
+            }
+            return toolProtection.oauthProvider;
+        }
+        // Priority 2: Scope prefix inference (fallback)
+        const inferredProvider = this.inferProviderFromScopes(toolProtection.requiredScopes || []);
+        if (inferredProvider && this.registry.hasProvider(inferredProvider)) {
+            console.log(`[ProviderResolver] Inferred provider "${inferredProvider}" from scopes`);
+            return inferredProvider;
+        }
+        // Priority 3: First configured provider (Phase 1 compatibility fallback)
+        // Ensure registry is loaded
+        await this.registry.loadFromAgentShield(projectId);
+        const providers = this.registry.getAllProviders();
+        if (providers.length > 0) {
+            // Log deprecation warning for Phase 1 tools
+            const firstProviderName = this.registry.getProviderNames()[0];
+            console.warn(`[ProviderResolver] Tool does not specify oauthProvider. ` +
+                `Using first configured provider "${firstProviderName}" as fallback. ` +
+                `This is deprecated - configure oauthProvider in AgentShield dashboard for Phase 2+.`);
+            return firstProviderName;
+        }
+        // Priority 4: Error if no provider can be resolved
+        throw new Error(`Tool requires OAuth but no provider could be resolved. ` +
+            `Either specify oauthProvider in tool protection config, or configure at least one provider for project "${projectId}".`);
+    }
+    /**
+     * Infer provider from scope prefixes
+     *
+     * Used as Priority 2 fallback when oauthProvider is not specified.
+     * Examples:
+     * - github:repo:read → github
+     * - gmail:read → google
+     * - microsoft:calendar:read → microsoft
+     *
+     * @param scopes - Required scopes for the tool
+     * @returns Provider name if uniquely inferred, null otherwise
+     */
+    inferProviderFromScopes(scopes) {
+        if (!scopes || scopes.length === 0) {
+            return null;
+        }
+        // Extract first part of scope (before first colon)
+        const scopePrefixes = scopes.map((scope) => {
+            const parts = scope.split(":");
+            return parts[0].toLowerCase();
+        });
+        // Provider mapping
+        const providerMap = {
+            github: "github",
+            google: "google",
+            gmail: "google", // gmail:read → google
+            calendar: "google", // calendar:read → google (if ambiguous, use project default)
+            microsoft: "microsoft",
+            outlook: "microsoft",
+            slack: "slack",
+            auth0: "auth0",
+            okta: "okta",
+        };
+        // Find unique provider
+        const providers = new Set(scopePrefixes.map((prefix) => providerMap[prefix]).filter(Boolean));
+        if (providers.size === 1) {
+            return Array.from(providers)[0];
+        }
+        // Ambiguous or no prefix → return null (use project-level provider)
+        return null;
+    }
+}
+//# sourceMappingURL=provider-resolver.js.map

package/src/services/provider-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-resolver.js","sourceRoot":"","sources":["provider-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;;;;;;GAQG;AACH,MAAM,OAAO,gBAAgB;IAEjB;IACA;IAFV,YACU,QAA+B,EAC/B,aAAiC;QADjC,aAAQ,GAAR,QAAQ,CAAuB;QAC/B,kBAAa,GAAb,aAAa,CAAoB;IACxC,CAAC;IAEJ;;;;;;;OAOG;IACH,KAAK,CAAC,eAAe,CACnB,cAA8B,EAC9B,SAAiB;QAEjB,0DAA0D;QAC1D,IAAI,cAAc,CAAC,aAAa,EAAE,CAAC;YACjC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,cAAc,CAAC,aAAa,CAAC,EAAE,CAAC;gBAC7D,MAAM,IAAI,KAAK,CACb,aAAa,cAAc,CAAC,aAAa,iCAAiC,SAAS,KAAK;oBACtF,mCAAmC,CACtC,CAAC;YACJ,CAAC;YACD,OAAO,cAAc,CAAC,aAAa,CAAC;QACtC,CAAC;QAED,gDAAgD;QAChD,MAAM,gBAAgB,GAAG,IAAI,CAAC,uBAAuB,CACnD,cAAc,CAAC,cAAc,IAAI,EAAE,CACpC,CAAC;QACF,IAAI,gBAAgB,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,gBAAgB,CAAC,EAAE,CAAC;YACpE,OAAO,CAAC,GAAG,CACT,yCAAyC,gBAAgB,eAAe,CACzE,CAAC;YACF,OAAO,gBAAgB,CAAC;QAC1B,CAAC;QAED,yEAAyE;QACzE,4BAA4B;QAC5B,MAAM,IAAI,CAAC,QAAQ,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC;QACnD,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,eAAe,EAAE,CAAC;QAClD,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzB,4CAA4C;YAC5C,MAAM,iBAAiB,GAAG,IAAI,CAAC,QAAQ,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,CAAC;YAC9D,OAAO,CAAC,IAAI,CACV,0DAA0D;gBACxD,oCAAoC,iBAAiB,iBAAiB;gBACtE,qFAAqF,CACxF,CAAC;YACF,OAAO,iBAAiB,CAAC;QAC3B,CAAC;QAED,mDAAmD;QACnD,MAAM,IAAI,KAAK,CACb,yDAAyD;YACvD,2GAA2G,SAAS,IAAI,CAC3H,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;OAWG;IACK,uBAAuB,CAAC,MAAgB;QAC9C,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,mDAAmD;QACnD,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACzC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC/B,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QAChC,CAAC,CAAC,CAAC;QAEH,mBAAmB;QACnB,MAAM,WAAW,GAA2B;YAC1C,MAAM,EAAE,QAAQ;YAChB,MAAM,EAAE,QAAQ;YAChB,KAAK,EAAE,QAAQ,EAAE,sBAAsB;YACvC,QAAQ,EAAE,QAAQ,EAAE,6DAA6D;YACjF,SAAS,EAAE,WAAW;YACtB,OAAO,EAAE,WAAW;YACpB,KAAK,EAAE,OAAO;YACd,KAAK,EAAE,OAAO;YACd,IAAI,EAAE,MAAM;SACb,CAAC;QAEF,uBAAuB;QACvB,MAAM,SAAS,GAAG,IAAI,GAAG,CACvB,aAAa,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CACnE,CAAC;QAEF,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QAClC,CAAC;QAED,oEAAoE;QACpE,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/src/services/provider-resolver.ts

@@ -0,0 +1,144 @@
+/**
+ * Provider Resolver
+ *
+ * Resolves OAuth provider for tools using priority-based resolution strategy.
+ * Supports Phase 2+ tool-specific providers with backward compatibility for Phase 1.
+ *
+ * @package @kya-os/mcp-i-core
+ */
+
+import type { ToolProtection } from "@kya-os/contracts/tool-protection";
+import type { OAuthProviderRegistry } from "./oauth-provider-registry.js";
+import type { OAuthConfigService } from "./oauth-config.service.js";
+
+/**
+ * Resolves OAuth provider for tools with priority-based fallback strategy
+ *
+ * Priority order:
+ * 1. Tool-specific oauthProvider field (Phase 2+ preferred)
+ * 2. Scope prefix inference (fallback)
+ * 3. First configured provider (Phase 1 compatibility fallback)
+ * 4. Error if no provider can be resolved
+ */
+export class ProviderResolver {
+  constructor(
+    private registry: OAuthProviderRegistry,
+    private configService: OAuthConfigService
+  ) {}
+
+  /**
+   * Resolve OAuth provider for a tool
+   *
+   * @param toolProtection - Tool protection configuration
+   * @param projectId - Project ID for fetching provider config
+   * @returns Provider name (never null - throws if cannot resolve)
+   * @throws Error if provider cannot be resolved
+   */
+  async resolveProvider(
+    toolProtection: ToolProtection,
+    projectId: string
+  ): Promise<string> {
+    // Priority 1: Tool-specific provider (Phase 2+ preferred)
+    if (toolProtection.oauthProvider) {
+      // Ensure registry is loaded before checking
+      if (this.registry.getProviderNames().length === 0) {
+        await this.registry.loadFromAgentShield(projectId);
+      }
+      if (!this.registry.hasProvider(toolProtection.oauthProvider)) {
+        throw new Error(
+          `Provider "${toolProtection.oauthProvider}" not configured for project "${projectId}". ` +
+            `Add provider in project settings.`
+        );
+      }
+      return toolProtection.oauthProvider;
+    }
+
+    // Priority 2: Scope prefix inference (fallback)
+    const inferredProvider = this.inferProviderFromScopes(
+      toolProtection.requiredScopes || []
+    );
+    if (inferredProvider) {
+      // Ensure registry is loaded before checking
+      if (this.registry.getProviderNames().length === 0) {
+        await this.registry.loadFromAgentShield(projectId);
+      }
+      if (this.registry.hasProvider(inferredProvider)) {
+        console.log(
+          `[ProviderResolver] Inferred provider "${inferredProvider}" from scopes`
+        );
+        return inferredProvider;
+      }
+    }
+
+    // Priority 3: First configured provider (Phase 1 compatibility fallback)
+    // Ensure registry is loaded
+    await this.registry.loadFromAgentShield(projectId);
+    const providers = this.registry.getAllProviders();
+    if (providers.length > 0) {
+      // Log deprecation warning for Phase 1 tools
+      const firstProviderName = this.registry.getProviderNames()[0];
+      console.warn(
+        `[ProviderResolver] Tool does not specify oauthProvider. ` +
+          `Using first configured provider "${firstProviderName}" as fallback. ` +
+          `This is deprecated - configure oauthProvider in AgentShield dashboard for Phase 2+.`
+      );
+      return firstProviderName;
+    }
+
+    // Priority 4: Error if no provider can be resolved
+    throw new Error(
+      `Tool requires OAuth but no provider could be resolved. ` +
+        `Either specify oauthProvider in tool protection config, or configure at least one provider for project "${projectId}".`
+    );
+  }
+
+  /**
+   * Infer provider from scope prefixes
+   *
+   * Used as Priority 2 fallback when oauthProvider is not specified.
+   * Examples:
+   * - github:repo:read → github
+   * - gmail:read → google
+   * - microsoft:calendar:read → microsoft
+   *
+   * @param scopes - Required scopes for the tool
+   * @returns Provider name if uniquely inferred, null otherwise
+   */
+  private inferProviderFromScopes(scopes: string[]): string | null {
+    if (!scopes || scopes.length === 0) {
+      return null;
+    }
+
+    // Extract first part of scope (before first colon)
+    const scopePrefixes = scopes.map((scope) => {
+      const parts = scope.split(":");
+      return parts[0].toLowerCase();
+    });
+
+    // Provider mapping
+    const providerMap: Record<string, string> = {
+      github: "github",
+      google: "google",
+      gmail: "google", // gmail:read → google
+      calendar: "google", // calendar:read → google (if ambiguous, use project default)
+      microsoft: "microsoft",
+      outlook: "microsoft",
+      slack: "slack",
+      auth0: "auth0",
+      okta: "okta",
+    };
+
+    // Find unique provider
+    const providers = new Set(
+      scopePrefixes.map((prefix) => providerMap[prefix]).filter(Boolean)
+    );
+
+    if (providers.size === 1) {
+      return Array.from(providers)[0];
+    }
+
+    // Ambiguous or no prefix → return null (use project-level provider)
+    return null;
+  }
+}
+

package/src/services/provider-validator.ts

@@ -0,0 +1,170 @@
+/**
+ * Provider Validator
+ *
+ * Validates OAuth provider configurations for custom IDP support.
+ * Ensures provider configurations are valid before registration.
+ *
+ * @package @kya-os/mcp-i-core
+ */
+
+import type { OAuthProvider } from "@kya-os/contracts/config";
+
+/**
+ * Reserved OAuth parameters that cannot be overridden by custom parameters
+ */
+const RESERVED_PARAMETERS = [
+  "response_type",
+  "client_id",
+  "redirect_uri",
+  "scope",
+  "state",
+  "code_challenge",
+  "code_challenge_method",
+] as const;
+
+/**
+ * Validation error for provider configuration issues
+ */
+export class ProviderValidationError extends Error {
+  constructor(message: string, public readonly field?: string) {
+    super(message);
+    this.name = "ProviderValidationError";
+  }
+}
+
+/**
+ * Service for validating OAuth provider configurations
+ */
+export class ProviderValidator {
+  /**
+   * Validate provider configuration
+   *
+   * @param provider - Provider configuration to validate
+   * @param name - Provider name (for error messages)
+   * @throws ProviderValidationError if validation fails
+   */
+  validate(provider: OAuthProvider, name: string): void {
+    // Validate required fields
+    if (!provider.clientId || provider.clientId.trim().length === 0) {
+      throw new ProviderValidationError(
+        `Provider "${name}" must have a clientId`,
+        "clientId"
+      );
+    }
+
+    if (!provider.authorizationUrl || provider.authorizationUrl.trim().length === 0) {
+      throw new ProviderValidationError(
+        `Provider "${name}" must have an authorizationUrl`,
+        "authorizationUrl"
+      );
+    }
+
+    if (!provider.tokenUrl || provider.tokenUrl.trim().length === 0) {
+      throw new ProviderValidationError(
+        `Provider "${name}" must have a tokenUrl`,
+        "tokenUrl"
+      );
+    }
+
+    // Validate URL formats
+    this.validateUrl(provider.authorizationUrl, name, "authorizationUrl");
+    this.validateUrl(provider.tokenUrl, name, "tokenUrl");
+
+    if (provider.userInfoUrl) {
+      this.validateUrl(provider.userInfoUrl, name, "userInfoUrl");
+    }
+
+    // Validate proxy mode requirements
+    if (provider.proxyMode && !provider.requiresClientSecret) {
+      throw new ProviderValidationError(
+        `Provider "${name}" with proxyMode=true must have requiresClientSecret=true`,
+        "proxyMode"
+      );
+    }
+
+    // Validate custom parameters don't conflict with reserved parameters
+    if (provider.customParams) {
+      this.validateCustomParams(provider.customParams, name);
+    }
+  }
+
+  /**
+   * Validate URL format
+   *
+   * @param url - URL to validate
+   * @param providerName - Provider name (for error messages)
+   * @param fieldName - Field name (for error messages)
+   * @throws ProviderValidationError if URL is invalid
+   */
+  private validateUrl(url: string, providerName: string, fieldName: string): void {
+    try {
+      const parsedUrl = new URL(url);
+      if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+        throw new ProviderValidationError(
+          `Provider "${providerName}" ${fieldName} must use HTTP or HTTPS protocol`,
+          fieldName
+        );
+      }
+    } catch (error) {
+      if (error instanceof ProviderValidationError) {
+        throw error;
+      }
+      throw new ProviderValidationError(
+        `Provider "${providerName}" ${fieldName} is not a valid URL: ${error instanceof Error ? error.message : String(error)}`,
+        fieldName
+      );
+    }
+  }
+
+  /**
+   * Validate custom parameters don't override reserved OAuth parameters
+   *
+   * @param customParams - Custom parameters to validate
+   * @param providerName - Provider name (for error messages)
+   * @throws ProviderValidationError if reserved parameter is overridden
+   */
+  private validateCustomParams(
+    customParams: Record<string, string>,
+    providerName: string
+  ): void {
+    for (const [key, value] of Object.entries(customParams)) {
+      const normalizedKey = key.toLowerCase();
+      if (RESERVED_PARAMETERS.includes(normalizedKey as any)) {
+        throw new ProviderValidationError(
+          `Provider "${providerName}" custom parameter "${key}" conflicts with reserved OAuth parameter. Reserved parameters: ${RESERVED_PARAMETERS.join(", ")}`,
+          `customParams.${key}`
+        );
+      }
+      if (!value || value.trim().length === 0) {
+        throw new ProviderValidationError(
+          `Provider "${providerName}" custom parameter "${key}" has empty value`,
+          `customParams.${key}`
+        );
+      }
+    }
+  }
+
+  /**
+   * Test provider endpoint reachability (optional)
+   *
+   * @param provider - Provider configuration
+   * @param fetchProvider - Fetch implementation
+   * @returns True if endpoint is reachable, false otherwise
+   */
+  async testProvider(
+    provider: OAuthProvider,
+    fetchProvider: typeof fetch
+  ): Promise<boolean> {
+    try {
+      // Test authorization URL (HEAD request to avoid triggering OAuth flow)
+      const authResponse = await fetchProvider(provider.authorizationUrl, {
+        method: "HEAD",
+        signal: AbortSignal.timeout(5000), // 5 second timeout
+      });
+      return authResponse.ok || authResponse.status === 405; // 405 Method Not Allowed is OK
+    } catch (error) {
+      return false;
+    }
+  }
+}
+