@chdlabs/my-shield 0.1.3 → 0.2.0

package/src/biometrics/index.js

@@ -0,0 +1,10 @@
+/**
+ * @file src/biometrics/index.js
+ * Behavioral Biometrics Engine Exports
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+
+export { MiniRocket } from './minirocket.js';
+export { DualRidgeClassifier } from './ridge.js';

package/src/biometrics/minirocket.js

@@ -0,0 +1,213 @@
+/**
+ * @file src/biometrics/minirocket.js
+ * Deterministic MiniRocket 1D Transform Engine
+ * High-performance, zero-dependency feature extractor using 84 fixed length-9 kernels
+ * with binary/ternary weights {-1, 2} and proportion of positive values (PPV).
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+
+const MR_KERNEL_LENGTH = 9;
+const MR_NUM_KERNELS = 84;
+
+export class MiniRocket {
+    /**
+     * @param {number} [windowLength=128] Length of the input kinematic series
+     * @param {number} [numFeatures=500] Number of MiniRocket PPV features to extract
+     */
+    constructor(windowLength = 128, numFeatures = 500) {
+        this.windowLength = windowLength;
+        this.targetFeatures = numFeatures;
+
+        this.kernelIndices = this._buildIndices();
+        this.dilations = this._buildDilations();
+        this.featureMap = this._buildFeatureMap();
+        this.thresholds = null;
+
+        // Pre-allocated scratch buffers to eliminate per-inference GC allocations
+        this._ca = new Float64Array(this.windowLength);
+        this._cg = new Float64Array(MR_KERNEL_LENGTH * this.windowLength);
+        this._c = new Float64Array(this.windowLength);
+    }
+
+    /**
+     * Build all C(9, 3) = 84 combinations of 3 positive kernel indices
+     * @private
+     */
+    _buildIndices() {
+        const indices = new Int32Array(MR_NUM_KERNELS * 3);
+        let p = 0;
+        for (let a = 0; a < MR_KERNEL_LENGTH; a++) {
+            for (let b = a + 1; b < MR_KERNEL_LENGTH; b++) {
+                for (let c = b + 1; c < MR_KERNEL_LENGTH; c++) {
+                    indices[p * 3 + 0] = a;
+                    indices[p * 3 + 1] = b;
+                    indices[p * 3 + 2] = c;
+                    p++;
+                }
+            }
+        }
+        return indices;
+    }
+
+    /**
+     * Compute multi-scale dilation schedule
+     * @private
+     */
+    _buildDilations() {
+        const maxExp = Math.log2((this.windowLength - 1) / (MR_KERNEL_LENGTH - 1));
+        const maxDilations = Math.min(32, Math.floor(this.targetFeatures / MR_NUM_KERNELS));
+        const dilations = [];
+
+        for (let i = 0; i < maxDilations; i++) {
+            const exponent = (i === maxDilations - 1) ? maxExp : (i * maxExp) / (maxDilations - 1);
+            const d = Math.floor(Math.pow(2, exponent));
+            if (!dilations.includes(d) && d >= 1) {
+                dilations.push(d);
+            }
+        }
+        return Int32Array.from(dilations);
+    }
+
+    /**
+     * Map feature indices to kernel index, dilation, and golden ratio quantile
+     * @private
+     */
+    _buildFeatureMap() {
+        const map = [];
+        const phi = (Math.sqrt(5) + 1) / 2;
+        let count = 0;
+
+        for (const d of this.dilations) {
+            for (let k = 0; k < MR_NUM_KERNELS; k++) {
+                if (count >= this.targetFeatures) break;
+                map.push({ kernelIdx: k, dilation: d, quantile: (count * phi) % 1.0 });
+                count++;
+            }
+            if (count >= this.targetFeatures) break;
+        }
+        return map;
+    }
+
+    /**
+     * Shared prefix sum computation across all kernels sharing dilation d
+     * @private
+     */
+    _convolveBase(x, d) {
+        const L = this.windowLength;
+        const padding = Math.floor(((MR_KERNEL_LENGTH - 1) * d) / 2);
+        const mid = Math.floor(MR_KERNEL_LENGTH / 2);
+
+        this._ca.fill(0);
+        this._cg.fill(0);
+
+        for (let i = 0; i < L; i++) {
+            this._ca[i] = -x[i];
+            this._cg[mid * L + i] = 3.0 * x[i];
+        }
+
+        let end = L - padding;
+        for (let g = 0; g < mid; g++) {
+            const e = Math.min(end, L);
+            if (e > 0) {
+                const off = L - e;
+                for (let j = 0; j < e; j++) {
+                    this._ca[off + j] -= x[j];
+                    this._cg[g * L + off + j] = 3.0 * x[j];
+                }
+            }
+            end += d;
+        }
+
+        let start = d;
+        for (let g = mid + 1; g < MR_KERNEL_LENGTH; g++) {
+            const m = L - start;
+            for (let j = 0; j < m; j++) {
+                this._ca[j] -= x[start + j];
+                this._cg[g * L + j] = 3.0 * x[start + j];
+            }
+            start += d;
+        }
+    }
+
+    /**
+     * Evaluate kernel output using precomputed prefix sums and 3 index lookups
+     * @private
+     */
+    _kernelOut(kernelIdx) {
+        const L = this.windowLength;
+        const i0 = this.kernelIndices[kernelIdx * 3 + 0] * L;
+        const i1 = this.kernelIndices[kernelIdx * 3 + 1] * L;
+        const i2 = this.kernelIndices[kernelIdx * 3 + 2] * L;
+
+        for (let i = 0; i < L; i++) {
+            this._c[i] = this._ca[i] + this._cg[i0 + i] + this._cg[i1 + i] + this._cg[i2 + i];
+        }
+    }
+
+    /**
+     * Load pre-computed bias thresholds
+     * @param {number[]|Float32Array} thresholdsArray
+     */
+    loadThresholds(thresholdsArray) {
+        this.thresholds = Float32Array.from(thresholdsArray);
+    }
+
+    /**
+     * Fit bias thresholds from a collection of training series
+     * @param {Array<number[]|Float64Array>} trainingWindows
+     */
+    fit(trainingWindows) {
+        const N = trainingWindows.length;
+        if (N === 0) throw new Error('Training windows cannot be empty.');
+        this.thresholds = new Float32Array(this.featureMap.length);
+
+        for (let f = 0; f < this.featureMap.length; f++) {
+            const feat = this.featureMap[f];
+            this._convolveBase(trainingWindows[f % N], feat.dilation);
+            this._kernelOut(feat.kernelIdx);
+
+            const sorted = Float64Array.from(this._c).sort();
+            const qIdx = Math.min(this.windowLength - 1, Math.floor(feat.quantile * this.windowLength));
+            this.thresholds[f] = sorted[qIdx];
+        }
+    }
+
+    /**
+     * Transform a 1D input series into Proportion of Positive Values (PPV) representation
+     * @param {number[]|Float64Array} series Equispaced series of length equal to windowLength
+     * @returns {Float32Array} PPV feature vector
+     */
+    transform(series) {
+        if (!this.thresholds) {
+            throw new Error('MiniRocket requires fitted or loaded thresholds.');
+        }
+        if (series.length !== this.windowLength) {
+            throw new Error(`Input series length (${series.length}) must match windowLength (${this.windowLength}).`);
+        }
+
+        const out = new Float32Array(this.featureMap.length);
+        let currentDilation = -1;
+
+        for (let f = 0; f < this.featureMap.length; f++) {
+            const feat = this.featureMap[f];
+
+            if (feat.dilation !== currentDilation) {
+                this._convolveBase(series, feat.dilation);
+                currentDilation = feat.dilation;
+            }
+
+            this._kernelOut(feat.kernelIdx);
+
+            const thresh = this.thresholds[f];
+            let pos = 0;
+            for (let i = 0; i < this.windowLength; i++) {
+                if (this._c[i] > thresh) pos++;
+            }
+            out[f] = pos / this.windowLength;
+        }
+
+        return out;
+    }
+}

package/src/biometrics/ridge.js

@@ -0,0 +1,144 @@
+/**
+ * @file src/biometrics/ridge.js
+ * Dual Regularized Ridge Regression Solver with Cholesky Decomposition
+ * Solves ridge regression in dual space when feature dimension P >> N, recovering
+ * primal weights for O(P) single dot-product inference latency.
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+
+export class DualRidgeClassifier {
+    /**
+     * @param {number} [alpha=10.0] L2 regularization strength
+     */
+    constructor(alpha = 10.0) {
+        this.alpha = alpha;
+        this.weights = null;
+        this.bias = 0.0;
+    }
+
+    /**
+     * Load pre-fitted weights and bias
+     * @param {number[]|Float32Array} weightsArray
+     * @param {number} [bias=0.0]
+     */
+    loadWeights(weightsArray, bias = 0.0) {
+        this.weights = Float32Array.from(weightsArray);
+        this.bias = bias;
+    }
+
+    /**
+     * Fit Dual Ridge classifier from feature matrix X and labels y
+     * @param {Array<Float32Array|number[]>} X Feature matrix (N samples x P features)
+     * @param {number[]} y Target labels (-1 for bot, +1 for human)
+     */
+    fit(X, y) {
+        const N = X.length;
+        if (N === 0) throw new Error('Training data X cannot be empty.');
+        const P = X[0].length;
+
+        let meanY = 0;
+        for (let i = 0; i < N; i++) meanY += y[i];
+        meanY /= N;
+        this.bias = meanY;
+
+        // Gram Matrix K = X * X^T + alpha * I
+        const K = Array.from({ length: N }, () => new Float64Array(N));
+        for (let i = 0; i < N; i++) {
+            for (let j = i; j < N; j++) {
+                let dot = 0;
+                for (let k = 0; k < P; k++) dot += X[i][k] * X[j][k];
+                K[i][j] = dot;
+                K[j][i] = dot;
+            }
+            K[i][i] += this.alpha;
+        }
+
+        // Cholesky Solve L * L^T * beta = (y - meanY)
+        const yC = y.map(v => v - this.bias);
+        const beta = this._choleskySolve(K, yC);
+
+        // Primal Recovery w = X^T * beta
+        this.weights = new Float32Array(P);
+        for (let j = 0; j < P; j++) {
+            let sum = 0;
+            for (let i = 0; i < N; i++) sum += beta[i] * X[i][j];
+            this.weights[j] = sum;
+        }
+
+        // Exact intercept b = mean(y) - w^T * mean(X)
+        let wMeanX = 0;
+        for (let j = 0; j < P; j++) {
+            let meanX_j = 0;
+            for (let i = 0; i < N; i++) meanX_j += X[i][j];
+            meanX_j /= N;
+            wMeanX += this.weights[j] * meanX_j;
+        }
+        this.bias = meanY - wMeanX;
+    }
+
+    /**
+     * Predict human classification probability for a feature vector
+     * @param {Float32Array|number[]} features
+     * @returns {{ score: number, probability: number, isHuman: boolean }}
+     */
+    predict(features) {
+        if (!this.weights) {
+            throw new Error('DualRidgeClassifier requires fitted or loaded weights.');
+        }
+
+        let score = this.bias;
+        const P = this.weights.length;
+        for (let i = 0; i < P; i++) {
+            score += this.weights[i] * features[i];
+        }
+
+        // Sigmoid mapping: P(Human) = 1 / (1 + exp(-score))
+        const probability = 1 / (1 + Math.exp(-Math.max(-50, Math.min(50, score))));
+        return {
+            score,
+            probability,
+            isHuman: score >= 0
+        };
+    }
+
+    /**
+     * Solve A * x = b via Cholesky decomposition A = L * L^T
+     * @private
+     */
+    _choleskySolve(A, b) {
+        const n = b.length;
+        const L = Array.from({ length: n }, () => new Float64Array(n));
+
+        for (let i = 0; i < n; i++) {
+            for (let j = 0; j <= i; j++) {
+                let sum = 0;
+                for (let k = 0; k < j; k++) sum += L[i][k] * L[j][k];
+                if (i === j) {
+                    const val = A[i][i] - sum;
+                    L[i][j] = Math.sqrt(val > 0 ? val : 1e-9);
+                } else {
+                    L[i][j] = (A[i][j] - sum) / L[j][j];
+                }
+            }
+        }
+
+        // Forward solve: L * z = b
+        const z = new Float64Array(n);
+        for (let i = 0; i < n; i++) {
+            let sum = 0;
+            for (let k = 0; k < i; k++) sum += L[i][k] * z[k];
+            z[i] = (b[i] - sum) / L[i][i];
+        }
+
+        // Back substitution: L^T * x = z
+        const x = new Float64Array(n);
+        for (let i = n - 1; i >= 0; i--) {
+            let sum = 0;
+            for (let k = i + 1; k < n; k++) sum += L[k][i] * x[k];
+            x[i] = (z[i] - sum) / L[i][i];
+        }
+        return x;
+    }
+}

package/src/client/collector.js

@@ -0,0 +1,117 @@
+/**
+ * @file src/client/collector.js
+ * Browser Client Kinematics Telemetry Collector
+ * Captures pointer dynamics and normalizes trajectories to equispaced kinematic series
+ * for behavioral biometric classification. Zero external dependencies.
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+
+export class MouseTelemetryCollector {
+    /**
+     * @param {Object} [options={}]
+     * @param {number} [options.windowLength=128] Number of equispaced time points
+     * @param {number} [options.sampleIntervalMs=10] Equispaced time delta (10ms = 100Hz)
+     * @param {number} [options.maxBufferSize=500] Raw event sliding buffer size
+     */
+    constructor(options = {}) {
+        this.windowLength = options.windowLength || 128;
+        this.sampleIntervalMs = options.sampleIntervalMs || 10;
+        this.maxBufferSize = options.maxBufferSize || 500;
+        this.buffer = [];
+        this.isListening = false;
+        this._onMove = this._onMove.bind(this);
+    }
+
+    /**
+     * Start capturing mouse movement events
+     */
+    start() {
+        if (this.isListening || typeof window === 'undefined') return;
+        window.addEventListener('mousemove', this._onMove, { passive: true });
+        this.isListening = true;
+    }
+
+    /**
+     * Stop capturing mouse movement events
+     */
+    stop() {
+        if (!this.isListening || typeof window === 'undefined') return;
+        window.removeEventListener('mousemove', this._onMove);
+        this.isListening = false;
+    }
+
+    /**
+     * Event listener callback
+     * @private
+     */
+    _onMove(e) {
+        this.buffer.push({
+            x: e.clientX,
+            y: e.clientY,
+            t: typeof performance !== 'undefined' ? performance.now() : Date.now(),
+            trusted: e.isTrusted !== false
+        });
+
+        if (this.buffer.length > this.maxBufferSize) {
+            this.buffer.shift();
+        }
+    }
+
+    /**
+     * Resamples trajectory to fixed length and derives kinematic velocity vector.
+     * @returns {{ velocity: number[], isTrusted: boolean, timestamp: number } | null}
+     */
+    getPayload() {
+        const requiredDuration = this.windowLength * this.sampleIntervalMs;
+        if (this.buffer.length < 10) return null;
+
+        const latest = this.buffer[this.buffer.length - 1];
+        const threshold = latest.t - requiredDuration;
+        const points = this.buffer.filter(p => p.t >= threshold);
+
+        if (points.length < 8) return null;
+
+        // Check synthetic dispatch
+        const allTrusted = points.every(p => p.trusted === true);
+
+        const startTime = points[0].t;
+        const L = this.windowLength;
+        const dt = this.sampleIntervalMs;
+
+        const resampledX = new Float64Array(L);
+        const resampledY = new Float64Array(L);
+        let rawIdx = 0;
+
+        // 1. Equispaced linear interpolation
+        for (let i = 0; i < L; i++) {
+            const targetT = startTime + i * dt;
+            while (rawIdx < points.length - 2 && points[rawIdx + 1].t < targetT) {
+                rawIdx++;
+            }
+            const p0 = points[rawIdx];
+            const p1 = points[Math.min(rawIdx + 1, points.length - 1)];
+            const segmentDt = p1.t - p0.t;
+            const alpha = segmentDt > 0 ? Math.min(Math.max((targetT - p0.t) / segmentDt, 0), 1) : 0;
+
+            resampledX[i] = p0.x + alpha * (p1.x - p0.x);
+            resampledY[i] = p0.y + alpha * (p1.y - p0.y);
+        }
+
+        // 2. Velocity Derivation
+        const velocity = new Float64Array(L);
+        for (let i = 1; i < L; i++) {
+            const dx = resampledX[i] - resampledX[i - 1];
+            const dy = resampledY[i] - resampledY[i - 1];
+            velocity[i] = Math.hypot(dx, dy) / dt;
+        }
+        velocity[0] = velocity[1];
+
+        return {
+            velocity: Array.from(velocity),
+            isTrusted: allTrusted,
+            timestamp: Date.now()
+        };
+    }
+}

package/src/client/index.js

@@ -0,0 +1,67 @@
+/**
+ * @file src/client/index.js
+ * Browser Client Suite for @chdlabs/my-shield
+ * Exports behavioral biometrics kinematics collector and DOM tripwire decoy.
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+
+export { MouseTelemetryCollector } from './collector.js';
+
+/**
+ * Injects invisible DOM tripwire decoy forms and links to trap automated scrapers
+ */
+export function injectTripwire() {
+    if (typeof document === 'undefined') return;
+
+    const trapContainer = document.createElement('div');
+    trapContainer.setAttribute('aria-hidden', 'true');
+    trapContainer.style.position = 'absolute';
+    trapContainer.style.left = '-9999px';
+    trapContainer.style.top = '-9999px';
+    trapContainer.style.width = '1px';
+    trapContainer.style.height = '1px';
+    trapContainer.style.overflow = 'hidden';
+    trapContainer.style.opacity = '0';
+    trapContainer.style.pointerEvents = 'none';
+
+    // Decoy form
+    const form = document.createElement('form');
+    form.setAttribute('method', 'POST');
+    form.setAttribute('action', '/api/__shield_trap');
+
+    const inputUser = document.createElement('input');
+    inputUser.setAttribute('type', 'text');
+    inputUser.setAttribute('name', 'admin_override');
+    inputUser.setAttribute('tabindex', '-1');
+    inputUser.setAttribute('autocomplete', 'off');
+
+    const inputPass = document.createElement('input');
+    inputPass.setAttribute('type', 'password');
+    inputPass.setAttribute('name', 'debug_pass');
+    inputPass.setAttribute('tabindex', '-1');
+
+    form.appendChild(inputUser);
+    form.appendChild(inputPass);
+    trapContainer.appendChild(form);
+
+    // Decoy link
+    const link = document.createElement('a');
+    link.setAttribute('href', '/api/__shield_trap');
+    link.setAttribute('rel', 'nofollow');
+    link.setAttribute('tabindex', '-1');
+    link.textContent = 'Admin Console';
+    trapContainer.appendChild(link);
+
+    document.body.appendChild(trapContainer);
+}
+
+// Auto-inject if document is available and ready
+if (typeof document !== 'undefined') {
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', injectTripwire);
+    } else {
+        injectTripwire();
+    }
+}

package/src/index.d.ts

@@ -47,12 +47,39 @@ export interface AdminOptions {
     enabled?: boolean;
 }
 
+export interface BehavioralGuardOptions {
+    threshold?: number;
+    headerName?: string;
+    replayWindowMs?: number;
+    allowFallbackOnError?: boolean;
+    autoBlockIP?: boolean;
+    onBotDetected?: (req: any, res: any, meta: any) => void;
+}
+
+export interface BiometricsOptions {
+    modelWeights?: {
+        thresholds: number[];
+        weights: number[];
+        bias: number;
+        windowLength?: number;
+        numFeatures?: number;
+    } | null;
+}
+
+export interface BehavioralVerificationResult {
+    score: number;
+    probability: number;
+    isHuman: boolean;
+    latencyMs: number;
+}
+
 export interface ShieldOptions {
     whitelist?: string[];
     bloom?: BloomOptions;
     lru?: LRUOptions;
     honeypot?: HoneypotOptions;
     intelligence?: IntelligenceOptions;
+    biometrics?: BiometricsOptions;
     admin?: AdminOptions;
     blockStatusCode?: number;
     logger?: {
@@ -82,6 +109,8 @@ export class Shield extends EventEmitter {
     adminRouter(options?: AdminRouterOptions): Router;
     costThrottle(options?: CostThrottleOptions): RequestHandler;
     keyLeakDetector(): RequestHandler;
+    behavioralGuard(options?: BehavioralGuardOptions): RequestHandler;
+    verifyBiometrics(velocity: number[] | Float64Array): BehavioralVerificationResult;
 
     blockIP(ip: string, reason?: string, metadata?: Record<string, any>, customTtlMs?: number | null): void;
     unblockIP(ip: string): void;
@@ -99,5 +128,36 @@ export class Shield extends EventEmitter {
     shutdown(): Promise<void>;
 }
 
+export class MiniRocket {
+    windowLength: number;
+    targetFeatures: number;
+    thresholds: Float32Array | null;
+    constructor(windowLength?: number, numFeatures?: number);
+    loadThresholds(thresholdsArray: number[] | Float32Array): void;
+    fit(trainingWindows: Array<number[] | Float64Array>): void;
+    transform(series: number[] | Float64Array): Float32Array;
+}
+
+export class DualRidgeClassifier {
+    alpha: number;
+    weights: Float32Array | null;
+    bias: number;
+    constructor(alpha?: number);
+    loadWeights(weightsArray: number[] | Float32Array, bias?: number): void;
+    fit(X: Array<Float32Array | number[]>, y: number[]): void;
+    predict(features: Float32Array | number[]): { score: number; probability: number; isHuman: boolean };
+}
+
+export class MouseTelemetryCollector {
+    windowLength: number;
+    sampleIntervalMs: number;
+    maxBufferSize: number;
+    constructor(options?: { windowLength?: number; sampleIntervalMs?: number; maxBufferSize?: number });
+    start(): void;
+    stop(): void;
+    getPayload(): { velocity: number[]; isTrusted: boolean; timestamp: number } | null;
+}
+
+export function injectTripwire(): void;
 export function createShield(options?: ShieldOptions): Shield;
 export default createShield;

package/src/index.js

@@ -17,6 +17,9 @@ import { NotFoundCollector } from './middleware/notFoundCollector.js';
 import { ShieldGuard } from './middleware/shieldGuard.js';
 import { CostThrottle } from './middleware/costThrottle.js';
 import { KeyLeakDetector } from './middleware/keyLeakDetector.js';
+import { BehavioralShieldService } from './middleware/behavioralGuard.js';
+import { MiniRocket } from './biometrics/minirocket.js';
+import { DualRidgeClassifier } from './biometrics/ridge.js';
 import { createAdminRouter } from './admin/adminRouter.js';
 
 export class Shield extends EventEmitter {
@@ -122,7 +125,15 @@ export class Shield extends EventEmitter {
             logger: this.logger
         });
 
-        // 8. Admin Dashboard Configuration (Default: false)
+        // 8. Behavioral Biometrics Subsystem (MiniRocket + Dual Ridge)
+        const biometricsOpts = options.biometrics || {};
+        this.behavioralShieldService = new BehavioralShieldService({
+            modelWeights: biometricsOpts.modelWeights || null,
+            shield: this,
+            logger: this.logger
+        });
+
+        // 9. Admin Dashboard Configuration (Default: false)
         const adminOpts = options.admin || {};
         this.adminEnabled = Boolean(adminOpts.enabled);
     }
@@ -171,6 +182,23 @@ export class Shield extends EventEmitter {
         return this.keyLeakDetectorInstance.middleware();
     }
 
+    /**
+     * Route-level Behavioral Biometrics Express Middleware
+     * Validates mouse kinematics against MiniRocket model
+     * @param {Object} [opts]
+     */
+    behavioralGuard(opts) {
+        return this.behavioralShieldService.middleware(opts);
+    }
+
+    /**
+     * Verify kinematics velocity series against MiniRocket model
+     * @param {number[]|Float64Array} velocityArray
+     */
+    verifyBiometrics(velocityArray) {
+        return this.behavioralShieldService.verify(velocityArray);
+    }
+
     /**
      * Block an IP address immediately
      * @param {string} ip
@@ -318,4 +346,8 @@ export function createShield(options = {}) {
     return new Shield(options);
 }
 
+export { MiniRocket } from './biometrics/minirocket.js';
+export { DualRidgeClassifier } from './biometrics/ridge.js';
+export { BehavioralShieldService } from './middleware/behavioralGuard.js';
+
 export default createShield;