src/scope.ts

Functions

Imports

It imports src/admin-client-audit.ts, src/agents-schema.ts, src/agents.ts, src/log.ts, src/portfolio-docs.ts, src/protected-paths.ts, src/time.ts. Imported by src/access-sync.ts, src/auto-merge-policy.ts, src/canon.ts, src/counts.ts, src/inbox-report.ts, src/index.ts, src/jobs-schema.ts, src/merge-class.ts, src/model-routing.ts, src/ops-session-auth.ts, src/prompts.ts, src/resources.ts, src/routes.ts, src/rule-docs.ts, src/server.ts, src/tools/docs-read.ts, src/tools/docs-write.ts, src/tools/docs.ts, src/tools/jobs.ts, src/tools/namespaces.ts, src/tools/repo-guards.ts.

Source

1import { z } from "zod";
2import type { McpServer } from "@modelcontextprotocol/server";
3import type { Agent } from "./agents";
4import type { AdminWriteObserver } from "./admin-client-audit";
5import { logEvent } from "./log";
6import { allowsScope, allowsToolAction, describeScope, type AgentGrant, type ScopeFlag } from "./agents-schema";
7import { protectedHits } from "./protected-paths";
8import { describePortfolioDocs, isPortfolioPath, isPortfolioTool, PORTFOLIO_DOCS } from "./portfolio-docs";
9import { MINUTE_MS, HOUR_MS } from "./time";
10
11// The one enforcement point. Every tool call, and every repo mutation inside one, is
12// checked here and nowhere else.
13//
14// A per-tool gate in each handler has three failure modes: a new tool can simply
15// omit the line, and a scan for mutating SQL cannot see a tool whose writes happen a
16// module away (the queue, the auto-merge tick, every repo write); a bare "may write"
17// says nothing about which namespace, which repo, or whether the caller may merge
18// into a repo that deploys on push; and a check spelled N times has to be widened at
19// N sites, which is how a fix lands in all but one of them.
20//
21// `checkScope` returns a refusal string naming the missing scope, or null. It is
22// called from two places, split by where the information is:
23//
24//   - The registrar (`guardRegistrations`), before any handler runs, for what is
25//     knowable from the tool and its arguments: the tool allowlist, the grant, the
26//     namespace and the repo selector.
27//   - The handler, for the flags, which depend on what the call asks to do.
28//     `mode: "direct"` needs can_direct_write and `mode: "pr"` does not, and no
29//     wrapper can know that before reading the arguments.
30
31// What each tool requires, stated once. The registrar enforces this table and
32// src/tool-annotations.ts derives readOnlyHint from it, so the two cannot disagree.
33//
34// "action" means the requirement depends on the action argument. A tool whose
35// requirement depends on nothing but the action states it per action in
36// TOOL_ACTION_GRANTS below, and the registrar reads it. `capsid_work_jobs` (action
37// list reads) and `capsid_lint_namespace` (mode gather reads) also depend on a namespace the handler resolves,
38// so their handlers call checkScope at the point where both are known.
39//
40// "admin" is write plus the admin identity, for a tool that edits the authorization
41// boundary itself or changes what other callers may do. "admin_read" is the admin
42// identity with only the read grant, for an admin tool that only reads (claims, the
43// operations state, what needs the seat): admin because it spans every namespace, and
44// served read-only because it changes nothing (capsid/research/design-mcp-servers.md,
45// section 3, which fixed claims and ops reading as not read-only). They live here, not
46// in a handler, because these tools are admin-only in whole, which the registrar can
47// decide from the tool name alone, and because checkScope is the one grant check
48// (test/scope.test.ts) and this table is the one statement of what each tool requires. No handler
49// decides a grant for itself.
50export type ToolRequirement = "read" | "write" | "action" | "admin" | "admin_read";
51
52// Capsid (14) and Capsid Admin (8): src/tools/surface.ts.
53export const TOOL_GRANTS: Record<string, ToolRequirement> = {
54  capsid_start_session: "read",
55  capsid_find_docs: "read",
56  capsid_read_doc: "read",
57  capsid_write_doc: "write",
58  capsid_delete_doc: "write",
59  // gather reads, finalize archives and report writes, each checked by the handler
60  // where the namespace is known.
61  capsid_lint_namespace: "action",
62  capsid_read_repo: "read",
63  // The CI log tail beyond the summary needs write, checked by the handler.
64  capsid_inspect_repo: "read",
65  capsid_change_repo: "write",
66  capsid_open_pr: "write",
67  capsid_close_pr: "write",
68  capsid_run_ci: "write",
69  // list reads; every other action changes the queue.
70  capsid_work_jobs: "action",
71  // Capsid's status (src/status.ts). The name is the improve loop's, kept when the loop
72  // was removed so no agent's tools list changes.
73  capsid_run_improve: "read",
74
75  // What needs the seat, across every namespace and repo. It only reads.
76  capsid_admin_whats_next: "admin_read",
77  // The namespace-to-repo mapping is the authorization boundary. A write-grant driver
78  // that could edit it could remap its own namespace onto any repo the App reaches
79  // and, with a repos axis of "*", immediately read and write it. Delete reaches
80  // across every table that names the namespace, which no scope narrows.
81  capsid_admin_manage_namespaces: "admin",
82  // The credential control plane. An agent that could mint, revoke or re-scope another
83  // could widen itself.
84  capsid_admin_manage_agents: "admin",
85  // Claims apart from verified outcomes. It only reads; it spans every namespace and
86  // every agent, and its export is the whole dataset.
87  capsid_admin_read_claims: "admin_read",
88  // The watcher's last pass, Cloudflare Access and Email Routing, and Workers Builds.
89  // It only reads, and spans every namespace's sites, CI runs and Cloudflare state.
90  capsid_admin_read_ops: "admin_read",
91  // The administrator's controls (preview, then perform with a signed single-use
92  // token). A control revokes an agent, resumes a job or edits a site, so a caller
93  // that could use one could widen itself.
94  capsid_admin_run_controls: "admin",
95  // mint_operator_key issues a credential, sign_policy decides whether this Worker may
96  // merge without a human, breaker_reset reopens a namespace's queue and overnight
97  // starts unattended sessions. None of those is a driver's work.
98  capsid_admin_control_improve: "admin",
99  // Mints a site key and sets it on the site Worker and on Carrel.
100  capsid_admin_set_site_key: "admin",
101};
102
103// Fail closed: a tool with no entry requires the write grant, so a tool added without
104// touching this table is refused to a read-only caller rather than waved through.
105// test/invariants.test.ts asserts the table and the registrations name the same set,
106// so the fallback is a backstop and not the normal path.
107export function requiredGrant(tool: string): ToolRequirement {
108  return Object.hasOwn(TOOL_GRANTS, tool) ? TOOL_GRANTS[tool] : "write";
109}
110
111// What each action requires, for an "action" tool whose requirement depends on nothing
112// but the action. The registrar reads this table. An unlisted action takes `default`,
113// so a new action is refused to a driver until listed. No served tool needs it today;
114// the improve loop's tool did, before the loop was removed.
115export const TOOL_ACTION_GRANTS: Record<string, { default: ToolRequirement; actions: Record<string, ToolRequirement> }> = {};
116
117export function requiredForAction(tool: string, action: string | undefined): ToolRequirement {
118  const spec = Object.hasOwn(TOOL_ACTION_GRANTS, tool) ? TOOL_ACTION_GRANTS[tool] : null;
119  if (!spec) return requiredGrant(tool);
120  if (action === undefined) return spec.default;
121  return Object.hasOwn(spec.actions, action) ? spec.actions[action] : spec.default;
122}
123
124// A requirement as the part of a ScopeNeed it decides. The registrar and every route
125// use this one mapping, so "admin" means the same thing wherever it is enforced.
126export function needFor(requirement: ToolRequirement): Pick<ScopeNeed, "grant" | "admin"> {
127  if (requirement === "admin") return { grant: "write", admin: true };
128  if (requirement === "admin_read") return { grant: "read", admin: true };
129  if (requirement === "action") return {};
130  return { grant: requirement };
131}
132
133// HTTP routes, which guardRegistrations never sees: it wraps MCP tools, and a plain
134// route in src/routes.ts is outside it by construction. A route checked only for the
135// write grant would let a driver minted for one namespace act across all of them.
136//
137// Every route in defaultHandler is in exactly one of these two tables, and
138// test/route-gates.test.ts fails when one is in neither, so a new route is a decision
139// rather than a gap.
140
141// A route that goes through checkScope, and what it requires.
142export const ROUTE_GRANTS: Record<string, ToolRequirement> = {
143  "/ops/backup": "admin",
144};
145
146// A route that does not, and why. Each reason names what authorizes the request
147// instead, because "public" and "authorized some other way" are different claims.
148export const UNGATED_ROUTES: Record<string, string> = {
149  "/health": "a liveness probe that returns provenance and store health, never a document",
150  "/public/model/v1.json":
151    "the public system model (src/public-data.ts): public by design, it serves only the document the daily build stored after toPublic filtered it (src/system-model.ts), never D1 or GitHub; GET only, edge-cached, then a per-IP KV limit that fails closed; no CORS, since site builds read it, not browsers",
152  "/public/stats/v1.json":
153    "the public aggregate numbers (src/public-stats.ts): counts, rates and medians over every namespace, agent and site, whole UTC days, null under ten rows, no string but a date and the sha /health shows; it serves only what the daily build stored, never D1; GET only, edge-cached, the same per-IP limit as the model, failing closed; no CORS",
154  "/public/code/v1.json":
155    "the public code maps (src/public-code.ts): each public system's repos' code-map.json from their code-map branch, parsed field by field, a private system's repos never read; it serves only what the daily build stored, never GitHub; GET only, edge-cached, the same per-IP limit as the model, failing closed; no CORS",
156  "/oauth/clients/verify-live.json": "the verify-live probe's OAuth client metadata document (src/oauth-client-docs.ts): public by nature, fetched by the authorization server with no credential, and holds no secret",
157  "/csp-report": "browsers post violation reports with no credential; the body is size- and type-bounded and rate-limited",
158  "/ops/mcp": "resolves the caller, and every tool call it serves then passes checkScope in the registrar",
159  "/ops/mcp/admin":
160    "Capsid Admin for a key: resolveAgent on the bearer (401 without one), then the admin identity only (403 for any other key), and every tool call it serves then passes checkScope in the registrar, where each tool is admin only",
161  "/backup/credential": "signed with the backup-specific HMAC key, derived from the Worker's root secret under its own context, and replay-protected",
162  "/bench/tasks": "signed with the capsid-bench HMAC key (src/bench.ts), which no backup key can produce, and replay-protected; registers a task once and never changes one",
163  "/bench/draw": "signed with the capsid-bench HMAC key and replay-protected; records the registration once and appends the drawn task order, which never changes",
164  "/bench/start": "signed with the capsid-bench HMAC key and replay-protected; opens a run only while KV bench:enabled reads on and under the running cap, and returns a treatment run's own run key once",
165  "/bench/repro": "signed with the capsid-bench HMAC key and replay-protected; writes the harness's reproduction receipt once for one running treatment run, which its run key's complete then requires",
166  "/shadow/job": "a GitHub Actions OIDC token whose repository is the capsid namespace's primary repo and whose workflow is shadow-test.yml on a pull request; returns only the capsid job that pull request names",
167  "/shadow/result": "the same OIDC token as /shadow/job; keeps the shadow test written for that pull request's job and records its base and head results",
168  "/bench/score": "signed with the capsid-bench HMAC key and replay-protected; closes one running bench run, takes every arm's claim from the report, and checks the treatment's job is its own, and closes that job in the same step",
169  "/ops/inbox":
170    "what needs Dustin, per app (src/inbox.ts): resolveAgent on the bearer (401 without one), then each app is kept only if checkScope admits the caller's read grant on that app's namespace, so a key scoped to one namespace sees that app alone and the admin or an all-namespace read key sees every app. GET only, no CORS headers (an app's server calls it, never a browser), nothing written",
171  "/ops/inbox/report":
172    "what an app reports about itself to the inbox (src/inbox-report.ts): resolveAgent on the bearer (401 without one), then checkScope for the write grant on the namespace the report names (403 otherwise), so a key reports for its own app alone; one report per minute per key, failing closed; at most 20 items, links on the app's own ops_sites origin only, a 16KB body cap; POST only, no CORS",
173  "/ops/access-sync":
174    "an app's members list made its Cloudflare Access group (src/access-sync.ts): resolveAgent on the bearer (401 without one), then checkScope for the write grant on the namespace the body names (403 otherwise); the group is never named by the caller but read from access_sync_groups for that namespace, and its name is checked against the pin before any write; per-key hourly and daily limits failing closed; a 64KB body cap; every call audited; POST only, no CORS",
175  "/ops/hooks":
176    "Claude Code's HTTP hooks: resolveAgent on the bearer (401 without one), then only a driver or the admin, and through checkScope only a caller holding the write grant on capsid_work_jobs (403 otherwise); each event binds to the one job the driver holds claimed, and a session keeps its first binding. 64KB body cap, allowlisted fields only (src/ops-hooks.ts, caller check in src/ops-session-auth.ts)",
177  "/ops/otlp/v1/metrics":
178    "Claude Code's OTLP metrics: resolveAgent on the bearer (401 otherwise), then a driver or the admin holding write through checkScope (403 otherwise); the usage is bound to the one job the driver holds claimed, never to a job the body names; points for a session another caller reported first are refused (src/ops-session-auth.ts, src/ops-otlp.ts)",
179  "/ops/otlp/v1/logs":
180    "Claude Code's OTLP logs, counted as api_error events only: resolveAgent on the bearer and the same caller and job binding as the metrics route (src/ops-session-auth.ts)",
181  "/authorize": "the OAuth authorization step, gated by the OAuth provider and the Access for SaaS login",
182  "/callback": "the OAuth callback, which validates state before issuing anything",
183  "/register":
184    "tightened Dynamic Client Registration for Grok and Gemini (src/dcr.ts): rate limited per caller and failing closed, a 16KB body cap, every redirect URI matched exactly against the allowlist; it writes a client record and grants nothing, since the client still meets the consent page and the Access sign-in",
185  "/portal/callback": "Capsid Portal's Access for SaaS callback, which validates state before issuing a session",
186  "/portal/api/ops": "the Portal's feed, gated by portalGate: the administrator's Access session, and a 403 for any bearer",
187  "/portal/api/ops/refresh":
188    "one watcher pass on demand, gated by portalGate, then a same-origin header, then a KV rate limit that fails closed",
189  "/portal/api/actions/preview":
190    "a Portal action's preview, which writes nothing: portalGate, a same-origin Sec-Fetch-Site, a 64KB body cap, then the X-Capsid-CSRF header against the capsid_portal_csrf cookie",
191  "/portal/api/actions/perform":
192    "a Portal action's perform: the preview's checks, then a token signed at preview time that binds the action, its params and the administrator's email for five minutes",
193  "/portal/api/namespaces": "the Portal's per-namespace status, read through the function behind capsid_run_improve action status, gated by portalGate",
194  "/portal/api/activity": "the Portal's bounded audit_log read, gated by portalGate",
195  "/portal/api/claims": "the Portal's bounded read of claims, evaluations and touches, through the capsid_admin_read_claims tool's readers, gated by portalGate",
196  "/portal/api/stale": "the Portal's stale jobs, through the reader behind capsid_work_jobs action list stale: true, gated by portalGate",
197  "/portal/api/plan": "the Portal's Tonight plan, through the reader behind capsid_work_jobs action list view plan, over every namespace, gated by portalGate",
198  "/portal/api/digest": "the Portal's since-you-last-looked strip, through the reader behind capsid_work_jobs action list view digest, over every namespace, gated by portalGate",
199  "/portal/api/convergence": "the Portal's convergence view of each site that opted into its operator API: sync_status, the health route and secret names read live, gated by portalGate",
200  "/portal/api/maintenance": "the Portal's Maintenance list, the daily pass's stored list that capsid_run_improve action status serves, gated by portalGate",
201  "/portal/api/packages/history": "the Portal's on-demand download history of one configured package, cached, gated by portalGate",
202  "/portal/api/shared-code": "the Portal's Shared code view: each configured shared package's tags and the pins in the configured sites' repos, read through the GitHub App and cached for an hour, gated by portalGate",
203  "/portal/api/library": "the Portal's read-only Library: the knowledge store's shelves, a search and one document with its edges, through the readers behind capsid_find_docs and capsid_read_doc, gated by portalGate",
204  "/portal/api/trends": "the Portal's trends for its charts: minutes, the queue, merges and rollbacks from D1, backup slots from R2, default-branch CI from GitHub (cached an hour), read-only, gated by portalGate",
205  "/portal/api/push":
206    "the Portal's phone alerts: GET lists the devices with alerts on behind portalGate; POST turns one on or off or sends a test behind the preview's checks (portalGate, same-origin, the body cap, CSRF)",
207  "/portal/api/sign-out": "expires the Portal's own cookies, behind the preview's checks so a cross-site page cannot sign the administrator out",
208  "/portal/api/*": "any other path under /portal/api/: portalGate, then a JSON 404, so the app's page is never served as data",
209  "/portal": "Capsid Portal's page, served from ASSETS only after portalGate admits the administrator's session",
210  "/portal/*": "Capsid Portal's files and client routes, served from ASSETS only after portalGate admits the administrator's session",
211};
212
213// The refusal for a gated route, or null. The same checkScope the tools use.
214export function routeRefusal(path: string, agent: Agent): string | null {
215  const requirement = Object.hasOwn(ROUTE_GRANTS, path) ? ROUTE_GRANTS[path] : "admin";
216  return checkScope(agent, { tool: path, ...needFor(requirement) });
217}
218
219export interface ScopeNeed {
220  tool: string;
221  // A capsid_work_jobs call as the registrar saw it: the job id it names, and whether it
222  // asks for more than one job's row (a view, the stale view or a status filter). Only
223  // the registrar sets it, before every handler; a bench run key is bound by it
224  // (benchRunRefusal).
225  call?: { jobId?: string; filtered: boolean };
226  // The action, for a tool whose action decides what it does. Present means the tools
227  // axis may narrow this call to the actions it names (allowsToolAction).
228  action?: string;
229  // The namespace this call touches. `undefined` means the call names none, which is
230  // not the same as "allowed" (see namespaceRefusal).
231  namespace?: string;
232  // The resolved repo, "owner/name", never the selector the caller passed.
233  //
234  // The `repo` argument is a selector: a label ("primary", "legacy") or a full
235  // owner/name that the namespace maps. The repos axis holds owner/name entries, so
236  // comparing the selector to the axis gets both directions wrong: the legitimate
237  // label "primary" is refused, and omitting the argument (almost every call) skips
238  // the axis while resolveRepo picks the namespace primary. Resolve first, then ask.
239  repo?: string;
240  // The document path a call names, for the one exception to the namespace axis: a
241  // read of a portfolio document in capsid (portfolioReadAdmits).
242  path?: string;
243  grant?: AgentGrant;
244  // The caller must be the admin identity, not merely hold the write grant. Set by
245  // the registrar for a tool whose TOOL_GRANTS entry is "admin" or "admin_read".
246  admin?: boolean;
247  // The action is a risky admin action (STEP_UP): an OAuth session needs a recent
248  // sign-in. Set by the registrar.
249  stepUp?: boolean;
250  // Flags whose absence refuses the call. Every one is checked, and the refusal
251  // names the FIRST missing one.
252  flags?: readonly ScopeFlag[];
253}
254
255// The work queue's tool, named once: the handlers' re-checks
256// (src/tools/jobs.ts, src/jobs-schema.ts, src/ops-session-auth.ts) ask about it.
257export const JOBS_TOOL = "capsid_work_jobs";
258
259// Why a flag is needed, so a refusal tells the caller what to ask for.
260const FLAG_REASON: Record<ScopeFlag, string> = {
261  can_merge: "merging a pull request can trigger a deploy on a repo that deploys on push",
262  can_direct_write: "a direct-mode commit lands on the default branch with no review",
263  can_dispatch: "dispatching a workflow spends CI minutes and runs code with that repo's secrets in scope",
264  can_write_workflows: "a workflow is what MEASURES the code, and a caller that can edit its own measurements has none",
265  can_touch_protected: "a protected path is tests, CI, lint or compiler config, a lockfile, a manifest, the agent steering layer, or a migration",
266  money_paths: "the path names a billing or payment surface",
267  can_comment_pr: "commenting on a pull request writes to a repo, and a reviewer that may comment must not thereby be able to merge or close",
268};
269
270// Order is deliberate: tool, grant, admin, namespace, repo, flags. A caller that
271// cannot use the tool is told that, not that its namespace is out of scope, which
272// would leak which namespaces exist.
273export function checkScope(agent: Agent, need: ScopeNeed): string | null {
274  if (agent.benchRun) {
275    const bound = benchRunRefusal(agent.benchRun, agent.actor, need);
276    if (bound) return bound;
277  }
278  const scopes = agent.scopes;
279  if (!allowsToolAction(scopes.tools, need.tool, need.action)) {
280    // Name the qualified tool.action that failed. A caller told it is not scoped to
281    // 'capsid_work_jobs' after being minted with capsid_work_jobs in its list would look for the wrong bug.
282    const asked = need.action === undefined ? need.tool : `${need.tool}.${need.action}`;
283    return `unauthorized: ${agent.actor} is not scoped to the '${asked}' tool. Its tool scope is ${describeScope(scopes.tools)}.`;
284  }
285  if (need.grant && !scopes.grants.includes(need.grant)) {
286    return (
287      `unauthorized: '${need.tool}' requires the ${need.grant} grant and ${agent.actor} holds ${scopes.grants.length ? scopes.grants.join(", ") : "no grant at all"}. ` +
288      `A read-only caller can use the read tools and nothing else.`
289    );
290  }
291  // Before the namespace check, so a driver calling an admin-only tool on its own
292  // namespace is told the tool is admin only.
293  if (need.admin && !agent.admin) {
294    const asked = need.action === undefined ? need.tool : `${need.tool}.${need.action}`;
295    return `unauthorized: '${asked}' is admin only and ${agent.actor} is not the admin. ${adminReason(need.tool)} Ask the admin to do it.`;
296  }
297  if (need.stepUp) {
298    const stale = stepUpRefusal(agent, need, Date.now());
299    if (stale) return stale;
300  }
301  if (need.namespace !== undefined && !allowsScope(scopes.namespaces, need.namespace) && !portfolioReadAdmits(need)) {
302    return (
303      `unauthorized: ${agent.actor} is not scoped to the '${need.namespace}' namespace. Its namespace scope is ${describeScope(scopes.namespaces)}.` +
304      (need.namespace === PORTFOLIO_DOCS.namespace
305        ? ` Outside its own namespace it may only read the portfolio documents in ${PORTFOLIO_DOCS.namespace}: ${describePortfolioDocs().join(", ")}.`
306        : "")
307    );
308  }
309  if (need.repo !== undefined && !allowsScope(scopes.repos, need.repo)) {
310    return `unauthorized: ${agent.actor} is not scoped to the '${need.repo}' repo. Its repo scope is ${describeScope(scopes.repos)}.`;
311  }
312  for (const flag of need.flags ?? []) {
313    if (!scopes.flags[flag]) {
314      return `unauthorized: '${need.tool}' needs the ${flag} flag and ${agent.actor} does not hold it, because ${FLAG_REASON[flag]}.`;
315    }
316  }
317  return null;
318}
319
320// What a bench run key may do (the methods paper's protocol, "The run key";
321// src/bench-run-key.ts): claim its one job, and list that job by id. Every other tool,
322// every other action, another job, no job, and a list that asks for more than the one
323// row are refused, so an action added later is closed to it until listed here. A
324// re-check inside the jobs handler carries no call and is not bound here: the
325// registrar's check, which binds every call, has already run.
326// complete and fail end the run's own account of its job (complete only with a
327// reproduction, src/jobs-seat.ts completeAsCaller); the score step still decides nothing
328// from them.
329const BENCH_RUN_ACTIONS: readonly string[] = ["claim", "list", "complete", "fail"];
330
331function benchRunRefusal(run: { run: string; job: string | null }, actor: string, need: ScopeNeed): string | null {
332  const refusal = `unauthorized: ${actor} is the run key of bench run ${run.run} and may only claim, read, complete or fail its own job`;
333  if (need.tool !== JOBS_TOOL) return `${refusal}; it cannot use ${need.tool}.`;
334  if (!need.call) return null;
335  if (!need.action || !BENCH_RUN_ACTIONS.includes(need.action)) return `${refusal}; it cannot ${need.action ?? "call the tool with no action"}.`;
336  if (run.job === null) return `${refusal}, and no single job carries this run's title yet.`;
337  if (need.call.jobId !== run.job) return `${refusal} (${run.job}); this call names ${need.call.jobId ?? "no job"}.`;
338  if (need.call.filtered) return `${refusal}; a list may not take a view, the stale view or a status filter.`;
339  return null;
340}
341
342// The one exception to the namespace axis (src/portfolio-docs.ts): any caller may read
343// the portfolio documents in capsid, because every driver is told to follow them. Only a
344// read tool on the list, so a write, a job or an edge never crosses. capsid_read_doc action read must
345// name an allowlisted path. capsid_find_docs actions list, glob and search name none: they are admitted here and their
346// handlers drop every capsid row that is not on the list (portfolioOnly).
347function portfolioReadAdmits(need: ScopeNeed): boolean {
348  if (need.namespace !== PORTFOLIO_DOCS.namespace) return false;
349  if (!isPortfolioTool(need.tool, need.action) || requiredGrant(need.tool) !== "read") return false;
350  if (need.grant !== undefined && need.grant !== "read") return false;
351  if (need.admin || need.flags?.length) return false;
352  if (need.tool === "capsid_read_doc") return need.path !== undefined && isPortfolioPath(need.path);
353  return true;
354}
355
356/** Whether this caller reaches `namespace` only through the portfolio exception, so a
357 *  listing handler must keep only the portfolio documents. */
358export function portfolioOnly(agent: Agent, namespace: string | undefined): boolean {
359  return namespace === PORTFOLIO_DOCS.namespace && !allowsScope(agent.scopes.namespaces, namespace);
360}
361
362// STEP-UP, for Capsid Admin:
363// the admin actions that change who may do what, or that cannot be taken back, need a
364// recent Access sign-in. A grant lives for weeks and is refreshed without a person;
365// this is the point where a person proves they are there. It is a re-authentication,
366// not a mid-call confirmation, which the ruling's rule 12 rules out until client
367// support is verified. "*" is every action of the tool.
368//
369// The window slides, as GitHub's sudo mode does: a step-up action is allowed when the
370// Access sign-in or the last SUCCESSFUL step-up action was within STEP_UP_IDLE_MS, and
371// each success resets that clock. A fixed window refused a working session mid-task.
372// STEP_UP_MAX_MS caps it from the sign-in whatever the activity (NIST SP 800-63B-4
373// allows an AAL3 session no more than 12 hours overall), so only a new sign-in extends
374// past it.
375//
376// Only an OAuth session carries a sign-in time (Agent.signedInAt). A key holder (the
377// seat's operator key at its terminal) has no session to refresh and is not stepped up;
378// its key is the credential.
379const STEP_UP_IDLE_MS = 2 * HOUR_MS;
380const STEP_UP_MAX_MS = 12 * HOUR_MS;
381
382export const STEP_UP: Record<string, readonly string[] | "*"> = {
383  capsid_admin_manage_namespaces: ["register", "update", "delete_perform"],
384  capsid_admin_manage_agents: ["mint", "revoke", "update_scopes"],
385  capsid_admin_run_controls: ["perform"],
386  capsid_admin_control_improve: "*",
387  capsid_admin_set_site_key: "*",
388};
389
390export function needsStepUp(tool: string, action: string | undefined): boolean {
391  if (!Object.hasOwn(STEP_UP, tool)) return false;
392  const actions = STEP_UP[tool];
393  return actions === "*" || (action !== undefined && actions.includes(action));
394}
395
396// The last successful step-up action is kept in KV, because each MCP request builds a
397// fresh Agent. It is kept per SESSION, keyed by the admin and the session's sign-in time,
398// not per admin: activity in one session (a laptop) must not keep another, idle one (a
399// forgotten device, or a grant whose refresh token leaked) inside the window. The entry
400// outlives the hard cap, so it never expires while it could still matter.
401const stepUpKey = (actor: string, signedInAt: number): string => `step-up:last:${actor}:${signedInAt}`;
402
403/** The time of this session's last successful step-up action, or undefined when there
404 *  is none or KV cannot say. Undefined falls back to the sign-in time alone, so a KV
405 *  failure can only narrow access, never widen it; a time after `now` is refused for the
406 *  same reason, since it would read as activity that has not happened. */
407export async function readLastStepUp(kv: KVNamespace, actor: string, signedInAt: number, now: number = Date.now()): Promise<number | undefined> {
408  try {
409    const value = Number(await kv.get(stepUpKey(actor, signedInAt)));
410    return Number.isFinite(value) && value > 0 && value <= now ? value : undefined;
411  } catch (error) {
412    logEvent("error", "STEP_UP_READ_FAILED", { message: `STEP_UP_READ_FAILED: ${error instanceof Error ? error.message : String(error)}; using the sign-in time alone` });
413    return undefined;
414  }
415}
416
417// Called only after a step-up action succeeded. The action is already done, so a KV
418// failure is logged and never fails it; the cost is that the idle clock is not reset.
419async function recordStepUp(kv: KVNamespace, agent: Agent, signedInAt: number, now: number): Promise<void> {
420  agent.lastStepUpAt = now;
421  try {
422    await kv.put(stepUpKey(agent.actor, signedInAt), String(now), { expirationTtl: STEP_UP_MAX_MS / 1000 + 3600 });
423  } catch (error) {
424    logEvent("error", "STEP_UP_WRITE_FAILED", { message: `STEP_UP_WRITE_FAILED: ${error instanceof Error ? error.message : String(error)}; the action succeeded and the idle clock was not reset` });
425  }
426}
427
428function stepUpRefusal(agent: Agent, need: ScopeNeed, now: number): string | null {
429  if (agent.signedInAt === undefined) return null;
430  const asked = need.action === undefined ? need.tool : `${need.tool}.${need.action}`;
431  const rule =
432    `A step-up action needs an Access sign-in or a step-up action within the last ${STEP_UP_IDLE_MS / HOUR_MS} hours, ` +
433    `and never more than ${STEP_UP_MAX_MS / HOUR_MS} hours after the sign-in.`;
434  const fix = `Reconnect the Capsid Admin connector (disconnect, then connect, and sign in), then call it again. Nothing was done.`;
435  if (agent.signedInAt === null) {
436    return `step-up required: '${asked}' changes who may do what or cannot be taken back. ${rule} This session signed in before sign-in times were recorded. ${fix}`;
437  }
438  const sinceSignIn = now - agent.signedInAt;
439  const sinceActive = now - Math.max(agent.signedInAt, agent.lastStepUpAt ?? 0);
440  if (sinceSignIn <= STEP_UP_MAX_MS && sinceActive <= STEP_UP_IDLE_MS) return null;
441  const minutes = (ms: number): string => `${Math.round(ms / MINUTE_MS)} minutes ago`;
442  const why =
443    sinceSignIn > STEP_UP_MAX_MS
444      ? `this session signed in ${minutes(sinceSignIn)}, past the ${STEP_UP_MAX_MS / HOUR_MS} hour cap`
445      : `this session signed in ${minutes(sinceSignIn)} and its last step-up action was ${agent.lastStepUpAt === undefined ? "none" : minutes(now - agent.lastStepUpAt)}`;
446  return `step-up required: '${asked}' changes who may do what or cannot be taken back. ${rule} Here ${why}. ${fix}`;
447}
448
449// Why each admin-only thing is admin only, for the refusal. An "admin" requirement
450// with no entry here fails the test that reads this table.
451const ADMIN_REASON: Record<string, string> = {
452  capsid_admin_whats_next:
453    "It reads what waits on the seat across every namespace and every mapped repo (blocked jobs, questions, open pull requests and their CI, stale work, failed checks), which is wider than any one caller's scope.",
454  capsid_admin_manage_namespaces:
455    "It edits the namespace-to-repo mapping, which is the authorization boundary every repo call resolves through, and its delete removes every live document of a namespace, so a scoped caller that could use it could widen itself or delete the boundary it sits behind.",
456  capsid_admin_manage_agents: "It mints, re-scopes and revokes agents, so a scoped caller that could use it could widen itself.",
457  capsid_admin_read_claims:
458    "It reads every agent's claims, the Worker's checks of them and every human touch, across every namespace, which is wider than any one caller's scope.",
459  capsid_admin_read_ops:
460    "It reads the watcher's last pass, the Cloudflare account's Access and Email Routing configuration, and every Workers Build, across every namespace, which is wider than any one caller's scope.",
461  capsid_admin_run_controls:
462    "It runs the administrator's controls (revoke an agent, resume or fail a job, edit the sites and packages the Portal watches), each of which changes what other callers may do or see, so a scoped caller that could use one could widen itself.",
463  capsid_admin_control_improve:
464    "It holds the administrator's switches: mint_operator_key issues a credential, sign_policy decides whether this Worker may merge without a human, breaker_reset reopens a namespace's queue and overnight starts unattended sessions, so a caller that could use one could widen itself. A driver reads status with capsid_run_improve.",
465  capsid_admin_set_site_key: "It mints a site's operator key and sets it as a secret on the site's Worker and on Carrel, so a caller that could use it could hand itself a site's key.",
466  "/ops/backup": "It backs up and prunes every namespace in the store, which is wider than any one namespace's scope.",
467};
468
469function adminReason(tool: string): string {
470  return Object.hasOwn(ADMIN_REASON, tool) ? ADMIN_REASON[tool] : "It acts on more than one namespace's scope.";
471}
472
473// The policy override is itself scoped: `allow_improve_paths`, which lets a document
474// write reach an autonomy policy document (capsid/policy/), needs these flags. The
475// argument keeps the improve loop's name, from when it also opened the loop's documents. The document tools check this list; it is named here so
476// the flag vocabulary stays inside the enforcement point.
477export const IMPROVE_OVERRIDE_FLAGS = ["can_touch_protected"] as const;
478
479// The same shape as fail() in tools/docs.ts, spelled here so the enforcement point
480// does not import the tool modules it guards (a cycle).
481function deny(message: string) {
482  return { content: [{ type: "text" as const, text: message }], isError: true };
483}
484
485// An omitted namespace means "every namespace" on tools such as capsid_find_docs
486// (list, glob, search), capsid_run_improve action status and capsid_work_jobs action list. For a caller scoped to "*" that changes nothing. For a
487// narrowed caller it would be a hole with no check in it, invisible because the tool
488// works. So a namespace-restricted caller that omits it is refused and told to name
489// it. Whether a tool takes a namespace is read from its own input schema, so a tool
490// that gains the argument is covered without anybody remembering to add it.
491function namespaceRefusal(agent: Agent, tool: string): string | null {
492  if (agent.scopes.namespaces === "*") return null;
493  return (
494    `unauthorized: ${agent.actor} is scoped to ${describeScope(agent.scopes.namespaces)}, so it must name a namespace on '${tool}'. ` +
495    `Omitting it asks for every namespace, which is wider than this caller's scope.`
496  );
497}
498
499interface RegisteredConfig {
500  inputSchema?: Record<string, unknown> | z.ZodObject;
501  // A composite tool's actions whose operation takes a namespace (src/tools/surface.ts).
502  // The merged schema declares `namespace` when any action takes one, and an action that
503  // takes none (capsid_find_docs action namespaces) must not be refused for omitting it.
504  // The registrar reads it and does not pass it on.
505  namespaceActions?: readonly string[];
506}
507
508type ToolHandler = (...args: unknown[]) => unknown;
509
510// Whether a handler's result is a success. An error result is not, and neither is a
511// domain refusal, which the tools return as an ordinary result whose JSON says ok:false
512// (the call was legitimate and the answer was no, so nothing was done).
513function toolSucceeded(result: unknown): boolean {
514  const r = result as { isError?: boolean; content?: Array<{ text?: unknown }> } | null;
515  if (r?.isError === true) return false;
516  const text = r?.content?.[0]?.text;
517  if (typeof text !== "string" || !text.startsWith("{")) return true;
518  try {
519    return (JSON.parse(text) as { ok?: unknown }).ok !== false;
520  } catch {
521    // Text that looks like JSON and is not is no proof of success: it does not reset the clock.
522    return false;
523  }
524}
525
526// Which argument names what a tool is asked to do. lint spells it `mode`, because its
527// modes separate a read (gather) from two writes. The registrar needs this to populate
528// need.action, and a per-tool answer scattered across the handlers leaves the
529// qualifier unwired. A tool absent here cannot be narrowed below the tool name. `mode` on
530// capsid_write_doc and capsid_change_repo is not an action: it already decides a flag
531// (can_direct_write) or a write shape, and one setting should not have two authorities.
532const ACTION_ARG: Record<string, string> = {
533  capsid_find_docs: "action",
534  capsid_read_doc: "action",
535  capsid_write_doc: "action",
536  capsid_lint_namespace: "mode",
537  capsid_read_repo: "action",
538  capsid_inspect_repo: "action",
539  capsid_change_repo: "action",
540  capsid_open_pr: "action",
541  capsid_close_pr: "action",
542  capsid_work_jobs: "action",
543  capsid_run_improve: "action",
544  capsid_admin_manage_namespaces: "action",
545  capsid_admin_manage_agents: "action",
546  capsid_admin_read_claims: "action",
547  capsid_admin_read_ops: "action",
548  capsid_admin_run_controls: "action",
549  capsid_admin_control_improve: "action",
550};
551
552// The action a tool falls back to when the caller omits an optional one, so a
553// narrowed list does not refuse the tool's own default. Every handler default needs
554// an entry: an unknown action on a narrowed tool is refused (allowsToolAction), so an
555// agent minted ["lint", "lint.gather"] would be refused its own default mode if the
556// registrar saw no action where the handler reads "gather".
557// test/audit-2026-09-16.test.ts derives the required entries from the served schemas:
558// an action argument a tool marks optional is a handler default.
559const DEFAULT_ACTION: Record<string, string> = {
560  capsid_find_docs: "list",
561  capsid_read_doc: "read",
562  capsid_write_doc: "write",
563  capsid_lint_namespace: "gather",
564  capsid_run_improve: "status",
565  capsid_admin_read_claims: "aggregate",
566};
567
568/** The action a call means when the caller omits the argument, or undefined. */
569export function defaultActionFor(tool: string): string | undefined {
570  return Object.hasOwn(DEFAULT_ACTION, tool) ? DEFAULT_ACTION[tool] : undefined;
571}
572
573export function actionArgFor(tool: string): string | undefined {
574  return Object.hasOwn(ACTION_ARG, tool) ? ACTION_ARG[tool] : undefined;
575}
576
577// The action this call asks for, read off the tool's own declared argument so an
578// unrelated property spelled "action" cannot narrow it.
579// A tool's declared arguments: a raw shape, or the shape of a zod object (the composite
580// tools, src/tools/surface.ts, register one so extra arguments reach their handler).
581function declaredShape(config: RegisteredConfig): Record<string, unknown> | undefined {
582  const schema = config?.inputSchema;
583  if (schema instanceof z.ZodObject) return schema.shape as Record<string, unknown>;
584  return schema;
585}
586
587function actionOf(tool: string, config: RegisteredConfig, args: Record<string, unknown>): string | undefined {
588  const key = actionArgFor(tool);
589  if (!key) return undefined;
590  const shape = declaredShape(config);
591  if (!shape || !Object.hasOwn(shape, key)) return undefined;
592  const value = args[key];
593  if (typeof value === "string") return value;
594  return defaultActionFor(tool);
595}
596
597// The registrar gate. Wraps the registration method once, before any tool module
598// runs, so every registration that follows is guarded whether or not its author
599// thought about scopes. A new tool cannot forget it, because a tool has to be
600// registered to exist.
601//
602// It wraps the server rather than replacing the call sites so every registration
603// stays a literal call on the server object, which test/invariants.test.ts,
604// test/tool-annotations.test.ts and test/counts.test.ts parse by that spelling. This
605// module must never spell that call itself, or those scanners would count it.
606export function guardRegistrations(server: McpServer, agent: Agent, observe?: AdminWriteObserver, stepUpKv?: KVNamespace): void {
607  const original = server.registerTool.bind(server) as (name: string, config: unknown, handler: ToolHandler) => unknown;
608  const patched = (name: string, config: RegisteredConfig, handler: ToolHandler) => {
609    const shape = declaredShape(config);
610    const declared = Boolean(shape && Object.hasOwn(shape, "namespace"));
611    const namespaceActions = config?.namespaceActions;
612    const takesNamespace = (action: string | undefined): boolean =>
613      namespaceActions && action !== undefined ? namespaceActions.includes(action) : declared;
614    const guarded: ToolHandler = (...callArgs: unknown[]) => {
615      const args = (callArgs[0] ?? {}) as Record<string, unknown>;
616      const namespace = typeof args.namespace === "string" ? args.namespace : undefined;
617      // Only a full owner/name can be compared to the axis here; the repo tools
618      // resolve a label and check the result (scopedRepo in src/tools/repo.ts).
619      const selector = typeof args.repo === "string" ? args.repo : undefined;
620      const repo = selector?.includes("/") ? selector : undefined;
621      const action = actionOf(name, config, args);
622      const refusal = checkScope(agent, {
623        tool: name,
624        namespace,
625        repo,
626        path: typeof args.path === "string" ? args.path : undefined,
627        action,
628        stepUp: needsStepUp(name, action),
629        ...(name === JOBS_TOOL
630          ? {
631              call: {
632                jobId: typeof args.id === "string" ? args.id : undefined,
633                filtered: args.view !== undefined || args.stale !== undefined || args.status !== undefined,
634              },
635            }
636          : {}),
637        // An "action" tool outside TOOL_ACTION_GRANTS (jobs, lint) is checked by its
638        // handler, where the namespace is known, so the registrar names no grant.
639        ...needFor(requiredForAction(name, action)),
640      });
641      if (refusal) return deny(refusal);
642      // A run key's call has already passed benchRunRefusal, which binds it to its one
643      // job in bench, so an omitted namespace asks for nothing wider.
644      if (takesNamespace(action) && namespace === undefined && !agent.benchRun) {
645        const missing = namespaceRefusal(agent, name);
646        if (missing) return deny(missing);
647      }
648      // Observation only (src/admin-client-audit.ts): after every refusal above, before
649      // the handler, and only for the admin and a requirement that is not a plain read.
650      // "action" tools (capsid_work_jobs, capsid_lint_namespace) are included, so a
651      // capsid_work_jobs action list is recorded too: more
652      // than a write, never less.
653      const run = (): unknown => {
654        const result = handler(...callArgs);
655        // A step-up action that succeeded resets the idle clock (STEP_UP). A refused or
656        // failed one does not: it proves nothing about the person being there.
657        const signedInAt = agent.signedInAt;
658        if (!stepUpKv || signedInAt === undefined || signedInAt === null || !needsStepUp(name, action)) return result;
659        return Promise.resolve(result).then(async (value) => {
660          if (toolSucceeded(value)) await recordStepUp(stepUpKv, agent, signedInAt, Date.now());
661          return value;
662        });
663      };
664      if (observe && agent.admin && requiredForAction(name, action) !== "read") {
665        return observe({ tool: name, action, namespace }, server.server.getClientVersion()?.name ?? null).then((refusal) =>
666          refusal ? deny(refusal) : run()
667        );
668      }
669      return run();
670    };
671    const { namespaceActions: _namespaceActions, ...served } = config ?? {};
672    return original(name, served, guarded);
673  };
674  (server as unknown as { registerTool: unknown }).registerTool = patched;
675}
676
677// Money paths: a repo path that names a billing or payment surface, matched by name.
678// A tripwire, not an authorization boundary. Broad on purpose and portfolio-wide: a
679// false positive costs one refusal naming the flag, a false negative is a payment
680// file edited by a credential nobody scoped for it. A word separator counts as a
681// boundary, so `stripe-client.ts` trips it (and so would `subscription-less.ts`).
682const MONEY_PATH = /(^|\/)(billing|payments?|checkout|invoices?|pricing|subscriptions?|stripe|payouts?|refunds?)(\/|[-_.]|$)/i;
683
684export function isMoneyPath(path: string): boolean {
685  return MONEY_PATH.test(path);
686}
687
688// Every flag a repo mutation needs, derived from the call, in one function so the
689// repo write tools cannot each decide a different answer.
690export function repoWriteFlags(
691  tool: string,
692  action: string | undefined,
693  args: { path?: string; mode?: string; allow_workflow_write?: boolean; force?: boolean }
694): ScopeFlag[] {
695  const flags: ScopeFlag[] = [];
696  if (args.mode === "direct") flags.push("can_direct_write");
697  if (args.allow_workflow_write === true) flags.push("can_write_workflows");
698  // close deletes the head branch, so a plain write grant could destroy the only copy
699  // of a branch somebody else pushed. That is the same blast radius as merge, so it
700  // needs can_merge too. Not deleting on close would leave stale branches behind. A tag
701  // or a release can start a deploy as a merge can.
702  if (tool === "capsid_close_pr" && (action === "merge" || action === "close" || action === "tag" || action === "release")) flags.push("can_merge");
703  // A forced branch delete too: force lifts the open-PR refusal, so it could delete
704  // another agent's open PR head. A delete without force needs no flag.
705  if (tool === "capsid_close_pr" && action === "delete_branch" && args.force === true) flags.push("can_merge");
706  // Separate from can_merge so the reviewer role can comment without merging.
707  if (tool === "capsid_open_pr" && action === "comment") flags.push("can_comment_pr");
708  if (tool === "capsid_run_ci") flags.push("can_dispatch");
709  // The protected list (src/protected-paths.ts). Those paths are what measure a repo:
710  // its tests, CI, lint and compiler config, lockfiles and manifests, agent steering
711  // layer and migrations. A scoped caller may touch them holding this flag.
712  if (args.path && protectedHits([args.path]).length > 0) flags.push("can_touch_protected");
713  if (args.path && isMoneyPath(args.path)) flags.push("money_paths");
714  return flags;
715}