@reley/crypto 0.1.0

package/src/keys.ts

@@ -0,0 +1,105 @@
+/**
+ * Key generation, signing, and libsodium initialization.
+ *
+ * Uses a default import of libsodium-wrappers-sumo which works across
+ * environments:
+ *  - Node.js: vitest alias / bundler resolves to the CJS module
+ *  - Browser: bundlers (webpack/vite) handle ESM resolution
+ */
+
+import _sodium from 'libsodium-wrappers-sumo';
+
+let initialized = false;
+
+/**
+ * Ensure libsodium is loaded and ready.
+ */
+export async function ensureSodium(): Promise<typeof _sodium> {
+  if (!initialized) {
+    await _sodium.ready;
+    initialized = true;
+  }
+  return _sodium;
+}
+
+export interface Ed25519KeyPair {
+  publicKey: Uint8Array; // 32 bytes
+  secretKey: Uint8Array; // 64 bytes
+  keyType: 'ed25519';
+}
+
+export interface X25519KeyPair {
+  publicKey: Uint8Array; // 32 bytes
+  secretKey: Uint8Array; // 32 bytes
+  keyType: 'x25519';
+}
+
+/**
+ * Generate an Ed25519 identity key pair (long-term, per-device).
+ */
+export async function generateIdentityKeyPair(): Promise<Ed25519KeyPair> {
+  const s = await ensureSodium();
+  const kp = s.crypto_sign_keypair();
+  return {
+    publicKey: kp.publicKey,
+    secretKey: kp.privateKey,
+    keyType: 'ed25519',
+  };
+}
+
+/**
+ * Generate an X25519 ephemeral key pair (per-session).
+ */
+export async function generateEphemeralKeyPair(): Promise<X25519KeyPair> {
+  const s = await ensureSodium();
+  const kp = s.crypto_kx_keypair();
+  return {
+    publicKey: kp.publicKey,
+    secretKey: kp.privateKey,
+    keyType: 'x25519',
+  };
+}
+
+/**
+ * Convert an Ed25519 public key to X25519 for ECDH.
+ */
+export async function ed25519ToX25519Public(ed25519Pk: Uint8Array): Promise<Uint8Array> {
+  const s = await ensureSodium();
+  return s.crypto_sign_ed25519_pk_to_curve25519(ed25519Pk);
+}
+
+/**
+ * Convert an Ed25519 secret key to X25519 for ECDH.
+ */
+export async function ed25519ToX25519Secret(ed25519Sk: Uint8Array): Promise<Uint8Array> {
+  const s = await ensureSodium();
+  return s.crypto_sign_ed25519_sk_to_curve25519(ed25519Sk);
+}
+
+/**
+ * Generate a cryptographically secure random one-time code.
+ */
+export async function generateOneTimeCode(length: number = 32): Promise<Uint8Array> {
+  const s = await ensureSodium();
+  return s.randombytes_buf(length);
+}
+
+/**
+ * Sign a message with an Ed25519 secret key.
+ */
+export async function sign(message: Uint8Array, secretKey: Uint8Array): Promise<Uint8Array> {
+  const s = await ensureSodium();
+  return s.crypto_sign_detached(message, secretKey);
+}
+
+/**
+ * Verify an Ed25519 signature.
+ */
+export async function verify(
+  signature: Uint8Array,
+  message: Uint8Array,
+  publicKey: Uint8Array,
+): Promise<boolean> {
+  const s = await ensureSodium();
+  return s.crypto_sign_verify_detached(signature, message, publicKey);
+}

package/src/qr-payload.ts

@@ -0,0 +1,112 @@
+import { ensureSodium } from './keys.js';
+
+export interface QRPayload {
+  releyUrl: string;
+  publicKey: Uint8Array; // 32 bytes - X25519 public key
+  oneTimeCode: Uint8Array; // 32 bytes
+  jwt: string;
+}
+
+const MAGIC = 'CB1'; // Reley v1
+
+/**
+ * Encode a QR payload to a base64url string.
+ */
+export async function encodeQRPayload(payload: QRPayload): Promise<string> {
+  const s = await ensureSodium();
+
+  const releyBytes = new TextEncoder().encode(payload.releyUrl);
+  const jwtBytes = new TextEncoder().encode(payload.jwt);
+
+  // Format: MAGIC(3) + releyLen(2 BE) + reley + pubKey(32) + otc(32) + jwtLen(2 BE) + jwt
+  const totalLen =
+    3 + 2 + releyBytes.length + 32 + 32 + 2 + jwtBytes.length;
+  const buf = new Uint8Array(totalLen);
+  let offset = 0;
+
+  // Magic
+  buf[offset++] = MAGIC.charCodeAt(0);
+  buf[offset++] = MAGIC.charCodeAt(1);
+  buf[offset++] = MAGIC.charCodeAt(2);
+
+  // Reley URL length + data
+  buf[offset++] = (releyBytes.length >>> 8) & 0xff;
+  buf[offset++] = releyBytes.length & 0xff;
+  buf.set(releyBytes, offset);
+  offset += releyBytes.length;
+
+  // Public key (32 bytes)
+  buf.set(payload.publicKey, offset);
+  offset += 32;
+
+  // One-time code (32 bytes)
+  buf.set(payload.oneTimeCode, offset);
+  offset += 32;
+
+  // JWT length + data
+  buf[offset++] = (jwtBytes.length >>> 8) & 0xff;
+  buf[offset++] = jwtBytes.length & 0xff;
+  buf.set(jwtBytes, offset);
+
+  return s.to_base64(buf, s.base64_variants.URLSAFE_NO_PADDING);
+}
+
+/**
+ * Decode a QR payload from a base64url string.
+ */
+export async function decodeQRPayload(encoded: string): Promise<QRPayload> {
+  const s = await ensureSodium();
+
+  const buf = s.from_base64(encoded, s.base64_variants.URLSAFE_NO_PADDING);
+
+  // Minimum: MAGIC(3) + releyLen(2) + pubKey(32) + otc(32) + jwtLen(2) = 71 bytes
+  if (buf.length < 71) {
+    throw new Error(`QR payload too short: ${buf.length} bytes (minimum 71)`);
+  }
+
+  let offset = 0;
+
+  // Verify magic
+  const magic = String.fromCharCode(buf[offset++], buf[offset++], buf[offset++]);
+  if (magic !== MAGIC) {
+    throw new Error(`Invalid QR payload magic: ${magic}`);
+  }
+
+  // Reley URL
+  const releyLen = (buf[offset] << 8) | buf[offset + 1];
+  offset += 2;
+  if (offset + releyLen + 32 + 32 + 2 > buf.length) {
+    throw new Error('QR payload truncated: reley URL overflows buffer');
+  }
+  const releyUrl = new TextDecoder().decode(buf.slice(offset, offset + releyLen));
+  offset += releyLen;
+
+  // Public key (32 bytes)
+  const publicKey = buf.slice(offset, offset + 32);
+  offset += 32;
+
+  // One-time code (32 bytes)
+  const oneTimeCode = buf.slice(offset, offset + 32);
+  offset += 32;
+
+  // JWT
+  if (offset + 2 > buf.length) {
+    throw new Error('QR payload truncated: missing JWT length');
+  }
+  const jwtLen = (buf[offset] << 8) | buf[offset + 1];
+  offset += 2;
+  if (offset + jwtLen > buf.length) {
+    throw new Error('QR payload truncated: JWT overflows buffer');
+  }
+  const jwt = new TextDecoder().decode(buf.slice(offset, offset + jwtLen));
+
+  return { releyUrl, publicKey, oneTimeCode, jwt };
+}
+
+/**
+ * Hash a one-time code (for safe transmission to reley).
+ */
+export async function hashOneTimeCode(otc: Uint8Array): Promise<Uint8Array> {
+  const s = await ensureSodium();
+  return s.crypto_generichash(32, otc, null);
+}

package/src/ratchet.ts

@@ -0,0 +1,124 @@
+import { deriveChainKey } from './hkdf.js';
+import { encrypt, decrypt } from './cipher.js';
+
+export const KEY_ROTATION_INTERVAL = 50;
+
+export interface RatchetState {
+  sendChainKey: Uint8Array;
+  recvChainKey: Uint8Array;
+  sendCounter: number;
+  recvCounter: number;
+  /** Highest received counter for replay protection */
+  maxRecvCounter: number;
+}
+
+/**
+ * Initialize a ratchet state from derived session keys.
+ */
+export function initRatchet(sendKey: Uint8Array, recvKey: Uint8Array): RatchetState {
+  return {
+    sendChainKey: sendKey,
+    recvChainKey: recvKey,
+    sendCounter: 0,
+    recvCounter: 0,
+    maxRecvCounter: -1,
+  };
+}
+
+/**
+ * Encrypt a message and advance the send ratchet.
+ */
+export async function ratchetEncrypt(
+  state: RatchetState,
+  plaintext: Uint8Array,
+): Promise<{ ciphertext: Uint8Array; nonce: Uint8Array; counter: number; state: RatchetState }> {
+  const { messageKey, nextChainKey } = await deriveChainKey(state.sendChainKey);
+  const counter = state.sendCounter;
+
+  // Build AAD: counter as 4-byte big-endian
+  const aad = buildAAD(1, counter);
+
+  const { nonce, ciphertext } = await encrypt(plaintext, messageKey, aad);
+
+  const newState: RatchetState = {
+    ...state,
+    sendChainKey: nextChainKey,
+    sendCounter: counter + 1,
+  };
+
+  return { ciphertext, nonce, counter, state: newState };
+}
+
+/**
+ * Decrypt a message and advance the receive ratchet.
+ */
+export async function ratchetDecrypt(
+  state: RatchetState,
+  ciphertext: Uint8Array,
+  nonce: Uint8Array,
+  counter: number,
+): Promise<{ plaintext: Uint8Array; state: RatchetState }> {
+  // Replay protection: reject messages with counter <= maxRecvCounter
+  if (counter <= state.maxRecvCounter) {
+    throw new Error(`Replay attack detected: counter ${counter} <= ${state.maxRecvCounter}`);
+  }
+
+  // Prevent DoS via excessively large counter gaps.
+  // Over a WebSocket (TCP-ordered), gaps should never exceed a few messages.
+  const MAX_COUNTER_GAP = 1000;
+  const gap = counter - state.recvCounter;
+  if (gap > MAX_COUNTER_GAP) {
+    throw new Error(`Counter gap too large: ${gap} (max ${MAX_COUNTER_GAP})`);
+  }
+
+  // Advance the recv chain to the correct counter
+  let chainKey = state.recvChainKey;
+  let currentCounter = state.recvCounter;
+  let messageKey: Uint8Array | undefined;
+
+  while (currentCounter <= counter) {
+    const derived = await deriveChainKey(chainKey);
+    if (currentCounter === counter) {
+      messageKey = derived.messageKey;
+    }
+    chainKey = derived.nextChainKey;
+    currentCounter++;
+  }
+
+  if (!messageKey) {
+    throw new Error('Failed to derive message key');
+  }
+
+  const aad = buildAAD(1, counter);
+  const plaintext = await decrypt(ciphertext, nonce, messageKey, aad);
+
+  const newState: RatchetState = {
+    ...state,
+    recvChainKey: chainKey,
+    recvCounter: currentCounter,
+    maxRecvCounter: counter,
+  };
+
+  return { plaintext, state: newState };
+}
+
+/**
+ * Check if key rotation is needed.
+ */
+export function needsKeyRotation(state: RatchetState): boolean {
+  return state.sendCounter > 0 && state.sendCounter % KEY_ROTATION_INTERVAL === 0;
+}
+
+/**
+ * Build AAD bytes: version (1 byte) + type (1 byte) + counter (4 bytes BE)
+ */
+function buildAAD(version: number, counter: number): Uint8Array {
+  const aad = new Uint8Array(6);
+  aad[0] = version;
+  aad[1] = 0x01; // message type
+  aad[2] = (counter >>> 24) & 0xff;
+  aad[3] = (counter >>> 16) & 0xff;
+  aad[4] = (counter >>> 8) & 0xff;
+  aad[5] = counter & 0xff;
+  return aad;
+}

package/src/utils.ts

@@ -0,0 +1,41 @@
+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: Uint8Array,
+  pk2: Uint8Array,
+): Promise<string> {
+  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: Uint8Array): Promise<string> {
+  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: string): Promise<Uint8Array> {
+  const s = await ensureSodium();
+  return s.from_base64(str, s.base64_variants.URLSAFE_NO_PADDING);
+}