@mandujs/core 0.41.2 → 0.43.0

package/src/middleware/secure/index.ts

@@ -1,417 +1,417 @@
-/**
- * Secure HTTP Headers Middleware
- *
- * A Helmet-equivalent bundle shipping OWASP-recommended defaults for:
- *   - Content-Security-Policy (CSP) — see `./csp.ts`
- *   - Strict-Transport-Security (HSTS)
- *   - X-Frame-Options (legacy; superseded by CSP `frame-ancestors`)
- *   - X-Content-Type-Options
- *   - Referrer-Policy
- *   - Permissions-Policy
- *   - X-XSS-Protection (legacy; explicitly `"0"` on modern clients)
- *
- * Strategy: we implement `MiddlewarePlugin` rather than the bare
- * `(ctx) => Response | void` signature so we can mutate the outgoing Response
- * via `afterHandle`. This mirrors `cors.ts` and means we do NOT need any
- * framework modifications, a new "pending headers" buffer in the context, or
- * a custom wrapper helper that callers must remember to invoke.
- *
- * Ordering vs. session/cookies:
- *   Unlike session middleware, which must commit BEFORE the response is
- *   built (DX-3 + Phase 2.3), header-setting middleware can run AFTER the
- *   response is produced — we use `afterHandle` which receives the fully-
- *   constructed Response and returns a replacement. No ordering hazard with
- *   cookies/session state, because we never touch `ctx.cookies`.
- *
- * CSP nonce plumbing:
- *   When `csp.nonce === true`, we compute a fresh nonce in `beforeHandle`
- *   and stash it on the context under the key `"csp-nonce"`. SSR handlers
- *   that render inline `<script>` tags can read it with
- *   `ctx.get<string>("csp-nonce")`. The same nonce is interpolated into the
- *   CSP header in `afterHandle`, guaranteeing the tag and the header agree.
- *
- *   Auto-injection of the nonce into `renderToStream`'s hydration script
- *   tags is intentionally out of scope for this middleware — see the
- *   Phase 6.2 follow-up item in `CLAUDE.md`.
- *
- * @example
- * ```ts
- * import { secure } from "@mandujs/core/middleware";
- *
- * export default Mandu.filling()
- *   .use(secure())                                 // all defaults
- *   .get((ctx) => ctx.ok({ hello: "world" }));
- *
- * // With CSP nonce:
- * export default Mandu.filling()
- *   .use(secure({ csp: { nonce: true } }))
- *   .get((ctx) => {
- *     const nonce = ctx.get<string>("csp-nonce");
- *     // render inline script with nonce={nonce}
- *     return ctx.ok({ ok: true });
- *   });
- * ```
- */
-import type { MiddlewarePlugin } from "../../filling/filling";
-import type { ManduContext } from "../../filling/context";
-import { buildCsp, type CspOptions } from "./csp";
-
-export { buildCsp, DEFAULT_CSP_DIRECTIVES } from "./csp";
-export type { CspOptions, BuiltCsp } from "./csp";
-
-// ========== Types ==========
-
-export type ReferrerPolicyValue =
-  | "no-referrer"
-  | "no-referrer-when-downgrade"
-  | "origin"
-  | "origin-when-cross-origin"
-  | "same-origin"
-  | "strict-origin"
-  | "strict-origin-when-cross-origin"
-  | "unsafe-url";
-
-export interface HstsOptions {
-  /** max-age in seconds. Default: 15552000 (180 days). */
-  maxAge?: number;
-  /** includeSubDomains directive. Default: true. */
-  includeSubDomains?: boolean;
-  /** preload directive. Default: false — opt-in; implies submitting to the preload list. */
-  preload?: boolean;
-}
-
-export interface SecureMiddlewareOptions {
-  /** Content-Security-Policy options, or `false` to disable. */
-  csp?: CspOptions | false;
-  /** Strict-Transport-Security options, or `false` to disable. */
-  hsts?: HstsOptions | false;
-  /** X-Frame-Options. Default: `"DENY"`. `false` to disable. */
-  frameOptions?: "DENY" | "SAMEORIGIN" | false;
-  /** X-Content-Type-Options: nosniff. Default: true. */
-  noSniff?: boolean;
-  /** Referrer-Policy. Default: `"strict-origin-when-cross-origin"`. */
-  referrerPolicy?: ReferrerPolicyValue | false;
-  /**
-   * Permissions-Policy map. Each entry becomes `feature=(allowlist)`.
-   * Use an empty array to deny a feature entirely (`feature=()`).
-   * `false` disables the header.
-   */
-  permissionsPolicy?: Record<string, string[]> | false;
-  /**
-   * X-XSS-Protection. Default: `"0"` — modern browsers should use CSP; the
-   * legacy auditor has known bypasses and is best disabled. `false` omits.
-   */
-  xssProtection?: "0" | "1" | "1; mode=block" | false;
-  /**
-   * Extra headers to set verbatim. Keys are set as-given (casing preserved
-   * by `Headers` normalization rules). Values overwrite any existing header.
-   */
-  extra?: Record<string, string>;
-}
-
-// ========== Defaults ==========
-
-const DEFAULT_HSTS: Required<HstsOptions> = Object.freeze({
-  maxAge: 15552000, // 180 days — matches Chrome's preload minimum
-  includeSubDomains: true,
-  preload: false,
-});
-
-const DEFAULT_REFERRER_POLICY: ReferrerPolicyValue = "strict-origin-when-cross-origin";
-
-/**
- * OWASP-recommended deny-by-default for commonly abused browser capabilities.
- *
- * - `camera` / `microphone`: prevent drive-by media capture; app pages that
- *   need these must opt in explicitly via override.
- * - `geolocation`: prevents third-party scripts from geo-tagging users.
- * - `payment`: blocks Payment Request API unless you explicitly own it.
- * - `usb`: blocks WebUSB (e.g. hardware key attacks).
- * - `interest-cohort`: opts out of FLoC/Topics tracking. Still widely
- *   respected; cheap insurance.
- */
-const DEFAULT_PERMISSIONS_POLICY: Record<string, string[]> = Object.freeze({
-  camera: [],
-  microphone: [],
-  geolocation: [],
-  payment: [],
-  usb: [],
-  "interest-cohort": [],
-}) as Record<string, string[]>;
-
-const CSP_NONCE_KEY = "csp-nonce";
-
-// ========== Public API ==========
-
-/**
- * Build the secure headers middleware. The options argument is consumed
- * eagerly at construction time — subsequent mutations to the passed object
- * do not affect the already-installed middleware.
- *
- * Returns a `MiddlewarePlugin` with:
- *   - `beforeHandle`: generates the per-request CSP nonce (if enabled) and
- *     stashes it on the context for handler use.
- *   - `afterHandle`: computes the final headers bundle and returns a new
- *     Response with the headers applied. Existing headers from the handler
- *     (e.g. `Content-Type`) are preserved.
- */
-export function secure(options: SecureMiddlewareOptions = {}): MiddlewarePlugin {
-  // Normalize / snapshot options up front so we don't re-read user input on
-  // every request (protects against surprise mutation mid-session).
-  const cfg = normalizeOptions(options);
-
-  return {
-    beforeHandle: async (ctx: ManduContext): Promise<void> => {
-      // If CSP is enabled AND nonce is requested, compute the nonce here so
-      // the handler can read it before producing the response. We build the
-      // full CSP string in `afterHandle` (cheap) using the same nonce so
-      // the header and any handler-rendered <script nonce={...}> agree.
-      if (cfg.csp && cfg.csp.nonce === true) {
-        // buildCsp will synthesize a fresh nonce; we capture it here and
-        // pin it for the afterHandle pass via a per-request override.
-        const built = buildCsp({ ...cfg.csp, nonce: true });
-        if (built.nonce) {
-          ctx.set<string>(CSP_NONCE_KEY, built.nonce);
-        }
-      }
-    },
-
-    afterHandle: async (
-      ctx: ManduContext,
-      response: Response
-    ): Promise<Response> => {
-      const headers = new Headers(response.headers);
-      applySecureHeaders(ctx, headers, cfg);
-
-      // Only re-wrap if we actually added/changed something. In practice the
-      // headers map is always non-empty (we always set at least one header
-      // when options are default), but this keeps us honest about
-      // Response-body identity and matches `cors.ts`'s pattern.
-      return new Response(response.body, {
-        status: response.status,
-        statusText: response.statusText,
-        headers,
-      });
-    },
-  };
-}
-
-/**
- * Manual escape hatch: apply secure headers to an arbitrary Response using
- * the options shape above.
- *
- * Prefer `.use(secure(...))` — this helper exists for callers outside the
- * filling pipeline (e.g. custom error responders, static file handlers).
- * Since no context is available, CSP nonce mode falls back to the one-shot
- * nonce generated inside `buildCsp` — the caller is responsible for wiring
- * that nonce into whatever they render.
- */
-export function applySecureHeadersToResponse(
-  response: Response,
-  options: SecureMiddlewareOptions = {}
-): { response: Response; nonce?: string } {
-  const cfg = normalizeOptions(options);
-  const headers = new Headers(response.headers);
-
-  // Derive a fresh nonce for this standalone call (no context to cache it on).
-  let emittedNonce: string | undefined;
-  if (cfg.csp && cfg.csp.nonce === true) {
-    const built = buildCsp({ ...cfg.csp, nonce: true });
-    emittedNonce = built.nonce;
-  }
-
-  // Pseudo-context shim so applySecureHeaders can read the nonce consistently.
-  const shim = {
-    request: response as unknown as Request, // only used for URL scheme check; standalone callers skip HSTS logic path below via hsts=false typically
-    get: <T>(_key: string): T | undefined => emittedNonce as T | undefined,
-  };
-  applySecureHeaders(shim as unknown as ManduContext, headers, {
-    ...cfg,
-    // If caller didn't explicitly disable HSTS, keep it — but the scheme
-    // probe will simply no-op on a non-Request shim. Callers who want HSTS
-    // on standalone responses must ensure `response.url` carries an
-    // `https:` URL, or they should pass a pre-built Request with
-    // `x-forwarded-proto: https`.
-  });
-
-  return {
-    response: new Response(response.body, {
-      status: response.status,
-      statusText: response.statusText,
-      headers,
-    }),
-    nonce: emittedNonce,
-  };
-}
-
-// ========== Internal: normalization ==========
-
-interface NormalizedOptions {
-  csp: CspOptions | null;
-  hsts: Required<HstsOptions> | null;
-  frameOptions: "DENY" | "SAMEORIGIN" | null;
-  noSniff: boolean;
-  referrerPolicy: ReferrerPolicyValue | null;
-  permissionsPolicy: Record<string, string[]> | null;
-  xssProtection: "0" | "1" | "1; mode=block" | null;
-  extra: Record<string, string>;
-}
-
-function normalizeOptions(options: SecureMiddlewareOptions): NormalizedOptions {
-  return {
-    csp: options.csp === false ? null : options.csp ?? {},
-    hsts:
-      options.hsts === false
-        ? null
-        : { ...DEFAULT_HSTS, ...(options.hsts ?? {}) },
-    frameOptions:
-      options.frameOptions === false
-        ? null
-        : options.frameOptions ?? "DENY",
-    noSniff: options.noSniff !== false,
-    referrerPolicy:
-      options.referrerPolicy === false
-        ? null
-        : options.referrerPolicy ?? DEFAULT_REFERRER_POLICY,
-    permissionsPolicy:
-      options.permissionsPolicy === false
-        ? null
-        : options.permissionsPolicy ?? { ...DEFAULT_PERMISSIONS_POLICY },
-    xssProtection:
-      options.xssProtection === false ? null : options.xssProtection ?? "0",
-    extra: options.extra ?? {},
-  };
-}
-
-// ========== Internal: header application ==========
-
-function applySecureHeaders(
-  ctx: ManduContext,
-  headers: Headers,
-  cfg: NormalizedOptions
-): void {
-  // --- CSP ---
-  if (cfg.csp) {
-    // If a nonce was pre-computed in beforeHandle, reuse it to ensure the
-    // handler's nonce=… values match what we emit in the header.
-    const pinnedNonce = ctx.get<string>(CSP_NONCE_KEY);
-    const effective =
-      pinnedNonce && cfg.csp.nonce === true
-        ? { ...cfg.csp, nonce: pinnedNonce }
-        : cfg.csp;
-
-    const built = buildCsp(effective);
-    headers.set(built.name, built.header);
-  }
-
-  // --- HSTS (only when the request is already HTTPS) ---
-  //
-  // RFC 6797 §7.2: UAs MUST ignore STS on insecure transport, but we also
-  // suppress it server-side to avoid leaking the policy across a plaintext
-  // channel (where an active MITM could strip it for first-visit users
-  // anyway — the "TOFU" problem HSTS is designed to reduce).
-  if (cfg.hsts && isHttps(ctx.request)) {
-    const parts = [`max-age=${Math.floor(cfg.hsts.maxAge)}`];
-    if (cfg.hsts.includeSubDomains) parts.push("includeSubDomains");
-    if (cfg.hsts.preload) parts.push("preload");
-    headers.set("Strict-Transport-Security", parts.join("; "));
-  }
-
-  // --- X-Frame-Options ---
-  if (cfg.frameOptions) {
-    headers.set("X-Frame-Options", cfg.frameOptions);
-  }
-
-  // --- X-Content-Type-Options ---
-  if (cfg.noSniff) {
-    headers.set("X-Content-Type-Options", "nosniff");
-  }
-
-  // --- Referrer-Policy ---
-  if (cfg.referrerPolicy) {
-    headers.set("Referrer-Policy", cfg.referrerPolicy);
-  }
-
-  // --- Permissions-Policy ---
-  if (cfg.permissionsPolicy) {
-    const pp = buildPermissionsPolicy(cfg.permissionsPolicy);
-    if (pp.length > 0) {
-      headers.set("Permissions-Policy", pp);
-    }
-  }
-
-  // --- X-XSS-Protection ---
-  if (cfg.xssProtection !== null) {
-    headers.set("X-XSS-Protection", cfg.xssProtection);
-  }
-
-  // --- Arbitrary extras (caller overrides always win) ---
-  for (const [k, v] of Object.entries(cfg.extra)) {
-    headers.set(k, v);
-  }
-}
-
-/**
- * Build a Permissions-Policy header value.
- *
- * Grammar (simplified): `feature=(allowlist) , feature=(allowlist)`
- *   - Bare tokens like `self` go inside the parens as-is.
- *   - Origins (URLs) must be wrapped in double quotes per spec.
- *   - Empty allowlist `()` denies the feature entirely.
- *
- * We accept the caller's array verbatim; they are responsible for quoting
- * their URL-shaped entries. We do wrap origins that look URL-ish (contain
- * `://`) when they are unquoted, because that's by far the most common
- * mistake and the cost of the heuristic is tiny.
- */
-function buildPermissionsPolicy(map: Record<string, string[]>): string {
-  const entries: string[] = [];
-  for (const [feature, allowlist] of Object.entries(map)) {
-    if (!Array.isArray(allowlist)) continue;
-    const items = allowlist.map(normalizePermissionsItem).join(" ");
-    entries.push(`${feature}=(${items})`);
-  }
-  return entries.join(", ");
-}
-
-function normalizePermissionsItem(raw: string): string {
-  if (raw === "self" || raw === "*") return raw;
-  if (raw.startsWith('"') && raw.endsWith('"')) return raw;
-  if (raw.includes("://")) return `"${raw}"`;
-  return raw;
-}
-
-/**
- * Determine whether the inbound request is HTTPS.
- *
- * Recognizes:
- *   1. Direct `https:` scheme in `request.url`
- *   2. `X-Forwarded-Proto: https` (de-facto reverse-proxy header)
- *   3. `Forwarded: proto=https` (RFC 7239)
- *
- * We intentionally don't trust these headers on direct (non-proxied)
- * connections — but since the caller is the one opting into HSTS, they're
- * also responsible for running behind a reverse proxy that sanitizes
- * client-supplied `Forwarded` / `X-Forwarded-*` headers. This matches
- * Helmet's and express's documented behavior.
- */
-function isHttps(request: Request): boolean {
-  try {
-    if (request.url.startsWith("https:")) return true;
-  } catch {
-    // Some shims may throw on `.url`; fall through to header checks.
-  }
-  const xfp = safeGetHeader(request, "x-forwarded-proto");
-  if (xfp && xfp.split(",")[0]!.trim().toLowerCase() === "https") return true;
-  const fwd = safeGetHeader(request, "forwarded");
-  if (fwd && /\bproto=https\b/i.test(fwd)) return true;
-  return false;
-}
-
-function safeGetHeader(request: Request, name: string): string | null {
-  try {
-    return request.headers?.get(name) ?? null;
-  } catch {
-    return null;
-  }
-}
+/**
+ * Secure HTTP Headers Middleware
+ *
+ * A Helmet-equivalent bundle shipping OWASP-recommended defaults for:
+ *   - Content-Security-Policy (CSP) — see `./csp.ts`
+ *   - Strict-Transport-Security (HSTS)
+ *   - X-Frame-Options (legacy; superseded by CSP `frame-ancestors`)
+ *   - X-Content-Type-Options
+ *   - Referrer-Policy
+ *   - Permissions-Policy
+ *   - X-XSS-Protection (legacy; explicitly `"0"` on modern clients)
+ *
+ * Strategy: we implement `MiddlewarePlugin` rather than the bare
+ * `(ctx) => Response | void` signature so we can mutate the outgoing Response
+ * via `afterHandle`. This mirrors `cors.ts` and means we do NOT need any
+ * framework modifications, a new "pending headers" buffer in the context, or
+ * a custom wrapper helper that callers must remember to invoke.
+ *
+ * Ordering vs. session/cookies:
+ *   Unlike session middleware, which must commit BEFORE the response is
+ *   built (DX-3 + Phase 2.3), header-setting middleware can run AFTER the
+ *   response is produced — we use `afterHandle` which receives the fully-
+ *   constructed Response and returns a replacement. No ordering hazard with
+ *   cookies/session state, because we never touch `ctx.cookies`.
+ *
+ * CSP nonce plumbing:
+ *   When `csp.nonce === true`, we compute a fresh nonce in `beforeHandle`
+ *   and stash it on the context under the key `"csp-nonce"`. SSR handlers
+ *   that render inline `<script>` tags can read it with
+ *   `ctx.get<string>("csp-nonce")`. The same nonce is interpolated into the
+ *   CSP header in `afterHandle`, guaranteeing the tag and the header agree.
+ *
+ *   Auto-injection of the nonce into `renderToStream`'s hydration script
+ *   tags is intentionally out of scope for this middleware — see the
+ *   Phase 6.2 follow-up item in `CLAUDE.md`.
+ *
+ * @example
+ * ```ts
+ * import { secure } from "@mandujs/core/middleware";
+ *
+ * export default Mandu.filling()
+ *   .use(secure())                                 // all defaults
+ *   .get((ctx) => ctx.ok({ hello: "world" }));
+ *
+ * // With CSP nonce:
+ * export default Mandu.filling()
+ *   .use(secure({ csp: { nonce: true } }))
+ *   .get((ctx) => {
+ *     const nonce = ctx.get<string>("csp-nonce");
+ *     // render inline script with nonce={nonce}
+ *     return ctx.ok({ ok: true });
+ *   });
+ * ```
+ */
+import type { MiddlewarePlugin } from "../../filling/filling";
+import type { ManduContext } from "../../filling/context";
+import { buildCsp, type CspOptions } from "./csp";
+
+export { buildCsp, DEFAULT_CSP_DIRECTIVES } from "./csp";
+export type { CspOptions, BuiltCsp } from "./csp";
+
+// ========== Types ==========
+
+export type ReferrerPolicyValue =
+  | "no-referrer"
+  | "no-referrer-when-downgrade"
+  | "origin"
+  | "origin-when-cross-origin"
+  | "same-origin"
+  | "strict-origin"
+  | "strict-origin-when-cross-origin"
+  | "unsafe-url";
+
+export interface HstsOptions {
+  /** max-age in seconds. Default: 15552000 (180 days). */
+  maxAge?: number;
+  /** includeSubDomains directive. Default: true. */
+  includeSubDomains?: boolean;
+  /** preload directive. Default: false — opt-in; implies submitting to the preload list. */
+  preload?: boolean;
+}
+
+export interface SecureMiddlewareOptions {
+  /** Content-Security-Policy options, or `false` to disable. */
+  csp?: CspOptions | false;
+  /** Strict-Transport-Security options, or `false` to disable. */
+  hsts?: HstsOptions | false;
+  /** X-Frame-Options. Default: `"DENY"`. `false` to disable. */
+  frameOptions?: "DENY" | "SAMEORIGIN" | false;
+  /** X-Content-Type-Options: nosniff. Default: true. */
+  noSniff?: boolean;
+  /** Referrer-Policy. Default: `"strict-origin-when-cross-origin"`. */
+  referrerPolicy?: ReferrerPolicyValue | false;
+  /**
+   * Permissions-Policy map. Each entry becomes `feature=(allowlist)`.
+   * Use an empty array to deny a feature entirely (`feature=()`).
+   * `false` disables the header.
+   */
+  permissionsPolicy?: Record<string, string[]> | false;
+  /**
+   * X-XSS-Protection. Default: `"0"` — modern browsers should use CSP; the
+   * legacy auditor has known bypasses and is best disabled. `false` omits.
+   */
+  xssProtection?: "0" | "1" | "1; mode=block" | false;
+  /**
+   * Extra headers to set verbatim. Keys are set as-given (casing preserved
+   * by `Headers` normalization rules). Values overwrite any existing header.
+   */
+  extra?: Record<string, string>;
+}
+
+// ========== Defaults ==========
+
+const DEFAULT_HSTS: Required<HstsOptions> = Object.freeze({
+  maxAge: 15552000, // 180 days — matches Chrome's preload minimum
+  includeSubDomains: true,
+  preload: false,
+});
+
+const DEFAULT_REFERRER_POLICY: ReferrerPolicyValue = "strict-origin-when-cross-origin";
+
+/**
+ * OWASP-recommended deny-by-default for commonly abused browser capabilities.
+ *
+ * - `camera` / `microphone`: prevent drive-by media capture; app pages that
+ *   need these must opt in explicitly via override.
+ * - `geolocation`: prevents third-party scripts from geo-tagging users.
+ * - `payment`: blocks Payment Request API unless you explicitly own it.
+ * - `usb`: blocks WebUSB (e.g. hardware key attacks).
+ * - `interest-cohort`: opts out of FLoC/Topics tracking. Still widely
+ *   respected; cheap insurance.
+ */
+const DEFAULT_PERMISSIONS_POLICY: Record<string, string[]> = Object.freeze({
+  camera: [],
+  microphone: [],
+  geolocation: [],
+  payment: [],
+  usb: [],
+  "interest-cohort": [],
+}) as Record<string, string[]>;
+
+const CSP_NONCE_KEY = "csp-nonce";
+
+// ========== Public API ==========
+
+/**
+ * Build the secure headers middleware. The options argument is consumed
+ * eagerly at construction time — subsequent mutations to the passed object
+ * do not affect the already-installed middleware.
+ *
+ * Returns a `MiddlewarePlugin` with:
+ *   - `beforeHandle`: generates the per-request CSP nonce (if enabled) and
+ *     stashes it on the context for handler use.
+ *   - `afterHandle`: computes the final headers bundle and returns a new
+ *     Response with the headers applied. Existing headers from the handler
+ *     (e.g. `Content-Type`) are preserved.
+ */
+export function secure(options: SecureMiddlewareOptions = {}): MiddlewarePlugin {
+  // Normalize / snapshot options up front so we don't re-read user input on
+  // every request (protects against surprise mutation mid-session).
+  const cfg = normalizeOptions(options);
+
+  return {
+    beforeHandle: async (ctx: ManduContext): Promise<void> => {
+      // If CSP is enabled AND nonce is requested, compute the nonce here so
+      // the handler can read it before producing the response. We build the
+      // full CSP string in `afterHandle` (cheap) using the same nonce so
+      // the header and any handler-rendered <script nonce={...}> agree.
+      if (cfg.csp && cfg.csp.nonce === true) {
+        // buildCsp will synthesize a fresh nonce; we capture it here and
+        // pin it for the afterHandle pass via a per-request override.
+        const built = buildCsp({ ...cfg.csp, nonce: true });
+        if (built.nonce) {
+          ctx.set<string>(CSP_NONCE_KEY, built.nonce);
+        }
+      }
+    },
+
+    afterHandle: async (
+      ctx: ManduContext,
+      response: Response
+    ): Promise<Response> => {
+      const headers = new Headers(response.headers);
+      applySecureHeaders(ctx, headers, cfg);
+
+      // Only re-wrap if we actually added/changed something. In practice the
+      // headers map is always non-empty (we always set at least one header
+      // when options are default), but this keeps us honest about
+      // Response-body identity and matches `cors.ts`'s pattern.
+      return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+      });
+    },
+  };
+}
+
+/**
+ * Manual escape hatch: apply secure headers to an arbitrary Response using
+ * the options shape above.
+ *
+ * Prefer `.use(secure(...))` — this helper exists for callers outside the
+ * filling pipeline (e.g. custom error responders, static file handlers).
+ * Since no context is available, CSP nonce mode falls back to the one-shot
+ * nonce generated inside `buildCsp` — the caller is responsible for wiring
+ * that nonce into whatever they render.
+ */
+export function applySecureHeadersToResponse(
+  response: Response,
+  options: SecureMiddlewareOptions = {}
+): { response: Response; nonce?: string } {
+  const cfg = normalizeOptions(options);
+  const headers = new Headers(response.headers);
+
+  // Derive a fresh nonce for this standalone call (no context to cache it on).
+  let emittedNonce: string | undefined;
+  if (cfg.csp && cfg.csp.nonce === true) {
+    const built = buildCsp({ ...cfg.csp, nonce: true });
+    emittedNonce = built.nonce;
+  }
+
+  // Pseudo-context shim so applySecureHeaders can read the nonce consistently.
+  const shim = {
+    request: response as unknown as Request, // only used for URL scheme check; standalone callers skip HSTS logic path below via hsts=false typically
+    get: <T>(_key: string): T | undefined => emittedNonce as T | undefined,
+  };
+  applySecureHeaders(shim as unknown as ManduContext, headers, {
+    ...cfg,
+    // If caller didn't explicitly disable HSTS, keep it — but the scheme
+    // probe will simply no-op on a non-Request shim. Callers who want HSTS
+    // on standalone responses must ensure `response.url` carries an
+    // `https:` URL, or they should pass a pre-built Request with
+    // `x-forwarded-proto: https`.
+  });
+
+  return {
+    response: new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    }),
+    nonce: emittedNonce,
+  };
+}
+
+// ========== Internal: normalization ==========
+
+interface NormalizedOptions {
+  csp: CspOptions | null;
+  hsts: Required<HstsOptions> | null;
+  frameOptions: "DENY" | "SAMEORIGIN" | null;
+  noSniff: boolean;
+  referrerPolicy: ReferrerPolicyValue | null;
+  permissionsPolicy: Record<string, string[]> | null;
+  xssProtection: "0" | "1" | "1; mode=block" | null;
+  extra: Record<string, string>;
+}
+
+function normalizeOptions(options: SecureMiddlewareOptions): NormalizedOptions {
+  return {
+    csp: options.csp === false ? null : options.csp ?? {},
+    hsts:
+      options.hsts === false
+        ? null
+        : { ...DEFAULT_HSTS, ...(options.hsts ?? {}) },
+    frameOptions:
+      options.frameOptions === false
+        ? null
+        : options.frameOptions ?? "DENY",
+    noSniff: options.noSniff !== false,
+    referrerPolicy:
+      options.referrerPolicy === false
+        ? null
+        : options.referrerPolicy ?? DEFAULT_REFERRER_POLICY,
+    permissionsPolicy:
+      options.permissionsPolicy === false
+        ? null
+        : options.permissionsPolicy ?? { ...DEFAULT_PERMISSIONS_POLICY },
+    xssProtection:
+      options.xssProtection === false ? null : options.xssProtection ?? "0",
+    extra: options.extra ?? {},
+  };
+}
+
+// ========== Internal: header application ==========
+
+function applySecureHeaders(
+  ctx: ManduContext,
+  headers: Headers,
+  cfg: NormalizedOptions
+): void {
+  // --- CSP ---
+  if (cfg.csp) {
+    // If a nonce was pre-computed in beforeHandle, reuse it to ensure the
+    // handler's nonce=… values match what we emit in the header.
+    const pinnedNonce = ctx.get<string>(CSP_NONCE_KEY);
+    const effective =
+      pinnedNonce && cfg.csp.nonce === true
+        ? { ...cfg.csp, nonce: pinnedNonce }
+        : cfg.csp;
+
+    const built = buildCsp(effective);
+    headers.set(built.name, built.header);
+  }
+
+  // --- HSTS (only when the request is already HTTPS) ---
+  //
+  // RFC 6797 §7.2: UAs MUST ignore STS on insecure transport, but we also
+  // suppress it server-side to avoid leaking the policy across a plaintext
+  // channel (where an active MITM could strip it for first-visit users
+  // anyway — the "TOFU" problem HSTS is designed to reduce).
+  if (cfg.hsts && isHttps(ctx.request)) {
+    const parts = [`max-age=${Math.floor(cfg.hsts.maxAge)}`];
+    if (cfg.hsts.includeSubDomains) parts.push("includeSubDomains");
+    if (cfg.hsts.preload) parts.push("preload");
+    headers.set("Strict-Transport-Security", parts.join("; "));
+  }
+
+  // --- X-Frame-Options ---
+  if (cfg.frameOptions) {
+    headers.set("X-Frame-Options", cfg.frameOptions);
+  }
+
+  // --- X-Content-Type-Options ---
+  if (cfg.noSniff) {
+    headers.set("X-Content-Type-Options", "nosniff");
+  }
+
+  // --- Referrer-Policy ---
+  if (cfg.referrerPolicy) {
+    headers.set("Referrer-Policy", cfg.referrerPolicy);
+  }
+
+  // --- Permissions-Policy ---
+  if (cfg.permissionsPolicy) {
+    const pp = buildPermissionsPolicy(cfg.permissionsPolicy);
+    if (pp.length > 0) {
+      headers.set("Permissions-Policy", pp);
+    }
+  }
+
+  // --- X-XSS-Protection ---
+  if (cfg.xssProtection !== null) {
+    headers.set("X-XSS-Protection", cfg.xssProtection);
+  }
+
+  // --- Arbitrary extras (caller overrides always win) ---
+  for (const [k, v] of Object.entries(cfg.extra)) {
+    headers.set(k, v);
+  }
+}
+
+/**
+ * Build a Permissions-Policy header value.
+ *
+ * Grammar (simplified): `feature=(allowlist) , feature=(allowlist)`
+ *   - Bare tokens like `self` go inside the parens as-is.
+ *   - Origins (URLs) must be wrapped in double quotes per spec.
+ *   - Empty allowlist `()` denies the feature entirely.
+ *
+ * We accept the caller's array verbatim; they are responsible for quoting
+ * their URL-shaped entries. We do wrap origins that look URL-ish (contain
+ * `://`) when they are unquoted, because that's by far the most common
+ * mistake and the cost of the heuristic is tiny.
+ */
+function buildPermissionsPolicy(map: Record<string, string[]>): string {
+  const entries: string[] = [];
+  for (const [feature, allowlist] of Object.entries(map)) {
+    if (!Array.isArray(allowlist)) continue;
+    const items = allowlist.map(normalizePermissionsItem).join(" ");
+    entries.push(`${feature}=(${items})`);
+  }
+  return entries.join(", ");
+}
+
+function normalizePermissionsItem(raw: string): string {
+  if (raw === "self" || raw === "*") return raw;
+  if (raw.startsWith('"') && raw.endsWith('"')) return raw;
+  if (raw.includes("://")) return `"${raw}"`;
+  return raw;
+}
+
+/**
+ * Determine whether the inbound request is HTTPS.
+ *
+ * Recognizes:
+ *   1. Direct `https:` scheme in `request.url`
+ *   2. `X-Forwarded-Proto: https` (de-facto reverse-proxy header)
+ *   3. `Forwarded: proto=https` (RFC 7239)
+ *
+ * We intentionally don't trust these headers on direct (non-proxied)
+ * connections — but since the caller is the one opting into HSTS, they're
+ * also responsible for running behind a reverse proxy that sanitizes
+ * client-supplied `Forwarded` / `X-Forwarded-*` headers. This matches
+ * Helmet's and express's documented behavior.
+ */
+function isHttps(request: Request): boolean {
+  try {
+    if (request.url.startsWith("https:")) return true;
+  } catch {
+    // Some shims may throw on `.url`; fall through to header checks.
+  }
+  const xfp = safeGetHeader(request, "x-forwarded-proto");
+  if (xfp && xfp.split(",")[0]!.trim().toLowerCase() === "https") return true;
+  const fwd = safeGetHeader(request, "forwarded");
+  if (fwd && /\bproto=https\b/i.test(fwd)) return true;
+  return false;
+}
+
+function safeGetHeader(request: Request, name: string): string | null {
+  try {
+    return request.headers?.get(name) ?? null;
+  } catch {
+    return null;
+  }
+}