@oxyhq/services 12.0.0 → 12.1.0

package/lib/typescript/module/ui/context/inSessionTokenRefresh.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 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 } from '@oxyhq/core';
+/**
+ * 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 declare const TOKEN_REFRESH_LEAD_MS = 60000;
+/**
+ * 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 declare function createInSessionRefreshHandler(oxyServices: OxyServices): AuthRefreshHandler;
+/**
+ * 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 declare function startTokenRefreshScheduler(oxyServices: OxyServices): TokenRefreshSchedulerHandle;
+//# sourceMappingURL=inSessionTokenRefresh.d.ts.map

package/lib/typescript/module/ui/context/inSessionTokenRefresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inSessionTokenRefresh.d.ts","sourceRoot":"","sources":["../../../../../src/ui/context/inSessionTokenRefresh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAEnB,MAAM,aAAa,CAAC;AAwBrB;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAY5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,6BAA6B,CAAC,WAAW,EAAE,WAAW,GAAG,kBAAkB,CA8D1F;AAED;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IAC1C,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,WAAW,GAAG,2BAA2B,CA4FhG"}

package/lib/typescript/module/ui/context/silentSessionRestore.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Silent, no-reload session-restore PRIMITIVES — the single shared
+ * implementation used by BOTH cold boot (`OxyContext.restoreSessionsFromStorage`)
+ * and in-session token refresh (`createInSessionRefreshHandler`). Neither caller
+ * re-implements these; they compose them. Keeping one home avoids the two paths
+ * drifting on "how do we mint a first-party token without a page reload".
+ *
+ * Each function is platform-agnostic at the type level and returns plain data;
+ * the callers own the side effects that differ between them (cold boot COMMITS
+ * the recovered session into provider state; refresh only reads the freshly
+ * planted bearer).
+ */
+import type { OxyServices, SessionLoginResponse } from '@oxyhq/core';
+/**
+ * Mint a fresh first-party session via the PER-APEX `/auth/silent` iframe — the
+ * durable cross-domain restore path that works WITHOUT a top-level navigation
+ * (so it succeeds under Safari ITP / Firefox TCP and in a backgrounded tab).
+ *
+ * The instance is configured with the CENTRAL auth URL, so we explicitly point
+ * the iframe at the per-apex host (`auth.<rp-apex>`) via `autoDetectAuthWebUrl()`
+ * + `silentSignIn`'s `authWebUrlOverride`. On a `*.oxy.so` app the per-apex host
+ * IS the central host, so this also covers same-apex. When auto-detection bails
+ * (localhost / IP / single-label / off-browser) there is no per-apex IdP and we
+ * return `null`. `silentSignIn` plants the access token internally on success.
+ *
+ * @returns the recovered session (token already planted) when complete, else
+ * `null` (no per-apex IdP, no session, or an incomplete iframe response).
+ */
+export declare function mintSessionViaPerApexIframe(oxyServices: OxyServices, timeoutMs: number): Promise<SessionLoginResponse | null>;
+/**
+ * Pick the active account from a `refreshAllSessions` snapshot: the persisted
+ * `authuser` slot when it still matches a returned account, otherwise the lowest
+ * `authuser` (the server sorts ascending, so `[0]`). Callers guarantee a
+ * non-empty list, so the result is always defined.
+ *
+ * Shared by cold-boot cookie restore and the in-session refresh cookie arm so
+ * the active-slot selection can never diverge between them.
+ */
+export declare function selectActiveRefreshAccount<T extends {
+    authuser: number;
+}>(accounts: T[], persistedAuthuser: number | null): T;
+//# sourceMappingURL=silentSessionRestore.d.ts.map

package/lib/typescript/module/ui/context/silentSessionRestore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"silentSessionRestore.d.ts","sourceRoot":"","sources":["../../../../../src/ui/context/silentSessionRestore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGrE;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,2BAA2B,CAC/C,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAatC;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,EACvE,QAAQ,EAAE,CAAC,EAAE,EACb,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAC/B,CAAC,CAMH"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/services",
-  "version": "12.0.0",
+  "version": "12.1.0",
   "description": "OxyHQ Expo/React Native SDK — UI components, screens, and native features",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -106,7 +106,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "0.4.0"
+    "@oxyhq/contracts": "0.5.0"
   },
   "devDependencies": {
     "nativewind": "5.0.0-preview.3",
@@ -152,7 +152,7 @@
   "peerDependencies": {
     "@expo/vector-icons": "^15.0.3",
     "@oxyhq/bloom": ">=0.16.0",
-    "@oxyhq/core": "^3.15.0",
+    "@oxyhq/core": "^3.17.0",
     "@react-native-async-storage/async-storage": "^2.0.0",
     "@react-native-community/netinfo": "^11.4.1",
     "@tanstack/query-async-storage-persister": "^5.100",

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,
@@ -54,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;
@@ -823,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
@@ -932,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
@@ -1408,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);

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;
+    },
+  };
+}

package/src/ui/context/silentSessionRestore.ts

@@ -0,0 +1,67 @@
+/**
+ * Silent, no-reload session-restore PRIMITIVES — the single shared
+ * implementation used by BOTH cold boot (`OxyContext.restoreSessionsFromStorage`)
+ * and in-session token refresh (`createInSessionRefreshHandler`). Neither caller
+ * re-implements these; they compose them. Keeping one home avoids the two paths
+ * drifting on "how do we mint a first-party token without a page reload".
+ *
+ * Each function is platform-agnostic at the type level and returns plain data;
+ * the callers own the side effects that differ between them (cold boot COMMITS
+ * the recovered session into provider state; refresh only reads the freshly
+ * planted bearer).
+ */
+import type { OxyServices, SessionLoginResponse } from '@oxyhq/core';
+import { autoDetectAuthWebUrl } from '@oxyhq/core';
+
+/**
+ * Mint a fresh first-party session via the PER-APEX `/auth/silent` iframe — the
+ * durable cross-domain restore path that works WITHOUT a top-level navigation
+ * (so it succeeds under Safari ITP / Firefox TCP and in a backgrounded tab).
+ *
+ * The instance is configured with the CENTRAL auth URL, so we explicitly point
+ * the iframe at the per-apex host (`auth.<rp-apex>`) via `autoDetectAuthWebUrl()`
+ * + `silentSignIn`'s `authWebUrlOverride`. On a `*.oxy.so` app the per-apex host
+ * IS the central host, so this also covers same-apex. When auto-detection bails
+ * (localhost / IP / single-label / off-browser) there is no per-apex IdP and we
+ * return `null`. `silentSignIn` plants the access token internally on success.
+ *
+ * @returns the recovered session (token already planted) when complete, else
+ * `null` (no per-apex IdP, no session, or an incomplete iframe response).
+ */
+export async function mintSessionViaPerApexIframe(
+  oxyServices: OxyServices,
+  timeoutMs: number,
+): Promise<SessionLoginResponse | null> {
+  const perApexAuthUrl = autoDetectAuthWebUrl();
+  if (!perApexAuthUrl) {
+    return null;
+  }
+  const session = await oxyServices.silentSignIn?.({
+    authWebUrlOverride: perApexAuthUrl,
+    timeout: timeoutMs,
+  });
+  if (!session?.user || !session.sessionId) {
+    return null;
+  }
+  return session;
+}
+
+/**
+ * Pick the active account from a `refreshAllSessions` snapshot: the persisted
+ * `authuser` slot when it still matches a returned account, otherwise the lowest
+ * `authuser` (the server sorts ascending, so `[0]`). Callers guarantee a
+ * non-empty list, so the result is always defined.
+ *
+ * Shared by cold-boot cookie restore and the in-session refresh cookie arm so
+ * the active-slot selection can never diverge between them.
+ */
+export function selectActiveRefreshAccount<T extends { authuser: number }>(
+  accounts: T[],
+  persistedAuthuser: number | null,
+): T {
+  const matched =
+    persistedAuthuser !== null
+      ? accounts.find((account) => account.authuser === persistedAuthuser)
+      : undefined;
+  return matched ?? accounts[0];
+}