@intentius/chant 0.124.30 → 0.124.31

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

@@ -0,0 +1,250 @@
+/**
+ * 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. Throws, with the command that lists it, when there is none or
+ * `.chant/trust.json` at the target's head does not list it with the runner
+ * role. With `unsigned` there is no key and nothing is checked.
+ */
+export function ciServeRunnerKey(req: { top: string; stateDir: string; branch: string; keyFile?: string; envKey?: string; unsigned?: boolean }): { pem?: string; fromFlag: boolean; source: string } {
+  if (req.unsigned) return { fromFlag: false, source: "none (--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) {
+    throw new CiRunError(`there is no runner key: no --key, no CHANT_RUNNER_KEY and no ${source}. Make one with chant ci serve --setup-key, list it with --trust, or start with --unsigned`);
+  }
+  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) throw new CiRunError(`there is no branch ${req.branch} here or on origin, so the runner key can't be checked against its .chant/trust.json; fetch it, or start with --unsigned`);
+  const listed = runnerKeyListed(req.top, head.commit, pem);
+  if (!listed.ok) {
+    throw new CiRunError(
+      `the runner key from ${source} is not trusted at ${branchAt(req.branch, head.commit)}: ${listed.reason}\n` +
+        `  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. Start with --unsigned to serve without signing.`,
+    );
+  }
+  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');
+  });
+});

package/src/workspace/ci-secrets.ts

@@ -0,0 +1,213 @@
+/**
+ * The chant runner's secrets file (#4096, epic #4101): the values a job gets
+ * from the host, such as cloud credentials and the endpoint, which a forge
+ * job would get from the forge's secrets.
+ *
+ * `chant ci run` and `chant ci serve` read it from `--secrets <file>`, or
+ * the file `CHANT_CI_SECRETS` names. It is a dotenv file of `NAME=value`
+ * lines, or a JSON object:
+ *
+ * - a map of name to value, `{ "AWS_SECRET_ACCESS_KEY": "..." }`;
+ * - or `{ "secrets": { ... }, "jobs": { "plan": [...], "apply": [...] } }`,
+ *   where `jobs` lists, for a job, the names it gets. A job `jobs` doesn't
+ *   name gets every secret.
+ *
+ * The allowlist lives in this file on the host, not in the repository, so a
+ * pull request can't widen what its plan gets.
+ *
+ * The file must belong to the user reading it and give group and others no
+ * permission at all, as ssh asks of a private key (`chmod 600`). A file
+ * that does is refused before any job runs.
+ *
+ * Every value in the file, and every value of the job's environment whose
+ * name looks secret ({@link SECRET_NAME}), is redacted from what the run
+ * writes about itself (../op/redact.ts).
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { redactorOf, type Redact } from "../op/redact";
+import { RUNNER_KEY_ENV } from "./ci-green";
+import type { CiJobName } from "./ci-run";
+
+/** The variable that names the secrets file when `--secrets` is not given. */
+export const CI_SECRETS_ENV = "CHANT_CI_SECRETS";
+
+/** A variable whose name matches this is taken as secret, and its value redacted. */
+export const SECRET_NAME = /TOKEN|SECRET|KEY|PASSWORD/i;
+
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+const JOBS: readonly CiJobName[] = ["plan", "apply"];
+
+/** The secrets file, read. */
+export interface CiSecrets {
+  /** Where it was read from. */
+  file: string;
+  /** Every secret, by name. */
+  values: Record<string, string>;
+  /** For a job the file names, the secrets it gets. A job missing here gets every one. */
+  jobs: Partial<Record<CiJobName, string[]>>;
+}
+
+export class CiSecretsError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CiSecretsError";
+  }
+}
+
+/**
+ * Refuse a secrets file anyone but its owner can read or write, or that
+ * belongs to another user, as ssh refuses a loose key. Not checked on
+ * Windows, whose files carry no such mode.
+ */
+export function checkCiSecretsMode(file: string): void {
+  let st: ReturnType<typeof statSync>;
+  try {
+    st = statSync(file);
+  } catch (err) {
+    throw new CiSecretsError(`the secrets file ${file} can't be read: ${(err as NodeJS.ErrnoException).code ?? String(err)}`);
+  }
+  if (!st.isFile()) throw new CiSecretsError(`the secrets file ${file} is not a file`);
+  if (process.platform === "win32") return;
+  const loose = Number(st.mode) & 0o077;
+  if (loose !== 0) {
+    const mode = (Number(st.mode) & 0o777).toString(8).padStart(4, "0");
+    throw new CiSecretsError(
+      `the secrets file ${file} has mode ${mode}, so its group or other users can ${loose & 0o044 ? "read" : "change"} it; a secrets file must be readable only by its owner, as ssh asks of a key: chmod 600 ${file}`,
+    );
+  }
+  const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+  if (uid !== undefined && Number(st.uid) !== uid) {
+    throw new CiSecretsError(`the secrets file ${file} belongs to uid ${st.uid}, not to this user (uid ${uid}); a secrets file must be its reader's own`);
+  }
+}
+
+/** A dotenv text's `NAME=value` pairs. Errors name the line, never a value. */
+export function parseDotenv(text: string, file: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  let i = 0;
+  let line = 1;
+  const fail = (why: string): never => {
+    throw new CiSecretsError(`${file}:${line}: ${why}`);
+  };
+  while (i < text.length) {
+    // One line: blank, a comment, or NAME=value.
+    const eol = text.indexOf("\n", i);
+    const rest = text.slice(i, eol === -1 ? text.length : eol);
+    const trimmed = rest.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) {
+      i = eol === -1 ? text.length : eol + 1;
+      line++;
+      continue;
+    }
+    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*/.exec(rest);
+    if (!m) fail("expected NAME=value");
+    const name = m![1]!;
+    let j = i + m![0].length;
+    const startLine = line;
+    let value = "";
+    const q = text[j];
+    if (q === '"' || q === "'") {
+      j++;
+      for (;;) {
+        if (j >= text.length) {
+          line = startLine;
+          fail(`the value of ${name} has no closing ${q}`);
+        }
+        const c = text[j]!;
+        if (c === q) break;
+        if (c === "\n") line++;
+        if (q === '"' && c === "\\" && j + 1 < text.length) {
+          const n = text[j + 1]!;
+          value += n === "n" ? "\n" : n === "r" ? "\r" : n === "t" ? "\t" : n;
+          j += 2;
+          continue;
+        }
+        value += c;
+        j++;
+      }
+      j++;
+      const end = text.indexOf("\n", j);
+      const after = text.slice(j, end === -1 ? text.length : end).trim();
+      if (after !== "" && !after.startsWith("#")) fail(`unexpected text after the quoted value of ${name}`);
+      i = end === -1 ? text.length : end + 1;
+    } else {
+      const end = text.indexOf("\n", j);
+      value = text.slice(j, end === -1 ? text.length : end).replace(/\s+#.*$/, "").trim();
+      i = end === -1 ? text.length : end + 1;
+    }
+    if (Object.prototype.hasOwnProperty.call(out, name)) fail(`${name} is set twice`);
+    out[name] = value;
+    line++;
+  }
+  return out;
+}
+
+function checkName(name: string, file: string): void {
+  if (!ENV_NAME.test(name)) throw new CiSecretsError(`${file} names a secret ${JSON.stringify(name)}, which is not a variable name`);
+  if (name === RUNNER_KEY_ENV) throw new CiSecretsError(`${file} sets ${RUNNER_KEY_ENV}, and the runner key is never passed to a job; give it to ci run or ci serve with --key or ${RUNNER_KEY_ENV}`);
+}
+
+/** The secrets in a file's text: JSON when it starts with `{`, else dotenv. */
+export function parseCiSecrets(text: string, file: string): Omit<CiSecrets, "file"> {
+  if (!text.trimStart().startsWith("{")) {
+    const values = parseDotenv(text, file);
+    for (const name of Object.keys(values)) checkName(name, file);
+    return { values, jobs: {} };
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    // The parser's message quotes the text near the error, which may be a secret.
+    throw new CiSecretsError(`${file} starts with {, and is not valid JSON`);
+  }
+  const doc = raw as Record<string, unknown>;
+  const structured = doc.secrets !== null && typeof doc.secrets === "object" && !Array.isArray(doc.secrets);
+  const map = (structured ? doc.secrets : doc) as Record<string, unknown>;
+  const values: Record<string, string> = {};
+  for (const [name, value] of Object.entries(map)) {
+    checkName(name, file);
+    if (typeof value !== "string") throw new CiSecretsError(`${file}: the secret ${name} must be a string`);
+    values[name] = value;
+  }
+  const jobs: CiSecrets["jobs"] = {};
+  if (structured) {
+    for (const key of Object.keys(doc)) if (key !== "secrets" && key !== "jobs") throw new CiSecretsError(`${file} has ${JSON.stringify(key)} beside secrets and jobs`);
+    const given = doc.jobs ?? {};
+    if (given === null || typeof given !== "object" || Array.isArray(given)) throw new CiSecretsError(`${file}: jobs must map plan and apply to lists of secret names`);
+    for (const [job, names] of Object.entries(given as Record<string, unknown>)) {
+      if (!(JOBS as readonly string[]).includes(job)) throw new CiSecretsError(`${file}: jobs names ${JSON.stringify(job)}, and the jobs are plan and apply`);
+      if (!Array.isArray(names) || names.some((n) => typeof n !== "string")) throw new CiSecretsError(`${file}: jobs.${job} must be a list of secret names`);
+      for (const n of names as string[]) if (!Object.prototype.hasOwnProperty.call(values, n)) throw new CiSecretsError(`${file}: jobs.${job} names ${n}, which the file does not set`);
+      jobs[job as CiJobName] = [...(names as string[])];
+    }
+  }
+  return { values, jobs };
+}
+
+/** Read the secrets file, refusing one others can read. */
+export function readCiSecrets(file: string): CiSecrets {
+  checkCiSecretsMode(file);
+  return { file, ...parseCiSecrets(readFileSync(file, "utf-8"), file) };
+}
+
+/** The secrets `job` gets: those `jobs` lists for it, else every one. */
+export function ciSecretsFor(secrets: CiSecrets | undefined, job: CiJobName): Record<string, string> {
+  if (!secrets) return {};
+  const names = secrets.jobs[job] ?? Object.keys(secrets.values);
+  return Object.fromEntries(names.map((n) => [n, secrets.values[n]!]));
+}
+
+/**
+ * The redactor for a job: every value in the secrets file, whether the job
+ * gets it or not, and the value of each variable in the job's environment
+ * whose name looks secret, such as `GITHUB_TOKEN` or a `--pass-env
+ * AWS_SECRET_ACCESS_KEY`. Undefined when there is nothing to redact.
+ */
+export function ciRedactor(jobEnv: Record<string, string>, secrets?: CiSecrets): Redact | undefined {
+  const values = Object.values(secrets?.values ?? {});
+  for (const [name, value] of Object.entries(jobEnv)) if (SECRET_NAME.test(name)) values.push(value);
+  return redactorOf(values);
+}