@daloyjs/core 1.0.0-beta.7 → 1.0.0-rc.1

package/README.md

@@ -509,7 +509,7 @@ The core only ever sees `Request → Response`. Adapters live at the edge.
 
 ## Status
 
-DaloyJS is now in the **`1.0.0` beta** (`1.0.0-beta.7`). The public API is feature-complete and stable for the 1.0 line; from `1.0.0` onward, breaking changes follow SemVer and deprecations get at least one minor cycle. Small adjustments are still possible before the `1.0.0` GA if beta feedback surfaces something. The framework is already in use for production trials.
+DaloyJS is at **`1.0.0-rc.1`**, a security-hardening release candidate. Because the framework has no external users yet, this RC ships a few intentional breaking changes (see the [CHANGELOG](CHANGELOG.md)) to get the secure-by-default posture right before GA rather than deferring them; the generated OpenAPI contract is unchanged. From `1.0.0` GA onward, breaking changes follow SemVer with deprecations getting at least one minor cycle. The framework is already in use for production trials.
 
 **Release quality bar.** Every release ships with **≥90% line + function coverage and ≥90% branch coverage**, strict TypeScript, OpenSSF Scorecard, CodeQL + Opengrep dual SAST, zizmor workflow linting, and npm provenance. Coverage was relaxed from a former 100% gate so complex security work isn't blocked chasing throwaway tests for unreachable defensive branches or tsx source-map phantoms; see [AGENTS.md](AGENTS.md) for the policy.
 
@@ -520,7 +520,7 @@ DaloyJS is now in the **`1.0.0` beta** (`1.0.0-beta.7`). The public API is featu
 - Zero-config OpenAPI `info` autofill from `package.json` (Node / Bun) or `deno.json` / `deno.jsonc` (Deno); explicit `openapi.info` values always win.
 - RFC 7231 + RFC 5789 HTTP-method allowlist enforced inside `app.route()` (WebDAV, `TRACE`, `CONNECT` rejected at the framework boundary).
 - AI-friendly route metadata via optional `meta: { examples, extensions, summary, description, tags }`; examples are validated against your schemas at build time, surfaced as OpenAPI `examples` + `x-daloy-*` extensions, and dumped as `routes.json` / `routes.yaml` via `daloy inspect --ai`.
-- Dependency-free MCP Streamable HTTP server helpers at `@daloyjs/core/mcp`: `createMcpHandler()` exposes tools (with `outputSchema`, `annotations`, and icons), resources, RFC 6570 resource templates, and prompts (with required-argument enforcement) over JSON-RPC 2.0 and validates `Origin` against DNS rebinding (with an `allowedOrigins` allowlist), while `mcpRoutes("/mcp", handler)` mounts the POST / GET / OPTIONS Daloy routes — with the JSON-RPC envelope schema surfaced in OpenAPI — for a dedicated MCP service with the same auth, rate-limit, body-limit, and timeout middleware as any other app.
+- Dependency-free MCP Streamable HTTP server helpers at `@daloyjs/core/mcp`: `createMcpHandler()` exposes tools (with `outputSchema`, `annotations`, and icons), resources, RFC 6570 resource templates, and prompts (with required-argument enforcement) over JSON-RPC 2.0 and validates `Origin` against DNS rebinding (with an `allowedOrigins` allowlist), while `mcpRoutes("/mcp", handler)` mounts the POST / GET / OPTIONS Daloy routes — with the JSON-RPC envelope schema surfaced in OpenAPI — for a dedicated MCP service with the same auth, rate-limit, body-limit, and timeout middleware as any other app. Every `tools/call` argument is validated server-side against the tool's `inputSchema` (a dependency-free JSON-Schema subset — `type`/`required`/`properties`/`additionalProperties`/`enum`/`const`/bounds; exposed as `validateMcpInput()`) before the handler runs, rejecting a mismatch with JSON-RPC `-32602`; the JSON-RPC body is parsed with prototype-pollution-safe `safeJsonParse`; and an unauthenticated `mcpRoutes()` endpoint refuses to boot in production unless opted out with `mcpRoutes(path, handler, { public: true })`.
 - API lifecycle and breaking-change detection: mark routes `deprecated` or give them a `sunset` date to emit RFC 8594 `Deprecation` / `Sunset` headers and an `x-sunset` OpenAPI extension, then gate CI with `diffOpenAPI()` / the `daloy diff` command, which fail on a breaking change versus the last published spec.
 - In-process test client (`app.request()`), contract-test runner (gated in CI via `daloy inspect --check` and shipped as a default test in every `create-daloy` template), in-process typed client, and Hey API codegen via `pnpm gen`.
 
@@ -549,7 +549,9 @@ DaloyJS is now in the **`1.0.0` beta** (`1.0.0-beta.7`). The public API is featu
 
 The framework refuses to start (or to construct) when configuration is unsafe:
 
-- Weak session secrets, `cors({ origin: "*" })` with credentials, `session()` + state-changing route without `csrf()`, and unconfigured `X-Forwarded-*` in production.
+- Weak session secrets, `cors({ origin: "*" })` with credentials, `session()` + state-changing route without `csrf()`, and unconfigured forwarded / client-IP headers (`X-Forwarded-*`, `X-Real-IP`, and vendor headers `CF-Connecting-IP` / `Fly-Client-IP` / `True-Client-IP`) in production.
+- **Shadow auth**: a route that declares an `auth:` requirement (advertised as protected in the OpenAPI `security` list) but installs no authentication hook to enforce it. Built-in auth middlewares (`bearerAuth` / `basicAuth` / `jwk` / `httpSignatureAuth` / `clientCertAuth`) satisfy the guard automatically; mark a custom auth hook (or upstream-gateway-enforced auth) with `markAuthHook()`.
+- **Unauthenticated MCP**: an `mcpRoutes()` endpoint with no auth hook — MCP tools are model-controlled and side-effecting. Opt out for a genuinely public server with `mcpRoutes(path, handler, { public: true })`.
 - `secureDefaults: false` in production unless `acknowledgeInsecureDefaults: true` is set, plus a once-per-process `error` log naming every disabled default.
 - `preset: "internal-service"` topology preset for service-to-service deployments behind a mesh / sidecar / private network: turns OFF the browser-only guards (auto `secureHeaders`, `corsCrossOriginGuard`, `csrf` boot guard, unconfigured `X-Forwarded-*` guard) while keeping every input, parser, credential, SSRF, weak-secret, and refuse-to-boot guard ON. Per-knob options still win, the choice is logged at boot under `event: "security.preset.applied"`, and the live posture is auditable via `app.getSecurityPosture()`.
 - `createJwtSigner()` / `createJwtVerifier()` refuse `alg: "none"`, accept only an explicit allowlist, refuse HS + JWK combinations, refuse to sign without `exp`, and refuse HS-shaped secrets under 32 bytes (RFC 7518 §3.2).
@@ -587,13 +589,13 @@ The framework refuses to start (or to construct) when configuration is unsafe:
 - `clientCertAuth()` mTLS / client-certificate auth at `@daloyjs/core/mtls`: authenticate zero-trust / service-to-service callers by their TLS client certificate from two sources — **native TLS** (the Node adapter lazily reads the peer cert off the socket; plain requests pay nothing) or a **TLS-terminating proxy** (Envoy `X-Forwarded-Client-Cert` and nginx/HAProxy-style structured headers). `requireVerified` by default, exact `allowSubjectCNs` / `allowIssuerCNs`, **constant-time** `allowFingerprints`, `allowSANs` (SPIFFE/DNS/URI/IP, `TYPE:value` or bare), validity-window enforcement, and a custom async `verify()` hook. Missing cert → `401` problem+json with `Cache-Control: no-store`; any failed check → `403` (never echoes cert details). The accepted `ClientCertificate` is stamped on `ctx.state`. `parseForwardedClientCert()` / `normalizePeerCertificate()` exported standalone. Zero runtime dependencies.
 - `autoBan()` adaptive auto-ban (fail2ban-style) at `@daloyjs/core/auto-ban`: temporarily ban abusive clients after repeated suspicious responses (default `401` / `403` / `429`, configurable `watchStatuses`) within a rolling `windowMs`. Bans **escalate** exponentially for repeat offenders (`banMs` → `2×` → `4×`, capped at `maxBanMs`) and **decay** once the client goes quiet. Observes the outgoing status via `onSend` (counts failures from any downstream middleware/handler), enforces in `beforeHandle`. Secure-by-default identity attribution — refuses to construct without `keyGenerator` or `trustProxyHeaders` so one offender can never ban everyone; unattributable requests are skipped. Pluggable `AutoBanStore` (mirrors the `rateLimit()` store; in-memory default, Redis-able for multi-instance), `groupId` sharing across route groups, `429`/`403` ban response with `Retry-After`, and `onBan` / `onStrike` hooks. Zero runtime dependencies.
 - `botGuard()` bot / User-Agent management at `@daloyjs/core/bot-guard`: the in-app equivalent of Nginx/WAF bot rules. Blocks empty/missing `User-Agent` (default on) and known-abusive `User-Agent` strings / `RegExp`s, and **verifies declared crawlers** — a request claiming to be Googlebot/Bingbot is confirmed via reverse-DNS + forward-confirm (the method Google and Bing document), so a spoofed `User-Agent` can't impersonate a trusted crawler. Ships `GOOGLEBOT` / `BINGBOT` / `WELL_KNOWN_BOTS` presets and accepts custom `VerifiedBotRule`s. Allowlist-first (`allowUserAgents` bypasses every rule), secure-by-default (`verifiedBots` refuses to construct without an IP source; unverifiable crawlers blocked unless `blockUnverifiableBots: false`), subdomain-boundary-safe domain matching, per-IP verification cache to keep DNS off the hot path, `mode: "log"` monitor mode, `onBlock` callback, and a pluggable `BotResolver` (default lazy `node:dns/promises`). Zero runtime dependencies.
-- `ipReputation()` IP reputation / dynamic denylist feed at `@daloyjs/core/ip-reputation`: wires pluggable, periodically-refreshed abuse feeds (Tor exit lists, Spamhaus DROP, cloud-abuse ranges, or your own threat intel) into the request path without a redeploy, reusing the same SSRF-grade CIDR matcher as `ipRestriction()`. Ships `urlFeed()` (fetches newline / Spamhaus-DROP-style lists, skips comment lines, keeps good rows from a partially-malformed feed) plus a custom `IpReputationFeed` interface. **Fail-open by design** — a feed that can't be loaded (initial or refresh) never blocks traffic; the last-known-good list is retained per feed. Periodic `unref`'d refresh, `mode: "log"` monitor mode, `onMatch` / `onError` callbacks, manual `refresh()` / `stop()` / `has()` / `size` controller, and pluggable IP resolution (`trustProxyHeaders` / `resolveIp`). Zero runtime dependencies.
+- `ipReputation()` IP reputation / dynamic denylist feed at `@daloyjs/core/ip-reputation`: wires pluggable, periodically-refreshed abuse feeds (Tor exit lists, Spamhaus DROP, cloud-abuse ranges, or your own threat intel) into the request path without a redeploy, reusing the same SSRF-grade CIDR matcher as `ipRestriction()`. Ships `urlFeed()` (fetches newline / Spamhaus-DROP-style lists, skips comment lines, keeps good rows from a partially-malformed feed; **SSRF-hardened by default** — the outbound fetch runs through `fetchGuard()`, so a compromised feed host can't redirect it into cloud-metadata / internal space; override via `fetchImpl`) plus a custom `IpReputationFeed` interface. **Fail-open by design** — a feed that can't be loaded (initial or refresh) never blocks traffic; the last-known-good list is retained per feed. Periodic `unref`'d refresh, `mode: "log"` monitor mode, `onMatch` / `onError` callbacks, manual `refresh()` / `stop()` / `has()` / `size` controller, and pluggable IP resolution (`trustProxyHeaders` / `resolveIp`). Zero runtime dependencies.
 - `geoBlock()` GeoIP / geo-blocking at `@daloyjs/core/geo-block`: country allow/deny middleware that maps the client IP to an ISO 3166-1 alpha-2 country and rejects (or logs) traffic from countries you don't serve. **No bundled GeoIP database and no runtime dependency** — supply either an operator-owned `lookupCountry(ip)` (a MaxMind / `ip2location` reader, or your own table, reusing the trusted-proxy `X-Forwarded-For` / `X-Real-IP` IP resolution) or a `resolveCountry(ctx)` that reads an edge-injected header (`CF-IPCountry`, `CloudFront-Viewer-Country`, `x-vercel-ip-country`). Deny wins over allow (least privilege); **allow-lists fail closed** on an unknown country while deny-only fails open (overridable via `allowUnknownCountry`). Country codes are validated at construction so typos throw instead of silently never matching. `mode: "log"` monitor mode with an `onBlock` decision hook (`denied_country` / `not_in_allowlist` / `unknown_country`), the resolved country stamped on `ctx.state.geo` for allowed requests, and a `403` problem+json rejection that never echoes the country/IP. Zero runtime dependencies.
 - `concurrencyLimit()` per-route / per-client concurrency limits + queueing at `@daloyjs/core/concurrency-limit`: HAProxy `maxconn`/queue parity at the app layer. Bounds in-flight requests through a surface with a per-bucket semaphore (`maxConcurrent`), a bounded FIFO queue (`maxQueue`) with an optional `queueTimeoutMs`, and a fast `503` + `Retry-After` once the queue is full or the wait times out. Partition the budget with `scope`: `"global"` (default), `"route"` (per `method + path`), `"client"` (per identity, needs `trustProxyHeaders`/`keyGenerator`), or a custom function (`undefined` skips limiting, fail-open). Acquires in `beforeHandle` and releases in `onSend`, so slots are freed on success, error, and short-circuit paths alike — never leaked. `onReject` observability hook, configurable `retryAfterSeconds`/`message`. Complements the `maxConnections` socket cap and `loadShedding()`. Zero runtime dependencies. HAProxy `maxconn`/queue parity at the app layer. Bounds in-flight requests through a surface with a per-bucket semaphore (`maxConcurrent`), a bounded FIFO queue (`maxQueue`) with an optional `queueTimeoutMs`, and a fast `503` + `Retry-After` once the queue is full or the wait times out. Partition the budget with `scope`: `"global"` (default), `"route"` (per `method + path`), `"client"` (per identity, needs `trustProxyHeaders`/`keyGenerator`), or a custom function (`undefined` skips limiting, fail-open). Acquires in `beforeHandle` and releases in `onSend`, so slots are freed on success, error, and short-circuit paths alike — never leaked. `onReject` observability hook, configurable `retryAfterSeconds`/`message`. Complements the `maxConnections` socket cap and `loadShedding()`. Zero runtime dependencies.
 - `requestDecompression()` inbound decompression-bomb guard at `@daloyjs/core/request-decompression`: core is safe by omission (it never decompresses request bodies), so this is the opt-in middleware for services that must accept compressed uploads. Inflates `gzip` / `deflate` bodies behind two caps enforced **during** inflation so a zip bomb is aborted before it is fully materialised: an absolute `maxDecompressedBytes` (required) and an expansion-ratio `maxRatio` (default `100`), both rejecting with `413`. The compressed upload itself is bounded by `maxCompressedBytes` (default 1 MiB) before a byte is inflated. Unknown, non-allowlisted, runtime-unsupported, or **layered** (`gzip, gzip`) encodings are refused `415`; malformed streams `400`; bodyless / uncompressed / `identity` / `GET` / `HEAD` traffic passes through untouched. Runs in `onRequest` and stashes the inflated bytes so schema-validated bodies and raw-body handlers both see the decompressed payload. `onBomb` observability hook, exported `decompressRequestBody()` for custom flows. Built on web-standard `DecompressionStream` (brotli excluded — not in the spec). Zero runtime dependencies.
 - `waf()` opt-in WAF-lite signature/anomaly inbound-inspection middleware at `@daloyjs/core/waf`: a first-party defense-in-depth layer for teams without an edge WAF (it does **not** replace ModSecurity / a CDN WAF). Wires DaloyJS' high-confidence injection signatures — SQLi, XSS, NoSQL-operator injection (reusing `hasMongoOperatorKeys` for a structural body check), and command injection — into a single scored inbound-inspection pass over the decoded path, the raw + decoded query string, an opt-in header allowlist, and the validated body. Each rule that fires adds an anomaly `score`; reaching `blockThreshold` (default `5`) rejects with a generic `403` (block mode) or merely reports via `onMatch` (log mode) so operators can tune against real traffic first. Per-rule enable/disable + score overrides, inspection-surface toggles, control-character-stripped log samples, and bounded scanning (`maxValueLength` / `maxBodyNodes`) keep a hostile payload from becoming CPU-DoS. The `403` body never names the rule that fired. Zero runtime dependencies.
 - Built-in docs UI Subresource Integrity (SRI): `DocsAssetOptions` lets `scalarHtml()` / `swaggerUiHtml()` / `redocHtml()` and the `docs: { assets }` auto-mount pin version-exact `*Integrity` hashes (`sha256`/`sha384`/`sha512`) plus a `crossOrigin` value (default `"anonymous"`) on the CDN-loaded Scalar / Swagger UI / Redoc `<script>` / `<link>` tags, so a poisoned jsDelivr asset can't execute. Malformed SRI values throw a `TypeError` at startup (browsers ignore unparseable `integrity`, so failing loud avoids a false sense of protection); self-hosting the assets via the same `assets` URLs stays supported. Zero runtime dependencies.
-- HTTP Message Signatures (RFC 9421) at `@daloyjs/core/http-signatures`: first-party sign/verify for server-to-server request authentication via the standard `Signature` / `Signature-Input` headers — complements the inbound-only webhook HMAC and `clientCertAuth()` mTLS. `signMessage()` / `signRequest()` build an RFC 9421 signature base over derived components (`@method`, `@target-uri`, `@authority`, `@scheme`, `@request-target`, `@path`, `@query`, `@query-param`, `@status`) and HTTP fields with Structured-Fields header serialization; `verifyMessage()` / `verifyRequest()` and the `httpSignatureAuth()` middleware check them. Algorithms `hmac-sha256` / `ed25519` / `ecdsa-p256-sha256` / `ecdsa-p384-sha384` / `rsa-pss-sha512` / `rsa-v1_5-sha256` via WebCrypto (no `node:` imports). Secure-by-default verify: a **mandatory `algorithms` allowlist** (no implicit "any alg"), optional per-key alg pinning to defeat algorithm-confusion, a required `created` timestamp with a 300s freshness window, `created`-in-future / `expires` skew rejection, configurable `requiredComponents`, a 32-byte raw-HMAC floor, and `nonce` replay defense; the middleware answers a missing/invalid signature with `401` + `Cache-Control: no-store` and stamps the verified result on `ctx.state.httpSignature`. Ships RFC 9530 `contentDigest()` / `verifyContentDigest()` to bind the request body. Zero runtime dependencies.
+- HTTP Message Signatures (RFC 9421) at `@daloyjs/core/http-signatures`: first-party sign/verify for server-to-server request authentication via the standard `Signature` / `Signature-Input` headers — complements the inbound-only webhook HMAC and `clientCertAuth()` mTLS. `signMessage()` / `signRequest()` build an RFC 9421 signature base over derived components (`@method`, `@target-uri`, `@authority`, `@scheme`, `@request-target`, `@path`, `@query`, `@query-param`, `@status`) and HTTP fields with Structured-Fields header serialization; `verifyMessage()` / `verifyRequest()` and the `httpSignatureAuth()` middleware check them. Algorithms `hmac-sha256` / `ed25519` / `ecdsa-p256-sha256` / `ecdsa-p384-sha384` / `rsa-pss-sha512` / `rsa-v1_5-sha256` via WebCrypto (no `node:` imports). Secure-by-default verify: a **mandatory `algorithms` allowlist** (no implicit "any alg"), optional per-key alg pinning to defeat algorithm-confusion, a required `created` timestamp with a 300s freshness window, `created`-in-future / `expires` skew rejection, configurable `requiredComponents`, a 32-byte raw-HMAC floor, a 2048-bit RSA modulus floor (NIST SP 800-131A, parity with the JWT verifier), and `nonce` replay defense; the middleware answers a missing/invalid signature with `401` + `Cache-Control: no-store` and stamps the verified result on `ctx.state.httpSignature`. Ships RFC 9530 `contentDigest()` / `verifyContentDigest()` to bind the request body. Zero runtime dependencies.
 - `compression()` built on web-standard `CompressionStream` (prefers `br` > `gzip` > `deflate`), with BREACH-aware always-on guards (skips `Set-Cookie`, `Authorization`, session / CSRF cookies, already-compressed content types), `minimumSize: 1024`, negative-compression-ratio post-check, no configurable `compressLevel` knob (CPU-DoS defense — `level: 9` is refused at construction), always-on `Vary: Accept-Encoding`, and strong → weak ETag downgrade per RFC 9110 §8.8.3.
 - `etag()` helper auto-skips on `Set-Cookie` and private / no-store / no-cache `Cache-Control` (cross-tenant fingerprinting defense).
 - `timing` / `timingSafeEqual` helpers.

package/dist/adapters/node.js

@@ -4,7 +4,7 @@
  */
 import { createServer, } from "node:http";
 import { Readable } from "node:stream";
-import { DALOY_RAW_BODY, DALOY_RAW_STREAM, DALOY_REQUEST_RAW_BODY } from "../app.js";
+import { DALOY_RAW_BODY, DALOY_RAW_STREAM, DALOY_REQUEST_RAW_BODY, DALOY_LIGHT_RESPONSE_OK, } from "../app.js";
 import { setClientCertificate, normalizePeerCertificate, } from "../mtls.js";
 import { FrameSink, encodeFrame, encodeClosePayload, encodeSendPayload, validateUpgrade, validateSelectedSubprotocol, checkWebSocketOrigin, WS_OPCODE, WS_CLOSE_CODE, WS_READY_STATE, WS_MAX_CONTROL_PAYLOAD, WebSocketProtocolError, WebSocketPayloadTooLargeError, } from "../websocket.js";
 /**
@@ -291,6 +291,209 @@ function writeAdapterError(res, e) {
         res.destroy(e);
     }
 }
+/**
+ * Lazily-materializing stand-in for an incoming WHATWG `Request`.
+ *
+ * Constructing a real (undici) `Request` costs ~4µs for GET and far more for
+ * POST-with-body (the constructor wraps the body bytes in a WHATWG
+ * `ReadableStream` that DaloyJS then bypasses anyway via the
+ * `DALOY_REQUEST_RAW_BODY` fast path). The dispatch hot path only ever reads
+ * `url`, `method`, `headers`, `signal`, and the raw-body symbol — so this
+ * shell carries those directly and defers the real `Request` until one of the
+ * less common surfaces (`json()`, `clone()`, `body`, `formData()`, …) is
+ * actually touched.
+ *
+ * Fidelity notes:
+ * - `instanceof Request` holds (prototype chain is re-rooted onto
+ *   `Request.prototype`), and every WHATWG method/getter is overridden here,
+ *   so nothing hits undici's brand-checked prototype accessors.
+ * - `signal` is an inert per-instance `AbortSignal`. This matches the real
+ *   adapter behaviour today: the Node adapter never wires socket aborts into
+ *   the request signal, so the signal never fires in either implementation.
+ * - Passing this object directly to `fetch()` is not supported (undici
+ *   brand-checks its input) — forward with `request.clone()` instead, which
+ *   returns a real `Request`. This mirrors @hono/node-server's shim.
+ *
+ * Security parity: the `Headers` instance is built eagerly from `rawHeaders`
+ * exactly as before, so the duplicate-singleton / reserved-header /
+ * header-count guards in `App.dispatch` see the identical view they saw with
+ * a real `Request`.
+ */
+/** Shared decoder for LightRequest's direct body reads. */
+const LIGHT_TEXT_DECODER = new TextDecoder();
+class LightRequest {
+    #url;
+    #method;
+    #headers;
+    #bodyBytes;
+    #real;
+    #signal;
+    constructor(url, method, headers, bodyBytes) {
+        this.#url = url;
+        this.#method = method;
+        this.#headers = headers;
+        this.#bodyBytes = bodyBytes;
+    }
+    /** Build (once) and return the real undici `Request` for rare surfaces. */
+    #materialize() {
+        return (this.#real ??=
+            this.#bodyBytes !== undefined
+                ? new Request(this.#url, {
+                    method: this.#method,
+                    headers: this.#headers,
+                    body: this.#bodyBytes,
+                })
+                : new Request(this.#url, { method: this.#method, headers: this.#headers }));
+    }
+    get url() {
+        return this.#url;
+    }
+    get method() {
+        return this.#method;
+    }
+    get headers() {
+        return this.#headers;
+    }
+    get signal() {
+        // Inert, lazily created: the Node adapter has never wired socket
+        // teardown into the request signal, so a never-firing signal is
+        // behaviourally identical to the one a real `Request` would carry.
+        return (this.#signal ??= new AbortController().signal);
+    }
+    get body() {
+        return this.#materialize().body;
+    }
+    get bodyUsed() {
+        if (this.#real !== undefined)
+            return this.#real.bodyUsed;
+        return this.#directlyConsumed;
+    }
+    /**
+     * Set when a body method served the pre-buffered bytes directly (no real
+     * `Request` ever existed). Subsequent body reads reject with a `TypeError`
+     * exactly like a consumed WHATWG body would.
+     */
+    #directlyConsumed = false;
+    /**
+     * Serve a body read straight from the pre-buffered bytes when possible.
+     * Returns `undefined` when the caller must delegate to the materialized
+     * real `Request` (no buffered bytes, or a real `Request` already owns the
+     * body state). Enforces single-read semantics via {@link #directlyConsumed}.
+     */
+    #consumeBytes() {
+        if (this.#real !== undefined || this.#bodyBytes === undefined)
+            return undefined;
+        if (this.#directlyConsumed) {
+            throw new TypeError("Body is unusable: Body has already been read");
+        }
+        this.#directlyConsumed = true;
+        return this.#bodyBytes;
+    }
+    // Spec-constant getters: these are exactly the values undici assigns to a
+    // server-side `new Request(url, { method, headers, body })`, hardcoded so
+    // reading them does not force materialization.
+    get cache() {
+        return "default";
+    }
+    get credentials() {
+        return "same-origin";
+    }
+    get destination() {
+        return "";
+    }
+    get integrity() {
+        return "";
+    }
+    get keepalive() {
+        return false;
+    }
+    get mode() {
+        return "cors";
+    }
+    get redirect() {
+        return "follow";
+    }
+    get referrer() {
+        return "about:client";
+    }
+    get referrerPolicy() {
+        return "";
+    }
+    arrayBuffer() {
+        try {
+            const bytes = this.#consumeBytes();
+            if (bytes === undefined)
+                return this.#materialize().arrayBuffer();
+            // Copy: the underlying buffer is also the framework's raw-body cache.
+            return Promise.resolve(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+        }
+        catch (e) {
+            return Promise.reject(e);
+        }
+    }
+    blob() {
+        return this.#materialize().blob();
+    }
+    bytes() {
+        try {
+            const bytes = this.#consumeBytes();
+            if (bytes === undefined)
+                return this.#materialize().bytes();
+            return Promise.resolve(new Uint8Array(bytes));
+        }
+        catch (e) {
+            return Promise.reject(e);
+        }
+    }
+    formData() {
+        return this.#materialize().formData();
+    }
+    json() {
+        try {
+            const bytes = this.#consumeBytes();
+            if (bytes === undefined)
+                return this.#materialize().json();
+            // JSON.parse (not the framework's safeJsonParse): request.json() is the
+            // raw WHATWG surface, and its error semantics (SyntaxError rejection)
+            // must match a real Request exactly. Framework-parsed bodies go through
+            // readBody()/safeJsonParse and never hit this method.
+            return Promise.resolve(JSON.parse(LIGHT_TEXT_DECODER.decode(bytes)));
+        }
+        catch (e) {
+            return Promise.reject(e);
+        }
+    }
+    text() {
+        try {
+            const bytes = this.#consumeBytes();
+            if (bytes === undefined)
+                return this.#materialize().text();
+            return Promise.resolve(LIGHT_TEXT_DECODER.decode(bytes));
+        }
+        catch (e) {
+            return Promise.reject(e);
+        }
+    }
+    /**
+     * Returns a real, fully-branded `Request` clone — safe to pass to `fetch()`.
+     * Throws a `TypeError` if the body has already been read, per spec.
+     */
+    clone() {
+        if (this.#directlyConsumed) {
+            throw new TypeError("Request body is already used");
+        }
+        return this.#materialize().clone();
+    }
+}
+// `instanceof Request` must hold for handler code and the framework's own
+// checks. Every own getter/method above shadows the brand-checked undici
+// accessors, so the re-rooted chain is only consulted for identity.
+Object.setPrototypeOf(LightRequest.prototype, Request.prototype);
+// This adapter consumes responses via status/headers/DALOY_RAW_BODY only
+// (see sendWebResponse), so serializeResult may skip the undici Response
+// construction for requests dispatched through this shim. Set once on the
+// prototype: zero per-request cost.
+LightRequest.prototype[DALOY_LIGHT_RESPONSE_OK] = true;
 function toWebRequest(req, trustProxy, bufferedBody) {
     const reqHeaders = req.headers;
     const forwardedHost = trustProxy
@@ -323,18 +526,20 @@ function toWebRequest(req, trustProxy, bufferedBody) {
     const headers = new Headers(headerPairs);
     const method = req.method ?? "GET";
     if (method === "GET" || method === "HEAD") {
-        return new Request(url, { method, headers });
+        // LightRequest: skips the ~4µs undici Request constructor on the GET
+        // hot path. Headers are still built eagerly above, so every header
+        // guard sees the same view as before.
+        return new LightRequest(url, method, headers, undefined);
     }
     if (bufferedBody !== undefined) {
-        const req2 = new Request(url, {
-            method,
-            headers,
-            body: bufferedBody,
-        });
-        // Stash the validated bytes so readBodyLimited (and any other internal
-        // body reader) can skip the WHATWG ReadableStream reader loop. The
-        // adapter has already enforced BUFFERED_BODY_MAX_BYTES + Content-Length
-        // here; readBodyLimited re-checks against the caller's limit.
+        // LightRequest with the pre-buffered bytes: skips the (much more
+        // expensive) body-wrapping undici Request constructor. The bytes are
+        // stashed via DALOY_REQUEST_RAW_BODY so readBodyLimited (and any other
+        // internal body reader) skips the WHATWG ReadableStream reader loop.
+        // The adapter has already enforced BUFFERED_BODY_MAX_BYTES +
+        // Content-Length here; readBodyLimited re-checks against the caller's
+        // limit.
+        const req2 = new LightRequest(url, method, headers, bufferedBody);
         req2[DALOY_REQUEST_RAW_BODY] = bufferedBody;
         return req2;
     }

package/dist/app.d.ts

@@ -756,6 +756,17 @@ export declare const DALOY_REQUEST_RAW_BODY: unique symbol;
  * opt in; userland code should not depend on it.
  */
 export declare const DALOY_RAW_STREAM: unique symbol;
+/**
+ * Internal Symbol an adapter sets (once, on its request shim's prototype) to
+ * declare: "the object that ultimately consumes this request's `Response`
+ * only reads `status` / `headers` / {@link DALOY_RAW_BODY} — it never needs a
+ * branded WHATWG `Response`". When present on the incoming request,
+ * {@link serializeResult} may return a {@link LightResponse} and skip the
+ * ~2µs undici `Response` construction per request. Requests without the
+ * marker (Bun / Deno / Workers adapters, tests, direct `app.fetch()` callers)
+ * always get a real `Response`, so the public contract is unchanged.
+ */
+export declare const DALOY_LIGHT_RESPONSE_OK: unique symbol;
 /**
  * Contract-first HTTP application.
  *
@@ -1096,19 +1107,32 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
     /**
      * 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.
+     * runs. Currently checks (production + `secureDefaults` only):
+     *
+     * 1. **Shadow auth** — a route that declares an `auth:` requirement (so it is
+     *    advertised as protected in the OpenAPI `security` list) must have an
+     *    authentication hook ({@link AUTH_HOOK_MARKER}) in its effective chain.
+     *    Otherwise it accepts unauthenticated requests while claiming protection.
+     * 2. **Unauthenticated MCP** — a route from {@link mcpRoutes} must have an
+     *    auth hook unless it opted out with `mcpRoutes(path, handler, { public: true })`.
+     *    MCP tools are model-controlled and side-effecting, so a public one is a
+     *    high-impact default.
+     * 3. **Missing CSRF** — 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. Skipped when `app({ csrf: "off" })`.
+     *
+     * Opt out of all guards with `app({ secureDefaults: false })`. Runs once per
+     * App between registration changes; the result is cached so the fast path is a
+     * single boolean check.
      */
     private assertBootGuards;
     /**
      * 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
+     * and a request arrives carrying a spoofable forwarded / client-IP header
+     * (`X-Forwarded-*`, `X-Real-IP`, or a vendor header like `CF-Connecting-IP`,
+     * `Fly-Client-IP`, `True-Client-IP`), 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.