@chdlabs/my-shield 0.2.0 → 0.3.0

package/src/core/ipResolver.js

@@ -0,0 +1,225 @@
+/**
+ * Enterprise Client IP Resolution & Gateway Protection
+ *
+ * Provides safe IP extraction across multi-hop reverse proxies, Cloudflare,
+ * Nginx, HAProxy, and containerized Docker/Kubernetes environments while
+ * defending against header spoofing and accidental gateway blacklisting.
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+import net from 'node:net';
+
+export class IPResolver {
+    /**
+     * @param {Object} [options={}]
+     * @param {boolean|string|string[]} [options.trustProxy='loopback,linklocal,uniquelocal']
+     * @param {boolean} [options.protectGateways=true]
+     * @param {string[]} [options.protectedSubnets] Additional subnets/IPs to protect from bans
+     */
+    constructor(options = {}) {
+        this.trustProxy = options.trustProxy !== undefined ? options.trustProxy : 'loopback,linklocal,uniquelocal';
+        this.gatewayProtection = options.protectGateways !== false;
+        this.protectedSubnets = options.protectedSubnets || [];
+    }
+
+    /**
+     * Clean and normalize raw IP string
+     * - Strips surrounding whitespace
+     * - Strips IPv6 zone index (e.g. %eth0)
+     * - Strips IPv6 port brackets (e.g. [2001:db8::1]:8080 -> 2001:db8::1)
+     * - Strips IPv4 port (e.g. 198.51.100.42:54321 -> 198.51.100.42)
+     * - Normalizes IPv6-mapped IPv4 (e.g. ::ffff:192.0.2.1 -> 192.0.2.1)
+     * @param {string} rawIp
+     * @returns {string}
+     */
+    normalize(rawIp) {
+        if (!rawIp || typeof rawIp !== 'string') return '';
+        let ip = rawIp.trim();
+
+        // 1. Strip IPv6 bracketed port: [2001:db8::1]:8080
+        if (ip.startsWith('[') && ip.includes(']')) {
+            const closingIdx = ip.indexOf(']');
+            ip = ip.substring(1, closingIdx);
+        } else if (ip.includes(':')) {
+            // Check if it's an IPv4 with port: 1.2.3.4:5678 (contains exactly one ':')
+            const colonCount = (ip.match(/:/g) || []).length;
+            if (colonCount === 1) {
+                const parts = ip.split(':');
+                if (net.isIPv4(parts[0])) {
+                    ip = parts[0];
+                }
+            }
+        }
+
+        // 2. Strip IPv6 zone index: fe80::1%eth0 -> fe80::1
+        if (ip.includes('%')) {
+            ip = ip.split('%')[0];
+        }
+
+        // 3. Normalize IPv6-mapped IPv4: ::ffff:192.168.1.1 -> 192.168.1.1
+        const lower = ip.toLowerCase();
+        if (lower.startsWith('::ffff:') && lower.indexOf('.', 7) !== -1) {
+            const candidateV4 = ip.substring(7);
+            if (net.isIPv4(candidateV4)) {
+                return candidateV4;
+            }
+        }
+
+        return ip;
+    }
+
+    /**
+     * Check if string is a valid IPv4 or IPv6 address
+     * @param {string} ip
+     * @returns {boolean}
+     */
+    isValid(ip) {
+        if (!ip || typeof ip !== 'string') return false;
+        return net.isIP(ip) !== 0;
+    }
+
+    /**
+     * Check if an IPv4 or IPv6 address is private, loopback, or link-local
+     * @param {string} ip
+     * @returns {boolean}
+     */
+    isPrivateOrLoopback(ip) {
+        const clean = this.normalize(ip);
+        if (!this.isValid(clean)) return false;
+
+        if (net.isIPv4(clean)) {
+            const octets = clean.split('.').map(Number);
+            const [o1, o2] = octets;
+
+            // 127.0.0.0/8 (Loopback)
+            if (o1 === 127) return true;
+            // 10.0.0.0/8 (Private)
+            if (o1 === 10) return true;
+            // 172.16.0.0/12 (Private including Docker 172.17.x.x)
+            if (o1 === 172 && o2 >= 16 && o2 <= 31) return true;
+            // 192.168.0.0/16 (Private)
+            if (o1 === 192 && o2 === 168) return true;
+            // 169.254.0.0/16 (Link-local)
+            if (o1 === 169 && o2 === 254) return true;
+            // 0.0.0.0
+            if (clean === '0.0.0.0') return true;
+
+            return false;
+        }
+
+        if (net.isIPv6(clean)) {
+            const lower = clean.toLowerCase();
+            // ::1 (Loopback)
+            if (lower === '::1' || lower === '0:0:0:0:0:0:0:1') return true;
+            // fe80::/10 (Link-local)
+            if (lower.startsWith('fe8') || lower.startsWith('fe9') || lower.startsWith('fea') || lower.startsWith('feb')) return true;
+            // fc00::/7 (Unique local / private: fc00::/8 and fd00::/8)
+            if (lower.startsWith('fc') || lower.startsWith('fd')) return true;
+
+            return false;
+        }
+
+        return false;
+    }
+
+    /**
+     * Check if an IP is a protected container gateway or loopback that should NEVER be banned
+     * (e.g. 172.17.0.1 Docker bridge, 127.0.0.1, ::1)
+     * @param {string} ip
+     * @returns {boolean}
+     */
+    isProtectedGateway(ip) {
+        if (!this.gatewayProtection) return false;
+        const clean = this.normalize(ip);
+        if (!this.isValid(clean)) return false;
+
+        // Loopback is always protected
+        if (clean === '127.0.0.1' || clean === '::1' || clean.startsWith('127.')) {
+            return true;
+        }
+
+        // Docker default bridge gateway and bridge subnet: 172.17.0.0/16
+        if (net.isIPv4(clean)) {
+            const octets = clean.split('.').map(Number);
+            // Default docker bridge network gateway: 172.17.0.1
+            if (octets[0] === 172 && octets[1] === 17) {
+                // If it ends with .1 (standard docker/podman host bridge gateway)
+                if (octets[3] === 1) return true;
+            }
+            // Standard docker compose default gateway: 172.18.0.1, 172.19.0.1, 172.20.0.1
+            if (octets[0] === 172 && octets[1] >= 17 && octets[1] <= 31 && octets[3] === 1) {
+                return true;
+            }
+        }
+
+        // Check any user-defined protected subnets/IPs
+        for (const subnet of this.protectedSubnets) {
+            if (clean === subnet) return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * Extract client IP safely from Express request
+     * @param {Object} req Express request
+     * @returns {string} Normalized client IP
+     */
+    resolve(req) {
+        if (!req) return '127.0.0.1';
+
+        // 1. Direct exposure mode (if trustProxy: false, ignore all proxy headers)
+        if (this.trustProxy === false) {
+            const direct = req.socket?.remoteAddress || req.connection?.remoteAddress || req.ip || '127.0.0.1';
+            const clean = this.normalize(direct);
+            return this.isValid(clean) ? clean : '127.0.0.1';
+        }
+
+        const headers = req.headers || {};
+
+        // 2. Priority check for single-value reverse proxy headers
+        const singleHeaders = [
+            'cf-connecting-ip', // Cloudflare
+            'true-client-ip',   // Akamai & Cloudflare Enterprise
+            'x-real-ip',        // Nginx proxy_set_header X-Real-IP $remote_addr
+            'x-client-ip'       // Apache & other reverse proxies
+        ];
+
+        for (const h of singleHeaders) {
+            const val = headers[h];
+            if (val && typeof val === 'string') {
+                const clean = this.normalize(val);
+                if (this.isValid(clean)) {
+                    return clean;
+                }
+            }
+        }
+
+        // 3. Multi-hop X-Forwarded-For chain parsing
+        const xff = headers['x-forwarded-for'];
+        if (xff && typeof xff === 'string') {
+            const ips = xff
+                .split(',')
+                .map(s => this.normalize(s))
+                .filter(s => this.isValid(s));
+
+            if (ips.length > 0) {
+                // Find first public IP (skipping private reverse proxy intermediate hops)
+                const publicIp = ips.find(ip => !this.isPrivateOrLoopback(ip));
+                if (publicIp) {
+                    return publicIp;
+                }
+                // If all IPs in chain are private, return the outermost client (first in XFF)
+                return ips[0];
+            }
+        }
+
+        // 4. Fallback to Express req.ip or socket remote address
+        const fallback = req.ip || req.socket?.remoteAddress || req.connection?.remoteAddress || '127.0.0.1';
+        const cleanFallback = this.normalize(fallback);
+        return this.isValid(cleanFallback) ? cleanFallback : '127.0.0.1';
+    }
+}
+
+export default IPResolver;

package/src/index.d.ts

@@ -47,13 +47,25 @@ 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 {
@@ -73,8 +85,44 @@ export interface BehavioralVerificationResult {
     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;
@@ -100,9 +148,90 @@ 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;
@@ -110,6 +239,8 @@ export class Shield extends EventEmitter {
     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;
@@ -148,16 +279,6 @@ export class DualRidgeClassifier {
     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

@@ -21,6 +21,9 @@ 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 {
     /**
@@ -136,6 +139,47 @@ export class Shield extends EventEmitter {
         // 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;
     }
 
     /**
@@ -191,6 +235,32 @@ export class Shield extends EventEmitter {
         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
@@ -208,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);
+        }
     }
 
     /**
@@ -227,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);
+        }
     }
 
     /**
@@ -328,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();
@@ -349,5 +438,17 @@ export function createShield(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;