@zapo-js/fake-server 1.0.0 → 1.2.0

package/dist/api/FakeServerSession.js

@@ -0,0 +1,355 @@
+"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 fake_companion_host_1 = require("../state/fake-companion-host");
+const AppStateSyncManager_1 = require("./AppStateSyncManager");
+const iq_handlers_1 = require("./iq-handlers");
+const PreKeyDispenser_1 = require("./PreKeyDispenser");
+const ServerRegistries_1 = require("./ServerRegistries");
+const HOST_DOMAIN = 's.whatsapp.net';
+/**
+ * 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.companionHost = new fake_companion_host_1.FakeCompanionHostState();
+        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, context) {
+        return this.iqRouter.route(iq, context);
+    }
+    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;
+        const companionHost = this.companionHost;
+        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(),
+            get mobilePrimary() {
+                return companionHost.primary;
+            },
+            relayLinkCodeStage: (iq, context) => host.relayLinkCodeStage(iq, context),
+            linkCompanionDevice: (upload) => this.linkCompanionDevice(host, upload),
+            revokeCompanionDevices: (deviceJids) => this.revokeCompanionDevices(deviceJids),
+            recordKeyIndexList: (bytes, timestampSeconds) => companionHost.recordKeyIndexList(bytes, timestampSeconds)
+        };
+    }
+    /**
+     * Server side of the primary's `pair-device` upload: allocates the device
+     * slot, hands the signed identity to the companion connection, and records
+     * the link. Resolves `null` when this session has no primary or the ref
+     * belongs to no live connection, which the handler turns into an IQ error.
+     */
+    async linkCompanionDevice(host, upload) {
+        const primary = this.companionHost.primary;
+        if (!primary) {
+            return null;
+        }
+        const deviceId = this.companionHost.allocateDeviceId();
+        const deviceJid = `${primary.username}:${deviceId}@${HOST_DOMAIN}`;
+        const completed = await host
+            .completeCompanionPairing({
+            ref: upload.ref,
+            deviceJid,
+            deviceIdentityBytes: upload.deviceIdentityBytes
+        })
+            .catch((error) => {
+            this.companionHost.releaseDeviceId(deviceId);
+            throw error;
+        });
+        if (!completed) {
+            this.companionHost.releaseDeviceId(deviceId);
+            return null;
+        }
+        this.companionHost.recordCompanion({
+            deviceJid,
+            deviceId,
+            ref: upload.ref,
+            keyIndex: (0, fake_companion_host_1.readCompanionKeyIndex)(upload.deviceIdentityBytes),
+            deviceIdentityBytes: upload.deviceIdentityBytes,
+            linkedAtSeconds: Math.floor(Date.now() / 1000)
+        });
+        this.companionHost.recordKeyIndexList(upload.keyIndexListBytes, upload.keyIndexListTimestampSeconds);
+        this.registries.registerDeviceId(primary.jid, deviceId);
+        return { deviceJid, companionPropsBytes: completed.companionPropsBytes };
+    }
+    revokeCompanionDevices(deviceJids) {
+        const removed = deviceJids
+            ? this.companionHost.removeCompanions(deviceJids)
+            : this.companionHost.removeAllCompanions();
+        const primary = this.companionHost.primary;
+        if (primary) {
+            for (const deviceJid of removed) {
+                this.registries.unregisterDeviceId(primary.jid, (0, ServerRegistries_1.toDeviceIdPart)(deviceJid));
+            }
+        }
+        return removed;
+    }
+}
+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';
+}

package/dist/api/FakeWaServer.d.ts

@@ -1,5 +1,7 @@
 import { Agent as HttpsAgent } from 'node:https';
 import { type WaFakeAuthenticatedInfo, WaFakeConnectionPipeline } from '../infra/WaFakeConnectionPipeline';
+import type { ParsedClientPayload } from '../protocol/auth/client-payload-validate';
+import type { BuildSuccessNodeInput } from '../protocol/auth/success-node';
 import type { BuildAbPropsResultInput } from '../protocol/iq/abprops';
 import { type BuildServerSyncNotificationInput, type FakeAppStateCollectionPayload } from '../protocol/iq/appstate-sync';
 import type { FakeBusinessProfile } from '../protocol/iq/business';
@@ -7,41 +9,72 @@ import type { FakePrivacyCategoryName, FakePrivacySettingsState } from '../proto
 import type { FakePrivacyTokenIssue } from '../protocol/iq/privacy-token';
 import type { FakeProfilePictureResult } from '../protocol/iq/profile';
 import { type WaFakeIqMatcher, type WaFakeIqResponder } from '../protocol/iq/router';
+import { type FakeAccountDevice } from '../protocol/push/mobile-notification';
 import type { ClientPreKeyBundle } from '../protocol/signal/prekey-upload';
+import type { FakeCompanionHostState } from '../state/fake-companion-host';
 import { type PublishedMediaBlob, type PublishMediaInput } from '../state/fake-media-store';
 import { type BinaryNode } from '../transport/codec';
-import { AppStateSyncManager, type CapturedAppStateMutation } from './AppStateSyncManager';
+import { type AppStateSyncManager, type CapturedAppStateMutation } from './AppStateSyncManager';
 import { type FakePairingDriverOptions } from './FakePairingDriver';
 import { type CreateFakePeerOptions, FakePeer } from './FakePeer';
-import { PreKeyDispenser } from './PreKeyDispenser';
+import { type ExpectIqOptions, type ExpectStanzaOptions, FakeServerSession, type StanzaMatcher } from './FakeServerSession';
+import type { PreKeyDispenser } from './PreKeyDispenser';
 import { type AuthenticatedPipelineListener, Scenario } from './Scenario';
-import { type CapturedBlocklistChange, type CapturedDirtyBitsClear, type CapturedGroupOp, type CapturedPrivacySet, type CapturedProfilePictureSet, type CapturedStatusSet, type FakeGroupMetadata, ServerRegistries } from './ServerRegistries';
+import type { CapturedBlocklistChange, CapturedDirtyBitsClear, CapturedGroupOp, CapturedPrivacySet, CapturedProfilePictureSet, CapturedStatusSet, FakeGroupMetadata, ServerRegistries } from './ServerRegistries';
 export type { FakeGroupMetadata, CapturedGroupOp, CapturedPrivacySet, CapturedBlocklistChange, CapturedProfilePictureSet, CapturedStatusSet, CapturedDirtyBitsClear } from './ServerRegistries';
 export type { CapturedAppStateMutation } from './AppStateSyncManager';
 export interface FakeWaServerOptions {
     readonly host?: string;
     readonly port?: number;
     readonly path?: string;
+    /**
+     * Attributes stamped on the post-handshake `<success/>` node of every
+     * authenticated connection (lid, display name, props versions, ...).
+     */
+    readonly successNodeAttributes?: BuildSuccessNodeInput;
+    /**
+     * Register the built-in IQ auto-handlers that answer everything the lib
+     * emits during normal operation. Default `true`; pass `false` to start
+     * with an empty router and wire every response via `registerIqHandler`.
+     */
+    readonly defaultIqHandlers?: boolean;
+    /**
+     * Assigns each authenticated connection to an isolated session, keyed by
+     * the returned id. Two connections that resolve to different ids share no
+     * peers, groups, prekeys, app-state, or captured stanzas. When omitted,
+     * every connection uses one shared default session (single-client mode).
+     *
+     * The resolver runs once per connection, right after authentication, so
+     * `info.clientPayload` is available for keying by login identity, e.g.
+     * `sessionKey: ({ clientPayload }) => clientPayload.kind === 'login' ?
+     * clientPayload.username : 'pending'`.
+     */
+    readonly sessionKey?: (info: FakeSessionKeyInfo) => string;
+    /**
+     * Also serve the WhatsApp Mobile transport on a raw TCP listener. Mobile
+     * clients dial `tcp://host:port` instead of upgrading to a WebSocket, but
+     * speak the same framing above the carrier, so both listeners share one
+     * server identity, session model, and IQ router. Pass `true` for an
+     * ephemeral port on the WebSocket host, or an object to pin host/port.
+     * Read the address back from {@link FakeWaServer.tcpUrl} and feed it to the
+     * client's `mobileTransport.tcpUrl`.
+     */
+    readonly tcp?: boolean | {
+        readonly host?: string;
+        readonly port?: number;
+    };
+}
+export interface FakeSessionKeyInfo {
+    readonly clientPayload: ParsedClientPayload;
+    readonly pipeline: WaFakeConnectionPipeline;
 }
 export interface FakeWaServerNoiseRootCa {
     readonly publicKey: Uint8Array;
     readonly serial: number;
 }
 export type FakeWaServerPipelineListener = (pipeline: WaFakeConnectionPipeline) => void;
-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;
-}
+export { FakeServerSession } from './FakeServerSession';
+export type { ExpectIqOptions, ExpectStanzaOptions, StanzaMatcher } from './FakeServerSession';
 export interface CapturedMediaUpload {
     readonly path: string;
     readonly mediaType: string;
@@ -51,22 +84,23 @@ export interface CapturedMediaUpload {
     readonly receivedAtMs: number;
 }
 export declare class FakeWaServer {
-    readonly registries: ServerRegistries;
-    readonly preKeyDispenser: PreKeyDispenser;
-    readonly appStateSync: AppStateSyncManager;
     private readonly wsServer;
     private readonly pipelines;
-    private readonly iqRouter;
-    private readonly capturedStanzas;
-    private readonly pendingIqExpectations;
-    private readonly pendingStanzaExpectations;
+    private readonly defaultSession;
+    private readonly pipelineSessions;
     private readonly authenticatedListeners;
-    private readonly inboundStanzaListeners;
-    private readonly capturedStanzaListeners;
+    private readonly sessions;
+    private readonly globalIqHandlers;
+    private readonly options;
     private rootCa;
     private serverStaticKeyPair;
     private listenInfo;
-    private pipelineListener;
+    private readonly tcpServer;
+    private tcpListenInfo;
+    private readonly pendingCompanionOffers;
+    private readonly mobilePrimaryPipelines;
+    private readonly linkCodeSessions;
+    private readonly pipelineListeners;
     private rejectMode;
     private readonly mediaStore;
     private readonly mediaHttpsServer;
@@ -74,7 +108,22 @@ export declare class FakeWaServer {
     private nextUploadCounter;
     private cachedMediaProxyAgent;
     constructor(options?: FakeWaServerOptions);
-    private buildIqHandlerDeps;
+    /** State of the single default session (the only session for one client). */
+    get registries(): ServerRegistries;
+    /** Companion-host account state of the default session (linked devices, key-index list). */
+    get companionHost(): FakeCompanionHostState;
+    get preKeyDispenser(): PreKeyDispenser;
+    get appStateSync(): AppStateSyncManager;
+    /**
+     * Returns the isolated session for `id`, creating it on first use. Every
+     * session gets its own registries, prekey dispenser, app-state, IQ router,
+     * and stanza capture. Use with the `sessionKey` option to run several
+     * `WaClient`s against one server without them sharing any state.
+     */
+    session(id: string): FakeServerSession;
+    /** The session a connection is bound to (default before authentication). */
+    sessionFor(pipeline: WaFakeConnectionPipeline): FakeServerSession;
+    private createSession;
     registerIqHandler(matcher: WaFakeIqMatcher, respond: WaFakeIqResponder, label?: string): () => void;
     routeIqForTest(iq: BinaryNode): Promise<BinaryNode | null>;
     onOutboundGroupOp(listener: (op: CapturedGroupOp) => void): () => void;
@@ -119,18 +168,26 @@ export declare class FakeWaServer {
     expectAppStateMutation(predicate: (mutation: CapturedAppStateMutation) => boolean, timeoutMs?: number): Promise<CapturedAppStateMutation>;
     provideAppStateCollection(name: string, provider: () => Promise<FakeAppStateCollectionPayload | null> | FakeAppStateCollectionPayload | null): () => void;
     pushServerSyncNotification(pipeline: WaFakeConnectionPipeline, input: BuildServerSyncNotificationInput): Promise<void>;
+    /**
+     * Pushes the account's device set to a mobile primary as `account_sync`.
+     * Defaults to what this session tracks - the primary itself plus every
+     * companion it linked - so passing a shorter list is how a test tells the
+     * primary that a device disappeared while it was offline.
+     */
+    pushAccountSyncDevices(pipeline: WaFakeConnectionPipeline, options?: {
+        readonly devices?: readonly FakeAccountDevice[];
+    }): Promise<void>;
     onAuthenticatedPipeline(listener: AuthenticatedPipelineListener): () => void;
     scenario(configure: (s: Scenario) => void): void;
     expectIq(matcher: WaFakeIqMatcher, options?: ExpectIqOptions): Promise<BinaryNode>;
     capturedStanzaSnapshot(): readonly BinaryNode[];
     /**
-     * Subscribes to every stanza captured from the client side (the lib).
-     * The listener is called synchronously for each new stanza as it
-     * arrives, in addition to `capturedStanzas` being appended. Returns
-     * an unsubscribe function. Useful for benches that need to count or
-     * react to a stream of receipts/messages without paying the O(N²)
-     * cost of polling `capturedStanzaSnapshot()` or queuing one
-     * `expectStanza(...)` per iteration.
+     * Subscribes to every stanza captured from the client side (the lib) of
+     * the default session. The listener is called synchronously for each new
+     * stanza as it arrives. Returns an unsubscribe function. Useful for
+     * benches that need to count or react to a stream of receipts/messages
+     * without paying the O(N²) cost of polling `capturedStanzaSnapshot()` or
+     * queuing one `expectStanza(...)` per iteration.
      */
     onCapturedStanza(listener: (node: BinaryNode) => void): () => void;
     expectStanza(matcher: StanzaMatcher, options?: ExpectStanzaOptions): Promise<BinaryNode>;
@@ -162,12 +219,63 @@ export declare class FakeWaServer {
     get url(): string;
     get host(): string;
     get port(): number;
+    /**
+     * `tcp://host:port` of the mobile listener, for the client's
+     * `mobileTransport.tcpUrl`.
+     *
+     * @throws when the server was started without the `tcp` option.
+     */
+    get tcpUrl(): string;
     get noiseRootCa(): FakeWaServerNoiseRootCa;
-    onPipeline(listener: FakeWaServerPipelineListener): void;
+    /**
+     * Subscribes to every new connection pipeline (pre-auth). Listeners
+     * fan out; returns an unsubscribe function.
+     */
+    onPipeline(listener: FakeWaServerPipelineListener): () => void;
     listen(): Promise<void>;
+    private rollbackFailedListen;
     stop(): Promise<void>;
     private handleConnection;
-    private handleCapturedStanza;
+    /**
+     * Rebinds a connection to its keyed session once authenticated. Runs
+     * before user `onAuthenticated` listeners and before any client stanza, so
+     * captures and IQ routing land in the right session from the first frame.
+     * No-op without a `sessionKey` resolver (single default session).
+     */
+    private bindPipelineSession;
+    /** Drops every reference to a closed connection so a relay never targets it. */
+    private forgetPipeline;
+    /**
+     * Records a phone login as the session's account owner. Everything on the
+     * companion-host path keys off it: device jids are minted under its number,
+     * and `remove-companion-device` is read as a revoke rather than a logout.
+     */
+    private bindMobilePrimary;
+    /**
+     * Offers a companion connection the refs for a primary-driven link: pushes
+     * the `pair-device` IQ it turns into a QR, and remembers each ref so the
+     * primary's upload can be routed back to this connection. Returns the refs.
+     *
+     * This is the counterpart of {@link runPairing}, where the server itself
+     * plays the primary. Here a real mobile-primary client signs the identity
+     * and the server only relays.
+     */
+    offerCompanionPairing(pipeline: WaFakeConnectionPipeline, options?: {
+        readonly refCount?: number;
+    }): Promise<readonly string[]>;
+    /**
+     * Relays one link-code stage between the two clients running the pairing
+     * handshake. `companion_hello` mints the ref that ties the stages together
+     * and registers it as a pairing offer, so the primary's later `pair-device`
+     * upload lands on the same companion connection as the QR flow.
+     */
+    private handleLinkCodeStage;
+    /**
+     * Host side of a companion link: hands the primary-signed identity to the
+     * connection that owns `ref` and reports what that companion advertised at
+     * registration. Resolves `null` for an unknown or already-consumed ref.
+     */
+    private completeCompanionPairing;
     private buildMediaRequestHandler;
     private handleMediaUpload;
     private requireListening;