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

package/CHANGELOG.md

@@ -7,6 +7,199 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.0.0] - 2026-09-25
+
+### Breaking
+
+- **Both SAML providers validate the assertion before trusting it** (#19).
+  Until now the only check was that the payload was a non-empty string, and
+  `Saml2PureProvider` took its session lifetime from a regular expression over
+  the unverified XML. `Saml2BearerProvider` now validates before the token
+  exchange, `Saml2PureProvider` before `cookieProvider`, through twelve checks:
+  document shape, unique IDs, signature, that the signed node is the node read,
+  `Status`, assertion ID, issuer, `Conditions`, `NotBefore`, `NotOnOrAfter`,
+  audience, one bearer subject confirmation (request ID, recipient, window) and
+  `Destination`, then replay. The README's *SAML assertion validation* lists
+  them with what refuses each.
+
+  **The configuration is required.** Supply `idpCertificates` (PEM or bare
+  base64 DER, a list for key rotation) and `idpEntityId`, or an
+  `assertionValidator` of your own; without them the provider's constructor
+  throws a `ValidationError` naming what is missing. A shipped validator
+  supplied as `assertionValidator` still needs `idpEntityId`, and its absence
+  fails at construction too; only a custom validator does without.
+  `spEntityId` becomes the `Audience` the assertion must name.
+
+  **Request IDs.** `InResponseTo` must answer the AuthnRequest the package
+  minted, or `authnRequestId` when the package did not build the request — a
+  pre-built `authorizationUrl`, or a strategy that returns a payload without
+  calling `buildAuthorizationUrl`. `idpInitiated: true` declares that no request
+  was sent, so the assertion must carry no `InResponseTo`; it gives up the
+  login-CSRF defence of a request ID, and is never inferred.
+  `Saml2BearerProvider` against UAA or XSUAA needs it, since both refuse an
+  assertion carrying `InResponseTo`. Having neither an ID nor the declaration,
+  or combining the declaration with an ID, raises a `ValidationError`. With
+  `idpInitiated` and no `authorizationUrl`, a strategy that calls
+  `buildAuthorizationUrl` is refused inside the builder, before any URL is
+  produced — so before a browser opens.
+
+  **Status, by validator.** Under `createSignedResponseValidator` —
+  `Saml2PureProvider`'s default — an identity provider returning a
+  non-`Success` status is now refused, where it was accepted before.
+  `Saml2BearerProvider`'s default, `createSignedAssertionValidator`, does not
+  read `Status`, so a bearer consumer sees no change there: a declining identity
+  provider mints no signed assertion, and the login fails for want of one.
+
+  **Migrating:** see *Migrating from 3.x to 4.0* in the README — add the trust
+  configuration, check `spEntityId`, and for `Saml2BearerProvider` against UAA
+  or XSUAA add `idpInitiated: true` with a strategy that never calls
+  `buildAuthorizationUrl`.
+- **`parseSamlNotOnOrAfter` is removed.** `Saml2PureProvider`'s `expiresAt` is
+  now the validated assertion's expiry — the earlier of `Conditions/@NotOnOrAfter`
+  and the accepted bearer confirmation's — read from the verified document.
+- **`buildSamlAuthorizationUrl` returns `{ url, requestId? }`**, since the
+  minted ID must survive to validation, and **`getSamlAssertion` returns
+  `Promise<SamlAssertionResult>`** (payload, request ID, ACS) instead of
+  `Promise<string>`. None of these, nor `parseSamlNotOnOrAfter`, was exported
+  from the package root; only a deep import of `dist/auth/saml2Auth` or
+  `dist/providers/saml2Utils` is affected.
+- **`@mcp-abap-adt/interfaces-auth` `^2.0.0`** (was `^1.2.0`), where
+  `AssertionContext.expectedInResponseTo` is optional — a breaking change for
+  implementers of `IAssertionValidator`, which must refuse an assertion
+  carrying `InResponseTo` when it is absent.
+
+### Added
+
+- **`createSignedResponseValidator`** and **`createSignedAssertionValidator`**,
+  sharing `ShippedValidatorOptions` (`idpCertificates`, `clockSkewMs`,
+  `replayStore`). The first requires the signature to cover the `Response` and
+  performs all twelve checks; the second accepts a signature over the
+  `Assertion` — bare, or inside a Response — and does not read `Status`,
+  `Response/Issuer` or `Destination` at all. `Saml2PureProvider` defaults to the
+  first, `Saml2BearerProvider` to the second; `assertionValidator` replaces
+  either.
+- **Replay detection**: `defaultReplayStore`, a process-wide in-memory store
+  shared by every default validator, keyed by `{issuer, assertionId}` and
+  retained until the earlier of `Conditions/@NotOnOrAfter` and the latest
+  `NotOnOrAfter` of a bearer confirmation that answers the request and names
+  the ACS, plus `clockSkewMs` — as long as the assertion could still be
+  accepted, which can outlast `expiresAt`; `createInMemoryReplayStore()` for
+  an isolated one; `assertionReplayStore` on the providers for a shared store
+  across processes.
+- **`clockSkewMs`**, default `0`.
+- Any XML parse fault — including one `@xmldom/xmldom` would otherwise repair,
+  such as an undeclared entity — is a refusal at `document`, and the parser
+  never writes to the console; the bearer conversion (`toBearerAssertion`)
+  parses the same way.
+- The validators refuse a payload carrying a `<!DOCTYPE` declaration, never
+  take a signing certificate from the document's own `KeyInfo`, and accept
+  RSA-SHA1 signatures and SHA-1 digests, as `xml-crypto` does by default; a
+  consumer wanting to refuse SHA-1 wraps a shipped validator in its own.
+- **`AssertionValidationError`**, with `check: AssertionCheck` naming the check
+  that refused the assertion, and code `ASSERTION_VALIDATION_ERROR`.
+- `xml-crypto` becomes a runtime dependency, for signature verification.
+
+### Development
+
+- Both validators run end to end in `npm test`, through `Saml2PureProvider`
+  and a real callback, against responses from `@mcp-abap-adt/auth-mocks` (the
+  devDependency and its range are unchanged). Every corruption variant is refused at the
+  check it targets, except `statusFailure` and `wrongDestination`, which the
+  assertion-only validator accepts — both halves asserted.
+- The provider stand's SAML suites run every login through the provider's
+  validation, including Keycloak's real responses, signed at both levels; the
+  live XSUAA suite does the same with its per-run identity provider, and now
+  refuses the `InResponseTo` case itself, before XSUAA sees it.
+- `@mcp-abap-adt/interfaces-auth-sap` `^1.0.1`.
+
+## [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