@leanmcp/auth 0.4.2 → 0.4.3

package/dist/index.d.ts

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

package/dist/proxy/index.d.mts

@@ -0,0 +1,376 @@
+/**
+ * OAuth Proxy Types
+ *
+ * Types and interfaces for the OAuth proxy that enables
+ * MCP servers to authenticate via external identity providers.
+ */
+/**
+ * OAuth provider configuration
+ */
+interface OAuthProviderConfig {
+    /** Display name of the provider */
+    name: string;
+    /** Provider identifier (e.g., 'google', 'github') */
+    id: string;
+    /** OAuth authorization endpoint */
+    authorizationEndpoint: string;
+    /** OAuth token endpoint */
+    tokenEndpoint: string;
+    /** UserInfo endpoint (optional, for fetching user profile) */
+    userInfoEndpoint?: string;
+    /** OAuth client ID */
+    clientId: string;
+    /** OAuth client secret */
+    clientSecret: string;
+    /** Scopes to request */
+    scopes: string[];
+    /** Token endpoint authentication method */
+    tokenEndpointAuthMethod?: 'client_secret_basic' | 'client_secret_post';
+    /** Whether the provider supports PKCE */
+    supportsPkce?: boolean;
+    /** Custom parameters for authorization */
+    authorizationParams?: Record<string, string>;
+    /** Custom parameters for token exchange */
+    tokenParams?: Record<string, string>;
+}
+/**
+ * User info from external provider
+ */
+interface ExternalUserInfo {
+    /** User's unique ID from the provider */
+    sub: string;
+    /** User's email address */
+    email?: string;
+    /** Whether email is verified */
+    email_verified?: boolean;
+    /** User's display name */
+    name?: string;
+    /** User's profile picture URL */
+    picture?: string;
+    /** Provider-specific raw data */
+    raw?: Record<string, unknown>;
+}
+/**
+ * Token mapping function
+ * Maps external provider tokens to internal MCP tokens
+ */
+type TokenMapper = (externalTokens: ExternalTokens, userInfo: ExternalUserInfo, provider: OAuthProviderConfig) => Promise<MappedTokens>;
+/**
+ * External provider tokens
+ */
+interface ExternalTokens {
+    access_token: string;
+    token_type: string;
+    expires_in?: number;
+    refresh_token?: string;
+    id_token?: string;
+    scope?: string;
+}
+/**
+ * Internal MCP tokens after mapping
+ */
+interface MappedTokens {
+    /** Access token to use with MCP server */
+    access_token: string;
+    /** Token type (usually Bearer) */
+    token_type: string;
+    /** Token lifetime in seconds */
+    expires_in?: number;
+    /** Refresh token for obtaining new tokens */
+    refresh_token?: string;
+    /** MCP user ID */
+    user_id?: string;
+}
+/**
+ * OAuth proxy configuration
+ */
+interface OAuthProxyConfig {
+    /** Base URL where the proxy is hosted */
+    baseUrl: string;
+    /** Path for authorization endpoint (default: /authorize) */
+    authorizePath?: string;
+    /** Path for token endpoint (default: /token) */
+    tokenPath?: string;
+    /** Path for callback from external provider (default: /callback) */
+    callbackPath?: string;
+    /** Configured upstream providers */
+    providers: OAuthProviderConfig[];
+    /** Custom token mapper (optional) */
+    tokenMapper?: TokenMapper;
+    /** Session storage for OAuth state */
+    sessionSecret: string;
+    /** Whether to forward PKCE to upstream provider */
+    forwardPkce?: boolean;
+}
+/**
+ * Pending authorization request
+ */
+interface PendingAuthRequest {
+    /** Provider ID */
+    providerId: string;
+    /** Original client redirect URI */
+    clientRedirectUri: string;
+    /** Original client state */
+    clientState?: string;
+    /** PKCE code verifier (if forwarding PKCE) */
+    codeVerifier?: string;
+    /** Internal state for proxy */
+    proxyState: string;
+    /** Created timestamp */
+    createdAt: number;
+}
+
+/**
+ * Pre-configured OAuth Providers
+ *
+ * Ready-to-use configurations for popular identity providers.
+ * Just add your client credentials.
+ */
+
+/**
+ * Google OAuth provider configuration
+ *
+ * @example
+ * ```typescript
+ * const google = googleProvider({
+ *   clientId: process.env.GOOGLE_CLIENT_ID!,
+ *   clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+ *   scopes: ['email', 'profile'],
+ * });
+ * ```
+ */
+declare function googleProvider(options: {
+    clientId: string;
+    clientSecret: string;
+    scopes?: string[];
+}): OAuthProviderConfig;
+/**
+ * GitHub OAuth provider configuration
+ *
+ * @example
+ * ```typescript
+ * const github = githubProvider({
+ *   clientId: process.env.GITHUB_CLIENT_ID!,
+ *   clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+ * });
+ * ```
+ */
+declare function githubProvider(options: {
+    clientId: string;
+    clientSecret: string;
+    scopes?: string[];
+}): OAuthProviderConfig;
+/**
+ * Microsoft Azure AD / Entra ID provider configuration
+ *
+ * @example
+ * ```typescript
+ * const azure = azureProvider({
+ *   clientId: process.env.AZURE_CLIENT_ID!,
+ *   clientSecret: process.env.AZURE_CLIENT_SECRET!,
+ *   tenantId: process.env.AZURE_TENANT_ID ?? 'common',
+ * });
+ * ```
+ */
+declare function azureProvider(options: {
+    clientId: string;
+    clientSecret: string;
+    tenantId?: string;
+    scopes?: string[];
+}): OAuthProviderConfig;
+/**
+ * GitLab OAuth provider configuration
+ *
+ * @example
+ * ```typescript
+ * const gitlab = gitlabProvider({
+ *   clientId: process.env.GITLAB_CLIENT_ID!,
+ *   clientSecret: process.env.GITLAB_CLIENT_SECRET!,
+ *   // Optional: use self-hosted GitLab
+ *   baseUrl: 'https://gitlab.mycompany.com',
+ * });
+ * ```
+ */
+declare function gitlabProvider(options: {
+    clientId: string;
+    clientSecret: string;
+    baseUrl?: string;
+    scopes?: string[];
+}): OAuthProviderConfig;
+/**
+ * Slack OAuth provider configuration
+ *
+ * @example
+ * ```typescript
+ * const slack = slackProvider({
+ *   clientId: process.env.SLACK_CLIENT_ID!,
+ *   clientSecret: process.env.SLACK_CLIENT_SECRET!,
+ * });
+ * ```
+ */
+declare function slackProvider(options: {
+    clientId: string;
+    clientSecret: string;
+    scopes?: string[];
+}): OAuthProviderConfig;
+/**
+ * Discord OAuth provider configuration
+ *
+ * @example
+ * ```typescript
+ * const discord = discordProvider({
+ *   clientId: process.env.DISCORD_CLIENT_ID!,
+ *   clientSecret: process.env.DISCORD_CLIENT_SECRET!,
+ * });
+ * ```
+ */
+declare function discordProvider(options: {
+    clientId: string;
+    clientSecret: string;
+    scopes?: string[];
+}): OAuthProviderConfig;
+/**
+ * Create a custom OAuth provider
+ *
+ * @example
+ * ```typescript
+ * const custom = customProvider({
+ *   id: 'my-idp',
+ *   name: 'My Identity Provider',
+ *   authorizationEndpoint: 'https://idp.example.com/authorize',
+ *   tokenEndpoint: 'https://idp.example.com/token',
+ *   clientId: process.env.MY_IDP_CLIENT_ID!,
+ *   clientSecret: process.env.MY_IDP_CLIENT_SECRET!,
+ *   scopes: ['openid', 'profile'],
+ * });
+ * ```
+ */
+declare function customProvider(config: OAuthProviderConfig): OAuthProviderConfig;
+
+/**
+ * OAuth Proxy
+ *
+ * Enables MCP servers to authenticate users via external identity providers.
+ * Acts as an intermediary between MCP clients and providers like Google, GitHub, etc.
+ */
+
+/**
+ * OAuth Proxy class
+ *
+ * Handles OAuth flows with external identity providers and maps
+ * their tokens to internal MCP tokens.
+ *
+ * @example
+ * ```typescript
+ * import { OAuthProxy, googleProvider, githubProvider } from '@leanmcp/auth/proxy';
+ *
+ * const proxy = new OAuthProxy({
+ *   baseUrl: 'https://mcp.example.com/auth',
+ *   sessionSecret: process.env.SESSION_SECRET!,
+ *   providers: [
+ *     googleProvider({ clientId: '...', clientSecret: '...' }),
+ *     githubProvider({ clientId: '...', clientSecret: '...' }),
+ *   ],
+ * });
+ *
+ * // Express integration
+ * app.get('/auth/authorize', (req, res) => {
+ *   const url = proxy.handleAuthorize(req.query);
+ *   res.redirect(url);
+ * });
+ *
+ * app.get('/auth/callback', async (req, res) => {
+ *   const result = await proxy.handleCallback(req.query);
+ *   res.redirect(result.redirectUri);
+ * });
+ * ```
+ */
+declare class OAuthProxy {
+    private config;
+    private providersMap;
+    constructor(config: OAuthProxyConfig);
+    /**
+     * Get configured providers
+     */
+    getProviders(): OAuthProviderConfig[];
+    /**
+     * Get a provider by ID
+     */
+    getProvider(id: string): OAuthProviderConfig | undefined;
+    /**
+     * Generate state parameter with signature
+     */
+    private generateState;
+    /**
+     * Verify state parameter signature
+     */
+    private verifyState;
+    /**
+     * Handle authorization request
+     *
+     * Redirects the user to the external provider's authorization page.
+     *
+     * @param params - Request parameters
+     * @returns URL to redirect the user to
+     */
+    handleAuthorize(params: {
+        provider: string;
+        redirect_uri: string;
+        state?: string;
+        scope?: string;
+        code_challenge?: string;
+        code_challenge_method?: string;
+    }): string;
+    /**
+     * Handle callback from external provider
+     *
+     * Exchanges the authorization code for tokens and maps them.
+     *
+     * @param params - Callback query parameters
+     * @returns Result with redirect URI and tokens
+     */
+    handleCallback(params: {
+        code?: string;
+        state?: string;
+        error?: string;
+        error_description?: string;
+    }): Promise<{
+        redirectUri: string;
+        tokens?: MappedTokens;
+        error?: string;
+    }>;
+    /**
+     * Exchange authorization code for tokens with external provider
+     */
+    private exchangeCodeForTokens;
+    /**
+     * Fetch user info from external provider
+     */
+    private fetchUserInfo;
+    /**
+     * Generate an internal authorization code for the mapped tokens
+     * This code can be exchanged via the token endpoint
+     */
+    private generateInternalCode;
+    /**
+     * Handle token request (exchange internal code for tokens)
+     */
+    handleToken(params: {
+        grant_type: string;
+        code?: string;
+        redirect_uri?: string;
+        client_id?: string;
+        client_secret?: string;
+        refresh_token?: string;
+    }): Promise<MappedTokens>;
+    /**
+     * Express/Connect middleware factory
+     */
+    createMiddleware(): {
+        authorize: (req: any, res: any) => void;
+        callback: (req: any, res: any) => Promise<void>;
+        token: (req: any, res: any) => Promise<void>;
+    };
+}
+
+export { type ExternalTokens, type ExternalUserInfo, type MappedTokens, type OAuthProviderConfig, OAuthProxy, type OAuthProxyConfig, type PendingAuthRequest, type TokenMapper, azureProvider, customProvider, discordProvider, githubProvider, gitlabProvider, googleProvider, slackProvider };