@chdlabs/my-shield 0.1.0

package/src/middleware/honeypot.js

@@ -0,0 +1,215 @@
+/**
+ * Static & Dynamic Route Honeypot Traps
+ * Catches vulnerability scanners probing for known sensitive paths,
+ * silently returning a 200 OK decoy after a brief delay while instantly
+ * blacklisting the IP in the Bloom filter and LRU cache.
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+
+export const DEFAULT_TRAP_ROUTES = [
+    // WordPress / PHP probes
+    '/wp-admin/', '/wp-includes/', '/wp-login.php', '/wp-content/',
+    '/xmlrpc.php', '/wp-json/',
+
+    // Environment / config file probes
+    '/.env', '/.env.local', '/.env.production',
+    '/.git/config', '/.git/HEAD',
+    '/.aws/credentials', '/.docker/config.json',
+
+    // Database dumps
+    '/backup.sql', '/db.sql', '/dump.sql', '/database.sql',
+
+    // Admin panels
+    '/phpMyAdmin/', '/phpmyadmin/', '/adminer.php',
+    '/server-status', '/server-info',
+
+    // Debug / actuator endpoints
+    '/api/v1/debug', '/api/v1/admin/config',
+    '/actuator/health', '/actuator/env',
+    '/debug/vars', '/debug/pprof/',
+
+    // Common exploit paths
+    '/cgi-bin/', '/shell', '/cmd', '/console',
+
+    // Client DOM Tripwire
+    '/api/__shield_trap'
+];
+
+export class Honeypot {
+    /**
+     * @param {Object} options
+     * @param {boolean} [options.enabled=true]
+     * @param {Array<string>} [options.additionalRoutes=[]] Custom trap paths
+     * @param {number} [options.delayMs=500] Delay before responding with silent 200 OK
+     * @param {Object} options.shield Shield core instance
+     * @param {Object} [options.logger=console]
+     */
+    constructor({
+        enabled = true,
+        additionalRoutes = [],
+        delayMs = 500,
+        shield,
+        logger = console
+    } = {}) {
+        this.enabled = enabled;
+        this.delayMs = Math.max(0, delayMs);
+        this.shield = shield;
+        this.logger = logger;
+
+        // Set of exact match trap routes
+        this.exactTraps = new Set();
+        // Array of prefix match trap routes (ending with /)
+        this.prefixTraps = new Set();
+        // Promoted/dynamically added routes tracked with metadata
+        this.routeMetadata = new Map();
+
+        // Register default trap routes
+        for (const route of DEFAULT_TRAP_ROUTES) {
+            this.addRoute(route, 'builtin');
+        }
+
+        // Register custom trap routes
+        if (Array.isArray(additionalRoutes)) {
+            for (const route of additionalRoutes) {
+                if (typeof route === 'string') {
+                    this.addRoute(route, 'custom');
+                }
+            }
+        }
+    }
+
+    /**
+     * Normalize path for matching
+     * @param {string} rawPath
+     * @returns {string}
+     */
+    normalizePath(rawPath) {
+        if (!rawPath || typeof rawPath !== 'string') return '/';
+        const cleaned = rawPath.split('?')[0].split('#')[0].trim();
+        return cleaned.replace(/\/+/g, '/') || '/';
+    }
+
+    /**
+     * Add a route to the active trap list
+     * @param {string} route
+     * @param {string} [source='dynamic']
+     */
+    addRoute(route, source = 'dynamic') {
+        const normalized = this.normalizePath(route);
+        if (normalized.endsWith('/') && normalized.length > 1) {
+            this.prefixTraps.add(normalized.toLowerCase());
+        } else {
+            this.exactTraps.add(normalized.toLowerCase());
+        }
+        this.routeMetadata.set(normalized, {
+            source,
+            addedAt: new Date().toISOString(),
+            hitCount: 0
+        });
+    }
+
+    /**
+     * Remove a trap route
+     * @param {string} route
+     * @returns {boolean}
+     */
+    removeRoute(route) {
+        const normalized = this.normalizePath(route);
+        const lower = normalized.toLowerCase();
+        const removed = this.exactTraps.delete(lower) || this.prefixTraps.delete(lower);
+        this.routeMetadata.delete(normalized);
+        return removed;
+    }
+
+    /**
+     * Check if a given request path triggers a honeypot trap
+     * @param {string} path
+     * @returns {boolean}
+     */
+    isTrap(path) {
+        if (!this.enabled || !path) return false;
+        const normalized = this.normalizePath(path).toLowerCase();
+
+        // Check exact match
+        if (this.exactTraps.has(normalized)) {
+            return true;
+        }
+
+        // Check directory/prefix match
+        for (const prefix of this.prefixTraps) {
+            if (normalized.startsWith(prefix)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Get list of routes that were auto-promoted or restored
+     * @returns {string[]}
+     */
+    getPromotedRoutes() {
+        const promoted = [];
+        for (const [route, meta] of this.routeMetadata.entries()) {
+            if (meta.source === 'auto_promoted' || meta.source === 'restored_from_file' || meta.source === 'manual_promotion') {
+                promoted.push(route);
+            }
+        }
+        return promoted;
+    }
+
+    /**
+     * Express middleware handler
+     */
+    middleware() {
+        return (req, res, next) => {
+            if (!this.enabled || !this.isTrap(req.path)) {
+                return next();
+            }
+
+            // Extract client IP
+            const ip = (req.headers['x-forwarded-for']?.split(',')[0]?.trim()) ||
+                       req.socket?.remoteAddress ||
+                       req.ip ||
+                       '127.0.0.1';
+
+            const matchedPath = this.normalizePath(req.path);
+            const meta = this.routeMetadata.get(matchedPath);
+            if (meta) {
+                meta.hitCount = (meta.hitCount || 0) + 1;
+            }
+
+            // 1. Immediately block IP in Bloom filter and LRU cache
+            if (this.shield) {
+                this.shield.blockIP(ip, 'honeypot_trap', { path: matchedPath });
+                this.shield.recordEvent({
+                    type: 'honeypot',
+                    ip,
+                    path: matchedPath,
+                    method: req.method,
+                    userAgent: req.headers['user-agent'] || '',
+                    timestamp: Date.now()
+                });
+            }
+
+            this.logger.warn?.(`[SHIELD] Honeypot triggered by ${ip} on path "${matchedPath}" -> IP Blacklisted`);
+
+            // 2. Delayed Silent 200 OK decoy response
+            const respond = () => {
+                if (res.headersSent) return;
+                res.status(200)
+                   .set('Content-Type', 'text/html')
+                   .send('<html><head><title>Loading...</title></head><body></body></html>');
+            };
+
+            if (this.delayMs > 0) {
+                setTimeout(respond, this.delayMs);
+            } else {
+                respond();
+            }
+        };
+    }
+}

package/src/middleware/keyLeakDetector.js

@@ -0,0 +1,98 @@
+/**
+ * API Key / Token Leak Detector Middleware
+ * Identifies tokens (e.g. JWT/PQC jti claims) used concurrently
+ * across multiple distinct IP addresses within a short sliding window.
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+
+export class KeyLeakDetector {
+    /**
+     * @param {Object} options
+     * @param {number} [options.windowMs=300000] Window to monitor (default 5 min)
+     * @param {number} [options.maxIpCount=2] Max concurrent IPs before flagging
+     * @param {Object} options.shield Shield core instance
+     * @param {Object} [options.logger=console]
+     */
+    constructor({
+        windowMs = 5 * 60 * 1000,
+        maxIpCount = 2,
+        shield,
+        logger = console
+    } = {}) {
+        this.windowMs = windowMs;
+        this.maxIpCount = maxIpCount;
+        this.shield = shield;
+        this.logger = logger;
+
+        // jti -> { ips: Set<string>, firstSeen: number }
+        this.jtiTracker = new Map();
+
+        this.cleanupTimer = setInterval(() => {
+            const now = Date.now();
+            for (const [jti, rec] of this.jtiTracker.entries()) {
+                if (now - rec.firstSeen > this.windowMs) {
+                    this.jtiTracker.delete(jti);
+                }
+            }
+        }, 60_000);
+
+        if (typeof this.cleanupTimer.unref === 'function') {
+            this.cleanupTimer.unref();
+        }
+    }
+
+    /**
+     * Middleware to inspect authenticated requests
+     * (Expects req.user?.jti or req.token?.jti to be populated by auth middleware)
+     */
+    middleware() {
+        return (req, res, next) => {
+            const jti = req.user?.jti || req.token?.jti || req.user?.id;
+            if (!jti) {
+                return next();
+            }
+
+            const ip = (req.headers['x-forwarded-for']?.split(',')[0]?.trim()) ||
+                       req.socket?.remoteAddress ||
+                       req.ip ||
+                       '127.0.0.1';
+
+            const now = Date.now();
+            let rec = this.jtiTracker.get(jti);
+
+            if (!rec || (now - rec.firstSeen > this.windowMs)) {
+                rec = { ips: new Set([ip]), firstSeen: now };
+                this.jtiTracker.set(jti, rec);
+            } else {
+                rec.ips.add(ip);
+
+                if (rec.ips.size > this.maxIpCount) {
+                    const ipList = Array.from(rec.ips);
+                    this.logger.warn?.(`[SHIELD] Security alert: Token ${jti} used from ${rec.ips.size} distinct IPs: ${ipList.join(', ')}`);
+
+                    if (this.shield) {
+                        this.shield.recordEvent({
+                            type: 'key_leak_detected',
+                            jti,
+                            ips: ipList,
+                            path: req.path,
+                            timestamp: now
+                        });
+                    }
+                }
+            }
+
+            next();
+        };
+    }
+
+    destroy() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+        this.jtiTracker.clear();
+    }
+}

package/src/middleware/notFoundCollector.js

@@ -0,0 +1,171 @@
+/**
+ * 404 Intelligence Collector & Anomaly Detector
+ * Captures all 404 status codes into the intelligence engine.
+ * Automatically bans IPs that probe >= 5 unique 404 paths within a 60-second window.
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+
+export class NotFoundCollector {
+    /**
+     * @param {Object} options
+     * @param {number} [options.anomalyThreshold=5] Unique 404s before IP is banned
+     * @param {number} [options.anomalyWindowMs=60000] Sliding window duration in ms
+     * @param {boolean} [options.captureAll=true]
+     * @param {Object} options.collector IntelligenceCollector instance
+     * @param {Object} options.shield Shield core instance
+     * @param {Object} [options.logger=console]
+     */
+    constructor({
+        anomalyThreshold = 5,
+        anomalyWindowMs = 60_000,
+        captureAll = true,
+        collector,
+        shield,
+        logger = console
+    } = {}) {
+        this.anomalyThreshold = Math.max(1, anomalyThreshold);
+        this.anomalyWindowMs = Math.max(1000, anomalyWindowMs);
+        this.captureAll = captureAll;
+        this.collector = collector;
+        this.shield = shield;
+        this.logger = logger;
+
+        // Sliding window tracker: ip -> { paths: Set<string>, firstSeen: number }
+        this.ipWindows = new Map();
+
+        // Periodic pruning of expired IP windows every 60 seconds
+        this.cleanupTimer = setInterval(() => {
+            this.pruneWindows();
+        }, 60_000);
+
+        if (typeof this.cleanupTimer.unref === 'function') {
+            this.cleanupTimer.unref();
+        }
+    }
+
+    /**
+     * Prune expired sliding windows to keep memory strictly bounded
+     */
+    pruneWindows() {
+        const now = Date.now();
+        for (const [ip, window] of this.ipWindows.entries()) {
+            if (now - window.firstSeen > this.anomalyWindowMs) {
+                this.ipWindows.delete(ip);
+            }
+        }
+    }
+
+    /**
+     * Handle a detected 404 event
+     * @param {Object} req Express request
+     */
+    handle404(req) {
+        const ip = (req.headers['x-forwarded-for']?.split(',')[0]?.trim()) ||
+                   req.socket?.remoteAddress ||
+                   req.ip ||
+                   '127.0.0.1';
+
+        const path = req.path || req.originalUrl || '/';
+        const userAgent = req.headers['user-agent'] || '';
+
+        // If IP is whitelisted, skip anomaly banning
+        const isWhitelisted = this.shield?.isWhitelisted(ip);
+
+        // 1. Record in 404 intelligence collector
+        if (this.captureAll && this.collector) {
+            this.collector.record404({ path, ip, userAgent });
+        }
+
+        if (isWhitelisted) {
+            return;
+        }
+
+        // 2. Sliding window anomaly evaluation
+        const now = Date.now();
+        let window = this.ipWindows.get(ip);
+
+        if (!window || (now - window.firstSeen > this.anomalyWindowMs)) {
+            window = {
+                paths: new Set([path]),
+                firstSeen: now
+            };
+            this.ipWindows.set(ip, window);
+        } else {
+            window.paths.add(path);
+
+            // Anomaly threshold reached!
+            if (window.paths.size >= this.anomalyThreshold) {
+                const uniqueCount = window.paths.size;
+                const pathList = Array.from(window.paths);
+
+                this.logger.warn?.(`[SHIELD] 404 Anomaly threshold reached for IP ${ip} (${uniqueCount} unique paths in ${Math.round((now - window.firstSeen) / 1000)}s) -> Blacklisting IP`);
+
+                if (this.shield) {
+                    this.shield.blockIP(ip, '404_anomaly', {
+                        threshold: this.anomalyThreshold,
+                        uniquePathsCount: uniqueCount,
+                        paths: pathList
+                    });
+
+                    this.shield.recordEvent({
+                        type: '404_anomaly',
+                        ip,
+                        path,
+                        uniqueCount,
+                        paths: pathList,
+                        userAgent,
+                        timestamp: now
+                    });
+                }
+
+                // Reset window for this banned IP
+                this.ipWindows.delete(ip);
+            }
+        }
+    }
+
+    /**
+     * Express middleware
+     */
+    middleware() {
+        return (req, res, next) => {
+            let handled = false;
+
+            // Hook into response finish event to detect any 404 response
+            res.on('finish', () => {
+                if (res.statusCode === 404 && !handled) {
+                    handled = true;
+                    this.handle404(req);
+                }
+            });
+
+            // If an API route reaches here without being handled by app routes, send a 404 response
+            // Non-API GET requests pass through to the SPA fallback
+            if (req.path.startsWith('/api') || req.method !== 'GET') {
+                if (!res.headersSent) {
+                    handled = true;
+                    this.handle404(req);
+                    return res.status(404).json({
+                        error: 'Not Found',
+                        path: req.path
+                    });
+                }
+            }
+
+            next();
+        };
+    }
+
+    /**
+     * Cleanup timer on shutdown
+     */
+    destroy() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+        this.ipWindows.clear();
+    }
+}

package/src/middleware/shieldGuard.js

@@ -0,0 +1,93 @@
+/**
+ * L1 Shield Guard Middleware
+ * High-performance dual-tier IP reputation gatekeeper:
+ *   1. Check Whitelist (instant pass)
+ *   2. Bloom Filter Lookup (< 0.1ms; if false -> instant pass)
+ *   3. LRU Cache Lookup (confirms whether bloom positive is a real threat)
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+
+export class ShieldGuard {
+    /**
+     * @param {Object} options
+     * @param {Object} options.bloom BloomFilter instance
+     * @param {Object} options.lru LRUCache instance
+     * @param {Object} options.shield Shield core instance
+     * @param {number} [options.blockStatusCode=403]
+     * @param {Object} [options.logger=console]
+     */
+    constructor({
+        bloom,
+        lru,
+        shield,
+        blockStatusCode = 403,
+        logger = console
+    } = {}) {
+        this.bloom = bloom;
+        this.lru = lru;
+        this.shield = shield;
+        this.blockStatusCode = blockStatusCode;
+        this.logger = logger;
+    }
+
+    /**
+     * Extract client IP safely from headers or socket
+     * @param {Object} req
+     * @returns {string}
+     */
+    getClientIP(req) {
+        const forwarded = req.headers['x-forwarded-for'];
+        if (forwarded && typeof forwarded === 'string') {
+            const first = forwarded.split(',')[0].trim();
+            if (first) return first;
+        }
+        return req.socket?.remoteAddress || req.ip || '127.0.0.1';
+    }
+
+    /**
+     * Express middleware
+     */
+    middleware() {
+        return (req, res, next) => {
+            const ip = this.getClientIP(req);
+
+            // 1. Whitelist Bypass
+            if (this.shield?.isWhitelisted(ip)) {
+                return next();
+            }
+
+            // 2. L1 Bloom Filter Check (< 0.1ms)
+            // If false -> IP is definitely clean, pass immediately!
+            if (!this.bloom.has(ip)) {
+                return next();
+            }
+
+            // 3. Bloom returned true: Check LRU cache to verify it's not a statistical false positive
+            const threat = this.lru.get(ip);
+            if (!threat) {
+                // False positive in Bloom filter (or threat expired from LRU) -> Pass request!
+                return next();
+            }
+
+            // Confirmed threat!
+            this.shield?.recordBlock();
+            this.shield?.recordEvent({
+                type: 'blocked_request',
+                ip,
+                path: req.path,
+                method: req.method,
+                reason: threat.reason || 'blacklist',
+                timestamp: Date.now()
+            });
+
+            this.logger.warn?.(`[SHIELD] Blocked request from ${ip} to ${req.method} ${req.path} (${threat.reason || 'blacklist'})`);
+
+            res.status(this.blockStatusCode).json({
+                error: 'Access denied by security shield',
+                code: 'SHIELD_BLOCKED'
+            });
+        };
+    }
+}