From 080c113d69c9bd6986d4940fcc44f6d2025c26fc Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 9 Oct 2026 11:47:36 +0200 Subject: [PATCH 01/54] Let the forge's tools never weaken protection or merge past the checks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit gitea_api took any endpoint with a token minted for the forge's administrator with write:admin: an agent could drop a branch's protection or its required checks, set the merge check's status, write to main or merge its own pull request (novox/hq ADR 0266 §7, the review of 2026-10-09). gitea_api now reads anything but the administration and writes only what an author writes; protection is only strengthened; a merge needs every required status a success and merges only that head; a guarded repository is not deleted; and the token is minted without write:admin, a kept one re-minted at the next start. --- modules/gitea/client.ts | 8 +- modules/gitea/guard.ts | 178 +++++++++++++++++++++++++++++++ modules/gitea/test/guard.test.ts | 165 ++++++++++++++++++++++++++++ modules/gitea/test/token.test.ts | 47 +++++--- modules/gitea/token.ts | 32 ++++-- modules/gitea/tools/index.ts | 77 +++++++++++-- 6 files changed, 476 insertions(+), 31 deletions(-) create mode 100644 modules/gitea/guard.ts create mode 100644 modules/gitea/test/guard.test.ts diff --git a/modules/gitea/client.ts b/modules/gitea/client.ts index 10577d13..368dbc96 100644 --- a/modules/gitea/client.ts +++ b/modules/gitea/client.ts @@ -463,10 +463,14 @@ export class GiteaClient { return res.text(); } - async mergePullRequest(owner: string, repo: string, index: number, method = "merge", deleteBranch = false): Promise { + /** Merge a pull request — never forced past its checks, and, given the head that was checked, only that head: + * the forge refuses the merge when the branch moved since (novox/hq ADR 0266). */ + async mergePullRequest(owner: string, repo: string, index: number, method = "merge", deleteBranch = false, + headCommit?: string): Promise { await this.request(`/repos/${owner}/${repo}/pulls/${index}/merge`, { method: "POST", - body: JSON.stringify({ Do: method, delete_branch_after_merge: deleteBranch }), + body: JSON.stringify({ Do: method, delete_branch_after_merge: deleteBranch, force_merge: false, + ...(headCommit ? { head_commit_id: headCommit } : {}) }), }); } diff --git a/modules/gitea/guard.ts b/modules/gitea/guard.ts new file mode 100644 index 00000000..61721b5d --- /dev/null +++ b/modules/gitea/guard.ts @@ -0,0 +1,178 @@ +// What the forge's tools refuse (novox/hq ADR 0266): whoever may call a tool includes agents, and the token +// the tools hold is minted for the forge's administrator. Through `gitea_api` any endpoint was one call away: +// an agent could drop a branch's protection or its required checks, write to main, set the merge check's +// status, or merge its own pull request — and a module merged into the catalogue is what the next push sends, +// as root, to every node. So: +// +// - `gitea_api` reads anything but the forge's administration, and writes only what an author writes: +// issues, comments, labels, pull requests (opened, edited, reviewed — never merged), branches, and a +// file on a branch that is neither the repository's default branch nor one a protection rule names. +// Everything else — administration, protection, settings, collaborators, teams, hooks, keys, tokens, +// statuses, a merge, a repository deleted or moved — has its own tool or is the operator's, at the +// forge as themselves; +// - `gitea_branch_protection_set` only makes protection stronger; +// - `gitea_merge_pull_request` merges only a head whose every required status succeeded, and only that +// head; +// - `gitea_delete_repo` refuses a repository any protection rule guards. +// +// Pure, so it is tested without a forge; the tools do the asking (tools/index.ts). + +import type { BranchProtection, ProtectionWanted } from "./protection.js"; + +/** A refusal of policy, in the words the caller sees. Never an error of the forge's. */ +export class Refused extends Error { + constructor(message: string) { + super(message); + this.name = "Refused"; + } +} + +/** What `gitea_api` may do with one call, as far as the call alone says. */ +export type ApiJudgement = + | { allowed: true } + | { refused: string } + /** A file written: allowed only on a branch that is not the default branch and that no rule names. */ + | { contents: { owner: string; repo: string; branch?: string; newBranch?: string } }; + +const READS = new Set(["GET", "HEAD"]); + +const seg = "([^/]+)"; +const repoPath = `^/repos/${seg}/${seg}`; + +/** The writes an author makes, by method and path. Anything not here is refused. */ +const AUTHOR_WRITES: ReadonlyArray<{ methods: string[]; path: RegExp }> = [ + { methods: ["POST"], path: new RegExp(`${repoPath}/issues$`) }, + { methods: ["PATCH"], path: new RegExp(`${repoPath}/issues/\\d+$`) }, + { methods: ["POST"], path: new RegExp(`${repoPath}/issues/\\d+/comments$`) }, + { methods: ["PATCH", "DELETE"], path: new RegExp(`${repoPath}/issues/comments/\\d+$`) }, + { methods: ["POST", "PUT", "DELETE"], path: new RegExp(`${repoPath}/issues/\\d+/labels(/\\d+)?$`) }, + { methods: ["POST"], path: new RegExp(`${repoPath}/labels$`) }, + { methods: ["PATCH", "DELETE"], path: new RegExp(`${repoPath}/labels/\\d+$`) }, + { methods: ["POST"], path: new RegExp(`${repoPath}/pulls$`) }, + { methods: ["PATCH"], path: new RegExp(`${repoPath}/pulls/\\d+$`) }, + { methods: ["POST"], path: new RegExp(`${repoPath}/pulls/\\d+/reviews(/\\d+(/comments)?)?$`) }, + { methods: ["POST", "DELETE"], path: new RegExp(`${repoPath}/pulls/\\d+/requested_reviewers$`) }, + { methods: ["POST"], path: new RegExp(`${repoPath}/branches$`) }, + { methods: ["POST"], path: /^\/user\/repos$/ }, + { methods: ["POST"], path: /^\/markdown(\/raw)?$/ }, +]; + +/** A file written through the contents API: one file, or several in one commit. */ +const CONTENTS = new RegExp(`${repoPath}/contents(/.*)?$`); + +/** Reads that are no one's but the administrator's. */ +const ADMIN_READS = [/^\/admin(\/|$)/, /^\/users\/[^/]+\/tokens(\/|$)/]; + +/** + * The path as the forge would route it: relative to /api/v1, its query dropped, refused when it could be read + * as another path — a dot segment, an encoded slash or dot, a backslash, an empty segment. A path the forge and + * this judge could read differently is never judged. + */ +export function routedPath(raw: string): string { + let path = String(raw ?? "").trim(); + if (!path.startsWith("/")) path = "/" + path; + path = path.replace(/^\/api\/v1(?=\/|$)/, "") || "/"; + const q = path.search(/[?#]/); + if (q >= 0) path = path.slice(0, q); + if (/%2e|%2f|%5c|\\/i.test(path)) throw new Refused(`${raw}: an encoded dot, slash or backslash is not taken`); + path = path.replace(/\/+$/, "") || "/"; + const segments = path.split("/").slice(1); + if (path !== "/" && segments.some((s) => s === "" || s === "." || s === "..")) { + throw new Refused(`${raw}: a path with an empty or dot segment is not taken`); + } + return path; +} + +/** What `gitea_api` may do with this call, judged on the call alone (novox/hq ADR 0266). */ +export function judgeApiCall(method: string, rawPath: string, body: unknown): ApiJudgement { + const m = String(method || "GET").toUpperCase(); + let path: string; + try { + path = routedPath(rawPath); + } catch (err) { + return { refused: (err as Error).message }; + } + if (READS.has(m)) { + if (ADMIN_READS.some((r) => r.test(path))) { + return { refused: `${m} ${path} is the forge's administration, which no tool reads (novox/hq ADR 0266)` }; + } + return { allowed: true }; + } + const contents = path.match(CONTENTS); + if (contents && ["POST", "PUT", "DELETE"].includes(m)) { + const b = (body ?? {}) as Record; + const str = (v: unknown) => (typeof v === "string" && v.trim() !== "" ? v.trim() : undefined); + return { contents: { owner: contents[1], repo: contents[2], branch: str(b.branch), newBranch: str(b.new_branch) } }; + } + if (AUTHOR_WRITES.some((w) => w.methods.includes(m) && w.path.test(path))) return { allowed: true }; + return { + refused: `${m} ${path} is not a write gitea_api makes (novox/hq ADR 0266): it writes only what an author ` + + `writes — issues, comments, labels, pull requests (never their merge), branches, and files on a branch ` + + `that is not the default branch and that no protection rule names. The forge's administration, a ` + + `branch's protection, a repository's settings, collaborators, teams, hooks, keys, tokens and statuses ` + + `are the operator's at the forge, or have their own tool (gitea_merge_pull_request, gitea_commit_status, ` + + `gitea_branch_protection_set, which only strengthens). Nothing was sent`, + }; +} + +/** Whether a protection rule's name — a branch, or a glob of them (`*`, `**`) — covers a branch. */ +export function ruleCovers(rule: string, branch: string): boolean { + if (rule === branch) return true; + if (!/[*?[]/.test(rule)) return false; + let re = ""; + for (let i = 0; i < rule.length; i++) { + const c = rule[i]; + if (c === "*" && rule[i + 1] === "*") { + re += ".*"; + i++; + } else if (c === "*") re += "[^/]*"; + else if (c === "?") re += "[^/]"; + else re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&"); + } + return new RegExp(`^${re}$`).test(branch); +} + +/** Refuses a file written to the default branch or to a branch a protection rule names. */ +export function judgeContentsWrite(target: string, defaultBranch: string, rules: BranchProtection[]): string | null { + if (target === defaultBranch) { + return `a file written to ${target}, the repository's default branch, is refused: a change reaches it by a pull ` + + `request that passes its checks (novox/hq ADR 0266). Write it on a branch of its own (new_branch). Nothing was sent`; + } + const guarding = rules.map((r) => String(r.rule_name ?? r.branch_name ?? "")).filter((r) => r && ruleCovers(r, target)); + if (guarding.length) { + return `a file written to ${target} is refused: the protection rule ${guarding.join(", ")} guards it ` + + `(novox/hq ADR 0266). Write it on a branch of its own. Nothing was sent`; + } + return null; +} + +/** Refuses a protection change that weakens the rule a branch has (novox/hq ADR 0266). */ +export function judgeProtectionChange(before: BranchProtection | null, want: ProtectionWanted): string | null { + if (!before) return null; // A new rule protects what nothing protected. + const had = before.enable_status_check ? [...new Set((before.status_check_contexts ?? []).filter(Boolean))] : []; + const wanted = new Set(want.statusChecks.map((c) => c.trim()).filter(Boolean)); + const dropped = had.filter((c) => !wanted.has(c)); + const why: string[] = []; + if (dropped.length) why.push(`it drops the required status ${dropped.join(", ")}`); + if (want.push === true && before.enable_push === false) why.push("it lets a person push to the branch directly"); + if (want.blockAdminOverride === false && before.block_admin_merge_override === true) { + why.push("it lets an administrator merge past a status that has not succeeded"); + } + if (!why.length) return null; + return `the protection of ${before.rule_name ?? before.branch_name} is only made stronger through a tool: ` + + `${why.join("; ")}. Whoever may call a tool includes agents, and a branch's protection is what keeps a ` + + `change from merging without its checks and the operator (novox/hq ADR 0266) — weakening it is the ` + + `operator's, at the forge as themselves. Nothing was changed`; +} + +/** The merge methods the forge takes for a merge that is a merge — never `manually-merged`. */ +export const MERGE_METHODS = new Set(["merge", "rebase", "rebase-merge", "squash", "fast-forward-only"]); + +/** A repository owner's or name's shape: what keeps a name from becoming another path. */ +export function checkName(what: string, value: unknown): string { + const v = String(value ?? "").trim(); + if (!/^[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(v) || v === "." || v === "..") { + throw new Refused(`${JSON.stringify(value)} is not a repository ${what}`); + } + return v; +} diff --git a/modules/gitea/test/guard.test.ts b/modules/gitea/test/guard.test.ts new file mode 100644 index 00000000..31a04804 --- /dev/null +++ b/modules/gitea/test/guard.test.ts @@ -0,0 +1,165 @@ +// What the forge's tools refuse (guard.ts; novox/hq ADR 0266): an agent reaches the forge through these tools +// with a token minted for the forge's administrator, so the tools — not the forge — are what keeps it from +// dropping a branch's protection, writing to main, setting the merge check's status, or merging past the +// checks. Each route a review found is reproduced here against a fake forge, and each is refused with nothing +// sent; the operator-approved merge of a pull request whose checks passed still goes through. + +import { test, after, beforeEach } from "node:test"; +import assert from "node:assert/strict"; +import { createServer, type IncomingMessage, type ServerResponse } from "node:http"; + +import { GiteaClient } from "../dist/client.js"; +import { ConfiguredToken } from "../dist/token.js"; +import { getGiteaTools } from "../dist/tools/index.js"; +import { judgeApiCall, judgeProtectionChange, ruleCovers, routedPath } from "../dist/guard.js"; + +interface Sent { method: string; path: string; body: any } + +const state = { + sent: [] as Sent[], + statuses: [] as { context: string; state: string }[], + rules: [] as any[], +}; +const protectedMain = () => ({ rule_name: "main", enable_push: false, enable_status_check: true, + status_check_contexts: ["mesh/merge-gate", "mesh/repo-check"], block_admin_merge_override: true }); + +beforeEach(() => { + state.sent = []; + state.statuses = [{ context: "mesh/merge-gate", state: "success" }, { context: "mesh/repo-check", state: "success" }]; + state.rules = [protectedMain()]; +}); + +const json = (res: ServerResponse, status: number, body: unknown): void => { + res.writeHead(status, { "Content-Type": "application/json" }); + res.end(body === null ? "" : JSON.stringify(body)); +}; +const read = (req: IncomingMessage): Promise => + new Promise((resolve) => { + let text = ""; + req.on("data", (c) => (text += c)); + req.on("end", () => resolve(text ? JSON.parse(text) : null)); + }); + +const server = createServer(async (req, res) => { + const url = new URL(req.url ?? "/", "http://fake"); + const path = url.pathname.replace(/^\/api\/v1/, ""); + const method = req.method ?? "GET"; + const body = await read(req); + if (method !== "GET") state.sent.push({ method, path, body }); + const repo = "/repos/novox/mesh-catalog"; + if (method === "GET" && path === repo) return json(res, 200, { full_name: "novox/mesh-catalog", default_branch: "main" }); + if (method === "GET" && path === `${repo}/branch_protections`) return json(res, 200, state.rules); + if (method === "GET" && path === `${repo}/pulls/7`) { + return json(res, 200, { number: 7, title: "x", state: "open", merged: false, head: { ref: "feat/x", sha: "abc1234" }, + base: { ref: "main" }, html_url: "http://fake/7" }); + } + if (method === "GET" && path === `${repo}/commits/abc1234/status`) { + return json(res, 200, { sha: "abc1234", state: "success", statuses: state.statuses }); + } + if (method === "POST" && path === `${repo}/pulls/7/merge`) return json(res, 200, null); + return json(res, method === "GET" ? 200 : 201, {}); +}); +await new Promise((r) => server.listen(0, "127.0.0.1", () => r())); +after(() => new Promise((r) => server.close(() => r()))); +const { port } = server.address() as { port: number }; +const tools = getGiteaTools(new GiteaClient(`http://127.0.0.1:${port}`, new ConfiguredToken("t"))); +const tool = (name: string) => tools.find((t) => t.name === name)!; +const writes = () => state.sent.map((s) => `${s.method} ${s.path}`); + +test("gitea_api refuses the forge's administration, a branch's protection and the merge check's status, and sends nothing", async () => { + for (const [method, path, body] of [ + ["PATCH", "/admin/users/agent", { admin: true }], + ["DELETE", "/repos/novox/mesh-catalog/branch_protections/main", undefined], + ["PATCH", "/repos/novox/mesh-catalog/branch_protections/main", { enable_status_check: false }], + ["POST", "/repos/novox/mesh-catalog/statuses/abc1234", { context: "mesh/merge-gate", state: "success" }], + ["POST", "/repos/novox/mesh-catalog/pulls/7/merge", { Do: "merge", force_merge: true }], + ["PUT", "/repos/novox/mesh-catalog/collaborators/agent", { permission: "admin" }], + ["POST", "/repos/novox/mesh-catalog/hooks", { type: "gitea" }], + ["POST", "/repos/novox/mesh-catalog/keys", { key: "ssh-ed25519 AAAA" }], + ["PATCH", "/repos/novox/mesh-catalog", { default_branch: "agent" }], + ["DELETE", "/repos/novox/mesh-catalog", undefined], + ["POST", "/repos/novox/mesh-catalog/transfer", { new_owner: "agent" }], + ["POST", "/users/mesh-admin/tokens", { name: "mine", scopes: ["all"] }], + ["PUT", "/orgs/novox/members/agent", undefined], + ["PATCH", "/repos/novox/mesh-catalog/issues/1/../../branch_protections/main", { enable_push: true }], + ["PATCH", "/repos/novox/mesh-catalog/issues/1/%2e%2e/%2e%2e/branch_protections/main", { enable_push: true }], + ] as const) { + await assert.rejects(tool("gitea_api").run({ path, method, ...(body ? { body } : {}) }), + /not a write gitea_api makes|not taken|administration/, `${method} ${path}`); + } + await assert.rejects(tool("gitea_api").run({ path: "/admin/users" }), /administration/); + assert.deepEqual(writes(), []); +}); + +test("gitea_api refuses a file written to the default branch or one a rule guards, and writes one on a branch of its own", async () => { + const put = (body: Record) => + tool("gitea_api").run({ path: "/repos/novox/mesh-catalog/contents/modules/sudo/module.json", method: "PUT", body }); + await assert.rejects(put({ content: "e30=", sha: "x" }), /default branch/); + await assert.rejects(put({ content: "e30=", sha: "x", branch: "main" }), /default branch/); + state.rules.push({ rule_name: "release/*" }); + await assert.rejects(put({ content: "e30=", sha: "x", branch: "release/1" }), /protection rule release\/\*/); + assert.deepEqual(writes(), []); + await put({ content: "e30=", sha: "x", branch: "main", new_branch: "feat/sudo-docs" }); + assert.deepEqual(writes(), ["PUT /repos/novox/mesh-catalog/contents/modules/sudo/module.json"]); +}); + +test("gitea_api still writes what an author writes", async () => { + await tool("gitea_api").run({ path: "/repos/novox/mesh-catalog/issues/3/comments", method: "POST", body: { body: "hi" } }); + await tool("gitea_api").run({ path: "/repos/novox/mesh-catalog/pulls/7/reviews", method: "POST", body: { event: "COMMENT" } }); + await tool("gitea_api").run({ path: "/repos/novox/mesh-catalog/branch_protections" }); + assert.deepEqual(writes(), ["POST /repos/novox/mesh-catalog/issues/3/comments", "POST /repos/novox/mesh-catalog/pulls/7/reviews"]); +}); + +test("gitea_branch_protection_set only strengthens", async () => { + const set = (args: Record) => + tool("gitea_branch_protection_set").run({ owner: "novox", repo: "mesh-catalog", branch: "main", ...args }); + await assert.rejects(set({ status_checks: "" }), /drops the required status mesh\/merge-gate, mesh\/repo-check/); + await assert.rejects(set({ status_checks: "mesh/merge-gate" }), /drops the required status mesh\/repo-check/); + await assert.rejects(set({ status_checks: "mesh/merge-gate,mesh/repo-check", push: true }), /push to the branch directly/); + await assert.rejects(set({ status_checks: "mesh/merge-gate,mesh/repo-check", block_admin_override: false }), + /merge past a status/); + assert.deepEqual(writes(), []); + await set({ status_checks: "mesh/merge-gate,mesh/repo-check,mesh/delivery" }); + assert.deepEqual(writes(), ["PATCH /repos/novox/mesh-catalog/branch_protections/main"]); +}); + +test("gitea_merge_pull_request merges only a head whose required statuses all succeeded, and only that head", async () => { + const merge = () => tool("gitea_merge_pull_request").run({ owner: "novox", repo: "mesh-catalog", number: 7 }); + state.statuses = [{ context: "mesh/merge-gate", state: "success" }, { context: "mesh/repo-check", state: "failure" }]; + await assert.rejects(merge(), /not merged: .*mesh\/repo-check \(failure\)/); + state.statuses = [{ context: "mesh/merge-gate", state: "success" }]; + await assert.rejects(merge(), /mesh\/repo-check \(missing\)/); + await assert.rejects(tool("gitea_merge_pull_request").run({ owner: "novox", repo: "mesh-catalog", number: 7, + method: "manually-merged" }), /not a merge method/); + assert.deepEqual(writes(), []); + // The operator said yes and the checks passed: the flow that stays. + state.statuses = [{ context: "mesh/merge-gate", state: "success" }, { context: "mesh/repo-check", state: "success" }]; + await merge(); + const sent = state.sent.find((s) => s.path.endsWith("/pulls/7/merge"))!; + assert.equal(sent.body.force_merge, false); + assert.equal(sent.body.head_commit_id, "abc1234"); +}); + +test("gitea_delete_repo refuses a repository a protection rule guards", async () => { + await assert.rejects(tool("gitea_delete_repo").run({ owner: "novox", name: "mesh-catalog", confirm: true }), + /guarded by the protection rule main/); + assert.deepEqual(writes(), []); +}); + +test("a repository owner or name is never another path", async () => { + await assert.rejects(tool("gitea_update_pull_request").run({ owner: "novox", repo: "mesh-catalog/branch_protections/main?", + number: 1, title: "x" }), /not a repository name/); + await assert.rejects(tool("gitea_get_issue").run({ owner: "..", repo: "admin", number: 1 }), /not a repository owner/); + assert.deepEqual(writes(), []); +}); + +test("the judges, without a forge", () => { + assert.equal(routedPath("/api/v1/repos/a/b/issues?x=1"), "/repos/a/b/issues"); + assert.throws(() => routedPath("/repos/a/b/../c"), /dot segment/); + assert.ok("allowed" in judgeApiCall("GET", "/repos/a/b/branch_protections", undefined)); + assert.ok("refused" in judgeApiCall("POST", "/repos/a/b/branch_protections", {})); + assert.ok("contents" in judgeApiCall("POST", "/repos/a/b/contents", { new_branch: "x" })); + assert.ok(ruleCovers("release/**", "release/a/b") && ruleCovers("feat/*", "feat/a") && !ruleCovers("feat/*", "feat/a/b")); + assert.equal(judgeProtectionChange(null, { statusChecks: [] }), null); + assert.equal(judgeProtectionChange(protectedMain(), { statusChecks: ["mesh/repo-check", "mesh/merge-gate"] }), null); +}); diff --git a/modules/gitea/test/token.test.ts b/modules/gitea/test/token.test.ts index c6f3b4a7..48201041 100644 --- a/modules/gitea/test/token.test.ts +++ b/modules/gitea/test/token.test.ts @@ -17,7 +17,7 @@ import { join } from "node:path"; import { collectTools } from "@novox/mesh-sdk/tools"; import { AdminRefused, MintedToken, TOKEN_SCOPES } from "../dist/token.js"; import { GiteaClient } from "../dist/client.js"; -import "../dist/tools/index.js"; +import { getGiteaTools } from "../dist/tools/index.js"; const ADMIN = "mesh-admin"; const PASSWORD = "the-vault-minted-this"; @@ -230,10 +230,12 @@ test("first start: mints with the admin account, keeps the token at 0600, asks f assert.equal(repos[0]?.full_name, "novox/hq"); assert.equal(forge.mints, 1); - assert.deepEqual(forge.lastScopes, ["write:repository", "write:issue", "read:user", "write:admin"]); + // Never write:admin (novox/hq ADR 0266): the forge's administration is the operator's, not a tool's. + assert.deepEqual(forge.lastScopes, ["write:repository", "write:issue", "read:user"]); assert.deepEqual(forge.lastScopes, [...TOKEN_SCOPES]); const token = forge.tokens.get("mesh-tools")!; assert.equal(await readFile(file, "utf8"), token + "\n"); + assert.equal(await readFile(file + ".scopes", "utf8"), "read:user,write:issue,write:repository\n"); assert.equal((await stat(file)).mode & 0o777, 0o600); // Said that it minted, and where it keeps it — never what it is. assert.ok(logs.some((l) => l.startsWith("minted a token")), logs.join("\n")); @@ -268,32 +270,45 @@ test("the forge rejects the kept token (its data was restored): minted afresh, o assert.ok(logs.some((l) => l.startsWith("the forge rejected the kept token")), logs.join("\n")); }); -test("a kept token from before write:admin: the forge refuses the admin route for the scope, the token is re-minted with the whole list, and the call goes through", async () => { +test("a token kept with write:admin by an earlier build is minted again without it at the next start, and the forge drops the old one", async () => { + const { env, file, logs } = await delivered(forge); + await minted(env, logs).listRepos(); + const old = forge.tokens.get("mesh-tools")!; + forge.scopesOf.set(old, ["write:repository", "write:issue", "read:user", "write:admin"]); + await rm(file + ".scopes"); // an earlier build kept no scopes beside it + const before = forge.mints; + + const again: string[] = []; + await minted(env, again).listRepos(); + + assert.equal(forge.mints, before + 1); + assert.deepEqual(forge.lastScopes, [...TOKEN_SCOPES]); + assert.ok(!forge.lastScopes!.includes("write:admin")); + assert.notEqual(forge.tokens.get("mesh-tools"), old); + assert.ok(![...forge.tokens.values()].includes(old), "the old token still stands on the forge"); + assert.ok(again.some((l) => l.includes("minted with other scopes")), again.join("\n")); + // An admin route through the escape hatch is refused before it is sent. + const tool = getGiteaTools(minted(env, again)).find((t) => t.name === "gitea_api")!; + await assert.rejects(tool.run({ path: "/admin/users/mesh_novox_builder", method: "PATCH", body: { admin: true } }), + /not a write gitea_api makes/); +}); + +test("a kept token lacking a scope the tools need: the forge refuses the call for the scope, the token is re-minted with the whole list, and the call goes through", async () => { const { env, file, logs } = await delivered(forge); const client = minted(env, logs); await client.listRepos(); const before = forge.mints; const old = forge.tokens.get("mesh-tools")!; - forge.scopesOf.set(old, ["write:repository", "write:issue", "read:user"]); // minted by the previous build + forge.scopesOf.set(old, ["write:repository", "write:issue"]); // minted before read:user was added - const user = await client.api<{ login: string; is_admin: boolean }>("/admin/users/mesh_novox_builder", { - method: "PATCH", - body: JSON.stringify({ admin: true }), - }); + const repos = await client.api("/user/repos"); - assert.equal(user.is_admin, true); + assert.equal(repos.length, 1); assert.equal(forge.mints, before + 1); assert.deepEqual(forge.lastScopes, [...TOKEN_SCOPES]); assert.notEqual(forge.tokens.get("mesh-tools"), old); assert.equal(await readFile(file, "utf8"), forge.tokens.get("mesh-tools") + "\n"); assert.ok(logs.some((l) => l.startsWith("the forge rejected the kept token")), logs.join("\n")); - // A 403 that is not about scopes is the forge's answer, not a reason to mint. - const again = forge.mints; - await assert.rejects( - client.api("/admin/users/untouchable", { method: "PATCH", body: JSON.stringify({ admin: true }) }), - /403 .*untouchable/, - ); - assert.equal(forge.mints, again); }); test("the kept file is gone but the forge still holds a token by that name: replaced, not refused", async () => { diff --git a/modules/gitea/token.ts b/modules/gitea/token.ts index fb1e53a9..3aac30b1 100644 --- a/modules/gitea/token.ts +++ b/modules/gitea/token.ts @@ -34,15 +34,18 @@ export const TOKEN_NAME = "mesh-tools"; * It sits under the `user` category despite listing repositories, not `repository` * — confirmed against the running forge (1.27.3), which answered * `required=[read:user]` to a token carrying only the other two. - * write:admin — /admin/users: the forge's own users are the mesh's to settle, such as making - * the builder's login a site admin so every repository the mesh may build is - * clonable (novox/hq 229). Nothing under /orgs or write:user. + * + * **Not write:admin** (novox/hq ADR 0266). It was here so a person could settle the forge's users through + * `gitea_api` (novox/hq 229); whoever may call a tool includes agents, and the forge's administration is the + * operator's. The provisioner settles users with the admin account's own login (GiteaAdmin), never this token. + * A token kept with a different list is minted again with this one at the next start (the scopes are kept + * beside it), and the forge drops the old one by name — so the scope a kept token had does not outlive this. * * A token kept from before a scope was added lacks it: the forge answers such a call with * `403 token does not have at least one of required scope(s)`, and the client treats that like a * 401 — the source re-mints by name, with the whole list, and the call is retried once. */ -export const TOKEN_SCOPES: readonly string[] = ["write:repository", "write:issue", "read:user", "write:admin"]; +export const TOKEN_SCOPES: readonly string[] = ["write:repository", "write:issue", "read:user"]; /** Where a client's token comes from, and what to do when the forge says it is wrong. */ export interface TokenSource { @@ -153,11 +156,12 @@ export class MintedToken implements TokenSource { if (!this.readFile) { this.readFile = true; const kept = this.read(); - if (kept !== null) { + if (kept !== null && this.keptScopes() === this.scopesLine()) { this.held = kept; this.log(`reusing the token kept at ${this.opts.file}`); return kept; } + if (kept !== null) return this.mint("the kept token was minted with other scopes than the tools take now — minting one with them"); } return this.mint("no token kept — minting one"); } @@ -202,13 +206,29 @@ export class MintedToken implements TokenSource { } } - /** Write the token at 0600, whole or not at all: a temp file beside it, then a rename. */ + /** The scopes as kept beside the token: sorted, one line. */ + private scopesLine(): string { + return [...this.scopes].sort().join(","); + } + + /** The scopes the kept token was minted with, "" when not kept (a token kept before they were). */ + private keptScopes(): string { + try { + return readFileSync(`${this.opts.file}.scopes`, "utf8").trim(); + } catch { + return ""; + } + } + + /** Write the token at 0600, whole or not at all: a temp file beside it, then a rename. Its scopes beside it. */ private keep(token: string): void { mkdirSync(dirname(this.opts.file), { recursive: true, mode: 0o700 }); const tmp = `${this.opts.file}.tmp`; writeFileSync(tmp, token + "\n", { mode: 0o600 }); chmodSync(tmp, 0o600); renameSync(tmp, this.opts.file); + writeFileSync(`${this.opts.file}.scopes.tmp`, this.scopesLine() + "\n", { mode: 0o600 }); + renameSync(`${this.opts.file}.scopes.tmp`, `${this.opts.file}.scopes`); } private async doMint(): Promise { diff --git a/modules/gitea/tools/index.ts b/modules/gitea/tools/index.ts index 33b70d41..c2bf056a 100644 --- a/modules/gitea/tools/index.ts +++ b/modules/gitea/tools/index.ts @@ -13,6 +13,9 @@ import { emit } from "@novox/mesh-sdk/events"; import { GiteaClient, type BranchProtection } from "../client.js"; import { appendNote, deliveryStatus, run, viewBody, viewComment } from "../delivery.js"; import { containedFrom, isCommit, mergeableUnder, newestByContext } from "../checks.js"; +import { + MERGE_METHODS, Refused, checkName, judgeApiCall, judgeContentsWrite, judgeProtectionChange, +} from "../guard.js"; /** The forge's container, where its repositories and git are: the note is written there (novox/hq ADR 0239). */ const forgeContainer = process.env.MESH_GITEA_CONTAINER || "gitea"; @@ -37,7 +40,26 @@ function parseLabels(raw: unknown): string[] { .filter(Boolean); } +/** Every tool's repository owner and name checked before it runs: a name is never another path (guard.ts). */ +function namesChecked(tools: ToolDefinition[]): ToolDefinition[] { + return tools.map((t) => ({ + ...t, + run: async (args: Record) => { + if (args.owner !== undefined) checkName("owner", args.owner); + if (args.repo !== undefined) checkName("name", args.repo); + if ((t.name === "gitea_create_repo" || t.name === "gitea_delete_repo") && args.name !== undefined) { + checkName("name", args.name); + } + return t.run(args); + }, + })); +} + export function getGiteaTools(gitea: GiteaClient): ToolDefinition[] { + return namesChecked(allGiteaTools(gitea)); +} + +function allGiteaTools(gitea: GiteaClient): ToolDefinition[] { return [ // ---- Repositories ---- { @@ -80,6 +102,14 @@ export function getGiteaTools(gitea: GiteaClient): ToolDefinition[] { }, run: async (args) => { if (!args.confirm) return { deleted: false, reason: "confirm must be true to delete a repository" }; + // A repository a protection rule guards is the mesh's: deleted and made again, it would be one without + // its protection, under the name the mesh builds from (novox/hq ADR 0266). + const guarded = await gitea.branchProtections(String(args.owner), String(args.name)); + if (guarded.length) { + throw new Refused(`${String(args.owner)}/${String(args.name)} is guarded by the protection rule ` + + `${guarded.map((r) => r.rule_name ?? r.branch_name).join(", ")}: deleting it is the operator's, at the forge ` + + `as themselves, never a tool's (novox/hq ADR 0266). Nothing was deleted`); + } await gitea.deleteRepo(String(args.owner), String(args.name)); return { deleted: true, repo: `${String(args.owner)}/${String(args.name)}` }; }, @@ -230,7 +260,9 @@ export function getGiteaTools(gitea: GiteaClient): ToolDefinition[] { }, { name: "gitea_merge_pull_request", - description: "Merge a pull request, optionally deleting the source branch afterwards.", + description: "Merge a pull request whose head has every status its base branch's protection requires as a success " + + "(mesh/merge-gate, mesh/repo-check), optionally deleting the source branch afterwards. Refused otherwise — no " + + "tool merges past a check — and only the head that was checked is merged.", input: { owner: { type: "string", description: "the repository owner" }, repo: { type: "string", description: "the repository name" }, @@ -243,8 +275,22 @@ export function getGiteaTools(gitea: GiteaClient): ToolDefinition[] { const repo = String(args.repo); const number = Number(args.number); const method = args.method ? String(args.method) : "merge"; + if (!MERGE_METHODS.has(method)) throw new Refused(`${method} is not a merge method: ${[...MERGE_METHODS].join(", ")}`); const deleteBranch = args.delete_branch === undefined ? true : Boolean(args.delete_branch); - await gitea.mergePullRequest(owner, repo, number, method, deleteBranch); + // **Only a head whose required statuses all succeeded** (novox/hq ADR 0266): read here rather than left + // to the forge, whose administrator — the account this tool's token is minted for — may merge past a + // rule that lets it. A rule that cannot be read is no rule passed. + const pull = await gitea.getPullRequest(owner, repo, number); + if (pull.merged) throw new Refused(`${owner}/${repo}#${number} is already merged`); + if (!pull.head_sha || !pull.base) throw new Refused(`${owner}/${repo}#${number} names no head commit or base branch`); + const rule = await gitea.branchProtection(owner, repo, pull.base); + const statuses = newestByContext((await gitea.combinedStatus(owner, repo, pull.head_sha)).statuses); + const verdict = mergeableUnder(pull.base, rule, statuses); + if (verdict.mergeable !== true) { + throw new Refused(`${owner}/${repo}#${number} is not merged: ${verdict.says}. A pull request merges once ` + + `its checks succeed; no tool merges past them (novox/hq ADR 0266)`); + } + await gitea.mergePullRequest(owner, repo, number, method, deleteBranch, pull.head_sha); // The merge commit only exists now; answered so the caller can follow what is built from it. // pull.merged is the events entrypoint's to announce (index.ts), once, within its poll. const merged = await gitea.getPullRequest(owner, repo, number); @@ -395,7 +441,7 @@ export function getGiteaTools(gitea: GiteaClient): ToolDefinition[] { }, { name: "gitea_branch_protection_set", - description: "Make a branch require commit statuses before a pull request merges into it — the mesh's merge check sets `mesh/merge-gate` (the module graph's gate) and `mesh/repo-check` (the repository's own tests). Edits the branch's rule (its required statuses replaced by these, everything else kept unless given) or creates one, which refuses direct pushes unless push=true. Answers the rule before and after.", + description: "Only ever stronger (novox/hq ADR 0266): a change that drops a required status, lets a person push directly or lets an administrator merge past a status is refused — that is the operator's, at the forge. Make a branch require commit statuses before a pull request merges into it — the mesh's merge check sets `mesh/merge-gate` (the module graph's gate) and `mesh/repo-check` (the repository's own tests). Edits the branch's rule (its required statuses replaced by these, everything else kept unless given) or creates one, which refuses direct pushes unless push=true. Answers the rule before and after.", input: { owner: { type: "string", description: "the repository owner" }, repo: { type: "string", description: "the repository name" }, @@ -408,11 +454,14 @@ export function getGiteaTools(gitea: GiteaClient): ToolDefinition[] { const owner = String(args.owner), repo = String(args.repo), branch = String(args.branch ?? "").trim(); if (!branch) throw new Error("name the branch to protect"); const before = await gitea.branchProtection(owner, repo, branch); - const { created, rule } = await gitea.setBranchProtection(owner, repo, branch, { + const want = { statusChecks: String(args.status_checks ?? "").split(","), push: args.push === undefined ? undefined : Boolean(args.push), blockAdminOverride: args.block_admin_override === undefined ? undefined : Boolean(args.block_admin_override), - }); + }; + const weakens = judgeProtectionChange(before, want); + if (weakens) throw new Refused(weakens); + const { created, rule } = await gitea.setBranchProtection(owner, repo, branch, want); return { branch, created, before: before ? summarised(before) : null, after: summarised(rule) }; }, }, @@ -562,14 +611,28 @@ export function getGiteaTools(gitea: GiteaClient): ToolDefinition[] { // ---- Escape hatch ---- { name: "gitea_api", - description: "Make an authenticated Gitea API call for any endpoint without a dedicated tool. Path is relative to /api/v1.", + description: "Make an authenticated Gitea API call for an endpoint without a dedicated tool. Path is relative to /api/v1. " + + "Reads anything but the forge's administration; writes only what an author writes — issues, comments, labels, " + + "pull requests (not their merge: gitea_merge_pull_request), branches, and files on a branch that is not the " + + "default branch and that no protection rule names. Administration, protection, settings, collaborators, teams, " + + "hooks, keys, tokens and statuses are refused (novox/hq ADR 0266).", input: { path: { type: "string", description: "API path relative to /api/v1, e.g. /repos/owner/repo/branches" }, method: { type: "string", description: "GET | POST | PUT | PATCH | DELETE (default GET)" }, body: { type: "object", description: "JSON request body for POST/PUT/PATCH" }, }, run: async (args) => { - const method = args.method ? String(args.method) : "GET"; + const method = (args.method ? String(args.method) : "GET").toUpperCase(); + const judged = judgeApiCall(method, String(args.path ?? ""), args.body); + if ("refused" in judged) throw new Refused(judged.refused); + if ("contents" in judged) { + const { owner, repo, branch, newBranch } = judged.contents; + const found = await gitea.api<{ default_branch?: string }>(`/repos/${checkName("owner", owner)}/${checkName("name", repo)}`); + const defaultBranch = String(found?.default_branch ?? "main"); + const refused = judgeContentsWrite(newBranch ?? branch ?? defaultBranch, defaultBranch, + await gitea.branchProtections(owner, repo)); + if (refused) throw new Refused(refused); + } const result = await gitea.api(String(args.path), { method, ...(args.body ? { body: JSON.stringify(args.body) } : {}), From a7953b969db4c33c215fd4d008e024291b27a5f8 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 9 Oct 2026 12:05:56 +0200 Subject: [PATCH 02/54] betterbird: a module for the mail and calendar client, so its windows and preferences can be seen and declared (hq issue 345) A calendar reminder showed as a transparent, empty window on shanks and no tool could say which window it was or which preferences Betterbird ran with. The module owns one file, the user.js its setting prefs fills, which its tools place whole into the profile Betterbird uses and never over an operator's own; it reads named preferences without credentials or accounts, restarts Betterbird under the user manager so its output reaches the journal, checks what it promises, and shows a reminder on demand from a throw-away profile so a fix can be proved without the operator's calendar. No package: betterbird-bin is the AUR's. --- modules/betterbird/README.md | 116 +++ .../betterbird/cmd/betterbird-tools/args.go | 97 +++ .../cmd/betterbird-tools/betterbird.go | 719 ++++++++++++++++++ .../cmd/betterbird-tools/betterbird_test.go | 256 +++++++ .../cmd/betterbird-tools/copies_test.go | 37 + .../cmd/betterbird-tools/desktop.go | 601 +++++++++++++++ .../cmd/betterbird-tools/desktop_test.go | 219 ++++++ .../betterbird/cmd/betterbird-tools/main.go | 147 ++++ .../cmd/betterbird-tools/manifest_test.go | 110 +++ .../cmd/betterbird-tools/reminder.go | 150 ++++ modules/betterbird/go.mod | 5 + modules/betterbird/go.sum | 2 + modules/betterbird/module.json | 55 ++ 13 files changed, 2514 insertions(+) create mode 100644 modules/betterbird/README.md create mode 100644 modules/betterbird/cmd/betterbird-tools/args.go create mode 100644 modules/betterbird/cmd/betterbird-tools/betterbird.go create mode 100644 modules/betterbird/cmd/betterbird-tools/betterbird_test.go create mode 100644 modules/betterbird/cmd/betterbird-tools/copies_test.go create mode 100644 modules/betterbird/cmd/betterbird-tools/desktop.go create mode 100644 modules/betterbird/cmd/betterbird-tools/desktop_test.go create mode 100644 modules/betterbird/cmd/betterbird-tools/main.go create mode 100644 modules/betterbird/cmd/betterbird-tools/manifest_test.go create mode 100644 modules/betterbird/cmd/betterbird-tools/reminder.go create mode 100644 modules/betterbird/go.mod create mode 100644 modules/betterbird/go.sum create mode 100644 modules/betterbird/module.json diff --git a/modules/betterbird/README.md b/modules/betterbird/README.md new file mode 100644 index 00000000..84de21b3 --- /dev/null +++ b/modules/betterbird/README.md @@ -0,0 +1,116 @@ +# betterbird + +Betterbird, the mail and calendar client of g14 and shanks (a Thunderbird fork, with the operator's +Exchange calendar through the Owl add-on), as a module (novox/hq issue 345, ADR 0208). It requires +`x11-display`, so it is assigned only where a display server is held on the same machine. + +It exists because a symptom had no tools: on a workstation, a calendar reminder appeared as a +transparent window with nothing in it (2026-10-09). Nothing in the mesh could say which window that +was, how the compositor treats it, or which preferences Betterbird ran with. The diagnosis is in hq +issue 345. + +## Owns + +| what | where | +|---|---| +| the module's directory | `~/.config/betterbird/` | +| the module's `user.js`, filled from the setting `prefs` | `~/.config/betterbird/user.js` | + +Nothing else. It holds no seat and adds no start. + +- **No package.** g14 and shanks both run `betterbird-bin` 153.1.0esr-1, installed explicitly from the + AUR: `pacman` counts it as foreign. The node-engine installs packages from the official + repositories only, so the module does not declare it, and **installing and upgrading Betterbird stay + the operator's** (an AUR helper). `betterbird_status` says the version and that it is from the AUR; + `betterbird_check` says when it is missing. +- **No start.** Betterbird is started by the operator from the launcher (on the workstation measured, + it runs in the login session's scope, started by hand, with no autostart entry and no line in i3's + configuration). `betterbird_restart` starts it as the transient user unit `mesh-betterbird`, so its + output then goes to the journal. +- **The profile is Betterbird's** (ADR 0182): `~/.thunderbird/` holds the mail, the address books, + the calendars' caches, the logins and the keys. The module declares none of it. + +## The user.js: how a preference is declared + +Betterbird reads `user.js` in its profile when it starts, and a preference set there wins over the +one it saved in `prefs.js`. The profile's directory has a random name per machine +(`.default-default`), which a manifest cannot name. So: + +1. the node-engine writes `~/.config/betterbird/user.js` from the module's setting `prefs`, one line of + `user_pref("name", value);` statements (default: a comment, no preference); +2. the module's tools copy that file whole into the profile: `betterbird_user_js` with `apply`, or + `betterbird_restart`, which places it before it starts Betterbird again; +3. Betterbird reads it at that start. + +**The profile is found** as the one the running Betterbird holds open; with none running, as the +installation's default in `profiles.ini` (`[Install…] Default`), else the profile marked `Default=1`. +On the workstation measured these differ: `Profile1` is marked `Default=1`, and the installation's +default, the one in use, is the other. + +**A user.js the module did not write is never overwritten.** The module's begins with the line +`// Betterbird's user.js (module betterbird`; any other is the operator's, and `apply` refuses with +what to do. The tools refuse a declared file that holds anything but comments and `user_pref` +statements, or that sets a preference whose name can hold a credential. + +The file is **trusted** (it carries no `"trusted": false`): a preference can weaken how the mail client +checks a server, so the setting is changed only at the controller's terminal, never through a verb +(novox/hq issue 339). + +## Tools + +They are served by the node's runtime as the operator account (ADR 0175). **No answer carries mail, a +calendar entry, an account, an address or a credential.** + +| tool | does | +|---|---| +| `betterbird_status` (r) | whether it runs (pid, since, scope, children), the package and version and that it is from the AUR, where its output goes, the profile and how it was found, the user.js (declared, placed, in effect), the add-ons the operator installed (ids), and the preferences that decide how its windows and notifications look | +| `betterbird_prefs` (r) | named preferences or prefixes (ending in `.` or `*`, at most 200): value and source (user.js, prefs.js or the default). A name that can hold a credential (`password`, `token`, `oauth`, `signon`, …) or that names an account, server, calendar or person (`mail.server.`, `mail.identity.`, `calendar.registry.`, `extensions.owl.`, …) is answered without its value | +| `betterbird_user_js` (r; a with `apply`) | the declared user.js against the profile's; `apply` places it | +| `betterbird_log` (r) | the last lines of the journal of `mesh-betterbird` (or of the reminder test), addresses and credentials masked. A Betterbird the module did not start prints elsewhere, and the answer says where | +| `betterbird_restart` (a) | ends Betterbird (asked to quit, forced after 20 s), places the user.js where allowed, starts it as `mesh-betterbird`. **An unsent message in a composer is lost: ask the operator first** | +| `betterbird_check` (r) | installed; one running; profile found; the user.js on the machine, valid, placed, in effect; its output read | +| `betterbird_reminder_test` (a) | a reminder on demand without the operator's calendar (below) | + +### A reminder on demand + +`betterbird_reminder_test` starts a **second** Betterbird with `--no-remote` in a throw-away profile +under `/run/user//mesh-betterbird-reminder-test/`, as the user unit +`mesh-betterbird-reminder-test` (ended after 10 minutes at most). The profile holds the module's +user.js and one calendar: a local `.ics` file with one event, "Mesh reminder test", whose reminder is +due `after` seconds from the call (default 40). `carry` copies named preferences of the operator's +profile into it (a theme, a colour switch), under the same limits as `betterbird_prefs`. Then: + +- `xorg_windows` with class `Calendar` answers the reminder window: role `AlarmWindow`, type `Dialog`, + its depth (32: a visual with alpha, which the compositor blends), its map state; +- `xorg_screenshot` with that window shows it as the screen shows it. + +`stop` ends it and removes the profile. The running Betterbird, its profile and its calendars are not +touched: `--no-remote` keeps the two apart. + +## The reminder window, as measured (2026-10-09, workstation, i3 and picom with glx) + +| | | +|---|---| +| X class / instance | `eu.betterbird.Betterbird` / `Calendar` | +| role, type | `AlarmWindow`, `_NET_WM_WINDOW_TYPE_DIALOG` (i3 floats it) | +| depth | 32 (ARGB visual), like every Betterbird window there | +| size | 600×300, kept in the profile's `xulstore.json` | + +A window of depth 32 that its program has not drawn is transparent under a compositor, not black: +that is why the symptom looks the way it does. Why Betterbird did not draw it is hq issue 345's +question. + +## What changes when it is assigned + +| | g14 | shanks | +|---|---|---| +| files | `~/.config/betterbird/` and its `user.js` (no preference) | the same | +| the profile | untouched until `betterbird_user_js` with `apply` or `betterbird_restart` | the same; the profile has no user.js today, so `apply` may place one | +| Betterbird | keeps running as started | keeps running as started (since 2026-10-04, its output on the session's pipe nobody reads: `betterbird_check` names it until `betterbird_restart`) | + +## Relies on + +- A display server on the same machine (`x11-display`, ADR 0208 §3). +- **`xorg`** for `xorg_windows` and `xorg_screenshot`, which look at Betterbird's windows. This module + carries no window code of its own. +- `systemd-run` and `journalctl` of the account's user manager. diff --git a/modules/betterbird/cmd/betterbird-tools/args.go b/modules/betterbird/cmd/betterbird-tools/args.go new file mode 100644 index 00000000..9b5dfcf7 --- /dev/null +++ b/modules/betterbird/cmd/betterbird-tools/args.go @@ -0,0 +1,97 @@ +// Reading a tool's arguments: JSON numbers arrive as float64, and a missing argument is its default. +// The same in every desktop module that carries it. +package main + +import ( + "fmt" + "math" + "strings" + "time" +) + +// text is a string argument, trimmed; required says an empty one is refused. +func text(args map[string]any, key string, required bool) (string, error) { + v, present := args[key] + if !present || v == nil { + if required { + return "", fmt.Errorf("%s is required", key) + } + return "", nil + } + s, ok := v.(string) + if !ok { + return "", fmt.Errorf("%s is a string, not %T", key, v) + } + s = strings.TrimSpace(s) + if s == "" && required { + return "", fmt.Errorf("%s is required", key) + } + return s, nil +} + +// whole is a whole-number argument within [least, most], or def when absent. +func whole(args map[string]any, key string, def, least, most int) (int, error) { + v, present := args[key] + if !present || v == nil { + return def, nil + } + f, ok := v.(float64) + if !ok { + if i, isInt := v.(int); isInt { + f = float64(i) + } else { + return 0, fmt.Errorf("%s is a number, not %T", key, v) + } + } + if f != math.Trunc(f) { + return 0, fmt.Errorf("%s is a whole number, not %v", key, f) + } + n := int(f) + if n < least || n > most { + return 0, fmt.Errorf("%s is %d; it is between %d and %d", key, n, least, most) + } + return n, nil +} + +// flag is a boolean argument, or def when absent. +func flag(args map[string]any, key string, def bool) (bool, error) { + v, present := args[key] + if !present || v == nil { + return def, nil + } + b, ok := v.(bool) + if !ok { + return false, fmt.Errorf("%s is true or false, not %T", key, v) + } + return b, nil +} + +// texts is a list-of-strings argument. +func texts(args map[string]any, key string) ([]string, error) { + v, present := args[key] + if !present || v == nil { + return nil, nil + } + list, ok := v.([]any) + if !ok { + if ss, isStrings := v.([]string); isStrings { + return ss, nil + } + return nil, fmt.Errorf("%s is a list of strings, not %T", key, v) + } + out := make([]string, 0, len(list)) + for i, item := range list { + s, ok := item.(string) + if !ok { + return nil, fmt.Errorf("%s[%d] is a string, not %T", key, i, item) + } + out = append(out, s) + } + return out, nil +} + +// seconds is a timeout argument in seconds, defaulted and bounded below the runtime's call limit. +func seconds(args map[string]any, key string, def, most int) (time.Duration, error) { + n, err := whole(args, key, def, 1, most) + return time.Duration(n) * time.Second, err +} diff --git a/modules/betterbird/cmd/betterbird-tools/betterbird.go b/modules/betterbird/cmd/betterbird-tools/betterbird.go new file mode 100644 index 00000000..3349791c --- /dev/null +++ b/modules/betterbird/cmd/betterbird-tools/betterbird.go @@ -0,0 +1,719 @@ +package main + +// Betterbird as the tools see it. Betterbird is the mail client's one process tree: the main process +// (comm betterbird-bin, no -contentproc) owns every window — the mail window, the calendar's reminder +// dialog, the composer — and its children (-contentproc) render add-ons and media. The tools read only: +// - the account's processes, and of the main process where its output goes (fd 1 and 2) and which +// profile it holds open; +// - profiles.ini, to find the profile, and the profile's prefs.js and user.js, of which only the +// preferences asked for are answered and never one that can hold a credential or names an account +// (passwordSecret, accountPrefix); +// - the profile's extensions.json, for the add-ons' ids and whether each is on; +// - the module's declared user.js (~/.config/betterbird/user.js), which the node-engine writes from +// the module's setting `prefs`. +// +// Never read: the mail store, the address books, logins.json, key4.db, cert9.db, cookies, the +// calendar's caches. Nothing of the operator's mail, calendar or accounts is answered. +// +// The one file a tool writes in the profile is user.js, and only the module's own: the declared file, +// copied whole (betterbird_user_js with apply, betterbird_restart). A user.js that is not the module's +// is never overwritten. + +import ( + "bufio" + "bytes" + "encoding/json" + "errors" + "fmt" + "os" + "path/filepath" + "regexp" + "sort" + "strconv" + "strings" + "time" +) + +const ( + mainComm = "betterbird-bin" + startBin = "/usr/bin/betterbird" + packageFor = "betterbird-bin" + appIni = "/opt/betterbird/application.ini" + restartAs = "mesh-betterbird" + testUnit = "mesh-betterbird-reminder-test" + // profilesDir is where Betterbird keeps its profiles: Thunderbird's place, which Betterbird shares. + profilesDir = ".thunderbird" + // declared is the module's user.js, written by the node-engine from the setting prefs. + declared = ".config/betterbird/user.js" + // mark is the first line of the module's user.js: how a user.js is known to be the module's. + mark = "// Betterbird's user.js (module betterbird" +) + +// readLink is how a process's file descriptors are read; tests replace it, so no test makes a link. +var readLink = os.Readlink + +// mainProcs are Betterbird's main processes: comm betterbird-bin without -contentproc. +func (m *Machine) mainProcs() []Proc { + var out []Proc + for _, p := range m.procs(mainComm) { + if !strings.Contains(p.Command, "-contentproc") { + out = append(out, p) + } + } + return out +} + +// Stream is where a process's standard output or error goes. +type Stream struct { + FD int `json:"fd"` + Goes string `json:"goes"` + // Dead is a pipe no process of the account reads: a write there fails. + Dead bool `json:"dead,omitempty"` +} + +// streams says where fd 1 and 2 of a process go. +func (m *Machine) streams(pid int) []Stream { + var out []Stream + for _, fd := range []int{1, 2} { + target, err := readLink(m.path(fmt.Sprintf("/proc/%d/fd/%d", pid, fd))) + s := Stream{FD: fd} + switch { + case err != nil: + s.Goes = "unreadable" + case target == "/dev/null": + s.Goes = "discarded (/dev/null)" + case strings.HasPrefix(target, "socket:"): + s.Goes = "a socket (the journal, when started by the module)" + case strings.HasPrefix(target, "pipe:"): + if r := m.pipeReaders(target, pid); len(r) > 0 { + s.Goes = "a pipe read by " + strings.Join(r, ", ") + } else { + s.Goes, s.Dead = "a pipe nobody reads", true + } + default: + s.Goes = m.tilde(target) + } + out = append(out, s) + } + return out +} + +// pipeReaders are the account's processes holding the pipe open for reading (O_RDONLY in fdinfo). +func (m *Machine) pipeReaders(pipe string, except int) []string { + entries, _ := os.ReadDir(m.path("/proc")) + seen := map[string]bool{} + var out []string + for _, e := range entries { + pid, err := strconv.Atoi(e.Name()) + if err != nil || pid == except { + continue + } + dir := m.path(filepath.Join("/proc", e.Name())) + if m.uidOf(dir) != m.UID { + continue + } + fds, _ := os.ReadDir(filepath.Join(dir, "fd")) + for _, fd := range fds { + if t, err := readLink(filepath.Join(dir, "fd", fd.Name())); err != nil || t != pipe { + continue + } + if readOnly(readTrimmed(filepath.Join(dir, "fdinfo", fd.Name()))) { + name := fmt.Sprintf("%s (pid %d)", readTrimmed(filepath.Join(dir, "comm")), pid) + if !seen[name] { + seen[name] = true + out = append(out, name) + } + } + } + } + sort.Strings(out) + return out +} + +// readOnly reads an fdinfo's flags (octal): the access mode is its low two bits, 0 for reading. +func readOnly(fdinfo string) bool { + for _, l := range strings.Split(fdinfo, "\n") { + if f := strings.Fields(l); len(f) == 2 && f[0] == "flags:" { + n, err := strconv.ParseInt(f[1], 8, 64) + return err == nil && n&3 == 0 + } + } + return false +} + +// iniSections reads an INI file into its sections, in order. +func iniSections(raw []byte) (names []string, sections map[string]map[string]string) { + sections = map[string]map[string]string{} + cur := "" + s := bufio.NewScanner(bytes.NewReader(raw)) + for s.Scan() { + l := strings.TrimSpace(s.Text()) + switch { + case l == "" || strings.HasPrefix(l, ";") || strings.HasPrefix(l, "#"): + case strings.HasPrefix(l, "[") && strings.HasSuffix(l, "]"): + cur = l[1 : len(l)-1] + if _, ok := sections[cur]; !ok { + names = append(names, cur) + sections[cur] = map[string]string{} + } + default: + if i := strings.IndexByte(l, '='); i > 0 && cur != "" { + sections[cur][strings.TrimSpace(l[:i])] = strings.TrimSpace(l[i+1:]) + } + } + } + return names, sections +} + +// Profile is the profile the tools act on, and how it was found. +type Profile struct { + Dir string `json:"dir"` + FoundBy string `json:"found_by"` + path string +} + +// profile finds the profile: the one the running Betterbird holds open, else the installation's +// default in profiles.ini ([Install…] Default), else the profile marked Default=1. +func (m *Machine) profile() (Profile, error) { + base := m.home(profilesDir) + if ps := m.mainProcs(); len(ps) > 0 { + counts := map[string]int{} + fds, _ := os.ReadDir(m.path(fmt.Sprintf("/proc/%d/fd", ps[0].PID))) + for _, fd := range fds { + t, err := readLink(m.path(fmt.Sprintf("/proc/%d/fd/%s", ps[0].PID, fd.Name()))) + if err != nil { + continue + } + rel, err := filepath.Rel(filepath.Join(m.Home, profilesDir), t) + if err != nil || strings.HasPrefix(rel, "..") || !strings.Contains(rel, "/") { + continue + } + counts[strings.SplitN(rel, "/", 2)[0]]++ + } + best, n := "", 0 + for d, c := range counts { + if c > n || (c == n && d < best) { + best, n = d, c + } + } + if best != "" { + return Profile{Dir: m.tilde(filepath.Join(m.Home, profilesDir, best)), path: filepath.Join(base, best), + FoundBy: fmt.Sprintf("held open by the running Betterbird (pid %d, %d files)", ps[0].PID, n)}, nil + } + } + raw, err := readBounded(filepath.Join(base, "profiles.ini")) + if err != nil { + return Profile{}, fmt.Errorf("no profile: Betterbird is not running and ~/%s/profiles.ini is unreadable (%v)", profilesDir, err) + } + names, sections := iniSections(raw) + pick := func(rel string, by string) (Profile, error) { + dir := filepath.Join(base, filepath.FromSlash(rel)) + if filepath.IsAbs(rel) { + dir = m.path(rel) + } + if !strings.HasPrefix(filepath.Clean(dir), filepath.Clean(base)+string(filepath.Separator)) { + return Profile{}, fmt.Errorf("profiles.ini names a profile outside ~/%s: %s", profilesDir, rel) + } + return Profile{Dir: m.tilde(strings.TrimPrefix(dir, m.Root)), path: dir, FoundBy: by}, nil + } + var installs []string + for _, n := range names { + if strings.HasPrefix(n, "Install") && sections[n]["Default"] != "" { + installs = append(installs, n) + } + } + if len(installs) == 1 { + return pick(sections[installs[0]]["Default"], "profiles.ini: the installation's default ["+installs[0]+"]") + } + for _, n := range names { + if strings.HasPrefix(n, "Profile") && sections[n]["Default"] == "1" && sections[n]["Path"] != "" { + return pick(sections[n]["Path"], "profiles.ini: the profile marked Default=1 ["+n+"]") + } + } + return Profile{}, fmt.Errorf("profiles.ini names %d installation defaults and no profile marked default: start Betterbird once, then ask again", len(installs)) +} + +// prefLine is one user_pref(…) or pref(…) line of prefs.js or user.js. +var prefLine = regexp.MustCompile(`^\s*(?:user_)?pref\(\s*"((?:[^"\\]|\\.)*)"\s*,\s*(.*?)\s*\)\s*;\s*$`) + +// readPrefs reads the preferences of a prefs.js or user.js: name to its value, as written. +func readPrefs(raw []byte) map[string]string { + out := map[string]string{} + s := bufio.NewScanner(bytes.NewReader(raw)) + s.Buffer(make([]byte, 64<<10), 4<<20) + for s.Scan() { + if mm := prefLine.FindStringSubmatch(s.Text()); mm != nil { + out[mm[1]] = mm[2] + } + } + return out +} + +// passwordSecret and accountPrefix say which preferences are never answered with their value: one +// whose name can hold a credential, and one that names an account, a server or a person. +var ( + passwordSecret = regexp.MustCompile(`(?i)(password|passwd|secret|token|oauth|auth|cookie|credential|signon|apikey|api_key|privatekey|private_key|\.key$)`) + accountPrefix = []string{"mail.server.", "mail.identity.", "mail.smtpserver.", "mail.smtp.", "mail.account.", + "mail.accountmanager.", "ldap_2.", "extensions.owl.", "calendar.registry.", "mail.root.", "mailnews.", + "services.sync.", "mail.displayname", "mail.default_"} +) + +// withheld says why a preference's value is never answered, or "" when it may be. +func withheld(name string) string { + if passwordSecret.MatchString(name) { + return "its name says it can hold a credential" + } + for _, p := range accountPrefix { + if strings.HasPrefix(name, p) { + return "it names an account, a server, a calendar or a person" + } + } + return "" +} + +// Pref is one preference as the profile holds it. +type Pref struct { + Name string `json:"name"` + // Value is what Betterbird uses: user.js's at the start, else prefs.js's. Absent: the default. + Value string `json:"value,omitempty"` + From string `json:"from,omitempty"` + Withheld string `json:"withheld,omitempty"` +} + +// mostPrefs bounds how many preferences one answer carries. +const mostPrefs = 200 + +// Prefs answers the named preferences (a name, or a prefix ending in . or *) from the profile. +func (m *Machine) Prefs(names []string) (map[string]any, error) { + if len(names) == 0 { + return nil, errors.New("names is required: preferences by name, or a prefix ending in . or *, e.g. calendar.alarms.") + } + p, err := m.profile() + if err != nil { + return nil, err + } + prefsJS, _ := readBounded(filepath.Join(p.path, "prefs.js")) + userJS, _ := readBounded(filepath.Join(p.path, "user.js")) + fromPrefs, fromUser := readPrefs(prefsJS), readPrefs(userJS) + all := map[string]bool{} + for n := range fromPrefs { + all[n] = true + } + for n := range fromUser { + all[n] = true + } + var out []Pref + cut := false + seen := map[string]bool{} + for _, want := range names { + prefix := strings.HasSuffix(want, ".") || strings.HasSuffix(want, "*") + want = strings.TrimSuffix(want, "*") + var matched []string + if prefix { + for n := range all { + if strings.HasPrefix(n, want) { + matched = append(matched, n) + } + } + sort.Strings(matched) + } else { + matched = []string{want} + } + for _, n := range matched { + if seen[n] { + continue + } + seen[n] = true + if len(out) == mostPrefs { + cut = true + break + } + pr := Pref{Name: n} + v, from := fromPrefs[n], "prefs.js" + if u, ok := fromUser[n]; ok { + v, from = u, "user.js (wins at the start)" + } else if _, ok := fromPrefs[n]; !ok { + from = "not set: Betterbird's default" + v = "" + } + pr.From = from + if why := withheld(n); why != "" { + pr.Withheld = why + } else { + pr.Value = v + } + out = append(out, pr) + } + } + answer := map[string]any{"profile": p, "prefs": out} + if cut { + answer["cut"] = fmt.Sprintf("the first %d; ask for a narrower prefix", mostPrefs) + } + return answer, nil +} + +// statement is the one thing a line of the module's user.js may be, beside a comment. +var statement = regexp.MustCompile(`^user_pref\("[A-Za-z0-9_.\-\[\]]+",\s*(true|false|-?[0-9]+|"(?:[^"\\]|\\.)*")\);$`) + +// validUserJS says what is wrong with a user.js the module would place, or nil. It holds comments and +// user_pref(…) statements only — the setting is one line, so several statements may share one — and +// sets no preference whose name could hold a credential. +func validUserJS(text string) error { + if !strings.HasPrefix(text, mark) { + return fmt.Errorf("it does not begin with the module's mark (%q)", mark) + } + for i, line := range strings.Split(text, "\n") { + line = strings.TrimSpace(line) + if line == "" || strings.HasPrefix(line, "//") { + continue + } + for _, st := range splitStatements(line) { + if st == "" || strings.HasPrefix(st, "//") { + continue + } + if !statement.MatchString(st) { + return fmt.Errorf("line %d holds %q, which is not user_pref(\"name\", value);", i+1, st) + } + name := st[len(`user_pref("`):strings.Index(st, `",`)] + if passwordSecret.MatchString(name) { + return fmt.Errorf("line %d sets %s, a preference that can hold a credential: not through the mesh", i+1, name) + } + } + } + return nil +} + +// splitStatements cuts a line after each `);`, outside a string. +func splitStatements(line string) []string { + var out []string + in, esc, start := false, false, 0 + for i := 0; i < len(line); i++ { + c := line[i] + switch { + case esc: + esc = false + case c == '\\' && in: + esc = true + case c == '"': + in = !in + case c == ';' && !in: + out = append(out, strings.TrimSpace(line[start:i+1])) + start = i + 1 + } + } + if rest := strings.TrimSpace(line[start:]); rest != "" { + out = append(out, rest) + } + return out +} + +// UserJS is the module's user.js against the profile's. +type UserJS struct { + Declared string `json:"declared"` + Present bool `json:"declared_present"` + Valid string `json:"declared_problem,omitempty"` + Profile string `json:"profile_user_js"` + Placed string `json:"placed"` + Statements int `json:"statements"` + // Effective says whether the running Betterbird started after the file was placed. + Effective string `json:"effective,omitempty"` + Content string `json:"content,omitempty"` + Applied bool `json:"applied,omitempty"` +} + +// userJS compares the declared user.js with the profile's; apply places the declared one when the +// profile has none or the module's. +func (m *Machine) userJS(apply bool) (UserJS, error) { + a := UserJS{Declared: "~/" + declared} + want, err := readBounded(m.home(declared)) + a.Present = err == nil + p, perr := m.profile() + if perr != nil { + return a, perr + } + target := filepath.Join(p.path, "user.js") + a.Profile = m.tilde(strings.TrimPrefix(target, m.Root)) + if a.Present { + if verr := validUserJS(string(want)); verr != nil { + a.Valid = verr.Error() + } + a.Content = string(want) + for _, line := range strings.Split(string(want), "\n") { + for _, st := range splitStatements(strings.TrimSpace(line)) { + if statement.MatchString(st) { + a.Statements++ + } + } + } + } + have, herr := readBounded(target) + switch { + case herr != nil: + a.Placed = "none: the profile has no user.js" + case a.Present && bytes.Equal(have, want): + a.Placed = "the module's, as declared" + case bytes.HasPrefix(have, []byte(mark)): + a.Placed = "the module's, from an earlier declaration" + default: + a.Placed = "not the module's: a user.js of the operator's, which the module never overwrites" + } + if apply { + switch { + case !a.Present: + return a, fmt.Errorf("the module's user.js is not on this machine (~/%s): the module is not pushed here yet", declared) + case a.Valid != "": + return a, fmt.Errorf("the module's user.js is refused: %s; change the setting prefs", a.Valid) + case herr == nil && !bytes.HasPrefix(have, []byte(mark)): + return a, fmt.Errorf("%s is not the module's: move it aside (its preferences belong in the setting prefs), then apply again", a.Profile) + } + if herr != nil || !bytes.Equal(have, want) { + tmp := target + ".mesh-new" + if err := os.WriteFile(tmp, want, 0o644); err != nil { + return a, err + } + if err := os.Rename(tmp, target); err != nil { + os.Remove(tmp) + return a, err + } + } + a.Applied, a.Placed = true, "the module's, as declared" + } + if ps := m.mainProcs(); len(ps) > 0 { + if st, err := os.Stat(target); err == nil { + if t, err := time.Parse(time.RFC3339, ps[0].Since); err == nil && st.ModTime().After(t) { + a.Effective = "not yet: Betterbird reads user.js when it starts, and it started before the file was placed (betterbird_restart)" + } else if err == nil { + a.Effective = "yes: the running Betterbird started after the file was placed" + } + } + } + return a, nil +} + +// Status is what betterbird_status answers. +type Status struct { + Running []Proc `json:"running"` + Children int `json:"children"` + Installed string `json:"installed,omitempty"` + Foreign bool `json:"from_the_aur,omitempty"` + Version string `json:"version,omitempty"` + Build string `json:"build,omitempty"` + Profile *Profile `json:"profile,omitempty"` + Problem string `json:"profile_problem,omitempty"` + Output []Stream `json:"output,omitempty"` + UserJS *UserJS `json:"user_js,omitempty"` + AddOns []AddOn `json:"add_ons,omitempty"` + // Display are the preferences that decide how its windows and notifications look. + Display []Pref `json:"display_prefs,omitempty"` +} + +// AddOn is one add-on the operator installed: its id, and whether it is on. +type AddOn struct { + ID string `json:"id"` + Active bool `json:"active"` +} + +// displayPrefs are the preferences betterbird_status answers: the reminder dialog, the theme, the +// renderer, and whether notifications go to the desktop's notifier. +var displayPrefs = []string{"calendar.alarms.playsound", "calendar.alarms.show", "calendar.alarms.showmissed", + "calendar.alarms.indicator.show", "alerts.useSystemBackend", "mail.biff.use_system_alert", + "extensions.activeThemeID", "browser.display.use_system_colors", "ui.systemUsesDarkTheme", + "gfx.webrender.software", "gfx.webrender.all", "layers.acceleration.disabled", "widget.gtk.overlay-scrollbars.enabled", + "mozilla.widget.use-argb-visuals"} + +func (m *Machine) foreign(pkg string) bool { + o := m.cmd(0, nil, "pacman", "-Qmq", pkg) + return o.Err == nil && o.Code == 0 && strings.TrimSpace(o.Stdout) == pkg +} + +// Status answers whether Betterbird runs, what is installed, its profile and the module's user.js. +func (m *Machine) Status() (Status, error) { + s := Status{Running: m.mainProcs()} + if s.Running == nil { + s.Running = []Proc{} + } + s.Children = len(m.procs(mainComm)) - len(s.Running) + if v, err := m.installed(packageFor); err == nil && v != "" { + s.Installed, s.Foreign = v, m.foreign(packageFor) + } + if raw, err := readBounded(m.path(appIni)); err == nil { + _, sec := iniSections(raw) + s.Version, s.Build = sec["App"]["Version"], sec["App"]["BuildID"] + } + if len(s.Running) > 0 { + s.Output = m.streams(s.Running[0].PID) + } + p, err := m.profile() + if err != nil { + s.Problem = err.Error() + return s, nil + } + s.Profile = &p + if u, err := m.userJS(false); err == nil { + u.Content = "" + s.UserJS = &u + } + if raw, err := readBounded(filepath.Join(p.path, "extensions.json")); err == nil { + var ext struct { + Addons []struct { + ID string `json:"id"` + Active bool `json:"active"` + Location string `json:"location"` + } `json:"addons"` + } + if json.Unmarshal(raw, &ext) == nil { + for _, a := range ext.Addons { + if a.Location == "app-profile" { + s.AddOns = append(s.AddOns, AddOn{a.ID, a.Active}) + } + } + } + } + if got, err := m.Prefs(displayPrefs); err == nil { + s.Display = got["prefs"].([]Pref) + } + return s, nil +} + +// emailAddress and credentialWord are masked in what Betterbird printed. +var ( + emailAddress = regexp.MustCompile(`[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}`) + credentialWord = regexp.MustCompile(`(?i)((?:password|passwd|token|secret|authorization|cookie)\S*\s*[=:]\s*)\S+`) +) + +func mask(s string) string { + s = emailAddress.ReplaceAllString(s, "") + return credentialWord.ReplaceAllString(s, "${1}") +} + +// mostAnswer bounds a log answer. +const mostAnswer = 128 << 10 + +// Log answers the last n lines Betterbird printed, from the journal of the unit the module starts it +// as; problems keeps the lines that say error, warning, crash or assertion. Addresses and credentials +// are masked. +func (m *Machine) Log(n int, problems bool, unit string) (map[string]any, error) { + if unit == "" { + unit = restartAs + } + if unit != restartAs && unit != testUnit { + return nil, fmt.Errorf("unit is %s or %s", restartAs, testUnit) + } + o := m.cmd(0, m.bus(), "journalctl", "--user", "--unit", unit+".service", "--no-pager", "--output", "short-iso", "-n", strconv.Itoa(n)) + if err := failed(o, "journalctl"); err != nil { + return nil, err + } + var lines []string + size := 0 + keep := regexp.MustCompile(`(?i)(error|warn|crash|assert|fail|exception)`) + for _, l := range strings.Split(strings.TrimRight(o.Stdout, "\n"), "\n") { + if l == "" || (problems && !keep.MatchString(l)) { + continue + } + l = mask(l) + if size+len(l) > mostAnswer { + break + } + size += len(l) + 1 + lines = append(lines, l) + } + if lines == nil { + lines = []string{} + } + a := map[string]any{"unit": unit + ".service", "lines": lines} + if ps := m.mainProcs(); len(ps) > 0 && !strings.HasPrefix(ps[0].StartedIn, restartAs) && unit == restartAs { + a["note"] = fmt.Sprintf("the running Betterbird (pid %d) was not started by the module: it runs in %s, "+ + "and its output goes where status says (output), not to this journal; betterbird_restart starts it as %s", + ps[0].PID, ps[0].StartedIn, restartAs) + } + return a, nil +} + +// RestartAnswer is what betterbird_restart answers. +type RestartAnswer struct { + Ended []int `json:"ended"` + Killed []int `json:"killed,omitempty"` + UserJS string `json:"user_js"` + Running []Proc `json:"running"` + Session Session `json:"session"` + Unit string `json:"unit"` +} + +// Restart ends Betterbird (asked to quit, forced after 20 s), places the module's user.js when it can, +// and starts Betterbird again in the operator's session under the account's service manager, its output +// in the journal. +func (m *Machine) Restart() (RestartAnswer, error) { + s, err := m.session() + if err != nil { + return RestartAnswer{}, err + } + a := RestartAnswer{Session: s, Unit: restartAs + ".service"} + a.Ended, a.Killed = m.stopProcs(20*time.Second, m.mainProcs()) + if u, err := m.userJS(true); err != nil { + a.UserJS = "not placed: " + err.Error() + } else { + a.UserJS = fmt.Sprintf("placed: %d preference(s) from ~/%s", u.Statements, declared) + } + if err := m.detach(s, restartAs, startBin); err != nil { + return a, err + } + m.waitFor(mainComm, 8*time.Second) + a.Running = m.mainProcs() + if a.Running == nil { + a.Running = []Proc{} + } + if len(a.Running) == 0 { + return a, fmt.Errorf("Betterbird was started as %s but no main process appeared within 8 s: betterbird_log says why", a.Unit) + } + return a, nil +} + +// CheckAnswer is what betterbird_check answers. +type CheckAnswer struct { + OK bool `json:"ok"` + Findings []Finding `json:"findings"` +} + +// Check verifies what the module promises: Betterbird installed, one running in the session, its +// profile found, the module's user.js declared, valid, placed and in effect, and its output read. +func (m *Machine) Check() (CheckAnswer, error) { + a := CheckAnswer{Findings: []Finding{}} + add := func(what, do string) { a.Findings = append(a.Findings, Finding{what, do}) } + v, err := m.installed(packageFor) + if err != nil { + return a, err + } + if v == "" { + add("Betterbird ("+packageFor+") is not installed", "install it from the AUR: the node-engine installs packages from the official repositories only, so the module does not") + } + ps := m.mainProcs() + switch { + case len(ps) == 0: + add("Betterbird is not running", "start it from the launcher, or betterbird_restart") + case len(ps) > 1: + add(fmt.Sprintf("%d Betterbird main processes run", len(ps)), "one profile is held by one process: betterbird_restart") + } + u, err := m.userJS(false) + switch { + case err != nil: + add("no profile: "+err.Error(), "start Betterbird once") + case !u.Present: + add("the module's user.js is not on this machine (~/"+declared+")", "the module is not pushed here: the controller's push") + case u.Valid != "": + add("the module's user.js is refused: "+u.Valid, "change the module's setting prefs") + case !strings.HasPrefix(u.Placed, "the module's, as declared"): + add("the profile's user.js is "+u.Placed, "betterbird_user_js with apply, then betterbird_restart") + case strings.HasPrefix(u.Effective, "not yet"): + add("the module's user.js is placed but not in effect: "+u.Effective, "betterbird_restart") + } + if len(ps) > 0 { + for _, s := range m.streams(ps[0].PID) { + if s.Dead { + add(fmt.Sprintf("Betterbird's fd %d is a pipe nobody reads (a session started before its output went to the journal): what it prints is lost", s.FD), + "betterbird_restart, which starts it with its output in the journal") + } + } + } + a.OK = len(a.Findings) == 0 + return a, nil +} diff --git a/modules/betterbird/cmd/betterbird-tools/betterbird_test.go b/modules/betterbird/cmd/betterbird-tools/betterbird_test.go new file mode 100644 index 00000000..c4c785b2 --- /dev/null +++ b/modules/betterbird/cmd/betterbird-tools/betterbird_test.go @@ -0,0 +1,256 @@ +package main + +import ( + "os" + "path/filepath" + "strings" + "testing" + "time" +) + +const profileDir = testHome + "/.thunderbird/60016jsp.default-default" + +// links stands in for the kernel's fd links: path → target. +func links(t *testing.T, m map[string]string) { + t.Helper() + old := readLink + readLink = func(p string) (string, error) { + for k, v := range m { + if strings.HasSuffix(p, k) { + return v, nil + } + } + return "", os.ErrNotExist + } + t.Cleanup(func() { readLink = old }) +} + +// betterbird is a running Betterbird with one child, its profile and its prefs. +func (f *fake) betterbird() { + f.proc(4000, 1000, "betterbird-bin", []string{"betterbird"}, "session-4.scope", "DISPLAY=:1") + f.proc(4001, 1000, "betterbird-bin", []string{"/opt/betterbird/betterbird-bin", "-contentproc", "-isForBrowser"}, "session-4.scope") + f.write("/proc/4000/fd/40", "") + f.write("/proc/4000/fd/41", "") + f.write("/proc/4000/fd/1", "") + f.write(testHome+"/.thunderbird/profiles.ini", "[Profile0]\nName=default-default\nIsRelative=1\nPath=60016jsp.default-default\n\n"+ + "[Profile1]\nName=default\nIsRelative=1\nPath=au2i98w4.default\nDefault=1\n\n[InstallF72D9E66FA3C07ED]\nDefault=60016jsp.default-default\nLocked=1\n") + f.write(profileDir+"/prefs.js", "// Mozilla User Preferences\n"+ + `user_pref("browser.display.use_system_colors", true);`+"\n"+ + `user_pref("extensions.activeThemeID", "thunderbird-compact-dark@mozilla.org");`+"\n"+ + `user_pref("calendar.alarms.showmissed", true);`+"\n"+ + `user_pref("mail.identity.id1.useremail", "someone@example.org");`+"\n"+ + `user_pref("extensions.owl.token", "abc");`+"\n"+ + `user_pref("signon.rememberSignons", true);`+"\n") + f.write(profileDir+"/extensions.json", `{"addons":[{"id":"owl@beonex.com","active":true,"location":"app-profile"},{"id":"x@mozilla.org","active":true,"location":"app-builtin"}]}`) +} + +func (f *fake) declare(prefs string) { + f.write(testHome+"/.config/betterbird/user.js", mark+", novox/hq issue 345). Owned by the mesh.\n//\n"+prefs+"\n") +} + +func TestTheProfileIsTheOneTheRunningBetterbirdHoldsElseTheInstallationsDefault(t *testing.T) { + f := newFake(t) + f.betterbird() + links(t, map[string]string{"/proc/4000/fd/40": profileDir + "/prefs.js", "/proc/4000/fd/41": profileDir + "/places.sqlite"}) + p, err := f.profile() + if err != nil || p.Dir != "~/.thunderbird/60016jsp.default-default" || !strings.Contains(p.FoundBy, "pid 4000, 2 files") { + t.Fatalf("%+v %v", p, err) + } + links(t, map[string]string{}) + p, err = f.profile() + if err != nil || p.Dir != "~/.thunderbird/60016jsp.default-default" || !strings.Contains(p.FoundBy, "InstallF72D9E66FA3C07ED") { + t.Fatalf("the installation's default, not Profile1's Default=1: %+v %v", p, err) + } +} + +func TestPrefsAnswerValuesButNeverACredentialOrAnAccount(t *testing.T) { + f := newFake(t) + f.betterbird() + links(t, nil) + f.write(profileDir+"/user.js", mark+")\n"+`user_pref("browser.display.use_system_colors", false);`+"\n") + got, err := f.Prefs([]string{"browser.display.", "mail.identity.*", "extensions.owl.token", "signon.rememberSignons", "gfx.webrender.software"}) + if err != nil { + t.Fatal(err) + } + ps := got["prefs"].([]Pref) + by := map[string]Pref{} + for _, p := range ps { + by[p.Name] = p + } + if p := by["browser.display.use_system_colors"]; p.Value != "false" || !strings.HasPrefix(p.From, "user.js") { + t.Fatalf("user.js wins: %+v", p) + } + for _, n := range []string{"mail.identity.id1.useremail", "extensions.owl.token", "signon.rememberSignons"} { + if p := by[n]; p.Value != "" || p.Withheld == "" { + t.Errorf("%s: %+v", n, p) + } + } + if p := by["gfx.webrender.software"]; p.Value != "" || !strings.Contains(p.From, "default") { + t.Fatalf("%+v", p) + } + if _, err := f.Prefs(nil); err == nil { + t.Fatal("names are required") + } +} + +func TestTheModulesUserJSIsPlacedOnlyWhereNoOperatorsFileIs(t *testing.T) { + f := newFake(t) + f.betterbird() + links(t, nil) + if _, err := f.userJS(true); err == nil || !strings.Contains(err.Error(), "not pushed") { + t.Fatalf("nothing declared: %v", err) + } + f.declare(`user_pref("calendar.alarms.showmissed", true); user_pref("ui.key.x", "a;b");`) + u, err := f.userJS(true) + if err != nil || !u.Applied || u.Statements != 2 { + t.Fatalf("%+v %v", u, err) + } + placed, _ := os.ReadFile(filepath.Join(f.Root, profileDir, "user.js")) + declared, _ := os.ReadFile(filepath.Join(f.Root, testHome, ".config/betterbird/user.js")) + if string(placed) != string(declared) { + t.Fatal("placed whole, as declared") + } + if !strings.HasPrefix(u.Effective, "yes") { + t.Fatalf("the fake Betterbird started after the file's time: %q", u.Effective) + } + later := time.Unix(1_900_000_000, 0) + os.Chtimes(filepath.Join(f.Root, profileDir, "user.js"), later, later) + if u, _ := f.userJS(false); !strings.HasPrefix(u.Effective, "not yet") { + t.Fatalf("placed after Betterbird started: %q", u.Effective) + } + f.write(profileDir+"/user.js", `user_pref("a.b", 1);`+"\n") + if _, err := f.userJS(true); err == nil || !strings.Contains(err.Error(), "not the module's") { + t.Fatalf("an operator's user.js is never overwritten: %v", err) + } + if b, _ := os.ReadFile(filepath.Join(f.Root, profileDir, "user.js")); string(b) != `user_pref("a.b", 1);`+"\n" { + t.Fatal("and it is left as it was") + } +} + +func TestTheUserJSHoldsOnlyPreferencesAndNoCredential(t *testing.T) { + for text, ok := range map[string]bool{ + mark + ")\n// none\n": true, + mark + ")\n" + `user_pref("a.b", true); user_pref("c", -3); user_pref("d", "x\"y;z");`: true, + mark + ")\n" + `pref("a.b", true);`: false, + mark + ")\n" + `user_pref("a.b", true); Services.foo();`: false, + mark + ")\n" + `user_pref("mail.smtpserver.s1.password", "x");`: false, + `user_pref("a.b", true);`: false, + } { + if err := validUserJS(text); (err == nil) != ok { + t.Errorf("%q: %v", text, err) + } + } +} + +func TestStatusSaysWhatRunsTheProfileTheAddOnsAndTheDisplayPrefs(t *testing.T) { + f := newFake(t) + f.betterbird() + links(t, map[string]string{"/proc/4000/fd/1": "pipe:[36802]"}) + f.write("/opt/betterbird/application.ini", "[App]\nVendor=Betterbird Project\nName=Betterbird\nVersion=153.1.0\nBuildID=20260820183427\n") + f.answer = func(name string, args []string) Output { + if name == "pacman" && args[0] == "-Q" { + return Output{Stdout: "betterbird-bin 153.1.0esr-1\n"} + } + if name == "pacman" && args[0] == "-Qmq" { + return Output{Stdout: "betterbird-bin\n"} + } + return Output{} + } + s, err := f.Status() + if err != nil { + t.Fatal(err) + } + if len(s.Running) != 1 || s.Running[0].PID != 4000 || s.Children != 1 || s.Installed != "153.1.0esr-1" || !s.Foreign || + s.Version != "153.1.0" || s.Profile == nil || len(s.AddOns) != 1 || s.AddOns[0].ID != "owl@beonex.com" { + t.Fatalf("%+v", s) + } + if !s.Output[0].Dead { + t.Fatalf("the session's dead pipe: %+v", s.Output) + } + found := false + for _, p := range s.Display { + if p.Name == "extensions.activeThemeID" && p.Value == `"thunderbird-compact-dark@mozilla.org"` { + found = true + } + } + if !found { + t.Fatalf("%+v", s.Display) + } +} + +func TestCheckNamesWhatIsMissingAndWhatToDo(t *testing.T) { + f := newFake(t) + f.betterbird() + links(t, map[string]string{"/proc/4000/fd/1": "pipe:[1]", "/proc/4000/fd/2": "/dev/null"}) + f.answer = func(name string, args []string) Output { return Output{Stdout: "betterbird-bin 153.1.0esr-1\n"} } + a, err := f.Check() + if err != nil || a.OK { + t.Fatalf("%+v %v", a, err) + } + all := "" + for _, x := range a.Findings { + all += x.What + " | " + x.Do + "\n" + } + if !strings.Contains(all, "not on this machine") || !strings.Contains(all, "pipe nobody reads") { + t.Fatal(all) + } +} + +func TestRestartEndsItPlacesTheUserJSAndStartsItUnderTheServiceManager(t *testing.T) { + f := newFake(t) + f.desktopSession() + f.betterbird() + links(t, nil) + f.declare("// none") + f.onStart = func(argv []string) { + f.proc(5000, 1000, "betterbird-bin", []string{"betterbird"}, "mesh-betterbird.service") + } + a, err := f.Restart() + if err != nil { + t.Fatal(err) + } + if len(a.Ended) != 1 || a.Ended[0] != 4000 || len(a.Running) != 1 || a.Running[0].PID != 5000 || !strings.HasPrefix(a.UserJS, "placed") { + t.Fatalf("%+v", a) + } + if !f.called("systemd-run --user --collect --quiet --unit=mesh-betterbird") { + t.Fatalf("%v", f.calls) + } +} + +func TestTheReminderTestTouchesNothingOfTheOperatorsProfile(t *testing.T) { + f := newFake(t) + f.desktopSession() + f.betterbird() + links(t, nil) + f.declare(`user_pref("calendar.alarms.show", true);`) + before, _ := os.ReadFile(filepath.Join(f.Root, profileDir, "prefs.js")) + a, err := f.ReminderTest(40*time.Second, []string{"extensions.activeThemeID", "mail.identity.id1.useremail", "nope.nope"}, false) + if err != nil { + t.Fatal(err) + } + if strings.Join(a.Carried, ",") != "extensions.activeThemeID" || len(a.Withheld) != 2 { + t.Fatalf("%+v", a) + } + dir := filepath.Join(f.Root, "/run/user/1000", testUnit) + user, _ := os.ReadFile(filepath.Join(dir, "profile", "user.js")) + cal, _ := os.ReadFile(filepath.Join(dir, "test.ics")) + if !strings.Contains(string(user), `"calendar.alarms.show", true`) || !strings.Contains(string(user), `"extensions.activeThemeID", "thunderbird-compact-dark@mozilla.org"`) || + !strings.Contains(string(user), "file:///run/user/1000/"+testUnit+"/test.ics") || strings.Contains(string(user), "someone@") { + t.Fatalf("%s", user) + } + // The event starts 10 minutes after the reminder, which is due 40 s from now. + if !strings.Contains(string(cal), "DTSTART:20270115T081040Z") || !strings.Contains(string(cal), "TRIGGER:-PT10M") || + a.Due != "2027-01-15T08:00:40Z" { + t.Fatalf("%s %s", cal, a.Due) + } + if !f.called("systemd-run --user --collect --quiet --unit=" + testUnit + " -p RuntimeMaxSec=600 --setenv=MOZ_NO_REMOTE=1") { + t.Fatalf("%v", f.calls) + } + after, _ := os.ReadFile(filepath.Join(f.Root, profileDir, "prefs.js")) + if string(before) != string(after) || exists(filepath.Join(f.Root, profileDir, "user.js")) { + t.Fatal("the operator's profile is untouched") + } + if _, err := f.ReminderTest(0, nil, true); err != nil || exists(dir) { + t.Fatalf("stop removes the test profile: %v", err) + } +} diff --git a/modules/betterbird/cmd/betterbird-tools/copies_test.go b/modules/betterbird/cmd/betterbird-tools/copies_test.go new file mode 100644 index 00000000..5bb7bb38 --- /dev/null +++ b/modules/betterbird/cmd/betterbird-tools/copies_test.go @@ -0,0 +1,37 @@ +package main + +// The desktop applications whose bundles carry desktop.go. Each builds alone, so each has its own copy; +// this test, itself one of the copied files, holds them to one text wherever the siblings are present. + +import ( + "bytes" + "os" + "path/filepath" + "testing" +) + +var carriers = []string{"blueman", "forticlient", "nextcloud-client", "nm-applet", "openrazer", "polychromatic", "slack"} + +func TestEveryDesktopApplicationCarriesTheSameCopy(t *testing.T) { + compared := 0 + for _, module := range carriers { + dir := filepath.Join("..", "..", "..", module, "cmd", module+"-tools") + if _, err := os.Stat(dir); err != nil { + continue + } + for _, f := range []string{"desktop.go", "desktop_test.go", "copies_test.go"} { + mine, err := os.ReadFile(f) + if err != nil { + t.Fatal(err) + } + theirs, err := os.ReadFile(filepath.Join(dir, f)) + if err != nil || !bytes.Equal(mine, theirs) { + t.Errorf("%s's copy of %s differs from this one: change every copy together", module, f) + } + } + compared++ + } + if compared == 0 { + t.Log("no sibling copies beside this module") + } +} diff --git a/modules/betterbird/cmd/betterbird-tools/desktop.go b/modules/betterbird/cmd/betterbird-tools/desktop.go new file mode 100644 index 00000000..4f52391d --- /dev/null +++ b/modules/betterbird/cmd/betterbird-tools/desktop.go @@ -0,0 +1,601 @@ +package main + +// desktop.go is the same file in every desktop application's bundle (copies_test.go names them and +// holds them to one text): a tray application of the operator's graphical session, seen from the +// node's tool runtime (novox/hq ADR 0208). +// +// The runtime is a system service running as the operator account (ADR 0175): it has the account's +// uid and none of the session's environment. A tool that starts something on the desktop finds the +// session from a process of the account that carries DISPLAY (the window manager first), and starts +// the program under the account's own service manager with `systemd-run --user`, never as its own +// child: the runtime's unit is a cgroup that is emptied whenever the runtime restarts. +// +// Everything a tool touches goes through a Machine: its filesystem root, its commands (a Runner) and +// its signals are injected, so the tests run against a fake /proc and a fake home. +// +// Bounds: one command gets at most CallTimeout (below the runtime's 30 s call limit) and is ended +// with everything it started when it takes longer; each stream is kept to MostOutput; a file is read +// to at most MostRead. + +import ( + "bufio" + "bytes" + "context" + "errors" + "fmt" + "io" + "os" + "os/exec" + "path/filepath" + "sort" + "strconv" + "strings" + "syscall" + "time" +) + +// Bounds every command and read is held to. +const ( + CallTimeout = 10 * time.Second + MostOutput = 256 << 10 + MostRead = 16 << 20 +) + +// Output is what a command did. +type Output struct { + Stdout string + Stderr string + Code int + // Err is why it did not run to an answer: not installed, ended on its timeout, or the spawn error. + Err error + Cut bool +} + +// ErrNotInstalled and ErrTimedOut are what a Runner answers in Output.Err. +var ( + ErrNotInstalled = errors.New("not installed") + ErrTimedOut = errors.New("timed out") + // ErrNoSession is answered by a tool that needs the desktop when nobody is logged in to it. + ErrNoSession = errors.New("no graphical session") +) + +// Runner runs one command with extra environment, within the context's deadline. Tests replace it. +type Runner func(ctx context.Context, env []string, name string, args ...string) Output + +// Machine is what the tools read and act on. +type Machine struct { + Root string // "" on the machine; a fake root in tests + Home string // the operator's home, as the machine names it + UID int + Run Runner + Kill func(pid int, sig syscall.Signal) error + Sleep func(time.Duration) + Now func() time.Time + Timeout time.Duration +} + +// NewMachine is the machine the bundle runs on. +func NewMachine() *Machine { + return &Machine{Home: operatorHome(), UID: os.Getuid(), Run: execRun, Kill: syscall.Kill, + Sleep: time.Sleep, Now: time.Now, Timeout: CallTimeout} +} + +// operatorHome is the account's home: what the runtime was told, else the process's own. +func operatorHome() string { + if h := strings.TrimSpace(os.Getenv("MESH_OPERATOR_HOME")); h != "" { + return h + } + h, _ := os.UserHomeDir() + return h +} + +func (m *Machine) path(p string) string { return filepath.Join(m.Root, p) } + +// home is a path under the operator's home, on this machine's filesystem. +func (m *Machine) home(rel ...string) string { + return filepath.Join(append([]string{m.Root, m.Home}, rel...)...) +} + +// tilde shows a path under the home as ~/…, so an answer does not carry the account's name. +func (m *Machine) tilde(p string) string { + if m.Home != "" && m.Home != "/" { + h := strings.TrimSuffix(m.Home, "/") + if p == h { + return "~" + } + if strings.HasPrefix(p, h+"/") { + return "~/" + strings.TrimPrefix(p, h+"/") + } + } + return p +} + +// cmd runs a command within the machine's timeout (or a shorter one). +func (m *Machine) cmd(timeout time.Duration, env []string, name string, args ...string) Output { + if timeout <= 0 || timeout > m.Timeout { + timeout = m.Timeout + } + ctx, cancel := context.WithTimeout(context.Background(), timeout) + defer cancel() + return m.Run(ctx, env, name, args...) +} + +// failed names how a command failed, or answers nil when it ran and exited 0. +func failed(o Output, name string, args ...string) error { + switch { + case errors.Is(o.Err, ErrNotInstalled): + return fmt.Errorf("%s is not installed on this machine", name) + case errors.Is(o.Err, ErrTimedOut): + return fmt.Errorf("%s gave no answer in time and was ended", name) + case o.Err != nil: + return fmt.Errorf("%s did not run: %v", name, o.Err) + case o.Code != 0: + said := strings.TrimSpace(o.Stderr) + if said == "" { + said = strings.TrimSpace(o.Stdout) + } + if said == "" { + said = "and said nothing" + } + return fmt.Errorf("%s %s exited %d: %s", name, strings.Join(args, " "), o.Code, tail(said, 1000)) + } + return nil +} + +func tail(s string, n int) string { + if len(s) <= n { + return s + } + return "…" + s[len(s)-n:] +} + +type capped struct { + b bytes.Buffer + cut bool +} + +func (c *capped) Write(p []byte) (int, error) { + if room := MostOutput - c.b.Len(); room < len(p) { + if room > 0 { + c.b.Write(p[:room]) + } + c.cut = true + return len(p), nil + } + return c.b.Write(p) +} + +func execRun(ctx context.Context, env []string, name string, args ...string) Output { + path, err := exec.LookPath(name) + if err != nil { + return Output{Code: 127, Err: ErrNotInstalled} + } + cmd := exec.CommandContext(ctx, path, args...) + cmd.Env = append(append(os.Environ(), "LC_ALL=C"), env...) + // Its own process group, so that ending it on a timeout ends what it started too. + cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true} + cmd.Cancel = func() error { + if cmd.Process != nil { + _ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL) + } + return nil + } + cmd.WaitDelay = 2 * time.Second + var out, errs capped + cmd.Stdout, cmd.Stderr = &out, &errs + err = cmd.Run() + o := Output{Stdout: out.b.String(), Stderr: errs.b.String(), Cut: out.cut || errs.cut} + var exit *exec.ExitError + switch { + case err == nil: + case ctx.Err() == context.DeadlineExceeded: + o.Code, o.Err = 124, ErrTimedOut + case errors.As(err, &exit): + o.Code = exit.ExitCode() + default: + o.Code, o.Err = 127, err + } + return o +} + +// readBounded reads a file to at most MostRead bytes. +func readBounded(path string) ([]byte, error) { + f, err := os.Open(path) + if err != nil { + return nil, err + } + defer f.Close() + return io.ReadAll(io.LimitReader(f, MostRead)) +} + +// Proc is one process of the account. +type Proc struct { + PID int `json:"pid"` + Command string `json:"command"` + // StartedIn is the unit or scope it runs in: the login session's scope when the session's start + // (dex, the window manager) started it, a mesh-… unit when a tool restarted it. + StartedIn string `json:"started_in,omitempty"` + Since string `json:"since,omitempty"` +} + +// procs are this account's processes named comm, oldest first. +func (m *Machine) procs(comm string) []Proc { + entries, err := os.ReadDir(m.path("/proc")) + if err != nil { + return nil + } + boot := m.bootTime() + var out []Proc + for _, e := range entries { + pid, err := strconv.Atoi(e.Name()) + if err != nil { + continue + } + dir := m.path(filepath.Join("/proc", e.Name())) + if readTrimmed(filepath.Join(dir, "comm")) != comm || m.uidOf(dir) != m.UID { + continue + } + p := Proc{PID: pid, Command: strings.TrimSpace(strings.ReplaceAll(readTrimmed(filepath.Join(dir, "cmdline")), "\x00", " "))} + if p.Command == "" { + p.Command = comm + } + if cg := readTrimmed(filepath.Join(dir, "cgroup")); cg != "" { + line := strings.Split(cg, "\n")[0] + p.StartedIn = filepath.Base(line[strings.LastIndexByte(line, ':')+1:]) + } + if t, ok := startOf(readTrimmed(filepath.Join(dir, "stat")), boot); ok { + p.Since = t.UTC().Format(time.RFC3339) + } + out = append(out, p) + } + sort.Slice(out, func(i, j int) bool { return out[i].PID < out[j].PID }) + return out +} + +// procsOf are the account's processes named comm whose program is word. The kernel keeps 15 +// characters of a command name, so a longer name can share them with another program's: this bundle's +// own binary among them (polychromatic-tools and polychromatic-tray-applet are both polychromatic-t). +// The program is the first word of the command line, or the second for a script run by its +// interpreter. An empty word keeps every process named comm. +func (m *Machine) procsOf(comm, word string) []Proc { + var out []Proc + for _, p := range m.procs(comm) { + f := strings.Fields(p.Command) + if word == "" || (len(f) > 0 && filepath.Base(f[0]) == word) || (len(f) > 1 && filepath.Base(f[1]) == word) { + out = append(out, p) + } + } + return out +} + +// uidOf is the real uid on a process's status, -1 when unreadable. +func (m *Machine) uidOf(dir string) int { + for _, l := range strings.Split(readTrimmed(filepath.Join(dir, "status")), "\n") { + if f := strings.Fields(l); len(f) > 1 && f[0] == "Uid:" { + if n, err := strconv.Atoi(f[1]); err == nil { + return n + } + } + } + return -1 +} + +func (m *Machine) bootTime() int64 { + for _, l := range strings.Split(readTrimmed(m.path("/proc/stat")), "\n") { + if f := strings.Fields(l); len(f) == 2 && f[0] == "btime" { + n, _ := strconv.ParseInt(f[1], 10, 64) + return n + } + } + return 0 +} + +// startOf reads a process's start from its stat line (field 22, in clock ticks of 1/100 s since boot). +func startOf(stat string, boot int64) (time.Time, bool) { + i := strings.LastIndexByte(stat, ')') + if i < 0 || boot == 0 { + return time.Time{}, false + } + f := strings.Fields(stat[i+1:]) + if len(f) < 20 { + return time.Time{}, false + } + ticks, err := strconv.ParseInt(f[19], 10, 64) + if err != nil { + return time.Time{}, false + } + return time.Unix(boot+ticks/100, 0), true +} + +func readTrimmed(path string) string { + b, err := os.ReadFile(path) + if err != nil { + return "" + } + return strings.TrimSpace(string(b)) +} + +func exists(path string) bool { + _, err := os.Stat(path) + return err == nil +} + +// Session is what a tool needs to start something on the operator's desktop. +type Session struct { + Display string `json:"display"` + XAuthority string `json:"xauthority,omitempty"` + Bus string `json:"bus,omitempty"` + RuntimeDir string `json:"runtime_dir,omitempty"` + From string `json:"found_in"` +} + +// sessionHolders are the processes whose environment is the session's, best first. +var sessionHolders = []string{"i3", "sway", "i3bar", "picom", "dunst", "xterm"} + +// session finds the account's graphical session, or ErrNoSession saying what it looked at. +func (m *Machine) session() (Session, error) { + entries, _ := os.ReadDir(m.path("/proc")) + best, bestRank := -1, len(sessionHolders)+1 + var env map[string]string + var from string + for _, e := range entries { + pid, err := strconv.Atoi(e.Name()) + if err != nil { + continue + } + dir := m.path(filepath.Join("/proc", e.Name())) + if m.uidOf(dir) != m.UID { + continue + } + raw, err := os.ReadFile(filepath.Join(dir, "environ")) + if err != nil { + continue + } + vars := parseEnviron(raw) + if vars["DISPLAY"] == "" { + continue + } + comm := readTrimmed(filepath.Join(dir, "comm")) + rank := len(sessionHolders) + for i, h := range sessionHolders { + if h == comm { + rank = i + } + } + if rank < bestRank || (rank == bestRank && pid > best) { + best, bestRank, env, from = pid, rank, vars, fmt.Sprintf("process %s (pid %d)", comm, pid) + } + } + if env == nil { + return Session{}, fmt.Errorf("%w for uid %d on this machine: no process of the account carries DISPLAY. "+ + "Is anyone logged in to the desktop?", ErrNoSession, m.UID) + } + s := Session{Display: env["DISPLAY"], XAuthority: env["XAUTHORITY"], Bus: env["DBUS_SESSION_BUS_ADDRESS"], + RuntimeDir: env["XDG_RUNTIME_DIR"], From: from} + if s.RuntimeDir == "" { + s.RuntimeDir = fmt.Sprintf("/run/user/%d", m.UID) + } + if s.Bus == "" && exists(m.path(filepath.Join(s.RuntimeDir, "bus"))) { + s.Bus = "unix:path=" + filepath.Join(s.RuntimeDir, "bus") + } + return s, nil +} + +// bus is the account's session bus environment, which a logged-in account has with or without a +// desktop: what a command needs to reach the user's service manager or a bus name. +func (m *Machine) bus() []string { + runtime := fmt.Sprintf("/run/user/%d", m.UID) + return []string{"XDG_RUNTIME_DIR=" + runtime, "DBUS_SESSION_BUS_ADDRESS=unix:path=" + runtime + "/bus"} +} + +// Env is the session's variables, for a command that draws or speaks to the desktop. +func (s Session) Env() []string { + var env []string + for _, kv := range [][2]string{{"DISPLAY", s.Display}, {"XAUTHORITY", s.XAuthority}, + {"DBUS_SESSION_BUS_ADDRESS", s.Bus}, {"XDG_RUNTIME_DIR", s.RuntimeDir}} { + if kv[1] != "" { + env = append(env, kv[0]+"="+kv[1]) + } + } + return env +} + +func parseEnviron(raw []byte) map[string]string { + env := map[string]string{} + for _, kv := range bytes.Split(raw, []byte{0}) { + if i := bytes.IndexByte(kv, '='); i > 0 { + env[string(kv[:i])] = string(kv[i+1:]) + } + } + return env +} + +// detach starts a long-lived program under the account's service manager, as a transient unit that +// carries the session's display. A unit left by an earlier start under the same name is stopped +// first, so the fixed name means at most one. +func (m *Machine) detach(s Session, unit string, argv ...string) error { + _ = m.cmd(5*time.Second, s.Env(), "systemctl", "--user", "stop", unit+".service") + call := []string{"--user", "--collect", "--quiet", "--unit=" + unit} + for _, kv := range [][2]string{{"DISPLAY", s.Display}, {"XAUTHORITY", s.XAuthority}} { + if kv[1] != "" { + call = append(call, "--setenv="+kv[0]+"="+kv[1]) + } + } + call = append(append(call, "--"), argv...) + return failed(m.cmd(8*time.Second, s.Env(), "systemd-run", call...), "systemd-run", call...) +} + +// stop ends every process of the account named in comms: SIGTERM, then SIGKILL for what is still +// there after grace. It answers the pids that ended and those that had to be killed. +func (m *Machine) stop(grace time.Duration, comms ...string) (ended, killed []int) { + var ps []Proc + for _, c := range comms { + ps = append(ps, m.procs(c)...) + } + return m.stopProcs(grace, ps) +} + +// stopProcs ends the processes given, as stop does. +func (m *Machine) stopProcs(grace time.Duration, ps []Proc) (ended, killed []int) { + var pids []int + for _, p := range ps { + if m.Kill(p.PID, syscall.SIGTERM) == nil { + pids = append(pids, p.PID) + } + } + alive := func() []int { + var left []int + for _, pid := range pids { + if exists(m.path(filepath.Join("/proc", strconv.Itoa(pid)))) { + left = append(left, pid) + } + } + return left + } + step := 200 * time.Millisecond + for waited := time.Duration(0); waited < grace && len(alive()) > 0; waited += step { + m.Sleep(step) + } + left := alive() + for _, pid := range left { + if m.Kill(pid, syscall.SIGKILL) == nil { + killed = append(killed, pid) + } + } + gone := map[int]bool{} + for _, pid := range left { + gone[pid] = true + } + for _, pid := range pids { + if !gone[pid] { + ended = append(ended, pid) + } + } + return ended, killed +} + +// waitFor waits up to d for a process of the account named comm, and answers what it found. +func (m *Machine) waitFor(comm string, d time.Duration) []Proc { return m.waitForOf(comm, "", d) } + +// waitForOf waits up to d for a process of the account named comm whose program is word (procsOf). +func (m *Machine) waitForOf(comm, word string, d time.Duration) []Proc { + step := 250 * time.Millisecond + for waited := time.Duration(0); ; waited += step { + if p := m.procsOf(comm, word); len(p) > 0 || waited >= d { + return p + } + m.Sleep(step) + } +} + +// desktopEntry reads the [Desktop Entry] group of an XDG desktop file; nil when there is none. +func desktopEntry(path string) map[string]string { + raw, err := readBounded(path) + if err != nil { + return nil + } + out := map[string]string{} + in := false + s := bufio.NewScanner(bytes.NewReader(raw)) + for s.Scan() { + l := strings.TrimSpace(s.Text()) + switch { + case strings.HasPrefix(l, "["): + in = l == "[Desktop Entry]" + case in && l != "" && !strings.HasPrefix(l, "#"): + if i := strings.IndexByte(l, '='); i > 0 { + out[strings.TrimSpace(l[:i])] = strings.TrimSpace(l[i+1:]) + } + } + } + return out +} + +// Autostart is what XDG autostart does with one entry: the account's file overrides the system's +// of the same name, and Hidden=true (or the GNOME switch off) means it is not started. +type Autostart struct { + Entry string `json:"entry"` + From string `json:"from"` + Exec string `json:"exec,omitempty"` + Starts bool `json:"starts"` + Because string `json:"because,omitempty"` +} + +// autostart resolves one XDG autostart entry by its file name, the account's directory first. +func (m *Machine) autostart(name string) Autostart { + a := Autostart{Entry: name} + user := m.home(".config", "autostart", name) + system := m.path(filepath.Join("/etc/xdg/autostart", name)) + var e map[string]string + switch { + case exists(user): + e, a.From = desktopEntry(user), m.tilde(filepath.Join(m.Home, ".config/autostart", name)) + case exists(system): + e, a.From = desktopEntry(system), filepath.Join("/etc/xdg/autostart", name) + default: + a.Because = "no such entry in ~/.config/autostart or /etc/xdg/autostart" + return a + } + a.Exec = e["Exec"] + switch { + case strings.EqualFold(e["Hidden"], "true"): + a.Because = "Hidden=true" + case strings.EqualFold(e["X-GNOME-Autostart-enabled"], "false"): + a.Because = "X-GNOME-Autostart-enabled=false" + case a.Exec == "": + a.Because = "the entry has no Exec" + default: + a.Starts = true + } + return a +} + +// i3Starts are the window manager's start-up lines (exec, exec_always) that run a program named +// word, in the configuration and its config.d: a second start beside an autostart entry. +func (m *Machine) i3Starts(word string) []string { + files := []string{m.home(".config", "i3", "config")} + more, _ := filepath.Glob(m.home(".config", "i3", "config.d", "*.conf")) + files = append(files, more...) + var out []string + for _, f := range files { + raw, err := readBounded(f) + if err != nil { + continue + } + for n, l := range strings.Split(string(raw), "\n") { + t := strings.TrimSpace(l) + if !strings.HasPrefix(t, "exec ") && !strings.HasPrefix(t, "exec_always ") { + continue + } + for _, w := range strings.Fields(t)[1:] { + if filepath.Base(strings.Trim(w, `"'`)) == word { + out = append(out, fmt.Sprintf("%s:%d: %s", m.tilde(strings.TrimPrefix(f, m.Root)), n+1, t)) + break + } + } + } + } + return out +} + +// installed asks the package manager for one package's version; "" when it is not installed. +func (m *Machine) installed(pkg string) (string, error) { + o := m.cmd(0, nil, "pacman", "-Q", pkg) + if o.Err != nil { + return "", failed(o, "pacman", "-Q", pkg) + } + if o.Code != 0 { + return "", nil + } + f := strings.Fields(o.Stdout) + if len(f) < 2 { + return "", fmt.Errorf("pacman -Q %s answered %q", pkg, o.Stdout) + } + return f[1], nil +} + +// Finding is one thing a check found wrong, and what to do about it. +type Finding struct { + What string `json:"what"` + Do string `json:"do,omitempty"` +} diff --git a/modules/betterbird/cmd/betterbird-tools/desktop_test.go b/modules/betterbird/cmd/betterbird-tools/desktop_test.go new file mode 100644 index 00000000..e17bb69d --- /dev/null +++ b/modules/betterbird/cmd/betterbird-tools/desktop_test.go @@ -0,0 +1,219 @@ +package main + +// The fake machine the tests run against, and the tests of desktop.go. The same in every desktop +// application's bundle (copies_test.go). + +import ( + "context" + "os" + "path/filepath" + "strconv" + "strings" + "sync" + "syscall" + "testing" + "time" +) + +const testHome = "/home/operator" + +// fake is a machine with a fake root, a scripted Runner and signals that end fake processes. +type fake struct { + *Machine + t *testing.T + mu sync.Mutex + calls []string + answer func(name string, args []string) Output + // onStart is run when systemd-run starts something, to let a fake process appear. + onStart func(argv []string) + // stubborn pids ignore SIGTERM. + stubborn map[int]bool + signals []string +} + +func newFake(t *testing.T) *fake { + t.Helper() + root := t.TempDir() + f := &fake{t: t, stubborn: map[int]bool{}} + f.Machine = &Machine{Root: root, Home: testHome, UID: 1000, Timeout: CallTimeout, + Sleep: func(time.Duration) {}, Now: func() time.Time { return time.Unix(1_800_000_000, 0) }} + f.Run = func(_ context.Context, env []string, name string, args ...string) Output { + f.mu.Lock() + f.calls = append(f.calls, strings.TrimSpace(name+" "+strings.Join(args, " "))) + f.mu.Unlock() + if name == "systemd-run" && f.onStart != nil { + for i, a := range args { + if a == "--" { + f.onStart(args[i+1:]) + } + } + } + if f.answer != nil { + return f.answer(name, args) + } + return Output{} + } + f.Kill = func(pid int, sig syscall.Signal) error { + f.signals = append(f.signals, strconv.Itoa(pid)+":"+sig.String()) + if sig == syscall.SIGKILL || !f.stubborn[pid] { + return os.RemoveAll(filepath.Join(root, "proc", strconv.Itoa(pid))) + } + return nil + } + f.write("/proc/stat", "cpu 1 2 3\nbtime 1799990000\n") + return f +} + +func (f *fake) write(path, content string) { + f.t.Helper() + p := filepath.Join(f.Root, path) + if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil { + f.t.Fatal(err) + } + if err := os.WriteFile(p, []byte(content), 0o644); err != nil { + f.t.Fatal(err) + } +} + +// proc adds a process of uid with a command name, argv, cgroup and environment. +func (f *fake) proc(pid, uid int, comm string, argv []string, cgroup string, env ...string) { + d := "/proc/" + strconv.Itoa(pid) + "/" + f.write(d+"comm", comm+"\n") + f.write(d+"status", "Name:\t"+comm+"\nUid:\t"+strconv.Itoa(uid)+"\t"+strconv.Itoa(uid)+"\t"+strconv.Itoa(uid)+"\t"+strconv.Itoa(uid)+"\n") + f.write(d+"cmdline", strings.Join(argv, "\x00")+"\x00") + f.write(d+"cgroup", "0::/user.slice/user-"+strconv.Itoa(uid)+".slice/"+cgroup+"\n") + f.write(d+"environ", strings.Join(env, "\x00")+"\x00") + // starttime (field 22) is 1000 ticks: 10 s after boot. + f.write(d+"stat", strconv.Itoa(pid)+" ("+comm+") S 1 1 1 0 -1 0 0 0 0 0 0 0 0 0 20 0 1 0 1000 0 0\n") +} + +func (f *fake) desktopSession() { + f.proc(3700, 1000, "i3", []string{"i3"}, "session-c1.scope", "DISPLAY=:1", "XAUTHORITY="+testHome+"/.Xauthority") + f.write("/run/user/1000/bus", "") +} + +func (f *fake) called(prefix string) bool { + for _, c := range f.calls { + if strings.HasPrefix(c, prefix) { + return true + } + } + return false +} + +func TestProcessesAreTheAccountsOwnWithWhereAndWhenTheyStarted(t *testing.T) { + f := newFake(t) + f.proc(10, 1000, "worker", []string{"/usr/bin/worker", "--background"}, "session-c1.scope") + f.proc(11, 1001, "worker", []string{"/usr/bin/worker"}, "session-c2.scope") + f.proc(12, 1000, "other", []string{"other"}, "x.scope") + got := f.procs("worker") + if len(got) != 1 || got[0].PID != 10 || got[0].Command != "/usr/bin/worker --background" || + got[0].StartedIn != "session-c1.scope" || got[0].Since != time.Unix(1799990010, 0).UTC().Format(time.RFC3339) { + t.Fatalf("%+v", got) + } +} + +func TestAProgramIsToldFromAnotherSharingItsCutName(t *testing.T) { + f := newFake(t) + f.proc(10, 1000, "polychromatic-t", []string{"/usr/bin/python", "/usr/bin/polychromatic-tray-applet"}, "s.scope") + f.proc(11, 1000, "polychromatic-t", []string{"polychromatic-tray-applet"}, "s.scope") + f.proc(12, 1000, "polychromatic-t", []string{"/usr/lib/mesh/polychromatic-tools"}, "s.scope") + if got := f.procsOf("polychromatic-t", "polychromatic-tray-applet"); len(got) != 2 || got[0].PID != 10 || got[1].PID != 11 { + t.Fatalf("%+v", got) + } + if got := f.procsOf("polychromatic-t", ""); len(got) != 3 { + t.Fatalf("%+v", got) + } + ended, _ := f.stopProcs(time.Second, f.procsOf("polychromatic-t", "polychromatic-tray-applet")) + if len(ended) != 2 || len(f.procs("polychromatic-t")) != 1 { + t.Fatalf("ended %v; the tools' own process must stay", ended) + } +} + +func TestTheSessionIsTheWindowManagersAndNoneIsSaidPlainly(t *testing.T) { + f := newFake(t) + if _, err := f.session(); err == nil || !strings.Contains(err.Error(), "no graphical session") { + t.Fatalf("%v", err) + } + f.proc(50, 1000, "xterm", []string{"xterm"}, "s.scope", "DISPLAY=:9") + f.desktopSession() + f.proc(60, 1001, "i3", []string{"i3"}, "s.scope", "DISPLAY=:5") + s, err := f.session() + if err != nil || s.Display != ":1" || s.XAuthority != testHome+"/.Xauthority" || s.Bus != "unix:path=/run/user/1000/bus" || + !strings.Contains(s.From, "i3") { + t.Fatalf("%+v %v", s, err) + } +} + +func TestStopAsksThenForcesAndDetachStartsUnderTheServiceManager(t *testing.T) { + f := newFake(t) + f.desktopSession() + f.proc(20, 1000, "app", []string{"app"}, "s.scope") + f.proc(21, 1000, "app", []string{"app"}, "s.scope") + f.stubborn[21] = true + ended, killed := f.stop(time.Second, "app") + if len(ended) != 1 || ended[0] != 20 || len(killed) != 1 || killed[0] != 21 { + t.Fatalf("ended %v killed %v (%v)", ended, killed, f.signals) + } + s, _ := f.session() + if err := f.detach(s, "mesh-app", "/usr/bin/app", "--background"); err != nil { + t.Fatal(err) + } + want := "systemd-run --user --collect --quiet --unit=mesh-app --setenv=DISPLAY=:1 --setenv=XAUTHORITY=" + testHome + + "/.Xauthority -- /usr/bin/app --background" + if !f.called("systemctl --user stop mesh-app.service") || !f.called(want) { + t.Fatalf("%q", f.calls) + } +} + +func TestAnAutostartEntryOfTheAccountOverridesTheSystemsAndHiddenStartsNothing(t *testing.T) { + f := newFake(t) + if a := f.autostart("x.desktop"); a.Starts || a.Because == "" { + t.Fatalf("%+v", a) + } + f.write("/etc/xdg/autostart/x.desktop", "[Desktop Entry]\nExec=x-applet\n[Desktop Action y]\nExec=other\n") + if a := f.autostart("x.desktop"); !a.Starts || a.Exec != "x-applet" || a.From != "/etc/xdg/autostart/x.desktop" { + t.Fatalf("%+v", a) + } + f.write(testHome+"/.config/autostart/x.desktop", "[Desktop Entry]\nExec=x-applet\nHidden=true\n") + if a := f.autostart("x.desktop"); a.Starts || a.Because != "Hidden=true" || a.From != "~/.config/autostart/x.desktop" { + t.Fatalf("%+v", a) + } +} + +func TestAWindowManagerStartIsFoundInTheConfigurationAndItsDropIns(t *testing.T) { + f := newFake(t) + f.write(testHome+"/.config/i3/config", "exec --no-startup-id dex --autostart --environment i3\n# exec app\nbindsym $mod+a exec app\n") + f.write(testHome+"/.config/i3/config.d/50-x.conf", "exec_always --no-startup-id /usr/bin/app --flag\n") + got := f.i3Starts("app") + if len(got) != 1 || got[0] != "~/.config/i3/config.d/50-x.conf:1: exec_always --no-startup-id /usr/bin/app --flag" { + t.Fatalf("%q", got) + } +} + +func TestACommandThatFailsIsNamed(t *testing.T) { + if err := failed(Output{Code: 127, Err: ErrNotInstalled}, "dex"); err == nil || !strings.Contains(err.Error(), "dex is not installed") { + t.Fatal(err) + } + if err := failed(Output{Code: 1, Stderr: "nope"}, "pacman", "-Q", "x"); err == nil || !strings.Contains(err.Error(), "pacman -Q x exited 1: nope") { + t.Fatal(err) + } + if err := failed(Output{}, "true"); err != nil { + t.Fatal(err) + } +} + +func TestTheRealRunnerBoundsTimeAndOutput(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond) + defer cancel() + if o := execRun(ctx, nil, "sleep", "5"); o.Err != ErrTimedOut { + t.Fatalf("%+v", o) + } + if o := execRun(context.Background(), nil, "no-such-program-here"); o.Err != ErrNotInstalled { + t.Fatalf("%+v", o) + } + o := execRun(context.Background(), nil, "head", "-c", strconv.Itoa(MostOutput+10), "/dev/zero") + if !o.Cut || len(o.Stdout) != MostOutput { + t.Fatalf("cut %v, %d bytes", o.Cut, len(o.Stdout)) + } +} diff --git a/modules/betterbird/cmd/betterbird-tools/main.go b/modules/betterbird/cmd/betterbird-tools/main.go new file mode 100644 index 00000000..b2e2ffa4 --- /dev/null +++ b/modules/betterbird/cmd/betterbird-tools/main.go @@ -0,0 +1,147 @@ +// The betterbird module's Go tools bundle (novox/hq ADR 0188, ADR 0193, ADR 0208): Betterbird, the +// mail and calendar client, in the operator's session, served by the node's runtime as the operator +// account. The module holds no seat, so every tool is its own. +// +// The operator's mail, calendars, accounts and credentials are never read: a tool reads processes, +// profiles.ini, and of the profile only prefs.js, user.js and extensions.json, and answers no +// preference that can hold a credential or names an account. +package main + +import ( + "fmt" + "os" + "time" + + stdio "git.novox.be/novox/mesh-sdk/go" +) + +func main() { + if err := stdio.Serve("", tools()); err != nil { + fmt.Fprintln(os.Stderr, err) + os.Exit(1) + } +} + +var machine = NewMachine() + +func tools() []stdio.Tool { + return []stdio.Tool{ + { + Name: "betterbird_status", + Description: "Betterbird: whether it runs (the main process's pid, since, and the scope it runs in; how " + + "many child processes), the installed package and version and whether it is from the AUR, where its " + + "output goes, the profile it uses and how that was found, the module's user.js (declared, placed, in " + + "effect), the add-ons the operator installed, and the preferences that decide how its windows and " + + "notifications look (reminder dialog, theme, renderer, system notifications). (r)", + Run: func(map[string]any) (any, error) { return machine.Status() }, + }, + { + Name: "betterbird_prefs", + Description: "Named preferences of Betterbird's profile: each one's value and where it comes from (user.js, " + + "which wins at the start; prefs.js; or Betterbird's default). A name ending in . or * is a prefix " + + "(at most 200 answered). A preference whose name can hold a credential, or that names an account, a " + + "server, a calendar or a person, is answered without its value. (r)", + Input: map[string]any{ + "names": map[string]any{"type": "array", "items": map[string]any{"type": "string"}, + "description": "preference names or prefixes, e.g. [\"calendar.alarms.\", \"extensions.activeThemeID\"]"}, + }, + Run: func(args map[string]any) (any, error) { + names, err := texts(args, "names") + if err != nil { + return nil, err + } + return machine.Prefs(names) + }, + }, + { + Name: "betterbird_user_js", + Description: "The module's user.js — the preferences the module declares, from its setting prefs, written by " + + "the mesh to ~/.config/betterbird/user.js — against the profile's user.js: whether it is placed, and " + + "whether the running Betterbird started after it was. With apply, place it in the profile (only where " + + "the profile has no user.js or the module's own; an operator's file is never overwritten). Betterbird " + + "reads it at its next start: betterbird_restart. (r; a with apply)", + Input: map[string]any{ + "apply": map[string]any{"type": "boolean", "description": "place the declared user.js in the profile (default false)"}, + }, + Run: func(args map[string]any) (any, error) { + apply, err := flag(args, "apply", false) + if err != nil { + return nil, err + } + return machine.userJS(apply) + }, + }, + { + Name: "betterbird_log", + Description: "The last lines Betterbird printed, from the journal of the unit the module starts it as " + + "(mesh-betterbird; or mesh-betterbird-reminder-test). With problems, only lines that say error, " + + "warning, assertion, crash or failure. Mail addresses and credentials are replaced by . A " + + "Betterbird the module did not start prints elsewhere, and the answer says so. (r)", + Input: map[string]any{ + "lines": map[string]any{"type": "integer", "description": "how many lines (default 100, at most 2000)"}, + "problems": map[string]any{"type": "boolean", "description": "only problem lines (default false)"}, + "unit": map[string]any{"type": "string", "enum": []string{restartAs, testUnit}, "description": "which start's journal (default " + restartAs + ")"}, + }, + Run: func(args map[string]any) (any, error) { + n, err := whole(args, "lines", 100, 1, 2000) + if err != nil { + return nil, err + } + problems, err := flag(args, "problems", false) + if err != nil { + return nil, err + } + unit, err := text(args, "unit", false) + if err != nil { + return nil, err + } + return machine.Log(n, problems, unit) + }, + }, + { + Name: "betterbird_restart", + Description: "End Betterbird (asked to quit, forced after 20 s), place the module's user.js when the profile " + + "allows it, and start Betterbird again in the operator's desktop session under the account's service " + + "manager (unit mesh-betterbird), its output in the journal. An unsent message in a composer is lost: ask " + + "the operator first. Answers the pids ended and the new main process. (a)", + Run: func(map[string]any) (any, error) { return machine.Restart() }, + }, + { + Name: "betterbird_check", + Description: "Check what the module promises: Betterbird is installed; one runs; its profile is found; the " + + "module's user.js is on the machine, valid, placed in the profile and in effect; its output is read " + + "(a pipe nobody reads loses what it prints). Answers ok and each finding with what to do. (r)", + Run: func(map[string]any) (any, error) { return machine.Check() }, + }, + { + Name: "betterbird_reminder_test", + Description: "Show a calendar reminder without touching the operator's calendar: a second Betterbird in a " + + "throw-away profile under the runtime directory (--no-remote, unit mesh-betterbird-reminder-test, at most " + + "10 minutes), with the module's user.js and one local calendar file holding one event whose reminder is " + + "due after `after` seconds. carry copies named preferences of the operator's profile (a theme, a " + + "colour switch) into it, never a credential or an account. Then xorg_windows (class Calendar) and " + + "xorg_screenshot show the reminder window. stop ends it and removes the profile. (a)", + Input: map[string]any{ + "after": map[string]any{"type": "integer", "description": "seconds until the reminder is due (default 40, 15 to 300)"}, + "carry": map[string]any{"type": "array", "items": map[string]any{"type": "string"}, + "description": "preference names to copy from the operator's profile, e.g. [\"extensions.activeThemeID\"]"}, + "stop": map[string]any{"type": "boolean", "description": "end the test Betterbird and remove its profile (default false)"}, + }, + Run: func(args map[string]any) (any, error) { + after, err := whole(args, "after", 40, 15, 300) + if err != nil { + return nil, err + } + carry, err := texts(args, "carry") + if err != nil { + return nil, err + } + stop, err := flag(args, "stop", false) + if err != nil { + return nil, err + } + return machine.ReminderTest(time.Duration(after)*time.Second, carry, stop) + }, + }, + } +} diff --git a/modules/betterbird/cmd/betterbird-tools/manifest_test.go b/modules/betterbird/cmd/betterbird-tools/manifest_test.go new file mode 100644 index 00000000..6a21f477 --- /dev/null +++ b/modules/betterbird/cmd/betterbird-tools/manifest_test.go @@ -0,0 +1,110 @@ +package main + +import ( + "encoding/json" + "os" + "path/filepath" + "reflect" + "strings" + "testing" +) + +// betterbird's shape (novox/hq issue 345, ADR 0208): no package (Betterbird comes from the AUR, and the +// node-engine installs from the official repositories only), no seat, no start of its own (the operator +// starts it from the launcher); the X display on its own machine; one directory and one file of its own, +// the user.js the setting prefs fills; and the Go bundle serving exactly the listed betterbird_ tools. + +type manifest struct { + Module string `json:"module"` + Version string `json:"version"` + Requires []string `json:"requires"` + Settings map[string]any `json:"settings"` + Tools []string `json:"tools"` + Resources []map[string]any `json:"resources"` + Build struct { + Artifacts []map[string]any `json:"artifacts"` + } `json:"build"` +} + +func readManifest(t *testing.T) (manifest, string) { + t.Helper() + raw, err := os.ReadFile(filepath.Join("..", "..", "module.json")) + if err != nil { + t.Fatal(err) + } + dec := json.NewDecoder(strings.NewReader(string(raw))) + dec.DisallowUnknownFields() + var m manifest + if err := dec.Decode(&m); err != nil { + t.Fatalf("module.json: %v", err) + } + return m, string(raw) +} + +func TestItOwnsTheUserJSAndNothingOfTheProfile(t *testing.T) { + m, raw := readManifest(t) + if m.Module != "betterbird" || !reflect.DeepEqual(m.Requires, []string{"x11-display"}) { + t.Fatalf("%+v", m) + } + var ids []string + for _, r := range m.Resources { + ids = append(ids, r["id"].(string)) + if r["type"] == "package" { + t.Errorf("betterbird-bin is the AUR's: a package resource asks the node-engine for what it cannot install") + } + if p, _ := r["path"].(string); !strings.HasPrefix(p, "${machine:account-home}/.config/betterbird") { + t.Errorf("a path outside the module's directory: %s", p) + } + } + if strings.Join(ids, ",") != "configuration-dir,user-js" { + t.Fatalf("%v", ids) + } + for _, never := range []string{".thunderbird", "prefs.js", "logins.json", "key4.db"} { + if strings.Contains(raw, never) { + t.Errorf("module.json names %q", never) + } + } + file := m.Resources[1] + content := file["content"].(string) + if !strings.HasPrefix(content, mark) || !strings.Contains(content, "${setting:prefs}") || file["trusted"] != nil { + t.Fatalf("the user.js begins with the mark, holds the setting, and stays trusted (only the terminal sets it): %v", file) + } + // The default is a comment, so a machine without the setting places a valid, empty user.js. + def := m.Settings["prefs"].(map[string]any)["default"].(string) + if err := validUserJS(strings.ReplaceAll(content, "${setting:prefs}", def)); err != nil { + t.Fatal(err) + } +} + +func TestTheToolsAgreeWithTheManifest(t *testing.T) { + m, raw := readManifest(t) + served := map[string]bool{} + for _, tool := range tools() { + served[tool.Name] = true + if !strings.HasPrefix(tool.Name, "betterbird_") || strings.TrimSpace(tool.Description) == "" { + t.Errorf("%s: prefixed betterbird_ and described", tool.Name) + } + } + for _, name := range m.Tools { + if !served[name] { + t.Errorf("module.json lists %s, which the bundle does not serve", name) + } + delete(served, name) + } + for name := range served { + t.Errorf("the bundle serves %s, which module.json does not list", name) + } + if len(m.Build.Artifacts) != 1 { + t.Fatalf("%v", m.Build.Artifacts) + } + b := m.Build.Artifacts[0] + if b["kind"] != "bundle" || b["language"] != "go" || b["from"] != "cmd/betterbird-tools" || b["binary"] != "betterbird-tools" { + t.Errorf("the Go tools bundle: %v", b) + } + s := strings.ToLower(raw) + for _, never := range []string{"/home/", "jochen", "g14", "shanks", "novox.be", "http"} { + if strings.Contains(s, never) { + t.Errorf("module.json names %q", never) + } + } +} diff --git a/modules/betterbird/cmd/betterbird-tools/reminder.go b/modules/betterbird/cmd/betterbird-tools/reminder.go new file mode 100644 index 00000000..2a7363b0 --- /dev/null +++ b/modules/betterbird/cmd/betterbird-tools/reminder.go @@ -0,0 +1,150 @@ +package main + +// A reminder on demand, without the operator's calendar: a second Betterbird, in a profile of its own +// under the account's runtime directory, with one local calendar file holding one event whose reminder +// is due a few seconds after the start. The running Betterbird, its profile, its accounts and its +// calendars are not touched: the second one starts with --no-remote, so it neither hands over to the +// first nor is handed to. +// +// The test profile gets the module's user.js too, so the reminder is drawn with the preferences the +// module declares. A theme or another preference of the operator's profile can be carried over by +// name (carry), within the same limits as betterbird_prefs: never a credential, never an account. +// +// It lives for at most ten minutes (the unit's RuntimeMaxSec), and stop ends it early and removes the +// profile. The reminder window is then found with xorg_windows (class Calendar, role AlarmWindow) and +// looked at with xorg_screenshot. + +import ( + "fmt" + "os" + "path/filepath" + "regexp" + "strconv" + "strings" + "time" +) + +// testDir is the test's profile and calendar, under the account's runtime directory. +func (m *Machine) testDir() string { + return m.path(fmt.Sprintf("/run/user/%d/%s", m.UID, testUnit)) +} + +// carryName is a preference name the test may carry over from the operator's profile. +var carryName = regexp.MustCompile(`^[A-Za-z0-9_.\-]+$`) + +// ReminderAnswer is what betterbird_reminder_test answers. +type ReminderAnswer struct { + Unit string `json:"unit"` + Profile string `json:"profile"` + Event string `json:"event"` + Due string `json:"reminder_due"` + Carried []string `json:"carried,omitempty"` + Withheld []string `json:"withheld,omitempty"` + Look string `json:"look"` + Stopped bool `json:"stopped,omitempty"` +} + +// ics is the test calendar: one event, its reminder `after` from now. +func ics(now time.Time, after time.Duration, stamp string) string { + f := func(t time.Time) string { return t.UTC().Format("20060102T150405Z") } + start := now.Add(after + 10*time.Minute) + return strings.Join([]string{"BEGIN:VCALENDAR", "VERSION:2.0", "PRODID:-//novox mesh//betterbird reminder test//EN", + "BEGIN:VEVENT", "UID:mesh-reminder-test-" + stamp + "@mesh", "DTSTAMP:" + f(now), "DTSTART:" + f(start), + "DTEND:" + f(start.Add(30*time.Minute)), "SUMMARY:Mesh reminder test", "BEGIN:VALARM", "ACTION:DISPLAY", + "DESCRIPTION:Mesh reminder test", "TRIGGER:-PT10M", "END:VALARM", "END:VEVENT", "END:VCALENDAR", ""}, "\r\n") +} + +// testPrefs are the test profile's own preferences: its one calendar, and no first-run questions. +func testPrefs(calendar string) string { + return strings.Join([]string{ + `user_pref("calendar.registry.meshtest.type", "ics");`, + `user_pref("calendar.registry.meshtest.uri", "file://` + calendar + `");`, + `user_pref("calendar.registry.meshtest.name", "Mesh reminder test");`, + `user_pref("calendar.registry.meshtest.calendar-main-in-composite", true);`, + `user_pref("calendar.registry.meshtest.suppressAlarms", false);`, + `user_pref("calendar.list.sortOrder", "meshtest");`, + `user_pref("mail.provider.suppress_dialog_on_startup", true);`, + `user_pref("mail.shell.checkDefaultClient", false);`, + `user_pref("datareporting.policy.dataSubmissionEnabled", false);`, + `user_pref("toolkit.telemetry.reportingpolicy.firstRun", false);`, + `user_pref("app.update.auto", false);`, + `user_pref("mail.rights.version", 1);`, + "", + }, "\n") +} + +// ReminderTest starts the test Betterbird, or with stop ends it and removes its profile. +func (m *Machine) ReminderTest(after time.Duration, carry []string, stop bool) (ReminderAnswer, error) { + dir := m.testDir() + a := ReminderAnswer{Unit: testUnit + ".service", Profile: strings.TrimPrefix(filepath.Join(dir, "profile"), m.Root), + Look: "xorg_windows with class Calendar answers the reminder window (role AlarmWindow, its depth and map state); " + + "xorg_screenshot with that window shows it as the screen does"} + if stop { + _ = m.cmd(5*time.Second, m.bus(), "systemctl", "--user", "stop", testUnit+".service") + if err := os.RemoveAll(dir); err != nil { + return a, err + } + a.Stopped, a.Look = true, "" + return a, nil + } + s, err := m.session() + if err != nil { + return a, err + } + var carried []string + if len(carry) > 0 { + p, err := m.profile() + if err != nil { + return a, err + } + prefsJS, _ := readBounded(filepath.Join(p.path, "prefs.js")) + have := readPrefs(prefsJS) + for _, n := range carry { + switch { + case !carryName.MatchString(n): + return a, fmt.Errorf("carry holds preference names, not %q", n) + case withheld(n) != "": + a.Withheld = append(a.Withheld, n+": "+withheld(n)) + case have[n] == "": + a.Withheld = append(a.Withheld, n+": not set in the operator's profile") + default: + carried = append(carried, fmt.Sprintf("user_pref(%s, %s);", strconv.Quote(n), have[n])) + a.Carried = append(a.Carried, n) + } + } + } + _ = m.cmd(5*time.Second, s.Env(), "systemctl", "--user", "stop", testUnit+".service") + if err := os.RemoveAll(dir); err != nil { + return a, err + } + if err := os.MkdirAll(filepath.Join(dir, "profile"), 0o700); err != nil { + return a, err + } + now := m.Now() + calendar := filepath.Join(dir, "test.ics") + if err := os.WriteFile(calendar, []byte(ics(now, after, strconv.FormatInt(now.Unix(), 10))), 0o600); err != nil { + return a, err + } + user := testPrefs(strings.TrimPrefix(calendar, m.Root)) + if mine, err := readBounded(m.home(declared)); err == nil && validUserJS(string(mine)) == nil { + user = string(mine) + "\n" + user + } + user += strings.Join(carried, "\n") + "\n" + if err := os.WriteFile(filepath.Join(dir, "profile", "user.js"), []byte(user), 0o600); err != nil { + return a, err + } + call := []string{"--user", "--collect", "--quiet", "--unit=" + testUnit, "-p", "RuntimeMaxSec=600", + "--setenv=MOZ_NO_REMOTE=1"} + for _, kv := range [][2]string{{"DISPLAY", s.Display}, {"XAUTHORITY", s.XAuthority}} { + if kv[1] != "" { + call = append(call, "--setenv="+kv[0]+"="+kv[1]) + } + } + call = append(call, "--", startBin, "--no-remote", "--profile", strings.TrimPrefix(filepath.Join(dir, "profile"), m.Root)) + if err := failed(m.cmd(8*time.Second, s.Env(), "systemd-run", call...), "systemd-run", call...); err != nil { + return a, err + } + a.Event = "Mesh reminder test, in a calendar file of the test profile only" + a.Due = now.Add(after).UTC().Format(time.RFC3339) + return a, nil +} diff --git a/modules/betterbird/go.mod b/modules/betterbird/go.mod new file mode 100644 index 00000000..49710a9c --- /dev/null +++ b/modules/betterbird/go.mod @@ -0,0 +1,5 @@ +module betterbird + +go 1.22 + +require git.novox.be/novox/mesh-sdk/go v0.1.7 diff --git a/modules/betterbird/go.sum b/modules/betterbird/go.sum new file mode 100644 index 00000000..b474419e --- /dev/null +++ b/modules/betterbird/go.sum @@ -0,0 +1,2 @@ +git.novox.be/novox/mesh-sdk/go v0.1.7 h1:C0sTQmtTiyYH7bnqZb7PusXnqA37gKuT7Nqjn9gG47w= +git.novox.be/novox/mesh-sdk/go v0.1.7/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY= diff --git a/modules/betterbird/module.json b/modules/betterbird/module.json new file mode 100644 index 00000000..b9f05de7 --- /dev/null +++ b/modules/betterbird/module.json @@ -0,0 +1,55 @@ +{ + "module": "betterbird", + "version": "1", + "requires": [ + "x11-display" + ], + "settings": { + "prefs": { + "kind": "preference", + "default": "// none", + "why": "Betterbird runs with its own defaults until a machine's assignment names a preference: one line of user_pref(\"name\", value); statements, which the module's user.js holds and Betterbird reads at its start (novox/hq issue 345)" + } + }, + "tools": [ + "betterbird_status", + "betterbird_prefs", + "betterbird_user_js", + "betterbird_log", + "betterbird_restart", + "betterbird_check", + "betterbird_reminder_test" + ], + "resources": [ + { + "id": "configuration-dir", + "type": "directory", + "path": "${machine:account-home}/.config/betterbird", + "owner": "${machine:account}", + "mode": "0755" + }, + { + "id": "user-js", + "type": "file", + "path": "${machine:account-home}/.config/betterbird/user.js", + "owner": "${machine:account}", + "mode": "0644", + "content": "// Betterbird's user.js (module betterbird, novox/hq issue 345). Owned by the mesh: the node-engine\n// writes it here at every push, and the module's tools copy it whole into Betterbird's profile\n// (betterbird_user_js with apply, betterbird_restart), where Betterbird reads it at its start and lets it\n// win over the preferences Betterbird saves itself. Change the module's setting prefs, never this file or the profile's copy.\n//\n// Only comments and user_pref(\"name\", value); statements; the tools refuse anything else, and any\n// preference whose name can hold a credential.\n${setting:prefs}\n" + } + ], + "build": { + "artifacts": [ + { + "name": "tools", + "kind": "bundle", + "language": "go", + "system": "arch", + "from": "cmd/betterbird-tools", + "binary": "betterbird-tools", + "loads": [ + "betterbird-tools" + ] + } + ] + } +} From 52a4827983d3e824a0a826a27da15b9804990768 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 9 Oct 2026 12:05:41 +0200 Subject: [PATCH 03/54] xorg: list the server's windows, and cut a window's screenshot from the screen (hq issue 345) A reminder window that showed as transparent and empty could not be looked at: the window manager's list leaves dialogs out and says nothing a compositor goes by, and xwd -id refused a window of a 32-bit visual with BadColor (X_QueryColors). xorg_windows answers every window with its class, and on request its depth, type, state, role and own opacity; a window's screenshot is now cut from the whole screen as the compositor shows it, and inline answers the image for a session that cannot read the machine's files. Declares xorg-xwininfo, which both now use. --- modules/xorg/README.md | 19 +- modules/xorg/cmd/xorg/main.go | 22 ++- modules/xorg/cmd/xorg/manifest_test.go | 2 +- modules/xorg/cmd/xorg/tools.go | 44 ++++- modules/xorg/cmd/xorg/windows.go | 246 +++++++++++++++++++++++++ modules/xorg/cmd/xorg/windows_test.go | 166 +++++++++++++++++ modules/xorg/cmd/xorg/xorg_test.go | 2 +- modules/xorg/module.json | 6 + 8 files changed, 494 insertions(+), 13 deletions(-) create mode 100644 modules/xorg/cmd/xorg/windows.go create mode 100644 modules/xorg/cmd/xorg/windows_test.go diff --git a/modules/xorg/README.md b/modules/xorg/README.md index cdc97851..226282b2 100644 --- a/modules/xorg/README.md +++ b/modules/xorg/README.md @@ -9,7 +9,7 @@ The X display server as a module (novox/hq ADR 0208, research 026, to-be 42 phas - **Gated by the capability `seat`**, which the host reports for a machine with a graphics device and a connected display. See *Blockers* for why not `graphical-session`. - **Packages:** `xorg-server`, `xorg-xinit`, `xorg-xrandr`, `xorg-xset`, `xorg-xrdb`, `xorg-xinput`, - `xorg-setxkbmap`, `xorg-xwd` and `autorandr`. The GPU's driver is not here. It follows the machine, + `xorg-setxkbmap`, `xorg-xwd`, `xorg-xwininfo` and `autorandr`. The GPU's driver is not here. It follows the machine, so it belongs to that machine model's hardware module. ## What it owns @@ -71,7 +71,8 @@ which is a cpp directive error under plain `xrdb -merge` but is skipped here. | `xorg_input_devices` | r | the input devices, and each pointer's libinput settings | | `xorg_input_set` | a | tap, tap drag, natural scroll, disable while typing, left handed, middle emulation, enabled, acceleration, by device id or name | | `xorg_keyboard` | r/a | the XKB map; set layout, variant, model, options | -| `xorg_screenshot` | d | a PNG of the screen, one output or one window, inside the home (default `~/Pictures/Screenshots/`) | +| `xorg_screenshot` | d | a PNG of the screen, one output or one window, inside the home (default `~/Pictures/Screenshots/`); with `inline`, the PNG in the answer as base64 (at most 4 MiB) | +| `xorg_windows` | r | the windows as the X server knows them, managed or not: id, name, instance and class, size and place; with a class or name filter (or `detail`), each one's depth (`argb`), visual, map state, override-redirect, types, states, role and own opacity | | `xorg_x_log` | r | the X server's log for the running session: version, start, errors (and warnings) | All answers are structured. Each tool that changes the running server says how long the change lasts. @@ -90,7 +91,19 @@ The bus it hands on is the user manager's (`unix:path=/run/user//bus`). Wit answers `{"error": "no-graphical-session", "reason": …, "looked": […]}`. The screenshot needs no screenshot program. `xwd` dumps the screen, and the module turns the dump -into a PNG itself. +into a PNG itself. **A window is cut from the dump of the whole screen** at the place `xwininfo` gives, +never dumped by its id: `xwd -id` asks the server for the window's colormap entries, which a window of +a 32-bit (alpha) visual refused with `BadColor (X_QueryColors)` on a workstation (2026-10-09), and the +cut shows the window as the compositor shows it, which is what a question about a window that looks +wrong needs. A window under another one shows what covers it. `inline` answers the image itself, for a +session that cannot read the machine's files. + +`xorg_windows` exists because a window manager lists only the windows it manages, and says nothing a +compositor goes by. A window of depth 32 has an alpha channel: the compositor blends it with what is +behind it, so one whose program drew nothing looks transparent rather than black. Its details take +two commands per window (`xwininfo -all`, and `xprop` for the role and the window's own opacity), so +they are read for at most 40 windows. `xprop` is the `picom` module's package; without it the role and +opacity are left out. ## What it improves diff --git a/modules/xorg/cmd/xorg/main.go b/modules/xorg/cmd/xorg/main.go index fd28adf4..56e95f5b 100644 --- a/modules/xorg/cmd/xorg/main.go +++ b/modules/xorg/cmd/xorg/main.go @@ -143,16 +143,34 @@ func tools(d desktop.Desk) []stdio.Tool { }, { Name: "xorg_screenshot", - Description: "Take a screenshot to a PNG file: the whole screen, one output, or one window by its X id. " + + Description: "Take a screenshot to a PNG file: the whole screen, one output, or one window by its X id " + + "(cut from the screen as the compositor shows it, so a see-through window shows what is behind it). " + "Written under the account's home (default ~/Pictures/Screenshots/screenshot-