feat: add validateAccessJwt to cloudflare:workers

[elithrar]

Adds a validateAccessJwt() function to the cloudflare:workers module that validates Cloudflare Access JWTs against team-specific JWKs, providing a built-in alternative for users to validate Access JWTs directly vs. glueing it all together themselves.

• Throws AccessJwtError with specific error codes (ERR_JWT_MISSING, ERR_JWT_EXPIRED, etc.) on validation failure - defaults to throwing exceptions that you must catch vs. some isValidJWT() type function that can be mishandled
• No external dependencies - uses WebCrypto APIs
• Retry logic for JWKS fetch (3 attempts, 5s backoff on 5xx errors)
• Isolate-level JWKS caching (1 hour TTL, with cache invalidation on key rotation)
• Team domain normalization (accepts both "myteam" and "myteam.cloudflareaccess.com")
• 60s clock skew tolerance for expiration

Usage

import { validateAccessJwt, AccessJwtError } from 'cloudflare:workers';

export default {
  async fetch(request, env) {
    try {
      // env.TEAM_DOMAIN is their CF1 Team to fetch the JWKSet from
      // env.AUDIENCE is the ID from their Access app (per the Access docs)
      const payload = await validateAccessJwt(request, env.TEAM_DOMAIN, env.AUDIENCE);
      return new Response(`Hello ${payload.email}!`);
    } catch (err) {
      if (err instanceof AccessJwtError) {
        return new Response(`Auth failed: ${err.code}`, { status: 403 });
      }
      throw err;
    }
  }
};

Error Codes

These will be added to the public docs under https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/validating-json/ + new Workers /examples as well

Code	Description
ERR_JWT_MISSING	No cf-access-jwt-assertion header
ERR_JWT_MALFORMED	Invalid JWT structure or unsupported algorithm
ERR_JWT_INVALID_SIGNATURE	Signature verification failed
ERR_JWT_EXPIRED	Token exp claim is in the past
ERR_JWT_NOT_YET_VALID	Token nbf claim is in the future
ERR_JWT_AUDIENCE_MISMATCH	Token aud doesn't match expected audience
ERR_JWT_ISSUER_MISMATCH	Token iss doesn't match team domain
ERR_JWKS_FETCH_FAILED	Failed to fetch JWKS after retries
ERR_JWKS_NO_MATCHING_KEY	No key with matching kid found
ERR_INVALID_TEAM_DOMAIN	Empty team domain provided
ERR_INVALID_AUDIENCE	Empty audience provided

Test Plan

• 20 test cases covering all error codes and edge cases
• Run: just test '//src/cloudflare/internal/test/access-jwt:access-jwt-test@'

[github-actions]

The generated output of @cloudflare/workers-types has been changed by this PR. If this is intentional, run just generate-types to update the snapshot. Alternatively, you can download the full generated types:

Full Type Diff

diff -r types/generated-snapshot/latest/index.d.ts bazel-bin/types/definitions/latest/index.d.ts
11660a11661,11701
>   // Access JWT validation
>   export type AccessJwtErrorCode =
>     | "ERR_JWT_MISSING"
>     | "ERR_JWT_MALFORMED"
>     | "ERR_JWT_INVALID_SIGNATURE"
>     | "ERR_JWT_EXPIRED"
>     | "ERR_JWT_NOT_YET_VALID"
>     | "ERR_JWT_AUDIENCE_MISMATCH"
>     | "ERR_JWT_ISSUER_MISMATCH"
>     | "ERR_JWKS_FETCH_FAILED"
>     | "ERR_JWKS_NO_MATCHING_KEY"
>     | "ERR_INVALID_TEAM_DOMAIN"
>     | "ERR_INVALID_AUDIENCE";
>   export class AccessJwtError extends Error {
>     readonly code: AccessJwtErrorCode;
>     constructor(code: AccessJwtErrorCode, message: string);
>   }
>   export interface AccessJwtPayload {
>     aud: string | string[];
>     email?: string;
>     exp: number;
>     iat: number;
>     nbf?: number;
>     iss: string;
>     sub: string;
>     [key: string]: unknown;
>   }
>   /**
>    * Validates a Cloudflare Access JWT from an incoming request.
>    *
>    * @param req - The incoming Request containing the cf-access-jwt-assertion header
>    * @param teamDomain - The Cloudflare One team domain (e.g., "mycompany" or "mycompany.cloudflareaccess.com")
>    * @param audience - The Application Audience (AUD) tag
>    * @throws {AccessJwtError} If validation fails for any reason
>    * @returns The decoded JWT payload on success
>    */
>   export function validateAccessJwt(
>     req: Request,
>     teamDomain: string,
>     audience: string,
>   ): Promise<AccessJwtPayload>;
diff -r types/generated-snapshot/latest/index.ts bazel-bin/types/definitions/latest/index.ts
11628a11629,11669
>   // Access JWT validation
>   export type AccessJwtErrorCode =
>     | "ERR_JWT_MISSING"
>     | "ERR_JWT_MALFORMED"
>     | "ERR_JWT_INVALID_SIGNATURE"
>     | "ERR_JWT_EXPIRED"
>     | "ERR_JWT_NOT_YET_VALID"
>     | "ERR_JWT_AUDIENCE_MISMATCH"
>     | "ERR_JWT_ISSUER_MISMATCH"
>     | "ERR_JWKS_FETCH_FAILED"
>     | "ERR_JWKS_NO_MATCHING_KEY"
>     | "ERR_INVALID_TEAM_DOMAIN"
>     | "ERR_INVALID_AUDIENCE";
>   export class AccessJwtError extends Error {
>     readonly code: AccessJwtErrorCode;
>     constructor(code: AccessJwtErrorCode, message: string);
>   }
>   export interface AccessJwtPayload {
>     aud: string | string[];
>     email?: string;
>     exp: number;
>     iat: number;
>     nbf?: number;
>     iss: string;
>     sub: string;
>     [key: string]: unknown;
>   }
>   /**
>    * Validates a Cloudflare Access JWT from an incoming request.
>    *
>    * @param req - The incoming Request containing the cf-access-jwt-assertion header
>    * @param teamDomain - The Cloudflare One team domain (e.g., "mycompany" or "mycompany.cloudflareaccess.com")
>    * @param audience - The Application Audience (AUD) tag
>    * @throws {AccessJwtError} If validation fails for any reason
>    * @returns The decoded JWT payload on success
>    */
>   export function validateAccessJwt(
>     req: Request,
>     teamDomain: string,
>     audience: string,
>   ): Promise<AccessJwtPayload>;

[elithrar]

The tests (after building...) fail locally — unclear (to me) why:

$ cat /private/var/tmp/_bazel_matt/2a80ed57af32aa0a2e438bf225f1030d/execroot/_main/bazel-out/darwin_arm64-fastbuild/testlogs/src/cloudflare/internal/test/access-jwt/access-jwt-test@/test.log
Executing tests from //src/cloudflare/internal/test/access-jwt:access-jwt-test@
-----------------------------------------------------------------------------
kj/exception.c++:357: warning: llvm-symbolizer was not found. To symbolize stack traces, install it in your $PATH or set $LLVM_SYMBOLIZER to the location of the binary. When running tests under bazel, use `--test_env=LLVM_SYMBOLIZER=<path>`.
*** Received signal #11: Segmentation fault: 11
stack: 10b8c7907 10b8c6a3f 10b8c650b 107c8ea5f 107c8fb1b 1071b9fcf 1071b8b63 1071b8a17 1071b8983 1074fcdc3 1074fd943 106c8020b 106c8014f 106c8011b 106c7c79f 106c7c3f7 104fe02ab 104fe01f3 104fdf173 104fdec37 104fdeac7 104984d1b 104984b9b 104984e63 10477d91b 1048d8cb7 10bb5b4ab 10bb5b477 10bb52f87

Dismissing as requested from Dan.

[mhart]

Some minor suggestions, just to use some slightly more modern/idiomatic methods, but looks great overall

[elithrar]

@mhart @anonrig I think I got this right — addressed all the comments:

• replaced atob/btoa with Uint8Array.fromBase64/toBase64 w/ base64url alphabet
• used FixedLengthArray<string, 3>
• switched from setTimeout to globalThis.scheduler.wait() for retry delays
• module-level TextEncoder/TextDecoder for reuse

[anonrig]

Except the failing tests, the implementation looks really good.

[anonrig]

Nit: best way to do this is by doing:

const url = new URL(`https://cloudflare.com/cdn-cgi/access/certs`)
url.hostname = normalizedDomain;

[jasnell]

shouldn't that be const url = new URL('https://cloudflare.com/cdn-cgi/access/certs);` ?

[elithrar]

The domain has to include the team name: e.g. https://opencode-devtools.cloudflareaccess.com/cdn-cgi/access/certs - as the certs are scoped to the Access team/domain

[anonrig]

You can just do url.hostname = "opencode-devtools.cloudflareaccess.com" on the new URL() and it would be a lot safer

[elithrar]

I don't think I understand the comments here :)

• The certs are always at https://${teamName}.cloudflareaccess.com/cdn-cgi/access/certs - teamName is dynamic
• It's not static (to be extra clear)

We can make this https://${teamName}.cloudflareaccess.com/cdn-cgi/access/certs so that the string template doesn't need to cover the 'static' part of the domain but I don't see that as a net win?

[elithrar]

@anonrig unfortunately getting the tests to run locally in any reliable way is beyond me, and I can't grok why the tests can't see the access-jwt module:

FAIL: //src/cloudflare/internal/test/access-jwt:access-jwt-test@ (Exit 1) (see /home/runner/.cache/bazel/_bazel_runner/be54bd8ac890d1817c772d91eb8f6cb4/execroot/_main/bazel-out/aarch64-dbg/testlogs/src/cloudflare/internal/test/access-jwt/access-jwt-test@/test.log)
INFO: From Testing //src/cloudflare/internal/test/access-jwt:access-jwt-test@:
==================== Test output for //src/cloudflare/internal/test/access-jwt:access-jwt-test@:
service access-jwt-test: Uncaught Error: No such module "cloudflare-internal:access-jwt".
  imported from "worker" 

[anonrig]

@anonrig unfortunately getting the tests to run locally in any reliable way is beyond me, and I can't grok why the tests can't see the access-jwt module:

@elithrar Sorry I just saw this comment. Unfortunately, internal modules are not available on test harness.

[elithrar]

Changes to fix the test module import issue:

1. Removed _clearJwksCache from access-jwt.ts (dead code since tests can't access internal modules)
2. Removed the cloudflare-internal:access-jwt import from the test file
3. Each test now uses a unique team domain (e.g., test-valid, test-expired, test-5xx-retry) so cache entries don't conflict between tests

[elithrar]

For internal reviewers: https://share.opencode.cloudflare.dev/share/fqzhroMQ

[elithrar]

@anonrig might need your help to get this over the line from a toolchain PoV.

[kentonv]

Adding this to the cloudflare:workers module means that this JavaScript code will need to be parsed and compiled by every isolate that imports cloudflare:workers, whether or not they actually use the JWT functions. The cloudflare:workers module is relevant to almost everyone these days, but the JWT functions are relevant to a much smaller set of people. Also, there's a proposal to add JWT validation to the native APIs which would make these functions obsolete -- but we'll still have to support them forever, of course.

Given all this I'd really prefer these functions be placed in a separate module, so that people who don't import the module aren't impacted.

(That said, I'd even more prefer that we just go ahead and implement the native API... it'd be pretty easy.)

[elithrar]

What’s the path forward? Do we keep telling customers to copy paste JWT validation code from the docs?

Are JWT native APIs landing this week? Next year?

[kentonv]

To be clear I was only asking that you move the function to a different module name, like cloudflare:access or something. (Though admittedly I don't quite understand why a built-in is better than an npm module here, but I won't fight on that point.)

The native API would be where ctx.accessCredentials is just automatically filled in with the verified credentials. I could (prompt Claude to) implement this in an hour probably except that the runtime doesn't know the worker's access team name (to fetch the keys) no audience. Seems like these should be part of the workers config and delivered via the control plane. If someone could spec that out and get the control plane to deliver that info we could ship it next week. But PMs and EMs control priorities here, not me.

But again, assuming we can't prioritize that now, I'm fine with the library, it just has to be a different module name.

[jroyal]

fwiw I have an engineer about to start working on this from the access side and will probably reach out to you @kentonv soon.

[elithrar]

Closing this as it sounds like we're taking a different approach.