@daloyjs/core 0.16.0 → 0.28.0

package/dist/app.js

@@ -1,13 +1,59 @@
 import { Router } from "./router.js";
-import { WebSocketRegistry } from "./websocket.js";
-import { BadRequestError, ForbiddenError, HttpError, InternalError, MethodNotAllowedError, NotFoundError, PayloadTooLargeError, RequestTimeoutError, UnsupportedMediaTypeError, ValidationError, } from "./errors.js";
+import { WebSocketRegistry, normalizeWebSocketOptions, } from "./websocket.js";
+import { BadRequestError, ForbiddenError, HttpError, InternalError, MethodNotAllowedError, NotFoundError, PayloadTooLargeError, RequestTimeoutError, TooManyRequestsError, UnsupportedMediaTypeError, ValidationError, } from "./errors.js";
 import { validate } from "./schema.js";
-import { readBodyLimited, safeJsonParse, randomId, assertNoDuplicateSingletonHeaders } from "./security.js";
+import { readBodyLimited, safeJsonParse, randomId, assertNoDuplicateSingletonHeaders, assertStrongSecret, timingSafeEqual } 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, SECURE_HEADERS_MARKER, } from "./middleware.js";
+import { secureHeaders as secureHeadersMiddleware, CORS_HOOK_MARKER, CORS_ORIGIN_ALLOW_MARKER, CORS_WILDCARD_ORIGIN_MARKER, CSRF_HOOK_MARKER, REQUIRE_SCOPES_AGGREGATE_KEY, REQUIRE_SCOPES_HOOK_MARKER, SECURE_HEADERS_MARKER, } from "./middleware.js";
+import { SESSION_HOOK_MARKER, SESSION_SECRETS_MARKER, } from "./session.js";
+import { loadShedding as loadSheddingMiddleware } from "./load-shedding.js";
+import { securitySchemeRequiresPayloadAuth } from "./security-schemes.js";
+import { assertBehindProxy } from "./conn-info.js";
 const AUTO_SECURE_HEADERS_MARKER = Symbol.for("daloyjs.app.autoSecureHeaders");
+/**
+ * Module-level latch shared across every {@link App} constructed in the same
+ * process. Ensures `unhandledRejection` / `uncaughtException` handlers are
+ * registered at most once — installing them twice would log the same crash
+ * twice (and once per listener thereafter), polluting the final exit signal.
+ */
+let crashHandlersInstalled = false;
+let activeCrashLogger;
+function setActiveCrashLogger(log) {
+    activeCrashLogger = log;
+}
+/** @internal Test-only helper to reset the latch between tests. */
+export function _resetCrashHandlersForTests() {
+    crashHandlersInstalled = false;
+    activeCrashLogger = undefined;
+}
+/**
+ * Wave 8 — once-per-process latch for the `secureDefaults: false` warning
+ * log. Multiple `new App({ secureDefaults: false })` instances in the same
+ * process share one log entry instead of flooding the access log with
+ * duplicate warnings on every construction.
+ */
+let insecureDefaultsLoggedThisProcess = false;
+/** @internal Test-only helper to reset the latch between tests. */
+export function _resetInsecureDefaultsLogForTests() {
+    insecureDefaultsLoggedThisProcess = false;
+}
+/**
+ * Wave 8 — list of secure-by-default surfaces disabled when
+ * `secureDefaults: false` is set. Surfaced through the once-per-process
+ * `error` log so the operator sees exactly which guards are off.
+ */
+const DISABLED_BY_INSECURE_DEFAULTS = Object.freeze([
+    "secureHeaders auto-install",
+    "cross-origin guard for state-changing requests",
+    "crash-on-unhandled-rejection (production)",
+    "first-request X-Forwarded-* / trustProxy guard",
+    "session() + state-changing route requires csrf() boot guard",
+    "weak session secret refuse-to-boot",
+    "cors({ origin: '*' }) refuse-to-boot",
+    "anonymous stateful plugin refuse-to-boot",
+]);
 const DEFAULTS = {
     bodyLimitBytes: 1024 * 1024,
     requestTimeoutMs: 30_000,
@@ -74,15 +120,23 @@ 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();
     closeHooks = [];
     closeHooksRun = false;
+    /** Wave 4 idle-connection close hooks (adapter-registered, sync). */
+    idleConnectionCloseHooks = [];
     pluginInstalledListeners = [];
     shutdownListeners = [];
     shutdownListenersRun = false;
-    pendingPlugins = [];
+    pendingPlugins = new Set();
+    pluginBootError = {
+        failed: false,
+        error: undefined,
+    };
     /** In-flight request count for graceful shutdown. */
     inflight = 0;
     draining = false;
@@ -93,6 +147,20 @@ export class App {
       * 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,
@@ -108,9 +176,65 @@ export class App {
                     ? options.logger
                     : createLogger({ level: options.logger?.level ?? "info" });
         this.warnOnEnvMismatch();
+        this.assertDisconnectStatusCode();
+        assertBehindProxy(this.options.behindProxy);
+        if (this.options.hooks)
+            this.assertSecureHookConfig(this.options.hooks);
+        this.assertInsecureDefaultsAcknowledged();
         this.installSecureDefaults();
+        this.maybeInstallCrashHandlers();
         this.maybeMountDocs();
     }
+    /**
+     * Wave 4 leftover: validate {@link AppOptions.disconnectStatusCode}.
+     * Refuses anything outside `[400, 499]` (except `0`, which disables the
+     * rewrite). Throws at construction time so the misconfiguration cannot
+     * survive past boot.
+     */
+    assertDisconnectStatusCode() {
+        const v = this.options.disconnectStatusCode;
+        if (v === undefined || v === 0)
+            return;
+        if (!Number.isInteger(v) || v < 400 || v > 499) {
+            throw new Error(`disconnectStatusCode must be an integer in [400, 499] or 0; got ${String(v)}.`);
+        }
+    }
+    /**
+     * Wave 8 — master-flag escape-hatch enforcement. When
+     * `secureDefaults: false` is set, the framework:
+     *  - refuses-to-construct in production unless
+     *    `acknowledgeInsecureDefaults: true` is also set; closes the
+     *    "developer flipped the flag off while debugging and shipped to
+     *    production" footgun.
+     *  - emits a once-per-process `error` log naming every default the flag
+     *    disables, so operators see the blast radius even if the option was
+     *    set deep in shared configuration.
+     */
+    assertInsecureDefaultsAcknowledged() {
+        if (this.options.secureDefaults !== false)
+            return;
+        const inProduction = this.isProduction();
+        if (inProduction && this.options.acknowledgeInsecureDefaults !== true) {
+            throw new Error("app({ secureDefaults: false }) is refused in production. " +
+                "secureDefaults turns off the entire Wave 1–7 secure-by-default " +
+                "surface (auto secureHeaders, cross-origin guard, crash-on-unhandled-rejection, " +
+                "trustProxy guard, csrf/session boot guard, weak-secret refuse-to-boot, " +
+                "cors({ origin: '*' }) refuse-to-boot, anonymous-stateful-plugin refuse-to-boot). " +
+                "If you really need this in production, also pass " +
+                "acknowledgeInsecureDefaults: true to confirm. Prefer per-feature opt-outs " +
+                "(secureHeaders: false, corsCrossOriginGuard: false, crashOnUnhandledRejection: false, " +
+                "trustProxy: false, csrf: \"off\") instead.");
+        }
+        if (!insecureDefaultsLoggedThisProcess) {
+            insecureDefaultsLoggedThisProcess = true;
+            this.log.error({
+                event: "secure_defaults.disabled",
+                production: inProduction,
+                acknowledged: this.options.acknowledgeInsecureDefaults === true,
+                disabled: DISABLED_BY_INSECURE_DEFAULTS,
+            }, `app({ secureDefaults: false }) disables: ${DISABLED_BY_INSECURE_DEFAULTS.join(", ")}.`);
+        }
+    }
     /**
      * Install the Wave 2 secure-by-default global hooks. Currently:
      *  - {@link secureHeaders} as a group-level hook so every response carries
@@ -134,6 +258,58 @@ export class App {
             auto[AUTO_SECURE_HEADERS_MARKER] = true;
             this.groupHooks.push(auto);
         }
+        // Wave 4 leftover: opt-in load-shedding pressure monitor.
+        if (this.options.loadShedding) {
+            const lsOpts = typeof this.options.loadShedding === "object"
+                ? this.options.loadShedding
+                : {};
+            this.groupHooks.push(loadSheddingMiddleware(lsOpts));
+        }
+    }
+    /**
+     * Wave 4 crash-on-unrecoverable-error guard. Installs Node-process-level
+     * listeners for `unhandledRejection` and `uncaughtException` that log
+     * through the pluggable logger and call `process.exit(1)`. Idempotent via
+     * a module-level latch so multiple `new App()` instantiations in the same
+     * process do not double-register; the most recently constructed App's
+     * logger is used. No-op on runtimes without `process.on` (Workers / Edge
+     * / Fastly), in non-production by default, and when
+     * `crashOnUnhandledRejection: false` or `secureDefaults: false`.
+     */
+    maybeInstallCrashHandlers() {
+        if (this.options.crashOnUnhandledRejection === false)
+            return;
+        if (this.options.crashOnUnhandledRejection === undefined &&
+            (this.options.secureDefaults === false || !this.isProduction())) {
+            return;
+        }
+        if (typeof process === "undefined" || typeof process.on !== "function") {
+            return;
+        }
+        setActiveCrashLogger(this.log);
+        if (crashHandlersInstalled)
+            return;
+        crashHandlersInstalled = true;
+        process.on("unhandledRejection", (reason) => {
+            const log = activeCrashLogger ?? this.log;
+            try {
+                log.fatal({ event: "process.unhandledRejection", err: serializeErr(reason) }, "Unhandled promise rejection — exiting (crashOnUnhandledRejection)");
+            }
+            catch {
+                /* swallow logger failure so we still exit */
+            }
+            process.exit(1);
+        });
+        process.on("uncaughtException", (err) => {
+            const log = activeCrashLogger ?? this.log;
+            try {
+                log.fatal({ event: "process.uncaughtException", err: serializeErr(err) }, "Uncaught exception — exiting (crashOnUnhandledRejection)");
+            }
+            catch {
+                /* swallow logger failure so we still exit */
+            }
+            process.exit(1);
+        });
     }
     /**
      * Emit a one-time `warn` when the explicit {@link AppOptions.env} option
@@ -211,6 +387,141 @@ export class App {
             `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");
+                }
+            }
+        }
+    }
+    assertRouteAuthPayloadConfig(route) {
+        const auth = route.auth;
+        if (!auth || auth.payload !== false)
+            return;
+        const scheme = this.options.openapi?.securitySchemes?.[auth.scheme];
+        if (!securitySchemeRequiresPayloadAuth(scheme))
+            return;
+        throw new Error(`Route ${route.method} ${route.path} declares auth.payload: false, ` +
+            `but security scheme "${auth.scheme}" requires payload authentication. ` +
+            `Remove the route-level opt-out or use a scheme without requirePayloadAuth: true.`);
+    }
+    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;
+        // Wave 6: `behindProxy` is the declarative successor — when supplied,
+        // the framework already knows how to interpret forwarded headers and
+        // the legacy unconfigured-proxy guard is satisfied.
+        if (this.options.behindProxy !== 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
@@ -370,6 +681,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,
@@ -377,11 +690,22 @@ export class App {
             tags: [...(this.groupTags ?? []), ...(def.tags ?? [])],
             auth: def.auth ?? this.groupAuth,
         };
+        this.assertRouteAuthPayloadConfig(merged);
         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;
     }
     /**
@@ -393,7 +717,235 @@ export class App {
      */
     ws(path, handler) {
         const fullPath = joinPath(this.prefix, path);
-        this.webSocketRoutes.add(fullPath, handler, () => ({ ...this.decorations }));
+        const options = normalizeWebSocketOptions(handler, {
+            production: this.isProduction(),
+            secureDefaults: this.options.secureDefaults !== false,
+        });
+        this.webSocketRoutes.add(fullPath, handler, () => ({ ...this.decorations }), options);
+        return this;
+    }
+    /**
+     * Register a liveness probe route. Returns `200 {"status":"ok"}` while
+     * the process is alive, regardless of plugin readiness. Use this for
+     * container orchestrator `livenessProbe` configuration — a failing
+     * liveness probe restarts the container.
+     *
+     * Defaults (Wave 4 secure-by-default):
+     *  - path: `/healthz`
+     *  - rate-limit: 60 req/min per remote IP, in-memory (per-process)
+     *  - auth: opt-in via `token`. In production with `secureDefaults: true`,
+     *    registration refuses to add the route without a `token` unless
+     *    `acknowledgeUnauthenticated: true` is set, so an unguarded
+     *    healthcheck cannot ship to production by accident.
+     *
+     * @example
+     * ```ts
+     * app.healthcheck({ token: process.env.HEALTH_TOKEN! });
+     * ```
+     *
+     * @since 0.18.0
+     */
+    healthcheck(opts = {}) {
+        this.registerHealthRoute("healthcheck", opts, () => ({
+            status: 200,
+            body: { status: "ok" },
+        }));
+        return this;
+    }
+    /**
+     * Register a readiness probe route. Returns `200 {"status":"ready"}`
+     * once every async plugin has resolved AND the app is not draining.
+     * Returns `503` otherwise. Use this for container orchestrator
+     * `readinessProbe` configuration — a failing readiness probe removes
+     * the pod from load-balancer rotation without restarting it.
+     *
+     * Defaults match {@link App.healthcheck} (path defaults to `/readyz`).
+     *
+     * @since 0.18.0
+     */
+    readinesscheck(opts = {}) {
+        this.registerHealthRoute("readinesscheck", opts, () => {
+            if (this.draining ||
+                this.pendingPlugins.size > 0 ||
+                this.pluginBootError.failed) {
+                return {
+                    status: 503,
+                    body: { status: "not-ready" },
+                    headers: { "retry-after": "5" },
+                };
+            }
+            return {
+                status: 200,
+                body: { status: "ready" },
+            };
+        });
+        return this;
+    }
+    registerHealthRoute(kind, opts, handler) {
+        const isHealth = kind === "healthcheck";
+        const defaultPath = (isHealth ? "/healthz" : "/readyz");
+        const path = (opts.path ?? defaultPath);
+        const rateLimitConfig = opts.rateLimit === false
+            ? null
+            : { limit: 60, windowMs: 60_000, ...(opts.rateLimit ?? {}) };
+        const token = opts.token;
+        // Wave 4 refuse-to-boot: unauthenticated health/ready probes in
+        // production are a documented info-disclosure surface (process uptime,
+        // plugin-ready transitions, internal hostnames in some shops). Force
+        // an explicit acknowledgement.
+        if (this.options.secureDefaults !== false &&
+            this.isProduction() &&
+            token === undefined &&
+            opts.acknowledgeUnauthenticated !== true) {
+            throw new Error(`app.${kind}() refused in production: provide opts.token to require ` +
+                `Authorization: Bearer <token>, or pass acknowledgeUnauthenticated: true ` +
+                `to acknowledge that this probe is reachable without credentials.`);
+        }
+        const buckets = rateLimitConfig
+            ? new Map()
+            : null;
+        this.route({
+            method: "GET",
+            path,
+            operationId: isHealth ? "healthcheck" : "readinesscheck",
+            tags: ["Health"],
+            summary: isHealth ? "Liveness probe" : "Readiness probe",
+            handler: async ({ request }) => {
+                if (buckets && rateLimitConfig) {
+                    const key = healthRouteKey(request);
+                    const now = Date.now();
+                    const entry = buckets.get(key);
+                    if (!entry || entry.resetMs <= now) {
+                        buckets.set(key, { count: 1, resetMs: now + rateLimitConfig.windowMs });
+                    }
+                    else {
+                        entry.count++;
+                        if (entry.count > rateLimitConfig.limit) {
+                            throw new TooManyRequestsError(Math.ceil((entry.resetMs - now) / 1000));
+                        }
+                    }
+                }
+                if (token !== undefined) {
+                    const h = request.headers.get("authorization") ?? "";
+                    const m = /^Bearer\s+(.+)$/i.exec(h);
+                    if (!m) {
+                        throw new HttpError(401, {
+                            type: "https://daloyjs.dev/errors/unauthorized",
+                            title: "Unauthorized",
+                            detail: "Health probe requires a bearer token.",
+                        }, { "www-authenticate": 'Bearer realm="health"' });
+                    }
+                    if (!timingSafeEqual(m[1], token)) {
+                        throw new ForbiddenError("Invalid health probe token.");
+                    }
+                }
+                return handler();
+            },
+            responses: {
+                200: {
+                    description: isHealth ? "Service is alive." : "Service is ready.",
+                },
+                503: {
+                    description: "Service is not ready.",
+                },
+            },
+        });
+    }
+    /**
+     * Wave 4 leftover: register a built-in receiver for CSP / Reporting API
+     * violation reports. Accepts `application/csp-report` and
+     * `application/reports+json` payloads, rate-limits per IP (defaults: 60
+     * req/min), caps body size (default 8 KiB), and forwards parsed reports
+     * to {@link CspReportRouteOptions.onReport} (or the structured logger
+     * when omitted). Returns `204 No Content` so browsers stop retrying.
+     *
+     * Combine with `secureHeaders({ reportingEndpoints, reportTo })` to wire
+     * the browser to this endpoint. The route is registered as `internal:
+    * false` (i.e. publicly reachable); that is required for the browser
+     * Reporting API to send to it.
+     *
+     */
+    cspReportRoute(opts = {}) {
+        const path = (opts.path ?? "/__csp-report");
+        const maxBytes = opts.maxBodyBytes ?? 8192;
+        const rateLimitConfig = opts.rateLimit === false
+            ? null
+            : { limit: 60, windowMs: 60_000, ...(opts.rateLimit ?? {}) };
+        const buckets = rateLimitConfig
+            ? new Map()
+            : null;
+        const log = this.log;
+        this.route({
+            method: "POST",
+            path,
+            operationId: "cspReport",
+            tags: ["Reporting"],
+            summary: "CSP / Reporting API violation receiver",
+            handler: async ({ request }) => {
+                if (buckets && rateLimitConfig) {
+                    const key = healthRouteKey(request);
+                    const now = Date.now();
+                    const entry = buckets.get(key);
+                    if (!entry || entry.resetMs <= now) {
+                        buckets.set(key, { count: 1, resetMs: now + rateLimitConfig.windowMs });
+                    }
+                    else {
+                        entry.count++;
+                        if (entry.count > rateLimitConfig.limit) {
+                            throw new TooManyRequestsError(Math.ceil((entry.resetMs - now) / 1000));
+                        }
+                    }
+                }
+                const contentType = (request.headers.get("content-type") ?? "")
+                    .split(";")[0]
+                    .trim()
+                    .toLowerCase();
+                if (contentType !== "application/csp-report" &&
+                    contentType !== "application/reports+json" &&
+                    contentType !== "application/json") {
+                    throw new UnsupportedMediaTypeError(contentType || "<none>", [
+                        "application/csp-report",
+                        "application/reports+json",
+                        "application/json",
+                    ]);
+                }
+                const rawBytes = await readBodyLimited(request, maxBytes);
+                const rawText = new TextDecoder().decode(rawBytes);
+                let parsed;
+                try {
+                    parsed = safeJsonParse(rawText);
+                }
+                catch {
+                    throw new BadRequestError("Invalid JSON report body");
+                }
+                if (parsed === undefined) {
+                    throw new BadRequestError("Invalid JSON report body");
+                }
+                const ip = healthRouteKey(request);
+                const userAgent = request.headers.get("user-agent");
+                try {
+                    if (opts.onReport) {
+                        await opts.onReport(parsed, {
+                            ip: ip === "global" ? null : ip,
+                            userAgent,
+                        });
+                    }
+                    else {
+                        log.warn({ event: "csp.report", ip, userAgent, report: parsed }, "CSP violation report received");
+                    }
+                }
+                catch (err) {
+                    log.error({ err: serializeErr(err), event: "csp.report.sinkFailed" }, "cspReportRoute onReport sink failed");
+                }
+                return { status: 204, body: undefined };
+            },
+            responses: {
+                204: { description: "Report accepted." },
+                413: { description: "Report body too large." },
+                415: { description: "Unsupported content-type." },
+                429: { description: "Rate limit exceeded." },
+            },
+        });
         return this;
     }
     /**
@@ -421,6 +973,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").
@@ -428,6 +982,8 @@ 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 = [
@@ -440,9 +996,11 @@ export class App {
         child.decorations = this.decorations;
         child.installedPlugins = this.installedPlugins;
         child.closeHooks = this.closeHooks;
+        child.idleConnectionCloseHooks = this.idleConnectionCloseHooks;
         child.pluginInstalledListeners = this.pluginInstalledListeners;
         child.shutdownListeners = this.shutdownListeners;
         child.pendingPlugins = this.pendingPlugins;
+        child.pluginBootError = this.pluginBootError;
         register(child);
         return this;
     }
@@ -464,6 +1022,11 @@ 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
@@ -479,6 +1042,7 @@ export class App {
         if (hooks[CORS_HOOK_MARKER] === true) {
             this.corsOriginAllows = corsOriginAllowsFromHooks(this.groupHooks);
         }
+        this.resetWave3BootGuardCache();
         return this;
     }
     /**
@@ -505,7 +1069,31 @@ export class App {
      * @param value - Value bound to that property on every request.
      * @returns This `App` instance for chaining.
      */
-    decorate(key, value) {
+    /**
+     * Apply an ordered list of plugin extensions (Wave 6 item 10) to the
+     * group-level hook chain. Each extension's `handler` is wrapped into a
+     * single-event {@link Hooks} bundle so subsequent route registrations
+     * pick it up via the normal hook composition path.
+     * @internal
+     */
+    applyExtensions(ordered) {
+        for (const ext of ordered) {
+            const hooks = { [ext.event]: ext.handler };
+            this.groupHooks.push(hooks);
+        }
+    }
+    decorate(key, value, opts = {}) {
+        if (Object.prototype.hasOwnProperty.call(this.decorations, key) &&
+            opts.override !== true) {
+            // Wave 6 item 9: namespace-protected decorators. Refuse to silently
+            // shadow an existing decoration; emit a once-per-process warn naming
+            // both decorators on the explicit-override path.
+            throw new Error(`decorate(): key "${key}" is already decorated. ` +
+                `Pass { override: true } to replace, or rename to avoid the collision.`);
+        }
+        if (opts.override === true && Object.prototype.hasOwnProperty.call(this.decorations, key)) {
+            this.log.warn({ event: "decorate.override", key }, `decorate("${key}") replaced an existing decoration.`);
+        }
         this.decorations[key] = value;
         return this;
     }
@@ -545,16 +1133,53 @@ export class App {
         return this;
     }
     /**
-     * Encapsulated plugin registration (Fastify-style). Receives a child App; routes/hooks are scoped.
+     * Encapsulated plugin registration (Fastify-style). Receives a child App;
+     * routes/hooks declared on the child are scoped to the plugin by default
+     * (Wave 6 item 15 \u2014 encapsulation default `local`).
+     *
+     * Wave 6 (`0.24.0`) additions on the plugin descriptor object:
+     *
+     * - `dependencies: string[]` \u2014 prerequisite plugin names; the framework
+     *   refuses-to-boot at registration time when any declared dependency has
+     *   not been installed first (item 8).
+     * - `seed: string` \u2014 differentiator for parameterized instances of the
+     *   same plugin (item 16). Dedup key becomes `${name}#${seed}`.
+     * - `stateful: boolean` \u2014 when `true` AND `name` is absent AND the app is
+     *   in production with `secureDefaults` on, registration refuses-to-boot
+     *   so silent double-installs of global-state-mutating plugins are caught
+     *   loud (item 16).
+     * - `extensions: [{ event, handler, before?, after? }]` \u2014 declarative
+     *   lifecycle-hook ordering with topological-sort + cycle detection
+     *   (item 10). Refuses-at-registration on cycles.
      */
     register(plugin, config = {}) {
-        const fn = typeof plugin === "function" ? plugin : plugin.register;
-        const name = typeof plugin === "function" ? undefined : plugin.name;
-        if (name) {
-            if (this.installedPlugins.has(name)) {
-                throw new Error(`Plugin "${name}" already registered`);
+        const fn = typeof plugin === "function" ? plugin : (plugin.register ?? (() => { }));
+        const descriptor = typeof plugin === "function" ? undefined : plugin;
+        const name = descriptor?.name;
+        const seed = descriptor?.seed;
+        const dedupKey = name ? (seed ? `${name}#${seed}` : name) : undefined;
+        const dependencies = descriptor?.dependencies ?? [];
+        const stateful = descriptor?.stateful ?? false;
+        if (stateful && !name && this.isProduction() && this.options.secureDefaults !== false) {
+            throw new Error("register(): anonymous stateful plugin refused in production. " +
+                "Declare { name } (and optional { seed }) so the plugin can be deduplicated.");
+        }
+        for (const dep of dependencies) {
+            if (!this.installedPlugins.has(dep)) {
+                throw new Error(`register(): plugin ${JSON.stringify(name ?? "<anonymous>")} declares ` +
+                    `dependency on "${dep}" but no plugin with that name has been registered yet.`);
             }
-            this.installedPlugins.add(name);
+        }
+        if (dedupKey) {
+            if (this.installedPlugins.has(dedupKey)) {
+                throw new Error(`Plugin "${dedupKey}" already registered`);
+            }
+            this.installedPlugins.add(dedupKey);
+        }
+        if (descriptor?.extensions && descriptor.extensions.length > 0) {
+            // Wave 6 item 10: topological sort with cycle detection.
+            const ordered = topoSortExtensions(descriptor.extensions);
+            this.applyExtensions(ordered);
         }
         const prefix = config.prefix ?? "/";
         const event = {
@@ -564,20 +1189,29 @@ export class App {
         this.group(prefix, config, (child) => {
             const r = fn(child);
             if (r && typeof r.then === "function") {
-                // Plugin is async — caller should await app.ready().
-                this.pendingPlugins.push(r.then(() => this.firePluginInstalled(event)));
+                // Plugin is async - caller should await app.ready().
+                this.trackPendingPlugin(r.then(() => this.firePluginInstalled(event)));
             }
             else {
                 // Sync plugin: fire listeners immediately. Any returned promise from a
                 // listener is collected so `app.ready()` can await observers too.
                 const pending = this.firePluginInstalled(event);
                 if (pending) {
-                    this.pendingPlugins.push(pending);
+                    this.trackPendingPlugin(pending);
                 }
             }
         });
         return this;
     }
+    trackPendingPlugin(promise) {
+        const tracked = promise.catch((err) => {
+            this.pluginBootError.failed = true;
+            this.pluginBootError.error = err;
+            throw err;
+        });
+        this.pendingPlugins.add(tracked);
+        void tracked.finally(() => this.pendingPlugins.delete(tracked)).catch(() => { });
+    }
     firePluginInstalled(event) {
         if (this.pluginInstalledListeners.length === 0)
             return undefined;
@@ -617,9 +1251,12 @@ export class App {
      * @returns Promise that resolves once all pending plugins have settled.
      */
     ready() {
-        if (this.pendingPlugins.length === 0)
+        if (this.pluginBootError.failed) {
+            return Promise.reject(this.pluginBootError.error);
+        }
+        if (this.pendingPlugins.size === 0)
             return Promise.resolve();
-        const pending = this.pendingPlugins.splice(0);
+        const pending = Array.from(this.pendingPlugins);
         return Promise.all(pending).then(() => undefined);
     }
     /**
@@ -642,6 +1279,28 @@ export class App {
      *   to RFC 9457 `application/problem+json` automatically.
      */
     fetch = async (request) => {
+        const response = await this.dispatch(request);
+        // In-flight responses that finish during draining advertise
+        // `Connection: close` so HTTP/1.1 load balancers stop re-using the
+        // socket for new requests. Wave 4 connection-draining.
+        if (this.draining && !response.headers.has("connection")) {
+            response.headers.set("connection", "close");
+        }
+        return response;
+    };
+    /**
+     * In-process entry point that bypasses the public `404` shield for
+     * routes declared with `internal: true`. Use it for cron jobs, admin
+     * scripts, and integration tests that need to exercise privileged
+     * handlers without exposing them to the network. All other security
+     * middleware (CORS, CSRF, rate limit, etc.) still runs normally.
+     *
+     * @since 0.19.0
+     */
+    inject = async (request) => {
+        return this.dispatch(request, { allowInternal: true });
+    };
+    dispatch = async (request, opts = {}) => {
         if (this.draining) {
             return new Response(JSON.stringify({
                 type: "https://daloyjs.dev/errors/shutting-down",
@@ -652,6 +1311,10 @@ export class App {
                 headers: {
                     "content-type": "application/problem+json",
                     "retry-after": "5",
+                    // Tell HTTP/1.1 load balancers to close the keep-alive socket
+                    // immediately so the next request lands on a healthy instance
+                    // rather than coming back to a dying one. Wave 4.
+                    connection: "close",
                 },
             });
         }
@@ -670,18 +1333,38 @@ 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);
+            // Hide internal routes from the public adapter surface. The router
+            // still finds them so app.inject() can dispatch normally, but
+            // app.fetch() responds 404 to avoid leaking existence.
+            const internalHidden = match?.handler.def.internal === true && opts.allowInternal !== true;
             this.assertCrossOriginAllowed(request, url, method, [
                 ...corsOriginAllowsFromHooks([this.options.hooks ?? {}]),
-                ...(match ? match.handler.corsOriginAllows : this.corsOriginAllows),
+                ...(match && !internalHidden ? match.handler.corsOriginAllows : this.corsOriginAllows),
             ]);
-            if (!match) {
-                const allowed = this.router.allowedMethods(url.pathname);
+            if (!match || internalHidden) {
+                if (internalHidden) {
+                    // Don't leak existence via 405/Allow header. Always 404.
+                    throw new NotFoundError(`No route for ${request.method} ${url.pathname}`);
+                }
+                const rawAllowed = this.router.allowedMethods(url.pathname);
+                // Filter out methods whose route definitions are marked
+                // `internal: true` unless the caller explicitly opted in via
+                // app.inject(). This prevents 405/Allow from leaking the
+                // existence of hidden admin/cron endpoints.
+                const allowed = opts.allowInternal
+                    ? rawAllowed
+                    : rawAllowed.filter((m) => {
+                        const candidate = this.router.find(m, url.pathname);
+                        return candidate?.handler.def.internal !== true;
+                    });
                 ctx = {
                     request,
                     params: {},
@@ -747,14 +1430,16 @@ export class App {
             if (afterReturn !== undefined)
                 result = afterReturn;
             let response = await serializeResult(result, def, this.options.validateResponses ?? true);
+            copyContextHeaders(ctx, response);
+            const finalized = await finalizeResponse(response, ctx, allHooks, stripFingerprint);
             if (method === "HEAD") {
-                response = new Response(null, {
-                    status: response.status,
-                    headers: response.headers,
+                return new Response(null, {
+                    status: finalized.status,
+                    statusText: finalized.statusText,
+                    headers: finalized.headers,
                 });
             }
-            copyContextHeaders(ctx, response);
-            return await finalizeResponse(response, ctx, allHooks, stripFingerprint);
+            return finalized;
         }
         catch (err) {
             const handled = await activeErrorHook?.(err, ctx);
@@ -768,6 +1453,29 @@ export class App {
                     onResponse: activeResponseHook,
                 }, stripFingerprint);
             }
+            // Wave 4 leftover: when the client has already disconnected, classify
+            // the request at `disconnectStatusCode` (default 499) instead of
+            // letting an AbortError bubble up as a generic 5xx. Logged at `info`
+            // so disconnect storms do not look like service incidents.
+            const disconnectCode = this.options.disconnectStatusCode ?? 499;
+            if (disconnectCode > 0 &&
+                request.signal?.aborted === true &&
+                !(err instanceof HttpError)) {
+                log.info({ event: "request.disconnected", status: disconnectCode }, "Client disconnected before response was sent");
+                const res = new Response(null, {
+                    status: disconnectCode,
+                    headers: {
+                        "content-type": "application/problem+json",
+                        "x-request-id": requestId,
+                    },
+                });
+                if (ctx)
+                    copyContextHeaders(ctx, res);
+                return finalizeResponse(res, ctx, {
+                    onSend: activeSendHook,
+                    onResponse: activeResponseHook,
+                }, stripFingerprint);
+            }
             const httpErr = err instanceof HttpError
                 ? err
                 : new InternalError(err instanceof Error ? err.message : "Unexpected error");
@@ -880,6 +1588,17 @@ export class App {
                 }
             }
         }
+        // Wave 4: kill idle keep-alive connections immediately so they cannot
+        // be re-used for a new request that would race with the drain. Adapters
+        // (Node) register a hook here. In-flight requests are unaffected.
+        for (const hook of this.idleConnectionCloseHooks) {
+            try {
+                hook();
+            }
+            catch (err) {
+                this.log.error({ err }, "idleConnectionCloseHook failed");
+            }
+        }
         const start = Date.now();
         while (this.inflight > 0 && Date.now() - start < timeoutMs) {
             await new Promise((r) => setTimeout(r, 25));
@@ -892,6 +1611,30 @@ export class App {
         }
         this.log.info({ inflight: this.inflight }, "DaloyJS shutdown complete");
     }
+    /**
+     * Alias for {@link App.shutdown}. Matches the Node `Server.close()` shape
+     * and reads more naturally from adapters that want a single "stop"
+     * method.
+     *
+     * @since 0.18.0
+     */
+    async close(timeoutMs = 10_000, reason) {
+        return this.shutdown(timeoutMs, reason);
+    }
+    /**
+     * Adapter-private hook to register a callback that runs synchronously
+     * when {@link App.shutdown} begins draining. The Node adapter uses this
+     * to invoke `server.closeIdleConnections()` so keep-alive sockets without
+     * an in-flight request are killed immediately instead of being held open
+     * until the OS / load balancer notices.
+     *
+     * Not part of the documented public API surface: subject to change.
+     *
+     * @internal
+     */
+    _registerIdleConnectionCloseHook(hook) {
+        this.idleConnectionCloseHooks.push(hook);
+    }
 }
 // ---------- helpers ----------
 function joinPath(a, b) {
@@ -900,6 +1643,16 @@ function joinPath(a, b) {
     const joined = `${left}${right}`;
     return joined === "" ? "/" : joined;
 }
+function healthRouteKey(request) {
+    // The probe rate limit deliberately does NOT honour `X-Forwarded-For` —
+    // health probes typically arrive directly from a sidecar / orchestrator,
+    // so even apps that trust forwarded headers should not let an attacker
+    // bypass the per-IP cap by spoofing the header. Fall back to a constant
+    // key when no proxy header is available (single shared bucket).
+    return (request.headers.get("x-real-ip") ??
+        request.headers.get("fly-client-ip") ??
+        "global");
+}
 function corsOriginAllowsFromHooks(layers) {
     const allows = [];
     for (const hooks of layers) {
@@ -917,18 +1670,131 @@ function corsOriginAllowsFromHooks(layers) {
     }
     return allows;
 }
+/**
+ * Topological sort of plugin extensions (Wave 6 item 10). Refuses-at-call
+ * on cyclic ordering with a structured error naming the cycle.
+ * @internal
+ */
+export function topoSortExtensions(exts) {
+    const byName = new Map();
+    for (const e of exts) {
+        if (byName.has(e.name)) {
+            throw new Error(`Duplicate plugin extension name: ${JSON.stringify(e.name)}.`);
+        }
+        byName.set(e.name, e);
+    }
+    // Build adjacency: edge from A -> B means A must run before B.
+    const edges = new Map();
+    for (const e of exts)
+        edges.set(e.name, new Set());
+    for (const e of exts) {
+        for (const b of e.before ?? []) {
+            if (byName.has(b))
+                edges.get(e.name).add(b);
+        }
+        for (const a of e.after ?? []) {
+            if (byName.has(a))
+                edges.get(a).add(e.name);
+        }
+    }
+    // Kahn's algorithm.
+    const indeg = new Map();
+    for (const name of edges.keys())
+        indeg.set(name, 0);
+    for (const [, outs] of edges) {
+        for (const v of outs)
+            indeg.set(v, (indeg.get(v) ?? 0) + 1);
+    }
+    const queue = [];
+    for (const [name, d] of indeg)
+        if (d === 0)
+            queue.push(name);
+    const out = [];
+    while (queue.length > 0) {
+        const name = queue.shift();
+        out.push(byName.get(name));
+        for (const v of edges.get(name)) {
+            const d = (indeg.get(v) ?? 0) - 1;
+            indeg.set(v, d);
+            if (d === 0)
+                queue.push(v);
+        }
+    }
+    if (out.length !== exts.length) {
+        const remaining = Array.from(byName.keys()).filter((n) => !out.some((e) => e.name === n));
+        throw new Error(`Plugin extension cycle detected among: ${remaining.map((n) => JSON.stringify(n)).join(", ")}.`);
+    }
+    return out;
+}
+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])
         .filter((f) => typeof f === "function");
-    return {
+    const requiredScopes = requiredScopesFromHooks(layers);
+    const beforeHandle = mergeBeforeHandle(firstResponse(pick("beforeHandle")), requiredScopes);
+    const hooks = {
         onRequest: chain(pick("onRequest")),
-        beforeHandle: firstResponse(pick("beforeHandle")),
+        beforeHandle,
         afterHandle: pipeline(pick("afterHandle")),
         onError: firstResponse(pick("onError")),
         onSend: responsePipeline(pick("onSend")),
         onResponse: chain(pick("onResponse")),
     };
+    stampRequiredScopes(hooks, requiredScopes);
+    return hooks;
+}
+function requiredScopesFromHooks(layers) {
+    const out = [];
+    for (const hooks of layers) {
+        const scopes = hooks[REQUIRE_SCOPES_HOOK_MARKER];
+        if (!Array.isArray(scopes))
+            continue;
+        for (const scope of scopes) {
+            if (typeof scope === "string" && !out.includes(scope))
+                out.push(scope);
+        }
+    }
+    return out;
+}
+function stampRequiredScopes(hooks, scopes) {
+    if (scopes.length > 0) {
+        hooks[REQUIRE_SCOPES_HOOK_MARKER] = [...scopes];
+    }
+}
+function mergeBeforeHandle(beforeHandle, requiredScopes) {
+    if (!beforeHandle && requiredScopes.length === 0)
+        return undefined;
+    return async (ctx) => {
+        if (requiredScopes.length > 0) {
+            const state = ctx.state;
+            const prior = state[REQUIRE_SCOPES_AGGREGATE_KEY];
+            const aggregate = Array.isArray(prior) ? [...prior] : [];
+            for (const scope of requiredScopes) {
+                if (!aggregate.includes(scope))
+                    aggregate.push(scope);
+            }
+            state[REQUIRE_SCOPES_AGGREGATE_KEY] = aggregate;
+        }
+        return beforeHandle?.(ctx);
+    };
 }
 function responsePipeline(fns) {
     if (fns.length === 0)