zapo-js 0.3.0 → 1.0.1

package/dist/signal/group/SenderKeyManager.js

@@ -1,9 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SenderKeyManager = void 0;
-const _crypto_1 = require("../../crypto/index.js");
+const _crypto_1 = require("../../crypto");
 const StoreLock_1 = require("../../infra/perf/StoreLock");
-const _proto_1 = require("../../proto.js");
+const _proto_1 = require("../../proto");
 const jid_1 = require("../../protocol/jid");
 const constants_1 = require("../api/constants");
 const constants_2 = require("../constants");
@@ -19,14 +19,19 @@ function extractAesCbcParams(seed) {
         keyBytes: seed.subarray(16, 48)
     };
 }
-async function aesCbcEncryptFromSeed(seed, plaintext) {
+function aesCbcEncryptFromSeed(seed, plaintext) {
     const { keyBytes, iv } = extractAesCbcParams(seed);
-    return (0, _crypto_1.aesCbcEncrypt)(await (0, _crypto_1.importAesCbcKey)(keyBytes), iv, plaintext);
+    return (0, _crypto_1.aesCbcEncrypt)(keyBytes, iv, plaintext);
 }
-async function aesCbcDecryptFromSeed(seed, ciphertext) {
+function aesCbcDecryptFromSeed(seed, ciphertext) {
     const { keyBytes, iv } = extractAesCbcParams(seed);
-    return (0, _crypto_1.aesCbcDecrypt)(await (0, _crypto_1.importAesCbcKey)(keyBytes), iv, ciphertext);
+    return (0, _crypto_1.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.
+ */
 class SenderKeyManager {
     constructor(store, options) {
         this.senderLock = new StoreLock_1.StoreLock();
@@ -34,13 +39,17 @@ 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 (0, SenderKeyChain_1.deriveSenderKeyMsgKey)(senderKey.iteration, senderKey.chainKey);
+            const derived = (0, SenderKeyChain_1.deriveSenderKeyMsgKey)(senderKey.iteration, senderKey.chainKey);
             await this.store.upsertSenderKey({
                 ...senderKey,
                 chainKey: derived.nextChainKey,
@@ -56,7 +65,7 @@ class SenderKeyManager {
                 groupId,
                 axolotlSenderKeyDistributionMessage: (0, _crypto_1.prependVersion)(distributionProto, constants_2.SIGNAL_GROUP_VERSION)
             };
-            const messagePayload = await aesCbcEncryptFromSeed(derived.messageKey.seed, plaintext);
+            const messagePayload = aesCbcEncryptFromSeed(derived.messageKey.seed, plaintext);
             const senderKeyMessage = _proto_1.proto.SenderKeyMessage.encode({
                 id: senderKey.keyId,
                 iteration: derived.messageKey.iteration,
@@ -87,6 +96,7 @@ 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 [];
@@ -104,6 +114,7 @@ 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;
@@ -120,6 +131,11 @@ 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) {
@@ -147,6 +163,7 @@ 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 = (0, SenderKeyCodec_1.parseSenderKeyMessage)(payload.ciphertext);
@@ -177,7 +194,7 @@ class SenderKeyManager {
             }
             const selected = await (0, SenderKeyChain_1.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/signal/group/encoding.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeSenderKeyRecord = encodeSenderKeyRecord;
+exports.decodeSenderKeyRecord = decodeSenderKeyRecord;
+exports.decodeSenderKeyDistributionRow = decodeSenderKeyDistributionRow;
+const _proto_1 = require("../../proto");
+const coercion_1 = require("../../util/coercion");
+/** Serializes a {@link SenderKeyRecord} into the Signal `SenderKeyRecordStructure` protobuf. */
+function encodeSenderKeyRecord(record) {
+    return _proto_1.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: (0, coercion_1.asNumber)(state.senderKeyId, `${field}.senderKeyId`),
+        iteration: (0, coercion_1.asNumber)(state.senderChainKey.iteration, `${field}.senderChainKey.iteration`),
+        chainKey: (0, coercion_1.asBytes)(state.senderChainKey.seed, `${field}.senderChainKey.seed`),
+        signingPublicKey: (0, coercion_1.asBytes)(state.senderSigningKey.public, `${field}.senderSigningKey.public`),
+        signingPrivateKey: state.senderSigningKey.private !== null && state.senderSigningKey.private !== undefined
+            ? (0, coercion_1.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: (0, coercion_1.asNumber)(messageKey.iteration, `${field}.senderMessageKeys[${i}].iteration`),
+                    seed: (0, coercion_1.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).
+ */
+function decodeSenderKeyRecord(raw, groupId, sender) {
+    const decoded = _proto_1.proto.SenderKeyRecordStructure.decode((0, coercion_1.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}. */
+function decodeSenderKeyDistributionRow(row) {
+    return {
+        groupId: (0, coercion_1.asString)(row.group_id, 'sender_key_distribution.group_id'),
+        sender: {
+            user: (0, coercion_1.asString)(row.sender_user, 'sender_key_distribution.sender_user'),
+            server: (0, coercion_1.asString)(row.sender_server, 'sender_key_distribution.sender_server'),
+            device: (0, coercion_1.asNumber)(row.sender_device, 'sender_key_distribution.sender_device')
+        },
+        keyId: (0, coercion_1.asNumber)(row.key_id, 'sender_key_distribution.key_id'),
+        timestampMs: (0, coercion_1.asNumber)(row.timestamp_ms, 'sender_key_distribution.timestamp_ms')
+    };
+}

package/dist/signal/index.js

@@ -1,18 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createSignalSessionResolver = exports.SignalProtocol = exports.createAndStoreInitialKeys = exports.SenderKeyManager = exports.SignalSessionSyncApi = exports.SignalRotateKeyApi = exports.SignalMissingPreKeysSyncApi = exports.SignalIdentitySyncApi = exports.SignalDeviceSyncApi = exports.SignalDigestSyncApi = exports.parsePreKeyUploadFailure = exports.buildPreKeyUploadIq = exports.generateSignedPreKey = exports.generateRegistrationInfo = exports.generateRegistrationId = exports.generatePreKeyPair = exports.toSignalAddressParts = exports.encodeSignalSessionRecord = exports.encodeSenderKeyRecord = exports.decodeStoreCount = exports.decodeSenderKeyRecord = exports.decodeSenderKeyDistributionRow = exports.decodeSignalSignedPreKeyRow = exports.decodeSignalSessionRecord = exports.decodeSignalRemoteIdentity = exports.decodeSignalRegistrationRow = exports.decodeSignalPreKeyRow = void 0;
+exports.createSignalSessionResolver = exports.SignalProtocol = exports.createAndStoreInitialKeys = exports.SenderKeyManager = exports.SignalSessionSyncApi = exports.SignalRotateKeyApi = exports.SignalMissingPreKeysSyncApi = exports.SignalIdentitySyncApi = exports.SignalDeviceSyncApi = exports.SignalDigestSyncApi = exports.parsePreKeyUploadFailure = exports.buildPreKeyUploadIq = exports.generateSignedPreKey = exports.generateRegistrationInfo = exports.generateRegistrationId = exports.generatePreKeyPair = exports.encodeSenderKeyRecord = exports.decodeSenderKeyRecord = exports.decodeSenderKeyDistributionRow = exports.decodeSignalSignedPreKeyRow = exports.decodeSignalRegistrationRow = exports.decodeSignalPreKeyRow = exports.encodeSignalSessionRecord = exports.decodeSignalSessionRecord = exports.decodeSignalRemoteIdentity = exports.toSignalAddressParts = exports.decodeStoreCount = void 0;
 var encoding_1 = require("./encoding");
-Object.defineProperty(exports, "decodeSignalPreKeyRow", { enumerable: true, get: function () { return encoding_1.decodeSignalPreKeyRow; } });
-Object.defineProperty(exports, "decodeSignalRegistrationRow", { enumerable: true, get: function () { return encoding_1.decodeSignalRegistrationRow; } });
-Object.defineProperty(exports, "decodeSignalRemoteIdentity", { enumerable: true, get: function () { return encoding_1.decodeSignalRemoteIdentity; } });
-Object.defineProperty(exports, "decodeSignalSessionRecord", { enumerable: true, get: function () { return encoding_1.decodeSignalSessionRecord; } });
-Object.defineProperty(exports, "decodeSignalSignedPreKeyRow", { enumerable: true, get: function () { return encoding_1.decodeSignalSignedPreKeyRow; } });
-Object.defineProperty(exports, "decodeSenderKeyDistributionRow", { enumerable: true, get: function () { return encoding_1.decodeSenderKeyDistributionRow; } });
-Object.defineProperty(exports, "decodeSenderKeyRecord", { enumerable: true, get: function () { return encoding_1.decodeSenderKeyRecord; } });
 Object.defineProperty(exports, "decodeStoreCount", { enumerable: true, get: function () { return encoding_1.decodeStoreCount; } });
-Object.defineProperty(exports, "encodeSenderKeyRecord", { enumerable: true, get: function () { return encoding_1.encodeSenderKeyRecord; } });
-Object.defineProperty(exports, "encodeSignalSessionRecord", { enumerable: true, get: function () { return encoding_1.encodeSignalSessionRecord; } });
 Object.defineProperty(exports, "toSignalAddressParts", { enumerable: true, get: function () { return encoding_1.toSignalAddressParts; } });
+var encoding_2 = require("./session/encoding");
+Object.defineProperty(exports, "decodeSignalRemoteIdentity", { enumerable: true, get: function () { return encoding_2.decodeSignalRemoteIdentity; } });
+Object.defineProperty(exports, "decodeSignalSessionRecord", { enumerable: true, get: function () { return encoding_2.decodeSignalSessionRecord; } });
+Object.defineProperty(exports, "encodeSignalSessionRecord", { enumerable: true, get: function () { return encoding_2.encodeSignalSessionRecord; } });
+var encoding_3 = require("./registration/encoding");
+Object.defineProperty(exports, "decodeSignalPreKeyRow", { enumerable: true, get: function () { return encoding_3.decodeSignalPreKeyRow; } });
+Object.defineProperty(exports, "decodeSignalRegistrationRow", { enumerable: true, get: function () { return encoding_3.decodeSignalRegistrationRow; } });
+Object.defineProperty(exports, "decodeSignalSignedPreKeyRow", { enumerable: true, get: function () { return encoding_3.decodeSignalSignedPreKeyRow; } });
+var encoding_4 = require("./group/encoding");
+Object.defineProperty(exports, "decodeSenderKeyDistributionRow", { enumerable: true, get: function () { return encoding_4.decodeSenderKeyDistributionRow; } });
+Object.defineProperty(exports, "decodeSenderKeyRecord", { enumerable: true, get: function () { return encoding_4.decodeSenderKeyRecord; } });
+Object.defineProperty(exports, "encodeSenderKeyRecord", { enumerable: true, get: function () { return encoding_4.encodeSenderKeyRecord; } });
 var keygen_1 = require("./registration/keygen");
 Object.defineProperty(exports, "generatePreKeyPair", { enumerable: true, get: function () { return keygen_1.generatePreKeyPair; } });
 Object.defineProperty(exports, "generateRegistrationId", { enumerable: true, get: function () { return keygen_1.generateRegistrationId; } });

package/dist/signal/registration/encoding.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeSignalRegistrationRow = decodeSignalRegistrationRow;
+exports.decodeSignalPreKeyRow = decodeSignalPreKeyRow;
+exports.decodeSignalSignedPreKeyRow = decodeSignalSignedPreKeyRow;
+const coercion_1 = require("../../util/coercion");
+/** Decodes a stored signal-registration SQL row into a {@link RegistrationInfo}. */
+function decodeSignalRegistrationRow(row) {
+    return {
+        registrationId: (0, coercion_1.asNumber)(row.registration_id, 'signal_registration.registration_id'),
+        identityKeyPair: {
+            pubKey: (0, coercion_1.asBytes)(row.identity_pub_key, 'signal_registration.identity_pub_key'),
+            privKey: (0, coercion_1.asBytes)(row.identity_priv_key, 'signal_registration.identity_priv_key')
+        }
+    };
+}
+/** Decodes a one-time prekey SQL row into a {@link PreKeyRecord}. */
+function decodeSignalPreKeyRow(row) {
+    return {
+        keyId: (0, coercion_1.asNumber)(row.key_id, 'signal_prekey.key_id'),
+        keyPair: {
+            pubKey: (0, coercion_1.asBytes)(row.pub_key, 'signal_prekey.pub_key'),
+            privKey: (0, coercion_1.asBytes)(row.priv_key, 'signal_prekey.priv_key')
+        },
+        uploaded: (0, coercion_1.toBoolOrUndef)(row.uploaded)
+    };
+}
+/** Decodes a signed-prekey SQL row into a {@link SignedPreKeyRecord}. */
+function decodeSignalSignedPreKeyRow(row) {
+    return {
+        keyId: (0, coercion_1.asNumber)(row.key_id, 'signal_signed_prekey.key_id'),
+        keyPair: {
+            pubKey: (0, coercion_1.asBytes)(row.pub_key, 'signal_signed_prekey.pub_key'),
+            privKey: (0, coercion_1.asBytes)(row.priv_key, 'signal_signed_prekey.priv_key')
+        },
+        signature: (0, coercion_1.asBytes)(row.signature, 'signal_signed_prekey.signature'),
+        uploaded: (0, coercion_1.toBoolOrUndef)(row.uploaded)
+    };
+}

package/dist/signal/registration/keygen.js

@@ -4,9 +4,13 @@ exports.generateRegistrationInfo = generateRegistrationInfo;
 exports.generatePreKeyPair = generatePreKeyPair;
 exports.generateSignedPreKey = generateSignedPreKey;
 exports.generateRegistrationId = generateRegistrationId;
-const _crypto_1 = require("../../crypto/index.js");
+const _crypto_1 = require("../../crypto");
 const keys_1 = require("../../crypto/core/keys");
 const X25519_1 = require("../../crypto/curves/X25519");
+/**
+ * Generates the per-device Signal registration info – a random registration id
+ * plus a fresh identity X25519 key pair.
+ */
 async function generateRegistrationInfo() {
     const [registrationId, identityKeyPair] = await Promise.all([
         generateRegistrationId(),
@@ -17,6 +21,7 @@ async function generateRegistrationInfo() {
         identityKeyPair
     };
 }
+/** Generates a fresh one-time prekey record with the given `keyId`. */
 async function generatePreKeyPair(keyId) {
     return {
         keyId,
@@ -24,6 +29,10 @@ 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).
+ */
 async function generateSignedPreKey(keyId, signingPrivateKey) {
     const keyPair = await X25519_1.X25519.generateKeyPair();
     const serializedPubKey = (0, keys_1.toSerializedPubKey)(keyPair.pubKey);
@@ -35,6 +44,7 @@ async function generateSignedPreKey(keyId, signingPrivateKey) {
         uploaded: false
     };
 }
+/** Generates a Signal registration id in the valid `[1, 16380]` range. */
 async function generateRegistrationId() {
     return await (0, _crypto_1.randomIntAsync)(1, 16381);
 }

package/dist/signal/registration/utils.js

@@ -2,6 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createAndStoreInitialKeys = createAndStoreInitialKeys;
 const keygen_1 = require("../registration/keygen");
+/**
+ * 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.
+ */
 async function createAndStoreInitialKeys(store, preKeyStore) {
     const [registrationInfo, firstPreKey] = await Promise.all([
         (0, keygen_1.generateRegistrationInfo)(),
@@ -11,7 +16,9 @@ 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);
-    await preKeyStore.getOrGenSinglePreKey(async () => firstPreKey);
+    // putPreKey (idempotent), not getOrGenSinglePreKey: a fixed-keyId generator
+    // collides with a stale keyId 1 and would spin forever inside getOrGen*.
+    await preKeyStore.putPreKey(firstPreKey);
     return {
         registrationInfo,
         signedPreKey,

package/dist/signal/session/SignalProtocol.js

@@ -1,30 +1,40 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SignalProtocol = void 0;
-const _crypto_1 = require("../../crypto/index.js");
+const _crypto_1 = require("../../crypto");
 const ConsoleLogger_1 = require("../../infra/log/ConsoleLogger");
 const StoreLock_1 = require("../../infra/perf/StoreLock");
+const jid_1 = require("../../protocol/jid");
 const constants_1 = require("../constants");
-const encoding_1 = require("../encoding");
+const encoding_1 = require("../session/encoding");
 const SignalRatchet_1 = require("../session/SignalRatchet");
 const SignalSerializer_1 = require("../session/SignalSerializer");
 const SignalSession_1 = require("../session/SignalSession");
 const bytes_1 = require("../../util/bytes");
-function signalAddressMapKey(address) {
-    return `${address.user}\u0001${address.server ?? ''}\u0001${address.device}`;
-}
 function signalAddressLockKey(address) {
-    return `signal:${signalAddressMapKey(address)}`;
+    return `signal:${(0, jid_1.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.
+ */
 class SignalProtocol {
     constructor(stores, logger = new ConsoleLogger_1.ConsoleLogger('info')) {
         this.stores = stores;
         this.logger = logger;
         this.sessionMutationLock = new StoreLock_1.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 = (0, _crypto_1.toSerializedPubKey)(remoteBundle.identity);
@@ -45,12 +55,100 @@ 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 = (0, _crypto_1.toSerializedPubKey)(remoteBundle.identity);
+                    if (!(0, bytes_1.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([
+                (0, SignalSession_1.requireLocalIdentity)(this.stores.signal),
+                (0, SignalSession_1.generateSerializedKeyPair)()
+            ]);
+            const session = await (0, SignalSession_1.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 ((0, bytes_1.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 [];
@@ -64,7 +162,7 @@ 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((0, jid_1.signalAddressKey)(entry.address), entry.session);
                 }
             }
             const uniqueAddressKeys = new Array(requests.length);
@@ -72,7 +170,7 @@ 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 = (0, jid_1.signalAddressKey)(address);
                 let isDuplicate = false;
                 for (let dedupIndex = 0; dedupIndex < uniqueAddressCount; dedupIndex += 1) {
                     if (uniqueAddressKeys[dedupIndex] === addressKey) {
@@ -109,7 +207,7 @@ 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 = (0, jid_1.signalAddressKey)(address);
                 const session = latestSessionByAddress.get(addressKey);
                 if (!session) {
                     throw new Error('signal session not found');
@@ -155,6 +253,10 @@ 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);
@@ -214,7 +316,7 @@ class SignalProtocol {
             ? {
                 ...incoming,
                 prevSessions: [
-                    (0, encoding_1.encodeSignalSessionSnapshot)((0, SignalSession_1.detachSession)(currentSession)),
+                    (0, encoding_1.encodeSignalSessionSnapshot)(currentSession),
                     ...currentSession.prevSessions.slice(0, constants_1.MAX_PREV_SESSIONS - 1)
                 ]
             }