@anonympins/fingerprint 0.3.2 → 0.3.3

package/package.json

@@ -1,33 +1,38 @@
 {
   "name": "@anonympins/fingerprint",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Advanced anti-bot library for Node.js using multi-layer fingerprinting (JA3, client-side, headers), behavioral analysis, and adaptive Proof-of-Work (PoW) challenges to mitigate scraping, scalping, and automated threats.",
-  "main": "fingerprint.js",
+  "main": "index.js",
   "type": "module",
   "engines": {
     "node": ">=20.0.0"
   },
   "scripts": {
     "test": "vitest run --reporter=verbose",
-    "build": "node build-client.js"
+    "build": "node src/js/build-client.js"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./client": {
+      "import": "./src/js/fingerprint.client.obfuscated.js",
+      "require": "./src/js/fingerprint.client.obfuscated.js",
+      "browser": "./src/js/fingerprint.client.obfuscated.js"
+    },
+    "./client/src/*": "./src/js/*",
+    "./fp.wasm": "./public/fp.wasm",
+    "./fp.js": "./public/fp.js",
+    "./package.json": "./package.json"
   },
   "files": [
-    "fingerprint.js",
-    "fingerprint.client.js",
-    "fingerprint.client.obfuscated.js",
-    "fingerprint.builder.js",
-    "pow.solver.js",
-    "pow.worker.js",
-    "pow.solver.inline.js",
-    "problem-manager.js",
-    "optimization.worker.js",
-    "library.js",
-    "redis-store.js",
-    "mongodb-store.js",
-    "sql-store.js", 
-    "public/fp.wasm",
+    "index.js",
+    "src/js/",
+    "public/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md",
+    "src/php/",
+    "composer.json",
+    "phpunit.xml"
   ],
   "repository": {
     "type": "git",

package/phpunit.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.6/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true">
+    <testsuites>
+        <testsuite name="default">
+            <directory>src/php/Tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <coverage>
+        <include>
+            <directory suffix=".php">./src/php</directory>
+        </include>
+        <exclude>
+            <directory>./src/php/Tests</directory>
+        </exclude>
+    </coverage>
+</phpunit>

package/public/fp.js

@@ -0,0 +1,2 @@
+var createFingerprintModule=(()=>{var _scriptName=globalThis.document?.currentScript?.src;return async function(moduleArg={}){var Module=moduleArg;var ENVIRONMENT_IS_WEB=!!globalThis.window;var ENVIRONMENT_IS_WORKER=!!globalThis.WorkerGlobalScope;var ENVIRONMENT_IS_NODE=globalThis.process?.versions?.node&&globalThis.process?.type!="renderer";var programArgs=[];var thisProgram="./this.program";var quit_=(status,toThrow)=>{throw toThrow};if(typeof __filename!="undefined"){_scriptName=__filename}else if(ENVIRONMENT_IS_WORKER){_scriptName=self.location.href}var scriptDirectory="";function locateFile(path){if(Module["locateFile"]){return Module["locateFile"](path,scriptDirectory)}return scriptDirectory+path}var readAsync,readBinary;if(ENVIRONMENT_IS_NODE){var fs=require("node:fs");scriptDirectory=__dirname+"/";readBinary=filename=>{filename=isFileURI(filename)?new URL(filename):filename;var ret=fs.readFileSync(filename);return ret};readAsync=async(filename,binary=true)=>{filename=isFileURI(filename)?new URL(filename):filename;var ret=fs.readFileSync(filename,binary?undefined:"utf8");return ret};if(process.argv.length>1){thisProgram=process.argv[1].replace(/\\/g,"/")}programArgs=process.argv.slice(2);quit_=(status,toThrow)=>{process.exitCode=status;throw toThrow}}else if(ENVIRONMENT_IS_WEB||ENVIRONMENT_IS_WORKER){try{scriptDirectory=new URL(".",_scriptName).href}catch{}{if(ENVIRONMENT_IS_WORKER){readBinary=url=>{var xhr=new XMLHttpRequest;xhr.open("GET",url,false);xhr.responseType="arraybuffer";xhr.send(null);return new Uint8Array(xhr.response)}}readAsync=async url=>{if(isFileURI(url)){return new Promise((resolve,reject)=>{var xhr=new XMLHttpRequest;xhr.open("GET",url,true);xhr.responseType="arraybuffer";xhr.onload=()=>{if(xhr.status==200||xhr.status==0&&xhr.response){resolve(xhr.response);return}reject(xhr.status)};xhr.onerror=reject;xhr.send(null)})}var response=await fetch(url,{credentials:"same-origin"});if(response.ok){return response.arrayBuffer()}throw new Error(response.status+" : "+response.url)}}}else{}var out=console.log.bind(console);var err=console.error.bind(console);var wasmBinary;var ABORT=false;var isFileURI=filename=>filename.startsWith("file://");class EmscriptenEH{}class EmscriptenSjLj extends EmscriptenEH{}var runtimeInitialized=false;function updateMemoryViews(){var b=wasmMemory.buffer;HEAP8=new Int8Array(b);HEAPU8=new Uint8Array(b);HEAPU32=new Uint32Array(b)}function preRun(){var preRun=Module["preRun"];if(preRun){if(typeof preRun=="function")preRun=[preRun];onPreRuns.push(...preRun)}callRuntimeCallbacks(onPreRuns)}function initRuntime(){runtimeInitialized=true;wasmExports["e"]()}function postRun(){var postRun=Module["postRun"];if(postRun){if(typeof postRun=="function")postRun=[postRun];onPostRuns.push(...postRun)}callRuntimeCallbacks(onPostRuns)}function abort(what){Module["onAbort"]?.(what);what=`Aborted(${what})`;err(what);ABORT=true;what+=". Build with -sASSERTIONS for more info.";var e=new WebAssembly.RuntimeError(what);throw e}var wasmBinaryFile;function findWasmBinary(){return locateFile("fp.wasm")}function getBinarySync(file){if(readBinary){return readBinary(file)}throw"both async and sync fetching of the wasm failed"}async function getWasmBinary(binaryFile){if(!wasmBinary){try{var response=await readAsync(binaryFile);return new Uint8Array(response)}catch{}}return getBinarySync(binaryFile)}async function instantiateArrayBuffer(binaryFile,imports){try{var binary=await getWasmBinary(binaryFile);var instance=await WebAssembly.instantiate(binary,imports);return instance}catch(reason){err(`failed to asynchronously prepare wasm: ${reason}`);abort(reason)}}async function instantiateAsync(binary,binaryFile,imports){if(!binary&&!isFileURI(binaryFile)&&!ENVIRONMENT_IS_NODE){try{var response=fetch(binaryFile,{credentials:"same-origin"});var instantiationResult=await WebAssembly.instantiateStreaming(response,imports);return instantiationResult}catch(reason){err(`wasm streaming compile failed: ${reason}`);err("falling back to ArrayBuffer instantiation")}}return instantiateArrayBuffer(binaryFile,imports)}function getWasmImports(){var imports={a:wasmImports};return imports}async function createWasm(){function receiveInstance(instance){wasmExports=instance.exports;assignWasmExports(wasmExports);updateMemoryViews();return wasmExports}function receiveInstantiationResult(result){return receiveInstance(result["instance"])}var info=getWasmImports();var instantiateWasm=Module["instantiateWasm"];if(instantiateWasm){return new Promise(resolve=>{instantiateWasm(info,inst=>resolve(receiveInstance(inst)))})}wasmBinaryFile??=findWasmBinary();var result=await instantiateAsync(wasmBinary,wasmBinaryFile,info);var exports=receiveInstantiationResult(result);return exports}class ExitStatus{name="ExitStatus";constructor(status){this.message=`Program terminated with exit(${status})`;this.status=status}}var callRuntimeCallbacks=callbacks=>{while(callbacks.length>0){callbacks.shift()(Module)}};var onPostRuns=[];var onPreRuns=[];var noExitRuntime=true;var HEAP8;var HEAPU32;class ExceptionInfo{constructor(excPtr){this.excPtr=excPtr;this.ptr=excPtr-24}set_type(type){HEAPU32[this.ptr+4>>2]=type}get_type(){return HEAPU32[this.ptr+4>>2]}set_destructor(destructor){HEAPU32[this.ptr+8>>2]=destructor}get_destructor(){return HEAPU32[this.ptr+8>>2]}set_caught(caught){caught=caught?1:0;HEAP8[this.ptr+12]=caught}get_caught(){return HEAP8[this.ptr+12]!=0}set_rethrown(rethrown){rethrown=rethrown?1:0;HEAP8[this.ptr+13]=rethrown}get_rethrown(){return HEAP8[this.ptr+13]!=0}init(type,destructor){this.set_adjusted_ptr(0);this.set_type(type);this.set_destructor(destructor)}set_adjusted_ptr(adjustedPtr){HEAPU32[this.ptr+16>>2]=adjustedPtr}get_adjusted_ptr(){return HEAPU32[this.ptr+16>>2]}}var uncaughtExceptionCount=0;var __Unwind_RaiseException=ex=>{abort()};var ___cxa_throw=(ptr,type,destructor)=>{var info=new ExceptionInfo(ptr);info.init(type,destructor);uncaughtExceptionCount++;__Unwind_RaiseException(ptr)};var __abort_js=()=>abort("");var abortOnCannotGrowMemory=requestedSize=>{abort("OOM")};var HEAPU8;var _emscripten_resize_heap=requestedSize=>{var oldSize=HEAPU8.length;requestedSize>>>=0;abortOnCannotGrowMemory(requestedSize)};{if(Module["noExitRuntime"])noExitRuntime=Module["noExitRuntime"];if(Module["print"])out=Module["print"];if(Module["printErr"])err=Module["printErr"];if(Module["arguments"])programArgs=Module["arguments"];if(Module["thisProgram"])thisProgram=Module["thisProgram"];var preInit=Module["preInit"];if(preInit){if(typeof preInit=="function")Module["preInit"]=preInit=[preInit];while(preInit.length>0){preInit.shift()()}}}var _hash_string,memory,__indirect_function_table,wasmMemory;function assignWasmExports(wasmExports){_hash_string=Module["_hash_string"]=wasmExports["f"];memory=wasmMemory=wasmExports["d"];__indirect_function_table=wasmExports["__indirect_function_table"]}var wasmImports={c:___cxa_throw,a:__abort_js,b:_emscripten_resize_heap};async function run(){preRun();var setStatus=Module["setStatus"];if(setStatus){setStatus("Running...");await new Promise(resolve=>setTimeout(resolve,1));setTimeout(setStatus,1,"")}if(ABORT)return;initRuntime();Module["onRuntimeInitialized"]?.();postRun()}var wasmExports;wasmExports=await createWasm();await run();
+;return Module}})();if(typeof exports==="object"&&typeof module==="object"){module.exports=createFingerprintModule;module.exports.default=createFingerprintModule}else if(typeof define==="function"&&define["amd"])define([],()=>createFingerprintModule);

package/src/js/build-client.js

@@ -0,0 +1,69 @@
+import { promises as fs } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { exec } from 'node:child_process';
+import JavaScriptObfuscator from 'javascript-obfuscator';
+import { minify } from 'terser';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Tente d'exécuter la commande de build pour le module WASM.
+ * Ne bloque pas le build si la commande échoue (ex: em++ non trouvé).
+ */
+function buildWasm() {
+  return new Promise((resolve) => {
+    console.log('Attempting to build WASM module (optional)...');
+    const command = "em++ src/cpp/main.cpp src/cpp/utils.cpp -o public/fp.js -s WASM=1 -s MODULARIZE=1 -s EXPORT_NAME='createFingerprintModule' -s \"EXPORTED_FUNCTIONS=['_hash_string']\" -O3 --no-entry";
+    
+    exec(command, (error, stdout, stderr) => {
+      if (error) {
+        console.warn('WASM build failed (this is optional and can be ignored):', stderr);
+      } else {
+        console.log('WASM module built successfully.');
+      }
+      resolve(); // Toujours résoudre la promesse pour ne pas bloquer le build principal.
+    });
+  });
+}
+
+async function buildClientScript() {
+  try {
+    console.log('Reading client script...');
+    const clientScriptPath = join(__dirname, 'fingerprint.client.js');
+    const clientScriptContent = await fs.readFile(clientScriptPath, 'utf-8');
+
+    console.log('Obfuscating client script...');
+    const obfuscationResult = JavaScriptObfuscator.obfuscate(clientScriptContent, {
+      compact: true,
+      controlFlowFlattening: true, // Aplatit le flux de contrôle
+      deadCodeInjection: true, // Injecte du code mort
+      stringArray: true,
+      stringArrayRotate: true, // Fait tourner le tableau de chaînes
+      stringArrayShuffle: true, // Mélange le tableau de chaînes
+      // L'utilisation d'une graine (seed) de 0 signifie que l'obfuscation sera déterministe
+      // pour une même entrée. Pour une obfuscation unique à chaque build, on peut utiliser
+      // une graine aléatoire, par exemple : seed: Math.random()
+      seed: Math.random(),
+      selfDefending: true,
+    });
+
+    const obfuscatedCode = obfuscationResult.getObfuscatedCode();
+
+    console.log('Writing obfuscated script to fingerprint.client.obfuscated.js...');
+    await fs.writeFile(join(__dirname, './fingerprint.client.obfuscated.js'), obfuscatedCode);
+
+    console.log('Client script build process completed successfully.');
+  } catch (error) {
+    console.error('Error during client script build:', error);
+    process.exit(1);
+  }
+}
+
+async function main() {
+  await buildClientScript();
+  await buildWasm();
+}
+
+main();

package/{fingerprint.builder.js → src/js/fingerprint.builder.js}

@@ -1,176 +1,169 @@
-/**
- * Algorithme de hachage cyrb53 (rapide et faible taux de collision).
- */
-// Exporté pour être utilisé comme fallback par fingerprint.client.js
-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() {
-        // Le hasher est maintenant une propriété pour pouvoir être surchargé par le client WASM.
-        this.components = new Map();
-        // FIX: Initialiser le hasher par défaut à l'implémentation JS.
-        this.hasher = cyrb53;
-    }
-
-    /**
-     * 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, this.hasher(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;
-    }
+/**
+ * Algorithme de hachage cyrb53 (rapide et faible taux de collision).
+ */
+// Exporté pour être utilisé comme fallback par fingerprint.client.js
+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() {
+        // Le hasher est maintenant une propriété pour pouvoir être surchargé par le client WASM.
+        this.components = new Map();
+        // FIX: Initialiser le hasher par défaut à l'implémentation JS.
+        this.hasher = cyrb53;
+    }
+
+    /**
+     * 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, this.hasher(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);
+
+        const volatileKeys = new Set([
+            'ch_ua', 'ch_platform', 'ch_mobile', 'ch_model', 'ch_arch', 'ch_bitness',
+            'cookie_keys', 'upgrade',
+            'network', 'http_ver',
+            '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: 3.0, // HTTP/2 settings frame fingerprint
+            tcp: 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;
+            }
+
+            const weight = weights[key] ?? 0;
+            // On ne compte une clé dans le poids total que si elle est présente dans au moins une des deux empreintes.
+            if (!map1.has(key) && !map2.has(key)) 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;
+    }
 }