mcp-login.mjs

Functions

Imports

It imports access-login.mjs, html.mjs. Imported by mcp-server.mjs.

Source

1/**
2 * The consent page and the upstream sign-in of a single-administrator MCP server, behind
3 * @cloudflare/workers-oauth-provider, and the tightened check on a dynamic client registration.
4 *
5 * The provider makes the Worker an OAuth 2.1 authorization server for MCP clients. It does not know who the human is,
6 * so after consent this handler sends them to Cloudflare Access for SaaS (`./access-login`) and lets in only the email
7 * the caller's `admit` accepts.
8 *
9 * The consent handle and the upstream state are the provider's own helpers (beginConsent, approveConsent,
10 * beginUpstream, finishUpstream): each is bound to the browser by a cookie the library sets and works once, so another
11 * site cannot submit consent or replay a callback. The PKCE verifier and nonce travel in the upstream state,
12 * server-side.
13 *
14 * Least scope first: the write box starts ticked only when the client asked for the write scope, the grant is what the
15 * administrator ticked, never what the client asked, and every grant holds the read scope.
16 *
17 * The provider is matched by its errors' names, not imported, so this package keeps no dependencies.
18 */
19
20import { accessSaas, authorizationUrl, finishSignIn, newSignIn } from "./access-login.mjs";
21import { escapeHtml as escape } from "./html.mjs";
22
23/** @typedef {import("./mcp-login.d.mts").LoginEnv} LoginEnv */
24/** @typedef {import("@cloudflare/workers-oauth-provider").AuthRequest} AuthRequest */
25/** @typedef {import("@cloudflare/workers-oauth-provider").ClientInfo} ClientInfo */
26
27// Caching and indexing: an authenticated operator surface is never cached or indexed.
28const PRIVATE_HEADERS = {
29  "cache-control": "no-store",
30  "x-content-type-options": "nosniff",
31  "referrer-policy": "no-referrer",
32  "x-robots-tag": "noindex, nofollow",
33};
34
35/** @param {string} body @param {number} [status] @param {Headers} [headers] */
36function text(body, status = 200, headers) {
37  const out = new Headers(headers);
38  out.set("content-type", "text/plain; charset=utf-8");
39  for (const [name, value] of Object.entries(PRIVATE_HEADERS)) out.set(name, value);
40  return new Response(body, { status, headers: out });
41}
42
43/** @param {string} location @param {Headers} [headers] */
44function redirect(location, headers) {
45  const out = new Headers(headers);
46  out.set("location", location);
47  out.set("cache-control", "no-store");
48  return new Response(null, { status: 302, headers: out });
49}
50
51/**
52 * The OAuth error answer to the client, once its redirect URI is known good.
53 * @param {AuthRequest} request @param {string} description @param {Headers} [headers]
54 */
55function redirectError(request, description, headers) {
56  const url = new URL(request.redirectUri);
57  url.searchParams.set("error", "access_denied");
58  url.searchParams.set("error_description", description);
59  url.searchParams.set("state", request.state);
60  if (request.issuer) url.searchParams.set("iss", request.issuer);
61  return redirect(url.href, headers);
62}
63
64/** @param {Request} request @param {LoginEnv} env */
65function origin(request, env) {
66  return (env.PUBLIC_ORIGIN?.trim() || new URL(request.url).origin).replace(/\/+$/, "");
67}
68
69/**
70 * The name a client is shown by: its own client_name, or the host that publishes its metadata.
71 * @param {ClientInfo | null} client @param {string} clientId
72 */
73function clientLabel(client, clientId) {
74  const name = client?.clientName?.trim();
75  if (name) return name.slice(0, 100);
76  try {
77    return new URL(clientId).hostname;
78  } catch {
79    return "an unnamed client";
80  }
81}
82
83/**
84 * The consent page's one inline <style>. The page renders this exact string between the tags, so a server's
85 * Content-Security-Policy trusts it by hash (`scriptHash(CONSENT_STYLE)` from `./csp`) and the two cannot drift.
86 */
87export const CONSENT_STYLE = `
88  :root { color-scheme: light dark; }
89  body { font: 16px/1.6 system-ui, sans-serif; max-width: 34rem; margin: 4rem auto; padding: 0 1.25rem; }
90  h1 { font-size: 1.35rem; line-height: 1.3; }
91  label { display: inline-flex; gap: .5rem; align-items: center; min-height: 24px; }
92  button { font: inherit; padding: .55rem 1.1rem; border-radius: .35rem; cursor: pointer; margin-right: .5rem; min-height: 24px; }
93`;
94
95const NOT_CONFIGURED =
96  "This server is not configured for sign-in: ACCESS_TEAM_DOMAIN, ACCESS_SAAS_CLIENT_ID or " +
97  "ACCESS_SAAS_CLIENT_SECRET is unset. Not configured means not open.";
98
99/**
100 * The provider's defaultHandler: /health, the consent page and its form on /authorize, and the Access /callback. A
101 * missing Access setting answers 503 on every sign-in route.
102 * @template {LoginEnv} E
103 * @param {import("./mcp-login.d.mts").LoginOptions<E>} options
104 */
105export function loginHandler({ name, scopes, about, admit }) {
106  const serverName = escape(name);
107
108  /**
109   * Consent has to be an act, so it is a real form. Everything from the client is escaped: a CIMD document's name is
110   * chosen by whoever serves it, a registered client's by its registrant. `about` is the server's own HTML.
111   * @param {ClientInfo | null} client @param {AuthRequest} request @param {string} handle
112   */
113  function consentPage(client, request, handle) {
114    const label = escape(clientLabel(client, request.clientId));
115    const redirectHost = escape(new URL(request.redirectUri).hostname);
116    const wantsWrite = request.scope.includes(scopes.write);
117    return `<!doctype html>
118<html lang="en"><head><meta charset="utf-8">
119<meta name="viewport" content="width=device-width,initial-scale=1">
120<meta name="robots" content="noindex,nofollow">
121<title>Allow ${label} to use ${serverName}?</title>
122<style>${CONSENT_STYLE}</style>
123</head><body>
124<h1>Allow ${label} to use ${serverName}?</h1>
125<p>Its access will be sent to <strong>${redirectHost}</strong>.</p>
126${about.trim()}
127<p>Next you sign in with Cloudflare Access. Only the configured administrator is accepted.</p>
128<form method="post">
129  <input type="hidden" name="handle" value="${escape(handle)}">
130  <p><label><input type="checkbox" name="allow_write" value="1"${wantsWrite ? " checked" : ""}>
131  Allow changes (${escape(scopes.write)})</label></p>
132  <button name="decision" value="approve">Continue to sign in</button>
133  <button name="decision" value="deny">Deny</button>
134</form>
135</body></html>`;
136  }
137
138  /** @param {Request} request @param {E} env */
139  async function authorizeGet(request, env) {
140    if (!accessSaas(env)) return text(NOT_CONFIGURED, 503);
141    const oauth = env.OAUTH_PROVIDER;
142    const authRequest = await oauth.parseAuthRequest(request);
143    const client = await oauth.lookupClient(authRequest.clientId);
144    if (!client) return text("Unknown OAuth client.", 400);
145    const consent = await oauth.beginConsent(authRequest);
146    consent.headers.set("content-type", "text/html; charset=utf-8");
147    // no-transform keeps Cloudflare from injecting anything into this page.
148    consent.headers.set("cache-control", "no-store, no-transform");
149    return new Response(consentPage(client, authRequest, consent.handle), { headers: consent.headers });
150  }
151
152  /** @param {Request} request @param {E} env */
153  async function authorizePost(request, env) {
154    const saas = accessSaas(env);
155    if (!saas) return text(NOT_CONFIGURED, 503);
156    const oauth = env.OAUTH_PROVIDER;
157    const form = await request.formData();
158    const handle = String(form.get("handle") ?? "");
159    if (form.get("decision") !== "approve") {
160      const denied = await oauth.denyConsent(request, handle);
161      return redirect(denied.redirectTo, denied.headers);
162    }
163    const scope = form.get("allow_write") === "1" ? [scopes.read, scopes.write] : [scopes.read];
164    const approved = await oauth.approveConsent(request, handle, { scope });
165    const signIn = newSignIn();
166    const { state, headers } = await oauth.beginUpstream({ ...approved.request, scope }, { data: signIn, headers: approved.headers });
167    return redirect(await authorizationUrl(saas, { redirectUri: `${origin(request, env)}/callback`, state, ...signIn }), headers);
168  }
169
170  /** @param {Request} request @param {E} env */
171  async function callback(request, env) {
172    const saas = accessSaas(env);
173    if (!saas) return text(NOT_CONFIGURED, 503);
174    const oauth = env.OAUTH_PROVIDER;
175    const { request: original, data, headers } = await oauth.finishUpstream(request);
176    const { verifier, nonce } = /** @type {{ verifier: string, nonce: string }} */ (data);
177    const code = new URL(request.url).searchParams.get("code");
178    if (!code) return redirectError(original, "Sign-in with Cloudflare Access did not complete.", headers);
179
180    const signedIn = await finishSignIn(saas, { code, redirectUri: `${origin(request, env)}/callback`, verifier, nonce });
181    if (!signedIn.ok) {
182      console.warn(JSON.stringify({ door: "refused", reason: signedIn.reason }));
183      return redirectError(original, "Cloudflare Access did not confirm the sign-in.", headers);
184    }
185    if (!(await admit(env, signedIn))) {
186      console.warn(JSON.stringify({ door: "refused", reason: "not-the-administrator" }));
187      return redirectError(original, `This account is not the administrator of ${name}.`, headers);
188    }
189
190    const granted = original.scope.includes(scopes.write) ? [scopes.read, scopes.write] : [scopes.read];
191    const { redirectTo } = await oauth.completeAuthorization({
192      request: original,
193      userId: signedIn.email.toLowerCase(),
194      metadata: { email: signedIn.email },
195      scope: granted,
196      props: { email: signedIn.email, scopes: granted },
197    });
198    return redirect(redirectTo, headers);
199  }
200
201  return {
202    /** @param {Request} request @param {E} env @returns {Promise<Response>} */
203    async fetch(request, env) {
204      const { pathname } = new URL(request.url);
205      try {
206        if (pathname === "/health") return text("ok");
207        if (pathname === "/authorize" && request.method === "GET") return await authorizeGet(request, env);
208        if (pathname === "/authorize" && request.method === "POST") return await authorizePost(request, env);
209        if (pathname === "/callback" && request.method === "GET") return await callback(request, env);
210        return text("Not found.", 404);
211      } catch (error) {
212        // Redirect only to a validated client; render the rest.
213        if (error instanceof Error && error.name === "AuthorizationError") {
214          const failure = /** @type {Error & { code: string, description: string, redirectUri?: string, state?: string, issuer?: string }} */ (error);
215          if (!failure.redirectUri) return text(`${failure.description} Start the sign-in again from your MCP client.`, 400);
216          const url = new URL(failure.redirectUri);
217          url.searchParams.set("error", failure.code);
218          url.searchParams.set("error_description", failure.description);
219          if (failure.state) url.searchParams.set("state", failure.state);
220          if (failure.issuer) url.searchParams.set("iss", failure.issuer);
221          return redirect(url.href);
222        }
223        if (error instanceof Error && error.name === "CimdFetchError") {
224          return text("This client could not be verified: its client metadata document could not be fetched.", 400);
225        }
226        throw error;
227      }
228    },
229  };
230}
231
232/**
233 * Whether a signed-in email is the single administrator's: `ADMIN_EMAIL`, compared without case. The email is the one
234 * Cloudflare Access verified. Fails closed: an unset or blank value admits nobody.
235 * @param {{ ADMIN_EMAIL?: string }} env
236 * @param {{ email?: unknown }} user
237 */
238export function isAdminUser(env, user) {
239  const admin = (env.ADMIN_EMAIL ?? "").trim().toLowerCase();
240  if (!admin || typeof user.email !== "string") return false;
241  return user.email.trim().toLowerCase() === admin;
242}
243
244/**
245 * The redirect URIs a dynamically registered client may name, from a comma-separated setting (DCR_REDIRECT_URIS).
246 * @param {string | undefined} configured
247 */
248export function allowedRedirects(configured) {
249  return (configured ?? "")
250    .split(",")
251    .map((uri) => uri.trim())
252    .filter(Boolean);
253}
254
255/**
256 * The tightened Dynamic Client Registration check, for the provider's clientRegistrationCallback. DCR is kept only
257 * for the clients that still need it (Grok, Gemini), so a registration is allowed only when every redirect URI it
258 * names is listed, character for character, in `configured`: a redirect URI is where an authorization code is
259 * delivered, and close to an allowed one is how codes are stolen. An empty or unset list refuses every registration.
260 * Registration grants nothing; the consent page, Access and the administrator check still decide.
261 * @param {string | undefined} configured
262 * @param {Record<string, unknown>} clientMetadata
263 * @returns {string | null} null when the registration may proceed, else why it is refused, naming the URI
264 */
265export function registrationRefusal(configured, clientMetadata) {
266  const allowed = allowedRedirects(configured);
267  if (allowed.length === 0) return "Dynamic client registration is closed on this server: no redirect URI is allowlisted.";
268  const asked = clientMetadata.redirect_uris;
269  if (!Array.isArray(asked) || asked.length === 0) return "A registration must name at least one redirect URI.";
270  for (const uri of asked) {
271    if (typeof uri !== "string" || !allowed.includes(uri)) return `The redirect URI ${JSON.stringify(uri)} is not allowlisted on this server.`;
272  }
273  return null;
274}