express-rate-limit 6.7.1 → 6.8.0

package/changelog.md

@@ -6,6 +6,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.8.0](https://github.com/express-rate-limit/express-rate-limit/releases/tag/v6.8.0)
+
+### Changed
+
+- Added a set of validation checks to execute on the first request. (See
+  [#358](https://github.com/express-rate-limit/express-rate-limit/issues/358))
+
 ## [6.7.1](https://github.com/express-rate-limit/express-rate-limit/releases/tag/v6.7.1)
 
 ### Fixed

package/dist/index.cjs

@@ -31,6 +31,116 @@ __export(source_exports, {
 });
 module.exports = __toCommonJS(source_exports);
 
+// source/validations.ts
+var import_node_net = require("net");
+var ValidationError = class extends Error {
+  /**
+   * The code must be a string, in snake case and all capital, that starts with
+   * the substring `ERR_ERL_`.
+   *
+   * The message must be a string, starting with a lowercase character,
+   * describing the issue in detail.
+   */
+  constructor(code, message) {
+    super(
+      `express-rate-limit: ${code} - ${message} See https://github.com/express-rate-limit/express-rate-limit/wiki/Error-Codes#${code.toLowerCase()} for more information on this error.`
+    );
+    __publicField(this, "name");
+    __publicField(this, "code");
+    this.name = this.constructor.name;
+    this.code = code;
+    this.message = message;
+  }
+};
+var Validations = class {
+  constructor(enabled) {
+    // eslint-disable-next-line @typescript-eslint/parameter-properties
+    __publicField(this, "enabled");
+    this.enabled = enabled;
+  }
+  enable() {
+    this.enabled = true;
+  }
+  disable() {
+    this.enabled = false;
+  }
+  /**
+   * Checks whether the IP address is valid, and that it does not have a port
+   * number in it.
+   *
+   * See https://github.com/express-rate-limit/express-rate-limit/wiki/Error-Codes#err_erl_invalid_ip_address.
+   *
+   * @param ip {string | undefined} - The IP address provided by Express as request.ip.
+   *
+   * @returns {void}
+   */
+  ip(ip) {
+    this.wrap(() => {
+      if (ip === void 0) {
+        throw new ValidationError(
+          "ERR_ERL_UNDEFINED_IP_ADDRESS",
+          `An undefined 'request.ip' was detected. This might indicate a misconfiguration or the connection being destroyed prematurely.`
+        );
+      }
+      if (!(0, import_node_net.isIP)(ip)) {
+        throw new ValidationError(
+          "ERR_ERL_INVALID_IP_ADDRESS",
+          `An invalid 'request.ip' (${ip}) was detected. Consider passing a custom 'keyGenerator' function to the rate limiter.`
+        );
+      }
+    });
+  }
+  /**
+   * Makes sure the trust proxy setting is not set to `true`.
+   *
+   * See https://github.com/express-rate-limit/express-rate-limit/wiki/Error-Codes#err_erl_permissive_trust_proxy.
+   *
+   * @param request {Request} - The Express request object.
+   *
+   * @returns {void}
+   */
+  trustProxy(request) {
+    this.wrap(() => {
+      if (request.app.get("trust proxy") === true) {
+        throw new ValidationError(
+          "ERR_ERL_PERMISSIVE_TRUST_PROXY",
+          `The Express 'trust proxy' setting is true, which allows anyone to trivially bypass IP-based rate limiting.`
+        );
+      }
+    });
+  }
+  /**
+   * Makes sure the trust proxy setting is set in case the `X-Forwarded-For`
+   * header is present.
+   *
+   * See https://github.com/express-rate-limit/express-rate-limit/wiki/Error-Codes#err_erl_unset_trust_proxy.
+   *
+   * @param request {Request} - The Express request object.
+   *
+   * @returns {void}
+   */
+  xForwardedForHeader(request) {
+    this.wrap(() => {
+      if (request.headers["x-forwarded-for"] && request.app.get("trust proxy") === false) {
+        throw new ValidationError(
+          "ERR_ERL_UNEXPECTED_X_FORWARDED_FOR",
+          `The 'X-Forwarded-For' header is set but the Express 'trust proxy' setting is false (default). This could indicate a misconfiguration which would prevent express-rate-limit from accurately identifying users.`
+        );
+      }
+    });
+  }
+  wrap(validation) {
+    if (!this.enabled) {
+      return;
+    }
+    try {
+      validation.call(this);
+    } catch (error) {
+      console.error(error);
+    }
+  }
+};
+
 // source/memory-store.ts
 var calculateNextResetTime = (windowMs) => {
   const resetTime = /* @__PURE__ */ new Date();
@@ -168,27 +278,43 @@ var promisifyStore = (passedStore) => {
   }
   return new PromisifiedStore();
 };
+var getOptionsFromConfig = (config) => {
+  const { validations, ...directlyPassableEntries } = config;
+  return {
+    ...directlyPassableEntries,
+    validate: validations.enabled
+  };
+};
+var omitUndefinedOptions = (passedOptions) => {
+  const omittedOptions = {};
+  for (const k of Object.keys(passedOptions)) {
+    const key = k;
+    if (passedOptions[key] !== void 0) {
+      omittedOptions[key] = passedOptions[key];
+    }
+  }
+  return omittedOptions;
+};
 var parseOptions = (passedOptions) => {
-  var _a, _b, _c;
+  var _a, _b, _c, _d;
   const notUndefinedOptions = omitUndefinedOptions(passedOptions);
+  const validations = new Validations((_a = notUndefinedOptions == null ? void 0 : notUndefinedOptions.validate) != null ? _a : true);
   const config = {
     windowMs: 60 * 1e3,
     max: 5,
     message: "Too many requests, please try again later.",
     statusCode: 429,
-    legacyHeaders: (_a = passedOptions.headers) != null ? _a : true,
-    standardHeaders: (_b = passedOptions.draft_polli_ratelimit_headers) != null ? _b : false,
+    legacyHeaders: (_b = passedOptions.headers) != null ? _b : true,
+    standardHeaders: (_c = passedOptions.draft_polli_ratelimit_headers) != null ? _c : false,
     requestPropertyName: "rateLimit",
     skipFailedRequests: false,
     skipSuccessfulRequests: false,
     requestWasSuccessful: (_request, response) => response.statusCode < 400,
     skip: (_request, _response) => false,
     keyGenerator(request, _response) {
-      if (!request.ip) {
-        console.error(
-          "WARN | `express-rate-limit` | `request.ip` is undefined. You can avoid this by providing a custom `keyGenerator` function, but it may be indicative of a larger issue."
-        );
-      }
+      validations.ip(request.ip);
+      validations.trustProxy(request);
+      validations.xForwardedForHeader(request);
       return request.ip;
     },
     async handler(request, response, _next, _optionsUsed) {
@@ -207,7 +333,9 @@ var parseOptions = (passedOptions) => {
     ...notUndefinedOptions,
     // Note that this field is declared after the user's options are spread in,
     // so that this field doesn't get overriden with an un-promisified store!
-    store: promisifyStore((_c = notUndefinedOptions.store) != null ? _c : new MemoryStore())
+    store: promisifyStore((_d = notUndefinedOptions.store) != null ? _d : new MemoryStore()),
+    // Print an error to the console if a few known misconfigurations are detected.
+    validations
   };
   if (typeof config.store.increment !== "function" || typeof config.store.decrement !== "function" || typeof config.store.resetKey !== "function" || config.store.resetAll !== void 0 && typeof config.store.resetAll !== "function" || config.store.init !== void 0 && typeof config.store.init !== "function") {
     throw new TypeError(
@@ -224,32 +352,33 @@ var handleAsyncErrors = (fn) => async (request, response, next) => {
   }
 };
 var rateLimit = (passedOptions) => {
-  const options = parseOptions(passedOptions != null ? passedOptions : {});
-  if (typeof options.store.init === "function")
-    options.store.init(options);
+  const config = parseOptions(passedOptions != null ? passedOptions : {});
+  const options = getOptionsFromConfig(config);
+  if (typeof config.store.init === "function")
+    config.store.init(options);
   const middleware = handleAsyncErrors(
     async (request, response, next) => {
-      const skip = await options.skip(request, response);
+      const skip = await config.skip(request, response);
       if (skip) {
         next();
         return;
       }
       const augmentedRequest = request;
-      const key = await options.keyGenerator(request, response);
-      const { totalHits, resetTime } = await options.store.increment(key);
-      const retrieveQuota = typeof options.max === "function" ? options.max(request, response) : options.max;
+      const key = await config.keyGenerator(request, response);
+      const { totalHits, resetTime } = await config.store.increment(key);
+      const retrieveQuota = typeof config.max === "function" ? config.max(request, response) : config.max;
       const maxHits = await retrieveQuota;
-      augmentedRequest[options.requestPropertyName] = {
+      augmentedRequest[config.requestPropertyName] = {
         limit: maxHits,
         current: totalHits,
         remaining: Math.max(maxHits - totalHits, 0),
         resetTime
       };
-      if (options.legacyHeaders && !response.headersSent) {
+      if (config.legacyHeaders && !response.headersSent) {
         response.setHeader("X-RateLimit-Limit", maxHits);
         response.setHeader(
           "X-RateLimit-Remaining",
-          augmentedRequest[options.requestPropertyName].remaining
+          augmentedRequest[config.requestPropertyName].remaining
         );
         if (resetTime instanceof Date) {
           response.setHeader("Date", (/* @__PURE__ */ new Date()).toUTCString());
@@ -259,11 +388,11 @@ var rateLimit = (passedOptions) => {
           );
         }
       }
-      if (options.standardHeaders && !response.headersSent) {
+      if (config.standardHeaders && !response.headersSent) {
         response.setHeader("RateLimit-Limit", maxHits);
         response.setHeader(
           "RateLimit-Remaining",
-          augmentedRequest[options.requestPropertyName].remaining
+          augmentedRequest[config.requestPropertyName].remaining
         );
         if (resetTime) {
           const deltaSeconds = Math.ceil(
@@ -272,17 +401,17 @@ var rateLimit = (passedOptions) => {
           response.setHeader("RateLimit-Reset", Math.max(0, deltaSeconds));
         }
       }
-      if (options.skipFailedRequests || options.skipSuccessfulRequests) {
+      if (config.skipFailedRequests || config.skipSuccessfulRequests) {
         let decremented = false;
         const decrementKey = async () => {
           if (!decremented) {
-            await options.store.decrement(key);
+            await config.store.decrement(key);
             decremented = true;
           }
         };
-        if (options.skipFailedRequests) {
+        if (config.skipFailedRequests) {
           response.on("finish", async () => {
-            if (!options.requestWasSuccessful(request, response))
+            if (!config.requestWasSuccessful(request, response))
               await decrementKey();
           });
           response.on("close", async () => {
@@ -293,38 +422,34 @@ var rateLimit = (passedOptions) => {
             await decrementKey();
           });
         }
-        if (options.skipSuccessfulRequests) {
+        if (config.skipSuccessfulRequests) {
           response.on("finish", async () => {
-            if (options.requestWasSuccessful(request, response))
+            if (config.requestWasSuccessful(request, response))
               await decrementKey();
           });
         }
       }
       if (maxHits && totalHits === maxHits + 1) {
-        options.onLimitReached(request, response, options);
+        config.onLimitReached(request, response, options);
       }
+      config.validations.disable();
       if (maxHits && totalHits > maxHits) {
-        if ((options.legacyHeaders || options.standardHeaders) && !response.headersSent) {
-          response.setHeader("Retry-After", Math.ceil(options.windowMs / 1e3));
+        if ((config.legacyHeaders || config.standardHeaders) && !response.headersSent) {
+          response.setHeader("Retry-After", Math.ceil(config.windowMs / 1e3));
         }
-        options.handler(request, response, next, options);
+        config.handler(request, response, next, options);
         return;
       }
       next();
     }
   );
-  middleware.resetKey = options.store.resetKey.bind(options.store);
+  middleware.resetKey = config.store.resetKey.bind(config.store);
   return middleware;
 };
-var omitUndefinedOptions = (passedOptions) => {
-  const omittedOptions = {};
-  for (const k of Object.keys(passedOptions)) {
-    const key = k;
-    if (passedOptions[key] !== void 0) {
-      omittedOptions[key] = passedOptions[key];
-    }
-  }
-  return omittedOptions;
-};
 var lib_default = rateLimit;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MemoryStore,
+  rateLimit
+});
 module.exports = rateLimit; module.exports.default = rateLimit; module.exports.rateLimit = rateLimit; module.exports.MemoryStore = MemoryStore;

package/dist/index.d.cts

@@ -140,7 +140,7 @@ export type Options = {
 	 *
 	 * Defaults to `60000` ms (= 1 minute).
 	 */
-	readonly windowMs: number;
+	windowMs: number;
 	/**
 	 * The maximum number of connections to allow during the `window` before
 	 * rate limiting the client.
@@ -150,65 +150,65 @@ export type Options = {
 	 *
 	 * Defaults to `5`.
 	 */
-	readonly max: number | ValueDeterminingMiddleware<number>;
+	max: number | ValueDeterminingMiddleware<number>;
 	/**
 	 * The response body to send back when a client is rate limited.
 	 *
 	 * Defaults to `'Too many requests, please try again later.'`
 	 */
-	readonly message: any | ValueDeterminingMiddleware<any>;
+	message: any | ValueDeterminingMiddleware<any>;
 	/**
 	 * The HTTP status code to send back when a client is rate limited.
 	 *
 	 * Defaults to `HTTP 429 Too Many Requests` (RFC 6585).
 	 */
-	readonly statusCode: number;
+	statusCode: number;
 	/**
 	 * Whether to send `X-RateLimit-*` headers with the rate limit and the number
 	 * of requests.
 	 *
 	 * Defaults to `true` (for backward compatibility).
 	 */
-	readonly legacyHeaders: boolean;
+	legacyHeaders: boolean;
 	/**
 	 * Whether to enable support for the standardized rate limit headers (`RateLimit-*`).
 	 *
 	 * Defaults to `false` (for backward compatibility, but its use is recommended).
 	 */
-	readonly standardHeaders: boolean;
+	standardHeaders: boolean;
 	/**
 	 * The name of the property on the request object to store the rate limit info.
 	 *
 	 * Defaults to `rateLimit`.
 	 */
-	readonly requestPropertyName: string;
+	requestPropertyName: string;
 	/**
 	 * If `true`, the library will (by default) skip all requests that have a 4XX
 	 * or 5XX status.
 	 *
 	 * Defaults to `false`.
 	 */
-	readonly skipFailedRequests: boolean;
+	skipFailedRequests: boolean;
 	/**
 	 * If `true`, the library will (by default) skip all requests that have a
 	 * status code less than 400.
 	 *
 	 * Defaults to `false`.
 	 */
-	readonly skipSuccessfulRequests: boolean;
+	skipSuccessfulRequests: boolean;
 	/**
 	 * Method to generate custom identifiers for clients.
 	 *
 	 * By default, the client's IP address is used.
 	 */
-	readonly keyGenerator: ValueDeterminingMiddleware<string>;
+	keyGenerator: ValueDeterminingMiddleware<string>;
 	/**
 	 * Express request handler that sends back a response when a client is
 	 * rate-limited.
 	 *
 	 * By default, sends back the `statusCode` and `message` set via the options.
 	 */
-	readonly handler: RateLimitExceededEventHandler;
+	handler: RateLimitExceededEventHandler;
 	/**
 	 * Express request handler that sends back a response when a client has
 	 * reached their rate limit, and will be rate limited on their next request.
@@ -216,14 +216,14 @@ export type Options = {
 	 * @deprecated 6.x - Please use a custom `handler` that checks the number of
 	 * hits instead.
 	 */
-	readonly onLimitReached: RateLimitReachedEventHandler;
+	onLimitReached: RateLimitReachedEventHandler;
 	/**
 	 * Method (in the form of middleware) to determine whether or not this request
 	 * counts towards a client's quota.
 	 *
 	 * By default, skips no requests.
 	 */
-	readonly skip: ValueDeterminingMiddleware<boolean>;
+	skip: ValueDeterminingMiddleware<boolean>;
 	/**
 	 * Method to determine whether or not the request counts as 'succesful'. Used
 	 * when either `skipSuccessfulRequests` or `skipFailedRequests` is set to true.
@@ -231,13 +231,17 @@ export type Options = {
 	 * By default, requests with a response status code less than 400 are considered
 	 * successful.
 	 */
-	readonly requestWasSuccessful: ValueDeterminingMiddleware<boolean>;
+	requestWasSuccessful: ValueDeterminingMiddleware<boolean>;
 	/**
 	 * The `Store` to use to store the hit count for each client.
 	 *
 	 * By default, the built-in `MemoryStore` will be used.
 	 */
 	store: Store | LegacyStore;
+	/**
+	 * Whether or not the validation checks should run.
+	 */
+	validate: boolean;
 	/**
 	 * Whether to send `X-RateLimit-*` headers with the rate limit and the number
 	 * of requests.
@@ -265,10 +269,10 @@ export type AugmentedRequest = Request & {
  * Express request object.
  */
 export type RateLimitInfo = {
-	readonly limit: number;
-	readonly current: number;
-	readonly remaining: number;
-	readonly resetTime: Date | undefined;
+	limit: number;
+	current: number;
+	remaining: number;
+	resetTime: Date | undefined;
 };
 /**
  *

package/dist/index.d.mts

@@ -140,7 +140,7 @@ export type Options = {
 	 *
 	 * Defaults to `60000` ms (= 1 minute).
 	 */
-	readonly windowMs: number;
+	windowMs: number;
 	/**
 	 * The maximum number of connections to allow during the `window` before
 	 * rate limiting the client.
@@ -150,65 +150,65 @@ export type Options = {
 	 *
 	 * Defaults to `5`.
 	 */
-	readonly max: number | ValueDeterminingMiddleware<number>;
+	max: number | ValueDeterminingMiddleware<number>;
 	/**
 	 * The response body to send back when a client is rate limited.
 	 *
 	 * Defaults to `'Too many requests, please try again later.'`
 	 */
-	readonly message: any | ValueDeterminingMiddleware<any>;
+	message: any | ValueDeterminingMiddleware<any>;
 	/**
 	 * The HTTP status code to send back when a client is rate limited.
 	 *
 	 * Defaults to `HTTP 429 Too Many Requests` (RFC 6585).
 	 */
-	readonly statusCode: number;
+	statusCode: number;
 	/**
 	 * Whether to send `X-RateLimit-*` headers with the rate limit and the number
 	 * of requests.
 	 *
 	 * Defaults to `true` (for backward compatibility).
 	 */
-	readonly legacyHeaders: boolean;
+	legacyHeaders: boolean;
 	/**
 	 * Whether to enable support for the standardized rate limit headers (`RateLimit-*`).
 	 *
 	 * Defaults to `false` (for backward compatibility, but its use is recommended).
 	 */
-	readonly standardHeaders: boolean;
+	standardHeaders: boolean;
 	/**
 	 * The name of the property on the request object to store the rate limit info.
 	 *
 	 * Defaults to `rateLimit`.
 	 */
-	readonly requestPropertyName: string;
+	requestPropertyName: string;
 	/**
 	 * If `true`, the library will (by default) skip all requests that have a 4XX
 	 * or 5XX status.
 	 *
 	 * Defaults to `false`.
 	 */
-	readonly skipFailedRequests: boolean;
+	skipFailedRequests: boolean;
 	/**
 	 * If `true`, the library will (by default) skip all requests that have a
 	 * status code less than 400.
 	 *
 	 * Defaults to `false`.
 	 */
-	readonly skipSuccessfulRequests: boolean;
+	skipSuccessfulRequests: boolean;
 	/**
 	 * Method to generate custom identifiers for clients.
 	 *
 	 * By default, the client's IP address is used.
 	 */
-	readonly keyGenerator: ValueDeterminingMiddleware<string>;
+	keyGenerator: ValueDeterminingMiddleware<string>;
 	/**
 	 * Express request handler that sends back a response when a client is
 	 * rate-limited.
 	 *
 	 * By default, sends back the `statusCode` and `message` set via the options.
 	 */
-	readonly handler: RateLimitExceededEventHandler;
+	handler: RateLimitExceededEventHandler;
 	/**
 	 * Express request handler that sends back a response when a client has
 	 * reached their rate limit, and will be rate limited on their next request.
@@ -216,14 +216,14 @@ export type Options = {
 	 * @deprecated 6.x - Please use a custom `handler` that checks the number of
 	 * hits instead.
 	 */
-	readonly onLimitReached: RateLimitReachedEventHandler;
+	onLimitReached: RateLimitReachedEventHandler;
 	/**
 	 * Method (in the form of middleware) to determine whether or not this request
 	 * counts towards a client's quota.
 	 *
 	 * By default, skips no requests.
 	 */
-	readonly skip: ValueDeterminingMiddleware<boolean>;
+	skip: ValueDeterminingMiddleware<boolean>;
 	/**
 	 * Method to determine whether or not the request counts as 'succesful'. Used
 	 * when either `skipSuccessfulRequests` or `skipFailedRequests` is set to true.
@@ -231,13 +231,17 @@ export type Options = {
 	 * By default, requests with a response status code less than 400 are considered
 	 * successful.
 	 */
-	readonly requestWasSuccessful: ValueDeterminingMiddleware<boolean>;
+	requestWasSuccessful: ValueDeterminingMiddleware<boolean>;
 	/**
 	 * The `Store` to use to store the hit count for each client.
 	 *
 	 * By default, the built-in `MemoryStore` will be used.
 	 */
 	store: Store | LegacyStore;
+	/**
+	 * Whether or not the validation checks should run.
+	 */
+	validate: boolean;
 	/**
 	 * Whether to send `X-RateLimit-*` headers with the rate limit and the number
 	 * of requests.
@@ -265,10 +269,10 @@ export type AugmentedRequest = Request & {
  * Express request object.
  */
 export type RateLimitInfo = {
-	readonly limit: number;
-	readonly current: number;
-	readonly remaining: number;
-	readonly resetTime: Date | undefined;
+	limit: number;
+	current: number;
+	remaining: number;
+	resetTime: Date | undefined;
 };
 /**
  *

package/dist/index.d.ts

@@ -140,7 +140,7 @@ export type Options = {
 	 *
 	 * Defaults to `60000` ms (= 1 minute).
 	 */
-	readonly windowMs: number;
+	windowMs: number;
 	/**
 	 * The maximum number of connections to allow during the `window` before
 	 * rate limiting the client.
@@ -150,65 +150,65 @@ export type Options = {
 	 *
 	 * Defaults to `5`.
 	 */
-	readonly max: number | ValueDeterminingMiddleware<number>;
+	max: number | ValueDeterminingMiddleware<number>;
 	/**
 	 * The response body to send back when a client is rate limited.
 	 *
 	 * Defaults to `'Too many requests, please try again later.'`
 	 */
-	readonly message: any | ValueDeterminingMiddleware<any>;
+	message: any | ValueDeterminingMiddleware<any>;
 	/**
 	 * The HTTP status code to send back when a client is rate limited.
 	 *
 	 * Defaults to `HTTP 429 Too Many Requests` (RFC 6585).
 	 */
-	readonly statusCode: number;
+	statusCode: number;
 	/**
 	 * Whether to send `X-RateLimit-*` headers with the rate limit and the number
 	 * of requests.
 	 *
 	 * Defaults to `true` (for backward compatibility).
 	 */
-	readonly legacyHeaders: boolean;
+	legacyHeaders: boolean;
 	/**
 	 * Whether to enable support for the standardized rate limit headers (`RateLimit-*`).
 	 *
 	 * Defaults to `false` (for backward compatibility, but its use is recommended).
 	 */
-	readonly standardHeaders: boolean;
+	standardHeaders: boolean;
 	/**
 	 * The name of the property on the request object to store the rate limit info.
 	 *
 	 * Defaults to `rateLimit`.
 	 */
-	readonly requestPropertyName: string;
+	requestPropertyName: string;
 	/**
 	 * If `true`, the library will (by default) skip all requests that have a 4XX
 	 * or 5XX status.
 	 *
 	 * Defaults to `false`.
 	 */
-	readonly skipFailedRequests: boolean;
+	skipFailedRequests: boolean;
 	/**
 	 * If `true`, the library will (by default) skip all requests that have a
 	 * status code less than 400.
 	 *
 	 * Defaults to `false`.
 	 */
-	readonly skipSuccessfulRequests: boolean;
+	skipSuccessfulRequests: boolean;
 	/**
 	 * Method to generate custom identifiers for clients.
 	 *
 	 * By default, the client's IP address is used.
 	 */
-	readonly keyGenerator: ValueDeterminingMiddleware<string>;
+	keyGenerator: ValueDeterminingMiddleware<string>;
 	/**
 	 * Express request handler that sends back a response when a client is
 	 * rate-limited.
 	 *
 	 * By default, sends back the `statusCode` and `message` set via the options.
 	 */
-	readonly handler: RateLimitExceededEventHandler;
+	handler: RateLimitExceededEventHandler;
 	/**
 	 * Express request handler that sends back a response when a client has
 	 * reached their rate limit, and will be rate limited on their next request.
@@ -216,14 +216,14 @@ export type Options = {
 	 * @deprecated 6.x - Please use a custom `handler` that checks the number of
 	 * hits instead.
 	 */
-	readonly onLimitReached: RateLimitReachedEventHandler;
+	onLimitReached: RateLimitReachedEventHandler;
 	/**
 	 * Method (in the form of middleware) to determine whether or not this request
 	 * counts towards a client's quota.
 	 *
 	 * By default, skips no requests.
 	 */
-	readonly skip: ValueDeterminingMiddleware<boolean>;
+	skip: ValueDeterminingMiddleware<boolean>;
 	/**
 	 * Method to determine whether or not the request counts as 'succesful'. Used
 	 * when either `skipSuccessfulRequests` or `skipFailedRequests` is set to true.
@@ -231,13 +231,17 @@ export type Options = {
 	 * By default, requests with a response status code less than 400 are considered
 	 * successful.
 	 */
-	readonly requestWasSuccessful: ValueDeterminingMiddleware<boolean>;
+	requestWasSuccessful: ValueDeterminingMiddleware<boolean>;
 	/**
 	 * The `Store` to use to store the hit count for each client.
 	 *
 	 * By default, the built-in `MemoryStore` will be used.
 	 */
 	store: Store | LegacyStore;
+	/**
+	 * Whether or not the validation checks should run.
+	 */
+	validate: boolean;
 	/**
 	 * Whether to send `X-RateLimit-*` headers with the rate limit and the number
 	 * of requests.
@@ -265,10 +269,10 @@ export type AugmentedRequest = Request & {
  * Express request object.
  */
 export type RateLimitInfo = {
-	readonly limit: number;
-	readonly current: number;
-	readonly remaining: number;
-	readonly resetTime: Date | undefined;
+	limit: number;
+	current: number;
+	remaining: number;
+	resetTime: Date | undefined;
 };
 /**
  *

package/dist/index.mjs

@@ -5,6 +5,116 @@ var __publicField = (obj, key, value) => {
   return value;
 };
 
+// source/validations.ts
+import { isIP } from "net";
+var ValidationError = class extends Error {
+  /**
+   * The code must be a string, in snake case and all capital, that starts with
+   * the substring `ERR_ERL_`.
+   *
+   * The message must be a string, starting with a lowercase character,
+   * describing the issue in detail.
+   */
+  constructor(code, message) {
+    super(
+      `express-rate-limit: ${code} - ${message} See https://github.com/express-rate-limit/express-rate-limit/wiki/Error-Codes#${code.toLowerCase()} for more information on this error.`
+    );
+    __publicField(this, "name");
+    __publicField(this, "code");
+    this.name = this.constructor.name;
+    this.code = code;
+    this.message = message;
+  }
+};
+var Validations = class {
+  constructor(enabled) {
+    // eslint-disable-next-line @typescript-eslint/parameter-properties
+    __publicField(this, "enabled");
+    this.enabled = enabled;
+  }
+  enable() {
+    this.enabled = true;
+  }
+  disable() {
+    this.enabled = false;
+  }
+  /**
+   * Checks whether the IP address is valid, and that it does not have a port
+   * number in it.
+   *
+   * See https://github.com/express-rate-limit/express-rate-limit/wiki/Error-Codes#err_erl_invalid_ip_address.
+   *
+   * @param ip {string | undefined} - The IP address provided by Express as request.ip.
+   *
+   * @returns {void}
+   */
+  ip(ip) {
+    this.wrap(() => {
+      if (ip === void 0) {
+        throw new ValidationError(
+          "ERR_ERL_UNDEFINED_IP_ADDRESS",
+          `An undefined 'request.ip' was detected. This might indicate a misconfiguration or the connection being destroyed prematurely.`
+        );
+      }
+      if (!isIP(ip)) {
+        throw new ValidationError(
+          "ERR_ERL_INVALID_IP_ADDRESS",
+          `An invalid 'request.ip' (${ip}) was detected. Consider passing a custom 'keyGenerator' function to the rate limiter.`
+        );
+      }
+    });
+  }
+  /**
+   * Makes sure the trust proxy setting is not set to `true`.
+   *
+   * See https://github.com/express-rate-limit/express-rate-limit/wiki/Error-Codes#err_erl_permissive_trust_proxy.
+   *
+   * @param request {Request} - The Express request object.
+   *
+   * @returns {void}
+   */
+  trustProxy(request) {
+    this.wrap(() => {
+      if (request.app.get("trust proxy") === true) {
+        throw new ValidationError(
+          "ERR_ERL_PERMISSIVE_TRUST_PROXY",
+          `The Express 'trust proxy' setting is true, which allows anyone to trivially bypass IP-based rate limiting.`
+        );
+      }
+    });
+  }
+  /**
+   * Makes sure the trust proxy setting is set in case the `X-Forwarded-For`
+   * header is present.
+   *
+   * See https://github.com/express-rate-limit/express-rate-limit/wiki/Error-Codes#err_erl_unset_trust_proxy.
+   *
+   * @param request {Request} - The Express request object.
+   *
+   * @returns {void}
+   */
+  xForwardedForHeader(request) {
+    this.wrap(() => {
+      if (request.headers["x-forwarded-for"] && request.app.get("trust proxy") === false) {
+        throw new ValidationError(
+          "ERR_ERL_UNEXPECTED_X_FORWARDED_FOR",
+          `The 'X-Forwarded-For' header is set but the Express 'trust proxy' setting is false (default). This could indicate a misconfiguration which would prevent express-rate-limit from accurately identifying users.`
+        );
+      }
+    });
+  }
+  wrap(validation) {
+    if (!this.enabled) {
+      return;
+    }
+    try {
+      validation.call(this);
+    } catch (error) {
+      console.error(error);
+    }
+  }
+};
+
 // source/memory-store.ts
 var calculateNextResetTime = (windowMs) => {
   const resetTime = /* @__PURE__ */ new Date();
@@ -142,27 +252,43 @@ var promisifyStore = (passedStore) => {
   }
   return new PromisifiedStore();
 };
+var getOptionsFromConfig = (config) => {
+  const { validations, ...directlyPassableEntries } = config;
+  return {
+    ...directlyPassableEntries,
+    validate: validations.enabled
+  };
+};
+var omitUndefinedOptions = (passedOptions) => {
+  const omittedOptions = {};
+  for (const k of Object.keys(passedOptions)) {
+    const key = k;
+    if (passedOptions[key] !== void 0) {
+      omittedOptions[key] = passedOptions[key];
+    }
+  }
+  return omittedOptions;
+};
 var parseOptions = (passedOptions) => {
-  var _a, _b, _c;
+  var _a, _b, _c, _d;
   const notUndefinedOptions = omitUndefinedOptions(passedOptions);
+  const validations = new Validations((_a = notUndefinedOptions == null ? void 0 : notUndefinedOptions.validate) != null ? _a : true);
   const config = {
     windowMs: 60 * 1e3,
     max: 5,
     message: "Too many requests, please try again later.",
     statusCode: 429,
-    legacyHeaders: (_a = passedOptions.headers) != null ? _a : true,
-    standardHeaders: (_b = passedOptions.draft_polli_ratelimit_headers) != null ? _b : false,
+    legacyHeaders: (_b = passedOptions.headers) != null ? _b : true,
+    standardHeaders: (_c = passedOptions.draft_polli_ratelimit_headers) != null ? _c : false,
     requestPropertyName: "rateLimit",
     skipFailedRequests: false,
     skipSuccessfulRequests: false,
     requestWasSuccessful: (_request, response) => response.statusCode < 400,
     skip: (_request, _response) => false,
     keyGenerator(request, _response) {
-      if (!request.ip) {
-        console.error(
-          "WARN | `express-rate-limit` | `request.ip` is undefined. You can avoid this by providing a custom `keyGenerator` function, but it may be indicative of a larger issue."
-        );
-      }
+      validations.ip(request.ip);
+      validations.trustProxy(request);
+      validations.xForwardedForHeader(request);
       return request.ip;
     },
     async handler(request, response, _next, _optionsUsed) {
@@ -181,7 +307,9 @@ var parseOptions = (passedOptions) => {
     ...notUndefinedOptions,
     // Note that this field is declared after the user's options are spread in,
     // so that this field doesn't get overriden with an un-promisified store!
-    store: promisifyStore((_c = notUndefinedOptions.store) != null ? _c : new MemoryStore())
+    store: promisifyStore((_d = notUndefinedOptions.store) != null ? _d : new MemoryStore()),
+    // Print an error to the console if a few known misconfigurations are detected.
+    validations
   };
   if (typeof config.store.increment !== "function" || typeof config.store.decrement !== "function" || typeof config.store.resetKey !== "function" || config.store.resetAll !== void 0 && typeof config.store.resetAll !== "function" || config.store.init !== void 0 && typeof config.store.init !== "function") {
     throw new TypeError(
@@ -198,32 +326,33 @@ var handleAsyncErrors = (fn) => async (request, response, next) => {
   }
 };
 var rateLimit = (passedOptions) => {
-  const options = parseOptions(passedOptions != null ? passedOptions : {});
-  if (typeof options.store.init === "function")
-    options.store.init(options);
+  const config = parseOptions(passedOptions != null ? passedOptions : {});
+  const options = getOptionsFromConfig(config);
+  if (typeof config.store.init === "function")
+    config.store.init(options);
   const middleware = handleAsyncErrors(
     async (request, response, next) => {
-      const skip = await options.skip(request, response);
+      const skip = await config.skip(request, response);
       if (skip) {
         next();
         return;
       }
       const augmentedRequest = request;
-      const key = await options.keyGenerator(request, response);
-      const { totalHits, resetTime } = await options.store.increment(key);
-      const retrieveQuota = typeof options.max === "function" ? options.max(request, response) : options.max;
+      const key = await config.keyGenerator(request, response);
+      const { totalHits, resetTime } = await config.store.increment(key);
+      const retrieveQuota = typeof config.max === "function" ? config.max(request, response) : config.max;
       const maxHits = await retrieveQuota;
-      augmentedRequest[options.requestPropertyName] = {
+      augmentedRequest[config.requestPropertyName] = {
         limit: maxHits,
         current: totalHits,
         remaining: Math.max(maxHits - totalHits, 0),
         resetTime
       };
-      if (options.legacyHeaders && !response.headersSent) {
+      if (config.legacyHeaders && !response.headersSent) {
         response.setHeader("X-RateLimit-Limit", maxHits);
         response.setHeader(
           "X-RateLimit-Remaining",
-          augmentedRequest[options.requestPropertyName].remaining
+          augmentedRequest[config.requestPropertyName].remaining
         );
         if (resetTime instanceof Date) {
           response.setHeader("Date", (/* @__PURE__ */ new Date()).toUTCString());
@@ -233,11 +362,11 @@ var rateLimit = (passedOptions) => {
           );
         }
       }
-      if (options.standardHeaders && !response.headersSent) {
+      if (config.standardHeaders && !response.headersSent) {
         response.setHeader("RateLimit-Limit", maxHits);
         response.setHeader(
           "RateLimit-Remaining",
-          augmentedRequest[options.requestPropertyName].remaining
+          augmentedRequest[config.requestPropertyName].remaining
         );
         if (resetTime) {
           const deltaSeconds = Math.ceil(
@@ -246,17 +375,17 @@ var rateLimit = (passedOptions) => {
           response.setHeader("RateLimit-Reset", Math.max(0, deltaSeconds));
         }
       }
-      if (options.skipFailedRequests || options.skipSuccessfulRequests) {
+      if (config.skipFailedRequests || config.skipSuccessfulRequests) {
         let decremented = false;
         const decrementKey = async () => {
           if (!decremented) {
-            await options.store.decrement(key);
+            await config.store.decrement(key);
             decremented = true;
           }
         };
-        if (options.skipFailedRequests) {
+        if (config.skipFailedRequests) {
           response.on("finish", async () => {
-            if (!options.requestWasSuccessful(request, response))
+            if (!config.requestWasSuccessful(request, response))
               await decrementKey();
           });
           response.on("close", async () => {
@@ -267,39 +396,30 @@ var rateLimit = (passedOptions) => {
             await decrementKey();
           });
         }
-        if (options.skipSuccessfulRequests) {
+        if (config.skipSuccessfulRequests) {
           response.on("finish", async () => {
-            if (options.requestWasSuccessful(request, response))
+            if (config.requestWasSuccessful(request, response))
               await decrementKey();
           });
         }
       }
       if (maxHits && totalHits === maxHits + 1) {
-        options.onLimitReached(request, response, options);
+        config.onLimitReached(request, response, options);
       }
+      config.validations.disable();
       if (maxHits && totalHits > maxHits) {
-        if ((options.legacyHeaders || options.standardHeaders) && !response.headersSent) {
-          response.setHeader("Retry-After", Math.ceil(options.windowMs / 1e3));
+        if ((config.legacyHeaders || config.standardHeaders) && !response.headersSent) {
+          response.setHeader("Retry-After", Math.ceil(config.windowMs / 1e3));
         }
-        options.handler(request, response, next, options);
+        config.handler(request, response, next, options);
         return;
       }
       next();
     }
   );
-  middleware.resetKey = options.store.resetKey.bind(options.store);
+  middleware.resetKey = config.store.resetKey.bind(config.store);
   return middleware;
 };
-var omitUndefinedOptions = (passedOptions) => {
-  const omittedOptions = {};
-  for (const k of Object.keys(passedOptions)) {
-    const key = k;
-    if (passedOptions[key] !== void 0) {
-      omittedOptions[key] = passedOptions[key];
-    }
-  }
-  return omittedOptions;
-};
 var lib_default = rateLimit;
 export {
   MemoryStore,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "express-rate-limit",
-	"version": "6.7.1",
+	"version": "6.8.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",
@@ -56,17 +56,17 @@
 	},
 	"scripts": {
 		"clean": "del-cli dist/ coverage/ *.log *.tmp *.bak *.tgz",
-		"build:cjs": "esbuild --bundle --target=es2019 --format=cjs --outfile=dist/index.cjs --footer:js=\"module.exports = rateLimit; module.exports.default = rateLimit; module.exports.rateLimit = rateLimit; module.exports.MemoryStore = MemoryStore;\" source/index.ts",
-		"build:esm": "esbuild --bundle --target=es2019 --format=esm --outfile=dist/index.mjs source/index.ts",
+		"build:cjs": "esbuild --platform=node --bundle --target=es2019 --format=cjs --outfile=dist/index.cjs --footer:js=\"module.exports = rateLimit; module.exports.default = rateLimit; module.exports.rateLimit = rateLimit; module.exports.MemoryStore = MemoryStore;\" source/index.ts",
+		"build:esm": "esbuild --platform=node --bundle --target=es2019 --format=esm --outfile=dist/index.mjs source/index.ts",
 		"build:types": "dts-bundle-generator --out-file=dist/index.d.ts source/index.ts && cp dist/index.d.ts dist/index.d.cts && cp dist/index.d.ts dist/index.d.mts",
 		"compile": "run-s clean build:*",
 		"lint:code": "xo --ignore test/external/",
 		"lint:rest": "prettier --ignore-path .gitignore --ignore-unknown --check .",
 		"lint": "run-s lint:*",
-		"autofix:code": "run-s lint:code --fix",
-		"autofix:rest": "run-s lint:rest --write .",
+		"autofix:code": "npm run lint:code -- --fix",
+		"autofix:rest": "npm run lint:rest -- --write .",
 		"autofix": "run-s autofix:*",
-		"test:lib": "cross-env NODE_OPTIONS=--experimental-vm-modules jest",
+		"test:lib": "cross-env NODE_NO_WARNINGS=1 NODE_OPTIONS=--experimental-vm-modules jest",
 		"test:ext": "cd test/external/ && bash run-all-tests",
 		"test": "run-s lint test:*",
 		"pre-commit": "lint-staged",
@@ -107,7 +107,15 @@
 				"index-signature"
 			],
 			"n/no-unsupported-features/es-syntax": 0
-		}
+		},
+		"overrides": [
+			{
+				"files": "test/library/*.ts",
+				"rules": {
+					"@typescript-eslint/no-unsafe-argument": 0
+				}
+			}
+		]
 	},
 	"prettier": {
 		"semi": false,
@@ -119,12 +127,6 @@
 	},
 	"jest": {
 		"preset": "ts-jest/presets/default-esm",
-		"globals": {
-			"ts-jest": {
-				"useESM": true
-			}
-		},
-		"verbose": true,
 		"collectCoverage": true,
 		"collectCoverageFrom": [
 			"source/**/*.ts"

package/readme.md

@@ -451,6 +451,21 @@ const limiter = rateLimit({
 })
 ```
 
+### `validate`
+
+> `boolean`
+
+When enabled, a set of validation checks are run on the first request to detect
+common misconfigurations with proxies, etc. Prints an error to the console if
+any issue is detected.
+
+Automatically disables after the first request is processed.
+
+See https://github.com/express-rate-limit/express-rate-limit/wiki/Error-Codes
+for more info.
+
+Defaults to true.
+
 ### `store`
 
 > `Store`