express-rate-limit 6.8.1 → 6.9.0

package/changelog.md

@@ -6,6 +6,18 @@ 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.9.0](https://github.com/express-rate-limit/express-rate-limit/releases/tag/v6.9.0)
+
+### Added
+
+- New validaion check for double-counted requests
+- Added help link to each ValidationError, directing users to the appropriate
+  wiki page for more info
+
+### Changed
+
+- Miscaleanous documenation improvements
+
 ## [6.8.1](https://github.com/express-rate-limit/express-rate-limit/releases/tag/v6.8.0) & [6.7.2](https://github.com/express-rate-limit/express-rate-limit/releases/tag/v6.8.0)
 
 ### Changed

package/dist/index.cjs

@@ -42,17 +42,17 @@ var ValidationError = class extends Error {
    * 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.`
-    );
+    const url = `https://express-rate-limit.github.io/${code}/`;
+    super(`${message} See ${url} for more information on this error.`);
     __publicField(this, "name");
     __publicField(this, "code");
+    __publicField(this, "help");
     this.name = this.constructor.name;
     this.code = code;
-    this.message = message;
+    this.help = url;
   }
 };
-var Validations = class {
+var _Validations = class _Validations {
   constructor(enabled) {
     // eslint-disable-next-line @typescript-eslint/parameter-properties
     __publicField(this, "enabled");
@@ -129,6 +129,37 @@ var Validations = class {
       }
     });
   }
+  /**
+   * Ensures a given key is incremented only once per request.
+   *
+   * @param request {Request} - The Express request object.
+   * @param store {Store} - The store class.
+   * @param key {string} - The key used to store the client's hit count.
+   *
+   * @returns {void}
+   */
+  singleCount(request, store, key) {
+    this.wrap(() => {
+      let storeKeys = _Validations.singleCountKeys.get(request);
+      if (!storeKeys) {
+        storeKeys = /* @__PURE__ */ new Map();
+        _Validations.singleCountKeys.set(request, storeKeys);
+      }
+      const storeKey = store.localKeys ? store : store.constructor.name;
+      let keys = storeKeys.get(storeKey);
+      if (!keys) {
+        keys = [];
+        storeKeys.set(storeKey, keys);
+      }
+      if (keys.includes(key)) {
+        throw new ValidationError(
+          "ERR_ERL_DOUBLE_COUNT",
+          `The hit count for ${key} was incremented more than once for a single request.`
+        );
+      }
+      keys.push(key);
+    });
+  }
   wrap(validation) {
     if (!this.enabled) {
       return;
@@ -140,6 +171,18 @@ var Validations = class {
     }
   }
 };
+/**
+ * Maps the key used in a store for a certain request, and ensures that the
+ * same key isn't used more than once per request.
+ *
+ * The store can be any one of the following:
+ *  - An instance, for stores like the MemoryStore where two instances do not
+ *    share state.
+ *  - A string (class name), for stores where multiple instances
+ *    typically share state, such as the Redis store.
+ */
+__publicField(_Validations, "singleCountKeys", /* @__PURE__ */ new WeakMap());
+var Validations = _Validations;
 
 // source/memory-store.ts
 var calculateNextResetTime = (windowMs) => {
@@ -165,6 +208,11 @@ var MemoryStore = class {
      * Reference to the active timer.
      */
     __publicField(this, "interval");
+    /**
+     * Confirmation that the keys incremented in once instance of MemoryStore
+     * cannot affect other instances.
+     */
+    __publicField(this, "localKeys", true);
   }
   /**
    * Method that initializes the store.
@@ -366,6 +414,7 @@ var rateLimit = (passedOptions) => {
       const augmentedRequest = request;
       const key = await config.keyGenerator(request, response);
       const { totalHits, resetTime } = await config.store.increment(key);
+      config.validations.singleCount(request, config.store, key);
       const retrieveQuota = typeof config.max === "function" ? config.max(request, response) : config.max;
       const maxHits = await retrieveQuota;
       augmentedRequest[config.requestPropertyName] = {

package/dist/index.d.cts

@@ -130,6 +130,14 @@ export type Store = {
 	 * Method to shutdown the store, stop timers, and release all resources.
 	 */
 	shutdown?: () => Promise<void> | void;
+	/**
+	 * Flag to indicate that keys incremented in one instance of this store can
+	 * not affect other instances. Typically false if a database is used, true for
+	 * MemoryStore.
+	 *
+	 * Used to help detect double-counting misconfigurations.
+	 */
+	localKeys?: boolean;
 };
 /**
  * The configuration options for the rate limiter.
@@ -309,6 +317,11 @@ export declare class MemoryStore implements Store {
 	 * Reference to the active timer.
 	 */
 	interval?: NodeJS.Timer;
+	/**
+	 * Confirmation that the keys incremented in once instance of MemoryStore
+	 * cannot affect other instances.
+	 */
+	localKeys: boolean;
 	/**
 	 * Method that initializes the store.
 	 *

package/dist/index.d.mts

@@ -130,6 +130,14 @@ export type Store = {
 	 * Method to shutdown the store, stop timers, and release all resources.
 	 */
 	shutdown?: () => Promise<void> | void;
+	/**
+	 * Flag to indicate that keys incremented in one instance of this store can
+	 * not affect other instances. Typically false if a database is used, true for
+	 * MemoryStore.
+	 *
+	 * Used to help detect double-counting misconfigurations.
+	 */
+	localKeys?: boolean;
 };
 /**
  * The configuration options for the rate limiter.
@@ -309,6 +317,11 @@ export declare class MemoryStore implements Store {
 	 * Reference to the active timer.
 	 */
 	interval?: NodeJS.Timer;
+	/**
+	 * Confirmation that the keys incremented in once instance of MemoryStore
+	 * cannot affect other instances.
+	 */
+	localKeys: boolean;
 	/**
 	 * Method that initializes the store.
 	 *

package/dist/index.d.ts

@@ -130,6 +130,14 @@ export type Store = {
 	 * Method to shutdown the store, stop timers, and release all resources.
 	 */
 	shutdown?: () => Promise<void> | void;
+	/**
+	 * Flag to indicate that keys incremented in one instance of this store can
+	 * not affect other instances. Typically false if a database is used, true for
+	 * MemoryStore.
+	 *
+	 * Used to help detect double-counting misconfigurations.
+	 */
+	localKeys?: boolean;
 };
 /**
  * The configuration options for the rate limiter.
@@ -309,6 +317,11 @@ export declare class MemoryStore implements Store {
 	 * Reference to the active timer.
 	 */
 	interval?: NodeJS.Timer;
+	/**
+	 * Confirmation that the keys incremented in once instance of MemoryStore
+	 * cannot affect other instances.
+	 */
+	localKeys: boolean;
 	/**
 	 * Method that initializes the store.
 	 *

package/dist/index.mjs

@@ -16,17 +16,17 @@ var ValidationError = class extends Error {
    * 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.`
-    );
+    const url = `https://express-rate-limit.github.io/${code}/`;
+    super(`${message} See ${url} for more information on this error.`);
     __publicField(this, "name");
     __publicField(this, "code");
+    __publicField(this, "help");
     this.name = this.constructor.name;
     this.code = code;
-    this.message = message;
+    this.help = url;
   }
 };
-var Validations = class {
+var _Validations = class _Validations {
   constructor(enabled) {
     // eslint-disable-next-line @typescript-eslint/parameter-properties
     __publicField(this, "enabled");
@@ -103,6 +103,37 @@ var Validations = class {
       }
     });
   }
+  /**
+   * Ensures a given key is incremented only once per request.
+   *
+   * @param request {Request} - The Express request object.
+   * @param store {Store} - The store class.
+   * @param key {string} - The key used to store the client's hit count.
+   *
+   * @returns {void}
+   */
+  singleCount(request, store, key) {
+    this.wrap(() => {
+      let storeKeys = _Validations.singleCountKeys.get(request);
+      if (!storeKeys) {
+        storeKeys = /* @__PURE__ */ new Map();
+        _Validations.singleCountKeys.set(request, storeKeys);
+      }
+      const storeKey = store.localKeys ? store : store.constructor.name;
+      let keys = storeKeys.get(storeKey);
+      if (!keys) {
+        keys = [];
+        storeKeys.set(storeKey, keys);
+      }
+      if (keys.includes(key)) {
+        throw new ValidationError(
+          "ERR_ERL_DOUBLE_COUNT",
+          `The hit count for ${key} was incremented more than once for a single request.`
+        );
+      }
+      keys.push(key);
+    });
+  }
   wrap(validation) {
     if (!this.enabled) {
       return;
@@ -114,6 +145,18 @@ var Validations = class {
     }
   }
 };
+/**
+ * Maps the key used in a store for a certain request, and ensures that the
+ * same key isn't used more than once per request.
+ *
+ * The store can be any one of the following:
+ *  - An instance, for stores like the MemoryStore where two instances do not
+ *    share state.
+ *  - A string (class name), for stores where multiple instances
+ *    typically share state, such as the Redis store.
+ */
+__publicField(_Validations, "singleCountKeys", /* @__PURE__ */ new WeakMap());
+var Validations = _Validations;
 
 // source/memory-store.ts
 var calculateNextResetTime = (windowMs) => {
@@ -139,6 +182,11 @@ var MemoryStore = class {
      * Reference to the active timer.
      */
     __publicField(this, "interval");
+    /**
+     * Confirmation that the keys incremented in once instance of MemoryStore
+     * cannot affect other instances.
+     */
+    __publicField(this, "localKeys", true);
   }
   /**
    * Method that initializes the store.
@@ -340,6 +388,7 @@ var rateLimit = (passedOptions) => {
       const augmentedRequest = request;
       const key = await config.keyGenerator(request, response);
       const { totalHits, resetTime } = await config.store.increment(key);
+      config.validations.singleCount(request, config.store, key);
       const retrieveQuota = typeof config.max === "function" ? config.max(request, response) : config.max;
       const maxHits = await retrieveQuota;
       augmentedRequest[config.requestPropertyName] = {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "express-rate-limit",
-	"version": "6.8.1",
+	"version": "6.9.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",
@@ -63,12 +63,12 @@
 		"lint:code": "xo --ignore test/external/",
 		"lint:rest": "prettier --ignore-path .gitignore --ignore-unknown --check .",
 		"lint": "run-s lint:*",
-		"autofix:code": "npm run lint:code -- --fix",
-		"autofix:rest": "npm run lint:rest -- --write .",
-		"autofix": "run-s autofix:*",
+		"format:code": "npm run lint:code -- --fix",
+		"format:rest": "npm run lint:rest -- --write .",
+		"format": "run-s format:*",
 		"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:*",
+		"test": "run-s lint test:lib",
 		"pre-commit": "lint-staged",
 		"prepare": "run-s compile && husky install config/husky"
 	},

package/readme.md

@@ -16,17 +16,42 @@ authentication and more to any API in minutes. Learn more at
 [![npm version](https://img.shields.io/npm/v/express-rate-limit.svg)](https://npmjs.org/package/express-rate-limit 'View this project on NPM')
 [![npm downloads](https://img.shields.io/npm/dm/express-rate-limit)](https://www.npmjs.com/package/express-rate-limit)
 
-Basic rate-limiting middleware for Express. Use to limit repeated requests to
-public APIs and/or endpoints such as password reset. Plays nice with
+Basic rate-limiting middleware for [Express](http://expressjs.com/). Use to
+limit repeated requests to public APIs and/or endpoints such as password reset.
+Plays nice with
 [express-slow-down](https://www.npmjs.com/package/express-slow-down).
 
 </div>
 
-### Alternate Rate Limiters
+## Use Cases
+
+Depending on your use case, you may need to switch to a different
+[store](#store).
+
+#### Abuse Prevention
+
+The default `MemoryStore` is probably fine.
 
-> This module does not share state with other processes/servers by default. If
-> you need a more robust solution, I recommend using an external store. See the
-> [`stores` section](#store) below for a list of external stores.
+#### API Rate Limit Enforcement
+
+You likely want to switch to a different [store](#store). As a performance
+optimization, the default `MemoryStore` uses a global time window, so if your
+limit is 10 requests per minute, a single user might be able to get an initial
+burst of up to 20 requests in a row if they happen to get the first 10 in at the
+end of one minute and the next 10 in at the start of the next minute. (After the
+initial burst, they will be limited to the expected 10 requests per minute.) All
+other stores use per-user time windows, so a user will get exactly 10 requests
+regardless.
+
+Additionally, if you have multiple servers or processes (for example, with the
+[node:cluster](https://nodejs.org/api/cluster.html) module), you'll likely want
+to use an external data store to syhcnronize hits
+([redis](https://npmjs.com/package/rate-limit-redis),
+[memcached](https://npmjs.org/package/rate-limit-memcached), [etc.](#store))
+This will guarentee the expected result even if some requests get handled by
+different servers/processes.
+
+### Alternate Rate Limiters
 
 This module was designed to only handle the basics and didn't even support
 external stores initially. These other options all are excellent pieces of
@@ -94,6 +119,7 @@ const limiter = rateLimit({
 	max: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes)
 	standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
 	legacyHeaders: false, // Disable the `X-RateLimit-*` headers
+	// store: ... , // Use an external store for more precise rate limiting
 })
 
 // Apply the rate limiting middleware to all requests
@@ -112,6 +138,7 @@ const apiLimiter = rateLimit({
 	max: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes)
 	standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
 	legacyHeaders: false, // Disable the `X-RateLimit-*` headers
+	// store: ... , // Use an external store for more precise rate limiting
 })
 
 // Apply the rate limiting middleware to API calls only
@@ -128,6 +155,7 @@ const apiLimiter = rateLimit({
 	max: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes)
 	standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
 	legacyHeaders: false, // Disable the `X-RateLimit-*` headers
+	// store: ... , // Use an external store for more precise rate limiting
 })
 
 app.use('/api/', apiLimiter)
@@ -149,17 +177,22 @@ app.post('/create-account', createAccountLimiter, (request, response) => {
 To use a custom store:
 
 ```ts
-import rateLimit, { MemoryStore } from 'express-rate-limit'
+import rateLimit from 'express-rate-limit'
+import RedisStore from 'rate-limit-redis'
+import RedisClient from 'ioredis'
 
-const apiLimiter = rateLimit({
+const redisClient = new RedisClient()
+const rateLimiter = rateLimit({
 	windowMs: 15 * 60 * 1000, // 15 minutes
 	max: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes)
 	standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
-	store: new MemoryStore(),
+	store: new RedisStore({
+		/* ... */
+	}), // Use the external store
 })
 
-// Apply the rate limiting middleware to API calls only
-app.use('/api', apiLimiter)
+// Apply the rate limiting middleware to all requests
+app.use(rateLimiter)
 ```
 
 > **Note:** most stores will require additional configuration, such as custom