zapo-js 0.2.0 → 1.0.0

package/dist/protocol/notification.js

@@ -1,10 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WA_GROUP_NOTIFICATION_TAGS = exports.WA_NOTIFICATION_TYPES = void 0;
+exports.WA_GROUP_NOTIFICATION_TAGS = exports.WA_REGISTRATION_NOTIFICATION_TAGS = exports.WA_NEWSLETTER_NOTIFICATION_TAGS = exports.WA_BUSINESS_NOTIFICATION_TAGS = exports.WA_NOTIFICATION_TYPES = void 0;
 exports.WA_NOTIFICATION_TYPES = Object.freeze({
     GROUP: 'w:gp2',
     ENCRYPT: 'encrypt',
-    DEVICES: 'devices'
+    DEVICES: 'devices',
+    SERVER: 'server',
+    REGISTRATION: 'registration',
+    NEWSLETTER: 'newsletter',
+    BUSINESS: 'business',
+    PICTURE: 'picture'
+});
+exports.WA_BUSINESS_NOTIFICATION_TAGS = Object.freeze({
+    VERIFIED_NAME: 'verified_name',
+    REMOVE: 'remove',
+    PROFILE: 'profile',
+    PRODUCT_CATALOG: 'product_catalog',
+    SUBSCRIPTIONS: 'subscriptions',
+    FEATURE_FLAGS: 'feature_flags'
+});
+exports.WA_NEWSLETTER_NOTIFICATION_TAGS = Object.freeze({
+    LIVE_UPDATES: 'live_updates'
+});
+exports.WA_REGISTRATION_NOTIFICATION_TAGS = Object.freeze({
+    WA_OLD_REGISTRATION: 'wa_old_registration',
+    DEVICE_LOGOUT: 'device_logout'
 });
 exports.WA_GROUP_NOTIFICATION_TAGS = Object.freeze({
     REMOVE: 'remove',
@@ -51,5 +71,7 @@ exports.WA_GROUP_NOTIFICATION_TAGS = Object.freeze({
     IS_CAPI_HOSTED_GROUP: 'is_capi_hosted_group',
     GROUP_SAFETY_CHECK: 'group_safety_check',
     LIMIT_SHARING_ENABLED: 'limit_sharing_enabled',
-    MISSING_PARTICIPANT_IDENTIFICATION: 'missing_participant_identification'
+    MISSING_PARTICIPANT_IDENTIFICATION: 'missing_participant_identification',
+    GROUP_HISTORY: 'group_history',
+    NO_GROUP_HISTORY: 'no_group_history'
 });

package/dist/protocol/presence.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WA_CHATSTATE_MEDIA = exports.WA_PRESENCE_LAST_SENTINELS = exports.WA_PRESENCE_TYPES = void 0;
+exports.WA_PRESENCE_TYPES = Object.freeze({
+    AVAILABLE: 'available',
+    UNAVAILABLE: 'unavailable',
+    SUBSCRIBE: 'subscribe'
+});
+exports.WA_PRESENCE_LAST_SENTINELS = Object.freeze({
+    DENY: 'deny',
+    NONE: 'none',
+    ERROR: 'error'
+});
+exports.WA_CHATSTATE_MEDIA = Object.freeze({
+    AUDIO: 'audio'
+});

package/dist/protocol/status.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WA_STATUS_DISTRIBUTION_SETTINGS = void 0;
+exports.WA_STATUS_DISTRIBUTION_SETTINGS = Object.freeze({
+    CONTACTS: 'contacts',
+    ALLOWLIST: 'allowlist',
+    DENYLIST: 'denylist',
+    CLOSE_FRIENDS: 'close_friends'
+});

package/dist/retry/codec.js

@@ -20,6 +20,10 @@ const RETRY_PAYLOAD_ENC_TYPE_REVERSE = Object.freeze({
     2: 'pkmsg',
     3: 'skmsg'
 });
+/**
+ * Encodes a {@link WaRetryReplayPayload} into the on-disk codec format used
+ * by the retry store. Supports the `plaintext`/`encrypted`/`opaque_node` modes.
+ */
 function encodeRetryReplayPayload(payload) {
     const chunks = [];
     if (payload.mode === 'plaintext') {
@@ -60,6 +64,7 @@ function encodeRetryReplayPayload(payload) {
     pushBytesField(chunks, payload.node, 'node');
     return (0, bytes_1.concatBytes)(chunks);
 }
+/** Inverse of {@link encodeRetryReplayPayload}. Throws on bad magic/version. */
 function decodeRetryReplayPayload(raw) {
     if (raw.byteLength < 3) {
         throw new Error('invalid retry replay payload: unsupported codec version');

package/dist/retry/parse.js

@@ -51,47 +51,25 @@ function parseRetryKeyBundle(node) {
     if (!node) {
         return undefined;
     }
-    const [identityNode, signedKeyNode, keyNode, deviceIdentityNode] = (0, helpers_1.findNodeChildrenByTags)(node, [constants_1.WA_NODE_TAGS.IDENTITY, constants_1.WA_NODE_TAGS.SKEY, constants_1.WA_NODE_TAGS.KEY, constants_1.WA_NODE_TAGS.DEVICE_IDENTITY]);
-    const identity = requireNode(identityNode, 'retry keys section missing identity or skey');
-    const signedKey = requireNode(signedKeyNode, 'retry keys section missing identity or skey');
-    const [signedKeyIdNode, signedKeyValueNode, signedKeySignatureNode] = (0, helpers_1.findNodeChildrenByTags)(signedKey, [constants_1.WA_NODE_TAGS.ID, constants_1.WA_NODE_TAGS.VALUE, constants_1.WA_NODE_TAGS.SIGNATURE]);
-    const signedKeyId = requireNode(signedKeyIdNode, 'retry keys section has incomplete skey');
-    const signedKeyValue = requireNode(signedKeyValueNode, 'retry keys section has incomplete skey');
-    const signedKeySignature = requireNode(signedKeySignatureNode, 'retry keys section has incomplete skey');
-    let keyIdNode;
-    let keyValueNode;
-    if (keyNode) {
-        const keyNodes = (0, helpers_1.findNodeChildrenByTags)(keyNode, [constants_1.WA_NODE_TAGS.ID, constants_1.WA_NODE_TAGS.VALUE]);
-        keyIdNode = keyNodes[0];
-        keyValueNode = keyNodes[1];
-    }
-    const keyId = keyNode ? requireNode(keyIdNode, 'retry keys section has incomplete key') : null;
-    const keyValue = keyNode
-        ? requireNode(keyValueNode, 'retry keys section has incomplete key')
-        : null;
+    const parsed = (0, codec_1.parseSignalKeyBundleFromNode)(node, 'retry.keys');
     return {
-        identity: (0, codec_1.decodeExactLength)(identity.content, 'retry.keys.identity', constants_2.SIGNAL_KEY_DATA_LENGTH),
-        deviceIdentity: deviceIdentityNode
-            ? (0, helpers_1.decodeNodeContentBase64OrBytes)(deviceIdentityNode.content, 'retry.keys.device-identity')
-            : undefined,
-        key: keyId && keyValue
-            ? {
-                id: (0, codec_1.parseUint)((0, codec_1.decodeExactLength)(keyId.content, 'retry.keys.key.id', constants_2.SIGNAL_KEY_ID_LENGTH), 'retry.keys.key.id'),
-                publicKey: (0, codec_1.decodeExactLength)(keyValue.content, 'retry.keys.key.value', constants_2.SIGNAL_KEY_DATA_LENGTH)
-            }
-            : undefined,
-        skey: {
-            id: (0, codec_1.parseUint)((0, codec_1.decodeExactLength)(signedKeyId.content, 'retry.keys.skey.id', constants_2.SIGNAL_KEY_ID_LENGTH), 'retry.keys.skey.id'),
-            publicKey: (0, codec_1.decodeExactLength)(signedKeyValue.content, 'retry.keys.skey.value', constants_2.SIGNAL_KEY_DATA_LENGTH),
-            signature: (0, codec_1.decodeExactLength)(signedKeySignature.content, 'retry.keys.skey.signature', constants_2.SIGNAL_SIGNATURE_LENGTH)
-        }
+        identity: parsed.identity,
+        ...(parsed.deviceIdentity ? { deviceIdentity: parsed.deviceIdentity } : {}),
+        ...(parsed.oneTimeKey ? { key: parsed.oneTimeKey } : {}),
+        skey: parsed.signedKey
     };
 }
+/**
+ * Parses an incoming `receipt` stanza into a {@link WaParsedRetryRequest}.
+ * Returns `null` when the stanza is not a retry/rekey-retry receipt; throws
+ * when required attrs/children are missing.
+ */
 function parseRetryReceiptRequest(node, options) {
     if (node.tag !== constants_1.WA_MESSAGE_TAGS.RECEIPT) {
         return null;
     }
-    const receiptType = node.attrs.type === 'retry' || node.attrs.type === 'enc_rekey_retry'
+    const receiptType = node.attrs.type === constants_1.WA_MESSAGE_TYPES.RECEIPT_TYPE_RETRY ||
+        node.attrs.type === constants_1.WA_MESSAGE_TYPES.RECEIPT_TYPE_ENC_REKEY_RETRY
         ? node.attrs.type
         : null;
     if (!receiptType) {
@@ -131,6 +109,10 @@ function parseRetryReceiptRequest(node, options) {
         keyBundle: parseRetryKeyBundle(keysNode)
     };
 }
+/**
+ * Returns whichever of `left`/`right` represents the more advanced retry
+ * state (according to the internal precedence rank).
+ */
 function pickRetryStateMax(left, right) {
     return RETRY_STATE_RANK[left] >= RETRY_STATE_RANK[right] ? left : right;
 }

package/dist/retry/reason.js

@@ -40,6 +40,11 @@ const RETRY_REASON_MATCHERS = [
         code: constants_1.RETRY_REASON.StatusRevokeDelay
     }
 ];
+/**
+ * Maps a decryption/Signal error to the appropriate {@link WaRetryReasonCode}
+ * so an outbound retry receipt carries the correct `error` attribute.
+ * Returns `undefined` when no known reason matches.
+ */
 function mapRetryReasonFromError(error) {
     const message = (0, primitives_1.toError)(error).message.toLowerCase();
     for (const matcher of RETRY_REASON_MATCHERS) {
@@ -49,5 +54,5 @@ function mapRetryReasonFromError(error) {
             return matcher.code;
         }
     }
-    return constants_1.RETRY_REASON.UnknownError;
+    return undefined;
 }

package/dist/retry/replay.js

@@ -1,19 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WaRetryReplayService = void 0;
-const device_sent_1 = require("../message/device-sent");
-const padding_1 = require("../message/padding");
+const icdc_1 = require("../message/crypto/icdc");
+const device_sent_1 = require("../message/encode/device-sent");
+const padding_1 = require("../message/encode/padding");
 const _proto_1 = require("../proto.js");
+const constants_1 = require("../protocol/constants");
 const jid_1 = require("../protocol/jid");
 const codec_1 = require("./codec");
 const binary_1 = require("../transport/binary");
 const message_1 = require("../transport/node/builders/message");
 const helpers_1 = require("../transport/node/helpers");
 const primitives_1 = require("../util/primitives");
+/**
+ * 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.
+ */
 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
             ? (0, codec_1.decodeRetryReplayPayload)(outbound.replayPayload)
@@ -42,43 +54,137 @@ 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 = (0, jid_1.isHostedDeviceJid)(requesterJid)
+            ? (0, message_1.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_1.proto.ADVSignedDeviceIdentity.encode(signedIdentity).finish();
+    }
+    async refreshRetryPlaintext(payload, options) {
+        if (!options.wrapAsDeviceSent && !this.options.resolveUserIcdc) {
+            return null;
+        }
+        try {
+            const messageBytes = (0, padding_1.unpadPkcs7)(payload.plaintext);
+            const decoded = _proto_1.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 = (0, icdc_1.injectDeviceListMetadata)(message, senderIcdc, recipientIcdc);
+                if (injected !== message) {
+                    message = injected;
+                    changed = true;
+                }
+            }
+            if (options.wrapAsDeviceSent && !message.deviceSentMessage) {
+                message = (0, device_sent_1.wrapDeviceSentMessage)(message, payload.to);
+                changed = true;
+            }
+            if (!changed) {
+                return null;
+            }
+            return (0, padding_1.writeRandomPadMax16)(_proto_1.proto.Message.encode(message).finish());
+        }
+        catch (error) {
+            this.options.logger.warn('retry request failed to refresh plaintext', {
+                context: options.logContext,
+                to: payload.to,
+                message: (0, primitives_1.toError)(error).message
+            });
+            return null;
+        }
+    }
+    safeUserJid(jid) {
+        if (!jid)
+            return null;
+        try {
+            return (0, jid_1.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_1.proto.ADVSignedDeviceIdentity.encode(signedIdentity).finish();
         }
+        const isStatus = (0, jid_1.isStatusBroadcastJid)(payload.to);
+        const metaAttrs = {};
+        if (isStatus) {
+            metaAttrs.status_setting = payload.statusSetting ?? 'contacts';
+        }
+        if ((0, jid_1.isHostedDeviceJid)(requesterJid)) {
+            metaAttrs.sender_intent = 'hosted';
+        }
+        const metaNode = Object.keys(metaAttrs).length > 0 ? (0, message_1.buildMetaNode)(metaAttrs) : undefined;
         const retryNode = (0, message_1.buildGroupRetryMessageNode)({
             to: payload.to,
             type: payload.type,
             id: outbound.messageId,
             requesterJid,
-            addressingMode: requesterAddress.server === 'lid' ? 'lid' : 'pn',
+            addressingMode: isStatus
+                ? undefined
+                : requesterAddress.server === constants_1.WA_DEFAULTS.LID_SERVER
+                    ? 'lid'
+                    : 'pn',
             encType: encrypted.type,
             ciphertext: encrypted.ciphertext,
             retryCount,
-            deviceIdentity
+            deviceIdentity,
+            metaNode
         });
         await this.options.messageClient.sendMessageNode(retryNode);
         return 'resent';
@@ -90,6 +196,12 @@ class WaRetryReplayService {
         if ((0, jid_1.normalizeDeviceJid)(payload.to) !== normalizedRequesterJid) {
             return 'ineligible';
         }
+        const deviceIdentity = payload.encType === 'pkmsg'
+            ? this.resolveSignedDeviceIdentity('encrypted_replay')
+            : undefined;
+        const metaNode = (0, jid_1.isHostedDeviceJid)(requesterJid)
+            ? (0, message_1.buildMetaNode)({ sender_intent: 'hosted' })
+            : undefined;
         await this.options.messageClient.sendEncrypted({
             to: requesterJid,
             encType: payload.encType,
@@ -97,7 +209,9 @@ class WaRetryReplayService {
             encCount: retryCount,
             id: outbound.messageId,
             type: payload.type,
-            participant: payload.participant
+            participant: payload.participant,
+            deviceIdentity,
+            metaNode
         });
         return 'resent';
     }
@@ -118,39 +232,19 @@ class WaRetryReplayService {
         await this.options.messageClient.sendMessageNode(replayNode);
         return 'resent';
     }
-    async maybeWrapGroupRetryPlaintextForSelfDevice(payload, requesterJid) {
-        if (!this.isRequesterCurrentAccount(requesterJid)) {
-            return null;
-        }
-        try {
-            const messageBytes = (0, padding_1.unpadPkcs7)(payload.plaintext);
-            const message = _proto_1.proto.Message.decode(messageBytes);
-            const wrapped = (0, device_sent_1.wrapDeviceSentMessage)(message, payload.to);
-            return (0, padding_1.writeRandomPadMax16)(_proto_1.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: (0, primitives_1.toError)(error).message
-            });
-            return null;
-        }
-    }
     isRequesterCurrentAccount(requesterJid) {
         const requesterUser = (0, jid_1.toUserJid)(requesterJid);
-        const meJid = this.options.getCurrentMeJid();
-        if (meJid && (0, jid_1.toUserJid)(meJid) === requesterUser) {
+        const credentials = this.options.getCurrentCredentials();
+        if (credentials?.meJid && (0, jid_1.toUserJid)(credentials.meJid) === requesterUser) {
             return true;
         }
-        const meLid = this.options.getCurrentMeLid();
-        if (meLid && (0, jid_1.toUserJid)(meLid) === requesterUser) {
+        if (credentials?.meLid && (0, jid_1.toUserJid)(credentials.meLid) === requesterUser) {
             return true;
         }
         return false;
     }
     isOpaqueReplayCompatible(node, normalizedRequesterJid) {
-        const participantsNode = (0, helpers_1.findNodeChild)(node, 'participants');
+        const participantsNode = (0, helpers_1.findNodeChild)(node, constants_1.WA_NODE_TAGS.PARTICIPANTS);
         if (participantsNode) {
             const participantsContent = Array.isArray(participantsNode.content)
                 ? participantsNode.content

package/dist/retry/tracker.js

@@ -5,6 +5,7 @@ const jid_1 = require("../protocol/jid");
 const codec_1 = require("./codec");
 const constants_1 = require("./constants");
 const primitives_1 = require("../util/primitives");
+/** Builds an {@link OutboundRetryTracker} backed by a {@link WaRetryStore}. */
 function createOutboundRetryTracker(options) {
     const { retryStore, logger } = options;
     const retryTtlMs = retryStore.getTtlMs?.() ?? constants_1.RETRY_OUTBOUND_TTL_MS;
@@ -20,7 +21,7 @@ function createOutboundRetryTracker(options) {
                 continue;
             }
             try {
-                deduped.add((0, jid_1.normalizeDeviceJid)(raw));
+                deduped.add((0, jid_1.toUserJid)(raw));
             }
             catch {
                 continue;
@@ -48,7 +49,6 @@ 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
@@ -59,7 +59,7 @@ function createOutboundRetryTracker(options) {
                 resolvedToJid &&
                 !(0, jid_1.isGroupOrBroadcastJid)(resolvedToJid)) {
                 try {
-                    eligibleRequesterDeviceJids = [(0, jid_1.normalizeDeviceJid)(resolvedToJid)];
+                    eligibleRequesterDeviceJids = [(0, jid_1.toUserJid)(resolvedToJid)];
                 }
                 catch {
                     eligibleRequesterDeviceJids = undefined;
@@ -68,15 +68,11 @@ 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/signal/api/SignalDeviceSyncApi.js

@@ -8,6 +8,10 @@ const usync_1 = require("../../transport/node/builders/usync");
 const helpers_1 = require("../../transport/node/helpers");
 const query_1 = require("../../transport/node/query");
 const usync_2 = require("../../transport/node/usync");
+/**
+ * Resolves the device list and LID mapping for a set of users via the `usync`
+ * protocol. Concurrent calls for the same JIDs are deduplicated.
+ */
 class SignalDeviceSyncApi {
     constructor(options) {
         this.syncDedup = new PromiseDedup_1.PromiseDedup();
@@ -19,6 +23,10 @@ class SignalDeviceSyncApi {
         this.hostDomain = options.hostDomain ?? constants_1.WA_DEFAULTS.HOST_DOMAIN;
         this.generateSid = options.generateSid ?? (0, usync_2.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) {
@@ -87,6 +95,10 @@ 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) {
@@ -128,8 +140,51 @@ 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);
@@ -203,16 +258,12 @@ class SignalDeviceSyncApi {
     }
     parseDeviceSyncResponse(node, requestedUsers) {
         (0, query_1.assertIqResult)(node, 'signal device sync');
-        const usyncNode = (0, helpers_1.findNodeChild)(node, constants_1.WA_NODE_TAGS.USYNC);
-        if (!usyncNode) {
-            throw new Error('signal device sync response missing usync node');
-        }
-        const listNode = (0, helpers_1.findNodeChild)(usyncNode, constants_1.WA_NODE_TAGS.LIST);
-        if (!listNode) {
-            throw new Error('signal device sync response missing list node');
+        (0, usync_2.logUsyncProtocolErrors)((0, usync_1.parseUsyncResultEnvelope)(node), this.logger, 'signal.deviceSync');
+        const userNodes = (0, usync_1.iterateUsyncUsers)(node);
+        if (!userNodes) {
+            throw new Error('signal device sync response missing usync envelope');
         }
         const requestedSet = new Set(requestedUsers);
-        const userNodes = (0, helpers_1.getNodeChildrenByTag)(listNode, constants_1.WA_NODE_TAGS.USER);
         const parsed = new Array(userNodes.length);
         let parsedCount = 0;
         for (let index = 0; index < userNodes.length; index += 1) {
@@ -236,16 +287,12 @@ class SignalDeviceSyncApi {
     }
     parseLidSyncResponse(node, requestedUsers) {
         (0, query_1.assertIqResult)(node, 'signal lid sync');
-        const usyncNode = (0, helpers_1.findNodeChild)(node, constants_1.WA_NODE_TAGS.USYNC);
-        if (!usyncNode) {
-            throw new Error('signal lid sync response missing usync node');
-        }
-        const listNode = (0, helpers_1.findNodeChild)(usyncNode, constants_1.WA_NODE_TAGS.LIST);
-        if (!listNode) {
-            throw new Error('signal lid sync response missing list node');
+        (0, usync_2.logUsyncProtocolErrors)((0, usync_1.parseUsyncResultEnvelope)(node), this.logger, 'signal.lidSync');
+        const userNodes = (0, usync_1.iterateUsyncUsers)(node);
+        if (!userNodes) {
+            throw new Error('signal lid sync response missing usync envelope');
         }
         const requestedSet = new Set(requestedUsers);
-        const userNodes = (0, helpers_1.getNodeChildrenByTag)(listNode, constants_1.WA_NODE_TAGS.USER);
         const parsed = new Array(userNodes.length);
         let parsedCount = 0;
         for (let index = 0; index < userNodes.length; index += 1) {
@@ -330,9 +377,12 @@ class SignalDeviceSyncApi {
             return [];
         }
         const parsedNormalizedUser = (0, jid_1.splitJid)(normalizedUserJid);
-        const parsedRawUser = (0, jid_1.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 (0, helpers_1.getNodeChildrenByTag)(deviceListNode, 'device')) {
+        for (const deviceNode of (0, helpers_1.getNodeChildrenByTag)(deviceListNode, constants_1.WA_NODE_TAGS.DEVICE)) {
             const parsedId = deviceNode.attrs.id
                 ? Number.parseInt(deviceNode.attrs.id, 10)
                 : Number.NaN;
@@ -341,7 +391,7 @@ class SignalDeviceSyncApi {
             }
             const isHostedDevice = (0, jid_1.isHostedDeviceId)(parsedId) || deviceNode.attrs.is_hosted === 'true';
             dedup.add((0, jid_1.buildDeviceJid)(parsedNormalizedUser.user, parsedNormalizedUser.server, parsedId, {
-                rawServer: parsedRawUser.server,
+                rawServer,
                 isHosted: isHostedDevice
             }));
         }