@oxyhq/core 9.2.1 → 9.2.2

package/dist/types/session/SessionClient.d.ts

@@ -56,9 +56,20 @@ export declare class SessionClient {
     private started;
     /** Same-origin cross-tab state-propagation channel; null on platforms without BroadcastChannel. */
     private channel;
+    /** App-facing subscriptions to named server-pushed socket events. */
+    private readonly serverEvents;
+    /** Event names already bound on the CURRENT socket instance. */
+    private readonly boundServerEvents;
     constructor(host: SessionClientHost, options?: SessionClientOptions);
     getState(): DeviceSessionState | null;
     subscribe(listener: StateListener): () => void;
+    /**
+     * 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;
+    private bindServerEvent;
     protected notify(): void;
     /** Validate + last-writer-wins by revision. Returns true if applied. */
     protected applyState(raw: unknown): boolean;

package/dist/types/session/accountDialogController.d.ts

@@ -111,6 +111,16 @@ export interface AccountDialogControllerOptions {
      * `Linking.openURL`). Headless core never touches `window`/`Linking` itself.
      */
     openUrl?: (url: string) => void;
+    /**
+     * Optional "can this app open this URL scheme?" probe, symmetric to
+     * {@link openUrl}. When provided, `showQr` uses it to detect an installed
+     * Commons (`oxycommons://`) and, if present, deep-links straight into its
+     * approve screen via {@link openUrl} — while KEEPING the QR/polling active as
+     * the fallback. Injected by the provider (native: `Linking.canOpenURL`; web:
+     * absent/false). Headless core never touches `Linking` itself; when absent
+     * `showQr` behaves exactly as before (render QR only).
+     */
+    canOpenApp?: (url: string) => Promise<boolean>;
 }
 type SnapshotListener = (snapshot: AccountDialogSnapshot) => void;
 export declare class AccountDialogController {
@@ -124,6 +134,7 @@ export declare class AccountDialogController {
     private readonly authRedirectUri;
     private readonly pollIntervalMs;
     private readonly openUrl?;
+    private readonly canOpenApp?;
     private readonly listeners;
     private view;
     private graph;
@@ -232,6 +243,12 @@ export declare class AccountDialogController {
      * session committed. Requires `clientId`.
      */
     showQr(): Promise<void>;
+    /**
+     * When a `canOpenApp` probe is injected and reports Commons installed, open the
+     * approve deep link via the injected `openUrl`. Best-effort and non-blocking: a
+     * probe/open failure is logged and swallowed — the QR/polling fallback remains.
+     */
+    private maybeOpenCommons;
     /** Tear down the active sign-in device flow (timers + token) and reset to idle. */
     cancelSignIn(): void;
     /**

package/dist/types/session/authStateStore.d.ts

@@ -77,11 +77,32 @@ export interface NativeKeyValueStorage {
     removeItem(key: string): Promise<void>;
 }
 /**
- * Versioned storage key. The `.v1` suffix lets a future shape change ship a
- * `.v2` key without reading a stale/incompatible `.v1` blob. Distinct from the
- * `oxy_shared_*` keychain keys in `KeyManager`, so it never collides.
+ * Versioned DURABLE storage key. Holds ONLY the small, re-mint-critical fields
+ * (`sessionId`, `userId`, `deviceId`, `deviceSecret`) — never the large JWT
+ * `accessToken`. Keeping this blob small (<2KB) matters on Android
+ * `expo-secure-store`, whose backing store can silently fail to persist an
+ * oversize value; bundling the token here previously took the mint credential
+ * down with it on every write, losing the session on cold restart.
+ *
+ * The `.v1` suffix lets a future shape change ship a `.v2` key without reading a
+ * stale/incompatible `.v1` blob. Distinct from the `oxy_shared_*` keychain keys
+ * in `KeyManager`, so it never collides.
+ *
+ * BACK-COMPAT: pre-split builds wrote the WHOLE state (including `accessToken` /
+ * `expiresAt`) into this single key. `load()` still reads those token fields
+ * from here when the warm key ({@link AUTH_STATE_TOKEN_STORAGE_KEY}) is absent,
+ * so upgrading users are not signed out; the next `save()` splits them apart.
  */
 export declare const AUTH_STATE_STORAGE_KEY = "oxy.auth.v1";
+/**
+ * Versioned BEST-EFFORT warm-token storage key. Holds the short-lived
+ * `{ accessToken, expiresAt }` pair only. Its write is genuinely non-fatal — a
+ * failure (quota / oversize keychain value) is swallowed because the session is
+ * fully re-mintable from the durable `deviceSecret`. Kept separate from
+ * {@link AUTH_STATE_STORAGE_KEY} so a failed token write can NEVER abort or
+ * corrupt the durable credential write.
+ */
+export declare const AUTH_STATE_TOKEN_STORAGE_KEY = "oxy.auth.token.v1";
 /**
  * A process-lifetime, in-memory {@link AuthStateStore}. Used directly for
  * tests/SSR and as the degraded fallback of the web store when `localStorage`
@@ -90,8 +111,9 @@ export declare const AUTH_STATE_STORAGE_KEY = "oxy.auth.v1";
  */
 export declare function createMemoryAuthStateStore(): AuthStateStore;
 /**
- * A `localStorage`-backed {@link AuthStateStore} under the versioned
- * {@link AUTH_STATE_STORAGE_KEY}.
+ * A `localStorage`-backed {@link AuthStateStore} split across the durable
+ * {@link AUTH_STATE_STORAGE_KEY} (mint credential) and the best-effort
+ * {@link AUTH_STATE_TOKEN_STORAGE_KEY} (warm access token).
  *
  * Resilience:
  *  - If `localStorage` is unreachable (sandboxed-iframe `SecurityError`, SSR),
@@ -107,8 +129,11 @@ export declare function createWebAuthStateStore(): AuthStateStore;
  * A native {@link AuthStateStore} over an injected async key/value store.
  *
  * `@oxyhq/core` never imports `expo-secure-store`; `@oxyhq/services` constructs
- * the SecureStore-backed adapter and passes it here. Every operation is wrapped
- * so a storage exception degrades gracefully (read → `null`, write → swallowed)
- * exactly like the web store.
+ * the SecureStore-backed adapter and passes it here. Persistence is split across
+ * the durable {@link AUTH_STATE_STORAGE_KEY} (mint credential) and the
+ * best-effort {@link AUTH_STATE_TOKEN_STORAGE_KEY} (warm access token) — the
+ * durable write is read-back-verified and its failure surfaced (not swallowed),
+ * while the warm-token write and all reads degrade gracefully exactly like the
+ * web store.
  */
 export declare function createNativeAuthStateStore(storage: NativeKeyValueStorage): AuthStateStore;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "9.2.1",
+  "version": "9.2.2",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -94,7 +94,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "^0.13.1",
+    "@oxyhq/contracts": "^0.13.2",
     "@oxyhq/protocol": "^0.1.3",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",

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

@@ -82,6 +82,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 +103,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 {
@@ -287,6 +325,7 @@ export class SessionClient {
     if (this.socket) {
       this.socket.disconnect();
       this.socket = null;
+      this.boundServerEvents.clear();
     }
   }
 
@@ -341,6 +380,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.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__/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';
@@ -161,6 +162,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.toBeUndefined();
+
+    // 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', () => {
@@ -210,6 +308,78 @@ describe('createNativeAuthStateStore', () => {
     // The write threw, but the in-memory mirror preserves the session.
     expect(await store.load()).toEqual(SAMPLE);
   });
+
+  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.toBeUndefined();
+
+    // 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', () => {