@oxyhq/core 9.2.1 → 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/mixins/OxyServices.utility.ts

@@ -5,9 +5,11 @@
  * and Express.js authentication middleware
  */
 import { jwtDecode } from 'jwt-decode';
+import type { LinkPreview } from '@oxyhq/contracts';
 import type { ApiError, User } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { loadNodeCrypto } from '@oxyhq/protocol';
+import { buildUrl } from '../utils/apiUtils';
 import { logger } from '../utils/loggerUtils';
 import { CACHE_TIMES } from './mixinHelpers';
 
@@ -217,15 +219,14 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
       image?: string;
     }> {
       try {
-        return await this.makeRequest<{
-          url: string;
-          title: string;
-          description: string;
-          image?: string;
-        }>('GET', '/link-metadata', { url }, {
-          cache: true,
-          cacheTTL: CACHE_TIMES.EXTRA_LONG,
-        });
+        const path = buildUrl('/links/preview', { url, wait: 1 });
+        const preview = await this.makeRequest<LinkPreview>('GET', path, undefined, { cache: false });
+        return {
+          url: preview.url,
+          title: preview.title?.trim() || preview.url.replace(/^https?:\/\//, '').replace(/\/$/, ''),
+          description: preview.description?.trim() || 'Link',
+          image: preview.image,
+        };
       } catch (error) {
         throw this.handleError(error);
       }

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
@@ -82,6 +105,10 @@ export class SessionClient {
   private started = false;
   /** Same-origin cross-tab state-propagation channel; null on platforms without BroadcastChannel. */
   private channel: SessionBroadcastChannel | null = null;
+  /** App-facing subscriptions to named server-pushed socket events. */
+  private readonly serverEvents = new Map<string, Set<(payload: unknown) => void>>();
+  /** Event names already bound on the CURRENT socket instance. */
+  private readonly boundServerEvents = new Set<string>();
 
   constructor(
     protected readonly host: SessionClientHost,
@@ -99,6 +126,40 @@ export class SessionClient {
     };
   }
 
+  /**
+   * Subscribe to a named server-pushed Socket.IO event (e.g. `civic:attested`).
+   * Listeners survive reconnects and socket re-creation; the returned function
+   * unsubscribes. Payloads are delivered as-is — callers validate shape.
+   */
+  onServerEvent(event: string, listener: (payload: unknown) => void): () => void {
+    let listeners = this.serverEvents.get(event);
+    if (!listeners) {
+      listeners = new Set();
+      this.serverEvents.set(event, listeners);
+    }
+    listeners.add(listener);
+    this.bindServerEvent(event);
+    return () => {
+      listeners.delete(listener);
+    };
+  }
+
+  private bindServerEvent(event: string): void {
+    if (!this.socket || this.boundServerEvents.has(event)) return;
+    this.boundServerEvents.add(event);
+    this.socket.on(event, (payload: unknown) => {
+      const listeners = this.serverEvents.get(event);
+      if (!listeners) return;
+      for (const listener of [...listeners]) {
+        try {
+          listener(payload);
+        } catch (error) {
+          logger.warn('[SessionClient] server-event listener threw', { component: 'SessionClient' }, error);
+        }
+      }
+    });
+  }
+
   protected notify(): void {
     for (const listener of this.listeners) {
       try {
@@ -110,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');
@@ -138,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);
         }
@@ -186,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);
     }
@@ -287,6 +351,7 @@ export class SessionClient {
     if (this.socket) {
       this.socket.disconnect();
       this.socket = null;
+      this.boundServerEvents.clear();
     }
   }
 
@@ -327,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
@@ -341,6 +408,11 @@ export class SessionClient {
       }
     });
     this.socket = socket;
+    // (Re)bind app-facing server-event subscriptions on the fresh socket.
+    this.boundServerEvents.clear();
+    for (const event of this.serverEvents.keys()) {
+      this.bindServerEvent(event);
+    }
   }
 
   /**

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();
+  });
 });