@oxyhq/core 9.2.2 → 9.2.3

package/src/session/__tests__/refresh.test.ts

@@ -1,8 +1,34 @@
 import type { OxyServices } from '../../OxyServices';
 import type { DeviceTokenMintResponse } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../../models/session';
-import { refreshPersistedSession, startTokenRefreshScheduler } from '../refresh';
-import { createMemoryAuthStateStore, type PersistedAuthState } from '../authStateStore';
+import {
+  refreshPersistedSession,
+  startTokenRefreshScheduler,
+  type DeviceSecretMintOutcome,
+} from '../refresh';
+import {
+  createMemoryAuthStateStore,
+  type AuthStateStore,
+  type PersistedAuthState,
+} from '../authStateStore';
+
+/**
+ * A real, per-client device-secret mint single-flight matching
+ * `HttpService.runSingleFlightDeviceSecretMint`: concurrent callers await the
+ * SAME in-flight mint and all receive its result; a fresh call after it settles
+ * starts a new one.
+ */
+function makeMintSingleFlight(): (mint: () => Promise<DeviceSecretMintOutcome>) => Promise<DeviceSecretMintOutcome> {
+  let inFlight: Promise<DeviceSecretMintOutcome> | null = null;
+  return (mint) => {
+    if (!inFlight) {
+      inFlight = mint().finally(() => {
+        inFlight = null;
+      });
+    }
+    return inFlight;
+  };
+}
 
 /** The persisted zero-cookie mint credential the refresh reads. */
 const STORED: PersistedAuthState = {
@@ -37,6 +63,9 @@ function makeOxy(overrides: RefreshMockOverrides = {}): { oxy: OxyServices; setT
     setTokens,
     mintFromDeviceSecret: overrides.mintFromDeviceSecret ?? (async () => MINT),
     signInWithSharedIdentity: overrides.signInWithSharedIdentity ?? (async () => null),
+    // The rotating mint runs under the client's process-wide single-flight; the
+    // arm reaches for it via `oxy.httpService.runSingleFlightDeviceSecretMint`.
+    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight() },
   } as unknown as OxyServices;
   return { oxy, setTokens };
 }
@@ -169,6 +198,116 @@ describe('refreshPersistedSession — arm 2 (native shared-key fallback)', () =>
     expect(await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: true })).toBeNull();
     expect(signInWithSharedIdentity).toHaveBeenCalledTimes(1);
   });
+
+  it('persists the recovered credential from the shared-key re-mint (repopulates the fast lane)', async () => {
+    // Bug #3: an in-session shared-key recovery must repopulate the durable
+    // device credential, not leave the fast device-secret lane empty.
+    const store = createMemoryAuthStateStore(); // no persisted secret → arm 1 skips
+    const RECOVERED: SessionLoginResponse = {
+      sessionId: 'sess-shared',
+      deviceId: 'dev-shared',
+      deviceSecret: 'ds-shared-secret',
+      expiresAt: '2030-01-01T00:00:00.000Z',
+      user: { id: 'user-shared', username: 'u', name: {}, avatar: undefined },
+      accessToken: 'access-shared',
+    };
+    const { oxy } = makeOxy({ signInWithSharedIdentity: jest.fn(async () => RECOVERED) });
+
+    const token = await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: true });
+
+    expect(token).toBe('access-shared');
+    expect(await store.load()).toEqual({
+      sessionId: 'sess-shared',
+      userId: 'user-shared',
+      deviceId: 'dev-shared',
+      deviceSecret: 'ds-shared-secret',
+      accessToken: 'access-shared',
+      expiresAt: '2030-01-01T00:00:00.000Z',
+    });
+  });
+});
+
+describe('refreshPersistedSession — single-flight (no double-rotation)', () => {
+  it('coalesces two concurrent mints into ONE server rotation; the store holds the final current secret', async () => {
+    // The server rotates the secret on every mint. Two concurrent lanes must
+    // therefore share ONE in-flight mint (one rotation) or the store could
+    // converge on a superseded secret.
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+
+    let release: (() => void) | null = null;
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const mintFromDeviceSecret = jest.fn(async (deviceId: string, deviceSecret: string) => {
+      // Block until BOTH callers have entered so the single-flight is exercised.
+      await gate;
+      expect(deviceId).toBe('dev-mint');
+      expect(deviceSecret).toBe('ds-secret-orig');
+      return MINT;
+    });
+    const { oxy, setTokens } = makeOxy({ mintFromDeviceSecret });
+
+    const first = refreshPersistedSession({ oxy, store, allowSharedKeyFallback: false });
+    const second = refreshPersistedSession({ oxy, store, allowSharedKeyFallback: false });
+    // Both callers entered while the mint is in flight.
+    release?.();
+    const [t1, t2] = await Promise.all([first, second]);
+
+    // Exactly one server rotation despite two concurrent callers…
+    expect(mintFromDeviceSecret).toHaveBeenCalledTimes(1);
+    // …both callers received the same minted token…
+    expect(t1).toBe('access-new');
+    expect(t2).toBe('access-new');
+    // …and the durable store converged on the rotated (current) secret.
+    expect((await store.load())?.deviceSecret).toBe('ds-next-secret');
+    // The token was planted exactly once (inside the single-flighted mint).
+    expect(setTokens).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('refreshPersistedSession — durable persist failure is fatal to the mint', () => {
+  it('does NOT plant a token when the rotated secret cannot be durably persisted', async () => {
+    // Bug #2: a mint that rotated the server secret but could not persist it must
+    // not leave the process advertising a session on an unsaved, soon-dead secret.
+    const failingStore: AuthStateStore = {
+      load: async () => STORED,
+      save: async () => false, // durable write did not land
+      clear: async () => undefined,
+    };
+    const mintFromDeviceSecret = jest.fn(async () => MINT);
+    const { oxy, setTokens } = makeOxy({ mintFromDeviceSecret });
+
+    const token = await refreshPersistedSession({
+      oxy,
+      store: failingStore,
+      allowSharedKeyFallback: false,
+    });
+
+    // The mint ran (the server rotated) but the token was NOT planted…
+    expect(mintFromDeviceSecret).toHaveBeenCalledTimes(1);
+    expect(setTokens).not.toHaveBeenCalled();
+    // …and the lane reports failure rather than a healthy session.
+    expect(token).toBeNull();
+  });
+
+  it('does NOT fall through to the shared-key arm on a persist failure', async () => {
+    const failingStore: AuthStateStore = {
+      load: async () => STORED,
+      save: async () => false,
+      clear: async () => undefined,
+    };
+    const signInWithSharedIdentity = jest.fn(async () => null);
+    const { oxy } = makeOxy({
+      mintFromDeviceSecret: async () => MINT,
+      signInWithSharedIdentity,
+    });
+
+    await refreshPersistedSession({ oxy, store: failingStore, allowSharedKeyFallback: true });
+
+    // A storage failure is not a bad-secret signal — the shared-key arm must not run.
+    expect(signInWithSharedIdentity).not.toHaveBeenCalled();
+  });
 });
 
 describe('startTokenRefreshScheduler', () => {

package/src/session/authStateStore.ts

@@ -68,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>;
 }
 
@@ -275,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;
@@ -376,6 +392,9 @@ export function createWebAuthStateStore(): AuthStateStore {
       } catch {
         // 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;
@@ -462,6 +481,9 @@ export function createNativeAuthStateStore(storage: NativeKeyValueStorage): Auth
       } catch {
         // 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;

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) {