@mcp-abap-adt/auth-providers 2.2.2 → 3.0.0

package/CHANGELOG.md

@@ -7,6 +7,94 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.0.0] - 2026-09-24
+
+### Added
+
+- **`UaaPasscodeProvider`** and **`manualPasscodeStrategy`** — the one-time
+  passcode `cf login --sso` uses, for UAA and XSUAA. The user fetches a
+  Temporary Authentication Code from `<uaaUrl>/passcode` in any browser,
+  logging in however the identity zone asks, and the provider exchanges it
+  through the password grant and refreshes afterwards — a headless SSO login
+  that XSUAA supports, unlike the device authorization grant. A rejected code
+  reports UAA's reason (`Invalid passcode`). Tested on the UAA stand.
+
+### Breaking
+
+- **Node.js 22 or 24** — `engines: "^22 || ^24"` (was `>=18.2.0`). The
+  supported versions now follow SAP BTP, Cloud Foundry, whose Node.js buildpack
+  offers exactly 22 and 24: Node 18 reached its end of life on 30 April 2025
+  and Node 20 on 30 April 2026, and SAP has removed 20 from Cloud Foundry. The
+  odd releases between them are excluded too — 23 reached end of life on 1 June
+  2025 and 25 on 1 June 2026 — and so is 26 until SAP offers it. CI tests on 22
+  and 24 instead of 18.
+
+  **Migrating:** run on Node 22 or 24. Nothing in the API changed.
+- **`DeviceFlowProvider` is removed**, with `DeviceFlowProviderConfig` and the
+  `auth-device-flow` command. It sent the device authorization grant to
+  `${uaaUrl}/oauth/device_authorization`, a path no server we could find
+  serves: Cloud Foundry UAA has no device grant, XSUAA answers that path with a
+  redirect to its login page and advertises no `device_authorization_endpoint`,
+  and servers that do implement RFC 8628 — Keycloak, Spring Authorization
+  Server, Ory Hydra, Zitadel, Dex — publish it elsewhere. Its live tests had
+  long been skipped.
+
+  **Migrating:** for a server that implements RFC 8628, use
+  `OidcDeviceFlowProvider` — it finds the endpoints through discovery
+  (`issuerUrl`) or takes them explicitly, and is tested against Keycloak. For a
+  headless login to UAA or XSUAA, use `UaaPasscodeProvider`: the user fetches
+  a one-time code from `<uaaUrl>/passcode` in any browser, as with
+  `cf login --sso`.
+
+### Fixed
+
+- **`Saml2BearerProvider` sends what RFC 7522 accepts** (#37). It forwarded
+  the strategy's payload as is — after an interactive login, the whole
+  `SAMLResponse` in standard base64 — where §2.1 takes one Assertion,
+  base64url-encoded. Cloud Foundry UAA answers 401 to a Response in either
+  encoding, so the provider could not get a token through any interactive
+  strategy. It now takes the Assertion out of a Response (copying onto it
+  every namespace declaration it inherited, including one used only inside an
+  `xsi:type` value, and keeping its signature) and sends it
+  base64url-encoded; a bare Assertion in either encoding is re-encoded. A
+  Response with no Assertion, several, or only an `EncryptedAssertion` is
+  refused before anything is sent. `@xmldom/xmldom` becomes a dependency.
+
+### Development
+
+- **Every provider but two is tested against a real authorization server** in
+  Docker: Cloud Foundry UAA — the server XSUAA is built from — and Keycloak.
+  `npm run test:stand` starts both, runs the suites and stops them, and CI runs
+  the same as its own job on Node 22 and 24.
+  - UAA: `Saml2BearerProvider` (confirming end to end what #23 was about: a
+    refresh token is issued with the saml2-bearer token when the client may
+    hold one, and spent without running the authorization strategy),
+    `ClientCredentialsProvider`, `AuthorizationCodeProvider` with refresh.
+  - Keycloak: `OidcPasswordProvider` with refresh, `OidcBrowserProvider` with
+    S256 PKCE, `OidcDeviceFlowProvider`, `OidcTokenExchangeProvider`
+    (RFC 8693).
+  - Keycloak as the SAML identity provider: `Saml2BearerProvider` end to end
+    into UAA, with no assertion built by the tests, and the identity-provider
+    half of `Saml2PureProvider`. This showed that UAA's bearer grant refuses
+    the answer to an SP-initiated login for its `InResponseTo`, and accepts an
+    IdP-initiated one; the README says so under `Saml2BearerProvider`.
+  - Interactive logins go through each server's own login and consent pages,
+    submitted over HTTP by a test helper.
+  - Not covered: `DeviceFlowProvider`, whose `/oauth/device_authorization`
+    neither server serves, and `Saml2PureProvider`'s cookie exchange, which is
+    the consumer's `cookieProvider`.
+
+- **Live checks against a real XSUAA** — `npm run test:xsuaa`, not in CI —
+  create an XSUAA instance and a SAML trust in a BTP subaccount, run, and
+  remove them. On a trial subaccount: `Saml2BearerProvider` gets a token and a
+  refresh token from an IdP-initiated assertion, converts a whole
+  `SAMLResponse`, refreshes without its strategy, and is refused an assertion
+  carrying `InResponseTo`, exactly as by UAA; `UaaPasscodeProvider` works,
+  including — checked by hand — with an ABAP environment's own service key,
+  whose token opens ADT.
+  `@mcp-abap-adt/auth-mocks` becomes a devDependency, for signing assertions.
+  The stand itself is not published.
+
 ## [2.2.2] - 2026-09-24
 
 ### Dependencies

package/README.md

@@ -15,8 +15,17 @@ npm install @mcp-abap-adt/auth-providers
 
 This package implements the `ITokenProvider` interface from `@mcp-abap-adt/interfaces-auth`:
 
-- **AuthorizationCodeProvider** - Uses browser-based OAuth2 authorization code flow (user token)
-- **ClientCredentialsProvider** - Uses `client_credentials` grant type (no browser required)
+- **ClientCredentialsProvider** — `client_credentials`, no user interaction
+- **AuthorizationCodeProvider** — UAA/XSUAA authorization code, through a browser
+- **UaaPasscodeProvider** — UAA/XSUAA one-time passcode from `/passcode`, the
+  login `cf login --sso` uses: SSO without a browser on this machine
+- **OidcBrowserProvider** — OIDC authorization code with PKCE
+- **OidcDeviceFlowProvider** — OAuth 2.0 device authorization grant (RFC 8628)
+- **OidcPasswordProvider**, **OidcTokenExchangeProvider** — password grant and
+  token exchange (RFC 8693)
+- **Saml2BearerProvider** — a SAML assertion exchanged for an OAuth2 token
+  (RFC 7522)
+- **Saml2PureProvider** — a SAML assertion exchanged for session cookies
 
 Providers are configured via constructor; `getTokens()` takes no parameters and handles refresh/login internally.
 
@@ -27,7 +36,8 @@ 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).
+if you are on an earlier major, [Migrating from 2.x to 3.0](#migrating-from-2x-to-30)
+and [Migrating from 1.x to 2.0](#migrating-from-1x-to-20).
 
 ## Responsibilities and Design Principles
 
@@ -378,6 +388,29 @@ const provider = new Saml2BearerProvider({
 const broker = new AuthBroker({ tokenProvider: provider }, 'none');
 ```
 
+**Who starts the login matters.** An identity provider answering an
+`AuthnRequest` — which is what the provider's own URL, and every shipped SAML
+strategy, sends — puts `InResponseTo` on the assertion's subject
+confirmation. UAA's saml2-bearer grant refuses any assertion that carries it:
+there is no request on its side to match it against, and UAA's
+`disableInResponseToCheck` applies to web SSO only. Measured against Cloud
+Foundry UAA with Keycloak as the identity provider, an SP-initiated login is
+refused with *"SubjectConfirmationData/@InResponseTo … did not match the valid
+value: null"*, and an IdP-initiated one — started at the IdP, answering no
+request — is accepted. Against UAA, supply the assertion from an IdP-initiated
+login, for instance through `externalCodeStrategy` whose `provide` ignores the
+URL it is handed. Whether XSUAA behaves the same has not been verified.
+
+**What is sent.** The saml2-bearer grant takes one SAML Assertion,
+base64url-encoded (RFC 7522 §2.1). A strategy may deliver either that or the
+whole `SAMLResponse` an identity provider posts, in standard base64 —
+`Saml2BearerProvider` takes the Assertion out of a Response and re-encodes it,
+copying onto it every namespace declaration it inherited — including one used
+only inside a value such as `xsi:type="xs:string"`. The Assertion must carry
+its own signature: one over the Response alone does not survive the cut, and
+the token endpoint refuses the Assertion. An `EncryptedAssertion` is refused
+before anything is sent.
+
 **Refresh.** When the token endpoint returns a `refresh_token` with the SAML
 bearer exchange, `Saml2BearerProvider` spends it once the access token expires:
 a `refresh_token` grant to the same endpoint (`tokenUrl`, or `uaaUrl` +
@@ -538,14 +571,39 @@ const result = await provider.getTokens();
 // result.refreshToken is undefined (client_credentials doesn't provide refresh tokens)
 ```
 
-#### DeviceFlowProvider
+#### UaaPasscodeProvider
+
+The login `cf login --sso` uses, for UAA and XSUAA: a one-time **Temporary
+Authentication Code**. Nothing opens and nothing listens on this machine — the
+user opens `<uaaUrl>/passcode` in any browser, on any device, logs in however
+the identity zone asks (SSO through a corporate IdP, MFA), and copies the code
+shown there. The provider exchanges it for tokens and refreshes them, so the
+code is asked for again only when the refresh token is gone. It suits an MCP
+server on a remote machine, in a container, or behind SSH.
+
+```typescript
+import { UaaPasscodeProvider, manualPasscodeStrategy } from '@mcp-abap-adt/auth-providers';
+
+const provider = new UaaPasscodeProvider({
+  uaaUrl: 'https://<subdomain>.authentication.<region>.hana.ondemand.com',
+  clientId: '...', // a client allowed the `password` grant (and `refresh_token`)
+  clientSecret: '...', // omit for a public client
+  // The default: announce <uaaUrl>/passcode, read the code from the terminal.
+  // Supply `read` to take it from anywhere else — never from stdin under MCP.
+  authorization: manualPasscodeStrategy({ read: askTheUser }),
+});
+```
+
+The exchange is the password grant with `passcode` instead of a username and
+password — a UAA extension, not an RFC. A code is single-use; a mistyped or
+spent one fails with `Passcode exchange failed (401): Invalid passcode`.
 
-`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.
+#### Device flow prompts
+
+`OidcDeviceFlowProvider` 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 — never to stdout,
+which carries protocol traffic under an MCP or LSP stdio transport.
 
 #### Callback port and lifetime
 
@@ -681,6 +739,39 @@ try {
 
 All error codes are defined in `@mcp-abap-adt/interfaces-auth` package as `TOKEN_PROVIDER_ERROR_CODES`.
 
+## Migrating from 2.x to 3.0
+
+3.0.0 changes no provider's configuration, but it drops a provider, a command
+and the Node versions nothing supports any more.
+
+- **Node.js 22 or 24.** `engines` is `"^22 || ^24"`, following SAP BTP, Cloud
+  Foundry. Node 18 and 20 are past their end of life and SAP has removed 20;
+  23 and 25, odd releases, are too. Move the process to 22 or 24.
+- **`DeviceFlowProvider` is gone**, with `DeviceFlowProviderConfig` and the
+  `auth-device-flow` command. It sent the device grant to
+  `<uaaUrl>/oauth/device_authorization`, which no server we know of serves —
+  neither UAA nor XSUAA offers the device grant at all. Replace it with:
+
+  ```typescript
+  // A server that implements RFC 8628 (Keycloak, Spring Authorization Server, …):
+  new OidcDeviceFlowProvider({ issuerUrl, clientId, logger });
+
+  // UAA or XSUAA — a headless SSO login, the way `cf login --sso` does it:
+  new UaaPasscodeProvider({
+    uaaUrl, clientId, clientSecret,
+    authorization: manualPasscodeStrategy({ read: askTheUser }),
+  });
+  ```
+
+- **`Saml2BearerProvider` now sends one base64url Assertion** (RFC 7522),
+  taken out of the `SAMLResponse` a login delivers. Before, it forwarded the
+  whole response, which UAA and XSUAA refuse — so nothing that worked stops
+  working. Note what the live checks showed, though: both refuse an assertion
+  carrying `InResponseTo`, which an identity provider sets whenever it answers
+  an AuthnRequest. Against them, supply an IdP-initiated assertion — see
+  *Who starts the login matters* under `Saml2BearerProvider`.
+- `@xmldom/xmldom` is a new runtime dependency, for that conversion.
+
 ## Migrating from 1.x to 2.0
 
 Every field that described *how* an interactive login is conducted is gone from
@@ -770,9 +861,11 @@ Three more changes that are not fields:
   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
+  accepted `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.
+  the device code must read stderr or supply a logger. (`DeviceFlowProvider`
+  itself was removed in 3.0.0 — see the changelog; `OidcDeviceFlowProvider`
+  behaves the same way.)
 - **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.
@@ -820,6 +913,127 @@ Integration tests will skip if `test-config.yaml` is not configured or contains
 - 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'`)
 
+### Providers against real authorization servers (UAA and Keycloak)
+
+The providers are also tested against two real, widely used authorization
+servers running locally in Docker from their official images — [Cloud Foundry
+UAA](https://github.com/cloudfoundry/uaa) (`cfidentity/uaa`), the open-source
+server XSUAA is built from, and [Keycloak](https://www.keycloak.org/)
+(`quay.io/keycloak/keycloak`). It needs Docker and nothing else — no SAP
+system, no setup step:
+
+```bash
+npm run test:stand    # start UAA and Keycloak, run the suites, stop both
+```
+
+`test:stand` starts both containers with `docker compose`, waits until both
+answer, runs the suites, and stops the containers again — also when a test
+fails, with the suites' exit code, after printing the last 200 lines of each
+server's log. A full run takes well under a minute. CI runs exactly this as its
+own job, on Node 22 and 24. To keep the stand up between runs, start it
+yourself; `test:stand` then leaves it running. Ownership is per server: if only
+one of the two was running, the run starts the other and removes only that one
+afterwards:
+
+```bash
+npm run stand:up      # start and keep running
+npm run test:stand    # as often as needed
+npm run stand:down    # stop
+```
+
+`STAND_KEEP=1 npm run test:stand` keeps a stand the run started. `UAA_PORT`
+(8080) and `KEYCLOAK_PORT` (8081) move the servers. A server that is already
+running is never changed: if it is published on another port than the one
+asked for, `test:stand` refuses and says so, rather than let Compose recreate
+it.
+
+| provider | server | what the suite proves |
+|---|---|---|
+| `Saml2BearerProvider` | UAA | a bearer assertion — and a whole `SAMLResponse` — is exchanged for a token; UAA issues a refresh token exactly when the client may hold one, and the provider refreshes without its authorization strategy |
+| `Saml2BearerProvider` | Keycloak → UAA | end to end with no assertion built by the tests: an IdP-initiated Keycloak login becomes a UAA token; the answer to the provider's own AuthnRequest is refused for its `InResponseTo` |
+| `Saml2PureProvider` | Keycloak | the identity-provider half: Keycloak accepts the provider's AuthnRequest and posts a signed response for that service provider to the ACS it named, which reaches `cookieProvider` unchanged |
+| `ClientCredentialsProvider` | UAA | a client token |
+| `UaaPasscodeProvider` | UAA | a code fetched from `/passcode` after logging in there, exchanged for tokens; a refresh that does not ask for another code; a spent code refused |
+| `AuthorizationCodeProvider` | UAA | a login through UAA's own form, and a refresh without logging in again |
+| `OidcPasswordProvider` | Keycloak | the password grant through discovery, and a refresh that works with a wrong password — so it is a refresh, not a second login |
+| `OidcBrowserProvider` | Keycloak | authorization code with S256 PKCE, which the client requires, through Keycloak's login page |
+| `OidcDeviceFlowProvider` | Keycloak | a token once the user logs in and grants access on Keycloak's device pages, read from the verification URI the provider announces |
+| `OidcTokenExchangeProvider` | Keycloak | RFC 8693: another client's access token exchanged for the requester's own |
+
+The servers' configuration is committed as test fixtures —
+`tests/stand/uaa/config/uaa.yml`, `tests/stand/keycloak/realm-test.json` and the
+test identity provider's key in `tests/stand/uaa/idp/` — so every machine and CI
+run the same stand. The keys and passwords in them are trusted by nothing but
+that local stand; they are not secrets, and must not be reused.
+
+For the Keycloak → UAA case the suite makes UAA trust Keycloak at run time —
+it registers Keycloak as a SAML identity provider through UAA's API, from the
+metadata Keycloak publishes — and configures Keycloak's IdP-initiated SSO to
+post to UAA's bearer ACS, since both depend on the ports and on keys Keycloak
+generates when it starts.
+
+Interactive logins are played by `src/__tests__/integration/stand/formLogin.ts`,
+which submits each server's own login and consent forms over HTTP.
+
+Not covered: the cookie half of `Saml2PureProvider`, which belongs to the
+consumer's `cookieProvider` and needs a real SAP system.
+
+A plain `npm test` skips these suites: they run only with `UAA_URL` or
+`KEYCLOAK_URL` set, which `test:stand` does.
+
+### Live checks against XSUAA (BTP subaccount)
+
+The stand proves the wire contracts against open-source servers. What only a
+real XSUAA can answer is checked by `npm run test:xsuaa`, against a BTP
+subaccount you are logged in to — a trial one is enough:
+
+```bash
+cf login -a https://api.cf.<region>.hana.ondemand.com --sso -o <org> -s <space>
+XSUAA_CF_API=https://api.cf.<region>.hana.ondemand.com XSUAA_CF_ORG=<org> \
+  XSUAA_CF_SPACE=<space> npm run test:xsuaa
+```
+
+It creates, in the targeted space, an `xsuaa`/`application` instance whose
+client may use saml2-bearer, refresh_token and password; an `xsuaa`/`apiaccess`
+instance, used only to manage trust; and a SAML trust to a test identity
+provider whose key is generated locally and never leaves the gitignored
+`tests/xsuaa/.local/`. Then it runs the suite and removes all of it — also when
+a test fails. Two rules keep it from touching anything else:
+
+- **Target.** The scripts refuse to run unless `cf` targets exactly
+  `XSUAA_CF_API`, `XSUAA_CF_ORG` and `XSUAA_CF_SPACE`. There are no defaults, so
+  a `cf` left pointing at another org or space cannot receive anything.
+- **Ownership.** Everything setup creates is recorded in
+  `tests/xsuaa/.local/owned` with its immutable ID — the service instance's
+  GUID, the trust's id — and the record names the API, org and space it
+  belongs to. A resource is treated as ours only when its name and its current
+  ID both match a record, checked right before it is reused, refreshed or
+  deleted. A name held by anything else — never created here, or recreated
+  after ours was deleted — is refused by setup and left alone by teardown, and
+  a record from another target is refused outright.
+
+The run fails — non-zero — when the tests fail or the teardown does. A
+teardown that fails stops at once and keeps `tests/xsuaa/.local/`, keys and
+record included, so `tests/xsuaa/teardown.sh` can be run again to finish. A
+lookup that fails — no session, no network, an API error — is a failure, never
+read as "already gone": `cf service` exits 1 for both, so only its exact
+not-found message counts as absence.
+`XSUAA_KEEP=1` keeps the environment for another run. A full run takes about a minute and
+a half. It is not part of CI.
+
+| check | result on XSUAA |
+|---|---|
+| `Saml2BearerProvider`, assertion without `InResponseTo` (IdP-initiated) | token and refresh token |
+| `Saml2BearerProvider`, a whole `SAMLResponse` | converted by the provider, accepted |
+| `Saml2BearerProvider`, refresh | never reaches the strategy |
+| `Saml2BearerProvider`, assertion with `InResponseTo` | refused — as UAA does |
+| `UaaPasscodeProvider` (with `XSUAA_PASSCODE=<code from /passcode>`) | token, refresh |
+
+`UaaPasscodeProvider` was also checked by hand with an ABAP environment's own
+service key: its client accepts the passcode, and the token opens ADT. That
+depends on the user being known to the ABAP system — a user from an identity
+provider not propagated to it gets a token and a 401 from ADT.
+
 ### Debug Logging
 
 To enable detailed logging during tests or runtime, set environment variables:
@@ -869,11 +1083,15 @@ Example output:
 - `@mcp-abap-adt/interfaces-auth` (^1.2.0) - Token provider and authorization contracts (`ITokenProvider`, `IAuthorizationStrategy`, `CallbackServerFactory`) and error code constants
 - `@mcp-abap-adt/interfaces-auth-sap` (^1.0.0) - XSUAA authorization configuration (`IAuthorizationConfig`)
 - `@mcp-abap-adt/interfaces-utils` (^1.1.0) - `ILogger`
+- `@xmldom/xmldom` - XML parsing, to take the Assertion out of a SAMLResponse for the saml2-bearer grant
 - `axios` - HTTP client
 - `express` - OAuth2 callback server
 - `open` - Browser opening utility
 
-Requires Node.js `>=18.2.0`.
+Requires Node.js 22 or 24 (`engines: "^22 || ^24"`). The supported versions
+follow SAP BTP, Cloud Foundry, whose Node.js buildpack offers exactly these two;
+CI tests both. Odd-numbered releases are never supported — they reach end of
+life within months — and a new major joins only once SAP offers it.
 
 ## License
 

package/dist/__tests__/integration/stand/formLogin.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Plays the user in an interactive login against a stand server's own login
+ * page: follows redirects, keeps cookies, finds the form with a password
+ * field, fills it in with every hidden field it carries (UAA's CSRF token,
+ * Keycloak's session code), and submits it.
+ *
+ * Deliberately small: enough for UAA's and Keycloak's stock login pages, which
+ * the pinned image versions keep stable. It is a test helper, not a browser.
+ */
+export interface Credentials {
+    username: string;
+    password: string;
+}
+export declare class FormBrowser {
+    private readonly cookies;
+    /** GET `url` and follow redirects until `stop(url)` or a page is served. */
+    open(url: string, stop?: (next: string) => boolean): Promise<{
+        url: string;
+        html?: string;
+    }>;
+    /**
+     * Submit the login form on `page`, then follow redirects until `stop` says
+     * the next location is the one the caller wants — typically the client's
+     * redirect URI carrying the code — without requesting it.
+     */
+    submitLogin(page: {
+        url: string;
+        html?: string;
+    }, credentials: Credentials, stop?: (next: string) => boolean): Promise<{
+        url: string;
+        html?: string;
+    }>;
+    /**
+     * Accept a consent page ("Do you grant these access privileges?"): submit
+     * the form that carries an `accept` button, with its hidden fields.
+     */
+    acceptConsent(page: {
+        url: string;
+        html?: string;
+    }): Promise<{
+        url: string;
+        html?: string;
+    }>;
+    private follow;
+    private remember;
+    private cookieHeader;
+}
+/**
+ * Log in through the authorization URL and return the redirect URI the server
+ * sends the browser back to, with its `code` — not requested, since nothing
+ * listens there.
+ */
+export declare function authorizeByForm(authorizationUrl: string, redirectUri: string, credentials: Credentials): Promise<URL>;
+/**
+ * Approve a device authorization the way a user would: open the verification
+ * URI (with the user code already in it), log in, and grant access.
+ */
+export declare function approveDevice(verificationUriComplete: string, credentials: Credentials): Promise<void>;
+/**
+ * A SAML login at an identity provider: open the AuthnRequest URL, log in,
+ * and take the SAMLResponse from the auto-posting form the IdP answers with —
+ * what a browser would post to the assertion consumer service.
+ */
+export declare function samlResponseByForm(authnRequestUrl: string, credentials: Credentials): Promise<{
+    samlResponse: string;
+    acsUrl: string;
+}>;
+//# sourceMappingURL=formLogin.d.ts.map

package/dist/__tests__/integration/stand/formLogin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formLogin.d.ts","sourceRoot":"","sources":["../../../../src/__tests__/integration/stand/formLogin.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAID,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IAErD,4EAA4E;IACtE,IAAI,CACR,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAqB,GAC5C,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAI1C;;;;OAIG;IACG,WAAW,CACf,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EACpC,WAAW,EAAE,WAAW,EACxB,IAAI,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAqB,GAC5C,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAmB1C;;;OAGG;IACG,aAAa,CAAC,IAAI,EAAE;QACxB,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;YAgC7B,MAAM;IA4BpB,OAAO,CAAC,QAAQ;IAUhB,OAAO,CAAC,YAAY;CAGrB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,GAAG,CAAC,CAcd;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,uBAAuB,EAAE,MAAM,EAC/B,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,IAAI,CAAC,CAKf;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAgBnD"}

package/dist/__tests__/integration/stand/formLogin.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * Plays the user in an interactive login against a stand server's own login
+ * page: follows redirects, keeps cookies, finds the form with a password
+ * field, fills it in with every hidden field it carries (UAA's CSRF token,
+ * Keycloak's session code), and submits it.
+ *
+ * Deliberately small: enough for UAA's and Keycloak's stock login pages, which
+ * the pinned image versions keep stable. It is a test helper, not a browser.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FormBrowser = void 0;
+exports.authorizeByForm = authorizeByForm;
+exports.approveDevice = approveDevice;
+exports.samlResponseByForm = samlResponseByForm;
+const MAX_HOPS = 20;
+class FormBrowser {
+    cookies = new Map();
+    /** GET `url` and follow redirects until `stop(url)` or a page is served. */
+    async open(url, stop = () => false) {
+        return this.follow(url, { method: 'GET' }, stop);
+    }
+    /**
+     * Submit the login form on `page`, then follow redirects until `stop` says
+     * the next location is the one the caller wants — typically the client's
+     * redirect URI carrying the code — without requesting it.
+     */
+    async submitLogin(page, credentials, stop = () => false) {
+        const form = findPasswordForm(page.html ?? '');
+        if (!form) {
+            throw new Error(`no login form on ${page.url}`);
+        }
+        const body = new URLSearchParams(form.hidden);
+        body.set(form.userField, credentials.username);
+        body.set(form.passwordField, credentials.password);
+        return this.follow(new URL(form.action, page.url).toString(), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: body.toString(),
+        }, stop);
+    }
+    /**
+     * Accept a consent page ("Do you grant these access privileges?"): submit
+     * the form that carries an `accept` button, with its hidden fields.
+     */
+    async acceptConsent(page) {
+        for (const match of (page.html ?? '').matchAll(/<form\b[^>]*>[\s\S]*?<\/form>/gi)) {
+            const formHtml = match[0];
+            const inputs = [...formHtml.matchAll(/<(?:input|button)\b[^>]*>/gi)].map((m) => m[0]);
+            const accept = inputs.find((i) => attribute(i, 'name') === 'accept');
+            if (!accept)
+                continue;
+            const body = new URLSearchParams();
+            for (const input of inputs) {
+                const name = attribute(input, 'name');
+                if (name && attribute(input, 'type') === 'hidden') {
+                    body.set(name, attribute(input, 'value') ?? '');
+                }
+            }
+            body.set('accept', attribute(accept, 'value') ?? 'Yes');
+            const formTag = /<form\b[^>]*>/i.exec(formHtml)?.[0] ?? '';
+            return this.follow(new URL(attribute(formTag, 'action') ?? '', page.url).toString(), {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                body: body.toString(),
+            }, () => false);
+        }
+        throw new Error(`no consent form on ${page.url}`);
+    }
+    async follow(url, init, stop) {
+        let current = url;
+        let request = init;
+        for (let hop = 0; hop < MAX_HOPS; hop++) {
+            const response = await fetch(current, {
+                ...request,
+                redirect: 'manual',
+                headers: { ...(request.headers ?? {}), Cookie: this.cookieHeader() },
+                signal: AbortSignal.timeout(15_000),
+            });
+            this.remember(response);
+            const location = response.headers.get('location');
+            if (response.status >= 300 && response.status < 400 && location) {
+                const next = new URL(location, current).toString();
+                if (stop(next))
+                    return { url: next };
+                current = next;
+                request = { method: 'GET' };
+                continue;
+            }
+            return { url: current, html: await response.text() };
+        }
+        throw new Error(`more than ${MAX_HOPS} redirects from ${url}`);
+    }
+    remember(response) {
+        for (const line of response.headers.getSetCookie()) {
+            const [pair] = line.split(';');
+            const eq = pair.indexOf('=');
+            if (eq > 0) {
+                this.cookies.set(pair.slice(0, eq).trim(), pair.slice(eq + 1).trim());
+            }
+        }
+    }
+    cookieHeader() {
+        return [...this.cookies].map(([k, v]) => `${k}=${v}`).join('; ');
+    }
+}
+exports.FormBrowser = FormBrowser;
+/**
+ * Log in through the authorization URL and return the redirect URI the server
+ * sends the browser back to, with its `code` — not requested, since nothing
+ * listens there.
+ */
+async function authorizeByForm(authorizationUrl, redirectUri, credentials) {
+    const reached = (next) => next.startsWith(redirectUri);
+    const browser = new FormBrowser();
+    const page = await browser.open(authorizationUrl, reached);
+    const done = page.html === undefined
+        ? page
+        : await browser.submitLogin(page, credentials, reached);
+    if (!reached(done.url)) {
+        throw new Error(`login did not return to ${redirectUri}; ended at ${done.url}`);
+    }
+    return new URL(done.url);
+}
+/**
+ * Approve a device authorization the way a user would: open the verification
+ * URI (with the user code already in it), log in, and grant access.
+ */
+async function approveDevice(verificationUriComplete, credentials) {
+    const browser = new FormBrowser();
+    const page = await browser.open(verificationUriComplete);
+    const consent = await browser.submitLogin(page, credentials);
+    await browser.acceptConsent(consent);
+}
+/**
+ * A SAML login at an identity provider: open the AuthnRequest URL, log in,
+ * and take the SAMLResponse from the auto-posting form the IdP answers with —
+ * what a browser would post to the assertion consumer service.
+ */
+async function samlResponseByForm(authnRequestUrl, credentials) {
+    const browser = new FormBrowser();
+    const page = await browser.submitLogin(await browser.open(authnRequestUrl), credentials);
+    const html = page.html ?? '';
+    const input = [...html.matchAll(/<input\b[^>]*>/gi)]
+        .map((m) => m[0])
+        .find((i) => attribute(i, 'name') === 'SAMLResponse');
+    const samlResponse = input ? attribute(input, 'value') : undefined;
+    const formTag = /<form\b[^>]*>/i.exec(html)?.[0] ?? '';
+    if (!samlResponse) {
+        throw new Error(`no SAMLResponse form on ${page.url}`);
+    }
+    return { samlResponse, acsUrl: attribute(formTag, 'action') ?? '' };
+}
+const decode = (value) => value
+    .replace(/&amp;/g, '&')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>');
+const attribute = (tag, name) => {
+    const match = new RegExp(`\\s${name}\\s*=\\s*("([^"]*)"|'([^']*)')`, 'i').exec(tag);
+    return match ? decode(match[2] ?? match[3] ?? '') : undefined;
+};
+function findPasswordForm(html) {
+    for (const match of html.matchAll(/<form\b[^>]*>[\s\S]*?<\/form>/gi)) {
+        const formHtml = match[0];
+        const inputs = [...formHtml.matchAll(/<input\b[^>]*>/gi)].map((m) => m[0]);
+        const password = inputs.find((i) => attribute(i, 'type') === 'password');
+        if (!password)
+            continue;
+        const hidden = {};
+        let userField = 'username';
+        for (const input of inputs) {
+            const type = (attribute(input, 'type') ?? 'text').toLowerCase();
+            const name = attribute(input, 'name');
+            if (!name)
+                continue;
+            if (type === 'hidden')
+                hidden[name] = attribute(input, 'value') ?? '';
+            if ((type === 'text' || type === 'email') &&
+                /user|email|login/i.test(name)) {
+                userField = name;
+            }
+        }
+        const formTag = /<form\b[^>]*>/i.exec(formHtml)?.[0] ?? '';
+        return {
+            action: attribute(formTag, 'action') ?? '',
+            userField,
+            passwordField: attribute(password, 'name') ?? 'password',
+            hidden,
+        };
+    }
+    return undefined;
+}