@mcp-z/oauth-google 1.0.0 → 1.0.2

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

@@ -3,11 +3,24 @@
  *
  * 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';
+ *
+ * CHANGE (2026-01-03):
+ * - Non-headless mode now opens the auth URL AND blocks (polls) until tokens are available,
+ *   for BOTH redirectUri (persistent) and ephemeral (loopback) modes.
+ * - Ephemeral flow no longer calls `open()` itself. Instead it:
+ *   1) starts the loopback callback server
+ *   2) throws AuthRequiredError(auth_url)
+ * - Middleware catches AuthRequiredError(auth_url):
+ *   - if not headless: open(url) once + poll pending state until callback completes (or timeout)
+ *   - then retries token acquisition and injects authContext in the SAME tool call.
+ */ import { addAccount, generatePKCE, getActiveAccount, getErrorTemplate, getSuccessTemplate, getToken, setAccountInfo, setActiveAccount, setToken } from '@mcp-z/oauth';
+import { randomUUID } from 'crypto';
 import { OAuth2Client } from 'google-auth-library';
 import * as http from 'http';
 import open from 'open';
 import { AuthRequiredError } from '../types.js';
+const OAUTH_TIMEOUT_MS = 5 * 60 * 1000;
+const OAUTH_POLL_MS = 500;
 /**
  * Loopback OAuth Client (RFC 8252 Section 7.3)
  *
@@ -66,77 +79,43 @@ import { AuthRequiredError } from '../types.js';
                 }
             }
         }
-        // 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 = {
+        // No valid token or no account - need OAuth authentication
+        const { clientId, scope, redirectUri } = this.config;
+        if (redirectUri) {
+            // Persistent callback mode (cloud deployment with configured redirect_uri)
+            const { verifier: codeVerifier, challenge: codeChallenge } = generatePKCE();
+            const stateId = randomUUID();
+            // Store PKCE verifier for callback (5 minute TTL)
+            await this.createPendingAuth({
+                state: stateId,
+                codeVerifier
+            });
+            // Build auth URL with configured redirect_uri
+            const authUrl = this.buildAuthUrl({
+                redirectUri,
+                codeChallenge,
+                state: stateId
+            });
+            logger.info('OAuth required - persistent callback mode', {
+                service,
+                redirectUri,
+                clientId,
+                scope
+            });
+            throw new AuthRequiredError({
                 kind: 'auth_url',
-                provider: 'google',
-                url: authUrl.toString(),
-                hint
-            };
-            const descriptor = effectiveAccountId ? {
-                ...baseDescriptor,
-                accountId: effectiveAccountId
-            } : baseDescriptor;
-            throw new AuthRequiredError(descriptor);
+                provider: service,
+                url: authUrl
+            });
         }
-        // Interactive mode - start ephemeral OAuth flow
+        // Ephemeral callback mode (local development)
+        // IMPORTANT: do NOT open here anymore; we throw auth_url and the middleware will open+poll.
         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()
+            headless: this.config.headless
         });
-        logger.info('OAuth flow completed', {
-            service,
-            accountId: email
-        });
-        return token.accessToken;
+        const descriptor = await this.startEphemeralOAuthFlow();
+        throw new AuthRequiredError(descriptor);
     }
     /**
    * Convert to googleapis-compatible OAuth2Client
@@ -170,51 +149,6 @@ import { AuthRequiredError } from '../types.js';
         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
    *
@@ -235,16 +169,6 @@ import { AuthRequiredError } from '../types.js';
         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
@@ -273,132 +197,345 @@ import { AuthRequiredError } from '../types.js';
         });
         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
+    // ---------------------------------------------------------------------------
+    // Shared OAuth helpers
+    // ---------------------------------------------------------------------------
+    /**
+   * Build OAuth authorization URL with the "most parameters" baseline.
+   * This is shared by BOTH persistent (redirectUri) and ephemeral (loopback) modes.
+   */ buildAuthUrl(args) {
+        const { clientId, scope } = this.config;
+        const authUrl = new URL('https://accounts.google.com/o/oauth2/v2/auth');
+        authUrl.searchParams.set('client_id', clientId);
+        authUrl.searchParams.set('redirect_uri', args.redirectUri);
+        authUrl.searchParams.set('response_type', 'code');
+        authUrl.searchParams.set('scope', scope);
+        authUrl.searchParams.set('access_type', 'offline'); // always
+        authUrl.searchParams.set('prompt', 'consent'); // always
+        authUrl.searchParams.set('code_challenge', args.codeChallenge);
+        authUrl.searchParams.set('code_challenge_method', 'S256');
+        authUrl.searchParams.set('state', args.state);
+        return authUrl.toString();
+    }
+    /**
+   * Create a cached token + email from an authorization code.
+   * This is the shared callback handler for BOTH persistent and ephemeral modes.
+   */ async handleAuthorizationCode(args) {
+        // Exchange code for token (must use same redirect_uri as in authorization request)
+        const tokenResponse = await this.exchangeCodeForToken(args.code, args.codeVerifier, args.redirectUri);
+        // 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);
+        return {
+            email,
+            token: cachedToken
+        };
+    }
+    /**
+   * Store token + account metadata. Shared by BOTH persistent and ephemeral modes.
+   */ async persistAuthResult(args) {
+        const { tokenStore, service } = this.config;
+        await setToken(tokenStore, {
+            accountId: args.email,
+            service
+        }, args.token);
+        await addAccount(tokenStore, {
+            service,
+            accountId: args.email
+        });
+        await setActiveAccount(tokenStore, {
+            service,
+            accountId: args.email
+        });
+        await setAccountInfo(tokenStore, {
+            service,
+            accountId: args.email
+        }, {
+            email: args.email,
+            addedAt: new Date().toISOString()
+        });
+    }
+    /**
+   * Pending auth (PKCE verifier) key format.
+   * Keep as-is (confirmed), even though it's not a public contract.
+   */ pendingKey(state) {
+        return `${this.config.service}:pending:${state}`;
+    }
+    /**
+   * Store PKCE verifier for callback (5 minute TTL).
+   * Shared by BOTH persistent and ephemeral modes.
+   */ async createPendingAuth(args) {
+        const { tokenStore } = this.config;
+        const record = {
+            codeVerifier: args.codeVerifier,
+            createdAt: Date.now()
+        };
+        await tokenStore.set(this.pendingKey(args.state), record, OAUTH_TIMEOUT_MS);
+    }
+    /**
+   * Load and validate pending auth state (5 minute TTL).
+   * Shared by BOTH persistent and ephemeral modes.
+   */ async readAndValidatePendingAuth(state) {
+        const { tokenStore } = this.config;
+        const pendingAuth = await tokenStore.get(this.pendingKey(state));
+        if (!pendingAuth) {
+            throw new Error('Invalid or expired OAuth state. Please try again.');
+        }
+        // Check TTL (5 minutes)
+        if (Date.now() - pendingAuth.createdAt > OAUTH_TIMEOUT_MS) {
+            await tokenStore.delete(this.pendingKey(state));
+            throw new Error('OAuth state expired. Please try again.');
+        }
+        return pendingAuth;
+    }
+    /**
+   * Mark pending auth as completed (used by middleware polling).
+   */ async markPendingComplete(args) {
+        const { tokenStore } = this.config;
+        const updated = {
+            ...args.pending,
+            completedAt: Date.now(),
+            email: args.email
+        };
+        await tokenStore.set(this.pendingKey(args.state), updated, OAUTH_TIMEOUT_MS);
+    }
+    /**
+   * Clean up pending auth state.
+   */ async deletePendingAuth(state) {
+        const { tokenStore } = this.config;
+        await tokenStore.delete(this.pendingKey(state));
+    }
+    /**
+   * Wait until pending auth is marked completed (or timeout).
+   * Used by middleware after opening auth URL in non-headless mode.
+   */ async waitForOAuthCompletion(state) {
+        const { tokenStore } = this.config;
+        const key = this.pendingKey(state);
+        const start = Date.now();
+        while(Date.now() - start < OAUTH_TIMEOUT_MS){
+            const pending = await tokenStore.get(key);
+            if (pending === null || pending === void 0 ? void 0 : pending.completedAt) {
+                return {
+                    email: pending.email
+                };
+            }
+            await new Promise((r)=>setTimeout(r, OAUTH_POLL_MS));
+        }
+        throw new Error('OAuth flow timed out after 5 minutes');
+    }
+    /**
+   * Process an OAuth callback using shared state validation + token exchange + persistence.
+   * Used by BOTH:
+   * - ephemeral loopback server callback handler
+   * - persistent redirectUri callback handler
+   *
+   * IMPORTANT CHANGE:
+   * - We do NOT delete pending state here anymore.
+   * - We mark it completed so middleware can poll and then clean it up.
+   */ async processOAuthCallback(args) {
+        const { logger, service } = this.config;
+        const pending = await this.readAndValidatePendingAuth(args.state);
+        logger.info('Processing OAuth callback', {
+            service,
+            state: args.state
+        });
+        const result = await this.handleAuthorizationCode({
+            code: args.code,
+            codeVerifier: pending.codeVerifier,
+            redirectUri: args.redirectUri
+        });
+        await this.persistAuthResult(result);
+        await this.markPendingComplete({
+            state: args.state,
+            email: result.email,
+            pending
+        });
+        logger.info('OAuth callback completed', {
+            service,
+            email: result.email
+        });
+        return result;
+    }
+    // ---------------------------------------------------------------------------
+    // Ephemeral loopback server + flow
+    // ---------------------------------------------------------------------------
+    /**
+   * Loopback OAuth server helper (RFC 8252 Section 7.3)
+   *
+   * Implements ephemeral local server with OS-assigned port (RFC 8252 Section 8.3).
+   * Shared callback handling uses:
+   * - the same authUrl builder as redirectUri mode
+   * - the same pending PKCE verifier storage as redirectUri mode
+   * - the same callback processor as redirectUri mode
+   */ createOAuthCallbackServer(args) {
+        const { logger } = this.config;
+        // Create ephemeral server with OS-assigned port (RFC 8252)
+        return http.createServer(async (req, res)=>{
+            try {
+                if (!req.url) {
+                    res.writeHead(400, {
+                        'Content-Type': 'text/html'
+                    });
+                    res.end(getErrorTemplate('Invalid request'));
+                    args.onError(new Error('Invalid request: missing URL'));
+                    return;
+                }
+                // Use loopback base for URL parsing (port is not important for parsing path/query)
+                const url = new URL(req.url, 'http://127.0.0.1');
+                if (url.pathname !== args.callbackPath) {
+                    res.writeHead(404, {
+                        'Content-Type': 'text/plain'
+                    });
+                    res.end('Not Found');
+                    return;
+                }
+                const code = url.searchParams.get('code');
+                const error = url.searchParams.get('error');
+                const state = url.searchParams.get('state');
+                if (error) {
+                    res.writeHead(400, {
+                        'Content-Type': 'text/html'
+                    });
+                    res.end(getErrorTemplate(error));
+                    args.onError(new Error(`OAuth error: ${error}`));
+                    return;
+                }
+                if (!code) {
+                    res.writeHead(400, {
+                        'Content-Type': 'text/html'
+                    });
+                    res.end(getErrorTemplate('No authorization code received'));
+                    args.onError(new Error('No authorization code received'));
+                    return;
+                }
+                if (!state) {
+                    res.writeHead(400, {
+                        'Content-Type': 'text/html'
+                    });
+                    res.end(getErrorTemplate('Missing state parameter in OAuth callback'));
+                    args.onError(new Error('Missing state parameter in OAuth callback'));
+                    return;
+                }
+                try {
+                    await this.processOAuthCallback({
+                        code,
+                        state,
+                        redirectUri: args.finalRedirectUri()
+                    });
+                    res.writeHead(200, {
+                        'Content-Type': 'text/html'
+                    });
+                    res.end(getSuccessTemplate());
+                    args.onDone();
+                } 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'));
+                    args.onError(exchangeError);
+                }
+            } catch (outerError) {
+                logger.error('OAuth callback server error', {
+                    error: outerError instanceof Error ? outerError.message : String(outerError)
+                });
+                res.writeHead(500, {
+                    'Content-Type': 'text/html'
+                });
+                res.end(getErrorTemplate('Internal server error'));
+                args.onError(outerError);
+            }
+        });
+    }
+    /**
+   * Starts the ephemeral loopback server and returns an AuthRequiredError(auth_url).
+   * Middleware will open+poll and then retry in the same call.
+   */ async startEphemeralOAuthFlow() {
+        const { headless, logger, redirectUri: configRedirectUri, service, tokenStore } = this.config;
+        // Server listen configuration (where ephemeral server binds)
+        let listenHost = 'localhost'; // Default: localhost for ephemeral loopback
+        let listenPort = 0; // Default: OS-assigned ephemeral port
+        // Redirect URI configuration (what goes in auth URL and token exchange)
         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);
+                const isLoopback = parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1';
+                if (isLoopback) {
+                    // Local development: Listen on specific loopback address/port
+                    listenHost = parsed.hostname;
+                    listenPort = parsed.port ? Number.parseInt(parsed.port, 10) : 0;
                 } else {
-                    targetPort = parsed.protocol === 'https:' ? 443 : 80;
+                    // Cloud deployment: Listen on 0.0.0.0 with PORT from environment
+                    // The redirectUri is the PUBLIC URL (e.g., https://example.com/oauth/callback)
+                    // The server listens on 0.0.0.0:PORT and the load balancer routes to it
+                    listenHost = '0.0.0.0';
+                    const envPort = process.env.PORT ? Number.parseInt(process.env.PORT, 10) : undefined;
+                    listenPort = envPort && Number.isFinite(envPort) ? envPort : 8080;
                 }
-                // Extract path (default to /callback if URL has no path or just '/')
+                // Extract callback path from URL
                 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
+                    listenHost,
+                    listenPort,
+                    callbackPath,
+                    redirectUri: configRedirectUri,
+                    isLoopback
                 });
             } 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)
+            // Continue with defaults (localhost, 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, ()=>{
+        // Generate PKCE challenge + state
+        const { verifier: codeVerifier, challenge: codeChallenge } = generatePKCE();
+        const stateId = randomUUID();
+        // Store PKCE verifier for callback (5 minute TTL)
+        await this.createPendingAuth({
+            state: stateId,
+            codeVerifier
+        });
+        let server = null;
+        let serverPort;
+        let finalRedirectUri; // set after listen
+        // Create ephemeral server with OS-assigned port (RFC 8252)
+        server = this.createOAuthCallbackServer({
+            callbackPath,
+            finalRedirectUri: ()=>finalRedirectUri,
+            onDone: ()=>{
+                server === null || server === void 0 ? void 0 : server.close();
+            },
+            onError: (err)=>{
+                logger.error('Ephemeral OAuth server error', {
+                    error: err instanceof Error ? err.message : String(err)
+                });
+                server === null || server === void 0 ? void 0 : server.close();
+            }
+        });
+        // Start listening
+        await new Promise((resolve, reject)=>{
+            server === null || server === void 0 ? void 0 : server.listen(listenPort, listenHost, ()=>{
                 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();
@@ -408,52 +545,38 @@ import { AuthRequiredError } from '../types.js';
                 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}`;
+                    finalRedirectUri = `http://localhost:${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
+                    headless,
+                    service
                 });
-                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`);
-                    });
-                }
+                resolve();
             });
-            // Timeout after 5 minutes
-            setTimeout(()=>{
-                if (server) {
-                    server.close();
-                    reject(new Error('OAuth flow timed out after 5 minutes'));
-                }
-            }, 5 * 60 * 1000);
         });
+        // Timeout after 5 minutes (match middleware polling timeout)
+        setTimeout(()=>{
+            if (server) {
+                server.close();
+                // Best-effort cleanup if user never completes flow:
+                // delete pending so a future attempt can restart cleanly.
+                void tokenStore.delete(this.pendingKey(stateId));
+            }
+        }, OAUTH_TIMEOUT_MS);
+        // Build auth URL - SAME helper as persistent mode
+        const authUrl = this.buildAuthUrl({
+            redirectUri: finalRedirectUri,
+            codeChallenge,
+            state: stateId
+        });
+        return {
+            kind: 'auth_url',
+            provider: service,
+            url: authUrl
+        };
     }
     async exchangeCodeForToken(code, codeVerifier, redirectUri) {
         const { clientId, clientSecret } = this.config;
@@ -518,6 +641,28 @@ import { AuthRequiredError } from '../types.js';
         };
     }
     /**
+   * Handle OAuth callback from persistent endpoint.
+   * Used by HTTP servers with configured redirectUri.
+   *
+   * @param params - OAuth callback parameters
+   * @returns Email and cached token
+   */ async handleOAuthCallback(params) {
+        const { code, state } = params;
+        const { redirectUri } = this.config;
+        if (!state) {
+            throw new Error('Missing state parameter in OAuth callback');
+        }
+        if (!redirectUri) {
+            throw new Error('handleOAuthCallback requires configured redirectUri');
+        }
+        // Shared callback processor (same code path as ephemeral)
+        return await this.processOAuthCallback({
+            code,
+            state,
+            redirectUri
+        });
+    }
+    /**
    * Create authentication middleware for MCP tools, resources, and prompts
    *
    * Returns position-aware middleware wrappers that enrich handlers with authentication context.
@@ -531,15 +676,6 @@ import { AuthRequiredError } from '../types.js';
    * 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
@@ -550,31 +686,60 @@ import { AuthRequiredError } from '../types.js';
             const wrappedHandler = async (...allArgs)=>{
                 // Extract extra from the correct position
                 const extra = allArgs[extraPosition];
-                try {
-                    // Check for backchannel override via _meta.accountId
-                    let accountId;
+                // Helper: retry once after open+poll completes
+                const ensureAuthenticatedOrThrow = async ()=>{
                     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, {
+                        // 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;
+                            }
+                        }
+                        await this.getAccessToken(accountId);
+                        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}`);
+                        }
+                        return effectiveAccountId;
                     } catch (error) {
-                        if (error instanceof Error && (error.code === 'REQUIRES_AUTHENTICATION' || error.name === 'AccountManagerError')) {
-                            accountId = undefined;
-                        } else {
-                            throw error;
+                        if (error instanceof AuthRequiredError && error.descriptor.kind === 'auth_url') {
+                            // Headless: don't open/poll; just propagate to outer handler to return auth_required.
+                            if (this.config.headless) throw error;
+                            // Non-headless: open once + poll until callback completes, then retry token acquisition.
+                            const authUrl = new URL(error.descriptor.url);
+                            const state = authUrl.searchParams.get('state');
+                            if (!state) throw new Error('Auth URL missing state parameter');
+                            if (!this.openedStates.has(state)) {
+                                this.openedStates.add(state);
+                                open(error.descriptor.url).catch((e)=>{
+                                    logger.info('Failed to open browser automatically', {
+                                        error: e instanceof Error ? e.message : String(e)
+                                    });
+                                });
+                            }
+                            // Block until callback completes (or timeout)
+                            await this.waitForOAuthCompletion(state);
+                            // Cleanup pending state after we observe completion
+                            await this.deletePendingAuth(state);
+                            // Retry after completion
+                            return await ensureAuthenticatedOrThrow();
                         }
+                        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}`);
-                    }
+                };
+                try {
+                    const effectiveAccountId = await ensureAuthenticatedOrThrow();
                     const auth = this.toAuth(effectiveAccountId);
                     // Inject authContext and logger into extra
                     extra.authContext = {
@@ -591,8 +756,6 @@ import { AuthRequiredError } from '../types.js';
                             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,
@@ -628,6 +791,8 @@ import { AuthRequiredError } from '../types.js';
         };
     }
     constructor(config){
+        // Track URLs we've already opened for a given state within this process (prevents tab spam).
+        this.openedStates = new Set();
         this.config = config;
     }
 }