{"_id":"@aminbozorgani/api-shield","name":"@aminbozorgani/api-shield","dist-tags":{"latest":"2.0.0"},"versions":{"2.0.0":{"name":"@aminbozorgani/api-shield","version":"2.0.0","type":"module","description":"Next-generation API security middleware suite for high-security Node.js platforms.","main":"src/index.js","types":"src/index.d.ts","exports":{".":{"import":"./src/index.js","types":"./src/index.d.ts"},"./shield":{"import":"./src/shield.d.ts","types":"./src/shield.d.ts"}},"engines":{"node":">=18"},"scripts":{"lint":"eslint .","test":"node --test"},"keywords":["security","api","middleware","rate-limit","firewall","hmac","jwt"],"author":{"name":"Amin Bozorgani"},"license":"MIT","dependencies":{"ajv":"^8.17.1","ajv-formats":"^3.0.1"},"peerDependencies":{"redis":"^4.6.12"},"_id":"@aminbozorgani/api-shield@2.0.0","_nodeVersion":"22.19.0","_npmVersion":"11.6.0","dist":{"integrity":"sha512-g+YVSfeaUIMV2FwFh7Xic41HyKNj7HuQzbql4+QdFX3+DIUcgZJQZKYTHVDO/AbASNiWDR5B7PVudI8JLhdBHg==","shasum":"51b22c3d0f3cf43daf88b8b92bbaaf3151ef9f5d","tarball":"https://registry.npmjs.org/@aminbozorgani/api-shield/-/api-shield-2.0.0.tgz","fileCount":32,"unpackedSize":41021,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD8x9la9hqCCtV8CYFBoeCzBrC0pUX0huk4/yVCEsFaWwIhAI0T0GEWUX5UbxAqJ3NJjfhjJKagWbkowfdOOcbidMur"}]},"_npmUser":{"name":"aminbozorgani","email":"bozorgane.0312@gmail.com"},"directories":{},"maintainers":[{"name":"aminbozorgani","email":"bozorgane.0312@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/api-shield_2.0.0_1763247390346_0.9463278086131932"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-15T22:56:30.243Z","2.0.0":"2025-11-15T22:56:30.528Z","modified":"2025-11-15T22:56:30.877Z"},"maintainers":[{"name":"aminbozorgani","email":"bozorgane.0312@gmail.com"}],"description":"Next-generation API security middleware suite for high-security Node.js platforms.","keywords":["security","api","middleware","rate-limit","firewall","hmac","jwt"],"author":{"name":"Amin Bozorgani"},"license":"MIT","readme":"# @aminbozorgani/api-shield\r\n\r\nAPI 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.\r\n\r\n## Features\r\n- Sliding-window rate limiting with burst detection, auto-block scores, and Redis/file/memory stores.\r\n- Stateful IP firewall with allow/block lists, CIDR support, and dynamic runtime rule injection.\r\n- Authentication guards for JWT, API keys, HMAC signatures, and replay protection.\r\n- User-Agent + bot heuristics with regex fingerprinting and curated bot datasets.\r\n- Anomaly engine tracking endpoint scans, header anomalies, payload abuse, and failed authentications.\r\n- Built-in JSON logger with pluggable transports and a rich event bus (`shieldEvents`).\r\n- Dependency-injected architecture with schema-validated config and middleware builder.\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @aminbozorgani/api-shield ajv ajv-formats\r\n# optional, for redis strategy\r\nnpm install redis\r\n```\r\n\r\n## Quick Start\r\n\r\n```js\r\nimport express from 'express';\r\nimport { createApiShield } from '@aminbozorgani/api-shield';\r\n\r\nconst shield = createApiShield();\r\n\r\nconst app = express();\r\napp.use(shield.middleware);\r\n```\r\n\r\n## Configuration\r\n\r\n```js\r\nconst shield = createApiShield({\r\n  rateLimit: {\r\n    max: 200,\r\n    store: 'redis',\r\n  },\r\n  auth: {\r\n    jwt: { enabled: true, secret: process.env.JWT_SECRET },\r\n    replay: { header: 'x-nonce', windowMs: 120000 },\r\n  },\r\n});\r\n```\r\n\r\n### Config Schema Highlights\r\n\r\n```json\r\n{\r\n  \"rateLimit\": {\r\n    \"enabled\": true,\r\n    \"windowMs\": 60000,\r\n    \"max\": 100,\r\n    \"store\": \"memory|redis|file\"\r\n  },\r\n  \"firewall\": {\r\n    \"allowlist\": [],\r\n    \"blocklist\": [],\r\n    \"cidr\": []\r\n  },\r\n  \"auth\": {\r\n    \"jwt\": {\r\n      \"enabled\": false,\r\n      \"secret\": \"\",\r\n      \"algorithm\": \"HS256\"\r\n    },\r\n    \"apiKey\": {\r\n      \"header\": \"x-api-key\",\r\n      \"keys\": []\r\n    },\r\n    \"hmac\": {\r\n      \"header\": \"x-signature\",\r\n      \"secret\": \"\"\r\n    },\r\n    \"replay\": {\r\n      \"header\": \"x-nonce\",\r\n      \"windowMs\": 300000\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## Middleware Usage\r\n\r\n### Express\r\n```js\r\napp.use(shield.middleware);\r\n```\r\n\r\n### Next.js (App Router)\r\n```js\r\nexport const middleware = shield.middleware;\r\n```\r\n\r\n### Hono\r\n```js\r\nconst hono = new Hono();\r\nhono.use('*', (c, next) => shield.middleware(c.req.raw, c.res.raw, next));\r\n```\r\n\r\n## Events\r\n\r\n```js\r\nshield.events.on('rateLimitExceeded', (payload) => {\r\n  console.log('moderate abuse', payload);\r\n});\r\n```\r\n\r\nEvents: `rateLimitExceeded`, `suspiciousBot`, `signatureMismatch`, `replayDetected`, `blockedRequest`.\r\n\r\n## Plugins\r\n\r\n```js\r\nshield.use({\r\n  register({ events }) {\r\n    events.on('blockedRequest', ({ reason, ip }) => {\r\n      // custom alerting\r\n    });\r\n  }\r\n});\r\n```\r\n\r\n## Architecture\r\n- **Core**: DI container, config loader, middleware builder, plugin loader, event bus.\r\n- **Modules**: rateLimit, firewall, auth, user-agent bot detection, anomaly detection, logging.\r\n- **Adapters**: memory, file, Redis stores.\r\n- **Middlewares**: context builder + pipeline orchestrator.\r\n- **Schemas & Types**: Ajv validators, `.d.ts` exports, runtime defaults.\r\n- **Utilities**: crypto helpers, IP parsing, sliding window counters.\r\n\r\n## Plugin Development Guide\r\n1. Implement `register({ container, events })`.\r\n2. Resolve dependencies from the container (logger, stores, config).\r\n3. Add middleware via `builder.use` or attach to events.\r\n\r\n## Advanced Example\r\n\r\n```js\r\nconst shield = createApiShield({\r\n  rateLimit: { store: 'redis', windowMs: 30000, max: 50 },\r\n  firewall: { blocklist: ['10.10.10.10'] },\r\n  bot: { regex: ['HeadlessChrome'] },\r\n});\r\n\r\nshield.events.on('replayDetected', ({ nonce }) => {\r\n  console.error('Blocked replay', nonce);\r\n});\r\n```\r\n\r\n## License\r\n\r\nMIT © Amin Bozorgani\r\n\r\n","readmeFilename":"README.md","_rev":"1-62120a74bc5e9a6488dcd94cb10cdf7f"}