nextlimiter 1.0.4 → 1.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextlimiter",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "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",

package/src/analytics/prometheus.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * Pure Node.js Prometheus Exposition Formatter
+ * Zero dependencies. Converts limiter stats to valid Prometheus text format.
+ */
+
+class PrometheusFormatter {
+  constructor(limiter) {
+    this.limiter = limiter;
+  }
+
+  contentType() {
+    return 'text/plain; version=0.0.4; charset=utf-8';
+  }
+
+  /**
+   * Escape label values according to Prometheus rules:
+   * \ -> \\
+   * " -> \"
+   * \n -> \n
+   */
+  _escapeLabel(str) {
+    return String(str)
+      .replace(/\\/g, '\\\\')
+      .replace(/"/g, '\\"')
+      .replace(/\n/g, '\\n');
+  }
+
+  /**
+   * Format a single metric block (help, type, and samples).
+   */
+  _metricBlock(name, help, type, samples) {
+    if (!samples || samples.length === 0) return '';
+    let block = `# HELP ${name} ${help}\n`;
+    block += `# TYPE ${name} ${type}\n`;
+
+    for (const sample of samples) {
+      const labelEntries = Object.entries(sample.labels || {});
+      if (labelEntries.length > 0) {
+        const labelStrs = labelEntries.map(([k, v]) => `${k}="${this._escapeLabel(v)}"`);
+        block += `${name}{${labelStrs.join(',')}} ${sample.value}\n`;
+      } else {
+        block += `${name} ${sample.value}\n`;
+      }
+    }
+    return block + '\n';
+  }
+
+  format() {
+    const stats = this.limiter.getStats();
+    let output = '';
+
+    // 1. Total requests (Counter)
+    output += this._metricBlock(
+      'nextlimiter_requests_total',
+      'Total requests processed by nextlimiter',
+      'counter',
+      [
+        { labels: { status: 'allowed' }, value: stats.allowedRequests },
+        { labels: { status: 'blocked' }, value: stats.blockedRequests }
+      ]
+    );
+
+    // 2. Block rate (Gauge)
+    output += this._metricBlock(
+      'nextlimiter_block_rate',
+      'Ratio of blocked to total requests (0.0 to 1.0)',
+      'gauge',
+      [{ labels: {}, value: isNaN(stats.blockRate) ? 0 : stats.blockRate }]
+    );
+
+    // 3. Top blocked IPs (Gauge)
+    const topBlockedSamples = (stats.topBlocked || []).slice(0, 10).map((item) => {
+      // Clean up IP label
+      let ip = item.key.replace(/^nextlimiter:(ip:)?/, '');
+      return { labels: { ip }, value: item.count };
+    });
+    if (topBlockedSamples.length > 0) {
+      output += this._metricBlock(
+        'nextlimiter_top_blocked_ip',
+        'Block count per offending IP',
+        'gauge',
+        topBlockedSamples
+      );
+    }
+
+    // 4. Top keys by volume (Gauge)
+    const topKeysSamples = (stats.topKeys || []).slice(0, 10).map((item) => {
+      return { labels: { key: item.key }, value: item.count };
+    });
+    if (topKeysSamples.length > 0) {
+      output += this._metricBlock(
+        'nextlimiter_top_keys_total',
+        'Total request count per key',
+        'gauge',
+        topKeysSamples
+      );
+    }
+
+    // 5. Uptime seconds (Gauge)
+    output += this._metricBlock(
+      'nextlimiter_uptime_seconds',
+      'Seconds since limiter was created',
+      'gauge',
+      [{ labels: {}, value: stats.uptimeMs / 1000 }]
+    );
+
+    // 6. Info (Gauge = 1)
+    const version = '1.0.5'; // Current pkg version
+    output += this._metricBlock(
+      'nextlimiter_info',
+      'Static info about the limiter instance',
+      'gauge',
+      [{ labels: { strategy: stats.config.strategy, version }, value: 1 }]
+    );
+
+    return output;
+  }
+}
+
+module.exports = { PrometheusFormatter };

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,13 @@ 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 { PrometheusFormatter }     = require('../analytics/prometheus');
 
 const STRATEGY_MAP = {
   'fixed-window':   fixedWindowCheck,
@@ -82,6 +85,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}`;
 
@@ -127,6 +147,41 @@ class Limiter {
     };
   }
 
+  /**
+   * Express route handler for serving Prometheus metrics.
+   * Exposes getStats() data in plain text format (version=0.0.4).
+   *
+   * @example
+   * app.get('/metrics', limiter.metricsHandler());
+   */
+  metricsHandler() {
+    return (req, res) => {
+      try {
+        const formatter = new PrometheusFormatter(this);
+        res.set('Content-Type', formatter.contentType());
+        res.send(formatter.format());
+      } catch (err) {
+        res.status(500).type('text/plain').send(`Error generating metrics: ${err.message}`);
+      }
+    };
+  }
+
+  /**
+   * Global middleware that automatically intercepts GET /metrics requests
+   * and serves the Prometheus exposition format. Passes through all other routes.
+   *
+   * @example
+   * app.use(limiter.metricsMiddleware());
+   */
+  metricsMiddleware() {
+    return (req, res, next) => {
+      if (req.method === 'GET' && req.path === '/metrics') {
+        return this.metricsHandler()(req, res);
+      }
+      next();
+    };
+  }
+
   /**
    * Programmatic rate limit check — use outside of HTTP middleware context.
    *
@@ -138,6 +193,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,8 @@ 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');
+const { PrometheusFormatter } = require('./analytics/prometheus');
 
 /**
  * Create a fully configured rate limiter instance.
@@ -102,6 +104,13 @@ module.exports = {
   MemoryStore,
   RedisStore,
 
+  // CIDR utilities (for advanced use)
+  ipMatchesCidr,
+  ipMatchesList,
+
+  // Analytics export
+  PrometheusFormatter,
+
   // 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 ────────────────────────────────────────────────────────
@@ -133,6 +139,12 @@ export interface RateLimitResult {
 
 // ── Analytics ────────────────────────────────────────────────────────────────
 
+export declare class PrometheusFormatter {
+  constructor(limiter: Limiter);
+  format(): string;
+  contentType(): string;
+}
+
 export interface KeyCount {
   key: string;
   count: number;
@@ -175,6 +187,18 @@ export declare class Limiter {
   /** Returns an Express-compatible middleware function */
   middleware(): (req: Request, res: Response, next: NextFunction) => Promise<void>;
 
+  /**
+   * Express route handler for serving Prometheus metrics.
+   * Exposes getStats() data in plain text format (version=0.0.4).
+   */
+  metricsHandler(): (req: any, res: any) => void;
+
+  /**
+   * Global middleware that automatically intercepts GET /metrics requests.
+   * Passes through all other routes.
+   */
+  metricsMiddleware(): (req: any, res: any, next: any) => void;
+
   /** Programmatic rate limit check by key string */
   check(key: string): Promise<RateLimitResult>;
 
@@ -271,6 +295,18 @@ 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>;