@zapo-js/fake-server 1.1.0 → 1.2.0

package/dist/api/FakeWaServer.js

@@ -4,14 +4,35 @@ exports.FakeWaServer = exports.FakeServerSession = void 0;
 const node_https_1 = require("node:https");
 const WaFakeConnectionPipeline_1 = require("../infra/WaFakeConnectionPipeline");
 const WaFakeMediaHttpsServer_1 = require("../infra/WaFakeMediaHttpsServer");
+const WaFakeTcpServer_1 = require("../infra/WaFakeTcpServer");
 const WaFakeWsServer_1 = require("../infra/WaFakeWsServer");
 const cert_chain_1 = require("../protocol/auth/cert-chain");
+const pair_device_1 = require("../protocol/auth/pair-device");
+const link_code_1 = require("../protocol/iq/link-code");
+const router_1 = require("../protocol/iq/router");
+const mobile_notification_1 = require("../protocol/push/mobile-notification");
 const fake_media_store_1 = require("../state/fake-media-store");
 const crypto_1 = require("../transport/crypto");
 const FakePairingDriver_1 = require("./FakePairingDriver");
 const FakePeer_1 = require("./FakePeer");
 const FakeServerSession_1 = require("./FakeServerSession");
 const Scenario_1 = require("./Scenario");
+const HOST_DOMAIN = 's.whatsapp.net';
+const MOBILE_PRIMARY_PLATFORM = 'android';
+/**
+ * Builds the mobile TCP listener when the option asks for one. Defaults its
+ * host to the WebSocket host so both listeners answer on the same interface.
+ */
+function createTcpServer(options) {
+    if (!options.tcp) {
+        return null;
+    }
+    const config = options.tcp === true ? {} : options.tcp;
+    return new WaFakeTcpServer_1.WaFakeTcpServer({
+        host: config.host ?? options.host,
+        port: config.port
+    });
+}
 var FakeServerSession_2 = require("./FakeServerSession");
 Object.defineProperty(exports, "FakeServerSession", { enumerable: true, get: function () { return FakeServerSession_2.FakeServerSession; } });
 class FakeWaServer {
@@ -24,6 +45,10 @@ class FakeWaServer {
         this.rootCa = null;
         this.serverStaticKeyPair = null;
         this.listenInfo = null;
+        this.tcpListenInfo = null;
+        this.pendingCompanionOffers = new Map();
+        this.mobilePrimaryPipelines = new Map();
+        this.linkCodeSessions = new Map();
         this.pipelineListeners = new Set();
         this.rejectMode = null;
         this.mediaStore = new fake_media_store_1.FakeMediaStore();
@@ -34,12 +59,18 @@ class FakeWaServer {
         this.options = options;
         this.wsServer = new WaFakeWsServer_1.WaFakeWsServer(options);
         this.wsServer.onConnection((connection) => this.handleConnection(connection));
+        this.tcpServer = createTcpServer(options);
+        this.tcpServer?.onConnection((connection) => this.handleConnection(connection));
         this.defaultSession = this.createSession('__default__');
     }
     /** State of the single default session (the only session for one client). */
     get registries() {
         return this.defaultSession.registries;
     }
+    /** Companion-host account state of the default session (linked devices, key-index list). */
+    get companionHost() {
+        return this.defaultSession.companionHost;
+    }
     get preKeyDispenser() {
         return this.defaultSession.preKeyDispenser;
     }
@@ -64,7 +95,11 @@ class FakeWaServer {
         return this.pipelineSessions.get(pipeline) ?? this.defaultSession;
     }
     createSession(id) {
-        const session = new FakeServerSession_1.FakeServerSession(id, { requireMediaHttpsInfo: () => this.requireMediaHttpsInfo() }, { defaultIqHandlers: this.options.defaultIqHandlers !== false });
+        const session = new FakeServerSession_1.FakeServerSession(id, {
+            requireMediaHttpsInfo: () => this.requireMediaHttpsInfo(),
+            completeCompanionPairing: (input) => this.completeCompanionPairing(input),
+            relayLinkCodeStage: (iq, context) => this.handleLinkCodeStage(iq, context)
+        }, { defaultIqHandlers: this.options.defaultIqHandlers !== false });
         this.sessions.set(id, session);
         // Server-level custom handlers apply to every session, present and future.
         for (const handler of this.globalIqHandlers) {
@@ -181,6 +216,27 @@ class FakeWaServer {
     async pushServerSyncNotification(pipeline, input) {
         return this.sessionFor(pipeline).appStateSync.pushServerSyncNotification(pipeline, input);
     }
+    /**
+     * Pushes the account's device set to a mobile primary as `account_sync`.
+     * Defaults to what this session tracks - the primary itself plus every
+     * companion it linked - so passing a shorter list is how a test tells the
+     * primary that a device disappeared while it was offline.
+     */
+    async pushAccountSyncDevices(pipeline, options = {}) {
+        const session = this.sessionFor(pipeline);
+        const primary = session.companionHost.primary;
+        if (!primary && !options.devices) {
+            throw new Error('cannot push account_sync: this session has no mobile primary');
+        }
+        const devices = options.devices ?? [
+            { deviceJid: primary.jid, keyIndex: 0 },
+            ...session.companionHost.linkedCompanions().map((companion) => ({
+                deviceJid: companion.deviceJid,
+                keyIndex: companion.keyIndex
+            }))
+        ];
+        await pipeline.sendStanza((0, mobile_notification_1.buildAccountSyncDevicesNotification)({ devices }));
+    }
     onAuthenticatedPipeline(listener) {
         this.authenticatedListeners.add(listener);
         return () => this.authenticatedListeners.delete(listener);
@@ -344,6 +400,18 @@ class FakeWaServer {
     get port() {
         return this.requireListening().port;
     }
+    /**
+     * `tcp://host:port` of the mobile listener, for the client's
+     * `mobileTransport.tcpUrl`.
+     *
+     * @throws when the server was started without the `tcp` option.
+     */
+    get tcpUrl() {
+        if (!this.tcpListenInfo) {
+            throw new Error('fake server has no mobile listener; start it with { tcp: true } to serve the mobile transport');
+        }
+        return this.tcpListenInfo.url;
+    }
     get noiseRootCa() {
         const root = this.requireRootCa();
         return { publicKey: root.publicKey, serial: root.serial };
@@ -371,11 +439,35 @@ class FakeWaServer {
         this.wsServer.setHttpRequestHandler(mediaHandler);
         this.mediaHttpsServer.setRequestHandler(mediaHandler);
         this.listenInfo = await this.wsServer.listen();
-        await this.mediaHttpsServer.listen('127.0.0.1');
+        try {
+            if (this.tcpServer) {
+                this.tcpListenInfo = await this.tcpServer.listen();
+            }
+            await this.mediaHttpsServer.listen('127.0.0.1');
+        }
+        catch (error) {
+            // A half-open server is worse than none: the listeners that did
+            // come up would stay bound and `listenInfo` would make a retry a
+            // no-op. Roll everything back so the caller can start over.
+            await this.rollbackFailedListen();
+            throw error;
+        }
+    }
+    async rollbackFailedListen() {
+        const ignore = () => undefined;
+        await this.wsServer.close().catch(ignore);
+        await this.tcpServer?.close().catch(ignore);
+        await this.mediaHttpsServer.close().catch(ignore);
+        this.listenInfo = null;
+        this.tcpListenInfo = null;
+        this.rootCa = null;
+        this.serverStaticKeyPair = null;
     }
     async stop() {
         this.pipelines.clear();
         await this.wsServer.close();
+        await this.tcpServer?.close();
+        this.tcpListenInfo = null;
         await this.mediaHttpsServer.close();
         if (this.cachedMediaProxyAgent) {
             this.cachedMediaProxyAgent.destroy();
@@ -398,7 +490,7 @@ class FakeWaServer {
             connection,
             rootCa: this.rootCa,
             serverStaticKeyPair: this.serverStaticKeyPair,
-            routeIq: (node) => this.sessionFor(pipeline).routeIq(node),
+            routeIq: (node) => this.sessionFor(pipeline).routeIq(node, { connection: pipeline }),
             ...(this.options.successNodeAttributes !== undefined
                 ? { successNodeAttributes: this.options.successNodeAttributes }
                 : {})
@@ -408,6 +500,7 @@ class FakeWaServer {
         pipeline.setEvents({
             onAuthenticated: () => {
                 this.bindPipelineSession(pipeline);
+                this.bindMobilePrimary(pipeline);
                 for (const listener of this.authenticatedListeners) {
                     try {
                         void Promise.resolve(listener(pipeline)).catch(() => undefined);
@@ -418,7 +511,7 @@ class FakeWaServer {
                 }
             },
             onStanza: (node) => this.sessionFor(pipeline).handleCapturedStanza(node),
-            onClose: () => this.pipelines.delete(pipeline)
+            onClose: () => this.forgetPipeline(pipeline)
         });
         for (const listener of this.pipelineListeners) {
             try {
@@ -444,6 +537,139 @@ class FakeWaServer {
         const id = resolveKey({ clientPayload, pipeline });
         this.pipelineSessions.set(pipeline, this.session(id));
     }
+    /** Drops every reference to a closed connection so a relay never targets it. */
+    forgetPipeline(pipeline) {
+        this.pipelines.delete(pipeline);
+        for (const [ref, offered] of this.pendingCompanionOffers) {
+            if (offered === pipeline) {
+                this.pendingCompanionOffers.delete(ref);
+            }
+        }
+        for (const [jid, primary] of this.mobilePrimaryPipelines) {
+            if (primary === pipeline) {
+                this.mobilePrimaryPipelines.delete(jid);
+            }
+        }
+        for (const [ref, session] of this.linkCodeSessions) {
+            if (session.companion === pipeline || session.primary === pipeline) {
+                this.linkCodeSessions.delete(ref);
+            }
+        }
+    }
+    /**
+     * Records a phone login as the session's account owner. Everything on the
+     * companion-host path keys off it: device jids are minted under its number,
+     * and `remove-companion-device` is read as a revoke rather than a logout.
+     */
+    bindMobilePrimary(pipeline) {
+        const clientPayload = pipeline.clientPayload;
+        if (clientPayload?.kind !== 'login' || clientPayload.flavor !== 'mobile') {
+            return;
+        }
+        const session = this.sessionFor(pipeline);
+        const jid = `${clientPayload.username}@${HOST_DOMAIN}`;
+        session.companionHost.bindPrimary({ username: clientPayload.username, jid });
+        if (session.companionHost.primary?.jid !== jid) {
+            // The session already belongs to another number. Wiring this login
+            // in anyway would let a link be relayed to this connection and then
+            // minted under the account that owns the session.
+            return;
+        }
+        session.registries.registerDeviceId(jid, 0);
+        // A reconnect of the same account replaces its stale connection here.
+        this.mobilePrimaryPipelines.set(jid, pipeline);
+    }
+    /**
+     * Offers a companion connection the refs for a primary-driven link: pushes
+     * the `pair-device` IQ it turns into a QR, and remembers each ref so the
+     * primary's upload can be routed back to this connection. Returns the refs.
+     *
+     * This is the counterpart of {@link runPairing}, where the server itself
+     * plays the primary. Here a real mobile-primary client signs the identity
+     * and the server only relays.
+     */
+    async offerCompanionPairing(pipeline, options = {}) {
+        const refs = await (0, pair_device_1.mintPairingRefs)(options.refCount);
+        // Send before registering: the builder rejects a bad ref count and the
+        // send can fail, and either would leave refs in the map that no
+        // connection will ever consume.
+        await pipeline.sendStanza((0, pair_device_1.buildPairDeviceIq)({ refs }));
+        for (const ref of refs) {
+            this.pendingCompanionOffers.set(ref, pipeline);
+        }
+        return refs;
+    }
+    /**
+     * Relays one link-code stage between the two clients running the pairing
+     * handshake. `companion_hello` mints the ref that ties the stages together
+     * and registers it as a pairing offer, so the primary's later `pair-device`
+     * upload lands on the same companion connection as the QR flow.
+     */
+    async handleLinkCodeStage(iq, context) {
+        const parsed = (0, link_code_1.parseLinkCodeStanza)(iq);
+        if (!parsed || !context) {
+            return null;
+        }
+        const sender = context.connection;
+        if (parsed.stage === 'companion_hello') {
+            const primary = parsed.phoneJid
+                ? this.mobilePrimaryPipelines.get(parsed.phoneJid)
+                : undefined;
+            if (!primary) {
+                return (0, router_1.buildIqError)(iq, { code: 404, text: 'primary-not-connected' });
+            }
+            const [ref] = await (0, pair_device_1.mintPairingRefs)(1);
+            this.linkCodeSessions.set(ref, { companion: sender, primary });
+            this.pendingCompanionOffers.set(ref, sender);
+            await primary.sendStanza((0, link_code_1.buildLinkCodeNotification)({
+                stage: 'companion_hello',
+                ref,
+                children: parsed.children
+            }));
+            return (0, router_1.buildIqResult)(iq, { content: (0, link_code_1.buildCompanionHelloResultContent)(ref) });
+        }
+        const session = parsed.ref ? this.linkCodeSessions.get(parsed.ref) : undefined;
+        if (!session || !parsed.ref) {
+            return (0, router_1.buildIqError)(iq, { code: 404, text: 'unknown-pairing-ref' });
+        }
+        const target = parsed.stage === 'primary_hello' ? session.companion : session.primary;
+        await target.sendStanza((0, link_code_1.buildLinkCodeNotification)({
+            stage: parsed.stage,
+            ref: parsed.ref,
+            children: parsed.children
+        }));
+        return (0, router_1.buildIqResult)(iq);
+    }
+    /**
+     * Host side of a companion link: hands the primary-signed identity to the
+     * connection that owns `ref` and reports what that companion advertised at
+     * registration. Resolves `null` for an unknown or already-consumed ref.
+     */
+    async completeCompanionPairing(input) {
+        const pipeline = this.pendingCompanionOffers.get(input.ref);
+        if (!pipeline) {
+            return null;
+        }
+        const registration = pipeline.clientPayload;
+        const companionPropsBytes = registration?.kind === 'registration'
+            ? (registration.devicePairingData.deviceProps ?? null)
+            : null;
+        // `<platform>` describes the primary that signed the link, not the
+        // companion. A zapo mobile session always logs in as ANDROID, so this
+        // is the only value a primary-driven link can carry here.
+        const platform = MOBILE_PRIMARY_PLATFORM;
+        await pipeline.sendStanza((0, pair_device_1.buildPairSuccessIq)({
+            deviceJid: input.deviceJid,
+            platform,
+            deviceIdentityBytes: input.deviceIdentityBytes
+        }));
+        for (const [ref, offered] of this.pendingCompanionOffers) {
+            if (offered === pipeline) {
+                this.pendingCompanionOffers.delete(ref);
+            }
+        }
+        return { companionPropsBytes, platform };
+    }
     buildMediaRequestHandler() {
         return (req, res) => {
             const rawUrl = req.url ?? '';

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';
@@ -41,6 +43,22 @@ export interface IqHandlerDeps {
         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',
@@ -249,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/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]);