mcp-oauth-provider 0.0.1

package/src/client/storage.ts

@@ -0,0 +1,335 @@
+import type {
+  OAuthClientInformation,
+  OAuthClientInformationFull,
+  OAuthTokens,
+  StorageAdapter,
+} from './config.js';
+
+export type { StorageAdapter };
+
+/**
+ * Internal token storage format with absolute expiry timestamp
+ */
+interface StoredTokens extends Omit<OAuthTokens, 'expires_in'> {
+  /**
+   * Absolute timestamp (milliseconds) when the token expires
+   * This is derived from expires_in when tokens are saved
+   */
+  expires_at?: number;
+}
+
+/**
+ * Calculate expires_in from expires_at timestamp
+ */
+function calculateExpiresIn(expiresAt: number | undefined): number | undefined {
+  if (!expiresAt) {
+    return undefined;
+  }
+
+  const now = Date.now();
+  const expiresInMs = expiresAt - now;
+  const expiresInSeconds = Math.floor(expiresInMs / 1000);
+
+  // Return 0 if already expired, otherwise return remaining seconds
+  return Math.max(0, expiresInSeconds);
+}
+
+/**
+ * Calculate expires_at from expires_in
+ */
+function calculateExpiresAt(expiresIn: number | undefined): number {
+  return Date.now() + (expiresIn || 0) * 1000;
+}
+
+/**
+ * In-memory storage adapter for OAuth data
+ * Suitable for development and testing, but data is lost when process exits
+ */
+export class MemoryStorage implements StorageAdapter {
+  private data = new Map<string, string>();
+
+  async get(key: string): Promise<string | undefined> {
+    return this.data.get(key);
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    this.data.set(key, value);
+  }
+
+  async delete(key: string): Promise<void> {
+    this.data.delete(key);
+  }
+
+  /**
+   * Clear all data (useful for testing)
+   */
+  clear(): void {
+    this.data.clear();
+  }
+}
+
+/**
+ * File-based storage adapter for OAuth data
+ * Persists data to the filesystem for longer-term storage
+ */
+export class FileStorage implements StorageAdapter {
+  private basePath: string;
+
+  constructor(basePath = './oauth-data') {
+    this.basePath = basePath;
+  }
+
+  private getFilePath(key: string): string {
+    // Sanitize key for filename
+    const sanitized = key.replace(/[^a-zA-Z0-9-_]/g, '_');
+
+    return `${this.basePath}/${sanitized}.json`;
+  }
+
+  private async ensureDirectory(): Promise<void> {
+    try {
+      await Bun.write(`${this.basePath}/.gitkeep`, '');
+    } catch {
+      // Directory creation will happen automatically with Bun.write
+    }
+  }
+
+  async get(key: string): Promise<string | undefined> {
+    try {
+      const file = Bun.file(this.getFilePath(key));
+      const exists = await file.exists();
+
+      if (!exists) {
+        return undefined;
+      }
+
+      return await file.text();
+    } catch {
+      return undefined;
+    }
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    await this.ensureDirectory();
+    await Bun.write(this.getFilePath(key), value);
+  }
+
+  async delete(key: string): Promise<void> {
+    try {
+      await Bun.$`rm -f ${this.getFilePath(key)}`;
+    } catch {
+      // File might not exist, ignore error
+    }
+  }
+
+  /**
+   * Clear all data (useful for testing)
+   */
+  async clear(): Promise<void> {
+    try {
+      await Bun.$`rm -rf ${this.basePath}`;
+    } catch {
+      // Directory might not exist, ignore error
+    }
+  }
+}
+
+/**
+ * Create a storage adapter based on the provided configuration
+ */
+export function createStorageAdapter(
+  type?: 'memory' | 'file',
+  options?: { path?: string }
+): StorageAdapter {
+  switch (type) {
+    case 'file':
+      return new FileStorage(options?.path);
+    case 'memory':
+    default:
+      return new MemoryStorage();
+  }
+}
+
+/**
+ * Options for initializing OAuthStorage
+ */
+export interface OAuthStorageOptions {
+  /**
+   * Static client information (from config)
+   * If provided, will ALWAYS be returned (takes precedence over storage)
+   * This is because client credentials are like API keys - they don't change
+   */
+  staticClientInfo?: OAuthClientInformation;
+
+  /**
+   * Initial tokens (from config)
+   * If provided, will be stored ONCE on first access if storage is empty
+   * After that, storage takes precedence (tokens change over time)
+   */
+  initialTokens?: OAuthTokens;
+}
+
+/**
+ * Helper class to manage OAuth data with the simplified storage adapter
+ * Handles initialization from config and provides a unified storage interface
+ */
+export class OAuthStorage {
+  private initialized = false;
+
+  constructor(
+    private storage: StorageAdapter,
+    private sessionId: string,
+    private options?: OAuthStorageOptions
+  ) {}
+
+  /**
+   * Initialize storage with config values if provided
+   * This ensures config tokens are written to storage on first use
+   */
+  private async initialize(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+
+    this.initialized = true;
+
+    // Initialize tokens if provided and not already in storage
+    // (tokens are one-time initialization, storage takes over after that)
+    if (this.options?.initialTokens) {
+      const existing = await this.storage.get(`tokens:${this.sessionId}`);
+
+      if (!existing) {
+        // Convert expires_in to expires_at before storing
+        const storedTokens: StoredTokens = {
+          access_token: this.options.initialTokens.access_token,
+          token_type: this.options.initialTokens.token_type,
+          refresh_token: this.options.initialTokens.refresh_token,
+          scope: this.options.initialTokens.scope,
+        };
+
+        // Only set expires_at if expires_in is provided
+        if (this.options.initialTokens.expires_in !== undefined) {
+          storedTokens.expires_at = calculateExpiresAt(
+            this.options.initialTokens.expires_in
+          );
+        }
+
+        await this.storage.set(
+          `tokens:${this.sessionId}`,
+          JSON.stringify(storedTokens)
+        );
+      }
+    }
+  }
+
+  async saveTokens(tokens: OAuthTokens): Promise<void> {
+    await this.initialize();
+
+    // Convert expires_in to expires_at for storage
+    const storedTokens: StoredTokens = {
+      access_token: tokens.access_token,
+      token_type: tokens.token_type,
+      refresh_token: tokens.refresh_token,
+      scope: tokens.scope,
+    };
+
+    // Only set expires_at if expires_in is provided
+    if (tokens.expires_in !== undefined) {
+      storedTokens.expires_at = calculateExpiresAt(tokens.expires_in);
+    }
+
+    await this.storage.set(
+      `tokens:${this.sessionId}`,
+      JSON.stringify(storedTokens)
+    );
+  }
+
+  async getTokens(): Promise<OAuthTokens | undefined> {
+    await this.initialize();
+    const data = await this.storage.get(`tokens:${this.sessionId}`);
+
+    if (!data) {
+      return undefined;
+    }
+
+    const storedTokens: StoredTokens = JSON.parse(data);
+
+    // Convert expires_at back to expires_in for the OAuthTokens interface
+    const tokens: OAuthTokens = {
+      access_token: storedTokens.access_token,
+      token_type: storedTokens.token_type,
+    };
+
+    // Only include optional fields if they exist
+    if (storedTokens.refresh_token !== undefined) {
+      tokens.refresh_token = storedTokens.refresh_token;
+    }
+    if (storedTokens.scope !== undefined) {
+      tokens.scope = storedTokens.scope;
+    }
+    if (storedTokens.expires_at !== undefined) {
+      tokens.expires_in = calculateExpiresIn(storedTokens.expires_at);
+    }
+
+    return tokens;
+  }
+
+  async clearTokens(): Promise<void> {
+    await this.initialize();
+    await this.storage.delete(`tokens:${this.sessionId}`);
+  }
+
+  async saveClientInfo(clientInfo: OAuthClientInformationFull): Promise<void> {
+    await this.initialize();
+    await this.storage.set('client_info', JSON.stringify(clientInfo));
+  }
+
+  async getClientInfo(): Promise<OAuthClientInformation | undefined> {
+    await this.initialize();
+
+    // Static client info from config ALWAYS takes precedence
+    // (client credentials are like API keys - they don't change)
+    if (this.options?.staticClientInfo?.client_id) {
+      return this.options.staticClientInfo;
+    }
+
+    const data = await this.storage.get('client_info');
+
+    return data ? JSON.parse(data) : undefined;
+  }
+
+  async clearClientInfo(): Promise<void> {
+    await this.initialize();
+    await this.storage.delete('client_info');
+  }
+
+  async saveCodeVerifier(verifier: string): Promise<void> {
+    await this.initialize();
+    await this.storage.set(`verifier:${this.sessionId}`, verifier);
+  }
+
+  async getCodeVerifier(): Promise<string | undefined> {
+    await this.initialize();
+
+    return this.storage.get(`verifier:${this.sessionId}`);
+  }
+
+  async clearCodeVerifier(): Promise<void> {
+    await this.initialize();
+    await this.storage.delete(`verifier:${this.sessionId}`);
+  }
+
+  async clearSession(): Promise<void> {
+    await this.initialize();
+    await Promise.all([this.clearTokens(), this.clearCodeVerifier()]);
+  }
+
+  async clearAll(): Promise<void> {
+    await this.initialize();
+    await Promise.all([
+      this.clearTokens(),
+      this.clearCodeVerifier(),
+      this.clearClientInfo(),
+    ]);
+  }
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * MCP OAuth Provider
+ *
+ * OAuth client provider implementation for the Model Context Protocol (MCP)
+ */
+
+export { MCPOAuthClientProvider } from './client/index.js';
+
+export {
+  createStorageAdapter,
+  FileStorage,
+  MemoryStorage,
+  OAuthStorage,
+  type StorageAdapter,
+} from './client/storage.js';
+
+export {
+  DEFAULT_CLIENT_METADATA,
+  generateSessionId,
+  generateState,
+  type OAuthClientInformation,
+  type OAuthClientInformationFull,
+  type OAuthClientMetadata,
+  type OAuthConfig,
+  type OAuthTokens,
+} from './client/config.js';
+
+/**
+ * Factory function to create an OAuth client provider
+ */
+export { createOAuthProvider } from './client/factory';

package/src/server/callback.ts

@@ -0,0 +1,257 @@
+import { renderErrorPage, renderSuccessPage } from './templates.js';
+
+/**
+ * OAuth callback result interface
+ */
+export interface CallbackResult {
+  /** Authorization code returned by OAuth provider */
+  code?: string;
+  /** State parameter for CSRF protection */
+  state?: string;
+  /** OAuth error code (e.g., 'access_denied', 'invalid_request') */
+  error?: string;
+  /** Human-readable error description */
+  error_description?: string;
+  /** URI with additional error information */
+  error_uri?: string;
+  /** Additional query parameters from OAuth provider */
+  [key: string]: string | undefined;
+}
+
+/**
+ * Configuration options for the OAuth callback server
+ */
+export interface CallbackServerOptions {
+  /** Port number to bind the server to */
+  port: number;
+  /** Hostname to bind the server to (default: "localhost") */
+  hostname?: string;
+  /** Custom HTML content for successful authorization */
+  successHtml?: string;
+  /** Custom HTML template for error pages */
+  errorHtml?: string;
+  /** AbortSignal for cancelling the server operation */
+  signal?: AbortSignal;
+  /** Callback function called for each HTTP request */
+  onRequest?: (req: Request) => void;
+}
+
+/**
+ * OAuth callback server implementation using Bun
+ */
+export class OAuthCallbackServer {
+  private server?: { stop: () => void };
+  private callbackListeners = new Map<
+    string,
+    {
+      resolve: (result: CallbackResult) => void;
+      reject: (error: Error) => void;
+    }
+  >();
+  private options: CallbackServerOptions | undefined;
+
+  /**
+   * Start the HTTP server
+   */
+  async start(options: CallbackServerOptions): Promise<void> {
+    this.options = options;
+
+    if (this.server) {
+      throw new Error('Server is already running');
+    }
+
+    // Handle abort signal
+    if (options.signal?.aborted) {
+      throw new Error('Operation aborted');
+    }
+
+    const abortHandler = () => {
+      this.stop().catch(() => {
+        // Ignore errors during cleanup
+      });
+    };
+
+    if (options.signal) {
+      options.signal.addEventListener('abort', abortHandler);
+    }
+
+    try {
+      this.server = Bun.serve({
+        port: options.port,
+        hostname: options.hostname || 'localhost',
+        fetch: request => this.handleRequest(request),
+        error: error => {
+          return new Response(`Server error: ${error.message}`, {
+            status: 500,
+          });
+        },
+      });
+
+      // eslint-disable-next-line no-console
+      console.log(
+        `OAuth callback server running on http://${options.hostname || 'localhost'}:${options.port}`
+      );
+    } catch (error) {
+      if (options.signal) {
+        options.signal.removeEventListener('abort', abortHandler);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Handle incoming HTTP requests
+   */
+  private handleRequest(request: Request): Response {
+    this.options?.onRequest?.(request);
+
+    const url = new URL(request.url);
+    const listener = this.callbackListeners.get(url.pathname);
+
+    if (!listener) {
+      return new Response('Not Found', { status: 404 });
+    }
+
+    // Extract OAuth callback parameters from URL
+    const params: CallbackResult = {};
+
+    for (const [key, value] of url.searchParams.entries()) {
+      params[key] = value;
+    }
+
+    // Generate appropriate response
+    const hasError = Boolean(params.error);
+    const html = hasError
+      ? renderErrorPage(
+          params.error,
+          params.error_description,
+          params.error_uri,
+          this.options?.errorHtml
+        )
+      : renderSuccessPage(this.options?.successHtml);
+
+    // Resolve the waiting promise with params (including error params)
+    // The caller can check for params.error to determine if it was an OAuth error
+    listener.resolve(params);
+
+    // Return HTML response with appropriate status code
+    return new Response(html, {
+      status: hasError ? 400 : 200,
+      headers: {
+        'Content-Type': 'text/html; charset=utf-8',
+        'Cache-Control': 'no-cache, no-store, must-revalidate',
+        Pragma: 'no-cache',
+        Expires: '0',
+      },
+    });
+  }
+
+  /**
+   * Wait for OAuth callback on the specified path
+   */
+  async waitForCallback(
+    path: string,
+    timeout: number
+  ): Promise<CallbackResult> {
+    if (!this.server) {
+      throw new Error('Server is not running');
+    }
+
+    try {
+      return await Promise.race([
+        // Promise resolved by handleRequest method
+        new Promise<CallbackResult>((resolve, reject) => {
+          this.callbackListeners.set(path, { resolve, reject });
+        }),
+        // Timeout promise
+        new Promise<CallbackResult>((_, reject) => {
+          setTimeout(() => {
+            reject(
+              new Error(
+                `OAuth callback timeout after ${timeout}ms waiting for ${path}`
+              )
+            );
+          }, timeout);
+        }),
+      ]);
+    } finally {
+      // Always clean up the listener
+      this.callbackListeners.delete(path);
+    }
+  }
+
+  /**
+   * Stop the server and clean up resources
+   */
+  async stop(): Promise<void> {
+    if (this.server) {
+      // Reject any pending promises
+      const error = new Error('Server stopped');
+
+      for (const listener of this.callbackListeners.values()) {
+        // Reject in a try-catch to prevent unhandled promise rejections
+        try {
+          listener.reject(error);
+        } catch {
+          // Ignore - the caller may have already handled or abandoned this promise
+        }
+      }
+
+      this.callbackListeners.clear();
+
+      // Stop the server
+      await this.server.stop();
+      this.server = undefined;
+    }
+  }
+
+  /**
+   * Check if server is running
+   */
+  isRunning(): boolean {
+    return Boolean(this.server);
+  }
+
+  /**
+   * Get server URL if running
+   */
+  getServerUrl(): string | undefined {
+    if (!this.server || !this.options) {
+      return undefined;
+    }
+
+    const { hostname = 'localhost', port } = this.options;
+
+    return `http://${hostname}:${port}`;
+  }
+}
+
+/**
+ * Create and start a temporary OAuth callback server
+ */
+export async function createCallbackServer(
+  options: CallbackServerOptions
+): Promise<OAuthCallbackServer> {
+  const server = new OAuthCallbackServer();
+
+  await server.start(options);
+
+  return server;
+}
+
+/**
+ * Convenience function to start server, wait for callback, and stop server
+ */
+export async function waitForOAuthCallback(
+  path: string,
+  options: CallbackServerOptions & { timeout?: number }
+): Promise<CallbackResult> {
+  const server = await createCallbackServer(options);
+  const timeout = options.timeout ?? 30000; // 30 second default
+
+  try {
+    return await server.waitForCallback(path, timeout);
+  } finally {
+    await server.stop();
+  }
+}

package/src/server/index.ts

@@ -0,0 +1,21 @@
+/**
+ * OAuth Callback Server Module
+ *
+ * Provides HTTP server functionality for handling OAuth authorization callbacks
+ */
+
+export {
+  createCallbackServer,
+  OAuthCallbackServer,
+  waitForOAuthCallback,
+  type CallbackResult,
+  type CallbackServerOptions,
+} from './callback.js';
+
+export {
+  ERROR_TEMPLATE,
+  renderErrorPage,
+  renderSuccessPage,
+  renderTemplate,
+  SUCCESS_TEMPLATE,
+} from './templates.js';