src/access-jwt.ts

Functions

Imports

It imports src/time.ts. Imported by src/access-login.ts.

Source

1import { createRemoteJWKSet, customFetch, decodeProtectedHeader, errors, jwtVerify } from "jose";
2import { HOUR_MS } from "./time";
3
4// Verifies the ID token Cloudflare Access for SaaS (OIDC) returns at Capsid's login
5// callback (capsid/research/design-capsid-access-login.md; decided 2026-09-27).
6//
7// Measured 2026-09-27 from the Capsid SaaS app's discovery document: the issuer is
8// https://<team>.cloudflareaccess.com/cdn-cgi/access/sso/oidc/<client id>, the keys are
9// at <issuer>/jwks, and ID tokens are RS256. The signature, algorithm, iss, aud, exp and
10// nbf are checked by jose (6.2.12, pinned), the standard the portfolio's sites share
11// (centralize D3, capsid/research/centralize-build-jobs.md; carrel's verifier is the model).
12// What jose does not decide is checked here, each with a named reason: the token names a
13// kid, it carries this sign-in's nonce, email_verified is not false, and an email is
14// present. Anything else is a refusal with a reason.
15//
16// Keys come through jose's createRemoteJWKSet, refetched when a token names an unknown kid
17// (how a rotation is picked up). cooldownDuration is 0 so that refetch is immediate, as
18// the hand-rolled verifier this replaced did, and cacheMaxAge is the hour it used. The
19// resolver is kept per JWKS URL.
20
21const KEYS_TTL_MS = HOUR_MS;
22const ALLOWED_ALGORITHMS = ["RS256"];
23const MAX_NAME = 80;
24
25export interface Jwk {
26  kid?: string;
27  kty: string;
28  n?: string;
29  e?: string;
30  alg?: string;
31}
32
33export type KeysFetcher = (url: string) => Promise<{ keys: Jwk[] }>;
34
35export interface IdTokenCheck {
36  issuer: string;
37  clientId: string;
38  jwksUrl: string;
39  nonce: string;
40}
41
42export type IdTokenVerdict = { ok: true; email: string; name?: string } | { ok: false; reason: string };
43
44type KeyResolver = ReturnType<typeof createRemoteJWKSet>;
45
46// What went wrong reading the keys, kept beside the resolver: jose reports a failed fetch
47// in its own words, and the reason Capsid shows names the fetch's own message.
48interface Keys {
49  resolve: KeyResolver;
50  lastError: { current: Error | null };
51}
52
53const resolvers = new Map<string, Keys>();
54
55export function clearIdTokenKeysCache(): void {
56  resolvers.clear();
57}
58
59function keysFor(url: string, fetchKeys: KeysFetcher | null): Keys {
60  const have = resolvers.get(url);
61  if (have) return have;
62  const lastError: { current: Error | null } = { current: null };
63  const resolve = createRemoteJWKSet(new URL(url), {
64    cooldownDuration: 0,
65    cacheMaxAge: KEYS_TTL_MS,
66    // The injected fetcher is how a test serves keys; live, jose's own fetch reads the URL.
67    ...(fetchKeys
68      ? {
69          [customFetch]: async (target: string): Promise<Response> => {
70            try {
71              const fetched = await fetchKeys(target);
72              if (!fetched || !Array.isArray(fetched.keys)) throw new Error("the Access JWKS endpoint returned no keys array");
73              return Response.json(fetched);
74            } catch (err) {
75              lastError.current = err instanceof Error ? err : new Error(String(err));
76              throw lastError.current;
77            }
78          },
79        }
80      : {}),
81  });
82  const made = { resolve, lastError };
83  resolvers.set(url, made);
84  return made;
85}
86
87const brief = (err: unknown): string => (err instanceof Error ? err.message : String(err)).slice(0, 120);
88
89export async function verifyIdToken(token: string, check: IdTokenCheck, now: Date, fetchKeys: KeysFetcher | null = null): Promise<IdTokenVerdict> {
90  // The kid is required before jose is asked: a token with no kid would otherwise match
91  // whichever single key the endpoint serves, and the endpoint's key set is not the
92  // token's to choose.
93  let header: ReturnType<typeof decodeProtectedHeader>;
94  try {
95    header = decodeProtectedHeader(token);
96  } catch {
97    return { ok: false, reason: "the ID token is not a JWT or does not decode" };
98  }
99  if (typeof header.kid !== "string" || header.kid === "") {
100    // An alg other than RS256 is the more useful thing to say when both are wrong.
101    if (header.alg !== "RS256") return { ok: false, reason: `the ID token's alg is ${String(header.alg)}, not RS256` };
102    return { ok: false, reason: "the ID token names no kid" };
103  }
104
105  const keys = keysFor(check.jwksUrl, fetchKeys);
106  keys.lastError.current = null;
107  let payload: Awaited<ReturnType<typeof jwtVerify>>["payload"];
108  try {
109    ({ payload } = await jwtVerify(token, keys.resolve, {
110      algorithms: ALLOWED_ALGORITHMS,
111      issuer: check.issuer,
112      audience: check.clientId,
113      currentDate: now,
114      requiredClaims: ["exp"],
115    }));
116  } catch (err) {
117    if (keys.lastError.current) return { ok: false, reason: `the Access keys could not be read: ${brief(keys.lastError.current)}` };
118    if (err instanceof errors.JOSEAlgNotAllowed) return { ok: false, reason: `the ID token's alg is ${String(header.alg)}, not RS256` };
119    if (err instanceof errors.JWSSignatureVerificationFailed) return { ok: false, reason: "the ID token's signature does not verify" };
120    if (err instanceof errors.JWKSNoMatchingKey) return { ok: false, reason: `no Access key has kid ${header.kid}` };
121    if (err instanceof errors.JWTExpired) return { ok: false, reason: "the ID token has expired or carries no exp" };
122    if (err instanceof errors.JWTClaimValidationFailed) {
123      switch (err.claim) {
124        case "iss":
125          return { ok: false, reason: "iss is not this application's issuer" };
126        case "aud":
127          return { ok: false, reason: "aud does not hold this application's client id" };
128        case "exp":
129          return { ok: false, reason: "the ID token has expired or carries no exp" };
130        case "nbf":
131          return { ok: false, reason: "the ID token is not valid yet (nbf)" };
132        default:
133          return { ok: false, reason: `the ID token's ${String(err.claim)} claim is not acceptable` };
134      }
135    }
136    if (err instanceof errors.JWSInvalid || err instanceof errors.JWTInvalid) return { ok: false, reason: "the ID token is not a JWT or does not decode" };
137    return { ok: false, reason: `the signature could not be checked: ${brief(err)}` };
138  }
139
140  if (payload.nonce !== check.nonce) return { ok: false, reason: "the ID token's nonce is not this sign-in's" };
141  if (payload.email_verified === false) return { ok: false, reason: "the ID token says the email is not verified" };
142  const email = typeof payload.email === "string" ? payload.email.trim() : "";
143  if (!email) return { ok: false, reason: "the ID token carries no email" };
144  // name is the profile scope's standard claim, present when the identity provider has one.
145  const name = typeof payload.name === "string" ? payload.name.trim().slice(0, MAX_NAME) : "";
146  return name ? { ok: true, email, name } : { ok: true, email };
147}