@mcp-abap-adt/connection 3.0.0 → 5.0.0

package/dist/connection/JwtAbapConnection.d.ts

@@ -1,38 +1,131 @@
-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 { SessionStrategy } from '../session/SessionStrategy.js';
 import type { AbapRequestOptions } from './AbapConnection.js';
 import { AbstractAbapConnection } from './AbstractAbapConnection.js';
 /**
- * JWT Authentication connection for SAP BTP Cloud systems
+ * The class you take should say which SYSTEM you are dialling, not which
+ * credential you hold — a session mechanism that rides along with the
+ * credential gets one of them wrong. `AdtCloudConnector` and
+ * `AdtOnPremConnector` are how that is said.
  *
- * 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)
+ * **This class is NOT deprecated yet, and must not be replaced by
+ * `AdtCloudConnector` + `TokenAuthProvider`.** What it does beyond
+ * authenticating has not moved: a 401 caught mid-operation, one refresh shared
+ * by every operation in flight, the session rebuilt behind it, generation
+ * fencing so a dead session's response cannot land, and the request retried
+ * once. A `TokenAuthProvider` fetches a token at establishment and nothing
+ * after it, so swapping today trades all of that for a connection that dies on
+ * the first expiry.
+ *
+ * Use this class for JWT until that machinery moves; the split is the
+ * platform-connectors spec's next step.
  */
 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 tryRefreshToken;
+    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 ensureRecovered;
     /**
      * Establishes the session for this auth type. Called by
      * AbstractAbapConnection.connect(), which owns the lifecycle around it.
      */
+    /**
+     * Cloud manages sessions through ADT: a session resource is opened at
+     * `/sap/bc/adt/core/http/sessions` and given back by `DELETE` on the address
+     * the server publishes. This is the one connection that does it — on-prem
+     * keeps the platform's ICF logoff, which is what it has always used.
+     */
+    protected createSessionStrategy(): SessionStrategy;
     protected establishSession(): Promise<void>;
     /**
      * 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;AAG5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAuBrE;;;;;;;;;;;;;;;;;GAiBG;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;IACH;;;;;OAKG;cACgB,qBAAqB,IAAI,eAAe;cAI3C,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,75 @@
 "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 CloudSecuritySessionStrategy_js_1 = require("../session/CloudSecuritySessionStrategy.js");
+const SessionLifecycle_js_1 = require("../session/SessionLifecycle.js");
 const AbstractAbapConnection_js_1 = require("./AbstractAbapConnection.js");
+const csrfConfig_js_1 = require("./csrfConfig.js");
 /**
- * JWT Authentication connection for SAP BTP Cloud systems
+ * Is this worth refreshing a token for?
  *
- * 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)
+ * 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;
+}
+/**
+ * The class you take should say which SYSTEM you are dialling, not which
+ * credential you hold — a session mechanism that rides along with the
+ * credential gets one of them wrong. `AdtCloudConnector` and
+ * `AdtOnPremConnector` are how that is said.
+ *
+ * **This class is NOT deprecated yet, and must not be replaced by
+ * `AdtCloudConnector` + `TokenAuthProvider`.** What it does beyond
+ * authenticating has not moved: a 401 caught mid-operation, one refresh shared
+ * by every operation in flight, the session rebuilt behind it, generation
+ * fencing so a dead session's response cannot land, and the request retried
+ * once. A `TokenAuthProvider` fetches a token at establishment and nothing
+ * after it, so swapping today trades all of that for a connection that dies on
+ * the first expiry.
+ *
+ * Use this class for JWT until that machinery moves; the split is the
+ * platform-connectors spec's next step.
  */
 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 +88,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.
      */
-    async tryRefreshToken() {
+    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.
+     */
+    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,17 +180,88 @@ 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. disconnect() 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.
      */
+    /**
+     * Cloud manages sessions through ADT: a session resource is opened at
+     * `/sap/bc/adt/core/http/sessions` and given back by `DELETE` on the address
+     * the server publishes. This is the one connection that does it — on-prem
+     * keeps the platform's ICF logoff, which is what it has always used.
+     */
+    createSessionStrategy() {
+        return new CloudSecuritySessionStrategy_js_1.CloudSecuritySessionStrategy(this.logger);
+    }
     async establishSession() {
         const baseUrl = await this.getBaseUrl();
         const discoveryUrl = `${baseUrl}/sap/bc/adt/discovery`;
         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 +270,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 +280,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 +295,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 +328,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/KerberosAbapConnection.d.ts

@@ -1,7 +1,15 @@
 import type { SapConfig } from '../config/sapConfig.js';
 import type { ILogger } from '../logger.js';
 import { AbstractAbapConnection } from './AbstractAbapConnection.js';
-/** Kerberos / SPNEGO single-leg auth: send Negotiate token, reuse the resulting SAP session cookie. */
+/**
+ * @deprecated The class you take should say which SYSTEM you are dialling,
+ * not which credential you hold — a session mechanism that rides along with
+ * the credential gets one of them wrong. Use `AdtOnPremConnector` with `a Kerberos credential`:
+ *
+ *   not yet available — SPNEGO keeps its own class until its exchange is moved
+ *
+ * Kept working, and not removed here: existing consumers are unaffected.
+ */
 export declare class KerberosAbapConnection extends AbstractAbapConnection {
     private spn;
     private currentToken;

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

@@ -1 +1 @@
-{"version":3,"file":"KerberosAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/KerberosAbapConnection.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAErE,uGAAuG;AACvG,qBAAa,sBAAuB,SAAQ,sBAAsB;IAChE,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,YAAY,CAAM;gBAEd,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,EAAE,SAAS,CAAC,EAAE,MAAM;IAQ1E,OAAO,CAAC,MAAM,CAAC,cAAc;IAa7B,mDAAmD;cACnC,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5C;;;;OAIG;IACH;;;OAGG;cACa,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAqFjD,SAAS,CAAC,wBAAwB,IAAI,MAAM;CAS7C"}
+{"version":3,"file":"KerberosAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/KerberosAbapConnection.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAErE;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,SAAQ,sBAAsB;IAChE,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,YAAY,CAAM;gBAEd,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,EAAE,SAAS,CAAC,EAAE,MAAM;IAQ1E,OAAO,CAAC,MAAM,CAAC,cAAc;IAa7B,mDAAmD;cACnC,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5C;;;;OAIG;IACH;;;OAGG;cACa,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAqFjD,SAAS,CAAC,wBAAwB,IAAI,MAAM;CAS7C"}

package/dist/connection/KerberosAbapConnection.js

@@ -5,7 +5,15 @@ const axios_1 = require("axios");
 const kerberosSpnego_js_1 = require("../auth/kerberosSpnego.js");
 const ntlm_js_1 = require("../auth/ntlm.js");
 const AbstractAbapConnection_js_1 = require("./AbstractAbapConnection.js");
-/** Kerberos / SPNEGO single-leg auth: send Negotiate token, reuse the resulting SAP session cookie. */
+/**
+ * @deprecated The class you take should say which SYSTEM you are dialling,
+ * not which credential you hold — a session mechanism that rides along with
+ * the credential gets one of them wrong. Use `AdtOnPremConnector` with `a Kerberos credential`:
+ *
+ *   not yet available — SPNEGO keeps its own class until its exchange is moved
+ *
+ * Kept working, and not removed here: existing consumers are unaffected.
+ */
 class KerberosAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnection {
     spn;
     currentToken = '';

package/dist/connection/RfcAbapConnection.d.ts

@@ -35,11 +35,6 @@ export declare class RfcAbapConnection implements AbapConnection {
     getSessionId(): string | null;
     setSessionType(type: 'stateful' | 'stateless'): void;
     makeAdtRequest<T = any, D = any>(options: IAbapRequestOptions): Promise<IAdtResponse<T, D>>;
-    /**
-     * Reset the connection — for RFC this closes the session.
-     * Provides interface compatibility with HTTP connections.
-     */
-    reset(): void;
     /**
      * Close the RFC connection and release the ABAP session.
      */

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

@@ -1 +1 @@
-{"version":3,"file":"RfcAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/RfcAbapConnection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,mBAAmB,EACnB,YAAY,EACb,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAkG1D;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,iBAAkB,YAAW,cAAc;IASpD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IATzB,OAAO,CAAC,SAAS,CAA2B;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,WAAW,CAAyC;IAC5D,OAAO,CAAC,aAAa,CAAuB;gBAGzB,MAAM,EAAE,SAAS,EACjB,MAAM,GAAE,OAAO,GAAG,IAAW;IAa1C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA8BxB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAInC,YAAY,IAAI,MAAM,GAAG,IAAI;IAI7B,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI;IAU9C,cAAc,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG,EACnC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IA8L9B;;;OAGG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5B,OAAO,CAAC,MAAM,CAAC,cAAc;CAqB9B"}
+{"version":3,"file":"RfcAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/RfcAbapConnection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,mBAAmB,EACnB,YAAY,EACb,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAkG1D;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,iBAAkB,YAAW,cAAc;IASpD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IATzB,OAAO,CAAC,SAAS,CAA2B;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,WAAW,CAAyC;IAC5D,OAAO,CAAC,aAAa,CAAuB;gBAGzB,MAAM,EAAE,SAAS,EACjB,MAAM,GAAE,OAAO,GAAG,IAAW;IAa1C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA8BxB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAInC,YAAY,IAAI,MAAM,GAAG,IAAI;IAI7B,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI;IAU9C,cAAc,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG,EACnC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IA8L9B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5B,OAAO,CAAC,MAAM,CAAC,cAAc;CAqB9B"}