@zapo-js/fake-server 1.0.0 → 1.2.0

package/dist/api/ServerRegistries.d.ts

@@ -99,6 +99,13 @@ export declare class ServerRegistries {
     mutateBlocklist(action: 'block' | 'unblock', jid: string): void;
     notifyGroupOp(op: CapturedGroupOp): void;
     registerPeer(peer: FakePeer): void;
+    /**
+     * Makes a device visible to `usync` without minting a full fake peer – used
+     * for the primary's own device set, whose companions are real clients with
+     * their own keys rather than server-side fakes.
+     */
+    registerDeviceId(userJid: string, deviceId: number): void;
+    unregisterDeviceId(userJid: string, deviceId: number): void;
     lookupDeviceIdsForUser(userJid: string): readonly number[];
     notifyProfilePictureSet(op: CapturedProfilePictureSet): void;
     notifyStatusSet(text: string): void;

package/dist/api/ServerRegistries.js

@@ -191,16 +191,31 @@ class ServerRegistries {
     }
     registerPeer(peer) {
         this.peerRegistry.set(peer.jid, peer);
-        const userJid = toUserJidPart(peer.jid);
-        const deviceId = toDeviceIdPart(peer.jid);
+        this.registerDeviceId(toUserJidPart(peer.jid), toDeviceIdPart(peer.jid));
+    }
+    /**
+     * Makes a device visible to `usync` without minting a full fake peer – used
+     * for the primary's own device set, whose companions are real clients with
+     * their own keys rather than server-side fakes.
+     */
+    registerDeviceId(userJid, deviceId) {
         const ids = this.deviceIdsByUser.get(userJid);
-        if (ids) {
+        if (!ids) {
+            this.deviceIdsByUser.set(userJid, [deviceId]);
+            return;
+        }
+        if (!ids.includes(deviceId)) {
             ids.push(deviceId);
             ids.sort((a, b) => a - b);
         }
-        else {
-            this.deviceIdsByUser.set(userJid, [deviceId]);
+    }
+    unregisterDeviceId(userJid, deviceId) {
+        const ids = this.deviceIdsByUser.get(userJid);
+        if (!ids) {
+            return;
         }
+        const next = ids.filter((id) => id !== deviceId);
+        this.deviceIdsByUser.set(userJid, next);
     }
     lookupDeviceIdsForUser(userJid) {
         return this.deviceIdsByUser.get(userJid) ?? [];

package/dist/api/iq-handlers.d.ts

@@ -2,11 +2,13 @@
 import { type BuildAbPropsResultInput } from '../protocol/iq/abprops';
 import { type FakeAppStateCollectionPayload } from '../protocol/iq/appstate-sync';
 import { type FakeBusinessProfile } from '../protocol/iq/business';
+import { type ParsedPairDeviceUpload } from '../protocol/iq/companion-host';
 import { type FakePrivacyCategoryName, type FakePrivacySettingsState } from '../protocol/iq/privacy';
 import { type FakePrivacyTokenIssue } from '../protocol/iq/privacy-token';
 import { type FakeProfilePictureResult } from '../protocol/iq/profile';
-import { type WaFakeIqRouter } from '../protocol/iq/router';
+import { type WaFakeIqContext, type WaFakeIqRouter } from '../protocol/iq/router';
 import { type ClientPreKeyBundle } from '../protocol/signal/prekey-upload';
+import type { FakeMobilePrimaryIdentity } from '../state/fake-companion-host';
 import { type BinaryNode } from '../transport/codec';
 import type { FakePeer } from './FakePeer';
 import { type CapturedBlocklistChange, type CapturedDirtyBitsClear, type CapturedGroupOp, type CapturedPrivacySet, type CapturedProfilePictureSet, type MutableFakeGroup } from './ServerRegistries';
@@ -34,12 +36,29 @@ export interface IqHandlerDeps {
     notifyPrivacySet(change: CapturedPrivacySet): void;
     notifyBlocklistChange(change: CapturedBlocklistChange): void;
     capturePreKeyBundle(bundle: ClientPreKeyBundle): void;
+    countServerPreKeys(): number;
     consumeOutboundAppStatePatches(iq: BinaryNode): Promise<void>;
     readonly appStateCollectionProviders: ReadonlyMap<string, () => Promise<FakeAppStateCollectionPayload | null> | FakeAppStateCollectionPayload | null>;
     requireMediaHttpsInfo(): {
         readonly host: string;
         readonly port: number;
     };
+    /** Mobile primary bound to this session, or `null` for a web session. */
+    readonly mobilePrimary: FakeMobilePrimaryIdentity | null;
+    /**
+     * Completes the primary's `pair-device` upload. Resolves `null` when the
+     * session has no primary or the ref belongs to no live connection.
+     */
+    linkCompanionDevice(upload: ParsedPairDeviceUpload): Promise<LinkedCompanionResult | null>;
+    /** Unlinks the given companions, or every one of them when passed `null`. */
+    revokeCompanionDevices(deviceJids: readonly string[] | null): readonly string[];
+    recordKeyIndexList(bytes: Uint8Array, timestampSeconds: number): void;
+    /** Routes a link-code stage to the other client, or `null` to fall through. */
+    relayLinkCodeStage(iq: BinaryNode, context: WaFakeIqContext | undefined): Promise<BinaryNode | null>;
+}
+export interface LinkedCompanionResult {
+    readonly deviceJid: string;
+    readonly companionPropsBytes: Uint8Array | null;
 }
 export declare function parseUsyncRequestedUserJids(iq: BinaryNode): readonly string[];
 export declare function parseRequestedKeyJids(iq: BinaryNode): readonly string[];

package/dist/api/iq-handlers.js

@@ -7,6 +7,7 @@ exports.registerDefaultIqHandlers = registerDefaultIqHandlers;
 const abprops_1 = require("../protocol/iq/abprops");
 const appstate_sync_1 = require("../protocol/iq/appstate-sync");
 const business_1 = require("../protocol/iq/business");
+const companion_host_1 = require("../protocol/iq/companion-host");
 const dirty_bits_1 = require("../protocol/iq/dirty-bits");
 const group_ops_1 = require("../protocol/iq/group-ops");
 const newsletter_1 = require("../protocol/iq/newsletter");
@@ -78,6 +79,28 @@ function buildGroupMetadataReply(iq, metadata) {
         ]
     };
 }
+/**
+ * True when the stanza arrived on the phone that owns this session's account.
+ * Being a phone login is not enough: a second number connecting to the same
+ * session must not drive the companion set of the account that owns it.
+ */
+function isSessionOwnerConnection(context, deps) {
+    const payload = context?.connection.clientPayload;
+    if (payload?.kind !== 'login' || payload.flavor !== 'mobile') {
+        return false;
+    }
+    return deps.mobilePrimary?.username === payload.username;
+}
+/** The device jid a connection speaks for, or `null` before it logs in. */
+function ownDeviceJid(context) {
+    const payload = context?.connection.clientPayload;
+    if (payload?.kind !== 'login') {
+        return null;
+    }
+    return payload.device > 0
+        ? `${payload.username}:${payload.device}@s.whatsapp.net`
+        : `${payload.username}@s.whatsapp.net`;
+}
 function registerDefaultIqHandlers(router, deps) {
     router.register({
         label: 'prekey-upload',
@@ -98,6 +121,29 @@ function registerDefaultIqHandlers(router, deps) {
         matcher: { xmlns: 'encrypt', type: 'get', childTag: 'digest' },
         respond: (iq) => (0, router_1.buildIqError)(iq, { code: 404, text: 'item-not-found' })
     });
+    // Baileys-family and whatsmeow clients block on this query before
+    // reporting the connection as open; zapo-js uses <digest> instead.
+    router.register({
+        label: 'prekey-count',
+        matcher: { xmlns: 'encrypt', type: 'get', childTag: 'count' },
+        respond: (iq) => {
+            const result = (0, router_1.buildIqResult)(iq);
+            return {
+                ...result,
+                content: [
+                    {
+                        tag: 'count',
+                        attrs: { value: String(deps.countServerPreKeys()) }
+                    }
+                ]
+            };
+        }
+    });
+    router.register({
+        label: 'passive-mode',
+        matcher: { xmlns: 'passive', type: 'set' },
+        respond: (iq) => (0, router_1.buildIqResult)(iq)
+    });
     router.register({
         label: 'media-conn',
         matcher: { xmlns: 'w:m', type: 'set', childTag: 'media_conn' },
@@ -226,10 +272,82 @@ function registerDefaultIqHandlers(router, deps) {
         matcher: { xmlns: 'encrypt', type: 'set', childTag: 'rotate' },
         respond: (iq) => (0, router_1.buildIqResult)(iq)
     });
+    router.register({
+        label: 'link-code-companion-reg',
+        matcher: { xmlns: 'md', type: 'set', childTag: 'link_code_companion_reg' },
+        respond: (iq, context) => deps.relayLinkCodeStage(iq, context)
+    });
+    router.register({
+        label: 'companion-pair-device',
+        matcher: { xmlns: 'md', type: 'set', childTag: 'pair-device' },
+        respond: async (iq, context) => {
+            const upload = (0, companion_host_1.parsePairDeviceUpload)(iq);
+            if (!upload) {
+                return (0, router_1.buildIqError)(iq, { code: 400, text: 'invalid-pair-device' });
+            }
+            // The link is minted under the account that owns the session, so
+            // only that account's phone may ask for one.
+            if (!isSessionOwnerConnection(context, deps)) {
+                return (0, router_1.buildIqError)(iq, { code: 403, text: 'not-authorized' });
+            }
+            const linked = await deps.linkCompanionDevice(upload);
+            if (!linked) {
+                return (0, router_1.buildIqError)(iq, { code: 404, text: 'unknown-pairing-ref' });
+            }
+            // Shape mirrors the phone's parser: <device jid> is a direct child
+            // of the result, with the companion's own props beside it.
+            const content = [{ tag: 'device', attrs: { jid: linked.deviceJid } }];
+            if (linked.companionPropsBytes) {
+                content.push({
+                    tag: 'companion-props',
+                    attrs: {},
+                    content: linked.companionPropsBytes
+                });
+            }
+            return (0, router_1.buildIqResult)(iq, { content });
+        }
+    });
+    router.register({
+        label: 'companion-key-index-list',
+        matcher: { xmlns: 'md', type: 'set', childTag: 'key-index-list' },
+        respond: (iq, context) => {
+            const published = (0, companion_host_1.parseKeyIndexListPublish)(iq);
+            if (!published) {
+                return (0, router_1.buildIqError)(iq, { code: 400, text: 'invalid-key-index-list' });
+            }
+            if (!isSessionOwnerConnection(context, deps)) {
+                return (0, router_1.buildIqError)(iq, { code: 403, text: 'not-authorized' });
+            }
+            deps.recordKeyIndexList(published.keyIndexListBytes, published.timestampSeconds);
+            return (0, router_1.buildIqResult)(iq);
+        }
+    });
     router.register({
         label: 'remove-companion-device',
         matcher: { xmlns: 'md', type: 'set', childTag: 'remove-companion-device' },
-        respond: (iq) => {
+        respond: (iq, context) => {
+            const removal = (0, companion_host_1.parseRemoveCompanionDevice)(iq);
+            // The same stanza means "log me out" from a companion and "unlink
+            // that device" from a primary. The wire does not say which, but the
+            // connection does: the account's own phone is always revoking
+            // someone else's device, and never ends its own session this way.
+            if (removal && isSessionOwnerConnection(context, deps)) {
+                if (!removal.all) {
+                    deps.revokeCompanionDevices(removal.deviceJid ? [removal.deviceJid] : []);
+                }
+                else if (!removal.excludeHostedCompanion) {
+                    // The hosted set is exactly what this session tracks, so
+                    // sparing it leaves the registry untouched.
+                    deps.revokeCompanionDevices(null);
+                }
+                return (0, router_1.buildIqResult)(iq);
+            }
+            // Anyone else may only unlink itself: a connection that is not the
+            // account's phone must never drop someone else's device. Its own
+            // session ends either way.
+            if (removal?.deviceJid && removal.deviceJid === ownDeviceJid(context)) {
+                deps.revokeCompanionDevices([removal.deviceJid]);
+            }
             deps.notifyLogout();
             return (0, router_1.buildIqResult)(iq);
         }

package/dist/bin.js

@@ -2,13 +2,17 @@
 "use strict";
 /** Standalone CLI for `@zapo-js/fake-server`. */
 Object.defineProperty(exports, "__esModule", { value: true });
+const node_readline_1 = require("node:readline");
 const FakeWaServer_1 = require("./api/FakeWaServer");
+const pair_device_1 = require("./protocol/auth/pair-device");
+const util_1 = require("./transport/util");
 function parseArgs(argv) {
     let host = '127.0.0.1';
     let port = 0;
     let path = '/ws/chat';
     const peerJids = [];
     const groupSpecs = [];
+    let pairJid = null;
     let log = false;
     let quiet = false;
     let json = false;
@@ -46,6 +50,9 @@ function parseArgs(argv) {
             case '--group':
                 groupSpecs.push(next());
                 break;
+            case '--pair':
+                pairJid = next();
+                break;
             case '--log':
                 log = true;
                 break;
@@ -59,7 +66,7 @@ function parseArgs(argv) {
                 throw new Error(`unknown flag: ${arg}`);
         }
     }
-    return { host, port, path, peerJids, groupSpecs, log, quiet, json, help };
+    return { host, port, path, peerJids, groupSpecs, pairJid, log, quiet, json, help };
 }
 function printHelp() {
     process.stdout.write(`@zapo-js/fake-server – standalone fake WhatsApp Web server
@@ -75,6 +82,12 @@ FLAGS
   --group <spec>      Pre-create a fake group; spec format
                       <group-jid>=<peer-jid>,<peer-jid>,...
                       All peers must already be passed via --peer.
+  --pair <jid>        Drive QR pairing for unregistered clients: the server
+                      sends pair-device refs, then prompts on stdin for the
+                      QR payload the client displays
+                      (ref,noisePubB64,identityPubB64,advSecretB64,platform)
+                      and answers pair-success assigning <jid> as the device
+                      jid. Without this flag the CLI is login-only.
   --log               Print every captured inbound stanza
   --quiet             Suppress the startup info banner
   --json              Print connection info as JSON
@@ -105,7 +118,7 @@ async function main() {
         args = parseArgs(process.argv.slice(2));
     }
     catch (error) {
-        process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.stderr.write(`error: ${(0, util_1.toError)(error).message}\n`);
         process.stderr.write('run with --help to see usage.\n');
         process.exit(2);
     }
@@ -127,11 +140,39 @@ async function main() {
         port: args.port,
         path: args.path
     });
+    if (args.pairJid !== null) {
+        const pairJid = args.pairJid;
+        let pairingStarted = false;
+        server.onAuthenticatedPipeline(async (pipeline) => {
+            if (pairingStarted)
+                return;
+            if (pipeline.clientPayload?.kind !== 'registration')
+                return;
+            pairingStarted = true;
+            try {
+                await server.runPairing(pipeline, { deviceJid: pairJid }, async () => {
+                    const qr = await readStdinLine('[fake-server] paste the QR payload displayed by the client and press Enter:\n');
+                    const parsed = (0, pair_device_1.parsePairingQrString)(qr.trim());
+                    return {
+                        advSecretKey: parsed.advSecretKey,
+                        identityPublicKey: parsed.identityPublicKey
+                    };
+                });
+                process.stdout.write(`[fake-server] pair-success sent for ${pairJid}; the client will now reconnect and log in\n`);
+            }
+            catch (error) {
+                pairingStarted = false;
+                process.stderr.write(`pairing failed: ${(0, util_1.toError)(error).message}\n`);
+            }
+        });
+    }
     let setupComplete = false;
     const setupPromise = new Promise((resolve, reject) => {
         server.onAuthenticatedPipeline(async (pipeline) => {
             if (setupComplete)
                 return;
+            if (pipeline.clientPayload?.kind !== 'login')
+                return;
             setupComplete = true;
             try {
                 const peers = new Map();
@@ -157,7 +198,7 @@ async function main() {
                 resolve();
             }
             catch (error) {
-                reject(error instanceof Error ? error : new Error(String(error)));
+                reject((0, util_1.toError)(error));
             }
         });
     });
@@ -166,12 +207,11 @@ async function main() {
         process.exitCode = 1;
     });
     if (args.log) {
-        server.onPipeline((pipeline) => {
-            pipeline.setEvents({
-                onStanza: (node) => {
-                    process.stdout.write(`[wire] ${node.tag}${node.attrs.id ? ` id=${node.attrs.id}` : ''}${node.attrs.type ? ` type=${node.attrs.type}` : ''}\n`);
-                }
-            });
+        // onCapturedStanza taps the server's own capture stream; overriding
+        // pipeline.setEvents here would replace the server's handlers and
+        // silently break --peer setup and stanza capture.
+        server.onCapturedStanza((node) => {
+            process.stdout.write(`[wire] ${node.tag}${node.attrs.id ? ` id=${node.attrs.id}` : ''}${node.attrs.type ? ` type=${node.attrs.type}` : ''}\n`);
         });
     }
     if (!args.quiet) {
@@ -184,10 +224,11 @@ async function main() {
                 path: args.path,
                 noiseRootCa: {
                     serial: noiseRoot.serial,
-                    publicKeyHex: bytesToHex(noiseRoot.publicKey)
+                    publicKeyHex: (0, util_1.bytesToHex)(noiseRoot.publicKey)
                 },
                 peers: args.peerJids,
-                groups: parsedGroups
+                groups: parsedGroups,
+                pair: args.pairJid
             }, null, 2) + '\n');
         }
         else {
@@ -200,9 +241,10 @@ async function main() {
                 `│ host           ${server.host}`,
                 `│ port           ${server.port}`,
                 `│ path           ${args.path}`,
-                `│ noise root ca  serial=${noiseRoot.serial} pub=${bytesToHex(noiseRoot.publicKey).slice(0, 32)}…`,
+                `│ noise root ca  serial=${noiseRoot.serial} pub=${(0, util_1.bytesToHex)(noiseRoot.publicKey).slice(0, 32)}…`,
                 `│ peers          ${args.peerJids.length === 0 ? '(none)' : args.peerJids.join(', ')}`,
                 `│ groups         ${parsedGroups.length === 0 ? '(none)' : parsedGroups.map((g) => g.groupJid).join(', ')}`,
+                `│ pair mode      ${args.pairJid ?? '(off – login only)'}`,
                 '├─────────────────────────────────────────────────────────────',
                 '│ Wire your WaClient with:',
                 '│   chatSocketUrls: [server.url]',
@@ -226,7 +268,7 @@ async function main() {
             process.exit(0);
         }
         catch (error) {
-            process.stderr.write(`error during shutdown: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.stderr.write(`error during shutdown: ${(0, util_1.toError)(error).message}\n`);
             process.exit(1);
         }
     };
@@ -234,15 +276,21 @@ async function main() {
     process.on('SIGTERM', () => void shutdown('SIGTERM'));
     await new Promise(() => undefined);
 }
-function bytesToHex(bytes) {
-    let out = '';
-    for (let index = 0; index < bytes.byteLength; index += 1) {
-        const value = bytes[index];
-        out += value < 16 ? `0${value.toString(16)}` : value.toString(16);
-    }
-    return out;
+function readStdinLine(prompt) {
+    process.stdout.write(prompt);
+    return new Promise((resolve, reject) => {
+        const rl = (0, node_readline_1.createInterface)({ input: process.stdin });
+        // resolve before close(): rl.close() emits 'close' synchronously,
+        // which would otherwise reject the still-pending promise first.
+        rl.once('line', (line) => {
+            resolve(line);
+            rl.close();
+        });
+        rl.once('close', () => reject(new Error('stdin closed before a QR payload was provided')));
+    });
 }
 main().catch((error) => {
-    process.stderr.write(`fatal: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+    const normalized = (0, util_1.toError)(error);
+    process.stderr.write(`fatal: ${normalized.stack ?? normalized.message}\n`);
     process.exit(1);
 });

package/dist/esm/api/FakeMobilePrimary.js

@@ -0,0 +1,102 @@
+/** Registered mobile-primary credentials for driving a phone-side client. */
+import { randomBytesAsync, randomIntAsync, toSerializedPubKey, X25519, xeddsaSign } from '../transport/crypto.js';
+const HOST_DOMAIN = 's.whatsapp.net';
+const LID_DOMAIN = 'lid';
+const ADV_SECRET_BYTES = 32;
+const SIGNED_PRE_KEY_ID = 1;
+/**
+ * Device the seeded primary advertises. A phone always sends these in its login
+ * `UserAgent`, so they double as the assertion target for a cross-check test.
+ */
+const DEFAULT_DEVICE_INFO = {
+    manufacturer: 'Google',
+    device: 'Pixel 7',
+    osVersion: '14',
+    osBuildNumber: 'UQ1A.240205.004',
+    appVersion: '2.26.27.70',
+    mcc: '724',
+    mnc: '10',
+    localeLanguageIso6391: 'pt',
+    localeCountryIso31661Alpha2: 'BR'
+};
+/**
+ * Seeds a store session with the credentials of an already-registered mobile
+ * primary, so a client can connect in mobile mode without a registration flow
+ * (which happens out of band, against WhatsApp's HTTP registration endpoints,
+ * and is therefore out of this server's reach).
+ *
+ * The returned `deviceInfo` goes straight into the client's `mobileTransport`;
+ * point its `tcpUrl` at {@link FakeWaServer.tcpUrl}:
+ *
+ * @example
+ * ```ts
+ * const server = await FakeWaServer.start({ tcp: true })
+ * const store = createStore({})
+ * const primary = await seedFakeMobilePrimary(store, 'mobile-session', {
+ *     phoneNumber: '5511999999999'
+ * })
+ * const client = new WaClient({
+ *     store,
+ *     sessionId: 'mobile-session',
+ *     mobileTransport: { deviceInfo: primary.deviceInfo, tcpUrl: server.tcpUrl },
+ *     testHooks: { noiseRootCa: server.noiseRootCa }
+ * })
+ * ```
+ *
+ * @throws when `phoneNumber` is not a positive digit-only string.
+ */
+export async function seedFakeMobilePrimary(store, sessionId, options) {
+    const primary = await createFakeMobilePrimary(options);
+    await store.session(sessionId).auth.save(primary.credentials);
+    return primary;
+}
+/**
+ * Builds registered mobile-primary credentials without persisting them. Use
+ * {@link seedFakeMobilePrimary} unless you own the persistence yourself.
+ *
+ * @throws when `phoneNumber` is not a positive digit-only string.
+ */
+export async function createFakeMobilePrimary(options) {
+    if (!/^[1-9]\d*$/.test(options.phoneNumber)) {
+        throw new Error(`phoneNumber must be digits only without a leading zero, got: ${options.phoneNumber}`);
+    }
+    // The login payload carries the number as a numeric username, so anything
+    // past the safe-integer range would seed credentials that only fail later,
+    // on connect.
+    if (!Number.isSafeInteger(Number(options.phoneNumber))) {
+        throw new Error(`phoneNumber is too long to be sent as a numeric username: ${options.phoneNumber}`);
+    }
+    const [noiseKeyPair, identityKeyPair, signedPreKeyPair, advSecretKey, registrationId] = await Promise.all([
+        X25519.generateKeyPair(),
+        X25519.generateKeyPair(),
+        X25519.generateKeyPair(),
+        randomBytesAsync(ADV_SECRET_BYTES),
+        randomIntAsync(1, 16381)
+    ]);
+    const signature = await xeddsaSign(identityKeyPair.privKey, toSerializedPubKey(signedPreKeyPair.pubKey));
+    const deviceInfo = {
+        ...DEFAULT_DEVICE_INFO,
+        ...options.deviceInfo
+    };
+    const meJid = `${options.phoneNumber}@${HOST_DOMAIN}`;
+    const meLid = options.lidUser ? `${options.lidUser}@${LID_DOMAIN}` : null;
+    const credentials = {
+        noiseKeyPair,
+        registrationInfo: { registrationId, identityKeyPair },
+        signedPreKey: {
+            keyId: SIGNED_PRE_KEY_ID,
+            keyPair: signedPreKeyPair,
+            signature,
+            uploaded: false
+        },
+        advSecretKey,
+        meJid,
+        deviceInfo,
+        // A phone has no companion device-identity and no key-index list of its
+        // own: both are minted at pairing time, by this primary, for others.
+        serverHasPreKeys: false,
+        ...(meLid ? { meLid } : {}),
+        ...(options.pushName ? { pushName: options.pushName } : {})
+    };
+    return { meJid, meLid, deviceInfo, credentials };
+}

package/dist/esm/api/FakePairingDriver.js

@@ -1,7 +1,6 @@
 /** Runs the server side of the QR pairing flow. */
 import { buildAdvSignedDeviceIdentity, generateFakePrimaryDevice } from '../protocol/auth/fake-primary-device.js';
-import { buildPairDeviceIq, buildPairSuccessIq } from '../protocol/auth/pair-device.js';
-import { randomBytesAsync } from '../transport/crypto.js';
+import { buildPairDeviceIq, buildPairSuccessIq, mintPairingRefs } from '../protocol/auth/pair-device.js';
 export class FakePairingDriver {
     constructor(options, deps) {
         this.primary = null;
@@ -10,8 +9,7 @@ export class FakePairingDriver {
     }
     async run() {
         this.primary = this.options.primary ?? (await generateFakePrimaryDevice());
-        const refs = await Promise.all(Array.from({ length: 6 }, () => randomBytesAsync(16)));
-        const pairDeviceIq = buildPairDeviceIq({ refs });
+        const pairDeviceIq = buildPairDeviceIq({ refs: await mintPairingRefs() });
         await this.deps.pipeline.sendStanza(pairDeviceIq);
         const waitForAck = this.deps.waitForPairDeviceAck?.(pairDeviceIq.attrs.id) ?? Promise.resolve();
         const [material] = await Promise.all([this.deps.companionMaterialResolver(), waitForAck]);

package/dist/esm/api/FakePeer.js

@@ -547,7 +547,13 @@ export class FakePeer {
     }
     nextId() {
         this.nextMessageCounter += 1;
-        return `${this.jid}-${Date.now()}-${this.nextMessageCounter}`;
+        // WA-style uppercase hex, no '@': strict binary decoders tokenize an
+        // id containing '@' as a JID and reject the stanza. The registration
+        // id keeps ids from colliding across peers created in the same ms.
+        const peerPart = this.keyBundle.registrationId.toString(16).padStart(4, '0');
+        const timePart = Date.now().toString(16);
+        const counterPart = this.nextMessageCounter.toString(16).padStart(4, '0');
+        return `3EB0${peerPart}${timePart}${counterPart}`.toUpperCase();
     }
 }
 function findEncForPeer(stanza, peerJid) {