@oxy.so/core 1.0.0

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

@@ -0,0 +1,63 @@
+/**
+ * `signChallengeWithSharedKey` tests.
+ *
+ * Verifies the shared-key challenge signer mirrors `signChallenge` exactly —
+ * same `auth:${publicKey}:${challenge}:${timestamp}` message format so the
+ * server verification path is unchanged — but sources the SHARED key from
+ * `KeyManager` (not the primary device key). We mock the shared key access with
+ * a real secp256k1 keypair so signing/verification is genuine.
+ */
+
+import { generateSecp256k1KeyPair } from '@oxy.so/protocol/secp256k1';
+import { verifySignature } from '@oxy.so/protocol';
+import { KeyManager } from '../keyManager';
+import { SignatureService } from '../signatureService';
+
+describe('SignatureService.signChallengeWithSharedKey', () => {
+  const sharedKeyPair = generateSecp256k1KeyPair();
+  const sharedPublicKey = sharedKeyPair.publicKey;
+  const sharedPrivateKey = sharedKeyPair.privateKey;
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('signs with the shared key and uses the unchanged message format', async () => {
+    jest.spyOn(KeyManager, 'getSharedPublicKey').mockResolvedValue(sharedPublicKey);
+    jest.spyOn(KeyManager, 'getSharedPrivateKey').mockResolvedValue(sharedPrivateKey);
+    // Guard: it must NOT fall back to the primary device key.
+    const primarySpy = jest.spyOn(KeyManager, 'getPublicKey');
+
+    const result = await SignatureService.signChallengeWithSharedKey('chal-123');
+
+    expect(result.publicKey).toBe(sharedPublicKey);
+    expect(typeof result.challenge).toBe('string'); // the signature
+    expect(typeof result.timestamp).toBe('number');
+    expect(primarySpy).not.toHaveBeenCalled();
+
+    // The signature verifies against the SAME message format `signChallenge`
+    // uses, proving the format is unchanged and the shared key signed it.
+    const message = `auth:${sharedPublicKey}:chal-123:${result.timestamp}`;
+    await expect(
+      verifySignature(message, result.challenge, sharedPublicKey),
+    ).resolves.toBe(true);
+  });
+
+  it('throws when no shared identity exists', async () => {
+    jest.spyOn(KeyManager, 'getSharedPublicKey').mockResolvedValue(null);
+    jest.spyOn(KeyManager, 'getSharedPrivateKey').mockResolvedValue(null);
+
+    await expect(
+      SignatureService.signChallengeWithSharedKey('chal-123'),
+    ).rejects.toThrow(/No shared identity/);
+  });
+
+  it('throws when the shared private key is missing even if the public key is present', async () => {
+    jest.spyOn(KeyManager, 'getSharedPublicKey').mockResolvedValue(sharedPublicKey);
+    jest.spyOn(KeyManager, 'getSharedPrivateKey').mockResolvedValue(null);
+
+    await expect(
+      SignatureService.signChallengeWithSharedKey('chal-123'),
+    ).rejects.toThrow(/No shared identity/);
+  });
+});

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

@@ -0,0 +1,230 @@
+/**
+ * Signed-record envelope tests — the DEVICE-key-bound path in `@oxy.so/core`.
+ *
+ * `SignatureService.signRecord` / `signRecordV2` read the device key from
+ * `KeyManager` and delegate the cryptography to `@oxy.so/protocol`'s
+ * `signEnvelope`. These tests prove the orchestration: an envelope built from a
+ * stored key round-trips through the protocol's `verifyEnvelopeSignature`, and
+ * tampering breaks it. The pure canonical-bytes / `computeRecordId` guards live
+ * in `@oxy.so/protocol`'s own suite.
+ *
+ * We mock `KeyManager.getPrivateKey` with a real secp256k1 private key,
+ * so the signing/verification is genuine cryptography (not a stub).
+ */
+
+import { generateSecp256k1KeyPair } from '@oxy.so/protocol/secp256k1';
+import type { SignedRecordEnvelope } from '@oxy.so/contracts';
+import {
+  canonicalize,
+  signedRecordSigningInput,
+  verifySignature,
+  verifyEnvelopeSignature,
+} from '@oxy.so/protocol';
+import { KeyManager } from '../keyManager';
+import { SignatureService } from '../signatureService';
+
+describe('SignatureService.signRecord / verifyEnvelopeSignature', () => {
+  const keyPair = generateSecp256k1KeyPair();
+  const publicKey = keyPair.publicKey;
+  const privateKey = keyPair.privateKey.padStart(64, '0');
+
+  beforeEach(() => {
+    jest.spyOn(KeyManager, 'getPrivateKey').mockResolvedValue(privateKey);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('builds a well-formed self-issued envelope', async () => {
+    const subject = 'did:web:oxy.so:u:abc123';
+    const record = { displayName: 'Nate', bio: 'builder' };
+
+    const envelope = await SignatureService.signRecord('profile', subject, record);
+
+    expect(envelope.version).toBe(1);
+    expect(envelope.type).toBe('profile');
+    expect(envelope.subject).toBe(subject);
+    expect(envelope.issuer).toBe(subject); // self-issued
+    expect(envelope.record).toEqual(record);
+    expect(envelope.publicKey).toBe(publicKey); // derived from the stored private key
+    expect(envelope.alg).toBe('ES256K-DER-SHA256');
+    expect(typeof envelope.signature).toBe('string');
+    expect(envelope.signature.length).toBeGreaterThan(0);
+    expect(typeof envelope.issuedAt).toBe('number');
+  });
+
+  it('round-trips: a freshly signed record verifies', async () => {
+    const envelope = await SignatureService.signRecord('identity', 'did:web:oxy.so:u:u1', {
+      handle: '@nate',
+      nested: { a: 1, b: [2, 3] },
+    });
+    await expect(verifyEnvelopeSignature(envelope)).resolves.toBe(true);
+  });
+
+  it('signs the canonical JSON of every field except publicKey + signature', async () => {
+    const subject = 'did:web:oxy.so:u:u2';
+    const record = { z: 1, a: 2 };
+    const envelope = await SignatureService.signRecord('profile', subject, record);
+
+    const expectedInput = canonicalize({
+      version: envelope.version,
+      type: envelope.type,
+      subject: envelope.subject,
+      issuer: envelope.issuer,
+      record: envelope.record,
+      issuedAt: envelope.issuedAt,
+    });
+
+    // The helper reproduces exactly that input from the envelope.
+    expect(signedRecordSigningInput(envelope)).toBe(expectedInput);
+    // And it omits publicKey/signature.
+    expect(expectedInput).not.toContain(envelope.publicKey);
+    expect(expectedInput).not.toContain(envelope.signature);
+
+    // The signature verifies against that exact input + the embedded key.
+    await expect(
+      verifySignature(expectedInput, envelope.signature, envelope.publicKey),
+    ).resolves.toBe(true);
+  });
+
+  describe('tamper detection', () => {
+    let envelope: SignedRecordEnvelope;
+
+    beforeEach(async () => {
+      envelope = await SignatureService.signRecord('profile', 'did:web:oxy.so:u:u3', {
+        displayName: 'Original',
+        score: 10,
+      });
+    });
+
+    it('rejects a mutated record', async () => {
+      const tampered: SignedRecordEnvelope = {
+        ...envelope,
+        record: { ...envelope.record, displayName: 'Tampered' },
+      };
+      await expect(verifyEnvelopeSignature(tampered)).resolves.toBe(false);
+    });
+
+    it('rejects a changed subject', async () => {
+      const tampered: SignedRecordEnvelope = { ...envelope, subject: 'did:web:oxy.so:u:evil' };
+      await expect(verifyEnvelopeSignature(tampered)).resolves.toBe(false);
+    });
+
+    it('rejects a changed issuedAt', async () => {
+      const tampered: SignedRecordEnvelope = { ...envelope, issuedAt: envelope.issuedAt + 1 };
+      await expect(verifyEnvelopeSignature(tampered)).resolves.toBe(false);
+    });
+
+    it('rejects verification against an unrelated public key', async () => {
+      const otherKey = generateSecp256k1KeyPair().publicKey;
+      const tampered: SignedRecordEnvelope = { ...envelope, publicKey: otherKey };
+      await expect(verifyEnvelopeSignature(tampered)).resolves.toBe(false);
+    });
+  });
+
+  it('throws when no identity is stored', async () => {
+    jest.spyOn(KeyManager, 'getPrivateKey').mockResolvedValue(null);
+    await expect(
+      SignatureService.signRecord('identity', 'did:web:oxy.so:u:u4', {}),
+    ).rejects.toThrow(/No identity found/);
+  });
+});
+
+describe('SignatureService.signRecordV2 / verifyEnvelopeSignature (v2 hash chain)', () => {
+  const keyPair = generateSecp256k1KeyPair();
+  const publicKey = keyPair.publicKey;
+  const privateKey = keyPair.privateKey.padStart(64, '0');
+
+  beforeEach(() => {
+    jest.spyOn(KeyManager, 'getPrivateKey').mockResolvedValue(privateKey);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  const chain = {
+    seq: 0,
+    prev: null as string | null,
+    collection: 'app.oxy.reputation',
+    rkey: 'rt_1',
+  };
+
+  it('builds a well-formed v2 envelope carrying the chain fields', async () => {
+    const subject = 'did:web:oxy.so:u:abc123';
+    const envelope = await SignatureService.signRecordV2(
+      'reputation_attestation',
+      subject,
+      { points: 25 },
+      chain,
+    );
+
+    expect(envelope.version).toBe(2);
+    expect(envelope.type).toBe('reputation_attestation');
+    expect(envelope.subject).toBe(subject);
+    expect(envelope.issuer).toBe(subject); // self-issued
+    expect(envelope.seq).toBe(0);
+    expect(envelope.prev).toBeNull();
+    expect(envelope.collection).toBe('app.oxy.reputation');
+    expect(envelope.rkey).toBe('rt_1');
+    expect(envelope.publicKey).toBe(publicKey);
+    expect(envelope.alg).toBe('ES256K-DER-SHA256');
+    expect(typeof envelope.signature).toBe('string');
+  });
+
+  it('round-trips: a freshly signed v2 record verifies', async () => {
+    const envelope = await SignatureService.signRecordV2(
+      'validation_verdict',
+      'did:web:oxy.so:u:v1',
+      { verdict: 'approve' },
+      { seq: 3, prev: 'a'.repeat(64), collection: 'app.oxy.validation', rkey: 'req_9' },
+    );
+    await expect(verifyEnvelopeSignature(envelope)).resolves.toBe(true);
+  });
+
+  it('covers the chain fields in the signed bytes (tampering breaks verify)', async () => {
+    const envelope = await SignatureService.signRecordV2(
+      'reputation_attestation',
+      'did:web:oxy.so:u:t1',
+      { points: 8 },
+      chain,
+    );
+
+    await expect(verifyEnvelopeSignature({ ...envelope, seq: 1 })).resolves.toBe(false);
+    await expect(
+      verifyEnvelopeSignature({ ...envelope, prev: 'b'.repeat(64) }),
+    ).resolves.toBe(false);
+    await expect(
+      verifyEnvelopeSignature({ ...envelope, collection: 'app.evil' }),
+    ).resolves.toBe(false);
+    await expect(verifyEnvelopeSignature({ ...envelope, rkey: 'other' })).resolves.toBe(false);
+  });
+
+  it('a v2 envelope signs over DIFFERENT bytes than the same base fields as v1', async () => {
+    const subject = 'did:web:oxy.so:u:diff';
+    const record = { x: 1 };
+    const v2 = await SignatureService.signRecordV2('profile', subject, record, chain);
+
+    const v1Input = signedRecordSigningInput({
+      version: 1,
+      type: 'profile',
+      subject,
+      issuer: subject,
+      record,
+      issuedAt: v2.issuedAt,
+    });
+    const v2Input = signedRecordSigningInput(v2);
+    expect(v2Input).not.toBe(v1Input);
+    expect(v2Input).toContain('"seq":0');
+    expect(v2Input).toContain('"prev":null');
+    expect(v2Input).toContain('"collection":"app.oxy.reputation"');
+  });
+
+  it('throws when no identity is stored', async () => {
+    jest.spyOn(KeyManager, 'getPrivateKey').mockResolvedValue(null);
+    await expect(
+      SignatureService.signRecordV2('identity', 'did:web:oxy.so:u:u4', {}, chain),
+    ).rejects.toThrow(/No identity found/);
+  });
+});

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,37 @@
+/**
+ * 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 shared `@oxy.so/protocol` secp256k1 primitive.
+ * 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 { deriveSecp256k1SharedSecret } from '@oxy.so/protocol/secp256k1';
+
+/**
+ * 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 {
+  return deriveSecp256k1SharedSecret(privateKeyHex, otherPublicKeyHex);
+}