@oxy.so/core 1.18.0 → 3.0.0

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

@@ -1,226 +0,0 @@
-/**
- * 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__/identityLink.test.ts

@@ -1,18 +0,0 @@
-import { deriveIdentityLinkCode } from '../identityLink';
-
-const LINK_ID = 'ab'.repeat(16);
-const KEY = `04${'1f'.repeat(64)}`;
-
-describe('deriveIdentityLinkCode', () => {
-  it('is 6 digits, the same on both devices whatever the key spelling', () => {
-    const code = deriveIdentityLinkCode(LINK_ID, KEY);
-    expect(code).toMatch(/^\d{6}$/);
-    expect(deriveIdentityLinkCode(LINK_ID, ` ${KEY.toUpperCase()} `)).toBe(code);
-  });
-
-  it('changes with the key and with the request', () => {
-    const code = deriveIdentityLinkCode(LINK_ID, KEY);
-    expect(deriveIdentityLinkCode(LINK_ID, `04${'2e'.repeat(64)}`)).not.toBe(code);
-    expect(deriveIdentityLinkCode('cd'.repeat(16), KEY)).not.toBe(code);
-  });
-});

package/src/crypto/__tests__/identityMocks.ts

@@ -1,125 +0,0 @@
-/**
- * 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__/identityProof.test.ts

@@ -1,81 +0,0 @@
-/**
- * The one identity-proof format (ADR 0024 D7): the signed bytes name every
- * claim, so a signature for one operation verifies for nothing else.
- */
-
-import { buildIdentityProofMessage, canonicalJson, type IdentityProofClaims } from '@oxy.so/contracts';
-import { verifySignature } from '@oxy.so/protocol';
-import { digestIdentityPayload, signIdentityProof } from '../identityProof';
-import { deriveSecp256k1PublicKey } from '@oxy.so/protocol/secp256k1';
-
-const keyPair = (privateKey: string) => ({ privateKey, publicKey: deriveSecp256k1PublicKey(privateKey) });
-const identity = keyPair('11'.repeat(32));
-
-const claims = (overrides: Partial<IdentityProofClaims> = {}): IdentityProofClaims => ({
-  action: 'link_identity',
-  subject: 'user-1',
-  actor: 'user-1',
-  rootPublicKey: identity.publicKey,
-  payloadDigest: digestIdentityPayload({ b: 1, a: [1, 'x'] }),
-  expectedRevision: 3,
-  audience: 'oxy-api/identity',
-  challenge: 'ab'.repeat(32),
-  expiresAt: 1_800_000_000_000,
-  ...overrides,
-});
-
-describe('canonical JSON', () => {
-  it('sorts keys at every depth and drops undefined members', () => {
-    expect(canonicalJson({ b: 1, a: { d: [3, { z: 1, y: 2 }], c: undefined } })).toBe('{"a":{"d":[3,{"y":2,"z":1}]},"b":1}');
-  });
-
-  it('digests the same payload identically whatever its key order', () => {
-    expect(digestIdentityPayload({ a: 1, b: 2 })).toBe(digestIdentityPayload({ b: 2, a: 1 }));
-    expect(digestIdentityPayload({ a: 1, b: 2 })).toMatch(/^[0-9a-f]{64}$/);
-  });
-
-  it('refuses values JSON cannot represent exactly', () => {
-    expect(() => canonicalJson({ a: Number.NaN })).toThrow('non-finite');
-    expect(() => canonicalJson({ a: () => 1 })).toThrow('unsupported');
-  });
-});
-
-describe('the signed bytes', () => {
-  it('are a fixed, versioned, domain-separated shape', () => {
-    expect(buildIdentityProofMessage(claims())).toBe(
-      `{"action":"link_identity","actor":"user-1","audience":"oxy-api/identity","challenge":"${'ab'.repeat(32)}","domain":"oxy-identity-proof","expectedRevision":3,"expiresAt":1800000000000,"payloadDigest":"${claims().payloadDigest}","rootPublicKey":"${identity.publicKey}","subject":"user-1","v":2}`,
-    );
-  });
-
-  it('refuse malformed claims instead of signing something ambiguous', () => {
-    expect(() => buildIdentityProofMessage(claims({ action: 'anything' as never }))).toThrow('unknown action');
-    expect(() => buildIdentityProofMessage(claims({ payloadDigest: 'AB'.repeat(32) }))).toThrow('payloadDigest');
-    expect(() => buildIdentityProofMessage(claims({ challenge: 'short' }))).toThrow('challenge');
-    expect(() => buildIdentityProofMessage(claims({ rootPublicKey: identity.publicKey.toUpperCase() }))).toThrow('rootPublicKey');
-  });
-});
-
-describe('signing', () => {
-  it('verifies for exactly the claims it was made for', async () => {
-    const proof = await signIdentityProof(identity, claims());
-    expect(proof).toMatchObject({ v: 2, challenge: 'ab'.repeat(32), expiresAt: 1_800_000_000_000 });
-
-    expect(await verifySignature(buildIdentityProofMessage(claims()), proof.signature, identity.publicKey)).toBe(true);
-    for (const changed of [
-      claims({ subject: 'user-2' }),
-      claims({ actor: 'user-2' }),
-      claims({ payloadDigest: digestIdentityPayload({ b: 2 }) }),
-      claims({ expectedRevision: 4 }),
-      claims({ audience: 'somewhere-else' }),
-      claims({ challenge: 'cd'.repeat(32) }),
-      claims({ expiresAt: 1_800_000_000_001 }),
-    ]) {
-      expect(await verifySignature(buildIdentityProofMessage(changed), proof.signature, identity.publicKey)).toBe(false);
-    }
-  });
-
-  it('will not sign claims naming a different root', async () => {
-    const other = keyPair('22'.repeat(32));
-    await expect(signIdentityProof(identity, claims({ rootPublicKey: other.publicKey }))).rejects.toThrow('different root');
-  });
-});