access-login.mjs

Functions

Imports

It imports no other module of this repo. Imported by access.mjs, mcp-login.mjs.

Source

1/**
2 * The upstream sign-in with Cloudflare Access for SaaS (OIDC), the one login every MCP server in the family uses.
3 *
4 * The state of a sign-in in flight (the client's request, the PKCE verifier, the nonce) is not kept here. An MCP
5 * server keeps it with @cloudflare/workers-oauth-provider's beginUpstream and finishUpstream, which hold it server-side,
6 * bind it to the browser by a cookie and spend it once; `newSignIn` makes what goes in it.
7 *
8 * - Every endpoint derives from the team domain and the SaaS app's client id, as the Access dashboard shows them.
9 *   A missing setting keeps the door shut.
10 * - PKCE (S256) and an OIDC nonce on every sign-in.
11 * - The ID token is verified with WebCrypto against the SaaS app's published keys, so there is no JWT library: RS256
12 *   only, the issuer, the audience, expiry and not-before with 60 seconds of skew (Access and Workers clocks are
13 *   not the same clock), the nonce, `email_verified` not false, and an email present. A kid not in the cached keys
14 *   refetches once, so a key rotation does not lock the door.
15 *
16 * Who is admitted is the caller's: the email comes back, and the caller compares it with its administrator.
17 */
18
19const SKEW_SECONDS = 60;
20const MAX_NAME = 80;
21
22/**
23 * The SaaS app's endpoints, or null while any setting is missing. ACCESS_TEAM_DOMAIN is the team domain as the
24 * dashboard shows it, https://<team>.cloudflareaccess.com (the scheme and a trailing slash are optional); null for any
25 * other host.
26 * @param {{ ACCESS_TEAM_DOMAIN?: string, ACCESS_SAAS_CLIENT_ID?: string, ACCESS_SAAS_CLIENT_SECRET?: string }} env
27 */
28export function accessSaas(env) {
29  // The issuer's host is trusted with the client secret and to sign who signs in, so it must be an Access team host.
30  const host = env.ACCESS_TEAM_DOMAIN?.trim().replace(/^https:\/\//i, "").replace(/\/+$/, "");
31  const team = host && /^[a-z0-9-]+\.cloudflareaccess\.com$/i.test(host) ? `https://${host.toLowerCase()}` : null;
32  const clientId = env.ACCESS_SAAS_CLIENT_ID?.trim();
33  const clientSecret = env.ACCESS_SAAS_CLIENT_SECRET?.trim();
34  if (!team || !clientId || !clientSecret) return null;
35  const issuer = `${team}/cdn-cgi/access/sso/oidc/${encodeURIComponent(clientId)}`;
36  return { clientId, clientSecret, issuer, authorizationUrl: `${issuer}/authorization`, tokenUrl: `${issuer}/token`, jwksUrl: `${issuer}/jwks` };
37}
38
39/** @param {Uint8Array} bytes */
40function base64url(bytes) {
41  let raw = "";
42  for (const b of bytes) raw += String.fromCharCode(b);
43  return btoa(raw).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
44}
45
46/** @param {string} value */
47function fromBase64url(value) {
48  const b64 = value.replace(/-/g, "+").replace(/_/g, "/");
49  const raw = atob(b64 + "=".repeat((4 - (b64.length % 4)) % 4));
50  return Uint8Array.from(raw, (c) => c.charCodeAt(0));
51}
52
53/** A fresh PKCE verifier (43 characters, 256 random bits) and OIDC nonce for one sign-in. Keep both server-side. */
54export function newSignIn() {
55  return { verifier: base64url(crypto.getRandomValues(new Uint8Array(32))), nonce: crypto.randomUUID() };
56}
57
58/**
59 * Where the browser goes to sign in with Access.
60 * @param {import("./access-login.d.mts").AccessSaas} saas
61 * @param {{ redirectUri: string, state: string, verifier: string, nonce: string }} input
62 */
63export async function authorizationUrl(saas, input) {
64  const challenge = base64url(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input.verifier))));
65  const url = new URL(saas.authorizationUrl);
66  url.searchParams.set("client_id", saas.clientId);
67  url.searchParams.set("redirect_uri", input.redirectUri);
68  url.searchParams.set("response_type", "code");
69  url.searchParams.set("scope", "openid email profile");
70  url.searchParams.set("state", input.state);
71  url.searchParams.set("nonce", input.nonce);
72  url.searchParams.set("code_challenge", challenge);
73  url.searchParams.set("code_challenge_method", "S256");
74  return url.href;
75}
76
77/** @typedef {JsonWebKey & { kid?: string }} Jwk */
78/** @typedef {(kid: string, fresh: boolean) => Promise<Jwk | undefined>} KeySource */
79
80/** @type {Map<string, Jwk[]>} */
81const cachedKeys = new Map();
82
83/** The keys at a JWKS URL, cached per isolate; `fresh` refetches. @param {string} jwksUrl @returns {KeySource} */
84export function remoteKeys(jwksUrl) {
85  return async (kid, fresh) => {
86    let keys = fresh ? undefined : cachedKeys.get(jwksUrl);
87    if (!keys) {
88      const response = await fetch(jwksUrl, { headers: { Accept: "application/json" } });
89      if (!response.ok) return undefined;
90      const body = /** @type {{ keys?: Jwk[] }} */ (await response.json().catch(() => ({})));
91      keys = Array.isArray(body.keys) ? body.keys : [];
92      cachedKeys.set(jwksUrl, keys);
93    }
94    return keys.find((key) => key.kid === kid);
95  };
96}
97
98/**
99 * The family's one JWT check, with the reason for a refusal: RS256 only (the algorithm is pinned here, never taken
100 * from the token, so `alg: none` and HMAC-with-the-public-key fail), signed by one of `keys`, issued by `issuer`
101 * exactly, for `audience` (a string or one entry of an array), with an `exp`, and in date with 60 seconds of skew. A
102 * kid not in the cached set refetches once. Both this module's ID token and `./access`'s request token use it.
103 *
104 * Only a fault in the token is a refusal. A key source that throws (`./access` throws when the keys cannot be fetched)
105 * is not caught: an outage reads as an outage.
106 * @param {string} token
107 * @param {KeySource} keys
108 * @param {{ issuer: string, audience: string, now?: number }} expect `now` in epoch milliseconds, for a test's clock
109 * @returns {Promise<import("./access-login.d.mts").JwtVerdict>}
110 */
111export async function verifyJwt(token, keys, expect) {
112  const parts = typeof token === "string" ? token.split(".") : [];
113  if (parts.length !== 3) return { ok: false, reason: "malformed" };
114  /** @type {{ alg?: unknown, kid?: unknown }} */
115  let header;
116  /** @type {unknown} */
117  let parsed;
118  try {
119    header = JSON.parse(new TextDecoder().decode(fromBase64url(parts[0])));
120    parsed = JSON.parse(new TextDecoder().decode(fromBase64url(parts[1])));
121  } catch {
122    return { ok: false, reason: "malformed" };
123  }
124  if (typeof header !== "object" || header === null) return { ok: false, reason: "malformed" };
125  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return { ok: false, reason: "malformed" };
126  const payload = /** @type {Record<string, unknown>} */ (parsed);
127  if (header.alg !== "RS256") return { ok: false, reason: "algorithm" };
128  if (typeof header.kid !== "string") return { ok: false, reason: "unknown-key" };
129  const jwk = (await keys(header.kid, false)) ?? (await keys(header.kid, true));
130  if (!jwk || jwk.kty !== "RSA") return { ok: false, reason: "unknown-key" };
131  let valid = false;
132  try {
133    const key = await crypto.subtle.importKey("jwk", { kty: jwk.kty, n: jwk.n, e: jwk.e }, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["verify"]);
134    valid = await crypto.subtle.verify("RSASSA-PKCS1-v1_5", key, fromBase64url(parts[2]), new TextEncoder().encode(`${parts[0]}.${parts[1]}`));
135  } catch {
136    return { ok: false, reason: "signature" };
137  }
138  if (!valid) return { ok: false, reason: "signature" };
139  const now = Math.floor((expect.now ?? Date.now()) / 1000);
140  if (payload.iss !== expect.issuer) return { ok: false, reason: "issuer" };
141  const aud = payload.aud;
142  if (!(aud === expect.audience || (Array.isArray(aud) && aud.includes(expect.audience)))) return { ok: false, reason: "audience" };
143  if (typeof payload.exp !== "number" || payload.exp + SKEW_SECONDS < now) return { ok: false, reason: "expired" };
144  if (payload.nbf !== undefined && (typeof payload.nbf !== "number" || payload.nbf - SKEW_SECONDS > now)) return { ok: false, reason: "not-yet-valid" };
145  return { ok: true, claims: payload };
146}
147
148/**
149 * The payload of an RS256 JWT signed by one of `keys`, issued by `issuer` for `audience` and in date, or null
150 * (`verifyJwt` without the reason).
151 * @param {string} token
152 * @param {KeySource} keys
153 * @param {{ issuer: string, audience: string, now?: number }} expect
154 * @returns {Promise<Record<string, unknown> | null>}
155 */
156export async function verifyIdToken(token, keys, expect) {
157  const verdict = await verifyJwt(token, keys, expect);
158  return verdict.ok ? verdict.claims : null;
159}
160
161/**
162 * Exchanges Access's code for tokens and verifies the ID token: signed by the SaaS app's keys, issued by it, for this
163 * client, carrying this sign-in's nonce, and naming an email that is not marked unverified. Anything else is a
164 * refusal with a reason a log can carry; no token or secret is in it.
165 * @param {import("./access-login.d.mts").AccessSaas} saas
166 * @param {{ code: string, redirectUri: string, verifier: string, nonce: string }} input
167 * @param {KeySource} [keys]
168 * @returns {Promise<import("./access-login.d.mts").SignedIn>}
169 */
170export async function finishSignIn(saas, input, keys = remoteKeys(saas.jwksUrl)) {
171  const response = await fetch(saas.tokenUrl, {
172    method: "POST",
173    headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
174    body: new URLSearchParams({
175      grant_type: "authorization_code",
176      code: input.code,
177      redirect_uri: input.redirectUri,
178      client_id: saas.clientId,
179      client_secret: saas.clientSecret,
180      code_verifier: input.verifier,
181    }),
182  });
183  if (!response.ok) return { ok: false, reason: `token-exchange-${response.status}` };
184  const tokens = /** @type {{ id_token?: unknown }} */ (await response.json().catch(() => ({})));
185  if (typeof tokens.id_token !== "string") return { ok: false, reason: "no-id-token" };
186
187  const payload = await verifyIdToken(tokens.id_token, keys, { issuer: saas.issuer, audience: saas.clientId });
188  if (!payload) return { ok: false, reason: "invalid-id-token" };
189  if (payload.nonce !== input.nonce) return { ok: false, reason: "nonce-mismatch" };
190  if (payload.email_verified === false) return { ok: false, reason: "email-not-verified" };
191  const email = typeof payload.email === "string" ? payload.email.trim() : "";
192  if (!email) return { ok: false, reason: "no-email" };
193  const name = typeof payload.name === "string" ? payload.name.trim().slice(0, MAX_NAME) : "";
194  return name ? { ok: true, email, name } : { ok: true, email };
195}