zapo-js 0.2.0 → 0.3.0

package/dist/esm/appstate/WaAppStateSyncClient.js

@@ -1,12 +1,12 @@
-import { APP_STATE_DEFAULT_COLLECTIONS, APP_STATE_DEFAULT_COLLECTION_VERSION, APP_STATE_EMPTY_LT_HASH } from './constants.js';
+import { APP_STATE_DEFAULT_COLLECTION_VERSION, APP_STATE_DEFAULT_COLLECTIONS, APP_STATE_EMPTY_LT_HASH } from './constants.js';
+import { parseSyncResponse } from './response-parser.js';
 import { WaAppStateCrypto } from './WaAppStateCrypto.js';
-import { parseSyncResponse } from './WaAppStateSyncResponseParser.js';
+import { randomBytesAsync, randomIntAsync } from '../crypto/index.js';
 import { proto } from '../proto.js';
 import { WA_APP_STATE_COLLECTION_STATES, WA_DEFAULTS, WA_IQ_TYPES, WA_NODE_TAGS, WA_XMLNS } from '../protocol/constants.js';
 import { parseSignalAddressFromJid } from '../protocol/jid.js';
 import { assertIqResult } from '../transport/node/query.js';
-import { decodeProtoBytes } from '../util/bytes.js';
-import { bytesToHex, uint8Equal } from '../util/bytes.js';
+import { bytesToHex, decodeProtoBytes, uint8Equal } from '../util/bytes.js';
 import { longToNumber } from '../util/primitives.js';
 export class WaAppStateMissingKeyError extends Error {
     constructor(message, keyId, collection) {
@@ -25,7 +25,8 @@ export class WaAppStateSyncClient {
         this.hostDomain = options.hostDomain ?? WA_DEFAULTS.HOST_DOMAIN;
         this.defaultTimeoutMs = options.defaultTimeoutMs ?? WA_DEFAULTS.APP_STATE_SYNC_TIMEOUT_MS;
         this.onMissingKeys = options.onMissingKeys;
-        this.crypto = new WaAppStateCrypto();
+        this.crypto = new WaAppStateCrypto(undefined, options.skipMacVerification === true);
+        this.mobilePrimary = options.mobilePrimary ?? false;
         this.syncContext = null;
         this.syncPromise = null;
     }
@@ -33,6 +34,28 @@ export class WaAppStateSyncClient {
         this.logger.trace('app-state export requested');
         return this.store.exportData();
     }
+    async ensureInitialSyncKey() {
+        const existing = await this.store.getActiveSyncKey();
+        if (existing) {
+            return existing;
+        }
+        const keyIdBytes = await randomBytesAsync(2);
+        const keyData = await randomBytesAsync(32);
+        const rawId = await randomIntAsync(0, 4294967295);
+        const key = {
+            keyId: keyIdBytes,
+            keyData,
+            timestamp: Date.now(),
+            fingerprint: { rawId, currentIndex: 0, deviceIndexes: [0] }
+        };
+        await this.store.upsertSyncKeys([key]);
+        this.crypto.clearCache();
+        this.logger.info('app-state initial sync key generated (mobile primary)', {
+            keyId: bytesToHex(keyIdBytes),
+            rawId
+        });
+        return key;
+    }
     async importSyncKeys(keys) {
         this.logger.debug('app-state importing sync keys', { count: keys.length });
         const inserted = await this.store.upsertSyncKeys(keys);
@@ -283,7 +306,7 @@ export class WaAppStateSyncClient {
             content: [
                 {
                     tag: WA_NODE_TAGS.SYNC,
-                    attrs: {},
+                    attrs: this.mobilePrimary ? { data_namespace: '3' } : {},
                     content: collectionNodes
                 }
             ]
@@ -462,11 +485,13 @@ export class WaAppStateSyncClient {
         if (!snapshot.version?.version) {
             throw new Error(`snapshot for ${collection} is missing version`);
         }
-        if (!snapshot.mac) {
-            throw new Error(`snapshot for ${collection} is missing mac`);
-        }
-        if (!snapshot.keyId?.id) {
-            throw new Error(`snapshot for ${collection} is missing keyId`);
+        if (!this.crypto.isMacVerificationSkipped) {
+            if (!snapshot.mac) {
+                throw new Error(`snapshot for ${collection} is missing mac`);
+            }
+            if (!snapshot.keyId?.id) {
+                throw new Error(`snapshot for ${collection} is missing keyId`);
+            }
         }
         return snapshot;
     }
@@ -481,14 +506,16 @@ export class WaAppStateSyncClient {
         if (!patch.version?.version) {
             throw new Error(`patch for ${collection} is missing version`);
         }
-        if (!patch.snapshotMac) {
-            throw new Error(`patch for ${collection} is missing snapshotMac`);
-        }
-        if (!patch.patchMac) {
-            throw new Error(`patch for ${collection} is missing patchMac`);
-        }
-        if (!patch.keyId?.id) {
-            throw new Error(`patch for ${collection} is missing keyId`);
+        if (!this.crypto.isMacVerificationSkipped) {
+            if (!patch.snapshotMac) {
+                throw new Error(`patch for ${collection} is missing snapshotMac`);
+            }
+            if (!patch.patchMac) {
+                throw new Error(`patch for ${collection} is missing patchMac`);
+            }
+            if (!patch.keyId?.id) {
+                throw new Error(`patch for ${collection} is missing keyId`);
+            }
         }
         if (patch.mutations && patch.mutations.length > 0 && patch.externalMutations) {
             throw new Error(`patch for ${collection} has inline and external mutations together`);
@@ -502,10 +529,13 @@ export class WaAppStateSyncClient {
     }
     async applySnapshot(collection, snapshot) {
         const version = this.normalizeProtoLong(snapshot.version?.version, `snapshot.version.version (${collection})`);
-        const keyId = decodeProtoBytes(snapshot.keyId?.id, `snapshot.keyId.id (${collection})`);
-        const keyData = await this.getKeyData(keyId);
-        if (!keyData) {
-            throw new WaAppStateMissingKeyError(`missing snapshot key ${bytesToHex(keyId)} for ${collection}`, keyId, collection);
+        let keyData = null;
+        if (!this.crypto.isMacVerificationSkipped) {
+            const keyId = decodeProtoBytes(snapshot.keyId?.id, `snapshot.keyId.id (${collection})`);
+            keyData = await this.getKeyData(keyId);
+            if (!keyData) {
+                throw new WaAppStateMissingKeyError(`missing snapshot key ${bytesToHex(keyId)} for ${collection}`, keyId, collection);
+            }
         }
         const indexValueMap = new Map();
         const mutations = [];
@@ -533,9 +563,11 @@ export class WaAppStateSyncClient {
             ltHashInputIndex += 1;
         }
         const ltHash = await this.crypto.ltHashAdd(APP_STATE_EMPTY_LT_HASH, ltHashInput);
-        const expectedSnapshotMac = await this.crypto.generateSnapshotMac(keyData, ltHash, version, collection);
-        if (!uint8Equal(expectedSnapshotMac, snapshot.mac)) {
-            throw new Error(`snapshot MAC mismatch for ${collection}`);
+        if (keyData !== null) {
+            const expectedSnapshotMac = await this.crypto.generateSnapshotMac(keyData, ltHash, version, collection);
+            if (!uint8Equal(expectedSnapshotMac, snapshot.mac)) {
+                throw new Error(`snapshot MAC mismatch for ${collection}`);
+            }
         }
         this.setCollectionState(collection, version, ltHash, indexValueMap);
         return mutations;
@@ -546,10 +578,13 @@ export class WaAppStateSyncClient {
         if (current.version !== patchVersion - 1) {
             throw new Error(`patch version mismatch for ${collection}: local=${current.version}, incoming=${patchVersion}`);
         }
-        const patchKeyId = decodeProtoBytes(patch.keyId?.id, `patch.keyId.id (${collection})`);
-        const patchKeyData = await this.getKeyData(patchKeyId);
-        if (!patchKeyData) {
-            throw new WaAppStateMissingKeyError(`missing patch key ${bytesToHex(patchKeyId)} for ${collection}`, patchKeyId, collection);
+        let patchKeyData = null;
+        if (!this.crypto.isMacVerificationSkipped) {
+            const patchKeyId = decodeProtoBytes(patch.keyId?.id, `patch.keyId.id (${collection})`);
+            patchKeyData = await this.getKeyData(patchKeyId);
+            if (!patchKeyData) {
+                throw new WaAppStateMissingKeyError(`missing patch key ${bytesToHex(patchKeyId)} for ${collection}`, patchKeyId, collection);
+            }
         }
         const decryptedMutations = await this.decryptPatchMutations(collection, patch);
         const macMutations = new Array(decryptedMutations.length);
@@ -564,7 +599,9 @@ export class WaAppStateSyncClient {
             };
         }
         const nextState = await this.computeNextCollectionState(current.hash, current.indexValueMap, macMutations, collection);
-        await this.assertPatchMacsMatch(patch, collection, patchKeyData, patchVersion, nextState.hash, valueMacs);
+        if (patchKeyData !== null) {
+            await this.assertPatchMacsMatch(patch, collection, patchKeyData, patchVersion, nextState.hash, valueMacs);
+        }
         this.setCollectionState(collection, patchVersion, nextState.hash, nextState.indexValueMap);
         return decryptedMutations;
     }

package/dist/esm/appstate/index.js

@@ -2,5 +2,5 @@ export * from './constants.js';
 export { encodeAppStateFingerprint, decodeAppStateFingerprint, decodeAppStateCollections, decodeAppStateSyncKeys } from './encoding.js';
 export * from './utils.js';
 export { WaAppStateCrypto } from './WaAppStateCrypto.js';
-export { parseSyncResponse } from './WaAppStateSyncResponseParser.js';
+export { parseSyncResponse } from './response-parser.js';
 export { WaAppStateSyncClient } from './WaAppStateSyncClient.js';

package/dist/esm/appstate/{WaAppStateSyncResponseParser.js → response-parser.js}

@@ -1,7 +1,7 @@
 import { parseCollectionName } from './utils.js';
 import { proto } from '../proto.js';
 import { WA_APP_STATE_COLLECTION_STATES, WA_APP_STATE_ERROR_CODES, WA_IQ_TYPES, WA_NODE_TAGS } from '../protocol/constants.js';
-import { decodeNodeContentBase64OrBytes, findNodeChildrenByTags, findNodeChild, getNodeChildrenByTag } from '../transport/node/helpers.js';
+import { decodeNodeContentBase64OrBytes, findNodeChild, findNodeChildrenByTags, getNodeChildrenByTag } from '../transport/node/helpers.js';
 export function parseSyncResponse(iqNode) {
     if (iqNode.tag !== WA_NODE_TAGS.IQ) {
         throw new Error(`invalid sync response tag ${iqNode.tag}`);

package/dist/esm/auth/WaAuthClient.js

@@ -1,4 +1,4 @@
-import { buildCommsConfig, loadOrCreateCredentials, persistCredentials } from './flow/WaAuthCredentialsFlow.js';
+import { buildCommsConfig, loadOrCreateCredentials, persistCredentials } from './credentials-flow.js';
 import { WaPairingFlow } from './pairing/WaPairingFlow.js';
 import { WaQrFlow } from './pairing/WaQrFlow.js';
 import { getWaCompanionPlatformId, WA_DEFAULTS } from '../protocol/constants.js';
@@ -24,6 +24,7 @@ export class WaAuthClient {
         this.callbacks = deps.callbacks ?? {};
         this.authStore = deps.authStore;
         this.signalStore = deps.signalStore;
+        this.preKeyStore = deps.preKeyStore;
         this.credentials = null;
         this.qrFlow = new WaQrFlow({
             logger: this.logger,
@@ -44,7 +45,8 @@ export class WaAuthClient {
                 emitPairingCode: (code) => this.callbacks.onPairingCode?.(code),
                 emitPairingRefresh: (forceManual) => this.callbacks.onPairingRefresh?.(forceManual),
                 emitPaired: (credentials) => this.callbacks.onPaired?.(credentials)
-            }
+            },
+            dangerous: options.dangerous
         });
     }
     getState(connected = false) {
@@ -64,7 +66,9 @@ export class WaAuthClient {
             this.credentials = await loadOrCreateCredentials({
                 logger: this.logger,
                 authStore: this.authStore,
-                signalStore: this.signalStore
+                signalStore: this.signalStore,
+                preKeyStore: this.preKeyStore,
+                skipSignedPreKeySignatureVerification: this.options.dangerous?.disableSignedPreKeySignatureVerification
             });
             this.logger.info('auth client credentials ready', {
                 registered: this.credentials?.meJid !== null && this.credentials?.meJid !== undefined
@@ -72,13 +76,17 @@ export class WaAuthClient {
             return this.credentials;
         });
     }
-    buildCommsConfig(socketOptions) {
+    buildCommsConfig(socketOptions, overrides = {}) {
         this.logger.trace('auth client building comms config');
         return buildCommsConfig(this.logger, this.requireCredentials(), socketOptions, {
             deviceBrowser: this.options.deviceBrowser,
             deviceOsDisplayName: this.options.deviceOsDisplayName,
             requireFullSync: this.options.requireFullSync,
-            version: this.options.version
+            version: this.options.version,
+            mobileTransport: this.options.mobileTransport,
+            noiseTrustedRootCa: overrides.noiseTrustedRootCa,
+            disableNoiseCertificateChainVerification: overrides.disableNoiseCertificateChainVerification ??
+                this.options.dangerous?.disableNoiseCertificateChainVerification
         });
     }
     async clearTransientState() {
@@ -177,10 +185,10 @@ export class WaAuthClient {
             }
         });
     }
-    async requestPairingCode(phoneNumber, shouldShowPushNotification = false) {
+    async requestPairingCode(phoneNumber, shouldShowPushNotification = false, customCode) {
         this.requireCredentials();
         this.logger.info('auth client requesting pairing code');
-        return this.runHandled(() => this.pairingFlow.requestPairingCode(phoneNumber, shouldShowPushNotification));
+        return this.runHandled(() => this.pairingFlow.requestPairingCode(phoneNumber, shouldShowPushNotification, customCode));
     }
     async fetchPairingCountryCodeIso() {
         this.requireCredentials();
@@ -228,7 +236,8 @@ export class WaAuthClient {
         await persistCredentials({
             logger: this.logger,
             authStore: this.authStore,
-            signalStore: this.signalStore
+            signalStore: this.signalStore,
+            preKeyStore: this.preKeyStore
         }, credentials);
     }
     requireCredentials() {

package/dist/esm/auth/{flow/WaAuthCredentialsFlow.js → credentials-flow.js}

@@ -1,11 +1,12 @@
-import { randomBytesAsync } from '../../crypto/index.js';
-import { toSerializedPubKey } from '../../crypto/core/keys.js';
-import { X25519 } from '../../crypto/curves/X25519.js';
-import { getLoginIdentity } from '../../protocol/jid.js';
-import { verifySignalSignature } from '../../signal/crypto/WaAdvSignature.js';
-import { createAndStoreInitialKeys } from '../../signal/registration/utils.js';
-import { toProxyAgent, toProxyDispatcher } from '../../transport/proxy.js';
-import { toError } from '../../util/primitives.js';
+import { randomBytesAsync, toRawPubKey, xeddsaVerify } from '../crypto/index.js';
+import { toSerializedPubKey } from '../crypto/core/keys.js';
+import { X25519 } from '../crypto/curves/X25519.js';
+import { getLoginIdentity } from '../protocol/jid.js';
+import { createAndStoreInitialKeys } from '../signal/registration/utils.js';
+import { WaMobileTcpSocketCtor } from '../transport/node/WaMobileTcpSocket.js';
+import { buildMobileLoginPayload } from '../transport/noise/WaMobileClientPayload.js';
+import { toProxyAgent, toProxyDispatcher } from '../transport/proxy.js';
+import { toError } from '../util/primitives.js';
 export async function loadOrCreateCredentials(args) {
     args.logger.trace('auth credentials loadOrCreate start');
     const existing = await args.authStore.load();
@@ -18,13 +19,16 @@ export async function loadOrCreateCredentials(args) {
         registered: existing.meJid !== null && existing.meJid !== undefined,
         hasServerStaticKey: existing.serverStaticKey !== null && existing.serverStaticKey !== undefined
     });
-    if (!existing.meJid && !(await hasValidSignedPreKey(args.logger, existing))) {
+    const skipSignedPreKeyCheck = args.skipSignedPreKeySignatureVerification === true;
+    if (!existing.meJid &&
+        !skipSignedPreKeyCheck &&
+        !(await hasValidSignedPreKey(args.logger, existing))) {
         args.logger.warn('signed pre-key is invalid, regenerating credentials');
         const fresh = await createFreshAndPersistCredentials(args);
         args.logger.info('regenerated credentials due to invalid signed pre-key');
         return fresh;
     }
-    await restoreSignalStore(args.signalStore, existing);
+    await restoreSignalStore(args.signalStore, args.preKeyStore, existing);
     args.logger.trace('auth credentials restored into signal store');
     return existing;
 }
@@ -34,15 +38,72 @@ export async function persistCredentials(args, credentials) {
     });
     await args.authStore.save(credentials);
 }
+function mobileTransportFromCredentials(credentials) {
+    if (!credentials.deviceInfo)
+        return undefined;
+    return {
+        deviceInfo: credentials.deviceInfo,
+        ...(credentials.pushName !== undefined ? { pushName: credentials.pushName } : {}),
+        ...(credentials.yearClass !== undefined ? { yearClass: credentials.yearClass } : {}),
+        ...(credentials.memClass !== undefined ? { memClass: credentials.memClass } : {})
+    };
+}
 export function buildCommsConfig(logger, credentials, socketOptions, clientOptions) {
     const meJid = credentials.meJid;
     const registered = meJid !== null && meJid !== undefined;
     const loginIdentity = registered ? getLoginIdentity(meJid) : null;
     const wsProxy = socketOptions.proxy?.ws;
+    // Resolve the effective mobile transport: explicit option wins, otherwise
+    // synthesize one from persisted credentials.deviceInfo so a registered
+    // mobile session boots in mobile mode without the caller re-passing
+    // deviceInfo on every `new WaClient(...)` call.
+    const effectiveMobileTransport = clientOptions.mobileTransport ?? mobileTransportFromCredentials(credentials);
     logger.debug('building comms config from credentials', {
         registered,
-        hasServerStaticKey: credentials.serverStaticKey !== null && credentials.serverStaticKey !== undefined
+        hasServerStaticKey: credentials.serverStaticKey !== null && credentials.serverStaticKey !== undefined,
+        mobile: Boolean(effectiveMobileTransport),
+        mobileSource: clientOptions.mobileTransport
+            ? 'option'
+            : effectiveMobileTransport
+                ? 'credentials'
+                : 'none'
     });
+    if (effectiveMobileTransport) {
+        if (wsProxy) {
+            throw new Error('mobileTransport does not support socketOptions.proxy.ws — remove the proxy option or open an issue to add TCP proxy support');
+        }
+        if (!loginIdentity) {
+            throw new Error('mobileTransport requires registered credentials (meJid) — run the mobile bridge flow first');
+        }
+        const loginPayload = buildMobileLoginPayload({
+            username: loginIdentity.username,
+            device: loginIdentity.device,
+            passive: effectiveMobileTransport.passive ?? false,
+            deviceInfo: effectiveMobileTransport.deviceInfo,
+            pushName: effectiveMobileTransport.pushName,
+            yearClass: effectiveMobileTransport.yearClass,
+            memClass: effectiveMobileTransport.memClass
+        });
+        return {
+            url: effectiveMobileTransport.tcpUrl ?? 'tcp://g.whatsapp.net:443',
+            rawWebSocketConstructor: WaMobileTcpSocketCtor,
+            connectTimeoutMs: socketOptions.connectTimeoutMs,
+            reconnectIntervalMs: socketOptions.reconnectIntervalMs,
+            timeoutIntervalMs: socketOptions.timeoutIntervalMs,
+            maxReconnectAttempts: socketOptions.maxReconnectAttempts,
+            noise: {
+                clientStaticKeyPair: credentials.noiseKeyPair,
+                isRegistered: true,
+                serverStaticKey: credentials.serverStaticKey,
+                routingInfo: credentials.routingInfo,
+                trustedRootCa: clientOptions.noiseTrustedRootCa,
+                verifyCertificateChain: clientOptions.disableNoiseCertificateChainVerification
+                    ? false
+                    : undefined,
+                loginPayload
+            }
+        };
+    }
     return {
         url: socketOptions.url,
         urls: socketOptions.urls,
@@ -58,6 +119,10 @@ export function buildCommsConfig(logger, credentials, socketOptions, clientOptio
             isRegistered: registered,
             serverStaticKey: credentials.serverStaticKey,
             routingInfo: credentials.routingInfo,
+            trustedRootCa: clientOptions.noiseTrustedRootCa,
+            verifyCertificateChain: clientOptions.disableNoiseCertificateChainVerification
+                ? false
+                : undefined,
             loginPayloadConfig: loginIdentity
                 ? {
                     username: loginIdentity.username,
@@ -80,11 +145,11 @@ export function buildCommsConfig(logger, credentials, socketOptions, clientOptio
         }
     };
 }
-async function createFreshCredentials(signalStore, logger) {
+async function createFreshCredentials(signalStore, preKeyStore, logger) {
     logger.trace('creating fresh credentials');
     const [noiseKeyPair, registrationBundle, advSecretKey] = await Promise.all([
         X25519.generateKeyPair(),
-        createAndStoreInitialKeys(signalStore),
+        createAndStoreInitialKeys(signalStore, preKeyStore),
         randomBytesAsync(32)
     ]);
     return {
@@ -96,16 +161,16 @@ async function createFreshCredentials(signalStore, logger) {
     };
 }
 async function createFreshAndPersistCredentials(args) {
-    const credentials = await createFreshCredentials(args.signalStore, args.logger);
+    const credentials = await createFreshCredentials(args.signalStore, args.preKeyStore, args.logger);
     // Persist credentials first so signal restore never commits state for credentials that failed to save.
     await args.authStore.save(credentials);
-    await restoreSignalStore(args.signalStore, credentials);
+    await restoreSignalStore(args.signalStore, args.preKeyStore, credentials);
     return credentials;
 }
 async function hasValidSignedPreKey(logger, credentials) {
     try {
         const serializedPubKey = toSerializedPubKey(credentials.signedPreKey.keyPair.pubKey);
-        const valid = await verifySignalSignature(credentials.registrationInfo.identityKeyPair.pubKey, serializedPubKey, credentials.signedPreKey.signature);
+        const valid = await xeddsaVerify(toRawPubKey(credentials.registrationInfo.identityKeyPair.pubKey), serializedPubKey, credentials.signedPreKey.signature);
         logger.trace('signed pre-key validation completed', { valid });
         return valid;
     }
@@ -116,10 +181,10 @@ async function hasValidSignedPreKey(logger, credentials) {
         return false;
     }
 }
-async function restoreSignalStore(signalStore, credentials) {
+async function restoreSignalStore(signalStore, preKeyStore, credentials) {
     await Promise.all([
         signalStore.setRegistrationInfo(credentials.registrationInfo),
         signalStore.setSignedPreKey(credentials.signedPreKey),
-        signalStore.setServerHasPreKeys(credentials.serverHasPreKeys === true)
+        preKeyStore.setServerHasPreKeys(credentials.serverHasPreKeys === true)
     ]);
 }

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

@@ -1,14 +1,14 @@
-import { completeCompanionFinish, createCompanionHello } from '../pairing/WaPairingCodeCrypto.js';
+import { completeCompanionFinish, createCompanionHello, normalizeCustomPairingCode } from '../pairing/pairing-code-crypto.js';
 import { randomBytesAsync } from '../../crypto/index.js';
 import { proto } from '../../proto.js';
+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/crypto/WaAdvSignature.js';
 import { buildAckNode, buildIqResultNode } from '../../transport/node/builders/global.js';
 import { buildCompanionFinishRequestNode, buildCompanionHelloRequestNode, buildGetCountryCodeRequestNode } from '../../transport/node/builders/pairing.js';
-import { decodeNodeContentUtf8OrBytes, findNodeChildrenByTags, findNodeChild, getFirstNodeChild, getNodeChildrenNonEmptyUtf8ByTag, hasNodeChild } from '../../transport/node/helpers.js';
-import { decodeProtoBytes } from '../../util/bytes.js';
-import { concatBytes, uint8Equal } from '../../util/bytes.js';
+import { decodeNodeContentUtf8OrBytes, findNodeChild, findNodeChildrenByTags, getFirstNodeChild, getNodeChildrenNonEmptyUtf8ByTag, hasNodeChild } from '../../transport/node/helpers.js';
+import { concatBytes, decodeProtoBytes, uint8Equal } from '../../util/bytes.js';
 export class WaPairingFlow {
     constructor(options) {
         this.opts = options;
@@ -21,26 +21,19 @@ export class WaPairingFlow {
         this.opts.logger.trace('pairing flow session cleared');
         this.pairingSession = null;
     }
-    async requestPairingCode(phoneNumber, shouldShowPushNotification = false) {
+    async requestPairingCode(phoneNumber, shouldShowPushNotification = false, customCode) {
         this.opts.logger.info('requesting pairing code', {
-            shouldShowPushNotification
+            shouldShowPushNotification,
+            hasCustomCode: customCode !== undefined
         });
+        const normalizedCustomCode = customCode !== undefined ? normalizeCustomPairingCode(customCode) : undefined;
         const credentials = this.requireCredentials();
         const phoneJid = parsePhoneJid(phoneNumber);
         const [companionHello, refreshedCredentials] = await Promise.all([
-            createCompanionHello(),
+            createCompanionHello({ customCode: normalizedCustomCode }),
             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 browserDisplayName = getWaBrowserDisplayName(this.opts.device.browser);
         const response = await this.opts.socket.query(buildCompanionHelloRequestNode({
             phoneJid,
             shouldShowPushNotification,
@@ -186,13 +179,15 @@ export class WaPairingFlow {
         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');
+        if (this.opts.dangerous?.disablePairSuccessHmacVerification !== true) {
+            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 = {
@@ -241,10 +236,12 @@ export class WaPairingFlow {
         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');
+        if (this.opts.dangerous?.disableAdvSignatureVerification !== true) {
+            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);

package/dist/esm/auth/pairing/{WaPairingCodeCrypto.js → pairing-code-crypto.js}

@@ -1,8 +1,9 @@
-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';
+export const CROCKFORD_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTVWXYZ';
+export const PBKDF2_ITERATIONS = 2 << 16;
 function bytesToCrockford(bytes) {
     let bitCount = 0;
     let value = 0;
@@ -20,14 +21,27 @@ function bytesToCrockford(bytes) {
     }
     return out;
 }
-export async function createCompanionHello() {
-    const [codeBytes, companionEphemeralKeyPair, salt, counter] = await Promise.all([
-        randomBytesAsync(5),
+export function normalizeCustomPairingCode(input) {
+    const stripped = input.replace(/-/g, '').toUpperCase();
+    if (stripped.length !== 8) {
+        throw new Error(`custom pairing code must be 8 characters, got ${stripped.length}`);
+    }
+    for (let i = 0; i < stripped.length; i += 1) {
+        if (CROCKFORD_ALPHABET.indexOf(stripped[i]) < 0) {
+            throw new Error(`custom pairing code contains invalid character "${stripped[i]}" (allowed: ${CROCKFORD_ALPHABET})`);
+        }
+    }
+    return stripped;
+}
+export async function createCompanionHello(options = {}) {
+    const normalizedCustomCode = options.customCode !== undefined ? normalizeCustomPairingCode(options.customCode) : null;
+    const [companionEphemeralKeyPair, salt, counter, codeBytes] = await Promise.all([
         X25519.generateKeyPair(),
         randomBytesAsync(32),
-        randomBytesAsync(16)
+        randomBytesAsync(16),
+        normalizedCustomCode !== null ? Promise.resolve(null) : randomBytesAsync(5)
     ]);
-    const pairingCode = bytesToCrockford(codeBytes);
+    const pairingCode = normalizedCustomCode ?? bytesToCrockford(codeBytes);
     const cipher = await pbkdf2DeriveAesCtrKey(TEXT_ENCODER.encode(pairingCode), salt, PBKDF2_ITERATIONS);
     const encrypted = await aesCtrEncrypt(cipher, counter, companionEphemeralKeyPair.pubKey);
     return {