@intentius/chant 0.124.39 → 0.124.41

package/src/gate-policy.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, test } from "vitest";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  assertGatePolicySettings,
+  checkGatePolicy,
+  conftestFindings,
+  exportGatePolicy,
+  gatePolicyArgv,
+  opaFindings,
+  type GatePolicyExec,
+  type GatePolicyTree,
+} from "./gate-policy";
+
+/** conftest's JSON for one input: a deny with its query, an older deny without one, and a warning. */
+const CONFTEST_DENY = JSON.stringify([
+  {
+    filename: "input.json",
+    namespace: "main",
+    successes: 2,
+    failures: [
+      { msg: "bucket logs is public", metadata: { query: "data.main.deny_public_bucket" } },
+      { msg: { msg: "no owner tag" } },
+    ],
+    warnings: [{ msg: "the plan deletes 3 resources" }],
+  },
+]);
+
+const opa = (value: unknown): string => JSON.stringify({ result: [{ expressions: [{ value, text: "data.main", location: { row: 1, col: 1 } }] }] });
+
+describe("reading the engine's answer (#4294)", () => {
+  test("conftest: failures deny by their query, warnings are advice", () => {
+    expect(conftestFindings(CONFTEST_DENY)).toEqual({
+      denials: [
+        { rule: "main.deny_public_bucket", message: "bucket logs is public" },
+        { rule: "main.deny", message: "no owner tag" },
+      ],
+      holds: [],
+      warnings: ["the plan deletes 3 resources"],
+    });
+    expect(conftestFindings(JSON.stringify([{ filename: "input.json", namespace: "main", successes: 1 }]))).toEqual({ denials: [], holds: [], warnings: [] });
+    expect(conftestFindings("not json")).toBeUndefined();
+    expect(conftestFindings(JSON.stringify({ result: [] }))).toBeUndefined();
+  });
+
+  test("opa: deny, violation, hold and warn rules by name; a child package one level down; allow_unattended is no rule", () => {
+    const found = opaFindings(
+      opa({
+        deny: ["public bucket"],
+        violation_size: "too many deletes",
+        hold_iam: ["an IAM role changes"],
+        hold: true,
+        warn: ["consider tags"],
+        allow_unattended: true,
+        allow_unattended_docs: ["docs only"],
+        other: 3,
+        aws: { deny_region: ["us-west-1 is not allowed"] },
+      }),
+    );
+    expect(found).toEqual({
+      denials: [
+        { rule: "main.aws.deny_region", message: "us-west-1 is not allowed" },
+        { rule: "main.deny", message: "public bucket" },
+        { rule: "main.violation_size", message: "too many deletes" },
+      ],
+      holds: [
+        { rule: "main.hold", message: "hold" },
+        { rule: "main.hold_iam", message: "an IAM role changes" },
+      ],
+      warnings: ["consider tags"],
+    });
+  });
+
+  test("opa: an undefined query matches nothing, an array is a deny set, errors and other shapes are no answer", () => {
+    expect(opaFindings(JSON.stringify({}))).toEqual({ denials: [], holds: [], warnings: [] });
+    expect(opaFindings(opa(["a", { msg: "b" }]), "policy.deny")).toEqual({ denials: [{ rule: "policy.deny", message: "a" }, { rule: "policy.deny", message: "b" }], holds: [], warnings: [] });
+    expect(opaFindings(JSON.stringify({ errors: [{ message: "rego_parse_error" }] }))).toBeUndefined();
+    expect(opaFindings(opa(7))).toBeUndefined();
+    expect(opaFindings("{")).toBeUndefined();
+  });
+});
+
+describe("running the engine (#4294)", () => {
+  const fake = (out: { status: number | null; stdout?: string; stderr?: string }, seen: string[][] = []): GatePolicyExec => (argv) => {
+    seen.push(argv);
+    return { status: out.status, stdout: out.stdout ?? "", stderr: out.stderr ?? "" };
+  };
+
+  test("the engines' own argv, and a command's placeholders filled", () => {
+    expect(gatePolicyArgv({}, { policy: "/p", input: "/i.json" })).toEqual(["conftest", "test", "--no-color", "--output", "json", "--policy", "/p", "--all-namespaces", "/i.json"]);
+    expect(gatePolicyArgv({ engine: "conftest", namespace: "infra" }, { policy: "/p", input: "/i.json" })).toContain("--namespace");
+    expect(gatePolicyArgv({ engine: "opa" }, { policy: "/p", input: "/i.json" })).toEqual(["opa", "eval", "--format", "json", "--data", "/p", "--input", "/i.json", "data.main"]);
+    expect(gatePolicyArgv({ engine: "opa", command: ["./bin/check", "--rules={policy}", "{input}"] }, { policy: "/p", input: "/i.json" })).toEqual(["./bin/check", "--rules=/p", "/i.json"]);
+  });
+
+  test("the input is written to the file the engine reads, and a denial is a verdict with its sorted rules", () => {
+    let input: unknown;
+    const exec: GatePolicyExec = (argv) => {
+      input = JSON.parse(readFileSync(argv[argv.length - 1]!, "utf-8"));
+      return { status: 1, stdout: CONFTEST_DENY, stderr: "" };
+    };
+    const verdict = checkGatePolicy({ settings: {}, input: { changeSet: { entries: [] } }, policyDir: "/p", exec });
+    expect(input).toEqual({ changeSet: { entries: [] } });
+    expect(verdict).toMatchObject({ result: "denied", engine: "conftest", rules: ["main.deny", "main.deny_public_bucket"], warnings: ["the plan deletes 3 resources"] });
+  });
+
+  test("a hold with no denial is held; nothing is passed", () => {
+    expect(checkGatePolicy({ settings: { engine: "opa" }, input: {}, policyDir: "/p", exec: fake({ status: 0, stdout: opa({ hold_iam: ["iam"] }) }) })).toMatchObject({ result: "held", holds: [{ rule: "main.hold_iam" }] });
+    expect(checkGatePolicy({ settings: { engine: "opa" }, input: {}, policyDir: "/p", exec: fake({ status: 0, stdout: opa({ deny: [], warn: [] }) }) })).toMatchObject({ result: "passed", denials: [], holds: [] });
+    expect(checkGatePolicy({ settings: { engine: "opa" }, input: {}, policyDir: "/p", exec: fake({ status: 0, stdout: opa({ deny: ["x"], hold: true }) }) }).result).toBe("denied");
+  });
+
+  test("an engine that does not start, prints no result or fails without a denial is an error", () => {
+    expect(checkGatePolicy({ settings: {}, input: {}, policyDir: "/p", exec: fake({ status: null, stderr: "spawn conftest ENOENT" }) })).toMatchObject({ result: "error", error: expect.stringContaining("did not run") });
+    expect(checkGatePolicy({ settings: {}, input: {}, policyDir: "/p", exec: fake({ status: 2, stdout: "Error: rego_parse_error" }) })).toMatchObject({ result: "error", error: expect.stringContaining("gave no conftest result") });
+    expect(checkGatePolicy({ settings: {}, input: {}, policyDir: "/p", exec: fake({ status: 2, stdout: "[]", stderr: "could not load policy" }) })).toMatchObject({ result: "error", error: expect.stringContaining("exited 2") });
+  });
+});
+
+describe("the policy at base (#4294)", () => {
+  const files: Record<string, string> = { "policy/main.rego": "package main\n", "policy/lib/util.rego": "package lib\n", "src/app.ts": "" };
+  const tree: GatePolicyTree = {
+    stat: (p) => (files[p] !== undefined ? "file" : Object.keys(files).some((f) => f.startsWith(`${p}/`)) ? "dir" : undefined),
+    list: (p) => {
+      const names = new Map<string, "file" | "dir">();
+      for (const f of Object.keys(files).filter((f) => f.startsWith(`${p}/`))) {
+        const rest = f.slice(p.length + 1).split("/");
+        names.set(rest[0]!, rest.length > 1 ? "dir" : "file");
+      }
+      return names.size ? [...names].map(([name, type]) => ({ name, type })) : undefined;
+    },
+    read: (p) => files[p]!,
+  };
+
+  test("the directory is copied out of the tree, and removed again", () => {
+    const out = exportGatePolicy(tree, "./policy/");
+    if ("error" in out) throw new Error(out.error);
+    expect(readFileSync(join(out.dir, "main.rego"), "utf-8")).toBe("package main\n");
+    expect(readFileSync(join(out.dir, "lib", "util.rego"), "utf-8")).toBe("package lib\n");
+    expect(existsSync(join(out.dir, "app.ts"))).toBe(false);
+    out.cleanup();
+    expect(existsSync(out.dir)).toBe(false);
+  });
+
+  test("a directory the base does not have is an error", () => {
+    expect(exportGatePolicy(tree, "rules")).toEqual({ error: "the policy directory rules does not exist at base" });
+  });
+});
+
+describe("ci.policy settings (#4294)", () => {
+  test("the four settings are read, and an unattended outcome is refused", () => {
+    expect(() => assertGatePolicySettings("ci.policy", { engine: "opa", path: "policy", namespace: "main", command: ["opa", "eval", "{input}"] })).not.toThrow();
+    expect(() => assertGatePolicySettings("ci.policy", {})).not.toThrow();
+    expect(() => assertGatePolicySettings("ci.policy", { engine: "sentinel" })).toThrow(/conftest or opa/);
+    expect(() => assertGatePolicySettings("ci.policy", { path: "../elsewhere" })).toThrow(/inside the workspace/);
+    expect(() => assertGatePolicySettings("ci.policy", { command: ["check"] })).toThrow(/\{input\}/);
+    expect(() => assertGatePolicySettings("ci.policy", { outcomes: ["deny", "allow_unattended"] })).toThrow(/no unattended outcome/);
+    expect(() => assertGatePolicySettings("ci.policy", { allow_unattended: true })).toThrow(/no unattended outcome/);
+    expect(() => assertGatePolicySettings("ci.policy", { rules: [] })).toThrow(/not a setting/);
+    expect(() => assertGatePolicySettings("ci.policy", [])).toThrow(/must be/);
+  });
+});

package/src/gate-policy.ts

@@ -0,0 +1,298 @@
+/**
+ * Gate-time policy (#4294): a policy engine run over a plan's change set,
+ * with the policy read at base, whose rules deny a plan or hold it for a
+ * person.
+ *
+ * The engine is any command that prints conftest's JSON result
+ * (`conftest test --output json`) or OPA's (`opa eval --format json`). The
+ * rules are counted as conftest counts them:
+ *
+ * - `deny`, `violation`, `deny_<name>` and `violation_<name>` deny the plan.
+ *   A denied plan applies only under an override that counts
+ *   (`./override-gate.ts`), on top of the gate's own approval.
+ * - `hold` and `hold_<name>` hold the plan: it waits for a person's approval
+ *   of its digest, even where the gate would let it through without one.
+ *   conftest runs only deny and warn rules, so a hold needs the opa shape.
+ * - `warn` and `warn_<name>` are advice. They fail nothing.
+ *
+ * There is no outcome that lets a plan apply with nobody approving it: a
+ * non-empty change set always waits for a person (ws-104, ws-080). A rule
+ * named `allow_unattended` is read as no rule at all.
+ *
+ * A policy that cannot run, or gives no answer this module can read, is an
+ * error, and the caller stops the apply: no path waives a policy.
+ *
+ * Like `./override-gate.ts` this module reads what it is handed and imports
+ * only node built-ins, so a product can bundle it into one file
+ * (`gate-policy-bundle.test.ts`). The pull-request jobs' use of it is in
+ * `./components/pr-policy.ts`.
+ */
+
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/** The result shapes chant reads: conftest's and OPA's. */
+export const GATE_POLICY_ENGINES = ["conftest", "opa"] as const;
+export type GatePolicyEngine = (typeof GATE_POLICY_ENGINES)[number];
+
+/** Where the policy is read when the settings name no `path`. */
+export const DEFAULT_POLICY_PATH = "policy";
+
+/** The settings of one policy step, read at base. */
+export interface GatePolicySettings {
+  /** The result shape, and the default command. Default `conftest`. */
+  engine?: GatePolicyEngine;
+  /** The policy directory, relative to the declaration at base. Default {@link DEFAULT_POLICY_PATH}. */
+  path?: string;
+  /** The package to read. conftest default: every namespace. opa default: `main`. */
+  namespace?: string;
+  /**
+   * The command to run instead of the engine's own, as argv. `{policy}` is
+   * the policy directory exported from base and `{input}` the input file. It
+   * prints the result shape `engine` names.
+   */
+  command?: string[];
+}
+
+/** A rule that matched, and what it said. */
+export interface GatePolicyFinding {
+  /** `<package>.<rule>`, such as `main.deny_public_bucket`. */
+  rule: string;
+  message: string;
+}
+
+/** What an engine's answer holds. */
+export interface GatePolicyFindings {
+  denials: GatePolicyFinding[];
+  holds: GatePolicyFinding[];
+  warnings: string[];
+}
+
+/**
+ * One policy check's outcome. `denied` wins over `held`. `error`: the
+ * policy did not run or gave no readable answer, and the apply stops.
+ */
+export interface GatePolicyVerdict {
+  result: "passed" | "denied" | "held" | "error";
+  engine: GatePolicyEngine;
+  denials: GatePolicyFinding[];
+  /** The ids of the rules that denied, sorted, each once: what an override names. */
+  rules: string[];
+  holds: GatePolicyFinding[];
+  warnings: string[];
+  error?: string;
+}
+
+export const DENY_RULE = /^(deny|violation)(_[A-Za-z0-9]+)*$/;
+export const WARN_RULE = /^warn(_[A-Za-z0-9]+)*$/;
+export const HOLD_RULE = /^hold(_[A-Za-z0-9]+)*$/;
+
+const ruleId = (query: string): string => query.replace(/^data\./, "");
+
+function messageOf(v: unknown): string {
+  if (typeof v === "string") return v;
+  if (v !== null && typeof v === "object" && typeof (v as { msg?: unknown }).msg === "string") return (v as { msg: string }).msg;
+  return JSON.stringify(v);
+}
+
+/** The findings in `conftest test --output json`. Undefined when it is not that shape. */
+export function conftestFindings(stdout: string): GatePolicyFindings | undefined {
+  let results: unknown;
+  try {
+    results = JSON.parse(stdout);
+  } catch {
+    return undefined;
+  }
+  if (!Array.isArray(results)) return undefined;
+  const out: GatePolicyFindings = { denials: [], holds: [], warnings: [] };
+  for (const r of results as Array<{ namespace?: string; failures?: Array<{ msg?: unknown; metadata?: { query?: unknown } }>; warnings?: Array<{ msg?: unknown }> }>) {
+    if (r === null || typeof r !== "object") return undefined;
+    for (const f of r.failures ?? []) {
+      // conftest names the query that denied in the failure's metadata; an older one gives only the namespace.
+      const rule = typeof f.metadata?.query === "string" ? ruleId(f.metadata.query) : `${r.namespace ?? "main"}.deny`;
+      out.denials.push({ rule, message: messageOf(f.msg) });
+    }
+    for (const w of r.warnings ?? []) out.warnings.push(messageOf(w.msg));
+  }
+  return out;
+}
+
+/** The rules of one package's value, and with `nested` its child packages one level down. */
+function packageFindings(doc: Record<string, unknown>, out: GatePolicyFindings, pkg: string, nested: boolean): void {
+  for (const [name, value] of Object.entries(doc).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+    // A rule matches when its value is true, a message, or a non-empty set of messages.
+    const said = Array.isArray(value) ? value.map(messageOf) : value === true ? [name] : typeof value === "string" && value !== "" ? [value] : [];
+    if (DENY_RULE.test(name)) {
+      for (const message of said) out.denials.push({ rule: `${pkg}.${name}`, message });
+    } else if (HOLD_RULE.test(name)) {
+      for (const message of said) out.holds.push({ rule: `${pkg}.${name}`, message });
+    } else if (WARN_RULE.test(name)) {
+      out.warnings.push(...said);
+    } else if (nested && value !== null && typeof value === "object" && !Array.isArray(value)) {
+      packageFindings(value as Record<string, unknown>, out, `${pkg}.${name}`, false);
+    }
+  }
+}
+
+/**
+ * The findings in `opa eval --format json data.<namespace>`. The query's
+ * value is the package: its rules are read by name. An array value is a
+ * deny set named after the query. A query that is undefined has no rule
+ * that matched. Undefined when the output is not that shape.
+ */
+export function opaFindings(stdout: string, namespace = "main"): GatePolicyFindings | undefined {
+  let parsed: { result?: Array<{ expressions?: Array<{ value?: unknown }> }>; errors?: unknown };
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed) || parsed.errors !== undefined) return undefined;
+  const value = parsed.result?.[0]?.expressions?.[0]?.value;
+  const out: GatePolicyFindings = { denials: [], holds: [], warnings: [] };
+  if (value === undefined) return out;
+  if (Array.isArray(value)) {
+    out.denials.push(...value.map((v) => ({ rule: namespace, message: messageOf(v) })));
+    return out;
+  }
+  if (value === null || typeof value !== "object") return undefined;
+  packageFindings(value as Record<string, unknown>, out, namespace, true);
+  return out;
+}
+
+/** A verdict from what the engine found. */
+export function gatePolicyVerdict(engine: GatePolicyEngine, found: GatePolicyFindings): GatePolicyVerdict {
+  const rules = [...new Set(found.denials.map((d) => d.rule))].sort();
+  return {
+    result: found.denials.length > 0 ? "denied" : found.holds.length > 0 ? "held" : "passed",
+    engine,
+    denials: found.denials,
+    rules,
+    holds: found.holds,
+    warnings: found.warnings,
+  };
+}
+
+const errorVerdict = (engine: GatePolicyEngine, error: string): GatePolicyVerdict => ({ result: "error", engine, denials: [], rules: [], holds: [], warnings: [], error });
+
+/** The argv one check runs: the settings' `command` with its placeholders filled, or the engine's own. */
+export function gatePolicyArgv(settings: GatePolicySettings, at: { policy: string; input: string }): string[] {
+  if (settings.command) return settings.command.map((a) => a.replaceAll("{policy}", at.policy).replaceAll("{input}", at.input));
+  if ((settings.engine ?? "conftest") === "opa") {
+    return ["opa", "eval", "--format", "json", "--data", at.policy, "--input", at.input, `data.${settings.namespace ?? "main"}`];
+  }
+  return ["conftest", "test", "--no-color", "--output", "json", "--policy", at.policy, ...(settings.namespace ? ["--namespace", settings.namespace] : ["--all-namespaces"]), at.input];
+}
+
+/** What one run of the engine printed and how it exited. `status` is null when it did not start. */
+export interface GatePolicyRun {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+export type GatePolicyExec = (argv: string[], cwd: string) => GatePolicyRun;
+
+/** Runs the engine with the job's environment. */
+export const defaultGatePolicyExec: GatePolicyExec = (argv, cwd) => {
+  const r = spawnSync(argv[0]!, argv.slice(1), { cwd, encoding: "utf-8", maxBuffer: 64 * 1024 * 1024 });
+  return { status: r.error ? null : r.status, stdout: r.stdout ?? "", stderr: `${r.stderr ?? ""}${r.error ? r.error.message : ""}` };
+};
+
+export interface CheckGatePolicyOptions {
+  settings: GatePolicySettings;
+  /** The input document, or its JSON text. */
+  input: unknown;
+  /** The policy directory, already exported from base. */
+  policyDir: string;
+  /** Where the engine runs. Default the policy directory. */
+  cwd?: string;
+  exec?: GatePolicyExec;
+}
+
+const tail = (text: string): string => text.trim().split("\n").slice(-3).join(" ");
+
+/** Run the engine once over `input` and read its answer. */
+export function checkGatePolicy(options: CheckGatePolicyOptions): GatePolicyVerdict {
+  const { settings } = options;
+  const engine = settings.engine ?? "conftest";
+  const work = mkdtempSync(join(tmpdir(), "chant-policy-input-"));
+  try {
+    const file = join(work, "input.json");
+    writeFileSync(file, typeof options.input === "string" ? options.input : JSON.stringify(options.input));
+    const argv = gatePolicyArgv(settings, { policy: options.policyDir, input: file });
+    const r = (options.exec ?? defaultGatePolicyExec)(argv, options.cwd ?? options.policyDir);
+    if (r.status === null) return errorVerdict(engine, `${argv[0]} did not run: ${tail(r.stderr) || "no such command"}`);
+    const found = engine === "opa" ? opaFindings(r.stdout, settings.namespace ?? "main") : conftestFindings(r.stdout);
+    if (found === undefined) return errorVerdict(engine, `${argv[0]} gave no ${engine} result (exit ${r.status}): ${tail(r.stderr || r.stdout)}`);
+    // conftest exits 1 on a denial and 2 or more when it could not run; opa exits 0 on a query it ran.
+    if (found.denials.length === 0 && r.status !== 0) return errorVerdict(engine, `${argv[0]} exited ${r.status}: ${tail(r.stderr)}`);
+    return gatePolicyVerdict(engine, found);
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+/** The part of a tree a policy is exported from: a workspace tree at base fits. */
+export interface GatePolicyTree {
+  stat(path: string): "file" | "dir" | undefined;
+  list(path: string): Array<{ name: string; type: "file" | "dir" }> | undefined;
+  read(path: string): string;
+  bytes?(path: string): Uint8Array;
+}
+
+/**
+ * Copy the policy directory `path` out of `tree` (the tree at base) into a
+ * new temporary directory, so the engine reads the policy as the base has
+ * it and never the change's copy. Returns the directory and how to remove
+ * it, or the reason there is no policy to read.
+ */
+export function exportGatePolicy(tree: GatePolicyTree, path: string): { dir: string; cleanup: () => void } | { error: string } {
+  const root = path.replace(/^\.\/+/, "").replace(/\/+$/, "");
+  const kind = root === "" || root === "." ? "dir" : tree.stat(root);
+  if (kind === undefined) return { error: `the policy directory ${path} does not exist at base` };
+  const dir = mkdtempSync(join(tmpdir(), "chant-policy-"));
+  const cleanup = (): void => rmSync(dir, { recursive: true, force: true });
+  const copy = (from: string, to: string): void => {
+    for (const entry of tree.list(from) ?? []) {
+      const src = from === "" || from === "." ? entry.name : `${from}/${entry.name}`;
+      const dest = join(to, entry.name);
+      if (entry.type === "dir") {
+        mkdirSync(dest, { recursive: true });
+        copy(src, dest);
+      } else {
+        writeFileSync(dest, tree.bytes ? tree.bytes(src) : tree.read(src));
+      }
+    }
+  };
+  try {
+    if (kind === "file") writeFileSync(join(dir, root.split("/").pop()!), tree.bytes ? tree.bytes(root) : tree.read(root));
+    else copy(root, dir);
+  } catch (err) {
+    cleanup();
+    return { error: `the policy at ${path} could not be read at base: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  return { dir, cleanup };
+}
+
+/** The settings, checked. Throws with what is wrong. `where` names them, such as `ci.policy`. */
+export function assertGatePolicySettings(where: string, raw: unknown): asserts raw is GatePolicySettings {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`${where} must be { engine?, path?, namespace?, command? }`);
+  for (const [key, value] of Object.entries(raw)) {
+    if (key === "engine") {
+      if (!(GATE_POLICY_ENGINES as readonly unknown[]).includes(value)) throw new Error(`${where}.engine must be ${GATE_POLICY_ENGINES.join(" or ")}, the result shape the command prints`);
+    } else if (key === "path" || key === "namespace") {
+      if (typeof value !== "string" || value.trim() === "") throw new Error(`${where}.${key} must be a non-empty string`);
+      if (key === "path" && (value.startsWith("/") || value.split("/").includes(".."))) throw new Error(`${where}.path must be a directory inside the workspace, relative to its declaration`);
+    } else if (key === "command") {
+      if (!Array.isArray(value) || value.length === 0 || !value.every((a) => typeof a === "string" && a !== "")) throw new Error(`${where}.command must be argv, a non-empty list of strings`);
+      if (!value.some((a: string) => a.includes("{input}"))) throw new Error(`${where}.command must pass the input file as {input}`);
+    } else if (key === "outcomes" || key === "allow_unattended" || key === "allowUnattended") {
+      throw new Error(`${where}.${key}: chant's policy step denies and holds only; a non-empty plan always waits for a person (ws-104), so there is no unattended outcome`);
+    } else {
+      throw new Error(`${where}.${key} is not a setting; the settings are engine, path, namespace and command`);
+    }
+  }
+}

package/src/lifecycle/__fixtures__/publish-fakes.ts

@@ -203,7 +203,12 @@ if (args[0] === "publish") {
   const [name, version] = split(args[1]);
   const p = reg.packages[name];
   if (!p) { console.error("npm error 404 Not Found - " + name); process.exit(1); }
-  if (p.lag && p.lag[version] > 0) { p.lag[version] -= 1; save(); }
+  if (process.env.FAKE_NPM_VIEW_ERROR && name.includes(process.env.FAKE_NPM_VIEW_ERROR) && p.versions.includes(version)) { console.error("npm error code E500"); console.error("npm error 500 Internal Server Error - GET https://registry.example/" + name); process.exit(1); }
+  if (p.lag && p.lag[version] > 0) {
+    p.lag[version] -= 1; save();
+    // A new package npm does not serve yet answers 404, as the real registry does.
+    if (process.env.FAKE_NPM_LAG_404) { console.error("npm error code E404"); console.error("npm error 404 No match found for version " + version); process.exit(1); }
+  }
   else if (p.versions.includes(version)) console.log(version);
 } else if (args[0] === "dist-tag" && args[1] === "add") {
   const [name, version] = split(args[2]);

package/src/lifecycle/gate-checkpoint.ts

@@ -6,7 +6,7 @@
  * The run writes the file just before it appends the pending fact, and puts
  * the file's digest on that fact as `checkpointDigest`. `chant approve`
  * copies the digest onto the approval, the way it copies the plan digest, and
- * a seal covers it (`../workspace/trust/gate-seal.ts`). A later run that
+ * a seal covers it (`./gate-seal.ts`). A later run that
  * resumes at the gate reads the file back and checks it against the digest
  * the approver saw, so a value pushed onto the branch after the approval is
  * refused rather than carried into the steps after the gate.

package/src/{workspace/trust → lifecycle}/gate-seal.ts

@@ -19,7 +19,7 @@
  */
 
 import { createHash, createPublicKey, verify, type KeyObject } from "node:crypto";
-import type { Signer } from "./trust-files";
+import type { Signer } from "../workspace/trust/trust-files";
 
 /**
  * The ssh signature namespace of a gate approval's seal (#3163, ws-080), so a

package/src/lifecycle/publish-declaration.ts

@@ -61,9 +61,10 @@ export const NpmPublishSchema = z
      */
     tokenEnv: envName.optional(),
     /**
-     * Seconds the reveal waits for the registry to serve every version it
-     * published before installing them to audit (#4244). A registry accepts a
-     * publish before it serves it. Default 600.
+     * A cap, in seconds, on the reveal's wait for the registry to serve every
+     * version it published before installing them to audit (#4244). A
+     * registry accepts a publish before it serves it. Unset, the wait ends
+     * only when every version is served or the registry fails (#4271).
      */
     registryWait: z.number().int().min(0).optional(),
   })

package/src/lifecycle/publish-npm.ts

@@ -160,10 +160,12 @@ function run(bin: string, args: string[], ctx: PublishContext, cwd: string = ctx
   });
 }
 
-/** Seconds the reveal waits for the registry to serve what it published, by default (#4244). */
-export const NPM_REGISTRY_WAIT_SECONDS = 600;
 /** Between polls of the registry while it waits. */
 export const NPM_REGISTRY_POLL_MS = 10_000;
+/** Between progress lines while the reveal waits for the registry (#4271). */
+export const NPM_REGISTRY_PROGRESS_MS = 60_000;
+/** `npm view`'s answers for a version the registry does not serve yet; any other failure is the registry's error. */
+const NPM_VIEW_NOT_YET = /\bE404\b|\b404 Not Found\b|is not in (this|the npm) registry|No match found for version|\b(ETARGET|notarget)\b/;
 /** npm's errors for a version the registry does not serve yet. */
 const NPM_NOT_SERVED = /\b(ETARGET|ERESOLVE|notarget)\b|No matching version found/;
 
@@ -225,29 +227,52 @@ export function npmTarget(decl: NpmPublishDeclaration, deps: PublishDeps): Publi
    * `npm audit signatures` there (#4049), which checks each package's
    * registry signature and provenance attestation.
    */
+  /**
+   * Whether the registry serves the version yet, while the reveal waits for
+   * it (#4271). A 404, or an answer without the version, is not yet; any other
+   * failure of `npm view` is the registry's error and ends the wait.
+   */
+  const probe = async (ctx: PublishContext, pkg: NpmPackage): Promise<boolean> => {
+    const r = await npm(ctx, ["view", `${pkg.name}@${pkg.version}`, "version", ...(decl.registry ? ["--registry", decl.registry] : [])]);
+    if (r.code === 0) return r.output.some((l) => l.trim() === pkg.version || l.trim() === JSON.stringify(pkg.version));
+    if (r.output.some((l) => NPM_VIEW_NOT_YET.test(l))) return false;
+    const said = r.output.filter((l) => /^npm (error|ERR!)/.test(l)).at(-1) ?? r.output.at(-1) ?? "npm printed nothing";
+    throw new PublishTargetError(
+      "publish-npm-registry-failed",
+      `npm view ${pkg.name}@${pkg.version} exited ${r.code} while the reveal waited for the registry to serve it, so nothing was audited: ${said}`,
+      "Each package was published. Once the registry answers, run the publish again: it publishes nothing twice and audits again.",
+    );
+  };
   /**
    * Wait until the registry serves every version (#4244): npm accepts a
    * publish minutes before `npm view` and `npm install` find it, so an
-   * install straight after fails with ETARGET or ERESOLVE.
+   * install straight after fails with ETARGET or ERESOLVE. The wait ends when
+   * every version is served or the registry fails (#4271), with a progress
+   * line about once a minute. `registryWait` caps it only when declared.
    */
   const served = async (ctx: PublishContext, pkgs: NpmPackage[]): Promise<void> => {
-    const wait = (decl.registryWait ?? NPM_REGISTRY_WAIT_SECONDS) * 1000;
+    const cap = decl.registryWait === undefined ? undefined : decl.registryWait * 1000;
     const start = now();
+    let logged: number | undefined;
     let missing = pkgs;
     for (;;) {
       const still: NpmPackage[] = [];
-      for (const pkg of missing) if (!(await onRegistry(ctx, pkg))) still.push(pkg);
+      for (const pkg of missing) if (!(await probe(ctx, pkg))) still.push(pkg);
       missing = still;
       if (missing.length === 0) return;
       const names = missing.map((p) => `${p.name}@${p.version}`).join(", ");
-      if (now() - start >= wait) {
+      const waited = now() - start;
+      if (cap !== undefined && waited >= cap) {
         throw new PublishTargetError(
           "publish-npm-not-served",
-          `the registry did not serve ${names} within ${Math.round(wait / 1000)}s of the publish, so nothing was audited`,
+          `the registry did not serve ${names} within ${Math.round(cap / 1000)}s of the publish, so nothing was audited`,
           "Each package was published. Once npm serves them, run the publish again: it publishes nothing twice and audits again. `registryWait` sets the wait.",
         );
       }
-      ctx.log(`waiting for the registry to serve ${names}`);
+      if (logged === undefined || now() - logged >= NPM_REGISTRY_PROGRESS_MS) {
+        ctx.log(`waiting for the registry to serve ${names}${waited > 0 ? ` (${Math.round(waited / 1000)}s so far)` : ""}`);
+        logged = now();
+      }
       await sleep(NPM_REGISTRY_POLL_MS);
     }
   };

package/src/lifecycle/publish-targets.test.ts

@@ -486,7 +486,8 @@ describe("SBOMs and provenance (#4049)", () => {
   });
 
   describe("npm: the reveal waits for the registry to serve what it published (#4244)", () => {
-    function lagged(env: Record<string, string>, registryWait?: number) {
+    // `step` is how far the clock moves per sleep, so a long wait costs few npm runs.
+    function lagged(env: Record<string, string>, registryWait?: number, step?: number) {
       const dir = temp();
       writePackage(join(dir, "core"), "@acme/core", "1.0.0");
       writePackage(join(dir, "cli"), "@acme/cli", "1.0.0");
@@ -494,7 +495,7 @@ describe("SBOMs and provenance (#4049)", () => {
       const npm = writeFakeNpm(join(dir, "bin"), log);
       let clock = 0;
       const sleeps: number[] = [];
-      const deps = { npm, now: () => clock, sleep: async (ms: number) => { sleeps.push(ms); clock += ms; } };
+      const deps = { npm, now: () => clock, sleep: async (ms: number) => { sleeps.push(ms); clock += step ?? ms; } };
       const ctx = context(dir, { env: { PATH: process.env.PATH, ...env }, provenance: OIDC });
       const d = decl({ type: "npm", packages: ["core", "cli"], stage: false, ...(registryWait !== undefined ? { registryWait } : {}) });
       return { log, deps, ctx, d, sleeps };
@@ -518,7 +519,39 @@ describe("SBOMs and provenance (#4049)", () => {
       expect(installs(log)).toBe(1);
     });
 
-    test("a version never served: the wait ends with an error naming it, before any install", async () => {
+    test("with no registryWait it waits past 600 seconds until npm serves, naming what is missing about once a minute (#4271)", async () => {
+      // 21 polls, the clock moving 30s each: served after 630s.
+      const { log, deps, ctx, d, sleeps } = lagged({ FAKE_NPM_LAG: "@acme/core=21,@acme/cli=1" }, undefined, 30_000);
+      const [target] = await createPublishTargets([d], deps);
+      await target!.reveal(ctx, await target!.stage(ctx));
+      expect(sleeps.length).toBe(21);
+      const progress = ctx.lines.filter((l) => l.startsWith("waiting for the registry to serve"));
+      expect(progress[0]).toBe("waiting for the registry to serve @acme/core@1.0.0, @acme/cli@1.0.0");
+      expect(progress[1]).toBe("waiting for the registry to serve @acme/core@1.0.0 (60s so far)");
+      expect(progress.at(-1)).toBe("waiting for the registry to serve @acme/core@1.0.0 (600s so far)");
+      expect(progress.length).toBe(11);
+      expect(installs(log)).toBe(1);
+    });
+
+    test("a 404 for the version is not yet served, and the wait goes on (#4271)", async () => {
+      const { log, deps, ctx, d, sleeps } = lagged({ FAKE_NPM_LAG: "@acme/cli=2", FAKE_NPM_LAG_404: "1" });
+      const [target] = await createPublishTargets([d], deps);
+      await target!.reveal(ctx, await target!.stage(ctx));
+      expect(sleeps).toEqual([10_000, 10_000]);
+      expect(installs(log)).toBe(1);
+    });
+
+    test("a registry error that is not a 404 ends the wait with npm's error, before any install (#4271)", async () => {
+      const { log, deps, ctx, d, sleeps } = lagged({ FAKE_NPM_VIEW_ERROR: "@acme/cli" });
+      const [target] = await createPublishTargets([d], deps);
+      const err = await refused(target!.reveal(ctx, await target!.stage(ctx)));
+      expect(err.code).toBe("publish-npm-registry-failed");
+      expect(err.message).toBe("npm view @acme/cli@1.0.0 exited 1 while the reveal waited for the registry to serve it, so nothing was audited: npm error 500 Internal Server Error - GET https://registry.example/@acme/cli");
+      expect(sleeps).toEqual([]);
+      expect(installs(log)).toBe(0);
+    });
+
+    test("with registryWait declared, a version never served: the wait ends with an error naming it, before any install", async () => {
       const { log, deps, ctx, d } = lagged({ FAKE_NPM_LAG: "@acme/core=1000" }, 30);
       const [target] = await createPublishTargets([d], deps);
       const err = await refused(target!.reveal(ctx, await target!.stage(ctx)));