zapo-js 1.3.0 → 1.5.0

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

@@ -6,7 +6,7 @@ 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';
+import { parseOptionalInt, toError } from '../util/primitives.js';
 export async function loadOrCreateCredentials(args) {
     args.logger.trace('auth credentials loadOrCreate start');
     const existing = await args.authStore.load();
@@ -61,6 +61,26 @@ async function resolveVersion(version) {
     }
     return resolved;
 }
+/**
+ * Validates the user-supplied `version` string against the transport it will
+ * feed. A mobile session sends the version as the four-part Android app
+ * version (`2.YY.WW.RR`) in the login payload, so it must have exactly four
+ * numeric parts. A web session advertises up to five parts (`2.3000.x[.y.z]`),
+ * so three to five numeric parts are accepted.
+ */
+function assertValidVersion(version, mobile) {
+    const parts = version.split('.');
+    const allNumeric = parts.every((part) => parseOptionalInt(part) !== undefined);
+    if (mobile) {
+        if (parts.length !== 4 || !allNumeric) {
+            throw new Error(`mobile session requires a 4-part numeric version (e.g. 2.26.27.70), got: ${version}`);
+        }
+        return;
+    }
+    if (parts.length < 3 || parts.length > 5 || !allNumeric) {
+        throw new Error(`web session requires a 3- to 5-part numeric version (e.g. 2.3000.1040229458), got: ${version}`);
+    }
+}
 export async function buildCommsConfig(logger, credentials, socketOptions, clientOptions) {
     const meJid = credentials.meJid;
     const registered = meJid !== null && meJid !== undefined;
@@ -81,6 +101,12 @@ export async function buildCommsConfig(logger, credentials, socketOptions, clien
                 ? 'credentials'
                 : 'none'
     });
+    const resolvedVersion = effectiveMobileTransport && clientOptions.mobileAppVersionOverride !== undefined
+        ? undefined
+        : await resolveVersion(clientOptions.version);
+    if (resolvedVersion !== undefined) {
+        assertValidVersion(resolvedVersion, Boolean(effectiveMobileTransport));
+    }
     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');
@@ -88,11 +114,18 @@ export async function buildCommsConfig(logger, credentials, socketOptions, clien
         if (!loginIdentity) {
             throw new Error('mobileTransport requires registered credentials (meJid) – run the mobile bridge flow first');
         }
+        if (clientOptions.mobileAppVersionOverride !== undefined) {
+            assertValidVersion(clientOptions.mobileAppVersionOverride, true);
+        }
+        const appVersionOverride = clientOptions.mobileAppVersionOverride ?? resolvedVersion;
+        const deviceInfo = appVersionOverride
+            ? { ...effectiveMobileTransport.deviceInfo, appVersion: appVersionOverride }
+            : effectiveMobileTransport.deviceInfo;
         const loginPayload = buildMobileLoginPayload({
             username: loginIdentity.username,
             device: loginIdentity.device,
             passive: effectiveMobileTransport.passive ?? false,
-            deviceInfo: effectiveMobileTransport.deviceInfo,
+            deviceInfo,
             pushName: effectiveMobileTransport.pushName,
             yearClass: effectiveMobileTransport.yearClass,
             memClass: effectiveMobileTransport.memClass
@@ -117,7 +150,7 @@ export async function buildCommsConfig(logger, credentials, socketOptions, clien
             }
         };
     }
-    const versionBase = await resolveVersion(clientOptions.version);
+    const versionBase = resolvedVersion;
     return {
         url: socketOptions.url,
         urls: socketOptions.urls,

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

@@ -0,0 +1,206 @@
+import { decodePrimaryEphemeralIdentity, deriveEncryptionKey, deriveVerificationCode, encryptPairingRequest, generateCompanionEphemeralIdentity } from '../pairing/shortcake-crypto.js';
+import { hkdf, hmacSha256Sign, randomBytesAsync } from '../../crypto/index.js';
+import { proto } from '../../proto.js';
+import { WA_DEFAULTS, WA_NODE_TAGS, WA_NOTIFICATION_TYPES } from '../../protocol/constants.js';
+import { buildAckNode } from '../../transport/node/builders/global.js';
+import { buildGetPasskeyRequestOptionsRequestNode, buildSetCompanionNonceRequestNode, buildSetEncryptedPairingRequestRequestNode, buildSetPasskeyPrologueRequestNode, buildShortcakeGetRefRequestNode } from '../../transport/node/builders/shortcake.js';
+import { decodeNodeContentUtf8OrBytes, findNodeChild } from '../../transport/node/helpers.js';
+import { assertIqResult } from '../../transport/node/query.js';
+import { TEXT_DECODER, TEXT_ENCODER } from '../../util/bytes.js';
+/** HKDF info for the pairing handoff HMAC key (derived from the ADV secret). */
+const HANDOFF_KEY_INFO = TEXT_ENCODER.encode('shortcake-passkey-handoff-v1');
+const HANDOFF_KEY_TTL_MS = 5 * 60 * 1000;
+const Stage = Object.freeze({
+    Idle: 'idle',
+    WaitingForPrimaryIdentity: 'waiting_for_primary_identity',
+    WaitingForConfirmation: 'waiting_for_confirmation',
+    WaitingForPairing: 'waiting_for_pairing'
+});
+/**
+ * Drives the companion side of the WhatsApp "Shortcake" passkey-linking
+ * handshake (the `xmlns="md"` IQ exchange + commit/reveal ECDH). It owns the
+ * wire protocol and crypto only; the WebAuthn assertion and the registration
+ * payload are injected by the caller.
+ */
+export class WaShortcakeFlow {
+    constructor(options) {
+        this.opts = options;
+        this.session = null;
+        this.handoffKey = null;
+    }
+    hasSession() {
+        return this.session !== null;
+    }
+    clearSession() {
+        this.session = null;
+        this.handoffKey = null;
+    }
+    /**
+     * Runs the prologue: fetch the request options, obtain the WebAuthn
+     * assertion (external), fetch the ref, build the companion ephemeral
+     * identity + commitment, and send the `passkey_prologue` IQ.
+     */
+    async executePrologue(args = {}) {
+        const deviceType = this.opts.deviceType ?? proto.DeviceProps.PlatformType.CHROME;
+        const requestOptions = args.requestOptions ?? (await this.requestPasskeyRequestOptions());
+        const assertion = await this.opts.signAssertion(requestOptions);
+        const ref = await this.requestRef();
+        const companion = await generateCompanionEphemeralIdentity({ ref, deviceType });
+        let pairingHandoffProof = args.pairingHandoffProof;
+        const handoffKey = this.handoffKey;
+        this.handoffKey = null;
+        if (pairingHandoffProof === undefined &&
+            handoffKey !== null &&
+            Date.now() - handoffKey.ts < HANDOFF_KEY_TTL_MS) {
+            pairingHandoffProof = hmacSha256Sign(handoffKey.hmac, companion.prologuePayloadBytes);
+        }
+        const skipHandoffUx = pairingHandoffProof !== undefined;
+        const response = await this.opts.socket.query(buildSetPasskeyPrologueRequestNode({
+            credentialId: assertion.credentialId,
+            webauthnAssertion: assertion.webauthnAssertion,
+            prologuePayload: companion.prologuePayloadBytes,
+            pairingHandoffProof
+        }), WA_DEFAULTS.IQ_TIMEOUT_MS);
+        assertIqResult(response, 'shortcake set-passkey-prologue');
+        this.session = {
+            companion,
+            ref,
+            deviceType,
+            skipHandoffUx,
+            stage: Stage.WaitingForPrimaryIdentity,
+            encryptionKey: null,
+            verificationCode: null
+        };
+        this.opts.logger.debug('shortcake prologue sent', { ref, skipHandoffUx });
+        this.opts.callbacks?.emitPrologueSent?.();
+    }
+    /**
+     * Routes the two server-pushed Shortcake notifications. Returns `true` when
+     * the notification was a Shortcake one (and was consumed):
+     * - `passkey_prologue_request` kicks the flow off (server forces passkey,
+     *   often right after a pairing-code `companion_finish`); the WebAuthn
+     *   options are usually embedded.
+     * - `crsc_continuation` carries the primary's ephemeral identity.
+     */
+    async handleIncomingNotification(node) {
+        if (node.attrs.type === WA_NOTIFICATION_TYPES.PASSKEY_PROLOGUE_REQUEST) {
+            return this.handlePasskeyPrologueRequest(node);
+        }
+        if (node.attrs.type === WA_NOTIFICATION_TYPES.CRSC_CONTINUATION) {
+            return this.handlePrimaryEphemeralIdentity(node);
+        }
+        return false;
+    }
+    async handlePasskeyPrologueRequest(node) {
+        await this.ackNotification(node);
+        await this.stashHandoffKeyAndRotateAdv();
+        const optionsNode = findNodeChild(node, WA_NODE_TAGS.PASSKEY_REQUEST_OPTIONS);
+        const requestOptions = optionsNode
+            ? decodeNodeContentUtf8OrBytes(optionsNode.content, 'shortcake.passkey_request_options')
+            : undefined;
+        this.opts.logger.debug('shortcake prologue requested by server', {
+            embeddedOptions: optionsNode !== undefined
+        });
+        await this.executePrologue({ requestOptions });
+        return true;
+    }
+    /**
+     * Derives a pairing handoff HMAC key from the current ADV secret and rotates
+     * the ADV secret (matching the official clients). The derived key signs the
+     * next prologue's handoff proof; the rotated secret goes into the eventual
+     * `PairingRequest`.
+     */
+    async stashHandoffKeyAndRotateAdv() {
+        const credentials = this.opts.auth.getCredentials();
+        if (!credentials) {
+            return;
+        }
+        this.handoffKey = {
+            hmac: hkdf(credentials.advSecretKey, null, HANDOFF_KEY_INFO, 32),
+            ts: Date.now()
+        };
+        await this.opts.auth.updateCredentials({
+            ...credentials,
+            advSecretKey: await randomBytesAsync(32)
+        });
+    }
+    async handlePrimaryEphemeralIdentity(node) {
+        const child = findNodeChild(node, WA_NODE_TAGS.PRIMARY_EPHEMERAL_IDENTITY);
+        if (!child) {
+            return false;
+        }
+        const session = this.session;
+        if (!session || session.stage !== Stage.WaitingForPrimaryIdentity) {
+            this.opts.logger.warn('shortcake primary identity ignored: no active prologue');
+            await this.ackNotification(node);
+            return true;
+        }
+        await this.ackNotification(node);
+        const primary = decodePrimaryEphemeralIdentity(decodeNodeContentUtf8OrBytes(child.content, 'shortcake.primary_ephemeral_identity'));
+        const nonceResponse = await this.opts.socket.query(buildSetCompanionNonceRequestNode(session.companion.companionNonce), WA_DEFAULTS.IQ_TIMEOUT_MS);
+        assertIqResult(nonceResponse, 'shortcake set-companion-nonce');
+        const verificationCode = deriveVerificationCode(session.companion.companionNonce, primary);
+        const encryptionKey = await deriveEncryptionKey({
+            companionPrivKey: session.companion.keyPair.privKey,
+            primaryPublicKey: primary.publicKey,
+            deviceType: session.deviceType,
+            ref: session.ref
+        });
+        session.encryptionKey = encryptionKey;
+        session.verificationCode = verificationCode;
+        session.stage = Stage.WaitingForConfirmation;
+        this.opts.logger.debug('shortcake verification code ready');
+        this.opts.callbacks?.emitVerificationCode?.(verificationCode);
+        await this.confirmVerificationCode();
+        return true;
+    }
+    /** Current verification code, once derived. */
+    getVerificationCode() {
+        return this.session?.verificationCode ?? null;
+    }
+    /**
+     * Confirms the verification code: builds + AES-GCM seals the pairing request
+     * and sends the `encrypted_pairing_request` IQ.
+     */
+    async confirmVerificationCode() {
+        const session = this.session;
+        if (!session || session.stage !== Stage.WaitingForConfirmation || !session.encryptionKey) {
+            throw new Error('shortcake: no verification code awaiting confirmation');
+        }
+        const credentials = this.opts.auth.getCredentials();
+        if (!credentials) {
+            throw new Error('shortcake: credentials are not initialized');
+        }
+        const plaintext = proto.PairingRequest.encode({
+            companionPublicKey: credentials.noiseKeyPair.pubKey,
+            companionIdentityKey: credentials.registrationInfo.identityKeyPair.pubKey,
+            advSecret: credentials.advSecretKey
+        }).finish();
+        const envelope = await encryptPairingRequest(session.encryptionKey, plaintext);
+        const response = await this.opts.socket.query(buildSetEncryptedPairingRequestRequestNode(envelope), WA_DEFAULTS.IQ_TIMEOUT_MS);
+        assertIqResult(response, 'shortcake set-encrypted-pairing-request');
+        session.stage = Stage.WaitingForPairing;
+        this.opts.logger.debug('shortcake encrypted pairing request sent');
+    }
+    async requestPasskeyRequestOptions() {
+        const response = await this.opts.socket.query(buildGetPasskeyRequestOptionsRequestNode(), WA_DEFAULTS.IQ_TIMEOUT_MS);
+        assertIqResult(response, 'shortcake get-passkey-request-options');
+        const optionsNode = findNodeChild(response, WA_NODE_TAGS.PASSKEY_REQUEST_OPTIONS);
+        if (!optionsNode) {
+            throw new Error('shortcake: get-passkey-request-options response missing options');
+        }
+        return decodeNodeContentUtf8OrBytes(optionsNode.content, 'shortcake.passkey_request_options');
+    }
+    async requestRef() {
+        const response = await this.opts.socket.query(buildShortcakeGetRefRequestNode(), WA_DEFAULTS.IQ_TIMEOUT_MS);
+        assertIqResult(response, 'shortcake get-ref');
+        const refNode = findNodeChild(response, WA_NODE_TAGS.REF);
+        if (!refNode) {
+            throw new Error('shortcake: get-ref response missing ref');
+        }
+        return TEXT_DECODER.decode(decodeNodeContentUtf8OrBytes(refNode.content, 'shortcake.ref'));
+    }
+    async ackNotification(node) {
+        await this.opts.socket.sendNode(buildAckNode({ kind: 'notification', node }));
+    }
+}

package/dist/esm/auth/pairing/companion-host.js

@@ -0,0 +1,140 @@
+import { aesCtrDecrypt, aesCtrEncrypt, aesGcmDecrypt, hkdf, pbkdf2Sha256, randomBytesAsync, toRawPubKey, X25519 } from '../../crypto/index.js';
+import { proto } from '../../proto.js';
+import { WA_PAIRING_KDF_INFO } from '../../protocol/index.js';
+import { computeAdvIdentityHmac, generateDeviceIdentityAccountSignature, signKeyIndexList } from '../../signal/index.js';
+import { concatBytes, decodeBase64Url, TEXT_ENCODER, uint8Equal } from '../../util/bytes.js';
+const PEM_HKDF_INFO = TEXT_ENCODER.encode('Canonical Ent Companion Nonce Encrypt');
+const PBKDF2_ITERATIONS = 131072;
+const PAIRING_AES_KEY_BYTES = 32;
+/**
+ * Parses a companion pairing QR of the form
+ * `ref,noisePubB64,identityPubB64,advSecretB64,platform`. The `ref` may itself
+ * contain commas, so the four trailing fields are taken from the end.
+ *
+ * @throws when fewer than 5 comma-separated fields are present.
+ */
+export function parseCompanionQr(qr) {
+    const parts = qr.split(',');
+    if (parts.length < 5) {
+        throw new Error(`companion qr must have at least 5 comma-separated parts, got ${parts.length}`);
+    }
+    const platform = parts[parts.length - 1];
+    const advSecretB64 = parts[parts.length - 2];
+    const identityPubB64 = parts[parts.length - 3];
+    const noisePubB64 = parts[parts.length - 4];
+    const ref = parts.slice(0, parts.length - 4).join(',');
+    return {
+        ref,
+        noisePublicKey: decodeBase64Url(noisePubB64, 'companionQr.noisePublicKey'),
+        identityPublicKey: decodeBase64Url(identityPubB64, 'companionQr.identityPublicKey'),
+        advSecretKey: decodeBase64Url(advSecretB64, 'companionQr.advSecretKey'),
+        platform
+    };
+}
+/**
+ * Builds the account-signed `ADVSignedKeyIndexList` bytes for the current device
+ * set. The zero-valued `accountType` enum is omitted to match the phone's byte
+ * layout.
+ */
+export async function buildSignedKeyIndexList(input) {
+    const details = proto.ADVKeyIndexList.encode({
+        rawId: input.rawId,
+        timestamp: input.timestampSeconds,
+        currentIndex: input.currentIndex,
+        validIndexes: [...input.validIndexes]
+    }).finish();
+    const accountSignature = await signKeyIndexList(details, input.accountIdentityKeyPair);
+    return proto.ADVSignedKeyIndexList.encode({ details, accountSignature }).finish();
+}
+/**
+ * Builds the signed device identity and key-index list for a linking companion.
+ * The byte layout mirrors WhatsApp's phone (and the in-repo fake-server
+ * reference): the zero-valued `accountType`/`deviceType` enum fields are omitted
+ * so the signed `details` match what the companion verifies.
+ */
+export async function buildSignedCompanionIdentity(input) {
+    const accountSignatureKey = toRawPubKey(input.accountIdentityKeyPair.pubKey);
+    const details = proto.ADVDeviceIdentity.encode({
+        rawId: input.rawId,
+        timestamp: input.timestampSeconds,
+        keyIndex: input.keyIndex
+    }).finish();
+    const accountSignature = await generateDeviceIdentityAccountSignature(details, input.companionIdentityPublicKey, input.accountIdentityKeyPair);
+    const signedIdentity = proto.ADVSignedDeviceIdentity.encode({
+        details,
+        accountSignatureKey,
+        accountSignature
+    }).finish();
+    const hmac = computeAdvIdentityHmac(input.advSecretKey, signedIdentity);
+    const deviceIdentityBytes = proto.ADVSignedDeviceIdentityHMAC.encode({
+        details: signedIdentity,
+        hmac
+    }).finish();
+    const keyIndexListBytes = await buildSignedKeyIndexList({
+        accountIdentityKeyPair: input.accountIdentityKeyPair,
+        rawId: input.rawId,
+        currentIndex: input.keyIndex,
+        timestampSeconds: input.timestampSeconds,
+        validIndexes: input.validIndexes
+    });
+    return { deviceIdentityBytes, keyIndexListBytes };
+}
+/**
+ * Derives the `<pem>` AES-GCM key the phone ships in the pair-device upload:
+ * `HKDF-SHA256(ikm = advSecret, salt = companionNoisePublicKey, info)`. Not yet
+ * verified against a live server from this implementation; see
+ * `CompanionHostOptions.includePem`.
+ */
+export function derivePemKey(advSecretKey, companionNoisePublicKey) {
+    return hkdf(advSecretKey, companionNoisePublicKey, PEM_HKDF_INFO, 32);
+}
+/**
+ * Link-code handshake, primary step 1: unwrap the companion ephemeral with the
+ * pairing code, generate the primary ephemeral, compute the shared ECDH secret,
+ * and wrap the primary ephemeral for the `primary_hello` stanza. Mirror of the
+ * companion's `createCompanionHello` + primary-ephemeral unwrap.
+ */
+export async function preparePrimaryHello(args) {
+    if (args.wrappedCompanionEphemeralPub.length < 48) {
+        throw new Error(`wrapped companion ephemeral pub too short: ${args.wrappedCompanionEphemeralPub.length} bytes (need >= 48)`);
+    }
+    const codeBytes = TEXT_ENCODER.encode(args.pairingCode);
+    const companionCipherKey = await pbkdf2Sha256(codeBytes, args.wrappedCompanionEphemeralPub.subarray(0, 32), PBKDF2_ITERATIONS, PAIRING_AES_KEY_BYTES);
+    const companionEphemeralPub = aesCtrDecrypt(companionCipherKey, args.wrappedCompanionEphemeralPub.subarray(32, 48), args.wrappedCompanionEphemeralPub.subarray(48));
+    const [primaryEphemeralKeyPair, salt, counter] = await Promise.all([
+        X25519.generateKeyPair(),
+        randomBytesAsync(32),
+        randomBytesAsync(16)
+    ]);
+    const primaryCipherKey = await pbkdf2Sha256(codeBytes, salt, PBKDF2_ITERATIONS, PAIRING_AES_KEY_BYTES);
+    const encrypted = aesCtrEncrypt(primaryCipherKey, counter, primaryEphemeralKeyPair.pubKey);
+    const sharedEphemeral = await X25519.scalarMult(primaryEphemeralKeyPair.privKey, companionEphemeralPub);
+    return {
+        primaryEphemeralKeyPair,
+        wrappedPrimaryEphemeralPub: concatBytes([salt, counter, encrypted]),
+        sharedEphemeral
+    };
+}
+/**
+ * Link-code handshake, primary step 2: decrypt the `companion_finish` key bundle
+ * and derive the shared `advSecret` (byte-identical to what the companion
+ * derives). Validates that the bundle binds both identities.
+ *
+ * @throws when the bundle's embedded identities do not match.
+ */
+export async function completePrimaryHandshake(args) {
+    const bundleEncryptionKey = hkdf(args.sharedEphemeral, args.wrappedKeyBundle.subarray(0, 32), WA_PAIRING_KDF_INFO.LINK_CODE_BUNDLE, 32);
+    const plaintextBundle = aesGcmDecrypt(bundleEncryptionKey, args.wrappedKeyBundle.subarray(32, 44), args.wrappedKeyBundle.subarray(44));
+    const bundleCompanionIdentity = plaintextBundle.subarray(0, 32);
+    const bundlePrimaryIdentity = plaintextBundle.subarray(32, 64);
+    const bundleSecret = plaintextBundle.subarray(64);
+    const rawCompanionIdentity = toRawPubKey(args.companionIdentityPub);
+    if (!uint8Equal(bundlePrimaryIdentity, toRawPubKey(args.primaryIdentityKeyPair.pubKey))) {
+        throw new Error('link-code bundle primary identity mismatch');
+    }
+    if (!uint8Equal(bundleCompanionIdentity, rawCompanionIdentity)) {
+        throw new Error('link-code bundle companion identity mismatch');
+    }
+    const sharedIdentity = await X25519.scalarMult(args.primaryIdentityKeyPair.privKey, rawCompanionIdentity);
+    return hkdf(concatBytes([args.sharedEphemeral, sharedIdentity, bundleSecret]), null, WA_PAIRING_KDF_INFO.ADV_SECRET, 32);
+}

package/dist/esm/auth/pairing/pairing-code-crypto.js

@@ -5,7 +5,7 @@ import { concatBytes, TEXT_ENCODER } from '../../util/bytes.js';
 const CROCKFORD_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTVWXYZ';
 export const PBKDF2_ITERATIONS = 2 << 16;
 const PAIRING_AES_KEY_BYTES = 32;
-function bytesToCrockford(bytes) {
+export function encodeBytesToCrockford(bytes) {
     let bitCount = 0;
     let value = 0;
     let out = '';
@@ -42,7 +42,7 @@ export async function createCompanionHello(options = {}) {
         randomBytesAsync(16),
         normalizedCustomCode !== null ? Promise.resolve(null) : randomBytesAsync(5)
     ]);
-    const pairingCode = normalizedCustomCode ?? bytesToCrockford(codeBytes);
+    const pairingCode = normalizedCustomCode ?? encodeBytesToCrockford(codeBytes);
     const cipherKey = await pbkdf2Sha256(TEXT_ENCODER.encode(pairingCode), salt, PBKDF2_ITERATIONS, PAIRING_AES_KEY_BYTES);
     const encrypted = aesCtrEncrypt(cipherKey, counter, companionEphemeralKeyPair.pubKey);
     return {

package/dist/esm/auth/pairing/shortcake-crypto.js

@@ -0,0 +1,99 @@
+import { encodeBytesToCrockford } from '../pairing/pairing-code-crypto.js';
+import { aesGcmEncrypt, hkdf, randomBytesAsync, sha256 } from '../../crypto/index.js';
+import { X25519 } from '../../crypto/curves/X25519.js';
+import { proto } from '../../proto.js';
+import { concatBytes, TEXT_ENCODER } from '../../util/bytes.js';
+/**
+ * Cryptographic core of the WhatsApp "Shortcake" companion-linking protocol
+ * (the device-link flow the official clients call CRSC / Shortcake).
+ *
+ * This module implements ONLY the wire/crypto half: ephemeral X25519 key
+ * exchange, the commit-reveal nonce, the verification code, and the AES-GCM
+ * pairing envelope. The WebAuthn/passkey assertion that gates the prologue is
+ * NOT produced here – it is an opaque input supplied by the caller (so the
+ * credential source stays out of the protocol layer).
+ *
+ * Mirrors `WAWebShortcakeLinkingAlgorithm` from the web client.
+ */
+const NONCE_BYTES = 32;
+const VERIFICATION_CODE_BYTES = 5;
+const GCM_IV_BYTES = 12;
+const ENCRYPTION_KEY_BYTES = 32;
+const EPHEMERAL_PUBLIC_KEY_BYTES = 32;
+/** HKDF `info` for the pairing-request encryption key. */
+const ENCRYPTION_KEY_INFO = TEXT_ENCODER.encode('Pairing Information Encryption Key');
+/**
+ * Generates the companion's ephemeral identity + commitment for a Shortcake
+ * prologue. The companion publishes a commitment to its nonce now and reveals
+ * the nonce later (after the primary's identity arrives) so the primary cannot
+ * grind the verification code.
+ */
+export async function generateCompanionEphemeralIdentity(args) {
+    const [keyPair, companionNonce] = await Promise.all([
+        X25519.generateKeyPair(),
+        randomBytesAsync(NONCE_BYTES)
+    ]);
+    const companionEphemeralIdentityBytes = proto.CompanionEphemeralIdentity.encode({
+        publicKey: keyPair.pubKey,
+        deviceType: args.deviceType,
+        ref: args.ref
+    }).finish();
+    const commitmentHash = sha256(concatBytes([companionEphemeralIdentityBytes, companionNonce]));
+    const prologuePayloadBytes = proto.ProloguePayload.encode({
+        companionEphemeralIdentity: companionEphemeralIdentityBytes,
+        commitment: { hash: commitmentHash }
+    }).finish();
+    return {
+        keyPair,
+        companionNonce,
+        companionEphemeralIdentityBytes,
+        commitmentHash,
+        prologuePayloadBytes
+    };
+}
+/** Parses + validates a `PrimaryEphemeralIdentity` proto from the primary. */
+export function decodePrimaryEphemeralIdentity(bytes) {
+    const decoded = proto.PrimaryEphemeralIdentity.decode(bytes);
+    const publicKey = decoded.publicKey;
+    const nonce = decoded.nonce;
+    if (!publicKey || publicKey.length !== EPHEMERAL_PUBLIC_KEY_BYTES) {
+        throw new Error('shortcake: PrimaryEphemeralIdentity.publicKey must be 32 bytes');
+    }
+    if (!nonce || nonce.length !== NONCE_BYTES) {
+        throw new Error('shortcake: PrimaryEphemeralIdentity.nonce must be 32 bytes');
+    }
+    return { publicKey, nonce };
+}
+/**
+ * Derives the short verification code shown on both devices:
+ * `Crockford32( primaryNonce[0..5] XOR SHA-256(companionNonce ‖ primaryPubKey)[0..5] )`.
+ */
+export function deriveVerificationCode(companionNonce, primary) {
+    const digest = sha256(concatBytes([companionNonce, primary.publicKey]));
+    const code = new Uint8Array(VERIFICATION_CODE_BYTES);
+    for (let i = 0; i < VERIFICATION_CODE_BYTES; i += 1) {
+        code[i] = primary.nonce[i] ^ digest[i];
+    }
+    return encodeBytesToCrockford(code);
+}
+/**
+ * Derives the AES-GCM key that protects the pairing request:
+ * `HKDF( X25519(companionPriv, primaryPub), salt="Companion Pairing <deviceType> with ref <ref>", info="Pairing Information Encryption Key" )`.
+ */
+export async function deriveEncryptionKey(args) {
+    const shared = await X25519.scalarMult(args.companionPrivKey, args.primaryPublicKey);
+    const salt = TEXT_ENCODER.encode(`Companion Pairing ${String(args.deviceType)} with ref ${args.ref}`);
+    return hkdf(shared, salt, ENCRYPTION_KEY_INFO, ENCRYPTION_KEY_BYTES);
+}
+/**
+ * Encrypts the pairing request plaintext under the derived key and returns the
+ * encoded `EncryptedPairingRequest` proto (random 12-byte IV).
+ */
+export async function encryptPairingRequest(encryptionKey, plaintext) {
+    if (encryptionKey.length !== ENCRYPTION_KEY_BYTES) {
+        throw new Error('shortcake: encryption key must be 32 bytes');
+    }
+    const iv = await randomBytesAsync(GCM_IV_BYTES);
+    const encryptedPayload = aesGcmEncrypt(encryptionKey, iv, plaintext);
+    return proto.EncryptedPairingRequest.encode({ encryptedPayload, iv }).finish();
+}

package/dist/esm/client/WaClient.js

@@ -12,7 +12,7 @@ import { normalizeDeviceJid } from '../protocol/jid.js';
 import { WA_DISCONNECT_REASONS, WA_LOGOUT_REASONS } from '../protocol/stream.js';
 import { buildRemoveCompanionDeviceIq } from '../transport/node/builders/device.js';
 import { assertIqResult, queryWithContext as queryNodeWithContext } from '../transport/node/query.js';
-import { fetchLatestWaWebVersion } from '../transport/wa-web-version-fetcher.js';
+import { fetchLatestWaMobileVersion, fetchLatestWaWebVersion } from '../transport/wa-version-fetcher.js';
 import { toError } from '../util/primitives.js';
 const SYNC_RELATED_PROTOCOL_TYPES = new Set([
     proto.Message.ProtocolMessage.Type.APP_STATE_SYNC_KEY_REQUEST,
@@ -70,13 +70,14 @@ class WaClientImpl extends EventEmitter {
         this.deps = dependencies;
         this.appStateSync = dependencies.appStateSync;
         this.mediaTransfer = dependencies.mediaTransfer;
-        this.disposePlugins = installWaClientPlugins(this, {
+        this.pluginInstallInput = {
             options: this.options,
             logger: this.logger,
             stores: this.stores,
             deps: this.deps,
             queryWithContext: this.queryWithContext.bind(this)
-        }, this.options.plugins ?? []);
+        };
+        this.installPlugins();
         this.bindNodeTransportEvents();
         this.on('connection', (event) => {
             if (event.status !== 'close')
@@ -85,22 +86,43 @@ class WaClientImpl extends EventEmitter {
                 return;
             if (event.reason !== WA_DISCONNECT_REASONS.FAILURE_CLIENT_TOO_OLD)
                 return;
-            this.logger.warn('wa rejected the connect with client_too_old: the zapo default WA Web version is outdated. ' +
-                'Auto-recovering by fetching the current version from web.whatsapp.com – ' +
+            this.logger.warn('wa rejected the connect with client_too_old: the zapo default WA version is outdated. ' +
+                'Auto-recovering by fetching the current version from the public source – ' +
                 'please upgrade zapo so the shipped default catches up.');
             void this.runClientTooOldRecover();
         });
+        this.on('connection', (event) => {
+            if (event.status !== 'open')
+                return;
+            void this.deps.mobileCoordinator.reconcileCompanions().catch((error) => {
+                this.logger.debug('companion reconcile on connect failed', {
+                    message: toError(error).message
+                });
+            });
+        });
+    }
+    installPlugins() {
+        this.disposePlugins = installWaClientPlugins(this, this.pluginInstallInput, this.options.plugins ?? []);
     }
     async runClientTooOldRecover() {
         try {
             if (this.connectPromise) {
                 await this.connectPromise.catch(() => undefined);
             }
-            const latest = await fetchLatestWaWebVersion();
+            const mobile = this.deps.isMobilePrimary();
+            const latest = mobile
+                ? await fetchLatestWaMobileVersion()
+                : await fetchLatestWaWebVersion();
             this.logger.info('client_too_old auto-recover: reconnecting', {
+                transport: mobile ? 'mobile' : 'web',
                 version: latest.version
             });
-            this.deps.authClient.setNextConnectVersion(latest.version);
+            if (mobile) {
+                this.deps.authClient.setNextConnectMobileAppVersion(latest.version);
+            }
+            else {
+                this.deps.authClient.setNextConnectVersion(latest.version);
+            }
             await this.connect();
         }
         catch (error) {
@@ -306,6 +328,9 @@ class WaClientImpl extends EventEmitter {
             this.logger.trace('wa client connect already in-flight');
             return this.connectPromise;
         }
+        if (!this.disposePlugins) {
+            this.installPlugins();
+        }
         this.writeBehind.restart();
         this.acceptingIncomingEvents = true;
         this.connectPromise = this.deps.connectionManager
@@ -329,11 +354,12 @@ class WaClientImpl extends EventEmitter {
     }
     /**
      * Closes the transport gracefully: pauses incoming events, flushes the
-     * write-behind persistence queue, and emits a `connection` close event
-     * with reason `client_disconnected`. Does not clear stored credentials -
-     * call {@link connect} again to resume the same session. There is no
-     * built-in auto-reconnect; subscribe to `connection: { status: 'close' }`
-     * and decide your own backoff.
+     * write-behind persistence queue, disposes installed plugins, and emits a
+     * `connection` close event with reason `client_disconnected`. Does not
+     * clear stored credentials - call {@link connect} again to resume the same
+     * session, which reinstalls the plugins. There is no built-in
+     * auto-reconnect; subscribe to `connection: { status: 'close' }` and decide
+     * your own backoff.
      */
     async disconnect() {
         await this.pauseIncomingEventsAndWaitDrain();
@@ -450,6 +476,14 @@ class WaClientImpl extends EventEmitter {
     get email() {
         return this.deps.emailCoordinator;
     }
+    /**
+     * Mobile coordinator: host and manage companion devices linked to this
+     * mobile-primary account (link via QR or pairing code, list, revoke).
+     * Requires a registered primary session. See {@link WaMobileCoordinator}.
+     */
+    get mobile() {
+        return this.deps.mobileCoordinator;
+    }
     /**
      * Unpairs this companion device by removing it server-side. Requires an
      * authenticated session; throws when no `meJid` is present.