@oxyhq/services 12.0.0 → 12.1.1

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.1",
   "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
@@ -1393,14 +1418,13 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
             // step that prevents the re-bounce loop: when it finds a session,
             // the terminal `sso-bounce` never fires.
             //
-            // The instance is configured with `authWebUrl=auth.oxy.so` (central,
-            // for the bounce + FedCM), so we explicitly point the iframe at the
-            // per-apex host via `autoDetectAuthWebUrl()` and `silentSignIn`'s
-            // `authWebUrlOverride`. On a `*.oxy.so` RP the per-apex host IS the
-            // central host (`auth.oxy.so`), so this is a same-host no-op-
-            // equivalent. When auto-detection bails (localhost/IP/single-label)
-            // there is no per-apex IdP and the step skips. Web only; on native
-            // `isWebBrowser()` gates it off, so native never runs an iframe.
+            // The per-apex iframe mint itself lives in
+            // `mintSessionViaPerApexIframe` (shared verbatim with the in-session
+            // refresh handler so the two paths can never drift): it points the
+            // iframe at `autoDetectAuthWebUrl()` and skips when there is no
+            // per-apex IdP (localhost/IP/single-label/off-browser). Web only; on
+            // native `isWebBrowser()` gates it off, so native never runs an
+            // iframe.
             //
             // FIX-B: additionally skipped when `stored-session` already won.
             // FIX-D: bounded by `SILENT_IFRAME_TIMEOUT` (plus `iframe.onerror`
@@ -1408,15 +1432,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,283 @@
+/**
+ * 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 composing the SAME silent-restore primitives cold boot uses
+ *     ({@link mintSessionViaPerApexIframe}, {@link selectActiveRefreshAccount}) —
+ *     not a copy. 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 { logger as loggerUtil } from '@oxyhq/core';
+import { AppState, type AppStateStatus } from 'react-native';
+import { isWebBrowser } from '../hooks/useWebSSO';
+import { readActiveAuthuser } from '../utils/activeAuthuser';
+import { mintSessionViaPerApexIframe, selectActiveRefreshAccount } from './silentSessionRestore';
+
+/**
+ * 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;
+
+/**
+ * A single refresh arm: attempts one silent-restore mechanism and resolves to
+ * the freshly planted access token, or `null` to fall through to the next arm.
+ */
+type RefreshArm = () => Promise<string | null>;
+
+/**
+ * Build the in-session `AuthRefreshHandler` for the owner client.
+ *
+ * Arms run in an explicit order; the first to plant a token wins. Each arm
+ * resolves to the planted token (read back via `getAccessToken()` — the
+ * underlying SDK call plants it internally) or `null`. A throw in one arm is
+ * logged and treated as `null` so the chain continues.
+ *
+ *   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. Resolves to `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. Per-apex `/auth/silent` iframe — {@link mintSessionViaPerApexIframe}
+ *        (shared verbatim with cold boot). The durable cross-apex path; also
+ *        covers `*.oxy.so` (the per-apex host IS the central host there).
+ *     2. FedCM silent re-auth (Chrome) — `silentSignInWithFedCM`.
+ *     3. Same-apex refresh cookie — `refreshAllSessions` + the shared
+ *        {@link selectActiveRefreshAccount}; plant the active account's rotated
+ *        token. On a cross-apex RP it returns `{accounts:[]}` (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: no arm issues a request 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`.
+ */
+export function createInSessionRefreshHandler(oxyServices: OxyServices): AuthRefreshHandler {
+  const runArm = async (label: string, reason: AuthRefreshReason, arm: RefreshArm): Promise<string | null> => {
+    try {
+      return await arm();
+    } catch (error) {
+      if (__DEV__) {
+        loggerUtil.debug(
+          `In-session refresh arm "${label}" failed (falling through)`,
+          { component: 'inSessionTokenRefresh', method: 'authRefreshHandler', reason },
+          error,
+        );
+      }
+      return null;
+    }
+  };
+
+  const webArms: Array<[string, RefreshArm]> = [
+    ['silent-iframe', async () =>
+      (await mintSessionViaPerApexIframe(oxyServices, SILENT_IFRAME_REFRESH_TIMEOUT))
+        ? oxyServices.getAccessToken()
+        : null,
+    ],
+    ['fedcm-silent', async () => {
+      if (oxyServices.isFedCMSupported?.() !== true) {
+        return null;
+      }
+      return (await oxyServices.silentSignInWithFedCM?.()) ? oxyServices.getAccessToken() : null;
+    }],
+    ['refresh-cookie', async () => {
+      const snapshot = await oxyServices.refreshAllSessions({ timeout: COOKIE_REFRESH_TIMEOUT });
+      if (snapshot.accounts.length === 0) {
+        return null;
+      }
+      const active = selectActiveRefreshAccount(snapshot.accounts, readActiveAuthuser());
+      oxyServices.httpService.setTokens(active.accessToken);
+      return oxyServices.getAccessToken();
+    }],
+  ];
+
+  return async (reason: AuthRefreshReason): Promise<string | null> => {
+    if (!isWebBrowser()) {
+      return runArm('native-shared-key', reason, async () =>
+        (await oxyServices.signInWithSharedIdentity?.()) ? oxyServices.getAccessToken() : null,
+      );
+    }
+
+    for (const [label, arm] of webArms) {
+      const token = await runArm(label, reason, arm);
+      if (token) {
+        return token;
+      }
+    }
+    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` — so a
+ * sign-out that clears the token cancels the timer) 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).
+ *
+ * The `exp` is derived directly from the JWT via `getAccessTokenExpiry()`. No-ops
+ * cleanly when there is no token, an opaque/no-`exp` token, or the host lacks
+ * `getAccessTokenExpiry` (older stubs) — the reactive 401 path stays the only
+ * refresh trigger in those cases.
+ */
+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];
+}