@zapo-js/fake-server 1.0.0 → 1.2.0

package/dist/infra/socket-adapters.d.ts

@@ -0,0 +1,18 @@
+/** Carrier adapters: WebSocket (companion transport) and raw TCP (mobile). */
+import type { Socket } from 'node:net';
+import type { WebSocket } from 'ws';
+import type { WaFakeSocketLike } from './WaFakeConnection';
+/**
+ * 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 declare function createWebSocketAdapter(socket: WebSocket): WaFakeSocketLike;
+/**
+ * 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 declare function createTcpSocketAdapter(socket: Socket): WaFakeSocketLike;

package/dist/infra/socket-adapters.js

@@ -0,0 +1,83 @@
+"use strict";
+/** Carrier adapters: WebSocket (companion transport) and raw TCP (mobile). */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWebSocketAdapter = createWebSocketAdapter;
+exports.createTcpSocketAdapter = createTcpSocketAdapter;
+const util_1 = require("../transport/util");
+/**
+ * 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.
+ */
+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: util_1.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.
+ */
+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/protocol/auth/cert-chain.d.ts

@@ -12,6 +12,10 @@ export interface BuildFakeCertChainInput {
     readonly leafKey: Uint8Array;
     readonly intermediateSerial?: number;
     readonly leafSerial?: number;
+    /** Unix seconds. Defaults to 24h before build time. */
+    readonly notBefore?: number;
+    /** Unix seconds. Defaults to 10 years after build time. */
+    readonly notAfter?: number;
 }
 export declare function generateFakeNoiseRootCa(): Promise<FakeNoiseRootCa>;
 export declare function buildFakeCertChain(input: BuildFakeCertChainInput): Promise<FakeCertChainResult>;

package/dist/protocol/auth/cert-chain.js

@@ -5,6 +5,8 @@ exports.generateFakeNoiseRootCa = generateFakeNoiseRootCa;
 exports.buildFakeCertChain = buildFakeCertChain;
 const crypto_1 = require("../../transport/crypto");
 const protos_1 = require("../../transport/protos");
+const WA_CERT_NOT_BEFORE_BACKDATE_SECONDS = 86400;
+const WA_CERT_NOT_AFTER_LIFETIME_SECONDS = 315360000;
 async function generateFakeNoiseRootCa() {
     const keyPair = await crypto_1.X25519.generateKeyPair();
     return {
@@ -16,17 +18,26 @@ async function generateFakeNoiseRootCa() {
 async function buildFakeCertChain(input) {
     const intermediateSerial = input.intermediateSerial ?? 1;
     const leafSerial = input.leafSerial ?? 2;
+    // Strict clients (e.g. whatsmeow) enforce the validity window; leaving
+    // notBefore/notAfter unset decodes as 0 (1970) and reads as expired.
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const notBefore = input.notBefore ?? nowSeconds - WA_CERT_NOT_BEFORE_BACKDATE_SECONDS;
+    const notAfter = input.notAfter ?? nowSeconds + WA_CERT_NOT_AFTER_LIFETIME_SECONDS;
     const intermediateKeyPair = await crypto_1.X25519.generateKeyPair();
     const intermediateDetails = protos_1.proto.CertChain.NoiseCertificate.Details.encode({
         serial: intermediateSerial,
         issuerSerial: input.root.serial,
-        key: intermediateKeyPair.pubKey
+        key: intermediateKeyPair.pubKey,
+        notBefore,
+        notAfter
     }).finish();
     const intermediateSignature = await (0, crypto_1.xeddsaSign)(input.root.privateKey, intermediateDetails);
     const leafDetails = protos_1.proto.CertChain.NoiseCertificate.Details.encode({
         serial: leafSerial,
         issuerSerial: intermediateSerial,
-        key: input.leafKey
+        key: input.leafKey,
+        notBefore,
+        notAfter
     }).finish();
     const leafSignature = await (0, crypto_1.xeddsaSign)(intermediateKeyPair.privKey, leafDetails);
     const encoded = protos_1.proto.CertChain.encode({

package/dist/protocol/auth/client-payload-validate.d.ts

@@ -5,12 +5,36 @@ export interface RegistrationPayload {
     readonly raw: Proto.IClientPayload;
     readonly devicePairingData: NonNullable<Proto.IClientPayload['devicePairingData']>;
 }
+/**
+ * Transport flavor a login `ClientPayload` was built for. `web` covers the
+ * companion/WhatsApp Web payload, `mobile` the phone payload sent over the
+ * mobile TCP transport.
+ */
+export type ClientPayloadFlavor = 'web' | 'mobile';
+/** Phone identity a mobile login advertises in its `UserAgent`. */
+export interface MobileLoginDetails {
+    readonly manufacturer: string;
+    readonly device: string;
+    readonly osVersion: string;
+    readonly osBuildNumber: string;
+    /** Dotted Android app version rebuilt from the `AppVersion` message. */
+    readonly appVersion: string;
+    readonly phoneId: string;
+    readonly mcc: string;
+    readonly mnc: string;
+    readonly pushName: string | null;
+    readonly yearClass: number | null;
+    readonly memClass: number | null;
+}
 export interface LoginPayload {
     readonly kind: 'login';
     readonly raw: Proto.IClientPayload;
     readonly username: string;
     readonly device: number;
     readonly loginCounter: number;
+    readonly flavor: ClientPayloadFlavor;
+    /** Phone details for a `mobile` login; `null` for a web login. */
+    readonly mobile: MobileLoginDetails | null;
 }
 export type ParsedClientPayload = RegistrationPayload | LoginPayload;
 export declare class ClientPayloadValidationError extends Error {

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

@@ -32,14 +32,90 @@ 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 === protos_1.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/protocol/auth/pair-device.d.ts

@@ -1,8 +1,22 @@
 /** Pairing IQ builders/parsers (source: `WAWebHandlePairDevice*`, `/wa-web`). */
 import type { BinaryNode } from '../../transport/codec';
+/**
+ * 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 declare function mintPairingRefs(count?: number): Promise<string[]>;
 export interface BuildPairDeviceIqInput {
     readonly id?: string;
-    readonly refs: readonly Uint8Array[];
+    /**
+     * The six rotating refs the companion turns into a QR. The client reads
+     * them as text, so a primary-driven link (where the ref has to survive the
+     * round trip back in the primary's upload) issues printable strings.
+     */
+    readonly refs: readonly (Uint8Array | string)[];
 }
 export declare function buildPairDeviceIq(input: BuildPairDeviceIqInput): BinaryNode;
 export interface BuildPairSuccessIqInput {

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

@@ -1,10 +1,26 @@
 "use strict";
 /** Pairing IQ builders/parsers (source: `WAWebHandlePairDevice*`, `/wa-web`). */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.mintPairingRefs = mintPairingRefs;
 exports.buildPairDeviceIq = buildPairDeviceIq;
 exports.buildPairSuccessIq = buildPairSuccessIq;
 exports.parsePairingQrString = parsePairingQrString;
+const crypto_1 = require("../../transport/crypto");
 const util_1 = require("../../transport/util");
+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.
+ */
+async function mintPairingRefs(count = PAIR_DEVICE_REF_COUNT) {
+    const raw = await Promise.all(Array.from({ length: count }, () => (0, crypto_1.randomBytesAsync)(PAIR_DEVICE_REF_BYTES)));
+    return raw.map((bytes) => (0, util_1.bytesToBase64UrlSafe)(bytes));
+}
 function buildPairDeviceIq(input) {
     if (input.refs.length !== 6) {
         throw new Error(`pair-device requires exactly 6 refs, got ${input.refs.length}`);

package/dist/protocol/iq/companion-host.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 type { BinaryNode } from '../../transport/codec';
+export interface ParsedPairDeviceUpload {
+    /** Pairing ref the companion advertised in its QR. */
+    readonly ref: string;
+    readonly companionNoisePublicKey: Uint8Array;
+    /** `ADVSignedDeviceIdentityHMAC` bytes the primary signed. */
+    readonly deviceIdentityBytes: Uint8Array;
+    /** `ADVSignedKeyIndexList` bytes for the account's device set. */
+    readonly keyIndexListBytes: Uint8Array;
+    readonly keyIndexListTimestampSeconds: number;
+    /** Encoded `ClientPairingProps`, when the primary declared them. */
+    readonly clientPropsBytes: Uint8Array | null;
+    /** AES-GCM key from the optional `<pem>` element. */
+    readonly pemKeyBytes: Uint8Array | null;
+}
+/**
+ * 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 declare function parsePairDeviceUpload(iq: BinaryNode): ParsedPairDeviceUpload | null;
+export interface ParsedKeyIndexListPublish {
+    readonly keyIndexListBytes: Uint8Array;
+    readonly timestampSeconds: number;
+}
+/**
+ * Parses the standalone key-index-list republish the primary sends whenever its
+ * companion set changes. Returns `null` when the stanza carries no list.
+ */
+export declare function parseKeyIndexListPublish(iq: BinaryNode): ParsedKeyIndexListPublish | null;
+export interface ParsedRemoveCompanionDevice {
+    /** Device to unlink; `null` when the stanza revokes every companion. */
+    readonly deviceJid: string | null;
+    /** `all="true"` – the phone's "log out all companion devices". */
+    readonly all: boolean;
+    readonly reason: string;
+    readonly excludeHostedCompanion: boolean;
+}
+/**
+ * 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 declare function parseRemoveCompanionDevice(iq: BinaryNode): ParsedRemoveCompanionDevice | null;

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

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePairDeviceUpload = parsePairDeviceUpload;
+exports.parseKeyIndexListPublish = parseKeyIndexListPublish;
+exports.parseRemoveCompanionDevice = parseRemoveCompanionDevice;
+const util_1 = require("../../transport/util");
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ */
+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 ? util_1.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'));
+}

package/dist/protocol/iq/link-code.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Link-code (pairing-code) relay stanzas.
+ *
+ * The handshake runs between two clients with the server in the middle: the
+ * companion asks for a code (`companion_hello`), the primary answers with its
+ * wrapped ephemeral (`primary_hello`), and the companion closes with the key
+ * bundle (`companion_finish`). Each stage arrives as an IQ from one client and
+ * leaves as a notification to the other; the server only routes and mints the
+ * ref that ties the three together.
+ */
+import type { BinaryNode } from '../../transport/codec';
+export type LinkCodeStage = 'companion_hello' | 'primary_hello' | 'companion_finish';
+export interface ParsedLinkCodeStanza {
+    readonly stage: LinkCodeStage;
+    /** Account the companion wants to link to, on the stages that carry it. */
+    readonly phoneJid: string | null;
+    /** Ref the stage refers to; absent on `companion_hello`, which mints it. */
+    readonly ref: string | null;
+    /** The stage's payload elements, relayed verbatim to the other client. */
+    readonly children: readonly BinaryNode[];
+}
+/**
+ * Parses a `<link_code_companion_reg>` IQ. Returns `null` for a stage this
+ * server does not relay (for example `get_country_code`), letting the router
+ * fall through to another handler.
+ */
+export declare function parseLinkCodeStanza(iq: BinaryNode): ParsedLinkCodeStanza | null;
+/**
+ * Builds the `companion_hello` IQ result carrying the ref the server minted.
+ * The companion keys its whole pairing session off it.
+ */
+export declare function buildCompanionHelloResultContent(ref: string): BinaryNode[];
+export interface BuildLinkCodeNotificationInput {
+    readonly stage: LinkCodeStage;
+    readonly ref: string;
+    /** Payload elements copied from the originating stanza. */
+    readonly children: readonly BinaryNode[];
+    readonly id?: string;
+    readonly to?: string;
+}
+/**
+ * Wraps a relayed stage as the notification the receiving client handles. The
+ * ref is (re)stamped so the receiver can match it against its pairing session,
+ * replacing any copy carried by the source stanza.
+ */
+export declare function buildLinkCodeNotification(input: BuildLinkCodeNotificationInput): BinaryNode;

package/dist/protocol/iq/link-code.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * Link-code (pairing-code) relay stanzas.
+ *
+ * The handshake runs between two clients with the server in the middle: the
+ * companion asks for a code (`companion_hello`), the primary answers with its
+ * wrapped ephemeral (`primary_hello`), and the companion closes with the key
+ * bundle (`companion_finish`). Each stage arrives as an IQ from one client and
+ * leaves as a notification to the other; the server only routes and mints the
+ * ref that ties the three together.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseLinkCodeStanza = parseLinkCodeStanza;
+exports.buildCompanionHelloResultContent = buildCompanionHelloResultContent;
+exports.buildLinkCodeNotification = buildLinkCodeNotification;
+const util_1 = require("../../transport/util");
+const RELAYED_STAGES = new Set([
+    'companion_hello',
+    'primary_hello',
+    'companion_finish'
+]);
+/**
+ * Parses a `<link_code_companion_reg>` IQ. Returns `null` for a stage this
+ * server does not relay (for example `get_country_code`), letting the router
+ * fall through to another handler.
+ */
+function parseLinkCodeStanza(iq) {
+    const node = findChild(iq, 'link_code_companion_reg');
+    const stage = node?.attrs.stage;
+    if (!node || typeof stage !== 'string' || !RELAYED_STAGES.has(stage)) {
+        return null;
+    }
+    const jid = node.attrs.jid;
+    return {
+        stage: stage,
+        phoneJid: typeof jid === 'string' && jid.length > 0 ? jid : null,
+        ref: readText(findChild(node, 'link_code_pairing_ref')),
+        children: Array.isArray(node.content) ? node.content : []
+    };
+}
+/**
+ * Builds the `companion_hello` IQ result carrying the ref the server minted.
+ * The companion keys its whole pairing session off it.
+ */
+function buildCompanionHelloResultContent(ref) {
+    return [
+        {
+            tag: 'link_code_companion_reg',
+            attrs: { stage: 'companion_hello' },
+            content: [{ tag: 'link_code_pairing_ref', attrs: {}, content: ref }]
+        }
+    ];
+}
+/**
+ * Wraps a relayed stage as the notification the receiving client handles. The
+ * ref is (re)stamped so the receiver can match it against its pairing session,
+ * replacing any copy carried by the source stanza.
+ */
+function buildLinkCodeNotification(input) {
+    const children = input.children.filter((child) => child.tag !== 'link_code_pairing_ref');
+    return {
+        tag: 'notification',
+        attrs: {
+            id: input.id ?? `link-code-${Math.random().toString(36).slice(2, 10)}`,
+            from: 's.whatsapp.net',
+            type: 'link_code_companion_reg',
+            ...(input.to !== undefined ? { to: input.to } : {})
+        },
+        content: [
+            {
+                tag: 'link_code_companion_reg',
+                attrs: { stage: input.stage },
+                content: [
+                    { tag: 'link_code_pairing_ref', attrs: {}, content: input.ref },
+                    ...children
+                ]
+            }
+        ]
+    };
+}
+function findChild(parent, tag) {
+    if (!Array.isArray(parent.content)) {
+        return null;
+    }
+    return parent.content.find((child) => child.tag === tag) ?? null;
+}
+function readText(node) {
+    if (!node) {
+        return null;
+    }
+    if (typeof node.content === 'string') {
+        return node.content;
+    }
+    return node.content instanceof Uint8Array ? util_1.TEXT_DECODER.decode(node.content) : null;
+}