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

package/CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-07-28
+
+### Fixed
+- **A callback server could hold its port after the login it was opened for had ended.** Three flows, three shapes of one defect: `browserAuth` leaked the socket when a callback carried neither `code` nor `error` — measured still bound at +5 s, +20 s, +35 s and +45 s, i.e. for the life of the process — while `oidcBrowserAuth` and `saml2Auth` had no timeout at all, so an abandoned login never settled and never released anything. (#11)
+- **A rejected login could report a port that was not yet free.** Five exit paths closed the socket asynchronously *after* the promise had settled, leaving a window in which "already in use" was untrue.
+- **`AuthorizationCodeProvider` raced `startBrowserAuth` against a second 30-second timer** of its own, so which fired was down to scheduling; when the outer one won it rejected while the socket was still bound. That timer was never cleared, keeping a login that succeeded in a second armed for the remaining 29.
+- **A hung browser launcher could delay the timeout and the release.** The launch is no longer awaited on the critical path.
+
+### Changed
+- All three flows now run inside a factory scope implementing `CallbackServerFactory` from `@mcp-abap-adt/interfaces`. The port is released when the scope ends — by success, error, timeout, cancellation, or a body that throws — instead of when a promise happens to settle, and the scope settles only once the socket is free. `timeoutMs` is mandatory and an `AbortSignal` is honoured before, during and after the bind.
+- Shutdown is bounded: stop accepting, wait up to 500 ms for `close`, then force. A timeout can no longer hang on its own cleanup.
+- Requires `@mcp-abap-adt/interfaces` `^11.4.0` (was `^2.3.0`).
+- **`engines.node` is now `>=18.2.0`** (was `>=18.0.0`), for `server.closeAllConnections()`.
+- `browserAuth.ts` is 395 lines, down from 790: the HTTP server, six separate close sites, two timers and the process-signal handlers are gone from it.
+
+### Removed
+- **The callback server no longer installs `SIGTERM` / `SIGINT` / `SIGHUP` / `exit` handlers.** A terminating process releases its listening sockets to the OS regardless — measured at 0-1 ms after the process disappears — and these were part of the cleanup tangle being removed. A client that kills the process mid-login still gets its port back.
+- **The manual paste channel no longer retries a bad code.** It used to re-render the form when the exchange failed; the code is now exchanged after the scope closes, so a wrong or expired paste ends the attempt. That retry loop was the only reason the socket outlived the code.
+
+### Notes
+- Public API is unchanged: `AuthorizationCodeProviderConfig` keeps `browser` and `redirectPort`, still defaulting to 3001.
+- The three factories stay internal. Exposing them so a consumer can supply its own callback receiver is issue #11 and is not part of this release.
+- A callback carrying neither `code` nor `error` still ends the login with an error. Only the leaked socket was fixed, not the termination.
+
+## [1.1.0] - 2026-06-02
+
+### Added
+- `extractCode(input)` helper: pulls an OAuth2 authorization code out of a bare
+  code, a `code=...` string, or a full redirected URL.
+- Manual paste authentication for `none`/`headless` browser modes, so login can
+  complete when the automatic `localhost` callback can't reach the process
+  (browser on another machine / container / SSH). Three racing channels, first
+  one wins:
+  - the existing automatic `GET /callback?code=...` redirect;
+  - an HTML paste form on the same callback server (`GET /` + `GET /submit`);
+  - stdin paste, only when `process.stdin.isTTY` (never consumed under stdio
+    RPC transports).
+
+### Fixed
+- `none`/`headless` mode now prints the authorization URL even when no logger is
+  supplied. The prompt previously rode on `log?.info(...)` and was silently
+  dropped without a logger; it now falls back to `stderr` (never stdout, to keep
+  stdio RPC transports uncorrupted).
+
 ## [1.0.5] - 2026-02-12
 
 ### Fixed

package/README.md

@@ -1,4 +1,5 @@
 # @mcp-abap-adt/auth-providers
+[![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg)](https://stand-with-ukraine.pp.ua)
 
 Token providers for MCP ABAP ADT auth-broker.
 
@@ -99,6 +100,36 @@ const clientCredsBroker = new AuthBroker({
 }, 'none');
 ```
 
+### Browser modes (`AuthorizationCodeProvider`)
+
+The `browser` option controls how the authorization URL is opened:
+
+| Mode | Behaviour |
+|------|-----------|
+| `system` (default) | Open the OS default browser |
+| `chrome` / `edge` / `firefox` | Open a specific browser |
+| `auto` | Try to open a browser; on failure, print the URL and wait |
+| `none` / `headless` | Do **not** open a browser — print the URL and wait for the code (SSH / remote / containers) |
+
+In `none`/`headless` mode the authorization URL is always shown, **even when no
+logger is supplied** (it falls back to `stderr`, never stdout, so stdio-based
+RPC transports are not corrupted).
+
+#### Manual paste (none / headless)
+
+Login can complete through any of three channels — whichever finishes first wins:
+
+1. **Automatic callback** — `GET /callback?code=...` on `http://localhost:<redirectPort>`.
+   Works when the browser is on the same machine as the process.
+2. **Paste form** — open `http://<host>:<redirectPort>/` and paste the code (or
+   the whole redirected URL). Works when the browser is on a *different* machine,
+   since the callback server listens on all interfaces.
+3. **Terminal paste** — paste the code on stdin and press Enter. Only active when
+   `process.stdin.isTTY` (stdin is never consumed under a stdio RPC transport).
+
+The exported `extractCode(input)` helper accepts a bare code, `code=...`, or a
+full redirected URL.
+
 ### SSO Providers
 
 This package also includes SSO providers for OIDC and SAML2, plus a small factory for DI-friendly creation.
@@ -310,11 +341,15 @@ const result = await provider.getTokens();
 // result.refreshToken is undefined (client_credentials doesn't provide refresh tokens)
 ```
 
-**Note**: The `browserAuthPort` parameter (default: 3001) configures the OAuth callback server port. If the requested port is already in use, an error will be thrown. You must specify a different port or free the port before starting authentication. The server properly closes all connections and frees the port after authentication completes, ensuring no lingering port occupation.
+**Note**: The `redirectPort` parameter (default: 3001) configures the OAuth callback server port. If the requested port is already in use, an error is thrown; specify a different port or free it before starting authentication.
+
+**Port lifetime**: the callback port is held for the login and nothing longer. It is bound when the login window opens and released when the login ends — by success, by failure, by timeout, or by cancellation — and the returned promise settles only after the socket is actually free. An error therefore always means the port is already available, and the port is released *before* the authorization code is exchanged for a token, so a slow identity provider cannot hold it either.
+
+**Timeout**: an interactive login waits 30 seconds for its callback. This applies to the browser, OIDC and SAML flows alike; before 1.2.0 the OIDC and SAML flows had no timeout at all, so an abandoned login held its port for the life of the process.
 
-**Timeout**: Browser authentication has a 30-second timeout to prevent blocking the consumer. If authentication is not completed within 30 seconds, the operation will fail with a timeout error. This prevents the provider from hanging indefinitely when the user doesn't complete authentication. 
+**Cancellation**: `ICallbackServerOptions.signal` accepts an `AbortSignal`, honoured before the bind, during it, and while waiting.
 
-**Process Termination Handling**: The OAuth callback server registers cleanup handlers for `SIGTERM`, `SIGINT`, `SIGHUP`, and `exit` signals. This ensures ports are properly freed even when MCP clients (like Cline) terminate the process before authentication completes. This is especially important for stdio servers where the client may kill the process at any time. On Windows, the `SIGBREAK` signal (Ctrl+Break) is also handled.
+**Process termination**: the callback server no longer installs its own `SIGTERM` / `SIGINT` / `SIGHUP` / `exit` handlers. A terminating process releases its listening sockets to the operating system anyway — measured at 0-1 ms after the process disappears — and the handlers were part of the cleanup tangle this release removes. If a client kills the process mid-login, the port comes back with the process.
 
 **Cross-Platform Browser Support**: The browser authentication works across Linux, macOS, and Windows:
 - **Linux**: Automatically sets `DISPLAY=:0` if neither `DISPLAY` nor `WAYLAND_DISPLAY` environment variables are set. Supports multiple browser executable names (`google-chrome`, `google-chrome-stable`, `chromium`, `chromium-browser` for Chrome; `firefox`, `firefox-esr` for Firefox).

package/dist/auth/browserAuth.d.ts

@@ -5,6 +5,18 @@ import type { IAuthorizationConfig, ILogger } from '@mcp-abap-adt/interfaces';
 type BrowserAuthConfig = IAuthorizationConfig & {
     authorizationUrl?: string;
 };
+/**
+ * Extract an OAuth2 authorization code from arbitrary pasted input.
+ *
+ * Accepts:
+ *  - a bare code: `abc123`
+ *  - `code=abc123`
+ *  - a full redirected URL: `http://localhost:7779/callback?code=abc123&state=...`
+ *
+ * Returns the decoded code, or null if nothing usable was found.
+ * @internal - Exported for testing and for manual-paste flows.
+ */
+export declare function extractCode(input: string): string | null;
 /**
  * Exchange authorization code for tokens
  * @internal - Exported for testing
@@ -14,15 +26,14 @@ export declare function exchangeCodeForToken(authConfig: IAuthorizationConfig, c
     refreshToken?: string;
 }>;
 /**
- * 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
+ * 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.
  */
-export declare function startBrowserAuth(authConfig: BrowserAuthConfig, browser?: string, logger?: ILogger, port?: number): Promise<{
+export declare function startBrowserAuth(authConfig: BrowserAuthConfig, browser?: string, logger?: ILogger, port?: number, timeoutMs?: number): Promise<{
     accessToken: string;
     refreshToken?: string;
 }>;

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;AAKH,OAAO,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAI9E,KAAK,iBAAiB,GAAG,oBAAoB,GAAG;IAC9C,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AA8BF;;;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;AA6BD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,iBAAiB,EAC7B,OAAO,GAAE,MAAiB,EAC1B,MAAM,CAAC,EAAE,OAAO,EAChB,IAAI,GAAE,MAAa,GAClB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAqjBzD"}
+{"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"}