@chdlabs/my-shield 0.2.0 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # 🛡️ @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.
+> High-performance, zero-latency security shield middleware for Express. Built with pure JavaScript probabilistic data structures (Bloom filter + LRU cache), honeypot traps, MiniRocket behavioral biometrics, pluggable threat persistence, and container-native enterprise IP resolution.
 
 [![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/)
@@ -12,13 +12,16 @@
 
 -  **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.
--  **MiniRocket Behavioral Biometrics**: Sub-2ms bot detection using deterministic 1D convolutional kernel transforms and Dual Ridge regression to identify automated splines and synthetic kinematics with zero runtime dependencies.
+-  **Enterprise Client IP Resolution (`IPResolver`)**: Production-tested parsing for Cloudflare (`CF-Connecting-IP`), Akamai (`True-Client-IP`), Nginx (`X-Real-IP`), and multi-hop HAProxy chains (`X-Forwarded-For`) with IPv6-mapped IPv4 normalization and port stripping.
+-  **Docker & Gateway Protection**: Docker bridge gateways (`172.17.0.1`) and loopback addresses (`127.0.0.1`, `::1`) are permanently immune from bans, preventing accidental container isolation.
+-  **Mission-Critical Route Protection**: First-class `shield.strictBotGuard()` to protect `/login`, `/checkout`, and `/register` against credential stuffing, carding (card testing), and automated account spam.
+-  **Dual-Mode Behavioral Biometrics**: Calibrated Ridge decision boundary (`0.50`) supporting non-blocking `'audit'` mode (for searches and queries) alongside strict `'block'` mode (for auth and checkout).
+-  **First-Party Client SDK (`@chdlabs/my-shield/client`)**: Unified `ShieldClient` and `PointerTelemetryCollector` with mobile touch support (`pointerdown`, `touchmove`, tap dwell kinetics), pointer freshness guards ($t_{\text{idle}} \le 2.5\text{s}$), buffer flushes on consumption, and automatic `fetch`/`Axios` interceptors.
+-  **Pluggable Threat Persistence**: Zero-overhead in-memory adapter, local JSON file persistence (`FileStorageAdapter`), or universal database hooks (`PostgreSQL`, `MySQL`, `Redis`, `Prisma`).
+-  **Built-in Admin OTP / MFA Challenge Gate**: Standalone, dark-mode OTP verification portal (`shield.otpGate()`) with timing-safe HMAC validation and brute-force protection.
+-  **Silent Honeypot Decoys**: Static trap routes (`/.env`, `/wp-login.php`, `/.git/config`, etc.) return a silent `200 OK` decoy response 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`).
+-  **Zero Production Dependencies**: Pure JavaScript built exclusively with Node.js built-ins (`crypto`, `fs`, `path`, `events`, `net`).
 
 ---
 
@@ -29,9 +32,14 @@ Incoming Request
        │
        ▼
 ┌───────────────────────────────────────┐
+│ Enterprise IPResolver                 │
+│ Cloudflare / Nginx / HAProxy / Direct │
+│ Gateway Protection (172.17.0.1 Immune)│
+└──────────────────┬────────────────────┘
+                   ▼
+┌───────────────────────────────────────┐
 │ L1 Shield Guard                       │
-│                                       │
-│ 1. IP Whitelist?   ──▶ Pass           │
+│ 1. IP Whitelisted? ──▶ Pass           │
 │ 2. Bloom Filter?   ──▶ False = Pass   │
 │ 3. LRU Cache?      ──▶ Found = Block  │
 └──────────────────┬────────────────────┘
@@ -43,11 +51,10 @@ Incoming Request
 └──────────────────┬────────────────────┘
                    ▼
 ┌───────────────────────────────────────┐
-│ Behavioral Biometrics Guard (Optional)│
-│ MiniRocket + Dual Ridge (< 2ms)       │
-│ Replay nonces?     ──▶ Block 403      │
-│ Synthetic event?   ──▶ Block 403      │
-│ Human probability? ──▶ >= 0.70 Pass   │
+│ Route-Level Bot Defenses (Optional)   │
+│ • strictBotGuard() on /login & /pay   │
+│ • behavioralGuard({ mode: 'audit' })  │
+│ • costThrottle() on high-cost routes  │
 └──────────────────┬────────────────────┘
                    ▼
 ┌───────────────────────────────────────┐
@@ -57,7 +64,7 @@ Incoming Request
 ┌───────────────────────────────────────┐
 │ 404 Intelligence Collector            │
 │ ≥ 5 unique 404s/60s? ──▶ Ban IP       │
-│ Dedup snapshot saved to disk          │
+│ Auto-promotes frequent targets        │
 └───────────────────────────────────────┘
 ```
 
@@ -81,63 +88,40 @@ const app = express();
 
 const shield = createShield({
   whitelist: ['127.0.0.1', '::1'],
+  trustProxy: true, // Auto-resolve Cloudflare, Nginx, or HAProxy client IPs
+  protectGateways: true, // Prevents 172.17.0.1 & loopbacks from ever being banned
+  storage: 'file', // Persist bans to ./data/shield/blocked_ips.json across restarts
   admin: {
-    enabled: true // Set to true to activate dashboard & telemetry (Default: false)
-  },
-  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
-    }
+    enabled: true // Set to true to activate dashboard (Default: false)
   }
 });
 
+// Hydrate persisted threats into Bloom and LRU on application startup
+await shield.init();
+
 // 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());
 
-
-// -----------------> ADD IN HERE ALL YOUR APPLICATION ROUTES <----------------//
-app.get('/api/data', (req, res) => res.json({ status: 'ok' }));
-// -----------------> ADD IN HERE ALL YOUR APPLICATION ROUTES <----------------//
-
-
-
+// 3. Application Routes
+app.get('/api/catalog', (req, res) => res.json({ items: [] }));
 
 // 4. Mount 404 intelligence collector (AFTER application routes)
 app.use(shield.notFoundCollector());
 
-// 5. Mount admin dashboard (protect API endpoints with your app's auth & RBAC middleware)
-app.use('/admin/shield', shield.adminRouter({
-  authMiddleware: [authenticateUser, requireAdminRole]
+// 5. Standalone OTP Protected Admin Console
+app.use('/admin/shield', shield.otpGate({
+  adminEmail: 'security@company.com',
+  async sendOtp(email, code) {
+    // Send OTP via your email service (Nodemailer, SendGrid, etc.)
+    console.log(`[OTP] Sent code ${code} to ${email}`);
+  }
 }));
+app.use('/admin/shield', shield.adminRouter());
 
-// Graceful shutdown: flushes 404 intelligence to disk
+// Graceful shutdown: flushes intelligence and threat persistence to disk
 process.on('SIGTERM', async () => {
   await shield.shutdown();
   process.exit(0);
@@ -146,208 +130,219 @@ process.on('SIGTERM', async () => {
 
 ---
 
-## 🔐 Admin Dashboard & Role-Based Access Control (RBAC)
+## 🛡️ Protecting Mission-Critical Routes (`/login`, `/checkout`, `/register`) From Bots
 
-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]
-}));
-```
+Automated bots attack high-value mutation endpoints in three distinct ways:
+1. **Credential Stuffing & Brute Force (`/login`)**: Trying thousands of leaked email/password combinations.
+2. **Card Testing / Carding (`/checkout`)**: Testing stolen credit card numbers, which triggers costly payment gateway decline fees and chargebacks.
+3. **Account Farming (`/register`)**: Creating fake accounts for spamming or exploiting promotional credits.
 
-#### 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.
+### 1. Backend Route Protection (`shield.strictBotGuard()`)
 
-### 3. Complete Express RBAC Example
+Mount `shield.strictBotGuard()` directly on your sensitive POST endpoints. It verifies behavioral mouse dynamics, rejects synthetic or automated bot vectors with `403 Forbidden`, and **instantly auto-bans the attacker's IP**:
 
 ```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.' });
-  }
-}
+import express from 'express';
+import { createShield } from '@chdlabs/my-shield';
 
-// 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();
-}
+const app = express();
+app.use(express.json());
 
-// Step C: Mount protected admin router
-app.use('/admin/shield', shield.adminRouter({
-  authMiddleware: [authenticateUser, requireAdminRole]
-}));
-```
+const shield = createShield({ trustProxy: true });
+await shield.init();
 
-### 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`.
+// Global ingress guard
+app.use(shield.middleware());
 
----
+// ── Protect High-Risk Mutations ──
 
-## 🧠 Behavioral Biometrics via MiniRocket & Dual Ridge
+// Protect Login against credential stuffing
+app.post('/api/auth/login', shield.strictBotGuard(), (req, res) => {
+  // Only authentic human users reach this handler!
+  res.json({ success: true, token: 'session_token' });
+});
 
-`@chdlabs/my-shield` incorporates client-side and server-side behavioral biometrics based on **MiniRocket** (*Minimally Random Convolutional Kernel Transform*) and a **Dual Ridge Classifier**.
+// Protect User Registration against fake accounts
+app.post('/api/auth/register', shield.strictBotGuard(), (req, res) => {
+  res.json({ success: true, user: req.body.email });
+});
 
-### Why Behavioral Biometrics?
-Headless automation tools (Puppeteer, Playwright, curl) and synthetic scripts often lack realistic pointer physics or produce mathematically smoothed Bézier splines. Human users exhibit distinct continuous neuromuscular tremor, deceleration profiles, micro-corrections, and sub-movements.
+// Protect Checkout: Combine Strict Bot Defense with Cost Throttling
+app.post('/api/checkout',
+  shield.strictBotGuard(),
+  shield.costThrottle({ weight: 5, maxCost: 50, windowMs: 60000 }),
+  (req, res) => {
+    res.json({ success: true, orderId: 'ord_123' });
+  }
+);
 
-MiniRocket maps 128-point equispaced mouse velocity trajectories into a high-dimensional feature space using 84 deterministic length-9 kernels with multi-scale dilations and Proportion of Positive Values (PPV). Scoring is resolved via a single dot-product in Dual Ridge regression in **< 2.0 ms** with zero runtime dependencies.
+// ── Protect High-Volume Reads with Audit Mode ──
+// Does not reject searches, but logs kinematics and attaches X-Shield-Verdict header
+app.get('/api/search', shield.behavioralGuard({ mode: 'audit' }), (req, res) => {
+  res.json({ results: [] });
+});
+```
 
----
+### 2. Frontend Client Integration (`ShieldClient`)
 
-### 1. Client-Side Telemetry Collection (Browser)
+Install `@chdlabs/my-shield` in your frontend application (or import `./client`).
 
-Import the browser client module (`@chdlabs/my-shield/client`):
+The client captures human pointer micro-movements across desktop mice, trackpads, and mobile touchscreens (measuring both continuous trajectory gestures and button tap dwell kinetics). When `instrumentFetch()` is enabled, it automatically attaches the `x-shield-telemetry` header to your API requests:
 
 ```javascript
-import { MouseTelemetryCollector } from '@chdlabs/my-shield/client';
+// client/index.js (React, Vue, or Vanilla JS)
+import { ShieldClient } from '@chdlabs/my-shield/client';
 
-// 1. Initialize telemetry collector (128 samples at 100Hz = 1.28s rolling window)
-const collector = new MouseTelemetryCollector({
+// 1. Initialize client SDK
+const shieldClient = new ShieldClient({
+  sampleIntervalMs: 10,
   windowLength: 128,
-  sampleIntervalMs: 10
+  minPoints: 15,          // Minimum raw events for continuous trajectories
+  maxIdleMs: 2500,        // Freshness Guard: Discards trajectory if pointer idle > 2.5s
+  captureTouch: true,     // Enables mobile touch & pointer dynamics
+  minTapDwellMs: 20,      // Distinguishes genuine human taps from instant 0ms bot clicks
+  flushOnConsumption: true, // Prevents replaying identical trajectories
+  autoInjectTripwire: true // Injects invisible honeypot decoy trap into DOM
 });
 
-// 2. Start capturing pointer dynamics
-collector.start();
+// 2. Start recording kinematics
+shieldClient.start();
 
-// 3. Attach telemetry packet to sensitive API requests
-async function submitLogin(username, password) {
-  // Extracts normalized 100Hz velocity series and event integrity metadata
-  const telemetry = collector.getPayload(); // { velocity: number[], isTrusted: boolean, timestamp: number }
+// 3. Transparently instrument fetch (or Axios)
+shieldClient.instrumentFetch({
+  headerName: 'x-shield-telemetry',
+  endpoints: ['/api/auth/*', '/api/checkout*']
+});
 
-  const response = await fetch('/api/auth/login', {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'x-shield-telemetry': telemetry ? JSON.stringify(telemetry) : ''
-    },
-    body: JSON.stringify({ username, password })
-  });
+// Now standard fetch calls automatically include kinematics telemetry!
+async function submitLogin(email, password) {
+  try {
+    const res = await fetch('/api/auth/login', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email, password })
+    });
+
+    if (res.status === 403) {
+      const err = await res.json();
+      if (err.shieldCode === 'AUTOMATED_KINEMATICS_DETECTED') {
+        alert('Bot behavior detected. Please interact with the page normally.');
+        return;
+      }
+    }
 
-  return response.json();
+    const data = await res.json();
+    console.log('Login successful:', data);
+  } catch (err) {
+    console.error('Request failed:', err);
+  }
 }
 ```
 
 ---
 
-### 2. Server-Side Route Guard (Express)
+## 🌐 Enterprise Reverse Proxies & Gateway Protection
 
-Protect sensitive routes (e.g. login, payment checkout, AI prompt generation) with `shield.behavioralGuard()`:
+When deploying in Docker, Kubernetes, AWS, or behind Cloudflare, standard `req.ip` lookups fail or ban internal container gateways. `IPResolver` resolves this natively:
 
 ```javascript
-import express from 'express';
-import { createShield } from '@chdlabs/my-shield';
-
-const app = express();
-app.use(express.json());
+const shield = createShield({
+  // Trust proxy headers: true | false | 'loopback,linklocal,uniquelocal'
+  trustProxy: true,
 
-const shield = createShield();
-
-// Protect sensitive endpoints with behavioral biometrics
-app.post(
-  '/api/auth/login',
-  shield.behavioralGuard({
-    threshold: 0.70,                  // Minimum human probability required (default: 0.70)
-    headerName: 'x-shield-telemetry', // Header containing telemetry JSON
-    replayWindowMs: 15_000,           // Max acceptable age/drift in ms (default: 15s)
-    autoBlockIP: true,                // Auto-blacklist detected bots into Shield L1 Bloom + LRU
-    allowFallbackOnError: false,      // Fail-closed (default: false)
-    onBotDetected: (req, res, meta) => {
-      // Optional custom callback when bot is intercepted
-      console.warn(`[BOT DETECTED] IP: ${req.ip}, Reason: ${meta.reason}, Confidence: ${meta.probability}`);
-      res.status(403).json({ error: 'Automated kinematics detected.', code: meta.reason });
-    }
-  }),
-  (req, res) => {
-    // Verified human request! Access biometric audit metadata:
-    console.log(req.shield.biometrics);
-    // => { isHuman: true, humanConfidence: 0.94, latencyMs: 0.85, score: 2.75 }
+  // Permanently protects Docker bridge (172.17.0.1) & loopbacks from bans
+  protectGateways: true,
 
-    res.json({ status: 'authenticated' });
-  }
-);
+  // Optional custom subnets to shield from accidental bans
+  protectedSubnets: ['10.0.0.1', '192.168.1.1']
+});
 ```
 
+### Supported Proxy Headers (in priority order):
+1. `cf-connecting-ip` (Cloudflare)
+2. `true-client-ip` (Akamai & Cloudflare Enterprise)
+3. `x-real-ip` (Nginx `proxy_set_header X-Real-IP $remote_addr`)
+4. `x-client-ip`
+5. `x-forwarded-for` (Multi-hop chains are parsed to find the first non-internal public IP)
+
+If `trustProxy: false` is set (direct internet exposure without reverse proxy), all proxy headers are ignored to prevent header spoofing injection attacks.
+
 ---
 
-### 3. Standalone Core Biometrics API
+## 💾 Pluggable Threat Persistence
 
-You can also use MiniRocket and the Dual Ridge Classifier directly for custom data pipelines or time series classification:
+In containerized or serverless deployments, in-memory caches reset on every restart. Shield supports pluggable persistence adapters to maintain active threat bans:
 
+### 1. Single-Container File Persistence (Zero External Dependencies)
 ```javascript
-import { MiniRocket, DualRidgeClassifier } from '@chdlabs/my-shield/biometrics';
+const shield = createShield({
+  storage: {
+    type: 'file',
+    directory: './data/shield',
+    filename: 'blocked_ips.json',
+    debounceMs: 500 // Debounced atomic writes
+  }
+});
+await shield.init();
+```
 
-// 1. Transform a 128-sample series into PPV features
-const mr = new MiniRocket(128, 336);
-mr.loadThresholds(fittedThresholds);
-const features = mr.transform(velocitySeries);
+### 2. Database & Cache Persistence (PostgreSQL, Redis, MongoDB, Prisma)
+Plug any database into Shield with three async callbacks:
 
-// 2. Predict class probability
-const ridge = new DualRidgeClassifier();
-ridge.loadWeights(fittedWeights, bias);
-const result = ridge.predict(features);
+```javascript
+const shield = createShield({
+  storage: {
+    async onLoad() {
+      // Return active unexpired blocked IPs on boot
+      const { rows } = await db.query(
+        'SELECT ip, reason, metadata, expires_at AS "expiresAt" FROM blocked_threats WHERE expires_at IS NULL OR expires_at > NOW()'
+      );
+      return rows;
+    },
+    async onBlock(ip, reason, metadata, expiresAt) {
+      // Save or update blocked threat
+      await db.query(
+        `INSERT INTO blocked_threats (ip, reason, metadata, expires_at)
+         VALUES ($1, $2, $3, $4)
+         ON CONFLICT (ip) DO UPDATE SET reason = $2, metadata = $3, expires_at = $4`,
+        [ip, reason, JSON.stringify(metadata), expiresAt ? new Date(expiresAt) : null]
+      );
+    },
+    async onUnblock(ip) {
+      await db.query('DELETE FROM blocked_threats WHERE ip = $1', [ip]);
+    }
+  }
+});
 
-console.log(result);
-// => { score: 1.42, probability: 0.805, isHuman: true }
+// Restores unexpired database threats into Bloom filter and LRU cache
+await shield.init();
 ```
 
 ---
 
-### 4. Custom Model Retraining CLI
+## 🔑 Built-in Admin OTP / MFA Challenge Gate
 
-To retrain model weights against your own captured movement datasets:
+Shield includes a standalone, zero-dependency dark-mode OTP challenge gate (`shield.otpGate()`) that protects `/admin/shield` without requiring external login libraries:
 
-```bash
-node scripts/train-weights.js
-```
-This fits MiniRocket thresholds and Dual Ridge primal weights from your kinematic data, serializing the bundle to `models/default-weights.json`.
-
----
-
-### Behavioral Guard Options Reference
+```javascript
+app.use('/admin/shield', shield.otpGate({
+  adminEmail: 'admin@company.com',
+  jwtSecret: process.env.SHIELD_SECRET, // Signs session cookies
+  codeTtlMs: 5 * 60 * 1000,             // Code valid for 5 minutes
+  maxAttempts: 5,                        // Locks out after 5 invalid tries
+  async sendOtp(email, code) {
+    // Deliver via email or SMS
+    await mailer.sendMail({
+      to: email,
+      subject: 'Shield Admin Passcode',
+      text: `Your one-time passcode is: ${code}`
+    });
+  }
+}));
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `threshold` | `number` | `0.70` | Minimum human probability cutoff ($P \ge \text{threshold}$) |
-| `headerName` | `string` | `'x-shield-telemetry'` | Request header containing JSON telemetry payload |
-| `replayWindowMs` | `number` | `15000` | Sliding window in ms; rejects expired or futuristic timestamps |
-| `allowFallbackOnError` | `boolean` | `false` | Fail-open (`true`) vs fail-closed (`false`) when telemetry is missing or malformed |
-| `autoBlockIP` | `boolean` | `false` | Automatically add detected bot IP to Shield L1 Bloom + LRU cache |
-| `onBotDetected` | `Function` | `undefined` | Custom callback `(req, res, meta)` invoked when bot or replay is detected |
+// Mount dashboard router
+app.use('/admin/shield', shield.adminRouter());
+```
 
 ---
 
@@ -356,26 +351,18 @@ This fits MiniRocket thresholds and Dual Ridge primal weights from your kinemati
 | 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 |
+| `trustProxy` | `boolean\|string` | `'loopback,linklocal,uniquelocal'` | Reverse proxy trust configuration |
+| `protectGateways` | `boolean` | `true` | Protects Docker bridge (`172.17.0.1`) and loopback from bans |
+| `storage` | `string\|Object` | `'memory'` | Storage adapter (`'memory'`, `'file'`, or callback hooks) |
+| `admin.enabled` | `boolean` | `false` | Explicit switch to enable admin dashboard & telemetry |
+| `bloom.expectedItems` | `number` | `100000` | Estimated distinct IPs to hold in Bloom 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.enabled` | `boolean` | `true` | Enable/disable static honeypot traps |
 | `honeypot.delayMs` | `number` | `500` | Delay before sending silent 200 OK decoy |
-| `honeypot.additionalRoutes` | `string[]` | `[]` | Custom trap path patterns |
-| `biometrics.modelWeights` | `Object` | `null` | Custom MiniRocket thresholds, weights, and bias |
 | `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 |
 
 ---
 
@@ -386,7 +373,6 @@ This fits MiniRocket thresholds and Dual Ridge primal weights from your kinemati
 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
@@ -394,14 +380,14 @@ shield.getStats();          // Returns aggregate stats, LRU sizes, traps list
 shield.getIntelligence();   // Full 404 intelligence snapshot
 shield.getBloomHealth();    // Saturation percentage and estimated FPR
 
-// Behavioral Biometrics
-const outcome = shield.verifyBiometrics(velocityArray); // { score, probability, isHuman, latencyMs }
-app.post('/api/auth/login', shield.behavioralGuard({ threshold: 0.70 }), handler);
+// Route-Level Bot Defenses
+app.post('/api/auth/login', shield.strictBotGuard(), handler);
+app.get('/api/search', shield.behavioralGuard({ mode: 'audit' }), handler);
 
-// Route-Level Denial-of-Wallet Cost Throttling
+// Denial-of-Wallet Cost Throttling
 app.post('/api/ai-generate', shield.costThrottle({ weight: 10, maxCost: 100 }), handler);
 
-// Route-Level Token / Credential Leak Detection
+// API Key / Secret Leak Detector
 app.use(shield.keyLeakDetector());
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chdlabs/my-shield",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Zero-latency security shield middleware with Bloom filter, honeypots, 404 intelligence, and MiniRocket behavioral biometrics",
   "type": "module",
   "main": "src/index.js",
@@ -17,6 +17,10 @@
     "./biometrics": {
       "types": "./src/index.d.ts",
       "import": "./src/biometrics/index.js"
+    },
+    "./storage": {
+      "types": "./src/index.d.ts",
+      "import": "./src/storage/index.js"
     }
   },
   "publishConfig": {