@ardennguyen/zalo-agent-cli 2.5.8 → 3.0.0

package/src/core/e2ee-notice.js

@@ -0,0 +1,41 @@
+/**
+ * End-to-end encrypted messages this client cannot read, counted and named once per daemon.
+ *
+ * Zalo routes an end-to-end encrypted conversation's messages (`chat.e2ee.*`) through the Signal pushes 551, 552 and
+ * 535. This client has no Signal keys, so the listener announces each one marked `data.undecryptable`, with its
+ * ciphertext removed from `content` (design 6.1 item 7, src/zalo/listener/dispatch.js). `listen` and `mcp start`
+ * each build one notice: the first such message is logged with what it means, every one is counted, and none is
+ * logged again, so a busy encrypted conversation cannot flood the log.
+ *
+ * Nothing here writes to stdout; the line carries no id, name or content.
+ */
+
+/**
+ * Build a daemon's notice.
+ *
+ * @param {object} [opts]
+ * @param {(line: string) => void} [opts.log] - where the one line goes (stderr)
+ * @returns {{note: (msg: object) => boolean, count: () => number}} `note` counts a listener message that is
+ *   undecryptable and answers whether it was; `count` is how many were seen
+ */
+export function createUndecryptableNotice({ log = (line) => console.error(line) } = {}) {
+    let seen = 0;
+    return {
+        note(msg) {
+            if (msg?.data?.undecryptable !== true) return false;
+            seen++;
+            if (seen === 1) {
+                try {
+                    log(
+                        "an end-to-end encrypted message arrived; this client cannot decrypt it, so it is kept " +
+                            "without its text (marked undecryptable). Later ones are counted, not logged again.",
+                    );
+                } catch {
+                    /* a broken logger must not break the daemon */
+                }
+            }
+            return true;
+        },
+        count: () => seen,
+    };
+}

package/src/core/exit-codes.js

@@ -0,0 +1,7 @@
+/** Exit codes a long-running command ends with when it must not be restarted blindly. */
+export const EXIT_CODE = Object.freeze({
+    /** Another session took the account. A supervisor must not restart this on its own. */
+    KICKED: 3,
+    /** The saved login was refused and logging in again did not help. */
+    SESSION_REVOKED: 4,
+});

package/src/core/export-crypt.js

@@ -0,0 +1,290 @@
+/**
+ * The password-encrypted export file (`db export --password`, the admin API's `encryption: "password"`): a plain
+ * SQLite export sealed with a key the user's password gives, so the person it is handed to opens it with that password
+ * and nothing of this machine (no keyring, no provider).
+ *
+ * Layout (all integers big-endian; docs/security.md "Password-encrypted export file"):
+ *
+ *     magic      8 bytes   "ZAEXPORT"
+ *     headerLen  uint32    length of the header
+ *     header     JSON      {format: "zalo-agent-cli/export", version: 1, content: "sqlite3", cipher: "aes-256-gcm",
+ *                           kdf: {name: "scrypt", N, r, p, keyLength: 32, salt: <base64, 16 bytes>},
+ *                           chunkSize, nonce: <base64, 8 bytes>, plaintextBytes, createdAt}
+ *     chunks     each chunkSize bytes of plaintext (the last one 0..chunkSize) encrypted, followed by its 16-byte tag
+ *
+ * - key = scrypt(password (UTF-8), salt, N, r, p, 32). The password is never stored, logged or written anywhere.
+ * - chunk i: nonce = header nonce (8 bytes) || uint32(i); AAD = SHA-256(magic || headerLen || header) || uint32(i) ||
+ *   final (1 byte: 1 for the last chunk). A changed header, a reordered, dropped or added chunk, or a file cut at a
+ *   chunk boundary fails to open: the last chunk is the only one sealed as final.
+ * - The plaintext is a SQLite database (the decrypted export, with `export_info` and `export_hidden_threads`).
+ *
+ * Streaming both ways, one chunk in memory at a time.
+ */
+import { createHash, createCipheriv, createDecipheriv, randomBytes, scrypt as scryptCb } from "node:crypto";
+import { open, rm, stat } from "node:fs/promises";
+
+export const EXPORT_MAGIC = Buffer.from("ZAEXPORT", "ascii");
+export const EXPORT_FORMAT = "zalo-agent-cli/export";
+export const EXPORT_VERSION = 1;
+const TAG_BYTES = 16;
+const MAX_HEADER_BYTES = 64 * 1024;
+/** scrypt cost the export is written with: N 2^17, r 8, p 1 (128 MiB, about half a second). */
+export const DEFAULT_KDF = Object.freeze({ N: 2 ** 17, r: 8, p: 1 });
+/** The most a file may ask a reader to spend (a crafted header must not exhaust memory). */
+const MAX_N = 2 ** 20;
+export const DEFAULT_CHUNK = 1024 * 1024;
+/** A password's length bounds. */
+export const PASSWORD_MIN = 8;
+export const PASSWORD_MAX = 1024;
+
+/** A failure to read an export: wrong password, damaged or not an export. */
+export class ExportCryptError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.name = "ExportCryptError";
+        this.code = code;
+    }
+}
+
+/**
+ * Refuse a password the export will not take (too short or too long, not text). Returns nothing when it is fine.
+ *
+ * @param {unknown} password
+ * @returns {string|null} why it is refused
+ */
+export function passwordProblem(password) {
+    if (typeof password !== "string") return "the password must be text";
+    const n = [...password].length;
+    if (n < PASSWORD_MIN) return `the password needs at least ${PASSWORD_MIN} characters`;
+    if (n > PASSWORD_MAX) return `the password may have at most ${PASSWORD_MAX} characters`;
+    return null;
+}
+
+function deriveKey(password, kdf) {
+    const { N, r, p } = kdf;
+    const salt = Buffer.from(kdf.salt, "base64");
+    return new Promise((resolve, reject) => {
+        scryptCb(
+            Buffer.from(password, "utf8"),
+            salt,
+            32,
+            { N, r, p, maxmem: 128 * N * r + 32 * 1024 * 1024 },
+            (err, key) => (err ? reject(err) : resolve(key)),
+        );
+    });
+}
+
+const u32 = (n) => {
+    const b = Buffer.alloc(4);
+    b.writeUInt32BE(n >>> 0);
+    return b;
+};
+
+function chunkAad(headerHash, index, final) {
+    return Buffer.concat([headerHash, u32(index), Buffer.from([final ? 1 : 0])]);
+}
+
+/**
+ * Encrypt a file under a password into the export format. Writes `out` (0600, never over an existing file); on any
+ * failure nothing is left there.
+ *
+ * @param {string} src - the plaintext (a SQLite file)
+ * @param {string} out
+ * @param {string} password
+ * @param {{kdf?: {N: number, r: number, p: number}, chunkSize?: number, now?: () => number}} [opts]
+ * @returns {Promise<{bytes: number, plaintextBytes: number, kdf: object}>}
+ */
+export async function encryptExportFile(
+    src,
+    out,
+    password,
+    { kdf = DEFAULT_KDF, chunkSize = DEFAULT_CHUNK, now = Date.now } = {},
+) {
+    const problem = passwordProblem(password);
+    if (problem) throw new ExportCryptError(problem, "PASSWORD");
+    const size = (await stat(src)).size;
+    const params = {
+        name: "scrypt",
+        N: kdf.N,
+        r: kdf.r,
+        p: kdf.p,
+        keyLength: 32,
+        salt: randomBytes(16).toString("base64"),
+    };
+    const nonce = randomBytes(8);
+    const header = Buffer.from(
+        JSON.stringify({
+            format: EXPORT_FORMAT,
+            version: EXPORT_VERSION,
+            content: "sqlite3",
+            cipher: "aes-256-gcm",
+            kdf: params,
+            chunkSize,
+            nonce: nonce.toString("base64"),
+            plaintextBytes: size,
+            createdAt: new Date(now()).toISOString(),
+        }),
+        "utf8",
+    );
+    const prefix = Buffer.concat([EXPORT_MAGIC, u32(header.length), header]);
+    const headerHash = createHash("sha256").update(prefix).digest();
+    const key = await deriveKey(password, params);
+    const input = await open(src, "r");
+    let output;
+    let written = 0;
+    try {
+        output = await open(out, "wx", 0o600);
+        await output.write(prefix);
+        written += prefix.length;
+        const buf = Buffer.alloc(chunkSize);
+        let pos = 0;
+        let index = 0;
+        for (;;) {
+            const { bytesRead } = await input.read(buf, 0, Math.min(chunkSize, size - pos), pos);
+            pos += bytesRead;
+            const final = pos >= size;
+            const iv = Buffer.concat([nonce, u32(index)]);
+            const c = createCipheriv("aes-256-gcm", key, iv);
+            c.setAAD(chunkAad(headerHash, index, final));
+            const body = Buffer.concat([c.update(buf.subarray(0, bytesRead)), c.final(), c.getAuthTag()]);
+            await output.write(body);
+            written += body.length;
+            index++;
+            if (final) break;
+            if (bytesRead === 0) throw new Error("the file shrank while it was encrypted");
+        }
+        await output.sync();
+    } catch (e) {
+        await output?.close().catch(() => {});
+        output = null;
+        if (!(e?.code === "EEXIST")) await rm(out, { force: true });
+        throw e;
+    } finally {
+        key.fill(0);
+        await input.close();
+        await output?.close();
+    }
+    return { bytes: written, plaintextBytes: size, kdf: { name: "scrypt", N: params.N, r: params.r, p: params.p } };
+}
+
+/**
+ * The header of an export file (no password needed), or why it is not one.
+ *
+ * @param {string} file
+ * @returns {Promise<{header: object, dataOffset: number, headerHash: Buffer, size: number}>}
+ */
+export async function readExportHeader(file) {
+    const fh = await open(file, "r");
+    try {
+        const size = (await fh.stat()).size;
+        const head = Buffer.alloc(12);
+        const { bytesRead } = await fh.read(head, 0, 12, 0);
+        if (bytesRead < 12 || !head.subarray(0, 8).equals(EXPORT_MAGIC)) {
+            throw new ExportCryptError("this is not a password-encrypted export (no ZAEXPORT header)", "NOT_EXPORT");
+        }
+        const len = head.readUInt32BE(8);
+        if (len < 2 || len > MAX_HEADER_BYTES || 12 + len > size) {
+            throw new ExportCryptError("the export's header is damaged", "DAMAGED");
+        }
+        const raw = Buffer.alloc(len);
+        await fh.read(raw, 0, len, 12);
+        let header;
+        try {
+            header = JSON.parse(raw.toString("utf8"));
+        } catch {
+            throw new ExportCryptError("the export's header is damaged", "DAMAGED");
+        }
+        const k = header?.kdf;
+        if (
+            header?.format !== EXPORT_FORMAT ||
+            header.version !== EXPORT_VERSION ||
+            header.cipher !== "aes-256-gcm" ||
+            k?.name !== "scrypt" ||
+            !Number.isInteger(k.N) ||
+            k.N < 2 ||
+            k.N > MAX_N ||
+            (k.N & (k.N - 1)) !== 0 ||
+            !Number.isInteger(k.r) ||
+            k.r < 1 ||
+            k.r > 32 ||
+            !Number.isInteger(k.p) ||
+            k.p < 1 ||
+            k.p > 16 ||
+            !Number.isInteger(header.chunkSize) ||
+            header.chunkSize < 1024 ||
+            header.chunkSize > 64 * 1024 * 1024 ||
+            Buffer.from(String(header.nonce ?? ""), "base64").length !== 8 ||
+            Buffer.from(String(k.salt ?? ""), "base64").length < 16
+        ) {
+            throw new ExportCryptError("this export's format or parameters are not supported", "UNSUPPORTED");
+        }
+        const headerHash = createHash("sha256")
+            .update(Buffer.concat([head, raw]))
+            .digest();
+        return { header, dataOffset: 12 + len, headerHash, size };
+    } finally {
+        await fh.close();
+    }
+}
+
+/**
+ * Decrypt an export file to `out` (0600, never over an existing file). A wrong password or any change to the file is
+ * `ExportCryptError` (`WRONG_PASSWORD_OR_DAMAGED`), and nothing is left at `out`.
+ *
+ * @param {string} file
+ * @param {string} out
+ * @param {string} password
+ * @returns {Promise<{plaintextBytes: number, header: object}>}
+ */
+export async function decryptExportFile(file, out, password) {
+    const { header, dataOffset, headerHash, size } = await readExportHeader(file);
+    if (typeof password !== "string" || !password) throw new ExportCryptError("a password is needed", "PASSWORD");
+    const key = await deriveKey(password, header.kdf);
+    const nonce = Buffer.from(header.nonce, "base64");
+    const step = header.chunkSize + TAG_BYTES;
+    const input = await open(file, "r");
+    let output;
+    let total = 0;
+    try {
+        output = await open(out, "wx", 0o600);
+        const buf = Buffer.alloc(step);
+        let pos = dataOffset;
+        let index = 0;
+        for (;;) {
+            const want = Math.min(step, size - pos);
+            if (want < TAG_BYTES) throw new ExportCryptError("the export is cut short", "WRONG_PASSWORD_OR_DAMAGED");
+            const { bytesRead } = await input.read(buf, 0, want, pos);
+            pos += bytesRead;
+            const final = pos >= size;
+            const d = createDecipheriv("aes-256-gcm", key, Buffer.concat([nonce, u32(index)]));
+            d.setAAD(chunkAad(headerHash, index, final));
+            d.setAuthTag(buf.subarray(bytesRead - TAG_BYTES, bytesRead));
+            let plain;
+            try {
+                plain = Buffer.concat([d.update(buf.subarray(0, bytesRead - TAG_BYTES)), d.final()]);
+            } catch {
+                throw new ExportCryptError(
+                    "the password is wrong, or the file was changed or damaged",
+                    "WRONG_PASSWORD_OR_DAMAGED",
+                );
+            }
+            await output.write(plain);
+            total += plain.length;
+            index++;
+            if (final) break;
+        }
+        if (Number.isInteger(header.plaintextBytes) && header.plaintextBytes !== total) {
+            throw new ExportCryptError("the export's size does not match its header", "WRONG_PASSWORD_OR_DAMAGED");
+        }
+    } catch (e) {
+        await output?.close().catch(() => {});
+        output = null;
+        if (e?.code !== "EEXIST") await rm(out, { force: true });
+        throw e;
+    } finally {
+        key.fill(0);
+        await input.close();
+        await output?.close();
+    }
+    return { plaintextBytes: total, header };
+}

package/src/core/fleet-controller.js

@@ -0,0 +1,340 @@
+/**
+ * The fleet controller (`zalo-agent fleet serve`): the account-lifecycle admin API for a whole host.
+ *
+ * A stopped account has no process and a new account has no server, so a per-account MCP server cannot host this.
+ * The controller is one process per host. It holds **no account lock and no Zalo socket** (AGENTS.md section 13): it
+ * starts and stops daemons (./fleet-supervisor.js: systemd units or spawned processes), relays to a running daemon's
+ * loopback channel, and runs the CLI for a logout or a removal, so every guard those have still applies.
+ *
+ * Routes, under `/zalo/admin` and behind the admin credential (./admin-api.js; an agent's token is refused):
+ *
+ *     GET    /accounts                              every account: state, presence, user, port, pid
+ *     POST   /accounts/<ownId>/start|stop|restart   drive its unit or process
+ *     POST   /accounts/<ownId>/presence/wake|park   relayed to the daemon's channel (on-demand presence)
+ *     POST   /accounts/<ownId>/presence/resume      relayed: take the account back after a yield (the user closed the
+ *                                                   other session of this login; the admin's explicit confirmation)
+ *     POST   /accounts/<ownId>/logout               guarded: 409 {confirmToken} first, then X-Confirm: <token>
+ *     DELETE /accounts/<ownId>                      guarded the same way: stop, `account remove` (crypto-shred)
+ *     GET    /events                                SSE: `account_state` and `session_expiring` for every account
+ *     ...    /accounts/qr[...]                      the QR add flow (./fleet-qr.js)
+ *     ...    /policy/..., /presence/always-on       the host-level policy (users, tenants, accounts)
+ *
+ * `account_state` comes from polling each daemon's channel every `pollMs` (5 s), plus `stopped` for an account with
+ * no process; each change goes to the SSE clients and the admin webhook once. The same poll reads when each saved
+ * login ends (`session` in the account list) and sends `session_expiring` once per threshold (./session-notice.js).
+ */
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { ACCOUNT_STATES, accountStateOfHealth } from "./account-state.js";
+import { sessionExpiringEvent } from "./session-notice.js";
+
+/** How long a guard's confirm token lives. */
+export const CONFIRM_TTL_MS = 2 * 60_000;
+
+/** What each guarded action ends, in the words the CLI's guard uses. */
+export const GUARDED_EFFECTS = Object.freeze({
+    logout:
+        "Ends this machine's Zalo session for the account (its saved login is deleted; chat history stays). " +
+        "It does not sign the device out on the phone: the phone's device list is what revokes it.",
+    remove:
+        "Stops the account's daemon, logs it out and removes it from this machine for good: its credentials, its " +
+        "local database and media, its keys (crypto-shred), its port and its env file. Zalo itself is not changed.",
+});
+
+const ACCOUNT_ID = /^[1-9][0-9]{0,30}$/;
+
+/**
+ * @param {object} args
+ * @param {{kind: string, start: Function, stop: Function, restart: Function, status: Function}} args.driver
+ * @param {() => Array<{ownId: string}>} args.listAccounts
+ * @param {(ownId: string) => Promise<{running: boolean, pid?: number|null, health: object|null, kicked?: boolean}>} args.probe
+ * @param {(ownId: string, path: string, params: object) => Promise<object|null>} args.relay - the daemon channel
+ * @param {(args: string[]) => Promise<{code: number, stdout: string, stderr: string}>} args.runCli
+ * @param {(ownId: string) => {port?: number|null, userId?: string|null, presence?: string|null}} [args.describe]
+ * @param {(ownId: string) => Promise<void>|void} [args.forget] - drop a removed account from the port table, its env
+ *   file and its user
+ * @param {{handle: (req: object, res: object, ctx: object) => boolean|Promise<boolean>}|null} [args.qr] - WP8
+ * @param {(ownId: string) => ({expiresAt: string, daysLeft: number, expired: boolean}|null)} [args.session] - when the
+ *   account's saved login ends, read from its saved cookie jar (a running daemon's own reading wins)
+ * @param {{due: (ownId: string, expiry: object|null) => boolean}|null} [args.sessionNotices] - which thresholds were
+ *   sent (./session-notice.js createSessionNotices); null sends no `session_expiring`
+ * @param {(event: object) => void} [args.webhook] - the admin webhook
+ * @param {(line: string) => void} [args.log]
+ * @param {() => number} [args.now]
+ * @param {number} [args.pollMs]
+ * @returns {object}
+ */
+export function createFleetController({
+    driver,
+    listAccounts,
+    probe,
+    relay,
+    runCli,
+    describe = () => ({}),
+    forget = () => {},
+    qr = null,
+    session = () => null,
+    sessionNotices = null,
+    webhook = () => {},
+    log = () => {},
+    now = Date.now,
+    pollMs = 5000,
+}) {
+    const states = new Map(); // ownId -> {state, at, pid}
+    const sessions = new Map(); // ownId -> {expiresAt, daysLeft, expired}
+    const clients = new Set();
+    const confirms = new Map(); // token -> {action, ownId, expiresAt}
+    let timer = null;
+    let polling = null;
+
+    const send = (res, code, body, headers = {}) => {
+        res.status(code)
+            .set({ "Cache-Control": "no-store", ...headers })
+            .json(body);
+    };
+
+    function publish(event) {
+        const line = `event: ${event.event}\ndata: ${JSON.stringify(event)}\n\n`;
+        for (const c of clients) {
+            try {
+                c.write(line);
+            } catch {
+                clients.delete(c);
+            }
+        }
+        try {
+            webhook(event);
+        } catch (e) {
+            log(`[fleet] the admin webhook failed: ${e.message}`);
+        }
+    }
+
+    function noteState(ownId, state, detail = {}) {
+        if (!ACCOUNT_STATES.includes(state)) return;
+        const prev = states.get(ownId);
+        if (prev?.state === state) return;
+        const at = now();
+        states.set(ownId, { state, at, pid: detail.pid ?? prev?.pid ?? null });
+        publish({
+            event: "account_state",
+            accountId: ownId,
+            state,
+            previous: prev?.state ?? null,
+            at: new Date(at).toISOString(),
+            detail: { source: "controller", ...detail },
+        });
+    }
+
+    /** Keep an account's session end for the list, and publish `session_expiring` when a threshold is crossed. */
+    function noteSession(ownId, expiry) {
+        if (expiry?.expiresAt) sessions.set(ownId, expiry);
+        else sessions.delete(ownId);
+        if (expiry?.expiresAt && sessionNotices?.due(ownId, expiry))
+            publish(sessionExpiringEvent(ownId, expiry, now()));
+    }
+
+    /** Ask every account where it stands; each change is published once. */
+    async function poll() {
+        if (polling) return polling;
+        polling = (async () => {
+            for (const { ownId } of listAccounts()) {
+                try {
+                    const p = await probe(ownId);
+                    const state = p.running ? accountStateOfHealth(p.health) : p.kicked ? "kicked" : "stopped";
+                    noteState(ownId, state, {
+                        pid: p.pid ?? null,
+                        ...(p.health?.presence ? { presence: p.health.presence.mode } : {}),
+                    });
+                    noteSession(ownId, p.health?.session ?? session(ownId));
+                } catch (e) {
+                    log(`[fleet] ${ownId}: ${e.message}`);
+                }
+            }
+        })().finally(() => {
+            polling = null;
+        });
+        return polling;
+    }
+
+    /** A guarded action: the first call names what it does and hands a single-use token; the second runs it. */
+    function guard(req, res, action, ownId) {
+        const given = String(req.headers?.["x-confirm"] ?? "");
+        for (const [t, c] of confirms) if (c.expiresAt <= now()) confirms.delete(t);
+        if (!given) {
+            const token = randomBytes(18).toString("base64url");
+            const expiresAt = now() + CONFIRM_TTL_MS;
+            confirms.set(token, { action, ownId, expiresAt });
+            send(res, 409, {
+                confirmationRequired: true,
+                action,
+                accountId: ownId,
+                effect: GUARDED_EFFECTS[action],
+                confirmToken: token,
+                expiresAt: new Date(expiresAt).toISOString(),
+            });
+            return false;
+        }
+        let match = null;
+        for (const [t, c] of confirms) {
+            const a = Buffer.from(t);
+            const b = Buffer.from(given);
+            if (a.length === b.length && timingSafeEqual(a, b)) match = [t, c];
+        }
+        if (!match || match[1].action !== action || match[1].ownId !== ownId || match[1].expiresAt <= now()) {
+            send(res, 409, { error: "the confirm token is not valid for this action (expired, used or another one)" });
+            return false;
+        }
+        confirms.delete(match[0]);
+        return true;
+    }
+
+    const known = (ownId) => listAccounts().some((a) => a.ownId === ownId);
+
+    async function accountsView() {
+        const out = [];
+        for (const { ownId } of listAccounts()) {
+            const s = states.get(ownId);
+            const sess = sessions.get(ownId);
+            out.push({
+                accountId: ownId,
+                state: s?.state ?? null,
+                since: s ? new Date(s.at).toISOString() : null,
+                pid: s?.pid ?? null,
+                session: sess ? { expiresAt: sess.expiresAt, daysLeft: sess.daysLeft, expired: sess.expired } : null,
+                ...describe(ownId),
+            });
+        }
+        return out;
+    }
+
+    /**
+     * Serve a route under `/zalo/admin` (already authorized). Returns false for a path that is not the controller's.
+     *
+     * @param {object} req
+     * @param {object} res
+     * @param {{who: string, ip: string, path: string}} ctx
+     * @returns {Promise<boolean>}
+     */
+    async function handle(req, res, ctx) {
+        const path = ctx.path;
+        if (qr && (path === "/accounts/qr" || path.startsWith("/accounts/qr/"))) return qr.handle(req, res, ctx);
+        if (path === "/events") {
+            if (req.method !== "GET") return (send(res, 405, { error: "GET only" }), true);
+            res.writeHead(200, {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-store",
+                Connection: "keep-alive",
+                "X-Accel-Buffering": "no",
+            });
+            res.write(`event: snapshot\ndata: ${JSON.stringify({ accounts: await accountsView() })}\n\n`);
+            clients.add(res);
+            req.on("close", () => clients.delete(res));
+            return true;
+        }
+        if (path === "/accounts") {
+            if (req.method !== "GET") return (send(res, 405, { error: "GET only" }), true);
+            send(res, 200, { supervisor: driver.kind, accounts: await accountsView() });
+            return true;
+        }
+        const m =
+            /^\/accounts\/([^/]+)(?:\/(start|stop|restart|logout|presence\/wake|presence\/park|presence\/resume))?$/.exec(
+                path,
+            );
+        if (!m) return false;
+        const ownId = decodeURIComponent(m[1]);
+        if (!ACCOUNT_ID.test(ownId)) return (send(res, 400, { error: "not an account id" }), true);
+        if (!known(ownId)) return (send(res, 404, { error: `account ${ownId} is not registered on this host` }), true);
+        const action = m[2] ?? null;
+        if (!action) {
+            if (req.method !== "DELETE") return (send(res, 405, { error: "DELETE only" }), true);
+            if (!guard(req, res, "remove", ownId)) return true;
+            log(`[fleet] remove ${ownId} (${ctx.who} ${ctx.ip})`);
+            await driver.stop(ownId);
+            const r = await runCli(["--json", "account", "remove", ownId]);
+            if (r.code !== 0) {
+                send(res, 500, { error: "account remove failed", detail: r.stderr.trim().slice(0, 500) });
+                return true;
+            }
+            await forget(ownId);
+            states.delete(ownId);
+            sessions.delete(ownId);
+            publish({
+                event: "account_state",
+                accountId: ownId,
+                state: "stopped",
+                previous: null,
+                at: new Date(now()).toISOString(),
+                detail: { source: "controller", removed: true },
+            });
+            send(res, 200, { removed: true, accountId: ownId });
+            return true;
+        }
+        if (req.method !== "POST") return (send(res, 405, { error: "POST only" }), true);
+        if (action === "start" || action === "stop" || action === "restart") {
+            const before = states.get(ownId)?.state ?? null;
+            const r = await driver[action](ownId);
+            // A start after a kick takes the account back from the other session: a person's decision, logged.
+            if (action !== "stop" && before === "kicked") log(`[fleet] ${action} ${ownId} after a kick (takeover)`);
+            log(`[fleet] ${action} ${ownId}: ${r.detail} (${ctx.who} ${ctx.ip})`);
+            if (action === "stop" && r.ok) noteState(ownId, "stopped");
+            send(res, r.ok ? 200 : 502, {
+                accountId: ownId,
+                action,
+                ok: r.ok,
+                detail: r.detail,
+                takeover: before === "kicked" && action !== "stop",
+            });
+            return true;
+        }
+        if (action === "presence/wake" || action === "presence/park" || action === "presence/resume") {
+            if (action === "presence/resume") log(`[fleet] presence resume ${ownId} (${ctx.who} ${ctx.ip})`);
+            const r = await relay(ownId, "/presence", { action: action.slice(9) });
+            if (!r) return (send(res, 409, { error: "no daemon runs for this account" }), true);
+            if (!r.ok) return (send(res, 409, { error: r.error, ...(r.code ? { code: r.code } : {}) }), true);
+            send(res, 200, r);
+            return true;
+        }
+        if (action === "logout") {
+            if (!guard(req, res, "logout", ownId)) return true;
+            log(`[fleet] logout ${ownId} (${ctx.who} ${ctx.ip})`);
+            await driver.stop(ownId);
+            const r = await runCli(["--json", "--account", ownId, "logout"]);
+            if (r.code !== 0) {
+                send(res, 500, { error: "logout failed", detail: r.stderr.trim().slice(0, 500) });
+                return true;
+            }
+            noteState(ownId, "login_needed", { reason: "logout" });
+            send(res, 200, { loggedOut: true, accountId: ownId });
+            return true;
+        }
+        return false;
+    }
+
+    return {
+        handle,
+        poll,
+        noteState,
+        publish,
+        /** Start polling every account's state. */
+        start() {
+            if (timer) return;
+            void poll();
+            timer = setInterval(() => void poll(), pollMs);
+            timer.unref?.();
+        },
+        stop() {
+            if (timer) clearInterval(timer);
+            timer = null;
+            for (const c of clients) {
+                try {
+                    c.end();
+                } catch {
+                    /* gone */
+                }
+            }
+            clients.clear();
+        },
+        /** For tests and `/accounts`: the last state seen per account. */
+        states: () => Object.fromEntries([...states].map(([k, v]) => [k, v.state])),
+        clients: () => clients.size,
+    };
+}