@daloyjs/core 1.0.0-rc.6 → 1.0.0-rc.8

package/README.md

@@ -598,7 +598,8 @@ DaloyJS is at **`1.0.0-rc.6`**, a security-hardening release candidate carrying
 - 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`.
 
@@ -665,7 +666,7 @@ The framework refuses to start (or to construct) when configuration is unsafe:
 - `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.

package/dist/adapters/node.js

@@ -874,9 +874,16 @@ class NodeWebSocketConnection {
             },
             onClose: (code, reason) => {
                 if (this.readyState === WS_READY_STATE.OPEN) {
-                    // Echo close per RFC 6455 §5.5.1.
+                    // Echo close per RFC 6455 §5.5.1 ("SHOULD use the same status code").
+                    // A peer that closed with an *empty* payload surfaces as the 1005
+                    // sentinel, which §7.4.1 forbids on the wire — echoing it produced a
+                    // CLOSE(1005) that a conforming peer (and this framework's own
+                    // decoder) must reject with 1002. An empty close is answered with an
+                    // empty close.
                     this.readyState = WS_READY_STATE.CLOSING;
-                    this._writeFrame(WS_OPCODE.CLOSE, encodeClosePayload(code, reason));
+                    this._writeFrame(WS_OPCODE.CLOSE, code === WS_CLOSE_CODE.NO_STATUS_RECEIVED
+                        ? new Uint8Array(0)
+                        : encodeClosePayload(code, reason));
                 }
                 this.readyState = WS_READY_STATE.CLOSED;
                 this._fireClose(code, reason);

package/dist/auto-ban.d.ts

@@ -11,7 +11,7 @@
  * The middleware is dependency-free and runtime-portable. It observes outgoing
  * responses via the {@link "./types.js".Hooks.onSend} hook (so it counts the
  * status produced by *any* later middleware or handler, not just its own) and
- * enforces the ban in {@link "./types.js".Hooks.beforeHandle}. The ban state
+ * enforces the ban in {@link "./types.js".Hooks.preBody}. The ban state
  * lives in a pluggable {@link AutoBanStore} — the in-memory default mirrors the
  * `rateLimit()` store and is single-process only; supply a shared (e.g. Redis)
  * implementation for multi-instance deployments.
@@ -19,7 +19,7 @@
  * @module
  * @since 0.37.0
  */
-import type { BaseContext, Hooks } from "./types.js";
+import type { Hooks, IdentityGateContext } from "./types.js";
 /**
  * One client's auto-ban bookkeeping. A record tracks the current strike count
  * inside the rolling strike window, when that window expires, the timestamp the
@@ -128,14 +128,70 @@ export interface AutoBanOptions {
      * Derive the client identity from `ctx`, or `undefined` to skip the request
      * (fail-open — never banned, never counted). Defaults to the proxy-header
      * resolver when {@link trustProxyHeaders} is set.
+     *
+     * Called first in `preBody`, where the gate is immune to mount order (see
+     * {@link IdentityGateContext}). If it returns `undefined` there, it is called
+     * again in `beforeHandle` — by then `session()` and other `beforeHandle` layers
+     * have populated `ctx.state`, so a generator keyed on a resolved session works
+     * rather than silently disabling the ban. Requests enforced by that second
+     * attempt are order-sensitive again, because `beforeHandle` is the phase a
+     * `responseCache()` hit short-circuits; key off headers, params or query where
+     * you can and the `preBody` pass handles it. Returning `undefined` from *both*
+     * still skips the request.
+     *
+     * `ctx.body` is not available in either phase — `preBody` runs before parsing,
+     * and the type reflects that. Derive the key from the request line, headers, or
+     * state instead.
      */
-    keyGenerator?: (ctx: BaseContext<any, any>) => string | undefined;
+    keyGenerator?: (ctx: IdentityGateContext) => string | undefined;
     /**
      * 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;
+    /**
+     * What to do when the default key generator cannot resolve a forwarded
+     * identity — the request carried no `X-Forwarded-For`, or a chain shorter than
+     * {@link trustedHops} declares.
+     *
+     * - `"peer"` (default) — fall back to the immediate TCP peer address, in its
+     *   own `peer:` keyspace. The peer cannot be spoofed, and a request that
+     *   skipped the declared proxy chain came *from* that peer, so strikes are
+     *   attributed to the real origin of the traffic.
+     * - `"skip"` — never count and never ban such a request.
+     *
+     * `"peer"` is the default because `"skip"` is a silent bypass: an attacker who
+     * can reach the origin directly gets unlimited strikes simply by omitting a
+     * header. Choose `"skip"` only when unresolved requests are known-benign and
+     * arrive from a shared address — for instance a load balancer that does not
+     * always set `X-Forwarded-For`, where every such request would otherwise share
+     * the balancer's single `peer:` bucket and a few `401`s could ban the lot.
+     * Prefer fixing the proxy configuration over choosing `"skip"`.
+     *
+     * Ignored when {@link keyGenerator} is supplied — a custom generator owns its
+     * own unresolved-identity posture, and returning `undefined` from it still
+     * means skip.
+     *
+     * @since 1.0.0-rc.8
+     */
+    onUnresolvedIdentity?: "peer" | "skip";
     /** Pluggable ban store. Default: a shared in-memory store keyed by `groupId`. */
     store?: AutoBanStore;
     /**
@@ -185,8 +241,12 @@ export declare class MemoryAutoBanStore implements AutoBanStore {
  * Identity attribution is mandatory: pass {@link AutoBanOptions.keyGenerator} or
  * set {@link AutoBanOptions.trustProxyHeaders}, otherwise construction throws so
  * a misconfiguration can never collapse every caller into one shared bucket and
- * ban the whole world at once. A request the key generator cannot attribute is
- * skipped (never counted, never banned).
+ * ban the whole world at once. When the default generator cannot resolve a
+ * forwarded identity — no `X-Forwarded-For`, or a chain shorter than
+ * {@link AutoBanOptions.trustedHops} declares — strikes are attributed to the
+ * unspoofable TCP peer instead of being discarded; see
+ * {@link AutoBanOptions.onUnresolvedIdentity}. A custom `keyGenerator` that
+ * returns `undefined` still skips the request.
  *
  * @example
  * ```ts

package/dist/auto-ban.js

@@ -11,7 +11,7 @@
  * The middleware is dependency-free and runtime-portable. It observes outgoing
  * responses via the {@link "./types.js".Hooks.onSend} hook (so it counts the
  * status produced by *any* later middleware or handler, not just its own) and
- * enforces the ban in {@link "./types.js".Hooks.beforeHandle}. The ban state
+ * enforces the ban in {@link "./types.js".Hooks.preBody}. The ban state
  * lives in a pluggable {@link AutoBanStore} — the in-memory default mirrors the
  * `rateLimit()` store and is single-process only; supply a shared (e.g. Redis)
  * implementation for multi-instance deployments.
@@ -20,6 +20,7 @@
  * @since 0.37.0
  */
 import { ForbiddenError, TooManyRequestsError } from "./errors.js";
+import { readRemoteAddress, 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,37 @@ 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}.
+ *
+ * When the forwarded chain cannot satisfy the declaration,
+ * {@link resolveForwardedClientIp} returns `undefined` — correct for *identity*,
+ * because such a request never traversed the declared topology. For *abuse
+ * accounting* that answer used to mean "skip", which handed an attacker unlimited
+ * strikes for free: reach the origin directly, past the CDN that appends the
+ * header, and every failed credential attempt went uncounted.
+ *
+ * So the fallback is the immediate TCP peer, prefixed to keep it in its own
+ * keyspace. The peer address cannot be spoofed — it is the socket actually
+ * talking to the adapter — and in exactly the direct-to-origin case that
+ * produced the bypass, the peer *is* the attacker, so accounting becomes precise
+ * rather than absent. Set `onUnresolvedIdentity: "skip"` to restore the previous
+ * behaviour; see {@link AutoBanOptions.onUnresolvedIdentity} for when that is
+ * the right call.
+ */
+function forwardedKey(hops, peerFallback) {
+    return (ctx) => {
+        const forwarded = resolveForwardedClientIp(ctx.request, hops);
+        if (forwarded !== undefined)
+            return forwarded;
+        if (!peerFallback)
+            return undefined;
+        const peer = readRemoteAddress(ctx);
+        return peer === undefined ? undefined : `peer:${peer}`;
+    };
 }
 /**
  * Adaptive, escalating, decaying auto-ban middleware (fail2ban-style). Counts
@@ -100,8 +126,12 @@ function forwardedKey(ctx) {
  * Identity attribution is mandatory: pass {@link AutoBanOptions.keyGenerator} or
  * set {@link AutoBanOptions.trustProxyHeaders}, otherwise construction throws so
  * a misconfiguration can never collapse every caller into one shared bucket and
- * ban the whole world at once. A request the key generator cannot attribute is
- * skipped (never counted, never banned).
+ * ban the whole world at once. When the default generator cannot resolve a
+ * forwarded identity — no `X-Forwarded-For`, or a chain shorter than
+ * {@link AutoBanOptions.trustedHops} declares — strikes are attributed to the
+ * unspoofable TCP peer instead of being discarded; see
+ * {@link AutoBanOptions.onUnresolvedIdentity}. A custom `keyGenerator` that
+ * returns `undefined` still skips the request.
  *
  * @example
  * ```ts
@@ -146,11 +176,22 @@ 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);
+    const onUnresolved = opts.onUnresolvedIdentity ?? "peer";
+    if (onUnresolved !== "peer" && onUnresolved !== "skip") {
+        throw new Error(`autoBan(): onUnresolvedIdentity must be "peer" or "skip"; got ${String(onUnresolved)}.`);
+    }
+    let keyOf;
+    if (opts.keyGenerator) {
+        keyOf = opts.keyGenerator;
+    }
+    else if (hops !== undefined) {
+        keyOf = forwardedKey(hops, onUnresolved === "peer");
+    }
+    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) {
@@ -165,23 +206,40 @@ export function autoBan(opts = {}) {
         store = shared;
     }
     const prefix = `${groupId}:`;
-    return {
-        async beforeHandle(ctx) {
-            const identity = keyOf(ctx);
-            if (identity === undefined)
-                return undefined;
-            const key = `${prefix}${identity}`;
-            const state = ctx.state;
-            state[STATE_KEY] = key;
-            const record = await store.get(key);
-            const now = Date.now();
-            if (record && record.bannedUntilMs > now) {
-                state[STATE_REJECTED] = true;
-                if (banStatus === 403)
-                    throw new ForbiddenError(message);
-                const retry = Math.ceil((record.bannedUntilMs - now) / 1000);
-                throw new TooManyRequestsError(retryAfter ? retry : undefined);
-            }
+    /**
+     * Resolve the identity, stash the key for `onSend`, and reject an active ban.
+     *
+     * Shared by the `preBody` gate and the `beforeHandle` fallback below so both
+     * phases enforce identically. Returns `true` once an identity was found, so
+     * the fallback knows whether `preBody` already handled the request.
+     */
+    const enforce = async (ctx) => {
+        const identity = keyOf(ctx);
+        if (identity === undefined)
+            return false;
+        const key = `${prefix}${identity}`;
+        const state = ctx.state;
+        state[STATE_KEY] = key;
+        const record = await store.get(key);
+        const now = Date.now();
+        if (record && record.bannedUntilMs > now) {
+            state[STATE_REJECTED] = true;
+            if (banStatus === 403)
+                throw new ForbiddenError(message);
+            const retry = Math.ceil((record.bannedUntilMs - now) / 1000);
+            throw new TooManyRequestsError(retryAfter ? retry : undefined);
+        }
+        return true;
+    };
+    const hooks = {
+        // `preBody`, not `beforeHandle`: the ban check must not be preemptable by an
+        // earlier `beforeHandle` middleware that short-circuits — a
+        // `responseCache()` HIT mounted above it would serve a banned client the
+        // cached body, so the ban would only ever apply to uncached routes.
+        // `preBody` always runs before any `beforeHandle`. Strike accounting stays in
+        // `onSend`, which observes the final status either way.
+        async preBody(ctx) {
+            await enforce(ctx);
             return undefined;
         },
         async onSend(res, ctx) {
@@ -217,4 +275,31 @@ export function autoBan(opts = {}) {
             return undefined;
         },
     };
+    // A custom `keyGenerator` may legitimately be unable to answer in `preBody` —
+    // typically because it reads state a `beforeHandle` layer resolves, such as
+    // `session()`. Without a second attempt that request gets no identity, so
+    // `onSend` finds no key and records no strike: the ban silently never arms.
+    // That is a worse failure than the ordering hazard the phase move closed, so
+    // retry in `beforeHandle` when, and only when, `preBody` came up empty.
+    //
+    // The default forwarded resolver never needs this — `onUnresolvedIdentity`
+    // already falls back to the TCP peer — so the hook is registered only for a
+    // custom generator and the common path pays nothing.
+    //
+    // Residual, deliberately accepted: a request enforced by this fallback IS
+    // order-sensitive again, because `beforeHandle` is the phase a
+    // `responseCache()` hit short-circuits. It applies solely to requests whose
+    // identity could not be resolved earlier, and enforcing late beats not
+    // enforcing at all. Resolve identity from headers/params/query where you can
+    // and `preBody` handles it, immune to mount order.
+    if (opts.keyGenerator) {
+        hooks.beforeHandle = async (ctx) => {
+            const state = ctx.state;
+            if (state[STATE_KEY] !== undefined)
+                return undefined; // preBody had it
+            await enforce(ctx);
+            return undefined;
+        };
+    }
+    return hooks;
 }

package/dist/bot-guard.d.ts

@@ -35,7 +35,7 @@
  * @module
  * @since 0.37.0
  */
-import type { BaseContext, Hooks } from "./types.js";
+import type { Hooks, IdentityGateContext } from "./types.js";
 /**
  * Pluggable DNS resolver used to verify declared crawlers. The default
  * implementation lazily imports `node:dns/promises`; provide your own on
@@ -131,12 +131,26 @@ 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}.
      */
-    resolveIp?: (ctx: BaseContext<any, any>) => string | undefined;
+    resolveIp?: (ctx: IdentityGateContext) => string | undefined;
     /**
      * Custom DNS resolver for crawler verification. Defaults to a lazy
      * `node:dns/promises`-backed resolver.

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();
@@ -260,7 +260,12 @@ export function botGuard(opts = {}) {
             throw new ForbiddenError(message);
     };
     return {
-        async beforeHandle(ctx) {
+        // `preBody`, not `beforeHandle`: a bot gate that short-circuits from
+        // `beforeHandle` loses to any earlier `beforeHandle` middleware that returns
+        // a Response first — a `responseCache()` HIT mounted above it would hand a
+        // blocked scraper the cached body. `preBody` always precedes `beforeHandle`,
+        // so the gate holds regardless of mount order.
+        async preBody(ctx) {
             const ua = ctx.request.headers.get("user-agent") ?? "";
             // Allowlist wins over every other rule.
             if (allowed.length > 0 && matchesUserAgent(ua, allowed))

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

package/dist/concurrency-limit.js

@@ -46,6 +46,7 @@
  * @since 0.37.0
  */
 import { HttpError } from "./errors.js";
+import { resolveForwardedClientIp, resolveForwardedTrust } from "./conn-info.js";
 const DEFAULT_MESSAGE = "Concurrency limit exceeded";
 /** Monotonic id so multiple mounted limiters use distinct per-request state slots. */
 let instanceCounter = 0;
@@ -59,12 +60,13 @@ function assertNonNegativeInteger(name, value) {
         throw new Error(`concurrencyLimit(): ${name} must be a non-negative 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 `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 forwardedKey(hops) {
+    return (ctx) => resolveForwardedClientIp(ctx.request, hops);
 }
 /** Extract just the pathname from a request URL without a full `URL` parse where possible. */
 function pathnameOf(url) {
@@ -104,11 +106,18 @@ function buildScopeResolver(opts) {
         return (ctx) => `${ctx.request.method} ${pathnameOf(ctx.request.url)}`;
     }
     // scope === "client"
-    if (!opts.keyGenerator && !opts.trustProxyHeaders) {
-        throw new Error('concurrencyLimit(): scope "client" requires keyGenerator or trustProxyHeaders so ' +
+    const hops = resolveForwardedTrust("concurrencyLimit()", opts);
+    let resolve;
+    if (opts.keyGenerator) {
+        resolve = opts.keyGenerator;
+    }
+    else if (hops !== undefined) {
+        resolve = forwardedKey(hops);
+    }
+    else {
+        throw new Error('concurrencyLimit(): scope "client" requires keyGenerator, trustedHops, or trustProxyHeaders so ' +
             "clients can be identified; otherwise every caller shares one bucket.");
     }
-    const resolve = opts.keyGenerator ?? forwardedKey;
     return (ctx) => {
         const id = resolve(ctx);
         return id === undefined ? undefined : `client:${id}`;

package/dist/conn-info.d.ts

@@ -111,6 +111,71 @@ export declare function assertBehindProxy(cfg: BehindProxyConfig | undefined): v
  * @internal
  */
 export declare function pickForwardedForByHops(header: string | null, hops: number): string | undefined;
+/**
+ * Validate a middleware's forwarded-header trust options and resolve them into
+ * a single hop count. Every middleware that keys on client IP calls this once
+ * at construction, so the trust policy lives in exactly one place instead of
+ * being re-derived at each call site.
+ *
+ * That single-source property is the point: the spoofable-IP vulnerability this
+ * module now guards against existed in nine independent copies of the same
+ * leftmost-`X-Forwarded-For` read, which meant nine separate places to get it
+ * wrong and nine separate fixes. Keeping the decision here means a future
+ * change to the trust rules lands everywhere at once.
+ *
+ * `trustedHops` must be an integer in [1, 64], mirroring the
+ * `behindProxy.hops` range: the floor of one exists because a middleware that
+ * trusts zero proxy hops has no business reading forwarding headers at all.
+ *
+ * @param name - Middleware function name used in error messages.
+ * @param opts - The middleware's options object; only the two trust fields are
+ *   read, so any middleware option type is structurally acceptable.
+ * @returns The number of trusted proxy hops when forwarded-header trust is
+ *   enabled — `trustedHops` verbatim, or `1` for a bare
+ *   `trustProxyHeaders: true` — or `undefined` when trust is off and the caller
+ *   must not read forwarding headers at all.
+ * @throws Error when `trustedHops` is not an integer in [1, 64], or when
+ *   `trustProxyHeaders: false` is combined with a `trustedHops` value. That
+ *   pairing is a contradiction, and it previously resolved silently in favour
+ *   of trust — meaning an explicit opt-out was ignored.
+ * @internal
+ */
+export declare function resolveForwardedTrust(name: string, opts: {
+    trustedHops?: number;
+    trustProxyHeaders?: boolean;
+}): number | undefined;
+/**
+ * Resolve the client IP from the proxy-set forwarding headers, walking a
+ * declared number of trusted hops from the RIGHT side of `X-Forwarded-For`.
+ *
+ * The right side is the spoof-resistant side: each proxy in the chain appends
+ * the address of the peer it actually observed, so the last `hops` entries
+ * were written by infrastructure you control, while anything further left is
+ * attacker-influenceable. Reading the leftmost entry (the historic
+ * `split(",")[0]` pattern) trusts the MOST attacker-controllable slot and
+ * enabled both rate-limit/ban evasion (rotate a spoofed left entry) and
+ * victim-IP framing (spoof a victim's address to get them banned or blocked).
+ *
+ * Falls back to `X-Real-IP` **only for a single declared hop**. That header
+ * carries exactly one hop of information, so it can stand in for a one-proxy
+ * declaration (the common nginx `X-Real-IP`-only setup) but cannot possibly
+ * satisfy a two-or-more-hop one. With 2+ declared hops and a chain shorter
+ * than the declaration, this returns `undefined` rather than guessing.
+ *
+ * Security note: this resolver is only meaningful when every request reaches
+ * the app through a proxy chain you control that appends (or overwrites)
+ * these headers. With no proxy in front, any forwarded-header trust is
+ * attacker-controlled by definition.
+ *
+ * @param request - Incoming request whose forwarding headers are read.
+ * @param hops - Number of trusted proxy hops; `1` (default) reads the
+ *   rightmost entry — the one your immediate proxy appended.
+ * @returns The resolved client IP, or `undefined` when no forwarded identity
+ *   is available. Callers decide their own posture for `undefined`
+ *   (fail-closed 403, fail-open skip, or a shared `"global"` bucket).
+ * @since 1.0.0-rc.7
+ */
+export declare function resolveForwardedClientIp(request: Request, hops?: number): string | undefined;
 /**
  * Resolve the client IP for this request using the configured
  * {@link BehindProxyConfig}. Returns `undefined` when no trusted source is