@anonympins/fingerprint 0.2.3 → 0.2.4

package/README.md

@@ -14,6 +14,10 @@ This system identifies and slows down bots and automated scripts by evaluating t
 The process unfolds in three steps:
 
 1.  **Identification & Fingerprinting**: A unique fingerprint is generated for each device. This combines a client-side browser fingerprint, server-side request headers, and the **JA3 fingerprint** from the TLS handshake, which reliably identifies the underlying HTTP client library (e.g., Chrome vs. a Python script). A `device_id` cookie is used to track the device over time.
+    *   **Advanced TLS Fingerprinting (JA4/JA4H)**: Beyond JA3, the system can leverage JA4/JA4H (if provided by a reverse proxy like Cloudflare or Akamai) for a more robust and modern TLS fingerprint, especially for HTTP/2 traffic.
+    *   **HTTP/2 Fingerprinting**: Analyzes HTTP/2 specific characteristics (settings frame, priority, window update) to identify client libraries.
+    *   **TCP/IP Fingerprinting**: If available (e.g., from a specialized reverse proxy), low-level TCP/IP stack characteristics (TTL, window size, options) are used for identification.
+    *   A `device_id` cookie is used to track the device over time.
 2.  **Suspicion Score Calculation**: Several indicators are analyzed to calculate a suspicion score:
     *   **Header Anomalies**: Missing `User-Agent`, `Accept-Language`, etc.
     *   **Device Behavior**: Rapid fingerprint changes (User-Agent rotation).
@@ -22,6 +26,7 @@ The process unfolds in three steps:
     *   **Cross-Layer Inconsistency**: Mismatches between client-side data (e.g., OS reported by the browser) and server-side headers (e.g., `User-Agent`).
     *   **Request Patterns**: Repetitive, rapid-fire, or sequential requests typical of scraping bots. The parameters for detecting these patterns (e.g., request velocity, burst detection) are dynamically adjusted by the auto-tuner for optimal performance.
     *   **Honeypot Trap**: Detection of bots that automatically fill hidden form fields or probe for common but unused URL parameters (e.g., `?debug=true`).
+    *   **TLS Fingerprint Spoofing**: Detects inconsistencies between the TLS fingerprint (JA3/JA4) and other HTTP headers (e.g., User-Agent), indicating an attempt to disguise the client.
 3.  **Dynamic Challenge**: If the suspicion score exceeds a certain threshold, a challenge is presented to the user. The difficulty and type of challenge depend on the score:
     *   **Low to Medium Suspicion**: A combined **CPU and Memory Proof-of-Work (PoW)** challenge is issued. The difficulty of both the CPU (hash calculation) and Memory (allocation and computation) components scales progressively with the suspicion score. For low scores, the memory challenge is negligible, making it primarily a CPU task.
     *   **High Suspicion**: For the most suspicious requests, the system issues a high-difficulty combined CPU/Memory challenge. The architecture allows for plugging in more complex challenges like CAPTCHAs if needed.
@@ -156,7 +161,8 @@ const securityConfig = {
         behaviorScore: 0.7,      // Penalizes non-human interactions (no mouse/keyboard activity)
         honeypotScore: 1.0,      // Strongly penalizes bots filling hidden form fields
         crossLayerInconsistencyScore: 0.4, // Penalizes mismatches between client-side data (e.g., OS) and server-side headers (e.g., User-Agent)
-        timeInconsistencyScore: 0.9 // Strongly penalizes large time gaps between client metric collection and server reception (replay attack)
+        timeInconsistencyScore: 0.9, // Strongly penalizes large time gaps between client metric collection and server reception (replay attack)
+        tlsSpoofingScore: 0.8      // Penalizes mismatches between the TLS fingerprint (JA3/JA4) and the User-Agent (client spoofing)
     },
     thresholds: {
         low: 20,    // Score from which a CPU challenge is issued
@@ -661,6 +667,7 @@ Updates the payload (parameters) of a specific problem by its ID. This allows fo
 
 ---
 
+## NodeJS raw integration
 **Workflow:**
 
 1.  **Instantiate the Engine**: Create an instance with your `securityConfig`.

package/fingerprint.builder.js

@@ -1,161 +1,172 @@
-/**
- * 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;
-    }
-
-    /**
-     * Affiche les composants actuels dans la console.
-     * @param {string} [title='FingerprintBuilder Components'] - Un titre pour le log.
-     */
-    log(title = 'FingerprintBuilder Components') {
-        console.log(`--- ${title} ---`);
-        const sortedComponents = Array.from(this.components.entries())
-            .sort((a, b) => a[0].localeCompare(b[0]));
-        
-        console.table(Object.fromEntries(sortedComponents));
-        console.log(`Final string: ${this.toString()}`);
-        console.log(`---------------------------------${'-'.repeat(title.length)}`);
-    }
-
-    /**
-     * 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("|");
-    }
-        /**
-        * 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;
-    }
-
-    /**
-     * 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);
-
-        // Keys to ignore when comparing the initial request fingerprint with the challenge solver's fingerprint.
-        // Headers like Client-Hints (ch_*), cookie presence (cookie_keys), and upgrade-insecure-requests
-        // can vary or be absent on the subsequent request that submits the solution, especially after a redirect.
-        // By ignoring them, we focus the comparison on more stable identifiers like UA, JA3, GPU, etc.
-        const volatileKeys = new Set([
-            'ch_ua', 'ch_platform', 'ch_mobile', 'ch_model', 'ch_arch', 'ch_bitness',
-            'cookie_keys', 'upgrade',
-            // Also ignore network and http version as they can change between requests (e.g., proxy, protocol upgrade)
-            'network', 'http_ver',
-            // Ignore proxy-related headers as they are not stable client identifiers
-            'x_forwarded_for', 'x_real_ip', 'cf_connecting_ip'
-        ]);
-
-        // Poids de "véracité" (Entropie/Stabilité)
-        // Les poids sont augmentés pour donner plus d'importance aux signaux forts.
-        const weights = {
-            // --- Signaux très forts (difficiles à usurper) ---
-            cvs: 5.0,   // Canvas: Très haute entropie (Rendu unique du GPU/driver)
-            gpu: 4.0,   // GPU: Haute entropie (Matériel spécifique)
-            ja3: 3.5,   // JA3: Identifie la librairie TLS (très stable pour un client donné)
-            ua: 2.0,    // User-Agent: Signal fort, bien que modifiable
-            
-            // --- Signaux composites et dérivés ---
-            client_fp_hash: 3.0, // Le hash de l'empreinte client est un signal très fort.
-            browser: 1.5,        // Le navigateur extrait du UA.
-            os_version: 1.5,     // L'OS extrait du UA.
-            device_type: 1.0,    // Le type d'appareil extrait du UA.
-
-            // --- Signaux moyens ---
-            hw: 1.5,    // Hardware (CPU, RAM): Stabilité moyenne
-            scr: 1.0,   // Screen: Stabilité moyenne
-            // 'os' est souvent la même chose que 'ch_platform', on peut le déprécier ou lui donner un poids faible.
-            os: 0.8,    // OS (nav.platform): Assez stable
-            geo: 0.5,   // Geo/Langue: Peut changer (VPN, voyage)
-        };
-
-        let weightedMatches = 0;
-        let totalWeight = 0;
-
-        const allKeys = new Set([...map1.keys(), ...map2.keys()]);
-
-        allKeys.forEach((key) => {
-            // On ignore les clés volatiles pour cette comparaison spécifique.
-            if (volatileKeys.has(key)) return;
-
-            // On ne compare que les clés qui ont un poids défini.
-            const weight = weights[key];
-            if (!weight) return;
-
-            totalWeight += weight; // N'incrémenter que si la clé est pertinente.
-            if (map1.get(key) === map2.get(key)) {
-                weightedMatches += weight;
-            }
-        });
-
-        return totalWeight === 0 ? 0 : weightedMatches / totalWeight;
-    }
+/**
+ * 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); // Use Math.imul for 32-bit multiplication
+        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;
+    }
+
+    /**
+     * Affiche les composants actuels dans la console.
+     * @param {string} [title='FingerprintBuilder Components'] - Un titre pour le log.
+     */
+    log(title = 'FingerprintBuilder Components') {
+        console.log(`--- ${title} ---`);
+        const sortedComponents = Array.from(this.components.entries())
+            .sort((a, b) => a[0].localeCompare(b[0]));
+        
+        console.table(Object.fromEntries(sortedComponents));
+        console.log(`Final string: ${this.toString()}`);
+        console.log(`---------------------------------${'-'.repeat(title.length)}`);
+    }
+
+    /**
+     * 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("|");
+    }
+        /**
+        * 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;
+    }
+
+    /**
+     * 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
+     */
+    // Note on `volatileKeys`: These keys are ignored during the comparison between the fingerprint
+    // of the request that *triggered* a challenge and the fingerprint of the request that *submits*
+    // the solution. This is because headers like Client-Hints (ch_*), cookie presence, and upgrade-insecure-requests
+    // can legitimately change or be absent on the subsequent request, especially after a redirect.
+    // By ignoring them, we focus the comparison on more stable identifiers like UA, JA3, GPU, etc.
+    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);
+
+        // Keys to ignore when comparing the initial request fingerprint with the challenge solver's fingerprint.
+        // Headers like Client-Hints (ch_*), cookie presence (cookie_keys), and upgrade-insecure-requests
+        // can vary or be absent on the subsequent request that submits the solution, especially after a redirect.
+        // By ignoring them, we focus the comparison on more stable identifiers like UA, JA3, GPU, etc.
+        const volatileKeys = new Set([
+            'ch_ua', 'ch_platform', 'ch_mobile', 'ch_model', 'ch_arch', 'ch_bitness',
+            'cookie_keys', 'upgrade',
+            // Also ignore network and http version as they can change between requests (e.g., proxy, protocol upgrade)
+            'network', 'http_ver',
+            // Ignore proxy-related headers as they are not stable client identifiers
+            'x_forwarded_for', 'x_real_ip', 'cf_connecting_ip'
+        ]);
+
+        // Poids de "véracité" (Entropie/Stabilité)
+        // Les poids sont augmentés pour donner plus d'importance aux signaux forts.
+        const weights = {
+            // --- Signaux très forts (difficiles à usurper) ---
+            cvs: 5.0,   // Canvas: Très haute entropie (Rendu unique du GPU/driver)
+            gpu: 4.0,   // GPU: Haute entropie (Matériel spécifique)
+            ja3: 3.5,   // JA3: Identifie la librairie TLS (très stable pour un client donné)
+            ja4: 4.0,   // JA4: Plus moderne, inclut HTTP/2
+            h2_settings: 3.0, // HTTP/2 settings frame fingerprint
+            tcp_fp: 2.5, // TCP/IP fingerprint
+            ua: 2.0,    // User-Agent: Signal fort, bien que modifiable
+            
+            // --- Signaux composites et dérivés ---
+            client_fp_hash: 3.0, // Le hash de l'empreinte client est un signal très fort.
+            browser: 1.5,        // Le navigateur extrait du UA.
+            os_version: 1.5,     // L'OS extrait du UA.
+            device_type: 1.0,    // Le type d'appareil extrait du UA.
+
+            // --- Signaux moyens ---
+            hw: 1.5,    // Hardware (CPU, RAM): Stabilité moyenne
+            scr: 1.0,   // Screen: Stabilité moyenne
+            // 'os' est souvent la même chose que 'ch_platform', on peut le déprécier ou lui donner un poids faible.
+            os: 0.8,    // OS (nav.platform): Assez stable
+            geo: 0.5,   // Geo/Langue: Peut changer (VPN, voyage)
+        };
+
+        let weightedMatches = 0;
+        let totalWeight = 0;
+
+        const allKeys = new Set([...map1.keys(), ...map2.keys()]);
+
+        allKeys.forEach((key) => {
+            // On ignore les clés volatiles pour cette comparaison spécifique.
+            if (volatileKeys.has(key)) return;
+
+            // On ne compare que les clés qui ont un poids défini.
+            const weight = weights[key];
+            // The check must be for `undefined` to allow keys that have a legitimate weight of 0.
+            // The previous `!weight` check would incorrectly exclude them, potentially leading to a totalWeight of 0
+            // and a similarity score of NaN, which evaluates to 0. This is the fix.
+            if (weight === undefined) return;
+
+            totalWeight += weight; // N'incrémenter que si la clé est pertinente.
+            if (map1.get(key) === map2.get(key)) {
+                weightedMatches += weight;
+            }
+        });
+
+        return totalWeight === 0 ? 0 : weightedMatches / totalWeight;
+    }
 }

package/fingerprint.client.js

@@ -220,6 +220,9 @@ const ClientLibrary = {
      * @returns {ClientBehaviorMetrics}
      */
     getClientBehaviorMetrics() {
+        // Add history length as a behavioral signal.
+        metrics.historyLength = window.history.length;
+
         // Ajoute un timestamp au moment de la collecte pour la détection de rejeu.
         metrics.clientTimestamp = Date.now();
 
@@ -438,6 +441,7 @@ const ClientLibrary = {
  * @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é.
+ * @property {number} historyLength - La longueur de l'historique de session du navigateur (`window.history.length`).
  * @property {number} clientTimestamp - Timestamp (Date.now()) de la collecte des métriques.
  */
 
@@ -446,6 +450,7 @@ const metrics = {
     mouseEntropy: 0,
     keystrokeLatency: 0,
     honeypotInteraction: false,
+    historyLength: 0,
     clientTimestamp: 0,
 };