@zapo-js/fake-server 0.3.0 → 1.1.0

package/dist/esm/protocol/signal/fake-app-state-crypto.js

@@ -0,0 +1,196 @@
+/** App-state crypto helpers mirrored from WhatsApp Web behavior. */
+import { aesCbcDecrypt, aesCbcEncrypt, hkdf, hmacSha256Sign, hmacSha512Sign, randomBytesAsync } from '../../transport/crypto.js';
+import { proto } from '../../transport/protos.js';
+import { TEXT_ENCODER } from '../../transport/util.js';
+const APP_STATE_DERIVED_KEY_LENGTH = 160;
+const APP_STATE_DERIVED_INDEX_KEY_END = 32;
+const APP_STATE_DERIVED_VALUE_ENCRYPTION_KEY_END = 64;
+const APP_STATE_DERIVED_VALUE_MAC_KEY_END = 96;
+const APP_STATE_DERIVED_SNAPSHOT_MAC_KEY_END = 128;
+const APP_STATE_DERIVED_PATCH_MAC_KEY_END = 160;
+const APP_STATE_VALUE_MAC_LENGTH = 32;
+const APP_STATE_MAC_OCTET_LENGTH = 8;
+const APP_STATE_IV_LENGTH = 16;
+const APP_STATE_LT_HASH_SIZE = 128;
+const APP_STATE_POINT_SIZE = 2;
+const KDF_INFO_MUTATION_KEYS = TEXT_ENCODER.encode('WhatsApp Mutation Keys');
+const KDF_INFO_PATCH_INTEGRITY = TEXT_ENCODER.encode('WhatsApp Patch Integrity');
+export const APP_STATE_EMPTY_LT_HASH = new Uint8Array(APP_STATE_LT_HASH_SIZE);
+export class FakeAppStateCrypto {
+    deriveKeys(keyData) {
+        const derived = hkdf(keyData, null, KDF_INFO_MUTATION_KEYS, APP_STATE_DERIVED_KEY_LENGTH);
+        return {
+            indexHmacKey: derived.subarray(0, APP_STATE_DERIVED_INDEX_KEY_END),
+            valueEncryptionAesKey: derived.subarray(APP_STATE_DERIVED_INDEX_KEY_END, APP_STATE_DERIVED_VALUE_ENCRYPTION_KEY_END),
+            valueMacHmacKey: derived.subarray(APP_STATE_DERIVED_VALUE_ENCRYPTION_KEY_END, APP_STATE_DERIVED_VALUE_MAC_KEY_END),
+            snapshotMacHmacKey: derived.subarray(APP_STATE_DERIVED_VALUE_MAC_KEY_END, APP_STATE_DERIVED_SNAPSHOT_MAC_KEY_END),
+            patchMacHmacKey: derived.subarray(APP_STATE_DERIVED_SNAPSHOT_MAC_KEY_END, APP_STATE_DERIVED_PATCH_MAC_KEY_END)
+        };
+    }
+    async encryptMutation(input) {
+        const derivedKeys = this.deriveKeys(input.keyData);
+        const indexBytes = new TextEncoder().encode(input.index);
+        const encoded = proto.SyncActionData.encode({
+            index: indexBytes,
+            value: input.value ?? undefined,
+            padding: new Uint8Array(0),
+            version: input.version
+        }).finish();
+        const iv = input.iv ?? (await randomBytesAsync(APP_STATE_IV_LENGTH));
+        if (iv.byteLength !== APP_STATE_IV_LENGTH) {
+            throw new Error(`invalid IV length ${iv.byteLength}`);
+        }
+        const indexMac = hmacSha256Sign(derivedKeys.indexHmacKey, indexBytes);
+        const cipherText = aesCbcEncrypt(derivedKeys.valueEncryptionAesKey, iv, encoded);
+        const cipherWithIv = concatBytes([iv, cipherText]);
+        const associatedData = generateAssociatedData(input.operation, input.keyId);
+        const valueMac = this.generateValueMac(derivedKeys.valueMacHmacKey, associatedData, cipherWithIv);
+        return {
+            indexMac,
+            valueBlob: concatBytes([cipherWithIv, valueMac]),
+            valueMac
+        };
+    }
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async decryptMutation(input) {
+        if (input.valueBlob.byteLength < APP_STATE_IV_LENGTH + APP_STATE_VALUE_MAC_LENGTH) {
+            throw new Error('invalid mutation value blob');
+        }
+        const derivedKeys = this.deriveKeys(input.keyData);
+        const iv = input.valueBlob.subarray(0, APP_STATE_IV_LENGTH);
+        const macStart = input.valueBlob.byteLength - APP_STATE_VALUE_MAC_LENGTH;
+        const valueMac = input.valueBlob.subarray(macStart);
+        const cipherText = input.valueBlob.subarray(APP_STATE_IV_LENGTH, macStart);
+        const cipherWithIv = input.valueBlob.subarray(0, macStart);
+        const associatedData = generateAssociatedData(input.operation, input.keyId);
+        const expectedMac = this.generateValueMac(derivedKeys.valueMacHmacKey, associatedData, cipherWithIv);
+        if (!uint8Equal(expectedMac, valueMac)) {
+            throw new Error('mutation value MAC mismatch');
+        }
+        const plaintext = aesCbcDecrypt(derivedKeys.valueEncryptionAesKey, iv, cipherText);
+        const syncActionData = proto.SyncActionData.decode(plaintext);
+        if (!syncActionData.index) {
+            throw new Error('missing sync action index');
+        }
+        if (syncActionData.version === null || syncActionData.version === undefined) {
+            throw new Error('missing sync action version');
+        }
+        const generatedIndexMac = hmacSha256Sign(derivedKeys.indexHmacKey, syncActionData.index);
+        if (!uint8Equal(generatedIndexMac, input.indexMac)) {
+            throw new Error('mutation index MAC mismatch');
+        }
+        return {
+            index: new TextDecoder().decode(syncActionData.index),
+            value: syncActionData.value ?? null,
+            version: syncActionData.version,
+            indexMac: input.indexMac,
+            valueMac
+        };
+    }
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async generateSnapshotMac(keyData, ltHash, version, collectionName) {
+        const derivedKeys = this.deriveKeys(keyData);
+        const payload = concatBytes([
+            ltHash,
+            intToBytesBe(8, version),
+            new TextEncoder().encode(collectionName)
+        ]);
+        return hmacSha256Sign(derivedKeys.snapshotMacHmacKey, payload);
+    }
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async generatePatchMac(keyData, snapshotMac, valueMacs, version, collectionName) {
+        const derivedKeys = this.deriveKeys(keyData);
+        const payload = concatBytes([
+            snapshotMac,
+            ...valueMacs,
+            intToBytesBe(8, version),
+            new TextEncoder().encode(collectionName)
+        ]);
+        return hmacSha256Sign(derivedKeys.patchMacHmacKey, payload);
+    }
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async ltHashAdd(base, addValues) {
+        return this.ltHashApply(base, addValues, (left, right) => left + right);
+    }
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async ltHashSubtract(base, removeValues) {
+        return this.ltHashApply(base, removeValues, (left, right) => left - right);
+    }
+    ltHashApply(base, values, combine) {
+        if (values.length === 0) {
+            return base.slice();
+        }
+        const expandedValues = values.map((value) => hkdf(value, null, KDF_INFO_PATCH_INTEGRITY, APP_STATE_LT_HASH_SIZE));
+        const out = new Uint8Array(base.byteLength);
+        pointwise(base, expandedValues[0], combine, out);
+        for (let index = 1; index < expandedValues.length; index += 1) {
+            pointwise(out, expandedValues[index], combine, out);
+        }
+        return out;
+    }
+    generateValueMac(valueMacHmacKey, associatedData, cipherWithIv) {
+        const octetLength = new Uint8Array(APP_STATE_MAC_OCTET_LENGTH);
+        octetLength[octetLength.length - 1] = associatedData.byteLength & 0xff;
+        const full = hmacSha512Sign(valueMacHmacKey, concatBytes([associatedData, cipherWithIv, octetLength]));
+        return full.subarray(0, APP_STATE_VALUE_MAC_LENGTH);
+    }
+}
+function generateAssociatedData(operation, keyId) {
+    // byte 0 is operation+1 (set=1, remove=2), then keyId bytes.
+    const opCode = operation === 'set' ? 1 : 2;
+    const out = new Uint8Array(1 + keyId.byteLength);
+    out[0] = opCode;
+    out.set(keyId, 1);
+    return out;
+}
+function pointwise(left, right, combine, out) {
+    if (left.byteLength !== right.byteLength) {
+        throw new Error('lt hash input length mismatch');
+    }
+    if (left.byteLength % APP_STATE_POINT_SIZE !== 0) {
+        throw new Error('lt hash input alignment mismatch');
+    }
+    if (out.byteLength !== left.byteLength) {
+        throw new Error('lt hash output length mismatch');
+    }
+    const leftView = new DataView(left.buffer, left.byteOffset, left.byteLength);
+    const rightView = new DataView(right.buffer, right.byteOffset, right.byteLength);
+    const outView = new DataView(out.buffer, out.byteOffset, out.byteLength);
+    for (let offset = 0; offset < left.byteLength; offset += APP_STATE_POINT_SIZE) {
+        const value = combine(leftView.getUint16(offset, true), rightView.getUint16(offset, true));
+        outView.setUint16(offset, value & 0xffff, true);
+    }
+}
+function intToBytesBe(byteLength, value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`invalid integer value: ${value}`);
+    }
+    const out = new Uint8Array(byteLength);
+    let current = value;
+    for (let i = byteLength - 1; i >= 0; i -= 1) {
+        out[i] = current & 0xff;
+        current = Math.floor(current / 256);
+    }
+    return out;
+}
+function uint8Equal(a, b) {
+    if (a.byteLength !== b.byteLength)
+        return false;
+    let diff = 0;
+    for (let index = 0; index < a.byteLength; index += 1) {
+        diff |= a[index] ^ b[index];
+    }
+    return diff === 0;
+}
+function concatBytes(parts) {
+    let total = 0;
+    for (const part of parts)
+        total += part.byteLength;
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.byteLength;
+    }
+    return out;
+}

package/dist/esm/protocol/signal/fake-peer-double-ratchet.js

@@ -0,0 +1,398 @@
+/** Bidirectional Signal Double Ratchet used by fake peers. */
+import { aesCbcDecrypt, aesCbcEncrypt, hkdf, hkdfSplit, hmacSha256Sign, prependVersion, toRawPubKey, toSerializedPubKey, X25519 } from '../../transport/crypto.js';
+import { proto } from '../../transport/protos.js';
+import { TEXT_ENCODER } from '../../transport/util.js';
+const SIGNAL_VERSION = 3;
+const SIGNAL_MAC_SIZE = 8;
+const SIGNAL_PREFIX_FF = new Uint8Array(32).fill(0xff);
+const MESSAGE_KEY_LABEL = new Uint8Array([1]);
+const CHAIN_KEY_LABEL = new Uint8Array([2]);
+const WHISPER_TEXT_INFO = TEXT_ENCODER.encode('WhisperText');
+const WHISPER_RATCHET_INFO = TEXT_ENCODER.encode('WhisperRatchet');
+const WHISPER_MESSAGE_KEYS_INFO = TEXT_ENCODER.encode('WhisperMessageKeys');
+export class FakePeerDoubleRatchetError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FakePeerDoubleRatchetError';
+    }
+}
+const MAX_FUTURE_RECV_KEYS = 2000;
+export class FakePeerDoubleRatchet {
+    constructor(keyBundle) {
+        this.remoteIdentityPubSerialized = null;
+        this.rootKey = null;
+        this.sendChain = null;
+        this.recvChain = null;
+        this.pendingPreKeyHeader = null;
+        this.bootstrapChainKey = null;
+        this.hasOutboundSendChain = false;
+        this.keyBundle = keyBundle;
+        this.localIdentityPubSerialized = toSerializedPubKey(keyBundle.identityKeyPair.pubKey);
+    }
+    get registrationId() {
+        return this.keyBundle.registrationId;
+    }
+    hasSendChain() {
+        return this.sendChain !== null && this.hasOutboundSendChain;
+    }
+    async initiateOutbound(bundle, options = {}) {
+        if (this.rootKey || this.sendChain || this.recvChain) {
+            throw new FakePeerDoubleRatchetError('session already initialized');
+        }
+        const remoteIdentity = toSerializedPubKey(bundle.identityKey);
+        const remoteSigned = toSerializedPubKey(bundle.signedPreKey.publicKey);
+        const localBase = await X25519.generateKeyPair();
+        const localBaseSerialized = toSerializedPubKey(localBase.pubKey);
+        // Do not fallback to bundle.preKeys[0], otherwise concurrent peers reuse one key id.
+        const consumedOneTime = options.skipOneTimePreKey ? undefined : options.oneTimePreKey;
+        const remoteOneTime = consumedOneTime ? toSerializedPubKey(consumedOneTime.publicKey) : null;
+        const [dh1, dh2, dh3, dh4] = await Promise.all([
+            X25519.scalarMult(this.keyBundle.identityKeyPair.privKey, toRawPubKey(remoteSigned)),
+            X25519.scalarMult(localBase.privKey, toRawPubKey(remoteIdentity)),
+            X25519.scalarMult(localBase.privKey, toRawPubKey(remoteSigned)),
+            remoteOneTime
+                ? X25519.scalarMult(localBase.privKey, toRawPubKey(remoteOneTime))
+                : Promise.resolve(null)
+        ]);
+        const sharedParts = [SIGNAL_PREFIX_FF, dh1, dh2, dh3];
+        if (dh4)
+            sharedParts.push(dh4);
+        const shared = concatBytes(sharedParts);
+        const [rootKey, _chainKey] = hkdfSplit(shared, null, WHISPER_TEXT_INFO);
+        void _chainKey;
+        const sendRatchet = await X25519.generateKeyPair();
+        const ratchetSecret = await X25519.scalarMult(sendRatchet.privKey, toRawPubKey(remoteSigned));
+        const [nextRootKey, sendChainKey] = hkdfSplit(ratchetSecret, rootKey, WHISPER_RATCHET_INFO);
+        this.rootKey = nextRootKey;
+        this.remoteIdentityPubSerialized = remoteIdentity;
+        this.sendChain = {
+            ratchetKeyPair: sendRatchet,
+            ratchetPubSerialized: toSerializedPubKey(sendRatchet.pubKey),
+            chainKey: sendChainKey,
+            nextIndex: 0
+        };
+        this.hasOutboundSendChain = true;
+        this.pendingPreKeyHeader = {
+            preKeyId: consumedOneTime?.keyId,
+            signedPreKeyId: bundle.signedPreKey.keyId,
+            baseKey: localBaseSerialized
+        };
+    }
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async encrypt(plaintext) {
+        if (!this.sendChain) {
+            throw new FakePeerDoubleRatchetError('cannot encrypt: session has no send chain (call initiateOutbound first)');
+        }
+        if (!this.remoteIdentityPubSerialized) {
+            throw new FakePeerDoubleRatchetError('remote identity not set');
+        }
+        const { nextChainKey, messageKey } = deriveMessageKey(this.sendChain.nextIndex, this.sendChain.chainKey);
+        const ciphertext = aesCbcEncrypt(messageKey.cipherKey, messageKey.iv, plaintext);
+        const signalPayload = proto.SignalMessage.encode({
+            ratchetKey: this.sendChain.ratchetPubSerialized,
+            counter: messageKey.index,
+            previousCounter: 0,
+            ciphertext
+        }).finish();
+        const versioned = prependVersion(signalPayload, SIGNAL_VERSION);
+        const macInput = concatBytes([
+            this.localIdentityPubSerialized,
+            this.remoteIdentityPubSerialized,
+            versioned
+        ]);
+        const fullMac = hmacSha256Sign(messageKey.macKey, macInput);
+        const mac = fullMac.subarray(0, SIGNAL_MAC_SIZE);
+        const inner = concatBytes([versioned, mac]);
+        this.sendChain = {
+            ...this.sendChain,
+            chainKey: nextChainKey,
+            nextIndex: messageKey.index + 1
+        };
+        if (this.pendingPreKeyHeader) {
+            const header = this.pendingPreKeyHeader;
+            this.pendingPreKeyHeader = null;
+            const preKeyMessage = proto.PreKeySignalMessage.encode({
+                registrationId: this.keyBundle.registrationId,
+                preKeyId: header.preKeyId,
+                signedPreKeyId: header.signedPreKeyId,
+                baseKey: header.baseKey,
+                identityKey: this.localIdentityPubSerialized,
+                message: inner
+            }).finish();
+            return {
+                type: 'pkmsg',
+                ciphertext: prependVersion(preKeyMessage, SIGNAL_VERSION)
+            };
+        }
+        return { type: 'msg', ciphertext: inner };
+    }
+    async decryptPreKeyMessage(envelope) {
+        const body = readVersionedBody(envelope);
+        const preKeyMessage = proto.PreKeySignalMessage.decode(body);
+        const baseKey = requireBytes(preKeyMessage.baseKey, 'baseKey');
+        const remoteIdentity = requireBytes(preKeyMessage.identityKey, 'identityKey');
+        const innerMessage = requireBytes(preKeyMessage.message, 'message');
+        const signedPreKeyId = preKeyMessage.signedPreKeyId;
+        if (signedPreKeyId === null || signedPreKeyId === undefined) {
+            throw new FakePeerDoubleRatchetError('PreKeySignalMessage missing signedPreKeyId');
+        }
+        if (signedPreKeyId !== this.keyBundle.signedPreKey.id) {
+            throw new FakePeerDoubleRatchetError(`signedPreKeyId mismatch: got ${signedPreKeyId}, expected ${this.keyBundle.signedPreKey.id}`);
+        }
+        const oneTimePreKeyId = preKeyMessage.preKeyId;
+        let oneTimePrivKey = null;
+        if (oneTimePreKeyId !== null && oneTimePreKeyId !== undefined) {
+            const entry = this.keyBundle.oneTimePreKeys.find((k) => k.id === oneTimePreKeyId);
+            if (!entry) {
+                throw new FakePeerDoubleRatchetError(`unknown one-time preKeyId ${oneTimePreKeyId}`);
+            }
+            oneTimePrivKey = entry.keyPair.privKey;
+        }
+        const remoteIdentityRaw = toRawPubKey(remoteIdentity);
+        const baseKeyRaw = toRawPubKey(baseKey);
+        const signedPriv = this.keyBundle.signedPreKey.keyPair.privKey;
+        const identityPriv = this.keyBundle.identityKeyPair.privKey;
+        const [dh1, dh2, dh3, dh4] = await Promise.all([
+            X25519.scalarMult(signedPriv, remoteIdentityRaw),
+            X25519.scalarMult(identityPriv, baseKeyRaw),
+            X25519.scalarMult(signedPriv, baseKeyRaw),
+            oneTimePrivKey
+                ? X25519.scalarMult(oneTimePrivKey, baseKeyRaw)
+                : Promise.resolve(null)
+        ]);
+        const sharedParts = [SIGNAL_PREFIX_FF, dh1, dh2, dh3];
+        if (dh4)
+            sharedParts.push(dh4);
+        const shared = concatBytes(sharedParts);
+        const [rootKey, chainKey] = hkdfSplit(shared, null, WHISPER_TEXT_INFO);
+        this.remoteIdentityPubSerialized = toSerializedPubKey(remoteIdentity);
+        this.rootKey = rootKey;
+        this.bootstrapChainKey = chainKey;
+        return this.decryptInnerSignalMessage(innerMessage, /* isBootstrap */ true);
+    }
+    async decryptMessage(envelope) {
+        return this.decryptInnerSignalMessage(envelope, /* isBootstrap */ false);
+    }
+    async decryptInnerSignalMessage(signalMessageBytes, isBootstrap) {
+        if (signalMessageBytes.byteLength < 1 + SIGNAL_MAC_SIZE) {
+            throw new FakePeerDoubleRatchetError('signal message too short');
+        }
+        const versionByte = signalMessageBytes[0];
+        if (versionByte >>> 4 !== SIGNAL_VERSION) {
+            throw new FakePeerDoubleRatchetError(`unsupported signal version ${versionByte >>> 4}`);
+        }
+        const macStart = signalMessageBytes.byteLength - SIGNAL_MAC_SIZE;
+        const versionedBody = signalMessageBytes.subarray(0, macStart);
+        const macBytes = signalMessageBytes.subarray(macStart);
+        const protoBody = versionedBody.subarray(1);
+        const signalMessage = proto.SignalMessage.decode(protoBody);
+        const ratchetKey = requireBytes(signalMessage.ratchetKey, 'ratchetKey');
+        const counter = signalMessage.counter;
+        if (counter === null || counter === undefined) {
+            throw new FakePeerDoubleRatchetError('SignalMessage missing counter');
+        }
+        const ciphertext = requireBytes(signalMessage.ciphertext, 'ciphertext');
+        const ratchetSerialized = toSerializedPubKey(ratchetKey);
+        if (isBootstrap) {
+            if (!this.rootKey || !this.bootstrapChainKey) {
+                throw new FakePeerDoubleRatchetError('bootstrap state missing');
+            }
+            const ratchetShared = await X25519.scalarMult(this.keyBundle.signedPreKey.keyPair.privKey, toRawPubKey(ratchetKey));
+            const [nextRootKey, recvChainKey] = hkdfSplit(ratchetShared, this.rootKey, WHISPER_RATCHET_INFO);
+            this.rootKey = nextRootKey;
+            this.bootstrapChainKey = null;
+            this.recvChain = {
+                ratchetPubKey: ratchetSerialized,
+                chainKey: recvChainKey,
+                nextIndex: 0,
+                unusedKeys: []
+            };
+            await this.rotateSendRatchet(ratchetKey);
+        }
+        else if (!this.recvChain ||
+            !uint8Equal(this.recvChain.ratchetPubKey, ratchetSerialized)) {
+            await this.runRecvRatchetStep(ratchetKey);
+        }
+        if (!this.recvChain) {
+            throw new FakePeerDoubleRatchetError('recv chain not initialized');
+        }
+        let messageKey = null;
+        if (counter < this.recvChain.nextIndex) {
+            const stashedIndex = this.recvChain.unusedKeys.findIndex((entry) => entry.index === counter);
+            if (stashedIndex === -1) {
+                throw new FakePeerDoubleRatchetError(`recv counter ${counter} is stale (next=${this.recvChain.nextIndex})`);
+            }
+            const stashed = this.recvChain.unusedKeys[stashedIndex];
+            messageKey = {
+                cipherKey: stashed.cipherKey,
+                macKey: stashed.macKey,
+                iv: stashed.iv
+            };
+            this.recvChain = {
+                ratchetPubKey: this.recvChain.ratchetPubKey,
+                chainKey: this.recvChain.chainKey,
+                nextIndex: this.recvChain.nextIndex,
+                unusedKeys: this.recvChain.unusedKeys.filter((_, i) => i !== stashedIndex)
+            };
+        }
+        else {
+            const skipDistance = counter - this.recvChain.nextIndex;
+            if (skipDistance > MAX_FUTURE_RECV_KEYS) {
+                throw new FakePeerDoubleRatchetError(`recv counter ${counter} is too far in the future (skip=${skipDistance})`);
+            }
+            let chainKey = this.recvChain.chainKey;
+            const newlyStashed = [];
+            let walkIndex = this.recvChain.nextIndex;
+            while (walkIndex <= counter) {
+                const derived = deriveMessageKeyFromChain(chainKey);
+                chainKey = derived.nextChainKey;
+                if (walkIndex === counter) {
+                    messageKey = derived.messageKey;
+                }
+                else {
+                    newlyStashed.push({
+                        index: walkIndex,
+                        cipherKey: derived.messageKey.cipherKey,
+                        macKey: derived.messageKey.macKey,
+                        iv: derived.messageKey.iv
+                    });
+                }
+                walkIndex += 1;
+            }
+            const allUnused = [...this.recvChain.unusedKeys, ...newlyStashed];
+            const trimmed = allUnused.length > MAX_FUTURE_RECV_KEYS
+                ? allUnused.slice(allUnused.length - MAX_FUTURE_RECV_KEYS)
+                : allUnused;
+            this.recvChain = {
+                ratchetPubKey: this.recvChain.ratchetPubKey,
+                chainKey,
+                nextIndex: walkIndex,
+                unusedKeys: trimmed
+            };
+        }
+        if (!messageKey) {
+            throw new FakePeerDoubleRatchetError('failed to derive recv message key');
+        }
+        if (!this.remoteIdentityPubSerialized) {
+            throw new FakePeerDoubleRatchetError('remoteIdentityPub not set');
+        }
+        const macInput = concatBytes([
+            this.remoteIdentityPubSerialized,
+            this.localIdentityPubSerialized,
+            versionedBody
+        ]);
+        const expectedFullMac = hmacSha256Sign(messageKey.macKey, macInput);
+        const expectedMac = expectedFullMac.subarray(0, SIGNAL_MAC_SIZE);
+        if (!uint8Equal(expectedMac, macBytes)) {
+            throw new FakePeerDoubleRatchetError('signal message MAC mismatch');
+        }
+        const padded = aesCbcDecrypt(messageKey.cipherKey, messageKey.iv, ciphertext);
+        return unpadPkcs7(padded);
+    }
+    async runRecvRatchetStep(remoteRatchetPub) {
+        if (!this.rootKey) {
+            throw new FakePeerDoubleRatchetError('cannot run recv DR step: no root key');
+        }
+        if (!this.sendChain) {
+            throw new FakePeerDoubleRatchetError('cannot run recv DR step: no current local ratchet (alice has not initiated)');
+        }
+        const remoteRatchetRaw = toRawPubKey(remoteRatchetPub);
+        const ratchetShared = await X25519.scalarMult(this.sendChain.ratchetKeyPair.privKey, remoteRatchetRaw);
+        const [nextRootKey, recvChainKey] = hkdfSplit(ratchetShared, this.rootKey, WHISPER_RATCHET_INFO);
+        this.rootKey = nextRootKey;
+        this.recvChain = {
+            ratchetPubKey: toSerializedPubKey(remoteRatchetPub),
+            chainKey: recvChainKey,
+            nextIndex: 0,
+            unusedKeys: []
+        };
+        await this.rotateSendRatchet(remoteRatchetPub);
+    }
+    async rotateSendRatchet(remoteRatchetPub) {
+        if (!this.rootKey) {
+            throw new FakePeerDoubleRatchetError('cannot rotate send ratchet: no root key');
+        }
+        const newRatchet = await X25519.generateKeyPair();
+        const ratchetShared = await X25519.scalarMult(newRatchet.privKey, toRawPubKey(remoteRatchetPub));
+        const [nextRootKey, sendChainKey] = hkdfSplit(ratchetShared, this.rootKey, WHISPER_RATCHET_INFO);
+        this.rootKey = nextRootKey;
+        this.sendChain = {
+            ratchetKeyPair: newRatchet,
+            ratchetPubSerialized: toSerializedPubKey(newRatchet.pubKey),
+            chainKey: sendChainKey,
+            nextIndex: 0
+        };
+        this.hasOutboundSendChain = true;
+    }
+}
+function deriveMessageKey(index, chainKey) {
+    const messageInputKey = hmacSha256Sign(chainKey, MESSAGE_KEY_LABEL);
+    const nextChainRaw = hmacSha256Sign(chainKey, CHAIN_KEY_LABEL);
+    const expanded = hkdf(messageInputKey, null, WHISPER_MESSAGE_KEYS_INFO, 80);
+    return {
+        nextChainKey: nextChainRaw.subarray(0, 32),
+        messageKey: {
+            index,
+            cipherKey: expanded.subarray(0, 32),
+            macKey: expanded.subarray(32, 64),
+            iv: expanded.subarray(64, 80)
+        }
+    };
+}
+function deriveMessageKeyFromChain(chainKey) {
+    const result = deriveMessageKey(0, chainKey);
+    return {
+        nextChainKey: result.nextChainKey,
+        messageKey: {
+            cipherKey: result.messageKey.cipherKey,
+            macKey: result.messageKey.macKey,
+            iv: result.messageKey.iv
+        }
+    };
+}
+function readVersionedBody(envelope) {
+    if (envelope.byteLength < 1) {
+        throw new FakePeerDoubleRatchetError('signal envelope is empty');
+    }
+    const version = envelope[0] >>> 4;
+    if (version !== SIGNAL_VERSION) {
+        throw new FakePeerDoubleRatchetError(`unsupported signal version ${version}`);
+    }
+    return envelope.subarray(1);
+}
+function unpadPkcs7(padded) {
+    if (padded.byteLength === 0)
+        return padded;
+    const padLen = padded[padded.byteLength - 1];
+    if (padLen === 0 || padLen > 16)
+        return padded;
+    if (padLen > padded.byteLength)
+        return padded;
+    return padded.subarray(0, padded.byteLength - padLen);
+}
+function uint8Equal(a, b) {
+    if (a.byteLength !== b.byteLength)
+        return false;
+    for (let i = 0; i < a.byteLength; i += 1) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+function concatBytes(parts) {
+    let total = 0;
+    for (const p of parts)
+        total += p.byteLength;
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const p of parts) {
+        out.set(p, offset);
+        offset += p.byteLength;
+    }
+    return out;
+}
+function requireBytes(value, label) {
+    if (!value)
+        throw new FakePeerDoubleRatchetError(`${label} missing`);
+    return value;
+}