@reley/crypto 0.1.0

package/dist/utils.js

@@ -0,0 +1,37 @@
+import { ensureSodium } from './keys.js';
+/**
+ * Compute a human-readable fingerprint from two public keys for MITM verification.
+ * Keys are sorted lexicographically to ensure both parties produce the same fingerprint.
+ * Uses Blake2b-128 hash, formatted as uppercase hex groups: "XXXX-XXXX-..."
+ */
+export async function computeFingerprint(pk1, pk2) {
+    const s = await ensureSodium();
+    const sorted = [pk1, pk2].sort((a, b) => {
+        for (let i = 0; i < a.length; i++) {
+            if (a[i] !== b[i])
+                return a[i] - b[i];
+        }
+        return 0;
+    });
+    const combined = new Uint8Array(sorted[0].length + sorted[1].length);
+    combined.set(sorted[0], 0);
+    combined.set(sorted[1], sorted[0].length);
+    const hash = s.crypto_generichash(16, combined, null);
+    const hex = s.to_hex(hash).toUpperCase();
+    return hex.match(/.{4}/g).join('-');
+}
+/**
+ * Encode a Uint8Array to a base64url string (no padding).
+ */
+export async function toBase64Url(data) {
+    const s = await ensureSodium();
+    return s.to_base64(data, s.base64_variants.URLSAFE_NO_PADDING);
+}
+/**
+ * Decode a base64url string to a Uint8Array.
+ */
+export async function fromBase64Url(str) {
+    const s = await ensureSodium();
+    return s.from_base64(str, s.base64_variants.URLSAFE_NO_PADDING);
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,GAAe,EACf,GAAe;IAEf,MAAM,CAAC,GAAG,MAAM,YAAY,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACtC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAClC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBAAE,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACxC,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;IACH,MAAM,QAAQ,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACrE,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3B,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,CAAC,CAAC,kBAAkB,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;IACtD,MAAM,GAAG,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;IACzC,OAAO,GAAG,CAAC,KAAK,CAAC,OAAO,CAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACvC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAgB;IAChD,MAAM,CAAC,GAAG,MAAM,YAAY,EAAE,CAAC;IAC/B,OAAO,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,eAAe,CAAC,kBAAkB,CAAC,CAAC;AACjE,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAW;IAC7C,MAAM,CAAC,GAAG,MAAM,YAAY,EAAE,CAAC;IAC/B,OAAO,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,eAAe,CAAC,kBAAkB,CAAC,CAAC;AAClE,CAAC"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@reley/crypto",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "E2E encryption primitives for Reley (X25519, HKDF, XChaCha20-Poly1305, Double Ratchet)",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "src", "LICENSE"],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "libsodium-wrappers-sumo": "^0.7.15"
+  },
+  "devDependencies": {
+    "@types/libsodium-wrappers-sumo": "^0.7.8",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  }
+}

package/src/__tests__/cipher.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import { encrypt, decrypt, KEY_LENGTH } from '../cipher.js';
+import { ensureSodium } from '../keys.js';
+
+describe('cipher (XChaCha20-Poly1305)', () => {
+  it('should encrypt and decrypt round-trip', async () => {
+    const s = await ensureSodium();
+    const key = s.randombytes_buf(KEY_LENGTH);
+    const plaintext = new TextEncoder().encode('Hello, Reley!');
+
+    const { nonce, ciphertext } = await encrypt(plaintext, key);
+    const decrypted = await decrypt(ciphertext, nonce, key);
+
+    expect(new TextDecoder().decode(decrypted)).toBe('Hello, Reley!');
+  });
+
+  it('should fail with wrong key', async () => {
+    const s = await ensureSodium();
+    const key1 = s.randombytes_buf(KEY_LENGTH);
+    const key2 = s.randombytes_buf(KEY_LENGTH);
+    const plaintext = new TextEncoder().encode('secret');
+
+    const { nonce, ciphertext } = await encrypt(plaintext, key1);
+    await expect(decrypt(ciphertext, nonce, key2)).rejects.toThrow('Decryption failed');
+  });
+
+  it('should fail with tampered ciphertext', async () => {
+    const s = await ensureSodium();
+    const key = s.randombytes_buf(KEY_LENGTH);
+    const plaintext = new TextEncoder().encode('secret');
+
+    const { nonce, ciphertext } = await encrypt(plaintext, key);
+    ciphertext[0] ^= 0xff; // tamper
+    await expect(decrypt(ciphertext, nonce, key)).rejects.toThrow('Decryption failed');
+  });
+
+  it('should support AAD', async () => {
+    const s = await ensureSodium();
+    const key = s.randombytes_buf(KEY_LENGTH);
+    const plaintext = new TextEncoder().encode('with aad');
+    const aad = new TextEncoder().encode('additional data');
+
+    const { nonce, ciphertext } = await encrypt(plaintext, key, aad);
+    const decrypted = await decrypt(ciphertext, nonce, key, aad);
+    expect(new TextDecoder().decode(decrypted)).toBe('with aad');
+
+    // Wrong AAD should fail
+    const wrongAad = new TextEncoder().encode('wrong');
+    await expect(decrypt(ciphertext, nonce, key, wrongAad)).rejects.toThrow('Decryption failed');
+  });
+
+  it('should reject invalid key length', async () => {
+    const plaintext = new TextEncoder().encode('test');
+    const badKey = new Uint8Array(16);
+    await expect(encrypt(plaintext, badKey)).rejects.toThrow('Key must be 32 bytes');
+  });
+});

package/src/__tests__/ecdh.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest';
+import { generateEphemeralKeyPair } from '../keys.js';
+import { computeSharedSecret } from '../ecdh.js';
+
+describe('ecdh', () => {
+  it('should compute matching shared secrets', async () => {
+    const alice = await generateEphemeralKeyPair();
+    const bob = await generateEphemeralKeyPair();
+
+    const secretAlice = await computeSharedSecret(alice.secretKey, bob.publicKey);
+    const secretBob = await computeSharedSecret(bob.secretKey, alice.publicKey);
+
+    expect(secretAlice).toHaveLength(32);
+    expect(Buffer.from(secretAlice)).toEqual(Buffer.from(secretBob));
+  });
+
+  it('should produce different secrets for different key pairs', async () => {
+    const alice = await generateEphemeralKeyPair();
+    const bob = await generateEphemeralKeyPair();
+    const carol = await generateEphemeralKeyPair();
+
+    const secretAB = await computeSharedSecret(alice.secretKey, bob.publicKey);
+    const secretAC = await computeSharedSecret(alice.secretKey, carol.publicKey);
+
+    expect(Buffer.from(secretAB)).not.toEqual(Buffer.from(secretAC));
+  });
+});

package/src/__tests__/hkdf.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest';
+import { deriveSessionKeys, deriveChainKey } from '../hkdf.js';
+import { ensureSodium } from '../keys.js';
+
+describe('hkdf', () => {
+  it('should derive different send and recv keys', async () => {
+    const s = await ensureSodium();
+    const sharedSecret = s.randombytes_buf(32);
+
+    const { sendKey, recvKey } = await deriveSessionKeys(sharedSecret);
+    expect(sendKey).toHaveLength(32);
+    expect(recvKey).toHaveLength(32);
+    expect(Buffer.from(sendKey)).not.toEqual(Buffer.from(recvKey));
+  });
+
+  it('should produce deterministic keys for same input', async () => {
+    const s = await ensureSodium();
+    const sharedSecret = s.randombytes_buf(32);
+
+    const keys1 = await deriveSessionKeys(sharedSecret);
+    const keys2 = await deriveSessionKeys(sharedSecret);
+
+    expect(Buffer.from(keys1.sendKey)).toEqual(Buffer.from(keys2.sendKey));
+    expect(Buffer.from(keys1.recvKey)).toEqual(Buffer.from(keys2.recvKey));
+  });
+
+  it('should produce different keys for different secrets', async () => {
+    const s = await ensureSodium();
+    const secret1 = s.randombytes_buf(32);
+    const secret2 = s.randombytes_buf(32);
+
+    const keys1 = await deriveSessionKeys(secret1);
+    const keys2 = await deriveSessionKeys(secret2);
+
+    expect(Buffer.from(keys1.sendKey)).not.toEqual(Buffer.from(keys2.sendKey));
+  });
+
+  it('should derive chain keys progressively', async () => {
+    const s = await ensureSodium();
+    const chainKey = s.randombytes_buf(32);
+
+    const { messageKey, nextChainKey } = await deriveChainKey(chainKey);
+    expect(messageKey).toHaveLength(32);
+    expect(nextChainKey).toHaveLength(32);
+
+    // Chain key should change
+    expect(Buffer.from(nextChainKey)).not.toEqual(Buffer.from(chainKey));
+    // Message key should differ from chain key
+    expect(Buffer.from(messageKey)).not.toEqual(Buffer.from(chainKey));
+  });
+
+  it('should produce deterministic chain progression', async () => {
+    const s = await ensureSodium();
+    const chainKey = s.randombytes_buf(32);
+
+    const result1 = await deriveChainKey(chainKey);
+    const result2 = await deriveChainKey(chainKey);
+
+    expect(Buffer.from(result1.messageKey)).toEqual(Buffer.from(result2.messageKey));
+    expect(Buffer.from(result1.nextChainKey)).toEqual(Buffer.from(result2.nextChainKey));
+  });
+});

package/src/__tests__/keys.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest';
+import {
+  generateIdentityKeyPair,
+  generateEphemeralKeyPair,
+  ed25519ToX25519Public,
+  ed25519ToX25519Secret,
+  generateOneTimeCode,
+  sign,
+  verify,
+} from '../keys.js';
+
+describe('keys', () => {
+  it('should generate Ed25519 identity key pair', async () => {
+    const kp = await generateIdentityKeyPair();
+    expect(kp.keyType).toBe('ed25519');
+    expect(kp.publicKey).toHaveLength(32);
+    expect(kp.secretKey).toHaveLength(64);
+  });
+
+  it('should generate unique key pairs', async () => {
+    const kp1 = await generateIdentityKeyPair();
+    const kp2 = await generateIdentityKeyPair();
+    expect(kp1.publicKey).not.toEqual(kp2.publicKey);
+  });
+
+  it('should generate X25519 ephemeral key pair', async () => {
+    const kp = await generateEphemeralKeyPair();
+    expect(kp.keyType).toBe('x25519');
+    expect(kp.publicKey).toHaveLength(32);
+    expect(kp.secretKey).toHaveLength(32);
+  });
+
+  it('should convert Ed25519 to X25519 keys', async () => {
+    const ed = await generateIdentityKeyPair();
+    const x25519Pk = await ed25519ToX25519Public(ed.publicKey);
+    const x25519Sk = await ed25519ToX25519Secret(ed.secretKey);
+    expect(x25519Pk).toHaveLength(32);
+    expect(x25519Sk).toHaveLength(32);
+  });
+
+  it('should generate one-time code', async () => {
+    const otc = await generateOneTimeCode(32);
+    expect(otc).toHaveLength(32);
+    const otc2 = await generateOneTimeCode(32);
+    expect(otc).not.toEqual(otc2);
+  });
+
+  it('should sign and verify messages', async () => {
+    const kp = await generateIdentityKeyPair();
+    const message = new TextEncoder().encode('hello world');
+    const signature = await sign(message, kp.secretKey);
+    expect(signature).toHaveLength(64);
+
+    const valid = await verify(signature, message, kp.publicKey);
+    expect(valid).toBe(true);
+
+    // Tampered message should fail
+    const tampered = new TextEncoder().encode('hello world!');
+    const invalid = await verify(signature, tampered, kp.publicKey);
+    expect(invalid).toBe(false);
+  });
+});

package/src/__tests__/qr-payload.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest';
+import { encodeQRPayload, decodeQRPayload, hashOneTimeCode } from '../qr-payload.js';
+import { ensureSodium } from '../keys.js';
+
+describe('qr-payload', () => {
+  it('should encode and decode QR payload round-trip', async () => {
+    const s = await ensureSodium();
+    const payload = {
+      releyUrl: 'wss://reley.example.com',
+      publicKey: s.randombytes_buf(32),
+      oneTimeCode: s.randombytes_buf(32),
+      jwt: 'eyJhbGciOiJIUzI1NiJ9.test.signature',
+    };
+
+    const encoded = await encodeQRPayload(payload);
+    expect(typeof encoded).toBe('string');
+
+    const decoded = await decodeQRPayload(encoded);
+    expect(decoded.releyUrl).toBe(payload.releyUrl);
+    expect(Buffer.from(decoded.publicKey)).toEqual(Buffer.from(payload.publicKey));
+    expect(Buffer.from(decoded.oneTimeCode)).toEqual(Buffer.from(payload.oneTimeCode));
+    expect(decoded.jwt).toBe(payload.jwt);
+  });
+
+  it('should reject too-short payload', async () => {
+    const s = await ensureSodium();
+    const badData = s.to_base64(
+      new TextEncoder().encode('XX1bad'),
+      s.base64_variants.URLSAFE_NO_PADDING,
+    );
+    await expect(decodeQRPayload(badData)).rejects.toThrow('QR payload too short');
+  });
+
+  it('should reject invalid magic', async () => {
+    const s = await ensureSodium();
+    // Build a buffer that passes the length check but has wrong magic
+    const buf = new Uint8Array(71);
+    buf[0] = 'X'.charCodeAt(0);
+    buf[1] = 'X'.charCodeAt(0);
+    buf[2] = '1'.charCodeAt(0);
+    const badData = s.to_base64(buf, s.base64_variants.URLSAFE_NO_PADDING);
+    await expect(decodeQRPayload(badData)).rejects.toThrow('Invalid QR payload magic');
+  });
+
+  it('should hash one-time codes consistently', async () => {
+    const s = await ensureSodium();
+    const otc = s.randombytes_buf(32);
+    const hash1 = await hashOneTimeCode(otc);
+    const hash2 = await hashOneTimeCode(otc);
+    expect(Buffer.from(hash1)).toEqual(Buffer.from(hash2));
+    expect(hash1).toHaveLength(32);
+  });
+
+  it('should produce different hashes for different OTCs', async () => {
+    const s = await ensureSodium();
+    const otc1 = s.randombytes_buf(32);
+    const otc2 = s.randombytes_buf(32);
+    const hash1 = await hashOneTimeCode(otc1);
+    const hash2 = await hashOneTimeCode(otc2);
+    expect(Buffer.from(hash1)).not.toEqual(Buffer.from(hash2));
+  });
+});

package/src/__tests__/ratchet.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect } from 'vitest';
+import { generateEphemeralKeyPair } from '../keys.js';
+import { computeSharedSecret } from '../ecdh.js';
+import { deriveSessionKeys } from '../hkdf.js';
+import {
+  initRatchet,
+  ratchetEncrypt,
+  ratchetDecrypt,
+  needsKeyRotation,
+  KEY_ROTATION_INTERVAL,
+} from '../ratchet.js';
+
+describe('ratchet', () => {
+  async function createPairedRatchets() {
+    const alice = await generateEphemeralKeyPair();
+    const bob = await generateEphemeralKeyPair();
+
+    const sharedAlice = await computeSharedSecret(alice.secretKey, bob.publicKey);
+    const sharedBob = await computeSharedSecret(bob.secretKey, alice.publicKey);
+
+    const keysAlice = await deriveSessionKeys(sharedAlice);
+    const keysBob = await deriveSessionKeys(sharedBob);
+
+    // Alice's send = Bob's recv, Alice's recv = Bob's send
+    const aliceState = initRatchet(keysAlice.sendKey, keysAlice.recvKey);
+    const bobState = initRatchet(keysBob.recvKey, keysBob.sendKey);
+
+    return { aliceState, bobState };
+  }
+
+  it('should encrypt and decrypt a message', async () => {
+    let { aliceState, bobState } = await createPairedRatchets();
+
+    const plaintext = new TextEncoder().encode('Hello Bob!');
+    const encrypted = await ratchetEncrypt(aliceState, plaintext);
+    aliceState = encrypted.state;
+
+    const decrypted = await ratchetDecrypt(
+      bobState,
+      encrypted.ciphertext,
+      encrypted.nonce,
+      encrypted.counter,
+    );
+    bobState = decrypted.state;
+
+    expect(new TextDecoder().decode(decrypted.plaintext)).toBe('Hello Bob!');
+  });
+
+  it('should handle multiple messages', async () => {
+    let { aliceState, bobState } = await createPairedRatchets();
+
+    for (let i = 0; i < 10; i++) {
+      const msg = `Message ${i}`;
+      const encrypted = await ratchetEncrypt(aliceState, new TextEncoder().encode(msg));
+      aliceState = encrypted.state;
+
+      const decrypted = await ratchetDecrypt(
+        bobState,
+        encrypted.ciphertext,
+        encrypted.nonce,
+        encrypted.counter,
+      );
+      bobState = decrypted.state;
+
+      expect(new TextDecoder().decode(decrypted.plaintext)).toBe(msg);
+    }
+
+    expect(aliceState.sendCounter).toBe(10);
+  });
+
+  it('should detect replay attacks', async () => {
+    let { aliceState, bobState } = await createPairedRatchets();
+
+    const encrypted = await ratchetEncrypt(
+      aliceState,
+      new TextEncoder().encode('first'),
+    );
+    aliceState = encrypted.state;
+
+    const decrypted = await ratchetDecrypt(
+      bobState,
+      encrypted.ciphertext,
+      encrypted.nonce,
+      encrypted.counter,
+    );
+    bobState = decrypted.state;
+
+    // Replay the same message
+    await expect(
+      ratchetDecrypt(bobState, encrypted.ciphertext, encrypted.nonce, encrypted.counter),
+    ).rejects.toThrow('Replay attack detected');
+  });
+
+  it('should signal key rotation need', () => {
+    const state = initRatchet(new Uint8Array(32), new Uint8Array(32));
+    expect(needsKeyRotation(state)).toBe(false);
+
+    const rotationState = { ...state, sendCounter: KEY_ROTATION_INTERVAL };
+    expect(needsKeyRotation(rotationState)).toBe(true);
+  });
+
+  it('should handle bidirectional communication', async () => {
+    let { aliceState, bobState } = await createPairedRatchets();
+
+    // Alice → Bob
+    const enc1 = await ratchetEncrypt(aliceState, new TextEncoder().encode('A→B'));
+    aliceState = enc1.state;
+    const dec1 = await ratchetDecrypt(bobState, enc1.ciphertext, enc1.nonce, enc1.counter);
+    bobState = dec1.state;
+    expect(new TextDecoder().decode(dec1.plaintext)).toBe('A→B');
+
+    // Bob → Alice
+    const enc2 = await ratchetEncrypt(bobState, new TextEncoder().encode('B→A'));
+    bobState = enc2.state;
+    const dec2 = await ratchetDecrypt(aliceState, enc2.ciphertext, enc2.nonce, enc2.counter);
+    aliceState = dec2.state;
+    expect(new TextDecoder().decode(dec2.plaintext)).toBe('B→A');
+  });
+});

package/src/cipher.ts

@@ -0,0 +1,90 @@
+/**
+ * XChaCha20-Poly1305 AEAD cipher.
+ *
+ * Despite the original filename "aes-gcm.ts", the actual algorithm has always
+ * been XChaCha20-Poly1305 via libsodium — AES-GCM was not used because it
+ * requires hardware AES-NI support which is unavailable on many platforms.
+ *
+ * XChaCha20-Poly1305 is a modern AEAD cipher providing:
+ *  - 256-bit key security
+ *  - 192-bit nonce (24 bytes) — practically eliminates nonce collision risk
+ *  - Poly1305 authentication tag (16 bytes)
+ *
+ * Nonce handling:
+ *  We generate a 12-byte random nonce and zero-pad it to 24 bytes for the
+ *  XChaCha20-Poly1305 IETF construction. The 12-byte nonce is transmitted on
+ *  the wire to save bandwidth; the receiver pads identically before decryption.
+ *  With random 12-byte nonces the collision probability is ~2^-48 per message
+ *  pair, which is safe for the expected message volume.
+ */
+import type _sodium from 'libsodium-wrappers-sumo';
+import { ensureSodium } from './keys.js';
+
+export const NONCE_LENGTH = 12;
+export const TAG_LENGTH = 16;
+export const KEY_LENGTH = 32;
+
+/**
+ * Encrypt data with XChaCha20-Poly1305.
+ * @returns { nonce, ciphertext } where ciphertext includes the auth tag
+ */
+export async function encrypt(
+  plaintext: Uint8Array,
+  key: Uint8Array,
+  aad: Uint8Array = new Uint8Array(0),
+): Promise<{ nonce: Uint8Array; ciphertext: Uint8Array }> {
+  const s = await ensureSodium();
+
+  if (key.length !== KEY_LENGTH) {
+    throw new Error(`Key must be ${KEY_LENGTH} bytes, got ${key.length}`);
+  }
+
+  const nonce = s.randombytes_buf(NONCE_LENGTH);
+  const ciphertext = s.crypto_aead_xchacha20poly1305_ietf_encrypt(
+    plaintext,
+    aad.length > 0 ? aad : null,
+    null, // nsec (unused)
+    // xchacha uses 24-byte nonce, pad our 12-byte nonce
+    padNonce(nonce, s),
+    key,
+  );
+
+  return { nonce, ciphertext };
+}
+
+/**
+ * Decrypt data with XChaCha20-Poly1305.
+ */
+export async function decrypt(
+  ciphertext: Uint8Array,
+  nonce: Uint8Array,
+  key: Uint8Array,
+  aad: Uint8Array = new Uint8Array(0),
+): Promise<Uint8Array> {
+  const s = await ensureSodium();
+
+  if (key.length !== KEY_LENGTH) {
+    throw new Error(`Key must be ${KEY_LENGTH} bytes, got ${key.length}`);
+  }
+
+  try {
+    return s.crypto_aead_xchacha20poly1305_ietf_decrypt(
+      null, // nsec (unused)
+      ciphertext,
+      aad.length > 0 ? aad : null,
+      padNonce(nonce, s),
+      key,
+    );
+  } catch {
+    throw new Error('Decryption failed: invalid ciphertext or key');
+  }
+}
+
+/**
+ * Pad a 12-byte nonce to 24 bytes for xchacha20poly1305.
+ */
+function padNonce(nonce: Uint8Array, s: typeof _sodium): Uint8Array {
+  const padded = new Uint8Array(s.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
+  padded.set(nonce, 0);
+  return padded;
+}

package/src/ecdh.ts

@@ -0,0 +1,13 @@
+import { ensureSodium } from './keys.js';
+
+/**
+ * Compute X25519 ECDH shared secret from our secret key and their public key.
+ * Returns 32-byte raw shared secret.
+ */
+export async function computeSharedSecret(
+  ourSecretKey: Uint8Array,
+  theirPublicKey: Uint8Array,
+): Promise<Uint8Array> {
+  const s = await ensureSodium();
+  return s.crypto_scalarmult(ourSecretKey, theirPublicKey);
+}

package/src/hkdf.ts

@@ -0,0 +1,69 @@
+import { ensureSodium } from './keys.js';
+
+const HKDF_HASH_LEN = 32; // SHA-256
+
+/**
+ * HKDF-Extract: PRK = HMAC-SHA256(salt, IKM)
+ */
+async function hkdfExtract(salt: Uint8Array, ikm: Uint8Array): Promise<Uint8Array> {
+  const s = await ensureSodium();
+  const key = salt.length > 0 ? salt : new Uint8Array(HKDF_HASH_LEN);
+  return s.crypto_auth_hmacsha256(ikm, key);
+}
+
+/**
+ * HKDF-Expand: OKM = T(1) || T(2) || ... truncated to length
+ */
+async function hkdfExpand(prk: Uint8Array, info: Uint8Array, length: number): Promise<Uint8Array> {
+  const s = await ensureSodium();
+  const n = Math.ceil(length / HKDF_HASH_LEN);
+  const okm = new Uint8Array(n * HKDF_HASH_LEN);
+  let prev = new Uint8Array(0);
+
+  for (let i = 1; i <= n; i++) {
+    const input = new Uint8Array(prev.length + info.length + 1);
+    input.set(prev, 0);
+    input.set(info, prev.length);
+    input[prev.length + info.length] = i;
+    prev = new Uint8Array(s.crypto_auth_hmacsha256(input, prk));
+    okm.set(prev, (i - 1) * HKDF_HASH_LEN);
+  }
+
+  return okm.slice(0, length);
+}
+
+/**
+ * Derive symmetric keys from ECDH shared secret.
+ * Returns { sendKey, recvKey } each 32 bytes for AEAD cipher.
+ */
+export async function deriveSessionKeys(
+  sharedSecret: Uint8Array,
+  salt: Uint8Array = new Uint8Array(0),
+  info: string = 'reley-v1',
+): Promise<{ sendKey: Uint8Array; recvKey: Uint8Array }> {
+  const infoBytes = new TextEncoder().encode(info);
+  const prk = await hkdfExtract(salt, sharedSecret);
+  // 64 bytes: first 32 = send key, next 32 = recv key
+  const okm = await hkdfExpand(prk, infoBytes, 64);
+  return {
+    sendKey: okm.slice(0, 32),
+    recvKey: okm.slice(32, 64),
+  };
+}
+
+/**
+ * Derive a single chain key for ratchet progression.
+ */
+export async function deriveChainKey(
+  chainKey: Uint8Array,
+  info: string = 'reley-chain',
+): Promise<{ messageKey: Uint8Array; nextChainKey: Uint8Array }> {
+  const s = await ensureSodium();
+  const msgKeyInput = new TextEncoder().encode(info + '-msg');
+  const chainKeyInput = new TextEncoder().encode(info + '-chain');
+
+  const messageKey = s.crypto_auth_hmacsha256(msgKeyInput, chainKey);
+  const nextChainKey = s.crypto_auth_hmacsha256(chainKeyInput, chainKey);
+
+  return { messageKey, nextChainKey };
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+export {
+  ensureSodium,
+  generateIdentityKeyPair,
+  generateEphemeralKeyPair,
+  ed25519ToX25519Public,
+  ed25519ToX25519Secret,
+  generateOneTimeCode,
+  sign,
+  verify,
+  type Ed25519KeyPair,
+  type X25519KeyPair,
+} from './keys.js';
+
+export { computeSharedSecret } from './ecdh.js';
+
+export { deriveSessionKeys, deriveChainKey } from './hkdf.js';
+
+export {
+  encrypt,
+  decrypt,
+  NONCE_LENGTH,
+  TAG_LENGTH,
+  KEY_LENGTH,
+} from './cipher.js';
+
+export {
+  initRatchet,
+  ratchetEncrypt,
+  ratchetDecrypt,
+  needsKeyRotation,
+  KEY_ROTATION_INTERVAL,
+  type RatchetState,
+} from './ratchet.js';
+
+export {
+  encodeQRPayload,
+  decodeQRPayload,
+  hashOneTimeCode,
+  type QRPayload,
+} from './qr-payload.js';
+
+export {
+  computeFingerprint,
+  toBase64Url,
+  fromBase64Url,
+} from './utils.js';