zapo-js 1.7.0 → 1.8.0

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/WaClient.js

@@ -61,6 +61,7 @@ class WaClientImpl extends node_events_1.EventEmitter {
                 syncAppState: () => this.deps.chatCoordinator.sync().then(() => { }),
                 syncAppStateWithOptions: (syncOptions) => this.deps.chatCoordinator.sync(syncOptions),
                 emitEvent: this.emit.bind(this),
+                hasEventListener: (event) => this.listenerCount(event) > 0,
                 handleIncomingMessageEvent: this.handleIncomingMessageEvent.bind(this),
                 handleError: this.handleError.bind(this),
                 handleIncomingFrame: this.handleIncomingFrame.bind(this),

package/dist/client/WaClientFactory.d.ts

@@ -60,6 +60,8 @@ interface WaClientBuildRuntime {
     readonly syncAppState: () => Promise<void>;
     readonly syncAppStateWithOptions: (options?: WaAppStateSyncOptions) => Promise<WaAppStateSyncResult>;
     readonly emitEvent: <K extends keyof WaClientEventMap>(event: K, ...args: Parameters<WaClientEventMap[K]>) => void;
+    /** Whether anything is subscribed, for events whose payload costs something to build. */
+    readonly hasEventListener: (event: keyof WaClientEventMap) => boolean;
     readonly handleIncomingMessageEvent: (event: WaIncomingMessageEvent) => Promise<void>;
     readonly handleError: (error: Error) => void;
     readonly handleIncomingFrame: (frame: Uint8Array) => Promise<void>;

package/dist/client/WaClientFactory.js

@@ -32,6 +32,7 @@ const devices_1 = require("./events/devices");
 const dirty_1 = require("./events/dirty");
 const identity_1 = require("./events/identity");
 const privacy_token_1 = require("./events/privacy-token");
+const username_1 = require("./events/username");
 const fanout_1 = require("./messaging/fanout");
 const group_metadata_1 = require("./messaging/group-metadata");
 const key_protocol_1 = require("./messaging/key-protocol");
@@ -41,6 +42,7 @@ const WaMediaTransferClient_1 = require("../media/transfer/WaMediaTransferClient
 const fetcher_1 = require("../message/addons/link-preview/fetcher");
 const newsletter_1 = require("../message/kinds/newsletter");
 const incoming_1 = require("../message/primitives/incoming");
+const media_retry_1 = require("../message/primitives/media-retry");
 const peer_data_operation_1 = require("../message/primitives/peer-data-operation");
 const WaMessageClient_1 = require("../message/WaMessageClient");
 const constants_1 = require("../protocol/constants");
@@ -100,6 +102,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,
@@ -121,10 +124,10 @@ function resolveWaClientBase(options, logger) {
     };
 }
 function createIncomingNodeRuntime(input) {
-    const { logger, emitEvent, authClient, connectionManager, nodeOrchestrator, streamControl, mediaMessageBuildOptions, retryCoordinator, messageDispatch, sendNode, syncAppState, disconnect, clearStoredCredentials, getCurrentCredentials, handleClientDirtyBits, incomingMessageAckOptions } = input;
+    const { logger, emitEvent, authClient, connectionManager, nodeOrchestrator, streamControl, mediaMessageBuildOptions, retryCoordinator, mediaRetryRequester, 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()),
@@ -140,6 +143,7 @@ function createIncomingNodeRuntime(input) {
         handleIncomingMessageNode: (node) => (0, incoming_1.handleIncomingMessageAck)(node, incomingMessageAckOptions),
         sendNode,
         handleIncomingRetryReceipt: (node) => retryCoordinator.handleIncomingRetryReceipt(node),
+        handleMediaRetryNotification: (node) => mediaRetryRequester.handleNotification(node),
         trackOutboundReceipt: (node) => retryCoordinator.trackOutboundReceipt(node),
         emitIncomingReceipt: (event) => emitEvent('receipt', event),
         emitIncomingPresence: (event) => emitEvent('presence', event),
@@ -332,6 +336,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,
@@ -380,6 +385,8 @@ function buildWaClientDependencies(input) {
     });
     const privacyCoordinator = (0, WaPrivacyCoordinator_1.createPrivacyCoordinator)({
         logger,
+        contactStore: sessionStore.contacts,
+        isUsernamePrivacyListIdentifierEnabled: () => abPropsCoordinator.getConfigValue('username_contact_privacy_setting_allow_uncontact_set_enable'),
         queryWithContext: runtime.queryWithContext,
         resolveUserJidPair: (userJid) => signalDeviceSync.resolveUserJidPair(userJid),
         getSelfLid: () => getCurrentCredentials()?.meLid ?? null,
@@ -512,9 +519,15 @@ function buildWaClientDependencies(input) {
         generateOutgoingMessageId: () => messageDispatch.generateOutgoingMessageId(),
         subscribeToProtocolMessage: runtime.subscribeProtocolMessage
     });
+    const mediaRetryRequester = (0, media_retry_1.createMediaRetryRequester)({
+        logger,
+        sendNode: (node) => nodeOrchestrator.sendNode(node, false),
+        getCurrentCredentials
+    });
     const messageCoordinator = new WaMessageCoordinator_1.WaMessageCoordinator({
         messageDispatch,
         mediaTransfer,
+        mediaRetry: mediaRetryRequester,
         mediaUploadOptions: mediaMessageBuildOptions,
         logger,
         messageStore: sessionStore.messages,
@@ -717,7 +730,15 @@ function buildWaClientDependencies(input) {
         },
         emitNewsletterMessageUpdate: (event) => runtime.emitEvent('newsletter_message_update', event),
         emitUnavailableMessage: (event) => runtime.emitEvent('message_unavailable', event),
-        emitUnhandledStanza: (event) => runtime.emitEvent('debug_unhandled_stanza', event)
+        emitUnhandledStanza: (event) => runtime.emitEvent('debug_unhandled_stanza', event),
+        emitDecryptedPayload: (build) => {
+            // Built only if someone is subscribed: the payload carries a copy of
+            // the plaintext and a redacted node, and this runs per `<enc>`.
+            if (!runtime.hasEventListener('debug_decrypted_payload')) {
+                return;
+            }
+            runtime.emitEvent('debug_decrypted_payload', build());
+        }
     };
     const handleClientDirtyBits = (dirtyBits) => (0, dirty_1.handleDirtyBits)({
         logger,
@@ -750,6 +771,7 @@ function buildWaClientDependencies(input) {
             streamControl,
             mediaMessageBuildOptions,
             retryCoordinator,
+            mediaRetryRequester,
             messageDispatch,
             sendNode: runtime.sendNode,
             syncAppState: runtime.syncAppState,
@@ -926,6 +948,10 @@ function buildWaClientDependencies(input) {
             if ((0, helpers_1.findNodeChild)(node, constants_1.WA_NODE_TAGS.PRIVACY)) {
                 privacyCoordinator.scheduleAccountSyncRefresh();
             }
+            const usernameEvent = (0, username_1.parseOwnUsernameNotification)(node);
+            if (usernameEvent) {
+                runtime.emitEvent('own_username', usernameEvent);
+            }
             return false;
         }
     });

package/dist/client/coordinators/WaIncomingNodeCoordinator.d.ts

@@ -22,6 +22,7 @@ interface WaIncomingNodeRuntime {
     readonly handleIncomingMessageNode: (node: BinaryNode) => Promise<boolean>;
     readonly sendNode: (node: BinaryNode) => Promise<void>;
     readonly handleIncomingRetryReceipt: (node: BinaryNode) => Promise<void>;
+    readonly handleMediaRetryNotification: (node: BinaryNode) => void;
     readonly trackOutboundReceipt: (node: BinaryNode) => Promise<void>;
     readonly emitIncomingReceipt: (event: WaIncomingReceiptEvent) => void;
     readonly emitIncomingPresence: (event: WaIncomingPresenceEvent) => void;

package/dist/client/coordinators/WaIncomingNodeCoordinator.js

@@ -238,7 +238,8 @@ class WaIncomingNodeCoordinator {
                 emitIncomingNotification: runtime.emitIncomingNotification,
                 emitMexNotification: runtime.emitMexNotification,
                 emitUnhandledStanza: runtime.emitUnhandledIncomingNode,
-                syncAppState: runtime.syncAppState
+                syncAppState: runtime.syncAppState,
+                handleMediaRetryNotification: runtime.handleMediaRetryNotification
             })
         });
         this.registerIncomingHandler({