@oxyhq/core 12.7.0 → 12.9.0

package/src/boot/__tests__/sessionColdBoot.test.ts

@@ -455,3 +455,116 @@ describe('runSessionColdBoot — signed out', () => {
     expect(setTokens).not.toHaveBeenCalled();
   });
 });
+
+describe('runSessionColdBoot — offline gating (isOffline)', () => {
+  /** Comfortably beyond the 60s refresh lead window. */
+  const farFuture = () => new Date(Date.now() + 3_600_000).toISOString();
+
+  const sharedSession: SessionLoginResponse = {
+    sessionId: 'sess-shared',
+    deviceId: 'dev-1',
+    expiresAt: '2030-01-01T00:00:00.000Z',
+    user: { id: 'user-shared', username: 'u', name: {}, avatar: undefined },
+    accessToken: 'access-shared',
+  };
+
+  it('offline: skips BOTH network steps (no mint, no shared-key) → signed out', async () => {
+    // Credential present, no warm token — the ONLY things that could resolve are
+    // the two network steps, which the offline hint must gate off.
+    const { store, seed } = seedCredStore();
+    await seed();
+    const mintFromDeviceSecret = jest.fn(async () => MINT);
+    const signInWithSharedIdentity = jest.fn(async () => sharedSession);
+    const { oxy } = makeOxy({ mintFromDeviceSecret, signInWithSharedIdentity });
+    const onSignedOut = jest.fn();
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: NATIVE,
+      isOffline: () => true,
+      onSignedOut,
+    });
+
+    expect(outcome).toEqual({ kind: 'unauthenticated' });
+    expect(mintFromDeviceSecret).not.toHaveBeenCalled();
+    expect(signInWithSharedIdentity).not.toHaveBeenCalled();
+    expect(onSignedOut).toHaveBeenCalledWith('no_session');
+  });
+
+  it('offline: the pure-local warm-token-plant STILL runs (returning user boots authenticated offline)', async () => {
+    const { store, seed } = seedCredStore({ accessToken: 'warm-access', expiresAt: farFuture() });
+    await seed();
+    const mintFromDeviceSecret = jest.fn(async () => MINT);
+    const { oxy, setTokens } = makeOxy({ mintFromDeviceSecret });
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: NATIVE,
+      isOffline: () => true,
+    });
+
+    // Warm plant is a pure-local read — never gated by the offline hint.
+    expect(outcome).toMatchObject({ kind: 'session', via: 'warm-token-plant' });
+    expect(setTokens).toHaveBeenCalledWith('warm-access');
+    expect(mintFromDeviceSecret).not.toHaveBeenCalled();
+  });
+
+  it('online (isOffline:()=>false): the network mint runs as normal', async () => {
+    const { store, seed } = seedCredStore();
+    await seed();
+    const mintFromDeviceSecret = jest.fn(async () => MINT);
+    const { oxy } = makeOxy({ mintFromDeviceSecret });
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: WEB,
+      isOffline: () => false,
+    });
+
+    expect(outcome).toMatchObject({ kind: 'session', via: 'device-secret-mint' });
+    expect(mintFromDeviceSecret).toHaveBeenCalledWith('dev-mint', 'ds-secret-orig');
+  });
+
+  it('shared-key-signin passes { requestOptions: { retry: false } } (cold-boot single-attempt)', async () => {
+    const store = createMemoryAuthStateStore(); // no mint credential → mint step no-secret skip
+    const signInWithSharedIdentity = jest.fn(async () => sharedSession);
+    const { oxy } = makeOxy({ signInWithSharedIdentity });
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: NATIVE });
+
+    expect(outcome).toMatchObject({ kind: 'session', via: 'shared-key-signin' });
+    expect(signInWithSharedIdentity).toHaveBeenCalledWith({ requestOptions: { retry: false } });
+  });
+});
+
+describe('runSessionColdBoot — overall deadline (overallDeadlineMs + onStepDeadline)', () => {
+  it('forwards the deadline: a non-settling mint step is abandoned via onStepDeadline and the boot ends bounded', async () => {
+    const { store, seed } = seedCredStore();
+    await seed();
+    // A mint that NEVER settles — without the overall deadline this hangs the
+    // whole boot (and therefore app routing) forever.
+    const mintFromDeviceSecret = jest.fn(
+      () => new Promise<DeviceTokenMintResponse>(() => undefined),
+    );
+    const { oxy } = makeOxy({ mintFromDeviceSecret });
+    const onStepDeadline = jest.fn();
+    const onSignedOut = jest.fn();
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: WEB,
+      overallDeadlineMs: 50,
+      onStepDeadline,
+      onSignedOut,
+    });
+
+    expect(outcome).toEqual({ kind: 'unauthenticated' });
+    expect(onStepDeadline).toHaveBeenCalledWith('device-secret-mint');
+    // A deadline trip is not an error — the boot resolves signed-out, not `error`.
+    expect(onSignedOut).toHaveBeenCalledWith('no_session');
+  });
+});

package/src/boot/sessionColdBoot.ts

@@ -47,6 +47,31 @@ export interface RunSessionColdBootOptions {
   /** Invoked when the boot ended signed out. */
   onSignedOut?: (reason: SignedOutReason) => void | Promise<void>;
   onStepError?: (id: string, error: unknown) => void;
+  /**
+   * HARD overall deadline (ms) for the whole ordered step chain, forwarded to
+   * {@link runColdBoot}. Defense-in-depth so a single non-settling network step
+   * (a black-hole network that neither connects nor rejects) can NEVER hang the
+   * boot — and therefore app routing — indefinitely. Inert on healthy loads
+   * (every step settles well under it); only trips on pathological networks.
+   * When omitted there is no overall deadline (unchanged behavior).
+   */
+  overallDeadlineMs?: number;
+  /**
+   * Invoked once per step abandoned because {@link overallDeadlineMs} expired
+   * before it settled. Forwarded to {@link runColdBoot}. Must not throw.
+   */
+  onStepDeadline?: (stepId: string) => void;
+  /**
+   * Best-effort connectivity hint. When it returns `true` the two NETWORK steps
+   * (`device-secret-mint`, `shared-key-signin`) are skipped — an offline device
+   * cannot mint, and attempting to would burn the whole deadline on a doomed
+   * request before routing settles. The pure-local `warm-token-plant` step is
+   * NEVER gated by this: an offline returning user with an unexpired persisted
+   * token must still boot authenticated. Only an EXPLICIT offline verdict should
+   * be returned; the caller resolves unknown/timeout to `false` (assume online)
+   * so a flaky probe can never falsely skip a real sign-in.
+   */
+  isOffline?: () => boolean;
 }
 
 /**
@@ -60,6 +85,11 @@ export async function runSessionColdBoot(
   const { oxy, store } = opts;
   const isNative = opts.platform?.isNative ?? detectNative();
 
+  // Best-effort connectivity gate for the NETWORK steps only. A missing hint or
+  // any non-`true` verdict means "assume online" — never falsely skip a real
+  // sign-in on an ambiguous probe.
+  const isOffline = (): boolean => opts.isOffline?.() ?? false;
+
   // Boot-local (not module-level) so it cannot leak across boots or break under
   // bundler re-evaluation.
   let signedOutReason: SignedOutReason = 'no_session';
@@ -114,6 +144,9 @@ export async function runSessionColdBoot(
   //    the durable store always converges on the true `current` secret.
   steps.push({
     id: 'device-secret-mint',
+    // Network step — skip entirely when the caller reports the device offline so
+    // a doomed mint cannot burn the overall deadline before routing settles.
+    enabled: () => !isOffline(),
     run: async () => {
       const result = await refreshDeviceSecretArm({ oxy, store });
       switch (result.status) {
@@ -166,12 +199,16 @@ export async function runSessionColdBoot(
     },
   });
 
-  // 3. shared-key-signin (native) — re-mint from the shared identity.
+  // 3. shared-key-signin (native) — re-mint from the shared identity. Native
+  //    AND online: it is a network step (challenge + verify round-trips), so it
+  //    is gated by the same offline hint as the mint lane. `{ retry: false }`
+  //    keeps the two round-trips as single attempts — the refresh scheduler /
+  //    401 lane own later retries — so this step cannot multiply boot latency.
   steps.push({
     id: 'shared-key-signin',
-    enabled: () => isNative,
+    enabled: () => isNative && !isOffline(),
     run: async () => {
-      const session = await oxy.signInWithSharedIdentity();
+      const session = await oxy.signInWithSharedIdentity({ requestOptions: { retry: false } });
       if (!session?.accessToken) {
         return { kind: 'skip' };
       }
@@ -201,6 +238,8 @@ export async function runSessionColdBoot(
 
   const outcome = await runColdBoot<DeviceBootSession>({
     steps,
+    overallDeadlineMs: opts.overallDeadlineMs,
+    onStepDeadline: opts.onStepDeadline,
     onStepError: (id, error) => {
       signedOutReason = 'error';
       opts.onStepError?.(id, error);

package/src/crypto/__tests__/identityMocks.ts

@@ -0,0 +1,125 @@
+/**
+ * Shared in-memory mocks for KeyManager identity tests.
+ *
+ * The secure-store mock keys every entry by `(keychainService ?? 'default') + ' '
+ * + key` so the v2 slot layout — which gives the primary and backup DISTINCT
+ * keychain services — is faithfully modeled (a write under one service is
+ * invisible to a read under another, exactly like Android's per-service
+ * AndroidKeyStore keys).
+ *
+ * `__simulateKeystoreDeath__(service)` reproduces the SDK 57 Android failure mode
+ * this whole hardening defends against: an undecryptable entry is DELETED on the
+ * READ path and the read returns `null` (no throw). A subsequent write under that
+ * service creates a fresh, readable entry (a new keystore key), so recovery can
+ * re-persist afterwards.
+ *
+ * The AsyncStorage mock is a real in-memory map (the identity marker + the
+ * advisory migration flag live here — independent of the keychain).
+ */
+
+type FailOp = 'set' | 'get';
+
+export interface FailPlan {
+  failKey?: string;
+  failOp?: FailOp;
+  failTimes?: number;
+  /** Restrict the fault to one keychain service (`'default'` for unscoped keys). */
+  failService?: string;
+}
+
+const compositeKey = (service: string | undefined, key: string): string =>
+  `${service ?? 'default'} ${key}`;
+
+export function createSecureStoreMock() {
+  const store = new Map<string, string>(); // keyed by `${service} ${key}`
+  const poisoned = new Set<string>(); // composite keys pending delete-on-read (keystore death)
+  const failPlan: FailPlan = {};
+
+  const maybeFail = (op: FailOp, key: string, service?: string): void => {
+    if (
+      failPlan.failOp === op &&
+      failPlan.failKey === key &&
+      (failPlan.failService === undefined || failPlan.failService === (service ?? 'default'))
+    ) {
+      if (failPlan.failTimes !== undefined) {
+        failPlan.failTimes -= 1;
+        if (failPlan.failTimes <= 0) {
+          failPlan.failKey = undefined;
+          failPlan.failOp = undefined;
+          failPlan.failTimes = undefined;
+          failPlan.failService = undefined;
+        }
+      }
+      throw new Error(`Simulated ${op} failure for ${key}`);
+    }
+  };
+
+  return {
+    __esModule: true,
+    WHEN_UNLOCKED_THIS_DEVICE_ONLY: 'WHEN_UNLOCKED_THIS_DEVICE_ONLY',
+    WHEN_UNLOCKED: 'WHEN_UNLOCKED',
+    setItemAsync: jest.fn(async (key: string, value: string, opts?: { keychainService?: string }) => {
+      maybeFail('set', key, opts?.keychainService);
+      const ck = compositeKey(opts?.keychainService, key);
+      poisoned.delete(ck); // a fresh write mints a new (readable) keystore entry
+      store.set(ck, value);
+    }),
+    getItemAsync: jest.fn(async (key: string, opts?: { keychainService?: string }) => {
+      maybeFail('get', key, opts?.keychainService);
+      const ck = compositeKey(opts?.keychainService, key);
+      if (poisoned.has(ck)) {
+        // Android SDK 57: undecryptable ciphertext is DELETED on read → null.
+        poisoned.delete(ck);
+        store.delete(ck);
+        return null;
+      }
+      return store.get(ck) ?? null;
+    }),
+    deleteItemAsync: jest.fn(async (key: string, opts?: { keychainService?: string }) => {
+      const ck = compositeKey(opts?.keychainService, key);
+      poisoned.delete(ck);
+      store.delete(ck);
+    }),
+    __resetStore__: () => {
+      store.clear();
+      poisoned.clear();
+      failPlan.failKey = undefined;
+      failPlan.failOp = undefined;
+      failPlan.failTimes = undefined;
+      failPlan.failService = undefined;
+    },
+    __getStore__: () => store,
+    __getRaw__: (key: string, service?: string): string | null => store.get(compositeKey(service, key)) ?? null,
+    __setRaw__: (key: string, value: string, service?: string): void => {
+      store.set(compositeKey(service, key), value);
+    },
+    __deleteRaw__: (key: string, service?: string): void => {
+      store.delete(compositeKey(service, key));
+    },
+    __simulateKeystoreDeath__: (service: string): void => {
+      // Mark every existing entry under this service as undecryptable; the next
+      // read of each deletes it and returns null.
+      for (const ck of store.keys()) {
+        if (ck.startsWith(`${service} `)) {
+          poisoned.add(ck);
+        }
+      }
+    },
+    __failPlan__: failPlan,
+  };
+}
+
+export function createAsyncStorageMock() {
+  const map = new Map<string, string>();
+  return {
+    getItem: async (key: string): Promise<string | null> => map.get(key) ?? null,
+    setItem: async (key: string, value: string): Promise<void> => {
+      map.set(key, value);
+    },
+    removeItem: async (key: string): Promise<void> => {
+      map.delete(key);
+    },
+    __map__: map,
+    __reset__: (): void => map.clear(),
+  };
+}

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

@@ -14,56 +14,20 @@
  *   3. restoreIdentityFromBackup() must refuse when the backup identifies a
  *      different account than a private key still present in the primary slot.
  *   4. A first-time create still writes a backup (no regression).
+ *
+ * The identity now lives in the isolated v2 slots (primary service `oxy_identity`,
+ * backup service `oxy_identity_backup`), so assertions read/write via the
+ * service-scoped mock helpers.
  */
 
 import { setPlatformOS } from '../../utils/platform';
 
-// Fault-injectable in-memory secure store. `failPlan` lets a test make a
-// specific (op, key) pair throw to simulate a keychain that fails mid-write or
-// is transiently locked.
-const failPlan: { failKey?: string; failOp?: 'set' | 'get'; failTimes?: number } = {};
-
 jest.mock(
   'expo-secure-store',
   () => {
-    const store = new Map<string, string>();
-    const maybeFail = (op: 'set' | 'get', key: string) => {
-      if (failPlan.failOp === op && failPlan.failKey === key) {
-        if (failPlan.failTimes !== undefined) {
-          failPlan.failTimes -= 1;
-          if (failPlan.failTimes <= 0) {
-            failPlan.failKey = undefined;
-            failPlan.failOp = undefined;
-            failPlan.failTimes = undefined;
-          }
-        }
-        throw new Error(`Simulated ${op} failure for ${key}`);
-      }
-    };
-    return {
-      __esModule: true,
-      WHEN_UNLOCKED_THIS_DEVICE_ONLY: 'WHEN_UNLOCKED_THIS_DEVICE_ONLY',
-      WHEN_UNLOCKED: 'WHEN_UNLOCKED',
-      setItemAsync: jest.fn(async (key: string, value: string) => {
-        maybeFail('set', key);
-        store.set(key, value);
-      }),
-      getItemAsync: jest.fn(async (key: string) => {
-        maybeFail('get', key);
-        return store.get(key) ?? null;
-      }),
-      deleteItemAsync: jest.fn(async (key: string) => {
-        store.delete(key);
-      }),
-      __resetStore__: () => {
-        store.clear();
-        failPlan.failKey = undefined;
-        failPlan.failOp = undefined;
-        failPlan.failTimes = undefined;
-      },
-      __getStore__: () => store,
-      __failPlan__: failPlan,
-    };
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { createSecureStoreMock } = require('./identityMocks');
+    return createSecureStoreMock();
   },
   { virtual: true },
 );
@@ -83,35 +47,55 @@ jest.mock(
   { virtual: true },
 );
 
-jest.mock('@oxyhq/protocol', () => ({
-  __esModule: true,
-  ...jest.requireActual('@oxyhq/protocol'),
-  // 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: { getItem: async () => null, setItem: async () => undefined, removeItem: async () => undefined },
-  }),
+jest.mock('@oxyhq/protocol', () => {
+  const actual = jest.requireActual('@oxyhq/protocol');
   // 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 { 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),
+  };
+});
+
+// v2 slot key names + keychain services (must match keyManager.ts).
+const PRIMARY_SVC = 'oxy_identity';
+const BACKUP_SVC = 'oxy_identity_backup';
+const V2_PRIV = 'oxy_identity_private_key_v2';
+const V2_PUB = 'oxy_identity_public_key_v2';
+const V2_BPRIV = 'oxy_identity_backup_private_key_v2';
+const V2_BPUB = 'oxy_identity_backup_public_key_v2';
 
 interface SecureStoreTestHandle {
   __resetStore__: () => void;
-  __getStore__: () => Map<string, string>;
-  __failPlan__: { failKey?: string; failOp?: 'set' | 'get'; failTimes?: number };
+  __getRaw__: (key: string, service?: string) => string | null;
+  __setRaw__: (key: string, value: string, service?: string) => void;
+  __deleteRaw__: (key: string, service?: string) => void;
+  __failPlan__: { failKey?: string; failOp?: 'set' | 'get'; failTimes?: number; failService?: string };
 }
 
 describe('KeyManager atomicity & recoverability under flaky storage', () => {
   let KeyManager: typeof import('../keyManager').KeyManager;
 
   const resetCaches = () => {
-    const km = KeyManager as unknown as { cachedPublicKey: unknown; cachedHasIdentity: unknown };
+    const km = KeyManager as unknown as {
+      cachedPublicKey: unknown;
+      cachedHasIdentity: unknown;
+      cachedPublicKeyResolved: unknown;
+    };
     km.cachedPublicKey = null;
     km.cachedHasIdentity = null;
+    km.cachedPublicKeyResolved = false;
   };
 
   beforeAll(() => {
@@ -132,34 +116,35 @@ describe('KeyManager atomicity & recoverability under flaky storage', () => {
   it('a failed OVERWRITE leaves the ORIGINAL identity intact and recoverable (no silent switch)', async () => {
     const originalPublic = await KeyManager.createIdentity();
     const ss = (await import('expo-secure-store' as string)) as unknown as SecureStoreTestHandle;
-    const originalPriv = ss.__getStore__().get('oxy_identity_private_key');
+    const originalPriv = ss.__getRaw__(V2_PRIV, PRIMARY_SVC);
     resetCaches();
 
     // The new primary private write fails mid-overwrite.
     ss.__failPlan__.failOp = 'set';
-    ss.__failPlan__.failKey = 'oxy_identity_private_key';
+    ss.__failPlan__.failKey = V2_PRIV;
+    ss.__failPlan__.failService = PRIMARY_SVC;
     await expect(KeyManager.createIdentity({ overwrite: true })).rejects.toBeDefined();
 
     // Recover from the simulated fault.
     ss.__failPlan__.failKey = undefined;
     ss.__failPlan__.failOp = undefined;
+    ss.__failPlan__.failService = undefined;
     resetCaches();
 
     // Primary must still be the original identity (rolled back).
     expect(await KeyManager.hasIdentity()).toBe(true);
     expect(await KeyManager.getPublicKey()).toBe(originalPublic);
-    expect(ss.__getStore__().get('oxy_identity_private_key')).toBe(originalPriv);
+    expect(ss.__getRaw__(V2_PRIV, PRIMARY_SVC)).toBe(originalPriv);
 
     // And the backup must still hold the ORIGINAL identity, never the new one.
-    const m = ss.__getStore__();
-    expect(m.get('oxy_identity_backup_private_key')).toBe(originalPriv);
-    expect(m.get('oxy_identity_backup_public_key')).toBe(originalPublic);
+    expect(ss.__getRaw__(V2_BPRIV, BACKUP_SVC)).toBe(originalPriv);
+    expect(ss.__getRaw__(V2_BPUB, BACKUP_SVC)).toBe(originalPublic);
   });
 
   it('a failed final backup refresh rejects and rolls back instead of succeeding with a stale backup', async () => {
     const originalPublic = await KeyManager.createIdentity();
     const ss = (await import('expo-secure-store' as string)) as unknown as SecureStoreTestHandle;
-    const originalPriv = ss.__getStore__().get('oxy_identity_private_key');
+    const originalPriv = ss.__getRaw__(V2_PRIV, PRIMARY_SVC);
     resetCaches();
 
     // Let the new primary write and verify, then fail exactly once while
@@ -167,7 +152,8 @@ describe('KeyManager atomicity & recoverability under flaky storage', () => {
     // with primary=B and backup=A, enabling a later absent-primary restore to
     // silently switch back to A.
     ss.__failPlan__.failOp = 'set';
-    ss.__failPlan__.failKey = 'oxy_identity_backup_public_key';
+    ss.__failPlan__.failKey = V2_BPUB;
+    ss.__failPlan__.failService = BACKUP_SVC;
     ss.__failPlan__.failTimes = 1;
     await expect(KeyManager.createIdentity({ overwrite: true })).rejects.toBeDefined();
 
@@ -178,14 +164,12 @@ describe('KeyManager atomicity & recoverability under flaky storage', () => {
     // cross-account backup.
     expect(await KeyManager.hasIdentity()).toBe(true);
     expect(await KeyManager.getPublicKey()).toBe(originalPublic);
-    const m = ss.__getStore__();
-    expect(m.get('oxy_identity_private_key')).toBe(originalPriv);
-    expect(m.get('oxy_identity_public_key')).toBe(originalPublic);
-    expect(m.get('oxy_identity_backup_private_key')).toBe(originalPriv);
-    expect(m.get('oxy_identity_backup_public_key')).toBe(originalPublic);
+    expect(ss.__getRaw__(V2_PRIV, PRIMARY_SVC)).toBe(originalPriv);
+    expect(ss.__getRaw__(V2_PUB, PRIMARY_SVC)).toBe(originalPublic);
+    expect(ss.__getRaw__(V2_BPRIV, BACKUP_SVC)).toBe(originalPriv);
+    expect(ss.__getRaw__(V2_BPUB, BACKUP_SVC)).toBe(originalPublic);
   });
 
-
   it('restoreIdentityFromBackup does NOT clobber a healthy primary that is only transiently unreadable', async () => {
     const original = await KeyManager.createIdentity();
     const ss = (await import('expo-secure-store' as string)) as unknown as SecureStoreTestHandle;
@@ -193,13 +177,14 @@ describe('KeyManager atomicity & recoverability under flaky storage', () => {
     // Put a DIFFERENT identity in the backup slot (simulates a stale backup
     // from a previous account that a failed backup-refresh left behind).
     const other = await KeyManager.generateKeyPair();
-    ss.__getStore__().set('oxy_identity_backup_private_key', other.privateKey);
-    ss.__getStore__().set('oxy_identity_backup_public_key', other.publicKey);
+    ss.__setRaw__(V2_BPRIV, other.privateKey, BACKUP_SVC);
+    ss.__setRaw__(V2_BPUB, other.publicKey, BACKUP_SVC);
     resetCaches();
 
     // Make the primary PRIVATE read throw (transient keychain lock).
     ss.__failPlan__.failOp = 'get';
-    ss.__failPlan__.failKey = 'oxy_identity_private_key';
+    ss.__failPlan__.failKey = V2_PRIV;
+    ss.__failPlan__.failService = PRIMARY_SVC;
 
     const restored = await KeyManager.restoreIdentityFromBackup();
     expect(restored).toBe(false); // refused — transient read must not trigger a restore
@@ -207,9 +192,10 @@ describe('KeyManager atomicity & recoverability under flaky storage', () => {
     // Clear the fault; the original primary must be intact and unchanged.
     ss.__failPlan__.failKey = undefined;
     ss.__failPlan__.failOp = undefined;
+    ss.__failPlan__.failService = undefined;
     resetCaches();
     expect(await KeyManager.getPublicKey()).toBe(original);
-    expect(ss.__getStore__().get('oxy_identity_public_key')).toBe(original);
+    expect(ss.__getRaw__(V2_PUB, PRIMARY_SVC)).toBe(original);
   });
 
   it('restoreIdentityFromBackup refuses when a present primary private key identifies a different account than the backup', async () => {
@@ -218,23 +204,22 @@ describe('KeyManager atomicity & recoverability under flaky storage', () => {
     // real, different identity than the backup.
     const a = await KeyManager.createIdentity();
     const ss = (await import('expo-secure-store' as string)) as unknown as SecureStoreTestHandle;
-    const m = ss.__getStore__();
 
     // Backup holds a DIFFERENT identity B.
     const b = await KeyManager.generateKeyPair();
-    m.set('oxy_identity_backup_private_key', b.privateKey);
-    m.set('oxy_identity_backup_public_key', b.publicKey);
+    ss.__setRaw__(V2_BPRIV, b.privateKey, BACKUP_SVC);
+    ss.__setRaw__(V2_BPUB, b.publicKey, BACKUP_SVC);
     // Corrupt A's stored public key (private key A still present & valid).
-    m.set('oxy_identity_public_key', `04${'e'.repeat(128)}`);
+    ss.__setRaw__(V2_PUB, `04${'e'.repeat(128)}`, PRIMARY_SVC);
     resetCaches();
 
     const restored = await KeyManager.restoreIdentityFromBackup();
     expect(restored).toBe(false);
     // Must NOT have switched the primary to B.
-    expect(m.get('oxy_identity_public_key')).not.toBe(b.publicKey);
-    expect(m.get('oxy_identity_private_key')).not.toBe(b.privateKey);
+    expect(ss.__getRaw__(V2_PUB, PRIMARY_SVC)).not.toBe(b.publicKey);
+    expect(ss.__getRaw__(V2_PRIV, PRIMARY_SVC)).not.toBe(b.privateKey);
     // The original A private key is still in place (untouched).
-    expect(KeyManager.derivePublicKey(m.get('oxy_identity_private_key') as string)).toBe(a);
+    expect(KeyManager.derivePublicKey(ss.__getRaw__(V2_PRIV, PRIMARY_SVC) as string)).toBe(a);
   });
 
   it('a failed primary write during the post-rotation importKeyPair leaves the OLD key recoverable from backup', async () => {
@@ -244,7 +229,7 @@ describe('KeyManager atomicity & recoverability under flaky storage', () => {
     // half-written new identity that can't be decrypted or backed up.
     const oldPublic = await KeyManager.createIdentity();
     const ss = (await import('expo-secure-store' as string)) as unknown as SecureStoreTestHandle;
-    const oldPriv = ss.__getStore__().get('oxy_identity_private_key');
+    const oldPriv = ss.__getRaw__(V2_PRIV, PRIMARY_SVC);
     resetCaches();
 
     // The NEW rotated key material (generateKeyPair does NOT persist).
@@ -252,31 +237,31 @@ describe('KeyManager atomicity & recoverability under flaky storage', () => {
 
     // The new primary private write fails mid-commit.
     ss.__failPlan__.failOp = 'set';
-    ss.__failPlan__.failKey = 'oxy_identity_private_key';
+    ss.__failPlan__.failKey = V2_PRIV;
+    ss.__failPlan__.failService = PRIMARY_SVC;
     await expect(KeyManager.importKeyPair(rotated.privateKey, { overwrite: true })).rejects.toBeDefined();
 
     // Recover from the simulated fault.
     ss.__failPlan__.failKey = undefined;
     ss.__failPlan__.failOp = undefined;
+    ss.__failPlan__.failService = undefined;
     resetCaches();
 
     // Primary is STILL the old identity (rolled back — never the new one).
     expect(await KeyManager.hasIdentity()).toBe(true);
     expect(await KeyManager.getPublicKey()).toBe(oldPublic);
-    const m = ss.__getStore__();
-    expect(m.get('oxy_identity_private_key')).toBe(oldPriv);
+    expect(ss.__getRaw__(V2_PRIV, PRIMARY_SVC)).toBe(oldPriv);
     // And the backup still holds the OLD identity, so the user can recover it.
-    expect(m.get('oxy_identity_backup_private_key')).toBe(oldPriv);
-    expect(m.get('oxy_identity_backup_public_key')).toBe(oldPublic);
+    expect(ss.__getRaw__(V2_BPRIV, BACKUP_SVC)).toBe(oldPriv);
+    expect(ss.__getRaw__(V2_BPUB, BACKUP_SVC)).toBe(oldPublic);
   });
 
   it('restores a provably-absent primary from a valid backup', async () => {
     const original = await KeyManager.createIdentity();
     const ss = (await import('expo-secure-store' as string)) as unknown as SecureStoreTestHandle;
-    const m = ss.__getStore__();
     // Wipe the primary entirely (backup remains).
-    m.delete('oxy_identity_private_key');
-    m.delete('oxy_identity_public_key');
+    ss.__deleteRaw__(V2_PRIV, PRIMARY_SVC);
+    ss.__deleteRaw__(V2_PUB, PRIMARY_SVC);
     resetCaches();
 
     const restored = await KeyManager.restoreIdentityFromBackup();