@mcp-z/oauth-google 1.0.1 → 1.0.3

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

@@ -3,6 +3,16 @@
  *
  * 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).
+ *
+ * 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.
  */ "use strict";
 Object.defineProperty(exports, "__esModule", {
     value: true
@@ -290,10 +300,14 @@ function _ts_generator(thisArg, body) {
         };
     }
 }
+var OAUTH_TIMEOUT_MS = 5 * 60 * 1000;
+var OAUTH_POLL_MS = 500;
 var LoopbackOAuthProvider = /*#__PURE__*/ function() {
     "use strict";
     function LoopbackOAuthProvider(config) {
         _class_call_check(this, LoopbackOAuthProvider);
+        // Track URLs we've already opened for a given state within this process (prevents tab spam).
+        this.openedStates = new Set();
         this.config = config;
     }
     var _proto = LoopbackOAuthProvider.prototype;
@@ -304,7 +318,7 @@ var LoopbackOAuthProvider = /*#__PURE__*/ function() {
    * @returns Access token for API requests
    */ _proto.getAccessToken = function getAccessToken(accountId) {
         return _async_to_generator(function() {
-            var _this_config, logger, service, tokenStore, effectiveAccountId, _tmp, storedToken, refreshedToken, error, _this_config1, clientId, scope, redirectUri, _generatePKCE, codeVerifier, codeChallenge, stateId, authUrl, _ref, token, email;
+            var _this_config, logger, service, tokenStore, effectiveAccountId, _tmp, storedToken, refreshedToken, error, _this_config1, clientId, scope, redirectUri, _generatePKCE, codeVerifier, codeChallenge, stateId, authUrl, descriptor;
             return _ts_generator(this, function(_state) {
                 switch(_state.label){
                     case 0:
@@ -413,92 +427,44 @@ var LoopbackOAuthProvider = /*#__PURE__*/ function() {
                         // Store PKCE verifier for callback (5 minute TTL)
                         return [
                             4,
-                            tokenStore.set("".concat(service, ":pending:").concat(stateId), {
-                                codeVerifier: codeVerifier,
-                                createdAt: Date.now()
-                            }, 5 * 60 * 1000)
+                            this.createPendingAuth({
+                                state: stateId,
+                                codeVerifier: codeVerifier
+                            })
                         ];
                     case 10:
                         _state.sent();
                         // Build auth URL with configured redirect_uri
-                        authUrl = new URL('https://accounts.google.com/o/oauth2/v2/auth');
-                        authUrl.searchParams.set('client_id', clientId);
-                        authUrl.searchParams.set('redirect_uri', redirectUri);
-                        authUrl.searchParams.set('response_type', 'code');
-                        authUrl.searchParams.set('scope', scope);
-                        authUrl.searchParams.set('access_type', 'offline');
-                        authUrl.searchParams.set('code_challenge', codeChallenge);
-                        authUrl.searchParams.set('code_challenge_method', 'S256');
-                        authUrl.searchParams.set('state', stateId);
-                        authUrl.searchParams.set('prompt', 'consent');
+                        authUrl = this.buildAuthUrl({
+                            redirectUri: redirectUri,
+                            codeChallenge: codeChallenge,
+                            state: stateId
+                        });
                         logger.info('OAuth required - persistent callback mode', {
                             service: service,
-                            redirectUri: redirectUri
+                            redirectUri: redirectUri,
+                            clientId: clientId,
+                            scope: scope
                         });
                         throw new _typests.AuthRequiredError({
                             kind: 'auth_url',
                             provider: service,
-                            url: authUrl.toString()
+                            url: authUrl
                         });
                     case 11:
                         // 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: service,
                             headless: this.config.headless
                         });
                         return [
                             4,
-                            this.performEphemeralOAuthFlow()
+                            this.startEphemeralOAuthFlow()
                         ];
                     case 12:
-                        _ref = _state.sent(), token = _ref.token, email = _ref.email;
-                        return [
-                            4,
-                            (0, _oauth.setToken)(tokenStore, {
-                                accountId: email,
-                                service: service
-                            }, token)
-                        ];
-                    case 13:
-                        _state.sent();
-                        return [
-                            4,
-                            (0, _oauth.addAccount)(tokenStore, {
-                                service: service,
-                                accountId: email
-                            })
-                        ];
-                    case 14:
-                        _state.sent();
-                        return [
-                            4,
-                            (0, _oauth.setActiveAccount)(tokenStore, {
-                                service: service,
-                                accountId: email
-                            })
-                        ];
-                    case 15:
-                        _state.sent();
-                        return [
-                            4,
-                            (0, _oauth.setAccountInfo)(tokenStore, {
-                                service: service,
-                                accountId: email
-                            }, {
-                                email: email,
-                                addedAt: new Date().toISOString()
-                            })
-                        ];
-                    case 16:
-                        _state.sent();
-                        logger.info('OAuth flow completed', {
-                            service: service,
-                            accountId: email
-                        });
-                        return [
-                            2,
-                            token.accessToken
-                        ];
+                        descriptor = _state.sent();
+                        throw new _typests.AuthRequiredError(descriptor);
                 }
             });
         }).call(this);
@@ -666,531 +632,802 @@ var LoopbackOAuthProvider = /*#__PURE__*/ function() {
             });
         }).call(this);
     };
-    _proto.performEphemeralOAuthFlow = function performEphemeralOAuthFlow() {
+    // ---------------------------------------------------------------------------
+    // Shared OAuth helpers
+    // ---------------------------------------------------------------------------
+    /**
+   * Build OAuth authorization URL with the "most parameters" baseline.
+   * This is shared by BOTH persistent (redirectUri) and ephemeral (loopback) modes.
+   */ _proto.buildAuthUrl = function buildAuthUrl(args) {
+        var _this_config = this.config, clientId = _this_config.clientId, scope = _this_config.scope;
+        var 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.
+   */ _proto.handleAuthorizationCode = function handleAuthorizationCode(args) {
         return _async_to_generator(function() {
-            var _this, _this_config, clientId, scope, headless, logger, configRedirectUri, listenHost, listenPort, callbackPath, useConfiguredUri, parsed, isLoopback, envPort;
+            var tokenResponse, cachedToken, email;
             return _ts_generator(this, function(_state) {
-                _this = this;
-                _this_config = this.config, clientId = _this_config.clientId, scope = _this_config.scope, headless = _this_config.headless, logger = _this_config.logger, configRedirectUri = _this_config.redirectUri;
-                // Server listen configuration (where ephemeral server binds)
-                listenHost = 'localhost'; // Default: localhost for ephemeral loopback
-                listenPort = 0; // Default: OS-assigned ephemeral port
-                // Redirect URI configuration (what goes in auth URL and token exchange)
-                callbackPath = '/callback'; // Default callback path
-                useConfiguredUri = false;
-                if (configRedirectUri) {
-                    try {
-                        parsed = new URL(configRedirectUri);
-                        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 {
-                            // 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';
-                            envPort = process.env.PORT ? Number.parseInt(process.env.PORT, 10) : undefined;
-                            listenPort = envPort && Number.isFinite(envPort) ? envPort : 8080;
-                        }
-                        // Extract callback path from URL
-                        if (parsed.pathname && parsed.pathname !== '/') {
-                            callbackPath = parsed.pathname;
-                        }
-                        useConfiguredUri = true;
-                        logger.debug('Using configured redirect URI', {
-                            listenHost: listenHost,
-                            listenPort: listenPort,
-                            callbackPath: callbackPath,
-                            redirectUri: configRedirectUri,
-                            isLoopback: isLoopback
-                        });
-                    } catch (error) {
-                        logger.warn('Failed to parse redirectUri, using ephemeral defaults', {
-                            redirectUri: configRedirectUri,
-                            error: _instanceof(error, Error) ? error.message : String(error)
-                        });
-                    // Continue with defaults (localhost, port 0, http, /callback)
-                    }
-                }
-                return [
-                    2,
-                    new Promise(function(resolve, reject) {
-                        // Generate PKCE challenge
-                        var _generatePKCE = (0, _oauth.generatePKCE)(), codeVerifier = _generatePKCE.verifier, codeChallenge = _generatePKCE.challenge;
-                        var server = null;
-                        var serverPort;
-                        var finalRedirectUri; // Will be set in server.listen callback
-                        // Create ephemeral server with OS-assigned port (RFC 8252)
-                        server = _http.createServer(function(req, res) {
-                            return _async_to_generator(function() {
-                                var url, code, _$error, tokenResponse, cachedToken, email, exchangeError;
-                                return _ts_generator(this, function(_state) {
-                                    switch(_state.label){
-                                        case 0:
-                                            if (!req.url) {
-                                                res.writeHead(400, {
-                                                    'Content-Type': 'text/html'
-                                                });
-                                                res.end((0, _oauth.getErrorTemplate)('Invalid request'));
-                                                server === null || server === void 0 ? void 0 : server.close();
-                                                reject(new Error('Invalid request: missing URL'));
-                                                return [
-                                                    2
-                                                ];
-                                            }
-                                            url = new URL(req.url, "http://127.0.0.1:".concat(serverPort));
-                                            if (!(url.pathname === callbackPath)) return [
-                                                3,
-                                                6
-                                            ];
-                                            code = url.searchParams.get('code');
-                                            _$error = url.searchParams.get('error');
-                                            if (_$error) {
-                                                res.writeHead(400, {
-                                                    'Content-Type': 'text/html'
-                                                });
-                                                res.end((0, _oauth.getErrorTemplate)(_$error));
-                                                server === null || server === void 0 ? void 0 : server.close();
-                                                reject(new Error("OAuth error: ".concat(_$error)));
-                                                return [
-                                                    2
-                                                ];
-                                            }
-                                            if (!code) {
-                                                res.writeHead(400, {
-                                                    'Content-Type': 'text/html'
-                                                });
-                                                res.end((0, _oauth.getErrorTemplate)('No authorization code received'));
-                                                server === null || server === void 0 ? void 0 : server.close();
-                                                reject(new Error('No authorization code received'));
-                                                return [
-                                                    2
-                                                ];
-                                            }
-                                            _state.label = 1;
-                                        case 1:
-                                            _state.trys.push([
-                                                1,
-                                                4,
-                                                ,
-                                                5
-                                            ]);
-                                            return [
-                                                4,
-                                                this.exchangeCodeForToken(code, codeVerifier, finalRedirectUri)
-                                            ];
-                                        case 2:
-                                            tokenResponse = _state.sent();
-                                            // Build cached token
-                                            cachedToken = _object_spread({
-                                                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
-                                            });
-                                            return [
-                                                4,
-                                                this.fetchUserEmailFromToken(tokenResponse.access_token)
-                                            ];
-                                        case 3:
-                                            email = _state.sent();
-                                            res.writeHead(200, {
-                                                'Content-Type': 'text/html'
-                                            });
-                                            res.end((0, _oauth.getSuccessTemplate)());
-                                            server === null || server === void 0 ? void 0 : server.close();
-                                            resolve({
-                                                token: cachedToken,
-                                                email: email
-                                            });
-                                            return [
-                                                3,
-                                                5
-                                            ];
-                                        case 4:
-                                            exchangeError = _state.sent();
-                                            logger.error('Token exchange failed', {
-                                                error: _instanceof(exchangeError, Error) ? exchangeError.message : String(exchangeError)
-                                            });
-                                            res.writeHead(500, {
-                                                'Content-Type': 'text/html'
-                                            });
-                                            res.end((0, _oauth.getErrorTemplate)('Token exchange failed'));
-                                            server === null || server === void 0 ? void 0 : server.close();
-                                            reject(exchangeError);
-                                            return [
-                                                3,
-                                                5
-                                            ];
-                                        case 5:
-                                            return [
-                                                3,
-                                                7
-                                            ];
-                                        case 6:
-                                            res.writeHead(404, {
-                                                'Content-Type': 'text/plain'
-                                            });
-                                            res.end('Not Found');
-                                            _state.label = 7;
-                                        case 7:
-                                            return [
-                                                2
-                                            ];
-                                    }
-                                });
-                            }).call(_this);
-                        });
-                        // Listen on configured host/port
-                        server.listen(listenPort, listenHost, function() {
-                            var 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 (public URL for cloud, or specific local URL)
-                                finalRedirectUri = configRedirectUri;
-                            } else {
-                                // Construct ephemeral redirect URI with actual server port (default local behavior)
-                                finalRedirectUri = "http://localhost:".concat(serverPort).concat(callbackPath);
-                            }
-                            // Build auth URL
-                            var 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
-                            });
-                            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("   ".concat(authUrl.toString(), "\n"));
-                                console.error('⏳ Waiting for authorization...\n');
-                            } else {
-                                // Interactive mode: Open browser automatically
-                                logger.info('Opening browser for OAuth authorization');
-                                (0, _open.default)(authUrl.toString()).catch(function(error) {
-                                    logger.info('Failed to open browser automatically', {
-                                        error: error.message
-                                    });
-                                    console.error('\n🔐 OAuth Authorization Required');
-                                    console.error("   ".concat(authUrl.toString(), "\n"));
-                                });
-                            }
+                switch(_state.label){
+                    case 0:
+                        return [
+                            4,
+                            this.exchangeCodeForToken(args.code, args.codeVerifier, args.redirectUri)
+                        ];
+                    case 1:
+                        tokenResponse = _state.sent();
+                        // Build cached token
+                        cachedToken = _object_spread({
+                            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
                         });
-                        // Timeout after 5 minutes
-                        setTimeout(function() {
-                            if (server) {
-                                server.close();
-                                reject(new Error('OAuth flow timed out after 5 minutes'));
+                        return [
+                            4,
+                            this.fetchUserEmailFromToken(tokenResponse.access_token)
+                        ];
+                    case 2:
+                        email = _state.sent();
+                        return [
+                            2,
+                            {
+                                email: email,
+                                token: cachedToken
                             }
-                        }, 5 * 60 * 1000);
-                    })
-                ];
+                        ];
+                }
             });
         }).call(this);
     };
-    _proto.exchangeCodeForToken = function exchangeCodeForToken(code, codeVerifier, redirectUri) {
+    /**
+   * Store token + account metadata. Shared by BOTH persistent and ephemeral modes.
+   */ _proto.persistAuthResult = function persistAuthResult(args) {
         return _async_to_generator(function() {
-            var _this_config, clientId, clientSecret, tokenUrl, params, body, response, errorText;
+            var _this_config, tokenStore, service;
             return _ts_generator(this, function(_state) {
                 switch(_state.label){
                     case 0:
-                        _this_config = this.config, clientId = _this_config.clientId, clientSecret = _this_config.clientSecret;
-                        tokenUrl = 'https://oauth2.googleapis.com/token';
-                        params = {
-                            code: code,
-                            client_id: clientId,
-                            redirect_uri: redirectUri,
-                            grant_type: 'authorization_code',
-                            code_verifier: codeVerifier
-                        };
-                        if (clientSecret) {
-                            params.client_secret = clientSecret;
-                        }
-                        body = new URLSearchParams(params);
+                        _this_config = this.config, tokenStore = _this_config.tokenStore, service = _this_config.service;
                         return [
                             4,
-                            fetch(tokenUrl, {
-                                method: 'POST',
-                                headers: {
-                                    'Content-Type': 'application/x-www-form-urlencoded'
-                                },
-                                body: body.toString()
-                            })
+                            (0, _oauth.setToken)(tokenStore, {
+                                accountId: args.email,
+                                service: service
+                            }, args.token)
                         ];
                     case 1:
-                        response = _state.sent();
-                        if (!!response.ok) return [
-                            3,
-                            3
-                        ];
+                        _state.sent();
                         return [
                             4,
-                            response.text()
+                            (0, _oauth.addAccount)(tokenStore, {
+                                service: service,
+                                accountId: args.email
+                            })
                         ];
                     case 2:
-                        errorText = _state.sent();
-                        throw new Error("Token exchange failed: ".concat(response.status, " ").concat(errorText));
+                        _state.sent();
+                        return [
+                            4,
+                            (0, _oauth.setActiveAccount)(tokenStore, {
+                                service: service,
+                                accountId: args.email
+                            })
+                        ];
                     case 3:
+                        _state.sent();
                         return [
                             4,
-                            response.json()
+                            (0, _oauth.setAccountInfo)(tokenStore, {
+                                service: service,
+                                accountId: args.email
+                            }, {
+                                email: args.email,
+                                addedAt: new Date().toISOString()
+                            })
                         ];
                     case 4:
+                        _state.sent();
                         return [
-                            2,
-                            _state.sent()
+                            2
                         ];
                 }
             });
         }).call(this);
     };
-    _proto.refreshAccessToken = function refreshAccessToken(refreshToken) {
+    /**
+   * Pending auth (PKCE verifier) key format.
+   * Keep as-is (confirmed), even though it's not a public contract.
+   */ _proto.pendingKey = function pendingKey(state) {
+        return "".concat(this.config.service, ":pending:").concat(state);
+    };
+    /**
+   * Store PKCE verifier for callback (5 minute TTL).
+   * Shared by BOTH persistent and ephemeral modes.
+   */ _proto.createPendingAuth = function createPendingAuth(args) {
         return _async_to_generator(function() {
-            var _this_config, clientId, clientSecret, tokenUrl, params, body, response, errorText, tokenResponse;
+            var tokenStore, record;
             return _ts_generator(this, function(_state) {
                 switch(_state.label){
                     case 0:
-                        _this_config = this.config, clientId = _this_config.clientId, clientSecret = _this_config.clientSecret;
-                        tokenUrl = 'https://oauth2.googleapis.com/token';
-                        params = {
-                            refresh_token: refreshToken,
-                            client_id: clientId,
-                            grant_type: 'refresh_token'
+                        tokenStore = this.config.tokenStore;
+                        record = {
+                            codeVerifier: args.codeVerifier,
+                            createdAt: Date.now()
                         };
-                        if (clientSecret) {
-                            params.client_secret = clientSecret;
-                        }
-                        body = new URLSearchParams(params);
                         return [
                             4,
-                            fetch(tokenUrl, {
-                                method: 'POST',
-                                headers: {
-                                    'Content-Type': 'application/x-www-form-urlencoded'
-                                },
-                                body: body.toString()
-                            })
+                            tokenStore.set(this.pendingKey(args.state), record, OAUTH_TIMEOUT_MS)
                         ];
                     case 1:
-                        response = _state.sent();
-                        if (!!response.ok) return [
-                            3,
-                            3
-                        ];
-                        return [
-                            4,
-                            response.text()
-                        ];
-                    case 2:
-                        errorText = _state.sent();
-                        throw new Error("Token refresh failed: ".concat(response.status, " ").concat(errorText));
-                    case 3:
-                        return [
-                            4,
-                            response.json()
-                        ];
-                    case 4:
-                        tokenResponse = _state.sent();
+                        _state.sent();
                         return [
-                            2,
-                            _object_spread({
-                                accessToken: tokenResponse.access_token,
-                                refreshToken: refreshToken
-                            }, tokenResponse.expires_in !== undefined && {
-                                expiresAt: Date.now() + tokenResponse.expires_in * 1000
-                            }, tokenResponse.scope !== undefined && {
-                                scope: tokenResponse.scope
-                            })
+                            2
                         ];
                 }
             });
         }).call(this);
     };
     /**
-   * Handle OAuth callback from persistent endpoint.
-   * Used by HTTP servers with configured redirectUri.
-   *
-   * @param params - OAuth callback parameters
-   * @returns Email and cached token
-   */ _proto.handleOAuthCallback = function handleOAuthCallback(params) {
+   * Load and validate pending auth state (5 minute TTL).
+   * Shared by BOTH persistent and ephemeral modes.
+   */ _proto.readAndValidatePendingAuth = function readAndValidatePendingAuth(state) {
         return _async_to_generator(function() {
-            var code, state, _this_config, logger, service, tokenStore, clientId, clientSecret, redirectUri, pendingKey, pendingAuth, body, response, errorText, tokenResponse, email, cachedToken;
+            var tokenStore, pendingAuth;
             return _ts_generator(this, function(_state) {
                 switch(_state.label){
                     case 0:
-                        code = params.code, state = params.state;
-                        _this_config = this.config, logger = _this_config.logger, service = _this_config.service, tokenStore = _this_config.tokenStore, clientId = _this_config.clientId, clientSecret = _this_config.clientSecret, redirectUri = _this_config.redirectUri;
-                        if (!state) {
-                            throw new Error('Missing state parameter in OAuth callback');
-                        }
-                        if (!redirectUri) {
-                            throw new Error('handleOAuthCallback requires configured redirectUri');
-                        }
-                        // Load pending auth (includes PKCE verifier)
-                        pendingKey = "".concat(service, ":pending:").concat(state);
+                        tokenStore = this.config.tokenStore;
                         return [
                             4,
-                            tokenStore.get(pendingKey)
+                            tokenStore.get(this.pendingKey(state))
                         ];
                     case 1:
                         pendingAuth = _state.sent();
                         if (!pendingAuth) {
                             throw new Error('Invalid or expired OAuth state. Please try again.');
                         }
-                        if (!(Date.now() - pendingAuth.createdAt > 5 * 60 * 1000)) return [
+                        if (!(Date.now() - pendingAuth.createdAt > OAUTH_TIMEOUT_MS)) return [
                             3,
                             3
                         ];
                         return [
                             4,
-                            tokenStore.delete(pendingKey)
+                            tokenStore.delete(this.pendingKey(state))
                         ];
                     case 2:
                         _state.sent();
                         throw new Error('OAuth state expired. Please try again.');
                     case 3:
-                        logger.info('Processing OAuth callback', {
-                            service: service,
-                            state: state
+                        return [
+                            2,
+                            pendingAuth
+                        ];
+                }
+            });
+        }).call(this);
+    };
+    /**
+   * Mark pending auth as completed (used by middleware polling).
+   */ _proto.markPendingComplete = function markPendingComplete(args) {
+        return _async_to_generator(function() {
+            var tokenStore, updated;
+            return _ts_generator(this, function(_state) {
+                switch(_state.label){
+                    case 0:
+                        tokenStore = this.config.tokenStore;
+                        updated = _object_spread_props(_object_spread({}, args.pending), {
+                            completedAt: Date.now(),
+                            email: args.email
                         });
-                        // Exchange code for token
-                        body = new URLSearchParams(_object_spread_props(_object_spread({
-                            code: code,
-                            client_id: clientId
-                        }, clientSecret && {
-                            client_secret: clientSecret
-                        }), {
-                            redirect_uri: redirectUri,
-                            grant_type: 'authorization_code',
-                            code_verifier: pendingAuth.codeVerifier
-                        }));
                         return [
                             4,
-                            fetch('https://oauth2.googleapis.com/token', {
-                                method: 'POST',
-                                headers: {
-                                    'Content-Type': 'application/x-www-form-urlencoded'
-                                },
-                                body: body.toString()
-                            })
+                            tokenStore.set(this.pendingKey(args.state), updated, OAUTH_TIMEOUT_MS)
                         ];
-                    case 4:
-                        response = _state.sent();
-                        if (!!response.ok) return [
-                            3,
-                            6
+                    case 1:
+                        _state.sent();
+                        return [
+                            2
                         ];
+                }
+            });
+        }).call(this);
+    };
+    /**
+   * Clean up pending auth state.
+   */ _proto.deletePendingAuth = function deletePendingAuth(state) {
+        return _async_to_generator(function() {
+            var tokenStore;
+            return _ts_generator(this, function(_state) {
+                switch(_state.label){
+                    case 0:
+                        tokenStore = this.config.tokenStore;
                         return [
                             4,
-                            response.text()
+                            tokenStore.delete(this.pendingKey(state))
                         ];
-                    case 5:
-                        errorText = _state.sent();
-                        throw new Error("Token exchange failed: ".concat(response.status, " ").concat(errorText));
-                    case 6:
+                    case 1:
+                        _state.sent();
                         return [
-                            4,
-                            response.json()
+                            2
+                        ];
+                }
+            });
+        }).call(this);
+    };
+    /**
+   * Wait until pending auth is marked completed (or timeout).
+   * Used by middleware after opening auth URL in non-headless mode.
+   */ _proto.waitForOAuthCompletion = function waitForOAuthCompletion(state) {
+        return _async_to_generator(function() {
+            var tokenStore, key, start, pending;
+            return _ts_generator(this, function(_state) {
+                switch(_state.label){
+                    case 0:
+                        tokenStore = this.config.tokenStore;
+                        key = this.pendingKey(state);
+                        start = Date.now();
+                        _state.label = 1;
+                    case 1:
+                        if (!(Date.now() - start < OAUTH_TIMEOUT_MS)) return [
+                            3,
+                            4
                         ];
-                    case 7:
-                        tokenResponse = _state.sent();
                         return [
                             4,
-                            this.fetchUserEmailFromToken(tokenResponse.access_token)
+                            tokenStore.get(key)
                         ];
-                    case 8:
-                        email = _state.sent();
-                        // Create cached token
-                        cachedToken = _object_spread({
-                            accessToken: tokenResponse.access_token,
-                            refreshToken: tokenResponse.refresh_token,
-                            expiresAt: tokenResponse.expires_in ? Date.now() + tokenResponse.expires_in * 1000 : undefined
-                        }, tokenResponse.scope !== undefined && {
-                            scope: tokenResponse.scope
-                        });
-                        // Store token
+                    case 2:
+                        pending = _state.sent();
+                        if (pending === null || pending === void 0 ? void 0 : pending.completedAt) {
+                            return [
+                                2,
+                                {
+                                    email: pending.email
+                                }
+                            ];
+                        }
                         return [
                             4,
-                            (0, _oauth.setToken)(tokenStore, {
-                                accountId: email,
-                                service: service
-                            }, cachedToken)
+                            new Promise(function(r) {
+                                return setTimeout(r, OAUTH_POLL_MS);
+                            })
                         ];
-                    case 9:
+                    case 3:
                         _state.sent();
-                        // Add account and set as active
+                        return [
+                            3,
+                            1
+                        ];
+                    case 4:
+                        throw new Error('OAuth flow timed out after 5 minutes');
+                }
+            });
+        }).call(this);
+    };
+    /**
+   * 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.
+   */ _proto.processOAuthCallback = function processOAuthCallback(args) {
+        return _async_to_generator(function() {
+            var _this_config, logger, service, pending, result;
+            return _ts_generator(this, function(_state) {
+                switch(_state.label){
+                    case 0:
+                        _this_config = this.config, logger = _this_config.logger, service = _this_config.service;
                         return [
                             4,
-                            (0, _oauth.addAccount)(tokenStore, {
-                                service: service,
-                                accountId: email
+                            this.readAndValidatePendingAuth(args.state)
+                        ];
+                    case 1:
+                        pending = _state.sent();
+                        logger.info('Processing OAuth callback', {
+                            service: service,
+                            state: args.state
+                        });
+                        return [
+                            4,
+                            this.handleAuthorizationCode({
+                                code: args.code,
+                                codeVerifier: pending.codeVerifier,
+                                redirectUri: args.redirectUri
                             })
                         ];
-                    case 10:
+                    case 2:
+                        result = _state.sent();
+                        return [
+                            4,
+                            this.persistAuthResult(result)
+                        ];
+                    case 3:
                         _state.sent();
                         return [
                             4,
-                            (0, _oauth.setActiveAccount)(tokenStore, {
-                                service: service,
-                                accountId: email
+                            this.markPendingComplete({
+                                state: args.state,
+                                email: result.email,
+                                pending: pending
                             })
                         ];
-                    case 11:
+                    case 4:
                         _state.sent();
-                        // Store account metadata
+                        logger.info('OAuth callback completed', {
+                            service: service,
+                            email: result.email
+                        });
+                        return [
+                            2,
+                            result
+                        ];
+                }
+            });
+        }).call(this);
+    };
+    // ---------------------------------------------------------------------------
+    // 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
+   */ _proto.createOAuthCallbackServer = function createOAuthCallbackServer(args) {
+        var _this = this;
+        var logger = this.config.logger;
+        // Create ephemeral server with OS-assigned port (RFC 8252)
+        return _http.createServer(function(req, res) {
+            return _async_to_generator(function() {
+                var url, code, error, state, exchangeError, outerError;
+                return _ts_generator(this, function(_state) {
+                    switch(_state.label){
+                        case 0:
+                            _state.trys.push([
+                                0,
+                                5,
+                                ,
+                                6
+                            ]);
+                            if (!req.url) {
+                                res.writeHead(400, {
+                                    'Content-Type': 'text/html'
+                                });
+                                res.end((0, _oauth.getErrorTemplate)('Invalid request'));
+                                args.onError(new Error('Invalid request: missing URL'));
+                                return [
+                                    2
+                                ];
+                            }
+                            // Use loopback base for URL parsing (port is not important for parsing path/query)
+                            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 [
+                                    2
+                                ];
+                            }
+                            code = url.searchParams.get('code');
+                            error = url.searchParams.get('error');
+                            state = url.searchParams.get('state');
+                            if (error) {
+                                res.writeHead(400, {
+                                    'Content-Type': 'text/html'
+                                });
+                                res.end((0, _oauth.getErrorTemplate)(error));
+                                args.onError(new Error("OAuth error: ".concat(error)));
+                                return [
+                                    2
+                                ];
+                            }
+                            if (!code) {
+                                res.writeHead(400, {
+                                    'Content-Type': 'text/html'
+                                });
+                                res.end((0, _oauth.getErrorTemplate)('No authorization code received'));
+                                args.onError(new Error('No authorization code received'));
+                                return [
+                                    2
+                                ];
+                            }
+                            if (!state) {
+                                res.writeHead(400, {
+                                    'Content-Type': 'text/html'
+                                });
+                                res.end((0, _oauth.getErrorTemplate)('Missing state parameter in OAuth callback'));
+                                args.onError(new Error('Missing state parameter in OAuth callback'));
+                                return [
+                                    2
+                                ];
+                            }
+                            _state.label = 1;
+                        case 1:
+                            _state.trys.push([
+                                1,
+                                3,
+                                ,
+                                4
+                            ]);
+                            return [
+                                4,
+                                this.processOAuthCallback({
+                                    code: code,
+                                    state: state,
+                                    redirectUri: args.finalRedirectUri()
+                                })
+                            ];
+                        case 2:
+                            _state.sent();
+                            res.writeHead(200, {
+                                'Content-Type': 'text/html'
+                            });
+                            res.end((0, _oauth.getSuccessTemplate)());
+                            args.onDone();
+                            return [
+                                3,
+                                4
+                            ];
+                        case 3:
+                            exchangeError = _state.sent();
+                            logger.error('Token exchange failed', {
+                                error: _instanceof(exchangeError, Error) ? exchangeError.message : String(exchangeError)
+                            });
+                            res.writeHead(500, {
+                                'Content-Type': 'text/html'
+                            });
+                            res.end((0, _oauth.getErrorTemplate)('Token exchange failed'));
+                            args.onError(exchangeError);
+                            return [
+                                3,
+                                4
+                            ];
+                        case 4:
+                            return [
+                                3,
+                                6
+                            ];
+                        case 5:
+                            outerError = _state.sent();
+                            logger.error('OAuth callback server error', {
+                                error: _instanceof(outerError, Error) ? outerError.message : String(outerError)
+                            });
+                            res.writeHead(500, {
+                                'Content-Type': 'text/html'
+                            });
+                            res.end((0, _oauth.getErrorTemplate)('Internal server error'));
+                            args.onError(outerError);
+                            return [
+                                3,
+                                6
+                            ];
+                        case 6:
+                            return [
+                                2
+                            ];
+                    }
+                });
+            }).call(_this);
+        });
+    };
+    /**
+   * Starts the ephemeral loopback server and returns an AuthRequiredError(auth_url).
+   * Middleware will open+poll and then retry in the same call.
+   */ _proto.startEphemeralOAuthFlow = function startEphemeralOAuthFlow() {
+        return _async_to_generator(function() {
+            var _this, _this_config, headless, logger, configRedirectUri, service, tokenStore, listenHost, listenPort, callbackPath, useConfiguredUri, parsed, isLoopback, envPort, _generatePKCE, codeVerifier, codeChallenge, stateId, server, serverPort, finalRedirectUri, authUrl;
+            return _ts_generator(this, function(_state) {
+                switch(_state.label){
+                    case 0:
+                        _this = this;
+                        _this_config = this.config, headless = _this_config.headless, logger = _this_config.logger, configRedirectUri = _this_config.redirectUri, service = _this_config.service, tokenStore = _this_config.tokenStore;
+                        // Server listen configuration (where ephemeral server binds)
+                        listenHost = 'localhost'; // Default: localhost for ephemeral loopback
+                        listenPort = 0; // Default: OS-assigned ephemeral port
+                        // Redirect URI configuration (what goes in auth URL and token exchange)
+                        callbackPath = '/callback'; // Default callback path
+                        useConfiguredUri = false;
+                        if (configRedirectUri) {
+                            try {
+                                parsed = new URL(configRedirectUri);
+                                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 {
+                                    // 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';
+                                    envPort = process.env.PORT ? Number.parseInt(process.env.PORT, 10) : undefined;
+                                    listenPort = envPort && Number.isFinite(envPort) ? envPort : 8080;
+                                }
+                                // Extract callback path from URL
+                                if (parsed.pathname && parsed.pathname !== '/') {
+                                    callbackPath = parsed.pathname;
+                                }
+                                useConfiguredUri = true;
+                                logger.debug('Using configured redirect URI', {
+                                    listenHost: listenHost,
+                                    listenPort: listenPort,
+                                    callbackPath: callbackPath,
+                                    redirectUri: configRedirectUri,
+                                    isLoopback: isLoopback
+                                });
+                            } catch (error) {
+                                logger.warn('Failed to parse redirectUri, using ephemeral defaults', {
+                                    redirectUri: configRedirectUri,
+                                    error: _instanceof(error, Error) ? error.message : String(error)
+                                });
+                            // Continue with defaults (localhost, port 0, http, /callback)
+                            }
+                        }
+                        // Generate PKCE challenge + state
+                        _generatePKCE = (0, _oauth.generatePKCE)(), codeVerifier = _generatePKCE.verifier, codeChallenge = _generatePKCE.challenge;
+                        stateId = (0, _crypto.randomUUID)();
+                        // Store PKCE verifier for callback (5 minute TTL)
                         return [
                             4,
-                            (0, _oauth.setAccountInfo)(tokenStore, {
-                                service: service,
-                                accountId: email
-                            }, {
-                                email: email,
-                                addedAt: new Date().toISOString()
+                            this.createPendingAuth({
+                                state: stateId,
+                                codeVerifier: codeVerifier
                             })
                         ];
-                    case 12:
+                    case 1:
                         _state.sent();
-                        // Clean up pending auth
+                        server = null;
+                        // Create ephemeral server with OS-assigned port (RFC 8252)
+                        server = this.createOAuthCallbackServer({
+                            callbackPath: callbackPath,
+                            finalRedirectUri: function() {
+                                return finalRedirectUri;
+                            },
+                            onDone: function() {
+                                server === null || server === void 0 ? void 0 : server.close();
+                            },
+                            onError: function(err) {
+                                logger.error('Ephemeral OAuth server error', {
+                                    error: _instanceof(err, Error) ? err.message : String(err)
+                                });
+                                server === null || server === void 0 ? void 0 : server.close();
+                            }
+                        });
+                        // Start listening
                         return [
                             4,
-                            tokenStore.delete(pendingKey)
+                            new Promise(function(resolve, reject) {
+                                server === null || server === void 0 ? void 0 : server.listen(listenPort, listenHost, function() {
+                                    var 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) {
+                                        finalRedirectUri = configRedirectUri;
+                                    } else {
+                                        finalRedirectUri = "http://localhost:".concat(serverPort).concat(callbackPath);
+                                    }
+                                    logger.info('Ephemeral OAuth server started', {
+                                        port: serverPort,
+                                        headless: headless,
+                                        service: service
+                                    });
+                                    resolve();
+                                });
+                            })
                         ];
-                    case 13:
+                    case 2:
                         _state.sent();
-                        logger.info('OAuth callback completed', {
-                            service: service,
-                            email: email
+                        // Timeout after 5 minutes (match middleware polling timeout)
+                        setTimeout(function() {
+                            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
+                        authUrl = this.buildAuthUrl({
+                            redirectUri: finalRedirectUri,
+                            codeChallenge: codeChallenge,
+                            state: stateId
                         });
                         return [
                             2,
                             {
-                                email: email,
-                                token: cachedToken
+                                kind: 'auth_url',
+                                provider: service,
+                                url: authUrl
                             }
                         ];
                 }
             });
         }).call(this);
     };
+    _proto.exchangeCodeForToken = function exchangeCodeForToken(code, codeVerifier, redirectUri) {
+        return _async_to_generator(function() {
+            var _this_config, clientId, clientSecret, tokenUrl, params, body, response, errorText;
+            return _ts_generator(this, function(_state) {
+                switch(_state.label){
+                    case 0:
+                        _this_config = this.config, clientId = _this_config.clientId, clientSecret = _this_config.clientSecret;
+                        tokenUrl = 'https://oauth2.googleapis.com/token';
+                        params = {
+                            code: code,
+                            client_id: clientId,
+                            redirect_uri: redirectUri,
+                            grant_type: 'authorization_code',
+                            code_verifier: codeVerifier
+                        };
+                        if (clientSecret) {
+                            params.client_secret = clientSecret;
+                        }
+                        body = new URLSearchParams(params);
+                        return [
+                            4,
+                            fetch(tokenUrl, {
+                                method: 'POST',
+                                headers: {
+                                    'Content-Type': 'application/x-www-form-urlencoded'
+                                },
+                                body: body.toString()
+                            })
+                        ];
+                    case 1:
+                        response = _state.sent();
+                        if (!!response.ok) return [
+                            3,
+                            3
+                        ];
+                        return [
+                            4,
+                            response.text()
+                        ];
+                    case 2:
+                        errorText = _state.sent();
+                        throw new Error("Token exchange failed: ".concat(response.status, " ").concat(errorText));
+                    case 3:
+                        return [
+                            4,
+                            response.json()
+                        ];
+                    case 4:
+                        return [
+                            2,
+                            _state.sent()
+                        ];
+                }
+            });
+        }).call(this);
+    };
+    _proto.refreshAccessToken = function refreshAccessToken(refreshToken) {
+        return _async_to_generator(function() {
+            var _this_config, clientId, clientSecret, tokenUrl, params, body, response, errorText, tokenResponse;
+            return _ts_generator(this, function(_state) {
+                switch(_state.label){
+                    case 0:
+                        _this_config = this.config, clientId = _this_config.clientId, clientSecret = _this_config.clientSecret;
+                        tokenUrl = 'https://oauth2.googleapis.com/token';
+                        params = {
+                            refresh_token: refreshToken,
+                            client_id: clientId,
+                            grant_type: 'refresh_token'
+                        };
+                        if (clientSecret) {
+                            params.client_secret = clientSecret;
+                        }
+                        body = new URLSearchParams(params);
+                        return [
+                            4,
+                            fetch(tokenUrl, {
+                                method: 'POST',
+                                headers: {
+                                    'Content-Type': 'application/x-www-form-urlencoded'
+                                },
+                                body: body.toString()
+                            })
+                        ];
+                    case 1:
+                        response = _state.sent();
+                        if (!!response.ok) return [
+                            3,
+                            3
+                        ];
+                        return [
+                            4,
+                            response.text()
+                        ];
+                    case 2:
+                        errorText = _state.sent();
+                        throw new Error("Token refresh failed: ".concat(response.status, " ").concat(errorText));
+                    case 3:
+                        return [
+                            4,
+                            response.json()
+                        ];
+                    case 4:
+                        tokenResponse = _state.sent();
+                        return [
+                            2,
+                            _object_spread({
+                                accessToken: tokenResponse.access_token,
+                                refreshToken: refreshToken
+                            }, tokenResponse.expires_in !== undefined && {
+                                expiresAt: Date.now() + tokenResponse.expires_in * 1000
+                            }, tokenResponse.scope !== undefined && {
+                                scope: tokenResponse.scope
+                            })
+                        ];
+                }
+            });
+        }).call(this);
+    };
+    /**
+   * Handle OAuth callback from persistent endpoint.
+   * Used by HTTP servers with configured redirectUri.
+   *
+   * @param params - OAuth callback parameters
+   * @returns Email and cached token
+   */ _proto.handleOAuthCallback = function handleOAuthCallback(params) {
+        return _async_to_generator(function() {
+            var code, state, redirectUri;
+            return _ts_generator(this, function(_state) {
+                switch(_state.label){
+                    case 0:
+                        code = params.code, state = params.state;
+                        redirectUri = this.config.redirectUri;
+                        if (!state) {
+                            throw new Error('Missing state parameter in OAuth callback');
+                        }
+                        if (!redirectUri) {
+                            throw new Error('handleOAuthCallback requires configured redirectUri');
+                        }
+                        return [
+                            4,
+                            this.processOAuthCallback({
+                                code: code,
+                                state: state,
+                                redirectUri: redirectUri
+                            })
+                        ];
+                    case 1:
+                        // Shared callback processor (same code path as ephemeral)
+                        return [
+                            2,
+                            _state.sent()
+                        ];
+                }
+            });
+        }).call(this);
+    };
     /**
    * Create authentication middleware for MCP tools, resources, and prompts
    *
@@ -1205,15 +1442,6 @@ var LoopbackOAuthProvider = /*#__PURE__*/ function() {
    * 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);
-   * ```
    */ _proto.authMiddleware = function authMiddleware() {
         var _this = this;
         var _this_config = this.config, service = _this_config.service, tokenStore = _this_config.tokenStore, logger = _this_config.logger;
@@ -1228,96 +1456,173 @@ var LoopbackOAuthProvider = /*#__PURE__*/ function() {
                     allArgs[_key] = arguments[_key];
                 }
                 return _async_to_generator(function() {
-                    var extra, accountId, _ref, _extra__meta, _tmp, error, effectiveAccountId, _tmp1, auth, error1, authRequiredResponse;
+                    var _this, extra, ensureAuthenticatedOrThrow, effectiveAccountId, auth, error, authRequiredResponse;
                     return _ts_generator(this, function(_state) {
                         switch(_state.label){
                             case 0:
+                                _this = this;
                                 // Extract extra from the correct position
                                 extra = allArgs[extraPosition];
+                                // Helper: retry once after open+poll completes
+                                ensureAuthenticatedOrThrow = function() {
+                                    return _async_to_generator(function() {
+                                        var accountId, _ref, _extra__meta, _tmp, error, effectiveAccountId, _tmp1, error1, authUrl, state;
+                                        return _ts_generator(this, function(_state) {
+                                            switch(_state.label){
+                                                case 0:
+                                                    _state.trys.push([
+                                                        0,
+                                                        11,
+                                                        ,
+                                                        16
+                                                    ]);
+                                                    _state.label = 1;
+                                                case 1:
+                                                    _state.trys.push([
+                                                        1,
+                                                        5,
+                                                        ,
+                                                        6
+                                                    ]);
+                                                    if (!((_ref = (_extra__meta = extra._meta) === null || _extra__meta === void 0 ? void 0 : _extra__meta.accountId) !== null && _ref !== void 0)) return [
+                                                        3,
+                                                        2
+                                                    ];
+                                                    _tmp = _ref;
+                                                    return [
+                                                        3,
+                                                        4
+                                                    ];
+                                                case 2:
+                                                    return [
+                                                        4,
+                                                        (0, _oauth.getActiveAccount)(tokenStore, {
+                                                            service: service
+                                                        })
+                                                    ];
+                                                case 3:
+                                                    _tmp = _state.sent();
+                                                    _state.label = 4;
+                                                case 4:
+                                                    accountId = _tmp;
+                                                    return [
+                                                        3,
+                                                        6
+                                                    ];
+                                                case 5:
+                                                    error = _state.sent();
+                                                    if (_instanceof(error, Error) && (error.code === 'REQUIRES_AUTHENTICATION' || error.name === 'AccountManagerError')) {
+                                                        accountId = undefined;
+                                                    } else {
+                                                        throw error;
+                                                    }
+                                                    return [
+                                                        3,
+                                                        6
+                                                    ];
+                                                case 6:
+                                                    return [
+                                                        4,
+                                                        this.getAccessToken(accountId)
+                                                    ];
+                                                case 7:
+                                                    _state.sent();
+                                                    if (!(accountId !== null && accountId !== void 0)) return [
+                                                        3,
+                                                        8
+                                                    ];
+                                                    _tmp1 = accountId;
+                                                    return [
+                                                        3,
+                                                        10
+                                                    ];
+                                                case 8:
+                                                    return [
+                                                        4,
+                                                        (0, _oauth.getActiveAccount)(tokenStore, {
+                                                            service: service
+                                                        })
+                                                    ];
+                                                case 9:
+                                                    _tmp1 = _state.sent();
+                                                    _state.label = 10;
+                                                case 10:
+                                                    effectiveAccountId = _tmp1;
+                                                    if (!effectiveAccountId) {
+                                                        throw new Error("No account found after OAuth flow for service ".concat(service));
+                                                    }
+                                                    return [
+                                                        2,
+                                                        effectiveAccountId
+                                                    ];
+                                                case 11:
+                                                    error1 = _state.sent();
+                                                    if (!(_instanceof(error1, _typests.AuthRequiredError) && error1.descriptor.kind === 'auth_url')) return [
+                                                        3,
+                                                        15
+                                                    ];
+                                                    // Headless: don't open/poll; just propagate to outer handler to return auth_required.
+                                                    if (this.config.headless) throw error1;
+                                                    // Non-headless: open once + poll until callback completes, then retry token acquisition.
+                                                    authUrl = new URL(error1.descriptor.url);
+                                                    state = authUrl.searchParams.get('state');
+                                                    if (!state) throw new Error('Auth URL missing state parameter');
+                                                    if (!this.openedStates.has(state)) {
+                                                        this.openedStates.add(state);
+                                                        (0, _open.default)(error1.descriptor.url).catch(function(e) {
+                                                            logger.info('Failed to open browser automatically', {
+                                                                error: _instanceof(e, Error) ? e.message : String(e)
+                                                            });
+                                                        });
+                                                    }
+                                                    // Block until callback completes (or timeout)
+                                                    return [
+                                                        4,
+                                                        this.waitForOAuthCompletion(state)
+                                                    ];
+                                                case 12:
+                                                    _state.sent();
+                                                    // Cleanup pending state after we observe completion
+                                                    return [
+                                                        4,
+                                                        this.deletePendingAuth(state)
+                                                    ];
+                                                case 13:
+                                                    _state.sent();
+                                                    return [
+                                                        4,
+                                                        ensureAuthenticatedOrThrow()
+                                                    ];
+                                                case 14:
+                                                    // Retry after completion
+                                                    return [
+                                                        2,
+                                                        _state.sent()
+                                                    ];
+                                                case 15:
+                                                    throw error1;
+                                                case 16:
+                                                    return [
+                                                        2
+                                                    ];
+                                            }
+                                        });
+                                    }).call(_this);
+                                };
                                 _state.label = 1;
                             case 1:
                                 _state.trys.push([
                                     1,
-                                    13,
-                                    ,
-                                    14
-                                ]);
-                                _state.label = 2;
-                            case 2:
-                                _state.trys.push([
-                                    2,
-                                    6,
+                                    4,
                                     ,
-                                    7
-                                ]);
-                                if (!((_ref = (_extra__meta = extra._meta) === null || _extra__meta === void 0 ? void 0 : _extra__meta.accountId) !== null && _ref !== void 0)) return [
-                                    3,
-                                    3
-                                ];
-                                _tmp = _ref;
-                                return [
-                                    3,
                                     5
-                                ];
-                            case 3:
-                                return [
-                                    4,
-                                    (0, _oauth.getActiveAccount)(tokenStore, {
-                                        service: service
-                                    })
-                                ];
-                            case 4:
-                                _tmp = _state.sent();
-                                _state.label = 5;
-                            case 5:
-                                accountId = _tmp;
-                                return [
-                                    3,
-                                    7
-                                ];
-                            case 6:
-                                error = _state.sent();
-                                if (_instanceof(error, Error) && (error.code === 'REQUIRES_AUTHENTICATION' || error.name === 'AccountManagerError')) {
-                                    accountId = undefined;
-                                } else {
-                                    throw error;
-                                }
-                                return [
-                                    3,
-                                    7
-                                ];
-                            case 7:
-                                // Eagerly validate token exists or trigger OAuth flow
-                                return [
-                                    4,
-                                    this.getAccessToken(accountId)
-                                ];
-                            case 8:
-                                _state.sent();
-                                if (!(accountId !== null && accountId !== void 0)) return [
-                                    3,
-                                    9
-                                ];
-                                _tmp1 = accountId;
-                                return [
-                                    3,
-                                    11
-                                ];
-                            case 9:
+                                ]);
                                 return [
                                     4,
-                                    (0, _oauth.getActiveAccount)(tokenStore, {
-                                        service: service
-                                    })
+                                    ensureAuthenticatedOrThrow()
                                 ];
-                            case 10:
-                                _tmp1 = _state.sent();
-                                _state.label = 11;
-                            case 11:
-                                effectiveAccountId = _tmp1;
-                                if (!effectiveAccountId) {
-                                    throw new Error("No account found after OAuth flow for service ".concat(service));
-                                }
+                            case 2:
+                                effectiveAccountId = _state.sent();
                                 auth = this.toAuth(effectiveAccountId);
                                 // Inject authContext and logger into extra
                                 extra.authContext = {
@@ -1329,27 +1634,25 @@ var LoopbackOAuthProvider = /*#__PURE__*/ function() {
                                     4,
                                     originalHandler.apply(void 0, _to_consumable_array(allArgs))
                                 ];
-                            case 12:
+                            case 3:
                                 // Call original handler with all args
                                 return [
                                     2,
                                     _state.sent()
                                 ];
-                            case 13:
-                                error1 = _state.sent();
-                                if (_instanceof(error1, _typests.AuthRequiredError)) {
+                            case 4:
+                                error = _state.sent();
+                                if (_instanceof(error, _typests.AuthRequiredError)) {
                                     logger.info('Authentication required', {
                                         service: service,
                                         tool: operation,
-                                        descriptor: error1.descriptor
+                                        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
                                     authRequiredResponse = {
                                         type: 'auth_required',
                                         provider: service,
                                         message: "Authentication required for ".concat(operation, ". Please authenticate with ").concat(service, "."),
-                                        url: error1.descriptor.kind === 'auth_url' ? error1.descriptor.url : undefined
+                                        url: error.descriptor.kind === 'auth_url' ? error.descriptor.url : undefined
                                     };
                                     return [
                                         2,
@@ -1368,8 +1671,8 @@ var LoopbackOAuthProvider = /*#__PURE__*/ function() {
                                         }
                                     ];
                                 }
-                                throw error1;
-                            case 14:
+                                throw error;
+                            case 5:
                                 return [
                                     2
                                 ];