@oxyhq/core 12.2.0 → 12.3.0

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

@@ -0,0 +1,86 @@
+/**
+ * RecoveryPhraseService.deriveBackupMaterial — encrypted off-device backup key
+ * schedule (b3 Feature 1).
+ *
+ * The two outputs are derived from the FULL 64-byte BIP-39 seed via HKDF-SHA256
+ * with domain-separated `info` labels. These tests PIN the derivation against a
+ * fixed phrase so an accidental algorithm/library/label swap is caught as a
+ * regression, and assert the domain separation is real (backup key ≠ lookup id ≠
+ * the raw private key, all from the same seed).
+ *
+ * The fixed phrase is the canonical BIP-39 all-zero-entropy vector
+ * ("abandon…about"), whose seed is the published `5eb00bbd…ce9e38e4` — so the
+ * pinned outputs below are reproducible from any independent HKDF-SHA256
+ * implementation over that seed.
+ */
+import { RecoveryPhraseService } from '../recoveryPhrase';
+import { KeyManager } from '../keyManager';
+
+const FIXED_PHRASE =
+  'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
+
+// Pinned outputs (independently reproducible — see file header).
+const EXPECTED_BACKUP_KEY_HEX = 'c6bb29585610550e2667a9d05f35d081f67dd8ccee20a04488c39b25f47a9e74';
+const EXPECTED_LOOKUP_ID = '8cad137ca961bfc62a2ef329869e8369777737c7c5353a8d94bb70d888c0ad0d';
+// The raw private key = seed[0:32] (the FROZEN phrase→privateKey derivation).
+const EXPECTED_PRIVATE_KEY = '5eb00bbddcf069084889a8ab9155568165f5c453ccb85e70811aaed6f6da5fc1';
+
+const toHex = (bytes: Uint8Array): string => Buffer.from(bytes).toString('hex');
+
+describe('RecoveryPhraseService.deriveBackupMaterial (KDF vectors)', () => {
+  it('derives the pinned backupKey + lookupId for the fixed phrase', async () => {
+    const { backupKey, lookupId } = await RecoveryPhraseService.deriveBackupMaterial(FIXED_PHRASE);
+
+    expect(backupKey).toBeInstanceOf(Uint8Array);
+    expect(backupKey).toHaveLength(32);
+    expect(toHex(backupKey)).toBe(EXPECTED_BACKUP_KEY_HEX);
+
+    expect(lookupId).toBe(EXPECTED_LOOKUP_ID);
+    expect(lookupId).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it('is deterministic (same phrase → identical material)', async () => {
+    const a = await RecoveryPhraseService.deriveBackupMaterial(FIXED_PHRASE);
+    const b = await RecoveryPhraseService.deriveBackupMaterial(FIXED_PHRASE);
+    expect(toHex(a.backupKey)).toBe(toHex(b.backupKey));
+    expect(a.lookupId).toBe(b.lookupId);
+  });
+
+  it('normalizes case/whitespace like the other phrase helpers', async () => {
+    const messy = `  ${FIXED_PHRASE.toUpperCase()}  `;
+    const { backupKey, lookupId } = await RecoveryPhraseService.deriveBackupMaterial(messy);
+    expect(toHex(backupKey)).toBe(EXPECTED_BACKUP_KEY_HEX);
+    expect(lookupId).toBe(EXPECTED_LOOKUP_ID);
+  });
+
+  it('enforces real domain separation (backupKey ≠ lookupId ≠ raw private key)', async () => {
+    const { backupKey, lookupId } = await RecoveryPhraseService.deriveBackupMaterial(FIXED_PHRASE);
+    const privateKey = await RecoveryPhraseService.derivePrivateKeyFromPhrase(FIXED_PHRASE);
+
+    // Sanity: the frozen phrase→privateKey path is unchanged.
+    expect(privateKey).toBe(EXPECTED_PRIVATE_KEY);
+
+    // The three derivations from the SAME seed are mutually distinct — a device
+    // compromise leaking only the 32-byte private key reveals nothing about the
+    // backup key or lookup id (both need the full 64-byte seed).
+    expect(toHex(backupKey)).not.toBe(lookupId);
+    expect(toHex(backupKey)).not.toBe(privateKey);
+    expect(lookupId).not.toBe(privateKey);
+  });
+
+  it('produces a valid signing key material that is NOT the backup key', async () => {
+    // Extra guard: the backupKey must never coincide with a usable identity key
+    // for this phrase.
+    const { backupKey } = await RecoveryPhraseService.deriveBackupMaterial(FIXED_PHRASE);
+    const privateKey = await RecoveryPhraseService.derivePrivateKeyFromPhrase(FIXED_PHRASE);
+    const publicKey = KeyManager.derivePublicKey(privateKey);
+    expect(publicKey).toMatch(/^04[0-9a-f]+$/);
+    expect(toHex(backupKey)).not.toBe(privateKey);
+  });
+
+  it('rejects an invalid recovery phrase', async () => {
+    await expect(RecoveryPhraseService.deriveBackupMaterial('not a real phrase')).rejects.toThrow(
+      /Invalid recovery phrase/,
+    );
+  });
+});

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

@@ -0,0 +1,225 @@
+/**
+ * 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 { ec as EC } from 'elliptic';
+import { hkdfSha256 } from '../kdf';
+import { encryptAead, decryptAead, AEAD_KEY_LENGTH, AEAD_NONCE_LENGTH } from '../aead';
+import { deriveSharedSecret } from '../ecdh';
+
+const ec = new EC('secp256k1');
+
+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 = ec.genKeyPair();
+  const bob = ec.genKeyPair();
+  const alicePriv = alice.getPrivate('hex');
+  const bobPriv = bob.getPrivate('hex');
+  const alicePubUncompressed = alice.getPublic('hex');
+  const bobPubUncompressed = bob.getPublic('hex');
+
+  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 = bob.getPublic(true, 'hex');
+    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 = ec.genKeyPair();
+    const withBob = deriveSharedSecret(alicePriv, bobPubUncompressed);
+    const withCarol = deriveSharedSecret(alicePriv, carol.getPublic('hex'));
+    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__/keyManager.atomicity.test.ts

@@ -237,6 +237,39 @@ describe('KeyManager atomicity & recoverability under flaky storage', () => {
     expect(KeyManager.derivePublicKey(m.get('oxy_identity_private_key') 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.__getStore__().get('oxy_identity_private_key');
+    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 = 'oxy_identity_private_key';
+    await expect(KeyManager.importKeyPair(rotated.privateKey, { overwrite: true })).rejects.toBeDefined();
+
+    // Recover from the simulated fault.
+    ss.__failPlan__.failKey = undefined;
+    ss.__failPlan__.failOp = 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);
+    // 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);
+  });
+
   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;

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

@@ -0,0 +1,61 @@
+/**
+ * RecoveryPhraseService — pure, non-persisting derivation helpers (b3 rotation).
+ *
+ * `derivePendingIdentity()` and `derivePrivateKeyFromPhrase()` must produce
+ * valid, self-consistent key material WITHOUT touching secure storage — the
+ * whole point of a "pending" identity is that nothing is committed until an
+ * external step (a server-confirmed key rotation) succeeds.
+ */
+
+import { RecoveryPhraseService } from '../recoveryPhrase';
+import { KeyManager } from '../keyManager';
+
+describe('RecoveryPhraseService.derivePendingIdentity (non-persisting)', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('produces a valid 12-word phrase whose privateKey derives the returned publicKey', async () => {
+    const pending = await RecoveryPhraseService.derivePendingIdentity();
+
+    expect(RecoveryPhraseService.validatePhrase(pending.phrase)).toBe(true);
+    expect(pending.words).toHaveLength(12);
+    expect(pending.words.join(' ')).toBe(pending.phrase);
+
+    // The private key is a canonical 64-hex-char secp256k1 scalar…
+    expect(pending.privateKey).toMatch(/^[0-9a-f]{64}$/);
+    // …and it deterministically derives the returned public key.
+    expect(KeyManager.derivePublicKey(pending.privateKey)).toBe(pending.publicKey);
+  });
+
+  it('does NOT persist anything to secure storage (never imports a key pair)', async () => {
+    const importSpy = jest.spyOn(KeyManager, 'importKeyPair');
+    const createSpy = jest.spyOn(KeyManager, 'createIdentity');
+
+    await RecoveryPhraseService.derivePendingIdentity();
+
+    expect(importSpy).not.toHaveBeenCalled();
+    expect(createSpy).not.toHaveBeenCalled();
+  });
+
+  it('yields a distinct identity on each call', async () => {
+    const a = await RecoveryPhraseService.derivePendingIdentity();
+    const b = await RecoveryPhraseService.derivePendingIdentity();
+    expect(a.phrase).not.toBe(b.phrase);
+    expect(a.publicKey).not.toBe(b.publicKey);
+  });
+
+  it('derivePrivateKeyFromPhrase round-trips: same phrase → same private/public key', async () => {
+    const pending = await RecoveryPhraseService.derivePendingIdentity();
+
+    const rederivedPrivate = await RecoveryPhraseService.derivePrivateKeyFromPhrase(pending.phrase);
+    expect(rederivedPrivate).toBe(pending.privateKey);
+    expect(KeyManager.derivePublicKey(rederivedPrivate)).toBe(pending.publicKey);
+  });
+
+  it('derivePrivateKeyFromPhrase rejects an invalid mnemonic', async () => {
+    await expect(
+      RecoveryPhraseService.derivePrivateKeyFromPhrase('not a real recovery phrase at all'),
+    ).rejects.toThrow(/Invalid recovery phrase/);
+  });
+});

package/src/crypto/aead.ts

@@ -0,0 +1,97 @@
+/**
+ * Authenticated Encryption with Associated Data (XChaCha20-Poly1305)
+ *
+ * Pure-JS/TS AEAD via `@noble/ciphers` — identical behaviour on web, Node, and
+ * React Native with zero WebCrypto / native-module dependency. This replaces
+ * the `crypto.subtle`-based path (unreliable on React Native) for the Commons
+ * encrypted backup and device-to-device transfer flows.
+ *
+ * XChaCha20-Poly1305 is chosen over AES-GCM specifically for its 24-byte
+ * (192-bit) random nonce: the nonce space is large enough that random nonces
+ * never collide in practice, so callers do not need to maintain a per-key
+ * counter. The 16-byte Poly1305 tag is appended to the ciphertext by the
+ * underlying library and validated on decrypt.
+ *
+ * The optional Associated Data (AAD) is authenticated but NOT encrypted: it
+ * binds the ciphertext to its context (e.g. a backup version, a device id, a
+ * DID). Decryption fails if the key, nonce, ciphertext, OR aad differ from
+ * those used at encryption time.
+ *
+ * ESM/CJS safe: static `import` only, no `require()`.
+ */
+
+// Loading the polyfill guarantees `globalThis.crypto.getRandomValues` exists on
+// every platform (native crypto on web/Node; expo-crypto-backed shim on RN).
+import './polyfill';
+import { xchacha20poly1305 } from '@noble/ciphers/chacha';
+
+/** Key length for XChaCha20-Poly1305, in bytes (256-bit). */
+export const AEAD_KEY_LENGTH = 32;
+/** Nonce length for XChaCha20-Poly1305, in bytes (192-bit). */
+export const AEAD_NONCE_LENGTH = 24;
+
+/** Ciphertext (Poly1305 tag appended) plus the random nonce used to produce it. */
+export interface AeadResult {
+  /** The 24-byte random nonce. Store/transmit alongside the ciphertext. */
+  nonce: Uint8Array;
+  /** Ciphertext with the 16-byte Poly1305 authentication tag appended. */
+  ciphertext: Uint8Array;
+}
+
+function assertKey(key: Uint8Array): void {
+  if (key.length !== AEAD_KEY_LENGTH) {
+    throw new Error(`AEAD key must be ${AEAD_KEY_LENGTH} bytes, got ${key.length}`);
+  }
+}
+
+/** Generate a fresh 24-byte random nonce via the platform CSPRNG. */
+function randomNonce(): Uint8Array {
+  const nonce = new Uint8Array(AEAD_NONCE_LENGTH);
+  globalThis.crypto.getRandomValues(nonce);
+  return nonce;
+}
+
+/**
+ * Encrypt `plaintext` under `key` with a fresh random nonce, authenticating the
+ * optional `aad`.
+ *
+ * @param key       32-byte symmetric key (e.g. from `hkdfSha256`).
+ * @param plaintext Bytes to encrypt.
+ * @param aad       Optional associated data authenticated but not encrypted.
+ * @returns         `{ nonce, ciphertext }` — both are required to decrypt.
+ */
+export function encryptAead(
+  key: Uint8Array,
+  plaintext: Uint8Array,
+  aad?: Uint8Array,
+): AeadResult {
+  assertKey(key);
+  const nonce = randomNonce();
+  const ciphertext = xchacha20poly1305(key, nonce, aad).encrypt(plaintext);
+  return { nonce, ciphertext };
+}
+
+/**
+ * Decrypt and authenticate `ciphertext` produced by {@link encryptAead}.
+ *
+ * Throws if the key, nonce, ciphertext, or aad differ from those used at
+ * encryption time (tamper detection), or if the tag is invalid.
+ *
+ * @param key        32-byte symmetric key.
+ * @param nonce      The 24-byte nonce returned by `encryptAead`.
+ * @param ciphertext Ciphertext with the appended Poly1305 tag.
+ * @param aad        The same associated data supplied at encryption time.
+ * @returns          The recovered plaintext bytes.
+ */
+export function decryptAead(
+  key: Uint8Array,
+  nonce: Uint8Array,
+  ciphertext: Uint8Array,
+  aad?: Uint8Array,
+): Uint8Array {
+  assertKey(key);
+  if (nonce.length !== AEAD_NONCE_LENGTH) {
+    throw new Error(`AEAD nonce must be ${AEAD_NONCE_LENGTH} bytes, got ${nonce.length}`);
+  }
+  return xchacha20poly1305(key, nonce, aad).decrypt(ciphertext);
+}

package/src/crypto/ecdh.ts

@@ -0,0 +1,60 @@
+/**
+ * ECDH shared-secret derivation (secp256k1)
+ *
+ * Derives a raw 32-byte ECDH shared secret from a local private key and a
+ * remote public key, using the SAME `elliptic` `EC('secp256k1')` primitive the
+ * rest of core's identity layer uses (`keyManager.ts`). This is the key-exchange
+ * step for the Commons device-to-device transfer flow: each side computes the
+ * same shared secret, which is then run through `hkdfSha256` to derive the
+ * symmetric key handed to `encryptAead` / `decryptAead`.
+ *
+ * The returned value is the raw x-coordinate of the ECDH point, big-endian,
+ * zero-padded to 32 bytes. It is NOT itself a symmetric key — always pass it
+ * through a KDF (HKDF) with a context-binding `info` before use.
+ *
+ * ESM/CJS safe: static `import` only, no `require()`.
+ */
+
+import { ec as EC } from 'elliptic';
+
+const ec = new EC('secp256k1');
+
+/** Lowercase and left-pad a private-key hex string to canonical 64-char form. */
+function canonicalPrivateKey(key: string): string {
+  return key.toLowerCase().padStart(64, '0');
+}
+
+const HEX_RE = /^[0-9a-fA-F]+$/;
+
+/**
+ * Compute the ECDH shared secret between a local private key and a remote
+ * public key on secp256k1.
+ *
+ * Symmetric by construction:
+ * `deriveSharedSecret(privA, pubB) === deriveSharedSecret(privB, pubA)`.
+ *
+ * @param privateKeyHex     Local private key, hex (up to 64 chars; canonicalized).
+ * @param otherPublicKeyHex Remote public key, hex — compressed (`02`/`03` + 32
+ *                          bytes) or uncompressed (`04` + 64 bytes).
+ * @returns                 The 32-byte big-endian shared secret.
+ */
+export function deriveSharedSecret(
+  privateKeyHex: string,
+  otherPublicKeyHex: string,
+): Uint8Array {
+  if (typeof privateKeyHex !== 'string' || !HEX_RE.test(privateKeyHex)) {
+    throw new Error('deriveSharedSecret: privateKeyHex must be a hex string');
+  }
+  if (typeof otherPublicKeyHex !== 'string' || !HEX_RE.test(otherPublicKeyHex)) {
+    throw new Error('deriveSharedSecret: otherPublicKeyHex must be a hex string');
+  }
+
+  const keyPair = ec.keyFromPrivate(canonicalPrivateKey(privateKeyHex));
+  const otherKey = ec.keyFromPublic(otherPublicKeyHex, 'hex');
+
+  // `derive` returns a BN (the shared point's x-coordinate). Serialize it
+  // big-endian, fixed 32 bytes, so both sides agree byte-for-byte regardless of
+  // any leading-zero stripping.
+  const sharedBytes = keyPair.derive(otherKey.getPublic()).toArray('be', 32);
+  return Uint8Array.from(sharedBytes);
+}

package/src/crypto/kdf.ts

@@ -0,0 +1,43 @@
+/**
+ * Key Derivation Function (HKDF-SHA256)
+ *
+ * Pure-JS/TS HKDF via `@noble/hashes` — identical behaviour on web, Node, and
+ * React Native with zero WebCrypto / native-module dependency. Used to derive
+ * fixed-length symmetric keys from higher-entropy input keying material (an
+ * ECDH shared secret, a recovery-phrase seed, etc.) for the Commons encrypted
+ * backup and device-to-device transfer flows.
+ *
+ * ESM/CJS safe: static `import` only, no `require()`.
+ */
+
+import { hkdf } from '@noble/hashes/hkdf';
+import { sha256 } from '@noble/hashes/sha256';
+
+/**
+ * Derive `length` bytes of keying material from `ikm` using HKDF-SHA256
+ * (RFC 5869 — extract-then-expand).
+ *
+ * @param ikm    Input keying material (the raw secret; NOT necessarily uniform).
+ * @param salt   Non-secret random salt. An empty array is treated by HKDF as a
+ *               zero-filled salt of the hash length — pass a real salt whenever
+ *               one is available so derivations for different contexts diverge.
+ * @param info   Context/application-binding string ("what is this key for").
+ *               Distinct `info` values yield independent keys from the same ikm.
+ * @param length Number of output bytes. Must be in (0, 255 * 32].
+ * @returns      Exactly `length` bytes of derived keying material.
+ */
+export function hkdfSha256(
+  ikm: Uint8Array,
+  salt: Uint8Array,
+  info: Uint8Array,
+  length: number,
+): Uint8Array {
+  if (!Number.isInteger(length) || length <= 0) {
+    throw new Error('hkdfSha256: length must be a positive integer');
+  }
+  // HKDF-Expand is defined for at most 255 * HashLen bytes of output.
+  if (length > 255 * 32) {
+    throw new Error('hkdfSha256: length must not exceed 8160 bytes (255 * 32)');
+  }
+  return hkdf(sha256, ikm, salt, info, length);
+}

package/src/crypto/keyManager.ts

@@ -1464,6 +1464,14 @@ export class KeyManager {
     return keyPair.getPublic('hex');
   }
 
+  /**
+   * Normalize a public key to uncompressed, lowercased hex. Used when building
+   * signed rotation payloads so legacy compressed/cased encodings still verify.
+   */
+  static canonicalPublicKey(publicKey: string): string {
+    return ec.keyFromPublic(publicKey, 'hex').getPublic(false, 'hex').toLowerCase();
+  }
+
   /**
    * Validate that a string is a valid public key
    *