@chdlabs/my-shield 0.1.3 → 0.3.0

package/src/middleware/behavioralGuard.js

@@ -0,0 +1,304 @@
+/**
+ * @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) {
+        if (this.shield?.ipResolver) {
+            return this.shield.ipResolver.resolve(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.50] Probability threshold for human classification (calibrated to Ridge boundary)
+     * @param {'block'|'audit'|'header-only'} [options.mode='block'] Execution mode: 'block' rejects bots, 'audit' logs and sets headers, 'header-only' sets headers
+     * @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 on missing/malformed telemetry
+     * @param {boolean} [options.autoBlockIP=false] Automatically add detected bot IP to Shield L1 blocklist
+     * @param {Function} [options.onBotDetected] Custom callback for bot detection (in 'block' mode)
+     * @param {Function} [options.onVerdict] Callback invoked for all outcomes: (verdict, req, res) => void
+     */
+    middleware(options = {}) {
+        const {
+            threshold = 0.50,
+            mode = 'block',
+            headerName = 'x-shield-telemetry',
+            replayWindowMs = 15_000,
+            allowFallbackOnError = false,
+            autoBlockIP = false,
+            onBotDetected,
+            onVerdict
+        } = options;
+
+        return (req, res, next) => {
+            const rawHeader = req.headers[headerName] || req.body?._shieldTelemetry;
+
+            const handleVerdict = (verdict) => {
+                if (typeof onVerdict === 'function') {
+                    try {
+                        onVerdict(verdict, req, res);
+                    } catch (e) {
+                        this.logger?.error?.('[SHIELD:BIOMETRICS] Error in onVerdict callback:', e.message);
+                    }
+                }
+            };
+
+            const setVerdictHeader = (isHuman, confidence, score, reason) => {
+                if (res.headersSent) return;
+                const headerVal = isHuman
+                    ? `HUMAN; confidence=${confidence.toFixed(2)}; score=${score.toFixed(2)}`
+                    : `BOT; confidence=${confidence.toFixed(2)}; score=${score.toFixed(2)}; reason=${reason || 'AUTOMATED_KINEMATICS_DETECTED'}`;
+                res.setHeader('X-Shield-Verdict', headerVal);
+            };
+
+            if (!rawHeader) {
+                if (mode === 'audit' || mode === 'header-only') {
+                    if (!res.headersSent) {
+                        res.setHeader('X-Shield-Verdict', 'UNKNOWN; reason=MISSING_TELEMETRY');
+                    }
+                    req.shield = req.shield || {};
+                    req.shield.biometrics = { isHuman: false, missingTelemetry: true };
+                    handleVerdict({ isHuman: false, reason: 'MISSING_TELEMETRY', mode });
+                    return next();
+                }
+
+                if (allowFallbackOnError) return next();
+                handleVerdict({ isHuman: false, reason: 'MISSING_TELEMETRY', mode });
+                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) {
+                    if (mode === 'audit' || mode === 'header-only') {
+                        setVerdictHeader(false, 0, -99, 'SYNTHETIC_EVENT_DISPATCH');
+                        req.shield = req.shield || {};
+                        req.shield.biometrics = { isHuman: false, reason: 'SYNTHETIC_EVENT_DISPATCH' };
+                        handleVerdict({ isHuman: false, reason: 'SYNTHETIC_EVENT_DISPATCH', mode });
+                        return next();
+                    }
+                    if (autoBlockIP && this.shield) {
+                        const ip = this.getClientIP(req);
+                        this.shield.blockIP(ip, 'behavioral_bot_detected', { reason: 'SYNTHETIC_EVENT_DISPATCH' });
+                    }
+                    handleVerdict({ isHuman: false, reason: 'SYNTHETIC_EVENT_DISPATCH', mode });
+                    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) {
+                    if (mode === 'audit' || mode === 'header-only') {
+                        setVerdictHeader(false, 0, -99, 'EXPIRED_OR_FUTURE_TELEMETRY');
+                        req.shield = req.shield || {};
+                        req.shield.biometrics = { isHuman: false, reason: 'EXPIRED_OR_FUTURE_TELEMETRY' };
+                        handleVerdict({ isHuman: false, reason: 'EXPIRED_OR_FUTURE_TELEMETRY', mode });
+                        return next();
+                    }
+                    handleVerdict({ isHuman: false, reason: 'EXPIRED_OR_FUTURE_TELEMETRY', mode });
+                    return this._deny(req, res, 'EXPIRED_OR_FUTURE_TELEMETRY', onBotDetected);
+                }
+
+                // 3. Payload Schema Validation
+                const isMalformed = !Array.isArray(payload.velocity) ||
+                    payload.velocity.length !== this.transformer.windowLength ||
+                    payload.velocity.some(v => typeof v !== 'number' || !Number.isFinite(v));
+
+                if (isMalformed) {
+                    if (mode === 'audit' || mode === 'header-only') {
+                        setVerdictHeader(false, 0, -99, 'MALFORMED_KINEMATICS_VECTOR');
+                        req.shield = req.shield || {};
+                        req.shield.biometrics = { isHuman: false, reason: 'MALFORMED_KINEMATICS_VECTOR' };
+                        handleVerdict({ isHuman: false, reason: 'MALFORMED_KINEMATICS_VECTOR', mode });
+                        return next();
+                    }
+                    handleVerdict({ isHuman: false, reason: 'MALFORMED_KINEMATICS_VECTOR', mode });
+                    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)) {
+                    if (mode === 'audit' || mode === 'header-only') {
+                        setVerdictHeader(false, 0, -99, 'REPLAY_ATTACK_DETECTED');
+                        req.shield = req.shield || {};
+                        req.shield.biometrics = { isHuman: false, reason: 'REPLAY_ATTACK_DETECTED' };
+                        handleVerdict({ isHuman: false, reason: 'REPLAY_ATTACK_DETECTED', mode });
+                        return next();
+                    }
+                    handleVerdict({ isHuman: false, reason: 'REPLAY_ATTACK_DETECTED', mode });
+                    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);
+                const isHuman = outcome.probability >= threshold;
+
+                req.shield = req.shield || {};
+                req.shield.biometrics = {
+                    isHuman,
+                    humanConfidence: outcome.probability,
+                    latencyMs: outcome.latencyMs,
+                    score: outcome.score
+                };
+
+                setVerdictHeader(isHuman, outcome.probability, outcome.score, isHuman ? null : 'AUTOMATED_KINEMATICS_DETECTED');
+
+                const verdictMeta = {
+                    isHuman,
+                    probability: outcome.probability,
+                    score: outcome.score,
+                    latencyMs: outcome.latencyMs,
+                    ip,
+                    mode
+                };
+                handleVerdict(verdictMeta);
+
+                // Record event in Shield core telemetry ring buffer
+                if (this.shield) {
+                    this.shield.recordEvent({
+                        type: isHuman ? 'BIOMETRICS_HUMAN' : (mode === 'block' ? 'BIOMETRICS_BLOCKED' : 'BIOMETRICS_AUDIT'),
+                        ip,
+                        isHuman,
+                        confidence: outcome.probability,
+                        score: outcome.score,
+                        latencyMs: outcome.latencyMs,
+                        mode
+                    });
+                }
+
+                if (mode === 'audit' || mode === 'header-only') {
+                    return next();
+                }
+
+                // mode === 'block'
+                if (!isHuman) {
+                    if (autoBlockIP && this.shield) {
+                        this.shield.blockIP(ip, 'behavioral_bot_detected', {
+                            confidence: outcome.probability,
+                            latencyMs: outcome.latencyMs,
+                            score: outcome.score
+                        });
+                    }
+                    return this._deny(req, res, 'AUTOMATED_KINEMATICS_DETECTED', onBotDetected, outcome);
+                }
+
+                next();
+            } catch (err) {
+                if (mode === 'audit' || mode === 'header-only' || allowFallbackOnError) {
+                    if (!res.headersSent) {
+                        res.setHeader('X-Shield-Verdict', 'UNKNOWN; reason=MALFORMED_TELEMETRY');
+                    }
+                    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
+        });
+    }
+}

package/src/middleware/honeypot.js

@@ -171,10 +171,12 @@ export class Honeypot {
             }
 
             // Extract client IP
-            const ip = (req.headers['x-forwarded-for']?.split(',')[0]?.trim()) ||
-                       req.socket?.remoteAddress ||
-                       req.ip ||
-                       '127.0.0.1';
+            const ip = this.shield?.ipResolver
+                ? this.shield.ipResolver.resolve(req)
+                : ((req.headers['x-forwarded-for']?.split(',')[0]?.trim()) ||
+                   req.socket?.remoteAddress ||
+                   req.ip ||
+                   '127.0.0.1');
 
             const matchedPath = this.normalizePath(req.path);
             const meta = this.routeMetadata.get(matchedPath);

package/src/middleware/notFoundCollector.js

@@ -62,10 +62,12 @@ export class NotFoundCollector {
      * @param {Object} req Express request
      */
     handle404(req) {
-        const ip = (req.headers['x-forwarded-for']?.split(',')[0]?.trim()) ||
-                   req.socket?.remoteAddress ||
-                   req.ip ||
-                   '127.0.0.1';
+        const ip = this.shield?.ipResolver
+            ? this.shield.ipResolver.resolve(req)
+            : ((req.headers['x-forwarded-for']?.split(',')[0]?.trim()) ||
+               req.socket?.remoteAddress ||
+               req.ip ||
+               '127.0.0.1');
 
         const path = req.path || req.originalUrl || '/';
         const userAgent = req.headers['user-agent'] || '';

package/src/middleware/shieldGuard.js

@@ -38,6 +38,9 @@ export class ShieldGuard {
      * @returns {string}
      */
     getClientIP(req) {
+        if (this.shield?.ipResolver) {
+            return this.shield.ipResolver.resolve(req);
+        }
         const forwarded = req.headers['x-forwarded-for'];
         if (forwarded && typeof forwarded === 'string') {
             const first = forwarded.split(',')[0].trim();

package/src/storage/BaseAdapter.js

@@ -0,0 +1,58 @@
+/**
+ * Base Storage Adapter Interface
+ *
+ * Defines the contract for pluggable threat persistence across container
+ * restarts and distributed multi-instance deployments.
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+
+export class BaseStorageAdapter {
+    /**
+     * Initialize adapter with parent Shield instance
+     * @param {Object} shield
+     */
+    async init(shield) {
+        this.shield = shield;
+    }
+
+    /**
+     * Load persisted blocked IPs upon system initialization
+     * @returns {Promise<Array<{ ip: string, reason: string, metadata: object, expiresAt: number|null }>>}
+     */
+    async loadBlockedIPs() {
+        return [];
+    }
+
+    /**
+     * Persist a newly blocked IP threat
+     * @param {string} ip
+     * @param {string} reason
+     * @param {Object} [metadata={}]
+     * @param {number|null} [expiresAt=null]
+     * @returns {Promise<void>}
+     */
+    async saveBlockedIP(ip, reason, metadata = {}, expiresAt = null) {
+        // Subclasses implement persistence
+    }
+
+    /**
+     * Remove an IP threat from persistent storage (unblock)
+     * @param {string} ip
+     * @returns {Promise<void>}
+     */
+    async removeBlockedIP(ip) {
+        // Subclasses implement deletion
+    }
+
+    /**
+     * Clean up timers or connection handles on graceful shutdown
+     * @returns {Promise<void>}
+     */
+    async close() {
+        // Subclasses clean up resources
+    }
+}
+
+export default BaseStorageAdapter;

package/src/storage/CallbackStorageAdapter.js

@@ -0,0 +1,69 @@
+/**
+ * Callback Storage Adapter
+ *
+ * Universal bridge allowing developers to plug any database or caching layer
+ * (PostgreSQL, MySQL, Redis, MongoDB, DynamoDB, Prisma) into Shield
+ * via simple async function callbacks.
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+import { BaseStorageAdapter } from './BaseAdapter.js';
+
+export class CallbackStorageAdapter extends BaseStorageAdapter {
+    /**
+     * @param {Object} options
+     * @param {Function} [options.onLoad] Async function returning Array of { ip, reason, metadata, expiresAt }
+     * @param {Function} [options.onBlock] Async function called when an IP is blocked: (ip, reason, metadata, expiresAt)
+     * @param {Function} [options.onUnblock] Async function called when an IP is unblocked: (ip)
+     * @param {Object} [options.logger]
+     */
+    constructor(options = {}) {
+        super();
+        this.onLoad = options.onLoad || null;
+        this.onBlock = options.onBlock || null;
+        this.onUnblock = options.onUnblock || null;
+        this.logger = options.logger || console;
+    }
+
+    async init(shield) {
+        await super.init(shield);
+    }
+
+    async loadBlockedIPs() {
+        if (typeof this.onLoad !== 'function') {
+            return [];
+        }
+        try {
+            const result = await this.onLoad();
+            return Array.isArray(result) ? result : [];
+        } catch (err) {
+            this.logger.error?.('[SHIELD:STORAGE] Error in custom onLoad storage callback:', err.message);
+            return [];
+        }
+    }
+
+    async saveBlockedIP(ip, reason, metadata = {}, expiresAt = null) {
+        if (typeof this.onBlock !== 'function') return;
+        try {
+            await this.onBlock(ip, reason, metadata, expiresAt);
+        } catch (err) {
+            this.logger.error?.(`[SHIELD:STORAGE] Error in custom onBlock callback for ${ip}:`, err.message);
+        }
+    }
+
+    async removeBlockedIP(ip) {
+        if (typeof this.onUnblock !== 'function') return;
+        try {
+            await this.onUnblock(ip);
+        } catch (err) {
+            this.logger.error?.(`[SHIELD:STORAGE] Error in custom onUnblock callback for ${ip}:`, err.message);
+        }
+    }
+
+    async close() {
+        // No-op for callbacks unless custom teardown needed
+    }
+}
+
+export default CallbackStorageAdapter;

package/src/storage/FileStorageAdapter.js

@@ -0,0 +1,174 @@
+/**
+ * File Storage Adapter
+ *
+ * Persists blocked IP threats and metadata to disk in JSON format.
+ * Employs atomic write operations (tempfile + rename) and debounced flushing
+ * to ensure integrity even during sudden container termination.
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { BaseStorageAdapter } from './BaseAdapter.js';
+
+export class FileStorageAdapter extends BaseStorageAdapter {
+    /**
+     * @param {Object} [options={}]
+     * @param {string} [options.directory='./data/shield']
+     * @param {string} [options.filename='blocked_ips.json']
+     * @param {number} [options.debounceMs=200]
+     * @param {Object} [options.logger]
+     */
+    constructor(options = {}) {
+        super();
+        const baseDir = options.directory || './data/shield';
+        const rawFileName = options.filename || 'blocked_ips.json';
+
+        // Sanitize path against directory traversal
+        const safeFileName = path.basename(rawFileName);
+        this.directory = path.resolve(process.cwd(), baseDir);
+        this.filePath = path.join(this.directory, safeFileName);
+        this.debounceMs = Math.max(0, options.debounceMs ?? 200);
+        this.logger = options.logger || console;
+
+        this.records = new Map();
+        this._flushTimer = null;
+    }
+
+    async init(shield) {
+        await super.init(shield);
+        this._ensureDirectory();
+        await this.loadBlockedIPs();
+    }
+
+    _ensureDirectory() {
+        try {
+            if (!fs.existsSync(this.directory)) {
+                fs.mkdirSync(this.directory, { recursive: true });
+            }
+        } catch (err) {
+            this.logger.error?.(`[SHIELD:STORAGE] Failed to create directory "${this.directory}":`, err.message);
+        }
+    }
+
+    async loadBlockedIPs() {
+        if (!fs.existsSync(this.filePath)) {
+            return [];
+        }
+
+        try {
+            const raw = fs.readFileSync(this.filePath, 'utf8');
+            if (!raw.trim()) return [];
+            const data = JSON.parse(raw);
+            const now = Date.now();
+            const active = [];
+
+            this.records.clear();
+
+            if (Array.isArray(data)) {
+                for (const item of data) {
+                    if (item && item.ip) {
+                        if (!item.expiresAt || item.expiresAt > now) {
+                            this.records.set(item.ip, item);
+                            active.push(item);
+                        }
+                    }
+                }
+            } else if (typeof data === 'object' && data !== null) {
+                // Object format: { "1.2.3.4": { reason, metadata, expiresAt } }
+                for (const [ip, item] of Object.entries(data)) {
+                    if (item) {
+                        const record = { ip, ...item };
+                        if (!record.expiresAt || record.expiresAt > now) {
+                            this.records.set(ip, record);
+                            active.push(record);
+                        }
+                    }
+                }
+            }
+
+            return active;
+        } catch (err) {
+            this.logger.error?.(`[SHIELD:STORAGE] Error loading blocked IPs from "${this.filePath}":`, err.message);
+            return [];
+        }
+    }
+
+    async saveBlockedIP(ip, reason, metadata = {}, expiresAt = null) {
+        if (!ip) return;
+        this.records.set(ip, {
+            ip,
+            reason,
+            metadata,
+            expiresAt,
+            savedAt: Date.now()
+        });
+        this._scheduleFlush();
+    }
+
+    async removeBlockedIP(ip) {
+        if (!ip) return;
+        if (this.records.delete(ip)) {
+            this._scheduleFlush();
+        }
+    }
+
+    _scheduleFlush() {
+        if (this.debounceMs === 0) {
+            this.flushSync();
+            return;
+        }
+
+        if (this._flushTimer) return;
+        this._flushTimer = setTimeout(() => {
+            this._flushTimer = null;
+            this.flushSync();
+        }, this.debounceMs);
+
+        if (typeof this._flushTimer.unref === 'function') {
+            this._flushTimer.unref();
+        }
+    }
+
+    /**
+     * Flush memory records to disk atomically
+     */
+    flushSync() {
+        if (this._flushTimer) {
+            clearTimeout(this._flushTimer);
+            this._flushTimer = null;
+        }
+
+        this._ensureDirectory();
+
+        const now = Date.now();
+        const exportArray = [];
+        for (const [ip, item] of this.records.entries()) {
+            if (item.expiresAt && item.expiresAt <= now) {
+                this.records.delete(ip);
+            } else {
+                exportArray.push(item);
+            }
+        }
+
+        const tempPath = `${this.filePath}.tmp.${Date.now()}`;
+        try {
+            fs.writeFileSync(tempPath, JSON.stringify(exportArray, null, 2), 'utf8');
+            fs.renameSync(tempPath, this.filePath);
+        } catch (err) {
+            this.logger.error?.(`[SHIELD:STORAGE] Failed writing blocked IPs to "${this.filePath}":`, err.message);
+            try {
+                if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath);
+            } catch {
+                // Ignore cleanup error
+            }
+        }
+    }
+
+    async close() {
+        this.flushSync();
+    }
+}
+
+export default FileStorageAdapter;