@mcp-abap-adt/connection 3.0.0 → 4.0.0

package/CHANGELOG.md

@@ -7,6 +7,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +848,8 @@ 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/v4.0.0...HEAD
+[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

@@ -113,6 +113,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
 
@@ -220,7 +221,7 @@ 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";
@@ -240,7 +241,7 @@ const config: SapConfig = {
   jwtToken: await tokenRefresher.getToken(), // Get initial token
 };
 
-// Create connection with token refresher - 401/403 handled automatically
+// Create connection with token refresher - 401 handled automatically
 const connection = new JwtAbapConnection(config, logger, undefined, tokenRefresher);
 await connection.connect();
 
@@ -253,6 +254,18 @@ const response = await connection.makeAdtRequest({
 });
 ```
 
+**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:

package/dist/connection/BaseAbapConnection.js

@@ -25,7 +25,7 @@ class BaseAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnect
         this.logger?.debug(`[DEBUG] BaseAbapConnection - Connecting to SAP system: ${discoveryUrl}`);
         try {
             // Try to get CSRF token (this will also get cookies)
-            const token = await this.fetchCsrfToken(discoveryUrl, 3, 1000);
+            const token = await this.fetchCsrfToken(discoveryUrl);
             this.setCsrfToken(token);
             this.logger?.debug('Successfully connected to SAP system', {
                 hasCsrfToken: !!this.getCsrfToken(),

package/dist/connection/CertificateAbapConnection.js

@@ -47,7 +47,7 @@ class CertificateAbapConnection extends AbstractAbapConnection_js_1.AbstractAbap
         const baseUrl = await this.getBaseUrl();
         const discoveryUrl = `${baseUrl}/sap/bc/adt/discovery`;
         try {
-            const token = await this.fetchCsrfToken(discoveryUrl, 3, 1000);
+            const token = await this.fetchCsrfToken(discoveryUrl);
             this.setCsrfToken(token);
         }
         catch (error) {

package/dist/connection/JwtAbapConnection.d.ts

@@ -1,4 +1,4 @@
-import type { IAdtResponse, ITokenRefresher } from '@mcp-abap-adt/interfaces';
+import { type IAdtResponse, type ITokenRefresher } from '@mcp-abap-adt/interfaces';
 import type { SapConfig } from '../config/sapConfig.js';
 import type { ILogger } from '../logger.js';
 import type { AbapRequestOptions } from './AbapConnection.js';
@@ -7,19 +7,92 @@ import { AbstractAbapConnection } from './AbstractAbapConnection.js';
  * JWT Authentication connection for SAP BTP Cloud systems
  *
  * Supports automatic token refresh via ITokenRefresher injection:
- * - If tokenRefresher is provided, 401/403 errors trigger automatic token refresh
- * - If tokenRefresher is not provided, 401/403 errors throw an error (legacy behavior)
+ * - a **401** triggers a token refresh when a tokenRefresher is available;
+ * - without one, or when the refresh does not help, the server's own error is
+ *   thrown unchanged — status and body intact;
+ * - a **403** is never a token problem. It propagates as it arrived, because a
+ *   new token is the same caller and cannot change a permissions answer.
  */
 export declare class JwtAbapConnection extends AbstractAbapConnection {
     private tokenRefresher?;
     private currentToken;
+    /** Bumped by any token refresh, token-only ones included. */
+    private tokenGeneration;
+    /** Single-flight over the token fetch alone. Touches no session state. */
+    private tokenRefreshInFlight?;
+    /**
+     * The `tokenGeneration` a completed session recovery was built for. Only
+     * `performRenewal` moves it, and only after `recoverSession` resolves.
+     *
+     * Separate from `tokenGeneration` because a token-only refresh — which
+     * `fetchCsrfToken` does, from inside an establishment — bumps that counter
+     * without rebuilding anything. Reading it as "the session is settled" made
+     * the outer handler retry a request whose session was never rebuilt.
+     */
+    private recoveredGeneration;
+    /**
+     * Single-flight over the whole credential renewal, session included.
+     *
+     * Sharing only the token fetch leaves the expensive half racing: `recover`
+     * and `cleanup` never join (`SessionLifecycle.transition`), so two concurrent
+     * renewals queue as cleanup A → recover A → cleanup B → recover B, and A's
+     * retry meets a session B has just torn down.
+     */
+    private renewalInFlight?;
+    /**
+     * Per connection, deliberately NOT static. `baseline` is compared against
+     * `this.tokenGeneration`, which is instance state — a store shared between
+     * instances would let one connection's operation hand its baseline to
+     * another's, and the comparison would be between unrelated counters.
+     */
+    private readonly recoveryScope;
     constructor(config: SapConfig, logger?: ILogger | null, sessionId?: string, tokenRefresher?: ITokenRefresher);
     protected buildAuthorizationHeader(): string;
     /**
-     * Refresh the JWT token using the injected tokenRefresher
-     * @returns true if token was refreshed, false if no refresher available
+     * For the public entry point: this call is its own operation, always.
+     *
+     * A re-entrant `makeAdtRequest` — from a logger or a refresher callback the
+     * connection itself invokes while a scope is live — is a new caller-visible
+     * operation. Inheriting there would hand it a baseline from somebody else's
+     * refresh, which reads as "already refreshed for me" and skips a refresh it
+     * needs.
+     */
+    private inNewRecoveryScope;
+    /** For the inner levels: join the operation in progress, or start one. */
+    private inRecoveryScope;
+    /**
+     * The baseline this operation is reasoning from.
+     *
+     * The `active` check here and the one in `inRecoveryScope` OVERLAP: each
+     * compensates for the other, and the stale-context test only fails when both
+     * are removed. Kept as two because they answer different questions — "may I
+     * join this scope" and "may I trust this baseline" — and a reader who finds
+     * one redundant would be deleting half a guarantee.
+     */
+    private currentBaseline;
+    /**
+     * Fetch a new token, unless somebody already did for this operation.
+     *
+     * Single-flighted so two concurrent handlers — including two nested
+     * `fetchCsrfToken` calls, which is a level `renewalInFlight` cannot reach —
+     * share one network call instead of racing and leaving `currentToken` as
+     * whichever settled last.
+     *
+     * @returns true when the caller may retry.
+     */
+    private refreshTokenOnce;
+    private performTokenRefresh;
+    /**
+     * Renew the credential and the session it belongs to, once, shared.
+     */
+    private renewCredential;
+    private performRenewal;
+    /**
+     * May this operation retry?
+     *
+     * The order of the checks is the design, not style.
      */
-    private tryRefreshToken;
+    private ensureRecovered;
     /**
      * Establishes the session for this auth type. Called by
      * AbstractAbapConnection.connect(), which owns the lifecycle around it.
@@ -29,10 +102,14 @@ export declare class JwtAbapConnection extends AbstractAbapConnection {
      * Override makeAdtRequest to handle JWT auth errors with automatic token refresh
      */
     makeAdtRequest<T = any, D = any>(options: AbapRequestOptions): Promise<IAdtResponse<T, D>>;
+    private attemptRequest;
     /**
      * Override fetchCsrfToken to handle JWT auth errors with automatic token refresh
      */
-    protected fetchCsrfToken(url: string, retryCount?: number, retryDelay?: number): Promise<string>;
+    protected fetchCsrfToken(url: string, retryCount?: number, retryDelay?: number, 
+    /** Fences the response effects; omitted during connect(), which has no lease. */
+    generation?: number): Promise<string>;
+    private attemptCsrfToken;
     private static validateConfig;
 }
 //# sourceMappingURL=JwtAbapConnection.d.ts.map

package/dist/connection/JwtAbapConnection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"JwtAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/JwtAbapConnection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAE9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAErE;;;;;;GAMG;AACH,qBAAa,iBAAkB,SAAQ,sBAAsB;IAC3D,OAAO,CAAC,cAAc,CAAC,CAAkB;IACzC,OAAO,CAAC,YAAY,CAAS;gBAG3B,MAAM,EAAE,SAAS,EACjB,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,EACvB,SAAS,CAAC,EAAE,MAAM,EAClB,cAAc,CAAC,EAAE,eAAe;IAWlC,SAAS,CAAC,wBAAwB,IAAI,MAAM;IAW5C;;;OAGG;YACW,eAAe;IA0B7B;;;OAGG;cACa,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IA2DjD;;OAEG;IACG,cAAc,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG,EACnC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAiE9B;;OAEG;cACa,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,UAAU,SAAI,EACd,UAAU,SAAO,GAChB,OAAO,CAAC,MAAM,CAAC;IA2ClB,OAAO,CAAC,MAAM,CAAC,cAAc;CAa9B"}
+{"version":3,"file":"JwtAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/JwtAbapConnection.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAuBrE;;;;;;;;;GASG;AACH,qBAAa,iBAAkB,SAAQ,sBAAsB;IAC3D,OAAO,CAAC,cAAc,CAAC,CAAkB;IACzC,OAAO,CAAC,YAAY,CAAS;IAE7B,6DAA6D;IAC7D,OAAO,CAAC,eAAe,CAAK;IAE5B,0EAA0E;IAC1E,OAAO,CAAC,oBAAoB,CAAC,CAAmB;IAEhD;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB,CAAK;IAEhC;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe,CAAC,CAAmB;IAE3C;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2C;gBAGvE,MAAM,EAAE,SAAS,EACjB,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,EACvB,SAAS,CAAC,EAAE,MAAM,EAClB,cAAc,CAAC,EAAE,eAAe;IAWlC,SAAS,CAAC,wBAAwB,IAAI,MAAM;IAW5C;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAc1B,0EAA0E;IAC1E,OAAO,CAAC,eAAe;IASvB;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IAQvB;;;;;;;;;OASG;IACH,OAAO,CAAC,gBAAgB;YAsBV,mBAAmB;IAoBjC;;OAEG;IACH,OAAO,CAAC,eAAe;YAiBT,cAAc;IAwB5B;;;;OAIG;YACW,eAAe;IAyB7B;;;OAGG;cACa,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BjD;;OAEG;IACG,cAAc,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG,EACnC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAKhB,cAAc;IA8D5B;;OAEG;cACa,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,UAAU,GAAE,MAAgC,EAC5C,UAAU,GAAE,MAAgC;IAC5C,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC;YASJ,gBAAgB;IAkD9B,OAAO,CAAC,MAAM,CAAC,cAAc;CAa9B"}

package/dist/connection/JwtAbapConnection.js

@@ -1,18 +1,66 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.JwtAbapConnection = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+const interfaces_1 = require("@mcp-abap-adt/interfaces");
 const axios_1 = require("axios");
+const SessionLifecycle_js_1 = require("../session/SessionLifecycle.js");
 const AbstractAbapConnection_js_1 = require("./AbstractAbapConnection.js");
+const csrfConfig_js_1 = require("./csrfConfig.js");
+/**
+ * Is this worth refreshing a token for?
+ *
+ * 401 only. A 403 means the server authenticated the caller and refused the
+ * action anyway — a new token is the same caller, so refreshing answers a
+ * question nobody asked and, worse, used to end with the original error
+ * replaced by "JWT token has expired". See issue #30.
+ */
+function isTokenExpiryCandidate(error) {
+    return error instanceof axios_1.AxiosError && error.response?.status === 401;
+}
 /**
  * JWT Authentication connection for SAP BTP Cloud systems
  *
  * Supports automatic token refresh via ITokenRefresher injection:
- * - If tokenRefresher is provided, 401/403 errors trigger automatic token refresh
- * - If tokenRefresher is not provided, 401/403 errors throw an error (legacy behavior)
+ * - a **401** triggers a token refresh when a tokenRefresher is available;
+ * - without one, or when the refresh does not help, the server's own error is
+ *   thrown unchanged — status and body intact;
+ * - a **403** is never a token problem. It propagates as it arrived, because a
+ *   new token is the same caller and cannot change a permissions answer.
  */
 class JwtAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnection {
     tokenRefresher;
     currentToken;
+    /** Bumped by any token refresh, token-only ones included. */
+    tokenGeneration = 0;
+    /** Single-flight over the token fetch alone. Touches no session state. */
+    tokenRefreshInFlight;
+    /**
+     * The `tokenGeneration` a completed session recovery was built for. Only
+     * `performRenewal` moves it, and only after `recoverSession` resolves.
+     *
+     * Separate from `tokenGeneration` because a token-only refresh — which
+     * `fetchCsrfToken` does, from inside an establishment — bumps that counter
+     * without rebuilding anything. Reading it as "the session is settled" made
+     * the outer handler retry a request whose session was never rebuilt.
+     */
+    recoveredGeneration = 0;
+    /**
+     * Single-flight over the whole credential renewal, session included.
+     *
+     * Sharing only the token fetch leaves the expensive half racing: `recover`
+     * and `cleanup` never join (`SessionLifecycle.transition`), so two concurrent
+     * renewals queue as cleanup A → recover A → cleanup B → recover B, and A's
+     * retry meets a session B has just torn down.
+     */
+    renewalInFlight;
+    /**
+     * Per connection, deliberately NOT static. `baseline` is compared against
+     * `this.tokenGeneration`, which is instance state — a store shared between
+     * instances would let one connection's operation hand its baseline to
+     * another's, and the comparison would be between unrelated counters.
+     */
+    recoveryScope = new node_async_hooks_1.AsyncLocalStorage();
     constructor(config, logger, sessionId, tokenRefresher) {
         JwtAbapConnection.validateConfig(config);
         super(config, logger || null, sessionId);
@@ -31,18 +79,90 @@ class JwtAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnecti
         return `Bearer ${this.currentToken}`;
     }
     /**
-     * Refresh the JWT token using the injected tokenRefresher
-     * @returns true if token was refreshed, false if no refresher available
+     * For the public entry point: this call is its own operation, always.
+     *
+     * A re-entrant `makeAdtRequest` — from a logger or a refresher callback the
+     * connection itself invokes while a scope is live — is a new caller-visible
+     * operation. Inheriting there would hand it a baseline from somebody else's
+     * refresh, which reads as "already refreshed for me" and skips a refresh it
+     * needs.
+     */
+    inNewRecoveryScope(fn) {
+        const scope = {
+            baseline: this.tokenGeneration,
+            active: true,
+        };
+        return this.recoveryScope.run(scope, async () => {
+            try {
+                return await fn();
+            }
+            finally {
+                scope.active = false;
+            }
+        });
+    }
+    /** For the inner levels: join the operation in progress, or start one. */
+    inRecoveryScope(fn) {
+        const inherited = this.recoveryScope.getStore();
+        // Only a scope that is still running. A store reached through an async
+        // resource that outlived its operation is stale, and its baseline describes
+        // a credential state that has since moved.
+        if (inherited?.active)
+            return fn();
+        return this.inNewRecoveryScope(fn);
+    }
+    /**
+     * The baseline this operation is reasoning from.
+     *
+     * The `active` check here and the one in `inRecoveryScope` OVERLAP: each
+     * compensates for the other, and the stale-context test only fails when both
+     * are removed. Kept as two because they answer different questions — "may I
+     * join this scope" and "may I trust this baseline" — and a reader who finds
+     * one redundant would be deleting half a guarantee.
+     */
+    currentBaseline() {
+        const scope = this.recoveryScope.getStore();
+        // No live scope means a caller reached a handler by a path that does not
+        // open one, or through a stale async context. Either way, treat it as its
+        // own operation rather than trusting a baseline nobody is standing behind.
+        return scope?.active ? scope.baseline : this.tokenGeneration;
+    }
+    /**
+     * Fetch a new token, unless somebody already did for this operation.
+     *
+     * Single-flighted so two concurrent handlers — including two nested
+     * `fetchCsrfToken` calls, which is a level `renewalInFlight` cannot reach —
+     * share one network call instead of racing and leaving `currentToken` as
+     * whichever settled last.
+     *
+     * @returns true when the caller may retry.
      */
-    async tryRefreshToken() {
+    refreshTokenOnce(baseline) {
+        if (this.tokenGeneration > baseline)
+            return Promise.resolve(true);
+        if (this.tokenRefreshInFlight)
+            return this.tokenRefreshInFlight;
         if (!this.tokenRefresher) {
             this.logger?.debug(`[DEBUG] JwtAbapConnection - No tokenRefresher available, cannot refresh token`);
-            return false;
+            return Promise.resolve(false);
         }
+        // Identity-checked clear, as SessionLifecycle.transition does with its
+        // tail: a joiner settling late must not clear a fetch somebody started
+        // after it.
+        const inFlight = this.performTokenRefresh().finally(() => {
+            if (this.tokenRefreshInFlight === inFlight) {
+                this.tokenRefreshInFlight = undefined;
+            }
+        });
+        this.tokenRefreshInFlight = inFlight;
+        return inFlight;
+    }
+    async performTokenRefresh() {
         try {
             this.logger?.debug(`[DEBUG] JwtAbapConnection - Refreshing token via tokenRefresher...`);
-            const newToken = await this.tokenRefresher.refreshToken();
-            this.currentToken = newToken;
+            // biome-ignore lint/style/noNonNullAssertion: refreshTokenOnce checks it
+            this.currentToken = await this.tokenRefresher.refreshToken();
+            this.tokenGeneration += 1;
             this.logger?.debug(`[DEBUG] JwtAbapConnection - Token refreshed successfully`);
             return true;
         }
@@ -51,6 +171,68 @@ class JwtAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnecti
             return false;
         }
     }
+    /**
+     * Renew the credential and the session it belongs to, once, shared.
+     */
+    renewCredential(baselineEpoch, baseline) {
+        if (this.renewalInFlight)
+            return this.renewalInFlight;
+        // Identity-checked clear, as SessionLifecycle.transition does with its
+        // tail: a joiner settling late must not clear a renewal somebody started
+        // after it.
+        const inFlight = this.performRenewal(baselineEpoch, baseline).finally(() => {
+            if (this.renewalInFlight === inFlight)
+                this.renewalInFlight = undefined;
+        });
+        this.renewalInFlight = inFlight;
+        return inFlight;
+    }
+    async performRenewal(baselineEpoch, baseline) {
+        // Shared with the token-only path, and a no-op when the token is already
+        // newer than the one that failed — then what is missing is the session, and
+        // a second fetch answers a question nobody asked.
+        if (!(await this.refreshTokenOnce(baseline)))
+            return false;
+        this.logger?.debug(`[DEBUG] JwtAbapConnection - Recovering session after token refresh...`);
+        // The renewed credential cannot keep the old ABAP session, so this is a
+        // session-lost teardown — internal, or it would cancel the very recovery it
+        // is setting up. reset() would be the caller-origin one.
+        this.discardSession();
+        // Re-establish before retrying: the retry goes through admission, and a
+        // discarded session admits nothing.
+        await this.recoverSession(baselineEpoch);
+        // Only here: a session now exists that was built with this token.
+        this.recoveredGeneration = this.tokenGeneration;
+        return true;
+    }
+    /**
+     * May this operation retry?
+     *
+     * The order of the checks is the design, not style.
+     */
+    async ensureRecovered(baselineEpoch) {
+        // 1. A renewal in flight is joined REGARDLESS of generation. A newer token
+        //    is no use while the session it belongs to is still being rebuilt:
+        //    retrying now is how a caller meets a closed admission door.
+        //
+        //    This overlaps check 2 as the counters stand — `recoveredGeneration`
+        //    only moves after `recoverSession` resolves, so check 2 cannot report a
+        //    rebuild that has not finished, and removing either guard alone leaves
+        //    the concurrency test green. Both are kept on purpose: this one states
+        //    the rule ("never decide anything while a renewal is running") without
+        //    depending on when some other counter happens to move, and it is what
+        //    keeps the invariant true if check 2's counter is ever changed.
+        if (this.renewalInFlight)
+            return this.renewalInFlight;
+        const baseline = this.currentBaseline();
+        // 2. A full renewal COMPLETED since this operation began — token, and the
+        //    session built with it. Not `tokenGeneration`: that moves on a
+        //    token-only refresh, which rebuilds nothing.
+        if (this.recoveredGeneration > baseline)
+            return true;
+        // 3. Nobody has. Renew, and let everyone else join.
+        return this.renewCredential(baselineEpoch, baseline);
+    }
     /**
      * Establishes the session for this auth type. Called by
      * AbstractAbapConnection.connect(), which owns the lifecycle around it.
@@ -61,7 +243,7 @@ class JwtAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnecti
         this.logger?.debug(`[DEBUG] JwtAbapConnection - Connecting to SAP system: ${discoveryUrl}`);
         try {
             // Try to get CSRF token (this will also get cookies)
-            const token = await this.fetchCsrfToken(discoveryUrl, 3, 1000);
+            const token = await this.fetchCsrfToken(discoveryUrl);
             this.setCsrfToken(token);
             this.logger?.debug('Successfully connected to SAP system', {
                 hasCsrfToken: !!this.getCsrfToken(),
@@ -70,31 +252,9 @@ class JwtAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnecti
             });
         }
         catch (error) {
-            // Handle JWT auth errors (401/403) during connect
-            if (error instanceof axios_1.AxiosError &&
-                (error.response?.status === 401 || error.response?.status === 403)) {
-                // Check if this is really an auth error, not a permissions error
-                const responseData = error.response?.data;
-                const responseText = typeof responseData === 'string'
-                    ? responseData
-                    : JSON.stringify(responseData || '');
-                // Don't retry on "No Access" errors
-                if (responseText.includes('ExceptionResourceNoAccess') ||
-                    responseText.includes('No authorization') ||
-                    responseText.includes('Missing authorization')) {
-                    throw error;
-                }
-                // Try to refresh token if tokenRefresher is available
-                if (await this.tryRefreshToken()) {
-                    // Retry the ESTABLISHMENT, not connect(): connect() runs this as a
-                    // joinable transition, so a nested call joins the transition already
-                    // in flight — this one — and waits for itself forever.
-                    this.logger?.debug(`[DEBUG] JwtAbapConnection - Retrying establishment after token refresh...`);
-                    return this.establishSession();
-                }
-                throw new Error('JWT token has expired. Please re-authenticate.');
+            if (isTokenExpiryCandidate(error)) {
+                this.logger?.error('[ERROR] JwtAbapConnection.establishSession - 401 while establishing; fetchCsrfToken has already refreshed and retried for this');
             }
-            // Re-throw other errors
             throw error;
         }
     }
@@ -102,6 +262,10 @@ class JwtAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnecti
      * Override makeAdtRequest to handle JWT auth errors with automatic token refresh
      */
     async makeAdtRequest(options) {
+        // A public call is its own operation, whatever scope it starts in.
+        return this.inNewRecoveryScope(() => this.attemptRequest(options));
+    }
+    async attemptRequest(options) {
         // Captured before the attempt: a recovery asks "has the caller asked to
         // stop since this request began", not since some later bookkeeping step.
         const baselineEpoch = this.teardownEpoch;
@@ -113,34 +277,32 @@ class JwtAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnecti
         }
         catch (error) {
             this.logger?.debug(`[DEBUG] JwtAbapConnection.makeAdtRequest - Request failed: ${error instanceof Error ? error.message : String(error)}`);
-            // Handle JWT auth errors (401/403)
-            if (error instanceof axios_1.AxiosError &&
-                (error.response?.status === 401 || error.response?.status === 403)) {
-                this.logger?.debug(`[DEBUG] JwtAbapConnection.makeAdtRequest - Got ${error.response.status}, attempting token refresh...`);
-                // Check if this is really an auth error, not a permissions error
-                const responseData = error.response?.data;
-                const responseText = typeof responseData === 'string'
-                    ? responseData
-                    : JSON.stringify(responseData || '');
-                // Don't retry on "No Access" errors - these are permission issues, not auth issues
-                if (responseText.includes('ExceptionResourceNoAccess') ||
-                    responseText.includes('No authorization') ||
-                    responseText.includes('Missing authorization')) {
-                    throw error;
-                }
-                // Try to refresh token if tokenRefresher is available
-                if (await this.tryRefreshToken()) {
-                    this.logger?.debug(`[DEBUG] JwtAbapConnection.makeAdtRequest - Recovering session after token refresh...`);
-                    // The renewed credential cannot keep the old ABAP session, so this is
-                    // a session-lost teardown — internal, or it would cancel the very
-                    // recovery it is setting up. reset() would be the caller-origin one.
-                    this.discardSession();
-                    // Re-establish before retrying: the retry goes through admission, and
-                    // a discarded session admits nothing.
-                    await this.recoverSession(baselineEpoch);
-                    return super.makeAdtRequest(options);
+            if (isTokenExpiryCandidate(error)) {
+                this.logger?.debug(`[DEBUG] JwtAbapConnection.makeAdtRequest - Got 401, attempting token refresh...`);
+                if (await this.ensureRecovered(baselineEpoch)) {
+                    // A renewal this operation joined was fenced against the STARTER's
+                    // baseline, not this one's, and establishAndCommit's own epoch checks
+                    // belong to the establishment that ran. Between the last of them and
+                    // this retry there is a gap nothing else watches: the connection can
+                    // be torn down by its caller and made usable again, and a retry would
+                    // then go out on a session that caller discarded.
+                    if (this.teardownEpoch !== baselineEpoch) {
+                        throw (0, SessionLifecycle_js_1.sessionError)(interfaces_1.ADT_SESSION_ERROR.NOT_CONNECTED, 'Retry abandoned: a teardown was requested for this connection');
+                    }
+                    try {
+                        return await super.makeAdtRequest(options);
+                    }
+                    catch (retryError) {
+                        // A 401 that survived a renewal is the case the deleted message
+                        // was about, and it only shows up here — the log below fires when
+                        // the renewal never happened, which is a different fact.
+                        if (isTokenExpiryCandidate(retryError)) {
+                            this.logger?.error('[ERROR] JwtAbapConnection.makeAdtRequest - 401 persists after a credential renewal; the credential may need re-authentication');
+                        }
+                        throw retryError;
+                    }
                 }
-                throw new Error('JWT token has expired. Please re-authenticate.');
+                this.logger?.error('[ERROR] JwtAbapConnection.makeAdtRequest - 401 persists and the token could not be refreshed; the credential may need re-authentication');
             }
             throw error;
         }
@@ -148,33 +310,37 @@ class JwtAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnecti
     /**
      * Override fetchCsrfToken to handle JWT auth errors with automatic token refresh
      */
-    async fetchCsrfToken(url, retryCount = 3, retryDelay = 1000) {
+    async fetchCsrfToken(url, retryCount = csrfConfig_js_1.CSRF_CONFIG.RETRY_COUNT, retryDelay = csrfConfig_js_1.CSRF_CONFIG.RETRY_DELAY, 
+    /** Fences the response effects; omitted during connect(), which has no lease. */
+    generation) {
+        // An inner level: join the operation in progress, or start one when
+        // reached directly — a bare connect() is still an operation with a
+        // baseline.
+        return this.inRecoveryScope(() => this.attemptCsrfToken(url, retryCount, retryDelay, generation));
+    }
+    async attemptCsrfToken(url, retryCount, retryDelay, generation) {
         try {
             // Try to fetch CSRF token using parent implementation
-            return await super.fetchCsrfToken(url, retryCount, retryDelay);
+            return await super.fetchCsrfToken(url, retryCount, retryDelay, generation);
         }
         catch (error) {
-            // Handle JWT auth errors (401/403) during CSRF token fetch
-            if (error instanceof axios_1.AxiosError &&
-                (error.response?.status === 401 || error.response?.status === 403)) {
-                // Check if this is really an auth error, not a permissions error
-                const responseData = error.response?.data;
-                const responseText = typeof responseData === 'string'
-                    ? responseData
-                    : JSON.stringify(responseData || '');
-                // Don't retry on "No Access" errors
-                if (responseText.includes('ExceptionResourceNoAccess') ||
-                    responseText.includes('No authorization') ||
-                    responseText.includes('Missing authorization')) {
-                    throw error;
-                }
-                // Try to refresh token if tokenRefresher is available
-                if (await this.tryRefreshToken()) {
+            // A 401 here may be an expired token; anything else is not ours to
+            // interpret — a 403 least of all, since a new token is the same caller.
+            if (isTokenExpiryCandidate(error)) {
+                if (await this.refreshTokenOnce(this.currentBaseline())) {
                     // Retry CSRF token fetch with new token
                     this.logger?.debug(`[DEBUG] JwtAbapConnection.fetchCsrfToken - Retrying after token refresh...`);
-                    return super.fetchCsrfToken(url, retryCount, retryDelay);
+                    try {
+                        return await super.fetchCsrfToken(url, retryCount, retryDelay, generation);
+                    }
+                    catch (retryError) {
+                        if (isTokenExpiryCandidate(retryError)) {
+                            this.logger?.error('[ERROR] JwtAbapConnection.fetchCsrfToken - 401 persists after a token refresh; the credential may need re-authentication');
+                        }
+                        throw retryError;
+                    }
                 }
-                throw new Error('JWT token has expired. Please re-authenticate.');
+                this.logger?.error('[ERROR] JwtAbapConnection.fetchCsrfToken - 401 persists and the token could not be refreshed; the credential may need re-authentication');
             }
             // Re-throw other errors
             throw error;

package/dist/connection/SamlAbapConnection.js

@@ -29,7 +29,7 @@ class SamlAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnect
         const discoveryUrl = `${baseUrl}/sap/bc/adt/discovery`;
         this.logger?.debug(`[DEBUG] SamlAbapConnection - Connecting to SAP system: ${discoveryUrl}`);
         try {
-            const token = await this.fetchCsrfToken(discoveryUrl, 3, 1000);
+            const token = await this.fetchCsrfToken(discoveryUrl);
             this.setCsrfToken(token);
             this.logger?.debug('Successfully connected to SAP system', {
                 hasCsrfToken: !!this.getCsrfToken(),

package/docs/INDEX.md

@@ -15,6 +15,7 @@ mcp-abap-connection/
 │   ├── INSTALLATION.md             # Setup and installation guide
 │   ├── USAGE.md                    # API documentation and examples
 │   ├── MIGRATION-2.0.md            # Moving to the explicit session lifecycle
+│   ├── MIGRATION-4.0.md            # JWT error classification: 401 refreshes, 403 propagates
 │   ├── SCOPE.md                    # What this package does and does not own
 │   ├── STATEFUL_SESSION_GUIDE.md   # Stateful requests and lock windows
 │   └── JWT_AUTH_TOOLS.md           # CLI tool for authentication
@@ -41,6 +42,10 @@ mcp-abap-connection/
 ### Core Features
 - 🔑 [JWT Auth Tools](./JWT_AUTH_TOOLS.md) - CLI tool for browser-based authentication
 
+### Upgrading
+- 🧱 [Migrating to 4.0.0](./MIGRATION-4.0.md) - JWT error classification: a 401 refreshes, a 403 propagates with the server's message
+- 🧱 [Migrating to 2.0.0](./MIGRATION-2.0.md) - The explicit session lifecycle: `connect()` is required
+
 ### Version Information
 - 📋 [CHANGELOG](../CHANGELOG.md) - Complete version history, including what the latest release changed
 

package/docs/MIGRATION-4.0.md

@@ -0,0 +1,95 @@
+# Migrating to 4.0.0: the server's error reaches you
+
+A JWT connection used to answer some failures with an error of its own making:
+
+```
+Error: JWT token has expired. Please re-authenticate.
+```
+
+It said that for a **401** and for a **403** alike, and it threw the original `AxiosError` away
+along with the status and the body. Now the server's error reaches the caller unchanged, and only
+a 401 is treated as a credential problem.
+
+## What breaks, and what to do
+
+### 1. That message is gone
+
+If anything matches on it, it will stop matching.
+
+```typescript
+// before
+catch (error) {
+  if (error.message.includes('JWT token has expired')) {
+    await reauthenticate();
+  }
+}
+
+// after
+catch (error) {
+  if (error.response?.status === 401) {
+    await reauthenticate();
+  }
+}
+```
+
+`error.response.status` and `error.response.data` are available now — they were not before,
+because the replacement error carried neither.
+
+**Why it changed.** The message was wrong about half the cases it was used for. A 403 is not an
+expired token, and telling a caller to re-authenticate for one sends them to fix the single thing
+that is not broken.
+
+### 2. A 403 no longer triggers a token refresh
+
+It propagates as it arrived. If your code relied on a refresh happening after a 403 — for
+instance to recover from an authorization gap that a *different* principal would not have — that
+no longer happens, and it never worked for the reason you may have assumed: a refreshed token
+belongs to the same caller and cannot change a permissions answer.
+
+What a 403 usually carries is worth reading:
+
+```xml
+<exc:exception>
+  <type id="ExceptionResourceNoAuthorization"/>
+  <message lang="EN">You are not authorized to make changes (authorization object S_DEVELOP)</message>
+</exc:exception>
+```
+
+The authorization object is named. That is actionable; "please re-authenticate" was not.
+
+### 3. A 401 still refreshes, and now says so when it does not help
+
+The happy path is unchanged: a 401 with an injected `ITokenRefresher` fetches a new token,
+re-establishes the session and retries. What changed is the unhappy one — when the retry comes
+back 401 as well, the original error is rethrown and an `ERROR`-level log line explains that the
+credential may genuinely need re-authentication.
+
+## What did not change
+
+- `ITokenRefresher` and how it is injected;
+- that a credential renewal replaces the SAP session — with a lock window open, a request still
+  fails with `ADT_SESSION_REPLACED` rather than continuing on a session your lock is not in (see
+  [STATEFUL_SESSION_GUIDE.md](./STATEFUL_SESSION_GUIDE.md));
+- every other authentication type. `BaseAbapConnection`, `SamlAbapConnection`,
+  `CertificateAbapConnection` and `KerberosAbapConnection` never refreshed tokens and never
+  synthesised an error in place of the server's.
+
+## Under the hood, if you are debugging
+
+Concurrent requests that hit the same expired token now share **one** renewal — one token fetch
+and one session re-establishment between them — rather than each running its own teardown and
+recovery in sequence. If you have log-line counts or timing expectations built around the old
+behaviour, they will change; the observable contract does not.
+
+## Where this came from
+
+Issue [#30](https://github.com/fr0ster/mcp-abap-connection/issues/30), found while probing ATC on
+a cloud trial: creating a classic program was reported as an expired token on three consecutive
+runs, while the same session was answering other requests with 200. It took bypassing the
+connector on the same credential to see the 403 and the `S_DEVELOP` message underneath.
+
+One question is deliberately left open and tracked in
+[#32](https://github.com/fr0ster/mcp-abap-connection/issues/32): whether some BTP setup answers an
+*invalid* token with 403 rather than 401. Nothing captured shows that it does, and preserving the
+original error is what makes the assumption safe to be wrong about — a caller would then see the
+server's own 403 instead of a misleading message.

package/docs/STATEFUL_SESSION_GUIDE.md

@@ -82,6 +82,12 @@ Every ADT request issued through `makeAdtRequest` automatically:
 
 This logic is transparent to callers (Builders, handlers, CLI scripts).
 
+On a JWT connection one case is **not** transparent, and cannot be: a 401 that leads to a token
+refresh also replaces the SAP session, because the renewed credential cannot keep the old one.
+Inside a lock window that surfaces as `ADT_SESSION_REPLACED` rather than a request quietly
+continuing on a session your lock is not in. A 403 never does this — it is an authorization
+answer, not a credential one, and nothing is torn down for it.
+
 ---
 
 ## Interaction With ADT Clients

package/docs/USAGE.md

@@ -676,12 +676,33 @@ For SAP BTP cloud systems. Token refresh is handled by `@mcp-abap-adt/auth-broke
 
 ```typescript
 class JwtAbapConnection extends AbstractAbapConnection {
-  constructor(config: SapConfig, logger?: ILogger | null);
+  constructor(
+    config: SapConfig,
+    logger?: ILogger | null,
+    sessionId?: string,
+    tokenRefresher?: ITokenRefresher,
+  );
   // Note: refreshToken() and canRefreshToken() methods removed in 0.2.0
-  // Use @mcp-abap-adt/auth-broker for token refresh functionality
+  // Token acquisition itself belongs to @mcp-abap-adt/auth-broker
 }
 ```
 
+**How failures are classified** (4.0.0 — see
+[MIGRATION-4.0.md](./MIGRATION-4.0.md)):
+
+| answer | what happens |
+|---|---|
+| **401** | with an injected `ITokenRefresher`, the token is refreshed, the SAP session re-established, and the request retried once. Without one, or when the retry is refused too, the server's error is rethrown |
+| **403** | propagates untouched. The server authenticated the caller and refused the action anyway, so a new token is the same caller — usually the body names the authorization object |
+| anything else | untouched |
+
+The connection never replaces the server's error with one of its own: `error.response.status` and
+`error.response.data` are always what SAP sent. Before 4.0.0 both 401 and 403 were reported as
+`JWT token has expired. Please re-authenticate.` with the original error discarded.
+
+Concurrent requests that meet the same expired token share **one** renewal — a single token fetch
+and a single session re-establishment between them, not one each.
+
 ### `createAbapConnection()` Factory
 
 Recommended way to create connections:

package/examples/README.md

@@ -43,8 +43,9 @@ node examples/jwt-with-token-refresh.js
 
 **What it demonstrates:**
 - Creating connection with token refresher injection
-- Automatic token refresh on 401/403 errors
+- Automatic token refresh on 401 errors
 - Retry logic with refreshed token
+- A 403 propagating untouched, with its status and body intact
 
 ### saml-connection.js
 

package/examples/jwt-with-token-refresh.js

@@ -4,10 +4,16 @@
  * This example demonstrates how to create a JwtAbapConnection with
  * automatic token refresh using ITokenRefresher from auth-broker.
  *
- * When 401/403 errors occur, the connection automatically:
+ * When a **401** occurs, the connection automatically:
  * 1. Calls tokenRefresher.refreshToken() to get a new token
  * 2. Updates internal token state
- * 3. Retries the failed request with the new token
+ * 3. Re-establishes the SAP session, which the new credential cannot inherit
+ * 4. Retries the failed request
+ *
+ * A **403** is left alone. It means the server authenticated you and refused
+ * the action anyway — an authorization gap, not an expired credential — so it
+ * propagates with its status and the server's message, and a new token would
+ * change nothing.
  */
 
 const { JwtAbapConnection } = require('@mcp-abap-adt/connection');
@@ -68,7 +74,9 @@ async function main() {
   try {
     await connection.connect();
 
-    // This request will automatically refresh token if 401/403 occurs. Note
+    // This request will automatically refresh the token if a 401 occurs. A
+    // 403 arrives as-is — read err.response.status and err.response.data to
+    // see which authorization object the server named. Note
     // that a refresh replaces the SAP session: with a lock window open the
     // request would fail with ADT_SESSION_REPLACED rather than continue on a
     // session your lock is not in.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/connection",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "ABAP connection layer for MCP ABAP ADT server",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",