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

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/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) {

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/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

package/dist/conn-info.js

@@ -106,6 +106,100 @@ export function pickForwardedForByHops(header, hops) {
     // typically lives at parts[parts.length - hops].
     return parts[parts.length - hops];
 }
+/**
+ * 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 function resolveForwardedTrust(name, opts) {
+    const hops = opts.trustedHops;
+    const trust = opts.trustProxyHeaders;
+    if (hops !== undefined) {
+        if (!Number.isInteger(hops) || hops < 1 || hops > 64) {
+            throw new Error(`${name}: trustedHops must be an integer in [1, 64]; got ${String(hops)}.`);
+        }
+        if (trust === false) {
+            throw new Error(`${name}: trustProxyHeaders: false contradicts trustedHops: ${hops}. ` +
+                "trustedHops implies proxy-header trust; drop whichever one you did not mean.");
+        }
+        return hops;
+    }
+    return trust === true ? 1 : 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 function resolveForwardedClientIp(request, hops = 1) {
+    const picked = pickForwardedForByHops(request.headers.get("x-forwarded-for"), hops);
+    if (picked)
+        return picked;
+    // Fail closed past one hop. A chain that produced fewer than `hops` entries
+    // means the request never traversed the declared topology — a direct-to-origin
+    // request that skipped the CDN, say — so no forwarded value it carries is
+    // trustworthy, `X-Real-IP` least of all. Trusting it here would hand back the
+    // rotating-identity evasion and victim-IP framing that reading from the right
+    // exists to prevent.
+    //
+    // An attacker inside the chain cannot reach this path: conforming proxies
+    // append, so prepending entries only ever lengthens the header. Reaching it
+    // requires bypassing the declared chain, and the safe answer there is "no
+    // identity", not "the identity the caller asked me to believe".
+    if (hops !== 1)
+        return undefined;
+    return request.headers.get("x-real-ip") ?? undefined;
+}
 /**
  * Resolve the client IP for this request using the configured
  * {@link BehindProxyConfig}. Returns `undefined` when no trusted source is
@@ -125,10 +219,11 @@ export function resolveClientIp(request, cfg) {
         return peer;
     if (cfg === "loopback") {
         if (peer === "127.0.0.1" || peer === "::1" || peer === "::ffff:127.0.0.1") {
-            const xff = request.headers.get("x-forwarded-for");
-            const first = xff?.split(",")[0]?.trim();
-            if (first)
-                return first;
+            // The same-host proxy is the single trusted hop, so read the slot IT
+            // appended (rightmost), never the attacker-influenceable leftmost one.
+            const picked = pickForwardedForByHops(request.headers.get("x-forwarded-for"), 1);
+            if (picked)
+                return picked;
         }
         return peer;
     }

package/dist/geo-block.d.ts

@@ -116,8 +116,23 @@ export interface GeoBlockOptions {
      * to `false` because those headers are client-spoofable unless every
      * request reaches Daloy through a proxy chain you control. Ignored when
      * `resolveCountry` is used or a custom `resolveIp` is supplied.
+     *
+     * 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 spoof an allowed-country IP. Must be an
+     * integer in [1, 64]; validated at construction. Ignored when
+     * `resolveCountry` is used or a custom `resolveIp` is supplied.
+     */
+    trustedHops?: number;
     /**
      * What to do when the country cannot be resolved. Defaults to `false` when
      * an `allow` list is configured (fail closed — an unknown country is not on

package/dist/geo-block.js

@@ -25,6 +25,7 @@
  * @since 0.37.0
  */
 import { ForbiddenError } from "./errors.js";
+import { resolveForwardedClientIp, resolveForwardedTrust } from "./conn-info.js";
 /** @internal Validate + normalise a configured country code, or throw. */
 function normalizeConfiguredCode(input) {
     const code = input.trim().toUpperCase();
@@ -38,16 +39,14 @@ function normalizeConfiguredCode(input) {
 function noIpResolver(_ctx) {
     return undefined;
 }
-/** @internal Read the leading `X-Forwarded-For` / `X-Real-IP` hop. */
-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 right side is written
+ * by the operator's own proxy chain and is therefore the spoof-resistant
+ * side — see {@link resolveForwardedClientIp}.
+ */
+function forwardedIpResolver(hops) {
+    return (ctx) => resolveForwardedClientIp(ctx.request, hops);
 }
 /**
  * Block or allow requests by client country. Daloy ships no GeoIP database;
@@ -105,7 +104,8 @@ export function geoBlock(opts) {
     const onBlock = opts.onBlock;
     const lookupCountry = opts.lookupCountry;
     const resolveCountry = opts.resolveCountry;
-    const resolveIp = opts.resolveIp ?? (opts.trustProxyHeaders ? forwardedIpResolver : noIpResolver);
+    const hops = resolveForwardedTrust("geoBlock()", opts);
+    const resolveIp = opts.resolveIp ?? (hops !== undefined ? forwardedIpResolver(hops) : noIpResolver);
     return {
         async beforeHandle(ctx) {
             let ip;

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { _resetCrashHandlersForTests } from "./app.js";
 export { _resetInsecureDefaultsLogForTests } from "./app.js";
 export { _resetIndeterminateEnvWarningForTests } from "./app.js";
 export type { AppOptions, AppOpenAPIOptions, DocsRouteOptions, AsyncAPIRouteOptions, HealthRouteOptions, CspReportRouteOptions, MetricsRouteOptions, IntrospectedRoute, PluginInstalledEvent, PluginExtension, ShutdownEvent, SecurityPreset, } from "./app.js";
-export { getConnInfo, setConnInfo, assertBehindProxy, resolveClientIp, readRemoteAddress, readRemotePort, pickForwardedForByHops, } from "./conn-info.js";
+export { getConnInfo, setConnInfo, assertBehindProxy, resolveClientIp, readRemoteAddress, readRemotePort, pickForwardedForByHops, resolveForwardedClientIp, } from "./conn-info.js";
 export type { BehindProxyConfig, ConnInfo } from "./conn-info.js";
 export { subdomains, PSL_SNAPSHOT_DATE, PSL_PUBLIC_SUFFIXES, MAX_SNAPSHOT_AGE_DAYS, } from "./subdomains.js";
 export type { SubdomainsOptions, SubdomainsResult } from "./subdomains.js";
@@ -19,8 +19,8 @@ export type { StandardSchemaV1 } from "./schema.js";
 export { validate, isStandardSchema } from "./schema.js";
 export { diffOpenAPI, hasBreakingChanges } from "./openapi-diff.js";
 export type { ChangeSeverity, OpenAPIChange, OpenAPIDiffResult } from "./openapi-diff.js";
-export { MCP_DEFAULT_MAX_BODY_BYTES, MCP_PROTOCOL_VERSION, MCP_PROTOCOL_VERSIONS, McpToolError, createMcpHandler, mcpRoutes, validateMcpInput, } from "./mcp.js";
-export type { McpContent, McpEmbeddedResourceContent, McpHandler, McpHandlerOptions, McpIcon, McpImageContent, McpJsonObject, McpJsonRpcId, McpJsonSchema, McpJsonValue, McpPrompt, McpPromptArgument, McpPromptDefinition, McpPromptMessage, McpPromptResult, McpRequestContext, McpResource, McpResourceContents, McpResourceDefinition, McpResourceTemplate, McpResourceTemplateDefinition, McpRoutesOptions, McpServerInfo, McpTextContent, McpTool, McpToolAnnotations, McpToolHandler, McpToolResult, } from "./mcp.js";
+export { MCP_DEFAULT_MAX_BODY_BYTES, MCP_ERROR_CODES, MCP_MAX_REQUEST_STATE_LENGTH, MCP_META_KEYS, MCP_MODERN_ERA_MIN_VERSION, MCP_PROTOCOL_VERSION, MCP_PROTOCOL_VERSIONS, McpToolError, createMcpHandler, isModernProtocolVersion, mcpRoutes, validateMcpInput, } from "./mcp.js";
+export type { McpCacheHints, McpContent, McpEmbeddedResourceContent, McpHandler, McpHandlerOptions, McpIcon, McpImageContent, McpImplementation, McpInputRequest, McpInputRequests, McpInputRequiredResult, McpInputResponses, McpJsonObject, McpJsonRpcId, McpJsonSchema, McpJsonValue, McpPrompt, McpPromptArgument, McpPromptDefinition, McpPromptMessage, McpPromptResult, McpProtocolEra, McpRequestContext, McpResource, McpResourceContents, McpResourceDefinition, McpResourceTemplate, McpResourceTemplateDefinition, McpRoutesOptions, McpServerInfo, McpTextContent, McpTool, McpToolAnnotations, McpToolHandler, McpToolResult, } from "./mcp.js";
 export { readBodyLimited, safeJsonParse, safeJsonParseLimited, isForbiddenObjectKey, sanitizeHeaderName, sanitizeHeaderValue, timingSafeEqual, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, assertHeaderCountWithinLimit, DEFAULT_MAX_HEADER_COUNT, RESERVED_INBOUND_HEADER_PREFIXES, SMUGGLING_SINGLETON_HEADERS, verifyWebhookSignature, signWebhookPayload, WEBHOOK_DEFAULT_TOLERANCE_SECONDS, assertStrongSecret, MIN_PROD_SECRET_BYTES, WEAK_SECRET_STRINGS, sanitizeFilename, assertSafeRelativePath, hasMongoOperatorKeys, assertNoMongoOperators, } from "./security.js";
 export type { WebhookHmacAlgorithm } from "./security.js";
 export { requestId, secureHeaders, SECURE_HEADERS_MARKER, cors, CORS_HOOK_MARKER, CORS_ORIGIN_ALLOW_MARKER, CORS_WILDCARD_ORIGIN_MARKER, rateLimit, loginThrottle, timing, bearerAuth, basicAuth, markAuthHook, AUTH_HOOK_MARKER, csrf, CSRF_HOOK_MARKER, fetchMetadata, requireScopes, REQUIRE_SCOPES_AGGREGATE_KEY, REQUIRE_SCOPES_HOOK_MARKER, _resetSharedRateLimitStoresForTests, } from "./middleware.js";

package/dist/index.js

@@ -5,13 +5,13 @@ export { findRoutesMissingResponseBodySchema } from "./app.js";
 export { _resetCrashHandlersForTests } from "./app.js";
 export { _resetInsecureDefaultsLogForTests } from "./app.js";
 export { _resetIndeterminateEnvWarningForTests } from "./app.js";
-export { getConnInfo, setConnInfo, assertBehindProxy, resolveClientIp, readRemoteAddress, readRemotePort, pickForwardedForByHops, } from "./conn-info.js";
+export { getConnInfo, setConnInfo, assertBehindProxy, resolveClientIp, readRemoteAddress, readRemotePort, pickForwardedForByHops, resolveForwardedClientIp, } from "./conn-info.js";
 export { subdomains, PSL_SNAPSHOT_DATE, PSL_PUBLIC_SUFFIXES, MAX_SNAPSHOT_AGE_DAYS, } from "./subdomains.js";
 export { defineDependency, DEPENDENCY_MARKER } from "./dependency.js";
 export { HttpError, BadRequestError, ValidationError, NotFoundError, ConflictError, UnauthorizedError, ForbiddenError, MethodNotAllowedError, PayloadTooLargeError, RequestHeaderFieldsTooLargeError, UnsupportedMediaTypeError, TooManyRequestsError, RequestTimeoutError, InternalError, MessageLeakError, httpError, SAFE_CUSTOM_ERROR_RESPONSE_HEADERS, checkCustomErrorResponseHeaders, } from "./errors.js";
 export { validate, isStandardSchema } from "./schema.js";
 export { diffOpenAPI, hasBreakingChanges } from "./openapi-diff.js";
-export { MCP_DEFAULT_MAX_BODY_BYTES, MCP_PROTOCOL_VERSION, MCP_PROTOCOL_VERSIONS, McpToolError, createMcpHandler, mcpRoutes, validateMcpInput, } from "./mcp.js";
+export { MCP_DEFAULT_MAX_BODY_BYTES, MCP_ERROR_CODES, MCP_MAX_REQUEST_STATE_LENGTH, MCP_META_KEYS, MCP_MODERN_ERA_MIN_VERSION, MCP_PROTOCOL_VERSION, MCP_PROTOCOL_VERSIONS, McpToolError, createMcpHandler, isModernProtocolVersion, mcpRoutes, validateMcpInput, } from "./mcp.js";
 export { readBodyLimited, safeJsonParse, safeJsonParseLimited, isForbiddenObjectKey, sanitizeHeaderName, sanitizeHeaderValue, timingSafeEqual, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, assertHeaderCountWithinLimit, DEFAULT_MAX_HEADER_COUNT, RESERVED_INBOUND_HEADER_PREFIXES, SMUGGLING_SINGLETON_HEADERS, verifyWebhookSignature, signWebhookPayload, WEBHOOK_DEFAULT_TOLERANCE_SECONDS, assertStrongSecret, MIN_PROD_SECRET_BYTES, WEAK_SECRET_STRINGS, sanitizeFilename, assertSafeRelativePath, hasMongoOperatorKeys, assertNoMongoOperators, } from "./security.js";
 export { requestId, secureHeaders, SECURE_HEADERS_MARKER, cors, CORS_HOOK_MARKER, CORS_ORIGIN_ALLOW_MARKER, CORS_WILDCARD_ORIGIN_MARKER, rateLimit, loginThrottle, timing, bearerAuth, basicAuth, markAuthHook, AUTH_HOOK_MARKER, csrf, CSRF_HOOK_MARKER, fetchMetadata, requireScopes, REQUIRE_SCOPES_AGGREGATE_KEY, REQUIRE_SCOPES_HOOK_MARKER, _resetSharedRateLimitStoresForTests, } from "./middleware.js";
 export { etag } from "./etag.js";

package/dist/ip-reputation.d.ts

@@ -109,8 +109,22 @@ export interface IpReputationOptions {
     /**
      * 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 dodge the denylist. Must be an integer in
+     * [1, 64]; validated at construction.
+     */
+    trustedHops?: number;
     /**
      * `"block"` (default) throws a {@link ForbiddenError} on a match; `"log"`
      * only invokes {@link IpReputationOptions.onMatch} and lets the request

package/dist/ip-reputation.js

@@ -46,6 +46,7 @@
  */
 import { ForbiddenError } from "./errors.js";
 import { fetchGuard } from "./fetch-guard.js";
+import { resolveForwardedClientIp, resolveForwardedTrust } from "./conn-info.js";
 import { compileCidrMatcher, matchesMatcher, parseIp } from "./ip-restriction.js";
 const DEFAULT_REFRESH_MS = 60 * 60_000;
 const DEFAULT_FETCH_TIMEOUT_MS = 30_000;
@@ -113,15 +114,13 @@ export function urlFeed(url, opts = {}) {
         },
     };
 }
-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;
@@ -158,7 +157,8 @@ export function ipReputation(opts) {
         throw new Error("ipReputation(): fetchTimeoutMs must be a positive integer.");
     }
     const message = opts.message ?? DEFAULT_MESSAGE;
-    const resolveIp = opts.resolveIp ?? (opts.trustProxyHeaders ? forwardedIpResolver : noIpResolver);
+    const hops = resolveForwardedTrust("ipReputation()", opts);
+    const resolveIp = opts.resolveIp ?? (hops !== undefined ? forwardedIpResolver(hops) : noIpResolver);
     // Last-known-good compiled denylist, one entry per feed so a single feed's
     // failed refresh doesn't drop the others.
     let compiled = opts.feeds.map((f) => ({ name: f.name, v4: [], v6: [] }));