@chdlabs/my-shield 0.1.2 → 0.2.0

package/src/middleware/behavioralGuard.js

@@ -0,0 +1,209 @@
+/**
+ * @file src/middleware/behavioralGuard.js
+ * Behavioral Biometrics Express Middleware
+ * Evaluates pointer kinematics telemetry against MiniRocket + Dual Ridge model.
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { MiniRocket } from '../biometrics/minirocket.js';
+import { DualRidgeClassifier } from '../biometrics/ridge.js';
+import { LRUCache } from '../core/lruCache.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export class BehavioralShieldService {
+    /**
+     * @param {Object} [options={}]
+     * @param {Object} [options.modelWeights] Custom model weights { thresholds, weights, bias }
+     * @param {Object} [options.shield] Shield instance
+     * @param {Object} [options.logger=console] Logger instance
+     */
+    constructor({ modelWeights = null, shield = null, logger = console } = {}) {
+        this.shield = shield;
+        this.logger = logger;
+
+        let weights = modelWeights;
+        if (!weights) {
+            try {
+                const defaultWeightsPath = path.resolve(__dirname, '../../models/default-weights.json');
+                if (fs.existsSync(defaultWeightsPath)) {
+                    weights = JSON.parse(fs.readFileSync(defaultWeightsPath, 'utf8'));
+                }
+            } catch (err) {
+                this.logger?.warn?.('[SHIELD:BIOMETRICS] Could not load default-weights.json:', err.message);
+            }
+        }
+
+        const featureCount = weights?.weights?.length || 336;
+        const windowLength = weights?.windowLength || 128;
+
+        this.transformer = new MiniRocket(windowLength, featureCount);
+        if (weights?.thresholds) {
+            this.transformer.loadThresholds(weights.thresholds);
+        }
+
+        this.classifier = new DualRidgeClassifier();
+        if (weights?.weights) {
+            this.classifier.loadWeights(weights.weights, weights.bias || 0.0);
+        }
+
+        // Bounded LRU cache for replay nonce protection (eliminates memory leaks)
+        this.nonceCache = new LRUCache({
+            maxSize: 10_000,
+            ttlMs: 60_000
+        });
+    }
+
+    /**
+     * Verify a 128-sample velocity vector
+     * @param {number[]|Float64Array} velocityArray
+     * @returns {{ score: number, probability: number, isHuman: boolean, latencyMs: number }}
+     */
+    verify(velocityArray) {
+        const t0 = performance.now();
+        const series = Float64Array.from(velocityArray);
+        const features = this.transformer.transform(series);
+        const result = this.classifier.predict(features);
+        const latency = +(performance.now() - t0).toFixed(2);
+
+        return { ...result, latencyMs: latency };
+    }
+
+    /**
+     * 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 factory
+     * @param {Object} [options={}]
+     * @param {number} [options.threshold=0.70] Probability threshold for human classification
+     * @param {string} [options.headerName='x-shield-telemetry'] Header name for telemetry JSON
+     * @param {number} [options.replayWindowMs=15000] Maximum acceptable age/future drift in ms
+     * @param {boolean} [options.allowFallbackOnError=false] Fail-open vs fail-closed
+     * @param {boolean} [options.autoBlockIP=false] Automatically add detected bot IP to Shield L1 blocklist
+     * @param {Function} [options.onBotDetected] Custom callback for bot detection
+     */
+    middleware(options = {}) {
+        const {
+            threshold = 0.70,
+            headerName = 'x-shield-telemetry',
+            replayWindowMs = 15_000,
+            allowFallbackOnError = false,
+            autoBlockIP = false,
+            onBotDetected
+        } = options;
+
+        return (req, res, next) => {
+            const rawHeader = req.headers[headerName] || req.body?._shieldTelemetry;
+
+            if (!rawHeader) {
+                if (allowFallbackOnError) return next();
+                return this._deny(req, res, 'MISSING_TELEMETRY', onBotDetected);
+            }
+
+            try {
+                const payload = typeof rawHeader === 'string' ? JSON.parse(rawHeader) : rawHeader;
+
+                // 1. Synthetic Dispatch Check
+                if (payload.isTrusted === false) {
+                    return this._deny(req, res, 'SYNTHETIC_EVENT_DISPATCH', onBotDetected);
+                }
+
+                // 2. Replay Protection Window Check
+                const now = Date.now();
+                if (!payload.timestamp || typeof payload.timestamp !== 'number' || Math.abs(now - payload.timestamp) > replayWindowMs) {
+                    return this._deny(req, res, 'EXPIRED_OR_FUTURE_TELEMETRY', onBotDetected);
+                }
+
+                // 3. Payload Schema Validation
+                if (!Array.isArray(payload.velocity) || payload.velocity.length !== this.transformer.windowLength) {
+                    return this._deny(req, res, 'MALFORMED_KINEMATICS_VECTOR', onBotDetected);
+                }
+
+                for (let i = 0; i < payload.velocity.length; i++) {
+                    const val = payload.velocity[i];
+                    if (typeof val !== 'number' || !Number.isFinite(val)) {
+                        return this._deny(req, res, 'MALFORMED_KINEMATICS_VECTOR', onBotDetected);
+                    }
+                }
+
+                // 4. Coordinate Signature Nonce Check
+                const nonce = crypto.createHash('sha256').update(JSON.stringify(payload.velocity)).digest('hex');
+                if (this.nonceCache.has(nonce)) {
+                    return this._deny(req, res, 'REPLAY_ATTACK_DETECTED', onBotDetected);
+                }
+                this.nonceCache.set(nonce, true, replayWindowMs);
+
+                // 5. MiniRocket & Dual Ridge Scoring
+                const outcome = this.verify(payload.velocity);
+                const ip = this.getClientIP(req);
+
+                req.shield = req.shield || {};
+                req.shield.biometrics = {
+                    isHuman: outcome.probability >= threshold,
+                    humanConfidence: outcome.probability,
+                    latencyMs: outcome.latencyMs,
+                    score: outcome.score
+                };
+
+                // Record event in Shield core if attached
+                if (this.shield) {
+                    this.shield.recordEvent({
+                        type: 'BIOMETRICS_VERIFIED',
+                        ip,
+                        isHuman: outcome.probability >= threshold,
+                        confidence: outcome.probability,
+                        latencyMs: outcome.latencyMs
+                    });
+                }
+
+                if (outcome.probability < threshold) {
+                    if (autoBlockIP && this.shield) {
+                        this.shield.blockIP(ip, 'behavioral_bot_detected', {
+                            confidence: outcome.probability,
+                            latencyMs: outcome.latencyMs
+                        });
+                    }
+                    return this._deny(req, res, 'AUTOMATED_KINEMATICS_DETECTED', onBotDetected, outcome);
+                }
+
+                next();
+            } catch (err) {
+                if (allowFallbackOnError) return next();
+                res.status(400).json({ error: 'Malformed telemetry packet', code: 'MALFORMED_TELEMETRY' });
+            }
+        };
+    }
+
+    /**
+     * Handle blocked request
+     * @private
+     */
+    _deny(req, res, reason, customHandler, meta = {}) {
+        if (customHandler && typeof customHandler === 'function') {
+            return customHandler(req, res, { reason, ...meta });
+        }
+        return res.status(403).json({
+            status: 'BLOCKED',
+            shieldCode: reason,
+            details: meta
+        });
+    }
+}