express-rate-limit 7.5.0 → 8.0.0

package/dist/index.mjs

@@ -1,13 +1,187 @@
+// source/ip-key-generator.ts
+import { isIPv6 } from "node:net";
+import iptools from "ip";
+function ipKeyGenerator(ip, ipv6Subnet = 56) {
+  if (ipv6Subnet && isIPv6(ip)) {
+    return `${iptools.mask(
+      ip,
+      iptools.fromPrefixLen(ipv6Subnet)
+    )}/${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
+import { isIPv6 as isIPv62 } from "node:net";
+
 // 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;
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+var SUPPORTED_DRAFT_VERSIONS = [
+  "draft-6",
+  "draft-7",
+  "draft-8"
+];
+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;
@@ -19,8 +193,7 @@ var getPartitionKey = (key) => {
   return Buffer.from(partitionKey).toString("base64");
 };
 var setLegacyHeaders = (response, info) => {
-  if (response.headersSent)
-    return;
+  if (response.headersSent) return;
   response.setHeader("X-RateLimit-Limit", info.limit.toString());
   response.setHeader("X-RateLimit-Remaining", info.remaining.toString());
   if (info.resetTime instanceof Date) {
@@ -32,10 +205,9 @@ var setLegacyHeaders = (response, info) => {
   }
 };
 var setDraft6Headers = (response, info, windowMs) => {
-  if (response.headersSent)
-    return;
+  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());
@@ -43,10 +215,9 @@ var setDraft6Headers = (response, info, windowMs) => {
     response.setHeader("RateLimit-Reset", resetSeconds.toString());
 };
 var setDraft7Headers = (response, info, windowMs) => {
-  if (response.headersSent)
-    return;
+  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",
@@ -54,25 +225,35 @@ var setDraft7Headers = (response, info, windowMs) => {
   );
 };
 var setDraft8Headers = (response, info, windowMs, name, key) => {
-  if (response.headersSent)
-    return;
+  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);
+  if (response.headersSent) return;
+  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
-import { isIP } from "net";
+import { isIP } from "node:net";
 var ValidationError = class extends Error {
   /**
    * The code must be a string, in snake case and all capital, that starts with
@@ -94,14 +275,12 @@ 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
   },
   // Should be EnabledValidations type, but that's a circular reference
   disable() {
-    for (const k of Object.keys(this.enabled))
-      this.enabled[k] = false;
+    for (const k of Object.keys(this.enabled)) this.enabled[k] = false;
   },
   /**
    * Checks whether the IP address is valid, and that it does not have a port
@@ -274,7 +453,8 @@ var validations = {
    * @returns {void}
    */
   headersDraftVersion(version) {
-    if (typeof version !== "string" || !SUPPORTED_DRAFT_VERSIONS.includes(version)) {
+    if (typeof version !== "string" || // @ts-expect-error This is fine. If version is not in the array, it will just return false.
+    !SUPPORTED_DRAFT_VERSIONS.includes(version)) {
       const versionString = SUPPORTED_DRAFT_VERSIONS.join(", ");
       throw new ValidationError(
         "ERR_ERL_HEADERS_UNSUPPORTED_DRAFT_VERSION",
@@ -330,7 +510,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",
@@ -342,6 +523,37 @@ var validations = {
         `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.`
+      );
+    }
   }
 };
 var getValidations = (_enabled) => {
@@ -356,9 +568,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) => {
@@ -372,175 +582,15 @@ var getValidations = (_enabled) => {
             args
           );
         } catch (error) {
-          if (error instanceof ChangeWarning)
-            console.warn(error);
-          else
-            console.error(error);
+          if (error instanceof ChangeWarning) console.warn(error);
+          else console.error(error);
         }
       };
   }
   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.
@@ -557,8 +607,7 @@ var promisifyStore = (passedStore) => {
         legacyStore.incr(
           key,
           (error, totalHits, resetTime) => {
-            if (error)
-              reject(error);
+            if (error) reject(error);
             resolve({ totalHits, resetTime });
           }
         );
@@ -585,18 +634,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(
@@ -604,9 +643,13 @@ 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";
+  if (standardHeaders === true) standardHeaders = "draft-6";
   const config = {
     windowMs: 60 * 1e3,
     limit: passedOptions.max ?? 5,
@@ -622,14 +665,10 @@ var parseOptions = (passedOptions) => {
       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" : ""}`;
+      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",
@@ -637,29 +676,35 @@ 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 (isIPv62(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 overriden by the passed options.
+    // Allow the default options to be overridden by the passed options.
     ...notUndefinedOptions,
     // `standardHeaders` is resolved into a draft version above, use that.
     standardHeaders,
     // 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!
+    // so that this field doesn't get overridden with an un-promisified store!
     store: promisifyStore(notUndefinedOptions.store ?? new MemoryStore()),
     // Print an error to the console if a few known misconfigurations are detected.
     validations: validations2
@@ -683,8 +728,7 @@ var rateLimit = (passedOptions) => {
   const options = getOptionsFromConfig(config);
   config.validations.creationStack(config.store);
   config.validations.unsharedStore(config.store);
-  if (typeof config.store.init === "function")
-    config.store.init(options);
+  if (typeof config.store.init === "function") config.store.init(options);
   const middleware = handleAsyncErrors(
     async (request, response, next) => {
       const skip = await config.skip(request, response);
@@ -720,7 +764,8 @@ var rateLimit = (passedOptions) => {
         limit,
         used: totalHits,
         remaining: Math.max(limit - totalHits, 0),
-        resetTime
+        resetTime,
+        key
       };
       Object.defineProperty(info, "current", {
         configurable: false,
@@ -769,8 +814,7 @@ var rateLimit = (passedOptions) => {
               await decrementKey();
           });
           response.on("close", async () => {
-            if (!response.writableEnded)
-              await decrementKey();
+            if (!response.writableEnded) await decrementKey();
           });
           response.on("error", async () => {
             await decrementKey();
@@ -801,9 +845,10 @@ 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;
 export {
   MemoryStore,
-  lib_default as default,
-  lib_default as rateLimit
+  rate_limit_default as default,
+  ipKeyGenerator,
+  rate_limit_default as rateLimit
 };