@oxyhq/core 12.9.0 → 12.10.1

package/dist/types/HttpService.d.ts

@@ -40,6 +40,20 @@ export interface RequestOptions {
      * mint call fully independent of the current (near-expired) bearer.
      */
     skipAuth?: boolean;
+    /**
+     * Execute this request WITHOUT taking a `RequestQueue` slot — run it directly.
+     *
+     * A queue slot represents network occupancy for ordinary DATA requests. The
+     * CONTROL-PLANE calls the auth lane depends on (the device-secret mint, `POST
+     * /session/device/token`, reached from `getAuthHeader` → `refreshAccessToken`)
+     * must never compete for a slot: when `maxConcurrentRequests` requests are all
+     * parked awaiting that very mint, a queued mint could never acquire a slot to
+     * run — a systemic deadlock. `bypassQueue` lets the mint run even when the
+     * queue is saturated. (The auth preflight is also resolved OUTSIDE the slot in
+     * `request()`, so ordinary requests never hold a slot while awaiting the mint;
+     * this flag is the explicit guarantee for the mint itself.)
+     */
+    bypassQueue?: boolean;
 }
 interface RequestConfig extends RequestOptions {
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';

package/dist/types/crypto/keyManager.d.ts

@@ -396,6 +396,39 @@ export declare class KeyManager {
      * and NEVER cached, so a poisoned "no identity" verdict can no longer stick.
      */
     static getPublicKey(): Promise<string | null>;
+    /**
+     * Persist the recovery mnemonic (the 12-word phrase) into its dedicated,
+     * device-only keychain slot so the user can re-reveal it from Settings after
+     * onboarding.
+     *
+     * Called best-effort at identity creation/import, where the phrase is already
+     * in memory: a failure to persist it must NEVER fail the identity itself, so
+     * callers deliberately swallow the thrown error (logging it). Storage errors
+     * throw {@link IdentityUnavailableError} — same "cannot determine" semantics as
+     * the other getters — so a caller MAY observe/log the failure.
+     *
+     * The mnemonic is stored ONLY here — never in the marker, `getIdentityStatus`,
+     * logs, or any exported bundle.
+     */
+    static storeRecoveryMnemonic(mnemonic: string): Promise<void>;
+    /**
+     * Read the stored recovery mnemonic for re-reveal in Settings.
+     *
+     * Returns the phrase, or `null` when a read SUCCEEDS and finds none — the
+     * expected result for any identity created/imported before this feature
+     * existed, since the phrase was never captured for those. THROWS
+     * {@link IdentityUnavailableError} when storage is unreadable (keychain locked
+     * / module load failure), matching {@link getPublicKey}'s contract — a thrown
+     * read is never flattened to `null`, so a caller distinguishes "phrase was
+     * never stored" from "keychain temporarily locked, retry".
+     */
+    static getRecoveryMnemonic(): Promise<string | null>;
+    /**
+     * Delete the stored recovery mnemonic. Best-effort: a delete failure is logged
+     * and swallowed, never thrown — it runs inside the identity-deletion path where
+     * an unreadable keychain must not abort the wider teardown.
+     */
+    static deleteRecoveryMnemonic(): Promise<void>;
     /**
      * Check if a complete, parseable identity exists on this device.
      *

package/dist/types/index.d.ts

@@ -21,7 +21,8 @@ export { OxyServices, AssetUrlResolutionError, OxyAuthenticationError, OxyAuthen
 export { OXY_CLOUD_URL, oxyClient } from './OxyServices';
 export type { LinkedHttpClient } from './OxyServices.base';
 export type { AuthRefreshReason, AuthRefreshHandler } from './HttpService';
-export { ServiceCredentialMismatchError } from './mixins/OxyServices.auth';
+export { ServiceCredentialMismatchError, } from './mixins/OxyServices.auth';
+export { getCommonsApprovalBlockingReason, parseCommonsApprovalExpiresAt, } from './utils/commonsApproval';
 export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
 export type { CommonsSignInHandle, CommonsSignInStatus, CommonsApprovalInfo, CommonsSignInActionResult, } from './mixins/OxyServices.auth';
 export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServices.utility';

package/dist/types/mixins/OxyServices.auth.d.ts

@@ -8,6 +8,7 @@ import type { LoginResult, LoginSessionResult } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 import type { PublicApplication } from './OxyServices.connectedApps';
+export { getCommonsApprovalBlockingReason, parseCommonsApprovalExpiresAt, } from '../utils/commonsApproval';
 export interface ChallengeResponse {
     challenge: string;
     expiresAt: string;
@@ -71,7 +72,7 @@ export interface CommonsSignInStatus {
  */
 export interface CommonsApprovalInfo {
     /** Sanitized, display-safe identity of the requesting application. */
-    application: PublicApplication;
+    application: PublicApplication | null;
     /** OAuth scopes the application is requesting. */
     scopes: string[];
     /** The origin the session is bound to (the RP web origin), when applicable. */
@@ -84,8 +85,8 @@ export interface CommonsApprovalInfo {
      * "not verified") by {@link OxyServicesAuthMixin.getCommonsApprovalInfo}.
      */
     originVerified: boolean;
-    /** Server-authoritative expiry (epoch milliseconds). */
-    expiresAt: number;
+    /** Server-authoritative expiry (epoch ms or ISO-8601 string from the API). */
+    expiresAt: number | string;
     /** Session lifecycle status. */
     status: string;
 }
@@ -596,4 +597,3 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
         }>;
     };
 } & T;
-export {};

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

@@ -35,6 +35,13 @@
  * password, social login, and 2FA were removed ecosystem-wide. Account
  * creation (`signup` view) is the same two identity backends: a passkey
  * ceremony on web, or a Commons-created identity.
+ *
+ * The controller owns NO surface PRESENTATION: whether the account dialog is
+ * mounted, visible, or dismissed is the job of the shared surface stack
+ * (`@oxyhq/services` presents the `AccountDialog` surface into `@oxyhq/bloom`'s
+ * stack). This is a headless state machine only — it exposes `setView` /
+ * `add` / `startSignup` (the view axis) and `cancelSignIn` (device-flow
+ * teardown), never an `open` / `close` / `visible`.
  */
 import type { OxyServices } from '../OxyServices';
 import type { SessionLoginResponse, MinimalUserData } from '../models/session';
@@ -294,8 +301,6 @@ export declare class AccountDialogController {
     private reconcileAuth;
     /** Set the dialog view directly. */
     setView(view: AccountDialogView): void;
-    /** Return to the account list and cancel any in-flight sign-in flow. */
-    close(): void;
     /** Switch to the "add account" view (the sign-in entry chooser). */
     add(): void;
     /** Switch to the "create account" view (passkey / Commons signup entry). */

package/dist/types/utils/commonsApproval.d.ts

@@ -0,0 +1,13 @@
+import type { PublicApplication } from '../mixins/OxyServices.connectedApps';
+export interface CommonsApprovalValidationInput {
+    application: PublicApplication | null;
+    status: string;
+    expiresAt: number | string;
+}
+/**
+ * Returns a user-facing blocking reason when an approval payload must not be
+ * shown as actionable, or `null` when the request is still pending and valid.
+ */
+export declare function getCommonsApprovalBlockingReason(info: CommonsApprovalValidationInput): string | null;
+/** Normalize API `expiresAt` (number or ISO string) to epoch ms. */
+export declare function parseCommonsApprovalExpiresAt(expiresAt: CommonsApprovalValidationInput['expiresAt']): number | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "12.9.0",
+  "version": "12.10.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -115,8 +115,8 @@
   "dependencies": {
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxyhq/contracts": "^0.17.0",
-    "@oxyhq/protocol": "^0.1.5",
+    "@oxyhq/contracts": "workspace:^",
+    "@oxyhq/protocol": "workspace:^",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",
     "elliptic": "^6.6.1",

package/src/HttpService.ts

@@ -85,6 +85,20 @@ export interface RequestOptions {
    * mint call fully independent of the current (near-expired) bearer.
    */
   skipAuth?: boolean;
+  /**
+   * Execute this request WITHOUT taking a `RequestQueue` slot — run it directly.
+   *
+   * A queue slot represents network occupancy for ordinary DATA requests. The
+   * CONTROL-PLANE calls the auth lane depends on (the device-secret mint, `POST
+   * /session/device/token`, reached from `getAuthHeader` → `refreshAccessToken`)
+   * must never compete for a slot: when `maxConcurrentRequests` requests are all
+   * parked awaiting that very mint, a queued mint could never acquire a slot to
+   * run — a systemic deadlock. `bypassQueue` lets the mint run even when the
+   * queue is saturated. (The auth preflight is also resolved OUTSIDE the slot in
+   * `request()`, so ordinary requests never hold a slot while awaiting the mint;
+   * this flag is the explicit guarantee for the mint itself.)
+   */
+  bypassQueue?: boolean;
 }
 
 interface RequestConfig extends RequestOptions {
@@ -414,24 +428,29 @@ export class HttpService {
       this.requestMetrics.cacheMisses++;
     }
 
+    // Resolve the auth preflight OUTSIDE the queue slot. A slot represents
+    // NETWORK OCCUPANCY only. `getAuthHeader` may await the single-flight token
+    // refresh/mint — itself a request — so if a slot-holding request awaited it
+    // here and every slot were held by requests all waiting on that same mint,
+    // the mint could never acquire a slot to run (systemic deadlock). Resolving
+    // it before enqueue means auth-blocked requests hold NO slot while the shared
+    // mint runs. `skipAuth` requests (the body-authenticated mint) send NO bearer
+    // and skip the near-expiry preflight — see RequestOptions.skipAuth. The
+    // 401/CSRF retry re-enters request() with a fresh config, so it re-resolves
+    // these here with the refreshed token / cleared CSRF.
+    const isStateChangingMethod = ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method);
+    const authHeader = config.skipAuth ? null : await this.getAuthHeader();
+    // CSRF protects cookie-authenticated browser writes. Bearer-authenticated SDK
+    // clients are not vulnerable to ambient-cookie CSRF, and linked app APIs
+    // should not need to implement a duplicate `/csrf-token` route.
+    const csrfToken = isStateChangingMethod && !authHeader ? await this.fetchCsrfToken() : null;
+
     // Request function
     const requestFn = async (): Promise<T> => {
       const startTime = Date.now();
       try {
         // Build URL with params
         const fullUrl = this.buildURL(url, params);
-        
-        // Get auth token (with auto-refresh). `skipAuth` requests (the
-        // body-authenticated refresh endpoint) send NO bearer and skip the
-        // near-expiry preflight — see RequestOptions.skipAuth for the deadlock
-        // this avoids.
-        const authHeader = config.skipAuth ? null : await this.getAuthHeader();
-
-        // CSRF protects cookie-authenticated browser writes. Bearer-authenticated
-        // SDK clients are not vulnerable to ambient-cookie CSRF, and linked app
-        // APIs should not need to implement a duplicate `/csrf-token` route.
-        const isStateChangingMethod = ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method);
-        const csrfToken = isStateChangingMethod && !authHeader ? await this.fetchCsrfToken() : null;
 
         // Determine if data is FormData using robust detection
         const isFormData = this.isFormData(data);
@@ -665,8 +684,12 @@ export class HttpService {
       ? () => this.deduplicator.deduplicate(dedupeKey, requestWithRetry)
       : requestWithRetry;
 
-    // Execute request (with queue if needed)
-    const result = await this.requestQueue.enqueue(finalRequest);
+    // Execute the request. Control-plane calls the auth lane depends on
+    // (`bypassQueue`, e.g. the device-secret mint) run DIRECTLY — a queued mint
+    // could never acquire a slot when every slot is parked awaiting it.
+    const result = config.bypassQueue
+      ? await finalRequest()
+      : await this.requestQueue.enqueue(finalRequest);
 
     // Cache the result if caching is enabled
     if (cache && cacheKey && result) {

package/src/__tests__/httpServiceAuthSelfAwait.test.ts

@@ -0,0 +1,108 @@
+/**
+ * Auth self-await regression.
+ *
+ * The refresh handler (arm 2 shared-key sign-in) calls PRE-SESSION public
+ * endpoints (`/auth/challenge`, `/auth/verify`, the commons-signin surface, …)
+ * from INSIDE the single-flight `tokenRefreshPromise`. If any of those carried
+ * an auth preflight (no `skipAuth`), its `getAuthHeader` would call
+ * `refreshAccessToken`, find the handler's own promise already in flight, and
+ * await it — the handler awaiting itself → permanent hang (no deadline on the
+ * auto-connect lane makes it visible). `skipAuth` on every pre-session public
+ * endpoint is what prevents this; these tests lock the invariant.
+ */
+import { HttpService } from '../HttpService';
+
+function createJwt(payload: Record<string, unknown>): string {
+  const encode = (value: unknown): string => Buffer.from(JSON.stringify(value)).toString('base64url');
+  return `${encode({ alg: 'HS256', typ: 'JWT' })}.${encode(payload)}.signature`;
+}
+
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+const nowSec = (): number => Math.floor(Date.now() / 1000);
+
+/** Resolve to `true` if `promise` settles within `ms`, else `false`. Always
+ *  clears its timer so no pending timeout leaks into jest's teardown. */
+async function settlesWithin(promise: Promise<unknown>, ms: number): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<false>((resolve) => {
+    timer = setTimeout(() => resolve(false), ms);
+  });
+  try {
+    return await Promise.race([promise.then(() => true), timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+describe('HttpService auth self-await', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.restoreAllMocks();
+  });
+
+  it('a skipAuth request issued from INSIDE the refresh handler resolves (no self-await)', async () => {
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes('/auth/challenge')) return jsonResponse({ challenge: 'c' });
+      return jsonResponse({ ok: true });
+    }) as typeof fetch;
+
+    const http = new HttpService({ baseURL: 'https://api.oxy.so', enableRetry: false });
+    // Near-expiry → the data request's preflight starts the refresh.
+    http.setTokens(createJwt({ userId: 'u', exp: nowSec() + 30 }));
+
+    http.setAuthRefreshHandler(async () => {
+      // Mirror arm 2: from inside the handler, hit a pre-session public endpoint.
+      // With skipAuth it does NOT re-enter refreshAccessToken; without it, its
+      // preflight would await THIS handler's own pending promise → self-await.
+      await http.post('/auth/challenge', { publicKey: 'p' }, { skipAuth: true, retry: false });
+      const fresh = createJwt({ userId: 'u', exp: nowSec() + 3600, jti: 'fresh' });
+      http.setTokens(fresh);
+      return fresh;
+    });
+
+    expect(await settlesWithin(http.get('/data'), 500)).toBe(true);
+  });
+
+  it('a skipAuth public request does NOT await a pending refresh', async () => {
+    let releaseRefresh: (() => void) | undefined;
+    const refreshGate = new Promise<void>((resolve) => {
+      releaseRefresh = resolve;
+    });
+
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes('/auth/challenge')) return jsonResponse({ challenge: 'c' });
+      return jsonResponse({ ok: true });
+    }) as typeof fetch;
+
+    const http = new HttpService({ baseURL: 'https://api.oxy.so', enableRetry: false });
+    http.setTokens(createJwt({ userId: 'u', exp: nowSec() + 30 }));
+
+    http.setAuthRefreshHandler(async () => {
+      await refreshGate; // hold the refresh open
+      const fresh = createJwt({ userId: 'u', exp: nowSec() + 3600, jti: 'fresh' });
+      http.setTokens(fresh);
+      return fresh;
+    });
+
+    // A data request whose preflight starts (and blocks on) the held refresh.
+    const data = http.get('/data');
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    // A skipAuth public request must settle WITHOUT waiting for the held refresh.
+    const pub = http.post('/auth/challenge', { publicKey: 'p' }, { skipAuth: true, retry: false });
+    expect(await settlesWithin(pub, 300)).toBe(true);
+
+    releaseRefresh?.();
+    await data;
+  });
+});

package/src/__tests__/httpServiceQueueDeadlock.test.ts

@@ -0,0 +1,128 @@
+/**
+ * RequestQueue deadlock regression.
+ *
+ * The auth preflight (`getAuthHeader` → single-flight `refreshAccessToken` → the
+ * device-secret mint) used to run INSIDE a RequestQueue slot, and the mint itself
+ * went through the queue. When `maxConcurrentRequests` requests all parked in
+ * slots awaiting that same mint, the mint could never acquire a slot to run —
+ * a systemic deadlock in which NOTHING settles (observed on a real device: the
+ * running count climbs to the pool size with zero settled requests, including a
+ * public GET /health). The fix: (1) `bypassQueue` runs control-plane calls (the
+ * mint) directly, and (2) the preflight is resolved OUTSIDE the slot, so an
+ * auth-blocked request never holds a slot while the shared mint runs.
+ */
+import { HttpService } from '../HttpService';
+
+function createJwt(payload: Record<string, unknown>): string {
+  const encode = (value: unknown): string => Buffer.from(JSON.stringify(value)).toString('base64url');
+  return `${encode({ alg: 'HS256', typ: 'JWT' })}.${encode(payload)}.signature`;
+}
+
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+/** Resolve to `true` if `promise` settles within `ms`, else `false`. Always
+ *  clears its timer so no pending timeout leaks into jest's teardown. */
+async function settlesWithin(promise: Promise<unknown>, ms: number): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<false>((resolve) => {
+    timer = setTimeout(() => resolve(false), ms);
+  });
+  try {
+    return await Promise.race([promise.then(() => true), timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+describe('HttpService RequestQueue deadlock', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.restoreAllMocks();
+  });
+
+  it('runs a bypassQueue control-plane request even when every slot is held', async () => {
+    const releases: Array<() => void> = [];
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes('/slow')) {
+        // Occupy the slot indefinitely until explicitly released.
+        await new Promise<void>((resolve) => releases.push(resolve));
+        return jsonResponse({ slow: true });
+      }
+      return jsonResponse({ minted: true });
+    }) as typeof fetch;
+
+    const http = new HttpService({
+      baseURL: 'https://api.oxy.so',
+      maxConcurrentRequests: 2,
+      enableRetry: false,
+    });
+
+    // Saturate both slots with requests whose fetch never settles.
+    const slowA = http.get('/slow/a', { skipAuth: true });
+    const slowB = http.get('/slow/b', { skipAuth: true });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    // The device-secret mint (bypassQueue) must still run despite full saturation.
+    const mint = http.post(
+      '/session/device/token',
+      { deviceId: 'd', deviceSecret: 's' },
+      { skipAuth: true, bypassQueue: true, retry: false },
+    );
+
+    expect(await settlesWithin(mint, 500)).toBe(true);
+
+    releases.forEach((release) => release());
+    await Promise.all([slowA, slowB]);
+  });
+
+  it('does not deadlock when a boot burst larger than the pool all trigger the same preflight mint', async () => {
+    const now = Math.floor(Date.now() / 1000);
+    // Within the 60s refresh lead window → every request's preflight refreshes.
+    const nearExpiry = createJwt({ userId: 'u', exp: now + 30 });
+    const fresh = createJwt({ userId: 'u', exp: now + 3600, jti: 'fresh' });
+
+    let mintCalls = 0;
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes('/session/device/token')) {
+        mintCalls += 1;
+        return jsonResponse({ minted: true });
+      }
+      return jsonResponse({ ok: true });
+    }) as typeof fetch;
+
+    const http = new HttpService({
+      baseURL: 'https://api.oxy.so',
+      maxConcurrentRequests: 2,
+      enableRetry: false,
+    });
+    http.setTokens(nearExpiry);
+
+    http.setAuthRefreshHandler(async () => {
+      // Mirror refreshDeviceSecretArm: mint via a bypassQueue request through the
+      // SAME instance, then plant + return the fresh token.
+      await http.post(
+        '/session/device/token',
+        { deviceId: 'd', deviceSecret: 's' },
+        { skipAuth: true, bypassQueue: true, retry: false },
+      );
+      http.setTokens(fresh);
+      return fresh;
+    });
+
+    // A boot burst of 4 against a pool of 2, all in the near-expiry window.
+    const burst = Promise.all([http.get('/a'), http.get('/b'), http.get('/c'), http.get('/d')]);
+
+    expect(await settlesWithin(burst, 800)).toBe(true);
+    // The single-flight refresh coalesces the whole burst into ONE mint.
+    expect(mintCalls).toBe(1);
+  });
+});

package/src/crypto/__tests__/keyManager.recoveryMnemonic.test.ts

@@ -0,0 +1,138 @@
+/**
+ * Recovery-mnemonic storage: a dedicated, device-only keychain slot that lets a
+ * user re-reveal their 12-word phrase from Settings. Isolated from the identity
+ * primary/backup slots (its own keychain service), null-on-absent, typed-throw
+ * on a locked keychain, and wiped when the identity is deleted.
+ */
+
+import { setPlatformOS } from '../../utils/platform';
+
+jest.mock(
+  'expo-secure-store',
+  () => {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { createSecureStoreMock } = require('./identityMocks');
+    return createSecureStoreMock();
+  },
+  { virtual: true },
+);
+
+jest.mock(
+  'expo-crypto',
+  () => ({
+    __esModule: true,
+    getRandomBytes: (length: number) => {
+      const out = new Uint8Array(length);
+      for (let i = 0; i < length; i++) out[i] = (Math.random() * 256) & 0xff;
+      return out;
+    },
+    digestStringAsync: async () => '0'.repeat(64),
+    CryptoDigestAlgorithm: { SHA256: 'SHA-256' },
+  }),
+  { virtual: true },
+);
+
+jest.mock('@oxyhq/protocol', () => {
+  const actual = jest.requireActual('@oxyhq/protocol');
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { createAsyncStorageMock } = require('./identityMocks');
+  const asyncStorage = createAsyncStorageMock();
+  return {
+    __esModule: true,
+    ...actual,
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    loadExpoCrypto: async () => require('expo-crypto'),
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    loadSecureStore: async () => require('expo-secure-store'),
+    loadAsyncStorage: async () => ({ default: asyncStorage }),
+    loadSharedIdentityBridge: async () => null,
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    loadNodeCrypto: async () => require('crypto'),
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    getRandomBytesRN: (n: number) => require('expo-crypto').getRandomBytes(n),
+  };
+});
+
+const MNEMONIC_SVC = 'oxy_identity_mnemonic';
+const MNEMONIC_KEY = 'oxy_identity_mnemonic_v1';
+const PRIMARY_SVC = 'oxy_identity';
+const PHRASE = 'legal winner thank year wave sausage worth useful legal winner thank yellow';
+
+interface SecureStoreTestHandle {
+  __resetStore__: () => void;
+  __getRaw__: (key: string, service?: string) => string | null;
+  __simulateKeystoreDeath__: (service: string) => void;
+  __failPlan__: { failKey?: string; failOp?: 'set' | 'get'; failTimes?: number; failService?: string };
+}
+
+describe('KeyManager recovery mnemonic storage', () => {
+  let KeyManager: typeof import('../keyManager').KeyManager;
+  let IdentityUnavailableError: typeof import('../keyManager').IdentityUnavailableError;
+  let ss: SecureStoreTestHandle;
+
+  beforeAll(() => {
+    setPlatformOS('ios');
+    (globalThis as unknown as { navigator: unknown }).navigator = { product: 'ReactNative' };
+  });
+
+  beforeEach(async () => {
+    jest.resetModules();
+    setPlatformOS('ios');
+    ss = (await import('expo-secure-store' as string)) as unknown as SecureStoreTestHandle;
+    ss.__resetStore__();
+    const km = await import('../keyManager');
+    KeyManager = km.KeyManager;
+    IdentityUnavailableError = km.IdentityUnavailableError;
+  });
+
+  it('round-trips a stored mnemonic', async () => {
+    await KeyManager.storeRecoveryMnemonic(PHRASE);
+    expect(await KeyManager.getRecoveryMnemonic()).toBe(PHRASE);
+  });
+
+  it('persists under its OWN keychain service, isolated from the identity slots', async () => {
+    await KeyManager.storeRecoveryMnemonic(PHRASE);
+    // Present under the mnemonic service, invisible under the primary service.
+    expect(ss.__getRaw__(MNEMONIC_KEY, MNEMONIC_SVC)).toBe(PHRASE);
+    expect(ss.__getRaw__(MNEMONIC_KEY, PRIMARY_SVC)).toBeNull();
+  });
+
+  it('returns null when no mnemonic was ever stored (pre-feature identity)', async () => {
+    expect(await KeyManager.getRecoveryMnemonic()).toBeNull();
+  });
+
+  it('survives a keystore death of the identity primary service', async () => {
+    await KeyManager.storeRecoveryMnemonic(PHRASE);
+    // The identity primary slot dies; the mnemonic lives in a distinct service.
+    ss.__simulateKeystoreDeath__(PRIMARY_SVC);
+    expect(await KeyManager.getRecoveryMnemonic()).toBe(PHRASE);
+  });
+
+  it('throws IdentityUnavailableError (never null) when the read throws', async () => {
+    await KeyManager.storeRecoveryMnemonic(PHRASE);
+    ss.__failPlan__.failOp = 'get';
+    ss.__failPlan__.failKey = MNEMONIC_KEY;
+    ss.__failPlan__.failService = MNEMONIC_SVC;
+    await expect(KeyManager.getRecoveryMnemonic()).rejects.toBeInstanceOf(IdentityUnavailableError);
+  });
+
+  it('throws IdentityUnavailableError when the write throws', async () => {
+    ss.__failPlan__.failOp = 'set';
+    ss.__failPlan__.failKey = MNEMONIC_KEY;
+    ss.__failPlan__.failService = MNEMONIC_SVC;
+    await expect(KeyManager.storeRecoveryMnemonic(PHRASE)).rejects.toBeInstanceOf(IdentityUnavailableError);
+  });
+
+  it('deleteRecoveryMnemonic removes the stored phrase', async () => {
+    await KeyManager.storeRecoveryMnemonic(PHRASE);
+    await KeyManager.deleteRecoveryMnemonic();
+    expect(await KeyManager.getRecoveryMnemonic()).toBeNull();
+  });
+
+  it('deleteIdentity(force) wipes the stored mnemonic', async () => {
+    await KeyManager.createIdentity();
+    await KeyManager.storeRecoveryMnemonic(PHRASE);
+    await KeyManager.deleteIdentity(true, true, true);
+    expect(await KeyManager.getRecoveryMnemonic()).toBeNull();
+  });
+});