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

package/bin/auth-authorization-code.ts

@@ -10,6 +10,7 @@ import {
   ABAP_CONNECTION_VARS,
 } from '@mcp-abap-adt/auth-stores';
 import { AuthorizationCodeProvider } from '../src/providers/AuthorizationCodeProvider';
+import { browserCallbackStrategy } from '../src/strategies';
 import {
   getUaaCredentials,
   parseEnvFile,
@@ -89,14 +90,15 @@ Example:
       authorizationUrl = `${uaaUrl}/oauth/authorize?client_id=${encodeURIComponent(clientId)}&redirect_uri=${encodeURIComponent(redirectUri)}&response_type=code`;
     }
 
-    // Create provider
+    // Create provider. `--port` now reaches the strategy that binds the socket;
+    // it must stay the port baked into the authorization URL above, or the
+    // provider rejects the mismatch before opening anything.
     const provider = new AuthorizationCodeProvider({
       authorizationUrl,
       uaaUrl,
       clientId,
       clientSecret,
-      browser,
-      redirectPort: port,
+      authorization: browserCallbackStrategy({ browser, port }),
       refreshToken: existingRefreshToken,
     });
 

package/dist/__tests__/helpers/netHelpers.d.ts

@@ -1,3 +1,19 @@
 export declare function getAvailablePort(): Promise<number>;
 export declare function canListenOnLocalhost(): Promise<boolean>;
+/**
+ * Whether a login in this test could own `port` — and therefore whether
+ * asserting that it released the port means anything.
+ *
+ * A release assertion is a claim about our own cleanup. When an unrelated
+ * process already holds the port, the login fails at the probe, never binds
+ * anything, and cannot release anything: the port is still held afterwards,
+ * the code is behaving exactly as it should, and the assertion fails anyway.
+ * That is a test reporting on what else is running on the machine.
+ *
+ * So the gate is placed *before* the login rather than the assertion being
+ * widened until it always passes — a `toBe(true)` relaxed into "free or held"
+ * would also pass when our own cleanup leaked, which is the one thing these
+ * cases exist to catch.
+ */
+export declare function canOwnPort(port: number, context: string): Promise<boolean>;
 //# sourceMappingURL=netHelpers.d.ts.map

package/dist/__tests__/helpers/netHelpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"netHelpers.d.ts","sourceRoot":"","sources":["../../../src/__tests__/helpers/netHelpers.ts"],"names":[],"mappings":"AAEA,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CAcxD;AAED,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,OAAO,CAAC,CAQ7D"}
+{"version":3,"file":"netHelpers.d.ts","sourceRoot":"","sources":["../../../src/__tests__/helpers/netHelpers.ts"],"names":[],"mappings":"AAEA,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CAcxD;AAED,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,OAAO,CAAC,CAQ7D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC,CAclB"}

package/dist/__tests__/helpers/netHelpers.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getAvailablePort = getAvailablePort;
 exports.canListenOnLocalhost = canListenOnLocalhost;
+exports.canOwnPort = canOwnPort;
 const net = __importStar(require("node:net"));
 async function getAvailablePort() {
     return new Promise((resolve, reject) => {
@@ -61,3 +62,31 @@ async function canListenOnLocalhost() {
         });
     });
 }
+/**
+ * Whether a login in this test could own `port` — and therefore whether
+ * asserting that it released the port means anything.
+ *
+ * A release assertion is a claim about our own cleanup. When an unrelated
+ * process already holds the port, the login fails at the probe, never binds
+ * anything, and cannot release anything: the port is still held afterwards,
+ * the code is behaving exactly as it should, and the assertion fails anyway.
+ * That is a test reporting on what else is running on the machine.
+ *
+ * So the gate is placed *before* the login rather than the assertion being
+ * widened until it always passes — a `toBe(true)` relaxed into "free or held"
+ * would also pass when our own cleanup leaked, which is the one thing these
+ * cases exist to catch.
+ */
+async function canOwnPort(port, context) {
+    const free = await new Promise((resolve) => {
+        const probe = net.createServer();
+        probe.once('error', () => resolve(false));
+        probe.listen(port, () => probe.close(() => resolve(true)));
+    });
+    if (!free) {
+        console.warn(`⚠️  Port ${port} is held by another process — skipping the port-release ` +
+            `assertions in "${context}". A login that never bound the socket cannot ` +
+            'release it; the remaining assertions in this case still run.');
+    }
+    return free;
+}

package/dist/__tests__/helpers/testLogger.d.ts

@@ -2,6 +2,6 @@
  * Test logger with environment variable control
  * Uses DefaultLogger from @mcp-abap-adt/logger for proper formatting
  */
-import type { ILogger } from '@mcp-abap-adt/interfaces';
+import type { ILogger } from '@mcp-abap-adt/interfaces-utils';
 export declare function createTestLogger(prefix?: string): ILogger;
 //# sourceMappingURL=testLogger.d.ts.map

package/dist/__tests__/helpers/testLogger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testLogger.d.ts","sourceRoot":"","sources":["../../../src/__tests__/helpers/testLogger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAGxD,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,MAAe,GAAG,OAAO,CAwCjE"}
+{"version":3,"file":"testLogger.d.ts","sourceRoot":"","sources":["../../../src/__tests__/helpers/testLogger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAG9D,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,MAAe,GAAG,OAAO,CAwCjE"}

package/dist/auth/announce.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Where an essential, user-facing prompt goes.
+ *
+ * Prompts are not log lines: a device code or an authorization URL the user
+ * cannot see makes the flow impassable, so they must survive the absence of a
+ * logger. They must equally never reach stdout, which carries protocol traffic
+ * under an MCP or LSP stdio transport.
+ */
+import type { ILogger } from '@mcp-abap-adt/interfaces-utils';
+export declare function announcer(logger?: ILogger): (msg: string) => void;
+//# sourceMappingURL=announce.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"announce.d.ts","sourceRoot":"","sources":["../../src/auth/announce.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAE9D,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAKjE"}

package/dist/auth/announce.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Where an essential, user-facing prompt goes.
+ *
+ * Prompts are not log lines: a device code or an authorization URL the user
+ * cannot see makes the flow impassable, so they must survive the absence of a
+ * logger. They must equally never reach stdout, which carries protocol traffic
+ * under an MCP or LSP stdio transport.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.announcer = announcer;
+function announcer(logger) {
+    return (msg) => {
+        if (logger)
+            logger.info(msg);
+        else
+            process.stderr.write(`${msg}\n`);
+    };
+}

package/dist/auth/browserAuth.d.ts

@@ -1,10 +1,8 @@
 /**
  * Browser authentication - OAuth2 flow for obtaining tokens
  */
-import type { IAuthorizationConfig, ILogger } from '@mcp-abap-adt/interfaces';
-type BrowserAuthConfig = IAuthorizationConfig & {
-    authorizationUrl?: string;
-};
+import type { IAuthorizationConfig } from '@mcp-abap-adt/interfaces-auth-sap';
+import type { ILogger } from '@mcp-abap-adt/interfaces-utils';
 /**
  * Extract an OAuth2 authorization code from arbitrary pasted input.
  *
@@ -17,25 +15,35 @@ type BrowserAuthConfig = IAuthorizationConfig & {
  * @internal - Exported for testing and for manual-paste flows.
  */
 export declare function extractCode(input: string): string | null;
+/**
+ * Build the OAuth2 authorization URL for a redirect URI that is already known.
+ *
+ * The URI is a parameter rather than a port because the port may have been
+ * chosen by the OS moments earlier — see `ICallbackServerOptions.port`.
+ */
+export declare function getJwtAuthorizationUrl(authConfig: IAuthorizationConfig, redirectUri: string): string;
 /**
  * Exchange authorization code for tokens
  * @internal - Exported for testing
  */
-export declare function exchangeCodeForToken(authConfig: IAuthorizationConfig, code: string, port?: number, log?: ILogger | null): Promise<{
+export declare function exchangeCodeForToken(authConfig: IAuthorizationConfig, code: string, redirectUri: string, log?: ILogger | null): Promise<{
     accessToken: string;
     refreshToken?: string;
 }>;
 /**
- * Interactive browser login for the UAA authorization-code flow.
+ * Open the authorization URL, or tell the user how to do it.
  *
- * The callback socket is owned by `withBrowserCallbackServer`: it is released
- * when the scope ends, whatever ends it, and before the code is exchanged — so
- * a slow UAA cannot hold the port, and a settled promise always means the port
- * is free.
+ * Never awaited on the critical path by the caller: a launcher that hangs must
+ * not delay the login timeout or the release of the port. A launcher that fails
+ * is reported through the scope's `fail`, which is just another way for the
+ * scope to end.
  */
-export declare function startBrowserAuth(authConfig: BrowserAuthConfig, browser?: string, logger?: ILogger, port?: number, timeoutMs?: number): Promise<{
-    accessToken: string;
-    refreshToken?: string;
-}>;
-export {};
+export declare function launchBrowser(authorizationUrl: string, browser: string, callbackUri: string, announce: (msg: string) => void, log: ILogger | null, 
+/**
+ * Extra guidance for 'none'/'headless', supplied only by a flow whose
+ * transport really offers another way in. The UAA callback server has a paste
+ * form on `/`; the OIDC and SAML ones do not, and promising one there sends
+ * the user to a 404.
+ */
+remoteHint?: string): Promise<void>;
 //# sourceMappingURL=browserAuth.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"browserAuth.d.ts","sourceRoot":"","sources":["../../src/auth/browserAuth.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAI9E,KAAK,iBAAiB,GAAG,oBAAoB,GAAG;IAC9C,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAYF;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiBxD;AAoBD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,oBAAoB,EAChC,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAa,EACnB,GAAG,CAAC,EAAE,OAAO,GAAG,IAAI,GACnB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAgDzD;AA8JD;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,iBAAiB,EAC7B,OAAO,GAAE,MAAiB,EAC1B,MAAM,CAAC,EAAE,OAAO,EAChB,IAAI,GAAE,MAAa,EACnB,SAAS,GAAE,MAAkB,GAC5B,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA2FzD"}
+{"version":3,"file":"browserAuth.d.ts","sourceRoot":"","sources":["../../src/auth/browserAuth.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAa9D;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiBxD;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,oBAAoB,EAChC,WAAW,EAAE,MAAM,GAClB,MAAM,CASR;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,oBAAoB,EAChC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,GAAG,CAAC,EAAE,OAAO,GAAG,IAAI,GACnB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA+CzD;AAeD;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,gBAAgB,EAAE,MAAM,EACxB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,EAC/B,GAAG,EAAE,OAAO,GAAG,IAAI;AACnB;;;;;GAKG;AACH,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAiGf"}

package/dist/auth/browserAuth.js

@@ -40,14 +40,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractCode = extractCode;
+exports.getJwtAuthorizationUrl = getJwtAuthorizationUrl;
 exports.exchangeCodeForToken = exchangeCodeForToken;
-exports.startBrowserAuth = startBrowserAuth;
+exports.launchBrowser = launchBrowser;
 const child_process = __importStar(require("node:child_process"));
-const http = __importStar(require("node:http"));
-const net = __importStar(require("node:net"));
-const readline = __importStar(require("node:readline"));
 const axios_1 = __importDefault(require("axios"));
-const callbackServer_1 = require("./callbackServer");
 const BROWSER_MAP = {
     chrome: 'chrome',
     edge: 'msedge',
@@ -89,12 +86,14 @@ function extractCode(input) {
     return trimmed;
 }
 /**
- * Get OAuth2 authorization URL
+ * Build the OAuth2 authorization URL for a redirect URI that is already known.
+ *
+ * The URI is a parameter rather than a port because the port may have been
+ * chosen by the OS moments earlier — see `ICallbackServerOptions.port`.
  */
-function getJwtAuthorizationUrl(authConfig, port = 3001) {
+function getJwtAuthorizationUrl(authConfig, redirectUri) {
     const oauthUrl = authConfig.uaaUrl;
     const clientid = authConfig.uaaClientId;
-    const redirectUri = `http://localhost:${port}/callback`;
     if (!oauthUrl || !clientid) {
         throw new Error('Authorization config missing UAA URL or client ID');
     }
@@ -104,10 +103,9 @@ function getJwtAuthorizationUrl(authConfig, port = 3001) {
  * Exchange authorization code for tokens
  * @internal - Exported for testing
  */
-async function exchangeCodeForToken(authConfig, code, port = 3001, log) {
+async function exchangeCodeForToken(authConfig, code, redirectUri, log) {
     const { uaaUrl: url, uaaClientId: clientid, uaaClientSecret: clientsecret, } = authConfig;
     const tokenUrl = `${url}/oauth/token`;
-    const redirectUri = `http://localhost:${port}/callback`;
     const params = new URLSearchParams();
     params.append('grant_type', 'authorization_code');
     params.append('code', code);
@@ -148,44 +146,29 @@ function _isDebugEnabled() {
         process.env.DEBUG?.includes('browser-auth') === true);
 }
 /**
- * Check if a port is available
+ * Open the authorization URL, or tell the user how to do it.
+ *
+ * Never awaited on the critical path by the caller: a launcher that hangs must
+ * not delay the login timeout or the release of the port. A launcher that fails
+ * is reported through the scope's `fail`, which is just another way for the
+ * scope to end.
  */
-function isPortAvailable(port) {
-    return new Promise((resolve) => {
-        const server = net.createServer();
-        server.listen(port, () => {
-            server.once('close', () => resolve(true));
-            server.close();
-        });
-        server.on('error', () => resolve(false));
-    });
-}
+async function launchBrowser(authorizationUrl, browser, callbackUri, announce, log, 
 /**
- * Start browser authentication flow
- * @param authConfig Authorization configuration with UAA credentials
- * @param browser Browser name (chrome, edge, firefox, system, none)
- * @param logger Optional logger instance. If not provided, uses default logger.
- * @param port Port for OAuth callback server (default: 3001)
- * @returns Promise that resolves to tokens
- * @internal - Internal function, not exported from package
- */ /**
-* Open the authorization URL, or tell the user how to do it.
-*
-* Never awaited on the critical path by the caller: a launcher that hangs must
-* not delay the login timeout or the release of the port. A launcher that fails
-* is reported through the scope's `fail`, which is just another way for the
-* scope to end.
-*/
-async function launchBrowser(authorizationUrl, browser, port, announce, log) {
+ * Extra guidance for 'none'/'headless', supplied only by a flow whose
+ * transport really offers another way in. The UAA callback server has a paste
+ * form on `/`; the OIDC and SAML ones do not, and promising one there sends
+ * the user to a 404.
+ */
+remoteHint) {
     const browserApp = BROWSER_MAP[browser];
     // 'none' / 'headless': show the URL and wait. For SSH and remote sessions.
     if (browser === 'none' || browser === 'headless') {
         announce('🔗 Open this URL in your browser to authenticate:');
         announce(`   ${authorizationUrl}`);
-        announce(`   Waiting for callback on http://localhost:${port}/callback ...`);
-        announce('   If your browser is on another machine, after login copy the ' +
-            '`code` from the address bar and paste it at ' +
-            `http://<this-host>:${port}/ — or paste it here and press Enter.`);
+        announce(`   Waiting for callback on ${callbackUri} ...`);
+        if (remoteHint)
+            announce(remoteHint);
         return;
     }
     if (browser === 'auto') {
@@ -200,7 +183,7 @@ async function launchBrowser(authorizationUrl, browser, port, announce, log) {
             log?.warn(`⚠️  Could not open browser automatically: ${message}`);
             announce('🔗 Please open this URL in your browser to authenticate:');
             announce(`   ${authorizationUrl}`);
-            announce(`   Waiting for callback on http://localhost:${port}/callback ...`);
+            announce(`   Waiting for callback on ${callbackUri} ...`);
         }
         return;
     }
@@ -269,72 +252,3 @@ async function launchBrowser(authorizationUrl, browser, port, announce, log) {
     else
         await open(authorizationUrl);
 }
-/**
- * Interactive browser login for the UAA authorization-code flow.
- *
- * The callback socket is owned by `withBrowserCallbackServer`: it is released
- * when the scope ends, whatever ends it, and before the code is exchanged — so
- * a slow UAA cannot hold the port, and a settled promise always means the port
- * is free.
- */
-async function startBrowserAuth(authConfig, browser = 'system', logger, port = 3001, timeoutMs = 30 * 1000) {
-    const log = logger || null;
-    // Essential, user-facing prompts (the auth URL, paste instructions) must be
-    // visible even when no logger is supplied. Fall back to stderr — never stdout,
-    // so stdio-based RPC transports (MCP/LSP) are not corrupted.
-    const announce = (msg) => {
-        if (log)
-            log.info(msg);
-        else
-            process.stderr.write(`${msg}\n`);
-    };
-    // 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.`);
-    }
-    let stdinReader = null;
-    const code = await (0, callbackServer_1.withBrowserCallbackServer)({ port, timeoutMs }, async (server) => {
-        const authorizationUrl = authConfig.authorizationUrl ??
-            getJwtAuthorizationUrl(authConfig, server.port);
-        log?.info(`[browserAuth] Authorization URL: ${authorizationUrl}`);
-        log?.info(`[browserAuth] Server listening on port: ${server.port}`);
-        const waiting = server.waitForResult();
-        // Not awaited: a launcher that hangs must not delay the timeout or the
-        // release, and one that fails ends the scope through `fail`.
-        void launchBrowser(authorizationUrl, browser, server.port, announce, log).catch((error) => {
-            const message = error instanceof Error ? error.message : String(error);
-            log?.error(`❌ Failed to open browser: ${message}. Please open manually: ${authorizationUrl}`, { error: message, url: authorizationUrl });
-            server.fail(new Error(`Browser opening failed for destination authentication. Please open manually: ${authorizationUrl}`));
-        });
-        // Manual stdin paste — only when attached to an interactive terminal.
-        // Under a stdio RPC transport stdin carries the protocol, so we must never
-        // consume it; isTTY guards that. A pasted line is handed to the same
-        // `/submit` route the paste form uses, so there is one way in, not two.
-        if ((browser === 'none' || browser === 'headless') &&
-            process.stdin.isTTY) {
-            stdinReader = readline.createInterface({ input: process.stdin });
-            stdinReader.on('line', (line) => {
-                const pasted = extractCode(line);
-                if (!pasted) {
-                    process.stderr.write('Could not read an authorization code from that input. Try again.\n');
-                    return;
-                }
-                const req = http.get({
-                    host: '127.0.0.1',
-                    port: server.port,
-                    path: `/submit?input=${encodeURIComponent(pasted)}`,
-                    agent: false,
-                });
-                req.on('error', () => undefined);
-            });
-        }
-        return await waiting;
-    }).finally(() => {
-        stdinReader?.close();
-        stdinReader = null;
-    });
-    log?.info('[browserAuth] Exchanging code for token...');
-    return await exchangeCodeForToken(authConfig, code, port, log);
-}

package/dist/auth/callbackServer.d.ts

@@ -8,7 +8,7 @@
  *
  * See `docs/superpowers/specs/2026-07-28-callback-server-contract-design.md`.
  */
-import type { CallbackServerFactory, ICallbackServerHandle, ICallbackServerOptions } from '@mcp-abap-adt/interfaces';
+import type { CallbackServerFactory, ICallbackServerHandle, ICallbackServerOptions } from '@mcp-abap-adt/interfaces-auth';
 import express from 'express';
 /**
  * How a route reports an outcome. Settling is deferred until the response has
@@ -20,6 +20,12 @@ export interface Settle<TResult> {
     ok(value: TResult, res?: express.Response): void;
     /** The callback reported a failure. Ends the scope. */
     err(error: Error, res?: express.Response): void;
+    /**
+     * This was not our redirect — a reloaded tab, a prefetch, a port scanner.
+     * Answered and counted; the login keeps waiting, bounded as ever by the
+     * timeout. Ends nothing.
+     */
+    ignore(reason: string, res?: express.Response): void;
 }
 export type RouteSetup<TResult> = (app: express.Express, settle: Settle<TResult>) => void;
 /**

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

@@ -1 +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"}
+{"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,+BAA+B,CAAC;AACvC,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;IAChD;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;CACtD;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,CAqMlB;AAyCD;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,qBAAqB,CAAC,MAAM,CA4DjE,CAAC"}

package/dist/auth/callbackServer.js

@@ -57,8 +57,8 @@ const MAX_TIMEOUT_MS = 2_147_483_647;
 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.isInteger(port) || port < 0 || port > 65535) {
+        throw new Error(`Invalid callback server port: ${String(port)}. Must be an integer in 0..65535.`);
     }
     if (!Number.isFinite(timeoutMs) ||
         timeoutMs <= 0 ||
@@ -105,6 +105,7 @@ async function runCallbackScope(options, routes, use) {
     });
     let timer = null;
     let alive = false;
+    let ignored = 0;
     const settleResult = (outcome) => {
         if (resultSettled)
             return;
@@ -202,25 +203,13 @@ async function runCallbackScope(options, routes, use) {
                 endScope({ error });
             });
         },
+        ignore(reason) {
+            ignored += 1;
+            options.logger?.warn('[callbackServer] ignored an incomplete callback request', { reason, ignored });
+        },
     };
     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 });
     });
@@ -232,10 +221,31 @@ async function runCallbackScope(options, routes, use) {
         }
         alive = true;
         timer = setTimeout(() => {
+            const tally = ignored > 0
+                ? ` ${ignored} incomplete request(s) reached /callback and were ignored.`
+                : '';
             endScope({
-                error: new Error(`Authentication timeout after ${options.timeoutMs / 1000} seconds. Please try again.`),
+                error: new Error(`Authentication timeout after ${options.timeoutMs / 1000} seconds. Please try again.${tally}`),
             });
         }, options.timeoutMs);
+        // The requested port may be 0, in which case only the OS knows the answer.
+        const bound = server.address().port;
+        const handle = {
+            port: bound,
+            redirectUri: `http://localhost:${bound}/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 });
+            },
+        };
         void use(handle).then((value) => endScope({ value }), (error) => endScope({ error }));
     });
     return await scopePromise;
@@ -296,8 +306,8 @@ const withBrowserCallbackServer = (options, use) => runCallbackScope(options, (a
         }
         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);
+            res.status(400).send('Error: not an authorization callback');
+            settle.ignore('no code and no error in query', res);
             return;
         }
         res.send(successHtml);

package/dist/auth/deviceFlowAuth.d.ts

@@ -4,7 +4,7 @@
  * OAuth2 Device Flow for devices without browser or input capabilities.
  * User authorizes on another device by entering a code.
  */
-import type { ILogger } from '@mcp-abap-adt/interfaces';
+import type { ILogger } from '@mcp-abap-adt/interfaces-utils';
 export interface DeviceFlowResult {
     deviceCode: string;
     userCode: string;

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

@@ -1 +1 @@
-{"version":3,"file":"deviceFlowAuth.d.ts","sourceRoot":"","sources":["../../src/auth/deviceFlowAuth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAGxD,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,gBAAgB,CAAC,CA4D3B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,UAAU,EAAE,MAAM,EAClB,QAAQ,GAAE,MAAU,EACpB,MAAM,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,gBAAgB,CAAC,CAoG3B"}
+{"version":3,"file":"deviceFlowAuth.d.ts","sourceRoot":"","sources":["../../src/auth/deviceFlowAuth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAG9D,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,gBAAgB,CAAC,CA4D3B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,UAAU,EAAE,MAAM,EAClB,QAAQ,GAAE,MAAU,EACpB,MAAM,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,gBAAgB,CAAC,CAoG3B"}

package/dist/auth/oidcBrowserAuth.d.ts

@@ -1,17 +1,10 @@
 /**
  * OIDC browser authorization code flow (capture code)
  */
-import type { ILogger } from '@mcp-abap-adt/interfaces';
+import type { CallbackServerFactory } from '@mcp-abap-adt/interfaces-auth';
 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>;
+export declare const withOidcCallbackServer: CallbackServerFactory<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;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"}
+{"version":3,"file":"oidcBrowserAuth.d.ts","sourceRoot":"","sources":["../../src/auth/oidcBrowserAuth.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,qBAAqB,EAGtB,MAAM,+BAA+B,CAAC;AAGvC,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,sBAAsB,EAAE,qBAAqB,CACxD,kBAAkB,CA6CjB,CAAC"}