src/access-login.ts

Functions

Imports

It imports src/access-jwt.ts, src/auth.ts, src/encoding.ts, src/env.ts. Imported by src/portal-auth.ts, src/routes.ts.

Source

1import { verifyIdToken, type KeysFetcher } from "./access-jwt";
2import { getCookie, isAdminEmail, sha256Hex } from "./auth";
3import { safeEqual } from "@dustinedwards/site-runtime/compare";
4import { b64urlFromBytes, bytesToHex } from "./encoding";
5import type { Env } from "./env";
6// The sign-in round trip with Cloudflare Access for SaaS (OIDC) as the upstream
7// identity (capsid/research/design-capsid-access-login.md, decided 2026-09-27), shared
8// by the MCP authorization flow (src/routes.ts) and Capsid Portal's login
9// (src/portal-auth.ts). What differs between them is passed in as a LoginFlow; what
10// each stores and does with the admitted email stays in the caller. A state token is
11// stored in OAUTH_KV for ten minutes, bound to the browser by a cookie holding a random
12// value of its own whose digest the stored state keeps, and used once. PKCE and an OIDC nonce are kept in the stored state, and the
13// ID token is verified in src/access-jwt.ts. The person is the email in the token,
14// admitted only when it equals ADMIN_EMAIL or a CO_OWNER_EMAILS entry exactly.
15//
16// Every endpoint derives from the team domain and the client id, as the SaaS app's
17// discovery document states them (measured 2026-09-27).
18
19// How long a started login stays usable: the KV state entry and the state cookie.
20export const STATE_TTL_SECONDS = 600;
21
22export interface LoginFlow {
23  // The path Access redirects back to, on this Worker's origin.
24  callbackPath: string;
25  stateCookie: string;
26  // The state cookie's Path attribute.
27  cookiePath: string;
28  kvPrefix: string;
29  // Appended to each state refusal, telling the user where to start again.
30  restartHint: string;
31}
32
33export function clearStateCookie(flow: LoginFlow): string {
34  return `${flow.stateCookie}=; HttpOnly; Secure; SameSite=Lax; Path=${flow.cookiePath}; Max-Age=0`;
35}
36
37interface AccessSaas {
38  clientId: string;
39  clientSecret: string;
40  issuer: string;
41}
42
43// The SaaS app's settings, or null while any is unset: the login is then closed.
44function accessSaas(env: Env): AccessSaas | null {
45  const team = env.ACCESS_TEAM_DOMAIN?.trim().replace(/\/+$/, "");
46  const clientId = env.ACCESS_SAAS_CLIENT_ID?.trim();
47  const clientSecret = env.ACCESS_SAAS_CLIENT_SECRET?.trim();
48  if (!team || !clientId || !clientSecret) return null;
49  return { clientId, clientSecret, issuer: `${team}/cdn-cgi/access/sso/oidc/${encodeURIComponent(clientId)}` };
50}
51
52const TOKEN_EXCHANGE_TIMEOUT_MS = 15_000;
53const UNCONFIGURED = "the sign-in is not configured (ACCESS_TEAM_DOMAIN, ACCESS_SAAS_CLIENT_ID, ACCESS_SAAS_CLIENT_SECRET), so it is closed";
54
55function refusal(message: string, status: number): Response {
56  return new Response(message, { status, headers: { "Content-Type": "text/plain;charset=utf-8" } });
57}
58
59async function s256(verifier: string): Promise<string> {
60  return b64urlFromBytes(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))));
61}
62
63// What the KV state holds: the caller's own value, this sign-in's PKCE verifier and
64// nonce, which never leave the server, and the digest of the browser binding the state
65// cookie carries.
66interface StoredSignIn {
67  stored: string;
68  verifier: string;
69  nonce: string;
70  binding: string;
71}
72
73// Stores `stored` against a fresh state token and redirects to Access.
74export async function startAccessLogin(
75  request: Request,
76  env: Env,
77  flow: LoginFlow,
78  stored: string,
79  extraCookies: string[] = []
80): Promise<Response> {
81  const saas = accessSaas(env);
82  if (!saas) return refusal(UNCONFIGURED, 503);
83  const stateToken = crypto.randomUUID();
84  // The browser binding is random and unrelated to the state token. A cookie derived
85  // from the token could be computed by anyone holding the callback URL, which carries
86  // the token, and would bind nothing (Grok audit 2026-10, S6).
87  const binding = bytesToHex(crypto.getRandomValues(new Uint8Array(32)));
88  const signIn: StoredSignIn = {
89    stored,
90    verifier: b64urlFromBytes(crypto.getRandomValues(new Uint8Array(32))),
91    nonce: crypto.randomUUID(),
92    binding: await sha256Hex(binding),
93  };
94  await env.OAUTH_KV.put(`${flow.kvPrefix}${stateToken}`, JSON.stringify(signIn), { expirationTtl: STATE_TTL_SECONDS });
95  const target = new URL(`${saas.issuer}/authorization`);
96  target.searchParams.set("client_id", saas.clientId);
97  target.searchParams.set("redirect_uri", `${new URL(request.url).origin}${flow.callbackPath}`);
98  target.searchParams.set("response_type", "code");
99  target.searchParams.set("scope", "openid email profile");
100  target.searchParams.set("state", stateToken);
101  target.searchParams.set("nonce", signIn.nonce);
102  target.searchParams.set("code_challenge", await s256(signIn.verifier));
103  target.searchParams.set("code_challenge_method", "S256");
104  const headers = new Headers({ Location: target.href });
105  // The state cookie carries the binding, which neither the URL nor the stored state holds.
106  headers.append("Set-Cookie", `${flow.stateCookie}=${binding}; HttpOnly; Secure; SameSite=Lax; Path=${flow.cookiePath}; Max-Age=${STATE_TTL_SECONDS}`);
107  for (const cookie of extraCookies) headers.append("Set-Cookie", cookie);
108  return new Response(null, { status: 302, headers });
109}
110
111export type AccessLoginResult<T> = { ok: true; email: string; name?: string; state: T } | { ok: false; response: Response };
112
113// Verifies the callback's state against the cookie and KV, exchanges the code with
114// PKCE, verifies the ID token and runs the admin check. `parse` turns the caller's
115// stored value back into what it stored; if it throws, the state is deleted and the
116// callback refused before anything reaches Access.
117export async function completeAccessLogin<T>(
118  request: Request,
119  env: Env,
120  flow: LoginFlow,
121  parse: (stored: string) => T,
122  now: Date = new Date(),
123  fetchKeys?: KeysFetcher
124): Promise<AccessLoginResult<T>> {
125  const fail = (message: string, status: number): AccessLoginResult<T> => ({ ok: false, response: refusal(message, status) });
126  const saas = accessSaas(env);
127  if (!saas) return fail(UNCONFIGURED, 503);
128  const url = new URL(request.url);
129  // Access reports a refused sign-in as error=... on the callback.
130  const upstreamError = url.searchParams.get("error");
131  if (upstreamError) return fail(`the sign-in was refused by Access: ${upstreamError.slice(0, 80)}. ${flow.restartHint}`, 403);
132  const code = url.searchParams.get("code");
133  const stateToken = url.searchParams.get("state");
134  if (!code || !stateToken) return fail("missing code or state", 400);
135
136  const notThisBrowser = `state validation failed: this browser did not start the flow. ${flow.restartHint}`;
137  const stateCookie = getCookie(request, flow.stateCookie);
138  if (!stateCookie) return fail(notThisBrowser, 403);
139  const stateKey = `${flow.kvPrefix}${stateToken}`;
140  const raw = await env.OAUTH_KV.get(stateKey);
141  if (!raw) return fail(`state expired or already used. ${flow.restartHint}`, 403);
142  let signIn: StoredSignIn;
143  try {
144    signIn = JSON.parse(raw) as StoredSignIn;
145    if (typeof signIn.verifier !== "string" || typeof signIn.nonce !== "string" || typeof signIn.stored !== "string" || typeof signIn.binding !== "string") {
146      throw new Error("shape");
147    }
148  } catch {
149    await env.OAUTH_KV.delete(stateKey);
150    return fail(`stored authorization state is unreadable. ${flow.restartHint}`, 403);
151  }
152  // A cookie that does not match leaves the state in place, so a stranger holding the
153  // callback URL cannot spend the browser's sign-in.
154  if (!await safeEqual(await sha256Hex(stateCookie), signIn.binding)) return fail(notThisBrowser, 403);
155  let state: T;
156  try {
157    state = parse(signIn.stored);
158  } catch {
159    await env.OAUTH_KV.delete(stateKey);
160    return fail(`stored authorization state is unreadable. ${flow.restartHint}`, 403);
161  }
162
163  // Bounded, so a hung token endpoint does not hold the sign-in (Grok audit 2026-10-21, CA-10).
164  const tokenResp = await fetch(`${saas.issuer}/token`, {
165    method: "POST",
166    signal: AbortSignal.timeout(TOKEN_EXCHANGE_TIMEOUT_MS),
167    headers: { Accept: "application/json", "Content-Type": "application/x-www-form-urlencoded" },
168    body: new URLSearchParams({
169      grant_type: "authorization_code",
170      code,
171      redirect_uri: `${url.origin}${flow.callbackPath}`,
172      client_id: saas.clientId,
173      client_secret: saas.clientSecret,
174      code_verifier: signIn.verifier,
175    }),
176  }).catch(() => null);
177  if (!tokenResp) return fail("the Access token exchange did not answer in time", 502);
178  if (!tokenResp.ok) return fail(`the Access token exchange failed (${tokenResp.status})`, 502);
179  const tokens = (await tokenResp.json().catch(() => ({}))) as { id_token?: unknown };
180  if (typeof tokens.id_token !== "string") return fail("the Access token exchange returned no ID token", 502);
181  // The state is consumed after the exchange, so a transient Access error does not burn
182  // it. Replay is bounded by Access, which honours a code once.
183  await env.OAUTH_KV.delete(stateKey);
184
185  const verdict = await verifyIdToken(
186    tokens.id_token,
187    { issuer: saas.issuer, clientId: saas.clientId, jwksUrl: `${saas.issuer}/jwks`, nonce: signIn.nonce },
188    now,
189    fetchKeys
190  );
191  if (!verdict.ok) return fail(`the sign-in could not be verified: ${verdict.reason}. ${flow.restartHint}`, 403);
192  if (!await isAdminEmail(env, verdict.email)) {
193    return fail("access denied: this email is not an administrator of capsid (ADMIN_EMAIL or CO_OWNER_EMAILS)", 403);
194  }
195  return verdict.name ? { ok: true, email: verdict.email, name: verdict.name, state } : { ok: true, email: verdict.email, state };
196}