src/agents.ts

Functions

Imports

It imports src/agents-schema.ts, src/auth.ts, src/bench-run-key.ts, src/log.ts. Imported by src/access-sync.ts, src/bench-run-key.ts, src/bench.ts, src/canon.ts, src/controls-perform.ts, src/controls-plan.ts, src/inbox-report.ts, src/index.ts, src/jobs-begin.ts, src/jobs-claim.ts, src/jobs-edit.ts, src/jobs-holder.ts, src/jobs-park.ts, src/jobs-schema.ts, src/jobs-seat.ts, src/jobs-transition.ts, src/ops-feed.ts, src/ops-session-auth.ts, src/prompts.ts, src/resources.ts, src/routes.ts, src/routine-fire.ts, src/scope.ts, src/server.ts, src/skills-refresh.ts, src/tools/docs.ts, src/watcher.ts.

Source

1import { bearerToken, operatorIdentity, sha256Hex } from "./auth";
2import { safeEqual } from "@dustinedwards/site-runtime/compare";
3import {
4  AGENT_GRANTS,
5  SCOPE_FLAGS,
6  agentActor,
7  parseScopes,
8  type AgentGrant,
9  type AgentKind,
10  type AgentRow,
11  type AgentScopes,
12  type ScopeFlag,
13} from "./agents-schema";
14import { runKeyAgent } from "./bench-run-key";
15import { logEvent } from "./log";
16
17// A bearer resolves to a caller, not to a tier. A bare "read" or "write" plus a key
18// fingerprint cannot say whose credential did something, and cannot give a queue
19// driver a credential that works a job without also being able to merge a pull
20// request into a repo that deploys on push.
21//
22// Four kinds of caller resolve here, and the order matters:
23//
24//   1. A minted agent (a row in `agents`), with exactly its row's scopes. Checked
25//      first, so a key that is also an OPERATOR_KEY_HASH entry gets the narrower
26//      authority.
27//   2. A legacy operator key: a plain entry is write with every flag, an `ro:` entry
28//      is read with none. This lets the table exist without breaking the credential
29//      used to mint the first agent. It stops working when its hash is removed.
30//   3. A bench run key (src/bench-run-key.ts): one treatment run of the paired
31//      comparison, bound to its one job while the run is open.
32//   4. The OAuth admin session, resolved in src/index.ts: the synthetic agent
33//      "admin", holding every scope.
34
35export interface Agent {
36  // The agents.id for a minted agent. For a synthetic one, its actor string, so a
37  // caller identity is always addressable by a single value.
38  id: string;
39  // The audit NAME. "admin" for an OAuth session, "opkey" for a legacy key, and the
40  // row's unique name for a minted agent.
41  name: string;
42  kind: AgentKind;
43  // What lands in audit_log.actor and jobs.claimed_by. `agent:<name>` for a minted
44  // agent; `opkey:<fingerprint>` for a legacy operator key; the admin as
45  // `access:<email>` on the MCP login (Cloudflare Access, since 2026-09-27) or
46  // `github:<login>` on rows the old console wrote before it moved to Access. Those are more specific than a
47  // synthetic name, and every audit query already reads them.
48  actor: string;
49  scopes: AgentScopes;
50  // May this caller mint, revoke and re-scope other agents? True only for the OAuth
51  // admin and a legacy write key, so a minted agent can never mint a wider one than
52  // itself. Not a flag, because update_scopes can set flags.
53  admin: boolean;
54  // A row-backed agent, as opposed to a synthetic one. What last_seen is written for.
55  row: AgentRow | null;
56  // When this OAuth session's Access sign-in happened (Props.signed_in_at), for the admin
57  // server's step-up (src/scope.ts STEP_UP). Absent for a caller that holds a key rather
58  // than a session; null for a session whose grant recorded no sign-in time, which is
59  // stale.
60  signedInAt?: number | null;
61  // When this admin last completed a step-up action successfully, read from KV where the
62  // session's agent is built and updated by the registrar (src/scope.ts STEP_UP). Absent
63  // when there is none, or when KV could not say.
64  lastStepUpAt?: number;
65  // A bench run key's run and the one job it may work (null while no single job carries
66  // the run's title). checkScope refuses it everything else (src/scope.ts).
67  benchRun?: { run: string; job: string | null };
68}
69
70function flagsAll(value: boolean): Record<ScopeFlag, boolean> {
71  const flags = {} as Record<ScopeFlag, boolean>;
72  for (const flag of SCOPE_FLAGS) flags[flag] = value;
73  return flags;
74}
75
76// Every namespace, repo, tool, grant and flag.
77function unrestrictedScopes(): AgentScopes {
78  return { namespaces: "*", repos: "*", tools: "*", grants: [...AGENT_GRANTS], flags: flagsAll(true) };
79}
80
81function readEverythingScopes(): AgentScopes {
82  return { namespaces: "*", repos: "*", tools: "*", grants: ["read"], flags: flagsAll(false) };
83}
84
85// The admin, as the MCP and Portal logins know it: the email Access verified, already
86// checked against ADMIN_EMAIL and CO_OWNER_EMAILS at sign-in and on every request. A
87// co-owner is this same agent under her own email, so her actor is `access:<her email>`
88// and her step-up clock (src/scope.ts) is her own.
89export function adminAgentForEmail(email: string, signedInAt?: number | null): Agent {
90  const actor = `access:${email}`;
91  return {
92    id: actor,
93    name: "admin",
94    kind: "seat",
95    actor,
96    scopes: unrestrictedScopes(),
97    admin: true,
98    row: null,
99    ...(signedInAt === undefined ? {} : { signedInAt }),
100  };
101}
102
103// A legacy grant and actor expressed as an Agent, so checkScope is the only
104// enforcement path: the fallback path and every test build a caller the same way,
105// and there is no second code path where scopes do not apply.
106export function legacyAgent(grant: AgentGrant, actor: string): Agent {
107  return {
108    id: actor,
109    name: actor.includes(":") ? actor.slice(0, actor.indexOf(":")) : actor,
110    kind: "session",
111    actor,
112    scopes: grant === "write" ? unrestrictedScopes() : readEverythingScopes(),
113    admin: grant === "write",
114    row: null,
115  };
116}
117
118function agentFromRow(row: AgentRow): Agent {
119  return {
120    id: row.id,
121    name: row.name,
122    kind: row.kind,
123    actor: agentActor(row.name),
124    scopes: parseScopes(row.scopes),
125    admin: false,
126    row,
127  };
128}
129
130export interface ResolvedAgent {
131  agent: Agent;
132  // last_seen, written best effort after the answer, so resolution stays a read and a
133  // failed write cannot look like a failed auth.
134  touch: () => Promise<void>;
135}
136
137
138// An indexed equality on the digest, confirmed with a constant-time compare. The
139// index keeps the lookup O(1) as the table grows; the compare keeps the guarantee if
140// the query is ever loosened (a LIKE, a case fold, a fake in a test).
141async function liveAgentByHash(db: D1Database, hash: string): Promise<AgentRow | null> {
142  const row = await db
143    .prepare("SELECT * FROM agents WHERE key_hash = ?1 AND revoked_at IS NULL")
144    .bind(hash)
145    .first<AgentRow>();
146  if (!row) return null;
147  return await safeEqual(row.key_hash, hash) ? row : null;
148}
149
150// A revoked agent does not fall through to OPERATOR_KEY_HASH: a key minted as an
151// agent is not an operator key, and falling through would make revocation depend on
152// the key never having matched anything else.
153export async function resolveAgent(
154  request: Request,
155  env: { DB: D1Database; OPERATOR_KEY_HASH?: string },
156  now: Date = new Date()
157): Promise<ResolvedAgent | null> {
158  const token = bearerToken(request);
159  if (!token) return null;
160  const hash = await sha256Hex(token);
161  const row = await liveAgentByHash(env.DB, hash);
162  if (row) {
163    const agent = agentFromRow(row);
164    return { agent, touch: () => touchLastSeen(env.DB, agent) };
165  }
166  const run = await runKeyAgent(env.DB, hash, now);
167  if (run) return { agent: run, touch: async () => {} };
168  // A revoked key is refused whether its row is still in agents or has moved to the
169  // archive (src/agents-archive.ts): an archived key is a revoked key.
170  const revoked = await env.DB.prepare(
171    "SELECT id FROM agents WHERE key_hash = ?1 UNION ALL SELECT id FROM agents_archive WHERE key_hash = ?1"
172  )
173    .bind(hash)
174    .first<{ id: string }>();
175  if (revoked) return null;
176  const { grant, fingerprint } = await operatorIdentity(request, env);
177  if (!grant || !fingerprint) return null;
178  return { agent: legacyAgent(grant, `opkey:${fingerprint}`), touch: async () => {} };
179}
180
181// Best effort: last_seen is how an unused credential is noticed, not how a request
182// is authorized.
183async function touchLastSeen(db: D1Database, agent: Agent): Promise<void> {
184  if (!agent.row) return;
185  try {
186    await db.prepare("UPDATE agents SET last_seen = datetime('now') WHERE id = ?1").bind(agent.id).run();
187  } catch (err) {
188    logEvent("error", "AGENT_LAST_SEEN_FAILED", { message: `AGENT_LAST_SEEN_FAILED ${agent.id}: ${err instanceof Error ? err.message : String(err)}` });
189  }
190}