@zapo-js/fake-server 1.1.0 → 1.2.0

package/dist/esm/api/FakeServerSession.js

@@ -1,9 +1,11 @@
 /** Per-session isolated server state: registries, prekeys, app-state, IQ routing, capture. */
 import { WaFakeIqRouter } from '../protocol/iq/router.js';
+import { FakeCompanionHostState, readCompanionKeyIndex } from '../state/fake-companion-host.js';
 import { AppStateSyncManager } from './AppStateSyncManager.js';
 import { registerDefaultIqHandlers } from './iq-handlers.js';
 import { PreKeyDispenser } from './PreKeyDispenser.js';
-import { ServerRegistries } from './ServerRegistries.js';
+import { ServerRegistries, toDeviceIdPart } from './ServerRegistries.js';
+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,
@@ -16,6 +18,7 @@ export class FakeServerSession {
         this.registries = new ServerRegistries();
         this.preKeyDispenser = new PreKeyDispenser();
         this.appStateSync = new AppStateSyncManager();
+        this.companionHost = new FakeCompanionHostState();
         this.iqRouter = new WaFakeIqRouter();
         this.capturedStanzas = [];
         this.pendingIqExpectations = new Set();
@@ -31,8 +34,8 @@ export class FakeServerSession {
         const handler = { matcher, respond, label };
         return this.iqRouter.register(handler, { priority: 'high' });
     }
-    routeIq(iq) {
-        return this.iqRouter.route(iq);
+    routeIq(iq, context) {
+        return this.iqRouter.route(iq, context);
     }
     handleCapturedStanza(node) {
         this.capturedStanzas.push(node);
@@ -148,6 +151,7 @@ export class FakeServerSession {
         const reg = this.registries;
         const preKey = this.preKeyDispenser;
         const appState = this.appStateSync;
+        const companionHost = this.companionHost;
         return {
             get peerRegistry() {
                 return reg.peerRegistry;
@@ -215,9 +219,67 @@ export class FakeServerSession {
             get appStateCollectionProviders() {
                 return appState.appStateCollectionProviders;
             },
-            requireMediaHttpsInfo: () => host.requireMediaHttpsInfo()
+            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: 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, toDeviceIdPart(deviceJid));
+            }
+        }
+        return removed;
+    }
 }
 export function matchesIq(iq, matcher) {
     if (iq.tag !== 'iq')

package/dist/esm/api/FakeWaServer.js

@@ -1,14 +1,35 @@
 import { Agent as HttpsAgent } from 'node:https';
 import { WaFakeConnectionPipeline } from '../infra/WaFakeConnectionPipeline.js';
 import { WaFakeMediaHttpsServer } from '../infra/WaFakeMediaHttpsServer.js';
+import { WaFakeTcpServer } from '../infra/WaFakeTcpServer.js';
 import { WaFakeWsServer } from '../infra/WaFakeWsServer.js';
 import { generateFakeNoiseRootCa } from '../protocol/auth/cert-chain.js';
+import { buildPairDeviceIq, buildPairSuccessIq, mintPairingRefs } from '../protocol/auth/pair-device.js';
+import { buildCompanionHelloResultContent, buildLinkCodeNotification, parseLinkCodeStanza } from '../protocol/iq/link-code.js';
+import { buildIqError, buildIqResult } from '../protocol/iq/router.js';
+import { buildAccountSyncDevicesNotification } from '../protocol/push/mobile-notification.js';
 import { FakeMediaStore } from '../state/fake-media-store.js';
 import { X25519 } from '../transport/crypto.js';
 import { FakePairingDriver } from './FakePairingDriver.js';
 import { FakePeer } from './FakePeer.js';
 import { FakeServerSession } from './FakeServerSession.js';
 import { Scenario } from './Scenario.js';
+const HOST_DOMAIN = 's.whatsapp.net';
+const MOBILE_PRIMARY_PLATFORM = 'android';
+/**
+ * Builds the mobile TCP listener when the option asks for one. Defaults its
+ * host to the WebSocket host so both listeners answer on the same interface.
+ */
+function createTcpServer(options) {
+    if (!options.tcp) {
+        return null;
+    }
+    const config = options.tcp === true ? {} : options.tcp;
+    return new WaFakeTcpServer({
+        host: config.host ?? options.host,
+        port: config.port
+    });
+}
 export { FakeServerSession } from './FakeServerSession.js';
 export class FakeWaServer {
     constructor(options = {}) {
@@ -20,6 +41,10 @@ export class FakeWaServer {
         this.rootCa = null;
         this.serverStaticKeyPair = null;
         this.listenInfo = null;
+        this.tcpListenInfo = null;
+        this.pendingCompanionOffers = new Map();
+        this.mobilePrimaryPipelines = new Map();
+        this.linkCodeSessions = new Map();
         this.pipelineListeners = new Set();
         this.rejectMode = null;
         this.mediaStore = new FakeMediaStore();
@@ -30,12 +55,18 @@ export class FakeWaServer {
         this.options = options;
         this.wsServer = new WaFakeWsServer(options);
         this.wsServer.onConnection((connection) => this.handleConnection(connection));
+        this.tcpServer = createTcpServer(options);
+        this.tcpServer?.onConnection((connection) => this.handleConnection(connection));
         this.defaultSession = this.createSession('__default__');
     }
     /** State of the single default session (the only session for one client). */
     get registries() {
         return this.defaultSession.registries;
     }
+    /** Companion-host account state of the default session (linked devices, key-index list). */
+    get companionHost() {
+        return this.defaultSession.companionHost;
+    }
     get preKeyDispenser() {
         return this.defaultSession.preKeyDispenser;
     }
@@ -60,7 +91,11 @@ export class FakeWaServer {
         return this.pipelineSessions.get(pipeline) ?? this.defaultSession;
     }
     createSession(id) {
-        const session = new FakeServerSession(id, { requireMediaHttpsInfo: () => this.requireMediaHttpsInfo() }, { defaultIqHandlers: this.options.defaultIqHandlers !== false });
+        const session = new FakeServerSession(id, {
+            requireMediaHttpsInfo: () => this.requireMediaHttpsInfo(),
+            completeCompanionPairing: (input) => this.completeCompanionPairing(input),
+            relayLinkCodeStage: (iq, context) => this.handleLinkCodeStage(iq, context)
+        }, { defaultIqHandlers: this.options.defaultIqHandlers !== false });
         this.sessions.set(id, session);
         // Server-level custom handlers apply to every session, present and future.
         for (const handler of this.globalIqHandlers) {
@@ -177,6 +212,27 @@ export class FakeWaServer {
     async pushServerSyncNotification(pipeline, input) {
         return this.sessionFor(pipeline).appStateSync.pushServerSyncNotification(pipeline, input);
     }
+    /**
+     * 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.
+     */
+    async pushAccountSyncDevices(pipeline, options = {}) {
+        const session = this.sessionFor(pipeline);
+        const primary = session.companionHost.primary;
+        if (!primary && !options.devices) {
+            throw new Error('cannot push account_sync: this session has no mobile primary');
+        }
+        const devices = options.devices ?? [
+            { deviceJid: primary.jid, keyIndex: 0 },
+            ...session.companionHost.linkedCompanions().map((companion) => ({
+                deviceJid: companion.deviceJid,
+                keyIndex: companion.keyIndex
+            }))
+        ];
+        await pipeline.sendStanza(buildAccountSyncDevicesNotification({ devices }));
+    }
     onAuthenticatedPipeline(listener) {
         this.authenticatedListeners.add(listener);
         return () => this.authenticatedListeners.delete(listener);
@@ -340,6 +396,18 @@ export class FakeWaServer {
     get port() {
         return this.requireListening().port;
     }
+    /**
+     * `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() {
+        if (!this.tcpListenInfo) {
+            throw new Error('fake server has no mobile listener; start it with { tcp: true } to serve the mobile transport');
+        }
+        return this.tcpListenInfo.url;
+    }
     get noiseRootCa() {
         const root = this.requireRootCa();
         return { publicKey: root.publicKey, serial: root.serial };
@@ -367,11 +435,35 @@ export class FakeWaServer {
         this.wsServer.setHttpRequestHandler(mediaHandler);
         this.mediaHttpsServer.setRequestHandler(mediaHandler);
         this.listenInfo = await this.wsServer.listen();
-        await this.mediaHttpsServer.listen('127.0.0.1');
+        try {
+            if (this.tcpServer) {
+                this.tcpListenInfo = await this.tcpServer.listen();
+            }
+            await this.mediaHttpsServer.listen('127.0.0.1');
+        }
+        catch (error) {
+            // A half-open server is worse than none: the listeners that did
+            // come up would stay bound and `listenInfo` would make a retry a
+            // no-op. Roll everything back so the caller can start over.
+            await this.rollbackFailedListen();
+            throw error;
+        }
+    }
+    async rollbackFailedListen() {
+        const ignore = () => undefined;
+        await this.wsServer.close().catch(ignore);
+        await this.tcpServer?.close().catch(ignore);
+        await this.mediaHttpsServer.close().catch(ignore);
+        this.listenInfo = null;
+        this.tcpListenInfo = null;
+        this.rootCa = null;
+        this.serverStaticKeyPair = null;
     }
     async stop() {
         this.pipelines.clear();
         await this.wsServer.close();
+        await this.tcpServer?.close();
+        this.tcpListenInfo = null;
         await this.mediaHttpsServer.close();
         if (this.cachedMediaProxyAgent) {
             this.cachedMediaProxyAgent.destroy();
@@ -394,7 +486,7 @@ export class FakeWaServer {
             connection,
             rootCa: this.rootCa,
             serverStaticKeyPair: this.serverStaticKeyPair,
-            routeIq: (node) => this.sessionFor(pipeline).routeIq(node),
+            routeIq: (node) => this.sessionFor(pipeline).routeIq(node, { connection: pipeline }),
             ...(this.options.successNodeAttributes !== undefined
                 ? { successNodeAttributes: this.options.successNodeAttributes }
                 : {})
@@ -404,6 +496,7 @@ export class FakeWaServer {
         pipeline.setEvents({
             onAuthenticated: () => {
                 this.bindPipelineSession(pipeline);
+                this.bindMobilePrimary(pipeline);
                 for (const listener of this.authenticatedListeners) {
                     try {
                         void Promise.resolve(listener(pipeline)).catch(() => undefined);
@@ -414,7 +507,7 @@ export class FakeWaServer {
                 }
             },
             onStanza: (node) => this.sessionFor(pipeline).handleCapturedStanza(node),
-            onClose: () => this.pipelines.delete(pipeline)
+            onClose: () => this.forgetPipeline(pipeline)
         });
         for (const listener of this.pipelineListeners) {
             try {
@@ -440,6 +533,139 @@ export class FakeWaServer {
         const id = resolveKey({ clientPayload, pipeline });
         this.pipelineSessions.set(pipeline, this.session(id));
     }
+    /** Drops every reference to a closed connection so a relay never targets it. */
+    forgetPipeline(pipeline) {
+        this.pipelines.delete(pipeline);
+        for (const [ref, offered] of this.pendingCompanionOffers) {
+            if (offered === pipeline) {
+                this.pendingCompanionOffers.delete(ref);
+            }
+        }
+        for (const [jid, primary] of this.mobilePrimaryPipelines) {
+            if (primary === pipeline) {
+                this.mobilePrimaryPipelines.delete(jid);
+            }
+        }
+        for (const [ref, session] of this.linkCodeSessions) {
+            if (session.companion === pipeline || session.primary === pipeline) {
+                this.linkCodeSessions.delete(ref);
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    bindMobilePrimary(pipeline) {
+        const clientPayload = pipeline.clientPayload;
+        if (clientPayload?.kind !== 'login' || clientPayload.flavor !== 'mobile') {
+            return;
+        }
+        const session = this.sessionFor(pipeline);
+        const jid = `${clientPayload.username}@${HOST_DOMAIN}`;
+        session.companionHost.bindPrimary({ username: clientPayload.username, jid });
+        if (session.companionHost.primary?.jid !== jid) {
+            // The session already belongs to another number. Wiring this login
+            // in anyway would let a link be relayed to this connection and then
+            // minted under the account that owns the session.
+            return;
+        }
+        session.registries.registerDeviceId(jid, 0);
+        // A reconnect of the same account replaces its stale connection here.
+        this.mobilePrimaryPipelines.set(jid, pipeline);
+    }
+    /**
+     * 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.
+     */
+    async offerCompanionPairing(pipeline, options = {}) {
+        const refs = await mintPairingRefs(options.refCount);
+        // Send before registering: the builder rejects a bad ref count and the
+        // send can fail, and either would leave refs in the map that no
+        // connection will ever consume.
+        await pipeline.sendStanza(buildPairDeviceIq({ refs }));
+        for (const ref of refs) {
+            this.pendingCompanionOffers.set(ref, pipeline);
+        }
+        return refs;
+    }
+    /**
+     * 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.
+     */
+    async handleLinkCodeStage(iq, context) {
+        const parsed = parseLinkCodeStanza(iq);
+        if (!parsed || !context) {
+            return null;
+        }
+        const sender = context.connection;
+        if (parsed.stage === 'companion_hello') {
+            const primary = parsed.phoneJid
+                ? this.mobilePrimaryPipelines.get(parsed.phoneJid)
+                : undefined;
+            if (!primary) {
+                return buildIqError(iq, { code: 404, text: 'primary-not-connected' });
+            }
+            const [ref] = await mintPairingRefs(1);
+            this.linkCodeSessions.set(ref, { companion: sender, primary });
+            this.pendingCompanionOffers.set(ref, sender);
+            await primary.sendStanza(buildLinkCodeNotification({
+                stage: 'companion_hello',
+                ref,
+                children: parsed.children
+            }));
+            return buildIqResult(iq, { content: buildCompanionHelloResultContent(ref) });
+        }
+        const session = parsed.ref ? this.linkCodeSessions.get(parsed.ref) : undefined;
+        if (!session || !parsed.ref) {
+            return buildIqError(iq, { code: 404, text: 'unknown-pairing-ref' });
+        }
+        const target = parsed.stage === 'primary_hello' ? session.companion : session.primary;
+        await target.sendStanza(buildLinkCodeNotification({
+            stage: parsed.stage,
+            ref: parsed.ref,
+            children: parsed.children
+        }));
+        return buildIqResult(iq);
+    }
+    /**
+     * 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.
+     */
+    async completeCompanionPairing(input) {
+        const pipeline = this.pendingCompanionOffers.get(input.ref);
+        if (!pipeline) {
+            return null;
+        }
+        const registration = pipeline.clientPayload;
+        const companionPropsBytes = registration?.kind === 'registration'
+            ? (registration.devicePairingData.deviceProps ?? null)
+            : null;
+        // `<platform>` describes the primary that signed the link, not the
+        // companion. A zapo mobile session always logs in as ANDROID, so this
+        // is the only value a primary-driven link can carry here.
+        const platform = MOBILE_PRIMARY_PLATFORM;
+        await pipeline.sendStanza(buildPairSuccessIq({
+            deviceJid: input.deviceJid,
+            platform,
+            deviceIdentityBytes: input.deviceIdentityBytes
+        }));
+        for (const [ref, offered] of this.pendingCompanionOffers) {
+            if (offered === pipeline) {
+                this.pendingCompanionOffers.delete(ref);
+            }
+        }
+        return { companionPropsBytes, platform };
+    }
     buildMediaRequestHandler() {
         return (req, res) => {
             const rawUrl = req.url ?? '';

package/dist/esm/api/ServerRegistries.js

@@ -186,16 +186,31 @@ export class ServerRegistries {
     }
     registerPeer(peer) {
         this.peerRegistry.set(peer.jid, peer);
-        const userJid = toUserJidPart(peer.jid);
-        const deviceId = toDeviceIdPart(peer.jid);
+        this.registerDeviceId(toUserJidPart(peer.jid), toDeviceIdPart(peer.jid));
+    }
+    /**
+     * Makes a device visible to `usync` without minting a full fake peer – used
+     * for the primary's own device set, whose companions are real clients with
+     * their own keys rather than server-side fakes.
+     */
+    registerDeviceId(userJid, deviceId) {
         const ids = this.deviceIdsByUser.get(userJid);
-        if (ids) {
+        if (!ids) {
+            this.deviceIdsByUser.set(userJid, [deviceId]);
+            return;
+        }
+        if (!ids.includes(deviceId)) {
             ids.push(deviceId);
             ids.sort((a, b) => a - b);
         }
-        else {
-            this.deviceIdsByUser.set(userJid, [deviceId]);
+    }
+    unregisterDeviceId(userJid, deviceId) {
+        const ids = this.deviceIdsByUser.get(userJid);
+        if (!ids) {
+            return;
         }
+        const next = ids.filter((id) => id !== deviceId);
+        this.deviceIdsByUser.set(userJid, next);
     }
     lookupDeviceIdsForUser(userJid) {
         return this.deviceIdsByUser.get(userJid) ?? [];

package/dist/esm/api/iq-handlers.js

@@ -2,6 +2,7 @@
 import { buildAbPropsResult } from '../protocol/iq/abprops.js';
 import { buildAppStateSyncFullResult, buildAppStateSyncResult, parseAppStateSyncRequest } from '../protocol/iq/appstate-sync.js';
 import { buildBusinessProfileResult, parseGetBusinessProfileIq } from '../protocol/iq/business.js';
+import { parseKeyIndexListPublish, parsePairDeviceUpload, parseRemoveCompanionDevice } from '../protocol/iq/companion-host.js';
 import { parseClearDirtyBitsIq } from '../protocol/iq/dirty-bits.js';
 import { buildGroupMetadataNode, buildGroupParticipantChangeResult, parseCreateGroupIq, parseGroupParticipantChangeIq, parseLeaveGroupIq, parseSetDescriptionIq, parseSetSubjectIq } from '../protocol/iq/group-ops.js';
 import { buildNewsletterMyAddonsResult } from '../protocol/iq/newsletter.js';
@@ -73,6 +74,28 @@ function buildGroupMetadataReply(iq, metadata) {
         ]
     };
 }
+/**
+ * True when the stanza arrived on the phone that owns this session's account.
+ * Being a phone login is not enough: a second number connecting to the same
+ * session must not drive the companion set of the account that owns it.
+ */
+function isSessionOwnerConnection(context, deps) {
+    const payload = context?.connection.clientPayload;
+    if (payload?.kind !== 'login' || payload.flavor !== 'mobile') {
+        return false;
+    }
+    return deps.mobilePrimary?.username === payload.username;
+}
+/** The device jid a connection speaks for, or `null` before it logs in. */
+function ownDeviceJid(context) {
+    const payload = context?.connection.clientPayload;
+    if (payload?.kind !== 'login') {
+        return null;
+    }
+    return payload.device > 0
+        ? `${payload.username}:${payload.device}@s.whatsapp.net`
+        : `${payload.username}@s.whatsapp.net`;
+}
 export function registerDefaultIqHandlers(router, deps) {
     router.register({
         label: 'prekey-upload',
@@ -244,10 +267,82 @@ export function registerDefaultIqHandlers(router, deps) {
         matcher: { xmlns: 'encrypt', type: 'set', childTag: 'rotate' },
         respond: (iq) => buildIqResult(iq)
     });
+    router.register({
+        label: 'link-code-companion-reg',
+        matcher: { xmlns: 'md', type: 'set', childTag: 'link_code_companion_reg' },
+        respond: (iq, context) => deps.relayLinkCodeStage(iq, context)
+    });
+    router.register({
+        label: 'companion-pair-device',
+        matcher: { xmlns: 'md', type: 'set', childTag: 'pair-device' },
+        respond: async (iq, context) => {
+            const upload = parsePairDeviceUpload(iq);
+            if (!upload) {
+                return buildIqError(iq, { code: 400, text: 'invalid-pair-device' });
+            }
+            // The link is minted under the account that owns the session, so
+            // only that account's phone may ask for one.
+            if (!isSessionOwnerConnection(context, deps)) {
+                return buildIqError(iq, { code: 403, text: 'not-authorized' });
+            }
+            const linked = await deps.linkCompanionDevice(upload);
+            if (!linked) {
+                return buildIqError(iq, { code: 404, text: 'unknown-pairing-ref' });
+            }
+            // Shape mirrors the phone's parser: <device jid> is a direct child
+            // of the result, with the companion's own props beside it.
+            const content = [{ tag: 'device', attrs: { jid: linked.deviceJid } }];
+            if (linked.companionPropsBytes) {
+                content.push({
+                    tag: 'companion-props',
+                    attrs: {},
+                    content: linked.companionPropsBytes
+                });
+            }
+            return buildIqResult(iq, { content });
+        }
+    });
+    router.register({
+        label: 'companion-key-index-list',
+        matcher: { xmlns: 'md', type: 'set', childTag: 'key-index-list' },
+        respond: (iq, context) => {
+            const published = parseKeyIndexListPublish(iq);
+            if (!published) {
+                return buildIqError(iq, { code: 400, text: 'invalid-key-index-list' });
+            }
+            if (!isSessionOwnerConnection(context, deps)) {
+                return buildIqError(iq, { code: 403, text: 'not-authorized' });
+            }
+            deps.recordKeyIndexList(published.keyIndexListBytes, published.timestampSeconds);
+            return buildIqResult(iq);
+        }
+    });
     router.register({
         label: 'remove-companion-device',
         matcher: { xmlns: 'md', type: 'set', childTag: 'remove-companion-device' },
-        respond: (iq) => {
+        respond: (iq, context) => {
+            const removal = parseRemoveCompanionDevice(iq);
+            // The same stanza means "log me out" from a companion and "unlink
+            // that device" from a primary. The wire does not say which, but the
+            // connection does: the account's own phone is always revoking
+            // someone else's device, and never ends its own session this way.
+            if (removal && isSessionOwnerConnection(context, deps)) {
+                if (!removal.all) {
+                    deps.revokeCompanionDevices(removal.deviceJid ? [removal.deviceJid] : []);
+                }
+                else if (!removal.excludeHostedCompanion) {
+                    // The hosted set is exactly what this session tracks, so
+                    // sparing it leaves the registry untouched.
+                    deps.revokeCompanionDevices(null);
+                }
+                return buildIqResult(iq);
+            }
+            // Anyone else may only unlink itself: a connection that is not the
+            // account's phone must never drop someone else's device. Its own
+            // session ends either way.
+            if (removal?.deviceJid && removal.deviceJid === ownDeviceJid(context)) {
+                deps.revokeCompanionDevices([removal.deviceJid]);
+            }
             deps.notifyLogout();
             return buildIqResult(iq);
         }

package/dist/esm/index.js

@@ -1,8 +1,16 @@
+export { createFakeMobilePrimary, seedFakeMobilePrimary } from './api/FakeMobilePrimary.js';
 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 { WaFakeTcpServer } from './infra/WaFakeTcpServer.js';
+export { createTcpSocketAdapter, createWebSocketAdapter } from './infra/socket-adapters.js';
+export { ClientPayloadValidationError, parseClientPayload } from './protocol/auth/client-payload-validate.js';
+export { parseKeyIndexListPublish, parsePairDeviceUpload, parseRemoveCompanionDevice } from './protocol/iq/companion-host.js';
+export { buildCompanionHelloResultContent, buildLinkCodeNotification, parseLinkCodeStanza } from './protocol/iq/link-code.js';
+export { buildAccountSyncDevicesNotification, buildAccountTakeoverNotice, buildRegistrationCodeNotification } from './protocol/push/mobile-notification.js';
+export { FakeCompanionHostState, readCompanionKeyIndex } from './state/fake-companion-host.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';

package/dist/esm/infra/WaFakeConnection.js

@@ -4,7 +4,14 @@ export class WaFakeConnection {
         this.currentState = 'open';
         this.id = id;
         this.socket = socket;
-        this.bindSocketEvents();
+        this.socket.listen({
+            onFrame: (frame) => this.handlers.onFrame?.(frame),
+            onClose: (info) => {
+                this.currentState = 'closed';
+                this.handlers.onClose?.(info);
+            },
+            onError: (error) => this.handlers.onError?.(error)
+        });
     }
     get state() {
         return this.currentState;
@@ -25,25 +32,4 @@ export class WaFakeConnection {
         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);
-        });
-    }
 }