@ardennguyen/zalo-agent-cli 2.5.9 → 3.0.0

package/src/zalo/qr-login.js

@@ -0,0 +1,494 @@
+/**
+ * The QR login, as Zalo's own client does it (plan item L15).
+ *
+ * The previous engine's `loginQR` differed from what the server expects: it announces `continue=https://zalo.me/pc`
+ * to three calls, makes a `verify-client` call Zalo's own app never makes, leaves out `cliGenQR`, and
+ * ends with a request to `jr/userinfo`. This is the verified sequence instead, all on `id.zalo.me` until the
+ * last hop:
+ *
+ *  1. `GET /account?continue=https://chat.zalo.me/`: the login page; its script name carries the build `v`.
+ *  2. `POST /account/logininfo`, form `{continue, v}`.
+ *  3. `POST /account/authen/qr/generate`, form `{continue, cliGenQR, v}`: the first QR (an image the server draws)
+ *     and its `code`. `cliGenQR=1` says the client can make a QR itself, which this client can (see below).
+ *  4. `POST /account/authen/qr/waiting-scan`, form `{continue, code, v}`: a long poll, asked again until the
+ *     phone scans (error 8 means "not yet").
+ *  5. An account that has a trusted device answers that scan with `status 4`, `new_qr_supported`, and a new `code`
+ *     and `token`, no name: the phone must scan a second QR, which the client makes itself from that token with
+ *     the page's trusted-device module (./trust-wasm.js, ./qr-image.js). This is the QR that is "swapped" on the
+ *     login page after the first scan. The long poll is then asked again on the new code, and its answer carries
+ *     the name and `link_data`, which the module turns into a proof of this device.
+ *  6. `POST /account/authen/qr/waiting-confirm`, form `{continue, code, bundle, v}`: a long poll, asked again
+ *     until the phone confirms. `bundle` is the proof (base64 of `{encLinkMetaData, encAccSign, encDeviceSign,
+ *     encCompPubKey}`); an account without a trusted device has none and confirms the first QR, with no bundle.
+ *  7. `GET /account/checksession?continue=...` and the redirects it starts: `jr.zaloapp.com/jr/syncsession`,
+ *     `jr.chat.zalo.me/jr/pushsession` (which sets `zpw_sek`), and the chat page.
+ *
+ * The session this returns is a cookie jar; {@link loginWithSession} turns it into a logged-in API. Events
+ * keep the shape the callbacks have always had (the numbers of `QR_EVENT`), so the commands that show the QR did not
+ * change; the second QR is one more `QR_GENERATED` event, with `data.layer` 2.
+ *
+ * Why the first version of this sequence failed on 2026-10-27, after it worked on 2026-10-25: the phone answered
+ * "QR is not valid" to it twice, and the scan answer carried no name. The step it was missing: the scan of the
+ * first QR is answered with `status 4` and a new code, and the client makes and shows a second
+ * QR. That version took the answer for the scan and confirmed on the first code. Why it was not asked for on the 25th
+ * is not known. See `docs/agent-notes.md`.
+ */
+import { writeFile } from "node:fs/promises";
+import { QR_EVENT } from "./enums.js";
+import { QrLoginAborted, QrLoginDeclined, ZaloApiError } from "./errors.js";
+import { withBrowserHeaders } from "./headers.js";
+import { qrPng } from "./qr-image.js";
+import { TRUST_PLATFORM_WEB, loadTrustWasm, wasmUrlOf } from "./trust-wasm.js";
+import { makeImei } from "./kernel/cipher.js";
+import { loadJar, saveJar } from "./kernel/cookies.js";
+import { httpRequest } from "./kernel/http.js";
+import { createSession } from "./kernel/session.js";
+
+const ID = "https://id.zalo.me";
+const CHAT = "https://chat.zalo.me/";
+const CONTINUE_QUERY = encodeURIComponent(CHAT);
+const PAGE_URL = `${ID}/account?continue=${CONTINUE_QUERY}`;
+
+/** The build number sits in the page's script name. */
+const BUILD_PATTERN = /https:\/\/stc-zlogin\.zdn\.vn\/main-([\d.]+)\.js/;
+
+/**
+ * What the server answers a first scan with when the account has a trusted device: `status` 4, and a second code.
+ */
+const SECOND_LAYER_STATUS = 4;
+
+/** Zalo's answer when a saved device identity is refused (the phone side was reset): link as a new device. */
+const RELINK_REFUSED = -21;
+
+/** The wasm files already fetched, by URL: they are 400 KB and the build changes about monthly. */
+const wasmCache = new Map();
+
+/** A QR code is shown for this long before a new one is made. */
+export const QR_LIFETIME_MS = 100_000;
+
+/** Zalo's answer to a long poll that has nothing yet. */
+const NOT_YET = 8;
+
+/** Zalo's answer when the phone declined. */
+const DECLINED = -13;
+
+/** Headers of a call the page's script makes to its own origin (names in any case: the transport merges by name). */
+const POST_HEADERS = {
+    Accept: "application/json, text/plain, */*",
+    "content-type": "application/x-www-form-urlencoded",
+    Origin: ID,
+    Referer: PAGE_URL,
+    "sec-fetch-site": "same-origin",
+    "sec-fetch-mode": "cors",
+    "sec-fetch-dest": "empty",
+};
+
+/** Headers of a page load (and of the redirects it starts). */
+const NAVIGATION_HEADERS = {
+    Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
+    priority: "u=0, i",
+    "upgrade-insecure-requests": "1",
+    "sec-fetch-mode": "navigate",
+    "sec-fetch-dest": "document",
+};
+
+/**
+ * The login page's build number.
+ *
+ * @param {string} html
+ * @returns {string|null}
+ */
+export function buildOf(html) {
+    return BUILD_PATTERN.exec(String(html))?.[1] ?? null;
+}
+
+/**
+ * The login page's script, as a URL.
+ *
+ * @param {string} html
+ * @returns {string|null}
+ */
+export function scriptUrlOf(html) {
+    return BUILD_PATTERN.exec(String(html))?.[0] ?? null;
+}
+
+/**
+ * Whether a scan answer asks for the second QR.
+ *
+ * @param {object|null|undefined} data
+ * @returns {boolean}
+ */
+export function wantsSecondQr(data) {
+    return data?.status === SECOND_LAYER_STATUS && data?.new_qr_supported === true && !!data?.token && !!data?.code;
+}
+
+/**
+ * The trusted-device module of the login page, ready to call: the page's script names the wasm file, and both are
+ * fetched as the page would.
+ *
+ * @param {object} ctx
+ * @param {string} scriptUrl
+ * @param {AbortSignal} [signal]
+ */
+export async function loadTrustFromPage(ctx, scriptUrl, signal) {
+    const common = {
+        method: "GET",
+        signal,
+        timeoutMs: 0,
+        headers: { Accept: "*/*", Referer: `${ID}/`, "sec-fetch-site": "cross-site" },
+    };
+    const script = await httpRequest(ctx, scriptUrl, {
+        ...common,
+        headers: { ...common.headers, "sec-fetch-mode": "no-cors", "sec-fetch-dest": "script" },
+    });
+    const wasmUrl = wasmUrlOf(await script.text());
+    if (!wasmUrl) throw new ZaloApiError("The login page names no trusted-device module (its layout changed)");
+    if (!wasmCache.has(wasmUrl)) {
+        const wasm = await httpRequest(ctx, wasmUrl, {
+            ...common,
+            headers: { ...common.headers, "sec-fetch-mode": "cors", "sec-fetch-dest": "empty" },
+        });
+        wasmCache.set(wasmUrl, Buffer.from(await wasm.arrayBuffer()));
+    }
+    return loadTrustWasm(wasmCache.get(wasmUrl));
+}
+
+/**
+ * One long-poll or JSON POST on the id domain.
+ *
+ * @param {object} ctx
+ * @param {string} path
+ * @param {Record<string, string>} fields
+ * @param {AbortSignal} [signal]
+ * @returns {Promise<{error_code?: number, error_message?: string, data?: any}>}
+ */
+async function post(ctx, path, fields, signal) {
+    // A long poll is held open by the server until something happens: no client timeout but the QR's own.
+    const res = await httpRequest(ctx, `${ID}${path}`, {
+        method: "POST",
+        headers: POST_HEADERS,
+        body: new URLSearchParams(fields),
+        signal,
+        timeoutMs: 0,
+    });
+    return res.json();
+}
+
+/**
+ * Ask a long poll again for as long as the answer is "not yet".
+ *
+ * @param {object} ctx
+ * @param {string} path
+ * @param {Record<string, string>} fields
+ * @param {AbortSignal} signal
+ */
+async function longPoll(ctx, path, fields, signal) {
+    for (;;) {
+        const answer = await post(ctx, path, fields, signal);
+        if (answer?.error_code !== NOT_YET) return answer;
+    }
+}
+
+/**
+ * Run one QR login attempt to the end (or until it is aborted).
+ *
+ * @param {object} ctx
+ * @param {object} p
+ * @param {AbortController} p.controller
+ * @param {(event: object) => void} p.emit
+ * @param {{retry: Function, abort: Function}} p.actions
+ * @param {string} p.qrPath
+ * @param {number} p.lifetimeMs
+ * @param {{timer: any}} p.state - holds the expiry timer so the caller can clear it
+ * @returns {Promise<{cookies: object[]}>}
+ */
+async function attempt(ctx, { controller, emit, actions, qrPath, lifetimeMs, state, loadTrust, trustStore }) {
+    const { signal } = controller;
+    ctx.cookie = loadJar([]);
+
+    // 1: the login page, and the build number in its script name.
+    const page = await httpRequest(ctx, PAGE_URL, {
+        method: "GET",
+        headers: { ...NAVIGATION_HEADERS, Referer: CHAT, "sec-fetch-site": "same-site" },
+        signal,
+        timeoutMs: 0,
+        follow: "jar",
+    });
+    const html = await page.text();
+    const v = buildOf(html);
+    if (!v) throw new ZaloApiError("Cannot get API login version");
+    const scriptUrl = scriptUrlOf(html);
+
+    // A QR is shown for `lifetimeMs`, then the attempt ends and the caller is told it expired.
+    const armExpiry = () => {
+        clearTimeout(state.timer);
+        state.timer = setTimeout(() => {
+            controller.abort();
+            emit({ type: QR_EVENT.QR_EXPIRED, data: null, actions });
+        }, lifetimeMs);
+    };
+    const show = (qr, image, layer) =>
+        emit({
+            type: QR_EVENT.QR_GENERATED,
+            data: { ...qr, image, layer },
+            actions: {
+                async saveToFile(path = qrPath) {
+                    await writeFile(path, image, "base64");
+                },
+                ...actions,
+            },
+        });
+
+    // 2 and 3: what the page asks before it shows a QR, and the first QR.
+    await post(ctx, "/account/logininfo", { continue: CHAT, v }, signal);
+    const generated = await post(ctx, "/account/authen/qr/generate", { continue: CHAT, cliGenQR: "1", v }, signal);
+    const qr = generated?.data;
+    if (!qr?.code || !qr?.image) {
+        throw new ZaloApiError(`Unable to generate QRCode\nResponse: ${JSON.stringify(generated, null, 2)}`);
+    }
+    show(qr, String(qr.image).replace(/^data:image\/png;base64,/, ""), 1);
+
+    // A QR the caller already retried or aborted has no expiry to announce.
+    if (signal.aborted) return new Promise(() => {});
+    armExpiry();
+
+    // 4: the phone scans.
+    let code = qr.code;
+    let scanned = await longPoll(ctx, "/account/authen/qr/waiting-scan", { continue: CHAT, code, v }, signal);
+    if (!scanned?.data) throw new ZaloApiError(`Cannot get scan result\nResponse: ${JSON.stringify(scanned)}`);
+
+    // 5: an account with a trusted device asks for a second QR, which this client makes.
+    let link = null;
+    if (wantsSecondQr(scanned.data)) {
+        const first = scanned.data;
+        if (!scriptUrl) throw new ZaloApiError("Cannot find the login script (the trusted-device module is in it)");
+        const trust = await loadTrust(ctx, scriptUrl, signal);
+        const saved = trustStore?.load(first.chatUid, first.master_id) ?? null;
+        const identity = saved
+            ? { publicKey: saved.publicKey, privateKey: saved.privateKey }
+            : trust.generateIdentity();
+        const secret = saved ? saved.linkingSecret : trust.generateLinkingSecret();
+        const relinkId = saved
+            ? trust.getRelinkId({
+                  primaryKey: saved.primaryPublicIdentityKey,
+                  publicKey: saved.publicKey,
+                  secret,
+                  linkingTimestamp: saved.linkingTimestamp,
+              })
+            : undefined;
+        const text = trust.generateLinkingQr({
+            publicKey: identity.publicKey,
+            secret: saved ? undefined : secret,
+            qrToken: first.token,
+            timestamp: Date.now(),
+            platform: TRUST_PLATFORM_WEB,
+            relinkId,
+        });
+        show(first, qrPng(text).toString("base64"), 2);
+        if (signal.aborted) return new Promise(() => {});
+        armExpiry();
+
+        code = first.code;
+        scanned = await longPoll(ctx, "/account/authen/qr/waiting-scan", { continue: CHAT, code, v }, signal);
+        if (scanned?.error_code === RELINK_REFUSED && saved) {
+            trustStore.clear(first.chatUid);
+            throw new ZaloApiError("The saved device identity was refused by the phone; it was cleared. Log in again.");
+        }
+        if (!scanned?.data) throw new ZaloApiError(`Cannot get scan result\nResponse: ${JSON.stringify(scanned)}`);
+        if (!scanned.data.link_data) throw new ZaloApiError("The phone's answer to the second QR carried no link data");
+        const proof = trust.createLinkingProof({
+            publicKey: identity.publicKey,
+            privateKey: identity.privateKey,
+            secret,
+            primaryLinkingData: new Uint8Array(Buffer.from(scanned.data.link_data.enc_link_data, "base64")),
+            linkingHmac: new Uint8Array(Buffer.from(scanned.data.link_data.enc_link_hmac, "base64")),
+            platform: TRUST_PLATFORM_WEB,
+        });
+        link = { uid: first.chatUid, identity, secret, proof };
+    }
+    emit({ type: QR_EVENT.QR_SCANNED, data: scanned.data, actions });
+
+    // 6: the phone confirms (or declines); with a proof, the proof goes with it.
+    const confirmFields = { continue: CHAT, code };
+    if (link) {
+        const b64 = (bytes) => Buffer.from(bytes).toString("base64");
+        confirmFields.bundle = b64(
+            Buffer.from(
+                JSON.stringify({
+                    encLinkMetaData: b64(link.proof.linkingMetadata),
+                    encAccSign: b64(link.proof.accountSignature),
+                    encDeviceSign: b64(link.proof.deviceSignature),
+                    encCompPubKey: b64(link.identity.publicKey),
+                }),
+            ),
+        );
+    }
+    confirmFields.v = v;
+    const confirmed = await longPoll(ctx, "/account/authen/qr/waiting-confirm", confirmFields, signal);
+    clearTimeout(state.timer);
+    if (!confirmed) throw new ZaloApiError("Cannot get confirm result");
+    if (confirmed.error_code === DECLINED) {
+        emit({ type: QR_EVENT.QR_DECLINED, data: { code }, actions });
+        throw new QrLoginDeclined();
+    }
+    if (confirmed.error_code !== 0) {
+        throw new ZaloApiError(`An error has occurred.\nResponse: ${JSON.stringify(confirmed, null, 2)}`);
+    }
+
+    // 7: the id domain hands the session to the chat domain through two redirects. They are followed here, one hop
+    // at a time as a browser navigation follows them, so that the cookie each hop sets is kept.
+    const session = await httpRequest(ctx, `${ID}/account/checksession?continue=${CONTINUE_QUERY}`, {
+        method: "GET",
+        headers: { ...NAVIGATION_HEADERS, Referer: PAGE_URL, "sec-fetch-site": "same-origin" },
+        signal,
+        timeoutMs: 0,
+        follow: "jar",
+    });
+    if (!session) throw new ZaloApiError("Cannot get session, login failed");
+    await session.text().catch(() => "");
+
+    // The identity is kept only once the login went through, so a failed one leaves no half-linked device behind.
+    let trusted = null;
+    if (link) {
+        trusted = {
+            uid: link.uid,
+            masterId: link.proof.masterId,
+            companionId: link.proof.companionId,
+            linkId: link.proof.linkId,
+            linkingTimestamp: link.proof.linkingTimestamp,
+            publicKey: link.identity.publicKey,
+            privateKey: link.identity.privateKey,
+            linkingSecret: link.secret,
+            primaryPublicIdentityKey: link.proof.primaryPublicIdentityKey,
+            devices: confirmed.data?.devices ?? null,
+        };
+        trustStore?.save(trusted);
+    }
+    // Whose login this is: the trusted-device scan names it, and the confirm answer carries it (`chatUid`).
+    const uid = link?.uid ?? confirmed.data?.chatUid ?? null;
+    return {
+        cookies: saveJar(ctx.cookie).cookies,
+        uid: uid === null || uid === undefined || uid === "" ? null : String(uid),
+        displayName: scanned.data.display_name ?? null,
+        trusted: trusted ? { uid: trusted.uid, masterId: trusted.masterId, companionId: trusted.companionId } : null,
+    };
+}
+
+/**
+ * The saved imei to log in with again, or null for a new one: only for a known account whose saved device id was made
+ * with this same user agent (an imei ends with the hash of its user agent, so the two must stay a pair).
+ *
+ * @param {string|null} uid
+ * @param {string} userAgent
+ * @param {((uid: string) => ({imei: string, userAgent: string}|null))|null} deviceFor
+ * @returns {string|null}
+ */
+export function deviceImeiFor(uid, userAgent, deviceFor) {
+    if (!uid || typeof deviceFor !== "function") return null;
+    let saved = null;
+    try {
+        saved = deviceFor(String(uid));
+    } catch {
+        return null;
+    }
+    if (typeof saved?.imei !== "string" || !saved.imei || saved.userAgent !== userAgent) return null;
+    return saved.imei;
+}
+
+/**
+ * Log in by QR with the official sequence and return the session it produced.
+ *
+ * @param {object} p
+ * @param {string} p.userAgent - the browser identity of this login, kept for every later call
+ * @param {object} [p.zaloOptions] - the session options (`polyfill`, `agent`, ...)
+ * @param {number} p.apiType
+ * @param {number} p.apiVersion
+ * @param {(event: object) => void} [p.onEvent] - events `{type, data, actions}`, `type` a `QR_EVENT` number
+ * @param {string} [p.qrPath] - where `saveToFile()` writes by default
+ * @param {number} [p.lifetimeMs] - how long a QR is shown before it expires
+ * @param {Function} [p.loadTrust] - `(ctx, scriptUrl, signal) => trust module`, the page's by default
+ * @param {{load: Function, save: Function, clear: Function}|null} [p.trustStore] - where the device identity is kept
+ * @param {(uid: string) => ({imei: string, userAgent: string}|null)} [p.deviceFor] - the device id this machine
+ *   already uses for an account, if any. Zalo keeps one imei per browser across logout and login, and keeps
+ *   the offline queue per device: an account that confirms the QR and has a saved device id with this same user agent
+ *   logs in with that imei again, so its queue survives the re-login. Anything else gets a new imei.
+ * @returns {Promise<{cookies: object[], imei: string, userAgent: string, language: string, trusted: object|null,
+ *   uid: string|null, deviceReused: boolean}>}
+ * @throws {QrLoginDeclined|QrLoginAborted|ZaloApiError}
+ */
+export function qrLogin({
+    userAgent,
+    zaloOptions = {},
+    apiType,
+    apiVersion,
+    onEvent = null,
+    qrPath = "qr.png",
+    lifetimeMs = QR_LIFETIME_MS,
+    loadTrust = loadTrustFromPage,
+    trustStore = null,
+    deviceFor = null,
+}) {
+    return new Promise((resolve, reject) => {
+        let current = null;
+
+        const stop = () => {
+            if (!current) return;
+            clearTimeout(current.state.timer);
+            current.controller.abort();
+            current.superseded = true;
+        };
+        const emit = (event) => onEvent?.(event);
+        const actions = {
+            retry: () => {
+                stop();
+                start();
+            },
+            abort: () => {
+                stop();
+                reject(new QrLoginAborted());
+            },
+        };
+
+        const start = () => {
+            const ctx = createSession({ apiType, apiVersion });
+            Object.assign(ctx.options, zaloOptions);
+            ctx.options.logging = false;
+            ctx.options.polyfill = withBrowserHeaders(ctx.options.polyfill, userAgent);
+            ctx.userAgent = userAgent;
+            const mine = { controller: new AbortController(), state: { timer: null }, superseded: false };
+            current = mine;
+            attempt(ctx, { ...mine, emit, actions, qrPath, lifetimeMs, loadTrust, trustStore }).then(
+                (result) => {
+                    clearTimeout(mine.state.timer);
+                    if (mine.superseded) return;
+                    const reused = deviceImeiFor(result.uid, userAgent, deviceFor);
+                    const imei = reused ?? makeImei(userAgent);
+                    const deviceReused = reused !== null;
+                    onEvent?.({
+                        type: QR_EVENT.GOT_LOGIN_INFO,
+                        data: { cookie: result.cookies, imei, userAgent },
+                        actions: null,
+                    });
+                    resolve({
+                        cookies: result.cookies,
+                        imei,
+                        userAgent,
+                        language: "vi",
+                        trusted: result.trusted,
+                        uid: result.uid,
+                        deviceReused,
+                    });
+                },
+                (error) => {
+                    clearTimeout(mine.state.timer);
+                    // A QR that expired (or was retried or aborted) aborts its own requests: that is not a failure.
+                    if (mine.superseded) return;
+                    if (error?.name === "AbortError" || error?.name === "TimeoutError") return;
+                    reject(error);
+                },
+            );
+        };
+
+        start();
+    });
+}

package/src/zalo/queues/control-queue.js

@@ -0,0 +1,193 @@
+/**
+ * The `601` control frames and the queues behind them (plan item X4).
+ *
+ * A `601` carries `controls[]`, each `{actionId, controlId, content: {act, act_type, data}}`, plus `queueStatus` with
+ * the control queues' cursors: `603_1`, `603_0` and `604_0`, each `{ids, lastId}`. A client uses those
+ * `lastId`s as the cursor of its next `603` pull, so that controls that arrived while it was offline (a group
+ * event, an unread mark, a sync status) are fetched when it comes back.
+ *
+ * A daemon pulls `603` on every connect, from the cursors kept here, and replays each page as a `601` push
+ * (src/core/control-replay.js, called by src/core/self-heal.js). This module is what reads those frames:
+ *
+ *  - {@link readControls} sorts the controls of a frame by what they are, so a control nobody handles is named
+ *    instead of vanishing;
+ *  - {@link controlCursorsOf} reads the control queues' cursors, which the daemon keeps (forward only) from every
+ *    push and every replayed page.
+ *
+ * Nothing here acknowledges a control: Zalo expects no acknowledgement at all (the cursor is the
+ * mechanism; a control queue is not consumed by being read), and the controls this client handles are acted on in
+ * memory, not stored.
+ */
+
+/** The control queues named in every `601` reply. */
+export const CONTROL_QUEUES = Object.freeze(["603_1", "603_0", "604_0"]);
+
+/**
+ * What a control is, by `act_type/act`, `act_type` or `act`. An entry names the handler that acts on it, or (`ignored`)
+ * why there is nothing for this client to do. The values come from observed frames and from the handlers
+ * this client already has (the listener's `file_done`, `video_done`, `photo_success`, `group`, `fr`; src/core/read-state.js's `mark_unread`; the sync status
+ * frames).
+ */
+const KNOWN = new Map([
+    ["transfer_sync2", { kind: "sync", handler: "sync-v2" }],
+    ["mark_unread", { kind: "read-state", handler: "read-state" }],
+    ["pinned_convers", { kind: "pin-state", handler: "read-state" }],
+    ["file_done", { kind: "upload", handler: "listener" }],
+    ["video_done", { kind: "upload", handler: "listener" }],
+    ["photo_success", { kind: "upload", handler: "listener" }],
+    ["group", { kind: "group-event", handler: "listener" }],
+    ["fr", { kind: "friend-event", handler: "listener" }],
+    // The owner's alias for someone set, changed or removed: the listener's `alias_change`; the app rereads its alias
+    // list (src/core/contact-names.js), as Zalo does.
+    ["alias", { kind: "alias", handler: "listener" }],
+    // The account's own profile changed on another device: the listener's `profile_change`; on `update` the app
+    // rereads its own profile name (src/core/contact-names.js).
+    ["profile", { kind: "profile", handler: "listener" }],
+    ["voice2text", { kind: "transcript", handler: "voice-text" }],
+    // A product or catalog added, edited or deleted on another device (the whole `prod_catalog` family), a DM
+    // reminder created, edited or deleted, the account's device list changed: src/core/control-events.js. Only the
+    // named `oneone` acts are handled; another act of that family is still named as unhandled.
+    ["prod_catalog", { kind: "catalog", handler: "control-events" }],
+    ["create_reminder11", { kind: "reminder", handler: "control-events" }],
+    ["update_reminder11", { kind: "reminder", handler: "control-events" }],
+    ["remove_reminder11", { kind: "reminder", handler: "control-events" }],
+    ["update_user_devices", { kind: "devices", handler: "control-events" }],
+    // This account's own settings changed on another device (`act: "update"`, the changed keys in `data`, to merge
+    // into the settings): a `settings_changed` event, src/core/control-events.js.
+    ["my_settings", { kind: "settings", handler: "control-events" }],
+    // Hidden chats hidden or unhidden (`add_remove`), their PIN removed (`reset`) or changed (`change_pin`, the new
+    // hash in `data.pin`) on another device: the app keeps its hidden set current from them.
+    ["hidden_chat", { kind: "hidden-chat", handler: "hidden-chats" }],
+    // A conversation muted or unmuted (`set`/`unset`, data `{toId, muteType, duration, startTime, systemTime}`), the
+    // conversation labels changed (`label_convers/update`), the archived ("Other") list changed
+    // (`archived_chat/update`, `{version, actionType, items}`), a quick message created, edited or deleted
+    // (`quick_message`, `{items, version}`), a conversation's auto-delete time changed (`conv_settings/update_ttl`), on
+    // another device. Zalo's own apps apply each to a store of their own; this client keeps none of them (`conv muted`,
+    // `label list`, `conv archived`, `quick-msg list` and `conv auto-delete-status` read Zalo live), so each is reported
+    // as an event: src/core/control-events.js.
+    ["mute", { kind: "mute", handler: "control-events" }],
+    ["label_convers", { kind: "labels", handler: "control-events" }],
+    ["archived_chat", { kind: "archived", handler: "control-events" }],
+    ["quick_message", { kind: "quick-message", handler: "control-events" }],
+    ["conv_settings/update_ttl", { kind: "auto-delete", handler: "control-events" }],
+    // Known, and nothing to do: what each is for, and why this client has nothing to change.
+    [
+        "media_send2me",
+        {
+            kind: "self-chat-media",
+            ignored:
+                "Zalo's apps add or remove the item in their My Cloud media panel; the zCloud index follows the cloud queue (cmd 620/621), not this",
+        },
+    ],
+    [
+        "photo/renew_link",
+        {
+            kind: "renew-link",
+            ignored:
+                "the late answer to a link renewal another device made to forward media (matched by originalUrl to a waiting callback); this client reads renewlink's own reply and waits for none",
+        },
+    ],
+    [
+        "file/renew_link",
+        {
+            kind: "renew-link",
+            ignored:
+                "the late answer to a link renewal another device made to forward a file (matched by originalUrl to a waiting callback); this client reads renewlink's own reply and waits for none",
+        },
+    ],
+    [
+        "video/renew_link",
+        {
+            kind: "renew-link",
+            ignored:
+                "the late answer to a link renewal another device made to forward a video (matched by originalUrl to a waiting callback); this client reads renewlink's own reply and waits for none",
+        },
+    ],
+    [
+        "emoji_status",
+        {
+            kind: "emoji-status",
+            ignored: "the status emoji Zalo paints beside a contact; this client neither keeps nor shows one",
+        },
+    ],
+    [
+        "contact_tab",
+        {
+            kind: "ui",
+            ignored: "the Contacts tab was opened on another device: Zalo clears that tab's badge (UI only)",
+        },
+    ],
+    [
+        "transfer_msg",
+        {
+            kind: "sync",
+            ignored:
+                "the phone's offer to sync messages after a QR login: `login` reads it from the control queue (src/core/sync-v2/auto-sync.js), and a daemon never starts a phone-backed restore",
+        },
+    ],
+]);
+
+/** The entry for a control: by `act_type/act` first, then by `act_type`, then by `act`. */
+function knownOf(actType, act) {
+    return KNOWN.get(`${actType}/${act}`) ?? KNOWN.get(actType) ?? KNOWN.get(act) ?? null;
+}
+
+/** A control's `data`: an object, or the JSON text of one, or null when it is neither. */
+function dataOf(data) {
+    let obj = data;
+    if (typeof data === "string") {
+        try {
+            obj = JSON.parse(data);
+        } catch {
+            return null;
+        }
+    }
+    return obj && typeof obj === "object" && !Array.isArray(obj) ? obj : null;
+}
+
+/**
+ * The controls of one `601` frame's `data`.
+ *
+ * @param {object|null|undefined} data - a decoded 601 frame's `data`
+ * @returns {Array<{actionId: string|null, actType: string, act: string, kind: string, handler: string|null,
+ *   handled: boolean, ignored: string|null, data: object|null, ts: number|null}>} `handled` is false for a control
+ *   this client does not know; `ignored` is the reason a known control needs nothing done (then `handler` is null);
+ *   `data` is the control's own data when it is an object; `ts` is the control's own time, when it has one
+ */
+export function readControls(data) {
+    const out = [];
+    for (const c of Array.isArray(data?.controls) ? data.controls : []) {
+        const content = c?.content;
+        if (!content || typeof content !== "object") continue;
+        const actType = String(content.act_type ?? "");
+        const act = String(content.act ?? "");
+        const known = knownOf(actType, act);
+        out.push({
+            actionId: c.actionId === undefined || c.actionId === null ? null : String(c.actionId),
+            actType,
+            act,
+            kind: known?.kind ?? "unknown",
+            handler: known?.handler ?? null,
+            handled: Boolean(known),
+            ignored: known?.ignored ?? null,
+            data: dataOf(content.data),
+            ts: Number.isFinite(Number(content.ts)) && Number(content.ts) > 0 ? Number(content.ts) : null,
+        });
+    }
+    return out;
+}
+
+/**
+ * The control queues' cursors in a `601` frame's `data`.
+ *
+ * @param {object|null|undefined} data
+ * @returns {Array<{queueName: string, id: string}>} only queues that name a numeric `lastId` other than 0
+ */
+export function controlCursorsOf(data) {
+    const out = [];
+    for (const queueName of CONTROL_QUEUES) {
+        const id = data?.queueStatus?.[queueName]?.lastId;
+        if (/^\d+$/.test(String(id ?? "")) && String(id) !== "0") out.push({ queueName, id: String(id) });
+    }
+    return out;
+}