@zapo-js/fake-server 1.1.0 → 1.3.0

package/dist/api/FakeWaServer.d.ts

@@ -1,5 +1,6 @@
 import { Agent as HttpsAgent } from 'node:https';
 import { type WaFakeAuthenticatedInfo, WaFakeConnectionPipeline } from '../infra/WaFakeConnectionPipeline';
+import { type FakeNoiseRootCa } from '../protocol/auth/cert-chain';
 import type { ParsedClientPayload } from '../protocol/auth/client-payload-validate';
 import type { BuildSuccessNodeInput } from '../protocol/auth/success-node';
 import type { BuildAbPropsResultInput } from '../protocol/iq/abprops';
@@ -8,8 +9,10 @@ import type { FakeBusinessProfile } from '../protocol/iq/business';
 import type { FakePrivacyCategoryName, FakePrivacySettingsState } from '../protocol/iq/privacy';
 import type { FakePrivacyTokenIssue } from '../protocol/iq/privacy-token';
 import type { FakeProfilePictureResult } from '../protocol/iq/profile';
-import type { WaFakeIqMatcher, WaFakeIqResponder } from '../protocol/iq/router';
+import { type WaFakeIqMatcher, type WaFakeIqResponder } from '../protocol/iq/router';
+import { type FakeAccountDevice } from '../protocol/push/mobile-notification';
 import type { ClientPreKeyBundle } from '../protocol/signal/prekey-upload';
+import type { FakeCompanionHostState } from '../state/fake-companion-host';
 import { type PublishedMediaBlob, type PublishMediaInput } from '../state/fake-media-store';
 import { type BinaryNode } from '../transport/codec';
 import { type AppStateSyncManager, type CapturedAppStateMutation } from './AppStateSyncManager';
@@ -48,6 +51,35 @@ export interface FakeWaServerOptions {
      * clientPayload.username : 'pending'`.
      */
     readonly sessionKey?: (info: FakeSessionKeyInfo) => string;
+    /**
+     * Also serve the WhatsApp Mobile transport on a raw TCP listener. Mobile
+     * clients dial `tcp://host:port` instead of upgrading to a WebSocket, but
+     * speak the same framing above the carrier, so both listeners share one
+     * server identity, session model, and IQ router. Pass `true` for an
+     * ephemeral port on the WebSocket host, or an object to pin host/port.
+     * Read the address back from {@link FakeWaServer.tcpUrl} and feed it to the
+     * client's `mobileTransport.tcpUrl`.
+     */
+    readonly tcp?: boolean | {
+        readonly host?: string;
+        readonly port?: number;
+    };
+    /**
+     * Root of the Noise certificate chain the server presents. Defaults to a
+     * fresh random CA per {@link FakeWaServer.listen}, read back from
+     * {@link FakeWaServer.noiseRootCa}.
+     *
+     * A client in a separate process cannot read it back: it has to pin the
+     * anchor before it dials, while the server is not listening yet. Pass a CA
+     * both sides derive from a shared seed to make it knowable ahead of time.
+     *
+     * Carries the signing half, unlike the public-only
+     * {@link FakeWaServerNoiseRootCa} this server exposes. It signs a chain no
+     * real client trusts, so it is test material rather than a secret — but a
+     * seed committed beside the tests is the intended source, not one shared
+     * with anything that matters.
+     */
+    readonly noiseRootCa?: FakeNoiseRootCa;
 }
 export interface FakeSessionKeyInfo {
     readonly clientPayload: ParsedClientPayload;
@@ -80,6 +112,11 @@ export declare class FakeWaServer {
     private rootCa;
     private serverStaticKeyPair;
     private listenInfo;
+    private readonly tcpServer;
+    private tcpListenInfo;
+    private readonly pendingCompanionOffers;
+    private readonly mobilePrimaryPipelines;
+    private readonly linkCodeSessions;
     private readonly pipelineListeners;
     private rejectMode;
     private readonly mediaStore;
@@ -90,6 +127,8 @@ export declare class FakeWaServer {
     constructor(options?: FakeWaServerOptions);
     /** State of the single default session (the only session for one client). */
     get registries(): ServerRegistries;
+    /** Companion-host account state of the default session (linked devices, key-index list). */
+    get companionHost(): FakeCompanionHostState;
     get preKeyDispenser(): PreKeyDispenser;
     get appStateSync(): AppStateSyncManager;
     /**
@@ -146,6 +185,15 @@ export declare class FakeWaServer {
     expectAppStateMutation(predicate: (mutation: CapturedAppStateMutation) => boolean, timeoutMs?: number): Promise<CapturedAppStateMutation>;
     provideAppStateCollection(name: string, provider: () => Promise<FakeAppStateCollectionPayload | null> | FakeAppStateCollectionPayload | null): () => void;
     pushServerSyncNotification(pipeline: WaFakeConnectionPipeline, input: BuildServerSyncNotificationInput): Promise<void>;
+    /**
+     * 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.
+     */
+    pushAccountSyncDevices(pipeline: WaFakeConnectionPipeline, options?: {
+        readonly devices?: readonly FakeAccountDevice[];
+    }): Promise<void>;
     onAuthenticatedPipeline(listener: AuthenticatedPipelineListener): () => void;
     scenario(configure: (s: Scenario) => void): void;
     expectIq(matcher: WaFakeIqMatcher, options?: ExpectIqOptions): Promise<BinaryNode>;
@@ -188,6 +236,13 @@ export declare class FakeWaServer {
     get url(): string;
     get host(): string;
     get port(): number;
+    /**
+     * `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(): string;
     get noiseRootCa(): FakeWaServerNoiseRootCa;
     /**
      * Subscribes to every new connection pipeline (pre-auth). Listeners
@@ -195,6 +250,7 @@ export declare class FakeWaServer {
      */
     onPipeline(listener: FakeWaServerPipelineListener): () => void;
     listen(): Promise<void>;
+    private rollbackFailedListen;
     stop(): Promise<void>;
     private handleConnection;
     /**
@@ -204,6 +260,39 @@ export declare class FakeWaServer {
      * No-op without a `sessionKey` resolver (single default session).
      */
     private bindPipelineSession;
+    /** Drops every reference to a closed connection so a relay never targets it. */
+    private forgetPipeline;
+    /**
+     * 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.
+     */
+    private bindMobilePrimary;
+    /**
+     * 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.
+     */
+    offerCompanionPairing(pipeline: WaFakeConnectionPipeline, options?: {
+        readonly refCount?: number;
+    }): Promise<readonly string[]>;
+    /**
+     * 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.
+     */
+    private handleLinkCodeStage;
+    /**
+     * 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.
+     */
+    private completeCompanionPairing;
     private buildMediaRequestHandler;
     private handleMediaUpload;
     private requireListening;

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 };
@@ -364,18 +432,42 @@ class FakeWaServer {
         }
         ;
         [this.rootCa, this.serverStaticKeyPair] = await Promise.all([
-            (0, cert_chain_1.generateFakeNoiseRootCa)(),
+            this.options.noiseRootCa ?? (0, cert_chain_1.generateFakeNoiseRootCa)(),
             crypto_1.X25519.generateKeyPair()
         ]);
         const mediaHandler = this.buildMediaRequestHandler();
         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[];