zapo-js 1.6.2 → 1.7.1

package/README.md

@@ -41,8 +41,8 @@ npm install zapo-js
 ```
 
 Zero mandatory runtime dependencies. Pick the optional packages you need
-on top: a persistent store and (optionally) the media processor for
-thumbnails / voice-note metadata.
+on top: a persistent store, the media processor for thumbnails /
+voice-note metadata, and the native crypto accelerator.
 
 ```bash
 # Persistent store - choose one
@@ -56,10 +56,21 @@ npm install @zapo-js/store-sqlite better-sqlite3
 npm install @zapo-js/media-utils sharp
 # plus a system `ffmpeg` + `ffprobe` on PATH (see media-utils README)
 
+# Optional - Rust crypto accelerator, no code change required
+npm install @zapo-js/native
+
 # Optional - structured logging
 npm install pino pino-pretty
 ```
 
+`@zapo-js/native` is picked up automatically once installed: the core
+resolves it on first use and falls back to the JS implementation when it is
+absent, so nothing else changes. It accelerates the two primitives that
+dominate the messaging hot path, X25519 ECDH and XEdDSA sign / verify. The
+published build is the WASM one (`ZAPO_NATIVE_BACKEND=auto` tries the NAPI
+addon first, then WASM); the compiled NAPI addon is not on npm yet and has
+to be built from `packages/native`. Set `ZAPO_NATIVE_BACKEND=js` to opt out.
+
 ## Quick Start
 
 ```ts
@@ -116,16 +127,19 @@ The core lives at the repo root (`zapo-js`). Optional packages live in
 [`packages/`](packages/) and ship under the `@zapo-js/*` scope. Install
 only what you need.
 
-| Package                                              | Peer dependency             | Purpose                                                                                                                                          |
-| ---------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| [`@zapo-js/store-sqlite`](packages/store-sqlite)     | `better-sqlite3`            | SQLite persistent store (single-process bots, dev sessions, small-to-medium prod).                                                               |
-| [`@zapo-js/store-redis`](packages/store-redis)       | `ioredis`                   | Redis-backed store with native TTL eviction.                                                                                                     |
-| [`@zapo-js/store-mongo`](packages/store-mongo)       | `mongodb`                   | MongoDB-backed store with TTL-index eviction.                                                                                                    |
-| [`@zapo-js/store-mysql`](packages/store-mysql)       | `mysql2`                    | MySQL / MariaDB-backed store with background cleanup poller.                                                                                     |
-| [`@zapo-js/store-postgres`](packages/store-postgres) | `pg`                        | PostgreSQL-backed store with background cleanup poller.                                                                                          |
-| [`@zapo-js/media-utils`](packages/media-utils)       | `sharp` + `ffmpeg`          | `WaMediaProcessor`: thumbnails, waveforms, voice-note normalization.                                                                             |
-| [`@zapo-js/fake-server`](packages/fake-server)       | (none)                      | In-process fake WhatsApp Web server for end-to-end testing.                                                                                      |
-| [`@zapo-js/mcp-server`](packages/mcp-server)         | `@modelcontextprotocol/sdk` | **Dev-only.** MCP server exposing multi-session `WaClient`s as dynamic tools for an LLM agent (Claude Code / Cursor / etc.). Not for production. |
+| Package                                              | Peer dependency                  | Purpose                                                                                                                                          |
+| ---------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [`@zapo-js/store-sqlite`](packages/store-sqlite)     | `better-sqlite3`                 | SQLite persistent store (single-process bots, dev sessions, small-to-medium prod).                                                               |
+| [`@zapo-js/store-redis`](packages/store-redis)       | `ioredis`                        | Redis-backed store with native TTL eviction.                                                                                                     |
+| [`@zapo-js/store-mongo`](packages/store-mongo)       | `mongodb`                        | MongoDB-backed store with TTL-index eviction.                                                                                                    |
+| [`@zapo-js/store-mysql`](packages/store-mysql)       | `mysql2`                         | MySQL / MariaDB-backed store with background cleanup poller.                                                                                     |
+| [`@zapo-js/store-postgres`](packages/store-postgres) | `pg`                             | PostgreSQL-backed store with background cleanup poller.                                                                                          |
+| [`@zapo-js/media-utils`](packages/media-utils)       | `sharp` + `file-type` + `ffmpeg` | `WaMediaProcessor`: thumbnails, waveforms, voice-note normalization.                                                                             |
+| [`@zapo-js/native`](packages/native)                 | (none)                           | Rust crypto accelerator for the messaging hot path (X25519 ECDH, XEdDSA sign / verify). Auto-detected once installed; ships as a WASM build.     |
+| [`@zapo-js/voip`](packages/voip)                     | `@roamhq/wrtc` + `libmlow-wasm`  | `client.voip` plugin for calls: MLow/WASM codec, SRTP, STUN, WebRTC/SCTP relay transport.                                                        |
+| [`@zapo-js/wam`](packages/wam)                       | (none)                           | `client.wam` plugin emitting the client-side WAM telemetry batches WA Web sends, for wire parity and anti-fingerprinting.                        |
+| [`@zapo-js/fake-server`](packages/fake-server)       | (none)                           | In-process fake WhatsApp Web server for end-to-end testing.                                                                                      |
+| [`@zapo-js/mcp-server`](packages/mcp-server)         | `@modelcontextprotocol/sdk`      | **Dev-only.** MCP server exposing multi-session `WaClient`s as dynamic tools for an LLM agent (Claude Code / Cursor / etc.). Not for production. |
 
 Each package's README has the install + config + integration notes.
 

package/dist/abprops-spec.d.ts

@@ -0,0 +1,10 @@
+import { type WaAbPropName } from '../spec/abprops';
+export { WA_ABPROPS, WA_ABPROPS_BY_CODE, WA_ABPROPS_SPECIAL_EARLY, WA_ABPROPS_USED_BEFORE_INIT, WA_GROUP_ABPROPS, WA_GROUP_ABPROPS_BY_CODE } from '../spec/abprops';
+export type { WaAbProp, WaAbPropName, WaAbPropType, WaAbPropValue, WaAbPropValueByName, WaAbPropValueOf, WaGroupAbPropName, WaGroupAbPropValueByName } from '../spec/abprops';
+/**
+ * Resolves the client-side prop name for a wire config code.
+ *
+ * Returns `undefined` for codes this build does not know about - the server
+ * advertises props from newer bundles, and WA Web drops those rows too.
+ */
+export declare function resolveAbPropNameByCode(configCode: number): WaAbPropName | undefined;

package/dist/abprops-spec.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WA_GROUP_ABPROPS_BY_CODE = exports.WA_GROUP_ABPROPS = exports.WA_ABPROPS_USED_BEFORE_INIT = exports.WA_ABPROPS_SPECIAL_EARLY = exports.WA_ABPROPS_BY_CODE = exports.WA_ABPROPS = void 0;
+exports.resolveAbPropNameByCode = resolveAbPropNameByCode;
+const abprops_1 = require("../spec/abprops");
+var abprops_2 = require("../spec/abprops");
+Object.defineProperty(exports, "WA_ABPROPS", { enumerable: true, get: function () { return abprops_2.WA_ABPROPS; } });
+Object.defineProperty(exports, "WA_ABPROPS_BY_CODE", { enumerable: true, get: function () { return abprops_2.WA_ABPROPS_BY_CODE; } });
+Object.defineProperty(exports, "WA_ABPROPS_SPECIAL_EARLY", { enumerable: true, get: function () { return abprops_2.WA_ABPROPS_SPECIAL_EARLY; } });
+Object.defineProperty(exports, "WA_ABPROPS_USED_BEFORE_INIT", { enumerable: true, get: function () { return abprops_2.WA_ABPROPS_USED_BEFORE_INIT; } });
+Object.defineProperty(exports, "WA_GROUP_ABPROPS", { enumerable: true, get: function () { return abprops_2.WA_GROUP_ABPROPS; } });
+Object.defineProperty(exports, "WA_GROUP_ABPROPS_BY_CODE", { enumerable: true, get: function () { return abprops_2.WA_GROUP_ABPROPS_BY_CODE; } });
+// The reverse map is emitted with numeric literal keys, so it cannot be indexed
+// with a plain `number`. Widening it keeps the lookup a single property read and
+// avoids allocating a parallel Map with 2000+ entries at module init.
+const AB_PROP_NAME_BY_CODE = abprops_1.WA_ABPROPS_BY_CODE;
+/**
+ * Resolves the client-side prop name for a wire config code.
+ *
+ * Returns `undefined` for codes this build does not know about - the server
+ * advertises props from newer bundles, and WA Web drops those rows too.
+ */
+function resolveAbPropNameByCode(configCode) {
+    return AB_PROP_NAME_BY_CODE[configCode];
+}

package/dist/appstate/crypto/WaAppStateCrypto.js

@@ -177,12 +177,10 @@ class WaAppStateCrypto {
         if (out.byteLength !== left.byteLength) {
             throw new Error('lt hash output length mismatch');
         }
-        const leftView = new DataView(left.buffer, left.byteOffset, left.byteLength);
-        const rightView = new DataView(right.buffer, right.byteOffset, right.byteLength);
-        const outView = new DataView(out.buffer, out.byteOffset, out.byteLength);
         for (let offset = 0; offset < left.byteLength; offset += constants_1.APP_STATE_POINT_SIZE) {
-            const value = combine(leftView.getUint16(offset, true), rightView.getUint16(offset, true));
-            outView.setUint16(offset, value & 0xffff, true);
+            const value = combine(left[offset] | (left[offset + 1] << 8), right[offset] | (right[offset + 1] << 8));
+            out[offset] = value & 0xff;
+            out[offset + 1] = (value >>> 8) & 0xff;
         }
         return out;
     }
@@ -199,7 +197,7 @@ class WaAppStateCrypto {
     generateValueMac(valueMacHmacKey, associatedData, iv, cipherText) {
         const octetLength = new Uint8Array(constants_1.APP_STATE_MAC_OCTET_LENGTH);
         octetLength[octetLength.length - 1] = associatedData.byteLength & 0xff;
-        const full = (0, primitives_1.hmacSha512Sign)(valueMacHmacKey, (0, bytes_1.concatBytes)([associatedData, iv, cipherText, octetLength]));
+        const full = (0, primitives_1.hmacSha512Sign)(valueMacHmacKey, [associatedData, iv, cipherText, octetLength]);
         return full.subarray(0, constants_1.APP_STATE_VALUE_MAC_LENGTH);
     }
     touchDerivedKeysCacheEntry(cacheKey, keys) {

package/dist/auth/WaAuthClient.d.ts

@@ -52,6 +52,12 @@ export declare class WaAuthClient {
     private credentials;
     private versionOverride;
     private mobileAppVersionOverride;
+    /**
+     * Successful logins made by this instance, advertised as
+     * `connectAttemptCount`. Process-local by design – the persisted
+     * counterpart is `credentials.loginCounter`.
+     */
+    private connectAttemptCount;
     constructor(options: WaAuthClientOptions, deps: WaAuthClientDeps);
     /**
      * Returns a snapshot of auth readiness flags (connection, registration,
@@ -121,8 +127,15 @@ export declare class WaAuthClient {
      * Persists the per-connection success attributes from the server (LID,
      * display name, companion key, last-success ts, props versions, ...). Only
      * persists when at least one attribute actually changed.
+     *
+     * Pass `countsAsLogin` only for the server `success` node: it advances the
+     * login counters advertised as `lc` / `connectAttemptCount`. Callers that
+     * merely reuse this to persist a single attribute (a push-name change, for
+     * instance) must leave it unset.
      */
-    persistSuccessAttributes(attributes: WaSuccessPersistAttributes): Promise<void>;
+    persistSuccessAttributes(attributes: WaSuccessPersistAttributes, { countsAsLogin }?: {
+        readonly countsAsLogin?: boolean;
+    }): Promise<void>;
     /**
      * Requests an 8-character pairing code for `phoneNumber` (link-code flow).
      * Pass `customCode` to suggest a specific code; the server still validates

package/dist/auth/WaAuthClient.js

@@ -23,11 +23,18 @@ class WaAuthClient {
     constructor(options, deps) {
         this.versionOverride = null;
         this.mobileAppVersionOverride = null;
+        /**
+         * Successful logins made by this instance, advertised as
+         * `connectAttemptCount`. Process-local by design – the persisted
+         * counterpart is `credentials.loginCounter`.
+         */
+        this.connectAttemptCount = 0;
         const device = (0, constants_1.resolveWaDeviceIdentity)(options);
         this.options = Object.freeze({
             ...options,
             deviceBrowser: device.browser,
             deviceOsDisplayName: device.osDisplayName,
+            deviceOsVersion: device.osVersion ?? undefined,
             devicePlatform: device.platform,
             requireFullSync: options.requireFullSync
         });
@@ -125,8 +132,10 @@ class WaAuthClient {
         const mobileAppVersionOverride = this.mobileAppVersionOverride;
         this.mobileAppVersionOverride = null;
         return (0, credentials_flow_1.buildCommsConfig)(this.logger, this.requireCredentials(), socketOptions, {
+            connectAttemptCount: this.connectAttemptCount,
             deviceBrowser: this.options.deviceBrowser,
             deviceOsDisplayName: this.options.deviceOsDisplayName,
+            deviceOsVersion: this.options.deviceOsVersion,
             requireFullSync: this.options.requireFullSync,
             version: override ?? this.options.version,
             mobileTransport: this.options.mobileTransport,
@@ -239,10 +248,19 @@ class WaAuthClient {
      * Persists the per-connection success attributes from the server (LID,
      * display name, companion key, last-success ts, props versions, ...). Only
      * persists when at least one attribute actually changed.
+     *
+     * Pass `countsAsLogin` only for the server `success` node: it advances the
+     * login counters advertised as `lc` / `connectAttemptCount`. Callers that
+     * merely reuse this to persist a single attribute (a push-name change, for
+     * instance) must leave it unset.
      */
-    async persistSuccessAttributes(attributes) {
+    async persistSuccessAttributes(attributes, { countsAsLogin = false } = {}) {
+        if (countsAsLogin) {
+            this.connectAttemptCount += 1;
+        }
         let persistDiff;
         const computeDiff = (current, next) => ({
+            loginCounterChanged: next.loginCounter !== current.loginCounter,
             lidChanged: next.meLid !== current.meLid,
             displayNameChanged: next.meDisplayName !== current.meDisplayName,
             companionChanged: (current.companionEncStatic === undefined) !==
@@ -262,6 +280,9 @@ class WaAuthClient {
             meDisplayName: attributes.meDisplayName ?? credentials.meDisplayName,
             companionEncStatic: attributes.companionEncStatic ?? credentials.companionEncStatic,
             lastSuccessTs: attributes.lastSuccessTs ?? credentials.lastSuccessTs,
+            loginCounter: countsAsLogin
+                ? (credentials.loginCounter ?? 0) + 1
+                : credentials.loginCounter,
             propsVersion: attributes.propsVersion ?? credentials.propsVersion,
             abPropsVersion: attributes.abPropsVersion ?? credentials.abPropsVersion,
             connectionLocation: attributes.connectionLocation ?? credentials.connectionLocation,

package/dist/auth/credentials-flow.d.ts

@@ -14,7 +14,7 @@ interface WaAuthCredentialsFlowArgs {
 }
 export declare function loadOrCreateCredentials(args: WaAuthCredentialsFlowArgs): Promise<WaAuthCredentials>;
 export declare function persistCredentials(args: WaAuthCredentialsFlowArgs, credentials: WaAuthCredentials): Promise<void>;
-export declare function buildCommsConfig(logger: Logger, credentials: WaAuthCredentials, socketOptions: WaAuthSocketOptions, clientOptions: Pick<WaAuthClientOptions, 'deviceBrowser' | 'deviceOsDisplayName' | 'requireFullSync' | 'version' | 'mobileTransport'> & {
+export declare function buildCommsConfig(logger: Logger, credentials: WaAuthCredentials, socketOptions: WaAuthSocketOptions, clientOptions: Pick<WaAuthClientOptions, 'deviceBrowser' | 'deviceOsDisplayName' | 'deviceOsVersion' | 'requireFullSync' | 'version' | 'mobileTransport'> & {
     readonly noiseTrustedRootCa?: WaNoiseRootCa;
     readonly disableNoiseCertificateChainVerification?: boolean;
     /**
@@ -25,5 +25,7 @@ export declare function buildCommsConfig(logger: Logger, credentials: WaAuthCred
      * sessions.
      */
     readonly mobileAppVersionOverride?: string;
+    /** Successful logins made by the calling client instance so far. */
+    readonly connectAttemptCount?: number;
 }): Promise<WaCommsConfig>;
 export {};

package/dist/auth/credentials-flow.js

@@ -179,6 +179,8 @@ async function buildCommsConfig(logger, credentials, socketOptions, clientOption
                 ? {
                     username: loginIdentity.username,
                     device: loginIdentity.device,
+                    loginCounter: credentials.loginCounter ?? 0,
+                    connectAttemptCount: clientOptions.connectAttemptCount ?? 0,
                     deviceBrowser: clientOptions.deviceBrowser,
                     deviceOsDisplayName: clientOptions.deviceOsDisplayName,
                     versionBase
@@ -190,6 +192,7 @@ async function buildCommsConfig(logger, credentials, socketOptions, clientOption
                     signedPreKey: credentials.signedPreKey,
                     deviceBrowser: clientOptions.deviceBrowser,
                     deviceOsDisplayName: clientOptions.deviceOsDisplayName,
+                    deviceOsVersion: clientOptions.deviceOsVersion,
                     requireFullSync: clientOptions.requireFullSync,
                     versionBase
                 }

package/dist/auth/pairing/WaPairingFlow.d.ts

@@ -31,6 +31,7 @@ interface WaPairingFlowOptions {
 export declare class WaPairingFlow {
     private readonly opts;
     private pairingSession;
+    private pairSuccessInFlight;
     constructor(options: WaPairingFlowOptions);
     hasPairingSession(): boolean;
     clearSession(): void;
@@ -41,7 +42,11 @@ export declare class WaPairingFlow {
     handleCompanionRegRefreshNotification(node: BinaryNode): Promise<boolean>;
     private handlePairDevice;
     private handlePairSuccess;
+    private completePairSuccess;
+    /** Returns `null` when the primary's account signature does not verify. */
     private buildPairSuccessResponseIdentity;
+    /** Mirrors the `not-authorized` IQ error WhatsApp Web returns on a failed pair-success. */
+    private sendPairSuccessValidationError;
     private handlePrimaryHello;
     private rotateAdvSecret;
     private requireCredentials;

package/dist/auth/pairing/WaPairingFlow.js

@@ -13,8 +13,13 @@ const pairing_1 = require("../../transport/node/builders/pairing");
 const helpers_1 = require("../../transport/node/helpers");
 const query_1 = require("../../transport/node/query");
 const bytes_1 = require("../../util/bytes");
+const primitives_1 = require("../../util/primitives");
+/** Server-enforced bounds on the `pair-success` `device-identity` payload. */
+const PAIR_SUCCESS_DEVICE_IDENTITY_MIN_BYTES = 1;
+const PAIR_SUCCESS_DEVICE_IDENTITY_MAX_BYTES = 500;
 class WaPairingFlow {
     constructor(options) {
+        this.pairSuccessInFlight = false;
         this.opts = options;
         this.pairingSession = null;
     }
@@ -33,6 +38,7 @@ class WaPairingFlow {
         const normalizedCustomCode = customCode !== undefined ? (0, pairing_code_crypto_1.normalizeCustomPairingCode)(customCode) : undefined;
         const credentials = this.requireCredentials();
         const phoneJid = (0, jid_1.parsePhoneJid)(phoneNumber);
+        const createdAtSeconds = Math.floor(Date.now() / 1000);
         const [companionHello, refreshedCredentials] = await Promise.all([
             (0, pairing_code_crypto_1.createCompanionHello)({ customCode: normalizedCustomCode }),
             this.rotateAdvSecret(credentials)
@@ -64,7 +70,7 @@ class WaPairingFlow {
             pairingCode: companionHello.pairingCode,
             phoneJid,
             ref,
-            createdAtSeconds: Math.floor(Date.now() / 1000),
+            createdAtSeconds,
             companionEphemeralKeyPair: companionHello.companionEphemeralKeyPair,
             attempts: 0,
             finished: false
@@ -166,6 +172,23 @@ class WaPairingFlow {
         this.opts.logger.debug('pair-device refs updated', { refsCount: refs.length });
     }
     async handlePairSuccess(iqNode, pairSuccessNode) {
+        if (this.pairSuccessInFlight) {
+            this.opts.logger.debug('pair-success ignored: already processing');
+            return;
+        }
+        if (this.opts.auth.getCredentials()?.meJid) {
+            this.opts.logger.debug('pair-success ignored: session already registered');
+            return;
+        }
+        this.pairSuccessInFlight = true;
+        try {
+            await this.completePairSuccess(iqNode, pairSuccessNode);
+        }
+        finally {
+            this.pairSuccessInFlight = false;
+        }
+    }
+    async completePairSuccess(iqNode, pairSuccessNode) {
         this.opts.logger.debug('processing pair-success node');
         const credentials = this.requireCredentials();
         const [deviceIdentityNode, deviceNode, platformNode] = (0, helpers_1.findNodeChildrenByTags)(pairSuccessNode, [constants_1.WA_NODE_TAGS.DEVICE_IDENTITY, 'device', constants_1.WA_NODE_TAGS.PLATFORM]);
@@ -177,7 +200,12 @@ class WaPairingFlow {
             });
             throw new Error('pair-success stanza is missing required nodes');
         }
-        const wrappedIdentity = _proto_1.proto.ADVSignedDeviceIdentityHMAC.decode((0, helpers_1.decodeNodeContentUtf8OrBytes)(deviceIdentityNode.content, 'pair-success.device-identity'));
+        const deviceIdentityBytes = (0, helpers_1.decodeNodeContentUtf8OrBytes)(deviceIdentityNode.content, 'pair-success.device-identity');
+        if (deviceIdentityBytes.length < PAIR_SUCCESS_DEVICE_IDENTITY_MIN_BYTES ||
+            deviceIdentityBytes.length > PAIR_SUCCESS_DEVICE_IDENTITY_MAX_BYTES) {
+            throw new Error(`pair-success device-identity must be ${PAIR_SUCCESS_DEVICE_IDENTITY_MIN_BYTES}-${PAIR_SUCCESS_DEVICE_IDENTITY_MAX_BYTES} bytes, got ${deviceIdentityBytes.length}`);
+        }
+        const wrappedIdentity = _proto_1.proto.ADVSignedDeviceIdentityHMAC.decode(deviceIdentityBytes);
         const wrappedDetails = (0, bytes_1.decodeProtoBytes)(wrappedIdentity.details, 'ADVSignedDeviceIdentityHMAC.details');
         const wrappedHmac = (0, bytes_1.decodeProtoBytes)(wrappedIdentity.hmac, 'ADVSignedDeviceIdentityHMAC.hmac');
         const accountType = wrappedIdentity.accountType ?? _proto_1.proto.ADVEncryptionType.E2EE;
@@ -194,16 +222,23 @@ class WaPairingFlow {
                     platform: platformNode.attrs.name,
                     isHosted
                 });
+                await this.sendPairSuccessValidationError(iqNode);
                 throw new Error('pair-success HMAC validation failed');
             }
         }
-        const { signedIdentity, keyIndex, responseIdentityBytes } = await this.buildPairSuccessResponseIdentity(credentials, wrappedDetails);
+        const built = await this.buildPairSuccessResponseIdentity(credentials, wrappedDetails);
+        if (!built) {
+            await this.sendPairSuccessValidationError(iqNode);
+            throw new Error('pair-success account signature validation failed');
+        }
+        const { signedIdentity, keyIndex, responseIdentityBytes } = built;
         const nextCredentials = {
             ...credentials,
             signedIdentity,
             meJid: deviceNode.attrs.jid,
             meLid: deviceNode.attrs.lid,
-            platform: platformNode.attrs.name
+            platform: platformNode.attrs.name,
+            loginCounter: 0
         };
         await this.opts.auth.updateCredentials(nextCredentials);
         this.opts.logger.info('pair-success credentials updated', {
@@ -238,6 +273,7 @@ class WaPairingFlow {
         this.opts.callbacks.emitPaired(nextCredentials);
         this.opts.logger.debug('pair-success completed and paired event emitted');
     }
+    /** Returns `null` when the primary's account signature does not verify. */
     async buildPairSuccessResponseIdentity(credentials, wrappedDetails) {
         const signedIdentity = _proto_1.proto.ADVSignedDeviceIdentity.decode(wrappedDetails);
         const details = (0, bytes_1.decodeProtoBytes)(signedIdentity.details, 'ADVSignedDeviceIdentity.details');
@@ -253,7 +289,7 @@ class WaPairingFlow {
                     keyIndex: advDeviceIdentity.keyIndex ?? 0,
                     isDeviceHosted
                 });
-                throw new Error('pair-success account signature validation failed');
+                return null;
             }
         }
         signedIdentity.deviceSignature = await (0, WaAdvSignature_1.generateDeviceSignature)(details, localIdentity, accountSignatureKey, false);
@@ -268,19 +304,35 @@ class WaPairingFlow {
             responseIdentityBytes
         };
     }
+    /** Mirrors the `not-authorized` IQ error WhatsApp Web returns on a failed pair-success. */
+    async sendPairSuccessValidationError(iqNode) {
+        try {
+            await this.opts.socket.sendNode((0, global_1.buildIqErrorNode)(iqNode, { code: 401, text: 'not-authorized' }));
+        }
+        catch (error) {
+            this.opts.logger.warn('failed to send pair-success error response', {
+                message: (0, primitives_1.toError)(error).message
+            });
+        }
+    }
     async handlePrimaryHello(linkCodeNode) {
-        const credentials = this.requireCredentials();
+        let credentials = this.requireCredentials();
         const pairingSession = this.pairingSession;
-        if (!pairingSession || pairingSession.finished) {
+        if (!pairingSession) {
             this.opts.logger.trace('primary_hello ignored: no active session');
             return;
         }
         pairingSession.attempts += 1;
         this.opts.logger.debug('processing primary_hello', {
-            attempts: pairingSession.attempts
+            attempts: pairingSession.attempts,
+            finished: pairingSession.finished
         });
-        if (pairingSession.attempts > 3) {
-            throw new Error('pairing code exceeded maximum primary hello attempts');
+        if (pairingSession.finished) {
+            if (pairingSession.attempts > constants_1.WA_DEFAULTS.PAIRING_CODE_MAX_PRIMARY_HELLOS) {
+                throw new Error('pairing code exceeded maximum primary hello attempts');
+            }
+            credentials = await this.rotateAdvSecret(credentials);
+            pairingSession.finished = false;
         }
         const [refNode, wrappedPrimaryNode, primaryIdentityNode] = (0, helpers_1.findNodeChildrenByTags)(linkCodeNode, [
             constants_1.WA_NODE_TAGS.LINK_CODE_PAIRING_REF,
@@ -309,6 +361,10 @@ class WaPairingFlow {
             companionEphemeralPrivKey: pairingSession.companionEphemeralKeyPair.privKey,
             registrationIdentityKeyPair: credentials.registrationInfo.identityKeyPair
         });
+        await this.opts.auth.updateCredentials({
+            ...credentials,
+            advSecretKey: finish.advSecret
+        });
         const result = await this.opts.socket.query((0, pairing_1.buildCompanionFinishRequestNode)({
             phoneJid: pairingSession.phoneJid,
             wrappedKeyBundle: finish.wrappedKeyBundle,
@@ -318,10 +374,6 @@ class WaPairingFlow {
         if (result.attrs.type === constants_1.WA_IQ_TYPES.ERROR) {
             throw new Error('companion_finish returned error');
         }
-        await this.opts.auth.updateCredentials({
-            ...credentials,
-            advSecretKey: finish.advSecret
-        });
         pairingSession.finished = true;
         this.opts.logger.debug('primary_hello completed with companion_finish success');
     }

package/dist/auth/types.d.ts

@@ -24,6 +24,11 @@ export interface WaAuthCredentials {
     readonly serverHasPreKeys?: boolean;
     readonly routingInfo?: Uint8Array;
     readonly lastSuccessTs?: number;
+    /**
+     * Successful logins since this device was paired, advertised as `lc` in the
+     * noise login payload. Reset to `0` when a new pairing completes.
+     */
+    readonly loginCounter?: number;
     readonly propsVersion?: number;
     readonly abPropsVersion?: number;
     readonly connectionLocation?: string;
@@ -65,6 +70,14 @@ export interface WaAuthClientOptions {
      * `'Mac OS'`, `'Linux'`). Defaults to the current runtime's OS.
      */
     readonly deviceOsDisplayName?: string;
+    /**
+     * OS version advertised in `DeviceProps.version` (`'10'`, `'14.6'`, ...).
+     * Defaults to the detected runtime OS version. Set this alongside
+     * {@link deviceOsDisplayName} when advertising an OS the process is not
+     * running on, so the advertised name and version agree. Values that are
+     * not dotted-numeric leave the field unset.
+     */
+    readonly deviceOsVersion?: string;
     /**
      * When `true`, request a full history download from the primary device on
      * pairing instead of just recent messages. Off by default.

package/dist/client/WaClient.d.ts

@@ -27,6 +27,7 @@ declare class WaClientImpl extends EventEmitter {
     private readonly appStateSync;
     private readonly mediaTransfer;
     private readonly writeBehind;
+    private readonly observeEphemeralSetting;
     private connectPromise;
     private acceptingIncomingEvents;
     private activeIncomingHandlers;
@@ -74,6 +75,16 @@ declare class WaClientImpl extends EventEmitter {
     getClockSkewMs(): number | null;
     private bindNodeTransportEvents;
     private handleIncomingMessageEvent;
+    /**
+     * Kicks off the group-history bundle download when the incoming message
+     * carries one. Fire-and-forget: the blob can be large, and the incoming
+     * handler must not stall behind a CDN fetch.
+     *
+     * The download outlives the handler that started it, so it takes a slot of
+     * its own in the drain accounting - `disconnect()` and `clearStoredState()`
+     * must not flush or wipe the stores while a bundle is still writing.
+     */
+    private tryProcessGroupHistoryBundle;
     private queryWithContext;
     private handleIncomingFrame;
     /**

package/dist/client/WaClient.js

@@ -3,12 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WaClient = void 0;
 const node_events_1 = require("node:events");
 const ignore_key_1 = require("./messaging/ignore-key");
+const ephemeral_setting_1 = require("./persistence/ephemeral-setting");
+const group_history_1 = require("./persistence/group-history");
 const history_sync_1 = require("./persistence/history-sync");
 const mailbox_1 = require("./persistence/mailbox");
 const WriteBehindPersistence_1 = require("./persistence/WriteBehindPersistence");
 const install_1 = require("./plugins/install");
 const WaClientFactory_1 = require("./WaClientFactory");
 const ConsoleLogger_1 = require("../infra/log/ConsoleLogger");
+const content_1 = require("../message/encode/content");
 const _proto_1 = require("../proto");
 const constants_1 = require("../protocol/constants");
 const jid_1 = require("../protocol/jid");
@@ -45,6 +48,10 @@ class WaClientImpl extends node_events_1.EventEmitter {
             threadStore: this.stores.threads,
             contactStore: this.stores.contacts
         }, this.logger, this.options.writeBehind);
+        this.observeEphemeralSetting = (0, ephemeral_setting_1.createEphemeralObserver)({
+            logger: this.logger,
+            chatMetadataStore: this.stores.chatMetadata
+        });
         const dependencies = (0, WaClientFactory_1.buildWaClientDependencies)({
             base,
             runtime: {
@@ -185,6 +192,7 @@ class WaClientImpl extends node_events_1.EventEmitter {
         }
         try {
             this.emit('message', event);
+            this.observeEphemeralSetting(event);
             void (0, mailbox_1.persistIncomingMailboxEntities)({
                 logger: this.logger,
                 writeBehind: this.writeBehind,
@@ -210,6 +218,9 @@ class WaClientImpl extends node_events_1.EventEmitter {
                     });
                 });
             }
+            if (this.options.history?.groupBundles === true && event.message && !event.key.fromMe) {
+                this.tryProcessGroupHistoryBundle(event);
+            }
             const protocolMessage = event.message?.protocolMessage;
             if (!protocolMessage) {
                 return;
@@ -261,6 +272,7 @@ class WaClientImpl extends node_events_1.EventEmitter {
                     await (0, history_sync_1.runHistorySyncNotification)({
                         logger: this.logger,
                         mediaTransfer: this.mediaTransfer,
+                        chatMetadataStore: this.stores.chatMetadata,
                         writeBehind: this.writeBehind,
                         emitEvent: this.emit.bind(this),
                         onPrivacyTokens: (conversations) => this.deps.trustedContactToken.hydrateFromHistorySync(conversations),
@@ -273,6 +285,16 @@ class WaClientImpl extends node_events_1.EventEmitter {
                 }
                 return;
             }
+            if (protocolType === _proto_1.proto.Message.ProtocolMessage.Type.EPHEMERAL_SETTING) {
+                (0, ephemeral_setting_1.persistIncomingEphemeralSetting)({
+                    logger: this.logger,
+                    writeBehind: this.writeBehind,
+                    chatMetadataStore: this.stores.chatMetadata,
+                    event,
+                    protocolMessage
+                });
+                return;
+            }
             if (SYNC_RELATED_PROTOCOL_TYPES.has(protocolType)) {
                 this.logger.info('incoming sync-related protocol message', {
                     id: event.key.id,
@@ -291,6 +313,43 @@ class WaClientImpl extends node_events_1.EventEmitter {
             this.leaveIncomingHandler();
         }
     }
+    /**
+     * Kicks off the group-history bundle download when the incoming message
+     * carries one. Fire-and-forget: the blob can be large, and the incoming
+     * handler must not stall behind a CDN fetch.
+     *
+     * The download outlives the handler that started it, so it takes a slot of
+     * its own in the drain accounting - `disconnect()` and `clearStoredState()`
+     * must not flush or wipe the stores while a bundle is still writing.
+     */
+    tryProcessGroupHistoryBundle(event) {
+        const bundle = (0, content_1.unwrapMessage)(event.message ?? {}).messageHistoryBundle;
+        const groupJid = event.key.remoteJid;
+        if (!bundle || !groupJid) {
+            return;
+        }
+        if (!this.tryEnterIncomingHandler()) {
+            return;
+        }
+        const credentials = this.deps.authClient.getCurrentCredentials();
+        void (0, group_history_1.runGroupHistoryBundle)({
+            logger: this.logger,
+            mediaTransfer: this.mediaTransfer,
+            writeBehind: this.writeBehind,
+            emitEvent: this.emit.bind(this),
+            meJid: credentials?.meJid,
+            meLid: credentials?.meLid,
+            getAbPropNumber: (name) => this.deps.abPropsCoordinator.getConfigValue(name)
+        }, {
+            bundle,
+            groupJid,
+            senderJid: event.key.participant ?? undefined,
+            bundleMessageId: event.key.id,
+            sentAtSeconds: event.timestampSeconds
+        }).finally(() => {
+            this.leaveIncomingHandler();
+        });
+    }
     async queryWithContext(context, node, timeoutMs = this.options.iqTimeoutMs ?? constants_1.WA_DEFAULTS.IQ_TIMEOUT_MS, contextData = {}, options = {}) {
         return (0, query_1.queryWithContext)(async (queryNode, queryTimeoutMs) => this.deps.lowLevelCoordinator.query(queryNode, queryTimeoutMs, options), this.logger, context, node, timeoutMs, contextData);
     }
@@ -365,6 +424,7 @@ class WaClientImpl extends node_events_1.EventEmitter {
      * your own backoff.
      */
     async disconnect() {
+        this.deps.privacyCoordinator.stopAccountSyncRefresh();
         await this.pauseIncomingEventsAndWaitDrain();
         const writeBehindFlush = await this.writeBehind.flush(this.options.writeBehind?.flushTimeoutMs);
         if (writeBehindFlush.remaining > 0) {

package/dist/client/WaClientFactory.d.ts

@@ -18,7 +18,7 @@ import { WaMobileCoordinator } from './coordinators/WaMobileCoordinator';
 import { type WaNewsletterCoordinator } from './coordinators/WaNewsletterCoordinator';
 import { WaPassiveTasksCoordinator } from './coordinators/WaPassiveTasksCoordinator';
 import { type WaPresenceCoordinator } from './coordinators/WaPresenceCoordinator';
-import { type WaPrivacyCoordinator } from './coordinators/WaPrivacyCoordinator';
+import { type WaPrivacyCoordinatorRuntime } from './coordinators/WaPrivacyCoordinator';
 import { type WaProfileCoordinator } from './coordinators/WaProfileCoordinator';
 import { WaRetryCoordinator } from './coordinators/WaRetryCoordinator';
 import { type WaStatusCoordinator } from './coordinators/WaStatusCoordinator';
@@ -110,7 +110,7 @@ export interface WaClientDependencies {
     readonly statusCoordinator: WaStatusCoordinator;
     readonly broadcastListCoordinator: WaBroadcastListCoordinator;
     readonly newsletterCoordinator: WaNewsletterCoordinator;
-    readonly privacyCoordinator: WaPrivacyCoordinator;
+    readonly privacyCoordinator: WaPrivacyCoordinatorRuntime;
     readonly profileCoordinator: WaProfileCoordinator;
     readonly businessCoordinator: WaBusinessCoordinator;
     readonly botCoordinator: WaBotCoordinator;