@oxy.so/core 7.9.0 → 7.9.1

package/dist/cjs/HttpService.js

@@ -71,6 +71,18 @@ function sameTokenSession(left, right) {
         'authMethodId',
     ].every((key) => (a[key] === undefined || typeof a[key] === 'string') && a[key] === b[key]);
 }
+/** Discard an unused body even when a platform's stream shim lacks cancel. */
+function discardResponseBody(response) {
+    try {
+        const body = response.body;
+        if (typeof body?.cancel !== 'function')
+            return Promise.resolve();
+        return Promise.resolve(body.cancel()).catch(() => { });
+    }
+    catch {
+        return Promise.resolve();
+    }
+}
 /**
  * The keys whose presence beside `data` makes a body a PAGE rather than a
  * payload — see {@link HttpService.unwrapResponse} for why this list is narrow.
@@ -463,6 +475,13 @@ class HttpService {
      * {@link ResponsePayload}, which makes reading the envelope a compile error.
      */
     async request(config) {
+        if (config.signal?.aborted)
+            throw (0, errorUtils_1.createCancelledError)('Request cancelled before it was sent');
+        // The provider can change independently of the last request. Synchronize
+        // before deriving the cache and deduplication identity, including hits.
+        const explicitAuthorization = Object.keys(config.headers ?? {}).some((key) => key.toLowerCase() === 'authorization');
+        if (!config.skipAuth && !explicitAuthorization)
+            this.syncAccessTokenFromProvider();
         // Per-call authority is not represented by the instance's session cache
         // key. Never share or retain responses authenticated by explicit headers.
         if (Object.keys(config.headers ?? {}).some((key) => ['authorization', 'x-oxy-user-id'].includes(key.toLowerCase()) ||
@@ -484,7 +503,8 @@ class HttpService {
                 valid: true,
             });
         }
-        const key = this.generateCacheKey(config.method, config.url, config.data || config.params);
+        const key = this.generateCacheKey(config.method, config.url, config.data || config.params) +
+            (config.skipAuth ? ' auth=none' : '');
         let lease = this.readLeases.get(key);
         if (!lease) {
             lease = { key, id: ++this.nextReadLeaseId, valid: true, readers: 0 };
@@ -514,6 +534,7 @@ class HttpService {
         // overrides any per-request `cache:true`: nothing is read from nor written
         // to the response cache. Request deduplication below is unaffected.
         const cache = cacheRequested && !this.cacheDisabled;
+        const cacheSessionEpoch = this.sessionEpoch;
         // Generate cache key (optimized for large objects)
         const cacheKey = cache ? lease.key : null;
         // Check cache first
@@ -538,7 +559,33 @@ class HttpService {
         // and skip the near-expiry preflight — see RequestOptions.skipAuth. The
         // 401 retry re-enters request() with a fresh config, so it re-resolves
         // this here with the refreshed token.
-        const authHeader = config.skipAuth ? null : await this.getAuthHeader();
+        const explicitAuth = Object.keys(config.headers ?? {}).some((key) => key.toLowerCase() === 'authorization');
+        const usesSessionAuth = !config.skipAuth && !explicitAuth;
+        const contextToken = usesSessionAuth ? this.syncAccessTokenFromProvider() : null;
+        const contextEpoch = this.sessionEpoch;
+        const authHeader = usesSessionAuth
+            ? await (0, requestSignal_1.awaitRequestSignal)(this.getAuthHeader(), signal)
+            : null;
+        const isOriginalSession = () => this.sessionEpoch === contextEpoch &&
+            sameTokenSession(contextToken, this.syncAccessTokenFromProvider());
+        const newerRequestToken = () => {
+            if (!contextToken || !authHeader?.startsWith('Bearer '))
+                return null;
+            const requestToken = authHeader.slice('Bearer '.length);
+            const current = this.syncAccessTokenFromProvider();
+            return current && current !== requestToken && sameTokenSession(requestToken, current)
+                ? current
+                : null;
+        };
+        // The provider can change between cache-key selection and auth preflight.
+        // Refuse to attach a response to a lease belonging to another identity.
+        if (usesSessionAuth &&
+            (!isOriginalSession() ||
+                (lease.key &&
+                    (cacheSessionEpoch !== this.sessionEpoch ||
+                        lease.key !== this.generateCacheKey(method, url, data || params))))) {
+            throw new OxyServices_errors_1.OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+        }
         // Never awaited: the PoP is a hint, and waiting on its trace fetch put up
         // to a second in front of requests.
         const edgeRegionHeader = (0, edgeRegion_1.peekBrowserEdgeRegionHeader)();
@@ -561,6 +608,9 @@ class HttpService {
             if (domain.aborted) {
                 throw (0, errorUtils_1.createCancelledError)('Request cancelled');
             }
+            if (usesSessionAuth && !isOriginalSession()) {
+                throw new OxyServices_errors_1.OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+            }
             /**
              * Whether OUR timer fired, so a timeout can be told apart from a
              * cancellation. Both reach us from `fetch` as an indistinguishable
@@ -568,6 +618,7 @@ class HttpService {
              * an abandoned request as a transient failure.
              */
             let timedOut = false;
+            let selfClearedEpoch = null;
             // This attempt's controller carries its own timeout and inherits the
             // call-wide abort domain. Declared OUTSIDE the `try` so the `finally`
             // that releases them can see them — the timer and the listener are
@@ -670,14 +721,27 @@ class HttpService {
                 // it, including on every throw between here and there.
                 if (timeoutId)
                     clearTimeout(timeoutId);
+                if (usesSessionAuth && !isOriginalSession()) {
+                    void discardResponseBody(response);
+                    throw new OxyServices_errors_1.OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+                }
                 // Handle response
                 if (!response.ok) {
                     // On 401, delegate to the installed auth refresh handler and retry
                     // once before giving up. HttpService deliberately does not know any
                     // session routes; the refresh handler owns session rotation.
-                    if (response.status === 401 && !config._isAuthRetry && !config.skipAuth) {
-                        const refreshed = await this.refreshAccessToken('response-401');
-                        if (refreshed) {
+                    if (response.status === 401 &&
+                        !config._isAuthRetry &&
+                        usesSessionAuth &&
+                        isOriginalSession()) {
+                        let refreshed = newerRequestToken();
+                        if (!refreshed) {
+                            if (domain.aborted)
+                                throw (0, errorUtils_1.createCancelledError)();
+                            refreshed = await (0, requestSignal_1.awaitRequestSignal)(this.refreshAccessToken('response-401'), domain);
+                        }
+                        refreshed || (refreshed = newerRequestToken());
+                        if (refreshed && isOriginalSession()) {
                             // `deduplicate: false` is REQUIRED on the retry. This re-issue runs
                             // while the ORIGINAL request is still in-flight under its dedupe
                             // key; the refreshed token is
@@ -696,11 +760,19 @@ class HttpService {
                                 retry: false,
                                 deduplicate: false,
                                 bypassQueue: true,
+                                // The original caller's signal may be aborted while another
+                                // deduplicated caller still owns this shared request.
+                                signal: domain,
                             });
                         }
                         // Refresh failed or no token — clear tokens
-                        this.tokenStore.clearTokens();
-                        this.notifyTokenChange();
+                        if (isOriginalSession()) {
+                            if (this.tokenStore.getAccessToken())
+                                this.sessionEpoch += 1;
+                            this.tokenStore.clearTokens();
+                            selfClearedEpoch = this.sessionEpoch;
+                            this.notifyTokenChange();
+                        }
                     }
                     // Read the error body (may be absent, non-JSON, empty or malformed).
                     // Anything unreadable leaves `errorBody` undefined and degrades to the
@@ -787,6 +859,9 @@ class HttpService {
                     const text = await response.text();
                     responseData = text || null;
                 }
+                if (usesSessionAuth && !isOriginalSession()) {
+                    throw new OxyServices_errors_1.OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+                }
                 const duration = Date.now() - startTime;
                 this.updateMetrics(true, duration);
                 this.config.onRequestEnd?.(url, method, duration, true);
@@ -795,6 +870,21 @@ class HttpService {
             catch (error) {
                 const duration = Date.now() - startTime;
                 this.updateMetrics(false, duration);
+                // A body reader can reject or finish parsing an error after the viewer
+                // changed. Do not surface that previous viewer's error or callbacks.
+                // An explicit abort/timeout retains its existing classification.
+                const providerToken = selfClearedEpoch !== null ? this.accessTokenProvider?.() : null;
+                const originalClearStillCurrent = selfClearedEpoch !== null &&
+                    selfClearedEpoch === this.sessionEpoch &&
+                    this.tokenStore.getAccessToken() === null &&
+                    (!providerToken || sameTokenSession(contextToken, providerToken));
+                if (usesSessionAuth &&
+                    !originalClearStillCurrent &&
+                    !isOriginalSession() &&
+                    !isAbortLike(error) &&
+                    !controller.signal.aborted) {
+                    throw new OxyServices_errors_1.OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+                }
                 this.config.onRequestEnd?.(url, method, duration, false);
                 this.config.onRequestError?.(url, method, error instanceof Error ? error : new Error(String(error)));
                 // An abort is the one failure whose CAUSE the error cannot carry on its
@@ -886,6 +976,9 @@ class HttpService {
                 disposeCallerLink?.();
             }
         }
+        if (usesSessionAuth && !isOriginalSession()) {
+            throw new OxyServices_errors_1.OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+        }
         // Cache the result if caching is enabled
         if (cache && cacheKey && lease.valid && result) {
             this.cache.set(cacheKey, result, cacheTTL);
@@ -1049,7 +1142,7 @@ class HttpService {
      * in `clearCacheEntry`.
      */
     generateCacheKey(method, url, data) {
-        return `${this.generateBaseCacheKey(method, url, data)}${HttpService.CACHE_IDENTITY_DELIM}${this.computeIdentityTag()}`;
+        return `${this.generateBaseCacheKey(method, url, data)}${HttpService.CACHE_IDENTITY_DELIM}${this.computeIdentityTag()} epoch=${this.sessionEpoch}`;
     }
     /**
      * Build the identity-agnostic portion of a cache key (`method:url[:data]`).
@@ -1173,6 +1266,7 @@ class HttpService {
             // on the way out would discard the flag it just set.
             this.lastRefreshWasRateLimited = false;
             const epoch = this.sessionEpoch;
+            const tokenAtStart = this.tokenStore.getAccessToken();
             this.tokenRefreshPromise = this.authRefreshHandler(reason)
                 .then((newToken) => {
                 if (epoch !== this.sessionEpoch) {
@@ -1185,6 +1279,12 @@ class HttpService {
                     this.logger.debug('Discarded a token refresh that outlived its session');
                     return null;
                 }
+                const installed = this.tokenStore.getAccessToken();
+                if (installed !== tokenAtStart && installed !== newToken) {
+                    // Another operation installed a token while this refresh was in
+                    // flight. Never overwrite it with this older completion.
+                    return installed && sameTokenSession(tokenAtStart, installed) ? installed : null;
+                }
                 if (!newToken) {
                     this.lastRefreshFailureAt = Date.now();
                     return null;
@@ -1482,7 +1582,7 @@ class HttpService {
                 assertCurrent();
             }
             catch (error) {
-                await response.body?.cancel();
+                await discardResponseBody(response);
                 throw error;
             }
             const replayable = Boolean(config.bodyFactory) || body === undefined || typeof body === 'string';
@@ -1496,18 +1596,18 @@ class HttpService {
                     refreshed = await (0, requestSignal_1.awaitRequestSignal)(this.refreshAccessToken('response-401'), config.signal);
                 }
                 catch (error) {
-                    void response.body?.cancel().catch(() => undefined);
+                    void discardResponseBody(response);
                     throw error;
                 }
                 try {
                     assertCurrent();
                 }
                 catch (error) {
-                    await response.body?.cancel();
+                    await discardResponseBody(response);
                     throw error;
                 }
                 if (refreshed) {
-                    await response.body?.cancel();
+                    await discardResponseBody(response);
                     if (config.signal?.aborted)
                         throw (0, errorUtils_1.createCancelledError)();
                     return this.requestResponseAttempt(config, fullUrl, `Bearer ${refreshed}`, true, epoch, contextToken);
@@ -1673,6 +1773,7 @@ class HttpService {
     peekCachedGet(url, params) {
         if (this.cacheDisabled)
             return null;
+        this.syncAccessTokenFromProvider();
         return this.cache.get(this.generateCacheKey('GET', url, params));
     }
     clearCache() {

package/dist/cjs/shared/utils/errorUtils.js

@@ -8,7 +8,7 @@
  * @module shared/utils/errorUtils
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isRetryableError = exports.isNetworkError = exports.isServerError = exports.isRateLimitError = exports.isNotFoundError = exports.isForbiddenError = exports.isUnauthorizedError = exports.isAlreadyRegisteredError = exports.getErrorMessage = exports.getErrorStatus = exports.HttpStatus = void 0;
+exports.isRetryableError = exports.isNetworkError = exports.isServerError = exports.isRateLimitError = exports.isNotFoundError = exports.isForbiddenError = exports.isUnauthorizedError = exports.isAlreadyRegisteredError = exports.getErrorMessage = exports.isSessionChangedError = exports.getErrorStatus = exports.HttpStatus = void 0;
 /**
  * Common HTTP status codes used in error checking.
  */
@@ -50,6 +50,9 @@ const getErrorStatus = (error) => {
     return undefined;
 };
 exports.getErrorStatus = getErrorStatus;
+/** A locally superseded request is not an unauthorized response from the server. */
+const isSessionChangedError = (error) => !!error && typeof error === 'object' && 'code' in error && error.code === 'AUTH_SESSION_CHANGED';
+exports.isSessionChangedError = isSessionChangedError;
 /**
  * Extracts the error message from an error object.
  *
@@ -104,7 +107,7 @@ exports.isAlreadyRegisteredError = isAlreadyRegisteredError;
  * @returns true if the error is a 401 Unauthorized
  */
 const isUnauthorizedError = (error) => {
-    return (0, exports.getErrorStatus)(error) === exports.HttpStatus.UNAUTHORIZED;
+    return !(0, exports.isSessionChangedError)(error) && (0, exports.getErrorStatus)(error) === exports.HttpStatus.UNAUTHORIZED;
 };
 exports.isUnauthorizedError = isUnauthorizedError;
 /**

package/dist/cjs/utils/asyncUtils.js

@@ -5,6 +5,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.retryAsync = retryAsync;
 const errorUtils_1 = require("./errorUtils");
+const errorUtils_2 = require("../shared/utils/errorUtils");
 /**
  * Whether an error came from a request hitting its own timeout.
  *
@@ -102,6 +103,11 @@ async function retryAsync(operation, maxRetriesOrOptions = 3, baseDelayArg = 100
             if ((0, errorUtils_1.isCancelledError)(error)) {
                 break;
             }
+            // A changed authentication context is a cancellation of this work, even
+            // if the caller's custom predicate would retry ordinary 401 responses.
+            if ((0, errorUtils_2.isSessionChangedError)(error)) {
+                break;
+            }
             if (!retryOnTimeout && isTimeoutError(error)) {
                 break;
             }

package/dist/cjs/utils/authHelpers.js

@@ -9,6 +9,7 @@ exports.ensureValidToken = ensureValidToken;
 exports.isAuthenticationError = isAuthenticationError;
 exports.withAuthErrorHandling = withAuthErrorHandling;
 exports.authenticatedApiCall = authenticatedApiCall;
+const errorUtils_1 = require("../shared/utils/errorUtils");
 /**
  * Error thrown when session sync is required
  */
@@ -63,6 +64,8 @@ async function ensureValidToken(oxyServices, _activeSessionId, syncSession) {
  * Checks if an error is an authentication error (401 or auth-related message)
  */
 function isAuthenticationError(error) {
+    if ((0, errorUtils_1.isSessionChangedError)(error))
+        return false;
     if (!error || typeof error !== 'object') {
         return false;
     }

package/dist/esm/HttpService.js

@@ -68,6 +68,18 @@ function sameTokenSession(left, right) {
         'authMethodId',
     ].every((key) => (a[key] === undefined || typeof a[key] === 'string') && a[key] === b[key]);
 }
+/** Discard an unused body even when a platform's stream shim lacks cancel. */
+function discardResponseBody(response) {
+    try {
+        const body = response.body;
+        if (typeof body?.cancel !== 'function')
+            return Promise.resolve();
+        return Promise.resolve(body.cancel()).catch(() => { });
+    }
+    catch {
+        return Promise.resolve();
+    }
+}
 /**
  * The keys whose presence beside `data` makes a body a PAGE rather than a
  * payload — see {@link HttpService.unwrapResponse} for why this list is narrow.
@@ -460,6 +472,13 @@ export class HttpService {
      * {@link ResponsePayload}, which makes reading the envelope a compile error.
      */
     async request(config) {
+        if (config.signal?.aborted)
+            throw createCancelledError('Request cancelled before it was sent');
+        // The provider can change independently of the last request. Synchronize
+        // before deriving the cache and deduplication identity, including hits.
+        const explicitAuthorization = Object.keys(config.headers ?? {}).some((key) => key.toLowerCase() === 'authorization');
+        if (!config.skipAuth && !explicitAuthorization)
+            this.syncAccessTokenFromProvider();
         // Per-call authority is not represented by the instance's session cache
         // key. Never share or retain responses authenticated by explicit headers.
         if (Object.keys(config.headers ?? {}).some((key) => ['authorization', 'x-oxy-user-id'].includes(key.toLowerCase()) ||
@@ -481,7 +500,8 @@ export class HttpService {
                 valid: true,
             });
         }
-        const key = this.generateCacheKey(config.method, config.url, config.data || config.params);
+        const key = this.generateCacheKey(config.method, config.url, config.data || config.params) +
+            (config.skipAuth ? ' auth=none' : '');
         let lease = this.readLeases.get(key);
         if (!lease) {
             lease = { key, id: ++this.nextReadLeaseId, valid: true, readers: 0 };
@@ -511,6 +531,7 @@ export class HttpService {
         // overrides any per-request `cache:true`: nothing is read from nor written
         // to the response cache. Request deduplication below is unaffected.
         const cache = cacheRequested && !this.cacheDisabled;
+        const cacheSessionEpoch = this.sessionEpoch;
         // Generate cache key (optimized for large objects)
         const cacheKey = cache ? lease.key : null;
         // Check cache first
@@ -535,7 +556,33 @@ export class HttpService {
         // and skip the near-expiry preflight — see RequestOptions.skipAuth. The
         // 401 retry re-enters request() with a fresh config, so it re-resolves
         // this here with the refreshed token.
-        const authHeader = config.skipAuth ? null : await this.getAuthHeader();
+        const explicitAuth = Object.keys(config.headers ?? {}).some((key) => key.toLowerCase() === 'authorization');
+        const usesSessionAuth = !config.skipAuth && !explicitAuth;
+        const contextToken = usesSessionAuth ? this.syncAccessTokenFromProvider() : null;
+        const contextEpoch = this.sessionEpoch;
+        const authHeader = usesSessionAuth
+            ? await awaitRequestSignal(this.getAuthHeader(), signal)
+            : null;
+        const isOriginalSession = () => this.sessionEpoch === contextEpoch &&
+            sameTokenSession(contextToken, this.syncAccessTokenFromProvider());
+        const newerRequestToken = () => {
+            if (!contextToken || !authHeader?.startsWith('Bearer '))
+                return null;
+            const requestToken = authHeader.slice('Bearer '.length);
+            const current = this.syncAccessTokenFromProvider();
+            return current && current !== requestToken && sameTokenSession(requestToken, current)
+                ? current
+                : null;
+        };
+        // The provider can change between cache-key selection and auth preflight.
+        // Refuse to attach a response to a lease belonging to another identity.
+        if (usesSessionAuth &&
+            (!isOriginalSession() ||
+                (lease.key &&
+                    (cacheSessionEpoch !== this.sessionEpoch ||
+                        lease.key !== this.generateCacheKey(method, url, data || params))))) {
+            throw new OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+        }
         // Never awaited: the PoP is a hint, and waiting on its trace fetch put up
         // to a second in front of requests.
         const edgeRegionHeader = peekBrowserEdgeRegionHeader();
@@ -558,6 +605,9 @@ export class HttpService {
             if (domain.aborted) {
                 throw createCancelledError('Request cancelled');
             }
+            if (usesSessionAuth && !isOriginalSession()) {
+                throw new OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+            }
             /**
              * Whether OUR timer fired, so a timeout can be told apart from a
              * cancellation. Both reach us from `fetch` as an indistinguishable
@@ -565,6 +615,7 @@ export class HttpService {
              * an abandoned request as a transient failure.
              */
             let timedOut = false;
+            let selfClearedEpoch = null;
             // This attempt's controller carries its own timeout and inherits the
             // call-wide abort domain. Declared OUTSIDE the `try` so the `finally`
             // that releases them can see them — the timer and the listener are
@@ -667,14 +718,27 @@ export class HttpService {
                 // it, including on every throw between here and there.
                 if (timeoutId)
                     clearTimeout(timeoutId);
+                if (usesSessionAuth && !isOriginalSession()) {
+                    void discardResponseBody(response);
+                    throw new OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+                }
                 // Handle response
                 if (!response.ok) {
                     // On 401, delegate to the installed auth refresh handler and retry
                     // once before giving up. HttpService deliberately does not know any
                     // session routes; the refresh handler owns session rotation.
-                    if (response.status === 401 && !config._isAuthRetry && !config.skipAuth) {
-                        const refreshed = await this.refreshAccessToken('response-401');
-                        if (refreshed) {
+                    if (response.status === 401 &&
+                        !config._isAuthRetry &&
+                        usesSessionAuth &&
+                        isOriginalSession()) {
+                        let refreshed = newerRequestToken();
+                        if (!refreshed) {
+                            if (domain.aborted)
+                                throw createCancelledError();
+                            refreshed = await awaitRequestSignal(this.refreshAccessToken('response-401'), domain);
+                        }
+                        refreshed || (refreshed = newerRequestToken());
+                        if (refreshed && isOriginalSession()) {
                             // `deduplicate: false` is REQUIRED on the retry. This re-issue runs
                             // while the ORIGINAL request is still in-flight under its dedupe
                             // key; the refreshed token is
@@ -693,11 +757,19 @@ export class HttpService {
                                 retry: false,
                                 deduplicate: false,
                                 bypassQueue: true,
+                                // The original caller's signal may be aborted while another
+                                // deduplicated caller still owns this shared request.
+                                signal: domain,
                             });
                         }
                         // Refresh failed or no token — clear tokens
-                        this.tokenStore.clearTokens();
-                        this.notifyTokenChange();
+                        if (isOriginalSession()) {
+                            if (this.tokenStore.getAccessToken())
+                                this.sessionEpoch += 1;
+                            this.tokenStore.clearTokens();
+                            selfClearedEpoch = this.sessionEpoch;
+                            this.notifyTokenChange();
+                        }
                     }
                     // Read the error body (may be absent, non-JSON, empty or malformed).
                     // Anything unreadable leaves `errorBody` undefined and degrades to the
@@ -784,6 +856,9 @@ export class HttpService {
                     const text = await response.text();
                     responseData = text || null;
                 }
+                if (usesSessionAuth && !isOriginalSession()) {
+                    throw new OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+                }
                 const duration = Date.now() - startTime;
                 this.updateMetrics(true, duration);
                 this.config.onRequestEnd?.(url, method, duration, true);
@@ -792,6 +867,21 @@ export class HttpService {
             catch (error) {
                 const duration = Date.now() - startTime;
                 this.updateMetrics(false, duration);
+                // A body reader can reject or finish parsing an error after the viewer
+                // changed. Do not surface that previous viewer's error or callbacks.
+                // An explicit abort/timeout retains its existing classification.
+                const providerToken = selfClearedEpoch !== null ? this.accessTokenProvider?.() : null;
+                const originalClearStillCurrent = selfClearedEpoch !== null &&
+                    selfClearedEpoch === this.sessionEpoch &&
+                    this.tokenStore.getAccessToken() === null &&
+                    (!providerToken || sameTokenSession(contextToken, providerToken));
+                if (usesSessionAuth &&
+                    !originalClearStillCurrent &&
+                    !isOriginalSession() &&
+                    !isAbortLike(error) &&
+                    !controller.signal.aborted) {
+                    throw new OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+                }
                 this.config.onRequestEnd?.(url, method, duration, false);
                 this.config.onRequestError?.(url, method, error instanceof Error ? error : new Error(String(error)));
                 // An abort is the one failure whose CAUSE the error cannot carry on its
@@ -883,6 +973,9 @@ export class HttpService {
                 disposeCallerLink?.();
             }
         }
+        if (usesSessionAuth && !isOriginalSession()) {
+            throw new OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+        }
         // Cache the result if caching is enabled
         if (cache && cacheKey && lease.valid && result) {
             this.cache.set(cacheKey, result, cacheTTL);
@@ -1046,7 +1139,7 @@ export class HttpService {
      * in `clearCacheEntry`.
      */
     generateCacheKey(method, url, data) {
-        return `${this.generateBaseCacheKey(method, url, data)}${HttpService.CACHE_IDENTITY_DELIM}${this.computeIdentityTag()}`;
+        return `${this.generateBaseCacheKey(method, url, data)}${HttpService.CACHE_IDENTITY_DELIM}${this.computeIdentityTag()} epoch=${this.sessionEpoch}`;
     }
     /**
      * Build the identity-agnostic portion of a cache key (`method:url[:data]`).
@@ -1170,6 +1263,7 @@ export class HttpService {
             // on the way out would discard the flag it just set.
             this.lastRefreshWasRateLimited = false;
             const epoch = this.sessionEpoch;
+            const tokenAtStart = this.tokenStore.getAccessToken();
             this.tokenRefreshPromise = this.authRefreshHandler(reason)
                 .then((newToken) => {
                 if (epoch !== this.sessionEpoch) {
@@ -1182,6 +1276,12 @@ export class HttpService {
                     this.logger.debug('Discarded a token refresh that outlived its session');
                     return null;
                 }
+                const installed = this.tokenStore.getAccessToken();
+                if (installed !== tokenAtStart && installed !== newToken) {
+                    // Another operation installed a token while this refresh was in
+                    // flight. Never overwrite it with this older completion.
+                    return installed && sameTokenSession(tokenAtStart, installed) ? installed : null;
+                }
                 if (!newToken) {
                     this.lastRefreshFailureAt = Date.now();
                     return null;
@@ -1479,7 +1579,7 @@ export class HttpService {
                 assertCurrent();
             }
             catch (error) {
-                await response.body?.cancel();
+                await discardResponseBody(response);
                 throw error;
             }
             const replayable = Boolean(config.bodyFactory) || body === undefined || typeof body === 'string';
@@ -1493,18 +1593,18 @@ export class HttpService {
                     refreshed = await awaitRequestSignal(this.refreshAccessToken('response-401'), config.signal);
                 }
                 catch (error) {
-                    void response.body?.cancel().catch(() => undefined);
+                    void discardResponseBody(response);
                     throw error;
                 }
                 try {
                     assertCurrent();
                 }
                 catch (error) {
-                    await response.body?.cancel();
+                    await discardResponseBody(response);
                     throw error;
                 }
                 if (refreshed) {
-                    await response.body?.cancel();
+                    await discardResponseBody(response);
                     if (config.signal?.aborted)
                         throw createCancelledError();
                     return this.requestResponseAttempt(config, fullUrl, `Bearer ${refreshed}`, true, epoch, contextToken);
@@ -1670,6 +1770,7 @@ export class HttpService {
     peekCachedGet(url, params) {
         if (this.cacheDisabled)
             return null;
+        this.syncAccessTokenFromProvider();
         return this.cache.get(this.generateCacheKey('GET', url, params));
     }
     clearCache() {

package/dist/esm/shared/utils/errorUtils.js

@@ -46,6 +46,8 @@ export const getErrorStatus = (error) => {
         return err.statusCode;
     return undefined;
 };
+/** A locally superseded request is not an unauthorized response from the server. */
+export const isSessionChangedError = (error) => !!error && typeof error === 'object' && 'code' in error && error.code === 'AUTH_SESSION_CHANGED';
 /**
  * Extracts the error message from an error object.
  *
@@ -98,7 +100,7 @@ export const isAlreadyRegisteredError = (error) => {
  * @returns true if the error is a 401 Unauthorized
  */
 export const isUnauthorizedError = (error) => {
-    return getErrorStatus(error) === HttpStatus.UNAUTHORIZED;
+    return !isSessionChangedError(error) && getErrorStatus(error) === HttpStatus.UNAUTHORIZED;
 };
 /**
  * Check if an error is a forbidden error (HTTP 403).

package/dist/esm/utils/asyncUtils.js

@@ -2,6 +2,7 @@
  * Retry with exponential backoff and jitter — the policy `HttpService` uses.
  */
 import { ErrorCodes, isCancelledError } from './errorUtils.js';
+import { isSessionChangedError } from '../shared/utils/errorUtils.js';
 /**
  * Whether an error came from a request hitting its own timeout.
  *
@@ -99,6 +100,11 @@ export async function retryAsync(operation, maxRetriesOrOptions = 3, baseDelayAr
             if (isCancelledError(error)) {
                 break;
             }
+            // A changed authentication context is a cancellation of this work, even
+            // if the caller's custom predicate would retry ordinary 401 responses.
+            if (isSessionChangedError(error)) {
+                break;
+            }
             if (!retryOnTimeout && isTimeoutError(error)) {
                 break;
             }

package/dist/esm/utils/authHelpers.js

@@ -2,6 +2,7 @@
  * Authentication helper utilities for common token validation
  * and authentication error handling patterns.
  */
+import { isSessionChangedError } from '../shared/utils/errorUtils.js';
 /**
  * Error thrown when session sync is required
  */
@@ -54,6 +55,8 @@ export async function ensureValidToken(oxyServices, _activeSessionId, syncSessio
  * Checks if an error is an authentication error (401 or auth-related message)
  */
 export function isAuthenticationError(error) {
+    if (isSessionChangedError(error))
+        return false;
     if (!error || typeof error !== 'object') {
         return false;
     }

package/dist/types/shared/utils/errorUtils.d.ts

@@ -29,6 +29,8 @@ export declare const HttpStatus: {
  * @returns The status code if found, undefined otherwise
  */
 export declare const getErrorStatus: (error: unknown) => number | undefined;
+/** A locally superseded request is not an unauthorized response from the server. */
+export declare const isSessionChangedError: (error: unknown) => boolean;
 /**
  * Extracts the error message from an error object.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.9.0",
+  "version": "7.9.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/HttpService.ts

@@ -88,6 +88,17 @@ function sameTokenSession(left: string | null, right: string | null): boolean {
   ].every((key) => (a[key] === undefined || typeof a[key] === 'string') && a[key] === b[key]);
 }
 
+/** Discard an unused body even when a platform's stream shim lacks cancel. */
+function discardResponseBody(response: Response): Promise<void> {
+  try {
+    const body = response.body;
+    if (typeof body?.cancel !== 'function') return Promise.resolve();
+    return Promise.resolve(body.cancel()).catch(() => {});
+  } catch {
+    return Promise.resolve();
+  }
+}
+
 /** A trusted platform transport, for example Expo's streaming fetch. */
 export type ResponseTransport = (input: string, init: RequestInit) => Promise<Response>;
 
@@ -695,6 +706,13 @@ export class HttpService {
    * {@link ResponsePayload}, which makes reading the envelope a compile error.
    */
   async request<T = unknown>(config: RequestConfig): Promise<ResponsePayload<T>> {
+    if (config.signal?.aborted) throw createCancelledError('Request cancelled before it was sent');
+    // The provider can change independently of the last request. Synchronize
+    // before deriving the cache and deduplication identity, including hits.
+    const explicitAuthorization = Object.keys(config.headers ?? {}).some(
+      (key) => key.toLowerCase() === 'authorization',
+    );
+    if (!config.skipAuth && !explicitAuthorization) this.syncAccessTokenFromProvider();
     // Per-call authority is not represented by the instance's session cache
     // key. Never share or retain responses authenticated by explicit headers.
     if (
@@ -725,7 +743,9 @@ export class HttpService {
         valid: true,
       });
     }
-    const key = this.generateCacheKey(config.method, config.url, config.data || config.params);
+    const key =
+      this.generateCacheKey(config.method, config.url, config.data || config.params) +
+      (config.skipAuth ? ' auth=none' : '');
     let lease = this.readLeases.get(key);
     if (!lease) {
       lease = { key, id: ++this.nextReadLeaseId, valid: true, readers: 0 };
@@ -768,6 +788,7 @@ export class HttpService {
     // overrides any per-request `cache:true`: nothing is read from nor written
     // to the response cache. Request deduplication below is unaffected.
     const cache = cacheRequested && !this.cacheDisabled;
+    const cacheSessionEpoch = this.sessionEpoch;
 
     // Generate cache key (optimized for large objects)
     const cacheKey = cache ? lease.key : null;
@@ -795,7 +816,37 @@ export class HttpService {
     // and skip the near-expiry preflight — see RequestOptions.skipAuth. The
     // 401 retry re-enters request() with a fresh config, so it re-resolves
     // this here with the refreshed token.
-    const authHeader = config.skipAuth ? null : await this.getAuthHeader();
+    const explicitAuth = Object.keys(config.headers ?? {}).some(
+      (key) => key.toLowerCase() === 'authorization',
+    );
+    const usesSessionAuth = !config.skipAuth && !explicitAuth;
+    const contextToken = usesSessionAuth ? this.syncAccessTokenFromProvider() : null;
+    const contextEpoch = this.sessionEpoch;
+    const authHeader = usesSessionAuth
+      ? await awaitRequestSignal(this.getAuthHeader(), signal)
+      : null;
+    const isOriginalSession = () =>
+      this.sessionEpoch === contextEpoch &&
+      sameTokenSession(contextToken, this.syncAccessTokenFromProvider());
+    const newerRequestToken = () => {
+      if (!contextToken || !authHeader?.startsWith('Bearer ')) return null;
+      const requestToken = authHeader.slice('Bearer '.length);
+      const current = this.syncAccessTokenFromProvider();
+      return current && current !== requestToken && sameTokenSession(requestToken, current)
+        ? current
+        : null;
+    };
+    // The provider can change between cache-key selection and auth preflight.
+    // Refuse to attach a response to a lease belonging to another identity.
+    if (
+      usesSessionAuth &&
+      (!isOriginalSession() ||
+        (lease.key &&
+          (cacheSessionEpoch !== this.sessionEpoch ||
+            lease.key !== this.generateCacheKey(method, url, data || params))))
+    ) {
+      throw new OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+    }
     // Never awaited: the PoP is a hint, and waiting on its trace fetch put up
     // to a second in front of requests.
     const edgeRegionHeader = peekBrowserEdgeRegionHeader();
@@ -820,6 +871,9 @@ export class HttpService {
       if (domain.aborted) {
         throw createCancelledError('Request cancelled');
       }
+      if (usesSessionAuth && !isOriginalSession()) {
+        throw new OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+      }
 
       /**
        * Whether OUR timer fired, so a timeout can be told apart from a
@@ -828,6 +882,7 @@ export class HttpService {
        * an abandoned request as a transient failure.
        */
       let timedOut = false;
+      let selfClearedEpoch: number | null = null;
 
       // This attempt's controller carries its own timeout and inherits the
       // call-wide abort domain. Declared OUTSIDE the `try` so the `finally`
@@ -955,14 +1010,29 @@ export class HttpService {
         // it, including on every throw between here and there.
         if (timeoutId) clearTimeout(timeoutId);
 
+        if (usesSessionAuth && !isOriginalSession()) {
+          void discardResponseBody(response);
+          throw new OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+        }
+
         // Handle response
         if (!response.ok) {
           // On 401, delegate to the installed auth refresh handler and retry
           // once before giving up. HttpService deliberately does not know any
           // session routes; the refresh handler owns session rotation.
-          if (response.status === 401 && !config._isAuthRetry && !config.skipAuth) {
-            const refreshed = await this.refreshAccessToken('response-401');
-            if (refreshed) {
+          if (
+            response.status === 401 &&
+            !config._isAuthRetry &&
+            usesSessionAuth &&
+            isOriginalSession()
+          ) {
+            let refreshed = newerRequestToken();
+            if (!refreshed) {
+              if (domain.aborted) throw createCancelledError();
+              refreshed = await awaitRequestSignal(this.refreshAccessToken('response-401'), domain);
+            }
+            refreshed ||= newerRequestToken();
+            if (refreshed && isOriginalSession()) {
               // `deduplicate: false` is REQUIRED on the retry. This re-issue runs
               // while the ORIGINAL request is still in-flight under its dedupe
               // key; the refreshed token is
@@ -981,11 +1051,18 @@ export class HttpService {
                 retry: false,
                 deduplicate: false,
                 bypassQueue: true,
+                // The original caller's signal may be aborted while another
+                // deduplicated caller still owns this shared request.
+                signal: domain,
               });
             }
             // Refresh failed or no token — clear tokens
-            this.tokenStore.clearTokens();
-            this.notifyTokenChange();
+            if (isOriginalSession()) {
+              if (this.tokenStore.getAccessToken()) this.sessionEpoch += 1;
+              this.tokenStore.clearTokens();
+              selfClearedEpoch = this.sessionEpoch;
+              this.notifyTokenChange();
+            }
           }
 
           // Read the error body (may be absent, non-JSON, empty or malformed).
@@ -1079,6 +1156,9 @@ export class HttpService {
           responseData = text || null;
         }
 
+        if (usesSessionAuth && !isOriginalSession()) {
+          throw new OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+        }
         const duration = Date.now() - startTime;
         this.updateMetrics(true, duration);
         this.config.onRequestEnd?.(url, method, duration, true);
@@ -1087,6 +1167,24 @@ export class HttpService {
       } catch (error: unknown) {
         const duration = Date.now() - startTime;
         this.updateMetrics(false, duration);
+        // A body reader can reject or finish parsing an error after the viewer
+        // changed. Do not surface that previous viewer's error or callbacks.
+        // An explicit abort/timeout retains its existing classification.
+        const providerToken = selfClearedEpoch !== null ? this.accessTokenProvider?.() : null;
+        const originalClearStillCurrent =
+          selfClearedEpoch !== null &&
+          selfClearedEpoch === this.sessionEpoch &&
+          this.tokenStore.getAccessToken() === null &&
+          (!providerToken || sameTokenSession(contextToken, providerToken));
+        if (
+          usesSessionAuth &&
+          !originalClearStillCurrent &&
+          !isOriginalSession() &&
+          !isAbortLike(error) &&
+          !controller.signal.aborted
+        ) {
+          throw new OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+        }
         this.config.onRequestEnd?.(url, method, duration, false);
         this.config.onRequestError?.(
           url,
@@ -1188,6 +1286,10 @@ export class HttpService {
       }
     }
 
+    if (usesSessionAuth && !isOriginalSession()) {
+      throw new OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+    }
+
     // Cache the result if caching is enabled
     if (cache && cacheKey && lease.valid && result) {
       this.cache.set(cacheKey, result, cacheTTL);
@@ -1382,7 +1484,7 @@ export class HttpService {
    * in `clearCacheEntry`.
    */
   private generateCacheKey(method: string, url: string, data?: unknown): string {
-    return `${this.generateBaseCacheKey(method, url, data)}${HttpService.CACHE_IDENTITY_DELIM}${this.computeIdentityTag()}`;
+    return `${this.generateBaseCacheKey(method, url, data)}${HttpService.CACHE_IDENTITY_DELIM}${this.computeIdentityTag()} epoch=${this.sessionEpoch}`;
   }
 
   /**
@@ -1516,6 +1618,7 @@ export class HttpService {
       // on the way out would discard the flag it just set.
       this.lastRefreshWasRateLimited = false;
       const epoch = this.sessionEpoch;
+      const tokenAtStart = this.tokenStore.getAccessToken();
       this.tokenRefreshPromise = this.authRefreshHandler(reason)
         .then((newToken) => {
           if (epoch !== this.sessionEpoch) {
@@ -1528,6 +1631,12 @@ export class HttpService {
             this.logger.debug('Discarded a token refresh that outlived its session');
             return null;
           }
+          const installed = this.tokenStore.getAccessToken();
+          if (installed !== tokenAtStart && installed !== newToken) {
+            // Another operation installed a token while this refresh was in
+            // flight. Never overwrite it with this older completion.
+            return installed && sameTokenSession(tokenAtStart, installed) ? installed : null;
+          }
           if (!newToken) {
             this.lastRefreshFailureAt = Date.now();
             return null;
@@ -1865,7 +1974,7 @@ export class HttpService {
       try {
         assertCurrent();
       } catch (error) {
-        await response.body?.cancel();
+        await discardResponseBody(response);
         throw error;
       }
       const replayable =
@@ -1884,17 +1993,17 @@ export class HttpService {
             config.signal,
           );
         } catch (error) {
-          void response.body?.cancel().catch(() => undefined);
+          void discardResponseBody(response);
           throw error;
         }
         try {
           assertCurrent();
         } catch (error) {
-          await response.body?.cancel();
+          await discardResponseBody(response);
           throw error;
         }
         if (refreshed) {
-          await response.body?.cancel();
+          await discardResponseBody(response);
           if (config.signal?.aborted) throw createCancelledError();
           return this.requestResponseAttempt(
             config,
@@ -2099,6 +2208,7 @@ export class HttpService {
    */
   peekCachedGet<T>(url: string, params?: Record<string, unknown>): T | null {
     if (this.cacheDisabled) return null;
+    this.syncAccessTokenFromProvider();
     return this.cache.get(this.generateCacheKey('GET', url, params)) as T | null;
   }
 

package/src/shared/utils/errorUtils.ts

@@ -50,6 +50,10 @@ export const getErrorStatus = (error: unknown): number | undefined => {
   return undefined;
 };
 
+/** A locally superseded request is not an unauthorized response from the server. */
+export const isSessionChangedError = (error: unknown): boolean =>
+  !!error && typeof error === 'object' && 'code' in error && error.code === 'AUTH_SESSION_CHANGED';
+
 /**
  * Extracts the error message from an error object.
  *
@@ -103,7 +107,7 @@ export const isAlreadyRegisteredError = (error: unknown): boolean => {
  * @returns true if the error is a 401 Unauthorized
  */
 export const isUnauthorizedError = (error: unknown): boolean => {
-  return getErrorStatus(error) === HttpStatus.UNAUTHORIZED;
+  return !isSessionChangedError(error) && getErrorStatus(error) === HttpStatus.UNAUTHORIZED;
 };
 
 /**

package/src/utils/asyncUtils.ts

@@ -3,6 +3,7 @@
  */
 
 import { ErrorCodes, isCancelledError } from './errorUtils';
+import { isSessionChangedError } from '../shared/utils/errorUtils';
 
 /** Options for {@link retryAsync}. */
 export interface RetryOptions {
@@ -146,6 +147,12 @@ export async function retryAsync<T>(
         break;
       }
 
+      // A changed authentication context is a cancellation of this work, even
+      // if the caller's custom predicate would retry ordinary 401 responses.
+      if (isSessionChangedError(error)) {
+        break;
+      }
+
       if (!retryOnTimeout && isTimeoutError(error)) {
         break;
       }

package/src/utils/authHelpers.ts

@@ -4,6 +4,7 @@
  */
 
 import type { OxyServices } from '../OxyServices';
+import { isSessionChangedError } from '../shared/utils/errorUtils';
 
 /**
  * Error thrown when session sync is required
@@ -80,6 +81,7 @@ export interface HandleApiErrorOptions {
  * Checks if an error is an authentication error (401 or auth-related message)
  */
 export function isAuthenticationError(error: unknown): boolean {
+  if (isSessionChangedError(error)) return false;
   if (!error || typeof error !== 'object') {
     return false;
   }