cairn-p2p 0.2.0

package/src/crypto/double-ratchet.ts

@@ -0,0 +1,355 @@
+import { CairnError } from '../errors.js';
+import type { CipherSuite } from '../config.js';
+import { X25519Keypair } from './exchange.js';
+import { hkdfSha256 } from './hkdf.js';
+import { aeadEncrypt, aeadDecrypt } from './aead.js';
+
+// Domain separation constants — must match Rust exactly.
+const ROOT_KDF_INFO = new TextEncoder().encode('cairn-root-chain-v1');
+const CHAIN_KDF_INFO = new TextEncoder().encode('cairn-chain-advance-v1');
+const MESSAGE_KEY_KDF_INFO = new TextEncoder().encode('cairn-msg-encrypt-v1');
+
+/** Header sent alongside each Double Ratchet encrypted message. */
+export interface RatchetHeader {
+  /** Sender's current DH ratchet public key (32 bytes). */
+  dhPublic: Uint8Array;
+  /** Number of messages in the previous sending chain. */
+  prevChainLen: number;
+  /** Message number in the current sending chain. */
+  msgNum: number;
+}
+
+/** Configuration for the Double Ratchet. */
+export interface RatchetConfig {
+  /** Maximum number of skipped message keys to cache (default: 100). */
+  maxSkip: number;
+  /** AEAD cipher suite (default: 'aes-256-gcm'). */
+  cipher: CipherSuite;
+}
+
+const DEFAULT_CONFIG: RatchetConfig = {
+  maxSkip: 100,
+  cipher: 'aes-256-gcm',
+};
+
+/** Internal serializable state. */
+interface RatchetState {
+  dhSelfSecret: Uint8Array;
+  dhSelfPublic: Uint8Array;
+  dhRemote: Uint8Array | null;
+  rootKey: Uint8Array;
+  chainKeySend: Uint8Array | null;
+  chainKeyRecv: Uint8Array | null;
+  msgNumSend: number;
+  msgNumRecv: number;
+  prevChainLen: number;
+  skippedKeys: Map<string, Uint8Array>;
+}
+
+/**
+ * Signal Double Ratchet session.
+ *
+ * Combines DH ratcheting (X25519), root chain KDF, and symmetric chain
+ * KDF to provide forward secrecy and break-in recovery for each message.
+ */
+export class DoubleRatchet {
+  private state: RatchetState;
+  private config: RatchetConfig;
+
+  private constructor(state: RatchetState, config: RatchetConfig) {
+    this.state = state;
+    this.config = config;
+  }
+
+  /**
+   * Initialize as the sender (initiator/Alice) after a shared secret
+   * has been established (e.g., from Noise XX handshake).
+   */
+  static initSender(
+    sharedSecret: Uint8Array,
+    remoteDh: Uint8Array,
+    config?: Partial<RatchetConfig>,
+  ): DoubleRatchet {
+    const cfg = { ...DEFAULT_CONFIG, ...config };
+    const dhSelf = X25519Keypair.generate();
+
+    // Perform initial DH ratchet step
+    const dhOutput = dhSelf.diffieHellman(remoteDh);
+    const [rootKey, chainKeySend] = kdfRk(sharedSecret, dhOutput);
+
+    const state: RatchetState = {
+      dhSelfSecret: dhSelf.secretBytes(),
+      dhSelfPublic: dhSelf.publicKeyBytes(),
+      dhRemote: new Uint8Array(remoteDh),
+      rootKey,
+      chainKeySend,
+      chainKeyRecv: null,
+      msgNumSend: 0,
+      msgNumRecv: 0,
+      prevChainLen: 0,
+      skippedKeys: new Map(),
+    };
+
+    return new DoubleRatchet(state, cfg);
+  }
+
+  /**
+   * Initialize as the receiver (responder/Bob) after a shared secret
+   * has been established.
+   */
+  static initReceiver(
+    sharedSecret: Uint8Array,
+    ourKeypair: X25519Keypair,
+    config?: Partial<RatchetConfig>,
+  ): DoubleRatchet {
+    const cfg = { ...DEFAULT_CONFIG, ...config };
+
+    const state: RatchetState = {
+      dhSelfSecret: ourKeypair.secretBytes(),
+      dhSelfPublic: ourKeypair.publicKeyBytes(),
+      dhRemote: null,
+      rootKey: new Uint8Array(sharedSecret),
+      chainKeySend: null,
+      chainKeyRecv: null,
+      msgNumSend: 0,
+      msgNumRecv: 0,
+      prevChainLen: 0,
+      skippedKeys: new Map(),
+    };
+
+    return new DoubleRatchet(state, cfg);
+  }
+
+  /** Encrypt a message. Returns header and ciphertext. */
+  encrypt(plaintext: Uint8Array): { header: RatchetHeader; ciphertext: Uint8Array } {
+    if (!this.state.chainKeySend) {
+      throw new CairnError('CRYPTO', 'no sending chain key established');
+    }
+
+    const [newChainKey, messageKey] = kdfCk(this.state.chainKeySend);
+    this.state.chainKeySend = newChainKey;
+
+    const header: RatchetHeader = {
+      dhPublic: new Uint8Array(this.state.dhSelfPublic),
+      prevChainLen: this.state.prevChainLen,
+      msgNum: this.state.msgNumSend,
+    };
+
+    this.state.msgNumSend++;
+
+    const nonce = deriveNonce(messageKey, header.msgNum);
+    const aad = serializeHeader(header);
+
+    const ciphertext = aeadEncrypt(this.config.cipher, messageKey, nonce, plaintext, aad);
+
+    // Best-effort zero message key
+    messageKey.fill(0);
+
+    return { header, ciphertext };
+  }
+
+  /** Decrypt a message given the header and ciphertext. */
+  decrypt(header: RatchetHeader, ciphertext: Uint8Array): Uint8Array {
+    // Try skipped keys first
+    const skippedId = skippedKeyId(header.dhPublic, header.msgNum);
+    const skippedMk = this.state.skippedKeys.get(skippedId);
+    if (skippedMk) {
+      this.state.skippedKeys.delete(skippedId);
+      return decryptWithKey(this.config.cipher, skippedMk, header, ciphertext);
+    }
+
+    // Check if peer's DH key changed (DH ratchet step needed)
+    const needDhRatchet = this.state.dhRemote === null ||
+      !bytesEqual(this.state.dhRemote, header.dhPublic);
+
+    if (needDhRatchet) {
+      this.skipMessageKeys(header.prevChainLen);
+      this.dhRatchet(header.dhPublic);
+    }
+
+    // Skip ahead in the current receiving chain if needed
+    this.skipMessageKeys(header.msgNum);
+
+    // Derive the message key from the receiving chain
+    if (!this.state.chainKeyRecv) {
+      throw new CairnError('CRYPTO', 'no receiving chain key established');
+    }
+    const [newChainKey, messageKey] = kdfCk(this.state.chainKeyRecv);
+    this.state.chainKeyRecv = newChainKey;
+    this.state.msgNumRecv++;
+
+    const result = decryptWithKey(this.config.cipher, messageKey, header, ciphertext);
+    messageKey.fill(0);
+    return result;
+  }
+
+  /** Export the ratchet state for persistence. */
+  exportState(): Uint8Array {
+    const skippedEntries: Array<[string, number[]]> = [];
+    for (const [key, value] of this.state.skippedKeys) {
+      skippedEntries.push([key, Array.from(value)]);
+    }
+
+    const obj = {
+      dhSelfSecret: Array.from(this.state.dhSelfSecret),
+      dhSelfPublic: Array.from(this.state.dhSelfPublic),
+      dhRemote: this.state.dhRemote ? Array.from(this.state.dhRemote) : null,
+      rootKey: Array.from(this.state.rootKey),
+      chainKeySend: this.state.chainKeySend ? Array.from(this.state.chainKeySend) : null,
+      chainKeyRecv: this.state.chainKeyRecv ? Array.from(this.state.chainKeyRecv) : null,
+      msgNumSend: this.state.msgNumSend,
+      msgNumRecv: this.state.msgNumRecv,
+      prevChainLen: this.state.prevChainLen,
+      skippedKeys: skippedEntries,
+    };
+
+    return new TextEncoder().encode(JSON.stringify(obj));
+  }
+
+  /** Import ratchet state from persisted bytes. */
+  static importState(data: Uint8Array, config?: Partial<RatchetConfig>): DoubleRatchet {
+    const cfg = { ...DEFAULT_CONFIG, ...config };
+    try {
+      const json = new TextDecoder().decode(data);
+      const obj = JSON.parse(json);
+
+      const skippedKeys = new Map<string, Uint8Array>();
+      if (obj.skippedKeys) {
+        for (const [key, value] of obj.skippedKeys) {
+          skippedKeys.set(key, new Uint8Array(value));
+        }
+      }
+
+      const state: RatchetState = {
+        dhSelfSecret: new Uint8Array(obj.dhSelfSecret),
+        dhSelfPublic: new Uint8Array(obj.dhSelfPublic),
+        dhRemote: obj.dhRemote ? new Uint8Array(obj.dhRemote) : null,
+        rootKey: new Uint8Array(obj.rootKey),
+        chainKeySend: obj.chainKeySend ? new Uint8Array(obj.chainKeySend) : null,
+        chainKeyRecv: obj.chainKeyRecv ? new Uint8Array(obj.chainKeyRecv) : null,
+        msgNumSend: obj.msgNumSend,
+        msgNumRecv: obj.msgNumRecv,
+        prevChainLen: obj.prevChainLen,
+        skippedKeys,
+      };
+
+      return new DoubleRatchet(state, cfg);
+    } catch (e) {
+      if (e instanceof CairnError) throw e;
+      throw new CairnError('CRYPTO', `ratchet state deserialization: ${e}`);
+    }
+  }
+
+  /** Skip message keys up to (but not including) the given message number. */
+  private skipMessageKeys(until: number): void {
+    if (!this.state.chainKeyRecv) return;
+
+    const toSkip = until - this.state.msgNumRecv;
+    if (toSkip <= 0) return;
+    if (toSkip > this.config.maxSkip) {
+      throw new CairnError('CRYPTO', 'max skip threshold exceeded');
+    }
+
+    let ck = this.state.chainKeyRecv;
+    for (let i = this.state.msgNumRecv; i < until; i++) {
+      const [newCk, mk] = kdfCk(ck);
+      if (!this.state.dhRemote) {
+        throw new CairnError('CRYPTO', 'no remote DH key for skipping');
+      }
+      const id = skippedKeyId(this.state.dhRemote, i);
+      this.state.skippedKeys.set(id, mk);
+      ck = newCk;
+      this.state.msgNumRecv++;
+    }
+    this.state.chainKeyRecv = ck;
+  }
+
+  /** Perform a DH ratchet step when the peer's public key changes. */
+  private dhRatchet(newRemotePublic: Uint8Array): void {
+    this.state.prevChainLen = this.state.msgNumSend;
+    this.state.msgNumSend = 0;
+    this.state.msgNumRecv = 0;
+    this.state.dhRemote = new Uint8Array(newRemotePublic);
+
+    // Derive receiving chain key from current DH keypair + new remote key
+    const dhSelf = X25519Keypair.fromBytes(this.state.dhSelfSecret);
+    const dhOutput = dhSelf.diffieHellman(newRemotePublic);
+    const [rootKey1, chainKeyRecv] = kdfRk(this.state.rootKey, dhOutput);
+    this.state.rootKey = rootKey1;
+    this.state.chainKeyRecv = chainKeyRecv;
+
+    // Generate new DH keypair and derive sending chain key
+    const newDhSelf = X25519Keypair.generate();
+    this.state.dhSelfSecret = newDhSelf.secretBytes();
+    this.state.dhSelfPublic = newDhSelf.publicKeyBytes();
+
+    const dhOutput2 = newDhSelf.diffieHellman(newRemotePublic);
+    const [rootKey2, chainKeySend] = kdfRk(this.state.rootKey, dhOutput2);
+    this.state.rootKey = rootKey2;
+    this.state.chainKeySend = chainKeySend;
+  }
+}
+
+/** Derive new root key and chain key from DH output. */
+function kdfRk(rootKey: Uint8Array, dhOutput: Uint8Array): [Uint8Array, Uint8Array] {
+  const output = hkdfSha256(dhOutput, rootKey, ROOT_KDF_INFO, 64);
+  return [output.slice(0, 32), output.slice(32, 64)];
+}
+
+/** Derive message key from chain key and advance the chain. */
+function kdfCk(chainKey: Uint8Array): [Uint8Array, Uint8Array] {
+  const newCk = hkdfSha256(chainKey, undefined, CHAIN_KDF_INFO, 32);
+  const mk = hkdfSha256(chainKey, undefined, MESSAGE_KEY_KDF_INFO, 32);
+  return [newCk, mk];
+}
+
+/** Derive a 12-byte nonce from a message key and message number. */
+function deriveNonce(messageKey: Uint8Array, msgNum: number): Uint8Array {
+  const nonce = new Uint8Array(12);
+  // First 8 bytes from message key, last 4 from message number (big-endian)
+  nonce.set(messageKey.slice(0, 8), 0);
+  const view = new DataView(nonce.buffer, nonce.byteOffset, nonce.byteLength);
+  view.setUint32(8, msgNum);
+  return nonce;
+}
+
+/** Serialize a RatchetHeader as JSON for AEAD AAD. */
+function serializeHeader(header: RatchetHeader): Uint8Array {
+  const obj = {
+    dh_public: Array.from(header.dhPublic),
+    prev_chain_len: header.prevChainLen,
+    msg_num: header.msgNum,
+  };
+  return new TextEncoder().encode(JSON.stringify(obj));
+}
+
+/** Decrypt ciphertext with a specific message key. */
+function decryptWithKey(
+  cipher: CipherSuite,
+  messageKey: Uint8Array,
+  header: RatchetHeader,
+  ciphertext: Uint8Array,
+): Uint8Array {
+  const nonce = deriveNonce(messageKey, header.msgNum);
+  const aad = serializeHeader(header);
+  return aeadDecrypt(cipher, messageKey, nonce, ciphertext, aad);
+}
+
+/** Create a skipped key ID string from DH public key and message number. */
+function skippedKeyId(dhPublic: Uint8Array, msgNum: number): string {
+  return bytesToHex(dhPublic) + ':' + msgNum;
+}
+
+/** Convert bytes to hex string. */
+function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+/** Compare two Uint8Arrays for equality. */
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}

package/src/crypto/exchange.ts

@@ -0,0 +1,51 @@
+import { x25519 } from '@noble/curves/ed25519';
+import { CairnError } from '../errors.js';
+
+/**
+ * An X25519 keypair for Diffie-Hellman key exchange.
+ */
+export class X25519Keypair {
+  private readonly secret: Uint8Array;
+  private readonly pubKey: Uint8Array;
+
+  private constructor(secret: Uint8Array, pubKey: Uint8Array) {
+    this.secret = secret;
+    this.pubKey = pubKey;
+  }
+
+  /** Generate a new random X25519 keypair. */
+  static generate(): X25519Keypair {
+    const secret = x25519.utils.randomSecretKey();
+    const pubKey = x25519.getPublicKey(secret);
+    return new X25519Keypair(secret, pubKey);
+  }
+
+  /** Restore from a 32-byte secret key. */
+  static fromBytes(secret: Uint8Array): X25519Keypair {
+    if (secret.length !== 32) {
+      throw new CairnError('CRYPTO', 'X25519 secret key must be 32 bytes');
+    }
+    const copy = new Uint8Array(secret);
+    const pubKey = x25519.getPublicKey(copy);
+    return new X25519Keypair(copy, pubKey);
+  }
+
+  /** Get the 32-byte public key. */
+  publicKeyBytes(): Uint8Array {
+    return new Uint8Array(this.pubKey);
+  }
+
+  /** Export the 32-byte secret key. */
+  secretBytes(): Uint8Array {
+    return new Uint8Array(this.secret);
+  }
+
+  /** Perform Diffie-Hellman key exchange with a peer's public key. Returns 32-byte shared secret. */
+  diffieHellman(peerPublic: Uint8Array): Uint8Array {
+    try {
+      return x25519.getSharedSecret(this.secret, peerPublic);
+    } catch (e) {
+      throw new CairnError('CRYPTO', `X25519 DH error: ${e}`);
+    }
+  }
+}

package/src/crypto/hkdf.ts

@@ -0,0 +1,33 @@
+import { hkdf } from '@noble/hashes/hkdf';
+import { sha256 } from '@noble/hashes/sha256';
+import { CairnError } from '../errors.js';
+
+// Domain separation info strings for HKDF derivations.
+// Must match Rust constants exactly.
+const encoder = new TextEncoder();
+export const HKDF_INFO_SESSION_KEY = encoder.encode('cairn-session-key-v1');
+export const HKDF_INFO_RENDEZVOUS = encoder.encode('cairn-rendezvous-id-v1');
+export const HKDF_INFO_SAS = encoder.encode('cairn-sas-derivation-v1');
+export const HKDF_INFO_CHAIN_KEY = encoder.encode('cairn-chain-key-v1');
+export const HKDF_INFO_MESSAGE_KEY = encoder.encode('cairn-message-key-v1');
+
+/**
+ * Derive key material from input keying material using HKDF-SHA256 (RFC 5869).
+ *
+ * @param ikm - input keying material (e.g., DH shared secret)
+ * @param salt - optional salt (undefined uses zero-filled salt)
+ * @param info - context-specific info string for domain separation
+ * @param length - number of bytes to derive
+ */
+export function hkdfSha256(
+  ikm: Uint8Array,
+  salt: Uint8Array | undefined,
+  info: Uint8Array,
+  length: number,
+): Uint8Array {
+  try {
+    return hkdf(sha256, ikm, salt, info, length);
+  } catch (e) {
+    throw new CairnError('CRYPTO', `HKDF-SHA256 error: ${e}`);
+  }
+}

package/src/crypto/identity.ts

@@ -0,0 +1,84 @@
+import * as ed from '@noble/ed25519';
+import { sha256 } from '@noble/hashes/sha256';
+import { CairnError } from '../errors.js';
+
+/**
+ * An Ed25519 identity keypair used for signing and peer identification.
+ */
+export class IdentityKeypair {
+  private readonly secret: Uint8Array;
+  private readonly pubKey: Uint8Array;
+
+  private constructor(secret: Uint8Array, pubKey: Uint8Array) {
+    this.secret = secret;
+    this.pubKey = pubKey;
+  }
+
+  /** Generate a new random Ed25519 identity keypair. */
+  static async generate(): Promise<IdentityKeypair> {
+    const secret = ed.utils.randomPrivateKey();
+    const pubKey = await ed.getPublicKeyAsync(secret);
+    return new IdentityKeypair(secret, pubKey);
+  }
+
+  /** Restore from a 32-byte secret key seed. */
+  static async fromBytes(secret: Uint8Array): Promise<IdentityKeypair> {
+    if (secret.length !== 32) {
+      throw new CairnError('CRYPTO', 'Ed25519 secret key must be 32 bytes');
+    }
+    const copy = new Uint8Array(secret);
+    const pubKey = await ed.getPublicKeyAsync(copy);
+    return new IdentityKeypair(copy, pubKey);
+  }
+
+  /** Export the 32-byte secret key seed. */
+  secretBytes(): Uint8Array {
+    return new Uint8Array(this.secret);
+  }
+
+  /** Get the 32-byte public key. */
+  publicKey(): Uint8Array {
+    return new Uint8Array(this.pubKey);
+  }
+
+  /** Derive the Peer ID: SHA-256 hash of the Ed25519 public key bytes (32 bytes). */
+  peerId(): Uint8Array {
+    return peerIdFromPublicKey(this.pubKey);
+  }
+
+  /** Sign a message. Returns 64-byte signature. */
+  async sign(message: Uint8Array): Promise<Uint8Array> {
+    try {
+      return await ed.signAsync(message, this.secret);
+    } catch (e) {
+      throw new CairnError('CRYPTO', `Ed25519 sign error: ${e}`);
+    }
+  }
+
+  /** Verify a signature against this keypair's public key. Throws on failure. */
+  async verify(message: Uint8Array, signature: Uint8Array): Promise<void> {
+    return verifySignature(this.pubKey, message, signature);
+  }
+}
+
+/** Derive Peer ID from a public key (without needing the private key). */
+export function peerIdFromPublicKey(publicKey: Uint8Array): Uint8Array {
+  return sha256(publicKey);
+}
+
+/** Verify a signature against an arbitrary public key. Throws on failure. */
+export async function verifySignature(
+  publicKey: Uint8Array,
+  message: Uint8Array,
+  signature: Uint8Array,
+): Promise<void> {
+  try {
+    const valid = await ed.verifyAsync(signature, message, publicKey);
+    if (!valid) {
+      throw new CairnError('CRYPTO', 'Ed25519 signature verification failed');
+    }
+  } catch (e) {
+    if (e instanceof CairnError) throw e;
+    throw new CairnError('CRYPTO', `Ed25519 verify error: ${e}`);
+  }
+}

package/src/crypto/index.ts

@@ -0,0 +1,20 @@
+// Crypto module — Ed25519, X25519, HKDF, AEAD, Noise XX, SPAKE2, SAS, Double Ratchet (tasks 030-032)
+
+export { IdentityKeypair, peerIdFromPublicKey, verifySignature } from './identity.js';
+export { X25519Keypair } from './exchange.js';
+export {
+  hkdfSha256,
+  HKDF_INFO_SESSION_KEY,
+  HKDF_INFO_RENDEZVOUS,
+  HKDF_INFO_SAS,
+  HKDF_INFO_CHAIN_KEY,
+  HKDF_INFO_MESSAGE_KEY,
+} from './hkdf.js';
+export { aeadEncrypt, aeadDecrypt, NONCE_SIZE, KEY_SIZE, TAG_SIZE } from './aead.js';
+export type { Role, HandshakeResult, StepOutput } from './noise.js';
+export { NoiseXXHandshake } from './noise.js';
+export { deriveNumericSas, deriveEmojiSas, EMOJI_TABLE } from './sas.js';
+export type { Spake2Role } from './spake2.js';
+export { Spake2 } from './spake2.js';
+export type { RatchetHeader, RatchetConfig } from './double-ratchet.js';
+export { DoubleRatchet } from './double-ratchet.js';