zapo-js 0.3.0 → 1.0.0

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) {
@@ -332,7 +379,7 @@ export class SignalDeviceSyncApi {
             ? 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;

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

@@ -5,7 +5,12 @@ 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;
@@ -120,7 +125,7 @@ export class SignalDigestSyncApi {
             }
             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,6 +6,11 @@ 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();
@@ -16,6 +21,10 @@ export class SignalIdentitySyncApi {
             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));

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

@@ -1,14 +1,18 @@
 import { WA_DEFAULTS, WA_NODE_TAGS } from '../../protocol/constants.js';
 import { splitJid, toUserJid } from '../../protocol/jid.js';
-import { decodeExactLength, parseUint } from '../api/codec.js';
-import { SIGNAL_KEY_DATA_LENGTH, SIGNAL_KEY_ID_LENGTH, SIGNAL_REGISTRATION_ID_LENGTH, SIGNAL_SIGNATURE_LENGTH } from '../api/constants.js';
+import { decodeExactLength, parseSignalKeyBundleFromNode, parseUint } from '../api/codec.js';
+import { SIGNAL_REGISTRATION_ID_LENGTH } from '../api/constants.js';
 import { buildMissingPreKeysFetchIq } from '../api/prekeys.js';
 import { registerParsedResultByRawAndCanonicalKey } from '../api/result-map.js';
-import { decodeNodeContentBase64OrBytes, findNodeChild, findNodeChildrenByTags, getNodeChildrenByTag } from '../../transport/node/helpers.js';
+import { findNodeChild, getNodeChildrenByTag } from '../../transport/node/helpers.js';
 import { assertIqResult } from '../../transport/node/query.js';
 function isMissingPreKeysUserResultPreferred(result) {
     return 'devices' in result;
 }
+/**
+ * Fetches missing prekey bundles for specific (user, device, registration id)
+ * triples – used during message encryption when a Signal session is missing.
+ */
 export class SignalMissingPreKeysSyncApi {
     constructor(options) {
         this.logger = options.logger;
@@ -16,6 +20,10 @@ export class SignalMissingPreKeysSyncApi {
         this.defaultTimeoutMs =
             options.defaultTimeoutMs ?? WA_DEFAULTS.SIGNAL_FETCH_KEY_BUNDLES_TIMEOUT_MS;
     }
+    /**
+     * Fetches prekey bundles for the requested `targets` in a single IQ.
+     * Returns either a per-device bundle list or an error envelope per user.
+     */
     async fetchMissingPreKeys(targets, timeoutMs = this.defaultTimeoutMs) {
         if (targets.length === 0) {
             return [];
@@ -91,69 +99,22 @@ export class SignalMissingPreKeysSyncApi {
             if (!Number.isSafeInteger(deviceId) || deviceId < 0) {
                 throw new Error(`missing prekeys device[${index}].id is invalid`);
             }
-            const [registrationNode, identityNode, signedKeyNode, oneTimeNode, deviceIdentityNode] = findNodeChildrenByTags(deviceNode, [
-                WA_NODE_TAGS.REGISTRATION,
-                WA_NODE_TAGS.IDENTITY,
-                WA_NODE_TAGS.SKEY,
-                WA_NODE_TAGS.KEY,
-                WA_NODE_TAGS.DEVICE_IDENTITY
-            ]);
-            if (!registrationNode || !identityNode || !signedKeyNode) {
+            const registrationNode = findNodeChild(deviceNode, WA_NODE_TAGS.REGISTRATION);
+            if (!registrationNode) {
                 throw new Error(`missing prekeys device payload is incomplete for ${userJid}`);
             }
-            const [signedKeyIdNode, signedKeyValueNode, signedKeySignatureNode] = findNodeChildrenByTags(signedKeyNode, [
-                WA_NODE_TAGS.ID,
-                WA_NODE_TAGS.VALUE,
-                WA_NODE_TAGS.SIGNATURE
-            ]);
-            if (!signedKeyIdNode || !signedKeyValueNode || !signedKeySignatureNode) {
-                throw new Error(`missing prekeys signed pre-key is incomplete for ${userJid}`);
-            }
-            let oneTimeIdNode;
-            let oneTimeValueNode;
-            if (oneTimeNode) {
-                const oneTimeNodes = findNodeChildrenByTags(oneTimeNode, [
-                    WA_NODE_TAGS.ID,
-                    WA_NODE_TAGS.VALUE
-                ]);
-                oneTimeIdNode = oneTimeNodes[0];
-                oneTimeValueNode = oneTimeNodes[1];
-            }
-            if (oneTimeNode && (!oneTimeIdNode || !oneTimeValueNode)) {
-                throw new Error(`missing prekeys one-time key is incomplete for ${userJid}`);
-            }
-            const baseBundle = {
-                regId: parseUint(decodeExactLength(registrationNode.content, 'missing prekeys device registration', SIGNAL_REGISTRATION_ID_LENGTH), 'missing prekeys device registration'),
-                identity: decodeExactLength(identityNode.content, 'missing prekeys device identity', SIGNAL_KEY_DATA_LENGTH),
-                signedKey: {
-                    id: parseUint(decodeExactLength(signedKeyIdNode.content, 'missing prekeys device skey.id', SIGNAL_KEY_ID_LENGTH), 'missing prekeys device skey.id'),
-                    publicKey: decodeExactLength(signedKeyValueNode.content, 'missing prekeys device skey.value', SIGNAL_KEY_DATA_LENGTH),
-                    signature: decodeExactLength(signedKeySignatureNode.content, 'missing prekeys device skey.signature', SIGNAL_SIGNATURE_LENGTH)
-                }
+            const regId = parseUint(decodeExactLength(registrationNode.content, 'missing prekeys device registration', SIGNAL_REGISTRATION_ID_LENGTH), 'missing prekeys device registration');
+            const parsed = parseSignalKeyBundleFromNode(deviceNode, 'missing prekeys device');
+            const bundle = {
+                regId,
+                identity: parsed.identity,
+                signedKey: parsed.signedKey,
+                ...(parsed.oneTimeKey ? { oneTimeKey: parsed.oneTimeKey } : {})
             };
-            const bundle = oneTimeIdNode && oneTimeValueNode
-                ? {
-                    ...baseBundle,
-                    oneTimeKey: {
-                        id: parseUint(decodeExactLength(oneTimeIdNode.content, 'missing prekeys device key.id', SIGNAL_KEY_ID_LENGTH), 'missing prekeys device key.id'),
-                        publicKey: decodeExactLength(oneTimeValueNode.content, 'missing prekeys device key.value', SIGNAL_KEY_DATA_LENGTH)
-                    }
-                }
-                : baseBundle;
-            let deviceIdentity;
-            if (deviceIdentityNode) {
-                deviceIdentity = decodeNodeContentBase64OrBytes(deviceIdentityNode.content, 'missing prekeys device device-identity');
-            }
-            bundles[index] = deviceIdentity
-                ? {
-                    deviceJid: deviceId === 0 ? userJid : `${user}:${deviceId}@${server}`,
-                    bundle,
-                    deviceIdentity
-                }
-                : {
-                    deviceJid: deviceId === 0 ? userJid : `${user}:${deviceId}@${server}`,
-                    bundle
-                };
+            const deviceJid = deviceId === 0 ? userJid : `${user}:${deviceId}@${server}`;
+            bundles[index] = parsed.deviceIdentity
+                ? { deviceJid, bundle, deviceIdentity: parsed.deviceIdentity }
+                : { deviceJid, bundle };
         }
         return bundles;
     }

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

@@ -2,6 +2,11 @@ import { WA_DEFAULTS, WA_IQ_TYPES, WA_NODE_TAGS } from '../../protocol/constants
 import { buildSignedPreKeyRotateIq } from '../api/prekeys.js';
 import { generateSignedPreKey } from '../registration/keygen.js';
 import { parseIqError } from '../../transport/node/query.js';
+/**
+ * Generates a fresh signed prekey and uploads it to the server. Handles the
+ * `406`/`409`/`5xx` error codes by signaling whether a digest re-validation
+ * is required.
+ */
 export class SignalRotateKeyApi {
     constructor(options) {
         this.logger = options.logger;
@@ -9,6 +14,11 @@ export class SignalRotateKeyApi {
         this.signalStore = options.signalStore;
         this.defaultTimeoutMs = options.defaultTimeoutMs ?? WA_DEFAULTS.IQ_TIMEOUT_MS;
     }
+    /**
+     * Rotates the signed prekey by generating a new one (next key id) and
+     * uploading it. Returns `shouldDigestKey: true` when the caller should
+     * re-run a digest validation after the rotation.
+     */
     async rotateSignedPreKey(timeoutMs = this.defaultTimeoutMs) {
         const [registrationInfo, currentSignedPreKey] = await Promise.all([
             this.signalStore.getRegistrationInfo(),

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

@@ -1,13 +1,18 @@
 import { WA_DEFAULTS, WA_IQ_TYPES, WA_NODE_TAGS, WA_XMLNS } from '../../protocol/constants.js';
 import { canonicalizeSignalJid } from '../../protocol/jid.js';
-import { decodeExactLength, parseUint } from '../api/codec.js';
-import { SIGNAL_KEY_DATA_LENGTH, SIGNAL_KEY_ID_LENGTH, SIGNAL_REGISTRATION_ID_LENGTH, SIGNAL_SIGNATURE_LENGTH } from '../api/constants.js';
+import { decodeExactLength, parseSignalKeyBundleFromNode, parseUint } from '../api/codec.js';
+import { SIGNAL_REGISTRATION_ID_LENGTH } from '../api/constants.js';
 import { registerParsedResultByRawAndCanonicalKey } from '../api/result-map.js';
-import { decodeNodeContentBase64OrBytes, findNodeChild, getNodeChildrenByTag } from '../../transport/node/helpers.js';
+import { findNodeChild, getNodeChildrenByTag } from '../../transport/node/helpers.js';
 import { assertIqResult } from '../../transport/node/query.js';
 function isKeyBundleResultPreferred(result) {
     return 'bundle' in result;
 }
+/**
+ * Fetches per-device prekey bundles required to start a Signal session.
+ * Use {@link fetchKeyBundle} for single-JID calls or {@link fetchKeyBundles}
+ * for batched encryption.
+ */
 export class SignalSessionSyncApi {
     constructor(options) {
         this.logger = options.logger;
@@ -16,6 +21,10 @@ export class SignalSessionSyncApi {
             options.defaultTimeoutMs ?? WA_DEFAULTS.SIGNAL_FETCH_KEY_BUNDLES_TIMEOUT_MS;
         this.hostDomain = options.hostDomain ?? WA_DEFAULTS.HOST_DOMAIN;
     }
+    /**
+     * Convenience wrapper for {@link fetchKeyBundles} that fetches a single
+     * bundle and throws on server error envelopes.
+     */
     async fetchKeyBundle(target, timeoutMs = this.defaultTimeoutMs) {
         const results = await this.fetchKeyBundles([target], timeoutMs);
         const first = results[0];
@@ -33,6 +42,10 @@ export class SignalSessionSyncApi {
         });
         return parsed;
     }
+    /**
+     * Batched key-bundle fetch. Returns one entry per JID – either a bundle
+     * (success) or an error envelope. Duplicate JIDs are coalesced.
+     */
     async fetchKeyBundles(targets, timeoutMs = this.defaultTimeoutMs) {
         if (targets.length === 0) {
             return [];
@@ -133,57 +146,16 @@ export class SignalSessionSyncApi {
         if (!registrationNode) {
             throw new Error('key bundle user missing registration node');
         }
-        const identityNode = findNodeChild(node, WA_NODE_TAGS.IDENTITY);
-        if (!identityNode) {
-            throw new Error('key bundle user missing identity node');
-        }
-        const signedPreKeyNode = findNodeChild(node, WA_NODE_TAGS.SKEY);
-        if (!signedPreKeyNode) {
-            throw new Error('key bundle user missing signed pre-key node');
-        }
-        const registrationBytes = decodeExactLength(registrationNode.content, 'key bundle registration', SIGNAL_REGISTRATION_ID_LENGTH);
-        const registrationId = parseUint(registrationBytes, 'key bundle registration');
-        const identity = decodeExactLength(identityNode.content, 'key bundle identity', SIGNAL_KEY_DATA_LENGTH);
-        const signedIdNode = findNodeChild(signedPreKeyNode, WA_NODE_TAGS.ID);
-        const signedValueNode = findNodeChild(signedPreKeyNode, WA_NODE_TAGS.VALUE);
-        const signedSignatureNode = findNodeChild(signedPreKeyNode, WA_NODE_TAGS.SIGNATURE);
-        if (!signedIdNode || !signedValueNode || !signedSignatureNode) {
-            throw new Error('key bundle signed pre-key is incomplete');
-        }
-        const signedIdBytes = decodeExactLength(signedIdNode.content, 'key bundle skey.id', SIGNAL_KEY_ID_LENGTH);
-        const signedValue = decodeExactLength(signedValueNode.content, 'key bundle skey.value', SIGNAL_KEY_DATA_LENGTH);
-        const signedSignature = decodeExactLength(signedSignatureNode.content, 'key bundle skey.signature', SIGNAL_SIGNATURE_LENGTH);
-        const preKeyNode = findNodeChild(node, WA_NODE_TAGS.KEY);
-        let oneTimeKey;
-        if (preKeyNode) {
-            const preKeyIdNode = findNodeChild(preKeyNode, WA_NODE_TAGS.ID);
-            const preKeyValueNode = findNodeChild(preKeyNode, WA_NODE_TAGS.VALUE);
-            if (!preKeyIdNode || !preKeyValueNode) {
-                throw new Error('key bundle one-time pre-key is incomplete');
-            }
-            const preKeyIdBytes = decodeExactLength(preKeyIdNode.content, 'key bundle key.id', SIGNAL_KEY_ID_LENGTH);
-            const preKeyValue = decodeExactLength(preKeyValueNode.content, 'key bundle key.value', SIGNAL_KEY_DATA_LENGTH);
-            oneTimeKey = {
-                id: parseUint(preKeyIdBytes, 'key bundle key.id'),
-                publicKey: preKeyValue
-            };
-        }
-        const deviceIdentityNode = findNodeChild(node, WA_NODE_TAGS.DEVICE_IDENTITY);
-        const deviceIdentity = deviceIdentityNode
-            ? decodeNodeContentBase64OrBytes(deviceIdentityNode.content, 'key bundle device-identity')
-            : undefined;
+        const regId = parseUint(decodeExactLength(registrationNode.content, 'key bundle registration', SIGNAL_REGISTRATION_ID_LENGTH), 'key bundle registration');
+        const parsed = parseSignalKeyBundleFromNode(node, 'key bundle');
         return {
             bundle: {
-                regId: registrationId,
-                identity,
-                signedKey: {
-                    id: parseUint(signedIdBytes, 'key bundle skey.id'),
-                    publicKey: signedValue,
-                    signature: signedSignature
-                },
-                ...(oneTimeKey ? { oneTimeKey } : {})
+                regId,
+                identity: parsed.identity,
+                signedKey: parsed.signedKey,
+                ...(parsed.oneTimeKey ? { oneTimeKey: parsed.oneTimeKey } : {})
             },
-            ...(deviceIdentity ? { deviceIdentity } : {})
+            ...(parsed.deviceIdentity ? { deviceIdentity: parsed.deviceIdentity } : {})
         };
     }
 }

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

@@ -1,4 +1,6 @@
-import { decodeNodeContentBase64OrBytes } from '../../transport/node/helpers.js';
+import { WA_NODE_TAGS } from '../../protocol/constants.js';
+import { SIGNAL_KEY_DATA_LENGTH, SIGNAL_KEY_ID_LENGTH, SIGNAL_SIGNATURE_LENGTH } from '../api/constants.js';
+import { decodeNodeContentBase64OrBytes, findNodeChildrenByTags } from '../../transport/node/helpers.js';
 export function decodeExactLength(value, field, expectedLength) {
     const bytes = decodeNodeContentBase64OrBytes(value, field);
     if (bytes.byteLength !== expectedLength) {
@@ -21,3 +23,52 @@ export function parseUint(bytes, field) {
     }
     throw new Error(`${field} has invalid byte length`);
 }
+/**
+ * Parses the shared `<identity><skey id|value|signature><key id|value><device-identity>`
+ * shape used by session pre-key bundles, missing pre-key device bundles, and retry
+ * receipt key bundles. Caller is responsible for parsing the `<registration>` node
+ * separately when it lives at the same level (it's omitted from retry bundles).
+ */
+export function parseSignalKeyBundleFromNode(node, fieldPrefix) {
+    const [identityNode, signedKeyNode, oneTimeKeyNode, deviceIdentityNode] = findNodeChildrenByTags(node, [
+        WA_NODE_TAGS.IDENTITY,
+        WA_NODE_TAGS.SKEY,
+        WA_NODE_TAGS.KEY,
+        WA_NODE_TAGS.DEVICE_IDENTITY
+    ]);
+    if (!identityNode) {
+        throw new Error(`${fieldPrefix} missing identity node`);
+    }
+    if (!signedKeyNode) {
+        throw new Error(`${fieldPrefix} missing signed pre-key node`);
+    }
+    const identity = decodeExactLength(identityNode.content, `${fieldPrefix}.identity`, SIGNAL_KEY_DATA_LENGTH);
+    const [signedKeyIdNode, signedKeyValueNode, signedKeySignatureNode] = findNodeChildrenByTags(signedKeyNode, [WA_NODE_TAGS.ID, WA_NODE_TAGS.VALUE, WA_NODE_TAGS.SIGNATURE]);
+    if (!signedKeyIdNode || !signedKeyValueNode || !signedKeySignatureNode) {
+        throw new Error(`${fieldPrefix} signed pre-key is incomplete`);
+    }
+    const signedKey = {
+        id: parseUint(decodeExactLength(signedKeyIdNode.content, `${fieldPrefix}.skey.id`, SIGNAL_KEY_ID_LENGTH), `${fieldPrefix}.skey.id`),
+        publicKey: decodeExactLength(signedKeyValueNode.content, `${fieldPrefix}.skey.value`, SIGNAL_KEY_DATA_LENGTH),
+        signature: decodeExactLength(signedKeySignatureNode.content, `${fieldPrefix}.skey.signature`, SIGNAL_SIGNATURE_LENGTH)
+    };
+    let oneTimeKey;
+    if (oneTimeKeyNode) {
+        const [oneTimeKeyIdNode, oneTimeKeyValueNode] = findNodeChildrenByTags(oneTimeKeyNode, [
+            WA_NODE_TAGS.ID,
+            WA_NODE_TAGS.VALUE
+        ]);
+        if (!oneTimeKeyIdNode || !oneTimeKeyValueNode) {
+            throw new Error(`${fieldPrefix} one-time pre-key is incomplete`);
+        }
+        oneTimeKey = {
+            id: parseUint(decodeExactLength(oneTimeKeyIdNode.content, `${fieldPrefix}.key.id`, SIGNAL_KEY_ID_LENGTH), `${fieldPrefix}.key.id`),
+            publicKey: decodeExactLength(oneTimeKeyValueNode.content, `${fieldPrefix}.key.value`, SIGNAL_KEY_DATA_LENGTH)
+        };
+    }
+    let deviceIdentity;
+    if (deviceIdentityNode) {
+        deviceIdentity = decodeNodeContentBase64OrBytes(deviceIdentityNode.content, `${fieldPrefix}.device-identity`);
+    }
+    return { identity, signedKey, oneTimeKey, deviceIdentity };
+}

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

@@ -1,5 +1,9 @@
 import { parseIqError } from '../../transport/node/query.js';
 export { buildMissingPreKeysFetchIq, buildPreKeyUploadIq, buildSignedPreKeyRotateIq } from '../../transport/node/builders/prekeys.js';
+/**
+ * Extracts the numeric error code and text from a failed `prekey` upload IQ
+ * response. Use after a non-success status to decide whether to retry.
+ */
 export function parsePreKeyUploadFailure(node) {
     const error = parseIqError(node);
     return {

package/dist/esm/signal/{crypto → attestation}/WaAdvSignature.js

@@ -1,7 +1,7 @@
-import { hmacSign, importHmacKey, toRawPubKey, xeddsaSign, xeddsaVerify } from '../../crypto/index.js';
-import { ADV_PREFIX_ACCOUNT_SIGNATURE, ADV_PREFIX_DEVICE_SIGNATURE, ADV_PREFIX_HOSTED_ACCOUNT_SIGNATURE, ADV_PREFIX_HOSTED_DEVICE_SIGNATURE } from '../crypto/constants.js';
+import { hmacSha256Sign, toRawPubKey, xeddsaSign, xeddsaVerify } from '../../crypto/index.js';
+import { ADV_PREFIX_ACCOUNT_SIGNATURE, ADV_PREFIX_DEVICE_SIGNATURE, ADV_PREFIX_HOSTED_ACCOUNT_SIGNATURE, ADV_PREFIX_HOSTED_DEVICE_SIGNATURE } from '../attestation/constants.js';
 import { concatBytes } from '../../util/bytes.js';
-export { ADV_PREFIX_ACCOUNT_SIGNATURE, ADV_PREFIX_DEVICE_SIGNATURE, ADV_PREFIX_HOSTED_ACCOUNT_SIGNATURE, ADV_PREFIX_HOSTED_DEVICE_SIGNATURE } from '../crypto/constants.js';
+export { ADV_PREFIX_ACCOUNT_SIGNATURE, ADV_PREFIX_DEVICE_SIGNATURE, ADV_PREFIX_HOSTED_ACCOUNT_SIGNATURE } from '../attestation/constants.js';
 export async function verifyDeviceIdentityAccountSignature(details, accountSignature, identityPublicKey, accountSignatureKey, isHosted = false) {
     const prefix = isHosted ? ADV_PREFIX_HOSTED_ACCOUNT_SIGNATURE : ADV_PREFIX_ACCOUNT_SIGNATURE;
     const message = concatBytes([prefix, details, identityPublicKey]);
@@ -12,7 +12,6 @@ export async function generateDeviceSignature(details, identityKeyPair, accountS
     const message = concatBytes([prefix, details, identityKeyPair.pubKey, accountSignatureKey]);
     return xeddsaSign(identityKeyPair.privKey, message);
 }
-export async function computeAdvIdentityHmac(secretKey, details) {
-    const key = await importHmacKey(secretKey);
-    return hmacSign(key, details);
+export function computeAdvIdentityHmac(secretKey, details) {
+    return hmacSha256Sign(secretKey, details);
 }

package/dist/esm/signal/constants.js

@@ -9,4 +9,7 @@ export const SENDER_KEY_FUTURE_MESSAGES_MAX = 20000;
 export const MESSAGE_KEY_LABEL = new Uint8Array([1]);
 export const CHAIN_KEY_LABEL = new Uint8Array([2]);
 export const WHISPER_GROUP_INFO = TEXT_ENCODER.encode('WhisperGroup');
+export const WHISPER_MESSAGE_KEYS_INFO = TEXT_ENCODER.encode('WhisperMessageKeys');
+export const WHISPER_TEXT_INFO = TEXT_ENCODER.encode('WhisperText');
+export const WHISPER_RATCHET_INFO = TEXT_ENCODER.encode('WhisperRatchet');
 export const SIGNAL_PREFIX = new Uint8Array(32).fill(0xff);