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

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

@@ -24,7 +24,7 @@
  * @module
  * @since 0.37.0
  */
-import type { BaseContext, Hooks } from "./types.js";
+import type { Hooks, IdentityGateContext } from "./types.js";
 /**
  * Why a request was (or would have been) blocked by {@link geoBlock}.
  *
@@ -57,7 +57,7 @@ export interface GeoBlockDecision {
  *
  * @since 0.37.0
  */
-export type CountryFromContext = (ctx: BaseContext<any, any>) => string | undefined | null | Promise<string | undefined | null>;
+export type CountryFromContext = (ctx: IdentityGateContext) => string | undefined | null | Promise<string | undefined | null>;
 /**
  * Operator-supplied IP → country lookup (e.g. a MaxMind reader). Return
  * `undefined`/`null`/`""` when the IP cannot be mapped to a country.
@@ -110,14 +110,29 @@ export interface GeoBlockOptions {
      * default Daloy fails closed because Web-standard `Request` objects do not
      * expose the peer address. Ignored when `resolveCountry` is used.
      */
-    resolveIp?: (ctx: BaseContext<any, any>) => string | undefined;
+    resolveIp?: (ctx: IdentityGateContext) => string | undefined;
     /**
      * Read `X-Forwarded-For` / `X-Real-IP` in the default IP resolver. Defaults
      * 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,9 +104,16 @@ 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) {
+        // Runs in `preBody`, not `beforeHandle`. A `beforeHandle` hook that returns
+        // a Response ends the chain, so a country gate in that phase is preempted by
+        // any earlier `beforeHandle` middleware that short-circuits — a
+        // `responseCache()` HIT above it would serve a denied country the cached
+        // body. `preBody` always precedes `beforeHandle`, which makes the gate
+        // immune to mount order. See {@link geoBlock}'s security note.
+        async preBody(ctx) {
             let ip;
             let rawCountry;
             if (resolveCountry) {

package/dist/idempotency.d.ts

@@ -164,17 +164,71 @@ export interface IdempotencyOptions {
      * unauthenticated idempotent writes). Returning a stable per-user id is
      * preferable to the raw credential when tokens rotate between retries.
      *
+     * **Supply this whenever `Authorization` is not per-user.** The default assumes
+     * that header names one caller. If it is shared — a per-tenant API key, a
+     * service token, a gateway credential — with end users distinguished some other
+     * way (a session cookie, a subject claim your app reads), then the default
+     * partitions per *tenant* and every user inside one tenant shares a namespace.
+     * A caller who knows another's `Idempotency-Key` can then replay their stored
+     * response. This is not detectable from the header alone, which is why it is
+     * your call rather than a framework guard: a resolvable-but-coarse scope looks
+     * identical to a correctly per-user one. The cookie-only case *is* guarded —
+     * see {@link allowUnscopedCallers}.
+     *
+     * Independently of scoping, a replay never re-issues `Set-Cookie`, so a coarse
+     * namespace cannot escalate from disclosing a response body into handing over a
+     * live session.
+     *
      * @since 0.40.0
      */
     scope?: (ctx: BaseContext<any, any>) => string | undefined | Promise<string | undefined>;
+    /**
+     * Accept callers the default {@link scope} resolver cannot identify, letting
+     * them share one idempotency namespace. Default `false`.
+     *
+     * The guard this disables exists because a cookie-authenticated request
+     * carries no `Authorization` header, so the default resolver returns
+     * `undefined` and the namespace collapses. The retry fingerprint (method +
+     * path + body) is then all that separates two users — and two users
+     * submitting the same payload fingerprint identically, so one replays the
+     * other's stored response (CWE-524). Rather than share the namespace
+     * silently, a cookie-bearing request with no resolvable scope throws with an
+     * actionable message.
+     *
+     * Set this to `true` only when unscoped callers are genuinely interchangeable
+     * — a public, unauthenticated idempotent write where no response body is
+     * caller-specific. Supplying {@link scope} is almost always the right answer
+     * instead. A custom `scope` bypasses the guard entirely, including when it
+     * returns `undefined`, because an explicit resolver owns its own posture.
+     *
+     * @since 1.0.0-rc.8
+     */
+    allowUnscopedCallers?: boolean;
 }
 /**
  * In-memory {@link IdempotencyStore}. Suitable for tests and single-process
- * deployments. Expired records are dropped on access; the map is opportunistically
- * pruned so it cannot grow without bound.
+ * deployments. Expired records are dropped on access.
+ *
+ * Growth is bounded by {@link maxEntries}: an expiry sweep runs first, and if the
+ * store is still at the cap the oldest surviving record is evicted. The sweep
+ * alone is not a bound — it only drops records that have *expired*, so a stream
+ * of unique keys inside the TTL grew the map linearly no matter how often it ran,
+ * with each entry pinning a stored response body.
+ *
+ * Evicting a live record can only cost exactly-once semantics for a retry that
+ * arrives after the eviction — it re-executes rather than replaying. That is the
+ * right trade against unbounded memory, but it is a reason to supply a shared
+ * (e.g. Redis) store for any deployment where the key volume approaches the cap.
  */
 export declare class MemoryIdempotencyStore implements IdempotencyStore {
     private readonly map;
+    private readonly maxEntries;
+    /**
+     * @param maxEntries - Maximum live records retained. Must be a positive
+     *   integer. Default {@link DEFAULT_MAX_IDEMPOTENCY_ENTRIES} (10 000).
+     * @throws Error when `maxEntries` is not a positive integer.
+     */
+    constructor(maxEntries?: number);
     /**
      * @inheritDoc
      * `_ttlMs` is part of the {@link IdempotencyStore} contract but unused here:

package/dist/idempotency.js

@@ -55,13 +55,44 @@ export function _resetSharedIdempotencyStoresForTests() {
     SHARED_IDEMPOTENCY_STORES.clear();
 }
 // ---------- Default store ----------
+/**
+ * Default cap on live records held by {@link MemoryIdempotencyStore}.
+ *
+ * Each record can hold a base64 response body up to
+ * {@link IdempotencyOptions.maxResponseBytes} (1 MiB by default), so the cap is
+ * what actually bounds this store's footprint. Matches the size at which the
+ * store already attempted an expiry sweep.
+ */
+const DEFAULT_MAX_IDEMPOTENCY_ENTRIES = 10_000;
 /**
  * In-memory {@link IdempotencyStore}. Suitable for tests and single-process
- * deployments. Expired records are dropped on access; the map is opportunistically
- * pruned so it cannot grow without bound.
+ * deployments. Expired records are dropped on access.
+ *
+ * Growth is bounded by {@link maxEntries}: an expiry sweep runs first, and if the
+ * store is still at the cap the oldest surviving record is evicted. The sweep
+ * alone is not a bound — it only drops records that have *expired*, so a stream
+ * of unique keys inside the TTL grew the map linearly no matter how often it ran,
+ * with each entry pinning a stored response body.
+ *
+ * Evicting a live record can only cost exactly-once semantics for a retry that
+ * arrives after the eviction — it re-executes rather than replaying. That is the
+ * right trade against unbounded memory, but it is a reason to supply a shared
+ * (e.g. Redis) store for any deployment where the key volume approaches the cap.
  */
 export class MemoryIdempotencyStore {
     map = new Map();
+    maxEntries;
+    /**
+     * @param maxEntries - Maximum live records retained. Must be a positive
+     *   integer. Default {@link DEFAULT_MAX_IDEMPOTENCY_ENTRIES} (10 000).
+     * @throws Error when `maxEntries` is not a positive integer.
+     */
+    constructor(maxEntries = DEFAULT_MAX_IDEMPOTENCY_ENTRIES) {
+        if (!Number.isInteger(maxEntries) || maxEntries < 1) {
+            throw new Error(`MemoryIdempotencyStore: maxEntries must be a positive integer; got ${String(maxEntries)}.`);
+        }
+        this.maxEntries = maxEntries;
+    }
     /**
      * @inheritDoc
      * `_ttlMs` is part of the {@link IdempotencyStore} contract but unused here:
@@ -71,9 +102,19 @@ export class MemoryIdempotencyStore {
         const existing = this.read(key);
         if (existing)
             return existing;
-        this.map.set(key, record);
-        if (this.map.size > 10_000)
+        if (this.map.size >= this.maxEntries) {
             this.prune();
+            // Still full: every record is live, so drop the oldest. `Map` iterates in
+            // insertion order, and `complete()` overwrites in place rather than
+            // re-inserting, so the first key is the least recently reserved.
+            while (this.map.size >= this.maxEntries) {
+                const oldest = this.map.keys().next();
+                if (oldest.done)
+                    break;
+                this.map.delete(oldest.value);
+            }
+        }
+        this.map.set(key, record);
         return null;
     }
     /** @inheritDoc */
@@ -185,20 +226,69 @@ function validateKey(key, headerName, maxLen) {
         throw new BadRequestError(`${headerName} header contains invalid characters.`);
     }
 }
+/**
+ * Response headers that must never be stored for replay.
+ *
+ * `set-cookie` is the security-critical entry. A stored response was replayed
+ * with every header the original produced, so a `Set-Cookie` issued to the first
+ * caller was re-issued to whoever replayed the record. Combined with any
+ * coarse-scoped namespace (a shared tenant `Authorization`, or an explicit
+ * `allowUnscopedCallers: true`) that promotes a body disclosure into handing over
+ * a live session — account takeover rather than data leakage. Even for a
+ * correctly scoped, genuinely same-caller retry it is wrong: the replay would
+ * resurrect a cookie the handler set once, silently rolling back a session
+ * rotation performed at login or on a privilege change.
+ *
+ * Unlike `responseCache()`, which refuses to store a `Set-Cookie` response at
+ * all, idempotency strips and stores: declining to store would release the
+ * reservation and let a retry re-execute the handler, which for a payment or
+ * order endpoint is the double-charge this middleware exists to prevent.
+ * Stripping keeps exactly-once semantics and drops only the header that must not
+ * be replayed.
+ *
+ * The remainder are hop-by-hop or per-request fields (RFC 9110 §7.6.1) that
+ * describe the one connection or the one request that populated the record;
+ * replaying `x-request-id` in particular hands every later caller a correlation
+ * id belonging to someone else's request.
+ */
+const NEVER_REPLAYED_HEADERS = new Set([
+    "set-cookie",
+    "set-cookie2",
+    "age",
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+    "x-request-id",
+]);
 async function captureResponse(res, maxBytes) {
     const buf = new Uint8Array(await res.clone().arrayBuffer());
     if (buf.byteLength > maxBytes)
         return null;
     const headers = [];
     res.headers.forEach((value, name) => {
-        headers.push([name, value]);
+        // Filter on capture, not on replay, so a credential never reaches the store
+        // in the first place — a shared (Redis) store would otherwise persist one
+        // caller's session cookie for the whole TTL.
+        if (!NEVER_REPLAYED_HEADERS.has(name.toLowerCase()))
+            headers.push([name, value]);
     });
     return { status: res.status, headers, body: buf.byteLength ? bytesToBase64(buf) : "" };
 }
 function buildReplayResponse(stored, replayHeaderName) {
     const headers = new Headers();
-    for (const [name, value] of stored.headers)
+    for (const [name, value] of stored.headers) {
+        // Filtered on capture already; re-checked here so a record written by an
+        // older build — or by any other writer sharing the same Redis store — cannot
+        // replay a credential either.
+        if (NEVER_REPLAYED_HEADERS.has(name.toLowerCase()))
+            continue;
         headers.set(name, value);
+    }
     headers.set(replayHeaderName, "true");
     const body = stored.body ? base64ToBytes(stored.body) : null;
     return markSchemaValidatedResponse(new Response(body, { status: stored.status, headers }));
@@ -252,6 +342,7 @@ export function idempotency(opts = {}) {
     const replayHeaderName = (opts.replayHeaderName ?? "idempotency-replayed").toLowerCase();
     const methods = new Set((opts.methods ?? ["POST", "PUT", "PATCH", "DELETE"]).map((m) => m.toUpperCase()));
     const requireKey = opts.requireKey === true;
+    const allowUnscopedCallers = opts.allowUnscopedCallers === true;
     const cacheableStatus = opts.cacheableStatus ?? ((status) => status < 500);
     const ttlMs = ttlSeconds * 1_000;
     let store;
@@ -291,6 +382,44 @@ export function idempotency(opts = {}) {
             const scopeRaw = opts.scope
                 ? await opts.scope(ctx)
                 : (ctx.request.headers.get("authorization") ?? undefined);
+            // A credentialed request the default resolver cannot see is the dangerous
+            // case: cookie-session auth sends no `Authorization`, so `scopeRaw` is
+            // undefined, the namespace collapses to the shared one, and the retry
+            // fingerprint (method + path + body) becomes the only thing separating two
+            // users. Two users legitimately submit the same payload fingerprint
+            // identically — so client B replays client A's stored response, which is
+            // exactly the CWE-524 disclosure `scope` exists to prevent.
+            //
+            // Fail loudly rather than share the namespace. This mirrors
+            // `responseCache()`, which treats `Cookie` as a credential alongside
+            // `Authorization` for the same reason. Only fires when a cookie is present
+            // *and* nothing resolved, so the documented bearer-token path is untouched
+            // and a genuinely anonymous caller still shares the unscoped namespace.
+            //
+            // Deliberately NOT widened to "any cookie-bearing request". A resolvable
+            // scope can still be too coarse — a per-tenant API key with
+            // cookie-identified end users partitions per tenant while every user inside
+            // one shares a namespace — but that is indistinguishable from the far more
+            // common shape of a *per-user* bearer token arriving alongside incidental
+            // browser cookies (analytics, consent, CSRF), where the default is already
+            // correct. Keying the guard on the cookie's presence rejects that setup with
+            // a 500, so the check stays where the default is provably useless rather
+            // than merely possibly coarse. Callers whose `Authorization` is shared
+            // across users must pass `scope` — see the TSDoc on
+            // {@link IdempotencyOptions.scope}. Independently of scoping, `Set-Cookie`
+            // is never stored or replayed (see {@link NEVER_REPLAYED_HEADERS}), so a
+            // coarse namespace cannot escalate into handing over a live session.
+            if (!opts.scope &&
+                scopeRaw === undefined &&
+                !allowUnscopedCallers &&
+                ctx.request.headers.has("cookie")) {
+                throw new Error("idempotency(): cannot determine the calling principal for a cookie-bearing request. " +
+                    "The default scope reads the Authorization header, which this request does not carry, " +
+                    "so every cookie-authenticated caller would share one idempotency namespace and could " +
+                    "replay another caller's stored response (CWE-524). Pass " +
+                    "`scope: (ctx) => ctx.state.session?.id` (or another stable per-caller id), or set " +
+                    "`allowUnscopedCallers: true` if these callers are genuinely interchangeable.");
+            }
             const scopeTag = scopeRaw ? `${await sha256Hex(scopeRaw)}:` : "";
             const storeKey = `${keyPrefix}${scopeTag}${key}`;
             const now = Date.now();

package/dist/index.d.ts

@@ -6,21 +6,21 @@ 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";
 export { defineDependency, DEPENDENCY_MARKER } from "./dependency.js";
 export type { DependencyHooks, DependencyOptions } from "./dependency.js";
-export type { RouteDefinition, HttpMethod, PathString, RequestSchemas, ResponsesMap, ResponseSpec, AuthSpec, Hooks, BaseContext, PreBodyContext, AppState, AuthScheme, AuthContext, HandlerReturn, InferRequest, ParamsOf, PathParams, CallbackDefinition, CallbackMap, CallbackOperation, RouteExample, RouteMeta, } from "./types.js";
+export type { RouteDefinition, HttpMethod, PathString, RequestSchemas, ResponsesMap, ResponseSpec, AuthSpec, Hooks, BaseContext, PreBodyContext, IdentityGateContext, AppState, AuthScheme, AuthContext, HandlerReturn, InferRequest, ParamsOf, PathParams, CallbackDefinition, CallbackMap, CallbackOperation, RouteExample, RouteMeta, } from "./types.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 type { ProblemDetails, ProblemRenderOptions, HttpErrorOptions } from "./errors.js";
 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";
@@ -101,5 +101,5 @@ export { otelTracing, TRACING_SPAN_KIND_SERVER, TRACING_SPAN_STATUS_UNSET, TRACI
 export type { OtelTracingOptions, TracingAttributes, TracingAttributeValue, TracingSpan, TracingStartSpanOptions, TracingTracer, } from "./tracing.js";
 export { tenancy, tenantScope, tenantFromSubdomain, tenantFromHeader, tenantFromPathPrefix, tenantFromClaim, defaultTenantNormalize, TENANCY_HOOK_MARKER, TENANCY_RESOLVED_MARKER, TENANT_UNRESOLVED, } from "./tenancy.js";
 export type { TenancyOptions, TenantResolver, TenantScopeOptions, SubdomainTenantOptions, PathPrefixTenantOptions, ClaimTenantOptions, UnresolvedStatus, InvalidStatus, } from "./tenancy.js";
-export { defineWebSocket, WebSocketRegistry, WebSocketProtocolError, WebSocketPayloadTooLargeError, WS_GUID, WS_READY_STATE, WS_OPCODE, WS_CLOSE_CODE, WS_MAX_CONTROL_PAYLOAD, DEFAULT_WS_BACKPRESSURE_LIMIT, DEFAULT_WS_MAX_PAYLOAD_LENGTH, DEFAULT_WS_IDLE_TIMEOUT_SECONDS, computeAcceptKey, parseSubprotocols, validateSelectedSubprotocol, validateUpgrade, checkWebSocketOrigin, parseFrame, encodeFrame, encodeClosePayload, decodeClosePayload, encodeSendPayload, normalizeWebSocketOptions, wsRateLimit, FrameSink, FRAME_INCOMPLETE, } from "./websocket.js";
+export { defineWebSocket, WebSocketRegistry, WebSocketProtocolError, WebSocketPayloadTooLargeError, WS_GUID, WS_READY_STATE, WS_OPCODE, WS_CLOSE_CODE, WS_MAX_CONTROL_PAYLOAD, DEFAULT_WS_BACKPRESSURE_LIMIT, DEFAULT_WS_MAX_PAYLOAD_LENGTH, DEFAULT_WS_IDLE_TIMEOUT_SECONDS, computeAcceptKey, parseSubprotocols, validateSelectedSubprotocol, validateUpgrade, checkWebSocketOrigin, parseFrame, encodeFrame, encodeClosePayload, decodeClosePayload, isValidWireCloseCode, encodeSendPayload, normalizeWebSocketOptions, wsRateLimit, FrameSink, FRAME_INCOMPLETE, } from "./websocket.js";
 export type { WebSocketConnection, WebSocketContext, WebSocketHandler, WebSocketMeta, WebSocketRouteEntry, NormalizedWebSocketOptions, WebSocketBeforeUpgrade, HandshakeResult, ParsedFrame, MessageEvent as WebSocketMessageEvent, FrameSinkEvents, } from "./websocket.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";
@@ -51,4 +51,4 @@ export { MetricsRegistry, Counter, Gauge, Histogram, httpMetrics, DEFAULT_DURATI
 export { fileField, multipartObject, isFileFieldSchema, isMultipartObjectSchema, } from "./multipart.js";
 export { otelTracing, TRACING_SPAN_KIND_SERVER, TRACING_SPAN_STATUS_UNSET, TRACING_SPAN_STATUS_OK, TRACING_SPAN_STATUS_ERROR, } from "./tracing.js";
 export { tenancy, tenantScope, tenantFromSubdomain, tenantFromHeader, tenantFromPathPrefix, tenantFromClaim, defaultTenantNormalize, TENANCY_HOOK_MARKER, TENANCY_RESOLVED_MARKER, TENANT_UNRESOLVED, } from "./tenancy.js";
-export { defineWebSocket, WebSocketRegistry, WebSocketProtocolError, WebSocketPayloadTooLargeError, WS_GUID, WS_READY_STATE, WS_OPCODE, WS_CLOSE_CODE, WS_MAX_CONTROL_PAYLOAD, DEFAULT_WS_BACKPRESSURE_LIMIT, DEFAULT_WS_MAX_PAYLOAD_LENGTH, DEFAULT_WS_IDLE_TIMEOUT_SECONDS, computeAcceptKey, parseSubprotocols, validateSelectedSubprotocol, validateUpgrade, checkWebSocketOrigin, parseFrame, encodeFrame, encodeClosePayload, decodeClosePayload, encodeSendPayload, normalizeWebSocketOptions, wsRateLimit, FrameSink, FRAME_INCOMPLETE, } from "./websocket.js";
+export { defineWebSocket, WebSocketRegistry, WebSocketProtocolError, WebSocketPayloadTooLargeError, WS_GUID, WS_READY_STATE, WS_OPCODE, WS_CLOSE_CODE, WS_MAX_CONTROL_PAYLOAD, DEFAULT_WS_BACKPRESSURE_LIMIT, DEFAULT_WS_MAX_PAYLOAD_LENGTH, DEFAULT_WS_IDLE_TIMEOUT_SECONDS, computeAcceptKey, parseSubprotocols, validateSelectedSubprotocol, validateUpgrade, checkWebSocketOrigin, parseFrame, encodeFrame, encodeClosePayload, decodeClosePayload, isValidWireCloseCode, encodeSendPayload, normalizeWebSocketOptions, wsRateLimit, FrameSink, FRAME_INCOMPLETE, } from "./websocket.js";

package/dist/ip-reputation.d.ts

@@ -44,7 +44,7 @@
  * @module
  * @since 0.37.0
  */
-import type { BaseContext, Hooks } from "./types.js";
+import type { Hooks, IdentityGateContext } from "./types.js";
 /**
  * A pluggable source of abusive IP / CIDR entries. Implementations return the
  * raw list each refresh; parsing, validation, and de-duplication are handled by
@@ -105,12 +105,26 @@ export interface IpReputationOptions {
      * Custom client-IP resolver. Overrides {@link IpReputationOptions.trustProxyHeaders}.
      * Defaults to failing open (no IP → not blocked).
      */
-    resolveIp?: (ctx: BaseContext<any, any>) => string | undefined;
+    resolveIp?: (ctx: IdentityGateContext) => string | undefined;
     /**
      * 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: [] }));
@@ -222,7 +222,12 @@ export function ipReputation(opts) {
     const ready = opts.loadOnStart === false ? Promise.resolve() : refresh();
     return {
         hooks: {
-            beforeHandle(ctx) {
+            // `preBody`, not `beforeHandle`: a denylist gate that short-circuits from
+            // `beforeHandle` is preempted by any earlier `beforeHandle` middleware that
+            // returns a Response first — a `responseCache()` HIT mounted above it would
+            // serve a denylisted address the cached body. `preBody` always runs first,
+            // so the feed holds regardless of mount order.
+            preBody(ctx) {
                 const ip = resolveIp(ctx);
                 if (!ip)
                     return undefined; // fail-open on unresolved IP