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

package/src/services/oauth-service.ts

@@ -0,0 +1,510 @@
+/**
+ * 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, OAuthProvider } 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 class OAuthService {
+  private config: Required<Omit<OAuthServiceConfig, "logger">> & {
+    logger: (message: string, data?: unknown) => void;
+  };
+
+  constructor(config: OAuthServiceConfig) {
+    this.config = {
+      configService: config.configService,
+      fetchProvider: config.fetchProvider,
+      agentShieldApiUrl: config.agentShieldApiUrl,
+      agentShieldApiKey: config.agentShieldApiKey,
+      projectId: config.projectId,
+      logger: config.logger || (() => {}),
+    };
+  }
+
+  /**
+   * 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.)
+   */
+  async exchangeToken(
+    provider: string,
+    code: string,
+    codeVerifier?: string,
+    redirectUri?: string
+  ): Promise<IdpTokens> {
+    // Fetch provider config
+    const oauthConfig = await this.config.configService.getOAuthConfig(
+      this.config.projectId
+    );
+    const providerConfig = oauthConfig.providers[provider];
+
+    if (!providerConfig) {
+      throw new Error(`Provider "${provider}" not configured for project "${this.config.projectId}"`);
+    }
+
+    // For PKCE providers, require codeVerifier
+    if (providerConfig.supportsPKCE && !providerConfig.proxyMode) {
+      if (!codeVerifier) {
+        throw new Error(
+          `Provider "${provider}" requires PKCE code_verifier for token exchange`
+        );
+      }
+      return this.exchangeTokenPKCE(
+        providerConfig,
+        code,
+        codeVerifier,
+        redirectUri || ""
+      );
+    }
+
+    // For proxy mode, codeVerifier is optional (only included if PKCE is supported)
+    if (providerConfig.proxyMode) {
+      return this.exchangeTokenProxy(
+        providerConfig,
+        code,
+        codeVerifier,
+        redirectUri || ""
+      );
+    }
+
+    throw new Error(
+      `Provider "${provider}" configuration is invalid: must support PKCE or use proxy mode`
+    );
+  }
+
+  /**
+   * Exchange token directly with OAuth provider using PKCE
+   */
+  private async exchangeTokenPKCE(
+    providerConfig: OAuthProvider,
+    code: string,
+    codeVerifier: string,
+    redirectUri: string
+  ): Promise<IdpTokens> {
+    this.config.logger("[OAuthService] Exchanging token with PKCE", {
+      provider: providerConfig.authorizationUrl,
+      tokenUrl: providerConfig.tokenUrl,
+    });
+
+    const response = await this.config.fetchProvider.fetch(providerConfig.tokenUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+      },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: redirectUri,
+        client_id: providerConfig.clientId,
+        code_verifier: codeVerifier,
+      }).toString(),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "Unknown error");
+      let errorData: any;
+      try {
+        errorData = JSON.parse(errorText);
+      } catch {
+        errorData = { error: errorText };
+      }
+
+      const errorMessage =
+        errorData.error_description || errorData.error || errorText;
+
+      this.config.logger("[OAuthService] Token exchange failed", {
+        status: response.status,
+        error: errorMessage,
+        provider: providerConfig.tokenUrl,
+      });
+
+      throw new Error(
+        `Token exchange failed: ${errorMessage} (${response.status})`
+      );
+    }
+
+    const tokens = await response.json() as {
+      access_token: string;
+      refresh_token?: string;
+      expires_in?: number;
+      token_type?: string;
+      scope?: string;
+    };
+
+    // Validate required fields
+    if (!tokens.access_token) {
+      throw new Error("Token response missing access_token");
+    }
+
+    // Calculate expiration timestamp
+    const expiresIn = tokens.expires_in || 3600; // Default 1 hour
+    const expiresAt = Date.now() + expiresIn * 1000;
+
+    const idpTokens: IdpTokens = {
+      access_token: tokens.access_token,
+      refresh_token: tokens.refresh_token,
+      expires_in: expiresIn,
+      expires_at: expiresAt,
+      token_type: tokens.token_type || "Bearer",
+      scope: tokens.scope,
+    };
+
+    this.config.logger("[OAuthService] Token exchange successful", {
+      provider: providerConfig.tokenUrl,
+      expiresAt: new Date(expiresAt).toISOString(),
+      hasRefreshToken: !!idpTokens.refresh_token,
+    });
+
+    return idpTokens;
+  }
+
+  /**
+   * 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 async exchangeTokenProxy(
+    providerConfig: OAuthProvider,
+    code: string,
+    codeVerifier?: string,
+    redirectUri?: string
+  ): Promise<IdpTokens> {
+    // Exchange via AgentShield proxy endpoint
+    const proxyUrl = `${this.config.agentShieldApiUrl}/api/v1/oauth/token`;
+
+    this.config.logger("[OAuthService] Exchanging token via proxy", {
+      proxyUrl,
+      provider: providerConfig.authorizationUrl,
+      hasCodeVerifier: !!codeVerifier,
+      supportsPKCE: providerConfig.supportsPKCE,
+    });
+
+    // Build request body - only include code_verifier if PKCE is supported and provided
+    const requestBody: Record<string, string> = {
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: redirectUri || "",
+      provider: providerConfig.authorizationUrl,
+      project_id: this.config.projectId,
+    };
+
+    // Include code_verifier only if provider supports PKCE and verifier is provided
+    if (providerConfig.supportsPKCE && codeVerifier) {
+      requestBody.code_verifier = codeVerifier;
+    }
+
+    const response = await this.config.fetchProvider.fetch(proxyUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.config.agentShieldApiKey}`,
+      },
+      body: JSON.stringify(requestBody),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "Unknown error");
+      let errorData: any;
+      try {
+        errorData = JSON.parse(errorText);
+      } catch {
+        errorData = { error: errorText };
+      }
+
+      const errorMessage =
+        errorData.error_description || errorData.error || errorText;
+
+      this.config.logger("[OAuthService] Proxy token exchange failed", {
+        status: response.status,
+        error: errorMessage,
+        proxyUrl,
+      });
+
+      throw new Error(
+        `Proxy token exchange failed: ${errorMessage} (${response.status})`
+      );
+    }
+
+    const result = await response.json() as {
+      data?: {
+        access_token: string;
+        refresh_token?: string;
+        expires_in?: number;
+        token_type?: string;
+        scope?: string;
+      };
+      access_token?: string;
+      refresh_token?: string;
+      expires_in?: number;
+      token_type?: string;
+      scope?: string;
+    };
+    const tokens = result.data || result;
+
+    // Validate required fields
+    if (!tokens.access_token) {
+      throw new Error("Proxy token response missing access_token");
+    }
+
+    // Calculate expiration timestamp
+    const expiresIn = tokens.expires_in || 3600; // Default 1 hour
+    const expiresAt = Date.now() + expiresIn * 1000;
+
+    const idpTokens: IdpTokens = {
+      access_token: tokens.access_token,
+      refresh_token: tokens.refresh_token,
+      expires_in: expiresIn,
+      expires_at: expiresAt,
+      token_type: tokens.token_type || "Bearer",
+      scope: tokens.scope,
+    };
+
+    this.config.logger("[OAuthService] Proxy token exchange successful", {
+      proxyUrl,
+      expiresAt: new Date(expiresAt).toISOString(),
+      hasRefreshToken: !!idpTokens.refresh_token,
+    });
+
+    return idpTokens;
+  }
+
+  /**
+   * 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
+   */
+  async refreshToken(
+    provider: string,
+    refreshToken: string
+  ): Promise<IdpTokens | null> {
+    // Fetch provider config
+    const oauthConfig = await this.config.configService.getOAuthConfig(
+      this.config.projectId
+    );
+    const providerConfig = oauthConfig.providers[provider];
+
+    if (!providerConfig) {
+      this.config.logger("[OAuthService] Provider not found for refresh", {
+        provider,
+      });
+      return null;
+    }
+
+    // For PKCE providers, refresh directly with OAuth provider
+    if (providerConfig.supportsPKCE && !providerConfig.proxyMode) {
+      return this.refreshTokenPKCE(providerConfig, refreshToken);
+    }
+
+    // For proxy mode, refresh via AgentShield
+    if (providerConfig.proxyMode) {
+      return this.refreshTokenProxy(providerConfig, refreshToken);
+    }
+
+    return null;
+  }
+
+  /**
+   * Refresh token directly with OAuth provider using PKCE
+   */
+  private async refreshTokenPKCE(
+    providerConfig: OAuthProvider,
+    refreshToken: string
+  ): Promise<IdpTokens | null> {
+    this.config.logger("[OAuthService] Refreshing token with PKCE", {
+      provider: providerConfig.tokenUrl,
+    });
+
+    try {
+      const response = await this.config.fetchProvider.fetch(providerConfig.tokenUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json",
+        },
+        body: new URLSearchParams({
+          grant_type: "refresh_token",
+          refresh_token: refreshToken,
+          client_id: providerConfig.clientId,
+        }).toString(),
+      });
+
+      if (!response.ok) {
+        this.config.logger("[OAuthService] Token refresh failed", {
+          status: response.status,
+          provider: providerConfig.tokenUrl,
+        });
+        return null;
+      }
+
+      const tokens = await response.json() as {
+        access_token: string;
+        refresh_token?: string;
+        expires_in?: number;
+        token_type?: string;
+        scope?: string;
+      };
+
+      if (!tokens.access_token) {
+        this.config.logger("[OAuthService] Token refresh response missing access_token");
+        return null;
+      }
+
+      // Calculate expiration timestamp
+      const expiresIn = tokens.expires_in || 3600; // Default 1 hour
+      const expiresAt = Date.now() + expiresIn * 1000;
+
+      const idpTokens: IdpTokens = {
+        access_token: tokens.access_token,
+        refresh_token: tokens.refresh_token || refreshToken, // Use new refresh token if provided, otherwise keep old one
+        expires_in: expiresIn,
+        expires_at: expiresAt,
+        token_type: tokens.token_type || "Bearer",
+        scope: tokens.scope,
+      };
+
+      this.config.logger("[OAuthService] Token refresh successful", {
+        provider: providerConfig.tokenUrl,
+        expiresAt: new Date(expiresAt).toISOString(),
+      });
+
+      return idpTokens;
+    } catch (error) {
+      this.config.logger("[OAuthService] Token refresh error", {
+        error: error instanceof Error ? error.message : String(error),
+        provider: providerConfig.tokenUrl,
+      });
+      return null;
+    }
+  }
+
+  /**
+   * Refresh token via AgentShield proxy
+   */
+  private async refreshTokenProxy(
+    providerConfig: OAuthProvider,
+    refreshToken: string
+  ): Promise<IdpTokens | null> {
+    const proxyUrl = `${this.config.agentShieldApiUrl}/api/v1/oauth/token`;
+
+    this.config.logger("[OAuthService] Refreshing token via proxy", {
+      proxyUrl,
+      provider: providerConfig.authorizationUrl,
+    });
+
+    try {
+      const response = await this.config.fetchProvider.fetch(proxyUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.config.agentShieldApiKey}`,
+        },
+        body: JSON.stringify({
+          grant_type: "refresh_token",
+          refresh_token: refreshToken,
+          provider: providerConfig.authorizationUrl,
+          project_id: this.config.projectId,
+        }),
+      });
+
+      if (!response.ok) {
+        this.config.logger("[OAuthService] Proxy token refresh failed", {
+          status: response.status,
+          proxyUrl,
+        });
+        return null;
+      }
+
+      const result = await response.json() as {
+        data?: {
+          access_token: string;
+          refresh_token?: string;
+          expires_in?: number;
+          token_type?: string;
+          scope?: string;
+        };
+        access_token?: string;
+        refresh_token?: string;
+        expires_in?: number;
+        token_type?: string;
+        scope?: string;
+      };
+      const tokens = result.data || result;
+
+      if (!tokens.access_token) {
+        this.config.logger("[OAuthService] Proxy token refresh response missing access_token");
+        return null;
+      }
+
+      // Calculate expiration timestamp
+      const expiresIn = tokens.expires_in || 3600; // Default 1 hour
+      const expiresAt = Date.now() + expiresIn * 1000;
+
+      const idpTokens: IdpTokens = {
+        access_token: tokens.access_token,
+        refresh_token: tokens.refresh_token || refreshToken,
+        expires_in: expiresIn,
+        expires_at: expiresAt,
+        token_type: tokens.token_type || "Bearer",
+        scope: tokens.scope,
+      };
+
+      this.config.logger("[OAuthService] Proxy token refresh successful", {
+        proxyUrl,
+        expiresAt: new Date(expiresAt).toISOString(),
+      });
+
+      return idpTokens;
+    } catch (error) {
+      this.config.logger("[OAuthService] Proxy token refresh error", {
+        error: error instanceof Error ? error.message : String(error),
+        proxyUrl,
+      });
+      return null;
+    }
+  }
+}
+