@zapo-js/fake-server 1.0.0 → 1.2.0

package/dist/esm/api/ServerRegistries.js

@@ -186,16 +186,31 @@ export class ServerRegistries {
     }
     registerPeer(peer) {
         this.peerRegistry.set(peer.jid, peer);
-        const userJid = toUserJidPart(peer.jid);
-        const deviceId = toDeviceIdPart(peer.jid);
+        this.registerDeviceId(toUserJidPart(peer.jid), toDeviceIdPart(peer.jid));
+    }
+    /**
+     * Makes a device visible to `usync` without minting a full fake peer – used
+     * for the primary's own device set, whose companions are real clients with
+     * their own keys rather than server-side fakes.
+     */
+    registerDeviceId(userJid, deviceId) {
         const ids = this.deviceIdsByUser.get(userJid);
-        if (ids) {
+        if (!ids) {
+            this.deviceIdsByUser.set(userJid, [deviceId]);
+            return;
+        }
+        if (!ids.includes(deviceId)) {
             ids.push(deviceId);
             ids.sort((a, b) => a - b);
         }
-        else {
-            this.deviceIdsByUser.set(userJid, [deviceId]);
+    }
+    unregisterDeviceId(userJid, deviceId) {
+        const ids = this.deviceIdsByUser.get(userJid);
+        if (!ids) {
+            return;
         }
+        const next = ids.filter((id) => id !== deviceId);
+        this.deviceIdsByUser.set(userJid, next);
     }
     lookupDeviceIdsForUser(userJid) {
         return this.deviceIdsByUser.get(userJid) ?? [];

package/dist/esm/api/iq-handlers.js

@@ -2,6 +2,7 @@
 import { buildAbPropsResult } from '../protocol/iq/abprops.js';
 import { buildAppStateSyncFullResult, buildAppStateSyncResult, parseAppStateSyncRequest } from '../protocol/iq/appstate-sync.js';
 import { buildBusinessProfileResult, parseGetBusinessProfileIq } from '../protocol/iq/business.js';
+import { parseKeyIndexListPublish, parsePairDeviceUpload, parseRemoveCompanionDevice } from '../protocol/iq/companion-host.js';
 import { parseClearDirtyBitsIq } from '../protocol/iq/dirty-bits.js';
 import { buildGroupMetadataNode, buildGroupParticipantChangeResult, parseCreateGroupIq, parseGroupParticipantChangeIq, parseLeaveGroupIq, parseSetDescriptionIq, parseSetSubjectIq } from '../protocol/iq/group-ops.js';
 import { buildNewsletterMyAddonsResult } from '../protocol/iq/newsletter.js';
@@ -73,6 +74,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`;
+}
 export function registerDefaultIqHandlers(router, deps) {
     router.register({
         label: 'prekey-upload',
@@ -93,6 +116,29 @@ export function registerDefaultIqHandlers(router, deps) {
         matcher: { xmlns: 'encrypt', type: 'get', childTag: 'digest' },
         respond: (iq) => buildIqError(iq, { code: 404, text: 'item-not-found' })
     });
+    // Baileys-family and whatsmeow clients block on this query before
+    // reporting the connection as open; zapo-js uses <digest> instead.
+    router.register({
+        label: 'prekey-count',
+        matcher: { xmlns: 'encrypt', type: 'get', childTag: 'count' },
+        respond: (iq) => {
+            const result = buildIqResult(iq);
+            return {
+                ...result,
+                content: [
+                    {
+                        tag: 'count',
+                        attrs: { value: String(deps.countServerPreKeys()) }
+                    }
+                ]
+            };
+        }
+    });
+    router.register({
+        label: 'passive-mode',
+        matcher: { xmlns: 'passive', type: 'set' },
+        respond: (iq) => buildIqResult(iq)
+    });
     router.register({
         label: 'media-conn',
         matcher: { xmlns: 'w:m', type: 'set', childTag: 'media_conn' },
@@ -221,10 +267,82 @@ export function registerDefaultIqHandlers(router, deps) {
         matcher: { xmlns: 'encrypt', type: 'set', childTag: 'rotate' },
         respond: (iq) => 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 = parsePairDeviceUpload(iq);
+            if (!upload) {
+                return 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 buildIqError(iq, { code: 403, text: 'not-authorized' });
+            }
+            const linked = await deps.linkCompanionDevice(upload);
+            if (!linked) {
+                return 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 buildIqResult(iq, { content });
+        }
+    });
+    router.register({
+        label: 'companion-key-index-list',
+        matcher: { xmlns: 'md', type: 'set', childTag: 'key-index-list' },
+        respond: (iq, context) => {
+            const published = parseKeyIndexListPublish(iq);
+            if (!published) {
+                return buildIqError(iq, { code: 400, text: 'invalid-key-index-list' });
+            }
+            if (!isSessionOwnerConnection(context, deps)) {
+                return buildIqError(iq, { code: 403, text: 'not-authorized' });
+            }
+            deps.recordKeyIndexList(published.keyIndexListBytes, published.timestampSeconds);
+            return buildIqResult(iq);
+        }
+    });
     router.register({
         label: 'remove-companion-device',
         matcher: { xmlns: 'md', type: 'set', childTag: 'remove-companion-device' },
-        respond: (iq) => {
+        respond: (iq, context) => {
+            const removal = 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 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 buildIqResult(iq);
         }

package/dist/esm/bin.js

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
 /** Standalone CLI for `@zapo-js/fake-server`. */
+import { createInterface } from 'node:readline';
 import { FakeWaServer } from './api/FakeWaServer.js';
+import { parsePairingQrString } from './protocol/auth/pair-device.js';
+import { bytesToHex, toError } from './transport/util.js';
 function parseArgs(argv) {
     let host = '127.0.0.1';
     let port = 0;
     let path = '/ws/chat';
     const peerJids = [];
     const groupSpecs = [];
+    let pairJid = null;
     let log = false;
     let quiet = false;
     let json = false;
@@ -44,6 +48,9 @@ function parseArgs(argv) {
             case '--group':
                 groupSpecs.push(next());
                 break;
+            case '--pair':
+                pairJid = next();
+                break;
             case '--log':
                 log = true;
                 break;
@@ -57,7 +64,7 @@ function parseArgs(argv) {
                 throw new Error(`unknown flag: ${arg}`);
         }
     }
-    return { host, port, path, peerJids, groupSpecs, log, quiet, json, help };
+    return { host, port, path, peerJids, groupSpecs, pairJid, log, quiet, json, help };
 }
 function printHelp() {
     process.stdout.write(`@zapo-js/fake-server – standalone fake WhatsApp Web server
@@ -73,6 +80,12 @@ FLAGS
   --group <spec>      Pre-create a fake group; spec format
                       <group-jid>=<peer-jid>,<peer-jid>,...
                       All peers must already be passed via --peer.
+  --pair <jid>        Drive QR pairing for unregistered clients: the server
+                      sends pair-device refs, then prompts on stdin for the
+                      QR payload the client displays
+                      (ref,noisePubB64,identityPubB64,advSecretB64,platform)
+                      and answers pair-success assigning <jid> as the device
+                      jid. Without this flag the CLI is login-only.
   --log               Print every captured inbound stanza
   --quiet             Suppress the startup info banner
   --json              Print connection info as JSON
@@ -103,7 +116,7 @@ async function main() {
         args = parseArgs(process.argv.slice(2));
     }
     catch (error) {
-        process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.stderr.write(`error: ${toError(error).message}\n`);
         process.stderr.write('run with --help to see usage.\n');
         process.exit(2);
     }
@@ -125,11 +138,39 @@ async function main() {
         port: args.port,
         path: args.path
     });
+    if (args.pairJid !== null) {
+        const pairJid = args.pairJid;
+        let pairingStarted = false;
+        server.onAuthenticatedPipeline(async (pipeline) => {
+            if (pairingStarted)
+                return;
+            if (pipeline.clientPayload?.kind !== 'registration')
+                return;
+            pairingStarted = true;
+            try {
+                await server.runPairing(pipeline, { deviceJid: pairJid }, async () => {
+                    const qr = await readStdinLine('[fake-server] paste the QR payload displayed by the client and press Enter:\n');
+                    const parsed = parsePairingQrString(qr.trim());
+                    return {
+                        advSecretKey: parsed.advSecretKey,
+                        identityPublicKey: parsed.identityPublicKey
+                    };
+                });
+                process.stdout.write(`[fake-server] pair-success sent for ${pairJid}; the client will now reconnect and log in\n`);
+            }
+            catch (error) {
+                pairingStarted = false;
+                process.stderr.write(`pairing failed: ${toError(error).message}\n`);
+            }
+        });
+    }
     let setupComplete = false;
     const setupPromise = new Promise((resolve, reject) => {
         server.onAuthenticatedPipeline(async (pipeline) => {
             if (setupComplete)
                 return;
+            if (pipeline.clientPayload?.kind !== 'login')
+                return;
             setupComplete = true;
             try {
                 const peers = new Map();
@@ -155,7 +196,7 @@ async function main() {
                 resolve();
             }
             catch (error) {
-                reject(error instanceof Error ? error : new Error(String(error)));
+                reject(toError(error));
             }
         });
     });
@@ -164,12 +205,11 @@ async function main() {
         process.exitCode = 1;
     });
     if (args.log) {
-        server.onPipeline((pipeline) => {
-            pipeline.setEvents({
-                onStanza: (node) => {
-                    process.stdout.write(`[wire] ${node.tag}${node.attrs.id ? ` id=${node.attrs.id}` : ''}${node.attrs.type ? ` type=${node.attrs.type}` : ''}\n`);
-                }
-            });
+        // onCapturedStanza taps the server's own capture stream; overriding
+        // pipeline.setEvents here would replace the server's handlers and
+        // silently break --peer setup and stanza capture.
+        server.onCapturedStanza((node) => {
+            process.stdout.write(`[wire] ${node.tag}${node.attrs.id ? ` id=${node.attrs.id}` : ''}${node.attrs.type ? ` type=${node.attrs.type}` : ''}\n`);
         });
     }
     if (!args.quiet) {
@@ -185,7 +225,8 @@ async function main() {
                     publicKeyHex: bytesToHex(noiseRoot.publicKey)
                 },
                 peers: args.peerJids,
-                groups: parsedGroups
+                groups: parsedGroups,
+                pair: args.pairJid
             }, null, 2) + '\n');
         }
         else {
@@ -201,6 +242,7 @@ async function main() {
                 `│ noise root ca  serial=${noiseRoot.serial} pub=${bytesToHex(noiseRoot.publicKey).slice(0, 32)}…`,
                 `│ peers          ${args.peerJids.length === 0 ? '(none)' : args.peerJids.join(', ')}`,
                 `│ groups         ${parsedGroups.length === 0 ? '(none)' : parsedGroups.map((g) => g.groupJid).join(', ')}`,
+                `│ pair mode      ${args.pairJid ?? '(off – login only)'}`,
                 '├─────────────────────────────────────────────────────────────',
                 '│ Wire your WaClient with:',
                 '│   chatSocketUrls: [server.url]',
@@ -224,7 +266,7 @@ async function main() {
             process.exit(0);
         }
         catch (error) {
-            process.stderr.write(`error during shutdown: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.stderr.write(`error during shutdown: ${toError(error).message}\n`);
             process.exit(1);
         }
     };
@@ -232,15 +274,21 @@ async function main() {
     process.on('SIGTERM', () => void shutdown('SIGTERM'));
     await new Promise(() => undefined);
 }
-function bytesToHex(bytes) {
-    let out = '';
-    for (let index = 0; index < bytes.byteLength; index += 1) {
-        const value = bytes[index];
-        out += value < 16 ? `0${value.toString(16)}` : value.toString(16);
-    }
-    return out;
+function readStdinLine(prompt) {
+    process.stdout.write(prompt);
+    return new Promise((resolve, reject) => {
+        const rl = createInterface({ input: process.stdin });
+        // resolve before close(): rl.close() emits 'close' synchronously,
+        // which would otherwise reject the still-pending promise first.
+        rl.once('line', (line) => {
+            resolve(line);
+            rl.close();
+        });
+        rl.once('close', () => reject(new Error('stdin closed before a QR payload was provided')));
+    });
 }
 main().catch((error) => {
-    process.stderr.write(`fatal: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+    const normalized = toError(error);
+    process.stderr.write(`fatal: ${normalized.stack ?? normalized.message}\n`);
     process.exit(1);
 });

package/dist/esm/index.js

@@ -1,8 +1,16 @@
+export { createFakeMobilePrimary, seedFakeMobilePrimary } from './api/FakeMobilePrimary.js';
 export { FakePairingDriver } from './api/FakePairingDriver.js';
 export { FakePeer } from './api/FakePeer.js';
-export { FakeWaServer } from './api/FakeWaServer.js';
+export { FakeServerSession, FakeWaServer } from './api/FakeWaServer.js';
 export { IqExpectation, Scenario } from './api/Scenario.js';
 export { WaFakeConnection } from './infra/WaFakeConnection.js';
+export { WaFakeTcpServer } from './infra/WaFakeTcpServer.js';
+export { createTcpSocketAdapter, createWebSocketAdapter } from './infra/socket-adapters.js';
+export { ClientPayloadValidationError, parseClientPayload } from './protocol/auth/client-payload-validate.js';
+export { parseKeyIndexListPublish, parsePairDeviceUpload, parseRemoveCompanionDevice } from './protocol/iq/companion-host.js';
+export { buildCompanionHelloResultContent, buildLinkCodeNotification, parseLinkCodeStanza } from './protocol/iq/link-code.js';
+export { buildAccountSyncDevicesNotification, buildAccountTakeoverNotice, buildRegistrationCodeNotification } from './protocol/push/mobile-notification.js';
+export { FakeCompanionHostState, readCompanionKeyIndex } from './state/fake-companion-host.js';
 export { buildAppStateSyncFullResult, buildAppStateSyncResult, buildServerSyncNotification, parseAppStateSyncRequest } from './protocol/iq/appstate-sync.js';
 export { buildIqError, buildIqResult } from './protocol/iq/router.js';
 export { buildCall, buildFailure } from './protocol/push/call-failure.js';

package/dist/esm/infra/WaFakeConnection.js

@@ -4,7 +4,14 @@ export class WaFakeConnection {
         this.currentState = 'open';
         this.id = id;
         this.socket = socket;
-        this.bindSocketEvents();
+        this.socket.listen({
+            onFrame: (frame) => this.handlers.onFrame?.(frame),
+            onClose: (info) => {
+                this.currentState = 'closed';
+                this.handlers.onClose?.(info);
+            },
+            onError: (error) => this.handlers.onError?.(error)
+        });
     }
     get state() {
         return this.currentState;
@@ -25,25 +32,4 @@ export class WaFakeConnection {
         this.currentState = 'closing';
         this.socket.close(code, reason);
     }
-    bindSocketEvents() {
-        this.socket.on('message', (data, isBinary) => {
-            if (!isBinary) {
-                this.handlers.onError?.(new Error('received unexpected text frame'));
-                return;
-            }
-            const frame = data instanceof Uint8Array
-                ? data
-                : Array.isArray(data)
-                    ? new Uint8Array(Buffer.concat(data))
-                    : new Uint8Array(data);
-            this.handlers.onFrame?.(frame);
-        });
-        this.socket.on('close', (code, reasonBuf) => {
-            this.currentState = 'closed';
-            this.handlers.onClose?.({ code, reason: reasonBuf.toString('utf8') });
-        });
-        this.socket.on('error', (error) => {
-            this.handlers.onError?.(error);
-        });
-    }
 }

package/dist/esm/infra/WaFakeConnectionPipeline.js

@@ -10,16 +10,20 @@ import { WaFakeNoiseHandshake } from './WaFakeNoiseHandshake.js';
 import { WaFakeTransport } from './WaFakeTransport.js';
 const NOISE_XX_NAME = new TextEncoder().encode('Noise_XX_25519_AESGCM_SHA256\0\0\0\0');
 const NOISE_IK_NAME = new TextEncoder().encode('Noise_IK_25519_AESGCM_SHA256\0\0\0\0');
-const PROLOGUE = new Uint8Array([0x57, 0x41, 0x06, 0x03]);
+const PROLOGUE_MAGIC_W = 0x57;
+const PROLOGUE_MAGIC_A = 0x41;
+const DEFAULT_PROLOGUE = new Uint8Array([PROLOGUE_MAGIC_W, PROLOGUE_MAGIC_A, 0x06, 0x03]);
 export class WaFakeConnectionPipeline {
     constructor(config) {
         this.events = {};
         this.state = { kind: 'awaiting_prologue' };
         this.chain = Promise.resolve();
+        this.authenticatedPayload = null;
+        this.clientPrologue = DEFAULT_PROLOGUE;
         this.config = config;
         this.frameSocket = new WaFakeFrameSocket(config.connection);
         this.frameSocket.setHandlers({
-            onPrologue: () => this.onPrologue(),
+            onPrologue: (prologue) => this.onPrologue(prologue),
             onFrame: (frame) => this.scheduleFrame(frame),
             onClose: (info) => {
                 this.state = { kind: 'closed' };
@@ -34,6 +38,10 @@ export class WaFakeConnectionPipeline {
     isAuthenticated() {
         return this.state.kind === 'authenticated';
     }
+    /** Parsed ClientPayload of the authenticated connection; null before auth. */
+    get clientPayload() {
+        return this.authenticatedPayload;
+    }
     async sendStanza(node) {
         if (this.state.kind !== 'authenticated') {
             throw new Error(`cannot send stanza while pipeline is in state "${this.state.kind}"`);
@@ -43,11 +51,20 @@ export class WaFakeConnectionPipeline {
         const ciphertext = await this.state.transport.encryptFrame(stanza);
         this.frameSocket.sendFrame(ciphertext);
     }
-    onPrologue() {
+    onPrologue(prologue) {
         if (this.state.kind !== 'awaiting_prologue') {
             this.events.onError?.(new Error('received second prologue from client'));
             return;
         }
+        // Mix back the header the client actually sent instead of a fixed one:
+        // it is hashed into the handshake, and a client is free to advertise a
+        // protocol/dict version other than the web client's 6/3.
+        this.clientPrologue = new Uint8Array([
+            PROLOGUE_MAGIC_W,
+            PROLOGUE_MAGIC_A,
+            prologue.protocolVersion,
+            prologue.dictVersion
+        ]);
         this.state = { kind: 'awaiting_client_hello' };
     }
     scheduleFrame(frame) {
@@ -89,7 +106,7 @@ export class WaFakeConnectionPipeline {
     }
     async handleXxClientHello(clientEphemeralPub) {
         const handshake = new WaFakeNoiseHandshake();
-        handshake.start(NOISE_XX_NAME, PROLOGUE);
+        handshake.start(NOISE_XX_NAME, this.clientPrologue);
         handshake.authenticate(clientEphemeralPub);
         const serverEphemeral = await X25519.generateKeyPair();
         handshake.authenticate(serverEphemeral.pubKey);
@@ -125,7 +142,7 @@ export class WaFakeConnectionPipeline {
         const encryptedClientStatic = clientHello.static;
         const encryptedClientPayload = clientHello.payload;
         const handshake = new WaFakeNoiseHandshake();
-        handshake.start(NOISE_IK_NAME, PROLOGUE);
+        handshake.start(NOISE_IK_NAME, this.clientPrologue);
         handshake.authenticate(this.config.serverStaticKeyPair.pubKey);
         handshake.authenticate(clientEphemeralPub);
         handshake.mixIntoKey(await X25519.scalarMult(this.config.serverStaticKeyPair.privKey, clientEphemeralPub));
@@ -153,14 +170,7 @@ export class WaFakeConnectionPipeline {
             }
         }).finish();
         this.frameSocket.sendFrame(serverHello);
-        const keys = handshake.finish();
-        const transport = new WaFakeTransport({
-            recvKey: keys.recvKey,
-            sendKey: keys.sendKey
-        });
-        this.state = { kind: 'authenticated', transport };
-        await this.sendStanza(buildSuccessNode(this.config.successNodeAttributes));
-        this.events.onAuthenticated?.({ clientPayload, clientStaticKey });
+        await this.completeAuthentication(handshake, clientPayload, clientStaticKey);
     }
     async handleClientFinish(frame, handshake, serverEphemeralKeyPair) {
         const parsed = proto.HandshakeMessage.decode(frame);
@@ -172,13 +182,27 @@ export class WaFakeConnectionPipeline {
         handshake.mixIntoKey(await X25519.scalarMult(serverEphemeralKeyPair.privKey, clientStaticKey));
         const clientPayloadBytes = handshake.decrypt(clientFinish.payload);
         const clientPayload = parseClientPayload(clientPayloadBytes);
+        await this.completeAuthentication(handshake, clientPayload, clientStaticKey);
+    }
+    async completeAuthentication(handshake, clientPayload, clientStaticKey) {
         const keys = handshake.finish();
         const transport = new WaFakeTransport({
             recvKey: keys.recvKey,
             sendKey: keys.sendKey
         });
         this.state = { kind: 'authenticated', transport };
+        this.authenticatedPayload = clientPayload;
         await this.sendStanza(buildSuccessNode(this.config.successNodeAttributes));
+        if (clientPayload.kind === 'login') {
+            // Real WA drains offline messages after login and closes the
+            // drain with this bulletin. Baileys-family clients buffer their
+            // events until it arrives, so send it eagerly with count=0.
+            await this.sendStanza({
+                tag: 'ib',
+                attrs: { from: 's.whatsapp.net' },
+                content: [{ tag: 'offline', attrs: { count: '0' } }]
+            });
+        }
         this.events.onAuthenticated?.({ clientPayload, clientStaticKey });
     }
     async handleAuthenticatedFrame(frame, transport) {
@@ -186,7 +210,7 @@ export class WaFakeConnectionPipeline {
         const node = await decodeBinaryNodeStanza(stanzaBytes);
         this.events.onStanza?.(node);
         if (node.tag === 'iq') {
-            const response = await this.config.iqRouter.route(node);
+            const response = await this.config.routeIq(node);
             if (response !== null) {
                 await this.sendStanza(response);
             }

package/dist/esm/infra/WaFakeTcpServer.js

@@ -0,0 +1,69 @@
+import { createServer } from 'node:net';
+import { createTcpSocketAdapter } from './socket-adapters.js';
+import { WaFakeConnection } from './WaFakeConnection.js';
+/**
+ * Raw-TCP listener for the WhatsApp Mobile transport. The mobile client dials
+ * `tcp://host:port` instead of upgrading to a WebSocket, but speaks the exact
+ * same prologue + length-prefixed frames on top, so every layer above the
+ * carrier is shared with {@link WaFakeWsServer}.
+ */
+export class WaFakeTcpServer {
+    constructor(options = {}) {
+        this.server = null;
+        this.connectionListener = null;
+        this.sockets = new Set();
+        this.nextConnectionId = 0;
+        this.options = {
+            host: options.host ?? '127.0.0.1',
+            port: options.port ?? 0
+        };
+    }
+    onConnection(listener) {
+        this.connectionListener = listener;
+    }
+    async listen() {
+        if (this.server) {
+            throw new Error('fake tcp server is already listening');
+        }
+        const server = createServer((socket) => {
+            this.sockets.add(socket);
+            socket.on('close', () => this.sockets.delete(socket));
+            const id = `t${this.nextConnectionId++}`;
+            this.connectionListener?.(new WaFakeConnection(id, createTcpSocketAdapter(socket)));
+        });
+        await new Promise((resolve, reject) => {
+            const onError = (error) => {
+                server.off('listening', onListening);
+                reject(error);
+            };
+            const onListening = () => {
+                server.off('error', onError);
+                resolve();
+            };
+            server.once('error', onError);
+            server.once('listening', onListening);
+            server.listen(this.options.port, this.options.host);
+        });
+        this.server = server;
+        const address = server.address();
+        return {
+            host: address.address,
+            port: address.port,
+            url: `tcp://${address.address}:${address.port}`
+        };
+    }
+    async close() {
+        const server = this.server;
+        if (!server) {
+            return;
+        }
+        for (const socket of this.sockets) {
+            socket.destroy();
+        }
+        this.sockets.clear();
+        await new Promise((resolve, reject) => {
+            server.close((error) => (error ? reject(error) : resolve()));
+        });
+        this.server = null;
+    }
+}

package/dist/esm/infra/WaFakeWsServer.js

@@ -1,5 +1,6 @@
 import { createServer } from 'node:http';
 import { WebSocketServer } from 'ws';
+import { createWebSocketAdapter } from './socket-adapters.js';
 import { WaFakeConnection } from './WaFakeConnection.js';
 export class WaFakeWsServer {
     constructor(options = {}) {
@@ -49,7 +50,7 @@ export class WaFakeWsServer {
         const wsServer = new WebSocketServer({ server: httpServer, path: this.options.path });
         wsServer.on('connection', (socket) => {
             const id = `c${this.nextConnectionId++}`;
-            const connection = new WaFakeConnection(id, socket);
+            const connection = new WaFakeConnection(id, createWebSocketAdapter(socket));
             this.connectionListener?.(connection);
         });
         await new Promise((resolve, reject) => {