@zapo-js/fake-server 1.1.0 → 1.3.0

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]);

package/dist/esm/api/FakeServerSession.js

@@ -1,9 +1,11 @@
 /** Per-session isolated server state: registries, prekeys, app-state, IQ routing, capture. */
 import { WaFakeIqRouter } from '../protocol/iq/router.js';
+import { FakeCompanionHostState, readCompanionKeyIndex } from '../state/fake-companion-host.js';
 import { AppStateSyncManager } from './AppStateSyncManager.js';
 import { registerDefaultIqHandlers } from './iq-handlers.js';
 import { PreKeyDispenser } from './PreKeyDispenser.js';
-import { ServerRegistries } from './ServerRegistries.js';
+import { ServerRegistries, toDeviceIdPart } from './ServerRegistries.js';
+const HOST_DOMAIN = 's.whatsapp.net';
 /**
  * One isolated logical device's worth of server state. Every `WaClient`
  * connected to a `FakeWaServer` is bound to exactly one session; peers,
@@ -16,6 +18,7 @@ export class FakeServerSession {
         this.registries = new ServerRegistries();
         this.preKeyDispenser = new PreKeyDispenser();
         this.appStateSync = new AppStateSyncManager();
+        this.companionHost = new FakeCompanionHostState();
         this.iqRouter = new WaFakeIqRouter();
         this.capturedStanzas = [];
         this.pendingIqExpectations = new Set();
@@ -31,8 +34,8 @@ export class FakeServerSession {
         const handler = { matcher, respond, label };
         return this.iqRouter.register(handler, { priority: 'high' });
     }
-    routeIq(iq) {
-        return this.iqRouter.route(iq);
+    routeIq(iq, context) {
+        return this.iqRouter.route(iq, context);
     }
     handleCapturedStanza(node) {
         this.capturedStanzas.push(node);
@@ -148,6 +151,7 @@ export class FakeServerSession {
         const reg = this.registries;
         const preKey = this.preKeyDispenser;
         const appState = this.appStateSync;
+        const companionHost = this.companionHost;
         return {
             get peerRegistry() {
                 return reg.peerRegistry;
@@ -215,9 +219,67 @@ export class FakeServerSession {
             get appStateCollectionProviders() {
                 return appState.appStateCollectionProviders;
             },
-            requireMediaHttpsInfo: () => host.requireMediaHttpsInfo()
+            requireMediaHttpsInfo: () => host.requireMediaHttpsInfo(),
+            get mobilePrimary() {
+                return companionHost.primary;
+            },
+            relayLinkCodeStage: (iq, context) => host.relayLinkCodeStage(iq, context),
+            linkCompanionDevice: (upload) => this.linkCompanionDevice(host, upload),
+            revokeCompanionDevices: (deviceJids) => this.revokeCompanionDevices(deviceJids),
+            recordKeyIndexList: (bytes, timestampSeconds) => companionHost.recordKeyIndexList(bytes, timestampSeconds)
         };
     }
+    /**
+     * Server side of the primary's `pair-device` upload: allocates the device
+     * slot, hands the signed identity to the companion connection, and records
+     * the link. Resolves `null` when this session has no primary or the ref
+     * belongs to no live connection, which the handler turns into an IQ error.
+     */
+    async linkCompanionDevice(host, upload) {
+        const primary = this.companionHost.primary;
+        if (!primary) {
+            return null;
+        }
+        const deviceId = this.companionHost.allocateDeviceId();
+        const deviceJid = `${primary.username}:${deviceId}@${HOST_DOMAIN}`;
+        const completed = await host
+            .completeCompanionPairing({
+            ref: upload.ref,
+            deviceJid,
+            deviceIdentityBytes: upload.deviceIdentityBytes
+        })
+            .catch((error) => {
+            this.companionHost.releaseDeviceId(deviceId);
+            throw error;
+        });
+        if (!completed) {
+            this.companionHost.releaseDeviceId(deviceId);
+            return null;
+        }
+        this.companionHost.recordCompanion({
+            deviceJid,
+            deviceId,
+            ref: upload.ref,
+            keyIndex: readCompanionKeyIndex(upload.deviceIdentityBytes),
+            deviceIdentityBytes: upload.deviceIdentityBytes,
+            linkedAtSeconds: Math.floor(Date.now() / 1000)
+        });
+        this.companionHost.recordKeyIndexList(upload.keyIndexListBytes, upload.keyIndexListTimestampSeconds);
+        this.registries.registerDeviceId(primary.jid, deviceId);
+        return { deviceJid, companionPropsBytes: completed.companionPropsBytes };
+    }
+    revokeCompanionDevices(deviceJids) {
+        const removed = deviceJids
+            ? this.companionHost.removeCompanions(deviceJids)
+            : this.companionHost.removeAllCompanions();
+        const primary = this.companionHost.primary;
+        if (primary) {
+            for (const deviceJid of removed) {
+                this.registries.unregisterDeviceId(primary.jid, toDeviceIdPart(deviceJid));
+            }
+        }
+        return removed;
+    }
 }
 export function matchesIq(iq, matcher) {
     if (iq.tag !== 'iq')

package/dist/esm/api/FakeWaServer.js

@@ -1,14 +1,35 @@
 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 { 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 { FakePairingDriver } from './FakePairingDriver.js';
 import { FakePeer } from './FakePeer.js';
 import { FakeServerSession } from './FakeServerSession.js';
 import { Scenario } from './Scenario.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 = {}) {
@@ -20,6 +41,10 @@ export 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 FakeMediaStore();
@@ -30,12 +55,18 @@ export class FakeWaServer {
         this.options = options;
         this.wsServer = new 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;
     }
@@ -60,7 +91,11 @@ export class FakeWaServer {
         return this.pipelineSessions.get(pipeline) ?? this.defaultSession;
     }
     createSession(id) {
-        const session = new FakeServerSession(id, { requireMediaHttpsInfo: () => this.requireMediaHttpsInfo() }, { defaultIqHandlers: this.options.defaultIqHandlers !== false });
+        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) {
@@ -177,6 +212,27 @@ export 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(buildAccountSyncDevicesNotification({ devices }));
+    }
     onAuthenticatedPipeline(listener) {
         this.authenticatedListeners.add(listener);
         return () => this.authenticatedListeners.delete(listener);
@@ -340,6 +396,18 @@ 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 };
@@ -360,18 +428,42 @@ export class FakeWaServer {
         }
         ;
         [this.rootCa, this.serverStaticKeyPair] = await Promise.all([
-            generateFakeNoiseRootCa(),
+            this.options.noiseRootCa ?? generateFakeNoiseRootCa(),
             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();
@@ -394,7 +486,7 @@ export 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 }
                 : {})
@@ -404,6 +496,7 @@ export 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);
@@ -414,7 +507,7 @@ export 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 {
@@ -440,6 +533,139 @@ export 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 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) => {
             const rawUrl = req.url ?? '';