@oxyhq/core 9.2.2 → 9.2.3

package/src/boot/sessionColdBoot.ts

@@ -7,21 +7,25 @@
  * 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.
  */
 import { runColdBoot, type ColdBootOutcome, type ColdBootStep } from '../utils/coldBoot';
 import { isNative as detectNative } from '../utils/platform';
-import { extractErrorStatus } from '../utils/errorUtils';
 import { logger } from '../utils/loggerUtils';
+import { TOKEN_REFRESH_LEAD_MS, refreshDeviceSecretArm } from '../session/refresh';
 import type { OxyServices } from '../OxyServices';
-import type { AuthStateStore, PersistedAuthState } from '../session/authStateStore';
+import type { AuthStateStore } from '../session/authStateStore';
 
 /** The winning session shape a cold-boot step reports. */
 export interface DeviceBootSession {
@@ -45,34 +49,6 @@ export interface RunSessionColdBootOptions {
   onStepError?: (id: string, error: unknown) => void;
 }
 
-/**
- * How a `mintFromDeviceSecret` call failed, distinguished so the cold boot can
- * react per the transport contract:
- *  - `invalid_secret` — the presented secret no longer matches (another tab/
- *    device rotated it, or theft divergence). Drop it and fall back.
- *  - `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.
- *
- * The mint is bearer-less (`skipAuth`), so `HttpService` surfaces the server's
- * 401 body string (`invalid_device_secret` | `no_active_session`) as the thrown
- * error's `message`; any non-401 is transport/server failure.
- */
-type MintFailure = 'invalid_secret' | 'no_active_session' | 'transient';
-
-function classifyMintFailure(error: unknown): MintFailure {
-  if (extractErrorStatus(error) === 401) {
-    // Structural read (not `instanceof Error`): the thrown value can be a plain
-    // ApiError-shaped object or come from another realm, where instanceof fails
-    // and a `no_active_session` would be misread as a stale secret and dropped.
-    const message = (error as { message?: unknown })?.message;
-    return typeof message === 'string' && message.includes('no_active_session')
-      ? 'no_active_session'
-      : 'invalid_secret';
-  }
-  return 'transient';
-}
-
 /**
  * Run the device-first cold boot. Resolves to the `runColdBoot` outcome and, as
  * a side effect, invokes `onSession` (winning session, token already planted) or
@@ -90,64 +66,107 @@ export async function runSessionColdBoot(
 
   const steps: Array<ColdBootStep<DeviceBootSession>> = [];
 
-  // 1. device-secret-mint (web + native) — the zero-cookie fast path. When the
-  //    origin persisted a deviceId + deviceSecret, mint a short access token with
-  //    a single bearer-less POST (no cookie, no navigation).
+  // 1. warm-token-plant (web + native) — the fastest path. When the persisted
+  //    store already holds a still-valid warm access token (its expiry more than
+  //    the refresh lead window away) plus its owning session identity, plant it
+  //    and yield the session IMMEDIATELY, skipping the blocking mint round-trip on
+  //    first paint. The token is used AS-IS: this step NEVER mints, rotates, or
+  //    persists anything. The proactive `startTokenRefreshScheduler` + the
+  //    request-time preflight (both wired in the services provider) rotate it in
+  //    the background; a revoked token self-heals via the 401 -> re-mint -> clear
+  //    path. This exposure is sanctioned by `authStateStore.ts` (~L30-36): the
+  //    warm token is short-lived and adds nothing over the already-persisted
+  //    `deviceSecret`.
   steps.push({
-    id: 'device-secret-mint',
+    id: 'warm-token-plant',
     run: async () => {
       const persisted = await store.load();
-      if (!persisted?.deviceId || !persisted?.deviceSecret) {
+      if (!persisted?.accessToken || !persisted.sessionId || !persisted.userId || !persisted.expiresAt) {
+        return { kind: 'skip' };
+      }
+      // Guard a malformed `expiresAt` (Date.parse -> NaN): treat as not-valid and
+      // fall through to the mint lane. A token still inside the refresh lead
+      // window (or already expired) is likewise skipped — let the mint lane get a
+      // fresh one rather than plant a token about to expire.
+      const expiresAtMs = new Date(persisted.expiresAt).getTime();
+      if (!Number.isFinite(expiresAtMs) || expiresAtMs <= Date.now() + TOKEN_REFRESH_LEAD_MS) {
         return { kind: 'skip' };
       }
-      try {
-        const mint = await oxy.mintFromDeviceSecret(persisted.deviceId, persisted.deviceSecret);
-        // Rotation-in-use anti-loss: persist the NEXT secret (+ refreshed warm
-        // fields, + the server's authoritative active account) BEFORE planting
-        // the minted access token, so a multi-tab race that rotates again can
-        // never strand this tab with a superseded secret.
-        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);
-        oxy.setTokens(mint.accessToken);
-        return {
-          kind: 'session',
-          session: { sessionId: next.sessionId, userId: next.userId, accessToken: mint.accessToken },
-        };
-      } catch (error) {
-        const failure = classifyMintFailure(error);
-        if (failure === 'invalid_secret') {
+      oxy.setTokens(persisted.accessToken);
+      return {
+        kind: 'session',
+        session: {
+          sessionId: persisted.sessionId,
+          userId: persisted.userId,
+          accessToken: persisted.accessToken,
+        },
+      };
+    },
+  });
+
+  // 2. device-secret-mint (web + native) — the zero-cookie fast path. When the
+  //    origin persisted a deviceId + deviceSecret, mint a short access token with
+  //    a single bearer-less POST (no cookie, no navigation). The mint itself runs
+  //    through `refreshDeviceSecretArm`, which acquires the client's PROCESS-WIDE
+  //    single-flight, persists the rotated `nextDeviceSecret` BEFORE planting the
+  //    token, and returns a classified outcome — so this step can never
+  //    double-rotate the server against the scheduler/transport/401 lanes, and
+  //    the durable store always converges on the true `current` secret.
+  steps.push({
+    id: 'device-secret-mint',
+    run: async () => {
+      const result = await refreshDeviceSecretArm({ oxy, store });
+      switch (result.status) {
+        case 'ok':
+          // The arm persisted the rotated secret and planted the token.
+          return {
+            kind: 'session',
+            session: {
+              sessionId: result.sessionId,
+              userId: result.userId,
+              accessToken: result.token,
+            },
+          };
+        case 'invalid-secret': {
           // Stale/diverged secret — drop it so the mint lane stops firing. On
           // native the shared-key step below can still recover; on web this ends
           // signed out. Setting it undefined drops the key on the store's JSON
           // serialization, and the mint guard treats undefined as absent.
-          await store.save({ ...persisted, deviceSecret: undefined });
+          const persisted = await store.load();
+          if (persisted) {
+            await store.save({ ...persisted, deviceSecret: undefined });
+          }
           return { kind: 'skip' };
         }
-        if (failure === 'no_active_session') {
-          // Device known, no live session — authoritative signed-out.
+        case 'no-session':
+          // Device known, no live session — authoritative signed-out. Keep the
+          // secret (the device may sign in again).
           signedOutReason = 'no_session';
           return { kind: 'skip' };
-        }
-        // Transient (network / 5xx): keep the secret; a later attempt can succeed.
-        logger.debug(
-          'device-secret mint failed (transient) — keeping secret',
-          { component: 'sessionColdBoot', method: 'device-secret-mint' },
-          error,
-        );
-        return { kind: 'skip' };
+        case 'persist-failed':
+          // The mint rotated the secret but it could not be durably persisted —
+          // refuse to advertise a session that will not survive a reload. Keep
+          // the secret; a later boot/attempt re-mints once storage recovers.
+          logger.error(
+            'device-secret mint rotated the secret but it could not be durably persisted — not planting',
+            undefined,
+            { component: 'sessionColdBoot', method: 'device-secret-mint' },
+          );
+          return { kind: 'skip' };
+        case 'transient':
+          // Network / 5xx: keep the secret; a later attempt can succeed.
+          logger.debug(
+            'device-secret mint failed (transient) — keeping secret',
+            { component: 'sessionColdBoot', method: 'device-secret-mint' },
+          );
+          return { kind: 'skip' };
+        case 'no-secret':
+          return { kind: 'skip' };
       }
     },
   });
 
-  // 2. shared-key-signin (native) — re-mint from the shared identity.
+  // 3. shared-key-signin (native) — re-mint from the shared identity.
   steps.push({
     id: 'shared-key-signin',
     enabled: () => isNative,

package/src/crypto/keyManager.ts

@@ -8,7 +8,7 @@
 import { ec as EC } from 'elliptic';
 import type { ECKeyPair } from 'elliptic';
 import { isWeb, isIOS, isAndroid } from '../utils/platform';
-import { type ExpoCryptoLike, type ExpoSecureStoreLike, isReactNative, isNodeJS, loadExpoCrypto, loadNodeCrypto, loadSecureStore } from '@oxyhq/protocol';
+import { type ExpoCryptoLike, type ExpoSecureStoreLike, isReactNative, isNodeJS, loadExpoCrypto, loadNodeCrypto, loadSecureStore, loadSharedIdentityBridge } from '@oxyhq/protocol';
 import { logger } from '../utils/loggerUtils';
 import { isDev } from '../shared/utils/debugUtils';
 
@@ -298,13 +298,20 @@ export class KeyManager {
         );
       }
     } else if (isAndroid()) {
-      // Android: Store in secure store (accessible via sharedUserId)
-      // Note: All Oxy apps must have the same sharedUserId in AndroidManifest.xml
-      await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, privateKey, {
-        keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
-      });
-
-      await store.setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey);
+      // Android: write through the cross-app bridge (`@oxyhq/expo-oxy-identity`)
+      // when present — it persists into Commons's hardware-backed
+      // EncryptedSharedPreferences behind a signature-protected ContentProvider,
+      // so same-key Oxy apps can read it. When the bridge is not linked, fall
+      // back to the package-private secure store (no cross-app sharing).
+      const bridge = await loadSharedIdentityBridge();
+      if (bridge) {
+        await bridge.putShared(privateKey, publicKey);
+      } else {
+        await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, privateKey, {
+          keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+        });
+        await store.setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey);
+      }
     }
 
     // Update cache
@@ -341,7 +348,14 @@ export class KeyManager {
         const opts: OxySecureStoreOptions = { keychainAccessGroup: IOS_KEYCHAIN_GROUP };
         publicKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, opts);
       } else if (isAndroid()) {
-        publicKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY);
+        // Android reads through the cross-app bridge; when it is not linked, fall
+        // back to the package-private store the fallback write path used.
+        const bridge = await loadSharedIdentityBridge();
+        if (bridge) {
+          publicKey = (await bridge.getShared())?.publicKey ?? null;
+        } else {
+          publicKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY);
+        }
       }
 
       // Cache result
@@ -378,7 +392,14 @@ export class KeyManager {
         const opts: OxySecureStoreOptions = { keychainAccessGroup: IOS_KEYCHAIN_GROUP };
         privateKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, opts);
       } else if (isAndroid()) {
-        privateKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY);
+        // Android reads through the cross-app bridge; when it is not linked, fall
+        // back to the package-private store the fallback write path used.
+        const bridge = await loadSharedIdentityBridge();
+        if (bridge) {
+          privateKey = (await bridge.getShared())?.privateKey ?? null;
+        } else {
+          privateKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY);
+        }
       }
 
       return privateKey;
@@ -458,11 +479,17 @@ export class KeyManager {
       };
       await store.setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey, publicOpts);
     } else if (isAndroid()) {
-      await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, canonicalPrivate, {
-        keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
-      });
-
-      await store.setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey);
+      // Android: write through the cross-app bridge when present; otherwise the
+      // package-private store (kept consistent with the read fallback).
+      const bridge = await loadSharedIdentityBridge();
+      if (bridge) {
+        await bridge.putShared(canonicalPrivate, publicKey);
+      } else {
+        await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, canonicalPrivate, {
+          keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+        });
+        await store.setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey);
+      }
     }
 
     // Update cache

package/src/index.ts

@@ -557,7 +557,7 @@ export type { SyncHubAfterSignInOptions } from './session/hubSync';
 // Session sync (device-scoped multi-account session client)
 // ---------------------------------------------------------------------------
 export { SessionClient } from './session/SessionClient';
-export type { TokenTransport, SessionClientHost, SessionClientOptions, DeviceCredential } from './session/SessionClient';
+export type { TokenTransport, SessionClientHost, SessionClientOptions, DeviceCredential, SessionStateOrigin } from './session/SessionClient';
 // The injectable socket factory type: consumers that bundle socket.io-client
 // (services/auth-sdk) pass its `io` export as `socketFactory` so realtime sync
 // never relies on core's lazy dynamic import of a bare specifier.
@@ -629,12 +629,13 @@ export type {
 
 export {
     refreshPersistedSession,
+    refreshDeviceSecretArm,
     createAuthRefreshHandler,
     installAuthRefreshHandler,
     startTokenRefreshScheduler,
     TOKEN_REFRESH_LEAD_MS,
 } from './session/refresh';
-export type { RefreshDeps, TokenRefreshSchedulerHandle } from './session/refresh';
+export type { RefreshDeps, TokenRefreshSchedulerHandle, DeviceSecretMintOutcome } from './session/refresh';
 
 export { runSessionColdBoot } from './boot/sessionColdBoot';
 export type {

package/src/session/SessionClient.ts

@@ -13,6 +13,22 @@ export interface TokenTransport {
   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;
@@ -34,13 +50,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
@@ -148,7 +171,7 @@ export class SessionClient {
   }
 
   /** Validate + last-writer-wins by revision. Returns true if applied. */
-  protected applyState(raw: unknown): boolean {
+  protected applyState(raw: unknown, origin: SessionStateOrigin = 'push'): boolean {
     const next = safeParseContract(deviceSessionStateSchema, raw);
     if (!next) {
       logger.warn('[SessionClient] discarded invalid session state');
@@ -176,7 +199,7 @@ export class SessionClient {
       this.notify();
       if (next.accounts.length === 0 && this.options.onUnauthenticated) {
         try {
-          this.options.onUnauthenticated();
+          this.options.onUnauthenticated(origin);
         } catch (error) {
           logger.error('[SessionClient] onUnauthenticated threw', error);
         }
@@ -224,7 +247,10 @@ export class SessionClient {
       logger.warn('[SessionClient] discarded invalid session sync', { component: 'SessionClient', issues, keys });
       return;
     }
-    this.applyState(sync.state);
+    // A `sync` is always the response to a direct REST call this client made
+    // (bootstrap / switch / signOut / add) → a `request`-origin, authoritative
+    // verdict.
+    this.applyState(sync.state, 'request');
     if (sync.activeToken && this.state && sync.state.activeAccountId === this.state.activeAccountId) {
       this.host.setTokens(sync.activeToken.accessToken);
     }
@@ -366,7 +392,9 @@ export class SessionClient {
       },
     });
     socket.on('session_state', (payload: unknown) => {
-      const applied = this.applyState(payload);
+      // A socket broadcast is a `push`-origin — potentially transient, so an
+      // empty state here must not erase the durable device credential.
+      const applied = this.applyState(payload, 'push');
       if (!applied) return;
       // A push changed the active account on another device/tab — re-fetch state
       // to plant the access token for the newly-active account. When this tab is

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

@@ -1,5 +1,6 @@
 import type { DeviceSessionState } from '@oxyhq/contracts';
-import { SessionClient, type SessionClientHost } from '../SessionClient';
+import { SessionClient, type SessionClientHost, type SessionStateOrigin } from '../SessionClient';
+import { createMemoryAuthStateStore } from '../authStateStore';
 
 const stateWith = (rev: number, active: string | null, accountIds: string[]): DeviceSessionState => ({
   deviceId: 'd1',
@@ -27,6 +28,10 @@ class TestClient extends SessionClient {
   public apply(raw: unknown): boolean {
     return this.applyState(raw);
   }
+
+  public applyWith(raw: unknown, origin: SessionStateOrigin): boolean {
+    return this.applyState(raw, origin);
+  }
 }
 
 describe('SessionClient.registerAndActivate', () => {
@@ -90,4 +95,56 @@ describe('SessionClient onUnauthenticated', () => {
     c.apply(stateWith(4, null, []));
     expect(onUnauthenticated).not.toHaveBeenCalled();
   });
+
+  it('passes the applied-state ORIGIN through to onUnauthenticated', () => {
+    const onUnauthenticated = jest.fn();
+    const c = new TestClient(makeHost(jest.fn()), { onUnauthenticated });
+
+    // A socket-pushed empty state → `push` origin.
+    c.applyWith(stateWith(1, null, []), 'push');
+    expect(onUnauthenticated).toHaveBeenLastCalledWith('push');
+
+    // A direct REST response empty state → `request` origin.
+    c.applyWith(stateWith(2, null, []), 'request');
+    expect(onUnauthenticated).toHaveBeenLastCalledWith('request');
+  });
+});
+
+describe('SessionClient onUnauthenticated — durable credential guard (bug #4)', () => {
+  const CRED = { sessionId: 's1', userId: 'a1', deviceId: 'dev-1', deviceSecret: 'ds-1' };
+
+  // Mirror the provider's origin-gated wipe: erase the durable credential ONLY on
+  // a `request`-origin verdict, never on a (possibly transient) `push`.
+  function wireGuardedStore() {
+    const store = createMemoryAuthStateStore();
+    const onUnauthenticated = (origin: SessionStateOrigin) => {
+      if (origin === 'request') void store.clear();
+    };
+    return { store, onUnauthenticated };
+  }
+
+  it('a transient socket-pushed accounts===0 does NOT wipe the durable credential', async () => {
+    const { store, onUnauthenticated } = wireGuardedStore();
+    await store.save(CRED);
+    const c = new TestClient(makeHost(jest.fn()), { onUnauthenticated });
+
+    // A `push`-origin empty state (e.g. a reconnect race on another device).
+    c.applyWith(stateWith(2, null, []), 'push');
+    await Promise.resolve();
+
+    // The device credential survives — a reload can still restore the session.
+    expect(await store.load()).toEqual(CRED);
+  });
+
+  it('a real (request-origin) sign-out DOES wipe the durable credential', async () => {
+    const { store, onUnauthenticated } = wireGuardedStore();
+    await store.save(CRED);
+    const c = new TestClient(makeHost(jest.fn()), { onUnauthenticated });
+
+    // A `request`-origin empty state = the REST sign-out response.
+    c.applyWith(stateWith(2, null, []), 'request');
+    await Promise.resolve();
+
+    expect(await store.load()).toBeNull();
+  });
 });

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__/authStateStore.test.ts

@@ -134,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);
   });
 
@@ -143,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);
@@ -222,7 +256,7 @@ describe('createWebAuthStateStore', () => {
 
     await expect(
       store.save({ ...SAMPLE, deviceId: 'dev-abc', deviceSecret: 'ds-secret-xyz' }),
-    ).resolves.toBeUndefined();
+    ).resolves.toBe(true);
 
     // The durable mint credential landed despite the warm-token write throwing.
     const durableRaw = storage.getItem(AUTH_STATE_STORAGE_KEY);
@@ -304,11 +338,35 @@ 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 = {
@@ -329,7 +387,7 @@ describe('createNativeAuthStateStore', () => {
 
     await expect(
       store.save({ ...SAMPLE, deviceId: 'dev-n', deviceSecret: 'ds-n' }),
-    ).resolves.toBeUndefined();
+    ).resolves.toBe(true);
 
     // The durable mint credential landed to disk.
     expect(map.get(AUTH_STATE_STORAGE_KEY)).toBeTruthy();