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

package/README.md

@@ -20,6 +20,15 @@ This package implements the `ITokenProvider` interface from `@mcp-abap-adt/inter
 
 Providers are configured via constructor; `getTokens()` takes no parameters and handles refresh/login internally.
 
+Since 2.0.0 an interactive login is conducted by an **authorization strategy**
+(`IAuthorizationStrategy` from `@mcp-abap-adt/interfaces`) passed as
+`authorization`. The provider owns what it can compute — the authorization URL
+and the token exchange; everything between them (reaching the URL, receiving
+what comes back, the port, the timeout) belongs to the strategy, which a
+consumer may replace wholesale. See
+[Choosing an authorization strategy](#choosing-an-authorization-strategy) and,
+if you are on 1.x, [Migrating from 1.x to 2.0](#migrating-from-1x-to-20).
+
 ## Responsibilities and Design Principles
 
 ### Core Development Principle
@@ -78,7 +87,11 @@ This package interacts with external packages **ONLY through interfaces**:
 
 ```typescript
 import { AuthBroker } from '@mcp-abap-adt/auth-broker';
-import { AuthorizationCodeProvider, ClientCredentialsProvider } from '@mcp-abap-adt/auth-providers';
+import {
+  AuthorizationCodeProvider,
+  ClientCredentialsProvider,
+  browserCallbackStrategy,
+} from '@mcp-abap-adt/auth-providers';
 
 // User token via authorization_code (browser flow)
 const authCodeBroker = new AuthBroker({
@@ -86,7 +99,7 @@ const authCodeBroker = new AuthBroker({
     uaaUrl: 'https://...',
     clientId: '...',
     clientSecret: '...',
-    browser: 'system',
+    authorization: browserCallbackStrategy({ browser: 'system' }),
   }),
 });
 
@@ -100,35 +113,141 @@ const clientCredsBroker = new AuthBroker({
 }, 'none');
 ```
 
-### Browser modes (`AuthorizationCodeProvider`)
+### Choosing an authorization strategy
+
+`authorization` decides how an interactive login is conducted. Omit it and the
+provider builds the callback strategy for its own flow, on the default port —
+which is convenient, and is also the only case where the default port applies
+without you having chosen it. Every shipped strategy is a plain function
+returning `IAuthorizationStrategy`, so a consumer can pass its own instead.
+
+| Strategy | For | What it does |
+|---|---|---|
+| `browserCallbackStrategy(opts)` | `AuthorizationCodeProvider` | Binds a local callback server, opens the URL, waits for `?code=` |
+| `oidcCallbackStrategy(opts)` | `OidcBrowserProvider` | The same, yielding `{ code, state }` |
+| `samlCallbackStrategy(opts)` | `Saml2BearerProvider`, `Saml2PureProvider` | The same, receiving a posted `SAMLResponse` |
+| `manualPasteStrategy({ redirectUri, read })` | code flows | Shows the URL, reads the pasted code (stdin by default) |
+| `manualSamlResponseStrategy({ redirectUri, read })` | SAML flows | Shows the URL, reads the pasted `SAMLResponse` |
+| `externalCodeStrategy({ redirectUri, provide })` | either | Hands the assembled URL to your function, takes back the payload |
+| `staticCodeStrategy({ redirectUri, payload })` | either | You already hold the payload; the URL is never built |
+| your own | any | Implement `IAuthorizationStrategy<TResult>` and pass it |
+
+Options common to the three callback strategies:
+
+| Option | Default | Meaning |
+|---|---|---|
+| `port` | `61001` (`DEFAULT_CALLBACK_PORT`) | Port to bind. `0` binds an ephemeral one — usable only where the identity provider accepts a loopback redirect on any port, never where a fixed redirect URI is registered |
+| `timeoutMs` | `30000` (`DEFAULT_LOGIN_TIMEOUT_MS`) | How long the login may wait for its callback |
+| `browser` | `'none'` | `'none'` / `'headless'` print the URL; `'system'`, `'auto'`, `'chrome'`, `'edge'`, `'firefox'` open it |
+| `callbackServer` | the one this package ships | Your own `CallbackServerFactory`, to reuse a server you already run |
+| `openUrl` | the built-in launcher | Receives `(url, browser, redirectUri)` |
+| `remoteHint` | the paste hint, only for the shipped UAA transport | Extra guidance printed in `'none'` / `'headless'` mode |
+| `signal` | — | `AbortSignal` cancelling the login |
+
+Note the `browser` default: **`'none'`, so nothing is opened unless you ask for
+it.** The URL is always shown, even with no logger — it falls back to `stderr`,
+never stdout, so an MCP/LSP stdio transport is not corrupted. (1.x behaved the
+same way; the 1.x README claiming `system` was the default was wrong.)
+
+The three `CallbackServerFactory` implementations are exported too —
+`withBrowserCallbackServer`, `withOidcCallbackServer`, `withSamlCallbackServer`
+— so a consumer can keep the transport and replace everything around it, or the
+reverse.
+
+For the three shipped flows, passing `callbackServer` to a ready constructor is
+the way to substitute a transport. The `BrowserCallbackStrategy` class behind
+them is exported as well, for the case the constructors cannot express: a
+receiver whose payload is none of the three shapes those flows deliver. Its
+options are the same, except `callbackServer` is required — there is no default
+transport to fall back on when the payload type is your own.
 
-The `browser` option controls how the authorization URL is opened:
+```typescript
+import { BrowserCallbackStrategy } from '@mcp-abap-adt/auth-providers';
 
-| 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) |
+const strategy = new BrowserCallbackStrategy<MyPayload>({
+  callbackServer: withMyOwnCallbackServer, // CallbackServerFactory<MyPayload>
+  port: 61001,
+  timeoutMs: 30000,
+});
+```
+
+#### Bringing your own
+
+```typescript
+import type { IAuthorizationStrategy } from '@mcp-abap-adt/interfaces';
+
+const fromOurPortal: IAuthorizationStrategy<string> = {
+  async authorize(request) {
+    const redirectUri = 'https://portal.internal/oauth/callback';
+    const url = await request.buildAuthorizationUrl(redirectUri);
+    // The redirect URI you return is the one sent to the token endpoint.
+    return { payload: await ourPortal.login(url), redirectUri };
+  },
+  async dispose() { await ourPortal.close(); },
+};
+```
 
-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).
+`dispose` is optional, and whoever constructs a strategy disposes of it: a
+strategy you pass in is yours to dispose, one the provider defaulted to is
+disposed by the provider.
 
-#### Manual paste (none / headless)
+#### Manual paste over a callback server
 
-Login can complete through any of three channels — whichever finishes first wins:
+With `browserCallbackStrategy` (the UAA transport), login can complete through
+either of **two** channels — whichever finishes first wins:
 
-1. **Automatic callback** — `GET /callback?code=...` on `http://localhost:<redirectPort>`.
+1. **Automatic callback** — `GET /callback?code=...` on the bound redirect URI.
    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).
+2. **Paste form** — open `http://<this-host>:<port>/` 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. In `'none'` /
+   `'headless'` mode the strategy prints this address for you — with the real
+   port and the host left for you to fill in, because the process cannot know
+   which of its addresses you can reach.
+
+**The terminal-paste channel is gone.** In 1.x a third channel read the code
+from stdin when `process.stdin.isTTY`; `browserCallbackStrategy` has no such
+reader, and this is deliberate rather than an oversight — under an MCP or LSP
+stdio transport stdin carries the protocol, and an authorization library has no
+business consuming it. Reading a pasted code is now a strategy of its own:
 
-The exported `extractCode(input)` helper accepts a bare code, `code=...`, or a
-full redirected URL.
+```typescript
+import {
+  AuthorizationCodeProvider,
+  manualPasteStrategy,
+} from '@mcp-abap-adt/auth-providers';
+
+const provider = new AuthorizationCodeProvider({
+  uaaUrl, clientId, clientSecret,
+  // Binds no socket at all: prints the URL, then reads one line.
+  // Defaults to stdin when it is a TTY — pass `read` to source it anywhere else.
+  authorization: manualPasteStrategy({
+    redirectUri: 'http://localhost:61001/callback',
+  }),
+});
+```
+
+`manualPasteStrategy` reads from stdin only when `process.stdin.isTTY`, and
+throws a clear error otherwise rather than consuming a protocol stream. Supply
+`read` to take the value from somewhere else entirely — a TUI prompt, an HTTP
+request, a file:
+
+```typescript
+authorization: manualPasteStrategy({
+  redirectUri: 'http://localhost:61001/callback',
+  read: async (prompt) => askInOurUi(prompt),
+})
+```
+
+The `redirectUri` you give it must be the one the identity provider will
+redirect to; it is also the one sent to the token endpoint. It defaults to
+`http://localhost:61001/callback`.
+
+Both the paste form and `manualPasteStrategy` accept a bare code, `code=...`,
+or a full redirected URL — whichever you paste, the code is extracted from it.
+
+> The `extractCode(input)` helper behind that leniency is internal; it is not
+> part of the package's exports, contrary to what the 1.1.0–1.2.0 README said.
 
 ### SSO Providers
 
@@ -146,7 +265,10 @@ Factory example:
 
 ```typescript
 import { AuthBroker } from '@mcp-abap-adt/auth-broker';
-import { SsoProviderFactory } from '@mcp-abap-adt/auth-providers';
+import {
+  SsoProviderFactory,
+  oidcCallbackStrategy,
+} from '@mcp-abap-adt/auth-providers';
 
 const tokenProvider = SsoProviderFactory.create({
   protocol: 'oidc',
@@ -156,59 +278,101 @@ const tokenProvider = SsoProviderFactory.create({
     clientId: '...',
     clientSecret: '...',
     scopes: ['openid', 'profile', 'email'],
-    browser: 'system',
+    authorization: oidcCallbackStrategy({ browser: 'system' }),
   },
 });
 
 const broker = new AuthBroker({ tokenProvider }, 'none');
 ```
 
-OIDC browser example (manual code + explicit endpoints):
+OIDC browser example (a code you already hold + explicit endpoints):
 
 ```typescript
-import { OidcBrowserProvider } from '@mcp-abap-adt/auth-providers';
+import {
+  OidcBrowserProvider,
+  asOidcResult,
+  staticCodeStrategy,
+} from '@mcp-abap-adt/auth-providers';
+
+const redirectUri = 'urn:ietf:wg:oauth:2.0:oob';
 
 const provider = new OidcBrowserProvider({
   clientId: '...',
   tokenEndpoint: 'https://issuer/oauth/token',
   authorizationEndpoint: 'https://issuer/oauth/authorize',
-  authorizationCode: '<paste-code-here>',
-  redirectUri: 'urn:ietf:wg:oauth:2.0:oob',
+  authorization: asOidcResult(
+    staticCodeStrategy({ redirectUri, payload: '<paste-code-here>' }),
+  ),
 });
 ```
 
-SAML bearer example (manual flow):
+`asOidcResult` is not optional here. `OidcBrowserProvider` takes
+`IAuthorizationStrategy<OidcCallbackResult>`, and the code-producing strategies
+(`staticCodeStrategy`, `externalCodeStrategy`, `manualPasteStrategy`) yield a
+`string`; passing one directly does not type-check. The adapter wraps the code
+as `{ code }` — a value that never travelled through a redirect carries no
+`state` to check — and delegates `dispose`, so wrapping costs nothing in
+lifecycle terms.
+
+The redirect URI is no longer a provider field: it belongs to the strategy,
+because with an ephemeral port nothing knows it until the socket is bound. The
+one the strategy reports is the one sent to the token endpoint.
+
+SAML bearer example (manual paste):
 
 ```typescript
 import { AuthBroker } from '@mcp-abap-adt/auth-broker';
-import { Saml2BearerProvider } from '@mcp-abap-adt/auth-providers';
+import {
+  Saml2BearerProvider,
+  manualSamlResponseStrategy,
+} from '@mcp-abap-adt/auth-providers';
+
+const acsUrl = 'https://sp.example.com/saml/acs';
 
 const provider = new Saml2BearerProvider({
-  assertionFlow: 'manual',
   idpSsoUrl: 'https://idp.example.com/sso',
   spEntityId: 'my-sp-entity',
+  acsUrl,
   uaaUrl: 'https://uaa.example.com',
   clientId: '...',
   clientSecret: '...',
+  // `redirectUri` must equal `acsUrl`, or the provider refuses the mismatch.
+  authorization: manualSamlResponseStrategy({ redirectUri: acsUrl, read: promptUser }),
 });
 
 const broker = new AuthBroker({ tokenProvider: provider }, 'none');
 ```
 
-SAML bearer example (headless, assertion provider):
+**Read that `redirectUri` twice.** A SAML strategy defaults its redirect URI to
+`http://localhost:61001/callback`, and the provider requires the assertion
+consumer service the IdP posts to be exactly the one the strategy names. If you
+declare a real `acsUrl` and leave `redirectUri` off, the login fails with
+*"SAML acsUrl is … but the authorization strategy is listening on …"* before
+anything is opened. Declare neither and the default is used for both, which is
+consistent — and only reachable when the IdP will post to your localhost.
+
+SAML bearer example (headless, assertion fetched elsewhere):
 
 ```typescript
 import { AuthBroker } from '@mcp-abap-adt/auth-broker';
-import { Saml2BearerProvider } from '@mcp-abap-adt/auth-providers';
+import {
+  Saml2BearerProvider,
+  externalCodeStrategy,
+} from '@mcp-abap-adt/auth-providers';
+
+const acsUrl = 'https://sp.example.com/saml/acs';
 
 const provider = new Saml2BearerProvider({
-  assertionFlow: 'assertion',
-  assertionProvider: async () => {
-    return getSamlResponseFromSsoProxy();
-  },
+  idpSsoUrl: 'https://idp.example.com/sso',
+  spEntityId: 'my-sp-entity',
+  acsUrl,
   uaaUrl: 'https://uaa.example.com',
   clientId: '...',
   clientSecret: '...',
+  authorization: externalCodeStrategy({
+    redirectUri: acsUrl,
+    provide: async (_authorizationUrl) => getSamlResponseFromSsoProxy(),
+  }),
 });
 
 const broker = new AuthBroker({ tokenProvider: provider }, 'none');
@@ -218,12 +382,18 @@ Pure SAML example (cookie-based):
 
 ```typescript
 import { AuthBroker } from '@mcp-abap-adt/auth-broker';
-import { Saml2PureProvider } from '@mcp-abap-adt/auth-providers';
+import {
+  Saml2PureProvider,
+  manualSamlResponseStrategy,
+} from '@mcp-abap-adt/auth-providers';
+
+const acsUrl = 'https://sp.example.com/saml/acs';
 
 const provider = new Saml2PureProvider({
-  assertionFlow: 'manual',
   idpSsoUrl: 'https://idp.example.com/sso',
   spEntityId: 'my-sp-entity',
+  acsUrl,
+  authorization: manualSamlResponseStrategy({ redirectUri: acsUrl, read: promptUser }),
   // Convert SAMLResponse to session cookies for SAP (implementation-specific)
   cookieProvider: async (samlResponse) => {
     return exchangeSamlForCookies(samlResponse);
@@ -233,6 +403,19 @@ const provider = new Saml2PureProvider({
 const broker = new AuthBroker({ tokenProvider: provider }, 'none');
 ```
 
+Both SAML providers now reject at construction when `authorizationUrl` is set
+without `acsUrl`:
+
+```
+acsUrl is required when authorizationUrl is set: the ACS inside a pre-built
+SAML request cannot be read, so it must be declared.
+```
+
+The ACS is buried in a deflated `SAMLRequest` this package did not build and
+cannot read, so it cannot be verified against whatever the strategy binds. 1.x
+accepted the combination and defaulted the ACS to
+`http://localhost:3001/callback` — usually not where the IdP posted.
+
 ### With Stores
 
 **Important**: BTP and ABAP are different entities:
@@ -241,7 +424,11 @@ const broker = new AuthBroker({ tokenProvider: provider }, 'none');
 
 ```typescript
 import { AuthBroker } from '@mcp-abap-adt/auth-broker';
-import { AuthorizationCodeProvider, ClientCredentialsProvider } from '@mcp-abap-adt/auth-providers';
+import {
+  AuthorizationCodeProvider,
+  ClientCredentialsProvider,
+  browserCallbackStrategy,
+} from '@mcp-abap-adt/auth-providers';
 import { 
   XsuaaServiceKeyStore, 
   XsuaaSessionStore,
@@ -276,7 +463,7 @@ const btpBroker = new AuthBroker({
     uaaUrl: 'https://...',
     clientId: '...',
     clientSecret: '...',
-    browser: 'system',
+    authorization: browserCallbackStrategy({ browser: 'system' }),
   }),
 });
 
@@ -284,7 +471,7 @@ const btpBroker = new AuthBroker({
 const abapServiceKeyStore = new AbapServiceKeyStore('/path/to/service-keys');
 const abapSessionStore = new AbapSessionStore('/path/to/sessions');
 
-// Use custom port if running alongside other services (e.g., proxy on port 3001)
+// Use a custom port if 61001 is taken, or if the IdP has a different one registered
 const abapBroker = new AuthBroker({
   serviceKeyStore: abapServiceKeyStore,
   sessionStore: abapSessionStore,
@@ -292,9 +479,8 @@ const abapBroker = new AuthBroker({
     uaaUrl: 'https://...',
     clientId: '...',
     clientSecret: '...',
-    browser: 'system',
-    redirectPort: 4001,
-  }), // Custom port to avoid conflicts
+    authorization: browserCallbackStrategy({ browser: 'system', port: 4001 }),
+  }),
 });
 ```
 
@@ -305,13 +491,16 @@ const abapBroker = new AuthBroker({
 Uses browser-based OAuth2 flow or refresh token:
 
 ```typescript
-import { AuthorizationCodeProvider } from '@mcp-abap-adt/auth-providers';
+import {
+  AuthorizationCodeProvider,
+  browserCallbackStrategy,
+} from '@mcp-abap-adt/auth-providers';
 
 const provider = new AuthorizationCodeProvider({
   uaaUrl: 'https://...authentication...hana.ondemand.com',
   clientId: '...',
   clientSecret: '...',
-  browser: 'system',
+  authorization: browserCallbackStrategy({ browser: 'system' }),
 });
 
 // If refreshToken is provided here, uses refresh flow (no browser)
@@ -341,30 +530,58 @@ 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.
+#### DeviceFlowProvider
+
+`DeviceFlowProviderConfig` now accepts `logger?: ILogger`. The verification URI
+and the user code are a prompt the user must see, not a log line: they go to the
+logger when one is supplied and to **stderr** otherwise. They no longer go to
+stdout — capturing stdout to read the device code will read nothing, and the
+change exists because stdout carries protocol traffic under an MCP or LSP stdio
+transport. `OidcDeviceFlowProvider` behaves the same way.
+
+#### Callback port and lifetime
+
+**Note**: the callback port is set on the strategy (`browserCallbackStrategy({ port })`
+and its OIDC/SAML siblings), not on the provider — the 1.x `redirectPort` field
+is gone. The default is **61001**, was 3001. If the requested port is already in
+use, an error is thrown; specify a different port or free it before starting
+authentication. `port: 0` binds an ephemeral port, which works only where the
+identity provider accepts a loopback redirect on any port.
+
+**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**: 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. 
+**Timeout**: an interactive login waits 30 seconds for its callback, adjustable with `timeoutMs`. 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.
 
-**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.
+**Incomplete callbacks**: a `/callback` carrying neither a code nor an error no longer ends the login. It is answered, counted, and the tally is reported if the login later times out — so a browser prefetch or a stray probe cannot cancel a login the user is still completing.
+
+**Cancellation**: pass `signal` to the strategy, or call `dispose()` on it. Both are honoured before the bind, during it, and while waiting; `dispose()` resolves only once the socket is free.
+
+**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 removed in 1.2.0. 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).
 - **Windows**: Uses proper `cmd /c start ""` syntax for reliable browser opening.
 - **macOS**: Uses native `open -a` command.
 
-**Headless Mode (SSH/Remote)**: For environments without a display (SSH sessions, Docker, CI/CD), use `browser: 'headless'`:
+**Headless Mode (SSH/Remote)**: For environments without a display (SSH sessions, Docker, CI/CD), leave `browser` at its default or set it explicitly:
 
 ```typescript
+const provider = new AuthorizationCodeProvider({
+  uaaUrl, clientId, clientSecret,
+  authorization: browserCallbackStrategy({ browser: 'headless' }),
+});
+
 const result = await provider.getTokens();
 ```
 
-In headless mode, the authentication URL is logged and the server waits for the user to complete authentication manually. The user can open the URL on any machine and the callback will be received by the server.
+In headless mode the authorization URL is shown — to the logger if there is one, to stderr otherwise — and the server waits for the user to complete authentication manually. The user can open the URL on any machine, and the callback reaches the server because it listens on all interfaces; the shipped UAA transport also prints where to paste the code if the redirect cannot reach back.
 
-**Browser Options**:
-- `'system'` (default): Opens system default browser
-- `'headless'`: Logs URL, waits for manual callback (SSH/remote)
-- `'none'`: Logs URL, immediately rejects (automated tests)
-- `'chrome'`, `'edge'`, `'firefox'`: Opens specific browser
+**Browser Options** (`browserCallbackStrategy({ browser })`):
+- `'none'` (default): Shows the URL, waits for the callback or a paste
+- `'headless'`: Same as `'none'`
+- `'system'`: Opens the system default browser
+- `'auto'`: Tries to open a browser; on failure the URL is shown and the login continues
+- `'chrome'`, `'edge'`, `'firefox'`: Opens a specific browser
 
 ### Token Validation
 
@@ -456,6 +673,102 @@ try {
 
 All error codes are defined in `@mcp-abap-adt/interfaces` package as `TOKEN_PROVIDER_ERROR_CODES`.
 
+## Migrating from 1.x to 2.0
+
+Every field that described *how* an interactive login is conducted is gone from
+the provider configs, replaced by a single `authorization` strategy.
+
+| 1.x field | 2.0 |
+|---|---|
+| `browser: 'system'` | `authorization: browserCallbackStrategy({ browser: 'system' })` |
+| `browser: 'system'`, `redirectPort: 4001` | `authorization: browserCallbackStrategy({ browser: 'system', port: 4001 })` |
+| `redirectUri: uri` (OIDC) | `redirectUri` on the strategy — the strategy owns it |
+| `authorizationCode: 'abc'` (OIDC) | `authorization: asOidcResult(staticCodeStrategy({ redirectUri, payload: 'abc' }))` |
+| `authorizationCodeProvider: fn` (OIDC) | `authorization: asOidcResult(externalCodeStrategy({ redirectUri, provide: fn }))` |
+| `assertionFlow: 'browser'` (SAML) | `authorization: samlCallbackStrategy()` — or omit `authorization` entirely |
+| `assertionFlow: 'manual'`, `manualInput: fn` (SAML) | `authorization: manualSamlResponseStrategy({ redirectUri: acsUrl, read: fn })` |
+| `assertionFlow: 'assertion'`, `assertionProvider: fn` (SAML) | `authorization: externalCodeStrategy({ redirectUri: acsUrl, provide: fn })` |
+
+Four things in that table are easy to get wrong.
+
+**The default callback port changed from 3001 to 61001** — for the UAA flow and
+for SAML alike, the latter because the SAML ACS used to default to
+`http://localhost:3001/callback` and now comes from the strategy. If you relied
+on the default and registered `http://localhost:3001/callback` with your
+identity provider, **the IdP rejects the redirect**, so the error you see is
+foreign and says nothing about this package. Either register the new URI, or
+keep the old one with one line:
+
+```ts
+authorization: browserCallbackStrategy({ browser: 'system', port: 3001 })
+```
+
+(61001 was chosen because it sits above Linux's `ip_local_port_range`, so an
+outbound connection never squats on it, and well away from the 3001/3333 range
+that servers and proxies in this family use.)
+
+**`redirectUri` is not optional in the SAML manual and assertion migrations.**
+The rows above show it for a reason: `manualSamlResponseStrategy` and
+`externalCodeStrategy` default their redirect URI to
+`http://localhost:61001/callback`, and both SAML providers require the ACS they
+were told about to match the URI the strategy names. Declare a real `acsUrl`,
+omit `redirectUri`, and the login fails the guard before anything opens:
+
+```
+SAML acsUrl is https://sp.example.com/saml/acs, but the authorization strategy
+is listening on http://localhost:61001/callback. They must match.
+```
+
+Pass `redirectUri: acsUrl` and it works. (Declaring neither leaves both at the
+default, which is consistent but only useful when the IdP posts to localhost.)
+
+**`asOidcResult` is required for `OidcBrowserProvider`.** It takes
+`IAuthorizationStrategy<OidcCallbackResult>`; `staticCodeStrategy`,
+`externalCodeStrategy` and `manualPasteStrategy` yield a `string`. The obvious
+one-line migration does not type-check without the adapter:
+
+```ts
+// 1.x
+new OidcBrowserProvider({ clientId, tokenEndpoint, authorizationEndpoint,
+  authorizationCode: 'abc', redirectUri: 'urn:ietf:wg:oauth:2.0:oob' });
+
+// 2.0
+const redirectUri = 'urn:ietf:wg:oauth:2.0:oob';
+new OidcBrowserProvider({ clientId, tokenEndpoint, authorizationEndpoint,
+  authorization: asOidcResult(staticCodeStrategy({ redirectUri, payload: 'abc' })) });
+
+// 2.0, code fetched by your own flow
+new OidcBrowserProvider({ clientId, tokenEndpoint, authorizationEndpoint,
+  authorization: asOidcResult(externalCodeStrategy({ redirectUri, provide: fetchCode })) });
+```
+
+`samlCallbackStrategy` needs no adapter: SAML strategies yield a string and the
+SAML providers take a string.
+
+**`acsUrl` is now required whenever `authorizationUrl` is set** on either SAML
+provider, and is rejected at construction rather than at login. 1.x accepted the
+combination and silently defaulted the ACS to `http://localhost:3001/callback`;
+since the real ACS is buried in a deflated `SAMLRequest` this package did not
+build, it cannot be inferred and must be declared.
+
+Three more changes that are not fields:
+
+- **The terminal-paste channel is gone from the browser strategy.** In 1.x a
+  `none` / `headless` login also accepted the code on stdin, without the
+  consumer choosing anything. `browserCallbackStrategy` no longer reads stdin at
+  all — under a stdio RPC transport that stream carries the protocol. If your
+  users pasted codes into the terminal, switch that flow to
+  `manualPasteStrategy({ redirectUri, read })`, which is the same capability as
+  an explicit choice; otherwise the paste form on `/` is the remaining fallback
+  for a browser on another machine.
+- **Device flow prompts no longer go to stdout.** `DeviceFlowProviderConfig`
+  accepts `logger?: ILogger`; the verification URI and user code go to that
+  logger, or to stderr when there is none. Anything that captured stdout to read
+  the device code must read stderr or supply a logger.
+- **A `/callback` carrying neither a code nor an error no longer ends the
+  login.** It is answered and counted, and the tally appears in the timeout
+  message if the login later expires.
+
 ## Testing
 
 The package includes both unit tests (with mocks) and integration tests (with real files and services).
@@ -496,8 +809,8 @@ Integration tests will skip if `test-config.yaml` is not configured or contains
 **Note**: 
 - Integration tests use `AbapServiceKeyStore` and `AbapSessionStore` for loading service keys and sessions
 - Tests may open a browser for authentication if no refresh token is available. This is expected behavior.
-- Each test scenario uses a unique port (3101, 3102, 3103) to avoid port conflicts
-- Tests use `browser: 'system'` for interactive authentication (not `'none'`)
+- The interactive test asks the OS for a free port rather than pinning one, so it cannot collide with a running server
+- Tests use `browserCallbackStrategy({ browser: 'system' })` for interactive authentication (not `'none'`)
 
 ### Debug Logging
 
@@ -545,11 +858,13 @@ Example output:
 
 ## Dependencies
 
-- `@mcp-abap-adt/interfaces` (^0.2.2) - Interface definitions and error code constants
+- `@mcp-abap-adt/interfaces` (^11.6.0) - Interface definitions (`ITokenProvider`, `IAuthorizationStrategy`, `CallbackServerFactory`) and error code constants
 - `axios` - HTTP client
 - `express` - OAuth2 callback server
 - `open` - Browser opening utility
 
+Requires Node.js `>=18.2.0`.
+
 ## License
 
 MIT

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,
     });