@mcp-abap-adt/connection 1.10.2 → 3.0.0

package/dist/connection/AbstractAbapConnection.js

@@ -38,11 +38,24 @@ const node_crypto_1 = require("node:crypto");
 const node_https_1 = require("node:https");
 const interfaces_1 = require("@mcp-abap-adt/interfaces");
 const axios_1 = __importStar(require("axios"));
+const SessionLifecycle_js_1 = require("../session/SessionLifecycle.js");
 const timeouts_js_1 = require("../utils/timeouts.js");
 const csrfConfig_js_1 = require("./csrfConfig.js");
+/**
+ * Declares the capabilities explicitly rather than satisfying them by accident.
+ * `AbapConnection` is the base contract every transport honours; these two are
+ * the HTTP session's own, and naming them means a signature that drifts from
+ * the published contract fails to compile here instead of at the consumer.
+ */
 class AbstractAbapConnection {
     config;
     logger;
+    /**
+     * Owns session state, admission and teardown ordering. Composed rather than
+     * inherited: RfcAbapConnection implements the interface directly, so the two
+     * transports share this unit instead of a base class.
+     */
+    lifecycle = new SessionLifecycle_js_1.SessionLifecycle();
     axiosInstance = null;
     csrfToken = null;
     cookies = null;
@@ -161,7 +174,278 @@ class AbstractAbapConnection {
     getConfig() {
         return this.config;
     }
+    /**
+     * Establishes the session, once, under the lifecycle.
+     *
+     * Idempotent, and concurrent callers share one establishment: the transition
+     * joins the tail of its own kind. A teardown requested while establishment
+     * was in flight means the caller asked to stop, so usability is NOT published
+     * and what was established is released — otherwise a slow connect would hand
+     * back a session someone had already discarded.
+     */
+    async connect() {
+        // Captured HERE, not inside the transition: the callback runs when this
+        // reaches the front of the queue, by which time a teardown the caller
+        // requested afterwards has already bumped the epoch — and comparing it
+        // against itself would let the connect publish a session the caller had
+        // asked to stop. The baseline is "when the caller asked to connect".
+        const baselineEpoch = this.lifecycle.teardownEpoch;
+        await this.lifecycle.transition('connect', async () => {
+            if (this.lifecycle.connected)
+                return;
+            await this.establishAndCommit(baselineEpoch);
+        });
+    }
+    /**
+     * Tears the session down. Never throws, and always settles.
+     *
+     * It waits for NOTHING. Deciding when to disconnect is the caller's, and so is
+     * preparing for it — finishing chains, releasing locks. Waiting here on a
+     * request whose caller chose no timeout is what made a teardown unbounded, and
+     * an unbounded teardown blocks every later transition on the serialized tail.
+     *
+     * Requests already in flight run to completion untouched. Generation fencing
+     * (see `SessionLifecycle.isCurrent`) keeps their results from reaching this
+     * connection afterwards.
+     *
+     * Sends no ADT session-close — see the design's D2.
+     */
+    async disconnect() {
+        // Synchronous, at the call: admission shuts and the generation moves before
+        // anything is queued, so a caller who has asked to disconnect cannot have
+        // requests still going through while this waits its turn.
+        this.lifecycle.beginTeardown({ origin: 'caller', sessionLost: false });
+        await this.lifecycle.transition('disconnect', async () => {
+            this.clearSessionState();
+            this.lifecycle.markDisconnected();
+        });
+    }
+    isConnected() {
+        return this.lifecycle.connected;
+    }
+    /**
+     * Fingerprint of the SAP-side session, or null when none is known.
+     *
+     * `null` is NOT a statement about the connection. Two situations produce it:
+     * no session exists, or the connection is live over a server that issued no
+     * session cookie. Use {@link isConnected} for connection state.
+     *
+     * It follows that null → non-null is not a replacement but an identity being
+     * learned; only a CHANGED value means the session was replaced.
+     */
+    getSessionIdentity() {
+        return this.lifecycle.identity;
+    }
+    /**
+     * Discards the session at a caller's request: cancels queued recoveries and
+     * queues the cleanup rather than tearing down under a live request.
+     */
     reset() {
+        this.lifecycle.beginTeardown({ origin: 'caller', sessionLost: true });
+        void this.lifecycle.transition('cleanup', async () => {
+            this.clearSessionState();
+            this.lifecycle.markDisconnected();
+        });
+    }
+    /**
+     * Re-establishes the session for a request that is recovering from a
+     * credential renewal, then lets that request retry.
+     *
+     * Runs as its own `recover` transition, which never joins another: each
+     * recovery carries the baseline of its own request. It yields to a caller's
+     * teardown — if the epoch moved since `baselineEpoch`, someone asked to stop
+     * while this was being prepared, and a retry must not resurrect a session
+     * they discarded.
+     *
+     * The transition queues behind the cleanup that the renewal itself raised, so
+     * it never re-establishes on top of stale transport state.
+     */
+    async recoverSession(baselineEpoch) {
+        await this.lifecycle.transition('recover', async () => {
+            await this.establishAndCommit(baselineEpoch);
+        });
+    }
+    /**
+     * Establishes a session and publishes it — but only if nobody asked to stop
+     * meanwhile.
+     *
+     * The epoch is checked BEFORE, so a teardown already requested costs no round
+     * trip, and AFTER, because establishment takes time and a caller can ask to
+     * stop during it. Checking only before is the defect this exists to prevent:
+     * markConnected() would then clear the teardown state and hand back a session
+     * the caller had already discarded.
+     *
+     * Shared by connect() and recoverSession() rather than written twice —
+     * the two drifted apart once already, and a third caller would drift again.
+     */
+    async establishAndCommit(baselineEpoch) {
+        if (this.lifecycle.teardownEpoch !== baselineEpoch) {
+            throw (0, SessionLifecycle_js_1.sessionError)(interfaces_1.ADT_SESSION_ERROR.NOT_CONNECTED, 'Establishment abandoned: a teardown was requested for this connection');
+        }
+        // Whatever session arrives from here is one we are deliberately
+        // establishing, so it must not read as a replacement: the identity policy
+        // treats a changed fingerprint as fatal, and it cannot tell our own
+        // re-establishment from a session taken out from under us. Forgetting first
+        // makes the new fingerprint `established`, which is what it is.
+        this.lifecycle.forgetIdentity();
+        try {
+            await this.establishSession();
+        }
+        catch (error) {
+            // A failed establishment leaves debris that poisons the next attempt: the
+            // 401 that rejected us may still have carried a Set-Cookie, and every
+            // subclass treats a cookie as proof that auth is already settled —
+            // buildAuthorizationHeader() returns '' once one exists. So the next
+            // connect() would go out with NO credentials at all, and be rejected for
+            // a reason that has nothing to do with why the first one failed.
+            //
+            // Safe to clear here, unlike the abandonment path below: establishSession()
+            // threw, so no session was published, and admission requires a connected
+            // lifecycle — nothing can be in flight over what this drops.
+            this.invalidateSession();
+            // And the identity with it. The rejecting response was still observed, so
+            // its cookie was recorded as a session that had just been established —
+            // leaving getSessionIdentity() naming a session that never existed while
+            // isConnected() says false. Two answers to one question is worse than
+            // either.
+            this.lifecycle.markDisconnected();
+            throw error;
+        }
+        if (this.lifecycle.teardownEpoch !== baselineEpoch) {
+            // Abandon WITHOUT clearing: the teardown that bumped the epoch is already
+            // queued, and it clears after draining. Clearing here would pull cookies,
+            // the CSRF token and the axios instance out from under a request that is
+            // still in flight — breaking the guarantee this whole change rests on,
+            // from inside the guard meant to protect it.
+            throw (0, SessionLifecycle_js_1.sessionError)(interfaces_1.ADT_SESSION_ERROR.NOT_CONNECTED, 'Establishment abandoned: a teardown was requested while it was in flight');
+        }
+        // establishSession() throws on failure, so reaching here means a session
+        // exists. There is no third outcome: no "connected but unusable", no
+        // resolved promise over an empty jar.
+        this.lifecycle.markConnected(this.sessionFingerprint());
+    }
+    /** The teardown epoch, for a recovery to capture before it starts. */
+    get teardownEpoch() {
+        return this.lifecycle.teardownEpoch;
+    }
+    /**
+     * Raises a session-lost teardown from inside request handling.
+     *
+     * There are exactly three things that can cost us the ABAP session, and they
+     * were found one at a time precisely because they were written apart. They go
+     * through here so a fourth joins the list instead of inventing its own
+     * sequence:
+     *
+     *   - the credential was renewed (the injected auth says so);
+     *   - the server says the session is gone (a dead-session response);
+     *   - the tracked cookie changed under us while a lock was held.
+     *
+     * `internal` origin, so it does not cancel the recovery that raised it, and
+     * `sessionLost`, so admission shuts at once and the identity is dropped
+     * immediately — a later comparison must see the change, and on a dead session
+     * the cookie is unchanged, so only the state can tell.
+     *
+     * Does not await: it is called from inside a request, and the cleanup must not
+     * wait for the very request that raised it.
+     */
+    raiseSessionLost(reason) {
+        this.logger?.warn(`Session lost: ${reason}`);
+        this.lifecycle.beginTeardown({ origin: 'internal', sessionLost: true });
+        void this.lifecycle.transition('cleanup', async () => {
+            this.clearSessionState();
+            this.lifecycle.markDisconnected();
+        });
+    }
+    /** The credential-renewal raiser; see raiseSessionLost(). */
+    discardSession() {
+        this.raiseSessionLost('the credential backing it was renewed');
+    }
+    /**
+     * Whether an error is this connection's own verdict about the session rather
+     * than something the server said about a request.
+     *
+     * A retry path that swallows one of these and rethrows the original error
+     * turns "your lock is dead" back into "your request 403'd", which is the very
+     * information the caller needs and the only one it cannot recover itself.
+     */
+    isSessionVerdict(error) {
+        const code = error?.code;
+        return (code === interfaces_1.ADT_SESSION_ERROR.SESSION_REPLACED ||
+            code === interfaces_1.ADT_SESSION_ERROR.NOT_CONNECTED ||
+            code === interfaces_1.ADT_SESSION_ERROR.RELEASE_PENDING);
+    }
+    /**
+     * Folds a response into the session state AND acts on what it means, in one
+     * step.
+     *
+     * Never call updateCookiesFromResponse() directly: it MUTATES the fingerprint,
+     * so discarding its classification absorbs a replacement silently and every
+     * later check reads `unchanged`. That is one call site forgetting, and it
+     * happened — on the error path and on every retry response.
+     */
+    observeResponse(headers, generation) {
+        // Fenced by SESSION GENERATION, not by the teardown epoch. Only a
+        // caller-initiated teardown moves the epoch — a recovery deliberately does
+        // not — so after a session loss and a successful recovery, a request from
+        // the dead session carries the same epoch as the new one and would sail
+        // straight through. The generation moves whenever the current session does.
+        //
+        // `undefined` means "not issued against a session": the CSRF fetch during
+        // connect() has no lease and must apply, since it is establishing the very
+        // session this would compare against.
+        if (generation !== undefined &&
+            generation !== this.lifecycle.sessionGeneration) {
+            this.logger?.debug('Ignoring a response from a previous session: its effects are fenced');
+            return;
+        }
+        this.applyIdentityPolicy(this.updateCookiesFromResponse(headers));
+    }
+    /**
+     * Acts on what a response said about the session identity.
+     *
+     * A replacement is always fatal, and that is a narrowing: an earlier version
+     * tolerated it "when no lock is held", deciding from the connection's own
+     * lock windows. Those are gone, and rightly — this layer does not know that a
+     * lock exists, what object it covers or what would release it. Locks are
+     * tracked a layer up, per object, by the code that took them.
+     *
+     * So the rule is written from what this layer CAN know: the ABAP session we
+     * were speaking to is not the one we are speaking to now. Anything the caller
+     * held against the old one is dead, and continuing quietly would hand them a
+     * session they never opened — the failure this whole design exists to prevent.
+     * Being wrong in this direction costs a reconnect; being wrong the other way
+     * costs a lock nobody can find.
+     */
+    applyIdentityPolicy(classification) {
+        if (classification !== 'replaced')
+            return;
+        this.raiseSessionLost('the session cookie changed under us');
+        throw (0, SessionLifecycle_js_1.sessionError)(interfaces_1.ADT_SESSION_ERROR.SESSION_REPLACED, 'The SAP session was replaced; anything held against the previous one is dead');
+    }
+    /**
+     * Whether the server is telling us the session it was given no longer exists.
+     *
+     * The E19 shape was HTTP 400 with "Session not found", answered in ~60 ms
+     * with the cookie present — which is why identity comparison cannot see this:
+     * the cookie, and therefore the fingerprint, is completely unchanged. The
+     * exact match is landscape-specific and is one of the live probes this design
+     * still owes.
+     */
+    isDeadSessionResponse(error) {
+        if (!(error instanceof axios_1.AxiosError) || !error.response)
+            return false;
+        if (error.response.status !== 400)
+            return false;
+        const text = [
+            error.response.statusText,
+            typeof error.response.data === 'string' ? error.response.data : '',
+        ]
+            .join(' ')
+            .toLowerCase();
+        return text.includes('session not found');
+    }
+    /** Drops everything that described the session. Not a lifecycle transition. */
+    clearSessionState() {
         if (this.axiosInstance) {
             this.axiosInstance.interceptors.request.clear();
             this.axiosInstance.interceptors.response.clear();
@@ -172,6 +456,23 @@ class AbstractAbapConnection {
         this.cookieStore.clear();
         // Note: baseUrl is not reset as it's derived from immutable config
     }
+    /**
+     * The session-bearing cookies, and only those.
+     *
+     * `sap-XSRF_*` is excluded deliberately: it changes on a token refresh WITHIN
+     * the same session, so including it would report an ordinary refresh as a new
+     * session and fail exactly where nothing is wrong. `sap-usercontext` is ours,
+     * overwritten on every response.
+     */
+    sessionFingerprint() {
+        const fingerprint = new Map();
+        for (const [name, value] of this.cookieStore) {
+            if (name.startsWith('SAP_SESSIONID')) {
+                fingerprint.set(name, value);
+            }
+        }
+        return fingerprint;
+    }
     async getBaseUrl() {
         return this.baseUrl;
     }
@@ -187,6 +488,20 @@ class AbstractAbapConnection {
         return headers;
     }
     async makeAdtRequest(options) {
+        // Admission first, synchronously, before any await: the check and the
+        // count must happen in one step, or a request could be admitted and still
+        // be invisible to a teardown draining at that instant. Throws
+        // NOT_CONNECTED when the caller never connected, or when a teardown has
+        // shut the door.
+        const lease = this.lifecycle.admitRequest();
+        try {
+            return await this.performRequest(options, lease);
+        }
+        finally {
+            lease.release();
+        }
+    }
+    async performRequest(options, lease) {
         const { url: endpoint, method, timeout, data, params, headers: customHeaders, } = options;
         const normalizedMethod = method.toUpperCase();
         // Build full URL: baseUrl + endpoint
@@ -282,7 +597,7 @@ class AbstractAbapConnection {
         });
         try {
             const response = await this.getAxiosInstance()(requestConfig);
-            this.updateCookiesFromResponse(response.headers);
+            this.observeResponse(response.headers, lease.generation);
             this.logger?.debug(`Request succeeded with status ${response.status}`, {
                 type: 'REQUEST_SUCCESS',
                 status: response.status,
@@ -292,6 +607,20 @@ class AbstractAbapConnection {
             return response;
         }
         catch (error) {
+            // FENCE FIRST, before anything reads or writes shared state.
+            //
+            // Fencing observeResponse() alone was not enough, and the gap was wide:
+            // everything below acts on this connection, not on the request. A late
+            // 400 "session not found" would call raiseSessionLost() and tear down the
+            // healthy session established since; a late 401/403 would call
+            // invalidateSession(), write a fresh CSRF token, and RETRY — replaying a
+            // mutation from a dead session inside the live one.
+            //
+            // A stale request gets its error back and nothing else happens.
+            if (!this.lifecycle.isCurrent(lease)) {
+                this.logger?.debug('A request from a previous session failed; its recovery is fenced');
+                throw error;
+            }
             const errorDetails = {
                 type: 'REQUEST_ERROR',
                 message: error instanceof Error ? error.message : String(error),
@@ -305,7 +634,17 @@ class AbstractAbapConnection {
                     typeof error.response.data === 'string'
                         ? error.response.data.slice(0, 200)
                         : JSON.stringify(error.response.data).slice(0, 200);
-                this.updateCookiesFromResponse(error.response.headers);
+                this.observeResponse(error.response.headers, lease.generation);
+            }
+            // The server telling us the session is gone is invisible to the identity
+            // comparison: the cookie, and therefore the fingerprint, is unchanged.
+            // Only the state can see it, and it must say so at once — otherwise a
+            // later unlockAll() finds a match and unlocks over a dead session.
+            if (this.isDeadSessionResponse(error)) {
+                this.raiseSessionLost('the server reports the session no longer exists');
+                // No internal retry: a blind retry here is what produced further locks
+                // in the field. The caller decides.
+                throw (0, SessionLifecycle_js_1.sessionError)(interfaces_1.ADT_SESSION_ERROR.SESSION_REPLACED, 'The SAP session no longer exists; any lock handle from it is dead');
             }
             // Check if this is a network error (connection refused, timeout, DNS, etc.)
             // Don't retry for network errors - these indicate infrastructure/VPN issues
@@ -347,7 +686,7 @@ class AbstractAbapConnection {
                     delete requestHeaders.cookie;
                 }
                 try {
-                    this.setCsrfToken(await this.fetchCsrfToken(requestUrl, 5, 2000));
+                    this.setCsrfToken(await this.fetchCsrfToken(requestUrl, 5, 2000, lease.generation));
                     const refreshedToken = this.getCsrfToken();
                     if (refreshedToken) {
                         requestHeaders['x-csrf-token'] = refreshedToken;
@@ -357,10 +696,16 @@ class AbstractAbapConnection {
                         requestHeaders.Cookie = refreshedCookies;
                     }
                     const retryResponse = await this.getAxiosInstance()(requestConfig);
-                    this.updateCookiesFromResponse(retryResponse.headers);
+                    this.observeResponse(retryResponse.headers, lease.generation);
                     return retryResponse;
                 }
                 catch (retryError) {
+                    // A session verdict outranks the error that started the retry: the
+                    // caller can retry a 403 itself, but it cannot discover that its lock
+                    // handle is dead from a 403.
+                    if (this.isSessionVerdict(retryError)) {
+                        throw retryError;
+                    }
                     this.logger?.debug(`CSRF retry failed; rethrowing original error: ${retryError instanceof Error
                         ? retryError.message
                         : String(retryError)}`);
@@ -379,23 +724,26 @@ class AbstractAbapConnection {
                     this.logger?.debug(`[DEBUG] BaseAbapConnection - 401 on GET request, retrying with cookies from error response`);
                     requestHeaders.Cookie = this.cookies;
                     const retryResponse = await this.getAxiosInstance()(requestConfig);
-                    this.updateCookiesFromResponse(retryResponse.headers);
+                    this.observeResponse(retryResponse.headers, lease.generation);
                     return retryResponse;
                 }
                 // If no cookies, try to get them via CSRF token fetch
                 this.logger?.debug(`[DEBUG] BaseAbapConnection - 401 on GET request, attempting to get cookies via CSRF token fetch`);
                 try {
                     // Try to get CSRF token (this will also get cookies)
-                    this.csrfToken = await this.fetchCsrfToken(requestUrl, 3, 1000);
+                    this.csrfToken = await this.fetchCsrfToken(requestUrl, 3, 1000, lease.generation);
                     if (this.cookies) {
                         requestHeaders.Cookie = this.cookies;
                         this.logger?.debug(`[DEBUG] BaseAbapConnection - Retrying GET request with cookies from CSRF fetch`);
                         const retryResponse = await this.getAxiosInstance()(requestConfig);
-                        this.updateCookiesFromResponse(retryResponse.headers);
+                        this.observeResponse(retryResponse.headers, lease.generation);
                         return retryResponse;
                     }
                 }
                 catch (csrfError) {
+                    if (this.isSessionVerdict(csrfError)) {
+                        throw csrfError;
+                    }
                     this.logger?.debug(`[DEBUG] BaseAbapConnection - Failed to get CSRF token for 401 retry: ${csrfError instanceof Error ? csrfError.message : String(csrfError)}`);
                     // Fall through to throw original error
                 }
@@ -407,7 +755,9 @@ class AbstractAbapConnection {
      * Fetch CSRF token from SAP system
      * Protected method for use by concrete implementations in their connect() method
      */
-    async fetchCsrfToken(url, retryCount = csrfConfig_js_1.CSRF_CONFIG.RETRY_COUNT, retryDelay = csrfConfig_js_1.CSRF_CONFIG.RETRY_DELAY) {
+    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) {
         // Try primary endpoint first, then fallback for older systems
         const baseUrl = url.includes('/sap/bc/adt/')
             ? url.split('/sap/bc/adt')[0]
@@ -431,9 +781,16 @@ class AbstractAbapConnection {
         let lastError;
         for (const csrfUrl of endpoints) {
             try {
-                return await this.fetchCsrfTokenFromEndpoint(csrfUrl, retryCount, retryDelay);
+                return await this.fetchCsrfTokenFromEndpoint(csrfUrl, retryCount, retryDelay, generation);
             }
             catch (error) {
+                // Third layer with a catch on this path, and the last one that could
+                // bury a verdict: falling through to the fallback endpoint would open
+                // ANOTHER session, and by then the teardown has cleared the fingerprint
+                // so the new one reads as `established` and the loss disappears.
+                if (this.isSessionVerdict(error)) {
+                    throw error;
+                }
                 lastError = error instanceof Error ? error : new Error(String(error));
                 this.logger?.debug(`CSRF token not available from ${csrfUrl}, trying next endpoint...`);
             }
@@ -444,7 +801,7 @@ class AbstractAbapConnection {
     /**
      * Fetch CSRF token from a specific endpoint with retries
      */
-    async fetchCsrfTokenFromEndpoint(csrfUrl, retryCount, retryDelay) {
+    async fetchCsrfTokenFromEndpoint(csrfUrl, retryCount, retryDelay, generation) {
         this.logger?.debug(`Fetching CSRF token from: ${csrfUrl}`);
         for (let attempt = 0; attempt <= retryCount; attempt++) {
             try {
@@ -482,7 +839,7 @@ class AbstractAbapConnection {
                     headers,
                     timeout: (0, timeouts_js_1.getTimeout)('csrf'),
                 });
-                this.updateCookiesFromResponse(response.headers);
+                this.observeResponse(response.headers, generation);
                 const token = response.headers['x-csrf-token'];
                 if (!token) {
                     this.logger?.error('No CSRF token in response headers', {
@@ -496,7 +853,7 @@ class AbstractAbapConnection {
                     throw new Error(csrfConfig_js_1.CSRF_ERROR_MESSAGES.NOT_IN_HEADERS);
                 }
                 if (response.headers['set-cookie']) {
-                    this.updateCookiesFromResponse(response.headers);
+                    this.observeResponse(response.headers, generation);
                     if (this.cookies) {
                         this.logger?.debug(`[DEBUG] BaseAbapConnection - Cookies received from CSRF response (first 100 chars): ${this.cookies.substring(0, 100)}...`);
                         this.logger?.debug('Cookies extracted from response', {
@@ -508,11 +865,19 @@ class AbstractAbapConnection {
                 return token;
             }
             catch (error) {
+                // A session verdict is not a failed token fetch and must not be
+                // retried into silence: the retry would observe the SAME new session,
+                // read it as `unchanged`, and the replacement this raised would be gone
+                // for good. It leaves immediately, past the loop and past the caller's
+                // recovery.
+                if (this.isSessionVerdict(error)) {
+                    throw error;
+                }
                 if (error instanceof axios_1.AxiosError) {
                     // Always try to extract cookies from error response, even on 401
                     // This ensures cookies are available for subsequent requests
                     if (error.response?.headers) {
-                        this.updateCookiesFromResponse(error.response.headers);
+                        this.observeResponse(error.response.headers, generation);
                         if (this.cookies) {
                             this.logger?.debug('Cookies extracted from error response', {
                                 status: error.response.status,
@@ -531,14 +896,14 @@ class AbstractAbapConnection {
                         this.logger?.debug('CSRF: SAP returned 405 (Method Not Allowed) — not critical, token found in header');
                         const token = error.response.headers['x-csrf-token'];
                         if (token) {
-                            this.updateCookiesFromResponse(error.response.headers);
+                            this.observeResponse(error.response.headers, generation);
                             return token;
                         }
                     }
                     if (error.response?.headers['x-csrf-token']) {
                         this.logger?.debug(`Got CSRF token despite error (status: ${error.response?.status})`);
                         const token = error.response.headers['x-csrf-token'];
-                        this.updateCookiesFromResponse(error.response.headers);
+                        this.observeResponse(error.response.headers, generation);
                         return token;
                     }
                     if (error.response) {
@@ -597,13 +962,19 @@ class AbstractAbapConnection {
     setInitialCookies(cookies) {
         this.cookies = cookies;
     }
+    /**
+     * Folds a response's cookies into the jar and classifies what that means for
+     * the session identity. Returns the classification rather than acting on it:
+     * cookie parsing stays free of policy, and no exception fires in the middle
+     * of a state update. The caller decides.
+     */
     updateCookiesFromResponse(headers) {
         if (!headers) {
-            return;
+            return 'unchanged';
         }
         const setCookie = headers['set-cookie'];
         if (!setCookie) {
-            return;
+            return 'unchanged';
         }
         const cookiesArray = Array.isArray(setCookie) ? setCookie : [setCookie];
         for (const entry of cookiesArray) {
@@ -633,16 +1004,17 @@ class AbstractAbapConnection {
             this.cookieStore.set('sap-usercontext', `sap-client=${this.config.client}`);
         }
         if (this.cookieStore.size === 0) {
-            return;
+            return 'unchanged';
         }
         const combined = Array.from(this.cookieStore.entries())
             .map(([name, value]) => (value ? `${name}=${value}` : name))
             .join('; ');
         if (!combined) {
-            return;
+            return 'unchanged';
         }
         this.cookies = combined;
         this.logger?.debug(`[DEBUG] BaseAbapConnection - Updated cookies from response (first 100 chars): ${this.cookies.substring(0, 100)}...`);
+        return this.lifecycle.observe(this.sessionFingerprint());
     }
     /**
      * Subclasses override to inject extra https.Agent options (e.g. mTLS cert/key/pfx).
@@ -700,6 +1072,13 @@ class AbstractAbapConnection {
         this.setCsrfToken(null);
         this.cookies = null;
         this.cookieStore.clear();
+        // And the tracked identity, because WE discarded the session. Without this
+        // the cookie that arrives next reads as a foreign replacement — and since a
+        // replacement is now always fatal, our own deliberate re-authentication
+        // would tear the connection down. The distinction that matters is not
+        // "was a lock held" but "did we cause this": what we discarded on purpose
+        // is not a session taken from under us.
+        this.lifecycle.forgetIdentity();
     }
     shouldRetryCsrf(error) {
         if (!(error instanceof axios_1.AxiosError)) {

package/dist/connection/BaseAbapConnection.d.ts

@@ -12,7 +12,11 @@ export declare class BaseAbapConnection extends AbstractAbapConnection {
      * Connect to SAP system with Basic Auth
      * Fetches CSRF token which also establishes session cookies
      */
-    connect(): Promise<void>;
+    /**
+     * Establishes the session for this auth type. Called by
+     * AbstractAbapConnection.connect(), which owns the lifecycle around it.
+     */
+    protected establishSession(): Promise<void>;
     protected buildAuthorizationHeader(): string;
     private static validateConfig;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"BaseAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/BaseAbapConnection.ts"],"names":[],"mappings":"AACA,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;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,sBAAsB;gBAE1D,MAAM,EAAE,SAAS,EACjB,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,EACvB,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE;IAMzC;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAsC9B,SAAS,CAAC,wBAAwB,IAAI,MAAM;IAU5C,OAAO,CAAC,MAAM,CAAC,cAAc;CAmB9B"}
+{"version":3,"file":"BaseAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/BaseAbapConnection.ts"],"names":[],"mappings":"AACA,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;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,sBAAsB;gBAE1D,MAAM,EAAE,SAAS,EACjB,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,EACvB,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE;IAMzC;;;OAGG;IACH;;;OAGG;cACa,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IA6CjD,SAAS,CAAC,wBAAwB,IAAI,MAAM;IAU5C,OAAO,CAAC,MAAM,CAAC,cAAc;CAmB9B"}

package/dist/connection/BaseAbapConnection.js

@@ -15,7 +15,11 @@ class BaseAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnect
      * Connect to SAP system with Basic Auth
      * Fetches CSRF token which also establishes session cookies
      */
-    async connect() {
+    /**
+     * Establishes the session for this auth type. Called by
+     * AbstractAbapConnection.connect(), which owns the lifecycle around it.
+     */
+    async establishSession() {
         const baseUrl = await this.getBaseUrl();
         const discoveryUrl = `${baseUrl}/sap/bc/adt/discovery`;
         this.logger?.debug(`[DEBUG] BaseAbapConnection - Connecting to SAP system: ${discoveryUrl}`);
@@ -41,6 +45,12 @@ class BaseAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnect
                     this.logger?.debug(`[DEBUG] BaseAbapConnection - Cookies extracted from error response during connect (first 100 chars): ${this.getCookies()?.substring(0, 100)}...`);
                 }
             }
+            // Rethrow: a resolved connect() must mean a usable session exists. This
+            // used to swallow and resolve anyway, deferring establishment to the
+            // first request — coherent only while that lazy path existed. Without it,
+            // swallowing would leave a connection that reports success, holds
+            // nothing, and refuses every request.
+            throw error;
         }
     }
     buildAuthorizationHeader() {

package/dist/connection/CertificateAbapConnection.d.ts

@@ -14,7 +14,11 @@ export declare class CertificateAbapConnection extends AbstractAbapConnection {
      * Loads certificate material and primes the session. MUST be called before the first
      * request — the TLS agent is built lazily and needs the client cert present.
      */
-    connect(): Promise<void>;
+    /**
+     * Establishes the session for this auth type. Called by
+     * AbstractAbapConnection.connect(), which owns the lifecycle around it.
+     */
+    protected establishSession(): Promise<void>;
     protected getHttpsAgentOptions(): AgentOptions;
     protected buildAuthorizationHeader(): string;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"CertificateAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/CertificateAbapConnection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAEV,0BAA0B,EAC3B,MAAM,0BAA0B,CAAC;AAGlC,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,mFAAmF;AACnF,qBAAa,yBAA0B,SAAQ,sBAAsB;IACnE,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,QAAQ,CAAqC;gBAGnD,MAAM,EAAE,SAAS,EACjB,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,EACvB,SAAS,CAAC,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,0BAA0B;IAOrC,OAAO,CAAC,MAAM,CAAC,cAAc;cAyBb,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAM/C;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB9B,SAAS,CAAC,oBAAoB,IAAI,YAAY;IAU9C,SAAS,CAAC,wBAAwB,IAAI,MAAM;CAG7C"}
+{"version":3,"file":"CertificateAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/CertificateAbapConnection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAEV,0BAA0B,EAC3B,MAAM,0BAA0B,CAAC;AAGlC,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,mFAAmF;AACnF,qBAAa,yBAA0B,SAAQ,sBAAsB;IACnE,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,QAAQ,CAAqC;gBAGnD,MAAM,EAAE,SAAS,EACjB,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,EACvB,SAAS,CAAC,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,0BAA0B;IAOrC,OAAO,CAAC,MAAM,CAAC,cAAc;cAyBb,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAM/C;;;OAGG;IACH;;;OAGG;cACa,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IA6BjD,SAAS,CAAC,oBAAoB,IAAI,YAAY;IAU9C,SAAS,CAAC,wBAAwB,IAAI,MAAM;CAG7C"}