@ardennguyen/zalo-agent-cli 2.5.9 → 3.0.0

package/src/zalo/profile.js

@@ -0,0 +1,184 @@
+/**
+ * The protocol profile: every value that says "who we are" to Zalo, in one place.
+ *
+ * Until now these were scattered: the announced version and type in
+ * `core/zalo-client.js`, the computer name as a literal in `core/logout.js`
+ * (and, separately, inside the previous engine), the device label inside `core/sync-v2`,
+ * and the browser presets in `utils/device-fingerprint.js`. A version bump
+ * meant hunting for all of them. Everything that identifies this client now
+ * reads from here, so changing the identity is one edit and one test.
+ *
+ * What lives here is deliberately small: only values the code announces to
+ * Zalo today. Server-driven settings (retry tables, keepalive intervals, the
+ * maintenance switch) are read from `getServerInfo` by the items that use
+ * them and are not duplicated here.
+ *
+ * The announced version is {@link DEFAULT_API_VERSION}, Zalo's current client
+ * version.
+ */
+
+/** The client class this CLI announces as: `zpw_type` and `type`. */
+export const API_TYPE = 30;
+
+/**
+ * The protocol version announced when `ZALO_API_VERSION` is not set:
+ * `zpw_ver` on every HTTP and WebSocket URL and `client_version` in the login
+ * calls, for every call alike. The previous engine defaulted to 685; Zalo's current
+ * clients were on 695 when this was last moved (2026-11-06; it was 694).
+ */
+export const DEFAULT_API_VERSION = 695;
+
+/** The `computer_name` sent in the login, server-info and logout calls. */
+export const COMPUTER_NAME = "Web";
+
+/**
+ * The device name shown for a phone-backed sync. It stays recognizable on
+ * purpose: this client does not pretend to be a browser or a mobile app.
+ */
+export const DEVICE_LABEL = "zalo-agent-cli";
+
+/**
+ * The `Accept-Language` every HTTP call and the socket upgrade send: what Chrome sends for an en-US profile, and the
+ * value this client has sent live since its first login (spec-kernel D3 asks for "the browser's own" without naming
+ * another). Kept here with the rest of the client's identity; the kernel reads it from here.
+ */
+export const ACCEPT_LANGUAGE = "en-US,en;q=0.9";
+
+/** Marks a bad ZALO_API_VERSION, so callers do not mistake it for a revoked session. */
+export const API_VERSION_INVALID = "ZALO_API_VERSION_INVALID";
+
+/**
+ * The protocol version to announce: `ZALO_API_VERSION` when set (a rollback
+ * switch, for example 685 for the previous engine's default), otherwise
+ * {@link DEFAULT_API_VERSION}. An empty or blank value counts as unset.
+ *
+ * @param {object} [env] - the environment to read, `process.env` by default
+ * @returns {number}
+ * @throws {Error} with `.code === API_VERSION_INVALID` when the variable is set
+ *   to anything but a positive whole number
+ */
+export function resolveApiVersion(env = process.env) {
+    const raw = env.ZALO_API_VERSION;
+    const value = raw === undefined ? "" : String(raw).trim();
+    if (value === "") return DEFAULT_API_VERSION;
+    const n = Number(value);
+    if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(n)) {
+        const err = new Error(
+            `ZALO_API_VERSION must be a positive whole number -- the protocol version to announce, ` +
+                `e.g. 685 to roll back from ${DEFAULT_API_VERSION} -- but it is "${raw}". Fix or unset it.`,
+        );
+        err.code = API_VERSION_INVALID;
+        throw err;
+    }
+    return n;
+}
+
+/** Marks a bad ZALO_QR_FLOW, so callers can tell it from a failed login. */
+export const QR_FLOW_INVALID = "ZALO_QR_FLOW_INVALID";
+
+/**
+ * Which QR login runs. Only `official` is left: the verified sequence (src/zalo/qr-login.js), the default since
+ * 2026-10-28, when two live logins with the trusted-device second QR went through (see docs/agent-notes.md). The
+ * `legacy` flow (the previous engine's) was removed in 3.0.0: it could not log in an account with a trusted device and
+ * skipped every later login fix. `ZALO_QR_FLOW=legacy` is refused with a message that says so, so a user who still
+ * has it in an `.env` learns why instead of seeing a generic error.
+ *
+ * @param {object} [env] - the environment to read, `process.env` by default
+ * @returns {"official"}
+ * @throws {Error} with `.code === QR_FLOW_INVALID` for `legacy` and for any other value but `official`
+ */
+export function resolveQrFlow(env = process.env) {
+    const raw = env.ZALO_QR_FLOW;
+    const value = raw === undefined ? "" : String(raw).trim().toLowerCase();
+    if (value === "" || value === "official") return "official";
+    const err = new Error(
+        value === "legacy"
+            ? "ZALO_QR_FLOW=legacy was removed in 3.0.0; the official QR login is the only one. " +
+                  "Unset ZALO_QR_FLOW or set it to official."
+            : `ZALO_QR_FLOW can only be "official" (the legacy flow was removed in 3.0.0), but it is "${raw}". ` +
+                  "Fix or unset it.",
+    );
+    err.code = QR_FLOW_INVALID;
+    throw err;
+}
+
+/** Chrome builds the QR-login fingerprint may announce. Newest first: the current stable and the three before it. */
+export const CHROME_VERSIONS = Object.freeze(["155.0.0.0", "154.0.0.0", "153.0.0.0", "152.0.0.0"]);
+
+/**
+ * Operating systems the fingerprint may claim. Chrome only, on purpose: other
+ * browsers send no Client Hints, and the phone's device label is read from
+ * those hints, so straying from Chrome would trade one oddity for another.
+ */
+export const UA_PLATFORMS = Object.freeze([
+    Object.freeze({ token: "Windows NT 10.0; Win64; x64", hint: '"Windows"' }),
+    Object.freeze({ token: "Macintosh; Intel Mac OS X 10_15_7", hint: '"macOS"' }),
+]);
+
+/**
+ * The browser User-Agent for a platform and Chrome build, in the exact shape
+ * Chrome sends.
+ *
+ * @param {{token: string}} platform - an entry of {@link UA_PLATFORMS}
+ * @param {string} chromeVersion - an entry of {@link CHROME_VERSIONS}
+ * @returns {string}
+ */
+export function buildUserAgent(platform, chromeVersion) {
+    return `Mozilla/5.0 (${platform.token}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${chromeVersion} Safari/537.36`;
+}
+
+/**
+ * Zalo's number for the browser a User-Agent names (the `browser` parameter of the profile call).
+ *
+ * @param {string} userAgent
+ * @returns {number} 1 Opera, 2 Firefox, 3 Safari, 4 Internet Explorer, 5 Edge, 6 Chrome, 0 anything else
+ */
+export function browserCodeOf(userAgent) {
+    const ua = String(userAgent ?? "");
+    if (/OPR\/|Opera/.test(ua)) return 1;
+    if (/Edg(e|A|iOS)?\//.test(ua)) return 5;
+    if (/MSIE |Trident\//.test(ua)) return 4;
+    if (/Firefox\//.test(ua)) return 2;
+    if (/Chrome\/|Chromium\//.test(ua)) return 6;
+    if (/Safari\//.test(ua)) return 3;
+    return 0;
+}
+
+/**
+ * Zalo's number for the operating system a User-Agent names (the `os` parameter of the profile call).
+ *
+ * @param {string} userAgent
+ * @returns {number} 1 Windows Phone, 2 Android, 3 iPad, 4 iPhone, 5 iPod, 6 macOS, 7 Windows, 8 Linux, 0 anything else
+ */
+export function osCodeOf(userAgent) {
+    const ua = String(userAgent ?? "");
+    if (/windows phone/i.test(ua)) return 1;
+    if (/android/i.test(ua)) return 2;
+    if (/iPad/i.test(ua)) return 3;
+    if (/iPhone/i.test(ua)) return 4;
+    if (/iPod/i.test(ua)) return 5;
+    if (/Macintosh|Mac OS X/i.test(ua)) return 6;
+    if (/Windows/i.test(ua)) return 7;
+    if (/Linux/i.test(ua)) return 8;
+    return 0;
+}
+
+/** The `avatar_size` every profile and list call asks for. */
+export const AVATAR_SIZE = 160;
+
+/**
+ * The profile as one frozen object, for callers that want to log or assert
+ * all of it at once.
+ *
+ * @param {object} [env] - the environment to read, `process.env` by default
+ * @returns {Readonly<{apiType: number, apiVersion: number, computerName: string, deviceLabel: string}>}
+ * @throws {Error} when `ZALO_API_VERSION` is invalid (see {@link resolveApiVersion})
+ */
+export function getProfile(env = process.env) {
+    return Object.freeze({
+        apiType: API_TYPE,
+        apiVersion: resolveApiVersion(env),
+        computerName: COMPUTER_NAME,
+        deviceLabel: DEVICE_LABEL,
+    });
+}

package/src/zalo/pulls.js

@@ -0,0 +1,129 @@
+/**
+ * The requests a client sends when a socket connects and when it pulls a queue (plan items X5 and X6).
+ *
+ * Every pull has the same shape, `{first, reqId, lastId, preIds}`: the request id rides in `data` as `reqId`, never
+ * as `req_id`, a key the server does not expect. Here:
+ *
+ *  - {@link installOfficialPulls} makes a listener send its two old-message pulls (510, 511) and its two
+ *    old-reaction pulls (610, 611) in that shape;
+ *  - the builders produce the other connect-time requests a client sends and this client does not yet:
+ *    the pulls of queues 515, 517, 518 and 603, the key-id request (564), the conversation-state request (577)
+ *    and the paged action list (537).
+ *
+ * Of these builders, 603 is now sent: on every connect a daemon pulls its control queues from their saved cursors
+ * and replays what they held (./../core/control-replay.js). The others are not sent, which is right for a client
+ * without end-to-end encryption: 515 and 517 are the Signal queues (1-1 messages
+ * encrypted for this device, and session-control items), unreadable without a Signal stack; 518 is deleted by an
+ * acknowledgement (557), so asking for it without handling it only loses it; 564 is the Signal key id; 577 only
+ * reconciles unread badges of a local store that counts unread messages (this client keeps a read watermark, which
+ * the offline pages' `clearUnreads` already move); 537 lists media already downloaded on another device, a prefetch
+ * hint. Answers seen live (2026-10-25): 515, 517 and 518 in the shape of the old-message queues (empty on the test
+ * account), 564 `{err, keyId}`, 537 `{hasMore, actions[]}`, 603 pages of 50 controls.
+ */
+import { nextReqId } from "./req-id.js";
+
+/** THREAD_TYPE.User; anything else is a group. */
+const THREAD_USER = 0;
+
+/** The queue pulls a client sends on connect, in order, as `[cmd, subCmd]`. */
+export const CONNECT_PULLS = Object.freeze([
+    [510, 1],
+    [511, 1],
+    [610, 1],
+    [611, 1],
+    [603, 1],
+    [515, 0],
+    [517, 0],
+    [518, 0],
+]);
+
+/**
+ * One queue pull.
+ *
+ * @param {number} cmd
+ * @param {number} subCmd
+ * @param {object} [opts]
+ * @param {string|null} [opts.lastId] - the queue's saved cursor
+ * @param {boolean} [opts.first] - false for the next page of an answer that said `more`
+ * @param {() => string} [opts.reqId] - a test seam
+ * @returns {{version: number, cmd: number, subCmd: number, data: {first: boolean, reqId: string, lastId: string|null, preIds: never[]}}}
+ */
+export function buildPull(cmd, subCmd, { lastId = null, first = true, reqId = nextReqId } = {}) {
+    return { version: 1, cmd, subCmd, data: { first, reqId: reqId(), lastId, preIds: [] } };
+}
+
+/** The key-id request (564): `{data: {platformType: 1}}`, 1 being this client's platform type. */
+export function buildKeyIdRequest() {
+    return { version: 1, cmd: 564, subCmd: 0, data: { data: { platformType: 1 } } };
+}
+
+/**
+ * The conversation-state request (577).
+ *
+ * @param {{oneone?: unknown[], group?: unknown[]}} [lists]
+ */
+export function buildConversationStateRequest({ oneone = [], group = [] } = {}) {
+    return { version: 1, cmd: 577, subCmd: 0, data: { oneone, group } };
+}
+
+/**
+ * One page request of the action list (537).
+ *
+ * @param {{lastId?: string|number, maxItem?: number}} [p]
+ */
+export function buildActionListRequest({ lastId = 0, maxItem = 50 } = {}) {
+    return { version: 1, cmd: 537, subCmd: 0, data: { lastId, maxItem } };
+}
+
+/**
+ * Page an action list the way the client does: ask again while the answer says `hasMore`, from the id of the last
+ * action it returned.
+ *
+ * @param {(request: object) => Promise<{hasMore?: boolean, actions?: Array<{id?: string|number, actionId?: string|number}>}|null>} ask -
+ *   sends one request and resolves the answer's `data`, or null when none came
+ * @param {object} [opts]
+ * @param {number} [opts.maxItem]
+ * @param {number} [opts.maxPages] - an opt-in bound; by default the list is read until `hasMore` is false, and the
+ *   runaway stop is a cursor that does not move (`stalled`)
+ * @returns {Promise<{actions: object[], pages: number, complete: boolean, reason: "drained"|"no-answer"|"stalled"|"page-cap"}>}
+ */
+export async function pageActionList(ask, { maxItem = 50, maxPages = Infinity } = {}) {
+    const out = { actions: [], pages: 0, complete: false, reason: "page-cap" };
+    let lastId = 0;
+    while (out.pages < maxPages) {
+        const answer = await ask(buildActionListRequest({ lastId, maxItem }));
+        if (!answer) return { ...out, reason: "no-answer" };
+        out.pages++;
+        const actions = Array.isArray(answer.actions) ? answer.actions : [];
+        out.actions.push(...actions);
+        if (!answer.hasMore) return { ...out, complete: true, reason: "drained" };
+        // The cursor is read from `id`; `actionId` is accepted too.
+        const last = actions.at(-1);
+        const next = last?.id ?? last?.actionId;
+        // A cursor that does not move would ask for the same page forever.
+        if (next === undefined || next === null || String(next) === String(lastId))
+            return { ...out, reason: "stalled" };
+        lastId = next;
+    }
+    return out;
+}
+
+/**
+ * Make a listener send its old-message and old-reaction pulls as the server expects: with `reqId`, never `req_id`.
+ * Safe to call twice.
+ *
+ * @param {object} listener - a listener (needs `sendWs`)
+ * @returns {object} the same listener
+ */
+export function installOfficialPulls(listener) {
+    if (!listener || listener.__officialPulls) return listener;
+    listener.__officialPulls = true;
+    const pull = (users, groups) =>
+        function pullQueue(threadType, lastMsgId = null) {
+            const cmd = threadType === THREAD_USER ? users : groups;
+            this.sendWs(buildPull(cmd, 1, { lastId: lastMsgId }));
+        };
+    listener.requestOldMessages = pull(510, 511);
+    listener.requestOldReactions = pull(610, 611);
+    return listener;
+}

package/src/zalo/qr-image.js

@@ -0,0 +1,90 @@
+/**
+ * A QR code as a PNG, for the second QR of the trusted-device login (see ./trust-wasm.js).
+ *
+ * The first QR of a login is an image Zalo's server draws. The second is text the trust module makes, which the
+ * page draws itself; this does the same: the text is encoded as bytes, with the page's own choice of error
+ * correction (H for a text under 150 characters, M above), and written as a grayscale PNG.
+ */
+import { deflateSync } from "node:zlib";
+import qrcode from "qrcode-generator";
+
+/** Modules of white around the code, as the QR standard asks. */
+const QUIET_ZONE = 4;
+
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+
+const crc32 = (buffer) => {
+    let c = 0xffffffff;
+    for (const byte of buffer) c = CRC_TABLE[(c ^ byte) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+};
+
+const chunk = (type, data) => {
+    const body = Buffer.concat([Buffer.from(type, "ascii"), data]);
+    const out = Buffer.alloc(body.length + 8);
+    out.writeUInt32BE(data.length, 0);
+    body.copy(out, 4);
+    out.writeUInt32BE(crc32(body), body.length + 4);
+    return out;
+};
+
+/**
+ * Error correction the page uses for a text of this length.
+ *
+ * @param {string} text
+ * @returns {"H"|"M"}
+ */
+export function errorLevelFor(text) {
+    return String(text).length < 150 ? "H" : "M";
+}
+
+/**
+ * Encode text as a QR code and return it as PNG bytes.
+ *
+ * @param {string} text
+ * @param {{scale?: number}} [options] - pixels per module, 8 by default
+ * @returns {Buffer}
+ */
+export function qrPng(text, { scale = 8 } = {}) {
+    const qr = qrcode(0, errorLevelFor(text));
+    qr.addData(String(text), "Byte");
+    qr.make();
+    const modules = qr.getModuleCount();
+    const size = (modules + QUIET_ZONE * 2) * scale;
+
+    // One filter byte (0, none) then the row's pixels: 0 is black, 255 white.
+    const row = Buffer.alloc(size + 1, 255);
+    row[0] = 0;
+    const raw = Buffer.alloc((size + 1) * size);
+    for (let y = 0; y < size; y++) {
+        const moduleY = Math.floor(y / scale) - QUIET_ZONE;
+        row.fill(255, 1);
+        if (moduleY >= 0 && moduleY < modules) {
+            for (let x = 0; x < size; x++) {
+                const moduleX = Math.floor(x / scale) - QUIET_ZONE;
+                if (moduleX >= 0 && moduleX < modules && qr.isDark(moduleY, moduleX)) row[x + 1] = 0;
+            }
+        }
+        row.copy(raw, y * (size + 1));
+    }
+
+    const header = Buffer.alloc(13);
+    header.writeUInt32BE(size, 0);
+    header.writeUInt32BE(size, 4);
+    header[8] = 8; // bit depth
+    header[9] = 0; // grayscale
+    return Buffer.concat([
+        Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+        chunk("IHDR", header),
+        chunk("IDAT", deflateSync(raw)),
+        chunk("IEND", Buffer.alloc(0)),
+    ]);
+}