nestjs-shield 1.0.0 → 1.1.0

package/README.md

@@ -37,7 +37,7 @@ Or from GitHub Packages (published as `@yassinos-coder/nestjs-shield`) — first
 GITHUB_TOKEN=ghp_xxx npm install @yassinos-coder/nestjs-shield
 ```
 
-Node ≥ 18, NestJS 9 / 10 / 11.
+Node ≥ 18, NestJS 9 / 10 / 11 / 12. NestJS 12 applications require Node ≥ 20.
 
 ## Quick start
 
@@ -129,6 +129,7 @@ interface ShieldConfig {
     window: number;                        // ms — count window
     banDuration: number;                   // ms — initial ban
     escalate?: boolean;                    // 2× each repeat ban, default true
+    maxBanDuration?: number;               // ms — cap on escalated ban duration
   };
 
   slowDown?: {

package/dist/apply-to.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Shield = void 0;
+const common_1 = require("@nestjs/common");
 const shield_engine_1 = require("./shield.engine");
 const shield_middleware_1 = require("./shield.middleware");
 const shield_constants_1 = require("./shield.constants");
 const memory_storage_1 = require("./storage/memory.storage");
 const redis_storage_1 = require("./storage/redis.storage");
+const banner_util_1 = require("./utils/banner.util");
 function buildStorage(option) {
     if (!option || option === 'memory')
         return new memory_storage_1.MemoryStorage();
@@ -24,9 +26,11 @@ function buildStorage(option) {
 class Shield {
     static applyTo(app, config = {}) {
         let engine = null;
+        let resolvedConfig = config;
         if (typeof app.get === 'function') {
             try {
                 engine = app.get(shield_constants_1.SHIELD_ENGINE);
+                resolvedConfig = engine.getConfig();
             }
             catch {
                 engine = null;
@@ -37,6 +41,11 @@ class Shield {
             engine = new shield_engine_1.ShieldEngine(config, storage);
         }
         app.use((0, shield_middleware_1.createShieldMiddleware)(engine));
+        if (resolvedConfig.enabled !== false && engine.markBannerShown()) {
+            const { banner, summary } = banner_util_1.BannerUtil.build(resolvedConfig);
+            process.stdout.write(banner + '\n');
+            new common_1.Logger('Shield').log(summary);
+        }
     }
 }
 exports.Shield = Shield;

package/dist/checks/auto-ban.check.js

@@ -33,8 +33,10 @@ class AutoBanCheck {
             return;
         const banCountKey = `${shield_constants_1.KEY_BAN_COUNT}:${ip}`;
         const banCountResult = await storage.increment(banCountKey, config.banDuration * 16);
-        const escalation = config.escalate === false ? 1 : Math.pow(2, banCountResult.count - 1);
-        const duration = config.banDuration * escalation;
+        const exponent = Math.min(Math.max(0, banCountResult.count - 1), 30);
+        const escalation = config.escalate === false ? 1 : Math.pow(2, exponent);
+        const computed = config.banDuration * escalation;
+        const duration = config.maxBanDuration !== undefined ? Math.min(computed, config.maxBanDuration) : computed;
         const expiresAt = Date.now() + duration;
         await storage.set(`${shield_constants_1.KEY_BAN}:${ip}`, String(expiresAt), duration);
         await storage.delete(violationsKey);

package/dist/shield.engine.d.ts

@@ -11,9 +11,11 @@ export interface EngineDecision {
 export declare class ShieldEngine {
     private readonly config;
     private readonly storage;
+    private bannerShown;
     constructor(config: ShieldConfig, storage: ShieldStorage);
     getConfig(): ShieldConfig;
     getStorage(): ShieldStorage;
+    markBannerShown(): boolean;
     run(req: AnyRequest, res: AnyResponse, overrides?: DecoratorOverrides): Promise<EngineDecision>;
     private merge;
     private mergeRateLimit;

package/dist/shield.engine.js

@@ -31,6 +31,7 @@ let ShieldEngine = class ShieldEngine {
     constructor(config, storage) {
         this.config = config;
         this.storage = storage;
+        this.bannerShown = false;
     }
     getConfig() {
         return this.config;
@@ -38,6 +39,12 @@ let ShieldEngine = class ShieldEngine {
     getStorage() {
         return this.storage;
     }
+    markBannerShown() {
+        if (this.bannerShown)
+            return false;
+        this.bannerShown = true;
+        return true;
+    }
     async run(req, res, overrides = {}) {
         if (this.config.enabled === false)
             return { allowed: true, ip: '' };
@@ -141,42 +148,54 @@ let ShieldEngine = class ShieldEngine {
             }
             release = burstOut.release;
         }
-        const rateLimit = this.mergeRateLimit(overrides);
-        let rateLimitTtl = 0;
-        if (!skipSet.has('rate-limit') && rateLimit) {
-            const rl = await rate_limit_check_1.RateLimitCheck.check(this.storage, req, ip, rateLimit);
-            rateLimitTtl = rateLimit.ttl;
-            if (rateLimit.headers !== false) {
-                headers_util_1.HeadersUtil.writeRateLimit(res, rateLimit.standardHeaders ?? 'draft-7', rl.limit, rl.remaining, rl.resetMs);
-            }
-            if (!rl.allowed) {
-                if (this.config.response?.rateLimit429?.includeRetryAfter !== false && rl.retryAfterMs) {
-                    headers_util_1.HeadersUtil.writeRetryAfter(res, rl.retryAfterMs);
+        try {
+            const rateLimit = this.mergeRateLimit(overrides);
+            let rateLimitTtl = 0;
+            if (!skipSet.has('rate-limit') && rateLimit) {
+                const rl = await rate_limit_check_1.RateLimitCheck.check(this.storage, req, ip, rateLimit);
+                rateLimitTtl = rateLimit.ttl;
+                if (rateLimit.headers !== false) {
+                    headers_util_1.HeadersUtil.writeRateLimit(res, rateLimit.standardHeaders ?? 'draft-7', rl.limit, rl.remaining, rl.resetMs);
                 }
-                await auto_ban_check_1.AutoBanCheck.recordViolation(this.storage, ip, this.config.autoBan);
-                if (release)
-                    await release();
-                this.notifyReject(req, res, ip, 'rate-limit', rl.reason ?? 'rate limited', 429, rl.retryAfterMs);
-                return {
-                    allowed: false,
-                    ip,
-                    exception: new shield_exceptions_1.ShieldRateLimitException({
-                        message: this.config.response?.rateLimit429?.message ?? rl.reason ?? 'Too many requests',
-                        code: this.config.response?.rateLimit429?.code,
-                        layer: 'rate-limit',
-                        retryAfter: rl.retryAfterMs ? Math.ceil(rl.retryAfterMs / 1000) : undefined,
-                    }),
-                };
+                if (!rl.allowed) {
+                    if (this.config.response?.rateLimit429?.includeRetryAfter !== false && rl.retryAfterMs) {
+                        headers_util_1.HeadersUtil.writeRetryAfter(res, rl.retryAfterMs);
+                    }
+                    await auto_ban_check_1.AutoBanCheck.recordViolation(this.storage, ip, this.config.autoBan);
+                    if (release)
+                        await release();
+                    this.notifyReject(req, res, ip, 'rate-limit', rl.reason ?? 'rate limited', 429, rl.retryAfterMs);
+                    return {
+                        allowed: false,
+                        ip,
+                        exception: new shield_exceptions_1.ShieldRateLimitException({
+                            message: this.config.response?.rateLimit429?.message ?? rl.reason ?? 'Too many requests',
+                            code: this.config.response?.rateLimit429?.code,
+                            layer: 'rate-limit',
+                            retryAfter: rl.retryAfterMs ? Math.ceil(rl.retryAfterMs / 1000) : undefined,
+                        }),
+                    };
+                }
+            }
+            let delayMs;
+            const slowDown = (overrides.slowDown ?? this.config.slowDown);
+            if (!skipSet.has('slow-down') && slowDown) {
+                const sd = await slow_down_check_1.SlowDownCheck.check(this.storage, ip, rateLimitTtl || 60_000, slowDown);
+                if (sd.delayMs && sd.delayMs > 0)
+                    delayMs = sd.delayMs;
             }
+            return { allowed: true, ip, delayMs, release };
         }
-        let delayMs;
-        const slowDown = (overrides.slowDown ?? this.config.slowDown);
-        if (!skipSet.has('slow-down') && slowDown) {
-            const sd = await slow_down_check_1.SlowDownCheck.check(this.storage, ip, rateLimitTtl || 60_000, slowDown);
-            if (sd.delayMs && sd.delayMs > 0)
-                delayMs = sd.delayMs;
+        catch (err) {
+            if (release) {
+                try {
+                    await release();
+                }
+                catch {
+                }
+            }
+            throw err;
         }
-        return { allowed: true, ip, delayMs, release };
     }
     merge(base, override) {
         if (!base && !override)

package/dist/shield.module.d.ts

@@ -1,13 +1,18 @@
-import { DynamicModule, ModuleMetadata, OnModuleDestroy, Type } from '@nestjs/common';
+import { DynamicModule, ModuleMetadata, OnApplicationBootstrap, OnModuleDestroy, Type } from '@nestjs/common';
+import { ShieldEngine } from './shield.engine';
 import type { ShieldConfig } from './shield.types';
 import type { ShieldStorage } from './storage/shield-storage.interface';
 export interface ShieldAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
     useFactory: (...args: unknown[]) => Promise<ShieldConfig> | ShieldConfig;
     inject?: (string | symbol | Type<unknown>)[];
 }
-export declare class ShieldModule implements OnModuleDestroy {
+export declare class ShieldModule implements OnApplicationBootstrap, OnModuleDestroy {
     private readonly storage;
-    constructor(storage: ShieldStorage);
+    private readonly config;
+    private readonly engine;
+    private readonly logger;
+    constructor(storage: ShieldStorage, config: ShieldConfig, engine: ShieldEngine);
+    onApplicationBootstrap(): void;
     static forRoot(config?: ShieldConfig): DynamicModule;
     static forRootAsync(options: ShieldAsyncOptions): DynamicModule;
     onModuleDestroy(): Promise<void>;

package/dist/shield.module.js

@@ -21,6 +21,7 @@ const shield_engine_1 = require("./shield.engine");
 const shield_guard_1 = require("./shield.guard");
 const memory_storage_1 = require("./storage/memory.storage");
 const redis_storage_1 = require("./storage/redis.storage");
+const banner_util_1 = require("./utils/banner.util");
 function buildStorage(option) {
     if (!option || option === 'memory')
         return new memory_storage_1.MemoryStorage();
@@ -37,8 +38,20 @@ function buildStorage(option) {
     return option;
 }
 let ShieldModule = ShieldModule_1 = class ShieldModule {
-    constructor(storage) {
+    constructor(storage, config, engine) {
         this.storage = storage;
+        this.config = config;
+        this.engine = engine;
+        this.logger = new common_1.Logger('Shield');
+    }
+    onApplicationBootstrap() {
+        if (this.config.enabled === false)
+            return;
+        if (!this.engine.markBannerShown())
+            return;
+        const { banner, summary } = banner_util_1.BannerUtil.build(this.config);
+        process.stdout.write(banner + '\n');
+        this.logger.log(summary);
     }
     static forRoot(config = {}) {
         const providers = [
@@ -101,5 +114,7 @@ exports.ShieldModule = ShieldModule;
 exports.ShieldModule = ShieldModule = ShieldModule_1 = __decorate([
     (0, common_1.Module)({}),
     __param(0, (0, common_1.Inject)(shield_constants_1.SHIELD_STORAGE)),
-    __metadata("design:paramtypes", [Object])
+    __param(1, (0, common_1.Inject)(shield_constants_1.SHIELD_CONFIG)),
+    __param(2, (0, common_1.Inject)(shield_constants_1.SHIELD_ENGINE)),
+    __metadata("design:paramtypes", [Object, Object, shield_engine_1.ShieldEngine])
 ], ShieldModule);

package/dist/shield.types.d.ts

@@ -25,6 +25,7 @@ export interface AutoBanConfig {
     window: number;
     banDuration: number;
     escalate?: boolean;
+    maxBanDuration?: number;
 }
 export interface SlowDownConfig {
     delayAfter: number;

package/dist/storage/redis.storage.js

@@ -99,6 +99,31 @@ end
 
 return { allowed, count, resetMs }
 `;
+const INCREMENT_LUA = `
+local key = KEYS[1]
+local by = tonumber(ARGV[1])
+local ttlMs = tonumber(ARGV[2])
+local count = redis.call('INCRBY', key, by)
+if count == by then
+  redis.call('PEXPIRE', key, ttlMs)
+end
+local ttl = redis.call('PTTL', key)
+if ttl < 0 then ttl = 0 end
+return { count, ttl }
+`;
+const BURST_INCREMENT_LUA = `
+local count = redis.call('INCR', KEYS[1])
+redis.call('PEXPIRE', KEYS[1], ARGV[1])
+return count
+`;
+const BURST_DECREMENT_LUA = `
+local count = tonumber(redis.call('GET', KEYS[1]) or '0')
+if count <= 1 then
+  redis.call('DEL', KEYS[1])
+  return 0
+end
+return redis.call('DECR', KEYS[1])
+`;
 const SLIDING_COUNTER_LUA = `
 local cur = KEYS[1]
 local prev = KEYS[2]
@@ -129,10 +154,11 @@ class RedisStorage {
     }
     async increment(key, ttlMs, by = 1) {
         const k = this.k(key);
-        const count = by === 1 ? await this.client.incr(k) : await this.client.incrby(k, by);
-        await this.client.pexpire(k, ttlMs);
-        const ttl = await this.client.pttl(k);
-        return { count, expiresAt: Date.now() + Math.max(0, ttl) };
+        const res = (await this.runScript('shieldIncrement', INCREMENT_LUA, [k], [by, ttlMs]));
+        return {
+            count: Number(res[0]),
+            expiresAt: Date.now() + Math.max(0, Number(res[1])),
+        };
     }
     async consumeToken(key, capacity, refillPerMs, cost = 1) {
         const k = this.k(key);
@@ -153,11 +179,9 @@ class RedisStorage {
     }
     async fixedWindow(key, ttlMs, limit) {
         const k = this.k(key);
-        const count = await this.client.incr(k);
-        if (count === 1)
-            await this.client.pexpire(k, ttlMs);
-        const ttl = await this.client.pttl(k);
-        return { count, allowed: count <= limit, resetMs: Math.max(0, ttl), limit };
+        const res = (await this.runScript('shieldIncrement', INCREMENT_LUA, [k], [1, ttlMs]));
+        const count = Number(res[0]);
+        return { count, allowed: count <= limit, resetMs: Math.max(0, Number(res[1])), limit };
     }
     async slidingWindowCounter(key, ttlMs, limit) {
         const now = Date.now();
@@ -212,16 +236,13 @@ class RedisStorage {
     }
     async incrementConcurrent(key) {
         const k = this.k(`burst:${key}`);
-        const next = await this.client.incr(k);
-        await this.client.pexpire(k, 60_000);
-        return next;
+        const next = await this.runScript('shieldBurstIncrement', BURST_INCREMENT_LUA, [k], [60_000]);
+        return Number(next);
     }
     async decrementConcurrent(key) {
         const k = this.k(`burst:${key}`);
-        const next = await this.client.decr(k);
-        if (next <= 0)
-            await this.client.del(k);
-        return Math.max(0, next);
+        const next = await this.runScript('shieldBurstDecrement', BURST_DECREMENT_LUA, [k], []);
+        return Math.max(0, Number(next));
     }
     k(key) {
         return this.prefix ? `${this.prefix}:${key}` : key;
@@ -241,6 +262,9 @@ class RedisStorage {
             this.client.defineCommand('shieldLeakyBucket', { numberOfKeys: 1, lua: LEAKY_BUCKET_LUA });
             this.client.defineCommand('shieldSlidingLog', { numberOfKeys: 1, lua: SLIDING_LOG_LUA });
             this.client.defineCommand('shieldSlidingCounter', { numberOfKeys: 2, lua: SLIDING_COUNTER_LUA });
+            this.client.defineCommand('shieldIncrement', { numberOfKeys: 1, lua: INCREMENT_LUA });
+            this.client.defineCommand('shieldBurstIncrement', { numberOfKeys: 1, lua: BURST_INCREMENT_LUA });
+            this.client.defineCommand('shieldBurstDecrement', { numberOfKeys: 1, lua: BURST_DECREMENT_LUA });
             this.commandsDefined = true;
         }
         catch {

package/dist/utils/banner.util.d.ts

@@ -0,0 +1,10 @@
+import type { ShieldConfig } from '../shield.types';
+export declare class BannerUtil {
+    static build(config: ShieldConfig): {
+        banner: string;
+        summary: string;
+    };
+    private static centerPad;
+    private static storageLabel;
+    private static version;
+}

package/dist/utils/banner.util.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BannerUtil = void 0;
+class BannerUtil {
+    static build(config) {
+        const version = BannerUtil.version();
+        const title = `nestjs-shield v${version}  --  up and running`;
+        const inner = ` ${title} `;
+        const width = Math.max(inner.length, 50);
+        const padded = BannerUtil.centerPad(inner, width);
+        const top = '   +' + '-'.repeat(width) + '+';
+        const mid = '   |' + ' '.repeat(width) + '|';
+        const banner = [
+            '',
+            top,
+            mid,
+            '   |' + padded + '|',
+            mid,
+            '   +' + '-'.repeat(width) + '+',
+            '',
+        ].join('\n');
+        const layers = [];
+        if (config.whitelist)
+            layers.push('whitelist');
+        if (config.blacklist)
+            layers.push('blacklist');
+        if (config.autoBan)
+            layers.push('auto-ban');
+        if (config.userAgent)
+            layers.push('user-agent');
+        if (config.payload)
+            layers.push('payload');
+        if (config.burst)
+            layers.push('burst');
+        if (config.rateLimit)
+            layers.push('rate-limit');
+        if (config.slowDown)
+            layers.push('slow-down');
+        const parts = [`storage=${BannerUtil.storageLabel(config)}`];
+        if (config.rateLimit) {
+            const rl = config.rateLimit;
+            const seconds = Math.max(1, Math.round(rl.ttl / 1000));
+            parts.push(`rate=${rl.limit}/${seconds}s (${rl.algorithm ?? 'token-bucket'})`);
+        }
+        if (layers.length)
+            parts.push(`layers=[${layers.join(', ')}]`);
+        return { banner, summary: parts.join(' | ') };
+    }
+    static centerPad(text, width) {
+        if (text.length >= width)
+            return text.slice(0, width);
+        const total = width - text.length;
+        const left = Math.floor(total / 2);
+        const right = total - left;
+        return ' '.repeat(left) + text + ' '.repeat(right);
+    }
+    static storageLabel(config) {
+        const s = config.storage;
+        if (!s || s === 'memory')
+            return 'memory';
+        if (typeof s === 'object' && 'type' in s)
+            return s.type;
+        return 'custom';
+    }
+    static version() {
+        try {
+            const pkg = require('../../package.json');
+            return pkg.version ?? '?';
+        }
+        catch {
+            return '?';
+        }
+    }
+}
+exports.BannerUtil = BannerUtil;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nestjs-shield",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Layered API protection for NestJS: rate limiting, IP allow/block lists, auto-ban, slow-down, UA filtering, burst caps, payload limits. Pluggable storage (memory/Redis).",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -51,8 +51,8 @@
     "node": ">=18"
   },
   "peerDependencies": {
-    "@nestjs/common": "^9.0.0 || ^10.0.0 || ^11.0.0",
-    "@nestjs/core": "^9.0.0 || ^10.0.0 || ^11.0.0",
+    "@nestjs/common": "^9.0.0 || ^10.0.0 || ^11.0.0 || ^12.0.0",
+    "@nestjs/core": "^9.0.0 || ^10.0.0 || ^11.0.0 || ^12.0.0",
     "reflect-metadata": "^0.1.13 || ^0.2.0",
     "rxjs": "^7.0.0"
   },
@@ -65,9 +65,9 @@
     "ipaddr.js": "^2.2.0"
   },
   "devDependencies": {
-    "@nestjs/common": "^10.4.0",
-    "@nestjs/core": "^10.4.0",
-    "@types/node": "^20.12.0",
+    "@nestjs/common": "^12.0.1",
+    "@nestjs/core": "^12.0.1",
+    "@types/node": "^22.0.0",
     "ioredis": "^5.4.1",
     "reflect-metadata": "^0.2.2",
     "rimraf": "^5.0.7",