nestjs-shield 1.0.0

package/dist/shield.engine.js

@@ -0,0 +1,215 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShieldEngine = void 0;
+const common_1 = require("@nestjs/common");
+const auto_ban_check_1 = require("./checks/auto-ban.check");
+const blacklist_check_1 = require("./checks/blacklist.check");
+const burst_check_1 = require("./checks/burst.check");
+const payload_check_1 = require("./checks/payload.check");
+const rate_limit_check_1 = require("./checks/rate-limit.check");
+const slow_down_check_1 = require("./checks/slow-down.check");
+const user_agent_check_1 = require("./checks/user-agent.check");
+const whitelist_check_1 = require("./checks/whitelist.check");
+const shield_exceptions_1 = require("./exceptions/shield.exceptions");
+const shield_constants_1 = require("./shield.constants");
+const headers_util_1 = require("./utils/headers.util");
+const ip_util_1 = require("./utils/ip.util");
+const ua_util_1 = require("./utils/ua.util");
+let ShieldEngine = class ShieldEngine {
+    constructor(config, storage) {
+        this.config = config;
+        this.storage = storage;
+    }
+    getConfig() {
+        return this.config;
+    }
+    getStorage() {
+        return this.storage;
+    }
+    async run(req, res, overrides = {}) {
+        if (this.config.enabled === false)
+            return { allowed: true, ip: '' };
+        const ip = this.config.ipResolver
+            ? this.config.ipResolver(req)
+            : ip_util_1.IpUtil.resolve(req, this.config.trustProxy);
+        if (overrides.skip === true)
+            return { allowed: true, ip };
+        const skipSet = new Set(Array.isArray(overrides.skip) ? overrides.skip : []);
+        const whitelist = this.merge(this.config.whitelist, overrides.whitelist);
+        if (!skipSet.has('whitelist')) {
+            const wl = whitelist_check_1.WhitelistCheck.run(ip, whitelist);
+            if (wl.allowed && wl.layer === 'whitelist')
+                return { allowed: true, ip };
+        }
+        const blacklist = this.merge(this.config.blacklist, overrides.blacklist);
+        if (!skipSet.has('blacklist')) {
+            const bl = blacklist_check_1.BlacklistCheck.run(ip, blacklist);
+            if (!bl.allowed) {
+                await auto_ban_check_1.AutoBanCheck.recordViolation(this.storage, ip, this.config.autoBan);
+                this.notifyReject(req, res, ip, bl.layer ?? 'blacklist', bl.reason ?? 'blocked', bl.status ?? 403);
+                return {
+                    allowed: false,
+                    ip,
+                    exception: new shield_exceptions_1.ShieldBlockedException({
+                        message: this.config.response?.blocked403?.message ?? bl.reason ?? 'Forbidden',
+                        code: this.config.response?.blocked403?.code,
+                        layer: 'blacklist',
+                        status: bl.status,
+                    }),
+                };
+            }
+        }
+        if (!skipSet.has('auto-ban')) {
+            const ab = await auto_ban_check_1.AutoBanCheck.check(this.storage, ip, this.config.autoBan);
+            if (!ab.allowed) {
+                if (ab.retryAfterMs)
+                    headers_util_1.HeadersUtil.writeRetryAfter(res, ab.retryAfterMs);
+                this.notifyReject(req, res, ip, 'auto-ban', ab.reason ?? 'banned', ab.status ?? 403, ab.retryAfterMs);
+                return {
+                    allowed: false,
+                    ip,
+                    exception: new shield_exceptions_1.ShieldBlockedException({
+                        message: this.config.response?.blocked403?.message ?? ab.reason ?? 'Forbidden',
+                        code: this.config.response?.blocked403?.code,
+                        layer: 'auto-ban',
+                        retryAfter: ab.retryAfterMs ? Math.ceil(ab.retryAfterMs / 1000) : undefined,
+                    }),
+                };
+            }
+        }
+        const ua = ua_util_1.UaUtil.extract(req.headers);
+        const userAgent = (overrides.userAgent ?? this.config.userAgent);
+        if (!skipSet.has('user-agent')) {
+            const uaOut = user_agent_check_1.UserAgentCheck.run(ua, userAgent);
+            if (!uaOut.allowed) {
+                await auto_ban_check_1.AutoBanCheck.recordViolation(this.storage, ip, this.config.autoBan);
+                this.notifyReject(req, res, ip, 'user-agent', uaOut.reason ?? 'blocked', 403);
+                return {
+                    allowed: false,
+                    ip,
+                    exception: new shield_exceptions_1.ShieldBlockedException({
+                        message: this.config.response?.blocked403?.message ?? uaOut.reason ?? 'Forbidden',
+                        code: this.config.response?.blocked403?.code,
+                        layer: 'user-agent',
+                    }),
+                };
+            }
+        }
+        const payload = (overrides.maxPayload ?? this.config.payload);
+        if (!skipSet.has('payload')) {
+            const pl = payload_check_1.PayloadCheck.run(req, payload);
+            if (!pl.allowed) {
+                this.notifyReject(req, res, ip, 'payload', pl.reason ?? 'too large', pl.status ?? 413);
+                return {
+                    allowed: false,
+                    ip,
+                    exception: new shield_exceptions_1.ShieldPayloadException({
+                        message: this.config.response?.payload413?.message ?? pl.reason ?? 'Payload too large',
+                        code: this.config.response?.payload413?.code,
+                        layer: 'payload',
+                    }),
+                };
+            }
+        }
+        let release;
+        const burst = (overrides.burst ?? this.config.burst);
+        if (!skipSet.has('burst') && burst) {
+            const burstOut = await burst_check_1.BurstCheck.check(this.storage, ip, burst);
+            if (!burstOut.allowed) {
+                this.notifyReject(req, res, ip, 'burst', burstOut.reason ?? 'too many concurrent', 429);
+                return {
+                    allowed: false,
+                    ip,
+                    exception: new shield_exceptions_1.ShieldRateLimitException({
+                        message: this.config.response?.rateLimit429?.message ?? burstOut.reason ?? 'Too many concurrent requests',
+                        code: this.config.response?.rateLimit429?.code,
+                        layer: 'burst',
+                    }),
+                };
+            }
+            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);
+                }
+                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 };
+    }
+    merge(base, override) {
+        if (!base && !override)
+            return undefined;
+        if (!base)
+            return override;
+        if (!override)
+            return base;
+        return { ...base, ...override };
+    }
+    mergeRateLimit(overrides) {
+        if (!this.config.rateLimit && !overrides.rateLimit)
+            return undefined;
+        if (overrides.rateLimit) {
+            return { ...(this.config.rateLimit ?? {}), ...overrides.rateLimit };
+        }
+        return this.config.rateLimit;
+    }
+    notifyReject(req, res, ip, layer, reason, status, retryAfterMs) {
+        const hook = this.config.response?.onReject;
+        if (!hook)
+            return;
+        try {
+            hook(req, res, { ip, layer, reason, status, retryAfterMs });
+        }
+        catch {
+        }
+    }
+};
+exports.ShieldEngine = ShieldEngine;
+exports.ShieldEngine = ShieldEngine = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(shield_constants_1.SHIELD_CONFIG)),
+    __param(1, (0, common_1.Inject)(shield_constants_1.SHIELD_STORAGE)),
+    __metadata("design:paramtypes", [Object, Object])
+], ShieldEngine);

package/dist/shield.guard.d.ts

@@ -0,0 +1,10 @@
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { ShieldEngine } from './shield.engine';
+export declare class ShieldGuard implements CanActivate {
+    private readonly engine;
+    private readonly reflector;
+    constructor(engine: ShieldEngine, reflector: Reflector);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    private collectOverrides;
+}

package/dist/shield.guard.js

@@ -0,0 +1,89 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShieldGuard = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const shield_constants_1 = require("./shield.constants");
+const shield_engine_1 = require("./shield.engine");
+let ShieldGuard = class ShieldGuard {
+    constructor(engine, reflector) {
+        this.engine = engine;
+        this.reflector = reflector;
+    }
+    async canActivate(context) {
+        if (context.getType() !== 'http')
+            return true;
+        const http = context.switchToHttp();
+        const req = http.getRequest();
+        const res = http.getResponse();
+        const overrides = this.collectOverrides(context);
+        const decision = await this.engine.run(req, res, overrides);
+        if (!decision.allowed) {
+            if (decision.exception)
+                throw decision.exception;
+            return false;
+        }
+        if (decision.release) {
+            const fired = { done: false };
+            const fire = () => {
+                if (fired.done)
+                    return;
+                fired.done = true;
+                Promise.resolve(decision.release?.()).catch(() => undefined);
+            };
+            if (typeof res.on === 'function') {
+                res.on('finish', fire);
+                res.on('close', fire);
+            }
+            else {
+                setImmediate(fire);
+            }
+        }
+        if (decision.delayMs && decision.delayMs > 0) {
+            await new Promise((r) => setTimeout(r, decision.delayMs));
+        }
+        return true;
+    }
+    collectOverrides(context) {
+        const targets = [context.getHandler(), context.getClass()];
+        const skip = this.reflector.getAllAndOverride(shield_constants_1.META_SKIP, targets);
+        const rateLimit = this.reflector.getAllAndOverride(shield_constants_1.META_RATE_LIMIT, targets);
+        const blacklist = this.reflector.getAllAndOverride(shield_constants_1.META_BLACKLIST, targets);
+        const whitelist = this.reflector.getAllAndOverride(shield_constants_1.META_WHITELIST, targets);
+        const slowDown = this.reflector.getAllAndOverride(shield_constants_1.META_SLOW_DOWN, targets);
+        const maxPayload = this.reflector.getAllAndOverride(shield_constants_1.META_MAX_PAYLOAD, targets);
+        const burst = this.reflector.getAllAndOverride(shield_constants_1.META_BURST, targets);
+        const userAgent = this.reflector.getAllAndOverride(shield_constants_1.META_UA, targets);
+        return {
+            skip,
+            rateLimit: rateLimit
+                ? { ...rateLimit, limit: rateLimit.limit, ttl: rateLimit.ttl }
+                : undefined,
+            blacklist,
+            whitelist,
+            slowDown,
+            maxPayload,
+            burst,
+            userAgent,
+        };
+    }
+};
+exports.ShieldGuard = ShieldGuard;
+exports.ShieldGuard = ShieldGuard = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(shield_constants_1.SHIELD_ENGINE)),
+    __metadata("design:paramtypes", [shield_engine_1.ShieldEngine,
+        core_1.Reflector])
+], ShieldGuard);

package/dist/shield.middleware.d.ts

@@ -0,0 +1,5 @@
+import type { ShieldEngine } from './shield.engine';
+import type { AnyRequest, AnyResponse } from './shield.types';
+type NextFn = (err?: unknown) => void;
+export declare function createShieldMiddleware(engine: ShieldEngine): (req: AnyRequest, res: AnyResponse, next: NextFn) => Promise<void>;
+export {};

package/dist/shield.middleware.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createShieldMiddleware = createShieldMiddleware;
+function createShieldMiddleware(engine) {
+    return async function shieldMiddleware(req, res, next) {
+        try {
+            const decision = await engine.run(req, res);
+            if (!decision.allowed && decision.exception) {
+                const exc = decision.exception;
+                const response = exc.getResponse();
+                const status = exc.getStatus();
+                if (typeof res.status === 'function') {
+                    const r = res.status(status);
+                    if (typeof r.json === 'function') {
+                        r.json(response);
+                        return;
+                    }
+                }
+                if (typeof res.setHeader === 'function') {
+                    res.setHeader('Content-Type', 'application/json');
+                }
+                res.statusCode = status;
+                if (typeof res.end === 'function')
+                    res.end(JSON.stringify(response));
+                return;
+            }
+            if (decision.release && typeof res.on === 'function') {
+                const fired = { done: false };
+                const fire = () => {
+                    if (fired.done)
+                        return;
+                    fired.done = true;
+                    Promise.resolve(decision.release?.()).catch(() => undefined);
+                };
+                res.on('finish', fire);
+                res.on('close', fire);
+            }
+            if (decision.delayMs && decision.delayMs > 0) {
+                await new Promise((r) => setTimeout(r, decision.delayMs));
+            }
+            next();
+        }
+        catch (err) {
+            next(err);
+        }
+    };
+}

package/dist/shield.module.d.ts

@@ -0,0 +1,14 @@
+import { DynamicModule, ModuleMetadata, OnModuleDestroy, Type } from '@nestjs/common';
+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 {
+    private readonly storage;
+    constructor(storage: ShieldStorage);
+    static forRoot(config?: ShieldConfig): DynamicModule;
+    static forRootAsync(options: ShieldAsyncOptions): DynamicModule;
+    onModuleDestroy(): Promise<void>;
+}

package/dist/shield.module.js

@@ -0,0 +1,105 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var ShieldModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShieldModule = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const shield_constants_1 = require("./shield.constants");
+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");
+function buildStorage(option) {
+    if (!option || option === 'memory')
+        return new memory_storage_1.MemoryStorage();
+    if (typeof option === 'object' && 'type' in option) {
+        if (option.type === 'memory')
+            return new memory_storage_1.MemoryStorage({ maxKeys: option.maxKeys });
+        if (option.type === 'redis') {
+            return new redis_storage_1.RedisStorage({
+                client: option.client,
+                keyPrefix: option.keyPrefix,
+            });
+        }
+    }
+    return option;
+}
+let ShieldModule = ShieldModule_1 = class ShieldModule {
+    constructor(storage) {
+        this.storage = storage;
+    }
+    static forRoot(config = {}) {
+        const providers = [
+            { provide: shield_constants_1.SHIELD_CONFIG, useValue: config },
+            {
+                provide: shield_constants_1.SHIELD_STORAGE,
+                useFactory: () => buildStorage(config.storage),
+            },
+            core_1.Reflector,
+            {
+                provide: shield_constants_1.SHIELD_ENGINE,
+                useFactory: (cfg, storage) => new shield_engine_1.ShieldEngine(cfg, storage),
+                inject: [shield_constants_1.SHIELD_CONFIG, shield_constants_1.SHIELD_STORAGE],
+            },
+            shield_guard_1.ShieldGuard,
+            { provide: core_1.APP_GUARD, useExisting: shield_guard_1.ShieldGuard },
+        ];
+        return {
+            module: ShieldModule_1,
+            global: true,
+            providers,
+            exports: [shield_constants_1.SHIELD_CONFIG, shield_constants_1.SHIELD_STORAGE, shield_constants_1.SHIELD_ENGINE, shield_guard_1.ShieldGuard],
+        };
+    }
+    static forRootAsync(options) {
+        const providers = [
+            {
+                provide: shield_constants_1.SHIELD_CONFIG,
+                useFactory: options.useFactory,
+                inject: options.inject ?? [],
+            },
+            {
+                provide: shield_constants_1.SHIELD_STORAGE,
+                useFactory: (cfg) => buildStorage(cfg.storage),
+                inject: [shield_constants_1.SHIELD_CONFIG],
+            },
+            core_1.Reflector,
+            {
+                provide: shield_constants_1.SHIELD_ENGINE,
+                useFactory: (cfg, storage) => new shield_engine_1.ShieldEngine(cfg, storage),
+                inject: [shield_constants_1.SHIELD_CONFIG, shield_constants_1.SHIELD_STORAGE],
+            },
+            shield_guard_1.ShieldGuard,
+            { provide: core_1.APP_GUARD, useExisting: shield_guard_1.ShieldGuard },
+        ];
+        return {
+            module: ShieldModule_1,
+            global: true,
+            imports: options.imports ?? [],
+            providers,
+            exports: [shield_constants_1.SHIELD_CONFIG, shield_constants_1.SHIELD_STORAGE, shield_constants_1.SHIELD_ENGINE, shield_guard_1.ShieldGuard],
+        };
+    }
+    async onModuleDestroy() {
+        if (this.storage?.dispose)
+            await this.storage.dispose();
+    }
+};
+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])
+], ShieldModule);

package/dist/shield.types.d.ts

@@ -0,0 +1,141 @@
+import type { ShieldLayer } from './shield.constants';
+import type { ShieldStorage } from './storage/shield-storage.interface';
+export type RateLimitAlgorithm = 'token-bucket' | 'sliding-window' | 'sliding-window-log' | 'fixed-window' | 'leaky-bucket';
+export type KeyByOption = 'ip' | {
+    header: string;
+} | ((req: AnyRequest) => string);
+export interface RateLimitConfig {
+    algorithm?: RateLimitAlgorithm;
+    limit: number;
+    ttl: number;
+    keyBy?: KeyByOption;
+    skip?: (req: AnyRequest) => boolean;
+    headers?: boolean;
+    standardHeaders?: 'draft-6' | 'draft-7';
+}
+export interface IpListConfig {
+    ips?: string[];
+    cidrs?: string[];
+}
+export interface BlacklistConfig extends IpListConfig {
+    statusCode?: number;
+}
+export interface AutoBanConfig {
+    threshold: number;
+    window: number;
+    banDuration: number;
+    escalate?: boolean;
+}
+export interface SlowDownConfig {
+    delayAfter: number;
+    delayMs: number | ((hit: number) => number);
+    maxDelayMs?: number;
+}
+export interface UserAgentConfig {
+    block?: (string | RegExp)[];
+    allow?: (string | RegExp)[];
+    requirePresent?: boolean;
+}
+export interface BurstConfig {
+    maxConcurrent: number;
+}
+export interface PayloadConfig {
+    maxBodyBytes?: number;
+    maxHeaderBytes?: number;
+}
+export interface RejectInfo {
+    layer: ShieldLayer;
+    ip: string;
+    reason: string;
+    status: number;
+    retryAfterMs?: number;
+}
+export interface ResponseConfig {
+    rateLimit429?: {
+        message?: string;
+        code?: string;
+        includeRetryAfter?: boolean;
+    };
+    blocked403?: {
+        message?: string;
+        code?: string;
+    };
+    payload413?: {
+        message?: string;
+        code?: string;
+    };
+    onReject?: (req: AnyRequest, res: AnyResponse, info: RejectInfo) => void;
+}
+export type StorageOption = ShieldStorage | 'memory' | {
+    type: 'memory';
+    maxKeys?: number;
+} | {
+    type: 'redis';
+    client: unknown;
+    keyPrefix?: string;
+};
+export interface ShieldConfig {
+    enabled?: boolean;
+    trustProxy?: boolean | number;
+    ipResolver?: (req: AnyRequest) => string;
+    storage?: StorageOption;
+    rateLimit?: RateLimitConfig;
+    whitelist?: IpListConfig;
+    blacklist?: BlacklistConfig;
+    autoBan?: AutoBanConfig;
+    slowDown?: SlowDownConfig;
+    userAgent?: UserAgentConfig;
+    burst?: BurstConfig;
+    payload?: PayloadConfig;
+    response?: ResponseConfig;
+}
+export type AnyRequest = {
+    ip?: string;
+    ips?: string[];
+    headers: Record<string, string | string[] | undefined>;
+    socket?: {
+        remoteAddress?: string;
+    };
+    connection?: {
+        remoteAddress?: string;
+    };
+    method?: string;
+    url?: string;
+    body?: unknown;
+    [key: string]: unknown;
+};
+export type AnyResponse = {
+    statusCode?: number;
+    setHeader: (name: string, value: string | number) => void;
+    status?: (code: number) => AnyResponse;
+    json?: (body: unknown) => AnyResponse;
+    end?: (body?: unknown) => AnyResponse;
+    on?: (event: string, cb: () => void) => void;
+    [key: string]: unknown;
+};
+export interface DecoratorOverrides {
+    skip?: true | ShieldLayer[];
+    rateLimit?: Partial<RateLimitConfig> & {
+        limit: number;
+        ttl: number;
+    };
+    blacklist?: IpListConfig;
+    whitelist?: IpListConfig;
+    slowDown?: SlowDownConfig;
+    maxPayload?: PayloadConfig;
+    burst?: BurstConfig;
+    userAgent?: UserAgentConfig;
+}
+export interface CheckOutcome {
+    allowed: boolean;
+    layer?: ShieldLayer;
+    status?: number;
+    reason?: string;
+    retryAfterMs?: number;
+    headers?: Record<string, string | number>;
+    delayMs?: number;
+    release?: () => Promise<void> | void;
+}
+export interface ResolvedConfig extends Omit<ShieldConfig, 'rateLimit'> {
+    rateLimit?: RateLimitConfig;
+}

package/dist/shield.types.js

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

package/dist/storage/memory.storage.d.ts

@@ -0,0 +1,30 @@
+import type { CounterResult, ShieldStorage, TokenBucketResult, WindowResult } from './shield-storage.interface';
+export interface MemoryStorageOptions {
+    maxKeys?: number;
+}
+export declare class MemoryStorage implements ShieldStorage {
+    private readonly maxKeys;
+    private readonly map;
+    private readonly buckets;
+    private readonly logs;
+    private readonly counters;
+    private sweepTimer;
+    constructor(opts?: MemoryStorageOptions);
+    increment(key: string, ttlMs: number, by?: number): Promise<CounterResult>;
+    consumeToken(key: string, capacity: number, refillPerMs: number, cost?: number): Promise<TokenBucketResult>;
+    fixedWindow(key: string, ttlMs: number, limit: number): Promise<WindowResult>;
+    slidingWindowCounter(key: string, ttlMs: number, limit: number): Promise<WindowResult>;
+    slidingWindowLog(key: string, ttlMs: number, limit: number, now?: number): Promise<WindowResult>;
+    leakyBucket(key: string, capacity: number, leakPerMs: number): Promise<TokenBucketResult>;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    incrementConcurrent(key: string): Promise<number>;
+    decrementConcurrent(key: string): Promise<number>;
+    dispose(): void;
+    private set_;
+    private evictIfNeeded;
+    private ttlFromRefill;
+    private startSweeper;
+    private sweep;
+}