zapo-js 0.2.0 → 1.0.0

package/dist/esm/transport/node/mex/client.js

@@ -0,0 +1,105 @@
+import { WA_MEX_PERSIST_IDS } from '../../../mex.js';
+import { WA_DEFAULTS, WA_IQ_TYPES, WA_NODE_TAGS, WA_XMLNS } from '../../../protocol/constants.js';
+import { decodeNodeContentUtf8OrBytes, findNodeChild } from '../../node/helpers.js';
+import { decodeMexArgoResponse, isMexArgoDecoderAvailable } from '../../node/mex/argo-decoder.js';
+import { assertIqResult } from '../../node/query.js';
+import { TEXT_DECODER } from '../../../util/bytes.js';
+import { toError } from '../../../util/primitives.js';
+const MEX_DEFAULT_TIMEOUT_MS = 32000;
+/**
+ * Typed wrapper around `dispatchMexQuery` that resolves persist IDs from the
+ * generated `WA_MEX_PERSIST_IDS` table. The op key constrains the `variables`
+ * shape via `WaMexOperationVariables` and defaults the response to
+ * `WaMexOperationResponses[K] | null` (the response tree the extractor walked
+ * from the Relay `operation.selections`; leaves are `unknown` since Relay
+ * strips scalar types at codegen).
+ */
+export async function runMexQuery(socket, opKey, variables) {
+    const persist = WA_MEX_PERSIST_IDS[opKey];
+    if (!persist) {
+        throw new Error(`mex/${String(opKey)} persist IDs not found`);
+    }
+    const { data } = await dispatchMexQuery(socket, {
+        docId: persist.docId,
+        clientDocId: persist.clientDocId,
+        opName: opKey,
+        variables: variables
+    });
+    return data;
+}
+export async function dispatchMexQuery(socket, args) {
+    const body = JSON.stringify({
+        queryId: args.clientDocId,
+        variables: args.variables
+    });
+    const node = {
+        tag: WA_NODE_TAGS.IQ,
+        attrs: {
+            ...(args.iqId ? { id: args.iqId } : {}),
+            to: WA_DEFAULTS.HOST_DOMAIN,
+            type: WA_IQ_TYPES.GET,
+            xmlns: WA_XMLNS.MEX
+        },
+        content: [
+            {
+                tag: 'query',
+                attrs: { query_id: args.docId },
+                content: body
+            }
+        ]
+    };
+    const response = await socket.query(node, args.timeoutMs ?? MEX_DEFAULT_TIMEOUT_MS);
+    assertIqResult(response, `mex/${args.opName}`);
+    const data = await parseMexResultPayload(response, args.opName);
+    return { raw: response, data };
+}
+async function parseMexResultPayload(node, opName) {
+    const result = findNodeChild(node, 'result');
+    if (!result) {
+        throw new Error(`mex/${opName} response missing <result>`);
+    }
+    const format = result.attrs.format ?? 'json';
+    const rawBytes = decodeNodeContentUtf8OrBytes(result.content, `mex/${opName}/result`);
+    if (format === 'argo') {
+        if (!(await isMexArgoDecoderAvailable())) {
+            throw new Error(`mex/${opName} argo response received but 'argo-codec' not installed; ${rawBytes.length}B; ` +
+                `strings: ${extractVisibleStrings(rawBytes)}`);
+        }
+        let decoded;
+        try {
+            decoded = await decodeMexArgoResponse(rawBytes);
+        }
+        catch (error) {
+            throw new Error(`mex/${opName} argo decode failed: ${toError(error).message}; ` +
+                `${rawBytes.length}B; strings: ${extractVisibleStrings(rawBytes)}`);
+        }
+        if (decoded.errors.length > 0) {
+            const summary = decoded.errors
+                .map((e) => {
+                const code = e.extensions?.error_code ?? e.extensions?.code ?? '?';
+                const sev = e.extensions?.severity;
+                return `${code}${sev ? `/${String(sev)}` : ''}: ${e.message} @${e.path ?? ''}`;
+            })
+                .join('; ');
+            throw new Error(`mex/${opName} errors: ${summary}`);
+        }
+        return decoded.data;
+    }
+    return extractGraphQlData(JSON.parse(TEXT_DECODER.decode(rawBytes)), opName);
+}
+function extractVisibleStrings(bytes) {
+    return TEXT_DECODER.decode(bytes)
+        .replace(/[\x00-\x1f\x7f-\xff]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function extractGraphQlData(payload, opName) {
+    const json = (payload ?? {});
+    if (json.errors && json.errors.length > 0) {
+        const summary = json.errors
+            .map((e) => `${e.extensions?.error_code ?? '?'}: ${e.message ?? '?'} @${(e.path ?? []).join('.')}`)
+            .join('; ');
+        throw new Error(`mex/${opName} errors: ${summary}`);
+    }
+    return json.data ?? null;
+}

package/dist/esm/transport/node/query.js

@@ -1,6 +1,11 @@
 import { WA_IQ_TYPES, WA_NODE_TAGS } from '../../protocol/constants.js';
 import { findNodeChild } from '../node/helpers.js';
 import { toError } from '../../util/primitives.js';
+/**
+ * Builds an IQ stanza (`<iq type="get|set" to="..." xmlns="..."/>`) with the
+ * given children/attrs. The caller is responsible for the `id` attribute
+ * (the transport assigns one automatically when omitted).
+ */
 export function buildIqNode(type, to, xmlns, content, attrs = {}) {
     return {
         tag: WA_NODE_TAGS.IQ,
@@ -13,6 +18,10 @@ export function buildIqNode(type, to, xmlns, content, attrs = {}) {
         ...(content !== undefined ? { content } : {})
     };
 }
+/**
+ * Reads the standard error envelope from an IQ stanza, returning the string
+ * `code`/`text` and (when parseable) the numeric `code`.
+ */
 export function parseIqError(node) {
     const errorNode = findNodeChild(node, WA_NODE_TAGS.ERROR);
     const code = errorNode?.attrs.code ?? node.attrs.type ?? 'unknown';
@@ -24,6 +33,10 @@ export function parseIqError(node) {
         ...(Number.isSafeInteger(parsedCode) ? { numericCode: parsedCode } : {})
     };
 }
+/**
+ * Throws when `node` is not a successful IQ result, embedding the parsed
+ * error envelope and the `context` label in the message.
+ */
 export function assertIqResult(node, context) {
     if (node.tag !== WA_NODE_TAGS.IQ) {
         throw new Error(`${context} returned non-iq node (${node.tag})`);
@@ -34,6 +47,10 @@ export function assertIqResult(node, context) {
     const error = parseIqError(node);
     throw new Error(`${context} iq failed (${error.code}: ${error.text})`);
 }
+/**
+ * Wraps `query(...)` so failures are logged with a `context` label and the
+ * stanza's tag/id/type, then rethrown. Used by every coordinator's IQ call.
+ */
 export async function queryWithContext(query, logger, context, node, timeoutMs, contextData = {}) {
     try {
         return await query(node, timeoutMs);

package/dist/esm/transport/node/usync.js

@@ -3,3 +3,15 @@ export function createUsyncSidGenerator() {
     const generatorPromise = createNodeIdGenerator();
     return async () => (await generatorPromise).next();
 }
+export function logUsyncProtocolErrors(envelope, logger, context) {
+    for (const protocol of Object.keys(envelope.errors)) {
+        const err = envelope.errors[protocol];
+        logger.warn('usync protocol error', {
+            context,
+            protocol,
+            code: err.code,
+            text: err.text,
+            backoffSeconds: err.backoffSeconds
+        });
+    }
+}

package/dist/esm/transport/noise/WaClientPayload.js

@@ -1,8 +1,8 @@
 import { randomUUID } from 'node:crypto';
 import { md5Bytes } from '../../crypto/core/primitives.js';
 import { proto } from '../../proto.js';
-import { DEFAULT_VERSION_BASE } from '../noise/constants.js';
-import { intToBytes, toBytesView } from '../../util/bytes.js';
+import { intToBytes } from '../../util/bytes.js';
+import { WA_VERSION } from '../../version-spec.js';
 function parseVersion(versionBase) {
     const [p = '2', s = '3000', t = '0'] = versionBase.split('.');
     const primary = Number.parseInt(p, 10);
@@ -15,13 +15,20 @@ function parseVersion(versionBase) {
     }
     return { primary, secondary, tertiary };
 }
+let cachedLocale = null;
 function resolveLocale() {
+    // The first `Intl.DateTimeFormat()` call triggers V8's lazy ICU init
+    // (tens of ms). The process locale does not change at runtime, so
+    // memoize after the first resolve.
+    if (cachedLocale !== null)
+        return cachedLocale;
     const locale = Intl.DateTimeFormat().resolvedOptions().locale || 'en-US';
     const [language = 'en', country = 'US'] = locale.split('-');
-    return {
+    cachedLocale = Object.freeze({
         lg: language.toLowerCase(),
         lc: country.toUpperCase()
-    };
+    });
+    return cachedLocale;
 }
 function defaultWebSubPlatform() {
     return proto.ClientPayload.WebInfo.WebSubPlatform.WEB_BROWSER;
@@ -100,12 +107,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 ?? DEFAULT_VERSION_BASE;
+    const versionBase = config.versionBase ?? WA_VERSION;
     const pull = config.pull ?? true;
     return {
         passive: config.passive === true,
@@ -113,10 +121,9 @@ function buildCommonPayload(config, version) {
         connectType: proto.ClientPayload.ConnectType.WIFI_UNKNOWN,
         connectReason: proto.ClientPayload.ConnectReason.USER_ACTIVATED,
         userAgent: config.userAgent ?? defaultUserAgent(versionBase, config.deviceOsDisplayName, version),
-        webInfo: config.webInfo ??
-            {
-                webSubPlatform: defaultWebSubPlatform()
-            }
+        webInfo: config.webInfo ?? {
+            webSubPlatform: defaultWebSubPlatform()
+        }
     };
 }
 export function buildLoginPayload(config) {
@@ -140,20 +147,18 @@ export function buildRegistrationPayload(config) {
     if (!Number.isSafeInteger(signedPreKeyId) || signedPreKeyId <= 0) {
         throw new Error('registration payload requires a valid signedPreKeyId');
     }
-    const versionBase = config.versionBase ?? DEFAULT_VERSION_BASE;
+    const versionBase = config.versionBase ?? WA_VERSION;
     const version = parseVersion(versionBase);
     const common = buildCommonPayload(config, version);
     const devicePairingData = {
-        buildHash: config.buildHash ? toBytesView(config.buildHash) : md5Bytes(versionBase),
-        deviceProps: config.deviceProps
-            ? toBytesView(config.deviceProps)
-            : defaultDeviceProps(versionBase, config, version),
+        buildHash: config.buildHash ?? md5Bytes(versionBase),
+        deviceProps: config.deviceProps ?? defaultDeviceProps(versionBase, config, version),
         eRegid: intToBytes(4, registrationId),
         eKeytype: intToBytes(1, 5),
-        eIdent: toBytesView(config.registrationInfo.identityKeyPair.pubKey),
+        eIdent: config.registrationInfo.identityKeyPair.pubKey,
         eSkeyId: intToBytes(3, signedPreKeyId),
-        eSkeyVal: toBytesView(config.signedPreKey.keyPair.pubKey),
-        eSkeySig: toBytesView(config.signedPreKey.signature)
+        eSkeyVal: config.signedPreKey.keyPair.pubKey,
+        eSkeySig: config.signedPreKey.signature
     };
     return proto.ClientPayload.encode({
         ...common,

package/dist/esm/transport/noise/WaFrameCodec.js

@@ -1,4 +1,4 @@
-import { EMPTY_BYTES, toBytesView } from '../../util/bytes.js';
+import { EMPTY_BYTES } from '../../util/bytes.js';
 const WA_MAX_FRAME_LENGTH = (1 << 24) - 1;
 function frameLength(header) {
     return (header[0] << 16) | (header[1] << 8) | header[2];
@@ -11,7 +11,7 @@ export class WaFrameCodec {
         if (maxFrameLength >= 1 << 24) {
             throw new Error('maxFrameLength must be lower than protocol limit (16777216)');
         }
-        this.introFrame = introFrame && introFrame.length > 0 ? toBytesView(introFrame) : null;
+        this.introFrame = introFrame && introFrame.length > 0 ? introFrame : null;
         this.maxFrameLength = maxFrameLength;
         this.introSent = false;
         this.buffered = EMPTY_BYTES;

package/dist/esm/transport/noise/WaMobileClientPayload.js

@@ -0,0 +1,58 @@
+import { randomUUID } from 'node:crypto';
+import { proto } from '../../proto.js';
+function parseAppVersion(version) {
+    const parts = version.split('.');
+    const at = (i) => {
+        const n = Number(parts[i]);
+        return Number.isFinite(n) ? n : undefined;
+    };
+    return {
+        primary: at(0) ?? 2,
+        secondary: at(1) ?? 0,
+        tertiary: at(2) ?? 0,
+        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.
+ */
+export function buildMobileLoginPayload(config) {
+    if (!Number.isSafeInteger(config.username) || config.username <= 0) {
+        throw new Error('mobile login payload requires a valid numeric username');
+    }
+    const info = config.deviceInfo;
+    const version = parseAppVersion(info.appVersion);
+    const userAgent = {
+        platform: proto.ClientPayload.UserAgent.Platform.ANDROID,
+        releaseChannel: proto.ClientPayload.UserAgent.ReleaseChannel.RELEASE,
+        appVersion: version,
+        mcc: info.mcc ?? '000',
+        mnc: info.mnc ?? '000',
+        osVersion: info.osVersion,
+        manufacturer: info.manufacturer,
+        device: info.device,
+        osBuildNumber: info.osBuildNumber,
+        phoneId: info.phoneId ?? randomUUID(),
+        localeLanguageIso6391: info.localeLanguageIso6391 ?? 'en',
+        localeCountryIso31661Alpha2: info.localeCountryIso31661Alpha2 ?? 'US',
+        deviceType: proto.ClientPayload.UserAgent.DeviceType.PHONE,
+        deviceBoard: info.deviceBoard,
+        deviceModelType: info.deviceModelType
+    };
+    return proto.ClientPayload.encode({
+        passive: config.passive === true,
+        pull: config.pull ?? true,
+        product: proto.ClientPayload.Product.WHATSAPP,
+        connectType: config.connectType ?? proto.ClientPayload.ConnectType.CELLULAR_UNKNOWN,
+        connectReason: config.connectReason ?? proto.ClientPayload.ConnectReason.USER_ACTIVATED,
+        userAgent,
+        username: config.username,
+        device: config.device ?? 0,
+        lidDbMigrated: config.lidDbMigrated === true,
+        pushName: config.pushName,
+        yearClass: config.yearClass,
+        memClass: config.memClass
+    }).finish();
+}

package/dist/esm/transport/noise/WaNoiseCert.js

@@ -1,24 +1,12 @@
-import { Ed25519, toSerializedPubKey } from '../../crypto/index.js';
-import { montgomeryToEdwardsPublic } from '../../crypto/curves/X25519.js';
+import { xeddsaVerify } from '../../crypto/index.js';
 import { proto } from '../../proto.js';
 import { ROOT_CA_PUBLIC_KEY_HEX, ROOT_CA_SERIAL } from '../noise/constants.js';
 import { assertByteLength, decodeProtoBytes, hexToBytes, uint8Equal } from '../../util/bytes.js';
 import { toSafeNumber } from '../../util/primitives.js';
-async function verifySignalVariant(serializedPublicKey, message, signatureInput) {
-    const publicKey = toSerializedPubKey(serializedPublicKey);
-    if (signatureInput.length !== 64) {
-        return false;
-    }
-    const signature = new Uint8Array(signatureInput);
-    const lastByte = signature[63];
-    if ((lastByte & 0x60) !== 0) {
-        return false;
-    }
-    const signBit = lastByte & 0x80;
-    signature[63] = lastByte & 0x7f;
-    const edwardsPublicKey = montgomeryToEdwardsPublic(publicKey.subarray(1), signBit);
-    return Ed25519.verify(message, signature, edwardsPublicKey);
-}
+const PRODUCTION_ROOT_CA = {
+    publicKey: hexToBytes(ROOT_CA_PUBLIC_KEY_HEX),
+    serial: ROOT_CA_SERIAL
+};
 function parseNoiseCertificate(certificate) {
     if (!certificate) {
         throw new Error('missing noise certificate');
@@ -38,21 +26,21 @@ function parseNoiseCertificate(certificate) {
         signature: signatureBytes
     };
 }
-function rootPublicKeySerialized() {
-    const raw = hexToBytes(ROOT_CA_PUBLIC_KEY_HEX);
-    return toSerializedPubKey(raw);
-}
-export async function verifyNoiseCertificateChain(certificateChain, serverStatic) {
+/**
+ * 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.
+ */
+export async function verifyNoiseCertificateChain(certificateChain, serverStatic, rootCa = PRODUCTION_ROOT_CA) {
     const chain = proto.CertChain.decode(certificateChain);
     if (!chain.leaf || !chain.intermediate) {
         throw new Error('noise certificate chain is missing leaf/intermediate');
     }
     const intermediate = parseNoiseCertificate(chain.intermediate);
-    if (intermediate.issuerSerial !== ROOT_CA_SERIAL) {
+    if (intermediate.issuerSerial !== rootCa.serial) {
         throw new Error('intermediate certificate issuer mismatch');
     }
-    const rootKey = rootPublicKeySerialized();
-    const validIntermediate = await verifySignalVariant(rootKey, intermediate.details, intermediate.signature);
+    const validIntermediate = await xeddsaVerify(rootCa.publicKey, intermediate.details, intermediate.signature);
     if (!validIntermediate) {
         throw new Error('intermediate certificate signature is invalid');
     }
@@ -60,8 +48,7 @@ export async function verifyNoiseCertificateChain(certificateChain, serverStatic
     if (leaf.issuerSerial !== intermediate.serial) {
         throw new Error('leaf certificate issuer mismatch');
     }
-    const intermediatePublicSerialized = toSerializedPubKey(intermediate.key);
-    const validLeaf = await verifySignalVariant(intermediatePublicSerialized, leaf.details, leaf.signature);
+    const validLeaf = await xeddsaVerify(intermediate.key, leaf.details, leaf.signature);
     if (!validLeaf) {
         throw new Error('leaf certificate signature is invalid');
     }

package/dist/esm/transport/noise/WaNoiseHandshake.js

@@ -1,53 +1,55 @@
-import { aesGcmDecrypt, aesGcmEncrypt, buildNonce, hkdfSplit, importAesGcmKey, sha256 } from '../../crypto/index.js';
+import { aesGcmDecrypt, aesGcmEncrypt, hkdfSplit, sha256, writeNonceCounter } from '../../crypto/index.js';
 import { WaNoiseSocket } from '../noise/WaNoiseSocket.js';
-import { concatBytes, EMPTY_BYTES } from '../../util/bytes.js';
+import { EMPTY_BYTES } from '../../util/bytes.js';
+/**
+ * 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}.
+ */
 export class WaNoiseHandshake {
     constructor() {
+        this.nonceScratch = new Uint8Array(12);
         this.handshakeHash = EMPTY_BYTES;
         this.chainingKey = EMPTY_BYTES;
         this.cipherKey = null;
         this.nonce = 0;
     }
-    async start(protocolName, prologue) {
-        const hashInput = protocolName.length === 32 ? protocolName : await sha256(protocolName);
+    start(protocolName, prologue) {
+        const hashInput = protocolName.length === 32 ? protocolName : sha256(protocolName);
         this.handshakeHash = hashInput;
         this.chainingKey = hashInput;
-        this.cipherKey = await importAesGcmKey(this.handshakeHash, ['encrypt', 'decrypt']);
-        await this.authenticate(prologue);
+        this.cipherKey = this.handshakeHash;
+        this.authenticate(prologue);
     }
-    async authenticate(data) {
-        this.handshakeHash = await sha256(concatBytes([this.handshakeHash, data]));
+    authenticate(data) {
+        this.handshakeHash = sha256([this.handshakeHash, data]);
     }
-    async mixIntoKey(keyMaterial) {
+    mixIntoKey(keyMaterial) {
         this.nonce = 0;
-        const [newChainingKey, nextCipherKey] = await hkdfSplit(keyMaterial, this.chainingKey, '');
+        const [newChainingKey, nextCipherKey] = hkdfSplit(keyMaterial, this.chainingKey, EMPTY_BYTES);
         this.chainingKey = newChainingKey;
-        this.cipherKey = await 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 = buildNonce(this.nonce++);
-        const ciphertext = await aesGcmEncrypt(this.cipherKey, nonce, plaintext, this.handshakeHash);
-        await this.authenticate(ciphertext);
+        writeNonceCounter(this.nonceScratch, this.nonce++);
+        const ciphertext = 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 = buildNonce(this.nonce++);
-        const plaintext = await aesGcmDecrypt(this.cipherKey, nonce, ciphertext, this.handshakeHash);
-        await this.authenticate(ciphertext);
+        writeNonceCounter(this.nonceScratch, this.nonce++);
+        const plaintext = aesGcmDecrypt(this.cipherKey, this.nonceScratch, ciphertext, this.handshakeHash);
+        this.authenticate(ciphertext);
         return plaintext;
     }
-    async finish() {
-        const [writeKeyRaw, readKeyRaw] = await hkdfSplit(EMPTY_BYTES, this.chainingKey, '');
-        const [writeKey, readKey] = await Promise.all([
-            importAesGcmKey(writeKeyRaw, ['encrypt']),
-            importAesGcmKey(readKeyRaw, ['decrypt'])
-        ]);
+    finish() {
+        const [writeKey, readKey] = hkdfSplit(EMPTY_BYTES, this.chainingKey, EMPTY_BYTES);
         this.handshakeHash = EMPTY_BYTES;
         this.chainingKey = EMPTY_BYTES;
         this.cipherKey = null;