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

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/config.js

@@ -24,9 +24,7 @@ export class ConfigValidationError extends Error {
     /** Every validation issue, as `{ key, message }` pairs (`key` is the dotted path, `"<root>"`/`"<source>"` for top-level failures). */
     issues;
     constructor(issues) {
-        const summary = issues
-            .map((i) => `  - ${i.key || "<root>"}: ${i.message}`)
-            .join("\n");
+        const summary = issues.map((i) => `  - ${i.key || "<root>"}: ${i.message}`).join("\n");
         super(`defineConfig(): configuration is invalid (${issues.length} issue${issues.length === 1 ? "" : "s"})\n${summary}`);
         this.name = "ConfigValidationError";
         this.issues = issues;

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/errors.js

@@ -40,9 +40,7 @@ export class MessageLeakError extends Error {
     /** The refused headers, each with its name and the reason it was disallowed. */
     offendingHeaders;
     constructor(offendingHeaders) {
-        const summary = offendingHeaders
-            .map((h) => `${h.name} (${h.reason})`)
-            .join(", ");
+        const summary = offendingHeaders.map((h) => `${h.name} (${h.reason})`).join(", ");
         super(`httpError({ res }): custom error response carries disallowed header(s): ${summary}. ` +
             "Only WWW-Authenticate, Proxy-Authenticate, Retry-After, Content-Type, " +
             "Content-Language, Content-Length, and Cache-Control (no-store|no-cache) " +
@@ -212,8 +210,7 @@ export class HttpError extends Error {
      * @returns A `Response` with `Content-Type: application/problem+json`.
      */
     toResponse(opts = {}) {
-        const isProd = opts.production ??
-            (typeof process !== "undefined" && process.env?.NODE_ENV === "production");
+        const isProd = opts.production ?? (typeof process !== "undefined" && process.env?.NODE_ENV === "production");
         const out = { ...this.problem };
         if (isProd && this.status >= 500) {
             delete out.detail; // do not leak internals

package/dist/etag.js

@@ -38,7 +38,10 @@ async function sha1Hex(bytes) {
 }
 function inmMatches(headerValue, candidate) {
     // RFC 7232 §3.2: comma-separated list of entity tags or `*`.
-    const list = headerValue.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    const list = headerValue
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
     if (list.length === 0)
         return false;
     for (const tag of list) {
@@ -97,7 +100,14 @@ export function etag(opts = {}) {
             const inm = ctx?.request?.headers.get("if-none-match");
             if (inm && inmMatches(inm, value)) {
                 const stripped = new Headers();
-                for (const allow of ["cache-control", "content-location", "date", "etag", "expires", "vary"]) {
+                for (const allow of [
+                    "cache-control",
+                    "content-location",
+                    "date",
+                    "etag",
+                    "expires",
+                    "vary",
+                ]) {
                     const v = headers.get(allow);
                     if (v !== null)
                         stripped.set(allow, v);

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;
@@ -90,12 +89,10 @@ export function geoBlock(opts) {
     const hasLookup = typeof opts.lookupCountry === "function";
     const hasResolve = typeof opts.resolveCountry === "function";
     if (hasLookup === hasResolve) {
-        throw new Error('geoBlock(): exactly one of "lookupCountry" or "resolveCountry" must ' +
-            "be provided.");
+        throw new Error('geoBlock(): exactly one of "lookupCountry" or "resolveCountry" must ' + "be provided.");
     }
     if (opts.mode !== undefined && opts.mode !== "block" && opts.mode !== "log") {
-        throw new Error(`geoBlock(): invalid mode ${JSON.stringify(opts.mode)}; expected ` +
-            '"block" or "log".');
+        throw new Error(`geoBlock(): invalid mode ${JSON.stringify(opts.mode)}; expected ` + '"block" or "log".');
     }
     const allow = new Set((opts.allow ?? []).map(normalizeConfiguredCode));
     const deny = new Set((opts.deny ?? []).map(normalizeConfiguredCode));
@@ -107,8 +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;
@@ -120,9 +117,7 @@ export function geoBlock(opts) {
                 ip = resolveIp(ctx) ?? undefined;
                 rawCountry = ip ? await lookupCountry(ip) : undefined;
             }
-            const country = rawCountry && rawCountry.trim()
-                ? rawCountry.trim().toUpperCase()
-                : undefined;
+            const country = rawCountry && rawCountry.trim() ? rawCountry.trim().toUpperCase() : undefined;
             let reason;
             if (!country) {
                 if (!allowUnknown)

package/dist/hashing.js

@@ -22,7 +22,7 @@
  *
  * @since 0.15.0
  */
-import { randomBytes, scrypt as scryptCb, timingSafeEqual as nodeTimingSafeEqual } from "node:crypto";
+import { randomBytes, scrypt as scryptCb, timingSafeEqual as nodeTimingSafeEqual, } from "node:crypto";
 // OWASP-aligned scrypt parameters (Password Storage Cheat Sheet, 2024).
 const SCRYPT_N = 1 << 17; // 131072
 const SCRYPT_R = 8;

package/dist/http-signatures.js

@@ -61,8 +61,7 @@ const ENC = new TextEncoder();
 // WebCrypto + encoding helpers
 // ---------------------------------------------------------------------------
 function getCrypto() {
-    const c = globalThis
-        .crypto;
+    const c = globalThis.crypto;
     if (!c?.subtle) {
         throw new Error("http-signatures: WebCrypto SubtleCrypto API is unavailable on this runtime.");
     }
@@ -181,9 +180,7 @@ async function importKey(alg, material, usage) {
         return c.subtle.importKey("raw", material, spec.importParams, false, [usage]);
     }
     if (isJsonWebKey(material)) {
-        const key = await c.subtle.importKey("jwk", material, spec.importParams, false, [
-            usage,
-        ]);
+        const key = await c.subtle.importKey("jwk", material, spec.importParams, false, [usage]);
         assertRsaModulusFloor(alg, key);
         return key;
     }
@@ -686,9 +683,7 @@ export async function verifyMessage(opts) {
         return fail("key_not_found");
     let keyMaterial;
     let pinnedAlg;
-    if (resolved instanceof Uint8Array ||
-        isCryptoKey(resolved) ||
-        isJsonWebKey(resolved)) {
+    if (resolved instanceof Uint8Array || isCryptoKey(resolved) || isJsonWebKey(resolved)) {
         keyMaterial = resolved;
     }
     else {

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";
@@ -89,7 +89,7 @@ export { session, rotateSession, signValue, verifySignedValue, MemorySessionStor
 export type { SessionOptions, SessionCookieOptions, SessionContext, SessionRecord, SessionStore, SessionState, RotateSessionOptions, } from "./session.js";
 export { idempotency, MemoryIdempotencyStore, _resetSharedIdempotencyStoresForTests, } from "./idempotency.js";
 export type { IdempotencyOptions, IdempotencyStore, IdempotencyRecord, StoredIdempotentResponse, } from "./idempotency.js";
-export { responseCache, MemoryResponseCacheStore, _resetSharedResponseCacheStoresForTests, } from "./response-cache.js";
+export { responseCache, MemoryResponseCacheStore, RESPONSE_CACHE_HOOK_MARKER, _resetSharedResponseCacheStoresForTests, } from "./response-cache.js";
 export type { ResponseCacheOptions, ResponseCacheStore, CachedResponse } from "./response-cache.js";
 export { encodeCursor, decodeCursor, buildLinkHeader, buildPageLinks, paginationQuery, MAX_CURSOR_LENGTH, } from "./pagination.js";
 export type { PaginationLink, PageLinkOptions, PageLinks, PaginationQueryOptions, PaginationParams, PaginationQuerySchema, } from "./pagination.js";
@@ -99,7 +99,7 @@ export { fileField, multipartObject, isFileFieldSchema, isMultipartObjectSchema,
 export type { FileFieldSchema, FileFieldOptions, FileMagicBytesOption, FileMagicBytesSignature, MultipartObjectOptions, MultipartShape, UploadedFile, } 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 type { OtelTracingOptions, TracingAttributes, TracingAttributeValue, TracingSpan, TracingStartSpanOptions, TracingTracer, } from "./tracing.js";
-export { tenancy, tenantScope, tenantFromSubdomain, tenantFromHeader, tenantFromPathPrefix, tenantFromClaim, defaultTenantNormalize, } from "./tenancy.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 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";
@@ -45,10 +45,10 @@ export { httpBearerScheme, httpBasicScheme, apiKeyScheme, oauth2Scheme, openIdCo
 export { discriminator, discriminatedUnion } from "./discriminator.js";
 export { session, rotateSession, signValue, verifySignedValue, MemorySessionStore, SESSION_HOOK_MARKER, SESSION_SECRETS_MARKER, } from "./session.js";
 export { idempotency, MemoryIdempotencyStore, _resetSharedIdempotencyStoresForTests, } from "./idempotency.js";
-export { responseCache, MemoryResponseCacheStore, _resetSharedResponseCacheStoresForTests, } from "./response-cache.js";
+export { responseCache, MemoryResponseCacheStore, RESPONSE_CACHE_HOOK_MARKER, _resetSharedResponseCacheStoresForTests, } from "./response-cache.js";
 export { encodeCursor, decodeCursor, buildLinkHeader, buildPageLinks, paginationQuery, MAX_CURSOR_LENGTH, } from "./pagination.js";
 export { MetricsRegistry, Counter, Gauge, Histogram, httpMetrics, DEFAULT_DURATION_BUCKETS, PROMETHEUS_CONTENT_TYPE, } from "./metrics.js";
 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, } from "./tenancy.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";

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,7 +46,8 @@
  */
 import { ForbiddenError } from "./errors.js";
 import { fetchGuard } from "./fetch-guard.js";
-import { compileCidrMatcher, matchesMatcher, parseIp, } from "./ip-restriction.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;
 const DEFAULT_MESSAGE = "IP address not permitted";
@@ -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: [] }));

package/dist/ip-restriction.d.ts

@@ -42,8 +42,22 @@ export interface IpRestrictionOptions {
      * to `false` because those headers are client-spoofable unless every
      * request reaches Daloy through a proxy chain you control. Pair with
      * `new App({ trustProxy: true })` in production.
+     *
+     * When enabled, the resolver reads the **rightmost** `X-Forwarded-For`
+     * entry — the one your immediate proxy appended — never the
+     * attacker-influenceable leftmost one, so a spoofed left entry cannot
+     * bypass an allow-list or dodge a deny. 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}. Must be an integer in
+     * [1, 64]; validated at construction.
+     */
+    trustedHops?: number;
     /**
      * Response message when a request is rejected. Defaults to
      * `"IP address not permitted"`. Avoid echoing the client IP back —