@ardennguyen/zalo-agent-cli 1.0.7 → 2.1.0

package/src/core/sync-v2/reactions.js

@@ -0,0 +1,236 @@
+/**
+ * Retrieve existing reactions from Zalo's server over the socket.
+ *
+ * Reactions are the one thing a transfer sync cannot restore — the Sync2
+ * payload has no reaction field — which this project long read as "a reaction
+ * not captured live is gone for good". That conclusion was wrong: Zalo Web
+ * fetches them over the SAME socket with cmd 610 (1-1) and cmd 611 (group),
+ * and fires both within ~1.4s of every connect (see the boot capture in
+ * agent/work/transfer-sync-v2). Measured live on a real account, one request
+ * pair returned 28 DM and 50 group reactions with full detail — target msgId,
+ * icon, rType and the reacting user — while the local cache held one row.
+ *
+ * zca-js already speaks the request (`listener.requestOldReactions`) and emits
+ * the objects (`old_reactions`), so no patch is needed. Two things it does not
+ * do, which is why this module exists:
+ *
+ *  1. It surfaces neither `lastActionId` nor `more`, so a caller using only the
+ *     event gets exactly one page and cannot tell whether more exist. The
+ *     server said `more: 1` for groups on the very first probe. We read those
+ *     fields off the raw socket, the same way SyncV2 taps cmd 601.
+ *  2. Its old-reactions handler omits the `JSON.parse(content)` its live
+ *     handler performs, so `content` arrives as a string.
+ *     `storeLiveReaction` absorbs both forms.
+ */
+
+import { decodeFrame } from "./index.js";
+import { storeLiveReaction } from "../live-store.js";
+
+/** zca-js ThreadType values. */
+const THREAD_USER = 0;
+const THREAD_GROUP = 1;
+
+/** Socket commands carrying the reaction backlog. */
+const CMD_DM = 610;
+const CMD_GROUP = 611;
+
+/** Default per-request deadline. A queue that has nothing to say says nothing. */
+export const DEFAULT_TIMEOUT_MS = 15000;
+
+/** Pages per thread type. The server pages with `more`; this is the runaway stop. */
+export const DEFAULT_MAX_PAGES = 20;
+
+/**
+ * Drain the reaction backlog for both thread types and store what comes back.
+ *
+ * The caller owns the socket: it must hold `daemon.lock`, start the listener
+ * and stop it afterwards — same contract as {@link backfillOverSocket}.
+ *
+ * @param {object} opts
+ * @param {import("zca-js").Listener} opts.listener - a started zca-js listener
+ * @param {number} [opts.timeoutMs=15000] - per-page deadline
+ * @param {number} [opts.maxPages=20] - cap per thread type
+ * @param {boolean} [opts.applyRemovals=true] - apply backlog entries with an empty
+ *   icon (un-reacts). ON by default, because the backlog is an ordered ACTION
+ *   LOG, not a snapshot of current state: it replays adds and removals in
+ *   sequence, so skipping the removals leaves reactions the user already took
+ *   off. Measured — one message came back with four reaction events where the
+ *   app showed one; replaying in order reproduced the one.
+ * @param {(p: object) => void} [opts.onProgress]
+ * @returns {Promise<{pages: number, received: number, stored: number, changed: number,
+ *   skippedRemovals: number, byType: object, truncated: boolean, unresolved: object[]}>}
+ *   `unresolved` holds the reactions whose target message was not in the cache
+ *   when they arrived. The backlog reaches further back than a windowed
+ *   restore, and when the drain runs beside a restore its target may simply
+ *   not be written yet -- so a caller that has since stored more messages can
+ *   pass these back through storeLiveReaction once more.
+ */
+export async function drainReactions(opts = {}) {
+    const {
+        listener,
+        timeoutMs = DEFAULT_TIMEOUT_MS,
+        maxPages = DEFAULT_MAX_PAGES,
+        applyRemovals = true,
+        onProgress = () => {},
+    } = opts;
+    if (!listener) throw new Error("drainReactions needs a started listener");
+
+    const stats = {
+        pages: 0,
+        received: 0,
+        stored: 0,
+        changed: 0,
+        skippedRemovals: 0,
+        byType: { dm: 0, group: 0 },
+        truncated: false,
+        unresolved: [],
+    };
+
+    // The raw tap is the only place `more` and `lastActionId` exist. Without it
+    // a drain stops after one page and reports success.
+    const envelopes = [];
+    const onRaw = (buf) => {
+        if (!(buf instanceof Buffer) || buf.length < 4) return;
+        const cmd = buf.readUInt16LE(1);
+        if (cmd !== CMD_DM && cmd !== CMD_GROUP) return;
+        try {
+            const parsed = JSON.parse(buf.subarray(4).toString("utf8"));
+            if (typeof parsed.data !== "string") return;
+            // decodeFrame is the repo's own mirror of zca-js's decodeEventData;
+            // the library does not export its internals.
+            const data = decodeFrame(parsed, listener.cipherKey)?.data;
+            envelopes.push({ cmd, lastActionId: data?.lastActionId, more: Number(data?.more) || 0 });
+        } catch {
+            /* a frame we cannot read is not a frame we need */
+        }
+    };
+
+    /** One request/response round for a thread type. */
+    const page = (threadType, anchor) =>
+        new Promise((resolve) => {
+            const cmd = threadType === THREAD_USER ? CMD_DM : CMD_GROUP;
+            let settled = false;
+            const before = envelopes.length;
+
+            const finish = (objs) => {
+                if (settled) return;
+                settled = true;
+                listener.removeListener("old_reactions", handler);
+                clearTimeout(timer);
+                // Match the envelope to this round by command.
+                const env = envelopes.slice(before).find((e) => e.cmd === cmd) || {};
+                resolve({ objs, more: env.more || 0, lastActionId: env.lastActionId });
+            };
+
+            const handler = (objs, isGroup) => {
+                const want = threadType === THREAD_GROUP;
+                if (isGroup !== want) return; // the other type's answer
+                // The envelope can land after the event; give it a tick.
+                setTimeout(() => finish(objs || []), 50);
+            };
+            const timer = setTimeout(() => finish(null), timeoutMs);
+
+            listener.on("old_reactions", handler);
+            try {
+                listener.requestOldReactions(threadType, anchor ?? null);
+            } catch (e) {
+                onProgress({ phase: "warn", detail: `request failed: ${e.message}` });
+                finish(null);
+            }
+        });
+
+    listener.ws?.on("message", onRaw);
+    try {
+        for (const threadType of [THREAD_USER, THREAD_GROUP]) {
+            const label = threadType === THREAD_USER ? "dm" : "group";
+            let anchor = null;
+            for (let p = 0; p < maxPages; p++) {
+                const { objs, more, lastActionId } = await page(threadType, anchor);
+                if (objs === null) {
+                    onProgress({ phase: "timeout", type: label, detail: `no answer within ${timeoutMs}ms` });
+                    break;
+                }
+                stats.pages++;
+                stats.received += objs.length;
+                for (const r of objs) {
+                    const icon = reactionIcon(r);
+                    if (!icon && !applyRemovals) {
+                        stats.skippedRemovals++;
+                        continue;
+                    }
+                    const res = storeLiveReaction(r, { source: "backlog" });
+                    if (res.stored) {
+                        stats.stored++;
+                        stats.changed += res.changed || 0;
+                        stats.byType[label]++;
+                    } else if (res.reason === "reaction target not resolvable") {
+                        stats.unresolved.push(r);
+                    }
+                }
+                onProgress({
+                    phase: "page",
+                    type: label,
+                    page: p + 1,
+                    received: objs.length,
+                    stored: stats.stored,
+                    more,
+                });
+                // `more` is the server's own "there is another page"; without a
+                // fresh anchor we would re-request the same one forever.
+                if (!more || !lastActionId || String(lastActionId) === String(anchor)) break;
+                anchor = String(lastActionId);
+                if (p === maxPages - 1) stats.truncated = true;
+            }
+        }
+    } finally {
+        try {
+            listener.ws?.off?.("message", onRaw);
+        } catch {
+            /* the socket may already be gone */
+        }
+    }
+
+    return stats;
+}
+
+/**
+ * Replay reactions the drain could not place when they arrived.
+ *
+ * `drainReactions` hands these back rather than dropping them: the backlog
+ * reaches further back than a windowed restore, so a reaction's target message
+ * may only be written after the drain saw it. A caller that has since stored
+ * more messages — `zalo-agent sync`, which restores before it drains — replays
+ * them through here.
+ *
+ * This WRITES, so it belongs in whichever process owns the db: the CLI when it
+ * holds the socket itself, the daemon when the stage runs through its channel.
+ * Shared so the two paths cannot drift.
+ *
+ * @param {object[]} [unresolved] - `drainReactions()` stats.unresolved
+ * @returns {number} how many were placed this time
+ */
+export function placeUnresolvedReactions(unresolved = []) {
+    let placed = 0;
+    for (const r of unresolved || []) {
+        if (storeLiveReaction(r, { source: "backlog" }).stored) placed++;
+    }
+    return placed;
+}
+
+/**
+ * The icon on a reaction object, whichever form its content arrived in.
+ *
+ * @param {object} reaction
+ * @returns {string}
+ */
+function reactionIcon(reaction) {
+    const c = reaction?.data?.content;
+    if (typeof c === "string") {
+        try {
+            return JSON.parse(c)?.rIcon ?? "";
+        } catch {
+            return "";
+        }
+    }
+    return c?.rIcon ?? "";
+}

package/src/core/sync-v2/renewlink.js

@@ -0,0 +1,124 @@
+/**
+ * Refresh an expired media URL — the same call Zalo Web makes when a photo,
+ * video or file in the timeline has aged past its signed URL.
+ *
+ *   POST {fileDomain}/api/message/renewlink   (cmd 12094)
+ *     params = AES({ toId, msgType, msgInfo, clientId, imei, isGroup })
+ *     msgInfo = JSON({ normalUrl, hdUrl, thumbUrl, oriUrl, isE2EE, isOriginal })
+ *
+ * Zalo media lives in three places, and this covers only the first:
+ *
+ *   1. Zalo's CDN — the `href`/`thumb` in the sync payload. The signature has
+ *      a lifetime tied to the message's age; while the server still holds the
+ *      file, renewlink hands back fresh URLs. That is this module.
+ *   2. zCloud (personal cloud) — a per-message E2EE backup, looked up by msgId.
+ *      See ./zcloud.js.
+ *   3. The sending device itself. No server path exists; the phone's own
+ *      re-upload hints (`fileUrlToRenew`, `video_url_to_renew`) ride along in
+ *      the sync payload and are preserved on the attachment record, but only
+ *      the Zalo mobile client can act on them.
+ *
+ * Built on zca-js's apiFactory so the authenticated envelope matches what the
+ * file service expects, the same way ./gid.js reaches /api/gid/decrypt.
+ */
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+const require = createRequire(import.meta.url);
+
+let _utils = null;
+function zcaUtils() {
+    if (_utils) return _utils;
+    _utils = require(join(dirname(require.resolve("zca-js")), "utils.cjs"));
+    return _utils;
+}
+
+/**
+ * Zalo Web strips its internal `jxl` marker before sending a URL back for
+ * renewal. Our URLs come straight off the wire and normally have none, so this
+ * is defensive rather than load-bearing.
+ */
+function removeJxlProtocol(url) {
+    if (typeof url !== "string") return url;
+    return url.replace(/^jxl:\/\//i, "").replace(/\/jxl\//i, "/");
+}
+
+/** Group threads (and the self-chat) take the group form of the request. */
+function isGroupThread(threadType) {
+    return threadType === "group";
+}
+
+/**
+ * Build a renewlink caller bound to this session.
+ *
+ * @param {object} api - logged-in zca-js api
+ * @returns {(req: object) => Promise<object>}
+ */
+export function makeRenewLink(api) {
+    const zu = zcaUtils();
+    const base = `${api.zpwServiceMap.file[0]}/api/message/renewlink`;
+    return zu.apiFactory()((_api, ctx, utils) => async ({ threadId, threadType, msgType, msgInfo, clientId }) => {
+        const info = {
+            ...msgInfo,
+            normalUrl: removeJxlProtocol(msgInfo.normalUrl),
+            hdUrl: removeJxlProtocol(msgInfo.hdUrl),
+            thumbUrl: removeJxlProtocol(msgInfo.thumbUrl),
+            oriUrl: removeJxlProtocol(msgInfo.oriUrl),
+            isE2EE: 0,
+            isOriginal: 0,
+        };
+        for (const k of Object.keys(info)) if (info[k] === undefined) delete info[k];
+
+        const params = {
+            toId: String(threadId),
+            msgType: Number(msgType) || 0,
+            msgInfo: JSON.stringify(info),
+            clientId: String(clientId || Date.now()),
+            imei: ctx.imei,
+            isGroup: isGroupThread(threadType) ? 1 : 0,
+        };
+        const enc = utils.encodeAES(JSON.stringify(params));
+        if (!enc) throw new Error("failed to encrypt renewlink params");
+        const resp = await utils.request(utils.makeURL(base), {
+            method: "POST",
+            body: new URLSearchParams({ params: enc }),
+        });
+        return utils.resolve(resp);
+    })(api.getContext(), api);
+}
+
+/**
+ * Pull refreshed URLs out of a renewlink response.
+ *
+ * The response envelope is not documented anywhere and Zalo has more than one
+ * shape for "here is the message again", so this reads defensively: it accepts
+ * the URL bag at the top level, under `data`, or nested one level deeper, and
+ * returns null when it finds nothing it recognises rather than guessing.
+ *
+ * @param {object} resp
+ * @returns {{normalUrl?: string, hdUrl?: string, thumbUrl?: string, oriUrl?: string}|null}
+ */
+export function extractRenewedUrls(resp) {
+    const KEYS = ["normalUrl", "hdUrl", "thumbUrl", "oriUrl", "url", "href"];
+    const candidates = [resp, resp?.data, resp?.data?.data, resp?.data?.msgInfo, resp?.msgInfo];
+    for (let c of candidates) {
+        if (typeof c === "string") {
+            try {
+                c = JSON.parse(c);
+            } catch {
+                continue;
+            }
+        }
+        if (!c || typeof c !== "object") continue;
+        const found = {};
+        for (const k of KEYS) if (typeof c[k] === "string" && /^https?:\/\//.test(c[k])) found[k] = c[k];
+        if (Object.keys(found).length) {
+            // `url`/`href` are aliases for the main download link.
+            if (!found.normalUrl && (found.url || found.href)) found.normalUrl = found.url || found.href;
+            delete found.url;
+            delete found.href;
+            return found;
+        }
+    }
+    return null;
+}

package/src/core/sync-v2/senders.js

@@ -0,0 +1,61 @@
+import { resolveNonFriendDms } from "./gid.js";
+
+const NOISED_ID = /^[0-9A-V]{32}$/;
+
+/**
+ * Build a per-restore sender resolver. Only DM entries can seed user identities:
+ * a group's globalId identifies the conversation, never one of its senders.
+ * Unknown senders use the existing profile gid/decrypt + getUserInfo path.
+ * Failures leave the original ID intact and are attempted once per restore.
+ *
+ * @param {object} api - authenticated zca-js API
+ * @param {Map<string, {id: string, name: string, type: string}>} threadMap
+ * @param {object} [options]
+ * @param {Function} [options.resolveUsers] - batched global-ID resolver
+ * @param {Function} [options.log] - diagnostic sink (never stdout in MCP mode)
+ * @returns {{prepare: Function, get: Function}} chunk preparation and row lookup
+ */
+export function createSenderResolver(api, threadMap, { resolveUsers = resolveNonFriendDms, log = () => {} } = {}) {
+    const users = new Map();
+    const attempted = new Set();
+    for (const [gid, user] of threadMap) {
+        if (user.type === "dm")
+            users.set(gid, { id: String(user.id), name: user.snapshotName ?? user.zaloName ?? user.name ?? "" });
+    }
+
+    return {
+        async prepare(messages) {
+            // Conversation resolution may have added non-friend users since
+            // this resolver was constructed. Do not repeat those lookups.
+            for (const [gid, user] of threadMap) {
+                if (user.type === "dm")
+                    users.set(gid, {
+                        id: String(user.id),
+                        name: user.snapshotName ?? user.zaloName ?? user.name ?? "",
+                    });
+            }
+            const missing = [...new Set(messages.map((m) => String(m.senderId || "")))].filter(
+                (id) => NOISED_ID.test(id) && !users.has(id) && !attempted.has(id),
+            );
+            if (!missing.length) return;
+            for (const id of missing) attempted.add(id);
+            try {
+                const resolved = await resolveUsers(api, missing, log);
+                for (const id of missing) {
+                    const user = resolved.get(id);
+                    // Never treat a missing mapping, or another opaque ID, as
+                    // a canonical user. Keep unknown senders explicitly unknown.
+                    if (user && /^[1-9][0-9]*$/.test(String(user.id))) {
+                        users.set(id, { id: String(user.id), name: user.name || "" });
+                    }
+                }
+            } catch {
+                log("sender identity lookup failed; unresolved sender IDs are preserved");
+            }
+        },
+        get(senderId) {
+            const id = String(senderId || "");
+            return users.get(id) || { id, name: "" };
+        },
+    };
+}

package/src/core/sync-v2/zcloud-cipher.js

@@ -0,0 +1,88 @@
+/**
+ * zCloud's params/response cipher — a Node-crypto port of Zalo Web's own.
+ *
+ * zCloud (`zcld.chat.zalo.me`) does not use the session cipher every other
+ * Zalo endpoint uses (the session key with an all-zero IV — zca-js's
+ * `encodeAES`/`decodeAES`). Zalo Web's zCloud layer keys a separate AES-CBC
+ * with `enk`, the second half of the account's cloud viewer key pair, and
+ * prepends a fresh random IV to every ciphertext:
+ *
+ *   encryptAES(json, enk) = base64( iv16 ‖ AES-CBC-PKCS7(utf8(json), key = base64decode(enk)) )
+ *   decryptAES(b64,  enk) = the same, reading the first 16 bytes as the IV
+ *   encodeParams(obj)     = encodeURIComponent(encryptAES(JSON.stringify(obj), enk))
+ *
+ * Source: bundle 1.e0ef5e98f8f9d8970e2c.js, module `98yS` (@2868035) and
+ * `tP1L.encodeParams`, build 826674fb31d2af1b2b59, captured 2026-09-29.
+ *
+ * CryptoJS picks the AES variant from the key's length, so a 16/24/32-byte enk
+ * means AES-128/192/256; any other length is refused rather than guessed.
+ * Decryption also refuses bytes that are not valid UTF-8 — CryptoJS's
+ * `toString(Utf8)` throws "Malformed UTF-8 data" in the same case — so a wrong
+ * key surfaces as an error instead of as garbage.
+ *
+ * Key material never leaves these functions and is never logged.
+ */
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+
+const IV_BYTES = 16;
+const BLOCK_BYTES = 16;
+const ALGORITHM_BY_KEY_BYTES = { 16: "aes-128-cbc", 24: "aes-192-cbc", 32: "aes-256-cbc" };
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+
+/** Decode enk into an AES key and the cipher name its length implies. */
+function keyOf(enk) {
+    const key = typeof enk === "string" && enk ? Buffer.from(enk, "base64") : Buffer.alloc(0);
+    const algorithm = ALGORITHM_BY_KEY_BYTES[key.length];
+    if (!algorithm) {
+        throw new Error(`zCloud enk must decode to a 16-, 24- or 32-byte AES key (got ${key.length} bytes)`);
+    }
+    return { key, algorithm };
+}
+
+/**
+ * Encrypt a string the way Zalo Web's zCloud layer does.
+ *
+ * @param {string} plaintext
+ * @param {string} enk - base64 AES key from the viewer key pair
+ * @returns {string} base64 of a random 16-byte IV followed by the ciphertext
+ */
+export function encryptZCloud(plaintext, enk) {
+    const { key, algorithm } = keyOf(enk);
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv(algorithm, key, iv);
+    return Buffer.concat([iv, cipher.update(String(plaintext), "utf8"), cipher.final()]).toString("base64");
+}
+
+/**
+ * Decrypt a zCloud ciphertext (a reply's `data`, or a request's `params`).
+ *
+ * Tolerates a percent-encoded value — base64 never contains `%`, so decoding
+ * one cannot corrupt a plain value.
+ *
+ * @param {string} ciphertext - base64(iv16 ‖ ciphertext)
+ * @param {string} enk - base64 AES key from the viewer key pair
+ * @returns {string} the UTF-8 plaintext
+ */
+export function decryptZCloud(ciphertext, enk) {
+    const { key, algorithm } = keyOf(enk);
+    let text = String(ciphertext ?? "");
+    if (text.includes("%")) text = decodeURIComponent(text);
+    const raw = Buffer.from(text, "base64");
+    if (raw.length <= IV_BYTES || (raw.length - IV_BYTES) % BLOCK_BYTES !== 0) {
+        throw new Error("zCloud ciphertext is not a 16-byte IV followed by whole AES blocks");
+    }
+    const decipher = createDecipheriv(algorithm, key, raw.subarray(0, IV_BYTES));
+    const plain = Buffer.concat([decipher.update(raw.subarray(IV_BYTES)), decipher.final()]);
+    return utf8.decode(plain);
+}
+
+/**
+ * Zalo Web's `encodeParams`: the value of a zCloud request's `params` query field.
+ *
+ * @param {object} params
+ * @param {string} enk
+ * @returns {string} encodeURIComponent(base64(iv ‖ ciphertext))
+ */
+export function encodeZCloudParams(params, enk) {
+    return encodeURIComponent(encryptZCloud(JSON.stringify(params), enk));
+}