@leanmcp/auth 0.4.2 → 0.4.3

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 };

package/dist/index.d.mts

@@ -0,0 +1,181 @@
+/**
+ * Shared types for @leanmcp/auth
+ */
+/**
+ * Options for the Authenticated decorator
+ */
+interface AuthenticatedOptions {
+    /**
+     * Whether to fetch and attach user information to authUser variable
+     * @default true
+     */
+    getUser?: boolean;
+    /**
+     * Project ID for fetching user environment variables.
+     * Required when @RequireEnv is used on the method or class.
+     * Used to scope user secrets to a specific project.
+     */
+    projectId?: string;
+}
+
+/**
+ * Global authUser type declaration
+ * This makes authUser available in @Authenticated methods without explicit declaration
+ */
+declare global {
+    /**
+     * Authenticated user object automatically available in @Authenticated methods
+     *
+     * Implemented as a getter that reads from AsyncLocalStorage for concurrency safety.
+     * Each request has its own isolated context - 100% safe for concurrent requests.
+     */
+    const authUser: any;
+}
+/**
+ * Get the current authenticated user from the async context
+ * This is safe for concurrent requests as each request has its own context
+ */
+declare function getAuthUser(): any;
+/**
+ * Authentication error class for better error handling
+ */
+declare class AuthenticationError extends Error {
+    code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Decorator to protect MCP tools, prompts, resources, or entire services with authentication
+ *
+ * CONCURRENCY SAFE: Uses AsyncLocalStorage to ensure each request has its own isolated
+ * authUser context, preventing race conditions in high-concurrency scenarios.
+ *
+ * Usage:
+ *
+ * 1. Protect individual methods with automatic user info:
+ * ```typescript
+ * @Tool({ description: 'Analyze sentiment' })
+ * @Authenticated(authProvider, { getUser: true })
+ * async analyzeSentiment(args: AnalyzeSentimentInput): Promise<AnalyzeSentimentOutput> {
+ *   // authUser is automatically available in method scope
+ *   console.log('User:', authUser);
+ *   console.log('User ID:', authUser.sub);
+ * }
+ * ```
+ *
+ * 2. Protect without fetching user info:
+ * ```typescript
+ * @Tool({ description: 'Public tool' })
+ * @Authenticated(authProvider, { getUser: false })
+ * async publicTool(args: PublicToolInput): Promise<PublicToolOutput> {
+ *   // Only verifies token, doesn't fetch user info
+ * }
+ * ```
+ *
+ * 3. Protect entire service (all tools/prompts/resources):
+ * ```typescript
+ * @Authenticated(authProvider)
+ * export class SentimentAnalysisService {
+ *   @Tool({ description: 'Analyze sentiment' })
+ *   async analyzeSentiment(args: AnalyzeSentimentInput) {
+ *     // All methods in this service require authentication
+ *     // authUser is automatically available in all methods
+ *     console.log('User:', authUser);
+ *   }
+ * }
+ * ```
+ *
+ * The decorator expects authentication token in the MCP request _meta field:
+ * ```json
+ * {
+ *   "method": "tools/call",
+ *   "params": {
+ *     "name": "toolName",
+ *     "arguments": { ...businessData },
+ *     "_meta": {
+ *       "authorization": {
+ *         "type": "bearer",
+ *         "token": "your-jwt-token"
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @param authProvider - Instance of AuthProviderBase to use for token verification
+ * @param options - Optional configuration for authentication behavior
+ */
+declare function Authenticated(authProvider: AuthProviderBase, options?: AuthenticatedOptions): (target: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor) => any;
+/**
+ * Check if a method or class requires authentication
+ */
+declare function isAuthenticationRequired(target: any): boolean;
+/**
+ * Get the auth provider for a method or class
+ */
+declare function getAuthProvider(target: any): AuthProviderBase | undefined;
+
+/**
+ * @leanmcp/auth - Authentication Module
+ *
+ * This module provides a base class for implementing authentication providers for MCP tools.
+ * Extend AuthProviderBase to integrate with different auth providers (Clerk, Stripe, Firebase, etc.)
+ */
+/**
+ * Base class for authentication providers
+ * Extend this class to implement integrations with different auth providers
+ */
+declare abstract class AuthProviderBase {
+    /**
+     * Initialize the auth provider with configuration
+     */
+    abstract init(config?: any): Promise<void>;
+    /**
+     * Refresh an authentication token
+     */
+    abstract refreshToken(refreshToken: string, username?: string): Promise<any>;
+    /**
+     * Verify if a token is valid
+     */
+    abstract verifyToken(token: string): Promise<boolean>;
+    /**
+     * Get user information from a token
+     */
+    abstract getUser(token: string): Promise<any>;
+}
+/**
+ * Unified AuthProvider class that dynamically selects the appropriate auth provider
+ * based on the provider parameter
+ */
+declare class AuthProvider extends AuthProviderBase {
+    private providerInstance;
+    private providerType;
+    private config;
+    constructor(provider: string, config?: any);
+    /**
+     * Initialize the selected auth provider
+     */
+    init(config?: any): Promise<void>;
+    /**
+     * Refresh an authentication token
+     */
+    refreshToken(refreshToken: string, username?: string): Promise<any>;
+    /**
+     * Verify if a token is valid
+     */
+    verifyToken(token: string): Promise<boolean>;
+    /**
+     * Get user information from a token
+     */
+    getUser(token: string): Promise<any>;
+    /**
+     * Get user secrets for a project (LeanMCP provider only)
+     * Other providers will return empty object
+     */
+    getUserSecrets(token: string, projectId: string): Promise<Record<string, string>>;
+    /**
+     * Get the provider type
+     */
+    getProviderType(): string;
+}
+
+export { AuthProvider, AuthProviderBase, Authenticated, type AuthenticatedOptions, AuthenticationError, getAuthProvider, getAuthUser, isAuthenticationRequired };