@mcp-z/oauth-google 1.0.0

package/dist/esm/providers/loopback-oauth.js

@@ -0,0 +1,639 @@
+/**
+ * Loopback OAuth Implementation (RFC 8252)
+ *
+ * Implements OAuth 2.0 Authorization Code Flow with PKCE using loopback interface redirection.
+ * Uses ephemeral local server with OS-assigned port (RFC 8252 Section 8.3).
+ */ import { addAccount, generatePKCE, getActiveAccount, getErrorTemplate, getSuccessTemplate, getToken, listAccountIds, setAccountInfo, setActiveAccount, setToken } from '@mcp-z/oauth';
+import { OAuth2Client } from 'google-auth-library';
+import * as http from 'http';
+import open from 'open';
+import { AuthRequiredError } from '../types.js';
+/**
+ * Loopback OAuth Client (RFC 8252 Section 7.3)
+ *
+ * Implements OAuth 2.0 Authorization Code Flow with PKCE for native applications
+ * using loopback interface redirection. Manages ephemeral OAuth flows and token persistence
+ * with Keyv for key-based token storage using compound keys.
+ *
+ * Token key format: {accountId}:{service}:token (e.g., "user@example.com:gmail:token")
+ */ export class LoopbackOAuthProvider {
+    /**
+   * Get access token from Keyv using compound key
+   *
+   * @param accountId - Account identifier (email address). Required for loopback OAuth.
+   * @returns Access token for API requests
+   */ async getAccessToken(accountId) {
+        const { logger, service, tokenStore } = this.config;
+        // Use active account if no accountId specified
+        const effectiveAccountId = accountId !== null && accountId !== void 0 ? accountId : await getActiveAccount(tokenStore, {
+            service
+        });
+        // If we have an accountId, try to use existing token
+        if (effectiveAccountId) {
+            logger.debug('Getting access token', {
+                service,
+                accountId: effectiveAccountId
+            });
+            // Check Keyv for token using new key format
+            const storedToken = await getToken(tokenStore, {
+                accountId: effectiveAccountId,
+                service
+            });
+            if (storedToken && this.isTokenValid(storedToken)) {
+                logger.debug('Using stored access token', {
+                    accountId: effectiveAccountId
+                });
+                return storedToken.accessToken;
+            }
+            // If stored token expired but has refresh token, try refresh
+            if (storedToken === null || storedToken === void 0 ? void 0 : storedToken.refreshToken) {
+                try {
+                    logger.info('Refreshing expired access token', {
+                        accountId: effectiveAccountId
+                    });
+                    const refreshedToken = await this.refreshAccessToken(storedToken.refreshToken);
+                    await setToken(tokenStore, {
+                        accountId: effectiveAccountId,
+                        service
+                    }, refreshedToken);
+                    return refreshedToken.accessToken;
+                } catch (error) {
+                    logger.info('Token refresh failed, starting new OAuth flow', {
+                        accountId: effectiveAccountId,
+                        error: error instanceof Error ? error.message : String(error)
+                    });
+                // Fall through to new OAuth flow
+                }
+            }
+        }
+        // No valid token or no account - check if we can start OAuth flow
+        const { headless } = this.config;
+        if (headless) {
+            // In headless mode (production), cannot start OAuth flow
+            // Throw AuthRequiredError with auth_url descriptor for MCP tool response
+            const { clientId, scope } = this.config;
+            // Incremental OAuth detection: Check if other accounts exist
+            const existingAccounts = await this.getExistingAccounts();
+            const hasOtherAccounts = effectiveAccountId ? existingAccounts.length > 0 && !existingAccounts.includes(effectiveAccountId) : existingAccounts.length > 0;
+            // Build informational OAuth URL for headless mode
+            // Note: No redirect_uri included - user must use account-add tool which starts proper ephemeral server
+            const authUrl = new URL('https://accounts.google.com/o/oauth2/v2/auth');
+            authUrl.searchParams.set('client_id', clientId);
+            authUrl.searchParams.set('response_type', 'code');
+            authUrl.searchParams.set('scope', scope);
+            authUrl.searchParams.set('access_type', 'offline');
+            authUrl.searchParams.set('prompt', 'consent');
+            let hint;
+            if (hasOtherAccounts) {
+                hint = `Existing ${service} accounts found. Use account-list to view, account-switch to change account, or account-add to add new account`;
+            } else if (effectiveAccountId) {
+                hint = `Use account-add to authenticate ${effectiveAccountId}`;
+            } else {
+                hint = 'Use account-add to authenticate interactively';
+            }
+            const baseDescriptor = {
+                kind: 'auth_url',
+                provider: 'google',
+                url: authUrl.toString(),
+                hint
+            };
+            const descriptor = effectiveAccountId ? {
+                ...baseDescriptor,
+                accountId: effectiveAccountId
+            } : baseDescriptor;
+            throw new AuthRequiredError(descriptor);
+        }
+        // Interactive mode - start ephemeral OAuth flow
+        logger.info('Starting ephemeral OAuth flow', {
+            service,
+            headless
+        });
+        const { token, email } = await this.performEphemeralOAuthFlow();
+        // Store token with email as accountId
+        await setToken(tokenStore, {
+            accountId: email,
+            service
+        }, token);
+        // Register account in account management system
+        await addAccount(tokenStore, {
+            service,
+            accountId: email
+        });
+        // Set as active account so subsequent getAccessToken() calls find it
+        await setActiveAccount(tokenStore, {
+            service,
+            accountId: email
+        });
+        // Store account metadata (email, added timestamp)
+        await setAccountInfo(tokenStore, {
+            service,
+            accountId: email
+        }, {
+            email,
+            addedAt: new Date().toISOString()
+        });
+        logger.info('OAuth flow completed', {
+            service,
+            accountId: email
+        });
+        return token.accessToken;
+    }
+    /**
+   * Convert to googleapis-compatible OAuth2Client
+   *
+   * @param accountId - Account identifier for multi-account support (e.g., 'user@example.com')
+   * @returns OAuth2Client configured for the specified account
+   */ toAuth(accountId) {
+        const { clientId, clientSecret } = this.config;
+        const client = new OAuth2Client({
+            clientId,
+            ...clientSecret && {
+                clientSecret
+            }
+        });
+        // @ts-expect-error - Override protected method to inject fresh token
+        client.getRequestMetadataAsync = async (_url)=>{
+            // Get token from FileAuthAdapter (not from client to avoid recursion)
+            const token = await this.getAccessToken(accountId);
+            // Update client credentials for googleapis compatibility
+            client.credentials = {
+                access_token: token,
+                token_type: 'Bearer'
+            };
+            // Return headers as Map (required by authclient.js addUserProjectAndAuthHeaders)
+            const headers = new Map();
+            headers.set('authorization', `Bearer ${token}`);
+            return {
+                headers
+            };
+        };
+        return client;
+    }
+    /**
+   * Authenticate new account with OAuth flow
+   * Triggers account selection, stores token, registers account
+   *
+   * @returns Email address of newly authenticated account
+   * @throws Error in headless mode (cannot open browser for OAuth)
+   */ async authenticateNewAccount() {
+        const { logger, headless, service, tokenStore } = this.config;
+        if (headless) {
+            throw new Error('Cannot authenticate new account in headless mode - interactive OAuth required');
+        }
+        logger.info('Starting new account authentication', {
+            service
+        });
+        // Trigger OAuth with account selection
+        const { token, email } = await this.performEphemeralOAuthFlow();
+        // Store token
+        await setToken(tokenStore, {
+            accountId: email,
+            service
+        }, token);
+        // Register account
+        await addAccount(tokenStore, {
+            service,
+            accountId: email
+        });
+        // Set as active account
+        await setActiveAccount(tokenStore, {
+            service,
+            accountId: email
+        });
+        // Store account metadata
+        await setAccountInfo(tokenStore, {
+            service,
+            accountId: email
+        }, {
+            email,
+            addedAt: new Date().toISOString()
+        });
+        logger.info('New account authenticated', {
+            service,
+            email
+        });
+        return email;
+    }
+    /**
+   * Get user email from Google's userinfo endpoint (pure query)
+   * Used to query email for existing authenticated account
+   *
+   * @param accountId - Account identifier to get email for
+   * @returns User's email address
+   */ async getUserEmail(accountId) {
+        // Get token for existing account
+        const token = await this.getAccessToken(accountId);
+        // Fetch email from Google userinfo
+        const response = await fetch('https://www.googleapis.com/oauth2/v2/userinfo', {
+            headers: {
+                Authorization: `Bearer ${token}`
+            }
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to get user info: ${response.status} ${await response.text()}`);
+        }
+        const userInfo = await response.json();
+        return userInfo.email;
+    }
+    /**
+   * Check for existing accounts in token storage (incremental OAuth detection)
+   *
+   * Uses key-utils helper for forward compatibility with key format changes.
+   *
+   * @returns Array of account IDs that have tokens for this service
+   */ async getExistingAccounts() {
+        const { service, tokenStore } = this.config;
+        return listAccountIds(tokenStore, service);
+    }
+    isTokenValid(token) {
+        if (!token.expiresAt) return true; // No expiry = assume valid
+        return Date.now() < token.expiresAt - 60000; // 1 minute buffer
+    }
+    /**
+   * Fetch user email from Google OAuth2 userinfo endpoint
+   * Called during OAuth flow to get email for accountId
+   *
+   * @param accessToken - Fresh access token from OAuth exchange
+   * @returns User's email address
+   */ async fetchUserEmailFromToken(accessToken) {
+        const { logger } = this.config;
+        const response = await fetch('https://www.googleapis.com/oauth2/v2/userinfo', {
+            headers: {
+                Authorization: `Bearer ${accessToken}`
+            }
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Failed to fetch user email: HTTP ${response.status} - ${errorText}`);
+        }
+        const userInfo = await response.json();
+        const email = userInfo.email;
+        logger.debug('Fetched user email from Google userinfo API', {
+            email
+        });
+        return email;
+    }
+    async performEphemeralOAuthFlow() {
+        const { clientId, scope, headless, logger, redirectUri: configRedirectUri } = this.config;
+        // Parse redirectUri if provided to extract host, protocol, port, and path
+        let targetHost = 'localhost'; // Default: localhost (match registered redirect URI)
+        let targetPort = 0; // Default: OS-assigned ephemeral port
+        let targetProtocol = 'http:'; // Default: http
+        let callbackPath = '/callback'; // Default callback path
+        let useConfiguredUri = false;
+        if (configRedirectUri) {
+            try {
+                const parsed = new URL(configRedirectUri);
+                // Use configured redirect URI as-is for production deployments
+                targetHost = parsed.hostname;
+                targetProtocol = parsed.protocol;
+                // Extract port from URL (use default ports if not specified)
+                if (parsed.port) {
+                    targetPort = Number.parseInt(parsed.port, 10);
+                } else {
+                    targetPort = parsed.protocol === 'https:' ? 443 : 80;
+                }
+                // Extract path (default to /callback if URL has no path or just '/')
+                if (parsed.pathname && parsed.pathname !== '/') {
+                    callbackPath = parsed.pathname;
+                }
+                useConfiguredUri = true;
+                logger.debug('Using configured redirect URI', {
+                    host: targetHost,
+                    protocol: targetProtocol,
+                    port: targetPort,
+                    path: callbackPath,
+                    redirectUri: configRedirectUri
+                });
+            } catch (error) {
+                logger.warn('Failed to parse redirectUri, using ephemeral defaults', {
+                    redirectUri: configRedirectUri,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            // Continue with defaults (127.0.0.1, port 0, http, /callback)
+            }
+        }
+        return new Promise((resolve, reject)=>{
+            // Generate PKCE challenge
+            const { verifier: codeVerifier, challenge: codeChallenge } = generatePKCE();
+            let server = null;
+            let serverPort;
+            let finalRedirectUri; // Will be set in server.listen callback
+            // Create ephemeral server with OS-assigned port (RFC 8252)
+            server = http.createServer(async (req, res)=>{
+                if (!req.url) {
+                    res.writeHead(400, {
+                        'Content-Type': 'text/html'
+                    });
+                    res.end(getErrorTemplate('Invalid request'));
+                    server === null || server === void 0 ? void 0 : server.close();
+                    reject(new Error('Invalid request: missing URL'));
+                    return;
+                }
+                const url = new URL(req.url, `http://127.0.0.1:${serverPort}`);
+                if (url.pathname === callbackPath) {
+                    const code = url.searchParams.get('code');
+                    const error = url.searchParams.get('error');
+                    if (error) {
+                        res.writeHead(400, {
+                            'Content-Type': 'text/html'
+                        });
+                        res.end(getErrorTemplate(error));
+                        server === null || server === void 0 ? void 0 : server.close();
+                        reject(new Error(`OAuth error: ${error}`));
+                        return;
+                    }
+                    if (!code) {
+                        res.writeHead(400, {
+                            'Content-Type': 'text/html'
+                        });
+                        res.end(getErrorTemplate('No authorization code received'));
+                        server === null || server === void 0 ? void 0 : server.close();
+                        reject(new Error('No authorization code received'));
+                        return;
+                    }
+                    try {
+                        // Exchange code for token (must use same redirect_uri as in authorization request)
+                        const tokenResponse = await this.exchangeCodeForToken(code, codeVerifier, finalRedirectUri);
+                        // Build cached token
+                        const cachedToken = {
+                            accessToken: tokenResponse.access_token,
+                            ...tokenResponse.refresh_token !== undefined && {
+                                refreshToken: tokenResponse.refresh_token
+                            },
+                            ...tokenResponse.expires_in !== undefined && {
+                                expiresAt: Date.now() + tokenResponse.expires_in * 1000
+                            },
+                            ...tokenResponse.scope !== undefined && {
+                                scope: tokenResponse.scope
+                            }
+                        };
+                        // Fetch user email immediately using the new access token
+                        const email = await this.fetchUserEmailFromToken(tokenResponse.access_token);
+                        res.writeHead(200, {
+                            'Content-Type': 'text/html'
+                        });
+                        res.end(getSuccessTemplate());
+                        server === null || server === void 0 ? void 0 : server.close();
+                        resolve({
+                            token: cachedToken,
+                            email
+                        });
+                    } catch (exchangeError) {
+                        logger.error('Token exchange failed', {
+                            error: exchangeError instanceof Error ? exchangeError.message : String(exchangeError)
+                        });
+                        res.writeHead(500, {
+                            'Content-Type': 'text/html'
+                        });
+                        res.end(getErrorTemplate('Token exchange failed'));
+                        server === null || server === void 0 ? void 0 : server.close();
+                        reject(exchangeError);
+                    }
+                } else {
+                    res.writeHead(404, {
+                        'Content-Type': 'text/plain'
+                    });
+                    res.end('Not Found');
+                }
+            });
+            // Listen on targetPort (0 for OS assignment, or custom port from redirectUri)
+            server.listen(targetPort, targetHost, ()=>{
+                const address = server === null || server === void 0 ? void 0 : server.address();
+                if (!address || typeof address === 'string') {
+                    server === null || server === void 0 ? void 0 : server.close();
+                    reject(new Error('Failed to start ephemeral server'));
+                    return;
+                }
+                serverPort = address.port;
+                // Construct final redirect URI
+                if (useConfiguredUri && configRedirectUri) {
+                    // Use configured redirect URI as-is for production
+                    finalRedirectUri = configRedirectUri;
+                } else {
+                    // Construct ephemeral redirect URI with actual server port
+                    finalRedirectUri = `${targetProtocol}//${targetHost}:${serverPort}${callbackPath}`;
+                }
+                // Build auth URL
+                const authUrl = new URL('https://accounts.google.com/o/oauth2/v2/auth');
+                authUrl.searchParams.set('client_id', clientId);
+                authUrl.searchParams.set('redirect_uri', finalRedirectUri);
+                authUrl.searchParams.set('response_type', 'code');
+                authUrl.searchParams.set('scope', scope);
+                authUrl.searchParams.set('access_type', 'offline');
+                authUrl.searchParams.set('prompt', 'consent');
+                authUrl.searchParams.set('code_challenge', codeChallenge);
+                authUrl.searchParams.set('code_challenge_method', 'S256');
+                logger.info('Ephemeral OAuth server started', {
+                    port: serverPort,
+                    headless
+                });
+                if (headless) {
+                    // Headless mode: Print auth URL to stderr (stdout is MCP protocol)
+                    console.error('\n🔐 OAuth Authorization Required');
+                    console.error('📋 Please visit this URL in your browser:\n');
+                    console.error(`   ${authUrl.toString()}\n`);
+                    console.error('⏳ Waiting for authorization...\n');
+                } else {
+                    // Interactive mode: Open browser automatically
+                    logger.info('Opening browser for OAuth authorization');
+                    open(authUrl.toString()).catch((error)=>{
+                        logger.info('Failed to open browser automatically', {
+                            error: error.message
+                        });
+                        console.error('\n🔐 OAuth Authorization Required');
+                        console.error(`   ${authUrl.toString()}\n`);
+                    });
+                }
+            });
+            // Timeout after 5 minutes
+            setTimeout(()=>{
+                if (server) {
+                    server.close();
+                    reject(new Error('OAuth flow timed out after 5 minutes'));
+                }
+            }, 5 * 60 * 1000);
+        });
+    }
+    async exchangeCodeForToken(code, codeVerifier, redirectUri) {
+        const { clientId, clientSecret } = this.config;
+        const tokenUrl = 'https://oauth2.googleapis.com/token';
+        const params = {
+            code,
+            client_id: clientId,
+            redirect_uri: redirectUri,
+            grant_type: 'authorization_code',
+            code_verifier: codeVerifier
+        };
+        if (clientSecret) {
+            params.client_secret = clientSecret;
+        }
+        const body = new URLSearchParams(params);
+        const response = await fetch(tokenUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded'
+            },
+            body: body.toString()
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Token exchange failed: ${response.status} ${errorText}`);
+        }
+        return await response.json();
+    }
+    async refreshAccessToken(refreshToken) {
+        const { clientId, clientSecret } = this.config;
+        const tokenUrl = 'https://oauth2.googleapis.com/token';
+        const params = {
+            refresh_token: refreshToken,
+            client_id: clientId,
+            grant_type: 'refresh_token'
+        };
+        if (clientSecret) {
+            params.client_secret = clientSecret;
+        }
+        const body = new URLSearchParams(params);
+        const response = await fetch(tokenUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded'
+            },
+            body: body.toString()
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Token refresh failed: ${response.status} ${errorText}`);
+        }
+        const tokenResponse = await response.json();
+        return {
+            accessToken: tokenResponse.access_token,
+            refreshToken: refreshToken,
+            ...tokenResponse.expires_in !== undefined && {
+                expiresAt: Date.now() + tokenResponse.expires_in * 1000
+            },
+            ...tokenResponse.scope !== undefined && {
+                scope: tokenResponse.scope
+            }
+        };
+    }
+    /**
+   * Create authentication middleware for MCP tools, resources, and prompts
+   *
+   * Returns position-aware middleware wrappers that enrich handlers with authentication context.
+   * The middleware handles token retrieval, refresh, and AuthRequiredError automatically.
+   *
+   * Single-user middleware for desktop/CLI apps where ONE user runs the entire process:
+   * - Desktop applications (Claude Desktop)
+   * - CLI tools (Gmail CLI)
+   * - Personal automation scripts
+   *
+   * All requests use token lookups based on the active account or account override.
+   *
+   * @returns Object with withToolAuth, withResourceAuth, withPromptAuth methods
+   *
+   * @example
+   * ```typescript
+   * const loopback = new LoopbackOAuthProvider({ service: 'gmail', ... });
+   * const authMiddleware = loopback.authMiddleware();
+   * const tools = toolFactories.map(f => f()).map(authMiddleware.withToolAuth);
+   * const resources = resourceFactories.map(f => f()).map(authMiddleware.withResourceAuth);
+   * const prompts = promptFactories.map(f => f()).map(authMiddleware.withPromptAuth);
+   * ```
+   */ authMiddleware() {
+        const { service, tokenStore, logger } = this.config;
+        // Shared wrapper logic - extracts extra parameter from specified position
+        // Generic T captures the actual module type; handler is cast from unknown to callable
+        const wrapAtPosition = (module, extraPosition)=>{
+            const operation = module.name;
+            const originalHandler = module.handler;
+            const wrappedHandler = async (...allArgs)=>{
+                // Extract extra from the correct position
+                const extra = allArgs[extraPosition];
+                try {
+                    // Check for backchannel override via _meta.accountId
+                    let accountId;
+                    try {
+                        var _ref;
+                        var _extra__meta;
+                        accountId = (_ref = (_extra__meta = extra._meta) === null || _extra__meta === void 0 ? void 0 : _extra__meta.accountId) !== null && _ref !== void 0 ? _ref : await getActiveAccount(tokenStore, {
+                            service
+                        });
+                    } catch (error) {
+                        if (error instanceof Error && (error.code === 'REQUIRES_AUTHENTICATION' || error.name === 'AccountManagerError')) {
+                            accountId = undefined;
+                        } else {
+                            throw error;
+                        }
+                    }
+                    // Eagerly validate token exists or trigger OAuth flow
+                    await this.getAccessToken(accountId);
+                    // After OAuth flow completes, get the actual accountId (email) that was set
+                    const effectiveAccountId = accountId !== null && accountId !== void 0 ? accountId : await getActiveAccount(tokenStore, {
+                        service
+                    });
+                    if (!effectiveAccountId) {
+                        throw new Error(`No account found after OAuth flow for service ${service}`);
+                    }
+                    const auth = this.toAuth(effectiveAccountId);
+                    // Inject authContext and logger into extra
+                    extra.authContext = {
+                        auth,
+                        accountId: effectiveAccountId
+                    };
+                    extra.logger = logger;
+                    // Call original handler with all args
+                    return await originalHandler(...allArgs);
+                } catch (error) {
+                    if (error instanceof AuthRequiredError) {
+                        logger.info('Authentication required', {
+                            service,
+                            tool: operation,
+                            descriptor: error.descriptor
+                        });
+                        // Return auth_required response wrapped in { result } to match tool outputSchema pattern
+                        // Tools define outputSchema: z.object({ result: discriminatedUnion(...) }) where auth_required is a branch
+                        const authRequiredResponse = {
+                            type: 'auth_required',
+                            provider: service,
+                            message: `Authentication required for ${operation}. Please authenticate with ${service}.`,
+                            url: error.descriptor.kind === 'auth_url' ? error.descriptor.url : undefined
+                        };
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        result: authRequiredResponse
+                                    })
+                                }
+                            ],
+                            structuredContent: {
+                                result: authRequiredResponse
+                            }
+                        };
+                    }
+                    throw error;
+                }
+            };
+            return {
+                ...module,
+                handler: wrappedHandler
+            };
+        };
+        return {
+            withToolAuth: (module)=>wrapAtPosition(module, 1),
+            withResourceAuth: (module)=>wrapAtPosition(module, 2),
+            withPromptAuth: (module)=>wrapAtPosition(module, 0)
+        };
+    }
+    constructor(config){
+        this.config = config;
+    }
+}
+/**
+ * Create a loopback OAuth client for Google services
+ * Works for both stdio and HTTP transports
+ */ export function createGoogleFileAuth(config) {
+    return new LoopbackOAuthProvider(config);
+}