@mcp-abap-adt/auth-providers 1.1.0 → 1.2.0

package/dist/auth/callbackServer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Scoped callback servers for interactive authorization flows.
+ *
+ * One owner, one release point. The socket belongs to the scope, not to the
+ * promise a caller happens to be awaiting: it is released on the first terminal
+ * outcome — the body returning or throwing, an explicit failure, the timeout, or
+ * an abort — and the factory settles only once it is actually free.
+ *
+ * See `docs/superpowers/specs/2026-07-28-callback-server-contract-design.md`.
+ */
+import type { CallbackServerFactory, ICallbackServerHandle, ICallbackServerOptions } from '@mcp-abap-adt/interfaces';
+import express from 'express';
+/**
+ * How a route reports an outcome. Settling is deferred until the response has
+ * actually flushed — `res.send()` returning does not mean the bytes have left,
+ * and settling earlier races the shutdown against the page being delivered.
+ */
+export interface Settle<TResult> {
+    /** The callback delivered a result. Does not end the scope by itself. */
+    ok(value: TResult, res?: express.Response): void;
+    /** The callback reported a failure. Ends the scope. */
+    err(error: Error, res?: express.Response): void;
+}
+export type RouteSetup<TResult> = (app: express.Express, settle: Settle<TResult>) => void;
+/**
+ * Owns the socket for the duration of `use`.
+ *
+ * Every flow registers its routes through `routes` and reports outcomes through
+ * `settle`; nothing else touches the internal promise, which is what keeps the
+ * "settles exactly once" guarantee in one place.
+ */
+export declare function runCallbackScope<TResult, TReturn>(options: ICallbackServerOptions, routes: RouteSetup<TResult>, use: (server: ICallbackServerHandle<TResult>) => Promise<TReturn>): Promise<TReturn>;
+/**
+ * Callback server for the UAA authorization-code flow.
+ *
+ * Delivers the authorization code. The paste form and `/submit` are kept for
+ * the case where the browser runs on another machine.
+ */
+export declare const withBrowserCallbackServer: CallbackServerFactory<string>;
+//# sourceMappingURL=callbackServer.d.ts.map

package/dist/auth/callbackServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callbackServer.d.ts","sourceRoot":"","sources":["../../src/auth/callbackServer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EACV,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,OAAO,MAAM,SAAS,CAAC;AAS9B;;;;GAIG;AACH,MAAM,WAAW,MAAM,CAAC,OAAO;IAC7B,yEAAyE;IACzE,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IACjD,uDAAuD;IACvD,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,EAAE,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;CACjD;AAED,MAAM,MAAM,UAAU,CAAC,OAAO,IAAI,CAChC,GAAG,EAAE,OAAO,CAAC,OAAO,EACpB,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,KACpB,IAAI,CAAC;AAqBV;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EACrD,OAAO,EAAE,sBAAsB,EAC/B,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,EAC3B,GAAG,EAAE,CAAC,MAAM,EAAE,qBAAqB,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAChE,OAAO,CAAC,OAAO,CAAC,CAuLlB;AAyCD;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,qBAAqB,CAAC,MAAM,CA4DjE,CAAC"}

package/dist/auth/callbackServer.js

@@ -0,0 +1,322 @@
+"use strict";
+/**
+ * Scoped callback servers for interactive authorization flows.
+ *
+ * One owner, one release point. The socket belongs to the scope, not to the
+ * promise a caller happens to be awaiting: it is released on the first terminal
+ * outcome — the body returning or throwing, an explicit failure, the timeout, or
+ * an abort — and the factory settles only once it is actually free.
+ *
+ * See `docs/superpowers/specs/2026-07-28-callback-server-contract-design.md`.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withBrowserCallbackServer = void 0;
+exports.runCallbackScope = runCallbackScope;
+const http = __importStar(require("node:http"));
+const express_1 = __importDefault(require("express"));
+const browserAuth_1 = require("./browserAuth");
+/** Node's `setTimeout` takes a 32-bit signed delay; above this it fires in 1 ms. */
+const MAX_TIMEOUT_MS = 2_147_483_647;
+/** How long shutdown waits for `close` before destroying what is left. */
+const SHUTDOWN_GRACE_MS = 500;
+function validate(options) {
+    const { port, timeoutMs } = options;
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`Invalid callback server port: ${String(port)}. Must be an integer in 1..65535.`);
+    }
+    if (!Number.isFinite(timeoutMs) ||
+        timeoutMs <= 0 ||
+        timeoutMs > MAX_TIMEOUT_MS) {
+        throw new Error(`Invalid callback server timeoutMs: ${String(timeoutMs)}. ` +
+            `Must be finite and within 1..${MAX_TIMEOUT_MS}.`);
+    }
+}
+/**
+ * Owns the socket for the duration of `use`.
+ *
+ * Every flow registers its routes through `routes` and reports outcomes through
+ * `settle`; nothing else touches the internal promise, which is what keeps the
+ * "settles exactly once" guarantee in one place.
+ */
+async function runCallbackScope(options, routes, use) {
+    validate(options);
+    if (options.signal?.aborted) {
+        throw new Error('Callback server aborted before it started');
+    }
+    const app = (0, express_1.default)();
+    const server = http.createServer(app);
+    const sockets = new Set();
+    server.on('connection', (socket) => {
+        sockets.add(socket);
+        socket.on('close', () => sockets.delete(socket));
+    });
+    let resultSettled = false;
+    let resolveResult;
+    let rejectResult;
+    const resultPromise = new Promise((res, rej) => {
+        resolveResult = res;
+        rejectResult = rej;
+    });
+    // Marked handled at creation: a body may create this promise and walk away,
+    // and rejecting it at scope end would otherwise raise unhandledRejection.
+    void resultPromise.catch(() => undefined);
+    let scopeSettled = false;
+    let resolveScope;
+    let rejectScope;
+    const scopePromise = new Promise((res, rej) => {
+        resolveScope = res;
+        rejectScope = rej;
+    });
+    let timer = null;
+    let alive = false;
+    const settleResult = (outcome) => {
+        if (resultSettled)
+            return;
+        resultSettled = true;
+        if ('value' in outcome)
+            resolveResult(outcome.value);
+        else
+            rejectResult(outcome.error);
+    };
+    /** The one place a scope ends. Everything after the first call is a no-op. */
+    const endScope = (outcome) => {
+        if (scopeSettled)
+            return;
+        scopeSettled = true;
+        alive = false;
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        options.signal?.removeEventListener('abort', onAbort);
+        settleResult({
+            error: new Error('Callback server closed before a result arrived'),
+        });
+        void shutdown().then(() => {
+            if ('value' in outcome)
+                resolveScope(outcome.value);
+            else
+                rejectScope(outcome.error);
+        });
+    };
+    function onAbort() {
+        endScope({ error: new Error('Callback server aborted') });
+    }
+    /**
+     * Stop accepting, end idle connections, wait for `close` under a grace, then
+     * destroy whatever is left. `closeAllConnections()` is deliberately not used
+     * in the first step: it destroys active connections too, and the one carrying
+     * the success page is active.
+     */
+    function shutdown() {
+        return new Promise((done) => {
+            let finished = false;
+            const finish = () => {
+                if (finished)
+                    return;
+                finished = true;
+                done();
+            };
+            // `close()` alone, first. From Node 19 it ends idle connections itself,
+            // and it does so gracefully — the client still reads what was written.
+            // `closeIdleConnections()` destroys instead, which cuts the success page
+            // off mid-read: `finish` on the response means "handed to the OS", not
+            // "read by the client".
+            server.close(() => finish());
+            setTimeout(() => {
+                if (finished)
+                    return;
+                // Grace expired — on Node 18.x `close()` does not end idle connections,
+                // and an active one may simply be stuck. Force it, bounded.
+                server.closeIdleConnections?.();
+                server.closeAllConnections?.();
+                for (const socket of sockets)
+                    socket.destroy();
+                finish();
+            }, SHUTDOWN_GRACE_MS).unref?.();
+        });
+    }
+    /**
+     * Settle only once the response has actually flushed, so shutdown cannot cut
+     * it off.
+     *
+     * The check is `writableFinished`, not `writableEnded`: the latter is true as
+     * soon as `end()` has been called and says nothing about the data having
+     * left. Measured on Node 25 with a paused client — an 800-byte body reports
+     * both flags true at once, but a 20 MB body reports `writableEnded` true and
+     * `writableFinished` false, with `finish` arriving 456 ms later. Keying off
+     * `writableEnded` therefore made this deferral a no-op on the very path it
+     * exists for.
+     */
+    const afterFlush = (res, then) => {
+        if (!res || res.writableFinished) {
+            then();
+            return;
+        }
+        res.once('finish', then);
+        res.once('close', then);
+    };
+    const settle = {
+        ok(value, res) {
+            afterFlush(res, () => settleResult({ value }));
+        },
+        err(error, res) {
+            afterFlush(res, () => {
+                settleResult({ error });
+                endScope({ error });
+            });
+        },
+    };
+    routes(app, settle);
+    options.signal?.addEventListener('abort', onAbort, { once: true });
+    const handle = {
+        port: options.port,
+        redirectUri: `http://localhost:${options.port}/callback`,
+        waitForResult: () => alive
+            ? resultPromise
+            : Promise.reject(new Error('Callback server scope has ended')),
+        // Silent no-op once the scope has ended: this is called fire-and-forget
+        // from a browser launcher's .catch(), and a late rejection must not become
+        // a fresh unhandled rejection.
+        fail: (error) => {
+            if (!alive)
+                return;
+            settleResult({ error });
+            endScope({ error });
+        },
+    };
+    server.once('error', (error) => {
+        endScope({ error });
+    });
+    server.listen(options.port, () => {
+        if (scopeSettled) {
+            // Aborted while binding.
+            void shutdown();
+            return;
+        }
+        alive = true;
+        timer = setTimeout(() => {
+            endScope({
+                error: new Error(`Authentication timeout after ${options.timeoutMs / 1000} seconds. Please try again.`),
+            });
+        }, options.timeoutMs);
+        void use(handle).then((value) => endScope({ value }), (error) => endScope({ error }));
+    });
+    return await scopePromise;
+}
+const successHtml = `<!DOCTYPE html>
+<html lang="en"><head><meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>SAP BTP Authentication</title>
+<style>body{font-family:'Segoe UI',Tahoma,sans-serif;text-align:center;padding:50px 20px;background:linear-gradient(135deg,#0070f3,#00d4ff);color:#fff;min-height:100vh;display:flex;flex-direction:column;justify-content:center;align-items:center}.container{background:rgba(255,255,255,.1);border-radius:20px;padding:40px;max-width:500px}.success-icon{font-size:4rem;margin-bottom:20px;color:#4ade80}h1{font-weight:300}</style>
+</head><body><div class="container"><div class="success-icon">✓</div>
+<h1>Authentication Successful!</h1>
+<p>You have successfully authenticated with SAP BTP. You can close this window.</p>
+</div></body></html>`;
+const errorHtml = (message) => `<!DOCTYPE html>
+<html lang="en"><head><meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Authentication Error</title>
+<style>body{font-family:'Segoe UI',Tahoma,sans-serif;text-align:center;padding:50px 20px;background:linear-gradient(135deg,#dc2626,#ef4444);color:#fff;min-height:100vh;display:flex;flex-direction:column;justify-content:center;align-items:center}.container{background:rgba(255,255,255,.1);border-radius:20px;padding:40px;max-width:500px}.error-icon{font-size:4rem;margin-bottom:20px;color:#fbbf24}h1{font-weight:300}</style>
+</head><body><div class="container"><div class="error-icon">✗</div>
+<h1>Authentication Failed</h1>
+<p>${message}</p>
+<p>Please check your service key configuration and try again.</p>
+</div></body></html>`;
+// Manual paste form (GET /). Used when the automatic localhost callback cannot
+// reach this server (browser on another machine). Accepts a bare code or a full
+// redirected URL; re-renders with a message on a bad paste.
+const pasteFormHtml = (message) => `<!DOCTYPE html>
+<html lang="en"><head><meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>SAP BTP Authentication — paste code</title>
+<style>body{font-family:'Segoe UI',Tahoma,sans-serif;text-align:center;padding:50px 20px;background:linear-gradient(135deg,#0070f3,#00d4ff);color:#fff;min-height:100vh;display:flex;flex-direction:column;justify-content:center;align-items:center}.container{background:rgba(255,255,255,.1);border-radius:20px;padding:40px;max-width:560px;width:100%}h1{font-weight:300}input{width:100%;padding:12px;border-radius:8px;border:none;font-size:1rem;box-sizing:border-box;margin:14px 0}button{padding:12px 24px;border-radius:8px;border:none;background:#fff;color:#0070f3;font-size:1rem;cursor:pointer}.msg{color:#fde68a;margin-bottom:10px}</style>
+</head><body><div class="container">
+<h1>Paste authorization code</h1>
+${message ? `<p class="msg">${message}</p>` : ''}
+<p>After signing in, copy the <code>code</code> from your browser's address bar
+(or paste the whole redirected URL) and submit it here.</p>
+<form action="/submit" method="get">
+<input name="input" autofocus placeholder="code=... or http://localhost/callback?code=..." />
+<button type="submit">Submit</button>
+</form></div></body></html>`;
+/**
+ * Callback server for the UAA authorization-code flow.
+ *
+ * Delivers the authorization code. The paste form and `/submit` are kept for
+ * the case where the browser runs on another machine.
+ */
+const withBrowserCallbackServer = (options, use) => runCallbackScope(options, (app, settle) => {
+    app.get('/callback', (req, res) => {
+        const { error, error_description, error_uri } = req.query;
+        if (error) {
+            const message = error_description
+                ? `${String(error)}: ${String(error_description)}`
+                : String(error);
+            res.status(400).send(errorHtml(message));
+            settle.err(new Error(`OAuth2 authentication failed: ${message}` +
+                (error_uri ? ` (${String(error_uri)})` : '')), res);
+            return;
+        }
+        const { code } = req.query;
+        if (!code || typeof code !== 'string') {
+            res.status(400).send('Error: Authorization code missing');
+            settle.err(new Error('Authorization code missing'), res);
+            return;
+        }
+        res.send(successHtml);
+        settle.ok(code, res);
+    });
+    app.get('/', (_req, res) => {
+        res.send(pasteFormHtml());
+    });
+    app.get('/submit', (req, res) => {
+        const raw = req.query.input ?? req.query.code;
+        const code = typeof raw === 'string' ? (0, browserAuth_1.extractCode)(raw) : null;
+        if (!code) {
+            res
+                .status(400)
+                .send(pasteFormHtml('Could not read an authorization code from that input. Try again.'));
+            return;
+        }
+        res.send(successHtml);
+        settle.ok(code, res);
+    });
+}, use);
+exports.withBrowserCallbackServer = withBrowserCallbackServer;

package/dist/auth/oidcBrowserAuth.d.ts

@@ -2,8 +2,16 @@
  * OIDC browser authorization code flow (capture code)
  */
 import type { ILogger } from '@mcp-abap-adt/interfaces';
-export declare function startOidcBrowserAuth(authorizationUrl: string, browser: string, logger?: ILogger, port?: number): Promise<{
+export interface OidcCallbackResult {
     code: string;
     state?: string;
-}>;
+}
+/**
+ * OIDC browser login.
+ *
+ * The callback socket belongs to the scope: it is released when the scope ends,
+ * whatever ends it. Before this, the flow had no timeout at all — an abandoned
+ * login never settled and the port was held for the life of the process.
+ */
+export declare function startOidcBrowserAuth(authorizationUrl: string, browser: string, logger?: ILogger, port?: number, timeoutMs?: number): Promise<OidcCallbackResult>;
 //# sourceMappingURL=oidcBrowserAuth.d.ts.map

package/dist/auth/oidcBrowserAuth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oidcBrowserAuth.d.ts","sourceRoot":"","sources":["../../src/auth/oidcBrowserAuth.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAqExD,wBAAsB,oBAAoB,CACxC,gBAAgB,EAAE,MAAM,EACxB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,OAAO,EAChB,IAAI,GAAE,MAAa,GAClB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA2C3C"}
+{"version":3,"file":"oidcBrowserAuth.d.ts","sourceRoot":"","sources":["../../src/auth/oidcBrowserAuth.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAIV,OAAO,EACR,MAAM,0BAA0B,CAAC;AAqElC,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA+BD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,gBAAgB,EAAE,MAAM,EACxB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,OAAO,EAChB,IAAI,GAAE,MAAa,EACnB,SAAS,GAAE,MAAkB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CAyB7B"}

package/dist/auth/oidcBrowserAuth.js

@@ -35,14 +35,10 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.startOidcBrowserAuth = startOidcBrowserAuth;
-const http = __importStar(require("node:http"));
 const net = __importStar(require("node:net"));
-const express_1 = __importDefault(require("express"));
+const callbackServer_1 = require("./callbackServer");
 const BROWSER_MAP = {
     chrome: 'chrome',
     edge: 'msedge',
@@ -103,42 +99,46 @@ async function openBrowserUrl(authorizationUrl, browser, logger) {
         logger?.info('[OIDC] Open URL manually', { authorizationUrl });
     }
 }
-async function startOidcBrowserAuth(authorizationUrl, browser, logger, port = 3001) {
+const withOidcCallbackServer = (options, use) => (0, callbackServer_1.runCallbackScope)(options, (app, settle) => {
+    app.get('/callback', (req, res) => {
+        const code = req.query.code;
+        const state = req.query.state;
+        if (!code || typeof code !== 'string') {
+            res.status(400).send('Missing authorization code');
+            settle.err(new Error('Missing authorization code'), res);
+            return;
+        }
+        res
+            .status(200)
+            .send('Authentication complete. You can close this window.');
+        settle.ok({ code, state: typeof state === 'string' ? state : undefined }, res);
+    });
+}, use);
+/**
+ * OIDC browser login.
+ *
+ * The callback socket belongs to the scope: it is released when the scope ends,
+ * whatever ends it. Before this, the flow had no timeout at all — an abandoned
+ * login never settled and the port was held for the life of the process.
+ */
+async function startOidcBrowserAuth(authorizationUrl, browser, logger, port = 3001, timeoutMs = 30 * 1000) {
+    // Pre-check kept for its message: AuthBroker matches /already in use/i to
+    // distinguish a busy port from other failures.
     const portAvailable = await isPortAvailable(port);
     if (!portAvailable) {
         throw new Error(`Port ${port} is already in use. Please specify a different port or free the port.`);
     }
-    return new Promise((resolve, reject) => {
-        const app = (0, express_1.default)();
-        const server = http.createServer(app);
-        server.keepAliveTimeout = 0;
-        server.headersTimeout = 0;
-        const PORT = port;
-        let resolved = false;
-        const cleanup = () => {
-            if (resolved)
-                return;
-            resolved = true;
-            server.close();
-        };
-        app.get('/callback', (req, res) => {
-            const code = req.query.code;
-            const state = req.query.state;
-            if (!code || typeof code !== 'string') {
-                res.status(400).send('Missing authorization code');
-                cleanup();
-                reject(new Error('Missing authorization code'));
-                return;
-            }
-            res
-                .status(200)
-                .send('Authentication complete. You can close this window.');
-            cleanup();
-            resolve({ code, state: typeof state === 'string' ? state : undefined });
-        });
-        server.listen(PORT, async () => {
-            logger?.info('[OIDC] Callback server listening', { port: PORT });
-            await openBrowserUrl(authorizationUrl, browser, logger);
+    return await withOidcCallbackServer({ port, timeoutMs }, async (server) => {
+        logger?.info('[OIDC] Callback server listening', { port: server.port });
+        const waiting = server.waitForResult();
+        // Not awaited: a launcher that hangs must not delay the timeout or the
+        // release of the port.
+        void openBrowserUrl(authorizationUrl, browser, logger).catch((error) => {
+            logger?.warn('[OIDC] Failed to open browser', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            logger?.info('[OIDC] Open URL manually', { authorizationUrl });
         });
+        return await waiting;
     });
 }

package/dist/auth/saml2Auth.d.ts

@@ -10,6 +10,13 @@ export interface Saml2AuthConfig {
     authorizationUrl?: string;
 }
 export declare function buildSamlAuthorizationUrl(config: Saml2AuthConfig): string;
-export declare function startSamlBrowserAuth(config: Saml2AuthConfig, browser: string, logger?: ILogger, port?: number): Promise<string>;
+/**
+ * SAML browser login.
+ *
+ * The callback socket belongs to the scope: it is released when the scope ends,
+ * whatever ends it. Before this, the flow had no timeout at all — an abandoned
+ * login never settled and the port was held for the life of the process.
+ */
+export declare function startSamlBrowserAuth(config: Saml2AuthConfig, browser: string, logger?: ILogger, port?: number, timeoutMs?: number): Promise<string>;
 export declare function parseSamlNotOnOrAfter(samlResponse: string): number | undefined;
 //# sourceMappingURL=saml2Auth.d.ts.map

package/dist/auth/saml2Auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"saml2Auth.d.ts","sourceRoot":"","sources":["../../src/auth/saml2Auth.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAGxD,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AA8CD,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAazE;AA+CD,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,OAAO,EAChB,IAAI,GAAE,MAAa,GAClB,OAAO,CAAC,MAAM,CAAC,CA4DjB;AAED,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,GACnB,MAAM,GAAG,SAAS,CAYpB"}
+{"version":3,"file":"saml2Auth.d.ts","sourceRoot":"","sources":["../../src/auth/saml2Auth.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAIV,OAAO,EACR,MAAM,0BAA0B,CAAC;AAIlC,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AA8CD,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAazE;AA8ED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,OAAO,EAChB,IAAI,GAAE,MAAa,EACnB,SAAS,GAAE,MAAkB,GAC5B,OAAO,CAAC,MAAM,CAAC,CA2BjB;AAED,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,GACnB,MAAM,GAAG,SAAS,CAYpB"}

package/dist/auth/saml2Auth.js

@@ -43,10 +43,10 @@ exports.buildSamlAuthorizationUrl = buildSamlAuthorizationUrl;
 exports.startSamlBrowserAuth = startSamlBrowserAuth;
 exports.parseSamlNotOnOrAfter = parseSamlNotOnOrAfter;
 const node_crypto_1 = require("node:crypto");
-const http = __importStar(require("node:http"));
 const net = __importStar(require("node:net"));
 const node_zlib_1 = require("node:zlib");
 const express_1 = __importDefault(require("express"));
+const callbackServer_1 = require("./callbackServer");
 const BROWSER_MAP = {
     chrome: 'chrome',
     edge: 'msedge',
@@ -140,53 +140,53 @@ async function openBrowserUrl(authorizationUrl, browser, logger) {
         logger?.info('[SAML] Open URL manually', { authorizationUrl });
     }
 }
-async function startSamlBrowserAuth(config, browser, logger, port = 3001) {
+const withSamlCallbackServer = (options, use) => (0, callbackServer_1.runCallbackScope)(options, (app, settle) => {
+    app.use(express_1.default.urlencoded({ extended: false, limit: '5mb' }));
+    const handle = (samlResponse, res) => {
+        res
+            .status(200)
+            .send('SAML authentication complete. You can close this window.');
+        if (typeof samlResponse === 'string' && samlResponse) {
+            settle.ok(samlResponse, res);
+        }
+        else {
+            settle.err(new Error('Missing SAMLResponse'), res);
+        }
+    };
+    app.post('/callback', (req, res) => {
+        handle(req.body?.SAMLResponse, res);
+    });
+    app.get('/callback', (req, res) => {
+        handle(req.query.SAMLResponse, res);
+    });
+}, use);
+/**
+ * SAML browser login.
+ *
+ * The callback socket belongs to the scope: it is released when the scope ends,
+ * whatever ends it. Before this, the flow had no timeout at all — an abandoned
+ * login never settled and the port was held for the life of the process.
+ */
+async function startSamlBrowserAuth(config, browser, logger, port = 3001, timeoutMs = 30 * 1000) {
+    // Pre-check kept for its message: AuthBroker matches /already in use/i to
+    // distinguish a busy port from other failures.
     const portAvailable = await isPortAvailable(port);
     if (!portAvailable) {
         throw new Error(`Port ${port} is already in use. Please specify a different port or free the port.`);
     }
     const authorizationUrl = buildSamlAuthorizationUrl(config);
-    return new Promise((resolve, reject) => {
-        const app = (0, express_1.default)();
-        app.use(express_1.default.urlencoded({ extended: false, limit: '5mb' }));
-        const server = http.createServer(app);
-        server.keepAliveTimeout = 0;
-        server.headersTimeout = 0;
-        const PORT = port;
-        let resolved = false;
-        const cleanup = () => {
-            if (resolved)
-                return;
-            resolved = true;
-            server.close();
-        };
-        const handleResponse = (samlResponse) => {
-            if (!samlResponse) {
-                cleanup();
-                reject(new Error('Missing SAMLResponse'));
-                return;
-            }
-            cleanup();
-            resolve(samlResponse);
-        };
-        app.post('/callback', (req, res) => {
-            const samlResponse = req.body?.SAMLResponse;
-            res
-                .status(200)
-                .send('SAML authentication complete. You can close this window.');
-            handleResponse(typeof samlResponse === 'string' ? samlResponse : undefined);
-        });
-        app.get('/callback', (req, res) => {
-            const samlResponse = req.query.SAMLResponse;
-            res
-                .status(200)
-                .send('SAML authentication complete. You can close this window.');
-            handleResponse(typeof samlResponse === 'string' ? samlResponse : undefined);
-        });
-        server.listen(PORT, async () => {
-            logger?.info('[SAML] Callback server listening', { port: PORT });
-            await openBrowserUrl(authorizationUrl, browser, logger);
+    return await withSamlCallbackServer({ port, timeoutMs }, async (server) => {
+        logger?.info('[SAML] Callback server listening', { port: server.port });
+        const waiting = server.waitForResult();
+        // Not awaited: a launcher that hangs must not delay the timeout or the
+        // release of the port.
+        void openBrowserUrl(authorizationUrl, browser, logger).catch((error) => {
+            logger?.warn('[SAML] Failed to open browser', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            logger?.info('[SAML] Open URL manually', { authorizationUrl });
         });
+        return await waiting;
     });
 }
 function parseSamlNotOnOrAfter(samlResponse) {

package/dist/providers/AuthorizationCodeProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AuthorizationCodeProvider.d.ts","sourceRoot":"","sources":["../../src/providers/AuthorizationCodeProvider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAEV,OAAO,EACP,YAAY,EACZ,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAIlC,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,WAAW,+BAA+B;IAE9C,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IAGrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAG1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IAGtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IAGtB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,iBAAiB;IAC9D,OAAO,CAAC,MAAM,CAAkC;gBAEpC,MAAM,EAAE,+BAA+B;IA8D7C,SAAS,IAAI,OAAO,CAAC,YAAY,CAAC;IAIxC,SAAS,CAAC,WAAW,IAAI,eAAe;cAIxB,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC;cA2ErC,cAAc,IAAI,OAAO,CAAC,YAAY,CAAC;CA0CxD"}
+{"version":3,"file":"AuthorizationCodeProvider.d.ts","sourceRoot":"","sources":["../../src/providers/AuthorizationCodeProvider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAEV,OAAO,EACP,YAAY,EACZ,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAIlC,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAKxD,MAAM,WAAW,+BAA+B;IAE9C,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IAGrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAG1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IAGtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IAGtB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,iBAAiB;IAC9D,OAAO,CAAC,MAAM,CAAkC;gBAEpC,MAAM,EAAE,+BAA+B;IA8D7C,SAAS,IAAI,OAAO,CAAC,YAAY,CAAC;IAIxC,SAAS,CAAC,WAAW,IAAI,eAAe;cAIxB,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC;cAoErC,cAAc,IAAI,OAAO,CAAC,YAAY,CAAC;CA0CxD"}