@chdlabs/my-shield 0.1.0

package/src/core/lruCache.js

@@ -0,0 +1,178 @@
+/**
+ * Bounded In-Memory LRU Cache with TTL Expiration
+ * Backed by native JavaScript Map preserving insertion order.
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+
+export class LRUCache {
+    /**
+     * @param {Object} options
+     * @param {number} [options.maxSize=10000] Maximum entries before evicting least-recently used
+     * @param {number} [options.ttlMs=300000] Default Time-To-Live in milliseconds (5 minutes)
+     */
+    constructor({ maxSize = 10_000, ttlMs = 5 * 60 * 1000 } = {}) {
+        this.maxSize = Math.max(1, maxSize);
+        this.ttlMs = ttlMs;
+        this.cache = new Map();
+        this.hits = 0;
+        this.misses = 0;
+        this.evictions = 0;
+    }
+
+    /**
+     * Set or update a key in the cache
+     * @param {string} key
+     * @param {*} value
+     * @param {number} [customTtlMs]
+     */
+    set(key, value, customTtlMs = null) {
+        const effectiveTtl = customTtlMs !== null && customTtlMs !== undefined ? customTtlMs : this.ttlMs;
+        const now = Date.now();
+        const expiresAt = effectiveTtl > 0 ? now + effectiveTtl : 0;
+
+        // If exists, delete first to move to the end (most recent)
+        if (this.cache.has(key)) {
+            this.cache.delete(key);
+        } else if (this.cache.size >= this.maxSize) {
+            // Evict oldest (first key in Map iterator)
+            const oldestKey = this.cache.keys().next().value;
+            if (oldestKey !== undefined) {
+                this.cache.delete(oldestKey);
+                this.evictions++;
+            }
+        }
+
+        this.cache.set(key, {
+            value,
+            expiresAt,
+            createdAt: now,
+            updatedAt: now
+        });
+    }
+
+    /**
+     * Retrieve a key from the cache, refreshing its recency
+     * @param {string} key
+     * @returns {*} Value or undefined if absent or expired
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this.misses++;
+            return undefined;
+        }
+
+        // Check expiration
+        if (entry.expiresAt > 0 && Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            this.misses++;
+            return undefined;
+        }
+
+        // Refresh position in Map (delete and re-insert)
+        this.cache.delete(key);
+        entry.updatedAt = Date.now();
+        this.cache.set(key, entry);
+        this.hits++;
+        return entry.value;
+    }
+
+    /**
+     * Check if a key exists and is unexpired without modifying LRU order
+     * @param {string} key
+     * @returns {boolean}
+     */
+    has(key) {
+        const entry = this.cache.get(key);
+        if (!entry) return false;
+        if (entry.expiresAt > 0 && Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return false;
+        }
+        return true;
+    }
+
+    /**
+     * Delete a key from the cache
+     * @param {string} key
+     * @returns {boolean}
+     */
+    delete(key) {
+        return this.cache.delete(key);
+    }
+
+    /**
+     * Clear all entries
+     */
+    clear() {
+        this.cache.clear();
+        this.hits = 0;
+        this.misses = 0;
+        this.evictions = 0;
+    }
+
+    /**
+     * Prune expired entries
+     * @returns {number} Count of removed entries
+     */
+    prune() {
+        const now = Date.now();
+        let pruned = 0;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.expiresAt > 0 && now > entry.expiresAt) {
+                this.cache.delete(key);
+                pruned++;
+            }
+        }
+        return pruned;
+    }
+
+    /**
+     * Current count of active entries
+     */
+    get size() {
+        return this.cache.size;
+    }
+
+    /**
+     * Get snapshot array of active unexpired entries
+     * @returns {Array<{ key: string, value: any, expiresAt: number, remainingTtlMs: number }>}
+     */
+    entries() {
+        const now = Date.now();
+        const result = [];
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.expiresAt > 0 && now > entry.expiresAt) {
+                this.cache.delete(key);
+                continue;
+            }
+            result.push({
+                key,
+                value: entry.value,
+                createdAt: entry.createdAt,
+                expiresAt: entry.expiresAt,
+                remainingTtlMs: entry.expiresAt > 0 ? Math.max(0, entry.expiresAt - now) : Infinity
+            });
+        }
+        return result;
+    }
+
+    /**
+     * Diagnostic statistics
+     */
+    getStats() {
+        const totalOps = this.hits + this.misses;
+        const hitRate = totalOps > 0 ? Number((this.hits / totalOps).toFixed(4)) : 0;
+        return {
+            size: this.cache.size,
+            maxSize: this.maxSize,
+            ttlMs: this.ttlMs,
+            hits: this.hits,
+            misses: this.misses,
+            hitRate,
+            evictions: this.evictions
+        };
+    }
+}

package/src/core/ringBuffer.js

@@ -0,0 +1,87 @@
+/**
+ * Fixed-Size In-Memory Ring Buffer for Security Events
+ * Overwrites oldest events once capacity is reached.
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+
+export class RingBuffer {
+    /**
+     * @param {number} [capacity=10000] Maximum events to retain in memory
+     */
+    constructor(capacity = 10_000) {
+        this.capacity = Math.max(10, capacity);
+        this.buffer = new Array(this.capacity);
+        this.head = 0; // points to next write slot
+        this.count = 0; // total valid items currently stored
+        this.totalPushed = 0;
+    }
+
+    /**
+     * Push a new event into the circular buffer
+     * @param {*} item
+     */
+    push(item) {
+        this.buffer[this.head] = item;
+        this.head = (this.head + 1) % this.capacity;
+        if (this.count < this.capacity) {
+            this.count++;
+        }
+        this.totalPushed++;
+    }
+
+    /**
+     * Return all stored items in chronological order (oldest to newest)
+     * @returns {Array<*>}
+     */
+    toArray() {
+        const result = new Array(this.count);
+        // If buffer has not wrapped around
+        if (this.count < this.capacity) {
+            for (let i = 0; i < this.count; i++) {
+                result[i] = this.buffer[i];
+            }
+        } else {
+            // Buffer has wrapped around: head points to the oldest item
+            let index = 0;
+            for (let i = this.head; i < this.capacity; i++) {
+                result[index++] = this.buffer[i];
+            }
+            for (let i = 0; i < this.head; i++) {
+                result[index++] = this.buffer[i];
+            }
+        }
+        return result;
+    }
+
+    /**
+     * Return the most recent n items (newest first)
+     * @param {number} [n=50]
+     * @returns {Array<*>}
+     */
+    getRecent(n = 50) {
+        const limit = Math.min(n, this.count);
+        const result = new Array(limit);
+        for (let i = 0; i < limit; i++) {
+            // Newest item is at (head - 1 - i + capacity) % capacity
+            const index = (this.head - 1 - i + this.capacity) % this.capacity;
+            result[i] = this.buffer[index];
+        }
+        return result;
+    }
+
+    /**
+     * Reset the buffer
+     */
+    clear() {
+        this.buffer = new Array(this.capacity);
+        this.head = 0;
+        this.count = 0;
+        this.totalPushed = 0;
+    }
+
+    get size() {
+        return this.count;
+    }
+}

package/src/index.d.ts

@@ -0,0 +1,97 @@
+import { EventEmitter } from 'events';
+import { RequestHandler, Router } from 'express';
+
+export interface BloomOptions {
+    expectedItems?: number;
+    falsePositiveRate?: number;
+    sizeBytes?: number | null;
+}
+
+export interface LRUOptions {
+    maxSize?: number;
+    ttlMs?: number;
+}
+
+export interface HoneypotOptions {
+    enabled?: boolean;
+    additionalRoutes?: string[];
+    delayMs?: number;
+}
+
+export interface FilePersistenceOptions {
+    enabled?: boolean;
+    directory?: string;
+    filename?: string;
+    intervalMs?: number;
+    loadOnStartup?: boolean;
+}
+
+export interface AutoPromoteOptions {
+    enabled?: boolean;
+    minHits?: number;
+    minUniqueIPs?: number;
+}
+
+export interface IntelligenceOptions {
+    anomalyThreshold?: number;
+    anomalyWindowMs?: number;
+    captureAll?: boolean;
+    ringBufferSize?: number;
+    maxUniquePaths?: number;
+    excludePatterns?: RegExp[];
+    filePersistence?: FilePersistenceOptions;
+    autoPromote?: AutoPromoteOptions;
+}
+
+export interface ShieldOptions {
+    whitelist?: string[];
+    bloom?: BloomOptions;
+    lru?: LRUOptions;
+    honeypot?: HoneypotOptions;
+    intelligence?: IntelligenceOptions;
+    blockStatusCode?: number;
+    logger?: {
+        info?: (...args: any[]) => void;
+        warn?: (...args: any[]) => void;
+        error?: (...args: any[]) => void;
+    };
+}
+
+export interface CostThrottleOptions {
+    weight?: number;
+    maxCost?: number;
+    windowMs?: number;
+}
+
+export interface AdminRouterOptions {
+    authMiddleware?: RequestHandler | RequestHandler[];
+}
+
+export class Shield extends EventEmitter {
+    constructor(options?: ShieldOptions);
+
+    middleware(): RequestHandler;
+    honeypot(): RequestHandler;
+    notFoundCollector(): RequestHandler;
+    adminRouter(options?: AdminRouterOptions): Router;
+    costThrottle(options?: CostThrottleOptions): RequestHandler;
+    keyLeakDetector(): RequestHandler;
+
+    blockIP(ip: string, reason?: string, metadata?: Record<string, any>, customTtlMs?: number | null): void;
+    unblockIP(ip: string): void;
+    allowIP(ip: string): void;
+    removeAllowedIP(ip: string): void;
+    isWhitelisted(ip: string): boolean;
+
+    recordEvent(event: Record<string, any>): void;
+    recordBlock(): void;
+
+    getStats(): Record<string, any>;
+    getIntelligence(): Record<string, any>;
+    getBloomHealth(): Record<string, any>;
+
+    shutdown(): Promise<void>;
+}
+
+export function createShield(options?: ShieldOptions): Shield;
+export default createShield;

package/src/index.js

@@ -0,0 +1,317 @@
+/**
+ * @chdlabs/my-shield
+ * Zero-latency security shield middleware with Bloom filter, honeypots, and 404 intelligence.
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+import { EventEmitter } from 'events';
+import { BloomFilter } from './core/bloomFilter.js';
+import { LRUCache } from './core/lruCache.js';
+import { RingBuffer } from './core/ringBuffer.js';
+import { IntelligenceCollector } from './intelligence/collector.js';
+import { AutoPromoter } from './intelligence/autoPromoter.js';
+import { FilePersistence } from './intelligence/filePersistence.js';
+import { Honeypot } from './middleware/honeypot.js';
+import { NotFoundCollector } from './middleware/notFoundCollector.js';
+import { ShieldGuard } from './middleware/shieldGuard.js';
+import { CostThrottle } from './middleware/costThrottle.js';
+import { KeyLeakDetector } from './middleware/keyLeakDetector.js';
+import { createAdminRouter } from './admin/adminRouter.js';
+
+export class Shield extends EventEmitter {
+    /**
+     * @param {Object} [options={}]
+     */
+    constructor(options = {}) {
+        super();
+        this.options = options;
+        this.logger = options.logger || console;
+        this.startTime = Date.now();
+
+        // 1. Whitelist (Set of IPs that are never blocked)
+        this.whitelist = new Set(
+            (options.whitelist || []).map(ip => String(ip).trim())
+        );
+
+        // 2. Core Probabilistic Data Structures
+        const bloomOpts = options.bloom || {};
+        this.bloom = new BloomFilter({
+            expectedItems: bloomOpts.expectedItems || 100_000,
+            falsePositiveRate: bloomOpts.falsePositiveRate || 0.01,
+            sizeBytes: bloomOpts.sizeBytes || null
+        });
+
+        const lruOpts = options.lru || {};
+        this.lru = new LRUCache({
+            maxSize: lruOpts.maxSize || 10_000,
+            ttlMs: lruOpts.ttlMs || 5 * 60 * 1000 // 5 minutes default
+        });
+
+        const intelOpts = options.intelligence || {};
+        const ringCapacity = intelOpts.ringBufferSize || 10_000;
+        this.ringBuffer = new RingBuffer(ringCapacity);
+
+        // 3. 404 Intelligence Collector
+        this.collector = new IntelligenceCollector({
+            maxUniquePaths: intelOpts.maxUniquePaths || 50_000,
+            excludePatterns: intelOpts.excludePatterns || []
+        });
+
+        // 4. Honeypot Subsystem
+        const honeypotOpts = options.honeypot || {};
+        this.honeypotInstance = new Honeypot({
+            enabled: honeypotOpts.enabled !== false,
+            additionalRoutes: honeypotOpts.additionalRoutes || [],
+            delayMs: honeypotOpts.delayMs ?? 500,
+            shield: this,
+            logger: this.logger
+        });
+
+        // 5. Auto-Promoter Subsystem
+        const autoPromoteOpts = intelOpts.autoPromote || {};
+        this.autoPromoter = new AutoPromoter({
+            enabled: autoPromoteOpts.enabled !== false,
+            minHits: autoPromoteOpts.minHits || 50,
+            minUniqueIPs: autoPromoteOpts.minUniqueIPs || 10,
+            collector: this.collector,
+            honeypot: this.honeypotInstance,
+            logger: this.logger
+        });
+
+        // 6. Single-File Persistence Subsystem
+        const fileOpts = intelOpts.filePersistence || {};
+        this.filePersistence = new FilePersistence({
+            enabled: fileOpts.enabled !== false,
+            directory: fileOpts.directory || './data/shield',
+            filename: fileOpts.filename || '404_intelligence.json',
+            intervalMs: fileOpts.intervalMs || 60 * 60 * 1000, // 1 hour default
+            loadOnStartup: fileOpts.loadOnStartup !== false,
+            collector: this.collector,
+            honeypot: this.honeypotInstance,
+            autoPromoter: this.autoPromoter,
+            logger: this.logger
+        });
+
+        // Start file persistence timer & initial startup load
+        if (fileOpts.enabled !== false) {
+            this.filePersistence.start();
+        }
+
+        // 7. Middlewares
+        this.guard = new ShieldGuard({
+            bloom: this.bloom,
+            lru: this.lru,
+            shield: this,
+            blockStatusCode: options.blockStatusCode || 403,
+            logger: this.logger
+        });
+
+        this.notFoundHandler = new NotFoundCollector({
+            anomalyThreshold: intelOpts.anomalyThreshold || 5,
+            anomalyWindowMs: intelOpts.anomalyWindowMs || 60_000,
+            captureAll: intelOpts.captureAll !== false,
+            collector: this.collector,
+            shield: this,
+            logger: this.logger
+        });
+
+        this.costThrottleInstance = new CostThrottle();
+        this.keyLeakDetectorInstance = new KeyLeakDetector({
+            shield: this,
+            logger: this.logger
+        });
+    }
+
+    /**
+     * L1 Guard Express Middleware (Mount first!)
+     */
+    middleware() {
+        return this.guard.middleware();
+    }
+
+    /**
+     * Honeypot Express Middleware (Mount before SPA fallback)
+     */
+    honeypot() {
+        return this.honeypotInstance.middleware();
+    }
+
+    /**
+     * 404 Collector & Anomaly Detector Middleware (Mount after app routes)
+     */
+    notFoundCollector() {
+        return this.notFoundHandler.middleware();
+    }
+
+    /**
+     * Admin Dashboard Router
+     * @param {Object} [options]
+     */
+    adminRouter(options = {}) {
+        return createAdminRouter(this, options);
+    }
+
+    /**
+     * Route-level Denial-of-Wallet Cost Throttle Decorator
+     * @param {Object} [opts]
+     */
+    costThrottle(opts) {
+        return this.costThrottleInstance.create(opts);
+    }
+
+    /**
+     * Route-level API Key / Token Leak Detector Middleware
+     */
+    keyLeakDetector() {
+        return this.keyLeakDetectorInstance.middleware();
+    }
+
+    /**
+     * Block an IP address immediately
+     * @param {string} ip
+     * @param {string} [reason='manual_block']
+     * @param {Object} [metadata={}]
+     * @param {number} [customTtlMs]
+     */
+    blockIP(ip, reason = 'manual_block', metadata = {}, customTtlMs = null) {
+        if (!ip || typeof ip !== 'string') return;
+        const cleanIp = ip.trim();
+
+        // Whitelisted IPs can never be blocked
+        if (this.whitelist.has(cleanIp)) return;
+
+        // 1. Add to Bloom filter (for sub-0.1ms pass-through check)
+        this.bloom.add(cleanIp);
+
+        // 2. Add to LRU confirmed threat cache (with TTL)
+        this.lru.set(cleanIp, { reason, metadata }, customTtlMs);
+    }
+
+    /**
+     * Unblock an IP address
+     * (Removes from LRU cache; Bloom will say maybe, but LRU confirms clean)
+     * @param {string} ip
+     */
+    unblockIP(ip) {
+        if (!ip || typeof ip !== 'string') return;
+        const cleanIp = ip.trim();
+        this.lru.delete(cleanIp);
+    }
+
+    /**
+     * Allow an IP address (whitelist)
+     * @param {string} ip
+     */
+    allowIP(ip) {
+        if (!ip || typeof ip !== 'string') return;
+        const cleanIp = ip.trim();
+        this.whitelist.add(cleanIp);
+        this.lru.delete(cleanIp);
+    }
+
+    /**
+     * Remove an IP from whitelist
+     * @param {string} ip
+     */
+    removeAllowedIP(ip) {
+        if (!ip || typeof ip !== 'string') return;
+        this.whitelist.delete(ip.trim());
+    }
+
+    /**
+     * Check if an IP is whitelisted
+     * @param {string} ip
+     * @returns {boolean}
+     */
+    isWhitelisted(ip) {
+        if (!ip || typeof ip !== 'string') return false;
+        return this.whitelist.has(ip.trim());
+    }
+
+    /**
+     * Record a security event in the ring buffer & emit to real-time subscribers
+     * @param {Object} event
+     */
+    recordEvent(event) {
+        const enriched = {
+            ...event,
+            timestamp: event.timestamp || Date.now()
+        };
+        this.ringBuffer.push(enriched);
+        this.emit('event', enriched);
+    }
+
+    /**
+     * Increment blocked threat counter in intelligence
+     */
+    recordBlock() {
+        this.collector.recordBlock();
+    }
+
+    /**
+     * Aggregate system diagnostics and statistics
+     */
+    getStats() {
+        const trapsList = [];
+        for (const [p, meta] of this.honeypotInstance.routeMetadata.entries()) {
+            trapsList.push({
+                path: p,
+                source: meta.source,
+                hitCount: meta.hitCount || 0
+            });
+        }
+
+        return {
+            uptime: (Date.now() - this.startTime) / 1000,
+            blockedIPs: this.lru.size,
+            eventsTotal: this.ringBuffer.size,
+            bloom: this.bloom.getStats(),
+            lru: this.lru.getStats(),
+            intelligence: this.collector.getStats(),
+            honeypot: {
+                activeTraps: trapsList.length,
+                promotedTraps: this.honeypotInstance.getPromotedRoutes().length,
+                traps: trapsList
+            },
+            persistence: this.filePersistence.getStatus()
+        };
+    }
+
+    /**
+     * Current 404 intelligence snapshot
+     */
+    getIntelligence() {
+        return this.collector.getSnapshot(this.honeypotInstance.getPromotedRoutes());
+    }
+
+    /**
+     * Bloom filter diagnostic metrics
+     */
+    getBloomHealth() {
+        return this.bloom.getStats();
+    }
+
+    /**
+     * Graceful shutdown: flush in-memory state to 404_intelligence.json
+     */
+    async shutdown() {
+        this.logger.info?.('[SHIELD] Graceful shutdown initiated. Flushing intelligence to disk...');
+        await this.filePersistence.stop();
+        this.notFoundHandler.destroy();
+        this.costThrottleInstance.destroy();
+        this.keyLeakDetectorInstance.destroy();
+        this.logger.info?.('[SHIELD] Shutdown complete.');
+    }
+}
+
+/**
+ * Factory helper to instantiate Shield
+ * @param {Object} [options]
+ * @returns {Shield}
+ */
+export function createShield(options = {}) {
+    return new Shield(options);
+}
+
+export default createShield;