zapo-js 0.2.0 → 1.0.0

package/dist/esm/retry/replay.js

@@ -1,16 +1,28 @@
-import { wrapDeviceSentMessage } from '../message/device-sent.js';
-import { unpadPkcs7, writeRandomPadMax16 } from '../message/padding.js';
+import { injectDeviceListMetadata } from '../message/crypto/icdc.js';
+import { wrapDeviceSentMessage } from '../message/encode/device-sent.js';
+import { unpadPkcs7, writeRandomPadMax16 } from '../message/encode/padding.js';
 import { proto } from '../proto.js';
-import { isGroupOrBroadcastJid, normalizeDeviceJid, parseJidFull, toUserJid } from '../protocol/jid.js';
+import { WA_DEFAULTS, WA_NODE_TAGS } from '../protocol/constants.js';
+import { isGroupOrBroadcastJid, isHostedDeviceJid, isStatusBroadcastJid, normalizeDeviceJid, parseJidFull, toUserJid } from '../protocol/jid.js';
 import { decodeRetryReplayPayload } from './codec.js';
 import { decodeBinaryNode } from '../transport/binary/index.js';
-import { buildGroupRetryMessageNode } from '../transport/node/builders/message.js';
+import { buildGroupRetryMessageNode, buildMetaNode } from '../transport/node/builders/message.js';
 import { findNodeChild } from '../transport/node/helpers.js';
 import { toError } from '../util/primitives.js';
+/**
+ * Replays a previously-sent outbound message in response to an incoming
+ * retry receipt. Dispatches to plaintext/encrypted/opaque-node handlers
+ * based on the stored payload shape.
+ */
 export class WaRetryReplayService {
     constructor(options) {
         this.options = options;
     }
+    /**
+     * Resends `outbound` to `requesterJid`. Returns `'resent'` on a fresh
+     * send or `'ineligible'` when the cached payload cannot satisfy the
+     * request (e.g. requester not in the original device list).
+     */
     async resendOutboundMessage(outbound, requesterJid, retryCount) {
         const payload = outbound.replayPayload instanceof Uint8Array
             ? decodeRetryReplayPayload(outbound.replayPayload)
@@ -39,43 +51,137 @@ export class WaRetryReplayService {
         catch {
             return 'ineligible';
         }
-        if (payloadUserJid !== requesterUserJid) {
+        const requesterIsSelf = this.isRequesterCurrentAccount(requesterJid);
+        if (payloadUserJid !== requesterUserJid && !requesterIsSelf) {
             return 'ineligible';
         }
-        const encrypted = await this.options.signalProtocol.encryptMessage(requesterAddress, payload.plaintext);
+        const plaintext = (await this.refreshRetryPlaintext(payload, {
+            wrapAsDeviceSent: requesterIsSelf,
+            includeRecipientIcdc: true,
+            logContext: 'direct'
+        })) ?? payload.plaintext;
+        await this.options.sessionResolver.ensureSession(requesterAddress, requesterJid);
+        const encrypted = await this.options.signalProtocol.encryptMessage(requesterAddress, plaintext);
+        const deviceIdentity = encrypted.type === 'pkmsg' ? this.resolveSignedDeviceIdentity('direct') : undefined;
+        const metaNode = isHostedDeviceJid(requesterJid)
+            ? buildMetaNode({ sender_intent: 'hosted' })
+            : undefined;
         await this.options.messageClient.sendEncrypted({
             to: requesterJid,
             encType: encrypted.type,
             ciphertext: encrypted.ciphertext,
             encCount: retryCount,
             id: outbound.messageId,
-            type: payload.type
+            type: payload.type,
+            deviceIdentity,
+            metaNode
         });
         return 'resent';
     }
+    resolveSignedDeviceIdentity(context) {
+        const signedIdentity = this.options.getCurrentCredentials()?.signedIdentity;
+        if (!signedIdentity) {
+            this.options.logger.warn('retry request missing signed identity for pkmsg envelope', {
+                context
+            });
+            return undefined;
+        }
+        return proto.ADVSignedDeviceIdentity.encode(signedIdentity).finish();
+    }
+    async refreshRetryPlaintext(payload, options) {
+        if (!options.wrapAsDeviceSent && !this.options.resolveUserIcdc) {
+            return null;
+        }
+        try {
+            const messageBytes = unpadPkcs7(payload.plaintext);
+            const decoded = proto.Message.decode(messageBytes);
+            let message = decoded;
+            let changed = false;
+            if (this.options.resolveUserIcdc) {
+                const meUserJid = this.safeUserJid(this.options.getCurrentCredentials()?.meJid);
+                const recipientUserJid = options.includeRecipientIcdc
+                    ? this.safeUserJid(payload.to)
+                    : null;
+                const [senderIcdc, recipientIcdc] = await Promise.all([
+                    meUserJid ? this.options.resolveUserIcdc(meUserJid) : Promise.resolve(null),
+                    recipientUserJid
+                        ? this.options.resolveUserIcdc(recipientUserJid)
+                        : Promise.resolve(null)
+                ]);
+                const injected = injectDeviceListMetadata(message, senderIcdc, recipientIcdc);
+                if (injected !== message) {
+                    message = injected;
+                    changed = true;
+                }
+            }
+            if (options.wrapAsDeviceSent && !message.deviceSentMessage) {
+                message = wrapDeviceSentMessage(message, payload.to);
+                changed = true;
+            }
+            if (!changed) {
+                return null;
+            }
+            return writeRandomPadMax16(proto.Message.encode(message).finish());
+        }
+        catch (error) {
+            this.options.logger.warn('retry request failed to refresh plaintext', {
+                context: options.logContext,
+                to: payload.to,
+                message: toError(error).message
+            });
+            return null;
+        }
+    }
+    safeUserJid(jid) {
+        if (!jid)
+            return null;
+        try {
+            return toUserJid(jid);
+        }
+        catch {
+            return null;
+        }
+    }
     async resendGroupPlaintextPayload(outbound, payload, requesterJid, requesterAddress, retryCount) {
-        const plaintext = (await this.maybeWrapGroupRetryPlaintextForSelfDevice(payload, requesterJid)) ??
-            payload.plaintext;
+        const plaintext = (await this.refreshRetryPlaintext(payload, {
+            wrapAsDeviceSent: this.isRequesterCurrentAccount(requesterJid),
+            includeRecipientIcdc: false,
+            logContext: 'group'
+        })) ?? payload.plaintext;
         const encrypted = await this.options.signalProtocol.encryptMessage(requesterAddress, plaintext);
         let deviceIdentity;
         if (encrypted.type === 'pkmsg') {
-            const signedIdentity = this.options.getCurrentSignedIdentity();
+            const signedIdentity = this.options.getCurrentCredentials()?.signedIdentity;
             if (!signedIdentity) {
                 this.options.logger.warn('retry request rejected: missing signed identity for pkmsg group retry');
                 return 'ineligible';
             }
             deviceIdentity = proto.ADVSignedDeviceIdentity.encode(signedIdentity).finish();
         }
+        const isStatus = isStatusBroadcastJid(payload.to);
+        const metaAttrs = {};
+        if (isStatus) {
+            metaAttrs.status_setting = payload.statusSetting ?? 'contacts';
+        }
+        if (isHostedDeviceJid(requesterJid)) {
+            metaAttrs.sender_intent = 'hosted';
+        }
+        const metaNode = Object.keys(metaAttrs).length > 0 ? buildMetaNode(metaAttrs) : undefined;
         const retryNode = buildGroupRetryMessageNode({
             to: payload.to,
             type: payload.type,
             id: outbound.messageId,
             requesterJid,
-            addressingMode: requesterAddress.server === 'lid' ? 'lid' : 'pn',
+            addressingMode: isStatus
+                ? undefined
+                : requesterAddress.server === WA_DEFAULTS.LID_SERVER
+                    ? 'lid'
+                    : 'pn',
             encType: encrypted.type,
             ciphertext: encrypted.ciphertext,
             retryCount,
-            deviceIdentity
+            deviceIdentity,
+            metaNode
         });
         await this.options.messageClient.sendMessageNode(retryNode);
         return 'resent';
@@ -87,6 +193,12 @@ export class WaRetryReplayService {
         if (normalizeDeviceJid(payload.to) !== normalizedRequesterJid) {
             return 'ineligible';
         }
+        const deviceIdentity = payload.encType === 'pkmsg'
+            ? this.resolveSignedDeviceIdentity('encrypted_replay')
+            : undefined;
+        const metaNode = isHostedDeviceJid(requesterJid)
+            ? buildMetaNode({ sender_intent: 'hosted' })
+            : undefined;
         await this.options.messageClient.sendEncrypted({
             to: requesterJid,
             encType: payload.encType,
@@ -94,7 +206,9 @@ export class WaRetryReplayService {
             encCount: retryCount,
             id: outbound.messageId,
             type: payload.type,
-            participant: payload.participant
+            participant: payload.participant,
+            deviceIdentity,
+            metaNode
         });
         return 'resent';
     }
@@ -115,39 +229,19 @@ export class WaRetryReplayService {
         await this.options.messageClient.sendMessageNode(replayNode);
         return 'resent';
     }
-    async maybeWrapGroupRetryPlaintextForSelfDevice(payload, requesterJid) {
-        if (!this.isRequesterCurrentAccount(requesterJid)) {
-            return null;
-        }
-        try {
-            const messageBytes = unpadPkcs7(payload.plaintext);
-            const message = proto.Message.decode(messageBytes);
-            const wrapped = wrapDeviceSentMessage(message, payload.to);
-            return writeRandomPadMax16(proto.Message.encode(wrapped).finish());
-        }
-        catch (error) {
-            this.options.logger.warn('retry request failed to wrap deviceSent payload for self requester', {
-                requester: requesterJid,
-                to: payload.to,
-                message: toError(error).message
-            });
-            return null;
-        }
-    }
     isRequesterCurrentAccount(requesterJid) {
         const requesterUser = toUserJid(requesterJid);
-        const meJid = this.options.getCurrentMeJid();
-        if (meJid && toUserJid(meJid) === requesterUser) {
+        const credentials = this.options.getCurrentCredentials();
+        if (credentials?.meJid && toUserJid(credentials.meJid) === requesterUser) {
             return true;
         }
-        const meLid = this.options.getCurrentMeLid();
-        if (meLid && toUserJid(meLid) === requesterUser) {
+        if (credentials?.meLid && toUserJid(credentials.meLid) === requesterUser) {
             return true;
         }
         return false;
     }
     isOpaqueReplayCompatible(node, normalizedRequesterJid) {
-        const participantsNode = findNodeChild(node, 'participants');
+        const participantsNode = findNodeChild(node, WA_NODE_TAGS.PARTICIPANTS);
         if (participantsNode) {
             const participantsContent = Array.isArray(participantsNode.content)
                 ? participantsNode.content

package/dist/esm/retry/tracker.js

@@ -1,7 +1,8 @@
-import { isGroupOrBroadcastJid, normalizeDeviceJid } from '../protocol/jid.js';
+import { isGroupOrBroadcastJid, toUserJid } from '../protocol/jid.js';
 import { encodeRetryReplayPayload } from './codec.js';
 import { RETRY_OUTBOUND_TTL_MS } from './constants.js';
 import { toError } from '../util/primitives.js';
+/** Builds an {@link OutboundRetryTracker} backed by a {@link WaRetryStore}. */
 export function createOutboundRetryTracker(options) {
     const { retryStore, logger } = options;
     const retryTtlMs = retryStore.getTtlMs?.() ?? RETRY_OUTBOUND_TTL_MS;
@@ -17,7 +18,7 @@ export function createOutboundRetryTracker(options) {
                 continue;
             }
             try {
-                deduped.add(normalizeDeviceJid(raw));
+                deduped.add(toUserJid(raw));
             }
             catch {
                 continue;
@@ -45,7 +46,6 @@ export function createOutboundRetryTracker(options) {
     };
     return {
         track: async (hint, publish) => {
-            const nowMs = Date.now();
             const replayMode = hint.replayPayload.mode;
             const resolvedToJid = hint.toJid ?? (replayMode === 'opaque_node' ? '' : hint.replayPayload.to);
             const replayPayload = supportsRawReplayPayload
@@ -56,7 +56,7 @@ export function createOutboundRetryTracker(options) {
                 resolvedToJid &&
                 !isGroupOrBroadcastJid(resolvedToJid)) {
                 try {
-                    eligibleRequesterDeviceJids = [normalizeDeviceJid(resolvedToJid)];
+                    eligibleRequesterDeviceJids = [toUserJid(resolvedToJid)];
                 }
                 catch {
                     eligibleRequesterDeviceJids = undefined;
@@ -65,15 +65,11 @@ export function createOutboundRetryTracker(options) {
             const createRetryOutboundRecord = (messageId, updatedAtMs, expiresAtMs) => ({
                 messageId,
                 toJid: resolvedToJid,
-                participantJid: hint.participantJid,
-                recipientJid: hint.recipientJid,
                 eligibleRequesterDeviceJids,
                 deliveredRequesterDeviceJids: [],
-                messageType: hint.type,
                 replayMode,
                 replayPayload,
                 state: 'pending',
-                createdAtMs: nowMs,
                 updatedAtMs,
                 expiresAtMs
             });

package/dist/esm/signal/api/SignalDeviceSyncApi.js

@@ -1,10 +1,14 @@
 import { PromiseDedup } from '../../infra/perf/PromiseDedup.js';
 import { WA_DEFAULTS, WA_NODE_TAGS, WA_USYNC_CONTEXTS } from '../../protocol/constants.js';
 import { buildDeviceJid, isHostedDeviceId, splitJid, toUserJid } from '../../protocol/jid.js';
-import { buildUsyncIq } from '../../transport/node/builders/usync.js';
+import { buildUsyncIq, iterateUsyncUsers, parseUsyncResultEnvelope } from '../../transport/node/builders/usync.js';
 import { findNodeChild, getNodeChildrenByTag } from '../../transport/node/helpers.js';
 import { assertIqResult } from '../../transport/node/query.js';
-import { createUsyncSidGenerator } from '../../transport/node/usync.js';
+import { createUsyncSidGenerator, logUsyncProtocolErrors } from '../../transport/node/usync.js';
+/**
+ * Resolves the device list and LID mapping for a set of users via the `usync`
+ * protocol. Concurrent calls for the same JIDs are deduplicated.
+ */
 export class SignalDeviceSyncApi {
     constructor(options) {
         this.syncDedup = new PromiseDedup();
@@ -16,6 +20,10 @@ export class SignalDeviceSyncApi {
         this.hostDomain = options.hostDomain ?? WA_DEFAULTS.HOST_DOMAIN;
         this.generateSid = options.generateSid ?? createUsyncSidGenerator();
     }
+    /**
+     * Refreshes the device list for every JID in `userJids`. Returns the
+     * resolved per-user device JIDs (matches the on-store snapshot).
+     */
     syncDeviceList(userJids, timeoutMs = this.defaultTimeoutMs) {
         const normalizedUsers = this.normalizeUsers(userJids);
         if (normalizedUsers.length === 0) {
@@ -84,6 +92,10 @@ export class SignalDeviceSyncApi {
         });
         return merged;
     }
+    /**
+     * Looks up LIDs for a list of phone JIDs via a `lid` usync query. Returns
+     * one entry per input JID with `exists` indicating server-side presence.
+     */
     async queryLidsByPhoneJids(phoneJids, timeoutMs = this.defaultTimeoutMs) {
         const normalizedPhoneJids = this.normalizeUsers(phoneJids);
         if (normalizedPhoneJids.length === 0) {
@@ -125,8 +137,51 @@ export class SignalDeviceSyncApi {
             users: result.length,
             found
         });
+        await this.propagateAltUserJids(result);
         return result;
     }
+    /**
+     * Enriches existing device-list snapshots with the resolved LID equivalents
+     * so {@link WaDeviceListStore.findByAnyUserJid} can later match a retry
+     * receipt arriving in LID form against an eligible list stored in PN form
+     * (and vice versa). Skips users with no cached snapshot — the alt gets
+     * recorded on the next {@link syncDeviceList} sweep.
+     */
+    async propagateAltUserJids(results) {
+        if (!this.deviceListStore || results.length === 0)
+            return;
+        const nowMs = Date.now();
+        const lidByPhoneJid = new Map();
+        const phoneJids = [];
+        for (const entry of results) {
+            if (entry.lidJid && entry.phoneJid) {
+                lidByPhoneJid.set(entry.phoneJid, entry.lidJid);
+                phoneJids.push(entry.phoneJid);
+            }
+        }
+        if (phoneJids.length === 0)
+            return;
+        const existing = await this.deviceListStore.getUserDevicesBatch(phoneJids, nowMs);
+        const updates = [];
+        for (let index = 0; index < phoneJids.length; index += 1) {
+            const snapshot = existing[index];
+            if (!snapshot)
+                continue;
+            const phoneJid = phoneJids[index];
+            const lidJid = lidByPhoneJid.get(phoneJid);
+            if (!lidJid || snapshot.altUserJid === lidJid)
+                continue;
+            updates.push({
+                userJid: snapshot.userJid,
+                altUserJid: lidJid,
+                deviceJids: snapshot.deviceJids,
+                updatedAtMs: nowMs
+            });
+        }
+        if (updates.length > 0) {
+            await this.deviceListStore.upsertUserDevicesBatch(updates);
+        }
+    }
     async collectUsersToQuery(normalizedUsers, nowMs, cachedByUser, store) {
         const records = await store.getUserDevicesBatch(normalizedUsers, nowMs);
         const usersToQuery = new Array(normalizedUsers.length);
@@ -200,16 +255,12 @@ export class SignalDeviceSyncApi {
     }
     parseDeviceSyncResponse(node, requestedUsers) {
         assertIqResult(node, 'signal device sync');
-        const usyncNode = findNodeChild(node, WA_NODE_TAGS.USYNC);
-        if (!usyncNode) {
-            throw new Error('signal device sync response missing usync node');
-        }
-        const listNode = findNodeChild(usyncNode, WA_NODE_TAGS.LIST);
-        if (!listNode) {
-            throw new Error('signal device sync response missing list node');
+        logUsyncProtocolErrors(parseUsyncResultEnvelope(node), this.logger, 'signal.deviceSync');
+        const userNodes = iterateUsyncUsers(node);
+        if (!userNodes) {
+            throw new Error('signal device sync response missing usync envelope');
         }
         const requestedSet = new Set(requestedUsers);
-        const userNodes = getNodeChildrenByTag(listNode, WA_NODE_TAGS.USER);
         const parsed = new Array(userNodes.length);
         let parsedCount = 0;
         for (let index = 0; index < userNodes.length; index += 1) {
@@ -233,16 +284,12 @@ export class SignalDeviceSyncApi {
     }
     parseLidSyncResponse(node, requestedUsers) {
         assertIqResult(node, 'signal lid sync');
-        const usyncNode = findNodeChild(node, WA_NODE_TAGS.USYNC);
-        if (!usyncNode) {
-            throw new Error('signal lid sync response missing usync node');
-        }
-        const listNode = findNodeChild(usyncNode, WA_NODE_TAGS.LIST);
-        if (!listNode) {
-            throw new Error('signal lid sync response missing list node');
+        logUsyncProtocolErrors(parseUsyncResultEnvelope(node), this.logger, 'signal.lidSync');
+        const userNodes = iterateUsyncUsers(node);
+        if (!userNodes) {
+            throw new Error('signal lid sync response missing usync envelope');
         }
         const requestedSet = new Set(requestedUsers);
-        const userNodes = getNodeChildrenByTag(listNode, WA_NODE_TAGS.USER);
         const parsed = new Array(userNodes.length);
         let parsedCount = 0;
         for (let index = 0; index < userNodes.length; index += 1) {
@@ -327,9 +374,12 @@ export class SignalDeviceSyncApi {
             return [];
         }
         const parsedNormalizedUser = splitJid(normalizedUserJid);
-        const parsedRawUser = splitJid(rawUserJid);
+        const rawAtIndex = rawUserJid.indexOf('@');
+        const rawServer = rawAtIndex >= 1 && rawAtIndex < rawUserJid.length - 1
+            ? rawUserJid.slice(rawAtIndex + 1)
+            : parsedNormalizedUser.server;
         const dedup = new Set();
-        for (const deviceNode of getNodeChildrenByTag(deviceListNode, 'device')) {
+        for (const deviceNode of getNodeChildrenByTag(deviceListNode, WA_NODE_TAGS.DEVICE)) {
             const parsedId = deviceNode.attrs.id
                 ? Number.parseInt(deviceNode.attrs.id, 10)
                 : Number.NaN;
@@ -338,7 +388,7 @@ export class SignalDeviceSyncApi {
             }
             const isHostedDevice = isHostedDeviceId(parsedId) || deviceNode.attrs.is_hosted === 'true';
             dedup.add(buildDeviceJid(parsedNormalizedUser.user, parsedNormalizedUser.server, parsedId, {
-                rawServer: parsedRawUser.server,
+                rawServer,
                 isHosted: isHostedDevice
             }));
         }

package/dist/esm/signal/api/SignalDigestSyncApi.js

@@ -1,15 +1,22 @@
 import { sha1 } from '../../crypto/index.js';
+import { toRawPubKey } from '../../crypto/core/keys.js';
 import { WA_DEFAULTS, WA_IQ_TYPES, WA_NODE_TAGS, WA_XMLNS } from '../../protocol/constants.js';
 import { decodeExactLength, parseUint } from '../api/codec.js';
 import { SIGNAL_KEY_BUNDLE_TYPE_BYTES, SIGNAL_KEY_BUNDLE_TYPE_LENGTH, SIGNAL_KEY_DATA_LENGTH, SIGNAL_KEY_ID_LENGTH, SIGNAL_REGISTRATION_ID_LENGTH, SIGNAL_SIGNATURE_LENGTH } from '../api/constants.js';
 import { decodeNodeContentBase64OrBytes, findNodeChild, getNodeChildren } from '../../transport/node/helpers.js';
 import { parseIqError } from '../../transport/node/query.js';
-import { concatBytes, uint8Equal } from '../../util/bytes.js';
+import { uint8Equal } from '../../util/bytes.js';
+/**
+ * Validates the local Signal key bundle (identity, signed prekey, one-time
+ * prekey ids) against the server-side digest. Used to detect drift after a
+ * crash or partial sync and decide whether to re-upload.
+ */
 export class SignalDigestSyncApi {
     constructor(options) {
         this.logger = options.logger;
         this.query = options.query;
         this.signalStore = options.signalStore;
+        this.preKeyStore = options.preKeyStore;
         this.defaultTimeoutMs =
             options.defaultTimeoutMs ?? WA_DEFAULTS.SIGNAL_FETCH_KEY_BUNDLES_TIMEOUT_MS;
         this.hostDomain = options.hostDomain ?? WA_DEFAULTS.HOST_DOMAIN;
@@ -82,7 +89,7 @@ export class SignalDigestSyncApi {
                 preKeyCount: digest.preKeyIds.length
             };
         }
-        if (!uint8Equal(registrationInfo.identityKeyPair.pubKey, digest.identity)) {
+        if (!uint8Equal(toRawPubKey(registrationInfo.identityKeyPair.pubKey), toRawPubKey(digest.identity))) {
             return {
                 valid: false,
                 shouldReupload: true,
@@ -91,7 +98,7 @@ export class SignalDigestSyncApi {
             };
         }
         if (signedPreKey.keyId !== digest.signedKey.id ||
-            !uint8Equal(signedPreKey.keyPair.pubKey, digest.signedKey.publicKey) ||
+            !uint8Equal(toRawPubKey(signedPreKey.keyPair.pubKey), toRawPubKey(digest.signedKey.publicKey)) ||
             !uint8Equal(signedPreKey.signature, digest.signedKey.signature)) {
             return {
                 valid: false,
@@ -100,10 +107,10 @@ export class SignalDigestSyncApi {
                 preKeyCount: digest.preKeyIds.length
             };
         }
-        const preKeys = await this.signalStore.getPreKeysById(digest.preKeyIds);
+        const preKeys = await this.preKeyStore.getPreKeysById(digest.preKeyIds);
         const bytesToHash = [
-            registrationInfo.identityKeyPair.pubKey,
-            signedPreKey.keyPair.pubKey,
+            toRawPubKey(registrationInfo.identityKeyPair.pubKey),
+            toRawPubKey(signedPreKey.keyPair.pubKey),
             signedPreKey.signature
         ];
         for (let index = 0; index < preKeys.length; index += 1) {
@@ -116,9 +123,9 @@ export class SignalDigestSyncApi {
                     preKeyCount: digest.preKeyIds.length
                 };
             }
-            bytesToHash.push(preKey.keyPair.pubKey);
+            bytesToHash.push(toRawPubKey(preKey.keyPair.pubKey));
         }
-        const localHash = (await sha1(concatBytes(bytesToHash))).subarray(0, digest.hash.byteLength);
+        const localHash = sha1(bytesToHash).subarray(0, digest.hash.byteLength);
         if (!uint8Equal(localHash, digest.hash)) {
             return {
                 valid: false,

package/dist/esm/signal/api/SignalIdentitySyncApi.js

@@ -6,16 +6,25 @@ import { decodeExactLength, parseUint } from '../api/codec.js';
 import { SIGNAL_KEY_BUNDLE_TYPE_LENGTH, SIGNAL_KEY_DATA_LENGTH } from '../api/constants.js';
 import { findNodeChild, getNodeChildrenByTag } from '../../transport/node/helpers.js';
 import { assertIqResult } from '../../transport/node/query.js';
+/**
+ * Fetches identity keys for a list of JIDs from the server and persists them
+ * into the identity store. Concurrent calls for the same JID set are
+ * deduplicated.
+ */
 export class SignalIdentitySyncApi {
     constructor(options) {
         this.syncDedup = new PromiseDedup();
         this.logger = options.logger;
         this.query = options.query;
-        this.signalStore = options.signalStore;
+        this.identityStore = options.identityStore;
         this.defaultTimeoutMs =
             options.defaultTimeoutMs ?? WA_DEFAULTS.SIGNAL_FETCH_KEY_BUNDLES_TIMEOUT_MS;
         this.hostDomain = options.hostDomain ?? WA_DEFAULTS.HOST_DOMAIN;
     }
+    /**
+     * Fetches and persists identity keys for `targetJids`. Returns one entry
+     * per JID the server resolved; missing/erroring users are skipped.
+     */
     syncIdentityKeys(targetJids, timeoutMs = this.defaultTimeoutMs) {
         const dedupKey = `${timeoutMs}:${targetJids.join(',')}`;
         return this.syncDedup.run(dedupKey, () => this.syncIdentityKeysInternal(targetJids, timeoutMs));
@@ -66,8 +75,8 @@ export class SignalIdentitySyncApi {
             ]
         }, timeoutMs);
         const entries = this.parseIdentitySyncResponse(response, normalizedTargets);
-        const { signalStore } = this;
-        if (signalStore && entries.length > 0) {
+        const { identityStore } = this;
+        if (identityStore && entries.length > 0) {
             const identities = new Array(entries.length);
             for (let index = 0; index < entries.length; index += 1) {
                 const entry = entries[index];
@@ -76,7 +85,7 @@ export class SignalIdentitySyncApi {
                     identityKey: toSerializedPubKey(entry.identity)
                 };
             }
-            await signalStore.setRemoteIdentities(identities);
+            await identityStore.setRemoteIdentities(identities);
         }
         this.logger.debug('signal identity sync success', {
             requested: normalizedTargets.length,