zapo-js 0.2.0 → 1.0.0

package/dist/esm/auth/WaAuthClient.js

@@ -1,12 +1,22 @@
-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';
 import { uint8Equal } from '../util/bytes.js';
 import { toError } from '../util/primitives.js';
 import { getRuntimeOsDisplayName } from '../util/runtime.js';
+/**
+ * Owns the auth/pairing lifecycle and persistence of {@link WaAuthCredentials}.
+ * Exposed as `client.auth` on a {@link WaClient}.
+ *
+ * Lifecycle: construct with options + dependencies, call
+ * {@link loadOrCreateCredentials} to bring credentials online, then either
+ * follow the QR flow (`onQr` callback) or call {@link requestPairingCode} for
+ * the link-code flow.
+ */
 export class WaAuthClient {
     constructor(options, deps) {
+        this.versionOverride = null;
         const deviceBrowser = options.deviceBrowser ?? WA_DEFAULTS.DEVICE_BROWSER;
         const device = Object.freeze({
             browser: deviceBrowser,
@@ -24,6 +34,8 @@ export class WaAuthClient {
         this.callbacks = deps.callbacks ?? {};
         this.authStore = deps.authStore;
         this.signalStore = deps.signalStore;
+        this.preKeyStore = deps.preKeyStore;
+        this.isConnected = deps.isConnected;
         this.credentials = null;
         this.qrFlow = new WaQrFlow({
             logger: this.logger,
@@ -44,9 +56,14 @@ export class WaAuthClient {
                 emitPairingCode: (code) => this.callbacks.onPairingCode?.(code),
                 emitPairingRefresh: (forceManual) => this.callbacks.onPairingRefresh?.(forceManual),
                 emitPaired: (credentials) => this.callbacks.onPaired?.(credentials)
-            }
+            },
+            dangerous: options.dangerous
         });
     }
+    /**
+     * Returns a snapshot of auth readiness flags (connection, registration,
+     * pending QR/pairing prompts).
+     */
     getState(connected = false) {
         return {
             connected,
@@ -55,16 +72,23 @@ export class WaAuthClient {
             hasPairingCode: this.pairingFlow.hasPairingSession()
         };
     }
+    /** Returns the currently-loaded credentials, or `null` before initialization. */
     getCurrentCredentials() {
         return this.credentials;
     }
+    /**
+     * Loads persisted credentials from the auth store, or generates a fresh
+     * set when none exist. Must be called before connecting.
+     */
     async loadOrCreateCredentials() {
         return this.runHandled(async () => {
             this.logger.debug('auth client loadOrCreateCredentials start');
             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,25 +96,56 @@ export class WaAuthClient {
             return this.credentials;
         });
     }
-    buildCommsConfig(socketOptions) {
+    /**
+     * Builds a {@link WaCommsConfig} from the current credentials and the
+     * runtime device/transport options – feeds {@link WaComms}.
+     */
+    async buildCommsConfig(socketOptions, overrides = {}) {
         this.logger.trace('auth client building comms config');
+        const override = this.versionOverride;
+        this.versionOverride = null;
         return buildCommsConfig(this.logger, this.requireCredentials(), socketOptions, {
             deviceBrowser: this.options.deviceBrowser,
             deviceOsDisplayName: this.options.deviceOsDisplayName,
             requireFullSync: this.options.requireFullSync,
-            version: this.options.version
+            version: override ?? this.options.version,
+            mobileTransport: this.options.mobileTransport,
+            noiseTrustedRootCa: overrides.noiseTrustedRootCa,
+            disableNoiseCertificateChainVerification: overrides.disableNoiseCertificateChainVerification ??
+                this.options.dangerous?.disableNoiseCertificateChainVerification
         });
     }
+    /**
+     * One-shot override for the next {@link buildCommsConfig} call: takes
+     * precedence over the user-supplied `version` option, then clears. Used
+     * by the `recoverFromClientTooOld` auto-retry to inject a fresh version
+     * string fetched from `web.whatsapp.com` without mutating the user's
+     * options.
+     */
+    setNextConnectVersion(version) {
+        this.versionOverride = version;
+    }
+    /** Clears the in-memory QR and pairing sessions without touching storage. */
+    // eslint-disable-next-line @typescript-eslint/require-await
     async clearTransientState() {
         this.logger.trace('auth client clear transient state');
         this.qrFlow.clear();
         this.pairingFlow.clearSession();
     }
+    /**
+     * Wipes credentials from memory **and** from the auth store. Does
+     * **not** touch the other store domains (signal, app-state, ...) -
+     * those are cleared separately when {@link WaClient.logout} triggers
+     * the server-side logout path, honoring `options.logoutStoreClear`.
+     * Call this manually only when you want to force a re-pair without
+     * going through the server logout IQ.
+     */
     async clearStoredCredentials() {
         this.logger.warn('auth client clearing stored credentials');
         this.credentials = null;
         await Promise.all([this.authStore.clear(), this.clearTransientState()]);
     }
+    /** Stores the server's noise static key for subsequent handshakes. */
     async persistServerStaticKey(serverStaticKey) {
         this.logger.debug('persisting server static key', {
             keyLength: serverStaticKey.byteLength
@@ -100,6 +155,7 @@ export class WaAuthClient {
             serverStaticKey
         }));
     }
+    /** Stores the "server holds prekeys" flag; persists only when the value changes. */
     async persistServerHasPreKeys(serverHasPreKeys) {
         await this.patchCredentials((credentials) => ({
             ...credentials,
@@ -113,6 +169,10 @@ export class WaAuthClient {
             }
         });
     }
+    /**
+     * Stores the routing-info blob received from the server. Skips persistence
+     * when the value matches the one already on disk.
+     */
     async persistRoutingInfo(routingInfo) {
         this.logger.trace('persisting routing info', {
             byteLength: routingInfo.byteLength
@@ -130,6 +190,7 @@ export class WaAuthClient {
             }
         });
     }
+    /** Clears the persisted routing-info blob (used after a routing error). */
     async clearRoutingInfo() {
         return this.patchCredentials((credentials) => ({
             ...credentials,
@@ -141,6 +202,11 @@ export class WaAuthClient {
             }
         });
     }
+    /**
+     * Persists the per-connection success attributes from the server (LID,
+     * display name, companion key, last-success ts, props versions, ...). Only
+     * persists when at least one attribute actually changed.
+     */
     async persistSuccessAttributes(attributes) {
         let persistDiff;
         const computeDiff = (current, next) => ({
@@ -177,24 +243,56 @@ export class WaAuthClient {
             }
         });
     }
-    async requestPairingCode(phoneNumber, shouldShowPushNotification = false) {
+    /**
+     * Requests an 8-character pairing code for `phoneNumber` (link-code flow).
+     * Pass `customCode` to suggest a specific code; the server still validates
+     * and may return a different one.
+     *
+     * The client must already be connected – kick off `WaClient.connect()` in
+     * parallel, wait for the `auth_pairing_required` event (or any QR), then
+     * call this. The user then enters the returned code in WhatsApp on their
+     * phone under *Linked Devices → Link with phone number instead*.
+     *
+     * @example
+     * ```ts
+     * // Start the handshake; do NOT await – connect() resolves only after pairing
+     * void client.connect()
+     *
+     * // Wait until the pairing screen is ready on the server side
+     * await new Promise<void>((resolve) => client.once('auth_pairing_required', () => resolve()))
+     *
+     * // Phone number in international format, digits only
+     * const code = await client.auth.requestPairingCode('5511999999999')
+     * console.log(`enter this on your phone: ${code.match(/.{1,4}/g)!.join('-')}`)
+     *
+     * // The `connect()` promise resolves after the user types the code:
+     * await new Promise<void>((resolve) => client.once('auth_paired', () => resolve()))
+     * ```
+     */
+    async requestPairingCode(phoneNumber, shouldShowPushNotification = true, customCode) {
+        this.requireConnected();
         this.requireCredentials();
-        this.logger.info('auth client requesting pairing code');
-        return this.runHandled(() => this.pairingFlow.requestPairingCode(phoneNumber, shouldShowPushNotification));
+        this.logger.debug('auth client requesting pairing code');
+        return this.runHandled(() => this.pairingFlow.requestPairingCode(phoneNumber, shouldShowPushNotification, customCode));
     }
+    /** Fetches the ISO country code the server resolved for the current account. */
     async fetchPairingCountryCodeIso() {
+        this.requireConnected();
         this.requireCredentials();
         this.logger.trace('auth client fetching pairing country code ISO');
         return this.runHandled(() => this.pairingFlow.fetchPairingCountryCodeIso());
     }
+    /** Dispatcher: returns `true` when `node` is a pairing-related IQ-set we handled. */
     async handleIncomingIqSet(node) {
         this.logger.trace('auth client handleIncomingIqSet', { id: node.attrs.id });
         return this.runHandled(() => this.pairingFlow.handleIncomingIqSet(node));
     }
+    /** Dispatcher: returns `true` when `node` is a link-code companion notification. */
     async handleLinkCodeNotification(node) {
         this.logger.trace('auth client handleLinkCodeNotification', { id: node.attrs.id });
         return this.runHandled(() => this.pairingFlow.handleLinkCodeNotification(node));
     }
+    /** Dispatcher: returns `true` when `node` is a companion-registration refresh notification. */
     async handleCompanionRegRefreshNotification(node) {
         this.logger.trace('auth client handleCompanionRegRefreshNotification', {
             id: node.attrs.id
@@ -222,15 +320,21 @@ export class WaAuthClient {
     }
     async updateCredentials(credentials) {
         this.logger.trace('auth client update credentials', {
-            registered: credentials?.meJid !== null && credentials?.meJid !== undefined
+            registered: !!credentials?.meJid
         });
         this.credentials = credentials;
         await persistCredentials({
             logger: this.logger,
             authStore: this.authStore,
-            signalStore: this.signalStore
+            signalStore: this.signalStore,
+            preKeyStore: this.preKeyStore
         }, credentials);
     }
+    requireConnected() {
+        if (this.isConnected && !this.isConnected()) {
+            throw new Error('client is not connected');
+        }
+    }
     requireCredentials() {
         if (!this.credentials) {
             throw new Error('credentials are not initialized');

package/dist/esm/auth/credentials-flow.js

@@ -0,0 +1,202 @@
+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/index.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();
+    if (!existing) {
+        const credentials = await createFreshAndPersistCredentials(args);
+        args.logger.info('created fresh auth credentials');
+        return credentials;
+    }
+    args.logger.debug('auth credentials loaded from store', {
+        registered: existing.meJid !== null && existing.meJid !== undefined,
+        hasServerStaticKey: existing.serverStaticKey !== null && existing.serverStaticKey !== undefined
+    });
+    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, args.preKeyStore, existing);
+    args.logger.trace('auth credentials restored into signal store');
+    return existing;
+}
+export async function persistCredentials(args, credentials) {
+    args.logger.trace('persisting auth credentials', {
+        registered: credentials.meJid !== null && credentials.meJid !== undefined
+    });
+    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 } : {})
+    };
+}
+async function resolveVersion(version) {
+    if (version === undefined)
+        return undefined;
+    if (typeof version === 'string')
+        return version;
+    const resolved = await version();
+    if (typeof resolved !== 'string' || resolved.length === 0) {
+        throw new Error('version resolver returned a non-string value');
+    }
+    return resolved;
+}
+export async 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,
+        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
+            }
+        };
+    }
+    const versionBase = await resolveVersion(clientOptions.version);
+    return {
+        url: socketOptions.url,
+        urls: socketOptions.urls,
+        protocols: socketOptions.protocols,
+        dispatcher: toProxyDispatcher(wsProxy),
+        agent: toProxyAgent(wsProxy),
+        connectTimeoutMs: socketOptions.connectTimeoutMs,
+        reconnectIntervalMs: socketOptions.reconnectIntervalMs,
+        timeoutIntervalMs: socketOptions.timeoutIntervalMs,
+        maxReconnectAttempts: socketOptions.maxReconnectAttempts,
+        noise: {
+            clientStaticKeyPair: credentials.noiseKeyPair,
+            isRegistered: registered,
+            serverStaticKey: credentials.serverStaticKey,
+            routingInfo: credentials.routingInfo,
+            trustedRootCa: clientOptions.noiseTrustedRootCa,
+            verifyCertificateChain: clientOptions.disableNoiseCertificateChainVerification
+                ? false
+                : undefined,
+            loginPayloadConfig: loginIdentity
+                ? {
+                    username: loginIdentity.username,
+                    device: loginIdentity.device,
+                    deviceBrowser: clientOptions.deviceBrowser,
+                    deviceOsDisplayName: clientOptions.deviceOsDisplayName,
+                    versionBase
+                }
+                : undefined,
+            registrationPayloadConfig: !loginIdentity
+                ? {
+                    registrationInfo: credentials.registrationInfo,
+                    signedPreKey: credentials.signedPreKey,
+                    deviceBrowser: clientOptions.deviceBrowser,
+                    deviceOsDisplayName: clientOptions.deviceOsDisplayName,
+                    requireFullSync: clientOptions.requireFullSync,
+                    versionBase
+                }
+                : undefined
+        }
+    };
+}
+async function createFreshCredentials(signalStore, preKeyStore, logger) {
+    logger.trace('creating fresh credentials');
+    const [noiseKeyPair, registrationBundle, advSecretKey] = await Promise.all([
+        X25519.generateKeyPair(),
+        createAndStoreInitialKeys(signalStore, preKeyStore),
+        randomBytesAsync(32)
+    ]);
+    return {
+        noiseKeyPair,
+        registrationInfo: registrationBundle.registrationInfo,
+        signedPreKey: registrationBundle.signedPreKey,
+        serverHasPreKeys: false,
+        advSecretKey
+    };
+}
+async function createFreshAndPersistCredentials(args) {
+    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, args.preKeyStore, credentials);
+    return credentials;
+}
+async function hasValidSignedPreKey(logger, credentials) {
+    try {
+        const serializedPubKey = toSerializedPubKey(credentials.signedPreKey.keyPair.pubKey);
+        const valid = await xeddsaVerify(toRawPubKey(credentials.registrationInfo.identityKeyPair.pubKey), serializedPubKey, credentials.signedPreKey.signature);
+        logger.trace('signed pre-key validation completed', { valid });
+        return valid;
+    }
+    catch (error) {
+        logger.warn('signed pre-key validation failed with exception', {
+            message: toError(error).message
+        });
+        return false;
+    }
+}
+async function restoreSignalStore(signalStore, preKeyStore, credentials) {
+    await Promise.all([
+        signalStore.setRegistrationInfo(credentials.registrationInfo),
+        signalStore.setSignedPreKey(credentials.signedPreKey),
+        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 { ADV_PREFIX_HOSTED_ACCOUNT_SIGNATURE, computeAdvIdentityHmac, generateDeviceSignature, verifyDeviceIdentityAccountSignature } from '../../signal/attestation/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, uint8TimingSafeEqual } 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 = true, 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,
@@ -72,7 +65,7 @@ export class WaPairingFlow {
             finished: false
         };
         this.opts.callbacks.emitPairingCode(companionHello.pairingCode);
-        this.opts.logger.info('pairing code emitted', {
+        this.opts.logger.debug('pairing code emitted', {
             phoneJid,
             createdAtSeconds: this.pairingSession.createdAtSeconds
         });
@@ -90,21 +83,19 @@ export class WaPairingFlow {
         return iso;
     }
     async handleIncomingIqSet(node) {
-        this.opts.logger.trace('pairing flow received iq:set', {
-            id: node.attrs.id,
-            from: node.attrs.from
-        });
+        const iqLogger = this.opts.logger.child({ id: node.attrs.id });
+        iqLogger.trace('pairing flow received iq:set', { 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 });
+            iqLogger.debug('handling pair-device stanza');
             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 });
+            iqLogger.debug('handling pair-success stanza');
             await this.handlePairSuccess(node, firstChild);
             return true;
         }
@@ -131,7 +122,7 @@ export class WaPairingFlow {
             }
             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', {
+                this.opts.logger.debug('received pairing refresh notification', {
                     forceManualRefresh: linkCodeNode.attrs.force_manual_refresh === 'true'
                 });
                 this.opts.callbacks.emitPairingRefresh(linkCodeNode.attrs.force_manual_refresh === 'true');
@@ -157,7 +148,7 @@ export class WaPairingFlow {
             node,
             typeOverride: WA_SIGNALING.COMPANION_REG_REFRESH_NOTIFICATION
         }));
-        this.opts.logger.info('handled companion_reg_refresh notification');
+        this.opts.logger.debug('handled companion_reg_refresh notification');
         this.opts.qrFlow.refreshCurrentQr();
         return true;
     }
@@ -167,10 +158,10 @@ export class WaPairingFlow {
         await this.rotateAdvSecret(this.requireCredentials());
         await this.opts.socket.sendNode(buildIqResultNode(iqNode));
         this.opts.qrFlow.setRefs(refs);
-        this.opts.logger.info('pair-device refs updated', { refsCount: refs.length });
+        this.opts.logger.debug('pair-device refs updated', { refsCount: refs.length });
     }
     async handlePairSuccess(iqNode, pairSuccessNode) {
-        this.opts.logger.info('processing pair-success node');
+        this.opts.logger.debug('processing pair-success node');
         const credentials = this.requireCredentials();
         const [deviceIdentityNode, deviceNode, platformNode] = findNodeChildrenByTags(pairSuccessNode, [WA_NODE_TAGS.DEVICE_IDENTITY, 'device', WA_NODE_TAGS.PLATFORM]);
         if (!deviceIdentityNode || !deviceNode || !platformNode) {
@@ -186,15 +177,22 @@ 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 = computeAdvIdentityHmac(credentials.advSecretKey, hmacInput);
+            if (!uint8TimingSafeEqual(expectedHmac, wrappedHmac)) {
+                this.opts.logger.error('pair-success hmac mismatch', {
+                    meJid: deviceNode.attrs.jid,
+                    meLid: deviceNode.attrs.lid,
+                    platform: platformNode.attrs.name,
+                    isHosted
+                });
+                throw new Error('pair-success HMAC validation failed');
+            }
         }
-        const { signedIdentity, keyIndex, responseIdentityBytes } = await this.buildPairSuccessResponseIdentity(credentials, wrappedDetails, isHosted);
+        const { signedIdentity, keyIndex, responseIdentityBytes } = await this.buildPairSuccessResponseIdentity(credentials, wrappedDetails);
         const nextCredentials = {
             ...credentials,
             signedIdentity,
@@ -235,19 +233,25 @@ export class WaPairingFlow {
         this.opts.callbacks.emitPaired(nextCredentials);
         this.opts.logger.debug('pair-success completed and paired event emitted');
     }
-    async buildPairSuccessResponseIdentity(credentials, wrappedDetails, isHosted) {
+    async buildPairSuccessResponseIdentity(credentials, wrappedDetails) {
         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 isDeviceHosted = advDeviceIdentity.deviceType === proto.ADVEncryptionType.HOSTED;
+        if (this.opts.dangerous?.disableAdvSignatureVerification !== true) {
+            const validAccountSignature = await verifyDeviceIdentityAccountSignature(details, accountSignature, localIdentity.pubKey, accountSignatureKey, isDeviceHosted);
+            if (!validAccountSignature) {
+                this.opts.logger.error('pair-success account signature invalid', {
+                    keyIndex: advDeviceIdentity.keyIndex ?? 0,
+                    isDeviceHosted
+                });
+                throw new Error('pair-success account signature validation failed');
+            }
+        }
+        signedIdentity.deviceSignature = await generateDeviceSignature(details, localIdentity, accountSignatureKey, false);
         const responseIdentityBytes = proto.ADVSignedDeviceIdentity.encode({
             details: signedIdentity.details,
             accountSignature: signedIdentity.accountSignature,
@@ -283,7 +287,9 @@ export class WaPairingFlow {
         }
         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');
+            this.opts.logger.warn('primary_hello ref mismatch ignored', {
+                phoneJid: pairingSession.phoneJid
+            });
             return;
         }
         const nowSeconds = Math.floor(Date.now() / 1000);
@@ -312,7 +318,7 @@ export class WaPairingFlow {
             advSecretKey: finish.advSecret
         });
         pairingSession.finished = true;
-        this.opts.logger.info('primary_hello completed with companion_finish success');
+        this.opts.logger.debug('primary_hello completed with companion_finish success');
     }
     async rotateAdvSecret(credentials) {
         const nextCredentials = {