nestjs-shield 1.0.0

package/dist/storage/memory.storage.js

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryStorage = void 0;
+const shield_constants_1 = require("../shield.constants");
+class MemoryStorage {
+    constructor(opts = {}) {
+        this.map = new Map();
+        this.buckets = new Map();
+        this.logs = new Map();
+        this.counters = new Map();
+        this.sweepTimer = null;
+        this.maxKeys = opts.maxKeys ?? shield_constants_1.DEFAULT_MEMORY_MAX_KEYS;
+        this.startSweeper();
+    }
+    async increment(key, ttlMs, by = 1) {
+        const now = Date.now();
+        const existing = this.map.get(key);
+        if (!existing || existing.expiresAt <= now) {
+            const entry = { value: String(by), expiresAt: now + ttlMs };
+            this.set_(key, entry);
+            return { count: by, expiresAt: entry.expiresAt };
+        }
+        const next = Number(existing.value) + by;
+        existing.value = String(next);
+        return { count: next, expiresAt: existing.expiresAt };
+    }
+    async consumeToken(key, capacity, refillPerMs, cost = 1) {
+        const now = Date.now();
+        let bucket = this.buckets.get(key);
+        if (!bucket || bucket.expiresAt <= now) {
+            bucket = { tokens: capacity, last: now, expiresAt: now + this.ttlFromRefill(capacity, refillPerMs) };
+            this.evictIfNeeded(this.buckets);
+            this.buckets.set(key, bucket);
+        }
+        const elapsed = now - bucket.last;
+        bucket.tokens = Math.min(capacity, bucket.tokens + elapsed * refillPerMs);
+        bucket.last = now;
+        bucket.expiresAt = now + this.ttlFromRefill(capacity, refillPerMs);
+        const allowed = bucket.tokens >= cost;
+        if (allowed)
+            bucket.tokens -= cost;
+        const deficit = Math.max(0, cost - bucket.tokens);
+        const resetMs = refillPerMs > 0 ? Math.ceil(deficit / refillPerMs) : 0;
+        return {
+            allowed,
+            remaining: Math.max(0, Math.floor(bucket.tokens)),
+            resetMs,
+            limit: capacity,
+        };
+    }
+    async fixedWindow(key, ttlMs, limit) {
+        const now = Date.now();
+        const existing = this.map.get(key);
+        let count;
+        let expiresAt;
+        if (!existing || existing.expiresAt <= now) {
+            expiresAt = now + ttlMs;
+            count = 1;
+            this.set_(key, { value: '1', expiresAt });
+        }
+        else {
+            count = Number(existing.value) + 1;
+            existing.value = String(count);
+            expiresAt = existing.expiresAt;
+        }
+        return { count, allowed: count <= limit, resetMs: Math.max(0, expiresAt - now), limit };
+    }
+    async slidingWindowCounter(key, ttlMs, limit) {
+        const now = Date.now();
+        const windowStart = Math.floor(now / ttlMs) * ttlMs;
+        const currentKey = `${key}:c:${windowStart}`;
+        const prevKey = `${key}:c:${windowStart - ttlMs}`;
+        const elapsedInWindow = now - windowStart;
+        const weight = 1 - elapsedInWindow / ttlMs;
+        const current = await this.increment(currentKey, ttlMs * 2);
+        const prevRaw = this.map.get(prevKey);
+        const prevCount = prevRaw && prevRaw.expiresAt > now ? Number(prevRaw.value) : 0;
+        const weighted = prevCount * weight + current.count;
+        const allowed = weighted <= limit;
+        const resetMs = Math.max(0, ttlMs - elapsedInWindow);
+        return { count: Math.ceil(weighted), allowed, resetMs, limit };
+    }
+    async slidingWindowLog(key, ttlMs, limit, now = Date.now()) {
+        let log = this.logs.get(key);
+        if (!log) {
+            log = { hits: [], expiresAt: now + ttlMs };
+            this.evictIfNeeded(this.logs);
+            this.logs.set(key, log);
+        }
+        const threshold = now - ttlMs;
+        log.hits = log.hits.filter((t) => t > threshold);
+        const allowed = log.hits.length < limit;
+        if (allowed)
+            log.hits.push(now);
+        log.expiresAt = now + ttlMs;
+        const oldest = log.hits[0] ?? now;
+        const resetMs = Math.max(0, oldest + ttlMs - now);
+        return { count: log.hits.length, allowed, resetMs, limit };
+    }
+    async leakyBucket(key, capacity, leakPerMs) {
+        const now = Date.now();
+        let bucket = this.buckets.get(key);
+        if (!bucket || bucket.expiresAt <= now) {
+            bucket = { tokens: 0, last: now, expiresAt: now + this.ttlFromRefill(capacity, leakPerMs) };
+            this.evictIfNeeded(this.buckets);
+            this.buckets.set(key, bucket);
+        }
+        const elapsed = now - bucket.last;
+        bucket.tokens = Math.max(0, bucket.tokens - elapsed * leakPerMs);
+        bucket.last = now;
+        bucket.expiresAt = now + this.ttlFromRefill(capacity, leakPerMs);
+        const allowed = bucket.tokens + 1 <= capacity;
+        if (allowed)
+            bucket.tokens += 1;
+        const overflow = Math.max(0, bucket.tokens - capacity + 1);
+        const resetMs = leakPerMs > 0 ? Math.ceil(overflow / leakPerMs) : 0;
+        return {
+            allowed,
+            remaining: Math.max(0, capacity - Math.ceil(bucket.tokens)),
+            resetMs,
+            limit: capacity,
+        };
+    }
+    async get(key) {
+        const now = Date.now();
+        const e = this.map.get(key);
+        if (!e || e.expiresAt <= now)
+            return null;
+        return e.value;
+    }
+    async set(key, value, ttlMs) {
+        this.set_(key, { value, expiresAt: Date.now() + ttlMs });
+    }
+    async delete(key) {
+        this.map.delete(key);
+        this.buckets.delete(key);
+        this.logs.delete(key);
+        this.counters.delete(key);
+    }
+    async incrementConcurrent(key) {
+        const next = (this.counters.get(key) ?? 0) + 1;
+        this.counters.set(key, next);
+        return next;
+    }
+    async decrementConcurrent(key) {
+        const next = Math.max(0, (this.counters.get(key) ?? 0) - 1);
+        if (next === 0)
+            this.counters.delete(key);
+        else
+            this.counters.set(key, next);
+        return next;
+    }
+    dispose() {
+        if (this.sweepTimer) {
+            clearInterval(this.sweepTimer);
+            this.sweepTimer = null;
+        }
+        this.map.clear();
+        this.buckets.clear();
+        this.logs.clear();
+        this.counters.clear();
+    }
+    set_(key, entry) {
+        this.evictIfNeeded(this.map);
+        this.map.set(key, entry);
+    }
+    evictIfNeeded(target) {
+        if (target.size < this.maxKeys)
+            return;
+        const evictCount = Math.ceil(this.maxKeys * 0.1);
+        let i = 0;
+        for (const k of target.keys()) {
+            if (i++ >= evictCount)
+                break;
+            target.delete(k);
+        }
+    }
+    ttlFromRefill(capacity, ratePerMs) {
+        if (ratePerMs <= 0)
+            return 60_000;
+        return Math.ceil(capacity / ratePerMs) * 2;
+    }
+    startSweeper() {
+        this.sweepTimer = setInterval(() => this.sweep(), 30_000);
+        if (this.sweepTimer.unref)
+            this.sweepTimer.unref();
+    }
+    sweep() {
+        const now = Date.now();
+        for (const [k, v] of this.map)
+            if (v.expiresAt <= now)
+                this.map.delete(k);
+        for (const [k, v] of this.buckets)
+            if (v.expiresAt <= now)
+                this.buckets.delete(k);
+        for (const [k, v] of this.logs)
+            if (v.expiresAt <= now)
+                this.logs.delete(k);
+    }
+}
+exports.MemoryStorage = MemoryStorage;

package/dist/storage/redis.storage.d.ts

@@ -0,0 +1,44 @@
+import type { CounterResult, ShieldStorage, TokenBucketResult, WindowResult } from './shield-storage.interface';
+type RedisLike = {
+    call: (...args: unknown[]) => Promise<unknown>;
+    eval: (...args: unknown[]) => Promise<unknown>;
+    incr: (key: string) => Promise<number>;
+    decr: (key: string) => Promise<number>;
+    incrby: (key: string, by: number) => Promise<number>;
+    pexpire: (key: string, ms: number) => Promise<number>;
+    pttl: (key: string) => Promise<number>;
+    get: (key: string) => Promise<string | null>;
+    set: (key: string, value: string, mode: string, ttl: number) => Promise<string | null>;
+    del: (key: string) => Promise<number>;
+    defineCommand?: (name: string, def: {
+        numberOfKeys: number;
+        lua: string;
+    }) => void;
+    [k: string]: unknown;
+};
+export interface RedisStorageOptions {
+    client: RedisLike;
+    keyPrefix?: string;
+}
+export declare class RedisStorage implements ShieldStorage {
+    private readonly client;
+    private readonly prefix;
+    private commandsDefined;
+    constructor(opts: RedisStorageOptions);
+    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>;
+    private k;
+    private ttlFor;
+    private tryDefineCommands;
+    private runScript;
+}
+export {};

package/dist/storage/redis.storage.js

@@ -0,0 +1,258 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisStorage = void 0;
+const TOKEN_BUCKET_LUA = `
+local key = KEYS[1]
+local capacity = tonumber(ARGV[1])
+local refillPerMs = tonumber(ARGV[2])
+local cost = tonumber(ARGV[3])
+local now = tonumber(ARGV[4])
+local ttlMs = tonumber(ARGV[5])
+
+local data = redis.call('HMGET', key, 'tokens', 'last')
+local tokens = tonumber(data[1])
+local last = tonumber(data[2])
+
+if tokens == nil then
+  tokens = capacity
+  last = now
+end
+
+local elapsed = math.max(0, now - last)
+tokens = math.min(capacity, tokens + elapsed * refillPerMs)
+
+local allowed = 0
+if tokens >= cost then
+  tokens = tokens - cost
+  allowed = 1
+end
+
+redis.call('HMSET', key, 'tokens', tokens, 'last', now)
+redis.call('PEXPIRE', key, ttlMs)
+
+local deficit = math.max(0, cost - tokens)
+local resetMs = 0
+if refillPerMs > 0 then
+  resetMs = math.ceil(deficit / refillPerMs)
+end
+
+return { allowed, math.floor(tokens), resetMs }
+`;
+const LEAKY_BUCKET_LUA = `
+local key = KEYS[1]
+local capacity = tonumber(ARGV[1])
+local leakPerMs = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+local ttlMs = tonumber(ARGV[4])
+
+local data = redis.call('HMGET', key, 'level', 'last')
+local level = tonumber(data[1])
+local last = tonumber(data[2])
+
+if level == nil then
+  level = 0
+  last = now
+end
+
+local elapsed = math.max(0, now - last)
+level = math.max(0, level - elapsed * leakPerMs)
+
+local allowed = 0
+if level + 1 <= capacity then
+  level = level + 1
+  allowed = 1
+end
+
+redis.call('HMSET', key, 'level', level, 'last', now)
+redis.call('PEXPIRE', key, ttlMs)
+
+local overflow = math.max(0, level - capacity + 1)
+local resetMs = 0
+if leakPerMs > 0 then
+  resetMs = math.ceil(overflow / leakPerMs)
+end
+
+return { allowed, math.max(0, capacity - math.ceil(level)), resetMs }
+`;
+const SLIDING_LOG_LUA = `
+local key = KEYS[1]
+local now = tonumber(ARGV[1])
+local ttlMs = tonumber(ARGV[2])
+local limit = tonumber(ARGV[3])
+local threshold = now - ttlMs
+
+redis.call('ZREMRANGEBYSCORE', key, '-inf', threshold)
+local count = redis.call('ZCARD', key)
+local allowed = 0
+if count < limit then
+  redis.call('ZADD', key, now, now .. ':' .. math.random())
+  count = count + 1
+  allowed = 1
+end
+redis.call('PEXPIRE', key, ttlMs)
+
+local oldest = redis.call('ZRANGE', key, 0, 0, 'WITHSCORES')
+local resetMs = 0
+if oldest[2] then
+  resetMs = math.max(0, tonumber(oldest[2]) + ttlMs - now)
+end
+
+return { allowed, count, resetMs }
+`;
+const SLIDING_COUNTER_LUA = `
+local cur = KEYS[1]
+local prev = KEYS[2]
+local ttlMs = tonumber(ARGV[1])
+local limit = tonumber(ARGV[2])
+local weight = tonumber(ARGV[3])
+local resetMs = tonumber(ARGV[4])
+
+local prevCount = tonumber(redis.call('GET', prev) or '0')
+local curCount = redis.call('INCR', cur)
+redis.call('PEXPIRE', cur, ttlMs * 2)
+
+local weighted = math.ceil(prevCount * weight + curCount)
+local allowed = 0
+if weighted <= limit then allowed = 1 end
+
+return { allowed, weighted, resetMs }
+`;
+class RedisStorage {
+    constructor(opts) {
+        this.commandsDefined = false;
+        if (!opts || !opts.client) {
+            throw new Error('RedisStorage requires an ioredis client');
+        }
+        this.client = opts.client;
+        this.prefix = opts.keyPrefix ?? '';
+        this.tryDefineCommands();
+    }
+    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) };
+    }
+    async consumeToken(key, capacity, refillPerMs, cost = 1) {
+        const k = this.k(key);
+        const ttlMs = this.ttlFor(capacity, refillPerMs);
+        const res = (await this.runScript('shieldTokenBucket', TOKEN_BUCKET_LUA, [k], [
+            capacity,
+            refillPerMs,
+            cost,
+            Date.now(),
+            ttlMs,
+        ]));
+        return {
+            allowed: res[0] === 1,
+            remaining: Math.max(0, Number(res[1])),
+            resetMs: Number(res[2]),
+            limit: capacity,
+        };
+    }
+    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 };
+    }
+    async slidingWindowCounter(key, ttlMs, limit) {
+        const now = Date.now();
+        const windowStart = Math.floor(now / ttlMs) * ttlMs;
+        const cur = this.k(`${key}:c:${windowStart}`);
+        const prev = this.k(`${key}:c:${windowStart - ttlMs}`);
+        const elapsedInWindow = now - windowStart;
+        const weight = 1 - elapsedInWindow / ttlMs;
+        const resetMs = Math.max(0, ttlMs - elapsedInWindow);
+        const res = (await this.runScript('shieldSlidingCounter', SLIDING_COUNTER_LUA, [cur, prev], [ttlMs, limit, weight, resetMs]));
+        return {
+            allowed: res[0] === 1,
+            count: Number(res[1]),
+            resetMs: Number(res[2]),
+            limit,
+        };
+    }
+    async slidingWindowLog(key, ttlMs, limit, now = Date.now()) {
+        const k = this.k(key);
+        const res = (await this.runScript('shieldSlidingLog', SLIDING_LOG_LUA, [k], [now, ttlMs, limit]));
+        return {
+            allowed: res[0] === 1,
+            count: Number(res[1]),
+            resetMs: Number(res[2]),
+            limit,
+        };
+    }
+    async leakyBucket(key, capacity, leakPerMs) {
+        const k = this.k(key);
+        const ttlMs = this.ttlFor(capacity, leakPerMs);
+        const res = (await this.runScript('shieldLeakyBucket', LEAKY_BUCKET_LUA, [k], [
+            capacity,
+            leakPerMs,
+            Date.now(),
+            ttlMs,
+        ]));
+        return {
+            allowed: res[0] === 1,
+            remaining: Math.max(0, Number(res[1])),
+            resetMs: Number(res[2]),
+            limit: capacity,
+        };
+    }
+    async get(key) {
+        return this.client.get(this.k(key));
+    }
+    async set(key, value, ttlMs) {
+        await this.client.set(this.k(key), value, 'PX', ttlMs);
+    }
+    async delete(key) {
+        await this.client.del(this.k(key));
+    }
+    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;
+    }
+    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);
+    }
+    k(key) {
+        return this.prefix ? `${this.prefix}:${key}` : key;
+    }
+    ttlFor(capacity, ratePerMs) {
+        if (ratePerMs <= 0)
+            return 60_000;
+        return Math.ceil(capacity / ratePerMs) * 2;
+    }
+    tryDefineCommands() {
+        if (this.commandsDefined)
+            return;
+        if (typeof this.client.defineCommand !== 'function')
+            return;
+        try {
+            this.client.defineCommand('shieldTokenBucket', { numberOfKeys: 1, lua: TOKEN_BUCKET_LUA });
+            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.commandsDefined = true;
+        }
+        catch {
+            this.commandsDefined = false;
+        }
+    }
+    async runScript(name, lua, keys, args) {
+        const fn = this.client[name];
+        if (this.commandsDefined && typeof fn === 'function') {
+            return fn.call(this.client, ...keys, ...args);
+        }
+        return this.client.eval(lua, keys.length, ...keys, ...args);
+    }
+}
+exports.RedisStorage = RedisStorage;

package/dist/storage/shield-storage.interface.d.ts

@@ -0,0 +1,30 @@
+export interface CounterResult {
+    count: number;
+    expiresAt: number;
+}
+export interface TokenBucketResult {
+    allowed: boolean;
+    remaining: number;
+    resetMs: number;
+    limit: number;
+}
+export interface WindowResult {
+    count: number;
+    allowed: boolean;
+    resetMs: number;
+    limit: number;
+}
+export interface ShieldStorage {
+    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?(): Promise<void> | void;
+}

package/dist/storage/shield-storage.interface.js

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

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

@@ -0,0 +1,5 @@
+import type { AnyResponse } from '../shield.types';
+export declare class HeadersUtil {
+    static writeRateLimit(res: AnyResponse, standard: 'draft-6' | 'draft-7', limit: number, remaining: number, resetMs: number): void;
+    static writeRetryAfter(res: AnyResponse, retryAfterMs: number): void;
+}

package/dist/utils/headers.util.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeadersUtil = void 0;
+class HeadersUtil {
+    static writeRateLimit(res, standard, limit, remaining, resetMs) {
+        const resetSec = Math.max(0, Math.ceil(resetMs / 1000));
+        if (standard === 'draft-7') {
+            res.setHeader('RateLimit-Limit', String(limit));
+            res.setHeader('RateLimit-Remaining', String(Math.max(0, remaining)));
+            res.setHeader('RateLimit-Reset', String(resetSec));
+            res.setHeader('RateLimit-Policy', `${limit};w=${resetSec || 1}`);
+        }
+        else {
+            res.setHeader('X-RateLimit-Limit', String(limit));
+            res.setHeader('X-RateLimit-Remaining', String(Math.max(0, remaining)));
+            res.setHeader('X-RateLimit-Reset', String(Math.floor(Date.now() / 1000) + resetSec));
+        }
+    }
+    static writeRetryAfter(res, retryAfterMs) {
+        res.setHeader('Retry-After', String(Math.max(1, Math.ceil(retryAfterMs / 1000))));
+    }
+}
+exports.HeadersUtil = HeadersUtil;

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

@@ -0,0 +1,6 @@
+import type { AnyRequest } from '../shield.types';
+export declare class IpUtil {
+    static resolve(req: AnyRequest, trustProxy?: boolean | number): string;
+    static normalize(addr: string): string;
+    static matches(ip: string, ips?: string[], cidrs?: string[]): boolean;
+}

package/dist/utils/ip.util.js

@@ -0,0 +1,100 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IpUtil = void 0;
+const ipaddr = __importStar(require("ipaddr.js"));
+class IpUtil {
+    static resolve(req, trustProxy = false) {
+        const xff = req.headers['x-forwarded-for'];
+        if (trustProxy && xff) {
+            const list = Array.isArray(xff) ? xff.join(',') : String(xff);
+            const parts = list.split(',').map((s) => s.trim()).filter(Boolean);
+            if (parts.length) {
+                if (typeof trustProxy === 'number') {
+                    const idx = Math.max(0, parts.length - trustProxy - 1);
+                    if (parts[idx])
+                        return IpUtil.normalize(parts[idx]);
+                }
+                return IpUtil.normalize(parts[0]);
+            }
+        }
+        if (trustProxy && Array.isArray(req.ips) && req.ips.length > 0) {
+            return IpUtil.normalize(req.ips[0]);
+        }
+        const direct = req.ip || req.socket?.remoteAddress || req.connection?.remoteAddress || '0.0.0.0';
+        return IpUtil.normalize(direct);
+    }
+    static normalize(addr) {
+        const trimmed = addr.trim();
+        if (trimmed.startsWith('::ffff:'))
+            return trimmed.slice(7);
+        return trimmed;
+    }
+    static matches(ip, ips = [], cidrs = []) {
+        if (!ip)
+            return false;
+        if (ips.includes(ip))
+            return true;
+        if (cidrs.length === 0)
+            return false;
+        let parsed;
+        try {
+            parsed = ipaddr.parse(ip);
+        }
+        catch {
+            return false;
+        }
+        for (const cidr of cidrs) {
+            try {
+                const [range, prefix] = ipaddr.parseCIDR(cidr);
+                if (parsed.kind() !== range.kind())
+                    continue;
+                if (parsed.kind() === 'ipv4') {
+                    if (parsed.match([range, prefix]))
+                        return true;
+                }
+                else {
+                    if (parsed.match([range, prefix]))
+                        return true;
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        return false;
+    }
+}
+exports.IpUtil = IpUtil;

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

@@ -0,0 +1,5 @@
+import type { AnyRequest, KeyByOption } from '../shield.types';
+export declare class KeyUtil {
+    static fromRequest(req: AnyRequest, ip: string, keyBy?: KeyByOption): string;
+    static route(req: AnyRequest): string;
+}