@intentius/chant 0.124.27 → 0.124.29

package/src/workspace/trust/op-run-statement.ts

@@ -0,0 +1,148 @@
+/**
+ * The Op-run statement (#4044): a runner's signed word that an Op ran on a
+ * commit and settled as its run record says.
+ *
+ * `chant ci tick` can take chant's own Op runs as its status source in place
+ * of a forge's check runs (`ci.green.source: "runs"`), so a project whose
+ * pipelines run as chant Ops gets green and revoked tags with no forge check
+ * runs. The run ledger on `chant/lifecycle` is written by whatever ran the
+ * Op, so the tick counts a run only when its record carries a statement
+ * signed by a runner key, the same keys and role a ci tag needs (#4031):
+ * `.chant/trust.json` at base lists the key under `runners`, and its
+ * principal holds the `runner` role there. A key the signers file lists is
+ * never a runner key (./policy.ts).
+ *
+ * The statement is an in-toto Statement v1 in a DSSE envelope (./dsse.ts),
+ * as runner evidence (#2553), the agent-run statement (#3192) and the ci tag
+ * statement (#4031) are:
+ *
+ * - `subject`: the commit the run built from (`gitSha`), by `digest.gitCommit`.
+ * - `predicate`: the signer's principal, and the run's id, Op, env, status
+ *   and the SHA-256 of its record without the statement.
+ *
+ * The runner signs at the end of the run when it is given a key
+ * (`chant run <op> --key <file>` or `CHANT_RUNNER_KEY`), and the envelope is
+ * stored on the record itself as `statement`, so the record and its
+ * signature are one ledger line. Verifying needs the record and the runner
+ * keys at base, so it works offline, and every read verifies again.
+ */
+
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { canonicalJson } from "../../effect-receipt";
+import type { OpRunRecord } from "../../op/runtime";
+import { IN_TOTO_PAYLOAD_TYPE, signEnvelope, verifyEnvelope, type DsseEnvelope } from "./dsse";
+import { STATEMENT_TYPE } from "./evidence";
+import { CI_TAG_SIGNER_ROLE, type CiTagFailure, type CiTagSigner } from "./ci-tag-statement";
+import type { RunnerKey } from "./policy";
+
+export const OP_RUN_PREDICATE = "https://intentius.io/chant/op-run/v1";
+
+const fullCommit = z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/);
+const text = z.string().min(1);
+
+/** The statement a runner signs for an Op run. Strict, so a verifier never acts on a field it does not know. */
+export const opRunStatementSchema = z
+  .object({
+    _type: z.literal(STATEMENT_TYPE),
+    subject: z
+      .array(
+        z
+          .object({ name: fullCommit, digest: z.object({ gitCommit: fullCommit }).strict() })
+          .strict()
+          .refine((s) => s.name === s.digest.gitCommit, "a commit subject is named by its own id"),
+      )
+      .length(1),
+    predicateType: z.literal(OP_RUN_PREDICATE),
+    predicate: z
+      .object({
+        signer: text,
+        run: z
+          .object({
+            id: text,
+            op: text,
+            env: text,
+            status: z.enum(["ok", "fail", "gated", "waiting"]),
+            record: z.object({ sha256: z.string().regex(/^[0-9a-f]{64}$/) }).strict(),
+          })
+          .strict(),
+      })
+      .strict(),
+  })
+  .strict();
+export type OpRunStatement = z.infer<typeof opRunStatementSchema>;
+
+/**
+ * The SHA-256 of a run record: the canonical JSON (keys sorted, no
+ * whitespace) of the record without its `statement`, so storing the
+ * statement never changes the hash it signs.
+ */
+export function opRunRecordDigest(record: OpRunRecord): string {
+  const { statement: _statement, ...rest } = record;
+  return createHash("sha256").update(canonicalJson(rest), "utf8").digest("hex");
+}
+
+/** The statement for a settled run, as `signer` would sign it. Throws for a run that knew no commit. */
+export function buildOpRunStatement(record: OpRunRecord, signer: string): OpRunStatement {
+  const sha = record.gitSha;
+  if (!sha || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(sha)) {
+    throw new Error(`run ${record.id} of ${record.op} names no full commit sha, so there is no commit for its statement to sign`);
+  }
+  return {
+    _type: STATEMENT_TYPE,
+    subject: [{ name: sha, digest: { gitCommit: sha } }],
+    predicateType: OP_RUN_PREDICATE,
+    predicate: { signer, run: { id: record.id, op: record.op, env: record.env, status: record.status, record: { sha256: opRunRecordDigest(record) } } },
+  };
+}
+
+/** The envelope a run record carries as `statement`, signed by `signer`. */
+export function signOpRunRecord(record: OpRunRecord, signer: CiTagSigner): DsseEnvelope {
+  const statement = buildOpRunStatement(record, signer.principal);
+  return signEnvelope(IN_TOTO_PAYLOAD_TYPE, Buffer.from(canonicalJson(statement), "utf8"), signer.key, signer.publicKey);
+}
+
+/** One run record judged: signed by a runner holding the `runner` role, or why not, in the words a ci tag uses. */
+export type OpRunVerdict = { status: "signed"; signer: string; keyid: string; reason: string } | { status: CiTagFailure; reason: string };
+
+const normalise = (name: string): string => name.normalize("NFKC").trim().toLowerCase();
+
+/**
+ * Verify the statement a run record carries against the runner keys and
+ * roles at base: a signature by a runner key whose principal holds the
+ * `runner` role, over a statement for this run, its commit and its record as
+ * the ledger holds it. Never throws.
+ */
+export function verifyOpRunStatement(record: OpRunRecord, runners: readonly RunnerKey[], roles: Readonly<Record<string, readonly string[]>>): OpRunVerdict {
+  const run = `run ${record.id} of ${record.op}`;
+  if (record.statement === undefined) return { status: "unsigned", reason: `${run} carries no statement signed by a runner key` };
+  const v = verifyEnvelope(record.statement, runners);
+  if (!v.ok) return { status: v.code === "envelope-untrusted" ? "untrusted" : "invalid", reason: `${run}: ${v.reason}` };
+  if (!(roles[CI_TAG_SIGNER_ROLE] ?? []).some((p) => normalise(p) === normalise(v.principal))) {
+    return { status: "untrusted", reason: `${run} is signed by ${v.principal}'s runner key, and ${v.principal} holds no ${CI_TAG_SIGNER_ROLE} role in .chant/trust.json at base` };
+  }
+  if (v.payloadType !== IN_TOTO_PAYLOAD_TYPE) return { status: "invalid", reason: `${run}: payload type ${v.payloadType} is not ${IN_TOTO_PAYLOAD_TYPE}` };
+  let raw: unknown;
+  try {
+    raw = JSON.parse(v.payload.toString("utf8"));
+  } catch {
+    return { status: "invalid", reason: `${run}: the statement's payload is not JSON` };
+  }
+  const parsed = opRunStatementSchema.safeParse(raw);
+  if (!parsed.success) {
+    const detail = parsed.error.issues.map((i) => `${i.path.join(".") || "/"}: ${i.message}`).join("; ");
+    return { status: "invalid", reason: `${run}: the payload is not a ${OP_RUN_PREDICATE} statement: ${detail}` };
+  }
+  const p = parsed.data.predicate;
+  if (p.signer !== v.principal) return { status: "invalid", reason: `${run}: the statement names signer ${JSON.stringify(p.signer)}, but ${v.principal}'s key signed it` };
+  const differs: string[] = [];
+  if (parsed.data.subject[0]!.name !== record.gitSha) differs.push(`it is for commit ${parsed.data.subject[0]!.name.slice(0, 12)}, and the record names ${record.gitSha ? record.gitSha.slice(0, 12) : "none"}`);
+  if (p.run.id !== record.id) differs.push(`it is for run ${p.run.id}`);
+  if (p.run.op !== record.op) differs.push(`it is for Op ${p.run.op}`);
+  if (p.run.env !== record.env) differs.push(`it is for env ${p.run.env}`);
+  if (p.run.status !== record.status) differs.push(`it says ${p.run.status}, and the record says ${record.status}`);
+  const digest = opRunRecordDigest(record);
+  if (p.run.record.sha256 !== digest) differs.push(`the record hashed ${p.run.record.sha256.slice(0, 12)} when signed and ${digest.slice(0, 12)} now`);
+  if (differs.length > 0) return { status: "mismatch", reason: `${run} is signed by ${v.principal}, but the statement does not match its record: ${differs.join("; ")}` };
+  return { status: "signed", signer: v.principal, keyid: v.keyid, reason: `signed by ${v.principal} (${CI_TAG_SIGNER_ROLE})` };
+}

package/src/workspace/trust/rotation.ts

@@ -256,15 +256,24 @@ export function signerHistory(repo: string, base: string, signersPath: string):
   return { versions };
 }
 
+/** A full commit id, as git prints it: lowercase hex, sha1 or sha256. */
+const FULL_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+
 /**
  * Finds the signer set in effect for a commit, by its position in the base's
- * history. Built once per base; the first-parent line is read once and
- * each lookup is a binary search.
+ * history. Built once per base. The first-parent line and the parents of
+ * every commit the base reaches are read once, in two `git rev-list` walks,
+ * and each lookup of a full commit id is then a map read (#4032). Before,
+ * each lookup ran `git merge-base --is-ancestor` about log2(n) times, and a
+ * trace over a busy file spent most of its time starting those processes. A
+ * commit named any other way (a ref, an abbreviated id) is still looked up
+ * with `git merge-base`, as before.
  */
 export class SignerPositions {
   private line: string[] | undefined;
   private index = new Map<string, number>();
   private memo = new Map<string, SignerVersion | null>();
+  private entries: Map<string, number> | undefined;
 
   constructor(
     private readonly repo: string,
@@ -291,21 +300,39 @@ export class SignerPositions {
   }
 
   /**
-   * The version that judges `commit`, or null when no signer set was in
-   * effect there (before the first one, or the chain is broken).
+   * For every commit the base reaches, the index on the first-parent line
+   * (newest first) of the oldest first-parent commit that contains it: where
+   * it came in. The line is walked oldest first, and each first-parent commit
+   * marks what it reaches that nothing older reached. A marked commit's
+   * ancestors are all marked, so the walk stops at one.
    */
-  versionFor(commit: string): SignerVersion | null {
-    const hit = this.memo.get(commit);
-    if (hit !== undefined) return hit;
-    const answer = this.lookup(commit);
-    this.memo.set(commit, answer);
-    return answer;
+  private entryIndex(): Map<string, number> {
+    if (!this.entries) {
+      const line = this.firstParents();
+      const parents = new Map<string, string[]>();
+      for (const row of git(this.repo, ["rev-list", "--parents", this.base]).split("\n")) {
+        const [commit, ...ps] = row.trim().split(" ");
+        if (commit) parents.set(commit, ps);
+      }
+      const entries = new Map<string, number>();
+      for (let i = line.length - 1; i >= 0; i--) {
+        const stack = [line[i]];
+        while (stack.length > 0) {
+          const c = stack.pop()!;
+          if (entries.has(c)) continue;
+          entries.set(c, i);
+          for (const p of parents.get(c) ?? []) if (!entries.has(p)) stack.push(p);
+        }
+      }
+      this.entries = entries;
+    }
+    return this.entries;
   }
 
-  private lookup(commit: string): SignerVersion | null {
-    if (this.history.broken) return null;
-    const latest = this.history.versions.at(-1) ?? null;
-    if (!this.isAncestor(commit, this.base)) return latest;
+  /** Where `commit` came in on the first-parent line, or null when the base doesn't reach it. */
+  private entryOf(commit: string): number | null {
+    if (FULL_ID.test(commit)) return this.entryIndex().get(commit) ?? null;
+    if (!this.isAncestor(commit, this.base)) return null;
     const line = this.firstParents();
     // The oldest first-parent commit that contains `commit` is where it came in.
     let lo = 0;
@@ -320,6 +347,26 @@ export class SignerPositions {
         hi = mid - 1;
       }
     }
+    return at;
+  }
+
+  /**
+   * The version that judges `commit`, or null when no signer set was in
+   * effect there (before the first one, or the chain is broken).
+   */
+  versionFor(commit: string): SignerVersion | null {
+    const hit = this.memo.get(commit);
+    if (hit !== undefined) return hit;
+    const answer = this.lookup(commit);
+    this.memo.set(commit, answer);
+    return answer;
+  }
+
+  private lookup(commit: string): SignerVersion | null {
+    if (this.history.broken) return null;
+    const latest = this.history.versions.at(-1) ?? null;
+    const at = this.entryOf(commit);
+    if (at === null) return latest;
     // The newest version made strictly before that commit.
     let best: SignerVersion | null = null;
     let bestIndex = Infinity;

package/src/workspace/trust/seal.ts

@@ -31,6 +31,7 @@ import { type TrustPolicy } from "./policy";
 import type { Signer } from "./trust-files";
 import { sshKeygen, verifySshSignature } from "./ssh-commit";
 import { GATE_SEAL_NAMESPACE, gateSealPayload, namespaceAllowed, sshSignatureKey, verifySshSignatureWith, type SealedGateApproval } from "./gate-seal";
+import { RELEASE_SEAL_NAMESPACE, releaseSealPayload } from "../identity-gate-rule";
 
 export { GATE_SEAL_NAMESPACE, gateSealPayload, gateSealVersion, sealedFieldsOf, type SealedGateApproval } from "./gate-seal";
 
@@ -321,6 +322,15 @@ export function sealGateApproval(keyFile: string, a: SealedGateApproval): Verdic
   return sign(keyFile, gateSealPayload(a), GATE_SEAL_NAMESPACE, a.resolvedBy);
 }
 
+/**
+ * Sign a release cut (#4031) with the key in `keyFile`, over
+ * `releaseSealPayload` in the `chant-release` namespace. The cut line keeps
+ * the armored signature; its actor is the signer. Throws a {@link SealError}.
+ */
+export function sealReleaseCut(keyFile: string, cut: { releaseDigest: string; label: string | null; actor: string; timestamp: string }): VerdictSeal {
+  return sign(keyFile, releaseSealPayload(cut), RELEASE_SEAL_NAMESPACE, cut.actor);
+}
+
 function sign(keyFile: string, payload: Buffer, namespace: string, signer: string): VerdictSeal {
   const signed = sshKeygen(["-q", "-Y", "sign", "-n", namespace, "-f", keyFile], payload);
   if (signed.missing) throw new SealError("--sign needs ssh-keygen, and it is not installed here");

package/src/workspace/trust/ssh-commit.ts

@@ -57,12 +57,14 @@ export function splitSignedCommit(raw: Buffer, header = "gpgsig"): SignedCommit
   return { payload, signature: sig.length > 0 ? sig.join("\n") + "\n" : undefined };
 }
 
-function objectFormat(repo: string): string {
-  try {
-    return execFileSync("git", ["rev-parse", "--show-object-format"], { cwd: repo, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
-  } catch {
-    return "sha1";
-  }
+/**
+ * The signature header of a raw commit object, by its object format, which
+ * shows in the length of its tree id. Read from the object itself, so judging
+ * a commit starts no `git rev-parse` (#4032).
+ */
+function signatureHeader(raw: Buffer): "gpgsig" | "gpgsig-sha256" {
+  const tree = /^tree ([0-9a-f]+)$/m.exec(raw.subarray(0, 200).toString("latin1"))?.[1];
+  return tree?.length === 64 ? "gpgsig-sha256" : "gpgsig";
 }
 
 /** Run ssh-keygen; `missing` is true when it is not installed. Shared with the verdict seals (./seal.ts). */
@@ -117,14 +119,13 @@ export const sshCommitAttestor: CommitAttestor = {
     const hit = cache.get(memo);
     if (hit) return hit;
     const raw = execFileSync("git", ["cat-file", "commit", commit], { cwd: ctx.repo, maxBuffer: 64 * 1024 * 1024 });
-    const answer = judgeRaw(raw, objectFormat(ctx.repo) === "sha256" ? "gpgsig-sha256" : "gpgsig", signers);
+    const answer = judgeRaw(raw, signatureHeader(raw), signers);
     cache.set(memo, answer);
     return answer;
   },
   attestRaw(ctx: AttestorContext, raw: Buffer): CommitAttestation {
     // A commit from another repository: its object format shows in its tree line.
-    const tree = /^tree ([0-9a-f]+)$/m.exec(raw.subarray(0, 200).toString("latin1"))?.[1];
-    return judgeRaw(raw, tree?.length === 64 ? "gpgsig-sha256" : "gpgsig", ctx.policy.signers);
+    return judgeRaw(raw, signatureHeader(raw), ctx.policy.signers);
   },
 };
 

package/src/workspace/wip.ts

@@ -38,7 +38,7 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { copyFileSync, existsSync, lstatSync, mkdtempSync, rmSync, unlinkSync } from "node:fs";
+import { copyFileSync, existsSync, lstatSync, mkdtempSync, rmSync, statSync, unlinkSync, utimesSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { KEPT_REF_PREFIX } from "../lifecycle/work-lease";
@@ -348,7 +348,16 @@ function worktreeTree(top: string): string {
     const index = join(dir, "index");
     // Start from the checkout's index so git reuses its stat data; the original is never written.
     const own = out(top, ["rev-parse", "--git-path", "index"]);
-    if (own && existsSync(resolve(top, own))) copyFileSync(resolve(top, own), index);
+    if (own && existsSync(resolve(top, own))) {
+      const source = resolve(top, own);
+      copyFileSync(source, index);
+      // Keep the index's own timestamps on the copy. git treats an entry whose
+      // file is as new as the index as racily clean and reads its content; a
+      // copy stamped now would make a same-size edit made in the same second as
+      // the last index write look unchanged, and the snapshot would miss it.
+      const { atime, mtime } = statSync(source);
+      utimesSync(index, atime, mtime);
+    }
     const env = { GIT_INDEX_FILE: index };
     const add = git(top, ["add", "--all", "--", ":/"], { env });
     if (!add.ok) throw new Error(`wip: git add into a temporary index failed: ${add.stderr.trim()}`);

package/src/cli/commands/__fixtures__/init-lexicon-output/docs/astro.config.mjs

@@ -1,14 +0,0 @@
-// @ts-check
-import { defineConfig } from 'astro/config';
-import starlight from '@astrojs/starlight';
-
-export default defineConfig({
-  integrations: [
-    starlight({
-      title: 'Fixture',
-      sidebar: [
-        { label: 'Overview', slug: '' },
-      ],
-    }),
-  ],
-});

package/src/cli/commands/__fixtures__/init-lexicon-output/docs/package.json

@@ -1,16 +0,0 @@
-{
-  "name": "@intentius/chant-lexicon-fixture-docs",
-  "type": "module",
-  "version": "0.0.1",
-  "private": true,
-  "scripts": {
-    "dev": "astro dev",
-    "build": "astro build",
-    "preview": "astro preview"
-  },
-  "dependencies": {
-    "@astrojs/starlight": "^0.37.6",
-    "astro": "^5.6.1",
-    "sharp": "^0.34.2"
-  }
-}

package/src/cli/commands/__fixtures__/init-lexicon-output/docs/src/content/docs/index.mdx

@@ -1,8 +0,0 @@
----
-title: Overview
-description: Fixture lexicon for chant
----
-
-Welcome to the Fixture lexicon documentation.
-
-Run `just generate` to populate this site with generated reference pages.

package/src/cli/commands/__fixtures__/init-lexicon-output/docs/src/content.config.ts

@@ -1,15 +0,0 @@
-import { defineCollection, z } from 'astro:content';
-import { docsLoader } from '@astrojs/starlight/loaders';
-import { docsSchema } from '@astrojs/starlight/schema';
-
-export const collections = {
-  docs: defineCollection({
-    loader: docsLoader(),
-    schema: docsSchema({
-      extend: z.object({
-        // Diátaxis quadrant (https://diataxis.fr), chant #1731.
-        diataxis: z.enum(['tutorial', 'how-to', 'reference', 'explanation']).optional(),
-      }),
-    }),
-  }),
-};

package/src/cli/commands/__fixtures__/init-lexicon-output/docs/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "astro/tsconfigs/strict",
-  "include": [
-    ".astro/types.d.ts",
-    "**/*"
-  ],
-  "exclude": [
-    "dist"
-  ]
-}