⚠️ Status: untested. This extension is provided as-is and has not been tested in production. Please feel free to fork, modify, improve, and open pull requests.

Licensed under GNU GPLv3 (see LICENSE).

IP Block — Express Middleware

An Express middleware that checks each request against the ip-block.com service and blocks disallowed clients.

Targets: Express 4.x / 5.x, Node.js 18+ (uses the built-in global fetch; on Node 14–16 provide a fetch polyfill).

Install

npm install ip-block-express

Register

const express = require('express');
const ipBlock = require('ip-block-express');

const app = express();

// If you are behind a proxy/load balancer, let Express compute req.ip:
app.set('trust proxy', true);

app.use(
  ipBlock({
    siteId: process.env.IP_BLOCK_SITE_ID,
    apiKey: process.env.IP_BLOCK_API_KEY,
    behindProxy: true,
    whitelist: ['127.0.0.1', '10.0.0.0/8'],
  })
);

app.get('/', (req, res) => res.send('Hello'));
app.listen(3000);

ESM / TypeScript:

import ipBlock from 'ip-block-express';
app.use(ipBlock({ siteId: '...', apiKey: '...' }));

Options (defaults)

{
  enabled: true,
  siteId: '',
  apiKey: '',
  apiUrl: 'https://api.ip-block.com/v1/check',
  failOpen: true,          // allow on error/timeout
  cacheTtl: 300,           // seconds (in-memory cache)
  timeout: 1000,           // ms (1 second)
  behindProxy: false,      // trust X-Forwarded-For / CF-Connecting-IP
  blockAction: '403',      // '403' or 'redirect'
  redirectUrl: 'https://www.ip-block.com/blocked.php',
  blockMessage: 'Access denied.',
  whitelist: [],           // IPs and CIDR ranges
}

How it works

• Builds {api_key, site_id, ip, user_agent, referrer} and POSTs it with a 1 second (timeout) abort.
• Blocks only when the response is {"action":"block"}.
• Fails open on any error/timeout/non-2xx/missing action (failOpen: false to fail closed).
• Caches each decision for cacheTtl seconds in an in-memory Map, keyed by md5(ip|user_agent|referrer).
• Honours whitelist (individual IPs and IPv4 CIDR ranges).
• Reads the real client IP from req.ip; with behindProxy: true it trusts CF-Connecting-IP then the first X-Forwarded-For hop.