@anonympins/fingerprint 0.0.7 → 0.0.8

package/README.md

@@ -34,6 +34,7 @@ Once the challenge is solved, a clearance "ticket" is issued via a secure cookie
 -   **Pluggable Datastore**: Supports external datastores like Redis for state persistence and scalability across multiple server instances.
 -   **Express.js Middleware**: Easy integration into an Express application with `powMiddleware`. The datastore must support setting a Time-To-Live (TTL) for challenge secrets.
 -   **Timing Attack Protection**: Uses `crypto.timingSafeEqual` for secure ticket validation.
+-   **Bot Whitelisting**: Includes a DNS-based verification mechanism to reliably identify and whitelist legitimate crawlers like Googlebot and Bingbot, preventing them from being challenged. The results are cached for optimal performance.
 -   **Automatic Parameter Tuning**: Includes a genetic algorithm-based optimizer (`startThresholdAutoTuning`) that analyzes real traffic to dynamically adjust not only suspicion thresholds (`low`, `medium`, `high`) but also the parameters for behavioral pattern detection, improving accuracy and reducing false positives over time.
 
 ## Installation and Usage
@@ -60,7 +61,7 @@ The `powMiddleware` requires a configuration object defining the weights of susp
 import express from 'express';
 import bodyParser from 'body-parser';
 import cookieParser from 'cookie-parser';
-import { powMiddleware /*, configurePow */ } from './fingerprint.js'; // Adjust the path
+import { powMiddleware, default_whitelist } from './fingerprint.js'; // Adjust the path
 
 const app = express();
 app.use(cookieParser());
@@ -132,6 +133,26 @@ const securityConfig = {
             }
         ]
     },
+    // (Optional) Whitelisting configuration.
+    whitelist: [
+        // Option 1: Static IP Allowlist.
+        // A simple array of IPs or CIDR ranges that are always allowed, bypassing all checks.
+        // Useful for internal tools, trusted partners, or monitoring services.
+        // This check is performed first for maximum efficiency.
+        { type: 'allowlist', entries: [
+            '192.168.1.100',      // A specific internal IP
+            '203.0.113.0/24',     // A partner's network range
+            '2001:db8::/32'       // An IPv6 range
+        ]},
+        // Option 2: DNS-verified bots (e.g., search engine crawlers).
+        // This uses a secure DNS lookup (reverse then forward) to verify the bot's identity.
+        // The result is cached per IP to avoid repeated DNS lookups.
+        // You can use the provided default list, which contains over 50 common bots, and extend it.
+        ...default_whitelist(), // Use the defaults
+        { userAgent: 'MyIndustrySpecificBot', hostnameSuffix: '.my-bot-verifier.com' }, // Add a custom bot
+    ],
+    // Or, if you only want the defaults:
+    // whitelist: default_whitelist(),
     // The logger is required for auto-tuning. It collects data on requests.
     logger: (log) => trafficData.push(log),
     // (Optional) Configuration for the automatic threshold and pattern tuning.
@@ -245,6 +266,117 @@ const signature = generateRequestSignature({ action: 'update', id: 123 });
 **Security Note:** This function is powerful but should be used with caution. The `secret` must be managed securely. It is typically used with a temporary, single-use secret provided by the server for a specific action, rather than a long-lived shared secret embedded in the client-side code.
 
 ---
+
+## Why Use the Client-Side Library? The Client + Server Synergy
+
+At first glance, client-side checks might seem redundant with server-side honeypots and analysis. In reality, they form two complementary and synergistic lines of defense.
+
+Imagine your server is a fortified castle:
+
+-   **Server-Side Defense (the guards on the walls):** They inspect anyone who knocks on the gate. They are effective, but this means the enemy is already at your door, and your resources (guards) are mobilized for every interaction, legitimate or not.
+-   **Client-Side Defense (scouts and traps in the forest):** They detect suspicious movements and neutralize threats *before* they even reach the castle walls. This saves the castle's resources for genuine visitors.
+
+The client-side library (`fingerprint.client.js`) gives your server "eyes and ears" where it was previously blind, offering three major advantages:
+
+1.  **Early Detection & Resource Savings:** A bot filling a client-side honeypot is flagged in its own browser. The server can then immediately block it based on the `X-Behavior-Metrics` header, saving CPU, memory, and bandwidth that would have been wasted processing a malicious request.
+2.  **Richer Behavioral Data:** The server cannot see how a user interacts with a page. The client-side library can detect non-human behavior (no mouse movement, instant form fills) that is impossible to spot from the server alone.
+3.  **More Robust Fingerprinting:** Server-side signals (IP, User-Agent) are easy to spoof. Client-side fingerprinting adds much stronger, hardware-based signals (Canvas, WebGL, CPU cores) that are significantly harder for bots to fake consistently.
+
+### Strengths at a Glance
+
+| Feature                 | Server-Side Only Approach                               | Client + Server Approach (with the library)                                |
+| :---------------------- | :------------------------------------------------------ | :------------------------------------------------------------------------- |
+| **Detection Point**     | **Reactive** (after the request is received)            | **Proactive** (before or during the request)                               |
+| **Resource Usage**      | Server is engaged for every request, good or bad.       | Client-side pre-filtering saves significant server resources.              |
+| **Behavioral Analysis** | Limited to request velocity and sequence.               | Rich data: mouse movement, typing rhythm, interaction with hidden elements. |
+| **Fingerprint Evasion** | **Easy** for bots to spoof headers and rotate IPs.      | **Hard** for bots to fake hardware-level fingerprints (Canvas/WebGL).      |
+| **Overall Strategy**    | Guards at the gate.                                     | Scouts in the field + Guards at the gate.                                  |
+
+In short, the client-side library is not an alternative, but a **force multiplier** for the server-side defenses.
+
+### Client-Side Integration: The `initializeClient` function
+
+To simplify setup, all client-side features can be enabled and configured through a single, unified function: `initializeClient(config)`. This is the recommended approach.
+
+```javascript
+import { initializeClient } from './path/to/fingerprint.client.js';
+
+// --- EXAMPLES ---
+
+// Example 1: Enable all default protections and protect same-origin fetch requests.
+initializeClient({
+  honeypots: ['email_confirm', 'user_nickname'], // Your honeypot field names
+  fetch: {} // An empty object enables fetch protection for same-origin
+});
+
+// Example 2: Enable everything and protect a specific API domain.
+initializeClient({
+  honeypots: ['email_confirm'],
+  fetch: {
+    targetDomains: ['api.yourdomain.com']
+  }
+});
+
+// Example 3: Enable only mouse and keystroke tracking, without patching fetch.
+initializeClient({
+  mouse: true,
+  keystrokes: true
+});
+
+// Example 4: Disable keystroke tracking but keep other defaults.
+initializeClient({
+  keystrokes: false,
+  fetch: {}
+});
+```
+
+### Client-Side Behavioral Analysis
+
+The following functions, available in `fingerprint.client.js`, allow for proactive, client-side detection of bot-like behavior. They collect metrics on user interaction which can be sent to the server for more accurate suspicion scoring. The server-side logic to interpret these metrics (via the `X-Behavior-Metrics` header) would need to be implemented as part of a custom scoring extension.
+
+#### `startKeystrokeDynamicsTracker()`
+*Client-side function only.* Starts tracking the timing between keystrokes. The average latency between key presses is a strong behavioral indicator. Humans have a natural, somewhat variable typing rhythm, whereas bots often simulate keystrokes with a fixed, unnaturally consistent delay, or paste text instantly (zero latency).
+
+#### `startMouseEntropyTracker()`
+*Client-side function only.* Starts tracking mouse movements on the page. It calculates a simple entropy score based on movement patterns. Human mouse movements are typically chaotic, whereas bots often have linear or no movement at all. This should be called once when your application's main component mounts.
+
+#### `initializeHoneypots(fieldNames)`
+*Client-side function only.* Sets up "traps" on hidden form fields. If a script automatically fills one of these fields, it's immediately flagged as a bot on the client side.
+
+This provides a proactive, first-line defense against simple bots. By setting up traps directly in the browser, you can detect a bot the moment it interacts with a hidden field, rather than waiting for it to submit a form and consume server resources. This detection is then reported to the server via the `X-Behavior-Metrics` header, allowing for an immediate and efficient block.
+
+- `fieldNames`: An array of strings corresponding to the `name` attributes of the honeypot input fields in your HTML.
+
+### Advanced: Manual Wrapping with `protectedFetch`
+
+If you prefer not to modify global functions or need fine-grained control over which requests are protected, you can use the `protectedFetch` wrapper. You must use this function instead of the standard `fetch` for your API calls.
+
+- **`protectedFetch(resource, options)`**: A wrapper around the native `fetch` API that automatically enriches requests with security headers. It adds:
+  - `X-Device-Fingerprint`: The client's device fingerprint.
+  - `X-Behavior-Metrics`: A JSON string containing the metrics collected by the behavioral trackers (e.g., mouse entropy, honeypot interaction).
+
+**Example:**
+
+```javascript
+import { 
+  initializeClient,
+  protectedFetch 
+} from './path/to/fingerprint.client.js';
+
+// Start tracking user behavior as soon as the app loads.
+// Note: You still need to initialize the trackers even if you use protectedFetch manually.
+initializeClient({ fetch: false }); // Disables automatic fetch patching
+
+// Now, use protectedFetch for your specific API calls.
+async function submitForm(data) {
+    const response = await protectedFetch('/api/submit-data', {
+        method: 'POST',
+        body: JSON.stringify(data),
+        headers: {'Content-Type': 'application/json'}
+    });
+}
+```
+
 ## Advanced Features
 
 ### Architecture: `FingerprintEngine`

package/fingerprint.client.js

@@ -0,0 +1,399 @@
+import { cyrb53, FingerprintBuilder } from './fingerprint.builder.js';
+
+const ClientLibrary = {
+    // Cache pour éviter de recalculer les constantes (Hardware, etc.)
+    _cachedBuilder: null,
+    /**
+     * Génère l'empreinte de l'appareil actuel.
+     */
+    getDeviceFingerprint() {
+        if (typeof window === "undefined") {
+            console.error("getDeviceFingerprint can only be called on the client-side.");
+            return "";
+        }
+
+        if (!this._cachedBuilder) {
+            const nav = window.navigator;
+            const screen = window.screen;
+
+            this._cachedBuilder = new FingerprintBuilder();
+
+            // 1. Hardware (Très stable) : Cœurs, RAM, GPU (si dispo via canvas), Touch
+            this._cachedBuilder.add(
+                "hw",
+                `${nav.hardwareConcurrency}_${nav.deviceMemory}_${nav.maxTouchPoints}`,
+            );
+
+            // 2. Geo/Locale (Stable sauf voyage/VPN) : Timezone, Langue
+            this._cachedBuilder.add(
+                "geo",
+                `${Intl.DateTimeFormat().resolvedOptions().timeZone}_${nav.language}_${new Date().getTimezoneOffset()}`,
+            );
+
+            // 3. Screen (Stable sauf changement moniteur/zoom) : Dimensions, ColorDepth
+            this._cachedBuilder.add(
+                "scr",
+                `${screen.width}x${screen.height}_${screen.colorDepth}`,
+            );
+
+            // 4. Platform (Stable) : OS, Engine
+            this._cachedBuilder.add("os", nav.platform);
+
+            // 5. Graphics (WebGL Vendor/Renderer) - Invariant matériel fort
+            try {
+                const canvas = document.createElement("canvas");
+                const gl =
+                    canvas.getContext("webgl") || canvas.getContext("experimental-webgl");
+                if (gl) {
+                    const debugInfo = gl.getExtension("WEBGL_debug_renderer_info");
+                    if (debugInfo) {
+                        const vendor = gl.getParameter(debugInfo.UNMASKED_VENDOR_WEBGL);
+                        const renderer = gl.getParameter(debugInfo.UNMASKED_RENDERER_WEBGL);
+                        this._cachedBuilder.add("gpu", `${vendor}_${renderer}`);
+                    }
+                }
+            } catch (e) {
+            }
+
+            // 6. Canvas Fingerprinting (Rendering quirks)
+            try {
+                const canvas = document.createElement("canvas");
+                const ctx = canvas.getContext("2d");
+                if (ctx) {
+                    canvas.width = 200;
+                    canvas.height = 50;
+                    ctx.textBaseline = "alphabetic";
+                    ctx.font = "14px 'Arial'";
+                    ctx.fillStyle = "#f60";
+                    ctx.fillRect(125, 1, 62, 20);
+                    ctx.fillStyle = "#069";
+                    ctx.fillText("fingerprint", 2, 15);
+                    ctx.fillStyle = "rgba(102, 204, 0, 0.7)";
+                    ctx.fillText("fingerprint", 4, 17);
+                    this._cachedBuilder.add("cvs", canvas.toDataURL());
+                }
+            } catch (e) {
+            }
+
+            // 7. Bot Detection (Indication cachée)
+            if (nav.webdriver) this._cachedBuilder.add("bot", "true");
+        }
+
+        return this._cachedBuilder.toString();
+    },
+
+    /**
+     * Génère une signature de requête incluant le contexte.
+     * @param {object} payload
+     */
+    generateRequestSignature(payload = {}) {
+        const deviceFp = this.getDeviceFingerprint();
+        const sortedPayload = Object.keys(payload)
+            .sort()
+            .map((k) => `${k}=${payload[k]}`)
+            .join("&");
+        const payloadHash = cyrb53(sortedPayload);
+        return `${deviceFp}|req:${payloadHash}`;
+    },
+
+    /**
+     * Génère une signature HMAC-SHA256 en utilisant l'API Web Crypto.
+     * @param {object} payload - Les données à signer.
+     * @param {string} secret - La clé secrète partagée.
+     * @returns {Promise<string>} La signature hexadécimale.
+     */
+    async generateClientSideSignature(payload, secret) {
+        const sortedPayload = Object.keys(payload).sort().map((k) => `${k}=${payload[k]}`).join("&");
+        const encoder = new TextEncoder();
+        const key = await window.crypto.subtle.importKey("raw", encoder.encode(secret), {
+            name: "HMAC",
+            hash: "SHA-256"
+        }, false, ["sign"]);
+        const signatureBuffer = await window.crypto.subtle.sign("HMAC", key, encoder.encode(sortedPayload));
+        const hashArray = Array.from(new Uint8Array(signatureBuffer));
+        return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+    },
+
+    /**
+     * @internal
+     * Resets the cached fingerprint builder. Used for testing purposes.
+     */
+    _resetCache() {
+        this._cachedBuilder = null;
+    },
+
+    /**
+     * Démarre le suivi des mouvements de la souris pour calculer l'entropie.
+     * À appeler une fois sur la page.
+     */
+    startMouseEntropyTracker() {
+        // S'assurer de ne pas attacher l'écouteur plusieurs fois
+        if (mouseMovements > 0) return;
+
+        document.addEventListener('mousemove', (e) => {
+            const dx = e.clientX - lastMousePos.x;
+            const dy = e.clientY - lastMousePos.y;
+            // Une métrique simple : la somme des distances. Un bot aura souvent 0.
+            metrics.mouseEntropy += Math.sqrt(dx * dx + dy * dy);
+            lastMousePos = {x: e.clientX, y: e.clientY};
+            mouseMovements++;
+        }, {passive: true});
+    },
+
+    /**
+     * Démarre le suivi de la dynamique de frappe pour calculer la latence.
+     * À appeler une fois sur la page.
+     */
+    startKeystrokeDynamicsTracker() {
+        // S'assurer de ne pas attacher l'écouteur plusieurs fois
+        if (keystrokeTimestamps.length > 0) return;
+
+        document.addEventListener('keydown', () => {
+            const now = performance.now();
+            if (keystrokeTimestamps.length > 0) {
+                const lastTimestamp = keystrokeTimestamps[keystrokeTimestamps.length - 1];
+                const latency = now - lastTimestamp;
+                // On ignore les latences irréalistes (trop longues ou trop courtes)
+                if (latency > 10 && latency < 2000) { // Augmenté à 2s
+                    if (keystrokeLatencies.length >= KEYSTROKE_HISTORY_MAX) {
+                        keystrokeLatencies.shift(); // Garder la taille de l'historique
+                    }
+                    keystrokeLatencies.push(latency);
+                }
+            }
+            keystrokeTimestamps.push(now);
+        }, {passive: true});
+    },
+
+    /**
+     * Initialise ou réinitialise les honeypots côté client pour une détection immédiate.
+     * Les anciens écouteurs sont supprimés avant d'en ajouter de nouveaux.
+     * @param {string[]} honeypotFieldNames - Noms des champs de formulaire cachés.
+     */
+    initializeHoneypots(honeypotFieldNames) {
+        // 1. Nettoyer les anciens écouteurs
+        activeHoneypotListeners.forEach((listener, field) => {
+            field.removeEventListener('input', listener);
+        });
+        activeHoneypotListeners.clear();
+
+        // 2. Ajouter les nouveaux écouteurs
+        honeypotFieldNames.forEach(fieldName => {
+            const field = document.querySelector(`[name="${fieldName}"]`);
+            if (field) {
+                // On utilise une fonction nommée (ou une référence) pour pouvoir la supprimer plus tard.
+                // L'option { once: true } est excellente, mais pour une réinitialisation complète,
+                // il est plus propre de gérer le nettoyage nous-mêmes.
+                const listener = () => {
+                    this.onHoneypotTrigger();
+                    // Se supprime lui-même après exécution, comme { once: true }
+                    field.removeEventListener('input', listener);
+                };
+                field.addEventListener('input', listener);
+                activeHoneypotListeners.set(field, listener); // On stocke la référence
+            }
+        });
+    },
+
+    /**
+     * Récupère les métriques comportementales collectées.
+     * À appeler avant d'envoyer une requête sensible.
+     * @returns {ClientBehaviorMetrics}
+     */
+    getClientBehaviorMetrics() {
+        // Normalise l'entropie de la souris
+        if (mouseMovements > 10) {
+            metrics.mouseEntropy /= mouseMovements;
+        }
+        // Calcule la latence moyenne des frappes
+        if (keystrokeLatencies.length > 0) {
+            const sum = keystrokeLatencies.reduce((a, b) => a + b, 0);
+            metrics.keystrokeLatency = sum / keystrokeLatencies.length;
+        } else {
+            metrics.keystrokeLatency = 0;
+        }
+        return metrics;
+    },
+
+    /**
+     * Enrichit une requête fetch avec les en-têtes de fingerprinting et de comportement.
+     * @param {RequestInfo} resource
+     * @param {RequestInit} [options]
+     * @returns {Promise<Response>}
+     */
+    async protectedFetch(resource, options = {}) {
+        const fp = this.getDeviceFingerprint();
+        const behavior = this.getClientBehaviorMetrics();
+
+        const headers = new Headers(options.headers || {});
+        headers.set('X-Device-Fingerprint', fp);
+        headers.set('X-Behavior-Metrics', JSON.stringify(behavior));
+
+        options.headers = headers;
+        return fetch(resource, options);
+    },
+
+// --- Système d'interception de Fetch robuste et anti-conflit ---
+
+    _isFetchPatched: false,
+    _interceptorChain: [],
+    _originalFetch: (typeof window !== 'undefined') ? window.fetch : () => Promise.reject(new Error('fetch is not available')),
+
+/**
+ * Adds an interceptor function to the `fetch` chain.
+ * Chaque intercepteur reçoit `resource`, `options`, et une fonction `next`.
+ * Il DOIT appeler `next(resource, options)` pour continuer la chaîne.
+ * @param {function(RequestInfo, RequestInit, function): Promise<Response>} interceptor
+ */
+  addFetchInterceptor(interceptor) {
+    if (!this._isFetchPatched) {
+        this.patchGlobalFetch();
+    }
+    this._interceptorChain.push(interceptor);
+  },
+
+  patchGlobalFetch() {
+    if (this._isFetchPatched || typeof window === 'undefined') return;
+
+    this._isFetchPatched = true;
+    window.fetch = (resource, options) => {
+        // Le "dispatcher" qui exécute la chaîne.
+        const dispatch = (index, res, opts) => {
+            if (index >= this._interceptorChain.length) {
+                // Fin de la chaîne, on appelle le fetch original.
+                return this._originalFetch(res, opts);
+            }
+            const nextInterceptor = this._interceptorChain[index];
+            // Appelle l'intercepteur actuel en lui passant la fonction pour appeler le suivant.
+            return nextInterceptor(res, opts, (nextRes, nextOpts) => dispatch(index + 1, nextRes, nextOpts));
+        };
+        return dispatch(0, resource, options || {});
+    };
+  },
+
+    /**
+     * La fonction qui est appelée lorsqu'un honeypot est déclenché.
+     * @private
+     */
+    onHoneypotTrigger : () => {
+        metrics.honeypotInteraction = true;
+        // On pourrait même envoyer un signalement au serveur immédiatement.
+    },
+
+  /**
+   * Initialise l'intercepteur de fingerprinting.
+   * Il s'ajoute à la chaîne d'interception sans écraser les autres.
+   * @param {string[]} [targetDomains] - Optionnel. Liste de domaines à protéger.
+   * Si non fourni, protège les requêtes de même origine.
+   */
+  initializeFetch(targetDomains = []) {
+    const fingerprintInterceptor = (resource, options, next) => {        
+        const requestUrl = (resource instanceof Request) ? resource.url : String(resource);        
+        let shouldProtect = false;
+
+        try {
+            const url = new URL(requestUrl, window.location.origin);
+            // Protéger si la liste de domaines est vide ET que la requête est de même origine,
+            // OU si le domaine de la requête est dans la liste fournie.
+            shouldProtect = (targetDomains.length === 0 && url.origin === window.location.origin) || 
+                            (targetDomains.length > 0 && targetDomains.includes(url.hostname));
+        } catch (e) {
+            // Si l'URL est relative (ex: '/api/data'), new URL() ne lèvera pas d'erreur.
+            // Ce bloc est une sécurité pour les cas où l'URL serait malformée.
+            // On protège par défaut si aucune liste de domaines n'est spécifiée.
+            shouldProtect = targetDomains.length === 0;
+        }
+
+        if (shouldProtect) {
+            const fp = this.getDeviceFingerprint();
+            const behavior = this.getClientBehaviorMetrics();
+            const headers = new Headers(options.headers || {});
+            headers.set('X-Device-Fingerprint', fp);
+            headers.set('X-Behavior-Metrics', JSON.stringify(behavior));
+            options.headers = headers;
+        }
+
+        // Passe la main à l'intercepteur suivant dans la chaîne.
+        return next(resource, options);
+    };
+
+    this.addFetchInterceptor(fingerprintInterceptor);
+  },
+  
+/**
+ * @typedef {object} ClientConfig
+ * @property {boolean} [mouse=true] - Activer le suivi de l'entropie de la souris.
+ * @property {boolean} [keystrokes=true] - Activer le suivi de la dynamique de frappe.
+ * @property {string[]} [honeypots] - Noms des champs de formulaire honeypot à initialiser.
+ * @property {object} [fetch] - Configuration pour l'interception de fetch.
+ * @property {string[]} [fetch.targetDomains] - Domaines à protéger. Si non fourni, protège les requêtes de même origine.
+ */
+
+/**
+ * Initialise toutes les protections côté client en une seule fois.
+ * C'est la méthode d'initialisation recommandée.
+ * @param {ClientConfig} [config={}] - L'objet de configuration.
+ */
+  initializeClient(config = {}) {
+    const {
+        mouse = true,
+        keystrokes = true,
+        honeypots = [],
+        fetch: fetchConfig,
+    } = config;
+
+    if (mouse) {
+        this.startMouseEntropyTracker();
+    }
+    if (keystrokes) {
+        this.startKeystrokeDynamicsTracker();
+    }
+    if (honeypots.length > 0) {
+        this.initializeHoneypots(honeypots);
+    }
+    if (fetchConfig !== undefined) {
+        this.initializeFetch(fetchConfig.targetDomains);
+    }
+  }
+};
+
+/**
+ * @typedef {object} ClientBehaviorMetrics
+ * @property {number} mouseEntropy - Entropie des mouvements de la souris.
+ * @property {number} keystrokeLatency - Latence moyenne entre les frappes.
+ * @property {boolean} honeypotInteraction - Vrai si un honeypot a été touché.
+ */
+
+/** @type {ClientBehaviorMetrics} */
+const metrics = {
+    mouseEntropy: 0,
+    keystrokeLatency: 0,
+    honeypotInteraction: false,
+};
+
+let lastMousePos = { x: 0, y: 0 };
+let mouseMovements = 0;
+let activeHoneypotListeners = new Map(); // Garde une trace des écouteurs actifs
+let keystrokeTimestamps = [];
+let keystrokeLatencies = []; // NOUVEAU: Tableau dédié pour les latences
+const KEYSTROKE_HISTORY_MAX = 20; // On garde l'historique des 20 dernières frappes
+
+
+
+// Exporter les fonctions individuellement pour la compatibilité ascendante
+export const getDeviceFingerprint = ClientLibrary.getDeviceFingerprint.bind(ClientLibrary);
+export const generateRequestSignature = ClientLibrary.generateRequestSignature.bind(ClientLibrary);
+export const generateClientSideSignature = ClientLibrary.generateClientSideSignature.bind(ClientLibrary);
+export const _resetCache = ClientLibrary._resetCache.bind(ClientLibrary);
+export const startMouseEntropyTracker = ClientLibrary.startMouseEntropyTracker.bind(ClientLibrary);
+export const startKeystrokeDynamicsTracker = ClientLibrary.startKeystrokeDynamicsTracker.bind(ClientLibrary);
+export const initializeHoneypots = ClientLibrary.initializeHoneypots.bind(ClientLibrary);
+export const getClientBehaviorMetrics = ClientLibrary.getClientBehaviorMetrics.bind(ClientLibrary);
+export const protectedFetch = ClientLibrary.protectedFetch.bind(ClientLibrary);
+export const addFetchInterceptor = ClientLibrary.addFetchInterceptor.bind(ClientLibrary);
+export const patchGlobalFetch = ClientLibrary.patchGlobalFetch.bind(ClientLibrary);
+export const initializeFetch = ClientLibrary.initializeFetch.bind(ClientLibrary);
+export const initializeClient = ClientLibrary.initializeClient.bind(ClientLibrary);
+
+// Export the internal object for testing purposes
+export default ClientLibrary;

package/fingerprint.js

@@ -1,5 +1,7 @@
 // C:/Dev/games.primals.net/src/utils/fingerprint.js
 import crypto from "node:crypto";
+import { parse } from "node:net";
+import dns from "node:dns/promises";
 import { Optimization } from "./library.js";
 import { cyrb53, FingerprintBuilder } from "./fingerprint.builder.js";
 
@@ -1124,14 +1126,134 @@ export class FingerprintEngine {
     this.isProduction = isProduction;
   }
 
+  /**
+   * Checks if an IP address is in the static allowlist (IPs or CIDR ranges).
+   * This is the fastest check and should be performed first.
+   * @private
+   * @param {string} clientIp - The IP address of the client.
+   * @returns {boolean} True if the IP is in the allowlist.
+   */
+  _isIpInAllowlist(clientIp) {
+    const { whitelist = [] } = this.securityConfig;
+    const allowlistRule = whitelist.find(rule => rule.type === 'allowlist');
+
+    if (!allowlistRule || !allowlistRule.entries || allowlistRule.entries.length === 0) {
+      return false;
+    }
+
+    const ip = parse(clientIp);
+    const ipVersion = ip.family;
+
+    for (const entry of allowlistRule.entries) {
+      if (entry.includes('/')) { // CIDR range
+        try {
+          const [range, prefixStr] = entry.split('/');
+          const prefix = parseInt(prefixStr, 10);
+          const rangeIp = parse(range);
+
+          if (rangeIp.family !== ipVersion) continue;
+
+          const ipBytes = ip.toBuffer();
+          const rangeBytes = rangeIp.toBuffer();
+          const mask = Buffer.alloc(ipBytes.length, 0xff);
+
+          for (let i = 0; i < Math.floor(prefix / 8); i++) {
+            if (ipBytes[i] !== rangeBytes[i]) {
+              break; // Mismatch in full byte, move to next entry
+            }
+          }
+          const remainingBits = prefix % 8;
+          if (remainingBits > 0) {
+            const byteIndex = Math.floor(prefix / 8);
+            const bitmask = (0xff << (8 - remainingBits)) & 0xff;
+            if ((ipBytes[byteIndex] & bitmask) !== (rangeBytes[byteIndex] & bitmask)) {
+              continue; // Mismatch in partial byte
+            }
+          }
+          return true; // IP is in CIDR range
+        } catch (e) { continue; /* Ignore invalid CIDR entries */ }
+      } else if (entry === clientIp) { // Direct IP match
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Verifies if a request comes from a legitimate, whitelisted bot (e.g., Googlebot)
+   * using reverse and forward DNS lookups. The result is cached.
+   * @private
+   * @param {object} requestContext - The request context.
+   * @returns {Promise<boolean>} True if the request is from a verified whitelisted bot.
+   */
+  async _verifyWhitelistedBot(requestContext) {
+    const { whitelist = [] } = this.securityConfig;
+    const botRules = whitelist.filter(rule => rule.hostnameSuffix);
+    if (botRules.length === 0) {
+      return false;
+    }
+
+    const { clientIp, headers } = requestContext;
+    const userAgent = headers['user-agent'] || '';
+
+    const matchedRule = botRules.find(rule => {
+      if (!rule.userAgent) return false;
+      try {
+        return new RegExp(rule.userAgent).test(userAgent);
+      } catch (e) {
+        console.error(`[Fingerprint] Invalid regex in whitelist rule: ${rule.userAgent}`);
+        return false;
+      }
+    });
+    if (!matchedRule) {
+      return false;
+    }
+
+    const cacheKey = `ip-whitelist:${clientIp}`;
+    const cachedStatus = await store.get(cacheKey);
+
+    if (cachedStatus === 'verified') {
+      return true;
+    }
+    if (cachedStatus === 'failed') {
+      return false;
+    }
+
+    try {
+      // 1. Reverse DNS lookup
+      const hostnames = await dns.reverse(clientIp);
+      const validHostname = hostnames.find(h => h.endsWith(matchedRule.hostnameSuffix));
+
+      if (!validHostname) {
+        await store.set(cacheKey, 'failed', 86400); // Cache failure for 24h
+        return false;
+      }
+
+      // 2. Forward DNS lookup
+      const addresses = await dns.resolve(validHostname);
+      if (addresses.includes(clientIp)) {
+        await store.set(cacheKey, 'verified', 86400); // Cache success for 24h
+        return true;
+      }
+    } catch (error) {
+      // DNS errors are common (e.g., for IPs with no rDNS record), treat as failure.
+    }
+
+    await store.set(cacheKey, 'failed', 86400); // Cache failure for 24h
+    return false;
+  }
+
   async processRequest(requestContext) {
     const { clientIp, path, cookies, query, isStatic } = requestContext;
     const { weights, thresholds, logger, onDeviceCompromised } = this.securityConfig;
-
     if (isStatic) {
       return { action: 'next', score: 0, vector: {} };
     }
 
+    // 1. Check static IP allowlist first for maximum performance.
+    if (this._isIpInAllowlist(clientIp)) {
+      return { action: 'next', score: 0, vector: { whitelisted: 100, type: 'allowlist' } };
+    }
+
     const { pow_nonce } = query;
 
     // Honeypot: Direct probing of challenge endpoints is highly suspicious.
@@ -1145,6 +1267,11 @@ export class FingerprintEngine {
         }
     }
 
+    // Check if the request is from a verified, whitelisted bot (e.g., Googlebot)
+    if (await this._verifyWhitelistedBot(requestContext)) {
+      return { action: 'next', score: 0, vector: { whitelisted: 100, type: 'bot' } };
+    }
+
     // Check for persisted "condemned" status early.
     const { deviceData } = await resolveRequestIdentity(requestContext);
     if (deviceData?.condemned) {
@@ -1410,6 +1537,111 @@ export class FingerprintEngine {
   }
 }
 
+/**
+ * Returns a default list of whitelisting rules for common and legitimate web crawlers.
+ * This list can be used as a base and extended with custom rules.
+ * @returns {Array<{userAgent: string, hostnameSuffix: string}>}
+ */
+export const default_whitelist = () => [
+    // === Moteurs de recherche majeurs ===
+    { userAgent: 'Googlebot', hostnameSuffix: '.googlebot.com' },
+    { userAgent: 'Google-Extended', hostnameSuffix: '.google.com' },
+    { userAgent: 'AdsBot-Google', hostnameSuffix: '.googlebot.com' },
+    { userAgent: 'Mediapartners-Google', hostnameSuffix: '.google.com' },
+    { userAgent: 'Google-InspectionTool', hostnameSuffix: '.google.com' },
+    { userAgent: '(bingbot|adidxbot)', hostnameSuffix: '.search.msn.com' },
+    { userAgent: 'DuckDuckBot', hostnameSuffix: '.duckduckgo.com' },
+    { userAgent: 'YandexBot', hostnameSuffix: '.yandex.com' },
+    { userAgent: 'YandexImages', hostnameSuffix: '.yandex.com' },
+    { userAgent: 'Baiduspider', hostnameSuffix: '.crawl.baidu.com' },
+    { userAgent: 'Slurp', hostnameSuffix: '.crawl.yahoo.net' },
+    { userAgent: 'Sogou web spider', hostnameSuffix: '.sogou.com' },
+    { userAgent: 'Exabot', hostnameSuffix: '.exabot.com' },
+    { userAgent: 'ia_archiver', hostnameSuffix: '.alexa.com' },
+    { userAgent: 'SeznamBot', hostnameSuffix: '.seznam.cz' },
+    { userAgent: 'Mail.RU_Bot', hostnameSuffix: '.mail.ru' },
+    { userAgent: 'Yeti', hostnameSuffix: '.naver.com' }, // Naver
+
+    // === Outils SEO et d'analyse ===
+    { userAgent: 'AhrefsBot', hostnameSuffix: '.ahrefs.com' },
+    { userAgent: 'SemrushBot', hostnameSuffix: '.semrush.com' },
+    { userAgent: 'MJ12bot', hostnameSuffix: '.mj12bot.com' }, // Majestic
+    { userAgent: 'rogerbot', hostnameSuffix: '.moz.com' }, // Moz
+    { userAgent: 'DotBot', hostnameSuffix: '.moz.com' }, // Moz (anciennement opensiteexplorer.org)
+    { userAgent: 'Screaming Frog SEO Spider', hostnameSuffix: '.screamingfrog.co.uk' },
+    { userAgent: 'cognitiveseo', hostnameSuffix: '.cognitiveseo.com' },
+    { userAgent: 'SEOkicks', hostnameSuffix: '.seokicks.com' },
+    { userAgent: 'serpstatbot', hostnameSuffix: '.serpstatbot.com' },
+    { userAgent: 'MegaIndex', hostnameSuffix: '.megaindex.com' },
+    { userAgent: 'LinkpadBot', hostnameSuffix: '.linkpad.ru' },
+    { userAgent: 'Sistrix', hostnameSuffix: '.sistrix.com' },
+    { userAgent: 'RyteBot', hostnameSuffix: '.ryte.com' },
+    { userAgent: 'linkfluence', hostnameSuffix: '.linkfluence.com' },
+    { userAgent: 'TurnitinBot', hostnameSuffix: '.turnitin.com' },
+    { userAgent: 'GrapeshotCrawler', hostnameSuffix: '.grapeshot.co.uk' },
+
+    // === Robots d'IA et de données ===
+    { userAgent: 'GPTBot', hostnameSuffix: '.openai.com' },
+    { userAgent: 'ChatGPT-User', hostnameSuffix: '.openai.com' },
+    { userAgent: 'Applebot', hostnameSuffix: '.applebot.apple.com' },
+    { userAgent: 'CCBot', hostnameSuffix: '.commoncrawl.org' },
+    { userAgent: 'Bytespider', hostnameSuffix: '.bytespider.com' }, // ByteDance (TikTok)
+    { userAgent: 'Diffbot', hostnameSuffix: '.diffbot.com' },
+    { userAgent: 'PerplexityBot', hostnameSuffix: '.perplexity.ai' },
+    { userAgent: 'ClaudeBot', hostnameSuffix: '.anthropic.com' },
+    { userAgent: 'cohere.io', hostnameSuffix: '.cohere.io' },
+    { userAgent: 'DataForSeoBot', hostnameSuffix: '.dataforseo.com' },
+    { userAgent: 'YouBot', hostnameSuffix: '.you.com' },
+    { userAgent: 'omgili', hostnameSuffix: '.omgili.com' },
+
+    // === Réseaux sociaux et partage ===
+    { userAgent: 'facebookexternalhit', hostnameSuffix: '.facebook.com' },
+    { userAgent: 'facebot', hostnameSuffix: '.facebook.com' },
+    { userAgent: 'Twitterbot', hostnameSuffix: '.twttr.com' },
+    { userAgent: 'Pinterestbot', hostnameSuffix: '.pinterest.com' },
+    { userAgent: 'LinkedInBot', hostnameSuffix: '.linkedin.com' },
+    { userAgent: 'Slackbot', hostnameSuffix: '.slack.com' },
+    { userAgent: 'Discordbot', hostnameSuffix: '.discord.com' },
+    { userAgent: 'TelegramBot', hostnameSuffix: '.telegram.org' },
+    { userAgent: 'WhatsApp', hostnameSuffix: '.wa.me' },
+    { userAgent: 'SkypeUriPreview', hostnameSuffix: '.skype.com' },
+    { userAgent: 'redditbot', hostnameSuffix: '.reddit.com' },
+
+    // === Services de monitoring et d'uptime ===
+    { userAgent: 'UptimeRobot', hostnameSuffix: '.uptimerobot.com' },
+    { userAgent: 'Pingdom', hostnameSuffix: '.pingdom.com' },
+    { userAgent: 'StatusCake', hostnameSuffix: '.statuscake.com' },
+    { userAgent: 'Site24x7', hostnameSuffix: '.site24x7.com' },
+    { userAgent: 'Freshping', hostnameSuffix: '.freshping.io' },
+    { userAgent: 'Better Uptime', hostnameSuffix: '.betteruptime.com' },
+    { userAgent: 'Checkly', hostnameSuffix: '.checkly-infra.com' },
+    { userAgent: 'Datadog', hostnameSuffix: '.datadoghq.com' },
+    { userAgent: 'NewRelicPinger', hostnameSuffix: '.newrelic.com' },
+
+    // === Archives et agrégateurs de contenu ===
+    { userAgent: 'archive.org_bot', hostnameSuffix: '.archive.org' },
+    { userAgent: 'Feedly', hostnameSuffix: '.feedly.com' },
+    { userAgent: 'FeedFetcher-Google', hostnameSuffix: '.google.com' },
+    { userAgent: 'TheOldReader', hostnameSuffix: '.theoldreader.com' },
+    { userAgent: 'Inoreader', hostnameSuffix: '.inoreader.com' },
+    { userAgent: 'FlipboardProxy', hostnameSuffix: '.flipboard.com' },
+    { userAgent: 'PaperLiBot', hostnameSuffix: '.paper.li' },
+
+    // === Services Cloud et Plateformes ===
+    { userAgent: 'Amazon Route 53 Health Check', hostnameSuffix: '.amazonaws.com' },
+    { userAgent: 'Google-Cloud-Scheduler', hostnameSuffix: '.google.com' },
+    { userAgent: 'APIs-Google', hostnameSuffix: '.google.com' },
+
+    // === Divers ===
+    { userAgent: 'W3C_Validator', hostnameSuffix: '.w3.org' },
+    { userAgent: 'GTmetrix', hostnameSuffix: '.gtmetrix.com' },
+    { userAgent: 'WebPageTest', hostnameSuffix: '.webpagetest.org' },
+    { userAgent: 'Google-Site-Verification', hostnameSuffix: '.google.com' },
+    { userAgent: 'KeyCDN', hostnameSuffix: '.keycdn.com' },
+];
+
+
+
 // --- Proof-of-Work Middleware (The Tollbooth) ---
 export const powMiddleware = (securityConfig) => {
   const engine = new FingerprintEngine(securityConfig);

package/package.json

@@ -1,48 +1,61 @@
-{
-  "name": "@anonympins/fingerprint",
-  "version": "0.0.7",
-  "description": "An HTTP(S) client mitigation and anti-bot protection library for Node.js/Express, based on digital fingerprinting and dynamic Proof-of-Work (PoW) challenges.",
-  "main": "fingerprint.js",
-  "type": "module",
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "scripts": {
-    "test": "vitest run"
-  },
-  "files": [
-    "fingerprint.js",
-    "library.js",
-    "README.md",
-    "LICENSE"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/anonympins/fingerprint.git"
-  },
-  "keywords": [
-    "fingerprint",
-    "bot",
-    "anti-bot",
-    "security",
-    "express",
-    "middleware",
-    "proof-of-work",
-    "pow",
-    "rate-limiting",
-    "mitigation",
-    "captcha"
-  ],
-  "author": "anonympins",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/anonympins/fingerprint/issues"
-  },
-  "homepage": "https://github.com/anonympins/fingerprint#readme",
-  "devDependencies": {
-    "body-parser": "^1.20.2",
-    "cookie-parser": "^1.4.6",
-    "express": "^4.18.2",
-    "vitest": "^4.1.11"
-  }
-}
+{
+  "name": "@anonympins/fingerprint",
+  "version": "0.0.8",
+  "description": "An HTTP(S) client mitigation and anti-bot protection library for Node.js/Express, based on digital fingerprinting and dynamic Proof-of-Work (PoW) challenges.",
+  "main": "fingerprint.js",
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "files": [
+    "fingerprint.js",
+    "fingerprint.client.js",
+    "library.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anonympins/fingerprint.git"
+  },
+  "keywords": [
+    "fingerprint",
+    "bot",
+    "anti-bot",
+    "security",
+    "express",
+    "middleware",
+    "proof-of-work",
+    "pow",
+    "rate-limiting",
+    "mitigation",
+    "captcha",
+    "dns"
+  ],
+  "author": "anonympins",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/anonympins/fingerprint/issues"
+  },
+  "homepage": "https://github.com/anonympins/fingerprint#readme",
+  "devDependencies": {
+    "body-parser": "^1.20.2",
+    "cookie-parser": "^1.4.6",
+    "express": "^4.18.2",
+    "vitest": "^4.1.11",
+    "ioredis": "^5.3.2",
+    "mongodb": "^6.3.0",
+    "prom-client": "^15.1.2"
+  },
+  "peerDependencies": {
+    "ioredis": "^5.3.2",
+    "mongodb": "^6.3.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": { "optional": true },
+    "mongodb": { "optional": true }
+  }
+}