@zapo-js/fake-server 1.0.0 → 1.2.0

package/dist/esm/api/FakeWaServer.js

@@ -1,124 +1,129 @@
 import { Agent as HttpsAgent } from 'node:https';
 import { WaFakeConnectionPipeline } from '../infra/WaFakeConnectionPipeline.js';
 import { WaFakeMediaHttpsServer } from '../infra/WaFakeMediaHttpsServer.js';
+import { WaFakeTcpServer } from '../infra/WaFakeTcpServer.js';
 import { WaFakeWsServer } from '../infra/WaFakeWsServer.js';
 import { generateFakeNoiseRootCa } from '../protocol/auth/cert-chain.js';
-import { WaFakeIqRouter } from '../protocol/iq/router.js';
+import { buildPairDeviceIq, buildPairSuccessIq, mintPairingRefs } from '../protocol/auth/pair-device.js';
+import { buildCompanionHelloResultContent, buildLinkCodeNotification, parseLinkCodeStanza } from '../protocol/iq/link-code.js';
+import { buildIqError, buildIqResult } from '../protocol/iq/router.js';
+import { buildAccountSyncDevicesNotification } from '../protocol/push/mobile-notification.js';
 import { FakeMediaStore } from '../state/fake-media-store.js';
 import { X25519 } from '../transport/crypto.js';
-import { AppStateSyncManager } from './AppStateSyncManager.js';
 import { FakePairingDriver } from './FakePairingDriver.js';
 import { FakePeer } from './FakePeer.js';
-import { registerDefaultIqHandlers } from './iq-handlers.js';
-import { PreKeyDispenser } from './PreKeyDispenser.js';
+import { FakeServerSession } from './FakeServerSession.js';
 import { Scenario } from './Scenario.js';
-import { ServerRegistries } from './ServerRegistries.js';
+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({
+        host: config.host ?? options.host,
+        port: config.port
+    });
+}
+export { FakeServerSession } from './FakeServerSession.js';
 export class FakeWaServer {
     constructor(options = {}) {
-        this.registries = new ServerRegistries();
-        this.preKeyDispenser = new PreKeyDispenser();
-        this.appStateSync = new AppStateSyncManager();
         this.pipelines = new Set();
-        this.iqRouter = new WaFakeIqRouter();
-        this.capturedStanzas = [];
-        this.pendingIqExpectations = new Set();
-        this.pendingStanzaExpectations = new Set();
+        this.pipelineSessions = new WeakMap();
         this.authenticatedListeners = new Set();
-        this.inboundStanzaListeners = new Set();
-        this.capturedStanzaListeners = new Set();
+        this.sessions = new Map();
+        this.globalIqHandlers = new Set();
         this.rootCa = null;
         this.serverStaticKeyPair = null;
         this.listenInfo = null;
-        this.pipelineListener = 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 FakeMediaStore();
         this.mediaHttpsServer = new WaFakeMediaHttpsServer();
         this.capturedMediaUploads = [];
         this.nextUploadCounter = 0;
         this.cachedMediaProxyAgent = null;
+        this.options = options;
         this.wsServer = new WaFakeWsServer(options);
         this.wsServer.onConnection((connection) => this.handleConnection(connection));
-        registerDefaultIqHandlers(this.iqRouter, this.buildIqHandlerDeps());
+        this.tcpServer = createTcpServer(options);
+        this.tcpServer?.onConnection((connection) => this.handleConnection(connection));
+        this.defaultSession = this.createSession('__default__');
     }
-    buildIqHandlerDeps() {
-        const reg = this.registries;
-        const preKey = this.preKeyDispenser;
-        const appState = this.appStateSync;
-        return {
-            get peerRegistry() {
-                return reg.peerRegistry;
-            },
-            get groupRegistry() {
-                return reg.groupRegistry;
-            },
-            get privacySettings() {
-                return reg.privacySettings;
-            },
-            get blocklistJids() {
-                return reg.blocklistJids;
-            },
-            get profilePicturesByJid() {
-                return reg.profilePicturesByJid;
-            },
-            get businessProfilesByJid() {
-                return reg.businessProfilesByJid;
-            },
-            get abPropsInput() {
-                return reg.abPropsInput;
-            },
-            get issuedPrivacyTokens() {
-                return reg.issuedPrivacyTokens;
-            },
-            get latestStatusText() {
-                return reg.latestStatusText;
-            },
-            setLatestStatusText: (text) => {
-                reg.latestStatusText = text;
-            },
-            lookupDeviceIdsForUser: (userJid) => reg.lookupDeviceIdsForUser(userJid),
-            notifyGroupOp: (op) => reg.notifyGroupOp(op),
-            mutatePrivacySettings: (category, value) => reg.mutatePrivacySettings(category, value),
-            mutateBlocklist: (action, jid) => reg.mutateBlocklist(action, jid),
-            notifyProfilePictureSet: (op) => reg.notifyProfilePictureSet(op),
-            handleProfilePictureSet: (targetJid, newId) => reg.handleProfilePictureSet(targetJid, newId),
-            notifyStatusSet: (text) => reg.notifyStatusSet(text),
-            notifyLogout: () => reg.notifyLogout(),
-            notifyPrivacyTokenIssue: (token) => reg.notifyPrivacyTokenIssue(token),
-            notifyDirtyBitsClear: (op) => reg.notifyDirtyBitsClear(op),
-            notifyPrivacySet: (change) => {
-                for (const listener of reg.privacySetListeners) {
-                    try {
-                        listener(change);
-                    }
-                    catch (error) {
-                        void error;
-                    }
-                }
-            },
-            notifyBlocklistChange: (change) => {
-                for (const listener of reg.blocklistChangeListeners) {
-                    try {
-                        listener(change);
-                    }
-                    catch (error) {
-                        void error;
-                    }
-                }
-            },
-            capturePreKeyBundle: (bundle) => preKey.captureBundle(bundle),
-            consumeOutboundAppStatePatches: (iq) => appState.consumeOutboundAppStatePatches(iq),
-            get appStateCollectionProviders() {
-                return appState.appStateCollectionProviders;
-            },
-            requireMediaHttpsInfo: () => this.requireMediaHttpsInfo()
-        };
+    /** 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;
+    }
+    get appStateSync() {
+        return this.defaultSession.appStateSync;
+    }
+    /**
+     * Returns the isolated session for `id`, creating it on first use. Every
+     * session gets its own registries, prekey dispenser, app-state, IQ router,
+     * and stanza capture. Use with the `sessionKey` option to run several
+     * `WaClient`s against one server without them sharing any state.
+     */
+    session(id) {
+        const existing = this.sessions.get(id);
+        if (existing) {
+            return existing;
+        }
+        return this.createSession(id);
+    }
+    /** The session a connection is bound to (default before authentication). */
+    sessionFor(pipeline) {
+        return this.pipelineSessions.get(pipeline) ?? this.defaultSession;
+    }
+    createSession(id) {
+        const session = new 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) {
+            handler.unregisterBySession.set(session, session.registerIqHandler(handler.matcher, handler.respond, handler.label));
+        }
+        return session;
     }
     registerIqHandler(matcher, respond, label) {
-        const handler = { matcher, respond, label };
-        return this.iqRouter.register(handler, { priority: 'high' });
+        const entry = {
+            matcher,
+            respond,
+            label,
+            unregisterBySession: new Map()
+        };
+        for (const session of this.sessions.values()) {
+            entry.unregisterBySession.set(session, session.registerIqHandler(matcher, respond, label));
+        }
+        this.globalIqHandlers.add(entry);
+        return () => {
+            for (const unregister of entry.unregisterBySession.values()) {
+                unregister();
+            }
+            entry.unregisterBySession.clear();
+            this.globalIqHandlers.delete(entry);
+        };
     }
     async routeIqForTest(iq) {
-        return this.iqRouter.route(iq);
+        return this.defaultSession.routeIq(iq);
     }
     onOutboundGroupOp(listener) {
         return this.registries.onOutboundGroupOp(listener);
@@ -175,7 +180,7 @@ export class FakeWaServer {
         return this.registries.createFakeGroup(input);
     }
     async triggerPreKeyUpload(pipeline, options = {}) {
-        return this.preKeyDispenser.triggerPreKeyUpload(pipeline, options);
+        return this.sessionFor(pipeline).preKeyDispenser.triggerPreKeyUpload(pipeline, options);
     }
     awaitPreKeyBundle(timeoutMs = 15000) {
         return this.preKeyDispenser.awaitPreKeyBundle(timeoutMs);
@@ -205,7 +210,28 @@ export class FakeWaServer {
         return this.appStateSync.provideAppStateCollection(name, provider);
     }
     async pushServerSyncNotification(pipeline, input) {
-        return this.appStateSync.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(buildAccountSyncDevicesNotification({ devices }));
     }
     onAuthenticatedPipeline(listener) {
         this.authenticatedListeners.add(listener);
@@ -215,78 +241,24 @@ export class FakeWaServer {
         configure(new Scenario(this));
     }
     expectIq(matcher, options = {}) {
-        const timeoutMs = options.timeoutMs ?? 2000;
-        for (const captured of this.capturedStanzas) {
-            if (matchesIq(captured, matcher)) {
-                return Promise.resolve(captured);
-            }
-        }
-        return new Promise((resolve, reject) => {
-            const expectation = {
-                matcher,
-                resolve: (iq) => {
-                    this.pendingIqExpectations.delete(expectation);
-                    clearTimeout(expectation.timer);
-                    resolve(iq);
-                },
-                reject: (error) => {
-                    this.pendingIqExpectations.delete(expectation);
-                    clearTimeout(expectation.timer);
-                    reject(error);
-                },
-                timer: setTimeout(() => {
-                    this.pendingIqExpectations.delete(expectation);
-                    reject(new Error(`expectIq timed out after ${timeoutMs}ms (${describeMatcher(matcher)})`));
-                }, timeoutMs)
-            };
-            this.pendingIqExpectations.add(expectation);
-        });
+        return this.defaultSession.expectIq(matcher, options);
     }
     capturedStanzaSnapshot() {
-        return this.capturedStanzas.slice();
+        return this.defaultSession.capturedStanzaSnapshot();
     }
     /**
-     * Subscribes to every stanza captured from the client side (the lib).
-     * The listener is called synchronously for each new stanza as it
-     * arrives, in addition to `capturedStanzas` being appended. Returns
-     * an unsubscribe function. Useful for benches that need to count or
-     * react to a stream of receipts/messages without paying the O(N²)
-     * cost of polling `capturedStanzaSnapshot()` or queuing one
-     * `expectStanza(...)` per iteration.
+     * Subscribes to every stanza captured from the client side (the lib) of
+     * the default session. The listener is called synchronously for each new
+     * stanza as it arrives. Returns an unsubscribe function. Useful for
+     * benches that need to count or react to a stream of receipts/messages
+     * without paying the O(N²) cost of polling `capturedStanzaSnapshot()` or
+     * queuing one `expectStanza(...)` per iteration.
      */
     onCapturedStanza(listener) {
-        this.capturedStanzaListeners.add(listener);
-        return () => {
-            this.capturedStanzaListeners.delete(listener);
-        };
+        return this.defaultSession.onCapturedStanza(listener);
     }
     expectStanza(matcher, options = {}) {
-        const timeoutMs = options.timeoutMs ?? 2000;
-        for (const captured of this.capturedStanzas) {
-            if (matchesStanza(captured, matcher)) {
-                return Promise.resolve(captured);
-            }
-        }
-        return new Promise((resolve, reject) => {
-            const expectation = {
-                matcher,
-                resolve: (node) => {
-                    this.pendingStanzaExpectations.delete(expectation);
-                    clearTimeout(expectation.timer);
-                    resolve(node);
-                },
-                reject: (error) => {
-                    this.pendingStanzaExpectations.delete(expectation);
-                    clearTimeout(expectation.timer);
-                    reject(error);
-                },
-                timer: setTimeout(() => {
-                    this.pendingStanzaExpectations.delete(expectation);
-                    reject(new Error(`expectStanza timed out after ${timeoutMs}ms (${describeStanzaMatcher(matcher)})`));
-                }, timeoutMs)
-            };
-            this.pendingStanzaExpectations.add(expectation);
-        });
+        return this.defaultSession.expectStanza(matcher, options);
     }
     async broadcastStanza(node) {
         const tasks = [];
@@ -348,8 +320,9 @@ export class FakeWaServer {
         return this.capturedMediaUploads.slice();
     }
     async createFakePeer(options, pipeline) {
-        const peer = await FakePeer.create(options, this.buildFakePeerDeps(pipeline));
-        this.registries.registerPeer(peer);
+        const session = this.sessionFor(pipeline);
+        const peer = await FakePeer.create(options, this.buildFakePeerDeps(pipeline, session));
+        session.registries.registerPeer(peer);
         return peer;
     }
     async createFakePeerWithDevices(input, pipeline) {
@@ -362,6 +335,7 @@ export class FakeWaServer {
         }
         const userPart = input.userJid.slice(0, atIdx);
         const server = input.userJid.slice(atIdx + 1);
+        const session = this.sessionFor(pipeline);
         const peers = [];
         for (const deviceId of input.deviceIds) {
             const deviceJid = deviceId === 0 ? input.userJid : `${userPart}:${deviceId}@${server}`;
@@ -369,36 +343,27 @@ export class FakeWaServer {
                 jid: deviceJid,
                 displayName: input.displayName,
                 skipOneTimePreKey: input.skipOneTimePreKey
-            }, this.buildFakePeerDeps(pipeline));
-            this.registries.registerPeer(peer);
+            }, this.buildFakePeerDeps(pipeline, session));
+            session.registries.registerPeer(peer);
             peers.push(peer);
         }
         return peers;
     }
-    buildFakePeerDeps(pipeline) {
+    buildFakePeerDeps(pipeline, session) {
         return {
-            bundleResolver: () => this.preKeyDispenser.awaitPreKeyBundle(),
-            reserveOneTimePreKey: () => this.preKeyDispenser.dispenseOneTimePreKey(),
+            bundleResolver: () => session.preKeyDispenser.awaitPreKeyBundle(),
+            reserveOneTimePreKey: () => session.preKeyDispenser.dispenseOneTimePreKey(),
             pushStanza: (stanza) => pipeline.sendStanza(stanza),
-            subscribeInboundMessages: (listener) => {
-                const wrapped = (node) => {
-                    if (node.tag !== 'message')
-                        return;
-                    listener(node);
-                };
-                this.inboundStanzaListeners.add(wrapped);
-                return () => {
-                    this.inboundStanzaListeners.delete(wrapped);
-                };
-            }
+            subscribeInboundMessages: (listener) => session.subscribeInboundMessages(listener)
         };
     }
     async runPairing(pipeline, options, companionMaterialResolver) {
+        const session = this.sessionFor(pipeline);
         const driver = new FakePairingDriver(options, {
             pipeline,
             companionMaterialResolver,
             waitForPairDeviceAck: async (pairDeviceIqId) => {
-                await this.expectIq({
+                await session.expectIq({
                     id: pairDeviceIqId
                 }, {
                     timeoutMs: 15000
@@ -431,12 +396,31 @@ export 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 };
     }
+    /**
+     * Subscribes to every new connection pipeline (pre-auth). Listeners
+     * fan out; returns an unsubscribe function.
+     */
     onPipeline(listener) {
-        this.pipelineListener = listener;
+        this.pipelineListeners.add(listener);
+        return () => {
+            this.pipelineListeners.delete(listener);
+        };
     }
     async listen() {
         if (this.listenInfo) {
@@ -451,11 +435,35 @@ export 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();
@@ -478,53 +486,185 @@ export class FakeWaServer {
             connection,
             rootCa: this.rootCa,
             serverStaticKeyPair: this.serverStaticKeyPair,
-            iqRouter: this.iqRouter
+            routeIq: (node) => this.sessionFor(pipeline).routeIq(node, { connection: pipeline }),
+            ...(this.options.successNodeAttributes !== undefined
+                ? { successNodeAttributes: this.options.successNodeAttributes }
+                : {})
         });
         this.pipelines.add(pipeline);
+        this.pipelineSessions.set(pipeline, this.defaultSession);
         pipeline.setEvents({
             onAuthenticated: () => {
+                this.bindPipelineSession(pipeline);
+                this.bindMobilePrimary(pipeline);
                 for (const listener of this.authenticatedListeners) {
-                    void listener(pipeline);
+                    try {
+                        void Promise.resolve(listener(pipeline)).catch(() => undefined);
+                    }
+                    catch {
+                        /* ignore */
+                    }
                 }
             },
-            onStanza: (node) => this.handleCapturedStanza(node),
-            onClose: () => this.pipelines.delete(pipeline)
+            onStanza: (node) => this.sessionFor(pipeline).handleCapturedStanza(node),
+            onClose: () => this.forgetPipeline(pipeline)
         });
-        this.pipelineListener?.(pipeline);
-    }
-    handleCapturedStanza(node) {
-        this.capturedStanzas.push(node);
-        for (const listener of this.capturedStanzaListeners) {
+        for (const listener of this.pipelineListeners) {
             try {
-                listener(node);
+                void Promise.resolve(listener(pipeline)).catch(() => undefined);
             }
-            catch (error) {
-                void error;
+            catch {
+                /* ignore */
             }
         }
-        for (const listener of this.inboundStanzaListeners) {
-            try {
-                listener(node);
+    }
+    /**
+     * Rebinds a connection to its keyed session once authenticated. Runs
+     * before user `onAuthenticated` listeners and before any client stanza, so
+     * captures and IQ routing land in the right session from the first frame.
+     * No-op without a `sessionKey` resolver (single default session).
+     */
+    bindPipelineSession(pipeline) {
+        const resolveKey = this.options.sessionKey;
+        const clientPayload = pipeline.clientPayload;
+        if (!resolveKey || !clientPayload) {
+            return;
+        }
+        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);
             }
-            catch (error) {
-                void error;
+        }
+        for (const [jid, primary] of this.mobilePrimaryPipelines) {
+            if (primary === pipeline) {
+                this.mobilePrimaryPipelines.delete(jid);
             }
         }
-        for (const expectation of this.pendingStanzaExpectations) {
-            if (matchesStanza(node, expectation.matcher)) {
-                expectation.resolve(node);
-                break;
+        for (const [ref, session] of this.linkCodeSessions) {
+            if (session.companion === pipeline || session.primary === pipeline) {
+                this.linkCodeSessions.delete(ref);
             }
         }
-        if (node.tag !== 'iq') {
+    }
+    /**
+     * 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;
         }
-        for (const expectation of this.pendingIqExpectations) {
-            if (matchesIq(node, expectation.matcher)) {
-                expectation.resolve(node);
-                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 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(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 = 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 buildIqError(iq, { code: 404, text: 'primary-not-connected' });
             }
+            const [ref] = await mintPairingRefs(1);
+            this.linkCodeSessions.set(ref, { companion: sender, primary });
+            this.pendingCompanionOffers.set(ref, sender);
+            await primary.sendStanza(buildLinkCodeNotification({
+                stage: 'companion_hello',
+                ref,
+                children: parsed.children
+            }));
+            return buildIqResult(iq, { content: buildCompanionHelloResultContent(ref) });
         }
+        const session = parsed.ref ? this.linkCodeSessions.get(parsed.ref) : undefined;
+        if (!session || !parsed.ref) {
+            return buildIqError(iq, { code: 404, text: 'unknown-pairing-ref' });
+        }
+        const target = parsed.stage === 'primary_hello' ? session.companion : session.primary;
+        await target.sendStanza(buildLinkCodeNotification({
+            stage: parsed.stage,
+            ref: parsed.ref,
+            children: parsed.children
+        }));
+        return 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(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) => {
@@ -612,69 +752,3 @@ function parseQueryParam(query, name) {
     }
     return undefined;
 }
-function matchesIq(iq, matcher) {
-    if (iq.tag !== 'iq')
-        return false;
-    if (matcher.id !== undefined && iq.attrs.id !== matcher.id)
-        return false;
-    if (matcher.type !== undefined && iq.attrs.type !== matcher.type)
-        return false;
-    if (matcher.xmlns !== undefined && iq.attrs.xmlns !== matcher.xmlns)
-        return false;
-    if (matcher.childTag !== undefined) {
-        const children = Array.isArray(iq.content) ? iq.content : null;
-        if (!children || children.length === 0)
-            return false;
-        if (children[0].tag !== matcher.childTag)
-            return false;
-    }
-    return true;
-}
-function describeMatcher(matcher) {
-    const parts = [];
-    if (matcher.id !== undefined)
-        parts.push(`id=${matcher.id}`);
-    if (matcher.type !== undefined)
-        parts.push(`type=${matcher.type}`);
-    if (matcher.xmlns !== undefined)
-        parts.push(`xmlns=${matcher.xmlns}`);
-    if (matcher.childTag !== undefined)
-        parts.push(`childTag=${matcher.childTag}`);
-    return parts.length > 0 ? parts.join(', ') : 'any iq';
-}
-function matchesStanza(node, matcher) {
-    if (matcher.tag !== undefined && node.tag !== matcher.tag)
-        return false;
-    if (matcher.type !== undefined && node.attrs.type !== matcher.type)
-        return false;
-    if (matcher.xmlns !== undefined && node.attrs.xmlns !== matcher.xmlns)
-        return false;
-    if (matcher.from !== undefined && node.attrs.from !== matcher.from)
-        return false;
-    if (matcher.to !== undefined && node.attrs.to !== matcher.to)
-        return false;
-    if (matcher.childTag !== undefined) {
-        const children = Array.isArray(node.content) ? node.content : null;
-        if (!children || children.length === 0)
-            return false;
-        if (children[0].tag !== matcher.childTag)
-            return false;
-    }
-    return true;
-}
-function describeStanzaMatcher(matcher) {
-    const parts = [];
-    if (matcher.tag !== undefined)
-        parts.push(`tag=${matcher.tag}`);
-    if (matcher.type !== undefined)
-        parts.push(`type=${matcher.type}`);
-    if (matcher.xmlns !== undefined)
-        parts.push(`xmlns=${matcher.xmlns}`);
-    if (matcher.from !== undefined)
-        parts.push(`from=${matcher.from}`);
-    if (matcher.to !== undefined)
-        parts.push(`to=${matcher.to}`);
-    if (matcher.childTag !== undefined)
-        parts.push(`childTag=${matcher.childTag}`);
-    return parts.length > 0 ? parts.join(', ') : 'any stanza';
-}