@leanmcp/auth 0.3.1 → 0.4.0

package/dist/client/index.d.ts

@@ -0,0 +1,499 @@
+import { T as TokenStorage, O as OAuthTokens } from '../types-DMpGN530.js';
+
+/**
+ * PKCE (Proof Key for Code Exchange) utilities for OAuth 2.1
+ *
+ * RFC 7636: https://tools.ietf.org/html/rfc7636
+ *
+ * PKCE protects against authorization code interception attacks
+ * by using a cryptographic challenge during the OAuth flow.
+ */
+/**
+ * PKCE code challenge and verifier pair
+ */
+interface PKCEPair {
+    /** High-entropy random string (43-128 chars) */
+    verifier: string;
+    /** SHA256 hash of verifier, base64url encoded */
+    challenge: string;
+    /** Challenge method - always S256 for security */
+    method: 'S256';
+}
+/**
+ * Generate a cryptographically secure PKCE code verifier.
+ *
+ * The verifier is a high-entropy random string between 43-128 characters
+ * using unreserved characters: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
+ *
+ * @param length - Length of the verifier (default: 64, min: 43, max: 128)
+ * @returns Base64url-encoded random string
+ */
+declare function generateCodeVerifier(length?: number): string;
+/**
+ * Generate a PKCE code challenge from a code verifier.
+ *
+ * Uses the S256 method: BASE64URL(SHA256(verifier))
+ *
+ * @param verifier - The code verifier string
+ * @returns Base64url-encoded SHA256 hash
+ */
+declare function generateCodeChallenge(verifier: string): string;
+/**
+ * Generate a complete PKCE pair (verifier and challenge).
+ *
+ * @example
+ * ```typescript
+ * const pkce = generatePKCE();
+ * // Send challenge in authorization request
+ * const authUrl = `${authorizationEndpoint}?code_challenge=${pkce.challenge}&code_challenge_method=S256`;
+ * // Send verifier in token request
+ * const tokenPayload = { code_verifier: pkce.verifier, ... };
+ * ```
+ *
+ * @param verifierLength - Length of the verifier (default: 64)
+ * @returns PKCE pair with verifier, challenge, and method
+ */
+declare function generatePKCE(verifierLength?: number): PKCEPair;
+/**
+ * Verify that a code verifier matches a code challenge.
+ *
+ * Used server-side to validate PKCE during token exchange.
+ *
+ * @param verifier - The code verifier from token request
+ * @param challenge - The code challenge from authorization request
+ * @param method - The challenge method (only 'S256' supported)
+ * @returns True if verifier matches challenge
+ */
+declare function verifyPKCE(verifier: string, challenge: string, method?: 'S256' | 'plain'): boolean;
+/**
+ * Validate that a string is a valid PKCE code verifier.
+ *
+ * @param verifier - String to validate
+ * @returns True if valid verifier format
+ */
+declare function isValidCodeVerifier(verifier: string): boolean;
+
+/**
+ * OAuth 2.1 Client for MCP
+ *
+ * Handles browser-based OAuth flows with PKCE support.
+ * Compatible with MCP servers and external OAuth providers.
+ */
+
+/**
+ * OAuth client configuration
+ */
+interface OAuthClientOptions {
+    /** MCP server URL or OAuth authorization server URL */
+    serverUrl: string;
+    /** OAuth scopes to request */
+    scopes?: string[];
+    /** Client name for dynamic registration */
+    clientName?: string;
+    /** Token storage backend */
+    storage?: TokenStorage;
+    /** Pre-configured client credentials (skip dynamic registration) */
+    clientId?: string;
+    clientSecret?: string;
+    /** Custom OAuth endpoints (auto-discovered if not provided) */
+    authorizationEndpoint?: string;
+    tokenEndpoint?: string;
+    registrationEndpoint?: string;
+    /** Enable PKCE (default: true) */
+    pkceEnabled?: boolean;
+    /** Automatically refresh tokens before expiry (default: true) */
+    autoRefresh?: boolean;
+    /** Seconds before expiry to trigger refresh (default: 60) */
+    refreshBuffer?: number;
+    /** Callback server port (default: auto) */
+    callbackPort?: number;
+    /** OAuth timeout in ms (default: 5 minutes) */
+    timeout?: number;
+}
+/**
+ * OAuth 2.1 client with PKCE and browser-based authentication
+ *
+ * @example
+ * ```typescript
+ * const client = new OAuthClient({
+ *   serverUrl: 'https://mcp.example.com',
+ *   scopes: ['read', 'write'],
+ * });
+ *
+ * // Start browser-based OAuth flow
+ * await client.authenticate();
+ *
+ * // Get token for API calls
+ * const token = await client.getValidToken();
+ * ```
+ */
+declare class OAuthClient {
+    private serverUrl;
+    private scopes;
+    private clientName;
+    private storage;
+    private pkceEnabled;
+    private autoRefresh;
+    private refreshBuffer;
+    private callbackPort?;
+    private timeout;
+    private authorizationEndpoint?;
+    private tokenEndpoint?;
+    private registrationEndpoint?;
+    private preConfiguredClientId?;
+    private preConfiguredClientSecret?;
+    private pendingRefresh?;
+    private metadata?;
+    constructor(options: OAuthClientOptions);
+    /**
+     * Discover OAuth metadata from .well-known endpoint
+     */
+    private discoverMetadata;
+    /**
+     * Get or register OAuth client credentials
+     */
+    private getClientCredentials;
+    /**
+     * Start the browser-based OAuth flow
+     *
+     * Opens the user's browser to the authorization URL and waits for the callback.
+     *
+     * @returns OAuth tokens
+     */
+    authenticate(): Promise<OAuthTokens>;
+    /**
+     * Open URL in browser
+     */
+    private openBrowser;
+    /**
+     * Exchange authorization code for tokens
+     */
+    private exchangeCodeForTokens;
+    /**
+     * Refresh the access token using the refresh token
+     */
+    refreshTokens(): Promise<OAuthTokens>;
+    private doRefreshTokens;
+    /**
+     * Get a valid access token, refreshing if necessary
+     */
+    getValidToken(): Promise<string>;
+    /**
+     * Get current tokens (may be expired)
+     */
+    getTokens(): Promise<OAuthTokens | null>;
+    /**
+     * Check if we have valid (non-expired) tokens
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Clear stored tokens and log out
+     */
+    logout(): Promise<void>;
+    /**
+     * Create an auth handler for HTTP requests
+     *
+     * @example
+     * ```typescript
+     * const authHandler = client.asAuthHandler();
+     * const authedRequest = await authHandler(request);
+     * ```
+     */
+    asAuthHandler(): (request: Request) => Promise<Request>;
+}
+
+/**
+ * Local HTTP callback server for OAuth redirects
+ *
+ * Spins up a temporary HTTP server to catch OAuth authorization callbacks.
+ * Used during browser-based OAuth flows.
+ */
+/**
+ * Result from OAuth callback
+ */
+interface CallbackResult {
+    /** Authorization code from the OAuth server */
+    code: string;
+    /** State parameter for CSRF protection */
+    state: string;
+}
+/**
+ * Error from OAuth callback
+ */
+interface CallbackError {
+    error: string;
+    error_description?: string;
+}
+/**
+ * Options for the callback server
+ */
+interface CallbackServerOptions {
+    /** Port to listen on (0 = auto-assign) */
+    port?: number;
+    /** Host to bind to (default: 127.0.0.1) */
+    host?: string;
+    /** Callback path (default: /callback) */
+    path?: string;
+    /** Timeout in milliseconds (default: 5 minutes) */
+    timeout?: number;
+    /** Custom success HTML */
+    successHtml?: string;
+    /** Custom error HTML */
+    errorHtml?: string;
+}
+/**
+ * Running callback server instance
+ */
+interface CallbackServer {
+    /** Full URL to use as redirect_uri */
+    redirectUri: string;
+    /** Port the server is listening on */
+    port: number;
+    /** Wait for the OAuth callback */
+    waitForCallback(): Promise<CallbackResult>;
+    /** Shutdown the server */
+    shutdown(): Promise<void>;
+}
+/**
+ * Start a local callback server for OAuth redirects
+ *
+ * @example
+ * ```typescript
+ * const server = await startCallbackServer({ port: 0 });
+ * console.log('Redirect URI:', server.redirectUri);
+ *
+ * // Open browser to authorization URL with redirect_uri set to server.redirectUri
+ *
+ * const result = await server.waitForCallback();
+ * console.log('Got code:', result.code);
+ *
+ * await server.shutdown();
+ * ```
+ */
+declare function startCallbackServer(options?: CallbackServerOptions): Promise<CallbackServer>;
+/**
+ * Find an available port
+ */
+declare function findAvailablePort(preferredPort?: number): Promise<number>;
+
+/**
+ * OAuth Metadata Discovery (RFC 8414)
+ *
+ * Discovers OAuth 2.0 authorization server metadata from .well-known endpoints.
+ * Supports both OAuth 2.0 and OpenID Connect discovery.
+ */
+/**
+ * OAuth 2.0 Authorization Server Metadata
+ * https://tools.ietf.org/html/rfc8414
+ */
+interface OAuthMetadata {
+    /** Authorization server's issuer identifier URL */
+    issuer: string;
+    /** URL of the authorization endpoint */
+    authorization_endpoint: string;
+    /** URL of the token endpoint */
+    token_endpoint: string;
+    /** URL of the dynamic client registration endpoint */
+    registration_endpoint?: string;
+    /** URL of the token revocation endpoint */
+    revocation_endpoint?: string;
+    /** URL of the token introspection endpoint */
+    introspection_endpoint?: string;
+    /** URL of the userinfo endpoint (OpenID Connect) */
+    userinfo_endpoint?: string;
+    /** URL of the JWKS endpoint */
+    jwks_uri?: string;
+    /** Scopes supported by the authorization server */
+    scopes_supported?: string[];
+    /** Response types supported */
+    response_types_supported?: string[];
+    /** Response modes supported */
+    response_modes_supported?: string[];
+    /** Grant types supported */
+    grant_types_supported?: string[];
+    /** Token endpoint auth methods supported */
+    token_endpoint_auth_methods_supported?: string[];
+    /** Code challenge methods supported (PKCE) */
+    code_challenge_methods_supported?: string[];
+    /** Whether server requires PKCE */
+    require_pkce?: boolean;
+}
+/**
+ * Discovery options
+ */
+interface DiscoveryOptions {
+    /** Request timeout in ms (default: 10000) */
+    timeout?: number;
+    /** Whether to cache the metadata (default: true) */
+    cache?: boolean;
+    /** Custom fetch function */
+    fetch?: typeof fetch;
+}
+/**
+ * Discover OAuth metadata from a server URL
+ *
+ * Tries the following .well-known endpoints in order:
+ * 1. /.well-known/oauth-authorization-server
+ * 2. /.well-known/openid-configuration
+ *
+ * @example
+ * ```typescript
+ * const metadata = await discoverOAuthMetadata('https://auth.example.com');
+ * console.log('Auth endpoint:', metadata.authorization_endpoint);
+ * console.log('Supports PKCE:', metadata.code_challenge_methods_supported?.includes('S256'));
+ * ```
+ */
+declare function discoverOAuthMetadata(serverUrl: string, options?: DiscoveryOptions): Promise<OAuthMetadata>;
+/**
+ * Clear cached metadata for a server
+ */
+declare function clearMetadataCache(serverUrl?: string): void;
+/**
+ * Check if server supports a specific feature based on metadata
+ */
+declare function serverSupports(metadata: OAuthMetadata, feature: 'pkce' | 'refresh_token' | 'dynamic_registration' | 'revocation'): boolean;
+/**
+ * Validate that metadata has required fields
+ */
+declare function validateMetadata(metadata: OAuthMetadata): {
+    valid: boolean;
+    errors: string[];
+};
+
+/**
+ * Background Token Refresh Manager
+ *
+ * Automatically refreshes tokens before they expire, ensuring
+ * uninterrupted access without user-visible authentication prompts.
+ */
+
+/**
+ * Token refresh callback
+ */
+type RefreshCallback = (refreshToken: string) => Promise<OAuthTokens>;
+/**
+ * Refresh event types
+ */
+type RefreshEvent = {
+    type: 'refresh_started';
+    serverUrl: string;
+} | {
+    type: 'refresh_success';
+    serverUrl: string;
+    tokens: OAuthTokens;
+} | {
+    type: 'refresh_failed';
+    serverUrl: string;
+    error: Error;
+} | {
+    type: 'token_expired';
+    serverUrl: string;
+};
+/**
+ * Event listener callback
+ */
+type RefreshEventListener = (event: RefreshEvent) => void;
+/**
+ * Refresh manager options
+ */
+interface RefreshManagerOptions {
+    /** Token storage backend */
+    storage: TokenStorage;
+    /** Function to refresh tokens */
+    refreshFn: RefreshCallback;
+    /** Server URL this manager is for */
+    serverUrl: string;
+    /** Seconds before expiry to trigger refresh (default: 300 = 5 minutes) */
+    refreshBuffer?: number;
+    /** Check interval in ms (default: 60000 = 1 minute) */
+    checkInterval?: number;
+    /** Maximum retry attempts on failure (default: 3) */
+    maxRetries?: number;
+    /** Retry delay in ms (default: 5000) */
+    retryDelay?: number;
+}
+/**
+ * Background Token Refresh Manager
+ *
+ * Monitors token expiry and automatically refreshes before expiration.
+ *
+ * @example
+ * ```typescript
+ * const manager = new RefreshManager({
+ *   storage,
+ *   serverUrl: 'https://mcp.example.com',
+ *   refreshFn: async (refreshToken) => {
+ *     // Call token endpoint with refresh_token grant
+ *     return await exchangeRefreshToken(refreshToken);
+ *   },
+ * });
+ *
+ * manager.on((event) => {
+ *   if (event.type === 'refresh_failed') {
+ *     console.error('Token refresh failed:', event.error);
+ *   }
+ * });
+ *
+ * manager.start();
+ *
+ * // Later...
+ * manager.stop();
+ * ```
+ */
+declare class RefreshManager {
+    private storage;
+    private refreshFn;
+    private serverUrl;
+    private refreshBuffer;
+    private checkInterval;
+    private maxRetries;
+    private retryDelay;
+    private intervalId?;
+    private pendingRefresh?;
+    private retryCount;
+    private listeners;
+    private isRunning;
+    constructor(options: RefreshManagerOptions);
+    /**
+     * Start background refresh monitoring
+     */
+    start(): void;
+    /**
+     * Stop background refresh monitoring
+     */
+    stop(): void;
+    /**
+     * Register event listener
+     */
+    on(listener: RefreshEventListener): () => void;
+    /**
+     * Emit event to all listeners
+     */
+    private emit;
+    /**
+     * Check token and refresh if needed
+     */
+    private checkAndRefresh;
+    /**
+     * Perform token refresh with retry logic
+     */
+    private performRefresh;
+    /**
+     * Actually perform the refresh
+     */
+    private doRefresh;
+    /**
+     * Force an immediate refresh
+     */
+    forceRefresh(): Promise<OAuthTokens>;
+    /**
+     * Get current running state
+     */
+    get running(): boolean;
+}
+/**
+ * Create a simple refresh manager for an OAuth client
+ */
+declare function createRefreshManager(storage: TokenStorage, serverUrl: string, tokenEndpoint: string, clientId: string, clientSecret?: string): RefreshManager;
+
+export { type CallbackError, type CallbackResult, type CallbackServer, type CallbackServerOptions, type DiscoveryOptions, OAuthClient, type OAuthClientOptions, type OAuthMetadata, type PKCEPair, type RefreshCallback, type RefreshEvent, type RefreshEventListener, RefreshManager, type RefreshManagerOptions, clearMetadataCache, createRefreshManager, discoverOAuthMetadata, findAvailablePort, generateCodeChallenge, generateCodeVerifier, generatePKCE, isValidCodeVerifier, serverSupports, startCallbackServer, validateMetadata, verifyPKCE };