mcp-oauth-provider 0.0.1

package/src/client/index.ts

@@ -0,0 +1,361 @@
+import type { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+import { AuthorizationServerMetadata } from '@modelcontextprotocol/sdk/shared/auth.js';
+import type {
+  OAuthClientInformation,
+  OAuthClientInformationFull,
+  OAuthClientMetadata,
+  OAuthConfig,
+  OAuthTokens,
+} from './config.js';
+import {
+  DEFAULT_CLIENT_METADATA,
+  generateSessionId,
+  generateState,
+} from './config.js';
+import { areTokensExpired, refreshTokensWithRetry } from './oauth-flow.js';
+import { MemoryStorage, OAuthStorage } from './storage.js';
+
+/**
+ * Options for token refresh
+ */
+interface TokenRefreshConfig {
+  maxRetries: number;
+  retryDelay: number;
+}
+
+/**
+ * MCP OAuth Client Provider implementation with automatic token refresh
+ */
+interface ProcessedOAuthConfig
+  extends Omit<
+    Required<OAuthConfig>,
+    'clientSecret' | 'tokens' | 'authorizationServerMetadata'
+  > {
+  clientSecret?: string;
+  tokens?: OAuthTokens;
+  clientMetadata: OAuthClientMetadata;
+  tokenRefresh: TokenRefreshConfig;
+}
+
+export class MCPOAuthClientProvider implements OAuthClientProvider {
+  private readonly config: ProcessedOAuthConfig;
+  private readonly oauthStorage: OAuthStorage;
+  private readonly sessionId: string;
+  private cachedClientInformation?: OAuthClientInformationFull;
+
+  public authorizationServerMetadata?: AuthorizationServerMetadata;
+
+  constructor(config: OAuthConfig) {
+    this.sessionId = config.sessionId ?? generateSessionId();
+    const storage = config.storage ?? new MemoryStorage();
+
+    // Set authorization server metadata if provided
+    if (config.authorizationServerMetadata) {
+      this.authorizationServerMetadata =
+        config.authorizationServerMetadata as AuthorizationServerMetadata;
+    }
+
+    this.oauthStorage = new OAuthStorage(storage, this.sessionId, {
+      staticClientInfo: config.clientId
+        ? {
+            client_id: config.clientId,
+            client_secret: config.clientSecret,
+          }
+        : undefined,
+      initialTokens: config.tokens,
+    });
+
+    // Merge with defaults
+    this.config = {
+      clientId: config.clientId ?? '',
+      clientSecret: config.clientSecret ?? undefined,
+      redirectUri: config.redirectUri,
+      scope: config.scope ?? 'read write',
+      sessionId: this.sessionId,
+      storage,
+      tokens: config.tokens,
+      clientMetadata: {
+        ...DEFAULT_CLIENT_METADATA,
+        ...(config.clientMetadata ?? {}),
+        redirect_uris: [config.redirectUri], // Always required
+        scope: config.scope ?? DEFAULT_CLIENT_METADATA.scope,
+      },
+      tokenRefresh: {
+        maxRetries: 3,
+        retryDelay: 1000,
+        ...(config.tokenRefresh ?? {}),
+      },
+    };
+  }
+
+  /**
+   * The URL to redirect the user agent to after authorization
+   */
+  get redirectUrl(): string | URL {
+    return this.config.redirectUri;
+  }
+
+  /**
+   * Metadata about this OAuth client
+   */
+  get clientMetadata(): OAuthClientMetadata {
+    return this.config.clientMetadata;
+  }
+
+  /**
+   * Returns a OAuth2 state parameter for CSRF protection
+   */
+  async state(): Promise<string> {
+    return generateState();
+  }
+
+  /**
+   * Loads information about this OAuth client
+   * Config credentials are initialized into storage, so all reads go through storage
+   */
+  async clientInformation(): Promise<OAuthClientInformation | undefined> {
+    return await this.oauthStorage.getClientInfo();
+  }
+
+  /**
+   * Saves client information after dynamic registration
+   */
+  async saveClientInformation(
+    clientInformation: OAuthClientInformationFull
+  ): Promise<void> {
+    this.cachedClientInformation = clientInformation;
+
+    await this.oauthStorage.saveClientInfo(clientInformation);
+  }
+
+  /**
+   * Loads any existing OAuth tokens for the current session
+   * Automatically refreshes tokens if they're expired or about to expire (within 5 minutes)
+   * Requires authorizationServerMetadata to be set (from auth flow) for automatic refresh
+   */
+  async tokens(): Promise<OAuthTokens | undefined> {
+    const currentTokens = await this.oauthStorage.getTokens();
+
+    if (!currentTokens) {
+      return undefined;
+    }
+
+    // Check if tokens are expired or about to expire (within 5 minutes)
+    const needsRefresh = areTokensExpired(currentTokens, undefined, 300);
+
+    // If tokens need refresh and we have the server metadata and refresh token, refresh automatically
+    if (
+      needsRefresh &&
+      currentTokens.refresh_token &&
+      this.authorizationServerMetadata?.token_endpoint
+    ) {
+      try {
+        // Use the token endpoint from authorization server metadata
+        const newTokens = await this.refreshTokens();
+
+        return newTokens;
+      } catch (error) {
+        // If refresh fails, return the current tokens and let the caller handle it
+        // This prevents breaking existing flows that might handle refresh differently
+        return currentTokens;
+      }
+    }
+
+    return currentTokens;
+  }
+
+  /**
+   * Refresh tokens using helper function
+   * Uses the token endpoint from authorizationServerMetadata
+   *
+   * @returns New OAuth tokens
+   * @throws Error if no authorization server metadata is available
+   */
+  async refreshTokens(): Promise<OAuthTokens> {
+    if (!this.authorizationServerMetadata?.token_endpoint) {
+      throw new Error(
+        'No authorization server metadata available. Cannot refresh tokens without token_endpoint.'
+      );
+    }
+
+    const { maxRetries, retryDelay } = this.config.tokenRefresh;
+
+    const currentTokens = await this.oauthStorage.getTokens();
+
+    if (!currentTokens?.refresh_token) {
+      throw new Error('No refresh token available');
+    }
+
+    const clientInfo = await this.clientInformation();
+
+    if (!clientInfo) {
+      throw new Error('No client information available');
+    }
+
+    try {
+      // Use helper function for retry logic with token endpoint
+      const newTokens = await refreshTokensWithRetry(
+        this.authorizationServerMetadata.token_endpoint,
+        clientInfo,
+        currentTokens.refresh_token,
+        this.addClientAuthentication,
+        maxRetries,
+        retryDelay
+      );
+
+      // Save the new tokens
+      await this.oauthStorage.saveTokens(newTokens);
+
+      return newTokens;
+    } catch (error) {
+      // All retries failed, invalidate tokens
+      await this.invalidateCredentials('tokens');
+      throw error;
+    }
+  }
+
+  /**
+   * Loads any existing OAuth tokens for the current session (without auto-refresh)
+   * Use this if you want to check tokens without triggering a refresh
+   */
+  async getStoredTokens(): Promise<OAuthTokens | undefined> {
+    return this.oauthStorage.getTokens();
+  }
+
+  /**
+   * Stores new OAuth tokens for the current session
+   */
+  async saveTokens(tokens: OAuthTokens): Promise<void> {
+    await this.oauthStorage.saveTokens(tokens);
+  }
+
+  /**
+   * Invoked to redirect the user agent to the given URL to begin the authorization flow
+   */
+  async redirectToAuthorization(authorizationUrl: URL): Promise<void> {
+    // In a real implementation, this would open a browser or redirect the user
+    // For now, we'll let the caller handle the redirect by throwing an error with the URL
+
+    // In a Bun environment, we could automatically open the browser:
+    if (typeof Bun !== 'undefined') {
+      try {
+        await Bun.$`open ${authorizationUrl.toString()}`;
+
+        return;
+      } catch {
+        // Fallback if 'open' command is not available
+      }
+    }
+
+    // If we can't automatically open, throw an error with the URL for the caller to handle
+    throw new Error(`Please navigate to: ${authorizationUrl.toString()}`);
+  }
+
+  /**
+   * Saves a PKCE code verifier for the current session
+   */
+  async saveCodeVerifier(codeVerifier: string): Promise<void> {
+    await this.oauthStorage.saveCodeVerifier(codeVerifier);
+  }
+
+  /**
+   * Loads the PKCE code verifier for the current session
+   */
+  async codeVerifier(): Promise<string> {
+    const verifier = await this.oauthStorage.getCodeVerifier();
+
+    if (!verifier) {
+      throw new Error('No code verifier found for current session');
+    }
+
+    return verifier;
+  }
+
+  /**
+   * Adds custom client authentication to OAuth token requests
+   */
+  addClientAuthentication = (
+    headers: Headers,
+    params: URLSearchParams,
+    url: string | URL,
+    metadata?: AuthorizationServerMetadata
+  ): void => {
+    const clientInfo = this.cachedClientInformation;
+
+    this.authorizationServerMetadata = metadata;
+
+    if (!clientInfo) {
+      throw new Error('No client information available for authentication');
+    }
+
+    // Use client_secret_post method by default
+    params.set('client_id', clientInfo.client_id);
+
+    if (clientInfo.client_secret) {
+      params.set('client_secret', clientInfo.client_secret);
+    }
+  };
+
+  /**
+   * Validates the resource URL for OAuth requests
+   */
+  async validateResourceURL(
+    serverUrl: string | URL,
+    resource?: string
+  ): Promise<URL | undefined> {
+    // Simple validation - in a real implementation you might want more sophisticated logic
+    if (resource) {
+      try {
+        return new URL(resource);
+      } catch {
+        throw new Error(`Invalid resource URL: ${resource}`);
+      }
+    }
+
+    // Default to server URL if no specific resource is provided
+    return new URL(serverUrl);
+  }
+
+  /**
+   * Invalidates stored credentials based on the specified scope
+   */
+  async invalidateCredentials(
+    scope: 'all' | 'client' | 'tokens' | 'verifier'
+  ): Promise<void> {
+    switch (scope) {
+      case 'all':
+        await this.oauthStorage.clearAll();
+        break;
+      case 'client':
+        await this.oauthStorage.clearClientInfo();
+        break;
+      case 'tokens':
+        await this.oauthStorage.clearTokens();
+        break;
+      case 'verifier':
+        await this.oauthStorage.clearCodeVerifier();
+        break;
+    }
+  }
+
+  /**
+   * Get the current session ID
+   */
+  getSessionId(): string {
+    return this.sessionId;
+  }
+
+  /**
+   * Get the OAuth storage helper
+   */
+  getOAuthStorage(): OAuthStorage {
+    return this.oauthStorage;
+  }
+
+  /**
+   * Clear the current session
+   */
+  async clearSession(): Promise<void> {
+    await this.oauthStorage.clearSession();
+  }
+}

package/src/client/oauth-flow.ts

@@ -0,0 +1,115 @@
+/**
+ * OAuth Flow Helpers
+ *
+ * Pure utility functions for OAuth operations
+ */
+
+import { refreshAuthorization } from '@modelcontextprotocol/sdk/client/auth.js';
+import type {
+  AuthorizationServerMetadata,
+  OAuthClientInformation,
+  OAuthTokens,
+} from '@modelcontextprotocol/sdk/shared/auth.js';
+
+/**
+ * Check if tokens are expired or about to expire
+ *
+ * @param tokens - OAuth tokens to check
+ * @param tokenExpiryTime - Tracked expiry timestamp (if available)
+ * @param bufferSeconds - Number of seconds before expiry to consider expired (default: 300 = 5 minutes)
+ * @returns true if tokens are expired or will expire soon
+ */
+export function areTokensExpired(
+  tokens: OAuthTokens | undefined,
+  tokenExpiryTime?: number,
+  bufferSeconds = 300
+): boolean {
+  if (!tokens) {
+    return true;
+  }
+
+  // If we have a tracked expiry time, use it (most accurate)
+  if (tokenExpiryTime) {
+    const now = Date.now();
+
+    return now >= tokenExpiryTime - bufferSeconds * 1000;
+  }
+
+  // If no expiry info, assume tokens are valid
+  if (tokens.expires_in === undefined) {
+    return false;
+  }
+
+  // Check if tokens will expire within the buffer period
+  // Note: expires_in is now derived from stored expires_at, so it's always accurate
+  return tokens.expires_in <= bufferSeconds;
+}
+
+/**
+ * Refresh OAuth tokens with retry logic
+ *
+ * @param serverUrl - Authorization server URL
+ * @param clientInfo - Client information
+ * @param refreshToken - Current refresh token
+ * @param addClientAuth - Client authentication function
+ * @param maxRetries - Maximum retry attempts (default: 3)
+ * @param retryDelay - Base delay between retries in ms (default: 1000)
+ * @param fetchFn - Optional custom fetch function
+ * @returns New OAuth tokens
+ * @throws Error if refresh fails after all retries
+ */
+export async function refreshTokensWithRetry(
+  serverUrl: string | URL,
+  clientInfo: OAuthClientInformation,
+  refreshToken: string,
+  addClientAuth?: (
+    headers: Headers,
+    params: URLSearchParams,
+    url: string | URL,
+    metadata?: AuthorizationServerMetadata
+  ) => void | Promise<void>,
+  maxRetries = 3,
+  retryDelay = 1000,
+  fetchFn?: typeof fetch
+): Promise<OAuthTokens> {
+  let lastError: Error | undefined;
+
+  /* eslint-disable no-await-in-loop */
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      // Attempt token refresh using SDK function
+      const newTokens = await refreshAuthorization(serverUrl, {
+        clientInformation: clientInfo,
+        refreshToken,
+        addClientAuthentication: addClientAuth,
+        fetchFn,
+      });
+
+      return newTokens;
+    } catch (error) {
+      lastError = error as Error;
+
+      // If this isn't the last attempt, wait before retrying
+      if (attempt < maxRetries - 1) {
+        await new Promise(resolve =>
+          setTimeout(resolve, retryDelay * (attempt + 1))
+        );
+      }
+    }
+  }
+  /* eslint-enable no-await-in-loop */
+
+  throw new Error(
+    `Token refresh failed after ${maxRetries} attempts: ${lastError?.message || 'Unknown error'}`
+  );
+}
+
+/**
+ * Calculate token expiry timestamp
+ *
+ * @param expiresIn - Token lifetime in seconds
+ * @returns Expiry timestamp in milliseconds
+ */
+export function calculateTokenExpiry(expiresIn: number): number {
+  return Date.now() + expiresIn * 1000;
+}