src/agents-schema.ts

Functions

Imports

It imports src/encoding.ts. Imported by src/agent-record.ts, src/agents-admin.ts, src/agents.ts, src/bench-run-key.ts, src/bench.ts, src/controls-plan.ts, src/jobs-schema.ts, src/review.ts, src/scope.ts, src/skills-refresh.ts, src/status.ts, src/tools/agents.ts, src/tools/jobs.ts, src/tools/namespaces.ts, src/watcher.ts.

Source

1import { bytesToHex } from "./encoding";
2
3// The vocabulary of a scoped credential, in one module so the table
4// (migrations/0008_agents.sql), the tool (src/tools/agents.ts) and the enforcement
5// point (src/scope.ts) cannot disagree about it: a list spelled twice drifts, and the
6// copy nobody looks at ends up checking five flags out of six. Free of Worker and MCP
7// imports so the scope logic is unit-testable under node.
8
9// Descriptive, not authorizing. What an agent may do lives in its scopes and
10// nowhere else, so a kind cannot quietly become a second permission system.
11export const AGENT_KINDS = ["session", "driver", "seat", "cron"] as const;
12export type AgentKind = (typeof AGENT_KINDS)[number];
13
14export const AGENT_GRANTS = ["read", "write"] as const;
15export type AgentGrant = (typeof AGENT_GRANTS)[number];
16
17// Each flag names an action whose consequence leaves this Worker, so the write grant
18// alone is not enough for any of them. The reasons are FLAG_REASON in src/scope.ts.
19export const SCOPE_FLAGS = [
20  "can_merge",
21  "can_direct_write",
22  "can_dispatch",
23  "can_write_workflows",
24  "can_touch_protected",
25  "money_paths",
26  // Commenting goes through capsid_open_pr action comment, a write tool, so a reviewer holds the write
27  // grant; without a flag of its own that grant would also let it merge and close.
28  // This flag makes "may comment on this PR" smaller than "may decide this PR".
29  "can_comment_pr",
30] as const;
31export type ScopeFlag = (typeof SCOPE_FLAGS)[number];
32
33// A list of names, or "*" for every name. "*" inside a list is not a wildcard, so a
34// typo in a mint command cannot grant everything.
35export type ScopeList = "*" | string[];
36
37export interface AgentScopes {
38  namespaces: ScopeList;
39  repos: ScopeList;
40  tools: ScopeList;
41  grants: AgentGrant[];
42  flags: Record<ScopeFlag, boolean>;
43}
44
45export interface AgentRow {
46  id: string;
47  name: string;
48  kind: AgentKind;
49  key_hash: string;
50  scopes: string;
51  created_by: string;
52  created_at: string;
53  revoked_at: string | null;
54  last_seen: string | null;
55  // The one job an old runner key existed to work (migrations/0021), or null; no key is minted with one now. Optional
56  // because a row read before that migration has no such column.
57  job_id?: string | null;
58}
59
60export function isAgentKind(value: unknown): value is AgentKind {
61  return typeof value === "string" && (AGENT_KINDS as readonly string[]).includes(value);
62}
63
64export function noFlags(): Record<ScopeFlag, boolean> {
65  // Built fresh each time, so a flag set on one agent cannot leak to another.
66  const flags = {} as Record<ScopeFlag, boolean>;
67  for (const flag of SCOPE_FLAGS) flags[flag] = false;
68  return flags;
69}
70
71// Nothing allowed: what parseScopes falls back to on a corrupt row.
72function emptyScopes(): AgentScopes {
73  return { namespaces: [], repos: [], tools: [], grants: [], flags: noFlags() };
74}
75
76// The default for a new agent: read, on the namespaces it was named for, and no
77// flags. Tools and repos are unrestricted because the grant already limits them (a
78// read grant cannot reach a write tool, and a repo read is a read); the axes that
79// must be narrowed at mint time are the ones the mint command asks for.
80export function defaultScopes(namespaces: string[]): AgentScopes {
81  return { namespaces: [...namespaces], repos: "*", tools: "*", grants: ["read"], flags: noFlags() };
82}
83
84function parseList(value: unknown): ScopeList {
85  if (value === "*") return "*";
86  if (!Array.isArray(value)) return [];
87  return value.filter((entry): entry is string => typeof entry === "string" && entry.length > 0);
88}
89
90// Fails closed: a scopes column that is null, empty, truncated, an array, a bare
91// string or an object with none of the keys resolves to emptyScopes(). A permissive
92// parse of a corrupt row looks like a working one until the row is corrupt.
93export function parseScopes(json: string | null | undefined): AgentScopes {
94  if (!json) return emptyScopes();
95  let raw: unknown;
96  try {
97    raw = JSON.parse(json);
98  } catch {
99    return emptyScopes();
100  }
101  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return emptyScopes();
102  const record = raw as Record<string, unknown>;
103  const grants = Array.isArray(record.grants)
104    ? (record.grants.filter((g): g is AgentGrant => (AGENT_GRANTS as readonly unknown[]).includes(g)) as AgentGrant[])
105    : [];
106  const flags = noFlags();
107  // Only the flags this system has, and only the boolean true, so a hand-written
108  // scopes blob cannot add an axis the enforcement point does not know.
109  const rawFlags = typeof record.flags === "object" && record.flags !== null ? (record.flags as Record<string, unknown>) : {};
110  for (const flag of SCOPE_FLAGS) flags[flag] = rawFlags[flag] === true;
111  return {
112    namespaces: parseList(record.namespaces),
113    repos: parseList(record.repos),
114    tools: parseList(record.tools),
115    grants,
116    flags,
117  };
118}
119
120export function serializeScopes(scopes: AgentScopes): string {
121  return JSON.stringify(scopes);
122}
123
124// The one list comparison. "*" is the only wildcard and it is the whole value, never
125// an entry.
126export function allowsScope(list: ScopeList, value: string): boolean {
127  return list === "*" ? true : list.includes(value);
128}
129
130// The same comparison for a tool whose action decides what it does (jobs: "may post
131// a job" and "may claim one" are different authorities). An entry may be qualified,
132// `jobs.post`, and the rule is:
133//
134//   - "*" allows everything.
135//   - A list naming at least one action of this tool is narrowed to the actions it
136//     names. Anything else of that tool is refused.
137//   - A bare tool name with no qualified sibling means the whole tool.
138//   - The narrowing reaches only the tool it names.
139//
140// Kept beside allowsScope rather than in the enforcement point so the rule is one
141// pure function the tests can drive without an agent or a server.
142export function allowsToolAction(list: ScopeList, tool: string, action: string | undefined): boolean {
143  if (list === "*") return true;
144  if (!list.includes(tool)) return false;
145  const prefix = `${tool}.`;
146  const qualified = list.some((entry) => entry.startsWith(prefix));
147  if (!qualified) return true;
148  // An unknown action on a narrowed tool is refused, not read as the whole tool:
149  // otherwise a reviewer minted ["capsid_open_pr", "capsid_open_pr.comment"] could open a pull
150  // request through a call path that names no action.
151  //
152  // It stays opt-in: a list with no qualified sibling for this tool is untouched.
153  // Opting in means the call path has to say what it is doing, and a path that cannot
154  // is refused.
155  if (action === undefined) return false;
156  return list.includes(`${prefix}${action}`);
157}
158
159// How a scope list reads in a refusal, so the refusal says what the scope is.
160export function describeScope(list: ScopeList): string {
161  if (list === "*") return "*";
162  return list.length === 0 ? "(none)" : list.join(", ");
163}
164
165// agent_<12 hex>. See the migration for why it is not a sequence.
166export function mintAgentId(): string {
167  return `agent_${bytesToHex(crypto.getRandomValues(new Uint8Array(6)))}`;
168}
169
170// 32 bytes of entropy behind a greppable prefix, so a key pasted into a file, a log
171// or a commit is findable by searching for one string. Returned ONCE by the mint
172// action and stored nowhere: what the table holds is its sha256.
173export function mintAgentKey(): string {
174  return `capsid_agent_${bytesToHex(crypto.getRandomValues(new Uint8Array(32)))}`;
175}
176
177// The audit identity, in the vocabulary audit_log.actor and jobs.claimed_by already
178// speak (`github:<login>`, `opkey:<fingerprint>`). The name is UNIQUE in the table,
179// so this string identifies exactly one agent row.
180export function agentActor(name: string): string {
181  return `agent:${name}`;
182}
183
184// The driver bootstrap instruction. capsid_admin_manage_namespaces action register returns the mint command
185// rather than minting, so no credential crosses the tool boundary.
186// test/register-namespace-mint.test.ts asserts the script it names can parse it.
187export function driverAgentName(namespace: string): string {
188  return `${namespace}-driver`;
189}
190
191export function driverKeyPath(namespace: string): string {
192  return `~/.capsid/agent-${driverAgentName(namespace)}.key`;
193}
194
195export function driverMintInstruction(namespace: string): string {
196  return (
197    `Mint its driver agent as the admin: node scripts/mint-agents.ts --namespace ${namespace} --apply. ` +
198    `The key is returned once and lands in ${driverKeyPath(namespace)} at mode 0600. ` +
199    // Cannot import TOOL_GRANTS (src/scope.ts imports this module), so
200    // test/audit-2026-09-16.test.ts holds the sentence and the table together.
201    `capsid_admin_manage_namespaces action register does not mint it: minting is admin only, and capsid_admin_manage_namespaces action register is itself admin only.`
202  );
203}