integrate-sdk 0.3.7 → 0.3.8

package/src/oauth/manager.ts

@@ -1,307 +0,0 @@
-/**
- * OAuth Manager
- * Orchestrates OAuth 2.0 Authorization Code Flow with PKCE
- */
-
-import type { OAuthConfig } from "../plugins/types.js";
-import type {
-  OAuthFlowConfig,
-  PendingAuth,
-  AuthStatus,
-  AuthorizationUrlResponse,
-  OAuthCallbackResponse,
-} from "./types.js";
-import { generateCodeVerifier, generateCodeChallenge, generateState } from "./pkce.js";
-import { OAuthWindowManager } from "./window-manager.js";
-
-/**
- * OAuth Manager
- * Handles OAuth authorization flows and token management
- */
-export class OAuthManager {
-  private pendingAuths: Map<string, PendingAuth> = new Map();
-  private sessionToken?: string;
-  private windowManager: OAuthWindowManager;
-  private flowConfig: OAuthFlowConfig;
-  private oauthApiBase: string;
-
-  constructor(
-    oauthApiBase: string,
-    flowConfig?: Partial<OAuthFlowConfig>
-  ) {
-    this.oauthApiBase = oauthApiBase;
-    this.windowManager = new OAuthWindowManager();
-    this.flowConfig = {
-      mode: flowConfig?.mode || 'redirect',
-      popupOptions: flowConfig?.popupOptions,
-      onAuthCallback: flowConfig?.onAuthCallback,
-    };
-  }
-
-  /**
-   * Initiate OAuth authorization flow
-   * 
-   * @param provider - OAuth provider (github, gmail, etc.)
-   * @param config - OAuth configuration
-   * @returns Promise that resolves when authorization is complete
-   * 
-   * @example
-   * ```typescript
-   * await oauthManager.initiateFlow('github', {
-   *   provider: 'github',
-   *   clientId: 'abc123',
-   *   clientSecret: 'secret',
-   *   scopes: ['repo', 'user']
-   * });
-   * ```
-   */
-  async initiateFlow(provider: string, config: OAuthConfig): Promise<void> {
-    // 1. Generate PKCE parameters
-    const codeVerifier = generateCodeVerifier();
-    const codeChallenge = await generateCodeChallenge(codeVerifier);
-    const state = generateState();
-
-    // 2. Store pending auth
-    const pendingAuth: PendingAuth = {
-      provider,
-      state,
-      codeVerifier,
-      codeChallenge,
-      scopes: config.scopes,
-      redirectUri: config.redirectUri,
-      initiatedAt: Date.now(),
-    };
-    this.pendingAuths.set(state, pendingAuth);
-
-    // 3. Request authorization URL from user's API route
-    const authUrl = await this.getAuthorizationUrl(provider, config.scopes, state, codeChallenge, config.redirectUri);
-
-    // 4. Open authorization URL (popup or redirect)
-    if (this.flowConfig.mode === 'popup') {
-      this.windowManager.openPopup(authUrl, this.flowConfig.popupOptions);
-      
-      // Wait for callback from popup
-      try {
-        const callbackParams = await this.windowManager.listenForCallback('popup');
-        await this.handleCallback(callbackParams.code, callbackParams.state);
-      } catch (error) {
-        // Clean up pending auth on error
-        this.pendingAuths.delete(state);
-        throw error;
-      }
-    } else {
-      // For redirect mode, just redirect - callback will be handled separately
-      this.windowManager.openRedirect(authUrl);
-    }
-  }
-
-  /**
-   * Handle OAuth callback
-   * Call this after user authorizes (from your callback page)
-   * 
-   * @param code - Authorization code from OAuth provider
-   * @param state - State parameter for verification
-   * @returns Session token for authenticated requests
-   * 
-   * @example
-   * ```typescript
-   * // In your callback route
-   * const sessionToken = await oauthManager.handleCallback(code, state);
-   * ```
-   */
-  async handleCallback(code: string, state: string): Promise<string> {
-    // 1. Verify state and get pending auth
-    const pendingAuth = this.pendingAuths.get(state);
-    
-    if (!pendingAuth) {
-      throw new Error('Invalid state parameter: no matching OAuth flow found');
-    }
-
-    // Check if auth is not too old (5 minutes)
-    const fiveMinutes = 5 * 60 * 1000;
-    if (Date.now() - pendingAuth.initiatedAt > fiveMinutes) {
-      this.pendingAuths.delete(state);
-      throw new Error('OAuth flow expired: please try again');
-    }
-
-    // Call custom callback handler if provided
-    if (this.flowConfig.onAuthCallback) {
-      try {
-        await this.flowConfig.onAuthCallback(pendingAuth.provider, code, state);
-      } catch (error) {
-        console.error('Custom OAuth callback handler failed:', error);
-      }
-    }
-
-    // 2. Send to user's API route for token exchange
-    try {
-      const response = await this.exchangeCodeForToken(
-        pendingAuth.provider,
-        code,
-        pendingAuth.codeVerifier,
-        state
-      );
-
-      // 3. Store session token
-      this.sessionToken = response.sessionToken;
-
-      // 4. Clean up pending auth
-      this.pendingAuths.delete(state);
-
-      return response.sessionToken;
-    } catch (error) {
-      this.pendingAuths.delete(state);
-      throw error;
-    }
-  }
-
-  /**
-   * Check authorization status for a provider
-   * 
-   * @param provider - OAuth provider to check
-   * @returns Authorization status
-   * 
-   * @example
-   * ```typescript
-   * const status = await oauthManager.checkAuthStatus('github');
-   * if (status.authorized) {
-   *   console.log('GitHub is authorized');
-   * }
-   * ```
-   */
-  async checkAuthStatus(provider: string): Promise<AuthStatus> {
-    if (!this.sessionToken) {
-      return {
-        authorized: false,
-        provider,
-      };
-    }
-
-    try {
-      const url = `${this.oauthApiBase}/status?provider=${encodeURIComponent(provider)}`;
-
-      const response = await fetch(url, {
-        method: 'GET',
-        headers: {
-          'X-Session-Token': this.sessionToken,
-        },
-      });
-
-      if (!response.ok) {
-        return {
-          authorized: false,
-          provider,
-        };
-      }
-
-      const status = await response.json() as AuthStatus;
-      return status;
-    } catch (error) {
-      console.error('Failed to check auth status:', error);
-      return {
-        authorized: false,
-        provider,
-      };
-    }
-  }
-
-  /**
-   * Get session token
-   */
-  getSessionToken(): string | undefined {
-    return this.sessionToken;
-  }
-
-  /**
-   * Set session token (for manual token management)
-   */
-  setSessionToken(token: string): void {
-    this.sessionToken = token;
-  }
-
-  /**
-   * Clear session token
-   */
-  clearSessionToken(): void {
-    this.sessionToken = undefined;
-  }
-
-  /**
-   * Request authorization URL from user's API route
-   * The API route will add OAuth secrets and forward to MCP server
-   */
-  private async getAuthorizationUrl(
-    provider: string,
-    scopes: string[],
-    state: string,
-    codeChallenge: string,
-    redirectUri?: string
-  ): Promise<string> {
-    const url = `${this.oauthApiBase}/authorize`;
-
-    const response = await fetch(url, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify({
-        provider,
-        scopes,
-        state,
-        codeChallenge,
-        codeChallengeMethod: 'S256',
-        redirectUri,
-      }),
-    });
-
-    if (!response.ok) {
-      const error = await response.text();
-      throw new Error(`Failed to get authorization URL: ${error}`);
-    }
-
-    const data = await response.json() as AuthorizationUrlResponse;
-    return data.authorizationUrl;
-  }
-
-  /**
-   * Exchange authorization code for session token via user's API route
-   * The API route will forward to MCP server
-   */
-  private async exchangeCodeForToken(
-    provider: string,
-    code: string,
-    codeVerifier: string,
-    state: string
-  ): Promise<OAuthCallbackResponse> {
-    const url = `${this.oauthApiBase}/callback`;
-
-    const response = await fetch(url, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify({
-        provider,
-        code,
-        codeVerifier,
-        state,
-      }),
-    });
-
-    if (!response.ok) {
-      const error = await response.text();
-      throw new Error(`Failed to exchange code for token: ${error}`);
-    }
-
-    const data = await response.json() as OAuthCallbackResponse;
-    return data;
-  }
-
-  /**
-   * Close any open OAuth windows
-   */
-  close(): void {
-    this.windowManager.close();
-  }
-}
-

package/src/oauth/pkce.ts

@@ -1,127 +0,0 @@
-/**
- * PKCE Utilities
- * Proof Key for Code Exchange (RFC 7636) implementation
- * 
- * PKCE enhances OAuth 2.0 security by preventing authorization code interception attacks.
- * It's especially important for public clients (browser/mobile apps).
- */
-
-/**
- * Generate a cryptographically secure random code verifier
- * Must be 43-128 characters long, using [A-Z] [a-z] [0-9] - . _ ~
- * 
- * @returns A random code verifier string
- * 
- * @example
- * ```typescript
- * const verifier = generateCodeVerifier();
- * // Returns: "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
- * ```
- */
-export function generateCodeVerifier(): string {
-  // Generate 32 random bytes (will be 43 characters when base64url encoded)
-  const array = new Uint8Array(32);
-  
-  if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
-    // Browser/modern environment
-    crypto.getRandomValues(array);
-  } else if (typeof globalThis !== 'undefined' && (globalThis as any).crypto) {
-    // Node.js 19+
-    (globalThis as any).crypto.getRandomValues(array);
-  } else {
-    // Fallback for older Node.js
-    throw new Error('crypto.getRandomValues is not available. Please use Node.js 19+ or a modern browser.');
-  }
-  
-  return base64UrlEncode(array);
-}
-
-/**
- * Generate code challenge from verifier using SHA-256
- * 
- * @param verifier - The code verifier to hash
- * @returns A Promise resolving to the base64url-encoded SHA-256 hash
- * 
- * @example
- * ```typescript
- * const verifier = generateCodeVerifier();
- * const challenge = await generateCodeChallenge(verifier);
- * // Returns: "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
- * ```
- */
-export async function generateCodeChallenge(verifier: string): Promise<string> {
-  // Convert verifier to Uint8Array
-  const encoder = new TextEncoder();
-  const data = encoder.encode(verifier);
-  
-  // Hash with SHA-256
-  let hashBuffer: ArrayBuffer;
-  
-  if (typeof crypto !== 'undefined' && crypto.subtle) {
-    // Browser/modern environment
-    hashBuffer = await crypto.subtle.digest('SHA-256', data);
-  } else if (typeof globalThis !== 'undefined' && (globalThis as any).crypto?.subtle) {
-    // Node.js 19+
-    hashBuffer = await (globalThis as any).crypto.subtle.digest('SHA-256', data);
-  } else {
-    // Fallback for older Node.js
-    throw new Error('crypto.subtle.digest is not available. Please use Node.js 19+ or a modern browser.');
-  }
-  
-  // Convert to base64url
-  return base64UrlEncode(new Uint8Array(hashBuffer));
-}
-
-/**
- * Generate a random state parameter for CSRF protection
- * 
- * @returns A random state string
- * 
- * @example
- * ```typescript
- * const state = generateState();
- * // Returns: "xyzABC123"
- * ```
- */
-export function generateState(): string {
-  // Generate 16 random bytes (will be 22 characters when base64url encoded)
-  const array = new Uint8Array(16);
-  
-  if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
-    crypto.getRandomValues(array);
-  } else if (typeof globalThis !== 'undefined' && (globalThis as any).crypto) {
-    (globalThis as any).crypto.getRandomValues(array);
-  } else {
-    throw new Error('crypto.getRandomValues is not available. Please use Node.js 19+ or a modern browser.');
-  }
-  
-  return base64UrlEncode(array);
-}
-
-/**
- * Base64url encode a Uint8Array
- * Base64url encoding uses URL-safe characters (no +, /, =)
- * 
- * @param array - The byte array to encode
- * @returns Base64url-encoded string
- */
-function base64UrlEncode(array: Uint8Array): string {
-  // Convert to base64
-  let base64 = '';
-  
-  if (typeof Buffer !== 'undefined') {
-    // Node.js
-    base64 = Buffer.from(array).toString('base64');
-  } else {
-    // Browser
-    const binary = String.fromCharCode(...array);
-    base64 = btoa(binary);
-  }
-  
-  // Convert to base64url (replace +/= with -_)
-  return base64
-    .replace(/\+/g, '-')
-    .replace(/\//g, '_')
-    .replace(/=/g, '');
-}
-

package/src/oauth/types.ts

@@ -1,101 +0,0 @@
-/**
- * OAuth Flow Types
- * Type definitions for OAuth 2.0 Authorization Code Flow with PKCE
- */
-
-/**
- * Popup window options for OAuth flow
- */
-export interface PopupOptions {
-  /** Window width in pixels (default: 600) */
-  width?: number;
-  /** Window height in pixels (default: 700) */
-  height?: number;
-}
-
-/**
- * OAuth flow configuration
- */
-export interface OAuthFlowConfig {
-  /** How to display OAuth authorization */
-  mode: 'popup' | 'redirect';
-  /** Popup window dimensions (only for popup mode) */
-  popupOptions?: PopupOptions;
-  /** Custom callback handler for receiving auth code */
-  onAuthCallback?: (provider: string, code: string, state: string) => Promise<void>;
-}
-
-/**
- * Authorization status for a provider
- */
-export interface AuthStatus {
-  /** Whether the provider is authorized */
-  authorized: boolean;
-  /** The provider name */
-  provider: string;
-  /** Authorized scopes */
-  scopes?: string[];
-  /** Token expiration time */
-  expiresAt?: string;
-}
-
-/**
- * Pending OAuth authorization
- * Tracks in-progress OAuth flows
- */
-export interface PendingAuth {
-  /** OAuth provider (github, gmail, etc.) */
-  provider: string;
-  /** CSRF protection state */
-  state: string;
-  /** PKCE code verifier */
-  codeVerifier: string;
-  /** PKCE code challenge */
-  codeChallenge: string;
-  /** OAuth scopes being requested */
-  scopes: string[];
-  /** Redirect URI */
-  redirectUri?: string;
-  /** Timestamp when auth was initiated */
-  initiatedAt: number;
-}
-
-/**
- * OAuth authorization URL response from server
- */
-export interface AuthorizationUrlResponse {
-  /** The full authorization URL to redirect user to */
-  authorizationUrl: string;
-}
-
-/**
- * OAuth callback response from server
- * Contains session token after successful authorization
- */
-export interface OAuthCallbackResponse {
-  /** Session token for authenticated requests */
-  sessionToken: string;
-  /** Token expiration time */
-  expiresAt?: string;
-}
-
-/**
- * Parameters for OAuth callback
- */
-export interface OAuthCallbackParams {
-  /** Authorization code from OAuth provider */
-  code: string;
-  /** State parameter for CSRF protection */
-  state: string;
-}
-
-/**
- * Configuration for OAuth callback route handler
- */
-export interface OAuthCallbackHandlerConfig {
-  /** URL to redirect to after successful OAuth (default: '/') */
-  redirectUrl?: string;
-  /** URL to redirect to on OAuth error (default: '/auth-error') */
-  errorRedirectUrl?: string;
-}
-