@daloyjs/core 1.0.0 → 1.1.0

package/README.md

@@ -584,7 +584,7 @@ The core only ever sees `Request → Response`. Adapters live at the edge.
 
 ## Status
 
-DaloyJS is at **`1.0.0`** — the public API is frozen and follows SemVer from here: no `1.x` minor changes the API, and any deprecation gets at least one minor cycle before removal. `@daloyjs/core` (npm), `create-daloy` (npm), and [`@daloyjs/daloy`](https://jsr.io/@daloyjs/daloy) (JSR) ship together at matching versions.
+DaloyJS is at **`1.1.0`** — the public API is frozen and follows SemVer from here: no `1.x` minor changes the API, and any deprecation gets at least one minor cycle before removal. `@daloyjs/core` (npm), `create-daloy` (npm), and [`@daloyjs/daloy`](https://jsr.io/@daloyjs/daloy) (JSR) ship together at matching versions.
 
 The release-candidate train that led here was largely adversarial: `rc.1` through `rc.9` carried remediations from live over-the-wire engagements against realistic multi-tenant apps, and the findings clustered in one place worth naming — **composition**, not individual modules. A `responseCache()` mounted ahead of the network-identity gates silently disabled them; the same order left `rateLimit()` never counting the requests a cache hit or an idempotent replay served; a forwarded-header resolver read the one `X-Forwarded-For` slot an attacker controls; `idempotency()` replayed a stored `Set-Cookie`. Each is fixed, each has a regression test, and several are now refuse-to-boot guards so the unsafe wiring cannot ship quietly. See the [CHANGELOG](CHANGELOG.md) for the full train and [boot guards](https://daloyjs.dev/docs/security/boot-guards) for the orders the framework now refuses.
 
@@ -637,7 +637,8 @@ The framework refuses to start (or to construct) when configuration is unsafe:
 - **Unauthenticated MCP**: an `mcpRoutes()` endpoint with no auth hook — MCP tools are model-controlled and side-effecting. Opt out for a genuinely public server with `mcpRoutes(path, handler, { public: true })`.
 - `secureDefaults: false` in production unless `acknowledgeInsecureDefaults: true` is set, plus a once-per-process `error` log naming every disabled default.
 - `preset: "internal-service"` topology preset for service-to-service deployments behind a mesh / sidecar / private network: turns OFF the browser-only guards (auto `secureHeaders`, `corsCrossOriginGuard`, `csrf` boot guard, unconfigured `X-Forwarded-*` guard) while keeping every input, parser, credential, SSRF, weak-secret, and refuse-to-boot guard ON. Per-knob options still win, the choice is logged at boot under `event: "security.preset.applied"`, and the live posture is auditable via `app.getSecurityPosture()`.
-- `createJwtSigner()` / `createJwtVerifier()` refuse `alg: "none"`, accept only an explicit allowlist, refuse HS + JWK combinations, refuse to sign without `exp`, and refuse HS-shaped secrets under 32 bytes (RFC 7518 §3.2).
+- `createJwtSigner()` / `createJwtVerifier()` refuse `alg: "none"`, accept only an explicit allowlist, refuse HS + JWK combinations, refuse to sign without `exp`, refuse HS-shaped secrets under 32 bytes (RFC 7518 §3.2), and refuse JWS `crit` headers at both sign and verify time (RFC 7515 §4.1.11 — no extensions are implemented, so none may be silently ignored). The verifier also accepts an opt-in `maxLifetimeSeconds` cap that rejects any token whose `exp - (iat ?? now)` exceeds it (`lifetime_exceeded`), closing the signer/verifier lifetime asymmetry.
+- Node adapter header-count hardening: because Node's llhttp parser *silently truncates* headers past `server.maxHeadersCount` instead of rejecting, the adapter answers `431` for any HTTP request *or WebSocket upgrade* whose raw header-field count reaches the cap — a truncated flood is indistinguishable from a handshake sitting exactly at it, so it is refused rather than completed with dropped fields (usable default budget: 99 fields).
 - `secureHeaders()` refuses to construct with `frameOptions: false` AND no CSP `frame-ancestors` directive (no clickjacking defense).
 - `cors()` refuses `methods: ['*']` at construction; default `allowMethods` narrowed to `[GET, HEAD, POST]` so `PUT` / `PATCH` / `DELETE` become explicit opt-ins.
 - `cspReportRoute()` refuses non-`application/json` (415) and refuses `maxBodyBytes > 64 KiB` at construction. The default production logger sink omits the parsed report body unless `logCspReportBodies: true` is set explicitly.
@@ -670,7 +671,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`, `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.
+- `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()`). For deployments where the origin itself is reachable, `trustedProxies` (a CIDR allowlist of your proxy peer addresses, accepted by every guard in that list) goes further: the immediate TCP peer is verified against the allowlist before any forwarded header is believed, so a direct-to-origin caller's spoofed `X-Forwarded-For` is ignored entirely — closing victim-IP framing and ban/limit evasion at the framework layer, and failing closed on peer-less edge platforms. 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.d.ts

@@ -37,7 +37,12 @@ export interface NodeServerOptions {
      * amplification (the dimension abused by the "HTTP/2 Bomb"). Node's own
      * default is `2000`; this adapter tightens it to `100` to mirror the
      * application-tier cap. Set `0` to disable (use Node's unbounded default).
-     * Default: 100.
+     *
+     * Note: Node's parser (llhttp) *silently truncates* headers past this cap
+     * rather than rejecting the request, so the adapter additionally refuses
+     * any request *or WebSocket upgrade* whose raw field count reaches the cap
+     * with `431` — at the cap, a truncated flood is indistinguishable from a
+     * legitimate handshake. Default: 100.
      *
      * @since 0.38.0
      */

package/dist/adapters/node.js

@@ -35,6 +35,15 @@ export function serve(app, opts = {}) {
         ? Math.max(1_000, Math.min(5_000, Math.floor(connectionTimeoutMs / 2)))
         : undefined;
     const handleRequest = (req, res, onBodyPull) => {
+        // Node's HTTP parser *silently truncates* headers past
+        // `server.maxHeadersCount` instead of rejecting the request (llhttp
+        // semantics — verified live against Node 24). See
+        // {@link isAtOrOverParserHeaderCap}. Cost: two property reads + compare.
+        const headerCap = server.maxHeadersCount ?? 0;
+        if (isAtOrOverParserHeaderCap(req, headerCap)) {
+            writeHeadersTooLarge(res, headerCap);
+            return;
+        }
         // GET/HEAD: no body work, dispatch directly. Keep this first so the GET
         // hot path doesn't pay for any of the buffering bookkeeping below.
         const method = req.method;
@@ -132,6 +141,20 @@ export function serve(app, opts = {}) {
         server.on("upgrade", (req, socket, head) => {
             wsSockets.add(socket);
             socket.on("close", () => wsSockets.delete(socket));
+            // Same llhttp truncation blind spot as handleRequest: upgrades never
+            // pass through the request listener or App.dispatch, so the portable
+            // maxHeaderCount guard never runs. Refuse at the parser cap before
+            // any Headers construction / 101 handshake.
+            const headerCap = server.maxHeadersCount ?? 0;
+            if (isAtOrOverParserHeaderCap(req, headerCap)) {
+                try {
+                    writeUpgradeError(socket, 431, "Request Header Fields Too Large");
+                }
+                catch {
+                    /* socket already closed */
+                }
+                return;
+            }
             // Safety net: a rejection here would otherwise be unhandled and, under
             // the production crash-on-unhandledRejection posture, kill the process
             // from a single malformed upgrade request.
@@ -327,6 +350,37 @@ function attachClientCertificate(req, request) {
  * defensively for runtimes/proxies that surface it as a normal request.)
  */
 const FETCH_FORBIDDEN_METHODS = new Set(["CONNECT", "TRACE", "TRACK"]);
+/**
+ * True when Node's parser has retained at least `headerCap` raw header fields.
+ * At the cap a truncated flood is indistinguishable from a legitimate request
+ * sitting exactly on the limit (llhttp drops excess fields instead of 431).
+ * A non-positive `headerCap` disables the check (`maxHeaderCount: 0`).
+ */
+function isAtOrOverParserHeaderCap(req, headerCap) {
+    return headerCap > 0 && req.rawHeaders.length / 2 >= headerCap;
+}
+/**
+ * Refuse a request whose raw header-field count reached the parser cap —
+ * indistinguishable from a flood that llhttp silently truncated. Mirrors
+ * {@link writeMethodRefused}'s RFC 9457 problem+json shape; `Connection: close`
+ * avoids reusing a socket whose remaining header fields were discarded.
+ *
+ * @param res - The Node {@link ServerResponse} to write the refusal to.
+ * @param cap - The effective parser header-count cap, echoed in the `detail`.
+ */
+function writeHeadersTooLarge(res, cap) {
+    if (res.headersSent)
+        return;
+    res.statusCode = 431;
+    res.setHeader("content-type", "application/problem+json");
+    res.setHeader("connection", "close");
+    res.end(JSON.stringify({
+        type: "https://daloyjs.dev/errors/request-header-fields-too-large",
+        title: "Request Header Fields Too Large",
+        status: 431,
+        detail: `Request reached the parser header-count cap (${cap}); excess fields would have been silently dropped.`,
+    }));
+}
 /**
  * Refuse a Fetch-forbidden HTTP method with a spec-correct `501 Not
  * Implemented`. `501` is more accurate than `405` here because the method is

package/dist/auto-ban.d.ts

@@ -92,9 +92,10 @@ export interface AutoBanStrikeEvent {
 }
 /**
  * Configuration for {@link autoBan}. Every field is optional except that the
- * middleware must be able to identify clients: supply a {@link keyGenerator} or
- * set {@link trustProxyHeaders} (otherwise construction throws, to avoid
- * accidentally banning every client through a shared `"global"` bucket).
+ * middleware must be able to identify clients: supply a {@link keyGenerator},
+ * {@link trustedHops}, {@link trustedProxies}, or set {@link trustProxyHeaders}
+ * (otherwise construction throws, to avoid accidentally banning every client
+ * through a shared `"global"` bucket).
  *
  * @since 0.37.0
  */
@@ -166,6 +167,19 @@ export interface AutoBanOptions {
      * [1, 64]; validated at construction.
      */
     trustedHops?: number;
+    /**
+     * Declare WHICH proxies are yours: an IP/CIDR allowlist (e.g.
+     * `["10.0.0.0/8", "203.0.113.10"]`) for the immediate peer's address.
+     * Forwarded headers are honoured only when the TCP socket actually talking
+     * to the adapter matches the list — the one property a remote client
+     * cannot spoof. A direct-to-origin attacker then falls back to the
+     * unspoofable peer identity, so a spoofed `X-Forwarded-For` can neither
+     * frame a victim IP for banning nor rotate away strike accumulation.
+     * Implies proxy-header trust at one hop unless {@link trustedHops} says
+     * otherwise; validated and compiled at construction. On peer-less edge
+     * platforms verification fails closed (forwarded identity ignored).
+     */
+    trustedProxies?: readonly string[];
     /**
      * 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
@@ -238,7 +252,8 @@ export declare class MemoryAutoBanStore implements AutoBanStore {
  * offenders; bans grow exponentially for persistent abuse and decay once the
  * client goes quiet.
  *
- * Identity attribution is mandatory: pass {@link AutoBanOptions.keyGenerator} or
+ * Identity attribution is mandatory: pass {@link AutoBanOptions.keyGenerator},
+ * {@link AutoBanOptions.trustedHops}, {@link AutoBanOptions.trustedProxies}, 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. When the default generator cannot resolve a
@@ -258,8 +273,8 @@ export declare class MemoryAutoBanStore implements AutoBanStore {
  *
  * @param opts - Auto-ban configuration.
  * @returns A {@link Hooks} bundle ready for `app.use(...)`.
- * @throws Error when neither `keyGenerator` nor `trustProxyHeaders` is provided,
- *   or when a numeric option is out of range.
+ * @throws Error when none of `keyGenerator`, `trustedHops`, `trustedProxies`, or
+ *   `trustProxyHeaders` is provided, or when a numeric option is out of range.
  * @since 0.37.0
  */
 export declare function autoBan(opts?: AutoBanOptions): Hooks;

package/dist/auto-ban.js

@@ -20,7 +20,7 @@
  * @since 0.37.0
  */
 import { ForbiddenError, TooManyRequestsError } from "./errors.js";
-import { readRemoteAddress, resolveForwardedClientIp, resolveForwardedTrust } from "./conn-info.js";
+import { readRemoteAddress, resolveForwardedClientIp, resolveForwardedTrust, resolveTrustedProxyMatchers, } from "./conn-info.js";
 const DEFAULT_WINDOW_MS = 10 * 60_000;
 const DEFAULT_MAX_STRIKES = 5;
 const DEFAULT_BAN_MS = 15 * 60_000;
@@ -106,9 +106,9 @@ function assertPositiveInteger(name, value) {
  * behaviour; see {@link AutoBanOptions.onUnresolvedIdentity} for when that is
  * the right call.
  */
-function forwardedKey(hops, peerFallback) {
+function forwardedKey(hops, peerFallback, trustedPeers) {
     return (ctx) => {
-        const forwarded = resolveForwardedClientIp(ctx.request, hops);
+        const forwarded = resolveForwardedClientIp(ctx.request, hops, trustedPeers);
         if (forwarded !== undefined)
             return forwarded;
         if (!peerFallback)
@@ -123,7 +123,8 @@ function forwardedKey(hops, peerFallback) {
  * offenders; bans grow exponentially for persistent abuse and decay once the
  * client goes quiet.
  *
- * Identity attribution is mandatory: pass {@link AutoBanOptions.keyGenerator} or
+ * Identity attribution is mandatory: pass {@link AutoBanOptions.keyGenerator},
+ * {@link AutoBanOptions.trustedHops}, {@link AutoBanOptions.trustedProxies}, 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. When the default generator cannot resolve a
@@ -143,8 +144,8 @@ function forwardedKey(hops, peerFallback) {
  *
  * @param opts - Auto-ban configuration.
  * @returns A {@link Hooks} bundle ready for `app.use(...)`.
- * @throws Error when neither `keyGenerator` nor `trustProxyHeaders` is provided,
- *   or when a numeric option is out of range.
+ * @throws Error when none of `keyGenerator`, `trustedHops`, `trustedProxies`, or
+ *   `trustProxyHeaders` is provided, or when a numeric option is out of range.
  * @since 0.37.0
  */
 export function autoBan(opts = {}) {
@@ -177,6 +178,7 @@ export function autoBan(opts = {}) {
     }
     const watch = new Set(watchStatuses);
     const hops = resolveForwardedTrust("autoBan()", opts);
+    const proxyMatchers = resolveTrustedProxyMatchers("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)}.`);
@@ -186,10 +188,10 @@ export function autoBan(opts = {}) {
         keyOf = opts.keyGenerator;
     }
     else if (hops !== undefined) {
-        keyOf = forwardedKey(hops, onUnresolved === "peer");
+        keyOf = forwardedKey(hops, onUnresolved === "peer", proxyMatchers);
     }
     else {
-        throw new Error("autoBan(): provide keyGenerator, trustedHops, or set trustProxyHeaders so clients can be identified; " +
+        throw new Error("autoBan(): provide keyGenerator, trustedHops, trustedProxies, or set trustProxyHeaders so clients can be identified; " +
             "otherwise every caller shares one bucket and a single offender would ban everyone.");
     }
     const groupId = opts.groupId ?? DEFAULT_GROUP_ID;

package/dist/bot-guard.d.ts

@@ -117,8 +117,8 @@ export interface BotGuardOptions {
     allowUserAgents?: readonly (string | RegExp)[];
     /**
      * Declared-crawler verification rules. When provided, an IP source is
-     * required (`resolveIp` or `trustProxyHeaders`), otherwise construction
-     * throws.
+     * required (`resolveIp`, `trustedHops`, `trustedProxies`, or
+     * `trustProxyHeaders`), otherwise construction throws.
      */
     verifiedBots?: readonly VerifiedBotRule[];
     /**
@@ -147,6 +147,16 @@ export interface BotGuardOptions {
      * an integer in [1, 64]; validated at construction.
      */
     trustedHops?: number;
+    /**
+     * Declare WHICH proxies are yours: an IP/CIDR allowlist for the immediate
+     * peer's address. Forwarded headers are honoured only when the TCP socket
+     * actually talking to the adapter matches the list, so a direct-to-origin
+     * attacker cannot impersonate a verified crawler's IP. Implies
+     * proxy-header trust at one hop unless {@link trustedHops} says otherwise;
+     * validated and compiled at construction. On peer-less edge platforms
+     * verification fails closed.
+     */
+    trustedProxies?: readonly string[];
     /**
      * Custom client-IP resolver. Overrides {@link BotGuardOptions.trustProxyHeaders}.
      */

package/dist/bot-guard.js

@@ -36,7 +36,7 @@
  * @since 0.37.0
  */
 import { ForbiddenError } from "./errors.js";
-import { resolveForwardedClientIp, resolveForwardedTrust } from "./conn-info.js";
+import { resolveForwardedClientIp, resolveForwardedTrust, resolveTrustedProxyMatchers, } from "./conn-info.js";
 const DEFAULT_MESSAGE = "Bot access denied";
 const DEFAULT_CACHE_TTL_MS = 60 * 60_000;
 const DEFAULT_CACHE_MAX = 10_000;
@@ -94,8 +94,8 @@ function matchesUserAgent(ua, patterns) {
  * `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 forwardedIpResolver(hops, trustedPeers) {
+    return (ctx) => resolveForwardedClientIp(ctx.request, hops, trustedPeers);
 }
 function noIpResolver(_ctx) {
     return undefined;
@@ -210,10 +210,12 @@ export function botGuard(opts = {}) {
         throw new Error('botGuard(): mode must be "block" or "log".');
     }
     const hops = resolveForwardedTrust("botGuard()", opts);
-    const resolveIp = opts.resolveIp ?? (hops !== undefined ? forwardedIpResolver(hops) : noIpResolver);
+    const proxyMatchers = resolveTrustedProxyMatchers("botGuard()", opts);
+    const resolveIp = opts.resolveIp ??
+        (hops !== undefined ? forwardedIpResolver(hops, proxyMatchers) : 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.");
+            "trustedProxies, or set trustProxyHeaders, otherwise declared crawlers cannot be verified.");
     }
     const resolver = opts.resolver ?? createDefaultResolver();
     // Per-IP verification cache (keyed by `ip\u0000botName`) so a crawler's DNS

package/dist/concurrency-limit.d.ts

@@ -113,6 +113,16 @@ export interface ConcurrencyLimitOptions {
      * in [1, 64]; validated at construction.
      */
     trustedHops?: number;
+    /**
+     * Declare WHICH proxies are yours: an IP/CIDR allowlist for the immediate
+     * peer's address when `scope: "client"`. Forwarded headers feed the bucket
+     * key only when the TCP socket actually talking to the adapter matches the
+     * list, so a direct-to-origin attacker cannot hop buckets with spoofed XFF
+     * to hoard slots. Implies proxy-header trust at one hop unless
+     * {@link trustedHops} says otherwise; validated and compiled at
+     * construction. On peer-less edge platforms verification fails closed.
+     */
+    trustedProxies?: readonly string[];
     /**
      * Custom client-identity resolver for `scope: "client"`. Overrides
      * {@link trustProxyHeaders}. Returning `undefined` skips limiting for the

package/dist/concurrency-limit.js

@@ -46,7 +46,7 @@
  * @since 0.37.0
  */
 import { HttpError } from "./errors.js";
-import { resolveForwardedClientIp, resolveForwardedTrust } from "./conn-info.js";
+import { getConnInfo, resolveForwardedClientIp, resolveForwardedTrust, resolveTrustedProxyMatchers, } 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;
@@ -64,9 +64,17 @@ function assertNonNegativeInteger(name, value) {
  * @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}.
+ * When no trustworthy forwarded identity exists, falls back to the unspoofable
+ * TCP peer so a missing/spoofed XFF cannot skip the limit entirely (undefined
+ * would fail open). Peer-less platforms still return `undefined` (skip).
  */
-function forwardedKey(hops) {
-    return (ctx) => resolveForwardedClientIp(ctx.request, hops);
+function forwardedKey(hops, trustedPeers) {
+    return (ctx) => {
+        const forwarded = resolveForwardedClientIp(ctx.request, hops, trustedPeers);
+        if (forwarded !== undefined)
+            return forwarded;
+        return getConnInfo(ctx.request)?.remoteAddress;
+    };
 }
 /** Extract just the pathname from a request URL without a full `URL` parse where possible. */
 function pathnameOf(url) {
@@ -107,16 +115,17 @@ function buildScopeResolver(opts) {
     }
     // scope === "client"
     const hops = resolveForwardedTrust("concurrencyLimit()", opts);
+    const proxyMatchers = resolveTrustedProxyMatchers("concurrencyLimit()", opts);
     let resolve;
     if (opts.keyGenerator) {
         resolve = opts.keyGenerator;
     }
     else if (hops !== undefined) {
-        resolve = forwardedKey(hops);
+        resolve = forwardedKey(hops, proxyMatchers);
     }
     else {
-        throw new Error('concurrencyLimit(): scope "client" requires keyGenerator, trustedHops, or trustProxyHeaders so ' +
-            "clients can be identified; otherwise every caller shares one bucket.");
+        throw new Error('concurrencyLimit(): scope "client" requires keyGenerator, trustedHops, trustedProxies, or ' +
+            "trustProxyHeaders so clients can be identified; otherwise every caller shares one bucket.");
     }
     return (ctx) => {
         const id = resolve(ctx);

package/dist/conn-info.d.ts

@@ -19,6 +19,7 @@
  * @since 0.24.0
  */
 import type { BaseContext } from "./types.js";
+import { type IpMatcher } from "./ip-match.js";
 /**
  * Declarative reverse-proxy posture. Replaces the
  * foot-gunny `trustProxy: boolean` with a structured value that
@@ -127,23 +128,57 @@ export declare function pickForwardedForByHops(header: string | null, hops: numb
  * `behindProxy.hops` range: the floor of one exists because a middleware that
  * trusts zero proxy hops has no business reading forwarding headers at all.
  *
+ * `trustedProxies` (a CIDR allowlist of proxy peer addresses) also enables
+ * forwarded-header trust, defaulting to one hop when `trustedHops` is not
+ * set: declaring WHO your proxies are is meaningless unless their headers
+ * are then read. Pair it with {@link resolveTrustedProxyMatchers} and pass
+ * the compiled matchers to {@link resolveForwardedClientIp} so the forwarded
+ * identity is honoured only when the immediate TCP peer is a verified proxy.
+ *
  * @param name - Middleware function name used in error messages.
- * @param opts - The middleware's options object; only the two trust fields are
+ * @param opts - The middleware's options object; only the 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.
+ *   enabled — `trustedHops` verbatim, `1` for a bare
+ *   `trustProxyHeaders: true`, or `1` when `trustedProxies` is declared
+ *   without an explicit hop count — 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.
+ *   `trustProxyHeaders: false` is combined with a `trustedHops` value or a
+ *   `trustedProxies` list. Those pairings are contradictions, and the first
+ *   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;
+    trustedProxies?: readonly string[];
 }): number | undefined;
+/**
+ * Validate and compile a middleware's `trustedProxies` CIDR allowlist into
+ * matchers usable with {@link resolveForwardedClientIp}. Called once at
+ * construction so the per-request cost of peer verification is a handful of
+ * byte comparisons, never string parsing.
+ *
+ * The allowlist answers the question `trustedHops` alone cannot: not "how
+ * many proxies are in front of me" but "is the socket actually talking to me
+ * one of MY proxies". Without it, any client that can reach the origin
+ * directly can claim any `X-Forwarded-For` identity — the victim-IP framing
+ * and ban-evasion classes documented on {@link resolveForwardedClientIp}.
+ *
+ * @param name - Middleware function name used in error messages.
+ * @param opts - The middleware's options object; only `trustedProxies` is read.
+ * @returns The compiled matchers, or `undefined` when `trustedProxies` is not
+ *   declared (no peer verification — the pre-existing posture).
+ * @throws Error when the list is empty (a silent "trust nobody" foot-gun) or
+ *   any entry is not a valid IP/CIDR. Both are refuse-at-construction
+ *   misconfigurations, never request-time surprises.
+ * @internal
+ */
+export declare function resolveTrustedProxyMatchers(name: string, opts: {
+    trustedProxies?: readonly string[];
+}): IpMatcher[] | 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`.
@@ -165,17 +200,27 @@ export declare function resolveForwardedTrust(name: string, opts: {
  * 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.
+ * attacker-controlled by definition. `trustedPeers` closes that gap at the
+ * framework layer: when supplied, the forwarded identity is honoured only
+ * when the immediate TCP peer — the socket actually talking to the adapter,
+ * which a remote client cannot spoof — is inside the declared proxy
+ * allowlist. A direct-to-origin attacker then gets `undefined` (no
+ * identity), so spoofed headers can neither frame a victim nor rotate away
+ * strikes. When conn metadata is absent (peer-less edge platforms),
+ * verification fails closed.
  *
  * @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.
+ * @param trustedPeers - Optional compiled allowlist from
+ *   {@link resolveTrustedProxyMatchers}. When supplied, forwarded headers
+ *   are honoured only if the immediate peer matches; otherwise `undefined`.
  * @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;
+export declare function resolveForwardedClientIp(request: Request, hops?: number, trustedPeers?: readonly IpMatcher[]): string | undefined;
 /**
  * Resolve the client IP for this request using the configured
  * {@link BehindProxyConfig}. Returns `undefined` when no trusted source is