@oxyhq/core 9.2.1 → 9.2.3

package/dist/types/HttpService.d.ts

@@ -13,6 +13,7 @@
  * - Request queuing
  */
 import type { OxyConfig } from './models/interfaces';
+import type { DeviceSecretMintOutcome } from './session/refresh';
 export type AuthRefreshReason = 'preflight' | 'response-401';
 export type AuthRefreshHandler = (reason: AuthRefreshReason) => Promise<string | null>;
 export type AccessTokenProvider = () => string | null;
@@ -77,6 +78,7 @@ export declare class HttpService {
     private tokenRefreshCooldownUntil;
     private authRefreshHandler;
     private accessTokenProvider;
+    private deviceSecretMintInFlight;
     /**
      * Epoch (ms) before which a cache-size telemetry warning must not be
      * re-emitted. Throttles the {@link CACHE_SOFT_MAX_ENTRIES} warning to at most
@@ -208,6 +210,25 @@ export declare class HttpService {
      */
     private getAuthHeader;
     refreshAccessToken(reason: AuthRefreshReason): Promise<string | null>;
+    /**
+     * PROCESS-WIDE single-flight for the rotating device-secret mint
+     * (`POST /session/device/token`).
+     *
+     * The server rotates the presented `deviceSecret` on every successful mint, so
+     * two concurrent mints would double-rotate and the durable store could end up
+     * holding a superseded secret → a later cold-boot mint 401s → the user is
+     * signed out. Every mint lane (the re-mint handler behind `refreshAccessToken`,
+     * the device-first cold boot, the socket token transport, the tab-focus
+     * reconcile) funnels its `refreshDeviceSecretArm` call through here, so
+     * concurrent callers await the SAME in-flight mint and all receive its result —
+     * exactly one server rotation.
+     *
+     * Distinct from {@link tokenRefreshPromise} (which dedups the FULL re-mint
+     * handler incl. the native shared-key arm + the failure cooldown): this inner
+     * guard serializes the rotation itself across BOTH the handler and the
+     * handler-independent cold boot, which never runs through `refreshAccessToken`.
+     */
+    runSingleFlightDeviceSecretMint(mint: () => Promise<DeviceSecretMintOutcome>): Promise<DeviceSecretMintOutcome>;
     /**
      * Unwrap standardized API response format
      */

package/dist/types/boot/sessionColdBoot.d.ts

@@ -7,12 +7,16 @@
  * the app renders with a "Sign in with Oxy" button.
  *
  * Ordered steps (first to yield a session wins):
- *   1. `device-secret-mint` (web + native) — the zero-cookie transport: when the
+ *   1. `warm-token-plant` (web + native) — the fastest path: when the persisted
+ *      store still holds a warm access token that is valid for more than the
+ *      refresh lead window, plant it and yield the session with NO network
+ *      round-trip. The background scheduler rotates it shortly after.
+ *   2. `device-secret-mint` (web + native) — the zero-cookie transport: when the
  *      origin persisted a `deviceId` + `deviceSecret`, mint a short access token
  *      with a single bearer-less POST to `/session/device/token` (no cookie, no
  *      navigation) and rotate the secret in-use.
- *   2. `shared-key-signin` (native) — re-mint from the shared-keychain identity.
- *   3. Signed out.
+ *   3. `shared-key-signin` (native) — re-mint from the shared-keychain identity.
+ *   4. Signed out.
  *
  * ESM-safe (no `require()`); no react/react-native/expo imports.
  */

package/dist/types/index.d.ts

@@ -90,7 +90,7 @@ export { buildIdpHubOrigin, buildHubSyncUrl, isIdpHubOrigin, isOfficialWebOrigin
 export { syncHubAfterSignIn, redeemHubTicketOnHub, } from './session/hubSync';
 export type { SyncHubAfterSignInOptions } from './session/hubSync';
 export { SessionClient } from './session/SessionClient';
-export type { TokenTransport, SessionClientHost, SessionClientOptions, DeviceCredential } from './session/SessionClient';
+export type { TokenTransport, SessionClientHost, SessionClientOptions, DeviceCredential, SessionStateOrigin } from './session/SessionClient';
 export type { SocketIOFactory, MinimalSocket } from './session/socketLoader';
 export { createSessionClientHost } from './session/sessionClientHost';
 export { createSessionClient } from './session/createSessionClient';
@@ -101,8 +101,8 @@ export { AccountDialogController, createAccountDialogController, } from './sessi
 export type { AccountDialogControllerOptions, AccountDialogSnapshot, AccountDialogView, SignInFlowPhase, SignInFlowState, } from './session/accountDialogController';
 export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthStateStore, AUTH_STATE_STORAGE_KEY, } from './session/authStateStore';
 export type { PersistedAuthState, AuthStateStore, NativeKeyValueStorage, } from './session/authStateStore';
-export { refreshPersistedSession, createAuthRefreshHandler, installAuthRefreshHandler, startTokenRefreshScheduler, TOKEN_REFRESH_LEAD_MS, } from './session/refresh';
-export type { RefreshDeps, TokenRefreshSchedulerHandle } from './session/refresh';
+export { refreshPersistedSession, refreshDeviceSecretArm, createAuthRefreshHandler, installAuthRefreshHandler, startTokenRefreshScheduler, TOKEN_REFRESH_LEAD_MS, } from './session/refresh';
+export type { RefreshDeps, TokenRefreshSchedulerHandle, DeviceSecretMintOutcome } from './session/refresh';
 export { runSessionColdBoot } from './boot/sessionColdBoot';
 export type { RunSessionColdBootOptions, SignedOutReason, DeviceBootSession, } from './boot/sessionColdBoot';
 export { packageInfo } from './constants/version';

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

@@ -4,6 +4,21 @@ export interface TokenTransport {
     /** 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>;
 }
+/**
+ * Where an applied device state came from, so consumers can decide how
+ * AUTHORITATIVE a zero-account ("signed out") verdict is:
+ *  - `request` — the response to a direct REST call this client made
+ *    (`bootstrap` / `switch` / `signOut` / `add`). A stable, server-authoritative
+ *    verdict: an empty state here reflects a real sign-out or revocation, so the
+ *    durable device credential MAY be erased.
+ *  - `push` — an out-of-band Socket.IO `session_state` broadcast. Potentially
+ *    transient (a reconnect race / another device's mutation), so an empty state
+ *    here must NOT erase THIS origin's durable device credential — only clear the
+ *    local UI session. A dead credential re-mints to `no_active_session` and
+ *    resolves signed-out cleanly on the next boot; a wrongly-erased one cannot be
+ *    recovered without a fresh sign-in.
+ */
+export type SessionStateOrigin = 'request' | 'push';
 export interface DeviceCredential {
     deviceId: string;
     deviceSecret: string;
@@ -25,13 +40,20 @@ export interface SessionClientOptions {
     /**
      * 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.
+     * this to clear local session state and, for a `request`-origin verdict, the
+     * persisted {@link AuthStateStore} so a reload does not try to restore a
+     * session that no longer exists on the device.
+     *
+     * The {@link SessionStateOrigin} is passed so the consumer can gate the
+     * DESTRUCTIVE credential wipe: a `push`-origin empty state (a socket broadcast,
+     * possibly a transient reconnect artifact) must NOT erase the durable device
+     * credential — only a `request`-origin verdict (a direct REST sign-out /
+     * revocation) is authoritative enough for that.
      *
      * 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;
+    onUnauthenticated?: (origin: SessionStateOrigin) => void;
     /**
      * Statically-injected `socket.io-client` factory (its `io` export).
      * `@oxyhq/services` lists `socket.io-client` as a real dependency and
@@ -56,12 +78,23 @@ export declare class SessionClient {
     private started;
     /** Same-origin cross-tab state-propagation channel; null on platforms without BroadcastChannel. */
     private channel;
+    /** App-facing subscriptions to named server-pushed socket events. */
+    private readonly serverEvents;
+    /** Event names already bound on the CURRENT socket instance. */
+    private readonly boundServerEvents;
     constructor(host: SessionClientHost, options?: SessionClientOptions);
     getState(): DeviceSessionState | null;
     subscribe(listener: StateListener): () => void;
+    /**
+     * Subscribe to a named server-pushed Socket.IO event (e.g. `civic:attested`).
+     * Listeners survive reconnects and socket re-creation; the returned function
+     * unsubscribes. Payloads are delivered as-is — callers validate shape.
+     */
+    onServerEvent(event: string, listener: (payload: unknown) => void): () => void;
+    private bindServerEvent;
     protected notify(): void;
     /** Validate + last-writer-wins by revision. Returns true if applied. */
-    protected applyState(raw: unknown): boolean;
+    protected applyState(raw: unknown, origin?: SessionStateOrigin): boolean;
     /**
      * Validate `{ state, activeToken }`, apply the state, and plant the active token host-side.
      * Token-planting is decoupled from whether `applyState` advanced the revision: a socket push

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

@@ -111,6 +111,16 @@ export interface AccountDialogControllerOptions {
      * `Linking.openURL`). Headless core never touches `window`/`Linking` itself.
      */
     openUrl?: (url: string) => void;
+    /**
+     * Optional "can this app open this URL scheme?" probe, symmetric to
+     * {@link openUrl}. When provided, `showQr` uses it to detect an installed
+     * Commons (`oxycommons://`) and, if present, deep-links straight into its
+     * approve screen via {@link openUrl} — while KEEPING the QR/polling active as
+     * the fallback. Injected by the provider (native: `Linking.canOpenURL`; web:
+     * absent/false). Headless core never touches `Linking` itself; when absent
+     * `showQr` behaves exactly as before (render QR only).
+     */
+    canOpenApp?: (url: string) => Promise<boolean>;
 }
 type SnapshotListener = (snapshot: AccountDialogSnapshot) => void;
 export declare class AccountDialogController {
@@ -124,6 +134,7 @@ export declare class AccountDialogController {
     private readonly authRedirectUri;
     private readonly pollIntervalMs;
     private readonly openUrl?;
+    private readonly canOpenApp?;
     private readonly listeners;
     private view;
     private graph;
@@ -232,6 +243,12 @@ export declare class AccountDialogController {
      * session committed. Requires `clientId`.
      */
     showQr(): Promise<void>;
+    /**
+     * When a `canOpenApp` probe is injected and reports Commons installed, open the
+     * approve deep link via the injected `openUrl`. Best-effort and non-blocking: a
+     * probe/open failure is logged and swallowed — the QR/polling fallback remains.
+     */
+    private maybeOpenCommons;
     /** Tear down the active sign-in device flow (timers + token) and reset to idle. */
     cancelSignIn(): void;
     /**

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

@@ -64,7 +64,21 @@ export interface PersistedAuthState {
  */
 export interface AuthStateStore {
     load(): Promise<PersistedAuthState | null>;
-    save(state: PersistedAuthState): Promise<void>;
+    /**
+     * Persist the credential blob and report whether it durably landed.
+     *
+     * Resolves `true` when the state is retained consistent with this store's
+     * durability guarantee — a durable backing whose read-back matched, or a
+     * degraded/in-memory store that held it in memory. Resolves `false` when a
+     * DURABLE backing was expected but the write did NOT land (read-back mismatch
+     * or a thrown write); the in-memory mirror still keeps the session live for
+     * this process, but it will be lost on reload.
+     *
+     * A lane persisting a ROTATED device secret (the mint's `nextDeviceSecret`)
+     * MUST treat `false` as fatal for that mint: it must NOT plant/advertise a
+     * session built on a secret that will not survive a reload.
+     */
+    save(state: PersistedAuthState): Promise<boolean>;
     clear(): Promise<void>;
 }
 /**
@@ -77,11 +91,32 @@ export interface NativeKeyValueStorage {
     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.
+ * Versioned DURABLE storage key. Holds ONLY the small, re-mint-critical fields
+ * (`sessionId`, `userId`, `deviceId`, `deviceSecret`) — never the large JWT
+ * `accessToken`. Keeping this blob small (<2KB) matters on Android
+ * `expo-secure-store`, whose backing store can silently fail to persist an
+ * oversize value; bundling the token here previously took the mint credential
+ * down with it on every write, losing the session on cold restart.
+ *
+ * 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.
+ *
+ * BACK-COMPAT: pre-split builds wrote the WHOLE state (including `accessToken` /
+ * `expiresAt`) into this single key. `load()` still reads those token fields
+ * from here when the warm key ({@link AUTH_STATE_TOKEN_STORAGE_KEY}) is absent,
+ * so upgrading users are not signed out; the next `save()` splits them apart.
  */
 export declare const AUTH_STATE_STORAGE_KEY = "oxy.auth.v1";
+/**
+ * Versioned BEST-EFFORT warm-token storage key. Holds the short-lived
+ * `{ accessToken, expiresAt }` pair only. Its write is genuinely non-fatal — a
+ * failure (quota / oversize keychain value) is swallowed because the session is
+ * fully re-mintable from the durable `deviceSecret`. Kept separate from
+ * {@link AUTH_STATE_STORAGE_KEY} so a failed token write can NEVER abort or
+ * corrupt the durable credential write.
+ */
+export declare const AUTH_STATE_TOKEN_STORAGE_KEY = "oxy.auth.token.v1";
 /**
  * A process-lifetime, in-memory {@link AuthStateStore}. Used directly for
  * tests/SSR and as the degraded fallback of the web store when `localStorage`
@@ -90,8 +125,9 @@ export declare const AUTH_STATE_STORAGE_KEY = "oxy.auth.v1";
  */
 export declare function createMemoryAuthStateStore(): AuthStateStore;
 /**
- * A `localStorage`-backed {@link AuthStateStore} under the versioned
- * {@link AUTH_STATE_STORAGE_KEY}.
+ * A `localStorage`-backed {@link AuthStateStore} split across the durable
+ * {@link AUTH_STATE_STORAGE_KEY} (mint credential) and the best-effort
+ * {@link AUTH_STATE_TOKEN_STORAGE_KEY} (warm access token).
  *
  * Resilience:
  *  - If `localStorage` is unreachable (sandboxed-iframe `SecurityError`, SSR),
@@ -107,8 +143,11 @@ 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.
+ * the SecureStore-backed adapter and passes it here. Persistence is split across
+ * the durable {@link AUTH_STATE_STORAGE_KEY} (mint credential) and the
+ * best-effort {@link AUTH_STATE_TOKEN_STORAGE_KEY} (warm access token) — the
+ * durable write is read-back-verified and its failure surfaced (not swallowed),
+ * while the warm-token write and all reads degrade gracefully exactly like the
+ * web store.
  */
 export declare function createNativeAuthStateStore(storage: NativeKeyValueStorage): AuthStateStore;

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

@@ -1,25 +1,3 @@
-/**
- * Unified token refresh — THE single access-token re-mint for web + native.
- *
- * The access token is short-lived; there is no refresh token. To keep a session
- * alive past the access token's TTL the client re-mints via the zero-cookie
- * device transport:
- *
- *  - `refreshPersistedSession` — arm 1 mints a fresh access token from the
- *    persisted `deviceId` + `deviceSecret` (`POST /session/device/token`),
- *    planting + persisting the rotated secret; arm 2 (native only) re-mints via
- *    the shared-keychain identity when there is no usable secret. It is used BOTH
- *    reactively (wrapped as the `AuthRefreshHandler` installed on `HttpService`)
- *    AND proactively (the scheduler below calls it).
- *  - `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 decoupled from any
- *    React type: re-mints ~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';
@@ -40,21 +18,79 @@ export interface RefreshDeps {
      */
     allowSharedKeyFallback?: boolean;
 }
+/**
+ * The outcome of ONE device-secret mint attempt (arm 1). Discriminated so both
+ * the re-mint handler and the cold boot can react per the transport contract
+ * without re-classifying the raw error:
+ *  - `ok` — minted, persisted the rotated secret, planted the token.
+ *  - `no-secret` — the store holds no `deviceId` + `deviceSecret` to mint from.
+ *  - `invalid-secret` — 401 `invalid_device_secret`: the presented secret
+ *    diverged (another tab/device rotated it past the grace window).
+ *  - `no-session` — 401 `no_active_session`: the device is known but has no live
+ *    session (authoritative signed-out).
+ *  - `transient` — network / 5xx; keep the secret, a later attempt can succeed.
+ *  - `persist-failed` — the mint succeeded (the SERVER rotated the secret) but
+ *    the rotated `nextDeviceSecret` could NOT be durably persisted. The token is
+ *    deliberately NOT planted: advertising a healthy session on a secret that
+ *    will not survive a reload is exactly the divergence that logs users out.
+ */
+export type DeviceSecretMintOutcome = {
+    status: 'ok';
+    token: string;
+    sessionId: string;
+    userId: string;
+} | {
+    status: 'no-secret';
+} | {
+    status: 'invalid-secret';
+} | {
+    status: 'no-session';
+} | {
+    status: 'transient';
+} | {
+    status: 'persist-failed';
+};
+/**
+ * Arm 1 — the rotating device-secret mint, run under the owning client's
+ * PROCESS-WIDE single-flight (`httpService.runSingleFlightDeviceSecretMint`).
+ *
+ * The server ROTATES the presented `deviceSecret` on every successful mint and
+ * the just-presented secret is valid only for a short grace window. If two lanes
+ * (cold boot, the proactive scheduler, a request-time preflight, a 401 retry,
+ * the socket token transport, or a tab-focus reconcile) minted concurrently they
+ * would double-rotate the server and the durable store could converge on the
+ * SUPERSEDED secret — after the grace window the next cold boot mint 401s and the
+ * user is signed out. Routing EVERY lane through this one single-flight makes
+ * concurrent callers await the SAME in-flight mint and all receive its result, so
+ * there is exactly one rotation and the store always converges on the true
+ * `current` secret.
+ *
+ * On success it persists `nextDeviceSecret` (read-back-verified) BEFORE planting
+ * the access token; a failed durable persist yields `persist-failed` WITHOUT
+ * planting. This function performs NO store mutation on failure — the caller
+ * applies the drop/clear policy (which differs web vs native) from the returned
+ * status.
+ */
+export declare function refreshDeviceSecretArm(deps: {
+    oxy: OxyServices;
+    store: AuthStateStore;
+}): Promise<DeviceSecretMintOutcome>;
 /**
  * Re-mint the persisted session and return the fresh access token, or `null`
  * when no arm could produce one.
  *
- * Arm 1 (`POST /session/device/token`): if the store holds a `deviceId` +
- * `deviceSecret`, mint — on success plant + persist the rotated secret. A 401
- * means the secret is diverged (`invalid_device_secret`) or the device has no
- * live session (`no_active_session`): drop the secret so the mint lane stops (or
- * clear the store on web, where there is no fallback). A transient error leaves
- * the store and returns `null`.
+ * Arm 1 (`POST /session/device/token`, via {@link refreshDeviceSecretArm}): mint
+ * from the persisted `deviceId` + `deviceSecret`. On a 401 the secret is diverged
+ * or the device has no live session: drop the secret so the mint lane stops (or
+ * clear the store on web, where there is no fallback), then fall to arm 2 on
+ * native. A transient error — or a durable-persist failure — leaves the store and
+ * returns `null` WITHOUT falling to shared-key (those are not bad-secret signals).
  *
  * Arm 2 (native shared-keychain): when the secret is absent or was just rejected,
- * 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.
+ * re-mint via `signInWithSharedIdentity` (which plants tokens). On success the
+ * recovered `{deviceId, deviceSecret, …}` is PERSISTED so the fast device-secret
+ * lane is repopulated (mirrors the cold boot's `shared-key-signin` step) — an
+ * in-session shared-key recovery must not leave the fast-lane credential empty.
  */
 export declare function refreshPersistedSession(deps: RefreshDeps): Promise<string | null>;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "9.2.1",
+  "version": "9.2.3",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -94,7 +94,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "^0.13.1",
+    "@oxyhq/contracts": "^0.13.2",
     "@oxyhq/protocol": "^0.1.3",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",

package/src/HttpService.ts

@@ -22,6 +22,7 @@ import { isNative, getPlatformOS } from './utils/platform';
 import { isReactNative } from '@oxyhq/protocol';
 import { computeIdentityTag, fnv1a32 } from './utils/cacheKey';
 import type { OxyConfig } from './models/interfaces';
+import type { DeviceSecretMintOutcome } from './session/refresh';
 
 /**
  * Check if we're running in a native app environment (React Native, not web)
@@ -234,6 +235,7 @@ export class HttpService {
   private tokenRefreshCooldownUntil: number = 0;
   private authRefreshHandler: AuthRefreshHandler | null = null;
   private accessTokenProvider: AccessTokenProvider | null = null;
+  private deviceSecretMintInFlight: Promise<DeviceSecretMintOutcome> | null = null;
 
   /**
    * Epoch (ms) before which a cache-size telemetry warning must not be
@@ -1061,6 +1063,35 @@ export class HttpService {
     return this.tokenRefreshPromise;
   }
 
+  /**
+   * PROCESS-WIDE single-flight for the rotating device-secret mint
+   * (`POST /session/device/token`).
+   *
+   * The server rotates the presented `deviceSecret` on every successful mint, so
+   * two concurrent mints would double-rotate and the durable store could end up
+   * holding a superseded secret → a later cold-boot mint 401s → the user is
+   * signed out. Every mint lane (the re-mint handler behind `refreshAccessToken`,
+   * the device-first cold boot, the socket token transport, the tab-focus
+   * reconcile) funnels its `refreshDeviceSecretArm` call through here, so
+   * concurrent callers await the SAME in-flight mint and all receive its result —
+   * exactly one server rotation.
+   *
+   * Distinct from {@link tokenRefreshPromise} (which dedups the FULL re-mint
+   * handler incl. the native shared-key arm + the failure cooldown): this inner
+   * guard serializes the rotation itself across BOTH the handler and the
+   * handler-independent cold boot, which never runs through `refreshAccessToken`.
+   */
+  runSingleFlightDeviceSecretMint(
+    mint: () => Promise<DeviceSecretMintOutcome>,
+  ): Promise<DeviceSecretMintOutcome> {
+    if (!this.deviceSecretMintInFlight) {
+      this.deviceSecretMintInFlight = mint().finally(() => {
+        this.deviceSecretMintInFlight = null;
+      });
+    }
+    return this.deviceSecretMintInFlight;
+  }
+
   /**
    * Unwrap standardized API response format
    */

package/src/boot/__tests__/sessionColdBoot.test.ts

@@ -10,6 +10,7 @@ import type { OxyServices } from '../../OxyServices';
 import type { DeviceTokenMintResponse } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../../models/session';
 import { runSessionColdBoot } from '../sessionColdBoot';
+import type { DeviceSecretMintOutcome } from '../../session/refresh';
 import { createMemoryAuthStateStore, type PersistedAuthState } from '../../session/authStateStore';
 
 interface OxyOverrides {
@@ -17,6 +18,19 @@ interface OxyOverrides {
   mintFromDeviceSecret?: OxyServices['mintFromDeviceSecret'];
 }
 
+/** A real device-secret mint single-flight matching HttpService's. */
+function makeMintSingleFlight(): (mint: () => Promise<DeviceSecretMintOutcome>) => Promise<DeviceSecretMintOutcome> {
+  let inFlight: Promise<DeviceSecretMintOutcome> | null = null;
+  return (mint) => {
+    if (!inFlight) {
+      inFlight = mint().finally(() => {
+        inFlight = null;
+      });
+    }
+    return inFlight;
+  };
+}
+
 function makeOxy(overrides: OxyOverrides = {}): { oxy: OxyServices; setTokens: jest.Mock } {
   const setTokens = jest.fn();
   const oxy = {
@@ -30,6 +44,8 @@ function makeOxy(overrides: OxyOverrides = {}): { oxy: OxyServices; setTokens: j
       ?? (async () => {
         throw new Error('mintFromDeviceSecret not stubbed');
       }),
+    // The device-secret-mint step runs through the client's single-flight.
+    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight() },
   } as unknown as OxyServices;
   return { oxy, setTokens };
 }
@@ -72,6 +88,109 @@ function seedCredStore(extra: Partial<PersistedAuthState> = {}) {
   };
 }
 
+describe('runSessionColdBoot — warm-token-plant', () => {
+  /** Comfortably beyond the 60s refresh lead window. */
+  const farFuture = () => new Date(Date.now() + 3_600_000).toISOString();
+
+  it('plants a still-valid warm token FIRST, skipping the mint round-trip', async () => {
+    const { store, seed } = seedCredStore({ accessToken: 'warm-access', expiresAt: farFuture() });
+    await seed();
+    const mintFromDeviceSecret = jest.fn(async () => MINT);
+    const { oxy, setTokens } = makeOxy({ mintFromDeviceSecret });
+    const saveSpy = jest.spyOn(store, 'save');
+    const onSession = jest.fn();
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, onSession });
+
+    expect(outcome).toEqual({ kind: 'session', via: 'warm-token-plant', session: expect.any(Object) });
+    expect(setTokens).toHaveBeenCalledWith('warm-access');
+    // The warm plant won before the mint lane — no network round-trip on first paint.
+    expect(mintFromDeviceSecret).not.toHaveBeenCalled();
+    // Session identity comes straight from the persisted owning session.
+    expect(onSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sessionId: 'sess-old',
+        userId: 'user-old',
+        accessToken: 'warm-access',
+        via: 'warm-token-plant',
+      }),
+    );
+    // Used AS-IS: the step never mints, rotates, or persists.
+    expect(saveSpy).not.toHaveBeenCalled();
+    expect(await store.load()).toMatchObject({ deviceSecret: 'ds-secret-orig', accessToken: 'warm-access' });
+  });
+
+  it('plants on native too (the step runs on both platforms)', async () => {
+    const { store, seed } = seedCredStore({ accessToken: 'warm-access', expiresAt: farFuture() });
+    await seed();
+    const mintFromDeviceSecret = jest.fn(async () => MINT);
+    const signInWithSharedIdentity = jest.fn(async () => null);
+    const { oxy, setTokens } = makeOxy({ mintFromDeviceSecret, signInWithSharedIdentity });
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: NATIVE });
+
+    expect(outcome).toMatchObject({ kind: 'session', via: 'warm-token-plant' });
+    expect(setTokens).toHaveBeenCalledWith('warm-access');
+    expect(mintFromDeviceSecret).not.toHaveBeenCalled();
+    expect(signInWithSharedIdentity).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ['within the refresh lead window', () => new Date(Date.now() + 30_000).toISOString()],
+    ['already expired', () => new Date(Date.now() - 1_000).toISOString()],
+    ['malformed (Date.parse NaN)', () => 'not-a-real-date'],
+  ])('skips to the mint lane when the warm token is %s', async (_label, expiresAt) => {
+    const { store, seed } = seedCredStore({ accessToken: 'warm-access', expiresAt: expiresAt() });
+    await seed();
+    const mintFromDeviceSecret = jest.fn(async () => MINT);
+    const { oxy, setTokens } = makeOxy({ mintFromDeviceSecret });
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB });
+
+    // Warm plant skipped → the unchanged mint lane resolved the session.
+    expect(outcome).toMatchObject({ kind: 'session', via: 'device-secret-mint' });
+    expect(mintFromDeviceSecret).toHaveBeenCalledWith('dev-mint', 'ds-secret-orig');
+    expect(setTokens).toHaveBeenCalledWith('access-minted');
+    // The stale warm token was NOT planted.
+    expect(setTokens).not.toHaveBeenCalledWith('warm-access');
+  });
+
+  it('skips (regression guard) when no accessToken is persisted → mint lane runs', async () => {
+    const { store, seed } = seedCredStore(); // deviceId/deviceSecret only, no warm token
+    await seed();
+    const mintFromDeviceSecret = jest.fn(async () => MINT);
+    const { oxy, setTokens } = makeOxy({ mintFromDeviceSecret });
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB });
+
+    expect(outcome).toMatchObject({ kind: 'session', via: 'device-secret-mint' });
+    expect(mintFromDeviceSecret).toHaveBeenCalledWith('dev-mint', 'ds-secret-orig');
+    expect(setTokens).toHaveBeenCalledWith('access-minted');
+  });
+
+  it('skips when a warm token is present but the owning sessionId/userId is missing', async () => {
+    // Device-only bootstrap blob: deviceId + deviceSecret but empty session identity.
+    const store = createMemoryAuthStateStore();
+    await store.save({
+      sessionId: '',
+      userId: '',
+      deviceId: 'dev-mint',
+      deviceSecret: 'ds-secret-orig',
+      accessToken: 'warm-access',
+      expiresAt: farFuture(),
+    });
+    const mintFromDeviceSecret = jest.fn(async () => MINT);
+    const { oxy, setTokens } = makeOxy({ mintFromDeviceSecret });
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB });
+
+    // No owning session → warm plant skips → the mint lane resolves it.
+    expect(outcome).toMatchObject({ kind: 'session', via: 'device-secret-mint' });
+    expect(setTokens).not.toHaveBeenCalledWith('warm-access');
+    expect(mintFromDeviceSecret).toHaveBeenCalled();
+  });
+});
+
 describe('runSessionColdBoot — device-secret-mint', () => {
   it('wins FIRST via the mint, persisting nextDeviceSecret BEFORE planting the token', async () => {
     const { store, seed } = seedCredStore();