@homeflare/cloudflare 0.3.1 → 0.3.2

package/dist/access-auth/handler.d.ts

@@ -0,0 +1,65 @@
+/**
+ * A Cloudflare Access verifier shaped for Caddy's `forward_auth`.
+ *
+ * ★ WHAT THIS ADDS, AND WHAT IT DELIBERATELY DOES NOT. The verification is
+ *   `verifyAccessToken` in `../access.ts` — jose, a cached remote JWKS, a circuit breaker.
+ *   This file is the HTTP shape around it: find the token, answer 2xx or 4xx, and hand the
+ *   identity to the upstream as headers. There is no second verifier here, on purpose; two
+ *   implementations of a signature check is how one of them silently stops checking.
+ *
+ * ⛔ FAIL CLOSED, ALWAYS. Every path that does not end in a verified identity returns a
+ *   non-2xx, including a JWKS endpoint that is down. Caddy grants access on 2xx and only
+ *   on 2xx, so an exception escaping this handler would become a 502 from Caddy — still
+ *   closed, but without a log line. Hence the catch-all.
+ *
+ * ⛔ NEVER LOG THE TOKEN. Not at debug, not in an error message, not truncated. A token in
+ *   a log file is a replayable session for the whole of its `exp`. `reason` below is a
+ *   fixed enum and the caught error contributes only its CLASS NAME — jose's messages are
+ *   safe today, but "safe today" is not a property worth betting a credential on.
+ *
+ * Guide, and the Caddyfile that calls this: docs/access-auth.md.
+ */
+import { type AccessIdentity, type AccessOptions } from '../access.ts';
+import { type Logger } from '../log.ts';
+/** Why a request was refused. A closed set, so it is safe to log and safe to alert on. */
+export type DenyReason = 'no-token' | 'invalid-token' | 'jwks-unavailable' | 'not-authorized' | 'unexpected';
+/** The headers the upstream receives on success. Values are always strings, never absent. */
+export interface IdentityHeaders {
+    /** @default 'X-Access-Email' */
+    readonly email?: string;
+    /** @default 'X-Access-Sub' */
+    readonly sub?: string;
+}
+export interface AccessForwardAuthOptions extends AccessOptions {
+    /** Rename the identity headers to match an upstream that expects its own names. */
+    readonly headers?: IdentityHeaders;
+    /**
+     * An extra check on an already-verified identity. `false` is a 403, not a 401.
+     * ⚠️ AUTHORIZATION, NOT AUTHENTICATION. The Access policy is the real gate; this is for
+     *   an upstream that additionally wants, say, one team. Do not use it to re-check `aud`.
+     */
+    readonly authorize?: (identity: AccessIdentity) => boolean | Promise<boolean>;
+    /** @default the package logger */
+    readonly logger?: Logger;
+}
+/**
+ * Build the `fetch` handler Caddy's `forward_auth` calls.
+ *
+ * ```ts
+ * const verify = accessForwardAuth({
+ *   teamDomain: 'https://example.cloudflareaccess.com',
+ *   audience: process.env.ACCESS_AUD,
+ * });
+ * Bun.serve({ port: 9101, hostname: '127.0.0.1', fetch: verify });
+ * ```
+ *
+ * ⛔ ONE HANDLER PER ACCESS APPLICATION. `audience` is fixed at construction and is never
+ *   read from the request — an AUD a caller can influence is the whole vulnerability this
+ *   exists to prevent. Protecting two applications means two handlers and two routes.
+ *
+ * ★ RETURNS A PLAIN `(Request) => Promise<Response>`, so it needs no server framework and
+ *   no runtime-specific import: `Bun.serve`, `node:http`'s fetch adapters and workerd all
+ *   take it as-is. Routing several of these by path is the consumer's own `if`.
+ */
+export declare function accessForwardAuth(options: AccessForwardAuthOptions): (request: Request) => Promise<Response>;
+//# sourceMappingURL=handler.d.ts.map

package/dist/access-auth/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/access-auth/handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAqB,MAAM,cAAc,CAAC;AAC1F,OAAO,EAAE,KAAK,MAAM,EAAO,MAAM,WAAW,CAAC;AAG7C,0FAA0F;AAC1F,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,eAAe,GACf,kBAAkB,GAClB,gBAAgB,GAChB,YAAY,CAAC;AAEjB,6FAA6F;AAC7F,MAAM,WAAW,eAAe;IAC9B,gCAAgC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,8BAA8B;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,wBAAyB,SAAQ,aAAa;IAC7D,mFAAmF;IACnF,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9E,kCAAkC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAuCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,wBAAwB,GAChC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CA6CzC"}

package/dist/access-auth/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@homeflare/cloudflare/access-auth` — a Cloudflare Access verifier for a reverse proxy's
+ * `forward_auth`, so a surface that is not a Worker can be protected by Access properly.
+ *
+ * ★ WHY THIS IS A SUBPATH AND NOT THE MAIN ENTRY. The package entry is the workerd layer.
+ *   This handler is runtime-neutral — `Request` in, `Response` out, no platform import —
+ *   because the process that runs it sits next to the proxy, typically under Bun or Node,
+ *   not on workerd. A subpath keeps that opt-in explicit and leaves the entry unchanged.
+ *
+ * ⛔ THE AUD IS THE WHOLE CHECK. Every Access application in one account is signed by the
+ *   SAME team keys, so a token minted for a different app in your own account verifies
+ *   perfectly against issuer and signature. Only `audience` says the token was minted for
+ *   THIS application. A verifier that checks `iss` alone admits every Access user of every
+ *   app you run — which reads as working, for everyone, until the wrong person tries.
+ *
+ * ⚠️ THIS PROTECTS THE PROXY HOP, NOT THE ORIGIN PORT. Verifying the JWT is worth nothing
+ *   if the upstream is also reachable directly; bind it to loopback, or the check is an
+ *   ornament on a door that is propped open. docs/access-auth.md says it again with the
+ *   Caddyfile.
+ */
+export { accessForwardAuth, type AccessForwardAuthOptions, type DenyReason, type IdentityHeaders, } from './handler.ts';
+export { ACCESS_COOKIE, ACCESS_HEADER, accessToken, readCookie, type FoundToken, type TokenSource, } from './token.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/access-auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/access-auth/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,UAAU,EACf,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,aAAa,EACb,aAAa,EACb,WAAW,EACX,UAAU,EACV,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,YAAY,CAAC"}

package/dist/access-auth/index.js

@@ -0,0 +1,186 @@
+// src/access.ts
+import { createRemoteJWKSet, customFetch, jwtVerify } from "jose";
+
+// src/jwks-breaker.ts
+var BREAKER_COOLDOWN_MS = 30000;
+var failures = new Map;
+function breakered(inner = (url, options) => fetch(url, options), cooldownMs = BREAKER_COOLDOWN_MS) {
+  return async (url, options) => {
+    const open = failures.get(url);
+    if (open !== undefined && Date.now() - open.at < cooldownMs) {
+      throw open.error;
+    }
+    try {
+      const response = await inner(url, options);
+      if (!response.ok) {
+        const error = new Error(`JWKS endpoint answered ${String(response.status)}: ${url}`);
+        failures.set(url, { at: Date.now(), error });
+        throw error;
+      }
+      failures.delete(url);
+      return response;
+    } catch (cause) {
+      const error = cause instanceof Error ? cause : new Error(String(cause));
+      failures.set(url, { at: Date.now(), error });
+      throw error;
+    }
+  };
+}
+
+// src/access.ts
+var ACCESS_HEADER = "cf-access-jwt-assertion";
+var jwks = new Map;
+function keysFor(teamDomain) {
+  const existing = jwks.get(teamDomain);
+  if (existing !== undefined)
+    return existing;
+  const created = createRemoteJWKSet(new URL(`${teamDomain}/cdn-cgi/access/certs`), {
+    [customFetch]: breakered()
+  });
+  jwks.set(teamDomain, created);
+  return created;
+}
+async function verifyAccessJwt(request, options) {
+  const token = request.headers.get(ACCESS_HEADER);
+  if (token === null)
+    throw new Error("access: no Cf-Access-Jwt-Assertion header");
+  return await verifyAccessToken(token, options);
+}
+async function verifyAccessToken(token, options) {
+  const { payload } = await jwtVerify(token, keysFor(options.teamDomain), {
+    issuer: options.teamDomain,
+    audience: options.audience,
+    ...options.maxTokenAge === undefined ? {} : { maxTokenAge: options.maxTokenAge },
+    ...options.clockTolerance === undefined ? {} : { clockTolerance: options.clockTolerance }
+  });
+  return {
+    email: typeof payload["email"] === "string" ? payload["email"] : undefined,
+    sub: payload.sub,
+    claims: payload
+  };
+}
+
+// src/log.ts
+function emit(level, message, fields) {
+  const line = { level, message, ...fields };
+  if (level === "error")
+    console.error(line);
+  else if (level === "warn")
+    console.warn(line);
+  else
+    console.log(line);
+}
+function make(bound) {
+  return {
+    debug: (message, fields) => emit("debug", message, { ...bound, ...fields }),
+    info: (message, fields) => emit("info", message, { ...bound, ...fields }),
+    warn: (message, fields) => emit("warn", message, { ...bound, ...fields }),
+    error: (message, fields) => emit("error", message, { ...bound, ...fields }),
+    with: (extra) => make({ ...bound, ...extra })
+  };
+}
+var log = make({});
+
+// src/access-auth/token.ts
+var ACCESS_HEADER2 = "Cf-Access-Jwt-Assertion";
+var ACCESS_COOKIE = "CF_Authorization";
+function readCookie(header, name) {
+  if (header === null)
+    return;
+  for (const pair of header.split(";")) {
+    const eq = pair.indexOf("=");
+    if (eq === -1)
+      continue;
+    if (pair.slice(0, eq).trim() !== name)
+      continue;
+    const value = pair.slice(eq + 1).trim();
+    return value === "" ? undefined : value;
+  }
+  return;
+}
+function accessToken(request) {
+  const fromHeader = request.headers.get(ACCESS_HEADER2);
+  if (fromHeader !== null && fromHeader !== "")
+    return { token: fromHeader, source: "header" };
+  const fromCookie = readCookie(request.headers.get("Cookie"), ACCESS_COOKIE);
+  if (fromCookie !== undefined)
+    return { token: fromCookie, source: "cookie" };
+  return;
+}
+
+// src/access-auth/handler.ts
+var DEFAULT_HEADERS = { email: "X-Access-Email", sub: "X-Access-Sub" };
+function reasonFor(error) {
+  for (let cur = error, hops = 0;cur instanceof Error && hops < 4; hops += 1) {
+    if (cur.message.includes("JWKS endpoint answered"))
+      return "jwks-unavailable";
+    if (cur.name === "JWKSTimeout" || cur.name === "TypeError")
+      return "jwks-unavailable";
+    cur = cur.cause;
+  }
+  return "invalid-token";
+}
+function errorClass(error) {
+  return error instanceof Error ? error.name : typeof error;
+}
+function deny(status) {
+  return new Response(null, { status });
+}
+function accessForwardAuth(options) {
+  const names = { ...DEFAULT_HEADERS, ...options.headers };
+  const logger = options.logger ?? log;
+  assertTeamDomain(options.teamDomain);
+  return async (request) => {
+    const found = accessToken(request);
+    if (found === undefined) {
+      logger.warn("access denied", { reason: "no-token" });
+      return deny(401);
+    }
+    let identity;
+    try {
+      identity = await verifyAccessToken(found.token, options);
+    } catch (error) {
+      const reason = reasonFor(error);
+      logger.warn("access denied", { reason, source: found.source, error: errorClass(error) });
+      return deny(401);
+    }
+    try {
+      if (options.authorize !== undefined && !await options.authorize(identity)) {
+        logger.warn("access denied", {
+          reason: "not-authorized",
+          email: identity.email ?? ""
+        });
+        return deny(403);
+      }
+    } catch (error) {
+      logger.error("access denied", {
+        reason: "unexpected",
+        error: errorClass(error)
+      });
+      return deny(403);
+    }
+    return granted(identity, names, found.source);
+  };
+}
+function granted(identity, names, source) {
+  const headers = new Headers;
+  headers.set(names.email, identity.email ?? "");
+  headers.set(names.sub, identity.sub ?? "");
+  headers.set("X-Access-Token-Source", source);
+  return new Response(null, { status: 204, headers });
+}
+function assertTeamDomain(teamDomain) {
+  if (!teamDomain.startsWith("https://") || teamDomain.endsWith("/")) {
+    throw new Error(`access-auth: teamDomain must be https:// with no trailing slash, got ${teamDomain}`);
+  }
+}
+export {
+  ACCESS_COOKIE,
+  ACCESS_HEADER2 as ACCESS_HEADER,
+  accessForwardAuth,
+  accessToken,
+  readCookie
+};
+
+//# debugId=5270BF136297A56A64756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/access-auth/index.js.map

@@ -0,0 +1,14 @@
+{
+  "version": 3,
+  "sources": ["../src/access.ts", "../src/jwks-breaker.ts", "../src/log.ts", "../src/access-auth/token.ts", "../src/access-auth/handler.ts"],
+  "sourcesContent": [
+    "/**\n * Cloudflare Access JWT verification.\n *\n * ★ WHY jose AND NOT A HAND-ROLLED VERIFY. Signature verification is the one place where\n *   a subtle bug is silent and total: a check that never fails looks identical to a\n *   check that always passes. jose handles JWKS fetching, `kid` matching and key\n *   rotation, and it is widely deployed. This file is the Access-specific\n *   wiring around it, nothing more.\n *\n * ⚠️ THE TRAP THIS CLOSES. Cloudflare's own example does `jwtVerify(...)` inline in the\n *   handler, which builds a NEW remote JWKS on every request — an outbound fetch per\n *   request, and a thundering herd on the certs endpoint under load. The cache below is\n *   keyed by team domain and lives for the isolate's lifetime.\n *\n * ⛔ NEVER SKIP `audience`. Any Access app in your account produces a JWT this team\n *   domain will happily verify; the AUD tag is the only thing that says the token was\n *   minted for THIS app. Verifying issuer alone accepts tokens from a neighbouring app.\n *\n * Docs: developers.cloudflare.com/cloudflare-one/identity/authorization-cookie/validating-json/\n */\nimport { createRemoteJWKSet, customFetch, jwtVerify } from 'jose';\nimport { breakered } from './jwks-breaker.ts';\n\n/** The header Access puts the token in. Lowercase — Headers.get is case-insensitive. */\nconst ACCESS_HEADER = 'cf-access-jwt-assertion';\n\nexport interface AccessOptions {\n  /** `https://<team>.cloudflareaccess.com` — the issuer, and the JWKS host. */\n  readonly teamDomain: string;\n  /** The application's AUD tag, from Zero Trust → Access → Applications. */\n  readonly audience: string;\n  /**\n   * Reject a token older than this, by `iat`. Seconds, or a jose duration like `'8h'`.\n   * ★ OPT-IN BECAUSE `exp` ALREADY BOUNDS THE TOKEN. Access sets the session lifetime in\n   *   `exp`, so this is a second, shorter leash for a surface that wants one — not a\n   *   missing check. ⚠️ Setting it below the Access session duration logs users out\n   *   mid-session with a 401 they cannot fix by retrying.\n   */\n  readonly maxTokenAge?: string | number;\n  /** Seconds of clock skew tolerated on `exp`/`nbf`/`iat`. jose's default is 0. */\n  readonly clockTolerance?: string | number;\n}\n\n/** The subset of Access claims worth depending on. */\nexport interface AccessIdentity {\n  readonly email: string | undefined;\n  readonly sub: string | undefined;\n  /** Everything else, for callers that need a claim this interface does not name. */\n  readonly claims: Readonly<Record<string, unknown>>;\n}\n\n/**\n * One JWKS per team domain, reused for the isolate's life.\n * ⚠️ Module scope is per-isolate on workerd, not per-request and not global. That is\n *   exactly the right lifetime here: long enough to amortise the fetch, short enough\n *   that a rotated key is picked up when the isolate recycles. jose also refreshes on\n *   an unknown `kid`.\n */\nconst jwks = new Map<string, ReturnType<typeof createRemoteJWKSet>>();\n\nfunction keysFor(teamDomain: string): ReturnType<typeof createRemoteJWKSet> {\n  const existing = jwks.get(teamDomain);\n  if (existing !== undefined) return existing;\n\n  // ⛔ THE BREAKER IS NOT OPTIONAL. jose refetches on EVERY call while an endpoint is\n  //   down — measured on 6.2.12: 5 verifications against a 404ing certs endpoint made 5\n  //   outbound fetches, and no combination of cacheMaxAge or cooldownDuration changes it.\n  //   Without this, a Cloudflare Access outage turns every inbound request into an\n  //   outbound one. See jwks-breaker.ts.\n  const created = createRemoteJWKSet(new URL(`${teamDomain}/cdn-cgi/access/certs`), {\n    [customFetch]: breakered(),\n  });\n  jwks.set(teamDomain, created);\n  return created;\n}\n\n/**\n * Verify the Access JWT on `request`, returning the identity it asserts.\n *\n * ⛔ THROWS ON EVERY FAILURE — missing header, bad signature, wrong audience, expired.\n *   ★ Deliberately not a boolean or a null: an `if (!ok)` that a caller forgets to write\n *     is an open door, whereas an unhandled throw is a 500 and a log line. Callers that\n *     want a soft path catch it explicitly.\n */\nexport async function verifyAccessJwt(\n  request: Request,\n  options: AccessOptions,\n): Promise<AccessIdentity> {\n  const token = request.headers.get(ACCESS_HEADER);\n  if (token === null) throw new Error('access: no Cf-Access-Jwt-Assertion header');\n\n  return await verifyAccessToken(token, options);\n}\n\n/**\n * Verify a token string that the caller has already located, returning the identity.\n *\n * ★ EXTRACTED SO THERE IS EXACTLY ONE VERIFICATION, NOT TWO. `verifyAccessJwt` reads the\n *   header; the forward_auth handler (`@homeflare/cloudflare/access-auth`) also accepts\n *   the `CF_Authorization` cookie, because Cloudflare's own documentation says the cookie\n *   \"is not guaranteed to be passed\" and the reverse is true too — a request that arrives\n *   through a proxy hop may carry one and not the other. Both funnel here, so a fix to the\n *   checks below cannot land on one path and miss the other.\n *\n * ⛔ THROWS ON EVERY FAILURE, exactly like `verifyAccessJwt`. Same reasoning: a boolean a\n *   caller forgets to test is an open door.\n */\nexport async function verifyAccessToken(\n  token: string,\n  options: AccessOptions,\n): Promise<AccessIdentity> {\n  const { payload } = await jwtVerify(token, keysFor(options.teamDomain), {\n    issuer: options.teamDomain,\n    audience: options.audience,\n    // ⛔ SPREAD, NOT `maxTokenAge: options.maxTokenAge`. `exactOptionalPropertyTypes` is on,\n    //   and passing an explicit `undefined` is not the same as omitting the key — jose\n    //   reads `'maxTokenAge' in options`, so the undefined form would enable the check\n    //   with an undefined bound.\n    ...(options.maxTokenAge === undefined ? {} : { maxTokenAge: options.maxTokenAge }),\n    ...(options.clockTolerance === undefined ? {} : { clockTolerance: options.clockTolerance }),\n  });\n\n  return {\n    email: typeof payload['email'] === 'string' ? payload['email'] : undefined,\n    sub: payload.sub,\n    claims: payload,\n  };\n}\n",
+    "/**\n * A circuit breaker for JWKS fetches, installed at jose's own `customFetch` seam.\n *\n * ⛔ THE AMPLIFICATION THIS CLOSES, MEASURED ON jose 6.2.12 — the version this package\n *   pins, not an old one:\n *\n *       5 verifications of a well-formed token, certs endpoint 404ing → 5 outbound fetches\n *\n *   jose assigns `jwksTimestamp` only inside the `.then()` of a SUCCESSFUL fetch\n *   (`dist/webapi/jwks/remote.js`, line 58). While an endpoint is down, `local` stays\n *   undefined, so `if (!local || !isFreshFor(jwksTimestamp, cacheMaxAge)) await reload()`\n *   runs on EVERY call. A down Access endpoint therefore turns every inbound request into\n *   an outbound fetch, indefinitely.\n *\n * ★ NOT A REIMPLEMENTATION. `customFetch` is jose's exported, documented extension point;\n *   jose keeps doing the caching, cooldown, `kid` matching and verification. This adds the\n *   one thing it does not do — remember that a fetch FAILED.\n *   ⚠️ Measured first: neither `cacheMaxAge: Infinity` nor `cooldownDuration` nor both\n *     together change the count. It is 5 fetches in every configuration, so this is not a\n *     matter of configuring jose correctly.\n *\n * ⛔ THE BREAKER STORES PLAIN VALUES ONLY — a timestamp and an Error. NEVER a Response, a\n *   body stream, or a promise of one.\n *   🔴 On workerd, a Response and its body belong to the IoContext of the request that\n *     created them, and another request touching either throws:\n *         Cannot perform I/O on behalf of a different request.\n *     Caching a Response across requests would therefore turn a VALID token into a flat\n *     401 for every caller but the first — an outage strictly worse than the amplification\n *     it was meant to fix. Timestamps and Errors cross requests legally; I/O objects do not.\n */\n\nimport type { FetchImplementation } from 'jose';\n\n/** How long a URL stays latched open after a failed probe. */\nexport const BREAKER_COOLDOWN_MS = 30_000;\n\ntype Failure = { readonly at: number; readonly error: Error };\n\n/**\n * ⚠️ Module scope is PER ISOLATE on workerd, which is the right lifetime: long enough to\n *   stop the storm, short enough that a recycled isolate retries a recovered endpoint.\n */\nconst failures = new Map<string, Failure>();\n\n/** Visible for testing. ⛔ Not exported from the package — resetting it in production\n *  would discard exactly the memory this exists to keep. */\nexport function resetBreaker(): void {\n  failures.clear();\n}\n\n/**\n * Wrap a fetch so a failing URL is not retried for `cooldownMs`.\n *\n * ★ FAILURE IS COUNTED AT THE SEAM, not inferred from an error class further up. jose\n *   throws `JWKSNoMatchingKey` as a NORMAL answer from a perfectly healthy endpoint — a\n *   token signed with a rotated key does that — so treating it as a fault would latch a\n *   working endpoint closed and reject every valid token for 30 seconds.\n */\nexport function breakered(\n  inner: FetchImplementation = (url, options) => fetch(url, options),\n  cooldownMs: number = BREAKER_COOLDOWN_MS,\n): FetchImplementation {\n  // ⚠️ jose's OWN FetchImplementation, not `typeof fetch`. It is narrower — a string URL\n  //   and a fixed options shape — and using the global type instead fails to typecheck on\n  //   `preconnect`, a property of the platform fetch that no seam implementation has.\n  return async (url, options) => {\n    const open = failures.get(url);\n\n    if (open !== undefined && Date.now() - open.at < cooldownMs) {\n      // ⚠️ Rethrow the ORIGINAL error, not a generic one: the first failure says whether\n      //   this was a 404, a TLS problem or a timeout, and that is what an operator needs.\n      //   A \"circuit open\" message alone hides the actual fault.\n      throw open.error;\n    }\n\n    try {\n      const response = await inner(url, options);\n\n      // ⛔ A non-200 is a failure here. jose requires 200 with a JSON body; a 404 or a 502\n      //   is exactly the down-endpoint case, and it does NOT throw on its own.\n      if (!response.ok) {\n        const error = new Error(`JWKS endpoint answered ${String(response.status)}: ${url}`);\n        failures.set(url, { at: Date.now(), error });\n        throw error;\n      }\n\n      failures.delete(url);\n      return response;\n    } catch (cause) {\n      const error = cause instanceof Error ? cause : new Error(String(cause));\n      // `set` is idempotent here — a second failure simply restarts the cooldown.\n      failures.set(url, { at: Date.now(), error });\n      throw error;\n    }\n  };\n}\n",
+    "/**\n * Structured logging for Workers.\n *\n * ★ WHY NO LOGGING LIBRARY. Cloudflare Workers Logs parses `console.log` output as JSON\n *   natively and indexes every field, with unlimited cardinality — so a JSON object on\n *   console IS the structured logging integration. pino is Node-shaped (streams, worker\n *   threads) and needs a wrapper on workerd; `pino-pretty` does not work with wrangler\n *   at all (workers-sdk#6841). Adding a dependency here would buy formatting we do not\n *   want and cost bundle size on a hot path.\n *   Docs: developers.cloudflare.com/workers/observability/logs/workers-logs/\n *\n * ⛔ NEVER LOG A CREDENTIAL. There is no redaction layer here and deliberately so — a\n *   redactor implies it is safe to pass secrets in, and then quietly misses one.\n */\n\n/** Anything JSON-serialisable. Workers Logs indexes each key as its own field. */\nexport type LogFields = Readonly<Record<string, unknown>>;\n\nexport interface Logger {\n  readonly debug: (message: string, fields?: LogFields) => void;\n  readonly info: (message: string, fields?: LogFields) => void;\n  readonly warn: (message: string, fields?: LogFields) => void;\n  readonly error: (message: string, fields?: LogFields) => void;\n  /** Returns a logger that merges `bound` into every subsequent line. */\n  readonly with: (bound: LogFields) => Logger;\n}\n\ntype Level = 'debug' | 'info' | 'warn' | 'error';\n\nfunction emit(level: Level, message: string, fields: LogFields): void {\n  // ⚠️ ONE OBJECT, NOT (message, fields). console.log with several arguments is\n  //   stringified and concatenated by the runtime, which destroys the structure Workers\n  //   Logs would otherwise index — the symptom is a `message` field containing your\n  //   whole payload as text, unqueryable.\n  const line = { level, message, ...fields };\n\n  if (level === 'error') console.error(line);\n  else if (level === 'warn') console.warn(line);\n  else console.log(line);\n}\n\nfunction make(bound: LogFields): Logger {\n  return {\n    debug: (message, fields) => emit('debug', message, { ...bound, ...fields }),\n    info: (message, fields) => emit('info', message, { ...bound, ...fields }),\n    warn: (message, fields) => emit('warn', message, { ...bound, ...fields }),\n    error: (message, fields) => emit('error', message, { ...bound, ...fields }),\n    with: (extra) => make({ ...bound, ...extra }),\n  };\n}\n\n/**\n * The root logger. Bind request-scoped context rather than passing it every call:\n *\n *     const requestLog = log.with({ requestId, path: url.pathname });\n *     requestLog.info('handled', { status, ms });\n */\nexport const log: Logger = make({});\n",
+    "/**\n * Finding the Access token on an inbound request — header first, cookie second.\n *\n * ★ BOTH, BECAUSE NEITHER IS GUARANTEED. Cloudflare's validation guide says the\n *   `CF_Authorization` cookie \"is not guaranteed to be passed\" and to prefer the\n *   `Cf-Access-Jwt-Assertion` header. The reverse also happens: the header is attached by\n *   the Access hop, so a request that reaches the origin through a further proxy — or a\n *   browser replaying its own cookie — can carry the cookie and not the header. Checking\n *   one only is a 401 that looks like a broken login and is actually a missing branch.\n *\n * ⛔ THE HEADER WINS WHEN BOTH ARE PRESENT, and that order is load-bearing. The header is\n *   set by the Access hop on this request; the cookie is whatever the client's jar held.\n *   Preferring the cookie would let a client pin a stale token over the fresh assertion.\n *   ⚠️ Neither is trusted here — both are verified identically by `verifyAccessToken`.\n *   This is about which candidate is tried, not about which is believed.\n */\n\n/** The header Access sets on the request it forwards to the origin. */\nexport const ACCESS_HEADER = 'Cf-Access-Jwt-Assertion';\n\n/** The cookie Access sets in the browser. */\nexport const ACCESS_COOKIE = 'CF_Authorization';\n\n/** Where a candidate token was found. Useful in a log line; never a trust signal. */\nexport type TokenSource = 'header' | 'cookie';\n\nexport interface FoundToken {\n  readonly token: string;\n  readonly source: TokenSource;\n}\n\n/**\n * Read one cookie out of a `Cookie` header value.\n *\n * ⚠️ HAND-PARSED, AND SMALL ON PURPOSE. A cookie library would bring parsing of\n *   attributes (Path, SameSite, Max-Age) that only ever appear on `Set-Cookie`, which is\n *   the response side. Requests carry a bare `name=value; name=value` list, and that is\n *   all this reads.\n * ⚠️ A JWT is base64url and contains no `;` or `=`-in-value ambiguity beyond padding, but\n *   this still splits on the FIRST `=` only — a value containing `=` (base64 padding) is\n *   otherwise truncated mid-token, which fails verification with a signature error and\n *   sends you hunting in the wrong place.\n */\nexport function readCookie(header: string | null, name: string): string | undefined {\n  if (header === null) return undefined;\n\n  for (const pair of header.split(';')) {\n    const eq = pair.indexOf('=');\n    if (eq === -1) continue;\n    if (pair.slice(0, eq).trim() !== name) continue;\n\n    const value = pair.slice(eq + 1).trim();\n    return value === '' ? undefined : value;\n  }\n\n  return undefined;\n}\n\n/**\n * The Access token on `request`, or `undefined` when it carries none.\n *\n * ⛔ RETURNS THE CANDIDATE UNVERIFIED. Every caller must hand the result to\n *   `verifyAccessToken`; nothing about being present in a header makes a token valid.\n */\nexport function accessToken(request: Request): FoundToken | undefined {\n  const fromHeader = request.headers.get(ACCESS_HEADER);\n  if (fromHeader !== null && fromHeader !== '') return { token: fromHeader, source: 'header' };\n\n  const fromCookie = readCookie(request.headers.get('Cookie'), ACCESS_COOKIE);\n  if (fromCookie !== undefined) return { token: fromCookie, source: 'cookie' };\n\n  return undefined;\n}\n",
+    "/**\n * A Cloudflare Access verifier shaped for Caddy's `forward_auth`.\n *\n * ★ WHAT THIS ADDS, AND WHAT IT DELIBERATELY DOES NOT. The verification is\n *   `verifyAccessToken` in `../access.ts` — jose, a cached remote JWKS, a circuit breaker.\n *   This file is the HTTP shape around it: find the token, answer 2xx or 4xx, and hand the\n *   identity to the upstream as headers. There is no second verifier here, on purpose; two\n *   implementations of a signature check is how one of them silently stops checking.\n *\n * ⛔ FAIL CLOSED, ALWAYS. Every path that does not end in a verified identity returns a\n *   non-2xx, including a JWKS endpoint that is down. Caddy grants access on 2xx and only\n *   on 2xx, so an exception escaping this handler would become a 502 from Caddy — still\n *   closed, but without a log line. Hence the catch-all.\n *\n * ⛔ NEVER LOG THE TOKEN. Not at debug, not in an error message, not truncated. A token in\n *   a log file is a replayable session for the whole of its `exp`. `reason` below is a\n *   fixed enum and the caught error contributes only its CLASS NAME — jose's messages are\n *   safe today, but \"safe today\" is not a property worth betting a credential on.\n *\n * Guide, and the Caddyfile that calls this: docs/access-auth.md.\n */\nimport { type AccessIdentity, type AccessOptions, verifyAccessToken } from '../access.ts';\nimport { type Logger, log } from '../log.ts';\nimport { type TokenSource, accessToken } from './token.ts';\n\n/** Why a request was refused. A closed set, so it is safe to log and safe to alert on. */\nexport type DenyReason =\n  | 'no-token'\n  | 'invalid-token'\n  | 'jwks-unavailable'\n  | 'not-authorized'\n  | 'unexpected';\n\n/** The headers the upstream receives on success. Values are always strings, never absent. */\nexport interface IdentityHeaders {\n  /** @default 'X-Access-Email' */\n  readonly email?: string;\n  /** @default 'X-Access-Sub' */\n  readonly sub?: string;\n}\n\nexport interface AccessForwardAuthOptions extends AccessOptions {\n  /** Rename the identity headers to match an upstream that expects its own names. */\n  readonly headers?: IdentityHeaders;\n  /**\n   * An extra check on an already-verified identity. `false` is a 403, not a 401.\n   * ⚠️ AUTHORIZATION, NOT AUTHENTICATION. The Access policy is the real gate; this is for\n   *   an upstream that additionally wants, say, one team. Do not use it to re-check `aud`.\n   */\n  readonly authorize?: (identity: AccessIdentity) => boolean | Promise<boolean>;\n  /** @default the package logger */\n  readonly logger?: Logger;\n}\n\nconst DEFAULT_HEADERS = { email: 'X-Access-Email', sub: 'X-Access-Sub' } as const;\n\n/**\n * ⛔ A JWKS FAILURE MUST NOT READ AS A BAD TOKEN. They need opposite responses from an\n *   operator — rotate nothing versus page someone — and they are indistinguishable in the\n *   caller's 401. jose surfaces the breaker's error as the `cause` of a JWKS error, so the\n *   class names of both the error and its cause are checked.\n */\nfunction reasonFor(error: unknown): DenyReason {\n  // ⚠️ WALK THE `cause` CHAIN. jose wraps a transport failure, so the interesting error is\n  //   rarely the outermost one — matching only on `error.name` reports every JWKS outage\n  //   as a bad token, which is the diagnosis that sends an operator to the wrong system.\n  for (let cur: unknown = error, hops = 0; cur instanceof Error && hops < 4; hops += 1) {\n    // The breaker in ../jwks-breaker.ts throws exactly this for a non-200 certs endpoint.\n    if (cur.message.includes('JWKS endpoint answered')) return 'jwks-unavailable';\n    // `JWKSTimeout` is jose's; a bare `TypeError` from the fetch seam is \"network refused\".\n    if (cur.name === 'JWKSTimeout' || cur.name === 'TypeError') return 'jwks-unavailable';\n    cur = cur.cause;\n  }\n\n  // ⛔ EVERYTHING ELSE IS A BAD TOKEN, INCLUDING `JWKSNoMatchingKey`. An unknown `kid` from\n  //   a healthy endpoint means the token was signed by a key this team does not publish —\n  //   that is a forgery or a long-rotated token, never an outage. Classing it as an outage\n  //   would hide a forged token in the alert that says \"Cloudflare is down\".\n  return 'invalid-token';\n}\n\nfunction errorClass(error: unknown): string {\n  return error instanceof Error ? error.name : typeof error;\n}\n\n/** ⛔ No body, no `WWW-Authenticate` detail, no reason. An unauthenticated caller learns\n *  nothing about why; the reason goes to the log, where an operator can read it. */\nfunction deny(status: 401 | 403): Response {\n  return new Response(null, { status });\n}\n\n/**\n * Build the `fetch` handler Caddy's `forward_auth` calls.\n *\n * ```ts\n * const verify = accessForwardAuth({\n *   teamDomain: 'https://example.cloudflareaccess.com',\n *   audience: process.env.ACCESS_AUD,\n * });\n * Bun.serve({ port: 9101, hostname: '127.0.0.1', fetch: verify });\n * ```\n *\n * ⛔ ONE HANDLER PER ACCESS APPLICATION. `audience` is fixed at construction and is never\n *   read from the request — an AUD a caller can influence is the whole vulnerability this\n *   exists to prevent. Protecting two applications means two handlers and two routes.\n *\n * ★ RETURNS A PLAIN `(Request) => Promise<Response>`, so it needs no server framework and\n *   no runtime-specific import: `Bun.serve`, `node:http`'s fetch adapters and workerd all\n *   take it as-is. Routing several of these by path is the consumer's own `if`.\n */\nexport function accessForwardAuth(\n  options: AccessForwardAuthOptions,\n): (request: Request) => Promise<Response> {\n  const names = { ...DEFAULT_HEADERS, ...options.headers };\n  const logger = options.logger ?? log;\n  assertTeamDomain(options.teamDomain);\n\n  return async (request: Request): Promise<Response> => {\n    const found = accessToken(request);\n    if (found === undefined) {\n      logger.warn('access denied', { reason: 'no-token' satisfies DenyReason });\n      return deny(401);\n    }\n\n    let identity: AccessIdentity;\n    try {\n      identity = await verifyAccessToken(found.token, options);\n    } catch (error) {\n      const reason = reasonFor(error);\n      logger.warn('access denied', { reason, source: found.source, error: errorClass(error) });\n      return deny(401);\n    }\n\n    try {\n      if (options.authorize !== undefined && !(await options.authorize(identity))) {\n        // ⚠️ 403, not 401: re-authenticating cannot help, and a 401 sends the browser back\n        //   to Access for a login it already completed — an infinite redirect loop.\n        logger.warn('access denied', {\n          reason: 'not-authorized' satisfies DenyReason,\n          email: identity.email ?? '',\n        });\n        return deny(403);\n      }\n    } catch (error) {\n      // ⛔ A THROWING `authorize` IS A DENIAL, NOT A GRANT. A consumer's callback that hits\n      //   its own database and fails must not fall through to the success path; letting the\n      //   exception escape would hand Caddy a 502, which is also closed but arrives with no\n      //   log line saying whose callback broke.\n      logger.error('access denied', {\n        reason: 'unexpected' satisfies DenyReason,\n        error: errorClass(error),\n      });\n      return deny(403);\n    }\n\n    return granted(identity, names, found.source);\n  };\n}\n\n/**\n * ⛔ EVERY IDENTITY HEADER IS SET ON EVERY 2xx, empty string included. This is the\n *   spoofing defence, and it is not optional.\n *   🔴 Caddy's `copy_headers` expands to `request_header <Name> {rp.header.<Name>}` inside\n *     a 2xx handler — it copies FROM the auth response ONTO the client's request. A client\n *     that sends `X-Access-Email: admin@example.com` itself is overwritten only if this\n *     response carries that header. Omitting it for a token with no `email` claim would\n *     leave the attacker's value standing, and the upstream would read it as identity.\n *     Always emitting the name closes that whether or not Caddy also clears absent fields\n *     — behaviour its documentation does not actually promise.\n */\nfunction granted(\n  identity: AccessIdentity,\n  names: Required<IdentityHeaders>,\n  source: TokenSource,\n): Response {\n  const headers = new Headers();\n  headers.set(names.email, identity.email ?? '');\n  headers.set(names.sub, identity.sub ?? '');\n  headers.set('X-Access-Token-Source', source);\n  return new Response(null, { status: 204, headers });\n}\n\n/**\n * ⚠️ A TRAILING SLASH BREAKS BOTH CHECKS AT ONCE, AND QUIETLY. `teamDomain` is used\n *   verbatim as the expected `iss` and as the JWKS origin, so `https://x.cloudflareaccess.com/`\n *   yields an `iss` that never matches any real token AND a double-slashed certs URL. The\n *   symptom is every token failing verification with no clue pointing at the config.\n */\nfunction assertTeamDomain(teamDomain: string): void {\n  if (!teamDomain.startsWith('https://') || teamDomain.endsWith('/')) {\n    throw new Error(\n      `access-auth: teamDomain must be https:// with no trailing slash, got ${teamDomain}`,\n    );\n  }\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "5270BF136297A56A64756E2164756E21",
+  "names": []
+}

package/dist/access-auth/token.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Finding the Access token on an inbound request — header first, cookie second.
+ *
+ * ★ BOTH, BECAUSE NEITHER IS GUARANTEED. Cloudflare's validation guide says the
+ *   `CF_Authorization` cookie "is not guaranteed to be passed" and to prefer the
+ *   `Cf-Access-Jwt-Assertion` header. The reverse also happens: the header is attached by
+ *   the Access hop, so a request that reaches the origin through a further proxy — or a
+ *   browser replaying its own cookie — can carry the cookie and not the header. Checking
+ *   one only is a 401 that looks like a broken login and is actually a missing branch.
+ *
+ * ⛔ THE HEADER WINS WHEN BOTH ARE PRESENT, and that order is load-bearing. The header is
+ *   set by the Access hop on this request; the cookie is whatever the client's jar held.
+ *   Preferring the cookie would let a client pin a stale token over the fresh assertion.
+ *   ⚠️ Neither is trusted here — both are verified identically by `verifyAccessToken`.
+ *   This is about which candidate is tried, not about which is believed.
+ */
+/** The header Access sets on the request it forwards to the origin. */
+export declare const ACCESS_HEADER = "Cf-Access-Jwt-Assertion";
+/** The cookie Access sets in the browser. */
+export declare const ACCESS_COOKIE = "CF_Authorization";
+/** Where a candidate token was found. Useful in a log line; never a trust signal. */
+export type TokenSource = 'header' | 'cookie';
+export interface FoundToken {
+    readonly token: string;
+    readonly source: TokenSource;
+}
+/**
+ * Read one cookie out of a `Cookie` header value.
+ *
+ * ⚠️ HAND-PARSED, AND SMALL ON PURPOSE. A cookie library would bring parsing of
+ *   attributes (Path, SameSite, Max-Age) that only ever appear on `Set-Cookie`, which is
+ *   the response side. Requests carry a bare `name=value; name=value` list, and that is
+ *   all this reads.
+ * ⚠️ A JWT is base64url and contains no `;` or `=`-in-value ambiguity beyond padding, but
+ *   this still splits on the FIRST `=` only — a value containing `=` (base64 padding) is
+ *   otherwise truncated mid-token, which fails verification with a signature error and
+ *   sends you hunting in the wrong place.
+ */
+export declare function readCookie(header: string | null, name: string): string | undefined;
+/**
+ * The Access token on `request`, or `undefined` when it carries none.
+ *
+ * ⛔ RETURNS THE CANDIDATE UNVERIFIED. Every caller must hand the result to
+ *   `verifyAccessToken`; nothing about being present in a header makes a token valid.
+ */
+export declare function accessToken(request: Request): FoundToken | undefined;
+//# sourceMappingURL=token.d.ts.map

package/dist/access-auth/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/access-auth/token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,uEAAuE;AACvE,eAAO,MAAM,aAAa,4BAA4B,CAAC;AAEvD,6CAA6C;AAC7C,eAAO,MAAM,aAAa,qBAAqB,CAAC;AAEhD,qFAAqF;AACrF,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE9C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAalF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAQpE"}

package/dist/access.d.ts

@@ -3,6 +3,16 @@ export interface AccessOptions {
     readonly teamDomain: string;
     /** The application's AUD tag, from Zero Trust → Access → Applications. */
     readonly audience: string;
+    /**
+     * Reject a token older than this, by `iat`. Seconds, or a jose duration like `'8h'`.
+     * ★ OPT-IN BECAUSE `exp` ALREADY BOUNDS THE TOKEN. Access sets the session lifetime in
+     *   `exp`, so this is a second, shorter leash for a surface that wants one — not a
+     *   missing check. ⚠️ Setting it below the Access session duration logs users out
+     *   mid-session with a 401 they cannot fix by retrying.
+     */
+    readonly maxTokenAge?: string | number;
+    /** Seconds of clock skew tolerated on `exp`/`nbf`/`iat`. jose's default is 0. */
+    readonly clockTolerance?: string | number;
 }
 /** The subset of Access claims worth depending on. */
 export interface AccessIdentity {
@@ -20,4 +30,18 @@ export interface AccessIdentity {
  *     want a soft path catch it explicitly.
  */
 export declare function verifyAccessJwt(request: Request, options: AccessOptions): Promise<AccessIdentity>;
+/**
+ * Verify a token string that the caller has already located, returning the identity.
+ *
+ * ★ EXTRACTED SO THERE IS EXACTLY ONE VERIFICATION, NOT TWO. `verifyAccessJwt` reads the
+ *   header; the forward_auth handler (`@homeflare/cloudflare/access-auth`) also accepts
+ *   the `CF_Authorization` cookie, because Cloudflare's own documentation says the cookie
+ *   "is not guaranteed to be passed" and the reverse is true too — a request that arrives
+ *   through a proxy hop may carry one and not the other. Both funnel here, so a fix to the
+ *   checks below cannot land on one path and miss the other.
+ *
+ * ⛔ THROWS ON EVERY FAILURE, exactly like `verifyAccessJwt`. Same reasoning: a boolean a
+ *   caller forgets to test is an open door.
+ */
+export declare function verifyAccessToken(token: string, options: AccessOptions): Promise<AccessIdentity>;
 //# sourceMappingURL=access.d.ts.map

package/dist/access.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACpD;AA2BD;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,cAAc,CAAC,CAczB"}
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvC,iFAAiF;IACjF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3C;AAED,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACpD;AA2BD;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,cAAc,CAAC,CAKzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,cAAc,CAAC,CAiBzB"}

package/dist/index.d.ts

@@ -20,7 +20,14 @@ export { VERSION } from './version.ts';
  *                         how to authenticate; RFC 9728 is what does.
  */
 export { accessIdentity, hasAccess, type AccessContext, type AccessIdentityInfo, } from './access-identity.ts';
-export { verifyAccessJwt, type AccessIdentity, type AccessOptions } from './access.ts';
+/**
+ * ⚠️ `verifyAccessToken` IS THE SAME CHECK WITH THE TOKEN ALREADY IN HAND — for a caller
+ *   that read it from somewhere other than the header (a cookie, a WebSocket subprotocol).
+ *   It is not a lighter variant: identical issuer, audience and expiry checks.
+ *   ★ Protecting a non-Worker origin behind a reverse proxy? `@homeflare/cloudflare/access-auth`
+ *     is the ready-made `forward_auth` handler; you do not need to assemble one from these.
+ */
+export { verifyAccessJwt, verifyAccessToken, type AccessIdentity, type AccessOptions, } from './access.ts';
 export { protectedResourceMetadata, serveMcpMetadata, unauthorizedResponse, wellKnownPath, type McpMetadataOptions, type ProtectedResourceMetadata, } from './mcp-metadata.ts';
 export { log, type LogFields, type Logger } from './log.ts';
 export { BREAKER_COOLDOWN_MS, breakered } from './jwks-breaker.ts';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC;;;;;;;;;;GAUG;AACH,OAAO,EACL,cAAc,EACd,SAAS,EACT,KAAK,aAAa,EAClB,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACvF,OAAO,EACL,yBAAyB,EACzB,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,GAC/B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,GAAG,EAAE,KAAK,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC;;;;;;;;;;GAUG;AACH,OAAO,EACL,cAAc,EACd,SAAS,EACT,KAAK,aAAa,EAClB,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B;;;;;;GAMG;AACH,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,yBAAyB,EACzB,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,GAC/B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,GAAG,EAAE,KAAK,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var VERSION = "0.3.1";
+var VERSION = "0.3.2";
 // src/access-identity.ts
 function hasAccess(ctx) {
   return ctx.access !== undefined;
@@ -63,9 +63,14 @@ async function verifyAccessJwt(request, options) {
   const token = request.headers.get(ACCESS_HEADER);
   if (token === null)
     throw new Error("access: no Cf-Access-Jwt-Assertion header");
+  return await verifyAccessToken(token, options);
+}
+async function verifyAccessToken(token, options) {
   const { payload } = await jwtVerify(token, keysFor(options.teamDomain), {
     issuer: options.teamDomain,
-    audience: options.audience
+    audience: options.audience,
+    ...options.maxTokenAge === undefined ? {} : { maxTokenAge: options.maxTokenAge },
+    ...options.clockTolerance === undefined ? {} : { clockTolerance: options.clockTolerance }
   });
   return {
     email: typeof payload["email"] === "string" ? payload["email"] : undefined,
@@ -140,8 +145,9 @@ export {
   serveMcpMetadata,
   unauthorizedResponse,
   verifyAccessJwt,
+  verifyAccessToken,
   wellKnownPath
 };
 
-//# debugId=EFB6530E524D859F64756E2164756E21
+//# debugId=CE0760F85A084BBF64756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -2,14 +2,14 @@
   "version": 3,
   "sources": ["../src/version.ts", "../src/access-identity.ts", "../src/access.ts", "../src/jwks-breaker.ts", "../src/mcp-metadata.ts", "../src/log.ts"],
   "sourcesContent": [
-    "// ⛔ GENERATED by scripts/sync-versions.ts — do not edit. Source: package.json.\nexport const VERSION: string = '0.3.1';\n",
+    "// ⛔ GENERATED by scripts/sync-versions.ts — do not edit. Source: package.json.\nexport const VERSION: string = '0.3.2';\n",
     "/**\n * Access identity WITHOUT parsing a JWT — the path Cloudflare added in August 2026.\n *\n * ★ WHEN ACCESS PROTECTS A WORKER, the edge attaches the authenticated identity to the\n *   execution context: `ctx.access.getIdentity()` returns email, name and groups with no\n *   token handling at all. Verifying the assertion yourself is the OLDER path, and it is\n *   still correct for origins that have no `ctx.access` — see `verifyAccessJwt`.\n *\n * ⛔ THIS IS NOT A WEAKER CHECK. The edge has already refused the request if it did not\n *   pass the Access policy; `ctx.access` exists only on requests that passed. Parsing the\n *   JWT again re-verifies something the platform has already enforced.\n *\n * ⚠️ `ctx.access` IS NOT PROPAGATED THROUGH SERVICE BINDINGS OR RPC. A downstream Worker\n *   reached by binding sees `undefined`, even though the caller was authenticated — so a\n *   service-bound Worker that needs identity must be told, or must sit behind its own\n *   Access application. Measured from Cloudflare's own documentation, 2026-08-14.\n *\n * ★ GROUPS COME FROM get-identity, NOT FROM THE TOKEN. Cloudflare trims the JWT's `custom`\n *   claim at roughly 1 KB, silently, so group membership read from a token can be\n *   incomplete — which is an authorization bug that only appears for users in many groups.\n */\n\n/** What `ctx.access.getIdentity()` resolves. Narrowed to the fields worth depending on. */\nexport interface AccessIdentityInfo {\n  readonly email: string | undefined;\n  readonly name: string | undefined;\n  readonly groups: readonly string[];\n  /** Everything else the platform returned, for callers needing a field not named here. */\n  readonly raw: Readonly<Record<string, unknown>>;\n}\n\n/**\n * The slice of the execution context this module uses.\n * ⚠️ Declared structurally rather than imported from `@cloudflare/workers-types`: this\n *   package should not force a types dependency on a consumer for one optional field.\n */\nexport interface AccessContext {\n  readonly access?: {\n    readonly aud?: string;\n    readonly getIdentity: () => Promise<Record<string, unknown> | null | undefined>;\n  };\n}\n\n/** True when the request reached this Worker through Cloudflare Access. */\nexport function hasAccess(ctx: AccessContext): boolean {\n  return ctx.access !== undefined;\n}\n\n/**\n * The authenticated identity, or `undefined` when the request did not come through Access.\n *\n * ```ts\n * const who = await accessIdentity(ctx);\n * if (who === undefined) return new Response('Access did not run', { status: 401 });\n * ```\n *\n * ⛔ RETURNS undefined RATHER THAN THROWING, deliberately — unlike `verifyAccessJwt`. A\n *   Worker may legitimately serve both protected and open routes, so \"no Access here\" is\n *   a branch rather than a failure. The caller decides what an unauthenticated request\n *   means, and that decision is visible at the call site.\n */\nexport async function accessIdentity(ctx: AccessContext): Promise<AccessIdentityInfo | undefined> {\n  const access = ctx.access;\n  if (access === undefined) return undefined;\n\n  const raw = (await access.getIdentity()) ?? {};\n  const groups = raw['groups'];\n\n  return {\n    email: typeof raw['email'] === 'string' ? raw['email'] : undefined,\n    name: typeof raw['name'] === 'string' ? raw['name'] : undefined,\n    // ⚠️ Always an array, never undefined: a caller writing `groups.includes(…)` on a\n    //   missing field would throw at exactly the moment authorization is being decided.\n    groups: Array.isArray(groups) ? groups.filter((g): g is string => typeof g === 'string') : [],\n    raw,\n  };\n}\n",
-    "/**\n * Cloudflare Access JWT verification.\n *\n * ★ WHY jose AND NOT A HAND-ROLLED VERIFY. Signature verification is the one place where\n *   a subtle bug is silent and total: a check that never fails looks identical to a\n *   check that always passes. jose handles JWKS fetching, `kid` matching and key\n *   rotation, and it is widely deployed. This file is the Access-specific\n *   wiring around it, nothing more.\n *\n * ⚠️ THE TRAP THIS CLOSES. Cloudflare's own example does `jwtVerify(...)` inline in the\n *   handler, which builds a NEW remote JWKS on every request — an outbound fetch per\n *   request, and a thundering herd on the certs endpoint under load. The cache below is\n *   keyed by team domain and lives for the isolate's lifetime.\n *\n * ⛔ NEVER SKIP `audience`. Any Access app in your account produces a JWT this team\n *   domain will happily verify; the AUD tag is the only thing that says the token was\n *   minted for THIS app. Verifying issuer alone accepts tokens from a neighbouring app.\n *\n * Docs: developers.cloudflare.com/cloudflare-one/identity/authorization-cookie/validating-json/\n */\nimport { createRemoteJWKSet, customFetch, jwtVerify } from 'jose';\nimport { breakered } from './jwks-breaker.ts';\n\n/** The header Access puts the token in. Lowercase — Headers.get is case-insensitive. */\nconst ACCESS_HEADER = 'cf-access-jwt-assertion';\n\nexport interface AccessOptions {\n  /** `https://<team>.cloudflareaccess.com` — the issuer, and the JWKS host. */\n  readonly teamDomain: string;\n  /** The application's AUD tag, from Zero Trust → Access → Applications. */\n  readonly audience: string;\n}\n\n/** The subset of Access claims worth depending on. */\nexport interface AccessIdentity {\n  readonly email: string | undefined;\n  readonly sub: string | undefined;\n  /** Everything else, for callers that need a claim this interface does not name. */\n  readonly claims: Readonly<Record<string, unknown>>;\n}\n\n/**\n * One JWKS per team domain, reused for the isolate's life.\n * ⚠️ Module scope is per-isolate on workerd, not per-request and not global. That is\n *   exactly the right lifetime here: long enough to amortise the fetch, short enough\n *   that a rotated key is picked up when the isolate recycles. jose also refreshes on\n *   an unknown `kid`.\n */\nconst jwks = new Map<string, ReturnType<typeof createRemoteJWKSet>>();\n\nfunction keysFor(teamDomain: string): ReturnType<typeof createRemoteJWKSet> {\n  const existing = jwks.get(teamDomain);\n  if (existing !== undefined) return existing;\n\n  // ⛔ THE BREAKER IS NOT OPTIONAL. jose refetches on EVERY call while an endpoint is\n  //   down — measured on 6.2.12: 5 verifications against a 404ing certs endpoint made 5\n  //   outbound fetches, and no combination of cacheMaxAge or cooldownDuration changes it.\n  //   Without this, a Cloudflare Access outage turns every inbound request into an\n  //   outbound one. See jwks-breaker.ts.\n  const created = createRemoteJWKSet(new URL(`${teamDomain}/cdn-cgi/access/certs`), {\n    [customFetch]: breakered(),\n  });\n  jwks.set(teamDomain, created);\n  return created;\n}\n\n/**\n * Verify the Access JWT on `request`, returning the identity it asserts.\n *\n * ⛔ THROWS ON EVERY FAILURE — missing header, bad signature, wrong audience, expired.\n *   ★ Deliberately not a boolean or a null: an `if (!ok)` that a caller forgets to write\n *     is an open door, whereas an unhandled throw is a 500 and a log line. Callers that\n *     want a soft path catch it explicitly.\n */\nexport async function verifyAccessJwt(\n  request: Request,\n  options: AccessOptions,\n): Promise<AccessIdentity> {\n  const token = request.headers.get(ACCESS_HEADER);\n  if (token === null) throw new Error('access: no Cf-Access-Jwt-Assertion header');\n\n  const { payload } = await jwtVerify(token, keysFor(options.teamDomain), {\n    issuer: options.teamDomain,\n    audience: options.audience,\n  });\n\n  return {\n    email: typeof payload['email'] === 'string' ? payload['email'] : undefined,\n    sub: payload.sub,\n    claims: payload,\n  };\n}\n",
+    "/**\n * Cloudflare Access JWT verification.\n *\n * ★ WHY jose AND NOT A HAND-ROLLED VERIFY. Signature verification is the one place where\n *   a subtle bug is silent and total: a check that never fails looks identical to a\n *   check that always passes. jose handles JWKS fetching, `kid` matching and key\n *   rotation, and it is widely deployed. This file is the Access-specific\n *   wiring around it, nothing more.\n *\n * ⚠️ THE TRAP THIS CLOSES. Cloudflare's own example does `jwtVerify(...)` inline in the\n *   handler, which builds a NEW remote JWKS on every request — an outbound fetch per\n *   request, and a thundering herd on the certs endpoint under load. The cache below is\n *   keyed by team domain and lives for the isolate's lifetime.\n *\n * ⛔ NEVER SKIP `audience`. Any Access app in your account produces a JWT this team\n *   domain will happily verify; the AUD tag is the only thing that says the token was\n *   minted for THIS app. Verifying issuer alone accepts tokens from a neighbouring app.\n *\n * Docs: developers.cloudflare.com/cloudflare-one/identity/authorization-cookie/validating-json/\n */\nimport { createRemoteJWKSet, customFetch, jwtVerify } from 'jose';\nimport { breakered } from './jwks-breaker.ts';\n\n/** The header Access puts the token in. Lowercase — Headers.get is case-insensitive. */\nconst ACCESS_HEADER = 'cf-access-jwt-assertion';\n\nexport interface AccessOptions {\n  /** `https://<team>.cloudflareaccess.com` — the issuer, and the JWKS host. */\n  readonly teamDomain: string;\n  /** The application's AUD tag, from Zero Trust → Access → Applications. */\n  readonly audience: string;\n  /**\n   * Reject a token older than this, by `iat`. Seconds, or a jose duration like `'8h'`.\n   * ★ OPT-IN BECAUSE `exp` ALREADY BOUNDS THE TOKEN. Access sets the session lifetime in\n   *   `exp`, so this is a second, shorter leash for a surface that wants one — not a\n   *   missing check. ⚠️ Setting it below the Access session duration logs users out\n   *   mid-session with a 401 they cannot fix by retrying.\n   */\n  readonly maxTokenAge?: string | number;\n  /** Seconds of clock skew tolerated on `exp`/`nbf`/`iat`. jose's default is 0. */\n  readonly clockTolerance?: string | number;\n}\n\n/** The subset of Access claims worth depending on. */\nexport interface AccessIdentity {\n  readonly email: string | undefined;\n  readonly sub: string | undefined;\n  /** Everything else, for callers that need a claim this interface does not name. */\n  readonly claims: Readonly<Record<string, unknown>>;\n}\n\n/**\n * One JWKS per team domain, reused for the isolate's life.\n * ⚠️ Module scope is per-isolate on workerd, not per-request and not global. That is\n *   exactly the right lifetime here: long enough to amortise the fetch, short enough\n *   that a rotated key is picked up when the isolate recycles. jose also refreshes on\n *   an unknown `kid`.\n */\nconst jwks = new Map<string, ReturnType<typeof createRemoteJWKSet>>();\n\nfunction keysFor(teamDomain: string): ReturnType<typeof createRemoteJWKSet> {\n  const existing = jwks.get(teamDomain);\n  if (existing !== undefined) return existing;\n\n  // ⛔ THE BREAKER IS NOT OPTIONAL. jose refetches on EVERY call while an endpoint is\n  //   down — measured on 6.2.12: 5 verifications against a 404ing certs endpoint made 5\n  //   outbound fetches, and no combination of cacheMaxAge or cooldownDuration changes it.\n  //   Without this, a Cloudflare Access outage turns every inbound request into an\n  //   outbound one. See jwks-breaker.ts.\n  const created = createRemoteJWKSet(new URL(`${teamDomain}/cdn-cgi/access/certs`), {\n    [customFetch]: breakered(),\n  });\n  jwks.set(teamDomain, created);\n  return created;\n}\n\n/**\n * Verify the Access JWT on `request`, returning the identity it asserts.\n *\n * ⛔ THROWS ON EVERY FAILURE — missing header, bad signature, wrong audience, expired.\n *   ★ Deliberately not a boolean or a null: an `if (!ok)` that a caller forgets to write\n *     is an open door, whereas an unhandled throw is a 500 and a log line. Callers that\n *     want a soft path catch it explicitly.\n */\nexport async function verifyAccessJwt(\n  request: Request,\n  options: AccessOptions,\n): Promise<AccessIdentity> {\n  const token = request.headers.get(ACCESS_HEADER);\n  if (token === null) throw new Error('access: no Cf-Access-Jwt-Assertion header');\n\n  return await verifyAccessToken(token, options);\n}\n\n/**\n * Verify a token string that the caller has already located, returning the identity.\n *\n * ★ EXTRACTED SO THERE IS EXACTLY ONE VERIFICATION, NOT TWO. `verifyAccessJwt` reads the\n *   header; the forward_auth handler (`@homeflare/cloudflare/access-auth`) also accepts\n *   the `CF_Authorization` cookie, because Cloudflare's own documentation says the cookie\n *   \"is not guaranteed to be passed\" and the reverse is true too — a request that arrives\n *   through a proxy hop may carry one and not the other. Both funnel here, so a fix to the\n *   checks below cannot land on one path and miss the other.\n *\n * ⛔ THROWS ON EVERY FAILURE, exactly like `verifyAccessJwt`. Same reasoning: a boolean a\n *   caller forgets to test is an open door.\n */\nexport async function verifyAccessToken(\n  token: string,\n  options: AccessOptions,\n): Promise<AccessIdentity> {\n  const { payload } = await jwtVerify(token, keysFor(options.teamDomain), {\n    issuer: options.teamDomain,\n    audience: options.audience,\n    // ⛔ SPREAD, NOT `maxTokenAge: options.maxTokenAge`. `exactOptionalPropertyTypes` is on,\n    //   and passing an explicit `undefined` is not the same as omitting the key — jose\n    //   reads `'maxTokenAge' in options`, so the undefined form would enable the check\n    //   with an undefined bound.\n    ...(options.maxTokenAge === undefined ? {} : { maxTokenAge: options.maxTokenAge }),\n    ...(options.clockTolerance === undefined ? {} : { clockTolerance: options.clockTolerance }),\n  });\n\n  return {\n    email: typeof payload['email'] === 'string' ? payload['email'] : undefined,\n    sub: payload.sub,\n    claims: payload,\n  };\n}\n",
     "/**\n * A circuit breaker for JWKS fetches, installed at jose's own `customFetch` seam.\n *\n * ⛔ THE AMPLIFICATION THIS CLOSES, MEASURED ON jose 6.2.12 — the version this package\n *   pins, not an old one:\n *\n *       5 verifications of a well-formed token, certs endpoint 404ing → 5 outbound fetches\n *\n *   jose assigns `jwksTimestamp` only inside the `.then()` of a SUCCESSFUL fetch\n *   (`dist/webapi/jwks/remote.js`, line 58). While an endpoint is down, `local` stays\n *   undefined, so `if (!local || !isFreshFor(jwksTimestamp, cacheMaxAge)) await reload()`\n *   runs on EVERY call. A down Access endpoint therefore turns every inbound request into\n *   an outbound fetch, indefinitely.\n *\n * ★ NOT A REIMPLEMENTATION. `customFetch` is jose's exported, documented extension point;\n *   jose keeps doing the caching, cooldown, `kid` matching and verification. This adds the\n *   one thing it does not do — remember that a fetch FAILED.\n *   ⚠️ Measured first: neither `cacheMaxAge: Infinity` nor `cooldownDuration` nor both\n *     together change the count. It is 5 fetches in every configuration, so this is not a\n *     matter of configuring jose correctly.\n *\n * ⛔ THE BREAKER STORES PLAIN VALUES ONLY — a timestamp and an Error. NEVER a Response, a\n *   body stream, or a promise of one.\n *   🔴 On workerd, a Response and its body belong to the IoContext of the request that\n *     created them, and another request touching either throws:\n *         Cannot perform I/O on behalf of a different request.\n *     Caching a Response across requests would therefore turn a VALID token into a flat\n *     401 for every caller but the first — an outage strictly worse than the amplification\n *     it was meant to fix. Timestamps and Errors cross requests legally; I/O objects do not.\n */\n\nimport type { FetchImplementation } from 'jose';\n\n/** How long a URL stays latched open after a failed probe. */\nexport const BREAKER_COOLDOWN_MS = 30_000;\n\ntype Failure = { readonly at: number; readonly error: Error };\n\n/**\n * ⚠️ Module scope is PER ISOLATE on workerd, which is the right lifetime: long enough to\n *   stop the storm, short enough that a recycled isolate retries a recovered endpoint.\n */\nconst failures = new Map<string, Failure>();\n\n/** Visible for testing. ⛔ Not exported from the package — resetting it in production\n *  would discard exactly the memory this exists to keep. */\nexport function resetBreaker(): void {\n  failures.clear();\n}\n\n/**\n * Wrap a fetch so a failing URL is not retried for `cooldownMs`.\n *\n * ★ FAILURE IS COUNTED AT THE SEAM, not inferred from an error class further up. jose\n *   throws `JWKSNoMatchingKey` as a NORMAL answer from a perfectly healthy endpoint — a\n *   token signed with a rotated key does that — so treating it as a fault would latch a\n *   working endpoint closed and reject every valid token for 30 seconds.\n */\nexport function breakered(\n  inner: FetchImplementation = (url, options) => fetch(url, options),\n  cooldownMs: number = BREAKER_COOLDOWN_MS,\n): FetchImplementation {\n  // ⚠️ jose's OWN FetchImplementation, not `typeof fetch`. It is narrower — a string URL\n  //   and a fixed options shape — and using the global type instead fails to typecheck on\n  //   `preconnect`, a property of the platform fetch that no seam implementation has.\n  return async (url, options) => {\n    const open = failures.get(url);\n\n    if (open !== undefined && Date.now() - open.at < cooldownMs) {\n      // ⚠️ Rethrow the ORIGINAL error, not a generic one: the first failure says whether\n      //   this was a 404, a TLS problem or a timeout, and that is what an operator needs.\n      //   A \"circuit open\" message alone hides the actual fault.\n      throw open.error;\n    }\n\n    try {\n      const response = await inner(url, options);\n\n      // ⛔ A non-200 is a failure here. jose requires 200 with a JSON body; a 404 or a 502\n      //   is exactly the down-endpoint case, and it does NOT throw on its own.\n      if (!response.ok) {\n        const error = new Error(`JWKS endpoint answered ${String(response.status)}: ${url}`);\n        failures.set(url, { at: Date.now(), error });\n        throw error;\n      }\n\n      failures.delete(url);\n      return response;\n    } catch (cause) {\n      const error = cause instanceof Error ? cause : new Error(String(cause));\n      // `set` is idempotent here — a second failure simply restarts the cooldown.\n      failures.set(url, { at: Date.now(), error });\n      throw error;\n    }\n  };\n}\n",
     "/**\n * RFC 9728 discovery for an MCP server — the third auth path, and the one a client\n * actually needs to find its way in.\n *\n * ★ THE MCP SPEC REQUIRES THIS. A server MUST publish OAuth 2.0 Protected Resource\n *   Metadata, and a client MUST use it to discover the authorization server. Without it a\n *   client cannot begin the flow, and has to be told endpoints out of band — which is\n *   exactly the gap that leaves real servers (Atlassian's, measured 2026) undiscoverable\n *   by spec-compliant clients.\n *\n * ⛔ TWO HALVES, AND ONE ALONE DOES NOT WORK:\n *     1. `GET /.well-known/oauth-protected-resource` returns the metadata document.\n *     2. A 401 carries `WWW-Authenticate` naming that document's URL.\n *   A client may start from either. Publishing the document but answering a bare 401 leaves\n *   clients that follow the header — the common path — with nowhere to go.\n *\n * ⚠️ THE WELL-KNOWN URL IS DERIVED FROM THE RESOURCE URL, NOT CHOSEN. That derivation is a\n *   security property, not a convention: it stops an attacker publishing metadata that\n *   claims to describe a resource it has no authority over.\n *\n * ★ NO I/O AT MODULE SCOPE. Everything here is pure, because a Worker cannot make network\n *   calls during module initialization — a metadata helper that fetched at import would\n *   fail on the edge and nowhere else.\n */\n\n/** The subset of RFC 9728 an MCP server needs. Extra fields pass through untouched. */\nexport interface ProtectedResourceMetadata {\n  /** The resource's own canonical URL. ⛔ Must match what clients call, exactly. */\n  readonly resource: string;\n  /** Authorization servers that issue tokens for it. */\n  readonly authorization_servers: readonly string[];\n  readonly scopes_supported?: readonly string[];\n  readonly bearer_methods_supported?: readonly string[];\n  readonly resource_documentation?: string;\n}\n\nexport interface McpMetadataOptions {\n  /** The MCP endpoint clients call, e.g. `https://mcp.example.com/mcp`. */\n  readonly resource: string;\n  /**\n   * The issuer. For Cloudflare's managed OAuth this is your team domain,\n   * `https://<team>.cloudflareaccess.com`.\n   */\n  readonly authorizationServer: string;\n  readonly scopes?: readonly string[];\n  readonly documentation?: string;\n}\n\n/**\n * The well-known path for a resource URL, derived per RFC 9728.\n *\n * ⚠️ A RESOURCE WITH A PATH KEEPS IT, AFTER the well-known segment:\n *     https://example.com/mcp → /.well-known/oauth-protected-resource/mcp\n *   Serving it at the root instead is the mistake that makes a multi-resource server\n *   advertise one resource's metadata for all of them.\n */\nexport function wellKnownPath(resource: string): string {\n  const path = new URL(resource).pathname.replace(/\\/+$/, '');\n  return path === ''\n    ? '/.well-known/oauth-protected-resource'\n    : `/.well-known/oauth-protected-resource${path}`;\n}\n\n/** Build the metadata document. Pure — no I/O, safe at module scope. */\nexport function protectedResourceMetadata(options: McpMetadataOptions): ProtectedResourceMetadata {\n  return {\n    resource: options.resource,\n    authorization_servers: [options.authorizationServer],\n    // ⚠️ `header` only. A bearer token in a query string lands in access logs and in\n    //   Referer, and RFC 6750 discourages it for exactly that reason.\n    bearer_methods_supported: ['header'],\n    ...(options.scopes === undefined ? {} : { scopes_supported: options.scopes }),\n    ...(options.documentation === undefined\n      ? {}\n      : { resource_documentation: options.documentation }),\n  };\n}\n\n/**\n * The 401 an unauthenticated MCP request must receive.\n *\n * ⛔ THE `resource_metadata` PARAMETER IS THE WHOLE POINT. A bare `WWW-Authenticate:\n *   Bearer` tells a client it needs a token but not where to get one, so discovery dead-ends\n *   and the client falls back to hardcoded endpoints — or fails.\n */\nexport function unauthorizedResponse(options: McpMetadataOptions): Response {\n  const metadataUrl = new URL(wellKnownPath(options.resource), options.resource).href;\n\n  return new Response(JSON.stringify({ error: 'unauthorized' }), {\n    status: 401,\n    headers: {\n      'content-type': 'application/json',\n      'www-authenticate': `Bearer resource_metadata=\"${metadataUrl}\"`,\n    },\n  });\n}\n\n/**\n * Serve the metadata document when the request is for it, otherwise `undefined`.\n *\n * ```ts\n * const discovery = serveMcpMetadata(request, { resource, authorizationServer });\n * if (discovery !== undefined) return discovery;\n * ```\n *\n * ⚠️ CORS IS OPEN HERE ON PURPOSE. Discovery metadata is public by definition — a client\n *   must read it BEFORE it has a token, often from a browser origin the server has never\n *   seen. Locking it down breaks the flow it exists to start.\n */\nexport function serveMcpMetadata(\n  request: Request,\n  options: McpMetadataOptions,\n): Response | undefined {\n  const url = new URL(request.url);\n  if (url.pathname !== wellKnownPath(options.resource)) return undefined;\n\n  return new Response(JSON.stringify(protectedResourceMetadata(options), null, 2), {\n    headers: {\n      'content-type': 'application/json',\n      'access-control-allow-origin': '*',\n      'cache-control': 'public, max-age=3600',\n    },\n  });\n}\n",
     "/**\n * Structured logging for Workers.\n *\n * ★ WHY NO LOGGING LIBRARY. Cloudflare Workers Logs parses `console.log` output as JSON\n *   natively and indexes every field, with unlimited cardinality — so a JSON object on\n *   console IS the structured logging integration. pino is Node-shaped (streams, worker\n *   threads) and needs a wrapper on workerd; `pino-pretty` does not work with wrangler\n *   at all (workers-sdk#6841). Adding a dependency here would buy formatting we do not\n *   want and cost bundle size on a hot path.\n *   Docs: developers.cloudflare.com/workers/observability/logs/workers-logs/\n *\n * ⛔ NEVER LOG A CREDENTIAL. There is no redaction layer here and deliberately so — a\n *   redactor implies it is safe to pass secrets in, and then quietly misses one.\n */\n\n/** Anything JSON-serialisable. Workers Logs indexes each key as its own field. */\nexport type LogFields = Readonly<Record<string, unknown>>;\n\nexport interface Logger {\n  readonly debug: (message: string, fields?: LogFields) => void;\n  readonly info: (message: string, fields?: LogFields) => void;\n  readonly warn: (message: string, fields?: LogFields) => void;\n  readonly error: (message: string, fields?: LogFields) => void;\n  /** Returns a logger that merges `bound` into every subsequent line. */\n  readonly with: (bound: LogFields) => Logger;\n}\n\ntype Level = 'debug' | 'info' | 'warn' | 'error';\n\nfunction emit(level: Level, message: string, fields: LogFields): void {\n  // ⚠️ ONE OBJECT, NOT (message, fields). console.log with several arguments is\n  //   stringified and concatenated by the runtime, which destroys the structure Workers\n  //   Logs would otherwise index — the symptom is a `message` field containing your\n  //   whole payload as text, unqueryable.\n  const line = { level, message, ...fields };\n\n  if (level === 'error') console.error(line);\n  else if (level === 'warn') console.warn(line);\n  else console.log(line);\n}\n\nfunction make(bound: LogFields): Logger {\n  return {\n    debug: (message, fields) => emit('debug', message, { ...bound, ...fields }),\n    info: (message, fields) => emit('info', message, { ...bound, ...fields }),\n    warn: (message, fields) => emit('warn', message, { ...bound, ...fields }),\n    error: (message, fields) => emit('error', message, { ...bound, ...fields }),\n    with: (extra) => make({ ...bound, ...extra }),\n  };\n}\n\n/**\n * The root logger. Bind request-scoped context rather than passing it every call:\n *\n *     const requestLog = log.with({ requestId, path: url.pathname });\n *     requestLog.info('handled', { status, ms });\n */\nexport const log: Logger = make({});\n"
   ],
-  "mappings": ";AACO,IAAM,UAAkB;;AC2CxB,SAAS,SAAS,CAAC,KAA6B;AAAA,EACrD,OAAO,IAAI,WAAW;AAAA;AAgBxB,eAAsB,cAAc,CAAC,KAA6D;AAAA,EAChG,MAAM,SAAS,IAAI;AAAA,EACnB,IAAI,WAAW;AAAA,IAAW;AAAA,EAE1B,MAAM,MAAO,MAAM,OAAO,YAAY,KAAM,CAAC;AAAA,EAC7C,MAAM,SAAS,IAAI;AAAA,EAEnB,OAAO;AAAA,IACL,OAAO,OAAO,IAAI,aAAa,WAAW,IAAI,WAAW;AAAA,IACzD,MAAM,OAAO,IAAI,YAAY,WAAW,IAAI,UAAU;AAAA,IAGtD,QAAQ,MAAM,QAAQ,MAAM,IAAI,OAAO,OAAO,CAAC,MAAmB,OAAO,MAAM,QAAQ,IAAI,CAAC;AAAA,IAC5F;AAAA,EACF;AAAA;;ACvDF;;;ACcO,IAAM,sBAAsB;AAQnC,IAAM,WAAW,IAAI;AAgBd,SAAS,SAAS,CACvB,QAA6B,CAAC,KAAK,YAAY,MAAM,KAAK,OAAO,GACjE,aAAqB,qBACA;AAAA,EAIrB,OAAO,OAAO,KAAK,YAAY;AAAA,IAC7B,MAAM,OAAO,SAAS,IAAI,GAAG;AAAA,IAE7B,IAAI,SAAS,aAAa,KAAK,IAAI,IAAI,KAAK,KAAK,YAAY;AAAA,MAI3D,MAAM,KAAK;AAAA,IACb;AAAA,IAEA,IAAI;AAAA,MACF,MAAM,WAAW,MAAM,MAAM,KAAK,OAAO;AAAA,MAIzC,IAAI,CAAC,SAAS,IAAI;AAAA,QAChB,MAAM,QAAQ,IAAI,MAAM,0BAA0B,OAAO,SAAS,MAAM,MAAM,KAAK;AAAA,QACnF,SAAS,IAAI,KAAK,EAAE,IAAI,KAAK,IAAI,GAAG,MAAM,CAAC;AAAA,QAC3C,MAAM;AAAA,MACR;AAAA,MAEA,SAAS,OAAO,GAAG;AAAA,MACnB,OAAO;AAAA,MACP,OAAO,OAAO;AAAA,MACd,MAAM,QAAQ,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;AAAA,MAEtE,SAAS,IAAI,KAAK,EAAE,IAAI,KAAK,IAAI,GAAG,MAAM,CAAC;AAAA,MAC3C,MAAM;AAAA;AAAA;AAAA;;;ADpEZ,IAAM,gBAAgB;AAwBtB,IAAM,OAAO,IAAI;AAEjB,SAAS,OAAO,CAAC,YAA2D;AAAA,EAC1E,MAAM,WAAW,KAAK,IAAI,UAAU;AAAA,EACpC,IAAI,aAAa;AAAA,IAAW,OAAO;AAAA,EAOnC,MAAM,UAAU,mBAAmB,IAAI,IAAI,GAAG,iCAAiC,GAAG;AAAA,KAC/E,cAAc,UAAU;AAAA,EAC3B,CAAC;AAAA,EACD,KAAK,IAAI,YAAY,OAAO;AAAA,EAC5B,OAAO;AAAA;AAWT,eAAsB,eAAe,CACnC,SACA,SACyB;AAAA,EACzB,MAAM,QAAQ,QAAQ,QAAQ,IAAI,aAAa;AAAA,EAC/C,IAAI,UAAU;AAAA,IAAM,MAAM,IAAI,MAAM,2CAA2C;AAAA,EAE/E,QAAQ,YAAY,MAAM,UAAU,OAAO,QAAQ,QAAQ,UAAU,GAAG;AAAA,IACtE,QAAQ,QAAQ;AAAA,IAChB,UAAU,QAAQ;AAAA,EACpB,CAAC;AAAA,EAED,OAAO;AAAA,IACL,OAAO,OAAO,QAAQ,aAAa,WAAW,QAAQ,WAAW;AAAA,IACjE,KAAK,QAAQ;AAAA,IACb,QAAQ;AAAA,EACV;AAAA;;AElCK,SAAS,aAAa,CAAC,UAA0B;AAAA,EACtD,MAAM,OAAO,IAAI,IAAI,QAAQ,EAAE,SAAS,QAAQ,QAAQ,EAAE;AAAA,EAC1D,OAAO,SAAS,KACZ,0CACA,wCAAwC;AAAA;AAIvC,SAAS,yBAAyB,CAAC,SAAwD;AAAA,EAChG,OAAO;AAAA,IACL,UAAU,QAAQ;AAAA,IAClB,uBAAuB,CAAC,QAAQ,mBAAmB;AAAA,IAGnD,0BAA0B,CAAC,QAAQ;AAAA,OAC/B,QAAQ,WAAW,YAAY,CAAC,IAAI,EAAE,kBAAkB,QAAQ,OAAO;AAAA,OACvE,QAAQ,kBAAkB,YAC1B,CAAC,IACD,EAAE,wBAAwB,QAAQ,cAAc;AAAA,EACtD;AAAA;AAUK,SAAS,oBAAoB,CAAC,SAAuC;AAAA,EAC1E,MAAM,cAAc,IAAI,IAAI,cAAc,QAAQ,QAAQ,GAAG,QAAQ,QAAQ,EAAE;AAAA,EAE/E,OAAO,IAAI,SAAS,KAAK,UAAU,EAAE,OAAO,eAAe,CAAC,GAAG;AAAA,IAC7D,QAAQ;AAAA,IACR,SAAS;AAAA,MACP,gBAAgB;AAAA,MAChB,oBAAoB,6BAA6B;AAAA,IACnD;AAAA,EACF,CAAC;AAAA;AAeI,SAAS,gBAAgB,CAC9B,SACA,SACsB;AAAA,EACtB,MAAM,MAAM,IAAI,IAAI,QAAQ,GAAG;AAAA,EAC/B,IAAI,IAAI,aAAa,cAAc,QAAQ,QAAQ;AAAA,IAAG;AAAA,EAEtD,OAAO,IAAI,SAAS,KAAK,UAAU,0BAA0B,OAAO,GAAG,MAAM,CAAC,GAAG;AAAA,IAC/E,SAAS;AAAA,MACP,gBAAgB;AAAA,MAChB,+BAA+B;AAAA,MAC/B,iBAAiB;AAAA,IACnB;AAAA,EACF,CAAC;AAAA;;AC7FH,SAAS,IAAI,CAAC,OAAc,SAAiB,QAAyB;AAAA,EAKpE,MAAM,OAAO,EAAE,OAAO,YAAY,OAAO;AAAA,EAEzC,IAAI,UAAU;AAAA,IAAS,QAAQ,MAAM,IAAI;AAAA,EACpC,SAAI,UAAU;AAAA,IAAQ,QAAQ,KAAK,IAAI;AAAA,EACvC;AAAA,YAAQ,IAAI,IAAI;AAAA;AAGvB,SAAS,IAAI,CAAC,OAA0B;AAAA,EACtC,OAAO;AAAA,IACL,OAAO,CAAC,SAAS,WAAW,KAAK,SAAS,SAAS,KAAK,UAAU,OAAO,CAAC;AAAA,IAC1E,MAAM,CAAC,SAAS,WAAW,KAAK,QAAQ,SAAS,KAAK,UAAU,OAAO,CAAC;AAAA,IACxE,MAAM,CAAC,SAAS,WAAW,KAAK,QAAQ,SAAS,KAAK,UAAU,OAAO,CAAC;AAAA,IACxE,OAAO,CAAC,SAAS,WAAW,KAAK,SAAS,SAAS,KAAK,UAAU,OAAO,CAAC;AAAA,IAC1E,MAAM,CAAC,UAAU,KAAK,KAAK,UAAU,MAAM,CAAC;AAAA,EAC9C;AAAA;AASK,IAAM,MAAc,KAAK,CAAC,CAAC;",
-  "debugId": "EFB6530E524D859F64756E2164756E21",
+  "mappings": "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",
+  "debugId": "CE0760F85A084BBF64756E2164756E21",
   "names": []
 }

package/docs/access-auth.md

@@ -0,0 +1,139 @@
+# Access for a surface that is not a Worker — `@homeflare/cloudflare/access-auth`
+
+Cloudflare Access authenticates the caller at the edge and forwards a signed JWT. A Worker
+reads the identity from `ctx.access` and is done. **Anything else — a daemon on a host, a
+web UI behind a tunnel — has to verify that JWT itself**, and that is what this is: a
+`forward_auth` verifier a reverse proxy calls before it lets a request reach the upstream.
+
+```
+browser ─► Cloudflare Access ─► tunnel ─► Caddy ─┬─► verifier  (this package)
+                                                 └─► upstream  (only on 2xx)
+```
+
+## The trap: verifying the wrong AUD admits everyone
+
+⛔ **Every Access application in one account is signed by the same team keys.** A token
+minted for a different app of yours has a valid signature, a valid `iss`, and an unexpired
+`exp`. The `aud` claim is the _only_ thing that says the token was minted for **this**
+application.
+
+A verifier that checks the issuer and skips the audience therefore admits **every Access
+user of every app you run**. It does not look broken: you log in, it works, your colleagues
+log in, it works. It fails the day someone who was only ever given the staging dashboard
+opens the thing you thought was locked.
+
+So `audience` is required, it is fixed when the handler is constructed, and it is never read
+from the request. One handler per Access application — two apps mean two handlers.
+
+## Running it
+
+```ts
+import { accessForwardAuth } from '@homeflare/cloudflare/access-auth';
+
+const verify = accessForwardAuth({
+  teamDomain: 'https://example.cloudflareaccess.com', // no trailing slash
+  audience: process.env['ACCESS_AUD'] ?? '', // the app's AUD tag
+});
+
+Bun.serve({ hostname: '127.0.0.1', port: 9101, fetch: verify });
+```
+
+It is a plain `(Request) => Promise<Response>`, so Node's fetch adapters and workerd take it
+unchanged. Answers:
+
+| outcome                                             | status | upstream sees                    |
+| --------------------------------------------------- | ------ | -------------------------------- |
+| verified                                            | 204    | `X-Access-Email`, `X-Access-Sub` |
+| no token, bad signature, wrong `aud`/`iss`, expired | 401    | nothing — request stops          |
+| verified but refused by your `authorize`            | 403    | nothing — request stops          |
+| the team's JWKS endpoint is down                    | 401    | nothing — **fails closed**       |
+
+The refusal carries no body and no reason: an unauthenticated caller learns nothing. The
+reason goes to the log as a fixed enum (`no-token`, `invalid-token`, `jwks-unavailable`,
+`not-authorized`, `unexpected`) — `jwks-unavailable` is the one worth alerting on, because
+it is the only one that means _your_ system is broken rather than the caller's token.
+
+⛔ **The token is never logged**, at any level, whole or truncated. A logged token is a
+replayable session for the whole of its `exp`.
+
+## Wiring it into Caddy
+
+`@homeflare/alchemy/caddy` renders the block, so the fields that matter are not retyped:
+
+```ts
+import { accessForwardAuth as forwardAuth, caddyWithFile } from '@homeflare/alchemy/caddy';
+
+const caddyfile = `vnc.example.com {
+${forwardAuth({ verifier: '127.0.0.1:9101', body: ['reverse_proxy 127.0.0.1:6080'] })}
+}
+`;
+```
+
+which produces:
+
+```caddyfile
+vnc.example.com {
+	reverse_proxy 127.0.0.1:6080
+	forward_auth 127.0.0.1:9101 {
+		uri /access/verify
+		copy_headers {
+			X-Access-Email
+			X-Access-Sub
+		}
+	}
+}
+```
+
+### Why `copy_headers` is the security-critical line
+
+Caddy's `forward_auth` copies the listed headers **from the verifier's response onto the
+client's request**, then passes it upstream. It expands to roughly:
+
+```caddyfile
+@good status 2xx
+handle_response @good {
+	request_header X-Access-Email {rp.header.X-Access-Email}
+}
+```
+
+⚠️ **A client can send `X-Access-Email: admin@example.com` itself.** It is overwritten only
+because the verifier's 204 carries that header. Caddy's documentation does not promise what
+happens to a listed field the auth response omits — so this verifier **always emits every
+identity header on a 2xx, empty string included**, rather than depending on that. A token
+with no `email` claim yields `X-Access-Email: ` and the client's value is gone either way.
+
+★ The corollary: **the list in `copy_headers` and the headers the verifier sets must agree.**
+A header the verifier sets but Caddy does not copy never arrives. A header Caddy copies but
+the verifier never sets is the spoofing case above. `accessForwardAuth()` defaults both ends
+to the same two names for exactly that reason; if you rename them, rename them on both sides.
+
+### Bind everything to loopback
+
+⛔ **Verifying the JWT is worth nothing if the upstream is reachable directly.** The check
+lives in Caddy's request path; anything that can reach the upstream's port skips it entirely.
+Both the verifier and the upstream bind to `127.0.0.1`, and Caddy is the only way in.
+`accessForwardAuth()` refuses a verifier address that is not loopback or a unix socket — not
+because a routable verifier cannot work, but because one is almost always an accident.
+
+## Key rotation, caching and outages
+
+The JWKS is fetched once per team domain and reused; jose refetches when it meets an unknown
+`kid`, which is how a rotated-in key is picked up without a restart. A certs endpoint that is
+_down_ is latched open for 30s by the breaker in `jwks-breaker.ts` — without it, jose refetches
+on every verification while the endpoint is failing, turning every inbound request into an
+outbound one.
+
+⚠️ **An unknown `kid` is a bad token, not an outage.** A key the endpoint does not publish
+means a forgery or a long-rotated token, and it is classified as `invalid-token`. Filing it
+under `jwks-unavailable` would hide a forged token inside the alert that says Cloudflare is
+having a bad day.
+
+## What this does not do
+
+- **It does not replace the Access policy.** Access decides who may authenticate; this
+  decides that the caller actually did. Use `authorize` for an extra rule, not as the gate.
+- **It does not help a Worker.** Behind Access, a Worker has `ctx.access.getIdentity()` and
+  should use it — see `accessIdentity` in the package entry.
+- **It does not terminate anything.** If the protected surface speaks a protocol Caddy is
+  proxying as raw TCP, there is no HTTP request to carry a JWT and no place for this to run;
+  the surface needs an HTTP front (a websockify, a web UI) before Access can guard it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/cloudflare",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Cloudflare Workers helpers: Access identity, MCP OAuth metadata, and structured logging.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/cloudflare#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -13,6 +13,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "src",
     "README.md",
     "LICENSE"
@@ -24,6 +25,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./access-auth": {
+      "types": "./dist/access-auth/index.d.ts",
+      "default": "./dist/access-auth/index.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {

package/src/access-auth/handler.ts

@@ -0,0 +1,195 @@
+/**
+ * A Cloudflare Access verifier shaped for Caddy's `forward_auth`.
+ *
+ * ★ WHAT THIS ADDS, AND WHAT IT DELIBERATELY DOES NOT. The verification is
+ *   `verifyAccessToken` in `../access.ts` — jose, a cached remote JWKS, a circuit breaker.
+ *   This file is the HTTP shape around it: find the token, answer 2xx or 4xx, and hand the
+ *   identity to the upstream as headers. There is no second verifier here, on purpose; two
+ *   implementations of a signature check is how one of them silently stops checking.
+ *
+ * ⛔ FAIL CLOSED, ALWAYS. Every path that does not end in a verified identity returns a
+ *   non-2xx, including a JWKS endpoint that is down. Caddy grants access on 2xx and only
+ *   on 2xx, so an exception escaping this handler would become a 502 from Caddy — still
+ *   closed, but without a log line. Hence the catch-all.
+ *
+ * ⛔ NEVER LOG THE TOKEN. Not at debug, not in an error message, not truncated. A token in
+ *   a log file is a replayable session for the whole of its `exp`. `reason` below is a
+ *   fixed enum and the caught error contributes only its CLASS NAME — jose's messages are
+ *   safe today, but "safe today" is not a property worth betting a credential on.
+ *
+ * Guide, and the Caddyfile that calls this: docs/access-auth.md.
+ */
+import { type AccessIdentity, type AccessOptions, verifyAccessToken } from '../access.ts';
+import { type Logger, log } from '../log.ts';
+import { type TokenSource, accessToken } from './token.ts';
+
+/** Why a request was refused. A closed set, so it is safe to log and safe to alert on. */
+export type DenyReason =
+  | 'no-token'
+  | 'invalid-token'
+  | 'jwks-unavailable'
+  | 'not-authorized'
+  | 'unexpected';
+
+/** The headers the upstream receives on success. Values are always strings, never absent. */
+export interface IdentityHeaders {
+  /** @default 'X-Access-Email' */
+  readonly email?: string;
+  /** @default 'X-Access-Sub' */
+  readonly sub?: string;
+}
+
+export interface AccessForwardAuthOptions extends AccessOptions {
+  /** Rename the identity headers to match an upstream that expects its own names. */
+  readonly headers?: IdentityHeaders;
+  /**
+   * An extra check on an already-verified identity. `false` is a 403, not a 401.
+   * ⚠️ AUTHORIZATION, NOT AUTHENTICATION. The Access policy is the real gate; this is for
+   *   an upstream that additionally wants, say, one team. Do not use it to re-check `aud`.
+   */
+  readonly authorize?: (identity: AccessIdentity) => boolean | Promise<boolean>;
+  /** @default the package logger */
+  readonly logger?: Logger;
+}
+
+const DEFAULT_HEADERS = { email: 'X-Access-Email', sub: 'X-Access-Sub' } as const;
+
+/**
+ * ⛔ A JWKS FAILURE MUST NOT READ AS A BAD TOKEN. They need opposite responses from an
+ *   operator — rotate nothing versus page someone — and they are indistinguishable in the
+ *   caller's 401. jose surfaces the breaker's error as the `cause` of a JWKS error, so the
+ *   class names of both the error and its cause are checked.
+ */
+function reasonFor(error: unknown): DenyReason {
+  // ⚠️ WALK THE `cause` CHAIN. jose wraps a transport failure, so the interesting error is
+  //   rarely the outermost one — matching only on `error.name` reports every JWKS outage
+  //   as a bad token, which is the diagnosis that sends an operator to the wrong system.
+  for (let cur: unknown = error, hops = 0; cur instanceof Error && hops < 4; hops += 1) {
+    // The breaker in ../jwks-breaker.ts throws exactly this for a non-200 certs endpoint.
+    if (cur.message.includes('JWKS endpoint answered')) return 'jwks-unavailable';
+    // `JWKSTimeout` is jose's; a bare `TypeError` from the fetch seam is "network refused".
+    if (cur.name === 'JWKSTimeout' || cur.name === 'TypeError') return 'jwks-unavailable';
+    cur = cur.cause;
+  }
+
+  // ⛔ EVERYTHING ELSE IS A BAD TOKEN, INCLUDING `JWKSNoMatchingKey`. An unknown `kid` from
+  //   a healthy endpoint means the token was signed by a key this team does not publish —
+  //   that is a forgery or a long-rotated token, never an outage. Classing it as an outage
+  //   would hide a forged token in the alert that says "Cloudflare is down".
+  return 'invalid-token';
+}
+
+function errorClass(error: unknown): string {
+  return error instanceof Error ? error.name : typeof error;
+}
+
+/** ⛔ No body, no `WWW-Authenticate` detail, no reason. An unauthenticated caller learns
+ *  nothing about why; the reason goes to the log, where an operator can read it. */
+function deny(status: 401 | 403): Response {
+  return new Response(null, { status });
+}
+
+/**
+ * Build the `fetch` handler Caddy's `forward_auth` calls.
+ *
+ * ```ts
+ * const verify = accessForwardAuth({
+ *   teamDomain: 'https://example.cloudflareaccess.com',
+ *   audience: process.env.ACCESS_AUD,
+ * });
+ * Bun.serve({ port: 9101, hostname: '127.0.0.1', fetch: verify });
+ * ```
+ *
+ * ⛔ ONE HANDLER PER ACCESS APPLICATION. `audience` is fixed at construction and is never
+ *   read from the request — an AUD a caller can influence is the whole vulnerability this
+ *   exists to prevent. Protecting two applications means two handlers and two routes.
+ *
+ * ★ RETURNS A PLAIN `(Request) => Promise<Response>`, so it needs no server framework and
+ *   no runtime-specific import: `Bun.serve`, `node:http`'s fetch adapters and workerd all
+ *   take it as-is. Routing several of these by path is the consumer's own `if`.
+ */
+export function accessForwardAuth(
+  options: AccessForwardAuthOptions,
+): (request: Request) => Promise<Response> {
+  const names = { ...DEFAULT_HEADERS, ...options.headers };
+  const logger = options.logger ?? log;
+  assertTeamDomain(options.teamDomain);
+
+  return async (request: Request): Promise<Response> => {
+    const found = accessToken(request);
+    if (found === undefined) {
+      logger.warn('access denied', { reason: 'no-token' satisfies DenyReason });
+      return deny(401);
+    }
+
+    let identity: AccessIdentity;
+    try {
+      identity = await verifyAccessToken(found.token, options);
+    } catch (error) {
+      const reason = reasonFor(error);
+      logger.warn('access denied', { reason, source: found.source, error: errorClass(error) });
+      return deny(401);
+    }
+
+    try {
+      if (options.authorize !== undefined && !(await options.authorize(identity))) {
+        // ⚠️ 403, not 401: re-authenticating cannot help, and a 401 sends the browser back
+        //   to Access for a login it already completed — an infinite redirect loop.
+        logger.warn('access denied', {
+          reason: 'not-authorized' satisfies DenyReason,
+          email: identity.email ?? '',
+        });
+        return deny(403);
+      }
+    } catch (error) {
+      // ⛔ A THROWING `authorize` IS A DENIAL, NOT A GRANT. A consumer's callback that hits
+      //   its own database and fails must not fall through to the success path; letting the
+      //   exception escape would hand Caddy a 502, which is also closed but arrives with no
+      //   log line saying whose callback broke.
+      logger.error('access denied', {
+        reason: 'unexpected' satisfies DenyReason,
+        error: errorClass(error),
+      });
+      return deny(403);
+    }
+
+    return granted(identity, names, found.source);
+  };
+}
+
+/**
+ * ⛔ EVERY IDENTITY HEADER IS SET ON EVERY 2xx, empty string included. This is the
+ *   spoofing defence, and it is not optional.
+ *   🔴 Caddy's `copy_headers` expands to `request_header <Name> {rp.header.<Name>}` inside
+ *     a 2xx handler — it copies FROM the auth response ONTO the client's request. A client
+ *     that sends `X-Access-Email: admin@example.com` itself is overwritten only if this
+ *     response carries that header. Omitting it for a token with no `email` claim would
+ *     leave the attacker's value standing, and the upstream would read it as identity.
+ *     Always emitting the name closes that whether or not Caddy also clears absent fields
+ *     — behaviour its documentation does not actually promise.
+ */
+function granted(
+  identity: AccessIdentity,
+  names: Required<IdentityHeaders>,
+  source: TokenSource,
+): Response {
+  const headers = new Headers();
+  headers.set(names.email, identity.email ?? '');
+  headers.set(names.sub, identity.sub ?? '');
+  headers.set('X-Access-Token-Source', source);
+  return new Response(null, { status: 204, headers });
+}
+
+/**
+ * ⚠️ A TRAILING SLASH BREAKS BOTH CHECKS AT ONCE, AND QUIETLY. `teamDomain` is used
+ *   verbatim as the expected `iss` and as the JWKS origin, so `https://x.cloudflareaccess.com/`
+ *   yields an `iss` that never matches any real token AND a double-slashed certs URL. The
+ *   symptom is every token failing verification with no clue pointing at the config.
+ */
+function assertTeamDomain(teamDomain: string): void {
+  if (!teamDomain.startsWith('https://') || teamDomain.endsWith('/')) {
+    throw new Error(
+      `access-auth: teamDomain must be https:// with no trailing slash, got ${teamDomain}`,
+    );
+  }
+}

package/src/access-auth/index.ts

@@ -0,0 +1,34 @@
+/**
+ * `@homeflare/cloudflare/access-auth` — a Cloudflare Access verifier for a reverse proxy's
+ * `forward_auth`, so a surface that is not a Worker can be protected by Access properly.
+ *
+ * ★ WHY THIS IS A SUBPATH AND NOT THE MAIN ENTRY. The package entry is the workerd layer.
+ *   This handler is runtime-neutral — `Request` in, `Response` out, no platform import —
+ *   because the process that runs it sits next to the proxy, typically under Bun or Node,
+ *   not on workerd. A subpath keeps that opt-in explicit and leaves the entry unchanged.
+ *
+ * ⛔ THE AUD IS THE WHOLE CHECK. Every Access application in one account is signed by the
+ *   SAME team keys, so a token minted for a different app in your own account verifies
+ *   perfectly against issuer and signature. Only `audience` says the token was minted for
+ *   THIS application. A verifier that checks `iss` alone admits every Access user of every
+ *   app you run — which reads as working, for everyone, until the wrong person tries.
+ *
+ * ⚠️ THIS PROTECTS THE PROXY HOP, NOT THE ORIGIN PORT. Verifying the JWT is worth nothing
+ *   if the upstream is also reachable directly; bind it to loopback, or the check is an
+ *   ornament on a door that is propped open. docs/access-auth.md says it again with the
+ *   Caddyfile.
+ */
+export {
+  accessForwardAuth,
+  type AccessForwardAuthOptions,
+  type DenyReason,
+  type IdentityHeaders,
+} from './handler.ts';
+export {
+  ACCESS_COOKIE,
+  ACCESS_HEADER,
+  accessToken,
+  readCookie,
+  type FoundToken,
+  type TokenSource,
+} from './token.ts';

package/src/access-auth/token.ts

@@ -0,0 +1,73 @@
+/**
+ * Finding the Access token on an inbound request — header first, cookie second.
+ *
+ * ★ BOTH, BECAUSE NEITHER IS GUARANTEED. Cloudflare's validation guide says the
+ *   `CF_Authorization` cookie "is not guaranteed to be passed" and to prefer the
+ *   `Cf-Access-Jwt-Assertion` header. The reverse also happens: the header is attached by
+ *   the Access hop, so a request that reaches the origin through a further proxy — or a
+ *   browser replaying its own cookie — can carry the cookie and not the header. Checking
+ *   one only is a 401 that looks like a broken login and is actually a missing branch.
+ *
+ * ⛔ THE HEADER WINS WHEN BOTH ARE PRESENT, and that order is load-bearing. The header is
+ *   set by the Access hop on this request; the cookie is whatever the client's jar held.
+ *   Preferring the cookie would let a client pin a stale token over the fresh assertion.
+ *   ⚠️ Neither is trusted here — both are verified identically by `verifyAccessToken`.
+ *   This is about which candidate is tried, not about which is believed.
+ */
+
+/** The header Access sets on the request it forwards to the origin. */
+export const ACCESS_HEADER = 'Cf-Access-Jwt-Assertion';
+
+/** The cookie Access sets in the browser. */
+export const ACCESS_COOKIE = 'CF_Authorization';
+
+/** Where a candidate token was found. Useful in a log line; never a trust signal. */
+export type TokenSource = 'header' | 'cookie';
+
+export interface FoundToken {
+  readonly token: string;
+  readonly source: TokenSource;
+}
+
+/**
+ * Read one cookie out of a `Cookie` header value.
+ *
+ * ⚠️ HAND-PARSED, AND SMALL ON PURPOSE. A cookie library would bring parsing of
+ *   attributes (Path, SameSite, Max-Age) that only ever appear on `Set-Cookie`, which is
+ *   the response side. Requests carry a bare `name=value; name=value` list, and that is
+ *   all this reads.
+ * ⚠️ A JWT is base64url and contains no `;` or `=`-in-value ambiguity beyond padding, but
+ *   this still splits on the FIRST `=` only — a value containing `=` (base64 padding) is
+ *   otherwise truncated mid-token, which fails verification with a signature error and
+ *   sends you hunting in the wrong place.
+ */
+export function readCookie(header: string | null, name: string): string | undefined {
+  if (header === null) return undefined;
+
+  for (const pair of header.split(';')) {
+    const eq = pair.indexOf('=');
+    if (eq === -1) continue;
+    if (pair.slice(0, eq).trim() !== name) continue;
+
+    const value = pair.slice(eq + 1).trim();
+    return value === '' ? undefined : value;
+  }
+
+  return undefined;
+}
+
+/**
+ * The Access token on `request`, or `undefined` when it carries none.
+ *
+ * ⛔ RETURNS THE CANDIDATE UNVERIFIED. Every caller must hand the result to
+ *   `verifyAccessToken`; nothing about being present in a header makes a token valid.
+ */
+export function accessToken(request: Request): FoundToken | undefined {
+  const fromHeader = request.headers.get(ACCESS_HEADER);
+  if (fromHeader !== null && fromHeader !== '') return { token: fromHeader, source: 'header' };
+
+  const fromCookie = readCookie(request.headers.get('Cookie'), ACCESS_COOKIE);
+  if (fromCookie !== undefined) return { token: fromCookie, source: 'cookie' };
+
+  return undefined;
+}

package/src/access.ts

@@ -29,6 +29,16 @@ export interface AccessOptions {
   readonly teamDomain: string;
   /** The application's AUD tag, from Zero Trust → Access → Applications. */
   readonly audience: string;
+  /**
+   * Reject a token older than this, by `iat`. Seconds, or a jose duration like `'8h'`.
+   * ★ OPT-IN BECAUSE `exp` ALREADY BOUNDS THE TOKEN. Access sets the session lifetime in
+   *   `exp`, so this is a second, shorter leash for a surface that wants one — not a
+   *   missing check. ⚠️ Setting it below the Access session duration logs users out
+   *   mid-session with a 401 they cannot fix by retrying.
+   */
+  readonly maxTokenAge?: string | number;
+  /** Seconds of clock skew tolerated on `exp`/`nbf`/`iat`. jose's default is 0. */
+  readonly clockTolerance?: string | number;
 }
 
 /** The subset of Access claims worth depending on. */
@@ -79,9 +89,35 @@ export async function verifyAccessJwt(
   const token = request.headers.get(ACCESS_HEADER);
   if (token === null) throw new Error('access: no Cf-Access-Jwt-Assertion header');
 
+  return await verifyAccessToken(token, options);
+}
+
+/**
+ * Verify a token string that the caller has already located, returning the identity.
+ *
+ * ★ EXTRACTED SO THERE IS EXACTLY ONE VERIFICATION, NOT TWO. `verifyAccessJwt` reads the
+ *   header; the forward_auth handler (`@homeflare/cloudflare/access-auth`) also accepts
+ *   the `CF_Authorization` cookie, because Cloudflare's own documentation says the cookie
+ *   "is not guaranteed to be passed" and the reverse is true too — a request that arrives
+ *   through a proxy hop may carry one and not the other. Both funnel here, so a fix to the
+ *   checks below cannot land on one path and miss the other.
+ *
+ * ⛔ THROWS ON EVERY FAILURE, exactly like `verifyAccessJwt`. Same reasoning: a boolean a
+ *   caller forgets to test is an open door.
+ */
+export async function verifyAccessToken(
+  token: string,
+  options: AccessOptions,
+): Promise<AccessIdentity> {
   const { payload } = await jwtVerify(token, keysFor(options.teamDomain), {
     issuer: options.teamDomain,
     audience: options.audience,
+    // ⛔ SPREAD, NOT `maxTokenAge: options.maxTokenAge`. `exactOptionalPropertyTypes` is on,
+    //   and passing an explicit `undefined` is not the same as omitting the key — jose
+    //   reads `'maxTokenAge' in options`, so the undefined form would enable the check
+    //   with an undefined bound.
+    ...(options.maxTokenAge === undefined ? {} : { maxTokenAge: options.maxTokenAge }),
+    ...(options.clockTolerance === undefined ? {} : { clockTolerance: options.clockTolerance }),
   });
 
   return {

package/src/index.ts

@@ -26,7 +26,19 @@ export {
   type AccessContext,
   type AccessIdentityInfo,
 } from './access-identity.ts';
-export { verifyAccessJwt, type AccessIdentity, type AccessOptions } from './access.ts';
+/**
+ * ⚠️ `verifyAccessToken` IS THE SAME CHECK WITH THE TOKEN ALREADY IN HAND — for a caller
+ *   that read it from somewhere other than the header (a cookie, a WebSocket subprotocol).
+ *   It is not a lighter variant: identical issuer, audience and expiry checks.
+ *   ★ Protecting a non-Worker origin behind a reverse proxy? `@homeflare/cloudflare/access-auth`
+ *     is the ready-made `forward_auth` handler; you do not need to assemble one from these.
+ */
+export {
+  verifyAccessJwt,
+  verifyAccessToken,
+  type AccessIdentity,
+  type AccessOptions,
+} from './access.ts';
 export {
   protectedResourceMetadata,
   serveMcpMetadata,

package/src/version.ts

@@ -1,2 +1,2 @@
 // ⛔ GENERATED by scripts/sync-versions.ts — do not edit. Source: package.json.
-export const VERSION: string = '0.3.1';
+export const VERSION: string = '0.3.2';