@chdlabs/my-shield 0.1.3 → 0.2.0

package/README.md

@@ -13,6 +13,7 @@
 -  **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.
 -  **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.
@@ -42,6 +43,14 @@ Incoming Request
 └──────────────────┬────────────────────┘
                    ▼
 ┌───────────────────────────────────────┐
+│ Behavioral Biometrics Guard (Optional)│
+│ MiniRocket + Dual Ridge (< 2ms)       │
+│ Replay nonces?     ──▶ Block 403      │
+│ Synthetic event?   ──▶ Block 403      │
+│ Human probability? ──▶ >= 0.70 Pass   │
+└──────────────────┬────────────────────┘
+                   ▼
+┌───────────────────────────────────────┐
 │ Application Routes (Your API)         │
 └──────────────────┬────────────────────┘
                    ▼
@@ -208,6 +217,140 @@ The dashboard client automatically looks for the session token in the following
 
 ---
 
+## 🧠 Behavioral Biometrics via MiniRocket & Dual Ridge
+
+`@chdlabs/my-shield` incorporates client-side and server-side behavioral biometrics based on **MiniRocket** (*Minimally Random Convolutional Kernel Transform*) and a **Dual Ridge Classifier**.
+
+### 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.
+
+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.
+
+---
+
+### 1. Client-Side Telemetry Collection (Browser)
+
+Import the browser client module (`@chdlabs/my-shield/client`):
+
+```javascript
+import { MouseTelemetryCollector } from '@chdlabs/my-shield/client';
+
+// 1. Initialize telemetry collector (128 samples at 100Hz = 1.28s rolling window)
+const collector = new MouseTelemetryCollector({
+  windowLength: 128,
+  sampleIntervalMs: 10
+});
+
+// 2. Start capturing pointer dynamics
+collector.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 }
+
+  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 })
+  });
+
+  return response.json();
+}
+```
+
+---
+
+### 2. Server-Side Route Guard (Express)
+
+Protect sensitive routes (e.g. login, payment checkout, AI prompt generation) with `shield.behavioralGuard()`:
+
+```javascript
+import express from 'express';
+import { createShield } from '@chdlabs/my-shield';
+
+const app = express();
+app.use(express.json());
+
+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 }
+
+    res.json({ status: 'authenticated' });
+  }
+);
+```
+
+---
+
+### 3. Standalone Core Biometrics API
+
+You can also use MiniRocket and the Dual Ridge Classifier directly for custom data pipelines or time series classification:
+
+```javascript
+import { MiniRocket, DualRidgeClassifier } from '@chdlabs/my-shield/biometrics';
+
+// 1. Transform a 128-sample series into PPV features
+const mr = new MiniRocket(128, 336);
+mr.loadThresholds(fittedThresholds);
+const features = mr.transform(velocitySeries);
+
+// 2. Predict class probability
+const ridge = new DualRidgeClassifier();
+ridge.loadWeights(fittedWeights, bias);
+const result = ridge.predict(features);
+
+console.log(result);
+// => { score: 1.42, probability: 0.805, isHuman: true }
+```
+
+---
+
+### 4. Custom Model Retraining CLI
+
+To retrain model weights against your own captured movement datasets:
+
+```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
+
+| 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 |
+
+---
+
 ## Configuration Reference
 
 | Option | Type | Default | Description |
@@ -222,6 +365,7 @@ The dashboard client automatically looks for the session token in the following
 | `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 |
+| `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 |
@@ -250,6 +394,10 @@ 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 Denial-of-Wallet Cost Throttling
 app.post('/api/ai-generate', shield.costThrottle({ weight: 10, maxCost: 100 }), handler);