@intentius/chant 0.124.30 → 0.124.32

package/src/workspace/ci-runner-key.test.ts

@@ -0,0 +1,204 @@
+/**
+ * #4099: the runner key on a `chant ci serve` or `chant ci run` host. The
+ * key is made in the state directory with mode 0600, `--setup-key --trust`
+ * proposes its runner entry on a branch through `trust runner add` (#3510)
+ * and never writes the target branch. Signing is opt-in (#4156): `ci serve`
+ * starts with no key and says nothing about it, and serves unsigned with one
+ * warning when `.chant/trust.json` at the target's head does not list its
+ * key. With `ci.green.signedSince` it refuses to start in either case.
+ *
+ * Every test works in its own temp repository with a bare origin and its own
+ * state directory. The jobs' `chant` is a stub script, and no job runs: the
+ * refusals come before the first poll.
+ */
+
+import { chmodSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { generateKeyPairSync } from "node:crypto";
+import { join } from "node:path";
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { cleanScratch, declaration, git, repoFixture, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
+import { parseArgs } from "../cli/parse-args";
+import type { CommandContext } from "../cli/registry";
+import { ciServeRunnerKey, ensureHostRunnerKey, hostRunnerKey, RUNNER_KEY_FILE } from "./ci-runner-key";
+import { runCiServe } from "./ci-serve";
+import { runCiRun } from "./ci-run";
+import { ciTagSigner } from "./ci-green";
+import { trustWrite } from "./trust/trust-write";
+
+const home = process.cwd();
+afterEach(() => {
+  process.chdir(home);
+  vi.restoreAllMocks();
+  cleanScratch();
+});
+
+/** The repository every test starts from, built once: a checkout on main with a bare origin, with commits made by a fixed identity and never signed. */
+const workspaceTemplate = repoFixture(() => {
+  const top = scratchDir("chant-runner-key-template-");
+  const origin = join(top, "origin");
+  const root = join(top, "root");
+  mkdirSync(origin);
+  mkdirSync(root);
+  git(origin, "init", "-q", "--bare");
+  git(root, "init", "-q");
+  git(root, "symbolic-ref", "HEAD", "refs/heads/main");
+  for (const [k, v] of [["user.name", "t"], ["user.email", "t@example.com"], ["commit.gpgsign", "false"]]) git(root, "config", k!, v!);
+  writeFiles(root, { "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "the app" }]), "app/a.txt": "a\n" });
+  git(root, "remote", "add", "origin", origin);
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", "init");
+  git(root, "push", "-q", "origin", "main");
+  return top;
+}, "chant-runner-key-");
+
+/** A copy of the template, its origin pointed at the copy of the bare one. */
+function workspace(): { root: string; origin: string; main: string } {
+  const top = workspaceTemplate();
+  const root = join(top, "root");
+  const origin = join(top, "origin");
+  git(root, "remote", "set-url", "origin", origin);
+  return { root, origin, main: git(root, "rev-parse", "HEAD") };
+}
+
+/** Run a ci command line in `cwd`, with what it printed. */
+async function cli(cwd: string, argv: string[], run: (ctx: CommandContext) => Promise<number> = runCiServe) {
+  process.chdir(cwd);
+  const out: string[] = [];
+  const err: string[] = [];
+  vi.spyOn(console, "log").mockImplementation((s: string) => void out.push(String(s)));
+  vi.spyOn(console, "error").mockImplementation((s: string) => void err.push(String(s)));
+  const code = await run({ args: parseArgs(argv) } as unknown as CommandContext);
+  return { code, out: out.join("\n"), err: err.join("\n") };
+}
+
+/** A stand-in for `chant` the jobs would run; no test here reaches a job. */
+function stubChant(): string {
+  const file = join(scratchDir("chant-runner-key-bin-"), "chant");
+  writeFileSync(file, "#!/bin/sh\nexit 0\n");
+  chmodSync(file, 0o755);
+  return file;
+}
+
+const SERVE = (state: string) => ["ci", "serve", "--forge", "forgejo", "--repo", "demo/estate", "--env", "local", "--once", "--state", state, "--chant", stubChant(), "--image", "node:22-bookworm"];
+
+describe("the host's runner key (#4099)", () => {
+  test("--setup-key makes an Ed25519 key with mode 0600, prints its public half, and reuses it", async () => {
+    const { root } = workspace();
+    const state = join(scratchDir("chant-runner-key-state-"), "ci-serve");
+    const first = await cli(root, ["ci", "serve", "--setup-key", "--state", state]);
+    expect(first.code).toBe(0);
+    const path = join(state, RUNNER_KEY_FILE);
+    expect(statSync(path).mode & 0o777).toBe(0o600);
+    expect(statSync(state).mode & 0o777).toBe(0o700);
+    expect(readFileSync(path, "utf-8")).toContain("BEGIN PRIVATE KEY");
+    expect(first.out).toMatch(/^ssh-ed25519 [A-Za-z0-9+/]+=*$/);
+    expect(first.err).toContain("made now, mode 0600");
+    // It is not listed yet, so the exact command is printed.
+    expect(first.err).toContain(`chant workspace trust runner add chant-runner:`);
+    expect(first.err).toContain(`--key "${first.out}"`);
+
+    // ci run --setup-key finds the same key and makes no other.
+    const again = await cli(root, ["ci", "run", "--setup-key", "--state", state], runCiRun);
+    expect(again.code).toBe(0);
+    expect(again.out).toBe(first.out);
+    expect(again.err).toContain("already here");
+
+    // A key other users can read is refused.
+    chmodSync(path, 0o644);
+    expect(() => hostRunnerKey(state)).toThrow(/can be read by other users/);
+    chmodSync(path, 0o600);
+    expect(ensureHostRunnerKey(state).created).toBe(false);
+  });
+
+  test("--setup-key --trust pushes the runner entry on a branch of its own and leaves main as it was", async () => {
+    const { root, origin, main } = workspace();
+    const state = scratchDir("chant-runner-key-state-");
+    const r = await cli(root, ["ci", "serve", "--setup-key", "--trust", "--principal", "chant-runner:demo", "--by", "github:alex", "--state", state]);
+    expect(r.code, r.err).toBe(0);
+    expect(r.err).toContain("committed the runner entry for chant-runner:demo on chant/trust-runner/chant-runner-demo");
+    const branch = "chant/trust-runner/chant-runner-demo";
+
+    // main is untouched, here and on the remote; the branch holds the entry and the role.
+    expect(git(origin, "rev-parse", "refs/heads/main")).toBe(main);
+    expect(git(root, "rev-parse", "HEAD")).toBe(main);
+    expect(git(root, "status", "--short")).toBe("");
+    const trust = JSON.parse(git(origin, "show", `${branch}:.chant/trust.json`)) as { runners: { principal: string; key: string }[]; roles: { runner: string[] } };
+    expect(trust.runners).toEqual([{ principal: "chant-runner:demo", class: "runner", key: r.out }]);
+    expect(trust.roles.runner).toEqual(["chant-runner:demo"]);
+    expect(git(origin, "rev-parse", `${branch}^`)).toBe(main);
+
+    // Until it merges, ci serve serves unsigned with a warning (refuses with the opt-in); once it has, the key signs as the principal.
+    const key = hostRunnerKey(state)!;
+    const pending = ciServeRunnerKey({ top: root, stateDir: state, branch: "main" });
+    expect(pending.pem).toBeUndefined();
+    expect(pending.warning).toMatch(/not trusted at main/);
+    expect(() => ciServeRunnerKey({ top: root, stateDir: state, branch: "main", required: main })).toThrow(/not trusted at main/);
+    git(root, "push", "-q", "origin", `refs/remotes/origin/${branch}:refs/heads/main`);
+    expect(ciServeRunnerKey({ top: root, stateDir: state, branch: "main" })).toMatchObject({ pem: key.pem, source: join(state, RUNNER_KEY_FILE) });
+    expect(ciTagSigner(root, git(root, "rev-parse", "refs/remotes/origin/main"), key.pem).principal).toBe("chant-runner:demo");
+
+    // Run again, it says the key is listed and proposes nothing.
+    const listed = await cli(root, ["ci", "serve", "--setup-key", "--trust", "--state", state]);
+    expect(listed.err).toContain("lists it for chant-runner:demo, with the runner role");
+  });
+
+  test("ci serve starts with no key and says nothing, and serves unsigned with one warning for a key trust.json does not list (#4156)", async () => {
+    const { root } = workspace();
+    const state = scratchDir("chant-runner-key-state-");
+
+    // No key: nothing about keys is printed. The serve goes on to the forge, which this test has no token for.
+    const none = await cli(root, SERVE(state));
+    expect(none.err.split("\n")).toHaveLength(2);
+    expect(none.err.split("\n")[0]).toContain("chant ci serve: --forge forgejo needs GITHUB_TOKEN");
+    const keyless = ciServeRunnerKey({ top: root, stateDir: state, branch: "main" });
+    expect(keyless.pem).toBeUndefined();
+    expect(keyless.warning).toBeUndefined();
+    expect(keyless.note).toContain("not signed");
+    // --verbose prints that one line.
+    const verbose = await cli(root, [...SERVE(state), "--verbose"]);
+    expect(verbose.err).toContain("ci serve: runs are not signed: there is no runner key");
+
+    // A key the head does not list: one warning at startup, and no key goes to the jobs.
+    ensureHostRunnerKey(state);
+    const unlisted = await cli(root, SERVE(state));
+    expect(unlisted.err.match(/not trusted at main [0-9a-f]{12}/g)).toHaveLength(1);
+    expect(unlisted.err).toContain("Runs are not signed until it is");
+    expect(unlisted.err).toContain("chant ci serve --setup-key --trust");
+    expect(unlisted.err).not.toContain("signing runs with");
+
+    // A key listed only in the working tree, not at the head, is not trusted either.
+    const other = generateKeyPairSync("ed25519").privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+    writeFileSync(join(state, "other.pem"), other, { mode: 0o600 });
+    expect(trustWrite({ cwd: root, action: "runner add", name: "ci-bot", key: join(state, "other.pem") })).toMatchObject({ changed: true });
+    const flagged = ciServeRunnerKey({ top: root, stateDir: state, branch: "main", keyFile: join(state, "other.pem") });
+    expect(flagged.pem).toBeUndefined();
+    expect(flagged.warning).toContain("lists no runner with this key");
+
+    // A key file that is not a key is an error either way.
+    writeFileSync(join(state, "bad.pem"), "not a key", { mode: 0o600 });
+    expect(() => ciServeRunnerKey({ top: root, stateDir: state, branch: "main", keyFile: join(state, "bad.pem") })).toThrow(/not an Ed25519 private key in PEM/);
+
+    // --unsigned is accepted and serves unsigned.
+    expect(ciServeRunnerKey({ top: root, stateDir: state, branch: "main", unsigned: true })).toMatchObject({ fromFlag: false, source: "none (--unsigned)" });
+  });
+
+  test("with ci.green.signedSince, ci serve refuses to start without a trusted key, --unsigned or not (#4156)", async () => {
+    const { root, main } = workspace();
+    const state = scratchDir("chant-runner-key-state-");
+    const green = { branch: "main", phases: { plan: ["pr-plan"] }, require: ["plan"], source: "runs", signedSince: main };
+    writeFiles(root, { "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "the app" }], { ci: { green } }) });
+
+    const none = await cli(root, SERVE(state));
+    expect(none.code).toBe(1);
+    expect(none.err).toContain(`ci.green.signedSince is ${main}, so every run must be signed, and there is no runner key`);
+    const unsigned = await cli(root, [...SERVE(state), "--unsigned"]);
+    expect(unsigned.code).toBe(1);
+    expect(unsigned.err).toContain("there is no runner key");
+
+    ensureHostRunnerKey(state);
+    const unlisted = await cli(root, SERVE(state));
+    expect(unlisted.code).toBe(1);
+    expect(unlisted.err).toMatch(/not trusted at main [0-9a-f]{12}/);
+    expect(unlisted.err).toContain("chant workspace trust runner add");
+  });
+});

package/src/workspace/ci-runner-key.ts

@@ -0,0 +1,275 @@
+/**
+ * The runner key on a `chant ci serve` or `chant ci run` host (#4099, epic
+ * #4101).
+ *
+ * The host keeps its runner key in the serve's state directory, by default
+ * `<git common dir>/chant/ci-serve/runner-key.pem`: an Ed25519 private key in
+ * PEM, mode 0600, made by `--setup-key` when there is none. Its public half
+ * is the `ssh-ed25519` line `.chant/trust.json` lists under `runners`, and
+ * `--setup-key --trust` proposes that entry through `chant workspace trust
+ * runner add` (#3510) on a branch of its own, pushed for review. It never
+ * commits to the target branch: changing the trust config is a protected
+ * write, and the change is reviewed and merged like any other.
+ *
+ * `ci serve` refuses to start when its key is not listed, with the runner
+ * role, in `.chant/trust.json` at the target branch's head, since every run
+ * it signed would then be ignored by `ci tick --source runs`. `--unsigned`
+ * starts it without a key.
+ */
+
+import { execFileSync } from "node:child_process";
+import { generateKeyPairSync } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { hostname, tmpdir } from "node:os";
+import { join } from "node:path";
+import { ciTagSigner } from "./ci-green";
+import { CiRunError } from "./ci-run";
+import { loadRunnerKey } from "./trust/dsse";
+import { trustWrite } from "./trust/trust-write";
+
+/** The runner key's file in the state directory. */
+export const RUNNER_KEY_FILE = "runner-key.pem";
+
+/** The principal `--setup-key --trust` lists the key for when `--principal` names none. */
+export function defaultRunnerPrincipal(): string {
+  return `chant-runner:${hostname().split(".")[0]!.toLowerCase().replace(/[^a-z0-9-]/g, "-") || "host"}`;
+}
+
+export interface HostRunnerKey {
+  path: string;
+  pem: string;
+  /** `ssh-ed25519 <base64>`. */
+  publicKey: string;
+  /** Whether this call made it. */
+  created: boolean;
+}
+
+const message = (err: unknown): string => (err instanceof Error ? err.message : String(err));
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+function tryGit(cwd: string, args: string[]): string | undefined {
+  try {
+    return git(cwd, args);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Read the key at `path`, refusing one others can read or one that is not an Ed25519 private key in PEM. */
+function readHostKey(path: string): HostRunnerKey {
+  const mode = statSync(path).mode & 0o777;
+  if (mode & 0o077) throw new CiRunError(`${path} can be read by other users (mode ${mode.toString(8)}); chmod 600 it, since it signs for this runner`);
+  const pem = readFileSync(path, "utf-8");
+  try {
+    return { path, pem, publicKey: loadRunnerKey(pem).publicKey, created: false };
+  } catch (err) {
+    throw new CiRunError(`${path} is not an Ed25519 private key in PEM: ${message(err)}`);
+  }
+}
+
+/** The host's runner key in `stateDir`, or undefined when there is none. */
+export function hostRunnerKey(stateDir: string): HostRunnerKey | undefined {
+  const path = join(stateDir, RUNNER_KEY_FILE);
+  return existsSync(path) ? readHostKey(path) : undefined;
+}
+
+/** The host's runner key in `stateDir`, made when there is none: Ed25519, PEM, mode 0600 in a directory of mode 0700. */
+export function ensureHostRunnerKey(stateDir: string): HostRunnerKey {
+  const found = hostRunnerKey(stateDir);
+  if (found) return found;
+  mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+  const path = join(stateDir, RUNNER_KEY_FILE);
+  const { privateKey } = generateKeyPairSync("ed25519");
+  const pem = privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+  // wx: never replace a key another process made in the meantime.
+  writeFileSync(path, pem, { mode: 0o600, flag: "wx" });
+  chmodSync(path, 0o600);
+  return { path, pem, publicKey: loadRunnerKey(pem).publicKey, created: true };
+}
+
+/**
+ * The target branch's head, as the readers of runners take it: the remote's
+ * branch after a fetch (best effort), else the local branch. Undefined when
+ * neither exists.
+ */
+export function targetHead(top: string, branch: string, remote = "origin"): { commit: string; ref: string } | undefined {
+  if (tryGit(top, ["remote", "get-url", remote]) !== undefined) tryGit(top, ["fetch", "-q", remote, `+refs/heads/${branch}:refs/remotes/${remote}/${branch}`]);
+  for (const ref of [`refs/remotes/${remote}/${branch}`, `refs/heads/${branch}`]) {
+    const commit = tryGit(top, ["rev-parse", "--verify", "-q", `${ref}^{commit}`]);
+    if (commit) return { commit, ref };
+  }
+  return undefined;
+}
+
+/** The exact command that lists `publicKey` for `principal`. */
+export function trustCommand(principal: string, publicKey: string): string {
+  return `chant workspace trust runner add ${principal} --key "${publicKey}"`;
+}
+
+/** Whether `.chant/trust.json` at `commit` lists the key as a runner holding the runner role: its principal, or why not. */
+export function runnerKeyListed(top: string, commit: string, pem: string): { ok: true; principal: string } | { ok: false; reason: string } {
+  try {
+    return { ok: true, principal: ciTagSigner(top, commit, pem, "the runs it signs").principal };
+  } catch (err) {
+    return { ok: false, reason: message(err) };
+  }
+}
+
+export interface RunnerTrustProposal {
+  /** The branch holding the commit, or null when the key was already listed at the target's head. */
+  branch: string | null;
+  commit: string | null;
+  /** Whether the branch was pushed to the remote. */
+  pushed: boolean;
+  /** The trust config's digest on the branch. */
+  digest: string | null;
+}
+
+/**
+ * Propose the runner entry for review (#4099): in a temporary worktree at
+ * the target's head, run `trust runner add` (#3510), commit the change on
+ * `chant/trust-runner/<principal>`, and push that branch to `remote` when
+ * the clone has it. The target branch is never written. The commit is made
+ * with the host's git identity and signing settings; when the policy at base
+ * has signers, the change needs a signature by a policy writer before it
+ * merges.
+ */
+export function proposeRunnerTrust(req: { top: string; branch: string; principal: string; publicKey: string; by?: string; remote?: string }): RunnerTrustProposal {
+  const remote = req.remote ?? "origin";
+  const head = targetHead(req.top, req.branch, remote);
+  if (!head) throw new CiRunError(`there is no branch ${req.branch} here or on ${remote}, so there is no trust config to add the runner to`);
+  const branch = `chant/trust-runner/${req.principal.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "")}`;
+  if (tryGit(req.top, ["rev-parse", "--verify", "-q", `refs/heads/${branch}`])) {
+    throw new CiRunError(`the branch ${branch} exists already; review or delete it, then run --setup-key --trust again`);
+  }
+  const dir = mkdtempSync(join(tmpdir(), "chant-trust-runner-"));
+  try {
+    git(req.top, ["worktree", "add", "-q", "-b", branch, dir, head.commit]);
+    const doc = trustWrite({ cwd: dir, action: "runner add", name: req.principal, key: req.publicKey, ...(req.by ? { by: req.by } : {}) });
+    if ("error" in doc) throw new CiRunError(`trust runner add refused (${doc.error.code}): ${doc.error.message}`);
+    if (!doc.changed) {
+      git(req.top, ["worktree", "remove", "--force", dir]);
+      git(req.top, ["branch", "-q", "-D", branch]);
+      return { branch: null, commit: null, pushed: false, digest: doc.digest };
+    }
+    git(dir, ["add", "--", ".chant/trust.json"]);
+    git(dir, ["commit", "-q", "-m", `trust the ${req.principal} runner key\n\nchant ci --setup-key --trust: list this host's runner key in .chant/trust.json (#4099).`]);
+    const commit = git(dir, ["rev-parse", "HEAD"]);
+    let pushed = false;
+    if (tryGit(req.top, ["remote", "get-url", remote]) !== undefined) {
+      try {
+        git(dir, ["push", "-q", remote, `refs/heads/${branch}:refs/heads/${branch}`]);
+        pushed = true;
+      } catch (err) {
+        throw new CiRunError(`committed ${branch} here, and pushing it to ${remote} failed: ${message(err).split("\n")[0]}`);
+      }
+    }
+    return { branch, commit, pushed, digest: doc.digest };
+  } finally {
+    tryGit(req.top, ["worktree", "remove", "--force", dir]);
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+export interface RunnerKeySetup {
+  key: HostRunnerKey;
+  /** The target's head the trust config was read at, or null when there is no such branch. */
+  head: string | null;
+  /** The principal the key is listed for at the head, or null. */
+  listedAs: string | null;
+  principal: string;
+  command: string;
+  proposal?: RunnerTrustProposal;
+}
+
+/** `--setup-key [--trust]`: make or read the key, see whether the target's head lists it, and with `trust` propose the entry. */
+export function setupRunnerKey(req: { top: string; stateDir: string; branch: string; principal?: string; trust?: boolean; by?: string }): RunnerKeySetup {
+  const key = ensureHostRunnerKey(req.stateDir);
+  const head = targetHead(req.top, req.branch);
+  const listed = head ? runnerKeyListed(req.top, head.commit, key.pem) : undefined;
+  const principal = req.principal ?? defaultRunnerPrincipal();
+  const out: RunnerKeySetup = { key, head: head?.commit ?? null, listedAs: listed?.ok ? listed.principal : null, principal, command: trustCommand(principal, key.publicKey) };
+  if (req.trust && !out.listedAs) out.proposal = proposeRunnerTrust({ top: req.top, branch: req.branch, principal, publicKey: key.publicKey, ...(req.by ? { by: req.by } : {}) });
+  return out;
+}
+
+/** What `--setup-key` prints on stderr; the public key alone goes to stdout. */
+export function formatRunnerKeySetup(s: RunnerKeySetup, branch: string): string {
+  const lines = [`runner key ${s.key.path} (${s.key.created ? "made now, mode 0600" : "already here"})`];
+  if (s.listedAs) {
+    lines.push(`.chant/trust.json at ${branch} ${s.head!.slice(0, 12)} lists it for ${s.listedAs}, with the runner role`);
+  } else if (s.proposal?.branch) {
+    lines.push(
+      `committed the runner entry for ${s.principal} on ${s.proposal.branch} (${s.proposal.commit!.slice(0, 12)})${s.proposal.pushed ? " and pushed it" : ""}; open a pull request into ${branch}, and the key counts once it merges`,
+    );
+    lines.push("changing .chant/trust.json is a protected write: when the trust policy has signers, an admin signs the commit before it merges");
+  } else if (s.proposal) {
+    lines.push(`the runner entry for ${s.principal} is already at ${branch}'s head`);
+  } else {
+    lines.push(`.chant/trust.json at ${branch}${s.head ? ` ${s.head.slice(0, 12)}` : ""} does not list it yet. In a checkout of ${branch}, run`, `  ${s.command}`, "commit the change through review, or run this again with --trust to push it on a branch");
+  }
+  return lines.join("\n");
+}
+
+/**
+ * The key `ci serve` signs with, checked before its first poll (#4099): the
+ * `--key` file, else `CHANT_RUNNER_KEY`, else the host's key in the state
+ * directory. Signing is opt-in (#4156):
+ *
+ * - With no key, `ci serve` serves unsigned and says so only in `note`.
+ * - A key `.chant/trust.json` at the target's head does not list with the
+ *   runner role, or a target branch it can't find to check against, leaves
+ *   it serving unsigned, with one `warning`.
+ * - With `required` (the declaration's `ci.green.signedSince`) each of
+ *   those refuses to start, as before #4156.
+ *
+ * A key that is not an Ed25519 private key in PEM, or a `--key` file that
+ * can't be read, refuses either way. `unsigned` (`--unsigned`) skips the
+ * key without `required` and is ignored with it.
+ */
+export function ciServeRunnerKey(req: {
+  top: string;
+  stateDir: string;
+  branch: string;
+  keyFile?: string;
+  envKey?: string;
+  unsigned?: boolean;
+  /** The declaration's `ci.green.signedSince`, when it sets one: every run must then be signed. */
+  required?: string | null;
+}): { pem?: string; fromFlag: boolean; source: string; warning?: string; note?: string } {
+  const required = req.required ?? null;
+  const optIn = `ci.green.signedSince is ${required}, so every run must be signed`;
+  if (req.unsigned && !required) return { fromFlag: false, source: "none (--unsigned)", note: "runs are not signed (--unsigned)" };
+  const host = req.keyFile === undefined && !req.envKey ? hostRunnerKey(req.stateDir) : undefined;
+  const pem = req.keyFile !== undefined ? readFileSync(req.keyFile, "utf-8") : req.envKey || host?.pem;
+  const source = req.keyFile !== undefined ? req.keyFile : req.envKey ? "CHANT_RUNNER_KEY" : (host?.path ?? join(req.stateDir, RUNNER_KEY_FILE));
+  if (pem === undefined) {
+    if (!required) return { fromFlag: false, source: "none", note: "runs are not signed: there is no runner key. To verify who ran a job, add one with chant ci serve --setup-key --trust" };
+    throw new CiRunError(`${optIn}, and there is no runner key: no --key, no CHANT_RUNNER_KEY and no ${source}. Make one with chant ci serve --setup-key and list it with --trust`);
+  }
+  let publicKey: string;
+  try {
+    publicKey = loadRunnerKey(pem).publicKey;
+  } catch (err) {
+    throw new CiRunError(`the runner key from ${source} is not an Ed25519 private key in PEM: ${message(err)}`);
+  }
+  const head = targetHead(req.top, req.branch);
+  if (!head) {
+    const why = `there is no branch ${req.branch} here or on origin, so the runner key can't be checked against its .chant/trust.json`;
+    if (required) throw new CiRunError(`${optIn}, and ${why}; fetch it`);
+    return { fromFlag: false, source, warning: `${why}, so runs are not signed; fetch it to sign them` };
+  }
+  const listed = runnerKeyListed(req.top, head.commit, pem);
+  if (!listed.ok) {
+    const why = `the runner key from ${source} is not trusted at ${branchAt(req.branch, head.commit)}: ${listed.reason}`;
+    const fix = `List it on a branch for review with chant ci serve --setup-key --trust, or run ${trustCommand(defaultRunnerPrincipal(), publicKey)} in a checkout of ${req.branch} and merge the change.`;
+    if (required) throw new CiRunError(`${optIn}, and ${why}\n  ${fix}`);
+    return { fromFlag: false, source, warning: `${why}. Runs are not signed until it is. ${fix}` };
+  }
+  return { pem, fromFlag: req.keyFile !== undefined, source };
+}
+
+const branchAt = (branch: string, commit: string) => `${branch} ${commit.slice(0, 12)}`;

package/src/workspace/ci-secrets.test.ts

@@ -0,0 +1,106 @@
+/**
+ * #4096: the chant runner's secrets file, its allowlist, and the redactor
+ * built from it. Each file is written to its own scratch directory.
+ */
+
+import { chmodSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, scratchDir } from "./__fixtures__/contract-repo";
+import { ciRedactor, ciSecretsFor, CiSecretsError, parseCiSecrets, parseDotenv, readCiSecrets } from "./ci-secrets";
+import { ciSecretsOf } from "./ci-run";
+import { redactorOf, redactText } from "../op/redact";
+import { parseArgs } from "../cli/parse-args";
+
+afterAll(cleanScratch);
+
+function fileWithMode(text: string, mode: number): string {
+  const file = join(scratchDir("chant-ci-secrets-"), "secrets.env");
+  writeFileSync(file, text);
+  chmodSync(file, mode);
+  return file;
+}
+
+describe("the secrets file (#4096)", () => {
+  test.skipIf(process.platform === "win32")("a file its group or other users can read or change is refused, as ssh refuses a loose key", () => {
+    for (const mode of [0o644, 0o640, 0o604, 0o620, 0o660]) {
+      const file = fileWithMode("A_TOKEN=abcdef\n", mode);
+      expect(() => readCiSecrets(file)).toThrow(CiSecretsError);
+      expect(() => readCiSecrets(file)).toThrow(new RegExp(`has mode 0${mode.toString(8)}.*chmod 600`));
+    }
+    for (const mode of [0o600, 0o400]) expect(readCiSecrets(fileWithMode("A_TOKEN=abcdef\n", mode)).values).toEqual({ A_TOKEN: "abcdef" });
+    // CHANT_CI_SECRETS names the file when --secrets does not, and the same check applies.
+    const loose = fileWithMode("A_TOKEN=abcdef\n", 0o644);
+    expect(() => ciSecretsOf(undefined, { CHANT_CI_SECRETS: loose })).toThrow(/chmod 600/);
+    expect(ciSecretsOf(undefined, { CHANT_CI_SECRETS: fileWithMode("A_TOKEN=abcdef\n", 0o600) })?.values).toEqual({ A_TOKEN: "abcdef" });
+    expect(ciSecretsOf(undefined, {})).toBeUndefined();
+    expect(() => readCiSecrets(join(scratchDir("chant-ci-secrets-"), "missing.env"))).toThrow(/can't be read: ENOENT/);
+  });
+
+  test("dotenv: comments, export, quotes and escapes, and errors that name the line and not the value", () => {
+    const text = [
+      "# cloud",
+      "export AWS_ACCESS_KEY_ID=AKIAEXAMPLE",
+      "AWS_SECRET_ACCESS_KEY = 'single # kept'",
+      'PEM="line one\\nline two"',
+      "PLAIN=value # a comment",
+      "",
+      'MULTI="a',
+      'b"',
+    ].join("\n");
+    expect(parseDotenv(text, "s.env")).toEqual({
+      AWS_ACCESS_KEY_ID: "AKIAEXAMPLE",
+      AWS_SECRET_ACCESS_KEY: "single # kept",
+      PEM: "line one\nline two",
+      PLAIN: "value",
+      MULTI: "a\nb",
+    });
+    expect(() => parseDotenv("A=1\nnot a line hunter2\n", "s.env")).toThrow(/^s\.env:2: expected NAME=value$/);
+    expect(() => parseDotenv('A="unclosed hunter2', "s.env")).toThrow(/s\.env:1: the value of A has no closing "/);
+    expect(() => parseDotenv("A=1\nA=2\n", "s.env")).toThrow(/A is set twice/);
+    expect(() => parseCiSecrets("CHANT_RUNNER_KEY=x\n", "s.env")).toThrow(/runner key is never passed to a job/);
+  });
+
+  test("JSON: a flat map, or secrets with an allowlist for each job", () => {
+    expect(parseCiSecrets('{ "A_TOKEN": "abcd" }', "s.json")).toEqual({ values: { A_TOKEN: "abcd" }, jobs: {} });
+    const s = { file: "s.json", ...parseCiSecrets(JSON.stringify({ secrets: { A: "aaaa", B: "bbbb" }, jobs: { plan: ["A"] } }), "s.json") };
+    expect(ciSecretsFor(s, "plan")).toEqual({ A: "aaaa" });
+    expect(ciSecretsFor(s, "apply")).toEqual({ A: "aaaa", B: "bbbb" });
+    expect(ciSecretsFor(undefined, "plan")).toEqual({});
+    expect(ciSecretsFor({ ...s, jobs: { plan: [] } }, "plan")).toEqual({});
+    expect(() => parseCiSecrets(JSON.stringify({ secrets: { A: "aaaa" }, jobs: { plan: ["C"] } }), "s.json")).toThrow(/jobs\.plan names C, which the file does not set/);
+    expect(() => parseCiSecrets(JSON.stringify({ secrets: { A: "aaaa" }, jobs: { deploy: [] } }), "s.json")).toThrow(/the jobs are plan and apply/);
+    expect(() => parseCiSecrets('{ "A": 1 }', "s.json")).toThrow(/must be a string/);
+    // A parse error does not quote the text, which may hold a secret.
+    expect(() => parseCiSecrets('{ "A": "hunter2', "s.json")).toThrow(/^s\.json starts with \{, and is not valid JSON$/);
+  });
+
+  test("ci run and ci serve take --secrets", () => {
+    expect(parseArgs(["ci", "run", "plan", "--secrets", "/etc/chant/ci.env"])).toMatchObject({ ciSecrets: "/etc/chant/ci.env" });
+    expect(parseArgs(["ci", "serve", "--secrets", "s.json"])).toMatchObject({ ciSecrets: "s.json" });
+    expect(() => parseArgs(["ci", "run", "plan", "--secrets"])).toThrow(/--secrets needs/);
+  });
+});
+
+describe("redaction (#4096)", () => {
+  test("every secret, and each job variable whose name looks secret, is ***; a value under 4 characters is kept", () => {
+    const secrets = { file: "s", values: { DB: "hunter22", PIN: "abc" }, jobs: {} };
+    const redact = ciRedactor({ GITHUB_TOKEN: "ghp_abcdef", AWS_SECRET_ACCESS_KEY: "aws-secret", MY_PASSWORD: "pw-1234", HOME: "/home/runner", GITHUB_REPOSITORY: "acme/estate" }, secrets)!;
+    expect(redact("hunter22 ghp_abcdef aws-secret pw-1234 abc /home/runner acme/estate")).toBe("*** *** *** *** abc /home/runner acme/estate");
+    expect(ciRedactor({ HOME: "/h" })).toBeUndefined();
+    expect(redactorOf(["abc", ""])).toBeUndefined();
+  });
+
+  test("a JSON document or line stays JSON, a value that spans lines is redacted line by line, and the longest value wins", () => {
+    const redact = redactorOf(["true", 'qu"ote', "-----BEGIN KEY-----\nAAAABBBB\n-----END KEY-----", "abcd", "abcdefgh"])!;
+    const line = `${JSON.stringify({ ok: true, msg: "it is true", q: 'say qu"ote' })}\n`;
+    const out = redactText(line, redact);
+    expect(JSON.parse(out)).toEqual({ ok: true, msg: "it is ***", q: "say ***" });
+    expect(out.endsWith("\n")).toBe(true);
+    expect(redactText("[x] cmd | AAAABBBB", redact)).toBe("[x] cmd | ***");
+    expect(redact("abcdefgh abcd")).toBe("*** ***");
+    expect(redactText("nothing here", redact)).toBe("nothing here");
+    // JSON Lines: each line on its own.
+    expect(redactText('{"a":"abcd"}\nplain abcd\n', redact)).toBe('{"a":"***"}\nplain ***\n');
+  });
+});