@verbeth/sdk 0.1.4 → 0.1.6

package/dist/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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"}

package/dist/esm/src/ratchet/encrypt.js

@@ -0,0 +1,78 @@
+// packages/sdk/src/ratchet/encrypt.ts
+/**
+ * Ratchet Encryption.
+ *
+ * Encrypts plaintext using the current sending chain, advances chain state,
+ * and signs the message with Ed25519.
+ *
+ * Returns a new session object. Caller must persist session state
+ * immediately for forward secrecy (before tx submission).
+ */
+import nacl from 'tweetnacl';
+import { kdfChainKey } from './kdf.js';
+/**
+ * Encode message header as 40 bytes for signing.
+ * Format: dh (32) + pn (4, BE) + n (4, BE)
+ */
+export function encodeHeader(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;
+}
+/**
+ * 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 function ratchetEncrypt(session, plaintext, signingSecretKey) {
+    if (!session.sendingChainKey) {
+        throw new Error('Session not ready to send (no sending chain key)');
+    }
+    // 1. Advance sending chain to get message key
+    const { chainKey: newChainKey, messageKey } = kdfChainKey(session.sendingChainKey);
+    // 2. Create header with current DH public key and message numbers
+    const header = {
+        dh: session.dhMyPublicKey,
+        pn: session.previousChainLength,
+        n: session.sendingMsgNumber,
+    };
+    // 3. Encrypt with message key using XSalsa20-Poly1305
+    const nonce = nacl.randomBytes(nacl.secretbox.nonceLength); // 24 bytes
+    const ciphertext = nacl.secretbox(plaintext, nonce, messageKey);
+    // 4. Combine nonce + ciphertext
+    const encryptedPayload = new Uint8Array(nonce.length + ciphertext.length);
+    encryptedPayload.set(nonce, 0);
+    encryptedPayload.set(ciphertext, nonce.length);
+    // 5. Sign (header || encryptedPayload) with Ed25519
+    const headerBytes = encodeHeader(header);
+    const dataToSign = new Uint8Array(headerBytes.length + encryptedPayload.length);
+    dataToSign.set(headerBytes, 0);
+    dataToSign.set(encryptedPayload, headerBytes.length);
+    const signature = nacl.sign.detached(dataToSign, signingSecretKey);
+    // 6. Create new session state (don't mutate original)
+    const newSession = {
+        ...session,
+        sendingChainKey: newChainKey,
+        sendingMsgNumber: session.sendingMsgNumber + 1,
+        updatedAt: Date.now(),
+    };
+    // 7. Wipe message key from memory
+    try {
+        messageKey.fill(0);
+    }
+    catch {
+    }
+    return {
+        session: newSession,
+        header,
+        ciphertext: encryptedPayload,
+        signature,
+        topic: session.currentTopicOutbound,
+    };
+}

package/dist/esm/src/ratchet/index.d.ts

@@ -0,0 +1,8 @@
+export { MAX_SKIP_PER_MESSAGE, MAX_STORED_SKIPPED_KEYS, MAX_SKIPPED_KEYS_AGE_MS, SYNC_BATCH_SIZE, RATCHET_VERSION_V1, TOPIC_TRANSITION_WINDOW_MS, type RatchetSession, type SkippedKey, type MessageHeader, type EncryptResult, type DecryptResult, type ParsedRatchetPayload, type InitResponderParams, type InitInitiatorParams, } from './types.js';
+export { kdfRootKey, kdfChainKey, dh, generateDHKeyPair, deriveTopic, hybridInitialSecret, } from './kdf.js';
+export { initSessionAsResponder, initSessionAsInitiator, computeConversationId, } from './session.js';
+export { ratchetEncrypt, encodeHeader, } from './encrypt.js';
+export { ratchetDecrypt, pruneExpiredSkippedKeys, matchesSessionTopic, } from './decrypt.js';
+export { packageRatchetPayload, parseRatchetPayload, isRatchetPayload, isRatchetPayloadHex, hexToBytes, bytesToHex, } from './codec.js';
+export { verifyMessageSignature, signMessage, isValidPayloadFormat, } from './auth.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/src/ratchet/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/ratchet/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,EACvB,eAAe,EACf,kBAAkB,EAClB,0BAA0B,EAE1B,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,aAAa,EAElB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EAEzB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACzB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,UAAU,EACV,WAAW,EACX,EAAE,EACF,iBAAiB,EACjB,WAAW,EACX,mBAAmB,GACpB,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,cAAc,EACd,YAAY,GACb,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,UAAU,EACV,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,sBAAsB,EACtB,WAAW,EACX,oBAAoB,GACrB,MAAM,WAAW,CAAC"}

package/dist/esm/src/ratchet/index.js

@@ -0,0 +1,8 @@
+// packages/sdk/src/ratchet/index.ts
+export { MAX_SKIP_PER_MESSAGE, MAX_STORED_SKIPPED_KEYS, MAX_SKIPPED_KEYS_AGE_MS, SYNC_BATCH_SIZE, RATCHET_VERSION_V1, TOPIC_TRANSITION_WINDOW_MS, } from './types.js';
+export { kdfRootKey, kdfChainKey, dh, generateDHKeyPair, deriveTopic, hybridInitialSecret, } from './kdf.js';
+export { initSessionAsResponder, initSessionAsInitiator, computeConversationId, } from './session.js';
+export { ratchetEncrypt, encodeHeader, } from './encrypt.js';
+export { ratchetDecrypt, pruneExpiredSkippedKeys, matchesSessionTopic, } from './decrypt.js';
+export { packageRatchetPayload, parseRatchetPayload, isRatchetPayload, isRatchetPayloadHex, hexToBytes, bytesToHex, } from './codec.js';
+export { verifyMessageSignature, signMessage, isValidPayloadFormat, } from './auth.js';

package/dist/esm/src/ratchet/kdf.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Derive new root key and chain key from DH output.
+ *
+ * @param rootKey - Current root key (32 bytes)
+ * @param dhOutput - DH shared secret (32 bytes)
+ * @returns New root key and chain key
+ */
+export declare function kdfRootKey(rootKey: Uint8Array, dhOutput: Uint8Array): {
+    rootKey: Uint8Array;
+    chainKey: Uint8Array;
+};
+/**
+ * Derive message key and advance chain key.
+ *
+ * @param chainKey - Current chain key (32 bytes)
+ * @returns New chain key and message key for encryption/decryption
+ */
+export declare function kdfChainKey(chainKey: Uint8Array): {
+    chainKey: Uint8Array;
+    messageKey: Uint8Array;
+};
+/**
+ * Perform X25519 Diffie-Hellman key exchange.
+ *
+ * @param mySecretKey - My X25519 secret key (32 bytes)
+ * @param theirPublicKey - Their X25519 public key (32 bytes)
+ * @returns Shared secret (32 bytes)
+ */
+export declare function dh(mySecretKey: Uint8Array, theirPublicKey: Uint8Array): Uint8Array;
+/**
+ * Generate new X25519 keypair for DH ratchet step.
+ *
+ * @returns New keypair with secretKey and publicKey
+ */
+export declare function generateDHKeyPair(): {
+    secretKey: Uint8Array;
+    publicKey: Uint8Array;
+};
+/**
+ * Derive topic from DH output using rootKey as PQ-secure salt.
+ *
+ * The rootKey (PQ-secure from hybrid handshake) acts as HKDF salt,
+ * providing quantum-resistant topic unlinkability even if dhOutput
+ * is later computed by a quantum adversary.
+ *
+ * @param rootKey - Current root key (32 bytes, PQ-secure)
+ * @param dhOutput - DH shared secret from ratchet step (32 bytes)
+ * @param direction - 'outbound' or 'inbound' for topic direction
+ * @returns bytes32 topic as hex string
+ */
+export declare function deriveTopic(rootKey: Uint8Array, dhOutput: Uint8Array, direction: 'outbound' | 'inbound'): `0x${string}`;
+/**
+ * Combines classical (X25519) and post-quantum (ML-KEM-768) key exchange
+ *
+ * @param x25519Secret - X25519 DH shared secret (32 bytes)
+ * @param kemSecret - ML-KEM-768 shared secret (32 bytes)
+ * @returns Hybrid shared secret (32 bytes)
+ */
+export declare function hybridInitialSecret(x25519Secret: Uint8Array, kemSecret: Uint8Array): Uint8Array;
+//# sourceMappingURL=kdf.d.ts.map

package/dist/esm/src/ratchet/kdf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kdf.d.ts","sourceRoot":"","sources":["../../../../src/ratchet/kdf.ts"],"names":[],"mappings":"AAeA;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,UAAU,GACnB;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,UAAU,CAAA;CAAE,CAM/C;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,UAAU,GACnB;IAAE,QAAQ,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,CAUlD;AAED;;;;;;GAMG;AACH,wBAAgB,EAAE,CAChB,WAAW,EAAE,UAAU,EACvB,cAAc,EAAE,UAAU,GACzB,UAAU,CAEZ;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI;IAAE,SAAS,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,UAAU,CAAA;CAAE,CAGpF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,UAAU,EACpB,SAAS,EAAE,UAAU,GAAG,SAAS,GAChC,KAAK,MAAM,EAAE,CAIf;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,UAAU,EACxB,SAAS,EAAE,UAAU,GACpB,UAAU,CAKZ"}