@stvor/sdk 2.4.0 → 3.0.0

package/dist/ratchet/index.js

@@ -1,318 +1,343 @@
-import sodium from 'libsodium-wrappers';
-import { ensureSodiumReady } from '../facade/sodium-singleton.js';
-// Initialize libsodium (safe to call multiple times)
-export async function initializeCrypto() {
-    await ensureSodiumReady();
-}
 /**
- * X3DH Session Establishment
- * @param identityKeyPair - The user's identity key pair
- * @param signedPreKeyPair - The user's signed pre-key pair
- * @param oneTimePreKey - A one-time pre-key
- * @param recipientIdentityKey - The recipient's identity key
- * @param recipientSignedPreKey - The recipient's signed pre-key
- * @param recipientOneTimePreKey - The recipient's one-time pre-key
- * @param recipientSPKSignature - Signature of SPK by recipient's identity key
- * @param protocolVersion - The protocol version
- * @param cipherSuite - The cipher suite
- * @returns SessionState
+ * X3DH + Double Ratchet Implementation
+ * Uses ONLY Node.js built-in crypto module — zero external dependencies
+ *
+ * Implements the Signal Protocol Double Ratchet with deferred initialization:
+ *   - First send  → "initiator" DH ratchet (DH with peer's SPK)
+ *   - First receive → "responder" DH ratchet (use own SPK, then fresh key)
+ * This allows either side to send first after symmetric X3DH key agreement.
+ *
+ * Provides:
+ *   - X3DH key agreement (symmetric variant, both sides derive same SK)
+ *   - Double Ratchet with DH ratchet + symmetric-key ratchet
+ *   - AES-256-GCM AEAD encryption with header as AAD
+ *   - ECDSA P-256 signing / verification
+ *   - HKDF-SHA256 key derivation
+ *   - HMAC-based chain-key ratchet (Signal-style)
  */
-export function establishSession(identityKeyPair, signedPreKeyPair, oneTimePreKey, recipientIdentityKey, recipientSignedPreKey, recipientOneTimePreKey, recipientSPKSignature, protocolVersion, cipherSuite) {
-    // Validate protocol version and cipher suite
-    validateProtocolVersion(protocolVersion);
-    validateCipherSuite(cipherSuite);
-    // Verify SPK signature
-    verifySPKSignature(recipientSignedPreKey, recipientSPKSignature, recipientIdentityKey);
-    // Derive shared secret with cryptographic binding
-    const sharedSecret = deriveSharedSecret(identityKeyPair.publicKey, recipientSignedPreKey, recipientOneTimePreKey, protocolVersion, cipherSuite);
-    if (!sharedSecret) {
-        throw new Error('Failed to derive shared secret');
-    }
-    // Derive root key
-    const rootKey = deriveKey(sharedSecret, 'x3dh-root-key', sodium.from_string(protocolVersion));
+import crypto from 'crypto';
+/* ================================================================
+ * Constants
+ * ================================================================ */
+const CURVE = 'prime256v1';
+const PUB_LEN = 65; // uncompressed P-256 public key
+const HEADER_LEN = 85; // 65 + 4 + 4 + 12
+const MAX_SKIP = 256;
+/* ================================================================
+ * Init (no-op — Node.js crypto is always ready)
+ * ================================================================ */
+export async function initializeCrypto() { }
+/* ================================================================
+ * Key generation
+ * ================================================================ */
+export function generateKeyPair() {
+    const ecdh = crypto.createECDH(CURVE);
+    ecdh.generateKeys();
     return {
-        identityKey: identityKeyPair.publicKey,
-        signedPreKey: signedPreKeyPair.publicKey,
-        oneTimePreKey,
-        rootKey,
-        sendingChainKey: rootKey,
-        receivingChainKey: rootKey,
-        skippedMessageKeys: new Map(),
-        isPostCompromise: false,
+        publicKey: Buffer.from(ecdh.getPublicKey()),
+        privateKey: Buffer.from(ecdh.getPrivateKey()),
     };
 }
-/**
- * Double Ratchet Encryption
- * @param plaintext - The message to encrypt
- * @param session - The current session state
- * @returns { ciphertext: Uint8Array; header: { publicKey: Uint8Array; nonce: Uint8Array } }
- */
-export function encryptMessage(plaintext, session) {
-    // Generate a new ratchet key pair
-    const ratchetKeyPair = sodium.crypto_kx_keypair();
-    // Perform a Diffie-Hellman exchange with the recipient's public key
-    const sharedSecret = sodium.crypto_kx_client_session_keys(ratchetKeyPair.publicKey, ratchetKeyPair.privateKey, session.identityKey);
-    // Update root key and derive new sending chain key
-    const newRootKey = sodium.crypto_generichash(32, new Uint8Array([...session.rootKey, ...sharedSecret.sharedTx]));
-    const newSendingChainKey = sodium.crypto_generichash(32, newRootKey);
-    // Derive a message key
-    const messageKey = sodium.crypto_generichash(32, newSendingChainKey);
-    // Encrypt the message
-    const nonce = sodium.randombytes_buf(sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
-    const ciphertext = sodium.crypto_aead_xchacha20poly1305_ietf_encrypt(sodium.from_string(plaintext), null, // No additional data
-    null, nonce, messageKey);
-    // Update session state
-    session.rootKey = newRootKey;
-    session.sendingChainKey = newSendingChainKey;
-    return {
-        ciphertext,
-        header: {
-            publicKey: ratchetKeyPair.publicKey,
-            nonce,
-        },
-    };
+/* ================================================================
+ * Low-level crypto helpers
+ * ================================================================ */
+/** ECDH shared secret */
+function ecdhSecret(priv, pub) {
+    const ecdh = crypto.createECDH(CURVE);
+    ecdh.setPrivateKey(priv);
+    return Buffer.from(ecdh.computeSecret(pub));
 }
-/**
- * Double Ratchet Decryption
- * @param ciphertext - The encrypted message
- * @param header - The message header containing the sender's public key and nonce
- * @param session - The current session state
- * @returns The decrypted plaintext
- */
-export function decryptMessage(ciphertext, header, session) {
-    // Check for skipped message keys
-    const skippedKey = session.skippedMessageKeys.get(header.nonce.toString());
-    if (skippedKey) {
-        session.skippedMessageKeys.delete(header.nonce.toString());
-        const plaintext = sodium.crypto_aead_xchacha20poly1305_ietf_decrypt(null, ciphertext, null, // No additional data
-        header.nonce, skippedKey);
-        return sodium.to_string(plaintext);
-    }
-    // Perform a Diffie-Hellman exchange with the sender's public key
-    const sharedSecret = sodium.crypto_kx_client_session_keys(session.identityKey, session.signedPreKey, header.publicKey);
-    // Update root key and derive new receiving chain key
-    const newRootKey = sodium.crypto_generichash(32, new Uint8Array([...session.rootKey, ...sharedSecret.sharedTx]));
-    const newReceivingChainKey = sodium.crypto_generichash(32, newRootKey);
-    // Derive the message key
-    const messageKey = sodium.crypto_generichash(32, newReceivingChainKey);
-    // Decrypt the message
-    const plaintext = sodium.crypto_aead_xchacha20poly1305_ietf_decrypt(null, ciphertext, null, // No additional data
-    header.nonce, messageKey);
-    // Update session state
-    session.rootKey = newRootKey;
-    session.receivingChainKey = newReceivingChainKey;
-    return sodium.to_string(plaintext);
-}
-// Enhanced KDF with explicit domain separation and transcript binding
-function deriveKey(inputKey, context, transcript) {
-    const label = sodium.from_string(context);
-    return sodium.crypto_generichash(32, new Uint8Array([...label, ...inputKey, ...transcript]));
+/** HKDF-SHA256 */
+function hkdf(ikm, salt, info, len) {
+    return Buffer.from(crypto.hkdfSync('sha256', ikm, salt, info, len));
 }
-function hkdfExtract(salt, inputKeyMaterial) {
-    return sodium.crypto_generichash(32, new Uint8Array([...salt, ...inputKeyMaterial]));
-}
-function hkdfExpand(prk, info, length) {
-    const infoBytes = sodium.from_string(info);
-    return sodium.crypto_generichash(length, new Uint8Array([...prk, ...infoBytes]));
-}
-function deriveRootKey(oldRootKey, dhOutput, transcript) {
-    const salt = deriveKey(oldRootKey, 'DR:dh', transcript);
-    const prk = hkdfExtract(salt, dhOutput);
-    return hkdfExpand(prk, 'DR:root', 32);
+/** Root-key KDF → new rootKey + chainKey */
+function kdfRK(rk, dhOut) {
+    const d = hkdf(dhOut, rk, 'stvor-rk', 64);
+    return {
+        rootKey: Buffer.from(d.subarray(0, 32)),
+        chainKey: Buffer.from(d.subarray(32, 64)),
+    };
 }
-function deriveChainKey(rootKey, transcript) {
-    const prk = hkdfExtract(rootKey, sodium.from_string('DR:chain'));
-    return hkdfExpand(prk, 'DR:chain', 32);
+/** Chain-key KDF → new chainKey + messageKey */
+function kdfCK(ck) {
+    return {
+        chainKey: Buffer.from(crypto.createHmac('sha256', ck).update('\x01').digest()),
+        messageKey: Buffer.from(crypto.createHmac('sha256', ck).update('\x02').digest()),
+    };
 }
-function deriveMessageKey(chainKey, transcript) {
-    const prk = hkdfExtract(chainKey, sodium.from_string('DR:message'));
-    return hkdfExpand(prk, 'DR:message', 32);
+/** AES-256-GCM encrypt with AAD */
+function aeadEnc(key, pt, nonce, aad) {
+    const c = crypto.createCipheriv('aes-256-gcm', key, nonce);
+    c.setAAD(aad);
+    const enc = Buffer.concat([c.update(pt), c.final()]);
+    return Buffer.concat([enc, c.getAuthTag()]); // ciphertext ‖ 16-byte tag
 }
-// Updated skipped keys handling with bounds
-const MAX_SKIPPED_KEYS = 50; // Limit to prevent DoS
-// Enhanced skipped keys handling with state exhaustion protection
-const MAX_TOTAL_SKIPPED_KEYS = 500; // Global limit across sessions
-let totalSkippedKeys = 0;
-export function addSkippedKey(session, header, messageKey) {
-    const keyId = `${header.publicKey.toString()}:${header.nonce.toString()}`;
-    if (session.skippedMessageKeys.size >= MAX_SKIPPED_KEYS) {
-        throw new Error('Skipped keys limit exceeded for session');
-    }
-    if (totalSkippedKeys >= MAX_TOTAL_SKIPPED_KEYS) {
-        throw new Error('Global skipped keys limit exceeded');
-    }
-    session.skippedMessageKeys.set(keyId, messageKey);
-    totalSkippedKeys++;
+/** AES-256-GCM decrypt with AAD */
+function aeadDec(key, ct, nonce, aad) {
+    const d = crypto.createDecipheriv('aes-256-gcm', key, nonce);
+    d.setAAD(aad);
+    d.setAuthTag(ct.subarray(-16));
+    return Buffer.concat([d.update(ct.subarray(0, -16)), d.final()]);
 }
-export function removeSkippedKey(session, header) {
-    const keyId = `${header.publicKey.toString()}:${header.nonce.toString()}`;
-    if (session.skippedMessageKeys.delete(keyId)) {
-        totalSkippedKeys--;
-    }
+/* ================================================================
+ * ECDSA P-256  — sign / verify
+ * ================================================================ */
+function toPrivKeyObj(pub, priv) {
+    return crypto.createPrivateKey({
+        key: {
+            kty: 'EC', crv: 'P-256',
+            x: pub.subarray(1, 33).toString('base64url'),
+            y: pub.subarray(33, 65).toString('base64url'),
+            d: priv.toString('base64url'),
+        },
+        format: 'jwk',
+    });
 }
-// Improved skipped keys eviction policy
-function cleanUpSkippedKeys(session) {
-    const currentTime = Date.now();
-    session.skippedMessageKeys.forEach((_, keyId) => {
-        const [timestamp] = keyId.split(':');
-        if (currentTime - parseInt(timestamp, 10) > 300000) { // Evict keys older than 5 minutes
-            session.skippedMessageKeys.delete(keyId);
-            totalSkippedKeys--;
-        }
+function toPubKeyObj(pub) {
+    return crypto.createPublicKey({
+        key: {
+            kty: 'EC', crv: 'P-256',
+            x: pub.subarray(1, 33).toString('base64url'),
+            y: pub.subarray(33, 65).toString('base64url'),
+        },
+        format: 'jwk',
     });
 }
-export function processSkippedKeys(session) {
-    cleanUpSkippedKeys(session);
+/** ECDSA-P256-SHA256 sign */
+export function ecSign(data, kp) {
+    return Buffer.from(crypto.sign('sha256', data, toPrivKeyObj(kp.publicKey, kp.privateKey)));
 }
-// Updated simultaneous send handling
-export function handleSimultaneousSend(session, isInitiator) {
-    if (isInitiator) {
-        // Initiator ratchets forward
-        session.sendingChainKey = deriveChainKey(session.sendingChainKey, sodium.from_string('initiator'));
-    }
-    else {
-        // Responder ratchets forward
-        session.receivingChainKey = deriveChainKey(session.receivingChainKey, sodium.from_string('responder'));
-    }
+/** ECDSA-P256-SHA256 verify */
+export function ecVerify(data, sig, pub) {
+    return crypto.verify('sha256', data, toPubKeyObj(pub), sig);
 }
-// Updated SPK signature verification with downgrade protection
-function verifySPKSignature(spk, spkSignature, identityKey) {
-    const isValid = sodium.crypto_sign_verify_detached(spkSignature, spk, identityKey);
-    if (!isValid) {
-        throw new Error('Invalid SPK signature');
-    }
+/* ================================================================
+ * X3DH — Symmetric Variant
+ *
+ * Both sides independently derive the SAME shared secret from
+ * their own (IK, SPK) and the peer's (IK, SPK).
+ * Canonical ordering by comparing IK public keys.
+ * ================================================================ */
+export function x3dhSymmetric(myIK, mySPK, peerIK, peerSPK) {
+    const iAmLower = Buffer.compare(myIK.publicKey, peerIK) < 0;
+    const d1 = iAmLower
+        ? ecdhSecret(myIK.privateKey, peerSPK)
+        : ecdhSecret(mySPK.privateKey, peerIK);
+    const d2 = iAmLower
+        ? ecdhSecret(mySPK.privateKey, peerIK)
+        : ecdhSecret(myIK.privateKey, peerSPK);
+    const d3 = ecdhSecret(mySPK.privateKey, peerSPK);
+    return hkdf(Buffer.concat([d1, d2, d3]), Buffer.alloc(32), 'X3DH', 32);
 }
-// Updated OPK exhaustion handling
-const OPK_POOL_SIZE = 100; // Example pool size
-let opkPool = [];
-export function generateOPKPool() {
-    opkPool = Array.from({ length: OPK_POOL_SIZE }, () => sodium.crypto_kx_keypair().publicKey);
+/* ================================================================
+ * Session Establishment
+ *
+ * Creates a "pending" session.  The first send triggers an
+ * initiator DH ratchet; the first receive triggers a responder
+ * DH ratchet.  Either side can go first.
+ * ================================================================ */
+export function establishSession(myIK, mySPK, peerIK, peerSPK) {
+    const sk = x3dhSymmetric(myIK, mySPK, peerIK, peerSPK);
+    const ratchetKP = generateKeyPair();
+    return {
+        myIdentityPublicKey: Buffer.from(myIK.publicKey),
+        peerIdentityPublicKey: Buffer.from(peerIK),
+        rootKey: sk, // raw shared secret
+        sendingChainKey: Buffer.alloc(32), // set by first DH ratchet
+        receivingChainKey: Buffer.alloc(32),
+        myRatchetKeyPair: ratchetKP,
+        theirRatchetPublicKey: null,
+        sendCount: 0,
+        recvCount: 0,
+        prevSendCount: 0,
+        skippedKeys: new Map(),
+        isPostCompromise: false,
+        /* deferred init data */
+        peerSPK: Buffer.from(peerSPK),
+        mySPKPair: {
+            publicKey: Buffer.from(mySPK.publicKey),
+            privateKey: Buffer.from(mySPK.privateKey),
+        },
+        /* legacy compat */
+        identityKey: myIK.publicKey,
+        signedPreKey: mySPK.publicKey,
+        oneTimePreKey: new Uint8Array(0),
+        sendingChainMessageNumber: 0,
+        receivingChainMessageNumber: 0,
+        previousSendingChainLength: 0,
+    };
 }
-// Improved X3DH race safety and OPK handling
-const OPK_LOCK = new Map(); // Lock for atomic OPK consumption
-export function consumeOPKAtomically(userId) {
-    if (OPK_LOCK.get(userId)) {
-        throw new Error('OPK consumption in progress');
-    }
-    OPK_LOCK.set(userId, true);
-    try {
-        const opk = consumeOPK();
-        return opk;
+/* ================================================================
+ * Double Ratchet — Encrypt
+ *
+ * Header layout (85 bytes):
+ *  [0..64]   ratchet public key   (65 B)
+ *  [65..68]  prev sending chain length  (u32 BE)
+ *  [69..72]  message number             (u32 BE)
+ *  [73..84]  AES-GCM nonce              (12 B)
+ * ================================================================ */
+export function encryptMessage(session, plaintext) {
+    /* ---- Deferred init: initiator DH ratchet on first send ---- */
+    if (!session.theirRatchetPublicKey && session.peerSPK) {
+        const dhOut = ecdhSecret(session.myRatchetKeyPair.privateKey, session.peerSPK);
+        const r = kdfRK(session.rootKey, dhOut);
+        session.rootKey = r.rootKey;
+        session.sendingChainKey = r.chainKey;
+        session.theirRatchetPublicKey = Buffer.from(session.peerSPK);
+        session.peerSPK = null; // consumed
+        session.mySPKPair = null;
     }
-    finally {
-        OPK_LOCK.delete(userId);
+    /* ---- Symmetric ratchet ---- */
+    const { chainKey, messageKey } = kdfCK(session.sendingChainKey);
+    session.sendingChainKey = chainKey;
+    const nonce = crypto.randomBytes(12);
+    const header = Buffer.alloc(HEADER_LEN);
+    session.myRatchetKeyPair.publicKey.copy(header, 0);
+    header.writeUInt32BE(session.prevSendCount, PUB_LEN);
+    header.writeUInt32BE(session.sendCount, PUB_LEN + 4);
+    nonce.copy(header, PUB_LEN + 8);
+    const ct = aeadEnc(messageKey, plaintext, nonce, header);
+    session.sendCount++;
+    session.sendingChainMessageNumber = session.sendCount;
+    return { ciphertext: ct, header };
+}
+/* ================================================================
+ * Double Ratchet — Decrypt
+ * ================================================================ */
+function skipKeys(s, until) {
+    if (until - s.recvCount > MAX_SKIP)
+        throw new Error('Too many skipped messages');
+    while (s.recvCount < until) {
+        const { chainKey, messageKey } = kdfCK(s.receivingChainKey);
+        s.receivingChainKey = chainKey;
+        s.skippedKeys.set(`${s.theirRatchetPublicKey.toString('hex')}:${s.recvCount}`, messageKey);
+        s.recvCount++;
     }
 }
-// Enhanced X3DH with cryptographic binding and explicit abort semantics
-function deriveSharedSecret(ik, spk, opk, protocolVersion, cipherSuite) {
-    const context = sodium.from_string(`${protocolVersion}:${cipherSuite}`);
-    return sodium.crypto_generichash(32, new Uint8Array([...ik, ...spk, ...opk, ...context]));
+function dhRatchetStep(s, theirNewKey) {
+    s.prevSendCount = s.sendCount;
+    s.sendCount = 0;
+    s.recvCount = 0;
+    s.theirRatchetPublicKey = Buffer.from(theirNewKey);
+    // Derive receiving chain
+    const dh1 = ecdhSecret(s.myRatchetKeyPair.privateKey, theirNewKey);
+    const r1 = kdfRK(s.rootKey, dh1);
+    s.rootKey = r1.rootKey;
+    s.receivingChainKey = r1.chainKey;
+    // New ratchet key pair → derive sending chain
+    s.myRatchetKeyPair = generateKeyPair();
+    const dh2 = ecdhSecret(s.myRatchetKeyPair.privateKey, theirNewKey);
+    const r2 = kdfRK(s.rootKey, dh2);
+    s.rootKey = r2.rootKey;
+    s.sendingChainKey = r2.chainKey;
 }
-// Final improvements for X3DH
-function validateProtocolVersion(version) {
-    const supportedVersions = ['1.0'];
-    if (!supportedVersions.includes(version)) {
-        throw new Error(`Unsupported protocol version: ${version}`);
+export function decryptMessage(session, ciphertext, header) {
+    const theirPub = header.subarray(0, PUB_LEN);
+    const prevChain = header.readUInt32BE(PUB_LEN);
+    const msgNum = header.readUInt32BE(PUB_LEN + 4);
+    const nonce = header.subarray(PUB_LEN + 8, HEADER_LEN);
+    /* ---- Deferred init: responder role on first receive ---- */
+    if (!session.theirRatchetPublicKey && session.mySPKPair) {
+        // Use our SPK as ratchet key for the first DH step
+        // so DH(mySPK, theirRatchetKey) matches initiator's DH(theirRatchetKey, mySPK)
+        session.myRatchetKeyPair = session.mySPKPair;
+        session.mySPKPair = null; // consumed
+        session.peerSPK = null;
     }
-}
-function validateCipherSuite(cipherSuite) {
-    const supportedSuites = ['AES-GCM'];
-    if (!supportedSuites.includes(cipherSuite)) {
-        throw new Error(`Unsupported cipher suite: ${cipherSuite}`);
+    // 1. Try skipped key
+    const skId = `${theirPub.toString('hex')}:${msgNum}`;
+    const skMK = session.skippedKeys.get(skId);
+    if (skMK) {
+        session.skippedKeys.delete(skId);
+        return aeadDec(skMK, ciphertext, nonce, header);
     }
-}
-/**
- * Policy for forced DH rotation.
- * Triggers a DH ratchet step based on:
- * - Number of messages sent.
- * - Time elapsed since the last ratchet.
- * - Explicit compromise flag.
- */
-const DH_RATCHET_POLICY = {
-    maxMessages: 50, // Trigger after 50 messages
-    maxTime: 10 * 60 * 1000, // Trigger after 10 minutes
-};
-let lastRatchetTime = Date.now();
-let messageCounter = 0;
-export function enforceDHRatchetPolicy(session, remotePublicKey, suspectedCompromise = false) {
-    const currentTime = Date.now();
-    // Check if policy conditions are met
-    if (messageCounter >= DH_RATCHET_POLICY.maxMessages ||
-        currentTime - lastRatchetTime >= DH_RATCHET_POLICY.maxTime ||
-        suspectedCompromise) {
-        forceDHRatchet(session, remotePublicKey);
-        // Reset counters
-        lastRatchetTime = currentTime;
-        messageCounter = 0;
+    // 2. DH ratchet if new ratchet key
+    const needsRatchet = !session.theirRatchetPublicKey ||
+        Buffer.compare(session.theirRatchetPublicKey, theirPub) !== 0;
+    if (needsRatchet) {
+        if (session.theirRatchetPublicKey) {
+            skipKeys(session, prevChain);
+        }
+        dhRatchetStep(session, theirPub);
     }
+    // 3. Skip to this message number
+    skipKeys(session, msgNum);
+    // 4. Derive message key
+    const { chainKey, messageKey } = kdfCK(session.receivingChainKey);
+    session.receivingChainKey = chainKey;
+    session.recvCount++;
+    session.receivingChainMessageNumber = session.recvCount;
+    return aeadDec(messageKey, ciphertext, nonce, header);
 }
-/**
- * Increment message counter and enforce policy.
- */
-export function incrementMessageCounter(session, remotePublicKey) {
-    messageCounter++;
-    enforceDHRatchetPolicy(session, remotePublicKey);
+/* ================================================================
+ * Force Ratchet (post-compromise security)
+ * ================================================================ */
+export function forceRatchet(session) {
+    session.myRatchetKeyPair = generateKeyPair();
+    session.sendCount = 0;
+    session.recvCount = 0;
+    session.prevSendCount = 0;
+    session.isPostCompromise = true;
 }
-/**
- * Force a DH ratchet step to enable PCS.
- * @param session - The current session state.
- * @param remotePublicKey - The remote party's ephemeral public key.
- */
-export function forceDHRatchet(session, remotePublicKey) {
-    // Generate a new ephemeral key pair
-    const ephemeralKeyPair = sodium.crypto_kx_keypair();
-    // Perform a Diffie-Hellman exchange
-    const dhOutput = sodium.crypto_kx_client_session_keys(ephemeralKeyPair.publicKey, ephemeralKeyPair.privateKey, remotePublicKey);
-    // Update the root key
-    const newRootKey = deriveRootKey(session.rootKey, dhOutput.sharedTx, sodium.from_string('dh-ratchet-recovery'));
-    // Clear compromised keys
-    session.sendingChainKey = newRootKey;
-    session.receivingChainKey = newRootKey;
-    session.skippedMessageKeys.clear();
-    // Update session state
-    session.rootKey = newRootKey;
+/* ================================================================
+ * Serialisation / Deserialisation
+ * ================================================================ */
+export function serializeSession(s) {
+    const sk = {};
+    for (const [k, v] of s.skippedKeys)
+        sk[k] = Array.from(v);
+    return Buffer.from(JSON.stringify({
+        myIK: Array.from(s.myIdentityPublicKey),
+        peerIK: Array.from(s.peerIdentityPublicKey),
+        rk: Array.from(s.rootKey),
+        sck: Array.from(s.sendingChainKey),
+        rck: Array.from(s.receivingChainKey),
+        mrk: {
+            pub: Array.from(s.myRatchetKeyPair.publicKey),
+            priv: Array.from(s.myRatchetKeyPair.privateKey),
+        },
+        trpk: s.theirRatchetPublicKey ? Array.from(s.theirRatchetPublicKey) : null,
+        sc: s.sendCount, rc: s.recvCount, psc: s.prevSendCount,
+        sk, ipc: s.isPostCompromise ? 1 : 0,
+        pspk: s.peerSPK ? Array.from(s.peerSPK) : null,
+        mspk: s.mySPKPair
+            ? { pub: Array.from(s.mySPKPair.publicKey), priv: Array.from(s.mySPKPair.privateKey) }
+            : null,
+    }));
 }
-/**
- * Ensure rootKey updates only occur through DH ratchet.
- * @param session - The current session state.
- * @param dhOutput - The DH output used to update the root key.
- */
-function enforceDHRatchetOnly(session, dhOutput) {
-    if (!dhOutput) {
-        throw new Error('Root key updates must occur through DH ratchet');
+export function deserializeSession(data) {
+    const o = JSON.parse(data.toString());
+    const skipped = new Map();
+    if (o.sk) {
+        for (const [k, v] of Object.entries(o.sk)) {
+            skipped.set(k, Buffer.from(v));
+        }
     }
-    // Update the root key
-    const newRootKey = deriveRootKey(session.rootKey, dhOutput, sodium.from_string('dh-ratchet-only'));
-    session.rootKey = newRootKey;
-}
-/**
- * Trigger PCS recovery only after receiving a new DH public key.
- * @param session - The current session state.
- * @param remotePublicKey - The new DH public key from the remote party.
- */
-export function receiveNewDHPublicKey(session, remotePublicKey) {
-    // Generate a new ephemeral key pair
-    const ephemeralKeyPair = sodium.crypto_kx_keypair();
-    // Perform a Diffie-Hellman exchange
-    const dhOutput = sodium.crypto_kx_client_session_keys(ephemeralKeyPair.publicKey, ephemeralKeyPair.privateKey, remotePublicKey);
-    // Update the root key
-    const newRootKey = deriveRootKey(session.rootKey, dhOutput, sodium.from_string('dh-ratchet-recovery'));
-    // Clear compromised keys
-    session.sendingChainKey = newRootKey;
-    session.receivingChainKey = newRootKey;
-    session.skippedMessageKeys.clear();
-    // Update session state
-    session.rootKey = newRootKey;
-}
-/**
- * Define and enforce state transitions between epochs.
- * @param session - The current session state.
- */
-function transitionToPostCompromiseEpoch(session) {
-    // Clear all pre-compromise state
-    session.sendingChainKey = null;
-    session.receivingChainKey = null;
-    session.skippedMessageKeys.clear();
-    // Mark the session as post-compromise
-    session.isPostCompromise = true;
+    const myIK = Buffer.from(o.myIK);
+    return {
+        myIdentityPublicKey: myIK,
+        peerIdentityPublicKey: Buffer.from(o.peerIK),
+        rootKey: Buffer.from(o.rk),
+        sendingChainKey: Buffer.from(o.sck),
+        receivingChainKey: Buffer.from(o.rck),
+        myRatchetKeyPair: {
+            publicKey: Buffer.from(o.mrk.pub),
+            privateKey: Buffer.from(o.mrk.priv),
+        },
+        theirRatchetPublicKey: o.trpk ? Buffer.from(o.trpk) : null,
+        sendCount: o.sc, recvCount: o.rc, prevSendCount: o.psc,
+        skippedKeys: skipped,
+        isPostCompromise: o.ipc === 1,
+        peerSPK: o.pspk ? Buffer.from(o.pspk) : null,
+        mySPKPair: o.mspk
+            ? { publicKey: Buffer.from(o.mspk.pub), privateKey: Buffer.from(o.mspk.priv) }
+            : null,
+        identityKey: myIK,
+        signedPreKey: myIK,
+        oneTimePreKey: new Uint8Array(0),
+        sendingChainMessageNumber: o.sc,
+        receivingChainMessageNumber: o.rc,
+        previousSendingChainLength: o.psc,
+    };
 }