zapo-js 1.7.0 → 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/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/WaClientFactory.js

@@ -100,6 +100,7 @@ function resolveWaClientBase(options, logger) {
         sessionId,
         deviceBrowser: device.browser,
         deviceOsDisplayName: device.osDisplayName,
+        deviceOsVersion: device.osVersion ?? undefined,
         devicePlatform: device.platform,
         urls: options.urls ?? options.chatSocketUrls ?? constants_1.WA_DEFAULTS.CHAT_SOCKET_URLS,
         iqTimeoutMs: options.iqTimeoutMs ?? constants_1.WA_DEFAULTS.IQ_TIMEOUT_MS,
@@ -124,7 +125,7 @@ function createIncomingNodeRuntime(input) {
     const { logger, emitEvent, authClient, connectionManager, nodeOrchestrator, streamControl, mediaMessageBuildOptions, retryCoordinator, messageDispatch, sendNode, syncAppState, disconnect, clearStoredCredentials, getCurrentCredentials, handleClientDirtyBits, incomingMessageAckOptions } = input;
     return {
         handleStreamControlResult: streamControl.handleStreamControlResult,
-        persistSuccessAttributes: (attributes) => authClient.persistSuccessAttributes(attributes),
+        persistSuccessAttributes: (attributes) => authClient.persistSuccessAttributes(attributes, { countsAsLogin: true }),
         emitSuccessNode: (node) => emitEvent('debug_connection_success', { node }),
         updateClockSkewFromSuccess: (serverUnixSeconds) => connectionManager.updateClockSkewFromSuccess(serverUnixSeconds),
         shouldWarmupMediaConn: () => !!(getCurrentCredentials()?.meJid && connectionManager.isConnected()),
@@ -332,6 +333,7 @@ function buildWaClientDependencies(input) {
     const authClient = new WaAuthClient_1.WaAuthClient({
         deviceBrowser: options.deviceBrowser,
         deviceOsDisplayName: options.deviceOsDisplayName,
+        deviceOsVersion: options.deviceOsVersion,
         devicePlatform: options.devicePlatform,
         requireFullSync: options.requireFullSync,
         version: options.version,

package/dist/client/coordinators/WaMessageDispatchCoordinator.js

@@ -398,17 +398,16 @@ class WaMessageDispatchCoordinator {
         ]);
         const messageWithIcdc = (0, icdc_1.injectDeviceListMetadata)(messageWithSecret, senderIcdc, recipientIcdc);
         const plaintext = await (0, padding_1.writeRandomPadMax16)(_proto_1.proto.Message.encode(messageWithIcdc).finish());
-        const buttonAddonKind = (0, content_1.resolveButtonAddonKind)(messageWithIcdc);
+        const outboundAttrs = (0, content_1.resolveOutboundMessageAttrs)(messageWithIcdc);
+        const buttonAddonKind = outboundAttrs.buttonAddonKind;
         const buttonAddonNode = buttonAddonKind ? (0, message_1.buildButtonAddonNode)(buttonAddonKind) : undefined;
         // when a <biz> companion is attached the stanza must advertise type=text and
         // omit enc.mediatype; sending type=media + mediatype=list/button alongside the
         // companion is rejected by the server as SMAX_INVALID (479).
-        const type = buttonAddonKind ? 'text' : (0, content_1.resolveMessageTypeAttr)(messageWithIcdc);
-        const edit = (0, content_1.resolveEditAttr)(messageWithIcdc) ?? undefined;
-        const mediatype = buttonAddonKind
-            ? undefined
-            : ((0, content_1.resolveEncMediaType)(messageWithIcdc) ?? undefined);
-        const metaAttrs = (0, content_1.resolveMetaAttrs)(messageWithIcdc);
+        const type = buttonAddonKind ? 'text' : outboundAttrs.typeAttr;
+        const edit = outboundAttrs.edit ?? undefined;
+        const mediatype = buttonAddonKind ? undefined : (outboundAttrs.mediatype ?? undefined);
+        const metaAttrs = outboundAttrs.metaAttrs;
         const metaNode = metaAttrs ? (0, message_1.buildMetaNode)(metaAttrs) : undefined;
         const customNodes = [];
         if (metaNode)
@@ -420,7 +419,7 @@ class WaMessageDispatchCoordinator {
                 customNodes.push(node);
             }
         }
-        const decryptFail = (0, content_1.resolveDecryptFailAttr)(messageWithIcdc);
+        const decryptFail = outboundAttrs.decryptFail;
         const envelope = {
             message: messageWithIcdc,
             plaintext,
@@ -540,7 +539,7 @@ class WaMessageDispatchCoordinator {
             replayStatusSetting: statusSetting,
             // Bare `<to jid=user>` ack hints route the skmsg through primary
             // devices that already hold the sender key.
-            customize: async ({ fanoutDeviceJids, distributionParticipants, messageWithSecret, sendOptions }) => {
+            customize: ({ fanoutDeviceJids, distributionParticipants, messageWithSecret, sendOptions }) => {
                 const distributedAddressKeys = new Set();
                 for (let i = 0; i < distributionParticipants.length; i += 1) {
                     distributedAddressKeys.add((0, jid_1.signalAddressKey)(distributionParticipants[i].address));
@@ -560,7 +559,7 @@ class WaMessageDispatchCoordinator {
                     seenAck.add(userJid);
                     ackHints.push({ jid: userJid });
                 }
-                const reportingArtifacts = await this.tryBuildReportingTokenArtifacts({
+                const reportingArtifacts = this.tryBuildReportingTokenArtifacts({
                     message: messageWithSecret,
                     stanzaId: sendOptions.id,
                     senderUserJid: (0, jid_1.toUserJid)(senderJid),
@@ -638,14 +637,15 @@ class WaMessageDispatchCoordinator {
                 participants.push(entry);
             }
         }
+        const outboundAttrs = (0, content_1.resolveOutboundMessageAttrs)(messageWithSecret);
         const messageNode = (0, message_1.buildGroupSenderKeyMessageNode)({
             to: input.groupJid,
-            type: (0, content_1.resolveMessageTypeAttr)(messageWithSecret),
+            type: outboundAttrs.typeAttr,
             id: sendOptions.id,
             phash: extras.phash,
-            edit: (0, content_1.resolveEditAttr)(messageWithSecret) ?? undefined,
-            mediatype: (0, content_1.resolveEncMediaType)(messageWithSecret) ?? undefined,
-            decryptFail: (0, content_1.resolveDecryptFailAttr)(messageWithSecret),
+            edit: outboundAttrs.edit ?? undefined,
+            mediatype: outboundAttrs.mediatype ?? undefined,
+            decryptFail: outboundAttrs.decryptFail,
             groupCiphertext: groupCiphertext.ciphertext,
             participants,
             deviceIdentity: shouldAttachDeviceIdentity
@@ -819,8 +819,9 @@ class WaMessageDispatchCoordinator {
                 break;
             }
         }
-        const reportingArtifacts = await this.tryBuildReportingTokenArtifacts({
+        const reportingArtifacts = this.tryBuildReportingTokenArtifacts({
             message,
+            messageBytes: (0, padding_1.unpadPkcs7)(plaintext),
             stanzaId: sendOptions.id,
             senderUserJid: (0, jid_1.toUserJid)(senderJid),
             remoteJid: groupJid,
@@ -975,8 +976,9 @@ class WaMessageDispatchCoordinator {
         phashTargets[phashTargetCount] = senderJid;
         phashTargets.length = phashTargetCount + 1;
         const localPhash = (0, phash_1.computePhashV2)(phashTargets);
-        const reportingArtifacts = await this.tryBuildReportingTokenArtifacts({
+        const reportingArtifacts = this.tryBuildReportingTokenArtifacts({
             message,
+            messageBytes: (0, padding_1.unpadPkcs7)(plaintext),
             stanzaId: sendOptions.id,
             senderUserJid: (0, jid_1.toUserJid)(senderJid),
             remoteJid: groupJid,
@@ -1088,9 +1090,6 @@ class WaMessageDispatchCoordinator {
         return (0, jid_1.normalizeDeviceJid)(meJid);
     }
     async encryptGroupDistributionParticipants(groupJid, senderKeyId, senderKeyDistributionMessage, participantUserJids) {
-        const distributionPayload = await (0, padding_1.writeRandomPadMax16)(_proto_1.proto.Message.encode({
-            senderKeyDistributionMessage
-        }).finish());
         const fanoutDeviceJids = await this.deps.fanoutResolver.resolveGroupParticipantDeviceJids(participantUserJids);
         if (fanoutDeviceJids.length === 0) {
             return {
@@ -1098,13 +1097,9 @@ class WaMessageDispatchCoordinator {
                 distributionParticipants: []
             };
         }
-        const fanoutTargetsByAddressKey = new Map();
         const fanoutAddresses = new Array(fanoutDeviceJids.length);
         for (let index = 0; index < fanoutDeviceJids.length; index += 1) {
-            const jid = fanoutDeviceJids[index];
-            const address = (0, jid_1.parseSignalAddressFromJid)(jid);
-            fanoutAddresses[index] = address;
-            fanoutTargetsByAddressKey.set((0, jid_1.signalAddressKey)(address), { jid, address });
+            fanoutAddresses[index] = (0, jid_1.parseSignalAddressFromJid)(fanoutDeviceJids[index]);
         }
         const pendingAddresses = await this.deps.senderKeyManager.filterParticipantsNeedingDistribution(groupJid, senderKeyId, fanoutAddresses);
         if (pendingAddresses.length === 0) {
@@ -1113,6 +1108,14 @@ class WaMessageDispatchCoordinator {
                 distributionParticipants: []
             };
         }
+        const fanoutTargetsByAddressKey = new Map();
+        for (let index = 0; index < fanoutAddresses.length; index += 1) {
+            const address = fanoutAddresses[index];
+            fanoutTargetsByAddressKey.set((0, jid_1.signalAddressKey)(address), {
+                jid: fanoutDeviceJids[index],
+                address
+            });
+        }
         const pendingAddressKeys = new Set();
         const pendingTargets = [];
         for (let index = 0; index < pendingAddresses.length; index += 1) {
@@ -1172,6 +1175,9 @@ class WaMessageDispatchCoordinator {
                 distributionParticipants: []
             };
         }
+        const distributionPayload = await (0, padding_1.writeRandomPadMax16)(_proto_1.proto.Message.encode({
+            senderKeyDistributionMessage
+        }).finish());
         const distributionEncryptRequests = new Array(availableTargets.length);
         for (let index = 0; index < availableTargets.length; index += 1) {
             const target = availableTargets[index];
@@ -1324,8 +1330,9 @@ class WaMessageDispatchCoordinator {
         const deviceIdentity = shouldAttachDeviceIdentity
             ? this.getEncodedSignedDeviceIdentity()
             : undefined;
-        const reportingArtifacts = await this.tryBuildReportingTokenArtifacts({
+        const reportingArtifacts = this.tryBuildReportingTokenArtifacts({
             message,
+            messageBytes: (0, padding_1.unpadPkcs7)(plaintext),
             stanzaId: sendOptions.id,
             senderUserJid: meUserJid,
             remoteJid: recipientUserJid,
@@ -1428,13 +1435,14 @@ class WaMessageDispatchCoordinator {
             return `3EB0${(0, bytes_1.bytesToHex)(await (0, _crypto_1.randomBytesAsync)(8)).toUpperCase()}`;
         }
     }
-    async tryBuildReportingTokenArtifacts(input) {
+    tryBuildReportingTokenArtifacts(input) {
         if (!input.stanzaId) {
             return null;
         }
         try {
-            return await (0, reporting_token_1.buildReportingTokenArtifacts)({
+            return (0, reporting_token_1.buildReportingTokenArtifacts)({
                 message: input.message,
+                messageBytes: input.messageBytes,
                 stanzaId: input.stanzaId,
                 senderUserJid: input.senderUserJid,
                 remoteJid: input.remoteJid