@ardennguyen/zalo-agent-cli 2.5.9 → 3.0.0

package/src/zalo/kernel/session.js

@@ -0,0 +1,261 @@
+/**
+ * The session context: the one object a login fills in and every call reads.
+ *
+ * Its field names are the ones the engine has always read (spec-kernel 2.3), so the 40-odd
+ * `api.getContext()` call sites did not change: `API_TYPE`, `API_VERSION`, `imei`, `cookie` (a tough-cookie jar),
+ * `userAgent`, `language`, `secretKey` (`zpw_enk`), `uid`, `settings`, `extraVer`, `loginInfo`, `kickout`,
+ * `options.polyfill` (the fetch every request goes through), `options.logging`, `options.selfListen`,
+ * `options.agent` (the WebSocket's proxy agent only; fetch takes its proxy through `polyfill`), and
+ * `uploadCallbacks` (the upload settlement registry below).
+ *
+ * The context is the same object for a session's whole life: caches are keyed by it.
+ */
+import { EventEmitter } from "node:events";
+
+/** How long an upload settlement waiter (or a plain callback entry) is kept before it is dropped. */
+export const UPLOAD_ENTRY_TTL_MS = 5 * 60 * 1000;
+
+/** How long a settlement that arrived before anyone waited for it is kept. */
+export const EARLY_SETTLE_TTL_MS = 60 * 1000;
+
+/**
+ * A new session context. Nothing is logged in yet: `secretKey` is null until a login sets it.
+ *
+ * @param {object} p
+ * @param {number} p.apiType - the client type announced (30)
+ * @param {number} p.apiVersion - the client version announced (from `src/zalo/profile.js`)
+ * @param {string} [p.userAgent]
+ * @param {string} [p.imei]
+ * @param {string} [p.language]
+ * @param {typeof fetch} [p.fetch] - the fetch every request goes through; `globalThis.fetch` at this moment
+ *   otherwise (tests replace it before a login so the session captures their fake)
+ * @param {object} [p.wsAgent] - a proxy agent for the WebSocket
+ * @param {boolean} [p.selfListen] - deliver our own messages to the listener too
+ * @param {Function} [p.imageMetadataGetter] - `(path) => {width, height, size}` for uploads
+ * @returns {object} the context
+ */
+export function createSession({
+    apiType,
+    apiVersion,
+    userAgent,
+    imei,
+    language,
+    fetch: fetchFn,
+    wsAgent,
+    selfListen = false,
+    imageMetadataGetter,
+} = {}) {
+    const ctx = {
+        API_TYPE: apiType,
+        API_VERSION: apiVersion,
+        uploadCallbacks: createUploadRegistry(),
+        options: {
+            selfListen,
+            logging: false,
+            polyfill: fetchFn ?? globalThis.fetch,
+        },
+        secretKey: null,
+    };
+    if (wsAgent) ctx.options.agent = wsAgent;
+    if (imageMetadataGetter) ctx.options.imageMetadataGetter = imageMetadataGetter;
+    if (userAgent !== undefined) ctx.userAgent = userAgent;
+    if (imei !== undefined) ctx.imei = imei;
+    if (language !== undefined) ctx.language = language;
+    return ctx;
+}
+
+/**
+ * @typedef {object} UploadSettlement
+ * @property {string} fileId
+ * @property {string|null} url
+ * @property {string|null} kind - "file_done", "video_done", "photo_success", ...
+ * @property {unknown} data - what the listener hands over: the whole 601 control
+ */
+
+/**
+ * The registry an upload waits on for the socket's word that the server has the file (the 601 control).
+ *
+ * It is a `Map` (`get`, `set`, `delete`, `has`), with each entry dropped after {@link UPLOAD_ENTRY_TTL_MS}, so an
+ * upload and a listener that use `ctx.uploadCallbacks` as a plain map keep working on it. On top of that:
+ *
+ * - `waitFor(fileId, {timeoutMs, signal})` resolves with the settlement when it comes;
+ * - `settle(fileId, {url, kind, data})` is the one call a listener makes for a finished upload. A function entry
+ *   under the id (the upload stands one there) is removed and called with `{fileUrl, fileId}`, the shape a Map-only
+ *   listener hands it; every waiter gets the settlement. Only when neither took it is it kept for
+ *   {@link EARLY_SETTLE_TTL_MS}, so a `waitFor` that comes a moment later still gets it (a plain map loses such a 601),
+ *   and nothing is left behind once someone did.
+ *
+ * Timers never keep the process alive.
+ */
+export class UploadRegistry extends Map {
+    constructor() {
+        super();
+        /** @type {Map<string, {settlement: UploadSettlement, timer: NodeJS.Timeout}>} */
+        this.early = new Map();
+        /** @type {Map<string, NodeJS.Timeout>} */
+        this.timers = new Map();
+        this.events = new EventEmitter();
+        this.events.setMaxListeners(0);
+    }
+
+    /**
+     * Register an entry (a plain callback, or anything an upload keeps), dropped after `ttl`.
+     *
+     * @param {string} key
+     * @param {unknown} value
+     * @param {number} [ttl]
+     * @returns {this}
+     */
+    set(key, value, ttl = UPLOAD_ENTRY_TTL_MS) {
+        const id = String(key);
+        clearTimeout(this.timers?.get(id));
+        if (this.timers) {
+            const timer = setTimeout(() => {
+                this.timers.delete(id);
+                super.delete(id);
+            }, ttl);
+            timer.unref?.();
+            this.timers.set(id, timer);
+        }
+        return super.set(id, value);
+    }
+
+    /**
+     * @param {string} key
+     * @returns {unknown}
+     */
+    get(key) {
+        return super.get(String(key));
+    }
+
+    /**
+     * @param {string} key
+     * @returns {boolean}
+     */
+    has(key) {
+        return super.has(String(key));
+    }
+
+    /**
+     * @param {string} key
+     * @returns {boolean}
+     */
+    delete(key) {
+        const id = String(key);
+        clearTimeout(this.timers?.get(id));
+        this.timers?.delete(id);
+        return super.delete(id);
+    }
+
+    /**
+     * Hand a settlement to whoever waits for this file. A function entry registered as a plain callback is removed and
+     * called with `{fileUrl: url, fileId}`; every waiter gets `{fileId, url, kind, data}`. With nobody to take it,
+     * the settlement is kept for a short while.
+     *
+     * @param {string|number} fileId - as the control carries it (handed to a function entry unchanged)
+     * @param {{url?: string|null, kind?: string|null, data?: unknown}} [info]
+     * @returns {boolean} whether a waiter or a callback took it
+     */
+    settle(fileId, info = {}) {
+        const id = String(fileId);
+        const settlement = {
+            fileId: id,
+            url: info?.url ?? null,
+            kind: info?.kind ?? null,
+            data: info?.data ?? null,
+        };
+        let taken = false;
+        const entry = super.get(id);
+        if (typeof entry === "function") {
+            this.delete(id);
+            taken = true;
+            try {
+                entry({ fileUrl: settlement.url, fileId });
+            } catch {
+                /* a callback's own failure is its own */
+            }
+        }
+        if (this.events.listenerCount(id) > 0) {
+            this.events.emit(id, settlement);
+            taken = true;
+        }
+        if (!taken) {
+            clearTimeout(this.early.get(id)?.timer);
+            const timer = setTimeout(() => this.early.delete(id), EARLY_SETTLE_TTL_MS);
+            timer.unref?.();
+            this.early.set(id, { settlement, timer });
+        }
+        return taken;
+    }
+
+    /**
+     * Wait for a file's settlement.
+     *
+     * @param {string} fileId
+     * @param {{timeoutMs?: number, signal?: AbortSignal}} [opts] - no timeout unless given
+     * @returns {Promise<UploadSettlement>}
+     * @throws {Error} with `.code` "UPLOAD_TIMEOUT" after `timeoutMs`, or the signal's reason when aborted
+     */
+    waitFor(fileId, { timeoutMs = 0, signal } = {}) {
+        const id = String(fileId);
+        const early = this.early.get(id);
+        if (early) {
+            clearTimeout(early.timer);
+            this.early.delete(id);
+            return Promise.resolve(early.settlement);
+        }
+        return new Promise((resolve, reject) => {
+            let timer = null;
+            const done = () => {
+                clearTimeout(timer);
+                this.events.off(id, onSettle);
+                signal?.removeEventListener("abort", onAbort);
+            };
+            const onSettle = (s) => {
+                done();
+                resolve(s);
+            };
+            const onAbort = () => {
+                done();
+                reject(signal.reason ?? new Error("aborted"));
+            };
+            if (signal?.aborted) return onAbort();
+            this.events.on(id, onSettle);
+            signal?.addEventListener("abort", onAbort, { once: true });
+            if (timeoutMs > 0) {
+                timer = setTimeout(() => {
+                    done();
+                    const err = new Error(`The server did not confirm the upload within ${timeoutMs} ms`);
+                    err.code = "UPLOAD_TIMEOUT";
+                    reject(err);
+                }, timeoutMs);
+                timer.unref?.();
+            }
+        });
+    }
+}
+
+/**
+ * A new upload settlement registry (see {@link UploadRegistry}).
+ *
+ * @returns {UploadRegistry}
+ */
+export function createUploadRegistry() {
+    return new UploadRegistry();
+}
+
+/**
+ * A per-session source of client ids (`clientId`, echoed back as a message's `cliMsgId`): the clock, but never the
+ * same value twice and never going back. Two sends in one millisecond get two ids.
+ *
+ * @param {() => number} [now]
+ * @returns {() => number} each call returns `max(now(), last + 1)`
+ */
+export function createClientIds(now = Date.now) {
+    let last = 0;
+    return () => {
+        const t = Math.floor(Number(now()));
+        last = t > last ? t : last + 1;
+        return last;
+    };
+}

package/src/zalo/kernel/zcloud-cipher.js

@@ -0,0 +1,83 @@
+/**
+ * zCloud's params/response cipher, on Node crypto.
+ *
+ * zCloud (`zcld.chat.zalo.me`) does not use the session cipher every other
+ * Zalo endpoint uses (the session key with an all-zero IV — src/zalo/kernel/cipher.js). zCloud 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))
+ *
+ * The AES variant follows 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, 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 zCloud expects.
+ *
+ * @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);
+}
+
+/**
+ * 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));
+}

package/src/zalo/kickout.js

@@ -0,0 +1,136 @@
+/**
+ * Why was this session ended? (plan item L12b)
+ *
+ * After a kick the client asks Zalo for the reason:
+ * `POST {aext}/api/session/kickout-info` with the form field `token`. It is a read: it changes nothing on the
+ * server. The answer is shown to the person ("you logged in on a different browser") instead of a bare disconnect.
+ *
+ * Where the key comes from (seen live, 2026-10-26): the **getLoginInfo** answer
+ * carries `auth_ext_info: {viewer_key, enk}`, and the client keeps both. The viewer
+ * key (334 characters) is the form's `token`; the answer is sealed with `enk` (24 characters, a base64 AES-128 key)
+ * in the session cipher's shape (zero IV), and opens to `{error_code, error_message, data: {kickoutSrc, kickoutTs}}`.
+ * The zCloud key pair (`zcloud`, 216 characters) is a different key and gets error 112, which is how the first
+ * attempt at this went wrong. `kickoutTs` is the moment the session was replaced, in seconds.
+ *
+ * What `kickoutSrc` means is the server's own table, `settings.features.kick_out_config[src]`: a title and a text in
+ * English and Vietnamese. {@link describeKickout} reads it.
+ *
+ * A client that has no keys cannot ask, and says so rather than guessing: this function returns null when it
+ * cannot learn the reason, for any cause. A kick has already been handled by the time it runs, so failing here is
+ * never an error worth raising.
+ */
+import { decryptZCloud } from "./kernel/zcloud-cipher.js";
+import { openSession } from "./kernel/cipher.js";
+import { buildUrl, httpRequest } from "./kernel/http.js";
+
+/**
+ * The keys the kickout lookup needs, as the login kept them.
+ *
+ * @param {object} api - a session from {@link loginWithSession}
+ * @returns {{viewerKey: string, enk: string}|null} null when the server gave this session none
+ */
+export function kickoutKeysOf(api) {
+    const z = api?.getContext?.()?.kickout;
+    return z?.viewerKey && z?.enk ? { viewerKey: String(z.viewerKey), enk: String(z.enk) } : null;
+}
+
+/**
+ * Open an answer sealed with `enk`: the session cipher's shape first (what Zalo does, seen live), then zCloud's.
+ *
+ * @returns {object|null}
+ */
+function openSealed(data, enk) {
+    try {
+        const text = openSession(enk, data);
+        if (text) return JSON.parse(text);
+    } catch {
+        /* not that cipher */
+    }
+    try {
+        return JSON.parse(decryptZCloud(data, enk));
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * The words for a kick, from the server's own table.
+ *
+ * @param {{kickoutSrc?: number, kickoutTs?: number}|null} info - what {@link fetchKickoutInfo} returned
+ * @param {object} [settings] - the session's `settings` (`features.kick_out_config`)
+ * @param {"en"|"vi"} [lang]
+ * @returns {{src: number|null, at: string|null, title: string|null, text: string|null}} fields the server did not
+ *   describe are null
+ */
+export function describeKickout(info, settings, lang = "en") {
+    const cfg = settings?.features?.kick_out_config?.[String(info?.kickoutSrc)];
+    const pick = (v) => (v && typeof v === "object" ? (v[lang] ?? v.en ?? null) : null);
+    const ts = Number(info?.kickoutTs);
+    return {
+        src:
+            Number.isFinite(Number(info?.kickoutSrc)) && info?.kickoutSrc !== undefined
+                ? Number(info.kickoutSrc)
+                : null,
+        at: ts > 0 ? new Date(ts * 1000).toISOString() : null,
+        title: pick(cfg?.title),
+        text: Array.isArray(cfg?.content) ? cfg.content.map(pick).filter(Boolean).join(" ") || null : null,
+    };
+}
+
+/**
+ * Ask Zalo why the session ended.
+ *
+ * @param {object} api - a session (its key may already be refused)
+ * @param {{viewerKey: string, enk: string}|null} keys - from {@link kickoutKeysOf}
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutMs]
+ * @returns {Promise<object|null>} what Zalo said, or null when the reason could not be learned
+ */
+export async function fetchKickoutInfo(api, keys, { timeoutMs = 5000 } = {}) {
+    if (!keys || typeof keys.viewerKey !== "string" || !keys.viewerKey || typeof keys.enk !== "string" || !keys.enk) {
+        return null;
+    }
+    try {
+        const ctx = api.getContext();
+        const host = ctx.loginInfo?.zpw_service_map_v3?.aext?.[0];
+        if (!host) return null;
+        const url = buildUrl(ctx, `${host}/api/session/kickout-info`, {});
+        const res = await httpRequest(ctx, url, {
+            method: "POST",
+            body: new URLSearchParams({ token: keys.viewerKey }),
+            timeoutMs,
+        });
+        const body = JSON.parse(await res.text());
+        if (body?.error_code !== undefined && Number(body.error_code) !== 0) return null;
+        let data = body?.data;
+        if (typeof data === "string" && data !== "") {
+            // Sealed with `enk`, which a refused session key does not affect.
+            const inner = openSealed(data, keys.enk);
+            if (!inner || typeof inner !== "object") return null;
+            if (inner.error_code !== undefined && Number(inner.error_code) !== 0) return null;
+            data = inner.data ?? inner;
+        }
+        return data && typeof data === "object" ? data : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Ask Zalo why the session ended, with the keys the login kept, and add the server's own words for it.
+ *
+ * @param {object} api - a session from {@link loginWithSession}
+ * @returns {Promise<object|null>} `{kickoutSrc, kickoutTs, src, at, title, text}`, or null when the reason could not
+ *   be learned
+ */
+export async function lookupKickout(api) {
+    const info = await fetchKickoutInfo(api, kickoutKeysOf(api));
+    if (!info) return info;
+    let settings;
+    try {
+        settings = api.getContext?.()?.settings;
+    } catch {
+        /* no settings: the numbers alone are shown */
+    }
+    return { ...info, ...describeKickout(info, settings) };
+}