zapo-js 1.4.0 → 1.5.0

package/dist/appstate/types.d.ts

@@ -28,14 +28,13 @@ export type WaAppStateMutationInput = {
     readonly collection: AppStateCollectionName;
     readonly operation: 'remove';
     readonly index: string;
-    readonly previousValue: Proto.ISyncActionValue;
     readonly version: number;
     readonly timestamp: number;
 };
 export interface WaAppStateMutation {
     readonly collection: AppStateCollectionName;
     readonly operation: 'set' | 'remove';
-    readonly source: 'snapshot' | 'patch';
+    readonly source: 'snapshot' | 'patch' | 'local';
     readonly index: string;
     readonly value: Proto.ISyncActionValue | null;
     readonly version: number;

package/dist/auth/WaAuthClient.d.ts

@@ -51,6 +51,7 @@ export declare class WaAuthClient {
     private readonly shortcakeFlow;
     private credentials;
     private versionOverride;
+    private mobileAppVersionOverride;
     constructor(options: WaAuthClientOptions, deps: WaAuthClientDeps);
     /**
      * Returns a snapshot of auth readiness flags (connection, registration,
@@ -85,6 +86,15 @@ export declare class WaAuthClient {
      * options.
      */
     setNextConnectVersion(version: string): void;
+    /**
+     * 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: string): void;
     /** Clears the in-memory QR and pairing sessions without touching storage. */
     clearTransientState(): Promise<void>;
     /**

package/dist/auth/WaAuthClient.js

@@ -10,7 +10,6 @@ const global_1 = require("../transport/node/builders/global");
 const WaClientPayload_1 = require("../transport/noise/WaClientPayload");
 const bytes_1 = require("../util/bytes");
 const primitives_1 = require("../util/primitives");
-const runtime_1 = require("../util/runtime");
 /**
  * Owns the auth/pairing lifecycle and persistence of {@link WaAuthCredentials}.
  * Exposed as `client.auth` on a {@link WaClient}.
@@ -23,12 +22,8 @@ const runtime_1 = require("../util/runtime");
 class WaAuthClient {
     constructor(options, deps) {
         this.versionOverride = null;
-        const deviceBrowser = options.deviceBrowser ?? constants_1.WA_DEFAULTS.DEVICE_BROWSER;
-        const device = Object.freeze({
-            browser: deviceBrowser,
-            osDisplayName: options.deviceOsDisplayName ?? (0, runtime_1.getRuntimeOsDisplayName)(),
-            platform: options.devicePlatform ?? (0, constants_1.getWaCompanionPlatformId)(deviceBrowser)
-        });
+        this.mobileAppVersionOverride = null;
+        const device = (0, constants_1.resolveWaDeviceIdentity)(options);
         this.options = Object.freeze({
             ...options,
             deviceBrowser: device.browser,
@@ -79,7 +74,7 @@ class WaAuthClient {
                     getCredentials: () => this.credentials,
                     updateCredentials: this.updateCredentials.bind(this)
                 },
-                deviceType: (0, WaClientPayload_1.resolveDevicePropsPlatformType)(deviceBrowser)
+                deviceType: (0, WaClientPayload_1.resolveDevicePropsPlatformType)(device.browser)
             })
             : null;
     }
@@ -127,12 +122,15 @@ 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 (0, credentials_flow_1.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
@@ -148,6 +146,17 @@ 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/auth/credentials-flow.d.ts

@@ -17,5 +17,13 @@ export declare function persistCredentials(args: WaAuthCredentialsFlowArgs, cred
 export declare function buildCommsConfig(logger: Logger, credentials: WaAuthCredentials, socketOptions: WaAuthSocketOptions, clientOptions: Pick<WaAuthClientOptions, 'deviceBrowser' | 'deviceOsDisplayName' | 'requireFullSync' | 'version' | 'mobileTransport'> & {
     readonly noiseTrustedRootCa?: WaNoiseRootCa;
     readonly disableNoiseCertificateChainVerification?: boolean;
+    /**
+     * One-shot override for the mobile `deviceInfo.appVersion` on this
+     * connect, applied on top of the resolved mobile transport. Used by
+     * the `recoverFromClientTooOld` auto-retry to inject a fresh Android
+     * app version fetched from the public listing. Ignored for web
+     * sessions.
+     */
+    readonly mobileAppVersionOverride?: string;
 }): Promise<WaCommsConfig>;
 export {};

package/dist/auth/credentials-flow.js

@@ -66,6 +66,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) => (0, primitives_1.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}`);
+    }
+}
 async function buildCommsConfig(logger, credentials, socketOptions, clientOptions) {
     const meJid = credentials.meJid;
     const registered = meJid !== null && meJid !== undefined;
@@ -86,6 +106,12 @@ async function buildCommsConfig(logger, credentials, socketOptions, clientOption
                 ? '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');
@@ -93,11 +119,18 @@ async function buildCommsConfig(logger, credentials, socketOptions, clientOption
         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 = (0, WaMobileClientPayload_1.buildMobileLoginPayload)({
             username: loginIdentity.username,
             device: loginIdentity.device,
             passive: effectiveMobileTransport.passive ?? false,
-            deviceInfo: effectiveMobileTransport.deviceInfo,
+            deviceInfo,
             pushName: effectiveMobileTransport.pushName,
             yearClass: effectiveMobileTransport.yearClass,
             memClass: effectiveMobileTransport.memClass
@@ -122,7 +155,7 @@ async function buildCommsConfig(logger, credentials, socketOptions, clientOption
             }
         };
     }
-    const versionBase = await resolveVersion(clientOptions.version);
+    const versionBase = resolvedVersion;
     return {
         url: socketOptions.url,
         urls: socketOptions.urls,

package/dist/auth/pairing/companion-host.d.ts

@@ -0,0 +1,105 @@
+import { type SignalKeyPair } from '../../crypto';
+/**
+ * `@sensitive` `advSecretKey` is companion secret material; consumers must not
+ * persist it without encryption at rest.
+ *
+ * Fields decoded from a companion pairing QR string. The companion (the device
+ * being linked) generates these; the primary consumes them to sign the device
+ * identity. `advSecretKey` is the companion's secret, not the primary's.
+ */
+export interface ParsedCompanionQr {
+    readonly ref: string;
+    readonly noisePublicKey: Uint8Array;
+    readonly identityPublicKey: Uint8Array;
+    readonly advSecretKey: Uint8Array;
+    readonly platform: string;
+}
+/**
+ * Parses a companion pairing QR of the form
+ * `ref,noisePubB64,identityPubB64,advSecretB64,platform`. The `ref` may itself
+ * contain commas, so the four trailing fields are taken from the end.
+ *
+ * @throws when fewer than 5 comma-separated fields are present.
+ */
+export declare function parseCompanionQr(qr: string): ParsedCompanionQr;
+/** `@sensitive` Carries the primary's `accountIdentityKeyPair` private key. */
+export interface BuildSignedKeyIndexListInput {
+    readonly accountIdentityKeyPair: SignalKeyPair;
+    readonly rawId: number;
+    readonly currentIndex: number;
+    readonly timestampSeconds: number;
+    readonly validIndexes: readonly number[];
+}
+/**
+ * Builds the account-signed `ADVSignedKeyIndexList` bytes for the current device
+ * set. The zero-valued `accountType` enum is omitted to match the phone's byte
+ * layout.
+ */
+export declare function buildSignedKeyIndexList(input: BuildSignedKeyIndexListInput): Promise<Uint8Array>;
+/**
+ * `@sensitive` Carries the primary's `accountIdentityKeyPair` private key and the
+ * companion's `advSecretKey`; do not persist unencrypted.
+ */
+export interface BuildSignedCompanionIdentityInput {
+    readonly accountIdentityKeyPair: SignalKeyPair;
+    readonly companionIdentityPublicKey: Uint8Array;
+    readonly advSecretKey: Uint8Array;
+    readonly rawId: number;
+    readonly keyIndex: number;
+    readonly timestampSeconds: number;
+    readonly validIndexes: readonly number[];
+}
+export interface SignedCompanionIdentity {
+    /** `ADVSignedDeviceIdentityHMAC` bytes for the `<device-identity>` node. */
+    readonly deviceIdentityBytes: Uint8Array;
+    /** `ADVSignedKeyIndexList` bytes for the `<key-index-list>` node. */
+    readonly keyIndexListBytes: Uint8Array;
+}
+/**
+ * Builds the signed device identity and key-index list for a linking companion.
+ * The byte layout mirrors WhatsApp's phone (and the in-repo fake-server
+ * reference): the zero-valued `accountType`/`deviceType` enum fields are omitted
+ * so the signed `details` match what the companion verifies.
+ */
+export declare function buildSignedCompanionIdentity(input: BuildSignedCompanionIdentityInput): Promise<SignedCompanionIdentity>;
+/**
+ * Derives the `<pem>` AES-GCM key the phone ships in the pair-device upload:
+ * `HKDF-SHA256(ikm = advSecret, salt = companionNoisePublicKey, info)`. Not yet
+ * verified against a live server from this implementation; see
+ * `CompanionHostOptions.includePem`.
+ */
+export declare function derivePemKey(advSecretKey: Uint8Array, companionNoisePublicKey: Uint8Array): Uint8Array;
+/**
+ * `@sensitive` Holds the `primaryEphemeralKeyPair` private key and the derived
+ * `sharedEphemeral`; keep in memory only, never persist unencrypted.
+ */
+export interface LinkCodePrimaryHello {
+    readonly primaryEphemeralKeyPair: SignalKeyPair;
+    /** `salt(32) || counter(16) || AES-CTR(primaryEphemeralPub)` for `primary_hello`. */
+    readonly wrappedPrimaryEphemeralPub: Uint8Array;
+    /** ECDH(primaryEphemeralPriv, companionEphemeralPub); stashed for the finish step. */
+    readonly sharedEphemeral: Uint8Array;
+}
+/**
+ * Link-code handshake, primary step 1: unwrap the companion ephemeral with the
+ * pairing code, generate the primary ephemeral, compute the shared ECDH secret,
+ * and wrap the primary ephemeral for the `primary_hello` stanza. Mirror of the
+ * companion's `createCompanionHello` + primary-ephemeral unwrap.
+ */
+export declare function preparePrimaryHello(args: {
+    readonly pairingCode: string;
+    readonly wrappedCompanionEphemeralPub: Uint8Array;
+}): Promise<LinkCodePrimaryHello>;
+/**
+ * Link-code handshake, primary step 2: decrypt the `companion_finish` key bundle
+ * and derive the shared `advSecret` (byte-identical to what the companion
+ * derives). Validates that the bundle binds both identities.
+ *
+ * @throws when the bundle's embedded identities do not match.
+ */
+export declare function completePrimaryHandshake(args: {
+    readonly sharedEphemeral: Uint8Array;
+    readonly wrappedKeyBundle: Uint8Array;
+    readonly companionIdentityPub: Uint8Array;
+    readonly primaryIdentityKeyPair: SignalKeyPair;
+}): Promise<Uint8Array>;

package/dist/auth/pairing/companion-host.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCompanionQr = parseCompanionQr;
+exports.buildSignedKeyIndexList = buildSignedKeyIndexList;
+exports.buildSignedCompanionIdentity = buildSignedCompanionIdentity;
+exports.derivePemKey = derivePemKey;
+exports.preparePrimaryHello = preparePrimaryHello;
+exports.completePrimaryHandshake = completePrimaryHandshake;
+const _crypto_1 = require("../../crypto");
+const _proto_1 = require("../../proto");
+const _protocol_1 = require("../../protocol");
+const _signal_1 = require("../../signal");
+const bytes_1 = require("../../util/bytes");
+const PEM_HKDF_INFO = bytes_1.TEXT_ENCODER.encode('Canonical Ent Companion Nonce Encrypt');
+const PBKDF2_ITERATIONS = 131072;
+const PAIRING_AES_KEY_BYTES = 32;
+/**
+ * Parses a companion pairing QR of the form
+ * `ref,noisePubB64,identityPubB64,advSecretB64,platform`. The `ref` may itself
+ * contain commas, so the four trailing fields are taken from the end.
+ *
+ * @throws when fewer than 5 comma-separated fields are present.
+ */
+function parseCompanionQr(qr) {
+    const parts = qr.split(',');
+    if (parts.length < 5) {
+        throw new Error(`companion qr must have at least 5 comma-separated parts, got ${parts.length}`);
+    }
+    const platform = parts[parts.length - 1];
+    const advSecretB64 = parts[parts.length - 2];
+    const identityPubB64 = parts[parts.length - 3];
+    const noisePubB64 = parts[parts.length - 4];
+    const ref = parts.slice(0, parts.length - 4).join(',');
+    return {
+        ref,
+        noisePublicKey: (0, bytes_1.decodeBase64Url)(noisePubB64, 'companionQr.noisePublicKey'),
+        identityPublicKey: (0, bytes_1.decodeBase64Url)(identityPubB64, 'companionQr.identityPublicKey'),
+        advSecretKey: (0, bytes_1.decodeBase64Url)(advSecretB64, 'companionQr.advSecretKey'),
+        platform
+    };
+}
+/**
+ * Builds the account-signed `ADVSignedKeyIndexList` bytes for the current device
+ * set. The zero-valued `accountType` enum is omitted to match the phone's byte
+ * layout.
+ */
+async function buildSignedKeyIndexList(input) {
+    const details = _proto_1.proto.ADVKeyIndexList.encode({
+        rawId: input.rawId,
+        timestamp: input.timestampSeconds,
+        currentIndex: input.currentIndex,
+        validIndexes: [...input.validIndexes]
+    }).finish();
+    const accountSignature = await (0, _signal_1.signKeyIndexList)(details, input.accountIdentityKeyPair);
+    return _proto_1.proto.ADVSignedKeyIndexList.encode({ details, accountSignature }).finish();
+}
+/**
+ * Builds the signed device identity and key-index list for a linking companion.
+ * The byte layout mirrors WhatsApp's phone (and the in-repo fake-server
+ * reference): the zero-valued `accountType`/`deviceType` enum fields are omitted
+ * so the signed `details` match what the companion verifies.
+ */
+async function buildSignedCompanionIdentity(input) {
+    const accountSignatureKey = (0, _crypto_1.toRawPubKey)(input.accountIdentityKeyPair.pubKey);
+    const details = _proto_1.proto.ADVDeviceIdentity.encode({
+        rawId: input.rawId,
+        timestamp: input.timestampSeconds,
+        keyIndex: input.keyIndex
+    }).finish();
+    const accountSignature = await (0, _signal_1.generateDeviceIdentityAccountSignature)(details, input.companionIdentityPublicKey, input.accountIdentityKeyPair);
+    const signedIdentity = _proto_1.proto.ADVSignedDeviceIdentity.encode({
+        details,
+        accountSignatureKey,
+        accountSignature
+    }).finish();
+    const hmac = (0, _signal_1.computeAdvIdentityHmac)(input.advSecretKey, signedIdentity);
+    const deviceIdentityBytes = _proto_1.proto.ADVSignedDeviceIdentityHMAC.encode({
+        details: signedIdentity,
+        hmac
+    }).finish();
+    const keyIndexListBytes = await buildSignedKeyIndexList({
+        accountIdentityKeyPair: input.accountIdentityKeyPair,
+        rawId: input.rawId,
+        currentIndex: input.keyIndex,
+        timestampSeconds: input.timestampSeconds,
+        validIndexes: input.validIndexes
+    });
+    return { deviceIdentityBytes, keyIndexListBytes };
+}
+/**
+ * Derives the `<pem>` AES-GCM key the phone ships in the pair-device upload:
+ * `HKDF-SHA256(ikm = advSecret, salt = companionNoisePublicKey, info)`. Not yet
+ * verified against a live server from this implementation; see
+ * `CompanionHostOptions.includePem`.
+ */
+function derivePemKey(advSecretKey, companionNoisePublicKey) {
+    return (0, _crypto_1.hkdf)(advSecretKey, companionNoisePublicKey, PEM_HKDF_INFO, 32);
+}
+/**
+ * Link-code handshake, primary step 1: unwrap the companion ephemeral with the
+ * pairing code, generate the primary ephemeral, compute the shared ECDH secret,
+ * and wrap the primary ephemeral for the `primary_hello` stanza. Mirror of the
+ * companion's `createCompanionHello` + primary-ephemeral unwrap.
+ */
+async function preparePrimaryHello(args) {
+    if (args.wrappedCompanionEphemeralPub.length < 48) {
+        throw new Error(`wrapped companion ephemeral pub too short: ${args.wrappedCompanionEphemeralPub.length} bytes (need >= 48)`);
+    }
+    const codeBytes = bytes_1.TEXT_ENCODER.encode(args.pairingCode);
+    const companionCipherKey = await (0, _crypto_1.pbkdf2Sha256)(codeBytes, args.wrappedCompanionEphemeralPub.subarray(0, 32), PBKDF2_ITERATIONS, PAIRING_AES_KEY_BYTES);
+    const companionEphemeralPub = (0, _crypto_1.aesCtrDecrypt)(companionCipherKey, args.wrappedCompanionEphemeralPub.subarray(32, 48), args.wrappedCompanionEphemeralPub.subarray(48));
+    const [primaryEphemeralKeyPair, salt, counter] = await Promise.all([
+        _crypto_1.X25519.generateKeyPair(),
+        (0, _crypto_1.randomBytesAsync)(32),
+        (0, _crypto_1.randomBytesAsync)(16)
+    ]);
+    const primaryCipherKey = await (0, _crypto_1.pbkdf2Sha256)(codeBytes, salt, PBKDF2_ITERATIONS, PAIRING_AES_KEY_BYTES);
+    const encrypted = (0, _crypto_1.aesCtrEncrypt)(primaryCipherKey, counter, primaryEphemeralKeyPair.pubKey);
+    const sharedEphemeral = await _crypto_1.X25519.scalarMult(primaryEphemeralKeyPair.privKey, companionEphemeralPub);
+    return {
+        primaryEphemeralKeyPair,
+        wrappedPrimaryEphemeralPub: (0, bytes_1.concatBytes)([salt, counter, encrypted]),
+        sharedEphemeral
+    };
+}
+/**
+ * Link-code handshake, primary step 2: decrypt the `companion_finish` key bundle
+ * and derive the shared `advSecret` (byte-identical to what the companion
+ * derives). Validates that the bundle binds both identities.
+ *
+ * @throws when the bundle's embedded identities do not match.
+ */
+async function completePrimaryHandshake(args) {
+    const bundleEncryptionKey = (0, _crypto_1.hkdf)(args.sharedEphemeral, args.wrappedKeyBundle.subarray(0, 32), _protocol_1.WA_PAIRING_KDF_INFO.LINK_CODE_BUNDLE, 32);
+    const plaintextBundle = (0, _crypto_1.aesGcmDecrypt)(bundleEncryptionKey, args.wrappedKeyBundle.subarray(32, 44), args.wrappedKeyBundle.subarray(44));
+    const bundleCompanionIdentity = plaintextBundle.subarray(0, 32);
+    const bundlePrimaryIdentity = plaintextBundle.subarray(32, 64);
+    const bundleSecret = plaintextBundle.subarray(64);
+    const rawCompanionIdentity = (0, _crypto_1.toRawPubKey)(args.companionIdentityPub);
+    if (!(0, bytes_1.uint8Equal)(bundlePrimaryIdentity, (0, _crypto_1.toRawPubKey)(args.primaryIdentityKeyPair.pubKey))) {
+        throw new Error('link-code bundle primary identity mismatch');
+    }
+    if (!(0, bytes_1.uint8Equal)(bundleCompanionIdentity, rawCompanionIdentity)) {
+        throw new Error('link-code bundle companion identity mismatch');
+    }
+    const sharedIdentity = await _crypto_1.X25519.scalarMult(args.primaryIdentityKeyPair.privKey, rawCompanionIdentity);
+    return (0, _crypto_1.hkdf)((0, bytes_1.concatBytes)([args.sharedEphemeral, sharedIdentity, bundleSecret]), null, _protocol_1.WA_PAIRING_KDF_INFO.ADV_SECRET, 32);
+}

package/dist/auth/types.d.ts

@@ -39,10 +39,11 @@ export type WaAuthSocketOptions = Pick<WaCommsConfig, 'url' | 'urls' | 'protocol
     };
 };
 /**
- * WhatsApp Web version supplied to {@link WaAuthClientOptions.version}. Either
- * a literal `'x.y.z'` string or an async resolver invoked once per connect,
- * letting callers refresh the version (e.g. via `fetchLatestWaWebVersion`)
- * without rebuilding the client.
+ * Version supplied to {@link WaAuthClientOptions.version}. Either a literal
+ * dotted-numeric string or an async resolver invoked once per connect,
+ * letting callers refresh the version (e.g. via `fetchLatestWaWebVersion` or
+ * `fetchLatestWaMobileVersion`) without rebuilding the client. See
+ * {@link WaAuthClientOptions.version} for the per-transport part-count rules.
  */
 export type WaVersionResolver = string | (() => string | Promise<string>);
 export interface WaAuthClientOptions {
@@ -70,11 +71,21 @@ export interface WaAuthClientOptions {
      */
     readonly requireFullSync?: boolean;
     /**
-     * WhatsApp Web version the client advertises. Either a `'x.y.z'` literal
-     * or a (sync/async) resolver invoked once per connect – use the resolver
-     * form together with {@link fetchLatestWaWebVersion} to refresh the
-     * version when the hardcoded default starts hitting `failure_client_too_old`.
-     * Defaults to a tested production version.
+     * Version the client advertises. Either a dotted-numeric literal or a
+     * (sync/async) resolver invoked once per connect – use the resolver form
+     * together with {@link fetchLatestWaWebVersion} /
+     * {@link fetchLatestWaMobileVersion} to refresh the version when the
+     * hardcoded default starts hitting `failure_client_too_old`.
+     *
+     * The accepted shape depends on the transport resolved for the connect:
+     * - **Web** sessions take a 3- to 5-part version (`2.3000.x[.y.z]`); all
+     *   supplied parts are advertised in the noise payload.
+     * - **Mobile** sessions take exactly a 4-part Android app version
+     *   (`2.26.27.70`); it overrides `mobileTransport.deviceInfo.appVersion`
+     *   in the login payload.
+     *
+     * An invalid part count for the resolved transport throws on connect.
+     * Defaults to a tested production version per transport.
      */
     readonly version?: WaVersionResolver;
     /**

package/dist/client/WaClient.d.ts

@@ -8,6 +8,7 @@ import type { WaEmailCoordinator } from './coordinators/WaEmailCoordinator';
 import type { WaGroupCoordinator } from './coordinators/WaGroupCoordinator';
 import type { WaLowLevelCoordinator } from './coordinators/WaLowLevelCoordinator';
 import type { WaMessageCoordinator } from './coordinators/WaMessageCoordinator';
+import type { WaMobileCoordinator } from './coordinators/WaMobileCoordinator';
 import type { WaNewsletterCoordinator } from './coordinators/WaNewsletterCoordinator';
 import type { WaPresenceCoordinator } from './coordinators/WaPresenceCoordinator';
 import type { WaPrivacyCoordinator } from './coordinators/WaPrivacyCoordinator';
@@ -31,11 +32,13 @@ declare class WaClientImpl extends EventEmitter {
     private activeIncomingHandlers;
     private readonly incomingHandlersDrainedWaiters;
     private disposePlugins;
+    private readonly pluginInstallInput;
     /**
      * @param options Client configuration (store, transport, addons, history...).
      * @param logger  Optional structured logger. Defaults to a `ConsoleLogger('info')`.
      */
     constructor(options: WaClientOptions, logger?: Logger);
+    private installPlugins;
     private runClientTooOldRecover;
     /** Strongly-typed `EventEmitter#on` over {@link WaClientEventMap}. */
     on<K extends keyof WaClientEventMap>(event: K, listener: WaClientEventMap[K]): this;
@@ -100,11 +103,12 @@ declare class WaClientImpl extends EventEmitter {
     connect(): Promise<void>;
     /**
      * Closes the transport gracefully: pauses incoming events, flushes the
-     * write-behind persistence queue, and emits a `connection` close event
-     * with reason `client_disconnected`. Does not clear stored credentials -
-     * call {@link connect} again to resume the same session. There is no
-     * built-in auto-reconnect; subscribe to `connection: { status: 'close' }`
-     * and decide your own backoff.
+     * write-behind persistence queue, disposes installed plugins, and emits a
+     * `connection` close event with reason `client_disconnected`. Does not
+     * clear stored credentials - call {@link connect} again to resume the same
+     * session, which reinstalls the plugins. There is no built-in
+     * auto-reconnect; subscribe to `connection: { status: 'close' }` and decide
+     * your own backoff.
      */
     disconnect(): Promise<void>;
     /**
@@ -166,6 +170,12 @@ declare class WaClientImpl extends EventEmitter {
      * via `options.mobileTransport`. See {@link WaEmailCoordinator}.
      */
     get email(): WaEmailCoordinator;
+    /**
+     * Mobile coordinator: host and manage companion devices linked to this
+     * mobile-primary account (link via QR or pairing code, list, revoke).
+     * Requires a registered primary session. See {@link WaMobileCoordinator}.
+     */
+    get mobile(): WaMobileCoordinator;
     /**
      * Unpairs this companion device by removing it server-side. Requires an
      * authenticated session; throws when no `meJid` is present.

package/dist/client/WaClient.js

@@ -15,7 +15,7 @@ const jid_1 = require("../protocol/jid");
 const stream_1 = require("../protocol/stream");
 const device_1 = require("../transport/node/builders/device");
 const query_1 = require("../transport/node/query");
-const wa_web_version_fetcher_1 = require("../transport/wa-web-version-fetcher");
+const wa_version_fetcher_1 = require("../transport/wa-version-fetcher");
 const primitives_1 = require("../util/primitives");
 const SYNC_RELATED_PROTOCOL_TYPES = new Set([
     _proto_1.proto.Message.ProtocolMessage.Type.APP_STATE_SYNC_KEY_REQUEST,
@@ -73,13 +73,14 @@ class WaClientImpl extends node_events_1.EventEmitter {
         this.deps = dependencies;
         this.appStateSync = dependencies.appStateSync;
         this.mediaTransfer = dependencies.mediaTransfer;
-        this.disposePlugins = (0, install_1.installWaClientPlugins)(this, {
+        this.pluginInstallInput = {
             options: this.options,
             logger: this.logger,
             stores: this.stores,
             deps: this.deps,
             queryWithContext: this.queryWithContext.bind(this)
-        }, this.options.plugins ?? []);
+        };
+        this.installPlugins();
         this.bindNodeTransportEvents();
         this.on('connection', (event) => {
             if (event.status !== 'close')
@@ -88,22 +89,43 @@ class WaClientImpl extends node_events_1.EventEmitter {
                 return;
             if (event.reason !== stream_1.WA_DISCONNECT_REASONS.FAILURE_CLIENT_TOO_OLD)
                 return;
-            this.logger.warn('wa rejected the connect with client_too_old: the zapo default WA Web version is outdated. ' +
-                'Auto-recovering by fetching the current version from web.whatsapp.com – ' +
+            this.logger.warn('wa rejected the connect with client_too_old: the zapo default WA version is outdated. ' +
+                'Auto-recovering by fetching the current version from the public source – ' +
                 'please upgrade zapo so the shipped default catches up.');
             void this.runClientTooOldRecover();
         });
+        this.on('connection', (event) => {
+            if (event.status !== 'open')
+                return;
+            void this.deps.mobileCoordinator.reconcileCompanions().catch((error) => {
+                this.logger.debug('companion reconcile on connect failed', {
+                    message: (0, primitives_1.toError)(error).message
+                });
+            });
+        });
+    }
+    installPlugins() {
+        this.disposePlugins = (0, install_1.installWaClientPlugins)(this, this.pluginInstallInput, this.options.plugins ?? []);
     }
     async runClientTooOldRecover() {
         try {
             if (this.connectPromise) {
                 await this.connectPromise.catch(() => undefined);
             }
-            const latest = await (0, wa_web_version_fetcher_1.fetchLatestWaWebVersion)();
+            const mobile = this.deps.isMobilePrimary();
+            const latest = mobile
+                ? await (0, wa_version_fetcher_1.fetchLatestWaMobileVersion)()
+                : await (0, wa_version_fetcher_1.fetchLatestWaWebVersion)();
             this.logger.info('client_too_old auto-recover: reconnecting', {
+                transport: mobile ? 'mobile' : 'web',
                 version: latest.version
             });
-            this.deps.authClient.setNextConnectVersion(latest.version);
+            if (mobile) {
+                this.deps.authClient.setNextConnectMobileAppVersion(latest.version);
+            }
+            else {
+                this.deps.authClient.setNextConnectVersion(latest.version);
+            }
             await this.connect();
         }
         catch (error) {
@@ -309,6 +331,9 @@ class WaClientImpl extends node_events_1.EventEmitter {
             this.logger.trace('wa client connect already in-flight');
             return this.connectPromise;
         }
+        if (!this.disposePlugins) {
+            this.installPlugins();
+        }
         this.writeBehind.restart();
         this.acceptingIncomingEvents = true;
         this.connectPromise = this.deps.connectionManager
@@ -332,11 +357,12 @@ class WaClientImpl extends node_events_1.EventEmitter {
     }
     /**
      * Closes the transport gracefully: pauses incoming events, flushes the
-     * write-behind persistence queue, and emits a `connection` close event
-     * with reason `client_disconnected`. Does not clear stored credentials -
-     * call {@link connect} again to resume the same session. There is no
-     * built-in auto-reconnect; subscribe to `connection: { status: 'close' }`
-     * and decide your own backoff.
+     * write-behind persistence queue, disposes installed plugins, and emits a
+     * `connection` close event with reason `client_disconnected`. Does not
+     * clear stored credentials - call {@link connect} again to resume the same
+     * session, which reinstalls the plugins. There is no built-in
+     * auto-reconnect; subscribe to `connection: { status: 'close' }` and decide
+     * your own backoff.
      */
     async disconnect() {
         await this.pauseIncomingEventsAndWaitDrain();
@@ -453,6 +479,14 @@ class WaClientImpl extends node_events_1.EventEmitter {
     get email() {
         return this.deps.emailCoordinator;
     }
+    /**
+     * Mobile coordinator: host and manage companion devices linked to this
+     * mobile-primary account (link via QR or pairing code, list, revoke).
+     * Requires a registered primary session. See {@link WaMobileCoordinator}.
+     */
+    get mobile() {
+        return this.deps.mobileCoordinator;
+    }
     /**
      * Unpairs this companion device by removing it server-side. Requires an
      * authenticated session; throws when no `meJid` is present.