@daloyjs/core 0.15.0 → 0.17.0

package/README.md

@@ -380,7 +380,7 @@ What works today, at a glance:
 
 - Contract-first routing, Standard Schema validation (Zod 4 / Valibot / ArkType / TypeBox), and OpenAPI 3.1 from a single source of truth.
 - Adapters for Node (Heroku/Railway/Render/Fly.io), Bun, Deno, Cloudflare Workers, Vercel Node / Edge / Next.js / Netlify Edge, Fastly Compute, and AWS Lambda / Netlify Functions / Lambda Function URLs.
-- Built-in security primitives (body limits, prototype-pollution-safe JSON, path-traversal guard, request timeouts, header injection guards, **duplicate `Host` / `Content-Length` rejection**, **stripped `Server` / `X-Powered-By` headers by default**, **structured-log redaction defaults** for authorization / cookie / password / token / JWT-shaped values) plus first-party middleware (`secureHeaders` with CSP nonce + Trusted Types, `cors`, `rateLimit`, `requestId`, `bearerAuth`, `basicAuth`, `csrf` with **double-submit cookie** + **Fetch-Metadata** strategies, `session`, `timing` / `timingSafeEqual`) and **zero-knob crypto helpers** (`passwordHash` / `passwordVerify` at `@daloyjs/core/hashing`, `verifyWebhookSignature` / `signWebhookPayload`).
+- Built-in security primitives (body limits, prototype-pollution-safe JSON, path-traversal guard, request timeouts, header injection guards, **duplicate `Host` / `Content-Length` rejection**, **stripped `Server` / `X-Powered-By` headers by default**, **structured-log redaction defaults** for authorization / cookie / password / token / JWT-shaped values, **`secureHeaders()` auto-applied since `0.16.0`** with user-installed overrides automatically replacing the auto instance, **cross-origin state-changing requests rejected with `403` since `0.16.0`** unless a route's `cors()` policy allows the request origin, **refuse-to-boot on weak session secrets, `cors({ origin: "*" })`, `session()` + state-changing route without `csrf()`, and unconfigured `X-Forwarded-*` in production since `0.17.0`** — all four checks opt-out via `app({ secureDefaults: false })`) plus first-party middleware (`secureHeaders` with CSP nonce + Trusted Types, `cors`, `rateLimit`, `requestId`, `bearerAuth`, `basicAuth`, `csrf` with **double-submit cookie** + **Fetch-Metadata** strategies, `session`, `timing` / `timingSafeEqual`) and **zero-knob crypto helpers** (`passwordHash` / `passwordVerify` at `@daloyjs/core/hashing`, `verifyWebhookSignature` / `signWebhookPayload`).
 - Streaming helpers (SSE + NDJSON), multipart ergonomics, OpenTelemetry-compatible tracing, signed-cookie sessions with pluggable stores, and a Redis-backed rate-limit store at `@daloyjs/core/rate-limit-redis`.
 - WebSocket primitives with the same Bun-style handler shape (`open`/`message`/`close`/`drain`/`error`) running on both Node and Bun adapters, plus typed `app.ws(path, handler)` registration and route-table awareness so the upgrade listener is only installed when WS routes exist.
 - Pretty `printStartupBanner()` / `formatStartupBanner()` startup helpers at `@daloyjs/core/banner`, used by every starter template so `pnpm dev` greets you with a colorized boxed panel (TTY + `NO_COLOR` / `FORCE_COLOR` aware, with an ASCII fallback for dumb terminals).

package/dist/app.d.ts

@@ -3,6 +3,7 @@ import { type Logger } from "./logger.js";
 import type { HttpMethod, Hooks, PathString, RequestSchemas, ResponsesMap, RouteDefinition } from "./types.js";
 import { type OpenAPIInfo, type OpenAPIOptions } from "./openapi.js";
 import { type DocsContentSecurityPolicyOptions, type ScalarReferenceConfiguration } from "./docs.js";
+import { type SecureHeadersOptions } from "./middleware.js";
 /**
  * Configuration accepted by {@link App}'s constructor. Every field is
  * optional; sensible production defaults are applied.
@@ -58,6 +59,79 @@ export interface AppOptions {
      * @since 0.15.0
      */
     stripServerHeaders?: boolean;
+    /**
+     * Master switch for the secure-by-default Wave 2 surface (auto-applied
+     * {@link secureHeaders}, cross-origin guard for state-changing requests
+      * when no {@link cors} hook allows the request origin). Defaults to `true`
+      * in `@daloyjs/core@0.16.0` and later. Per-feature opt-outs
+     * (`secureHeaders: false`, `corsCrossOriginGuard: false`) remain available
+     * when this is left on. Pass `false` to restore the pre-0.16 behavior
+     * wholesale.
+     *
+     * @since 0.16.0
+     */
+    secureDefaults?: boolean;
+    /**
+     * Auto-install {@link secureHeaders} as a global hook so every response
+     * carries hardened defaults (HSTS, X-Frame-Options, nosniff, strict
+     * referrer, COOP/CORP, default CSP, etc.). Active when
+     * {@link AppOptions.secureDefaults} is not `false`. Pass `false` to skip
+     * the auto-install (you may still register your own `secureHeaders()` via
+     * `app.use(...)`). Pass an options object to override the defaults of the
+     * auto-installed instance.
+     *
+     * @since 0.16.0
+     */
+    secureHeaders?: SecureHeadersOptions | false;
+    /**
+     * Reject state-changing requests (`POST`, `PUT`, `PATCH`, `DELETE`) that
+      * carry a cross-origin `Origin` header when no {@link cors} hook in the
+      * matched route's hook chain allows that origin. Active when
+      * {@link AppOptions.secureDefaults} is not `false`. Returns
+      * `403 application/problem+json` so the rejection is loud at the network
+      * boundary instead of silently allowing a CSRF / SSRF surface. Set to
+      * `false` if you intentionally serve a cross-origin API without `cors()`
+      * (rare; almost always a misconfiguration).
+     *
+     * @since 0.16.0
+     */
+    corsCrossOriginGuard?: boolean;
+    /**
+     * Declare whether the application sits behind a trusted reverse proxy
+     * that populates `X-Forwarded-*` headers (load balancer, CDN, Vercel,
+     * Cloudflare, AWS ALB, etc.). The value is opt-in tri-state for the
+     * Wave 3 first-request guard:
+     *
+     * - `undefined` (default) — *unconfigured*. The framework returns
+     *   `500 problem+json` on the first request that carries an
+     *   `X-Forwarded-*` header so a misconfigured proxy chain cannot silently
+     *   leak spoofed client IPs to the rate limiter, audit logs, or
+     *   request-id propagation. Disabled when {@link AppOptions.secureDefaults}
+     *   is `false`.
+     * - `true` — *trust*. The framework reads `X-Forwarded-*` without
+     *   suspicion. Use only when every request passes through a proxy chain
+     *   you control.
+     * - `false` — *explicitly do not trust*. The framework ignores
+     *   `X-Forwarded-*` even when present and silences the unconfigured-proxy
+     *   guard. Use when the application is exposed directly to the public
+     *   internet on purpose.
+     *
+     * @since 0.17.0
+     */
+    trustProxy?: boolean;
+    /**
+     * Opt-out for the Wave 3 boot guard that refuses to start an App which
+     * registers {@link session} and any state-changing route without a
+     * matching {@link csrf} hook. Set to `"off"` to acknowledge that you
+     * intentionally accept cookie-authenticated POST / PUT / PATCH / DELETE
+     * requests without CSRF protection (SPA + bearer-token apps, internal
+     * services on a private network, etc.). Leave unset (the default) for
+     * any browser-facing API: the boot error includes one-line copy-paste
+     * remediation. Disabled when {@link AppOptions.secureDefaults} is `false`.
+     *
+     * @since 0.17.0
+     */
+    csrf?: "off";
     /** Pluggable logger. Default: structured JSON logger at "info" (or noop in test). */
     logger?: Logger | {
         level?: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
@@ -267,6 +341,8 @@ export declare class App {
     private groupHooks;
     private groupTags;
     private groupAuth?;
+    /** Effective security markers for each registered route hook chain. */
+    private routeSecurityMarkers;
     /** Decorator bag merged into ctx.state on every request. */
     private decorations;
     private installedPlugins;
@@ -279,7 +355,40 @@ export declare class App {
     /** In-flight request count for graceful shutdown. */
     private inflight;
     private draining;
+    /**
+      * CORS origin allowlist predicates from the currently active group-level
+      * hooks. Used for unmatched routes; matched routes use the snapshot stored
+      * on their compiled route so later `app.use(cors(...))` calls do not
+      * retroactively loosen earlier routes.
+     */
+    private corsOriginAllows;
+    /**
+     * Whether the Wave 3 once-only boot guard has run (session + CSRF +
+     * state-changing-route check). The check is deferred to first request
+     * because route registration and `app.use(csrf(...))` can happen in any
+     * order after construction; doing it on first `fetch()` is the latest
+     * point we still get a 500 before any handler ever runs.
+     */
+    private wave3BootGuard;
+    /**
+     * Latched marker stamped after the framework has reported the first
+     * unconfigured-proxy request. Logged once at `warn` level so production
+     * dashboards see the misconfiguration without flooding on every retry.
+     */
+    private trustProxyWarned;
     constructor(options?: AppOptions);
+    /**
+     * Install the Wave 2 secure-by-default global hooks. Currently:
+     *  - {@link secureHeaders} as a group-level hook so every response carries
+     *    the hardened baseline (HSTS, X-Frame-Options, nosniff, default CSP).
+     *
+     * Called once during construction — the CORS cross-origin guard lives
+     * inside {@link App.fetch} because it needs the live request to decide.
+     * The auto-installed `secureHeaders` instance only sets headers when the
+     * response does not already carry them, so user-supplied
+     * `app.use(secureHeaders({...}))` still wins per-header.
+     */
+    private installSecureDefaults;
     /**
      * Emit a one-time `warn` when the explicit {@link AppOptions.env} option
      * disagrees with `process.env.NODE_ENV`. Silent when either signal is
@@ -293,6 +402,60 @@ export declare class App {
      * auto-mount and error response detail stripping.
      */
     private isProduction;
+    /**
+     * Wave 2 cross-origin guard. Rejects state-changing requests (`POST` /
+     * `PUT` / `PATCH` / `DELETE`) that carry an `Origin` header pointing at a
+     * different origin than the request URL when no {@link cors} hook is
+     * registered (neither at the app level nor on the matched route). Throws
+     * a {@link ForbiddenError} that surfaces as `403 application/problem+json`
+     * so the rejection is loud rather than silently allowing the unintended
+     * cross-origin write.
+     *
+     * Disabled when {@link AppOptions.secureDefaults} is `false` or
+     * {@link AppOptions.corsCrossOriginGuard} is `false`. Same-origin
+     * requests, GET / HEAD / OPTIONS, requests with no `Origin` header, and
+     * routes whose hook chain includes a `cors()` policy allowing the origin
+     * are unaffected.
+     */
+    private assertCrossOriginAllowed;
+    /**
+     * Wave 3 sync boot guard. Inspects a hook layer being installed via
+     * {@link App.use} and refuses-to-boot when:
+     *
+     *  - `cors({ origin: "*" })` is registered while resolved environment is
+     *    `production`;
+     *  - `session({ secret })` is registered while resolved environment is
+     *    `production` and any secret fails {@link assertStrongSecret}.
+     *
+     * Disabled when `secureDefaults: false`. Thrown errors propagate out of
+     * `app.use(...)` so the process exits during startup rather than serving
+     * a misconfigured surface.
+     */
+    private assertSecureHookConfig;
+    private resetWave3BootGuardCache;
+    /**
+     * Wave 3 first-request boot guard. Verifies that the assembled hook
+     * chain + route table is internally consistent before any user handler
+     * runs. Currently checks: when `session()` is installed and any route
+     * accepts a state-changing method (`POST` / `PUT` / `PATCH` / `DELETE`),
+     * a `csrf()` hook (or third-party equivalent stamped with
+     * {@link CSRF_HOOK_MARKER}) must also be present in that route's effective
+     * hook chain. Opt out with `app({ csrf: "off" })` or
+     * `app({ secureDefaults: false })`. Runs once per App between registration
+     * changes; the result is cached so the fast path is a single boolean check.
+     */
+    private assertWave3BootGuards;
+    /**
+     * Wave 3 per-request guard for spoofed proxy headers. When the App was
+     * constructed without an explicit {@link AppOptions.trustProxy} value
+     * and a request arrives carrying an `X-Forwarded-*` header, refuse to
+     * dispatch it: the rate limiter, audit log, and request-id propagation
+     * would otherwise honour the attacker-supplied IP. Returns a structured
+     * `500 problem+json` so the failure is loud at the network boundary.
+     * Disabled when `secureDefaults: false` or when `trustProxy` is set to
+     * `true` or `false` explicitly.
+     */
+    private assertTrustProxyConfigured;
     /**
      * Resolve the {@link AppOptions.docs} option and, when enabled, register
      * the `/openapi.json` + `/docs` routes. Called once during construction so

package/dist/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/app.js

@@ -1,11 +1,14 @@
 import { Router } from "./router.js";
 import { WebSocketRegistry } from "./websocket.js";
-import { BadRequestError, HttpError, InternalError, MethodNotAllowedError, NotFoundError, PayloadTooLargeError, RequestTimeoutError, UnsupportedMediaTypeError, ValidationError, } from "./errors.js";
+import { BadRequestError, ForbiddenError, HttpError, InternalError, MethodNotAllowedError, NotFoundError, PayloadTooLargeError, RequestTimeoutError, UnsupportedMediaTypeError, ValidationError, } from "./errors.js";
 import { validate } from "./schema.js";
-import { readBodyLimited, safeJsonParse, randomId, assertNoDuplicateSingletonHeaders } from "./security.js";
+import { readBodyLimited, safeJsonParse, randomId, assertNoDuplicateSingletonHeaders, assertStrongSecret } from "./security.js";
 import { createLogger, noopLogger } from "./logger.js";
 import { generateOpenAPI, openapiToYAML, } from "./openapi.js";
 import { docsContentSecurityPolicy, scalarHtml, swaggerUiHtml, } from "./docs.js";
+import { secureHeaders as secureHeadersMiddleware, CORS_HOOK_MARKER, CORS_ORIGIN_ALLOW_MARKER, CORS_WILDCARD_ORIGIN_MARKER, CSRF_HOOK_MARKER, SECURE_HEADERS_MARKER, } from "./middleware.js";
+import { SESSION_HOOK_MARKER, SESSION_SECRETS_MARKER, } from "./session.js";
+const AUTO_SECURE_HEADERS_MARKER = Symbol.for("daloyjs.app.autoSecureHeaders");
 const DEFAULTS = {
     bodyLimitBytes: 1024 * 1024,
     requestTimeoutMs: 30_000,
@@ -72,6 +75,8 @@ export class App {
     groupHooks = [];
     groupTags = [];
     groupAuth;
+    /** Effective security markers for each registered route hook chain. */
+    routeSecurityMarkers = [];
     /** Decorator bag merged into ctx.state on every request. */
     decorations = {};
     installedPlugins = new Set();
@@ -84,6 +89,27 @@ export class App {
     /** In-flight request count for graceful shutdown. */
     inflight = 0;
     draining = false;
+    /**
+      * CORS origin allowlist predicates from the currently active group-level
+      * hooks. Used for unmatched routes; matched routes use the snapshot stored
+      * on their compiled route so later `app.use(cors(...))` calls do not
+      * retroactively loosen earlier routes.
+     */
+    corsOriginAllows = [];
+    /**
+     * Whether the Wave 3 once-only boot guard has run (session + CSRF +
+     * state-changing-route check). The check is deferred to first request
+     * because route registration and `app.use(csrf(...))` can happen in any
+     * order after construction; doing it on first `fetch()` is the latest
+     * point we still get a 500 before any handler ever runs.
+     */
+    wave3BootGuard = { checked: false };
+    /**
+     * Latched marker stamped after the framework has reported the first
+     * unconfigured-proxy request. Logged once at `warn` level so production
+     * dashboards see the misconfiguration without flooding on every retry.
+     */
+    trustProxyWarned = false;
     constructor(options = {}) {
         this.options = {
             validateResponses: options.validateResponses ?? DEFAULTS.validateResponses,
@@ -99,8 +125,35 @@ export class App {
                     ? options.logger
                     : createLogger({ level: options.logger?.level ?? "info" });
         this.warnOnEnvMismatch();
+        if (this.options.hooks)
+            this.assertSecureHookConfig(this.options.hooks);
+        this.installSecureDefaults();
         this.maybeMountDocs();
     }
+    /**
+     * Install the Wave 2 secure-by-default global hooks. Currently:
+     *  - {@link secureHeaders} as a group-level hook so every response carries
+     *    the hardened baseline (HSTS, X-Frame-Options, nosniff, default CSP).
+     *
+     * Called once during construction — the CORS cross-origin guard lives
+     * inside {@link App.fetch} because it needs the live request to decide.
+     * The auto-installed `secureHeaders` instance only sets headers when the
+     * response does not already carry them, so user-supplied
+     * `app.use(secureHeaders({...}))` still wins per-header.
+     */
+    installSecureDefaults() {
+        if (this.options.secureDefaults === false)
+            return;
+        if (this.options.secureHeaders !== false) {
+            const opts = this.options.secureHeaders &&
+                typeof this.options.secureHeaders === "object"
+                ? this.options.secureHeaders
+                : {};
+            const auto = secureHeadersMiddleware(opts);
+            auto[AUTO_SECURE_HEADERS_MARKER] = true;
+            this.groupHooks.push(auto);
+        }
+    }
     /**
      * Emit a one-time `warn` when the explicit {@link AppOptions.env} option
      * disagrees with `process.env.NODE_ENV`. Silent when either signal is
@@ -132,6 +185,170 @@ export class App {
             typeof process.env !== "undefined" &&
             process.env.NODE_ENV === "production");
     }
+    /**
+     * Wave 2 cross-origin guard. Rejects state-changing requests (`POST` /
+     * `PUT` / `PATCH` / `DELETE`) that carry an `Origin` header pointing at a
+     * different origin than the request URL when no {@link cors} hook is
+     * registered (neither at the app level nor on the matched route). Throws
+     * a {@link ForbiddenError} that surfaces as `403 application/problem+json`
+     * so the rejection is loud rather than silently allowing the unintended
+     * cross-origin write.
+     *
+     * Disabled when {@link AppOptions.secureDefaults} is `false` or
+     * {@link AppOptions.corsCrossOriginGuard} is `false`. Same-origin
+     * requests, GET / HEAD / OPTIONS, requests with no `Origin` header, and
+     * routes whose hook chain includes a `cors()` policy allowing the origin
+     * are unaffected.
+     */
+    assertCrossOriginAllowed(request, url, method, corsOriginAllows) {
+        if (this.options.secureDefaults === false)
+            return;
+        if (this.options.corsCrossOriginGuard === false)
+            return;
+        if (method !== "POST" &&
+            method !== "PUT" &&
+            method !== "PATCH" &&
+            method !== "DELETE") {
+            return;
+        }
+        const origin = request.headers.get("origin");
+        if (!origin || origin === "null")
+            return;
+        let originUrl;
+        try {
+            originUrl = new URL(origin);
+        }
+        catch {
+            // Malformed Origin header — refuse loudly.
+            throw new ForbiddenError("Cross-origin state-changing request rejected: malformed Origin header.");
+        }
+        if (originUrl.origin === url.origin)
+            return;
+        if (corsOriginAllows.some((allows) => allows(origin)))
+            return;
+        throw new ForbiddenError(`Cross-origin ${method} from "${originUrl.origin}" rejected: no registered cors() policy allows that origin. ` +
+            `Register cors({ origin: [...] }) via app.use(...) to allow it, or pass ` +
+            `app({ corsCrossOriginGuard: false }) / app({ secureDefaults: false }) to disable this guard.`);
+    }
+    /**
+     * Wave 3 sync boot guard. Inspects a hook layer being installed via
+     * {@link App.use} and refuses-to-boot when:
+     *
+     *  - `cors({ origin: "*" })` is registered while resolved environment is
+     *    `production`;
+     *  - `session({ secret })` is registered while resolved environment is
+     *    `production` and any secret fails {@link assertStrongSecret}.
+     *
+     * Disabled when `secureDefaults: false`. Thrown errors propagate out of
+     * `app.use(...)` so the process exits during startup rather than serving
+     * a misconfigured surface.
+     */
+    assertSecureHookConfig(hooks) {
+        if (this.options.secureDefaults === false)
+            return;
+        if (!this.isProduction())
+            return;
+        const record = hooks;
+        if (record[CORS_WILDCARD_ORIGIN_MARKER] === true) {
+            throw new Error('cors({ origin: "*" }) refused in production: a wildcard CORS origin exposes every state-changing route cross-origin. ' +
+                "Replace the wildcard with an explicit allowlist (string[] or predicate), or pass " +
+                "app({ secureDefaults: false }) to disable this guard.");
+        }
+        if (record[SESSION_HOOK_MARKER] === true) {
+            const secrets = record[SESSION_SECRETS_MARKER];
+            if (Array.isArray(secrets)) {
+                for (const s of secrets) {
+                    assertStrongSecret(s, "session");
+                }
+            }
+        }
+    }
+    resetWave3BootGuardCache() {
+        this.wave3BootGuard.checked = false;
+        this.wave3BootGuard.error = undefined;
+    }
+    /**
+     * Wave 3 first-request boot guard. Verifies that the assembled hook
+     * chain + route table is internally consistent before any user handler
+     * runs. Currently checks: when `session()` is installed and any route
+     * accepts a state-changing method (`POST` / `PUT` / `PATCH` / `DELETE`),
+     * a `csrf()` hook (or third-party equivalent stamped with
+     * {@link CSRF_HOOK_MARKER}) must also be present in that route's effective
+     * hook chain. Opt out with `app({ csrf: "off" })` or
+     * `app({ secureDefaults: false })`. Runs once per App between registration
+     * changes; the result is cached so the fast path is a single boolean check.
+     */
+    assertWave3BootGuards() {
+        if (this.wave3BootGuard.checked) {
+            if (this.wave3BootGuard.error)
+                throw this.wave3BootGuard.error;
+            return;
+        }
+        this.wave3BootGuard.checked = true;
+        if (this.options.secureDefaults === false)
+            return;
+        if (this.options.csrf === "off")
+            return;
+        // Per the risk register: boot guards only fire in production so CI /
+        // staging surfaces that ship sample secrets / no CSRF token while
+        // iterating do not pay the refuse-to-boot cost.
+        if (!this.isProduction())
+            return;
+        const stateChanging = this.routeSecurityMarkers.find((r) => isStateChangingMethod(r.method) && r.hasSession && !r.hasCsrf);
+        if (!stateChanging)
+            return;
+        const err = new Error(`session() is registered in the hook chain for a state-changing route ` +
+            `(${stateChanging.method} ${stateChanging.path}) but no csrf() hook is installed. ` +
+            `Register csrf() via app.use(csrf({ strategy: "fetch-metadata", allowedOrigins: [...] })), ` +
+            `or pass app({ csrf: "off" }) to acknowledge that this app is not browser-facing.`);
+        this.wave3BootGuard.error = err;
+        throw err;
+    }
+    /**
+     * Wave 3 per-request guard for spoofed proxy headers. When the App was
+     * constructed without an explicit {@link AppOptions.trustProxy} value
+     * and a request arrives carrying an `X-Forwarded-*` header, refuse to
+     * dispatch it: the rate limiter, audit log, and request-id propagation
+     * would otherwise honour the attacker-supplied IP. Returns a structured
+     * `500 problem+json` so the failure is loud at the network boundary.
+     * Disabled when `secureDefaults: false` or when `trustProxy` is set to
+     * `true` or `false` explicitly.
+     */
+    assertTrustProxyConfigured(request) {
+        if (this.options.secureDefaults === false)
+            return;
+        if (this.options.trustProxy !== undefined)
+            return;
+        // Same risk-register clause as the session/CSRF guard: only enforce
+        // in production. Dev/CI surfaces routinely test forwarded headers
+        // without configuring a reverse-proxy posture.
+        if (!this.isProduction())
+            return;
+        const headers = request.headers;
+        let found;
+        for (const name of [
+            "x-forwarded-for",
+            "x-forwarded-host",
+            "x-forwarded-proto",
+            "x-forwarded-port",
+            "x-real-ip",
+        ]) {
+            if (headers.has(name)) {
+                found = name;
+                break;
+            }
+        }
+        if (!found)
+            return;
+        if (!this.trustProxyWarned) {
+            this.trustProxyWarned = true;
+            this.log.warn({ event: "trust-proxy.unconfigured", header: found }, `Request carried ${found} but app({ trustProxy }) is unset; refusing to honour spoofable proxy headers.`);
+        }
+        throw new InternalError(`Refusing to dispatch request: ${found} header is present but app({ trustProxy }) is unconfigured. ` +
+            `Pass app({ trustProxy: true }) when running behind a trusted reverse proxy, ` +
+            `or app({ trustProxy: false }) to ignore forwarded headers, ` +
+            `or app({ secureDefaults: false }) to disable this guard.`);
+    }
     /**
      * Resolve the {@link AppOptions.docs} option and, when enabled, register
      * the `/openapi.json` + `/docs` routes. Called once during construction so
@@ -291,6 +508,8 @@ export class App {
      * @returns This `App` instance for chaining.
      */
     route(def) {
+        if (def.hooks)
+            this.assertSecureHookConfig(def.hooks);
         const fullPath = joinPath(this.prefix, def.path);
         const merged = {
             ...def,
@@ -298,9 +517,21 @@ export class App {
             tags: [...(this.groupTags ?? []), ...(def.tags ?? [])],
             auth: def.auth ?? this.groupAuth,
         };
-        const hooks = mergeHooks([...this.groupHooks, def.hooks ?? {}]);
-        this.router.add(def.method, fullPath, { def: merged, hooks }, def.operationId);
+        const sources = [...this.groupHooks, def.hooks ?? {}];
+        const hooks = mergeHooks(sources);
+        const corsOriginAllows = corsOriginAllowsFromHooks(sources);
+        const securityMarkers = securityMarkersFromHooks([
+            this.options.hooks ?? {},
+            ...sources,
+        ]);
+        this.router.add(def.method, fullPath, { def: merged, hooks, corsOriginAllows }, def.operationId);
         this.routes.push(merged);
+        this.routeSecurityMarkers.push({
+            method: merged.method,
+            path: merged.path,
+            ...securityMarkers,
+        });
+        this.resetWave3BootGuardCache();
         return this;
     }
     /**
@@ -340,6 +571,8 @@ export class App {
      * @returns This `App` instance for chaining.
      */
     group(prefix, config, register) {
+        if (config.hooks)
+            this.assertSecureHookConfig(config.hooks);
         // Child apps share the parent's router/routes/etc. Disable docs auto-mount
         // on the child so it does not re-register the parent's `/openapi.json` and
         // `/docs` routes (which would throw "Duplicate route").
@@ -347,12 +580,15 @@ export class App {
         child.router = this.router;
         child.routes = this.routes;
         child.webSocketRoutes = this.webSocketRoutes;
+        child.routeSecurityMarkers = this.routeSecurityMarkers;
+        child.wave3BootGuard = this.wave3BootGuard;
         child.log = this.log;
         child.prefix = joinPath(this.prefix, prefix);
         child.groupHooks = [
             ...this.groupHooks,
             ...(config.hooks ? [config.hooks] : []),
         ];
+        child.corsOriginAllows = corsOriginAllowsFromHooks(child.groupHooks);
         child.groupTags = [...this.groupTags, ...(config.tags ?? [])];
         child.groupAuth = config.auth ?? this.groupAuth;
         child.decorations = this.decorations;
@@ -382,7 +618,27 @@ export class App {
      * @returns This `App` instance for chaining.
      */
     use(hooks) {
+        // Wave 3 boot guards: refuse to start when the new hook layer is a
+        // known-misconfigured security primitive in production. These checks
+        // run synchronously at registration time so the developer sees the
+        // failure during boot, not on first request.
+        this.assertSecureHookConfig(hooks);
+        // If the developer installs their own secureHeaders(), drop the
+        // Wave 2 auto-installed instance so the user's overrides win instead of
+        // being shadowed (the auto one runs first and the per-header
+        // "set only if absent" semantics mean the second installation would be
+        // a silent no-op).
+        if (hooks[SECURE_HEADERS_MARKER] === true) {
+            const autoIdx = this.groupHooks.findIndex((h) => h[AUTO_SECURE_HEADERS_MARKER] ===
+                true);
+            if (autoIdx >= 0)
+                this.groupHooks.splice(autoIdx, 1);
+        }
         this.groupHooks.push(hooks);
+        if (hooks[CORS_HOOK_MARKER] === true) {
+            this.corsOriginAllows = corsOriginAllowsFromHooks(this.groupHooks);
+        }
+        this.resetWave3BootGuardCache();
         return this;
     }
     /**
@@ -574,12 +830,18 @@ export class App {
         let activeSendHook = globalHooks.onSend;
         try {
             assertNoDuplicateSingletonHeaders(request.headers);
+            this.assertTrustProxyConfigured(request);
+            this.assertWave3BootGuards();
             await globalHooks.onRequest?.(request);
             const url = new URL(request.url);
             const method = request.method;
             const headFallback = method === "HEAD";
             const match = this.router.find(method, url.pathname) ??
                 (headFallback ? this.router.find("GET", url.pathname) : undefined);
+            this.assertCrossOriginAllowed(request, url, method, [
+                ...corsOriginAllowsFromHooks([this.options.hooks ?? {}]),
+                ...(match ? match.handler.corsOriginAllows : this.corsOriginAllows),
+            ]);
             if (!match) {
                 const allowed = this.router.allowedMethods(url.pathname);
                 ctx = {
@@ -800,6 +1062,41 @@ function joinPath(a, b) {
     const joined = `${left}${right}`;
     return joined === "" ? "/" : joined;
 }
+function corsOriginAllowsFromHooks(layers) {
+    const allows = [];
+    for (const hooks of layers) {
+        const record = hooks;
+        const allow = record[CORS_ORIGIN_ALLOW_MARKER];
+        if (typeof allow === "function") {
+            allows.push(allow);
+        }
+        else if (record[CORS_HOOK_MARKER] === true) {
+            // Third-party CORS helpers can still opt out of the guard with the
+            // original marker. The first-party cors() stamps a stricter predicate
+            // above, so disallowed origins are rejected before the handler runs.
+            allows.push(() => true);
+        }
+    }
+    return allows;
+}
+function securityMarkersFromHooks(layers) {
+    let hasSession = false;
+    let hasCsrf = false;
+    for (const hooks of layers) {
+        const record = hooks;
+        if (record[SESSION_HOOK_MARKER] === true)
+            hasSession = true;
+        if (record[CSRF_HOOK_MARKER] === true)
+            hasCsrf = true;
+    }
+    return { hasSession, hasCsrf };
+}
+function isStateChangingMethod(method) {
+    return (method === "POST" ||
+        method === "PUT" ||
+        method === "PATCH" ||
+        method === "DELETE");
+}
 function mergeHooks(layers) {
     const pick = (key) => layers
         .map((h) => h[key])
@@ -906,7 +1203,7 @@ async function buildContext(request, url, rawParams, def, opts) {
     }
     if (def.request?.body) {
         const ct = (request.headers.get("content-type") ?? "").toLowerCase();
-        const allowed = opts.allowedContentTypes ?? [
+        const allowed = def.accepts ?? opts.allowedContentTypes ?? [
             "application/json",
             "application/x-www-form-urlencoded",
             "multipart/form-data",