@ardennguyen/zalo-agent-cli 2.5.8 → 3.0.0

package/src/core/fleet-serve.js

@@ -0,0 +1,292 @@
+/**
+ * `zalo-agent fleet serve`: the fleet controller's HTTP server (built around ./fleet-controller.js) and what it is built from on a
+ * real host: the supervisor driver (./fleet-supervisor.js), each daemon's loopback channel, the CLI for a logout or a
+ * removal, the admin credential (./admin-api.js), and the admin webhook.
+ *
+ * It holds no account lock and opens no Zalo socket. Binds 127.0.0.1 unless told otherwise; put a reverse proxy with
+ * TLS in front (`publicUrl`) for a CRM on another machine.
+ */
+import express from "express";
+import { createHash, createHmac, randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { createServer } from "node:net";
+import { createInterface } from "node:readline";
+import { join } from "node:path";
+import { parseEnv } from "node:util";
+import { createAdminApi, resolveAdminCredentials } from "./admin-api.js";
+import { assignPorts } from "./fleet.js";
+import { LOCAL_PROXY, accountPublicUrl, renderAccountEnv } from "./fleet-templates.js";
+import { applyPolicy, getPolicy } from "./policy-store.js";
+import { writeFileAtomic } from "../zalo/kernel/atomic-file.js";
+
+/** The default port of the controller. */
+export const DEFAULT_CONTROLLER_PORT = 3899;
+
+/**
+ * The SHA-256 of every agent token in an env dir (`<dir>/<ownId>.env`, `ZALO_MCP_AUTH_TOKEN`): refused by the
+ * controller even if an admin token were set to the same value.
+ *
+ * @param {string|null} dir
+ * @returns {Set<string>} hex digests
+ */
+export function agentTokenHashes(dir) {
+    const out = new Set();
+    if (!dir || !existsSync(dir)) return out;
+    for (const f of readdirSync(dir).filter((n) => n.endsWith(".env"))) {
+        try {
+            const env = parseEnv(readFileSync(join(dir, f), "utf8"));
+            for (const [k, v] of Object.entries(env)) {
+                if (/^ZALO_MCP_AUTH_TOKEN(_\d+)?$/.test(k) && v)
+                    out.add(createHash("sha256").update(v, "utf8").digest("hex"));
+            }
+        } catch {
+            /* an unreadable file holds no token we can check */
+        }
+    }
+    return out;
+}
+
+/**
+ * Run this CLI as a child (`account remove`, `logout`): the same guards and code paths a person gets.
+ *
+ * @param {string[]} args
+ * @param {{env?: NodeJS.ProcessEnv}} [o]
+ * @returns {Promise<{code: number, stdout: string, stderr: string}>}
+ */
+export function runSelf(args, { env = process.env } = {}) {
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, [process.argv[1], ...args], {
+            env: { ...env, ZALO_JSON_MODE: "1" },
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (d) => (stdout += d));
+        child.stderr.on("data", (d) => (stderr += d));
+        child.on("error", (e) => resolve({ code: 1, stdout, stderr: stderr + e.message }));
+        child.on("exit", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+    });
+}
+
+/**
+ * The admin webhook: every `account_state` and QR event, POSTed as JSON, signed like the daemons' webhooks when a
+ * secret is set (`Authorization: Bearer <secret>`, `X-Zalo-Signature: sha256=<HMAC>`). Fire and forget.
+ *
+ * @param {string|null} url
+ * @param {string|null} secret
+ * @param {typeof fetch} [fetchFn]
+ * @returns {(event: object) => void}
+ */
+export function adminWebhook(url, secret, fetchFn = fetch) {
+    if (!url) return () => {};
+    return (event) => {
+        const body = JSON.stringify(event);
+        const headers = { "Content-Type": "application/json" };
+        if (secret) {
+            headers.Authorization = `Bearer ${secret}`;
+            headers["X-Zalo-Signature"] = `sha256=${createHmac("sha256", secret).update(body).digest("hex")}`;
+        }
+        fetchFn(url, { method: "POST", headers, body, signal: AbortSignal.timeout(5000) }).catch(() => {});
+    };
+}
+
+/**
+ * Build the controller's express app.
+ *
+ * @param {object} args
+ * @param {object} args.controller - ./fleet-controller.js
+ * @param {object} [args.config] - the MCP config (`admin.*`)
+ * @param {NodeJS.ProcessEnv} [args.env]
+ * @param {Set<string>} [args.agentHashes] - refused tokens (hex SHA-256)
+ * @param {{servePage: (req: object, res: object) => Promise<boolean>}|null} [args.qrPages]
+ * @param {(line: string) => void} [args.log]
+ * @returns {{app: object, admin: object}}
+ */
+export function buildControllerApp({
+    controller,
+    config = {},
+    env = process.env,
+    agentHashes = new Set(),
+    qrPages = null,
+    log = (l) => console.error(l),
+}) {
+    const creds = resolveAdminCredentials({ config, env });
+    for (const p of creds.problems) log(`[fleet] ${p}`);
+    const admin = createAdminApi({
+        ownId: null,
+        config,
+        hashes: creds.hashes,
+        mtls: false,
+        isAgentCredential: (token) => agentHashes.has(createHash("sha256").update(token, "utf8").digest("hex")),
+        routes: (req, res, ctx) => controller.handle(req, res, ctx),
+        log,
+    });
+    const app = express();
+    app.disable("x-powered-by");
+    if (qrPages) {
+        app.use("/zalo/qr/", (req, res, next) => {
+            req.url = req.originalUrl;
+            qrPages
+                .servePage(req, res)
+                .then((done) => {
+                    if (!done && !res.headersSent) res.status(404).set("Cache-Control", "no-store").end();
+                })
+                .catch(next);
+        });
+    }
+    app.use(express.json({ limit: "64kb" }));
+    app.use("/zalo/admin", (req, res) => admin.handle(req, res));
+    app.get("/health", (_req, res) => res.json({ status: "ok", kind: "fleet-controller" }));
+    return { app, admin };
+}
+
+/** A free loopback port (the child login's own page; never offered, but it must not collide). */
+function freePort() {
+    return new Promise((resolve) => {
+        const srv = createServer();
+        srv.listen(0, "127.0.0.1", () => {
+            const { port } = srv.address();
+            srv.close(() => resolve(port));
+        });
+        srv.on("error", () => resolve(0));
+    });
+}
+
+/**
+ * One QR login as a child process (`zalo-agent --json login`), for ./fleet-qr.js: its JSON lines, a kill, its exit.
+ * The child is the same `login` a person runs (credentials saved, account registered); a QR login is HTTP and opens no
+ * chat socket.
+ *
+ * @param {{proxy?: string|null}} [o]
+ * @returns {{onLine: (fn: (line: string) => void) => void, kill: () => void, exited: Promise<number>}}
+ */
+export function spawnLoginChild({ proxy = null } = {}) {
+    const lines = [];
+    const subscribers = [];
+    let child = null;
+    let killed = false;
+    const exited = freePort().then(
+        (port) =>
+            new Promise((resolve) => {
+                if (killed) return resolve(1);
+                child = spawn(
+                    process.execPath,
+                    [
+                        process.argv[1],
+                        "--json",
+                        "login",
+                        ...(port ? ["--qr-port", String(port)] : []),
+                        ...(proxy ? ["--proxy", proxy] : []),
+                    ],
+                    {
+                        env: { ...process.env, ZALO_JSON_MODE: "1" },
+                        stdio: ["ignore", "pipe", "pipe"],
+                        windowsHide: true,
+                    },
+                );
+                const rl = createInterface({ input: child.stdout });
+                rl.on("line", (l) => {
+                    lines.push(l);
+                    for (const fn of subscribers) fn(l);
+                });
+                child.stderr.resume();
+                child.on("error", () => resolve(1));
+                child.on("exit", (code) => resolve(code ?? 1));
+            }),
+    );
+    return {
+        onLine: (fn) => {
+            subscribers.push(fn);
+            for (const l of lines) fn(l);
+        },
+        kill: () => {
+            killed = true;
+            child?.kill();
+        },
+        exited,
+    };
+}
+
+/**
+ * The QR add's finish steps, after the child login registered the account: a port, the env file with a generated
+ * token (and, with a `domain`, the account's public URL as `fleet generate --domain` writes it), the user's
+ * membership, the presence mode, and the start (or a deliberate restart of a daemon the new login kicked).
+ *
+ * @param {object} o
+ * @param {string} o.ownId
+ * @param {string} o.userId
+ * @param {"on-demand"|"always-on"|null} o.presence
+ * @param {boolean} o.start
+ * @param {boolean} o.wasRunning
+ * @param {string|null} o.envDir
+ * @param {string|null} [o.domain] - the proxy layout's host: the env file gets `ZALO_MCP_PUBLIC_URL=https://<domain>/a/<id>`
+ * @param {boolean} [o.trustProxy] - also `ZALO_MCP_TRUSTED_PROXIES=127.0.0.1` (the shared env does not trust the proxy)
+ * @param {{start: Function, restart: Function}} o.driver
+ * @param {() => string} [o.makeToken]
+ * @returns {Promise<object>} what the `done` event carries
+ */
+export async function finishQrAdd({
+    ownId,
+    userId,
+    presence,
+    start,
+    wasRunning,
+    envDir,
+    domain = null,
+    trustProxy = false,
+    driver,
+    makeToken = () => randomBytes(32).toString("hex"),
+}) {
+    const port = assignPorts([ownId]).ports[ownId];
+    const publicUrl = domain ? accountPublicUrl(domain, ownId) : null;
+    let envWritten = false;
+    if (envDir) {
+        const file = join(envDir, `${ownId}.env`);
+        if (!existsSync(file)) {
+            mkdirSync(envDir, { recursive: true });
+            const trustedProxies = publicUrl && trustProxy ? LOCAL_PROXY : null;
+            writeFileAtomic(file, renderAccountEnv({ ownId, port, token: makeToken(), publicUrl, trustedProxies }), {
+                mode: 0o600,
+            });
+            envWritten = true;
+        }
+    }
+    const user = getPolicy({ kind: "user", id: userId });
+    if (!user.accounts.includes(ownId)) {
+        applyPolicy({
+            target: { kind: "user", id: userId },
+            op: "patch",
+            policy: {},
+            accounts: [...user.accounts, ownId],
+            actor: "fleet-controller qr",
+        });
+    }
+    let demoted = [];
+    if (presence) {
+        demoted = applyPolicy({
+            target: { kind: "account", id: ownId },
+            op: "patch",
+            policy: { presence: { mode: presence } },
+            actor: "fleet-controller qr",
+        }).demoted;
+    }
+    const out = {
+        port,
+        envWritten,
+        userId,
+        ...(envWritten && publicUrl ? { publicUrl } : {}),
+        ...(demoted.length ? { demoted } : {}),
+    };
+    if (wasRunning) {
+        // The new login took the session from the running daemon (it exits 3): bring it back on purpose.
+        const r = await driver.restart(ownId);
+        return { ...out, restarted: "relogin", started: r.ok };
+    }
+    if (start) {
+        const r = await driver.start(ownId);
+        return { ...out, started: r.ok };
+    }
+    return { ...out, started: false };
+}

package/src/core/fleet-supervisor.js

@@ -0,0 +1,176 @@
+/**
+ * Who starts and stops an account's daemon on this host: systemd (the `zalo-mcp@<ownId>.service` template unit that
+ * `fleet generate` writes) or a plain spawn (`fleet start` / `fleet stop`). One interface for both, so the fleet
+ * controller (`fleet serve`, ./fleet-controller.js) and the `fleet` commands drive either the same way:
+ *
+ *     driver.start(ownId) / stop(ownId) / restart(ownId)  -> {ok, detail, code?}
+ *     driver.status(ownId)                                -> {running, state, pid?}
+ *
+ * - **systemd**: `systemctl start|stop|restart zalo-mcp@<ownId>.service`, run without a shell, the unit name built
+ *   from a checked account id only. A service user drives it through a polkit rule that names `zalo-mcp@*.service`
+ *   and nothing else (docs/config-samples/systemd/zalo-fleet-polkit.rules). `RestartPreventExitStatus=3 4` keeps a
+ *   kicked or refused account down until a person starts it.
+ * - **spawn**: `spawnDaemonProcess` / `stopDaemon` (./daemon-channel.js), as `fleet start` / `fleet stop` do.
+ *
+ * `ZALO_FLEET_SUPERVISOR=systemd|spawn` picks one; unset: systemd when `/run/systemd/system` exists, else spawn
+ * ({@link detectSupervisor}, for the controller), or per account by its unit's state ({@link supervisorOf}, for
+ * `fleet start|stop|restart`, which must not start a daemon beside a unit or stop one its unit restarts).
+ * The runner is injectable, so tests drive a fake `systemctl`.
+ */
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+
+/** The template unit `fleet generate` writes. */
+export const UNIT_TEMPLATE_NAME = "zalo-mcp@.service";
+
+const ACCOUNT_ID = /^[1-9][0-9]{0,30}$/;
+
+/**
+ * The unit of one account. Throws on anything that is not an account id, so no other unit can be named.
+ *
+ * @param {string} ownId
+ * @returns {string}
+ */
+export function unitName(ownId) {
+    const id = String(ownId ?? "");
+    if (!ACCOUNT_ID.test(id)) throw new Error(`"${id}" is not an account id`);
+    return `zalo-mcp@${id}.service`;
+}
+
+/**
+ * Run `systemctl` with these arguments, no shell.
+ *
+ * @param {string[]} args
+ * @param {{timeoutMs?: number}} [o]
+ * @returns {Promise<{code: number, stdout: string, stderr: string}>}
+ */
+export function runSystemctl(args, { timeoutMs = 60_000 } = {}) {
+    return new Promise((resolve) => {
+        execFile("systemctl", args, { timeout: timeoutMs, windowsHide: true }, (err, stdout, stderr) => {
+            const code = err ? (typeof err.code === "number" ? err.code : 1) : 0;
+            resolve({ code, stdout: String(stdout ?? ""), stderr: String(stderr ?? err?.message ?? "") });
+        });
+    });
+}
+
+/**
+ * Which supervisor this host uses.
+ *
+ * @param {{env?: NodeJS.ProcessEnv, exists?: (p: string) => boolean}} [o]
+ * @returns {"systemd"|"spawn"}
+ */
+export function detectSupervisor({ env = process.env, exists = existsSync } = {}) {
+    const asked = String(env.ZALO_FLEET_SUPERVISOR ?? "")
+        .trim()
+        .toLowerCase();
+    if (asked === "systemd" || asked === "spawn") return asked;
+    return exists("/run/systemd/system") ? "systemd" : "spawn";
+}
+
+/** Unit states in which systemd owns the account's daemon (running, starting, stopping, or kept down). */
+const UNIT_OWNS = new Set(["active", "activating", "deactivating", "reloading", "failed"]);
+
+/**
+ * Who runs this one account's daemon: systemd when its `zalo-mcp@<ownId>` unit is loaded and either running
+ * (or starting, stopping, kept down as `failed`) or enabled; else a plain spawn. `ZALO_FLEET_SUPERVISOR`
+ * decides for every account when set. A daemon started beside a running unit races the unit for `daemon.lock`
+ * (the unit then loops to its start limit), and a spawn-stopped one is restarted by `Restart=always`: so
+ * `fleet start|stop|restart` ask this per account, and go through systemctl for a unit.
+ *
+ * @param {string} ownId
+ * @param {{env?: NodeJS.ProcessEnv, exists?: (p: string) => boolean, run?: typeof runSystemctl}} [o]
+ * @returns {Promise<"systemd"|"spawn">}
+ */
+export async function supervisorOf(ownId, { env = process.env, exists = existsSync, run = runSystemctl } = {}) {
+    const asked = String(env.ZALO_FLEET_SUPERVISOR ?? "")
+        .trim()
+        .toLowerCase();
+    if (asked === "systemd" || asked === "spawn") return asked;
+    if (!exists("/run/systemd/system")) return "spawn";
+    const r = await run(["show", unitName(ownId), "--property=LoadState,ActiveState,UnitFileState"], {
+        timeoutMs: 15_000,
+    });
+    if (r.code !== 0) return "spawn";
+    const p = Object.fromEntries(
+        r.stdout
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => l.includes("="))
+            .map((l) => [l.slice(0, l.indexOf("=")), l.slice(l.indexOf("=") + 1)]),
+    );
+    if (p.LoadState !== "loaded") return "spawn";
+    return UNIT_OWNS.has(p.ActiveState) || p.UnitFileState === "enabled" ? "systemd" : "spawn";
+}
+
+/**
+ * The systemd driver.
+ *
+ * @param {{run?: typeof runSystemctl}} [o]
+ * @returns {object}
+ */
+export function createSystemdDriver({ run = runSystemctl } = {}) {
+    const act = async (verb, ownId) => {
+        const unit = unitName(ownId);
+        const r = await run([verb, unit]);
+        return r.code === 0
+            ? { ok: true, detail: `${verb} ${unit}` }
+            : { ok: false, code: r.code, detail: `systemctl ${verb} ${unit} failed: ${r.stderr.trim() || r.code}` };
+    };
+    return {
+        kind: "systemd",
+        start: (id) => act("start", id),
+        stop: (id) => act("stop", id),
+        restart: (id) => act("restart", id),
+        async status(ownId) {
+            const r = await run(["is-active", unitName(ownId)]);
+            const state = r.stdout.trim() || "unknown";
+            return { running: state === "active" || state === "activating" || state === "reloading", state };
+        },
+    };
+}
+
+/**
+ * The spawn driver: the daemons are this host's own child processes, as `fleet start` makes them.
+ *
+ * @param {object} o
+ * @param {(args: {accountDir: string, args: string[], env: object}) => Promise<object>} o.spawnDaemon
+ * @param {(accountDir: string) => Promise<{stopped: boolean, graceful?: boolean, pid?: number}>} o.stopDaemon
+ * @param {(accountDir: string) => {running: boolean, pid: number|null}} o.daemonStatus
+ * @param {(ownId: string) => string} o.accountDir
+ * @param {(ownId: string) => string[]} o.argsFor - the daemon's command line (e.g. `mcp start --http <port>`)
+ * @param {(ownId: string) => object} [o.envFor] - extra environment (the account's env file)
+ * @returns {object}
+ */
+export function createSpawnDriver({ spawnDaemon, stopDaemon, daemonStatus, accountDir, argsFor, envFor = () => ({}) }) {
+    const start = async (ownId) => {
+        unitName(ownId);
+        const r = await spawnDaemon({ accountDir: accountDir(ownId), args: argsFor(ownId), env: envFor(ownId) });
+        if (r.ok) return { ok: true, detail: `started (pid ${r.pid})`, pid: r.pid };
+        if (r.alreadyRunning) return { ok: true, detail: `already running (pid ${r.pid})`, pid: r.pid };
+        return { ok: false, detail: `failed: ${r.error}${r.logPath ? ` (log: ${r.logPath})` : ""}` };
+    };
+    const stop = async (ownId) => {
+        unitName(ownId);
+        const r = await stopDaemon(accountDir(ownId));
+        return {
+            ok: true,
+            detail: r.stopped
+                ? `stopped (pid ${r.pid}${r.graceful === false ? ", forced" : ""})`
+                : "no daemon was running",
+        };
+    };
+    return {
+        kind: "spawn",
+        start,
+        stop,
+        async restart(ownId) {
+            await stop(ownId);
+            return start(ownId);
+        },
+        async status(ownId) {
+            unitName(ownId);
+            const s = daemonStatus(accountDir(ownId));
+            return { running: Boolean(s.running), state: s.running ? "active" : "inactive", pid: s.pid ?? null };
+        },
+    };
+}