@leanmcp/auth 0.3.2 → 0.4.0

package/dist/proxy/index.d.ts

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