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

package/dist/middleware.d.ts

@@ -470,8 +470,22 @@ export interface RateLimitOptions {
      * Trust x-forwarded-for / x-real-ip when deriving the default key.
      * Off by default because those headers are client-spoofable unless your
      * reverse proxy strips and rewrites them.
+     *
+     * When enabled, the key is the **rightmost** `X-Forwarded-For` entry — the
+     * one your immediate proxy appended — never the attacker-influenceable
+     * leftmost one, so rotating spoofed left entries cannot evade the limit.
+     * 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 derives the default key 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. Ignored when a custom `keyGenerator`
+     * is supplied.
+     */
+    trustedHops?: number;
     /** When true, set Retry-After header on 429. Default: true. */
     retryAfter?: boolean;
     /**
@@ -546,8 +560,24 @@ export interface LoginThrottleOptions {
     keyGenerator?: (ctx: RateLimitContext) => string;
     /** Shared store for the hard limit. Uses rateLimit()'s in-memory group bucket by default. */
     store?: RateLimitStore;
-    /** Trust x-forwarded-for / x-real-ip when deriving the default key. Default: false. */
+    /** Trust x-forwarded-for / x-real-ip when deriving the default key. Default: false.
+     *
+     * When enabled, the key is the **rightmost** `X-Forwarded-For` entry — the
+     * one your immediate proxy appended — never the attacker-influenceable
+     * leftmost one. Behind more than one proxy hop, set {@link trustedHops}
+     * instead.
+     */
     trustProxyHeaders?: boolean;
+    /**
+     * Declare exactly how many proxy hops sit between Daloy and the public
+     * internet. Implies proxy-header trust and derives the default key that
+     * many entries from the right of `X-Forwarded-For` via
+     * {@link "./conn-info.js".resolveForwardedClientIp}, so rotating spoofed
+     * left entries cannot evade the throttle. Must be an integer in [1, 64];
+     * validated at construction. Ignored when a custom `keyGenerator` is
+     * supplied.
+     */
+    trustedHops?: number;
     /** When true, set Retry-After header on 429. Default: true. */
     retryAfter?: boolean;
     /** Start slowing responses after this many attempts in the same window. Default: 2. */

package/dist/middleware.js

@@ -7,6 +7,7 @@
 import { assertCookieAttributes, readRequestCookie, serializeCookie } from "./cookie.js";
 import { TooManyRequestsError, ForbiddenError } from "./errors.js";
 import { randomId, sanitizeHeaderName, timingSafeEqual } from "./security.js";
+import { resolveForwardedClientIp, resolveForwardedTrust } from "./conn-info.js";
 /**
  * Generate or accept a stable `X-Request-ID` for every request. The id is
  * stamped on `ctx.state.requestId`, mirrored on outgoing response headers,
@@ -775,15 +776,8 @@ export function rateLimit(opts) {
         store = new MemoryStore();
     }
     const groupPrefix = opts.groupId ? `${opts.groupId}:` : "";
-    const keyOf = opts.keyGenerator ??
-        ((ctx) => {
-            if (opts.trustProxyHeaders) {
-                const xff = ctx.request.headers.get("x-forwarded-for");
-                const first = xff ? xff.split(",")[0].trim() : "";
-                return first || ctx.request.headers.get("x-real-ip") || "global";
-            }
-            return "global";
-        });
+    const hops = resolveForwardedTrust("rateLimit()", opts);
+    const keyOf = opts.keyGenerator ?? defaultForwardedRateLimitKey(hops);
     const enforce = async (ctx) => {
         const key = `${groupPrefix}${keyOf(ctx)}`;
         const { count, resetMs } = await store.hit(key, opts.windowMs);
@@ -811,15 +805,22 @@ function assertPositiveInteger(name, value) {
         throw new Error(`loginThrottle(): ${name} must be a positive integer.`);
     }
 }
-function defaultLoginThrottleKey(trustProxyHeaders) {
-    return (ctx) => {
-        if (trustProxyHeaders) {
-            const forwardedFor = ctx.request.headers.get("x-forwarded-for");
-            const firstForwarded = forwardedFor ? forwardedFor.split(",")[0].trim() : "";
-            return firstForwarded || ctx.request.headers.get("x-real-ip") || "global";
-        }
-        return "global";
-    };
+/**
+ * Default rate-limit / login-throttle key: the spoof-resistant forwarded client
+ * IP, or the shared `"global"` bucket when proxy-header trust is off or the
+ * request carries no trustworthy forwarded identity.
+ *
+ * @param hops - Trusted proxy hop count from
+ *   {@link "./conn-info.js".resolveForwardedTrust}, or `undefined` when
+ *   forwarded-header trust is disabled.
+ * @returns A key generator suitable for {@link rateLimit} and
+ *   {@link loginThrottle}.
+ * @internal
+ */
+function defaultForwardedRateLimitKey(hops) {
+    if (hops === undefined)
+        return () => "global";
+    return (ctx) => resolveForwardedClientIp(ctx.request, hops) ?? "global";
 }
 function wait(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -852,7 +853,8 @@ export function loginThrottle(opts = {}) {
     assertNonNegativeInteger("delayMs", delayMs);
     assertNonNegativeInteger("maxDelayMs", maxDelayMs);
     const groupId = opts.groupId ?? "login";
-    const keyGenerator = opts.keyGenerator ?? defaultLoginThrottleKey(opts.trustProxyHeaders);
+    const hops = resolveForwardedTrust("loginThrottle()", opts);
+    const keyGenerator = opts.keyGenerator ?? defaultForwardedRateLimitKey(hops);
     const limiter = rateLimit({
         windowMs,
         max,

package/dist/sbom.cdx.json

@@ -1,15 +1,15 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:1fe1844d-d5f6-5dd3-b35a-8f79f17a35f5",
+  "serialNumber": "urn:uuid:01ee81d6-1bb6-55ca-b05e-3e30279d9f5c",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-26T17:41:07.733Z",
+    "timestamp": "2026-07-29T20:03:05.244Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "1.0.0-rc.6"
+        "version": "1.0.0-rc.7"
       }
     ],
     "authors": [
@@ -19,11 +19,11 @@
     ],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/@daloyjs/core@1.0.0-rc.6",
+      "bom-ref": "pkg:npm/@daloyjs/core@1.0.0-rc.7",
       "name": "@daloyjs/core",
-      "version": "1.0.0-rc.6",
+      "version": "1.0.0-rc.7",
       "description": "DaloyJS is a runtime-portable, contract-first TypeScript web framework with built-in OpenAPI (Hey API), typed client generation, large-scale maintainability, and security-first defaults. Hono-grade portability, Elysia-grade DX, FastAPI-grade docs, Fastify-grade ops — distributed via pnpm.",
-      "purl": "pkg:npm/@daloyjs/core@1.0.0-rc.6",
+      "purl": "pkg:npm/@daloyjs/core@1.0.0-rc.7",
       "licenses": [
         {
           "license": {
@@ -46,9 +46,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag--daloyjs-core-1.0.0-rc.6",
+        "tagId": "swidtag--daloyjs-core-1.0.0-rc.7",
         "name": "@daloyjs/core",
-        "version": "1.0.0-rc.6",
+        "version": "1.0.0-rc.7",
         "tagVersion": 0,
         "patch": false
       }
@@ -57,7 +57,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/@daloyjs/core@1.0.0-rc.6",
+      "ref": "pkg:npm/@daloyjs/core@1.0.0-rc.7",
       "dependsOn": []
     }
   ]

package/dist/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@daloyjs/core-1.0.0-rc.6",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.0.0-rc.6-1fe1844d-d5f6-5dd3-b35a-8f79f17a35f5",
+  "name": "@daloyjs/core-1.0.0-rc.7",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.0.0-rc.7-01ee81d6-1bb6-55ca-b05e-3e30279d9f5c",
   "creationInfo": {
-    "created": "2026-07-26T17:41:07.733Z",
+    "created": "2026-07-29T20:03:05.244Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package--daloyjs-core",
       "name": "@daloyjs/core",
-      "versionInfo": "1.0.0-rc.6",
+      "versionInfo": "1.0.0-rc.7",
       "downloadLocation": "https://github.com/daloyjs/daloy",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
@@ -27,7 +27,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/@daloyjs/core@1.0.0-rc.6"
+          "referenceLocator": "pkg:npm/@daloyjs/core@1.0.0-rc.7"
         }
       ]
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daloyjs/core",
-  "version": "1.0.0-rc.6",
+  "version": "1.0.0-rc.7",
   "description": "DaloyJS is a runtime-portable, contract-first TypeScript web framework with built-in OpenAPI (Hey API), typed client generation, large-scale maintainability, and security-first defaults. Hono-grade portability, Elysia-grade DX, FastAPI-grade docs, Fastify-grade ops — distributed via pnpm.",
   "type": "module",
   "publishConfig": {