@zapo-js/fake-server 1.1.0 → 1.3.0

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

package/dist/esm/infra/WaFakeConnectionPipeline.js

@@ -10,17 +10,20 @@ import { WaFakeNoiseHandshake } from './WaFakeNoiseHandshake.js';
 import { WaFakeTransport } from './WaFakeTransport.js';
 const NOISE_XX_NAME = new TextEncoder().encode('Noise_XX_25519_AESGCM_SHA256\0\0\0\0');
 const NOISE_IK_NAME = new TextEncoder().encode('Noise_IK_25519_AESGCM_SHA256\0\0\0\0');
-const PROLOGUE = new Uint8Array([0x57, 0x41, 0x06, 0x03]);
+const PROLOGUE_MAGIC_W = 0x57;
+const PROLOGUE_MAGIC_A = 0x41;
+const DEFAULT_PROLOGUE = new Uint8Array([PROLOGUE_MAGIC_W, PROLOGUE_MAGIC_A, 0x06, 0x03]);
 export class WaFakeConnectionPipeline {
     constructor(config) {
         this.events = {};
         this.state = { kind: 'awaiting_prologue' };
         this.chain = Promise.resolve();
         this.authenticatedPayload = null;
+        this.clientPrologue = DEFAULT_PROLOGUE;
         this.config = config;
         this.frameSocket = new WaFakeFrameSocket(config.connection);
         this.frameSocket.setHandlers({
-            onPrologue: () => this.onPrologue(),
+            onPrologue: (prologue) => this.onPrologue(prologue),
             onFrame: (frame) => this.scheduleFrame(frame),
             onClose: (info) => {
                 this.state = { kind: 'closed' };
@@ -48,11 +51,20 @@ export class WaFakeConnectionPipeline {
         const ciphertext = await this.state.transport.encryptFrame(stanza);
         this.frameSocket.sendFrame(ciphertext);
     }
-    onPrologue() {
+    onPrologue(prologue) {
         if (this.state.kind !== 'awaiting_prologue') {
             this.events.onError?.(new Error('received second prologue from client'));
             return;
         }
+        // Mix back the header the client actually sent instead of a fixed one:
+        // it is hashed into the handshake, and a client is free to advertise a
+        // protocol/dict version other than the web client's 6/3.
+        this.clientPrologue = new Uint8Array([
+            PROLOGUE_MAGIC_W,
+            PROLOGUE_MAGIC_A,
+            prologue.protocolVersion,
+            prologue.dictVersion
+        ]);
         this.state = { kind: 'awaiting_client_hello' };
     }
     scheduleFrame(frame) {
@@ -94,7 +106,7 @@ export class WaFakeConnectionPipeline {
     }
     async handleXxClientHello(clientEphemeralPub) {
         const handshake = new WaFakeNoiseHandshake();
-        handshake.start(NOISE_XX_NAME, PROLOGUE);
+        handshake.start(NOISE_XX_NAME, this.clientPrologue);
         handshake.authenticate(clientEphemeralPub);
         const serverEphemeral = await X25519.generateKeyPair();
         handshake.authenticate(serverEphemeral.pubKey);
@@ -130,7 +142,7 @@ export class WaFakeConnectionPipeline {
         const encryptedClientStatic = clientHello.static;
         const encryptedClientPayload = clientHello.payload;
         const handshake = new WaFakeNoiseHandshake();
-        handshake.start(NOISE_IK_NAME, PROLOGUE);
+        handshake.start(NOISE_IK_NAME, this.clientPrologue);
         handshake.authenticate(this.config.serverStaticKeyPair.pubKey);
         handshake.authenticate(clientEphemeralPub);
         handshake.mixIntoKey(await X25519.scalarMult(this.config.serverStaticKeyPair.privKey, clientEphemeralPub));

package/dist/esm/infra/WaFakeTcpServer.js

@@ -0,0 +1,69 @@
+import { createServer } from 'node:net';
+import { createTcpSocketAdapter } from './socket-adapters.js';
+import { WaFakeConnection } from './WaFakeConnection.js';
+/**
+ * Raw-TCP listener for the WhatsApp Mobile transport. The mobile client dials
+ * `tcp://host:port` instead of upgrading to a WebSocket, but speaks the exact
+ * same prologue + length-prefixed frames on top, so every layer above the
+ * carrier is shared with {@link WaFakeWsServer}.
+ */
+export class WaFakeTcpServer {
+    constructor(options = {}) {
+        this.server = null;
+        this.connectionListener = null;
+        this.sockets = new Set();
+        this.nextConnectionId = 0;
+        this.options = {
+            host: options.host ?? '127.0.0.1',
+            port: options.port ?? 0
+        };
+    }
+    onConnection(listener) {
+        this.connectionListener = listener;
+    }
+    async listen() {
+        if (this.server) {
+            throw new Error('fake tcp server is already listening');
+        }
+        const server = createServer((socket) => {
+            this.sockets.add(socket);
+            socket.on('close', () => this.sockets.delete(socket));
+            const id = `t${this.nextConnectionId++}`;
+            this.connectionListener?.(new WaFakeConnection(id, createTcpSocketAdapter(socket)));
+        });
+        await new Promise((resolve, reject) => {
+            const onError = (error) => {
+                server.off('listening', onListening);
+                reject(error);
+            };
+            const onListening = () => {
+                server.off('error', onError);
+                resolve();
+            };
+            server.once('error', onError);
+            server.once('listening', onListening);
+            server.listen(this.options.port, this.options.host);
+        });
+        this.server = server;
+        const address = server.address();
+        return {
+            host: address.address,
+            port: address.port,
+            url: `tcp://${address.address}:${address.port}`
+        };
+    }
+    async close() {
+        const server = this.server;
+        if (!server) {
+            return;
+        }
+        for (const socket of this.sockets) {
+            socket.destroy();
+        }
+        this.sockets.clear();
+        await new Promise((resolve, reject) => {
+            server.close((error) => (error ? reject(error) : resolve()));
+        });
+        this.server = null;
+    }
+}

package/dist/esm/infra/WaFakeWsServer.js

@@ -1,5 +1,6 @@
 import { createServer } from 'node:http';
 import { WebSocketServer } from 'ws';
+import { createWebSocketAdapter } from './socket-adapters.js';
 import { WaFakeConnection } from './WaFakeConnection.js';
 export class WaFakeWsServer {
     constructor(options = {}) {
@@ -49,7 +50,7 @@ export class WaFakeWsServer {
         const wsServer = new WebSocketServer({ server: httpServer, path: this.options.path });
         wsServer.on('connection', (socket) => {
             const id = `c${this.nextConnectionId++}`;
-            const connection = new WaFakeConnection(id, socket);
+            const connection = new WaFakeConnection(id, createWebSocketAdapter(socket));
             this.connectionListener?.(connection);
         });
         await new Promise((resolve, reject) => {

package/dist/esm/infra/socket-adapters.js

@@ -0,0 +1,79 @@
+/** Carrier adapters: WebSocket (companion transport) and raw TCP (mobile). */
+import { TEXT_DECODER } from '../transport/util.js';
+/**
+ * Adapts a `ws` socket to {@link WaFakeSocketLike}. Owns the two WebSocket
+ * quirks the rest of the server should not know about: a message can arrive as
+ * a fragment array, and a text frame is a protocol violation here because every
+ * WhatsApp frame is binary.
+ */
+export function createWebSocketAdapter(socket) {
+    return {
+        send: (frame) => socket.send(frame),
+        close: (code, reason) => socket.close(code, reason),
+        listen: (events) => {
+            socket.on('message', (data, isBinary) => {
+                if (!isBinary) {
+                    events.onError(new Error('received unexpected text frame'));
+                    return;
+                }
+                events.onFrame(toFrameBytes(data));
+            });
+            socket.on('close', (code, reason) => {
+                events.onClose({ code, reason: TEXT_DECODER.decode(reason) });
+            });
+            socket.on('error', (error) => {
+                events.onError(error);
+            });
+        }
+    };
+}
+/**
+ * Adapts a Node TCP socket to {@link WaFakeSocketLike} for the mobile
+ * transport. A TCP stream has no message boundaries and no close codes: every
+ * chunk is forwarded as-is (the frame codec above reassembles them) and the
+ * code/reason the server asked for is replayed when the socket finally closes.
+ */
+export function createTcpSocketAdapter(socket) {
+    let closeCode = 1000;
+    let closeReason = '';
+    return {
+        send: (frame) => {
+            socket.write(frame);
+        },
+        close: (code, reason) => {
+            closeCode = code;
+            closeReason = reason;
+            socket.end();
+        },
+        listen: (events) => {
+            socket.on('data', (chunk) => {
+                events.onFrame(chunk);
+            });
+            socket.on('close', () => {
+                events.onClose({ code: closeCode, reason: closeReason });
+            });
+            socket.on('error', (error) => {
+                events.onError(error);
+            });
+        }
+    };
+}
+function toFrameBytes(data) {
+    if (data instanceof Uint8Array) {
+        return data;
+    }
+    if (data instanceof ArrayBuffer) {
+        return new Uint8Array(data);
+    }
+    let total = 0;
+    for (const part of data) {
+        total += part.byteLength;
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const part of data) {
+        out.set(part, offset);
+        offset += part.byteLength;
+    }
+    return out;
+}

package/dist/esm/protocol/auth/client-payload-validate.js

@@ -27,14 +27,90 @@ export function parseClientPayload(bytes) {
     if (raw.username === undefined || raw.username === null) {
         throw new ClientPayloadValidationError('missing_username', 'login ClientPayload is missing the username field');
     }
+    const flavor = resolveLoginFlavor(raw);
     return {
         kind: 'login',
         raw,
         username: String(raw.username),
         device: typeof raw.device === 'number' ? raw.device : 0,
-        loginCounter: typeof raw.lc === 'number' ? raw.lc : 0
+        loginCounter: typeof raw.lc === 'number' ? raw.lc : 0,
+        flavor,
+        mobile: flavor === 'mobile' ? parseMobileDetails(raw) : null
     };
 }
+/**
+ * Resolves the transport flavor of a login payload. `webInfo` and the `WEB`
+ * platform mark a companion; a phone is identified by the device fields only
+ * the mobile payload carries. Sniffing those fields (rather than the platform
+ * enum alone) is deliberate: `ANDROID` is the zero value of the enum, so a
+ * payload that omits `platform` entirely would otherwise read as mobile.
+ */
+function resolveLoginFlavor(raw) {
+    if (raw.webInfo) {
+        return 'web';
+    }
+    const userAgent = raw.userAgent;
+    if (!userAgent || userAgent.platform === proto.ClientPayload.UserAgent.Platform.WEB) {
+        return 'web';
+    }
+    return userAgent.manufacturer && userAgent.device ? 'mobile' : 'web';
+}
+function parseMobileDetails(raw) {
+    const userAgent = raw.userAgent;
+    if (!userAgent) {
+        throw new ClientPayloadValidationError('missing_field', 'mobile login ClientPayload is missing the userAgent');
+    }
+    const required = [
+        ['manufacturer', 'device manufacturer'],
+        ['device', 'device model'],
+        ['osVersion', 'os version'],
+        ['osBuildNumber', 'os build number'],
+        ['phoneId', 'phone id']
+    ];
+    for (const [field, label] of required) {
+        const value = userAgent[field];
+        if (value === undefined || value === null || value === '') {
+            throw new ClientPayloadValidationError('missing_field', `mobile login ClientPayload missing ${label} (userAgent.${String(field)})`);
+        }
+    }
+    const appVersion = userAgent.appVersion;
+    if (!appVersion || appVersion.primary === undefined || appVersion.primary === null) {
+        throw new ClientPayloadValidationError('missing_field', 'mobile login ClientPayload missing the app version (userAgent.appVersion)');
+    }
+    return {
+        manufacturer: String(userAgent.manufacturer),
+        device: String(userAgent.device),
+        osVersion: String(userAgent.osVersion),
+        osBuildNumber: String(userAgent.osBuildNumber),
+        appVersion: formatAppVersion(appVersion),
+        phoneId: String(userAgent.phoneId),
+        mcc: userAgent.mcc ? String(userAgent.mcc) : '000',
+        mnc: userAgent.mnc ? String(userAgent.mnc) : '000',
+        pushName: typeof raw.pushName === 'string' ? raw.pushName : null,
+        yearClass: toOptionalNumber(raw.yearClass),
+        memClass: toOptionalNumber(raw.memClass)
+    };
+}
+function formatAppVersion(version) {
+    const parts = [
+        version.primary,
+        version.secondary,
+        version.tertiary,
+        version.quaternary,
+        version.quinary
+    ];
+    const present = [];
+    for (const part of parts) {
+        if (part === undefined || part === null) {
+            break;
+        }
+        present.push(Number(part));
+    }
+    return present.join('.');
+}
+function toOptionalNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
 function validateRegistrationFields(devicePairingData) {
     const required = [
         ['eIdent', 'identity public key'],

package/dist/esm/protocol/auth/pair-device.js

@@ -1,5 +1,20 @@
 /** Pairing IQ builders/parsers (source: `WAWebHandlePairDevice*`, `/wa-web`). */
-import { decodeBase64Url } from '../../transport/util.js';
+import { randomBytesAsync } from '../../transport/crypto.js';
+import { bytesToBase64UrlSafe, decodeBase64Url } from '../../transport/util.js';
+const PAIR_DEVICE_REF_COUNT = 6;
+const PAIR_DEVICE_REF_BYTES = 16;
+/**
+ * Mints the rotating refs a `pair-device` push carries.
+ *
+ * They are printable on purpose. A client reads `<ref>` as text and pastes it
+ * into a comma-separated QR payload, so raw random bytes can decode into a
+ * comma or a newline and quietly corrupt whatever reads that payload back -
+ * including the primary that has to echo the ref in its upload.
+ */
+export async function mintPairingRefs(count = PAIR_DEVICE_REF_COUNT) {
+    const raw = await Promise.all(Array.from({ length: count }, () => randomBytesAsync(PAIR_DEVICE_REF_BYTES)));
+    return raw.map((bytes) => bytesToBase64UrlSafe(bytes));
+}
 export function buildPairDeviceIq(input) {
     if (input.refs.length !== 6) {
         throw new Error(`pair-device requires exactly 6 refs, got ${input.refs.length}`);

package/dist/esm/protocol/iq/companion-host.js

@@ -0,0 +1,104 @@
+/**
+ * Primary-side `md` IQ parsers: a phone hosting companion devices.
+ *
+ * These are the inverse of `protocol/auth/pair-device.ts`, which drives the
+ * companion side. Here the client is the primary: it signs a companion's device
+ * identity and uploads it, republishes its key-index list, and revokes devices.
+ */
+import { TEXT_DECODER } from '../../transport/util.js';
+/**
+ * Parses the primary's `<iq type="set" xmlns="md"><pair-device>` upload.
+ * Returns `null` when the stanza is not a well-formed pair-device upload, which
+ * lets the router fall through to another handler.
+ */
+export function parsePairDeviceUpload(iq) {
+    const pairDevice = findChild(iq, 'pair-device');
+    if (!pairDevice) {
+        return null;
+    }
+    const ref = readText(findChild(pairDevice, 'ref'));
+    const companionNoisePublicKey = readBytes(findChild(pairDevice, 'pub-key'));
+    const deviceIdentityBytes = readBytes(findChild(pairDevice, 'device-identity'));
+    const keyIndexList = findChild(pairDevice, 'key-index-list');
+    const keyIndexListBytes = readBytes(keyIndexList);
+    if (!ref || !companionNoisePublicKey || !deviceIdentityBytes || !keyIndexListBytes) {
+        return null;
+    }
+    return {
+        ref,
+        companionNoisePublicKey,
+        deviceIdentityBytes,
+        keyIndexListBytes,
+        keyIndexListTimestampSeconds: readTimestampSeconds(keyIndexList),
+        clientPropsBytes: readBytes(findChild(pairDevice, 'client-props')),
+        pemKeyBytes: readPemKey(pairDevice)
+    };
+}
+/**
+ * Parses the standalone key-index-list republish the primary sends whenever its
+ * companion set changes. Returns `null` when the stanza carries no list.
+ */
+export function parseKeyIndexListPublish(iq) {
+    const keyIndexList = findChild(iq, 'key-index-list');
+    const keyIndexListBytes = readBytes(keyIndexList);
+    if (!keyIndexListBytes) {
+        return null;
+    }
+    return {
+        keyIndexListBytes,
+        timestampSeconds: readTimestampSeconds(keyIndexList)
+    };
+}
+/**
+ * Parses `<remove-companion-device>`. The same stanza serves a companion
+ * logging itself out (`jid` = its own device) and a primary unlinking one of
+ * its companions, so the caller decides by comparing against the connection's
+ * own jid.
+ */
+export function parseRemoveCompanionDevice(iq) {
+    const remove = findChild(iq, 'remove-companion-device');
+    if (!remove) {
+        return null;
+    }
+    const jid = remove.attrs.jid;
+    return {
+        deviceJid: typeof jid === 'string' && jid.length > 0 ? jid : null,
+        all: remove.attrs.all === 'true',
+        reason: typeof remove.attrs.reason === 'string' ? remove.attrs.reason : '',
+        excludeHostedCompanion: remove.attrs.exclude_hosted_companion === 'true'
+    };
+}
+function findChild(parent, tag) {
+    if (!Array.isArray(parent.content)) {
+        return null;
+    }
+    return parent.content.find((child) => child.tag === tag) ?? null;
+}
+function readBytes(node) {
+    if (!node) {
+        return null;
+    }
+    return node.content instanceof Uint8Array ? node.content : null;
+}
+function readText(node) {
+    if (!node) {
+        return null;
+    }
+    if (typeof node.content === 'string') {
+        return node.content;
+    }
+    return node.content instanceof Uint8Array ? TEXT_DECODER.decode(node.content) : null;
+}
+function readTimestampSeconds(node) {
+    const raw = node?.attrs.ts;
+    const parsed = typeof raw === 'string' ? Number.parseInt(raw, 10) : Number.NaN;
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+/** The `<pem>` wrapper nests the key bytes in a second `<pem>` element. */
+function readPemKey(pairDevice) {
+    const pem = findChild(pairDevice, 'pem');
+    if (!pem) {
+        return null;
+    }
+    return readBytes(findChild(pem, 'pem'));
+}