@verbeth/sdk 0.1.4 → 0.1.5

package/dist/src/pq/kem.js

@@ -0,0 +1,40 @@
+// packages/sdk/src/pq/kem.ts
+/**
+ * ML-KEM-768 Key Encapsulation Mechanism wrapper.
+ *
+ * Provides post-quantum key encapsulation for hybrid handshakes.
+ */
+import { ml_kem768 } from '@noble/post-quantum/ml-kem.js';
+export const kem = {
+    publicKeyBytes: 1184, // in bytes
+    ciphertextBytes: 1088,
+    sharedSecretBytes: 32,
+    /**
+     * Generate a new ML-KEM-768 keypair.
+     *
+     * @returns Object containing publicKey and secretKey
+     */
+    generateKeyPair() {
+        return ml_kem768.keygen();
+    },
+    /**
+     * Encapsulate a shared secret using the recipient's public key.
+     *
+     * @param publicKey - Recipient's ML-KEM-768 public key
+     * @returns Object containing ciphertext and sharedSecret
+     */
+    encapsulate(publicKey) {
+        const result = ml_kem768.encapsulate(publicKey);
+        return { ciphertext: result.cipherText, sharedSecret: result.sharedSecret };
+    },
+    /**
+     * Decapsulate a ciphertext using the secret key to recover the shared secret.
+     *
+     * @param ciphertext - KEM ciphertext
+     * @param secretKey - Recipient's ML-KEM-768 secret key
+     * @returns Shared secret
+     */
+    decapsulate(ciphertext, secretKey) {
+        return ml_kem768.decapsulate(ciphertext, secretKey);
+    }
+};

package/dist/src/ratchet/auth.d.ts

@@ -0,0 +1,34 @@
+import { MessageHeader } from './types.js';
+/**
+ * Verify message signature before any ratchet operations.
+ * This is the primary DoS protection layer.
+ *
+ * The signature covers (header || ciphertext), where header is the 40-byte
+ * binary encoding of (dh, pn, n).
+ *
+ * @param signature - Ed25519 signature (64 bytes)
+ * @param header - Message header
+ * @param ciphertext - Encrypted payload
+ * @param signingPublicKey - Contact's Ed25519 public key (32 bytes)
+ * @returns true if signature is valid
+ */
+export declare function verifyMessageSignature(signature: Uint8Array, header: MessageHeader, ciphertext: Uint8Array, signingPublicKey: Uint8Array): boolean;
+/**
+ * Create Ed25519 signature for a message.
+ *
+ * @param header - Message header
+ * @param ciphertext - Encrypted payload
+ * @param signingSecretKey - Ed25519 secret key (64 bytes)
+ * @returns Ed25519 signature (64 bytes)
+ */
+export declare function signMessage(header: MessageHeader, ciphertext: Uint8Array, signingSecretKey: Uint8Array): Uint8Array;
+/**
+ * Validate that a parsed payload has a well-formed signature and header.
+ * Does NOT verify the signature - just checks lengths and format.
+ *
+ * @param signature - Signature bytes
+ * @param header - Parsed header
+ * @returns true if format is valid
+ */
+export declare function isValidPayloadFormat(signature: Uint8Array, header: MessageHeader): boolean;
+//# sourceMappingURL=auth.d.ts.map

package/dist/src/ratchet/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/ratchet/auth.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAM3C;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,UAAU,EACrB,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,UAAU,EACtB,gBAAgB,EAAE,UAAU,GAC3B,OAAO,CAmBT;AAkBD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,UAAU,EACtB,gBAAgB,EAAE,UAAU,GAC3B,UAAU,CAOZ;AAMD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,UAAU,EACrB,MAAM,EAAE,aAAa,GACpB,OAAO,CAST"}

package/dist/src/ratchet/auth.js

@@ -0,0 +1,88 @@
+// packages/sdk/src/ratchet/auth.ts
+/**
+ * Message Authentication for Ratchet Protocol.
+ */
+import nacl from 'tweetnacl';
+// =============================================================================
+// Signature Verification
+// =============================================================================
+/**
+ * Verify message signature before any ratchet operations.
+ * This is the primary DoS protection layer.
+ *
+ * The signature covers (header || ciphertext), where header is the 40-byte
+ * binary encoding of (dh, pn, n).
+ *
+ * @param signature - Ed25519 signature (64 bytes)
+ * @param header - Message header
+ * @param ciphertext - Encrypted payload
+ * @param signingPublicKey - Contact's Ed25519 public key (32 bytes)
+ * @returns true if signature is valid
+ */
+export function verifyMessageSignature(signature, header, ciphertext, signingPublicKey) {
+    if (signature.length !== 64) {
+        return false;
+    }
+    if (signingPublicKey.length !== 32) {
+        return false;
+    }
+    // Reconstruct signed data: header || ciphertext
+    const headerBytes = encodeHeaderForSigning(header);
+    const dataToVerify = new Uint8Array(headerBytes.length + ciphertext.length);
+    dataToVerify.set(headerBytes, 0);
+    dataToVerify.set(ciphertext, headerBytes.length);
+    try {
+        return nacl.sign.detached.verify(dataToVerify, signature, signingPublicKey);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Encode header as 40 bytes for signature verification.
+ * Format: dh (32) + pn (4, BE) + n (4, BE)
+ */
+function encodeHeaderForSigning(header) {
+    const buf = new Uint8Array(40);
+    buf.set(header.dh, 0);
+    new DataView(buf.buffer).setUint32(32, header.pn, false); // big-endian
+    new DataView(buf.buffer).setUint32(36, header.n, false);
+    return buf;
+}
+// =============================================================================
+// Signature Creation
+// =============================================================================
+/**
+ * Create Ed25519 signature for a message.
+ *
+ * @param header - Message header
+ * @param ciphertext - Encrypted payload
+ * @param signingSecretKey - Ed25519 secret key (64 bytes)
+ * @returns Ed25519 signature (64 bytes)
+ */
+export function signMessage(header, ciphertext, signingSecretKey) {
+    const headerBytes = encodeHeaderForSigning(header);
+    const dataToSign = new Uint8Array(headerBytes.length + ciphertext.length);
+    dataToSign.set(headerBytes, 0);
+    dataToSign.set(ciphertext, headerBytes.length);
+    return nacl.sign.detached(dataToSign, signingSecretKey);
+}
+// =============================================================================
+// Validation Helpers
+// =============================================================================
+/**
+ * Validate that a parsed payload has a well-formed signature and header.
+ * Does NOT verify the signature - just checks lengths and format.
+ *
+ * @param signature - Signature bytes
+ * @param header - Parsed header
+ * @returns true if format is valid
+ */
+export function isValidPayloadFormat(signature, header) {
+    return (signature.length === 64 &&
+        header.dh.length === 32 &&
+        header.pn >= 0 &&
+        header.n >= 0 &&
+        Number.isInteger(header.pn) &&
+        Number.isInteger(header.n));
+}

package/dist/src/ratchet/codec.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Binary Codec for Ratchet Messages.
+ *
+ * Wire format:
+ * ┌─────────────────────────────────────────────────────────────┐
+ * │ Offset │ Size │ Field                                       │
+ * ├────────┼──────┼─────────────────────────────────────────────┤
+ * │ 0      │ 1    │ Version (0x01)                              │
+ * │ 1      │ 64   │ Ed25519 signature                           │
+ * │ 65     │ 32   │ DH ratchet public key                       │
+ * │ 97     │ 4    │ pn (uint32 BE) - previous chain length      │
+ * │ 101    │ 4    │ n (uint32 BE) - message number              │
+ * │ 105    │ var  │ Ciphertext (nonce + AEAD output)            │
+ * └─────────────────────────────────────────────────────────────┘
+ *
+ * Total minimum: 105 bytes + ciphertext
+ */
+import { MessageHeader, ParsedRatchetPayload } from './types.js';
+/**
+ * Package ratchet message components into binary format.
+ *
+ * @param signature - Ed25519 signature (64 bytes)
+ * @param header - Message header (dh, pn, n)
+ * @param ciphertext - Encrypted payload (nonce + secretbox output)
+ * @returns Binary payload ready for on-chain submission
+ */
+export declare function packageRatchetPayload(signature: Uint8Array, header: MessageHeader, ciphertext: Uint8Array): Uint8Array;
+/**
+ * Parse a binary ratchet payload.
+ *
+ * @param payload - Raw binary payload
+ * @returns Parsed components, or null if invalid format
+ */
+export declare function parseRatchetPayload(payload: Uint8Array): ParsedRatchetPayload | null;
+/**
+ * Check if payload is in ratchet format.
+ * Used to distinguish ratchet messages from legacy JSON format.
+ *
+ * @param payload - Raw payload bytes
+ * @returns true if payload starts with ratchet version byte
+ */
+export declare function isRatchetPayload(payload: Uint8Array): boolean;
+/**
+ * Check if hex string represents a ratchet payload.
+ *
+ * @param hexPayload - Hex string (with or without 0x prefix)
+ * @returns true if payload is ratchet format
+ */
+export declare function isRatchetPayloadHex(hexPayload: string): boolean;
+export declare function hexToBytes(hex: string): Uint8Array;
+export declare function bytesToHex(bytes: Uint8Array, prefix?: boolean): string;
+//# sourceMappingURL=codec.d.ts.map

package/dist/src/ratchet/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../../src/ratchet/codec.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAsB,MAAM,YAAY,CAAC;AAKrF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,UAAU,EACrB,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,UAAU,GACrB,UAAU,CAiCZ;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,UAAU,GAAG,oBAAoB,GAAG,IAAI,CAmCpF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAE7D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAQ/D;AAGD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAOlD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,GAAE,OAAc,GAAG,MAAM,CAK5E"}

package/dist/src/ratchet/codec.js

@@ -0,0 +1,127 @@
+// packages/sdk/src/ratchet/codec.ts
+/**
+ * Binary Codec for Ratchet Messages.
+ *
+ * Wire format:
+ * ┌─────────────────────────────────────────────────────────────┐
+ * │ Offset │ Size │ Field                                       │
+ * ├────────┼──────┼─────────────────────────────────────────────┤
+ * │ 0      │ 1    │ Version (0x01)                              │
+ * │ 1      │ 64   │ Ed25519 signature                           │
+ * │ 65     │ 32   │ DH ratchet public key                       │
+ * │ 97     │ 4    │ pn (uint32 BE) - previous chain length      │
+ * │ 101    │ 4    │ n (uint32 BE) - message number              │
+ * │ 105    │ var  │ Ciphertext (nonce + AEAD output)            │
+ * └─────────────────────────────────────────────────────────────┘
+ *
+ * Total minimum: 105 bytes + ciphertext
+ */
+import { RATCHET_VERSION_V1 } from './types.js';
+/** Minimum payload length: version(1) + sig(64) + dh(32) + pn(4) + n(4) */
+const MIN_PAYLOAD_LENGTH = 1 + 64 + 32 + 4 + 4; // 105 bytes
+/**
+ * Package ratchet message components into binary format.
+ *
+ * @param signature - Ed25519 signature (64 bytes)
+ * @param header - Message header (dh, pn, n)
+ * @param ciphertext - Encrypted payload (nonce + secretbox output)
+ * @returns Binary payload ready for on-chain submission
+ */
+export function packageRatchetPayload(signature, header, ciphertext) {
+    if (signature.length !== 64) {
+        throw new Error(`Invalid signature length: ${signature.length}, expected 64`);
+    }
+    if (header.dh.length !== 32) {
+        throw new Error(`Invalid DH key length: ${header.dh.length}, expected 32`);
+    }
+    // Total: 1 + 64 + 32 + 4 + 4 + ciphertext.length = 105 + ciphertext.length
+    const payload = new Uint8Array(MIN_PAYLOAD_LENGTH + ciphertext.length);
+    const view = new DataView(payload.buffer);
+    let offset = 0;
+    payload[offset++] = RATCHET_VERSION_V1;
+    payload.set(signature, offset);
+    offset += 64;
+    payload.set(header.dh, offset);
+    offset += 32;
+    // pn (uint32 big-endian)
+    view.setUint32(offset, header.pn, false);
+    offset += 4;
+    // n (uint32 big-endian)
+    view.setUint32(offset, header.n, false);
+    offset += 4;
+    payload.set(ciphertext, offset);
+    return payload;
+}
+/**
+ * Parse a binary ratchet payload.
+ *
+ * @param payload - Raw binary payload
+ * @returns Parsed components, or null if invalid format
+ */
+export function parseRatchetPayload(payload) {
+    if (payload.length < MIN_PAYLOAD_LENGTH) {
+        return null;
+    }
+    const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+    let offset = 0;
+    const version = payload[offset++];
+    if (version !== RATCHET_VERSION_V1) {
+        return null;
+    }
+    const signature = payload.slice(offset, offset + 64);
+    offset += 64;
+    const dh = payload.slice(offset, offset + 32);
+    offset += 32;
+    // pn (uint32 big-endian)
+    const pn = view.getUint32(offset, false);
+    offset += 4;
+    // n (uint32 big-endian)
+    const n = view.getUint32(offset, false);
+    offset += 4;
+    const ciphertext = payload.slice(offset);
+    return {
+        version,
+        signature,
+        header: { dh, pn, n },
+        ciphertext,
+    };
+}
+/**
+ * Check if payload is in ratchet format.
+ * Used to distinguish ratchet messages from legacy JSON format.
+ *
+ * @param payload - Raw payload bytes
+ * @returns true if payload starts with ratchet version byte
+ */
+export function isRatchetPayload(payload) {
+    return payload.length >= MIN_PAYLOAD_LENGTH && payload[0] === RATCHET_VERSION_V1;
+}
+/**
+ * Check if hex string represents a ratchet payload.
+ *
+ * @param hexPayload - Hex string (with or without 0x prefix)
+ * @returns true if payload is ratchet format
+ */
+export function isRatchetPayloadHex(hexPayload) {
+    const hex = hexPayload.startsWith('0x') ? hexPayload.slice(2) : hexPayload;
+    if (hex.length < MIN_PAYLOAD_LENGTH * 2) {
+        return false;
+    }
+    // Check first byte is version
+    const firstByte = parseInt(hex.slice(0, 2), 16);
+    return firstByte === RATCHET_VERSION_V1;
+}
+export function hexToBytes(hex) {
+    const cleanHex = hex.startsWith('0x') ? hex.slice(2) : hex;
+    const bytes = new Uint8Array(cleanHex.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(cleanHex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}
+export function bytesToHex(bytes, prefix = true) {
+    const hex = Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+    return prefix ? `0x${hex}` : hex;
+}

package/dist/src/ratchet/decrypt.d.ts

@@ -0,0 +1,28 @@
+import { RatchetSession, MessageHeader, DecryptResult } from './types.js';
+/**
+ * Decrypt a message using the ratchet.
+ *
+ * @param session - Current ratchet session state
+ * @param header - Parsed message header
+ * @param ciphertext - Encrypted payload (nonce + secretbox output)
+ * @returns Decrypt result with new session state and plaintext, or null on failure
+ */
+export declare function ratchetDecrypt(session: RatchetSession, header: MessageHeader, ciphertext: Uint8Array): DecryptResult | null;
+/**
+ * Prune expired skipped keys from session.
+ *
+ * @param session - Current session
+ * @param maxAgeMs - Maximum age in milliseconds (default: 24 hours)
+ * @returns Session with pruned skipped keys
+ */
+export declare function pruneExpiredSkippedKeys(session: RatchetSession, maxAgeMs?: number): RatchetSession;
+/**
+ * Check if topic matches this session.
+ * Returns match type or null.
+ *
+ * @param session - Ratchet session to check
+ * @param topic - Topic to match against
+ * @returns 'current' if matches current inbound, 'previous' if matches previous (within grace), null otherwise
+ */
+export declare function matchesSessionTopic(session: RatchetSession, topic: `0x${string}`): 'current' | 'previous' | null;
+//# sourceMappingURL=decrypt.d.ts.map

package/dist/src/ratchet/decrypt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decrypt.d.ts","sourceRoot":"","sources":["../../../src/ratchet/decrypt.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,cAAc,EACd,aAAa,EACb,aAAa,EAKd,MAAM,YAAY,CAAC;AAGpB;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,UAAU,GACrB,aAAa,GAAG,IAAI,CA4EtB;AAgKD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,cAAc,EACvB,QAAQ,GAAE,MAA4B,GACrC,cAAc,CAyBhB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,KAAK,MAAM,EAAE,GACnB,SAAS,GAAG,UAAU,GAAG,IAAI,CAgB/B"}

package/dist/src/ratchet/decrypt.js

@@ -0,0 +1,255 @@
+// packages/sdk/src/ratchet/decrypt.ts
+/**
+ * Ratchet Decryption with Skip Key Handling.
+ *
+ * Handles:
+ * - Normal sequential message decryption
+ * - DH ratchet steps when sender's DH key changes
+ * - Out-of-order messages via skipped keys
+ * - Topic ratcheting synchronized with DH ratchet
+ */
+import nacl from 'tweetnacl';
+import { hexlify } from 'ethers';
+import { MAX_SKIP_PER_MESSAGE, MAX_STORED_SKIPPED_KEYS, TOPIC_TRANSITION_WINDOW_MS, } from './types.js';
+import { kdfRootKey, kdfChainKey, dh, generateDHKeyPair, deriveTopic } from './kdf.js';
+/**
+ * Decrypt a message using the ratchet.
+ *
+ * @param session - Current ratchet session state
+ * @param header - Parsed message header
+ * @param ciphertext - Encrypted payload (nonce + secretbox output)
+ * @returns Decrypt result with new session state and plaintext, or null on failure
+ */
+export function ratchetDecrypt(session, header, ciphertext) {
+    // Sanity check: even authenticated messages shouldn't require insane skips
+    const skipNeeded = Math.max(0, header.n - session.receivingMsgNumber);
+    if (skipNeeded > MAX_SKIP_PER_MESSAGE || header.pn > MAX_SKIP_PER_MESSAGE) {
+        console.error(`Message requires ${skipNeeded} skips (pn=${header.pn}) — likely corrupted or malicious peer`);
+        return null;
+    }
+    const dhPubHex = hexlify(header.dh);
+    const currentTheirDHHex = session.dhTheirPublicKey
+        ? hexlify(session.dhTheirPublicKey)
+        : null;
+    // 1. Try skipped keys first (handles out-of-order messages)
+    const skippedResult = trySkippedKeys(session, dhPubHex, header.n, ciphertext);
+    if (skippedResult) {
+        return skippedResult;
+    }
+    // 2. Clone session for modifications
+    let newSession = { ...session, skippedKeys: [...session.skippedKeys] };
+    // 3. Check if we need to perform a DH ratchet step
+    if (dhPubHex !== currentTheirDHHex) {
+        // Skip any remaining messages from previous receiving chain
+        if (newSession.receivingChainKey) {
+            newSession = skipMessages(newSession, newSession.receivingMsgNumber, header.pn);
+        }
+        // Perform DH ratchet step
+        newSession = dhRatchetStep(newSession, header.dh);
+    }
+    // 4. Skip messages if n > receivingMsgNumber (within current epoch)
+    if (header.n > newSession.receivingMsgNumber) {
+        newSession = skipMessages(newSession, newSession.receivingMsgNumber, header.n);
+    }
+    // 5. Derive message key
+    if (!newSession.receivingChainKey) {
+        console.error('No receiving chain key available');
+        return null;
+    }
+    const { chainKey: newReceivingChainKey, messageKey } = kdfChainKey(newSession.receivingChainKey);
+    // 6. Decrypt
+    const plaintext = decryptWithKey(ciphertext, messageKey);
+    // 7. Wipe message key
+    try {
+        messageKey.fill(0);
+    }
+    catch {
+        // Ignore if fill fails
+    }
+    if (!plaintext) {
+        return null;
+    }
+    // 8. Update session state
+    newSession = {
+        ...newSession,
+        receivingChainKey: newReceivingChainKey,
+        receivingMsgNumber: header.n + 1,
+        updatedAt: Date.now(),
+    };
+    return {
+        session: newSession,
+        plaintext,
+    };
+}
+/**
+ * DH ratchet step on receipt of a message with a new remote DH public key.
+ *
+ * Topic derivation is sender-centric: `deriveTopicFromDH(x, 'outbound')` denotes
+ * the topic used by the party who *sent* the DH pubkey for their sending direction.
+ * Therefore, when we ratchet on receive, we swap labels for topics derived from `dhReceive`.
+ */
+function dhRatchetStep(session, theirNewDHPub) {
+    // Advance receiving chain (based on our current DH secret and their new DH pubkey)
+    const dhReceive = dh(session.dhMySecretKey, theirNewDHPub);
+    const { rootKey: rootKey1, chainKey: receivingChainKey } = kdfRootKey(session.rootKey, dhReceive);
+    // Generate new DH keypair for our next sending chain
+    const newDHKeyPair = generateDHKeyPair();
+    // Advance sending chain
+    const dhSend = dh(newDHKeyPair.secretKey, theirNewDHPub);
+    const { rootKey: rootKey2, chainKey: sendingChainKey } = kdfRootKey(rootKey1, dhSend);
+    // Current topics (post ratchet) - swapped since we're the receiver
+    // Use rootKey1 (derived from dhReceive) for PQ-secure topic derivation
+    const newTopicOut = deriveTopic(rootKey1, dhReceive, 'inbound');
+    const newTopicIn = deriveTopic(rootKey1, dhReceive, 'outbound');
+    // Next topics (for our next DH pubkey) - normal labels because we will be the sender
+    // Use rootKey2 (derived from dhSend) for PQ-secure topic derivation
+    const nextTopicOut = deriveTopic(rootKey2, dhSend, 'outbound');
+    const nextTopicIn = deriveTopic(rootKey2, dhSend, 'inbound');
+    return {
+        ...session,
+        rootKey: rootKey2,
+        dhMySecretKey: newDHKeyPair.secretKey,
+        dhMyPublicKey: newDHKeyPair.publicKey,
+        dhTheirPublicKey: theirNewDHPub,
+        receivingChainKey,
+        receivingMsgNumber: 0,
+        sendingChainKey,
+        sendingMsgNumber: 0,
+        previousChainLength: session.sendingMsgNumber,
+        nextTopicOutbound: nextTopicOut,
+        nextTopicInbound: nextTopicIn,
+        currentTopicOutbound: newTopicOut,
+        currentTopicInbound: newTopicIn,
+        previousTopicInbound: session.currentTopicInbound,
+        previousTopicExpiry: Date.now() + TOPIC_TRANSITION_WINDOW_MS,
+        topicEpoch: session.topicEpoch + 1,
+    };
+}
+/**
+ * Skip messages by deriving and storing their keys for later out-of-order decryption.
+ *
+ * Called when:
+ * - header.n > receivingMsgNumber (messages skipped in current epoch)
+ * - DH ratchet step with header.pn > 0 (messages from previous epoch)
+ */
+function skipMessages(session, start, until) {
+    if (!session.receivingChainKey || until <= start) {
+        return session;
+    }
+    const skippedKeys = [...session.skippedKeys];
+    let chainKey = session.receivingChainKey;
+    const dhPubHex = hexlify(session.dhTheirPublicKey);
+    const now = Date.now();
+    for (let i = start; i < until; i++) {
+        const { chainKey: newChainKey, messageKey } = kdfChainKey(chainKey);
+        skippedKeys.push({
+            dhPubKeyHex: dhPubHex,
+            msgNumber: i,
+            messageKey: new Uint8Array(messageKey),
+            createdAt: now,
+        });
+        chainKey = newChainKey;
+    }
+    // Prune if we have too many skipped keys
+    let prunedKeys = skippedKeys;
+    if (skippedKeys.length > MAX_STORED_SKIPPED_KEYS) {
+        prunedKeys = skippedKeys
+            .sort((a, b) => b.createdAt - a.createdAt)
+            .slice(0, MAX_STORED_SKIPPED_KEYS);
+    }
+    return {
+        ...session,
+        receivingChainKey: chainKey,
+        skippedKeys: prunedKeys,
+    };
+}
+function trySkippedKeys(session, dhPubHex, msgNumber, ciphertext) {
+    const idx = session.skippedKeys.findIndex((sk) => sk.dhPubKeyHex === dhPubHex && sk.msgNumber === msgNumber);
+    if (idx === -1) {
+        return null;
+    }
+    const skippedKey = session.skippedKeys[idx];
+    const plaintext = decryptWithKey(ciphertext, skippedKey.messageKey);
+    if (!plaintext) {
+        return null;
+    }
+    const newSkippedKeys = [...session.skippedKeys];
+    newSkippedKeys.splice(idx, 1);
+    // Wipe the key
+    try {
+        skippedKey.messageKey.fill(0);
+    }
+    catch {
+    }
+    return {
+        session: {
+            ...session,
+            skippedKeys: newSkippedKeys,
+            updatedAt: Date.now(),
+        },
+        plaintext,
+    };
+}
+/**
+ * Decrypt ciphertext with message key using XSalsa20-Poly1305.
+ * Ciphertext format: nonce (24 bytes) + secretbox output
+ */
+function decryptWithKey(ciphertext, messageKey) {
+    if (ciphertext.length < nacl.secretbox.nonceLength) {
+        return null;
+    }
+    const nonce = ciphertext.slice(0, nacl.secretbox.nonceLength);
+    const box = ciphertext.slice(nacl.secretbox.nonceLength);
+    const result = nacl.secretbox.open(box, nonce, messageKey);
+    return result || null;
+}
+/**
+ * Prune expired skipped keys from session.
+ *
+ * @param session - Current session
+ * @param maxAgeMs - Maximum age in milliseconds (default: 24 hours)
+ * @returns Session with pruned skipped keys
+ */
+export function pruneExpiredSkippedKeys(session, maxAgeMs = 24 * 60 * 60 * 1000) {
+    const now = Date.now();
+    const cutoff = now - maxAgeMs;
+    const prunedKeys = session.skippedKeys.filter((sk) => sk.createdAt > cutoff);
+    // Wipe expired keys
+    for (const sk of session.skippedKeys) {
+        if (sk.createdAt <= cutoff) {
+            try {
+                sk.messageKey.fill(0);
+            }
+            catch {
+            }
+        }
+    }
+    if (prunedKeys.length === session.skippedKeys.length) {
+        return session; // No change
+    }
+    return {
+        ...session,
+        skippedKeys: prunedKeys,
+        updatedAt: now,
+    };
+}
+/**
+ * Check if topic matches this session.
+ * Returns match type or null.
+ *
+ * @param session - Ratchet session to check
+ * @param topic - Topic to match against
+ * @returns 'current' if matches current inbound, 'previous' if matches previous (within grace), null otherwise
+ */
+export function matchesSessionTopic(session, topic) {
+    const t = topic.toLowerCase();
+    if (session.currentTopicInbound.toLowerCase() === t) {
+        return 'current';
+    }
+    if (session.previousTopicInbound?.toLowerCase() === t &&
+        session.previousTopicExpiry &&
+        Date.now() < session.previousTopicExpiry) {
+        return 'previous';
+    }
+    return null;
+}

package/dist/src/ratchet/encrypt.d.ts

@@ -0,0 +1,17 @@
+import { RatchetSession, MessageHeader, EncryptResult } from './types.js';
+/**
+ * Encode message header as 40 bytes for signing.
+ * Format: dh (32) + pn (4, BE) + n (4, BE)
+ */
+export declare function encodeHeader(header: MessageHeader): Uint8Array;
+/**
+ * Encrypt a message using the ratchet.
+ *
+ * @param session - Current ratchet session state
+ * @param plaintext - Message to encrypt
+ * @param signingSecretKey - Ed25519 secret key for signing (64 bytes)
+ * @returns Encrypt result with new session state, header, ciphertext, signature, and topic
+ * @throws If session is not ready to send (no sending chain key)
+ */
+export declare function ratchetEncrypt(session: RatchetSession, plaintext: Uint8Array, signingSecretKey: Uint8Array): EncryptResult;
+//# sourceMappingURL=encrypt.d.ts.map

package/dist/src/ratchet/encrypt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encrypt.d.ts","sourceRoot":"","sources":["../../../src/ratchet/encrypt.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG1E;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,UAAU,CAM9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,UAAU,EACrB,gBAAgB,EAAE,UAAU,GAC3B,aAAa,CAqDf"}