@intentius/chant 0.124.23 → 0.124.25

package/src/workspace/trust/trust.test.ts

@@ -8,6 +8,7 @@
  */
 
 import { execFileSync } from "node:child_process";
+import { join } from "node:path";
 import Ajv2020 from "ajv/dist/2020";
 import schema from "../records.schema.json";
 import { afterEach, describe, expect, test } from "vitest";
@@ -357,6 +358,110 @@ describe.skipIf(!hasSshKeygen)("the ssh-commit attestor, against the policy at b
   });
 });
 
+describe.skipIf(!hasSshKeygen)("writeScope and agents in the declaration are protected (#3079)", () => {
+  const scoped = (over: Record<string, unknown> = {}) =>
+    JSON.stringify(
+      {
+        name: "ws",
+        schema: 1,
+        members: [{ name: "app", dir: "app", kind: "other", because: "plain files" }],
+        writeScope: { agent: { records: {} } },
+        agents: [{ name: "app-agent", member: "app" }],
+        ...over,
+      },
+      null,
+      2,
+    );
+
+  /** main: alice and bob sign, alice is admin when `admin`; the declaration at base restricts agents. */
+  function baseline(label: string, opts: { admin?: boolean; declaration?: string; dir?: string } = {}) {
+    const r = repo(label);
+    const alice = r.key("alice");
+    const bob = r.key("bob");
+    r.write(".chant/allowed_signers", signers(["alice@example.test", alice], ["bob@example.test", bob]));
+    if (opts.admin) r.write(".chant/trust.json", JSON.stringify({ schema: 1, roles: { admin: ["alice@example.test"] } }));
+    r.commit("policy", alice);
+    r.write(`${opts.dir ? `${opts.dir}/` : ""}chant.workspace.json`, opts.declaration ?? scoped());
+    r.commit("declaration", alice);
+    r.git(["checkout", "-q", "-b", "change"]);
+    return { r, alice, bob };
+  }
+
+  test("an unsigned commit that widens writeScope is a refused protected write", async () => {
+    const { r } = baseline("scope-unsigned");
+    r.write("chant.workspace.json", scoped({ writeScope: { agent: { records: { decision: ["new", "amend"] } } } }));
+    const c = r.commit("let agents amend");
+    const report = await verify(r);
+    expect(report.ok).toBe(false);
+    expect(report.protectedWrites).toEqual([expect.objectContaining({ commit: c, paths: ["chant.workspace.json"], allowed: false })]);
+    expect(report.failures.join("\n")).toMatch(/chant\.workspace\.json \(writeScope\) is protected/);
+  });
+
+  test("a change to agents is a protected write, allowed when a signer at base signs it", async () => {
+    const { r, alice } = baseline("agents-signed");
+    r.write("chant.workspace.json", scoped({ agents: [{ name: "app-agent", member: "app" }, { name: "other", member: "app" }] }));
+    r.commit("add a session", alice);
+    const report = await verify(r);
+    expect(report.protectedWrites).toEqual([expect.objectContaining({ allowed: true, principal: "alice@example.test", blocks: ["agents"] })]);
+    expect(report.ok).toBe(true);
+  });
+
+  test("with an admin role granted, a signer who is not an admin may not change writeScope", async () => {
+    const { r, bob } = baseline("scope-admin", { admin: true });
+    r.write("chant.workspace.json", scoped({ writeScope: {} }));
+    r.commit("drop the scope", bob);
+    const report = await verify(r);
+    expect(report.protectedWrites[0]).toMatchObject({ allowed: false, principal: "bob@example.test", blocks: ["writeScope"] });
+    expect(report.ok).toBe(false);
+  });
+
+  test("deleting the declaration drops the scope, and is a protected write", async () => {
+    const { r } = baseline("scope-deleted");
+    r.git(["rm", "-q", "chant.workspace.json"]);
+    r.commit("no more workspace");
+    const report = await verify(r);
+    expect(report.protectedWrites[0]).toMatchObject({ allowed: false, blocks: ["writeScope", "agents"] });
+    expect(report.ok).toBe(false);
+  });
+
+  test("other edits to the declaration are not protected", async () => {
+    const { r } = baseline("scope-other");
+    r.write("chant.workspace.json", scoped({ name: "renamed" }));
+    r.commit("rename");
+    const report = await verify(r);
+    expect(report.protectedWrites).toEqual([]);
+    expect(report.declaration).toEqual({ path: "chant.workspace.json", blocks: ["writeScope", "agents"], changed: [] });
+    expect(report.ok).toBe(true);
+  });
+
+  test("a scope the change adds, where the declaration at base has none, is not protected", async () => {
+    const { r } = baseline("scope-none", { declaration: JSON.stringify({ name: "ws", schema: 1, members: [] }) });
+    r.write("chant.workspace.json", scoped());
+    r.commit("restrict agents");
+    const report = await verify(r);
+    expect(report.protectedWrites).toEqual([]);
+    expect(report.declaration).toBeNull();
+  });
+
+  test("a change and its revert inside the range leave nothing to protect", async () => {
+    const { r } = baseline("scope-revert");
+    r.write("chant.workspace.json", scoped({ writeScope: {} }));
+    r.commit("drop");
+    r.write("chant.workspace.json", scoped());
+    r.commit("restore");
+    const report = await verify(r);
+    expect(report.protectedWrites).toEqual([]);
+  });
+
+  test("the declaration is found from cwd, as check --changes finds it", async () => {
+    const { r } = baseline("scope-nested", { dir: "ws" });
+    r.write("ws/chant.workspace.json", scoped({ writeScope: {} }));
+    r.commit("drop");
+    const report = await verifyChange({ repo: r.dir, cwd: join(r.dir, "ws"), base: "main", attestors: await activeAttestors() });
+    expect(report.protectedWrites).toEqual([expect.objectContaining({ paths: ["ws/chant.workspace.json"], allowed: false })]);
+  });
+});
+
 describe("attestation is opt-in", () => {
   test("without a signers file at base nothing is verified, and every record is unattested", async () => {
     const r = repo("off");

package/src/workspace/trust/verify-cli.ts

@@ -26,6 +26,7 @@ export async function runWorkspaceVerify(ctx: CommandContext): Promise<number> {
   }
   const report = verifyChange({
     repo,
+    cwd: process.cwd(),
     base: args.base,
     head: args.head,
     require: args.require === "attested" || args.require === "attested-runs" ? args.require : undefined,
@@ -49,7 +50,7 @@ function printReport(r: ChangeReport): void {
     lines.push(`  ${c.commit.slice(0, 8)}  ${c.level}${who}  ${c.subject}${note}`);
   }
   for (const c of r.runs.commits) lines.push(`  ${c.commit.slice(0, 8)}  agent run ${c.runs.join(", ") || c.run}: ${c.attested ? "attested" : "not attested"}, ${c.reason}`);
-  for (const w of r.protectedWrites) lines.push(`  protected write ${w.commit.slice(0, 8)} ${w.paths.join(", ")}: ${w.allowed ? "allowed" : "refused"}, ${w.reason}`);
+  for (const w of r.protectedWrites) lines.push(`  protected write ${w.commit.slice(0, 8)} ${w.paths.join(", ")}${w.blocks ? ` (${w.blocks.join(", ")})` : ""}: ${w.allowed ? "allowed" : "refused"}, ${w.reason}`);
   if (r.rotation && "to" in r.rotation) lines.push(`  signer set: version ${r.rotation.from} to ${r.rotation.to}, signed by ${r.rotation.signedBy.join(", ")}`);
   for (const n of r.notes) lines.push(n);
   console.log(lines.join("\n"));

package/src/workspace/trust/verify.ts

@@ -8,6 +8,12 @@
  * that touches those files must be attested by a signer the base policy
  * trusts, and by an admin when the base policy grants the admin role.
  *
+ * The write scope is policy too (#3079): when the workspace declaration at
+ * base has a `writeScope` or `agents` block, a commit that changes either
+ * block, or removes the declaration, is a protected write on the same terms.
+ * Other edits to the declaration are not. The declaration is found from
+ * `cwd`, as `chant workspace check --changes` finds it.
+ *
  * Attestation is opt-in (#2525 rule 6). Without a signers file at base the
  * check passes and says so, unless `--require attested` asks for more.
  *
@@ -22,6 +28,11 @@
  */
 
 import { execFileSync } from "node:child_process";
+import { posix } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { DECLARATION_FILES, WorkspaceReadError } from "../declaration";
+import { parseJsonText } from "../jsonc";
+import { locateWorkspace } from "../which-chant";
 import { type CommitAttestor, type ProvenanceLevel } from "./attestor";
 import { policyAtBase, commitProvenance, resolveBase, type BaseSource, type RecordProvenance } from "./provenance";
 import { policyWriters, protectedPaths, type ExcludedSigner, type TrustPolicy } from "./policy";
@@ -41,6 +52,8 @@ export interface CommitVerdict extends RecordProvenance {
 export interface ProtectedWrite {
   commit: string;
   paths: string[];
+  /** For a declaration write (#3079): the scope blocks the commit changes. */
+  blocks?: ScopeBlock[];
   level: ProvenanceLevel;
   principal?: string;
   allowed: boolean;
@@ -67,6 +80,12 @@ export interface ChangeReport {
   /** Protected paths whose content differs between the merge base and head. */
   protectedChanged: string[];
   protectedWrites: ProtectedWrite[];
+  /**
+   * The workspace declaration at base, when it has a scope block (#3079): its
+   * path from the repository root, the blocks it has, and the blocks that
+   * differ between the merge base and head.
+   */
+  declaration: { path: string; blocks: ScopeBlock[]; changed: ScopeBlock[] } | null;
   /**
    * When the change edits the signer set (#2553): the version it proposes and
    * who signed it, or, when the new set is refused, the version it had to
@@ -80,6 +99,8 @@ export interface ChangeReport {
 
 export interface VerifyOptions {
   repo: string;
+  /** Where to look for the workspace declaration, as `check --changes` does; the repository root by default. */
+  cwd?: string;
   base?: string;
   head?: string;
   require?: VerifyRequirement;
@@ -106,6 +127,51 @@ export function commitsTouching(repo: string, range: string, paths: string[]): M
   return out;
 }
 
+/** The declaration blocks whose change is a protected write (#3079). */
+export type ScopeBlock = "writeScope" | "agents";
+const SCOPE_BLOCKS: readonly ScopeBlock[] = ["writeScope", "agents"];
+
+/** The scope blocks of the declaration in `dir` at `rev`: absent ones undefined, or the text when it can't be read. */
+type ScopeState = { blocks: Partial<Record<ScopeBlock, unknown>> } | { unreadable: string };
+
+function scopeState(repo: string, rev: string, dir: string): ScopeState {
+  const present = DECLARATION_FILES.map((name) => ({ name, text: fileAt(repo, rev, posix.join(dir, name)) })).filter((f) => f.text !== undefined);
+  if (present.length === 0) return { blocks: {} };
+  if (present.length > 1) return { unreadable: present.map((f) => f.text).join("\0") };
+  const parsed = parseJsonText(present[0].text!, { jsonc: present[0].name.endsWith(".jsonc") });
+  if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null || Array.isArray(parsed.value)) return { unreadable: present[0].text! };
+  const obj = parsed.value as Record<string, unknown>;
+  return { blocks: Object.fromEntries(SCOPE_BLOCKS.filter((b) => obj[b] !== undefined).map((b) => [b, obj[b]])) };
+}
+
+/** The scope blocks that differ between two states; all of them when either can't be read and the texts differ. */
+function changedBlocks(a: ScopeState, b: ScopeState): ScopeBlock[] {
+  if ("unreadable" in a || "unreadable" in b) {
+    return "unreadable" in a && "unreadable" in b && a.unreadable === b.unreadable ? [] : [...SCOPE_BLOCKS];
+  }
+  return SCOPE_BLOCKS.filter((k) => !isDeepStrictEqual(a.blocks[k], b.blocks[k]));
+}
+
+/**
+ * The directory, from the repository root, of the declaration found from
+ * `cwd` at `base`, with the scope blocks it has there. Null when there is no
+ * declaration, or one with neither block: then nothing in it is protected. A
+ * declaration that can't be read at base counts as having both.
+ */
+function scopedDeclarationAt(repo: string, cwd: string, base: string): { dir: string; blocks: ScopeBlock[] } | null {
+  let dir: string;
+  try {
+    const root = locateWorkspace(cwd, base).root;
+    dir = root === "." ? "" : root;
+  } catch (err) {
+    if (err instanceof WorkspaceReadError) return null;
+    throw err;
+  }
+  const state = scopeState(repo, base, dir);
+  const blocks = "unreadable" in state ? [...SCOPE_BLOCKS] : SCOPE_BLOCKS.filter((b) => b in state.blocks);
+  return blocks.length > 0 ? { dir, blocks } : null;
+}
+
 /** Whether a merge commit changes nothing beyond what its parents bring. */
 function mergeWithoutOwnChanges(repo: string, commit: string, parents: number): boolean {
   if (parents < 2) return false;
@@ -134,6 +200,7 @@ export function verifyChange(opts: VerifyOptions): ChangeReport {
     protectedPaths: protectedPaths(policy),
     protectedChanged: [],
     protectedWrites: [],
+    declaration: null,
     rotation: null,
     notes: [],
     failures: [],
@@ -157,7 +224,8 @@ export function verifyChange(opts: VerifyOptions): ChangeReport {
 
   // Every commit in the change, oldest first, with its parents.
   const listing = git(repo, ["rev-list", "--reverse", "--parents", `${base.commit}..${head}`]).split("\n").filter(Boolean);
-  const parentsOf = new Map(listing.map((l) => { const [c, ...p] = l.split(" "); return [c, p.length] as const; }));
+  const parentList = new Map(listing.map((l) => { const [c, ...p] = l.split(" "); return [c, p] as const; }));
+  const parentsOf = new Map([...parentList].map(([c, p]) => [c, p.length] as const));
   report.runs = changeRuns(repo, [...parentsOf.keys()], policy.runners);
   if (opts.require === "attested-runs") {
     if (policy.runners.length === 0 && report.runs.commits.length > 0) {
@@ -204,23 +272,48 @@ export function verifyChange(opts: VerifyOptions): ChangeReport {
   }
 
   // Protected writes: every commit that touches the policy needs a writer's signature.
+  const writers = policyWriters(policy);
+  const judge = (commit: string, paths: string[], blocks?: ScopeBlock[]) => {
+    const v = verdicts.get(commit) ?? { ...commitProvenance(repo, policy, commit, opts.attestors), commit, subject: "" };
+    const allowed = v.level === "attested" && v.principal !== undefined && writers.has(v.principal);
+    const who = policy.roles.admin?.length ? "an admin the policy at base names" : "a signer the policy at base lists";
+    const what = blocks ? `${paths.join(", ")} (${blocks.join(", ")})` : paths.join(", ");
+    const reason = allowed
+      ? `signed by ${v.principal}, ${who.replace(/^an? /, "")}`
+      : v.level === "attested"
+        ? `signed by ${v.principal}, who is not ${who}`
+        : `${what} is protected and needs a signature by ${who}: ${v.reason}`;
+    report.protectedWrites.push({ commit, paths, ...(blocks ? { blocks } : {}), level: v.level, ...(v.principal ? { principal: v.principal } : {}), allowed, reason });
+    if (!allowed) report.failures.push(`${commit.slice(0, 8)} changes ${what}: ${reason}`);
+  };
   if (changedPaths.length > 0) {
-    const writers = policyWriters(policy);
     const touching = commitsTouching(repo, `${base.commit}..${head}`, report.protectedPaths);
     if (touching.size === 0) {
       report.failures.push(`the policy files ${changedPaths.join(", ")} differ from base, and no commit in the change accounts for it`);
     }
-    for (const [commit, paths] of touching) {
-      const v = verdicts.get(commit) ?? { ...commitProvenance(repo, policy, commit, opts.attestors), commit, subject: "" };
-      const allowed = v.level === "attested" && v.principal !== undefined && writers.has(v.principal);
-      const who = policy.roles.admin?.length ? "an admin the policy at base names" : "a signer the policy at base lists";
-      const reason = allowed
-        ? `signed by ${v.principal}, ${who.replace(/^an? /, "")}`
-        : v.level === "attested"
-          ? `signed by ${v.principal}, who is not ${who}`
-          : `${paths.join(", ")} is protected and needs a signature by ${who}: ${v.reason}`;
-      report.protectedWrites.push({ commit, paths, level: v.level, ...(v.principal ? { principal: v.principal } : {}), allowed, reason });
-      if (!allowed) report.failures.push(`${commit.slice(0, 8)} changes ${paths.join(", ")}: ${reason}`);
+    for (const [commit, paths] of touching) judge(commit, paths);
+  }
+
+  // The write scope in the declaration at base (#3079): a commit that changes writeScope or agents.
+  const scoped = scopedDeclarationAt(repo, opts.cwd ?? repo, base.commit);
+  if (scoped) {
+    const files = DECLARATION_FILES.map((name) => posix.join(scoped.dir, name));
+    const changed = changedBlocks(scopeState(repo, mergeBase, scoped.dir), scopeState(repo, head, scoped.dir));
+    report.declaration = { path: files.find((f) => fileAt(repo, base.commit!, f) !== undefined) ?? files[0], blocks: scoped.blocks, changed };
+    if (changed.length > 0) {
+      let accounted = false;
+      for (const [commit, paths] of commitsTouching(repo, `${base.commit}..${head}`, files)) {
+        const after = scopeState(repo, commit, scoped.dir);
+        // A merge changes a block only when it differs from every parent.
+        const per = (parentList.get(commit) ?? []).map((p) => new Set(changedBlocks(scopeState(repo, p, scoped.dir), after)));
+        const blocks = SCOPE_BLOCKS.filter((b) => per.length > 0 && per.every((s) => s.has(b)));
+        if (blocks.length === 0) continue;
+        accounted = true;
+        judge(commit, paths, blocks);
+      }
+      if (!accounted) {
+        report.failures.push(`${changed.join(" and ")} in ${report.declaration.path} differ from base, and no commit in the change accounts for it`);
+      }
     }
   }
 

package/src/workspace/write-scope.test.ts

@@ -371,6 +371,24 @@ describe("chant workspace agent: what a session reloads from (#2548)", () => {
     agent.expectValid(doc);
     expect(code(doc)).toBe("agent-unknown");
   });
+
+  test("a declaration that fails validation is declaration-invalid, with the problem, not declaration-missing (#3433)", async () => {
+    const broken = JSON.stringify({ name: "studio", schema: 1, members: [{ name: "app", dir: "app" }], agents: AGENTS });
+    for (const committed of [false, true]) {
+      const dir = repo({ "chant.workspace.json": broken, "app/server.mjs": "export {};\n" }, committed);
+      if (committed) git(dir, "branch", "-M", "main");
+      const doc = await agentSession({ cwd: dir, name: "app-agent" });
+      agent.expectValid(doc);
+      expect(code(doc), committed ? "committed on main" : "uncommitted").toBe("declaration-invalid");
+      expect("error" in doc ? doc.error.message : "").toMatch(/kind/);
+    }
+  });
+
+  test("no declaration at all is still declaration-missing", async () => {
+    const doc = await agentSession({ cwd: repo({ "app/server.mjs": "export {};\n" }), name: "app-agent" });
+    agent.expectValid(doc);
+    expect(code(doc)).toBe("declaration-missing");
+  });
 });
 
 describe("principal classes a plugin defines (#3080)", () => {

package/src/workspace/write-scope.ts

@@ -352,18 +352,28 @@ export interface ScopeSource {
   policy: TrustPolicy;
   /** The principal classes: the core four and those the declaration's pins supply, path pins read where the declaration was (#3080). */
   classes: ClassRegistry;
+  /** Why the working tree's declaration couldn't be read when `declaration` is null: declaration-missing, or declaration-invalid with the problem (#3433). */
+  failure?: WorkspaceReadError;
 }
 
-function readAt(cwd: string, at?: string): { declaration: Declaration; rootOnDisk: string; root: string; tree: WorkspaceTree } | null {
+type ReadAt = { declaration: Declaration; rootOnDisk: string; root: string; tree: WorkspaceTree };
+
+/** The declaration at `at` (the working tree without it), or the read error that says why there is none. */
+function readOrFailure(cwd: string, at?: string): ReadAt | WorkspaceReadError {
   try {
     const located = locateWorkspace(cwd, at);
     return { declaration: readDeclaration(located.tree), rootOnDisk: located.rootOnDisk, root: located.root, tree: located.tree };
   } catch (err) {
-    if (err instanceof WorkspaceReadError) return null;
+    if (err instanceof WorkspaceReadError) return err;
     throw err;
   }
 }
 
+function readAt(cwd: string, at?: string): ReadAt | null {
+  const read = readOrFailure(cwd, at);
+  return read instanceof WorkspaceReadError ? null : read;
+}
+
 /**
  * The scope for a write from `cwd`: the declaration and the trust policy at
  * the base revision (`origin/HEAD`, `main` or `master`), so a write can't
@@ -375,7 +385,7 @@ export function scopeSource(cwd: string, at?: string): ScopeSource {
   const top = gitRoot(cwd);
   const base = top ? resolveBase(top, at) : null;
   const policy = top && base ? policyAtBase(top, base) : emptyPolicy(null);
-  const withClasses = (read: NonNullable<ReturnType<typeof readAt>>) => {
+  const withClasses = (read: ReadAt) => {
     const { tree, ...rest } = read;
     return { ...rest, classes: loadClassRegistry(read.declaration.pins, read.rootOnDisk, { tree }).registry };
   };
@@ -383,8 +393,9 @@ export function scopeSource(cwd: string, at?: string): ScopeSource {
     const atBase = readAt(cwd, base.commit);
     if (atBase) return { ...withClasses(atBase), from: "base", policy };
   }
-  const here = readAt(cwd);
-  return here ? { ...withClasses(here), from: "working-tree", policy } : { declaration: null, from: null, rootOnDisk: null, root: null, policy, classes: coreClassRegistry() };
+  const here = readOrFailure(cwd);
+  if (here instanceof WorkspaceReadError) return { declaration: null, from: null, rootOnDisk: null, root: null, policy, classes: coreClassRegistry(), failure: here };
+  return { ...withClasses(here), from: "working-tree", policy };
 }
 
 const toPosix = (p: string) => (sep === "/" ? p : p.split(sep).join("/"));