@zapo-js/fake-server 1.0.0 → 1.2.0

package/dist/esm/state/fake-companion-host.js

@@ -0,0 +1,158 @@
+/** Per-session account state for a mobile primary hosting companion devices. */
+import { proto } from '../transport/protos.js';
+export class FakeCompanionHostState {
+    constructor() {
+        this.primaryIdentity = null;
+        this.companions = new Map();
+        this.reservedDeviceIds = new Set();
+        this.keyIndexList = null;
+        this.linkListeners = new Set();
+        this.revokeListeners = new Set();
+    }
+    /** The mobile primary bound to this session, or `null` for a web session. */
+    get primary() {
+        return this.primaryIdentity;
+    }
+    /**
+     * Records the primary at login. The first account to bind owns the session
+     * for good: a later login under a different number would otherwise mint
+     * device jids for one account while the companions of another are still
+     * tracked here.
+     */
+    bindPrimary(identity) {
+        if (this.primaryIdentity) {
+            return;
+        }
+        this.primaryIdentity = identity;
+    }
+    /** Companions linked from this account, in link order. */
+    linkedCompanions() {
+        return [...this.companions.values()];
+    }
+    /** Last key-index list the primary published, or `null` if it never did. */
+    publishedKeyIndexList() {
+        return this.keyIndexList;
+    }
+    /**
+     * Reserves the next free device slot. The primary owns device 0, so
+     * companions start at 1 and a revoked slot is reused only once no live
+     * companion holds it. The slot is held from here until the link is either
+     * recorded or released, because a link spans an await and two overlapping
+     * pairings would otherwise be handed the same jid.
+     */
+    allocateDeviceId() {
+        const taken = new Set([0, ...this.reservedDeviceIds]);
+        for (const companion of this.companions.values()) {
+            taken.add(companion.deviceId);
+        }
+        let candidate = 1;
+        while (taken.has(candidate)) {
+            candidate += 1;
+        }
+        this.reservedDeviceIds.add(candidate);
+        return candidate;
+    }
+    /** Frees a slot whose link never completed. */
+    releaseDeviceId(deviceId) {
+        this.reservedDeviceIds.delete(deviceId);
+    }
+    recordCompanion(companion) {
+        this.reservedDeviceIds.delete(companion.deviceId);
+        this.companions.set(companion.deviceJid, companion);
+        for (const listener of this.linkListeners) {
+            try {
+                listener(companion);
+            }
+            catch (error) {
+                void error;
+            }
+        }
+    }
+    /**
+     * Drops companions and notifies listeners. Returns the jids actually
+     * removed, so a revoke of an untracked device is observable as a no-op.
+     */
+    removeCompanions(deviceJids) {
+        const removed = [];
+        for (const deviceJid of deviceJids) {
+            if (this.companions.delete(deviceJid)) {
+                removed.push(deviceJid);
+            }
+        }
+        if (removed.length > 0) {
+            for (const listener of this.revokeListeners) {
+                try {
+                    listener(removed);
+                }
+                catch (error) {
+                    void error;
+                }
+            }
+        }
+        return removed;
+    }
+    removeAllCompanions() {
+        return this.removeCompanions([...this.companions.keys()]);
+    }
+    recordKeyIndexList(bytes, timestampSeconds) {
+        const decoded = decodeKeyIndexList(bytes);
+        this.keyIndexList = {
+            bytes,
+            timestampSeconds,
+            validIndexes: decoded.validIndexes,
+            currentIndex: decoded.currentIndex
+        };
+    }
+    onCompanionLinked(listener) {
+        this.linkListeners.add(listener);
+        return () => {
+            this.linkListeners.delete(listener);
+        };
+    }
+    onCompanionsRevoked(listener) {
+        this.revokeListeners.add(listener);
+        return () => {
+            this.revokeListeners.delete(listener);
+        };
+    }
+}
+/**
+ * Reads the ADV key index out of the `ADVSignedDeviceIdentityHMAC` the primary
+ * uploaded. Returns 0 when the payload does not decode, which keeps a
+ * malformed upload observable in the recorded companion instead of throwing
+ * inside the IQ handler.
+ */
+export function readCompanionKeyIndex(deviceIdentityBytes) {
+    try {
+        const hmacWrapper = proto.ADVSignedDeviceIdentityHMAC.decode(deviceIdentityBytes);
+        if (!hmacWrapper.details) {
+            return 0;
+        }
+        const signed = proto.ADVSignedDeviceIdentity.decode(hmacWrapper.details);
+        if (!signed.details) {
+            return 0;
+        }
+        return proto.ADVDeviceIdentity.decode(signed.details).keyIndex ?? 0;
+    }
+    catch (error) {
+        void error;
+        return 0;
+    }
+}
+function decodeKeyIndexList(bytes) {
+    try {
+        const signed = proto.ADVSignedKeyIndexList.decode(bytes);
+        if (!signed.details) {
+            return { validIndexes: [], currentIndex: 0 };
+        }
+        const details = proto.ADVKeyIndexList.decode(signed.details);
+        return {
+            validIndexes: details.validIndexes ?? [],
+            currentIndex: details.currentIndex ?? 0
+        };
+    }
+    catch (error) {
+        void error;
+        return { validIndexes: [], currentIndex: 0 };
+    }
+}

package/dist/esm/transport/auth.js

@@ -0,0 +1,7 @@
+/**
+ * Layer 1 – credential/store type wrapper.
+ *
+ * Re-exports the auth and store types from zapo-js so the fixture layer can
+ * seed a registered session without importing zapo-js directly.
+ */
+export {};

package/dist/esm/transport/crypto.js

@@ -4,5 +4,5 @@
  * Re-exports bit-exact cryptographic primitives from zapo-js. No protocol
  * interpretation, so reusing them does not create a test-vs-impl tautology.
  */
-export { aesCbcDecrypt, aesCbcEncrypt, aesGcmDecrypt, aesGcmEncrypt, Ed25519, hkdf, hkdfSplit, hmacSha256Sign, hmacSha512Sign, prependVersion, randomBytesAsync, readVersionedContent, sha256, sha512, toRawPubKey, toSerializedPubKey, X25519, xeddsaSign, xeddsaVerify } from 'zapo-js/crypto';
+export { aesCbcDecrypt, aesCbcEncrypt, aesGcmDecrypt, aesGcmEncrypt, Ed25519, hkdf, hkdfSplit, hmacSha256Sign, hmacSha512Sign, prependVersion, randomBytesAsync, randomIntAsync, readVersionedContent, sha256, sha512, toRawPubKey, toSerializedPubKey, X25519, xeddsaSign, xeddsaVerify } from 'zapo-js/crypto';
 export { WaMediaCrypto } from 'zapo-js/media';

package/dist/esm/transport/util.js

@@ -4,5 +4,6 @@
  * Re-exports bit-exact byte helpers from zapo-js so Layer 2/3 of the fake
  * server can use them without importing zapo-js directly.
  */
-export { bytesToBase64, bytesToBase64UrlSafe, bytesToHex, decodeBase64Url } from 'zapo-js/util';
+export { bytesToBase64, bytesToBase64UrlSafe, bytesToHex, decodeBase64Url, toError } from 'zapo-js/util';
 export const TEXT_ENCODER = new TextEncoder();
+export const TEXT_DECODER = new TextDecoder();

package/dist/index.d.ts

@@ -1,14 +1,29 @@
+export { createFakeMobilePrimary, seedFakeMobilePrimary } from './api/FakeMobilePrimary';
+export type { FakeMobilePrimary, SeedFakeMobilePrimaryOptions } from './api/FakeMobilePrimary';
 export { FakePairingDriver } from './api/FakePairingDriver';
 export type { CompanionPairingMaterial, FakePairingDriverDeps, FakePairingDriverOptions } from './api/FakePairingDriver';
 export { FakePeer } from './api/FakePeer';
 export type { CreateFakePeerOptions, ExpectGroupMessageOptions, ExpectMessageOptions, ReceivedMessage, SendMessageOptions } from './api/FakePeer';
-export { FakeWaServer } from './api/FakeWaServer';
-export type { BinaryNode, ExpectIqOptions, ExpectStanzaOptions, FakeWaServerNoiseRootCa, FakeWaServerOptions, FakeWaServerPipelineListener, StanzaMatcher, WaFakeAuthenticatedInfo, WaFakeConnectionPipeline } from './api/FakeWaServer';
+export { FakeServerSession, FakeWaServer } from './api/FakeWaServer';
+export type { BinaryNode, ExpectIqOptions, ExpectStanzaOptions, FakeSessionKeyInfo, FakeWaServerNoiseRootCa, FakeWaServerOptions, FakeWaServerPipelineListener, StanzaMatcher, WaFakeAuthenticatedInfo, WaFakeConnectionPipeline } from './api/FakeWaServer';
 export { IqExpectation, Scenario } from './api/Scenario';
 export type { AuthenticatedPipelineListener, ScenarioServer } from './api/Scenario';
 export { WaFakeConnection } from './infra/WaFakeConnection';
-export type { WaFakeConnectionHandlers, WaFakeConnectionState } from './infra/WaFakeConnection';
-export type { WaFakeIqHandler, WaFakeIqMatcher, WaFakeIqResponder, WaFakeIqRouterEvents, WaFakeIqType } from './protocol/iq/router';
+export type { WaFakeConnectionHandlers, WaFakeConnectionState, WaFakeSocketEvents, WaFakeSocketLike } from './infra/WaFakeConnection';
+export { WaFakeTcpServer } from './infra/WaFakeTcpServer';
+export type { WaFakeTcpServerListenInfo, WaFakeTcpServerOptions } from './infra/WaFakeTcpServer';
+export { createTcpSocketAdapter, createWebSocketAdapter } from './infra/socket-adapters';
+export { ClientPayloadValidationError, parseClientPayload } from './protocol/auth/client-payload-validate';
+export type { ClientPayloadFlavor, LoginPayload, MobileLoginDetails, ParsedClientPayload, RegistrationPayload } from './protocol/auth/client-payload-validate';
+export type { WaFakeIqConnection, WaFakeIqContext, WaFakeIqHandler, WaFakeIqMatcher, WaFakeIqResponder, WaFakeIqRouterEvents, WaFakeIqType } from './protocol/iq/router';
+export { parseKeyIndexListPublish, parsePairDeviceUpload, parseRemoveCompanionDevice } from './protocol/iq/companion-host';
+export type { ParsedKeyIndexListPublish, ParsedPairDeviceUpload, ParsedRemoveCompanionDevice } from './protocol/iq/companion-host';
+export { buildCompanionHelloResultContent, buildLinkCodeNotification, parseLinkCodeStanza } from './protocol/iq/link-code';
+export type { BuildLinkCodeNotificationInput, LinkCodeStage, ParsedLinkCodeStanza } from './protocol/iq/link-code';
+export { buildAccountSyncDevicesNotification, buildAccountTakeoverNotice, buildRegistrationCodeNotification } from './protocol/push/mobile-notification';
+export type { BuildAccountSyncDevicesInput, BuildAccountTakeoverNoticeInput, BuildRegistrationCodeNotificationInput, FakeAccountDevice } from './protocol/push/mobile-notification';
+export { FakeCompanionHostState, readCompanionKeyIndex } from './state/fake-companion-host';
+export type { FakeLinkedCompanion, FakeMobilePrimaryIdentity, FakePublishedKeyIndexList } from './state/fake-companion-host';
 export { buildAppStateSyncFullResult, buildAppStateSyncResult, buildServerSyncNotification, parseAppStateSyncRequest } from './protocol/iq/appstate-sync';
 export type { BuildAppStateSyncFullResultInput, BuildAppStateSyncResultInput, BuildServerSyncNotificationInput, FakeAppStateCollectionName, FakeAppStateCollectionPayload } from './protocol/iq/appstate-sync';
 export { buildIqError, buildIqResult } from './protocol/iq/router';

package/dist/index.js

@@ -1,17 +1,45 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildStreamErrorXmlNotWellFormed = exports.buildStreamErrorReplaced = exports.buildStreamErrorDeviceRemoved = exports.buildStreamErrorCode = exports.buildStreamErrorAck = exports.PreKeyUploadParseError = exports.parsePreKeyUploadIq = exports.parsePairingQrString = exports.buildPairSuccessIq = exports.buildPairDeviceIq = exports.generateFakePrimaryDevice = exports.buildAdvSignedDeviceIdentity = exports.FakeSenderKey = exports.FakePeerDoubleRatchet = exports.generateFakePeerIdentity = exports.buildReceipt = exports.buildIncomingPresence = exports.buildNotification = exports.buildGroupNotification = exports.buildMessage = exports.FakeMediaStore = exports.FakeAppStateCollection = exports.FakeAppStateCrypto = exports.APP_STATE_EMPTY_LT_HASH = exports.encodeHistorySyncPlaintext = exports.buildHistorySyncMessage = exports.buildHistorySyncExternalMessage = exports.buildAppStateSyncKeyShareMessage = exports.buildIncomingErrorStanza = exports.buildChatstate = exports.buildFailure = exports.buildCall = exports.buildIqResult = exports.buildIqError = exports.parseAppStateSyncRequest = exports.buildServerSyncNotification = exports.buildAppStateSyncResult = exports.buildAppStateSyncFullResult = exports.WaFakeConnection = exports.Scenario = exports.IqExpectation = exports.FakeWaServer = exports.FakePeer = exports.FakePairingDriver = void 0;
+exports.FakePeerDoubleRatchet = exports.generateFakePeerIdentity = exports.buildReceipt = exports.buildIncomingPresence = exports.buildNotification = exports.buildGroupNotification = exports.buildMessage = exports.FakeMediaStore = exports.FakeAppStateCollection = exports.FakeAppStateCrypto = exports.APP_STATE_EMPTY_LT_HASH = exports.encodeHistorySyncPlaintext = exports.buildHistorySyncMessage = exports.buildHistorySyncExternalMessage = exports.buildAppStateSyncKeyShareMessage = exports.buildIncomingErrorStanza = exports.buildChatstate = exports.buildFailure = exports.buildCall = exports.buildIqResult = exports.buildIqError = exports.parseAppStateSyncRequest = exports.buildServerSyncNotification = exports.buildAppStateSyncResult = exports.buildAppStateSyncFullResult = exports.readCompanionKeyIndex = exports.FakeCompanionHostState = exports.buildRegistrationCodeNotification = exports.buildAccountTakeoverNotice = exports.buildAccountSyncDevicesNotification = exports.parseLinkCodeStanza = exports.buildLinkCodeNotification = exports.buildCompanionHelloResultContent = exports.parseRemoveCompanionDevice = exports.parsePairDeviceUpload = exports.parseKeyIndexListPublish = exports.parseClientPayload = exports.ClientPayloadValidationError = exports.createWebSocketAdapter = exports.createTcpSocketAdapter = exports.WaFakeTcpServer = exports.WaFakeConnection = exports.Scenario = exports.IqExpectation = exports.FakeWaServer = exports.FakeServerSession = exports.FakePeer = exports.FakePairingDriver = exports.seedFakeMobilePrimary = exports.createFakeMobilePrimary = void 0;
+exports.buildStreamErrorXmlNotWellFormed = exports.buildStreamErrorReplaced = exports.buildStreamErrorDeviceRemoved = exports.buildStreamErrorCode = exports.buildStreamErrorAck = exports.PreKeyUploadParseError = exports.parsePreKeyUploadIq = exports.parsePairingQrString = exports.buildPairSuccessIq = exports.buildPairDeviceIq = exports.generateFakePrimaryDevice = exports.buildAdvSignedDeviceIdentity = exports.FakeSenderKey = void 0;
+var FakeMobilePrimary_1 = require("./api/FakeMobilePrimary");
+Object.defineProperty(exports, "createFakeMobilePrimary", { enumerable: true, get: function () { return FakeMobilePrimary_1.createFakeMobilePrimary; } });
+Object.defineProperty(exports, "seedFakeMobilePrimary", { enumerable: true, get: function () { return FakeMobilePrimary_1.seedFakeMobilePrimary; } });
 var FakePairingDriver_1 = require("./api/FakePairingDriver");
 Object.defineProperty(exports, "FakePairingDriver", { enumerable: true, get: function () { return FakePairingDriver_1.FakePairingDriver; } });
 var FakePeer_1 = require("./api/FakePeer");
 Object.defineProperty(exports, "FakePeer", { enumerable: true, get: function () { return FakePeer_1.FakePeer; } });
 var FakeWaServer_1 = require("./api/FakeWaServer");
+Object.defineProperty(exports, "FakeServerSession", { enumerable: true, get: function () { return FakeWaServer_1.FakeServerSession; } });
 Object.defineProperty(exports, "FakeWaServer", { enumerable: true, get: function () { return FakeWaServer_1.FakeWaServer; } });
 var Scenario_1 = require("./api/Scenario");
 Object.defineProperty(exports, "IqExpectation", { enumerable: true, get: function () { return Scenario_1.IqExpectation; } });
 Object.defineProperty(exports, "Scenario", { enumerable: true, get: function () { return Scenario_1.Scenario; } });
 var WaFakeConnection_1 = require("./infra/WaFakeConnection");
 Object.defineProperty(exports, "WaFakeConnection", { enumerable: true, get: function () { return WaFakeConnection_1.WaFakeConnection; } });
+var WaFakeTcpServer_1 = require("./infra/WaFakeTcpServer");
+Object.defineProperty(exports, "WaFakeTcpServer", { enumerable: true, get: function () { return WaFakeTcpServer_1.WaFakeTcpServer; } });
+var socket_adapters_1 = require("./infra/socket-adapters");
+Object.defineProperty(exports, "createTcpSocketAdapter", { enumerable: true, get: function () { return socket_adapters_1.createTcpSocketAdapter; } });
+Object.defineProperty(exports, "createWebSocketAdapter", { enumerable: true, get: function () { return socket_adapters_1.createWebSocketAdapter; } });
+var client_payload_validate_1 = require("./protocol/auth/client-payload-validate");
+Object.defineProperty(exports, "ClientPayloadValidationError", { enumerable: true, get: function () { return client_payload_validate_1.ClientPayloadValidationError; } });
+Object.defineProperty(exports, "parseClientPayload", { enumerable: true, get: function () { return client_payload_validate_1.parseClientPayload; } });
+var companion_host_1 = require("./protocol/iq/companion-host");
+Object.defineProperty(exports, "parseKeyIndexListPublish", { enumerable: true, get: function () { return companion_host_1.parseKeyIndexListPublish; } });
+Object.defineProperty(exports, "parsePairDeviceUpload", { enumerable: true, get: function () { return companion_host_1.parsePairDeviceUpload; } });
+Object.defineProperty(exports, "parseRemoveCompanionDevice", { enumerable: true, get: function () { return companion_host_1.parseRemoveCompanionDevice; } });
+var link_code_1 = require("./protocol/iq/link-code");
+Object.defineProperty(exports, "buildCompanionHelloResultContent", { enumerable: true, get: function () { return link_code_1.buildCompanionHelloResultContent; } });
+Object.defineProperty(exports, "buildLinkCodeNotification", { enumerable: true, get: function () { return link_code_1.buildLinkCodeNotification; } });
+Object.defineProperty(exports, "parseLinkCodeStanza", { enumerable: true, get: function () { return link_code_1.parseLinkCodeStanza; } });
+var mobile_notification_1 = require("./protocol/push/mobile-notification");
+Object.defineProperty(exports, "buildAccountSyncDevicesNotification", { enumerable: true, get: function () { return mobile_notification_1.buildAccountSyncDevicesNotification; } });
+Object.defineProperty(exports, "buildAccountTakeoverNotice", { enumerable: true, get: function () { return mobile_notification_1.buildAccountTakeoverNotice; } });
+Object.defineProperty(exports, "buildRegistrationCodeNotification", { enumerable: true, get: function () { return mobile_notification_1.buildRegistrationCodeNotification; } });
+var fake_companion_host_1 = require("./state/fake-companion-host");
+Object.defineProperty(exports, "FakeCompanionHostState", { enumerable: true, get: function () { return fake_companion_host_1.FakeCompanionHostState; } });
+Object.defineProperty(exports, "readCompanionKeyIndex", { enumerable: true, get: function () { return fake_companion_host_1.readCompanionKeyIndex; } });
 var appstate_sync_1 = require("./protocol/iq/appstate-sync");
 Object.defineProperty(exports, "buildAppStateSyncFullResult", { enumerable: true, get: function () { return appstate_sync_1.buildAppStateSyncFullResult; } });
 Object.defineProperty(exports, "buildAppStateSyncResult", { enumerable: true, get: function () { return appstate_sync_1.buildAppStateSyncResult; } });

package/dist/infra/WaFakeConnection.d.ts

@@ -1,4 +1,3 @@
-import type { WebSocket } from 'ws';
 export type WaFakeConnectionState = 'open' | 'closing' | 'closed';
 export interface WaFakeConnectionHandlers {
     readonly onFrame?: (frame: Uint8Array) => void;
@@ -8,15 +7,34 @@ export interface WaFakeConnectionHandlers {
     }) => void;
     readonly onError?: (error: Error) => void;
 }
+/** Events a carrier adapter pushes into the connection it backs. */
+export interface WaFakeSocketEvents {
+    readonly onFrame: (frame: Uint8Array) => void;
+    readonly onClose: (info: {
+        readonly code: number;
+        readonly reason: string;
+    }) => void;
+    readonly onError: (error: Error) => void;
+}
+/**
+ * Carrier a connection speaks over. Each transport adapts its own quirks (the
+ * WebSocket fragment array, the absence of close codes on a TCP stream) behind
+ * this interface, so every layer above stays carrier-agnostic: the WebSocket
+ * listener serves companions, the TCP listener serves the mobile transport.
+ */
+export interface WaFakeSocketLike {
+    readonly send: (frame: Uint8Array) => void;
+    readonly close: (code: number, reason: string) => void;
+    readonly listen: (events: WaFakeSocketEvents) => void;
+}
 export declare class WaFakeConnection {
     readonly id: string;
     private readonly socket;
     private handlers;
     private currentState;
-    constructor(id: string, socket: WebSocket);
+    constructor(id: string, socket: WaFakeSocketLike);
     get state(): WaFakeConnectionState;
     setHandlers(handlers: WaFakeConnectionHandlers): void;
     sendFrame(frame: Uint8Array): void;
     close(code?: number, reason?: string): void;
-    private bindSocketEvents;
 }

package/dist/infra/WaFakeConnection.js

@@ -7,7 +7,14 @@ 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;
@@ -28,26 +35,5 @@ 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);
-        });
-    }
 }
 exports.WaFakeConnection = WaFakeConnection;

package/dist/infra/WaFakeConnectionPipeline.d.ts

@@ -2,7 +2,6 @@
 import { type FakeNoiseRootCa } from '../protocol/auth/cert-chain';
 import { type ParsedClientPayload } from '../protocol/auth/client-payload-validate';
 import { buildSuccessNode } from '../protocol/auth/success-node';
-import { type WaFakeIqRouter } from '../protocol/iq/router';
 import { type BinaryNode } from '../transport/codec';
 import { type SignalKeyPair } from '../transport/crypto';
 import type { WaFakeConnection } from './WaFakeConnection';
@@ -10,7 +9,12 @@ export interface WaFakeConnectionPipelineConfig {
     readonly connection: WaFakeConnection;
     readonly rootCa: FakeNoiseRootCa;
     readonly serverStaticKeyPair: SignalKeyPair;
-    readonly iqRouter: WaFakeIqRouter;
+    /**
+     * Routes an inbound IQ against the session this connection is bound to.
+     * The server resolves the session per connection, so the pipeline stays
+     * unaware of session identity.
+     */
+    readonly routeIq: (iq: BinaryNode) => Promise<BinaryNode | null>;
     readonly successNodeAttributes?: Parameters<typeof buildSuccessNode>[0];
 }
 export interface WaFakeConnectionPipelineEvents {
@@ -33,9 +37,13 @@ export declare class WaFakeConnectionPipeline {
     private events;
     private state;
     private chain;
+    private authenticatedPayload;
+    private clientPrologue;
     constructor(config: WaFakeConnectionPipelineConfig);
     setEvents(events: WaFakeConnectionPipelineEvents): void;
     isAuthenticated(): boolean;
+    /** Parsed ClientPayload of the authenticated connection; null before auth. */
+    get clientPayload(): ParsedClientPayload | null;
     sendStanza(node: BinaryNode): Promise<void>;
     private onPrologue;
     private scheduleFrame;
@@ -45,6 +53,7 @@ export declare class WaFakeConnectionPipeline {
     /** Server-side IK path used when the client already cached our static key. */
     private handleIkClientHello;
     private handleClientFinish;
+    private completeAuthentication;
     private handleAuthenticatedFrame;
     private fail;
 }

package/dist/infra/WaFakeConnectionPipeline.js

@@ -13,16 +13,20 @@ const WaFakeNoiseHandshake_1 = require("./WaFakeNoiseHandshake");
 const WaFakeTransport_1 = require("./WaFakeTransport");
 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]);
 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_1.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' };
@@ -37,6 +41,10 @@ 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}"`);
@@ -46,11 +54,20 @@ 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) {
@@ -92,7 +109,7 @@ class WaFakeConnectionPipeline {
     }
     async handleXxClientHello(clientEphemeralPub) {
         const handshake = new WaFakeNoiseHandshake_1.WaFakeNoiseHandshake();
-        handshake.start(NOISE_XX_NAME, PROLOGUE);
+        handshake.start(NOISE_XX_NAME, this.clientPrologue);
         handshake.authenticate(clientEphemeralPub);
         const serverEphemeral = await crypto_1.X25519.generateKeyPair();
         handshake.authenticate(serverEphemeral.pubKey);
@@ -128,7 +145,7 @@ class WaFakeConnectionPipeline {
         const encryptedClientStatic = clientHello.static;
         const encryptedClientPayload = clientHello.payload;
         const handshake = new WaFakeNoiseHandshake_1.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 crypto_1.X25519.scalarMult(this.config.serverStaticKeyPair.privKey, clientEphemeralPub));
@@ -156,14 +173,7 @@ class WaFakeConnectionPipeline {
             }
         }).finish();
         this.frameSocket.sendFrame(serverHello);
-        const keys = handshake.finish();
-        const transport = new WaFakeTransport_1.WaFakeTransport({
-            recvKey: keys.recvKey,
-            sendKey: keys.sendKey
-        });
-        this.state = { kind: 'authenticated', transport };
-        await this.sendStanza((0, success_node_1.buildSuccessNode)(this.config.successNodeAttributes));
-        this.events.onAuthenticated?.({ clientPayload, clientStaticKey });
+        await this.completeAuthentication(handshake, clientPayload, clientStaticKey);
     }
     async handleClientFinish(frame, handshake, serverEphemeralKeyPair) {
         const parsed = protos_1.proto.HandshakeMessage.decode(frame);
@@ -175,13 +185,27 @@ class WaFakeConnectionPipeline {
         handshake.mixIntoKey(await crypto_1.X25519.scalarMult(serverEphemeralKeyPair.privKey, clientStaticKey));
         const clientPayloadBytes = handshake.decrypt(clientFinish.payload);
         const clientPayload = (0, client_payload_validate_1.parseClientPayload)(clientPayloadBytes);
+        await this.completeAuthentication(handshake, clientPayload, clientStaticKey);
+    }
+    async completeAuthentication(handshake, clientPayload, clientStaticKey) {
         const keys = handshake.finish();
         const transport = new WaFakeTransport_1.WaFakeTransport({
             recvKey: keys.recvKey,
             sendKey: keys.sendKey
         });
         this.state = { kind: 'authenticated', transport };
+        this.authenticatedPayload = clientPayload;
         await this.sendStanza((0, success_node_1.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) {
@@ -189,7 +213,7 @@ class WaFakeConnectionPipeline {
         const node = await (0, codec_1.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/infra/WaFakeTcpServer.d.ts

@@ -0,0 +1,29 @@
+import { WaFakeConnection } from './WaFakeConnection';
+export interface WaFakeTcpServerOptions {
+    readonly host?: string;
+    readonly port?: number;
+}
+export interface WaFakeTcpServerListenInfo {
+    readonly host: string;
+    readonly port: number;
+    /** `tcp://host:port` – feed straight into `mobileTransport.tcpUrl`. */
+    readonly url: string;
+}
+export type WaFakeTcpServerConnectionListener = (connection: WaFakeConnection) => void;
+/**
+ * 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 declare class WaFakeTcpServer {
+    private readonly options;
+    private server;
+    private connectionListener;
+    private readonly sockets;
+    private nextConnectionId;
+    constructor(options?: WaFakeTcpServerOptions);
+    onConnection(listener: WaFakeTcpServerConnectionListener): void;
+    listen(): Promise<WaFakeTcpServerListenInfo>;
+    close(): Promise<void>;
+}

package/dist/infra/WaFakeTcpServer.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WaFakeTcpServer = void 0;
+const node_net_1 = require("node:net");
+const socket_adapters_1 = require("./socket-adapters");
+const WaFakeConnection_1 = require("./WaFakeConnection");
+/**
+ * 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}.
+ */
+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 = (0, node_net_1.createServer)((socket) => {
+            this.sockets.add(socket);
+            socket.on('close', () => this.sockets.delete(socket));
+            const id = `t${this.nextConnectionId++}`;
+            this.connectionListener?.(new WaFakeConnection_1.WaFakeConnection(id, (0, socket_adapters_1.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;
+    }
+}
+exports.WaFakeTcpServer = WaFakeTcpServer;

package/dist/infra/WaFakeWsServer.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WaFakeWsServer = void 0;
 const node_http_1 = require("node:http");
 const ws_1 = require("ws");
+const socket_adapters_1 = require("./socket-adapters");
 const WaFakeConnection_1 = require("./WaFakeConnection");
 class WaFakeWsServer {
     constructor(options = {}) {
@@ -52,7 +53,7 @@ class WaFakeWsServer {
         const wsServer = new ws_1.WebSocketServer({ server: httpServer, path: this.options.path });
         wsServer.on('connection', (socket) => {
             const id = `c${this.nextConnectionId++}`;
-            const connection = new WaFakeConnection_1.WaFakeConnection(id, socket);
+            const connection = new WaFakeConnection_1.WaFakeConnection(id, (0, socket_adapters_1.createWebSocketAdapter)(socket));
             this.connectionListener?.(connection);
         });
         await new Promise((resolve, reject) => {