@oxyhq/core 9.2.1 → 9.2.3

package/src/session/accountDialogController.ts

@@ -131,10 +131,27 @@ 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>;
 }
 
 const DEFAULT_POLL_INTERVAL_MS = 3000;
 
+/**
+ * Commons's custom URL scheme. Probed via the injected `canOpenApp` to detect an
+ * installed Commons on the same device; the `oxycommons://approve?...` deep link
+ * itself is the flow's `qrPayload`.
+ */
+const COMMONS_APP_SCHEME = 'oxycommons://';
+
 const IDLE_SIGN_IN: SignInFlowState = {
   phase: 'idle',
   authorizeCode: null,
@@ -160,6 +177,7 @@ export class AccountDialogController {
   private readonly authRedirectUri: string | null;
   private readonly pollIntervalMs: number;
   private readonly openUrl?: (url: string) => void;
+  private readonly canOpenApp?: (url: string) => Promise<boolean>;
 
   private readonly listeners = new Set<SnapshotListener>();
 
@@ -197,6 +215,7 @@ export class AccountDialogController {
     this.authRedirectUri = options.authRedirectUri ?? null;
     this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
     this.openUrl = options.openUrl;
+    this.canOpenApp = options.canOpenApp;
     this.snapshot = this.computeSnapshot();
   }
 
@@ -534,11 +553,37 @@ export class AccountDialogController {
         error: null,
       });
       this.scheduleNextPoll(handle.sessionToken);
+      // Same-device convenience: if Commons is installed (native only — `canOpenApp`
+      // is undefined/false on web), deep-link straight into its approve screen with
+      // the same `oxycommons://approve?...` payload the QR encodes. The QR + polling
+      // stay live as the fallback, so a user who dismisses the app-open still
+      // completes the sign-in by scanning.
+      void this.maybeOpenCommons(handle.qrPayload);
     } catch (error) {
       this.setSignIn({ ...IDLE_SIGN_IN, phase: 'error', error: errorMessage(error) });
     }
   }
 
+  /**
+   * 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 async maybeOpenCommons(qrPayload: string): Promise<void> {
+    if (!this.canOpenApp || !this.openUrl) return;
+    try {
+      if (await this.canOpenApp(COMMONS_APP_SCHEME)) {
+        this.openUrl(qrPayload);
+      }
+    } catch (error) {
+      logger.debug(
+        '[AccountDialogController] Commons deep-link probe failed (QR fallback active)',
+        { component: 'AccountDialogController' },
+        error,
+      );
+    }
+  }
+
   /** Tear down the active sign-in device flow (timers + token) and reset to idle. */
   cancelSignIn(): void {
     this.clearPollTimer();

package/src/session/authStateStore.ts

@@ -17,6 +17,8 @@
  * ESM-safe (no `require()`).
  */
 
+import { logger } from '../utils/loggerUtils';
+
 /**
  * The persisted session credential set for a single origin.
  *
@@ -66,7 +68,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>;
 }
 
@@ -81,12 +97,34 @@ export interface NativeKeyValueStorage {
 }
 
 /**
- * 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 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 const AUTH_STATE_TOKEN_STORAGE_KEY = 'oxy.auth.token.v1';
+
 /**
  * Parse + shape-validate a stored blob. Returns `null` for anything that is
  * not a well-formed {@link PersistedAuthState} (absent, malformed JSON, wrong
@@ -142,6 +180,104 @@ function deserialize(raw: string | null): PersistedAuthState | null {
   return state;
 }
 
+/** The parsed warm-token blob: the short-lived optimization fields only. */
+interface WarmToken {
+  accessToken?: string;
+  expiresAt?: string;
+}
+
+/**
+ * Parse the best-effort warm-token blob. Returns `null` for anything not a
+ * well-formed object so a corrupt warm entry simply forgoes the warm-boot
+ * optimization (the durable credential re-mints a fresh token).
+ */
+function parseWarmToken(raw: string | null): WarmToken | 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>;
+  const warm: WarmToken = {};
+  if (typeof candidate.accessToken === 'string' && candidate.accessToken.length > 0) {
+    warm.accessToken = candidate.accessToken;
+  }
+  if (typeof candidate.expiresAt === 'string' && candidate.expiresAt.length > 0) {
+    warm.expiresAt = candidate.expiresAt;
+  }
+  return warm;
+}
+
+/** Serialize ONLY the small, re-mint-critical fields for the durable key. */
+function serializeDurable(state: PersistedAuthState): string {
+  const durable: Record<string, string> = {
+    sessionId: state.sessionId,
+    userId: state.userId,
+  };
+  if (state.deviceId) {
+    durable.deviceId = state.deviceId;
+  }
+  if (state.deviceSecret) {
+    durable.deviceSecret = state.deviceSecret;
+  }
+  return JSON.stringify(durable);
+}
+
+/**
+ * Serialize the warm-token blob, or `null` when there is no token to persist
+ * (so the caller clears the warm key rather than writing an empty object).
+ */
+function serializeWarmToken(state: PersistedAuthState): string | null {
+  const warm: WarmToken = {};
+  if (state.accessToken) {
+    warm.accessToken = state.accessToken;
+  }
+  if (state.expiresAt) {
+    warm.expiresAt = state.expiresAt;
+  }
+  if (!warm.accessToken && !warm.expiresAt) {
+    return null;
+  }
+  return JSON.stringify(warm);
+}
+
+/**
+ * Compose the unchanged {@link PersistedAuthState} return shape from the two
+ * on-disk keys. `accessToken` / `expiresAt` come from the warm key when it is
+ * present; when the warm key is ABSENT the token fields fall back to whatever
+ * the durable blob carried — the pre-split combined `oxy.auth.v1` blob (BACK-COMPAT).
+ */
+function composeState(durableRaw: string | null, warmRaw: string | null): PersistedAuthState | null {
+  const state = deserialize(durableRaw);
+  if (!state) {
+    return null;
+  }
+  if (warmRaw !== null) {
+    // New split layout: the warm key is authoritative for the token fields.
+    // Drop anything the durable blob may have carried, then overlay the warm
+    // values (a warm key with no token → the session simply has no warm token).
+    delete state.accessToken;
+    delete state.expiresAt;
+    const warm = parseWarmToken(warmRaw);
+    if (warm?.accessToken) {
+      state.accessToken = warm.accessToken;
+    }
+    if (warm?.expiresAt) {
+      state.expiresAt = warm.expiresAt;
+    }
+  }
+  // else: BACK-COMPAT — the warm key is absent, so `deserialize` already applied
+  // any `accessToken` / `expiresAt` from the old combined blob.
+  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`
@@ -153,7 +289,9 @@ export function createMemoryAuthStateStore(): AuthStateStore {
   return {
     load: async () => current,
     save: async (state) => {
+      // Memory IS this store's durability backing — the write always lands.
       current = state;
+      return true;
     },
     clear: async () => {
       current = null;
@@ -180,8 +318,9 @@ function safeGetLocalStorage(): Storage | null {
 }
 
 /**
- * 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),
@@ -208,19 +347,54 @@ export function createWebAuthStateStore(): AuthStateStore {
         return sessionMirror;
       }
       try {
-        return deserialize(storage.getItem(AUTH_STATE_STORAGE_KEY));
+        return composeState(
+          storage.getItem(AUTH_STATE_STORAGE_KEY),
+          storage.getItem(AUTH_STATE_TOKEN_STORAGE_KEY),
+        );
       } catch {
         return null;
       }
     },
     save: async (state) => {
       sessionMirror = state; // mirror FIRST — authoritative even if persist fails
+      // Durable credential FIRST, then VERIFY it landed. The in-memory mirror
+      // keeps the session live for this page, but a failed DURABLE write means
+      // the mint credential will NOT survive a reload — surface it, never swallow.
+      let durablePersisted = false;
       try {
-        storage.setItem(AUTH_STATE_STORAGE_KEY, JSON.stringify(state));
+        const durableJson = serializeDurable(state);
+        storage.setItem(AUTH_STATE_STORAGE_KEY, durableJson);
+        durablePersisted = storage.getItem(AUTH_STATE_STORAGE_KEY) === durableJson;
+        if (!durablePersisted) {
+          logger.error(
+            '[authStateStore] durable credential read-back mismatch after save — the device credential did not persist; the session survives this process via the in-memory mirror but will be lost on reload',
+            undefined,
+            { component: 'authStateStore' },
+          );
+        }
+      } catch (error) {
+        logger.error(
+          '[authStateStore] durable credential persist threw — the device credential did not persist; the session survives this process via the in-memory mirror but will be lost on reload',
+          error,
+          { component: 'authStateStore' },
+        );
+      }
+      // Warm token AFTER, best-effort. Its failure is genuinely non-fatal (the
+      // durable credential re-mints a fresh token) and must never abort or
+      // corrupt the durable write above.
+      try {
+        const warmJson = serializeWarmToken(state);
+        if (warmJson) {
+          storage.setItem(AUTH_STATE_TOKEN_STORAGE_KEY, warmJson);
+        } else {
+          storage.removeItem(AUTH_STATE_TOKEN_STORAGE_KEY);
+        }
       } catch {
-        // Quota / private-mode / disabled storage — non-fatal. The session
-        // stays live via the in-memory mirror; only reload durability is lost.
+        // Quota / private-mode / disabled storage — non-fatal warm-boot loss only.
       }
+      // Report ONLY the durable-credential landing; the warm-token outcome above
+      // is intentionally excluded (it is a best-effort optimization).
+      return durablePersisted;
     },
     clear: async () => {
       sessionMirror = null;
@@ -229,6 +403,11 @@ export function createWebAuthStateStore(): AuthStateStore {
       } catch {
         // Non-fatal — see save().
       }
+      try {
+        storage.removeItem(AUTH_STATE_TOKEN_STORAGE_KEY);
+      } catch {
+        // Non-fatal — see save().
+      }
     },
   };
 }
@@ -237,9 +416,12 @@ export 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 function createNativeAuthStateStore(storage: NativeKeyValueStorage): AuthStateStore {
   // Same in-memory mirror as the web store — a locked/failed SecureStore write
@@ -251,18 +433,57 @@ export function createNativeAuthStateStore(storage: NativeKeyValueStorage): Auth
         return sessionMirror;
       }
       try {
-        return deserialize(await storage.getItem(AUTH_STATE_STORAGE_KEY));
+        const [durableRaw, warmRaw] = await Promise.all([
+          storage.getItem(AUTH_STATE_STORAGE_KEY),
+          storage.getItem(AUTH_STATE_TOKEN_STORAGE_KEY),
+        ]);
+        return composeState(durableRaw, warmRaw);
       } catch {
         return null;
       }
     },
     save: async (state) => {
       sessionMirror = state;
+      // Durable credential FIRST, then VERIFY. On Android SecureStore an
+      // oversize/failed write can resolve WITHOUT throwing, so a read-back is the
+      // only reliable proof. The mirror keeps the session live for this app run,
+      // but a failed DURABLE write means the mint credential will NOT survive a
+      // cold restart — surface it, never swallow.
+      let durablePersisted = false;
+      try {
+        const durableJson = serializeDurable(state);
+        await storage.setItem(AUTH_STATE_STORAGE_KEY, durableJson);
+        durablePersisted = (await storage.getItem(AUTH_STATE_STORAGE_KEY)) === durableJson;
+        if (!durablePersisted) {
+          logger.error(
+            '[authStateStore] durable credential read-back mismatch after save — the device credential did not persist (likely oversize SecureStore value); the session survives this app run via the in-memory mirror but will be lost on cold restart',
+            undefined,
+            { component: 'authStateStore' },
+          );
+        }
+      } catch (error) {
+        logger.error(
+          '[authStateStore] durable credential persist threw — the device credential did not persist; the session survives this app run via the in-memory mirror but will be lost on cold restart',
+          error,
+          { component: 'authStateStore' },
+        );
+      }
+      // Warm token AFTER, best-effort. Its failure is genuinely non-fatal (the
+      // durable credential re-mints a fresh token) and must never abort or
+      // corrupt the durable write above.
       try {
-        await storage.setItem(AUTH_STATE_STORAGE_KEY, JSON.stringify(state));
+        const warmJson = serializeWarmToken(state);
+        if (warmJson) {
+          await storage.setItem(AUTH_STATE_TOKEN_STORAGE_KEY, warmJson);
+        } else {
+          await storage.removeItem(AUTH_STATE_TOKEN_STORAGE_KEY);
+        }
       } catch {
-        // Non-fatal — session stays live via the in-memory mirror.
+        // Locked / oversize keychain — non-fatal warm-boot loss only.
       }
+      // Report ONLY the durable-credential landing; the warm-token outcome above
+      // is intentionally excluded (it is a best-effort optimization).
+      return durablePersisted;
     },
     clear: async () => {
       sessionMirror = null;
@@ -271,6 +492,11 @@ export function createNativeAuthStateStore(storage: NativeKeyValueStorage): Auth
       } catch {
         // Non-fatal.
       }
+      try {
+        await storage.removeItem(AUTH_STATE_TOKEN_STORAGE_KEY);
+      } catch {
+        // Non-fatal.
+      }
     },
   };
 }

package/src/session/refresh.ts

@@ -20,6 +20,7 @@
  *
  * Framework-free; no module-level mutable state.
  */
+import type { DeviceTokenMintResponse } from '@oxyhq/contracts';
 import type { OxyServices } from '../OxyServices';
 import type { AuthRefreshHandler, AuthRefreshReason } from '../HttpService';
 import type { AuthStateStore, PersistedAuthState } from './authStateStore';
@@ -71,68 +72,173 @@ 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 async function refreshDeviceSecretArm(deps: {
+  oxy: OxyServices;
+  store: AuthStateStore;
+}): Promise<DeviceSecretMintOutcome> {
+  const { oxy, store } = deps;
+  return oxy.httpService.runSingleFlightDeviceSecretMint(async () => {
+    const persisted = await store.load();
+    if (!persisted?.deviceId || !persisted?.deviceSecret) {
+      return { status: 'no-secret' };
+    }
+
+    let mint: DeviceTokenMintResponse;
+    try {
+      mint = await oxy.mintFromDeviceSecret(persisted.deviceId, persisted.deviceSecret);
+    } catch (error) {
+      if (extractErrorStatus(error) === 401) {
+        // Structural read (not `instanceof Error`): the thrown value can be a
+        // plain ApiError-shaped object or come from another realm.
+        const message = (error as { message?: unknown })?.message;
+        return typeof message === 'string' && message.includes('no_active_session')
+          ? { status: 'no-session' }
+          : { status: 'invalid-secret' };
+      }
+      return { status: 'transient' };
+    }
+
+    const active = mint.state.accounts.find((a) => a.accountId === mint.state.activeAccountId);
+    const next: PersistedAuthState = {
+      ...persisted,
+      deviceId: mint.state.deviceId,
+      deviceSecret: mint.nextDeviceSecret,
+      accessToken: mint.accessToken,
+      expiresAt: mint.expiresAt,
+      ...(active ? { sessionId: active.sessionId, userId: active.accountId } : {}),
+    };
+    // Rotation-in-use anti-loss: persist the NEXT secret and read-back-VERIFY it
+    // landed BEFORE planting the token. A failed durable persist must NOT plant.
+    const persistedOk = await store.save(next);
+    if (!persistedOk) {
+      return { status: 'persist-failed' };
+    }
+    oxy.setTokens(mint.accessToken);
+    return { status: 'ok', token: mint.accessToken, sessionId: next.sessionId, userId: next.userId };
+  });
+}
+
 /**
  * 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 async function refreshPersistedSession(deps: RefreshDeps): Promise<string | null> {
   const { oxy, store } = deps;
   const allowSharedKeyFallback = deps.allowSharedKeyFallback ?? isNative();
 
-  const persisted = await store.load();
-
-  if (persisted?.deviceId && persisted?.deviceSecret) {
-    try {
-      const mint = await oxy.mintFromDeviceSecret(persisted.deviceId, persisted.deviceSecret);
-      oxy.setTokens(mint.accessToken);
-      const active = mint.state.accounts.find((a) => a.accountId === mint.state.activeAccountId);
-      const next: PersistedAuthState = {
-        ...persisted,
-        deviceId: mint.state.deviceId,
-        deviceSecret: mint.nextDeviceSecret,
-        accessToken: mint.accessToken,
-        expiresAt: mint.expiresAt,
-        ...(active ? { sessionId: active.sessionId, userId: active.accountId } : {}),
-      };
-      await store.save(next);
-      return mint.accessToken;
-    } catch (error) {
-      if (extractErrorStatus(error) === 401) {
-        // Secret diverged / no active session. On a shared-key device drop only
-        // the secret so arm 2 below can recover; otherwise the session is over.
-        if (allowSharedKeyFallback) {
+  const arm1 = await refreshDeviceSecretArm({ oxy, store });
+  switch (arm1.status) {
+    case 'ok':
+      return arm1.token;
+    case 'transient':
+      logger.debug(
+        'Persisted deviceSecret mint failed (transient) — keeping store',
+        { component: 'refresh', method: 'refreshPersistedSession' },
+      );
+      return null;
+    case 'persist-failed':
+      // The server rotated the secret but it did not durably persist. Do NOT fall
+      // to shared-key and do NOT plant — a later attempt re-mints (the process
+      // mirror still holds the rotated secret the server accepts) and can persist
+      // once storage recovers. Never advertise a session on an unsaved secret.
+      logger.error(
+        'Device-secret mint rotated the secret but it could not be durably persisted — refusing to plant (a later attempt re-mints)',
+        undefined,
+        { component: 'refresh', method: 'refreshPersistedSession' },
+      );
+      return null;
+    case 'invalid-secret':
+    case 'no-session': {
+      // 401: secret diverged or no live session. On a shared-key device drop only
+      // the secret (keep the identity so arm 2 can recover); otherwise (web) the
+      // session is over — clear the store.
+      const persisted = await store.load();
+      if (allowSharedKeyFallback) {
+        if (persisted) {
           await store.save({ ...persisted, deviceSecret: undefined });
-        } else {
-          await store.clear();
         }
-        // Fall through to the native shared-key arm.
       } else {
-        logger.debug(
-          'Persisted deviceSecret mint failed (transient) — keeping store',
-          { component: 'refresh', method: 'refreshPersistedSession' },
-          error,
-        );
-        return null;
+        await store.clear();
       }
+      break;
     }
+    case 'no-secret':
+      break;
   }
 
   if (allowSharedKeyFallback) {
     try {
       const session = await oxy.signInWithSharedIdentity();
       if (session?.accessToken) {
+        // Repopulate the fast device-secret lane from the shared-key re-mint.
+        if (session.deviceId && session.deviceSecret) {
+          await store.save({
+            sessionId: session.sessionId,
+            userId: session.user.id,
+            deviceId: session.deviceId,
+            deviceSecret: session.deviceSecret,
+            accessToken: session.accessToken,
+            expiresAt: session.expiresAt,
+          });
+        }
         return session.accessToken;
       }
     } catch (error) {