@zapo-js/fake-server 0.3.0 → 1.1.0

package/dist/{cli.js → esm/bin.js}

@@ -1,14 +1,16 @@
 #!/usr/bin/env node
-"use strict";
 /** Standalone CLI for `@zapo-js/fake-server`. */
-Object.defineProperty(exports, "__esModule", { value: true });
-const FakeWaServer_1 = require("./api/FakeWaServer");
+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;
@@ -46,6 +48,9 @@ function parseArgs(argv) {
             case '--group':
                 groupSpecs.push(next());
                 break;
+            case '--pair':
+                pairJid = next();
+                break;
             case '--log':
                 log = true;
                 break;
@@ -59,10 +64,10 @@ 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
+    process.stdout.write(`@zapo-js/fake-server – standalone fake WhatsApp Web server
 
 USAGE
   npx @zapo-js/fake-server [flags]
@@ -75,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
@@ -105,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);
     }
@@ -122,16 +133,44 @@ async function main() {
             }
         }
     }
-    const server = await FakeWaServer_1.FakeWaServer.start({
+    const server = await FakeWaServer.start({
         host: args.host,
         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();
@@ -157,7 +196,7 @@ async function main() {
                 resolve();
             }
             catch (error) {
-                reject(error instanceof Error ? error : new Error(String(error)));
+                reject(toError(error));
             }
         });
     });
@@ -166,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) {
@@ -187,7 +225,8 @@ async function main() {
                     publicKeyHex: bytesToHex(noiseRoot.publicKey)
                 },
                 peers: args.peerJids,
-                groups: parsedGroups
+                groups: parsedGroups,
+                pair: args.pairJid
             }, null, 2) + '\n');
         }
         else {
@@ -203,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]',
@@ -226,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);
         }
     };
@@ -234,16 +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);
 });
-//# sourceMappingURL=cli.js.map

package/dist/esm/index.js

@@ -0,0 +1,26 @@
+export { FakePairingDriver } from './api/FakePairingDriver.js';
+export { FakePeer } from './api/FakePeer.js';
+export { FakeServerSession, FakeWaServer } from './api/FakeWaServer.js';
+export { IqExpectation, Scenario } from './api/Scenario.js';
+export { WaFakeConnection } from './infra/WaFakeConnection.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';
+export { buildChatstate } from './protocol/push/chatstate.js';
+export { buildIncomingErrorStanza } from './protocol/push/error-stanza.js';
+export { buildAppStateSyncKeyShareMessage } from './protocol/push/app-state-key-share.js';
+export { buildHistorySyncExternalMessage, buildHistorySyncMessage, encodeHistorySyncPlaintext } from './protocol/push/history-sync.js';
+export { APP_STATE_EMPTY_LT_HASH, FakeAppStateCrypto } from './protocol/signal/fake-app-state-crypto.js';
+export { FakeAppStateCollection } from './state/fake-app-state-collection.js';
+export { FakeMediaStore } from './state/fake-media-store.js';
+export { buildMessage } from './protocol/push/message.js';
+export { buildGroupNotification, buildNotification } from './protocol/push/notification.js';
+export { buildIncomingPresence } from './protocol/push/presence.js';
+export { buildReceipt } from './protocol/push/receipt.js';
+export { generateFakePeerIdentity } from './protocol/signal/fake-peer-identity.js';
+export { FakePeerDoubleRatchet } from './protocol/signal/fake-peer-double-ratchet.js';
+export { FakeSenderKey } from './protocol/signal/fake-sender-key.js';
+export { buildAdvSignedDeviceIdentity, generateFakePrimaryDevice } from './protocol/auth/fake-primary-device.js';
+export { buildPairDeviceIq, buildPairSuccessIq, parsePairingQrString } from './protocol/auth/pair-device.js';
+export { parsePreKeyUploadIq, PreKeyUploadParseError } from './protocol/signal/prekey-upload.js';
+export { buildStreamErrorAck, buildStreamErrorCode, buildStreamErrorDeviceRemoved, buildStreamErrorReplaced, buildStreamErrorXmlNotWellFormed } from './protocol/stream/stream-error.js';

package/dist/esm/infra/WaFakeConnection.js

@@ -0,0 +1,49 @@
+export class WaFakeConnection {
+    constructor(id, socket) {
+        this.handlers = {};
+        this.currentState = 'open';
+        this.id = id;
+        this.socket = socket;
+        this.bindSocketEvents();
+    }
+    get state() {
+        return this.currentState;
+    }
+    setHandlers(handlers) {
+        this.handlers = handlers;
+    }
+    sendFrame(frame) {
+        if (this.currentState !== 'open') {
+            throw new Error(`cannot send frame on connection in state "${this.currentState}"`);
+        }
+        this.socket.send(frame);
+    }
+    close(code = 1000, reason = '') {
+        if (this.currentState === 'closed' || this.currentState === 'closing') {
+            return;
+        }
+        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

@@ -0,0 +1,235 @@
+/** Per-connection lifecycle pipeline (Noise handshake + stanza loop). */
+import { buildFakeCertChain } from '../protocol/auth/cert-chain.js';
+import { parseClientPayload } from '../protocol/auth/client-payload-validate.js';
+import { buildSuccessNode } from '../protocol/auth/success-node.js';
+import { decodeBinaryNodeStanza, encodeBinaryNodeStanza } from '../transport/codec.js';
+import { X25519 } from '../transport/crypto.js';
+import { proto } from '../transport/protos.js';
+import { WaFakeFrameSocket } from './WaFakeFrameSocket.js';
+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]);
+export class WaFakeConnectionPipeline {
+    constructor(config) {
+        this.events = {};
+        this.state = { kind: 'awaiting_prologue' };
+        this.chain = Promise.resolve();
+        this.authenticatedPayload = null;
+        this.config = config;
+        this.frameSocket = new WaFakeFrameSocket(config.connection);
+        this.frameSocket.setHandlers({
+            onPrologue: () => this.onPrologue(),
+            onFrame: (frame) => this.scheduleFrame(frame),
+            onClose: (info) => {
+                this.state = { kind: 'closed' };
+                this.events.onClose?.(info);
+            },
+            onError: (error) => this.events.onError?.(error)
+        });
+    }
+    setEvents(events) {
+        this.events = events;
+    }
+    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}"`);
+        }
+        const stanza = encodeBinaryNodeStanza(node);
+        // Keep outbound encrypted frames in FIFO order across concurrent callers.
+        const ciphertext = await this.state.transport.encryptFrame(stanza);
+        this.frameSocket.sendFrame(ciphertext);
+    }
+    onPrologue() {
+        if (this.state.kind !== 'awaiting_prologue') {
+            this.events.onError?.(new Error('received second prologue from client'));
+            return;
+        }
+        this.state = { kind: 'awaiting_client_hello' };
+    }
+    scheduleFrame(frame) {
+        this.chain = this.chain.then(() => this.handleFrame(frame));
+    }
+    async handleFrame(frame) {
+        try {
+            switch (this.state.kind) {
+                case 'awaiting_client_hello':
+                    await this.handleClientHello(frame);
+                    return;
+                case 'awaiting_client_finish':
+                    await this.handleClientFinish(frame, this.state.handshake, this.state.serverEphemeralKeyPair);
+                    return;
+                case 'authenticated':
+                    await this.handleAuthenticatedFrame(frame, this.state.transport);
+                    return;
+                default:
+                    this.events.onError?.(new Error(`unexpected frame in state "${this.state.kind}"`));
+            }
+        }
+        catch (error) {
+            this.fail(error);
+        }
+    }
+    async handleClientHello(frame) {
+        const parsed = proto.HandshakeMessage.decode(frame);
+        const clientHello = parsed.clientHello;
+        if (!clientHello?.ephemeral) {
+            throw new Error('ClientHello missing ephemeral');
+        }
+        // IK includes encrypted static+payload in ClientHello; XX does not.
+        if (clientHello.static && clientHello.payload) {
+            await this.handleIkClientHello(clientHello);
+        }
+        else {
+            await this.handleXxClientHello(clientHello.ephemeral);
+        }
+    }
+    async handleXxClientHello(clientEphemeralPub) {
+        const handshake = new WaFakeNoiseHandshake();
+        handshake.start(NOISE_XX_NAME, PROLOGUE);
+        handshake.authenticate(clientEphemeralPub);
+        const serverEphemeral = await X25519.generateKeyPair();
+        handshake.authenticate(serverEphemeral.pubKey);
+        handshake.mixIntoKey(await X25519.scalarMult(serverEphemeral.privKey, clientEphemeralPub));
+        const encryptedServerStatic = handshake.encrypt(this.config.serverStaticKeyPair.pubKey);
+        handshake.mixIntoKey(await X25519.scalarMult(this.config.serverStaticKeyPair.privKey, clientEphemeralPub));
+        const certChain = await buildFakeCertChain({
+            root: this.config.rootCa,
+            leafKey: this.config.serverStaticKeyPair.pubKey
+        });
+        const encryptedCertPayload = handshake.encrypt(certChain.encoded);
+        const serverHello = proto.HandshakeMessage.encode({
+            serverHello: {
+                ephemeral: serverEphemeral.pubKey,
+                static: encryptedServerStatic,
+                payload: encryptedCertPayload
+            }
+        }).finish();
+        this.frameSocket.sendFrame(serverHello);
+        this.state = {
+            kind: 'awaiting_client_finish',
+            handshake,
+            serverEphemeralKeyPair: serverEphemeral,
+            clientEphemeralPub
+        };
+    }
+    /** Server-side IK path used when the client already cached our static key. */
+    async handleIkClientHello(clientHello) {
+        if (!clientHello.ephemeral || !clientHello.static || !clientHello.payload) {
+            throw new Error('IK ClientHello missing ephemeral/static/payload');
+        }
+        const clientEphemeralPub = clientHello.ephemeral;
+        const encryptedClientStatic = clientHello.static;
+        const encryptedClientPayload = clientHello.payload;
+        const handshake = new WaFakeNoiseHandshake();
+        handshake.start(NOISE_IK_NAME, PROLOGUE);
+        handshake.authenticate(this.config.serverStaticKeyPair.pubKey);
+        handshake.authenticate(clientEphemeralPub);
+        handshake.mixIntoKey(await X25519.scalarMult(this.config.serverStaticKeyPair.privKey, clientEphemeralPub));
+        const clientStaticKey = handshake.decrypt(encryptedClientStatic);
+        handshake.mixIntoKey(await X25519.scalarMult(this.config.serverStaticKeyPair.privKey, clientStaticKey));
+        const clientPayloadBytes = handshake.decrypt(encryptedClientPayload);
+        const clientPayload = parseClientPayload(clientPayloadBytes);
+        const serverEphemeral = await X25519.generateKeyPair();
+        handshake.authenticate(serverEphemeral.pubKey);
+        const [dhEphem, dhStatic] = await Promise.all([
+            X25519.scalarMult(serverEphemeral.privKey, clientEphemeralPub),
+            X25519.scalarMult(serverEphemeral.privKey, clientStaticKey)
+        ]);
+        handshake.mixIntoKey(dhEphem);
+        handshake.mixIntoKey(dhStatic);
+        const certChain = await buildFakeCertChain({
+            root: this.config.rootCa,
+            leafKey: this.config.serverStaticKeyPair.pubKey
+        });
+        const encryptedCertPayload = handshake.encrypt(certChain.encoded);
+        const serverHello = proto.HandshakeMessage.encode({
+            serverHello: {
+                ephemeral: serverEphemeral.pubKey,
+                payload: encryptedCertPayload
+            }
+        }).finish();
+        this.frameSocket.sendFrame(serverHello);
+        await this.completeAuthentication(handshake, clientPayload, clientStaticKey);
+    }
+    async handleClientFinish(frame, handshake, serverEphemeralKeyPair) {
+        const parsed = proto.HandshakeMessage.decode(frame);
+        const clientFinish = parsed.clientFinish;
+        if (!clientFinish?.static || !clientFinish.payload) {
+            throw new Error('ClientFinish missing static/payload');
+        }
+        const clientStaticKey = handshake.decrypt(clientFinish.static);
+        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) {
+        const stanzaBytes = await transport.decryptFrame(frame);
+        const node = await decodeBinaryNodeStanza(stanzaBytes);
+        this.events.onStanza?.(node);
+        if (node.tag === 'iq') {
+            const response = await this.config.routeIq(node);
+            if (response !== null) {
+                await this.sendStanza(response);
+            }
+            else {
+                this.events.onUnhandledStanza?.(node);
+            }
+            return;
+        }
+        // Mirror the minimal ack shape that resolves the lib pending publish.
+        if (node.tag === 'message' && node.attrs.id) {
+            const messageType = node.attrs.type ?? 'text';
+            const from = node.attrs.to ?? 's.whatsapp.net';
+            const ackAttrs = {
+                id: node.attrs.id,
+                class: 'receipt',
+                type: messageType,
+                from
+            };
+            if (node.attrs.participant) {
+                ackAttrs.participant = node.attrs.participant;
+            }
+            await this.sendStanza({
+                tag: 'ack',
+                attrs: ackAttrs
+            });
+        }
+    }
+    fail(error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        this.events.onError?.(err);
+        this.state = { kind: 'closed' };
+        this.config.connection.close(1011, err.message.slice(0, 120));
+    }
+}

package/dist/esm/infra/WaFakeFrameSocket.js

@@ -0,0 +1,117 @@
+/** WhatsApp frame codec (prologue + 3-byte length-prefixed frames). */
+const PROLOGUE_W = 0x57;
+const PROLOGUE_A = 0x41;
+const ROUTING_MAGIC = 0xed;
+const VERSION_HEADER_LENGTH = 4;
+const FRAME_LENGTH_PREFIX_BYTES = 3;
+const MAX_FRAME_LENGTH = 1 << 24;
+export class WaFakeFrameSocket {
+    constructor(connection) {
+        this.handlers = {};
+        this.inboundBuffer = new Uint8Array(0);
+        this.prologueParsed = false;
+        this.connection = connection;
+        this.connection.setHandlers({
+            onFrame: (bytes) => this.handleInboundBytes(bytes),
+            onClose: (info) => this.handlers.onClose?.(info),
+            onError: (error) => this.handlers.onError?.(error)
+        });
+    }
+    setHandlers(handlers) {
+        this.handlers = handlers;
+    }
+    sendFrame(body) {
+        if (body.byteLength >= MAX_FRAME_LENGTH) {
+            throw new Error(`frame too large: ${body.byteLength} bytes`);
+        }
+        const out = new Uint8Array(FRAME_LENGTH_PREFIX_BYTES + body.byteLength);
+        out[0] = (body.byteLength >> 16) & 0xff;
+        out[1] = (body.byteLength >> 8) & 0xff;
+        out[2] = body.byteLength & 0xff;
+        out.set(body, FRAME_LENGTH_PREFIX_BYTES);
+        this.connection.sendFrame(out);
+    }
+    handleInboundBytes(chunk) {
+        try {
+            this.inboundBuffer = concatBytes(this.inboundBuffer, chunk);
+            if (!this.prologueParsed) {
+                if (!this.tryParsePrologue()) {
+                    return;
+                }
+            }
+            this.drainFrames();
+        }
+        catch (error) {
+            this.handlers.onError?.(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    tryParsePrologue() {
+        const buffer = this.inboundBuffer;
+        let offset = 0;
+        let routingInfo = null;
+        if (buffer.byteLength === 0) {
+            return false;
+        }
+        if (buffer[0] === ROUTING_MAGIC) {
+            if (buffer.byteLength < 4) {
+                return false;
+            }
+            const routingLen = (buffer[1] << 16) | (buffer[2] << 8) | buffer[3];
+            if (buffer.byteLength < 4 + routingLen + VERSION_HEADER_LENGTH) {
+                return false;
+            }
+            routingInfo = buffer.slice(4, 4 + routingLen);
+            offset = 4 + routingLen;
+        }
+        else if (buffer.byteLength < VERSION_HEADER_LENGTH) {
+            return false;
+        }
+        const versionStart = offset;
+        const w = buffer[versionStart];
+        const a = buffer[versionStart + 1];
+        if (w !== PROLOGUE_W || a !== PROLOGUE_A) {
+            throw new Error(`invalid prologue magic: expected "WA", got ${hex(w)} ${hex(a)}`);
+        }
+        const protocolVersion = buffer[versionStart + 2];
+        const dictVersion = buffer[versionStart + 3];
+        offset = versionStart + VERSION_HEADER_LENGTH;
+        this.inboundBuffer = buffer.slice(offset);
+        this.prologueParsed = true;
+        this.handlers.onPrologue?.({ protocolVersion, dictVersion, routingInfo });
+        return true;
+    }
+    drainFrames() {
+        while (true) {
+            const buffer = this.inboundBuffer;
+            if (buffer.byteLength < FRAME_LENGTH_PREFIX_BYTES) {
+                return;
+            }
+            const length = (buffer[0] << 16) | (buffer[1] << 8) | buffer[2];
+            if (length >= MAX_FRAME_LENGTH) {
+                throw new Error(`frame too large: ${length} bytes`);
+            }
+            const total = FRAME_LENGTH_PREFIX_BYTES + length;
+            if (buffer.byteLength < total) {
+                return;
+            }
+            const body = buffer.slice(FRAME_LENGTH_PREFIX_BYTES, total);
+            this.inboundBuffer = buffer.slice(total);
+            this.handlers.onFrame?.(body);
+        }
+    }
+}
+function concatBytes(a, b) {
+    if (a.byteLength === 0)
+        return b;
+    if (b.byteLength === 0)
+        return a;
+    const out = new Uint8Array(a.byteLength + b.byteLength);
+    out.set(a, 0);
+    out.set(b, a.byteLength);
+    return out;
+}
+function hex(byte) {
+    if (byte === undefined)
+        return 'undefined';
+    return `0x${byte.toString(16).padStart(2, '0')}`;
+}