@oxyhq/core 5.5.0 → 7.0.0

package/dist/types/models/interfaces.d.ts

@@ -2,20 +2,6 @@ import type { UserNameResponse } from '@oxyhq/contracts';
 export interface OxyConfig {
     baseURL: string;
     cloudURL?: string;
-    /**
-     * Base URL the SDK's first-party session/refresh calls target.
-     *
-     * Per the 2026 session architecture (docs/SESSION-ARCHITECTURE.md), every app
-     * keeps its OWN first-party session on its OWN domain. For non-`oxy.so` apps
-     * this is the app's own same-site backend (e.g. `https://api.mention.earth`),
-     * whose session bridge forwards the user's refresh credential to
-     * `api.oxy.so`. For `*.oxy.so` apps this is omitted and falls back to
-     * `baseURL` (`https://api.oxy.so`), so their behavior is unchanged.
-     *
-     * Resolve via {@link OxyServices.getSessionBaseUrl}; when unset it returns
-     * `baseURL`. This is purely additive — no refresh/auth logic reads it yet.
-     */
-    sessionBaseUrl?: string;
     authWebUrl?: string;
     authRedirectUri?: string;
     /**
@@ -110,7 +96,6 @@ export interface User {
     phone?: string;
     address?: string;
     birthday?: string;
-    location?: string;
     website?: string;
     createdAt?: string;
     updatedAt?: string;
@@ -584,55 +569,3 @@ export interface UpdateDeviceNameResponse {
     message: string;
     deviceName: string;
 }
-/**
- * Minimal user shape included in a `RefreshAllAccount` entry. The server
- * projects a small whitelist (`username name avatar email color`) so the
- * client can render the account chooser without an extra `/users/me` round
- * trip per account.
- *
- * `avatar` and `color` are `string | null` because they are stored as nullable
- * fields in the user document.
- */
-export interface RefreshAllAccountUser {
-    id: string;
-    username: string;
-    /**
-     * Structured human name as emitted by `formatUserResponse` (the canonical
-     * {@link UserNameResponse} `{ first?, last?, full? }` subdocument), NOT a bare
-     * string. The server projects `name` verbatim from the user document. The
-     * single source of truth is `@oxyhq/contracts`.
-     */
-    name: UserNameResponse;
-    avatar?: string | null;
-    email?: string;
-    color?: string | null;
-}
-/**
- * One rotated account entry returned by `POST /auth/refresh-all`. `authuser` is
- * the device-local slot index (0..N-1) the cookie was bound to.
- */
-export interface RefreshAllAccount {
-    authuser: number;
-    accessToken: string;
-    expiresAt: string;
-    sessionId: string;
-    user: RefreshAllAccountUser | null;
-}
-/**
- * Wire shape of `POST /auth/refresh-all`. Always 200 with a (possibly empty)
- * accounts array — 401 means "no accounts signed in on this device" and is
- * normalised to `{ accounts: [] }` at the SDK layer.
- */
-export interface RefreshAllResponse {
-    accounts: RefreshAllAccount[];
-}
-/**
- * Wire shape of `POST /auth/refresh` (single-slot refresh, optionally targeting
- * a specific `?authuser=N` slot). The server always includes the numeric slot in
- * the response.
- */
-export interface RefreshCookieResponse {
-    accessToken: string;
-    expiresAt: string;
-    authuser: number;
-}

package/dist/types/models/session.d.ts

@@ -7,11 +7,10 @@ export interface ClientSession {
     userId?: string;
     isCurrent?: boolean;
     /**
-     * Web-only: the device-local refresh-cookie slot index (0..N) that backs
-     * this session. Populated from `POST /auth/refresh-all` and from login /
-     * signup / fedcm-exchange responses. Required for per-session web token
-     * refresh via `refreshTokenViaCookie({ authuser })` without a bearer token.
-     * Absent on native (RN uses the bearer-protected session id directly).
+     * The account's ordinal slot (0..N) within the device's account set
+     * (`SessionAccount.authuser` in `@oxyhq/contracts`), projected from the
+     * device-first `DeviceSessionState` — used purely for stable Google-style
+     * account-chooser ordering, not for any token-refresh mechanism.
      */
     authuser?: number;
 }

package/dist/types/server/index.d.ts

@@ -23,5 +23,5 @@ export type { SafeFetchOptions, SafeFetchResult, SsrfCheckFail, SsrfCheckOk, Ssr
 export { createOxyCors } from './cors';
 export type { OxyCorsOptions } from './cors';
 export { verifySecret } from './verifySecret';
-export { registrableApex } from '../utils/fapiAutoDetect';
+export { registrableApex } from '../utils/registrableApex';
 export { SSO_CALLBACK_PATH } from '../utils/ssoBounce';

package/dist/types/session/SessionClient.d.ts

@@ -1,7 +1,7 @@
 import { type DeviceSessionState } from '@oxyhq/contracts';
 import type { MinimalSocket, SocketIOFactory } from './socketLoader';
 export interface TokenTransport {
-    /** Ensure this app holds a per-domain access token for state.activeAccountId (mint via FedCM/silent/sso/keychain). Best-effort. */
+    /** Ensure this app holds a per-domain access token for state.activeAccountId (mint via the persisted refresh family / shared keychain). Best-effort. */
     ensureActiveToken(state: DeviceSessionState): Promise<void>;
 }
 export interface SessionClientHost {
@@ -16,6 +16,16 @@ export interface SessionClientHost {
 }
 export interface SessionClientOptions {
     transport?: TokenTransport;
+    /**
+     * Invoked when an APPLIED state has zero accounts — i.e. a device
+     * signout-all removed the last account from this device set. Providers use
+     * this to clear the persisted {@link AuthStateStore} so a reload does not
+     * try to restore a session that no longer exists on the device.
+     *
+     * Only fires when a state is actually applied (revision advanced), never on
+     * a stale/rejected push. Exceptions thrown by the callback are isolated.
+     */
+    onUnauthenticated?: () => void;
     /**
      * Statically-injected `socket.io-client` factory (its `io` export).
      * `@oxyhq/services` and `@oxyhq/auth` list `socket.io-client` as a real
@@ -60,6 +70,21 @@ export declare class SessionClient {
         all: true;
     }): Promise<void>;
     addCurrentAccount(): Promise<void>;
+    /**
+     * Register the just-signed-in account into the device set AND make it the
+     * ACTIVE account — the explicit user-intent activation a sign-in UI performs.
+     *
+     * `addCurrentAccount` alone honors the server's `activate:'if-empty'` policy
+     * (a new account does NOT steal focus from an already-active one), which is
+     * correct for a background/silent add but wrong right after a deliberate
+     * sign-in. This adds, then switches to the target so the UI lands on the
+     * account the user just authenticated.
+     *
+     * @param accountId - The signed-in account id (e.g. `session.user.id`). When
+     *   omitted, falls back to the host's current-account ref. If neither
+     *   resolves, the add still applies and no switch is performed.
+     */
+    registerAndActivate(accountId?: string): Promise<void>;
     start(): Promise<void>;
     stop(): void;
     private connectSocket;

package/dist/types/session/authStateStore.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 declare 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 declare const DEVICE_TOKEN_STORAGE_KEY = "oxy.device.v1";
+/**
+ * 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 declare function createMemoryAuthStateStore(): AuthStateStore;
+/**
+ * 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 declare function createWebAuthStateStore(): AuthStateStore;
+/**
+ * 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 declare function createNativeAuthStateStore(storage: NativeKeyValueStorage): AuthStateStore;

package/dist/types/session/refresh.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 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 } from '../HttpService';
+import type { AuthStateStore } from './authStateStore';
+/**
+ * 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 declare const TOKEN_REFRESH_LEAD_MS = 60000;
+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 declare function refreshPersistedSession(deps: RefreshDeps): Promise<string | 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 declare function createAuthRefreshHandler(deps: RefreshDeps): AuthRefreshHandler;
+/**
+ * Install the unified refresh handler on the owner client's `HttpService`.
+ * Returns a disposer that removes it.
+ */
+export declare function installAuthRefreshHandler(deps: RefreshDeps): () => void;
+/** 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 declare function startTokenRefreshScheduler(oxy: OxyServices): TokenRefreshSchedulerHandle;

package/dist/types/shared/utils/debugUtils.d.ts

@@ -12,7 +12,7 @@
 export declare const isDev: () => boolean;
 /**
  * Log a debug message (only in development)
- * @param prefix - Log prefix (e.g., '[FedCM]')
+ * @param prefix - Log prefix (e.g., '[ColdBoot]')
  * @param args - Arguments to log
  */
 export declare const debugLog: (prefix: string, ...args: unknown[]) => void;
@@ -30,12 +30,12 @@ export declare const debugWarn: (prefix: string, ...args: unknown[]) => void;
 export declare const debugError: (prefix: string, ...args: unknown[]) => void;
 /**
  * Create a namespaced debug logger
- * @param namespace - Logger namespace (e.g., 'FedCM', 'SilentAuth')
+ * @param namespace - Logger namespace (e.g., 'ColdBoot', 'DeviceAuth')
  * @returns Object with log, warn, error methods
  *
  * @example
  * ```ts
- * const debug = createDebugLogger('FedCM');
+ * const debug = createDebugLogger('ColdBoot');
  * debug.log('Starting authentication');
  * debug.warn('Token expires soon');
  * debug.error('Authentication failed', error);

package/dist/types/utils/accountUtils.d.ts

@@ -2,7 +2,6 @@
  * Shared account types and pure helper functions.
  * Used by both @oxyhq/services (React Native) and @oxyhq/auth (Web) account stores.
  */
-import type { RefreshAllAccount } from '../models/interfaces';
 export interface QuickAccount {
     sessionId: string;
     userId?: string;
@@ -12,9 +11,8 @@ export interface QuickAccount {
     avatarUrl?: string;
     /**
      * Device-local account slot index, 0..N-1 (Google-style multi-account).
-     * Mirrors the server's `oxy_rt_${authuser}` cookie slot. Optional so that
-     * pre-multi-account QuickAccounts (sessionId-only, non-cookie auth on RN)
-     * remain valid; web flows always populate it after `refreshAllSessions`.
+     * Optional so that pre-multi-account QuickAccounts (sessionId-only) remain
+     * valid; the device session set populates it where available.
      */
     authuser?: number;
     /**
@@ -94,19 +92,6 @@ export declare const createQuickAccount: (sessionId: string, userData: {
     } | string;
     avatar?: string | null;
 }, existingAccount?: QuickAccount, getFileDownloadUrl?: (fileId: string, variant: string) => string) => QuickAccount;
-/**
- * Merge a fresh `/auth/refresh-all` snapshot into an existing QuickAccount
- * list, preserving any cached fields (`avatarUrl`) for slots that didn't
- * change. The fresh response is canonical: the resulting list contains EXACTLY
- * the slots present in `fresh`, sorted by `authuser` ascending. Stale stored
- * accounts that no longer appear in `fresh` are dropped (the server already
- * authoritatively cleared the corresponding cookie).
- *
- * @param stored Previously persisted QuickAccount list (any order).
- * @param fresh Server's authoritative refresh-all response.
- * @returns Canonical merged list, sorted by `authuser` asc.
- */
-export declare const mergeAccountsFromRefreshAll: (stored: QuickAccount[] | undefined, fresh: RefreshAllAccount[]) => QuickAccount[];
 /**
  * Return the account's preferred Bloom color preset, or `null` if it has no
  * preference. Centralises the `color ?? null` normalisation so consumers can

package/dist/types/utils/authWebUrl.d.ts

@@ -1,42 +1,16 @@
 /**
- * Central IdP (auth web) URL resolution for cross-domain SSO.
+ * Central IdP apex constant.
  *
- * The Oxy ecosystem runs a single, central Identity Provider at
- * `auth.oxy.so`. For TRUE central cross-domain SSO (Google/Meta/Clerk style),
- * FedCM and the opaque-code SSO bounce always target this one origin — it owns
- * the host-only `fedcm_session` cookie and the central session store reachable
- * via `api.oxy.so`. Relying Parties (mention.earth, homiio.com, alia.onl, …)
- * delegate to it rather than standing up a per-apex IdP.
- *
- * This module is intentionally pure: it performs no DOM access, reads no
- * `window`/`location`, and has no side effects. It is the single source of
- * truth for the central IdP origin so call sites never hardcode the literal.
- *
- * Note: this is distinct from `autoDetectAuthWebUrl` (per-apex `auth.<rp-apex>`
- * derivation). The central-SSO path deliberately does NOT auto-detect per-apex
- * IdPs — it is central only. An explicitly-configured `authWebUrl` still wins.
+ * The client SSO/FedCM resolvers (`resolveCentralAuthUrl`, `CENTRAL_AUTH_URL`)
+ * were removed in the device-first / legacy-final cutovers. The lone survivor is
+ * `CENTRAL_IDP_APEX`, kept because it has a LIVE consumer —
+ * `@oxyhq/core/server`'s CORS helper (`server/cors.ts`'s `createOxyCors`)
+ * auto-allows `*.oxy.so` from it. That CORS use is permanent, so this stays
+ * past the SSO/FedCM teardown.
  */
 /**
  * The registrable apex (eTLD+1) of the Oxy ecosystem's central Identity
- * Provider. The central IdP is reachable at `auth.${CENTRAL_IDP_APEX}` and the
- * ID-token assertion issuer is always `https://auth.${CENTRAL_IDP_APEX}`
- * regardless of which per-apex `auth.<rp>` host served a given request.
- *
- * Kept as a standalone constant so the IdP worker and the SDK derive the same
- * literal from one source of truth (the worker imports it to brand assertions).
+ * Provider, reachable at `auth.${CENTRAL_IDP_APEX}`. Single source of truth so
+ * the CORS helper (and anything else that needs the central apex) never drifts.
  */
 export declare const CENTRAL_IDP_APEX = "oxy.so";
-/**
- * The canonical central Identity Provider origin for the Oxy ecosystem.
- * No trailing slash. Derived from {@link CENTRAL_IDP_APEX} so the apex and the
- * full origin never drift apart.
- */
-export declare const CENTRAL_AUTH_URL = "https://auth.oxy.so";
-/**
- * Resolve the central IdP origin, honouring an explicit override.
- *
- * @param explicit - A caller-supplied auth web URL, or `undefined`/empty to use
- *   the central default. An explicit non-empty value always wins.
- * @returns The explicit value when provided, otherwise {@link CENTRAL_AUTH_URL}.
- */
-export declare function resolveCentralAuthUrl(explicit?: string): string;

package/dist/types/utils/coldBoot.d.ts

@@ -3,19 +3,21 @@
  * authentication resolution.
  *
  * On a fresh page load / app launch the SDK may have several ways to recover an
- * existing session (silent FedCM, a persisted refresh token, a cross-domain
- * claim, a redirect SSO return, ...). They must be attempted in a deterministic
- * order*, and the FIRST one that yields a session wins — every later step is
- * skipped. This module encodes exactly that contract and nothing else.
+ * existing session (a persisted refresh-token family, a shared-keychain
+ * identity, a cross-domain boot-fragment return, ...). They must be attempted
+ * in a deterministic order, and the FIRST one that yields a session wins —
+ * every later step is skipped. This module encodes exactly that contract and
+ * nothing else.
  *
  * Design constraints (all enforced):
  *   - PURE: no DOM, no `navigator`, no `window`, no React, no platform globals.
  *   - NO module-level mutable state. Every call to {@link runColdBoot} is fully
  *     self-contained, so it is safe under bundler re-evaluation (e.g. the Metro
- *     web bundle, which is precisely why the FedCM silent-SSO guard had to live
- *     in consumers rather than a core singleton).
- *   - Architecture-agnostic: both candidate cross-domain SSO designs consume
- *     this same primitive; it knows nothing about HOW a step resolves a session.
+ *     web bundle — the reason any run-once guard for a step must live in the
+ *     calling consumer, never in a core module-level singleton).
+ *   - Architecture-agnostic: it knows nothing about HOW a step resolves a
+ *     session; `runSessionColdBoot` (`boot/coldBootV2.ts`) is the current
+ *     device-first consumer.
  *
  * A step is skipped (without running) when its `enabled` predicate returns
  * false. Any thrown error — from either `enabled` or `run` — is reported via
@@ -92,15 +94,16 @@ export interface RunColdBootOptions<S> {
      * fails to settle before the deadline, the runner abandons the await for that
      * step (reporting it via `onStepDeadline`) and CONTINUES to the next step,
      * each now racing against an already-expired deadline. This is deliberate:
-     * the runner keeps iterating so the TERMINAL step (e.g. the `/sso` bounce,
-     * whose `run()` performs its side effect synchronously before its first
-     * `await`) still gets to fire. A step that has nothing to contribute after
-     * the deadline simply doesn't settle and is skipped in turn.
+     * the runner keeps iterating so the TERMINAL step (e.g. `coldBootV2`'s
+     * `bootstrap-hop`, whose `run()` performs its navigation side effect
+     * synchronously before its first `await`) still gets to fire. A step that
+     * has nothing to contribute after the deadline simply doesn't settle and is
+     * skipped in turn.
      *
      * Per-step timeouts inside `run()` remain the first line of defense and
      * should keep every step well under this budget on a healthy load; this only
-     * trips when one of them regresses (the production FedCM-silent hang). When
-     * omitted there is no overall deadline.
+     * trips when one of them regresses (a step hanging past its own timeout).
+     * When omitted there is no overall deadline.
      */
     readonly overallDeadlineMs?: number;
     /**

package/dist/types/utils/platform.d.ts

@@ -33,3 +33,17 @@ export declare function isAndroid(): boolean;
  * This allows lazy detection in environments where react-native is available
  */
 export declare function setPlatformOS(os: PlatformOS): void;
+/**
+ * True only in a real web browser (a DOM is present), false on React Native
+ * and Node/SSR.
+ *
+ * Native defines a global `window` but no `document`, so the DOM probe — not a
+ * bare `window` check — is the reliable discriminator. This is the single
+ * source of truth consumed by `@oxyhq/services` and `@oxyhq/auth` (both dropped
+ * their local copies), so every consumer shares the exact same predicate.
+ *
+ * NOTE: this is a live runtime probe (not the cached `getPlatformOS()` verdict)
+ * because it must reflect the actual DOM availability at call time in the
+ * consumer's bundle.
+ */
+export declare function isWebBrowser(): boolean;

package/dist/types/utils/registrableApex.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Registrable-apex (eTLD+1) host kernel.
+ *
+ * The client FAPI auto-detection helper was removed in the device-first cutover
+ * (which is why this file is now named for what it actually is, not the old
+ * `fapiAutoDetect`). What survives is the pure registrable-domain kernel, still
+ * used server-side by the api's device-first same-apex trust checks
+ * (`deviceAuth.ts`'s `POST /auth/device/web-session`, via `sameSite.ts`'s
+ * `isSameSiteTrustedRequest`) and the `@oxyhq/core/server` CORS/re-export layer.
+ *
+ * `registrableApex` is NOT legacy — the device-first same-apex check is a live
+ * consumer, so this kernel stays regardless of the SSO/FedCM removal.
+ */
+/**
+ * Compute the bare registrable apex (eTLD+1) of a hostname using the Public
+ * Suffix List, including private hosted suffixes.
+ *
+ * Performs NO protocol handling and builds NO URL — it only answers "what is
+ * the registrable domain of this host, or is that undefinable?".
+ *
+ * Returns `null` (apex undefinable) for:
+ *   - empty input;
+ *   - IPv4 literals (`192.168.1.10`);
+ *   - IPv6 literals or any host carrying a port (`[::1]`, anything with `:`);
+ *   - single-label hosts (`intranet`, `localhost`);
+ *   - public suffixes without a registrable label (e.g. `co.uk`, `github.io`).
+ *
+ * @param hostname - A bare hostname (no scheme), e.g. `www.mention.earth`.
+ * @returns The eTLD+1 (`mention.earth`), or `null` when undefinable.
+ */
+export declare function registrableApex(hostname: string): string | null;