zapo-js 1.4.0 → 1.5.0

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

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeHistorySync = encodeHistorySync;
+exports.buildInlineHistorySyncNotification = buildInlineHistorySyncNotification;
+exports.buildHistorySyncBootstrapMessage = buildHistorySyncBootstrapMessage;
+const node_util_1 = require("node:util");
+const node_zlib_1 = require("node:zlib");
+const _proto_1 = require("../../proto");
+const deflateAsync = (0, node_util_1.promisify)(node_zlib_1.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.
+ */
+async function encodeHistorySync(content) {
+    const serialized = _proto_1.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.
+ */
+function buildInlineHistorySyncNotification(syncType, deflatedPayload, options = {}) {
+    return {
+        type: _proto_1.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.
+ */
+async function buildHistorySyncBootstrapMessage(input = {}) {
+    const historySync = {
+        syncType: _proto_1.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_1.proto.Message.HistorySyncType.INITIAL_BOOTSTRAP, payload);
+    return { message, payloadBytes: payload.byteLength };
+}

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

@@ -4,6 +4,15 @@ exports.createAppStateSyncKeyProtocol = createAppStateSyncKeyProtocol;
 const _proto_1 = require("../../proto");
 const jid_1 = require("../../protocol/jid");
 const bytes_1 = require("../../util/bytes");
+/**
+ * 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;
 function createAppStateSyncKeyProtocol(options) {
     const { publishProtocolMessageToDevice, fanoutResolver, getCurrentCredentials, logger } = options;
     const requireCurrentIdentity = (context) => {
@@ -67,7 +76,12 @@ 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((0, bytes_1.bytesToHex)(key.keyId));
+                continue;
+            }
             const keyHex = (0, bytes_1.bytesToHex)(key.keyId);
             if (seenKeyIds.has(keyHex)) {
                 continue;
@@ -84,7 +98,10 @@ 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((0, bytes_1.bytesToHex)(keyId));
+                }
                 continue;
             }
             const keyHex = (0, bytes_1.bytesToHex)(keyId);
@@ -96,6 +113,13 @@ 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_1.proto.Message.ProtocolMessage.Type.APP_STATE_SYNC_KEY_SHARE,
             appStateSyncKeyShare: {

package/dist/client/persistence/companion-host.d.ts

@@ -0,0 +1,36 @@
+/** A companion device this primary has linked. */
+export interface CompanionRecord {
+    readonly deviceJid: string;
+    readonly keyIndex: number;
+    readonly companionIdentityPublicKey: Uint8Array;
+    readonly addedAtSeconds: number;
+}
+/**
+ * The primary's ADV epoch state. `rawId` is the account's stable ADV identity
+ * id; `currentKeyIndex` is the last-issued companion key index (companions get
+ * `currentKeyIndex + 1`). This MUST persist across restarts, otherwise reissuing
+ * an already-used key index breaks previously linked devices.
+ */
+export interface CompanionHostEpochState {
+    readonly rawId: number;
+    readonly currentKeyIndex: number;
+    readonly companions: readonly CompanionRecord[];
+}
+/**
+ * Persistence hook for {@link CompanionHostEpochState}. Supply one via plugin
+ * options to survive restarts; without it the epoch is in-memory only (fine for
+ * a single-session smoke test, unsafe for production relinking).
+ */
+export interface CompanionHostPersistence {
+    readonly load: () => Promise<CompanionHostEpochState | null> | CompanionHostEpochState | null;
+    readonly save: (state: CompanionHostEpochState) => Promise<void> | void;
+}
+/**
+ * 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 declare function createFileCompanionHostPersistence(filePath: string): CompanionHostPersistence;

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

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFileCompanionHostPersistence = createFileCompanionHostPersistence;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const bytes_1 = require("../../util/bytes");
+/**
+ * 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.
+ */
+function createFileCompanionHostPersistence(filePath) {
+    return {
+        async load() {
+            let raw;
+            try {
+                raw = await (0, promises_1.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: (0, bytes_1.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: (0, bytes_1.bytesToBase64)(companion.companionIdentityPublicKey),
+                    addedAtSeconds: companion.addedAtSeconds
+                }))
+            };
+            await (0, promises_1.mkdir)((0, node_path_1.dirname)(filePath), { recursive: true });
+            const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+            await (0, promises_1.writeFile)(tempPath, JSON.stringify(serialized), 'utf8');
+            await (0, promises_1.rename)(tempPath, filePath);
+        }
+    };
+}

package/dist/client/plugins/install.d.ts

@@ -13,6 +13,7 @@ export interface WaClientPluginInstallInput {
 }
 /**
  * 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 declare function installWaClientPlugins(client: WaClient, input: WaClientPluginInstallInput, plugins: readonly WaClientPluginDefinition[]): () => Promise<void>;

package/dist/client/plugins/install.js

@@ -3,11 +3,36 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.installWaClientPlugins = installWaClientPlugins;
 const types_1 = require("../plugins/types");
 const primitives_1 = require("../../util/primitives");
+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.
  */
 function installWaClientPlugins(client, input, plugins) {
+    const registry = getPluginRegistry(client);
     const seenIds = new Set();
     const seenExposeAs = new Set();
     const disposeCallbacks = [];
@@ -40,24 +65,32 @@ function installWaClientPlugins(client, input, plugins) {
             logger: input.logger.child({ plugin: plugin.id })
         };
         if ((0, types_1.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/client/types.d.ts

@@ -4,6 +4,7 @@ import type { WaShortcakeAssertionSigner } from '../auth/pairing/WaShortcakeFlow
 import type { WaAuthClientOptions, WaAuthCredentials, WaAuthDangerousOptions, WaAuthSocketOptions } from '../auth/types';
 import type { WaCallGroupParticipant, WaCallType } from './events/call';
 import type { IncomingPresenceType, PresenceLastSeen } from './events/presence';
+import type { CompanionHostPersistence } from './persistence/companion-host';
 import type { WaClientPluginDefinition } from './plugins/types';
 import type { WaMediaProcessor } from '../media/processor';
 import type { WaLinkPreviewOptions } from '../message/addons/link-preview/types';
@@ -83,6 +84,16 @@ export interface WaClientOptions extends WaAuthClientOptions, WaAuthSocketOption
      * tests or pinning a specific edge.
      */
     readonly chatSocketUrls?: readonly string[];
+    /**
+     * Companion-hosting config for a mobile-primary session (see
+     * {@link WaClient.mobile}). `persistence` survives the ADV epoch across
+     * restarts (without it, relinking breaks previously linked devices);
+     * `includePem` adds the experimental `<pem>` node to the pair-device upload.
+     */
+    readonly companionHost?: {
+        readonly persistence?: CompanionHostPersistence;
+        readonly includePem?: boolean;
+    };
     /** Default timeout (ms) for IQ queries. Defaults to `WA_DEFAULTS.IQ_TIMEOUT_MS` (60s). */
     readonly iqTimeoutMs?: number;
     /** Default timeout (ms) for raw node `query()` calls when none is passed. */
@@ -119,8 +130,11 @@ export interface WaClientOptions extends WaAuthClientOptions, WaAuthSocketOption
      * Automatically reconnect when the server rejects the noise handshake
      * with HTTP 405 / `failure_client_too_old`. On every 405 the client
      * logs a warning asking you to upgrade zapo, fetches the current
-     * version from `web.whatsapp.com` via `fetchLatestWaWebVersion()`,
-     * swaps it in for the next connect, and retries. Off by default.
+     * version, swaps it in for the next connect, and retries. Off by
+     * default. Web sessions fetch the WA Web version via
+     * `fetchLatestWaWebVersion()` (swapped in as the connect `version`);
+     * mobile sessions fetch the Android app version via
+     * `fetchLatestWaMobileVersion()` (swapped in as `deviceInfo.appVersion`).
      */
     readonly recoverFromClientTooOld?: boolean;
     /**
@@ -141,6 +155,7 @@ export interface WaClientOptions extends WaAuthClientOptions, WaAuthSocketOption
      * Chat-event emission tuning. `emitSnapshotMutations: true` re-emits
      * `app_state_mutation` events for every mutation seen during a snapshot
      * sync (off by default – those mutations represent historical state).
+     * This client's own outbound app-state actions surface on `mutation_send`.
      */
     readonly chatEvents?: {
         readonly emitSnapshotMutations?: boolean;
@@ -540,6 +555,22 @@ export interface WaIncomingMessageEvent extends Omit<WaIncomingBaseEvent, 'chatJ
     readonly pushName?: string;
     readonly message?: Proto.IMessage;
 }
+/**
+ * An outbound message this client sent, surfaced with its decrypted
+ * {@link Proto.IMessage} – the symmetric counterpart to
+ * {@link WaIncomingMessageEvent}. Fires from {@link WaMessageCoordinator.send}
+ * as the stanza is built, so plugins/loggers can observe outgoing content
+ * (forwards, reactions, polls, media) that the encrypted `<message>` on the
+ * wire does not reveal.
+ */
+export interface WaOutgoingMessageEvent {
+    /** Destination jid (chat / group / status). */
+    readonly to: string;
+    /** Outgoing stanza id, when assigned. */
+    readonly id?: string;
+    /** The decrypted message proto being sent. */
+    readonly message: Proto.IMessage;
+}
 export interface WaIncomingProtocolMessageEvent extends WaIncomingMessageEvent {
     readonly protocolMessage: Proto.Message.IProtocolMessage;
 }
@@ -1001,7 +1032,7 @@ export interface WaHistorySyncChunkEvent {
     /** Server-reported progress, 0–100. */
     readonly progress?: number;
 }
-export type WaAppStateMutationSource = 'snapshot' | 'patch';
+export type WaAppStateMutationSource = 'snapshot' | 'patch' | 'local';
 type MutationEventBase = {
     readonly source: WaAppStateMutationSource;
     readonly collection: AppStateCollectionName;
@@ -1022,6 +1053,12 @@ export type WaAppStateMutationEvent = {
         readonly operation: 'remove';
     } & MutationEventBase & WaAppstateIndexArgs<K>);
 }[WaAppstateActionKey];
+/**
+ * Listener shared by the inbound `mutation` and outbound `mutation_send`
+ * events. A single named alias so the (large) `WaAppStateMutationEvent` union
+ * is referenced once by the event map rather than expanded per event.
+ */
+type WaAppStateMutationListener = (event: WaAppStateMutationEvent) => void;
 export type WaConnectionEvent = {
     readonly status: 'open';
     readonly reason: WaConnectionOpenReason;
@@ -1103,6 +1140,13 @@ export interface WaClientEventMap {
      * `options.quote` for threads).
      */
     readonly message: (event: WaIncomingMessageEvent) => void;
+    /**
+     * An outbound message this client is sending, with its decrypted
+     * {@link Proto.IMessage} – the symmetric counterpart to `message`. Lets
+     * plugins/loggers observe outgoing content (forwards, reactions, polls,
+     * media) the encrypted wire stanza hides.
+     */
+    readonly message_send: (event: WaOutgoingMessageEvent) => void;
     /**
      * A decrypted addon (poll vote, reaction, edit, comment, ...) attached to
      * a previous message. Fires unless `addons.autoDecrypt` is explicitly
@@ -1162,11 +1206,20 @@ export interface WaClientEventMap {
     /** Profile/group/community picture change notification – the new picture must still be fetched explicitly. */
     readonly picture: (event: WaPictureEvent) => void;
     /**
-     * A parsed app-state mutation crossed the sync boundary – chat mute/star/
-     * read/pin/archive/contact/label/etc. Use the discriminator
-     * (`event.action`) to branch on the mutation kind.
+     * A parsed app-state mutation arriving from a sync – chat mute/star/read/
+     * pin/archive/contact/label/etc. changed on another device. Inbound only;
+     * this client's own outbound actions surface on `mutation_send`. Use the
+     * discriminator (`event.schema`) to branch on the mutation kind.
      */
-    readonly mutation: (event: WaAppStateMutationEvent) => void;
+    readonly mutation: WaAppStateMutationListener;
+    /**
+     * An app-state action this client is sending (mute/star/read/pin/archive/
+     * clear/delete/…) surfaced at action time – the outbound counterpart to
+     * `mutation`, symmetric to how `message_send` pairs with `message`.
+     * `event.source` is always `'local'`. Optimistic: emitted as the mutation
+     * is enqueued, before the server flush confirms it.
+     */
+    readonly mutation_send: WaAppStateMutationListener;
     /**
      * One chunk of history-sync data, fired both during the initial
      * bootstrap that the primary device pushes after pairing and for any
@@ -1204,6 +1257,17 @@ export interface WaClientEventMap {
      * `mobileTransport`.
      */
     readonly mobile_account_takeover_notice: (event: WaAccountTakeoverNoticeEvent) => void;
+    /** A companion device was linked from this mobile-primary account. */
+    readonly companion_host_linked: (result: {
+        readonly deviceJid: string;
+        readonly keyIndex: number;
+    }) => void;
+    /** A hosted companion device was revoked / unlinked. */
+    readonly companion_host_revoked: (payload: {
+        readonly deviceJid: string;
+    }) => void;
+    /** A companion-host link or provisioning operation failed. */
+    readonly companion_host_error: (error: Error) => void;
     /** **debug** – the success node closing the noise handshake; emitted before `connection: { status: 'open' }`. */
     readonly debug_connection_success: (event: {
         readonly node: BinaryNode;

package/dist/esm/auth/WaAuthClient.js

@@ -2,12 +2,11 @@ import { buildCommsConfig, loadOrCreateCredentials, persistCredentials } from '.
 import { WaPairingFlow } from './pairing/WaPairingFlow.js';
 import { WaQrFlow } from './pairing/WaQrFlow.js';
 import { WaShortcakeFlow } from './pairing/WaShortcakeFlow.js';
-import { getWaCompanionPlatformId, WA_DEFAULTS, WA_NOTIFICATION_TYPES } from '../protocol/constants.js';
+import { resolveWaDeviceIdentity, WA_NOTIFICATION_TYPES } from '../protocol/constants.js';
 import { buildAckNode } from '../transport/node/builders/global.js';
 import { resolveDevicePropsPlatformType } from '../transport/noise/WaClientPayload.js';
 import { uint8Equal } from '../util/bytes.js';
 import { toError } from '../util/primitives.js';
-import { getRuntimeOsDisplayName } from '../util/runtime.js';
 /**
  * Owns the auth/pairing lifecycle and persistence of {@link WaAuthCredentials}.
  * Exposed as `client.auth` on a {@link WaClient}.
@@ -20,12 +19,8 @@ import { getRuntimeOsDisplayName } from '../util/runtime.js';
 export class WaAuthClient {
     constructor(options, deps) {
         this.versionOverride = null;
-        const deviceBrowser = options.deviceBrowser ?? WA_DEFAULTS.DEVICE_BROWSER;
-        const device = Object.freeze({
-            browser: deviceBrowser,
-            osDisplayName: options.deviceOsDisplayName ?? getRuntimeOsDisplayName(),
-            platform: options.devicePlatform ?? getWaCompanionPlatformId(deviceBrowser)
-        });
+        this.mobileAppVersionOverride = null;
+        const device = resolveWaDeviceIdentity(options);
         this.options = Object.freeze({
             ...options,
             deviceBrowser: device.browser,
@@ -76,7 +71,7 @@ export class WaAuthClient {
                     getCredentials: () => this.credentials,
                     updateCredentials: this.updateCredentials.bind(this)
                 },
-                deviceType: resolveDevicePropsPlatformType(deviceBrowser)
+                deviceType: resolveDevicePropsPlatformType(device.browser)
             })
             : null;
     }
@@ -124,12 +119,15 @@ export class WaAuthClient {
         this.logger.trace('auth client building comms config');
         const override = this.versionOverride;
         this.versionOverride = null;
+        const mobileAppVersionOverride = this.mobileAppVersionOverride;
+        this.mobileAppVersionOverride = null;
         return buildCommsConfig(this.logger, this.requireCredentials(), socketOptions, {
             deviceBrowser: this.options.deviceBrowser,
             deviceOsDisplayName: this.options.deviceOsDisplayName,
             requireFullSync: this.options.requireFullSync,
             version: override ?? this.options.version,
             mobileTransport: this.options.mobileTransport,
+            mobileAppVersionOverride: mobileAppVersionOverride ?? undefined,
             noiseTrustedRootCa: overrides.noiseTrustedRootCa,
             disableNoiseCertificateChainVerification: overrides.disableNoiseCertificateChainVerification ??
                 this.options.dangerous?.disableNoiseCertificateChainVerification
@@ -145,6 +143,17 @@ export class WaAuthClient {
     setNextConnectVersion(version) {
         this.versionOverride = version;
     }
+    /**
+     * One-shot override for the mobile `deviceInfo.appVersion` on the next
+     * {@link buildCommsConfig} call, then clears. The mobile transport reads
+     * its version from `deviceInfo.appVersion` (the login payload), not the
+     * `version` string, so {@link setNextConnectVersion} has no effect on a
+     * mobile session. Used by the `recoverFromClientTooOld` auto-retry to
+     * inject a fresh Android app version without mutating the user's options.
+     */
+    setNextConnectMobileAppVersion(appVersion) {
+        this.mobileAppVersionOverride = appVersion;
+    }
     /** Clears the in-memory QR and pairing sessions without touching storage. */
     // eslint-disable-next-line @typescript-eslint/require-await
     async clearTransientState() {

package/dist/esm/auth/credentials-flow.js

@@ -6,7 +6,7 @@ import { createAndStoreInitialKeys } from '../signal/index.js';
 import { WaMobileTcpSocketCtor } from '../transport/node/WaMobileTcpSocket.js';
 import { buildMobileLoginPayload } from '../transport/noise/WaMobileClientPayload.js';
 import { toProxyAgent, toProxyDispatcher } from '../transport/proxy.js';
-import { toError } from '../util/primitives.js';
+import { parseOptionalInt, toError } from '../util/primitives.js';
 export async function loadOrCreateCredentials(args) {
     args.logger.trace('auth credentials loadOrCreate start');
     const existing = await args.authStore.load();
@@ -61,6 +61,26 @@ async function resolveVersion(version) {
     }
     return resolved;
 }
+/**
+ * Validates the user-supplied `version` string against the transport it will
+ * feed. A mobile session sends the version as the four-part Android app
+ * version (`2.YY.WW.RR`) in the login payload, so it must have exactly four
+ * numeric parts. A web session advertises up to five parts (`2.3000.x[.y.z]`),
+ * so three to five numeric parts are accepted.
+ */
+function assertValidVersion(version, mobile) {
+    const parts = version.split('.');
+    const allNumeric = parts.every((part) => parseOptionalInt(part) !== undefined);
+    if (mobile) {
+        if (parts.length !== 4 || !allNumeric) {
+            throw new Error(`mobile session requires a 4-part numeric version (e.g. 2.26.27.70), got: ${version}`);
+        }
+        return;
+    }
+    if (parts.length < 3 || parts.length > 5 || !allNumeric) {
+        throw new Error(`web session requires a 3- to 5-part numeric version (e.g. 2.3000.1040229458), got: ${version}`);
+    }
+}
 export async function buildCommsConfig(logger, credentials, socketOptions, clientOptions) {
     const meJid = credentials.meJid;
     const registered = meJid !== null && meJid !== undefined;
@@ -81,6 +101,12 @@ export async function buildCommsConfig(logger, credentials, socketOptions, clien
                 ? 'credentials'
                 : 'none'
     });
+    const resolvedVersion = effectiveMobileTransport && clientOptions.mobileAppVersionOverride !== undefined
+        ? undefined
+        : await resolveVersion(clientOptions.version);
+    if (resolvedVersion !== undefined) {
+        assertValidVersion(resolvedVersion, Boolean(effectiveMobileTransport));
+    }
     if (effectiveMobileTransport) {
         if (wsProxy) {
             throw new Error('mobileTransport does not support socketOptions.proxy.ws – remove the proxy option or open an issue to add TCP proxy support');
@@ -88,11 +114,18 @@ export async function buildCommsConfig(logger, credentials, socketOptions, clien
         if (!loginIdentity) {
             throw new Error('mobileTransport requires registered credentials (meJid) – run the mobile bridge flow first');
         }
+        if (clientOptions.mobileAppVersionOverride !== undefined) {
+            assertValidVersion(clientOptions.mobileAppVersionOverride, true);
+        }
+        const appVersionOverride = clientOptions.mobileAppVersionOverride ?? resolvedVersion;
+        const deviceInfo = appVersionOverride
+            ? { ...effectiveMobileTransport.deviceInfo, appVersion: appVersionOverride }
+            : effectiveMobileTransport.deviceInfo;
         const loginPayload = buildMobileLoginPayload({
             username: loginIdentity.username,
             device: loginIdentity.device,
             passive: effectiveMobileTransport.passive ?? false,
-            deviceInfo: effectiveMobileTransport.deviceInfo,
+            deviceInfo,
             pushName: effectiveMobileTransport.pushName,
             yearClass: effectiveMobileTransport.yearClass,
             memClass: effectiveMobileTransport.memClass
@@ -117,7 +150,7 @@ export async function buildCommsConfig(logger, credentials, socketOptions, clien
             }
         };
     }
-    const versionBase = await resolveVersion(clientOptions.version);
+    const versionBase = resolvedVersion;
     return {
         url: socketOptions.url,
         urls: socketOptions.urls,