src/controls.ts

Functions

Imports

It imports src/controls-base.ts, src/controls-perform.ts, src/controls-plan.ts, src/controls-token.ts, src/env.ts, src/ops-types/portal.ts. Imported by src/portal-actions.ts, src/tools/controls.ts.

Source

1import type { Env } from "./env";
2import type { PortalAction, PortalPreview } from "./ops-types/portal";
3import { type ActionResult, performAction } from "./controls-perform";
4import { type Plan, planAction } from "./controls-plan";
5import { signConfirm, verifyConfirm } from "./controls-token";
6import { type ActionParams, PORTAL_ACTIONS, type Surface, SWITCHES, UNKNOWN_ACTION } from "./controls-base";
7
8// THE CONTROLS' CORE (capsid/research/design-portal-full-controls.md, section 2): what each
9// admin control is, what it will do, the one dispatch to the shared mutators, and the
10// signed confirmation both surfaces use. It was the body of src/portal-actions.ts; the
11// Portal's routes there and the `capsid_admin_run_controls` tool (src/tools/controls.ts) are its two
12// callers, so a control is implemented once and parity is a property of this file and the
13// controls-*.ts files beside it.
14
15export const TOKEN_TTL_SECONDS = 5 * 60;
16
17/** What each action is about to do, naming the target, for the confirm step. */
18function describeAction(action: PortalAction, params: ActionParams): string {
19  const said = describeOnce(action, params);
20  return params.undo === "true" ? `Undo: ${said}` : said;
21}
22
23function describeOnce(action: PortalAction, params: ActionParams): string {
24  const ns = params.namespace ?? "";
25  const id = params.id ?? "";
26  switch (action) {
27    case "overnight":
28      return params.value === "off"
29        ? "Turn the overnight run OFF. No scheduled run starts; one already running finishes."
30        : params.value === "subscription"
31          ? "Set the overnight run to run on the SUBSCRIPTION. The scheduler may then start the per-namespace drivers on your machine overnight, billed against your Max plan. This records your decision, its date and its reasoning where the switch is set."
32          : "Set the overnight run to run on the API key. The scheduler refuses to start unless it authenticates with ANTHROPIC_API_KEY and no subscription token is in use. Billed per token to your Console account.";
33    case "resume_job":
34      return `Resume blocked job ${id}. The job moves back to claimed under the driver that blocked it, and that driver continues it. It does not move to you. If the job was blocked by a shared identity such as your own admin session, it goes back to the queue with your approval instead, and the next free session claims it.`;
35    case "release_job":
36      return `Release job ${id} back to the queue. Whoever holds it loses the claim, the next free session claims it, and no outcome is recorded against the holder.`;
37    case "fail_job":
38      return `Mark job ${id} failed. This is the seat stepping in on a job it does not hold, and it is recorded as such.`;
39    case "close_shipped":
40      return `Close blocked job ${id} as shipped. Its work landed, so the job moves to done, and the outcome is credited to the driver that did the work, not to you. The pull requests it names are read from GitHub for the outcome, and the close is recorded as yours.`;
41    case "supersede_job":
42      return `Supersede job ${id}${params.replaced_by ? ` with ${params.replaced_by}` : ""}. It ends as superseded, replaced before any work was done: no outcome row is written against anybody.`;
43    case "park_job":
44      return `Park job ${id}. It stays listed but is never claimed or planned until somebody unparks it; the reason says when it comes back.`;
45    case "unpark_job":
46      return `Unpark job ${id}. It goes back to the queue at its priority, and the next free session may claim it.`;
47    case "pr_close":
48      return `Close pull request #${params.number ?? ""} in ${ns}${params.repo ? ` (${params.repo})` : ""} without merging it. Its head branch is deleted as capsid_close_pr action close deletes it. GitHub can reopen it; the Portal does not.`;
49    case "approve_pr":
50      return params.undo === "true"
51        ? `Void the open approval of pull request ${params.prs ?? ""} in ${ns}. The executor will not merge it.`
52        : `Approve pull request ${params.prs ?? ""} in ${ns} at the head you reviewed. Nothing merges now: the executor merges an approved pull request once CI is green on that exact sha, and a new push, red CI or 7 days voids the approval.`;
53    case "revoke_agent":
54      return `Revoke the agent ${params.name ?? ""}. Its key stops resolving immediately. The row stays, so its audit history still reads, and the name can never be minted again.`;
55    case "site_add":
56      return params.origin
57        ? `Add ${ns} to the sites Capsid Portal watches. The watcher probes it from its next pass.`
58        : `Record that ${ns} serves no site, so the site-map check stops reporting it as unmapped.`;
59    case "site_edit":
60      return `Change how Capsid Portal watches ${ns}. The watcher reads the new row on its next pass.`;
61    case "site_remove":
62      return `Remove ${ns} from the Portal's site configuration. The watcher stops probing it on its next pass.`;
63    case "reset_breaker":
64      return `Reset the queue's circuit breaker for ${ns}. Jobs its drivers failed before now stop counting, so ${ns} hands out work again until the threshold is reached anew.`;
65    case "package_add":
66      return `Add the npm package ${params.name ?? ""} to the packages Capsid Portal watches. The watcher reads it from its next pass.`;
67    case "package_edit":
68      return `Change how Capsid Portal watches the package ${params.name ?? ""}. The watcher reads the new row on its next pass.`;
69    case "package_remove":
70      return `Remove the package ${params.name ?? ""} from the Portal. The watcher stops reading it; its weekly rows are kept.`;
71    case "canon_approve":
72      return `Approve canon proposal ${params.id ?? ""}. The document is written as proposed, with the current version snapshotted first, and only if it is still the body the proposal was written against.`;
73    case "canon_reject":
74      return `Reject canon proposal ${params.id ?? ""}. The document is not touched, and the proposer reads your reason.`;
75    case "canon_approve_all":
76      return "Decide every pending canon proposal at once. On each document the newest proposal is approved, written as the single Approve writes it, unless its document moved since it was written; older proposals on the same document, and outdated ones, are rejected with a reason the proposer reads.";
77    case "site_repair":
78      return `Run ${params.tool ?? ""} on ${ns} through its operator API. It re-derives one of the site's stores from its source and reports whether it converged. Capsid calls only the site's allowlisted repairs; it never merges and never mints.`;
79    case "sign_policy_change":
80      return params.change === "demote"
81        ? `Write and sign the next version of the auto-merge policy without the merge unit ${params.unit ?? ""}: its pull requests wait for an approval again.`
82        : `Write and sign the next version of the auto-merge policy with the merge unit ${params.unit ?? ""} promoted to auto: its pull requests may merge with no human when every other check passes. This widens autonomy, so the new version number is typed as confirm.`;
83    case "sign_policy_from_repo":
84      return "Write the auto-merge policy from docs/policy/auto-merge.md on the default branch, exactly as it reads there, and sign it. The version in the file is typed as confirm, because the policy decides what merges with no human.";
85    case "unit_resume":
86      return `Lift the suspension of the merge unit ${params.unit ?? ""}. The tick may merge its pull requests unattended again, and the rollbacks before now suspend it no more.`;
87    case "automerge_resume":
88      return `Lift the pause on auto-merge for ${ns}. The tick may merge its pull requests unattended again, and the rollbacks and reverts before now count against it no more.`;
89  }
90}
91
92// The params each action takes. Anything else is refused rather than carried into a
93// token nobody reads.
94const FIELDS: Record<PortalAction, readonly string[]> = {
95  overnight: ["value", "reason", "undo"],
96  resume_job: ["id", "reason", "note"],
97  release_job: ["id", "reason"],
98  fail_job: ["id", "reason"],
99  close_shipped: ["id", "reason"],
100  supersede_job: ["id", "reason", "replaced_by"],
101  park_job: ["id", "reason", "undo"],
102  unpark_job: ["id", "reason", "undo"],
103  pr_close: ["namespace", "repo", "number", "reason"],
104  approve_pr: ["namespace", "repo", "prs", "shas", "confirm", "reason", "undo"],
105  revoke_agent: ["name"],
106  site_add: ["namespace", "name", "origin", "health_path", "platform", "script", "operator"],
107  site_edit: ["namespace", "revision", "name", "origin", "health_path", "platform", "script", "operator"],
108  site_remove: ["namespace", "revision"],
109  reset_breaker: ["namespace"],
110  package_add: ["name", "repo", "formerly"],
111  package_edit: ["name", "revision", "repo", "formerly"],
112  package_remove: ["name", "revision"],
113  canon_approve: ["id"],
114  canon_reject: ["id", "reason"],
115  // The plan the preview read is bound into the token beside these (Plan.bind), so a
116  // caller cannot send one.
117  canon_approve_all: ["reason"],
118  site_repair: ["namespace", "tool"],
119  sign_policy_change: ["change", "unit", "confirm", "reason"],
120  // The hash its preview read is bound into the token (Plan.bind), so a caller cannot send one.
121  sign_policy_from_repo: ["confirm", "reason"],
122  unit_resume: ["unit", "reason"],
123  automerge_resume: ["namespace", "reason"],
124};
125
126
127/** The action's params from a preview body: only the fields it takes, each a string,
128 *  trimmed, blanks dropped. */
129function paramsFrom(action: PortalAction, raw: unknown): { ok: true; params: Record<string, string> } | { ok: false; refusal: string } {
130  if (raw === undefined) raw = {};
131  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { ok: false, refusal: "params must be an object of strings." };
132  const allowed = FIELDS[action];
133  const params: Record<string, string> = {};
134  for (const [key, value] of Object.entries(raw)) {
135    if (!allowed.includes(key)) {
136      return { ok: false, refusal: `${action} takes ${allowed.join(" and ")}; '${key}' is not one of them.` };
137    }
138    if (typeof value !== "string") return { ok: false, refusal: `${action}'s ${key} must be a string.` };
139    if (value.trim()) params[key] = value.trim();
140  }
141  return { ok: true, params };
142}
143
144// ---------------------------------------------------------------------------
145// The registry and its two doors.
146
147/** One control: its name, the params it takes, whether it needs a reason, and the two
148 *  steps every surface goes through. plan writes nothing. perform calls the one
149 *  mutator that exists for the control, then writes the click's audit row. */
150export interface Control {
151  name: PortalAction;
152  fields: readonly string[];
153  reasonRequired: boolean;
154  plan(env: Env, email: string, params: Record<string, string>, surface: Surface): Promise<Plan>;
155  perform(env: Env, email: string, source: string | null, now: Date, params: ActionParams, surface: Surface): Promise<ActionResult>;
156}
157
158export const CONTROLS: readonly Control[] = PORTAL_ACTIONS.map((name) => ({
159  name,
160  fields: FIELDS[name],
161  reasonRequired: SWITCHES.has(name),
162  plan: (env, email, params, surface) => planAction(env, email, name, params, surface),
163  perform: (env, email, source, now, params, surface) => performAction(env, email, source, now, name, params, surface),
164}));
165
166function controlNamed(name: unknown): Control | null {
167  return typeof name === "string" ? (CONTROLS.find((c) => c.name === name) ?? null) : null;
168}
169
170const randomJti = (): string => {
171  const bytes = crypto.getRandomValues(new Uint8Array(16));
172  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
173};
174
175const NONCE_PREFIX = "control-nonce:";
176
177export type Previewed = { ok: true; preview: PortalPreview } | { ok: false; status: number; refusal: string };
178
179/** The preview step for either surface: validate the name and params, plan from the state
180 *  now (a read, never a write), and sign a confirmation for the email. */
181export async function previewControl(env: Env, email: string, name: unknown, rawParams: unknown, now: Date, surface: Surface): Promise<Previewed> {
182  const control = controlNamed(name);
183  if (!control) return { ok: false, status: 400, refusal: UNKNOWN_ACTION(typeof name === "string" ? name : "") };
184  const parsed = paramsFrom(control.name, rawParams);
185  if (!parsed.ok) return { ok: false, status: 400, refusal: parsed.refusal };
186  const plan = await control.plan(env, email, parsed.params, surface);
187  if (!plan.ok) return { ok: false, status: 400, refusal: plan.refusal };
188  const exp = Math.floor(now.getTime() / 1000) + TOKEN_TTL_SECONDS;
189  const token = await signConfirm(env, { v: 2, jti: randomJti(), action: control.name, params: { ...parsed.params, ...plan.bind }, email, exp });
190  return {
191    ok: true,
192    preview: {
193      action: control.name,
194      summary: describeAction(control.name, parsed.params),
195      changes: plan.changes,
196      audit: plan.audit,
197      token,
198      expires_at: new Date(exp * 1000).toISOString(),
199    },
200  };
201}
202
203export type Performed = { ok: true; action: PortalAction; result: Extract<ActionResult, { ok: true }> } | { ok: false; status: number; refusal: string };
204
205/** The perform step for either surface: the token must verify for the email, then it is
206 *  spent (a confirmation is used once, whichever surface took it), then the control runs.
207 *  A token is spent even when the control then refuses: the refusal is about state, and
208 *  the next try starts from a fresh preview that shows the state as it is. KV has no
209 *  compare-and-set, so two performs of one token inside the same instant could both
210 *  pass the check; every mutator is guarded on the state it moves from, which is what
211 *  stops the second. */
212export async function performControl(env: Env, email: string, token: unknown, source: string | null, now: Date, surface: Surface): Promise<Performed> {
213  if (typeof token !== "string") return { ok: false, status: 400, refusal: "a perform needs the token its preview returned." };
214  const verified = await verifyConfirm(env, token, email, now);
215  if (!verified.ok) return { ok: false, status: verified.status, refusal: verified.refusal };
216  const { action, params, jti, exp } = verified.claims;
217  const control = controlNamed(action);
218  if (!control) return { ok: false, status: 400, refusal: UNKNOWN_ACTION(String(action)) };
219
220  const nonceKey = `${NONCE_PREFIX}${jti}`;
221  if ((await env.APP_KV.get(nonceKey)) !== null) {
222    return { ok: false, status: 409, refusal: "this confirmation was already used: preview again to get a new one." };
223  }
224  // Held until the token itself would have expired, plus a minute for clock skew, and not
225  // under KV's 60 second floor.
226  await env.APP_KV.put(nonceKey, now.toISOString(), { expirationTtl: Math.max(60, exp - Math.floor(now.getTime() / 1000) + 60) });
227
228  const result = await control.perform(env, email, source, now, params, surface);
229  if (!result.ok) return { ok: false, status: 400, refusal: result.refusal };
230  return { ok: true, action: control.name, result };
231}