@oxyhq/services 11.1.1 → 12.1.0

package/src/ui/context/OxyContext.tsx

@@ -18,7 +18,6 @@ import type { ClientSession } from '@oxyhq/core';
 import {
   runColdBoot,
   resolveCentralAuthUrl,
-  autoDetectAuthWebUrl,
   registrableApex,
   SSO_CALLBACK_PATH,
   ssoStateKey,
@@ -28,6 +27,7 @@ import {
   ssoAttemptedKey,
   isCentralIdPOrigin,
   guardActive,
+  allowSsoBounce,
   ssoNavigate,
   buildSsoBounceUrl,
   consumeSsoReturn,
@@ -53,6 +53,8 @@ import { useAccountStore } from '../stores/accountStore';
 import { logger as loggerUtil } from '@oxyhq/core';
 import { useWebSSO, isWebBrowser } from '../hooks/useWebSSO';
 import { buildSilentGuardKey } from '../../utils/silentGuardKey';
+import { createInSessionRefreshHandler, startTokenRefreshScheduler } from './inSessionTokenRefresh';
+import { mintSessionViaPerApexIframe, selectActiveRefreshAccount } from './silentSessionRestore';
 
 export interface OxyContextState {
   user: User | null;
@@ -196,16 +198,6 @@ export interface OxyContextProviderProps {
    * for the cross-app device sign-in flow. See {@link OxyContextState.clientId}.
    */
   clientId?: string;
-  /**
-   * When `true`, skips ONLY the terminal `sso-bounce` cold-boot step — the
-   * force-redirect to `auth.<apex>/sso?prompt=none` that fires for a visitor
-   * with no recoverable local session. Every other cold-boot step still runs
-   * (callback consume, FedCM silent, `/auth/silent` iframe, stored-session,
-   * cookie-restore), so a returning signed-in user is still silently
-   * restored; only the bounce for a truly anonymous visitor is suppressed.
-   * Default `false`.
-   */
-  disableAutoSso?: boolean;
   onAuthStateChange?: (user: User | null) => void;
   onError?: (error: ApiError) => void;
 }
@@ -462,7 +454,6 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   authRedirectUri,
   storageKeyPrefix = 'oxy_session',
   clientId: clientIdProp,
-  disableAutoSso = false,
   onAuthStateChange,
   onError,
 }) => {
@@ -631,6 +622,25 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     return storageReady.promise;
   }, [storageReady]);
 
+  // Clear the durable "had a signed-in Oxy session before" hint.
+  //
+  // The hint (`storageKeys.priorSession`) is WRITTEN whenever a session is
+  // established/restored — every commit funnels through `persistSessionDurably`,
+  // and the stored-session reload winner sets it directly to backfill
+  // pre-existing installs. It lives in the SAME `storageKeyPrefix`-scoped
+  // durable store as the session ids, so it SURVIVES a session expiring; it is
+  // cleared ONLY here, on EXPLICIT full sign-out (wired into `clearAllAccountData`
+  // and the `useAuthOperations` logout paths — never the passive token-expiry
+  // path). At cold boot the hint is read into `hadPriorSession` and feeds
+  // `allowSsoBounce`: a RETURNING visitor (hint present) whose local session has
+  // lapsed still gets ONE terminal `/sso` establish bounce so a central-only
+  // cross-domain session recovers, while a truly first-time anonymous visitor is
+  // never force-redirected.
+  const clearPriorSessionHint = useCallback(async (): Promise<void> => {
+    const readyStorage = await getReadyStorage();
+    await readyStorage.removeItem(storageKeys.priorSession);
+  }, [getReadyStorage, storageKeys.priorSession]);
+
   useEffect(() => {
     let mounted = true;
     createPlatformStorage()
@@ -717,6 +727,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     updateSessions,
     saveActiveSessionId,
     clearSessionState,
+    clearPriorSessionHint,
     switchSession,
     applyLanguagePreference,
     onAuthStateChange,
@@ -745,12 +756,18 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     // Clear session state (sessions, activeSessionId, storage)
     await clearSessionState();
 
+    // Explicit FULL sign-out: drop the durable returning-user hint so the next
+    // cold boot treats this device as a first-time anonymous visitor (no forced
+    // `/sso` bounce). NOT done on the passive token-expiry path, so an expired
+    // session still recovers via a returning-user bounce.
+    await clearPriorSessionHint();
+
     // Reset account store
     useAccountStore.getState().reset();
 
     // Clear HTTP service cache
     oxyServices.clearCache();
-  }, [queryClient, storage, clearSessionState, logger, oxyServices]);
+  }, [queryClient, storage, clearSessionState, clearPriorSessionHint, logger, oxyServices]);
 
   const { getDeviceSessions, logoutAllDeviceSessions, updateDeviceName } = useDeviceManagement({
     oxyServices,
@@ -807,6 +824,34 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     return oxyServices.onTokensChanged(handleTokenChange);
   }, [logger, oxyServices]);
 
+  // In-session access-token refresh (SDK-owned; every Expo RP inherits it).
+  //
+  // The services path never installed an `authRefreshHandler`, so the owner
+  // `HttpService.refreshAccessToken` short-circuited to null and a 15-minute
+  // access token expired with the app open while `isAuthenticated` stayed true —
+  // a zombie logged-in state whose cross-apex feed calls 401-looped. Here we (1)
+  // install a handler that re-mints a fresh token WITHOUT a reload using the SAME
+  // durable silent-restore arms cold boot uses, and (2) start a proactive
+  // scheduler that refreshes ~60s before expiry (and on tab-focus / app-
+  // foreground) so the common case never even hits the reactive 401 path. The
+  // linked client (`createLinkedClient`) delegates its refresh back to this owner
+  // handler, so it is fixed for free.
+  //
+  // Runs once per `oxyServices` instance (stable, ref-constructed), and BEFORE
+  // any cold-boot request can 401: cold boot is gated on async storage init, so
+  // this synchronous mount effect installs the handler first. On cleanup the
+  // handler is detached and the scheduler torn down (timer + foreground listener)
+  // so nothing leaks across a provider remount. `setAuthRefreshHandler` is
+  // optional-chained to tolerate partial test stubs.
+  useEffect(() => {
+    oxyServices.httpService.setAuthRefreshHandler?.(createInSessionRefreshHandler(oxyServices));
+    const scheduler = startTokenRefreshScheduler(oxyServices);
+    return () => {
+      scheduler.dispose();
+      oxyServices.httpService.setAuthRefreshHandler?.(null);
+    };
+  }, [oxyServices]);
+
   // Durable, navigation-safe session persistence.
   //
   // Writes the active-session id and appends the session id to the durable
@@ -831,7 +876,13 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       sessionIds.push(sessionId);
       await readyStorage.setItem(storageKeys.sessionIds, JSON.stringify(sessionIds));
     }
-  }, [getReadyStorage, logger, storageKeys.activeSessionId, storageKeys.sessionIds]);
+    // A session is now durably committed — set the returning-user hint so a
+    // future cold boot whose local session has lapsed still gets ONE `/sso`
+    // establish bounce (see `markPriorSessionHint`). Every web commit path
+    // (FedCM / silent iframe / SSO return / password / cookie restore) funnels
+    // through here, so this is the single chokepoint for the hint.
+    await readyStorage.setItem(storageKeys.priorSession, '1');
+  }, [getReadyStorage, logger, storageKeys.activeSessionId, storageKeys.sessionIds, storageKeys.priorSession]);
 
   // Refs so the cold-boot restore can plant session state without widening its
   // dependency array (mirrors the existing ref pattern above).
@@ -910,11 +961,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     // Pick the active account: persisted authuser if it still matches a returned
     // account, otherwise the lowest authuser (deterministic). The server has
     // already sorted ascending so [0] is the lowest.
-    const persistedAuthuser = readActiveAuthuser();
-    const matched = persistedAuthuser !== null
-      ? snapshot.accounts.find((a) => a.authuser === persistedAuthuser)
-      : undefined;
-    const activeAccount = matched ?? snapshot.accounts[0];
+    const activeAccount = selectActiveRefreshAccount(snapshot.accounts, readActiveAuthuser());
 
     // Plant the active access token. Sibling accounts' access tokens stay in
     // the snapshot (the chooser can drive a per-account refresh via
@@ -1073,6 +1120,12 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
         // immediately so the loading screen clears without waiting for the
         // remaining cold-boot steps to be evaluated/short-circuited (idempotent).
         markAuthResolvedRef.current();
+        // Backfill the returning-user hint. A reload winner already had the hint
+        // set at original sign-in, but pre-existing installs (signed in before
+        // this hint shipped) get it set here so their NEXT lapse-and-return still
+        // earns one `/sso` establish bounce. `storage` is non-null (guarded at
+        // the top of this callback); best-effort, never blocks restore.
+        await storage.setItem(storageKeys.priorSession, '1');
         return true;
       } catch (switchError) {
         // Silently handle expected errors (invalid sessions, timeouts, network issues)
@@ -1102,6 +1155,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     storage,
     storageKeys.activeSessionId,
     storageKeys.sessionIds,
+    storageKeys.priorSession,
   ]);
 
   // Shared in-flight `runSsoReturn` promise — see the CONCURRENCY note on
@@ -1213,6 +1267,27 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     // `stored-session` skips, this stays false, and the probes run as before.
     let storedSessionRestored = false;
 
+    // FIX-B smart-gate input: has this device/app EVER had a signed-in Oxy
+    // session (the durable `priorSession` hint, set on every commit, cleared
+    // only on explicit full sign-out)? Read ONCE here — synchronously usable by
+    // the terminal `sso-bounce` `enabled` gate below — so a RETURNING visitor
+    // whose local session has lapsed still earns one `/sso` establish bounce,
+    // while a truly first-time anonymous visitor is never force-redirected.
+    // `storage` is non-null (guarded above); a read failure is treated as "no
+    // prior session" (fail safe toward anonymous-browse).
+    let hadPriorSession = false;
+    try {
+      hadPriorSession = (await storage.getItem(storageKeys.priorSession)) === '1';
+    } catch (priorSessionReadError) {
+      if (__DEV__) {
+        loggerUtil.debug(
+          'Failed to read prior-session hint (treating as first-time visitor)',
+          { component: 'OxyContext', method: 'restoreSessionsFromStorage' },
+          priorSessionReadError as unknown,
+        );
+      }
+    }
+
     try {
       const outcome = await runColdBoot<true>({
         steps: [
@@ -1358,15 +1433,15 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
             id: 'silent-iframe',
             enabled: () => !storedSessionRestored && isWebBrowser(),
             run: async () => {
-              const perApexAuthUrl = autoDetectAuthWebUrl();
-              if (!perApexAuthUrl || !commitWebSession) {
+              if (!commitWebSession) {
                 return { kind: 'skip' };
               }
-              const session = await oxyServices.silentSignIn?.({
-                authWebUrlOverride: perApexAuthUrl,
-                timeout: SILENT_IFRAME_TIMEOUT,
-              });
-              if (!session?.user || !session?.sessionId) {
+              // Shared with the in-session refresh handler: the ONE
+              // implementation of "mint a first-party per-apex token without a
+              // reload" lives in `silentSessionRestore` so cold boot and refresh
+              // never drift.
+              const session = await mintSessionViaPerApexIframe(oxyServices, SILENT_IFRAME_TIMEOUT);
+              if (!session) {
                 return { kind: 'skip' };
               }
               await commitWebSession(session);
@@ -1400,11 +1475,23 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
             // still active (loop + self-heal protection).
             id: 'sso-bounce',
             enabled: () => {
-              // Opt-out: when the consumer disabled auto-SSO, never bounce a
-              // truly-anonymous visitor to the central IdP. All other restore
-              // steps already ran above, so a signed-in user is still
-              // recovered; only this terminal force-bounce is suppressed.
-              if (disableAutoSso) {
+              // Smart gate (SDK-owned, shared with `WebOxyProvider` via core's
+              // `allowSsoBounce`). The terminal `/sso` establish-bounce is the
+              // ONLY cold-boot step that can recover a session living SOLELY at
+              // the central IdP (a cross-apex RP whose local session expired),
+              // and it is what plants the per-apex `fedcm_session` cookie the
+              // earlier silent-iframe step relies on. So it is allowed iff a
+              // prior-signed-in hint exists OR a local session was recovered this
+              // boot (`storedSessionRestored`, always false here — an earlier step
+              // would have won — but passed for spec fidelity): a RETURNING user
+              // still gets ONE bounce, while a truly first-time anonymous visitor
+              // does NOT (anonymous browse). The per-tab loop guards below
+              // (`ssoNoSessionKey`, `ssoAttemptedKey`, `guardActive`) still cap an
+              // allowed bounce at one per cold boot.
+              if (!allowSsoBounce({
+                hasPriorSession: hadPriorSession,
+                hasLocalSession: storedSessionRestored,
+              })) {
                 return false;
               }
               if (!isWebBrowser() || window.top !== window.self) {
@@ -1497,11 +1584,11 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   }, [
     oxyServices,
     storage,
+    storageKeys.priorSession,
     restoreViaRefreshCookie,
     restoreStoredSession,
     runSsoReturn,
     markAuthResolved,
-    disableAutoSso,
   ]);
 
   useEffect(() => {

package/src/ui/context/hooks/useAuthOperations.ts

@@ -20,6 +20,14 @@ export interface UseAuthOperationsOptions {
   updateSessions: (sessions: ClientSession[], options?: { merge?: boolean }) => void;
   saveActiveSessionId: (sessionId: string) => Promise<void>;
   clearSessionState: () => Promise<void>;
+  /**
+   * Clear the durable returning-user hint (`storageKeys.priorSession`). Called
+   * ONLY on EXPLICIT full sign-out — alongside `clearSsoBounceState()` — so the
+   * next cold boot treats this device as a first-time anonymous visitor (no
+   * forced `/sso` bounce). NEVER called on the passive token-expiry path, so an
+   * expired session still recovers via a returning-user bounce. Best-effort.
+   */
+  clearPriorSessionHint: () => Promise<void>;
   switchSession: (sessionId: string) => Promise<User>;
   applyLanguagePreference: (user: User) => Promise<void>;
   onAuthStateChange?: (user: User | null) => void;
@@ -44,6 +52,24 @@ const LOGIN_ERROR_CODE = 'LOGIN_ERROR';
 const LOGOUT_ERROR_CODE = 'LOGOUT_ERROR';
 const LOGOUT_ALL_ERROR_CODE = 'LOGOUT_ALL_ERROR';
 
+/**
+ * Fire-and-forget the durable returning-user hint clear on explicit sign-out.
+ *
+ * Mirrors the synchronous, non-blocking nature of the sibling
+ * `clearSsoBounceState()`: sign-out must NEVER block on (or fail because of) a
+ * best-effort storage write. The clear is invoked synchronously (so unit tests
+ * can assert it ran) but its async settle is detached; any rejection is logged,
+ * never thrown.
+ */
+function clearPriorSessionHintSafe(
+  clearPriorSessionHint: () => Promise<void>,
+  logger?: (message: string, error?: unknown) => void,
+): void {
+  clearPriorSessionHint().catch((hintError) => {
+    logger?.('Failed to clear prior-session hint on sign-out', hintError);
+  });
+}
+
 /**
  * Authentication operations using public key cryptography.
  * Accepts public key as parameter - identity management is handled by the app layer.
@@ -56,6 +82,7 @@ export const useAuthOperations = ({
   updateSessions,
   saveActiveSessionId,
   clearSessionState,
+  clearPriorSessionHint,
   switchSession,
   applyLanguagePreference,
   onAuthStateChange,
@@ -227,6 +254,7 @@ export const useAuthOperations = ({
             // Genuine FULL sign-out (no sessions remain): clear the per-origin
             // SSO bounce state so a fresh deliberate sign-in can re-probe.
             clearSsoBounceState();
+            clearPriorSessionHintSafe(clearPriorSessionHint, logger);
             await clearSessionState();
             return;
           }
@@ -237,6 +265,7 @@ export const useAuthOperations = ({
         if (isInvalid && targetSessionId === activeSessionId) {
           // The active session is invalid → full sign-out; clear SSO state too.
           clearSsoBounceState();
+          clearPriorSessionHintSafe(clearPriorSessionHint, logger);
           await clearSessionState();
           return;
         }
@@ -254,6 +283,7 @@ export const useAuthOperations = ({
     [
       activeSessionId,
       clearSessionState,
+      clearPriorSessionHint,
       logger,
       onError,
       oxyServices,
@@ -286,8 +316,11 @@ export const useAuthOperations = ({
         clearActiveAuthuser();
       }
       // logoutAll is ALWAYS a full sign-out: clear the per-origin SSO bounce
-      // state (web-guarded internally) so a fresh sign-in can re-probe.
+      // state (web-guarded internally) so a fresh sign-in can re-probe, and drop
+      // the durable returning-user hint so the next cold boot is treated as a
+      // first-time anonymous visitor (no forced `/sso` bounce after sign-out).
       clearSsoBounceState();
+      clearPriorSessionHintSafe(clearPriorSessionHint, logger);
       await clearSessionState();
     } catch (error) {
       handleAuthError(error, {
@@ -299,7 +332,7 @@ export const useAuthOperations = ({
       });
       throw error instanceof Error ? error : new Error('Logout all failed');
     }
-  }, [activeSessionId, clearSessionState, logger, onError, oxyServices, setAuthState]);
+  }, [activeSessionId, clearSessionState, clearPriorSessionHint, logger, onError, oxyServices, setAuthState]);
 
   return {
     signIn,

package/src/ui/context/inSessionTokenRefresh.ts

@@ -0,0 +1,298 @@
+/**
+ * In-session access-token refresh for the React Native / Expo SDK.
+ *
+ * THE GAP THIS CLOSES: the services `OxyContext` owns the session but never
+ * installed an `authRefreshHandler` on the owner `HttpService`, so
+ * `HttpService.refreshAccessToken` short-circuited to `null` — there was NO
+ * in-session token refresh on the RN path at all. A 15-minute access token
+ * expired with the tab/app open and nothing re-minted one; cross-apex RP feeds
+ * (mention.earth, …) then 401'd in a loop while `isAuthenticated` stayed `true`
+ * (a zombie logged-in state), because the `Domain=oxy.so` refresh cookie can't
+ * reach `api.<apex>`. (`AuthManager`, which installs a refresh handler on the
+ * web path, is only ever constructed by `WebOxyProvider` in `@oxyhq/auth`.)
+ *
+ * THE FIX, two cooperating pieces both wired from `OxyContext`:
+ *
+ *  1. {@link createInSessionRefreshHandler} — an `AuthRefreshHandler` installed
+ *     on the owner client. It re-mints a fresh access token WITHOUT a page
+ *     reload by reusing the SAME durable per-apex silent-restore arms cold boot
+ *     uses (in order; first that yields a token wins). The linked client
+ *     (`createLinkedClient`) inherits the fix for free — its refresh delegates
+ *     back to the owner's `refreshAccessToken`.
+ *
+ *  2. {@link startTokenRefreshScheduler} — a proactive scheduler that refreshes
+ *     ~{@link TOKEN_REFRESH_LEAD_MS} before expiry (and on web tab-focus / native
+ *     app-foreground), so the common case never even reaches the reactive
+ *     401-then-recover flash.
+ *
+ * Concurrency/cooldown/dedup are owned by `HttpService.refreshAccessToken`
+ * (single in-flight `tokenRefreshPromise` + cooldown) — this module does not
+ * reimplement them, so the timer / foreground / per-request triggers collapse to
+ * one network attempt (no refresh storm).
+ */
+import type {
+  OxyServices,
+  AuthRefreshHandler,
+  AuthRefreshReason,
+} from '@oxyhq/core';
+import { autoDetectAuthWebUrl, logger as loggerUtil } from '@oxyhq/core';
+import { AppState, type AppStateStatus } from 'react-native';
+import { isWebBrowser } from '../hooks/useWebSSO';
+import { readActiveAuthuser } from '../utils/activeAuthuser';
+
+/**
+ * Per-arm fail-fast budget (ms) for the web first-party `/auth/silent` iframe
+ * arm. Slightly more generous than the cold-boot iframe budget (2.5s) because an
+ * in-session refresh is NOT in the first-paint critical path — a couple hundred
+ * ms of extra headroom for the same-origin handshake is worth a higher success
+ * rate. `silentSignIn` still fail-fasts on `iframe.onerror`, so a hard failure
+ * returns well before this.
+ */
+const SILENT_IFRAME_REFRESH_TIMEOUT = 4000;
+
+/**
+ * Per-arm fail-fast budget (ms) for the same-apex refresh-cookie arm
+ * (`refreshAllSessions`). On a cross-apex RP the `Domain=oxy.so` cookie never
+ * reaches `api.<apex>`, so this returns `{accounts:[]}` quickly; the bound only
+ * matters if that endpoint stalls.
+ */
+const COOKIE_REFRESH_TIMEOUT = 4000;
+
+/**
+ * Lead time (ms) before access-token expiry at which the proactive scheduler
+ * refreshes. Mirrors `HttpService`'s per-request `TOKEN_REFRESH_LEAD_SECONDS`
+ * (60s) so the scheduled refresh and the request-time preflight refresh use the
+ * same window — the scheduler simply fires it during idle/background instead of
+ * waiting for the next request.
+ */
+export const TOKEN_REFRESH_LEAD_MS = 60_000;
+
+function debugRefresh(message: string, reason: AuthRefreshReason, error?: unknown): void {
+  if (__DEV__) {
+    loggerUtil.debug(
+      message,
+      { component: 'inSessionTokenRefresh', method: 'authRefreshHandler', reason },
+      error,
+    );
+  }
+}
+
+/**
+ * Build the in-session `AuthRefreshHandler` for the owner client.
+ *
+ * Arms (first to yield a fresh token wins; each is bounded and falls through on
+ * failure). Every arm plants the fresh token internally, so on success we read
+ * it back via `getAccessToken()`:
+ *
+ *   NATIVE (Expo): shared cross-app identity key re-mint
+ *     (`signInWithSharedIdentity` → challenge→sign→verify plants the tokens).
+ *     The ONLY silent native arm (mirrors cold boot's `shared-key-signin`); the
+ *     `/auth/silent` web iframe is NEVER attempted on native. Returns `null`
+ *     when the device holds no shared identity (e.g. a password-only native
+ *     sign-in) so a genuinely dead session reconciles to logged-out rather than
+ *     staying a zombie.
+ *
+ *   WEB, in order:
+ *     1. First-party `/auth/silent` iframe at the per-apex IdP
+ *        (`silentSignIn` with `authWebUrlOverride = autoDetectAuthWebUrl()`).
+ *        The durable cross-apex path: the iframe reads the first-party
+ *        `fedcm_session` cookie on `auth.<apex>` and mints a fresh Oxy token. No
+ *        top-level navigation → works in a backgrounded tab. On a `*.oxy.so`
+ *        app the per-apex host IS the central host, so this also covers
+ *        same-apex.
+ *     2. FedCM silent re-auth (Chrome) — `silentSignInWithFedCM`.
+ *     3. Same-apex refresh cookie — `refreshAllSessions`. On `*.oxy.so` the
+ *        httpOnly `oxy_rt_${n}` cookies ride along; we plant the active
+ *        account's rotated token. On a cross-apex RP it returns `{accounts:[]}`
+ *        and is a clean no-op. Unlike the cold-boot cookie restore this does NOT
+ *        rebuild multi-session state — an in-session refresh only needs a fresh
+ *        bearer.
+ *
+ * NO RECURSION: none of these arms issue requests through the authed client's
+ * `refreshAccessToken` path. The iframe/FedCM transports are postMessage /
+ * credential APIs; the follow-up `/session/user` fetch inside `silentSignIn`
+ * runs against the just-planted FULL-TTL token (≫ the preflight lead), so it
+ * never re-enters the refresh path; `refreshAllSessions` uses a raw `fetch` with
+ * `credentials:'include'`.
+ */
+export function createInSessionRefreshHandler(oxyServices: OxyServices): AuthRefreshHandler {
+  return async (reason: AuthRefreshReason): Promise<string | null> => {
+    if (!isWebBrowser()) {
+      try {
+        const session = await oxyServices.signInWithSharedIdentity?.();
+        if (session) {
+          // `verifyChallenge` inside `signInWithSharedIdentity` already planted
+          // the fresh tokens; read the planted access token back out.
+          return oxyServices.getAccessToken();
+        }
+      } catch (error) {
+        debugRefresh('Native shared-key in-session refresh failed', reason, error);
+      }
+      return null;
+    }
+
+    // WEB arm 1 — first-party silent iframe at the per-apex IdP.
+    try {
+      const perApexAuthUrl = autoDetectAuthWebUrl();
+      if (perApexAuthUrl) {
+        const session = await oxyServices.silentSignIn?.({
+          authWebUrlOverride: perApexAuthUrl,
+          timeout: SILENT_IFRAME_REFRESH_TIMEOUT,
+        });
+        if (session) {
+          return oxyServices.getAccessToken();
+        }
+      }
+    } catch (error) {
+      debugRefresh('Silent-iframe in-session refresh failed', reason, error);
+    }
+
+    // WEB arm 2 — FedCM silent re-auth (Chrome).
+    try {
+      if (oxyServices.isFedCMSupported?.() === true) {
+        const session = await oxyServices.silentSignInWithFedCM?.();
+        if (session) {
+          return oxyServices.getAccessToken();
+        }
+      }
+    } catch (error) {
+      debugRefresh('FedCM-silent in-session refresh failed', reason, error);
+    }
+
+    // WEB arm 3 — same-apex refresh cookie.
+    try {
+      const snapshot = await oxyServices.refreshAllSessions({ timeout: COOKIE_REFRESH_TIMEOUT });
+      if (snapshot.accounts.length > 0) {
+        const persistedAuthuser = readActiveAuthuser();
+        const active =
+          (persistedAuthuser !== null
+            ? snapshot.accounts.find((account) => account.authuser === persistedAuthuser)
+            : undefined) ?? snapshot.accounts[0];
+        oxyServices.httpService.setTokens(active.accessToken);
+        return oxyServices.getAccessToken();
+      }
+    } catch (error) {
+      debugRefresh('Refresh-cookie in-session refresh failed', reason, error);
+    }
+
+    return null;
+  };
+}
+
+/**
+ * Handle returned by {@link startTokenRefreshScheduler}; call `dispose()` to tear
+ * down the timer and the foreground listener.
+ */
+export interface TokenRefreshSchedulerHandle {
+  dispose(): void;
+}
+
+/**
+ * Start the proactive in-session refresh scheduler against `oxyServices`.
+ *
+ * Schedules a single timer to fire {@link TOKEN_REFRESH_LEAD_MS} before the
+ * current access token's `exp`, calling `httpService.refreshAccessToken`
+ * ('preflight') — which runs the installed handler and is deduped + cooldown-
+ * guarded. After every attempt it reschedules from the (possibly rotated) token.
+ * It also reschedules whenever the token changes (`onTokensChanged`) and, on
+ * web tab-focus / native app-foreground, refreshes immediately if already inside
+ * the lead window (a long-hidden tab throttles timers, so the token can be
+ * expired on return).
+ *
+ * No-ops cleanly when there is no token, an opaque/no-`exp` token, or the host
+ * lacks `getAccessTokenExpiry` (older stubs) — in those cases the reactive 401
+ * path remains the only refresh trigger.
+ */
+export function startTokenRefreshScheduler(oxyServices: OxyServices): TokenRefreshSchedulerHandle {
+  let disposed = false;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  const clearTimer = (): void => {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  };
+
+  const runRefresh = (): void => {
+    // `refreshAccessToken` is deduped + cooldown-guarded internally, so this is
+    // safe to call from the timer, the foreground listener, and request-time
+    // preflight concurrently — they collapse to one network attempt.
+    const refresh = oxyServices.httpService.refreshAccessToken?.('preflight');
+    if (!refresh) {
+      return;
+    }
+    void refresh
+      .catch(() => null)
+      .finally(() => {
+        if (!disposed) {
+          schedule();
+        }
+      });
+  };
+
+  const schedule = (): void => {
+    clearTimer();
+    if (disposed || !oxyServices.getAccessToken()) {
+      return;
+    }
+    const expSeconds = oxyServices.getAccessTokenExpiry?.() ?? null;
+    if (expSeconds === null) {
+      return;
+    }
+    const fireInMs = expSeconds * 1000 - Date.now() - TOKEN_REFRESH_LEAD_MS;
+    timer = setTimeout(runRefresh, Math.max(fireInMs, 0));
+  };
+
+  const onForeground = (): void => {
+    if (disposed || !oxyServices.getAccessToken()) {
+      return;
+    }
+    const expSeconds = oxyServices.getAccessTokenExpiry?.() ?? null;
+    if (expSeconds === null) {
+      return;
+    }
+    const remainingMs = expSeconds * 1000 - Date.now();
+    if (remainingMs <= TOKEN_REFRESH_LEAD_MS) {
+      runRefresh();
+    } else {
+      schedule();
+    }
+  };
+
+  const unsubscribeTokens = oxyServices.onTokensChanged(() => {
+    if (!disposed) {
+      schedule();
+    }
+  });
+
+  let removeForeground: (() => void) | null = null;
+  if (isWebBrowser() && typeof document !== 'undefined') {
+    const handler = (): void => {
+      if (document.visibilityState === 'visible') {
+        onForeground();
+      }
+    };
+    document.addEventListener('visibilitychange', handler);
+    removeForeground = () => document.removeEventListener('visibilitychange', handler);
+  } else if (!isWebBrowser() && AppState && typeof AppState.addEventListener === 'function') {
+    const subscription = AppState.addEventListener('change', (state: AppStateStatus) => {
+      if (state === 'active') {
+        onForeground();
+      }
+    });
+    removeForeground = () => subscription.remove();
+  }
+
+  schedule();
+
+  return {
+    dispose(): void {
+      disposed = true;
+      clearTimer();
+      unsubscribeTokens();
+      removeForeground?.();
+      removeForeground = null;
+    },
+  };
+}