@intentius/chant 0.124.40 → 0.124.42

package/src/__fixtures__/oidc-emulator.ts

@@ -0,0 +1,118 @@
+/**
+ * A local emulator of every service the OIDC trade (#4296, ../ci-identity.ts)
+ * talks to, for tests: the forge's token request URL, AWS STS, Google's STS
+ * and IAM credentials, and Entra's token endpoint. It answers with test
+ * values only and keeps every request, so a test can say which identity
+ * was asked for and how many tokens were minted.
+ */
+
+import { createServer, type IncomingMessage, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import type { CloudTradeSpec } from "../ci-identity";
+
+/** What the emulator was asked. */
+export interface EmulatorLog {
+  /** Each OIDC token minted: its audience. */
+  minted: string[];
+  /** Each AWS role assumed, with the token it was assumed with. */
+  assumed: Array<{ role: string; token: string }>;
+  /** Each GCP service account impersonated. */
+  impersonated: string[];
+  /** Each Azure client a token was traded for, with the token. */
+  clients: Array<{ clientId: string; token: string }>;
+}
+
+export interface OidcEmulator {
+  url: string;
+  log: EmulatorLog;
+  /** The forge's token request variables, as a GitHub or Forgejo job with `id-token: write` has them. */
+  requestEnv: { ACTIONS_ID_TOKEN_REQUEST_URL: string; ACTIONS_ID_TOKEN_REQUEST_TOKEN: string };
+  /** `spec` with each cloud pointed at the emulator. */
+  pointAt(spec: CloudTradeSpec): CloudTradeSpec;
+  close(): Promise<void>;
+}
+
+/** The request token the emulator accepts, and the prefix of every token it mints. */
+export const EMULATED_REQUEST_TOKEN = "emulated-oidc-request-token-4296";
+export const EMULATED_JWT_PREFIX = "eyJemulated4296";
+
+/** The test credentials the emulator hands out for an identity: they name it, so a test can tell which was traded. */
+export function emulatedCredentials(identity: string): { accessKeyId: string; secret: string; token: string } {
+  const tag = identity.replace(/[^A-Za-z0-9]/g, "").slice(-24);
+  return { accessKeyId: `ASIATEST${tag}`, secret: `secret-${tag}`, token: `session-${tag}` };
+}
+
+const body = (req: IncomingMessage): Promise<string> =>
+  new Promise((ok) => {
+    let b = "";
+    req.on("data", (c) => (b += c));
+    req.on("end", () => ok(b));
+  });
+
+/** Start the emulator on a free local port. */
+export async function startOidcEmulator(): Promise<OidcEmulator> {
+  const log: EmulatorLog = { minted: [], assumed: [], impersonated: [], clients: [] };
+  const server: Server = createServer(async (req, res) => {
+    const url = new URL(req.url ?? "/", "http://127.0.0.1");
+    const text = await body(req);
+    const send = (status: number, payload: unknown, type = "application/json") => {
+      res.writeHead(status, { "content-type": type });
+      res.end(typeof payload === "string" ? payload : JSON.stringify(payload));
+    };
+    if (url.pathname === "/oidc") {
+      if (req.headers.authorization !== `bearer ${EMULATED_REQUEST_TOKEN}`) return send(401, { message: "bad request token" });
+      const aud = url.searchParams.get("audience") ?? "";
+      log.minted.push(aud);
+      return send(200, { value: `${EMULATED_JWT_PREFIX}.${Buffer.from(aud).toString("base64url")}.${log.minted.length}` });
+    }
+    if (url.pathname === "/aws/") {
+      const form = new URLSearchParams(text);
+      const role = form.get("RoleArn") ?? "";
+      const token = form.get("WebIdentityToken") ?? "";
+      if (form.get("Action") !== "AssumeRoleWithWebIdentity" || !token.startsWith("eyJ")) return send(400, "<Error>bad request</Error>", "text/xml");
+      log.assumed.push({ role, token });
+      const c = emulatedCredentials(role);
+      return send(
+        200,
+        `<AssumeRoleWithWebIdentityResponse><AssumeRoleWithWebIdentityResult><Credentials><AccessKeyId>${c.accessKeyId}</AccessKeyId><SecretAccessKey>${c.secret}</SecretAccessKey><SessionToken>${c.token}</SessionToken><Expiration>2026-10-22T23:00:00Z</Expiration></Credentials></AssumeRoleWithWebIdentityResult></AssumeRoleWithWebIdentityResponse>`,
+        "text/xml",
+      );
+    }
+    if (url.pathname === "/gcp-sts/v1/token") {
+      const j = JSON.parse(text) as { subjectToken?: string };
+      if (!j.subjectToken?.startsWith("eyJ")) return send(400, { error: "bad subject token" });
+      return send(200, { access_token: "federated-test-token", token_type: "Bearer" });
+    }
+    const sa = /^\/gcp-iam\/v1\/projects\/-\/serviceAccounts\/([^/:]+):generateAccessToken$/.exec(url.pathname);
+    if (sa) {
+      if (req.headers.authorization !== "Bearer federated-test-token") return send(401, { error: "bad federated token" });
+      const name = decodeURIComponent(sa[1]!);
+      log.impersonated.push(name);
+      return send(200, { accessToken: `ya29.${emulatedCredentials(name).token}`, expireTime: "2026-10-22T23:00:00Z" });
+    }
+    if (/^\/azure\/[^/]+\/oauth2\/v2\.0\/token$/.test(url.pathname)) {
+      const form = new URLSearchParams(text);
+      const clientId = form.get("client_id") ?? "";
+      const token = form.get("client_assertion") ?? "";
+      if (form.get("grant_type") !== "client_credentials" || !token.startsWith("eyJ")) return send(400, { error: "bad grant" });
+      log.clients.push({ clientId, token });
+      return send(200, { access_token: `azure.${emulatedCredentials(clientId).token}`, token_type: "Bearer" });
+    }
+    send(404, { message: `no route ${url.pathname}` });
+  });
+  await new Promise<void>((ok) => server.listen(0, "127.0.0.1", ok));
+  const url = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+  return {
+    url,
+    log,
+    requestEnv: { ACTIONS_ID_TOKEN_REQUEST_URL: `${url}/oidc?api-version=2.0`, ACTIONS_ID_TOKEN_REQUEST_TOKEN: EMULATED_REQUEST_TOKEN },
+    pointAt(spec) {
+      return {
+        ...(spec.aws ? { aws: { ...spec.aws, endpoint: `${url}/aws` } } : {}),
+        ...(spec.gcp ? { gcp: { ...spec.gcp, stsEndpoint: `${url}/gcp-sts`, iamEndpoint: `${url}/gcp-iam` } } : {}),
+        ...(spec.azure ? { azure: { ...spec.azure, authority: `${url}/azure` } } : {}),
+      };
+    },
+    close: () => new Promise<void>((ok) => server.close(() => ok())),
+  };
+}

package/src/ci-handover.test.ts

@@ -0,0 +1,209 @@
+/**
+ * #4295: the forge token handover. A step that runs the pull request's code
+ * starts again without the forge token variables, the report it writes goes
+ * to the next job as data, and the checkout keeps no credentials.
+ *
+ * Each test runs the generated shell for real, with `sh`, in a temp
+ * directory, with every token variable set to a value it then looks for.
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { gzipSync } from "node:zlib";
+import { afterAll, describe, expect, test } from "vitest";
+import {
+  CHECKOUT_TOKEN_ENV,
+  checkoutScript,
+  dropForgeTokens,
+  FORGE_TOKEN_VARS,
+  GITLAB_DROP_FORGE_TOKENS,
+  HANDOVER_LIMITS,
+  handoverKeys,
+  handoverTrap,
+  holdsForgeToken,
+  packJs,
+  UNPACK_JS,
+  withoutForgeTokens,
+} from "./ci-handover";
+
+const dirs: string[] = [];
+afterAll(() => {
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+});
+function scratch(prefix: string): string {
+  const d = mkdtempSync(join(tmpdir(), prefix));
+  dirs.push(d);
+  return d;
+}
+
+const SECRET = "ghs_handover_secret_4295";
+/** Every forge token variable, set to a value a leak would show. */
+const TOKENS = Object.fromEntries(FORGE_TOKEN_VARS.map((v) => [v, `${SECRET}_${v}`]));
+const BASE = { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: process.env.HOME ?? "/tmp" };
+
+/** Run `body` after the drop line as a script file, as a forge runs a step, and return what `env` printed in it. */
+function stepEnv(body: string, extra: Record<string, string> = {}): { env: string; status: number | null } {
+  const dir = scratch("chant-handover-step-");
+  const out = join(dir, "env.txt");
+  const file = join(dir, "step.sh");
+  writeFileSync(file, `${dropForgeTokens("sh")}\n${body.replaceAll("$OUT", out)}\n`);
+  const r = spawnSync("sh", ["-e", file], { cwd: dir, env: { ...BASE, ...TOKENS, ...extra }, encoding: "utf-8" });
+  return { env: existsSync(out) ? readFileSync(out, "utf-8") : "", status: r.status };
+}
+
+describe("a step that runs the change's code holds no forge token (#4295)", () => {
+  test("the step's shell and every process it starts see none of the token variables", () => {
+    const { env, status } = stepEnv('env > "$OUT"; sh -c \'env\' >> "$OUT"');
+    expect(status).toBe(0);
+    expect(env).not.toContain(SECRET);
+    for (const name of FORGE_TOKEN_VARS) expect(env).not.toMatch(new RegExp(`^${name}=`, "m"));
+    // It restarted once, which the marker says, so it does not loop.
+    expect(env).toMatch(/^CHANT_NO_FORGE_TOKEN=1$/m);
+  });
+
+  test.skipIf(process.platform !== "linux")("the restart leaves no token in the shell's own initial environment, which a child reads from /proc", () => {
+    const { env } = stepEnv('tr "\\0" "\\n" < /proc/$$/environ > "$OUT"; sh -c \'tr "\\0" "\\n" < /proc/$PPID/environ\' >> "$OUT"');
+    expect(env).toContain("CHANT_NO_FORGE_TOKEN=1");
+    expect(env).not.toContain(SECRET);
+  });
+
+  test("a step's exit code is its own after the restart", () => {
+    expect(stepEnv("exit 3").status).toBe(3);
+  });
+
+  test("a shell that cannot restart, such as sh -c, unsets them", () => {
+    const r = spawnSync("sh", ["-c", `${dropForgeTokens("sh")}\nenv`], { env: { ...BASE, ...TOKENS }, encoding: "utf-8" });
+    expect(r.status).toBe(0);
+    expect(r.stdout).not.toContain(SECRET);
+  });
+
+  test("bash restarts with pipefail", () => {
+    const dir = scratch("chant-handover-bash-");
+    const file = join(dir, "step.sh");
+    writeFileSync(file, `${dropForgeTokens("bash")}\nenv\n`);
+    const r = spawnSync("bash", ["-e", file], { env: { ...BASE, ...TOKENS }, encoding: "utf-8" });
+    expect(r.stdout).not.toContain(SECRET);
+    expect(r.stdout).toContain("CHANT_NO_FORGE_TOKEN=1");
+  });
+
+  test("GitLab's line unsets them for every line after it in the job's one shell", () => {
+    const r = spawnSync("sh", ["-c", `${GITLAB_DROP_FORGE_TOKENS}\nenv`], { env: { ...BASE, ...TOKENS }, encoding: "utf-8" });
+    expect(r.stdout).not.toContain(SECRET);
+  });
+
+  test("withoutForgeTokens and holdsForgeToken cover chant's, GitHub's, Forgejo's and GitLab's names", () => {
+    const env = { ...TOKENS, AWS_ACCESS_KEY_ID: "floci", GITHUB_REPOSITORY: "acme/estate" };
+    expect(withoutForgeTokens(env)).toEqual({ AWS_ACCESS_KEY_ID: "floci", GITHUB_REPOSITORY: "acme/estate" });
+    expect(holdsForgeToken(env)).toBe(true);
+    expect(holdsForgeToken({ GITHUB_TOKEN: "" })).toBe(false);
+    for (const name of ["GITHUB_TOKEN", "GH_TOKEN", "CHANT_FORGE_TOKEN", "FORGEJO_TOKEN", "GITLAB_TOKEN", "CI_JOB_TOKEN", "ACTIONS_RUNTIME_TOKEN"]) {
+      expect(FORGE_TOKEN_VARS).toContain(name);
+    }
+  });
+});
+
+/** Run the plan step's trap with `files` in its report directory, and return the outputs it wrote. */
+function handOn(files: Record<string, string>, forge: "github" | "forgejo" = "github"): string {
+  const dir = scratch("chant-handover-pack-");
+  for (const [name, body] of Object.entries(files)) {
+    mkdirSync(join(dir, ".chant/pr", name, ".."), { recursive: true });
+    writeFileSync(join(dir, ".chant/pr", name), body);
+  }
+  const output = join(dir, "github-output");
+  const file = join(dir, "step.sh");
+  writeFileSync(file, [dropForgeTokens("sh"), ...handoverTrap(".chant/pr", forge), "cd /", "exit 1", ""].join("\n"));
+  spawnSync("sh", ["-e", file], { cwd: dir, env: { ...BASE, ...TOKENS, GITHUB_OUTPUT: output }, encoding: "utf-8" });
+  return readFileSync(output, "utf-8");
+}
+
+/** What the note job writes back from `outputs`, one `key=value` a line, as toJSON hands each value in. */
+function takeBack(outputs: string, forge: "github" | "forgejo" = "github"): { dir: string; log: string } {
+  const values = Object.fromEntries(outputs.trimEnd().split("\n").map((l) => [l.slice(0, l.indexOf("=")), l.slice(l.indexOf("=") + 1)]));
+  const stdin = handoverKeys(forge).map((k) => JSON.stringify(values[k] ?? "")).join("\n") + "\n";
+  const dir = scratch("chant-handover-take-");
+  const log = execFileSync("node", ["-e", UNPACK_JS, join(dir, ".chant/pr")], { input: stdin, encoding: "utf-8" });
+  return { dir: join(dir, ".chant/pr"), log };
+}
+
+describe("the plan step hands its report to the note job as data (#4295)", () => {
+  test("every file goes on as the job's outputs, even when the step fails after changing directory, and comes back the same", () => {
+    const files = { "pr-plan.json": '{"stage":"plan"}\n', "pr-note.md": "note\n", "run-events/a.jsonl": "{}\n" };
+    const outputs = handOn(files);
+    expect(outputs).toMatch(/^report_0=/);
+    // The output carries no token, though the step started with every one.
+    expect(outputs).not.toContain(Buffer.from(SECRET).toString("base64").slice(0, 12));
+    const { dir, log } = takeBack(outputs);
+    expect(log).toContain("took 3 report files");
+    for (const [name, body] of Object.entries(files)) expect(readFileSync(join(dir, name), "utf-8")).toBe(body);
+  });
+
+  test("a path that leaves the directory is left out", () => {
+    const payload = gzipSync(JSON.stringify({ "../escape": Buffer.from("x").toString("base64"), "ok.txt": Buffer.from("y").toString("base64") })).toString("base64");
+    const { dir, log } = takeBack(`report_0=${payload}\n`);
+    expect(log).toContain('left out "../escape"');
+    expect(existsSync(join(dir, "..", "escape"))).toBe(false);
+    expect(readFileSync(join(dir, "ok.txt"), "utf-8")).toBe("y");
+  });
+
+  test("outputs that do not read hand on nothing, and the note job carries on", () => {
+    expect(takeBack("report_0=not-base64-gzip\n").log).toContain("does not read");
+    expect(takeBack("").log).toContain("handed on no report");
+  });
+
+  test("a report too large is cut to the plan report and the note", () => {
+    const saved = { ...HANDOVER_LIMITS.github };
+    HANDOVER_LIMITS.github.chunk = 2_000;
+    try {
+      expect(packJs("github")).toContain("CHUNK=2000");
+      const big = Array.from({ length: 4000 }, (_, i) => `${i}-${Math.random()}`).join("\n");
+      const { dir } = takeBack(handOn({ "pr-plan.json": "{}", "pr-note.md": "n", "change-set.json": big }));
+      expect(existsSync(join(dir, "pr-plan.json"))).toBe(true);
+      expect(existsSync(join(dir, "change-set.json"))).toBe(false);
+    } finally {
+      Object.assign(HANDOVER_LIMITS.github, saved);
+    }
+  });
+
+  test("Forgejo hands on up to four outputs of a MiB each", () => {
+    expect(handoverKeys("forgejo")).toEqual(["report_0", "report_1", "report_2", "report_3"]);
+    expect(handoverKeys("github")).toEqual(["report_0"]);
+  });
+});
+
+describe("the checkout keeps no credentials (#4295)", () => {
+  test("it checks the run's commit out with the token in the fetch's environment alone, and fetches chant/lifecycle while it can", () => {
+    const top = scratch("chant-handover-checkout-");
+    const origin = join(top, "acme", "estate");
+    const seed = join(top, "seed");
+    mkdirSync(origin, { recursive: true });
+    mkdirSync(seed);
+    const g = (cwd: string, ...args: string[]) => execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false", ...args], { cwd, encoding: "utf-8" }).trim();
+    g(origin, "init", "-q", "--bare");
+    g(seed, "init", "-q");
+    writeFileSync(join(seed, "a.txt"), "a\n");
+    g(seed, "add", "-A");
+    g(seed, "commit", "-q", "-m", "a");
+    const sha = g(seed, "rev-parse", "HEAD");
+    g(seed, "push", "-q", origin, "HEAD:refs/heads/main", "HEAD:refs/heads/chant/lifecycle", "HEAD:refs/pull/7/merge");
+
+    const work = join(top, "work");
+    mkdirSync(work);
+    const file = join(top, "checkout.sh");
+    writeFileSync(file, checkoutScript(true, true) + "\n");
+    const r = spawnSync("sh", ["-e", file], {
+      cwd: work,
+      env: { ...BASE, GIT_CONFIG_GLOBAL: join(top, "gitconfig"), [CHECKOUT_TOKEN_ENV]: SECRET, GITHUB_SERVER_URL: `file://${top}`, GITHUB_REPOSITORY: "acme/estate", GITHUB_REF: "refs/pull/7/merge", GITHUB_SHA: sha },
+      encoding: "utf-8",
+    });
+    expect(r.stderr).toBe("");
+    expect(r.status).toBe(0);
+    expect(g(work, "rev-parse", "HEAD")).toBe(sha);
+    expect(g(work, "rev-parse", "chant/lifecycle")).toBe(sha);
+    // Nothing of the token is left in the repository's config.
+    const config = readFileSync(join(work, ".git", "config"), "utf-8");
+    expect(config).not.toContain("extraheader");
+    expect(config).not.toContain(Buffer.from(`x-access-token:${SECRET}`).toString("base64"));
+  });
+});

package/src/ci-handover.ts

@@ -0,0 +1,237 @@
+/**
+ * The forge token handover (#4295): no step that runs a pull request's code
+ * holds a forge token.
+ *
+ * A pull request's plan runs its code: the synth of its components, the
+ * plans their capabilities run, its build and lint, and its hooks. A token
+ * that can post a note or set a status can also push, so the generated plan
+ * job uses the job's token for the checkout's fetches alone and drops it
+ * before anything else runs. The ordering is terragucci's `handover.ts`
+ * (INTENTIUS/terragucci e6cb431, packages/terragucci/src/handover.ts):
+ *
+ * 1. The checkout is a script ({@link checkoutScript}), not actions/checkout,
+ *    whose post step runs at the job's end with the token as its input. The
+ *    token reaches its fetches through the environment, never the git config.
+ * 2. Every later step starts again without the token variables
+ *    ({@link dropForgeTokens}).
+ * 3. The plan step is the job's last. A step after it would start beside
+ *    whatever the change's code left running, with what it wrote to
+ *    GITHUB_ENV and GITHUB_PATH. So the plan step hands its report directory
+ *    on as the job's outputs ({@link handoverTrap}) in place of an artifact
+ *    upload.
+ * 4. A fresh job, `plan-note`, checks out the target branch's commit, takes
+ *    the report back ({@link takeOverScript}), keeps it as the artifact, and
+ *    posts the note and the status with the token (`chant components
+ *    pr-post`, ./pr-post.ts). It reads the report as data.
+ *
+ * `chant ci run plan` keeps the same rule: no step of the plan job gets a
+ * forge token, and the runner posts from the report once the steps settle
+ * (../workspace/ci-run.ts).
+ */
+
+import type { ForgeKind } from "./pr-forge";
+
+/**
+ * The variables a runner, a job or a secret may hold a forge token in.
+ * A step that runs the change's code starts without them. The list is
+ * terragucci's `STEP_TOKEN_VARS` (render.ts:1787) with chant's own names
+ * (`FORGE_TOKEN_ENV` in ./pr-forge.ts) and GitLab's added.
+ */
+export const FORGE_TOKEN_VARS = [
+  "CHANT_FORGE_TOKEN",
+  "CHANT_GITHUB_TOKEN",
+  "CHANT_FORGEJO_TOKEN",
+  "CHANT_GITLAB_TOKEN",
+  "CHANT_CHECKOUT_TOKEN",
+  "GITHUB_TOKEN",
+  "GH_TOKEN",
+  "FORGEJO_TOKEN",
+  "GITEA_TOKEN",
+  "GITLAB_TOKEN",
+  "CI_JOB_TOKEN",
+  "ACTIONS_RUNTIME_TOKEN",
+] as const;
+
+/** `env` without {@link FORGE_TOKEN_VARS}. */
+export function withoutForgeTokens<T extends Record<string, string | undefined>>(env: T): T {
+  const out = { ...env };
+  for (const name of FORGE_TOKEN_VARS) delete out[name];
+  return out;
+}
+
+/** Whether `env` holds a forge token under one of {@link FORGE_TOKEN_VARS}. */
+export function holdsForgeToken(env: Record<string, string | undefined>): boolean {
+  return FORGE_TOKEN_VARS.some((name) => (env[name] ?? "") !== "");
+}
+
+/** The marker a step {@link dropForgeTokens} restarted carries. */
+export const NO_FORGE_TOKEN_MARKER = "CHANT_NO_FORGE_TOKEN";
+
+/**
+ * The first line of a step that runs the change's code: restart the step's
+ * shell once without the token variables in its process environment, or,
+ * when it cannot restart, unset them. Unsetting alone leaves the values in
+ * the shell's own initial environment, which a child reads on Linux from
+ * `/proc/<pid>/environ`; the restart replaces it. A forge runs a step's
+ * script as a file (`sh -e {0}` in a GitHub or Forgejo container job), so
+ * `$0` is that file. terragucci's `restartWithout` (render.ts:1826).
+ */
+export function dropForgeTokens(shell: "sh" | "bash" = "sh", extra: readonly string[] = []): string {
+  const again = shell === "bash" ? 'bash --noprofile --norc -e -o pipefail "$0"' : 'sh -e "$0"';
+  const marker = NO_FORGE_TOKEN_MARKER;
+  // #4296: a plan job that traded its OIDC token drops the variables a token is requested with too.
+  const vars = [...FORGE_TOKEN_VARS, ...extra];
+  const can = `[ -z "\${${marker}:-}" ] && [ "\${0#*/}" != "$0" ] && [ -f "$0" ] && ! { [ "\${0##*/}" = sh ] || [ "\${0##*/}" = bash ] || [ "\${0##*/}" = dash ]; } && command -v env >/dev/null 2>&1 && command -v ${shell} >/dev/null 2>&1`;
+  return `if ${can}; then exec env ${vars.map((v) => `-u ${v}`).join(" ")} ${marker}=1 ${again}; fi; unset ${vars.join(" ")}`;
+}
+
+/** The line a GitLab plan job starts its script with: GitLab runs the script in one shell, so the unset holds for every line after it. */
+export const GITLAB_DROP_FORGE_TOKENS = `unset ${FORGE_TOKEN_VARS.join(" ")}`;
+
+/** The forges whose plan job hands its report on through job outputs. GitLab passes the artifact to the next job itself. */
+export type HandoverForge = Exclude<ForgeKind, "gitlab">;
+
+/**
+ * How many outputs the plan job hands its report on in, and the most
+ * characters each holds. Forgejo keeps each output's value to 1 MiB. GitHub
+ * keeps a job's outputs to 1 MB together, sized as UTF-16. terragucci's
+ * `HANDOVER_LIMITS` (handover.ts).
+ */
+export const HANDOVER_LIMITS: Record<HandoverForge, { chunk: number; parts: number }> = {
+  forgejo: { chunk: 1_000_000, parts: 4 },
+  github: { chunk: 450_000, parts: 1 },
+};
+
+/** The outputs' names on a forge: report_0, report_1, ... */
+export function handoverKeys(forge: HandoverForge): string[] {
+  return Array.from({ length: HANDOVER_LIMITS[forge].parts }, (_, i) => `report_${i}`);
+}
+
+/** The files the note job reads, which a report too large to hand on whole is cut to. */
+export const HANDOVER_NOTE_FILES = ["pr-plan.json", "pr-note.md"] as const;
+
+/**
+ * Packs the report directory (argv 1) into the step's output file (argv 2):
+ * every regular file, found without following a link, as gzipped JSON in
+ * base64, cut into the forge's chunks. A report too large is cut to
+ * {@link HANDOVER_NOTE_FILES}, and to none when even those are too large.
+ */
+export function packJs(forge: HandoverForge): string {
+  const { chunk, parts } = HANDOVER_LIMITS[forge];
+  return [
+    'const fs=require("fs"),p=require("path"),z=require("zlib");',
+    "const [dir,out]=process.argv.slice(1);",
+    `const CHUNK=${chunk},PARTS=${parts},NOTE=${JSON.stringify(HANDOVER_NOTE_FILES)};`,
+    "const all={};",
+    'const walk=(d,r)=>{let n=[];try{n=fs.readdirSync(d).sort()}catch{return}for(const x of n){const f=p.join(d,x),k=r?r+"/"+x:x;let s;try{s=fs.lstatSync(f)}catch{continue}if(s.isDirectory())walk(f,k);else if(s.isFile())all[k]=fs.readFileSync(f).toString("base64")}};',
+    'walk(dir,"");',
+    'const pack=(o)=>z.gzipSync(JSON.stringify(o)).toString("base64");',
+    "let b=pack(all);",
+    "if(b.length>CHUNK*PARTS){b=pack(Object.fromEntries(Object.entries(all).filter(([k])=>NOTE.includes(k))));",
+    'if(b.length>CHUNK*PARTS){b=pack({});console.error("chant: the plan report is too large to hand to the note job, even cut to the report and the note; it hands on none of it")}',
+    'else console.error("chant: the plan report is too large to hand to the note job whole; it hands on pr-plan.json and pr-note.md")}',
+    'let o="";for(let i=0;i*CHUNK<b.length;i++)o+="report_"+i+"="+b.slice(i*CHUNK,(i+1)*CHUNK)+"\\n";',
+    "fs.appendFileSync(out,o);",
+  ].join("");
+}
+
+/**
+ * Writes back, under the directory argv 1 names, the files the plan job
+ * handed on: stdin holds its outputs, one JSON string a line. A path is kept
+ * only when it is plain segments (no empty one, no `.` or `..`, no backslash
+ * or control character), so nothing lands outside the directory.
+ */
+export const UNPACK_JS = [
+  'const fs=require("fs"),p=require("path"),z=require("zlib");',
+  "const dir=process.argv[1];",
+  'let b="";',
+  'for(const l of fs.readFileSync(0,"utf8").split("\\n")){if(!l.trim())continue;let s="";try{s=JSON.parse(l)}catch{}if(typeof s==="string")b+=s}',
+  'if(!b){console.log("chant: the plan job handed on no report");process.exit(0)}',
+  'let files;try{files=JSON.parse(z.gunzipSync(Buffer.from(b,"base64"),{maxOutputLength:268435456}).toString("utf8"))}catch(e){console.log("chant: the report the plan job handed on does not read: "+e.message);process.exit(0)}',
+  'if(!files||typeof files!=="object"||Array.isArray(files)){console.log("chant: the report the plan job handed on is not a set of files");process.exit(0)}',
+  "let n=0;",
+  'for(const [k,v] of Object.entries(files)){const parts=k.split("/");',
+  'if(typeof v!=="string"||k.length>1024||parts.some((x)=>!x||x==="."||x===".."||/[\\\\\\x00-\\x1f]/.test(x))){console.log("chant: left out "+JSON.stringify(k));continue}',
+  'try{const f=p.join(dir,...parts);fs.mkdirSync(p.dirname(f),{recursive:true});fs.writeFileSync(f,Buffer.from(v,"base64"));n++}catch(e){console.log("chant: could not write "+JSON.stringify(k)+": "+e.message)}}',
+  'console.log("chant: took "+n+" report files from the plan job")',
+].join("");
+
+/**
+ * The lines of the plan step, after {@link dropForgeTokens}: when the step
+ * ends, however it ends, its report directory (`dir`, from the directory the
+ * step starts in) goes into the step's outputs.
+ */
+export function handoverTrap(dir: string, forge: HandoverForge): string[] {
+  return [
+    `chant_report="$PWD/${dir}"`,
+    `chant_handover() { node -e '${packJs(forge)}' "$chant_report" "\${GITHUB_OUTPUT:-/dev/null}" || echo "chant: the plan report could not be handed to the note job" >&2; }`,
+    "trap chant_handover EXIT",
+  ];
+}
+
+/** A job's outputs that carry the report its step `step` handed on. */
+export function handoverOutputs(step: string, forge: HandoverForge): Record<string, string> {
+  return Object.fromEntries(handoverKeys(forge).map((k) => [k, `\${{ steps.${step}.outputs.${k} }}`]));
+}
+
+/**
+ * The script of the step that takes the report job `job` handed on into
+ * `dir`. Each output comes in as toJSON's string, one line of a quoted
+ * heredoc whose end no JSON string can be, so the change's outputs stay data.
+ */
+export function takeOverScript(job: string, dir: string, forge: HandoverForge): string {
+  return [
+    "set -u",
+    `node -e '${UNPACK_JS}' ${dir} <<'END_OF_REPORT'`,
+    ...handoverKeys(forge).map((k) => `\${{ toJSON(needs.${job}.outputs.${k}) }}`),
+    "END_OF_REPORT",
+  ].join("\n");
+}
+
+/** The variable the checkout script reads the job's token from. */
+export const CHECKOUT_TOKEN_ENV = "CHANT_CHECKOUT_TOKEN";
+
+/**
+ * Checks the run's commit out with git, as actions/checkout does without
+ * credentials kept: `GITHUB_SHA` under `GITHUB_REF`. With `history`, every
+ * branch and tag too, since the plan measures the change with git. The job's
+ * token ({@link CHECKOUT_TOKEN_ENV}) reaches the fetches alone, through the
+ * environment, never the git config. A workspace already checked out is
+ * cleaned first, as actions/checkout does. terragucci's `checkoutScript`
+ * (handover.ts). With `ledger`, the `chant/lifecycle` branch is fetched
+ * into a local branch too, while the token is there: the plan reads the
+ * gate ledger from it, and a later fetch without the token cannot reach a
+ * private repository (`requireLifecycleLedger` in ./lifecycle/git.ts reads
+ * the local branch when the fetch fails).
+ */
+export function checkoutScript(history: boolean, ledger = false): string {
+  const fetchLine = history
+    ? `git -c protocol.version=2 fetch -q --prune --no-recurse-submodules origin '+refs/heads/*:refs/remotes/origin/*' '+refs/tags/*:refs/tags/*' "+$want:$target"`
+    : 'git -c protocol.version=2 fetch -q --no-tags --prune --no-recurse-submodules --depth=1 origin "+$want:$target"';
+  return [
+    "set -eu",
+    'git config --global --add safe.directory "$PWD" 2>/dev/null || true',
+    "[ -d .git ] || git init -q .",
+    'git remote get-url origin >/dev/null 2>&1 || git remote add origin "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY"',
+    `if [ -n "\${${CHECKOUT_TOKEN_ENV}:-}" ]; then`,
+    `  chant_auth="$(printf 'x-access-token:%s' "$${CHECKOUT_TOKEN_ENV}" | base64 | tr -d '\\n')"`,
+    '  export GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=http.extraheader GIT_CONFIG_VALUE_0="AUTHORIZATION: basic $chant_auth"',
+    "  unset chant_auth",
+    "fi",
+    'ref="$GITHUB_REF"',
+    'want="$GITHUB_SHA"',
+    'case "$ref" in',
+    '  refs/heads/*) target="refs/remotes/origin/${ref#refs/heads/}" ;;',
+    '  refs/tags/*) target="$ref" ;;',
+    '  refs/*) target="refs/remotes/${ref#refs/}" ;;',
+    '  *) target="refs/remotes/origin/chant-head" ;;',
+    "esac",
+    "if git rev-parse -q --verify HEAD >/dev/null; then git clean -ffdxq; fi",
+    fetchLine,
+    ...(ledger ? ["git -c protocol.version=2 fetch -q --no-tags origin '+refs/heads/chant/lifecycle:refs/heads/chant/lifecycle' 2>/dev/null || true"] : []),
+    'case "$ref" in',
+    '  refs/heads/*) git checkout -q --force -B "${ref#refs/heads/}" "$target" ;;',
+    '  *) git checkout -q --force --detach "$target" ;;',
+    "esac",
+  ].join("\n");
+}