@daloyjs/core 1.0.0-rc.3 → 1.0.0-rc.5

package/dist/app.js

@@ -1,12 +1,13 @@
 import { Router } from "./router.js";
 import { WebSocketRegistry, normalizeWebSocketOptions, } from "./websocket.js";
 import { BadRequestError, ForbiddenError, HttpError, InternalError, MethodNotAllowedError, NotFoundError, PayloadTooLargeError, RequestTimeoutError, TooManyRequestsError, UnsupportedMediaTypeError, ValidationError, } from "./errors.js";
-import { readBodyLimited, safeJsonParse, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, assertHeaderCountWithinLimit, DEFAULT_MAX_HEADER_COUNT, assertStrongSecret, timingSafeEqual, isForbiddenObjectKey, } from "./security.js";
-import { createLogger, noopLogger } from "./logger.js";
+import { readBodyLimited, safeJsonParseLimited, randomId, assertInboundHeaderGuards, DEFAULT_MAX_HEADER_COUNT, assertStrongSecret, timingSafeEqual, isForbiddenObjectKey, } from "./security.js";
+import { createLogger, noopLogger, sanitizeUrlForLog } from "./logger.js";
 import { generateOpenAPI, openapiToYAML, } from "./openapi.js";
+import { isSchemaValidatedResponse } from "./internal-response.js";
 import { asyncapiHtml, docsContentSecurityPolicy, redocHtml, scalarHtml, swaggerUiHtml, } from "./docs.js";
 import { generateAsyncAPI, asyncapiToYAML, } from "./asyncapi.js";
-import { secureHeaders as secureHeadersMiddleware, AUTH_HOOK_MARKER, 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 { secureHeaders as secureHeadersMiddleware, AUTH_HOOK_MARKER, CORS_HOOK_MARKER, CORS_ORIGIN_ALLOW_MARKER, CORS_WILDCARD_ORIGIN_MARKER, CSRF_HOOK_MARKER, _mergePreBodyWithEarlyRejections, REQUIRE_SCOPES_AGGREGATE_KEY, REQUIRE_SCOPES_HOOK_MARKER, SECURE_HEADERS_MARKER, } from "./middleware.js";
 import { COMPRESSION_HOOK_MARKER } from "./compression.js";
 import { SESSION_HOOK_MARKER, SESSION_SECRETS_MARKER } from "./session.js";
 import { loadShedding as loadSheddingMiddleware, } from "./load-shedding.js";
@@ -72,6 +73,7 @@ const INTERNAL_SERVICE_PRESET_DISABLED = Object.freeze([
  */
 const INTERNAL_SERVICE_PRESET_KEPT = Object.freeze([
     "bodyLimitBytes (1 MiB default)",
+    "jsonMaxKeys (10k) + jsonMaxDepth (50) structural limits",
     "requestTimeoutMs (30 s default)",
     "crashOnUnhandledRejection (production)",
     "weak session secret refuse-to-boot",
@@ -169,6 +171,8 @@ const DEFAULTS = {
     bodyLimitBytes: 1024 * 1024,
     requestTimeoutMs: 30_000,
     maxHeaderCount: DEFAULT_MAX_HEADER_COUNT,
+    jsonMaxKeys: 10_000,
+    jsonMaxDepth: 50,
     validateResponses: true,
 };
 const TEXT_ENCODER = new TextEncoder();
@@ -192,6 +196,23 @@ export const DALOY_RAW_BODY = Symbol.for("daloyjs.response.rawBody");
  * so first-party adapters can opt in; not part of the userland API surface.
  */
 export const DALOY_REQUEST_RAW_BODY = Symbol.for("daloyjs.request.rawBody");
+/**
+ * Internal Symbol an adapter sets (on its request shim) to expose the request's
+ * abort hook: a `(reason: unknown) => void` that aborts the `AbortController`
+ * backing `request.signal`. The core invokes it when a request exceeds
+ * {@link AppOptions.requestTimeoutMs} so a handler that forwarded
+ * `ctx.request.signal` to downstream I/O (`fetch`, a DB driver) sees those
+ * calls cancel — cooperative teardown, since single-threaded JS cannot preempt
+ * a running handler.
+ *
+ * The hook is invoked as a method on the request (`this` stays bound to the
+ * shim) so it can reach the shim's private controller. Absent on runtimes
+ * whose `Request.signal` is managed by the platform (Bun / Deno / Workers) and
+ * on direct `app.fetch()` callers, where {@link abortRequest} is a safe no-op
+ * and the timeout still resolves as a `408`. Module-public so first-party
+ * adapters can opt in; not part of the userland API surface.
+ */
+export const DALOY_REQUEST_ABORT = Symbol.for("daloyjs.request.abort");
 /**
  * Internal Symbol set by handlers/serializers to attach a raw stream
  * (Node `Readable` or Web `ReadableStream`) to a `Response`. The Node
@@ -444,6 +465,8 @@ export class App {
             bodyLimitBytes: resolved.bodyLimitBytes ?? DEFAULTS.bodyLimitBytes,
             requestTimeoutMs: resolved.requestTimeoutMs ?? DEFAULTS.requestTimeoutMs,
             maxHeaderCount: resolved.maxHeaderCount ?? DEFAULTS.maxHeaderCount,
+            jsonMaxKeys: resolved.jsonMaxKeys ?? DEFAULTS.jsonMaxKeys,
+            jsonMaxDepth: resolved.jsonMaxDepth ?? DEFAULTS.jsonMaxDepth,
             ...resolved,
         };
         this.log =
@@ -572,6 +595,8 @@ export class App {
             bodyLimitBytes: this.options.bodyLimitBytes,
             requestTimeoutMs: this.options.requestTimeoutMs,
             maxHeaderCount: this.options.maxHeaderCount ?? DEFAULT_MAX_HEADER_COUNT,
+            jsonMaxKeys: this.options.jsonMaxKeys ?? DEFAULTS.jsonMaxKeys,
+            jsonMaxDepth: this.options.jsonMaxDepth ?? DEFAULTS.jsonMaxDepth,
             stripServerHeaders: o.stripServerHeaders !== false,
             production: this.isProduction(),
         });
@@ -775,6 +800,7 @@ export class App {
         if (hooks !== null && typeof hooks === "object") {
             const HOOK_KEYS = [
                 "onRequest",
+                "preBody",
                 "beforeHandle",
                 "afterHandle",
                 "onError",
@@ -791,7 +817,7 @@ export class App {
                         "route unguarded.");
                 }
                 if (Object.keys(hooks).length > 0) {
-                    throw new Error("Hooks object carries none of the recognized hook keys (onRequest, " +
+                    throw new Error("Hooks object carries none of the recognized hook keys (onRequest, preBody, " +
                         "beforeHandle, afterHandle, onError, onSend, onResponse), so it would " +
                         "silently apply no hooks. To compose multiple hook bundles use " +
                         "every(...) / some(...) from @daloyjs/core.");
@@ -1089,21 +1115,17 @@ export class App {
         const docsPath = (opts.path ?? "/docs");
         const ui = opts.ui ?? "scalar";
         const tags = opts.tags ?? ["Docs"];
-        // Best-effort lazy read of the host project's package.json so that
-        // `new App({ docs: true })` with no explicit `openapi.info` still produces
-        // a spec titled after the user's package (`name` → title,
-        // `version` → version, `description` → description). Silently skipped on
-        // edge runtimes that lack `node:fs`.
-        const resolveInfo = async () => {
+        // Keep docs generation purely web-standard. Host metadata is explicit so
+        // edge bundlers never need to resolve or stub `node:fs` from the core.
+        const resolveInfo = () => {
             const fromOpenapi = this.options.openapi?.info ?? {};
-            const fromPkg = await readHostPackageJsonInfo();
-            const title = fromOpenapi.title ?? this.options.title ?? fromPkg.title ?? "DaloyJS API";
-            const version = fromOpenapi.version ?? this.options.version ?? fromPkg.version ?? "0.0.0";
-            const description = fromOpenapi.description ?? this.options.description ?? fromPkg.description;
+            const title = fromOpenapi.title ?? this.options.title ?? "DaloyJS API";
+            const version = fromOpenapi.version ?? this.options.version ?? "0.0.0";
+            const description = fromOpenapi.description ?? this.options.description;
             return description ? { title, version, description } : { title, version };
         };
         const generate = async () => generateOpenAPI(this, {
-            info: await resolveInfo(),
+            info: resolveInfo(),
             ...(this.options.openapi?.servers ? { servers: this.options.openapi.servers } : {}),
             ...(this.options.openapi?.securitySchemes
                 ? { securitySchemes: this.options.openapi.securitySchemes }
@@ -1178,7 +1200,7 @@ export class App {
                 200: { description: "Interactive API documentation UI." },
             },
             handler: async () => {
-                const title = opts.title ?? (await resolveInfo()).title;
+                const title = opts.title ?? resolveInfo().title;
                 const html = ui === "swagger"
                     ? swaggerUiHtml({
                         specUrl: openapiPath,
@@ -1253,16 +1275,15 @@ export class App {
         const yamlPath = opts.yamlPath === false ? null : (opts.yamlPath ?? "/asyncapi.yaml");
         const uiPath = (opts.path ?? "/asyncapi");
         const tags = opts.tags ?? ["AsyncAPI"];
-        const resolveInfo = async () => {
+        const resolveInfo = () => {
             const fromOpenapi = this.options.openapi?.info ?? {};
-            const fromPkg = await readHostPackageJsonInfo();
-            const title = fromOpenapi.title ?? this.options.title ?? fromPkg.title ?? "DaloyJS API";
-            const version = fromOpenapi.version ?? this.options.version ?? fromPkg.version ?? "0.0.0";
+            const title = fromOpenapi.title ?? this.options.title ?? "DaloyJS API";
+            const version = fromOpenapi.version ?? this.options.version ?? "0.0.0";
             return { title, version };
         };
         const servers = opts.servers ?? this.asyncapiServersFromOpenAPI();
         const generate = async () => generateAsyncAPI(this, {
-            info: await resolveInfo(),
+            info: resolveInfo(),
             ...(servers ? { servers } : {}),
         });
         this.route({
@@ -1463,6 +1484,56 @@ export class App {
         this.resetBootGuardCache();
         return this;
     }
+    /**
+     * Register a literal tuple of independently defined route contracts.
+     *
+     * Unlike repeated statements against an already-declared `App` variable,
+     * this method returns an App whose route tuple includes every supplied
+     * contract. That preserves the exact no-codegen client surface across route
+     * files and feature modules.
+     *
+     * @param definitions - Readonly literal tuple of route definitions.
+     * @returns This App instance widened with every supplied route contract.
+     * @since 1.0.0
+     */
+    registerRoutes(definitions) {
+        for (const definition of definitions)
+            this.route(definition);
+        return this;
+    }
+    get(path, options, handler) {
+        return this.addHttpShorthand("GET", path, options, handler);
+    }
+    post(path, options, handler) {
+        return this.addHttpShorthand("POST", path, options, handler);
+    }
+    put(path, options, handler) {
+        return this.addHttpShorthand("PUT", path, options, handler);
+    }
+    patch(path, options, handler) {
+        return this.addHttpShorthand("PATCH", path, options, handler);
+    }
+    delete(path, options, handler) {
+        return this.addHttpShorthand("DELETE", path, options, handler);
+    }
+    head(path, options, handler) {
+        return this.addHttpShorthand("HEAD", path, options, handler);
+    }
+    addHttpShorthand(method, path, options, possibleHandler) {
+        if (options === null || typeof options !== "object" || typeof possibleHandler !== "function") {
+            throw new TypeError(`app.${method.toLowerCase()}(): expected (path, contract, handler); opaque responses require an explicit contract with acknowledgeNoResponseBodySchema: true`);
+        }
+        const contract = options;
+        return this.route({
+            ...contract,
+            method,
+            path,
+            operationId: typeof contract.operationId === "string"
+                ? contract.operationId
+                : inferOperationId(method, path),
+            handler: possibleHandler,
+        });
+    }
     /**
      * Register a WebSocket route. The handler runs when an HTTP client sends an
      * `Upgrade: websocket` request to `path`; the adapter performs the RFC 6455
@@ -1647,6 +1718,7 @@ export class App {
         }));
         this._coldPathHooksCache = undefined;
         const buckets = rateLimitConfig ? new Map() : null;
+        const trustProxyHeaders = appTrustsProxyHeaders(this.options);
         this.route({
             method: "GET",
             path,
@@ -1657,7 +1729,7 @@ export class App {
             acknowledgeNoResponseBodySchema: true,
             handler: async ({ request }) => {
                 if (buckets && rateLimitConfig) {
-                    const key = healthRouteKey(request);
+                    const key = healthRouteKey(request, trustProxyHeaders);
                     const now = Date.now();
                     const entry = buckets.get(key);
                     if (!entry || entry.resetMs <= now) {
@@ -1767,6 +1839,7 @@ export class App {
                 `to acknowledge that this probe is reachable without credentials.`);
         }
         const buckets = rateLimitConfig ? new Map() : null;
+        const trustProxyHeaders = appTrustsProxyHeaders(this.options);
         this.route({
             method: "GET",
             path,
@@ -1777,7 +1850,7 @@ export class App {
             acknowledgeNoResponseBodySchema: true,
             handler: async ({ request }) => {
                 if (buckets && rateLimitConfig) {
-                    const key = healthRouteKey(request);
+                    const key = healthRouteKey(request, trustProxyHeaders);
                     const now = Date.now();
                     const entry = buckets.get(key);
                     if (!entry || entry.resetMs <= now) {
@@ -1841,6 +1914,7 @@ export class App {
         }
         const rateLimitConfig = opts.rateLimit === false ? null : { limit: 60, windowMs: 60_000, ...(opts.rateLimit ?? {}) };
         const buckets = rateLimitConfig ? new Map() : null;
+        const trustProxyHeaders = appTrustsProxyHeaders(this.options);
         const log = this.log;
         // Only log report bodies when explicitly enabled. In
         // production this is opt-in; in development the body is included by
@@ -1854,7 +1928,7 @@ export class App {
             summary: "CSP / Reporting API violation receiver",
             handler: async ({ request }) => {
                 if (buckets && rateLimitConfig) {
-                    const key = healthRouteKey(request);
+                    const key = healthRouteKey(request, trustProxyHeaders);
                     const now = Date.now();
                     const entry = buckets.get(key);
                     if (!entry || entry.resetMs <= now) {
@@ -1882,7 +1956,7 @@ export class App {
                 const rawText = new TextDecoder().decode(rawBytes);
                 let parsed;
                 try {
-                    parsed = safeJsonParse(rawText);
+                    parsed = safeJsonParseLimited(rawText, 1000, 20); // CSP reports are small
                 }
                 catch {
                     throw new BadRequestError("Invalid JSON report body");
@@ -1890,7 +1964,7 @@ export class App {
                 if (parsed === undefined) {
                     throw new BadRequestError("Invalid JSON report body");
                 }
-                const ip = healthRouteKey(request);
+                const ip = healthRouteKey(request, trustProxyHeaders);
                 const userAgent = request.headers.get("user-agent");
                 try {
                     if (opts.onReport) {
@@ -2331,7 +2405,11 @@ export class App {
             : baseLog.child({
                 requestId,
                 method: request.method,
-                url: request.url,
+                // Never bind the raw request URL: query strings commonly carry
+                // OAuth codes, API keys, and signed-URL tokens. sanitizeUrlForLog
+                // keeps origin+path and redacts sensitive query values so 4xx/5xx
+                // lines cannot become a credential sink under the field name `url`.
+                url: sanitizeUrlForLog(request.url),
             });
         const stripFingerprint = this.options.stripServerHeaders !== false;
         let ctx;
@@ -2340,9 +2418,10 @@ export class App {
         let activeResponseHook = globalHooks.onResponse;
         let activeSendHook = globalHooks.onSend;
         try {
-            assertNoDuplicateSingletonHeaders(request.headers);
-            assertNoReservedInternalHeaders(request.headers);
-            assertHeaderCountWithinLimit(request.headers, this.options.maxHeaderCount ?? DEFAULT_MAX_HEADER_COUNT);
+            // Singleton-duplicate + reserved-prefix + header-count cap share ONE
+            // Headers.forEach walk (assertInboundHeaderGuards) instead of a
+            // three-Headers.get() pass plus a separate walk.
+            assertInboundHeaderGuards(request.headers, this.options.maxHeaderCount ?? DEFAULT_MAX_HEADER_COUNT);
             this.assertTrustProxyConfigured(request);
             this.assertBootGuards();
             if (globalHooks.onRequest !== undefined) {
@@ -2393,10 +2472,13 @@ export class App {
                 // `decorations`, iterate headers, or materialize a `Headers`
                 // instance just to be thrown away. The 204 OPTIONS preflight branch
                 // below uses its own `synthCtx`, so this skip is safe for it too.
+                const coldPreBody = method === "OPTIONS" ? undefined : this.coldPathHooks.preBody;
                 const coldGuards = method === "OPTIONS" ? undefined : this.coldPathHooks.beforeHandle;
                 const needsCtx = allowed.length > 0 && method === "OPTIONS"
                     ? false // OPTIONS path builds synthCtx
-                    : activeErrorHook !== undefined || coldGuards !== undefined;
+                    : activeErrorHook !== undefined ||
+                        coldPreBody !== undefined ||
+                        coldGuards !== undefined;
                 if (needsCtx) {
                     // `query` and `headers` are materialized lazily — the common
                     // `onError` hook reads `requestId` / path and never touches them,
@@ -2438,6 +2520,18 @@ export class App {
                     };
                     ctx.set.headers.set("x-request-id", requestId);
                 }
+                if (coldPreBody !== undefined) {
+                    const guardResult = coldPreBody(ctx);
+                    const guarded = isPromiseLike(guardResult) ? await guardResult : guardResult;
+                    if (guarded instanceof Response) {
+                        copyContextHeaders(ctx, guarded);
+                        if (!guarded.headers.has("x-request-id")) {
+                            guarded.headers.set("x-request-id", requestId);
+                        }
+                        const fin = finalizeResponse(guarded, ctx, this.coldPathHooks, stripFingerprint);
+                        return isPromiseLike(fin) ? await fin : fin;
+                    }
+                }
                 if (coldGuards !== undefined) {
                     const guardResult = coldGuards(ctx);
                     const guarded = isPromiseLike(guardResult) ? await guardResult : guardResult;
@@ -2497,11 +2591,10 @@ export class App {
                 if (isPromiseLike(routeOnRequestResult))
                     await routeOnRequestResult;
             }
-            // buildContext is sync unless a schema validator or body read actually
-            // suspends — branch on the promise so the fully-sync case never
-            // schedules a microtask.
-            const builtCtx = buildContext(request, getUrl, match.params, def, this.options);
-            ctx = isPromiseLike(builtCtx) ? await builtCtx : builtCtx;
+            // Build a minimal route context before validation or body I/O so cheap
+            // perimeter hooks can reject unauthenticated callers without consuming
+            // an attacker-controlled request stream.
+            ctx = createPreBodyContext(request, getUrl, match.params);
             // Stable two-field write keeps `ctx.state`'s hidden class consistent across
             // requests for the common no-decorator case. The decorations spread only
             // fires when `app.decorate()` was actually called.
@@ -2515,6 +2608,30 @@ export class App {
             const routeDecorations = match.handler.decorations;
             if (routeDecorations !== undefined)
                 Object.assign(state, routeDecorations);
+            if (allHooks.preBody !== undefined) {
+                const preBodyResult = allHooks.preBody(ctx);
+                const preBody = isPromiseLike(preBodyResult) ? await preBodyResult : preBodyResult;
+                const overriddenId = state.requestId;
+                if (typeof overriddenId === "string" && overriddenId.length > 0) {
+                    requestId = overriddenId;
+                }
+                if (preBody instanceof Response) {
+                    assertAcknowledgedSuccessfulHookResponse(preBody, def, "preBody");
+                    copyContextHeaders(ctx, preBody);
+                    if (!preBody.headers.has("x-request-id"))
+                        preBody.headers.set("x-request-id", requestId);
+                    if (hasFinalizeHook) {
+                        const fin = finalizeResponse(preBody, ctx, allHooks, stripFingerprint);
+                        return isPromiseLike(fin) ? await fin : fin;
+                    }
+                    return finalizeFast(preBody, stripFingerprint);
+                }
+            }
+            // Validation remains sync-first; only an async schema or an actual body
+            // stream read suspends. `beforeHandle` still receives the fully validated
+            // context for compatibility with body-aware middleware.
+            const validatedCtx = validateContext(ctx, def, this.options);
+            ctx = isPromiseLike(validatedCtx) ? await validatedCtx : validatedCtx;
             if (allHooks.beforeHandle !== undefined) {
                 const beforeResult = allHooks.beforeHandle(ctx);
                 const before = isPromiseLike(beforeResult) ? await beforeResult : beforeResult;
@@ -2526,6 +2643,7 @@ export class App {
                     requestId = overriddenId;
                 }
                 if (before instanceof Response) {
+                    assertAcknowledgedSuccessfulHookResponse(before, def, "beforeHandle");
                     copyContextHeaders(ctx, before);
                     if (!before.headers.has("x-request-id"))
                         before.headers.set("x-request-id", requestId);
@@ -2546,16 +2664,18 @@ export class App {
                 if (afterReturn !== undefined)
                     result = afterReturn;
             }
-            // Escape hatch: a handler (or an `afterHandle` transform) may return a
-            // raw web-standard `Response` — an AI SDK stream, a forwarded upstream
-            // response, or any pre-built body that no response schema can describe.
-            // It bypasses response-schema validation by design, but is finalized
-            // through the exact same path as every other response (and as the
-            // `beforeHandle` `Response` passthrough above), so no security control
-            // is skipped: `ctx.set` headers (secureHeaders / CORS) are copied on, the
-            // request id is added when absent, `onSend` / `onResponse` hooks run,
-            // fingerprint headers are stripped, and `HEAD` yields an empty body.
+            // Explicit escape hatch: a handler (or an `afterHandle` transform) may
+            // return a raw web-standard `Response` only when the route acknowledges
+            // that its body is opaque and will not be schema-validated. Without the
+            // acknowledgement, fail closed instead of silently bypassing response
+            // field stripping. Acknowledged responses still use the normal finalizer
+            // so headers, request ids, hooks, fingerprint stripping, and HEAD
+            // semantics remain intact.
             if (result instanceof Response) {
+                if (def.acknowledgeNoResponseBodySchema !== true) {
+                    throw new InternalError("Raw Response refused: set acknowledgeNoResponseBodySchema: true on the route " +
+                        "to explicitly accept that its response body bypasses schema validation.");
+                }
                 copyContextHeaders(ctx, result);
                 if (!result.headers.has("x-request-id")) {
                     result.headers.set("x-request-id", requestId);
@@ -2767,8 +2887,8 @@ export class App {
      * "draining" signal); then the app waits up to `timeoutMs` for in-flight
      * requests to settle; finally, {@link App.onClose} cleanups run.
      *
-     * Both Node and Bun adapters call this automatically on `SIGINT` / `SIGTERM`.
-     * Call it manually from custom runtimes or integration tests.
+     * The Node, Bun, and Deno adapters call this automatically on `SIGINT` /
+     * `SIGTERM`. Call it manually from custom runtimes or integration tests.
      *
      * @param timeoutMs - Maximum time (ms) to wait for inflight requests. Default: `10_000`.
      * @param reason - Optional human-readable reason forwarded to listeners.
@@ -2837,20 +2957,52 @@ export class App {
     }
 }
 // ---------- helpers ----------
+/** Derive a stable camel-case operation id from an HTTP method and route path. */
+function inferOperationId(method, path) {
+    if (path === "/")
+        return `${method.toLowerCase()}Root`;
+    const capitalizeWords = (value) => value
+        .split(/[-_]/)
+        .filter(Boolean)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join("");
+    const suffix = path
+        .slice(1)
+        .split("/")
+        .map((segment) => segment.startsWith(":") ? `By${capitalizeWords(segment.slice(1))}` : capitalizeWords(segment))
+        .join("");
+    return `${method.toLowerCase()}${suffix}`;
+}
 function joinPath(a, b) {
     const left = a.replace(/\/+$/, "");
     const right = b.startsWith("/") ? b : `/${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).
+/**
+ * Rate-limit / attribution key for built-in observability routes
+ * (`/healthz`, `/readyz`, `/metrics`, CSP report).
+ *
+ * Secure default: a single shared `"global"` bucket. Spoofable platform
+ * headers (`X-Real-IP`, `Fly-Client-IP`) are only read when the app has an
+ * explicit trusted-proxy posture (`trustProxy: true` or `behindProxy` set).
+ * `X-Forwarded-For` is never used here — probes and scrapers often hit the
+ * process directly, and a free-form XFF chain would let an attacker rotate
+ * identities to bypass the cap.
+ *
+ * @param request - Inbound request.
+ * @param trustProxyHeaders - When true, platform client-IP headers may be used.
+ * @returns A stable string key for the in-memory rate-limit map.
+ */
+function healthRouteKey(request, trustProxyHeaders) {
+    if (!trustProxyHeaders)
+        return "global";
     return request.headers.get("x-real-ip") ?? request.headers.get("fly-client-ip") ?? "global";
 }
+/** True when the app declared a trusted reverse-proxy posture. */
+function appTrustsProxyHeaders(options) {
+    return options.trustProxy === true || options.behindProxy !== undefined;
+}
 function corsOriginAllowsFromHooks(layers) {
     const allows = [];
     for (const hooks of layers) {
@@ -3118,6 +3270,7 @@ function mergeHooks(layers) {
     const beforeHandle = mergeBeforeHandle(firstResponse(pick("beforeHandle")), requiredScopes);
     const hooks = {
         onRequest: chain(pick("onRequest")),
+        preBody: _mergePreBodyWithEarlyRejections(layers),
         beforeHandle,
         afterHandle: pipeline(pick("afterHandle")),
         onError: firstResponse(pick("onError")),
@@ -3223,34 +3376,32 @@ function scalarConfigurationWithPreferredAuth(configuration, schemes) {
 }
 function finalizeResponse(res, ctx, hooks, stripFingerprint = true) {
     let final = res;
-    const finish = (f) => {
-        if (stripFingerprint) {
-            f.headers.delete("server");
-            f.headers.delete("x-powered-by");
-        }
-        if (hooks.onResponse !== undefined) {
-            const onResponseResult = hooks.onResponse(f);
-            if (isPromiseLike(onResponseResult)) {
-                return onResponseResult.then(() => f);
-            }
-        }
-        return f;
-    };
     if (hooks.onSend !== undefined) {
         const sentResult = hooks.onSend(res, ctx);
         if (isPromiseLike(sentResult)) {
             return sentResult.then((sent) => {
                 if (sent instanceof Response)
                     final = sent;
-                return finish(final);
+                return finishFinalize(final, hooks, stripFingerprint);
             });
         }
-        else {
-            if (sentResult instanceof Response)
-                final = sentResult;
+        if (sentResult instanceof Response)
+            final = sentResult;
+    }
+    return finishFinalize(final, hooks, stripFingerprint);
+}
+function finishFinalize(res, hooks, stripFingerprint) {
+    if (stripFingerprint) {
+        res.headers.delete("server");
+        res.headers.delete("x-powered-by");
+    }
+    if (hooks.onResponse !== undefined) {
+        const onResponseResult = hooks.onResponse(res);
+        if (isPromiseLike(onResponseResult)) {
+            return onResponseResult.then(() => res);
         }
     }
-    return finish(final);
+    return res;
 }
 function isPromiseLike(value) {
     return value !== null && typeof value === "object" && typeof value.then === "function";
@@ -3346,6 +3497,20 @@ function copyContextHeaders(ctx, res) {
             res.headers.set(k, v);
     });
 }
+/**
+ * Refuse a successful opaque hook response unless the route explicitly opts
+ * out of response-body schema protection. Error/denial responses remain
+ * available to authentication and authorization hooks without an opt-out.
+ */
+function assertAcknowledgedSuccessfulHookResponse(response, def, phase) {
+    if (response.status >= 400 ||
+        def.acknowledgeNoResponseBodySchema === true ||
+        isSchemaValidatedResponse(response)) {
+        return;
+    }
+    throw new InternalError(`Raw ${phase} Response refused: set acknowledgeNoResponseBodySchema: true on the route ` +
+        "to explicitly accept that its successful response body bypasses schema validation.");
+}
 function hasRequestSchema(request, key) {
     return !!request && !!request[key];
 }
@@ -3453,38 +3618,23 @@ class RequestContext {
         this._hSet = true;
     }
 }
-function buildContext(request, getUrl, rawParams, def, opts) {
-    const set = new LazyResponseSet();
-    const hasHeadersSchema = !!def.request?.headers;
-    const hasQuerySchema = !!def.request?.query;
+function createPreBodyContext(request, getUrl, rawParams) {
     let headersObj;
     let queryObj;
-    const buildHeaders = () => (headersObj ??= headersToObject(request.headers));
-    const buildQuery = () => (queryObj ??= queryToObject(getUrl().searchParams));
-    let params = rawParams;
-    let query;
-    let headers;
-    let body = undefined;
+    const ctx = new RequestContext(request, rawParams, {}, new LazyResponseSet());
+    ctx._hBuilder = () => (headersObj ??= headersToObject(request.headers));
+    ctx._qBuilder = () => (queryObj ??= queryToObject(getUrl().searchParams));
+    return ctx;
+}
+function validateContext(ctx, def, opts) {
+    const hasHeadersSchema = !!def.request?.headers;
+    const hasQuerySchema = !!def.request?.query;
+    const request = ctx.request;
+    const rawParams = ctx.params;
+    const buildHeaders = () => ctx.headers;
+    const buildQuery = () => ctx.query;
     const hasSchema = def.request?.params || def.request?.query || def.request?.headers || def.request?.body;
-    const finishContext = () => {
-        const ctx = new RequestContext(request, params, {}, set);
-        ctx.body = body;
-        if (hasQuerySchema) {
-            ctx._q = query;
-            ctx._qSet = true;
-        }
-        else {
-            ctx._qBuilder = buildQuery;
-        }
-        if (hasHeadersSchema) {
-            ctx._h = headers;
-            ctx._hSet = true;
-        }
-        else {
-            ctx._hBuilder = buildHeaders;
-        }
-        return ctx;
-    };
+    const finishContext = () => ctx;
     if (!hasSchema) {
         return finishContext();
     }
@@ -3497,11 +3647,11 @@ function buildContext(request, getUrl, rawParams, def, opts) {
         const r = def.request.body["~standard"].validate(raw);
         if (isPromiseLike(r)) {
             return r.then((resolved) => {
-                body = applyChecked(resolved, "body");
+                ctx.body = applyChecked(resolved, "body");
                 return finishContext();
             });
         }
-        body = applyChecked(r, "body");
+        ctx.body = applyChecked(r, "body");
         return finishContext();
     };
     const stepBody = () => {
@@ -3517,7 +3667,7 @@ function buildContext(request, getUrl, rawParams, def, opts) {
         if (!allowed.some((a) => ct.includes(a))) {
             throw new UnsupportedMediaTypeError(ct || "(none)", allowed);
         }
-        const raw = readBody(request, ct, opts.bodyLimitBytes, opts.multipart);
+        const raw = readBody(request, ct, opts.bodyLimitBytes, opts.multipart, opts.jsonMaxKeys, opts.jsonMaxDepth);
         if (isPromiseLike(raw))
             return raw.then(validateBodyAndFinish);
         return validateBodyAndFinish(raw);
@@ -3528,11 +3678,11 @@ function buildContext(request, getUrl, rawParams, def, opts) {
         const r = def.request.headers["~standard"].validate(buildHeaders());
         if (isPromiseLike(r)) {
             return r.then((resolved) => {
-                headers = applyChecked(resolved, "headers");
+                ctx.headers = applyChecked(resolved, "headers");
                 return stepBody();
             });
         }
-        headers = applyChecked(r, "headers");
+        ctx.headers = applyChecked(r, "headers");
         return stepBody();
     };
     const stepQuery = () => {
@@ -3541,22 +3691,22 @@ function buildContext(request, getUrl, rawParams, def, opts) {
         const r = def.request.query["~standard"].validate(buildQuery());
         if (isPromiseLike(r)) {
             return r.then((resolved) => {
-                query = applyChecked(resolved, "query");
+                ctx.query = applyChecked(resolved, "query");
                 return stepHeaders();
             });
         }
-        query = applyChecked(r, "query");
+        ctx.query = applyChecked(r, "query");
         return stepHeaders();
     };
     if (def.request?.params) {
         const r = def.request.params["~standard"].validate(rawParams);
         if (isPromiseLike(r)) {
             return r.then((resolved) => {
-                params = applyChecked(resolved, "params");
+                ctx.params = applyChecked(resolved, "params");
                 return stepQuery();
             });
         }
-        params = applyChecked(r, "params");
+        ctx.params = applyChecked(r, "params");
     }
     return stepQuery();
 }
@@ -3621,10 +3771,13 @@ function readBodyBytesFast(req, limit) {
     }
     return undefined;
 }
-function parseJsonBodyBytes(bytes) {
+function parseJsonBodyBytes(bytes, maxKeys, maxDepth) {
     if (bytes.byteLength === 0)
         return undefined;
-    return safeJsonParse(TEXT_DECODER.decode(bytes));
+    const text = TEXT_DECODER.decode(bytes);
+    // Use the limited parser when limits are enabled; falls back to safe behavior
+    // when limits are disabled (0 / negative).
+    return safeJsonParseLimited(text, maxKeys, maxDepth);
 }
 function parseUrlencodedBodyBytes(bytes) {
     const params = new URLSearchParams(TEXT_DECODER.decode(bytes));
@@ -3646,12 +3799,12 @@ function parseUrlencodedBodyBytes(bytes) {
  * streaming `readBodyLimited` promise otherwise. All parsing keeps the
  * prototype-pollution-safe semantics of the previous implementation.
  */
-function readBody(req, ct, limit, multipart) {
+function readBody(req, ct, limit, multipart, jsonMaxKeys = 10_000, jsonMaxDepth = 50) {
     if (ct.includes("application/json")) {
         const fast = readBodyBytesFast(req, limit);
         if (fast !== undefined)
-            return parseJsonBodyBytes(fast);
-        return readBodyLimited(req, limit).then(parseJsonBodyBytes);
+            return parseJsonBodyBytes(fast, jsonMaxKeys, jsonMaxDepth);
+        return readBodyLimited(req, limit).then((b) => parseJsonBodyBytes(b, jsonMaxKeys, jsonMaxDepth));
     }
     if (ct.includes("application/x-www-form-urlencoded")) {
         const fast = readBodyBytesFast(req, limit);
@@ -3877,11 +4030,46 @@ function runHandler(def, ctx, requestTimeoutMs) {
     if (requestTimeoutMs === 0 || !isPromiseLike(result)) {
         return result;
     }
-    return withTimeout(result, requestTimeoutMs);
+    return withTimeout(result, requestTimeoutMs, ctx.request);
+}
+/**
+ * Fire an adapter's request abort hook (see {@link DALOY_REQUEST_ABORT}) if the
+ * request shim exposes one. Called as a method so `this` stays bound to the
+ * request. A no-op when the hook is absent (platform-managed `Request.signal`
+ * or a direct `app.fetch()` caller), so the caller must not depend on the
+ * signal actually firing.
+ *
+ * @param request - The in-flight request whose signal should be aborted.
+ * @param reason - Abort reason surfaced on `request.signal.reason`.
+ */
+function abortRequest(request, reason) {
+    const hooked = request;
+    hooked[DALOY_REQUEST_ABORT]?.(reason);
 }
-function withTimeout(p, ms) {
+/**
+ * Race a handler promise against the per-request timeout.
+ *
+ * On timeout the request's {@link DALOY_REQUEST_ABORT} hook is fired first —
+ * aborting `request.signal` with a `TimeoutError` `DOMException` (the same
+ * reason shape as `AbortSignal.timeout()`) so cooperative downstream I/O the
+ * handler forwarded the signal to unwinds — and then the returned promise
+ * rejects with a {@link RequestTimeoutError} so the client receives a `408`.
+ * The handler promise itself keeps a rejection handler attached, so a late
+ * settle (including the `AbortError` from the work it just cancelled) never
+ * surfaces as an unhandled rejection.
+ *
+ * @typeParam T - The handler's resolved value type.
+ * @param p - The handler (or hook chain) promise to bound.
+ * @param ms - Timeout in milliseconds; assumed non-zero by the caller.
+ * @param request - The in-flight request, used to fire the abort hook.
+ * @returns A promise that settles with the handler result or a 408 timeout.
+ */
+function withTimeout(p, ms, request) {
     return new Promise((resolve, reject) => {
-        const t = setTimeout(() => reject(new RequestTimeoutError(ms)), ms);
+        const t = setTimeout(() => {
+            abortRequest(request, new DOMException(`Request exceeded ${ms}ms`, "TimeoutError"));
+            reject(new RequestTimeoutError(ms));
+        }, ms);
         p.then((v) => {
             clearTimeout(t);
             resolve(v);
@@ -3918,103 +4106,3 @@ function serializeErr(err) {
 export function createApp(options = {}) {
     return new App(options);
 }
-const PACKAGE_JSON_CACHE = {};
-/**
- * Best-effort lazy read of the host project's `package.json` so that
- * `new App({ docs: true })` with no explicit `openapi.info` still produces
- * a spec titled after the user's package. Reads `package.json` first; if
- * none is found while walking up from `process.cwd()`, falls back to
- * `deno.json` / `deno.jsonc` so Deno projects get the same DX without a
- * `package.json`. Returns an empty object on edge runtimes (Cloudflare
- * Workers) where `node:fs` is absent, on any I/O or parse
- * error, and when nothing is found.
- *
- * The result is memoized at module scope: manifests do not change
- * during a process lifetime and we never want this to add latency to
- * subsequent docs requests.
- */
-function readHostPackageJsonInfo() {
-    if (PACKAGE_JSON_CACHE.value !== undefined)
-        return PACKAGE_JSON_CACHE.value;
-    const promise = (async () => {
-        const empty = {};
-        const proc = globalThis.process;
-        if (!proc || typeof proc.cwd !== "function")
-            return empty;
-        let fs;
-        let path;
-        try {
-            fs = await import("node:fs");
-            path = await import("node:path");
-        }
-        catch {
-            return empty;
-        }
-        let dir;
-        try {
-            dir = proc.cwd();
-        }
-        catch {
-            return empty;
-        }
-        const parseManifest = (raw, allowComments) => {
-            // deno.jsonc allows // line comments and /* block */ comments. Strip
-            // them before parsing — naively, but well enough for typical manifests.
-            const text = allowComments
-                ? raw.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:\\])\/\/.*$/gm, "$1")
-                : raw;
-            return JSON.parse(text);
-        };
-        const extractInfo = (json) => {
-            const result = {};
-            if (typeof json.name === "string" && json.name.length > 0) {
-                result.title = json.name;
-            }
-            if (typeof json.version === "string" && json.version.length > 0) {
-                result.version = json.version;
-            }
-            if (typeof json.description === "string" && json.description.length > 0) {
-                result.description = json.description;
-            }
-            return result;
-        };
-        // Walk up to the filesystem root looking for a manifest. Cap depth so
-        // a deeply-nested cwd can't cause excessive stat calls. At each level,
-        // prefer package.json, then deno.json, then deno.jsonc.
-        for (let i = 0; i < 12; i++) {
-            const pkg = path.join(dir, "package.json");
-            const denoJson = path.join(dir, "deno.json");
-            const denoJsonc = path.join(dir, "deno.jsonc");
-            try {
-                if (fs.existsSync(pkg)) {
-                    return extractInfo(parseManifest(fs.readFileSync(pkg, "utf8"), false));
-                }
-                if (fs.existsSync(denoJson)) {
-                    return extractInfo(parseManifest(fs.readFileSync(denoJson, "utf8"), false));
-                }
-                if (fs.existsSync(denoJsonc)) {
-                    return extractInfo(parseManifest(fs.readFileSync(denoJsonc, "utf8"), true));
-                }
-            }
-            catch {
-                return empty;
-            }
-            const parent = path.dirname(dir);
-            if (parent === dir)
-                break;
-            dir = parent;
-        }
-        return empty;
-    })();
-    PACKAGE_JSON_CACHE.value = promise;
-    return promise;
-}
-/**
- * Test helper: clear the cached package.json read so each test starts
- * from a fresh lookup. Not part of the public API.
- *
- * @internal
- */
-export function _resetPackageJsonCacheForTests() {
-    PACKAGE_JSON_CACHE.value = undefined;
-}