@adrianhall/cloudflare-toolkit 0.0.1

package/dist/hono/index.d.ts

@@ -0,0 +1,347 @@
+import { n as ProblemDetailsInput, t as ProblemDetails } from "../types-Cx6NNILW.js";
+import { a as Environment, l as Logger, p as Transport, s as LogLevel } from "../types-DCSMb1cp.js";
+import { t as PathPolicy } from "../types-DXboaWOT.js";
+import { Context, ErrorHandler, MiddlewareHandler, NotFoundHandler } from "hono";
+//#region src/lib/hono/error-handler.d.ts
+/**
+ * Options for {@link problemDetailsErrorHandler}.
+ */
+interface ProblemDetailsErrorHandlerOptions {
+  /** Prefix for the `type` URI. When set, a status-derived slug is appended. */
+  typePrefix?: string;
+  /** Default `type` URI. Defaults to `"about:blank"`. */
+  defaultType?: string;
+  /**
+   * Include the stack trace on unhandled `Error` responses (500). The stack is emitted as a
+   * top-level `stack` extension member per RFC 9457 §3.1 flattening, not in `detail`, to
+   * prevent leakage into UIs that render `detail` verbatim.
+   *
+   * Security-sensitive: development-only, must default to `false`.
+   */
+  includeStack?: boolean;
+  /**
+   * When `true`, populate `instance` from the request path (`c.req.path`) if the thrown problem
+   * didn't specify one. Explicit values always win.
+   *
+   * Default: `false` — opt-in to avoid silently changing response shape.
+   */
+  autoInstance?: boolean;
+  /** Custom error to {@link ProblemDetailsInput} mapping. */
+  mapError?: (error: Error) => ProblemDetailsInput | undefined;
+  /**
+   * Localize `title`/`detail` before sending the response. Returned fields are merged onto the
+   * original {@link ProblemDetails}, so callers may return a partial patch (e.g. `{ title: "..."
+   * }`) or omit the return entirely.
+   */
+  localize?: (pd: ProblemDetails, c: Context) => Partial<ProblemDetails> | undefined;
+}
+/**
+ * Create an `app.onError` handler that returns RFC 9457 Problem Details responses. Handles
+ * {@link ProblemDetailsError}, Hono `HTTPException`, and unhandled exceptions.
+ *
+ * @param options - Options controlling `type` URI construction, stack-trace exposure, `instance`
+ * auto-population, custom error mapping, and localization.
+ * @returns A Hono `ErrorHandler`.
+ * @example
+ * ```ts
+ * import { Hono } from "hono";
+ * import { problemDetailsErrorHandler } from "@adrianhall/cloudflare-toolkit/hono";
+ *
+ * const app = new Hono();
+ * app.onError(problemDetailsErrorHandler());
+ * ```
+ */
+declare function problemDetailsErrorHandler(options?: ProblemDetailsErrorHandlerOptions): ErrorHandler;
+//#endregion
+//#region src/lib/hono/not-found-handler.d.ts
+/**
+ * Options for {@link notFoundHandler}.
+ */
+interface NotFoundHandlerOptions {
+  /** Prefix for the `type` URI. When set, a status-derived slug is appended. */
+  typePrefix?: string;
+  /** Default `type` URI when `typePrefix` is not set. Defaults to `"about:blank"`. */
+  defaultType?: string;
+  /**
+   * When `true`, populate `instance` from the request path (`c.req.path`).
+   *
+   * Default: `false`, matching `problemDetailsErrorHandler`'s own default.
+   */
+  autoInstance?: boolean;
+}
+/**
+ * Create an `app.notFound` handler that returns an RFC 9457 Problem Details `404` response. This
+ * mimics what throwing `notFound()` (`@adrianhall/cloudflare-toolkit/errors`) through
+ * {@link problemDetailsErrorHandler} would produce, without requiring a request to actually
+ * throw — `app.notFound()` is wired independently of `app.onError()`.
+ *
+ * @param options - Options controlling the `type` URI and whether `instance` is auto-populated.
+ * @returns A Hono `NotFoundHandler`.
+ * @example
+ * ```ts
+ * import { Hono } from "hono";
+ * import { notFoundHandler } from "@adrianhall/cloudflare-toolkit/hono";
+ *
+ * const app = new Hono();
+ * app.notFound(notFoundHandler());
+ * ```
+ */
+declare function notFoundHandler(options?: NotFoundHandlerOptions): NotFoundHandler;
+//#endregion
+//#region src/lib/hono/types.d.ts
+/**
+ * Context variables set by {@link cloudflareLogger}. Intersect this with your own `Variables`
+ * when typing your `Hono` instance so that `c.get("LOGGER")`/`c.var.LOGGER` is statically known:
+ *
+ * ```ts
+ * interface AppVariables extends LoggerVariables {
+ *   // Custom variables go here
+ * }
+ *
+ * type AppContext = { Bindings: Env; Variables: AppVariables };
+ * ```
+ */
+interface LoggerVariables {
+  /** The request-scoped `Logger` set by `cloudflareLogger`. */
+  LOGGER: Logger;
+}
+/**
+ * Context variables set by {@link cloudflareAccess} on a successfully authenticated request.
+ * Intersect this with your own `Variables` when typing your `Hono` instance so that
+ * `c.get("userEmail")`/`c.get("userSub")` are statically known:
+ *
+ * ```ts
+ * interface AppVariables extends AuthVariables {
+ *   // Custom variables go here
+ * }
+ *
+ * type AppContext = { Bindings: Env; Variables: AppVariables };
+ * ```
+ */
+interface AuthVariables {
+  /** Authenticated user's email address (from the JWT `email` claim). */
+  userEmail: string;
+  /** Authenticated user's unique identifier (from the JWT `sub` claim). */
+  userSub: string;
+}
+/**
+ * Convenience alias for the common case of using {@link cloudflareAccess} and
+ * {@link cloudflareLogger} together:
+ *
+ * ```ts
+ * interface AppVariables extends CloudflareToolkitVariables {
+ *   // Custom variables go here
+ * }
+ * ```
+ *
+ * Exactly equal to `AuthVariables & LoggerVariables` — {@link AuthVariables} and
+ * {@link LoggerVariables} remain separate, independently composable types; this alias does not
+ * replace using either on its own.
+ */
+type CloudflareToolkitVariables = AuthVariables & LoggerVariables;
+//#endregion
+//#region src/lib/hono/logger-middleware.d.ts
+/**
+ * Options for {@link cloudflareLogger}.
+ */
+interface CloudflareLoggerOptions {
+  /**
+   * Environment hint passed to `resolveLoggerConfig`. When omitted, the middleware reads
+   * `c.env.ENVIRONMENT` at request time; when that is also absent, `resolveLoggerConfig` treats
+   * it as `"production"`.
+   */
+  readonly environment?: Environment;
+  /**
+   * Minimum severity level to emit. Defaults to the level chosen by
+   * `resolveLoggerConfig(environment, "worker")`.
+   */
+  readonly level?: LogLevel;
+  /**
+   * Transport to receive emitted records. Defaults to the transport chosen by
+   * `resolveLoggerConfig(environment, "worker")`. Inject a capture transport in tests to assert
+   * on emitted records.
+   */
+  readonly transport?: Transport;
+}
+/**
+ * Create Hono middleware that attaches a request-scoped {@link Logger} to the context as
+ * `LOGGER` (`LoggerVariables`, ./types.ts), so downstream middleware and handlers can log
+ * through it.
+ *
+ * The logger's level and transport are resolved via `resolveLoggerConfig(environment, "worker")`
+ * (`@adrianhall/cloudflare-toolkit/logging`) unless overridden by `options.level`/
+ * `options.transport`. This middleware is independently wireable — it has no dependency on
+ * `cloudflareAccess`.
+ *
+ * @param options - Options controlling the environment, level, and transport used to build the
+ * logger.
+ * @returns A Hono `MiddlewareHandler` parameterised with {@link LoggerVariables}, so
+ * `c.set("LOGGER", …)` inside this middleware — and `c.get("LOGGER")` in a consumer's own
+ * handlers once composed via `app.use(...)` — are statically checked against
+ * {@link LoggerVariables} rather than accepted as an untyped magic string.
+ * @example
+ * ```ts
+ * import { Hono } from "hono";
+ * import { cloudflareLogger } from "@adrianhall/cloudflare-toolkit/hono";
+ *
+ * const app = new Hono();
+ * app.use(cloudflareLogger());
+ *
+ * app.get("/", (c) => {
+ *   c.get("LOGGER").info("handling request");
+ *   return c.text("ok");
+ * });
+ * ```
+ */
+declare function cloudflareLogger(options?: CloudflareLoggerOptions): MiddlewareHandler<{
+  Variables: LoggerVariables;
+}>;
+//#endregion
+//#region src/lib/hono/cloudflare-access.d.ts
+/**
+ * Options for {@link cloudflareAccess}.
+ */
+interface CloudflareAccessOptions {
+  /**
+   * Path policies evaluated in order (first match wins).
+   *
+   * - `authenticate: false` — bypass JWT validation entirely.
+   * - `authenticate: true` — require a valid JWT (401 if missing/invalid).
+   * - No matching policy — behavior is controlled by
+   *   {@link CloudflareAccessOptions.defaultAction}.
+   *
+   * When omitted, every path is subject to {@link CloudflareAccessOptions.defaultAction}.
+   *
+   * @example
+   * ```ts
+   * policies: [
+   *   { pattern: /^\/api\/version$/, authenticate: false },
+   *   { pattern: /^\/api\//, authenticate: true }
+   * ]
+   * ```
+   */
+  readonly policies?: PathPolicy[];
+  /**
+   * What to do when the request path does not match any policy.
+   *
+   * - `"block"` *(default)* — return 401 if no valid JWT is present.
+   * - `"bypass"` — allow the request through without authentication. If a valid JWT is present
+   *   it is still verified and `AuthVariables` are still set; otherwise the request continues
+   *   with no authenticated user.
+   */
+  readonly defaultAction?: "block" | "bypass";
+  /**
+   * Cloudflare Access team domain used to fetch the public JWKS. When omitted, the middleware
+   * reads `c.env.CLOUDFLARE_TEAM_DOMAIN` at request time.
+   */
+  readonly teamDomain?: string;
+  /**
+   * Application Audience Tag. When provided, the middleware verifies the JWT `aud` claim
+   * contains this value.
+   *
+   * **When omitted, audience validation is skipped** — the `aud` claim is not checked at all.
+   * Every Cloudflare Access application in the same team shares the same JWKS, so without an
+   * `aud` check, a JWT that is valid for *any other Access application in the team* is accepted
+   * here too (cross-application token replay).
+   *
+   * Unless {@link CloudflareAccessOptions.enableDevTokens} is `true` (local development),
+   * omitting `audience` logs a one-time warning at construction time — see
+   * {@link cloudflareAccess}'s security remarks.
+   */
+  readonly audience?: string;
+  /**
+   * Enable HS256 developer-token verification.
+   *
+   * **Default `false` (fail-closed).** When `false`, {@link cloudflareAccess} verifies the JWT
+   * **only** against the Cloudflare Access JWKS — a developer-signed HS256 token (including one
+   * signed with the public `DEFAULT_DEV_SECRET`) is rejected. This prevents a deployed Worker
+   * from silently trusting forgeable dev tokens.
+   *
+   * Enable it only in local development, gated on a build-time signal that is statically
+   * `false` in production:
+   *
+   * ```ts
+   * app.use(cloudflareAccess({ policies, enableDevTokens: import.meta.env.DEV }));
+   * ```
+   *
+   * When enabled without an explicit {@link CloudflareAccessOptions.devSecret}, the middleware
+   * logs a one-time warning that it is verifying with the public default secret.
+   */
+  readonly enableDevTokens?: boolean;
+  /**
+   * HMAC secret for validating developer-generated JWTs. Ignored unless
+   * {@link CloudflareAccessOptions.enableDevTokens} is `true`. When dev tokens are enabled and
+   * this is omitted, the well-known `DEFAULT_DEV_SECRET` is used and a one-time warning is
+   * logged — never rely on that for production security.
+   */
+  readonly devSecret?: string;
+  /**
+   * Structured logger used for debug/info/warn/error diagnostics. Defaults to a silent logger
+   * (nothing is emitted) when omitted.
+   */
+  readonly logger?: Logger;
+}
+/**
+ * Create a Hono middleware that validates a Cloudflare Access JWT and sets `AuthVariables`
+ * (`userEmail`, `userSub`, ./types.ts) on the Hono context.
+ *
+ * **Policy evaluation**:
+ *
+ * | Policy match           | Behavior                                    |
+ * | ----------------------- | -------------------------------------------- |
+ * | `authenticate: false`  | Bypass — skip JWT validation entirely.       |
+ * | `authenticate: true`   | Require — valid JWT or 401.                  |
+ * | No matching policy      | Controlled by `defaultAction` (see below).   |
+ *
+ * Every `401` this middleware returns is an RFC 9457 `application/problem+json` response
+ * (`{ type, status, title, detail }`), matching `problemDetailsErrorHandler` and
+ * `notFoundHandler`'s conventions.
+ *
+ * **`defaultAction`** (applies when no policy matches):
+ *
+ * - `"block"` *(default)* — return 401 if no valid JWT is present.
+ * - `"bypass"` — allow the request through. If a JWT *is* present and valid, the context
+ *   variables are still set; otherwise the request continues with no authenticated user.
+ *
+ * **Verification order** (when JWT validation is performed):
+ *
+ * 1. *(Opt-in)* When `enableDevTokens` is `true`, try HMAC verification with the dev secret
+ *    (fast, in-process).
+ * 2. Verify against the remote JWKS endpoint for the team domain.
+ *
+ * Developer-token verification is **fail-closed**: it is disabled by default so a deployed
+ * Worker never silently trusts a forgeable HS256 token signed with the public
+ * `DEFAULT_DEV_SECRET`. Enable it only in local development.
+ *
+ * **Audience validation is opt-in, not fail-closed**: omitting
+ * {@link CloudflareAccessOptions.audience} skips the `aud` check and allows cross-application
+ * token replay within the same Cloudflare Access team (see that option's docs). To surface this
+ * without breaking existing deployments, {@link cloudflareAccess} logs a one-time warning at
+ * construction time whenever `audience` is omitted **and** `enableDevTokens` is not `true` —
+ * i.e. in the default, production-shaped configuration. The warning is intentionally silent
+ * when `enableDevTokens` is `true`, since that already signals a local-development posture.
+ *
+ * @remarks Security-critical: this fail-closed default must be preserved exactly — see the
+ * "fail-closed" describe block in `test/workers/hono/cloudflare-access.test.ts`.
+ * @param options - Options controlling path policies, the default action for unmatched paths,
+ * the Cloudflare Access team domain/audience, dev-token verification, and the logger.
+ * @returns A Hono `MiddlewareHandler` parameterised with {@link AuthVariables}, so
+ * `c.set("userEmail", …)`/`c.set("userSub", …)` inside this middleware — and `c.get("userEmail")`/
+ * `c.get("userSub")` in a consumer's own handlers once composed via `app.use(...)` — are
+ * statically checked against {@link AuthVariables} rather than accepted as untyped magic strings.
+ * @example
+ * ```ts
+ * import { Hono } from "hono";
+ * import { cloudflareAccess, type AuthVariables } from "@adrianhall/cloudflare-toolkit/hono";
+ *
+ * const app = new Hono<{ Variables: AuthVariables }>();
+ * app.use(cloudflareAccess({ policies: [{ pattern: /^\/api\/version$/, authenticate: false }] }));
+ * app.get("/api/*", (c) => c.json({ user: c.get("userEmail") }));
+ * ```
+ */
+declare function cloudflareAccess(options?: CloudflareAccessOptions): MiddlewareHandler<{
+  Variables: AuthVariables;
+}>;
+//#endregion
+export { type AuthVariables, type CloudflareAccessOptions, type CloudflareLoggerOptions, type CloudflareToolkitVariables, type LoggerVariables, type NotFoundHandlerOptions, type ProblemDetailsErrorHandlerOptions, cloudflareAccess, cloudflareLogger, notFoundHandler, problemDetailsErrorHandler };
+//# sourceMappingURL=index.d.ts.map

package/dist/hono/index.js

@@ -0,0 +1,307 @@
+import { a as statusToPhrase, i as normalizeProblemDetails, n as ProblemDetailsError, o as statusToSlug, r as buildProblemResponse } from "../factory-BI5gVL_P.js";
+import { n as resolveLoggerConfig, s as createLogger, t as createSilentTransport } from "../silent-CWpHE65X.js";
+import { l as verifyAccessJwt, s as parseCookie, u as verifyDevJwt } from "../jwt-BvuKtvby.js";
+import { t as matchPolicy } from "../policy-CvS6AvvD.js";
+import { HTTPException } from "hono/http-exception";
+//#region src/lib/hono/error-handler.ts
+function buildType$1(status, options) {
+	if (options.typePrefix) {
+		const slug = statusToSlug(status);
+		if (slug) return `${options.typePrefix}/${slug}`;
+	}
+	return options.defaultType ?? "about:blank";
+}
+function toResponse(input, c, options) {
+	let pd = normalizeProblemDetails(input);
+	if (options.autoInstance && pd.instance === void 0) pd = {
+		...pd,
+		instance: c.req.path
+	};
+	if (options.localize) try {
+		pd = {
+			...pd,
+			...options.localize(pd, c)
+		};
+	} catch {}
+	c.set("problemDetails", pd);
+	return buildProblemResponse(pd);
+}
+/**
+* Create an `app.onError` handler that returns RFC 9457 Problem Details responses. Handles
+* {@link ProblemDetailsError}, Hono `HTTPException`, and unhandled exceptions.
+*
+* @param options - Options controlling `type` URI construction, stack-trace exposure, `instance`
+* auto-population, custom error mapping, and localization.
+* @returns A Hono `ErrorHandler`.
+* @example
+* ```ts
+* import { Hono } from "hono";
+* import { problemDetailsErrorHandler } from "@adrianhall/cloudflare-toolkit/hono";
+*
+* const app = new Hono();
+* app.onError(problemDetailsErrorHandler());
+* ```
+*/
+function problemDetailsErrorHandler(options = {}) {
+	return (error, c) => {
+		if (error instanceof ProblemDetailsError) return toResponse(error.problemDetails, c, options);
+		if (options.mapError) {
+			const mapped = options.mapError(error);
+			if (mapped) return toResponse(mapped, c, options);
+		}
+		if (error instanceof HTTPException) return toResponse({
+			status: error.status,
+			type: buildType$1(error.status, options),
+			title: statusToPhrase(error.status),
+			detail: error.message
+		}, c, options);
+		return toResponse({
+			status: 500,
+			type: buildType$1(500, options),
+			title: "Internal Server Error",
+			detail: "An unexpected error occurred",
+			extensions: options.includeStack ? { stack: error.stack } : void 0
+		}, c, options);
+	};
+}
+//#endregion
+//#region src/lib/hono/not-found-handler.ts
+const NOT_FOUND_STATUS = 404;
+function buildType(options) {
+	if (options.typePrefix) return `${options.typePrefix}/${statusToSlug(NOT_FOUND_STATUS)}`;
+	return options.defaultType ?? "about:blank";
+}
+/**
+* Create an `app.notFound` handler that returns an RFC 9457 Problem Details `404` response. This
+* mimics what throwing `notFound()` (`@adrianhall/cloudflare-toolkit/errors`) through
+* {@link problemDetailsErrorHandler} would produce, without requiring a request to actually
+* throw — `app.notFound()` is wired independently of `app.onError()`.
+*
+* @param options - Options controlling the `type` URI and whether `instance` is auto-populated.
+* @returns A Hono `NotFoundHandler`.
+* @example
+* ```ts
+* import { Hono } from "hono";
+* import { notFoundHandler } from "@adrianhall/cloudflare-toolkit/hono";
+*
+* const app = new Hono();
+* app.notFound(notFoundHandler());
+* ```
+*/
+function notFoundHandler(options = {}) {
+	return (c) => {
+		let pd = {
+			type: buildType(options),
+			status: NOT_FOUND_STATUS,
+			title: statusToPhrase(NOT_FOUND_STATUS)
+		};
+		if (options.autoInstance) pd = {
+			...pd,
+			instance: c.req.path
+		};
+		return buildProblemResponse(pd);
+	};
+}
+//#endregion
+//#region src/lib/hono/logger-middleware.ts
+function resolveEnvironment(options, c) {
+	if (options.environment !== void 0) return options.environment;
+	return c.env?.ENVIRONMENT;
+}
+/**
+* Create Hono middleware that attaches a request-scoped {@link Logger} to the context as
+* `LOGGER` (`LoggerVariables`, ./types.ts), so downstream middleware and handlers can log
+* through it.
+*
+* The logger's level and transport are resolved via `resolveLoggerConfig(environment, "worker")`
+* (`@adrianhall/cloudflare-toolkit/logging`) unless overridden by `options.level`/
+* `options.transport`. This middleware is independently wireable — it has no dependency on
+* `cloudflareAccess`.
+*
+* @param options - Options controlling the environment, level, and transport used to build the
+* logger.
+* @returns A Hono `MiddlewareHandler` parameterised with {@link LoggerVariables}, so
+* `c.set("LOGGER", …)` inside this middleware — and `c.get("LOGGER")` in a consumer's own
+* handlers once composed via `app.use(...)` — are statically checked against
+* {@link LoggerVariables} rather than accepted as an untyped magic string.
+* @example
+* ```ts
+* import { Hono } from "hono";
+* import { cloudflareLogger } from "@adrianhall/cloudflare-toolkit/hono";
+*
+* const app = new Hono();
+* app.use(cloudflareLogger());
+*
+* app.get("/", (c) => {
+*   c.get("LOGGER").info("handling request");
+*   return c.text("ok");
+* });
+* ```
+*/
+function cloudflareLogger(options = {}) {
+	return async (c, next) => {
+		const base = resolveLoggerConfig(resolveEnvironment(options, c), "worker");
+		const logger = createLogger({
+			level: options.level ?? base.level,
+			transport: options.transport ?? base.transport
+		});
+		c.set("LOGGER", logger);
+		await next();
+	};
+}
+//#endregion
+//#region src/lib/hono/cloudflare-access.ts
+/** Silent fallback used when `options.logger` is not supplied. */
+function createDefaultLogger() {
+	return createLogger({ transport: createSilentTransport() });
+}
+/**
+* Build a `401 Unauthorized` RFC 9457 `application/problem+json` response, matching the shape
+* `problemDetailsErrorHandler` (`./error-handler.js`) and `notFoundHandler` (`./not-found-handler.js`)
+* produce. Built directly via `../problem-details/utils.js` rather than by throwing
+* `unauthorized()` (`@adrianhall/cloudflare-toolkit/errors`), so `cloudflareAccess` returns the
+* correct shape even when a consumer hasn't wired `app.onError(problemDetailsErrorHandler())` —
+* every piece of `/hono` middleware is wired independently (no combined/coordinator middleware).
+*
+* @param detail - Human-readable explanation for this specific 401 occurrence.
+* @returns The resulting `Response`.
+*/
+function unauthorizedResponse(detail) {
+	return buildProblemResponse(normalizeProblemDetails({
+		status: 401,
+		detail
+	}));
+}
+/**
+* Attempt to verify a JWT.
+*
+* When `enableDevTokens` is `true`, the dev (HS256) secret is tried first as a fast in-process
+* path; otherwise that path is skipped entirely and only Cloudflare Access JWKS verification
+* runs — the fail-closed default.
+*
+* Returns the verified claims or `null`.
+*/
+async function verifyToken(c, token, options) {
+	if (options.enableDevTokens) {
+		const devResult = await verifyDevJwt(token, options.devSecret);
+		if (devResult) return devResult;
+	}
+	const bindings = c.env;
+	const teamDomain = options.teamDomainOverride ?? bindings?.CLOUDFLARE_TEAM_DOMAIN;
+	if (!teamDomain) {
+		options.logger.error("No team domain configured - set CLOUDFLARE_TEAM_DOMAIN in env or pass teamDomain in options");
+		return null;
+	}
+	return verifyAccessJwt(token, teamDomain, options.audience, options.logger);
+}
+/**
+* Create a Hono middleware that validates a Cloudflare Access JWT and sets `AuthVariables`
+* (`userEmail`, `userSub`, ./types.ts) on the Hono context.
+*
+* **Policy evaluation**:
+*
+* | Policy match           | Behavior                                    |
+* | ----------------------- | -------------------------------------------- |
+* | `authenticate: false`  | Bypass — skip JWT validation entirely.       |
+* | `authenticate: true`   | Require — valid JWT or 401.                  |
+* | No matching policy      | Controlled by `defaultAction` (see below).   |
+*
+* Every `401` this middleware returns is an RFC 9457 `application/problem+json` response
+* (`{ type, status, title, detail }`), matching `problemDetailsErrorHandler` and
+* `notFoundHandler`'s conventions.
+*
+* **`defaultAction`** (applies when no policy matches):
+*
+* - `"block"` *(default)* — return 401 if no valid JWT is present.
+* - `"bypass"` — allow the request through. If a JWT *is* present and valid, the context
+*   variables are still set; otherwise the request continues with no authenticated user.
+*
+* **Verification order** (when JWT validation is performed):
+*
+* 1. *(Opt-in)* When `enableDevTokens` is `true`, try HMAC verification with the dev secret
+*    (fast, in-process).
+* 2. Verify against the remote JWKS endpoint for the team domain.
+*
+* Developer-token verification is **fail-closed**: it is disabled by default so a deployed
+* Worker never silently trusts a forgeable HS256 token signed with the public
+* `DEFAULT_DEV_SECRET`. Enable it only in local development.
+*
+* **Audience validation is opt-in, not fail-closed**: omitting
+* {@link CloudflareAccessOptions.audience} skips the `aud` check and allows cross-application
+* token replay within the same Cloudflare Access team (see that option's docs). To surface this
+* without breaking existing deployments, {@link cloudflareAccess} logs a one-time warning at
+* construction time whenever `audience` is omitted **and** `enableDevTokens` is not `true` —
+* i.e. in the default, production-shaped configuration. The warning is intentionally silent
+* when `enableDevTokens` is `true`, since that already signals a local-development posture.
+*
+* @remarks Security-critical: this fail-closed default must be preserved exactly — see the
+* "fail-closed" describe block in `test/workers/hono/cloudflare-access.test.ts`.
+* @param options - Options controlling path policies, the default action for unmatched paths,
+* the Cloudflare Access team domain/audience, dev-token verification, and the logger.
+* @returns A Hono `MiddlewareHandler` parameterised with {@link AuthVariables}, so
+* `c.set("userEmail", …)`/`c.set("userSub", …)` inside this middleware — and `c.get("userEmail")`/
+* `c.get("userSub")` in a consumer's own handlers once composed via `app.use(...)` — are
+* statically checked against {@link AuthVariables} rather than accepted as untyped magic strings.
+* @example
+* ```ts
+* import { Hono } from "hono";
+* import { cloudflareAccess, type AuthVariables } from "@adrianhall/cloudflare-toolkit/hono";
+*
+* const app = new Hono<{ Variables: AuthVariables }>();
+* app.use(cloudflareAccess({ policies: [{ pattern: /^\/api\/version$/, authenticate: false }] }));
+* app.get("/api/*", (c) => c.json({ user: c.get("userEmail") }));
+* ```
+*/
+function cloudflareAccess(options = {}) {
+	const policies = options.policies;
+	const defaultAction = options.defaultAction ?? "block";
+	const enableDevTokens = options.enableDevTokens ?? false;
+	const devSecretProvided = typeof options.devSecret === "string";
+	const devSecret = options.devSecret ?? "cloudflare-access-dev-secret-do-not-use-in-production";
+	const audience = options.audience;
+	const teamDomainOverride = options.teamDomain;
+	const log = options.logger ?? createDefaultLogger();
+	if (enableDevTokens && !devSecretProvided) log.warn("enableDevTokens is true but no devSecret was provided; verifying HS256 dev tokens with the public DEFAULT_DEV_SECRET. This is only safe in local development.");
+	if (!enableDevTokens && audience === void 0) log.warn("No audience was provided; the JWT 'aud' claim will not be validated. Any Cloudflare Access application in the same team can mint a token accepted here (cross-application token replay). Set the 'audience' option to this app's Audience Tag, or set enableDevTokens to silence this warning in local development.");
+	return async (c, next) => {
+		const pathname = new URL(c.req.url).pathname;
+		const policyMatch = policies ? matchPolicy(pathname, policies) : void 0;
+		if (policyMatch?.authenticate === false) {
+			log.debug("Path is public - bypassing auth", { pathname });
+			return next();
+		}
+		const authRequired = policyMatch?.authenticate === true || policyMatch === void 0 && defaultAction === "block";
+		const token = c.req.header("cf-access-jwt-assertion") ?? parseCookie(c.req.header("cookie"));
+		if (!token) {
+			if (authRequired) {
+				log.warn("No JWT found in header or cookie");
+				return unauthorizedResponse("Authentication required");
+			}
+			log.debug("No JWT - continuing (bypass)", { pathname });
+			return next();
+		}
+		const result = await verifyToken(c, token, {
+			enableDevTokens,
+			devSecret,
+			audience,
+			teamDomainOverride,
+			logger: log
+		});
+		if (result) {
+			log.debug("Verified token", { email: result.email });
+			c.set("userEmail", result.email);
+			c.set("userSub", result.sub);
+			return next();
+		}
+		if (authRequired) {
+			log.warn("JWT verification failed");
+			return unauthorizedResponse("Invalid or expired token");
+		}
+		log.info("JWT invalid - continuing (bypass)", { pathname });
+		return next();
+	};
+}
+//#endregion
+export { cloudflareAccess, cloudflareLogger, notFoundHandler, problemDetailsErrorHandler };
+
+//# sourceMappingURL=index.js.map