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

package/README.md

@@ -28,11 +28,21 @@ Disclosure](https://img.shields.io/badge/Security-Responsible%20Disclosure-yello
 
 DaloyJS is maintained in the GitHub organization at <https://github.com/daloyjs>; the canonical framework repository is <https://github.com/daloyjs/daloy>.
 
-## Partners
+## Acknowledgements
 
-<a href="https://snyk.io">
-  <img src="https://github.com/user-attachments/assets/da58db43-67cc-45d4-ade5-bdaa7b041465" alt="Snyk's Secure Developer Program" width="160">
-</a>
+We are grateful to the following companies for supporting DaloyJS with free access to their tools and services.
+
+<div align="center" style="background-color: #f5f5f5; padding: 25px; border-radius: 10px; margin: 20px 0;">
+
+<a href="https://snyk.io"><img src="https://github.com/user-attachments/assets/da58db43-67cc-45d4-ade5-bdaa7b041465" height="75" width="auto" alt="Snyk"></a>
+   
+<a href="https://socket.dev"><img src="https://github.com/user-attachments/assets/7d2dde1f-6b60-4f20-b05b-80ace5ae6862" height="75" width="auto" alt="Socket"></a>
+   
+<a href="https://www.aikido.dev"><img src="https://github.com/user-attachments/assets/67e62dd1-b907-4246-a0aa-95ef13fa491c" height="75" width="auto" alt="Aikido"></a>
+   
+<a href="https://www.coderabbit.ai"><img src="https://github.com/user-attachments/assets/0d9d8e68-eb21-41ec-978c-337b66ee34b6" height="75" width="auto" alt="CodeRabbit"></a>
+
+</div>
 
 ---
 
@@ -66,7 +76,7 @@ DaloyJS exists to be the framework you'd build if you took the best ideas from e
 | **Portable supply-chain hardening** for the apps you build | [pnpm](https://pnpm.io/motivation) defaults + a zero-runtime-dep core | Hardened `.npmrc`, source-verified lockfiles, zero runtime deps, CycloneDX + SPDX SBOM, and npm provenance attestations.                                                                                  |
 
 ```
-framework test suite passing · ≥90% line + function coverage / ≥90% branch coverage · typechecks on TypeScript 7 with `strict: true`
+framework test suite passing · ≥90% line + function coverage / ≥92% branch coverage · typechecks on TypeScript 7 with `strict: true`
 runs on Node, Bun, Deno, Cloudflare, Vercel
 ~12.3M static-route ops/sec · ~1.5M dynamic-route ops/sec on M-class CPU
 ```
@@ -196,7 +206,7 @@ app.get(
   async ({ params }) => ({
     status: 200,
     body: { id: params.id, title: `Book ${params.id}` },
-  }),
+  })
 );
 
 serve(app, { port: 3000 });
@@ -529,7 +539,7 @@ const usersPlugin = {
         operationId: "me",
         responses: { 200: { description: "ok" } },
       },
-      async () => ({ status: 200, body: { user: "alice" } }),
+      async () => ({ status: 200, body: { user: "alice" } })
     );
   },
 };
@@ -574,9 +584,9 @@ The core only ever sees `Request → Response`. Adapters live at the edge.
 
 ## Status
 
-DaloyJS is at **`1.0.0-rc.5`**, a security-hardening release candidate. Because the framework has no external users yet, this RC makes a few intentional changes (see the [CHANGELOG](CHANGELOG.md)) to get the secure-by-default posture right before the stable release rather than deferring them; the generated OpenAPI contract is unchanged. From `1.0.0` stable onward, the API follows SemVer with deprecations getting at least one minor cycle. The framework is already in use for production trials.
+DaloyJS is at **`1.0.0-rc.6`**, a security-hardening release candidate carrying the remediations from a live over-the-wire engagement against a realistic multi-tenant app — cross-principal response-cache disclosure (`SECURITY-AUDIT.md` F-4 … F-9), SQLi signature evasions in `waf()`, and an unbounded WebSocket frame buffer. Because the framework has no external users yet, this RC makes a few intentional changes (see the [CHANGELOG](CHANGELOG.md)) to get the secure-by-default posture right before the stable release rather than deferring them; the generated OpenAPI contract is unchanged. From `1.0.0` stable onward, the API follows 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.
+**Release quality bar.** Every release ships with **≥90% line + function coverage** (`pnpm coverage`) **and ≥92% branch coverage** (`pnpm coverage:branches` on compiled JS), 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.
 
 ### Routing, validation, and docs
 
@@ -588,7 +598,8 @@ DaloyJS is at **`1.0.0-rc.5`**, a security-hardening release candidate. Because
 - Header/JWT/basic/mTLS authentication runs in the `preBody` phase before request-body I/O; body-aware WAF, idempotency, signature, and application middleware keep the validated `beforeHandle` phase.
 - 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. 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 })`.
+- Project docs site serves a curated [`/llms.txt`](https://daloyjs.dev/llms.txt) index (Markdown map + `.md` siblings of every docs page, blog under `Optional`) so coding agents can load documentation without scraping HTML; see [llms.txt docs](https://daloyjs.dev/docs/llms-txt).
+- Dependency-free MCP Streamable HTTP server helpers at `@daloyjs/core/mcp`, speaking the **stateless MCP `2026-07-28`** revision and every earlier one on the same endpoint: `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. Modern requests get `server/discover`, per-request `_meta` validation, `resultType` + `_meta.serverInfo` on every result, `ttlMs` / `cacheScope` caching hints (defaulting to no caching and `private` scope so an authorization-scoped tool list is never shared by a proxy), multi round-trip requests (`input_required` + client retry, replacing server-initiated elicitation/sampling/roots), and `x-mcp-header` parameter mirroring — with a missing or disagreeing `MCP-Protocol-Version` / `Mcp-Method` / `Mcp-Name` / `Mcp-Param-*` header rejected as `-32020` so a gateway can never route on one value while the tool executes another. Legacy clients keep the `initialize` handshake unchanged. 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`.
 
@@ -646,16 +657,16 @@ The framework refuses to start (or to construct) when configuration is unsafe:
 - `requireScopes()` with RFC-6750 `WWW-Authenticate: Bearer` challenge and per-request scope aggregation.
 - `session()` with signed cookies and pluggable stores.
 - `idempotency()` with `Idempotency-Key` fingerprinting + byte-for-byte response replay, in-flight `409`, `422` on key reuse with a different payload, and a pluggable `IdempotencyStore` (in-memory default) at `@daloyjs/core/idempotency`.
-- `responseCache()` server-side body cache (cache-key + TTL with `s-maxage`/`max-age` orchestration, request `no-store`/`no-cache` directives, recursion-safe stale-while-revalidate, `Vary`-aware keying, `X-Cache` HIT/MISS/STALE marker, pluggable `ResponseCacheStore` in-memory default) at `@daloyjs/core/response-cache`. Never caches `Set-Cookie` or `private`/`no-store`/`no-cache` responses. Complements `etag()`/`compression()`, which do not cache bodies.
+- `responseCache()` server-side body cache (cache-key + TTL with `s-maxage`/`max-age` orchestration, request `no-store`/`no-cache` directives, recursion-safe stale-while-revalidate, proactive `varyHeaders` keying, `X-Cache` HIT/MISS/STALE marker, pluggable `ResponseCacheStore` whose in-memory default is bounded on both entry count and retained bytes) at `@daloyjs/core/response-cache`. Never caches `Set-Cookie`, `private`/`no-store`/`no-cache`, or `Vary: *` responses, and strips `Age`/hop-by-hop/`X-Request-Id` from stored entries so a hit never replays another request's correlation id. **Fail-closed on every principal dimension (CWE-524):** the key is the full _effective request URI_ including the authority (RFC 9111 §4), so hostnames never share entries; requests carrying `Authorization` **or** `Cookie` bypass the shared cache unless a `principal` names the caller (then each gets its own entry) or the header is explicitly declared shareable; a tenant resolved by `tenancy()` is folded into the key automatically — with a boot guard that refuses to start if the cache is mounted ahead of `tenancy()`; and the response's **own `Vary` header** is honoured as a secondary key (RFC 9111 §4.1), so the `Vary: Origin` written by `cors()` and the `Vary: Accept-Encoding` written by `compression()` keep one caller's allowed origin — or their gzipped bytes — from being served to the next, with each variant stored separately so they all stay warm. Complements `etag()`/`compression()`, which do not cache bodies.
 - `paginationQuery()` / `encodeCursor()` / `decodeCursor()` / `buildPageLinks()` / `buildLinkHeader()` cursor-pagination helpers at `@daloyjs/core/pagination`: opaque base64url cursors (length-capped, prototype-pollution-safe decode → `400` on tamper), RFC 8288 `Link` header emission with CRLF / header-injection guards, and a Standard Schema that validates `cursor`/`limit` and auto-wires both into the OpenAPI spec + typed client via `toJSONSchema()`.
 - `app.metrics()` + `MetricsRegistry` / `httpMetrics()` Prometheus / OpenMetrics exposition at `@daloyjs/core/metrics`: dependency-free counters / gauges / histograms, RED instrumentation (`http_requests_total`, `http_request_duration_seconds`, `http_requests_in_flight`) plus process gauges, exposition-injection-safe name/label validation, a per-metric cardinality cap, and an opt-in `/metrics` route with the same hardened posture as `app.healthcheck()` (bearer token + `timingSafeEqual`, per-IP rate limit, refuse-to-boot unauthenticated in production). The repo ships an `examples/observability/` Docker Compose stack that starts a pre-configured Prometheus + Grafana pair (with an auto-provisioned RED + heatmap dashboard) against any local app via `docker compose -f examples/observability/docker-compose.yml up`.
 - `otelTracing()` OpenTelemetry-compatible distributed tracing at `@daloyjs/core/tracing`: a dependency-free `Hooks` bundle that opens one `SERVER` span per request, attaches HTTP semantic-convention attributes (`http.request.method`, `url.path`, `server.address` / `server.port`, `http.response.status_code`, …), records exceptions + escalates `5xx` to `ERROR`, guarantees a single `span.end()`, and exposes the live span on `ctx.state.otelSpan`. Bring any tracer matching the small `TracingTracer` interface (the real `@opentelemetry/api` SDK on Node, or a custom exporter on Workers/Deno) plus your own propagator via `contextFromRequest` for `traceparent` continuation — no OTel SDK is forced into your install. The `examples/observability/` stack also runs **Jaeger**, and `examples/otel-tracing-demo.ts` ships a ~120-line dependency-free OTLP/HTTP exporter that streams spans straight to it.
-- `tenancy()` secure-by-default multitenancy at `@daloyjs/core/tenancy`: a dependency-free `Hooks` bundle that resolves the calling tenant once per request and exposes it on `ctx.state.tenant`. Pluggable resolution (`tenantFromSubdomain` PSL-aware, `tenantFromHeader`, `tenantFromPathPrefix`, `tenantFromClaim`, or a custom `(ctx) => string`, tried in array order). **Refuse-unresolved by default** (no ambient "default" tenant leak), **format-validated ids** (rejects key/log-injection + cache-poisoning payloads before they reach a key), **no-enumeration `404`** for unknown tenants, and **host-spoof-safe** subdomain resolution. A `tenantScope()` key helper drops straight into `rateLimit` `keyGenerator` and `concurrencyLimit` / `idempotency` / `responseCache` `scope` to partition each per tenant (CWE-524 cross-tenant cache defense). Runnable `examples/multitenancy-demo.ts`.
+- `tenancy()` secure-by-default multitenancy at `@daloyjs/core/tenancy`: a dependency-free `Hooks` bundle that resolves the calling tenant once per request and exposes it on `ctx.state.tenant`. Pluggable resolution (`tenantFromSubdomain` PSL-aware, `tenantFromHeader`, `tenantFromPathPrefix`, `tenantFromClaim`, or a custom `(ctx) => string`, tried in array order). **Refuse-unresolved by default** (no ambient "default" tenant leak), **format-validated ids** (rejects key/log-injection + cache-poisoning payloads before they reach a key), **no-enumeration `404`** for unknown tenants, and **host-spoof-safe** subdomain resolution. A `tenantScope()` key helper drops straight into `rateLimit` `keyGenerator` and `concurrencyLimit` / `idempotency` `scope` to partition each per tenant (CWE-524 cross-tenant cache defense); `responseCache()` needs no wiring at all — it reads the resolved tenant itself and refuses to boot if mounted ahead of `tenancy()`. Runnable `examples/multitenancy-demo.ts`.
 - `resilientFetch()` + `CircuitBreaker` outbound resilience at `@daloyjs/core/fetch-resilience`: a dependency-free circuit breaker (`closed → open → half-open`), retry-with-backoff (exponential + full jitter, idempotent-method/transient-status scoped, honours `Retry-After`), and a per-call timeout (`AbortController` → `FetchTimeoutError`) designed to layer **on top of** `fetchGuard()` — an `SsrfBlockedError` is a terminal refusal that is never retried and never trips the breaker, so SSRF protection stays intact under the resilience layer.
 - `createWebhookSender()` + `MemoryWebhookDeadLetterSink` outbound webhook delivery at `@daloyjs/core/webhook-delivery`: the outbound counterpart to `verifyWebhookSignature()` — timestamped HMAC-signed `POST`s (`webhook-id` / `webhook-timestamp` / `webhook-signature`, computed over `"<timestamp>.<body>"` and reused across retries for safe deduping), bounded retry-with-backoff (transient-status + network scoped, honours `Retry-After`), per-attempt timeout, and dead-letter semantics. Transport defaults to `fetchGuard()`, so a subscriber URL pointing at cloud metadata or a private range is refused with a terminal `SsrfBlockedError` (never retried, dead-lettered once). Zero runtime dependencies.
 - `app.cron()` + standalone `Scheduler` in-process scheduled tasks at `@daloyjs/core/scheduler`: a queue-agnostic schedule primitive for periodic housekeeping (cache sweeps, token refresh, reconciliation). Fixed intervals or 5-field cron expressions (lists / ranges / steps / named months & days / `@hourly`–`@yearly` aliases / optional IANA `timeZone`), arithmetic cron parsing (no backtracking regex), fixed-rate **single-flight** (overlapping ticks are skipped, never run concurrently), per-run `timeoutMs` with `AbortSignal`, and graceful-shutdown integration (stop arming → await in-flight → abort after grace). Timers are `unref`'d. `parseCron()` / `nextCronRun()` exported standalone. Zero runtime dependencies.
 - `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.
+- `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`, `trustedHops`, or `trustProxyHeaders` so one offender can never ban everyone; unattributable requests are skipped. Proxy-header identity is **spoof-resistant**: the client IP is read from the rightmost `X-Forwarded-For` entry (the one your proxy appended) via `resolveForwardedClientIp()`, so rotating spoofed left entries can neither evade strike accumulation nor frame a victim IP for banning; multi-hop chains declare their hop count with `trustedHops` (shared by `rateLimit()`, `loginThrottle()`, `concurrencyLimit()`, `geoBlock()`, `ipRestriction()`, `ipReputation()`, and `botGuard()`). 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; **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.
@@ -697,7 +708,7 @@ The framework refuses to start (or to construct) when configuration is unsafe:
 - Adapter-independent `ConnInfo` abstraction: `getConnInfo()`, lazy `ctx.remoteAddress`, `ctx.remotePort` — populated by the Node, Bun, Deno, and Lambda adapters from the real peer socket / event source, never from spoofable headers.
 - `daloy doctor` production-posture validator with `--audit-secrets` and `--audit-defaults` (flags wildcard-credentials CORS, > 24h CORS `maxAge`, > 25 MiB blanket body limits, zero `idleTimeoutMs` in production, and unsafe opt-ins).
 - PSL-aware `subdomains()` helper with a `≤ 90 days` snapshot guard.
-- Secure-by-default multitenancy via `tenancy()` + `tenantScope()`: pluggable tenant resolution (subdomain / header / path / JWT claim / custom), refuse-unresolved + format-validated ids + no-enumeration `404` by default, and a key helper that partitions `rateLimit` / `concurrencyLimit` / `idempotency` / `responseCache` per tenant.
+- Secure-by-default multitenancy via `tenancy()` + `tenantScope()`: pluggable tenant resolution (subdomain / header / path / JWT claim / custom), refuse-unresolved + format-validated ids + no-enumeration `404` by default, a key helper that partitions `rateLimit` / `concurrencyLimit` / `idempotency` per tenant, and automatic per-tenant `responseCache` partitioning backed by a boot guard.
 - `defineDependency()` typed-DI helper with per-request deduplication.
 - Scheme-aware `ctx.state.auth` typed contract; named, optionally seeded stateful plugins.
 

package/dist/adapters/bun.js

@@ -273,8 +273,7 @@ function reportBunHandlerFailure(app, data, label, err, notifyError) {
     }
 }
 function validateControlPayload(data) {
-    if (data !== undefined &&
-        encodeSendPayload(data).payload.length > WS_MAX_CONTROL_PAYLOAD) {
+    if (data !== undefined && encodeSendPayload(data).payload.length > WS_MAX_CONTROL_PAYLOAD) {
         throw new WebSocketProtocolError("Control frame payload exceeds 125 bytes");
     }
 }

package/dist/adapters/node.js

@@ -2,7 +2,7 @@
  * Node adapter: translates IncomingMessage/ServerResponse to web-standard
  * Request/Response. Includes graceful shutdown wired to SIGTERM/SIGINT.
  */
-import { createServer, } from "node:http";
+import { createServer } from "node:http";
 import { Readable } from "node:stream";
 import { DALOY_RAW_BODY, DALOY_RAW_STREAM, DALOY_REQUEST_RAW_BODY, DALOY_LIGHT_RESPONSE_OK, DALOY_REQUEST_ABORT, } from "../app.js";
 import { BadRequestError } from "../errors.js";
@@ -74,9 +74,7 @@ export function serve(app, opts = {}) {
     // `0` opts out and restores Node's unbounded-ish default (2000).
     const maxHeaderCount = opts.maxHeaderCount;
     server.maxHeadersCount =
-        typeof maxHeaderCount === "number" && maxHeaderCount >= 0
-            ? maxHeaderCount
-            : 100;
+        typeof maxHeaderCount === "number" && maxHeaderCount >= 0 ? maxHeaderCount : 100;
     // Connection-layer admission control. Reject overflow sockets at accept time
     // rather than queuing them into the event loop under overload.
     if (typeof opts.maxConnections === "number" && opts.maxConnections > 0) {
@@ -125,7 +123,10 @@ export function serve(app, opts = {}) {
         await new Promise((resolve, reject) => server.close((err) => (err ? reject(err) : resolve())));
     };
     if (opts.handleSignals !== false) {
-        const onSignal = (sig) => { app.log.info({ sig }, "DaloyJS received signal, shutting down"); void close().then(() => process.exit(0)); };
+        const onSignal = (sig) => {
+            app.log.info({ sig }, "DaloyJS received signal, shutting down");
+            void close().then(() => process.exit(0));
+        };
         process.once("SIGTERM", () => onSignal("SIGTERM"));
         process.once("SIGINT", () => onSignal("SIGINT"));
     }
@@ -133,9 +134,7 @@ export function serve(app, opts = {}) {
         server,
         get port() {
             const address = server.address();
-            return address !== null && typeof address === "object"
-                ? address.port
-                : requestedPort;
+            return address !== null && typeof address === "object" ? address.port : requestedPort;
         },
         close,
     };
@@ -280,11 +279,7 @@ function attachClientCertificate(req, request) {
  * Node's `connect` event rather than the request listener; it is included here
  * defensively for runtimes/proxies that surface it as a normal request.)
  */
-const FETCH_FORBIDDEN_METHODS = new Set([
-    "CONNECT",
-    "TRACE",
-    "TRACK",
-]);
+const FETCH_FORBIDDEN_METHODS = new Set(["CONNECT", "TRACE", "TRACK"]);
 /**
  * Refuse a Fetch-forbidden HTTP method with a spec-correct `501 Not
  * Implemented`. `501` is more accurate than `405` here because the method is
@@ -544,15 +539,10 @@ Object.setPrototypeOf(LightRequest.prototype, Request.prototype);
 LightRequest.prototype[DALOY_LIGHT_RESPONSE_OK] = true;
 function toWebRequest(req, trustProxy, bufferedBody) {
     const reqHeaders = req.headers;
-    const forwardedHost = trustProxy
-        ? firstHeader(reqHeaders["x-forwarded-host"])
-        : undefined;
+    const forwardedHost = trustProxy ? firstHeader(reqHeaders["x-forwarded-host"]) : undefined;
     const host = forwardedHost ?? reqHeaders.host ?? "localhost";
-    const forwardedProto = trustProxy
-        ? firstHeader(reqHeaders["x-forwarded-proto"])
-        : undefined;
-    const proto = forwardedProto ??
-        (req.socket.encrypted ? "https" : "http");
+    const forwardedProto = trustProxy ? firstHeader(reqHeaders["x-forwarded-proto"]) : undefined;
+    const proto = forwardedProto ?? (req.socket.encrypted ? "https" : "http");
     const url = `${proto}://${host}${normalizeRequestTarget(req.url)}`;
     // Reject malformed Host / request-target combinations at the adapter
     // boundary instead of letting the invalid URL propagate as a 500 later.
@@ -667,7 +657,8 @@ function sendWebResponse(res, out) {
     // which we must strip so Node falls back to chunked transfer-encoding.
     const rawStream = res[DALOY_RAW_STREAM];
     if (rawStream !== undefined) {
-        if (typeof rawStream.pipe === "function" && !(rawStream instanceof ReadableStream)) {
+        if (typeof rawStream.pipe === "function" &&
+            !(rawStream instanceof ReadableStream)) {
             // Node `Readable` from the handler: skip the Web-stream bridge entirely
             // and `.pipe(out)` like Fastify/Koa/Express do.
             out.removeHeader("content-length");
@@ -721,15 +712,10 @@ function pumpBody(body, out) {
 }
 // ---------- WebSocket upgrade ----------
 async function handleUpgrade(app, req, socket, head, trustProxy) {
-    const forwardedHost = trustProxy
-        ? firstHeader(req.headers["x-forwarded-host"])
-        : undefined;
+    const forwardedHost = trustProxy ? firstHeader(req.headers["x-forwarded-host"]) : undefined;
     const host = forwardedHost ?? req.headers.host ?? "localhost";
-    const forwardedProto = trustProxy
-        ? firstHeader(req.headers["x-forwarded-proto"])
-        : undefined;
-    const proto = forwardedProto ??
-        (req.socket.encrypted ? "https" : "http");
+    const forwardedProto = trustProxy ? firstHeader(req.headers["x-forwarded-proto"]) : undefined;
+    const proto = forwardedProto ?? (req.socket.encrypted ? "https" : "http");
     // A malformed `Host` header (e.g. containing a space) reaches this point:
     // Node's HTTP parser accepts it and fires `upgrade`, but WHATWG URL
     // parsing throws. Reject it as the client error it is instead of letting

package/dist/app.d.ts

@@ -1176,7 +1176,11 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      *    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
+     * 3. **Cache ahead of tenancy** — a `responseCache()` that runs before
+     *    `tenancy()` builds its key before the tenant exists in `ctx.state`, so
+     *    every tenant collides on one entry and one tenant's response is served to
+     *    the next caller (CWE-524).
+     * 4. **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" })`.

package/dist/app.js

@@ -127,6 +127,15 @@ const CANONICAL_HTTP_METHODS = new Set([
  * `App` bundle. Must match the string used in `mcpRoutes`.
  */
 const MCP_ROUTE_MARKER = Symbol.for("daloyjs.mcp.route");
+/**
+ * Global-registry symbols stamped by `responseCache()` and `tenancy()` on the
+ * `Hooks` bundles they return. Read here — rather than imported from
+ * `response-cache.ts` / `tenancy.ts` — so neither module is pulled into the core
+ * `App` bundle (which would cost every serverless cold start). Must match the
+ * strings used in those modules.
+ */
+const RESPONSE_CACHE_HOOK_MARKER = Symbol.for("daloyjs.response-cache.hook");
+const TENANCY_HOOK_MARKER = Symbol.for("daloyjs.tenancy.hook");
 /**
  * Apply a topology-aware security preset on top of caller-supplied
  * options. Returns a new options object where preset defaults fill in
@@ -949,7 +958,11 @@ export class App {
      *    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
+     * 3. **Cache ahead of tenancy** — a `responseCache()` that runs before
+     *    `tenancy()` builds its key before the tenant exists in `ctx.state`, so
+     *    every tenant collides on one entry and one tenant's response is served to
+     *    the next caller (CWE-524).
+     * 4. **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" })`.
@@ -998,7 +1011,24 @@ export class App {
             this.bootGuard.error = err;
             throw err;
         }
-        // Guard 3: session() + state-changing route without csrf().
+        // Guard 3: responseCache() mounted ahead of tenancy(). The cache partitions
+        // on the tenant automatically, but only if the tenant is already in
+        // ctx.state when the key is built. Mounted first, it would key every
+        // tenant's response identically and serve one tenant's private body to the
+        // next caller (CWE-524) — silently, with a normal-looking cache HIT.
+        const cacheBeforeTenancy = this.routeSecurityMarkers.find((r) => r.cacheBeforeTenancy);
+        if (cacheBeforeTenancy) {
+            const err = new Error(`Route ${cacheBeforeTenancy.method} ${cacheBeforeTenancy.path} runs responseCache() ` +
+                `before tenancy() in its effective hook chain. The cache key is built before the tenant ` +
+                `is resolved, so every tenant would share one cache entry and one tenant's response ` +
+                `would be served to the next caller (CWE-524 cross-tenant cached-response disclosure). ` +
+                `Register tenancy() first — as a global hook (new App({ hooks: tenancy(...) })) or an ` +
+                `earlier app.use(...) — so the tenant is in ctx.state before the cache reads it. ` +
+                `See https://daloyjs.dev/docs/security/boot-guards.`);
+            this.bootGuard.error = err;
+            throw err;
+        }
+        // Guard 4: session() + state-changing route without csrf().
         if (this.options.csrf === "off")
             return;
         const stateChanging = this.routeSecurityMarkers.find((r) => isStateChangingMethod(r.method) && r.hasSession && !r.hasCsrf);
@@ -1068,13 +1098,21 @@ export class App {
             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. ` +
+        const refusal = new InternalError(`Refusing to dispatch request: ${found} header is present but app({ trustProxy }) is unconfigured. ` +
             `Honouring a spoofable forwarded header would let a client forge its source IP for the rate ` +
             `limiter, audit log, and request-id propagation. ` +
             `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. ` +
             `See https://daloyjs.dev/docs/security/boot-guards.`);
+        // Every refused request throws from this one line, so the stack is
+        // identical each time and names framework internals rather than anything
+        // an operator can act on. Keep the 500 and keep a line per request — the
+        // refusal must stay visible — but drop the stack, so a client cannot
+        // multiply the bytes it pushes into the error tier by replaying the header.
+        // The actionable message is logged once per process by the warn above.
+        refusal[OMIT_STACK_IN_LOG] = true;
+        throw refusal;
     }
     /**
      * Resolve the {@link AppOptions.docs} option and, when enabled, register
@@ -3143,16 +3181,29 @@ function securityMarkersFromHooks(layers) {
     let hasSession = false;
     let hasCsrf = false;
     let hasAuth = false;
-    for (const hooks of layers) {
-        const record = hooks;
+    // `layers` is in execution order, so the first index of each marker is enough
+    // to tell whether the cache reads state before tenancy has written it.
+    let cacheIndex = -1;
+    let tenancyIndex = -1;
+    for (let i = 0; i < layers.length; i++) {
+        const record = layers[i];
         if (record[SESSION_HOOK_MARKER] === true)
             hasSession = true;
         if (record[CSRF_HOOK_MARKER] === true)
             hasCsrf = true;
         if (record[AUTH_HOOK_MARKER] === true)
             hasAuth = true;
+        if (cacheIndex === -1 && record[RESPONSE_CACHE_HOOK_MARKER] === true)
+            cacheIndex = i;
+        if (tenancyIndex === -1 && record[TENANCY_HOOK_MARKER] === true)
+            tenancyIndex = i;
     }
-    return { hasSession, hasCsrf, hasAuth };
+    return {
+        hasSession,
+        hasCsrf,
+        hasAuth,
+        cacheBeforeTenancy: cacheIndex !== -1 && tenancyIndex !== -1 && cacheIndex < tenancyIndex,
+    };
 }
 function isStateChangingMethod(method) {
     return method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE";
@@ -4079,8 +4130,25 @@ function withTimeout(p, ms, request) {
         });
     });
 }
+/**
+ * Marker set on an error whose stack carries no incident information because
+ * the same framework line throws it for every offending request — a rejected
+ * *configuration* or *request shape*, not a fault in the app's code.
+ *
+ * `serializeErr` omits the stack for these. The stack is byte-identical on every
+ * occurrence and points at framework internals, so logging it per request just
+ * multiplies the volume an unauthenticated client can push into the error tier
+ * (the expensive, alerting one) without telling an operator anything the
+ * message does not already say.
+ *
+ * @internal
+ */
+const OMIT_STACK_IN_LOG = Symbol.for("daloyjs.error.omitStackInLog");
 function serializeErr(err) {
     if (err instanceof Error) {
+        if (err[OMIT_STACK_IN_LOG] === true) {
+            return { name: err.name, message: err.message };
+        }
         return { name: err.name, message: err.message, stack: err.stack };
     }
     return { value: String(err) };

package/dist/auto-ban.d.ts

@@ -134,8 +134,24 @@ export interface AutoBanOptions {
      * Read `X-Forwarded-For` / `X-Real-IP` in the default key generator. Off by
      * default because those headers are client-spoofable unless every request
      * reaches the app through a proxy chain you control.
+     *
+     * When enabled, the key is the **rightmost** `X-Forwarded-For` entry — the
+     * one your immediate proxy appended — never the attacker-influenceable
+     * leftmost one. Behind more than one proxy hop, set {@link trustedHops}
+     * instead so the key comes from the slot your outermost trusted proxy wrote.
      */
     trustProxyHeaders?: boolean;
+    /**
+     * Declare exactly how many proxy hops sit between Daloy and the public
+     * internet. Implies proxy-header trust (no need to also set
+     * {@link trustProxyHeaders}) and reads the client IP that many entries from
+     * the right of `X-Forwarded-For` via
+     * {@link "./conn-info.js".resolveForwardedClientIp}, so spoofed entries an
+     * attacker prepends on the left are ignored — they can neither evade strike
+     * accumulation nor frame a victim IP for banning. Must be an integer in
+     * [1, 64]; validated at construction.
+     */
+    trustedHops?: number;
     /** Pluggable ban store. Default: a shared in-memory store keyed by `groupId`. */
     store?: AutoBanStore;
     /**

package/dist/auto-ban.js

@@ -20,6 +20,7 @@
  * @since 0.37.0
  */
 import { ForbiddenError, TooManyRequestsError } from "./errors.js";
+import { resolveForwardedClientIp, resolveForwardedTrust } from "./conn-info.js";
 const DEFAULT_WINDOW_MS = 10 * 60_000;
 const DEFAULT_MAX_STRIKES = 5;
 const DEFAULT_BAN_MS = 15 * 60_000;
@@ -84,12 +85,14 @@ function assertPositiveInteger(name, value) {
         throw new Error(`autoBan(): ${name} must be a positive integer.`);
     }
 }
-function forwardedKey(ctx) {
-    const forwarded = ctx.request.headers.get("x-forwarded-for");
-    const first = forwarded ? forwarded.split(",")[0].trim() : "";
-    if (first)
-        return first;
-    return ctx.request.headers.get("x-real-ip") ?? undefined;
+/**
+ * @internal Default identity resolver: the client IP at the declared number of
+ * trusted proxy hops from the right of `X-Forwarded-For` (falling back to
+ * `X-Real-IP`). Reading the right side keeps the key spoof-resistant — see
+ * {@link resolveForwardedClientIp}.
+ */
+function forwardedKey(hops) {
+    return (ctx) => resolveForwardedClientIp(ctx.request, hops);
 }
 /**
  * Adaptive, escalating, decaying auto-ban middleware (fail2ban-style). Counts
@@ -146,11 +149,18 @@ export function autoBan(opts = {}) {
         }
     }
     const watch = new Set(watchStatuses);
-    if (!opts.keyGenerator && !opts.trustProxyHeaders) {
-        throw new Error("autoBan(): provide keyGenerator or set trustProxyHeaders so clients can be identified; " +
+    const hops = resolveForwardedTrust("autoBan()", opts);
+    let keyOf;
+    if (opts.keyGenerator) {
+        keyOf = opts.keyGenerator;
+    }
+    else if (hops !== undefined) {
+        keyOf = forwardedKey(hops);
+    }
+    else {
+        throw new Error("autoBan(): provide keyGenerator, trustedHops, or set trustProxyHeaders so clients can be identified; " +
             "otherwise every caller shares one bucket and a single offender would ban everyone.");
     }
-    const keyOf = opts.keyGenerator ?? forwardedKey;
     const groupId = opts.groupId ?? DEFAULT_GROUP_ID;
     let store;
     if (opts.store) {
@@ -207,9 +217,7 @@ export function autoBan(opts = {}) {
             opts.onStrike?.({ key, strikes, status: res.status });
             if (strikes >= maxStrikes) {
                 banCount += 1;
-                const duration = escalate
-                    ? Math.min(maxBanMs, banMs * 2 ** (banCount - 1))
-                    : banMs;
+                const duration = escalate ? Math.min(maxBanMs, banMs * 2 ** (banCount - 1)) : banMs;
                 bannedUntilMs = now + duration;
                 strikes = 0;
                 opts.onBan?.({ key, banCount, banDurationMs: duration, bannedUntilMs });

package/dist/bot-guard.d.ts

@@ -131,8 +131,22 @@ export interface BotGuardOptions {
     /**
      * Trust `X-Forwarded-For` / `X-Real-IP` in the default IP resolver. Only
      * enable behind a trusted proxy that overwrites these headers.
+     *
+     * When enabled, the resolver reads the **rightmost** `X-Forwarded-For`
+     * entry — the one your immediate proxy appended — never the
+     * attacker-influenceable leftmost one. Behind more than one proxy hop, set
+     * {@link trustedHops} instead.
      */
     trustProxyHeaders?: boolean;
+    /**
+     * Declare exactly how many proxy hops sit between Daloy and the public
+     * internet. Implies proxy-header trust and reads the client IP that many
+     * entries from the right of `X-Forwarded-For` via
+     * {@link "./conn-info.js".resolveForwardedClientIp}, so attacker-prepended
+     * entries on the left cannot impersonate a verified crawler's IP. Must be
+     * an integer in [1, 64]; validated at construction.
+     */
+    trustedHops?: number;
     /**
      * Custom client-IP resolver. Overrides {@link BotGuardOptions.trustProxyHeaders}.
      */

package/dist/bot-guard.js

@@ -36,6 +36,7 @@
  * @since 0.37.0
  */
 import { ForbiddenError } from "./errors.js";
+import { resolveForwardedClientIp, resolveForwardedTrust } from "./conn-info.js";
 const DEFAULT_MESSAGE = "Bot access denied";
 const DEFAULT_CACHE_TTL_MS = 60 * 60_000;
 const DEFAULT_CACHE_MAX = 10_000;
@@ -88,15 +89,13 @@ function matchesUserAgent(ua, patterns) {
     }
     return false;
 }
-function forwardedIpResolver(ctx) {
-    const headers = ctx.request.headers;
-    const forwarded = headers.get("x-forwarded-for");
-    if (forwarded) {
-        const first = forwarded.split(",")[0]?.trim();
-        if (first)
-            return first;
-    }
-    return ctx.request.headers.get("x-real-ip") ?? undefined;
+/**
+ * @internal Read the client IP `hops` entries from the right of
+ * `X-Forwarded-For` (falling back to `X-Real-IP`) — the spoof-resistant side
+ * of the header; see {@link resolveForwardedClientIp}.
+ */
+function forwardedIpResolver(hops) {
+    return (ctx) => resolveForwardedClientIp(ctx.request, hops);
 }
 function noIpResolver(_ctx) {
     return undefined;
@@ -210,9 +209,10 @@ export function botGuard(opts = {}) {
     if (mode !== "block" && mode !== "log") {
         throw new Error('botGuard(): mode must be "block" or "log".');
     }
-    const resolveIp = opts.resolveIp ?? (opts.trustProxyHeaders ? forwardedIpResolver : noIpResolver);
-    if (verifiedBots.length > 0 && !opts.resolveIp && !opts.trustProxyHeaders) {
-        throw new Error("botGuard(): verifiedBots requires a client-IP source — provide resolveIp " +
+    const hops = resolveForwardedTrust("botGuard()", opts);
+    const resolveIp = opts.resolveIp ?? (hops !== undefined ? forwardedIpResolver(hops) : noIpResolver);
+    if (verifiedBots.length > 0 && !opts.resolveIp && hops === undefined) {
+        throw new Error("botGuard(): verifiedBots requires a client-IP source — provide resolveIp, trustedHops, " +
             "or set trustProxyHeaders, otherwise declared crawlers cannot be verified.");
     }
     const resolver = opts.resolver ?? createDefaultResolver();

package/dist/cli.js

@@ -274,7 +274,11 @@ export function parseArgs(argv) {
     };
     let command = "inspect";
     let i = 0;
-    if (argv[0] === "inspect" || argv[0] === "dev" || argv[0] === "help" || argv[0] === "doctor" || argv[0] === "diff") {
+    if (argv[0] === "inspect" ||
+        argv[0] === "dev" ||
+        argv[0] === "help" ||
+        argv[0] === "doctor" ||
+        argv[0] === "diff") {
         command = argv[0];
         i = 1;
     }
@@ -593,7 +597,8 @@ async function runDoctor(opts, io) {
     const o = app.options;
     const isProd = o.env === "production" ||
         o.production === true ||
-        globalThis.process?.env?.NODE_ENV === "production";
+        globalThis.process?.env?.NODE_ENV ===
+            "production";
     if (opts.noAuditDefaults !== true) {
         if (isProd && o.trustProxy === undefined && o.behindProxy === undefined) {
             findings.push({
@@ -907,10 +912,8 @@ export function buildAiDump(app, opts) {
             method: def.method,
             path: def.path,
             ...(def.operationId ? { operationId: def.operationId } : {}),
-            ...(def.summary ?? meta?.summary
-                ? { summary: def.summary ?? meta?.summary }
-                : {}),
-            ...(def.description ?? meta?.description
+            ...((def.summary ?? meta?.summary) ? { summary: def.summary ?? meta?.summary } : {}),
+            ...((def.description ?? meta?.description)
                 ? { description: def.description ?? meta?.description }
                 : {}),
             tags: dedupeTags(def.tags, meta?.tags),

package/dist/concurrency-limit.d.ts

@@ -97,8 +97,22 @@ export interface ConcurrencyLimitOptions {
      * Read `X-Forwarded-For` / `X-Real-IP` when `scope: "client"`. Off by default
      * because those headers are client-spoofable unless every request reaches the
      * app through a proxy chain you control.
+     *
+     * When enabled, the key is the **rightmost** `X-Forwarded-For` entry — the
+     * one your immediate proxy appended — never the attacker-influenceable
+     * leftmost one. Behind more than one proxy hop, set {@link trustedHops}
+     * instead.
      */
     trustProxyHeaders?: boolean;
+    /**
+     * Declare exactly how many proxy hops sit between Daloy and the public
+     * internet when `scope: "client"`. Implies proxy-header trust and reads the
+     * client IP that many entries from the right of `X-Forwarded-For` via
+     * {@link "./conn-info.js".resolveForwardedClientIp}, so attacker-prepended
+     * entries on the left cannot hop buckets to hoard slots. Must be an integer
+     * in [1, 64]; validated at construction.
+     */
+    trustedHops?: number;
     /**
      * Custom client-identity resolver for `scope: "client"`. Overrides
      * {@link trustProxyHeaders}. Returning `undefined` skips limiting for the