src/signed-docs.ts

Functions

Imports

It imports src/auth.ts, src/env.ts. Imported by src/auto-merge-policy.ts, src/gate-policy.ts, src/job-signing.ts, src/jobs-begin.ts, src/jobs-claim.ts, src/jobs-seat.ts, src/namespace-delete.ts, src/policy-sign.ts, src/routine-fire.ts, src/shadow.ts, src/tools/docs-write.ts, src/tools/lint.ts.

Source

1import { hmacHex, sha256Hex } from "./auth";
2import { safeEqual } from "@dustinedwards/site-runtime/compare";
3import type { Env } from "./env";
4
5// The Worker signs the documents it later acts on: a job's body (src/jobs-claim.ts) and
6// the two autonomy policies (src/policy-sign.ts). One key, derived from
7// IMPROVE_SCORE_SECRET under its own context string, distinct from the backup
8// credential's (src/signed-requests.ts) on purpose.
9//
10// The context string keeps the improve loop's name, where this signing began: changing
11// it would invalidate every signed job and policy already stored.
12const TASK_KEY_CONTEXT = "capsid-improve-task:v1";
13
14export async function deriveTaskKey(rootSecret: string): Promise<string> {
15  return hmacHex(rootSecret, TASK_KEY_CONTEXT);
16}
17
18export const TASK_SIGNATURE_FIELD = "capsid-task-signature";
19
20const FRONTMATTER = /^---\n([\s\S]*?)\n---\n/;
21
22/**
23 * Split a signed document into its frontmatter signature and the signed body.
24 *
25 * `strayLines` counts every frontmatter line other than the one signature line.
26 * signTaskBody writes exactly one line there, and the HMAC does not cover the
27 * frontmatter, so any other line is unsigned text sitting beside the signature.
28 * verifySignedBody refuses a document that carries one.
29 */
30export function splitSignedTask(text: string): { signature: string | null; body: string; strayLines: number } {
31  const match = FRONTMATTER.exec(text);
32  if (!match) return { signature: null, body: text, strayLines: 0 };
33  const lines = match[1].split("\n").map((l) => l.trim());
34  const line = lines.find((l) => l.startsWith(`${TASK_SIGNATURE_FIELD}:`));
35  const strayLines = lines.length - (line === undefined ? 0 : 1);
36  const body = text.slice(match[0].length);
37  if (!line) return { signature: null, body, strayLines };
38  return { signature: line.slice(`${TASK_SIGNATURE_FIELD}:`.length).trim(), body, strayLines };
39}
40
41/** Wrap a rendered task body in the frontmatter block carrying its signature. */
42export async function signTaskBody(rootSecret: string, body: string): Promise<string> {
43  const key = await deriveTaskKey(rootSecret);
44  const signature = await hmacHex(key, body);
45  return `---\n${TASK_SIGNATURE_FIELD}: ${signature}\n---\n${body}`;
46}
47
48// `body` is the text the signature covers. A caller that reads fields from a signed
49// document parses this, never the stored text, because the stored text also holds
50// the frontmatter and the frontmatter is not signed.
51export type TaskVerification = { ok: true; body: string } | { ok: false; reason: string };
52
53// The signature check. A job is posted by a human seat, so its audit actor is that seat
54// and only the signature proves it went through `post`. One implementation for every
55// caller, so they cannot drift on what "signed" means.
56export async function verifySignedBody(
57  rootSecret: string | undefined,
58  stored: string,
59  what: string
60): Promise<TaskVerification> {
61  if (!rootSecret) {
62    return { ok: false, reason: `signing is not configured on this Worker (IMPROVE_SCORE_SECRET is unset), so no ${what} can be verified. Refusing rather than executing an unverifiable plan.` };
63  }
64  const { signature, body, strayLines } = splitSignedTask(stored);
65  if (!signature) {
66    return {
67      ok: false,
68      reason: `this ${what} carries no ${TASK_SIGNATURE_FIELD} frontmatter line. The Worker signs every one it writes, so an unsigned one did not come from it. Refusing to execute it.`,
69    };
70  }
71  if (strayLines > 0) {
72    return {
73      ok: false,
74      reason: `this ${what}'s frontmatter holds ${strayLines} line(s) besides the ${TASK_SIGNATURE_FIELD} line. The signature does not cover the frontmatter and the Worker writes only that one line there, so the extra lines were added after signing. Refusing to execute it.`,
75    };
76  }
77  const key = await deriveTaskKey(rootSecret);
78  const expected = await hmacHex(key, body);
79  if (!await safeEqual(signature.toLowerCase(), expected)) {
80    return {
81      ok: false,
82      reason: `this ${what}'s ${TASK_SIGNATURE_FIELD} does not match its body. It was edited after the Worker wrote it. Refusing to execute it.`,
83    };
84  }
85  return { ok: true, body };
86}
87
88// One reader for both signed policies (capsid/policy/auto-merge.md and gates.md). Both
89// are read, verified and parsed the same way, so a fix to that path is made once. Each
90// loader keeps only what differs: which document, and what its parsed lists must agree
91// with. It lives beside the verifier so one refused-list entry covers both.
92const POLICY_NAMESPACE = "capsid";
93
94// Where the signed policies live. sign_policy signs nothing outside it.
95export const POLICY_PREFIX = "policy/";
96
97/**
98 * The ordinary write tools refuse a policy document. The Worker reads them as
99 * authority: capsid/policy/auto-merge.md says what it may merge with no human, and
100 * capsid/policy/gates.md which blocked commands the seat may approve without one. So
101 * a write here is a ruling, accepted only with allow_improve_paths (a name kept from
102 * the improve loop, removed 2026-10-19), which needs can_touch_protected.
103 */
104export function policyWriteRefusal(namespace: string, path: string, allow: boolean): string | null {
105  if (allow || !path.startsWith(POLICY_PREFIX)) return null;
106  return `${namespace}/${path} is an autonomy policy document. It decides what this Worker may do without a human, so a write here is a ruling. Pass allow_improve_paths: true to write it anyway; the flag needs the can_touch_protected scope and is audit-logged.`;
107}
108
109/**
110 * Read capsid/<path> and return the signed body, or a refusal. `ifAbsent` finishes
111 * the sentence that reports a missing document ("so nothing is auto-merged").
112 */
113export async function readSignedPolicy(
114  env: Pick<Env, "DB" | "IMPROVE_SCORE_SECRET" | "APP_KV">,
115  path: string,
116  what: string,
117  ifAbsent: string
118): Promise<{ body: string } | { error: string }> {
119  const row = await env.DB.prepare("SELECT body FROM documents WHERE namespace = ?1 AND path = ?2")
120    .bind(POLICY_NAMESPACE, path)
121    .first<{ body: string | null }>();
122  if (!row) return { error: `no ${what} at ${POLICY_NAMESPACE}/${path}, so ${ifAbsent}.` };
123  const verdict = await verifySignedBody(env.IMPROVE_SCORE_SECRET, row.body ?? "", what);
124  if (!verdict.ok) return { error: verdict.reason };
125  // The signed body only. The stored text also holds the unsigned frontmatter.
126  const rollback = await checkPolicyPin(env, path, what, verdict.body);
127  if (rollback) return { error: rollback };
128  return { body: verdict.body };
129}
130
131// Anti-rollback. A signature proves the Worker signed these bytes once, not that they
132// are current. Every signed version stays in document_versions, and `capsid_write_doc`
133// action restore or a plain write can put an older one back with its signature still verifying. So APP_KV
134// records, under policyPinKey(path), the sha256 of the current signed body (plus its
135// `- version:` for the refusal text), and a load refuses any other signed body.
136// The pin is the hash, not the version, because a lower version signed on purpose (the
137// seat withdrawing a change) must hold, and a higher version put back after it must
138// not. sign_policy writes it before storing the signed document, so the body it signs
139// becomes the only one that loads; re-signing the same body writes the same hash. A
140// load writes it only when no record exists yet, pinning the signed body stored then.
141export const policyPinKey = (path: string): string => `policy:signed:${path}`;
142
143export interface PolicyPin {
144  sha256: string;
145  version: string | null;
146}
147
148export async function policyPin(body: string): Promise<PolicyPin> {
149  return { sha256: await sha256Hex(body), version: policyField(body, "version") };
150}
151
152/** A refusal when `body` is not the signed body recorded for `path`, or null. */
153async function checkPolicyPin(
154  env: Pick<Env, "APP_KV">,
155  path: string,
156  what: string,
157  body: string
158): Promise<string | null> {
159  const current = await policyPin(body);
160  const cannot = (step: string, err: unknown) =>
161    `the ${what}'s anti-rollback record (${policyPinKey(path)}) could not be ${step} (${err instanceof Error ? err.message : String(err)}), so the stored policy is not shown to be the last one signed. Refusing rather than loading it.`;
162  let raw: string | null;
163  try {
164    raw = await env.APP_KV.get(policyPinKey(path));
165  } catch (err) {
166    return cannot("read", err);
167  }
168  if (raw === null) {
169    try {
170      await env.APP_KV.put(policyPinKey(path), JSON.stringify(current));
171    } catch (err) {
172      return cannot("written", err);
173    }
174    return null;
175  }
176  let pinned: PolicyPin;
177  try {
178    pinned = JSON.parse(raw) as PolicyPin;
179  } catch (err) {
180    return cannot("parsed", err);
181  }
182  if (pinned.sha256 === current.sha256) return null;
183  return `the stored ${what} (version ${current.version ?? "unnamed"}, body sha256 ${current.sha256.slice(0, 12)}) is signed but is not the one last signed (version ${pinned.version ?? "unnamed"}, body sha256 ${String(pinned.sha256).slice(0, 12)}). An older signed copy put back in place is refused. If this copy is meant to be current, sign it again with sign_policy.`;
184}
185
186/** The value of the first `- <name>: <value>` line in a policy body, or null. */
187export function policyField(body: string, name: string): string | null {
188  const line = body
189    .split("\n")
190    .map((l) => l.trim())
191    .find((l) => l.toLowerCase().startsWith(`- ${name}:`));
192  return line ? line.slice(line.indexOf(":") + 1).trim() : null;
193}
194
195// A check or class id: a backticked lowercase name at the head of a list item. Matching
196// the backticks, not any list item, keeps the prose around the list out of the policy.
197export const POLICY_ID_ITEM = /^- `([a-z_]+)`/;