@ardennguyen/zalo-agent-cli 2.5.9 → 3.0.0

package/src/zalo/listener/dispatch.js

@@ -0,0 +1,404 @@
+/**
+ * The chat socket's decoded payloads -> the typed events the engine subscribes to.
+ *
+ * Routing follows Zalo's socket handler families (agent/docs/zca-replace/spec-listener.md 3, "Routing"): one chat path
+ * for the message pushes, one control path for the controls and reactions, one action path for typing. Each
+ * function here takes one frame's decoded `data` and returns the steps the listener carries out, in order:
+ *
+ *   {emit: name, args: [...]}                       emit one event
+ *   {settle: {fileId, url, kind, fileUrl, control}}   an upload the server finished (a 601 control)
+ *   {error: Error}                                  one item of the frame could not be read
+ *
+ * An item that cannot be read costs that item only: the rest of the frame is still read (each reaction and each
+ * control is parsed on its own; the previous engine lost every item after a bad one).
+ *
+ * Pure functions apart from the documented in-place rewrites of the message objects (./models.js): no socket, no
+ * output, nothing logged.
+ */
+import { friendControlEvent } from "./friend-events.js";
+import { groupControlEvent } from "./group-events.js";
+import {
+    GroupDeliveredMessage,
+    GroupMessage,
+    GroupSeenMessage,
+    GroupTyping,
+    Reaction,
+    Undo,
+    UserDeliveredMessage,
+    UserMessage,
+    UserSeenMessage,
+    UserTyping,
+    isRecall,
+} from "./models.js";
+
+/** Thread types, as the engine reads them (0 a 1-1 conversation, 1 a group). */
+const USER = 0;
+const GROUP = 1;
+
+/**
+ * Chat pushes read through one path, any of which may carry messages, receipts and read state: the live
+ * pushes 501 (1-1), 521 (group), 502/522 (receipts), the mixed offline push 504 and 524, 570, the server re-push
+ * 534, and the Signal pushes 551 (1-1), 552 (group) and 535 (missed), which are decrypted first and then read the
+ * same way.
+ */
+export const CHAT_PUSH_CMDS = Object.freeze([501, 521, 502, 522, 504, 524, 570, 534, 551, 552, 535]);
+
+/** The two old-message queue answers (subCmd 1): `old_messages`, with no recall split. */
+export const OLD_MESSAGE_CMDS = Object.freeze({ 510: USER, 511: GROUP });
+
+/** The control push this listener reads controls from. 603 pages reach it replayed as 601 (src/core/control-replay.js). */
+export const CMD_CONTROL = 601;
+
+/** The live reaction push. */
+export const CMD_REACTIONS = 612;
+
+/** The old-reaction queue answers: 610 for 1-1 conversations, 611 for groups. */
+export const OLD_REACTION_CMDS = Object.freeze({ 610: false, 611: true });
+
+/** The action push (typing, file sending, online status). */
+export const CMD_ACTIONS = 602;
+
+/** Control kinds that settle an upload: the file, video and photo forms of "the server has the file". */
+export const UPLOAD_ACT_TYPES = Object.freeze(["file_done", "video_done", "photo_success"]);
+
+/**
+ * Every cmd this module turns into events. Anything else reaches the raw taps only.
+ *
+ * @param {number} cmd
+ * @param {number} subCmd
+ * @returns {boolean}
+ */
+export function isDispatched(cmd, subCmd) {
+    if (CHAT_PUSH_CMDS.includes(cmd)) return true;
+    if (Object.hasOwn(OLD_MESSAGE_CMDS, cmd)) return subCmd === 1;
+    return cmd === CMD_CONTROL || cmd === CMD_REACTIONS || cmd === CMD_ACTIONS || Object.hasOwn(OLD_REACTION_CMDS, cmd);
+}
+
+/** An array field of a payload, or an empty list. */
+const listOf = (data, key) => (Array.isArray(data?.[key]) ? data[key] : []);
+
+/**
+ * True for a message of an end-to-end encrypted type (`chat.e2ee.*`): its content is ciphertext this client, which
+ * has no Signal stack, cannot open.
+ *
+ * @param {object} msg
+ * @returns {boolean}
+ */
+export function isE2eeMessage(msg) {
+    return typeof msg?.msgType === "string" && /(^|\.)e2ee(\.|$)/i.test(msg.msgType);
+}
+
+/**
+ * Keep an unreadable end-to-end encrypted message out of every text store (design 6.1 item 7): it is still
+ * announced, marked `undecryptable`, with its ciphertext removed from `content`.
+ *
+ * @param {object} msg - rewritten in place
+ */
+function markUndecryptable(msg) {
+    msg.undecryptable = true;
+    msg.content = "";
+}
+
+/**
+ * One pushed message (or recall) as its event step.
+ *
+ * @param {string} uid
+ * @param {object} msg
+ * @param {boolean} isGroup
+ * @returns {{emit: string, args: unknown[]}}
+ */
+function pushedMessage(uid, msg, isGroup) {
+    if (isE2eeMessage(msg)) markUndecryptable(msg);
+    if (isRecall(msg)) return { emit: "undo", args: [new Undo(uid, msg, isGroup)] };
+    return { emit: "message", args: [isGroup ? new GroupMessage(uid, msg) : new UserMessage(uid, msg)] };
+}
+
+/**
+ * Run `make` for one item; a throw becomes an error step naming what was being read and the kind of failure. The
+ * failure itself rides along as `cause` (its text varies by Node version and can quote the payload, so it is not
+ * part of the message).
+ */
+function guarded(out, what, make) {
+    try {
+        const step = make();
+        if (step) out.push(step);
+    } catch (e) {
+        out.push({ error: new Error(`${what}: one item not readable (${e?.name ?? "Error"})`, { cause: e }) });
+    }
+}
+
+/**
+ * A chat push: every message list, then the receipts (the order the engine has always had: messages in array order, delivered before
+ * seen). `pageMsgs` (page and official-account conversations) are 1-1 conversations to the engine.
+ *
+ * @param {string} uid - the own uid
+ * @param {number} cmd
+ * @param {object} data - the decoded payload's `data`
+ * @returns {object[]} steps
+ */
+export function dispatchChat(uid, cmd, data) {
+    const out = [];
+    const lists = [
+        ["msgs", false],
+        ["groupMsgs", true],
+        ["pageMsgs", false],
+    ];
+    for (const [key, isGroup] of lists) {
+        for (const msg of listOf(data, key)) guarded(out, `cmd ${cmd} ${key}`, () => pushedMessage(uid, msg, isGroup));
+    }
+
+    // 502 is the 1-1 receipt push and 522 the group one; in a mixed push an entry with a group id is a group's.
+    const groupDelivered = (d) => (cmd === 522 ? true : cmd === 502 ? false : d?.groupId !== undefined);
+    const delivered = [];
+    for (const d of listOf(data, "delivereds")) {
+        guarded(delivered, `cmd ${cmd} delivereds`, () =>
+            groupDelivered(d) ? new GroupDeliveredMessage(uid, d) : new UserDeliveredMessage(d),
+        );
+    }
+    const seen = [];
+    for (const d of listOf(data, "seens")) guarded(seen, `cmd ${cmd} seens`, () => new UserSeenMessage(d));
+    for (const d of listOf(data, "groupSeens")) {
+        guarded(seen, `cmd ${cmd} groupSeens`, () => new GroupSeenMessage(uid, d));
+    }
+    for (const [name, items] of [
+        ["delivered_messages", delivered],
+        ["seen_messages", seen],
+    ]) {
+        const objects = items.filter((s) => !s.error);
+        out.push(...items.filter((s) => s.error));
+        if (objects.length) out.push({ emit: name, args: [objects] });
+    }
+    return out;
+}
+
+/**
+ * An old-message queue answer (510/1, 511/1): `old_messages(list, threadType)`, recalls left in the list as
+ * messages (the history writers drop them as removals). Nothing is emitted when the answer has no message list.
+ *
+ * @param {string} uid
+ * @param {number} cmd - 510 or 511
+ * @param {object} data
+ * @returns {object[]} steps
+ */
+export function dispatchOldMessages(uid, cmd, data) {
+    const type = OLD_MESSAGE_CMDS[cmd];
+    const key = type === GROUP ? "groupMsgs" : "msgs";
+    if (!Array.isArray(data?.[key])) return [];
+    const out = [];
+    const objects = [];
+    for (const msg of data[key]) {
+        guarded(out, `cmd ${cmd} ${key}`, () => {
+            objects.push(type === GROUP ? new GroupMessage(uid, msg) : new UserMessage(uid, msg));
+            return null;
+        });
+    }
+    out.push({ emit: "old_messages", args: [objects, type] });
+    return out;
+}
+
+/**
+ * Reactions of a control frame: each `content` parsed from JSON on its own, a reaction whose content does not parse
+ * skipped with an error step.
+ *
+ * @param {string} uid
+ * @param {number} cmd
+ * @param {object} data
+ * @returns {object[]} steps
+ */
+function reactionSteps(uid, cmd, data) {
+    const out = [];
+    for (const [key, isGroup] of [
+        ["reacts", false],
+        ["reactGroups", true],
+    ]) {
+        for (const r of listOf(data, key)) {
+            guarded(out, `cmd ${cmd} ${key}`, () => {
+                if (typeof r.content === "string") r.content = JSON.parse(r.content);
+                return { emit: "reaction", args: [new Reaction(uid, r, isGroup)] };
+            });
+        }
+    }
+    return out;
+}
+
+/** A control's `data` as an object, parsing JSON text; anything else as it is. */
+function controlData(data) {
+    if (typeof data !== "string") return data;
+    try {
+        return JSON.parse(data);
+    } catch {
+        return data;
+    }
+}
+
+/**
+ * The URL a finished upload is reachable at: `data.url` for files and videos; for a photo, its original, then its
+ * HD, then its thumbnail form (the photo control fills missing sizes from each other).
+ */
+function uploadUrl(kind, data) {
+    if (!data || typeof data !== "object") return null;
+    if (kind === "photo_success") return data.org ?? data.hd ?? data.normal ?? data.thumb ?? data.url ?? null;
+    return data.url ?? null;
+}
+
+/**
+ * One control (`controls[]` entry) as its steps.
+ *
+ * @param {string} uid
+ * @param {object} control
+ * @returns {object[]}
+ */
+function controlSteps(uid, control) {
+    const content = control?.content;
+    if (!content || typeof content !== "object") return [];
+    const actType = content.act_type;
+    if (UPLOAD_ACT_TYPES.includes(actType)) {
+        const data = controlData(content.data);
+        const url = uploadUrl(actType, data);
+        const fileId = content.fileId;
+        return [
+            { settle: { fileId, url, kind: actType, control } },
+            { emit: "upload_attachment", args: [{ fileUrl: url, fileId }] },
+        ];
+    }
+    if (actType === "group") {
+        const ev = groupControlEvent(uid, content);
+        return ev ? [{ emit: "group_event", args: [ev] }] : [];
+    }
+    if (actType === "fr") {
+        const ev = friendControlEvent(uid, content);
+        return ev ? [{ emit: "friend_event", args: [ev] }] : [];
+    }
+    // The owner set, changed or removed an alias (on any device). It names no alias: the alias list is refetched
+    // on it, and so does the engine.
+    if (actType === "alias") return [{ emit: "alias_change", args: [{ act: content.act ?? null }] }];
+    // The account's own profile changed on another device (`update`: name or avatar; `update_status`, `phonebook`,
+    // `mode`, `biz`): the own profile is refetched on `update`.
+    if (actType === "profile") return [{ emit: "profile_change", args: [{ act: content.act ?? null }] }];
+    return [];
+}
+
+/**
+ * A control push (601) or a reaction push (612): every control in order, then every reaction (`controls`, `reacts`
+ * and `reactGroups` are read from either).
+ *
+ * @param {string} uid
+ * @param {number} cmd - 601 or 612
+ * @param {object} data
+ * @returns {object[]} steps
+ */
+export function dispatchCtrl(uid, cmd, data) {
+    const out = [];
+    for (const control of listOf(data, "controls")) {
+        const act = control?.content?.act_type;
+        try {
+            out.push(...controlSteps(uid, control));
+        } catch (e) {
+            const why = `cmd ${cmd} control ${act ?? "?"}: one item not readable (${e?.name ?? "Error"})`;
+            out.push({ error: new Error(why, { cause: e }) });
+        }
+    }
+    out.push(...reactionSteps(uid, cmd, data));
+    return out;
+}
+
+/**
+ * An old-reaction queue answer (610 1-1, 611 group): `old_reactions(list, isGroup)` once per frame, each `content`
+ * left as the server sent it (the reaction drain and the store read a string or an object alike).
+ *
+ * @param {string} uid
+ * @param {number} cmd - 610 or 611
+ * @param {object} data
+ * @returns {object[]} steps
+ */
+export function dispatchOldReactions(uid, cmd, data) {
+    const isGroup = OLD_REACTION_CMDS[cmd];
+    const key = isGroup ? "reactGroups" : "reacts";
+    if (!Array.isArray(data?.[key])) return [];
+    const out = [];
+    const objects = [];
+    for (const r of data[key]) {
+        guarded(out, `cmd ${cmd} ${key}`, () => {
+            objects.push(new Reaction(uid, r, isGroup));
+            return null;
+        });
+    }
+    out.push({ emit: "old_reactions", args: [objects, isGroup] });
+    return out;
+}
+
+/** The 602 acts that are someone typing (`typing` act_type) or sending a file (`fsending`), and their thread kind. */
+const TYPING_ACTS = Object.freeze({
+    typing: { typing: false, gtyping: true },
+    fsending: { sending: false, gsending: true },
+});
+
+/**
+ * One 602 action's `data`: a typing action's is a JSON fragment without its braces, a file-sending action's is whole
+ * JSON text.
+ *
+ * @param {object} action
+ * @returns {object}
+ */
+function actionData(action) {
+    const d = action.data;
+    if (d && typeof d === "object") return d;
+    return JSON.parse(action.act_type === "typing" ? `{${d}}` : String(d));
+}
+
+/**
+ * A 602 `profile` / `online_status` action as `{userId, lastOnline}`, or null for any other action. It means
+ * "this user was last online at `lastOnline`" (`data` is JSON text `{uid, lastOnline}`). A malformed one throws.
+ *
+ * @param {object} action - one entry of a 602 frame's `actions`
+ * @returns {{userId: string, lastOnline: number}|null}
+ */
+export function onlineStatusOf(action) {
+    if (action?.act_type !== "profile" || action.act !== "online_status") return null;
+    const d = typeof action.data === "string" ? JSON.parse(action.data) : action.data;
+    if (!d?.uid || !d.lastOnline) return null;
+    const lastOnline = Number(d.lastOnline);
+    return Number.isFinite(lastOnline) ? { userId: String(d.uid), lastOnline } : null;
+}
+
+/**
+ * An action push (602): the typing and file-sending actions, as `typing` events (`action` "typing" or "fsending").
+ * One from this account's own uid (another of its devices) is dropped, as Zalo drops it. Other action kinds
+ * (`online_status` among them, read by src/core/last-online.js through the socket tap) reach the raw taps only.
+ *
+ * @param {object} data
+ * @param {string} [uid] - the own uid
+ * @returns {object[]} steps
+ */
+export function dispatchAction(data, uid = "") {
+    const out = [];
+    for (const action of listOf(data, "actions")) {
+        const kinds = TYPING_ACTS[action?.act_type];
+        if (!kinds || !Object.hasOwn(kinds, action.act)) continue;
+        guarded(out, `cmd 602 ${action.act_type}`, () => {
+            const d = actionData(action);
+            const opts = { ownId: uid, action: action.act_type };
+            const ev = kinds[action.act] ? new GroupTyping(d, opts) : new UserTyping(d, opts);
+            return ev.isSelf ? null : { emit: "typing", args: [ev] };
+        });
+    }
+    return out;
+}
+
+/**
+ * The steps of one decoded frame, by cmd.
+ *
+ * @param {string} uid - the own uid
+ * @param {{cmd: number, subCmd: number}} head
+ * @param {object} data - the decoded payload's `data`
+ * @returns {object[]} steps; none for a cmd {@link isDispatched} does not name
+ */
+export function dispatchFrame(uid, { cmd, subCmd }, data) {
+    if (!data || typeof data !== "object") return [];
+    if (CHAT_PUSH_CMDS.includes(cmd)) return dispatchChat(uid, cmd, data);
+    if (Object.hasOwn(OLD_MESSAGE_CMDS, cmd)) return subCmd === 1 ? dispatchOldMessages(uid, cmd, data) : [];
+    if (cmd === CMD_CONTROL || cmd === CMD_REACTIONS) return dispatchCtrl(uid, cmd, data);
+    if (Object.hasOwn(OLD_REACTION_CMDS, cmd)) return dispatchOldReactions(uid, cmd, data);
+    if (cmd === CMD_ACTIONS) return dispatchAction(data, uid);
+    return [];
+}

package/src/zalo/listener/frames.js

@@ -0,0 +1,222 @@
+/**
+ * Chat socket frames: the 4-byte header, the outgoing encoder, and the payload decoder.
+ *
+ * Wire format (both directions): `[version u8][cmd u16 little-endian][subCmd u8]` followed by UTF-8 JSON.
+ *
+ * An inbound frame's JSON is an envelope, `{encrypt, data, key?, error_code?}`. `data` is a string whose encoding
+ * `encrypt` names:
+ *
+ *   0  the JSON text itself
+ *   1  base64 of a zlib- or gzip-compressed JSON text
+ *   2  URI-encoded base64 of `iv (16 bytes) | additional data (16 bytes) | AES-GCM ciphertext | tag (16 bytes)`,
+ *      whose plaintext is compressed JSON; the key is the session cipher key (base64, 16 or 32 bytes: any AES
+ *      size is accepted)
+ *   3  as 2, but the plaintext is the JSON text, not compressed
+ *
+ * The session cipher key arrives in the cmd 1 frame's top-level `key`, and that frame's own `data` is encrypted
+ * under it. An outbound frame carries the JSON of `data` in the clear, or nothing after the header when there is no
+ * data object.
+ *
+ * Ids: the decoder can quote bare integer ids by key before parsing (`idKeys`, see ../kernel/json-ids.js), per
+ * handler family (chat, control). {@link idKeysForCmd} names the list for a cmd.
+ *
+ * Pure functions: no socket, no state, no output.
+ */
+import crypto from "node:crypto";
+import zlib from "node:zlib";
+import { CHAT_ID_KEYS, CTRL_ID_KEYS, preParse } from "../kernel/json-ids.js";
+
+/** Bytes before the JSON body of every frame. */
+export const HEADER_BYTES = 4;
+
+/** The `encrypt` values of an inbound envelope. */
+export const ENCRYPT = Object.freeze({ PLAIN: 0, ZIPPED: 1, SEALED_ZIPPED: 2, SEALED: 3 });
+
+/** The handshake answer: carries the session cipher key and the queue lists. */
+export const CMD_AUTH = 1;
+
+/** Ping (subCmd 1) and its echo. */
+export const CMD_PING = 2;
+
+/**
+ * Cmds the chat handler owns: pushes (501, 521, 502, 522, 504, 524, 570, 534), the Signal pushes routed
+ * through the same path (551, 552, 535, ...), the cloud pushes (620, 621, 623), 530, 533, the kick (3000), and the
+ * two chat queue answers this client pulls (510, 511). The rest of the chat queues come at run time from the
+ * handshake's `qCmds`; {@link idKeysForCmd} adds them when given the handshake data.
+ */
+export const CHAT_CMDS = Object.freeze([
+    501, 521, 502, 522, 504, 524, 570, 534, 551, 552, 535, 543, 544, 548, 549, 561, 580, 581, 582, 559, 546, 550, 553,
+    554, 620, 621, 623, 530, 533, 3000, 510, 511,
+]);
+
+/**
+ * Cmds the control handler owns: actions (602), reactions (612 push, 613 clear, 610 and 611 pages), controls (601
+ * push, 603 page) and 600. The control queues come at run time from the handshake's `ctrl_qCmds`.
+ */
+export const CTRL_CMDS = Object.freeze([602, 612, 613, 610, 611, 601, 603, 600]);
+
+/** The cmds listed in a handshake queue list (`[{cmd, subCmd}]`), ignoring malformed entries. */
+function queueCmds(list) {
+    if (!Array.isArray(list)) return [];
+    return list.filter((q) => q && Number.isInteger(q.cmd)).map((q) => q.cmd);
+}
+
+/**
+ * The id key list a cmd's payload is parsed with: the chat list for chat cmds, the control list for control cmds,
+ * and null (a plain parse) for anything else, the handshake and the ping included.
+ *
+ * @param {number} cmd
+ * @param {{qCmds?: Array<{cmd: number}>, ctrl_qCmds?: Array<{cmd: number}>}|null} [auth] - the decoded handshake
+ *   data; its queue lists join the chat and control families
+ * @returns {readonly string[]|null}
+ */
+export function idKeysForCmd(cmd, auth = null) {
+    if (CHAT_CMDS.includes(cmd) || queueCmds(auth?.qCmds).includes(cmd)) return CHAT_ID_KEYS;
+    if (CTRL_CMDS.includes(cmd) || queueCmds(auth?.ctrl_qCmds).includes(cmd)) return CTRL_ID_KEYS;
+    return null;
+}
+
+/**
+ * Read a frame's header.
+ *
+ * @param {Uint8Array} buf - the whole frame
+ * @returns {{version: number, cmd: number, subCmd: number}|null} null when the buffer is shorter than the header
+ */
+export function readHeader(buf) {
+    if (!(buf instanceof Uint8Array) || buf.length < HEADER_BYTES) return null;
+    const b = Buffer.isBuffer(buf) ? buf : Buffer.from(buf.buffer, buf.byteOffset, buf.length);
+    return { version: b[0], cmd: b.readUInt16LE(1), subCmd: b[3] };
+}
+
+/**
+ * Read a whole inbound frame: the header, then the JSON envelope as it is (the envelope's `data` stays encoded).
+ *
+ * @param {Uint8Array} buf
+ * @returns {{version: number, cmd: number, subCmd: number, envelope: object}|null} null for a buffer shorter than
+ *   the header, a body that is not JSON, or a body that is not a JSON object
+ */
+export function parseFrame(buf) {
+    const head = readHeader(buf);
+    if (!head) return null;
+    let envelope;
+    try {
+        envelope = JSON.parse(Buffer.from(buf.buffer, buf.byteOffset, buf.length).subarray(HEADER_BYTES).toString());
+    } catch {
+        return null;
+    }
+    if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) return null;
+    return { ...head, envelope };
+}
+
+const isUint = (n, max) => Number.isInteger(n) && n >= 0 && n <= max;
+
+/**
+ * Build an outbound frame: the header, then the UTF-8 JSON of `data` when `data` is a plain object, and nothing
+ * more otherwise.
+ *
+ * @param {{version?: number, cmd: number, subCmd: number, data?: object}} payload - `version` defaults to 1;
+ *   `subCmd` has no default, because a wrong one is silently ignored by the server
+ * @returns {Buffer}
+ * @throws {TypeError} when `version` or `subCmd` is not an integer 0-255, or `cmd` not an integer 0-65535
+ */
+export function encodeFrame({ version = 1, cmd, subCmd, data } = {}) {
+    if (!isUint(version, 0xff)) throw new TypeError("frame version must be an integer 0-255");
+    if (!isUint(cmd, 0xffff)) throw new TypeError("frame cmd must be an integer 0-65535");
+    if (!isUint(subCmd, 0xff)) throw new TypeError("frame subCmd must be an integer 0-255");
+    const head = Buffer.alloc(HEADER_BYTES);
+    head[0] = version;
+    head.writeUInt16LE(cmd, 1);
+    head[3] = subCmd;
+    const plain = data !== null && typeof data === "object" && !Array.isArray(data);
+    return plain ? Buffer.concat([head, Buffer.from(JSON.stringify(data), "utf8")]) : head;
+}
+
+/** AES-GCM by key size, as WebCrypto picks it from the raw key's length. */
+const GCM_BY_KEY_BYTES = new Map([
+    [16, "aes-128-gcm"],
+    [24, "aes-192-gcm"],
+    [32, "aes-256-gcm"],
+]);
+
+/** iv (16) + additional data (16) + tag (16): a sealed payload shorter than this holds nothing. */
+const SEALED_MIN_BYTES = 48;
+
+/** Open a sealed payload: `iv | aad | ciphertext | tag` under the base64 session key. */
+function openSealed(raw, cipherKey) {
+    if (!cipherKey || raw.length < SEALED_MIN_BYTES) throw new Error("missing cipher key or short frame");
+    const key = Buffer.from(String(cipherKey), "base64");
+    const algorithm = GCM_BY_KEY_BYTES.get(key.length);
+    if (!algorithm) throw new Error(`cipher key has ${key.length} bytes; expected 16, 24 or 32`);
+    const tagAt = raw.length - 16;
+    const decipher = crypto.createDecipheriv(algorithm, key, raw.subarray(0, 16));
+    decipher.setAAD(raw.subarray(16, 32));
+    decipher.setAuthTag(raw.subarray(tagAt));
+    return Buffer.concat([decipher.update(raw.subarray(32, tagAt)), decipher.final()]);
+}
+
+/** Inflate zlib or gzip (the format is read from the header), with raw deflate as the last resort. */
+function inflate(bytes) {
+    try {
+        return zlib.unzipSync(bytes);
+    } catch {
+        return zlib.inflateRawSync(bytes);
+    }
+}
+
+/**
+ * Decode an inbound envelope's `data` into the payload object.
+ *
+ * Same call shape as the decoder in src/core/sync-v2/index.js, which re-exports this one: `decodeFrame(parsed,
+ * cipherKey)` parses plainly; pass `{idKeys}` to keep the listed ids lossless (the per-handler key lists).
+ *
+ * @param {{encrypt: number, data: string}} parsed - the frame's JSON envelope
+ * @param {string|null|undefined} cipherKey - the session key (base64); needed for encrypt 2 and 3 only
+ * @param {{idKeys?: readonly string[]|null}} [opts]
+ * @returns {any} the decoded payload, usually `{error_code, data}`
+ * @throws {Error} on an unknown encrypt type, a `data` that is not a string, a missing key or a payload shorter than
+ *   48 bytes for encrypt 2 and 3, a wrong key (the GCM tag does not verify), bad compression, or text that is not
+ *   JSON
+ */
+export function decodeFrame(parsed, cipherKey, opts = {}) {
+    const encrypt = parsed?.encrypt;
+    if (!Object.values(ENCRYPT).includes(encrypt)) throw new Error(`unsupported frame encrypt type ${encrypt}`);
+    if (typeof parsed.data !== "string") throw new Error(`frame data must be a string, got ${typeof parsed.data}`);
+    let text;
+    if (encrypt === ENCRYPT.PLAIN) {
+        text = parsed.data;
+    } else {
+        const raw = Buffer.from(encrypt === ENCRYPT.ZIPPED ? parsed.data : decodeURIComponent(parsed.data), "base64");
+        const plain = encrypt === ENCRYPT.ZIPPED ? raw : openSealed(raw, cipherKey);
+        text = (encrypt === ENCRYPT.SEALED ? plain : inflate(plain)).toString("utf8");
+    }
+    const keys = opts?.idKeys;
+    return JSON.parse(keys ? preParse(text, keys) : text);
+}
+
+/**
+ * Read the handshake (cmd 1) envelope: take its cipher key, and decode its `data` under that same key.
+ *
+ * One deliberate leniency: a strict reading requires the decoded payload's `error_code` to be exactly 0 (else
+ * INVALID_AUTH_DATA, 5007). Here a payload that carries no `error_code` at all is accepted, and only
+ * a present, non-zero one refuses the session. The previous engine never decoded this payload, so a key frame without the field
+ * has always opened a session for this client, and nothing reads the field but this check; refusing it would end
+ * sessions that work today over a field no consumer uses. An explicit refusal (any non-zero code) is still final.
+ * tests/unit/listener-frames.test.js pins both halves.
+ *
+ * @param {{key?: string, encrypt?: number, data?: string}} envelope
+ * @returns {{key: string, auth: object|null}} `auth` is the decoded payload's `data` (`{qCmds, ctrl_qCmds,
+ *   bk_cmds}`), or null when the envelope carries no data
+ * @throws {Error} when the envelope has no key, or its data does not decode, or the decoded payload reports a
+ *   non-zero `error_code`
+ */
+export function readAuthFrame(envelope) {
+    const key = envelope?.key;
+    if (typeof key !== "string" || key.length === 0) throw new Error("handshake frame carries no cipher key");
+    if (typeof envelope.data !== "string" || envelope.data.length === 0) return { key, auth: null };
+    const payload = decodeFrame(envelope, key);
+    // Absent is accepted on purpose (see above); a present code must be 0.
+    if (payload?.error_code !== undefined && payload.error_code !== 0) {
+        throw new Error(`handshake refused with error_code ${payload.error_code}`);
+    }
+    return { key, auth: payload?.data && typeof payload.data === "object" ? payload.data : null };
+}