@zapo-js/fake-server 1.0.0 → 1.2.0

package/README.md

@@ -1,6 +1,18 @@
 # @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
+
+```bash
+npm i -D @zapo-js/fake-server zapo-js
+```
+
+`zapo-js` is a peer dependency - the fake server reuses the core's binary codec, crypto, and protos. Everything below works from any project; nothing requires this monorepo.
 
 ## Quick start
 
@@ -29,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
@@ -40,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)
@@ -50,7 +65,7 @@ src/
 │   ├── fake-media-store.ts  # In-memory media blob store
 │   └── fake-app-state-collection.ts  # App-state patch/snapshot provider
 ├── transport/               # Re-exports from zapo-js (codec, crypto, protos)
-└── __tests__/               # Cross-check test suite (147 tests)
+└── __tests__/               # Cross-check test suite
     └── helpers/             # Shared test utilities (zapo-client factory)
 
 bench/
@@ -63,14 +78,63 @@ bench/
 
 ### FakeWaServer
 
-Central facade. Manages the WS listener, noise handshake, IQ router, and all state registries:
+Central facade. Manages the WS listener, noise handshake, IQ router, and all state registries.
+
+Constructor options (`FakeWaServer.start({...})` / `new FakeWaServer({...})`):
+
+```ts
+const server = await FakeWaServer.start({
+    host: '127.0.0.1', // default
+    port: 5222, // default: random free port
+    path: '/ws/chat', // default
+    successNodeAttributes: {
+        // stamped on every post-handshake <success/>
+        lid: '5511999@lid',
+        displayName: 'Fake Display'
+    },
+    defaultIqHandlers: false // start with an empty IQ router (default: true)
+})
+```
 
 - **Peer registry** (`peerRegistry`): maps device JIDs → `FakePeer` instances. The global `usync` + `prekey-fetch` IQ handlers consult this.
+- **Sessions**: state is grouped per session (see below). A single-client server uses one default session, and the `server.registries` / `server.expectIq(...)` / `server.preKeyDispenser` surface delegates straight to it.
 - **Group registry** (`groupRegistry`): maps group JIDs → group metadata + participants. The `w:g2` handler serves it.
-- **IQ router** (`WaFakeIqRouter`): first-match-wins stanza dispatcher with `{ xmlns, type, childTag }` matchers. ~20 global handlers registered in the constructor cover every IQ the lib emits during normal operation.
+- **IQ router** (`WaFakeIqRouter`): first-match-wins stanza dispatcher with `{ xmlns, type, childTag }` matchers. ~27 global handlers registered in the constructor cover every IQ the lib emits during normal operation (disable them with `defaultIqHandlers: false`). `registerIqHandler(matcher, respond)` registers at high priority and shadows the defaults; a responder that returns `null` falls through to the next matching handler, so you can observe an IQ (capture, assert) and still let the default answer it.
 - **Prekey dispenser**: hands out unique one-time prekeys from the lib's upload to FakePeers. Resets on each forced refill (`triggerPreKeyUpload({ force: true })`).
 - **Listener fan-outs**: `onOutboundGroupOp`, `onOutboundPrivacySet`, `onOutboundBlocklistChange`, `onOutboundProfilePictureSet`, `onOutboundStatusSet`, `onLogout`, `onOutboundPrivacyTokenIssue`, `onOutboundDirtyBitsClear`.
 
+### Sessions (multiple clients, one server)
+
+By default every connection shares one session, so a single `WaClient` sees the whole `FakeWaServer` surface. To run **several clients against one server without them sharing any state**, pass a `sessionKey` resolver: each authenticated connection is bound to an isolated session keyed by the returned id. Sessions never share peers, groups, prekeys, app-state, or captured stanzas.
+
+```ts
+const server = await FakeWaServer.start({
+    // Key each connection by its login username; pre-login (registration)
+    // connections fall under one transient bucket.
+    sessionKey: ({ clientPayload }) =>
+        clientPayload.kind === 'login' ? String(clientPayload.username) : 'pending'
+})
+
+// After a client authenticates, reach its isolated state through the pipeline:
+const session = server.sessionFor(pipeline) // FakeServerSession
+await session.expectIq({ xmlns: 'passive', type: 'set' })
+session.registries.peerRegistry // this client's peers only
+session.preKeyDispenser.capturedPreKeyBundleSnapshot() // this client's prekeys
+
+// Or address a session by id directly:
+const alice = server.session('5511111111111')
+
+// Peer creation routes to the connection's session automatically:
+const peer = await server.createFakePeer({ jid: peerJid }, pipeline)
+```
+
+Notes:
+
+- The resolver runs once per connection, right after authentication (so `clientPayload` is available). Connections that resolve to the same id reuse one session.
+- `server.registerIqHandler(...)` applies to every session (present and future); `session.registerIqHandler(...)` scopes to one session.
+- The media HTTPS store is process-global and shared across sessions; isolation covers peers/groups/prekeys/app-state/captures, not uploaded media blobs.
+- QR pairing writes to the connection's session too, so pair clients **sequentially** when keying registration connections into a shared bucket.
+
 ### FakePeer
 
 Simulated WhatsApp peer with real Signal Protocol crypto:
@@ -91,33 +155,97 @@ 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` set `<rotate>`                                                         | `signed-prekey-rotate`        | Ack                                     |
-| `encrypt` get `<key>`                                                            | `prekey-fetch`                | Serves peer bundles from registry       |
-| `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
+
+The fake server speaks the real wire protocol, so other WhatsApp Web libraries (Baileys forks, whatsmeow, ...) can connect to it too. The recipe:
+
+1. **Point the client's WebSocket URL at `server.url`** (the upgrade path is `/ws/chat`, same as production).
+2. **Trust the fake root CA.** The server signs its Noise cert chain with a per-instance random root; clients that verify the cert signature against WhatsApp's pinned production key must be told to trust `server.noiseRootCa.publicKey` instead (exposed via the CLI's `--json` as `noiseRootCa.publicKeyHex`). The chain carries a valid `notBefore`/`notAfter` window, so clients that enforce validity work out of the box.
+3. **Post-connect IQs are answered by default**: the `passive` set IQ and the `encrypt` get `<count>` prekey-count query, which Baileys-family and whatsmeow clients block on before reporting the connection as open.
+4. **Offline drain bulletin**: after every login the server sends `<ib><offline count="0"/></ib>`, which Baileys-family clients require before flushing their buffered events.
+5. **QR pairing**: in-process, use `server.runPairing(...)` with the client's `advSecretKey` + identity public key; from the standalone CLI, use `--pair <device-jid>` and paste the QR payload the client displays when prompted.
 
 ## Benchmarking
 
@@ -161,16 +289,35 @@ node --expose-gc --import tsx packages/fake-server/bench/messaging.bench.ts --cp
 
 ## CLI
 
+The package ships a `fake-wa-server` bin, so the standalone server works from any project (or no project at all):
+
+```bash
+# One-off via npx
+npx @zapo-js/fake-server --port 5222 --peer 5511888@s.whatsapp.net --log
+
+# Installed as a dev dependency
+npx fake-wa-server --port 5222 --peer 5511888@s.whatsapp.net --log
+
+# First-time QR pairing: prompts on stdin for the QR payload the client displays
+npx fake-wa-server --port 5222 --pair 5511999:1@s.whatsapp.net
+
+# Print connection info (url + noise root CA hex) as JSON, for scripting
+npx fake-wa-server --json
+```
+
+From inside this monorepo (runs the source, no build needed):
+
 ```bash
-# Standalone server for manual testing
 npm --workspace=@zapo-js/fake-server run cli -- --port 5222 --peer 5511888@s.whatsapp.net --log
 ```
 
+Run with `--help` for the full flag list.
+
 ## Test suite
 
 ```bash
 npm --workspace=@zapo-js/fake-server test
-# 147 tests, --test-concurrency=1
+# 164 tests, --test-concurrency=1
 ```
 
 Cross-check tests drive a real `WaClient` against the fake server and assert on both sides (lib emits correct events, peer decrypts correctly). Unit tests validate protocol builders/parsers in isolation.

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/FakePeer.js

@@ -550,7 +550,13 @@ class FakePeer {
     }
     nextId() {
         this.nextMessageCounter += 1;
-        return `${this.jid}-${Date.now()}-${this.nextMessageCounter}`;
+        // WA-style uppercase hex, no '@': strict binary decoders tokenize an
+        // id containing '@' as a JID and reject the stanza. The registration
+        // id keeps ids from colliding across peers created in the same ms.
+        const peerPart = this.keyBundle.registrationId.toString(16).padStart(4, '0');
+        const timePart = Date.now().toString(16);
+        const counterPart = this.nextMessageCounter.toString(16).padStart(4, '0');
+        return `3EB0${peerPart}${timePart}${counterPart}`.toUpperCase();
     }
 }
 exports.FakePeer = FakePeer;

package/dist/api/FakeServerSession.d.ts

@@ -0,0 +1,100 @@
+/** Per-session isolated server state: registries, prekeys, app-state, IQ routing, capture. */
+import type { BuildAbPropsResultInput } from '../protocol/iq/abprops';
+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';
+import { ServerRegistries } from './ServerRegistries';
+export interface ExpectIqOptions {
+    readonly timeoutMs?: number;
+}
+export interface ExpectStanzaOptions {
+    readonly timeoutMs?: number;
+}
+export interface StanzaMatcher {
+    readonly tag?: string;
+    readonly type?: string;
+    readonly xmlns?: string;
+    readonly from?: string;
+    readonly to?: string;
+    readonly childTag?: string;
+}
+/**
+ * Shared server-side dependencies a session needs but does not own. The media
+ * HTTPS server is process-global (one listener), so its address is injected
+ * rather than duplicated per session.
+ */
+export interface FakeServerSessionHost {
+    requireMediaHttpsInfo(): {
+        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`
+ * connected to a `FakeWaServer` is bound to exactly one session; peers,
+ * groups, privacy, prekeys, app-state, and captured stanzas never leak across
+ * sessions. A single-client server uses one default session, which is why the
+ * legacy `FakeWaServer` surface delegates straight through to it.
+ */
+export declare class FakeServerSession {
+    readonly id: string;
+    readonly registries: ServerRegistries;
+    readonly preKeyDispenser: PreKeyDispenser;
+    readonly appStateSync: AppStateSyncManager;
+    readonly companionHost: FakeCompanionHostState;
+    readonly iqRouter: WaFakeIqRouter;
+    private readonly capturedStanzas;
+    private readonly pendingIqExpectations;
+    private readonly pendingStanzaExpectations;
+    private readonly capturedStanzaListeners;
+    private readonly inboundStanzaListeners;
+    constructor(id: string, host: FakeServerSessionHost, options: {
+        readonly defaultIqHandlers: boolean;
+    });
+    registerIqHandler(matcher: WaFakeIqMatcher, respond: WaFakeIqResponder, label?: string): () => void;
+    routeIq(iq: BinaryNode, context?: WaFakeIqContext): Promise<BinaryNode | null>;
+    handleCapturedStanza(node: BinaryNode): void;
+    subscribeInboundMessages(listener: (node: BinaryNode) => void): () => void;
+    onCapturedStanza(listener: (node: BinaryNode) => void): () => void;
+    capturedStanzaSnapshot(): readonly BinaryNode[];
+    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;
+export type { ClientPreKeyBundle, BuildAbPropsResultInput };