@oxy.so/core 1.9.0 → 1.10.0

package/dist/esm/HttpService.js

@@ -17,18 +17,12 @@ import { RequestDeduplicator, RequestQueue, SimpleLogger } from './utils/request
 import { retryAsync } from './utils/asyncUtils.js';
 import { createCancelledError, ErrorCodes, handleHttpError, parseHttpErrorBody } from './utils/errorUtils.js';
 import { jwtDecode } from 'jwt-decode';
-import { isNative, getPlatformOS } from './utils/platform.js';
 import { isReactNative } from '@oxy.so/protocol';
 import { computeIdentityTag, fnv1a32 } from './utils/cacheKey.js';
 import { redactUrlQuery } from './utils/redactUrl.js';
 import { OxyAuthenticationError } from './OxyServices.errors.js';
 import { getBrowserEdgeRegionHeader } from './utils/edgeRegion.js';
 import { getBrowserActivityIdHeader } from './utils/activityId.js';
-/**
- * Check if we're running in a native app environment (React Native, not web)
- * This is used to determine CSRF handling mode
- */
-const isNativeApp = isNative();
 /**
  * Default per-request timeout (ms) when neither the call site nor
  * {@link OxyConfig.requestTimeout} overrides it. Kept tight so a stalled
@@ -36,24 +30,6 @@ const isNativeApp = isNative();
  * request queue.
  */
 const DEFAULT_REQUEST_TIMEOUT_MS = 5000;
-/**
- * Timeout (ms) for the dedicated `GET /csrf-token` fetch. Independent of the
- * regular request timeout: this is a small, fast, unauthenticated call and
- * should never inherit a longer per-request budget.
- */
-const CSRF_FETCH_TIMEOUT_MS = 5000;
-/**
- * Number of attempts for fetching a CSRF token before giving up. The first
- * failure is usually a cold edge/cookie race; a single retry recovers it
- * without masking a genuinely broken `/csrf-token` route.
- */
-const CSRF_FETCH_MAX_ATTEMPTS = 2;
-/**
- * Backoff (ms) between CSRF-token fetch attempts. Short by design — a CSRF
- * fetch sits in the critical path of a state-changing request, so the retry
- * must add minimal latency.
- */
-const CSRF_FETCH_RETRY_DELAY_MS = 500;
 /**
  * Cooldown (ms) applied after a failed access-token refresh before another
  * refresh is attempted while the CURRENT token is still valid (a proactive,
@@ -113,6 +89,24 @@ const RATE_LIMITED_REFRESH_COOLDOWN_MS = 60000;
  * expired so the request carries a fresh bearer rather than racing the clock.
  */
 const TOKEN_REFRESH_LEAD_SECONDS = 60;
+/**
+ * Whether `token` is a JWT that is still valid but already inside the refresh
+ * lead window. `false` for an expired, opaque or no-`exp` token.
+ */
+function isInsideRefreshLeadWindow(token) {
+    try {
+        const decoded = jwtDecode(token);
+        if (typeof decoded.exp !== 'number') {
+            return false;
+        }
+        const now = Math.floor(Date.now() / 1000);
+        // `<=`: the proactive scheduler fires at exactly `exp - lead`.
+        return decoded.exp > now && decoded.exp - now <= TOKEN_REFRESH_LEAD_SECONDS;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Soft ceiling on the number of live entries in the identity-scoped GET
  * response cache. Crossing it does NOT evict anything (the {@link TTLCache}
@@ -138,8 +132,6 @@ const CACHE_SIZE_WARNING_THROTTLE_MS = 60000;
 class TokenStore {
     constructor() {
         this.accessToken = null;
-        this.csrfToken = null;
-        this.csrfTokenFetchPromise = null;
     }
     setTokens(accessToken) {
         this.accessToken = accessToken;
@@ -153,22 +145,6 @@ class TokenStore {
     hasAccessToken() {
         return !!this.accessToken;
     }
-    setCsrfToken(token) {
-        this.csrfToken = token;
-    }
-    getCsrfToken() {
-        return this.csrfToken;
-    }
-    setCsrfTokenFetchPromise(promise) {
-        this.csrfTokenFetchPromise = promise;
-    }
-    getCsrfTokenFetchPromise() {
-        return this.csrfTokenFetchPromise;
-    }
-    clearCsrfToken() {
-        this.csrfToken = null;
-        this.csrfTokenFetchPromise = null;
-    }
 }
 /**
  * Propagate `parent`'s abort to `child`, returning a disposer.
@@ -234,9 +210,45 @@ export class HttpService {
          * it, and there is exactly one timestamp to reason about.
          */
         this.lastRefreshWasRateLimited = false;
+        /**
+         * The access token the last SUCCESSFUL refresh handed back while it was still
+         * inside the refresh lead window, or `null`.
+         *
+         * The device mint (`POST /session/device/token`) answers with the session's
+         * STORED access token for as long as that token has not expired — it only
+         * mints a new one once the old one is past `exp`. A client that re-mints
+         * {@link TOKEN_REFRESH_LEAD_SECONDS} before `exp` therefore gets the SAME
+         * token back, and because that counts as a success (no cooldown), every
+         * following request re-ran the preflight and minted again: one mint per
+         * request for the last minute of every token, which exhausted the server's
+         * 30/min mint budget. The 429 that followed imposed a 60s cooldown that
+         * straddled the token's real expiry, so the next request went out with no
+         * bearer, drew a 401, found the refresh cooling down, and signed the user out.
+         *
+         * Remembering the answer ends that: while the current token IS this value and
+         * has not yet expired, the server has already said it has nothing fresher, so
+         * the preflight sends the still-valid token instead of asking again. Once the
+         * token crosses `exp` the preflight asks once more and the server rotates.
+         */
+        this.noFresherTokenThan = null;
         this.authRefreshHandler = null;
         this.accessTokenProvider = null;
         this.deviceSecretMintInFlight = null;
+        /**
+         * Bumped by every {@link endSession}. A re-mint captures it before its first
+         * await and plants nothing if it moved: a refresh that was already in flight
+         * when the user signed out would otherwise complete a moment later and put a
+         * bearer — and through the token listeners, the account — back.
+         */
+        this.sessionEpoch = 0;
+        /**
+         * Set by {@link endSession}, cleared by the next {@link setTokens}. Read by the
+         * native shared-keychain re-mint arm: after a sign-out a 401 is the expected
+         * answer, not a cue to sign back in with the identity key. The device-secret
+         * arm is NOT gated on it — minting from a credential the store still holds is
+         * how a signed-out tab joins a sign-in made in another tab.
+         */
+        this.sessionEnded = false;
         /**
          * Epoch (ms) before which a cache-size telemetry warning must not be
          * re-emitted. Throttles the {@link CACHE_SOFT_MAX_ENTRIES} warning to at most
@@ -390,14 +402,9 @@ export class HttpService {
         // it before enqueue means auth-blocked requests hold NO slot while the shared
         // mint runs. `skipAuth` requests (the body-authenticated mint) send NO bearer
         // and skip the near-expiry preflight — see RequestOptions.skipAuth. The
-        // 401/CSRF retry re-enters request() with a fresh config, so it re-resolves
-        // these here with the refreshed token / cleared CSRF.
-        const isStateChangingMethod = ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method);
+        // 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();
-        // CSRF protects cookie-authenticated browser writes. Bearer-authenticated SDK
-        // clients are not vulnerable to ambient-cookie CSRF, and linked app APIs
-        // should not need to implement a duplicate `/csrf-token` route.
-        const csrfToken = isStateChangingMethod && !authHeader ? await this.fetchCsrfToken() : null;
         const edgeRegionHeader = await getBrowserEdgeRegionHeader();
         const activityIdHeader = getBrowserActivityIdHeader();
         // A request the caller has ALREADY abandoned takes no queue slot and makes
@@ -468,29 +475,6 @@ export class HttpService {
                 if (authHeader) {
                     headers['Authorization'] = authHeader;
                 }
-                // Add CSRF token header for state-changing requests
-                if (csrfToken) {
-                    headers['X-CSRF-Token'] = csrfToken;
-                }
-                // Add native app header for React Native (required for CSRF validation)
-                // Native apps can't persist cookies like browsers, so the server uses
-                // header-only CSRF validation when this header is present
-                if (isNativeApp && isStateChangingMethod) {
-                    headers['X-Native-App'] = 'true';
-                }
-                // Debug logging for CSRF issues, routed through SimpleLogger so it only
-                // fires when consumers opt in via `enableLogging`.
-                if (isStateChangingMethod) {
-                    this.logger.debug('CSRF Debug:', {
-                        url,
-                        method,
-                        isNativeApp,
-                        platformOS: getPlatformOS(),
-                        hasCsrfToken: !!csrfToken,
-                        csrfTokenLength: csrfToken?.length,
-                        hasNativeAppHeader: headers['X-Native-App'] === 'true',
-                    });
-                }
                 // Merge custom headers if provided
                 if (config.headers) {
                     Object.entries(config.headers).forEach(([key, value]) => {
@@ -542,34 +526,19 @@ export class HttpService {
                     if (response.status === 401 && !config._isAuthRetry && !config.skipAuth) {
                         const refreshed = await this.refreshAccessToken('response-401');
                         if (refreshed) {
-                            // `deduplicate: false` is REQUIRED on the retry (mirrors the 403
-                            // CSRF retry below). This re-issue runs while the ORIGINAL request
-                            // is still in-flight under its dedupe key; the refreshed token is
+                            // `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
                             // for the SAME user, so the identity-scoped key is UNCHANGED — a
                             // deduplicated retry would resolve to the still-pending original
                             // and await itself (deadlock). Opting the retry out of dedupe makes
                             // it a fresh request.
                             return this.request({ ...config, _isAuthRetry: true, retry: false, deduplicate: false });
                         }
-                        // Refresh failed or no token — clear tokens and stale CSRF
+                        // Refresh failed or no token — clear tokens
                         this.tokenStore.clearTokens();
-                        this.tokenStore.clearCsrfToken();
                         this.notifyTokenChange();
                     }
-                    // On 403 with CSRF error, clear cached token and retry once
-                    if (response.status === 403 && !config._isCsrfRetry) {
-                        try {
-                            const clonedResponse = response.clone();
-                            const errBody = await clonedResponse.json();
-                            if (errBody?.code === 'CSRF_TOKEN_INVALID' || errBody?.code === 'CSRF_TOKEN_MISSING') {
-                                this.tokenStore.clearCsrfToken();
-                                return this.request({ ...config, _isCsrfRetry: true, retry: false, deduplicate: false });
-                            }
-                        }
-                        catch {
-                            // Failed to parse error body — not a CSRF error
-                        }
-                    }
                     // Read the error body (may be absent, non-JSON, empty or malformed).
                     // Anything unreadable leaves `errorBody` undefined and degrades to the
                     // status-based message — an error path that throws its own error is
@@ -943,75 +912,6 @@ export class HttpService {
             return false;
         }
     }
-    /**
-     * Fetch CSRF token from server (with deduplication)
-     * Required for state-changing requests (POST, PUT, PATCH, DELETE)
-     */
-    async fetchCsrfToken() {
-        // Return cached token if available
-        const cachedToken = this.tokenStore.getCsrfToken();
-        if (cachedToken) {
-            this.logger.debug('Using cached CSRF token');
-            return cachedToken;
-        }
-        // Deduplicate concurrent CSRF token fetches
-        const existingPromise = this.tokenStore.getCsrfTokenFetchPromise();
-        if (existingPromise) {
-            this.logger.debug('Waiting for existing CSRF fetch');
-            return existingPromise;
-        }
-        const fetchPromise = (async () => {
-            for (let attempt = 1; attempt <= CSRF_FETCH_MAX_ATTEMPTS; attempt++) {
-                try {
-                    this.logger.debug('Fetching CSRF token from:', `${this.baseURL}/csrf-token`, `(attempt ${attempt})`);
-                    // Use AbortController for timeout (more compatible than AbortSignal.timeout)
-                    const controller = new AbortController();
-                    const timeoutId = setTimeout(() => controller.abort(), CSRF_FETCH_TIMEOUT_MS);
-                    const response = await fetch(`${this.baseURL}/csrf-token`, {
-                        method: 'GET',
-                        headers: { 'Accept': 'application/json' },
-                        credentials: 'include', // Required to receive and send cookies
-                        signal: controller.signal,
-                    });
-                    clearTimeout(timeoutId);
-                    this.logger.debug('CSRF fetch response:', response.status, response.ok);
-                    if (response.ok) {
-                        const data = await response.json();
-                        const token = data.csrfToken || null;
-                        this.logger.debug('CSRF response data:', {
-                            hasCsrfToken: typeof token === 'string' && token.length > 0,
-                            csrfTokenLength: token?.length,
-                        });
-                        this.tokenStore.setCsrfToken(token);
-                        this.logger.debug('CSRF token fetched');
-                        return token;
-                    }
-                    // Also check response header for CSRF token
-                    const headerToken = response.headers.get('X-CSRF-Token');
-                    if (headerToken) {
-                        this.tokenStore.setCsrfToken(headerToken);
-                        this.logger.debug('CSRF token from header');
-                        return headerToken;
-                    }
-                    this.logger.debug('CSRF fetch failed with status:', response.status);
-                    this.logger.warn('Failed to fetch CSRF token:', response.status);
-                }
-                catch (error) {
-                    this.logger.debug('CSRF fetch error:', error);
-                    this.logger.warn('CSRF token fetch error:', error);
-                }
-                // Brief backoff before the next attempt.
-                if (attempt < CSRF_FETCH_MAX_ATTEMPTS) {
-                    await new Promise(resolve => setTimeout(resolve, CSRF_FETCH_RETRY_DELAY_MS));
-                }
-            }
-            return null;
-        })().finally(() => {
-            this.tokenStore.setCsrfTokenFetchPromise(null);
-        });
-        this.tokenStore.setCsrfTokenFetchPromise(fetchPromise);
-        return fetchPromise;
-    }
     /**
      * Get auth header with automatic token refresh
      */
@@ -1025,6 +925,12 @@ export class HttpService {
             const currentTime = Math.floor(Date.now() / 1000);
             // If the token expires within the refresh lead window, refresh it.
             if (decoded.exp && decoded.exp - currentTime < TOKEN_REFRESH_LEAD_SECONDS) {
+                // The server already answered this token's refresh with this very token:
+                // it has nothing fresher until `exp`. Use it rather than asking again
+                // (see `noFresherTokenThan`).
+                if (decoded.exp > currentTime && accessToken === this.noFresherTokenThan) {
+                    return `Bearer ${accessToken}`;
+                }
                 const refreshed = await this.refreshAccessToken('preflight');
                 if (refreshed)
                     return `Bearer ${refreshed}`;
@@ -1067,16 +973,26 @@ export class HttpService {
             // by calling `noteRefreshRateLimited()` from INSIDE this call, so clearing
             // on the way out would discard the flag it just set.
             this.lastRefreshWasRateLimited = false;
+            const epoch = this.sessionEpoch;
             this.tokenRefreshPromise = this.authRefreshHandler(reason)
                 .then((newToken) => {
+                if (epoch !== this.sessionEpoch) {
+                    // The session ended while this re-mint was in flight. Not a failure
+                    // (no cooldown), and nothing to plant.
+                    this.logger.debug('Discarded a token refresh that outlived its session');
+                    return null;
+                }
                 if (!newToken) {
                     this.lastRefreshFailureAt = Date.now();
                     return null;
                 }
+                // A token is planted again, so there is a session again.
+                this.sessionEnded = false;
                 if (this.tokenStore.getAccessToken() !== newToken) {
                     this.tokenStore.setTokens(newToken);
                     this.notifyTokenChange();
                 }
+                this.noFresherTokenThan = isInsideRefreshLeadWindow(newToken) ? newToken : null;
                 // A success clears the failure timestamp so the next refresh is never
                 // throttled by a stale cooldown.
                 this.lastRefreshFailureAt = 0;
@@ -1110,6 +1026,16 @@ export class HttpService {
     noteRefreshRateLimited() {
         this.lastRefreshWasRateLimited = true;
     }
+    /**
+     * Whether the server has already answered a refresh of the CURRENT access
+     * token with that same, still-valid token — i.e. it has nothing fresher to
+     * give until the token's `exp`. The proactive scheduler reads this so it waits
+     * for expiry instead of re-asking at its 1s floor.
+     */
+    isAwaitingCurrentTokenExpiry() {
+        const token = this.tokenStore.getAccessToken();
+        return token !== null && token === this.noFresherTokenThan && isInsideRefreshLeadWindow(token);
+    }
     /**
      * Whether the CURRENT stored access token is already past its `exp`. Drives
      * the shorter post-failure refresh cooldown ({@link EXPIRED_TOKEN_REFRESH_COOLDOWN_MS}):
@@ -1261,7 +1187,6 @@ export class HttpService {
                     return this.requestAuthenticatedResponseAttempt(config, `Bearer ${refreshed}`, true);
                 }
                 this.tokenStore.clearTokens();
-                this.tokenStore.clearCsrfToken();
                 this.notifyTokenChange();
             }
             const duration = Date.now() - startTime;
@@ -1296,9 +1221,34 @@ export class HttpService {
     }
     // Token management
     setTokens(accessToken) {
+        this.sessionEnded = false;
         this.tokenStore.setTokens(accessToken);
         this.notifyTokenChange();
     }
+    /**
+     * End the local session: clear the bearer and abandon every re-mint already
+     * in flight, so none of them can plant a token after the sign-out.
+     *
+     * {@link clearTokens} alone only drops the bearer, which is right for a
+     * mirror (a linked client following its parent) but not for a sign-out: a
+     * refresh started a moment earlier would finish and plant a new one.
+     */
+    endSession() {
+        this.sessionEpoch += 1;
+        this.sessionEnded = true;
+        this.clearTokens();
+    }
+    /**
+     * The current session epoch — see {@link endSession}. A re-mint lane that
+     * plants tokens itself (the device-secret arm) compares it across its awaits.
+     */
+    getSessionEpoch() {
+        return this.sessionEpoch;
+    }
+    /** Whether {@link endSession} ran and no token has been planted since. */
+    hasSessionEnded() {
+        return this.sessionEnded;
+    }
     setAuthRefreshHandler(handler) {
         this.authRefreshHandler = handler;
     }
@@ -1307,7 +1257,6 @@ export class HttpService {
     }
     clearTokens() {
         this.tokenStore.clearTokens();
-        this.tokenStore.clearCsrfToken();
         // Drop the response cache on logout. The cache is identity-scoped, so a
         // different user could never read these entries, but a logged-out client
         // must not keep the previous session's personalized data resident in
@@ -1423,8 +1372,8 @@ export class HttpService {
     }
     // Test-only utility — clears tokens on this instance
     __resetTokensForTests() {
+        this.sessionEnded = false;
         this.tokenStore.clearTokens();
-        this.tokenStore.clearCsrfToken();
     }
 }
 /**

package/dist/esm/OxyServices.base.js

@@ -165,10 +165,12 @@ export class OxyServicesBase {
         this.httpService.setTokens(accessToken);
     }
     /**
-     * Clear stored authentication tokens
+     * Clear stored authentication tokens and end the local session: a re-mint
+     * already in flight plants nothing, and no new one runs until a token is set
+     * again (see `HttpService.endSession`).
      */
     clearTokens() {
-        this.httpService.clearTokens();
+        this.httpService.endSession();
         this._cachedUserId = undefined;
         this._cachedAccessToken = null;
     }

package/dist/esm/boot/sessionColdBoot.js

@@ -202,6 +202,9 @@ export async function runSessionColdBoot(opts) {
                     // Network / 5xx: keep the secret; a later attempt can succeed.
                     logger.debug('device-secret mint failed (transient) — keeping secret', { component: 'sessionColdBoot', method: 'device-secret-mint' });
                     return { kind: 'skip' };
+                case 'session-ended':
+                    // Signed out while the boot was minting; the arm planted nothing.
+                    return { kind: 'skip' };
                 case 'no-secret':
                     return { kind: 'skip' };
             }

package/dist/esm/mixins/OxyServices.user.js

@@ -285,10 +285,7 @@ export function OxyServicesUserMixin(Base) {
          *   `PostHydrationService`) and is unchanged.
          * - **Plain client (browser / React Native with a user session):** when no
          *   service credentials are configured, the chunk is fetched via
-         *   `makeRequest`, which attaches the configured user bearer. oxy-api's CSRF
-         *   middleware skips bearer-authenticated writes, and `makeRequest` only
-         *   fetches a CSRF token for cookie-only (no-bearer) state-changing requests,
-         *   so the user-bearer POST is sent without CSRF and succeeds. Previously
+         *   `makeRequest`, which attaches the configured user bearer. Previously
          *   this method always used the service path, so every client-side caller
          *   silently received `[]` because `getServiceToken()` had no credentials.
          *
@@ -315,7 +312,7 @@ export function OxyServicesUserMixin(Base) {
             }
             // A backend that called configureServiceAuth() uses the bearer-service
             // path; any other caller (browser / RN with a user session) uses the
-            // user-bearer path. See the method doc for why the user path is CSRF-safe.
+            // user-bearer path.
             const useServiceAuth = Boolean(this._serviceApiKey && this._serviceApiSecret);
             // Run chunks concurrently; a single chunk failure must not sink the rest.
             const settled = await Promise.all(chunks.map(async (chunk) => {

package/dist/esm/server/cors.js

@@ -35,7 +35,6 @@ const DEFAULT_ALLOWED_HEADERS = [
     'X-Requested-With',
     'X-Oxy-User-Id',
     'X-Oxy-Internal',
-    'X-CSRF-Token',
     'X-Oxy-Edge-Region',
     'X-Oxy-Activity-Id',
 ];

package/dist/esm/session/refresh.js

@@ -31,6 +31,20 @@ const MIN_SCHEDULE_DELAY_MS = 1000;
  */
 const MIN_FAILURE_BACKOFF_MS = 5000;
 const MAX_FAILURE_BACKOFF_MS = 5 * 60000;
+/**
+ * How long past `exp` to re-mint when a successful refresh handed back a token
+ * that is STILL inside the lead window.
+ *
+ * The device mint returns the session's stored access token until that token
+ * has actually expired, so asking again before `exp` only returns the same
+ * token. Re-arming from expiry in that state computed a negative delay, hit the
+ * {@link MIN_SCHEDULE_DELAY_MS} floor and re-minted once a second for the last
+ * minute of every token — 30+ mints, the server's whole per-minute budget, and
+ * the 429 that followed straddled the real expiry. Waiting until just past
+ * `exp` asks exactly once more, when the server will rotate. The margin covers
+ * the server's strict `exp < now` comparison and a little clock skew.
+ */
+export const REMINT_AFTER_EXPIRY_MS = 2000;
 /**
  * Arm 1 — the device-secret mint, run under the owning client's PROCESS-WIDE
  * single-flight (`httpService.runSingleFlightDeviceSecretMint`).
@@ -57,6 +71,7 @@ export async function refreshDeviceSecretArm(deps) {
     const { oxy, store } = deps;
     const pin = deps.pin ?? null;
     return oxy.httpService.runSingleFlightDeviceSecretMint(async () => {
+        const epoch = oxy.httpService.getSessionEpoch();
         const persisted = await store.load();
         if (!persisted?.deviceId || !persisted?.deviceSecret) {
             return { status: 'no-secret' };
@@ -122,12 +137,26 @@ export async function refreshDeviceSecretArm(deps) {
             expiresAt: mint.expiresAt,
             ...(bound ? { sessionId: bound.sessionId, userId: bound.accountId } : {}),
         };
+        if (oxy.httpService.getSessionEpoch() !== epoch) {
+            // Signed out while minting. The server has rotated the secret, so a store
+            // that still holds the presented one must learn the rotation (the
+            // token-null lane keeps the store so a reload can restore); a store the
+            // sign-out cleared must NOT be refilled. Either way, plant nothing.
+            const current = await store.load();
+            if (current?.deviceId === persisted.deviceId && current.deviceSecret === persisted.deviceSecret) {
+                await store.save(next);
+            }
+            return { status: 'session-ended' };
+        }
         // Persist nextDeviceSecret (read-back-verified) BEFORE planting the token.
         // A failed durable persist must NOT plant.
         const persistedOk = await store.save(next);
         if (!persistedOk) {
             return { status: 'persist-failed' };
         }
+        if (oxy.httpService.getSessionEpoch() !== epoch) {
+            return { status: 'session-ended' };
+        }
         oxy.setTokens(mint.accessToken);
         return {
             status: 'ok',
@@ -165,6 +194,7 @@ export async function refreshPersistedSession(deps) {
     const identity = deps.identity ?? null;
     // The shared keychain is never an identity-bound client's recovery path.
     const allowSharedKeyFallback = identity ? false : (deps.allowSharedKeyFallback ?? isNative());
+    const epoch = oxy.httpService.getSessionEpoch();
     // Resolved per call: a re-established identity session can move the pin, and a
     // replaced/removed local key clears it (in which case arm 1 must NOT mint —
     // an unpinned mint would adopt whatever account the device switched to).
@@ -176,6 +206,8 @@ export async function refreshPersistedSession(deps) {
     switch (arm1.status) {
         case 'ok':
             return arm1.token;
+        case 'session-ended':
+            return null;
         case 'transient':
             logger.debug('Persisted deviceSecret mint failed (transient) — keeping store', { component: 'refresh', method: 'refreshPersistedSession' });
             return null;
@@ -214,10 +246,18 @@ export async function refreshPersistedSession(deps) {
     if (identity) {
         return recoverIdentitySession(oxy, store, identity);
     }
-    if (allowSharedKeyFallback) {
+    // Never after a sign-out: the shared keychain holds an identity KEY, not a
+    // session, and using it here would sign the user straight back in.
+    if (allowSharedKeyFallback && !oxy.httpService.hasSessionEnded()) {
         try {
-            const session = await oxy.signInWithSharedIdentity();
+            // Planted here, not by the sign-in: a sign-out that lands while the
+            // challenge round-trips must win, or the shared keychain signs the user
+            // straight back in.
+            const session = await oxy.signInWithSharedIdentity({ plantTokens: false });
             if (session?.accessToken) {
+                if (oxy.httpService.getSessionEpoch() !== epoch) {
+                    return null;
+                }
                 // Repopulate the fast device-secret lane from the shared-key re-mint.
                 if (session.deviceId && session.deviceSecret) {
                     await store.save({
@@ -229,6 +269,10 @@ export async function refreshPersistedSession(deps) {
                         expiresAt: session.expiresAt,
                     });
                 }
+                if (oxy.httpService.getSessionEpoch() !== epoch) {
+                    return null;
+                }
+                oxy.setTokens(session.accessToken);
                 return session.accessToken;
             }
         }
@@ -326,12 +370,26 @@ export function startTokenRefreshScheduler(oxy) {
         if (expSeconds === null) {
             return;
         }
-        armTimer(expSeconds * 1000 - Date.now() - TOKEN_REFRESH_LEAD_MS);
+        const untilExpiryMs = expSeconds * 1000 - Date.now();
+        // The server already answered this token's refresh with this very token:
+        // asking again before `exp` only gets it back again. Ask just after expiry,
+        // when the server rotates (see REMINT_AFTER_EXPIRY_MS).
+        if (untilExpiryMs > 0 && oxy.httpService.isAwaitingCurrentTokenExpiry?.()) {
+            armTimer(untilExpiryMs + REMINT_AFTER_EXPIRY_MS);
+            return;
+        }
+        armTimer(untilExpiryMs - TOKEN_REFRESH_LEAD_MS);
     };
     const runRefresh = () => {
         // Clear any pending timer up front so an out-of-band trigger (focus) plus
         // a fired timer can never double-run.
         clearTimer();
+        // Another lane (a request-time preflight) already asked, and the server
+        // answered with this same token: re-arm for just past expiry instead.
+        if (oxy.httpService.isAwaitingCurrentTokenExpiry?.()) {
+            scheduleFromExpiry();
+            return;
+        }
         void oxy.httpService.refreshAccessToken('preflight')
             .then((token) => Boolean(token))
             .catch(() => false)
@@ -374,10 +432,16 @@ export function startTokenRefreshScheduler(oxy) {
             schedule();
         }
     };
-    const unsubscribeTokens = oxy.onTokensChanged(() => {
-        if (!disposed) {
-            schedule();
+    // Re-arm only on a token that actually CHANGED. The mint plants the token it
+    // returns even when that is the token already held, and treating the repeat
+    // as new re-armed from an in-lead-window expiry, i.e. at the 1s floor.
+    let lastSeenToken = oxy.getAccessToken();
+    const unsubscribeTokens = oxy.onTokensChanged((token) => {
+        if (disposed || token === lastSeenToken) {
+            return;
         }
+        lastSeenToken = token;
+        schedule();
     });
     let removeFocusListener = null;
     if (typeof document !== 'undefined') {

package/dist/esm/utils/errorUtils.js

@@ -69,7 +69,7 @@ const nonEmptyString = (value) => typeof value === 'string' && value.trim().leng
  * - `{ error: '<CODE>', error_description }` — RFC 6749 §5.2 / RFC 6750 §3, the
  *   OAuth token and userinfo endpoints. `error_description` is the human text
  *   and `error` is the machine code, so both survive.
- * - `{ message, code }` — e.g. the API's CSRF rejections.
+ * - `{ message, code }` — e.g. the API's middleware rejections.
  * - `{ error: '<human message>' }` — legacy hand-rolled routes. With no sibling
  *   `message`/`error_description` the string is the message, not a code: a bare
  *   `error` string is not machine-readable enough to promote to `code`.