@chdlabs/my-shield 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ChdLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+# 🛡️ @chdlabs/my-shield
+
+> High-performance, zero-latency security shield middleware for Express. Built with pure JavaScript probabilistic data structures (Bloom filter + LRU cache), honeypot traps, and a self-improving 404 intelligence engine.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node: >=20](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-success.svg)](https://www.npmjs.com/package/@chdlabs/my-shield)
+
+---
+
+## Highlights
+
+- ⚡ **Sub-0.1ms Clean Pass**: Legitimate requests pass through the L1 Bloom filter in `< 0.1ms`.
+- 🎯 **Zero False-Positive Blocks**: Two-tiered L1 caching (Bloom filter + LRU confirmed threat cache) guarantees statistical Bloom false positives are never blocked.
+- 🍯 **Silent Honeypot Decoys**: Static trap routes (`/.env`, `/wp-login.php`, `/.git/config`, etc.) return a silent `200 OK` decoy response after a brief delay and instantly blacklist scanners.
+- 🔍 **404 Anomaly & Intelligence**: Captures every 404 URL probe, bans scanners probing $\ge 5$ unique paths in 60s, and auto-promotes frequent attack targets to active honeypots.
+- 💾 **Single-File Deduplicated Persistence**: Preserves learned probe patterns and promoted honeypots across process restarts in an atomic JSON file (`404_intelligence.json`).
+- 📊 **Self-Contained Security Dashboard**: Built-in dark-themed telemetry console with real-time Server-Sent Events (SSE), charts, and active block management.
+- 🪶 **Zero Production Dependencies**: Pure JavaScript built exclusively with Node.js built-ins (`crypto`, `fs`, `path`, `events`).
+
+---
+
+## Architecture
+
+```
+Incoming Request
+       │
+       ▼
+┌───────────────────────────────────────┐
+│ L1 Shield Guard                       │
+│                                       │
+│ 1. IP Whitelist?   ──▶ Pass           │
+│ 2. Bloom Filter?   ──▶ False = Pass   │
+│ 3. LRU Cache?      ──▶ Found = Block  │
+└──────────────────┬────────────────────┘
+                   ▼
+┌───────────────────────────────────────┐
+│ Honeypot Trap Router                  │
+│ Hits sensitive path? ──▶ Silent 200   │
+│                          Blacklist IP │
+└──────────────────┬────────────────────┘
+                   ▼
+┌───────────────────────────────────────┐
+│ Application Routes (Your API)         │
+└──────────────────┬────────────────────┘
+                   ▼
+┌───────────────────────────────────────┐
+│ 404 Intelligence Collector            │
+│ ≥ 5 unique 404s/60s? ──▶ Ban IP       │
+│ Dedup snapshot saved to disk          │
+└───────────────────────────────────────┘
+```
+
+---
+
+## Installation
+
+```bash
+npm install @chdlabs/my-shield
+```
+
+---
+
+## Quick Start (Express)
+
+```javascript
+import express from 'express';
+import { createShield } from '@chdlabs/my-shield';
+
+const app = express();
+
+const shield = createShield({
+  bloom: {
+    expectedItems: 100_000,
+    falsePositiveRate: 0.01
+  },
+  lru: {
+    maxSize: 10_000,
+    ttlMs: 5 * 60 * 1000 // 5 minutes
+  },
+  honeypot: {
+    enabled: true,
+    delayMs: 500
+  },
+  intelligence: {
+    anomalyThreshold: 5,     // 5 unique 404s in 60s -> BAN
+    anomalyWindowMs: 60_000,
+    captureAll: true,
+    filePersistence: {
+      enabled: true,
+      directory: './data/shield',
+      filename: '404_intelligence.json',
+      intervalMs: 60 * 60 * 1000, // 1 hour save interval
+      loadOnStartup: true
+    },
+    autoPromote: {
+      enabled: true,
+      minHits: 50,
+      minUniqueIPs: 10
+    }
+  }
+});
+
+// 1. Mount main defense guard (FIRST middleware after parsing)
+app.use(shield.middleware());
+
+// 2. Mount honeypot trap router (BEFORE application routes)
+app.use(shield.honeypot());
+
+// 3. Application routes
+app.get('/api/data', (req, res) => res.json({ status: 'ok' }));
+
+// 4. Mount 404 intelligence collector (AFTER application routes)
+app.use(shield.notFoundCollector());
+
+// 5. Mount admin dashboard (protect with your auth middleware)
+app.use('/admin/shield', authenticateAdmin, shield.adminRouter());
+
+// Graceful shutdown: flushes 404 intelligence to disk
+process.on('SIGTERM', async () => {
+  await shield.shutdown();
+  process.exit(0);
+});
+```
+
+---
+
+## Configuration Reference
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `whitelist` | `string[]` | `[]` | List of IP addresses that are never blocked |
+| `bloom.expectedItems` | `number` | `100000` | Estimated distinct IPs to hold in filter |
+| `bloom.falsePositiveRate` | `number` | `0.01` | Target false positive probability (1%) |
+| `bloom.sizeBytes` | `number` | `null` | Explicit bit array size in bytes |
+| `lru.maxSize` | `number` | `10000` | Max entries in confirmed threat cache |
+| `lru.ttlMs` | `number` | `300000` | Threat cache TTL in ms (5 minutes) |
+| `honeypot.enabled` | `boolean` | `true` | Enable/disable honeypot traps |
+| `honeypot.delayMs` | `number` | `500` | Delay before sending silent 200 OK decoy |
+| `honeypot.additionalRoutes` | `string[]` | `[]` | Custom trap path patterns |
+| `intelligence.anomalyThreshold` | `number` | `5` | Unique 404s before IP is banned |
+| `intelligence.anomalyWindowMs` | `number` | `60000` | Sliding window in ms (60 seconds) |
+| `intelligence.filePersistence.enabled` | `boolean` | `true` | Enable periodic JSON snapshot saves |
+| `intelligence.filePersistence.directory` | `string` | `'./data/shield'` | Destination directory for JSON snapshot |
+| `intelligence.filePersistence.filename` | `string` | `'404_intelligence.json'` | Single deduplicated filename |
+| `intelligence.filePersistence.intervalMs`| `number` | `3600000` | Snapshot save interval (1 hour) |
+| `intelligence.filePersistence.loadOnStartup` | `boolean` | `true` | Restore intelligence on process start |
+| `intelligence.autoPromote.enabled` | `boolean` | `true` | Auto-promote frequent 404s to traps |
+| `intelligence.autoPromote.minHits` | `number` | `50` | Min 404 hits before promotion |
+| `intelligence.autoPromote.minUniqueIPs` | `number` | `10` | Min distinct IPs probing path |
+
+---
+
+## Programmatic API
+
+```javascript
+// Manual IP Governance
+shield.blockIP('198.51.100.42', 'manual_ban', { admin: 'dev1' });
+shield.unblockIP('198.51.100.42');
+shield.allowIP('192.168.1.50');       // Add to whitelist
+shield.removeAllowedIP('192.168.1.50');
+shield.isWhitelisted('192.168.1.50'); // Returns boolean
+
+// Telemetry & Metrics
+shield.getStats();          // Returns aggregate stats, LRU sizes, traps list
+shield.getIntelligence();   // Full 404 intelligence snapshot
+shield.getBloomHealth();    // Saturation percentage and estimated FPR
+
+// Route-Level Denial-of-Wallet Cost Throttling
+app.post('/api/ai-generate', shield.costThrottle({ weight: 10, maxCost: 100 }), handler);
+
+// Route-Level Token / Credential Leak Detection
+app.use(shield.keyLeakDetector());
+```
+
+---
+
+## Publishing to npmjs
+
+To publish `@chdlabs/my-shield` to npm:
+
+1. Log in to your npm account (if not already logged in):
+   ```bash
+   npm login
+   ```
+2. Navigate to the `sdk` directory and publish:
+   ```bash
+   cd sdk
+   npm publish
+   ```
+   *(Note: Since `@chdlabs` is a scoped package, `"publishConfig": { "access": "public" }` is pre-configured in `package.json`).*
+
+---
+
+## License
+
+MIT © CHDLabs

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@chdlabs/my-shield",
+  "version": "0.1.0",
+  "description": "Zero-latency security shield middleware with Bloom filter, honeypots, and 404 intelligence",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./client": "./src/client/shield-client.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "express": ">=4.18.0 || >=5.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "security",
+    "honeypot",
+    "bloom-filter",
+    "waf",
+    "express-middleware",
+    "bot-detection",
+    "404-intelligence"
+  ],
+  "author": "CHDLabs",
+  "license": "MIT",
+  "scripts": {
+    "test": "node test/integration.test.js"
+  }
+}

package/src/admin/adminRouter.js

@@ -0,0 +1,221 @@
+/**
+ * Shield Administration Express Router & Management API
+ * Provides programmatic governance, analytics endpoints, and serves
+ * the self-contained monitoring dashboard.
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+import express from 'express';
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export function createAdminRouter(shield, options = {}) {
+    const router = express.Router();
+    const dashboardDir = path.resolve(__dirname, 'dashboard');
+    const authMiddleware = Array.isArray(options.authMiddleware) ? options.authMiddleware : (options.authMiddleware ? [options.authMiddleware] : []);
+
+    // ── Static Asset Handlers ──
+    router.get('/', (req, res) => {
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.sendFile(path.join(dashboardDir, 'index.html'));
+    });
+
+    router.get('/dashboard.css', (req, res) => {
+        res.setHeader('Content-Type', 'text/css; charset=utf-8');
+        res.sendFile(path.join(dashboardDir, 'dashboard.css'));
+    });
+
+    router.get('/dashboard.js', (req, res) => {
+        res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
+        res.sendFile(path.join(dashboardDir, 'dashboard.js'));
+    });
+
+    // ── Protect API endpoints if authMiddleware provided ──
+    if (authMiddleware.length > 0) {
+        router.use('/api', ...authMiddleware);
+    }
+
+    // ── API Endpoints ──
+
+    // 1. Overall System Stats
+    router.get('/api/stats', (req, res) => {
+        res.json(shield.getStats());
+    });
+
+    // 2. Paginated / Recent Security Events
+    router.get('/api/events', (req, res) => {
+        const limit = Math.min(500, Math.max(1, parseInt(req.query.limit || '50', 10)));
+        const type = req.query.type;
+        let events = shield.ringBuffer.getRecent(limit * 2);
+
+        if (type) {
+            events = events.filter(e => e && e.type === type);
+        }
+
+        res.json({
+            totalRecorded: shield.ringBuffer.size,
+            returned: Math.min(events.length, limit),
+            events: events.slice(0, limit)
+        });
+    });
+
+    // 3. 404 Intelligence Snapshot
+    router.get('/api/intelligence', (req, res) => {
+        res.json(shield.getIntelligence());
+    });
+
+    // 4. Download 404_intelligence.json directly
+    router.get('/api/intelligence/file', (req, res) => {
+        const filePath = shield.filePersistence?.filePath;
+        if (!filePath || !fs.existsSync(filePath)) {
+            return res.status(404).json({ error: 'Intelligence file not yet generated or found' });
+        }
+        res.download(filePath, '404_intelligence.json');
+    });
+
+    // 5. Bloom Filter Diagnostics
+    router.get('/api/bloom', (req, res) => {
+        res.json(shield.getBloomHealth());
+    });
+
+    // 6. Currently Blocked IPs (from LRU)
+    router.get('/api/blocked', (req, res) => {
+        const entries = shield.lru.entries().map(e => ({
+            ip: e.key,
+            reason: e.value?.reason || 'unspecified',
+            metadata: e.value?.metadata || {},
+            createdAt: e.createdAt,
+            expiresAt: e.expiresAt,
+            remainingTtlMs: e.remainingTtlMs
+        }));
+        res.json({ count: entries.length, blockedIPs: entries });
+    });
+
+    // 7. Whitelisted IPs
+    router.get('/api/whitelist', (req, res) => {
+        res.json({
+            count: shield.whitelist.size,
+            whitelistedIPs: Array.from(shield.whitelist)
+        });
+    });
+
+    // 8. Manual IP Block
+    router.post('/api/block', express.json(), (req, res) => {
+        const { ip, reason = 'manual_admin_block', ttlMs } = req.body || {};
+        if (!ip || typeof ip !== 'string') {
+            return res.status(400).json({ error: 'Valid "ip" string is required' });
+        }
+        shield.blockIP(ip.trim(), reason, { adminAction: true }, ttlMs);
+        shield.recordEvent({
+            type: 'admin_action',
+            action: 'block_ip',
+            ip: ip.trim(),
+            reason,
+            timestamp: Date.now()
+        });
+        res.json({ success: true, message: `IP ${ip.trim()} successfully blocked` });
+    });
+
+    // 9. Manual IP Whitelist (Allow)
+    router.post('/api/allow', express.json(), (req, res) => {
+        const { ip } = req.body || {};
+        if (!ip || typeof ip !== 'string') {
+            return res.status(400).json({ error: 'Valid "ip" string is required' });
+        }
+        shield.allowIP(ip.trim());
+        shield.recordEvent({
+            type: 'admin_action',
+            action: 'allow_ip',
+            ip: ip.trim(),
+            timestamp: Date.now()
+        });
+        res.json({ success: true, message: `IP ${ip.trim()} added to whitelist` });
+    });
+
+    // 10. Manual IP Unblock
+    router.delete('/api/block/:ip', (req, res) => {
+        const ip = req.params.ip;
+        shield.unblockIP(ip);
+        shield.recordEvent({
+            type: 'admin_action',
+            action: 'unblock_ip',
+            ip,
+            timestamp: Date.now()
+        });
+        res.json({ success: true, message: `IP ${ip} removed from blocked cache` });
+    });
+
+    // 11. Remove from Whitelist
+    router.delete('/api/allow/:ip', (req, res) => {
+        const ip = req.params.ip;
+        shield.removeAllowedIP(ip);
+        shield.recordEvent({
+            type: 'admin_action',
+            action: 'remove_allowed_ip',
+            ip,
+            timestamp: Date.now()
+        });
+        res.json({ success: true, message: `IP ${ip} removed from whitelist` });
+    });
+
+    // 12. Add Honeypot Route
+    router.post('/api/honeypot/add', express.json(), (req, res) => {
+        const { path: routePath } = req.body || {};
+        if (!routePath || typeof routePath !== 'string') {
+            return res.status(400).json({ error: 'Valid "path" string is required' });
+        }
+        shield.honeypotInstance.addRoute(routePath.trim(), 'admin_manual');
+        res.json({ success: true, message: `Honeypot trap added for path "${routePath.trim()}"` });
+    });
+
+    // 13. Remove Honeypot Route
+    router.delete('/api/honeypot/{*path}', (req, res) => {
+        const raw = req.params.path;
+        const routePath = Array.isArray(raw) ? '/' + raw.join('/') : (req.query.path || '/' + (raw || ''));
+        const removed = shield.honeypotInstance.removeRoute(routePath);
+        res.json({ success: removed, message: removed ? `Removed trap "${routePath}"` : `Trap not found` });
+    });
+
+    // 14. Promote a 404 path to honeypot manually
+    router.post('/api/promote', express.json(), (req, res) => {
+        const { path: routePath } = req.body || {};
+        if (!routePath || typeof routePath !== 'string') {
+            return res.status(400).json({ error: 'Valid "path" string is required' });
+        }
+        const promoted = shield.autoPromoter?.promotePath(routePath.trim());
+        res.json({ success: !!promoted, message: `Path "${routePath.trim()}" promoted to honeypot trap` });
+    });
+
+    // 15. Server-Sent Events (SSE) Live Feed
+    router.get('/api/stream', (req, res) => {
+        res.setHeader('Content-Type', 'text/event-stream');
+        res.setHeader('Cache-Control', 'no-cache');
+        res.setHeader('Connection', 'keep-alive');
+        res.flushHeaders?.();
+
+        // Send initial connection event
+        res.write(`data: ${JSON.stringify({ type: 'connected', timestamp: Date.now() })}\n\n`);
+
+        const listener = (event) => {
+            res.write(`data: ${JSON.stringify(event)}\n\n`);
+        };
+
+        shield.on('event', listener);
+
+        const heartbeat = setInterval(() => {
+            res.write(': heartbeat\n\n');
+        }, 15000);
+
+        req.on('close', () => {
+            clearInterval(heartbeat);
+            shield.off('event', listener);
+        });
+    });
+
+    return router;
+}