app/lib/mcp/door.ts

Functions

Imports

It imports app/lib/agent-keys.server.ts, app/lib/deployed.ts, app/lib/mcp/registration.ts, app/lib/mcp/scopes.ts, app/lib/mcp/server.ts, app/lib/people.server.ts. Imported by workers/app.ts.

Source

1// The AI door: everything on carrel-mcp.dustinedwards.info (design decision 7, corrected 2026-09-27).
2//
3// That hostname is exempt from Carrel's Worker-level Access (a hostname Bypass app, setup in the PR),
4// because an MCP client must reach the OAuth endpoints before anyone has signed in. So nothing here
5// trusts Access's own header. Instead this door is an OAuth 2.1 authorization server of its own
6// (@cloudflare/workers-oauth-provider): CIMD for Claude, Claude Code and ChatGPT, a tightened
7// registration for Grok and Gemini (registration.ts), and the person signs in upstream through
8// Cloudflare Access for SaaS (site-runtime's access-login). The verified email must belong to an
9// active person in Carrel, checked when the grant is made and again on every request.
10//
11// Every request through this door is an AI session, told apart by the hostname it arrived on, never
12// by email. The pages are never served here, and this door is never served on the browser's host.
13//
14// Routes on this host, outermost first:
15//   /mcp                          a named agent key (agent-keys.server.ts) goes straight to agentHandler;
16//                                 anything else: the provider checks the bearer token, then apiHandler
17//                                 finds the person and hands the request to server.ts
18//   /authorize  /callback         the consent page and the Access sign-in, below
19//   /register                     tightened registration, rate limited here, then the provider
20//   /token, /.well-known/*        served by the provider
21//   /health                       liveness, and the deployed commit for the deploy's live gate
22//   anything else                 404
23
24import OAuthProvider, { AuthorizationError, CimdFetchError, type AuthRequest, type ClientInfo, type OAuthHelpers } from "@cloudflare/workers-oauth-provider";
25
26import { agentClient, agentPrincipal } from "~/lib/agent-keys.server";
27import { deployedSha } from "~/lib/deployed";
28import { findAgentViewer, findViewer } from "~/lib/people.server";
29
30import { accessSaas, authorizationUrl, finishSignIn, newSignIn } from "@dustinedwards/site-runtime/access-login";
31import { allowedRedirects, checkRegistration, REGISTER_PATH, registrationLimited } from "./registration";
32import { AGENT_SCOPES, effectiveScopes, grantScopes, SCOPE_WRITE, SCOPES_SUPPORTED } from "./scopes";
33import { carrelOrigin, handleMcp, MCP_ROUTE } from "./server";
34
35/** What a grant stores, encrypted, and hands to every request made with its tokens. */
36type DoorProps = { personId: number; email: string; client: string; clientId: string };
37
38type DoorEnv = Env & { OAUTH_PROVIDER: OAuthHelpers };
39
40/**
41 * The AI door's origin. Read loosely, like CARREL_ORIGIN, because a wrangler.jsonc from before this
42 * change has no CARREL_MCP_ORIGIN and its generated types would not either.
43 */
44export function mcpOrigin(env: Env): string {
45  const configured = (env as { CARREL_MCP_ORIGIN?: string }).CARREL_MCP_ORIGIN?.trim();
46  return (configured || "https://carrel-mcp.dustinedwards.info").replace(/\/+$/, "");
47}
48
49/** Whether a request arrived on the AI door's hostname. The only thing that decides the door. */
50export function isMcpHost(request: Request, env: Env): boolean {
51  return new URL(request.url).host.toLowerCase() === new URL(mcpOrigin(env)).host.toLowerCase();
52}
53
54// Caching and indexing only. The security headers are workers/security-headers.ts's, applied by
55// workers/app.ts to every response on this host.
56const PRIVATE_HEADERS: Record<string, string> = {
57  "Cache-Control": "no-store",
58  "X-Robots-Tag": "noindex, nofollow",
59};
60
61function text(body: string, status: number, headers?: Headers): Response {
62  const out = new Headers(headers);
63  out.set("Content-Type", "text/plain; charset=utf-8");
64  for (const [name, value] of Object.entries(PRIVATE_HEADERS)) out.set(name, value);
65  return new Response(body, { status, headers: out });
66}
67
68function redirect(location: string, headers?: Headers): Response {
69  const out = new Headers(headers);
70  out.set("Location", location);
71  out.set("Cache-Control", "no-store");
72  return new Response(null, { status: 302, headers: out });
73}
74
75/** The OAuth error answer to the client, once its redirect URI is known good. */
76function redirectError(request: AuthRequest, description: string, headers?: Headers): Response {
77  const url = new URL(request.redirectUri);
78  url.searchParams.set("error", "access_denied");
79  url.searchParams.set("error_description", description);
80  url.searchParams.set("state", request.state);
81  if (request.issuer) url.searchParams.set("iss", request.issuer);
82  return redirect(url.href, headers);
83}
84
85/**
86 * Liveness on the AI door, the one Carrel host outside Access, so CI can read it before anyone signs in.
87 * The live gate polls it until `sha` is the commit it deployed. It says nothing else: no backup age, no
88 * table, no error text (the backup health stays on the browser host's /health, behind Access).
89 */
90function liveness(env: Env): Response {
91  const out = new Headers({ "Content-Type": "application/json; charset=utf-8" });
92  for (const [name, value] of Object.entries(PRIVATE_HEADERS)) out.set(name, value);
93  return new Response(JSON.stringify({ ok: true, sha: deployedSha(env) }), { status: 200, headers: out });
94}
95
96const escape = (value: string) => value.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
97
98/** The name a client is credited by: its CIMD client_name, or else the host that publishes it. */
99function clientLabel(client: ClientInfo | null, clientId: string): string {
100  const name = client?.clientName?.trim();
101  if (name) return name.slice(0, 100);
102  try {
103    return new URL(clientId).hostname;
104  } catch {
105    return "an unnamed AI client";
106  }
107}
108
109/**
110 * The consent page, shown for every authorization of every client: nothing remembers an approval.
111 * Consent has to be an act, so it is a real form. Everything from the client is escaped: a CIMD
112 * document's name is chosen by whoever serves it, and a registered client's by whoever registered it.
113 */
114function consentPage(client: ClientInfo | null, request: AuthRequest, handle: string): string {
115  const name = escape(clientLabel(client, request.clientId));
116  const redirectHost = new URL(request.redirectUri).hostname;
117  const local = /^(localhost|127(\.\d{1,3}){3}|\[::1\])$/.test(redirectHost);
118  const publisher = request.clientId.startsWith("https://")
119    ? `Published by <strong>${escape(new URL(request.clientId).hostname)}</strong>.`
120    : "This app registered itself with Carrel, so its name is its own claim, not checked.";
121  const writes = grantScopes(request.scope).includes(SCOPE_WRITE);
122  const asks = writes
123    ? "It asks to read, save AI drafts beside yours, and flag problems. You can allow reading only."
124    : "It asks to read only. It will not be able to save drafts or flag problems.";
125  return `<!doctype html>
126<html lang="en"><head><meta charset="utf-8">
127<meta name="viewport" content="width=device-width,initial-scale=1">
128<meta name="robots" content="noindex,nofollow">
129<title>Allow ${name} to use Carrel?</title>
130<style>
131  :root { color-scheme: light dark; }
132  body { font: 17px/1.6 Georgia, "Iowan Old Style", serif; max-width: 34rem; margin: 4rem auto; padding: 0 1.25rem; }
133  h1 { font-size: 1.4rem; line-height: 1.3; }
134  .fine { font-size: .9rem; opacity: .8; }
135  button { font: inherit; padding: .55rem 1.1rem; border-radius: .35rem; cursor: pointer; margin-right: .5rem; }
136</style>
137</head><body>
138<h1>Allow ${name} to use Carrel as you?</h1>
139<p>${publisher} Its access will be sent to <strong>${escape(redirectHost)}</strong>.</p>
140${local ? "<p><strong>This sends access to an app on your computer.</strong> Continue only if you just started signing in from it.</p>" : ""}
141<p>${asks} Either way it can do only what your role in Carrel allows. Publishing is for Dustin's own sessions only, and never while a flag is open.</p>
142<p class="fine">Next you sign in with Cloudflare Access. Only people Carrel already knows are let in.</p>
143<form method="post">
144  <input type="hidden" name="handle" value="${escape(handle)}">
145  <button name="decision" value="approve">Continue to sign in</button>
146  ${writes ? '<button name="decision" value="read-only">Allow reading only</button>' : ""}
147  <button name="decision" value="deny">Deny</button>
148</form>
149</body></html>`;
150}
151
152async function authorizeGet(request: Request, env: DoorEnv): Promise<Response> {
153  if (!accessSaas(env)) return text("Carrel's AI door is not configured: ACCESS_SAAS_CLIENT_ID or ACCESS_SAAS_CLIENT_SECRET is unset. Not configured means not open.", 503);
154  const oauth = env.OAUTH_PROVIDER;
155  const authRequest = await oauth.parseAuthRequest(request);
156  const client = await oauth.lookupClient(authRequest.clientId);
157  if (!client) return text("Unknown OAuth client.", 400);
158  const consent = await oauth.beginConsent(authRequest);
159  consent.headers.set("Content-Type", "text/html; charset=utf-8");
160  // no-transform keeps Cloudflare from injecting its Web Analytics beacon into this page.
161  consent.headers.set("Cache-Control", "no-store, no-transform");
162  return new Response(consentPage(client, authRequest, consent.handle), { headers: consent.headers });
163}
164
165async function authorizePost(request: Request, env: DoorEnv): Promise<Response> {
166  const saas = accessSaas(env);
167  if (!saas) return text("Carrel's AI door is not configured. Not configured means not open.", 503);
168  const oauth = env.OAUTH_PROVIDER;
169  const form = await request.formData();
170  const handle = String(form.get("handle") ?? "");
171  const decision = form.get("decision");
172  if (decision !== "approve" && decision !== "read-only") {
173    const denied = await oauth.denyConsent(request, handle);
174    return new Response(null, { status: 302, headers: denied.headers });
175  }
176  const consented = await oauth.approveConsent(request, handle);
177  // Least scope: read, and write only when the client asked for it and the person did not narrow
178  // the grant to reading. The callback grants exactly this.
179  const approved = { ...consented, request: { ...consented.request, scope: grantScopes(consented.request.scope, { readOnly: decision === "read-only" }) } };
180  // Only now, after consent, does the sign-in start. The verifier and nonce stay server-side.
181  const signIn = newSignIn();
182  const { state, headers } = await oauth.beginUpstream(approved.request, { data: signIn, headers: approved.headers });
183  return redirect(await authorizationUrl(saas, { redirectUri: `${mcpOrigin(env)}/callback`, state, ...signIn }), headers);
184}
185
186async function callback(request: Request, env: DoorEnv): Promise<Response> {
187  const saas = accessSaas(env);
188  if (!saas) return text("Carrel's AI door is not configured. Not configured means not open.", 503);
189  const oauth = env.OAUTH_PROVIDER;
190  const { request: original, data, headers } = await oauth.finishUpstream<{ verifier: string; nonce: string }>(request);
191  const params = new URL(request.url).searchParams;
192  const code = params.get("code");
193  if (params.get("error") || !code) return redirectError(original, "Sign-in with Cloudflare Access did not complete.", headers);
194
195  const signedIn = await finishSignIn(saas, { code, redirectUri: `${mcpOrigin(env)}/callback`, verifier: data.verifier, nonce: data.nonce });
196  if (!signedIn.ok) {
197    console.warn(JSON.stringify({ door: "sign-in-refused", reason: signedIn.reason }));
198    return redirectError(original, "Carrel could not verify the sign-in.", headers);
199  }
200  const viewer = await findViewer(env.DB, signedIn.email);
201  if (!viewer) {
202    // Access let them in, but Carrel does not know them: no row, no access (design section 3).
203    console.warn(JSON.stringify({ door: "refused", reason: "unknown-person" }));
204    return redirectError(original, "This person is not in Carrel.", headers);
205  }
206
207  const client = clientLabel(await oauth.lookupClient(original.clientId).catch(() => null), original.clientId);
208  const props: DoorProps = { personId: viewer.id, email: viewer.email, client, clientId: original.clientId };
209  const { redirectTo } = await oauth.completeAuthorization({
210    request: original,
211    userId: String(viewer.id),
212    metadata: { client },
213    scope: original.scope,
214    props,
215  });
216  headers.set("Location", redirectTo);
217  headers.set("Cache-Control", "no-store");
218  return new Response(null, { status: 302, headers });
219}
220
221/** Everything on this host the provider does not own. */
222const loginHandler = {
223  async fetch(request: Request, env: DoorEnv): Promise<Response> {
224    const { pathname } = new URL(request.url);
225    try {
226      if (pathname === "/health") return liveness(env);
227      if (pathname === "/authorize" && request.method === "GET") return await authorizeGet(request, env);
228      if (pathname === "/authorize" && request.method === "POST") return await authorizePost(request, env);
229      if (pathname === "/callback" && request.method === "GET") return await callback(request, env);
230      return text("Not found.", 404);
231    } catch (error) {
232      // Per the provider's consent-page guide: redirect only to a validated client, render the rest.
233      if (error instanceof AuthorizationError && error.redirectUri) {
234        const url = new URL(error.redirectUri);
235        url.searchParams.set("error", error.code);
236        url.searchParams.set("error_description", error.description);
237        if (error.state) url.searchParams.set("state", error.state);
238        if (error.issuer) url.searchParams.set("iss", error.issuer);
239        return redirect(url.href);
240      }
241      if (error instanceof AuthorizationError) return text(`${error.description} Start the sign-in again from your MCP client.`, 400);
242      if (error instanceof CimdFetchError) return text("This app could not be verified: its client metadata document could not be fetched.", 400);
243      throw error;
244    }
245  },
246};
247
248/**
249 * The authenticated MCP surface. The provider has checked the token by the time this runs. The
250 * person is looked up again on every request: a grant lives for weeks, and a person disabled in
251 * Carrel must lose the door at once, not when the grant expires.
252 */
253export const apiHandler = {
254  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
255    const { props, auth } = ctx as ExecutionContext & { props?: Partial<DoorProps>; auth?: { audience?: string; scope?: string[] } };
256    // The token must have been issued for this server (RFC 8707), checked here as well as by the
257    // provider, so a provider set up for a second resource could never hand Carrel a token for it.
258    // Nothing passes the token on: the site and the novels repository take Carrel's own keys.
259    if (auth?.audience !== `${mcpOrigin(env)}${MCP_ROUTE}`) {
260      console.warn(JSON.stringify({ door: "refused", reason: "audience", audience: auth?.audience ?? null }));
261      return text("Forbidden. This token was not issued for Carrel.", 403);
262    }
263    const viewer = props?.email ? await findViewer(env.DB, props.email) : null;
264    if (!viewer || viewer.id !== props?.personId) {
265      console.warn(JSON.stringify({ door: "refused", reason: viewer ? "person-changed" : "unknown-person" }));
266      return text("Forbidden. This grant does not belong to an active person in Carrel.", 403);
267    }
268    const session = { viewer, client: props.client || "an unnamed AI client", scopes: effectiveScopes(auth.scope ?? []) };
269    const response = await handleMcp(request, env, ctx, session, { carrelOrigin: carrelOrigin(env) });
270    const out = new Response(response.body, response);
271    for (const [name, value] of Object.entries(PRIVATE_HEADERS)) out.headers.set(name, value);
272    return out;
273  },
274};
275
276/**
277 * The named-agent surface. A key (agent-keys.server.ts) names an agent, and the agent is the person
278 * row "agent:<name>" in Carrel's People table, found again on every request: disabling that row
279 * revokes the agent at once, and its role on each project is whatever People says, never the key's.
280 * A key with no active row is refused here and never falls through to anything. Writes are credited
281 * to "agent:<name>", the same text as the person, never to Dustin.
282 */
283async function agentHandler(request: Request, env: Env, ctx: ExecutionContext, name: string): Promise<Response> {
284  const viewer = await findAgentViewer(env.DB, name);
285  if (!viewer) {
286    console.warn(JSON.stringify({ door: "refused", reason: "agent-not-in-carrel", agent: name }));
287    return text("Forbidden. This agent key does not belong to an active agent in Carrel.", 403);
288  }
289  console.log(JSON.stringify({ door: "agent-key-accepted", agent: name }));
290  const response = await handleMcp(request, env, ctx, { viewer, client: agentClient(name), scopes: AGENT_SCOPES }, { carrelOrigin: carrelOrigin(env) });
291  const out = new Response(response.body, response);
292  for (const [header, value] of Object.entries(PRIVATE_HEADERS)) out.headers.set(header, value);
293  return out;
294}
295
296const providers = new Map<string, OAuthProvider<Env>>();
297
298/**
299 * One provider per origin and registration allowlist: the resource URI and the registration policy
300 * are both fixed at construction, so a changed allowlist gets a new provider, never a stale one.
301 */
302function providerFor(env: Env): OAuthProvider<Env> {
303  const origin = mcpOrigin(env);
304  const allowed = allowedRedirects(env);
305  const key = `${origin} ${[...allowed].join(" ")}`;
306  let provider = providers.get(key);
307  if (!provider) {
308    provider = new OAuthProvider<Env>({
309      apiRoute: MCP_ROUTE,
310      apiHandler,
311      defaultHandler: loginHandler as unknown as ExportedHandler<Env>,
312      authorizeEndpoint: "/authorize",
313      tokenEndpoint: "/token",
314      scopesSupported: SCOPES_SUPPORTED,
315      resourceMetadata: {
316        resource: `${origin}${MCP_ROUTE}`,
317        authorization_servers: [origin],
318        scopes_supported: SCOPES_SUPPORTED,
319        resource_name: "Carrel",
320      },
321      // CIMD first. claude.ai, Claude Code and ChatGPT send their client_id as a metadata URL and
322      // never register (measured in dustinedwards-mcp, 2026-07-30). Needs global_fetch_strictly_public
323      // in wrangler.jsonc.
324      clientIdMetadataDocumentEnabled: true,
325      // Tightened registration beside it, for Grok and Gemini (rule 13, registration.ts): exact
326      // callbacks only, a code and refresh grant only, rate limited in aiDoor before it gets here.
327      clientRegistrationEndpoint: REGISTER_PATH,
328      clientRegistrationCallback: ({ clientMetadata }) => checkRegistration(allowed, clientMetadata),
329    });
330    providers.set(key, provider);
331  }
332  return provider;
333}
334
335/** Serves one request that arrived on the AI door's hostname. */
336export async function aiDoor(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
337  const { pathname } = new URL(request.url);
338  if (pathname === MCP_ROUTE || pathname.startsWith(`${MCP_ROUTE}/`)) {
339    // Tried, never required: no match (no secret, a bad header, an OAuth token) is the OAuth path, unchanged.
340    const agent = await agentPrincipal(env, request.headers.get("Authorization"));
341    if (agent) return agentHandler(request, env, ctx, agent);
342  }
343  if (pathname === REGISTER_PATH && request.method === "POST") {
344    const limited = await registrationLimited(request, env);
345    if (limited) return limited;
346  }
347  return providerFor(env).fetch(request, env, ctx);
348}