{"id":17614,"library":"express-ip-filter-middleware","title":"Express IP Filter Middleware","description":"express-ip-filter-middleware is an Express.js middleware designed for robust access control, enabling developers to filter incoming requests based on IP addresses or CIDR blocks. It leverages Node.js's built-in `net.BlockList` for efficient management of allowed and denied IP ranges. The current stable version is 2.0.2, with recent releases primarily focusing on dependency updates, indicating an active maintenance cadence. Key differentiators include its explicit `whitelist` and `blacklist` modes, which mimic Apache's `mod_access` behavior, offering precise control over how allow and deny rules interact. It also provides an `ipOverride` option for custom IP address extraction, making it flexible for environments behind proxies or load balancers.","status":"active","version":"2.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/sjinks/express-ip-filter-middleware","tags":["javascript","express","expressjs","middleware","ip","filter","IP address","access","typescript"],"install":[{"cmd":"npm install express-ip-filter-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add express-ip-filter-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add express-ip-filter-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for the middleware to function within an Express application.","package":"express","optional":false}],"imports":[{"note":"The primary middleware export is a named export. Default import or direct require without property access will result in an error in CommonJS.","wrong":"const ipFilterMiddleware = require('express-ip-filter-middleware');","symbol":"ipFilterMiddleware","correct":"import { ipFilterMiddleware } from 'express-ip-filter-middleware';"},{"note":"Use the `node:` protocol prefix for built-in Node.js modules for clarity and future-proofing.","wrong":"import { BlockList } from 'net';","symbol":"BlockList","correct":"import { BlockList } from 'node:net';"},{"note":"`express` is a default export, though type definitions often provide named exports for specific types (e.g., `Request`, `Response`).","wrong":"import { express } from 'express';","symbol":"express","correct":"import express from 'express';"}],"quickstart":{"code":"import { BlockList } from 'node:net';\nimport express from 'express';\nimport { ipFilterMiddleware } from 'express-ip-filter-middleware';\n\n// Create BlockList instances for allowed and denied IPs\nconst allow = new BlockList();\nallow.addSubnet('192.168.0.0', 16); // Allow entire 192.168.x.x network\nallow.addAddress('10.0.0.5'); // Allow a specific IP\n\nconst deny = new BlockList();\ndeny.addAddress('192.168.0.1'); // Deny a specific IP within the allowed subnet\n\n// Configure the middleware options\nconst options = {\n    mode: 'whitelist', // Only explicitly allowed IPs can access\n    allow,\n    deny,\n    // Example of overriding IP detection if behind a proxy\n    // ipOverride: (req) => req.headers['x-forwarded-for'] as string || req.ip,\n};\n\n// Initialize Express app and apply the IP filter middleware\nconst app = express();\napp.use(ipFilterMiddleware(options));\n\n// Define a protected route\napp.get('/', (req, res) => {\n    res.send('Welcome, authorized user!');\n});\n\n// Start the server\nconst PORT = 3000;\napp.listen(PORT, () => {\n    console.log(`Server running on http://localhost:${PORT}`);\n});","lang":"typescript","description":"This quickstart initializes an Express app, configures an IP filter in 'whitelist' mode using `node:net.BlockList`, and applies it globally to demonstrate basic access control."},"warnings":[{"fix":"Always explicitly define the `mode` option when configuring the `ipFilterMiddleware`.","message":"The `mode` option ('whitelist' or 'blacklist') is required. Prior versions might have had implicit defaults, but v2.x explicitly enforces this, and omitting it will cause the middleware to throw an error during initialization.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure that your `allow` list contains the necessary IP addresses or CIDR blocks when operating in 'whitelist' mode, or configure `deny` with explicit blocks if you intend to allow everything else.","message":"In 'whitelist' mode, if both `allow` and `deny` lists are empty, all access will be denied. This behavior is intentional, similar to Apache's `Order Allow,Deny` directive, where an empty `Allow` list defaults to no access.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Implement robust validation within your `ipOverride` function to ensure it always returns a valid IPv4/IPv6 string or `undefined`. Consider using a `try-catch` block around the middleware in your Express application or a global error handler to gracefully manage such errors.","message":"If the optional `ipOverride` function is provided and returns an invalid IP address string, the middleware will bail out with an error. This can lead to unexpected server crashes if not handled.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Review your existing `express-ip-filter-middleware` configurations against the v2 documentation and thoroughly test all IP-filtering scenarios, particularly edge cases involving empty lists, invalid IPs, or proxy setups, when upgrading.","message":"While v2.0.0 represents a major version bump, explicit breaking changes from v1.x are not extensively documented in the public changelog. Users migrating from older versions should thoroughly test their applications, as subtle behavioral changes or stricter validations might exist.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"For ESM, use `import { ipFilterMiddleware } from 'express-ip-filter-middleware';`. For CJS, use `const { ipFilterMiddleware } = require('express-ip-filter-middleware');`.","cause":"Attempting to import `ipFilterMiddleware` as a default export or using CommonJS `require` without property access when it is a named export.","error":"TypeError: ipFilterMiddleware is not a function"},{"fix":"Add a `mode` property to your options object, e.g., `{ mode: 'whitelist', allow, deny }`.","cause":"The `mode` property ('whitelist' or 'blacklist') was not provided in the options object passed to `ipFilterMiddleware`.","error":"Error: 'mode' is a required option"},{"fix":"Ensure that the `allow` `BlockList` instance is populated with all desired IP addresses or networks when using `mode: 'whitelist'`.","cause":"Operating in 'whitelist' mode without any IPs or CIDR blocks added to the `allow` list, which by default denies all access.","error":"Access denied unexpectedly in whitelist mode"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}