express-rate-limit 8.0.1 → 8.2.0

package/dist/index.cjs

@@ -39,7 +39,8 @@ function ipKeyGenerator(ip, ipv6Subnet = 56) {
 
 // source/memory-store.ts
 var MemoryStore = class {
-  constructor() {
+  constructor(validations2) {
+    this.validations = validations2;
     /**
      * These two maps store usage (requests) and reset time by key (for example, IP
      * addresses or API keys).
@@ -65,6 +66,7 @@ var MemoryStore = class {
    */
   init(options) {
     this.windowMs = options.windowMs;
+    this.validations?.windowMs(this.windowMs);
     if (this.interval) clearInterval(this.interval);
     this.interval = setInterval(() => {
       this.clearExpired();
@@ -237,7 +239,7 @@ var setDraft6Headers = (response, info, windowMs) => {
   response.setHeader("RateLimit-Policy", `${info.limit};w=${windowSeconds}`);
   response.setHeader("RateLimit-Limit", info.limit.toString());
   response.setHeader("RateLimit-Remaining", info.remaining.toString());
-  if (resetSeconds)
+  if (typeof resetSeconds === "number")
     response.setHeader("RateLimit-Reset", resetSeconds.toString());
 };
 var setDraft7Headers = (response, info, windowMs) => {
@@ -367,6 +369,21 @@ var validations = {
       );
     }
   },
+  /**
+   * Alert the user if the Forwarded header is set (standardized version of X-Forwarded-For - not supported by express as of version 5.1.0)
+   *
+   * @param request {Request} - The Express request object.
+   *
+   * @returns {void}
+   */
+  forwardedHeader(request) {
+    if (request.headers.forwarded && request.ip === request.socket?.remoteAddress) {
+      throw new ValidationError(
+        "ERR_ERL_FORWARDED_HEADER",
+        `The 'Forwarded' header (standardized X-Forwarded-For) is set but currently being ignored. Add a custom keyGenerator to use a value from this header.`
+      );
+    }
+  },
   /**
    * Ensures totalHits value from store is a positive integer.
    *
@@ -504,12 +521,50 @@ var validations = {
       );
     }
   },
+  knownOptions(passedOptions) {
+    if (!passedOptions) return;
+    const optionsMap = {
+      windowMs: true,
+      limit: true,
+      message: true,
+      statusCode: true,
+      legacyHeaders: true,
+      standardHeaders: true,
+      identifier: true,
+      requestPropertyName: true,
+      skipFailedRequests: true,
+      skipSuccessfulRequests: true,
+      keyGenerator: true,
+      ipv6Subnet: true,
+      handler: true,
+      skip: true,
+      requestWasSuccessful: true,
+      store: true,
+      validate: true,
+      headers: true,
+      max: true,
+      passOnStoreError: true
+    };
+    const validOptions = Object.keys(optionsMap).concat(
+      "draft_polli_ratelimit_headers"
+      // not a valid option anymore, but we have a more specific check for this one, so don't warn for it here
+    );
+    for (const key of Object.keys(passedOptions)) {
+      if (!validOptions.includes(key)) {
+        throw new ValidationError(
+          "ERR_ERL_UNKNOWN_OPTION",
+          `Unexpected configuration option: ${key}`
+          // todo: suggest a valid option with a short levenstein distance?
+        );
+      }
+    }
+  },
   /**
    * Checks the options.validate setting to ensure that only recognized
    * validations are enabled or disabled.
    *
    * If any unrecognized values are found, an error is logged that
-   * includes the list of supported vaidations.
+   * includes the list of supported validations.
    */
   validationsConfig() {
     const supportedValidations = Object.keys(this).filter(
@@ -580,6 +635,21 @@ var validations = {
         "Custom keyGenerator appears to use request IP without calling the ipKeyGenerator helper function for IPv6 addresses. This could allow IPv6 users to bypass limits."
       );
     }
+  },
+  /**
+   * Checks to see if the window duration is greater than 2^32 - 1. This is only
+   * called by the default MemoryStore, since it uses Node's setInterval method.
+   *
+   * See https://nodejs.org/api/timers.html#setintervalcallback-delay-args.
+   */
+  windowMs(windowMs) {
+    const SET_TIMEOUT_MAX = 2 ** 31 - 1;
+    if (typeof windowMs !== "number" || Number.isNaN(windowMs) || windowMs < 1 || windowMs > SET_TIMEOUT_MAX) {
+      throw new ValidationError(
+        "ERR_ERL_WINDOW_MS",
+        `Invalid windowMs value: ${windowMs}${typeof windowMs !== "number" ? ` (${typeof windowMs})` : ""}, must be a number between 1 and ${SET_TIMEOUT_MAX} when using the default MemoryStore`
+      );
+    }
   }
 };
 var getValidations = (_enabled) => {
@@ -664,6 +734,7 @@ var parseOptions = (passedOptions) => {
   const notUndefinedOptions = omitUndefinedProperties(passedOptions);
   const validations2 = getValidations(notUndefinedOptions?.validate ?? true);
   validations2.validationsConfig();
+  validations2.knownOptions(passedOptions);
   validations2.draftPolliHeaders(
     // @ts-expect-error see the note above.
     notUndefinedOptions.draft_polli_ratelimit_headers
@@ -706,6 +777,7 @@ var parseOptions = (passedOptions) => {
       validations2.ip(request.ip);
       validations2.trustProxy(request);
       validations2.xForwardedForHeader(request);
+      validations2.forwardedHeader(request);
       const ip = request.ip;
       let subnet = 56;
       if ((0, import_node_net3.isIPv6)(ip)) {
@@ -731,7 +803,9 @@ var parseOptions = (passedOptions) => {
     standardHeaders,
     // Note that this field is declared after the user's options are spread in,
     // so that this field doesn't get overridden with an un-promisified store!
-    store: promisifyStore(notUndefinedOptions.store ?? new MemoryStore()),
+    store: promisifyStore(
+      notUndefinedOptions.store ?? new MemoryStore(validations2)
+    ),
     // Print an error to the console if a few known misconfigurations are detected.
     validations: validations2
   };

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-// Generated by dts-bundle-generator v8.0.1
+// Generated by dts-bundle-generator v8.1.2
 
 import { NextFunction, Request, RequestHandler, Response } from 'express';
 
@@ -60,6 +60,14 @@ declare const validations: {
 	 * @returns {void}
 	 */
 	xForwardedForHeader(request: Request): void;
+	/**
+	 * Alert the user if the Forwarded header is set (standardized version of X-Forwarded-For - not supported by express as of version 5.1.0)
+	 *
+	 * @param request {Request} - The Express request object.
+	 *
+	 * @returns {void}
+	 */
+	forwardedHeader(request: Request): void;
 	/**
 	 * Ensures totalHits value from store is a positive integer.
 	 *
@@ -124,12 +132,13 @@ declare const validations: {
 	 * @returns {void}
 	 */
 	headersResetTime(resetTime?: Date): void;
+	knownOptions(passedOptions?: Partial<Options>): void;
 	/**
 	 * Checks the options.validate setting to ensure that only recognized
 	 * validations are enabled or disabled.
 	 *
 	 * If any unrecognized values are found, an error is logged that
-	 * includes the list of supported vaidations.
+	 * includes the list of supported validations.
 	 */
 	validationsConfig(): void;
 	/**
@@ -141,6 +150,13 @@ declare const validations: {
 	ipv6Subnet(ipv6Subnet?: any): void;
 	ipv6SubnetOrKeyGenerator(options: Partial<Options>): void;
 	keyGeneratorIpFallback(keyGenerator?: ValueDeterminingMiddleware<string>): void;
+	/**
+	 * Checks to see if the window duration is greater than 2^32 - 1. This is only
+	 * called by the default MemoryStore, since it uses Node's setInterval method.
+	 *
+	 * See https://nodejs.org/api/timers.html#setintervalcallback-delay-args.
+	 */
+	windowMs(windowMs: number): void;
 };
 export type Validations = typeof validations;
 /**
@@ -496,6 +512,7 @@ export type Client = {
  * @public
  */
 export declare class MemoryStore implements Store {
+	private validations?;
 	/**
 	 * The duration of time before which all hit counts are reset (in milliseconds).
 	 */
@@ -521,6 +538,7 @@ export declare class MemoryStore implements Store {
 	 * cannot affect other instances.
 	 */
 	localKeys: boolean;
+	constructor(validations?: Validations | undefined);
 	/**
 	 * Method that initializes the store.
 	 *

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-// Generated by dts-bundle-generator v8.0.1
+// Generated by dts-bundle-generator v8.1.2
 
 import { NextFunction, Request, RequestHandler, Response } from 'express';
 
@@ -60,6 +60,14 @@ declare const validations: {
 	 * @returns {void}
 	 */
 	xForwardedForHeader(request: Request): void;
+	/**
+	 * Alert the user if the Forwarded header is set (standardized version of X-Forwarded-For - not supported by express as of version 5.1.0)
+	 *
+	 * @param request {Request} - The Express request object.
+	 *
+	 * @returns {void}
+	 */
+	forwardedHeader(request: Request): void;
 	/**
 	 * Ensures totalHits value from store is a positive integer.
 	 *
@@ -124,12 +132,13 @@ declare const validations: {
 	 * @returns {void}
 	 */
 	headersResetTime(resetTime?: Date): void;
+	knownOptions(passedOptions?: Partial<Options>): void;
 	/**
 	 * Checks the options.validate setting to ensure that only recognized
 	 * validations are enabled or disabled.
 	 *
 	 * If any unrecognized values are found, an error is logged that
-	 * includes the list of supported vaidations.
+	 * includes the list of supported validations.
 	 */
 	validationsConfig(): void;
 	/**
@@ -141,6 +150,13 @@ declare const validations: {
 	ipv6Subnet(ipv6Subnet?: any): void;
 	ipv6SubnetOrKeyGenerator(options: Partial<Options>): void;
 	keyGeneratorIpFallback(keyGenerator?: ValueDeterminingMiddleware<string>): void;
+	/**
+	 * Checks to see if the window duration is greater than 2^32 - 1. This is only
+	 * called by the default MemoryStore, since it uses Node's setInterval method.
+	 *
+	 * See https://nodejs.org/api/timers.html#setintervalcallback-delay-args.
+	 */
+	windowMs(windowMs: number): void;
 };
 export type Validations = typeof validations;
 /**
@@ -496,6 +512,7 @@ export type Client = {
  * @public
  */
 export declare class MemoryStore implements Store {
+	private validations?;
 	/**
 	 * The duration of time before which all hit counts are reset (in milliseconds).
 	 */
@@ -521,6 +538,7 @@ export declare class MemoryStore implements Store {
 	 * cannot affect other instances.
 	 */
 	localKeys: boolean;
+	constructor(validations?: Validations | undefined);
 	/**
 	 * Method that initializes the store.
 	 *

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// Generated by dts-bundle-generator v8.0.1
+// Generated by dts-bundle-generator v8.1.2
 
 import { NextFunction, Request, RequestHandler, Response } from 'express';
 
@@ -60,6 +60,14 @@ declare const validations: {
 	 * @returns {void}
 	 */
 	xForwardedForHeader(request: Request): void;
+	/**
+	 * Alert the user if the Forwarded header is set (standardized version of X-Forwarded-For - not supported by express as of version 5.1.0)
+	 *
+	 * @param request {Request} - The Express request object.
+	 *
+	 * @returns {void}
+	 */
+	forwardedHeader(request: Request): void;
 	/**
 	 * Ensures totalHits value from store is a positive integer.
 	 *
@@ -124,12 +132,13 @@ declare const validations: {
 	 * @returns {void}
 	 */
 	headersResetTime(resetTime?: Date): void;
+	knownOptions(passedOptions?: Partial<Options>): void;
 	/**
 	 * Checks the options.validate setting to ensure that only recognized
 	 * validations are enabled or disabled.
 	 *
 	 * If any unrecognized values are found, an error is logged that
-	 * includes the list of supported vaidations.
+	 * includes the list of supported validations.
 	 */
 	validationsConfig(): void;
 	/**
@@ -141,6 +150,13 @@ declare const validations: {
 	ipv6Subnet(ipv6Subnet?: any): void;
 	ipv6SubnetOrKeyGenerator(options: Partial<Options>): void;
 	keyGeneratorIpFallback(keyGenerator?: ValueDeterminingMiddleware<string>): void;
+	/**
+	 * Checks to see if the window duration is greater than 2^32 - 1. This is only
+	 * called by the default MemoryStore, since it uses Node's setInterval method.
+	 *
+	 * See https://nodejs.org/api/timers.html#setintervalcallback-delay-args.
+	 */
+	windowMs(windowMs: number): void;
 };
 export type Validations = typeof validations;
 /**
@@ -496,6 +512,7 @@ export type Client = {
  * @public
  */
 export declare class MemoryStore implements Store {
+	private validations?;
 	/**
 	 * The duration of time before which all hit counts are reset (in milliseconds).
 	 */
@@ -521,6 +538,7 @@ export declare class MemoryStore implements Store {
 	 * cannot affect other instances.
 	 */
 	localKeys: boolean;
+	constructor(validations?: Validations | undefined);
 	/**
 	 * Method that initializes the store.
 	 *

package/dist/index.mjs

@@ -10,7 +10,8 @@ function ipKeyGenerator(ip, ipv6Subnet = 56) {
 
 // source/memory-store.ts
 var MemoryStore = class {
-  constructor() {
+  constructor(validations2) {
+    this.validations = validations2;
     /**
      * These two maps store usage (requests) and reset time by key (for example, IP
      * addresses or API keys).
@@ -36,6 +37,7 @@ var MemoryStore = class {
    */
   init(options) {
     this.windowMs = options.windowMs;
+    this.validations?.windowMs(this.windowMs);
     if (this.interval) clearInterval(this.interval);
     this.interval = setInterval(() => {
       this.clearExpired();
@@ -208,7 +210,7 @@ var setDraft6Headers = (response, info, windowMs) => {
   response.setHeader("RateLimit-Policy", `${info.limit};w=${windowSeconds}`);
   response.setHeader("RateLimit-Limit", info.limit.toString());
   response.setHeader("RateLimit-Remaining", info.remaining.toString());
-  if (resetSeconds)
+  if (typeof resetSeconds === "number")
     response.setHeader("RateLimit-Reset", resetSeconds.toString());
 };
 var setDraft7Headers = (response, info, windowMs) => {
@@ -338,6 +340,21 @@ var validations = {
       );
     }
   },
+  /**
+   * Alert the user if the Forwarded header is set (standardized version of X-Forwarded-For - not supported by express as of version 5.1.0)
+   *
+   * @param request {Request} - The Express request object.
+   *
+   * @returns {void}
+   */
+  forwardedHeader(request) {
+    if (request.headers.forwarded && request.ip === request.socket?.remoteAddress) {
+      throw new ValidationError(
+        "ERR_ERL_FORWARDED_HEADER",
+        `The 'Forwarded' header (standardized X-Forwarded-For) is set but currently being ignored. Add a custom keyGenerator to use a value from this header.`
+      );
+    }
+  },
   /**
    * Ensures totalHits value from store is a positive integer.
    *
@@ -475,12 +492,50 @@ var validations = {
       );
     }
   },
+  knownOptions(passedOptions) {
+    if (!passedOptions) return;
+    const optionsMap = {
+      windowMs: true,
+      limit: true,
+      message: true,
+      statusCode: true,
+      legacyHeaders: true,
+      standardHeaders: true,
+      identifier: true,
+      requestPropertyName: true,
+      skipFailedRequests: true,
+      skipSuccessfulRequests: true,
+      keyGenerator: true,
+      ipv6Subnet: true,
+      handler: true,
+      skip: true,
+      requestWasSuccessful: true,
+      store: true,
+      validate: true,
+      headers: true,
+      max: true,
+      passOnStoreError: true
+    };
+    const validOptions = Object.keys(optionsMap).concat(
+      "draft_polli_ratelimit_headers"
+      // not a valid option anymore, but we have a more specific check for this one, so don't warn for it here
+    );
+    for (const key of Object.keys(passedOptions)) {
+      if (!validOptions.includes(key)) {
+        throw new ValidationError(
+          "ERR_ERL_UNKNOWN_OPTION",
+          `Unexpected configuration option: ${key}`
+          // todo: suggest a valid option with a short levenstein distance?
+        );
+      }
+    }
+  },
   /**
    * Checks the options.validate setting to ensure that only recognized
    * validations are enabled or disabled.
    *
    * If any unrecognized values are found, an error is logged that
-   * includes the list of supported vaidations.
+   * includes the list of supported validations.
    */
   validationsConfig() {
     const supportedValidations = Object.keys(this).filter(
@@ -551,6 +606,21 @@ var validations = {
         "Custom keyGenerator appears to use request IP without calling the ipKeyGenerator helper function for IPv6 addresses. This could allow IPv6 users to bypass limits."
       );
     }
+  },
+  /**
+   * Checks to see if the window duration is greater than 2^32 - 1. This is only
+   * called by the default MemoryStore, since it uses Node's setInterval method.
+   *
+   * See https://nodejs.org/api/timers.html#setintervalcallback-delay-args.
+   */
+  windowMs(windowMs) {
+    const SET_TIMEOUT_MAX = 2 ** 31 - 1;
+    if (typeof windowMs !== "number" || Number.isNaN(windowMs) || windowMs < 1 || windowMs > SET_TIMEOUT_MAX) {
+      throw new ValidationError(
+        "ERR_ERL_WINDOW_MS",
+        `Invalid windowMs value: ${windowMs}${typeof windowMs !== "number" ? ` (${typeof windowMs})` : ""}, must be a number between 1 and ${SET_TIMEOUT_MAX} when using the default MemoryStore`
+      );
+    }
   }
 };
 var getValidations = (_enabled) => {
@@ -635,6 +705,7 @@ var parseOptions = (passedOptions) => {
   const notUndefinedOptions = omitUndefinedProperties(passedOptions);
   const validations2 = getValidations(notUndefinedOptions?.validate ?? true);
   validations2.validationsConfig();
+  validations2.knownOptions(passedOptions);
   validations2.draftPolliHeaders(
     // @ts-expect-error see the note above.
     notUndefinedOptions.draft_polli_ratelimit_headers
@@ -677,6 +748,7 @@ var parseOptions = (passedOptions) => {
       validations2.ip(request.ip);
       validations2.trustProxy(request);
       validations2.xForwardedForHeader(request);
+      validations2.forwardedHeader(request);
       const ip = request.ip;
       let subnet = 56;
       if (isIPv62(ip)) {
@@ -702,7 +774,9 @@ var parseOptions = (passedOptions) => {
     standardHeaders,
     // Note that this field is declared after the user's options are spread in,
     // so that this field doesn't get overridden with an un-promisified store!
-    store: promisifyStore(notUndefinedOptions.store ?? new MemoryStore()),
+    store: promisifyStore(
+      notUndefinedOptions.store ?? new MemoryStore(validations2)
+    ),
     // Print an error to the console if a few known misconfigurations are detected.
     validations: validations2
   };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "express-rate-limit",
-	"version": "8.0.1",
+	"version": "8.2.0",
 	"description": "Basic IP rate-limiting middleware for Express. Use to limit repeated requests to public APIs and/or endpoints such as password reset.",
 	"author": {
 		"name": "Nathan Friedly",
@@ -77,29 +77,29 @@
 		"express": ">= 4.11"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.1.1",
+		"@biomejs/biome": "2.3.1",
 		"@express-rate-limit/prettier": "1.1.1",
 		"@express-rate-limit/tsconfig": "1.0.2",
-		"@jest/globals": "30.0.4",
-		"@types/express": "5.0.3",
+		"@jest/globals": "30.2.0",
+		"@types/express": "5.0.4",
 		"@types/jest": "30.0.0",
-		"@types/node": "24.0.14",
+		"@types/node": "24.9.1",
 		"@types/supertest": "6.0.3",
 		"del-cli": "6.0.0",
-		"dts-bundle-generator": "8.0.1",
-		"esbuild": "0.25.6",
+		"dts-bundle-generator": "8.1.2",
+		"esbuild": "0.25.11",
 		"express": "5.1.0",
 		"husky": "9.1.7",
-		"jest": "30.0.4",
-		"lint-staged": "16.1.2",
-		"mintlify": "4.2.15",
+		"jest": "30.2.0",
+		"lint-staged": "16.2.6",
+		"mintlify": "4.2.179",
 		"npm-run-all": "4.1.5",
 		"prettier": "3.6.2",
 		"ratelimit-header-parser": "0.1.0",
-		"supertest": "7.1.3",
-		"ts-jest": "29.4.0",
+		"supertest": "7.1.4",
+		"ts-jest": "29.4.5",
 		"ts-node": "10.9.2",
-		"typescript": "5.8.3"
+		"typescript": "5.9.3"
 	},
 	"prettier": "@express-rate-limit/prettier",
 	"lint-staged": {