@ardennguyen/zalo-agent-cli 2.5.9 → 3.0.0

package/src/zalo/kernel/http.js

@@ -0,0 +1,360 @@
+/**
+ * The transport every Zalo call goes through: URLs, headers, cookies, redirects, timeouts, and the reply envelope.
+ *
+ * Wire facts this follows (spec-kernel 6-8), with the points where the previous engine differed:
+ *
+ * - URL (D1): `zpw_ver` and `zpw_type` come first, then the endpoint's own parameters in insertion order, each value
+ *   escaped with `encodeURIComponent`. The login host's calls carry no version pair (`{version: false}`).
+ * - Headers of an API call (an XHR): `Accept: application/json, text/plain, * / *` (no spaces), `Origin:
+ *   https://chat.zalo.me`, `Referer: https://chat.zalo.me/`, `User-Agent`, `Accept-Language`, and `Content-Type:
+ *   application/x-www-form-urlencoded` on a form POST only (D2). `Accept-Encoding` is left to fetch (D4). Names are
+ *   compared without regard to case, so a caller's `origin` replaces the default `Origin` instead of joining it.
+ * - Cookies (D5, D6): the `Cookie` header is the jar's answer for the full URL; every `Set-Cookie` is stored against
+ *   the URL of the request that received it.
+ * - Redirects (D7): `follow: "jar"` follows them here, as a browser navigation does: at most 10 hops, a relative
+ *   `Location` resolved against the current URL, 301/302/303 become a GET without a body, 307/308 keep both, every
+ *   hop's cookies stored, each hop sent with navigation headers. The `Referer` stays the page that started the
+ *   navigation (cut to its origin on a cross-origin hop) and `sec-fetch-site` is the initiator's relation to each
+ *   hop, never better than an earlier hop's, as the Fetch standard has it.
+ * - Timeout: 10 s unless the caller says otherwise; `timeoutMs: 0` waits as long as it takes.
+ * - The reply: HTTP 2xx, outer `error_code` 0, then (for a session reply) the `data` opened with the session key and
+ *   its inner `error_code` 0; the answer is the inner `data`. Errors are thrown as `ZaloApiError(message, code)`.
+ *
+ * The fetch called is always `ctx.options.polyfill` (the proxy fetch, the browser-header wrapper, upkeep's activity
+ * tracker and every test fake sit behind it). Nothing here writes to stdout or logs a cookie, key or id.
+ */
+import { Blob } from "node:buffer";
+import { ZaloApiError } from "../errors.js";
+import { openSession, sealSession } from "./cipher.js";
+import { cookieHeader, newJar, storeSetCookies } from "./cookies.js";
+import { ACCEPT_LANGUAGE } from "../profile.js";
+
+/** The default request timeout. */
+export const DEFAULT_TIMEOUT_MS = 10_000;
+
+/** The most redirects a navigation follows. */
+export const MAX_REDIRECTS = 10;
+
+/** The origin every API call carries. */
+const CHAT_ORIGIN = "https://chat.zalo.me";
+
+/** The `Accept-Language` of every call, from the client's identity in `src/zalo/profile.js` (spec-kernel D3). */
+export { ACCEPT_LANGUAGE };
+
+/** Headers of an XHR from the chat page. */
+const XHR_HEADERS = Object.freeze({
+    accept: "application/json, text/plain, */*",
+    origin: CHAT_ORIGIN,
+    referer: `${CHAT_ORIGIN}/`,
+});
+
+/** Headers of a page load (and of each hop of a redirect it follows). */
+export const NAVIGATION_HEADERS = Object.freeze({
+    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",
+});
+
+const FORM_TYPE = "application/x-www-form-urlencoded";
+const REDIRECT_STATUS = new Set([301, 302, 303, 307, 308]);
+
+/**
+ * A URL with Zalo's common query first.
+ *
+ * @param {{API_VERSION?: number, API_TYPE?: number}} ctx
+ * @param {string} base - a URL, possibly with a query already
+ * @param {Record<string, unknown>} [params] - appended in order; `undefined` values are left out, `null` is "null"
+ * @param {{version?: boolean}} [opts] - `version: false` for the login host's calls
+ * @returns {string}
+ */
+export function buildUrl(ctx, base, params = {}, { version = true } = {}) {
+    const url = new URL(base);
+    const pairs = [...url.searchParams.entries()];
+    const has = (name) => pairs.some(([k]) => k === name);
+    const head = [];
+    if (version) {
+        if (!has("zpw_ver")) head.push(["zpw_ver", String(ctx.API_VERSION)]);
+        if (!has("zpw_type")) head.push(["zpw_type", String(ctx.API_TYPE)]);
+    }
+    const tail = [];
+    for (const [k, v] of Object.entries(params ?? {})) {
+        if (v === undefined) continue;
+        tail.push([k, String(v)]);
+    }
+    url.search = "";
+    const query = [...head, ...pairs, ...tail]
+        .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+        .join("&");
+    return query ? `${url.toString()}?${query}` : url.toString();
+}
+
+/**
+ * Seal request params with the session key.
+ *
+ * @param {{secretKey?: string|null}} ctx
+ * @param {object|string} value - an object is JSON-encoded
+ * @returns {string} base64
+ * @throws {Error} when the session has no key (not logged in), or the key does not seal
+ */
+export function sealParams(ctx, value) {
+    if (!ctx?.secretKey) throw new Error("Not logged in. Run: zalo-agent login");
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    const sealed = sealSession(ctx.secretKey, text);
+    if (sealed === null) throw new ZaloApiError("Failed to encrypt params");
+    return sealed;
+}
+
+/**
+ * A multipart body: one file part plus plain fields. fetch writes the `multipart/form-data` content type and its
+ * boundary itself.
+ *
+ * @param {{field: string, filename: string, type?: string, bytes: Uint8Array|ArrayBuffer|Blob}} file
+ * @param {Record<string, string|number>} [fields]
+ * @returns {FormData}
+ */
+export function multipartBody(file, fields = {}) {
+    const form = new globalThis.FormData();
+    for (const [k, v] of Object.entries(fields)) form.append(k, String(v));
+    const blob =
+        file.bytes instanceof Blob
+            ? file.bytes
+            : new Blob([file.bytes], { type: file.type || "application/octet-stream" });
+    form.append(file.field, blob, file.filename);
+    return form;
+}
+
+/**
+ * Headers as a plain object of lowercase names.
+ *
+ * @param {Record<string, unknown>|Headers|null|undefined} headers
+ * @returns {Record<string, string>}
+ */
+export function lowerHeaders(headers) {
+    const out = {};
+    if (!headers) return out;
+    const entries = headers instanceof Headers ? headers.entries() : Object.entries(headers);
+    for (const [k, v] of entries) if (v !== undefined && v !== null) out[String(k).toLowerCase()] = String(v);
+    return out;
+}
+
+/** Whether a body is a URL-encoded form: a FormData or binary body gets its own content type. */
+function isForm(body) {
+    return body instanceof URLSearchParams || typeof body === "string";
+}
+
+/** The registrable part of a host, for the hosts Zalo uses (zalo.me, zaloapp.com, zdn.vn). */
+const siteOf = (host) => host.split(".").slice(-2).join(".");
+
+/** "same-origin", "same-site", "cross-site" (or "none" without an initiator) of a URL as seen from an origin. */
+function relation(fromOrigin, url) {
+    if (!fromOrigin) return "none";
+    const from = new URL(fromOrigin);
+    const to = new URL(url);
+    if (from.origin === to.origin) return "same-origin";
+    return from.protocol === to.protocol && siteOf(from.hostname) === siteOf(to.hostname) ? "same-site" : "cross-site";
+}
+
+const SITE_RANK = { none: 0, "same-origin": 1, "same-site": 2, "cross-site": 3 };
+
+/** The `Referer` a navigation hop carries: the initiator's full URL same-origin, its origin otherwise. */
+function referrerFor(initiator, url) {
+    if (!initiator) return null;
+    const from = new URL(initiator);
+    const to = new URL(url);
+    if (from.origin === to.origin) return from.toString();
+    if (from.protocol === "https:" && to.protocol === "http:") return null;
+    return `${from.origin}/`;
+}
+
+/**
+ * The headers of one request.
+ *
+ * @param {object} ctx
+ * @param {string} url
+ * @param {string} method
+ * @param {unknown} body
+ * @param {Record<string, string>} caller - lowercase names
+ * @param {"xhr"|"navigate"} kind
+ * @returns {Record<string, string>}
+ */
+function headersFor(ctx, url, method, body, caller, kind) {
+    const out = { ...(kind === "navigate" ? NAVIGATION_HEADERS : XHR_HEADERS) };
+    if (method !== "GET" && method !== "HEAD" && isForm(body)) out["content-type"] = FORM_TYPE;
+    out["accept-language"] = ACCEPT_LANGUAGE;
+    out["user-agent"] = String(ctx.userAgent);
+    const cookie = cookieHeader(ctx.cookie, url);
+    if (cookie) out.cookie = cookie;
+    return { ...out, ...caller };
+}
+
+/**
+ * One HTTP request on a session: default headers, the jar in and out, a timeout, and (on request) redirects
+ * followed as a browser follows a navigation.
+ *
+ * @param {object} ctx - the session (`userAgent`, `cookie`, `options.polyfill`)
+ * @param {string} url
+ * @param {object} [init]
+ * @param {string} [init.method] - GET unless given
+ * @param {Record<string, string>|Headers} [init.headers] - over the defaults, by name in any case
+ * @param {URLSearchParams|FormData|string|Uint8Array} [init.body]
+ * @param {AbortSignal} [init.signal]
+ * @param {number} [init.timeoutMs] - 10 s by default; 0 for none
+ * @param {"auto"|"manual"|"jar"} [init.follow] - "auto" lets fetch follow (the default); "manual" returns a 3xx as
+ *   it is; "jar" follows here, hop by hop, keeping every hop's cookies
+ * @param {"xhr"|"navigate"} [init.kind] - which default header set (an API call by default)
+ * @returns {Promise<Response>}
+ * @throws {ZaloApiError} on a timeout ("Zalo did not answer within N s: <path>", `.timeout` true), a redirect loop,
+ *   or a session with no User-Agent
+ */
+export async function httpRequest(ctx, url, init = {}) {
+    const {
+        method: givenMethod = "GET",
+        headers: givenHeaders,
+        body: givenBody,
+        signal: callerSignal,
+        timeoutMs = DEFAULT_TIMEOUT_MS,
+        follow = "auto",
+        kind = "xhr",
+    } = init;
+    if (!ctx?.userAgent) throw new ZaloApiError("User agent is not available");
+    if (!ctx.cookie) ctx.cookie = newJar();
+    const fetchFn = ctx.options?.polyfill ?? globalThis.fetch;
+
+    const timeoutSignal = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : null;
+    const signal =
+        timeoutSignal && callerSignal
+            ? AbortSignal.any([callerSignal, timeoutSignal])
+            : (timeoutSignal ?? callerSignal);
+
+    const callerHeaders = lowerHeaders(givenHeaders);
+    let method = String(givenMethod).toUpperCase();
+    let body = givenBody;
+    let current = String(url);
+    let headers = headersFor(ctx, current, method, body, callerHeaders, kind);
+    const initiator = headers.referer ?? null;
+    const initiatorOrigin = initiator ? new URL(initiator).origin : null;
+    let site = relation(initiatorOrigin, current);
+
+    for (let hop = 0; ; hop++) {
+        const req = { method, headers };
+        if (signal) req.signal = signal;
+        if (body !== undefined && body !== null && method !== "GET" && method !== "HEAD") req.body = body;
+        if (follow === "manual" || follow === "jar") req.redirect = "manual";
+        else if (init.redirect) req.redirect = init.redirect;
+        let res;
+        try {
+            res = await fetchFn(current, req);
+        } catch (e) {
+            if (timeoutSignal?.aborted && !callerSignal?.aborted) {
+                const err = new ZaloApiError(
+                    `Zalo did not answer within ${Math.round(timeoutMs / 1000)} s: ${new URL(current).pathname}`,
+                );
+                err.timeout = true;
+                throw err;
+            }
+            throw e;
+        }
+        storeSetCookies(ctx.cookie, current, res);
+        const location = res?.headers?.get?.("location");
+        if (follow !== "jar" || !REDIRECT_STATUS.has(res.status) || !location) return res;
+        if (hop + 1 > MAX_REDIRECTS) throw new ZaloApiError(`Too many redirects (more than ${MAX_REDIRECTS})`);
+        try {
+            await res.body?.cancel();
+        } catch {
+            /* nothing to release */
+        }
+
+        const next = new URL(location, current).toString();
+        const keep = res.status === 307 || res.status === 308;
+        if (!keep) {
+            method = method === "HEAD" ? "HEAD" : "GET";
+            body = undefined;
+        }
+        const rank = relation(initiatorOrigin, next);
+        if (SITE_RANK[rank] > SITE_RANK[site]) site = rank;
+        const carried = { ...callerHeaders };
+        for (const name of ["referer", "origin", "sec-fetch-site", "cookie", "content-length"]) delete carried[name];
+        if (!keep) delete carried["content-type"];
+        headers = headersFor(ctx, next, method, body, carried, "navigate");
+        const referer = referrerFor(initiator, next);
+        if (referer) headers.referer = referer;
+        else delete headers.referer;
+        headers["sec-fetch-site"] = site;
+        if (keep && method !== "GET" && method !== "HEAD" && initiatorOrigin) headers.origin = initiatorOrigin;
+        current = next;
+    }
+}
+
+/** The body of a response as text, from fakes that have only `json()` too. */
+async function textOf(response) {
+    if (typeof response.text === "function") return response.text();
+    return JSON.stringify(await response.json());
+}
+
+/** Whether a reply's code says "no error" (Zalo writes 0; a missing code is not a success). */
+const isZero = (code) => code !== undefined && code !== null && Number(code) === 0;
+
+/**
+ * Decode Zalo's reply envelope.
+ *
+ * @param {object} ctx - the session (its `secretKey` opens a session reply)
+ * @param {Response} response
+ * @param {object} [opts]
+ * @param {boolean} [opts.encrypted] - a session reply (default) or a plain one, whose `data` is not sealed
+ * @param {number[]} [opts.okCodes] - non-zero codes that are an answer, not an error
+ * @param {Record<string|number, unknown>|null} [opts.emptyOn] - a code that means "nothing", with the value to return
+ * @param {(text: string) => unknown} [opts.parse] - parses the opened text (lossless id parsing); JSON.parse otherwise
+ * @param {boolean} [opts.envelope] - return `{data, code, message}` instead of the data alone
+ * @returns {Promise<any>}
+ * @throws {ZaloApiError} `HTTP <status>` (code null, `.status` set) for a non-2xx; Zalo's message and code for an
+ *   outer or inner error, with that envelope's `data` on `.data` when it had one; "Failed to parse response data"
+ *   (no code) when the body or `data` does not open
+ */
+export async function decodeReply(ctx, response, opts = {}) {
+    const { encrypted = true, okCodes = [], emptyOn = null, parse = JSON.parse, envelope = false } = opts;
+    if (!response?.ok) {
+        const err = new ZaloApiError(`HTTP ${response?.status}`, null);
+        err.status = response?.status ?? null;
+        throw err;
+    }
+    const answer = (data, code, message) => (envelope ? { data, code, message } : data);
+    const settle = (env) => {
+        const code = env?.error_code;
+        if (isZero(code)) return null;
+        const n = Number(code);
+        const message = env?.error_message ?? "";
+        if (emptyOn && Object.hasOwn(emptyOn, String(n))) {
+            return { value: answer(structuredClone(emptyOn[String(n)]), n, message) };
+        }
+        if (okCodes.includes(n)) return { value: answer(env?.data ?? null, n, message) };
+        throw new ZaloApiError(
+            env?.error_message ?? `Zalo answered error ${code}`,
+            Number.isFinite(n) ? n : null,
+            env?.data ?? undefined,
+        );
+    };
+
+    let outer;
+    try {
+        outer = JSON.parse(await textOf(response));
+    } catch {
+        throw new ZaloApiError("Failed to parse response data");
+    }
+    const first = settle(outer);
+    if (first) return first.value;
+    if (!encrypted) return answer(outer?.data, 0, outer?.error_message ?? "");
+
+    const opened = openSession(ctx?.secretKey, outer?.data);
+    let inner;
+    try {
+        if (opened === null) throw new Error("does not open");
+        inner = parse(opened);
+    } catch {
+        throw new ZaloApiError("Failed to parse response data");
+    }
+    const second = settle(inner);
+    if (second) return second.value;
+    return answer(inner?.data, 0, inner?.error_message ?? "");
+}

package/src/zalo/kernel/json-ids.js

@@ -0,0 +1,118 @@
+/**
+ * Lossless ids in JSON text: quote the bare integers under a known list of keys before `JSON.parse` sees them.
+ *
+ * Zalo sends ids (user, group, message, action ids) as bare JSON integers, many past 2^53, which `JSON.parse` rounds.
+ * No big-number parser is used. Each socket handler runs its frame text through a pass
+ * that wraps the digits of every listed key's value in quotes, then parses it plainly. The pass also reaches the
+ * same keys inside JSON that is held, escaped, in a string value (`"data":"{\"uid\":123}"`), so a nested payload
+ * parsed later keeps its ids too.
+ *
+ * Consequences:
+ *  - a listed key's integer becomes a string, however small (`"msgId":5` -> `"5"`);
+ *  - an integer under a key that is not listed stays a number (lossy past 2^53);
+ *  - negative numbers, decimals and exponents are left as they are;
+ *  - in an array under a listed key (`"ids":[1,2]`), each bare integer item is quoted and other items are left alone.
+ *
+ * The key lists are Zalo's, one per socket handler family (chat, control, request/response). Pure functions, no I/O.
+ */
+
+/** Keys the chat handler quotes (messages, receipts, recalls: cmds 501, 521, 502, 522, 504, 510, 511, ...). */
+export const CHAT_ID_KEYS = Object.freeze([
+    "uidFrom",
+    "uidTo",
+    "uid",
+    "ownerId",
+    "destId",
+    "srcId",
+    "fromUid",
+    "threadId",
+    "globalMsgId",
+    "globalDelMsgId",
+    "msgId",
+    "refMessageId",
+    "actionId",
+    "lastActionIdOther",
+    "lastActionId",
+    "resetLastActionId",
+    "lastId",
+    "ids",
+]);
+
+/** Keys the control handler quotes (controls, reactions, typing: cmds 601, 602, 603, 610, 611, 612, ...). */
+export const CTRL_ID_KEYS = Object.freeze([
+    "uid",
+    "group_id",
+    "owner_id",
+    "groupId",
+    "msgId",
+    "refMessageId",
+    "actionId",
+    "lastActionIdOther",
+    "lastActionId",
+    "resetLastActionId",
+    "lastId",
+    "ids",
+]);
+
+/** Keys the request/response handler quotes: the chat list without the two global message id keys. */
+export const API_ID_KEYS = Object.freeze(CHAT_ID_KEYS.filter((k) => k !== "globalMsgId" && k !== "globalDelMsgId"));
+
+/** One compiled pattern per key list, keyed by the list's joined text. */
+const PATTERNS = new Map();
+
+/**
+ * The pattern for one key list. Groups: 1 the backslashes before each quote of the key (0 at the top level, 1 or more
+ * inside an escaped JSON string; the closing quote must carry the same), 2 the key, 3 and 4 the spacing around the
+ * colon, 5 a bare unsigned integer (not followed by more of a number), 6 the inside of an array with no nested
+ * array or object.
+ *
+ * @param {readonly string[]} keys
+ * @returns {RegExp}
+ */
+function patternFor(keys) {
+    const sig = keys.join("\n");
+    let re = PATTERNS.get(sig);
+    if (!re) {
+        const names = keys.map((k) => k.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+        re = new RegExp(String.raw`(\\*)"(${names})\1"(\s*):(\s*)(?:(\d+)(?![\d.eE])|\[([^[\]{}]*)\])`, "g");
+        PATTERNS.set(sig, re);
+    }
+    return re;
+}
+
+/** Quote one array's bare-integer items, keeping every other item and all spacing as it was. */
+function quoteItems(inside, esc) {
+    return inside
+        .split(",")
+        .map((item) => item.replace(/^(\s*)(\d+)(\s*)$/, (_m, a, n, b) => `${a}${esc}"${n}${esc}"${b}`))
+        .join(",");
+}
+
+/**
+ * Quote the bare integers under `keys` in a JSON text, so a plain `JSON.parse` keeps
+ * every digit of those ids. Text that is not a string, an empty text, or an empty key list is returned unchanged.
+ *
+ * @param {string} text - JSON text (a whole frame payload, or a nested payload)
+ * @param {readonly string[]} keys - the keys whose integer values become strings
+ * @returns {string} the same JSON with those integers quoted
+ */
+export function preParse(text, keys) {
+    if (typeof text !== "string" || text.length === 0 || !Array.isArray(keys) || keys.length === 0) return text;
+    return text.replace(patternFor(keys), (_m, esc, key, s1, s2, num, inside) => {
+        const head = `${esc}"${key}${esc}"${s1}:${s2}`;
+        if (num !== undefined) return `${head}${esc}"${num}${esc}"`;
+        return `${head}[${quoteItems(inside, esc)}]`;
+    });
+}
+
+/**
+ * `JSON.parse` after {@link preParse}: the ids under `keys` arrive as strings, every digit kept.
+ *
+ * @param {string} text - JSON text
+ * @param {readonly string[]} keys - the keys whose integer values become strings
+ * @returns {any} the parsed value
+ * @throws {SyntaxError} when the text is not JSON
+ */
+export function parseWithIds(text, keys) {
+    return JSON.parse(preParse(text, keys));
+}

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

@@ -0,0 +1,165 @@
+/**
+ * The login cipher: what `getLoginInfo` and `getServerInfo` need before any session key exists.
+ *
+ * Wire facts (spec-kernel 11.2):
+ *
+ * - `zcid` = uppercase hex of AES-256-CBC (zero IV, PKCS#7) of `"<type>,<imei>,<firstLaunchTime>"`, keyed by the
+ *   UTF-8 bytes of a fixed 32-character string (32 bytes, so AES-256; it is not hex-decoded).
+ * - `zcid_ext` = 6 to 12 random lowercase hex characters.
+ * - the answer key `enk` (32 characters): with `n` = uppercase MD5 hex of `zcid_ext`, take the characters at even
+ *   positions of `n` (first 8), the even positions of `zcid` (first 12), and the odd positions of `zcid` in reverse
+ *   order (first 12).
+ * - the login data is sealed as base64 of AES-256-CBC (zero IV, PKCS#7) keyed by the UTF-8 bytes of `enk`;
+ *   `enc_ver` is `"v2"`. The answer's `data` is sealed the same way (sometimes URL-escaped).
+ * - `signkey` = MD5 hex of `"zsecure" + <kind> + <every param value, ordered by param name>`.
+ */
+import { createCipheriv, createDecipheriv, createHash, randomBytes, randomInt } from "node:crypto";
+
+/** The fixed key `zcid` is sealed with (Zalo's param cipher key). */
+const ZCID_KEY = "3FC4F0D2AB50057BCE0D90D9187A22B1";
+
+/** `enc_ver` of every encrypted login call. */
+export const ENC_VER = "v2";
+
+const ZERO_IV = Buffer.alloc(16);
+
+/** AES-CBC with a UTF-8 key of 16, 24 or 32 bytes. */
+function algorithmFor(keyBytes) {
+    if (keyBytes.length === 16) return "aes-128-cbc";
+    if (keyBytes.length === 24) return "aes-192-cbc";
+    if (keyBytes.length === 32) return "aes-256-cbc";
+    throw new Error(`a login cipher key must be 16, 24 or 32 bytes, not ${keyBytes.length}`);
+}
+
+/** @param {string} key @param {string} text @returns {Buffer} */
+function sealUtf8Key(key, text) {
+    const k = Buffer.from(key, "utf8");
+    const c = createCipheriv(algorithmFor(k), k, ZERO_IV);
+    return Buffer.concat([c.update(text, "utf8"), c.final()]);
+}
+
+/** MD5 in lowercase hex. */
+const md5 = (text) => createHash("md5").update(text, "utf8").digest("hex");
+
+/**
+ * The `zcid` of a login.
+ *
+ * @param {number|string} type - the API type (30)
+ * @param {string} imei
+ * @param {number} firstLaunchTime - milliseconds
+ * @returns {string} uppercase hex
+ */
+export function makeZcid(type, imei, firstLaunchTime) {
+    if (!type || !imei || !firstLaunchTime) throw new Error("makeZcid: type, imei and firstLaunchTime are needed");
+    return sealUtf8Key(ZCID_KEY, `${type},${imei},${firstLaunchTime}`).toString("hex").toUpperCase();
+}
+
+/**
+ * A fresh `zcid_ext`: 6 to 12 random lowercase hex characters.
+ *
+ * @returns {string}
+ */
+export function makeZcidExt() {
+    const length = randomInt(6, 13);
+    return randomBytes(Math.ceil(length / 2))
+        .toString("hex")
+        .slice(0, length);
+}
+
+/** The characters of `s` at even (0, 2, ...) and odd positions. */
+function evenOdd(s) {
+    const even = [];
+    const odd = [];
+    [...s].forEach((ch, i) => (i % 2 === 0 ? even : odd).push(ch));
+    return { even, odd };
+}
+
+/**
+ * The key the `getLoginInfo` answer is sealed with.
+ *
+ * @param {string} zcid
+ * @param {string} zcidExt
+ * @returns {string} 32 characters
+ */
+export function deriveEnk(zcid, zcidExt) {
+    if (!zcid || !zcidExt) throw new Error("deriveEnk: zcid and zcid_ext are needed");
+    const fromExt = evenOdd(md5(zcidExt).toUpperCase()).even;
+    const fromZcid = evenOdd(zcid);
+    return (
+        fromExt.slice(0, 8).join("") +
+        fromZcid.even.slice(0, 12).join("") +
+        fromZcid.odd.reverse().slice(0, 12).join("")
+    );
+}
+
+/**
+ * Seal the login data with `enk`.
+ *
+ * @param {string} enk
+ * @param {object|string} data - an object is JSON-encoded
+ * @returns {string} base64
+ */
+export function sealLogin(enk, data) {
+    const text = typeof data === "string" ? data : JSON.stringify(data);
+    return sealUtf8Key(enk, text).toString("base64");
+}
+
+/**
+ * Open a `getLoginInfo` answer's `data`.
+ *
+ * @param {string} enk
+ * @param {string} data - base64, URL-escaped or not
+ * @returns {object|string|null} the parsed JSON; the text when it is not JSON; null when it does not open
+ */
+export function openLogin(enk, data) {
+    let text;
+    try {
+        const k = Buffer.from(enk, "utf8");
+        const d = createDecipheriv(algorithmFor(k), k, ZERO_IV);
+        const raw = Buffer.from(decodeURIComponent(String(data)), "base64");
+        text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat([d.update(raw), d.final()]));
+    } catch {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    } catch {
+        return text;
+    }
+}
+
+/**
+ * The `signkey` of a login-host call.
+ *
+ * @param {"getserverinfo"|"getlogininfo"} kind
+ * @param {Record<string, unknown>} params - every field sent at that point (`signkey` itself excluded)
+ * @returns {string} MD5 lowercase hex
+ */
+export function signKey(kind, params) {
+    let text = `zsecure${kind}`;
+    for (const name of Object.keys(params).sort()) text += params[name];
+    return md5(text);
+}
+
+/**
+ * Everything one encrypted `getLoginInfo` needs.
+ *
+ * @param {object} p
+ * @param {number} p.type
+ * @param {string} p.imei
+ * @param {number} p.firstLaunchTime
+ * @param {string} [p.zcidExt] - injected by tests; random otherwise
+ * @returns {{zcid: string, zcidExt: string, enk: string, params: () => {zcid: string, zcid_ext: string,
+ *   enc_ver: string}, seal: (data: object|string) => string}}
+ */
+export function createLoginEncryptor({ type, imei, firstLaunchTime, zcidExt = makeZcidExt() }) {
+    const zcid = makeZcid(type, imei, firstLaunchTime);
+    const enk = deriveEnk(zcid, zcidExt);
+    return {
+        zcid,
+        zcidExt,
+        enk,
+        params: () => ({ zcid, zcid_ext: zcidExt, enc_ver: ENC_VER }),
+        seal: (data) => sealLogin(enk, data),
+    };
+}

package/src/zalo/kernel/secret-file.js

@@ -0,0 +1,45 @@
+/**
+ * How the layer's stores read and write a file that holds a secret (the trusted-device identity, the phone sessions of
+ * a transfer sync).
+ *
+ * The layer itself only knows plain files at 0600. An application that protects its data at rest installs a codec
+ * once ({@link setSecretFileCodec}), or hands one to a store, and every such file then goes through it: the layer
+ * never learns how the bytes are protected, and never imports the application.
+ *
+ * A codec: `read(file, meta)` returns the text, or null when there is no file, and throws when the file exists but
+ * cannot be opened; `write(file, text, meta)` replaces the file atomically and throws when it cannot. `meta` says what
+ * the file is: `{kind, use, account?, dir?}` (`use` is `boot` for what a login needs, `data` for everything else).
+ */
+import { readFileSync } from "node:fs";
+import { writeFileAtomic } from "./atomic-file.js";
+
+/** The plain codec: the file as it is, written at 0600. */
+export const plainCodec = Object.freeze({
+    read(file) {
+        try {
+            return readFileSync(file, "utf8");
+        } catch (e) {
+            if (e.code === "ENOENT") return null;
+            throw e;
+        }
+    },
+    write(file, text) {
+        writeFileAtomic(file, text, { mode: 0o600 });
+    },
+});
+
+let installed = plainCodec;
+
+/**
+ * Install the codec every store uses unless it was handed its own; null restores the plain one.
+ *
+ * @param {{read: Function, write: Function}|null} codec
+ */
+export function setSecretFileCodec(codec) {
+    installed = codec ?? plainCodec;
+}
+
+/** @returns {{read: Function, write: Function}} the codec in use */
+export function secretFileCodec() {
+    return installed;
+}