@anonympins/fingerprint 0.0.7 → 0.0.9

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.
@@ -177,17 +198,41 @@ The main Express middleware. It orchestrates identification, suspicion calculati
 
 #### `configureStore(store)`
 Allows replacing the in-memory store with an external datastore (like Redis) for persistence and scaling.
+The library provides ready-to-use adapters for popular datastores like Redis and MongoDB, which automatically handle the Time-To-Live (TTL) required for temporary data like challenge secrets.
 
-See the Datastore Integration Guide for a complete example of creating a Redis store.
+**Redis Example:**
 
 ```javascript
 import { configureStore } from './fingerprint.js';
-import { createRedisStore } from './redis-store.js'; // Assuming a redis store implementation exists
+import { createRedisStore } from './redis-store.js';
+import Redis from 'ioredis';
 
-const redisStore = createRedisStore(process.env.REDIS_URL);
+const redisClient = new Redis(process.env.REDIS_URL);
+const redisStore = createRedisStore(redisClient);
 configureStore(redisStore);
 ```
 
+**MongoDB Example:**
+
+```javascript
+import { configureStore } from './fingerprint.js';
+import { createMongoDbStore } from './mongodb-store.js';
+import { MongoClient } from 'mongodb';
+
+const mongoClient = new MongoClient(process.env.MONGODB_URL);
+
+// It's recommended to connect before your application starts listening.
+await mongoClient.connect(); 
+
+const mongoStore = createMongoDbStore(mongoClient.db('your-db-name'), 'sessions'); // 'sessions' is the collection name
+configureStore(mongoStore);
+
+// IMPORTANT: For automatic expiration of challenges and other temporary data to work,
+// you must create a TTL index on the `expiresAt` field in your MongoDB collection.
+// Run this command in the mongo shell:
+// db.sessions.createIndex({ "expiresAt": 1 }, { expireAfterSeconds: 0 })
+```
+
 #### `identifyRequest(req, res)`
 An asynchronous function that returns an identification string for a given request, based on its suspicion level (`device:<id>`, `suspicious_medium:<ip>`, etc.). Useful for integration with a custom rate-limiter.
 
@@ -245,6 +290,114 @@ 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';
+ 
+/**
+ * Initializes all client-side protections.
+ * This is the recommended way to set up the client-side library.
+ */
+initializeClient({
+  // (Optional, default: true) Enable mouse movement tracking to detect non-human patterns.
+  // Set to `false` to disable.
+  mouse: true,
+ 
+  // (Optional, default: true) Enable keystroke dynamics tracking (timing between key presses).
+  // Set to `false` to disable.
+  keystrokes: true,
+ 
+  // (Optional) An array of `name` attributes for hidden form fields that act as bot traps.
+  honeypots: ['email_confirm', 'user_nickname', 'website_url'],
+ 
+  // (Optional) Enables automatic protection for `fetch` requests.
+  // If the `fetch` object is present, the protection is active.
+  fetch: {
+    // (Optional) An array of domains to protect. If empty or not provided,
+    // it protects same-origin requests by default.
+    targetDomains: ['api.yourdomain.com', 'auth.yourdomain.com']
+  }
+});
+```
+
+### 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.builder.js

@@ -0,0 +1,104 @@
+/**
+ * Algorithme de hachage cyrb53 (rapide et faible taux de collision).
+ */
+export const cyrb53 = (str, seed = 0) => {
+    let h1 = 0xdeadbeef ^ seed,
+        h2 = 0x41c6ce57 ^ seed;
+    for (let i = 0, ch; i < str.length; i++) {
+        ch = str.charCodeAt(i);
+        h1 = Math.imul(h1 ^ ch, 2654435761);
+        h2 = Math.imul(h2 ^ ch, 1597334677);
+    }
+    h1 =
+        Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^
+        Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 =
+        Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^
+        Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return 4294967296 * (2097151 & h2) + (h1 >>> 0);
+};
+
+/**
+ * Classe pour construire une empreinte composite (Multi-Hash).
+ * Format de sortie : "grp1:hash1|grp2:hash2|grp3:hash3"
+ */
+export class FingerprintBuilder {
+    constructor() {
+        this.components = new Map();
+    }
+
+    /**
+     * Ajoute un composant au hash global.
+     * @param {string} group - Le nom du groupe (ex: 'hw', 'screen', 'geo')
+     * @param {string|number|boolean} value - La valeur brute à hasher
+     */
+    add(group, value) {
+        if (value === undefined || value === null) return this;
+        // On hash la valeur individuellement pour l'anonymiser et réduire sa taille
+        this.components.set(group, cyrb53(String(value)));
+        return this;
+    }
+
+    /**
+     * Adds a raw component without hashing it.
+     * Useful for metrics that need to be read on the server.
+     * @param {string} group - The name of the group.
+     * @param {string|number} value - The raw value.
+     */
+    addRaw(group, value) {
+        if (value === undefined || value === null) return this;
+        this.components.set(group, value);
+        return this;
+    }
+    /**
+     * Génère la chaîne de signature finale.
+     * Trie les clés pour garantir un ordre déterministe.
+     */
+    toString() {
+        return Array.from(this.components.entries())
+            .sort((a, b) => a[0].localeCompare(b[0])) // Tri alphabétique des clés
+            .map(([key, hash]) => `${key}:${hash}`)
+            .join("|");
+    }
+
+    /**
+     * Compares two fingerprints and returns a similarity score (0 to 1).
+     * Uses weights to give more importance to strong invariants (Canvas, GPU).
+     * @param {string} fpString1 - Fingerprint A
+     * @param {string} fpString2 - Fingerprint B
+     */
+    static compare(fpString1, fpString2) {
+        if (!fpString1 || !fpString2) return 0;
+
+        const parse = (str) => new Map(str.split("|").map(part => part.split(":")).filter(([k,v]) => k && v));
+
+        const map1 = parse(fpString1);
+        const map2 = parse(fpString2);
+
+        // Poids de "véracité" (Entropie/Stabilité)
+        const weights = {
+            cvs: 4.0,   // Canvas: Très haute entropie (Rendu unique)
+            gpu: 3.0,   // GPU: Haute entropie (Matériel spécifique)
+            hw: 1.5,    // Hardware: Moyenne entropie
+            scr: 1.0,   // Screen: Moyenne
+            geo: 0.5,   // Geo: Faible (VPN/Voyage)
+            os: 0.5,    // OS: Faible (Générique)
+            bot: 0.0,   // Bot: Informatif
+        };
+
+        let weightedMatches = 0;
+        let totalWeight = 0;
+
+        const allKeys = new Set([...map1.keys(), ...map2.keys()]);
+
+        allKeys.forEach((key) => {
+            const weight = weights[key] || 1.0;
+            totalWeight += weight;
+            if (map1.get(key) === map2.get(key)) {
+                weightedMatches += weight;
+            }
+        });
+
+        return totalWeight === 0 ? 0 : weightedMatches / totalWeight;
+    }
+}

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,7 +1,11 @@
 // C:/Dev/games.primals.net/src/utils/fingerprint.js
 import crypto from "node:crypto";
+import { BlockList } from "node:net";
+import dns from "node:dns/promises";
 import { Optimization } from "./library.js";
 import { cyrb53, FingerprintBuilder } from "./fingerprint.builder.js";
+export { createRedisStore } from "./redis-store.js";
+export { createMongoDbStore } from "./mongodb-store.js";
 
 /**
  * Retrieves the POW_SECRET from environment variables with appropriate checks.
@@ -700,7 +704,7 @@ function verifyTrapUrl(path, signature, nonce) {
 /**
  * @typedef {object} IStore
  * @property {(key: string) => Promise<any>} get
- * @property {(key: string, value: any) => Promise<void>} set
+ * @property {(key: string, value: any, ttl?: number) => Promise<void>} set
  * @property {(key: string) => Promise<boolean>} has
  * @property {(key: string) => Promise<void>} delete
  */
@@ -711,8 +715,21 @@ function verifyTrapUrl(path, signature, nonce) {
  */
 const inMemoryStore = {
   _map: new Map(),
+  _timeouts: new Map(),
   async get(key) { return this._map.get(key); },
-  async set(key, value) { this._map.set(key, value); },
+  async set(key, value, ttl) {
+    this._map.set(key, value);
+    // If a timeout already exists for this key, clear it.
+    if (this._timeouts.has(key)) {
+        clearTimeout(this._timeouts.get(key));
+        this._timeouts.delete(key);
+    }
+    // If a TTL is provided, set a timeout to delete the key.
+    if (ttl && ttl > 0) {
+        const timeoutId = setTimeout(() => this._map.delete(key), ttl * 1000);
+        this._timeouts.set(key, timeoutId);
+    }
+  },
   async has(key) { return this._map.has(key); },
   async delete(key) { this._map.delete(key); },
 };
@@ -859,7 +876,7 @@ export const getSuspicionVector = async (context, securityConfig) => {
     context._newCookies = context._newCookies || [];
     context._newCookies.push(newCookie);
   }
-  await store.set(`ip-device:${clientIp}`, deviceId); // Link the IP to the device
+  await store.set(`ip-device:${clientIp}`, deviceId, 600); // Link the IP to the device for 10 minutes
 
   // Periodically clean up device data
   if (Date.now() - deviceData.lastUpdate > 10 * 60 * 1000) { // 10 minutes
@@ -1082,14 +1099,16 @@ function generateCombinedPoWChallengePage(cpuChallengeDetails, memoryDifficulty,
  * Verifies a PoW solution based on a target and generates a ticket.
  */
 export function verifyCpuTargetPoWAndGenerateTicket(
-  clientIp,
+  clientIp, // This parameter is crucial and must be the actual client IP
   nonce,
   solution,
   suspicionFactor,
   clientSecret, // Le secret est maintenant requis
 ) {
   const target = calculateTarget(suspicionFactor);
-  const message = clientSecret ? `${clientIp}:${nonce}:${solution}:${clientSecret}` : `${clientIp}:${nonce}:${solution}`;
+  const message = clientSecret
+    ? `${clientIp}:${nonce}:${solution}:${clientSecret}`
+    : `${clientIp}:${nonce}:${solution}`;
   const hash = crypto
     .createHash("sha256")
     .update(message)
@@ -1122,16 +1141,118 @@ export class FingerprintEngine {
     const isProduction = process.env.NODE_ENV === 'production';
     this.securityConfig = securityConfig;
     this.isProduction = isProduction;
+    this._allowlist = this._buildAllowlist();
+  }
+
+  /**
+   * 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.
+   */
+  _buildAllowlist() {
+    const blockList = new BlockList();
+    const { whitelist = [] } = this.securityConfig;
+    const allowlistRule = whitelist.find(rule => rule.type === 'allowlist');
+
+    if (!allowlistRule || !allowlistRule.entries || allowlistRule.entries.length === 0) {
+      return blockList; // Retourne une liste vide
+    }
+
+    for (const entry of allowlistRule.entries) {
+      if (entry.includes('/')) { // CIDR range
+        try {
+          const [address, prefix] = entry.split('/');
+          blockList.addSubnet(address, parseInt(prefix, 10));
+        } catch (e) {
+          // Ignore les entrées CIDR invalides
+        }
+      } else { // Direct IP match
+        blockList.addAddress(entry);
+      }
+    }
+    return blockList;
+  }
+  _isIpInAllowlist(clientIp) {
+    return this._allowlist.check(clientIp);
+  }
+  /**
+   * 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 (TTL in seconds)
+        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 (TTL in seconds)
+        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 (TTL in seconds)
+    return false;
   }
 
   async processRequest(requestContext) {
-    const { clientIp, path, cookies, query, isStatic } = requestContext;
+    const { clientIp = "unknown", 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 +1266,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) {
@@ -1223,7 +1349,7 @@ export class FingerprintEngine {
         if (logger) {
             logger({ type: 'trap_triggered', deviceId: cookies?.device_id, score: 100, path: path, timestamp: Date.now() });
         }
-        await store.set(`device:${cookies.device_id}`, deviceData);
+        await store.set(`device:${cookies.device_id}`, deviceData); // No TTL for condemned status
         return { action: 'block', status: 403, body: 'Forbidden', score: 100, vector: { honeypotScore: 100 } };
     }
 
@@ -1309,7 +1435,7 @@ export class FingerprintEngine {
 
         // Associate the current challenge nonce with the device for trap URL verification later.
         if (deviceData) {
-            deviceData.lastChallengeNonce = nonce;
+            deviceData.lastChallengeNonce = nonce; // No TTL, part of the main device object
             await store.set(`device:${cookies.device_id}`, deviceData);
         }
 
@@ -1385,7 +1511,7 @@ export class FingerprintEngine {
     if (ipProfile.statelessCount > statelessLimit) {
       return `suspicious_high:${clientIp}`;
     }
-    await store.set(`ip:${clientIp}`, ipProfile);
+    await store.set(`ip:${clientIp}`, ipProfile, 600); // Keep IP profile for 10 minutes
 
     const vector = await __internal.getSuspicionVector(requestContext, this.securityConfig); // Pass the config
     const { honeypotScore } = getHoneypotScore(requestContext, this.securityConfig.honeypot);
@@ -1410,6 +1536,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/mongodb-store.js

@@ -0,0 +1,53 @@
+/**
+ * @file Creates a store adapter for MongoDB.
+ * This adapter uses a collection as a key-value store and leverages MongoDB's TTL indexes
+ * for automatic expiration of documents.
+ */
+
+/**
+ * Creates a store adapter for a MongoDB collection.
+ * It's recommended to pass the `db` object and let the adapter handle the collection.
+ *
+ * **Note:** For TTL to work, you must create a TTL index on the `expiresAt` field in your collection.
+ * In the mongo shell, run:
+ * `db.yourCollectionName.createIndex({ "expiresAt": 1 }, { expireAfterSeconds: 0 })`
+ *
+ * @param {import('mongodb').Db} db - An instance of a MongoDB Db object.
+ * @param {string} [collectionName='fingerprint_store'] - The name of the collection to use.
+ * @returns {import('./fingerprint.js').IStore} An object that complies with the IStore interface.
+ */
+export function createMongoDbStore(db, collectionName = 'fingerprint_store') {
+  const collection = db.collection(collectionName);
+
+  return {
+    async get(key) {
+      const doc = await collection.findOne({ _id: key });
+      // The TTL index automatically removes expired documents, so no need to check `expiresAt` here.
+      return doc ? doc.value : null;
+    },
+    async set(key, value, ttl) {
+      const doc = {
+        _id: key,
+        value: value,
+      };
+
+      if (ttl && ttl > 0) {
+        // Set the expiration date for the TTL index.
+        doc.expiresAt = new Date(Date.now() + ttl * 1000);
+      }
+
+      await collection.updateOne(
+        { _id: key },
+        { $set: doc },
+        { upsert: true }
+      );
+    },
+    async has(key) {
+      const count = await collection.countDocuments({ _id: key });
+      return count > 0;
+    },
+    async delete(key) {
+      await collection.deleteOne({ _id: key });
+    },
+  };
+}

package/package.json

@@ -1,48 +1,75 @@
-{
-  "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.9",
+  "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",
+    "fingerprint.builder.js",
+    "library.js",
+    "redis-store.js",
+    "mongodb-store.js",
+    "sql-store.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",
+    "prom-client": "^15.1.2",
+    "vitest": "^4.1.11"
+  },
+  "peerDependencies": {
+    "ioredis": "^5.3.2",
+    "knex": ">=3.0.0",
+    "mongodb": "^6.3.0",
+    "sqlite3": "^5.1.7"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    },
+    "mongodb": {
+      "optional": true
+    },
+    "knex": {
+      "optional": true
+    },
+    "sqlite3": {
+      "optional": true
+    }
+  }
+}

package/redis-store.js

@@ -0,0 +1,43 @@
+/**
+ * @file Creates a store adapter for ioredis.
+ * This adapter handles the serialization and deserialization of complex objects,
+ * including the conversion of Set objects to arrays for storage in Redis.
+ */
+
+/**
+ * Creates a store adapter for an ioredis client.
+ * @param {import('ioredis').Redis} redisClient - An instance of the ioredis client.
+ * @returns {import('./fingerprint.js').IStore} An object that complies with the IStore interface.
+ */
+export function createRedisStore(redisClient) {
+  return {
+    async get(key) {
+      const value = await redisClient.get(key);
+      if (!value) return null;
+      // Use a reviver to convert arrays back to Sets for specific keys like 'ips'.
+      return JSON.parse(value, (k, v) => {
+        if (k === 'ips' && Array.isArray(v)) {
+          return new Set(v);
+        }
+        return v;
+      });
+    },
+    async set(key, value, ttl) {
+      // Use a replacer to convert Set objects into arrays before serialization.
+      const stringValue = JSON.stringify(value, (k, v) => {
+        if (v instanceof Set) {
+          return Array.from(v);
+        }
+        return v;
+      });
+
+      if (ttl && ttl > 0) {
+        await redisClient.set(key, stringValue, 'EX', ttl);
+      } else {
+        await redisClient.set(key, stringValue);
+      }
+    },
+    async has(key) { return (await redisClient.exists(key)) === 1; },
+    async delete(key) { await redisClient.del(key); },
+  };
+}

package/sql-store.js

@@ -0,0 +1,78 @@
+/**
+ * @file Creates a store adapter for Knex.js.
+ * This adapter is compatible with various SQL databases like PostgreSQL, MySQL, and SQLite.
+ * It handles serialization of complex objects and TTL for automatic data expiration.
+ */
+
+/**
+ * Creates a store adapter for a Knex.js client.
+ *
+ * **Note:** You must create the table yourself before using the store.
+ * The table should have at least the following columns:
+ * - `key` (string, primary key)
+ * - `value` (text or json/jsonb)
+ * - `expiresAt` (datetime or timestamp with time zone)
+ *
+ * Example schema for PostgreSQL:
+ * ```sql
+ * CREATE TABLE your_table_name (
+ *   "key" VARCHAR(255) PRIMARY KEY,
+ *   "value" TEXT NOT NULL,
+ *   "expiresAt" TIMESTAMPTZ
+ * );
+ * ```
+ *
+ * @param {import('knex').Knex} knex - An instance of the Knex client.
+ * @param {string} [tableName='fingerprint_store'] - The name of the table to use.
+ * @returns {import('./fingerprint.js').IStore} An object that complies with the IStore interface.
+ */
+export function createSqlStore(knex, tableName = 'fingerprint_store') {
+  // Custom replacer/reviver to handle Set serialization, similar to the Redis store.
+  const replacer = (k, v) => (v instanceof Set ? Array.from(v) : v);
+  const reviver = (k, v) => (k === 'ips' && Array.isArray(v) ? new Set(v) : v);
+
+  return {
+    async get(key) {
+      const row = await knex(tableName).where('key', key).first();
+      if (!row) return null;
+
+      // Manually check for expiration, as not all SQL databases have automatic TTL cleanup.
+      if (row.expiresAt && new Date(row.expiresAt) < new Date()) {
+        await this.delete(key); // Clean up expired key.
+        return null;
+      }
+
+      try {
+        return JSON.parse(row.value, reviver);
+      } catch (e) {
+        // In case of malformed JSON, treat it as a miss.
+        return null;
+      }
+    },
+
+    async set(key, value, ttl) {
+      const stringValue = JSON.stringify(value, replacer);
+      const expiresAt = ttl ? new Date(Date.now() + ttl * 1000) : null;
+
+      // Use native upsert capabilities of Knex for different SQL dialects.
+      await knex(tableName)
+        .insert({ key, value: stringValue, expiresAt })
+        .onConflict('key')
+        .merge();
+    },
+
+    async has(key) {
+      const row = await knex(tableName).where('key', key).first('key');
+      if (!row) return false;
+      // Also check for expiration here.
+      if (row.expiresAt && new Date(row.expiresAt) < new Date()) {
+        return false;
+      }
+      return true;
+    },
+
+    async delete(key) {
+      await knex(tableName).where('key', key).del();
+    },
+  };
+}