src/agents-admin.ts

Functions

Imports

It imports src/agents-schema.ts, src/auth.ts, src/store-guards.ts. Imported by src/controls-perform.ts, src/tools/agents.ts.

Source

1import { sha256Hex } from "./auth";
2import {
3  AGENT_GRANTS,
4  AGENT_KINDS,
5  SCOPE_FLAGS,
6  defaultScopes,
7  isAgentKind,
8  mintAgentId,
9  mintAgentKey,
10  parseScopes,
11  serializeScopes,
12  type AgentGrant,
13  type AgentKind,
14  type AgentRow,
15  type AgentScopes,
16} from "./agents-schema";
17import { auditStatement } from "./store-guards";
18
19// The control plane for credentials: mint, list, revoke, re-scope. Admin only (see
20// ADMIN_REASON in src/scope.ts): an agent that could mint another could widen itself.
21//
22// Separate from src/agents.ts, the resolver. The resolver runs on every request and
23// reads; this runs when a human changes the credential inventory and writes. Keeping
24// them apart lets the resolver stay a read.
25
26export interface AgentResult {
27  ok: boolean;
28  action: string;
29  agent?: PublicAgent;
30  agents?: PublicAgent[];
31  key?: string;
32  note?: string;
33  scopes?: AgentScopes;
34  refusal?: string;
35}
36
37// What an agent looks like to a reader. The stored hash never appears, only its
38// first twelve hex, the same shape as an operator-key fingerprint, so an agent can be
39// matched against an audit row without handing out what it authenticates with.
40interface PublicAgent {
41  id: string;
42  name: string;
43  kind: AgentKind;
44  fingerprint: string;
45  scopes: AgentScopes;
46  created_by: string;
47  created_at: string;
48  revoked_at: string | null;
49  last_seen: string | null;
50}
51
52function publicAgent(row: AgentRow): PublicAgent {
53  return {
54    id: row.id,
55    name: row.name,
56    kind: row.kind,
57    fingerprint: row.key_hash.slice(0, 12),
58    scopes: parseScopes(row.scopes),
59    created_by: row.created_by,
60    created_at: row.created_at,
61    revoked_at: row.revoked_at,
62    last_seen: row.last_seen,
63  };
64}
65
66function refuse(action: string, refusal: string): AgentResult {
67  return { ok: false, action, refusal };
68}
69
70function agentAudit(db: D1Database, actor: string, action: string, name: string, params: Record<string, unknown>) {
71  // An agent is not a document, so its name goes in the path slot under a fixed
72  // "agents" namespace: one audit table rather than a second log nobody reads.
73  return auditStatement(db, actor, action, "agents", name, params);
74}
75
76async function liveAgentByName(db: D1Database, name: string): Promise<AgentRow | null> {
77  return db.prepare("SELECT * FROM agents WHERE name = ?1 AND revoked_at IS NULL").bind(name).first<AgentRow>();
78}
79
80export interface ScopeArgs {
81  namespaces?: string[];
82  repos?: string[];
83  tools?: string[];
84  grants?: string[];
85  flags?: Record<string, unknown>;
86}
87
88// A list of exactly ["*"] is the wildcard; anything else is a list of names. Shared
89// by mint and re-scope, because a disagreement would mean one of them silently
90// narrowing a caller to a namespace literally named "*".
91function scopeList(names: string[]): "*" | string[] {
92  return names.length === 1 && names[0] === "*" ? "*" : [...names];
93}
94
95// Applies the narrowing asked for on top of a base. An omitted axis keeps its base
96// value, so naming one flag does not clear the others, and a call naming none
97// cannot widen anything.
98function applyScopes(base: AgentScopes, args: ScopeArgs): AgentScopes {
99  const scopes: AgentScopes = { ...base, flags: { ...base.flags } };
100  if (args.namespaces) scopes.namespaces = scopeList(args.namespaces);
101  if (args.repos) scopes.repos = scopeList(args.repos);
102  if (args.tools) scopes.tools = scopeList(args.tools);
103  if (args.grants) scopes.grants = args.grants.filter((g): g is AgentGrant => (AGENT_GRANTS as readonly string[]).includes(g));
104  if (args.flags) {
105    for (const flag of SCOPE_FLAGS) {
106      if (Object.hasOwn(args.flags, flag)) scopes.flags[flag] = args.flags[flag] === true;
107    }
108  }
109  return scopes;
110}
111
112// The repos axis a mint gets when the caller names none: every repo the named
113// namespaces map. Starting from defaultScopes (repos "*") would give every agent
114// minted through MCP every repo in the portfolio, while scripts/mint-agents.ts
115// derives a narrow list; two mint paths must agree about the default.
116//
117// Derived from the live namespaces mapping, the same table resolveRepo reads and the
118// repos axis is compared against, so the two cannot drift apart.
119//
120// A namespace scope of "*" derives "*": enumerating today's mapping would silently
121// exclude a namespace registered later. A namespace with no mapped repo refuses
122// rather than falling back to the wildcard, as the script does.
123async function reposForNamespaces(db: D1Database, namespaces: "*" | string[]): Promise<{ repos: "*" | string[] } | { error: string }> {
124  if (namespaces === "*") return { repos: "*" };
125  const repos: string[] = [];
126  for (const namespace of namespaces) {
127    const row = await db.prepare("SELECT repos FROM namespaces WHERE namespace = ?1").bind(namespace).first<{ repos: string }>();
128    if (!row) {
129      return {
130        error:
131          `namespace '${namespace}' is not registered, so the repos this agent may reach cannot be derived. ` +
132          `Register it first, or pass repos explicitly.`,
133      };
134    }
135    let list: unknown;
136    try {
137      list = JSON.parse(row.repos || "[]");
138    } catch {
139      return { error: `namespace '${namespace}' has a corrupt repos mapping. Repair it with capsid_admin_manage_namespaces action update, or pass repos explicitly.` };
140    }
141    if (!Array.isArray(list) || list.length === 0) {
142      return {
143        error:
144          `namespace '${namespace}' maps no repos, so an agent scoped to it would get the wildcard by default. ` +
145          `Map its repos with capsid_admin_manage_namespaces action update, or pass repos explicitly (pass the single entry * to mean every repo deliberately).`,
146      };
147    }
148    for (const entry of list as Array<{ repo?: unknown }>) {
149      if (typeof entry?.repo === "string" && entry.repo && !repos.includes(entry.repo)) repos.push(entry.repo);
150    }
151  }
152  return { repos };
153}
154
155export async function mintAgent(db: D1Database, actor: string, args: ScopeArgs & { name: string; kind: string }): Promise<AgentResult> {
156  const name = args.name.trim();
157  if (!name) return refuse("mint", "an agent needs a name: it is the audit identity every row it writes carries.");
158  // A run key's actor is agent:bench-run-<run>, and the breaker skips those fails (src/job-breaker.ts).
159  if (name.startsWith("bench-run-")) return refuse("mint", "names starting bench-run- belong to bench run keys; choose another name.");
160  if (!isAgentKind(args.kind)) {
161    return refuse("mint", `'${args.kind}' is not an agent kind. One of: ${AGENT_KINDS.join(", ")}.`);
162  }
163  if (!args.namespaces || args.namespaces.length === 0) {
164    return refuse(
165      "mint",
166      "mint needs at least one namespace. A new agent is scoped to the namespaces it was named for, so minting one with none creates a credential that reaches nothing and says nothing about what it was for. Pass the single entry * deliberately if every namespace is what you mean."
167    );
168  }
169  // Names are never reused, revoked and archived ones included, so the check is over
170  // every row of both tables. An audit actor has to mean one credential forever, or
171  // the log cannot answer who did something.
172  const existing = await db
173    .prepare("SELECT id FROM agents WHERE name = ?1 UNION ALL SELECT id FROM agents_archive WHERE name = ?1")
174    .bind(name)
175    .first<{ id: string }>();
176  if (existing) {
177    return refuse("mint", `an agent named '${name}' already exists (${existing.id}). A name is an audit identity and is never reused, including after a revoke.`);
178  }
179  const named = scopeList(args.namespaces);
180  // Derived only when the caller named none; an explicit list, "*" included, is kept.
181  let derived: "*" | string[] | undefined;
182  if (!args.repos) {
183    const answer = await reposForNamespaces(db, named);
184    if ("error" in answer) return refuse("mint", answer.error);
185    derived = answer.repos;
186  }
187  const scopes = applyScopes(
188    { ...defaultScopes([]), namespaces: named, ...(derived === undefined ? {} : { repos: derived }) },
189    { ...args, namespaces: undefined }
190  );
191  // The key is returned once; only its sha256 is stored or logged.
192  const key = mintAgentKey();
193  const keyHash = await sha256Hex(key);
194  const row: AgentRow = {
195    id: mintAgentId(),
196    name,
197    kind: args.kind,
198    key_hash: keyHash,
199    scopes: serializeScopes(scopes),
200    created_by: actor,
201    created_at: new Date().toISOString(),
202    revoked_at: null,
203    last_seen: null,
204  };
205  await db.batch([
206    db
207      .prepare("INSERT INTO agents (id, name, kind, key_hash, scopes, created_by, created_at) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)")
208      .bind(row.id, row.name, row.kind, row.key_hash, row.scopes, row.created_by, row.created_at),
209    agentAudit(db, actor, "agent-minted", name, { id: row.id, kind: row.kind, key_fingerprint: keyHash.slice(0, 12), scopes }),
210  ]);
211  return {
212    ok: true,
213    action: "mint",
214    agent: publicAgent(row),
215    key,
216    scopes,
217    note: "This key is shown ONCE and is stored nowhere: the table holds its sha256. Save it now. If it is lost, revoke this agent and mint another.",
218  };
219}
220
221export async function listAgents(db: D1Database): Promise<AgentResult> {
222  // Revoked rows are included until the watcher pass archives them
223  // (src/agents-archive.ts): a revoked credential is exactly what an inventory is read
224  // for, and hiding it would make "revoked" and "never existed" look the same. The
225  // archive is the list action's archived: true.
226  const { results } = await db.prepare("SELECT * FROM agents ORDER BY created_at DESC, name").all<AgentRow>();
227  return { ok: true, action: "list", agents: (results ?? []).map(publicAgent) };
228}
229
230export async function revokeAgent(db: D1Database, actor: string, name: string): Promise<AgentResult> {
231  const row = await liveAgentByName(db, name);
232  if (!row) return refuse("revoke", `no live agent named '${name}'. Call action list to see the inventory, revoked ones included.`);
233  // Keyed UPDATE with RETURNING: no row back means somebody else got there first,
234  // and reporting success over that would be false.
235  const won = await db
236    .prepare("UPDATE agents SET revoked_at = datetime('now') WHERE id = ?1 AND revoked_at IS NULL RETURNING id")
237    .bind(row.id)
238    .first<{ id: string }>();
239  if (!won) return refuse("revoke", `'${name}' was revoked by somebody else between reading it and revoking it.`);
240  await db.batch([agentAudit(db, actor, "agent-revoked", name, { id: row.id, scopes: parseScopes(row.scopes) })]);
241  return { ok: true, action: "revoke", agent: { ...publicAgent(row), revoked_at: new Date().toISOString() } };
242}
243
244export async function updateAgentScopes(db: D1Database, actor: string, name: string, args: ScopeArgs): Promise<AgentResult> {
245  const row = await liveAgentByName(db, name);
246  if (!row) return refuse("update_scopes", `no live agent named '${name}'. Call action list to see the inventory, revoked ones included.`);
247  const before = parseScopes(row.scopes);
248  const scopes = applyScopes(before, args);
249  const won = await db
250    .prepare("UPDATE agents SET scopes = ?2 WHERE id = ?1 AND revoked_at IS NULL RETURNING id")
251    .bind(row.id, serializeScopes(scopes))
252    .first<{ id: string }>();
253  if (!won) return refuse("update_scopes", `'${name}' was revoked between reading it and re-scoping it.`);
254  // Both sides go in the audit row. The current scopes are answerable from the table;
255  // what they were before, and who widened them, only from the row that changed them.
256  await db.batch([agentAudit(db, actor, "agent-rescoped", name, { id: row.id, before, after: scopes })]);
257  return { ok: true, action: "update_scopes", agent: { ...publicAgent(row), scopes }, scopes };
258}