src/index.ts

Functions

Imports

It imports src/admin-client-audit.ts, src/agents.ts, src/auth.ts, src/backup.ts, src/dcr.ts, src/env.ts, src/log.ts, src/mcp-handler.ts, src/mcp-host.ts, src/portal-host.ts, src/routes.ts, src/scope.ts, src/security-headers.ts, src/server.ts, src/skills-refresh.ts, src/supersede.ts, src/task-runs.ts, src/tick.ts. No module of this repo imports it.

Source

1import OAuthProvider from "@cloudflare/workers-oauth-provider";
2import { adminGrantEmail } from "./auth";
3import { adminAgentForEmail } from "./agents";
4import { readLastStepUp } from "./scope";
5import { adminWriteObserver, recordAdminInitialize } from "./admin-client-audit";
6import { runBackup } from "./backup";
7import { supersedePass } from "./supersede";
8import { defaultHandler } from "./routes";
9import { mcpOriginProblem, withSecurityHeaders } from "./security-headers";
10import type { Env, Props } from "./env";
11import { buildAdminServer, buildServer } from "./server";
12import { ADMIN_MCP_ROUTE, serveMcp } from "./mcp-handler";
13import { gateRegistration, REGISTER_PATH } from "./dcr";
14import { runTick } from "./tick";
15import { NOT_ITS_DAY, runSkillsRefresh } from "./skills-refresh";
16import { runTask, type TaskResult } from "./task-runs";
17import { portalHostRequest } from "./portal-host";
18import { hostRefusal, LEGACY_HOST, LEGACY_MCP_URL, MCP_URL } from "./mcp-host";
19import { logEvent } from "./log";
20
21// Spelled once. wrangler.jsonc declares them; test/crons.test.ts derives one list
22// from the other and fails in both directions.
23export const BACKUP_CRON = "0 9 * * *";
24export const TICK_CRON = "*/5 * * * *";
25// Fires daily; readSchedule decides from KV whether today is the configured day, so
26// the weekly schedule changes without a redeploy.
27export const SKILLS_REFRESH_CRON = "30 9 * * *";
28
29const apiHandler = {
30  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
31    // Checked on every request, not only at sign-in (src/auth.ts adminGrantEmail).
32    const email = await adminGrantEmail(env, (ctx as ExecutionContext & { props?: Props }).props);
33    if (!email) {
34      return new Response("forbidden: this grant does not belong to an administrator of capsid", {
35        status: 403,
36      });
37    }
38    // The admin agent holds every scope; the email Access verified is the audit actor.
39    const props = (ctx as ExecutionContext & { props?: Props }).props;
40    const signedInAt = typeof props?.signed_in_at === "number" ? props.signed_in_at : null;
41    const admin = adminAgentForEmail(email, signedInAt);
42    // Only Capsid Admin serves step-up actions, so only its route reads the clock. A KV
43    // failure leaves it undefined, which falls back to the sign-in time alone (src/scope.ts STEP_UP).
44    const adminRoute = new URL(request.url).pathname === ADMIN_MCP_ROUTE;
45    if (adminRoute && signedInAt !== null) admin.lastStepUpAt = await readLastStepUp(env.APP_KV, admin.actor, signedInAt);
46    // Observation only, for 30 days (src/admin-client-audit.ts): which client the admin
47    // acts through. It never refuses on what the client says.
48    await recordAdminInitialize(env.DB, admin.actor, request);
49    const observe = adminWriteObserver(env.DB, admin.actor, request.headers.get("User-Agent"));
50    // Capsid Admin on its own route: the eight administrator tools, never on /mcp. Only the administrator's grant
51    // reaches this handler at all, and the step-up in src/scope.ts guards its risky actions.
52    if (adminRoute) {
53      return serveMcp(request, env, ctx, ADMIN_MCP_ROUTE, () => buildAdminServer(env, admin, "", observe));
54    }
55    return serveMcp(request, env, ctx, "/mcp", () => buildServer(env, admin, "", observe));
56  },
57};
58
59// Fail-closed: every response leaves with no-store unless it asked otherwise.
60const CACHE_EXEMPT_PATHS = new Set(["/health"]);
61
62function withCacheDefault(response: Response, pathname: string): Response {
63  if (CACHE_EXEMPT_PATHS.has(pathname)) return response;
64  if (response.headers.has("Cache-Control")) return response;
65  // Headers on an already-constructed Response can be immutable, so rebuild.
66  const headers = new Headers(response.headers);
67  headers.set("Cache-Control", "no-store");
68  return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
69}
70
71// The RFC 8707 resource is per host. workers-oauth-provider binds every access token to
72// ONE configured resource and refuses a token whose audience origin is not the host the
73// request arrived on (token_audience_unbound, audience_mismatch), so one provider cannot
74// serve /mcp on two hosts. The MCP endpoint lives at MCP_URL; the old address keeps its
75// own provider only for the hours of the same-day cut (job_2f9671f89e89), so the
76// claude.ai connector, authorized there, works until it is switched. Both share OAUTH_KV.
77// The step that turns workers.dev off removes legacyProvider.
78function oauthProvider(resource: string, registration: boolean) {
79  return new OAuthProvider({
80    apiRoute: "/mcp",
81    apiHandler,
82    defaultHandler,
83    authorizeEndpoint: "/authorize",
84    tokenEndpoint: "/token",
85    resourceMetadata: { resource },
86    // CIMD first (capsid/mcp-wrapper-standard.md, amendment 2026-09-27): a client's id is
87    // the URL of its metadata document. The provider advertises CIMD only while the
88    // global_fetch_strictly_public compatibility flag is set (wrangler.jsonc.example).
89    clientIdMetadataDocumentEnabled: true,
90    // Tightened DCR for Grok and Gemini, on
91    // the MCP host only: src/dcr.ts judges every registration before the provider
92    // sees it. The old address keeps none; it is going.
93    ...(registration ? { clientRegistrationEndpoint: REGISTER_PATH } : {}),
94  });
95}
96
97const provider = oauthProvider(MCP_URL, true);
98const legacyProvider = oauthProvider(LEGACY_MCP_URL, false);
99
100export default {
101  async fetch(original: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
102    // portal.dustinedwards.info serves the Portal and nothing else (src/portal-host.ts):
103    // /x there is /portal/x here, and an old /portal address redirects to the root. It
104    // runs FIRST, before the OAuth provider, because the provider answers its own routes
105    // (/mcp, /token, /authorize, /register, its metadata) without reaching the routes
106    // handler. Behind the provider, /mcp on the Portal host was the MCP endpoint, and
107    // live gate 7 rolled #218's deploy back (run 36863432268).
108    const host = portalHostRequest(original);
109    if ("redirect" in host) return withSecurityHeaders(host.redirect);
110    const request = host.request;
111    // The MCP host serves the machine surface only, and the old address's /portal is
112    // retired (src/mcp-host.ts). Also before the provider, for the same reason.
113    const refused = hostRefusal(request);
114    if (refused) return withSecurityHeaders(withCacheDefault(refused, new URL(request.url).pathname));
115    const pathname = new URL(request.url).pathname;
116    if (pathname === "/mcp" || pathname === ADMIN_MCP_ROUTE) {
117      const originProblem = mcpOriginProblem(request);
118      if (originProblem) {
119        return withSecurityHeaders(withCacheDefault(new Response(originProblem, { status: 403 }), pathname));
120      }
121    }
122    const legacy = new URL(request.url).hostname === LEGACY_HOST;
123    let forwarded = request;
124    if (!legacy && pathname === REGISTER_PATH && request.method === "POST") {
125      const gate = await gateRegistration(request, env, new Date());
126      if ("refuse" in gate) return withSecurityHeaders(withCacheDefault(gate.refuse, pathname));
127      forwarded = gate.forward;
128    }
129    const response = await (legacy ? legacyProvider : provider).fetch(forwarded, env, ctx);
130    return withSecurityHeaders(withCacheDefault(response, pathname));
131  },
132  // Dispatch on controller.cron, not the clock: 09:00 UTC matches all three
133  // expressions and Cloudflare delivers once per expression. Each branch is its own
134  // task so a throwing tick cannot stop the backup. runTask (src/task-runs.ts) records every run in the
135  // run ledger, logs a throw with the tag named here, and rethrows it so the
136  // invocation shows as failed.
137  scheduled(controller: ScheduledController, env: Env, ctx: ExecutionContext) {
138    const cron = controller.cron;
139
140    if (cron === BACKUP_CRON) {
141      ctx.waitUntil(
142        runTask(
143          env,
144          "backup",
145          () => runBackup(env),
146          (result): TaskResult => {
147            if (!result.ran) {
148              logEvent("error", "BACKUP_CRON_SKIPPED", { message: `BACKUP_CRON_SKIPPED ${result.skipped}` });
149              return { outcome: "skipped", reason: `skipped: ${result.skipped}` };
150            }
151            if (result.prune_refused !== null) {
152              logEvent("error", "BACKUP_CRON_REFUSED_PRUNE", { message: `BACKUP_CRON_REFUSED_PRUNE ${result.prune_refused}` });
153              return { outcome: "refused", reason: `wrote ${result.json_keys.length} dump objects, and the prune refused: ${result.prune_refused}` };
154            }
155            return {
156              outcome: "ok",
157              reason: `wrote ${result.json_keys.length} dump objects (${result.documents} documents); pruned ${result.json_backups_pruned} dumps (${result.json_backups_locked} locked), ${result.versions_pruned} versions, ${result.audit_pruned} audit rows`,
158            };
159          },
160          { tag: "BACKUP_CRON_THREW", rethrow: true }
161        )
162      );
163      // Its own task, so a throw here cannot stop the backup (design-hybrid-search 3.4).
164      ctx.waitUntil(
165        runTask(
166          env,
167          "supersede",
168          () => supersedePass(env),
169          (report): TaskResult => {
170            if (report.marked.length === 0) return null;
171            const line = report.marked.map((m) => `${m.document} by ${m.by}`).join("; ");
172            return { outcome: "ok", reason: `marked ${report.marked.length} superseded${report.more ? " (more next pass)" : ""}: ${line}` };
173          },
174          { tag: "SUPERSEDE_PASS_THREW", rethrow: true }
175        )
176      );
177    }
178
179    if (cron === TICK_CRON) {
180      ctx.waitUntil(
181        runTask(
182          env,
183          "tick",
184          () => runTick(env, new Date()),
185          (): TaskResult => ({ outcome: "ok", reason: "the tick's steps ran; each records its own run" }),
186          { tag: "TICK_THREW", rethrow: true }
187        )
188      );
189    }
190
191    if (cron === SKILLS_REFRESH_CRON) {
192      ctx.waitUntil(
193        runTask(
194          env,
195          "skills-refresh",
196          () => runSkillsRefresh(env, new Date()),
197          (outcome): TaskResult => {
198            if (!outcome.ran) {
199              logEvent("log", "SKILLS_REFRESH_SKIPPED", { message: `SKILLS_REFRESH_SKIPPED ${outcome.skipped}` });
200              // Not its day of the week is not a run; switched off is a skip worth showing.
201              return outcome.skipped?.startsWith(NOT_ITS_DAY) ? null : { outcome: "skipped", reason: `skipped: ${outcome.skipped ?? "no reason given"}` };
202            }
203            const line = `checked=${outcome.checked} changed=${outcome.changed.join(",") || "none"} posted=${outcome.posted.join(",") || "none"}`;
204            logEvent("log", "SKILLS_REFRESH", { message: `SKILLS_REFRESH ${line}` });
205            for (const r of outcome.refused) logEvent("error", "SKILLS_REFRESH_REFUSED", { message: `SKILLS_REFRESH_REFUSED ${r.slug}: ${r.reason}` });
206            return outcome.refused.length > 0
207              ? { outcome: "refused", reason: `${line}; refused ${outcome.refused.map((r) => `${r.slug}: ${r.reason}`).join("; ")}` }
208              : { outcome: "ok", reason: line };
209          },
210          { tag: "SKILLS_REFRESH_THREW", rethrow: true }
211        )
212      );
213    }
214  },
215} satisfies ExportedHandler<Env>;