@chdlabs/my-shield 0.2.0 → 0.3.1

package/src/middleware/behavioralGuard.js

@@ -76,12 +76,58 @@ export class BehavioralShieldService {
         return { ...result, latencyMs: latency };
     }
 
+    /**
+     * Evaluate mobile tap dwell kinetics against human physiological tap distribution
+     * @param {number} dwellMs Tap contact duration in milliseconds
+     * @returns {{ score: number, probability: number, isHuman: boolean, latencyMs: number, reason?: string }}
+     */
+    verifyTapDwell(dwellMs) {
+        const t0 = performance.now();
+        if (typeof dwellMs !== 'number' || !Number.isFinite(dwellMs) || dwellMs < 20) {
+            return {
+                score: -2.5,
+                probability: 0.05,
+                isHuman: false,
+                latencyMs: +(performance.now() - t0).toFixed(2),
+                reason: 'BOT_INSTANT_TAP'
+            };
+        }
+        if (dwellMs > 1500) {
+            return {
+                score: -1.2,
+                probability: 0.20,
+                isHuman: false,
+                latencyMs: +(performance.now() - t0).toFixed(2),
+                reason: 'ABNORMAL_TAP_DWELL'
+            };
+        }
+
+        // Calibrated log-normal human tap distribution (mean = ~90ms, std = 0.55)
+        const logVal = Math.log(dwellMs);
+        const mean = Math.log(90);
+        const std = 0.55;
+        const z = (logVal - mean) / std;
+        const score = +(2.0 - 0.8 * Math.abs(z)).toFixed(2);
+        const probability = +(1 / (1 + Math.exp(-score))).toFixed(2);
+        const latency = +(performance.now() - t0).toFixed(2);
+
+        return {
+            score,
+            probability,
+            isHuman: probability >= 0.50,
+            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();
@@ -93,28 +139,61 @@ export class BehavioralShieldService {
     /**
      * Express middleware factory
      * @param {Object} [options={}]
-     * @param {number} [options.threshold=0.70] Probability threshold for human classification
+     * @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
+     * @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
+     * @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.70,
+            threshold = 0.50,
+            mode = 'block',
             headerName = 'x-shield-telemetry',
             replayWindowMs = 15_000,
             allowFallbackOnError = false,
             autoBlockIP = false,
-            onBotDetected
+            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 || typeof res.setHeader !== 'function') 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);
             }
 
@@ -123,70 +202,139 @@ export class BehavioralShieldService {
 
                 // 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
-                if (!Array.isArray(payload.velocity) || payload.velocity.length !== this.transformer.windowLength) {
-                    return this._deny(req, res, 'MALFORMED_KINEMATICS_VECTOR', onBotDetected);
-                }
+                const isMalformed = !Array.isArray(payload.velocity) ||
+                    payload.velocity.length !== this.transformer.windowLength ||
+                    payload.velocity.some(v => typeof v !== 'number' || !Number.isFinite(v));
 
-                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);
+                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);
+                // 5. Kinematics Scoring (MiniRocket or Touch Tap Dwell)
+                const isTap = payload.source === 'tap' && typeof payload.dwellMs === 'number';
+                const outcome = isTap ? this.verifyTapDwell(payload.dwellMs) : this.verify(payload.velocity);
                 const ip = this.getClientIP(req);
+                const isHuman = outcome.probability >= threshold;
+                const failReason = outcome.reason || 'AUTOMATED_KINEMATICS_DETECTED';
 
                 req.shield = req.shield || {};
                 req.shield.biometrics = {
-                    isHuman: outcome.probability >= threshold,
+                    isHuman,
                     humanConfidence: outcome.probability,
                     latencyMs: outcome.latencyMs,
-                    score: outcome.score
+                    score: outcome.score,
+                    pointerType: payload.pointerType || 'mouse',
+                    source: payload.source || 'trajectory'
                 };
 
-                // Record event in Shield core if attached
+                setVerdictHeader(isHuman, outcome.probability, outcome.score, isHuman ? null : failReason);
+
+                const verdictMeta = {
+                    isHuman,
+                    probability: outcome.probability,
+                    score: outcome.score,
+                    latencyMs: outcome.latencyMs,
+                    pointerType: payload.pointerType || 'mouse',
+                    source: payload.source || 'trajectory',
+                    ip,
+                    mode
+                };
+                handleVerdict(verdictMeta);
+
+                // Record event in Shield core telemetry ring buffer
                 if (this.shield) {
                     this.shield.recordEvent({
-                        type: 'BIOMETRICS_VERIFIED',
+                        type: isHuman ? 'BIOMETRICS_HUMAN' : (mode === 'block' ? 'BIOMETRICS_BLOCKED' : 'BIOMETRICS_AUDIT'),
                         ip,
-                        isHuman: outcome.probability >= threshold,
+                        isHuman,
                         confidence: outcome.probability,
-                        latencyMs: outcome.latencyMs
+                        score: outcome.score,
+                        latencyMs: outcome.latencyMs,
+                        pointerType: payload.pointerType || 'mouse',
+                        source: payload.source || 'trajectory',
+                        mode
                     });
                 }
 
-                if (outcome.probability < threshold) {
+                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
+                            latencyMs: outcome.latencyMs,
+                            score: outcome.score,
+                            reason: failReason,
+                            pointerType: payload.pointerType || 'mouse'
                         });
                     }
-                    return this._deny(req, res, 'AUTOMATED_KINEMATICS_DETECTED', onBotDetected, outcome);
+                    return this._deny(req, res, failReason, onBotDetected, outcome);
                 }
 
                 next();
             } catch (err) {
-                if (allowFallbackOnError) return next();
+                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' });
             }
         };

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;