@anonympins/fingerprint 0.0.8 → 0.1.0

package/README.md

@@ -25,7 +25,7 @@ The process unfolds in three steps:
     *   **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.
 
-Once the challenge is solved, a clearance "ticket" is issued via a secure cookie, exempting the user from new challenges for a set period.
+Once the challenge is solved, a clearance "ticket" is issued via a secure cookie, exempting the user from new challenges for a set period. For API clients, the challenge is delivered as a `429` JSON response, and the client is expected to solve it and retry the request.
 
 ## Features
 
@@ -81,21 +81,33 @@ const securityConfig = {
         headerAnomalyScore: 0.1, // Penalizes abnormal headers (missing UA, etc.)
         requestPatternScore: 0.6,// Penalizes bot-like request sequences (scraping, etc.)
         inconsistencyScore: 0.8, // Strongly penalizes inconsistency between the current and initial fingerprint (stolen cookie)
+        behaviorScore: 0.7,    // Penalizes non-human interactions (no mouse/keyboard activity)
         honeypotScore: 1.0       // Strongly penalizes bots filling hidden form fields
     },
+    // A new, non-suspicious device will always have its score adjusted to a minimum of 1, ensuring it receives a minimal, almost imperceptible challenge on its first visit.
     thresholds: {
         low: 20,    // Score from which a CPU challenge is issued
         medium: 45, // Score for a more difficult combined CPU/Memory challenge
         high: 75,   // Score for a very difficult challenge
         block: 95,  // Score above which the request is blocked outright (HTTP 403)
-        isStaticResource: (req) => req.path.startsWith('/static/') // Optional: Custom function to identify static resources
+        isStaticResource: (req) => req.path.startsWith('/static/'), // Optional: Custom function to identify static resources
+        isApiRequest: (req) => req.path.startsWith('/api/') || req.headers.accept?.includes('application/json') // Optional: Custom function to identify API requests
     },
+    // (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.
+    deviceIdCookieMaxAge: undefined, // By default, it's a session cookie. Set a value in ms for a persistent cookie.
+
     patterns: { // (Optional) Initial values for request pattern detection, optimized by auto-tuner if enabled.
-        velocityThreshold: 200, // ms between requests to be considered "fast"
-        burstThreshold: 500,    // 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
+        velocityThreshold: 200,   // ms between requests to be considered "fast"
+        burstThreshold: 500,      // ms for identical requests to be a "burst"
+        scrapeThreshold: 1000,    // ms for sequential requests to be "scraping"
+        scrapeBurstWeight: 40,    // Additional weight for repeated scraping patterns
+        sequenceLength: 3,        // Length of a request sequence to detect (e.g., A->B->C)
+        sequenceWeight: 60,       // Penalty for repeating a sequence
+        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
     },
     honeypot: {
         // List of field names that are traps for bots.
@@ -140,10 +152,10 @@ const securityConfig = {
         // Useful for internal tools, trusted partners, or monitoring services.
         // This check is performed first for maximum efficiency.
         { type: 'allowlist', entries: [
-            '192.168.1.100',      // A specific internal IP
-            '203.0.113.0/24',     // A partner's network range
-            '2001:db8::/32'       // An IPv6 range
-        ]},
+                '192.168.1.100',      // A specific internal IP
+                '203.0.113.0/24',     // A partner's network range
+                '2001:db8::/32'       // An IPv6 range
+            ]},
         // Option 2: DNS-verified bots (e.g., search engine crawlers).
         // This uses a secure DNS lookup (reverse then forward) to verify the bot's identity.
         // The result is cached per IP to avoid repeated DNS lookups.
@@ -198,17 +210,41 @@ The main Express middleware. It orchestrates identification, suspicion calculati
 
 #### `configureStore(store)`
 Allows replacing the in-memory store with an external datastore (like Redis) for persistence and scaling.
+The library provides ready-to-use adapters for popular datastores like Redis and MongoDB, which automatically handle the Time-To-Live (TTL) required for temporary data like challenge secrets.
 
-See the Datastore Integration Guide for a complete example of creating a Redis store.
+**Redis Example:**
 
 ```javascript
 import { configureStore } from './fingerprint.js';
-import { createRedisStore } from './redis-store.js'; // Assuming a redis store implementation exists
+import { createRedisStore } from './redis-store.js';
+import Redis from 'ioredis';
 
-const redisStore = createRedisStore(process.env.REDIS_URL);
+const redisClient = new Redis(process.env.REDIS_URL);
+const redisStore = createRedisStore(redisClient);
 configureStore(redisStore);
 ```
 
+**MongoDB Example:**
+
+```javascript
+import { configureStore } from './fingerprint.js';
+import { createMongoDbStore } from './mongodb-store.js';
+import { MongoClient } from 'mongodb';
+
+const mongoClient = new MongoClient(process.env.MONGODB_URL);
+
+// It's recommended to connect before your application starts listening.
+await mongoClient.connect(); 
+
+const mongoStore = createMongoDbStore(mongoClient.db('your-db-name'), 'sessions'); // 'sessions' is the collection name
+configureStore(mongoStore);
+
+// IMPORTANT: For automatic expiration of challenges and other temporary data to work,
+// you must create a TTL index on the `expiresAt` field in your MongoDB collection.
+// Run this command in the mongo shell:
+// db.sessions.createIndex({ "expiresAt": 1 }, { expireAfterSeconds: 0 })
+```
+
 #### `identifyRequest(req, res)`
 An asynchronous function that returns an identification string for a given request, based on its suspicion level (`device:<id>`, `suspicious_medium:<ip>`, etc.). Useful for integration with a custom rate-limiter.
 
@@ -300,34 +336,35 @@ To simplify setup, all client-side features can be enabled and configured throug
 
 ```javascript
 import { initializeClient } from './path/to/fingerprint.client.js';
-
-// --- EXAMPLES ---
-
-// Example 1: Enable all default protections and protect same-origin fetch requests.
+ 
+/**
+ * Initializes all client-side protections.
+ * This is the recommended way to set up the client-side library.
+ */
 initializeClient({
-  honeypots: ['email_confirm', 'user_nickname'], // Your honeypot field names
-  fetch: {} // An empty object enables fetch protection for same-origin
-});
-
-// Example 2: Enable everything and protect a specific API domain.
-initializeClient({
-  honeypots: ['email_confirm'],
+  // (Optional, default: true) Enable mouse movement tracking to detect non-human patterns.
+  // Set to `false` to disable.
+  mouse: true,
+ 
+  // (Optional, default: true) Enable keystroke dynamics tracking (timing between key presses).
+  // Set to `false` to disable.
+  keystrokes: true,
+ 
+  // (Optional) An array of `name` attributes for hidden form fields that act as bot traps.
+  honeypots: ['email_confirm', 'user_nickname', 'website_url'],
+ 
+  // (Optional) Enables automatic protection for `fetch` requests.
+  // If the `fetch` object is present, the protection is active.
   fetch: {
-    targetDomains: ['api.yourdomain.com']
+    // (Optional) An array of domains to protect. If empty or not provided, it protects same-origin requests by default.
+    targetDomains: ['api.yourdomain.com', 'auth.yourdomain.com'],
+    
+    // (Optional, default: true) If enabled, the client will automatically intercept 429 challenge responses,
+    // solve the PoW in the background, and retry the original request with the solution.
+    // This makes the protection seamless for API clients that use this library.
+    handleChallenges: true
   }
 });
-
-// Example 3: Enable only mouse and keystroke tracking, without patching fetch.
-initializeClient({
-  mouse: true,
-  keystrokes: true
-});
-
-// Example 4: Disable keystroke tracking but keep other defaults.
-initializeClient({
-  keystrokes: false,
-  fetch: {}
-});
 ```
 
 ### Client-Side Behavioral Analysis
@@ -352,15 +389,15 @@ This provides a proactive, first-line defense against simple bots. By setting up
 If you prefer not to modify global functions or need fine-grained control over which requests are protected, you can use the `protectedFetch` wrapper. You must use this function instead of the standard `fetch` for your API calls.
 
 - **`protectedFetch(resource, options)`**: A wrapper around the native `fetch` API that automatically enriches requests with security headers. It adds:
-  - `X-Device-Fingerprint`: The client's device fingerprint.
-  - `X-Behavior-Metrics`: A JSON string containing the metrics collected by the behavioral trackers (e.g., mouse entropy, honeypot interaction).
+    - `X-Device-Fingerprint`: The client's device fingerprint.
+    - `X-Behavior-Metrics`: A JSON string containing the metrics collected by the behavioral trackers (e.g., mouse entropy, honeypot interaction).
 
 **Example:**
 
 ```javascript
-import { 
-  initializeClient,
-  protectedFetch 
+import {
+    initializeClient,
+    protectedFetch
 } from './path/to/fingerprint.client.js';
 
 // Start tracking user behavior as soon as the app loads.

package/fingerprint.builder.js

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

package/fingerprint.client.js

@@ -1,4 +1,5 @@
 import { cyrb53, FingerprintBuilder } from './fingerprint.builder.js';
+import { solveChallenge } from './pow.solver.js';
 
 const ClientLibrary = {
     // Cache pour éviter de recalculer les constantes (Hardware, etc.)
@@ -320,6 +321,44 @@ const ClientLibrary = {
     this.addFetchInterceptor(fingerprintInterceptor);
   },
   
+  /**
+   * Intercepte une réponse de challenge JSON, le résout, et réessaie la requête.
+   * @param {Response} response - La réponse initiale (potentiellement 429).
+   * @param {RequestInfo} resource - La ressource de la requête originale.
+   * @param {RequestInit} options - Les options de la requête originale.
+   * @returns {Promise<Response>} - La réponse de la requête réessayée.
+   * @private
+   */
+  async solveChallengeAndRetry(response, resource, options) {
+    if (response.status !== 429) {
+      return response;
+    }
+
+    try {
+      const challengeData = await response.json();
+      if (!challengeData.challenge || !challengeData.challenge.type) {
+        return response; // Pas un challenge JSON valide
+      }
+
+      console.log(`[Fingerprint] Received a '${challengeData.challenge.type}' challenge. Solving...`);
+      const solution = await solveChallenge(challengeData.challenge);
+      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);
+      url.searchParams.set('pow_type', challengeData.challenge.type);
+      url.searchParams.set('pow_nonce', challengeData.challenge.nonce);
+      // La solution peut être un objet (pour les challenges combinés) ou une valeur simple
+      Object.entries(solution).forEach(([key, value]) => {
+        url.searchParams.set(`pow_solution_${key}`, value);
+      });
+
+      return this._originalFetch(url.toString(), options);
+    } catch (e) {
+      console.error('[Fingerprint] Failed to solve or retry challenge:', e);
+      return response; // Retourne la réponse 429 originale en cas d'échec
+    }
+  },
 /**
  * @typedef {object} ClientConfig
  * @property {boolean} [mouse=true] - Activer le suivi de l'entropie de la souris.
@@ -339,7 +378,7 @@ const ClientLibrary = {
         mouse = true,
         keystrokes = true,
         honeypots = [],
-        fetch: fetchConfig,
+        fetch: fetchConfig = {},
     } = config;
 
     if (mouse) {
@@ -351,8 +390,17 @@ const ClientLibrary = {
     if (honeypots.length > 0) {
         this.initializeHoneypots(honeypots);
     }
-    if (fetchConfig !== undefined) {
+    // On vérifie si l'objet fetch est présent pour activer l'interception
+    if (Object.keys(fetchConfig).length > 0 || config.fetch) {
         this.initializeFetch(fetchConfig.targetDomains);
+
+        // 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);
+          });
+        }
     }
   }
 };
@@ -394,6 +442,7 @@ export const addFetchInterceptor = ClientLibrary.addFetchInterceptor.bind(Client
 export const patchGlobalFetch = ClientLibrary.patchGlobalFetch.bind(ClientLibrary);
 export const initializeFetch = ClientLibrary.initializeFetch.bind(ClientLibrary);
 export const initializeClient = ClientLibrary.initializeClient.bind(ClientLibrary);
+export const solveChallengeAndRetry = ClientLibrary.solveChallengeAndRetry.bind(ClientLibrary);
 
 // Export the internal object for testing purposes
 export default ClientLibrary;