@zapo-js/fake-server 1.0.0 → 1.1.0

package/README.md

@@ -2,6 +2,14 @@
 
 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.
 
+## 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
 
 ```ts
@@ -50,7 +58,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 +71,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:
@@ -101,8 +158,10 @@ Every outbound IQ the lib sends during normal operation is handled:
 | `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 |
@@ -119,6 +178,16 @@ Every outbound IQ the lib sends during normal operation is handled:
 | `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
 
 ```bash
@@ -161,16 +230,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/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,67 @@
+/** Per-session isolated server state: registries, prekeys, app-state, IQ routing, capture. */
+import type { BuildAbPropsResultInput } from '../protocol/iq/abprops';
+import { type WaFakeIqMatcher, type WaFakeIqResponder, WaFakeIqRouter } from '../protocol/iq/router';
+import type { ClientPreKeyBundle } from '../protocol/signal/prekey-upload';
+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;
+    };
+}
+/**
+ * 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 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): 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;
+}
+export declare function matchesIq(iq: BinaryNode, matcher: WaFakeIqMatcher): boolean;
+export declare function matchesStanza(node: BinaryNode, matcher: StanzaMatcher): boolean;
+export type { ClientPreKeyBundle, BuildAbPropsResultInput };

package/dist/api/FakeServerSession.js

@@ -0,0 +1,293 @@
+"use strict";
+/** Per-session isolated server state: registries, prekeys, app-state, IQ routing, capture. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FakeServerSession = void 0;
+exports.matchesIq = matchesIq;
+exports.matchesStanza = matchesStanza;
+const router_1 = require("../protocol/iq/router");
+const AppStateSyncManager_1 = require("./AppStateSyncManager");
+const iq_handlers_1 = require("./iq-handlers");
+const PreKeyDispenser_1 = require("./PreKeyDispenser");
+const ServerRegistries_1 = require("./ServerRegistries");
+/**
+ * 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.
+ */
+class FakeServerSession {
+    constructor(id, host, options) {
+        this.registries = new ServerRegistries_1.ServerRegistries();
+        this.preKeyDispenser = new PreKeyDispenser_1.PreKeyDispenser();
+        this.appStateSync = new AppStateSyncManager_1.AppStateSyncManager();
+        this.iqRouter = new router_1.WaFakeIqRouter();
+        this.capturedStanzas = [];
+        this.pendingIqExpectations = new Set();
+        this.pendingStanzaExpectations = new Set();
+        this.capturedStanzaListeners = new Set();
+        this.inboundStanzaListeners = new Set();
+        this.id = id;
+        if (options.defaultIqHandlers) {
+            (0, iq_handlers_1.registerDefaultIqHandlers)(this.iqRouter, this.buildIqHandlerDeps(host));
+        }
+    }
+    registerIqHandler(matcher, respond, label) {
+        const handler = { matcher, respond, label };
+        return this.iqRouter.register(handler, { priority: 'high' });
+    }
+    routeIq(iq) {
+        return this.iqRouter.route(iq);
+    }
+    handleCapturedStanza(node) {
+        this.capturedStanzas.push(node);
+        for (const listener of this.capturedStanzaListeners) {
+            try {
+                listener(node);
+            }
+            catch (error) {
+                void error;
+            }
+        }
+        for (const listener of this.inboundStanzaListeners) {
+            try {
+                listener(node);
+            }
+            catch (error) {
+                void error;
+            }
+        }
+        for (const expectation of this.pendingStanzaExpectations) {
+            if (matchesStanza(node, expectation.matcher)) {
+                expectation.resolve(node);
+                break;
+            }
+        }
+        if (node.tag !== 'iq') {
+            return;
+        }
+        for (const expectation of this.pendingIqExpectations) {
+            if (matchesIq(node, expectation.matcher)) {
+                expectation.resolve(node);
+                return;
+            }
+        }
+    }
+    subscribeInboundMessages(listener) {
+        const wrapped = (node) => {
+            if (node.tag !== 'message')
+                return;
+            listener(node);
+        };
+        this.inboundStanzaListeners.add(wrapped);
+        return () => {
+            this.inboundStanzaListeners.delete(wrapped);
+        };
+    }
+    onCapturedStanza(listener) {
+        this.capturedStanzaListeners.add(listener);
+        return () => {
+            this.capturedStanzaListeners.delete(listener);
+        };
+    }
+    capturedStanzaSnapshot() {
+        return this.capturedStanzas.slice();
+    }
+    expectIq(matcher, options = {}) {
+        const timeoutMs = options.timeoutMs ?? 2000;
+        for (const captured of this.capturedStanzas) {
+            if (matchesIq(captured, matcher)) {
+                return Promise.resolve(captured);
+            }
+        }
+        return new Promise((resolve, reject) => {
+            const expectation = {
+                matcher,
+                resolve: (iq) => {
+                    this.pendingIqExpectations.delete(expectation);
+                    clearTimeout(expectation.timer);
+                    resolve(iq);
+                },
+                reject: (error) => {
+                    this.pendingIqExpectations.delete(expectation);
+                    clearTimeout(expectation.timer);
+                    reject(error);
+                },
+                timer: setTimeout(() => {
+                    this.pendingIqExpectations.delete(expectation);
+                    reject(new Error(`expectIq timed out after ${timeoutMs}ms (${describeMatcher(matcher)})`));
+                }, timeoutMs)
+            };
+            this.pendingIqExpectations.add(expectation);
+        });
+    }
+    expectStanza(matcher, options = {}) {
+        const timeoutMs = options.timeoutMs ?? 2000;
+        for (const captured of this.capturedStanzas) {
+            if (matchesStanza(captured, matcher)) {
+                return Promise.resolve(captured);
+            }
+        }
+        return new Promise((resolve, reject) => {
+            const expectation = {
+                matcher,
+                resolve: (node) => {
+                    this.pendingStanzaExpectations.delete(expectation);
+                    clearTimeout(expectation.timer);
+                    resolve(node);
+                },
+                reject: (error) => {
+                    this.pendingStanzaExpectations.delete(expectation);
+                    clearTimeout(expectation.timer);
+                    reject(error);
+                },
+                timer: setTimeout(() => {
+                    this.pendingStanzaExpectations.delete(expectation);
+                    reject(new Error(`expectStanza timed out after ${timeoutMs}ms (${describeStanzaMatcher(matcher)})`));
+                }, timeoutMs)
+            };
+            this.pendingStanzaExpectations.add(expectation);
+        });
+    }
+    buildIqHandlerDeps(host) {
+        const reg = this.registries;
+        const preKey = this.preKeyDispenser;
+        const appState = this.appStateSync;
+        return {
+            get peerRegistry() {
+                return reg.peerRegistry;
+            },
+            get groupRegistry() {
+                return reg.groupRegistry;
+            },
+            get privacySettings() {
+                return reg.privacySettings;
+            },
+            get blocklistJids() {
+                return reg.blocklistJids;
+            },
+            get profilePicturesByJid() {
+                return reg.profilePicturesByJid;
+            },
+            get businessProfilesByJid() {
+                return reg.businessProfilesByJid;
+            },
+            get abPropsInput() {
+                return reg.abPropsInput;
+            },
+            get issuedPrivacyTokens() {
+                return reg.issuedPrivacyTokens;
+            },
+            get latestStatusText() {
+                return reg.latestStatusText;
+            },
+            setLatestStatusText: (text) => {
+                reg.latestStatusText = text;
+            },
+            lookupDeviceIdsForUser: (userJid) => reg.lookupDeviceIdsForUser(userJid),
+            notifyGroupOp: (op) => reg.notifyGroupOp(op),
+            mutatePrivacySettings: (category, value) => reg.mutatePrivacySettings(category, value),
+            mutateBlocklist: (action, jid) => reg.mutateBlocklist(action, jid),
+            notifyProfilePictureSet: (op) => reg.notifyProfilePictureSet(op),
+            handleProfilePictureSet: (targetJid, newId) => reg.handleProfilePictureSet(targetJid, newId),
+            notifyStatusSet: (text) => reg.notifyStatusSet(text),
+            notifyLogout: () => reg.notifyLogout(),
+            notifyPrivacyTokenIssue: (token) => reg.notifyPrivacyTokenIssue(token),
+            notifyDirtyBitsClear: (op) => reg.notifyDirtyBitsClear(op),
+            notifyPrivacySet: (change) => {
+                for (const listener of reg.privacySetListeners) {
+                    try {
+                        listener(change);
+                    }
+                    catch (error) {
+                        void error;
+                    }
+                }
+            },
+            notifyBlocklistChange: (change) => {
+                for (const listener of reg.blocklistChangeListeners) {
+                    try {
+                        listener(change);
+                    }
+                    catch (error) {
+                        void error;
+                    }
+                }
+            },
+            capturePreKeyBundle: (bundle) => preKey.captureBundle(bundle),
+            countServerPreKeys: () => preKey.preKeysAvailable(),
+            consumeOutboundAppStatePatches: (iq) => appState.consumeOutboundAppStatePatches(iq),
+            get appStateCollectionProviders() {
+                return appState.appStateCollectionProviders;
+            },
+            requireMediaHttpsInfo: () => host.requireMediaHttpsInfo()
+        };
+    }
+}
+exports.FakeServerSession = FakeServerSession;
+function matchesIq(iq, matcher) {
+    if (iq.tag !== 'iq')
+        return false;
+    if (matcher.id !== undefined && iq.attrs.id !== matcher.id)
+        return false;
+    if (matcher.type !== undefined && iq.attrs.type !== matcher.type)
+        return false;
+    if (matcher.xmlns !== undefined && iq.attrs.xmlns !== matcher.xmlns)
+        return false;
+    if (matcher.childTag !== undefined) {
+        const children = Array.isArray(iq.content) ? iq.content : null;
+        if (!children || children.length === 0)
+            return false;
+        if (children[0].tag !== matcher.childTag)
+            return false;
+    }
+    return true;
+}
+function describeMatcher(matcher) {
+    const parts = [];
+    if (matcher.id !== undefined)
+        parts.push(`id=${matcher.id}`);
+    if (matcher.type !== undefined)
+        parts.push(`type=${matcher.type}`);
+    if (matcher.xmlns !== undefined)
+        parts.push(`xmlns=${matcher.xmlns}`);
+    if (matcher.childTag !== undefined)
+        parts.push(`childTag=${matcher.childTag}`);
+    return parts.length > 0 ? parts.join(', ') : 'any iq';
+}
+function matchesStanza(node, matcher) {
+    if (matcher.tag !== undefined && node.tag !== matcher.tag)
+        return false;
+    if (matcher.type !== undefined && node.attrs.type !== matcher.type)
+        return false;
+    if (matcher.xmlns !== undefined && node.attrs.xmlns !== matcher.xmlns)
+        return false;
+    if (matcher.from !== undefined && node.attrs.from !== matcher.from)
+        return false;
+    if (matcher.to !== undefined && node.attrs.to !== matcher.to)
+        return false;
+    if (matcher.childTag !== undefined) {
+        const children = Array.isArray(node.content) ? node.content : null;
+        if (!children || children.length === 0)
+            return false;
+        if (children[0].tag !== matcher.childTag)
+            return false;
+    }
+    return true;
+}
+function describeStanzaMatcher(matcher) {
+    const parts = [];
+    if (matcher.tag !== undefined)
+        parts.push(`tag=${matcher.tag}`);
+    if (matcher.type !== undefined)
+        parts.push(`type=${matcher.type}`);
+    if (matcher.xmlns !== undefined)
+        parts.push(`xmlns=${matcher.xmlns}`);
+    if (matcher.from !== undefined)
+        parts.push(`from=${matcher.from}`);
+    if (matcher.to !== undefined)
+        parts.push(`to=${matcher.to}`);
+    if (matcher.childTag !== undefined)
+        parts.push(`childTag=${matcher.childTag}`);
+    return parts.length > 0 ? parts.join(', ') : 'any stanza';
+}