zapo-js 0.3.0 → 1.0.0

package/dist/esm/signal/encoding.js

@@ -1,7 +1,6 @@
-import { proto } from '../proto.js';
 import { WA_DEFAULTS } from '../protocol/constants.js';
-import { assertByteLength } from '../util/bytes.js';
-import { asBytes, asNumber, asOptionalBytes, asOptionalNumber, asString, toBoolOrUndef } from '../util/coercion.js';
+import { asNumber } from '../util/coercion.js';
+/** Flattens a {@link SignalAddress} into plain fields, defaulting `server` to the host domain. */
 export function toSignalAddressParts(address) {
     return {
         user: address.user,
@@ -9,292 +8,10 @@ export function toSignalAddressParts(address) {
         device: address.device
     };
 }
-export function decodeSignalAddressFromRow(row) {
-    return {
-        user: asString(row.sender_user, 'signal.sender_user'),
-        server: asString(row.sender_server, 'signal.sender_server'),
-        device: asNumber(row.sender_device, 'signal.sender_device')
-    };
-}
-export function decodeSignalRegistrationRow(row) {
-    return {
-        registrationId: asNumber(row.registration_id, 'signal_registration.registration_id'),
-        identityKeyPair: {
-            pubKey: asBytes(row.identity_pub_key, 'signal_registration.identity_pub_key'),
-            privKey: asBytes(row.identity_priv_key, 'signal_registration.identity_priv_key')
-        }
-    };
-}
-export function decodeSignalPreKeyRow(row) {
-    return {
-        keyId: asNumber(row.key_id, 'signal_prekey.key_id'),
-        keyPair: {
-            pubKey: asBytes(row.pub_key, 'signal_prekey.pub_key'),
-            privKey: asBytes(row.priv_key, 'signal_prekey.priv_key')
-        },
-        uploaded: toBoolOrUndef(row.uploaded)
-    };
-}
-export function decodeSignalSignedPreKeyRow(row) {
-    return {
-        keyId: asNumber(row.key_id, 'signal_signed_prekey.key_id'),
-        keyPair: {
-            pubKey: asBytes(row.pub_key, 'signal_signed_prekey.pub_key'),
-            privKey: asBytes(row.priv_key, 'signal_signed_prekey.priv_key')
-        },
-        signature: asBytes(row.signature, 'signal_signed_prekey.signature'),
-        uploaded: toBoolOrUndef(row.uploaded)
-    };
-}
-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
-    };
-}
-export function encodeSignalSessionRecord(record) {
-    return proto.RecordStructure.encode({
-        currentSession: encodeSignalSessionSnapshot(record),
-        previousSessions: record.prevSessions
-    }).finish();
-}
-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 ?? []
-    };
-}
-export function encodeSenderKeyRecord(record) {
-    return proto.SenderKeyRecordStructure.encode({
-        senderKeyStates: [
-            {
-                senderKeyId: record.keyId,
-                senderChainKey: {
-                    iteration: record.iteration,
-                    seed: record.chainKey
-                },
-                senderSigningKey: {
-                    public: record.signingPublicKey,
-                    private: record.signingPrivateKey
-                },
-                senderMessageKeys: (() => {
-                    const src = record.unusedMessageKeys ?? [];
-                    const arr = new Array(src.length);
-                    for (let i = 0; i < src.length; i += 1) {
-                        const messageKey = src[i];
-                        arr[i] = {
-                            iteration: messageKey.iteration,
-                            seed: messageKey.seed
-                        };
-                    }
-                    return arr;
-                })()
-            }
-        ]
-    }).finish();
-}
-function decodeSenderKeyState(state, field) {
-    if (!state.senderChainKey) {
-        throw new Error(`missing ${field}.senderChainKey`);
-    }
-    if (!state.senderSigningKey) {
-        throw new Error(`missing ${field}.senderSigningKey`);
-    }
-    return {
-        keyId: asNumber(state.senderKeyId, `${field}.senderKeyId`),
-        iteration: asNumber(state.senderChainKey.iteration, `${field}.senderChainKey.iteration`),
-        chainKey: asBytes(state.senderChainKey.seed, `${field}.senderChainKey.seed`),
-        signingPublicKey: asBytes(state.senderSigningKey.public, `${field}.senderSigningKey.public`),
-        signingPrivateKey: state.senderSigningKey.private !== null && state.senderSigningKey.private !== undefined
-            ? asBytes(state.senderSigningKey.private, `${field}.senderSigningKey.private`)
-            : undefined,
-        unusedMessageKeys: (() => {
-            const src = state.senderMessageKeys ?? [];
-            const arr = new Array(src.length);
-            for (let i = 0; i < src.length; i += 1) {
-                const messageKey = src[i];
-                arr[i] = {
-                    iteration: asNumber(messageKey.iteration, `${field}.senderMessageKeys[${i}].iteration`),
-                    seed: asBytes(messageKey.seed, `${field}.senderMessageKeys[${i}].seed`)
-                };
-            }
-            return arr;
-        })()
-    };
-}
-export function decodeSenderKeyRecord(raw, groupId, sender) {
-    const decoded = proto.SenderKeyRecordStructure.decode(asBytes(raw, 'sender_keys.record'));
-    const state = decoded.senderKeyStates?.[0];
-    if (!state) {
-        throw new Error('missing sender_keys.record.senderKeyStates[0]');
-    }
-    const parsed = decodeSenderKeyState(state, 'sender_keys.record.senderKeyStates[0]');
-    return {
-        groupId,
-        sender,
-        keyId: parsed.keyId,
-        iteration: parsed.iteration,
-        chainKey: parsed.chainKey,
-        signingPublicKey: parsed.signingPublicKey,
-        signingPrivateKey: parsed.signingPrivateKey,
-        unusedMessageKeys: parsed.unusedMessageKeys
-    };
-}
-export function decodeSenderKeyDistributionRow(row) {
-    return {
-        groupId: asString(row.group_id, 'sender_key_distribution.group_id'),
-        sender: {
-            user: asString(row.sender_user, 'sender_key_distribution.sender_user'),
-            server: asString(row.sender_server, 'sender_key_distribution.sender_server'),
-            device: asNumber(row.sender_device, 'sender_key_distribution.sender_device')
-        },
-        keyId: asNumber(row.key_id, 'sender_key_distribution.key_id'),
-        timestampMs: asNumber(row.timestamp_ms, 'sender_key_distribution.timestamp_ms')
-    };
-}
+/**
+ * Reads the `count` field of a single-row SQL `COUNT(*)` result, returning
+ * `0` when the row is missing.
+ */
 export function decodeStoreCount(row, field) {
     return row ? asNumber(row.count, field) : 0;
 }
-export function decodeSignalRemoteIdentity(raw) {
-    return asBytes(raw, 'signal_identity.identity_key');
-}

package/dist/esm/signal/group/SenderKeyChain.js

@@ -1,6 +1,7 @@
-import { hkdf, hmacSign, importHmacKey } from '../../crypto/index.js';
+import { hkdf, hmacSha256Sign } from '../../crypto/index.js';
 import { CHAIN_KEY_LABEL, MAX_UNUSED_KEYS, MESSAGE_KEY_LABEL, SENDER_KEY_FUTURE_MESSAGES_MAX, WHISPER_GROUP_INFO } from '../constants.js';
 import { assertByteLength, removeAt } from '../../util/bytes.js';
+// eslint-disable-next-line @typescript-eslint/require-await
 export async function selectMessageKey(senderKey, targetIteration, futureMessagesMax) {
     const delta = targetIteration - senderKey.iteration;
     if (delta > (futureMessagesMax ?? SENDER_KEY_FUTURE_MESSAGES_MAX)) {
@@ -22,9 +23,9 @@ export async function selectMessageKey(senderKey, targetIteration, futureMessage
             }
         };
     }
-    let chainState = await createSenderChainState(senderKey.chainKey);
-    const firstDerived = await deriveSenderKeyMsgKeyFromState(senderKey.iteration, chainState);
-    chainState = firstDerived.nextState;
+    let chainKey = ensureChainKey(senderKey.chainKey);
+    const firstDerived = deriveSenderKeyMsgKeyFromChainKey(senderKey.iteration, chainKey);
+    chainKey = firstDerived.nextChainKey;
     let messageKey = firstDerived.messageKey;
     if (delta === 0) {
         return {
@@ -32,7 +33,7 @@ export async function selectMessageKey(senderKey, targetIteration, futureMessage
             updatedRecord: {
                 ...senderKey,
                 iteration: targetIteration + 1,
-                chainKey: chainState.chainKey,
+                chainKey,
                 unusedMessageKeys: currentUnused
             }
         };
@@ -50,8 +51,8 @@ export async function selectMessageKey(senderKey, targetIteration, futureMessage
         else {
             nextUnused.push(messageKey);
         }
-        const derived = await deriveSenderKeyMsgKeyFromState(iteration, chainState);
-        chainState = derived.nextState;
+        const derived = deriveSenderKeyMsgKeyFromChainKey(iteration, chainKey);
+        chainKey = derived.nextChainKey;
         messageKey = derived.messageKey;
     }
     return {
@@ -59,41 +60,25 @@ export async function selectMessageKey(senderKey, targetIteration, futureMessage
         updatedRecord: {
             ...senderKey,
             iteration: targetIteration + 1,
-            chainKey: chainState.chainKey,
+            chainKey,
             unusedMessageKeys: nextUnused
         }
     };
 }
-export async function deriveSenderKeyMsgKey(iteration, chainKey) {
-    const state = await createSenderChainState(chainKey);
-    const derived = await deriveSenderKeyMsgKeyFromState(iteration, state);
-    return {
-        nextChainKey: derived.nextState.chainKey,
-        messageKey: derived.messageKey
-    };
+export function deriveSenderKeyMsgKey(iteration, chainKey) {
+    return deriveSenderKeyMsgKeyFromChainKey(iteration, ensureChainKey(chainKey));
 }
-async function createSenderChainState(chainKey) {
+function ensureChainKey(chainKey) {
     assertByteLength(chainKey, 32, 'sender key chainKey must be 32 bytes');
-    return {
-        chainKey,
-        hmacKey: await importHmacKey(chainKey)
-    };
+    return chainKey;
 }
-async function deriveSenderKeyMsgKeyFromState(iteration, state) {
-    const [nextChainRaw, messageInputKey] = await Promise.all([
-        hmacSign(state.hmacKey, CHAIN_KEY_LABEL),
-        hmacSign(state.hmacKey, MESSAGE_KEY_LABEL)
-    ]);
+function deriveSenderKeyMsgKeyFromChainKey(iteration, chainKey) {
+    const nextChainRaw = hmacSha256Sign(chainKey, CHAIN_KEY_LABEL);
+    const messageInputKey = hmacSha256Sign(chainKey, MESSAGE_KEY_LABEL);
     const nextChainKey = nextChainRaw.subarray(0, 32);
-    const [nextHmacKey, messageSeed] = await Promise.all([
-        importHmacKey(nextChainKey),
-        hkdf(messageInputKey, null, WHISPER_GROUP_INFO, 50)
-    ]);
+    const messageSeed = hkdf(messageInputKey, null, WHISPER_GROUP_INFO, 50);
     return {
-        nextState: {
-            chainKey: nextChainKey,
-            hmacKey: nextHmacKey
-        },
+        nextChainKey,
         messageKey: {
             iteration,
             seed: messageSeed

package/dist/esm/signal/group/SenderKeyManager.js

@@ -1,4 +1,4 @@
-import { aesCbcDecrypt, aesCbcEncrypt, importAesCbcKey, prependVersion, randomBytesAsync, randomIntAsync, toRawPubKey, toSerializedPubKey, X25519, xeddsaSign, xeddsaVerify } from '../../crypto/index.js';
+import { aesCbcDecrypt, aesCbcEncrypt, prependVersion, randomBytesAsync, randomIntAsync, toRawPubKey, toSerializedPubKey, X25519, xeddsaSign, xeddsaVerify } from '../../crypto/index.js';
 import { StoreLock } from '../../infra/perf/StoreLock.js';
 import { proto } from '../../proto.js';
 import { signalAddressKey } from '../../protocol/jid.js';
@@ -16,14 +16,19 @@ function extractAesCbcParams(seed) {
         keyBytes: seed.subarray(16, 48)
     };
 }
-async function aesCbcEncryptFromSeed(seed, plaintext) {
+function aesCbcEncryptFromSeed(seed, plaintext) {
     const { keyBytes, iv } = extractAesCbcParams(seed);
-    return aesCbcEncrypt(await importAesCbcKey(keyBytes), iv, plaintext);
+    return aesCbcEncrypt(keyBytes, iv, plaintext);
 }
-async function aesCbcDecryptFromSeed(seed, ciphertext) {
+function aesCbcDecryptFromSeed(seed, ciphertext) {
     const { keyBytes, iv } = extractAesCbcParams(seed);
-    return aesCbcDecrypt(await importAesCbcKey(keyBytes), iv, ciphertext);
+    return aesCbcDecrypt(keyBytes, iv, ciphertext);
 }
+/**
+ * Implements the sender-key group encryption side of Signal: creates and
+ * rotates sender keys, encrypts/decrypts group messages, and tracks which
+ * participants have already received the distribution message.
+ */
 export class SenderKeyManager {
     constructor(store, options) {
         this.senderLock = new StoreLock();
@@ -31,13 +36,17 @@ export class SenderKeyManager {
         this.getFutureMessagesMax = options?.getFutureMessagesMax;
         this.skipSignatureVerification = options?.skipSignatureVerification === true;
     }
+    /**
+     * Produces the distribution message and ciphertext for `plaintext` sent by
+     * `sender` into `groupId`. Initializes a sender key when none exists yet.
+     */
     async prepareGroupEncryption(groupId, sender, plaintext) {
         return this.runWithSenderLock(groupId, sender, async () => {
             const senderKey = await this.ensureSenderKeyInternal(groupId, sender);
             if (!senderKey.signingPrivateKey) {
                 throw new Error('sender private signing key is missing');
             }
-            const derived = await deriveSenderKeyMsgKey(senderKey.iteration, senderKey.chainKey);
+            const derived = deriveSenderKeyMsgKey(senderKey.iteration, senderKey.chainKey);
             await this.store.upsertSenderKey({
                 ...senderKey,
                 chainKey: derived.nextChainKey,
@@ -53,7 +62,7 @@ export class SenderKeyManager {
                 groupId,
                 axolotlSenderKeyDistributionMessage: prependVersion(distributionProto, SIGNAL_GROUP_VERSION)
             };
-            const messagePayload = await aesCbcEncryptFromSeed(derived.messageKey.seed, plaintext);
+            const messagePayload = aesCbcEncryptFromSeed(derived.messageKey.seed, plaintext);
             const senderKeyMessage = proto.SenderKeyMessage.encode({
                 id: senderKey.keyId,
                 iteration: derived.messageKey.iteration,
@@ -84,6 +93,7 @@ export class SenderKeyManager {
             };
         });
     }
+    /** Filters a participant list down to those who have not yet received the current sender key distribution. */
     async filterParticipantsNeedingDistribution(groupId, senderKeyId, participants) {
         if (participants.length === 0) {
             return [];
@@ -101,6 +111,7 @@ export class SenderKeyManager {
         pendingParticipants.length = pendingCount;
         return pendingParticipants;
     }
+    /** Records that the sender key was successfully delivered to the given participants. */
     async markSenderKeyDistributed(groupId, senderKeyId, participants) {
         if (participants.length === 0) {
             return;
@@ -117,6 +128,11 @@ export class SenderKeyManager {
         }
         await this.store.upsertSenderKeyDistributions(distributions);
     }
+    /**
+     * Verifies (per `skipSignatureVerification`) and stores an incoming sender
+     * key distribution so subsequent group ciphertexts from `sender` can be
+     * decrypted.
+     */
     async processSenderKeyDistributionPayload(groupId, sender, payload) {
         return this.runWithSenderLock(groupId, sender, async () => {
             if (groupId.length === 0) {
@@ -144,6 +160,7 @@ export class SenderKeyManager {
             return record;
         });
     }
+    /** Decrypts an incoming sender-key group ciphertext into plaintext. */
     async decryptGroupMessage(payload) {
         return this.runWithSenderLock(payload.groupId, payload.sender, async () => {
             const parsed = parseSenderKeyMessage(payload.ciphertext);
@@ -174,7 +191,7 @@ export class SenderKeyManager {
             }
             const selected = await selectMessageKey(senderKey, parsed.iteration, this.getFutureMessagesMax?.());
             // Keep decrypt + persist ordered: failed decrypt must not advance sender-key state.
-            const plaintext = await aesCbcDecryptFromSeed(selected.messageKey.seed, parsed.ciphertext);
+            const plaintext = aesCbcDecryptFromSeed(selected.messageKey.seed, parsed.ciphertext);
             await this.store.upsertSenderKey(selected.updatedRecord);
             return plaintext;
         });

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

@@ -0,0 +1,96 @@
+import { proto } from '../../proto.js';
+import { asBytes, asNumber, asString } from '../../util/coercion.js';
+/** Serializes a {@link SenderKeyRecord} into the Signal `SenderKeyRecordStructure` protobuf. */
+export function encodeSenderKeyRecord(record) {
+    return proto.SenderKeyRecordStructure.encode({
+        senderKeyStates: [
+            {
+                senderKeyId: record.keyId,
+                senderChainKey: {
+                    iteration: record.iteration,
+                    seed: record.chainKey
+                },
+                senderSigningKey: {
+                    public: record.signingPublicKey,
+                    private: record.signingPrivateKey
+                },
+                senderMessageKeys: (() => {
+                    const src = record.unusedMessageKeys ?? [];
+                    const arr = new Array(src.length);
+                    for (let i = 0; i < src.length; i += 1) {
+                        const messageKey = src[i];
+                        arr[i] = {
+                            iteration: messageKey.iteration,
+                            seed: messageKey.seed
+                        };
+                    }
+                    return arr;
+                })()
+            }
+        ]
+    }).finish();
+}
+function decodeSenderKeyState(state, field) {
+    if (!state.senderChainKey) {
+        throw new Error(`missing ${field}.senderChainKey`);
+    }
+    if (!state.senderSigningKey) {
+        throw new Error(`missing ${field}.senderSigningKey`);
+    }
+    return {
+        keyId: asNumber(state.senderKeyId, `${field}.senderKeyId`),
+        iteration: asNumber(state.senderChainKey.iteration, `${field}.senderChainKey.iteration`),
+        chainKey: asBytes(state.senderChainKey.seed, `${field}.senderChainKey.seed`),
+        signingPublicKey: asBytes(state.senderSigningKey.public, `${field}.senderSigningKey.public`),
+        signingPrivateKey: state.senderSigningKey.private !== null && state.senderSigningKey.private !== undefined
+            ? asBytes(state.senderSigningKey.private, `${field}.senderSigningKey.private`)
+            : undefined,
+        unusedMessageKeys: (() => {
+            const src = state.senderMessageKeys ?? [];
+            const arr = new Array(src.length);
+            for (let i = 0; i < src.length; i += 1) {
+                const messageKey = src[i];
+                arr[i] = {
+                    iteration: asNumber(messageKey.iteration, `${field}.senderMessageKeys[${i}].iteration`),
+                    seed: asBytes(messageKey.seed, `${field}.senderMessageKeys[${i}].seed`)
+                };
+            }
+            return arr;
+        })()
+    };
+}
+/**
+ * Decodes a stored sender-key blob into a {@link SenderKeyRecord}.
+ * `groupId`/`sender` are re-attached from the row key (not in the protobuf).
+ */
+export function decodeSenderKeyRecord(raw, groupId, sender) {
+    const decoded = proto.SenderKeyRecordStructure.decode(asBytes(raw, 'sender_keys.record'));
+    const state = decoded.senderKeyStates?.[0];
+    if (!state) {
+        throw new Error('missing sender_keys.record.senderKeyStates[0]');
+    }
+    const parsed = decodeSenderKeyState(state, 'sender_keys.record.senderKeyStates[0]');
+    return {
+        groupId,
+        sender,
+        keyId: parsed.keyId,
+        iteration: parsed.iteration,
+        chainKey: parsed.chainKey,
+        signingPublicKey: parsed.signingPublicKey,
+        signingPrivateKey: parsed.signingPrivateKey,
+        unusedMessageKeys: parsed.unusedMessageKeys
+    };
+}
+/** Decodes a sender-key-distribution SQL row into a {@link SenderKeyDistributionRecord}. */
+export function decodeSenderKeyDistributionRow(row) {
+    return {
+        groupId: asString(row.group_id, 'sender_key_distribution.group_id'),
+        sender: {
+            user: asString(row.sender_user, 'sender_key_distribution.sender_user'),
+            server: asString(row.sender_server, 'sender_key_distribution.sender_server'),
+            device: asNumber(row.sender_device, 'sender_key_distribution.sender_device')
+        },
+        keyId: asNumber(row.key_id, 'sender_key_distribution.key_id'),
+        timestampMs: asNumber(row.timestamp_ms, 'sender_key_distribution.timestamp_ms')
+    };
+}

package/dist/esm/signal/index.js

@@ -1,4 +1,7 @@
-export { decodeSignalPreKeyRow, decodeSignalRegistrationRow, decodeSignalRemoteIdentity, decodeSignalSessionRecord, decodeSignalSignedPreKeyRow, decodeSenderKeyDistributionRow, decodeSenderKeyRecord, decodeStoreCount, encodeSenderKeyRecord, encodeSignalSessionRecord, toSignalAddressParts } from './encoding.js';
+export { decodeStoreCount, toSignalAddressParts } from './encoding.js';
+export { decodeSignalRemoteIdentity, decodeSignalSessionRecord, encodeSignalSessionRecord } from './session/encoding.js';
+export { decodeSignalPreKeyRow, decodeSignalRegistrationRow, decodeSignalSignedPreKeyRow } from './registration/encoding.js';
+export { decodeSenderKeyDistributionRow, decodeSenderKeyRecord, encodeSenderKeyRecord } from './group/encoding.js';
 export { generatePreKeyPair, generateRegistrationId, generateRegistrationInfo, generateSignedPreKey } from './registration/keygen.js';
 export { buildPreKeyUploadIq, parsePreKeyUploadFailure } from './api/prekeys.js';
 export { SignalDigestSyncApi } from './api/SignalDigestSyncApi.js';

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

@@ -0,0 +1,34 @@
+import { asBytes, asNumber, toBoolOrUndef } from '../../util/coercion.js';
+/** Decodes a stored signal-registration SQL row into a {@link RegistrationInfo}. */
+export function decodeSignalRegistrationRow(row) {
+    return {
+        registrationId: asNumber(row.registration_id, 'signal_registration.registration_id'),
+        identityKeyPair: {
+            pubKey: asBytes(row.identity_pub_key, 'signal_registration.identity_pub_key'),
+            privKey: asBytes(row.identity_priv_key, 'signal_registration.identity_priv_key')
+        }
+    };
+}
+/** Decodes a one-time prekey SQL row into a {@link PreKeyRecord}. */
+export function decodeSignalPreKeyRow(row) {
+    return {
+        keyId: asNumber(row.key_id, 'signal_prekey.key_id'),
+        keyPair: {
+            pubKey: asBytes(row.pub_key, 'signal_prekey.pub_key'),
+            privKey: asBytes(row.priv_key, 'signal_prekey.priv_key')
+        },
+        uploaded: toBoolOrUndef(row.uploaded)
+    };
+}
+/** Decodes a signed-prekey SQL row into a {@link SignedPreKeyRecord}. */
+export function decodeSignalSignedPreKeyRow(row) {
+    return {
+        keyId: asNumber(row.key_id, 'signal_signed_prekey.key_id'),
+        keyPair: {
+            pubKey: asBytes(row.pub_key, 'signal_signed_prekey.pub_key'),
+            privKey: asBytes(row.priv_key, 'signal_signed_prekey.priv_key')
+        },
+        signature: asBytes(row.signature, 'signal_signed_prekey.signature'),
+        uploaded: toBoolOrUndef(row.uploaded)
+    };
+}

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

@@ -1,6 +1,10 @@
 import { randomIntAsync, xeddsaSign } from '../../crypto/index.js';
 import { toSerializedPubKey } from '../../crypto/core/keys.js';
 import { X25519 } from '../../crypto/curves/X25519.js';
+/**
+ * Generates the per-device Signal registration info – a random registration id
+ * plus a fresh identity X25519 key pair.
+ */
 export async function generateRegistrationInfo() {
     const [registrationId, identityKeyPair] = await Promise.all([
         generateRegistrationId(),
@@ -11,6 +15,7 @@ export async function generateRegistrationInfo() {
         identityKeyPair
     };
 }
+/** Generates a fresh one-time prekey record with the given `keyId`. */
 export async function generatePreKeyPair(keyId) {
     return {
         keyId,
@@ -18,6 +23,10 @@ export async function generatePreKeyPair(keyId) {
         uploaded: false
     };
 }
+/**
+ * Generates a signed prekey: a fresh X25519 keypair plus an XEdDSA signature
+ * over its serialized public key, signed by `signingPrivateKey` (identity key).
+ */
 export async function generateSignedPreKey(keyId, signingPrivateKey) {
     const keyPair = await X25519.generateKeyPair();
     const serializedPubKey = toSerializedPubKey(keyPair.pubKey);
@@ -29,6 +38,7 @@ export async function generateSignedPreKey(keyId, signingPrivateKey) {
         uploaded: false
     };
 }
+/** Generates a Signal registration id in the valid `[1, 16380]` range. */
 export async function generateRegistrationId() {
     return await randomIntAsync(1, 16381);
 }