zapo-js 0.2.0 → 1.0.0

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

@@ -1,11 +1,12 @@
-import { aesCbcDecrypt, aesCbcEncrypt, hkdf, importAesCbcKey, importHmacKey, hmacSign, 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 { detachSession, calculateRatchet, 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');
     }
@@ -16,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) {
@@ -35,7 +32,7 @@ export async function selectMessageKey(chain, targetCounter) {
         if (idx === -1) {
             throw new Error('duplicate message');
         }
-        const messageKey = unused[idx];
+        const messageKey = decodeSignalMessageKey(unused[idx], `unusedMsgKeys[${idx}]`);
         const nextUnused = removeAt(unused, idx);
         return {
             messageKey,
@@ -47,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
             }
         };
@@ -73,55 +70,41 @@ export async function selectMessageKey(chain, targetCounter) {
             overflow -= 1;
         }
         else {
-            nextUnused.push(currentMessageKey);
+            nextUnused.push({
+                index: currentMessageKey.index,
+                cipherKey: currentMessageKey.cipherKey,
+                macKey: currentMessageKey.macKey,
+                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,
@@ -129,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;
@@ -174,13 +156,14 @@ export async function decryptMsg(session, parsed, onPrevSessionDecryptError) {
     }
     catch (error) {
         for (let i = 0; i < session.prevSessions.length; i += 1) {
-            const prevSession = snapshotToRecord(session.prevSessions[i]);
+            const decodedPrev = decodeSignalSessionSnapshot(session.prevSessions[i], `prevSessions[${i}]`);
+            const prevSession = snapshotToRecord(decodedPrev);
             try {
                 const [updatedPrev, plaintext] = await decryptMsgFromSession(prevSession, parsed);
                 const updatedSession = {
                     ...updatedPrev,
                     prevSessions: [
-                        detachSession(session),
+                        encodeSignalSessionSnapshot(session),
                         ...session.prevSessions.slice(0, i),
                         ...session.prevSessions.slice(i + 1)
                     ]
@@ -207,7 +190,10 @@ export async function decryptMsg(session, parsed, onPrevSessionDecryptError) {
 }
 export async function decryptMsgFromSession(session, message) {
     const ratchetPubKey = toSerializedPubKey(message.ratchetPubKey);
-    const recvChainIndex = session.recvChains.findIndex((entry) => uint8Equal(entry.ratchetPubKey, ratchetPubKey));
+    const recvChainIndex = session.recvChains.findIndex((raw) => {
+        const key = raw.senderRatchetKey;
+        return key !== null && key !== undefined && uint8Equal(key, ratchetPubKey);
+    });
     let selectedMessageKey;
     let updatedSession;
     if (recvChainIndex === -1) {
@@ -225,7 +211,7 @@ export async function decryptMsgFromSession(session, message) {
         selectedMessageKey = selected.messageKey;
         const sendRatchet = await calculateRatchet(recvRatchet.rootKey, newSendRatchet, ratchetPubKey);
         const nextRecvChains = session.recvChains.slice(-MAX_TRACKED_RECV_CHAINS);
-        nextRecvChains.push(selected.updatedChain);
+        nextRecvChains.push(encodeSignalRecvChain(selected.updatedChain));
         updatedSession = {
             ...session,
             rootKey: sendRatchet.rootKey,
@@ -240,30 +226,26 @@ export async function decryptMsgFromSession(session, message) {
         };
     }
     else {
-        const selected = await selectMessageKey(session.recvChains[recvChainIndex], message.counter);
+        const decoded = decodeSignalRecvChain(session.recvChains[recvChainIndex], `recvChains[${recvChainIndex}]`);
+        const selected = await selectMessageKey(decoded, message.counter);
         selectedMessageKey = selected.messageKey;
         const nextRecvChains = session.recvChains.slice();
-        nextRecvChains[recvChainIndex] = selected.updatedChain;
+        nextRecvChains[recvChainIndex] = encodeSignalRecvChain(selected.updatedChain);
         updatedSession = {
             ...session,
             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/SignalSerializer.js

@@ -1,7 +1,6 @@
 import { readVersionedContent, toSerializedPubKey } from '../../crypto/index.js';
 import { proto } from '../../proto.js';
 import { SIGNAL_MAC_SIZE, SIGNAL_VERSION } from '../constants.js';
-import { toBytesView } from '../../util/bytes.js';
 export function deserializeMsg(versionContentMac) {
     const content = readVersionedContent(versionContentMac, SIGNAL_VERSION, SIGNAL_MAC_SIZE);
     const parsed = proto.SignalMessage.decode(content);
@@ -14,9 +13,9 @@ export function deserializeMsg(versionContentMac) {
         throw new Error('invalid signal message');
     }
     return {
-        ratchetPubKey: toSerializedPubKey(toBytesView(parsed.ratchetKey)),
+        ratchetPubKey: toSerializedPubKey(parsed.ratchetKey),
         counter: parsed.counter,
-        ciphertext: toBytesView(parsed.ciphertext),
+        ciphertext: parsed.ciphertext,
         versionContentMac
     };
 }
@@ -35,14 +34,14 @@ export function deserializePkMsg(versionContent) {
         parsed.message === undefined) {
         throw new Error('invalid prekey signal message');
     }
-    const signal = deserializeMsg(toBytesView(parsed.message));
+    const signal = deserializeMsg(parsed.message);
     return {
         ...signal,
         remote: {
             regId: parsed.registrationId,
-            pubKey: toSerializedPubKey(toBytesView(parsed.identityKey))
+            pubKey: toSerializedPubKey(parsed.identityKey)
         },
-        sessionBaseKey: toSerializedPubKey(toBytesView(parsed.baseKey)),
+        sessionBaseKey: toSerializedPubKey(parsed.baseKey),
         localSignedPreKeyId: parsed.signedPreKeyId,
         localOneTimeKeyId: parsed.preKeyId ?? null
     };

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

@@ -1,5 +1,6 @@
 import { hkdfSplit, toRawPubKey, toSerializedPubKey, X25519 } from '../../crypto/index.js';
-import { SIGNAL_PREFIX } from '../constants.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 {
@@ -7,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;
@@ -21,19 +17,19 @@ export function findMatchingSession(session, sessionBaseKey) {
         return session;
     }
     for (let index = 0; index < session.prevSessions.length; index += 1) {
-        const previousSession = session.prevSessions[index];
-        if (!previousSession.aliceBaseKey ||
-            !uint8Equal(previousSession.aliceBaseKey, serializedBaseKey)) {
+        const rawPrev = session.prevSessions[index];
+        if (!rawPrev.aliceBaseKey || !uint8Equal(rawPrev.aliceBaseKey, serializedBaseKey)) {
             continue;
         }
-        const prevSessions = [detachSession(session)];
+        const decoded = decodeSignalSessionSnapshot(rawPrev, `prevSessions[${index}]`);
+        const prevSessions = [encodeSignalSessionSnapshot(session)];
         for (let i = 0; i < session.prevSessions.length; i += 1) {
             if (i !== index) {
                 prevSessions.push(session.prevSessions[i]);
             }
         }
         return {
-            ...previousSession,
+            ...decoded,
             prevSessions
         };
     }
@@ -71,12 +67,11 @@ 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 = {
-        ratchetPubKey: remoteRatchetKey,
-        nextMsgIndex: 0,
-        chainKey,
-        unusedMsgKeys: []
+        senderRatchetKey: remoteRatchetKey,
+        chainKey: { index: 0, key: chainKey },
+        messageKeys: []
     };
     const sendRatchet = await generateSerializedKeyPair();
     const sendRatchetResult = await calculateRatchet(rootKey, sendRatchet, remoteRatchetKey);
@@ -118,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 },
@@ -137,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
@@ -154,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');
+}