@mcp-abap-adt/auth-broker 4.0.0 → 5.0.0

package/CHANGELOG.md

@@ -9,7 +9,279 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Thank you to all contributors! See [CONTRIBUTORS.md](../../CONTRIBUTORS.md) for the complete list.
 
-## [Unreleased]
+## [5.0.0] - 2026-10-09
+
+The broker on the auth chain's 6.0 contracts (auth-providers 6, interfaces-auth 7, auth-errors
+2). A major: what every failure is changes class, two options become required for token
+destinations, the session binding gains a versioned record, and every wait can be cancelled.
+Released with `@mcp-abap-adt/auth-broker-cli` 3.0.0. What a 4.x consumer must do, row by row:
+the README's *Migrating to 5.0.0*.
+
+### Breaking
+
+- **`renewal` is required for every token row.** `AuthBrokerConfig.renewal` — `(destination,
+  grant: TokenGrant) => IRenewalStrategy` — is called once per build of every UAA, OIDC and
+  SAML row, after every other check and before the provider's constructor; its answer is the
+  provider's `renewal`, unchanged. No default: a token row without it is a
+  `DestinationConfigError` naming `renewal`, beside every other missing field. A `renewal` that
+  throws is `DestinationConfigError(['renewal'])`, "the renewal option failed", carrying what it
+  threw. Not called for `basic`, `snc`, `none`, nor for the token API's `provider`.
+  `() => refreshThenLogin()` is 4.x's behaviour.
+- **`onWriteFailure: 'fail' | 'continue'` is required** for every destination that writes a
+  secret — a token row `getProvider` builds, and every call of the token API with a `provider`.
+  Without it: `DestinationConfigError` naming `onWriteFailure`. `'fail'`: the call whose write
+  did not land fails (`unknown`, `persisting-tokens`), and while the destination's last write is
+  pending (failed, queued or in flight) `getProvider`, `getToken` and `refreshToken` retry it on
+  entry and once more before success, and are refused while it fails. `'continue'`: logged, the
+  call goes on. A moment of a provider already handed out that commits nothing is not refused.
+- **Failures are `AuthProviderFailure`s, read through `@mcp-abap-adt/auth-errors`.** A
+  provider's failure reaches `getToken()` / `refreshToken()` as the same object. The broker reads
+  a caught value only through `readFailure` / `isAuthProviderFailure` — no `instanceof`,
+  `message` or `name` of an error is read in `src`. The broker's own failures are minted by
+  auth-errors: an aborted wait (`interactive-login`, `aborted`), a write that did not land under
+  `'fail'` (`unknown`, `persisting-tokens`, an allowlisted `code`), a provider that answered no
+  token (`request-failed`, `token-source`, `no-access-token` — replacing "Token provider did not
+  return authorization token …").
+- **`DestinationConfigError` carries the provider's failure.** New `error?: IAuthProviderError`
+  (kind, facts, rendered words, admitted diagnostics; no `cause`) when a provider's or a
+  strategy's failure caused the refusal; the message then ends `: <error.reason>`. New
+  `isDestinationConfigError(value)` — structural, no `instanceof`; true for a JSON copy. A
+  provider constructor that throws inside a build — any row, not only SNC — is a
+  `DestinationConfigError` naming the store fields its configuration facts name. The SNC row
+  decides by kind (`configuration` → its fields), not by `instanceof ValidationError`. The
+  broker's own copy of the three certificate phrases is gone: `clientAuthentication`'s refusal
+  reads `the clientAuthentication strategy failed: <reason>` with auth-providers'
+  `client-certificate` failure carried. New rows: `renewal`, `onWriteFailure`, `provider` (an
+  instance after the destination's identity changed), a store field of a shape the broker
+  cannot take, `samlIdpInitiated`, `oidcScopes` and `oidcActorTokenType` of the wrong shape.
+- **`issuedBy` is a versioned binding record**: `mcp-abap-adt-binding/2;<row>;<eleven address
+  fields>;<trust>` — the row (`authType/grantType`, or `provider/…` for the token API's consumer
+  provider), the exact string of every server address the row hands its provider
+  (`encodeURIComponent`-encoded, never canonicalised: `clientId`, `uaaUrl`, `oidcIssuerUrl`, the
+  three OIDC endpoints, `oidcAudience`, `samlIdpSsoUrl`, `samlAcsUrl`, `samlTokenUrl`, the
+  certificate client's `certUrl`) and the SHA-256 of the row's non-secret trust input (SAML
+  trust, OIDC scopes, the password grant's user, the token-exchange token types, the certificate
+  client's public certificate). Compared by exact equality, never parsed; no secret and no hash
+  of one in it. `issuedFor` keeps 4.x's canonical form. **Every session written before 5.0.0
+  reads as unbound**: its stored token and refresh token are not used, and the provider's first
+  renewal is a login (or a token request). A `none` row compares `issuedBy` always and refuses a
+  4.x binding naming `issuedBy`. `bindingOf(means, client)` keeps its signature and returns the
+  version-2 record.
+- **A stored secret seeds only a fully stated binding**: one whose record holds the client the
+  row authenticates and every address its provider sends a credential to — so an issuer-less
+  OIDC row with explicit endpoints and a client is now seeded, and `token_exchange` and the
+  token API's consumer provider never are.
+- **A provider is never changed.** Every call of `getProvider` and the token API re-reads what
+  the destination's provider was built from (the means, the client, the certificate client when
+  read) and compares everything the build read, secrets included (in memory only); anything
+  changed builds a new provider that starts with nothing. 4.x cached a destination's provider
+  for the broker's life. An instance `provider` whose destination's identity changed is refused
+  until a new broker.
+- **Two paths, resolved and cached apart.** The row path (`getProvider`, and the token API
+  without `provider`) and the consumer path (the token API with `provider`) each have their own
+  resolution, cache, identity and binding; only the destination's write queue is shared.
+- **The token API's factory is handed no stored secret**: `authConfig` is the client
+  (`refreshToken` a key, never a value), `connConfig` the allowlisted connection means
+  (`serviceUrl`, `sapClient`, `language`, `authType`, `grantType`), the fourth argument the
+  strategy's answer and the client identity (`refreshToken` never set). The consumer path is
+  never seeded. A consumer provider's result without a refresh token writes `refreshToken: ''`
+  (the stored one is no longer carried).
+- **Session writes state every field** (auth-stores 4 merges): a credential write states the
+  token or cookies, `expiresAt` (the provider's report), the refresh token the provider owns or
+  `''`, `issuedFor` (`''` when the means state no `serviceUrl`) and `issuedBy`; `saml2_pure`'s
+  cookies write `refreshToken: ''`; a refresh token discarded before any credential writes only
+  `refreshToken: ''`. A refresh token is written only by the provider that obtained it or was
+  seeded with it and has not discarded it since — never read from the store at write time.
+- **The write queue has no retry timer.** One queue per destination: one write at a time, in
+  order; a replaced provider's late write is dropped once the new one has written; a failed
+  write stays pending until the destination's next write or `flush()`. The 1 s → 60 s retry
+  timer is gone. The store's contract, documented: `saveSession` settles.
+- **`flush()` rejects with an `AggregateError` of `SessionWriteFailure`s** (`destination`,
+  `error`: the store's error classified `persisting-tokens`) instead of
+  `Error("<dest>": <class>)`; the message keeps 4.x's lead.
+- **The built providers persist through auth-providers' `refreshStatePersistence`** (`onTokens`
+  is gone from every row), with the consumer's `onWriteFailure`.
+- **`AuthBrokerConfig`'s optional fields are declared `?: T | undefined`.**
+
+### Added
+
+- **Cancellation.** `BrokerCallOptions { signal? }` on `getProvider`, `getToken`,
+  `refreshToken`, `flush` and `createTokenRefresher`. Every wait is a waiter of auth-errors'
+  `sharedAttempt`: an abort releases that caller alone (`aborted`), the work runs on; when every
+  caller of a build aborted, the build is not cached and writes nothing. `getProvider`'s signal
+  is attached to the token or SNC provider it answers, so a login that provider starts later is
+  aborted once every holder's signal aborted; the token API never attaches and passes its signal
+  to `getTokens({ signal })` / `refreshTokens({ signal })`. `ClientAuthenticationContext.signal`:
+  the build's attempt. The broker sets no timeout and has no timer.
+- **`authDebug?: boolean`** — passed to every token provider the broker builds, on only for
+  `true`, never read from the environment.
+- Exports: `isDestinationConfigError`, `DestinationConfigErrorLike`, `SessionWriteFailure`,
+  `BrokerCallOptions`, `TokenGrant`, and the re-exported `IRenewalStrategy`.
+
+### Changed
+
+- **Logging**: every line goes through a guard — a logger that throws or rejects changes no
+  outcome. A failed write is one `warn` line with auth-errors' `logFields`, never a class name or
+  message. A stored secret not used is a `warn` only where a stored secret could ever be seeded,
+  a `debug` line otherwise.
+- **The certificate client is re-read on every call** when the build read it: a rotated
+  certificate builds a new provider at the next call (4.x pinned it for the broker's life).
+- **Built under a stricter compiler.** Both packages, sources and tests, compile with
+  `noImplicitReturns`, `noFallthroughCasesInSwitch`, `noImplicitOverride`,
+  `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes`; objects handed to a consumer keep
+  exactly their own keys (`src/contractShape.ts`). Lint: `noExplicitAny` is an error outside the
+  tests, and `lint:check` fails on any warning.
+- **The broker stand and the live suites** run on the 6.0 chain and on
+  `@mcp-abap-adt/connection` 14; each states `renewal` and `onWriteFailure`.
+- `tools/check-provider-shape.mjs`, copied byte for byte from auth-errors 2.1.1, runs with
+  rules 4, 5, 6 over both packages (`npm run check:shape`).
+
+### Dependencies
+
+- `@mcp-abap-adt/auth-providers` `^5.3.0` → `^6.0.0`; `@mcp-abap-adt/interfaces-auth` `^3.2.0`
+  → `^7.5.0`; `@mcp-abap-adt/interfaces-auth-sap` `^2.0.0` → `^3.3.0`;
+  `@mcp-abap-adt/interfaces-auth-broker` `^1.2.0` → `^1.3.0`; new `@mcp-abap-adt/auth-errors`
+  `^2.1.1`. Dev: `@mcp-abap-adt/auth-stores` `^4.0.0`, `@mcp-abap-adt/connection` `^14.0.0`.
+
+### Measured, and not
+
+- Not yet re-run on 5.0.0: the x509 live check (`npm run test:live:x509`, last run 2026-10-05 on
+  4.1.0) and the live suite (`npm run test:live`).
+
+## [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