express-rate-limit 7.4.1 → 7.5.0

package/dist/index.cjs

@@ -27,6 +27,9 @@ __export(source_exports, {
 module.exports = __toCommonJS(source_exports);
 
 // source/headers.ts
+var import_node_buffer = require("buffer");
+var import_node_crypto = require("crypto");
+var SUPPORTED_DRAFT_VERSIONS = ["draft-6", "draft-7", "draft-8"];
 var getResetSeconds = (resetTime, windowMs) => {
   let resetSeconds = void 0;
   if (resetTime) {
@@ -37,6 +40,12 @@ var getResetSeconds = (resetTime, windowMs) => {
   }
   return resetSeconds;
 };
+var getPartitionKey = (key) => {
+  const hash = (0, import_node_crypto.createHash)("sha256");
+  hash.update(key);
+  const partitionKey = hash.digest("hex").slice(0, 12);
+  return import_node_buffer.Buffer.from(partitionKey).toString("base64");
+};
 var setLegacyHeaders = (response, info) => {
   if (response.headersSent)
     return;
@@ -72,6 +81,17 @@ var setDraft7Headers = (response, info, windowMs) => {
     `limit=${info.limit}, remaining=${info.remaining}, reset=${resetSeconds}`
   );
 };
+var setDraft8Headers = (response, info, windowMs, name, key) => {
+  if (response.headersSent)
+    return;
+  const windowSeconds = Math.ceil(windowMs / 1e3);
+  const resetSeconds = getResetSeconds(info.resetTime, windowMs);
+  const partitionKey = getPartitionKey(key);
+  const policy = `q=${info.limit}; w=${windowSeconds}; pk=:${partitionKey}:`;
+  const header = `r=${info.remaining}; t=${resetSeconds}`;
+  response.append("RateLimit-Policy", `"${name}"; ${policy}`);
+  response.append("RateLimit", `"${name}"; ${header}`);
+};
 var setRetryAfterHeader = (response, info, windowMs) => {
   if (response.headersSent)
     return;
@@ -274,6 +294,22 @@ var validations = {
       );
     }
   },
+  /**
+   * Warns the user when an invalid/unsupported version of the draft spec is passed.
+   *
+   * @param version {any | undefined} - The version passed by the user.
+   *
+   * @returns {void}
+   */
+  headersDraftVersion(version) {
+    if (typeof version !== "string" || !SUPPORTED_DRAFT_VERSIONS.includes(version)) {
+      const versionString = SUPPORTED_DRAFT_VERSIONS.join(", ");
+      throw new ValidationError(
+        "ERR_ERL_HEADERS_UNSUPPORTED_DRAFT_VERSION",
+        `standardHeaders: only the following versions of the IETF draft specification are supported: ${versionString}.`
+      );
+    }
+  },
   /**
    * Warns the user when the selected headers option requires a reset time but
    * the store does not provide one.
@@ -606,6 +642,24 @@ var parseOptions = (passedOptions) => {
     message: "Too many requests, please try again later.",
     statusCode: 429,
     legacyHeaders: passedOptions.headers ?? true,
+    identifier(request, _response) {
+      let duration = "";
+      const property = config.requestPropertyName;
+      const { limit } = request[property];
+      const seconds = config.windowMs / 1e3;
+      const minutes = config.windowMs / (1e3 * 60);
+      const hours = config.windowMs / (1e3 * 60 * 60);
+      const days = config.windowMs / (1e3 * 60 * 60 * 24);
+      if (seconds < 60)
+        duration = `${seconds}sec`;
+      else if (minutes < 60)
+        duration = `${minutes}min`;
+      else if (hours < 24)
+        duration = `${hours}hr${hours > 1 ? "s" : ""}`;
+      else
+        duration = `${days}day${days > 1 ? "s" : ""}`;
+      return `${limit}-in-${duration}`;
+    },
     requestPropertyName: "rateLimit",
     skipFailedRequests: false,
     skipSuccessfulRequests: false,
@@ -628,7 +682,7 @@ var parseOptions = (passedOptions) => {
       }
     },
     passOnStoreError: false,
-    // Allow the default options to be overriden by the options passed to the middleware.
+    // Allow the default options to be overriden by the passed options.
     ...notUndefinedOptions,
     // `standardHeaders` is resolved into a draft version above, use that.
     standardHeaders,
@@ -706,11 +760,27 @@ var rateLimit = (passedOptions) => {
         setLegacyHeaders(response, info);
       }
       if (config.standardHeaders && !response.headersSent) {
-        if (config.standardHeaders === "draft-6") {
-          setDraft6Headers(response, info, config.windowMs);
-        } else if (config.standardHeaders === "draft-7") {
-          config.validations.headersResetTime(info.resetTime);
-          setDraft7Headers(response, info, config.windowMs);
+        switch (config.standardHeaders) {
+          case "draft-6": {
+            setDraft6Headers(response, info, config.windowMs);
+            break;
+          }
+          case "draft-7": {
+            config.validations.headersResetTime(info.resetTime);
+            setDraft7Headers(response, info, config.windowMs);
+            break;
+          }
+          case "draft-8": {
+            const retrieveName = typeof config.identifier === "function" ? config.identifier(request, response) : config.identifier;
+            const name = await retrieveName;
+            config.validations.headersResetTime(info.resetTime);
+            setDraft8Headers(response, info, config.windowMs, name, key);
+            break;
+          }
+          default: {
+            config.validations.headersDraftVersion(config.standardHeaders);
+            break;
+          }
         }
       }
       if (config.skipFailedRequests || config.skipSuccessfulRequests) {

package/dist/index.d.cts

@@ -86,6 +86,14 @@ declare const validations: {
 	 * @returns {void}
 	 */
 	onLimitReached(onLimitReached?: any): void;
+	/**
+	 * Warns the user when an invalid/unsupported version of the draft spec is passed.
+	 *
+	 * @param version {any | undefined} - The version passed by the user.
+	 *
+	 * @returns {void}
+	 */
+	headersDraftVersion(version?: any): void;
 	/**
 	 * Warns the user when the selected headers option requires a reset time but
 	 * the store does not provide one.
@@ -111,6 +119,7 @@ declare const validations: {
 	creationStack(store: Store): void;
 };
 export type Validations = typeof validations;
+declare const SUPPORTED_DRAFT_VERSIONS: string[];
 /**
  * Callback that fires when a client's hit counter is incremented.
  *
@@ -271,7 +280,7 @@ export type Store = {
 	 */
 	prefix?: string;
 };
-export type DraftHeadersVersion = "draft-6" | "draft-7";
+export type DraftHeadersVersion = (typeof SUPPORTED_DRAFT_VERSIONS)[number];
 /**
  * Validate configuration object for enabling or disabling specific validations.
  *
@@ -326,6 +335,13 @@ export type Options = {
 	 * Defaults to `false` (for backward compatibility, but its use is recommended).
 	 */
 	standardHeaders: boolean | DraftHeadersVersion;
+	/**
+	 * The name used to identify the quota policy in the `RateLimit` headers as per
+	 * the 8th draft of the IETF specification.
+	 *
+	 * Defaults to `{limit}-in-{window}`.
+	 */
+	identifier: string | ValueDeterminingMiddleware<string>;
 	/**
 	 * The name of the property on the request object to store the rate limit info.
 	 *

package/dist/index.d.mts

@@ -86,6 +86,14 @@ declare const validations: {
 	 * @returns {void}
 	 */
 	onLimitReached(onLimitReached?: any): void;
+	/**
+	 * Warns the user when an invalid/unsupported version of the draft spec is passed.
+	 *
+	 * @param version {any | undefined} - The version passed by the user.
+	 *
+	 * @returns {void}
+	 */
+	headersDraftVersion(version?: any): void;
 	/**
 	 * Warns the user when the selected headers option requires a reset time but
 	 * the store does not provide one.
@@ -111,6 +119,7 @@ declare const validations: {
 	creationStack(store: Store): void;
 };
 export type Validations = typeof validations;
+declare const SUPPORTED_DRAFT_VERSIONS: string[];
 /**
  * Callback that fires when a client's hit counter is incremented.
  *
@@ -271,7 +280,7 @@ export type Store = {
 	 */
 	prefix?: string;
 };
-export type DraftHeadersVersion = "draft-6" | "draft-7";
+export type DraftHeadersVersion = (typeof SUPPORTED_DRAFT_VERSIONS)[number];
 /**
  * Validate configuration object for enabling or disabling specific validations.
  *
@@ -326,6 +335,13 @@ export type Options = {
 	 * Defaults to `false` (for backward compatibility, but its use is recommended).
 	 */
 	standardHeaders: boolean | DraftHeadersVersion;
+	/**
+	 * The name used to identify the quota policy in the `RateLimit` headers as per
+	 * the 8th draft of the IETF specification.
+	 *
+	 * Defaults to `{limit}-in-{window}`.
+	 */
+	identifier: string | ValueDeterminingMiddleware<string>;
 	/**
 	 * The name of the property on the request object to store the rate limit info.
 	 *

package/dist/index.d.ts

@@ -86,6 +86,14 @@ declare const validations: {
 	 * @returns {void}
 	 */
 	onLimitReached(onLimitReached?: any): void;
+	/**
+	 * Warns the user when an invalid/unsupported version of the draft spec is passed.
+	 *
+	 * @param version {any | undefined} - The version passed by the user.
+	 *
+	 * @returns {void}
+	 */
+	headersDraftVersion(version?: any): void;
 	/**
 	 * Warns the user when the selected headers option requires a reset time but
 	 * the store does not provide one.
@@ -111,6 +119,7 @@ declare const validations: {
 	creationStack(store: Store): void;
 };
 export type Validations = typeof validations;
+declare const SUPPORTED_DRAFT_VERSIONS: string[];
 /**
  * Callback that fires when a client's hit counter is incremented.
  *
@@ -271,7 +280,7 @@ export type Store = {
 	 */
 	prefix?: string;
 };
-export type DraftHeadersVersion = "draft-6" | "draft-7";
+export type DraftHeadersVersion = (typeof SUPPORTED_DRAFT_VERSIONS)[number];
 /**
  * Validate configuration object for enabling or disabling specific validations.
  *
@@ -326,6 +335,13 @@ export type Options = {
 	 * Defaults to `false` (for backward compatibility, but its use is recommended).
 	 */
 	standardHeaders: boolean | DraftHeadersVersion;
+	/**
+	 * The name used to identify the quota policy in the `RateLimit` headers as per
+	 * the 8th draft of the IETF specification.
+	 *
+	 * Defaults to `{limit}-in-{window}`.
+	 */
+	identifier: string | ValueDeterminingMiddleware<string>;
 	/**
 	 * The name of the property on the request object to store the rate limit info.
 	 *

package/dist/index.mjs

@@ -1,4 +1,7 @@
 // source/headers.ts
+import { Buffer } from "buffer";
+import { createHash } from "crypto";
+var SUPPORTED_DRAFT_VERSIONS = ["draft-6", "draft-7", "draft-8"];
 var getResetSeconds = (resetTime, windowMs) => {
   let resetSeconds = void 0;
   if (resetTime) {
@@ -9,6 +12,12 @@ var getResetSeconds = (resetTime, windowMs) => {
   }
   return resetSeconds;
 };
+var getPartitionKey = (key) => {
+  const hash = createHash("sha256");
+  hash.update(key);
+  const partitionKey = hash.digest("hex").slice(0, 12);
+  return Buffer.from(partitionKey).toString("base64");
+};
 var setLegacyHeaders = (response, info) => {
   if (response.headersSent)
     return;
@@ -44,6 +53,17 @@ var setDraft7Headers = (response, info, windowMs) => {
     `limit=${info.limit}, remaining=${info.remaining}, reset=${resetSeconds}`
   );
 };
+var setDraft8Headers = (response, info, windowMs, name, key) => {
+  if (response.headersSent)
+    return;
+  const windowSeconds = Math.ceil(windowMs / 1e3);
+  const resetSeconds = getResetSeconds(info.resetTime, windowMs);
+  const partitionKey = getPartitionKey(key);
+  const policy = `q=${info.limit}; w=${windowSeconds}; pk=:${partitionKey}:`;
+  const header = `r=${info.remaining}; t=${resetSeconds}`;
+  response.append("RateLimit-Policy", `"${name}"; ${policy}`);
+  response.append("RateLimit", `"${name}"; ${header}`);
+};
 var setRetryAfterHeader = (response, info, windowMs) => {
   if (response.headersSent)
     return;
@@ -246,6 +266,22 @@ var validations = {
       );
     }
   },
+  /**
+   * Warns the user when an invalid/unsupported version of the draft spec is passed.
+   *
+   * @param version {any | undefined} - The version passed by the user.
+   *
+   * @returns {void}
+   */
+  headersDraftVersion(version) {
+    if (typeof version !== "string" || !SUPPORTED_DRAFT_VERSIONS.includes(version)) {
+      const versionString = SUPPORTED_DRAFT_VERSIONS.join(", ");
+      throw new ValidationError(
+        "ERR_ERL_HEADERS_UNSUPPORTED_DRAFT_VERSION",
+        `standardHeaders: only the following versions of the IETF draft specification are supported: ${versionString}.`
+      );
+    }
+  },
   /**
    * Warns the user when the selected headers option requires a reset time but
    * the store does not provide one.
@@ -578,6 +614,24 @@ var parseOptions = (passedOptions) => {
     message: "Too many requests, please try again later.",
     statusCode: 429,
     legacyHeaders: passedOptions.headers ?? true,
+    identifier(request, _response) {
+      let duration = "";
+      const property = config.requestPropertyName;
+      const { limit } = request[property];
+      const seconds = config.windowMs / 1e3;
+      const minutes = config.windowMs / (1e3 * 60);
+      const hours = config.windowMs / (1e3 * 60 * 60);
+      const days = config.windowMs / (1e3 * 60 * 60 * 24);
+      if (seconds < 60)
+        duration = `${seconds}sec`;
+      else if (minutes < 60)
+        duration = `${minutes}min`;
+      else if (hours < 24)
+        duration = `${hours}hr${hours > 1 ? "s" : ""}`;
+      else
+        duration = `${days}day${days > 1 ? "s" : ""}`;
+      return `${limit}-in-${duration}`;
+    },
     requestPropertyName: "rateLimit",
     skipFailedRequests: false,
     skipSuccessfulRequests: false,
@@ -600,7 +654,7 @@ var parseOptions = (passedOptions) => {
       }
     },
     passOnStoreError: false,
-    // Allow the default options to be overriden by the options passed to the middleware.
+    // Allow the default options to be overriden by the passed options.
     ...notUndefinedOptions,
     // `standardHeaders` is resolved into a draft version above, use that.
     standardHeaders,
@@ -678,11 +732,27 @@ var rateLimit = (passedOptions) => {
         setLegacyHeaders(response, info);
       }
       if (config.standardHeaders && !response.headersSent) {
-        if (config.standardHeaders === "draft-6") {
-          setDraft6Headers(response, info, config.windowMs);
-        } else if (config.standardHeaders === "draft-7") {
-          config.validations.headersResetTime(info.resetTime);
-          setDraft7Headers(response, info, config.windowMs);
+        switch (config.standardHeaders) {
+          case "draft-6": {
+            setDraft6Headers(response, info, config.windowMs);
+            break;
+          }
+          case "draft-7": {
+            config.validations.headersResetTime(info.resetTime);
+            setDraft7Headers(response, info, config.windowMs);
+            break;
+          }
+          case "draft-8": {
+            const retrieveName = typeof config.identifier === "function" ? config.identifier(request, response) : config.identifier;
+            const name = await retrieveName;
+            config.validations.headersResetTime(info.resetTime);
+            setDraft8Headers(response, info, config.windowMs, name, key);
+            break;
+          }
+          default: {
+            config.validations.headersDraftVersion(config.standardHeaders);
+            break;
+          }
         }
       }
       if (config.skipFailedRequests || config.skipSuccessfulRequests) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "express-rate-limit",
-	"version": "7.4.1",
+	"version": "7.5.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",
@@ -74,7 +74,7 @@
 		"prepare": "run-s compile && husky install config/husky"
 	},
 	"peerDependencies": {
-		"express": "4 || 5 || ^5.0.0-beta.1"
+		"express": "^4.11 || 5 || ^5.0.0-beta.1"
 	},
 	"devDependencies": {
 		"@express-rate-limit/prettier": "1.1.1",
@@ -87,7 +87,7 @@
 		"del-cli": "5.1.0",
 		"dts-bundle-generator": "8.0.1",
 		"esbuild": "0.19.5",
-		"express": "4.21.0",
+		"express": "4.21.1",
 		"husky": "8.0.3",
 		"jest": "29.7.0",
 		"lint-staged": "15.0.2",

package/readme.md

@@ -26,7 +26,7 @@ import { rateLimit } from 'express-rate-limit'
 const limiter = rateLimit({
 	windowMs: 15 * 60 * 1000, // 15 minutes
 	limit: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes).
-	standardHeaders: 'draft-7', // draft-6: `RateLimit-*` headers; draft-7: combined `RateLimit` header
+	standardHeaders: 'draft-8', // draft-6: `RateLimit-*` headers; draft-7 & draft-8: combined `RateLimit` header
 	legacyHeaders: false, // Disable the `X-RateLimit-*` headers.
 	// store: ... , // Redis, Memcached, etc. See below.
 })
@@ -45,24 +45,25 @@ The rate limiter comes with a built-in memory store, and supports a variety of
 All function options may be async. Click the name for additional info and
 default values.
 
-| Option                     | Type                             | Remarks                                                                                         |
-| -------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------- |
-| [`windowMs`]               | `number`                         | How long to remember requests for, in milliseconds.                                             |
-| [`limit`]                  | `number` \| `function`           | How many requests to allow.                                                                     |
-| [`message`]                | `string` \| `json` \| `function` | Response to return after limit is reached.                                                      |
-| [`statusCode`]             | `number`                         | HTTP status code after limit is reached (default is 429).                                       |
-| [`handler`]                | `function`                       | Function to run after limit is reached (overrides `message` and `statusCode` settings, if set). |
-| [`legacyHeaders`]          | `boolean`                        | Enable the `X-Rate-Limit` header.                                                               |
-| [`standardHeaders`]        | `'draft-6'` \| `'draft-7'`       | Enable the `Ratelimit` header.                                                                  |
-| [`store`]                  | `Store`                          | Use a custom store to share hit counts across multiple nodes.                                   |
-| [`passOnStoreError`]       | `boolean`                        | Allow (`true`) or block (`false`, default) traffic if the store becomes unavailable.            |
-| [`keyGenerator`]           | `function`                       | Identify users (defaults to IP address).                                                        |
-| [`requestPropertyName`]    | `string`                         | Add rate limit info to the `req` object.                                                        |
-| [`skip`]                   | `function`                       | Return `true` to bypass the limiter for the given request.                                      |
-| [`skipSuccessfulRequests`] | `boolean`                        | Uncount 1xx/2xx/3xx responses.                                                                  |
-| [`skipFailedRequests`]     | `boolean`                        | Uncount 4xx/5xx responses.                                                                      |
-| [`requestWasSuccessful`]   | `function`                       | Used by `skipSuccessfulRequests` and `skipFailedRequests`.                                      |
-| [`validate`]               | `boolean` \| `object`            | Enable or disable built-in validation checks.                                                   |
+| Option                     | Type                                      | Remarks                                                                                         |
+| -------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| [`windowMs`]               | `number`                                  | How long to remember requests for, in milliseconds.                                             |
+| [`limit`]                  | `number` \| `function`                    | How many requests to allow.                                                                     |
+| [`message`]                | `string` \| `json` \| `function`          | Response to return after limit is reached.                                                      |
+| [`statusCode`]             | `number`                                  | HTTP status code after limit is reached (default is 429).                                       |
+| [`handler`]                | `function`                                | Function to run after limit is reached (overrides `message` and `statusCode` settings, if set). |
+| [`legacyHeaders`]          | `boolean`                                 | Enable the `X-Rate-Limit` header.                                                               |
+| [`standardHeaders`]        | `'draft-6'` \| `'draft-7'` \| `'draft-8'` | Enable the `Ratelimit` header.                                                                  |
+| [`identifier`]             | `string` \| `function`                    | Name associated with the quota policy enforced by this rate limiter.                            |
+| [`store`]                  | `Store`                                   | Use a custom store to share hit counts across multiple nodes.                                   |
+| [`passOnStoreError`]       | `boolean`                                 | Allow (`true`) or block (`false`, default) traffic if the store becomes unavailable.            |
+| [`keyGenerator`]           | `function`                                | Identify users (defaults to IP address).                                                        |
+| [`requestPropertyName`]    | `string`                                  | Add rate limit info to the `req` object.                                                        |
+| [`skip`]                   | `function`                                | Return `true` to bypass the limiter for the given request.                                      |
+| [`skipSuccessfulRequests`] | `boolean`                                 | Uncount 1xx/2xx/3xx responses.                                                                  |
+| [`skipFailedRequests`]     | `boolean`                                 | Uncount 4xx/5xx responses.                                                                      |
+| [`requestWasSuccessful`]   | `function`                                | Used by `skipSuccessfulRequests` and `skipFailedRequests`.                                      |
+| [`validate`]               | `boolean` \| `object`                     | Enable or disable built-in validation checks.                                                   |
 
 ## Thank You
 
@@ -126,6 +127,8 @@ MIT © [Nathan Friedly](http://nfriedly.com/),
 	https://express-rate-limit.mintlify.app/reference/configuration#legacyheaders
 [`standardHeaders`]:
 	https://express-rate-limit.mintlify.app/reference/configuration#standardheaders
+[`identifier`]:
+	https://express-rate-limit.mintlify.app/reference/configuration#identifier
 [`store`]: https://express-rate-limit.mintlify.app/reference/configuration#store
 [`passOnStoreError`]:
 	https://express-rate-limit.mintlify.app/reference/configuration#passOnStoreError