@anonympins/fingerprint 0.7.5 → 0.8.0

package/src/js/fingerprint.utils.js

@@ -1,5 +1,18 @@
 import {cyrb53} from "./fingerprint.builder.js";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
 
+/**
+ * Verifies a Zero-Knowledge Proof (ZKP) of the Schnorr type.
+ * The verification checks that g^s ≡ t * y^c (mod p),
+ * where c is a challenge computed by SHA-256 hashing of (g, y, t).
+ *
+ * @param {string} yStr - The public key y, hex-encoded (without the 0x prefix).
+ * @param {string} tStr - The commitment t, hex-encoded (without the 0x prefix).
+ * @param {string} sStr - The response s, hex-encoded (without the 0x prefix).
+ * @returns {boolean} True if the proof is valid, false otherwise (or on error).
+ */
 export function verifyZkpProof(yStr, tStr, sStr) {
     try {
         const y = BigInt('0x' + yStr);
@@ -19,6 +32,14 @@ export function verifyZkpProof(yStr, tStr, sStr) {
     }
 }
 
+/**
+ * Serializes a value to JSON while escaping dangerous characters
+ * for safe inclusion in HTML/JS (XSS prevention).
+ * Escapes <, >, U+2028, and U+2029.
+ *
+ * @param {*} val - The value to serialize.
+ * @returns {string} The escaped JSON string.
+ */
 export function safeJsonStringify(val) {
     return JSON.stringify(val)
         .replace(/</g, '\\u003c')
@@ -27,6 +48,16 @@ export function safeJsonStringify(val) {
         .replace(/\u2029/g, '\\u2029');
 }
 
+/**
+ * Sanitizes and validates a redirect path to prevent open redirects.
+ * - Strips out disallowed characters.
+ * - Prevents protocol-relative redirects (//evil.com).
+ * - Prevents absolute redirects (http://evil.com).
+ * - Ensures the path starts with a single '/'.
+ *
+ * @param {string} p - The raw redirect path.
+ * @returns {string} The sanitized path (or '/' by default).
+ */
 export function sanitizeRedirectPath(p) {
     if (typeof p !== 'string') return '/';
     let sanitized = p.replace(/[^a-zA-Z0-9\/.\-_~%?&=:@+,;]/g, '');
@@ -49,6 +80,16 @@ export function sanitizeRedirectPath(p) {
     }
     return sanitized.replace(/^\/+/g, '/');
 }
+
+/**
+ * Decodes a polymorphic fingerprint by restoring the original keys
+ * from a mapping of randomized keys.
+ * Expected format: "randKey: value|randKey: value|...".
+ *
+ * @param {string} fpString - The encoded fingerprint.
+ * @param {object} mapping - The mapping object containing `keys` (orig -> rand).
+ * @returns {string} The decoded fingerprint with original keys.
+ */
 export function decodePolymorphicFingerprint(fpString, mapping) {
     if (!fpString || !mapping || !mapping.keys) return fpString;
     const reverseKeys = {};
@@ -67,6 +108,130 @@ export function decodePolymorphicFingerprint(fpString, mapping) {
     return mappedParts.join('|');
 }
 
+/**
+ * Extracts and parses a Private Access Token (PAT / Privacy Pass / RFC 9578).
+ * Supports 'Authorization: PrivateToken token="..."' and 'Sec-Private-State-Token'.
+ *
+ * @param {object} headers - HTTP request headers object.
+ * @returns {Array<Uint8Array>} Array of raw binary tokens.
+ */
+export function extractPrivateAccessTokens(headers) {
+    if (!headers) return [];
+    const tokens = [];
+
+    const authHeader = headers['authorization'] || headers['Authorization'];
+    if (typeof authHeader === 'string' && authHeader.toLowerCase().startsWith('privatetoken ')) {
+        const match = authHeader.match(/token=(?:"([^"]+)"|([a-zA-Z0-9_\-+/=]+))/i);
+        if (match) {
+            const rawB64 = match[1] || match[2];
+            try {
+                tokens.push(Buffer.from(rawB64.replace(/-/g, '+').replace(/_/g, '/'), 'base64'));
+            } catch (e) {}
+        }
+    }
+
+    const pstHeader = headers['sec-private-state-token'] || headers['Sec-Private-State-Token'];
+    if (typeof pstHeader === 'string') {
+        const parts = pstHeader.split(',');
+        for (const part of parts) {
+            const trimmed = part.trim();
+            if (trimmed) {
+                try {
+                    tokens.push(Buffer.from(trimmed.replace(/-/g, '+').replace(/_/g, '/'), 'base64'));
+                } catch (e) {}
+            }
+        }
+    }
+
+    return tokens;
+}
+
+/**
+ * Decodes an RFC 9578 Token structure:
+ * uint16_t token_type (2 bytes)
+ * uint8_t nonce[32] (32 bytes)
+ * uint8_t challenge_digest[32] (32 bytes)
+ * uint8_t token_key_id[32] (32 bytes)
+ * uint8_t authenticator[Nk] (>= 32 bytes)
+ *
+ * @param {Uint8Array|Buffer} buffer
+ * @returns {object|null}
+ */
+export function parsePrivateAccessToken(buffer) {
+    if (!buffer || buffer.length < 98) return null; // 2 + 32 + 32 + 32 = 98 min
+
+    const view = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer);
+    const tokenType = view.readUInt16BE(0);
+    const nonce = view.subarray(2, 34);
+    const challengeDigest = view.subarray(34, 66);
+    const tokenKeyId = view.subarray(66, 98);
+    const authenticator = view.subarray(98);
+
+    if (authenticator.length === 0) return null;
+
+    return {
+        tokenType,
+        nonce: nonce.toString('hex'),
+        challengeDigest: challengeDigest.toString('hex'),
+        tokenKeyId: tokenKeyId.toString('hex'),
+        authenticator,
+        signedData: view.subarray(0, 98)
+    };
+}
+
+/**
+ * Validates a decoded Private Access Token signature against configured public keys.
+ *
+ * @param {object} parsedToken - Output from parsePrivateAccessToken.
+ * @param {object} patConfig - Configuration with trustedKeys mapping.
+ * @returns {boolean} True if signature is cryptographically valid.
+ */
+export function verifyPatSignature(parsedToken, patConfig = {}) {
+    if (!parsedToken) return false;
+    const trustedKeys = patConfig.trustedKeys || {};
+    const keyId = parsedToken.tokenKeyId;
+    const publicKey = trustedKeys[keyId] || trustedKeys[keyId.toLowerCase()] || patConfig.defaultPublicKey;
+
+    if (!publicKey) {
+        return false;
+    }
+
+    const { tokenType, signedData, authenticator } = parsedToken;
+
+    try {
+        // Type 0x0001 (Blind RSA 2048) / 0x0002 (Rate-Limited Blind RSA)
+        if (tokenType === 0x0001 || tokenType === 0x0002 || tokenType === 1 || tokenType === 2) {
+            // Try RSA-PSS with SHA-384 (RFC 9577) first, fallback to SHA-256 and PKCS#1 v1.5
+            const algorithms = [
+                { hash: 'sha384', padding: crypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: 48 },
+                { hash: 'sha256', padding: crypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: 32 },
+                { hash: 'sha384', padding: crypto.constants.RSA_PKCS1_PADDING },
+                { hash: 'sha256', padding: crypto.constants.RSA_PKCS1_PADDING }
+            ];
+
+            for (const alg of algorithms) {
+                try {
+                    const verifier = crypto.createVerify(alg.hash);
+                    verifier.update(signedData);
+                    const isValid = verifier.verify({
+                        key: publicKey,
+                        padding: alg.padding,
+                        saltLength: alg.saltLength
+                    }, authenticator);
+                    if (isValid) return true;
+                } catch (verifyErr) {}
+            }
+        } else if (tokenType === 0x0003 || tokenType === 3) {
+            // VOPRF / Ed25519 authentication verification
+            try {
+                return crypto.verify(null, signedData, publicKey, authenticator);
+            } catch (voprfErr) {}
+        }
+    } catch (e) {
+        return false;
+    }
+    return false;
+}
 
 /**
  * @private
@@ -127,6 +292,15 @@ export function parseJa3(ja3String) {
     };
 }
 
+/**
+ * Computes modular exponentiation (base^exponent mod modulus) efficiently
+ * using the binary exponentiation method (square-and-multiply).
+ *
+ * @param {bigint} base - The base.
+ * @param {bigint} exponent - The exponent.
+ * @param {bigint} modulus - The modulus.
+ * @returns {bigint} The result of base^exponent mod modulus.
+ */
 export function modPow(base, exponent, modulus) {
     if (modulus === 1n) return 0n;
     let result = 1n;
@@ -142,6 +316,14 @@ export function modPow(base, exponent, modulus) {
 }
 
 
+/**
+ * Computes a simple hash of the IP network by applying a mask (CIDR prefix).
+ * For example, with a prefix of 24, only the first 3 octets are kept.
+ *
+ * @param {string} ip - The IP address in IPv4 format (e.g. "192.168.1.42").
+ * @param {number} [prefix=24] - The network prefix length (in bits).
+ * @returns {string|null} A hexadecimal hash of the network, or null if the IP is invalid.
+ */
 export function hashNetwork(ip, prefix = 24) {
     // Network hash (/24 or /16 mask)
     const parts = ip.split('.');
@@ -157,6 +339,14 @@ export function hashNetwork(ip, prefix = 24) {
     }
     return hash.toString(16);
 }
+
+/**
+ * Checks whether an IP address is a loopback address (localhost).
+ * Handles IPv4, IPv6, and the IPv4-mapped prefix (::ffff:).
+ *
+ * @param {string} ip - The IP address to test.
+ * @returns {boolean} True if the IP is a loopback address, false otherwise.
+ */
 export function isLoopbackIp(ip) {
     if (!ip || typeof ip !== 'string') return true;
     let cleanIp = ip.trim().toLowerCase();
@@ -164,9 +354,16 @@ export function isLoopbackIp(ip) {
         cleanIp = cleanIp.substring(7);
     }
     return cleanIp === '127.0.0.1' || cleanIp === '::1' || cleanIp === 'localhost' ||
-           cleanIp.startsWith('127.') || cleanIp === '0.0.0.0' || cleanIp === '::';
+        cleanIp.startsWith('127.') || cleanIp === '0.0.0.0' || cleanIp === '::';
 }
 
+/**
+ * Normalizes a referer URL by keeping only the protocol and hostname
+ * (e.g. "https://example.com").
+ *
+ * @param {string} referer - The raw referer URL.
+ * @returns {string} The normalized URL, or the original value if invalid.
+ */
 export function normalizeReferer(referer) {
     try {
         const url = new URL(referer);
@@ -176,6 +373,13 @@ export function normalizeReferer(referer) {
     }
 }
 
+/**
+ * Checks whether an IP address belongs to a private range (RFC 1918, loopback,
+ * link-local, CGNAT, etc.). Handles both IPv4 and IPv6 formats.
+ *
+ * @param {string} ip - The IP address to test.
+ * @returns {boolean} True if the IP is private, false otherwise.
+ */
 export function isPrivateIp(ip) {
     if (!ip || typeof ip !== 'string') return false;
     let cleanIp = ip.trim().toLowerCase();
@@ -200,7 +404,16 @@ export function isPrivateIp(ip) {
     }
     return false;
 }
-// Utility parsing functions
+
+/**
+ * Basic User-Agent parsing to extract:
+ * - the browser (with major version),
+ * - the operating system,
+ * - the device type (mobile, tablet, desktop).
+ *
+ * @param {string} ua - The User-Agent string.
+ * @returns {object} An object { browser?, os?, device }.
+ */
 export function parseUserAgent(ua) {
     // Basic User-Agent parser
     const result = {};
@@ -238,4 +451,41 @@ export function parseUserAgent(ua) {
     else result.device = 'desktop';
 
     return result;
+}
+
+/**
+ * Programmatically generates an Ed25519 key pair in PEM format
+ * (PKCS#8 for private key, SPKI for public key) matching OpenSSL CLI:
+ * `openssl genpkey -algorithm ed25519 -out issuer-private.pem`
+ * `openssl pkey -in issuer-private.pem -pubout -out issuer-public.pem`
+ *
+ * @param {string} [outDir='./config'] Target directory to store the PEM files.
+ * @param {object} [options={}] Optional configuration (e.g. custom file names).
+ * @returns {{privateKeyPath: string, publicKeyPath: string, privateKey: string, publicKey: string}}
+ */
+export function generateIssuerPemKeys(outDir = './config', options = {}) {
+    const privateKeyName = options.privateKeyName || 'issuer-private.pem';
+    const publicKeyName = options.publicKeyName || 'issuer-public.pem';
+
+    const { privateKey, publicKey } = crypto.generateKeyPairSync('ed25519', {
+        privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+        publicKeyEncoding: { type: 'spki', format: 'pem' }
+    });
+
+    if (!fs.existsSync(outDir)) {
+        fs.mkdirSync(outDir, { recursive: true });
+    }
+
+    const privateKeyPath = path.join(outDir, privateKeyName);
+    const publicKeyPath = path.join(outDir, publicKeyName);
+
+    fs.writeFileSync(privateKeyPath, privateKey, { mode: 0o600 });
+    fs.writeFileSync(publicKeyPath, publicKey, { mode: 0o644 });
+
+    return {
+        privateKeyPath,
+        publicKeyPath,
+        privateKey,
+        publicKey
+    };
 }

package/src/js/pow.worker.js

@@ -10,7 +10,7 @@ self.onmessage = async (event) => {
     let solution = 0;
     const encoder = new TextEncoder();
     if (baseBlock) {
-        // Mode solveCpuTargetInline (Uint8Array base block)
+        // solveCpuTargetInline mode (Uint8Array base block)
         const blockArray = new Uint8Array(baseBlock);
         while (true) {
             const solutionBytes = encoder.encode(String(solution));
@@ -31,7 +31,7 @@ self.onmessage = async (event) => {
             }
         }
     } else {
-        // Mode solveCpuTarget standard/legacy (Message string)
+        // Standard/legacy solveCpuTarget mode (Message string)
         while (true) {
             const currentMessage = `${message}:${solution}`;
             const data = encoder.encode(currentMessage);

package/src/js/tests/cross_parity.test.js

@@ -12,14 +12,14 @@ describe('Cross-Parity Chaos PoW Floating Point Parity (JS vs WASM vs PHP)', ()
     let wasmModule = null;
 
     beforeAll(async () => {
-        // Essai de compilation WASM à la volée s'il y a em++
+        // Attempt on-the-fly WASM compilation if em++ toolchain is available
         try {
             execSync('node src/js/build-client.js', { stdio: 'ignore' });
         } catch (e) {
-            // Ignorer si Emscripten n'est pas présent dans l'env
+            // Ignore if Emscripten is missing in environment
         }
 
-        // Instancier le WASM réel si compilé
+        // Instantiate compiled WASM module if available
         if (fs.existsSync(fpJsPath) && fs.existsSync(fpWasmPath)) {
             try {
                 const module = await import(fpJsPath);

package/src/js/tests/dns-circuit-breaker.test.js

@@ -9,15 +9,15 @@ describe('DNS Circuit Breaker', () => {
         dnsCircuitBreaker.failureCount = 0;
         dnsCircuitBreaker.lastStateChange = 0;
         dnsCircuitBreaker.threshold = 5;
-        dnsCircuitBreaker.cooldownMs = 1000; // 1s de cooldown pour accélérer le test unitaire
+        dnsCircuitBreaker.cooldownMs = 1000; // 1s cooldown to speed up test execution
     });
 
-    it('devrait démarrer à l\'état CLOSED et autoriser les résolutions', () => {
+    it('should start in CLOSED state and allow lookups', () => {
         expect(canAttemptDns()).toBe(true);
         expect(dnsCircuitBreaker.state).toBe('CLOSED');
     });
 
-    it('devrait s\'ouvrir après avoir atteint le seuil d\'échecs (5)', () => {
+    it('should transition to OPEN after reaching failure threshold (5)', () => {
         for (let i = 0; i < 4; i++) {
             recordDnsFailure();
             expect(canAttemptDns()).toBe(true);
@@ -29,7 +29,7 @@ describe('DNS Circuit Breaker', () => {
         expect(dnsCircuitBreaker.state).toBe('OPEN');
     });
 
-    it('devrait passer en HALF-OPEN après expiration du cooldown', async () => {
+    it('should transition to HALF-OPEN after cooldown expires', async () => {
         for (let i = 0; i < 5; i++) {
             recordDnsFailure();
         }
@@ -41,12 +41,12 @@ describe('DNS Circuit Breaker', () => {
         expect(dnsCircuitBreaker.state).toBe('HALF-OPEN');
     });
 
-    it('devrait se refermer (CLOSED) après un succès en HALF-OPEN', async () => {
+    it('should reset to CLOSED after a success while in HALF-OPEN', async () => {
         for (let i = 0; i < 5; i++) {
             recordDnsFailure();
         }
         await new Promise((resolve) => setTimeout(resolve, 1100));
-        expect(canAttemptDns()).toBe(true); // Passage en HALF-OPEN
+        expect(canAttemptDns()).toBe(true); // Transition to HALF-OPEN
 
         recordDnsSuccess();
         expect(dnsCircuitBreaker.state).toBe('CLOSED');

package/src/js/tests/fingerprint.builder.test.js

@@ -1,79 +1,77 @@
-import {describe, expect, it} from 'vitest';
-import {FingerprintBuilder} from '../fingerprint.builder.js';
-
-describe('FingerprintBuilder.compare', () => {
-
-    // Empreinte réaliste d'un utilisateur légitime (ex: Chrome sur Windows)
-    // C'est l'empreinte qui serait stockée lors de la première visite.
-    const realisticOriginalFp = new FingerprintBuilder()
-        .add('cvs', 'mock-canvas-data-v1')
-        .add('gpu', 'ANGLE (NVIDIA GeForce RTX 3080 Direct3D11 vs_5_0 ps_5_0)')
-        .add('hw', '16_8_0') // 16 cores, 8GB RAM, no touch
-        .add('os', 'Win32')
-        .add('ua', 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36')
-        .add('ja3', '771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513,29-23-24,0')
-        // En-têtes qui peuvent changer lors de la requête de résolution du challenge
-        .add('cookie_keys', '_ga,session,device_id')
-        .add('upgrade', '1')
-        .toString();
-
-    it('should return a similarity score of 1.0 for the same device with minor volatile changes', () => {
-        // Scénario de succès : L'utilisateur résout un challenge.
-        // L'empreinte du solveur est presque identique, mais certains en-têtes "volatils"
-        // (comme la présence de cookies ou 'upgrade-insecure-requests') ont changé ou disparu.
-        // La fonction `compare` est conçue pour ignorer ces clés volatiles.
-        const realisticSolverFp = new FingerprintBuilder()
-            .add('cvs', 'mock-canvas-data-v1') // Identique
-            .add('gpu', 'ANGLE (NVIDIA GeForce RTX 3080 Direct3D11 vs_5_0 ps_5_0)') // Identique
-            .add('hw', '16_8_0') // Identique
-            .add('os', 'Win32') // Identique
-            .add('ua', 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36') // Identique
-            .add('ja3', '771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513,29-23-24,0') // Identique
-            // La clé 'cookie_keys' est absente, simulant une requête sans cookies.
-            // La clé 'upgrade' est également absente.
-            .toString();
-
-        const similarity = FingerprintBuilder.compare(realisticOriginalFp, realisticSolverFp);
-
-        // La similarité doit être de 1.0 car toutes les différences concernent des clés volatiles
-        // qui sont ignorées par la comparaison.
-        expect(similarity).toBe(1.0);
-    });
-
-    it('should return a low similarity score for two completely different devices', () => {
-        // Scénario d'échec : Un attaquant a volé le cookie `device_id` et tente de
-        // résoudre un challenge depuis une machine différente (ex: un serveur Linux avec Firefox).
-        const differentSolverFp = new FingerprintBuilder()
-            .add('cvs', 'different-canvas-data') // Différent
-            .add('gpu', 'llvmpipe (LLVM 15.0.7, 256 bits)') // Différent (GPU de VM)
-            .add('hw', '8_4_0') // Différent
-            .add('os', 'Linux x86_64') // Différent
-            .add('ua', 'Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Firefox/102.0') // Différent
-            .add('ja3', '771,49195-49199-52393-52392-49196-49200-49162-49161-49171-49172-156-157-47-53,65281-11-10-35-16-5-13-51-45-43-27-23-17513,29-23-24,0') // Différent (JA3 de Firefox)
-            .toString();
-
-        const similarity = FingerprintBuilder.compare(realisticOriginalFp, differentSolverFp);
-
-        // La similarité doit être très faible (proche de 0) car tous les signaux forts sont différents.
-        expect(similarity).toBeLessThan(0.1);
-    });
-
-    it('should return 0 if one of the fingerprints is null or empty', () => {
-        expect(FingerprintBuilder.compare(realisticOriginalFp, null)).toBe(0);
-        expect(FingerprintBuilder.compare(null, realisticOriginalFp)).toBe(0);
-        expect(FingerprintBuilder.compare(realisticOriginalFp, '')).toBe(0);
-        expect(FingerprintBuilder.compare('', realisticOriginalFp)).toBe(0);
-        expect(FingerprintBuilder.compare(null, null)).toBe(0);
-    });
-
-    it('should handle fingerprints with missing components gracefully', () => {
-        const partialFp = new FingerprintBuilder()
-            .add('ua', 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36')
-            .add('os', 'Win32')
-            .toString(); // Manque GPU, canvas, etc.
-
-        const similarity = FingerprintBuilder.compare(realisticOriginalFp, partialFp);
-        expect(similarity).toBeGreaterThan(0);
-        expect(similarity).toBeLessThan(1);
-    });
+import {describe, expect, it} from 'vitest';
+import {FingerprintBuilder} from '../fingerprint.builder.js';
+
+describe('FingerprintBuilder.compare', () => {
+
+    // Realistic fingerprint for a legitimate user (e.g. Chrome on Windows)
+    // Recorded during baseline initial visit.
+    const realisticOriginalFp = new FingerprintBuilder()
+        .add('cvs', 'mock-canvas-data-v1')
+        .add('gpu', 'ANGLE (NVIDIA GeForce RTX 3080 Direct3D11 vs_5_0 ps_5_0)')
+        .add('hw', '16_8_0') // 16 cores, 8GB RAM, no touch
+        .add('os', 'Win32')
+        .add('ua', 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36')
+        .add('ja3', '771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513,29-23-24,0')
+        // Volatile headers that may legitimately change during challenge solving
+        .add('cookie_keys', '_ga,session,device_id')
+        .add('upgrade', '1')
+        .toString();
+
+    it('should return a similarity score of 1.0 for the same device with minor volatile changes', () => {
+        // Success scenario: user solves a challenge.
+        // Solver fingerprint is identical except for volatile headers
+        // (such as cookie presence or upgrade-insecure-requests) which compare ignores.
+        const realisticSolverFp = new FingerprintBuilder()
+            .add('cvs', 'mock-canvas-data-v1') // Identique
+            .add('gpu', 'ANGLE (NVIDIA GeForce RTX 3080 Direct3D11 vs_5_0 ps_5_0)') // Identique
+            .add('hw', '16_8_0') // Identique
+            .add('os', 'Win32') // Identique
+            .add('ua', 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36') // Identique
+            .add('ja3', '771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513,29-23-24,0') // Identique
+            // 'cookie_keys' is omitted, simulating a request without cookies
+            // 'upgrade' header is also omitted
+            .toString();
+
+        const similarity = FingerprintBuilder.compare(realisticOriginalFp, realisticSolverFp);
+
+        // Similarity remains 1.0 because all differences reside in ignored volatile keys
+        expect(similarity).toBe(1.0);
+    });
+
+    it('should return a low similarity score for two completely different devices', () => {
+        // Failure scenario: attacker steals device_id cookie and attempts
+        // challenge resolution from a different machine (e.g. Linux VM with Firefox).
+        const differentSolverFp = new FingerprintBuilder()
+            .add('cvs', 'different-canvas-data') // Différent
+            .add('gpu', 'llvmpipe (LLVM 15.0.7, 256 bits)') // Différent (GPU de VM)
+            .add('hw', '8_4_0') // Différent
+            .add('os', 'Linux x86_64') // Différent
+            .add('ua', 'Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Firefox/102.0') // Différent
+            .add('ja3', '771,49195-49199-52393-52392-49196-49200-49162-49161-49171-49172-156-157-47-53,65281-11-10-35-16-5-13-51-45-43-27-23-17513,29-23-24,0') // Différent (JA3 de Firefox)
+            .toString();
+
+        const similarity = FingerprintBuilder.compare(realisticOriginalFp, differentSolverFp);
+
+        // Similarity should be very low (close to 0) since invariant signals differ
+        expect(similarity).toBeLessThan(0.1);
+    });
+
+    it('should return 0 if one of the fingerprints is null or empty', () => {
+        expect(FingerprintBuilder.compare(realisticOriginalFp, null)).toBe(0);
+        expect(FingerprintBuilder.compare(null, realisticOriginalFp)).toBe(0);
+        expect(FingerprintBuilder.compare(realisticOriginalFp, '')).toBe(0);
+        expect(FingerprintBuilder.compare('', realisticOriginalFp)).toBe(0);
+        expect(FingerprintBuilder.compare(null, null)).toBe(0);
+    });
+
+    it('should handle fingerprints with missing components gracefully', () => {
+        const partialFp = new FingerprintBuilder()
+            .add('ua', 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36')
+            .add('os', 'Win32')
+            .toString(); // Missing GPU, canvas, etc.
+
+        const similarity = FingerprintBuilder.compare(realisticOriginalFp, partialFp);
+        expect(similarity).toBeGreaterThan(0);
+        expect(similarity).toBeLessThan(1);
+    });
 });