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

package/CHANGELOG.md

@@ -9,6 +9,63 @@ 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.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

@@ -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.4 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 —
@@ -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;;;;;;;;;;;;' }
@@ -829,6 +845,10 @@ const renewed = await tokenRefresher.refreshToken();
 A `@mcp-abap-adt/connection` 14 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.
+
 ## Errors
 
 **A provider's failure passes as the same object.** Whatever a provider throws from
@@ -930,7 +950,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 +1009,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 +1197,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 +1241,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.4",
   "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": "^14.1.0",
     "@mcp-abap-adt/logger": "^0.4.0",
     "@types/js-yaml": "^4.0.9",
     "js-yaml": "^4.1.1",