@ardennguyen/zalo-agent-cli 2.5.9 → 3.0.0

package/src/core/overflow-repair.js

@@ -0,0 +1,221 @@
+/**
+ * Queue overflow: what Zalo dropped from an offline queue, the no-tap repair for groups, and the notice.
+ *
+ * Zalo signals overflow with `queueStatus["<q>"].evict == 1` (or a `resetLastActionId`). Zalo's own apps answer it
+ * by recording a missing range from the last time online to now and showing "Sync recent messages", which the
+ * phone-backed restore fills. Groups have a second, no-tap path: their
+ * messages are kept in the group cloud-message store, which Zalo reads back for the affected groups (AFMC). 1-1
+ * messages have no such path.
+ *
+ * This module does the group half here: for every group the account is in (most recently active first, in batches of
+ * 50 as Zalo's own AFMC batch), it reads each group's newest messages from the cloud store, page after page, until it
+ * reaches the start of the loss (or the store has nothing older), and stores what the cache lacks, insert-if-absent
+ * (the same writer `msg history` uses). A group whose newest message is older than the loss had no activity in it and
+ * costs one request. The 1-1 half stays a pending gap that `zalo-agent sync --from <date>` closes with a tap on the
+ * phone. `maxGroups` and `maxPerGroup` remain as opt-in bounds.
+ *
+ * A drain that returns 0 rows with no `evict` is NOT an overflow: it is a quiet queue (or a cursor from before this
+ * device's login, which ./device-since.js handles).
+ */
+import { getRecentThreads } from "./db.js";
+import { storeHistoryMessage } from "./live-store.js";
+import { syncFromDate } from "./sync-v2/gap-advice.js";
+
+/** Groups per batch: Zalo's own AFMC batch. Every group is read, batch after batch. */
+export const OVERFLOW_GROUP_BATCH = 50;
+
+/** Groups read per overflow: no cap by default (an opt-in `maxGroups` bounds it). */
+export const OVERFLOW_MAX_GROUPS = Infinity;
+
+/** Messages read per group: no cap by default; the read stops at the start of the loss (an opt-in `maxPerGroup`). */
+export const OVERFLOW_MAX_PER_GROUP = Infinity;
+
+/** The first, cheap read per group: one cloud-store page. */
+const FIRST_COUNT = 50;
+
+/** Pause between groups. Zalo rate-limits hard (src/core/sync-v2/board.js). */
+const GROUP_DELAY_MS = 300;
+
+/** Pause between two batches of groups. */
+const BATCH_DELAY_MS = 1000;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** The groups the account is in, from the server's group list (`getAllGroups`'s `gridVerMap`). */
+async function listMemberGroups(api) {
+    const res = await api.getAllGroups();
+    const map = res?.gridVerMap ?? res?.data?.gridVerMap ?? null;
+    if (!map || typeof map !== "object") throw new Error("the group list carried no gridVerMap");
+    return Object.keys(map).map(String);
+}
+
+/** A group's newest messages from the cloud store (src/zalo/custom/group-history.js), loaded on demand. */
+async function fetchGroupHistory(api, groupId, count, opts) {
+    const { getGroupHistory } = await import("../zalo/custom/group-history.js");
+    return getGroupHistory(api, groupId, count, opts);
+}
+
+const tsOf = (m) => Number(m?.data?.ts);
+
+/**
+ * Read the groups' cloud store back to `fromTs` and store what the cache lacks.
+ *
+ * @param {object} p
+ * @param {object} p.api - a logged-in session
+ * @param {number} p.fromTs - the start of the loss (ms)
+ * @param {(api: object) => Promise<string[]>} [p.listGroups] - the groups the account is in
+ * @param {(api: object, groupId: string, count: number, opts?: {untilTs?: number}) => Promise<{groupMsgs: object[],
+ *   more: 0|1, filtered?: boolean}>} [p.fetchGroup] - one group's newest messages, newest first; `count` may be
+ *   Infinity with `untilTs`: page back until a page reaches that time
+ * @param {(limit: number) => string[]} [p.recentGroups] - group ids by local recency, most recent first (-1: all)
+ * @param {(msg: object) => {stored: boolean, info?: object}} [p.store]
+ * @param {number} [p.maxGroups] - opt-in bound on the groups read
+ * @param {number} [p.maxPerGroup] - opt-in bound on the messages read per group
+ * @param {number} [p.delayMs]
+ * @param {number} [p.batchDelayMs]
+ * @returns {Promise<{checked: number, active: number, members: number|null, added: Array<{msg: object,
+ *   info: object}>, complete: boolean, incomplete: string[]}>} `complete` true only when every group the account is
+ *   in was read back to `fromTs` (or had nothing after it); `incomplete` names why not, without ids
+ */
+export async function repairGroupsFromCloud({
+    api,
+    fromTs,
+    listGroups = listMemberGroups,
+    fetchGroup = fetchGroupHistory,
+    recentGroups = (limit) => getRecentThreads(limit, "group").map((t) => String(t.threadId)),
+    store = (msg) => storeHistoryMessage(msg, { src: "group-cloud" }),
+    maxGroups = OVERFLOW_MAX_GROUPS,
+    maxPerGroup = OVERFLOW_MAX_PER_GROUP,
+    delayMs = GROUP_DELAY_MS,
+    batchDelayMs = BATCH_DELAY_MS,
+}) {
+    const out = { checked: 0, active: 0, members: null, added: [], complete: true, incomplete: [] };
+    const note = (why) => {
+        out.complete = false;
+        if (!out.incomplete.includes(why)) out.incomplete.push(why);
+    };
+
+    let members = null;
+    try {
+        members = await listGroups(api);
+        out.members = members.length;
+    } catch {
+        note("the group list could not be read");
+    }
+    let local = [];
+    try {
+        local = recentGroups(Number.isFinite(maxGroups) ? maxGroups * 4 : -1);
+    } catch {
+        /* an unreadable cache only changes the order */
+    }
+    // Most recently active first; only groups the account is in when the list is known.
+    const memberSet = members ? new Set(members) : null;
+    const order = [...new Set([...local.filter((g) => !memberSet || memberSet.has(g)), ...(members ?? [])])];
+    if (order.length > maxGroups) note(`more than ${maxGroups} groups; the least recently active were not read`);
+    const groups = order.slice(0, maxGroups);
+
+    for (const [i, groupId] of groups.entries()) {
+        if (i > 0) {
+            const wait = i % OVERFLOW_GROUP_BATCH === 0 ? batchDelayMs : delayMs;
+            if (wait) await sleep(wait);
+        }
+        out.checked++;
+        try {
+            let page = await fetchGroup(api, groupId, Math.min(FIRST_COUNT, maxPerGroup));
+            let rows = Array.isArray(page?.groupMsgs) ? page.groupMsgs : [];
+            const reached = (list) => list.some((m) => tsOf(m) <= fromTs);
+            if (!rows.some((m) => tsOf(m) > fromTs)) continue; // nothing new in the window
+            out.active++;
+            if (!reached(rows) && page?.more && maxPerGroup > FIRST_COUNT) {
+                // Page back, 50 a page, until a page reaches the start of the loss or the store has nothing older.
+                page = await fetchGroup(api, groupId, maxPerGroup, { untilTs: fromTs });
+                rows = Array.isArray(page?.groupMsgs) ? page.groupMsgs : rows;
+            }
+            for (const msg of rows) {
+                if (!(tsOf(msg) > fromTs)) continue;
+                const r = store(msg);
+                if (r?.stored) out.added.push({ msg, info: r.info });
+            }
+            if (!reached(rows) && (page?.more || page?.filtered)) {
+                note(
+                    page?.filtered
+                        ? "a group's cloud store withholds messages from before this device's login"
+                        : page?.stalled
+                          ? "a group's cloud store stopped advancing its cursor"
+                          : `a group had more than ${maxPerGroup} messages in the window`,
+                );
+            }
+        } catch {
+            note("a group's cloud store could not be read");
+        }
+    }
+    // Oldest first, as a bot would have seen them live.
+    out.added.sort((a, b) => tsOf(a.msg) - tsOf(b.msg));
+    return out;
+}
+
+/**
+ * The `queue_overflow` event: ids and counts only, never a name or a message.
+ *
+ * @param {object} p
+ * @param {string|null} p.accountId
+ * @param {number} p.fromTs - last known online
+ * @param {number} p.toTs
+ * @param {string[]} p.queues - the queues Zalo said it dropped from, e.g. ["510_1"]
+ * @param {boolean} p.direct - whether 1-1 messages may be missing (a 1-1 queue overflowed)
+ * @param {{checked: number, active: number, added: number, complete: boolean}|null} p.groups - the group repair, or
+ *   null when no group queue overflowed
+ * @param {boolean} p.pending - whether a gap stays pending
+ * @param {number} [p.at]
+ * @returns {object}
+ */
+export function queueOverflowEvent({ accountId, fromTs, toTs, queues, direct, groups, pending, at = Date.now() }) {
+    return {
+        event: "queue_overflow",
+        accountId: accountId ?? null,
+        fromTs,
+        toTs,
+        queues: [...queues],
+        direct: Boolean(direct),
+        groups: groups
+            ? { checked: groups.checked, active: groups.active, added: groups.added, complete: groups.complete }
+            : null,
+        pending: Boolean(pending),
+        command: pending ? `zalo-agent sync --from ${syncFromDate(fromTs)}` : null,
+        at,
+    };
+}
+
+/**
+ * One `queue_overflow` event as a line for a person.
+ *
+ * @param {object} e
+ * @returns {string}
+ */
+export function describeQueueOverflow(e) {
+    const since = new Date(e.fromTs).toISOString();
+    const parts = [`Zalo's offline queue overflowed (${e.queues.join(", ")}): messages since ${since} were dropped.`];
+    if (e.groups) {
+        parts.push(
+            e.groups.complete
+                ? `Groups were repaired from Zalo's group store without a tap (${e.groups.added} message(s) added, ${e.groups.active} active group(s)).`
+                : `Groups were partly repaired from Zalo's group store (${e.groups.added} message(s) added, ${e.groups.checked} group(s) read).`,
+        );
+    }
+    if (e.pending) {
+        parts.push(
+            `${e.direct ? "1-1 messages" : "What is left"} can only come back from the phone: run \`${e.command}\` and tap on the phone.`,
+        );
+    }
+    return parts.join(" ");
+}
+
+/**
+ * The event as an MCP system event (the buffer's `pushSystem`).
+ *
+ * @param {object} e
+ * @returns {object}
+ */
+export function queueOverflowSystemEvent(e) {
+    return { type: "queue_overflow", ...e, text: describeQueueOverflow(e) };
+}

package/src/core/policy-layer.js

@@ -0,0 +1,55 @@
+/**
+ * The top layer of every runtime setting: the live policy (./policy-store.js), as the resolvers read it.
+ *
+ * Settings are layered built-in defaults < files (mcp-config.json, storage.json) < environment < policy. The resolvers
+ * (src/core/deploy-policy.js, confirm-guard.js, mcp-config.js, storage-quota.js) ask this module for one account's
+ * policy on every call, so a change applied by the admin API, `policy set` or a file drop counts on the next tool
+ * call, with no restart.
+ *
+ * This module has no imports on purpose: the resolvers load it, and the store (which needs the key layer) registers
+ * itself here when it is loaded (src/index.js loads it for every command). A process that never loads the store, as a
+ * unit test of a resolver, sees no policy.
+ */
+
+let provider = null;
+
+/**
+ * Install the function that returns one account's effective policy (nested, the tenant's under the account's own).
+ *
+ * @param {((ownId: string) => object|null)|null} fn
+ */
+export function setPolicyProvider(fn) {
+    provider = typeof fn === "function" ? fn : null;
+}
+
+/**
+ * One account's effective policy, or null when there is none (or no store is loaded).
+ *
+ * @param {string|null|undefined} ownId
+ * @returns {object|null}
+ */
+export function policyFor(ownId) {
+    const id = ownId === undefined || ownId === null ? "" : String(ownId).trim();
+    if (!id || !provider) return null;
+    try {
+        return provider(id) || null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * One key of one account's policy (dotted, e.g. `media.linkAuth`), or undefined.
+ *
+ * @param {string|null|undefined} ownId
+ * @param {string} key
+ * @returns {unknown}
+ */
+export function policyValue(ownId, key) {
+    let node = policyFor(ownId);
+    for (const p of key.split(".")) {
+        if (!node || typeof node !== "object" || Array.isArray(node)) return undefined;
+        node = node[p];
+    }
+    return node === null ? undefined : node;
+}

package/src/core/policy-schema.js

@@ -0,0 +1,401 @@
+/**
+ * The runtime policy's schema: every key the policy store (./policy-store.js) takes, how its value is checked, and the
+ * keys it refuses because they only take effect at a restart.
+ *
+ * A policy document is nested JSON, keyed like mcp-config.json and storage.json (`{"media": {"linkAuth": "bearer"}}`);
+ * a key is named by its dotted path (`media.linkAuth`) in the CLI, the admin API's errors and the audit log. A leaf
+ * whose value is itself an object (`media.deliver`) is one key.
+ *
+ * Secrets never go in a policy (a webhook signing secret, tokens, key material): those keys are refused like the
+ * restart-only ones, so a policy file and the audit log never hold one.
+ */
+import {
+    APPROVAL_DELIVERIES,
+    APPROVAL_SECRETS,
+    HIDDEN_CHAT_MODES,
+    MEDIA_DELIVER_MODES,
+    MEDIA_KINDS,
+    MEDIA_LINK_AUTHS,
+    durationMs,
+} from "./deploy-policy.js";
+
+const CONFIRM_MODES = ["agent", "human", "off"];
+const TRUE = ["1", "true", "on", "yes"];
+const FALSE = ["0", "false", "off", "no"];
+const UNITS = { b: 1, kb: 1024, mb: 1024 ** 2, gb: 1024 ** 3, tb: 1024 ** 4 };
+
+/**
+ * A storage size: a whole number of bytes, or `"2GB"`, `"500MB"`, `"1.5TB"` (1 KB = 1024 bytes); `"unlimited"` is
+ * no limit (an explicit one, which beats a lower layer's limit). Null when it is not one.
+ *
+ * @param {unknown} value
+ * @returns {number|"unlimited"|null}
+ */
+export function parseBytes(value) {
+    if (typeof value === "number") return Number.isSafeInteger(value) && value > 0 ? value : null;
+    const text = String(value ?? "")
+        .trim()
+        .toLowerCase();
+    if (text === "unlimited") return "unlimited";
+    const m = /^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb|tb)?$/.exec(text);
+    if (!m) return null;
+    const n = Math.floor(Number(m[1]) * UNITS[m[2] || "b"]);
+    return Number.isSafeInteger(n) && n > 0 ? n : null;
+}
+
+/**
+ * A number of days, `"30d"` (or a bare whole number); null when it is not one.
+ *
+ * @param {unknown} value
+ * @returns {number|null}
+ */
+export function parseDays(value) {
+    const m = /^\s*(\d+)\s*d?\s*$/i.exec(String(value ?? ""));
+    if (!m) return null;
+    const n = Number(m[1]);
+    return n >= 1 && n <= 36500 ? n : null;
+}
+
+/** `keep`, or a number of days. */
+function keepOrDays(value) {
+    if (
+        String(value ?? "")
+            .trim()
+            .toLowerCase() === "keep"
+    )
+        return { value: "keep" };
+    const d = parseDays(value);
+    return d ? { value: `${d}d` } : { error: 'is not "keep" or a number of days (e.g. "90d")' };
+}
+
+const oneOf = (allowed) => (value) => {
+    const v = String(value ?? "")
+        .trim()
+        .toLowerCase();
+    return allowed.includes(v) ? { value: v } : { error: `is not one of ${allowed.join(", ")}` };
+};
+const bool = (value) => {
+    if (value === true || value === false) return { value };
+    const v = String(value ?? "")
+        .trim()
+        .toLowerCase();
+    if (TRUE.includes(v)) return { value: true };
+    if (FALSE.includes(v)) return { value: false };
+    return { error: "is not true or false" };
+};
+const wholeNumber =
+    (min, max = Number.MAX_SAFE_INTEGER) =>
+    (value) => {
+        const n = typeof value === "number" ? value : Number(String(value ?? "").trim());
+        return Number.isInteger(n) && n >= min && n <= max
+            ? { value: n }
+            : { error: `is not a whole number from ${min}${max < Number.MAX_SAFE_INTEGER ? ` to ${max}` : " up"}` };
+    };
+const duration = (minMs) => (value) => {
+    const ms = durationMs(value);
+    return ms && ms >= minMs
+        ? { value: typeof value === "number" ? value : String(value).trim() }
+        : {
+              error: `is not a duration of at least ${minMs >= 60_000 ? `${minMs / 60_000}m` : `${minMs / 1000}s`} (e.g. "10m")`,
+          };
+};
+const bytes = (value) => {
+    const b = parseBytes(value);
+    return b === null ? { error: 'is not a size (bytes, or e.g. "2GB", or "unlimited")' } : { value };
+};
+const deliverMap = (value) => {
+    if (typeof value === "string") {
+        const v = value.trim().toLowerCase();
+        if (MEDIA_DELIVER_MODES.includes(v)) return { value: v };
+        const out = {};
+        for (const pair of v.split(",")) {
+            const [k, m] = pair.split("=").map((s) => s?.trim());
+            if (!MEDIA_KINDS.includes(k) || !MEDIA_DELIVER_MODES.includes(m))
+                return { error: `"${pair}" is not <kind>=<inline|link|tempfile>` };
+            out[k] = m;
+        }
+        return { value: out };
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return { error: "is not a mode or a {kind: mode} object" };
+    const out = {};
+    for (const [k, m] of Object.entries(value)) {
+        const mode = String(m ?? "")
+            .trim()
+            .toLowerCase();
+        if (!MEDIA_KINDS.includes(k)) return { error: `names an unknown media kind "${k}"` };
+        if (!MEDIA_DELIVER_MODES.includes(mode)) return { error: `.${k} is not inline, link or tempfile` };
+        out[k] = mode;
+    }
+    return { value: out };
+};
+const modeList = (value) => {
+    const list = Array.isArray(value) ? value : String(value ?? "").split(",");
+    const modes = list.map((m) => String(m).trim().toLowerCase()).filter(Boolean);
+    if (!modes.length || modes.some((m) => !MEDIA_DELIVER_MODES.includes(m)))
+        return { error: "is not a list of inline, link, tempfile" };
+    return { value: [...new Set(modes)] };
+};
+const webhookUrl = (value) => {
+    try {
+        const u = new URL(String(value));
+        if (u.protocol !== "https:" && u.protocol !== "http:") return { error: "is not an http(s) URL" };
+        return { value: String(value).trim() };
+    } catch {
+        return { error: "is not an absolute URL" };
+    }
+};
+const fraction = (value) => {
+    const n = typeof value === "number" ? value : Number(String(value ?? "").trim());
+    return n > 0 && n <= 1 ? { value: n } : { error: "is not a fraction above 0 and at most 1 (e.g. 0.8)" };
+};
+const durationOrOff = (minMs) => (value) =>
+    String(value ?? "")
+        .trim()
+        .toLowerCase() === "off"
+        ? { value: "off" }
+        : duration(minMs)(value).error
+          ? { error: `is "off" or a duration of at least ${minMs / 60_000}m (e.g. "6h")` }
+          : duration(minMs)(value);
+const accountIds = (value) => {
+    const list = Array.isArray(value) ? value : String(value ?? "").split(",");
+    const ids = list.map((s) => String(s).trim()).filter(Boolean);
+    if (ids.some((id) => !/^[1-9][0-9]{0,30}$/.test(id))) return { error: "is not a list of account ids" };
+    return { value: [...new Set(ids)] };
+};
+
+/** The presence modes (src/core/presence.js). */
+export const PRESENCE_MODES = Object.freeze(["on-demand", "always-on"]);
+
+/**
+ * Every policy key: its check, and where it may be set (`tenant`: only in a tenant's file; `scopes`: only in these
+ * kinds of file). A user's file (`users/<userId>.json`) takes the account keys, minus the tenant-only ones.
+ * The values are read by the same resolvers that read mcp-config.json and storage.json, with the policy on top.
+ */
+export const POLICY_KEYS = Object.freeze({
+    confirmMode: { check: oneOf(CONFIRM_MODES) },
+    hiddenChats: { check: oneOf(HIDDEN_CHAT_MODES) },
+    allowPinArgument: { check: bool },
+    "approval.secret": { check: oneOf(APPROVAL_SECRETS) },
+    "approval.deliver": { check: oneOf(APPROVAL_DELIVERIES) },
+    "media.deliver": { check: deliverMap },
+    "media.inlineMaxBytes": { check: wholeNumber(1) },
+    "media.allowDeliver": { check: modeList },
+    "media.linkTtl": { check: duration(1000) },
+    "media.tempfileTtl": { check: duration(1000) },
+    "media.linkAuth": { check: oneOf(MEDIA_LINK_AUTHS) },
+    "media.linkRateLimit": { check: wholeNumber(1) },
+    "media.capability.maxClients": { check: wholeNumber(1) },
+    "media.capability.ttl": { check: duration(1000) },
+    "media.autoOpen": { check: bool },
+    webhook: { check: webhookUrl },
+    webhookBatchSize: { check: wholeNumber(1, 100) },
+    webhookMaxAge: { check: duration(60_000) },
+    "quota.account.limit": { check: bytes },
+    "quota.tenant.limit": { check: bytes, tenant: true },
+    "quota.tenant.accounts": { check: accountIds, tenant: true },
+    "quota.graceDays": { check: wholeNumber(0, 3650) },
+    "quota.warnAt": { check: fraction },
+    "quota.purgeOrder": { check: oneOf(["media-first"]) },
+    "retention.messages": { check: keepOrDays },
+    "retention.media": { check: keepOrDays },
+    "retention.outboxDead": {
+        check: (v) =>
+            parseDays(v) ? { value: `${parseDays(v)}d` } : { error: 'is not a number of days (e.g. "30d")' },
+    },
+    "retention.purgeEvery": { check: duration(60_000) },
+    // What a group's local history becomes when the account leaves it, is removed or blocked, or it is disbanded
+    // (src/core/group-exit.js): read at each exit, no restart. keep -> purge purges the kept groups on the next pass.
+    "groups.onLeave": { check: oneOf(["purge", "keep"]) },
+    // On-demand presence (src/core/presence.js, src/core/presence-config.js): live, no restart.
+    "presence.mode": { check: oneOf(PRESENCE_MODES) },
+    "presence.idleTimeout": { check: duration(30_000) },
+    "presence.minConnected": { check: duration(1000) },
+    "presence.maxWakesPerHour": { check: wholeNumber(1, 1000) },
+    "presence.warmWait": { check: duration(1000) },
+    "presence.connectOnStart": { check: bool },
+    "presence.catchUpEvery": { check: durationOrOff(5 * 60_000) },
+    "presence.maxLeases": { check: wholeNumber(1, 1024) },
+    "presence.leaseTtl": { check: duration(15_000) },
+    "presence.leaseTtlMax": { check: duration(15_000) },
+    "presence.waitHoldsSocket": { check: bool },
+    "presence.onKick": { check: oneOf(["yield", "exit"]) },
+    // The always-on cap (owner decision 1: over it, the oldest always-on account is demoted to on-demand).
+    "presence.alwaysOn.maxPerUser": { check: wholeNumber(0, 10_000), scopes: ["tenant", "user"] },
+    "presence.alwaysOn.maxPerTenant": { check: wholeNumber(0, 1_000_000), scopes: ["tenant"] },
+});
+
+/**
+ * Keys a running server cannot change: they are read once at start (the port, the address, TLS, the key provider)
+ * or they are secrets, which never go in a policy. A change to one is refused with `restartRequired`.
+ */
+export const RESTART_KEYS = Object.freeze([
+    "httpPort",
+    "host",
+    "publicUrl",
+    "tls",
+    "oauth",
+    "trustedProxies",
+    "admin",
+    "webhookSecret",
+    "media.downloadDir",
+    "provider",
+    "dkeyLayer",
+    "dpapi",
+    "kms",
+    "passphrase",
+    "systemdCreds",
+    "keychain",
+    "secretService",
+    "env",
+    "accounts",
+]);
+
+const isPlainObject = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
+const isBranch = (path) => Object.keys(POLICY_KEYS).some((k) => k.startsWith(`${path}.`));
+const restartKeyOf = (path) => RESTART_KEYS.find((k) => path === k || path.startsWith(`${k}.`)) ?? null;
+
+/**
+ * A nested policy as `{dotted: value}` leaves; a value of null is kept (it means "remove" in a patch).
+ *
+ * @param {object} policy
+ * @returns {Record<string, unknown>}
+ */
+export function flattenPolicy(policy) {
+    const out = {};
+    const walk = (obj, prefix) => {
+        for (const [k, v] of Object.entries(obj ?? {})) {
+            const path = prefix ? `${prefix}.${k}` : k;
+            if (!POLICY_KEYS[path] && isPlainObject(v) && (isBranch(path) || restartKeyOf(path) === null))
+                walk(v, path);
+            else out[path] = v;
+        }
+    };
+    walk(policy, "");
+    return out;
+}
+
+/**
+ * Leaves back into a nested policy.
+ *
+ * @param {Record<string, unknown>} flat
+ * @returns {object}
+ */
+export function nestPolicy(flat) {
+    const out = {};
+    for (const [path, value] of Object.entries(flat)) {
+        const parts = path.split(".");
+        let node = out;
+        for (const p of parts.slice(0, -1)) node = node[p] = isPlainObject(node[p]) ? node[p] : {};
+        node[parts.at(-1)] = value;
+    }
+    return out;
+}
+
+/**
+ * Check a policy (nested), for an account's file or a tenant's. Values are normalized (`"BEARER"` → `"bearer"`).
+ *
+ * @param {unknown} policy
+ * @param {{scope?: "account"|"user"|"tenant", allowNull?: boolean}} [opts] - `allowNull`: a patch, where null removes a key
+ * @returns {{policy: object, errors: Array<{key: string, error: string}>, restartRequired: string[]}}
+ */
+export function validatePolicy(policy, { scope = "account", allowNull = false } = {}) {
+    const errors = [];
+    const restartRequired = [];
+    if (!isPlainObject(policy)) {
+        return { policy: {}, errors: [{ key: "", error: "the policy must be a JSON object" }], restartRequired };
+    }
+    const clean = {};
+    for (const [key, value] of Object.entries(flattenPolicy(policy))) {
+        const restart = restartKeyOf(key);
+        if (restart) {
+            restartRequired.push(key);
+            continue;
+        }
+        const spec = POLICY_KEYS[key];
+        if (!spec) {
+            errors.push({ key, error: "is not a policy key" });
+            continue;
+        }
+        if (spec.tenant && scope !== "tenant") {
+            errors.push({ key, error: "is set in a tenant's policy only" });
+            continue;
+        }
+        if (spec.scopes && !spec.scopes.includes(scope)) {
+            errors.push({ key, error: `is set in a ${spec.scopes.join(" or ")} policy only` });
+            continue;
+        }
+        if (value === null) {
+            if (allowNull) clean[key] = null;
+            else errors.push({ key, error: "is null (leave the key out instead)" });
+            continue;
+        }
+        const r = spec.check(value);
+        if (r.error) errors.push({ key, error: r.error });
+        else clean[key] = r.value;
+    }
+    return { policy: nestPolicy(clean), errors, restartRequired };
+}
+
+/**
+ * One value as the CLI takes it (`policy set <key> <value>`): JSON when it parses (a number, an object, a list,
+ * `true`), else the text itself.
+ *
+ * @param {string} text
+ * @returns {unknown}
+ */
+export function parseCliValue(text) {
+    const t = String(text ?? "").trim();
+    try {
+        return JSON.parse(t);
+    } catch {
+        return t;
+    }
+}
+
+/**
+ * A JSON merge patch (RFC 7396) of two nested policies: null removes a key, an object merges, anything else replaces.
+ *
+ * @param {object} base
+ * @param {object} patch
+ * @returns {object}
+ */
+export function mergePolicy(base, patch) {
+    const flat = { ...flattenPolicy(base) };
+    for (const [key, value] of Object.entries(flattenPolicy(patch))) {
+        if (value === null) delete flat[key];
+        else flat[key] = value;
+    }
+    return nestPolicy(flat);
+}
+
+/**
+ * The dotted keys whose value differs between two policies.
+ *
+ * @param {object} a
+ * @param {object} b
+ * @returns {string[]}
+ */
+export function changedKeys(a, b) {
+    const fa = flattenPolicy(a ?? {});
+    const fb = flattenPolicy(b ?? {});
+    return [...new Set([...Object.keys(fa), ...Object.keys(fb)])]
+        .filter((k) => JSON.stringify(fa[k]) !== JSON.stringify(fb[k]))
+        .sort();
+}
+
+/**
+ * One key's value in a nested policy, or undefined.
+ *
+ * @param {object|null|undefined} policy
+ * @param {string} key - dotted
+ * @returns {unknown}
+ */
+export function policyGet(policy, key) {
+    let node = policy;
+    for (const p of key.split(".")) {
+        if (!isPlainObject(node)) return undefined;
+        node = node[p];
+    }
+    return node;
+}