src/policy-sign.ts

Functions

Imports

It imports src/auth.ts, src/auto-merge-policy.ts, src/env.ts, src/github/contents.ts, src/signed-docs.ts, src/store-guards.ts. Imported by src/controls-perform.ts, src/controls-plan.ts, src/tools/status.ts.

Source

1import type { Env } from "./env";
2import { sha256Hex } from "./auth";
3import { POLICY_PREFIX, policyPin, policyPinKey, signTaskBody, splitSignedTask } from "./signed-docs";
4import { auditStatement, documentUpsert, isMissingRowAbort, requireBodyUnchanged, snapshotLive } from "./store-guards";
5import { AUTO_MERGE_POLICY_PATH, checkMergePolicyBody, loadMergePolicy, parseMergePolicy } from "./auto-merge-policy";
6import { readRepoFile } from "./github/contents";
7
8// Signing a policy document: the one path that mints the signature the auto-merge and
9// gate policies are verified against. Its constraints:
10//
11//   1. Admin only, enforced at the tool layer: an agent that could sign a policy could
12//      widen itself.
13//   2. capsid/policy/ only, checked here as well as at the tool, so no second caller
14//      can point it elsewhere.
15//   3. It signs what is already stored. There is no body argument, so this cannot sign
16//      arbitrary bytes.
17//   4. It re-signs rather than nesting: existing frontmatter is stripped first.
18//
19// The write snapshots the prior row and appends to audit_log in one batch
20// (test/write-invariants.test.ts).
21
22export interface PolicySignResult {
23  ok: true;
24  action: "sign_policy";
25  namespace: string;
26  path: string;
27  signature: string;
28  // Of the signed body as stored.
29  sha256: string;
30  bytes: number;
31  resigned: boolean;
32}
33
34export interface PolicySignRefusal {
35  ok: false;
36  action: "sign_policy";
37  error: string;
38}
39
40const POLICY_SIGN_NAMESPACE = "capsid";
41
42export async function signPolicyDocument(
43  env: Env,
44  actor: string,
45  namespace: string,
46  path: string
47): Promise<PolicySignResult | PolicySignRefusal> {
48  const refuse = (error: string): PolicySignRefusal => ({ ok: false, action: "sign_policy", error });
49
50  if (namespace !== POLICY_SIGN_NAMESPACE) {
51    return refuse(
52      `sign_policy only signs documents in '${POLICY_SIGN_NAMESPACE}', and this asked for '${namespace}'. The policies this Worker reads live in one namespace.`
53    );
54  }
55  if (!path.startsWith(POLICY_PREFIX) || path.includes("..")) {
56    return refuse(
57      `sign_policy only signs documents under '${POLICY_PREFIX}', and this asked for '${path}'. A signature is authority, so the set of paths that can carry one is fixed.`
58    );
59  }
60  if (!env.IMPROVE_SCORE_SECRET) {
61    return refuse("signing is not configured on this Worker (IMPROVE_SCORE_SECRET is unset), so no policy can be signed.");
62  }
63
64  const prior = await env.DB.prepare("SELECT title, body FROM documents WHERE namespace = ?1 AND path = ?2")
65    .bind(namespace, path)
66    .first<{ title: string | null; body: string | null }>();
67  if (!prior) {
68    return refuse(`no document at ${namespace}/${path}. Write the policy first, read it, then sign it.`);
69  }
70
71  const stored = prior.body ?? "";
72  const { signature: existing, body } = splitSignedTask(stored);
73  if (body.trim().length === 0) {
74    return refuse(`${namespace}/${path} has an empty body below its frontmatter. An empty policy authorises nothing and is not signed.`);
75  }
76  const committed = await commitSigned(env, "sign_policy", namespace, path, prior, body, (sig, sha, bytes) =>
77    // The signature and hash, not the body, which the document and snapshot hold.
78    auditStatement(env.DB, actor, "policy-signed", namespace, path, { signature: sig, sha256: sha, bytes, resigned: existing !== null })
79  );
80  if (!committed.ok) return refuse(committed.error);
81  const { signature, sha256, signed } = committed;
82
83  return {
84    ok: true,
85    action: "sign_policy",
86    namespace,
87    path,
88    signature: signature ?? "",
89    sha256,
90    bytes: signed.length,
91    resigned: existing !== null,
92  };
93}
94
95/** Sign `body` and write it over the stored policy at `path`: the anti-rollback pin first,
96 *  then one batch that refuses if the stored body changed since `prior` was read,
97 *  snapshots the prior row, writes the signed body and the audit row
98 *  (test/write-invariants.test.ts). */
99async function commitSigned(
100  env: Env,
101  caller: string,
102  namespace: string,
103  path: string,
104  prior: { title: string | null; body: string | null },
105  body: string,
106  audit: (signature: string | null, sha256: string, bytes: number) => D1PreparedStatement
107): Promise<{ ok: true; signed: string; signature: string | null; sha256: string } | { ok: false; error: string }> {
108  const signed = await signTaskBody(env.IMPROVE_SCORE_SECRET!, body);
109  const { signature } = splitSignedTask(signed);
110  const sha256 = await sha256Hex(signed);
111  // The anti-rollback record is written first: from here on the loaders accept this
112  // body and no other signed copy (policyPin in signed-docs.ts). Written before the
113  // store so every failure refuses, including a store that aborts below.
114  try {
115    await env.APP_KV.put(policyPinKey(path), JSON.stringify(await policyPin(body)));
116  } catch (err) {
117    return {
118      ok: false,
119      error: `the anti-rollback record for ${namespace}/${path} could not be written (${err instanceof Error ? err.message : String(err)}). Nothing was signed or written. Sign it again.`,
120    };
121  }
122  // The body guard goes first, so an edit after the read aborts rather than being
123  // replaced by the signed older body.
124  try {
125    await env.DB.batch([
126      requireBodyUnchanged(env.DB, namespace, path, prior.body),
127      snapshotLive(env.DB, namespace, path),
128      documentUpsert(env.DB, namespace, path, prior.title, signed, null, null, null),
129      audit(signature, sha256, signed.length),
130    ]);
131  } catch (err) {
132    if (isMissingRowAbort(err)) {
133      // The pin above already moved, so the message says so: until the next signing the
134      // loaders accept only the body read here, not whatever the document holds now.
135      return {
136        ok: false,
137        error:
138          `${namespace}/${path} changed or was removed after ${caller} read it, so the document was not written. ` +
139          `Its anti-rollback record (${policyPinKey(path)}) already names the body ${caller} read, so the stored policy does not load until it is signed again. ` +
140          `Read the policy again and sign it again.`,
141      };
142    }
143    throw err;
144  }
145  return { ok: true, signed, signature, sha256 };
146}
147
148// ---------------------------------------------------------------------------
149// sign_policy_change (docs/design/design-merge-pipeline.md section 7, PR 10; Dustin's
150// DECIDE 9 of 2026-10-09): promoting a merge unit to auto, or removing one, writes the
151// next version of the auto-merge policy and signs it in one admin control. It widens
152// autonomy, so the perform needs the new version number typed as confirm. It edits only
153// two things in the stored, signed policy: the version line, and one line of the
154// `## Auto units` section. The new body must load as the old one did (the same checks,
155// paths and steps the code enforces), or nothing is written.
156
157type PolicyChange = "promote" | "demote";
158
159export type PolicyChangePlan =
160  | { ok: true; from: string; to: string; unit: string; change: PolicyChange; body: string; prior: { title: string | null; body: string }; changes: string[] }
161  | { ok: false; error: string };
162
163const UNITS_SECTION = "## Auto units";
164const UNITS_INTRO = "Merge units promoted to auto by a signed policy change (sign_policy_change), each a namespace and a path class. A unit widens only the namespace's allowed paths; refused paths, money, migrations and workflows still refuse.";
165
166/** `capsid/tests` or `capsid / tests` as the policy writes it, or null. */
167function normalUnit(raw: string | undefined): string | null {
168  const m = /^\s*([a-z0-9-]+)\s*\/\s*([a-z-]+)\s*$/.exec(raw ?? "");
169  return m ? `${m[1]} / ${m[2]}` : null;
170}
171
172/** The body with the version bumped and one unit line added or removed. */
173function editPolicy(body: string, to: string, change: PolicyChange, unit: string): string {
174  const lines = body.split("\n");
175  const v = lines.findIndex((l) => /^\s*- version:/i.test(l));
176  lines[v] = `- version: ${to}`;
177  const line = `- unit \`${unit}\``;
178  const head = lines.findIndex((l) => l.trim().toLowerCase() === UNITS_SECTION.toLowerCase());
179  if (change === "demote") return lines.filter((l) => l.trim() !== line).join("\n");
180  if (head < 0) return `${lines.join("\n").replace(/\s*$/, "")}\n\n${UNITS_SECTION}\n\n${UNITS_INTRO}\n\n${line}\n`;
181  let end = lines.findIndex((l, i) => i > head && l.trim().startsWith("##"));
182  if (end < 0) end = lines.length;
183  let at = head + 1;
184  for (let i = head + 1; i < end; i++) if (lines[i]!.trim().startsWith("- unit ")) at = i + 1;
185  if (at === head + 1) {
186    lines.splice(at, 0, "", line);
187  } else {
188    lines.splice(at, 0, line);
189  }
190  return lines.join("\n");
191}
192
193/** What sign_policy_change will write, from the signed policy now. Reads only. */
194export async function planPolicyChange(env: Env, change: string | undefined, rawUnit: string | undefined): Promise<PolicyChangePlan> {
195  const refuse = (error: string): PolicyChangePlan => ({ ok: false, error });
196  if (change !== "promote" && change !== "demote") return refuse(`sign_policy_change needs change: promote or demote; got '${change ?? ""}'.`);
197  const unit = normalUnit(rawUnit);
198  if (!unit) return refuse(`sign_policy_change needs unit as '<namespace>/<path class>', for example 'capsid/tests'; got '${rawUnit ?? ""}'.`);
199  if (!env.IMPROVE_SCORE_SECRET) return refuse("signing is not configured on this Worker (IMPROVE_SCORE_SECRET is unset), so no policy can be signed.");
200  // The policy in force must load first: a change is made to a policy the Worker trusts.
201  const loaded = await loadMergePolicy(env);
202  if ("error" in loaded) return refuse(`the auto-merge policy in force does not load, so it is not changed: ${loaded.error}`);
203  const from = loaded.policy.version;
204  if (!/^[1-9][0-9]{0,5}$/.test(from)) return refuse(`the policy's version is '${from}', not a whole number, so its next version cannot be named.`);
205  const to = String(Number(from) + 1);
206  const listed = loaded.policy.units.includes(unit);
207  if (change === "promote" && listed) return refuse(`${unit} is already promoted to auto in version ${from}.`);
208  if (change === "demote" && !listed) return refuse(`${unit} is not promoted to auto in version ${from}, so there is nothing to remove.`);
209  const prior = await env.DB.prepare("SELECT title, body FROM documents WHERE namespace = ?1 AND path = ?2")
210    .bind(POLICY_SIGN_NAMESPACE, AUTO_MERGE_POLICY_PATH)
211    .first<{ title: string | null; body: string | null }>();
212  if (!prior?.body) return refuse(`no document at ${POLICY_SIGN_NAMESPACE}/${AUTO_MERGE_POLICY_PATH}.`);
213  const body = editPolicy(splitSignedTask(prior.body).body, to, change, unit);
214  // Parsed as the loader will parse it: an unknown class, money or a namespace the policy
215  // does not cover refuses here, before anything is signed.
216  const parsed = parseMergePolicy(body);
217  if ("error" in parsed) return refuse(`the edited policy would not load: ${parsed.error}`);
218  if (parsed.policy.version !== to || parsed.policy.units.includes(unit) !== (change === "promote")) {
219    return refuse("the edited policy does not say what the change asked for, so nothing is written. Edit the policy by hand.");
220  }
221  return {
222    ok: true,
223    from,
224    to,
225    unit,
226    change,
227    body,
228    prior: { title: prior.title, body: prior.body },
229    changes: [
230      `${POLICY_SIGN_NAMESPACE}/${AUTO_MERGE_POLICY_PATH}: version ${from} -> ${to}, signed. Version ${from} is snapshotted, and from now the loaders accept version ${to} and no older copy (the anti-rollback pin).`,
231      change === "promote"
232        ? `${unit} is added under ${UNITS_SECTION}: its pull requests may merge with no human when every other check passes. It widens only the allowed paths; refused paths, money, migrations and workflows still refuse.`
233        : `${unit} is removed from ${UNITS_SECTION}: its pull requests wait for an approval again.`,
234      `Type ${to} as confirm to sign it.`,
235    ],
236  };
237}
238
239/** The write: the plan again from the state now, the typed version checked, then signed. */
240export async function performPolicyChange(env: Env, actor: string, change: string | undefined, rawUnit: string | undefined, confirm: string | undefined): Promise<{ ok: true; summary: string } | { ok: false; error: string }> {
241  const plan = await planPolicyChange(env, change, rawUnit);
242  if (!plan.ok) return plan;
243  if (!confirm) return { ok: false, error: `sign_policy_change widens or narrows what merges with no human, so it needs the new version number typed as confirm: ${plan.to}.` };
244  if (confirm !== plan.to) return { ok: false, error: `confirm is '${confirm}', but the new version is ${plan.to}. Nothing was signed.` };
245  const committed = await commitSigned(env, "sign_policy_change", POLICY_SIGN_NAMESPACE, AUTO_MERGE_POLICY_PATH, plan.prior, plan.body, (signature, sha256, bytes) =>
246    auditStatement(env.DB, actor, "policy-changed", POLICY_SIGN_NAMESPACE, AUTO_MERGE_POLICY_PATH, { from: plan.from, to: plan.to, change: plan.change, unit: plan.unit, signature, sha256, bytes })
247  );
248  if (!committed.ok) return committed;
249  return { ok: true, summary: `Signed auto-merge policy version ${plan.to}: ${plan.unit} ${plan.change === "promote" ? "promoted to auto" : "removed from auto"}.` };
250}
251
252// ---------------------------------------------------------------------------
253// sign_policy_from_repo: the reviewable source of the auto-merge policy is
254// docs/policy/auto-merge.md on the default branch, and the stored, signed copy is written
255// from it. This control does that in one admin step instead of a capsid_write_doc and a
256// sign_policy by hand. The preview reads the file from GitHub, holds it to the checks
257// loadMergePolicy makes (checkMergePolicyBody) and shows the old and new hash and the
258// lines that differ. The perform reads it again and refuses if it is not the text the
259// preview showed, then writes and signs it through commitSigned. It widens or narrows
260// autonomy as the document says, so the version number typed as confirm is the version in
261// the file. The stored policy in force need not load: this is also the way to replace one
262// that does not.
263
264/** The reviewable source, on the capsid repo's default branch. */
265export const REPO_POLICY_PATH = "docs/policy/auto-merge.md";
266
267export type RepoPolicyPlan =
268  | {
269      ok: true;
270      // The stored policy's version, or null when what is stored has no readable version.
271      from: string | null;
272      to: string;
273      // Of the unsigned body stored now, and of the file in the repo.
274      oldSha: string;
275      newSha: string;
276      body: string;
277      prior: { title: string | null; body: string };
278      added: string[];
279      removed: string[];
280      changes: string[];
281    }
282  | { ok: false; error: string };
283
284const SHOWN_LINES = 12;
285
286/** The lines each text has that the other lacks, as a multiset: order is not compared, which
287 *  is enough to say how much changed and to show a reader what. */
288function lineDelta(before: string, after: string): { added: string[]; removed: string[] } {
289  const count = (text: string): Map<string, number> => {
290    const m = new Map<string, number>();
291    for (const l of text.split("\n")) m.set(l, (m.get(l) ?? 0) + 1);
292    return m;
293  };
294  const a = count(before);
295  const b = count(after);
296  // The lines of `source` beyond the number `against` has of each.
297  const surplus = (source: string, own: Map<string, number>, against: Map<string, number>): string[] => {
298    const out: string[] = [];
299    const seen = new Map<string, number>();
300    for (const l of source.split("\n")) {
301      const n = (seen.get(l) ?? 0) + 1;
302      seen.set(l, n);
303      if (n > (against.get(l) ?? 0) && n <= (own.get(l) ?? 0)) out.push(l);
304    }
305    return out;
306  };
307  return { added: surplus(after, b, a), removed: surplus(before, a, b) };
308}
309
310function shownLines(label: "added" | "removed", lines: string[]): string[] {
311  const real = lines.filter((l) => l.trim().length > 0);
312  const mark = label === "added" ? "+" : "-";
313  const more = real.length > SHOWN_LINES ? [`... and ${real.length - SHOWN_LINES} more ${label} lines.`] : [];
314  return [...real.slice(0, SHOWN_LINES).map((l) => `${mark} ${l}`), ...more];
315}
316
317/** What sign_policy_from_repo will write: the repo's file now against the stored policy.
318 *  Reads only. */
319export async function planPolicyFromRepo(env: Env): Promise<RepoPolicyPlan> {
320  const refuse = (error: string): RepoPolicyPlan => ({ ok: false, error });
321  if (!env.IMPROVE_SCORE_SECRET) return refuse("signing is not configured on this Worker (IMPROVE_SCORE_SECRET is unset), so no policy can be signed.");
322  let content: string;
323  try {
324    // Fresh, not the read cache: the perform compares this read with the preview's.
325    content = (await readRepoFile(env, POLICY_SIGN_NAMESPACE, REPO_POLICY_PATH, undefined, undefined, true)).content;
326  } catch (err) {
327    return refuse(`${REPO_POLICY_PATH} could not be read from the ${POLICY_SIGN_NAMESPACE} repo's default branch, so nothing is signed: ${err instanceof Error ? err.message : String(err)}`);
328  }
329  if (splitSignedTask(content).signature !== null || content.startsWith("---\n")) {
330    return refuse(`${REPO_POLICY_PATH} opens with frontmatter. The repo file is the unsigned source, and the signature is added here, so nothing is signed.`);
331  }
332  if (content.trim().length === 0) return refuse(`${REPO_POLICY_PATH} is empty. An empty policy authorises nothing and is not signed.`);
333  // The checks the loader makes, so what is signed here is a body the Worker will load.
334  const loaded = checkMergePolicyBody(content);
335  if ("error" in loaded) return refuse(`${REPO_POLICY_PATH} would not load, so nothing is signed: ${loaded.error}`);
336  const to = loaded.policy.version;
337  if (!/^[1-9][0-9]{0,5}$/.test(to)) return refuse(`${REPO_POLICY_PATH} says version '${to}', not a whole number, so the version to type as confirm cannot be named.`);
338
339  const prior = await env.DB.prepare("SELECT title, body FROM documents WHERE namespace = ?1 AND path = ?2")
340    .bind(POLICY_SIGN_NAMESPACE, AUTO_MERGE_POLICY_PATH)
341    .first<{ title: string | null; body: string | null }>();
342  if (!prior?.body) {
343    return refuse(`no document at ${POLICY_SIGN_NAMESPACE}/${AUTO_MERGE_POLICY_PATH} to write over. Write it once with capsid_write_doc (allow_improve_paths), and this control keeps it in step with the repo.`);
344  }
345  const stored = splitSignedTask(prior.body).body;
346  const storedParsed = parseMergePolicy(stored);
347  const from = "policy" in storedParsed ? storedParsed.policy.version : null;
348  const oldSha = await sha256Hex(stored);
349  const newSha = await sha256Hex(content);
350  if (oldSha === newSha) return refuse(`${REPO_POLICY_PATH} is the policy already stored, so there is nothing to sign.`);
351  // Two different documents under one version number would muddle the history. The pin
352  // keeps a rollback out of the loaders, but not that.
353  if (from !== null && /^[1-9][0-9]{0,5}$/.test(from) && Number(to) <= Number(from)) {
354    return refuse(`${REPO_POLICY_PATH} says version ${to}, and the stored policy is version ${from}. Raise the version in the file before signing it.`);
355  }
356  const { added, removed } = lineDelta(stored, content);
357  return {
358    ok: true,
359    from,
360    to,
361    oldSha,
362    newSha,
363    body: content,
364    prior: { title: prior.title, body: prior.body },
365    added,
366    removed,
367    changes: [
368      `${POLICY_SIGN_NAMESPACE}/${AUTO_MERGE_POLICY_PATH}: ${from === null ? "the stored body has no readable version" : `version ${from}`} -> ${to}, written exactly as ${REPO_POLICY_PATH} reads on the default branch now, and signed. The stored version is snapshotted, and from now the loaders accept this body and no older copy (the anti-rollback pin).`,
369      `sha256 of the body: ${oldSha} (stored) -> ${newSha} (repo).`,
370      `Lines changed: ${removed.length} removed, ${added.length} added.`,
371      ...shownLines("removed", removed),
372      ...shownLines("added", added),
373      `Type ${to} as confirm to sign it. The perform reads the file again and is refused if it is not this text.`,
374    ],
375  };
376}
377
378/** The write: the file read again and checked against the preview's hash, the typed version
379 *  checked, then signed through commitSigned. */
380export async function performPolicyFromRepo(env: Env, actor: string, confirm: string | undefined, previewedSha: string | undefined): Promise<{ ok: true; summary: string } | { ok: false; error: string }> {
381  if (!previewedSha) return { ok: false, error: "sign_policy_from_repo carries the hash its preview read, and this confirmation has none. Nothing was signed. Preview again." };
382  const plan = await planPolicyFromRepo(env);
383  if (!plan.ok) return plan;
384  if (plan.newSha !== previewedSha) {
385    return { ok: false, error: `${REPO_POLICY_PATH} changed since the preview (it read ${previewedSha}; it now reads ${plan.newSha}). Nothing was signed. Preview again.` };
386  }
387  if (!confirm) return { ok: false, error: `sign_policy_from_repo changes what merges with no human, so it needs the version number typed as confirm: ${plan.to}.` };
388  if (confirm !== plan.to) return { ok: false, error: `confirm is '${confirm}', but the file's version is ${plan.to}. Nothing was signed.` };
389  const committed = await commitSigned(env, "sign_policy_from_repo", POLICY_SIGN_NAMESPACE, AUTO_MERGE_POLICY_PATH, plan.prior, plan.body, (signature, sha256, bytes) =>
390    auditStatement(env.DB, actor, "policy-loaded-from-repo", POLICY_SIGN_NAMESPACE, AUTO_MERGE_POLICY_PATH, {
391      from: plan.from,
392      to: plan.to,
393      source: REPO_POLICY_PATH,
394      old_sha256: plan.oldSha,
395      new_sha256: plan.newSha,
396      added: plan.added.length,
397      removed: plan.removed.length,
398      signature,
399      sha256,
400      bytes,
401    })
402  );
403  if (!committed.ok) return committed;
404  return { ok: true, summary: `Signed auto-merge policy version ${plan.to} from ${REPO_POLICY_PATH} (${plan.removed.length} lines removed, ${plan.added.length} added).` };
405}