@oxyhq/core 9.2.1 → 9.2.3

package/src/session/__tests__/SessionClient.serverEvents.test.ts

@@ -0,0 +1,71 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import type { MinimalSocket, SocketIOFactory } from '../socketLoader';
+import { SessionClient, type SessionClientHost } from '../SessionClient';
+
+type Handler = (...args: unknown[]) => void;
+class FakeSocket implements MinimalSocket {
+  connected = false;
+  handlers = new Map<string, Handler[]>();
+  on(event: string, cb: Handler) { const l = this.handlers.get(event) ?? []; l.push(cb); this.handlers.set(event, l); }
+  off(event: string, cb?: Handler) { if (!cb) { this.handlers.delete(event); return; } this.handlers.set(event, (this.handlers.get(event) ?? []).filter((h) => h !== cb)); }
+  connect() { this.connected = true; }
+  disconnect() { this.connected = false; }
+  emitServer(event: string, payload: unknown) { for (const h of this.handlers.get(event) ?? []) h(payload); }
+}
+
+const STATE = (rev: number): DeviceSessionState => ({ deviceId: 'd1', accounts: [{ accountId: 'a1', sessionId: 's1', authuser: 0 }], activeAccountId: 'a1', revision: rev, updatedAt: 1720000000000 });
+const SYNC = (rev: number) => ({ state: STATE(rev), activeToken: { accessToken: `jwt-${rev}`, expiresAt: 'x' } });
+
+function makeHost(over: Partial<SessionClientHost> = {}): SessionClientHost {
+  return {
+    makeRequest: jest.fn().mockResolvedValue(SYNC(1)),
+    getBaseURL: () => 'http://test.invalid',
+    getAccessToken: () => 'tok',
+    getDeviceCredential: () => null,
+    onTokensChanged: () => () => undefined,
+    setTokens: jest.fn(),
+    getCurrentAccountId: () => 'a1',
+    ...over,
+  };
+}
+
+describe('SessionClient.onServerEvent', () => {
+  it('delivers a server event to a listener registered BEFORE the socket exists', async () => {
+    let created: FakeSocket | null = null;
+    const factory: SocketIOFactory = jest.fn(() => { created = new FakeSocket(); created.connected = true; return created; });
+    const client = new SessionClient(makeHost(), { socketFactory: factory });
+    const seen: unknown[] = [];
+    client.onServerEvent('civic:attested', (p) => seen.push(p));
+    await client.start();
+    created?.emitServer('civic:attested', { byUserId: 'u2' });
+    expect(seen).toEqual([{ byUserId: 'u2' }]);
+    client.stop();
+  });
+
+  it('delivers to a listener registered AFTER the socket exists, and unsubscribe stops delivery', async () => {
+    let created: FakeSocket | null = null;
+    const factory: SocketIOFactory = jest.fn(() => { created = new FakeSocket(); created.connected = true; return created; });
+    const client = new SessionClient(makeHost(), { socketFactory: factory });
+    await client.start();
+    const seen: unknown[] = [];
+    const unsub = client.onServerEvent('civic:attested', (p) => seen.push(p));
+    created?.emitServer('civic:attested', 1);
+    unsub();
+    created?.emitServer('civic:attested', 2);
+    expect(seen).toEqual([1]);
+    client.stop();
+  });
+
+  it('one listener throwing does not break the others', async () => {
+    let created: FakeSocket | null = null;
+    const factory: SocketIOFactory = jest.fn(() => { created = new FakeSocket(); created.connected = true; return created; });
+    const client = new SessionClient(makeHost(), { socketFactory: factory });
+    await client.start();
+    const seen: unknown[] = [];
+    client.onServerEvent('civic:attested', () => { throw new Error('boom'); });
+    client.onServerEvent('civic:attested', (p) => seen.push(p));
+    created?.emitServer('civic:attested', 'ok');
+    expect(seen).toEqual(['ok']);
+    client.stop();
+  });
+});

package/src/session/__tests__/SessionClient.socket.test.ts

@@ -131,4 +131,36 @@ describe('SessionClient socket', () => {
     c.stop();
     expect(fakeSocket.connected).toBe(false);
   });
+
+  it('a socket-pushed empty state fires onUnauthenticated with the PUSH origin (bug #4)', async () => {
+    const onUnauthenticated = jest.fn();
+    const c = new SessionClient(makeHost(), { onUnauthenticated });
+    await c.start();
+
+    const EMPTY: DeviceSessionState = { deviceId: 'd1', accounts: [], activeAccountId: null, revision: 9, updatedAt: 1720000000001 };
+    fakeSocket.trigger('session_state', EMPTY);
+
+    expect(onUnauthenticated).toHaveBeenCalledWith('push');
+    c.stop();
+  });
+
+  it('a REST signOut-all empty response fires onUnauthenticated with the REQUEST origin', async () => {
+    const onUnauthenticated = jest.fn();
+    const EMPTY_SYNC = {
+      state: { deviceId: 'd1', accounts: [], activeAccountId: null, revision: 9, updatedAt: 1720000000001 },
+      activeToken: null,
+    };
+    // bootstrap during start() returns a populated state; the signout (and any
+    // stray reconcile) returns empty.
+    const makeRequest = jest.fn().mockResolvedValue(EMPTY_SYNC).mockResolvedValueOnce(SYNC(1));
+    const c = new SessionClient(makeHost({ makeRequest }), { onUnauthenticated });
+    await c.start();
+
+    await c.signOut({ all: true });
+    // Flush any fire-and-forget post-commit reconcile before asserting/teardown.
+    await Promise.resolve();
+
+    expect(onUnauthenticated).toHaveBeenCalledWith('request');
+    c.stop();
+  });
 });

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

@@ -540,6 +540,91 @@ describe('AccountDialogController — sign in with Oxy', () => {
   });
 });
 
+describe('AccountDialogController — Commons deep-link (canOpenApp)', () => {
+  const START_HANDLE = {
+    sessionToken: 'secret-tok',
+    authorizeCode: 'AUTH-CODE',
+    qrPayload: 'oxycommons://approve?v=1&code=AUTH-CODE',
+    expiresAt: Date.now() + 600_000,
+    status: 'pending' as const,
+  };
+
+  function makeController(opts: {
+    openUrl?: jest.Mock;
+    canOpenApp?: jest.Mock;
+  }): { controller: AccountDialogController; oxy: OxyMock } {
+    const oxy = makeOxy();
+    oxy.startCommonsSignIn.mockResolvedValue(START_HANDLE);
+    oxy.pollCommonsSignIn.mockResolvedValue({ authorized: false, status: 'pending' });
+    const controller = new AccountDialogController({
+      oxyServices: oxy as unknown as OxyServices,
+      sessionClient: new TestSessionClient(host()),
+      clientId: 'oxy_dk_test',
+      pollIntervalMs: 1000,
+      openUrl: opts.openUrl,
+      canOpenApp: opts.canOpenApp,
+    });
+    return { controller, oxy };
+  }
+
+  it('deep-links into Commons via openUrl when canOpenApp reports it installed, keeping the QR/polling fallback', async () => {
+    const openUrl = jest.fn();
+    const canOpenApp = jest.fn().mockResolvedValue(true);
+    const { controller } = makeController({ openUrl, canOpenApp });
+
+    await controller.showQr();
+    await flush(); // let the (non-awaited) canOpenApp probe resolve
+
+    expect(canOpenApp).toHaveBeenCalledWith('oxycommons://');
+    expect(openUrl).toHaveBeenCalledWith('oxycommons://approve?v=1&code=AUTH-CODE');
+    // The QR + polling remain the fallback path — the flow is still waiting.
+    const snap = controller.getSnapshot();
+    expect(snap.view).toBe('qr');
+    expect(snap.signIn.phase).toBe('waiting');
+    expect(snap.signIn.qrPayload).toBe('oxycommons://approve?v=1&code=AUTH-CODE');
+    controller.cancelSignIn();
+  });
+
+  it('does NOT open Commons when canOpenApp reports it absent (renders QR only)', async () => {
+    const openUrl = jest.fn();
+    const canOpenApp = jest.fn().mockResolvedValue(false);
+    const { controller } = makeController({ openUrl, canOpenApp });
+
+    await controller.showQr();
+    await flush();
+
+    expect(canOpenApp).toHaveBeenCalledWith('oxycommons://');
+    expect(openUrl).not.toHaveBeenCalled();
+    expect(controller.getSnapshot().signIn.phase).toBe('waiting');
+    controller.cancelSignIn();
+  });
+
+  it('never probes or opens when canOpenApp is absent (web — unchanged behavior)', async () => {
+    const openUrl = jest.fn();
+    const { controller } = makeController({ openUrl });
+
+    await controller.showQr();
+    await flush();
+
+    expect(openUrl).not.toHaveBeenCalled();
+    expect(controller.getSnapshot().signIn.qrPayload).toBe('oxycommons://approve?v=1&code=AUTH-CODE');
+    controller.cancelSignIn();
+  });
+
+  it('swallows a canOpenApp probe rejection and keeps the QR fallback', async () => {
+    const openUrl = jest.fn();
+    const canOpenApp = jest.fn().mockRejectedValue(new Error('probe boom'));
+    const { controller } = makeController({ openUrl, canOpenApp });
+
+    await controller.showQr();
+    await flush();
+
+    expect(openUrl).not.toHaveBeenCalled();
+    expect(controller.getSnapshot().signIn.phase).toBe('waiting');
+    controller.cancelSignIn();
+  });
+});
+
 describe('AccountDialogController — openPasswordAtOxyAuth', () => {
   beforeEach(() => {
     const store = new Map<string, string>();

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

@@ -3,6 +3,7 @@ import {
   createNativeAuthStateStore,
   createMemoryAuthStateStore,
   AUTH_STATE_STORAGE_KEY,
+  AUTH_STATE_TOKEN_STORAGE_KEY,
   type PersistedAuthState,
   type NativeKeyValueStorage,
 } from '../authStateStore';
@@ -133,7 +134,8 @@ describe('createWebAuthStateStore', () => {
 
     // Construction must not throw, and the store must still function (in-memory).
     const store = createWebAuthStateStore();
-    await expect(store.save(SAMPLE)).resolves.toBeUndefined();
+    // A degraded in-memory store IS its own durability backing → reports `true`.
+    await expect(store.save(SAMPLE)).resolves.toBe(true);
     expect(await store.load()).toEqual(SAMPLE);
   });
 
@@ -142,13 +144,46 @@ describe('createWebAuthStateStore', () => {
     const store = createWebAuthStateStore();
     const withCreds: PersistedAuthState = { ...SAMPLE, deviceId: 'dev-abc', deviceSecret: 'ds-secret-xyz' };
 
-    await expect(store.save(withCreds)).resolves.toBeUndefined();
+    // The durable write threw → the store reports the persist did NOT land.
+    await expect(store.save(withCreds)).resolves.toBe(false);
     // The write never reached storage...
     expect(localStorage.getItem(AUTH_STATE_STORAGE_KEY)).toBeNull();
     // ...but the in-memory mirror keeps the session (incl. the mint credential) live.
     expect(await store.load()).toEqual(withCreds);
   });
 
+  it('reports false when the durable write SILENTLY no-ops (read-back mismatch, no throw)', async () => {
+    // A backing store whose setItem neither throws nor persists — the exact
+    // failure the read-back guards. The mirror keeps the session live, but the
+    // credential did not land, so save() must report false.
+    const map = new Map<string, string>();
+    const storage = {
+      getItem: (k: string) => map.get(k) ?? null,
+      setItem: (k: string, v: string) => {
+        // Only the WARM key writes; the durable credential silently vanishes.
+        if (k === AUTH_STATE_TOKEN_STORAGE_KEY) map.set(k, v);
+      },
+      removeItem: (k: string) => {
+        map.delete(k);
+      },
+      clear: () => map.clear(),
+      key: (i: number) => Array.from(map.keys())[i] ?? null,
+      get length() {
+        return map.size;
+      },
+    } as Storage;
+    installLocalStorage(storage);
+    const store = createWebAuthStateStore();
+
+    await expect(
+      store.save({ ...SAMPLE, deviceId: 'dev-x', deviceSecret: 'ds-x' }),
+    ).resolves.toBe(false);
+    // The durable blob never landed…
+    expect(storage.getItem(AUTH_STATE_STORAGE_KEY)).toBeNull();
+    // …but the mirror still serves the session for this page's lifetime.
+    expect(await store.load()).toMatchObject({ deviceId: 'dev-x', deviceSecret: 'ds-x' });
+  });
+
   it('a cleared session reads null even if storage later holds a stale blob (mirror wins)', async () => {
     const storage = makeFakeStorage();
     installLocalStorage(storage);
@@ -161,6 +196,103 @@ describe('createWebAuthStateStore', () => {
     // The authoritative in-memory mirror still reports the cleared state.
     expect(await store.load()).toBeNull();
   });
+
+  it('splits the token into the warm key and keeps the durable blob token-free', async () => {
+    const storage = makeFakeStorage();
+    installLocalStorage(storage);
+    const store = createWebAuthStateStore();
+
+    await store.save({ ...SAMPLE, deviceId: 'dev-1', deviceSecret: 'ds-1' });
+
+    // Durable key holds ONLY the small mint-critical fields — never the JWT.
+    const durableRaw = storage.getItem(AUTH_STATE_STORAGE_KEY);
+    expect(durableRaw).toBeTruthy();
+    expect(JSON.parse(durableRaw ?? '{}')).toEqual({
+      sessionId: 's-1',
+      userId: 'u-1',
+      deviceId: 'dev-1',
+      deviceSecret: 'ds-1',
+    });
+
+    // Warm key holds ONLY the short-lived token pair.
+    const warmRaw = storage.getItem(AUTH_STATE_TOKEN_STORAGE_KEY);
+    expect(warmRaw).toBeTruthy();
+    expect(JSON.parse(warmRaw ?? '{}')).toEqual({
+      accessToken: 'a-jwt',
+      expiresAt: '2030-01-01T00:00:00.000Z',
+    });
+
+    // A FRESH store (empty mirror) composes both keys back into the same shape.
+    expect(await createWebAuthStateStore().load()).toEqual({
+      ...SAMPLE,
+      deviceId: 'dev-1',
+      deviceSecret: 'ds-1',
+    });
+  });
+
+  it('persists the durable credential even when the warm-token write fails', async () => {
+    const map = new Map<string, string>();
+    const storage = {
+      getItem: (k: string) => map.get(k) ?? null,
+      setItem: (k: string, v: string) => {
+        // Simulate the warm token exceeding the store's capacity while the small
+        // durable blob writes fine.
+        if (k === AUTH_STATE_TOKEN_STORAGE_KEY) {
+          throw new DOMException('QuotaExceededError', 'QuotaExceededError');
+        }
+        map.set(k, v);
+      },
+      removeItem: (k: string) => {
+        map.delete(k);
+      },
+      clear: () => map.clear(),
+      key: (i: number) => Array.from(map.keys())[i] ?? null,
+      get length() {
+        return map.size;
+      },
+    } as Storage;
+    installLocalStorage(storage);
+    const store = createWebAuthStateStore();
+
+    await expect(
+      store.save({ ...SAMPLE, deviceId: 'dev-abc', deviceSecret: 'ds-secret-xyz' }),
+    ).resolves.toBe(true);
+
+    // The durable mint credential landed despite the warm-token write throwing.
+    const durableRaw = storage.getItem(AUTH_STATE_STORAGE_KEY);
+    expect(durableRaw).toBeTruthy();
+    const durable = JSON.parse(durableRaw ?? '{}');
+    expect(durable.deviceId).toBe('dev-abc');
+    expect(durable.deviceSecret).toBe('ds-secret-xyz');
+    expect(durable.accessToken).toBeUndefined();
+    // The warm-token key never persisted.
+    expect(storage.getItem(AUTH_STATE_TOKEN_STORAGE_KEY)).toBeNull();
+
+    // A fresh store restores the mint credential from disk; no warm token survives.
+    const loaded = await createWebAuthStateStore().load();
+    expect(loaded?.deviceId).toBe('dev-abc');
+    expect(loaded?.deviceSecret).toBe('ds-secret-xyz');
+    expect(loaded?.accessToken).toBeUndefined();
+  });
+
+  it('load() reads an old combined oxy.auth.v1 blob (pre-split back-compat)', async () => {
+    const storage = makeFakeStorage();
+    installLocalStorage(storage);
+    // A user upgraded from the pre-split build: the WHOLE state (incl. the token)
+    // lives in the single durable key; the warm key does not exist yet.
+    storage.setItem(
+      AUTH_STATE_STORAGE_KEY,
+      JSON.stringify({ ...SAMPLE, deviceId: 'dev-old', deviceSecret: 'ds-old' }),
+    );
+    expect(storage.getItem(AUTH_STATE_TOKEN_STORAGE_KEY)).toBeNull();
+
+    const store = createWebAuthStateStore();
+    const loaded = await store.load();
+    // The token is read back from the combined blob (no one is logged out).
+    expect(loaded).toEqual({ ...SAMPLE, deviceId: 'dev-old', deviceSecret: 'ds-old' });
+    expect(loaded?.accessToken).toBe('a-jwt');
+    expect(loaded?.expiresAt).toBe('2030-01-01T00:00:00.000Z');
+  });
 });
 
 describe('createNativeAuthStateStore', () => {
@@ -206,10 +338,106 @@ describe('createNativeAuthStateStore', () => {
         throw new Error('secure store locked');
       },
     });
-    await expect(store.save(SAMPLE)).resolves.toBeUndefined();
-    // The write threw, but the in-memory mirror preserves the session.
+    // The durable write threw → reports the persist did NOT land…
+    await expect(store.save(SAMPLE)).resolves.toBe(false);
+    // …but the in-memory mirror preserves the session for this app run.
     expect(await store.load()).toEqual(SAMPLE);
   });
+
+  it('reports false when the durable SecureStore write SILENTLY no-ops (oversize value, no throw)', async () => {
+    // Android SecureStore can resolve a write WITHOUT throwing yet not persist an
+    // oversize value — the read-back is the only reliable proof. save() must
+    // report false so a rotating-secret lane refuses to plant on it.
+    const map = new Map<string, string>();
+    const storage: NativeKeyValueStorage = {
+      getItem: async (k) => map.get(k) ?? null,
+      setItem: async (k, v) => {
+        if (k === AUTH_STATE_TOKEN_STORAGE_KEY) map.set(k, v); // durable silently dropped
+      },
+      removeItem: async (k) => {
+        map.delete(k);
+      },
+    };
+    const store = createNativeAuthStateStore(storage);
+
+    await expect(
+      store.save({ ...SAMPLE, deviceId: 'dev-x', deviceSecret: 'ds-x' }),
+    ).resolves.toBe(false);
+    expect(map.get(AUTH_STATE_STORAGE_KEY)).toBeUndefined();
+    expect(await store.load()).toMatchObject({ deviceId: 'dev-x', deviceSecret: 'ds-x' });
+  });
+
+  it('persists the durable credential even when the warm-token write fails (oversize SecureStore value)', async () => {
+    const map = new Map<string, string>();
+    const storage: NativeKeyValueStorage = {
+      getItem: async (k) => map.get(k) ?? null,
+      // The large JWT exceeds the SecureStore value limit; the small durable blob
+      // writes fine.
+      setItem: async (k, v) => {
+        if (k === AUTH_STATE_TOKEN_STORAGE_KEY) {
+          throw new Error('Value too large for SecureStore');
+        }
+        map.set(k, v);
+      },
+      removeItem: async (k) => {
+        map.delete(k);
+      },
+    };
+    const store = createNativeAuthStateStore(storage);
+
+    await expect(
+      store.save({ ...SAMPLE, deviceId: 'dev-n', deviceSecret: 'ds-n' }),
+    ).resolves.toBe(true);
+
+    // The durable mint credential landed to disk.
+    expect(map.get(AUTH_STATE_STORAGE_KEY)).toBeTruthy();
+    const durable = JSON.parse(map.get(AUTH_STATE_STORAGE_KEY) ?? '{}');
+    expect(durable.deviceId).toBe('dev-n');
+    expect(durable.deviceSecret).toBe('ds-n');
+    expect(durable.accessToken).toBeUndefined();
+    expect(map.get(AUTH_STATE_TOKEN_STORAGE_KEY)).toBeUndefined();
+
+    // A FRESH store (empty mirror) restores the mint credential from disk.
+    const loaded = await createNativeAuthStateStore(storage).load();
+    expect(loaded?.deviceId).toBe('dev-n');
+    expect(loaded?.deviceSecret).toBe('ds-n');
+    expect(loaded?.accessToken).toBeUndefined();
+  });
+
+  it('load() reads an old combined blob (pre-split back-compat)', async () => {
+    const map = new Map<string, string>();
+    const storage: NativeKeyValueStorage = {
+      getItem: async (k) => map.get(k) ?? null,
+      setItem: async (k, v) => {
+        map.set(k, v);
+      },
+      removeItem: async (k) => {
+        map.delete(k);
+      },
+    };
+    // Pre-split combined blob in the single durable key; no warm key.
+    map.set(
+      AUTH_STATE_STORAGE_KEY,
+      JSON.stringify({ ...SAMPLE, deviceId: 'dev-old', deviceSecret: 'ds-old' }),
+    );
+
+    const store = createNativeAuthStateStore(storage);
+    expect(await store.load()).toEqual({ ...SAMPLE, deviceId: 'dev-old', deviceSecret: 'ds-old' });
+  });
+
+  it('clear() wipes BOTH the durable and warm keys', async () => {
+    const storage = makeNativeStorage();
+    const store = createNativeAuthStateStore(storage);
+    await store.save({ ...SAMPLE, deviceId: 'dev-1', deviceSecret: 'ds-1' });
+    // Both keys were written by the split save.
+    expect(storage.map.get(AUTH_STATE_STORAGE_KEY)).toBeTruthy();
+    expect(storage.map.get(AUTH_STATE_TOKEN_STORAGE_KEY)).toBeTruthy();
+
+    await store.clear();
+    expect(storage.map.get(AUTH_STATE_STORAGE_KEY)).toBeUndefined();
+    expect(storage.map.get(AUTH_STATE_TOKEN_STORAGE_KEY)).toBeUndefined();
+    expect(await store.load()).toBeNull();
+  });
 });
 
 describe('createMemoryAuthStateStore', () => {

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', () => {