nextlimiter 1.0.3 → 1.0.5

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "nextlimiter",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Production-ready rate limiting for Node.js — sliding window, token bucket, SaaS plans, smart limiting, and built-in analytics.",
   "main": "src/index.js",
   "types": "types/index.d.ts",
+  "exports": {
+    ".": "./src/index.js",
+    "./fastify": "./src/adapters/fastify.js",
+    "./next": "./src/adapters/next.js",
+    "./hono": "./src/adapters/hono.js"
+  },
   "files": [
     "src/",
     "types/",
@@ -36,7 +42,10 @@
   },
   "peerDependencies": {
     "express": ">=4.0.0",
-    "ioredis": ">=4.0.0"
+    "ioredis": ">=4.0.0",
+    "fastify": ">=4.0.0",
+    "fastify-plugin": ">=4.0.0",
+    "hono": ">=3.0.0"
   },
   "peerDependenciesMeta": {
     "express": {
@@ -44,6 +53,15 @@
     },
     "ioredis": {
       "optional": true
+    },
+    "fastify": {
+      "optional": true
+    },
+    "fastify-plugin": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
     }
   },
   "devDependencies": {

package/src/adapters/fastify.js

@@ -0,0 +1,80 @@
+'use strict';
+
+/**
+ * NextLimiter — Fastify adapter
+ *
+ * Registers a Fastify plugin that applies rate limiting via an onRequest hook.
+ * Uses the same createLimiter() core — no rate limit logic lives here.
+ *
+ * Peer dependency: fastify-plugin (npm install fastify-plugin)
+ *
+ * @example
+ * const fastify = require('fastify')();
+ * const fastifyRateLimit = require('nextlimiter/fastify');
+ *
+ * fastify.register(fastifyRateLimit, { max: 100, windowMs: 60_000 });
+ */
+
+const { createLimiter } = require('../index');
+
+/**
+ * Extract the best available IP from a Fastify request.
+ * @param {object} request - Fastify request object
+ * @returns {string}
+ */
+function extractIp(request) {
+  return (
+    request.headers['cf-connecting-ip'] ||
+    request.headers['x-forwarded-for']?.split(',')[0]?.trim() ||
+    request.ip ||
+    'unknown'
+  );
+}
+
+/**
+ * Fastify plugin factory.
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {object} options - Same options as createLimiter()
+ * @param {function} done
+ */
+async function plugin(fastify, options) {
+  const limiter = createLimiter(options);
+
+  fastify.addHook('onRequest', async (request, reply) => {
+    try {
+      const ip     = extractIp(request);
+      const result = await limiter.check(ip);
+
+      if (!result.allowed) {
+        return reply.code(429).send({
+          error:      'Too Many Requests',
+          retryAfter: result.retryAfter,
+          limit:      result.limit,
+          resetAt:    new Date(result.resetAt).toISOString(),
+        });
+      }
+
+      // Set rate limit headers on allowed requests
+      reply.header('X-RateLimit-Limit',     String(result.limit));
+      reply.header('X-RateLimit-Remaining', String(result.remaining));
+      reply.header('X-RateLimit-Reset',     String(Math.ceil(result.resetAt / 1000)));
+      reply.header('X-RateLimit-Strategy',  result.strategy);
+    } catch (err) {
+      // Fail open — never let the rate limiter take down the app
+      request.log.warn(`[NextLimiter] Rate limiter error: ${err.message}. Failing open.`);
+    }
+  });
+}
+
+let fastifyPlugin;
+try {
+  fastifyPlugin = require('fastify-plugin');
+} catch {
+  // If fastify-plugin is not installed, wrap minimally so the plugin still works
+  fastifyPlugin = (fn, meta) => fn;
+}
+
+module.exports = fastifyPlugin(plugin, {
+  fastify:  '>=4.0.0',
+  name:     'nextlimiter',
+});

package/src/adapters/hono.js

@@ -0,0 +1,87 @@
+'use strict';
+
+/**
+ * NextLimiter — Hono adapter
+ *
+ * Provides a Hono-compatible middleware factory for Cloudflare Workers,
+ * Bun, Deno, and any edge runtime supported by Hono.
+ *
+ * Uses Web APIs only (fetch/Request/Response/Headers) — no Node.js built-ins.
+ * Safe to deploy on Cloudflare Workers, Vercel Edge, and Deno Deploy.
+ *
+ * No peer dependencies required beyond Hono itself.
+ *
+ * @example
+ * const { Hono } = require('hono');
+ * const { rateLimitMiddleware } = require('nextlimiter/hono');
+ *
+ * const app = new Hono();
+ * app.use('*', rateLimitMiddleware({ max: 100, windowMs: 60_000 }));
+ *
+ * app.get('/', (c) => c.text('Hello World!'));
+ * export default app;
+ */
+
+const { createLimiter } = require('../index');
+
+/**
+ * Extract the real client IP from a Hono context.
+ * Prioritises Cloudflare's CF-Connecting-IP header, then X-Forwarded-For.
+ *
+ * @param {import('hono').Context} c
+ * @returns {string}
+ */
+function extractIp(c) {
+  return (
+    c.req.header('cf-connecting-ip') ||
+    c.req.header('x-forwarded-for')?.split(',')[0]?.trim() ||
+    c.req.header('x-real-ip') ||
+    'unknown'
+  );
+}
+
+/**
+ * Hono middleware factory.
+ *
+ * @param {object} options - Same options as createLimiter()
+ * @returns {import('hono').MiddlewareHandler}
+ *
+ * @example
+ * app.use('/api/*', rateLimitMiddleware({ max: 100, windowMs: 60_000, strategy: 'sliding-window' }));
+ */
+function rateLimitMiddleware(options = {}) {
+  const limiter = createLimiter(options);
+
+  return async function honoRateLimitMiddleware(c, next) {
+    try {
+      const ip     = extractIp(c);
+      const result = await limiter.check(ip);
+
+      if (!result.allowed) {
+        return c.json(
+          {
+            error:      'Too Many Requests',
+            retryAfter: result.retryAfter,
+            limit:      result.limit,
+            resetAt:    new Date(result.resetAt).toISOString(),
+          },
+          429
+        );
+      }
+
+      // Set rate limit headers before passing to next handler
+      c.header('X-RateLimit-Limit',     String(result.limit));
+      c.header('X-RateLimit-Remaining', String(result.remaining));
+      c.header('X-RateLimit-Reset',     String(Math.ceil(result.resetAt / 1000)));
+      c.header('X-RateLimit-Strategy',  result.strategy);
+
+      await next();
+    } catch (err) {
+      // Fail open — never let the rate limiter crash the Hono app
+      console.warn(`[NextLimiter] Rate limiter error: ${err.message}. Failing open.`);
+      await next();
+    }
+  };
+}
+
+module.exports = { rateLimitMiddleware };

package/src/adapters/next.js

@@ -0,0 +1,157 @@
+'use strict';
+
+/**
+ * NextLimiter — Next.js adapter
+ *
+ * Provides two higher-order wrappers:
+ *   withRateLimit()     — for Next.js Pages Router API routes (Node.js runtime)
+ *   withRateLimitEdge() — for App Router / middleware.js (Edge runtime, Web APIs only)
+ *
+ * No peer dependencies required.
+ *
+ * @example
+ * // Pages Router (pages/api/hello.js)
+ * const { withRateLimit } = require('nextlimiter/next');
+ * export default withRateLimit(handler, { max: 100, windowMs: 60_000 });
+ *
+ * // App Router / Edge (middleware.js)
+ * const { withRateLimitEdge } = require('nextlimiter/next');
+ * export default withRateLimitEdge(handler, { max: 50 });
+ */
+
+const { createLimiter } = require('../index');
+
+// ── Shared helpers ────────────────────────────────────────────────────────────
+
+/**
+ * Memoize limiter instances per options reference so the limiter is only
+ * created once per HOC call, not on every request.
+ */
+const limiterCache = new WeakMap();
+
+function getLimiter(options) {
+  if (limiterCache.has(options)) return limiterCache.get(options);
+  const limiter = createLimiter(options);
+  limiterCache.set(options, limiter);
+  return limiter;
+}
+
+// ── Pages Router (Node.js runtime) ───────────────────────────────────────────
+
+/**
+ * Higher-order function for Next.js Pages Router API routes.
+ * Wraps a handler with rate limiting using the Node.js HTTP req/res API.
+ *
+ * @param {function} handler - Next.js API route handler (req, res) => void
+ * @param {object}   options - createLimiter() options
+ * @returns {function} wrapped async handler
+ *
+ * @example
+ * export default withRateLimit(async (req, res) => {
+ *   res.json({ hello: 'world' });
+ * }, { max: 100, windowMs: 60_000 });
+ */
+function withRateLimit(handler, options = {}) {
+  const limiter = getLimiter(options);
+
+  return async function rateLimitedHandler(req, res) {
+    try {
+      const ip =
+        (req.headers['x-forwarded-for']?.split(',')[0]?.trim()) ||
+        req.socket?.remoteAddress ||
+        'unknown';
+
+      const result = await limiter.check(ip);
+
+      if (!result.allowed) {
+        return res.status(429).json({
+          error:      'Too Many Requests',
+          retryAfter: result.retryAfter,
+          limit:      result.limit,
+          resetAt:    new Date(result.resetAt).toISOString(),
+        });
+      }
+
+      // Set rate limit headers
+      res.setHeader('X-RateLimit-Limit',     String(result.limit));
+      res.setHeader('X-RateLimit-Remaining', String(result.remaining));
+      res.setHeader('X-RateLimit-Reset',     String(Math.ceil(result.resetAt / 1000)));
+      res.setHeader('X-RateLimit-Strategy',  result.strategy);
+
+      return handler(req, res);
+    } catch (err) {
+      // Fail open — never let the rate limiter crash the API route
+      console.warn(`[NextLimiter] Rate limiter error: ${err.message}. Failing open.`);
+      return handler(req, res);
+    }
+  };
+}
+
+// ── App Router / Edge runtime (Web APIs only) ─────────────────────────────────
+
+/**
+ * Higher-order function for Next.js App Router or middleware.js.
+ * Uses Web Request/Response API only — no Node.js built-ins.
+ * Safe to run on Vercel Edge, Cloudflare Workers, and Deno.
+ *
+ * @param {function} handler - async (request: Request) => Response
+ * @param {object}   options - createLimiter() options
+ * @returns {function} wrapped async handler
+ *
+ * @example
+ * // middleware.js
+ * export default withRateLimitEdge(async (req) => {
+ *   return new Response('OK');
+ * }, { max: 50, windowMs: 60_000 });
+ */
+function withRateLimitEdge(handler, options = {}) {
+  const limiter = getLimiter(options);
+
+  return async function rateLimitedEdgeHandler(request) {
+    try {
+      const ip =
+        request.headers.get('cf-connecting-ip') ||
+        request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ||
+        'unknown';
+
+      const result = await limiter.check(ip);
+
+      if (!result.allowed) {
+        return new Response(
+          JSON.stringify({
+            error:      'Too Many Requests',
+            retryAfter: result.retryAfter,
+            limit:      result.limit,
+            resetAt:    new Date(result.resetAt).toISOString(),
+          }),
+          {
+            status:  429,
+            headers: { 'Content-Type': 'application/json' },
+          }
+        );
+      }
+
+      // Call the handler and inject rate limit headers into the response
+      const response = await handler(request);
+
+      // Clone with additional headers (Response is immutable)
+      const headers = new Headers(response.headers);
+      headers.set('X-RateLimit-Limit',     String(result.limit));
+      headers.set('X-RateLimit-Remaining', String(result.remaining));
+      headers.set('X-RateLimit-Reset',     String(Math.ceil(result.resetAt / 1000)));
+      headers.set('X-RateLimit-Strategy',  result.strategy);
+
+      return new Response(response.body, {
+        status:     response.status,
+        statusText: response.statusText,
+        headers,
+      });
+    } catch (err) {
+      // Fail open
+      console.warn(`[NextLimiter] Rate limiter error: ${err.message}. Failing open.`);
+      return handler(request);
+    }
+  };
+}
+
+module.exports = { withRateLimit, withRateLimitEdge };

package/src/core/accessControl.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const { ipMatchesList } = require('../utils/cidr');
+
+/**
+ * Access control check — evaluated BEFORE rate limiting.
+ *
+ * Precedence: blacklist > whitelist > allow
+ *
+ * @param {string} ip     - Client's real IP address
+ * @param {object} config - Resolved NextLimiter config
+ * @returns {{ action: 'allow'|'block'|'skip', reason: string }}
+ *
+ * @example
+ * checkAccess('5.6.1.1', { blacklist: ['5.6.0.0/16'] })
+ * // → { action: 'block', reason: 'blacklisted' }
+ *
+ * checkAccess('10.0.5.5', { whitelist: ['10.0.0.0/8'] })
+ * // → { action: 'skip', reason: 'whitelisted' }
+ *
+ * checkAccess('1.2.3.4', {})
+ * // → { action: 'allow', reason: 'proceed' }
+ */
+function checkAccess(ip, config) {
+  // Blacklist wins — always checked first regardless of whitelist
+  if (config.blacklist && ipMatchesList(ip, config.blacklist)) {
+    return { action: 'block', reason: 'blacklisted' };
+  }
+
+  // Whitelist — bypass all rate limiting
+  if (config.whitelist && ipMatchesList(ip, config.whitelist)) {
+    return { action: 'skip', reason: 'whitelisted' };
+  }
+
+  return { action: 'allow', reason: 'proceed' };
+}
+
+module.exports = { checkAccess };

package/src/core/config.js

@@ -85,6 +85,8 @@ const DEFAULT_CONFIG = {
   plans: DEFAULT_PLANS,     // plan map — override to define custom plans
   preset: null,             // 'strict' | 'relaxed' | 'api' | 'auth'
   keyGenerator: null,       // (req) => string — custom key fn
+  whitelist:     null,       // string[] — IPs/CIDRs that bypass rate limiting
+  blacklist:     null,       // string[] — IPs/CIDRs that always get 403
 };
 
 /**
@@ -121,6 +123,30 @@ function resolveConfig(userOptions = {}) {
   if (base.max <= 0) throw new Error('[NextLimiter] config.max must be greater than 0');
   if (base.windowMs <= 0) throw new Error('[NextLimiter] config.windowMs must be greater than 0');
 
+  // Validate whitelist / blacklist (warn, never throw)
+  for (const listName of ['whitelist', 'blacklist']) {
+    const list = base[listName];
+    if (list == null) continue;
+    if (!Array.isArray(list)) {
+      console.warn(`[NextLimiter] config.${listName} must be an array. Ignoring.`);
+      base[listName] = null;
+      continue;
+    }
+    const valid = [];
+    for (const entry of list) {
+      if (typeof entry !== 'string' || entry.trim() === '') {
+        console.warn(`[NextLimiter] config.${listName}: skipping invalid entry:`, entry);
+        continue;
+      }
+      // Loose format check: must look like x.x.x.x or x.x.x.x/n
+      if (!/^\d{1,3}(\.\d{1,3}){3}(\/\d{1,2})?$/.test(entry.trim())) {
+        console.warn(`[NextLimiter] config.${listName}: entry "${entry}" doesn't look like a valid IP or CIDR. It will be attempted anyway.`);
+      }
+      valid.push(entry.trim());
+    }
+    base[listName] = valid.length > 0 ? valid : null;
+  }
+
   return base;
 }
 

package/src/core/limiter.js

@@ -6,10 +6,12 @@ const { fixedWindowCheck }        = require('../strategies/fixedWindow');
 const { slidingWindowCheck }      = require('../strategies/slidingWindow');
 const { tokenBucketCheck }        = require('../strategies/tokenBucket');
 const { resolveKeyGenerator }     = require('../utils/keyGenerator');
+const { extractIp }               = require('../utils/keyGenerator');
 const { createLogger }            = require('../utils/logger');
 const { AnalyticsTracker }        = require('../analytics/tracker');
 const { SmartDetector }           = require('../smart/detector');
 const { setHeaders }              = require('../middleware/headers');
+const { checkAccess }             = require('./accessControl');
 
 const STRATEGY_MAP = {
   'fixed-window':   fixedWindowCheck,
@@ -82,6 +84,23 @@ class Limiter {
           return next();
         }
 
+        // ── Access control (whitelist / blacklist) ───────────────────────────
+        const clientIp = extractIp(req);
+        const access   = checkAccess(clientIp, this._config);
+
+        if (access.action === 'block') {
+          return res.status(403).json({
+            error:   'Forbidden',
+            message: 'Your IP address has been blocked.',
+          });
+        }
+
+        if (access.action === 'skip') {
+          // Whitelisted — bypass all rate limiting, proceed immediately
+          return next();
+        }
+        // ────────────────────────────────────────────────────────────────────
+
         const rawKey = this._keyGenerator(req);
         const key    = `${this._config.keyPrefix}${rawKey}`;
 
@@ -138,6 +157,39 @@ class Limiter {
    * if (!result.allowed) throw new Error('Rate limit exceeded');
    */
   async check(key) {
+    // Apply access control if the key looks like a plain IP address
+    const looksLikeIp = /^\d{1,3}(\.\d{1,3}){3}$/.test(String(key).trim());
+    if (looksLikeIp) {
+      const access = checkAccess(key, this._config);
+      if (access.action === 'block') {
+        return {
+          allowed:      false,
+          limit:        this._config.max,
+          remaining:    0,
+          resetAt:      Date.now(),
+          retryAfter:   0,
+          key,
+          strategy:     this._config.strategy,
+          smartBlocked: false,
+          blocked:      true,
+          reason:       'blacklisted',
+        };
+      }
+      if (access.action === 'skip') {
+        return {
+          allowed:    true,
+          limit:      this._config.max,
+          remaining:  Infinity,
+          resetAt:    Date.now() + this._config.windowMs,
+          retryAfter: 0,
+          key,
+          strategy:   this._config.strategy,
+          smartBlocked: false,
+          reason:     'whitelisted',
+        };
+      }
+    }
+
     const fullKey = `${this._config.keyPrefix}${key}`;
     const result  = await this._runCheck(fullKey);
     this._analytics.record(fullKey, result.allowed);

package/src/index.js

@@ -4,6 +4,7 @@ const { Limiter }     = require('./core/limiter');
 const { PRESETS, DEFAULT_PLANS } = require('./core/config');
 const { MemoryStore } = require('./store/memoryStore');
 const { RedisStore }  = require('./store/redisStore');
+const { ipMatchesCidr, ipMatchesList } = require('./utils/cidr');
 
 /**
  * Create a fully configured rate limiter instance.
@@ -102,6 +103,10 @@ module.exports = {
   MemoryStore,
   RedisStore,
 
+  // CIDR utilities (for advanced use)
+  ipMatchesCidr,
+  ipMatchesList,
+
   // Constants
   PRESETS,
   DEFAULT_PLANS,

package/src/utils/cidr.js

@@ -0,0 +1,136 @@
+'use strict';
+
+/**
+ * CIDR IP matching utilities — zero dependencies, pure bitwise arithmetic.
+ * Works in any runtime: Node.js, Cloudflare Workers, Deno, Bun, Edge.
+ *
+ * No Buffer, no `net` module, no external libraries.
+ */
+
+/**
+ * Convert an IPv4 dotted-decimal string to a 32-bit unsigned integer.
+ *
+ * @param {string} ip - e.g. '192.168.1.50'
+ * @returns {number} 32-bit unsigned integer
+ * @throws {Error} if the string is not a valid IPv4 address
+ *
+ * @example
+ * ipToInt('1.2.3.4') // → 16909060
+ * ipToInt('0.0.0.0') // → 0
+ * ipToInt('255.255.255.255') // → 4294967295
+ */
+function ipToInt(ip) {
+  const parts = String(ip).split('.');
+  if (parts.length !== 4) {
+    throw new Error(`[NextLimiter] Invalid IPv4 address: "${ip}"`);
+  }
+  let result = 0;
+  for (const part of parts) {
+    const octet = parseInt(part, 10);
+    if (isNaN(octet) || octet < 0 || octet > 255 || String(octet) !== part.trim()) {
+      throw new Error(`[NextLimiter] Invalid IPv4 octet "${part}" in address "${ip}"`);
+    }
+    result = ((result << 8) | octet) >>> 0;
+  }
+  return result >>> 0; // ensure unsigned
+}
+
+/**
+ * Convert a CIDR string (or plain IP) to a { networkInt, maskInt } range.
+ *
+ * - '10.0.0.0/8'  → { networkInt: 167772160, maskInt: 4278190080 }
+ * - '1.2.3.4'     → treated as /32 (exact match only)
+ *
+ * @param {string} cidr - e.g. '192.168.1.0/24' or '1.2.3.4'
+ * @returns {{ networkInt: number, maskInt: number }}
+ * @throws {Error} on invalid CIDR
+ *
+ * @example
+ * cidrToRange('10.0.0.0/8')
+ * // → { networkInt: 167772160, maskInt: 4278190080 }
+ *
+ * cidrToRange('192.168.1.0/24')
+ * // → { networkInt: 3232235776, maskInt: 4294967040 }
+ */
+function cidrToRange(cidr) {
+  const slashIdx = String(cidr).indexOf('/');
+
+  if (slashIdx === -1) {
+    // Plain IP — treat as /32
+    const networkInt = ipToInt(cidr);
+    return { networkInt, maskInt: 0xFFFFFFFF >>> 0 };
+  }
+
+  const ip     = cidr.slice(0, slashIdx);
+  const prefix = parseInt(cidr.slice(slashIdx + 1), 10);
+
+  if (isNaN(prefix) || prefix < 0 || prefix > 32) {
+    throw new Error(`[NextLimiter] Invalid CIDR prefix in "${cidr}"`);
+  }
+
+  // Build the subnet mask: ( all 1s ) left-shifted by (32 - prefix), force unsigned
+  // Special case: prefix 0 → mask is 0 (matches everything)
+  const maskInt    = prefix === 0 ? 0 : ((0xFFFFFFFF << (32 - prefix)) >>> 0);
+  const networkInt = (ipToInt(ip) & maskInt) >>> 0;
+
+  return { networkInt, maskInt };
+}
+
+/**
+ * Check whether an IP address falls within a CIDR range (or matches a plain IP).
+ *
+ * @param {string} ip   - e.g. '10.0.1.5'
+ * @param {string} cidr - e.g. '10.0.0.0/8' or '10.0.1.5'
+ * @returns {boolean}
+ *
+ * @example
+ * ipMatchesCidr('10.0.1.5',    '10.0.0.0/8')       // → true
+ * ipMatchesCidr('192.168.1.50','192.168.1.0/24')    // → true
+ * ipMatchesCidr('1.2.3.4',     '1.2.3.4')           // → true  (exact /32)
+ * ipMatchesCidr('1.2.3.5',     '1.2.3.4')           // → false
+ * ipMatchesCidr('172.0.0.1',   '10.0.0.0/8')        // → false
+ */
+function ipMatchesCidr(ip, cidr) {
+  try {
+    const ipInt = ipToInt(ip);
+    const range = cidrToRange(cidr);
+    return ((ipInt & range.maskInt) >>> 0) === range.networkInt;
+  } catch {
+    // Any parse failure → conservative answer: not a match
+    return false;
+  }
+}
+
+/**
+ * Check whether an IP matches ANY entry in a list of IPs or CIDR ranges.
+ *
+ * @param {string}   ip   - Client IP to test
+ * @param {string[]} list - Array of IPs or CIDR strings
+ * @returns {boolean} true if ip matches at least one entry
+ *
+ * @example
+ * ipMatchesList('10.0.5.5', ['10.0.0.0/8', '192.168.1.1'])  // → true
+ * ipMatchesList('11.0.0.1', ['10.0.0.0/8'])                 // → false
+ * ipMatchesList('1.2.3.4',  [])                              // → false
+ */
+function ipMatchesList(ip, list) {
+  if (!list || list.length === 0) return false;
+  for (const entry of list) {
+    if (ipMatchesCidr(ip, entry)) return true;
+  }
+  return false;
+}
+
+module.exports = { ipToInt, cidrToRange, ipMatchesCidr, ipMatchesList };
+
+// ── Inline test cases (run with node src/utils/cidr.js) ──────────────────────
+//
+// ipMatchesCidr('10.0.1.5',    '10.0.0.0/8')        → true
+// ipMatchesCidr('192.168.1.50','192.168.1.0/24')     → true
+// ipMatchesCidr('1.2.3.4',     '1.2.3.4')            → true  (exact /32)
+// ipMatchesCidr('1.2.3.5',     '1.2.3.4')            → false
+// ipMatchesCidr('172.0.0.1',   '10.0.0.0/8')         → false
+// ipMatchesList('10.0.5.5',    ['10.0.0.0/8'])        → true
+// ipMatchesList('11.0.0.1',    ['10.0.0.0/8'])        → false
+// ipMatchesList('5.6.1.1',     ['5.6.0.0/16'])        → true
+// ipMatchesList('5.7.0.1',     ['5.6.0.0/16'])        → false

package/src/utils/keyGenerator.js

@@ -26,6 +26,15 @@ function getIP(req) {
   );
 }
 
+/**
+ * Alias for getIP — exported for use by access control and other utils
+ * that need the raw client IP without a 'ip:' prefix.
+ *
+ * @param {object} req - Express / Node.js request object
+ * @returns {string}
+ */
+const extractIp = getIP;
+
 /**
  * Rate limit by authenticated user ID.
  * Looks for userId in: req.user.id → req.user._id → req.userId → req.auth.userId
@@ -92,4 +101,4 @@ function resolveKeyGenerator(keyBy) {
   }
 }
 
-module.exports = { getIP, getUserId, getApiKey, resolveKeyGenerator };
+module.exports = { getIP, extractIp, getUserId, getApiKey, resolveKeyGenerator };

package/types/index.d.ts

@@ -96,6 +96,12 @@ export interface LimiterOptions {
 
   /** Fully custom key generator function */
   keyGenerator?: (req: Request) => string;
+
+  /** Array of IPs or CIDR ranges to bypass rate limiting */
+  whitelist?: string[];
+
+  /** Array of IPs or CIDR ranges to block immediately (403) */
+  blacklist?: string[];
 }
 
 // ── Rate limit result ────────────────────────────────────────────────────────
@@ -271,7 +277,68 @@ export declare class RedisStore implements Store {
   clear(): void;
 }
 
+// ── Utilities ────────────────────────────────────────────────────────────────
+
+/**
+ * Check whether an IP matches a CIDR range string.
+ * Supports standard CIDR (10.0.0.0/8) and exact exact IPs (1.2.3.4).
+ */
+export declare function ipMatchesCidr(ip: string, cidr: string): boolean;
+
+/** Check whether an IP matches ANY element in a list of IPs / CIDR ranges. */
+export declare function ipMatchesList(ip: string, list: string[]): boolean;
+
+
 // ── Constants ────────────────────────────────────────────────────────────────
 
 export declare const PRESETS: Record<BuiltInPreset, LimiterOptions>;
 export declare const DEFAULT_PLANS: Record<BuiltInPlan, PlanDefinition>;
+
+// ── Adapters ─────────────────────────────────────────────────────────────────
+//
+// These are available as subpath imports:
+//   import fastifyRateLimit from 'nextlimiter/fastify'
+//   import { withRateLimit, withRateLimitEdge } from 'nextlimiter/next'
+//   import { rateLimitMiddleware } from 'nextlimiter/hono'
+
+// fastify adapter
+declare module 'nextlimiter/fastify' {
+  import { FastifyPluginAsync } from 'fastify';
+  const fastifyRateLimit: FastifyPluginAsync<LimiterOptions>;
+  export default fastifyRateLimit;
+}
+
+// next.js adapter
+declare module 'nextlimiter/next' {
+  import type { NextApiRequest, NextApiResponse } from 'next';
+
+  /**
+   * Wrap a Next.js Pages Router API handler with rate limiting (Node.js runtime).
+   */
+  export function withRateLimit<T extends (req: NextApiRequest, res: NextApiResponse) => any>(
+    handler: T,
+    options?: LimiterOptions
+  ): (req: NextApiRequest, res: NextApiResponse) => Promise<void>;
+
+  /**
+   * Wrap a Next.js App Router / middleware handler with rate limiting (Edge runtime).
+   * Uses Web Request / Response API only — no Node.js built-ins.
+   */
+  export function withRateLimitEdge<T extends (req: Request) => Promise<Response>>(
+    handler: T,
+    options?: LimiterOptions
+  ): (req: Request) => Promise<Response>;
+}
+
+// hono adapter
+declare module 'nextlimiter/hono' {
+  /**
+   * Returns a Hono middleware that applies rate limiting.
+   * Safe for Cloudflare Workers, Bun, Deno — uses Web APIs only.
+   *
+   * @example
+   * app.use('*', rateLimitMiddleware({ max: 100, windowMs: 60_000 }));
+   */
+  export function rateLimitMiddleware(options?: LimiterOptions): (c: any, next: () => Promise<void>) => Promise<void>;
+}
+