express-rate-limit 7.5.1 → 8.0.1

package/dist/index.cjs

@@ -21,11 +21,179 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   MemoryStore: () => MemoryStore,
-  default: () => lib_default,
-  rateLimit: () => lib_default
+  default: () => rate_limit_default,
+  ipKeyGenerator: () => ipKeyGenerator,
+  rateLimit: () => rate_limit_default
 });
 module.exports = __toCommonJS(index_exports);
 
+// source/ip-key-generator.ts
+var import_node_net = require("node:net");
+var import_ip_address = require("ip-address");
+function ipKeyGenerator(ip, ipv6Subnet = 56) {
+  if (ipv6Subnet && (0, import_node_net.isIPv6)(ip)) {
+    return `${new import_ip_address.Address6(`${ip}/${ipv6Subnet}`).startAddress().correctForm()}/${ipv6Subnet}`;
+  }
+  return ip;
+}
+
+// source/memory-store.ts
+var MemoryStore = class {
+  constructor() {
+    /**
+     * These two maps store usage (requests) and reset time by key (for example, IP
+     * addresses or API keys).
+     *
+     * They are split into two to avoid having to iterate through the entire set to
+     * determine which ones need reset. Instead, `Client`s are moved from `previous`
+     * to `current` as they hit the endpoint. Once `windowMs` has elapsed, all clients
+     * left in `previous`, i.e., those that have not made any recent requests, are
+     * known to be expired and can be deleted in bulk.
+     */
+    this.previous = /* @__PURE__ */ new Map();
+    this.current = /* @__PURE__ */ new Map();
+    /**
+     * Confirmation that the keys incremented in once instance of MemoryStore
+     * cannot affect other instances.
+     */
+    this.localKeys = true;
+  }
+  /**
+   * Method that initializes the store.
+   *
+   * @param options {Options} - The options used to setup the middleware.
+   */
+  init(options) {
+    this.windowMs = options.windowMs;
+    if (this.interval) clearInterval(this.interval);
+    this.interval = setInterval(() => {
+      this.clearExpired();
+    }, this.windowMs);
+    this.interval.unref?.();
+  }
+  /**
+   * Method to fetch a client's hit count and reset time.
+   *
+   * @param key {string} - The identifier for a client.
+   *
+   * @returns {ClientRateLimitInfo | undefined} - The number of hits and reset time for that client.
+   *
+   * @public
+   */
+  async get(key) {
+    return this.current.get(key) ?? this.previous.get(key);
+  }
+  /**
+   * Method to increment a client's hit counter.
+   *
+   * @param key {string} - The identifier for a client.
+   *
+   * @returns {ClientRateLimitInfo} - The number of hits and reset time for that client.
+   *
+   * @public
+   */
+  async increment(key) {
+    const client = this.getClient(key);
+    const now = Date.now();
+    if (client.resetTime.getTime() <= now) {
+      this.resetClient(client, now);
+    }
+    client.totalHits++;
+    return client;
+  }
+  /**
+   * Method to decrement a client's hit counter.
+   *
+   * @param key {string} - The identifier for a client.
+   *
+   * @public
+   */
+  async decrement(key) {
+    const client = this.getClient(key);
+    if (client.totalHits > 0) client.totalHits--;
+  }
+  /**
+   * Method to reset a client's hit counter.
+   *
+   * @param key {string} - The identifier for a client.
+   *
+   * @public
+   */
+  async resetKey(key) {
+    this.current.delete(key);
+    this.previous.delete(key);
+  }
+  /**
+   * Method to reset everyone's hit counter.
+   *
+   * @public
+   */
+  async resetAll() {
+    this.current.clear();
+    this.previous.clear();
+  }
+  /**
+   * Method to stop the timer (if currently running) and prevent any memory
+   * leaks.
+   *
+   * @public
+   */
+  shutdown() {
+    clearInterval(this.interval);
+    void this.resetAll();
+  }
+  /**
+   * Recycles a client by setting its hit count to zero, and reset time to
+   * `windowMs` milliseconds from now.
+   *
+   * NOT to be confused with `#resetKey()`, which removes a client from both the
+   * `current` and `previous` maps.
+   *
+   * @param client {Client} - The client to recycle.
+   * @param now {number} - The current time, to which the `windowMs` is added to get the `resetTime` for the client.
+   *
+   * @return {Client} - The modified client that was passed in, to allow for chaining.
+   */
+  resetClient(client, now = Date.now()) {
+    client.totalHits = 0;
+    client.resetTime.setTime(now + this.windowMs);
+    return client;
+  }
+  /**
+   * Retrieves or creates a client, given a key. Also ensures that the client being
+   * returned is in the `current` map.
+   *
+   * @param key {string} - The key under which the client is (or is to be) stored.
+   *
+   * @returns {Client} - The requested client.
+   */
+  getClient(key) {
+    if (this.current.has(key)) return this.current.get(key);
+    let client;
+    if (this.previous.has(key)) {
+      client = this.previous.get(key);
+      this.previous.delete(key);
+    } else {
+      client = { totalHits: 0, resetTime: /* @__PURE__ */ new Date() };
+      this.resetClient(client);
+    }
+    this.current.set(key, client);
+    return client;
+  }
+  /**
+   * Move current clients to previous, create a new map for current.
+   *
+   * This function is called every `windowMs`.
+   */
+  clearExpired() {
+    this.previous = this.current;
+    this.current = /* @__PURE__ */ new Map();
+  }
+};
+
+// source/rate-limit.ts
+var import_node_net3 = require("node:net");
+
 // source/headers.ts
 var import_node_buffer = require("node:buffer");
 var import_node_crypto = require("node:crypto");
@@ -34,12 +202,12 @@ var SUPPORTED_DRAFT_VERSIONS = [
   "draft-7",
   "draft-8"
 ];
-var getResetSeconds = (resetTime, windowMs) => {
-  let resetSeconds = void 0;
+var getResetSeconds = (windowMs, resetTime) => {
+  let resetSeconds;
   if (resetTime) {
     const deltaSeconds = Math.ceil((resetTime.getTime() - Date.now()) / 1e3);
     resetSeconds = Math.max(0, deltaSeconds);
-  } else if (windowMs) {
+  } else {
     resetSeconds = Math.ceil(windowMs / 1e3);
   }
   return resetSeconds;
@@ -65,7 +233,7 @@ var setLegacyHeaders = (response, info) => {
 var setDraft6Headers = (response, info, windowMs) => {
   if (response.headersSent) return;
   const windowSeconds = Math.ceil(windowMs / 1e3);
-  const resetSeconds = getResetSeconds(info.resetTime);
+  const resetSeconds = getResetSeconds(windowMs, info.resetTime);
   response.setHeader("RateLimit-Policy", `${info.limit};w=${windowSeconds}`);
   response.setHeader("RateLimit-Limit", info.limit.toString());
   response.setHeader("RateLimit-Remaining", info.remaining.toString());
@@ -75,7 +243,7 @@ var setDraft6Headers = (response, info, windowMs) => {
 var setDraft7Headers = (response, info, windowMs) => {
   if (response.headersSent) return;
   const windowSeconds = Math.ceil(windowMs / 1e3);
-  const resetSeconds = getResetSeconds(info.resetTime, windowMs);
+  const resetSeconds = getResetSeconds(windowMs, info.resetTime);
   response.setHeader("RateLimit-Policy", `${info.limit};w=${windowSeconds}`);
   response.setHeader(
     "RateLimit",
@@ -85,21 +253,33 @@ var setDraft7Headers = (response, info, windowMs) => {
 var setDraft8Headers = (response, info, windowMs, name, key) => {
   if (response.headersSent) return;
   const windowSeconds = Math.ceil(windowMs / 1e3);
-  const resetSeconds = getResetSeconds(info.resetTime, windowMs);
+  const resetSeconds = getResetSeconds(windowMs, info.resetTime);
   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}`);
+  const policy = `q=${info.limit}; w=${windowSeconds}; pk=:${partitionKey}:`;
   response.append("RateLimit", `"${name}"; ${header}`);
+  response.append("RateLimit-Policy", `"${name}"; ${policy}`);
 };
 var setRetryAfterHeader = (response, info, windowMs) => {
   if (response.headersSent) return;
-  const resetSeconds = getResetSeconds(info.resetTime, windowMs);
+  const resetSeconds = getResetSeconds(windowMs, info.resetTime);
   response.setHeader("Retry-After", resetSeconds.toString());
 };
 
+// source/utils.ts
+var omitUndefinedProperties = (passedOptions) => {
+  const omittedOptions = {};
+  for (const k of Object.keys(passedOptions)) {
+    const key = k;
+    if (passedOptions[key] !== void 0) {
+      omittedOptions[key] = passedOptions[key];
+    }
+  }
+  return omittedOptions;
+};
+
 // source/validations.ts
-var import_node_net = require("node:net");
+var import_node_net2 = require("node:net");
 var ValidationError = class extends Error {
   /**
    * The code must be a string, in snake case and all capital, that starts with
@@ -121,7 +301,6 @@ var ChangeWarning = class extends ValidationError {
 var usedStores = /* @__PURE__ */ new Set();
 var singleCountKeys = /* @__PURE__ */ new WeakMap();
 var validations = {
-  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
   enabled: {
     default: true
   },
@@ -146,7 +325,7 @@ var validations = {
         `An undefined 'request.ip' was detected. This might indicate a misconfiguration or the connection being destroyed prematurely.`
       );
     }
-    if (!(0, import_node_net.isIP)(ip)) {
+    if (!(0, import_node_net2.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.`
@@ -256,7 +435,7 @@ var validations = {
     if (limit === 0) {
       throw new ChangeWarning(
         "WRN_ERL_MAX_ZERO",
-        `Setting limit or max to 0 disables rate limiting in express-rate-limit v6 and older, but will cause all requests to be blocked in v7`
+        "Setting limit or max to 0 disables rate limiting in express-rate-limit v6 and older, but will cause all requests to be blocked in v7"
       );
     }
   },
@@ -288,7 +467,7 @@ var validations = {
     if (onLimitReached) {
       throw new ChangeWarning(
         "WRN_ERL_DEPRECATED_ON_LIMIT_REACHED",
-        `The onLimitReached configuration option is deprecated and has been removed in express-rate-limit v7.`
+        "The onLimitReached configuration option is deprecated and has been removed in express-rate-limit v7."
       );
     }
   },
@@ -357,7 +536,8 @@ var validations = {
     const { stack } = new Error(
       "express-rate-limit validation check (set options.validate.creationStack=false to disable)"
     );
-    if (stack?.includes("Layer.handle [as handle_request]")) {
+    if (stack?.includes("Layer.handle [as handle_request]") || // express v4
+    stack?.includes("Layer.handleRequest")) {
       if (!store.localKeys) {
         throw new ValidationError(
           "ERR_ERL_CREATED_IN_REQUEST_HANDLER",
@@ -366,7 +546,38 @@ var validations = {
       }
       throw new ValidationError(
         "ERR_ERL_CREATED_IN_REQUEST_HANDLER",
-        `express-rate-limit instance should be created at app initialization, not when responding to a request.`
+        "express-rate-limit instance should be created at app initialization, not when responding to a request."
+      );
+    }
+  },
+  ipv6Subnet(ipv6Subnet) {
+    if (ipv6Subnet === false) {
+      return;
+    }
+    if (!Number.isInteger(ipv6Subnet) || ipv6Subnet < 32 || ipv6Subnet > 64) {
+      throw new ValidationError(
+        "ERR_ERL_IPV6_SUBNET",
+        `Unexpected ipv6Subnet value: ${ipv6Subnet}. Expected an integer between 32 and 64 (usually 48-64).`
+      );
+    }
+  },
+  ipv6SubnetOrKeyGenerator(options) {
+    if (options.ipv6Subnet !== void 0 && options.keyGenerator) {
+      throw new ValidationError(
+        "ERR_ERL_IPV6SUBNET_OR_KEYGENERATOR",
+        `Incompatible options: the 'ipv6Subnet' option is ignored when a custom 'keyGenerator' function is also set.`
+      );
+    }
+  },
+  keyGeneratorIpFallback(keyGenerator) {
+    if (!keyGenerator) {
+      return;
+    }
+    const src = keyGenerator.toString();
+    if ((src.includes("req.ip") || src.includes("request.ip")) && !src.includes("ipKeyGenerator")) {
+      throw new ValidationError(
+        "ERR_ERL_KEY_GEN_IPV6",
+        "Custom keyGenerator appears to use request IP without calling the ipKeyGenerator helper function for IPv6 addresses. This could allow IPv6 users to bypass limits."
       );
     }
   }
@@ -383,9 +594,7 @@ var getValidations = (_enabled) => {
       ..._enabled
     };
   }
-  const wrappedValidations = {
-    enabled
-  };
+  const wrappedValidations = { enabled };
   for (const [name, validation] of Object.entries(validations)) {
     if (typeof validation === "function")
       wrappedValidations[name] = (...args) => {
@@ -407,161 +616,7 @@ var getValidations = (_enabled) => {
   return wrappedValidations;
 };
 
-// source/memory-store.ts
-var MemoryStore = class {
-  constructor() {
-    /**
-     * These two maps store usage (requests) and reset time by key (for example, IP
-     * addresses or API keys).
-     *
-     * They are split into two to avoid having to iterate through the entire set to
-     * determine which ones need reset. Instead, `Client`s are moved from `previous`
-     * to `current` as they hit the endpoint. Once `windowMs` has elapsed, all clients
-     * left in `previous`, i.e., those that have not made any recent requests, are
-     * known to be expired and can be deleted in bulk.
-     */
-    this.previous = /* @__PURE__ */ new Map();
-    this.current = /* @__PURE__ */ new Map();
-    /**
-     * Confirmation that the keys incremented in once instance of MemoryStore
-     * cannot affect other instances.
-     */
-    this.localKeys = true;
-  }
-  /**
-   * Method that initializes the store.
-   *
-   * @param options {Options} - The options used to setup the middleware.
-   */
-  init(options) {
-    this.windowMs = options.windowMs;
-    if (this.interval) clearInterval(this.interval);
-    this.interval = setInterval(() => {
-      this.clearExpired();
-    }, this.windowMs);
-    if (this.interval.unref) this.interval.unref();
-  }
-  /**
-   * Method to fetch a client's hit count and reset time.
-   *
-   * @param key {string} - The identifier for a client.
-   *
-   * @returns {ClientRateLimitInfo | undefined} - The number of hits and reset time for that client.
-   *
-   * @public
-   */
-  async get(key) {
-    return this.current.get(key) ?? this.previous.get(key);
-  }
-  /**
-   * Method to increment a client's hit counter.
-   *
-   * @param key {string} - The identifier for a client.
-   *
-   * @returns {ClientRateLimitInfo} - The number of hits and reset time for that client.
-   *
-   * @public
-   */
-  async increment(key) {
-    const client = this.getClient(key);
-    const now = Date.now();
-    if (client.resetTime.getTime() <= now) {
-      this.resetClient(client, now);
-    }
-    client.totalHits++;
-    return client;
-  }
-  /**
-   * Method to decrement a client's hit counter.
-   *
-   * @param key {string} - The identifier for a client.
-   *
-   * @public
-   */
-  async decrement(key) {
-    const client = this.getClient(key);
-    if (client.totalHits > 0) client.totalHits--;
-  }
-  /**
-   * Method to reset a client's hit counter.
-   *
-   * @param key {string} - The identifier for a client.
-   *
-   * @public
-   */
-  async resetKey(key) {
-    this.current.delete(key);
-    this.previous.delete(key);
-  }
-  /**
-   * Method to reset everyone's hit counter.
-   *
-   * @public
-   */
-  async resetAll() {
-    this.current.clear();
-    this.previous.clear();
-  }
-  /**
-   * Method to stop the timer (if currently running) and prevent any memory
-   * leaks.
-   *
-   * @public
-   */
-  shutdown() {
-    clearInterval(this.interval);
-    void this.resetAll();
-  }
-  /**
-   * Recycles a client by setting its hit count to zero, and reset time to
-   * `windowMs` milliseconds from now.
-   *
-   * NOT to be confused with `#resetKey()`, which removes a client from both the
-   * `current` and `previous` maps.
-   *
-   * @param client {Client} - The client to recycle.
-   * @param now {number} - The current time, to which the `windowMs` is added to get the `resetTime` for the client.
-   *
-   * @return {Client} - The modified client that was passed in, to allow for chaining.
-   */
-  resetClient(client, now = Date.now()) {
-    client.totalHits = 0;
-    client.resetTime.setTime(now + this.windowMs);
-    return client;
-  }
-  /**
-   * Retrieves or creates a client, given a key. Also ensures that the client being
-   * returned is in the `current` map.
-   *
-   * @param key {string} - The key under which the client is (or is to be) stored.
-   *
-   * @returns {Client} - The requested client.
-   */
-  getClient(key) {
-    if (this.current.has(key)) return this.current.get(key);
-    let client;
-    if (this.previous.has(key)) {
-      client = this.previous.get(key);
-      this.previous.delete(key);
-    } else {
-      client = { totalHits: 0, resetTime: /* @__PURE__ */ new Date() };
-      this.resetClient(client);
-    }
-    this.current.set(key, client);
-    return client;
-  }
-  /**
-   * Move current clients to previous, create a new map for current.
-   *
-   * This function is called every `windowMs`.
-   */
-  clearExpired() {
-    this.previous = this.current;
-    this.current = /* @__PURE__ */ new Map();
-  }
-};
-
-// source/lib.ts
+// source/rate-limit.ts
 var isLegacyStore = (store) => (
   // Check that `incr` exists but `increment` does not - store authors might want
   // to keep both around for backwards compatibility.
@@ -605,18 +660,8 @@ var getOptionsFromConfig = (config) => {
     validate: validations2.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) => {
-  const notUndefinedOptions = omitUndefinedOptions(passedOptions);
+  const notUndefinedOptions = omitUndefinedProperties(passedOptions);
   const validations2 = getValidations(notUndefinedOptions?.validate ?? true);
   validations2.validationsConfig();
   validations2.draftPolliHeaders(
@@ -624,6 +669,11 @@ var parseOptions = (passedOptions) => {
     notUndefinedOptions.draft_polli_ratelimit_headers
   );
   validations2.onLimitReached(notUndefinedOptions.onLimitReached);
+  if (notUndefinedOptions.ipv6Subnet !== void 0 && typeof notUndefinedOptions.ipv6Subnet !== "function") {
+    validations2.ipv6Subnet(notUndefinedOptions.ipv6Subnet);
+  }
+  validations2.keyGeneratorIpFallback(notUndefinedOptions.keyGenerator);
+  validations2.ipv6SubnetOrKeyGenerator(notUndefinedOptions);
   let standardHeaders = notUndefinedOptions.standardHeaders ?? false;
   if (standardHeaders === true) standardHeaders = "draft-6";
   const config = {
@@ -652,21 +702,27 @@ var parseOptions = (passedOptions) => {
     skipSuccessfulRequests: false,
     requestWasSuccessful: (_request, response) => response.statusCode < 400,
     skip: (_request, _response) => false,
-    keyGenerator(request, _response) {
+    async keyGenerator(request, response) {
       validations2.ip(request.ip);
       validations2.trustProxy(request);
       validations2.xForwardedForHeader(request);
-      return request.ip;
+      const ip = request.ip;
+      let subnet = 56;
+      if ((0, import_node_net3.isIPv6)(ip)) {
+        subnet = typeof config.ipv6Subnet === "function" ? await config.ipv6Subnet(request, response) : config.ipv6Subnet;
+        if (typeof config.ipv6Subnet === "function")
+          validations2.ipv6Subnet(subnet);
+      }
+      return ipKeyGenerator(ip, subnet);
     },
+    ipv6Subnet: 56,
     async handler(request, response, _next, _optionsUsed) {
       response.status(config.statusCode);
       const message = typeof config.message === "function" ? await config.message(
         request,
         response
       ) : config.message;
-      if (!response.writableEnded) {
-        response.send(message);
-      }
+      if (!response.writableEnded) response.send(message);
     },
     passOnStoreError: false,
     // Allow the default options to be overridden by the passed options.
@@ -734,7 +790,8 @@ var rateLimit = (passedOptions) => {
         limit,
         used: totalHits,
         remaining: Math.max(limit - totalHits, 0),
-        resetTime
+        resetTime,
+        key
       };
       Object.defineProperty(info, "current", {
         configurable: false,
@@ -814,10 +871,11 @@ var rateLimit = (passedOptions) => {
   middleware.getKey = typeof config.store.get === "function" ? config.store.get.bind(config.store) : getThrowFn;
   return middleware;
 };
-var lib_default = rateLimit;
+var rate_limit_default = rateLimit;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   MemoryStore,
+  ipKeyGenerator,
   rateLimit
 });
-module.exports = rateLimit; module.exports.default = rateLimit; module.exports.rateLimit = rateLimit; module.exports.MemoryStore = MemoryStore;
+module.exports = Object.assign(rateLimit, module.exports);