@chdlabs/my-shield 0.1.3 → 0.3.0

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,136 @@
+/**
+ * @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
+     * @param {number} [options.maxIdleMs=2500] Maximum acceptable idle gap before trajectory considered stale
+     * @param {number} [options.minPoints=15] Minimum raw points required to avoid flat interpolation
+     * @param {boolean} [options.flushOnConsumption=true] Flush buffer after getPayload to avoid replaying identical vectors
+     */
+    constructor(options = {}) {
+        this.windowLength = options.windowLength || 128;
+        this.sampleIntervalMs = options.sampleIntervalMs || 10;
+        this.maxBufferSize = options.maxBufferSize || 500;
+        this.maxIdleMs = options.maxIdleMs ?? 2500;
+        this.minPoints = options.minPoints ?? 15;
+        this.flushOnConsumption = options.flushOnConsumption !== false;
+        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() {
+        if (this.buffer.length < this.minPoints) return null;
+
+        const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
+        const latest = this.buffer[this.buffer.length - 1];
+
+        // 1. Freshness Guard: If pointer has been stationary for > maxIdleMs (e.g. 2.5s), discard stale vectors
+        if (this.maxIdleMs > 0 && (now - latest.t > this.maxIdleMs)) {
+            if (this.flushOnConsumption) this.buffer = [];
+            return null;
+        }
+
+        const requiredDuration = this.windowLength * this.sampleIntervalMs;
+        const threshold = latest.t - requiredDuration;
+        const points = this.buffer.filter(p => p.t >= threshold);
+
+        if (points.length < this.minPoints) 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;
+
+        // 2. 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);
+        }
+
+        // 3. 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];
+
+        // 4. Buffer Flush on Consumption (Stops replay of identical kinematics across multiple clicks)
+        if (this.flushOnConsumption) {
+            this.buffer = [];
+        }
+
+        return {
+            velocity: Array.from(velocity),
+            isTrusted: allTrusted,
+            timestamp: Date.now()
+        };
+    }
+}

package/src/client/index.js

@@ -0,0 +1,68 @@
+/**
+ * @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';
+export { ShieldClient } from './shieldClient.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/client/shieldClient.js

@@ -0,0 +1,118 @@
+/**
+ * ShieldClient - Browser Client SDK for Behavioral Biometrics & Tripwires
+ *
+ * Provides real-time mouse kinematics telemetry capture, freshness verification,
+ * replay protection, and transparent HTTP interceptors for fetch and Axios.
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+import { MouseTelemetryCollector } from './collector.js';
+import { injectTripwire } from './index.js';
+
+export class ShieldClient {
+    /**
+     * @param {Object} [options={}]
+     * @param {number} [options.windowLength=128]
+     * @param {number} [options.sampleIntervalMs=10]
+     * @param {number} [options.maxIdleMs=2500] Discard stale trajectory if pointer idle > 2.5s
+     * @param {number} [options.minPoints=15] Require at least 15 events
+     * @param {boolean} [options.flushOnConsumption=true] Flush buffer after reading payload
+     * @param {boolean} [options.autoInjectTripwire=false] Auto-inject decoy honeypot trap into DOM
+     */
+    constructor(options = {}) {
+        this.options = options;
+        this.collector = new MouseTelemetryCollector(options);
+
+        if (options.autoInjectTripwire && typeof document !== 'undefined') {
+            injectTripwire();
+        }
+    }
+
+    /**
+     * Begin recording pointer movements
+     */
+    start() {
+        this.collector.start();
+    }
+
+    /**
+     * Stop recording pointer movements
+     */
+    stop() {
+        this.collector.stop();
+    }
+
+    /**
+     * Extract normalized 128-sample kinematic telemetry vector
+     * @returns {{ velocity: number[], isTrusted: boolean, timestamp: number } | null}
+     */
+    getPayload() {
+        return this.collector.getPayload();
+    }
+
+    /**
+     * Transparently instrument window.fetch to attach x-shield-telemetry header
+     * @param {Object} [options={}]
+     * @param {string} [options.headerName='x-shield-telemetry']
+     * @param {string[]} [options.endpoints=['*']] URL patterns to match (e.g. ['/api/auth/*', '/checkout'])
+     */
+    instrumentFetch({ headerName = 'x-shield-telemetry', endpoints = ['*'] } = {}) {
+        if (typeof window === 'undefined' || typeof window.fetch !== 'function') return;
+        const originalFetch = window.fetch;
+        const client = this;
+
+        window.fetch = async function(input, init = {}) {
+            let url = typeof input === 'string' ? input : (input?.url || '');
+
+            const isMatch = endpoints.some(pattern => {
+                if (pattern === '*' || pattern === '/*') return true;
+                if (pattern.endsWith('*')) return url.startsWith(pattern.slice(0, -1));
+                return url === pattern;
+            });
+
+            if (isMatch) {
+                const payload = client.getPayload();
+                if (payload) {
+                    const headers = new Headers(init.headers || {});
+                    headers.set(headerName, JSON.stringify(payload));
+                    init = { ...init, headers };
+                }
+            }
+
+            return originalFetch.call(this, input, init);
+        };
+    }
+
+    /**
+     * Transparently instrument an Axios instance to attach telemetry headers
+     * @param {Object} axiosInstance Axios instance
+     * @param {Object} [options={}]
+     * @param {string} [options.headerName='x-shield-telemetry']
+     * @param {string[]} [options.endpoints=['*']]
+     */
+    instrumentAxios(axiosInstance, { headerName = 'x-shield-telemetry', endpoints = ['*'] } = {}) {
+        if (!axiosInstance || !axiosInstance.interceptors || !axiosInstance.interceptors.request) return;
+        const client = this;
+
+        axiosInstance.interceptors.request.use((config) => {
+            const url = config.url || '';
+            const isMatch = endpoints.some(pattern => {
+                if (pattern === '*' || pattern === '/*') return true;
+                if (pattern.endsWith('*')) return url.startsWith(pattern.slice(0, -1));
+                return url === pattern;
+            });
+
+            if (isMatch) {
+                const payload = client.getPayload();
+                if (payload) {
+                    config.headers = config.headers || {};
+                    config.headers[headerName] = JSON.stringify(payload);
+                }
+            }
+            return config;
+        });
+    }
+}
+
+export default ShieldClient;

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;