@zapo-js/fake-server 1.1.0 → 1.2.0

package/README.md

@@ -1,6 +1,10 @@
 # @zapo-js/fake-server
 
-In-process fake WhatsApp Web server that drives the real `zapo-js` `WaClient` end-to-end - full Noise XX/IK handshake, QR pairing, Signal Protocol (X3DH + Double Ratchet), SenderKey for groups, media upload/download over self-signed HTTPS, app-state sync - all without touching WhatsApp servers.
+In-process fake WhatsApp server that drives the real `zapo-js` `WaClient` end-to-end - full Noise XX/IK handshake, QR pairing, Signal Protocol (X3DH + Double Ratchet), SenderKey for groups, media upload/download over self-signed HTTPS, app-state sync - all without touching WhatsApp servers.
+
+It serves both transports: companions over WebSocket, and phones over the
+mobile TCP transport, including the companion-hosting side of a primary
+(pair-device, key-index list, pairing-code handshake).
 
 ## Install
 
@@ -37,9 +41,10 @@ await server.stop()
 ```text
 src/
 ├── api/                     # Public-facing API
-│   ├── FakeWaServer.ts      # Main facade – WS server, IQ router, registries, lifecycle
+│   ├── FakeWaServer.ts      # Main facade – WS/TCP servers, IQ router, registries, lifecycle
 │   ├── FakePeer.ts          # Simulated WhatsApp peer – Signal crypto, send/recv, groups
-│   ├── FakePairingDriver.ts # QR pairing flow orchestrator
+│   ├── FakePairingDriver.ts # QR pairing flow orchestrator (server plays the primary)
+│   ├── FakeMobilePrimary.ts # Registered mobile-primary credentials for a phone client
 │   └── Scenario.ts          # Declarative test scenario DSL
 ├── protocol/                # Protocol-layer builders, parsers, crypto
 │   ├── auth/                # Pairing, ADV identity, cert chain, client payload
@@ -48,8 +53,10 @@ src/
 │   ├── signal/              # Signal Protocol impl (Double Ratchet, SenderKey, prekeys)
 │   └── stream/              # Stream error builders
 ├── infra/                   # Transport infrastructure
-│   ├── WaFakeWsServer.ts    # Raw WebSocket server (ws)
-│   ├── WaFakeConnection.ts  # Per-connection WS wrapper
+│   ├── WaFakeWsServer.ts    # Raw WebSocket server (ws) – companion transport
+│   ├── WaFakeTcpServer.ts   # Raw TCP server – mobile transport
+│   ├── socket-adapters.ts   # Per-carrier socket adapters (WebSocket, TCP)
+│   ├── WaFakeConnection.ts  # Per-connection, carrier-agnostic wrapper
 │   ├── WaFakeConnectionPipeline.ts  # Noise handshake + authenticated frame transport
 │   ├── WaFakeFrameSocket.ts # Length-prefixed framing layer
 │   ├── WaFakeTransport.ts   # AES-GCM noise transport (post-handshake encrypt/decrypt)
@@ -148,35 +155,87 @@ Simulated WhatsApp peer with real Signal Protocol crypto:
 
 After pairing, the lib reconnects with IK handshake. Use `waitForNextAuthenticatedPipeline()` to capture the post-pair pipeline.
 
+### Mobile transport (phone clients)
+
+Start the server with `{ tcp: true }` to also listen for the WhatsApp Mobile
+transport, which dials `tcp://host:port` instead of upgrading to a WebSocket.
+Both listeners share one server identity, session model, and IQ router.
+
+Registration happens out of band (against WhatsApp's HTTP endpoints), so a
+phone session starts from credentials that already exist – seed them with
+`seedFakeMobilePrimary`:
+
+```ts
+const server = await FakeWaServer.start({ tcp: true })
+const store = createStore({})
+const primary = await seedFakeMobilePrimary(store, 'phone-session', {
+    phoneNumber: '5511999999999'
+})
+
+const client = new WaClient({
+    store,
+    sessionId: 'phone-session',
+    mobileTransport: { deviceInfo: primary.deviceInfo, tcpUrl: server.tcpUrl },
+    testHooks: { noiseRootCa: server.noiseRootCa }
+})
+```
+
+### Companion hosting (a phone links a companion)
+
+The inverse of `runPairing`: the identity is signed by a real mobile-primary
+client rather than by the server, which relays that signed exchange and does the
+account bookkeeping around it. `offerCompanionPairing(pipeline)` pushes the refs
+a companion turns into its QR; when the primary uploads `pair-device` for one of
+them, the server mints the device jid, hands the signed identity to the
+companion as `pair-success`, and tracks the link.
+
+```ts
+await server.offerCompanionPairing(companionPipeline)
+const linked = await primary.mobile.linkCompanion(qrFromCompanion)
+server.companionHost.linkedCompanions() // [{ deviceJid, keyIndex, ... }]
+```
+
+The pairing-code flow works the same way end to end: the server mints the ref on
+`companion_hello` and relays `primary_hello` / `companion_finish` between the two
+clients, so `client.auth.requestPairingCode()` on one side and
+`client.mobile.linkCompanionByCode()` on the other complete a real handshake.
+
+`pushAccountSyncDevices(pipeline)` pushes the account's device set as an
+`account_sync` notification – pass a shorter list to tell a primary that a
+device disappeared while it was offline.
+
 ## IQ coverage
 
 Every outbound IQ the lib sends during normal operation is handled:
 
-| IQ                                                                               | Handler                       | State mutation                          |
-| -------------------------------------------------------------------------------- | ----------------------------- | --------------------------------------- |
-| `abt` get                                                                        | `abprops`                     | Seedable via `setAbProps()`             |
-| `w:p` / `urn:xmpp:ping` get                                                      | `whatsapp-ping` / `xmpp-ping` | Ack                                     |
-| `encrypt` set                                                                    | `prekey-upload`               | Captures bundle, resets dispenser       |
-| `encrypt` get `<digest>`                                                         | `signal-digest`               | Returns 404 → forces upload             |
-| `encrypt` get `<count>`                                                          | `prekey-count`                | Serves remaining dispenser prekey count |
-| `encrypt` set `<rotate>`                                                         | `signed-prekey-rotate`        | Ack                                     |
-| `encrypt` get `<key>`                                                            | `prekey-fetch`                | Serves peer bundles from registry       |
-| `passive` set                                                                    | `passive-mode`                | Ack                                     |
-| `usync` get                                                                      | `usync`                       | Resolves device IDs from registry       |
-| `w:m` set `<media_conn>`                                                         | `media-conn`                  | Points lib at fake HTTPS server         |
-| `w:sync:app:state` set                                                           | `app-state-sync`              | Serves patches/snapshots from providers |
-| `w:g2` get `<query>`                                                             | `group-metadata`              | Serves from group registry              |
-| `w:g2` set `<create\|add\|remove\|promote\|demote\|subject\|description\|leave>` | `group-*`                     | Mutates group registry                  |
-| `privacy` get                                                                    | `privacy-get`                 | Serves settings + disallowed lists      |
-| `privacy` set `<privacy>`                                                        | `privacy-set`                 | Mutates privacy state                   |
-| `privacy` set `<tokens>`                                                         | `privacy-token-issue`         | Captures issued tokens                  |
-| `blocklist` get/set                                                              | `blocklist-*`                 | Mutates blocklist                       |
-| `w:profile:picture` get/set                                                      | `profile-picture-*`           | Mutates profile picture registry        |
-| `status` set                                                                     | `status-set`                  | Captures latest status                  |
-| `w:biz` get/set                                                                  | `business-profile-*`          | Serves/captures business profiles       |
-| `md` set `<remove-companion-device>`                                             | `remove-companion-device`     | Fires logout listeners                  |
-| `newsletter` get `<my_addons>`                                                   | `newsletter-my-addons`        | Ack                                     |
-| `urn:xmpp:whatsapp:dirty` set                                                    | `dirty-bits-clear`            | Captures cleared bits                   |
+| IQ                                                                               | Handler                       | State mutation                            |
+| -------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------------- |
+| `abt` get                                                                        | `abprops`                     | Seedable via `setAbProps()`               |
+| `w:p` / `urn:xmpp:ping` get                                                      | `whatsapp-ping` / `xmpp-ping` | Ack                                       |
+| `encrypt` set                                                                    | `prekey-upload`               | Captures bundle, resets dispenser         |
+| `encrypt` get `<digest>`                                                         | `signal-digest`               | Returns 404 → forces upload               |
+| `encrypt` get `<count>`                                                          | `prekey-count`                | Serves remaining dispenser prekey count   |
+| `encrypt` set `<rotate>`                                                         | `signed-prekey-rotate`        | Ack                                       |
+| `encrypt` get `<key>`                                                            | `prekey-fetch`                | Serves peer bundles from registry         |
+| `passive` set                                                                    | `passive-mode`                | Ack                                       |
+| `usync` get                                                                      | `usync`                       | Resolves device IDs from registry         |
+| `w:m` set `<media_conn>`                                                         | `media-conn`                  | Points lib at fake HTTPS server           |
+| `w:sync:app:state` set                                                           | `app-state-sync`              | Serves patches/snapshots from providers   |
+| `w:g2` get `<query>`                                                             | `group-metadata`              | Serves from group registry                |
+| `w:g2` set `<create\|add\|remove\|promote\|demote\|subject\|description\|leave>` | `group-*`                     | Mutates group registry                    |
+| `privacy` get                                                                    | `privacy-get`                 | Serves settings + disallowed lists        |
+| `privacy` set `<privacy>`                                                        | `privacy-set`                 | Mutates privacy state                     |
+| `privacy` set `<tokens>`                                                         | `privacy-token-issue`         | Captures issued tokens                    |
+| `blocklist` get/set                                                              | `blocklist-*`                 | Mutates blocklist                         |
+| `w:profile:picture` get/set                                                      | `profile-picture-*`           | Mutates profile picture registry          |
+| `status` set                                                                     | `status-set`                  | Captures latest status                    |
+| `w:biz` get/set                                                                  | `business-profile-*`          | Serves/captures business profiles         |
+| `md` set `<remove-companion-device>`                                             | `remove-companion-device`     | Unlinks a hosted device, else logs out    |
+| `md` set `<pair-device>`                                                         | `companion-pair-device`       | Mints the device jid, relays pair-success |
+| `md` set `<key-index-list>`                                                      | `companion-key-index-list`    | Records the published list                |
+| `md` set `<link_code_companion_reg>`                                             | `link-code-companion-reg`     | Relays the pairing-code handshake         |
+| `newsletter` get `<my_addons>`                                                   | `newsletter-my-addons`        | Ack                                       |
+| `urn:xmpp:whatsapp:dirty` set                                                    | `dirty-bits-clear`            | Captures cleared bits                     |
 
 ## Using with non-zapo-js clients
 

package/dist/api/FakeMobilePrimary.d.ts

@@ -0,0 +1,55 @@
+/** Registered mobile-primary credentials for driving a phone-side client. */
+import type { WaAuthCredentials, WaMobileTransportDeviceInfo, WaStore } from '../transport/auth';
+export interface SeedFakeMobilePrimaryOptions {
+    /** Account phone number, digits only (for example `5511999999999`). */
+    readonly phoneNumber: string;
+    /** Overrides merged over the default phone identity. */
+    readonly deviceInfo?: Partial<WaMobileTransportDeviceInfo>;
+    readonly pushName?: string;
+    /**
+     * LID user part. Set it to make the primary LID-native, which is what
+     * drives `<client-props isChatDbLidMigrated>` on a pair-device upload.
+     */
+    readonly lidUser?: string;
+}
+export interface FakeMobilePrimary {
+    /** `<phone>@s.whatsapp.net` – the primary is always device 0. */
+    readonly meJid: string;
+    readonly meLid: string | null;
+    readonly deviceInfo: WaMobileTransportDeviceInfo;
+    readonly credentials: WaAuthCredentials;
+}
+/**
+ * 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 declare function seedFakeMobilePrimary(store: WaStore, sessionId: string, options: SeedFakeMobilePrimaryOptions): Promise<FakeMobilePrimary>;
+/**
+ * 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 declare function createFakeMobilePrimary(options: SeedFakeMobilePrimaryOptions): Promise<FakeMobilePrimary>;

package/dist/api/FakeMobilePrimary.js

@@ -0,0 +1,106 @@
+"use strict";
+/** Registered mobile-primary credentials for driving a phone-side client. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.seedFakeMobilePrimary = seedFakeMobilePrimary;
+exports.createFakeMobilePrimary = createFakeMobilePrimary;
+const crypto_1 = require("../transport/crypto");
+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.
+ */
+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.
+ */
+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([
+        crypto_1.X25519.generateKeyPair(),
+        crypto_1.X25519.generateKeyPair(),
+        crypto_1.X25519.generateKeyPair(),
+        (0, crypto_1.randomBytesAsync)(ADV_SECRET_BYTES),
+        (0, crypto_1.randomIntAsync)(1, 16381)
+    ]);
+    const signature = await (0, crypto_1.xeddsaSign)(identityKeyPair.privKey, (0, crypto_1.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/api/FakePairingDriver.js

@@ -4,7 +4,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FakePairingDriver = void 0;
 const fake_primary_device_1 = require("../protocol/auth/fake-primary-device");
 const pair_device_1 = require("../protocol/auth/pair-device");
-const crypto_1 = require("../transport/crypto");
 class FakePairingDriver {
     constructor(options, deps) {
         this.primary = null;
@@ -13,8 +12,7 @@ class FakePairingDriver {
     }
     async run() {
         this.primary = this.options.primary ?? (await (0, fake_primary_device_1.generateFakePrimaryDevice)());
-        const refs = await Promise.all(Array.from({ length: 6 }, () => (0, crypto_1.randomBytesAsync)(16)));
-        const pairDeviceIq = (0, pair_device_1.buildPairDeviceIq)({ refs });
+        const pairDeviceIq = (0, pair_device_1.buildPairDeviceIq)({ refs: await (0, pair_device_1.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/api/FakeServerSession.d.ts

@@ -1,7 +1,8 @@
 /** Per-session isolated server state: registries, prekeys, app-state, IQ routing, capture. */
 import type { BuildAbPropsResultInput } from '../protocol/iq/abprops';
-import { type WaFakeIqMatcher, type WaFakeIqResponder, WaFakeIqRouter } from '../protocol/iq/router';
+import { type WaFakeIqContext, type WaFakeIqMatcher, type WaFakeIqResponder, WaFakeIqRouter } from '../protocol/iq/router';
 import type { ClientPreKeyBundle } from '../protocol/signal/prekey-upload';
+import { FakeCompanionHostState } from '../state/fake-companion-host';
 import { type BinaryNode } from '../transport/codec';
 import { AppStateSyncManager } from './AppStateSyncManager';
 import { PreKeyDispenser } from './PreKeyDispenser';
@@ -30,6 +31,29 @@ export interface FakeServerSessionHost {
         readonly host: string;
         readonly port: number;
     };
+    /**
+     * Completes a pairing offer against the companion connection that owns
+     * `ref`: relays the primary-signed identity as `pair-success` and reports
+     * back what the companion advertised. Resolves `null` when no live
+     * connection holds that ref. Lives on the host because pairing spans two
+     * connections while a session owns neither.
+     */
+    completeCompanionPairing(input: CompleteCompanionPairingInput): Promise<CompletedCompanionPairing | null>;
+    /**
+     * Routes one link-code stage to the other client in the handshake, or
+     * resolves `null` when the stanza is not a stage this server relays.
+     */
+    relayLinkCodeStage(iq: BinaryNode, context: WaFakeIqContext | undefined): Promise<BinaryNode | null>;
+}
+export interface CompleteCompanionPairingInput {
+    readonly ref: string;
+    readonly deviceJid: string;
+    readonly deviceIdentityBytes: Uint8Array;
+}
+export interface CompletedCompanionPairing {
+    /** Companion `DeviceProps` from its registration payload, echoed to the primary. */
+    readonly companionPropsBytes: Uint8Array | null;
+    readonly platform: string;
 }
 /**
  * One isolated logical device's worth of server state. Every `WaClient`
@@ -43,6 +67,7 @@ export declare class FakeServerSession {
     readonly registries: ServerRegistries;
     readonly preKeyDispenser: PreKeyDispenser;
     readonly appStateSync: AppStateSyncManager;
+    readonly companionHost: FakeCompanionHostState;
     readonly iqRouter: WaFakeIqRouter;
     private readonly capturedStanzas;
     private readonly pendingIqExpectations;
@@ -53,7 +78,7 @@ export declare class FakeServerSession {
         readonly defaultIqHandlers: boolean;
     });
     registerIqHandler(matcher: WaFakeIqMatcher, respond: WaFakeIqResponder, label?: string): () => void;
-    routeIq(iq: BinaryNode): Promise<BinaryNode | null>;
+    routeIq(iq: BinaryNode, context?: WaFakeIqContext): Promise<BinaryNode | null>;
     handleCapturedStanza(node: BinaryNode): void;
     subscribeInboundMessages(listener: (node: BinaryNode) => void): () => void;
     onCapturedStanza(listener: (node: BinaryNode) => void): () => void;
@@ -61,6 +86,14 @@ export declare class FakeServerSession {
     expectIq(matcher: WaFakeIqMatcher, options?: ExpectIqOptions): Promise<BinaryNode>;
     expectStanza(matcher: StanzaMatcher, options?: ExpectStanzaOptions): Promise<BinaryNode>;
     private buildIqHandlerDeps;
+    /**
+     * 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.
+     */
+    private linkCompanionDevice;
+    private revokeCompanionDevices;
 }
 export declare function matchesIq(iq: BinaryNode, matcher: WaFakeIqMatcher): boolean;
 export declare function matchesStanza(node: BinaryNode, matcher: StanzaMatcher): boolean;

package/dist/api/FakeServerSession.js

@@ -5,10 +5,12 @@ exports.FakeServerSession = void 0;
 exports.matchesIq = matchesIq;
 exports.matchesStanza = matchesStanza;
 const router_1 = require("../protocol/iq/router");
+const fake_companion_host_1 = require("../state/fake-companion-host");
 const AppStateSyncManager_1 = require("./AppStateSyncManager");
 const iq_handlers_1 = require("./iq-handlers");
 const PreKeyDispenser_1 = require("./PreKeyDispenser");
 const ServerRegistries_1 = require("./ServerRegistries");
+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,
@@ -21,6 +23,7 @@ class FakeServerSession {
         this.registries = new ServerRegistries_1.ServerRegistries();
         this.preKeyDispenser = new PreKeyDispenser_1.PreKeyDispenser();
         this.appStateSync = new AppStateSyncManager_1.AppStateSyncManager();
+        this.companionHost = new fake_companion_host_1.FakeCompanionHostState();
         this.iqRouter = new router_1.WaFakeIqRouter();
         this.capturedStanzas = [];
         this.pendingIqExpectations = new Set();
@@ -36,8 +39,8 @@ 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);
@@ -153,6 +156,7 @@ class FakeServerSession {
         const reg = this.registries;
         const preKey = this.preKeyDispenser;
         const appState = this.appStateSync;
+        const companionHost = this.companionHost;
         return {
             get peerRegistry() {
                 return reg.peerRegistry;
@@ -220,9 +224,67 @@ 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: (0, fake_companion_host_1.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, (0, ServerRegistries_1.toDeviceIdPart)(deviceJid));
+            }
+        }
+        return removed;
+    }
 }
 exports.FakeServerSession = FakeServerSession;
 function matchesIq(iq, matcher) {

package/dist/api/FakeWaServer.d.ts

@@ -8,8 +8,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 +50,19 @@ 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;
+    };
 }
 export interface FakeSessionKeyInfo {
     readonly clientPayload: ParsedClientPayload;
@@ -80,6 +95,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 +110,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 +168,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 +219,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 +233,7 @@ export declare class FakeWaServer {
      */
     onPipeline(listener: FakeWaServerPipelineListener): () => void;
     listen(): Promise<void>;
+    private rollbackFailedListen;
     stop(): Promise<void>;
     private handleConnection;
     /**
@@ -204,6 +243,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;