@oxyhq/core 5.4.3 → 6.0.0

package/src/session/authStateStore.ts

@@ -0,0 +1,335 @@
+/**
+ * Persisted auth state — ONE shape, web + native.
+ *
+ * The device-first session model (auth-centralization wave 1) persists the
+ * rotating refresh-token family head per ORIGIN so a reload restores the
+ * session locally without a redirect. This module is the storage seam: a tiny
+ * `load / save / clear` interface plus platform factories, so the cold boot
+ * (`coldBootV2`) and the unified refresh handler (`refresh.ts`) never touch a
+ * platform storage API directly.
+ *
+ * Platform-agnostic — the native factory takes an INJECTED key/value store
+ * (`@oxyhq/services` passes a SecureStore-backed adapter) so `@oxyhq/core`
+ * never imports `expo-secure-store`. The web factory is self-contained
+ * (`localStorage`) and degrades to in-memory when storage is unavailable
+ * (sandboxed iframe `SecurityError`, private-mode quota, SSR).
+ *
+ * ESM-safe (no `require()`).
+ */
+
+/**
+ * The persisted session credential set for a single origin.
+ *
+ * `refreshToken` is the rotating single-use family head; `sessionId` + `userId`
+ * identify the owning device session and account. `deviceToken` is the opaque,
+ * add-only device attribution token (mirrored to the shared keychain on native
+ * so every Oxy app on one phone shares one DeviceSession).
+ *
+ * `accessToken` + `expiresAt` are OPTIONAL warm-boot fields. Persisting them
+ * lets the cold boot plant a still-valid access token on the very first paint
+ * WITHOUT a blocking `/auth/refresh-token` round-trip — the proactive scheduler
+ * then rotates it in the background. They are a strict optimization: the store
+ * is fully functional (via `refreshToken`) when they are absent or stale, and
+ * the access token is short-lived, so persisting it adds no exposure the
+ * already-persisted refresh token does not (see the plan's XSS risk note — the
+ * refresh token is the dominant secret either way).
+ */
+export interface PersistedAuthState {
+  sessionId: string;
+  refreshToken: string;
+  userId: string;
+  deviceToken?: string;
+  /** Optional warm-boot access token (short-lived; see interface docs). */
+  accessToken?: string;
+  /** Optional warm-boot access-token expiry, ISO-8601. */
+  expiresAt?: string;
+}
+
+/**
+ * The storage seam consumed by the cold boot and the refresh handler. Async
+ * throughout so one interface fits both synchronous web `localStorage` and
+ * asynchronous native SecureStore/AsyncStorage.
+ *
+ * Two lifetimes:
+ *  - The SESSION credential blob (`load`/`save`/`clear`) is per-sign-in and is
+ *    wiped on `clear()` (sign-out).
+ *  - The DEVICE token (`loadDeviceToken`/`saveDeviceToken`/`clearDeviceToken`)
+ *    is long-lived device attribution that SURVIVES `clear()`: a signed-out
+ *    browser is still the same device, and a later in-app (cross-apex,
+ *    cookie-less) login sends this token so the new session joins the SAME
+ *    server-side DeviceSession. Only an explicit device signout-all
+ *    (`clearDeviceToken`) removes it.
+ */
+export interface AuthStateStore {
+  load(): Promise<PersistedAuthState | null>;
+  save(state: PersistedAuthState): Promise<void>;
+  clear(): Promise<void>;
+  loadDeviceToken(): Promise<string | null>;
+  saveDeviceToken(token: string): Promise<void>;
+  clearDeviceToken(): Promise<void>;
+}
+
+/**
+ * The minimal async key/value surface a native store must provide. Matches
+ * both `expo-secure-store` (wrapped) and `@react-native-async-storage`.
+ */
+export interface NativeKeyValueStorage {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+}
+
+/**
+ * Versioned storage key. The `.v1` suffix lets a future shape change ship a
+ * `.v2` key without reading a stale/incompatible `.v1` blob. Distinct from the
+ * `oxy_shared_*` keychain keys in `KeyManager`, so it never collides.
+ */
+export const AUTH_STATE_STORAGE_KEY = 'oxy.auth.v1';
+
+/**
+ * Storage key for the long-lived device-attribution token. Separate from
+ * {@link AUTH_STATE_STORAGE_KEY} because it must OUTLIVE a session `clear()`
+ * (sign-out) — the device is unchanged across sign-ins.
+ */
+export const DEVICE_TOKEN_STORAGE_KEY = 'oxy.device.v1';
+
+/**
+ * Parse + shape-validate a stored blob. Returns `null` for anything that is
+ * not a well-formed {@link PersistedAuthState} (absent, malformed JSON, wrong
+ * types) so a corrupt entry degrades to "signed out" rather than throwing.
+ */
+function deserialize(raw: string | null): PersistedAuthState | null {
+  if (!raw) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    return null;
+  }
+  const candidate = parsed as Record<string, unknown>;
+  if (
+    typeof candidate.sessionId !== 'string' ||
+    typeof candidate.refreshToken !== 'string' ||
+    typeof candidate.userId !== 'string' ||
+    candidate.sessionId.length === 0 ||
+    candidate.refreshToken.length === 0 ||
+    candidate.userId.length === 0
+  ) {
+    return null;
+  }
+  const state: PersistedAuthState = {
+    sessionId: candidate.sessionId,
+    refreshToken: candidate.refreshToken,
+    userId: candidate.userId,
+  };
+  if (typeof candidate.deviceToken === 'string' && candidate.deviceToken.length > 0) {
+    state.deviceToken = candidate.deviceToken;
+  }
+  if (typeof candidate.accessToken === 'string' && candidate.accessToken.length > 0) {
+    state.accessToken = candidate.accessToken;
+  }
+  if (typeof candidate.expiresAt === 'string' && candidate.expiresAt.length > 0) {
+    state.expiresAt = candidate.expiresAt;
+  }
+  return state;
+}
+
+/**
+ * A process-lifetime, in-memory {@link AuthStateStore}. Used directly for
+ * tests/SSR and as the degraded fallback of the web store when `localStorage`
+ * is unreachable. Not durable across reloads — that is acceptable for the
+ * fallback because the alternative (throwing) would break cold boot entirely.
+ */
+export function createMemoryAuthStateStore(): AuthStateStore {
+  let current: PersistedAuthState | null = null;
+  let deviceToken: string | null = null;
+  return {
+    load: async () => current,
+    save: async (state) => {
+      current = state;
+    },
+    clear: async () => {
+      current = null;
+    },
+    loadDeviceToken: async () => deviceToken,
+    saveDeviceToken: async (token) => {
+      deviceToken = token;
+    },
+    clearDeviceToken: async () => {
+      deviceToken = null;
+    },
+  };
+}
+
+/**
+ * Read the ambient `localStorage`, tolerating the case where merely ACCESSING
+ * `window.localStorage` throws. In a sandboxed / cross-origin iframe the getter
+ * itself raises `SecurityError` (not the method calls), so the access must be
+ * inside the try. Returns `null` when storage is unavailable.
+ */
+function safeGetLocalStorage(): Storage | null {
+  try {
+    if (typeof globalThis === 'undefined') {
+      return null;
+    }
+    const store = (globalThis as { localStorage?: Storage }).localStorage;
+    return store ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A `localStorage`-backed {@link AuthStateStore} under the versioned
+ * {@link AUTH_STATE_STORAGE_KEY}.
+ *
+ * Resilience:
+ *  - If `localStorage` is unreachable (sandboxed-iframe `SecurityError`, SSR),
+ *    the whole store degrades to an in-memory {@link createMemoryAuthStateStore}
+ *    for this page's lifetime — never throws on construction.
+ *  - Individual `getItem`/`setItem`/`removeItem` are each wrapped: a read that
+ *    throws yields `null`; a write that throws (quota, private mode) is
+ *    swallowed. The persisted-refresh lane treats a failed persist as "no
+ *    durable state" (falls back to the bootstrap hop) rather than crashing.
+ */
+export function createWebAuthStateStore(): AuthStateStore {
+  const storage = safeGetLocalStorage();
+  if (!storage) {
+    return createMemoryAuthStateStore();
+  }
+  // In-memory mirror so a FAILED persist (quota / private mode / locked store)
+  // does not silently lose the session for this page's lifetime. `undefined`
+  // means "never written this session" → fall back to storage; any set value
+  // (including `null` after clear) is authoritative and preferred over storage.
+  let sessionMirror: PersistedAuthState | null | undefined;
+  let deviceTokenMirror: string | null | undefined;
+  return {
+    load: async () => {
+      if (sessionMirror !== undefined) {
+        return sessionMirror;
+      }
+      try {
+        return deserialize(storage.getItem(AUTH_STATE_STORAGE_KEY));
+      } catch {
+        return null;
+      }
+    },
+    save: async (state) => {
+      sessionMirror = state; // mirror FIRST — authoritative even if persist fails
+      try {
+        storage.setItem(AUTH_STATE_STORAGE_KEY, JSON.stringify(state));
+      } catch {
+        // Quota / private-mode / disabled storage — non-fatal. The session
+        // stays live via the in-memory mirror; only reload durability is lost.
+      }
+    },
+    clear: async () => {
+      sessionMirror = null;
+      try {
+        storage.removeItem(AUTH_STATE_STORAGE_KEY);
+      } catch {
+        // Non-fatal — see save().
+      }
+    },
+    loadDeviceToken: async () => {
+      if (deviceTokenMirror !== undefined) {
+        return deviceTokenMirror;
+      }
+      try {
+        return storage.getItem(DEVICE_TOKEN_STORAGE_KEY);
+      } catch {
+        return null;
+      }
+    },
+    saveDeviceToken: async (token) => {
+      deviceTokenMirror = token;
+      try {
+        storage.setItem(DEVICE_TOKEN_STORAGE_KEY, token);
+      } catch {
+        // Non-fatal — see save().
+      }
+    },
+    clearDeviceToken: async () => {
+      deviceTokenMirror = null;
+      try {
+        storage.removeItem(DEVICE_TOKEN_STORAGE_KEY);
+      } catch {
+        // Non-fatal — see save().
+      }
+    },
+  };
+}
+
+/**
+ * A native {@link AuthStateStore} over an injected async key/value store.
+ *
+ * `@oxyhq/core` never imports `expo-secure-store`; `@oxyhq/services` constructs
+ * the SecureStore-backed adapter and passes it here. Every operation is wrapped
+ * so a storage exception degrades gracefully (read → `null`, write → swallowed)
+ * exactly like the web store.
+ */
+export function createNativeAuthStateStore(storage: NativeKeyValueStorage): AuthStateStore {
+  // Same in-memory mirror as the web store — a locked/failed SecureStore write
+  // must not silently lose the session for the app's lifetime.
+  let sessionMirror: PersistedAuthState | null | undefined;
+  let deviceTokenMirror: string | null | undefined;
+  return {
+    load: async () => {
+      if (sessionMirror !== undefined) {
+        return sessionMirror;
+      }
+      try {
+        return deserialize(await storage.getItem(AUTH_STATE_STORAGE_KEY));
+      } catch {
+        return null;
+      }
+    },
+    save: async (state) => {
+      sessionMirror = state;
+      try {
+        await storage.setItem(AUTH_STATE_STORAGE_KEY, JSON.stringify(state));
+      } catch {
+        // Non-fatal — session stays live via the in-memory mirror.
+      }
+    },
+    clear: async () => {
+      sessionMirror = null;
+      try {
+        await storage.removeItem(AUTH_STATE_STORAGE_KEY);
+      } catch {
+        // Non-fatal.
+      }
+    },
+    loadDeviceToken: async () => {
+      if (deviceTokenMirror !== undefined) {
+        return deviceTokenMirror;
+      }
+      try {
+        return await storage.getItem(DEVICE_TOKEN_STORAGE_KEY);
+      } catch {
+        return null;
+      }
+    },
+    saveDeviceToken: async (token) => {
+      deviceTokenMirror = token;
+      try {
+        await storage.setItem(DEVICE_TOKEN_STORAGE_KEY, token);
+      } catch {
+        // Non-fatal.
+      }
+    },
+    clearDeviceToken: async () => {
+      deviceTokenMirror = null;
+      try {
+        await storage.removeItem(DEVICE_TOKEN_STORAGE_KEY);
+      } catch {
+        // Non-fatal.
+      }
+    },
+  };
+}

package/src/session/createSessionClient.ts

@@ -1,5 +1,6 @@
 import type { OxyServices } from '../OxyServices';
 import { SessionClient, type TokenTransport } from './SessionClient';
+import type { SocketIOFactory } from './socketLoader';
 import { createSessionClientHost } from './sessionClientHost';
 
 /**
@@ -17,15 +18,22 @@ import { createSessionClientHost } from './sessionClientHost';
  * The host is returned alongside the client (not just the client) so the
  * caller can call `host.setCurrentAccountId(...)` as the active account
  * changes.
+ *
+ * `socketFactory` is the statically-injected `socket.io-client` `io` export.
+ * Consumers that bundle socket.io-client as a real dependency pass it so
+ * realtime sync never depends on core's lazy dynamic import of a bare
+ * specifier (bundler-fragile in Metro/Expo-web and Vite against the published
+ * dist). When omitted, the client falls back to the lazy loader.
  */
 export function createSessionClient(
   oxyServices: OxyServices,
   transport: TokenTransport,
+  socketFactory?: SocketIOFactory,
 ): {
   client: SessionClient;
   host: ReturnType<typeof createSessionClientHost>;
 } {
   const host = createSessionClientHost(oxyServices);
-  const client = new SessionClient(host, { transport });
+  const client = new SessionClient(host, { transport, socketFactory });
   return { client, host };
 }

package/src/session/refresh.ts

@@ -0,0 +1,334 @@
+/**
+ * Unified token refresh — THE single refresh implementation for web + native.
+ *
+ * Before device-first, refresh was duplicated: `@oxyhq/auth`'s
+ * `session/tokenRefresh.ts` (per-apex `/auth/silent` iframe) and
+ * `@oxyhq/services`'s `inSessionTokenRefresh.ts` (native shared-key). This
+ * module replaces both with ONE persisted-refresh-token rotation shared by
+ * every consumer:
+ *
+ *  - `refreshPersistedSession` — arm 1 rotates the stored refresh-token family
+ *    (`POST /auth/refresh-token`), planting + persisting the rotated pair; arm 2
+ *    (native only) re-mints via the shared-keychain identity when there is no
+ *    live refresh token. It is used BOTH reactively (wrapped as the
+ *    `AuthRefreshHandler` installed on `HttpService`) AND proactively (the
+ *    cold-boot `stored-tokens` step calls it directly).
+ *  - `createAuthRefreshHandler` / `installAuthRefreshHandler` wire arm 1+2 into
+ *    `HttpService.setAuthRefreshHandler`, keeping that layer's single-flight
+ *    dedup + cooldown (this module does NOT reimplement them).
+ *  - `startTokenRefreshScheduler` — a proactive scheduler (lifted from the
+ *    better of the two prior duplicates, `@oxyhq/auth`'s `tokenRefresh.ts`),
+ *    decoupled from any React / auth-sdk type: refreshes ~60s before `exp`,
+ *    re-arms on token change + web tab-focus, `.unref?.()`s its timer in Node.
+ *
+ * Framework-free; no module-level mutable state.
+ */
+import type { OxyServices } from '../OxyServices';
+import type { AuthRefreshHandler, AuthRefreshReason } from '../HttpService';
+import type { AuthStateStore, PersistedAuthState } from './authStateStore';
+import { isNative } from '../utils/platform';
+import { logger } from '../utils/loggerUtils';
+
+/**
+ * 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 just fires it during idle/background.
+ */
+export const TOKEN_REFRESH_LEAD_MS = 60_000;
+
+/**
+ * Max `setTimeout` delay (2^31 − 1 ms, ~24.8 days). A larger delay overflows
+ * the int32 timer field and fires IMMEDIATELY — with a long-TTL token that
+ * turns the reschedule-on-finish loop into a tight busy refresh. Clamp to it.
+ */
+const MAX_TIMEOUT_DELAY_MS = 2_147_483_647;
+
+/**
+ * Floor (ms) on ANY scheduled delay. An already-expired / in-lead-window token
+ * computes a non-positive `exp − now − lead`; without this floor that becomes
+ * `setTimeout(…, 0)`, and a FAILING refresh (offline / server error) would
+ * re-arm at 0 in the finally block → a tight 100%-CPU busy loop. The floor
+ * guarantees every re-arm yields the event loop.
+ */
+const MIN_SCHEDULE_DELAY_MS = 1_000;
+
+/**
+ * Backoff schedule (ms) applied when a scheduled refresh FAILS: first retry
+ * after {@link MIN_FAILURE_BACKOFF_MS}, doubling up to {@link MAX_FAILURE_BACKOFF_MS}.
+ * Reset to 0 on any success or token change. This is what converts the former
+ * zero-delay failure loop into a bounded, backing-off retry.
+ */
+const MIN_FAILURE_BACKOFF_MS = 5_000;
+const MAX_FAILURE_BACKOFF_MS = 5 * 60_000;
+
+/**
+ * Error codes (in addition to HTTP 401/403) that mean the stored refresh token
+ * is permanently unusable — the family was revoked or a reuse was detected. On
+ * any of these the persisted store is CLEARED (the session is truly over);
+ * transient failures (network, 5xx) leave the store intact so a later attempt
+ * can still succeed.
+ */
+const REVOKED_REFRESH_CODES = new Set([
+  'invalid_grant',
+  'refresh_token_revoked',
+  'refresh_token_reuse',
+  'token_reuse',
+  'invalid_token',
+]);
+
+interface HttpishError {
+  status?: number;
+  code?: string;
+}
+
+/** Does this error mean the refresh token is permanently dead (vs. transient)? */
+function isRevokedRefreshError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') {
+    return false;
+  }
+  const e = error as HttpishError;
+  if (e.status === 401 || e.status === 403) {
+    return true;
+  }
+  return typeof e.code === 'string' && REVOKED_REFRESH_CODES.has(e.code);
+}
+
+export interface RefreshDeps {
+  oxy: OxyServices;
+  store: AuthStateStore;
+  /**
+   * Whether to fall back to the native shared-keychain re-mint (arm 2) when
+   * there is no live refresh token / arm 1 is revoked. Defaults to `isNative()`
+   * — web has no shared keychain. Exposed for tests.
+   */
+  allowSharedKeyFallback?: boolean;
+}
+
+/**
+ * Rotate the persisted session and return the fresh access token, or `null`
+ * when no arm could produce one.
+ *
+ * Arm 1 (`POST /auth/refresh-token`): if the store holds a refresh token, rotate
+ * it — on success plant + persist the rotated pair; on a REVOKED error clear the
+ * store; on a transient error leave the store and return `null`.
+ *
+ * Arm 2 (native shared-keychain): when there is no refresh token or arm 1 was
+ * revoked, re-mint via `signInWithSharedIdentity` (which plants tokens). The
+ * shared keychain — not the per-origin store — is the durable native credential,
+ * so this arm does not write the store.
+ */
+export async function refreshPersistedSession(deps: RefreshDeps): Promise<string | null> {
+  const { oxy, store } = deps;
+  const allowSharedKeyFallback = deps.allowSharedKeyFallback ?? isNative();
+
+  const persisted = await store.load();
+
+  if (persisted?.refreshToken) {
+    try {
+      const rotated = await oxy.refreshWithToken(persisted.refreshToken);
+      oxy.setTokens(rotated.accessToken);
+      const next: PersistedAuthState = {
+        sessionId: rotated.sessionId,
+        refreshToken: rotated.refreshToken,
+        userId: persisted.userId,
+        accessToken: rotated.accessToken,
+        expiresAt: rotated.expiresAt,
+      };
+      if (persisted.deviceToken) {
+        next.deviceToken = persisted.deviceToken;
+      }
+      await store.save(next);
+      return rotated.accessToken;
+    } catch (error) {
+      if (isRevokedRefreshError(error)) {
+        await store.clear();
+        // Fall through to the native shared-key arm below — on a shared-key
+        // device the refresh family being revoked does not end the session.
+      } else {
+        logger.debug(
+          'Persisted refresh failed (transient) — keeping store',
+          { component: 'refresh', method: 'refreshPersistedSession' },
+          error,
+        );
+        return null;
+      }
+    }
+  }
+
+  if (allowSharedKeyFallback) {
+    try {
+      const session = await oxy.signInWithSharedIdentity();
+      if (session?.accessToken) {
+        return session.accessToken;
+      }
+    } catch (error) {
+      logger.debug(
+        'Shared-key refresh fallback failed',
+        { component: 'refresh', method: 'refreshPersistedSession' },
+        error,
+      );
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Build the reactive `AuthRefreshHandler` (arm 1 + arm 2). Install it via
+ * {@link installAuthRefreshHandler} or directly on
+ * `oxy.httpService.setAuthRefreshHandler`. `HttpService` owns single-flight
+ * dedup + cooldown, so the timer, the request-time preflight, and a 401 all
+ * collapse to one network attempt.
+ */
+export function createAuthRefreshHandler(deps: RefreshDeps): AuthRefreshHandler {
+  return async (_reason: AuthRefreshReason): Promise<string | null> => {
+    return refreshPersistedSession(deps);
+  };
+}
+
+/**
+ * Install the unified refresh handler on the owner client's `HttpService`.
+ * Returns a disposer that removes it.
+ */
+export function installAuthRefreshHandler(deps: RefreshDeps): () => void {
+  deps.oxy.httpService.setAuthRefreshHandler(createAuthRefreshHandler(deps));
+  return () => {
+    deps.oxy.httpService.setAuthRefreshHandler(null);
+  };
+}
+
+/** Handle returned by {@link startTokenRefreshScheduler}; `dispose()` tears it down. */
+export interface TokenRefreshSchedulerHandle {
+  dispose(): void;
+}
+
+/**
+ * Start the proactive refresh scheduler against `oxy`.
+ *
+ * Schedules a single timer to fire {@link TOKEN_REFRESH_LEAD_MS} before the
+ * current access token's `exp`, calling
+ * `oxy.httpService.refreshAccessToken('preflight')` (which runs the installed
+ * handler; deduped + cooldown-guarded). After every attempt it reschedules
+ * from the possibly-rotated token. It also reschedules whenever the token
+ * changes (a sign-out that clears the token cancels the timer) and, on web
+ * tab-focus, 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 or an opaque/no-`exp` token — the
+ * reactive 401 path stays the only refresh trigger in that case. The timer is
+ * `.unref?.()`-ed so it never keeps a Node/Jest event loop alive.
+ */
+export function startTokenRefreshScheduler(oxy: OxyServices): TokenRefreshSchedulerHandle {
+  let disposed = false;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  // 0 = no active backoff; grows on consecutive failures, resets on success /
+  // token change. Keeps a failing refresh from re-arming at zero delay.
+  let failureBackoffMs = 0;
+
+  const clearTimer = (): void => {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  };
+
+  /** Arm the timer for `delayMs`, flooring at {@link MIN_SCHEDULE_DELAY_MS} and capping at the int32 max. */
+  const armTimer = (delayMs: number): void => {
+    clearTimer();
+    const clamped = Math.min(Math.max(delayMs, MIN_SCHEDULE_DELAY_MS), MAX_TIMEOUT_DELAY_MS);
+    timer = setTimeout(runRefresh, clamped);
+    // Never keep a Node/Jest event loop alive for a background refresh timer.
+    timer.unref?.();
+  };
+
+  /** Schedule the next refresh from the current token's expiry (the healthy path). */
+  const scheduleFromExpiry = (): void => {
+    clearTimer();
+    if (disposed || !oxy.getAccessToken()) {
+      return;
+    }
+    const expSeconds = oxy.getAccessTokenExpiry();
+    if (expSeconds === null) {
+      return;
+    }
+    armTimer(expSeconds * 1000 - Date.now() - TOKEN_REFRESH_LEAD_MS);
+  };
+
+  const runRefresh = (): void => {
+    // Clear any pending timer up front so an out-of-band trigger (focus) plus
+    // a fired timer can never double-run.
+    clearTimer();
+    void oxy.httpService.refreshAccessToken('preflight')
+      .then((token) => Boolean(token))
+      .catch(() => false)
+      .then((ok) => {
+        if (disposed) {
+          return;
+        }
+        if (ok) {
+          // Success — drop any backoff and re-arm from the rotated token's exp.
+          failureBackoffMs = 0;
+          scheduleFromExpiry();
+          return;
+        }
+        // Failure — back off (never re-arm at zero) and retry.
+        failureBackoffMs =
+          failureBackoffMs === 0
+            ? MIN_FAILURE_BACKOFF_MS
+            : Math.min(failureBackoffMs * 2, MAX_FAILURE_BACKOFF_MS);
+        armTimer(failureBackoffMs);
+      });
+  };
+
+  /** Public (re)schedule entry: a fresh token / focus signal — drop backoff and arm from expiry. */
+  const schedule = (): void => {
+    failureBackoffMs = 0;
+    scheduleFromExpiry();
+  };
+
+  const onFocus = (): void => {
+    if (disposed || !oxy.getAccessToken()) {
+      return;
+    }
+    const expSeconds = oxy.getAccessTokenExpiry();
+    if (expSeconds === null) {
+      return;
+    }
+    const remainingMs = expSeconds * 1000 - Date.now();
+    if (remainingMs <= TOKEN_REFRESH_LEAD_MS) {
+      runRefresh();
+    } else {
+      schedule();
+    }
+  };
+
+  const unsubscribeTokens = oxy.onTokensChanged(() => {
+    if (!disposed) {
+      schedule();
+    }
+  });
+
+  let removeFocusListener: (() => void) | null = null;
+  if (typeof document !== 'undefined') {
+    const handler = (): void => {
+      if (document.visibilityState === 'visible') {
+        onFocus();
+      }
+    };
+    document.addEventListener('visibilitychange', handler);
+    removeFocusListener = () => document.removeEventListener('visibilitychange', handler);
+  }
+
+  schedule();
+
+  return {
+    dispose(): void {
+      disposed = true;
+      clearTimer();
+      unsubscribeTokens();
+      removeFocusListener?.();
+      removeFocusListener = null;
+    },
+  };
+}