@mcp-abap-adt/auth-broker 3.1.0 → 4.1.0

package/CHANGELOG.md

@@ -11,6 +11,537 @@ Thank you to all contributors! See [CONTRIBUTORS.md](../../CONTRIBUTORS.md) for
 
 ## [Unreleased]
 
+## [4.1.0] - 2026-10-05
+
+**x509 service keys.** A client that authenticates to the authorization
+server with a certificate instead of a secret — an XSUAA service key created
+with `{"credential-type": "x509"}` — when the consumer says so, through a
+strategy. Additive: without the new option every destination is served
+exactly as by 4.0.0, and nothing certificate-related is read. Released with
+`@mcp-abap-adt/auth-broker-cli` 2.1.0.
+
+### Added
+
+- **`AuthBrokerConfig.clientAuthentication`** — a `ClientAuthenticationStrategy`
+  `(context) => Promise<IClientAuthentication>`: how the client of every grant
+  that authenticates one (`authorization_code`, `client_credentials`,
+  `passcode`, `oidc_authorization_code`, `device_code`, `password`,
+  `token_exchange`, `saml2_bearer` — `ClientAuthenticationGrant`)
+  authenticates. Called once per build with a `ClientAuthenticationContext`
+  (`destination`, `grant`, the key store's secret `client` — `uaaUrl`,
+  `uaaClientId`, `uaaClientSecret` only, never a refresh token — or `null`, and a
+  lazy, memoised `readCertificate()`); its answer goes to the provider as
+  `clientAuthentication`, with no client secret. No default and no "nothing"
+  answer: a stated choice never falls back to the secret.
+- **`fromServiceKeyCertificate()`** — auth-providers' `tlsClientCertificate`
+  from the key store's certificate client, against `<certUrl>/oauth/token`
+  (a trailing `/` of `certUrl` dropped), the material checked before it
+  answers. **`fromServiceKeySecret({ encoding: 'raw' | 'form' })`** —
+  `clientSecretBasic` with the secret client; `encoding` required (`raw` for
+  XSUAA, measured). Each fails closed; a fallback is the consumer's
+  composition, decided by what the key holds (`readCertificate()`), never by
+  catching a refusal.
+- **The certificate client** is read through the optional
+  `IServiceKeyStore.getClientCertificate` (`@mcp-abap-adt/interfaces-auth-broker`
+  1.2.0) — auth-stores 3.3.0 answers it for an x509 XSUAA key and for an
+  `EnvDestinationStore` stating `SAP_UAA_CLIENT_CERT_PATH`,
+  `SAP_UAA_CLIENT_KEY_PATH` and `SAP_UAA_CERT_URL` (`XSUAA_UAA_*`) — only
+  when the strategy asks, at most once per build. The row's client is then
+  its identity: the secret client's `uaaUrl` / `uaaClientId`, else the
+  certificate client's.
+- **The token API factory's fourth argument, `TokenProviderClient`** —
+  beside a strategy, for a grant that authenticates a client: the strategy's
+  `clientAuthentication`, the client identity (`uaaUrl`, `clientId`) and the
+  stored `refreshToken` when the session is bound here — taken only from the
+  session read whose binding was checked, never from a client's own read.
+  Never a certificate, key or secret. Additive: a 4.0.0 factory keeps working.
+- **Fixed-words refusals**: whatever a strategy, a store it reads or the
+  certificate check throws — and an answer that is no `IClientAuthentication`
+  — is a `DestinationConfigError` naming `clientAuthentication` before any
+  provider exists, its words chosen by the error's class (no certificate, no
+  secret, incomplete / expired / unusable certificate, no client
+  authentication, the certificate could not be read, the strategy failed); a
+  factory that throws beside a strategy is one naming `provider`,
+  `clientAuthentication`. No `cause`, nothing of the thrown message, no PEM
+  anywhere — log, refusal, error, session store.
+- Exports: `fromServiceKeyCertificate`, `fromServiceKeySecret`, and the
+  types `ClientAuthenticationStrategy`, `ClientAuthenticationContext`,
+  `ClientAuthenticationGrant`, `FromServiceKeySecretOptions`,
+  `TokenProviderClient`, `IClientCertificate`, `IClientAuthentication`.
+- `npm run test:live:x509`: the live check against a BTP subaccount (exact
+  `cf target` guard, a GUID ledger, teardown also on failure). Not in CI.
+
+### Changed
+
+- **A client row with no client and no strategy names the way out.** The
+  `DestinationConfigError` of a UAA, OIDC or `saml2_bearer` destination whose
+  key store answers no client (or one without a client id) keeps its
+  `missingFields`; its message adds `; a certificate client needs a
+  clientAuthentication strategy`.
+
+### On the strategy path (only with `clientAuthentication`)
+
+- **The binding is the client's identity**: `issuedBy` from the identity's
+  `uaaUrl` and `client_id`, so a certificate destination's tokens are reused
+  after the broker is recreated and dropped when the issuer or client id
+  changes — and a secret key and an x509 key of the same client id share one
+  session (switching keeps its token and refresh token).
+- **A resource neither side states matches**: means with no `serviceUrl`, or
+  one that does not parse (the CLI's XSUAA placeholder), and a session stored
+  without `issuedFor`; a resource stated on one side only never matches.
+  Without a strategy an absent resource still matches nothing.
+- **The token API with a factory**: the destination must state `authType`
+  (`jwt` / `saml`) and `grantType` (else `DestinationConfigError` naming
+  both); `saml2_pure` and `none` get three arguments; every stored secret —
+  the refresh token in `authConfig` and the fourth argument, the token,
+  cookies and expiry in `connConfig` — reaches the factory only when the
+  session is bound here, and a result without a refresh token carries forward
+  only a bound one. (Without a strategy, 4.0.0's carry-over stands.) An
+  instance `provider` gets no strategy. What the strategy and the factory
+  are handed is built from allowlists, never a store's answer passed whole:
+  the client (`uaaUrl`, `uaaClientId`, `uaaClientSecret`), the certificate
+  client (its five declared fields), and the seed (`serviceUrl`, `sapClient`,
+  `language`, `authType`, `grantType`, and the session secret's fields only
+  from a bound read).
+
+### Dependencies
+
+`@mcp-abap-adt/interfaces-auth-broker` `^1.2.0` (was `^1.1.0`),
+`@mcp-abap-adt/interfaces-auth` `^3.2.0` (was `^3.0.0`),
+`@mcp-abap-adt/auth-providers` `^5.3.0` (was `^5.2.1`); dev:
+`@mcp-abap-adt/auth-stores` `^3.3.0`.
+
+### Migrating from 4.0.0
+
+Nothing is required. Code that matched a `DestinationConfigError`'s message
+for a destination without a client should match `missingFields` or the class
+instead. To use an x509 key: auth-stores `^3.3.0` and
+`clientAuthentication: fromServiceKeyCertificate()` — then read the strategy
+path's rules above (identity binding, bound secrets only, the token API's
+grant refusal, the factory's fourth argument). See *Migrating from 4.0.0* in
+the README.
+
+### Measured, and not
+
+Measured: `client_credentials` with an x509 XSUAA key on a BTP trial,
+2026-10-05 (`credential-types: ["binding-secret", "x509"]`) — the broker
+(`getProvider` and the token API), `mcp-auth --client-auth certificate` and
+`generate-env-from-service-key --client-auth certificate`, each followed by a
+fresh broker over the written destination; all five live cases passed. Not
+measured: `authorization_code` and `passcode` over x509, the OIDC grants and
+`saml2_bearer` with a strategy, ABAP environment service keys with x509.
+
+### Known limitations
+
+- **The certificate is pinned for the broker's lifetime.** It is read when a
+  destination's provider is built, and the provider is cached per
+  destination for as long as the `AuthBroker` lives. An XSUAA x509
+  certificate lives about seven days: a long-running process then gets "the
+  client certificate has expired" until it builds a new `AuthBroker`, and
+  replacing the key or the PEM files changes nothing before that. Rotation is
+  out of scope.
+- The certificate refusals use the broker's own three phrases (incomplete /
+  expired / could not be used), classified by auth-providers'
+  `CertificateMaterialError` flags; the provider's own hint for each is not
+  relayed. auth-providers' exported refusal words (a later minor) would
+  replace them.
+
+## [4.0.0] - 2026-10-02
+
+**What 4.0.0 is.** The broker hands a process **the credential for a
+destination, ready to use**: `getProvider(destination)` returns the
+`IAuthProvider` (`@mcp-abap-adt/interfaces-auth` 3) the destination states —
+basic, SNC, a UAA, OIDC or SAML grant, or a credential handed over — which a
+`@mcp-abap-adt/connection` 10 connector takes as it is, and whatever that
+provider obtains or renews is stored in the session store, whoever triggered
+it. The token API (`getToken`, `refreshToken`, `createTokenRefresher`) stays.
+Released with `@mcp-abap-adt/auth-broker-cli` 2.0.0, the commands on this
+version.
+
+### Breaking
+
+1. **The two stores have one role each.** The service key store holds the
+   *means* — `authType`, `grantType`, the client, basic's user and password,
+   the SNC, OIDC and SAML settings, `serviceUrl`; the session store holds the
+   *secret* — the token or cookies, `expiresAt`, the refresh token, and what
+   the secret is bound to (`issuedFor`, `issuedBy`). The broker writes the
+   secret alone, in one `saveSession`, and never a means field: no
+   `serviceUrl`, `authType` or client is written to the session any more
+   (3.x called `setConnectionConfig` and `setAuthorizationConfig`).
+   `getProvider` reads the means from the key store only: a destination
+   whose means only a session answers is a `DestinationConfigError`.
+2. **The session store must take a write of the secret alone:
+   `@mcp-abap-adt/auth-stores` 3 or later**, or a store of your own that does.
+   auth-stores 1.x and 2.x are not supported: their `AbapSessionStore`
+   throws on a `saveSession` without `serviceUrl` and their
+   `SafeAbapSessionStore` refuses it (measured on 1.2.3, 1.2.4 and 2.0.0), so
+   a token would be obtained and then never stored. auth-stores 3.1.0 or
+   later for the binding (item 4).
+3. **`getConnectionConfig` / `getAuthorizationConfig` compose the two
+   stores** — the key store's means with the session's secret laid over them
+   — instead of answering the session's configuration whole.
+4. **A stored secret is used only for the resource and issuer it was
+   obtained for** (`issuedFor`, `issuedBy`): one bound elsewhere, or not
+   bound at all, is not reused — the provider logs in afresh, and a `none`
+   destination is refused.
+5. **The token API refuses a destination the key store states as `basic` or
+   `snc`** (`DestinationConfigError`, `authType`), instead of writing a token
+   over its session.
+6. **Contracts and dependencies.** `@mcp-abap-adt/interfaces-auth` `^3.0.0`,
+   `@mcp-abap-adt/interfaces-auth-sap` `^2.0.0`,
+   `@mcp-abap-adt/interfaces-auth-broker` `^1.1.0` (the store contracts, new),
+   `@mcp-abap-adt/auth-providers` `^5.2.1` (now a runtime dependency). Types
+   of `interfaces-auth` 2.x and providers of auth-providers 4.x no longer mix
+   with this version.
+
+### Migrating from 3.x
+
+- **Stores.** Use `@mcp-abap-adt/auth-stores` `^3.1.0` (this version is
+  tested against 3.2.0), or stores of your own on the
+  `@mcp-abap-adt/interfaces-auth-broker` contracts. State the means in a key
+  store: an `EnvDestinationStore(dir, { fallback })` over
+  `<destination>.env`, or `AbapServiceKeyStore(dir, { grantType })` /
+  `XsuaaServiceKeyStore(dir, { grantType })` over a SAP service key — a key
+  cannot state its grant, so whoever builds the store states it. The session
+  store keeps the secret: `AbapSessionStore`, `XsuaaSessionStore`,
+  `EnvFileSessionStore`, or the in-memory `Safe*` ones. A custom
+  `ISessionStore` must persist `issuedFor` and `issuedBy` beside the secret,
+  or the broker never reuses its sessions (a login every start).
+- **3.x session files** hold means and secret together. Point an
+  `EnvDestinationStore` and a session store at the same directory: each reads
+  its own keys where they are. A `basic` or `snc` file works once it states
+  `SAP_AUTH_TYPE`; a `jwt` or `saml` file needs `SAP_GRANT_TYPE` (3.x never
+  wrote one) — run the `auth-broker-cli` command that produced it again, or
+  add the line. Its stored token is reused when its `SAP_URL` (+
+  `SAP_CLIENT`) and `SAP_UAA_URL` + `SAP_UAA_CLIENT_ID` are the destination's
+  (auth-stores 3.1.0 reads them as the binding); otherwise the first start
+  logs in once. XSUAA sessions written with an empty URL log in once.
+- **A `@mcp-abap-adt/connection` 10 connector:** build it from
+  `await broker.getProvider(destination)` instead of a token and a token
+  refresher. Construct the broker with a `serviceKeyStore` and without a
+  `provider`, and give it the collaborators its destinations' grants use —
+  `authorization`, `oidcAuthorization`, `deviceCodePresenter`, `samlCookies`,
+  `assertionReplayStore`; there is no default. A headless process gives ones
+  that refuse. The connector's URL comes from your key store
+  (`getConnectionConfig`); `getProvider` does not need it.
+- **The token API with a provider of your own** (calm-server's way): see
+  *The token API* below — the same calls, reads and answers; what it writes
+  is the secret alone.
+- **`DestinationConfigError`** (new, exported): catch it where the process
+  builds its connector or asks for a token. `missingFields` names what the
+  destination lacks (a field, or a collaborator option) — never a value.
+- **`flush()`** (new): a session write that fails is retried by the broker
+  instead of failing the authentication. Call `await broker.flush()` on
+  shutdown (`SIGTERM`, before a stdio transport closes) to learn whether
+  every secret is stored; it rejects naming the destinations still failing.
+- **`bindingOf(means, client?)`** (new): a consumer that writes a handed-over
+  token or cookies (a `none` destination) to the session store itself writes
+  `bindingOf(means)` beside them, or `getProvider` refuses the destination.
+- **Imports.** The re-exported types keep their names. If you import
+  `ISessionStore`, `IServiceKeyStore`, `IConnectionConfig` or `IConfig` from
+  `@mcp-abap-adt/interfaces-auth-sap` yourself, take them from
+  `@mcp-abap-adt/interfaces-auth-broker`; `IAuthorizationConfig` and
+  `AuthType` stay in `interfaces-auth-sap`. Providers are auth-providers 5:
+  the interactive ones take their `authorization` strategy explicitly.
+- **The commands** are `@mcp-abap-adt/auth-broker-cli` (since 3.1.0); its
+  2.0.0 is the version on this library — what changed for its flags, files
+  and exit codes is in its CHANGELOG, *Migrating from 1.0.0*.
+
+#### The token API (`getToken`, `refreshToken`, `createTokenRefresher`)
+
+**What stays.** A consumer that passes its own `provider` (an instance or a
+`TokenProviderFactory`) calls the same methods with the same signatures and
+gets the same answers: the provider is asked as before, seeded from the same
+reads in the same order (the session first, then the key store), and its
+errors — and a store's — reach the caller unchanged. `createTokenRefresher`
+is unchanged and stays supported (calm-server injects it into its own
+connection).
+
+**What changes for it.**
+
+1. **The session gets the secret alone** — the token or cookies, `expiresAt`,
+   the refresh token, and what the secret is bound to (`issuedFor`,
+   `issuedBy`) — in one `saveSession`. No `serviceUrl`, `authType` or client
+   is written back any more, so a wrapper that only kept the written-back
+   `serviceUrl` out of the session (calm-server's `TargetUrlSessionStore`)
+   has nothing left to filter. A store that merges a write into what it holds
+   — auth-stores 3, and auth-stores 1.x/2.x's `XsuaaSessionStore` and
+   `EnvFileSessionStore` (measured on 1.2.4 and 2.0.0) — keeps what it holds.
+2. **The session store must accept a write of the secret alone.**
+   Measured: auth-stores **1.2.3, 1.2.4 and 2.0.0**'s `AbapSessionStore`
+   throws a `TypeError` on a `saveSession` without `serviceUrl`, and their
+   `SafeAbapSessionStore` refuses it (`missing required field: serviceUrl`) —
+   even when the session already holds its URL. On those stores `getToken`
+   obtains a token and then throws the store's error, and the broker's retry
+   cannot succeed. Use auth-stores **3** (`^3.1.0` for the binding) — or a
+   store of your own that takes the secret alone. (1.x/2.x's
+   `SafeXsuaaSessionStore` replaces the session with what is written: the
+   URL or client it held in memory is gone after the first token, so state
+   them in the key store.)
+3. **A destination the key store states as `basic` or `snc` is refused**
+   (`DestinationConfigError`, `missingFields: ['authType']`) instead of
+   getting a token written over its credential.
+4. **A failed write is retried.** It still reaches `getToken`'s caller; the
+   broker then retries it on its own, and `flush()` reports what is still
+   pending — call it on shutdown.
+
+**Without a `provider`,** the token API serves what the destination states,
+on the provider `getProvider` builds for it (see *Added*): the consumer
+composes the key store (the means, `grantType` included) and the
+collaborators instead of a provider.
+
+### Added
+
+- **`bindingOf(means, client?)`** — the binding (`issuedFor`, `issuedBy`) the
+  broker writes beside a secret for a destination with those means, for a
+  consumer that hands over a credential (a `none` destination's token or
+  cookies) and writes it to the session store itself. It is the same function
+  `getProvider` checks a stored secret against and `persist` writes
+  (`destinationBinding`, `src/bindingOf.ts`), so what a consumer writes and
+  what the broker expects cannot diverge, and no consumer canonicalises a URI.
+  `@mcp-abap-adt/auth-broker-cli`'s `--cookie` uses it.
+
+- **`getProvider(destination): Promise<IAuthProvider>`** — the credential the
+  destination states, for a `@mcp-abap-adt/connection` 10 connector. The
+  destination's `authType` (and `grantType`, for `jwt` and `saml`) chooses the
+  provider and nothing else does; the means are read from the service key
+  store only, the secret (token or cookies) from the session store only. Built
+  in this version: `basic` → `BasicAuthProvider`, `snc` →
+  `SncLogonProvider.forSecureLoginClient` (from `sncPartnerName`, `sncQop`,
+  `sncLib`, `sncMyName`), `jwt` / `none` → `TokenAuthProvider.fixed` with the
+  session's token, `saml` / `none` → `SamlAuthProvider` with the session's
+  cookies, the UAA grants, the OIDC grants and the SAML grants (below) —
+  every pair of the table. One provider per destination: the promise of the build is cached before the
+  first read, so concurrent first calls build once, and dropped when the build
+  throws, so the next call retries.
+- **The UAA grants in `getProvider`**: `jwt` / `authorization_code` →
+  `AuthorizationCodeProvider`, `jwt` / `client_credentials` →
+  `ClientCredentialsProvider`, `jwt` / `passcode` → `UaaPasscodeProvider`. The
+  client (`uaaUrl`, `uaaClientId`, `uaaClientSecret`) comes from the key
+  store's `getAuthorizationConfig`; `authorization_code` and `passcode` are
+  seeded from the session — the token, the refresh token and `expiresAt` —
+  and without a session log in at `prepare()`; `client_credentials` takes the
+  client alone. `uaaClientSecret: ''` is a public client, which `passcode`
+  takes as no secret. No row needs `serviceUrl`: the resource URL is not
+  authorization data — no token provider reads it — so the connector takes it
+  from the key store, and `getProvider` neither requires it nor passes it to a
+  provider; it reads it only to bind a stored secret (below).
+- **The OIDC grants in `getProvider`**: `jwt` / `oidc_authorization_code` →
+  `OidcBrowserProvider` (PKCE), `device_code` → `OidcDeviceFlowProvider`,
+  `password` → `OidcPasswordProvider`, `token_exchange` →
+  `OidcTokenExchangeProvider`. The client id and secret come from the key
+  store's client (`uaaClientSecret: ''` is a public client, sent with no
+  secret); the endpoints from `oidcIssuerUrl` (discovery) or, without it,
+  every explicit endpoint the row reads (`oidcAuthorizationEndpoint`,
+  `oidcDeviceAuthorizationEndpoint`, `oidcTokenEndpoint`); `oidcScopes` as
+  given, joined by one space into `token_exchange`'s `scope`; `password`'s
+  user and `token_exchange`'s subject, audience and actor token from the
+  means — sent, never written. Seeded from the session like the UAA rows;
+  `issuedBy` is `oidcIssuerUrl`, else `uaaUrl`, with `client_id`.
+- **The SAML grants in `getProvider`**: `saml` / `saml2_pure` →
+  `Saml2PureProvider`, `saml2_bearer` → `Saml2BearerProvider`. The broker
+  composes the assertion validator from the destination's trust —
+  `createSignedResponseValidator` for `saml2_pure`,
+  `createSignedAssertionValidator` for `saml2_bearer`, from
+  `samlIdpCertificates`, `samlClockSkewMs` and the consumer's
+  `assertionReplayStore` — and passes `samlIdpEntityId` as the expected
+  issuer, with `samlIdpSsoUrl`, `samlSpEntityId`, `samlAcsUrl`,
+  `samlRelayState` and `samlIdpInitiated`. `saml2_pure` is seeded with the
+  stored cookies and `expiresAt` (auth-providers 5.1.0's seed) and bound to
+  `samlAcsUrl` (origin and path); `saml2_bearer` takes the client and
+  `samlTokenUrl`, is seeded with the token, refresh token and `expiresAt`, and
+  is bound to `uaaUrl` with `client_id`.
+- **The `authorization` option is used**: `(destination, grant) =>
+  IAuthorizationStrategy<string>`, the interactive half of
+  `authorization_code` and `passcode` (for `passcode` the strategy is handed
+  `<uaaUrl>/passcode`). Called once per destination's build, never disposed
+  by the broker; required only by those two grants and the two SAML grants
+  (which it conducts with the grant passed), with no default.
+- **The other collaborator options are used**: `oidcAuthorization` by
+  `oidc_authorization_code`, `deviceCodePresenter` by `device_code`,
+  `samlCookies` (the validated SAMLResponse → the system's session cookies)
+  by `saml2_pure`, `assertionReplayStore` by both SAML grants — each a
+  function of the destination, called once per build, never disposed, and
+  required only by its rows: missing, a `DestinationConfigError` naming it.
+- **What a `getProvider` provider obtains is stored.** Every token provider
+  the broker builds gets `onTokens`, so a token obtained at `prepare()`, on
+  expiry, or in `rejected()` after a 401 is in the session store before the
+  provider answers. The write is the session secret alone — one
+  `saveSession(destination, { authorizationToken, expiresAt, refreshToken,
+  issuedFor, issuedBy })`, the stored refresh token carried forward when the
+  result has none and the stored session is bound where the new secret is —
+  and never a means field (no `serviceUrl`, no `authType`, no client secret,
+  no subject token, no password). A `saml2_pure` result (`tokenType:
+  'saml'`) is written as cookies — `{ sessionCookies, expiresAt, issuedFor,
+  issuedBy }`, no refresh token; a `saml2_bearer` result as a token.
+  A destination the key store states as `basic` or `snc` is not written.
+- **A stored secret is used only where it is bound** (`issuedFor` /
+  `issuedBy`, `@mcp-abap-adt/interfaces-auth-broker` 1.1.0). The broker
+  computes from the means the resource a secret is for (`serviceUrl` with
+  `sap-client`) and who issued it to which client (`uaaUrl` with
+  `client_id` for the UAA grants and `saml2_bearer`; the OIDC issuer, else
+  `uaaUrl`, with `client_id` for the OIDC grants; the ACS for `saml2_pure`),
+  canonicalises them and the session's values with one function
+  — scheme and host lower-cased, the port explicit (`443` / `80`), the path
+  without a trailing `/`, only `sap-client` (the means' `sapClient` first) or
+  `client_id` kept and re-encoded, so percent-encoding compares equal — and
+  writes both with every secret, each left out when the means lack its source.
+  The grants that obtain a secret (UAA, OIDC, SAML) are seeded only when both
+  stored values match; otherwise the
+  stored secret, refresh token included, is not used: the provider logs in
+  afresh and the log says only `<destination>: secret bound to another
+  resource, discarded`. A `none` destination is refused instead: a
+  `DestinationConfigError` naming `issuedFor` when the stored resource is not
+  the destination's or is absent, and naming `issuedBy` when the means state
+  an issuer (`oidcIssuerUrl` or the client for `jwt`, `samlAcsUrl` for `saml`)
+  and the stored one is not it. **What a consumer meets:** a custom
+  `ISessionStore` must persist both fields beside the secret, else every
+  process start is a fresh login; a headless process whose strategy refuses
+  logins answers Oops on a mismatch instead of presenting a foreign secret; a
+  changed URL, SAP client, UAA or client costs one login. Session files
+  written before `@mcp-abap-adt/auth-stores` 3.1.0 keep working: its stores
+  answer the binding from the file's `SAP_URL` (+ `SAP_CLIENT`) and
+  `SAP_UAA_URL` + `SAP_UAA_CLIENT_ID`; XSUAA sessions written with an empty
+  URL have none and log in once.
+- **A failed session write does not fail the authentication**: it stays
+  pending for its destination and the broker retries it on its own — one
+  second, doubling, capped at one minute, on a timer that does not keep the
+  process alive. A newer result replaces the pending one; writes for one
+  destination never overlap; failures are logged by class name, never their
+  message.
+- **`flush(): Promise<void>`** — one more attempt for every pending session
+  write; resolves when all have landed, rejects with an `AggregateError`
+  naming the destinations whose store still refuses (the retries go on). Call
+  it on shutdown.
+- **`DestinationConfigError`** (`code: 'DESTINATION_CONFIG'`, `destination`,
+  `missingFields`) — a destination that lacks what its type needs:
+  no `serviceKeyStore` option, no means, no or an unknown `authType`, a
+  `jwt`/`saml` destination without a `grantType` or with a pair outside the
+  table, a missing field of its row (`''` counts as missing; for the UAA
+  grants `uaaUrl`, `uaaClientId`, and `uaaClientSecret` for
+  `authorization_code` / `client_credentials`), a missing collaborator option
+  (`authorization`; for the OIDC and SAML grants `oidcAuthorization`,
+  `deviceCodePresenter`, `samlCookies`, `assertionReplayStore`), an OIDC
+  grant with neither `oidcIssuerUrl` nor its endpoints (`oidcIssuerUrl` and
+  each endpoint missing), a SAML grant without its trust (`samlIdpSsoUrl`,
+  `samlSpEntityId`, `samlIdpEntityId`, `samlIdpCertificates` — an empty list
+  counts as missing), a certificate the validator cannot read
+  (`samlIdpCertificates`) or a `samlClockSkewMs` that is not a whole,
+  non-negative number, a `none` credential not bound to the destination
+  (`issuedFor`, `issuedBy`), or a provider
+  constructor's own `ValidationError` (an `sncQop` outside `1|2|3|8|9`, named
+  as the store field; the provider's error, which quotes the value, is not
+  kept). It names fields and options, never a stored value.
+- **The token API shares `getProvider`'s provider.** Without a consumer
+  `provider`, `getToken`, `refreshToken` and `createTokenRefresher` ask the
+  very provider `getProvider` hands out for the destination — one per
+  destination, so one token, one refresh token and one renewal in flight
+  serve the connector and the token API alike (a `refreshToken()` during a
+  renewal in `rejected()` joins it). They write nothing themselves: the
+  provider's `onTokens` does, as for any `getProvider` provider. They serve the
+  destinations whose provider obtains a token — every grant but `none` — and
+  throw `DestinationConfigError` naming `provider` for a `none` destination,
+  before any provider is built. A failed write still reaches the caller:
+  `getToken` / `refreshToken` throw the store's error for the token they
+  received — as 3.x did — while the broker keeps retrying the write.
+- The collaborator options `authorization`, `oidcAuthorization`,
+  `deviceCodePresenter`, `samlCookies`, `assertionReplayStore` on
+  `AuthBrokerConfig`, and the `StrategyGrant` type.
+- **The broker's own test stand** (`tests/stand/`, `npm run test:stand`):
+  Cloud Foundry UAA and Keycloak in Docker, copied from auth-providers' stand,
+  with suites running the UAA grants end to end through auth-stores 3.1.0's
+  file stores — the binding asserted in the session file, and a session bound
+  to another URL not reused — the OIDC grants against Keycloak, and the SAML
+  grants with Keycloak as identity provider and UAA as service provider
+  (`saml2_pure`'s cookies a real UAA session from its web SSO ACS;
+  `saml2_bearer` exchanged at UAA's bearer grant); a CI workflow runs the build-and-test gate and the stand on every
+  push and pull request. Not shipped in the package.
+
+### Changed
+
+- **`provider` is optional.** `getProvider` does not use it. With it, the
+  token API asks it, as in 3.x; without it, the token API asks
+  `getProvider`'s provider (above). With neither a `provider` nor a
+  `serviceKeyStore`, `getToken` and `refreshToken` throw
+  `DestinationConfigError` naming both.
+- **Breaking: the token API refuses a destination stated `basic` or `snc`.**
+  It reads the destination's `authType` from the key store first and, for
+  `basic` or `snc`, throws `DestinationConfigError` naming `authType` before
+  any provider is asked — 3.x asked the provider and wrote `authType: 'jwt'`
+  and a token over the session of a destination that holds no token. A key
+  store that states no `authType` (a 3.x setup with a consumer `provider`),
+  or no key store at all, is served as before.
+- **Breaking: the token API writes the session secret alone.** With a
+  consumer `provider` it still writes after every `getTokens()` /
+  `refreshTokens()`, cache hits included, but through the same write path as
+  `getProvider`'s providers: one `saveSession(destination, {
+  authorizationToken | sessionCookies, expiresAt, refreshToken, issuedFor,
+  issuedBy })`, retried when the store fails and awaited by `flush()`. 3.x
+  wrote the session's connection config back with `serviceUrl` and a derived
+  `authType` (`setConnectionConfig`), and a client the session held with the
+  new refresh token (`setAuthorizationConfig`); neither method is called any
+  more. A result without a refresh token carries the stored one forward.
+  `issuedFor` is the `serviceUrl` the token API resolved, with the SAP client
+  (the session's, else the key store's); `issuedBy` is the client a factory
+  was handed (`uaaUrl` with `client_id`) — an instance is handed no client,
+  so its tokens are bound to no issuer and `getProvider` never seeds from
+  them. Both are fixed when the provider is built for the destination (an
+  instance: at its first call for it) and kept with it, so a URL or client
+  changed later never re-labels a token obtained before the change; a new
+  broker picks the change up. A failed write is thrown to the caller as the store raised it, as in
+  3.x, and retried.
+- The token API's reads are 3.x's, and so are its answers: the session first,
+  then the key store, for `serviceUrl` and the client a factory is seeded
+  with; the factory called once per destination — now cached as the promise
+  of its build, so concurrent first calls build once — and again after one
+  that threw; an instance used for every destination; the provider's errors
+  and a store's failures propagate unchanged; a result without a token is an
+  error. `createTokenRefresher(destination)` is unchanged and not
+  deprecated.
+- **Breaking: `getConnectionConfig` / `getAuthorizationConfig` compose the two
+  stores** instead of answering the session's configuration whole (and the
+  key's only when the session had none). `getConnectionConfig` is the key
+  store's means with the session's `authorizationToken`, `sessionCookies` and
+  `expiresAt` laid over them; `getAuthorizationConfig` is the key store's
+  client with the session's refresh token, `null` without a client in the key
+  store. Means a session store answers are not read, nor a secret a key store
+  answers. A consumer that kept the URL or the client only in its session
+  store gets them from a key store now.
+- **Contracts from their 2026-10 packages.** `@mcp-abap-adt/interfaces-auth`
+  `^3.0.0` (was `^2.1.0`), `@mcp-abap-adt/interfaces-auth-sap` `^2.0.0` (was
+  `^1.0.1`), and `@mcp-abap-adt/interfaces-auth-broker` `^1.1.0` (new; 1.1.0
+  for `issuedFor` / `issuedBy`). The
+  store contracts — `IConfig`, `IConnectionConfig`, `ISessionStore`,
+  `IServiceKeyStore` — moved out of `interfaces-auth-sap` into
+  `interfaces-auth-broker`; this package now takes them from there.
+  `IAuthorizationConfig` and `AuthType` stay in `interfaces-auth-sap`. The
+  re-exported names are unchanged; only where they come from. A consumer that
+  imports them from this package changes nothing; one that imports
+  `ISessionStore` and friends from `interfaces-auth-sap` itself takes them
+  from `interfaces-auth-broker` from its 2.0.0 on.
+- `@mcp-abap-adt/auth-providers` `^5.2.1` (was `^4.2.0`, a dev dependency) is
+  a runtime dependency: `getProvider` constructs its classes. None is
+  re-exported. 5.2.0 because `ClientCredentialsProvider` takes a `logger`
+  from it: the broker passes its own, so a `client_credentials` destination's
+  token lifecycle is logged like the other grants' (tokens redacted by the
+  provider); 5.2.1 because 5.2.0 skipped OIDC discovery unless every
+  device-flow endpoint was missing, so a `device_code` destination stating
+  its issuer and one explicit endpoint was refused at `prepare()`. The library's tests run against `@mcp-abap-adt/auth-stores`
+  `^3.2.0` (a dev dependency, was `^1.2.3`; the `auth-stores-3` alias the
+  stand, live and binding suites used is gone): its session stores hold the
+  secret alone, which is all the broker writes now. The carried-over on-disk
+  case reads the means from an `EnvDestinationStore` and asserts the session
+  file holds the secret and its binding and nothing else. Dev dependency
+  `@mcp-abap-adt/connection` `^10.0.3` (was `^10.0.2`), for the end-to-end
+  test: a connector built from `getProvider`, a 401 renewed in `rejected()`,
+  the new token in the session file, and the token API answering it.
+- Comments no longer name `@mcp-abap-adt/auth-stores-btp` / `-xsuaa` (which do
+  not exist) or the deleted `@mcp-abap-adt/interfaces` facade.
+- Dev dependency `@mcp-abap-adt/auth-mocks` `^0.3.0` (new): the SAML grants'
+  unit tests validate assertions its identity provider signs — one signing
+  the Response, one the Assertion alone — rather than documents the suite
+  signs itself. Not shipped.
+
 ## [3.1.0] - 2026-10-01
 
 **Why a minor.** The library's API is unchanged: every export, signature and