zapo-js 0.1.2 → 0.3.0

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,13 +45,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
         });
     }
     getState(connected = false) {
         return {
             connected,
-            registered: hasMeJid(this.credentials),
+            registered: this.credentials?.meJid !== null && this.credentials?.meJid !== undefined,
             hasQr: this.qrFlow.hasQr(),
             hasPairingCode: this.pairingFlow.hasPairingSession()
         };
@@ -64,20 +66,27 @@ 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: hasMeJid(this.credentials)
+                registered: this.credentials?.meJid !== null && this.credentials?.meJid !== undefined
             });
             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
+            requireFullSync: this.options.requireFullSync,
+            version: this.options.version,
+            mobileTransport: this.options.mobileTransport,
+            noiseTrustedRootCa: overrides.noiseTrustedRootCa,
+            disableNoiseCertificateChainVerification: overrides.disableNoiseCertificateChainVerification ??
+                this.options.dangerous?.disableNoiseCertificateChainVerification
         });
     }
     async clearTransientState() {
@@ -87,9 +96,8 @@ export class WaAuthClient {
     }
     async clearStoredCredentials() {
         this.logger.warn('auth client clearing stored credentials');
-        await this.authStore.clear();
         this.credentials = null;
-        await this.clearTransientState();
+        await Promise.all([this.authStore.clear(), this.clearTransientState()]);
     }
     async persistServerStaticKey(serverStaticKey) {
         this.logger.debug('persisting server static key', {
@@ -142,53 +150,45 @@ export class WaAuthClient {
         });
     }
     async persistSuccessAttributes(attributes) {
-        await this.patchCredentials((credentials) => {
-            return {
-                ...credentials,
-                meLid: attributes.meLid ?? credentials.meLid,
-                meDisplayName: attributes.meDisplayName ?? credentials.meDisplayName,
-                companionEncStatic: attributes.companionEncStatic ?? credentials.companionEncStatic,
-                lastSuccessTs: attributes.lastSuccessTs ?? credentials.lastSuccessTs,
-                propsVersion: attributes.propsVersion ?? credentials.propsVersion,
-                abPropsVersion: attributes.abPropsVersion ?? credentials.abPropsVersion,
-                connectionLocation: attributes.connectionLocation ?? credentials.connectionLocation,
-                accountCreationTs: attributes.accountCreationTs ?? credentials.accountCreationTs
-            };
-        }, {
-            shouldPersist: (current, next) => next.meLid !== current.meLid ||
-                next.meDisplayName !== current.meDisplayName ||
-                (current.companionEncStatic === undefined) !==
-                    (next.companionEncStatic === undefined) ||
+        let persistDiff;
+        const computeDiff = (current, next) => ({
+            lidChanged: next.meLid !== current.meLid,
+            displayNameChanged: next.meDisplayName !== current.meDisplayName,
+            companionChanged: (current.companionEncStatic === undefined) !==
+                (next.companionEncStatic === undefined) ||
                 (current.companionEncStatic !== undefined &&
                     next.companionEncStatic !== undefined &&
-                    !uint8Equal(current.companionEncStatic, next.companionEncStatic)) ||
-                next.lastSuccessTs !== current.lastSuccessTs ||
-                next.propsVersion !== current.propsVersion ||
-                next.abPropsVersion !== current.abPropsVersion ||
-                next.connectionLocation !== current.connectionLocation ||
-                next.accountCreationTs !== current.accountCreationTs,
-            onPersist: (current, next) => {
-                this.logger.debug('persisting success attributes', {
-                    lidChanged: next.meLid !== current.meLid,
-                    displayNameChanged: next.meDisplayName !== current.meDisplayName,
-                    companionChanged: (current.companionEncStatic === undefined) !==
-                        (next.companionEncStatic === undefined) ||
-                        (current.companionEncStatic !== undefined &&
-                            next.companionEncStatic !== undefined &&
-                            !uint8Equal(current.companionEncStatic, next.companionEncStatic)),
-                    lastSuccessTsChanged: next.lastSuccessTs !== current.lastSuccessTs,
-                    propsVersionChanged: next.propsVersion !== current.propsVersion,
-                    abPropsVersionChanged: next.abPropsVersion !== current.abPropsVersion,
-                    connectionLocationChanged: next.connectionLocation !== current.connectionLocation,
-                    accountCreationTsChanged: next.accountCreationTs !== current.accountCreationTs
-                });
+                    !uint8Equal(current.companionEncStatic, next.companionEncStatic)),
+            lastSuccessTsChanged: next.lastSuccessTs !== current.lastSuccessTs,
+            propsVersionChanged: next.propsVersion !== current.propsVersion,
+            abPropsVersionChanged: next.abPropsVersion !== current.abPropsVersion,
+            connectionLocationChanged: next.connectionLocation !== current.connectionLocation,
+            accountCreationTsChanged: next.accountCreationTs !== current.accountCreationTs
+        });
+        await this.patchCredentials((credentials) => ({
+            ...credentials,
+            meLid: attributes.meLid ?? credentials.meLid,
+            meDisplayName: attributes.meDisplayName ?? credentials.meDisplayName,
+            companionEncStatic: attributes.companionEncStatic ?? credentials.companionEncStatic,
+            lastSuccessTs: attributes.lastSuccessTs ?? credentials.lastSuccessTs,
+            propsVersion: attributes.propsVersion ?? credentials.propsVersion,
+            abPropsVersion: attributes.abPropsVersion ?? credentials.abPropsVersion,
+            connectionLocation: attributes.connectionLocation ?? credentials.connectionLocation,
+            accountCreationTs: attributes.accountCreationTs ?? credentials.accountCreationTs
+        }), {
+            shouldPersist: (current, next) => {
+                persistDiff = computeDiff(current, next);
+                return Object.values(persistDiff).some(Boolean);
+            },
+            onPersist: () => {
+                this.logger.debug('persisting success attributes', persistDiff);
             }
         });
     }
-    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();
@@ -230,13 +230,14 @@ export class WaAuthClient {
     }
     async updateCredentials(credentials) {
         this.logger.trace('auth client update credentials', {
-            registered: hasMeJid(credentials)
+            registered: credentials?.meJid !== null && credentials?.meJid !== undefined
         });
         this.credentials = credentials;
         await persistCredentials({
             logger: this.logger,
             authStore: this.authStore,
-            signalStore: this.signalStore
+            signalStore: this.signalStore,
+            preKeyStore: this.preKeyStore
         }, credentials);
     }
     requireCredentials() {
@@ -250,6 +251,3 @@ export class WaAuthClient {
         this.callbacks.onError?.(error);
     }
 }
-function hasMeJid(credentials) {
-    return credentials?.meJid !== null && credentials?.meJid !== undefined;
-}

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

@@ -0,0 +1,190 @@
+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();
+    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 } : {})
+    };
+}
+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,
+        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,
+        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: clientOptions.version
+                }
+                : undefined,
+            registrationPayloadConfig: !loginIdentity
+                ? {
+                    registrationInfo: credentials.registrationInfo,
+                    signedPreKey: credentials.signedPreKey,
+                    deviceBrowser: clientOptions.deviceBrowser,
+                    deviceOsDisplayName: clientOptions.deviceOsDisplayName,
+                    requireFullSync: clientOptions.requireFullSync,
+                    versionBase: clientOptions.version
+                }
+                : 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/index.js

@@ -1,4 +1,2 @@
 export * from './types.js';
 export { WaAuthClient } from './WaAuthClient.js';
-export { completeCompanionFinish, createCompanionHello } from './pairing/WaPairingCodeCrypto.js';
-export { WaAuthSqliteStore } from '../store/providers/sqlite/auth.store.js';

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

@@ -1,13 +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 { buildCompanionFinishRequestNode, buildCompanionHelloRequestNode, buildGetCountryCodeRequestNode, buildIqResultNode, buildNotificationAckNode } 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 { buildAckNode, buildIqResultNode } from '../../transport/node/builders/global.js';
+import { buildCompanionFinishRequestNode, buildCompanionHelloRequestNode, buildGetCountryCodeRequestNode } from '../../transport/node/builders/pairing.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;
@@ -20,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,
@@ -118,7 +112,10 @@ export class WaPairingFlow {
             id: node.attrs.id,
             stage: linkCodeNode.attrs.stage
         });
-        await this.opts.socket.sendNode(buildNotificationAckNode(node));
+        await this.opts.socket.sendNode(buildAckNode({
+            kind: 'notification',
+            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);
@@ -146,18 +143,24 @@ export class WaPairingFlow {
         if (!hasExpectedChild) {
             return false;
         }
-        await this.opts.socket.sendNode(buildNotificationAckNode(node, WA_SIGNALING.COMPANION_REG_REFRESH_NOTIFICATION));
+        // Rotate first so we don't ack success before local credential state is durably updated.
         await this.rotateAdvSecret(this.requireCredentials());
+        await this.opts.socket.sendNode(buildAckNode({
+            kind: 'notification',
+            node,
+            typeOverride: WA_SIGNALING.COMPANION_REG_REFRESH_NOTIFICATION
+        }));
         this.opts.logger.info('handled companion_reg_refresh notification');
         this.opts.qrFlow.refreshCurrentQr();
         return true;
     }
     async handlePairDevice(iqNode, pairDeviceNode) {
         const refs = getNodeChildrenNonEmptyUtf8ByTag(pairDeviceNode, WA_NODE_TAGS.REF, 'pair-device.ref');
+        // Commit adv-secret rotation before sending IQ success to avoid protocol/state divergence.
         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 });
-        await this.opts.socket.sendNode(buildIqResultNode(iqNode));
     }
     async handlePairSuccess(iqNode, pairSuccessNode) {
         this.opts.logger.info('processing pair-success node');
@@ -176,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 = {
@@ -231,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 {
@@ -45,8 +59,8 @@ export async function completeCompanionFinish(args) {
     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([
+    const [sharedEphemeral, bundleSalt, bundleSecret, bundleIv] = await Promise.all([
+        X25519.scalarMult(args.companionEphemeralPrivKey, primaryEphemeralPub),
         randomBytesAsync(32),
         randomBytesAsync(32),
         randomBytesAsync(12)
@@ -58,9 +72,11 @@ export async function completeCompanionFinish(args) {
         args.primaryIdentityPub,
         bundleSecret
     ]);
-    const encryptedBundle = await aesGcmEncrypt(bundleEncryptionKey, bundleIv, plaintextBundle);
+    const [encryptedBundle, sharedIdentity] = await Promise.all([
+        aesGcmEncrypt(bundleEncryptionKey, bundleIv, plaintextBundle),
+        X25519.scalarMult(args.registrationIdentityKeyPair.privKey, args.primaryIdentityPub)
+    ]);
     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 {