zapo-js 1.4.0 → 1.5.0

package/dist/esm/client/messaging/companion-host.js

@@ -0,0 +1,56 @@
+import { promisify } from 'node:util';
+import { deflate } from 'node:zlib';
+import { proto } from '../../proto.js';
+const deflateAsync = promisify(deflate);
+/**
+ * Serializes a `HistorySync` and zlib-deflates it. The phone uses DEFLATE
+ * level 1; any zlib-framed level inflates identically, so it is only a
+ * size/speed tradeoff.
+ */
+export async function encodeHistorySync(content) {
+    const serialized = proto.HistorySync.encode(content).finish();
+    const compressed = await deflateAsync(serialized, { level: 1 });
+    return new Uint8Array(compressed);
+}
+/**
+ * Wraps a deflated `HistorySync` inline in a `HISTORY_SYNC_NOTIFICATION` protocol
+ * message. Only small syncs are inlined; larger ones ride an external
+ * `md-msg-hist` MMS blob referenced by the same notification.
+ */
+export function buildInlineHistorySyncNotification(syncType, deflatedPayload, options = {}) {
+    return {
+        type: proto.Message.ProtocolMessage.Type.HISTORY_SYNC_NOTIFICATION,
+        historySyncNotification: {
+            syncType,
+            chunkOrder: options.chunkOrder ?? 0,
+            progress: options.progress ?? 100,
+            initialHistBootstrapInlinePayload: deflatedPayload
+        }
+    };
+}
+/**
+ * Builds the `INITIAL_BOOTSTRAP` `HISTORY_SYNC_NOTIFICATION` a mobile-primary
+ * pushes to a freshly-linked companion: a deflated `HistorySync` wrapped in a
+ * protocol message for delivery as an encrypted peer message. Note
+ * `HistorySync.syncType` and `HistorySyncNotification.syncType` are distinct
+ * enum types with shared values, so each field uses its own.
+ */
+export async function buildHistorySyncBootstrapMessage(input = {}) {
+    const historySync = {
+        syncType: proto.HistorySync.HistorySyncType.INITIAL_BOOTSTRAP,
+        chunkOrder: 0,
+        progress: 100,
+        conversations: input.conversations ? [...input.conversations] : [],
+        pushnames: input.pushnames ? [...input.pushnames] : [],
+        phoneNumberToLidMappings: (input.phoneNumberToLidMappings ?? []).map((mapping) => ({
+            pnJid: mapping.pnJid,
+            lidJid: mapping.lidJid
+        })),
+        ...(input.companionMetaNonce !== undefined
+            ? { companionMetaNonce: input.companionMetaNonce }
+            : {})
+    };
+    const payload = await encodeHistorySync(historySync);
+    const message = buildInlineHistorySyncNotification(proto.Message.HistorySyncType.INITIAL_BOOTSTRAP, payload);
+    return { message, payloadBytes: payload.byteLength };
+}

package/dist/esm/client/messaging/key-protocol.js

@@ -1,6 +1,15 @@
 import { proto } from '../../proto.js';
 import { normalizeDeviceJid } from '../../protocol/jid.js';
 import { bytesToHex } from '../../util/bytes.js';
+/**
+ * Valid app-state sync key ids are exactly 6 bytes: a 2-byte device id followed
+ * by a 4-byte big-endian epoch (matching the phone primary's `crypto_info`
+ * (device_id, epoch) schema and WhatsApp Web's `handleAppStateSyncKeyShare`,
+ * which fatally rejects any share whose keyId byte length is not 6). A primary
+ * must never emit a malformed key, so legacy/short key ids are dropped from
+ * outgoing shares rather than poisoning the peer's syncd engine.
+ */
+const APP_STATE_SYNC_KEY_ID_LENGTH = 6;
 export function createAppStateSyncKeyProtocol(options) {
     const { publishProtocolMessageToDevice, fanoutResolver, getCurrentCredentials, logger } = options;
     const requireCurrentIdentity = (context) => {
@@ -64,7 +73,12 @@ export function createAppStateSyncKeyProtocol(options) {
         const seenKeyIds = new Set();
         const keyShareEntries = [];
         let sharedKeyCount = 0;
+        const droppedKeyIds = [];
         for (const key of keys) {
+            if (key.keyId.byteLength !== APP_STATE_SYNC_KEY_ID_LENGTH) {
+                droppedKeyIds.push(bytesToHex(key.keyId));
+                continue;
+            }
             const keyHex = bytesToHex(key.keyId);
             if (seenKeyIds.has(keyHex)) {
                 continue;
@@ -81,7 +95,10 @@ export function createAppStateSyncKeyProtocol(options) {
             });
         }
         for (const keyId of missingKeyIds) {
-            if (keyId.byteLength === 0) {
+            if (keyId.byteLength !== APP_STATE_SYNC_KEY_ID_LENGTH) {
+                if (keyId.byteLength > 0) {
+                    droppedKeyIds.push(bytesToHex(keyId));
+                }
                 continue;
             }
             const keyHex = bytesToHex(keyId);
@@ -93,6 +110,13 @@ export function createAppStateSyncKeyProtocol(options) {
                 keyId: { keyId }
             });
         }
+        if (droppedKeyIds.length > 0) {
+            logger.warn('app-state refusing to share malformed sync keys: keyId byte length must be 6', {
+                droppedCount: droppedKeyIds.length,
+                totalExpected: keys.length + missingKeyIds.length,
+                sample: droppedKeyIds.slice(0, 5)
+            });
+        }
         const protocolMessage = {
             type: proto.Message.ProtocolMessage.Type.APP_STATE_SYNC_KEY_SHARE,
             appStateSyncKeyShare: {

package/dist/esm/client/persistence/companion-host.js

@@ -0,0 +1,54 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { base64ToBytes, bytesToBase64 } from '../../util/bytes.js';
+/**
+ * File-backed {@link CompanionHostPersistence}: stores the ADV epoch as JSON at
+ * `filePath` (the companion identity keys are base64-encoded). Zero native
+ * dependencies - the state is tiny (the epoch header plus the linked-companion
+ * list). For a database-backed store, implement the two-method
+ * `CompanionHostPersistence` contract directly against your DB; there is no need
+ * for a dedicated core store domain.
+ */
+export function createFileCompanionHostPersistence(filePath) {
+    return {
+        async load() {
+            let raw;
+            try {
+                raw = await readFile(filePath, 'utf8');
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    return null;
+                }
+                throw error;
+            }
+            const parsed = JSON.parse(raw);
+            return {
+                rawId: parsed.rawId,
+                currentKeyIndex: parsed.currentKeyIndex,
+                companions: parsed.companions.map((companion) => ({
+                    deviceJid: companion.deviceJid,
+                    keyIndex: companion.keyIndex,
+                    companionIdentityPublicKey: base64ToBytes(companion.companionIdentityPublicKey),
+                    addedAtSeconds: companion.addedAtSeconds
+                }))
+            };
+        },
+        async save(state) {
+            const serialized = {
+                rawId: state.rawId,
+                currentKeyIndex: state.currentKeyIndex,
+                companions: state.companions.map((companion) => ({
+                    deviceJid: companion.deviceJid,
+                    keyIndex: companion.keyIndex,
+                    companionIdentityPublicKey: bytesToBase64(companion.companionIdentityPublicKey),
+                    addedAtSeconds: companion.addedAtSeconds
+                }))
+            };
+            await mkdir(dirname(filePath), { recursive: true });
+            const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+            await writeFile(tempPath, JSON.stringify(serialized), 'utf8');
+            await rename(tempPath, filePath);
+        }
+    };
+}

package/dist/esm/client/plugins/install.js

@@ -1,10 +1,35 @@
 import { isWaClientExposePluginDefinition } from '../plugins/types.js';
 import { toError } from '../../util/primitives.js';
+const PLUGIN_REGISTRY = Symbol('waClientPluginRegistry');
+/**
+ * Per-client store for exposed-plugin state that must survive a
+ * disconnect/connect cycle. Each `exposeAs` property is defined on the client
+ * exactly once (a non-configurable getter reading `instances`); reinstalls
+ * only repopulate the slot, so plugins can be torn down on disconnect and
+ * rebuilt on the next connect without redefining reserved members.
+ */
+function getPluginRegistry(client) {
+    const holder = client;
+    const existing = holder[PLUGIN_REGISTRY];
+    if (existing) {
+        return existing;
+    }
+    const registry = { instances: new Map(), exposedDefined: new Set() };
+    Object.defineProperty(client, PLUGIN_REGISTRY, {
+        value: registry,
+        enumerable: false,
+        configurable: false,
+        writable: false
+    });
+    return registry;
+}
 /**
  * Installs {@link WaClientOptions.plugins} on `client`. Returns a dispose
- * function invoked by {@link WaClient.disconnect}.
+ * function invoked by {@link WaClient.disconnect}. Safe to call again after a
+ * dispose to reinstall the same plugins on reconnect.
  */
 export function installWaClientPlugins(client, input, plugins) {
+    const registry = getPluginRegistry(client);
     const seenIds = new Set();
     const seenExposeAs = new Set();
     const disposeCallbacks = [];
@@ -37,24 +62,32 @@ export function installWaClientPlugins(client, input, plugins) {
             logger: input.logger.child({ plugin: plugin.id })
         };
         if (isWaClientExposePluginDefinition(plugin)) {
-            if (seenExposeAs.has(plugin.exposeAs)) {
-                throw new Error(`duplicate wa client plugin exposeAs: ${plugin.exposeAs}`);
+            const exposeAs = plugin.exposeAs;
+            if (seenExposeAs.has(exposeAs)) {
+                throw new Error(`duplicate wa client plugin exposeAs: ${exposeAs}`);
             }
-            seenExposeAs.add(plugin.exposeAs);
-            if (plugin.exposeAs in client) {
-                throw new Error(`wa client plugin exposeAs "${plugin.exposeAs}" collides with a reserved client member`);
+            seenExposeAs.add(exposeAs);
+            if (!registry.exposedDefined.has(exposeAs)) {
+                if (exposeAs in client) {
+                    throw new Error(`wa client plugin exposeAs "${exposeAs}" collides with a reserved client member`);
+                }
+                registry.exposedDefined.add(exposeAs);
+                Object.defineProperty(client, exposeAs, {
+                    get: () => registry.instances.get(exposeAs),
+                    enumerable: true,
+                    configurable: false
+                });
             }
             const instance = plugin.setup(pluginCtx);
-            Object.defineProperty(client, plugin.exposeAs, {
-                get: () => instance,
-                enumerable: true,
-                configurable: false
+            registry.instances.set(exposeAs, instance);
+            registerDispose(() => {
+                registry.instances.delete(exposeAs);
             });
             if (plugin.dispose) {
                 const dispose = plugin.dispose;
                 registerDispose(() => dispose(instance, pluginCtx));
             }
-            pluginCtx.logger.debug('wa client plugin installed', { exposeAs: plugin.exposeAs });
+            pluginCtx.logger.debug('wa client plugin installed', { exposeAs });
         }
         else {
             plugin.setup(pluginCtx);

package/dist/esm/index.js

@@ -1,14 +1,17 @@
 export { WaClient } from './client/index.js';
 export { defineWaClientPlugin } from './client/plugins/index.js';
 export { downloadMediaMessage } from './client/media.js';
+export { createFileCompanionHostPersistence } from './client/persistence/companion-host.js';
 export { parseUsyncResultEnvelope } from './transport/node/builders/usync.js';
-export { getContentType, resolveMessageTarget } from './message/encode/content.js';
+export { getContentType, resolveEncMediaType, resolveMessageTarget, unwrapMessage } from './message/encode/content.js';
+export { getContextInfo } from './message/context-info.js';
 export { resolveMediaPayload } from './message/encode/media-payload.js';
 export { unpadPkcs7, writeRandomPadMax16 } from './message/encode/padding.js';
-export { fetchLatestWaWebVersion } from './transport/wa-web-version-fetcher.js';
+export { fetchLatestWaWebVersion, fetchLatestWaMobileVersion } from './transport/wa-version-fetcher.js';
 export { ConsoleLogger } from './infra/log/ConsoleLogger.js';
 export { PinoLogger, createPinoLogger } from './infra/log/PinoLogger.js';
 export { createNoopLogger } from './infra/log/types.js';
+export { WA_VERSION } from './version-spec.js';
 export { createStore, WaAuthMemoryStore } from './store/index.js';
 export { delay } from './util/async.js';
 export { buildDeviceJid, canonicalizeSignalJid, canonicalizeSignalServer, getLoginIdentity, getWaCompanionPlatformId, getWaMediaHkdfInfo, isBotJid, isBroadcastJid, isGroupJid, isGroupOrBroadcastJid, isHostedDeviceId, isHostedDeviceJid, isHostedServer, isLidJid, isNewsletterJid, isStatusBroadcastJid, isUserJid, normalizeDeviceJid, normalizeRecipientJid, parseJidFull, parsePhoneJid, parseSignalAddressFromJid, signalAddressKey, splitJid, toUserJid, WA_ACCOUNT_SYNC_PROTOCOLS, WA_APP_STATE_COLLECTIONS, WA_APP_STATE_COLLECTION_STATES, WA_APP_STATE_ERROR_CODES, WA_APP_STATE_KDF_INFO, WA_APP_STATE_KEY_TYPES, WA_APP_STATE_SYNC_DATA_TYPE, WA_BROWSERS, WA_BUSINESS_HOURS_DAYS, WA_BUSINESS_HOURS_MODES, WA_COMPANION_PLATFORM_IDS, WA_DEFAULTS, WA_DIRTY_PROTOCOLS, WA_DIRTY_TYPES, WA_DISCONNECT_REASONS, WA_IQ_TYPES, WA_LOGOUT_REASONS, WA_MESSAGE_TAGS, WA_MESSAGE_TYPES, WA_MEDIA_HKDF_INFO, WA_NODE_TAGS, WA_PAIRING_KDF_INFO, WA_PREVIEW_MEDIA_HKDF_INFO, WA_READY_STATES, WA_RETRYABLE_ACK_CODES, WA_SIGNALING, WA_STREAM_SIGNALING, WA_SUPPORTED_DIRTY_TYPES, WA_PRIVACY_CATEGORIES, WA_PRIVACY_CATEGORY_TO_SETTING, WA_PRIVACY_DISALLOWED_LIST_CATEGORIES, WA_PRIVACY_SETTING_TO_CATEGORY, WA_PRIVACY_TAGS, WA_PRIVACY_VALUES, WA_XMLNS } from './protocol/index.js';

package/dist/esm/message/WaMessageClient.js

@@ -1,5 +1,5 @@
 import { describeAckNode, isAckOrReceiptNode, isNegativeAckNode, isRetryableNegativeAck } from './primitives/ack.js';
-import { WA_DEFAULTS, WA_MESSAGE_TAGS, WA_MESSAGE_TYPES, WA_NODE_TAGS } from '../protocol/constants.js';
+import { WA_ADDRESSING_MODES, WA_DEFAULTS, WA_MESSAGE_TAGS, WA_MESSAGE_TYPES, WA_NODE_TAGS } from '../protocol/constants.js';
 import { buildReceiptNode } from '../transport/node/builders/global.js';
 import { delay } from '../util/async.js';
 import { parseOptionalInt, toError } from '../util/primitives.js';
@@ -226,7 +226,8 @@ export class WaMessageClient {
     }
     extractAckMetadata(ackNode) {
         const addressingModeRaw = ackNode.attrs.addressing_mode;
-        const addressingMode = addressingModeRaw === 'pn' || addressingModeRaw === 'lid'
+        const addressingMode = addressingModeRaw === WA_ADDRESSING_MODES.PN ||
+            addressingModeRaw === WA_ADDRESSING_MODES.LID
             ? addressingModeRaw
             : undefined;
         return {

package/dist/esm/message/context-info.js

@@ -85,6 +85,10 @@ function pickContextInfoTarget(message) {
     }
     return null;
 }
+/** Reads the `contextInfo` off a message's first content submessage (null when absent). */
+export function getContextInfo(message) {
+    return pickContextInfoTarget(message)?.contextInfo ?? null;
+}
 export function resolveSendContextInfo(input) {
     const ctx = {
         ...(input.contentLevel ?? {}),

package/dist/esm/protocol/constants.js

@@ -1,9 +1,10 @@
-export { getWaCompanionPlatformId, WA_BROWSERS, WA_COMPANION_PLATFORM_IDS } from './browser.js';
+export { getWaBrowserDisplayName, getWaCompanionPlatformId, WA_BROWSERS, WA_COMPANION_PLATFORM_IDS } from './browser.js';
+export { resolveWaDeviceIdentity } from './device-identity.js';
 export { WA_SIGNALING, WA_PAIRING_KDF_INFO } from './auth.js';
 export { WA_CONNECTION_REASONS, WA_DISCONNECT_REASONS, WA_FAILURE_REASONS, WA_LOGOUT_REASONS, WA_READY_STATES, WA_STREAM_SIGNALING } from './stream.js';
 export { WA_IQ_TYPES, WA_NODE_TAGS, WA_XMLNS } from './nodes.js';
 export { WA_CALL_CHILD_TAGS, WA_CALL_NODE_ATTRS, WA_CALL_PAYLOAD_TAGS, WA_CALL_RECEIPT_PAYLOAD_TAGS } from './call.js';
-export { WA_EDIT_ATTRS, WA_ENC_MEDIA_TYPES, WA_EVENT_META_TYPES, WA_MESSAGE_TAGS, WA_MESSAGE_TYPES, WA_NACK_REASONS, WA_POLL_META_TYPES, WA_RETRYABLE_ACK_CODES, WA_STANZA_MSG_TYPES } from './message.js';
+export { WA_ADDRESSING_MODES, WA_EDIT_ATTRS, WA_ENC_CIPHERTEXT_TYPES, WA_ENC_MEDIA_TYPES, WA_EVENT_META_TYPES, WA_MESSAGE_TAGS, WA_MESSAGE_TYPES, WA_NACK_REASONS, WA_POLL_META_TYPES, WA_RETRYABLE_ACK_CODES, WA_STANZA_MSG_TYPES } from './message.js';
 export { WA_APP_STATE_COLLECTIONS, WA_APP_STATE_COLLECTION_STATES, WA_APP_STATE_ERROR_CODES, WA_APP_STATE_KDF_INFO, WA_APP_STATE_KEY_TYPES, WA_APP_STATE_SYNC_DATA_TYPE } from './appstate.js';
 export { getWaMediaHkdfInfo, WA_MEDIA_HKDF_INFO, WA_PREVIEW_MEDIA_HKDF_INFO } from './media.js';
 export { WA_ACCOUNT_SYNC_PROTOCOLS, WA_DIRTY_PROTOCOLS, WA_DIRTY_TYPES, WA_SUPPORTED_DIRTY_TYPES } from './dirty.js';
@@ -17,6 +18,6 @@ export { WA_BIZ_BOT_TYPES, WA_BOT_DEFAULT_CAPABILITIES, WA_BOT_HKDF_INFO, WA_BOT
 export { WA_STATUS_DISTRIBUTION_SETTINGS } from './status.js';
 export { WA_EMAIL_CONTEXTS, WA_EMAIL_ERROR_CODES, WA_EMAIL_LIMITS, WA_EMAIL_TAGS, WA_EMAIL_XMLNS } from './email.js';
 export { AB_PROP_CONFIGS, resolveAbPropNameByCode, WA_ABPROPS_PROTOCOL_VERSION, WA_ABPROPS_REFRESH_BOUNDS } from './abprops.js';
-export { WA_GROUP_PARTICIPANT_TYPES } from './group.js';
+export { WA_GROUP_MEMBERSHIP_ACTION_TAGS, WA_GROUP_PARTICIPANT_TYPES } from './group.js';
 export { WA_USYNC_CONTEXTS, WA_USYNC_DEFAULTS, WA_USYNC_MODES } from './usync.js';
 export { WA_NEWSLETTER_FETCH_KEY_TYPES, WA_NEWSLETTER_MUTE_TYPES, WA_NEWSLETTER_MUTE_VALUES, WA_NEWSLETTER_PICTURE_TYPES, WA_NEWSLETTER_RECEIVE_TYPES, WA_NEWSLETTER_ROLES, WA_NEWSLETTER_SEND_TYPES, WA_NEWSLETTER_STATE_TYPES, WA_NEWSLETTER_VERIFICATION_STATES, WA_NEWSLETTER_VIEW_ROLES } from './newsletter.js';

package/dist/esm/protocol/device-identity.js

@@ -0,0 +1,18 @@
+import { getWaCompanionPlatformId } from './browser.js';
+import { WA_DEFAULTS } from './defaults.js';
+import { getRuntimeOsDisplayName } from '../util/runtime.js';
+/**
+ * Resolves the device identity from raw options, applying the shared defaults:
+ * browser falls back to {@link WA_DEFAULTS}.DEVICE_BROWSER, OS name to the
+ * detected runtime OS, and platform id is inferred from the browser. This is
+ * the single source of truth used by both the client factory and the auth
+ * client so the pairing payload and any analytics/telemetry agree.
+ */
+export function resolveWaDeviceIdentity(options) {
+    const browser = options.deviceBrowser ?? WA_DEFAULTS.DEVICE_BROWSER;
+    return Object.freeze({
+        browser,
+        osDisplayName: options.deviceOsDisplayName ?? getRuntimeOsDisplayName(),
+        platform: options.devicePlatform ?? getWaCompanionPlatformId(browser)
+    });
+}

package/dist/esm/protocol/group.js

@@ -3,3 +3,9 @@ export const WA_GROUP_PARTICIPANT_TYPES = Object.freeze({
     ADMIN: 'admin',
     REGULAR: 'participant'
 });
+/** `<membership_requests_action>` child tags for approving/rejecting group join requests. */
+export const WA_GROUP_MEMBERSHIP_ACTION_TAGS = Object.freeze({
+    REQUESTS_ACTION: 'membership_requests_action',
+    APPROVE: 'approve',
+    REJECT: 'reject'
+});

package/dist/esm/protocol/message.js

@@ -5,6 +5,18 @@ export const WA_MESSAGE_TAGS = Object.freeze({
     ACK: 'ack',
     ERROR: 'error'
 });
+/** `<enc type>` ciphertext kinds (Signal `msg`/`pkmsg`, group `skmsg`, message-secret `msmsg`). */
+export const WA_ENC_CIPHERTEXT_TYPES = Object.freeze({
+    MESSAGE: 'msg',
+    PREKEY: 'pkmsg',
+    SENDER_KEY: 'skmsg',
+    MESSAGE_SECRET: 'msmsg'
+});
+/** `addressing_mode` stanza attr: phone-number vs LID addressing. */
+export const WA_ADDRESSING_MODES = Object.freeze({
+    PN: 'pn',
+    LID: 'lid'
+});
 export const WA_MESSAGE_TYPES = Object.freeze({
     ENC_VERSION: '2',
     MEDIA_NOTIFY: 'medianotify',

package/dist/esm/protocol/nodes.js

@@ -10,6 +10,7 @@ export const WA_NODE_TAGS = Object.freeze({
     NOTIFICATION: 'notification',
     SUCCESS: 'success',
     INFO_BULLETIN: 'ib',
+    OFFLINE: 'offline',
     DIRTY: 'dirty',
     EDGE_ROUTING: 'edge_routing',
     ROUTING_INFO: 'routing_info',
@@ -80,7 +81,20 @@ export const WA_NODE_TAGS = Object.freeze({
     USERNAME: 'username',
     TEXT_STATUS: 'text_status',
     DISAPPEARING_MODE: 'disappearing_mode',
-    BUSINESS: 'business'
+    BUSINESS: 'business',
+    PUB_KEY: 'pub-key',
+    KEY_INDEX_LIST: 'key-index-list',
+    CLIENT_PROPS: 'client-props',
+    PEM: 'pem',
+    TTL: 'ttl',
+    KEY_ID: 'key_id',
+    REMOVE_COMPANION_DEVICE: 'remove-companion-device',
+    PRIMARY_IDENTITY_PUB: 'primary_identity_pub',
+    COMPANION_IDENTITY_PUBLIC: 'companion_identity_public',
+    COMPANION_SERVER_AUTH_KEY_PUB: 'companion_server_auth_key_pub',
+    LINK_CODE_PAIRING_WRAPPED_PRIMARY_EPHEMERAL_PUB: 'link_code_pairing_wrapped_primary_ephemeral_pub',
+    LINK_CODE_PAIRING_WRAPPED_COMPANION_EPHEMERAL_PUB: 'link_code_pairing_wrapped_companion_ephemeral_pub',
+    LINK_CODE_PAIRING_WRAPPED_KEY_BUNDLE: 'link_code_pairing_wrapped_key_bundle'
 });
 export const WA_IQ_TYPES = Object.freeze({
     GET: 'get',

package/dist/esm/retry/replay.js

@@ -2,7 +2,7 @@ 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 { WA_DEFAULTS, WA_NODE_TAGS } from '../protocol/constants.js';
+import { WA_ADDRESSING_MODES, 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';
@@ -197,8 +197,8 @@ export class WaRetryReplayService {
             addressingMode: isStatus
                 ? undefined
                 : requesterAddress.server === WA_DEFAULTS.LID_SERVER
-                    ? 'lid'
-                    : 'pn',
+                    ? WA_ADDRESSING_MODES.LID
+                    : WA_ADDRESSING_MODES.PN,
             encType: encrypted.type,
             ciphertext: encrypted.ciphertext,
             retryCount,

package/dist/esm/signal/attestation/WaAdvSignature.js

@@ -1,17 +1,82 @@
 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 { ADV_PREFIX_ACCOUNT_KEY_INDEX, ADV_PREFIX_ACCOUNT_SIGNATURE, ADV_PREFIX_DEVICE_SIGNATURE, ADV_PREFIX_HOSTED_ACCOUNT_KEY_INDEX, 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 } from '../attestation/constants.js';
+export { ADV_PREFIX_ACCOUNT_KEY_INDEX, ADV_PREFIX_ACCOUNT_SIGNATURE, ADV_PREFIX_DEVICE_SIGNATURE, ADV_PREFIX_HOSTED_ACCOUNT_SIGNATURE } from '../attestation/constants.js';
+/**
+ * Companion-side check that the primary's account key signed a device identity.
+ * Verifies `accountSignature` over `prefix || details || identityPublicKey`
+ * against the account signature public key. Inverse of
+ * {@link generateDeviceIdentityAccountSignature}.
+ */
 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]);
     return xeddsaVerify(toRawPubKey(accountSignatureKey), message, accountSignature);
 }
+/**
+ * Companion-side signature proving possession of the identity private key after
+ * adopting a primary-signed identity. Signs
+ * `prefix || details || identityKeyPair.pubKey || accountSignatureKey`, and is
+ * verified by the primary via {@link verifyDeviceSignature}.
+ */
 export async function generateDeviceSignature(details, identityKeyPair, accountSignatureKey, isHosted = false) {
     const prefix = isHosted ? ADV_PREFIX_HOSTED_DEVICE_SIGNATURE : ADV_PREFIX_DEVICE_SIGNATURE;
     const message = concatBytes([prefix, details, identityKeyPair.pubKey, accountSignatureKey]);
     return xeddsaSign(identityKeyPair.privKey, message);
 }
+/**
+ * HMAC-SHA256 over an `ADVSignedDeviceIdentity` (or hosted-prefixed variant)
+ * keyed by the shared ADV secret, binding the signed identity to the pairing
+ * secret inside `ADVSignedDeviceIdentityHMAC`.
+ */
 export function computeAdvIdentityHmac(secretKey, details) {
     return hmacSha256Sign(secretKey, details);
 }
+/**
+ * Primary-side counterpart to {@link verifyDeviceIdentityAccountSignature}.
+ * Signs a companion's `ADVDeviceIdentity` details with the account (primary)
+ * identity key so a linking companion can prove the primary authorized this
+ * device. The signed message is `prefix || details || companionIdentityPublicKey`.
+ *
+ * `accountIdentityKeyPair` is the primary's own Signal identity key pair; its
+ * public half is what ships as `ADVSignedDeviceIdentity.accountSignatureKey`.
+ * Pass `companionIdentityPublicKey` in the exact byte form the companion will
+ * present at verification (the value carried in its pairing QR / key bundle).
+ */
+export async function generateDeviceIdentityAccountSignature(details, companionIdentityPublicKey, accountIdentityKeyPair, isHosted = false) {
+    const prefix = isHosted ? ADV_PREFIX_HOSTED_ACCOUNT_SIGNATURE : ADV_PREFIX_ACCOUNT_SIGNATURE;
+    const message = concatBytes([prefix, details, companionIdentityPublicKey]);
+    return xeddsaSign(accountIdentityKeyPair.privKey, message);
+}
+/**
+ * Primary-side counterpart to {@link generateDeviceSignature}. Verifies the
+ * device signature a companion returns after adopting a signed identity, which
+ * proves the companion holds the identity private key it registered. The signed
+ * message is `prefix || details || companionIdentityPublicKey || accountSignatureKey`.
+ */
+export async function verifyDeviceSignature(details, deviceSignature, companionIdentityPublicKey, accountSignatureKey, isHosted = false) {
+    const prefix = isHosted ? ADV_PREFIX_HOSTED_DEVICE_SIGNATURE : ADV_PREFIX_DEVICE_SIGNATURE;
+    const message = concatBytes([prefix, details, companionIdentityPublicKey, accountSignatureKey]);
+    return xeddsaVerify(toRawPubKey(companionIdentityPublicKey), message, deviceSignature);
+}
+/**
+ * Signs an `ADVKeyIndexList` details blob with the account (primary) identity
+ * key. A primary republishes this list whenever its companion set changes so
+ * every device can validate the current set of key indexes. The signed message
+ * is `prefix || keyIndexListDetails`.
+ */
+export async function signKeyIndexList(keyIndexListDetails, accountIdentityKeyPair, isHosted = false) {
+    const prefix = isHosted ? ADV_PREFIX_HOSTED_ACCOUNT_KEY_INDEX : ADV_PREFIX_ACCOUNT_KEY_INDEX;
+    const message = concatBytes([prefix, keyIndexListDetails]);
+    return xeddsaSign(accountIdentityKeyPair.privKey, message);
+}
+/**
+ * Verifies an `ADVSignedKeyIndexList` account signature against the primary's
+ * account signature key. Inverse of {@link signKeyIndexList}; used by a device
+ * to validate a key-index list published by the primary.
+ */
+export async function verifyKeyIndexListSignature(keyIndexListDetails, accountSignature, accountSignatureKey, isHosted = false) {
+    const prefix = isHosted ? ADV_PREFIX_HOSTED_ACCOUNT_KEY_INDEX : ADV_PREFIX_ACCOUNT_KEY_INDEX;
+    const message = concatBytes([prefix, keyIndexListDetails]);
+    return xeddsaVerify(toRawPubKey(accountSignatureKey), message, accountSignature);
+}

package/dist/esm/signal/attestation/constants.js

@@ -1,4 +1,6 @@
 export const ADV_PREFIX_ACCOUNT_SIGNATURE = new Uint8Array([6, 0]);
 export const ADV_PREFIX_DEVICE_SIGNATURE = new Uint8Array([6, 1]);
+export const ADV_PREFIX_ACCOUNT_KEY_INDEX = new Uint8Array([6, 2]);
 export const ADV_PREFIX_HOSTED_ACCOUNT_SIGNATURE = new Uint8Array([6, 5]);
 export const ADV_PREFIX_HOSTED_DEVICE_SIGNATURE = new Uint8Array([6, 6]);
+export const ADV_PREFIX_HOSTED_ACCOUNT_KEY_INDEX = new Uint8Array([6, 7]);

package/dist/esm/signal/index.js

@@ -14,3 +14,4 @@ export { SenderKeyManager } from './group/SenderKeyManager.js';
 export { createAndStoreInitialKeys } from './registration/utils.js';
 export { SignalProtocol } from './session/SignalProtocol.js';
 export { createSignalSessionResolver } from './session/resolver.js';
+export { ADV_PREFIX_ACCOUNT_KEY_INDEX, ADV_PREFIX_ACCOUNT_SIGNATURE, ADV_PREFIX_DEVICE_SIGNATURE, ADV_PREFIX_HOSTED_ACCOUNT_SIGNATURE, computeAdvIdentityHmac, generateDeviceIdentityAccountSignature, generateDeviceSignature, signKeyIndexList, verifyDeviceIdentityAccountSignature, verifyDeviceSignature, verifyKeyIndexListSignature } from './attestation/WaAdvSignature.js';

package/dist/esm/transport/index.js

@@ -1,6 +1,6 @@
 export { decodeBinaryNode, decodeBinaryNodeStanza, encodeBinaryNode, encodeBinaryNodeStanza } from './binary/index.js';
 export { isProxyAgent, isProxyDispatcher, isProxyTransport, toProxyAgent, toProxyDispatcher } from './proxy.js';
-export { fetchLatestWaWebVersion } from './wa-web-version-fetcher.js';
+export { fetchLatestWaWebVersion, fetchLatestWaMobileVersion } from './wa-version-fetcher.js';
 export { WaComms } from './WaComms.js';
 export { verifyNoiseCertificateChain } from './noise/WaNoiseCert.js';
 export { WaNoiseHandshake } from './noise/WaNoiseHandshake.js';

package/dist/esm/transport/node/builders/group.js

@@ -1,4 +1,5 @@
 import { WA_DEFAULTS } from '../../../protocol/defaults.js';
+import { WA_GROUP_MEMBERSHIP_ACTION_TAGS } from '../../../protocol/group.js';
 import { WA_IQ_TYPES, WA_XMLNS } from '../../../protocol/nodes.js';
 import { buildIqNode } from '../../node/query.js';
 export function buildCreateGroupIq(input) {
@@ -76,20 +77,20 @@ export function buildMembershipRequestsActionIq(input) {
     const children = [];
     if (approve.length > 0) {
         children.push({
-            tag: 'approve',
+            tag: WA_GROUP_MEMBERSHIP_ACTION_TAGS.APPROVE,
             attrs: {},
             content: approve.map((jid) => ({ tag: 'participant', attrs: { jid } }))
         });
     }
     if (reject.length > 0) {
         children.push({
-            tag: 'reject',
+            tag: WA_GROUP_MEMBERSHIP_ACTION_TAGS.REJECT,
             attrs: {},
             content: reject.map((jid) => ({ tag: 'participant', attrs: { jid } }))
         });
     }
     return buildIqNode(WA_IQ_TYPES.SET, input.groupJid, WA_XMLNS.GROUPS, [
-        { tag: 'membership_requests_action', attrs: {}, content: children }
+        { tag: WA_GROUP_MEMBERSHIP_ACTION_TAGS.REQUESTS_ACTION, attrs: {}, content: children }
     ]);
 }
 export function buildCancelMembershipRequestsIq(input) {