@intentius/chant 0.124.40 → 0.124.41

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/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/query.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, test } from "vitest";
+import type { LedgerReadPort } from "./ledger-port";
+import { firstWord, formatQueryResult, loadQueryData, QUERY_SCHEMA_VERSION, QUERY_TABLES, QueryError, runQuery, SCHEMA_TABLE } from "./query";
+import { makeRelease } from "./release-store";
+
+/** A port over a map of `<dir>/<file>` to text, the shape `gitLedgerReadPort` reads. */
+function port(files: Record<string, string>): LedgerReadPort {
+  const dirs = (): string[] => [...new Set(Object.keys(files).map((p) => p.slice(0, p.indexOf("/"))))];
+  return {
+    read: async (dir, file) => files[`${dir}/${file}`] ?? null,
+    list: async (dir) => Object.keys(files).filter((p) => p.startsWith(`${dir}/`)).map((p) => p.slice(dir.length + 1)),
+    trees: async () => dirs(),
+  };
+}
+
+const lines = (...rows: unknown[]): string => rows.map((r) => (typeof r === "string" ? r : JSON.stringify(r))).join("\n") + "\n";
+
+const release = makeRelease({ member: null, commit: "c".repeat(40), artifactDigests: [{ component: "api", kind: "image", path: "dist/api.tar", digest: "sha256:aa" }], targets: [{ env: "prod", templates: [], params: [] }] });
+
+const ledger = port({
+  "prod/aws.json": JSON.stringify({ lexicon: "aws", environment: "prod", commit: "a".repeat(40), timestamp: "2026-10-01T00:00:00Z", resources: { Bucket: { type: "AWS::S3::Bucket", status: "CREATE_COMPLETE", physicalId: "my-bucket", attributes: { Arn: "arn:aws:s3:::my-bucket" } }, Queue: { type: "AWS::SQS::Queue", status: "CREATE_COMPLETE" } } }),
+  "prod/edge__k8s.json": JSON.stringify({ lexicon: "k8s", environment: "prod", commit: "b".repeat(40), timestamp: "2026-10-02T00:00:00Z", depth: "deep", resources: { Web: { type: "K8s::Apps::Deployment", status: "Available", ownership: "owned" } }, unobserved: { Gone: { reason: "not-found" } } }),
+  "prod/observation-baseline.json": JSON.stringify({ version: 1, environment: "prod" }),
+  "prod/releases.jsonl": lines(
+    { version: 1, component: "api", env: "prod", digest: "sha256:aa", gitSha: "c".repeat(40), runId: "r1", runOrigin: { forge: "github", url: "https://example.test/run/1" }, timestamp: "2026-10-03T00:00:00Z", actor: "ci", releaseDigest: release.releaseDigest },
+    "{not json",
+  ),
+  "prod/runs__deploy.jsonl": lines(
+    { version: 1, id: "run-1", op: "deploy", env: "prod", started: "2026-10-03T00:00:00Z", ended: "2026-10-03T00:01:00Z", status: "fail", labels: { Env: "prod" }, outcomes: {}, phases: [], failure: { code: "command-failed", reason: "exit 1", phase: "apply" } },
+    { version: 1, id: "run-2", op: "deploy", env: "prod", started: "2026-10-04T00:00:00Z", ended: "2026-10-04T00:01:00Z", status: "ok", labels: {}, outcomes: { url: "https://x" }, phases: [] },
+  ),
+  "_gates/deploy.jsonl": lines(
+    { version: 1, kind: "pending", op: "deploy", gate: "prod-approval", timestamp: "2026-10-03T00:00:00Z", expiresAt: "2026-10-10T00:00:00Z", planDigest: "sha256:p1", origin: "cli" },
+    { version: 1, op: "deploy", gate: "prod-approval", resolvedBy: "alice", timestamp: "2026-10-03T01:00:00Z", planDigest: "sha256:p1", approver: { kind: "human" } },
+  ),
+  [`_releases/${release.releaseDigest.replace(/:/g, "_")}.json`]: JSON.stringify(release),
+  "_releases/sha256_tampered.json": JSON.stringify({ ...release, releaseDigest: "sha256:tampered" }),
+  "_releases/cuts.jsonl": lines({ version: 1, releaseDigest: release.releaseDigest, label: "v1.0.0", actor: "alice", timestamp: "2026-10-02T12:00:00Z", runId: null, runOrigin: null, signature: null }),
+});
+
+describe("chant query (#4297)", () => {
+  test("loads every ledger into its table and counts what it can't read", async () => {
+    const load = await loadQueryData([{ member: null, port: ledger }]);
+    expect(load.data.snapshots).toHaveLength(2);
+    expect(load.data.resources.map((r) => r.name)).toEqual(["Bucket", "Queue", "Web"]);
+    expect(load.data.resources[2]).toMatchObject({ stack: "edge", lexicon: "k8s", ownership: "owned" });
+    expect(load.data.snapshots[1]).toMatchObject({ depth: "deep", resources: 1, unobserved: 1 });
+    expect(load.data.runs.map((r) => r.status)).toEqual(["fail", "ok"]);
+    expect(load.data.gates.map((g) => g.kind)).toEqual(["pending", "resolution"]);
+    expect(load.data.deploys).toHaveLength(1);
+    expect(load.data.releases).toEqual([expect.objectContaining({ release_digest: release.releaseDigest, envs: "prod" })]);
+    expect(load.data.cuts[0]).toMatchObject({ label: "v1.0.0", signed: 0 });
+    expect(load.malformed).toMatchObject({ deploys: 1, releases: 1, runs: 0, gates: 0 });
+  });
+
+  test("runs SQL over the tables and joins them", async () => {
+    const load = await loadQueryData([{ member: null, port: ledger }]);
+    const byType = await runQuery("SELECT lexicon, count(*) AS n FROM resources GROUP BY lexicon ORDER BY lexicon", load);
+    expect(byType.columns).toEqual(["lexicon", "n"]);
+    expect(byType.rows).toEqual([{ lexicon: "aws", n: 2 }, { lexicon: "k8s", n: 1 }]);
+    const joined = await runQuery("SELECT d.component, c.label FROM deploys d JOIN cuts c ON c.release_digest = d.release_digest", load);
+    expect(joined.rows).toEqual([{ component: "api", label: "v1.0.0" }]);
+    const arn = await runQuery("SELECT json_extract(attributes, '$.Arn') AS arn FROM resources WHERE name = 'Bucket'", load);
+    expect(arn.rows[0].arn).toBe("arn:aws:s3:::my-bucket");
+    expect(arn.schemaVersion).toBe(QUERY_SCHEMA_VERSION);
+    expect(formatQueryResult(arn)).toContain("(1 row)");
+  });
+
+  test("chant_schema lists every column with the schema version", async () => {
+    const load = await loadQueryData([]);
+    const r = await runQuery(`SELECT DISTINCT version, table_name FROM ${SCHEMA_TABLE} ORDER BY table_name`, load);
+    expect(r.rows.map((x) => x.table_name)).toEqual(Object.keys(QUERY_TABLES).sort());
+    expect(new Set(r.rows.map((x) => x.version))).toEqual(new Set([QUERY_SCHEMA_VERSION]));
+  });
+
+  test("each member's rows name the member", async () => {
+    const load = await loadQueryData([{ member: "api", port: ledger }, { member: "web", port: port({}) }]);
+    const r = await runQuery("SELECT DISTINCT member FROM runs", load);
+    expect(r.rows).toEqual([{ member: "api" }]);
+  });
+
+  test("refuses anything but a read", async () => {
+    const load = await loadQueryData([]);
+    await expect(runQuery("DELETE FROM runs", load)).rejects.toBeInstanceOf(QueryError);
+    await expect(runQuery("  ", load)).rejects.toBeInstanceOf(QueryError);
+    // A WITH that writes is stopped by query_only.
+    await expect(runQuery("WITH x AS (SELECT 1) INSERT INTO runs (id) SELECT * FROM x", load)).rejects.toBeInstanceOf(QueryError);
+    await expect(runQuery("SELECT nope FROM runs", load)).rejects.toThrow(/does not run/);
+    expect(firstWord("-- note\n /* c */ select 1")).toBe("select");
+  });
+});