@ardennguyen/zalo-agent-cli 2.5.8 → 3.0.0

package/src/core/conversation-actions.js

@@ -0,0 +1,214 @@
+/**
+ * Conversation actions shared by `conv` (src/commands/conv.js) and the MCP tool `zalo_conversation`: pinning,
+ * archiving, the anchor `conv delete` deletes backwards from, the auto-delete periods, and forgetting a conversation's
+ * local copy. Each call is the one the CLI makes, so the two surfaces cannot drift apart.
+ */
+
+import { zaloPost } from "../zalo/receipts.js";
+import { getMessages, forgetThread } from "./db.js";
+import { pruneDownloadedMedia } from "./sync-v2/media.js";
+
+/**
+ * How many cached rows to inspect before giving up on finding an anchor.
+ * Deep enough to see past a run of sync-v2 rows, shallow enough that the
+ * lookup stays a single cheap query.
+ */
+export const ANCHOR_SCAN_DEPTH = 200;
+
+/** How far back to look for an incoming message to anchor a seen event (or an unread mark) on. */
+export const SEEN_ANCHOR_SCAN_DEPTH = 50;
+
+/**
+ * The hidden-conversation list as the CLI and MCP hand it out: the threads and whether a PIN is set, never the PIN.
+ *
+ * Zalo's `hiddenconvers/get-all` answers with `pin`, the unsalted MD5 of the 4-digit PIN (a client keeps it to check
+ * the PIN on the device). Ten thousand guesses recover the PIN from it, so passing the answer through gave it to
+ * every script and every MCP agent that listed hidden conversations (seen live 2026-11-07).
+ *
+ * @param {object|null|undefined} raw - Zalo's get-all answer
+ * @returns {{threads: object[], hasPin: boolean}}
+ */
+export function hiddenConversationsView(raw) {
+    return { threads: Array.isArray(raw?.threads) ? raw.threads : [], hasPin: Boolean(raw?.pin) };
+}
+
+/** `conv auto-delete`'s periods, in milliseconds, as Zalo offers them. */
+export const AUTO_DELETE_TTLS = Object.freeze({ off: 0, "1d": 86400000, "7d": 604800000, "14d": 1209600000 });
+
+/** Build the deleteChat anchor triple, or null when any part is missing. */
+function toAnchor(ownerId, cliMsgId, globalMsgId) {
+    if (!ownerId || !cliMsgId || !globalMsgId) return null;
+    return { ownerId: String(ownerId), cliMsgId: String(cliMsgId), globalMsgId: String(globalMsgId) };
+}
+
+/**
+ * Find the newest message in a thread and return the anchor triple `deleteChat` needs.
+ *
+ * Groups expose a REST history endpoint; DMs do not, so the caller has to
+ * supply the ids by hand there. Both paths are best-effort: Zalo's history
+ * APIs lag live traffic, so the "newest" message found may not be the true
+ * newest (see agent/work/transfer-sync-v2/NOTES.md § Ordering).
+ *
+ * The local cache must already be open (the caller opens it: `conv delete` writes to it next). With no cache open,
+ * only the group store can answer.
+ *
+ * @param {object} api
+ * @param {string} threadId
+ * @param {number} type - 0=User, 1=Group
+ * @returns {Promise<{ownerId: string, cliMsgId: string, globalMsgId: string}|null>}
+ */
+export async function newestMessageAnchor(api, threadId, type) {
+    // Source 1: Zalo's cloud-message store, the group history Zalo serves
+    // (src/zalo/custom/group-history.js). The previous engine's getGroupChatHistory asked
+    // /api/group/history, which Zalo answers with 404 -- and this used to read
+    // its answer as an array, a shape it never had.
+    if (type === 1) {
+        try {
+            // Loaded on demand: only the group path needs it.
+            const { getGroupHistory } = await import("../zalo/custom/group-history.js");
+            const history = await getGroupHistory(api, threadId, 1);
+            const last = history.groupMsgs[0]?.data;
+            const anchor = toAnchor(last?.uidFrom ?? last?.ownerId, last?.cliMsgId, last?.msgId ?? last?.globalMsgId);
+            if (anchor) return anchor;
+        } catch {
+            // Store unreachable, or no group_cloud_message host — fall through to the local cache.
+        }
+    }
+
+    // Source 2: the local SQLite cache. Anything `listen`, `sync` or a prior
+    // `msg history` wrote is here, and rows carry the raw payload, which is
+    // where cliMsgId lives.
+    //
+    // Scan BACKWARDS rather than trusting the newest row, because not every
+    // writer stores a usable payload. `listen` and the `msg history` socket
+    // backfill persist the full frame (cliMsgId, uidFrom, …); the sync-v2
+    // restore persists a minimal shape with no cliMsgId at all. A thread
+    // whose newest rows came from sync-v2 therefore has a newest row that
+    // cannot anchor anything, while older rows can — measured on a live
+    // account as 10 usable rows out of 294 for a group, and 0 out of 43 for
+    // a DM that had never been history-fetched. Reading only row 1 turned
+    // that into "Could not determine the last message", and made the group
+    // path succeed or fail on the luck of which writer touched it last.
+    //
+    // Deleting backwards from a slightly older anchor leaves the newest few
+    // messages in place, which is the same staleness `msg history` already
+    // has (see agent/work/transfer-sync-v2/NOTES.md § Ordering) and is far
+    // better than refusing outright.
+    try {
+        for (const row of getMessages(threadId, ANCHOR_SCAN_DEPTH)) {
+            let raw = {};
+            try {
+                raw = JSON.parse(row.raw_data || "{}");
+            } catch {
+                continue; // unparseable payload — try an older row
+            }
+            const data = raw.data ?? raw;
+            const anchor = toAnchor(row.senderId ?? data.uidFrom, data.cliMsgId, row.msgId ?? data.msgId);
+            if (anchor) return anchor;
+        }
+        return null;
+    } catch {
+        return null; // no cache open in this process
+    }
+}
+
+/**
+ * Pin or unpin one conversation.
+ *
+ * `POST {conversation}/api/pinconvers/updatev2` with
+ * `{actionType: 1 pin | 2 unpin, conversations: ["g<id>" | "u<id>"], tab: 0}`
+ * -- captured for a group and a DM, both directions. The previous engine's
+ * setPinnedConversations sent the same minus `tab`, so it is not used.
+ *
+ * @param {object} api - logged-in session
+ * @param {{threadId: string, type: 0|1, pinned: boolean}} opts
+ * @returns {Promise<object>}
+ */
+export async function setConversationPinned(api, { threadId, type, pinned }) {
+    const conversation = `${type === 1 ? "g" : "u"}${threadId}`;
+    const response = await zaloPost(api, {
+        url: `${api.zpwServiceMap.conversation[0]}/api/pinconvers/updatev2`,
+        params: () => ({ actionType: pinned ? 1 : 2, conversations: [conversation], tab: 0 }),
+    });
+    return { threadId: String(threadId), type, pinned, conversation, response };
+}
+
+/**
+ * Move one conversation to Zalo's "Other" tab (archive) or back to Focused.
+ *
+ * `POST {label}/api/archivedchat/update` with
+ * `{ids: [{id, type: 1 group | 0 user}], version, actionType: 0 to Other | 1 back, imei}`.
+ *
+ * `version` is the one decision here. The previous engine's updateArchivedChatList
+ * sent `Date.now()`. The server expects its OWN version: each update carries
+ * exactly the `version` the previous response returned, and the first one
+ * carries the version stored from the server, which can be weeks older than the
+ * clock. A client keeps that value, refreshes it from `archivedchat/list` at
+ * start-up and from every update response, and reads the list again when an
+ * answer flags it stale. A CLI run is a fresh client every time, so it does the
+ * start-up step: read the list (getArchivedChatList) and send the version found
+ * there. With no version, nothing
+ * is sent.
+ *
+ * @param {object} api - logged-in session
+ * @param {{threadId: string, type: 0|1, archived: boolean}} opts
+ * @returns {Promise<object>}
+ */
+export async function setConversationArchived(api, { threadId, type, archived }) {
+    let listed;
+    try {
+        listed = await api.getArchivedChatList();
+    } catch (e) {
+        throw new Error(`Could not read Zalo's archived-chat version, so nothing was sent: ${e.message}`);
+    }
+    const v = listed?.version;
+    const version = typeof v === "number" ? v : /^\d+$/.test(String(v ?? "")) ? Number(v) : NaN;
+    if (!Number.isFinite(version)) {
+        throw new Error(
+            `Zalo's archived-chat list carried no usable version (${JSON.stringify(v)}), so nothing was sent.`,
+        );
+    }
+    const response = await zaloPost(api, {
+        url: `${api.zpwServiceMap.label[0]}/api/archivedchat/update`,
+        params: (ctx) => ({
+            ids: [{ id: String(threadId), type: type === 1 ? 1 : 0 }],
+            version,
+            actionType: archived ? 0 : 1,
+            imei: ctx.imei,
+        }),
+    });
+    return {
+        threadId: String(threadId),
+        type,
+        archived,
+        previousVersion: version,
+        version: response?.version ?? null,
+        needResync: Boolean(response?.needResync),
+        response,
+    };
+}
+
+/**
+ * Delete this machine's copy of one conversation: its downloaded media first, then its rows. Zalo is not contacted.
+ *
+ * Files first: forgetThread drops the rows that point at them, and a deleted row would leave its media stranded on
+ * disk. Each half is best effort, and what failed is reported rather than thrown.
+ *
+ * @param {string} threadId
+ * @returns {Promise<{threadId: string, messages: number, files: number, errors: Array<{what: "media"|"rows", message: string}>}>}
+ */
+export async function forgetConversation(threadId) {
+    const id = String(threadId);
+    const out = { threadId: id, messages: 0, files: 0, errors: [] };
+    try {
+        out.files = (await pruneDownloadedMedia({ all: true, threadId: id })).deleted || 0;
+    } catch (e) {
+        out.errors.push({ what: "media", message: e.message });
+    }
+    try {
+        out.messages = forgetThread(id).messages || 0;
+    } catch (e) {
+        out.errors.push({ what: "rows", message: e.message });
+    }
+    return out;
+}

package/src/core/credentials.js

@@ -7,14 +7,17 @@
  *   DATA_DIR        = <CONFIG_DIR>/accounts         (env: ZALO_DATA_DIR,        flag: --data-dir)
  *   MEDIA_DIR       = null (<DATA_DIR>/<id>/media)  (env: ZALO_MEDIA_DIR,       flag: --media-dir)
  *
- * All credential files use 0600 permissions (owner read/write only).
+ * All credential files use 0600 permissions (owner read/write only), and since 3.0.0 they are sealed under the
+ * account's boot key (src/core/keystore/): a copied file is unreadable without the key provider of this machine.
  */
 
-import { readFileSync, unlinkSync, existsSync, mkdirSync } from "fs";
+import { readFileSync, unlinkSync, existsSync, mkdirSync, statSync } from "fs";
 import { join, resolve } from "path";
 import { homedir } from "os";
 import { parseEnv } from "node:util";
-import { writeFileAtomic } from "../utils/atomic-file.js";
+import { openFile, sealFile } from "./keystore/index.js";
+import { writeFileAtomic } from "../zalo/kernel/atomic-file.js";
+import { sessionExpiryOf } from "./session-expiry.js";
 
 const defaultConfigDir = join(homedir(), ".zalo-agent-cli");
 
@@ -168,31 +171,129 @@ function credPath(ownId) {
     return join(CREDENTIALS_DIR, `cred_${ownId}.json`);
 }
 
+/** What the key layer calls the saved login: sealed under the boot key, which opens without a login. */
+const CRED_SPEC = { kind: "credentials", use: "boot" };
+
+/**
+ * What this machine last saved for an account's device: the imei, when that device id was first used here
+ * (`deviceSince`, ms), and when the file was last written (`mtime`, ms).
+ *
+ * Zalo keeps the offline queue per device (imei): a new device's queue starts at its login, so the time a device id
+ * was first used bounds what Zalo's queue can give back (agent research: offline-queue retention §4). Never throws.
+ *
+ * @param {string} ownId
+ * @returns {{state: "none"|"unreadable"|"ok", imei?: string|null, deviceSince?: number|null, mtime?: number|null}}
+ *   `none` when nothing is saved, `unreadable` when a file exists but cannot be opened or parsed
+ */
+export function readSavedDevice(ownId) {
+    const target = credPath(ownId);
+    if (!existsSync(target)) return { state: "none" };
+    try {
+        const mtime = statSync(target).mtimeMs;
+        const bytes = openFile(target, String(ownId), CRED_SPEC);
+        if (bytes === null) return { state: "none" };
+        const creds = JSON.parse(bytes.toString("utf8"));
+        const since = Number(creds?.deviceSince);
+        return {
+            state: "ok",
+            imei: typeof creds?.imei === "string" && creds.imei ? creds.imei : null,
+            deviceSince: Number.isFinite(since) && since > 0 ? since : null,
+            mtime: Number.isFinite(mtime) ? Math.floor(mtime) : null,
+        };
+    } catch {
+        return { state: "unreadable" };
+    }
+}
+
+/**
+ * The `deviceSince` a save should carry: the time this device id was first used for the account here.
+ *
+ * - Same imei as the saved login: the saved stamp. A login saved before stamps existed has none; its file's last write
+ *   is used instead. That is never earlier than the imei's first use (every save rewrites the file), so coverage is
+ *   never claimed from before the device existed.
+ * - Nothing saved, and the new credentials carry their own stamp (an exported login, with its imei): that stamp.
+ * - Anything else (a new or changed imei, or a saved login that cannot be read): now. A new device.
+ *
+ * @param {{state: string, imei?: string|null, deviceSince?: number|null, mtime?: number|null}} prev - readSavedDevice()
+ * @param {{imei?: string, deviceSince?: number}} creds - what is being saved
+ * @param {number} now
+ * @returns {number}
+ */
+export function deviceSinceFor(prev, creds, now) {
+    const imei = typeof creds?.imei === "string" && creds.imei ? creds.imei : null;
+    if (prev?.state === "ok" && imei && prev.imei === imei) {
+        if (Number.isFinite(prev.deviceSince) && prev.deviceSince > 0) return Math.min(prev.deviceSince, now);
+        if (Number.isFinite(prev.mtime) && prev.mtime > 0) return Math.min(prev.mtime, now);
+        return now;
+    }
+    const carried = Number(creds?.deviceSince);
+    if (prev?.state === "none" && imei && Number.isFinite(carried) && carried > 0 && carried <= now) return carried;
+    return now;
+}
+
 /**
- * Save credentials for a specific account.
+ * Save credentials for a specific account, sealed. Stamps `deviceSince` (see {@link deviceSinceFor}): kept while
+ * the imei stays the same, set to now when it changes. Every login path saves through here.
  * @param {string} ownId
  * @param {object} creds - {imei, cookie, userAgent, language?}
+ * @param {{now?: number}} [opts]
  * @returns {string} File path
+ * @throws {Error} a KeystoreError when no key can be had: the login is then not saved at all, never in the clear
  */
-export function saveCredentials(ownId, creds) {
+export function saveCredentials(ownId, creds, { now = Date.now() } = {}) {
     ensureDirs();
     const target = credPath(ownId);
-    // Atomic and created at 0600: a login is never left half written, and the file is never readable
-    // by others, even for the moment between a write and a chmod.
-    writeFileAtomic(target, JSON.stringify(creds, null, 2));
+    const deviceSince = deviceSinceFor(readSavedDevice(ownId), creds, now);
+    // Sealed, atomic and created at 0600: a login is never left half written, and never readable by others.
+    sealFile(target, String(ownId), CRED_SPEC, JSON.stringify({ ...creds, deviceSince }, null, 2));
+    noteSessionEnd(ownId, creds?.cookie);
     return target;
 }
 
+/** The account folder's session-end marker (src/core/session-notice.js SESSION_NOTICE_FILE). */
+const SESSION_MARKER = "session-notice.json";
+
+/**
+ * Record when the login just saved ends, in the account folder's marker, so `fleet status` shows it before the
+ * account's daemon has ever run (the marker needs no key to read). A new end resets the thresholds already sent;
+ * the same end leaves the marker alone. Best effort: a marker that cannot be written never fails a login.
+ *
+ * @param {string} ownId
+ * @param {unknown} jar - the saved cookie jar
+ */
+function noteSessionEnd(ownId, jar) {
+    try {
+        const end = sessionExpiryOf(jar);
+        if (!end) return;
+        const file = join(getAccountDir(ownId), SESSION_MARKER);
+        let prev = null;
+        try {
+            prev = JSON.parse(readFileSync(file, "utf8"));
+        } catch {
+            prev = null;
+        }
+        if (prev?.expiresAt === end.expiresAt) return;
+        mkdirSync(getAccountDir(ownId), { recursive: true });
+        writeFileAtomic(file, JSON.stringify({ expiresAt: end.expiresAt, threshold: null }) + "\n", { mode: 0o600 });
+    } catch {
+        // The daemon's watch writes it on its first look.
+    }
+}
+
 /**
- * Load credentials for a specific account.
+ * Load credentials for a specific account. A plaintext file from before 3.0.0 is sealed on the way.
  * @param {string} ownId
- * @returns {object|null}
+ * @returns {object|null} null when there are none (or the file is not JSON)
+ * @throws {Error} a KeystoreError / SealError when the file exists but cannot be opened (no provider, wrong key,
+ *   edited): saying "not logged in" then would send people to a QR login that would not fix it
  */
 export function loadCredentials(ownId) {
     const target = credPath(ownId);
     if (!existsSync(target)) return null;
+    const bytes = openFile(target, String(ownId), CRED_SPEC);
+    if (bytes === null) return null;
     try {
-        return JSON.parse(readFileSync(target, "utf-8"));
+        return JSON.parse(bytes.toString("utf8"));
     } catch {
         return null;
     }

package/src/core/current-user-names.js

@@ -1,4 +1,12 @@
-import { runPacedBatches, userInfoLog } from "./user-info.js";
+import { runPacedBatches, userInfoLog } from "../zalo/custom/user-info.js";
+import { readAllAliases } from "../zalo/api/people.js";
+import { noteAliasSnapshot, pickName } from "./contact-names.js";
+
+/** Aliases asked per page. */
+const ALIAS_PAGE_SIZE = 100;
+
+/** Pages read before the alias list is given up on as endless. */
+const MAX_ALIAS_PAGES = 1000;
 
 /** The default `log`: silent unless a daemon registered a sink with `setUserInfoLogger`. */
 const NO_LOG = () => {};
@@ -12,45 +20,63 @@ const NO_LOG = () => {};
  * @returns {Promise<Map<string, string>>} UID -> account-owned alias
  */
 export async function readUserAliases(api, log = () => {}) {
+    const aliases = await readUserAliasSnapshot(api);
+    if (aliases) return aliases;
+    log("current aliases unavailable; falling back to profile names or UIDs");
+    return new Map();
+}
+
+/**
+ * Like {@link readUserAliases}, but null when the snapshot could not be read completely, so a caller that keeps a
+ * snapshot (./contact-names.js) never mistakes a failed read for "the owner removed every alias". A complete read is
+ * also handed to the account's alias book, so every later display in this process sees it.
+ * @param {object} api - current authenticated API
+ * @returns {Promise<Map<string, string>|null>} UID -> account-owned alias, or null
+ */
+export async function readUserAliasSnapshot(api) {
     const aliases = new Map();
     try {
-        if (typeof api?.getAliasList !== "function") return aliases;
-        for (let page = 1; page <= 1000; page++) {
-            const result = await api.getAliasList(100, page);
-            if (!Array.isArray(result?.items)) throw new Error("invalid alias page");
-            let added = 0;
-            for (const item of result.items) {
-                if (item.userId && typeof item.alias === "string" && item.alias.trim()) {
-                    const uid = String(item.userId);
-                    if (!aliases.has(uid)) added++;
-                    aliases.set(uid, item.alias);
-                }
+        if (typeof api?.getAliasList !== "function") return null;
+        // readAllAliases pages the list (`hasMore`, a full page, 212 past page 1). This wrapper keeps
+        // this function's own contract on top: a malformed page, a page that repeats ids already read, or running
+        // past the page cap fails the whole read instead of handing back part of the list.
+        const seen = new Set();
+        const checked = {
+            getAliasList: async (count, page) => {
+                if (page > MAX_ALIAS_PAGES) throw new Error("alias pagination limit reached");
+                const result = await api.getAliasList(count, page);
+                if (!Array.isArray(result?.items)) throw new Error("invalid alias page");
+                const ids = result.items.map((item) => String(item?.userId ?? ""));
+                if (ids.length && ids.every((id) => seen.has(id))) throw new Error("alias pagination did not advance");
+                for (const id of ids) seen.add(id);
+                return result;
+            },
+        };
+        const items = await readAllAliases(checked, { pageSize: ALIAS_PAGE_SIZE, maxPages: MAX_ALIAS_PAGES + 1 });
+        for (const item of items) {
+            if (item?.userId && typeof item.alias === "string" && item.alias.trim()) {
+                aliases.set(String(item.userId), item.alias);
             }
-            if (result.items.length < 100) return aliases;
-            if (!added) throw new Error("alias pagination did not advance");
         }
-        throw new Error("alias pagination limit reached");
     } catch {
-        log("current aliases unavailable; falling back to profile names or UIDs");
-        return new Map();
+        return null;
     }
+    noteAliasSnapshot(aliases);
+    return aliases;
 }
 
 /**
- * Select a current label independently of any per-message historical name.
+ * Select a current label independently of any per-message historical name: the owner's alias, then the profile's
+ * Zalo name, then its display name, then the UID (./contact-names.js `pickName`, the one precedence every output uses).
  * @param {string} uid - canonical user ID
  * @param {object} [profile] - fresh Zalo profile
  * @param {Map<string, string>} [aliases] - account-owned aliases
- * @returns {{name: string, source: string}} label and provenance
+ * @returns {{name: string, source: string}} label and provenance (`alias`, `display`, `zalo` or `uid`)
  */
 export function currentUserName(uid, profile, aliases = new Map()) {
     const id = String(uid || "");
-    const alias = aliases.get(id);
-    if (alias) return { name: alias, source: "alias" };
-    // displayName can itself be an alias. Only zaloName establishes the
-    // profile-name fallback independently of the owner's alias snapshot.
-    const name = profile?.zaloName;
-    return name ? { name, source: "zalo" } : { name: id, source: "uid" };
+    const picked = pickName(id, { ...profile, alias: aliases.get(id) ?? null });
+    return { name: picked.name ?? id, source: picked.source };
 }
 
 /**
@@ -101,7 +127,10 @@ export async function resolveCurrentUserNames(api, uids, { aliases, profiles = n
 }
 
 /**
- * Decorate copied messages with current labels; senderName stays historical.
+ * Decorate copied messages with current labels. `senderName` is the name to show, alias first: the owner's alias
+ * when one is set, else the name the message carried, else the current profile name. `senderZaloName` keeps the
+ * name the message carried (the stored snapshot, never rewritten), `senderAlias` the alias or null, and
+ * `senderDisplayName`/`senderDisplayNameSource` the current label (alias, phonebook name, Zalo name, display name or UID).
  * DM titles use the peer's UID, including for an outgoing message from self.
  * @param {object} api - current authenticated API
  * @param {object[]} messages - cached or live rows
@@ -114,8 +143,13 @@ export async function withCurrentSenderNames(api, messages, dmThreadIds = []) {
     return messages.map((m) => {
         const sender = names.get(String(m.senderId)) || { name: null, source: "uid" };
         const peer = peers.has(String(m.threadId)) && names.get(String(m.threadId));
+        const raw = "senderZaloName" in m ? m.senderZaloName || null : m.senderName || null;
+        const alias = sender.source === "alias" ? sender.name : null;
         return {
             ...m,
+            senderName: alias ?? raw ?? (sender.source !== "uid" ? sender.name : null),
+            senderAlias: alias,
+            senderZaloName: raw,
             senderDisplayName: sender.name,
             senderDisplayNameSource: sender.source,
             ...(peer && { threadName: peer.name }),