@mcp-abap-adt/connection 3.0.0 → 5.0.0

package/CHANGELOG.md

@@ -7,6 +7,340 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.0.0] - 2026-08-21
+
+A connection now says which system it is, closes what it opens, and is handed its
+credential instead of being one. See [Migration to 5.0](./docs/MIGRATION-5.0.md).
+
+### Added
+
+- **`AdtOnPremConnector` and `AdtCloudConnector`.** The class you take states which SYSTEM you
+  are dialling; the auth provider states how you authenticate there. The two are independent, and
+  both were reachable combinations that the old shape got wrong: a communication user against
+  ABAP Cloud, and a bearer token against an on-prem system.
+
+  Nothing is detected. `/sap/bc/adt/core/http/sessions` answers on **on-prem too**, publishing
+  both the session resource and the ICF logoff in one document, and its `DELETE` there leaves the
+  session listed while the logoff removes it — a probe would have chosen the mechanism that
+  releases nothing.
+
+- **Auth providers** — `BasicAuthProvider`, `TokenAuthProvider`, `SamlAuthProvider`,
+  `CertificateAuthProvider` — and `IAuthProvider`, the contract they satisfy. A token provider
+  renews on its own, so nothing is cached here: the header is asked for per request, and on a
+  `401` the provider is told its answer was refused (`refreshToken()`) before being asked again.
+
+- **`createAbapConnection(..., { system })`** builds the connector you name, with a provider from
+  the config. Without it, the old choice by `authType`, warned about once per call.
+
+- **`disconnect({ deadlineMs })`** — the parameter `ISessionLifecycleAware` published and nothing
+  implemented. It bounds the **wait**, never the request: handed to axios it would abort the
+  socket and cancel the release it was waiting for.
+
+### Changed — BREAKING
+
+- **`connect()` fails when the server opened no session**, where it used to warn and hand the
+  connection back. A lock is held by the ABAP session, so a connection without one can read but
+  can hold nothing, and the failure surfaced a request later as `400 Session not found` with the
+  object half-edited. Verified rather than inferred: a connection that received no
+  `SAP_SESSIONID` is listed in the server's session list as nothing at all.
+
+- **`disconnect()` makes a network call**, telling the server the session is finished. It does
+  not wait by default — `SAP_RELEASE_DEADLINE_MS` is `0` — because waiting is for steps whose
+  successor needs the server to have caught up, and a teardown has none. Requests still in flight
+  are running on the session being released and will start failing; that is the caller having
+  asked to disconnect.
+
+- **The five auth connection classes are deprecated** and keep working.
+
+### Removed — BREAKING
+
+- **`reset()`**, from `AbstractAbapConnection` and `RfcAbapConnection`. There is no local-only
+  discard because there is no local-only session: it lives on the server, and dropping the cookie
+  leaves it there. `await disconnect()`, then `connect()` again.
+
+### Fixed
+
+- **Requests stay on the server the session lives on.** A session belongs to one application
+  server, so on a multi-node system a request landing elsewhere gets a different session and any
+  lock held on the first dies — no inactivity, nobody at fault. `sap-adt-saplb` is asked for and
+  sent back, as Eclipse does.
+
+- **A late `401` no longer tears down a healthy session.** The comparison is bound to the session
+  the request went out on, so a refusal answered by a session that has since been replaced is
+  retried rather than acted on.
+
+- **A credential that is cookies reaches the wire.** A SAML provider's cookies are part of the
+  contract and merged with the session jar rather than written over by it — one says who we are,
+  the other which session we are in.
+
+- **A session opened before a failed `connect()` is not abandoned**, and the logoff does not cut
+  a lock chain held open with `beginCriticalSection()`.
+
+### Measured
+
+- 25 connects in a row on-prem: **24-25** given a session with the logoff, **2** without.
+- The server's session list shows the row appear at the second of the call, and go on
+  `disconnect()`; without one it would sit for 30 more minutes.
+- The timeout is **idle-based**: 45 small requests a minute apart held one session straight
+  through a 30-minute window, identity unchanged. There is no keepalive timer here on purpose.
+- Cloud: `AdtCloudConnector` with a token provider — session opened through ADT, three stateful
+  requests holding it, closed by `DELETE` on the address the server published.
+
+### Fixed
+
+- **Every session of a reconnect cycle is released, not only the first.** A release already on
+  its way was treated as "the release still owed" whoever it belonged to, so an in-flight logoff
+  for a previous session suppressed the current one's entirely: `connect → disconnect → connect →
+  disconnect` sent **one** logoff and left the second session open. Not an edge case — the
+  default deadline is `0`, so `disconnect()` does not wait for the logoff and a release is
+  routinely still in flight when the next `connect()` happens, which made this the normal path on
+  any server that does not answer instantly. Releases are now keyed by the session they belong
+  to, and both completion handlers clear by that key, so a late answer about one session cannot
+  discard what is owed for another. Sessions still owed are kept as a set rather than one slot,
+  because more than one can be outstanding and the older was being overwritten.
+
+### Removed — BREAKING
+
+- **`reset()` is gone**, from `AbstractAbapConnection` and `RfcAbapConnection`. There is no
+  local-only discard, because there is no local-only session: the session lives on the server,
+  and dropping the cookie leaves it there. The lifecycle is `connect()` / `disconnect()`,
+  repeatable, and both say what they do to the server.
+
+  It carried nothing `disconnect()` lacks — it cleared the fingerprint at the start of teardown
+  rather than at its end, did not join the transition tail, and returned `void`. That last one
+  is the point: a teardown that reports nothing cannot tell the caller whether the session was
+  released, which is the whole subject of this release.
+
+  No callers outside tests, and it is in neither `IAbapConnection` nor `ISessionLifecycleAware`,
+  so consumers programming against the published contracts are unaffected. `RfcAbapConnection`
+  keeps `close()`, which is its own teardown and always was.
+
+  **Migration:** `conn.reset()` → `await conn.disconnect()`, and `connect()` again to carry on —
+  the connection is reusable. A caller that does not want to wait simply does not `await` it,
+  which is what `reset()` was really used for.
+
+### Fixed
+
+- **`disconnect()` tells the server the session is done, not only the client.** Dropping the cookie
+  left the ABAP session alive until its own timeout — default `http/security_session_timeout`,
+  1800 s — so a process that connects repeatedly left one behind every time. Measured on S/4HANA
+  on-prem: 25 connects in a row with the logoff, 24–25 of them were given a session; without it,
+  2. The server-side view is unambiguous — SM04 showed 25 HTTP sessions for the same user, one per
+  `connect()`, each holding ~12.8 MB, all of them opened by `P=/sap/bc/adt/discovery`, which is the
+  establishing call.
+
+  The logoff says the session is no longer needed; **when the server reclaims it is the
+  server's business** — possibly not until the next `connect()` asks for one — and nothing
+  here waits on that or depends on it. So `disconnect()` **does not wait by default**:
+  waiting is for steps whose successor needs the server to have caught up, and a teardown
+  has no successor. A caller that wants a bounded wait passes it —
+  `disconnect({ deadlineMs })`, the parameter `ISessionLifecycleAware` has published all
+  along and which nothing implemented; the default comes from `SAP_RELEASE_DEADLINE_MS`,
+  which is `0`.
+
+  **The deadline bounds the wait, never the request.** When it expires the waiting stops and
+  the logoff carries on to the server — the contract's word is *detach*. Handed to axios as a
+  request timeout instead, it would abort the socket and cancel the very release it was waiting
+  for: `deadlineMs: 200` against a server answering in 500 ms left the session open, and the
+  default of `0` was more reliable than any small positive value.
+
+  **Each caller waits its own deadline.** Concurrent disconnects join one transition and share
+  its promise, so a wait placed inside it was the first caller's wait imposed on everyone — a
+  caller passing `0` sat through another's 30-second budget, the one guarantee the parameter
+  exists to make. The transition now carries only what must happen once: dispatching the logoff
+  and clearing the local state.
+
+  **A repeat call finishes what is still owed**, as `ISessionLifecycleAware` promises. It could
+  not: `clearSessionState()` drops the cookies, so a second call found nothing to send and the
+  session lived out its 1800 s. The cookies of an incomplete release are kept aside for exactly
+  that retry and dropped as soon as one succeeds; a release already on its way is joined rather
+  than duplicated.
+
+  **The logoff does not cut a lock chain in flight.** It ends the session that chain is running
+  on, so a consumer's `finally` firing on shutdown mid-unlock would leave the object locked and
+  inactive — the damage this release exists to prevent, caused by the release itself.
+  `beginCriticalSection()` is honoured here as it already is for timeouts: the local teardown
+  still happens, the session is recorded as still owed, and calling `disconnect()` again once
+  the chain has finished releases it.
+
+- **A malformed `SAP_RELEASE_DEADLINE_MS` is refused at construction, not at teardown.** It
+  reached `parseInt`, came out `NaN`, and threw from **every** `disconnect()` in the process —
+  blaming a `deadlineMs` argument nobody had passed. It is a startup fault: the same on every
+  call, not the caller's argument, and worth refusing a connection over. `Number()` rather than
+  `parseInt()`, which read `"5s"` as `5` and travelled on as a silently wrong bound.
+
+  And `disconnect()` no longer throws at all, which is what it and the interface both promise.
+  Its place is a `finally` — a connection that was connected must be disconnected — and an
+  exception raised there replaces the error that sent the caller into it. A nonsense per-call
+  `deadlineMs` is reported and the default used instead.
+
+  It surfaces as anything but a session problem: once the server stops issuing sessions it still
+  authenticates every request, so stateless reads and writes keep working and only the
+  lock-bound write fails — `200` for the LOCK, a handle, then `400 Session not found` on the next
+  request and a half-edited object.
+
+  ICF rather than ADT because ADT publishes no session-close: its discovery document lists none on
+  any reachable system — on-prem, cloud, or legacy — and the ADT logon is the discovery call
+  itself. Best effort and never throwing: `disconnect()` must always settle, and a session we
+  could not close beats a teardown that hangs.
+
+  How many sessions a system tolerates is the server's business and is not guessed at here. Using
+  few connections, and reusing them, stays the consumer's decision.
+
+- **A connection the server gave no session now warns.** `sessionFingerprint()` tracks
+  `SAP_SESSIONID*` only, so a server that issued none leaves it empty — and an empty fingerprint
+  can never be classified `replaced`: `observe()` returns `established` or `unchanged` forever,
+  `applyIdentityPolicy()` never fires, `getSessionIdentity()` names nothing. Refusing to connect
+  would be the honest answer and is deliberately not done yet: whether cloud ABAP issues this
+  cookie is unverified, and a rule that wrong would break every cloud consumer to fix an on-prem
+  fault.
+
+### Documentation
+
+- **The guides stop recommending `reset()`**, which this release removes. `USAGE.md` had a
+  runnable `connection.reset()` under *Connection Reset*, `STATEFUL_SESSION_GUIDE.md` offered it
+  as the remedy for CSRF errors, and `MIGRATION-2.0.md` described its teardown — anyone following
+  them got `connection.reset is not a function`. They now say what replaces it and why: starting
+  over means telling the server, and dropping a cookie does not.
+- A doc block left dangling by the same removal had `close()` in `RfcAbapConnection` documented as
+  "Reset the connection … Provides interface compatibility with HTTP connections" — an API that no
+  longer exists.
+
+### Tests
+
+- The stub in `sessionComposition.test.ts` answered every route instantly, `/sap/bc/adt/slow`
+  included, so *does not wait for an in-flight request* held whenever `disconnect()` performed no
+  I/O rather than because the teardown declined to wait. That route now takes 300 ms and the test
+  asserts what its name says.
+- `sessionTeardown.test.ts` covers the teardown contract from the caller's side: the logoff goes
+  out with the session cookies and without a request timeout at any budget; it is detached rather
+  than aborted when a deadline expires; a failing logoff still disconnects; a repeat call re-sends
+  what is owed and sends nothing once it succeeded; two concurrent disconnects share one logoff
+  and keep separate deadlines; a critical section defers it; and a malformed
+  `SAP_RELEASE_DEADLINE_MS` refuses construction.
+
+### Fixed
+
+- **`disconnect()` releases the session this connection holds, and nothing else.** What grew
+  around that sentence — a map of owed sessions, a map of releases in flight, an attempt counter,
+  a give-up rule, a retry across reconnects, and the waiting rules to go with them — is gone. Four
+  review rounds found a defect in each round's own fix, every one of them in that machinery, and
+  none of it was needed: **a connection holds one session**. `connect()` opens it, `disconnect()`
+  closes it, a repeat `connect()` is a NEW session with a new `SAP_SESSIONID`, and an earlier
+  session is not this connection's business — its logoff is already on the wire, or the system
+  times it out.
+
+  Nothing retries, counts, limits or keeps a list. How many connections to run, how frugally, and
+  what to do when a release did not land are the caller's, and were never knowable from inside a
+  single connection.
+
+  The session a release belongs to is now its `SAP_SESSIONID`, not the cookie header it is sent
+  with. The header also carries `sap-XSRF_*`, which rotates within one and the same session, so
+  comparing headers made a session stop recognising itself after a token refresh.
+
+- **A logoff that cannot even be assembled no longer escapes the teardown.** Building it can throw
+  on its own — a certificate connection whose material is not loaded throws while building the
+  agent — and `disconnect()` is documented never to throw and is called from a `finally`, where a
+  throw replaces the error that sent the caller there.
+
+### Documentation
+
+- **The cookies are the session, and a logoff ends it for everyone holding them.** A second
+  connection given the same cookie jar works in the same ABAP session and can use the locks taken
+  in it; `disconnect()` closes that session for all of them, and no connection can see the copies.
+  Written down in `STATEFUL_SESSION_GUIDE.md` and on `disconnect()` itself.
+
+### Changed — BREAKING
+
+- **`connect()` fails when the server opened no session**, instead of warning and handing back a
+  connection whose first lock would be dead on arrival. Locks are held by the ABAP session, so a
+  connection without one can read but can hold nothing; the failure used to surface a request
+  later, as `400 Session not found` with the object half-edited.
+
+  Verified rather than inferred: a connection that received no `SAP_SESSIONID` was held open
+  against an on-prem system and the session list showed **nothing** for it, while one that
+  received the cookie appeared there. No cookie, no session.
+
+  Reported, not decided on. The message says what the server did, what still works, what does
+  not, the usual cause — sessions are limited per user and shared with every other tool logged on
+  as them — and that nothing is retried here, because whether to wait, retry, or release sessions
+  the user still holds depends on what only the caller knows.
+
+  Every transport, not only basic: splitting by authentication type would encode a guess about
+  cloud ABAP, whose ADT endpoint would not answer the bearer obtainable here. If a cloud system
+  turns out to hold sessions without issuing this cookie, this is the rule to revisit.
+
+### Documentation
+
+- **`STATEFUL_SESSION_GUIDE.md` gains "A Lock Lives In The Session".** That a lock dies with the
+  session that took it; that the timeout is an idle one, spent by silence rather than by elapsed
+  time — one small request a minute kept a session alive for 45 minutes past a 30-minute window,
+  identity unchanged; and that any request in the session resets it, which is why this package
+  holds no keepalive timer. Holding a session alive holds a scarce shared slot, and that is the
+  caller's decision to make.
+
+## [4.0.0] - 2026-08-16
+
+A JWT connection stops answering with an error of its own making. See
+[docs/MIGRATION-4.0.md](docs/MIGRATION-4.0.md).
+
+### Breaking
+
+- **A 403 no longer triggers a token refresh.** It means the server authenticated the caller and
+  refused the action anyway, so a new token is the same caller and cannot change the answer.
+- **`Error('JWT token has expired. Please re-authenticate.')` is gone.** Both a 401 and a 403 were
+  reported with it, and the original `AxiosError` was discarded along with the status and the
+  body. The server's error now reaches the caller unchanged. Code matching on that message must
+  branch on `error.response.status` instead — which it can now do.
+
+### Fixed
+
+- The substring guard meant to let permission failures past matched three literal strings and SAP
+  sends none of them: the type is `ExceptionResourceNoAuthorization`, not `...NoAccess`, and the
+  message reads "not authorized", not "No authorization". The list is deleted rather than
+  extended — it enumerated prose, so the next unlisted wording would have been the same defect
+  ([#30](https://github.com/fr0ster/mcp-abap-connection/issues/30)).
+- A 401 that survives a renewal is now logged at ERROR. The previous log fired only when the
+  renewal never happened, so the case the deleted message was actually about passed silently.
+- `establishSession` no longer refreshes or recurses into itself. `fetchCsrfToken` owns recovery
+  during establishment; a second refresh at the outer level asked the same refresher the same
+  question, and the recursion was unbounded whenever the refresher kept resolving.
+- `JwtAbapConnection.fetchCsrfToken` declared three parameters where the base declares four and
+  called `super` with three, silently dropping the `generation` that fences response effects.
+  TypeScript accepts that — fewer parameters are assignable to more. Latent rather than live:
+  both call sites that pass one are gated on basic auth.
+
+### Changed
+
+- **One credential renewal per caller-visible operation, session included.** Concurrent requests
+  meeting the same expired token now share a single token fetch *and* a single session
+  re-establishment. Previously each ran its own teardown and recovery — and since `recover` and
+  `cleanup` never join, one request's cleanup could tear down the session another had just
+  rebuilt, leaving its retry at a closed door.
+- The renewal decision is made against the credential state the operation started with, carried
+  in a per-connection `AsyncLocalStorage`. A nested token-only refresh no longer passes for a
+  session recovery.
+- A retry is abandoned with `ADT_NOT_CONNECTED` if the connection was torn down between the last
+  lifecycle check and the retry itself.
+- `establishSession` takes its CSRF retry defaults from `CSRF_CONFIG` at all four authentication
+  types instead of repeating `3, 1000` in each.
+
+### Documentation
+
+- New [MIGRATION-4.0.md](docs/MIGRATION-4.0.md), linked from the README and the docs index, which
+  now has an *Upgrading* section — the 2.0 migration guide was in the tree but linked from
+  nowhere but a directory listing.
+- `USAGE.md` gains the classification table; `STATEFUL_SESSION_GUIDE.md` notes that a 401-driven
+  refresh replaces the SAP session and surfaces as `ADT_SESSION_REPLACED` inside a lock window,
+  while a 403 tears down nothing; the README and both examples no longer promise a refresh on
+  403.
+
+### Known
+
+- Whether some BTP setup answers an *invalid* token with 403 rather than 401 is unobserved and
+  tracked in [#32](https://github.com/fr0ster/mcp-abap-connection/issues/32). Preserving the
+  original error is what makes the assumption safe to be wrong about.
+
 ## [3.0.0] - 2026-08-03
 
 Undoes two mistakes from 2.0.0, four days old. Everything else that release
@@ -786,7 +1120,9 @@ const connection = createAbapConnection(config, logger);
 - JWT token refresh now properly handles connection errors (401/403 during initial connect)
 - Permission errors (403 with "ExceptionResourceNoAccess") no longer trigger JWT refresh loops
 - Proper separation: base class handles HTTP/session, concrete classes handle auth-specific errors
-[Unreleased]: https://github.com/fr0ster/mcp-abap-connection/compare/v3.0.0...HEAD
+[Unreleased]: https://github.com/fr0ster/mcp-abap-connection/compare/v5.0.0...HEAD
+[5.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v4.0.0...v5.0.0
+[4.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v3.0.0...v4.0.0
 [3.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v2.0.0...v3.0.0
 [2.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v1.10.2...v2.0.0
 [1.10.2]: https://github.com/fr0ster/mcp-abap-connection/compare/v1.10.1...v1.10.2

package/README.md

@@ -17,8 +17,8 @@ ABAP connection layer for MCP ABAP ADT server. Provides a unified interface for
   - Session headers management (cookies, CSRF tokens)
   - Session state persistence is handled by `@mcp-abap-adt/auth-broker` package
 - 🏗️ **Clean Architecture**:
-  - Abstract base class for common HTTP/session logic
-  - Auth-type specific implementations (BaseAbapConnection, JwtAbapConnection, SamlAbapConnection)
+  - One connector per SYSTEM (`AdtOnPremConnector`, `AdtCloudConnector`), handed an auth provider
+  - Authentication is a parameter, not a subclass — nothing about the system is inferred from it
   - Proper separation of concerns - no JWT logic in base class
 - 🔌 **Realtime Transport Scaffold**:
   - Generic `GenericWebSocketTransport` with pluggable WS factory
@@ -39,21 +39,31 @@ The package uses a clean separation of concerns:
   - CSRF token fetching with retry
   - Auth-agnostic - knows nothing about Basic or JWT
   
-- **`BaseAbapConnection`** (concrete, exported):
-  - Basic Authentication implementation
-  - `connect()` establishes the session (required before any request)
-  - Suitable for on-premise SAP systems
-  
-- **`JwtAbapConnection`** (concrete, exported):
-  - JWT/OAuth2 Authentication implementation
-  - `connect()` establishes the session with the JWT token (required before any request)
-  - Suitable for SAP BTP ABAP Environment
-  - Token refresh handled by auth-broker package
-
-- **`SamlAbapConnection`** (concrete, exported):
-  - Session-cookie-based authentication (`authType: "saml"`)
-  - Uses existing SSO/SAML session cookies
-  - Fetches CSRF token and executes ADT requests in same HTTP model
+- **`AdtOnPremConnector`** (concrete, exported):
+  - An on-prem system: the session arrives with the establishing call, and the platform's
+    ICF logoff is how it is given back
+  - Takes an auth provider — basic, SAML, certificate, a bearer token, whatever you hold
+
+- **`AdtCloudConnector`** (concrete, exported):
+  - An ABAP Cloud system: a session is a resource, opened at
+    `/sap/bc/adt/core/http/sessions` and given back by `DELETE` on the address it publishes
+  - Takes an auth provider, same as above
+
+  **Which one you take is how you say where you are dialling.** Nothing is probed:
+  the session resource answers on on-prem too, and its `DELETE` there leaves the
+  session open while the logoff removes it — so asking the server would pick the
+  mechanism that releases nothing.
+
+- **Auth providers** (`BasicAuthProvider`, `TokenAuthProvider`, `SamlAuthProvider`,
+  `CertificateAuthProvider`):
+  - What a connection authenticates with, passed in
+  - A token provider renews on its own; the connector asks it per request and, on a
+    `401`, tells it the answer was refused before asking again
+
+- **`BaseAbapConnection`, `JwtAbapConnection`, `SamlAbapConnection`,
+  `CertificateAbapConnection`, `KerberosAbapConnection`** (deprecated, still exported):
+  - The previous shape, where the class stated your credential and the session
+    mechanism came with it. See [Migration to 5.0](./docs/MIGRATION-5.0.md)
 
 - **`GenericWebSocketTransport`** (concrete, exported):
   - Transport abstraction for realtime WS message flows
@@ -113,6 +123,7 @@ This package interacts with external packages **ONLY through interfaces**:
 
 - 📦 **[Installation Guide](./docs/INSTALLATION.md)** - Setup and installation instructions
 - 📚 **[Usage Guide](./docs/USAGE.md)** - Detailed usage examples and API documentation
+- 🚚 **[Migration to 4.0.0](./docs/MIGRATION-4.0.md)** - a 401 refreshes the token, a 403 reaches you with the server's message; the synthesised "JWT token has expired" is gone
 - 🚚 **[Migration: the explicit session lifecycle](./docs/MIGRATION-2.0.md)** - `connect()` is now required; start here if you are coming from 1.x
 - 💡 **[Examples](./examples/)** - Working code examples
 
@@ -157,7 +168,9 @@ const logger = {
 };
 
 // Create connection
-const connection = createAbapConnection(config, logger);
+const connection = createAbapConnection(config, logger, undefined, undefined, {
+  system: "onprem", // which SYSTEM this is — said, never detected
+});
 await connection.connect();   // required before any request
 
 // Make ADT request
@@ -188,7 +201,9 @@ const logger = {
 };
 
 // Logger is optional - if not provided, no logging output
-const connection = createAbapConnection(config, logger);
+const connection = createAbapConnection(config, logger, undefined, undefined, {
+  system: "cloud", // which SYSTEM this is — said, never detected
+});
 await connection.connect();
 
 // Note: Token refresh is handled by @mcp-abap-adt/auth-broker package
@@ -209,7 +224,9 @@ const config: SapConfig = {
   sessionCookies: "MYSAPSSO2=...; SAP_SESSIONID=...",
 };
 
-const connection = createAbapConnection(config, logger);
+const connection = createAbapConnection(config, logger, undefined, undefined, {
+  system: "onprem", // which SYSTEM this is — said, never detected
+});
 await connection.connect();
 
 const response = await connection.makeAdtRequest({
@@ -220,10 +237,14 @@ const response = await connection.makeAdtRequest({
 
 ### Cloud Usage with Automatic Token Refresh
 
-For automatic token refresh on 401/403 errors, inject `ITokenRefresher`:
+For automatic token refresh on **401** errors, inject `ITokenRefresher`:
 
 ```typescript
-import { JwtAbapConnection, SapConfig } from "@mcp-abap-adt/connection";
+import {
+  AdtCloudConnector,
+  TokenAuthProvider,
+  SapConfig,
+} from "@mcp-abap-adt/connection";
 import type { ITokenRefresher } from "@mcp-abap-adt/interfaces";
 
 // Token refresher provides token acquisition and refresh
@@ -233,26 +254,44 @@ const tokenRefresher: ITokenRefresher = {
   refreshToken: async () => { /* refresh and return new token */ },
 };
 
-// JWT configuration
 const config: SapConfig = {
   url: "https://your-instance.abap.cloud.sap",
   authType: "jwt",
-  jwtToken: await tokenRefresher.getToken(), // Get initial token
 };
 
-// Create connection with token refresher - 401/403 handled automatically
-const connection = new JwtAbapConnection(config, logger, undefined, tokenRefresher);
+// The connector says which SYSTEM this is; the provider says how to
+// authenticate. Neither decides the other.
+const connection = new AdtCloudConnector(
+  config,
+  new TokenAuthProvider(tokenRefresher),
+  logger,
+);
 await connection.connect();
 
-// Requests automatically retry with refreshed token on auth errors. A refresh
-// replaces the SAP session, so if a lock window is open the request fails with
-// ADT_SESSION_REPLACED instead of continuing on a session your lock is not in.
+// On a 401 the connector tells the provider its token was refused, asks again,
+// and only if the answer changed rebuilds the session and retries once. An
+// unchanged answer means the server refused these credentials, and the 401
+// reaches you. A refresh replaces the SAP session, so if a lock window is open
+// the request fails with ADT_SESSION_REPLACED rather than continuing on a
+// session your lock is not in.
 const response = await connection.makeAdtRequest({
   method: "GET",
   url: "/sap/bc/adt/programs/programs/your-program",
 });
 ```
 
+**A 403 is never treated as an expired token.** It means the server
+authenticated the caller and refused the action anyway, so no credential can
+change the answer. It propagates unchanged — `error.response.status` and the
+server's message, which usually names the authorization object — rather than
+being reported as an expired token.
+
+Earlier versions reported both 401 and 403 as
+`JWT token has expired. Please re-authenticate.` and discarded the original
+error. Code matching on that message must branch on `error.response.status`
+instead — which it can now do, since the status is no longer thrown away.
+See [MIGRATION-4.0.md](./docs/MIGRATION-4.0.md).
+
 ### Stateful Sessions
 
 For operations that require session state (e.g., object modifications), you can enable stateful sessions:
@@ -260,7 +299,9 @@ For operations that require session state (e.g., object modifications), you can
 ```typescript
 import { createAbapConnection } from "@mcp-abap-adt/connection";
 
-const connection = createAbapConnection(config, logger);
+const connection = createAbapConnection(config, logger, undefined, undefined, {
+  system: "onprem", // which SYSTEM this is — said, never detected
+});
 await connection.connect();
 
 // Enable stateful session mode (adds x-sap-adt-sessiontype: stateful header)
@@ -308,7 +349,9 @@ class MyLogger implements ILogger {
 }
 
 const logger = new MyLogger();
-const connection = createAbapConnection(config, logger);
+const connection = createAbapConnection(config, logger, undefined, undefined, {
+  system: "onprem", // which SYSTEM this is — said, never detected
+});
 ```
 
 ## CLI Tool

package/dist/auth/IAuthProvider.d.ts

@@ -0,0 +1,84 @@
+/**
+ * How a connection proves who it is — passed in, not inherited.
+ *
+ * The class a consumer takes says which SYSTEM it is dialling; this says how it
+ * authenticates there. The two are independent: a communication user against
+ * ABAP Cloud and a bearer token against on-prem are both ordinary, and a design
+ * where the credential picks the system's session mechanism gets one of them
+ * wrong whichever way it guesses.
+ *
+ * Deliberately not "give me a token". Four of the five ways in are not tokens:
+ * basic is a header built from a username, a certificate is TLS material and no
+ * header at all, and SPNEGO is a negotiation with the server. What every one of
+ * them has in common is small, and it is this.
+ *
+ * `establishSession()` is NOT here. Measured across all five implementations it
+ * is the same work — fetch a CSRF token from `/sap/bc/adt/discovery`, keep it,
+ * tolerate a failure — with the only difference being a step before it, which is
+ * `prepare()`.
+ */
+import type { AgentOptions } from 'node:https';
+export interface IAuthProvider {
+    /** For logs, so which credential ran is never inferred from behaviour. */
+    readonly kind: string;
+    /**
+     * Get ready before anything is sent: load key material, unlock a store.
+     * Called once per establishment, before the first request.
+     *
+     * Not for tokens. A stateful token provider caches and renews on its own, so
+     * asking it IS the preparation — and holding what it returned would hide the
+     * renewal it exists to do.
+     *
+     * Optional because most credentials are ready as constructed. A credential
+     * that throws here fails the connect, which is correct — it has nothing to
+     * authenticate with.
+     */
+    prepare?(): Promise<void>;
+    /**
+     * The `Authorization` header value, or `''` when this credential is not a
+     * header — a certificate authenticates through TLS and has none.
+     *
+     * **Asked per request, and asynchronous, because the answer can change.** A
+     * token provider checks expiry and renews behind this call; anything cached
+     * on this side would serve the stale token and defeat it. Cheap in the
+     * ordinary case for the same reason: the provider holds the token and only
+     * goes to the network when it has expired.
+     */
+    authorizationHeader(): Promise<string>;
+    /**
+     * The server refused what this last handed out; get a new one.
+     *
+     * Separate from `authorizationHeader()` because the two questions are
+     * different, and the token contract says so: `getToken()` "may return cached
+     * token if still valid", while `refreshToken()` is documented as the one to
+     * call "when getToken() returned a token that was rejected by server". Asking
+     * the first again after a 401 gets the same rejected token back, and the
+     * renewal never happens.
+     *
+     * Omitted by credentials that cannot be renewed — a password is a password.
+     */
+    renew?(): Promise<void>;
+    /**
+     * Cookies this credential authenticates with, for the ways in where the
+     * session was negotiated elsewhere and handed over — SAML is one.
+     *
+     * Part of the contract rather than a method a provider happens to have: the
+     * first version left it off, so `SamlAuthProvider` held the cookies, nothing
+     * ever asked for them, and the recommended replacement authenticated with
+     * nothing at all.
+     */
+    cookies?(): string;
+    /**
+     * TLS options for credentials that live in the transport rather than in a
+     * header. Omitted by everything else.
+     */
+    httpsAgentOptions?(): AgentOptions;
+    /**
+     * Fetch the CSRF token this credential's own way.
+     *
+     * Only SPNEGO needs it: its token is consumed by one request and the exchange
+     * is the fetch. Everything else leaves it out and gets the shared path.
+     */
+    fetchCsrfToken?(url: string): Promise<string>;
+}
+//# sourceMappingURL=IAuthProvider.d.ts.map

package/dist/auth/IAuthProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IAuthProvider.d.ts","sourceRoot":"","sources":["../../src/auth/IAuthProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B;;;;;;;;;OASG;IACH,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAEvC;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExB;;;;;;;;OAQG;IACH,OAAO,CAAC,IAAI,MAAM,CAAC;IAEnB;;;OAGG;IACH,iBAAiB,CAAC,IAAI,YAAY,CAAC;IAEnC;;;;;OAKG;IACH,cAAc,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/C"}

package/dist/auth/IAuthProvider.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * How a connection proves who it is — passed in, not inherited.
+ *
+ * The class a consumer takes says which SYSTEM it is dialling; this says how it
+ * authenticates there. The two are independent: a communication user against
+ * ABAP Cloud and a bearer token against on-prem are both ordinary, and a design
+ * where the credential picks the system's session mechanism gets one of them
+ * wrong whichever way it guesses.
+ *
+ * Deliberately not "give me a token". Four of the five ways in are not tokens:
+ * basic is a header built from a username, a certificate is TLS material and no
+ * header at all, and SPNEGO is a negotiation with the server. What every one of
+ * them has in common is small, and it is this.
+ *
+ * `establishSession()` is NOT here. Measured across all five implementations it
+ * is the same work — fetch a CSRF token from `/sap/bc/adt/discovery`, keep it,
+ * tolerate a failure — with the only difference being a step before it, which is
+ * `prepare()`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });