@aminbozorgani/api-shield

API Shield 2.0.0 is a modular, plug-in ready, TypeScript-first security framework for Node.js and modern edge runtimes. It combines rate limiting, IP firewalling, authentication guards, bot detection, anomaly detection, logging, and event-driven automation under one cohesive middleware experience.

Features

• Sliding-window rate limiting with burst detection, auto-block scores, and Redis/file/memory stores.
• Stateful IP firewall with allow/block lists, CIDR support, and dynamic runtime rule injection.
• Authentication guards for JWT, API keys, HMAC signatures, and replay protection.
• User-Agent + bot heuristics with regex fingerprinting and curated bot datasets.
• Anomaly engine tracking endpoint scans, header anomalies, payload abuse, and failed authentications.
• Built-in JSON logger with pluggable transports and a rich event bus (shieldEvents).
• Dependency-injected architecture with schema-validated config and middleware builder.

Installation

npm install @aminbozorgani/api-shield ajv ajv-formats
# optional, for redis strategy
npm install redis

Quick Start

import express from 'express';
import { createApiShield } from '@aminbozorgani/api-shield';

const shield = createApiShield();

const app = express();
app.use(shield.middleware);

Configuration

const shield = createApiShield({
  rateLimit: {
    max: 200,
    store: 'redis',
  },
  auth: {
    jwt: { enabled: true, secret: process.env.JWT_SECRET },
    replay: { header: 'x-nonce', windowMs: 120000 },
  },
});

Config Schema Highlights

{
  "rateLimit": {
    "enabled": true,
    "windowMs": 60000,
    "max": 100,
    "store": "memory|redis|file"
  },
  "firewall": {
    "allowlist": [],
    "blocklist": [],
    "cidr": []
  },
  "auth": {
    "jwt": {
      "enabled": false,
      "secret": "",
      "algorithm": "HS256"
    },
    "apiKey": {
      "header": "x-api-key",
      "keys": []
    },
    "hmac": {
      "header": "x-signature",
      "secret": ""
    },
    "replay": {
      "header": "x-nonce",
      "windowMs": 300000
    }
  }
}

Middleware Usage

Express

app.use(shield.middleware);

Next.js (App Router)

export const middleware = shield.middleware;

Hono

const hono = new Hono();
hono.use('*', (c, next) => shield.middleware(c.req.raw, c.res.raw, next));

Events

shield.events.on('rateLimitExceeded', (payload) => {
  console.log('moderate abuse', payload);
});

Events: rateLimitExceeded, suspiciousBot, signatureMismatch, replayDetected, blockedRequest.

Plugins

shield.use({
  register({ events }) {
    events.on('blockedRequest', ({ reason, ip }) => {
      // custom alerting
    });
  }
});

Architecture

• Core: DI container, config loader, middleware builder, plugin loader, event bus.
• Modules: rateLimit, firewall, auth, user-agent bot detection, anomaly detection, logging.
• Adapters: memory, file, Redis stores.
• Middlewares: context builder + pipeline orchestrator.
• Schemas & Types: Ajv validators, .d.ts exports, runtime defaults.
• Utilities: crypto helpers, IP parsing, sliding window counters.

Plugin Development Guide

1. Implement register({ container, events }).
2. Resolve dependencies from the container (logger, stores, config).
3. Add middleware via builder.use or attach to events.

Advanced Example

const shield = createApiShield({
  rateLimit: { store: 'redis', windowMs: 30000, max: 50 },
  firewall: { blocklist: ['10.10.10.10'] },
  bot: { regex: ['HeadlessChrome'] },
});

shield.events.on('replayDetected', ({ nonce }) => {
  console.error('Blocked replay', nonce);
});

License

MIT © Amin Bozorgani