auto-smart-security 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 HaiVinh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# auto-smart-security
+
+🔐 Production-ready security middleware for **Express / NestJS**  
+Protect your API from bots, abuse, and attacks with rate limiting, auto blacklist, and Redis support.
+
+---
+
+## ✨ Features
+
+- ✅ Path whitelist (block API scanning)
+- ✅ Rate limiting (express-rate-limit)
+- ✅ Automatic IP blacklist with TTL
+- ✅ Bot detection (score-based)
+- ✅ Memory or Redis blacklist store
+- ✅ Multi-instance / Docker / Kubernetes safe
+- ✅ Framework-agnostic (Express & NestJS)
+- ✅ `onBlock` hook for logging & notifications (Slack / Telegram / Sentry…)
+
+---
+
+## 📦 Installation
+
+```bash
+npm install smart-security
+```
+
+⚠️ Peer dependency
+Your application must have express installed
+
+```bash
+npm install express
+```
+
+## 🚀 Quick Start (Express / NestJS)
+
+```ts
+import { applySecurity } from 'smart-security';
+import { SEND_NOTIFICATION_ERR } from './notify';
+
+applySecurity(app, {
+  mode: 'prod',
+  pathWhitelist: ['admin/', 'media', 'oauth2'],
+  rateLimit: { max: 120, windowMs: 60_000 },
+  bot: { enabled: true },
+  blacklistTTL: 10 * 60 * 1000,
+
+  onBlock: (info) => {
+    SEND_NOTIFICATION_ERR(
+      `[SECURITY]
+Reason: ${info.reason}
+IP: ${info.ip}
+URL: ${info.url}
+UA: ${info.ua ?? 'N/A'}`
+    );
+  },
+});
+```
+
+## ⚙️ SecurityOptions
+
+```ts
+interface SecurityOptions {
+  /** Skip all security when in dev mode */
+  mode?: 'prod' | 'dev';
+
+  /** Allowed API paths */
+  pathWhitelist: string[];
+
+  /** Hard-coded blacklist */
+  staticBlacklist?: string[];
+
+  /** Dynamic blacklist TTL (milliseconds) */
+  blacklistTTL?: number;
+
+  /** Custom blacklist store (Redis / Memory) */
+  blacklist?: {
+    store?: BlacklistStore;
+  };
+
+  /** Rate limiting */
+  rateLimit?: {
+    windowMs: number;
+    max: number;
+  };
+
+  /** Bot detection */
+  bot?: {
+    enabled: boolean;
+    scoreLimit?: number;
+  };
+
+  /** Callback when a request is blocked */
+  onBlock?: (info: BlockInfo) => void;
+}
+```
+
+## 🚫 Block Reasons
+
+The onBlock callback receives one of the following reasons:
+
+| reason             | Description              |
+| ------------------ | ------------------------ |
+| `rate-limit`       | Too many requests        |
+| `bot-detected`     | Bot behavior detected    |
+| `path-not-allowed` | Path not in whitelist    |
+| `error-spam`       | Repeated error responses |
+| `blacklist`        | IP is blacklisted        |
+
+## 🤖 Bot Detection
+
+Bots are detected using a score-based system, including:
+
+- Suspicious User-Agent (curl, python, scrapy)
+- Missing browser headers
+- No cookies
+- Scanning sensitive paths (.env, wp-admin)
+- Unusual HTTP methods
+
+➡ When the score exceeds the threshold → block + blacklist
+
+## 🧱 Blacklist Store
+
+🧠 Memory (default)
+
+- No configuration required
+- Suitable for single-instance deployments
+
+## ☁️ Redis (recommended for production)
+
+Using ioredis
+
+```ts
+import Redis from 'ioredis';
+import { RedisBlacklistStore } from 'smart-security/dist/blacklist/redis.store';
+
+const redis = new Redis(process.env.REDIS_URL);
+
+applySecurity(app, {
+  pathWhitelist: ['admin/', 'media'],
+  blacklist: {
+    store: new RedisBlacklistStore(
+      redis,
+      ['1.2.3.4'], // static blacklist
+      600          // TTL in seconds
+    ),
+  },
+});
+```
+
+## Development Mode
+
+Disable all security logic (local development):
+
+```ts
+applySecurity(app, {
+  mode: 'dev',
+  pathWhitelist: [],
+});
+```
+
+## 🧠 Best Practices
+
+- ✔ Whitelist only valid API paths
+- ✔ Avoid permanent blacklisting
+- ✔ Use Redis for multi-instance environments
+- ✔ Handle logging & notifications via onBlock
+
+## 🧩 Works With
+
+- Express
+- NestJS (Express adapter)
+- Docker / Kubernetes
+- Cloudflare / Nginx / reverse proxies
+
+## 🧩 Works With

package/dist/apply-security.d.ts

@@ -0,0 +1,2 @@
+import { SecurityOptions } from './types';
+export declare function applySecurity(app: any, options: SecurityOptions): void;

package/dist/apply-security.js

@@ -0,0 +1,71 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applySecurity = applySecurity;
+const helmet_1 = __importDefault(require("helmet"));
+const utils_1 = require("./utils");
+const bot_detector_1 = require("./bot-detector");
+const rate_limiter_1 = require("./rate-limiter");
+const memory_store_1 = require("./blacklist/memory.store");
+function applySecurity(app, options) {
+    // Dev mode → skip security
+    if (options.mode === 'dev')
+        return;
+    app.set('trust proxy', true);
+    /** ================= BLACKLIST STORE ================= */
+    const blacklist = options.blacklist?.store ??
+        new memory_store_1.MemoryBlacklistStore(options.staticBlacklist, options.blacklistTTL);
+    /** ================= BOT DETECTOR ================= */
+    const botDetector = options.bot?.enabled === true
+        ? new bot_detector_1.BotDetector(options.bot.scoreLimit)
+        : null;
+    /** ================= RATE LIMIT ================= */
+    if (options.rateLimit) {
+        app.use((0, rate_limiter_1.createRateLimiter)(options.rateLimit, (req) => {
+            const ip = (0, utils_1.getClientIP)(req);
+            blacklist.block(ip);
+            options.onBlock?.({
+                ip,
+                reason: 'rate-limit',
+                url: req.originalUrl,
+                ua: req.headers?.['user-agent'],
+            });
+        }));
+    }
+    /** ================= MAIN SECURITY ================= */
+    app.use(async (req, res, next) => {
+        const ip = (0, utils_1.getClientIP)(req);
+        const url = req.originalUrl;
+        /** 1️⃣ Blacklist */
+        if (await blacklist.isBlocked(ip)) {
+            return res.status(403).send('Access denied');
+        }
+        /** 2️⃣ Bot detection */
+        if (botDetector?.detect(req)) {
+            await blacklist.block(ip);
+            options.onBlock?.({
+                ip,
+                reason: 'bot-detected',
+                url,
+                ua: req.headers?.['user-agent'],
+            });
+            return res.status(403).send('Bot detected');
+        }
+        /** 3️⃣ Path whitelist */
+        if (options.pathWhitelist?.length &&
+            !options.pathWhitelist.some((p) => url.includes(p))) {
+            await blacklist.block(ip);
+            options.onBlock?.({
+                ip,
+                reason: 'path-not-allowed',
+                url,
+            });
+            return res.status(403).send('Blocked path');
+        }
+        next();
+    });
+    /** ================= HELMET ================= */
+    app.use((0, helmet_1.default)());
+}

package/dist/blacklist/blacklist.interface.d.ts

@@ -0,0 +1,4 @@
+export interface BlacklistStore {
+    isBlocked(ip: string): Promise<boolean> | boolean;
+    block(ip: string, ttl?: number): Promise<void> | void;
+}

package/dist/blacklist/blacklist.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/blacklist/memory.store.d.ts

@@ -0,0 +1,9 @@
+import { BlacklistStore } from './blacklist.interface';
+export declare class MemoryBlacklistStore implements BlacklistStore {
+    private ttl;
+    private dynamic;
+    private staticList;
+    constructor(staticBlacklist?: string[], ttl?: number);
+    isBlocked(ip: string): boolean;
+    block(ip: string, ttl?: number): void;
+}

package/dist/blacklist/memory.store.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryBlacklistStore = void 0;
+class MemoryBlacklistStore {
+    constructor(staticBlacklist = [], ttl = 10 * 60 * 1000) {
+        this.ttl = ttl;
+        this.dynamic = new Map();
+        this.staticList = new Set(staticBlacklist);
+    }
+    isBlocked(ip) {
+        if (this.staticList.has(ip))
+            return true;
+        const exp = this.dynamic.get(ip);
+        if (!exp)
+            return false;
+        if (Date.now() > exp) {
+            this.dynamic.delete(ip);
+            return false;
+        }
+        return true;
+    }
+    block(ip, ttl) {
+        this.dynamic.set(ip, Date.now() + (ttl ?? this.ttl));
+    }
+}
+exports.MemoryBlacklistStore = MemoryBlacklistStore;

package/dist/blacklist/redis.store.d.ts

@@ -0,0 +1,17 @@
+import { BlacklistStore } from './blacklist.interface';
+interface RedisLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ...args: any[]): Promise<any>;
+    del(key: string): Promise<any>;
+}
+export declare class RedisBlacklistStore implements BlacklistStore {
+    private redis;
+    private staticBlacklist;
+    private ttlSeconds;
+    private prefix;
+    constructor(redis: RedisLike, staticBlacklist?: string[], ttlSeconds?: number);
+    private key;
+    isBlocked(ip: string): Promise<boolean>;
+    block(ip: string, ttlSeconds?: number): Promise<void>;
+}
+export {};

package/dist/blacklist/redis.store.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisBlacklistStore = void 0;
+class RedisBlacklistStore {
+    constructor(redis, staticBlacklist = [], ttlSeconds = 600) {
+        this.redis = redis;
+        this.staticBlacklist = staticBlacklist;
+        this.ttlSeconds = ttlSeconds;
+        this.prefix = 'security:blacklist:';
+    }
+    key(ip) {
+        return `${this.prefix}${ip}`;
+    }
+    async isBlocked(ip) {
+        if (this.staticBlacklist.includes(ip))
+            return true;
+        const value = await this.redis.get(this.key(ip));
+        return value === '1';
+    }
+    async block(ip, ttlSeconds) {
+        const ttl = ttlSeconds ?? this.ttlSeconds;
+        await this.redis.set(this.key(ip), '1', 'EX', ttl);
+    }
+}
+exports.RedisBlacklistStore = RedisBlacklistStore;

package/dist/bot-detector.d.ts

@@ -0,0 +1,6 @@
+export declare class BotDetector {
+    private limit;
+    private scores;
+    constructor(limit?: number);
+    detect(req: any): boolean;
+}

package/dist/bot-detector.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BotDetector = void 0;
+const utils_1 = require("./utils");
+class BotDetector {
+    constructor(limit = 8) {
+        this.limit = limit;
+        this.scores = new Map();
+    }
+    detect(req) {
+        let score = 0;
+        const ua = (req.headers?.['user-agent'] || '').toLowerCase();
+        if (!ua || ua.length < 20)
+            score += 2;
+        if (/(curl|wget|python|java|scrapy|axios|httpclient|go-http)/.test(ua))
+            score += 5;
+        if (!req.headers?.accept)
+            score += 1;
+        if (!req.headers?.['accept-language'])
+            score += 1;
+        if (!req.headers?.['sec-fetch-site'])
+            score += 2;
+        if (!req.headers?.cookie)
+            score += 1;
+        if (/(wp-admin|\.env|phpmyadmin|cgi-bin)/i.test(req.originalUrl))
+            score += 5;
+        const ip = (0, utils_1.getClientIP)(req);
+        const total = (this.scores.get(ip) || 0) + score;
+        this.scores.set(ip, total);
+        return total >= this.limit;
+    }
+}
+exports.BotDetector = BotDetector;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './apply-security';
+export * from './types';
+export * from './utils';

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./apply-security"), exports);
+__exportStar(require("./types"), exports);
+__exportStar(require("./utils"), exports);

package/dist/rate-limiter.d.ts

@@ -0,0 +1,4 @@
+export declare function createRateLimiter(options: {
+    windowMs: number;
+    max: number;
+}, onLimit: (req: any, res: any) => void): import("express-rate-limit").RateLimitRequestHandler;

package/dist/rate-limiter.js

@@ -0,0 +1,19 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRateLimiter = createRateLimiter;
+const express_rate_limit_1 = __importDefault(require("express-rate-limit"));
+function createRateLimiter(options, onLimit) {
+    return (0, express_rate_limit_1.default)({
+        windowMs: options.windowMs,
+        max: options.max,
+        standardHeaders: true,
+        legacyHeaders: false,
+        handler: (req, res) => {
+            onLimit(req, res);
+            res.status(429).send('Too many requests');
+        },
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,37 @@
+import { BlacklistStore } from './blacklist/blacklist.interface';
+export type BlockReason = 'rate-limit' | 'bot-detected' | 'path-not-allowed' | 'error-spam' | 'blacklist';
+export interface BlockInfo {
+    ip: string;
+    reason: BlockReason;
+    url: string;
+    ua?: string;
+    extra?: any;
+}
+export interface RateLimitOptions {
+    windowMs: number;
+    max: number;
+}
+export interface BotOptions {
+    enabled: boolean;
+    scoreLimit?: number;
+}
+export interface SecurityOptions {
+    /** dev → skip security */
+    mode?: 'prod' | 'dev';
+    /** allow only these paths */
+    pathWhitelist: string[];
+    /** hard blacklist */
+    staticBlacklist?: string[];
+    /** dynamic blacklist ttl (ms) */
+    blacklistTTL?: number;
+    /** custom blacklist store (Redis / Memory) */
+    blacklist?: {
+        store?: BlacklistStore;
+    };
+    /** rate limit */
+    rateLimit?: RateLimitOptions;
+    /** bot detection */
+    bot?: BotOptions;
+    /** notify app when blocked */
+    onBlock?: (info: BlockInfo) => void;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils.d.ts

@@ -0,0 +1 @@
+export declare function getClientIP(req: any): string;

package/dist/utils.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getClientIP = getClientIP;
+function getClientIP(req) {
+    return (req.headers?.['x-real-ip'] ||
+        req.headers?.['x-forwarded-for']?.split(',')[0] ||
+        req.socket?.remoteAddress ||
+        req.ip ||
+        'unknown');
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "auto-smart-security",
+  "version": "1.0.0",
+  "description": "Production-ready security middleware for Express / NestJS",
+  "author": "Hai Vinh <haivinhinspirit@gmail.com>",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "readmeFilename": "README.md",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start:dev": "tsc -w"
+  },
+  "keywords": [
+    "security",
+    "express",
+    "nestjs",
+    "rate-limit",
+    "bot-detection",
+    "blacklist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "express": ">=4",
+    "node": ">=18"
+  },
+  "dependencies": {
+    "express-rate-limit": "^7.0.0",
+    "helmet": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.0.3",
+    "typescript": "^5.3.0"
+  }
+}