zapo-js 0.1.0

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

@@ -0,0 +1,71 @@
+import { CROCKFORD_ALPHABET, PBKDF2_ITERATIONS } from '../pairing/constants.js';
+import { aesCtrDecrypt, aesCtrEncrypt, aesGcmEncrypt, hkdf, importAesGcmKey, pbkdf2DeriveAesCtrKey, randomBytesAsync } from '../../crypto/index.js';
+import { X25519 } from '../../crypto/curves/X25519.js';
+import { WA_PAIRING_KDF_INFO } from '../../protocol/constants.js';
+import { concatBytes, TEXT_ENCODER } from '../../util/bytes.js';
+function bytesToCrockford(bytes) {
+    let bitCount = 0;
+    let value = 0;
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 1) {
+        value = (value << 8) | bytes[i];
+        bitCount += 8;
+        while (bitCount >= 5) {
+            out += CROCKFORD_ALPHABET[(value >>> (bitCount - 5)) & 31];
+            bitCount -= 5;
+        }
+    }
+    if (bitCount > 0) {
+        out += CROCKFORD_ALPHABET[(value << (5 - bitCount)) & 31];
+    }
+    return out;
+}
+export async function createCompanionHello() {
+    const [codeBytes, companionEphemeralKeyPair, salt, counter] = await Promise.all([
+        randomBytesAsync(5),
+        X25519.generateKeyPair(),
+        randomBytesAsync(32),
+        randomBytesAsync(16)
+    ]);
+    const pairingCode = bytesToCrockford(codeBytes);
+    const cipher = await pbkdf2DeriveAesCtrKey(TEXT_ENCODER.encode(pairingCode), salt, PBKDF2_ITERATIONS);
+    const encrypted = await aesCtrEncrypt(cipher, counter, companionEphemeralKeyPair.pubKey);
+    return {
+        pairingCode,
+        companionEphemeralKeyPair,
+        wrappedCompanionEphemeralPub: concatBytes([salt, counter, encrypted])
+    };
+}
+export async function completeCompanionFinish(args) {
+    if (args.wrappedPrimaryEphemeralPub.length <= 48) {
+        throw new Error('invalid wrapped primary payload');
+    }
+    const pairingCipher = await pbkdf2DeriveAesCtrKey(TEXT_ENCODER.encode(args.pairingCode), args.wrappedPrimaryEphemeralPub.subarray(0, 32), PBKDF2_ITERATIONS);
+    const primaryEphemeralPub = await aesCtrDecrypt(pairingCipher, args.wrappedPrimaryEphemeralPub.subarray(32, 48), args.wrappedPrimaryEphemeralPub.subarray(48));
+    if (primaryEphemeralPub.length === 0) {
+        throw new Error('empty primary ephemeral public key');
+    }
+    const sharedEphemeral = await X25519.scalarMult(args.companionEphemeralPrivKey, primaryEphemeralPub);
+    const [bundleSalt, bundleSecret, bundleIv] = await Promise.all([
+        randomBytesAsync(32),
+        randomBytesAsync(32),
+        randomBytesAsync(12)
+    ]);
+    const bundleEncryptionKeyRaw = await hkdf(sharedEphemeral, bundleSalt, WA_PAIRING_KDF_INFO.LINK_CODE_BUNDLE, 32);
+    const bundleEncryptionKey = await importAesGcmKey(bundleEncryptionKeyRaw, ['encrypt']);
+    const plaintextBundle = concatBytes([
+        args.registrationIdentityKeyPair.pubKey,
+        args.primaryIdentityPub,
+        bundleSecret
+    ]);
+    const encryptedBundle = await aesGcmEncrypt(bundleEncryptionKey, bundleIv, plaintextBundle);
+    const wrappedKeyBundle = concatBytes([bundleSalt, bundleIv, encryptedBundle]);
+    const sharedIdentity = await X25519.scalarMult(args.registrationIdentityKeyPair.privKey, args.primaryIdentityPub);
+    const advMaterial = concatBytes([sharedEphemeral, sharedIdentity, bundleSecret]);
+    const advSecret = await hkdf(advMaterial, null, WA_PAIRING_KDF_INFO.ADV_SECRET, 32);
+    return {
+        wrappedKeyBundle,
+        companionIdentityPublic: args.registrationIdentityKeyPair.pubKey,
+        advSecret
+    };
+}

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

@@ -0,0 +1,324 @@
+import { completeCompanionFinish, createCompanionHello } from '../pairing/WaPairingCodeCrypto.js';
+import { randomBytesAsync } from '../../crypto/index.js';
+import { proto } from '../../proto.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/crypto/WaAdvSignature.js';
+import { buildCompanionFinishRequestNode, buildCompanionHelloRequestNode, buildGetCountryCodeRequestNode, buildIqResultNode, buildNotificationAckNode } from '../../transport/node/builders/pairing.js';
+import { decodeNodeContentUtf8OrBytes, findNodeChild, getFirstNodeChild, getNodeChildrenByTag, hasNodeChild } from '../../transport/node/helpers.js';
+import { decodeProtoBytes } from '../../util/base64.js';
+import { concatBytes, TEXT_DECODER, uint8Equal } from '../../util/bytes.js';
+export class WaPairingFlow {
+    constructor(options) {
+        this.opts = options;
+        this.pairingSession = null;
+    }
+    hasPairingSession() {
+        return this.pairingSession !== null;
+    }
+    clearSession() {
+        this.opts.logger.trace('pairing flow session cleared');
+        this.pairingSession = null;
+    }
+    async requestPairingCode(phoneNumber, shouldShowPushNotification = false) {
+        this.opts.logger.info('requesting pairing code', {
+            shouldShowPushNotification
+        });
+        const credentials = this.requireCredentials();
+        const phoneJid = parsePhoneJid(phoneNumber);
+        const [companionHello, refreshedCredentials] = await Promise.all([
+            createCompanionHello(),
+            this.rotateAdvSecret(credentials)
+        ]);
+        const browser = this.opts.device.browser;
+        const browserDisplayName = {
+            chrome: 'Chrome',
+            firefox: 'Firefox',
+            ie: 'IE',
+            opera: 'Opera',
+            safari: 'Safari',
+            edge: 'Edge',
+            chromium: 'Chromium'
+        }[browser.trim().toLowerCase()] ?? browser;
+        const response = await this.opts.socket.query(buildCompanionHelloRequestNode({
+            phoneJid,
+            shouldShowPushNotification,
+            wrappedCompanionEphemeralPub: companionHello.wrappedCompanionEphemeralPub,
+            companionServerAuthKeyPub: refreshedCredentials.noiseKeyPair.pubKey,
+            companionPlatformId: this.opts.device.platform,
+            companionPlatformDisplay: `${browserDisplayName} (${this.opts.device.osDisplayName})`
+        }), WA_DEFAULTS.IQ_TIMEOUT_MS);
+        this.opts.logger.debug('pairing code request response received', {
+            responseTag: response.tag,
+            responseType: response.attrs.type
+        });
+        const linkCodeNode = findNodeChild(response, WA_NODE_TAGS.LINK_CODE_COMPANION_REG);
+        if (!linkCodeNode) {
+            throw new Error('companion hello response missing link_code_companion_reg');
+        }
+        const refNode = findNodeChild(linkCodeNode, WA_NODE_TAGS.LINK_CODE_PAIRING_REF);
+        if (!refNode) {
+            throw new Error('companion hello response missing link_code_pairing_ref');
+        }
+        const ref = decodeNodeContentUtf8OrBytes(refNode.content, 'link_code_pairing_ref');
+        this.pairingSession = {
+            pairingCode: companionHello.pairingCode,
+            phoneJid,
+            ref,
+            createdAtSeconds: Math.floor(Date.now() / 1000),
+            companionEphemeralKeyPair: companionHello.companionEphemeralKeyPair,
+            attempts: 0,
+            finished: false
+        };
+        this.opts.callbacks.emitPairingCode(companionHello.pairingCode);
+        this.opts.logger.info('pairing code emitted', {
+            phoneJid,
+            createdAtSeconds: this.pairingSession.createdAtSeconds
+        });
+        return companionHello.pairingCode;
+    }
+    async fetchPairingCountryCodeIso() {
+        this.opts.logger.trace('fetching pairing country code ISO');
+        const response = await this.opts.socket.query(buildGetCountryCodeRequestNode(), WA_DEFAULTS.IQ_TIMEOUT_MS);
+        const countryCodeNode = findNodeChild(response, WA_NODE_TAGS.COUNTRY_CODE);
+        const iso = countryCodeNode?.attrs.iso;
+        if (!iso) {
+            throw new Error('country_code response is missing iso');
+        }
+        this.opts.logger.debug('pairing country code received', { iso });
+        return iso;
+    }
+    async handleIncomingIqSet(node) {
+        this.opts.logger.trace('pairing flow received iq:set', {
+            id: node.attrs.id,
+            from: node.attrs.from
+        });
+        const firstChild = getFirstNodeChild(node);
+        if (!firstChild) {
+            return false;
+        }
+        if (firstChild.tag === WA_NODE_TAGS.PAIR_DEVICE) {
+            this.opts.logger.debug('handling pair-device stanza', { id: node.attrs.id });
+            await this.handlePairDevice(node, firstChild);
+            return true;
+        }
+        if (firstChild.tag === WA_NODE_TAGS.PAIR_SUCCESS) {
+            this.opts.logger.debug('handling pair-success stanza', { id: node.attrs.id });
+            await this.handlePairSuccess(node, firstChild);
+            return true;
+        }
+        return false;
+    }
+    async handleLinkCodeNotification(node) {
+        const linkCodeNode = findNodeChild(node, WA_NODE_TAGS.LINK_CODE_COMPANION_REG);
+        if (!linkCodeNode) {
+            return false;
+        }
+        this.opts.logger.trace('handling link_code_companion_reg notification', {
+            id: node.attrs.id,
+            stage: linkCodeNode.attrs.stage
+        });
+        await this.opts.socket.sendNode(buildNotificationAckNode(node));
+        const stage = linkCodeNode.attrs.stage;
+        if (stage === WA_SIGNALING.LINK_CODE_STAGE_REFRESH_CODE) {
+            const refNode = findNodeChild(linkCodeNode, WA_NODE_TAGS.LINK_CODE_PAIRING_REF);
+            if (!refNode || !this.pairingSession?.ref) {
+                return true;
+            }
+            const ref = decodeNodeContentUtf8OrBytes(refNode.content, 'refresh_code.link_code_pairing_ref');
+            if (uint8Equal(ref, this.pairingSession.ref)) {
+                this.opts.logger.info('received pairing refresh notification', {
+                    forceManualRefresh: linkCodeNode.attrs.force_manual_refresh === 'true'
+                });
+                this.opts.callbacks.emitPairingRefresh(linkCodeNode.attrs.force_manual_refresh === 'true');
+            }
+            return true;
+        }
+        if (stage !== WA_SIGNALING.LINK_CODE_STAGE_PRIMARY_HELLO) {
+            return true;
+        }
+        await this.handlePrimaryHello(linkCodeNode);
+        return true;
+    }
+    async handleCompanionRegRefreshNotification(node) {
+        const hasExpectedChild = hasNodeChild(node, WA_SIGNALING.COMPANION_REG_REFRESH_NOTIFICATION) ||
+            hasNodeChild(node, 'pair-device-rotate-qr');
+        if (!hasExpectedChild) {
+            return false;
+        }
+        await this.opts.socket.sendNode(buildNotificationAckNode(node, WA_SIGNALING.COMPANION_REG_REFRESH_NOTIFICATION));
+        await this.rotateAdvSecret(this.requireCredentials());
+        this.opts.logger.info('handled companion_reg_refresh notification');
+        this.opts.qrFlow.refreshCurrentQr();
+        return true;
+    }
+    async handlePairDevice(iqNode, pairDeviceNode) {
+        const refs = getNodeChildrenByTag(pairDeviceNode, WA_NODE_TAGS.REF)
+            .map((child) => TEXT_DECODER.decode(decodeNodeContentUtf8OrBytes(child.content, 'pair-device.ref')))
+            .filter((ref) => ref.length > 0);
+        await this.rotateAdvSecret(this.requireCredentials());
+        this.opts.qrFlow.setRefs(refs);
+        this.opts.logger.info('pair-device refs updated', { refsCount: refs.length });
+        await this.opts.socket.sendNode(buildIqResultNode(iqNode));
+    }
+    async handlePairSuccess(iqNode, pairSuccessNode) {
+        this.opts.logger.info('processing pair-success node');
+        const credentials = this.requireCredentials();
+        const deviceIdentityNode = findNodeChild(pairSuccessNode, WA_NODE_TAGS.DEVICE_IDENTITY);
+        const deviceNode = findNodeChild(pairSuccessNode, 'device');
+        const platformNode = findNodeChild(pairSuccessNode, WA_NODE_TAGS.PLATFORM);
+        if (!deviceIdentityNode || !deviceNode || !platformNode) {
+            this.opts.logger.error('pair-success missing required nodes', {
+                hasDeviceIdentity: !!deviceIdentityNode,
+                hasDevice: !!deviceNode,
+                hasPlatform: !!platformNode
+            });
+            throw new Error('pair-success stanza is missing required nodes');
+        }
+        const wrappedIdentity = proto.ADVSignedDeviceIdentityHMAC.decode(decodeNodeContentUtf8OrBytes(deviceIdentityNode.content, 'pair-success.device-identity'));
+        const wrappedDetails = decodeProtoBytes(wrappedIdentity.details, 'ADVSignedDeviceIdentityHMAC.details');
+        const wrappedHmac = decodeProtoBytes(wrappedIdentity.hmac, 'ADVSignedDeviceIdentityHMAC.hmac');
+        const accountType = wrappedIdentity.accountType ?? proto.ADVEncryptionType.E2EE;
+        const isHosted = accountType === proto.ADVEncryptionType.HOSTED;
+        const hmacInput = isHosted
+            ? concatBytes([ADV_PREFIX_HOSTED_ACCOUNT_SIGNATURE, wrappedDetails])
+            : wrappedDetails;
+        const expectedHmac = await computeAdvIdentityHmac(credentials.advSecretKey, hmacInput);
+        if (!uint8Equal(expectedHmac, wrappedHmac)) {
+            this.opts.logger.error('pair-success hmac mismatch');
+            throw new Error('pair-success HMAC validation failed');
+        }
+        const { signedIdentity, keyIndex, responseIdentityBytes } = await this.buildPairSuccessResponseIdentity(credentials, wrappedDetails, isHosted);
+        const nextCredentials = {
+            ...credentials,
+            signedIdentity,
+            meJid: deviceNode.attrs.jid,
+            meLid: deviceNode.attrs.lid,
+            platform: platformNode.attrs.name
+        };
+        await this.opts.auth.updateCredentials(nextCredentials);
+        this.opts.logger.info('pair-success credentials updated', {
+            meJid: nextCredentials.meJid,
+            meLid: nextCredentials.meLid,
+            platform: nextCredentials.platform
+        });
+        this.opts.qrFlow.clear();
+        await this.opts.socket.sendNode({
+            tag: WA_NODE_TAGS.IQ,
+            attrs: {
+                ...(iqNode.attrs.id ? { id: iqNode.attrs.id } : {}),
+                to: iqNode.attrs.from ?? WA_DEFAULTS.HOST_DOMAIN,
+                type: WA_IQ_TYPES.RESULT
+            },
+            content: [
+                {
+                    tag: 'pair-device-sign',
+                    attrs: {},
+                    content: [
+                        {
+                            tag: WA_NODE_TAGS.DEVICE_IDENTITY,
+                            attrs: {
+                                'key-index': String(keyIndex)
+                            },
+                            content: responseIdentityBytes
+                        }
+                    ]
+                }
+            ]
+        });
+        this.opts.callbacks.emitPaired(nextCredentials);
+        this.opts.logger.debug('pair-success completed and paired event emitted');
+    }
+    async buildPairSuccessResponseIdentity(credentials, wrappedDetails, isHosted) {
+        const signedIdentity = proto.ADVSignedDeviceIdentity.decode(wrappedDetails);
+        const details = decodeProtoBytes(signedIdentity.details, 'ADVSignedDeviceIdentity.details');
+        const accountSignature = decodeProtoBytes(signedIdentity.accountSignature, 'ADVSignedDeviceIdentity.accountSignature');
+        const accountSignatureKey = decodeProtoBytes(signedIdentity.accountSignatureKey, 'ADVSignedDeviceIdentity.accountSignatureKey');
+        const localIdentity = credentials.registrationInfo.identityKeyPair;
+        const validAccountSignature = await verifyDeviceIdentityAccountSignature(details, accountSignature, localIdentity.pubKey, accountSignatureKey, isHosted);
+        if (!validAccountSignature) {
+            this.opts.logger.error('pair-success account signature invalid');
+            throw new Error('pair-success account signature validation failed');
+        }
+        signedIdentity.deviceSignature = await generateDeviceSignature(details, localIdentity, accountSignatureKey, isHosted);
+        const advDeviceIdentity = proto.ADVDeviceIdentity.decode(details);
+        const responseIdentityBytes = proto.ADVSignedDeviceIdentity.encode({
+            details: signedIdentity.details,
+            accountSignature: signedIdentity.accountSignature,
+            deviceSignature: signedIdentity.deviceSignature
+        }).finish();
+        return {
+            signedIdentity,
+            keyIndex: advDeviceIdentity.keyIndex ?? 0,
+            responseIdentityBytes
+        };
+    }
+    async handlePrimaryHello(linkCodeNode) {
+        const credentials = this.requireCredentials();
+        const pairingSession = this.pairingSession;
+        if (!pairingSession || pairingSession.finished) {
+            this.opts.logger.trace('primary_hello ignored: no active session');
+            return;
+        }
+        pairingSession.attempts += 1;
+        this.opts.logger.debug('processing primary_hello', {
+            attempts: pairingSession.attempts
+        });
+        if (pairingSession.attempts > 3) {
+            throw new Error('pairing code exceeded maximum primary hello attempts');
+        }
+        const refNode = findNodeChild(linkCodeNode, WA_NODE_TAGS.LINK_CODE_PAIRING_REF);
+        const wrappedPrimaryNode = findNodeChild(linkCodeNode, 'link_code_pairing_wrapped_primary_ephemeral_pub');
+        const primaryIdentityNode = findNodeChild(linkCodeNode, 'primary_identity_pub');
+        if (!refNode || !wrappedPrimaryNode || !primaryIdentityNode) {
+            throw new Error('primary_hello notification is missing fields');
+        }
+        const ref = decodeNodeContentUtf8OrBytes(refNode.content, 'primary_hello.link_code_pairing_ref');
+        if (!pairingSession.ref || !uint8Equal(ref, pairingSession.ref)) {
+            this.opts.logger.warn('primary_hello ref mismatch ignored');
+            return;
+        }
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        if (nowSeconds - pairingSession.createdAtSeconds >
+            WA_DEFAULTS.PAIRING_CODE_MAX_AGE_SECONDS) {
+            throw new Error('primary_hello received for an expired pairing code');
+        }
+        const finish = await completeCompanionFinish({
+            pairingCode: pairingSession.pairingCode,
+            wrappedPrimaryEphemeralPub: decodeNodeContentUtf8OrBytes(wrappedPrimaryNode.content, 'primary_hello.link_code_pairing_wrapped_primary_ephemeral_pub'),
+            primaryIdentityPub: decodeNodeContentUtf8OrBytes(primaryIdentityNode.content, 'primary_hello.primary_identity_pub'),
+            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,
+            companionIdentityPublic: finish.companionIdentityPublic,
+            ref
+        }), WA_DEFAULTS.IQ_TIMEOUT_MS);
+        if (result.attrs.type === WA_IQ_TYPES.ERROR) {
+            throw new Error('companion_finish returned error');
+        }
+        pairingSession.finished = true;
+        this.opts.logger.info('primary_hello completed with companion_finish success');
+    }
+    async rotateAdvSecret(credentials) {
+        const nextCredentials = {
+            ...credentials,
+            advSecretKey: await randomBytesAsync(32)
+        };
+        await this.opts.auth.updateCredentials(nextCredentials);
+        return nextCredentials;
+    }
+    requireCredentials() {
+        const credentials = this.opts.auth.getCredentials();
+        if (!credentials) {
+            throw new Error('credentials are not initialized');
+        }
+        return credentials;
+    }
+}

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

@@ -0,0 +1,82 @@
+import { WA_DEFAULTS } from '../../protocol/constants.js';
+import { bytesToBase64 } from '../../util/base64.js';
+export class WaQrFlow {
+    constructor(args) {
+        this.logger = args.logger;
+        this.getCredentials = args.getCredentials;
+        this.getDevicePlatform = args.getDevicePlatform;
+        this.emitQr = args.emitQr;
+        this.qrRefs = [];
+        this.currentRef = null;
+        this.currentQrTimer = null;
+    }
+    hasQr() {
+        return this.qrRefs.length > 0 || this.currentQrTimer !== null;
+    }
+    clear() {
+        this.logger.trace('qr flow clear');
+        if (this.currentQrTimer) {
+            clearTimeout(this.currentQrTimer);
+            this.currentQrTimer = null;
+        }
+        this.qrRefs = [];
+        this.currentRef = null;
+    }
+    refreshCurrentQr() {
+        if (!this.currentRef) {
+            this.logger.trace('qr flow refresh skipped: no active ref');
+            return false;
+        }
+        const credentials = this.getCredentials();
+        if (!credentials) {
+            this.logger.warn('qr flow refresh skipped: missing credentials');
+            return false;
+        }
+        const ttlMs = this.qrRefs.length === 5
+            ? WA_DEFAULTS.QR_INITIAL_TTL_MS
+            : WA_DEFAULTS.QR_ROTATION_TTL_MS;
+        this.logger.debug('qr flow refresh emit', { ttlMs, remainingRefs: this.qrRefs.length });
+        this.emitQr(this.buildQr(this.currentRef, credentials), ttlMs);
+        return true;
+    }
+    setRefs(refs) {
+        this.clear();
+        this.qrRefs = [...refs];
+        this.logger.info('qr refs updated', { count: this.qrRefs.length });
+        if (this.qrRefs.length === 0) {
+            return;
+        }
+        this.rotateRef();
+    }
+    rotateRef() {
+        const credentials = this.getCredentials();
+        if (!credentials) {
+            this.clear();
+            return;
+        }
+        const ref = this.qrRefs.shift();
+        if (!ref) {
+            this.clear();
+            return;
+        }
+        this.currentRef = ref;
+        const ttlMs = this.qrRefs.length === 5
+            ? WA_DEFAULTS.QR_INITIAL_TTL_MS
+            : WA_DEFAULTS.QR_ROTATION_TTL_MS;
+        this.logger.trace('qr flow emit new code', { ttlMs, remainingRefs: this.qrRefs.length });
+        this.emitQr(this.buildQr(ref, credentials), ttlMs);
+        this.currentQrTimer = setTimeout(() => {
+            this.currentQrTimer = null;
+            this.rotateRef();
+        }, ttlMs);
+    }
+    buildQr(ref, credentials) {
+        return [
+            ref,
+            bytesToBase64(credentials.noiseKeyPair.pubKey),
+            bytesToBase64(credentials.registrationInfo.identityKeyPair.pubKey),
+            bytesToBase64(credentials.advSecretKey),
+            this.getDevicePlatform()
+        ].join(',');
+    }
+}

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

@@ -0,0 +1,2 @@
+export const CROCKFORD_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTVWXYZ';
+export const PBKDF2_ITERATIONS = 2 << 16;

package/dist/esm/auth/types.js

@@ -0,0 +1 @@
+export {};