@zapo-js/fake-server 1.0.0 → 1.1.0

package/dist/bin.js

@@ -2,13 +2,17 @@
 "use strict";
 /** Standalone CLI for `@zapo-js/fake-server`. */
 Object.defineProperty(exports, "__esModule", { value: true });
+const node_readline_1 = require("node:readline");
 const FakeWaServer_1 = require("./api/FakeWaServer");
+const pair_device_1 = require("./protocol/auth/pair-device");
+const util_1 = require("./transport/util");
 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;
@@ -46,6 +50,9 @@ function parseArgs(argv) {
             case '--group':
                 groupSpecs.push(next());
                 break;
+            case '--pair':
+                pairJid = next();
+                break;
             case '--log':
                 log = true;
                 break;
@@ -59,7 +66,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
@@ -75,6 +82,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
@@ -105,7 +118,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: ${(0, util_1.toError)(error).message}\n`);
         process.stderr.write('run with --help to see usage.\n');
         process.exit(2);
     }
@@ -127,11 +140,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 = (0, pair_device_1.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: ${(0, util_1.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();
@@ -157,7 +198,7 @@ async function main() {
                 resolve();
             }
             catch (error) {
-                reject(error instanceof Error ? error : new Error(String(error)));
+                reject((0, util_1.toError)(error));
             }
         });
     });
@@ -166,12 +207,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) {
@@ -184,10 +224,11 @@ async function main() {
                 path: args.path,
                 noiseRootCa: {
                     serial: noiseRoot.serial,
-                    publicKeyHex: bytesToHex(noiseRoot.publicKey)
+                    publicKeyHex: (0, util_1.bytesToHex)(noiseRoot.publicKey)
                 },
                 peers: args.peerJids,
-                groups: parsedGroups
+                groups: parsedGroups,
+                pair: args.pairJid
             }, null, 2) + '\n');
         }
         else {
@@ -200,9 +241,10 @@ async function main() {
                 `│ host           ${server.host}`,
                 `│ port           ${server.port}`,
                 `│ path           ${args.path}`,
-                `│ noise root ca  serial=${noiseRoot.serial} pub=${bytesToHex(noiseRoot.publicKey).slice(0, 32)}…`,
+                `│ noise root ca  serial=${noiseRoot.serial} pub=${(0, util_1.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]',
@@ -226,7 +268,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: ${(0, util_1.toError)(error).message}\n`);
             process.exit(1);
         }
     };
@@ -234,15 +276,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 = (0, node_readline_1.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 = (0, util_1.toError)(error);
+    process.stderr.write(`fatal: ${normalized.stack ?? normalized.message}\n`);
     process.exit(1);
 });

package/dist/esm/api/FakePeer.js

@@ -547,7 +547,13 @@ export 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();
     }
 }
 function findEncForPeer(stanza, peerJid) {

package/dist/esm/api/FakeServerSession.js

@@ -0,0 +1,287 @@
+/** Per-session isolated server state: registries, prekeys, app-state, IQ routing, capture. */
+import { WaFakeIqRouter } from '../protocol/iq/router.js';
+import { AppStateSyncManager } from './AppStateSyncManager.js';
+import { registerDefaultIqHandlers } from './iq-handlers.js';
+import { PreKeyDispenser } from './PreKeyDispenser.js';
+import { ServerRegistries } from './ServerRegistries.js';
+/**
+ * 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 class FakeServerSession {
+    constructor(id, host, options) {
+        this.registries = new ServerRegistries();
+        this.preKeyDispenser = new PreKeyDispenser();
+        this.appStateSync = new AppStateSyncManager();
+        this.iqRouter = new 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) {
+            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()
+        };
+    }
+}
+export 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';
+}
+export 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';
+}