@anonympins/fingerprint 0.2.0 → 0.2.2

package/README.md

@@ -63,6 +63,8 @@ export POW_SECRET="your_secret_key_of_at_least_32_characters"
 
 The `powMiddleware` requires a configuration object defining the weights of suspicion indicators and the challenge trigger thresholds.
 
+All following `securityConfig` parameters are optional.
+
 ```javascript
 import express from 'express';
 import bodyParser from 'body-parser';
@@ -98,6 +100,10 @@ const securityConfig = {
         high: 75,   // Score for a very difficult challenge
         block: 95,  // Score above which the request is blocked outright (HTTP 404)
     },
+    cpu: {
+        minDifficultyBits: 8,
+        maxDifficultyBits: 24,
+    },
     // (Optional) Configure the duration (in milliseconds) for various temporary data.
     ticketMaxAge: 3600000, // 1 hour. Duration for which a solved challenge ticket is valid.
     challengeTtl: 300000, // 5 minutes. Time during which a challenge nonce is valid.
@@ -106,11 +112,15 @@ const securityConfig = {
     verbose: process.env.NODE_ENV !== 'production', // Log detailed info in development, but not in production.
     patterns: { // (Optional) Initial values for request pattern detection, optimized by auto-tuner if enabled.
         velocityThreshold: 800,   // ms between requests to be considered "fast"
-        burstThreshold: 1500,      // ms for identical requests to be a "burst"
+        burstThreshold: 1500,     // ms for identical requests to be a "burst"
         scrapeThreshold: 1000,    // ms for sequential requests to be "scraping"
         historySize: 10,          // Number of requests to keep for pattern analysis
-        decayFactor: 0.9,         // How quickly the pattern score decays over time
-        inactivityReset: 30000,   // ms of inactivity after which the pattern score is reset
+        minSamples: 5,            // Minimum number of timings to collect before statistical analysis.
+        regularityThreshold: 50,  // Standard deviation (ms) below which behavior is "too regular".
+        benfordThreshold: 0.15,   // Benford's Law deviation threshold above which the distribution is "unnatural".
+        patternWeight: 80,        // Strong, one-time penalty when a pattern is detected.
+        decayFactor: 0.9,         // Factor by which the pattern score decreases over time.
+        inactivityReset: 5000,    // Time (ms) after which the pattern score is reset.
     },
     honeypot: {
         // List of field names that are traps for bots.
@@ -152,6 +162,9 @@ const securityConfig = {
                 '203.0.113.0/24',     // A partner's network range
                 '2001:db8::/32'       // An IPv6 range
             ]},
+        { type: 'hostname_allowlist', entries: [
+                'google.com',      // A specific hostname
+            ]},
         // 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.
@@ -169,7 +182,8 @@ const securityConfig = {
     autotuning: {
         trafficData: trafficData,       // The data source for the genetic algorithm.
         interval: 1800000,              // Optimization cycle every 30 minutes (in ms).
-        minDataPoints: 200              // Minimum requests before starting an optimization cycle.
+        minDataPoints: 200,              // Minimum requests before starting an optimization cycle.
+        maxDataPoints: 20000              // Minimum requests before starting an optimization cycle.
     },
     // Enables problem solving for suspicious activity (configurable in problems.config.json)
     enableUsefulWork: true
@@ -536,6 +550,48 @@ While `powMiddleware` is convenient for Express, you can use the `FingerprintEng
 
 The engine is a named export from the main module.
 
+### Useful Proof-of-Work (`ProblemManager`)
+
+Instead of issuing a generic Proof-of-Work, the system can dispatch a "useful" computational problem to a suspicious client. This allows harnessing the client's CPU cycles to solve complex problems (like optimization tasks) over time. This feature is managed by the `ProblemManager` class, which is enabled via the `enableUsefulWork: true` flag in the security configuration.
+
+The `ProblemManager` reads its configuration from `problems.config.json`, which defines the problems to be solved, the type of work units, and the current state of the solutions.
+
+While you typically won't interact with it directly, its methods are exported and can be used for monitoring or manual administration. The main instance is exported as `problemManager`.
+
+#### `problemManager.dispatchWork(suspicionFactor)`
+
+Selects a problem and generates a work unit for a client. The difficulty of the task (e.g., number of iterations) is scaled based on the client's `suspicionFactor`.
+
+*   **`suspicionFactor`** (`number`): A factor to adjust the difficulty of the work unit.
+*   **Returns**: (`object|null`) An object containing the `problemId` and the `task` to be sent to the client, or `null` if no problems are available.
+
+#### `problemManager.integrateSolution(problemId, solutionData)`
+
+Integrates a solution returned by a client into the problem's state. If the new solution is better than the existing one, it is saved as the new best solution.
+
+*   **`problemId`** (`string`): The ID of the problem being updated.
+*   **`solutionData`** (`object`): The solution data returned by the client (e.g., `{ solution, energy }`).
+
+#### `problemManager.getBestSolutions([problemId])`
+
+Retrieves the best solution currently known for one or all problems. This is useful for creating an API endpoint to view the progress of the distributed computation.
+
+*   **`problemId`** (`string`, optional): The ID of a specific problem.
+*   **Returns**: (`object|Array<object>|null`)
+    *   If a `problemId` is provided, it returns an object with the best solution for that problem (`{ id, solution, score, lastUpdate }`).
+    *   If no `problemId` is provided, it returns an array of these objects for all problems.
+
+**Example: Creating an API endpoint to view solutions**
+
+```javascript
+import { problemManager } from './fingerprint.js'; // Adjust path
+
+app.get('/api/problems/solutions', (req, res) => {
+    const solutions = problemManager.getBestSolutions();
+    res.json(solutions);
+});
+```
+
 **Workflow:**
 
 1.  **Instantiate the Engine**: Create an instance with your `securityConfig`.

package/fingerprint.builder.js

@@ -1,104 +1,161 @@
-/**
- * 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;
-    }
+/**
+ * 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;
+    }
 }

package/fingerprint.client.js

@@ -335,7 +335,7 @@ const ClientLibrary = {
    * @private
    */
   async solveChallengeAndRetry(response, resource, options) {
-    if (response.status !== 404 || !response.headers.get('content-type')?.includes('application/json')) {
+    if (response.status !== 404 || !response.headers.get('content-type')?.includes('application/json') || response.bodyUsed) {
       return response;
     }
     
@@ -346,30 +346,18 @@ const ClientLibrary = {
       }
 
       console.log(`[Fingerprint] Received a '${challengeData.challenge.type}' challenge. Solving...`);
-      const solution = await solveChallenge(challengeData.challenge);
+      // L'empreinte de l'appareil qui résout le challenge est cruciale.
+      const solverFp = this.getDeviceFingerprint();
+      const solutionWrapper = await solveChallenge(challengeData.challenge, solverFp);
       console.log('[Fingerprint] Challenge solved. Retrying original request.');
 
       // Ajouter la solution aux paramètres de la requête pour le nouvel essai
       const url = new URL((resource instanceof Request) ? resource.url : String(resource), window.location.origin);
-      // Le type de challenge est maintenant `cpu_mem` pour les API
-      url.searchParams.set('pow_type', 'cpu_mem');
-      url.searchParams.set('pow_nonce', challengeData.challenge.nonce);
-
-      // La solution est un objet { cpu: ..., mem: ... }. Le serveur attend pow_solution_cpu et pow_solution_mem.
-      Object.entries(solution).forEach(([key, value]) => {
-        url.searchParams.set(`pow_solution_${key}`, String(value));
-      });
-
-      // Pour le challenge d'optimisation, la solution est un tableau d'objets
-      if (solution.population) {
-        url.searchParams.set('pow_solution_population', JSON.stringify(solution.population));
-      }
+      // La logique de formatage est maintenant cachée dans la classe ChallengeSolution.
+      solutionWrapper.applyToUrl(url);
 
-      // Pour le challenge de travail utile
-      if (solution.work_result) {
-        url.searchParams.set('pow_solution_work_result', JSON.stringify(solution.work_result));
-        url.searchParams.set('pow_problem_id', solution.problem_id);
-      }
+      // On ajoute l'empreinte du solveur à la requête de réessai.
+      url.searchParams.set('pow_fp', solverFp);
 
       // On utilise la chaîne d'intercepteurs pour la requête réessayée,
       // ce qui garantit que le fetch original est appelé avec le bon contexte.
@@ -418,8 +406,9 @@ const ClientLibrary = {
         // Ajoute l'intercepteur pour la résolution de challenge
         if (fetchConfig.handleChallenges !== false) {
           this.addFetchInterceptor(async (resource, options, next) => {
-            const response = await next(resource, options);
-            return this.solveChallengeAndRetry(response, resource, options);
+            const originalResponse = await next(resource, options);
+            // On clone la réponse pour que la lecture du corps par solveChallengeAndRetry ne la consomme pas pour l'appelant original.
+            return this.solveChallengeAndRetry(originalResponse.clone(), resource, options);
           });
         }
     }