@intentius/chant 0.100.0 → 0.101.0

package/src/workspace/trust/evidence.ts

@@ -0,0 +1,207 @@
+/**
+ * Runner evidence (#2553, #2524 D5 "Evidence").
+ *
+ * A runner, meaning a CI job or a service, states that a check ran over a
+ * set of records at one commit. The statement is an in-toto Statement v1:
+ * each record is a subject, named by its path and hashed, and the predicate
+ * binds the commit, its tree, the check, and the digests of the claim and of
+ * the environment when given. The runner signs it in a DSSE envelope with its
+ * own Ed25519 key.
+ *
+ * Verifying needs only the envelope, the repository's objects and the runner
+ * keys the policy at base lists, so it works offline. Evidence is never
+ * reused on trust: a verdict reports, subject by subject, whether the records
+ * still hash the same, and evidence for records that changed is `stale`.
+ */
+
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { z } from "zod";
+import { canonicalJson } from "../../effect-receipt";
+import type { ReasonCode } from "../reason-codes";
+import { IN_TOTO_PAYLOAD_TYPE, signEnvelope, verifyEnvelope, type DsseEnvelope } from "./dsse";
+import type { KeyObject } from "node:crypto";
+import type { RunnerKey } from "./policy";
+
+export const STATEMENT_TYPE = "https://in-toto.io/Statement/v1";
+export const RUNNER_EVIDENCE_PREDICATE = "https://intentius.io/chant/runner-evidence/v1";
+
+/**
+ * Why evidence is refused, by `evidence sign` or `evidence verify` (#2553).
+ * Each is in `reason-codes.ts` and in `evidence.schema.json`. A sign or verify
+ * that can't read the record kind fails with the records read's own code.
+ */
+export const EVIDENCE_ERROR_CODES = [
+  "not-a-git-repository",
+  "revision-unknown",
+  "trust-policy-unreadable",
+  "envelope-unreadable",
+  "envelope-invalid",
+  "envelope-untrusted",
+  "evidence-payload-type",
+  "evidence-statement-invalid",
+  "evidence-runner-mismatch",
+  "runner-key-invalid",
+  "runner-key-is-signer",
+  "runner-key-unlisted",
+  "kind-unreadable",
+  "kind-invalid",
+  "schema-unreadable",
+  "schema-id-mismatch",
+  "schema-invalid",
+  "location-missing",
+] as const satisfies readonly ReasonCode[];
+export type EvidenceErrorCode = (typeof EVIDENCE_ERROR_CODES)[number];
+
+const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/);
+const fullCommit = z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/);
+
+/** The statement a runner signs. Strict, so a verifier never acts on a field it does not know. */
+export const evidenceStatementSchema = z
+  .object({
+    _type: z.literal(STATEMENT_TYPE),
+    subject: z
+      .array(
+        z
+          .object({
+            name: z
+              .string()
+              .min(1)
+              .refine((n) => !n.startsWith("/") && !n.split("/").includes(".."), "a path inside the repository"),
+            digest: z.object({ sha256: sha256Hex }).strict(),
+          })
+          .strict(),
+      ),
+    predicateType: z.literal(RUNNER_EVIDENCE_PREDICATE),
+    predicate: z
+      .object({
+        runner: z.string().min(1),
+        commit: fullCommit,
+        tree: fullCommit,
+        check: z.string().min(1),
+        claim: z.object({ sha256: sha256Hex }).strict().optional(),
+        environment: z.object({ sha256: sha256Hex }).strict().optional(),
+      })
+      .strict(),
+  })
+  .strict();
+export type EvidenceStatement = z.infer<typeof evidenceStatementSchema>;
+
+/** SHA-256 of a record's text, line endings normalised as seals do (#2524 D4). */
+export function recordHash(text: string): string {
+  return createHash("sha256").update(text.replace(/\r\n?/g, "\n"), "utf8").digest("hex");
+}
+
+function sha256(bytes: Buffer | string): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+function git(repo: string, args: string[]): string {
+  return execFileSync("git", args, { cwd: repo, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 });
+}
+
+function blobAt(repo: string, commit: string, path: string): string | undefined {
+  try {
+    return git(repo, ["cat-file", "blob", `${commit}:${path}`]);
+  } catch {
+    return undefined;
+  }
+}
+
+export interface EvidenceInput {
+  repo: string;
+  /** The full commit id the check ran at. Records are hashed as committed there. */
+  commit: string;
+  paths: string[];
+  runner: string;
+  check: string;
+  claim?: Buffer;
+  environment?: Buffer;
+}
+
+export function buildStatement(input: EvidenceInput): EvidenceStatement {
+  const subject = [...input.paths].sort().map((name) => {
+    const text = blobAt(input.repo, input.commit, name);
+    if (text === undefined) throw new Error(`${name} is not in commit ${input.commit.slice(0, 8)}`);
+    return { name, digest: { sha256: recordHash(text) } };
+  });
+  return {
+    _type: STATEMENT_TYPE,
+    subject,
+    predicateType: RUNNER_EVIDENCE_PREDICATE,
+    predicate: {
+      runner: input.runner,
+      commit: input.commit,
+      tree: git(input.repo, ["rev-parse", `${input.commit}^{tree}`]).trim(),
+      check: input.check,
+      ...(input.claim ? { claim: { sha256: sha256(input.claim) } } : {}),
+      ...(input.environment ? { environment: { sha256: sha256(input.environment) } } : {}),
+    },
+  };
+}
+
+export function signEvidence(statement: EvidenceStatement, key: KeyObject, publicKey: string): DsseEnvelope {
+  return signEnvelope(IN_TOTO_PAYLOAD_TYPE, Buffer.from(canonicalJson(statement), "utf8"), key, publicKey);
+}
+
+export interface SubjectVerdict {
+  name: string;
+  signed: string;
+  /** The hash at the revision checked, or null when the record is not there. */
+  now: string | null;
+  matches: boolean;
+}
+
+export type EvidenceVerdict =
+  | {
+      ok: true;
+      /** `current` when every subject still hashes the same at the revision checked; otherwise `stale`. */
+      status: "current" | "stale";
+      runner: string;
+      class: RunnerKey["class"];
+      keyid: string;
+      statement: EvidenceStatement;
+      subjects: SubjectVerdict[];
+    }
+  | { ok: false; code: EvidenceErrorCode; reason: string };
+
+/**
+ * Verify an envelope against the runner keys at base, then compare each
+ * subject with the record as committed at `at`.
+ */
+export function verifyEvidence(envelope: unknown, runners: readonly RunnerKey[], repo: string, at: string): EvidenceVerdict {
+  const v = verifyEnvelope(envelope, runners);
+  if (!v.ok) return v;
+  if (v.payloadType !== IN_TOTO_PAYLOAD_TYPE) return { ok: false, code: "evidence-payload-type", reason: `payload type ${v.payloadType} is not ${IN_TOTO_PAYLOAD_TYPE}` };
+  let raw: unknown;
+  try {
+    raw = JSON.parse(v.payload.toString("utf8"));
+  } catch {
+    return { ok: false, code: "evidence-statement-invalid", reason: "the payload is not JSON" };
+  }
+  const parsed = evidenceStatementSchema.safeParse(raw);
+  if (!parsed.success) {
+    const detail = parsed.error.issues.map((i) => `${i.path.join(".") || "/"}: ${i.message}`).join("; ");
+    return { ok: false, code: "evidence-statement-invalid", reason: `the payload is not a ${RUNNER_EVIDENCE_PREDICATE} statement: ${detail}` };
+  }
+  const statement = parsed.data;
+  // The runner named inside must be the one whose key signed: a runner cannot speak for another.
+  if (statement.predicate.runner !== v.principal) {
+    return { ok: false, code: "evidence-runner-mismatch", reason: `the statement names runner ${JSON.stringify(statement.predicate.runner)}, but ${v.principal}'s key signed it` };
+  }
+  const subjects = statement.subject.map((s) => {
+    const text = blobAt(repo, at, s.name);
+    const now = text === undefined ? null : recordHash(text);
+    return { name: s.name, signed: s.digest.sha256, now, matches: now !== null && now === s.digest.sha256 };
+  });
+  const runner = runners.find((r) => r.principal === v.principal)!;
+  return {
+    ok: true,
+    status: subjects.every((s) => s.matches) ? "current" : "stale",
+    runner: v.principal,
+    class: runner.class,
+    keyid: v.keyid,
+    statement,
+    subjects,
+  };
+}

package/src/workspace/trust/policy.ts

@@ -219,6 +219,49 @@ export const trustConfigSchema = z
      * the commits `from..to`.
      */
     adopted: z.array(z.object({ from: fullCommit.optional(), to: fullCommit, note: z.string().optional() }).strict()).optional(),
+    /**
+     * Keys that sign runner evidence (#2553). Each belongs to a service or a CI
+     * identity, never to a person: a key or principal the signers file lists
+     * is refused here.
+     */
+    runners: z
+      .array(
+        z
+          .object({
+            principal: z.string().min(1),
+            class: z.enum(["runner", "service"]),
+            key: z.string().regex(/^ssh-ed25519 [A-Za-z0-9+/]+={0,2}$/, "an ssh-ed25519 public key, with no comment"),
+          })
+          .strict(),
+      )
+      .optional(),
+    /**
+     * Signers admitted for the work one return brought back (#2552, D10,
+     * ws-004). Each entry names the return by its id (the file
+     * `.chant/returns/<id>.json` the import wrote) and the keys it admits.
+     * An admitted key verifies only the returned commits and seals of that
+     * return, never a commit made in this repository.
+     */
+    admitted: z
+      .array(
+        z
+          .object({
+            return: z.string().regex(/^ret-[0-9a-f]{12}$/, "a return id, ret-<12 hex>"),
+            signers: z
+              .array(
+                z
+                  .object({
+                    principal: z.string().min(1),
+                    key: z.string().regex(/^(ssh-ed25519|ssh-rsa|ecdsa-sha2-nistp(256|384|521)|sk-ssh-ed25519@openssh\.com|sk-ecdsa-sha2-nistp256@openssh\.com) [A-Za-z0-9+/]+={0,2}$/, "an ssh public key, with no comment"),
+                  })
+                  .strict(),
+              )
+              .min(1),
+            note: z.string().optional(),
+          })
+          .strict(),
+      )
+      .optional(),
   })
   .strict();
 
@@ -227,6 +270,14 @@ export type TrustConfig = z.infer<typeof trustConfigSchema>;
 /** The role whose holders may change the policy. Without any grant of it, every signer may. */
 export const ADMIN_ROLE = "admin";
 
+/** A key that signs runner evidence: a service or CI identity. */
+export interface RunnerKey {
+  principal: string;
+  class: "runner" | "service";
+  /** `ssh-ed25519 <base64>`. */
+  key: string;
+}
+
 /** The policy a check applies, as read at base. */
 export interface TrustPolicy {
   /** The full commit id the policy was read at, or null when there is no base. */
@@ -239,13 +290,32 @@ export interface TrustPolicy {
   excluded: ExcludedSigner[];
   roles: Record<string, string[]>;
   adopted: Array<{ from?: string; to: string }>;
+  /** Runner and service keys that may sign runner evidence (#2553). */
+  runners: RunnerKey[];
+  /** Runner entries that are not used, and why. */
+  excludedRunners: Array<{ principal: string; reason: string }>;
+  /** Signers admitted per return (#2552), keyed by return id. They verify that return's commits and seals only. */
+  admitted: Record<string, Signer[]>;
+  /**
+   * Set on a copy of the policy used for one returned record (#2552): the
+   * return it came back in. A seal by a principal the policy does not list
+   * then reads as unverifiable rather than unlisted, until an admin admits
+   * the signer. Never set on the policy read at base.
+   */
+  returnedFrom?: string;
   /** Why the policy could not be read, when it could not. Nothing verifies then. */
   problems: string[];
+  /**
+   * The signer set in effect at a commit's position in the base's history
+   * (#2553). Absent, every commit is judged by `signers`.
+   */
+  signersAt?: (commit: string) => { version: number; signers: Signer[] } | null;
 }
 
-/** Paths whose change is a protected write under `policy`. */
+/** Paths whose change is a protected write under `policy`: the config, the signers file and its rotation file (#2553). */
 export function protectedPaths(policy: TrustPolicy): string[] {
-  return [...new Set([TRUST_CONFIG_PATH, policy.signersPath])].sort();
+  const s = policy.signersPath;
+  return [...new Set([TRUST_CONFIG_PATH, s, posix.join(posix.dirname(s), `${posix.basename(s)}.rotation.json`)])].sort();
 }
 
 /** Principals allowed to change the policy: the admins when any are granted, otherwise every signer. */
@@ -257,7 +327,7 @@ export function policyWriters(policy: TrustPolicy): Set<string> {
 
 /** A policy with nothing in it: attestation off. */
 export function emptyPolicy(base: string | null, problems: string[] = []): TrustPolicy {
-  return { base, signersPath: DEFAULT_SIGNERS_PATH, active: false, signers: [], excluded: [], roles: {}, adopted: [], problems };
+  return { base, signersPath: DEFAULT_SIGNERS_PATH, active: false, signers: [], excluded: [], roles: {}, adopted: [], runners: [], excludedRunners: [], admitted: {}, problems };
 }
 
 /**
@@ -285,6 +355,22 @@ export function readTrustPolicy(source: RecordSource, base: string | null): Trus
   const signersPath = config.signers ?? DEFAULT_SIGNERS_PATH;
   const text = readOptional(source, signersPath);
   const set = text === undefined ? { signers: [], excluded: [] } : parseAllowedSigners(text);
+  // A runner key is a machine's, never a person's (#2553).
+  const humanKeys = new Set(set.signers.map((s) => s.key));
+  const humanNames = new Set(set.signers.map((s) => s.principal));
+  const runners: RunnerKey[] = [];
+  const excludedRunners: Array<{ principal: string; reason: string }> = [];
+  const all = config.runners ?? [];
+  for (const r of all) {
+    if (humanKeys.has(r.key) || humanNames.has(r.principal)) {
+      excludedRunners.push({ principal: r.principal, reason: `${signersPath} lists this ${humanKeys.has(r.key) ? "key" : "principal"}; runner keys belong to a service or CI identity, never to a signer` });
+    } else if (all.filter((o) => o.key === r.key || o.principal === r.principal).length > 1) {
+      // One key under two names, or one name with two entries, would leave it unclear who signed.
+      excludedRunners.push({ principal: r.principal, reason: "another runner entry has the same key or principal; each runner is one principal with one key" });
+    } else {
+      runners.push(r);
+    }
+  }
   return {
     base,
     signersPath,
@@ -293,10 +379,31 @@ export function readTrustPolicy(source: RecordSource, base: string | null): Trus
     excluded: set.excluded,
     roles: config.roles ?? {},
     adopted: config.adopted ?? [],
+    runners,
+    excludedRunners,
+    admitted: admittedOf(config),
     problems: [],
   };
 }
 
+/** The admitted signers, by return id. Two entries for one return add up. */
+function admittedOf(config: TrustConfig): Record<string, Signer[]> {
+  const out: Record<string, Signer[]> = {};
+  for (const a of config.admitted ?? []) {
+    out[a.return] = [...(out[a.return] ?? []), ...a.signers.map((s) => ({ principal: s.principal, key: s.key, line: 0 }))];
+  }
+  return out;
+}
+
+/**
+ * The policy for work that came back in return `id` (#2552): the signers at
+ * base plus the ones admitted for that return, marked with the return so a
+ * seal by an unknown signer reads as unverifiable.
+ */
+export function returnedPolicy(policy: TrustPolicy, id: string): TrustPolicy {
+  return { ...policy, signers: [...policy.signers, ...(policy.admitted[id] ?? [])], returnedFrom: id };
+}
+
 /** A file's text through `source`, or undefined when it is not there. */
 export function readOptional(source: RecordSource, path: string): string | undefined {
   const dir = posix.dirname(path);

package/src/workspace/trust/provenance.ts

@@ -15,6 +15,7 @@ import { execFileSync } from "node:child_process";
 import { gitRevisionSource } from "../record-source";
 import { attestCommit, type CommitAttestor, type ProvenanceLevel } from "./attestor";
 import { emptyPolicy, readTrustPolicy, type TrustPolicy } from "./policy";
+import { SignerPositions, signerHistory } from "./rotation";
 
 /** What `records` reports for one record. */
 export interface RecordProvenance {
@@ -25,6 +26,12 @@ export interface RecordProvenance {
   principal?: string;
   key?: string;
   reason: string;
+  /**
+   * Set when the content came back in a return (#2552): the return's id, the
+   * commit in the returned copy that the level judges, and the commit here
+   * that holds the content. `commit` above is that commit here.
+   */
+  returned?: { id: string; commit?: string; importedIn: string | null };
 }
 
 /** Where the base revision came from. */
@@ -70,10 +77,22 @@ export function resolveBase(repo: string, explicit?: string): ResolvedBase {
   return { commit: null, from: null, problem: "no base revision: pass --base <rev> (there is no origin/HEAD, main or master)" };
 }
 
-/** The policy at `base`, or an inactive one when there is no base. */
+/**
+ * The policy at `base`, or an inactive one when there is no base. With a
+ * signers file, its history is verified too (#2553): every version must be
+ * signed by a threshold of the one before, or nothing verifies.
+ */
 export function policyAtBase(repo: string, base: ResolvedBase): TrustPolicy {
   if (!base.commit) return emptyPolicy(null, base.problem ? [base.problem] : []);
-  return readTrustPolicy(gitRevisionSource(repo, base.commit), base.commit);
+  const policy = readTrustPolicy(gitRevisionSource(repo, base.commit), base.commit);
+  if (!policy.active || policy.problems.length > 0) return policy;
+  const history = signerHistory(repo, base.commit, policy.signersPath);
+  if (history.broken) {
+    const at = history.broken.commit ? ` at ${history.broken.commit.slice(0, 8)}` : "";
+    return { ...policy, problems: [`the signer history of ${policy.signersPath} is broken${at}: ${history.broken.reason}`] };
+  }
+  const positions = new SignerPositions(repo, base.commit, history);
+  return { ...policy, signersAt: (commit) => positions.versionFor(commit) };
 }
 
 /**
@@ -126,7 +145,18 @@ export function isAdopted(repo: string, policy: TrustPolicy, commit: string): bo
 
 /** A commit's provenance level under `policy`. */
 export function commitProvenance(repo: string, policy: TrustPolicy, commit: string, attestors: readonly CommitAttestor[]): RecordProvenance {
-  const a = attestCommit({ repo, policy }, commit, attestors);
+  // Judge the commit by the signer set in effect where it entered the base's history (#2553).
+  let judged = policy;
+  if (policy.signersAt) {
+    const v = policy.signersAt(commit);
+    judged = { ...policy, signers: v?.signers ?? [] };
+    if (!v || v.version === 0) {
+      const none = "no signer set was in effect where this commit entered the base's history";
+      if (isAdopted(repo, policy, commit)) return { level: "adopted", commit, reason: `in a commit range the policy at base adopts; ${none}` };
+      return { level: "unattested", commit, reason: none };
+    }
+  }
+  const a = attestCommit({ repo, policy: judged }, commit, attestors);
   if (a.level === "unattested" && isAdopted(repo, policy, commit)) {
     return { level: "adopted", commit, attestor: a.attestor, reason: `in a commit range the policy at base adopts; ${a.reason}` };
   }
@@ -147,6 +177,12 @@ export interface ProvenanceQuery {
   at: string | null;
   paths: string[];
   attestors: readonly CommitAttestor[];
+  /**
+   * A second look at each committed path, given the provenance of the commit
+   * that holds it here. Returned work (#2552) uses it to judge the commit the
+   * content was made in, which a return carries. Undefined keeps the answer.
+   */
+  revisit?: (path: string, host: RecordProvenance) => RecordProvenance | undefined;
 }
 
 /**
@@ -175,7 +211,8 @@ export function recordProvenance(q: ProvenanceQuery): Map<string, RecordProvenan
       out.set(p, { level: "unattested", commit: null, reason: "no commit holds this file" });
       continue;
     }
-    out.set(p, commitProvenance(q.repo, q.policy, c, q.attestors));
+    const host = commitProvenance(q.repo, q.policy, c, q.attestors);
+    out.set(p, q.revisit?.(p, host) ?? host);
   }
   return out;
 }

package/src/workspace/trust/record-seal.test.ts

@@ -221,7 +221,7 @@ describe.skipIf(!hasSshKeygen)("author seals under a signers file at base", () =
     const digest = (await record(r)).digest;
     const doc = await amend(r, { state: "superseded" });
     if ("error" in doc) throw new Error(doc.error.message);
-    expect(doc.changed).toEqual(["state", "seal"]);
+    expect(doc.changed).toEqual(["state", "seal", "closed_digest"]);
     expect(doc.sealDropped).toMatch(/moves its digest or its state/);
     expect((await record(r)).digest).toBe(digest);
   });