@chdlabs/my-shield 0.1.3 → 0.3.0

package/src/index.d.ts

@@ -47,12 +47,87 @@ export interface AdminOptions {
     enabled?: boolean;
 }
 
+export interface BehavioralVerdict {
+    isHuman: boolean;
+    probability: number;
+    score: number;
+    latencyMs: number;
+    ip?: string;
+    mode?: 'block' | 'audit' | 'header-only';
+    reason?: string;
+}
+
+export interface BehavioralGuardOptions {
+    threshold?: number;
+    mode?: 'block' | 'audit' | 'header-only';
+    headerName?: string;
+    replayWindowMs?: number;
+    allowFallbackOnError?: boolean;
+    autoBlockIP?: boolean;
+    onBotDetected?: (req: any, res: any, meta: any) => void;
+    onVerdict?: (verdict: BehavioralVerdict, req: any, res: 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 FileStorageOptions {
+    type?: 'file';
+    directory?: string;
+    filename?: string;
+    debounceMs?: number;
+}
+
+export interface CallbackStorageOptions {
+    onLoad?: () => Promise<Array<{ ip: string; reason: string; metadata?: any; expiresAt?: number | null }>>;
+    onBlock?: (ip: string, reason: string, metadata?: any, expiresAt?: number | null) => Promise<void>;
+    onUnblock?: (ip: string) => Promise<void>;
+}
+
+export type StorageOption = 'memory' | 'file' | FileStorageOptions | CallbackStorageOptions | BaseStorageAdapter;
+
+export interface IPResolverOptions {
+    trustProxy?: boolean | string | string[];
+    protectGateways?: boolean;
+    protectedSubnets?: string[];
+}
+
+export interface OtpGateOptions {
+    adminEmail?: string;
+    jwtSecret?: string;
+    secret?: string;
+    cookieName?: string;
+    codeTtlMs?: number;
+    sessionTtlMs?: number;
+    maxAttempts?: number;
+    sendOtp?: (email: string, code: string) => Promise<void>;
+}
+
 export interface ShieldOptions {
     whitelist?: string[];
+    trustProxy?: boolean | string | string[];
+    protectGateways?: boolean;
+    protectedSubnets?: string[];
+    storage?: StorageOption;
     bloom?: BloomOptions;
     lru?: LRUOptions;
     honeypot?: HoneypotOptions;
     intelligence?: IntelligenceOptions;
+    biometrics?: BiometricsOptions;
     admin?: AdminOptions;
     blockStatusCode?: number;
     logger?: {
@@ -73,15 +148,100 @@ export interface AdminRouterOptions {
     authMiddleware?: RequestHandler | RequestHandler[];
 }
 
+export class BaseStorageAdapter {
+    shield: any;
+    init(shield: any): Promise<void>;
+    loadBlockedIPs(): Promise<Array<{ ip: string; reason: string; metadata?: any; expiresAt?: number | null }>>;
+    saveBlockedIP(ip: string, reason: string, metadata?: any, expiresAt?: number | null): Promise<void>;
+    removeBlockedIP(ip: string): Promise<void>;
+    close(): Promise<void>;
+}
+
+export class MemoryAdapter extends BaseStorageAdapter {}
+export class FileStorageAdapter extends BaseStorageAdapter {
+    constructor(options?: FileStorageOptions & { logger?: any });
+    flushSync(): void;
+}
+export class CallbackStorageAdapter extends BaseStorageAdapter {
+    constructor(options?: CallbackStorageOptions & { logger?: any });
+}
+
+export function createStorageAdapter(storageOption?: StorageOption, logger?: any): BaseStorageAdapter;
+
+export class IPResolver {
+    constructor(options?: IPResolverOptions);
+    normalize(rawIp: string): string;
+    isValid(ip: string): boolean;
+    isPrivateOrLoopback(ip: string): boolean;
+    isProtectedGateway(ip: string): boolean;
+    resolve(req: any): string;
+}
+
+export class OTPGate {
+    constructor(options?: OtpGateOptions & { logger?: any });
+    generateCode(): string;
+    createSessionToken(email: string): string;
+    verifySessionToken(token: string): { valid: boolean; email?: string };
+    middleware(): RequestHandler;
+}
+
+export function createOtpGate(options?: OtpGateOptions & { logger?: any }): RequestHandler;
+
+export interface MouseTelemetryCollectorOptions {
+    windowLength?: number;
+    sampleIntervalMs?: number;
+    maxBufferSize?: number;
+    maxIdleMs?: number;
+    minPoints?: number;
+    flushOnConsumption?: boolean;
+}
+
+export interface ShieldClientOptions extends MouseTelemetryCollectorOptions {
+    autoInjectTripwire?: boolean;
+}
+
+export interface InstrumentFetchOptions {
+    headerName?: string;
+    endpoints?: string[];
+}
+
+export class MouseTelemetryCollector {
+    windowLength: number;
+    sampleIntervalMs: number;
+    maxBufferSize: number;
+    constructor(options?: MouseTelemetryCollectorOptions);
+    start(): void;
+    stop(): void;
+    getPayload(): { velocity: number[]; isTrusted: boolean; timestamp: number } | null;
+}
+
+export class ShieldClient {
+    collector: MouseTelemetryCollector;
+    constructor(options?: ShieldClientOptions);
+    start(): void;
+    stop(): void;
+    getPayload(): { velocity: number[]; isTrusted: boolean; timestamp: number } | null;
+    instrumentFetch(options?: InstrumentFetchOptions): void;
+    instrumentAxios(axiosInstance: any, options?: InstrumentFetchOptions): void;
+}
+
 export class Shield extends EventEmitter {
+    ipResolver: IPResolver;
+    storageAdapter: BaseStorageAdapter;
+
     constructor(options?: ShieldOptions);
 
+    init(): Promise<this>;
     middleware(): RequestHandler;
     honeypot(): RequestHandler;
     notFoundCollector(): RequestHandler;
     adminRouter(options?: AdminRouterOptions): Router;
     costThrottle(options?: CostThrottleOptions): RequestHandler;
     keyLeakDetector(): RequestHandler;
+    behavioralGuard(options?: BehavioralGuardOptions): RequestHandler;
+    strictBotGuard(options?: BehavioralGuardOptions): RequestHandler;
+    otpGate(options?: OtpGateOptions): 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 +259,26 @@ 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 function injectTripwire(): void;
 export function createShield(options?: ShieldOptions): Shield;
 export default createShield;

package/src/index.js

@@ -17,7 +17,13 @@ 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';
+import { IPResolver } from './core/ipResolver.js';
+import { createStorageAdapter } from './storage/index.js';
+import { createOtpGate, OTPGate } from './admin/otpGate.js';
 
 export class Shield extends EventEmitter {
     /**
@@ -122,9 +128,58 @@ 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);
+
+        // 10. Enterprise Client IP Resolution & Gateway Protection
+        this.ipResolver = new IPResolver({
+            trustProxy: options.trustProxy,
+            protectGateways: options.protectGateways !== false,
+            protectedSubnets: options.protectedSubnets || []
+        });
+
+        // 11. Pluggable Storage Adapter (Memory, File, or Database Callbacks)
+        this.storageAdapter = createStorageAdapter(options.storage, this.logger);
+    }
+
+    /**
+     * Asynchronous initialization: hydrates unexpired threats from persistent storage
+     * into Bloom filter and LRU cache.
+     * @returns {Promise<this>}
+     */
+    async init() {
+        await this.storageAdapter.init(this);
+        try {
+            const blockedList = await this.storageAdapter.loadBlockedIPs();
+            if (Array.isArray(blockedList)) {
+                const now = Date.now();
+                for (const item of blockedList) {
+                    if (item && item.ip) {
+                        const cleanIp = this.ipResolver ? this.ipResolver.normalize(item.ip) : item.ip.trim();
+                        if (!this.whitelist.has(cleanIp) && !this.ipResolver.isProtectedGateway(cleanIp)) {
+                            this.bloom.add(cleanIp);
+                            const ttl = item.expiresAt ? Math.max(1, item.expiresAt - now) : null;
+                            this.lru.set(cleanIp, { reason: item.reason || 'restored_threat', metadata: item.metadata || {} }, ttl);
+                        }
+                    }
+                }
+                if (blockedList.length > 0) {
+                    this.logger.info?.(`[SHIELD] Hydrated ${blockedList.length} persistent threats into Bloom & LRU.`);
+                }
+            }
+        } catch (err) {
+            this.logger.error?.('[SHIELD:STORAGE] Error during startup threat hydration:', err.message);
+        }
+        return this;
     }
 
     /**
@@ -171,6 +226,49 @@ 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);
+    }
+
+    /**
+     * Route-level strict behavioral bot defense decorator
+     * Designed specifically for mission-critical routes like /login, /checkout, /register
+     * Automatically rejects bots with 403 and blacklists their IP in Shield L1.
+     * @param {Object} [opts]
+     */
+    strictBotGuard(opts = {}) {
+        return this.behavioralGuard({
+            mode: 'block',
+            autoBlockIP: true,
+            threshold: 0.50,
+            ...opts
+        });
+    }
+
+    /**
+     * Shield Standalone OTP Authentication Gate Middleware
+     * @param {Object} [options]
+     */
+    otpGate(options = {}) {
+        return createOtpGate({
+            logger: this.logger,
+            ...options
+        });
+    }
+
+    /**
+     * 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
@@ -180,16 +278,28 @@ export class Shield extends EventEmitter {
      */
     blockIP(ip, reason = 'manual_block', metadata = {}, customTtlMs = null) {
         if (!ip || typeof ip !== 'string') return;
-        const cleanIp = ip.trim();
+        const cleanIp = this.ipResolver ? this.ipResolver.normalize(ip) : ip.trim();
 
-        // Whitelisted IPs can never be blocked
+        // Whitelisted IPs and protected gateways can never be blocked
         if (this.whitelist.has(cleanIp)) return;
+        if (this.ipResolver && this.ipResolver.isProtectedGateway(cleanIp)) {
+            this.logger.warn?.(`[SHIELD] Block attempted on protected gateway/loopback (${cleanIp}). Block prevented.`);
+            return;
+        }
 
         // 1. Add to Bloom filter (for sub-0.1ms pass-through check)
         this.bloom.add(cleanIp);
 
         // 2. Add to LRU confirmed threat cache (with TTL)
         this.lru.set(cleanIp, { reason, metadata }, customTtlMs);
+
+        // 3. Persist to storage adapter
+        const expiresAt = customTtlMs ? Date.now() + customTtlMs : (this.lru.ttlMs ? Date.now() + this.lru.ttlMs : null);
+        try {
+            this.storageAdapter?.saveBlockedIP(cleanIp, reason, metadata, expiresAt);
+        } catch (err) {
+            this.logger.error?.('[SHIELD:STORAGE] Error saving blocked IP to storage:', err.message);
+        }
     }
 
     /**
@@ -199,8 +309,14 @@ export class Shield extends EventEmitter {
      */
     unblockIP(ip) {
         if (!ip || typeof ip !== 'string') return;
-        const cleanIp = ip.trim();
+        const cleanIp = this.ipResolver ? this.ipResolver.normalize(ip) : ip.trim();
         this.lru.delete(cleanIp);
+
+        try {
+            this.storageAdapter?.removeBlockedIP(cleanIp);
+        } catch (err) {
+            this.logger.error?.('[SHIELD:STORAGE] Error removing blocked IP from storage:', err.message);
+        }
     }
 
     /**
@@ -300,8 +416,9 @@ export class Shield extends EventEmitter {
      * Graceful shutdown: flush in-memory state to 404_intelligence.json
      */
     async shutdown() {
-        this.logger.info?.('[SHIELD] Graceful shutdown initiated. Flushing intelligence to disk...');
+        this.logger.info?.('[SHIELD] Graceful shutdown initiated. Flushing state to disk...');
         await this.filePersistence.stop();
+        await this.storageAdapter?.close?.();
         this.notFoundHandler.destroy();
         this.costThrottleInstance.destroy();
         this.keyLeakDetectorInstance.destroy();
@@ -318,4 +435,20 @@ 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 { IPResolver } from './core/ipResolver.js';
+export { OTPGate, createOtpGate } from './admin/otpGate.js';
+export {
+    BaseStorageAdapter,
+    MemoryAdapter,
+    FileStorageAdapter,
+    CallbackStorageAdapter,
+    createStorageAdapter
+} from './storage/index.js';
+export { ShieldClient } from './client/shieldClient.js';
+export { MouseTelemetryCollector } from './client/collector.js';
+export { injectTripwire } from './client/index.js';
+
 export default createShield;