@zapo-js/fake-server 0.3.0 → 1.1.0

package/README.md

@@ -1,6 +1,14 @@
 # @zapo-js/fake-server
 
-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.
+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
 
@@ -29,8 +37,8 @@ await server.stop()
 ```text
 src/
 ├── api/                     # Public-facing API
-│   ├── FakeWaServer.ts      # Main facade — WS server, IQ router, registries, lifecycle
-│   ├── FakePeer.ts          # Simulated WhatsApp peer — Signal crypto, send/recv, groups
+│   ├── FakeWaServer.ts      # Main facade – WS server, IQ router, registries, lifecycle
+│   ├── FakePeer.ts          # Simulated WhatsApp peer – Signal crypto, send/recv, groups
 │   ├── FakePairingDriver.ts # QR pairing flow orchestrator
 │   └── Scenario.ts          # Declarative test scenario DSL
 ├── protocol/                # Protocol-layer builders, parsers, crypto
@@ -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/AppStateSyncManager.d.ts

@@ -24,4 +24,3 @@ export declare class AppStateSyncManager {
     pushServerSyncNotification(pipeline: WaFakeConnectionPipeline, input: BuildServerSyncNotificationInput): Promise<void>;
     consumeOutboundAppStatePatches(iq: BinaryNode): Promise<void>;
 }
-//# sourceMappingURL=AppStateSyncManager.d.ts.map

package/dist/api/AppStateSyncManager.js

@@ -148,4 +148,3 @@ class AppStateSyncManager {
     }
 }
 exports.AppStateSyncManager = AppStateSyncManager;
-//# sourceMappingURL=AppStateSyncManager.js.map

package/dist/api/FakePairingDriver.d.ts

@@ -24,4 +24,3 @@ export declare class FakePairingDriver {
     constructor(options: FakePairingDriverOptions, deps: FakePairingDriverDeps);
     run(): Promise<void>;
 }
-//# sourceMappingURL=FakePairingDriver.d.ts.map

package/dist/api/FakePairingDriver.js

@@ -33,4 +33,3 @@ class FakePairingDriver {
     }
 }
 exports.FakePairingDriver = FakePairingDriver;
-//# sourceMappingURL=FakePairingDriver.js.map

package/dist/api/FakePeer.d.ts

@@ -12,6 +12,13 @@ export interface CreateFakePeerOptions {
     readonly displayName?: string;
     readonly keyBundle?: FakePeerKeyBundle;
     readonly skipOneTimePreKey?: boolean;
+    /**
+     * Stash every outbound (id → plaintext + pristine ciphertext) so
+     * tests / benches can drive replays via {@link FakePeer.replaySentMessage}.
+     * Off by default to avoid inflating the fixture's heap on long
+     * memory-focused runs that never replay.
+     */
+    readonly enableReplayCache?: boolean;
 }
 export interface SendMessageOptions {
     readonly id?: string;
@@ -45,20 +52,57 @@ interface FakePeerDeps {
 export declare class FakePeer {
     readonly jid: string;
     readonly displayName?: string;
-    readonly keyBundle: FakePeerKeyBundle;
+    keyBundle: FakePeerKeyBundle;
     readonly identity: FakePeerIdentity;
     private readonly deps;
-    private readonly ratchet;
+    private ratchet;
     private readonly skipOneTimePreKey;
-    private readonly reservedOneTimePreKey;
+    private reservedOneTimePreKey;
     private ratchetInitiated;
     private nextMessageCounter;
+    private readonly replayCacheEnabled;
+    private readonly sentPlaintextById;
+    private readonly sentEncryptedById;
     private readonly senderKeysByGroup;
     private readonly groupsBootstrapped;
     private readonly groupRecvSession;
     private constructor();
     static create(options: CreateFakePeerOptions, deps: FakePeerDeps): Promise<FakePeer>;
     sendMessage(message: proto.IMessage, options?: SendMessageOptions): Promise<void>;
+    /**
+     * Re-encrypts and re-pushes a previously sent message identified by
+     * `originalMsgId`. Used by tests / benches that exercise the lib's
+     * incoming-retry path: after the lib emits `<receipt type="retry">`
+     * back to this peer, the peer is expected to re-send the same
+     * plaintext so the lib can decrypt it successfully on the second
+     * attempt.
+     *
+     * The replay reuses the original stanza id by default so the lib's
+     * dedup logic (and tests that wait for a specific id) see the resend
+     * as a continuation of the same outbound. Pass `resendId` to use a
+     * different id.
+     */
+    replaySentMessage(originalMsgId: string, options?: {
+        readonly resendId?: string;
+    }): Promise<void>;
+    /**
+     * Rotates the peer's prekey material and resets the Signal session
+     * state so the lib has to re-run X3DH on the next outbound. Keeps
+     * the identity key pair (same user) but issues a new signed prekey
+     * + new one-time prekey set. After this call:
+     *   - `keyBundle` reflects the new material;
+     *   - the underlying `FakePeerDoubleRatchet` is fresh – the next
+     *     inbound from the lib must be a `pkmsg` (initial signal
+     *     message), which the new `keyBundle` is wired to decrypt;
+     *   - any cached one-time prekey reservation in the dispenser is
+     *     dropped so subsequent retry-receipts include this peer's new
+     *     keys directly via {@link sendRetryReceipt}.
+     *
+     * Use this to simulate the "session lost" scenario that real
+     * WhatsApp clients trigger when they need the sender to fully
+     * re-bootstrap the Signal session via the retry-receipt path.
+     */
+    rotateForRetry(): Promise<void>;
     sendConversation(text: string, options?: SendMessageOptions): Promise<void>;
     sendMessageEdit(input: {
         readonly targetMessageId: string;
@@ -131,6 +175,36 @@ export declare class FakePeer {
     sendAppStateSyncKeyShare(input: BuildAppStateSyncKeyShareInput, options?: SendMessageOptions): Promise<void>;
     sendGroupConversation(groupJid: string, text: string, options?: SendMessageOptions): Promise<void>;
     sendGroupMessage(groupJid: string, message: proto.IMessage, options?: SendMessageOptions): Promise<void>;
+    /**
+     * Sends a `<receipt type="retry">` stanza to the lib asking it to
+     * re-encrypt and re-send the message identified by `originalMsgId`.
+     * Used by benches / tests that exercise the lib's outbound retry
+     * replay path.
+     *
+     * Shape matches WhatsApp Web's `WAWebRetryRequestParser`:
+     * `<receipt id type=retry from t><retry id count?/><registration>4B</registration>[<keys>...</keys>]</receipt>`.
+     *
+     * When `includeKeys` is true (default), the `<keys>` block carries
+     * the peer's current identity + signed prekey + one-time prekey.
+     * This forces the lib's `WaRetryCoordinator` to tear down the
+     * existing session and re-run X3DH against these fresh keys before
+     * re-encrypting the original payload, so the resend lands as a
+     * `pkmsg` against the peer's *new* prekey state. Pair this with
+     * {@link rotateForRetry} to simulate full session loss + recovery.
+     *
+     * `<device-identity>` is omitted: it's `maybeChild` in wa-web and
+     * also optional in the lib's parser. The fake-peer fixture doesn't
+     * have an ADV primary-device to sign one, and the lib's outbound
+     * retry replay path does not require it.
+     */
+    sendRetryReceipt(originalMsgId: string, options?: {
+        readonly count?: number;
+        readonly receiptId?: string;
+        readonly t?: number;
+        readonly error?: number;
+        readonly includeKeys?: boolean;
+    }): Promise<void>;
+    private buildRetryKeysNode;
     expectMessage(options?: ExpectMessageOptions): Promise<ReceivedMessage>;
     expectGroupMessage(groupJid: string, options?: ExpectGroupMessageOptions): Promise<ReceivedMessage>;
     private decryptPairwise;
@@ -140,4 +214,3 @@ export declare class FakePeer {
     private nextId;
 }
 export {};
-//# sourceMappingURL=FakePeer.d.ts.map

package/dist/api/FakePeer.js

@@ -14,6 +14,8 @@ class FakePeer {
     constructor(keyBundle, options, deps) {
         this.ratchetInitiated = false;
         this.nextMessageCounter = 0;
+        this.sentPlaintextById = new Map();
+        this.sentEncryptedById = new Map();
         this.senderKeysByGroup = new Map();
         this.groupsBootstrapped = new Set();
         this.groupRecvSession = new fake_peer_group_recv_session_1.FakePeerGroupRecvSession();
@@ -26,6 +28,7 @@ class FakePeer {
         this.displayName = options.displayName;
         this.deps = deps;
         this.skipOneTimePreKey = options.skipOneTimePreKey === true;
+        this.replayCacheEnabled = options.enableReplayCache === true;
         this.reservedOneTimePreKey =
             !this.skipOneTimePreKey && deps.reserveOneTimePreKey
                 ? deps.reserveOneTimePreKey()
@@ -45,6 +48,18 @@ class FakePeer {
             : ciphertext;
         const enc = { type, ciphertext: finalCiphertext };
         const id = options.id ?? this.nextId();
+        if (this.replayCacheEnabled) {
+            // Stash the plaintext so the bench / a test can replay this
+            // exact payload later in response to an incoming retry
+            // receipt from the lib (replaySentMessage). Also stash the
+            // PRISTINE ciphertext (pre-tamper) + signal type so a
+            // replay can put the original frame back on the wire –
+            // matches how a real Signal sender re-sends after a
+            // recipient asks for retry: same counter + ratchet key,
+            // just an uncorrupted body.
+            this.sentPlaintextById.set(id, message);
+            this.sentEncryptedById.set(id, { type, ciphertext });
+        }
         const stanza = (0, message_1.buildMessage)({
             id,
             from: options.from ?? this.jid,
@@ -56,6 +71,76 @@ class FakePeer {
         });
         await this.deps.pushStanza(stanza);
     }
+    /**
+     * Re-encrypts and re-pushes a previously sent message identified by
+     * `originalMsgId`. Used by tests / benches that exercise the lib's
+     * incoming-retry path: after the lib emits `<receipt type="retry">`
+     * back to this peer, the peer is expected to re-send the same
+     * plaintext so the lib can decrypt it successfully on the second
+     * attempt.
+     *
+     * The replay reuses the original stanza id by default so the lib's
+     * dedup logic (and tests that wait for a specific id) see the resend
+     * as a continuation of the same outbound. Pass `resendId` to use a
+     * different id.
+     */
+    async replaySentMessage(originalMsgId, options = {}) {
+        const stored = this.sentEncryptedById.get(originalMsgId);
+        if (stored) {
+            // Re-send the pristine ciphertext – same Signal counter +
+            // ratchet key as the original send, just without the
+            // tamper. The lib's recv chain still has the message key
+            // for that counter, so this is the recovery path real
+            // WhatsApp peers walk after observing a retry receipt for
+            // a frame the recipient failed to decrypt.
+            const enc = { type: stored.type, ciphertext: stored.ciphertext };
+            const id = options.resendId ?? originalMsgId;
+            const stanza = (0, message_1.buildMessage)({
+                id,
+                from: this.jid,
+                type: 'text',
+                notify: this.displayName,
+                enc: [enc]
+            });
+            await this.deps.pushStanza(stanza);
+            return;
+        }
+        const message = this.sentPlaintextById.get(originalMsgId);
+        if (!message) {
+            throw new Error(`FakePeer.replaySentMessage: no sent plaintext for id ${originalMsgId}`);
+        }
+        await this.sendMessage(message, { id: options.resendId ?? originalMsgId });
+    }
+    /**
+     * Rotates the peer's prekey material and resets the Signal session
+     * state so the lib has to re-run X3DH on the next outbound. Keeps
+     * the identity key pair (same user) but issues a new signed prekey
+     * + new one-time prekey set. After this call:
+     *   - `keyBundle` reflects the new material;
+     *   - the underlying `FakePeerDoubleRatchet` is fresh – the next
+     *     inbound from the lib must be a `pkmsg` (initial signal
+     *     message), which the new `keyBundle` is wired to decrypt;
+     *   - any cached one-time prekey reservation in the dispenser is
+     *     dropped so subsequent retry-receipts include this peer's new
+     *     keys directly via {@link sendRetryReceipt}.
+     *
+     * Use this to simulate the "session lost" scenario that real
+     * WhatsApp clients trigger when they need the sender to fully
+     * re-bootstrap the Signal session via the retry-receipt path.
+     */
+    async rotateForRetry() {
+        const refreshed = await (0, fake_peer_key_bundle_1.generateFakePeerKeyBundle)({
+            identityKeyPair: this.keyBundle.identityKeyPair,
+            registrationId: this.keyBundle.registrationId,
+            signedPreKeyId: this.keyBundle.signedPreKey.id + 1,
+            firstOneTimePreKeyId: (this.keyBundle.oneTimePreKeys[this.keyBundle.oneTimePreKeys.length - 1]?.id ?? 0) +
+                1
+        });
+        this.keyBundle = refreshed;
+        this.ratchet = new fake_peer_double_ratchet_1.FakePeerDoubleRatchet(refreshed);
+        this.ratchetInitiated = false;
+        this.reservedOneTimePreKey = null;
+    }
     sendConversation(text, options = {}) {
         return this.sendMessage({ conversation: text }, options);
     }
@@ -234,6 +319,112 @@ class FakePeer {
         });
         await this.deps.pushStanza(groupStanza);
     }
+    /**
+     * Sends a `<receipt type="retry">` stanza to the lib asking it to
+     * re-encrypt and re-send the message identified by `originalMsgId`.
+     * Used by benches / tests that exercise the lib's outbound retry
+     * replay path.
+     *
+     * Shape matches WhatsApp Web's `WAWebRetryRequestParser`:
+     * `<receipt id type=retry from t><retry id count?/><registration>4B</registration>[<keys>...</keys>]</receipt>`.
+     *
+     * When `includeKeys` is true (default), the `<keys>` block carries
+     * the peer's current identity + signed prekey + one-time prekey.
+     * This forces the lib's `WaRetryCoordinator` to tear down the
+     * existing session and re-run X3DH against these fresh keys before
+     * re-encrypting the original payload, so the resend lands as a
+     * `pkmsg` against the peer's *new* prekey state. Pair this with
+     * {@link rotateForRetry} to simulate full session loss + recovery.
+     *
+     * `<device-identity>` is omitted: it's `maybeChild` in wa-web and
+     * also optional in the lib's parser. The fake-peer fixture doesn't
+     * have an ADV primary-device to sign one, and the lib's outbound
+     * retry replay path does not require it.
+     */
+    async sendRetryReceipt(originalMsgId, options = {}) {
+        const receiptId = options.receiptId ?? originalMsgId;
+        const retryCount = options.count ?? 1;
+        const t = options.t ?? Math.floor(Date.now() / 1000);
+        const error = options.error;
+        const includeKeys = options.includeKeys !== false;
+        const registration = new Uint8Array(4);
+        const regId = this.keyBundle.registrationId & 0xffffffff;
+        registration[0] = (regId >>> 24) & 0xff;
+        registration[1] = (regId >>> 16) & 0xff;
+        registration[2] = (regId >>> 8) & 0xff;
+        registration[3] = regId & 0xff;
+        const retryAttrs = {
+            v: '1',
+            count: String(retryCount),
+            id: originalMsgId,
+            t: String(t)
+        };
+        if (error !== undefined && error !== 0) {
+            retryAttrs.error = String(error);
+        }
+        const content = [
+            {
+                tag: 'retry',
+                attrs: retryAttrs
+            },
+            {
+                tag: 'registration',
+                attrs: {},
+                content: registration
+            }
+        ];
+        if (includeKeys) {
+            content.push(this.buildRetryKeysNode());
+        }
+        const receipt = {
+            tag: 'receipt',
+            attrs: {
+                id: receiptId,
+                from: this.jid,
+                type: 'retry',
+                t: String(t)
+            },
+            content
+        };
+        await this.deps.pushStanza(receipt);
+    }
+    buildRetryKeysNode() {
+        const skey = this.keyBundle.signedPreKey;
+        const oneTime = this.keyBundle.oneTimePreKeys[0];
+        if (!oneTime) {
+            throw new Error('FakePeer.sendRetryReceipt: no one-time prekey available');
+        }
+        const skeyIdBytes = encodeUint3(skey.id);
+        const keyIdBytes = encodeUint3(oneTime.id);
+        return {
+            tag: 'keys',
+            attrs: {},
+            content: [
+                {
+                    tag: 'identity',
+                    attrs: {},
+                    content: this.keyBundle.identityKeyPair.pubKey
+                },
+                {
+                    tag: 'skey',
+                    attrs: {},
+                    content: [
+                        { tag: 'id', attrs: {}, content: skeyIdBytes },
+                        { tag: 'value', attrs: {}, content: skey.keyPair.pubKey },
+                        { tag: 'signature', attrs: {}, content: skey.signature }
+                    ]
+                },
+                {
+                    tag: 'key',
+                    attrs: {},
+                    content: [
+                        { tag: 'id', attrs: {}, content: keyIdBytes },
+                        { tag: 'value', attrs: {}, content: oneTime.keyPair.pubKey }
+                    ]
+                }
+            ]
+        };
+    }
     expectMessage(options = {}) {
         const timeoutMs = options.timeoutMs ?? 5000;
         return new Promise((resolve, reject) => {
@@ -359,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;
@@ -395,6 +592,16 @@ function findTopLevelEnc(stanza, type) {
     }
     return null;
 }
+function encodeUint3(value) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffffff) {
+        throw new Error(`encodeUint3: value out of range: ${value}`);
+    }
+    const out = new Uint8Array(3);
+    out[0] = (value >>> 16) & 0xff;
+    out[1] = (value >>> 8) & 0xff;
+    out[2] = value & 0xff;
+    return out;
+}
 function encodePlaintextWithPadding(message) {
     const encoded = protos_1.proto.Message.encode(message).finish();
     const padLen = 16 - (encoded.byteLength % 16);
@@ -405,4 +612,3 @@ function encodePlaintextWithPadding(message) {
     }
     return out;
 }
-//# sourceMappingURL=FakePeer.js.map

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 };