zapo-js 1.6.2 → 1.7.1

package/dist/crypto/core/primitives.d.ts

@@ -21,6 +21,25 @@ export declare function aesGcmEncrypt(key: AesKey, nonce: Uint8Array, plaintext:
 export declare function aesGcmDecrypt(key: AesKey, nonce: Uint8Array, ciphertext: Uint8Array, aad?: Uint8Array): Uint8Array;
 /** AES-256-CBC encrypt with PKCS#7 padding (default Node behavior). */
 export declare function aesCbcEncrypt(key: Uint8Array, iv: Uint8Array, plaintext: Uint8Array): Uint8Array;
+/**
+ * AES-256-CBC encrypt into a buffer that reserves `trailerBytes` of spare room
+ * after the ciphertext, for a caller that has to append a MAC to it.
+ *
+ * Appending to the result of {@link aesCbcEncrypt} means copying the whole
+ * ciphertext a second time, which on a media payload is a copy of the entire
+ * file to make room for ten bytes. Sizing the destination from the PKCS#7
+ * output length up front removes that copy, and feeding the cipher in bounded
+ * chunks keeps the transient buffer Node hands back to a chunk rather than a
+ * second full-size ciphertext, so peak memory stays near one copy of the
+ * payload instead of two.
+ *
+ * The ciphertext occupies `result.length - trailerBytes`; the reserved tail is
+ * left zeroed for the caller to fill.
+ *
+ * @throws when `trailerBytes` is not a non-negative safe integer, or when the
+ * cipher yields a length other than the PKCS#7 size the destination was cut to.
+ */
+export declare function aesCbcEncryptWithTrailer(key: Uint8Array, iv: Uint8Array, plaintext: Uint8Array, trailerBytes: number): Uint8Array;
 /** AES-256-CBC decrypt with PKCS#7 padding. */
 export declare function aesCbcDecrypt(key: Uint8Array, iv: Uint8Array, ciphertext: Uint8Array): Uint8Array;
 /** AES-256-CTR encrypt with the given 16-byte counter. */

package/dist/crypto/core/primitives.js

@@ -7,6 +7,7 @@ exports.md5Bytes = md5Bytes;
 exports.aesGcmEncrypt = aesGcmEncrypt;
 exports.aesGcmDecrypt = aesGcmDecrypt;
 exports.aesCbcEncrypt = aesCbcEncrypt;
+exports.aesCbcEncryptWithTrailer = aesCbcEncryptWithTrailer;
 exports.aesCbcDecrypt = aesCbcDecrypt;
 exports.aesCtrEncrypt = aesCtrEncrypt;
 exports.aesCtrDecrypt = aesCtrDecrypt;
@@ -17,6 +18,9 @@ const node_crypto_1 = require("node:crypto");
 const node_util_1 = require("node:util");
 const bytes_1 = require("../../util/bytes");
 const AES_GCM_TAG_LENGTH = 16;
+const AES_CBC_BLOCK_SIZE = 16;
+/** Bounds the transient buffer `cipher.update` returns per call. */
+const AES_CBC_CHUNK_SIZE = 262144;
 const pbkdf2Async = (0, node_util_1.promisify)(node_crypto_1.pbkdf2);
 function feed(target, input) {
     if (Array.isArray(input)) {
@@ -96,6 +100,50 @@ function aesCbcEncrypt(key, iv, plaintext) {
     }
     return (0, bytes_1.concatBytes)([head, tail]);
 }
+/**
+ * AES-256-CBC encrypt into a buffer that reserves `trailerBytes` of spare room
+ * after the ciphertext, for a caller that has to append a MAC to it.
+ *
+ * Appending to the result of {@link aesCbcEncrypt} means copying the whole
+ * ciphertext a second time, which on a media payload is a copy of the entire
+ * file to make room for ten bytes. Sizing the destination from the PKCS#7
+ * output length up front removes that copy, and feeding the cipher in bounded
+ * chunks keeps the transient buffer Node hands back to a chunk rather than a
+ * second full-size ciphertext, so peak memory stays near one copy of the
+ * payload instead of two.
+ *
+ * The ciphertext occupies `result.length - trailerBytes`; the reserved tail is
+ * left zeroed for the caller to fill.
+ *
+ * @throws when `trailerBytes` is not a non-negative safe integer, or when the
+ * cipher yields a length other than the PKCS#7 size the destination was cut to.
+ */
+function aesCbcEncryptWithTrailer(key, iv, plaintext, trailerBytes) {
+    if (!Number.isSafeInteger(trailerBytes) || trailerBytes < 0) {
+        throw new Error(`invalid trailer length ${trailerBytes}`);
+    }
+    const cipherLength = (Math.floor(plaintext.length / AES_CBC_BLOCK_SIZE) + 1) * AES_CBC_BLOCK_SIZE;
+    const out = new Uint8Array(cipherLength + trailerBytes);
+    const cipher = (0, node_crypto_1.createCipheriv)('aes-256-cbc', key, iv);
+    let offset = 0;
+    for (let start = 0; start < plaintext.length; start += AES_CBC_CHUNK_SIZE) {
+        const end = Math.min(start + AES_CBC_CHUNK_SIZE, plaintext.length);
+        const block = cipher.update(plaintext.subarray(start, end));
+        if (block.length > 0) {
+            out.set(block, offset);
+            offset += block.length;
+        }
+    }
+    const tail = cipher.final();
+    if (tail.length > 0) {
+        out.set(tail, offset);
+        offset += tail.length;
+    }
+    if (offset !== cipherLength) {
+        throw new Error(`aes-cbc produced ${offset} bytes, expected ${cipherLength}`);
+    }
+    return out;
+}
 /** AES-256-CBC decrypt with PKCS#7 padding. */
 function aesCbcDecrypt(key, iv, ciphertext) {
     const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-cbc', key, iv);

package/dist/crypto/core/xeddsa.js

@@ -9,17 +9,30 @@ const X25519_1 = require("../curves/X25519");
 const edwards_1 = require("../math/edwards");
 const le_1 = require("../math/le");
 const mod_1 = require("../math/mod");
+const nativeBackend_1 = require("../nativeBackend");
 const bytes_1 = require("../../util/bytes");
 const PREFIX_SIGNATURE_RANDOM = new Uint8Array([
     0xfe, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
     0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff
 ]);
+const nativeBinding = (() => {
+    if (process.env.ZAPO_XEDDSA_FORCE_JS)
+        return null;
+    const mod = (0, nativeBackend_1.resolveNativeCryptoBackend)();
+    if (mod && typeof mod.xeddsaSign === 'function' && typeof mod.xeddsaVerify === 'function') {
+        return { xeddsaSign: mod.xeddsaSign, xeddsaVerify: mod.xeddsaVerify };
+    }
+    return null;
+})();
 /**
  * Verifies an XEdDSA signature over `message` against an X25519 (Montgomery)
  * public key, converting to the Edwards form internally. Returns `false`
  * on shape mismatch instead of throwing.
  */
 async function xeddsaVerify(curvePublicKey, message, signature) {
+    if (nativeBinding) {
+        return nativeBinding.xeddsaVerify(curvePublicKey, message, signature);
+    }
     if (signature.length !== 64) {
         return false;
     }
@@ -38,16 +51,34 @@ async function xeddsaVerify(curvePublicKey, message, signature) {
         signature[lastByteIndex] = originalLastByte;
     }
 }
+const publicDerivationCache = new WeakMap();
+function derivePublicForSigning(privateKey) {
+    const cached = publicDerivationCache.get(privateKey);
+    if (cached) {
+        return cached;
+    }
+    const clampedPrivateKey = (0, X25519_1.clampCurvePrivateKeyInPlace)(privateKey);
+    const privateScalar = (0, le_1.bytesToBigIntLE)(clampedPrivateKey);
+    const encodedPublic = (0, edwards_1.encodeExtendedPoint)((0, edwards_1.scalarMultBase)(privateScalar));
+    const derivation = {
+        privateScalar,
+        encodedPublic,
+        pubKeySignBit: encodedPublic[31] & 0x80
+    };
+    publicDerivationCache.set(privateKey, derivation);
+    return derivation;
+}
 /**
  * Signs `message` with an X25519 (Montgomery) private key using the XEdDSA
  * construction. Returns a 64-byte signature.
  */
 async function xeddsaSign(privateKey, message) {
     (0, bytes_1.assertByteLength)(privateKey, 32, `invalid curve25519 private key length ${privateKey.length}`);
-    const clampedPrivateKey = (0, X25519_1.clampCurvePrivateKeyInPlace)(privateKey);
-    const privateScalar = (0, le_1.bytesToBigIntLE)(clampedPrivateKey);
-    const encodedPublic = (0, edwards_1.encodeExtendedPoint)((0, edwards_1.scalarMultBase)(privateScalar));
-    const pubKeySignBit = encodedPublic[31] & 0x80;
+    if (nativeBinding) {
+        return (0, bytes_1.toBytesView)(nativeBinding.xeddsaSign(privateKey, message));
+    }
+    const { privateScalar, encodedPublic, pubKeySignBit } = derivePublicForSigning(privateKey);
+    const clampedPrivateKey = privateKey;
     const randomSuffix = await (0, random_1.randomBytesAsync)(64);
     const r = (0, mod_1.modGroup)((0, le_1.bytesToBigIntLE)((0, primitives_1.sha512)([PREFIX_SIGNATURE_RANDOM, clampedPrivateKey, message, randomSuffix])));
     const encodedR = (0, edwards_1.encodeExtendedPoint)((0, edwards_1.scalarMultBase)(r));

package/dist/crypto/curves/X25519.js

@@ -10,7 +10,17 @@ const constants_1 = require("../curves/constants");
 const types_1 = require("../curves/types");
 const constants_2 = require("../math/constants");
 const fe_1 = require("../math/fe");
+const nativeBackend_1 = require("../nativeBackend");
 const bytes_1 = require("../../util/bytes");
+const nativeX25519ScalarMult = (() => {
+    if (process.env.ZAPO_X25519_FORCE_JS)
+        return null;
+    const mod = (0, nativeBackend_1.resolveNativeCryptoBackend)();
+    if (mod && typeof mod.x25519ScalarMult === 'function') {
+        return mod.x25519ScalarMult;
+    }
+    return null;
+})();
 const diffieHellmanWithCallback = node_crypto_1.diffieHellman;
 let diffieHellmanAsync = null;
 let diffieHellmanAsyncProbed = false;
@@ -76,19 +86,33 @@ function montgomeryToEdwardsPublic(curvePublicKey, signBit) {
     encoded[31] = (encoded[31] & 0x7f) | (signBit & 0x80);
     return encoded;
 }
+const privateKeyObjectCache = new WeakMap();
+const publicKeyObjectCache = new WeakMap();
 function x25519PrivateKeyObject(privKey) {
-    return (0, node_crypto_1.createPrivateKey)({
+    const cached = privateKeyObjectCache.get(privKey);
+    if (cached) {
+        return cached;
+    }
+    const keyObject = (0, node_crypto_1.createPrivateKey)({
         key: (0, types_1.pkcs8FromRawPrivate)(constants_1.X25519_PKCS8_PREFIX, privKey),
         format: 'der',
         type: 'pkcs8'
     });
+    privateKeyObjectCache.set(privKey, keyObject);
+    return keyObject;
 }
 function x25519PublicKeyObject(pubKey) {
-    return (0, node_crypto_1.createPublicKey)({
+    const cached = publicKeyObjectCache.get(pubKey);
+    if (cached) {
+        return cached;
+    }
+    const keyObject = (0, node_crypto_1.createPublicKey)({
         key: (0, bytes_1.concatBytes)([constants_1.X25519_SPKI_PREFIX, pubKey]),
         format: 'der',
         type: 'spki'
     });
+    publicKeyObjectCache.set(pubKey, keyObject);
+    return keyObject;
 }
 /**
  * X25519 key-pair generation and Diffie-Hellman scalar multiplication
@@ -120,6 +144,9 @@ class X25519 {
     static async scalarMult(privKey, pubKey) {
         (0, bytes_1.assertByteLength)(privKey, 32, 'x25519 private key must be 32 bytes');
         (0, bytes_1.assertByteLength)(pubKey, 32, 'x25519 public key must be 32 bytes');
+        if (nativeX25519ScalarMult) {
+            return (0, bytes_1.toBytesView)(nativeX25519ScalarMult(privKey, pubKey));
+        }
         const opts = {
             privateKey: x25519PrivateKeyObject(privKey),
             publicKey: x25519PublicKeyObject(pubKey)

package/dist/crypto/nativeBackend.d.ts

@@ -0,0 +1,20 @@
+export interface NativeCryptoModule {
+    readonly x25519ScalarMult?: (privateKey: Uint8Array, publicKey: Uint8Array) => Uint8Array;
+    readonly xeddsaSign?: (privateKey: Uint8Array, message: Uint8Array) => Uint8Array;
+    readonly xeddsaVerify?: (publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array) => boolean;
+}
+declare const ABSENCE_TOKENS: {
+    readonly napi: readonly ["'@zapo-js/native'", "binding.js", "Cannot find native binding"];
+    readonly wasm: readonly ["'@zapo-js/native'", "zapo_native_wasm.js"];
+};
+export type NativeBackendKind = keyof typeof ABSENCE_TOKENS;
+/**
+ * Classifies a backend load failure: `true` means the backend is simply not
+ * available on this install (missing optional package, entry file absent,
+ * no prebuilt binary, ESM build without `require`) and the fallback should
+ * stay silent; `false` means the backend is present but broken and the
+ * degradation deserves a process warning.
+ */
+export declare function isBackendAbsence(backend: NativeBackendKind, error: unknown): boolean;
+export declare function resolveNativeCryptoBackend(): NativeCryptoModule | null;
+export {};

package/dist/crypto/nativeBackend.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isBackendAbsence = isBackendAbsence;
+exports.resolveNativeCryptoBackend = resolveNativeCryptoBackend;
+/**
+ * Resolves the optional native crypto accelerator backend shared by the
+ * X25519 and XEdDSA paths. Selected via `ZAPO_NATIVE_BACKEND`:
+ *
+ *   - `auto` (default) – try the NAPI addon first, then the WASM build,
+ *                        then no accelerator.
+ *   - `napi`           – only the compiled Rust NAPI addon (`@zapo-js/native`).
+ *   - `wasm`           – only the wasm-bindgen build of the same Rust core.
+ *                        The shipped artifact targets the web (ESM glue +
+ *                        explicit init) so one build serves browsers and
+ *                        Node; loading it here relies on `require(esm)`,
+ *                        available unflagged on Node 20.19+ / 22.12+.
+ *   - `js` / `none`    – no accelerator; callers fall back to the pure-JS
+ *                        (and `node:crypto`) implementations.
+ *
+ * The module is resolved once and memoised. A failed backend resolves to
+ * `null` (or, under `auto`, falls through to the next one) so callers
+ * transparently fall back to JS. An absent backend stays silent - that is
+ * the expected shape of an optional accelerator - but a present-yet-broken
+ * one (corrupt binary, ABI mismatch, unsupported runtime) emits a process
+ * warning with code `ZAPO_NATIVE_LOAD_FAILED` so the degradation is
+ * visible. The per-primitive `ZAPO_X25519_FORCE_JS` / `ZAPO_XEDDSA_FORCE_JS`
+ * escape hatches are honoured by the callers, not here.
+ */
+const node_fs_1 = require("node:fs");
+const primitives_1 = require("../util/primitives");
+const WASM_MODULE_SPECIFIER = '@zapo-js/native/wasm/pkg/zapo_native_wasm.js';
+const WASM_BINARY_SPECIFIER = '@zapo-js/native/wasm/pkg/zapo_native_wasm_bg.wasm';
+function loadWasmBackend() {
+    const mod = require(WASM_MODULE_SPECIFIER);
+    const wasmBytes = (0, node_fs_1.readFileSync)(require.resolve(WASM_BINARY_SPECIFIER));
+    mod.initSync({ module: wasmBytes });
+    return mod;
+}
+let cached;
+const ABSENCE_TOKENS = {
+    napi: ["'@zapo-js/native'", 'binding.js', 'Cannot find native binding'],
+    wasm: ["'@zapo-js/native'", 'zapo_native_wasm.js']
+};
+/**
+ * Classifies a backend load failure: `true` means the backend is simply not
+ * available on this install (missing optional package, entry file absent,
+ * no prebuilt binary, ESM build without `require`) and the fallback should
+ * stay silent; `false` means the backend is present but broken and the
+ * degradation deserves a process warning.
+ */
+function isBackendAbsence(backend, error) {
+    if (error instanceof ReferenceError) {
+        return error.message.includes('require is not defined');
+    }
+    const { code, message } = (error ?? {});
+    if (typeof message !== 'string')
+        return false;
+    const notFound = code === 'MODULE_NOT_FOUND' || code === 'ERR_MODULE_NOT_FOUND';
+    if (!notFound && !message.includes('Cannot find native binding'))
+        return false;
+    return ABSENCE_TOKENS[backend].some((token) => message.includes(token));
+}
+function warnLoadFailure(backend, error) {
+    process.emitWarning('failed to load native crypto accelerator, falling back', {
+        code: 'ZAPO_NATIVE_LOAD_FAILED',
+        detail: `${backend}: ${(0, primitives_1.toError)(error).message}`
+    });
+}
+function resolveNativeCryptoBackend() {
+    if (cached !== undefined)
+        return cached;
+    const backend = (process.env.ZAPO_NATIVE_BACKEND ?? 'auto').toLowerCase();
+    cached = null;
+    if (backend === 'js' || backend === 'none')
+        return cached;
+    if (backend === 'napi' || backend === 'auto') {
+        try {
+            cached = require('@zapo-js/native');
+        }
+        catch (error) {
+            if (!isBackendAbsence('napi', error))
+                warnLoadFailure('napi', error);
+        }
+    }
+    if (cached === null && (backend === 'wasm' || backend === 'auto')) {
+        try {
+            cached = loadWasmBackend();
+        }
+        catch (error) {
+            if (!isBackendAbsence('wasm', error))
+                warnLoadFailure('wasm', error);
+        }
+    }
+    return cached;
+}

package/dist/esm/abprops-spec.js

@@ -0,0 +1,15 @@
+import { WA_ABPROPS_BY_CODE } from '../../spec/abprops/index.js';
+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/index.js';
+// 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 = 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.
+ */
+export function resolveAbPropNameByCode(configCode) {
+    return AB_PROP_NAME_BY_CODE[configCode];
+}

package/dist/esm/appstate/crypto/WaAppStateCrypto.js

@@ -174,12 +174,10 @@ export 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 += 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;
     }
@@ -196,7 +194,7 @@ export class WaAppStateCrypto {
     generateValueMac(valueMacHmacKey, associatedData, iv, cipherText) {
         const octetLength = new Uint8Array(APP_STATE_MAC_OCTET_LENGTH);
         octetLength[octetLength.length - 1] = associatedData.byteLength & 0xff;
-        const full = hmacSha512Sign(valueMacHmacKey, concatBytes([associatedData, iv, cipherText, octetLength]));
+        const full = hmacSha512Sign(valueMacHmacKey, [associatedData, iv, cipherText, octetLength]);
         return full.subarray(0, APP_STATE_VALUE_MAC_LENGTH);
     }
     touchDerivedKeysCacheEntry(cacheKey, keys) {

package/dist/esm/auth/WaAuthClient.js

@@ -20,11 +20,18 @@ export 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 = resolveWaDeviceIdentity(options);
         this.options = Object.freeze({
             ...options,
             deviceBrowser: device.browser,
             deviceOsDisplayName: device.osDisplayName,
+            deviceOsVersion: device.osVersion ?? undefined,
             devicePlatform: device.platform,
             requireFullSync: options.requireFullSync
         });
@@ -122,8 +129,10 @@ export class WaAuthClient {
         const mobileAppVersionOverride = this.mobileAppVersionOverride;
         this.mobileAppVersionOverride = null;
         return 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,
@@ -236,10 +245,19 @@ export 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) !==
@@ -259,6 +277,9 @@ export 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/esm/auth/credentials-flow.js

@@ -174,6 +174,8 @@ export async function buildCommsConfig(logger, credentials, socketOptions, clien
                 ? {
                     username: loginIdentity.username,
                     device: loginIdentity.device,
+                    loginCounter: credentials.loginCounter ?? 0,
+                    connectAttemptCount: clientOptions.connectAttemptCount ?? 0,
                     deviceBrowser: clientOptions.deviceBrowser,
                     deviceOsDisplayName: clientOptions.deviceOsDisplayName,
                     versionBase
@@ -185,6 +187,7 @@ export async function buildCommsConfig(logger, credentials, socketOptions, clien
                     signedPreKey: credentials.signedPreKey,
                     deviceBrowser: clientOptions.deviceBrowser,
                     deviceOsDisplayName: clientOptions.deviceOsDisplayName,
+                    deviceOsVersion: clientOptions.deviceOsVersion,
                     requireFullSync: clientOptions.requireFullSync,
                     versionBase
                 }

package/dist/esm/auth/pairing/WaPairingFlow.js

@@ -5,13 +5,18 @@ import { getWaBrowserDisplayName } from '../../protocol/browser.js';
 import { WA_DEFAULTS, WA_IQ_TYPES, WA_NODE_TAGS, WA_SIGNALING } from '../../protocol/constants.js';
 import { parsePhoneJid } from '../../protocol/jid.js';
 import { ADV_PREFIX_HOSTED_ACCOUNT_SIGNATURE, computeAdvIdentityHmac, generateDeviceSignature, verifyDeviceIdentityAccountSignature } from '../../signal/attestation/WaAdvSignature.js';
-import { buildAckNode, buildIqResultNode } from '../../transport/node/builders/global.js';
+import { buildAckNode, buildIqErrorNode, buildIqResultNode } from '../../transport/node/builders/global.js';
 import { buildCompanionFinishRequestNode, buildCompanionHelloRequestNode, buildGetCountryCodeRequestNode } from '../../transport/node/builders/pairing.js';
 import { decodeNodeContentUtf8OrBytes, findNodeChild, findNodeChildrenByTags, getFirstNodeChild, getNodeChildrenNonEmptyUtf8ByTag, hasNodeChild } from '../../transport/node/helpers.js';
 import { assertIqResult } from '../../transport/node/query.js';
 import { concatBytes, decodeProtoBytes, uint8Equal, uint8TimingSafeEqual } from '../../util/bytes.js';
+import { toError } from '../../util/primitives.js';
+/** 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;
 export class WaPairingFlow {
     constructor(options) {
+        this.pairSuccessInFlight = false;
         this.opts = options;
         this.pairingSession = null;
     }
@@ -30,6 +35,7 @@ export class WaPairingFlow {
         const normalizedCustomCode = customCode !== undefined ? normalizeCustomPairingCode(customCode) : undefined;
         const credentials = this.requireCredentials();
         const phoneJid = parsePhoneJid(phoneNumber);
+        const createdAtSeconds = Math.floor(Date.now() / 1000);
         const [companionHello, refreshedCredentials] = await Promise.all([
             createCompanionHello({ customCode: normalizedCustomCode }),
             this.rotateAdvSecret(credentials)
@@ -61,7 +67,7 @@ export class WaPairingFlow {
             pairingCode: companionHello.pairingCode,
             phoneJid,
             ref,
-            createdAtSeconds: Math.floor(Date.now() / 1000),
+            createdAtSeconds,
             companionEphemeralKeyPair: companionHello.companionEphemeralKeyPair,
             attempts: 0,
             finished: false
@@ -163,6 +169,23 @@ export 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] = findNodeChildrenByTags(pairSuccessNode, [WA_NODE_TAGS.DEVICE_IDENTITY, 'device', WA_NODE_TAGS.PLATFORM]);
@@ -174,7 +197,12 @@ export class WaPairingFlow {
             });
             throw new Error('pair-success stanza is missing required nodes');
         }
-        const wrappedIdentity = proto.ADVSignedDeviceIdentityHMAC.decode(decodeNodeContentUtf8OrBytes(deviceIdentityNode.content, 'pair-success.device-identity'));
+        const deviceIdentityBytes = 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.ADVSignedDeviceIdentityHMAC.decode(deviceIdentityBytes);
         const wrappedDetails = decodeProtoBytes(wrappedIdentity.details, 'ADVSignedDeviceIdentityHMAC.details');
         const wrappedHmac = decodeProtoBytes(wrappedIdentity.hmac, 'ADVSignedDeviceIdentityHMAC.hmac');
         const accountType = wrappedIdentity.accountType ?? proto.ADVEncryptionType.E2EE;
@@ -191,16 +219,23 @@ export 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', {
@@ -235,6 +270,7 @@ export 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.ADVSignedDeviceIdentity.decode(wrappedDetails);
         const details = decodeProtoBytes(signedIdentity.details, 'ADVSignedDeviceIdentity.details');
@@ -250,7 +286,7 @@ export class WaPairingFlow {
                     keyIndex: advDeviceIdentity.keyIndex ?? 0,
                     isDeviceHosted
                 });
-                throw new Error('pair-success account signature validation failed');
+                return null;
             }
         }
         signedIdentity.deviceSignature = await generateDeviceSignature(details, localIdentity, accountSignatureKey, false);
@@ -265,19 +301,35 @@ export 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(buildIqErrorNode(iqNode, { code: 401, text: 'not-authorized' }));
+        }
+        catch (error) {
+            this.opts.logger.warn('failed to send pair-success error response', {
+                message: 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 > 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] = findNodeChildrenByTags(linkCodeNode, [
             WA_NODE_TAGS.LINK_CODE_PAIRING_REF,
@@ -306,6 +358,10 @@ export 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(buildCompanionFinishRequestNode({
             phoneJid: pairingSession.phoneJid,
             wrappedKeyBundle: finish.wrappedKeyBundle,
@@ -315,10 +371,6 @@ export class WaPairingFlow {
         if (result.attrs.type === 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');
     }