access.mjs

Functions

Imports

It imports access-login.mjs. No module of this repo imports it.

Source

1/**
2 * The check that a request came through Cloudflare Access: the token Access signs for each request it lets through,
3 * read from the `Cf-Access-Jwt-Assertion` header (or, on request, the `CF_Authorization` cookie) and verified against
4 * the team's published keys, with the WebCrypto verifier `./access-login` uses, so there is no JWT library.
5 *
6 * Presence of the header proves nothing, since anyone can send one. What proves a request passed Access is a signature
7 * by a key Access publishes, an `aud` naming THIS application's tag, and an `iss` equal to the team domain,
8 * https://<team>.cloudflareaccess.com with no trailing slash. RS256 is pinned. 60 seconds of clock skew either way.
9 *
10 * Only a fault in the token is a refusal. When the keys cannot be fetched, `accessKeys` throws, so an outage reads as
11 * an outage and not as every administrator being locked out silently.
12 *
13 * Not here, because each site does it its own way: who a verified token is (an email, a service token's common_name),
14 * case folding, the local development bypass, and what a refusal shows.
15 */
16
17import { verifyJwt } from "./access-login.mjs";
18
19export const ACCESS_JWT_HEADER = "cf-access-jwt-assertion";
20export const ACCESS_COOKIE = "CF_Authorization";
21
22/** How long an unknown kid waits before it may refetch the keys again, so a forged kid cannot hammer the endpoint. */
23export const REFETCH_COOLDOWN_MS = 30_000;
24
25/**
26 * The issuer Access writes, https://<team domain>, from the team domain as either site keeps it: with or without the
27 * scheme, with or without a trailing slash. Null when it is missing or not a <team>.cloudflareaccess.com host.
28 * @param {string | undefined} teamDomain
29 * @returns {string | null}
30 */
31export function accessIssuer(teamDomain) {
32  const host = (teamDomain ?? "")
33    .trim()
34    .replace(/^https:\/\//i, "")
35    .replace(/\/+$/, "");
36  // Only an Access team host: the keys fetched from it are trusted to sign who a request is.
37  if (!host || !/^[a-z0-9-]+\.cloudflareaccess\.com$/i.test(host)) return null;
38  return `https://${host.toLowerCase()}`;
39}
40
41/** @typedef {import("./access-login.d.mts").Jwk} Jwk */
42/** @typedef {import("./access-login.d.mts").KeySource} KeySource */
43
44/** @type {Map<string, { keys: Jwk[], fetchedAt: number }>} */
45const cachedKeys = new Map();
46
47/**
48 * The team's signing keys at https://<team domain>/cdn-cgi/access/certs, cached per isolate. A kid not in the cache
49 * refetches, at most once per REFETCH_COOLDOWN_MS. A failed fetch, an error status or a body with no key list THROWS.
50 * @param {string} teamDomain
51 * @returns {KeySource}
52 */
53export function accessKeys(teamDomain) {
54  const issuer = accessIssuer(teamDomain);
55  if (!issuer) throw new Error("accessKeys: the Access team domain is missing or not a host");
56  const url = `${issuer}/cdn-cgi/access/certs`;
57  return async (kid, fresh) => {
58    let entry = cachedKeys.get(url);
59    if (!entry || (fresh && Date.now() - entry.fetchedAt >= REFETCH_COOLDOWN_MS)) {
60      const response = await fetch(url, { headers: { Accept: "application/json" } });
61      if (!response.ok) throw new Error(`the Access keys at ${url} answered ${response.status}`);
62      const body = /** @type {{ keys?: unknown }} */ (await response.json().catch(() => ({})));
63      if (!Array.isArray(body.keys)) throw new Error(`the Access keys at ${url} are not a key set`);
64      entry = { keys: /** @type {Jwk[]} */ (body.keys), fetchedAt: Date.now() };
65      cachedKeys.set(url, entry);
66    }
67    return entry.keys.find((key) => key.kid === kid);
68  };
69}
70
71/**
72 * The value of one cookie, or null.
73 * @param {Request} request
74 * @param {string} name
75 */
76function cookieValue(request, name) {
77  for (const part of (request.headers.get("cookie") ?? "").split(";")) {
78    const eq = part.indexOf("=");
79    if (eq !== -1 && part.slice(0, eq).trim() === name) return part.slice(eq + 1).trim() || null;
80  }
81  return null;
82}
83
84/**
85 * The Access token a request carries: the header, else (with `cookie`) the CF_Authorization cookie, else null. The
86 * header is added only on paths an Access application covers; the cookie rides on every path of the host.
87 * @param {Request} request
88 * @param {{ cookie?: boolean }} [options]
89 * @returns {string | null}
90 */
91export function accessToken(request, { cookie = false } = {}) {
92  return request.headers.get(ACCESS_JWT_HEADER) || (cookie ? cookieValue(request, ACCESS_COOKIE) : null);
93}
94
95/**
96 * One Access application's verdict on a token: the claims, or the reason it is refused (`verifyJwt`'s reasons:
97 * malformed, algorithm, unknown-key, signature, issuer, audience, expired, not-yet-valid).
98 * @param {string} token
99 * @param {KeySource} keys
100 * @param {{ issuer: string, audience: string, now?: number }} expect `now` in epoch milliseconds
101 * @returns {Promise<import("./access-login.d.mts").JwtVerdict>}
102 */
103export function verifyAccessToken(token, keys, expect) {
104  return verifyJwt(token, keys, expect);
105}
106
107/**
108 * One Access application's verdict on a request. `not-configured` when the team domain or the audience is missing,
109 * `no-token` when the request carries none, a token reason when it fails; otherwise the token's claims, which the
110 * caller reads for `email` (a person) or `common_name` (a service token). Throws when the keys cannot be fetched.
111 * @param {Request} request
112 * @param {{ teamDomain: string | undefined, audience: string | undefined, cookie?: boolean, keys?: KeySource, now?: number }} options
113 * @returns {Promise<import("./access.d.mts").AccessVerdict>}
114 */
115export async function verifyAccessRequest(request, { teamDomain, audience, cookie = false, keys, now }) {
116  const issuer = accessIssuer(teamDomain);
117  const aud = audience?.trim();
118  if (!issuer || !aud) return { ok: false, reason: "not-configured" };
119  const token = accessToken(request, { cookie });
120  if (!token) return { ok: false, reason: "no-token" };
121  return verifyJwt(token, keys ?? accessKeys(issuer), { issuer, audience: aud, now });
122}