@oxy.so/core 1.0.0

package/src/crypto/__tests__/cryptoPrimitives.test.ts

@@ -0,0 +1,226 @@
+/**
+ * b3 Phase 0 crypto primitives — HKDF-SHA256, XChaCha20-Poly1305 AEAD, and
+ * secp256k1 ECDH. These are the pure, self-contained foundation for the Commons
+ * encrypted-backup and device-to-device transfer flows.
+ *
+ * - kdf: pinned against the published RFC 5869 test vectors (TC1/TC2/TC3) so an
+ *   accidental algorithm/library swap is caught as a regression.
+ * - aead: round-trip plus exhaustive tamper coverage (flipped byte, wrong AAD,
+ *   wrong key, wrong nonce) — every mismatch must throw.
+ * - ecdh: symmetry (`derive(a,pubB) === derive(b,pubA)`), fixed 32-byte width,
+ *   and compressed/uncompressed public-key parity.
+ */
+
+import {
+  generateSecp256k1KeyPair,
+  normalizeSecp256k1PublicKey,
+} from '@oxy.so/protocol/secp256k1';
+import { hkdfSha256 } from '../kdf';
+import { encryptAead, decryptAead, AEAD_KEY_LENGTH, AEAD_NONCE_LENGTH } from '../aead';
+import { deriveSharedSecret } from '../ecdh';
+
+const fromHex = (hex: string): Uint8Array =>
+  Uint8Array.from(Buffer.from(hex.replace(/\s/g, ''), 'hex'));
+const toHex = (bytes: Uint8Array): string => Buffer.from(bytes).toString('hex');
+const range = (start: number, end: number): Uint8Array =>
+  Uint8Array.from(Array.from({ length: end - start + 1 }, (_, i) => start + i));
+
+describe('hkdfSha256 (RFC 5869)', () => {
+  // RFC 5869 Appendix A — Test Case 1 (basic, with salt & info).
+  it('matches RFC 5869 Test Case 1', () => {
+    const okm = hkdfSha256(
+      fromHex('0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b'),
+      fromHex('000102030405060708090a0b0c'),
+      fromHex('f0f1f2f3f4f5f6f7f8f9'),
+      42,
+    );
+    expect(toHex(okm)).toBe(
+      '3cb25f25faacd57a90434f64d0362f2a2d2d0a90cf1a5a4c5db02d56ecc4c5bf34007208d5b887185865',
+    );
+  });
+
+  // RFC 5869 Appendix A — Test Case 2 (longer inputs & output).
+  it('matches RFC 5869 Test Case 2', () => {
+    const okm = hkdfSha256(range(0x00, 0x4f), range(0x60, 0xaf), range(0xb0, 0xff), 82);
+    expect(toHex(okm)).toBe(
+      'b11e398dc80327a1c8e7f78c596a49344f012eda2d4efad8a050cc4c19afa97c59045a99cac7827271cb41c65e590e09da3275600c2f09b8367793a9aca3db71cc30c58179ec3e87c14c01d5c1f3434f1d87',
+    );
+  });
+
+  // RFC 5869 Appendix A — Test Case 3 (zero-length salt & info).
+  it('matches RFC 5869 Test Case 3 (empty salt/info)', () => {
+    const okm = hkdfSha256(
+      fromHex('0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b'),
+      new Uint8Array(0),
+      new Uint8Array(0),
+      42,
+    );
+    expect(toHex(okm)).toBe(
+      '8da4e775a563c18f715f802a063c5a31b8a11f5c5ee1879ec3454e5f3c738d2d9d201395faa4b61a96c8',
+    );
+  });
+
+  it('returns exactly the requested number of bytes', () => {
+    const ikm = fromHex('deadbeef');
+    expect(hkdfSha256(ikm, new Uint8Array(0), new Uint8Array(0), 16).length).toBe(16);
+    expect(hkdfSha256(ikm, new Uint8Array(0), new Uint8Array(0), 32).length).toBe(32);
+    expect(hkdfSha256(ikm, new Uint8Array(0), new Uint8Array(0), 64).length).toBe(64);
+  });
+
+  it('derives independent keys for distinct info (context binding)', () => {
+    const ikm = fromHex('00112233445566778899aabbccddeeff');
+    const salt = fromHex('a1b2c3d4');
+    const backup = hkdfSha256(ikm, salt, new TextEncoder().encode('oxy.backup.v1'), 32);
+    const transfer = hkdfSha256(ikm, salt, new TextEncoder().encode('oxy.transfer.v1'), 32);
+    expect(toHex(backup)).not.toBe(toHex(transfer));
+  });
+
+  it('rejects invalid output lengths', () => {
+    const ikm = fromHex('deadbeef');
+    expect(() => hkdfSha256(ikm, new Uint8Array(0), new Uint8Array(0), 0)).toThrow();
+    expect(() => hkdfSha256(ikm, new Uint8Array(0), new Uint8Array(0), -1)).toThrow();
+    expect(() => hkdfSha256(ikm, new Uint8Array(0), new Uint8Array(0), 1.5)).toThrow();
+    expect(() => hkdfSha256(ikm, new Uint8Array(0), new Uint8Array(0), 255 * 32 + 1)).toThrow();
+  });
+});
+
+describe('encryptAead / decryptAead (XChaCha20-Poly1305)', () => {
+  const key = hkdfSha256(fromHex('00'), new Uint8Array(0), new TextEncoder().encode('aead-test'), AEAD_KEY_LENGTH);
+  const plaintext = new TextEncoder().encode('the quick brown fox jumps over the lazy dog');
+  const aad = new TextEncoder().encode('oxy.backup.v1:did:web:oxy.so:u:123');
+
+  it('round-trips without AAD', () => {
+    const { nonce, ciphertext } = encryptAead(key, plaintext);
+    expect(nonce.length).toBe(AEAD_NONCE_LENGTH);
+    // Ciphertext = plaintext length + 16-byte Poly1305 tag.
+    expect(ciphertext.length).toBe(plaintext.length + 16);
+    expect(toHex(decryptAead(key, nonce, ciphertext))).toBe(toHex(plaintext));
+  });
+
+  it('round-trips with AAD', () => {
+    const { nonce, ciphertext } = encryptAead(key, plaintext, aad);
+    expect(toHex(decryptAead(key, nonce, ciphertext, aad))).toBe(toHex(plaintext));
+  });
+
+  it('produces a distinct random nonce on each call', () => {
+    const a = encryptAead(key, plaintext);
+    const b = encryptAead(key, plaintext);
+    expect(toHex(a.nonce)).not.toBe(toHex(b.nonce));
+    // Random nonce => distinct ciphertext even for identical plaintext+key.
+    expect(toHex(a.ciphertext)).not.toBe(toHex(b.ciphertext));
+  });
+
+  it('throws when a ciphertext byte is flipped (tamper detection)', () => {
+    const { nonce, ciphertext } = encryptAead(key, plaintext, aad);
+    const tampered = Uint8Array.from(ciphertext);
+    tampered[0] ^= 0x01;
+    expect(() => decryptAead(key, nonce, tampered, aad)).toThrow();
+  });
+
+  it('throws when the authentication tag is flipped (tamper detection)', () => {
+    const { nonce, ciphertext } = encryptAead(key, plaintext, aad);
+    const tampered = Uint8Array.from(ciphertext);
+    tampered[tampered.length - 1] ^= 0x80;
+    expect(() => decryptAead(key, nonce, tampered, aad)).toThrow();
+  });
+
+  it('throws when AAD does not match', () => {
+    const { nonce, ciphertext } = encryptAead(key, plaintext, aad);
+    const wrongAad = new TextEncoder().encode('oxy.backup.v1:did:web:oxy.so:u:999');
+    expect(() => decryptAead(key, nonce, ciphertext, wrongAad)).toThrow();
+    // AAD present at encrypt, absent at decrypt must also fail.
+    expect(() => decryptAead(key, nonce, ciphertext)).toThrow();
+  });
+
+  it('throws when the key does not match', () => {
+    const { nonce, ciphertext } = encryptAead(key, plaintext, aad);
+    const wrongKey = hkdfSha256(fromHex('01'), new Uint8Array(0), new TextEncoder().encode('aead-test'), AEAD_KEY_LENGTH);
+    expect(() => decryptAead(wrongKey, nonce, ciphertext, aad)).toThrow();
+  });
+
+  it('throws when the nonce does not match', () => {
+    const { nonce, ciphertext } = encryptAead(key, plaintext, aad);
+    const wrongNonce = Uint8Array.from(nonce);
+    wrongNonce[0] ^= 0x01;
+    expect(() => decryptAead(key, wrongNonce, ciphertext, aad)).toThrow();
+  });
+
+  it('rejects keys of the wrong length', () => {
+    expect(() => encryptAead(new Uint8Array(16), plaintext)).toThrow();
+    const { nonce, ciphertext } = encryptAead(key, plaintext);
+    expect(() => decryptAead(new Uint8Array(31), nonce, ciphertext)).toThrow();
+  });
+
+  it('rejects a nonce of the wrong length on decrypt', () => {
+    const { ciphertext } = encryptAead(key, plaintext);
+    expect(() => decryptAead(key, new Uint8Array(12), ciphertext)).toThrow();
+  });
+
+  it('handles empty plaintext', () => {
+    const empty = new Uint8Array(0);
+    const { nonce, ciphertext } = encryptAead(key, empty, aad);
+    expect(ciphertext.length).toBe(16); // tag only
+    expect(decryptAead(key, nonce, ciphertext, aad).length).toBe(0);
+  });
+});
+
+describe('deriveSharedSecret (secp256k1 ECDH)', () => {
+  const alice = generateSecp256k1KeyPair();
+  const bob = generateSecp256k1KeyPair();
+  const alicePriv = alice.privateKey;
+  const bobPriv = bob.privateKey;
+  const alicePubUncompressed = alice.publicKey;
+  const bobPubUncompressed = bob.publicKey;
+
+  it('is symmetric: derive(a, pubB) === derive(b, pubA)', () => {
+    const ab = deriveSharedSecret(alicePriv, bobPubUncompressed);
+    const ba = deriveSharedSecret(bobPriv, alicePubUncompressed);
+    expect(toHex(ab)).toBe(toHex(ba));
+  });
+
+  it('returns exactly 32 bytes', () => {
+    expect(deriveSharedSecret(alicePriv, bobPubUncompressed).length).toBe(32);
+  });
+
+  it('agrees for compressed and uncompressed public-key encodings', () => {
+    const bobPubCompressed = normalizeSecp256k1PublicKey(bob.publicKey, true);
+    const fromUncompressed = deriveSharedSecret(alicePriv, bobPubUncompressed);
+    const fromCompressed = deriveSharedSecret(alicePriv, bobPubCompressed);
+    expect(toHex(fromCompressed)).toBe(toHex(fromUncompressed));
+  });
+
+  it('yields different secrets for different counterparties', () => {
+    const carol = generateSecp256k1KeyPair();
+    const withBob = deriveSharedSecret(alicePriv, bobPubUncompressed);
+    const withCarol = deriveSharedSecret(alicePriv, carol.publicKey);
+    expect(toHex(withBob)).not.toBe(toHex(withCarol));
+  });
+
+  it('is stable across repeated derivations', () => {
+    const first = deriveSharedSecret(alicePriv, bobPubUncompressed);
+    const second = deriveSharedSecret(alicePriv, bobPubUncompressed);
+    expect(toHex(first)).toBe(toHex(second));
+  });
+
+  it('composes with HKDF to yield a usable AEAD key round-trip', () => {
+    const shared = deriveSharedSecret(alicePriv, bobPubUncompressed);
+    const info = new TextEncoder().encode('oxy.transfer.v1');
+    const aliceKey = hkdfSha256(shared, new Uint8Array(0), info, AEAD_KEY_LENGTH);
+    const bobKey = hkdfSha256(
+      deriveSharedSecret(bobPriv, alicePubUncompressed),
+      new Uint8Array(0),
+      info,
+      AEAD_KEY_LENGTH,
+    );
+    expect(toHex(aliceKey)).toBe(toHex(bobKey));
+
+    const message = new TextEncoder().encode('device transfer payload');
+    const { nonce, ciphertext } = encryptAead(aliceKey, message);
+    expect(toHex(decryptAead(bobKey, nonce, ciphertext))).toBe(toHex(message));
+  });
+
+  it('rejects non-hex inputs', () => {
+    expect(() => deriveSharedSecret('zzzz', bobPubUncompressed)).toThrow();
+    expect(() => deriveSharedSecret(alicePriv, 'nothex')).toThrow();
+  });
+});

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

@@ -0,0 +1,272 @@
+/**
+ * Tests for KeyManager atomic-write & backup-restore safety under FLAKY storage.
+ *
+ * These pin the "never leave the device with zero recoverable copies of a
+ * healthy identity" invariant. Each scenario corresponds to a real
+ * account-loss / account-switch bug that a half-failed SecureStore write could
+ * otherwise cause:
+ *
+ *   1. A failed OVERWRITE must roll the primary back to the ORIGINAL identity
+ *      and must keep a recoverable backup of it — never switch to the
+ *      half-written new identity.
+ *   2. A transient read failure must not cause restoreIdentityFromBackup() to
+ *      clobber a healthy-but-momentarily-locked primary with a stale backup.
+ *   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';
+
+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('@oxy.so/protocol', () => {
+  const actual = jest.requireActual('@oxy.so/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),
+  };
+});
+
+// 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;
+  __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;
+      cachedPublicKeyResolved: unknown;
+    };
+    km.cachedPublicKey = null;
+    km.cachedHasIdentity = null;
+    km.cachedPublicKeyResolved = false;
+  };
+
+  beforeAll(() => {
+    setPlatformOS('ios');
+    (globalThis as unknown as { navigator: unknown }).navigator = { product: 'ReactNative' };
+  });
+
+  beforeEach(async () => {
+    jest.resetModules();
+    setPlatformOS('ios');
+    const ss = (await import('expo-secure-store' as string)) as unknown as SecureStoreTestHandle;
+    ss.__resetStore__();
+    const km = await import('../keyManager');
+    KeyManager = km.KeyManager;
+    resetCaches();
+  });
+
+  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.__getRaw__(V2_PRIV, PRIMARY_SVC);
+    resetCaches();
+
+    // The new primary private write fails mid-overwrite.
+    ss.__failPlan__.failOp = 'set';
+    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.__getRaw__(V2_PRIV, PRIMARY_SVC)).toBe(originalPriv);
+
+    // And the backup must still hold the ORIGINAL identity, never the new one.
+    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.__getRaw__(V2_PRIV, PRIMARY_SVC);
+    resetCaches();
+
+    // Let the new primary write and verify, then fail exactly once while
+    // refreshing the backup to the new identity. This used to return success
+    // 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 = V2_BPUB;
+    ss.__failPlan__.failService = BACKUP_SVC;
+    ss.__failPlan__.failTimes = 1;
+    await expect(KeyManager.createIdentity({ overwrite: true })).rejects.toBeDefined();
+
+    resetCaches();
+
+    // The operation failed atomically: primary and backup both still identify
+    // the original account, so callers cannot observe success with a stale
+    // cross-account backup.
+    expect(await KeyManager.hasIdentity()).toBe(true);
+    expect(await KeyManager.getPublicKey()).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;
+
+    // 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.__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 = V2_PRIV;
+    ss.__failPlan__.failService = PRIMARY_SVC;
+
+    const restored = await KeyManager.restoreIdentityFromBackup();
+    expect(restored).toBe(false); // refused — transient read must not trigger a restore
+
+    // 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.__getRaw__(V2_PUB, PRIMARY_SVC)).toBe(original);
+  });
+
+  it('restoreIdentityFromBackup refuses when a present primary private key identifies a different account than the backup', async () => {
+    // Primary holds identity A (valid). Corrupt ONLY the public key so the
+    // primary fails its consistency check but the private key still derives a
+    // real, different identity than the backup.
+    const a = await KeyManager.createIdentity();
+    const ss = (await import('expo-secure-store' as string)) as unknown as SecureStoreTestHandle;
+
+    // Backup holds a DIFFERENT identity B.
+    const b = await KeyManager.generateKeyPair();
+    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).
+    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(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(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 () => {
+    // b3 key rotation: the server has already swapped to the NEW key; the device
+    // now commits it via importKeyPair({overwrite:true}). If that write fails
+    // mid-overwrite, the OLD key MUST remain intact and recoverable — never a
+    // 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.__getRaw__(V2_PRIV, PRIMARY_SVC);
+    resetCaches();
+
+    // The NEW rotated key material (generateKeyPair does NOT persist).
+    const rotated = await KeyManager.generateKeyPair();
+
+    // The new primary private write fails mid-commit.
+    ss.__failPlan__.failOp = 'set';
+    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);
+    expect(ss.__getRaw__(V2_PRIV, PRIMARY_SVC)).toBe(oldPriv);
+    // And the backup still holds the OLD identity, so the user can recover it.
+    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;
+    // Wipe the primary entirely (backup remains).
+    ss.__deleteRaw__(V2_PRIV, PRIMARY_SVC);
+    ss.__deleteRaw__(V2_PUB, PRIMARY_SVC);
+    resetCaches();
+
+    const restored = await KeyManager.restoreIdentityFromBackup();
+    expect(restored).toBe(true);
+    expect(await KeyManager.getPublicKey()).toBe(original);
+    expect(await KeyManager.verifyIdentityIntegrity()).toBe(true);
+  });
+});