@leanmcp/auth 0.4.2 → 0.4.4-alpha.6.6dae082

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

package/dist/proxy/index.js

@@ -233,28 +233,28 @@ var OAuthProxy = class {
     }
   }
   /**
-   * Get configured providers
-   */
+  * Get configured providers
+  */
   getProviders() {
     return this.config.providers;
   }
   /**
-   * Get a provider by ID
-   */
+  * Get a provider by ID
+  */
   getProvider(id) {
     return this.providersMap.get(id);
   }
   /**
-   * Generate state parameter with signature
-   */
+  * Generate state parameter with signature
+  */
   generateState() {
     const nonce = (0, import_crypto2.randomUUID)();
     const signature = (0, import_crypto2.createHmac)("sha256", this.config.sessionSecret).update(nonce).digest("hex").substring(0, 8);
     return `${nonce}.${signature}`;
   }
   /**
-   * Verify state parameter signature
-   */
+  * Verify state parameter signature
+  */
   verifyState(state) {
     const [nonce, signature] = state.split(".");
     if (!nonce || !signature) return false;
@@ -262,13 +262,13 @@ var OAuthProxy = class {
     return signature === expectedSignature;
   }
   /**
-   * Handle authorization request
-   * 
-   * Redirects the user to the external provider's authorization page.
-   * 
-   * @param params - Request parameters
-   * @returns URL to redirect the user to
-   */
+  * 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) {
     const provider = this.providersMap.get(params.provider);
     if (!provider) {
@@ -311,13 +311,13 @@ var OAuthProxy = class {
     return authUrl.toString();
   }
   /**
-   * 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
-   */
+  * 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
+  */
   async handleCallback(params) {
     const { code, state, error, error_description } = params;
     if (error) {
@@ -372,8 +372,8 @@ var OAuthProxy = class {
     };
   }
   /**
-   * Exchange authorization code for tokens with external provider
-   */
+  * Exchange authorization code for tokens with external provider
+  */
   async exchangeCodeForTokens(provider, code, redirectUri, codeVerifier) {
     const tokenPayload = {
       grant_type: "authorization_code",
@@ -394,7 +394,7 @@ var OAuthProxy = class {
     }
     const headers = {
       "Content-Type": "application/x-www-form-urlencoded",
-      "Accept": "application/json"
+      Accept: "application/json"
     };
     if (provider.tokenEndpointAuthMethod === "client_secret_basic") {
       const credentials = Buffer.from(`${provider.clientId}:${provider.clientSecret}`).toString("base64");
@@ -412,8 +412,8 @@ var OAuthProxy = class {
     return response.json();
   }
   /**
-   * Fetch user info from external provider
-   */
+  * Fetch user info from external provider
+  */
   async fetchUserInfo(provider, accessToken) {
     if (!provider.userInfoEndpoint) {
       return {
@@ -422,8 +422,8 @@ var OAuthProxy = class {
     }
     const response = await fetch(provider.userInfoEndpoint, {
       headers: {
-        "Authorization": `Bearer ${accessToken}`,
-        "Accept": "application/json"
+        Authorization: `Bearer ${accessToken}`,
+        Accept: "application/json"
       }
     });
     if (!response.ok) {
@@ -443,9 +443,9 @@ var OAuthProxy = class {
     };
   }
   /**
-   * Generate an internal authorization code for the mapped tokens
-   * This code can be exchanged via the token endpoint
-   */
+  * Generate an internal authorization code for the mapped tokens
+  * This code can be exchanged via the token endpoint
+  */
   generateInternalCode(tokens) {
     const code = (0, import_crypto2.randomUUID)();
     const signature = (0, import_crypto2.createHmac)("sha256", this.config.sessionSecret).update(code).update(JSON.stringify(tokens)).digest("hex").substring(0, 16);
@@ -462,8 +462,8 @@ var OAuthProxy = class {
     return fullCode;
   }
   /**
-   * Handle token request (exchange internal code for tokens)
-   */
+  * Handle token request (exchange internal code for tokens)
+  */
   async handleToken(params) {
     const { grant_type, code, refresh_token } = params;
     if (grant_type === "authorization_code") {
@@ -486,8 +486,8 @@ var OAuthProxy = class {
     throw new Error(`Unsupported grant_type: ${grant_type}`);
   }
   /**
-   * Express/Connect middleware factory
-   */
+  * Express/Connect middleware factory
+  */
   createMiddleware() {
     return {
       authorize: /* @__PURE__ */ __name((req, res) => {

package/dist/proxy/index.mjs

@@ -178,28 +178,28 @@ var OAuthProxy = class {
     }
   }
   /**
-   * Get configured providers
-   */
+  * Get configured providers
+  */
   getProviders() {
     return this.config.providers;
   }
   /**
-   * Get a provider by ID
-   */
+  * Get a provider by ID
+  */
   getProvider(id) {
     return this.providersMap.get(id);
   }
   /**
-   * Generate state parameter with signature
-   */
+  * Generate state parameter with signature
+  */
   generateState() {
     const nonce = randomUUID();
     const signature = createHmac("sha256", this.config.sessionSecret).update(nonce).digest("hex").substring(0, 8);
     return `${nonce}.${signature}`;
   }
   /**
-   * Verify state parameter signature
-   */
+  * Verify state parameter signature
+  */
   verifyState(state) {
     const [nonce, signature] = state.split(".");
     if (!nonce || !signature) return false;
@@ -207,13 +207,13 @@ var OAuthProxy = class {
     return signature === expectedSignature;
   }
   /**
-   * Handle authorization request
-   * 
-   * Redirects the user to the external provider's authorization page.
-   * 
-   * @param params - Request parameters
-   * @returns URL to redirect the user to
-   */
+  * 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) {
     const provider = this.providersMap.get(params.provider);
     if (!provider) {
@@ -256,13 +256,13 @@ var OAuthProxy = class {
     return authUrl.toString();
   }
   /**
-   * 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
-   */
+  * 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
+  */
   async handleCallback(params) {
     const { code, state, error, error_description } = params;
     if (error) {
@@ -317,8 +317,8 @@ var OAuthProxy = class {
     };
   }
   /**
-   * Exchange authorization code for tokens with external provider
-   */
+  * Exchange authorization code for tokens with external provider
+  */
   async exchangeCodeForTokens(provider, code, redirectUri, codeVerifier) {
     const tokenPayload = {
       grant_type: "authorization_code",
@@ -339,7 +339,7 @@ var OAuthProxy = class {
     }
     const headers = {
       "Content-Type": "application/x-www-form-urlencoded",
-      "Accept": "application/json"
+      Accept: "application/json"
     };
     if (provider.tokenEndpointAuthMethod === "client_secret_basic") {
       const credentials = Buffer.from(`${provider.clientId}:${provider.clientSecret}`).toString("base64");
@@ -357,8 +357,8 @@ var OAuthProxy = class {
     return response.json();
   }
   /**
-   * Fetch user info from external provider
-   */
+  * Fetch user info from external provider
+  */
   async fetchUserInfo(provider, accessToken) {
     if (!provider.userInfoEndpoint) {
       return {
@@ -367,8 +367,8 @@ var OAuthProxy = class {
     }
     const response = await fetch(provider.userInfoEndpoint, {
       headers: {
-        "Authorization": `Bearer ${accessToken}`,
-        "Accept": "application/json"
+        Authorization: `Bearer ${accessToken}`,
+        Accept: "application/json"
       }
     });
     if (!response.ok) {
@@ -388,9 +388,9 @@ var OAuthProxy = class {
     };
   }
   /**
-   * Generate an internal authorization code for the mapped tokens
-   * This code can be exchanged via the token endpoint
-   */
+  * Generate an internal authorization code for the mapped tokens
+  * This code can be exchanged via the token endpoint
+  */
   generateInternalCode(tokens) {
     const code = randomUUID();
     const signature = createHmac("sha256", this.config.sessionSecret).update(code).update(JSON.stringify(tokens)).digest("hex").substring(0, 16);
@@ -407,8 +407,8 @@ var OAuthProxy = class {
     return fullCode;
   }
   /**
-   * Handle token request (exchange internal code for tokens)
-   */
+  * Handle token request (exchange internal code for tokens)
+  */
   async handleToken(params) {
     const { grant_type, code, refresh_token } = params;
     if (grant_type === "authorization_code") {
@@ -431,8 +431,8 @@ var OAuthProxy = class {
     throw new Error(`Unsupported grant_type: ${grant_type}`);
   }
   /**
-   * Express/Connect middleware factory
-   */
+  * Express/Connect middleware factory
+  */
   createMiddleware() {
     return {
       authorize: /* @__PURE__ */ __name((req, res) => {