src/site-operator.ts

Functions

Imports

It imports src/env.ts, src/ops-types/sites.ts, src/time.ts. Imported by src/controls-plan.ts, src/ops-sites.ts, src/site-convergence.ts, src/site-repair.ts, src/site-watch.ts.

Source

1import type { Env } from "./env";
2import type { SiteOperator } from "./ops-types/sites";
3import { MINUTE_MS } from "./time";
4
5// A SITE'S OPERATOR API (job_09e5f6cbf782, Dustin 2026-10-03). Capsid is the operations
6// hub and may trigger an allowlist of a site's own repair tools, so the repairs, the
7// convergence view and the watchdog can leave the site. A site opts in by configuration
8// (ops_sites.operator, migrations/0035), never by code here.
9//
10// Two allowlists, both enforced in this Worker before any request leaves it:
11//   - the CEILING, in code: a repair is a sync_* tool (sync_status is a read, not a
12//     repair) or refresh_citations. backup_media is never called, and neither is anything
13//     else the site's operator API serves (save_post, delete_post, decide_mention...).
14//   - the SITE'S OWN list, in its configuration: the tools its repairs map and its weekly
15//     tools name. A tool the ceiling allows but the site does not name is refused too.
16// Capsid never merges and never mints: the token is one the seat set as a Capsid Worker
17// secret, read by name, sent only to the site's own origin, and never logged, returned or
18// put in an audit row.
19
20/** The ceiling: the only tools Capsid will ever call as a repair. */
21export function repairToolRefusal(tool: string): string | null {
22  if (tool === "backup_media") return "backup_media is not a repair Capsid may call: it copies the media bucket, and it stays with the site's own watchdog.";
23  if (tool === "sync_status") return "sync_status is a read, not a repair.";
24  if (tool === "refresh_citations" || /^sync_[a-z][a-z_]{0,40}$/.test(tool)) return null;
25  return `'${tool}' is not a repair Capsid may call: only the site's sync_* tools and refresh_citations are.`;
26}
27
28const SECRET_NAME = /^[A-Z][A-Z0-9_]{0,48}_OPERATOR_TOKEN$/;
29const CHECK_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
30const ENV_NAME = /^[A-Z][A-Z0-9_]{0,63}$/;
31const OPERATOR_PATH = /^\/[A-Za-z0-9._~/-]{0,199}$/;
32const MAX_REPAIRS = 40;
33const MAX_SECRETS = 40;
34const MAX_JSON = 4000;
35
36export type ParsedOperator = { ok: true; operator: SiteOperator } | { ok: false; refusal: string };
37
38/** A site's operator configuration from its stored or edited JSON, checked whole: one bad
39 *  entry refuses all of it, so a configuration is never half applied. */
40export function parseOperator(raw: string): ParsedOperator {
41  const refuse = (refusal: string): ParsedOperator => ({ ok: false, refusal: `operator: ${refusal}` });
42  if (raw.length > MAX_JSON) return refuse(`at most ${MAX_JSON} characters.`);
43  let value: unknown;
44  try {
45    value = JSON.parse(raw);
46  } catch (err) {
47    return refuse(`not JSON (${err instanceof Error ? err.message : String(err)}).`);
48  }
49  if (!value || typeof value !== "object" || Array.isArray(value)) return refuse("must be a JSON object.");
50  const o = value as Record<string, unknown>;
51  const known = ["path", "auth_var", "repairs", "weekly", "secrets"];
52  const extra = Object.keys(o).filter((k) => !known.includes(k));
53  if (extra.length) return refuse(`takes ${known.join(", ")}; '${extra[0]}' is not one of them.`);
54  if (typeof o.path !== "string" || !OPERATOR_PATH.test(o.path) || o.path.includes("..")) return refuse("path must be a path on the site's origin, such as /api/operator.");
55  if (typeof o.auth_var !== "string" || !SECRET_NAME.test(o.auth_var)) return refuse("auth_var must name a Capsid Worker secret ending in _OPERATOR_TOKEN, such as DUSTINEDWARDS_OPERATOR_TOKEN.");
56  const repairs: Array<[string, string]> = [];
57  if (o.repairs !== undefined) {
58    if (!o.repairs || typeof o.repairs !== "object" || Array.isArray(o.repairs)) return refuse("repairs must map health check names to repair tools.");
59    for (const [check, tool] of Object.entries(o.repairs)) {
60      if (!CHECK_NAME.test(check)) return refuse(`'${check}' is not a health check name.`);
61      if (typeof tool !== "string") return refuse(`the repair for ${check} must be a tool name.`);
62      const bad = repairToolRefusal(tool);
63      if (bad) return refuse(`${check}: ${bad}`);
64      repairs.push([check, tool]);
65    }
66    if (repairs.length > MAX_REPAIRS) return refuse(`at most ${MAX_REPAIRS} repairs.`);
67  }
68  const weekly: string[] = [];
69  if (o.weekly !== undefined) {
70    if (!Array.isArray(o.weekly)) return refuse("weekly must be a list of tools.");
71    for (const tool of o.weekly) {
72      if (typeof tool !== "string") return refuse("weekly must be a list of tool names.");
73      const bad = repairToolRefusal(tool);
74      if (bad) return refuse(`weekly: ${bad}`);
75      if (!weekly.includes(tool)) weekly.push(tool);
76    }
77  }
78  const secrets: string[] = [];
79  if (o.secrets !== undefined) {
80    if (!Array.isArray(o.secrets) || o.secrets.length > MAX_SECRETS) return refuse(`secrets must be a list of at most ${MAX_SECRETS} names.`);
81    for (const name of o.secrets) {
82      if (typeof name !== "string" || !ENV_NAME.test(name)) return refuse(`'${String(name)}' is not a secret name.`);
83      if (!secrets.includes(name)) secrets.push(name);
84    }
85  }
86  return { ok: true, operator: { path: o.path, auth_var: o.auth_var, repairs: Object.fromEntries(repairs), weekly, secrets } };
87}
88
89/** The tools this site allows: its repairs and its weekly tools. */
90export function allowedTools(operator: SiteOperator): string[] {
91  return [...new Set([...Object.values(operator.repairs), ...operator.weekly])];
92}
93
94/** Why `tool` may not be called on this site, or null. The ceiling first, then the site's
95 *  own list, checked again here before every request, not only when the configuration
96 *  was saved: a row written before a ceiling change must not outlive it. */
97export function toolRefusal(operator: SiteOperator, tool: string, reading = false): string | null {
98  if (reading && tool === "sync_status") return null;
99  const ceiling = repairToolRefusal(tool);
100  if (ceiling) return ceiling;
101  if (!allowedTools(operator).includes(tool)) return `${tool} is not in this site's allowlist (${allowedTools(operator).join(", ") || "none"}).`;
102  return null;
103}
104
105/** Whether the token is set, by name, without reading it out. */
106export function tokenSet(env: Env, operator: SiteOperator): boolean {
107  const value = (env as unknown as Record<string, unknown>)[operator.auth_var];
108  return typeof value === "string" && value.length > 0;
109}
110
111export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
112
113/** What one call to the operator API came to. `converged` is the tool's own read-back
114 *  verdict where it gives one; a 200 without it proves nothing and says so. */
115export interface OperatorCall {
116  ok: boolean;
117  status: number;
118  /** The reply's data, for a read (sync_status). Never echoed for a repair. */
119  data: unknown;
120  converged: boolean | null;
121  expected: number | null;
122  present: number | null;
123  /** What went wrong, in one line, or null. Never carries the token. */
124  error: string | null;
125}
126
127const CALL_TIMEOUT_MS = MINUTE_MS;
128const ERROR_MAX = 300;
129
130/** One allowlisted call: POST {tool, args: {}} to the site's operator route with the
131 *  configured token. Refused before any request when the tool is not allowed or the token
132 *  is not set. Never throws. */
133export async function callOperator(
134  env: Env,
135  site: { origin: string; operator: SiteOperator },
136  tool: string,
137  fetchImpl: FetchLike = fetch,
138  opts: { reading?: boolean } = {}
139): Promise<OperatorCall> {
140  const fail = (status: number, error: string): OperatorCall => ({ ok: false, status, data: null, converged: null, expected: null, present: null, error: error.slice(0, ERROR_MAX) });
141  const refusal = toolRefusal(site.operator, tool, opts.reading === true);
142  if (refusal) return fail(0, `refused by Capsid before any request: ${refusal}`);
143  const token = (env as unknown as Record<string, unknown>)[site.operator.auth_var];
144  if (typeof token !== "string" || token.length === 0) return fail(0, `the Capsid Worker secret ${site.operator.auth_var} is not set, so nothing was called.`);
145  let response: Response;
146  let payload: unknown;
147  try {
148    response = await fetchImpl(site.origin + site.operator.path, {
149      method: "POST",
150      headers: { authorization: `Bearer ${token}`, "content-type": "application/json", "user-agent": "capsid" },
151      body: JSON.stringify({ tool, args: {} }),
152      redirect: "manual",
153      signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
154    });
155    payload = await response.json().catch(() => null);
156  } catch (err) {
157    return fail(0, `${tool} did not complete: ${err instanceof Error ? err.message : String(err)}`);
158  }
159  const body = (payload && typeof payload === "object" ? payload : {}) as { ok?: unknown; data?: unknown; error?: unknown };
160  if (!response.ok || body.ok !== true) {
161    const said = typeof body.error === "string" ? body.error : "no error was given";
162    return fail(response.status, `${tool} answered ${response.status}: ${said}`);
163  }
164  const data = body.data && typeof body.data === "object" ? (body.data as Record<string, unknown>) : null;
165  const num = (v: unknown) => (typeof v === "number" && Number.isFinite(v) ? v : null);
166  return {
167    ok: true,
168    status: response.status,
169    data: opts.reading ? body.data : null,
170    converged: typeof data?.converged === "boolean" ? data.converged : null,
171    expected: num(data?.expected),
172    present: num(data?.present),
173    error: null,
174  };
175}
176
177/** One line for an audit row or a task run: what the call did. */
178export function callLine(tool: string, call: OperatorCall): string {
179  if (!call.ok) return call.error ?? `${tool} failed`;
180  if (call.converged === null) return `${tool} answered ${call.status} without a converged verdict, so nothing was proven`;
181  return `${tool} ${call.converged ? "converged" : "did not converge"}${call.expected !== null ? ` (${call.present ?? "?"} of ${call.expected} present)` : ""}`;
182}