access.ts

apps/worker/src/access.ts

1. import { errorMessage } from '@meridian/shared'
2. /**
3. * Verifying who Cloudflare Access says is asking.
4. *
5. * The JWT and not the email header. Access sets `Cf-Access-Authenticated-User-Email`, and it is tempting to read
6. * it and move on. That header is only trustworthy if every request reaches this
7. * Worker through Access, and the Worker is published on a `workers.dev`
8. * hostname, which is publicly routable. Access sits in front of it by
9. * configuration, not by physics. A misconfigured application, a preview URL left
10. * uncovered, or a direct request would all deliver a header this Worker cannot
11. * distinguish from the real thing, and the header is trivially settable by
12. * whoever sends the request.
13. *
14. * The executive briefing has exactly one reader, enforced rather than
15. * preferred, and trusting a spoofable header would make it a preference. So
16. * the signed assertion is verified instead: `Cf-Access-Jwt-Assertion` is an RS256 JWT signed
17. * by the Access team's keys, and only Access can mint one.
18. *
19. * Fail closed, always. Every failure path here returns null and the caller must
20. * refuse the request. That includes the case where Access has not been configured
21. * yet: a freshly deployed Worker with no application in front of it serves
22. * nothing at all rather than serving everything to everyone. That is the correct
23. * order: the board carries client names and order numbers.
24. */
26. export interface AccessIdentity {
27. email: string
28. /** Subject claim, for logging a denial without logging an address. */
29. sub: string
30. }
32. interface Jwk {
33. kid: string
34. kty: string
35. n: string
36. e: string
37. alg?: string
38. }
40. const base64UrlToBytes = (s: string): Uint8Array => {
41. const pad = s.length % 4 === 0 ? '' : '='.repeat(4 - (s.length % 4))
42. const bin = atob(s.replace(/-/g, '+').replace(/_/g, '/') + pad)
43. const out = new Uint8Array(bin.length)
44. for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
45. return out
46. }
48. const decodeJson = (s: string): Record<string, unknown> =>
49. JSON.parse(new TextDecoder().decode(base64UrlToBytes(s))) as Record<string, unknown>
51. /**
52. * Access's signing keys, cached for a few minutes.
53. *
54. * Cached because a key fetch on every request would put a network round trip on
55. * the read path; kept short because key rotation must take effect without a
56. * deploy. A stale key set fails closed; the signature simply will not verify.
57. */
58. let keyCache: { at: number; keys: Map<string, CryptoKey> } | null = null
59. const KEY_TTL_MS = 5 * 60_000
61. /**
62. * Drop the cached signing keys. For tests only. Production rotation is handled
63. * by the short TTL above, and nothing in the request path should need this.
64. */
65. export function __resetKeyCache(): void {
66. keyCache = null
67. }
69. async function signingKeys(teamDomain: string): Promise<Map<string, CryptoKey>> {
70. const now = Date.now()
71. if (keyCache && now - keyCache.at < KEY_TTL_MS) return keyCache.keys
73. const res = await fetch(`https://${teamDomain}/cdn-cgi/access/certs`)
74. if (!res.ok) throw new Error(`Access certs returned ${res.status}`)
75. const body = (await res.json()) as { keys?: Jwk[] }
77. const keys = new Map<string, CryptoKey>()
78. for (const jwk of body.keys ?? []) {
79. if (jwk.kty !== 'RSA') continue
80. keys.set(
81. jwk.kid,
82. await crypto.subtle.importKey(
83. 'jwk',
84. { kty: jwk.kty, n: jwk.n, e: jwk.e, alg: 'RS256', ext: true },
85. { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },
86. false,
87. ['verify'],
88. ),
89. )
90. }
91. keyCache = { at: now, keys }
92. return keys
93. }
95. /**
96. * The verified identity, or null.
97. *
98. * Null is the only failure signal and it never carries a reason to the caller on
99. * purpose: a request that fails verification gets one answer, so nothing about
100. * why can be probed from outside. The reason is logged, not returned.
101. */
102. export async function identify(
103. req: Request,
104. teamDomain: string | undefined,
105. audience: string | undefined,
106. log: (why: string) => void = () => {},
107. ): Promise<AccessIdentity | null> {
108. if (!teamDomain || !audience) {
109. log('ACCESS_TEAM_DOMAIN or ACCESS_AUD is not set on the Worker')
110. return null
111. }
112. const token = req.headers.get('Cf-Access-Jwt-Assertion')
113. if (!token) {
114. log('no Cf-Access-Jwt-Assertion header; request did not come through Access')
115. return null
116. }
118. const parts = token.split('.')
119. if (parts.length !== 3) {
120. log('assertion is not a three-part JWT')
121. return null
122. }
123. const [rawHeader, rawPayload, rawSig] = parts as [string, string, string]
125. let header: Record<string, unknown>
126. let claims: Record<string, unknown>
127. try {
128. header = decodeJson(rawHeader)
129. claims = decodeJson(rawPayload)
130. } catch {
131. log('assertion header or payload is not valid base64url JSON')
132. return null
133. }
135. // Algorithm is pinned. Accepting whatever `alg` claims is the classic JWT
136. // failure: "none" verifies trivially, and an HMAC alg would let the public key
137. // be used as a shared secret.
138. if (header.alg !== 'RS256') {
139. log(`assertion alg is ${String(header.alg)}, not RS256`)
140. return null
141. }
143. // A key fetch that fails is a denial, not an error. Letting this throw would
144. // surface as a 500: still closed, but it reads as the board being broken and
145. // invites someone to "fix" it by loosening the check. Refusing cleanly says
146. // what it is: we cannot confirm who you are, so we will not answer.
147. let keys: Map<string, CryptoKey>
148. try {
149. keys = await signingKeys(teamDomain)
150. } catch (err) {
151. log(`could not fetch Access signing keys: ${errorMessage(err)}`)
152. return null
153. }
154. const key = keys.get(String(header.kid))
155. if (!key) {
156. log('assertion kid matches none of the current Access signing keys')
157. return null
158. }
160. const ok = await crypto.subtle.verify(
161. { name: 'RSASSA-PKCS1-v1_5' },
162. key,
163. base64UrlToBytes(rawSig),
164. new TextEncoder().encode(`${rawHeader}.${rawPayload}`),
165. )
166. if (!ok) {
167. log('assertion signature does not verify')
168. return null
169. }
171. // Audience. Without this, a token minted by the same Access team for a
172. // different application would be accepted here. Access teams commonly protect
173. // several apps, and a token is only meant for the one it was issued for.
174. const aud = claims.aud
175. const audList = Array.isArray(aud) ? aud.map(String) : [String(aud)]
176. if (!audList.includes(audience)) {
177. log('assertion audience is for a different Access application')
178. return null
179. }
181. const now = Math.floor(Date.now() / 1000)
182. if (typeof claims.exp !== 'number' || claims.exp < now) {
183. log('assertion is expired')
184. return null
185. }
186. if (typeof claims.nbf === 'number' && claims.nbf > now) {
187. log('assertion is not valid yet')
188. return null
189. }
190. // Exact, not `includes`. A substring test is satisfied by any issuer merely
191. // containing the team domain: `https://attacker.example/your-team.cloudflareaccess.com`
192. // would pass. The signature still has to verify against keys fetched from
193. // `teamDomain` itself, so a forged token cannot be signed either way. But a check that only holds because a different check is
194. // doing the work is not a check, and this one is meant to be defence in depth.
195. if (typeof claims.iss === 'string' && claims.iss !== `https://${teamDomain}`) {
196. log('assertion issuer is not exactly this Access team')
197. return null
198. }
200. const email = typeof claims.email === 'string' ? claims.email.trim().toLowerCase() : ''
201. if (!email) {
202. log('assertion carries no email claim')
203. return null
204. }
205. return { email, sub: typeof claims.sub === 'string' ? claims.sub : '' }
206. }