🛡️ @neabyte/express-shield

Lightweight Express middleware for rate limiting, unique client fingerprinting, Cloudflare-aware IP trust, and essential security headers 🛡️
Now with auto-updated Cloudflare IP lists, hot-reload without restart, and zero dependency design for production-grade security and flexibility.

✨ Features

• 🔁 Auto-updated Cloudflare IPs: Automatically keeps the IP whitelist in sync with Cloudflare’s official ranges (IPv4/IPv6) and hot-reloads without restart.
• 🚦 Rate Limiting: Configurable time window and maximum requests per IP address (with Cloudflare trusted IP logic).
• 🔒 Fingerprinting: Generates a unique, consistent client fingerprint for better request tracking.
• 🛡️ Security Headers: Automatically applies crucial HTTP security headers (X-Content-Type-Options, Strict-Transport-Security, X-Frame-Options, Referrer-Policy, and more).
• 🎨 Custom Error Responses: Override default 429 (Too Many Requests) handler with custom logic/format.
• 📦 Modular Design: Redis is optional; rate limiting is skipped if no Redis is supplied.
• ⚙️ TypeScript Support: Built-in .d.ts types, fully typed exports.
• 🔄 Zero External Dependency: No deps except Express and (optionally) ioredis for rate-limit.

🚀 Installation

npm install @neabyte/express-shield

Requires Node.js >=18.20.8

• After install, Cloudflare IPs are fetched to data/ folder.
• To update manually: node ./script/update-cloudflare-ip.js

🛠️ Quick Start

With Redis (Enables Rate Limiting)

const express = require('express')
const Redis = require('ioredis')
const { createExpressShield } = require('@neabyte/express-shield')

const app = express()
const redisClient = new Redis()

app.use(
  createExpressShield(
    redisClient,
    {
      app,
      windowSec: 60,
      maxRequests: 10,
      showHeader: true,
      showLog: false,
      applySecurity: true,
      customErrorResponse: (req, res, ttl) => {
        res.status(429).json({
          error: 'Too many requests',
          ip: req.fingerprint.ip,
          retryAfterSec: ttl
        })
      }
    }
  )
)

app.get('/', (req, res) => {
  res.send('Hello, world! 🎉 This route is protected with rate limiting and security headers.')
})

app.listen(3000, () => console.log('Server running on port 3000 🚀'))

Without Redis (Skips Rate Limiting)

const express = require('express')
const { createExpressShield } = require('@neabyte/express-shield')

const app = express()

app.use(
  createExpressShield(
    null,
    {
      app,
      applySecurity: true
    }
  )
)

app.get('/', (req, res) => {
  res.send('Hello, world! 🎉 This route is protected with security headers.')
})

app.listen(3000, () => console.log('Server running on port 3000 🚀'))

⚡ Cloudflare IP Support

• The IP whitelist used for trusting cf-connecting-ip is auto-updated using Cloudflare’s published range.

• After install, files data/cloudflare_ipv4.json and data/cloudflare_ipv6.json are created/updated.

• IPs are hot-reloaded at runtime (no restart needed).

• To force reload in app code:

  const { reloadCloudflareIpList } = require('@neabyte/express-shield')
  reloadCloudflareIpList()

🧩 Parameters & Defaults

| Parameter | Type | Default | Description | | ----------------------------- | --------- | -------------------- | -------------------------------------------------------------- | | redisClient | object? | null | Optional ioredis instance. If falsy, disables rate limiting. | | options.app | Express | null | Express app instance for header patching. | | options.windowSec | number | 60 | Duration of the rate limit window (seconds). | | options.maxRequests | number | 10 | Max allowed requests per IP within the window. | | options.showHeader | boolean | true | Show X-Fingerprint-Id header. | | options.showLog | boolean | false | Enable debug console logging. | | options.applySecurity | boolean | true | Apply HTTP security headers. | | options.customErrorResponse | function | default 429 JSON | Custom 429 handler. (req, res, ttl) => void | | options.whitelist | string[] | [] | Skip rate-limit for these IPs. | | options.ipResolver | function | getClientIpAddress | Custom IP resolver (rarely needed). |

📖 API Reference

• createExpressShield(redisClient, options)
  Creates the Express middleware. Handles security headers, fingerprinting, rate limit (if Redis provided).

• getClientIpAddress(req)
  Returns the trusted client IP. Automatically checks cf-connecting-ip if request comes from Cloudflare IP range.

• generateFingerprintHash(req)
  Returns a SHA256 hash of client IP + headers (used for fingerprinting).

• reloadCloudflareIpList()
  Forces reload of Cloudflare IPv4 + IPv6 lists from data/ folder. Useful for manual reload or custom schedulers.

• watchCloudflareIpList()
  Starts file watcher. Automatically reloads Cloudflare IPs when data/cloudflare_ipv4.json or data/cloudflare_ipv6.json change.

• CLOUDFLARE_IPV4 / CLOUDFLARE_IPV6
  Exposes current trusted Cloudflare IP lists (arrays of CIDR).

• checkIpInCidrList(ip, cidrList)
  Utility to check if an IP (IPv4/IPv6) is within any CIDR in the list.

• checkIpv4InCidr(ip, cidr) / checkIpv6InCidr(ip, cidr)
  Low-level CIDR match utilities for IPv4 / IPv6.

• convertIpv4ToNumber(ip) / convertIpv6ToBigint(ip)
  Internal helpers to convert IP addresses for CIDR math (exposed for testability).

Note: All utility functions are exposed primarily for testing and advanced use cases.
Typical users only need createExpressShield and optionally reloadCloudflareIpList.

✅ Running Tests Locally

npm install
npm test

❤️ Contributing

1. Fork the repo 🔱
2. Create your feature branch (git checkout -b feature/your-feature-name)
3. Commit your changes (git commit -am 'Add some your-feature-name')
4. Push to the branch (git push origin feature/your-feature-name)
5. Open a Pull Request 📬

📬 Questions / Support

For questions, issues or feature requests, please open an issue or start a discussion.

🗒️ Changelog

See CHANGELOG.md for all updates.

📜 License

MIT License © 2025 NeaByteLab