@mcp-abap-adt/auth-broker 5.0.1 → 5.0.5

package/CHANGELOG.md

@@ -9,6 +9,75 @@ 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.
 
+## [5.0.5] - 2026-10-12
+
+The library's code and runtime dependencies are the same as 5.0.4. What changed is the
+docs, the README's connection note included, and the tests.
+
+### Changed
+- The tests and live checks run on `@mcp-abap-adt/connection` 15.0.0 (dev dependency
+  `^15.0.0`, on `@mcp-abap-adt/interfaces-adt-connection` 2.0.0, one copy). Their
+  end-to-end suite is renamed `adtConnector.test.ts`.
+- The docs name `connection` 14 or 15 as the connector `getProvider`'s provider is for.
+  The README says why a consumer that also uses `adt-clients` should take 15.
+
+## [5.0.4] - 2026-10-12
+
+The first published release after 5.0.1. The code is the same as 5.0.2 and 5.0.3, which were
+tagged but not published. It is released together with auth-broker-cli 3.1.1, so that one
+publish from the main checkout carries both. 5.0.2 (built and tested on auth-stores 5) and
+5.0.3 (tests on connection 14.1.0, the README's connection note) arrive with 5.0.4.
+
+## [5.0.3] - 2026-10-12
+
+Development only; the published library is unchanged.
+
+### Changed
+- The tests run on `@mcp-abap-adt/connection` 14.1.0 (a dev dependency, `^14.1.0`):
+  its `disconnect()` sends the session's logoff, so a connection the broker's
+  tests and live checks close no longer leaves its SAP session open until the
+  server's timeout. The connection is the consumer's; the broker does not
+  depend on it.
+- README: a consumer should use `@mcp-abap-adt/connection` 14.1.0 or later. From
+  14.1.0, `disconnect()` ends the SAP session.
+
+## [5.0.2] - 2026-10-11
+
+Built and tested on `@mcp-abap-adt/auth-stores` 5.0.0; the code is the same as
+5.0.1. auth-stores is not a dependency of the library: the consumer composes
+the stores, and 5.0.2 works with auth-stores 4 or 5 alike.
+
+### Migration (for a consumer moving to auth-stores 5)
+
+- **A session file with no binding keys beside its credential** — written by
+  auth-stores 2.x/3.0.0, auth-broker 3.x, or by hand — is no longer composed a
+  binding by the store and read as unbound (one login). auth-stores 5 refuses
+  the record whole with a `StorageError` (`code: 'STORAGE_ERROR'`,
+  `reason: 'record-format'`, fixed words, no value of the record), and the
+  broker passes it unchanged to the caller of `getProvider` and the token API
+  (every row that reads the session; the broker's own `client_credentials`
+  reads none, and its new credential replaces the record). This is 5.0.0's
+  rule that a store's read failure other than `FILE_NOT_FOUND` reaches the
+  caller, not a change of the broker.
+- **What to do:** regenerate the session with
+  `mcp-auth --service-key <key.json> --output <file> --type abap|xsuaa`, or
+  remove its session lines; a file holding only the means is no session.
+  `@mcp-abap-adt/auth-broker-cli` 3.1.0 (released together) does it for you:
+  `mcp-auth --env <file>` or `--destination <name>` over such a file discards
+  its session and logs in anew, the means kept byte for byte.
+
+### Changed
+- Dev dependency `@mcp-abap-adt/auth-stores` ^5.0.0.
+- Tests: a pre-3.1.0 session file, and a 4.x token beside `issuedFor` alone,
+  now assert the store's `record-format` error reaching the caller — no
+  request, no login, no write, the file byte for byte, no record value in the
+  error or the log — where they asserted a login over a composed binding.
+
+### Documentation
+- README (*Errors*, *A Credential Stays Bound to Its Identity*, the upgrade
+  note), `docs/` and `CLAUDE.md` describe the record-format refusal and name
+  auth-stores 5.
+
 ## [5.0.1] - 2026-10-09
 
 Development only; the code is the same as 5.0.0.

package/README.md

@@ -4,7 +4,7 @@
 A per-destination credential broker for SAP BTP and ABAP systems. For a destination — a name,
 such as `TRIAL` — `getProvider` builds the `IAuthProvider` the destination states (basic, SNC, a
 UAA, OIDC or SAML grant, or a credential handed over) from the *means* in the service key store
-and the *secret* in the session store, ready for a `@mcp-abap-adt/connection` 14 connector, and
+and the *secret* in the session store, ready for a `@mcp-abap-adt/connection` 14 or 15 connector, and
 stores back every token or set of SAML session cookies that provider obtains or renews. The
 token API (`getToken`, `refreshToken`, `createTokenRefresher`) serves whoever wants a token and
 nothing else. It decides nothing about tokens itself: whether the cached token is still good,
@@ -16,10 +16,14 @@ the renewal strategy's you give it; where means and secrets live is the stores'
 short — a token destination needs two options the broker has no default for (`renewal`,
 `onWriteFailure`); every failure is an `AuthProviderFailure` read through
 `@mcp-abap-adt/auth-errors`; every session written before 5.0.0 reads as unbound once, so each
-token destination logs in once after the upgrade.
+token destination logs in once after the upgrade. A session file with no binding keys at all
+(written before auth-stores 3.1.0, or by hand) is refused by auth-stores 5 as a whole, and that
+error reaches you: regenerate it with `mcp-auth` (see [*Errors*](#errors)) — from
+auth-broker-cli 3.1.1, `mcp-auth --env <file>` (or `--destination <name>`) over such a file
+discards its session and logs in anew.
 
 The `mcp-auth` command that writes destination files is
-[`@mcp-abap-adt/auth-broker-cli`](../auth-broker-cli/README.md) (3.0.0, on this version), in the
+[`@mcp-abap-adt/auth-broker-cli`](../auth-broker-cli/README.md) (3.1.1, on this version), in the
 same repository. This package has no `bin`.
 
 ## Features
@@ -39,8 +43,8 @@ same repository. This package has no `bin`.
 npm install @mcp-abap-adt/auth-broker @mcp-abap-adt/auth-providers @mcp-abap-adt/auth-errors @mcp-abap-adt/auth-stores
 ```
 
-5.0.0 depends on `@mcp-abap-adt/auth-providers` `^6.0.0`, `@mcp-abap-adt/auth-errors`
-`^2.1.1`, `@mcp-abap-adt/interfaces-auth` `^7.5.0`, `@mcp-abap-adt/interfaces-auth-sap`
+5.0.5 depends on `@mcp-abap-adt/auth-providers` `^6.0.0`, `@mcp-abap-adt/auth-errors`
+`^2.2.0`, `@mcp-abap-adt/interfaces-auth` `^7.5.0`, `@mcp-abap-adt/interfaces-auth-sap`
 `^3.3.0`, `@mcp-abap-adt/interfaces-auth-broker` `^1.3.0` and
 `@mcp-abap-adt/interfaces-utils` `^1.1.0`. Declare `auth-providers` yourself — the renewal
 strategies (`refreshThenLogin`, `refreshOnly`) and the interactive strategies come from it —
@@ -96,7 +100,7 @@ const provider = await broker.getProvider('TRIAL', { signal: session.signal });
 ```
 
 `getProvider(destination)` returns the `IAuthProvider` (from `@mcp-abap-adt/interfaces-auth`
-7) that a `@mcp-abap-adt/connection` 14 connector takes as it is. The broker reads two stores,
+7) that a `@mcp-abap-adt/connection` 14 or 15 connector takes as it is. The broker reads two stores,
 each for one role:
 
 - **the means** — `authType`, `grantType`, basic's user and password, the SNC, OIDC and SAML
@@ -312,7 +316,7 @@ success — and the write runs on, landing or failing on its own.
 
 **The store's contract.** `saveSession` settles: it resolves or rejects. A store whose
 `saveSession` never settles holds its destination's queue; avoiding that is yours (each waiting
-caller is still released by its own signal). auth-stores 4's `saveSession` **merges** — a field
+caller is still released by its own signal). auth-stores 5's `saveSession` **merges** — a field
 left out keeps what is stored — so the broker states every field that must not survive:
 
 | What the provider reported | What one `saveSession` writes |
@@ -439,6 +443,18 @@ means lacking what the record needs, or no `serviceUrl`) gets a `debug` line ins
 start. An OIDC destination with explicit endpoints and a client but no issuer is fully stated,
 and is reused after a restart when its means are unchanged.
 
+**A record the store refuses is not "no session".** auth-stores 5 reads a session only in its
+own format — beside a token or cookies, both binding keys (`SAP_ISSUED_FOR` / `SAP_ISSUED_BY`,
+or the `XSUAA_*` pair), present even when empty — and refuses any other record as a whole with
+a `StorageError` (`reason: 'record-format'`): a file written by auth-stores 2.x/3.0.0 or
+auth-broker 3.x, or by hand. The broker does not read that as an absent session and log in over
+it; `getProvider` and the token API reject with the store's error, unchanged, before any
+request (every row that reads the session; the broker's own `client_credentials` reads none,
+and its new credential replaces the record). Regenerate the session with `mcp-auth`: from
+auth-broker-cli 3.1.1, a run over the file (`--env`, `--destination`) discards its session — the
+session keys alone, in a private copy, the original written only after the new login is stored —
+and logs in anew.
+
 **The `none` rows** present a credential the broker cannot obtain again, so a mismatch is
 refused, not discarded: a `DestinationConfigError` naming `issuedFor` when the stored resource
 differs or is absent (or the means state no `serviceUrl`), and `issuedBy` when the stored record
@@ -468,7 +484,7 @@ import { bindingOf } from '@mcp-abap-adt/auth-broker';
 const means = await keyStore.getConnectionConfig('DEV'); // saml / none
 await sessionStore.saveSession('DEV', {
   sessionCookies: cookies,
-  refreshToken: '', // auth-stores 4 merges: clear what an earlier session left
+  refreshToken: '', // auth-stores 5 merges: clear what an earlier session left
   ...bindingOf(means ?? {}),
   // { issuedFor: 'https://dev.example.com:443?sap-client=100',
   //   issuedBy: 'mcp-abap-adt-binding/2;saml/none;;;;;;;;;;;;' }
@@ -826,9 +842,16 @@ const current = await tokenRefresher.getToken();
 const renewed = await tokenRefresher.refreshToken();
 ```
 
-A `@mcp-abap-adt/connection` 14 connector takes an `IAuthProvider` instead: give it `await
+A `@mcp-abap-adt/connection` 14 or 15 connector takes an `IAuthProvider` instead: give it `await
 broker.getProvider('TRIAL', { signal })`.
 
+Use `@mcp-abap-adt/connection` 14.1.0 or later. From 14.1.0 its `disconnect()` sends the
+session's logoff. An earlier 14.x left each closed connection's SAP session open until the
+server's own timeout, so a process that connects again and again collects sessions.
+Connection 15 is built on `@mcp-abap-adt/interfaces-adt-connection` 2, as `adt-clients` is.
+If your consumer uses both, choose 15: with 14 it installs two copies of that contract.
+The broker hands either one the same `IAuthProvider`.
+
 ## Errors
 
 **A provider's failure passes as the same object.** Whatever a provider throws from
@@ -930,7 +953,13 @@ needs a clientAuthentication strategy`.
 
 - **A store's read failure** (anything but `FILE_NOT_FOUND`, which is absence) reaches the
   caller as the store raised it — your collaborator's error, returned to you, also through the
-  shared resolution. A store that answers `null`, or fails with `FILE_NOT_FOUND` (logged at
+  shared resolution. With auth-stores 5 that includes a session record not of the store's
+  format: a `StorageError` with `code: 'STORAGE_ERROR'` and `reason: 'record-format'`, in the
+  store's fixed words (`AbapSessionStore: the stored session for "<destination>" is not in this
+  store's format; regenerate it with mcp-auth`) — no value of the record. Regenerate the session
+  (`mcp-auth --service-key <key.json> --output <file>`, or from auth-broker-cli 3.1.1
+  `mcp-auth --env <file>`, which discards the refused session and logs in anew), or remove its
+  session lines. A store that answers `null`, or fails with `FILE_NOT_FOUND` (logged at
   debug), means "nothing here".
 - **The constructor's argument checks** (`AuthBroker: sessionStore is required`, …) are plain
   `Error`s naming option names: a programming error.
@@ -983,7 +1012,7 @@ its level from `AUTH_LOG_LEVEL`.)
 
 ### File Structure
 
-With `@mcp-abap-adt/auth-stores` 4 one `<destination>.env` file can hold a destination whole,
+With `@mcp-abap-adt/auth-stores` 5 one `<destination>.env` file can hold a destination whole,
 each store reading and writing only its own keys — the means through `EnvDestinationStore`, the
 secret through `AbapSessionStore` (or both in separate directories, as you compose them):
 
@@ -1171,7 +1200,7 @@ What a 4.x consumer must now do, row by row. The full list of changes is the
 
 | 4.x | 5.0.0 — what to do |
 |---|---|
-| `@mcp-abap-adt/auth-providers` 5, `interfaces-auth` 3, `auth-stores` 3 | auth-providers `^6.0.0`, interfaces-auth `^7.5.0`, auth-errors `^2.1.1`, auth-stores `^4.0.0`; one installed copy of each contract (`npm ls`) |
+| `@mcp-abap-adt/auth-providers` 5, `interfaces-auth` 3, `auth-stores` 3 | auth-providers `^6.0.0`, interfaces-auth `^7.5.0`, auth-errors `^2.1.1`, auth-stores `^4.0.0` (`^5.0.0` from 5.0.4, the first published since 5.0.1: a session record without binding keys is refused, see *Errors*); one installed copy of each contract (`npm ls`) |
 | token rows renewed by the provider's built-in rule | pass `renewal: () => refreshThenLogin()` — 4.x's steps; without `renewal` a token row is refused (`missingFields: ['renewal']`) |
 | a `getProvider` provider's failed write never failed the authentication; the token API threw the store's error | pass `onWriteFailure`: `'continue'` keeps 4.x's connector behaviour (best effort); `'fail'` keeps 4.x's token-API behaviour and extends it to the connector and to every later call of the destination while the write is pending. Without it a destination that writes a secret is refused |
 | errors of the token API: auth-providers 5.x classes (`ValidationError`, `BrowserAuthError`, `RefreshError`, …) | `AuthProviderFailure`: read it with `readFailure(error, operation)` and `matchKind` (auth-errors); auth-providers' *Migrating to 6.0.0* maps each class to its kind |
@@ -1215,7 +1244,7 @@ npm test -w @mcp-abap-adt/auth-broker -- AuthBroker.test.ts -t "name of the case
 ```
 
 Tests run sequentially (`maxWorkers: 1`, `maxConcurrency: 1`). The broker suites need nothing:
-fake stores of the contract or auth-stores 4 in temporary directories, real providers, a token
+fake stores of the contract or auth-stores 5 in temporary directories, real providers, a token
 endpoint the test starts on `127.0.0.1`. `AuthBroker.integration.test.ts` reads real service
 keys and sessions only when `packages/auth-broker/tests/test-config.yaml` exists (from the
 template beside it); without it every case returns at once. The stand (`npm run test:stand`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/auth-broker",
-  "version": "5.0.1",
+  "version": "5.0.5",
   "description": "Per-destination credential broker for SAP BTP and ABAP: the IAuthProvider a destination states, built from its key store and session store, with every secret it obtains stored back; and a token API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -65,8 +65,8 @@
   },
   "devDependencies": {
     "@mcp-abap-adt/auth-mocks": "^0.4.0",
-    "@mcp-abap-adt/auth-stores": "^4.0.0",
-    "@mcp-abap-adt/connection": "^14.0.0",
+    "@mcp-abap-adt/auth-stores": "^5.0.0",
+    "@mcp-abap-adt/connection": "^15.0.0",
     "@mcp-abap-adt/logger": "^0.4.0",
     "@types/js-yaml": "^4.0.9",
     "js-yaml": "^4.1.1",