zapo-js 0.3.0 → 1.0.0

package/dist/esm/signal/registration/utils.js

@@ -1,4 +1,9 @@
 import { generatePreKeyPair, generateRegistrationInfo, generateSignedPreKey } from '../registration/keygen.js';
+/**
+ * Bootstraps a fresh Signal identity: generates registration info, the first
+ * signed prekey, and the first one-time prekey, then persists them in order
+ * so a partial commit can never split bootstrap state.
+ */
 export async function createAndStoreInitialKeys(store, preKeyStore) {
     const [registrationInfo, firstPreKey] = await Promise.all([
         generateRegistrationInfo(),
@@ -8,6 +13,7 @@ export async function createAndStoreInitialKeys(store, preKeyStore) {
     // Keep writes ordered so partial commit failures don't leave split registration bootstrap state.
     await store.setRegistrationInfo(registrationInfo);
     await store.setSignedPreKey(signedPreKey);
+    // eslint-disable-next-line @typescript-eslint/require-await
     await preKeyStore.getOrGenSinglePreKey(async () => firstPreKey);
     return {
         registrationInfo,

package/dist/esm/signal/session/SignalProtocol.js

@@ -1,27 +1,37 @@
 import { toSerializedPubKey } from '../../crypto/index.js';
 import { ConsoleLogger } from '../../infra/log/ConsoleLogger.js';
 import { StoreLock } from '../../infra/perf/StoreLock.js';
+import { signalAddressKey } from '../../protocol/jid.js';
 import { MAX_PREV_SESSIONS } from '../constants.js';
-import { encodeSignalSessionSnapshot } from '../encoding.js';
+import { encodeSignalSessionSnapshot } from '../session/encoding.js';
 import { decryptMsg, decryptMsgFromSession, encryptMsg } from '../session/SignalRatchet.js';
 import { deserializeMsg, deserializePkMsg, requirePreKey, requireSignedPreKey } from '../session/SignalSerializer.js';
-import { detachSession, findMatchingSession, generateSerializedKeyPair, initiateSessionIncoming, initiateSessionOutgoing, requireLocalIdentity, toSerializedKeyPair } from '../session/SignalSession.js';
+import { findMatchingSession, generateSerializedKeyPair, initiateSessionIncoming, initiateSessionOutgoing, requireLocalIdentity, toSerializedKeyPair } from '../session/SignalSession.js';
 import { uint8Equal } from '../../util/bytes.js';
-function signalAddressMapKey(address) {
-    return `${address.user}\u0001${address.server ?? ''}\u0001${address.device}`;
-}
 function signalAddressLockKey(address) {
-    return `signal:${signalAddressMapKey(address)}`;
+    return `signal:${signalAddressKey(address)}`;
 }
+/**
+ * High-level Signal protocol session orchestrator: establishes outgoing
+ * sessions from prekey bundles, encrypts/decrypts ratchet messages, and owns
+ * the per-address session mutation lock.
+ */
 export class SignalProtocol {
     constructor(stores, logger = new ConsoleLogger('info')) {
         this.stores = stores;
         this.logger = logger;
         this.sessionMutationLock = new StoreLock();
     }
+    /**
+     * Builds an outgoing Signal session against a remote prekey bundle. Set
+     * `options.reuseExisting` to skip the handshake when a session already
+     * exists for the same remote identity. Set `options.knownAbsent` only
+     * when the caller already proved (within the same logical step) that no
+     * session exists; it skips the in-lock recheck and forces a new handshake.
+     */
     async establishOutgoingSession(address, remoteBundle, options = {}) {
         return this.runWithAddressLock(address, async () => {
-            if (options.reuseExisting) {
+            if (options.reuseExisting && !options.knownAbsent) {
                 const existing = await this.stores.session.getSession(address);
                 if (existing) {
                     const remoteIdentity = toSerializedPubKey(remoteBundle.identity);
@@ -42,12 +52,100 @@ export class SignalProtocol {
             return session;
         });
     }
+    /**
+     * Compute an outgoing session under the per-address lock without
+     * persisting. Caller batches results and persists via
+     * {@link persistOutgoingSessionsBatch} to collapse N `setRemoteIdentity`
+     * + `setSession` round-trips into one bulk write per store.
+     */
+    async prepareOutgoingSession(address, remoteBundle, options = {}) {
+        return this.runWithAddressLock(address, async () => {
+            if (options.reuseExisting && !options.knownAbsent) {
+                const existing = await this.stores.session.getSession(address);
+                if (existing) {
+                    const remoteIdentity = toSerializedPubKey(remoteBundle.identity);
+                    if (!uint8Equal(existing.remote.pubKey, remoteIdentity)) {
+                        throw new Error('identity mismatch');
+                    }
+                    return {
+                        session: existing,
+                        remoteIdentity: existing.remote.pubKey,
+                        reusedExisting: true
+                    };
+                }
+            }
+            const [local, localOneTimeBase] = await Promise.all([
+                requireLocalIdentity(this.stores.signal),
+                generateSerializedKeyPair()
+            ]);
+            const session = await initiateSessionOutgoing(local, remoteBundle, localOneTimeBase);
+            return {
+                session,
+                remoteIdentity: session.remote.pubKey,
+                reusedExisting: false
+            };
+        });
+    }
+    /**
+     * Persist prepared outgoing sessions while holding every per-address
+     * lock (same discipline as {@link encryptMessagesBatch}). Re-reads
+     * sessions inside the lock; defers to a concurrent writer's session
+     * when identities agree to avoid clobbering a fresher ratchet advance,
+     * and reports identity conflicts via `skipped`.
+     */
+    async persistOutgoingSessionsBatch(entries) {
+        if (entries.length === 0)
+            return { resolved: [], skipped: [] };
+        const lockKeys = new Array(entries.length);
+        for (let i = 0; i < entries.length; i += 1) {
+            lockKeys[i] = signalAddressLockKey(entries[i].address);
+        }
+        return this.sessionMutationLock.runMany(lockKeys, async () => {
+            const addresses = entries.map((e) => e.address);
+            const existingSessions = await this.stores.session.getSessionsBatch(addresses);
+            const identityUpdates = [];
+            const sessionUpdates = [];
+            const resolved = [];
+            const skipped = [];
+            for (let i = 0; i < entries.length; i += 1) {
+                const entry = entries[i];
+                const existing = existingSessions[i];
+                if (existing) {
+                    if (uint8Equal(existing.remote.pubKey, entry.remoteIdentity)) {
+                        resolved.push({ address: entry.address, session: existing });
+                        continue;
+                    }
+                    skipped.push({ address: entry.address, reason: 'identity-mismatch' });
+                    continue;
+                }
+                identityUpdates.push({
+                    address: entry.address,
+                    identityKey: entry.remoteIdentity
+                });
+                sessionUpdates.push({ address: entry.address, session: entry.session });
+                resolved.push({ address: entry.address, session: entry.session });
+            }
+            if (identityUpdates.length > 0) {
+                await this.stores.identity.setRemoteIdentities(identityUpdates);
+            }
+            if (sessionUpdates.length > 0) {
+                await this.stores.session.setSessionsBatch(sessionUpdates);
+            }
+            return { resolved, skipped };
+        });
+    }
+    /**
+     * Encrypts `plaintext` for `address`. Returns `pkmsg` when this is the
+     * first message of the session, `msg` otherwise. `expectedIdentity`
+     * enforces identity continuity.
+     */
     async encryptMessage(address, plaintext, expectedIdentity) {
         const [encrypted] = await this.encryptMessagesBatch([
             { address, plaintext, expectedIdentity }
         ]);
         return encrypted;
     }
+    /** Batch variant of {@link encryptMessage} that shares per-address locks. */
     async encryptMessagesBatch(requests, prefetchedSessions) {
         if (requests.length === 0) {
             return [];
@@ -61,7 +159,7 @@ export class SignalProtocol {
             if (prefetchedSessions && prefetchedSessions.length > 0) {
                 for (let index = 0; index < prefetchedSessions.length; index += 1) {
                     const entry = prefetchedSessions[index];
-                    prefetchedByAddress.set(signalAddressMapKey(entry.address), entry.session);
+                    prefetchedByAddress.set(signalAddressKey(entry.address), entry.session);
                 }
             }
             const uniqueAddressKeys = new Array(requests.length);
@@ -69,7 +167,7 @@ export class SignalProtocol {
             let uniqueAddressCount = 0;
             for (let index = 0; index < requests.length; index += 1) {
                 const address = requests[index].address;
-                const addressKey = signalAddressMapKey(address);
+                const addressKey = signalAddressKey(address);
                 let isDuplicate = false;
                 for (let dedupIndex = 0; dedupIndex < uniqueAddressCount; dedupIndex += 1) {
                     if (uniqueAddressKeys[dedupIndex] === addressKey) {
@@ -106,7 +204,7 @@ export class SignalProtocol {
             for (let index = 0; index < requests.length; index += 1) {
                 const request = requests[index];
                 const address = request.address;
-                const addressKey = signalAddressMapKey(address);
+                const addressKey = signalAddressKey(address);
                 const session = latestSessionByAddress.get(addressKey);
                 if (!session) {
                     throw new Error('signal session not found');
@@ -152,6 +250,10 @@ export class SignalProtocol {
             return results;
         });
     }
+    /**
+     * Decrypts a Signal message (`msg` or `pkmsg`) from `address`. For
+     * `pkmsg`, instantiates the session from the embedded bundle when needed.
+     */
     async decryptMessage(address, envelope) {
         return this.runWithAddressLock(address, async () => {
             const currentSession = await this.stores.session.getSession(address);
@@ -211,7 +313,7 @@ export class SignalProtocol {
             ? {
                 ...incoming,
                 prevSessions: [
-                    encodeSignalSessionSnapshot(detachSession(currentSession)),
+                    encodeSignalSessionSnapshot(currentSession),
                     ...currentSession.prevSessions.slice(0, MAX_PREV_SESSIONS - 1)
                 ]
             }

package/dist/esm/signal/session/SignalRatchet.js

@@ -1,12 +1,12 @@
-import { aesCbcDecrypt, aesCbcEncrypt, hkdf, hmacSign, importAesCbcKey, importHmacKey, prependVersion, toSerializedPubKey } from '../../crypto/index.js';
+import { aesCbcDecrypt, aesCbcEncrypt, hkdf, hmacSha256Sign, prependVersion, toSerializedPubKey } from '../../crypto/index.js';
 import { proto } from '../../proto.js';
-import { CHAIN_KEY_LABEL, FUTURE_MESSAGES_MAX, MAX_UNUSED_KEYS, MESSAGE_KEY_LABEL, SIGNAL_MAC_SIZE, SIGNAL_VERSION } from '../constants.js';
-import { decodeSignalMessageKey, decodeSignalRecvChain, decodeSignalSessionSnapshot, encodeSignalRecvChain, encodeSignalSessionSnapshot } from '../encoding.js';
-import { calculateRatchet, detachSession, generateSerializedKeyPair, snapshotToRecord } from '../session/SignalSession.js';
-import { concatBytes, removeAt, uint8Equal } from '../../util/bytes.js';
+import { CHAIN_KEY_LABEL, FUTURE_MESSAGES_MAX, MAX_UNUSED_KEYS, MESSAGE_KEY_LABEL, SIGNAL_MAC_SIZE, SIGNAL_VERSION, WHISPER_MESSAGE_KEYS_INFO } from '../constants.js';
+import { decodeSignalMessageKey, decodeSignalRecvChain, decodeSignalSessionSnapshot, encodeSignalRecvChain, encodeSignalSessionSnapshot } from '../session/encoding.js';
+import { calculateRatchet, generateSerializedKeyPair, snapshotToRecord } from '../session/SignalSession.js';
+import { concatBytes, removeAt, uint8Equal, uint8TimingSafeEqual } from '../../util/bytes.js';
 import { toError } from '../../util/primitives.js';
 const MAX_TRACKED_RECV_CHAINS = 4;
-export function splitMsgKey(index, bytes) {
+function splitMsgKey(index, bytes) {
     if (bytes.length < 80) {
         throw new Error('invalid message key length');
     }
@@ -17,14 +17,10 @@ export function splitMsgKey(index, bytes) {
         iv: bytes.subarray(64, 80)
     };
 }
-export async function deriveMsgKey(index, chainKey) {
-    const state = await createDerivedChainState(chainKey);
-    const derived = await deriveMsgKeyFromState(index, state);
-    return {
-        nextChainKey: derived.nextState.chainKey,
-        messageKey: derived.messageKey
-    };
+export function deriveMsgKey(index, chainKey) {
+    return deriveMsgKeyFromChainKey(index, chainKey);
 }
+// eslint-disable-next-line @typescript-eslint/require-await
 export async function selectMessageKey(chain, targetCounter) {
     const delta = targetCounter - chain.nextMsgIndex;
     if (delta > FUTURE_MESSAGES_MAX) {
@@ -48,17 +44,17 @@ export async function selectMessageKey(chain, targetCounter) {
             }
         };
     }
-    let chainState = await createDerivedChainState(chain.chainKey);
-    const first = await deriveMsgKeyFromState(chain.nextMsgIndex, chainState);
+    let chainKey = chain.chainKey;
+    const first = deriveMsgKeyFromChainKey(chain.nextMsgIndex, chainKey);
     let currentMessageKey = first.messageKey;
-    chainState = first.nextState;
+    chainKey = first.nextChainKey;
     if (delta === 0) {
         return {
             messageKey: currentMessageKey,
             updatedChain: {
                 ratchetPubKey: chain.ratchetPubKey,
                 nextMsgIndex: targetCounter + 1,
-                chainKey: chainState.chainKey,
+                chainKey,
                 unusedMsgKeys: unused
             }
         };
@@ -81,53 +77,34 @@ export async function selectMessageKey(chain, targetCounter) {
                 iv: currentMessageKey.iv
             });
         }
-        const derived = await deriveMsgKeyFromState(counter, chainState);
+        const derived = deriveMsgKeyFromChainKey(counter, chainKey);
         currentMessageKey = derived.messageKey;
-        chainState = derived.nextState;
+        chainKey = derived.nextChainKey;
     }
     return {
         messageKey: currentMessageKey,
         updatedChain: {
             ratchetPubKey: chain.ratchetPubKey,
             nextMsgIndex: targetCounter + 1,
-            chainKey: chainState.chainKey,
+            chainKey,
             unusedMsgKeys: nextUnused
         }
     };
 }
-async function createDerivedChainState(chainKey) {
-    return {
-        chainKey,
-        hmacKey: await importHmacKey(chainKey)
-    };
-}
-async function deriveMsgKeyFromState(index, state) {
-    const nextChainRawPromise = hmacSign(state.hmacKey, CHAIN_KEY_LABEL);
-    const messageInputKeyPromise = hmacSign(state.hmacKey, MESSAGE_KEY_LABEL);
-    const [nextChainRaw, messageInputKey] = await Promise.all([
-        nextChainRawPromise,
-        messageInputKeyPromise
-    ]);
+function deriveMsgKeyFromChainKey(index, chainKey) {
+    const nextChainRaw = hmacSha256Sign(chainKey, CHAIN_KEY_LABEL);
+    const messageInputKey = hmacSha256Sign(chainKey, MESSAGE_KEY_LABEL);
     const nextChainKey = nextChainRaw.subarray(0, 32);
-    const [nextHmacKey, expanded] = await Promise.all([
-        importHmacKey(nextChainKey),
-        hkdf(messageInputKey, null, 'WhisperMessageKeys', 80)
-    ]);
+    const expanded = hkdf(messageInputKey, null, WHISPER_MESSAGE_KEYS_INFO, 80);
     return {
-        nextState: {
-            chainKey: nextChainKey,
-            hmacKey: nextHmacKey
-        },
+        nextChainKey,
         messageKey: splitMsgKey(index, expanded)
     };
 }
+// eslint-disable-next-line @typescript-eslint/require-await
 export async function encryptMsg(session, plaintext) {
-    const { nextChainKey, messageKey } = await deriveMsgKey(session.sendChain.nextMsgIndex, session.sendChain.chainKey);
-    const [cipherKey, macKey] = await Promise.all([
-        importAesCbcKey(messageKey.cipherKey),
-        importHmacKey(messageKey.macKey)
-    ]);
-    const ciphertext = await aesCbcEncrypt(cipherKey, messageKey.iv, plaintext);
+    const { nextChainKey, messageKey } = deriveMsgKey(session.sendChain.nextMsgIndex, session.sendChain.chainKey);
+    const ciphertext = aesCbcEncrypt(messageKey.cipherKey, messageKey.iv, plaintext);
     const signalPayload = proto.SignalMessage.encode({
         ratchetKey: session.sendChain.ratchetKey.pubKey,
         counter: messageKey.index,
@@ -135,12 +112,11 @@ export async function encryptMsg(session, plaintext) {
         ciphertext
     }).finish();
     const versionedSignalPayload = prependVersion(signalPayload, SIGNAL_VERSION);
-    const macInput = concatBytes([
+    const mac = hmacSha256Sign(messageKey.macKey, [
         session.local.pubKey,
         session.remote.pubKey,
         versionedSignalPayload
     ]);
-    const mac = await hmacSign(macKey, macInput);
     const signalMessage = concatBytes([versionedSignalPayload, mac.subarray(0, SIGNAL_MAC_SIZE)]);
     let type = 'msg';
     let output = signalMessage;
@@ -187,7 +163,7 @@ export async function decryptMsg(session, parsed, onPrevSessionDecryptError) {
                 const updatedSession = {
                     ...updatedPrev,
                     prevSessions: [
-                        encodeSignalSessionSnapshot(detachSession(session)),
+                        encodeSignalSessionSnapshot(session),
                         ...session.prevSessions.slice(0, i),
                         ...session.prevSessions.slice(i + 1)
                     ]
@@ -260,21 +236,16 @@ export async function decryptMsgFromSession(session, message) {
             recvChains: nextRecvChains
         };
     }
-    const [cipherKey, macKey] = await Promise.all([
-        importAesCbcKey(selectedMessageKey.cipherKey),
-        importHmacKey(selectedMessageKey.macKey)
-    ]);
     const payloadWithoutMac = message.versionContentMac.subarray(0, message.versionContentMac.length - SIGNAL_MAC_SIZE);
-    const expectedMacInput = concatBytes([
+    const expectedMac = hmacSha256Sign(selectedMessageKey.macKey, [
         session.remote.pubKey,
         session.local.pubKey,
         payloadWithoutMac
     ]);
-    const expectedMac = await hmacSign(macKey, expectedMacInput);
     const receivedMac = message.versionContentMac.subarray(message.versionContentMac.length - SIGNAL_MAC_SIZE);
-    if (!uint8Equal(expectedMac.subarray(0, SIGNAL_MAC_SIZE), receivedMac)) {
+    if (!uint8TimingSafeEqual(expectedMac.subarray(0, SIGNAL_MAC_SIZE), receivedMac)) {
         throw new Error('invalid message mac');
     }
-    const plaintext = await aesCbcDecrypt(cipherKey, selectedMessageKey.iv, message.ciphertext);
+    const plaintext = aesCbcDecrypt(selectedMessageKey.cipherKey, selectedMessageKey.iv, message.ciphertext);
     return [updatedSession, plaintext];
 }

package/dist/esm/signal/session/SignalSession.js

@@ -1,6 +1,6 @@
 import { hkdfSplit, toRawPubKey, toSerializedPubKey, X25519 } from '../../crypto/index.js';
-import { SIGNAL_PREFIX } from '../constants.js';
-import { decodeSignalSessionSnapshot, encodeSignalSessionSnapshot } from '../encoding.js';
+import { SIGNAL_PREFIX, WHISPER_RATCHET_INFO, WHISPER_TEXT_INFO } from '../constants.js';
+import { decodeSignalSessionSnapshot, encodeSignalSessionSnapshot } from '../session/encoding.js';
 import { concatBytes, uint8Equal } from '../../util/bytes.js';
 export function snapshotToRecord(snapshot) {
     return {
@@ -8,11 +8,6 @@ export function snapshotToRecord(snapshot) {
         prevSessions: []
     };
 }
-export function detachSession(session) {
-    const { prevSessions, ...snapshot } = session;
-    void prevSessions;
-    return snapshot;
-}
 export function findMatchingSession(session, sessionBaseKey) {
     if (!session) {
         return null;
@@ -27,9 +22,7 @@ export function findMatchingSession(session, sessionBaseKey) {
             continue;
         }
         const decoded = decodeSignalSessionSnapshot(rawPrev, `prevSessions[${index}]`);
-        const prevSessions = [
-            encodeSignalSessionSnapshot(detachSession(session))
-        ];
+        const prevSessions = [encodeSignalSessionSnapshot(session)];
         for (let i = 0; i < session.prevSessions.length; i += 1) {
             if (i !== index) {
                 prevSessions.push(session.prevSessions[i]);
@@ -74,7 +67,7 @@ export async function initiateSessionOutgoing(local, remoteBundle, localOneTimeB
         baseDh,
         ...(oneTimeDh ? [oneTimeDh] : [])
     ]);
-    const [rootKey, chainKey] = await hkdfSplit(secret, null, 'WhisperText');
+    const [rootKey, chainKey] = hkdfSplit(secret, null, WHISPER_TEXT_INFO);
     const recvChain = {
         senderRatchetKey: remoteRatchetKey,
         chainKey: { index: 0, key: chainKey },
@@ -120,7 +113,7 @@ export async function initiateSessionIncoming(local, remote, sessionBaseKey, loc
         signedDh,
         ...(oneTimeDh ? [oneTimeDh] : [])
     ]);
-    const [rootKey, chainKey] = await hkdfSplit(secret, null, 'WhisperText');
+    const [rootKey, chainKey] = hkdfSplit(secret, null, WHISPER_TEXT_INFO);
     return {
         local: { regId: local.regId, pubKey: local.staticKeyPair.pubKey },
         remote: { regId: remote.regId, pubKey: remotePub },
@@ -139,7 +132,7 @@ export async function initiateSessionIncoming(local, remote, sessionBaseKey, loc
 }
 export async function calculateRatchet(rootKey, localRatchet, remoteRatchetPubKey) {
     const sharedSecret = await ecdh(localRatchet.privKey, remoteRatchetPubKey);
-    const [nextRootKey, chainKey] = await hkdfSplit(sharedSecret, rootKey, 'WhisperRatchet');
+    const [nextRootKey, chainKey] = hkdfSplit(sharedSecret, rootKey, WHISPER_RATCHET_INFO);
     return {
         rootKey: nextRootKey,
         chainKey
@@ -156,5 +149,5 @@ export function toSerializedKeyPair(pair) {
     };
 }
 export async function ecdh(privateKey, publicKey) {
-    return X25519.scalarMult(privateKey, toRawPubKey(publicKey));
+    return await X25519.scalarMult(privateKey, toRawPubKey(publicKey));
 }

package/dist/esm/signal/session/encoding.js

@@ -0,0 +1,173 @@
+import { proto } from '../../proto.js';
+import { assertByteLength } from '../../util/bytes.js';
+import { asBytes, asNumber, asOptionalBytes, asOptionalNumber } from '../../util/coercion.js';
+export function encodeSignalSessionSnapshot(session) {
+    return {
+        sessionVersion: 3,
+        localRegistrationId: session.local.regId,
+        localIdentityPublic: session.local.pubKey,
+        remoteRegistrationId: session.remote.regId,
+        remoteIdentityPublic: session.remote.pubKey,
+        rootKey: session.rootKey,
+        previousCounter: session.prevSendChainHighestIndex,
+        senderChain: encodeSignalSendChain(session.sendChain),
+        receiverChains: session.recvChains,
+        pendingPreKey: session.initialExchangeInfo
+            ? {
+                preKeyId: session.initialExchangeInfo.remoteOneTimeId ?? undefined,
+                signedPreKeyId: session.initialExchangeInfo.remoteSignedId,
+                baseKey: session.initialExchangeInfo.localOneTimePubKey
+            }
+            : undefined,
+        aliceBaseKey: session.aliceBaseKey ?? undefined
+    };
+}
+function encodeSignalSendChain(chain) {
+    return {
+        senderRatchetKey: chain.ratchetKey.pubKey,
+        senderRatchetKeyPrivate: chain.ratchetKey.privKey,
+        chainKey: {
+            index: chain.nextMsgIndex,
+            key: chain.chainKey
+        },
+        messageKeys: []
+    };
+}
+export function encodeSignalRecvChain(chain) {
+    return {
+        senderRatchetKey: chain.ratchetPubKey,
+        chainKey: {
+            index: chain.nextMsgIndex,
+            key: chain.chainKey
+        },
+        messageKeys: chain.unusedMsgKeys
+    };
+}
+export function decodeSignalMessageKey(messageKey, field) {
+    const cipherKey = asBytes(messageKey.cipherKey, `${field}.cipherKey`);
+    assertByteLength(cipherKey, 32, `invalid ${field}.cipherKey length ${cipherKey.byteLength}`);
+    const macKey = asBytes(messageKey.macKey, `${field}.macKey`);
+    assertByteLength(macKey, 32, `invalid ${field}.macKey length ${macKey.byteLength}`);
+    const iv = asBytes(messageKey.iv, `${field}.iv`);
+    assertByteLength(iv, 16, `invalid ${field}.iv length ${iv.byteLength}`);
+    return {
+        index: asNumber(messageKey.index, `${field}.index`),
+        cipherKey,
+        macKey,
+        iv
+    };
+}
+export function decodeSignalRecvChain(chain, field) {
+    const chainKey = chain.chainKey;
+    if (!chainKey) {
+        throw new Error(`missing ${field}.chainKey`);
+    }
+    const ratchetPubKey = asBytes(chain.senderRatchetKey, `${field}.senderRatchetKey`);
+    assertByteLength(ratchetPubKey, 33, `invalid ${field}.senderRatchetKey length ${ratchetPubKey.byteLength}`);
+    const chainKeyBytes = asBytes(chainKey.key, `${field}.chainKey.key`);
+    assertByteLength(chainKeyBytes, 32, `invalid ${field}.chainKey.key length ${chainKeyBytes.byteLength}`);
+    return {
+        ratchetPubKey,
+        nextMsgIndex: asNumber(chainKey.index, `${field}.chainKey.index`),
+        chainKey: chainKeyBytes,
+        unusedMsgKeys: chain.messageKeys ?? []
+    };
+}
+function decodeSignalSendChain(chain, field) {
+    const chainKey = chain.chainKey;
+    if (!chainKey) {
+        throw new Error(`missing ${field}.chainKey`);
+    }
+    const privateKey = asOptionalBytes(chain.senderRatchetKeyPrivate, `${field}.senderRatchetKeyPrivate`);
+    if (!privateKey) {
+        throw new Error(`missing ${field}.senderRatchetKeyPrivate`);
+    }
+    assertByteLength(privateKey, 32, `invalid ${field}.senderRatchetKeyPrivate length ${privateKey.byteLength}`);
+    const ratchetPubKey = asBytes(chain.senderRatchetKey, `${field}.senderRatchetKey`);
+    assertByteLength(ratchetPubKey, 33, `invalid ${field}.senderRatchetKey length ${ratchetPubKey.byteLength}`);
+    const chainKeyBytes = asBytes(chainKey.key, `${field}.chainKey.key`);
+    assertByteLength(chainKeyBytes, 32, `invalid ${field}.chainKey.key length ${chainKeyBytes.byteLength}`);
+    return {
+        ratchetKey: {
+            pubKey: ratchetPubKey,
+            privKey: privateKey
+        },
+        nextMsgIndex: asNumber(chainKey.index, `${field}.chainKey.index`),
+        chainKey: chainKeyBytes
+    };
+}
+export function decodeSignalSessionSnapshot(session, field) {
+    const senderChain = session.senderChain;
+    if (!senderChain) {
+        throw new Error(`missing ${field}.senderChain`);
+    }
+    const pendingPreKey = session.pendingPreKey;
+    const localPubKey = asBytes(session.localIdentityPublic, `${field}.localIdentityPublic`);
+    assertByteLength(localPubKey, 33, `invalid ${field}.localIdentityPublic length ${localPubKey.byteLength}`);
+    const remotePubKey = asBytes(session.remoteIdentityPublic, `${field}.remoteIdentityPublic`);
+    assertByteLength(remotePubKey, 33, `invalid ${field}.remoteIdentityPublic length ${remotePubKey.byteLength}`);
+    const rootKey = asBytes(session.rootKey, `${field}.rootKey`);
+    assertByteLength(rootKey, 32, `invalid ${field}.rootKey length ${rootKey.byteLength}`);
+    const localOneTimePubKey = pendingPreKey
+        ? asBytes(pendingPreKey.baseKey, `${field}.pendingPreKey.baseKey`)
+        : null;
+    if (localOneTimePubKey) {
+        assertByteLength(localOneTimePubKey, 33, `invalid ${field}.pendingPreKey.baseKey length ${localOneTimePubKey.byteLength}`);
+    }
+    const aliceBaseKey = asOptionalBytes(session.aliceBaseKey, `${field}.aliceBaseKey`) ?? null;
+    if (aliceBaseKey) {
+        assertByteLength(aliceBaseKey, 33, `invalid ${field}.aliceBaseKey length ${aliceBaseKey.byteLength}`);
+    }
+    return {
+        local: {
+            regId: asNumber(session.localRegistrationId, `${field}.localRegistrationId`),
+            pubKey: localPubKey
+        },
+        remote: {
+            regId: asNumber(session.remoteRegistrationId, `${field}.remoteRegistrationId`),
+            pubKey: remotePubKey
+        },
+        rootKey,
+        sendChain: decodeSignalSendChain(senderChain, `${field}.senderChain`),
+        recvChains: session.receiverChains ?? [],
+        initialExchangeInfo: pendingPreKey
+            ? {
+                remoteOneTimeId: asOptionalNumber(pendingPreKey.preKeyId, `${field}.pendingPreKey.preKeyId`) ??
+                    null,
+                remoteSignedId: asNumber(pendingPreKey.signedPreKeyId, `${field}.pendingPreKey.signedPreKeyId`),
+                localOneTimePubKey: localOneTimePubKey
+            }
+            : null,
+        prevSendChainHighestIndex: asOptionalNumber(session.previousCounter, `${field}.previousCounter`) ?? 0,
+        aliceBaseKey
+    };
+}
+/**
+ * Serializes a {@link SignalSessionRecord} (current + previous sessions) into
+ * the Signal `RecordStructure` protobuf encoding used by the session stores.
+ */
+export function encodeSignalSessionRecord(record) {
+    return proto.RecordStructure.encode({
+        currentSession: encodeSignalSessionSnapshot(record),
+        previousSessions: record.prevSessions
+    }).finish();
+}
+/**
+ * Decodes a Signal `RecordStructure` payload (as stored on disk) back into a
+ * {@link SignalSessionRecord}. Throws when the current session is missing.
+ */
+export function decodeSignalSessionRecord(raw) {
+    const decoded = proto.RecordStructure.decode(asBytes(raw, 'signal_sessions.record'));
+    if (!decoded.currentSession) {
+        throw new Error('missing signal_sessions.record.currentSession');
+    }
+    const current = decodeSignalSessionSnapshot(decoded.currentSession, 'signal_sessions.currentSession');
+    return {
+        ...current,
+        prevSessions: decoded.previousSessions ?? []
+    };
+}
+/** Reads a stored remote identity blob into a Uint8Array (validates byte-shape). */
+export function decodeSignalRemoteIdentity(raw) {
+    return asBytes(raw, 'signal_identity.identity_key');
+}