cloudflare-toolkit

Appearance

@adrianhall/cloudflare-toolkit

@adrianhall/cloudflare-toolkit / lib/hono / CloudflareAccessOptions

Interface: CloudflareAccessOptions ​

Defined in: src/lib/hono/cloudflare-access.ts:41

Options for cloudflareAccess.

Properties ​

audience? ​

readonly optional audience?: string

Defined in: src/lib/hono/cloudflare-access.ts:102

Fallback Application Audience Tag. Used to verify the JWT aud claim for a request whose matched PathPolicy does not itself specify an audience (including when no policy matches at all and CloudflareAccessOptions.defaultAction is "block").

A matched policy's own audience (see PathPolicy.audience) overrides this fallback for that request rather than merging with it — this lets path-specific audiences coexist with one shared fallback for everything else.

When neither this fallback nor the matched policy specify an audience, audience validation is skipped for that request — the aud claim is not checked at all. Every Cloudflare Access application in the same team shares the same JWKS, so without an aud check, a JWT that is valid for any other Access application in the team is accepted here too (cross-application token replay).

Unless CloudflareAccessOptions.enableDevTokens is true (local development), any authenticated request path that could reach verification without an audience configured — either this fallback or a per-policy audience — logs a one-time warning at construction time; see cloudflareAccess's security remarks.

defaultAction? ​

readonly optional defaultAction?: "bypass" | "block"

Defined in: src/lib/hono/cloudflare-access.ts:76

What to do when the request path does not match any policy.

  • "block" (default) — return 401 if no valid JWT is present.
  • "bypass" — allow the request through without authentication. If a valid JWT is present it is still verified and AuthVariables is still set; otherwise the request continues with no authenticated user.

devSecret? ​

readonly optional devSecret?: string

Defined in: src/lib/hono/cloudflare-access.ts:128

HMAC secret for validating developer-generated JWTs. Ignored unless CloudflareAccessOptions.enableDevTokens is true. When dev tokens are enabled and this is omitted, the well-known DEFAULT_DEV_SECRET is used and a one-time warning is logged — never rely on that for production security.

enableDevTokens? ​

readonly optional enableDevTokens?: boolean

Defined in: src/lib/hono/cloudflare-access.ts:121

Enable HS256 developer-token verification.

Default false (fail-closed). When false, cloudflareAccess verifies the JWT only against the Cloudflare Access JWKS — a developer-signed HS256 token (including one signed with the public DEFAULT_DEV_SECRET) is rejected. This prevents a deployed Worker from silently trusting forgeable dev tokens.

Enable it only in local development, gated on a build-time signal that is statically false in production:

ts
app.use(cloudflareAccess({ policies, enableDevTokens: import.meta.env.DEV }));

When enabled without an explicit CloudflareAccessOptions.devSecret, the middleware logs a one-time warning that it is verifying with the public default secret.

logger? ​

readonly optional logger?: Logger

Defined in: src/lib/hono/cloudflare-access.ts:133

Structured logger used for debug/info/warn/error diagnostics. Defaults to a silent logger (nothing is emitted) when omitted.

policies? ​

readonly optional policies?: PathPolicy[]

Defined in: src/lib/hono/cloudflare-access.ts:67

Path policies evaluated in order (first match wins).

  • authenticate: false — bypass JWT validation entirely.
  • authenticate: true — require a valid JWT (401 if missing/invalid).
  • No matching policy — behavior is controlled by CloudflareAccessOptions.defaultAction.

When omitted, every path is subject to CloudflareAccessOptions.defaultAction.

Each policy may also set its own audience — see PathPolicy.audience — so a single middleware instance can protect several path-scoped Cloudflare Access applications on the same hostname, each validated against its own Audience Tag, instead of one flat allowlist shared by every protected path.

Example ​

ts
policies: [
  { pattern: /^/api/version$/, authenticate: false },
  { pattern: /^/api/contributor/, authenticate: true, audience: contributorAud },
  { pattern: /^/api/reviewer/, authenticate: true, audience: reviewerAud },
  { pattern: /^/api//, authenticate: true }
]

teamDomain? ​

readonly optional teamDomain?: string

Defined in: src/lib/hono/cloudflare-access.ts:81

Cloudflare Access team domain used to fetch the public JWKS. When omitted, the middleware reads c.env.CLOUDFLARE_TEAM_DOMAIN at request time.