@chdlabs/my-shield 0.1.0 → 0.1.2

package/README.md

@@ -10,13 +10,14 @@
 
 ## 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`).
+-  **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.
+-  **Safe By Default**: Admin dashboard is disabled by default (`admin.enabled: false`) with dedicated RBAC integration to prevent unauthorized telemetry access.
+-  **Zero Production Dependencies**: Pure JavaScript built exclusively with Node.js built-ins (`crypto`, `fs`, `path`, `events`).
 
 ---
 
@@ -70,6 +71,10 @@ import { createShield } from '@chdlabs/my-shield';
 const app = express();
 
 const shield = createShield({
+  whitelist: ['127.0.0.1', '::1'],
+  admin: {
+    enabled: true // Set to true to activate dashboard & telemetry (Default: false)
+  },
   bloom: {
     expectedItems: 100_000,
     falsePositiveRate: 0.01
@@ -113,8 +118,10 @@ 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());
+// 5. Mount admin dashboard (protect API endpoints with your app's auth & RBAC middleware)
+app.use('/admin/shield', shield.adminRouter({
+  authMiddleware: [authenticateUser, requireAdminRole]
+}));
 
 // Graceful shutdown: flushes 404 intelligence to disk
 process.on('SIGTERM', async () => {
@@ -125,11 +132,83 @@ process.on('SIGTERM', async () => {
 
 ---
 
+## 🔐 Admin Dashboard & Role-Based Access Control (RBAC)
+
+The built-in admin dashboard provides live telemetry, attack velocity, probe intelligence, active threat management, and real-time Server-Sent Events (SSE).
+
+### 1. Enabling the Dashboard
+By default, the admin dashboard is **disabled** (`admin.enabled: false`). If mounted while disabled, `/admin/shield` safely returns `404 Not Found`. To enable it, explicitly configure:
+```javascript
+const shield = createShield({
+  admin: {
+    enabled: true // Required to activate dashboard routes
+  }
+});
+```
+
+### 2. Restricting Access to Administrators Only
+Do **not** wrap `shield.adminRouter()` at the top-level route (e.g., `app.use('/admin/shield', requireAdmin, ...)`). Doing so causes browser page visits to fail with an immediate `401 Unauthorized` JSON response because web browsers do not send `Authorization` headers on initial page navigations.
+
+Instead, pass your authentication and authorization middleware into `shield.adminRouter({ authMiddleware })`:
+```javascript
+app.use('/admin/shield', shield.adminRouter({
+  authMiddleware: [authenticateUser, requireAdminRole]
+}));
+```
+
+#### Why this pattern is secure:
+1. **Public Static Delivery**: The browser can freely download the dashboard SPA shell (`index.html`, `dashboard.css`, `dashboard.js`).
+2. **Protected API & Telemetry**: All data-bearing endpoints (`/admin/shield/api/stats`, `/admin/shield/api/blocked`, `/admin/shield/api/stream`, etc.) are strictly guarded by your `authMiddleware`.
+3. **Graceful UI Feedback**: If a non-admin or unauthenticated visitor accesses the page, the dashboard renders an informative warning banner rather than a raw, broken JSON error.
+
+### 3. Complete Express RBAC Example
+
+```javascript
+// Step A: Authentication middleware (verifies JWT / Bearer token)
+function authenticateUser(req, res, next) {
+  const authHeader = req.headers.authorization || (req.query?.token ? `Bearer ${req.query.token}` : null);
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    return res.status(401).json({ error: 'Authentication required. Missing Authorization header.' });
+  }
+
+  const token = authHeader.split(' ')[1];
+  try {
+    const claims = verifyJwt(token); // Verify your JWT / PQC token
+    req.user = claims;
+    next();
+  } catch (err) {
+    return res.status(401).json({ error: 'Invalid or expired session token.' });
+  }
+}
+
+// Step B: Role-Based Access Control (RBAC) middleware
+function requireAdminRole(req, res, next) {
+  // Check user role from token claims or database lookup
+  if (!req.user || (req.user.role !== 'admin' && req.user.role !== 'super_admin')) {
+    return res.status(403).json({ error: 'Access denied: Administrator privileges required.' });
+  }
+  next();
+}
+
+// Step C: Mount protected admin router
+app.use('/admin/shield', shield.adminRouter({
+  authMiddleware: [authenticateUser, requireAdminRole]
+}));
+```
+
+### 4. How the Dashboard Authenticates
+The dashboard client automatically looks for the session token in the following order:
+1. **URL Query Parameter**: Navigating to `http://your-server.com/admin/shield?token=<jwt>` extracts the token into `sessionStorage` and automatically scrubs the parameter from the browser's address bar to prevent token leakage.
+2. **Storage Fallback**: Checks `sessionStorage` and `localStorage` under standard keys: `shield_session_token`, `pqc_session_token`, `token`, `access_token`, `auth_token`, or `jwt`.
+
+---
+
 ## Configuration Reference
 
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `whitelist` | `string[]` | `[]` | List of IP addresses that are never blocked |
+| `admin.enabled` | `boolean` | `false` | Explicit switch to enable the admin dashboard & telemetry |
 | `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 |
@@ -175,23 +254,6 @@ 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

@@ -1,6 +1,6 @@
 {
   "name": "@chdlabs/my-shield",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Zero-latency security shield middleware with Bloom filter, honeypots, and 404 intelligence",
   "type": "module",
   "main": "src/index.js",
@@ -18,8 +18,9 @@
   "peerDependencies": {
     "express": ">=4.18.0 || >=5.0.0"
   },
-  "dependencies": {},
-  "devDependencies": {},
+  "devDependencies": {
+    "express": "^5.2.1"
+  },
   "engines": {
     "node": ">=20.0.0"
   },
@@ -42,4 +43,4 @@
   "scripts": {
     "test": "node test/integration.test.js"
   }
-}
+}

package/src/admin/adminRouter.js

@@ -15,6 +15,19 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 export function createAdminRouter(shield, options = {}) {
+    const isEnabled = options.enabled !== undefined ? Boolean(options.enabled) : Boolean(shield?.adminEnabled);
+    if (!isEnabled) {
+        shield?.logger?.warn?.('[SHIELD] Admin dashboard router is mounted, but admin is disabled in configuration. Enable via createShield({ admin: { enabled: true } }) or shield.adminRouter({ enabled: true })');
+        const disabledRouter = express.Router();
+        disabledRouter.use((req, res) => {
+            res.status(404).json({
+                error: 'Shield admin dashboard is disabled in configuration.',
+                hint: 'Enable via createShield({ admin: { enabled: true } }) or shield.adminRouter({ enabled: true })'
+            });
+        });
+        return disabledRouter;
+    }
+
     const router = express.Router();
     const dashboardDir = path.resolve(__dirname, 'dashboard');
     const authMiddleware = Array.isArray(options.authMiddleware) ? options.authMiddleware : (options.authMiddleware ? [options.authMiddleware] : []);

package/src/admin/dashboard/dashboard.css

@@ -532,3 +532,23 @@ body.shield-body {
     from { transform: translateX(20px); opacity: 0; }
     to { transform: translateX(0); opacity: 1; }
 }
+
+/* Auth Challenge Banners */
+.auth-banner {
+    padding: 0.85rem 1.25rem;
+    margin-bottom: 1.5rem;
+    border-radius: var(--radius-md);
+    font-size: 0.875rem;
+    line-height: 1.4;
+    font-weight: 500;
+}
+.auth-banner-unauth {
+    background-color: rgba(234, 179, 8, 0.15);
+    border: 1px solid rgba(234, 179, 8, 0.4);
+    color: #fde047;
+}
+.auth-banner-forbidden {
+    background-color: rgba(239, 68, 68, 0.15);
+    border: 1px solid rgba(239, 68, 68, 0.4);
+    color: #fca5a5;
+}

package/src/admin/dashboard/dashboard.js

@@ -49,8 +49,57 @@
         }, 4000);
     }
 
+    function setAuthBanner(type, message) {
+        let banner = document.getElementById('shield-auth-banner');
+        if (!banner) {
+            banner = document.createElement('div');
+            banner.id = 'shield-auth-banner';
+            const main = document.querySelector('.main-content');
+            if (main) {
+                main.insertBefore(banner, main.firstChild);
+            }
+        }
+        if (banner) {
+            banner.className = `auth-banner ${type === '403' ? 'auth-banner-forbidden' : 'auth-banner-unauth'}`;
+            banner.textContent = message;
+            banner.style.display = 'block';
+        }
+    }
+
+    function clearAuthBanner() {
+        const banner = document.getElementById('shield-auth-banner');
+        if (banner) {
+            banner.style.display = 'none';
+        }
+    }
+
     function getStoredToken() {
-        return localStorage.getItem('pqc_session_token');
+        if (typeof window === 'undefined') return null;
+
+        // 1. Check URL query params for ?token=... or ?auth=...
+        try {
+            const params = new URLSearchParams(window.location.search);
+            const queryToken = params.get('token') || params.get('auth');
+            if (queryToken) {
+                sessionStorage.setItem('shield_session_token', queryToken);
+                params.delete('token');
+                params.delete('auth');
+                const cleanQuery = params.toString() ? `?${params.toString()}` : '';
+                window.history.replaceState({}, '', window.location.pathname + cleanQuery + window.location.hash);
+                return queryToken;
+            }
+        } catch {
+            // Ignore URL parsing errors
+        }
+
+        // 2. Check session and local storage with multi-key fallback
+        return sessionStorage.getItem('shield_session_token')
+            || localStorage.getItem('shield_session_token')
+            || localStorage.getItem('pqc_session_token')
+            || localStorage.getItem('token')
+            || localStorage.getItem('access_token')
+            || localStorage.getItem('auth_token')
+            || localStorage.getItem('jwt');
     }
 
     async function apiFetch(url, options = {}) {
@@ -61,9 +110,13 @@
         }
         const res = await fetch(url, { ...options, headers });
         if (res.status === 401) {
+            setAuthBanner('401', '⚠️ Authentication required: Please log in to the application with an administrator account to access telemetry and management APIs.');
             showToast('Authentication required. Please login with an admin account.', 'error');
         } else if (res.status === 403) {
+            setAuthBanner('403', '🚫 Access denied: Administrator privileges required for this account.');
             showToast('Access denied: Administrator privileges required.', 'error');
+        } else if (res.ok) {
+            clearAuthBanner();
         }
         return res;
     }

package/src/index.d.ts

@@ -43,12 +43,17 @@ export interface IntelligenceOptions {
     autoPromote?: AutoPromoteOptions;
 }
 
+export interface AdminOptions {
+    enabled?: boolean;
+}
+
 export interface ShieldOptions {
     whitelist?: string[];
     bloom?: BloomOptions;
     lru?: LRUOptions;
     honeypot?: HoneypotOptions;
     intelligence?: IntelligenceOptions;
+    admin?: AdminOptions;
     blockStatusCode?: number;
     logger?: {
         info?: (...args: any[]) => void;
@@ -64,6 +69,7 @@ export interface CostThrottleOptions {
 }
 
 export interface AdminRouterOptions {
+    enabled?: boolean;
     authMiddleware?: RequestHandler | RequestHandler[];
 }
 

package/src/index.js

@@ -121,6 +121,10 @@ export class Shield extends EventEmitter {
             shield: this,
             logger: this.logger
         });
+
+        // 8. Admin Dashboard Configuration (Default: false)
+        const adminOpts = options.admin || {};
+        this.adminEnabled = Boolean(adminOpts.enabled);
     }
 
     /**