zapo-js 0.3.0 → 1.0.0

package/dist/transport/noise/WaClientPayload.js

@@ -5,8 +5,8 @@ exports.buildRegistrationPayload = buildRegistrationPayload;
 const node_crypto_1 = require("node:crypto");
 const primitives_1 = require("../../crypto/core/primitives");
 const _proto_1 = require("../../proto.js");
-const constants_1 = require("../noise/constants");
 const bytes_1 = require("../../util/bytes");
+const _version_spec_1 = require("../../version-spec.js");
 function parseVersion(versionBase) {
     const [p = '2', s = '3000', t = '0'] = versionBase.split('.');
     const primary = Number.parseInt(p, 10);
@@ -111,12 +111,13 @@ function defaultDeviceProps(versionBase, config, version) {
             supportHostedGroupMsg: true,
             supportBizHostedMsg: true,
             supportFbidBotChatHistory: true,
-            supportMessageAssociation: true
+            supportMessageAssociation: true,
+            supportInlineContacts: true
         }
     }).finish();
 }
 function buildCommonPayload(config, version) {
-    const versionBase = config.versionBase ?? constants_1.DEFAULT_VERSION_BASE;
+    const versionBase = config.versionBase ?? _version_spec_1.WA_VERSION;
     const pull = config.pull ?? true;
     return {
         passive: config.passive === true,
@@ -124,10 +125,9 @@ function buildCommonPayload(config, version) {
         connectType: _proto_1.proto.ClientPayload.ConnectType.WIFI_UNKNOWN,
         connectReason: _proto_1.proto.ClientPayload.ConnectReason.USER_ACTIVATED,
         userAgent: config.userAgent ?? defaultUserAgent(versionBase, config.deviceOsDisplayName, version),
-        webInfo: config.webInfo ??
-            {
-                webSubPlatform: defaultWebSubPlatform()
-            }
+        webInfo: config.webInfo ?? {
+            webSubPlatform: defaultWebSubPlatform()
+        }
     };
 }
 function buildLoginPayload(config) {
@@ -151,7 +151,7 @@ function buildRegistrationPayload(config) {
     if (!Number.isSafeInteger(signedPreKeyId) || signedPreKeyId <= 0) {
         throw new Error('registration payload requires a valid signedPreKeyId');
     }
-    const versionBase = config.versionBase ?? constants_1.DEFAULT_VERSION_BASE;
+    const versionBase = config.versionBase ?? _version_spec_1.WA_VERSION;
     const version = parseVersion(versionBase);
     const common = buildCommonPayload(config, version);
     const devicePairingData = {

package/dist/transport/noise/WaMobileClientPayload.js

@@ -16,6 +16,11 @@ function parseAppVersion(version) {
         quaternary: at(3)
     };
 }
+/**
+ * Builds the encoded {@link Proto.ClientPayload} bytes the WhatsApp Mobile
+ * transport sends after the noise login handshake. Throws when
+ * `username`/`appVersion` are missing/invalid.
+ */
 function buildMobileLoginPayload(config) {
     if (!Number.isSafeInteger(config.username) || config.username <= 0) {
         throw new Error('mobile login payload requires a valid numeric username');

package/dist/transport/noise/WaNoiseCert.js

@@ -29,6 +29,11 @@ function parseNoiseCertificate(certificate) {
         signature: signatureBytes
     };
 }
+/**
+ * Validates a WhatsApp noise certificate chain against `rootCa` (defaults to
+ * the production root) and confirms the leaf binds `serverStatic`. Throws on
+ * any structural mismatch, bad signature, or unexpected issuer serial.
+ */
 async function verifyNoiseCertificateChain(certificateChain, serverStatic, rootCa = PRODUCTION_ROOT_CA) {
     const chain = _proto_1.proto.CertChain.decode(certificateChain);
     if (!chain.leaf || !chain.intermediate) {

package/dist/transport/noise/WaNoiseHandshake.js

@@ -4,53 +4,55 @@ exports.WaNoiseHandshake = void 0;
 const _crypto_1 = require("../../crypto/index.js");
 const WaNoiseSocket_1 = require("../noise/WaNoiseSocket");
 const bytes_1 = require("../../util/bytes");
+/**
+ * Implements the Noise XX-style handshake state used by WaComms: tracks the
+ * handshake hash, chaining key, derived cipher key, and nonce counter. Calls
+ * {@link finish} to produce the post-handshake {@link WaNoiseSocket}.
+ */
 class WaNoiseHandshake {
     constructor() {
+        this.nonceScratch = new Uint8Array(12);
         this.handshakeHash = bytes_1.EMPTY_BYTES;
         this.chainingKey = bytes_1.EMPTY_BYTES;
         this.cipherKey = null;
         this.nonce = 0;
     }
-    async start(protocolName, prologue) {
-        const hashInput = protocolName.length === 32 ? protocolName : await (0, _crypto_1.sha256)(protocolName);
+    start(protocolName, prologue) {
+        const hashInput = protocolName.length === 32 ? protocolName : (0, _crypto_1.sha256)(protocolName);
         this.handshakeHash = hashInput;
         this.chainingKey = hashInput;
-        this.cipherKey = await (0, _crypto_1.importAesGcmKey)(this.handshakeHash, ['encrypt', 'decrypt']);
-        await this.authenticate(prologue);
+        this.cipherKey = this.handshakeHash;
+        this.authenticate(prologue);
     }
-    async authenticate(data) {
-        this.handshakeHash = await (0, _crypto_1.sha256)((0, bytes_1.concatBytes)([this.handshakeHash, data]));
+    authenticate(data) {
+        this.handshakeHash = (0, _crypto_1.sha256)([this.handshakeHash, data]);
     }
-    async mixIntoKey(keyMaterial) {
+    mixIntoKey(keyMaterial) {
         this.nonce = 0;
-        const [newChainingKey, nextCipherKey] = await (0, _crypto_1.hkdfSplit)(keyMaterial, this.chainingKey, '');
+        const [newChainingKey, nextCipherKey] = (0, _crypto_1.hkdfSplit)(keyMaterial, this.chainingKey, bytes_1.EMPTY_BYTES);
         this.chainingKey = newChainingKey;
-        this.cipherKey = await (0, _crypto_1.importAesGcmKey)(nextCipherKey, ['encrypt', 'decrypt']);
+        this.cipherKey = nextCipherKey;
     }
-    async encrypt(plaintext) {
+    encrypt(plaintext) {
         if (!this.cipherKey) {
             throw new Error('noise handshake cipher key is not initialized');
         }
-        const nonce = (0, _crypto_1.buildNonce)(this.nonce++);
-        const ciphertext = await (0, _crypto_1.aesGcmEncrypt)(this.cipherKey, nonce, plaintext, this.handshakeHash);
-        await this.authenticate(ciphertext);
+        (0, _crypto_1.writeNonceCounter)(this.nonceScratch, this.nonce++);
+        const ciphertext = (0, _crypto_1.aesGcmEncrypt)(this.cipherKey, this.nonceScratch, plaintext, this.handshakeHash);
+        this.authenticate(ciphertext);
         return ciphertext;
     }
-    async decrypt(ciphertext) {
+    decrypt(ciphertext) {
         if (!this.cipherKey) {
             throw new Error('noise handshake cipher key is not initialized');
         }
-        const nonce = (0, _crypto_1.buildNonce)(this.nonce++);
-        const plaintext = await (0, _crypto_1.aesGcmDecrypt)(this.cipherKey, nonce, ciphertext, this.handshakeHash);
-        await this.authenticate(ciphertext);
+        (0, _crypto_1.writeNonceCounter)(this.nonceScratch, this.nonce++);
+        const plaintext = (0, _crypto_1.aesGcmDecrypt)(this.cipherKey, this.nonceScratch, ciphertext, this.handshakeHash);
+        this.authenticate(ciphertext);
         return plaintext;
     }
-    async finish() {
-        const [writeKeyRaw, readKeyRaw] = await (0, _crypto_1.hkdfSplit)(bytes_1.EMPTY_BYTES, this.chainingKey, '');
-        const [writeKey, readKey] = await Promise.all([
-            (0, _crypto_1.importAesGcmKey)(writeKeyRaw, ['encrypt']),
-            (0, _crypto_1.importAesGcmKey)(readKeyRaw, ['decrypt'])
-        ]);
+    finish() {
+        const [writeKey, readKey] = (0, _crypto_1.hkdfSplit)(bytes_1.EMPTY_BYTES, this.chainingKey, bytes_1.EMPTY_BYTES);
         this.handshakeHash = bytes_1.EMPTY_BYTES;
         this.chainingKey = bytes_1.EMPTY_BYTES;
         this.cipherKey = null;

package/dist/transport/noise/WaNoiseSession.js

@@ -51,7 +51,6 @@ function buildRoutingInfoPrefix(routingInfo) {
 class WaNoiseSession {
     constructor(sendWire, logger = new ConsoleLogger_1.ConsoleLogger('info')) {
         this.writeChain = Promise.resolve();
-        this.readChain = Promise.resolve();
         this.frameCodec = null;
         this.handshakeInbox = [];
         this.handshakeInboxHead = 0;
@@ -84,16 +83,16 @@ class WaNoiseSession {
         const verifyCertificates = config.verifyCertificateChain !== false;
         this.trustedRootCa = config.trustedRootCa;
         if (config.serverStaticKey && config.serverStaticKey.length === 32) {
-            this.logger.info('noise session attempting resume handshake (IK)');
+            this.logger.debug('noise session attempting resume handshake (IK)');
             this.noiseSocket = await this.resumeHandshake(config.serverStaticKey, config.clientStaticKeyPair, ephemeralKeyPair, payload, protocolHeader, verifyCertificates);
             await this.decodeBufferedPostHandshakeFrames();
-            this.logger.info('noise session established via resume/full fallback path');
+            this.logger.info('noise session established', { mode: 'resume_or_fallback' });
             return;
         }
-        this.logger.info('noise session starting full handshake (XX)');
+        this.logger.debug('noise session starting full handshake (XX)');
         this.noiseSocket = await this.fullHandshake(config.clientStaticKeyPair, ephemeralKeyPair, payload, protocolHeader, verifyCertificates);
         await this.decodeBufferedPostHandshakeFrames();
-        this.logger.info('noise session established via full handshake');
+        this.logger.info('noise session established', { mode: 'full' });
     }
     encryptFrame(frame) {
         const socket = this.noiseSocket;
@@ -101,19 +100,11 @@ class WaNoiseSession {
         if (!socket || !codec) {
             return Promise.reject(new Error('noise session is not established'));
         }
-        let encryptPromise;
-        try {
-            encryptPromise = socket.encrypt(socket.reserveWriteNonce(), frame);
-        }
-        catch (error) {
-            return Promise.reject(error);
-        }
-        const result = this.writeChain
-            .then(() => encryptPromise)
-            .then((encrypted) => codec.encodeFrame(encrypted));
+        const result = this.writeChain.then(() => codec.encodeFrame(socket.encrypt(frame)));
         this.writeChain = result.then(() => { }, () => { });
         return result;
     }
+    // eslint-disable-next-line @typescript-eslint/require-await
     async pushWireChunk(chunk) {
         const codec = this.frameCodec;
         if (!codec) {
@@ -142,11 +133,7 @@ class WaNoiseSession {
             return out;
         }
         if (frames.length > 0) {
-            const decryptBatch = this.decryptFramesBatch(this.noiseSocket, frames);
-            this.readChain = this.readChain
-                .then(() => decryptBatch)
-                .then(() => { }, () => { });
-            const decrypted = await decryptBatch;
+            const decrypted = this.decryptFramesBatch(this.noiseSocket, frames);
             for (let i = 0; i < decrypted.length; i++) {
                 out.push(decrypted[i]);
             }
@@ -164,15 +151,12 @@ class WaNoiseSession {
             rejecter(closeError);
         }
     }
-    async decryptFramesBatch(socket, frames) {
-        if (frames.length === 1) {
-            return [await socket.decrypt(socket.reserveReadNonce(), frames[0])];
-        }
-        const pending = new Array(frames.length);
+    decryptFramesBatch(socket, frames) {
+        const out = new Array(frames.length);
         for (let i = 0; i < frames.length; i++) {
-            pending[i] = socket.decrypt(socket.reserveReadNonce(), frames[i]);
+            out[i] = socket.decrypt(frames[i]);
         }
-        return Promise.all(pending);
+        return out;
     }
     reset() {
         this.logger.trace('noise session reset');
@@ -186,7 +170,6 @@ class WaNoiseSession {
         this.serverStaticKey = null;
         this.trustedRootCa = undefined;
         this.writeChain = Promise.resolve();
-        this.readChain = Promise.resolve();
     }
     getServerStaticKey() {
         return this.serverStaticKey;
@@ -194,8 +177,8 @@ class WaNoiseSession {
     async fullHandshake(clientStaticKeyPair, ephemeralKeyPair, payload, protocolHeader, verifyCertificates) {
         this.logger.trace('noise full handshake: send client hello');
         const handshake = new WaNoiseHandshake_1.WaNoiseHandshake();
-        await handshake.start(constants_2.NOISE_XX_NAME, protocolHeader);
-        await handshake.authenticate(ephemeralKeyPair.pubKey);
+        handshake.start(constants_2.NOISE_XX_NAME, protocolHeader);
+        handshake.authenticate(ephemeralKeyPair.pubKey);
         const clientHello = _proto_1.proto.HandshakeMessage.encode({
             clientHello: {
                 ephemeral: ephemeralKeyPair.pubKey
@@ -209,23 +192,23 @@ class WaNoiseSession {
         if (resumeResult.socket) {
             return resumeResult.socket;
         }
-        this.logger.info('noise resume handshake fallback to XX');
+        this.logger.debug('noise resume handshake fallback to XX');
         return this.resumeHandshakeWithFallback(clientStaticKeyPair, ephemeralKeyPair, payload, protocolHeader, resumeResult.serverHelloFrame, verifyCertificates);
     }
     async tryResumeHandshakeWithIk(serverStaticKey, clientStaticKeyPair, ephemeralKeyPair, payload, protocolHeader) {
         this.logger.trace('noise resume handshake: send IK client hello');
         const handshake = new WaNoiseHandshake_1.WaNoiseHandshake();
-        await handshake.start(constants_2.NOISE_IK_NAME, protocolHeader);
-        await handshake.authenticate(serverStaticKey);
-        await handshake.authenticate(ephemeralKeyPair.pubKey);
+        handshake.start(constants_2.NOISE_IK_NAME, protocolHeader);
+        handshake.authenticate(serverStaticKey);
+        handshake.authenticate(ephemeralKeyPair.pubKey);
         const [agreement1, agreement2] = await Promise.all([
             _crypto_1.X25519.scalarMult(ephemeralKeyPair.privKey, serverStaticKey),
             _crypto_1.X25519.scalarMult(clientStaticKeyPair.privKey, serverStaticKey)
         ]);
-        await handshake.mixIntoKey(agreement1);
-        const encryptedClientStatic = await handshake.encrypt(clientStaticKeyPair.pubKey);
-        await handshake.mixIntoKey(agreement2);
-        const encryptedPayload = await handshake.encrypt(payload);
+        handshake.mixIntoKey(agreement1);
+        const encryptedClientStatic = handshake.encrypt(clientStaticKeyPair.pubKey);
+        handshake.mixIntoKey(agreement2);
+        const encryptedPayload = handshake.encrypt(payload);
         const clientHello = _proto_1.proto.HandshakeMessage.encode({
             clientHello: {
                 ephemeral: ephemeralKeyPair.pubKey,
@@ -249,22 +232,22 @@ class WaNoiseSession {
             throw new Error('noise resume handshake missing certificate payload');
         }
         const serverEphemeral = serverHello.ephemeral;
-        await handshake.authenticate(serverEphemeral);
+        handshake.authenticate(serverEphemeral);
         const [dh1, dh2] = await Promise.all([
             _crypto_1.X25519.scalarMult(ephemeralKeyPair.privKey, serverEphemeral),
             _crypto_1.X25519.scalarMult(clientStaticKeyPair.privKey, serverEphemeral)
         ]);
-        await handshake.mixIntoKey(dh1);
-        await handshake.mixIntoKey(dh2);
-        await handshake.decrypt(serverHello.payload);
+        handshake.mixIntoKey(dh1);
+        handshake.mixIntoKey(dh2);
+        handshake.decrypt(serverHello.payload);
         this.serverStaticKey = serverStaticKey;
-        this.logger.info('noise resume handshake successful without fallback');
-        return { socket: await handshake.finish(), serverHelloFrame: null };
+        this.logger.debug('noise resume handshake successful without fallback');
+        return { socket: handshake.finish(), serverHelloFrame: null };
     }
     async resumeHandshakeWithFallback(clientStaticKeyPair, ephemeralKeyPair, payload, protocolHeader, serverHelloFrame, verifyCertificates) {
         const fallback = new WaNoiseHandshake_1.WaNoiseHandshake();
-        await fallback.start(constants_2.NOISE_XX_FALLBACK_NAME, protocolHeader);
-        await fallback.authenticate(ephemeralKeyPair.pubKey);
+        fallback.start(constants_2.NOISE_XX_FALLBACK_NAME, protocolHeader);
+        fallback.authenticate(ephemeralKeyPair.pubKey);
         return this.continueFullHandshake(fallback, serverHelloFrame, clientStaticKeyPair, ephemeralKeyPair, payload, verifyCertificates);
     }
     async continueFullHandshake(handshake, serverHelloFrame, clientStaticKeyPair, ephemeralKeyPair, payload, verifyCertificates) {
@@ -275,19 +258,19 @@ class WaNoiseSession {
             throw new Error('noise full handshake missing server hello fields');
         }
         const serverEphemeral = serverHello.ephemeral;
-        await handshake.authenticate(serverEphemeral);
-        await handshake.mixIntoKey(await _crypto_1.X25519.scalarMult(ephemeralKeyPair.privKey, serverEphemeral));
-        const serverStatic = await handshake.decrypt(serverHello.static);
-        await handshake.mixIntoKey(await _crypto_1.X25519.scalarMult(ephemeralKeyPair.privKey, serverStatic));
-        const certificate = await handshake.decrypt(serverHello.payload);
+        handshake.authenticate(serverEphemeral);
+        handshake.mixIntoKey(await _crypto_1.X25519.scalarMult(ephemeralKeyPair.privKey, serverEphemeral));
+        const serverStatic = handshake.decrypt(serverHello.static);
+        handshake.mixIntoKey(await _crypto_1.X25519.scalarMult(ephemeralKeyPair.privKey, serverStatic));
+        const certificate = handshake.decrypt(serverHello.payload);
         if (verifyCertificates) {
             await (0, WaNoiseCert_1.verifyNoiseCertificateChain)(certificate, serverStatic, this.trustedRootCa);
             this.logger.trace('noise certificate chain verified');
         }
         this.serverStaticKey = serverStatic;
-        const encryptedClientStatic = await handshake.encrypt(clientStaticKeyPair.pubKey);
-        await handshake.mixIntoKey(await _crypto_1.X25519.scalarMult(clientStaticKeyPair.privKey, serverEphemeral));
-        const encryptedPayload = await handshake.encrypt(payload);
+        const encryptedClientStatic = handshake.encrypt(clientStaticKeyPair.pubKey);
+        handshake.mixIntoKey(await _crypto_1.X25519.scalarMult(clientStaticKeyPair.privKey, serverEphemeral));
+        const encryptedPayload = handshake.encrypt(payload);
         const clientFinish = _proto_1.proto.HandshakeMessage.encode({
             clientFinish: {
                 static: encryptedClientStatic,
@@ -350,6 +333,7 @@ class WaNoiseSession {
             throw (0, primitives_1.toError)(error);
         });
     }
+    // eslint-disable-next-line @typescript-eslint/require-await
     async decodeBufferedPostHandshakeFrames() {
         if (!this.noiseSocket || this.handshakeInboxHead >= this.handshakeInbox.length) {
             return;
@@ -360,11 +344,7 @@ class WaNoiseSession {
         const start = this.handshakeInboxHead;
         const frames = this.handshakeInbox.slice(start);
         if (frames.length > 0) {
-            const decryptBatch = this.decryptFramesBatch(this.noiseSocket, frames);
-            this.readChain = this.readChain
-                .then(() => decryptBatch)
-                .then(() => { }, () => { });
-            const decrypted = await decryptBatch;
+            const decrypted = this.decryptFramesBatch(this.noiseSocket, frames);
             for (let i = 0; i < decrypted.length; i++) {
                 this.pendingDecryptedFrames.push(decrypted[i]);
             }

package/dist/transport/noise/WaNoiseSocket.js

@@ -1,25 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WaNoiseSocket = void 0;
+const node_crypto_1 = require("node:crypto");
 const _crypto_1 = require("../../crypto/index.js");
+/**
+ * Post-handshake symmetric channel: applies AES-GCM with per-direction
+ * 12-byte nonces (counter in the trailing 4 bytes) using a per-instance
+ * scratch buffer to avoid allocations on the hot path.
+ */
 class WaNoiseSocket {
     constructor(encryptKey, decryptKey) {
-        this.encryptKey = encryptKey;
-        this.decryptKey = decryptKey;
+        this.writeNonceScratch = new Uint8Array(12);
+        this.readNonceScratch = new Uint8Array(12);
+        this.encryptKey = (0, node_crypto_1.createSecretKey)(encryptKey);
+        this.decryptKey = (0, node_crypto_1.createSecretKey)(decryptKey);
         this.writeCounter = 0;
         this.readCounter = 0;
     }
-    reserveWriteNonce() {
-        return (0, _crypto_1.buildNonce)(this.writeCounter++);
+    /** Encrypts an outgoing `frame` with the next write nonce; advances the write counter. */
+    encrypt(frame, additionalData) {
+        (0, _crypto_1.writeNonceCounter)(this.writeNonceScratch, this.writeCounter++);
+        return (0, _crypto_1.aesGcmEncrypt)(this.encryptKey, this.writeNonceScratch, frame, additionalData);
     }
-    encrypt(nonce, frame, additionalData) {
-        return (0, _crypto_1.aesGcmEncrypt)(this.encryptKey, nonce, frame, additionalData);
-    }
-    reserveReadNonce() {
-        return (0, _crypto_1.buildNonce)(this.readCounter++);
-    }
-    decrypt(nonce, frame, additionalData) {
-        return (0, _crypto_1.aesGcmDecrypt)(this.decryptKey, nonce, frame, additionalData);
+    /** Decrypts an incoming `frame` with the next read nonce; advances the read counter. */
+    decrypt(frame, additionalData) {
+        (0, _crypto_1.writeNonceCounter)(this.readNonceScratch, this.readCounter++);
+        return (0, _crypto_1.aesGcmDecrypt)(this.decryptKey, this.readNonceScratch, frame, additionalData);
     }
 }
 exports.WaNoiseSocket = WaNoiseSocket;

package/dist/transport/noise/constants.js

@@ -1,8 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ROOT_CA_PUBLIC_KEY_HEX = exports.ROOT_CA_SERIAL = exports.NOISE_XX_FALLBACK_NAME = exports.NOISE_IK_NAME = exports.NOISE_XX_NAME = exports.WA_PROTO_HEADER = exports.DEFAULT_VERSION_BASE = void 0;
+exports.ROOT_CA_PUBLIC_KEY_HEX = exports.ROOT_CA_SERIAL = exports.NOISE_XX_FALLBACK_NAME = exports.NOISE_IK_NAME = exports.NOISE_XX_NAME = exports.WA_PROTO_HEADER = void 0;
 const bytes_1 = require("../../util/bytes");
-exports.DEFAULT_VERSION_BASE = '2.3000.1034748654';
 exports.WA_PROTO_HEADER = new Uint8Array([87, 65, 6, 3]);
 exports.NOISE_XX_NAME = bytes_1.TEXT_ENCODER.encode('Noise_XX_25519_AESGCM_SHA256\0\0\0\0');
 exports.NOISE_IK_NAME = bytes_1.TEXT_ENCODER.encode('Noise_IK_25519_AESGCM_SHA256\0\0\0\0');

package/dist/transport/proxy.js

@@ -5,27 +5,32 @@ exports.isProxyAgent = isProxyAgent;
 exports.isProxyTransport = isProxyTransport;
 exports.toProxyDispatcher = toProxyDispatcher;
 exports.toProxyAgent = toProxyAgent;
+/** Type guard for an undici-style proxy dispatcher (has `dispatch` method). */
 function isProxyDispatcher(value) {
     return (typeof value === 'object' &&
         value !== null &&
         'dispatch' in value &&
         typeof value.dispatch === 'function');
 }
+/** Type guard for a Node http.Agent-style proxy (has `addRequest` method). */
 function isProxyAgent(value) {
     return (typeof value === 'object' &&
         value !== null &&
         'addRequest' in value &&
         typeof value.addRequest === 'function');
 }
+/** Type guard accepting either {@link isProxyDispatcher} or {@link isProxyAgent} shapes. */
 function isProxyTransport(value) {
     return isProxyDispatcher(value) || isProxyAgent(value);
 }
+/** Narrows `proxy` to {@link WaProxyDispatcher} or returns `undefined`. */
 function toProxyDispatcher(proxy) {
     if (!proxy || !isProxyDispatcher(proxy)) {
         return undefined;
     }
     return proxy;
 }
+/** Narrows `proxy` to {@link WaProxyAgent} or returns `undefined`. */
 function toProxyAgent(proxy) {
     if (!proxy || !isProxyAgent(proxy)) {
         return undefined;

package/dist/transport/stream/parse.js

@@ -7,7 +7,6 @@ const constants_1 = require("../../protocol/constants");
 const helpers_1 = require("../node/helpers");
 const bytes_1 = require("../../util/bytes");
 const primitives_1 = require("../../util/primitives");
-const DIGITS_ONLY_RE = /^\d+$/;
 function parseStreamControlNode(node) {
     if (node.tag === constants_1.WA_STREAM_SIGNALING.XML_STREAM_END_TAG) {
         return { kind: 'xmlstreamend' };
@@ -21,12 +20,9 @@ function parseStreamControlNode(node) {
             ? { kind: 'stream_error_replaced' }
             : { kind: 'stream_error_device_removed' };
     }
-    const codeStr = node.attrs.code;
-    if (codeStr && DIGITS_ONLY_RE.test(codeStr)) {
-        const code = Number(codeStr);
-        if (Number.isSafeInteger(code)) {
-            return { kind: 'stream_error_code', code };
-        }
+    const code = (0, primitives_1.parseOptionalInt)(node.attrs.code);
+    if (code !== undefined) {
+        return { kind: 'stream_error_code', code };
     }
     const ackNode = (0, helpers_1.findNodeChild)(node, constants_1.WA_STREAM_SIGNALING.ACK_TAG);
     if (ackNode) {

package/dist/transport/wa-web-version-fetcher.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchLatestWaWebVersion = fetchLatestWaWebVersion;
+const proxy_1 = require("./proxy");
+const primitives_1 = require("../util/primitives");
+const DEFAULT_USER_AGENT = 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36';
+const DEFAULT_TIMEOUT_MS = 10000;
+const SW_JS_URL = 'https://web.whatsapp.com/sw.js';
+const CLIENT_REVISION_PATTERN = /\\?"client_revision\\?":\s*(\d+)/;
+/**
+ * Fetches the current WhatsApp Web `client_revision` from the public
+ * `sw.js` served by the WhatsApp Web frontend and assembles a
+ * `2.3000.x` version string suitable for `WaClientOptions.version`.
+ *
+ * Use this when the library's hardcoded default starts being rejected by
+ * the server with HTTP 405 / `failure_client_too_old`, and you need to
+ * refresh the version without waiting for a library bump.
+ *
+ * Network failures and parse errors throw; wrap in a `try`/`catch` and
+ * fall back to the hardcoded default.
+ *
+ * @example
+ * const latest = await fetchLatestWaWebVersion()
+ * const client = new WaClient({ store, sessionId, version: latest.version })
+ */
+async function fetchLatestWaWebVersion(options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const dispatcher = (0, proxy_1.toProxyDispatcher)(options.proxy);
+    const fetchImpl = options.fetch ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error(`fetch latest wa-web version timed out after ${timeoutMs}ms`)), timeoutMs);
+    timer.unref?.();
+    let onExternalAbort = null;
+    const externalSignal = options.signal;
+    if (externalSignal) {
+        if (externalSignal.aborted) {
+            controller.abort(externalSignal.reason);
+        }
+        else {
+            onExternalAbort = () => controller.abort(externalSignal.reason);
+            externalSignal.addEventListener('abort', onExternalAbort, { once: true });
+        }
+    }
+    try {
+        const headers = {
+            'sec-fetch-site': 'none',
+            'user-agent': options.userAgent ?? DEFAULT_USER_AGENT
+        };
+        if (options.headers) {
+            for (const key in options.headers) {
+                headers[key.toLowerCase()] = options.headers[key];
+            }
+        }
+        const init = {
+            method: 'GET',
+            headers,
+            signal: controller.signal
+        };
+        if (dispatcher) {
+            // dispatcher is a non-standard undici-only extension to RequestInit
+            ;
+            init.dispatcher = dispatcher;
+        }
+        let response;
+        try {
+            response = await fetchImpl(SW_JS_URL, init);
+        }
+        catch (error) {
+            throw new Error(`failed to fetch sw.js: ${(0, primitives_1.toError)(error).message}`);
+        }
+        if (!response.ok) {
+            throw new Error(`failed to fetch sw.js: http ${response.status}`);
+        }
+        const body = await response.text();
+        const match = CLIENT_REVISION_PATTERN.exec(body);
+        if (!match?.[1]) {
+            throw new Error('client_revision not found in sw.js response');
+        }
+        const revision = Number.parseInt(match[1], 10);
+        if (!Number.isSafeInteger(revision) || revision <= 0) {
+            throw new Error(`invalid client_revision in sw.js: ${match[1]}`);
+        }
+        return {
+            version: `2.3000.${revision}`,
+            parts: [2, 3000, revision]
+        };
+    }
+    finally {
+        clearTimeout(timer);
+        if (externalSignal && onExternalAbort) {
+            externalSignal.removeEventListener('abort', onExternalAbort);
+        }
+    }
+}

package/dist/types/appstate/constants.d.ts

@@ -10,6 +10,6 @@ export declare const APP_STATE_MAC_OCTET_LENGTH = 8;
 export declare const APP_STATE_IV_LENGTH = 16;
 export declare const APP_STATE_LT_HASH_SIZE = 128;
 export declare const APP_STATE_POINT_SIZE = 2;
-export declare const APP_STATE_EMPTY_LT_HASH: Uint8Array<ArrayBuffer>;
+export declare const APP_STATE_EMPTY_LT_HASH: Readonly<Uint8Array>;
 export declare const APP_STATE_DEFAULT_COLLECTION_VERSION = 0;
 export declare const APP_STATE_DEFAULT_COLLECTIONS: readonly AppStateCollectionName[];

package/dist/types/appstate/{WaAppStateCrypto.d.ts → crypto/WaAppStateCrypto.d.ts}

@@ -1,11 +1,10 @@
-import { type CryptoKey } from '../crypto/core/primitives';
-import { type Proto } from '..';
+import { type Proto } from '../..';
 interface WaAppStateDerivedKeys {
-    readonly indexHmacKey: CryptoKey;
-    readonly valueEncryptionAesKey: CryptoKey;
-    readonly valueMacHmacKey: CryptoKey;
-    readonly snapshotMacHmacKey: CryptoKey;
-    readonly patchMacHmacKey: CryptoKey;
+    readonly indexHmacKey: Uint8Array;
+    readonly valueEncryptionAesKey: Uint8Array;
+    readonly valueMacHmacKey: Uint8Array;
+    readonly snapshotMacHmacKey: Uint8Array;
+    readonly patchMacHmacKey: Uint8Array;
 }
 interface WaAppStateEncryptedMutation {
     readonly indexMac: Uint8Array;
@@ -19,15 +18,27 @@ interface WaAppStateDecryptedMutation {
     readonly indexMac: Uint8Array;
     readonly valueMac: Uint8Array;
 }
+/**
+ * Implements the app-state mutation cryptography: HKDF key derivation (with
+ * a bounded LRU cache), per-mutation encrypt/decrypt, snapshot/patch MAC
+ * generation, and the LT-hash arithmetic used to track collection state.
+ */
 export declare class WaAppStateCrypto {
     private readonly derivedKeysCache;
     private readonly derivedKeysCacheMaxSize;
     private readonly skipMacVerification;
     constructor(derivedKeysCacheMaxSize?: number, skipMacVerification?: boolean);
     get isMacVerificationSkipped(): boolean;
+    /** Empties the derived-keys LRU cache (e.g. after a session reset). */
     clearCache(): void;
-    deriveKeys(keyData: Uint8Array): Promise<WaAppStateDerivedKeys>;
-    generateIndexMac(indexHmacKey: CryptoKey, indexBytes: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Derives the index/value/snapshot/patch keys from an app-state sync key.
+     * Cached by base64 of `keyData` (LRU-bounded).
+     */
+    deriveKeys(keyData: Uint8Array): WaAppStateDerivedKeys;
+    /** Computes the HMAC-SHA-256 index MAC over `indexBytes`. */
+    generateIndexMac(indexHmacKey: Uint8Array, indexBytes: Uint8Array): Uint8Array;
+    /** Encrypts a single mutation value with AES-CBC + HMAC value-MAC. */
     encryptMutation(args: {
         readonly operation: number;
         readonly keyId: Uint8Array;
@@ -37,6 +48,7 @@ export declare class WaAppStateCrypto {
         readonly version: number;
         readonly iv?: Uint8Array;
     }): Promise<WaAppStateEncryptedMutation>;
+    /** Verifies and decrypts a single app-state mutation. */
     decryptMutation(args: {
         readonly operation: number;
         readonly keyId: Uint8Array;
@@ -44,10 +56,15 @@ export declare class WaAppStateCrypto {
         readonly indexMac: Uint8Array;
         readonly valueBlob: Uint8Array;
     }): Promise<WaAppStateDecryptedMutation>;
+    /** Generates the HMAC-SHA-512 snapshot MAC over the LT-hash + version + collection name. */
     generateSnapshotMac(keyData: Uint8Array, ltHash: Uint8Array, version: number, collectionName: string): Promise<Uint8Array>;
+    /** Generates the HMAC-SHA-512 patch MAC binding mutations to a collection version. */
     generatePatchMac(keyData: Uint8Array, snapshotMac: Uint8Array, valueMacs: readonly Uint8Array[], version: number, collectionName: string): Promise<Uint8Array>;
+    /** Adds value MACs into the running LT-hash digest for a collection. */
     ltHashAdd(base: Uint8Array, addValues: readonly Uint8Array[]): Promise<Uint8Array>;
+    /** Removes value MACs from the running LT-hash digest (for `remove` operations). */
     ltHashSubtract(base: Uint8Array, removeValues: readonly Uint8Array[]): Promise<Uint8Array>;
+    /** Combined subtract+add LT-hash update used when a key's value MAC changes in place. */
     ltHashSubtractThenAdd(base: Uint8Array, addValues: readonly Uint8Array[], removeValues: readonly Uint8Array[]): Promise<{
         readonly hash: Uint8Array;
         readonly subtractResult: Uint8Array;