@anonympins/fingerprint 0.0.2 → 0.0.3

package/README.md

@@ -1,15 +1,15 @@
 # fingerprint
-![](https://img.shields.io/github/actions/workflow/status/anonympins/fingerprint/ci.yml)
-![](https://img.shields.io/github/v/release/anonympins/fingerprint)
-![](https://img.shields.io/github/downloads/anonympins/fingerprint/total)
-![](https://img.shields.io/github/watchers/anonympins/fingerprint)
-![](https://img.shields.io/github/license/anonympins/fingerprint)
+[![CI](https://img.shields.io/github/actions/workflow/status/anonympins/fingerprint/ci.yml)](https://github.com/anonympins/fingerprint/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/anonympins/fingerprint)](https://github.com/anonympins/fingerprint/releases)
+[![License](https://img.shields.io/github/license/anonympins/fingerprint)](https://github.com/anonympins/fingerprint/blob/main/LICENSE)
+[![Downloads](https://img.shields.io/github/downloads/anonympins/fingerprint/total)](https://github.com/anonympins/fingerprint/releases)
+[![Watchers](https://img.shields.io/github/watchers/anonympins/fingerprint)](https://github.com/anonympins/fingerprint/watchers)
 
 An HTTP(S) client mitigation and anti-bot protection library for Node.js/Express, based on digital fingerprinting and dynamic Proof-of-Work (PoW) challenges.
 
 ## How It Works
 
-This system is designed to identify and slow down bots and automated scripts by evaluating the "suspicion" level of each incoming request. Instead of outright blocking, it imposes challenges with a difficulty proportional to the suspicion score, penalizing bots without significantly impacting legitimate users.
+This system identifies and slows down bots and automated scripts by evaluating the "suspicion" level of each incoming request. Instead of outright blocking, it imposes challenges with a difficulty proportional to the suspicion score, penalizing bots without significantly impacting legitimate users.
 
 The process unfolds in three steps:
 
@@ -20,25 +20,19 @@ The process unfolds in three steps:
     *   **IP Behavior**: An excessive number of different devices seen from the same IP, or a single device using a large number of IPs (proxy rotation).
     *   **Inconsistency**: A low similarity score between the current fingerprint and the initial one associated with the `device_id` (cookie theft detection).
 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:
-    *   **Level 1 (Low Suspicion)**: CPU-based PoW challenge (SHA-256).
-    *   **Level 2 (Medium Suspicion)**: Memory-intensive PoW challenge.
-    *   **Level 3 (High Suspicion)**: Complex challenge (e.g., TSP - Traveling Salesperson Problem) or a CAPTCHA.
+    *   **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 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.
 
 ## Features
 
 -   **Multi-Factor Fingerprinting**: Combines client-side data (`hardwareConcurrency`, `deviceMemory`, `screen`, `canvas`, `webgl`) and server-side data (`User-Agent`, `Client-Hints`).
--   **Weighted Suspicion Engine**: Calculates a score based on behavioral and technical indicators.
--   **Variable-Difficulty Proof-of-Work Challenges**:
-    -   `cpu_target`: An "analog" CPU challenge where difficulty is finely tuned to the suspicion score.
-    -   `memory`: A challenge that allocates an amount of memory proportional to the suspicion level.
-    -   `tsp`: An optimization challenge (Traveling Salesperson Problem) for the most suspicious cases.
 -   **Secure Ticket System**: Uses HMAC-SHA256 signatures to validate clearances and prevent tampering.
 -   **Pluggable Datastore**: Supports external datastores like Redis for state persistence and scalability across multiple server instances.
 -   **Express.js Middleware**: Easy integration into an Express application with `powMiddleware`.
 -   **Timing Attack Protection**: Uses `crypto.timingSafeEqual` for secure ticket validation.
--   **Automatic Threshold Tuning**: (Optional) Includes a genetic algorithm-based optimizer (`startThresholdAutoTuning`) that analyzes real traffic to dynamically adjust suspicion thresholds (`low`, `medium`, `high`), improving bot detection accuracy and reducing false positives over time.
+-   **Automatic Threshold Tuning**: Includes a genetic algorithm-based optimizer (`startThresholdAutoTuning`) that analyzes real traffic to dynamically adjust suspicion thresholds (`low`, `medium`, `high`), improving bot detection accuracy and reducing false positives over time.
 
 ## Installation and Usage
 
@@ -58,13 +52,11 @@ export POW_SECRET="your_secret_key_of_at_least_32_characters"
 
 ### Integration Example
 
-For the `powMiddleware` to work, it needs a configuration defining the weights of suspicion indicators and the challenge trigger thresholds.
+The `powMiddleware` requires a configuration object defining the weights of suspicion indicators and the challenge trigger thresholds.
 
 ```javascript
 import express from 'express';
 import cookieParser from 'cookie-parser';
-// The `configurePow` function is a conceptual example. In the actual implementation,
-// you would pass the configuration to the middleware, for example, via a factory function.
 import { powMiddleware /*, configurePow */ } from './fingerprint.js'; // Adjust the path
 
 const app = express();
@@ -81,27 +73,33 @@ const securityConfig = {
     },
     thresholds: {
         low: 20,    // Score from which a CPU challenge is issued
-        medium: 45, // Score for a Memory challenge
-        high: 75    // Score for a complex challenge (TSP/Captcha)
+        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)
     }
 };
 
-// In a real-world scenario, you would configure the middleware.
-// For example: const configuredPowMiddleware = createPowMiddleware(securityConfig);
+// Create an instance of the middleware with your security configuration.
 const powMiddlewareInstance = powMiddleware(securityConfig);
 
 // Enable trust proxy if your app is behind a reverse proxy (Nginx, etc.)
 // to correctly retrieve the client's IP.
 app.set('trust proxy', 1);
 
-// Apply the protection middleware to all routes or to specific routes.
-// You would use the configured middleware here.
+// Apply the protection middleware to all routes or to specific ones.
 app.use(powMiddlewareInstance);
 
 app.get('/', (req, res) => {
     res.send('Welcome to the protected page!');
 });
 
+// Example of accessing the suspicion score in a subsequent middleware or route.
+// The `fingerprint` object is attached to the request object by the middleware.
+app.use((req, res, next) => {
+    console.log(`Request from ${req.ip} has a suspicion score of: ${req.fingerprint?.score}`);
+    next();
+});
+
 app.listen(3000, () => console.log('Server started on port 3000'));
 ```
 
@@ -111,7 +109,7 @@ In addition to the main middleware, several functions are exported to allow for
 
 ### Main Functions
 
-#### `powMiddleware(req, res, next)`
+#### `powMiddleware(securityConfig)`
 The main Express middleware. It orchestrates identification, suspicion calculation, and challenge issuance. It is the main entry point of the library.
 
 #### `configureStore(store)`
@@ -119,7 +117,7 @@ Allows replacing the in-memory store with an external datastore (like Redis) for
 
 ```javascript
 import { configureStore } from './fingerprint.js';
-import { createRedisStore } from './redis-store.js'; // Assuming you have a redis store implementation
+import { createRedisStore } from './redis-store.js'; // Assuming a redis store implementation exists
 
 const redisStore = createRedisStore(process.env.REDIS_URL);
 configureStore(redisStore);
@@ -154,7 +152,7 @@ app.use(async (req, res, next) => {
 #### `isTicketValid(ip, ticket)`
 Checks the validity of a `pow_clearance` cookie. Returns `true` if the ticket is present, not expired, and correctly signed for the given IP.
 
-#### `FingerprintBuilder` (Class)
+#### `FingerprintBuilder`
 A class for building granular server-side fingerprints.
 
 ```javascript
@@ -166,7 +164,22 @@ const fp = builder.toString(); // "os:hash1|ua:hash2"
 
 #### `getDeviceFingerprint()`
 *Client-side function only.* Generates a detailed browser fingerprint using APIs like Canvas, WebGL, etc.
+This is the primary function for client-side identification.
+
+#### `generateRequestSignature(payload)`
+*Client-side function only.* Creates a signature for an outgoing request. It combines the device fingerprint with a hash of the request's `payload`. This can be used on the server-side to verify that a request comes from a recognized device and that its payload has not been trivially altered.
 
+```javascript
+// On the client
+const signature = generateRequestSignature({ action: 'update', id: 123 });
+// Send signature in headers...
+```
+
+#### `generateClientSideSignature(payload, secret)`
+*Client-side function only.* Generates a secure HMAC-SHA256 signature for a given `payload` using a `secret`.
+**Security Note:** This function is powerful but should be used with caution. The `secret` must be managed securely. It is typically used with a temporary, single-use secret provided by the server for a specific action, rather than a long-lived shared secret embedded in the client-side code.
+
+---
 ## Advanced Features
 
 ### Architecture: `FingerprintEngine`
@@ -219,6 +232,10 @@ const server = http.createServer(async (req, res) => {
     // 2. Process and get a decision
     const decision = await engine.processRequest(requestContext);
 
+    // The decision object now contains the score and the raw suspicion vector.
+    // You can use it for logging or custom logic.
+    console.log(`Request from ${requestContext.clientIp} processed with score: ${decision.score}`);
+
     // 3. Act on the decision
     if (decision.action === 'challenge') {
         res.writeHead(decision.status, { 'Content-Type': 'text/html' });

package/fingerprint.js

@@ -1,6 +1,8 @@
 // C:/Dev/games.primals.net/src/utils/fingerprint.js
 import crypto from "node:crypto";
 import { Optimization } from "./library.js";
+import { cyrb53, FingerprintBuilder } from "./fingerprint.builder.js";
+import { getDeviceHash } from "./fingerprint.server.js";
 
 const POW_SECRET = process.env.POW_SECRET;
 
@@ -9,250 +11,6 @@ if (!POW_SECRET && process.env.NODE_ENV === 'production') {
 } else if (!POW_SECRET) {
   console.warn('Warning: POW_SECRET environment variable not set. Using a default, insecure secret for development.');
 }
-/**
- * cyrb53 hash algorithm (fast with a low collision rate). Exported for reuse.
- */
-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);
-};
-
-/**
- * Class to build a composite fingerprint (Multi-Hash).
- * Output format: "grp1:hash1|grp2:hash2|grp3:hash3"
- */
-export class FingerprintBuilder {
-  constructor() {
-    this.components = new Map();
-  }
-
-  /**
-   * Adds a component to the global hash.
-   * @param {string} group - The group name (e.g., 'hw', 'screen', 'geo')
-   * @param {string|number|boolean} value - The raw value to be hashed
-   */
-  add(group, value) {
-    if (value === undefined || value === null) return this;
-    // Hash the value individually to anonymize it and reduce its size
-    this.components.set(group, cyrb53(String(value)));
-    return this;
-  }
-
-  /**
-   * Generates the final signature string.
-   * Sorts keys to ensure a deterministic order.
-   */
-  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) => {
-      const map = new Map();
-      str.split("|").forEach((part) => {
-        const [k, v] = part.split(":");
-        if (k && v) map.set(k, v);
-      });
-      return map;
-    };
-
-    const map1 = parse(fpString1);
-    const map2 = parse(fpString2);
-
-    // "Veracity" weights (Entropy/Stability)
-    const weights = {
-      cvs: 4.0, // Canvas: Very high entropy (Unique rendering)
-      gpu: 3.0, // GPU: High entropy (Specific hardware)
-      hw: 1.5, // Hardware: Medium entropy
-      scr: 1.0, // Screen: Medium
-      geo: 0.5, // Geo: Low (VPN/Travel)
-      os: 0.5, // OS: Low (Generic)
-      bot: 0.0, // Bot: Informational
-    };
-
-    let weightedMatches = 0;
-    let totalWeight = 0;
-
-    const allKeys = new Set([...map1.keys(), ...map2.keys()]);
-
-    allKeys.forEach((key) => {
-      if (map1.has(key) && map2.has(key)) {
-        const weight = weights[key] || 1.0;
-        totalWeight += weight;
-
-        if (map1.get(key) === map2.get(key)) {
-          weightedMatches += weight;
-        }
-      }
-    });
-
-    return totalWeight === 0 ? 0 : weightedMatches / totalWeight;
-  }
-}
-
-// Cache to avoid recalculating constants (Hardware, etc.)
-let cachedBuilder = null;
-
-/**
- * Generates the fingerprint of the current device.
- */
-export const getDeviceFingerprint = () => {
-  // NOTE: This is client-side code and should be in a separate file.
-  // It will not work in a Node.js environment.
-  // The presence of `window` and `document` confirms this.
-
-  if (typeof window === "undefined") return "server-side";
-
-  if (!cachedBuilder) {
-    const nav = window.navigator;
-    const screen = window.screen;
-
-    cachedBuilder = new FingerprintBuilder();
-
-    // 1. Hardware (Very stable): Cores, RAM, GPU (if available via canvas), Touch
-    cachedBuilder.add(
-      "hw",
-      `${nav.hardwareConcurrency}_${nav.deviceMemory}_${nav.maxTouchPoints}`,
-    );
-
-    // 2. Geo/Locale (Stable except for travel/VPN): Timezone, Language
-    cachedBuilder.add(
-      "geo",
-      `${Intl.DateTimeFormat().resolvedOptions().timeZone}_${nav.language}_${new Date().getTimezoneOffset()}`,
-    );
-
-    // 3. Screen (Stable except for monitor/zoom changes): Dimensions, ColorDepth
-    // Note: We use availWidth/Height which excludes the taskbar, sometimes more unique
-    cachedBuilder.add(
-      "scr",
-      `${screen.width}x${screen.height}_${screen.colorDepth}`,
-    );
-
-    // 4. Platform (Stable): OS, Engine
-    cachedBuilder.add("os", nav.platform);
-
-    // 5. Graphics (WebGL Vendor/Renderer) - Strong hardware invariant
-    try {
-      const canvas = document.createElement("canvas");
-      const gl =
-        canvas.getContext("webgl") || canvas.getContext("experimental-webgl");
-      if (gl) {
-        const debugInfo = gl.getExtension("WEBGL_debug_renderer_info");
-        if (debugInfo) {
-          const vendor = gl.getParameter(debugInfo.UNMASKED_VENDOR_WEBGL);
-          const renderer = gl.getParameter(debugInfo.UNMASKED_RENDERER_WEBGL);
-          cachedBuilder.add("gpu", `${vendor}_${renderer}`);
-        }
-      }
-    } catch (e) {}
-
-    // 6. Canvas Fingerprinting (Rendering quirks) - Adds ~5-10% uniqueness
-    // Exploits micro-differences in anti-aliasing and font rendering
-    try {
-      const canvas = document.createElement("canvas");
-      const ctx = canvas.getContext("2d");
-      if (ctx) {
-        canvas.width = 200;
-        canvas.height = 50;
-        ctx.textBaseline = "alphabetic";
-        ctx.font = "14px 'Arial'";
-        ctx.fillStyle = "#f60";
-        ctx.fillRect(125, 1, 62, 20);
-        ctx.fillStyle = "#069";
-        ctx.fillText("Primals", 2, 15);
-        ctx.fillStyle = "rgba(102, 204, 0, 0.7)";
-        ctx.fillText("Primals", 4, 17);
-        cachedBuilder.add("cvs", canvas.toDataURL());
-      }
-    } catch (e) {}
-
-    // 7. Bot Detection (Hidden indicator)
-    if (nav.webdriver) cachedBuilder.add("bot", "true");
-  }
-
-  // Return a copy to allow adding dynamic fields if needed without polluting the cache
-  return cachedBuilder.toString();
-};
-
-/**
- * Generates a request signature including the context.
- * @param {object} payload
- */
-export const generateRequestSignature = (payload = {}) => {
-  const deviceFp = getDeviceFingerprint();
-
-  // Create a temporary builder that inherits from deviceFp
-  // Note: Here we keep it simple, just concatenating the payload hash
-  const sortedPayload = Object.keys(payload)
-    .sort()
-    .map((k) => `${k}=${payload[k]}`)
-    .join("&");
-  const payloadHash = cyrb53(sortedPayload);
-
-  return `${deviceFp}|req:${payloadHash}`;
-};
-
-/**
- * Generates an HMAC-SHA256 signature for combat data.
- * @param {object} payload - The data to sign (e.g., { opponentId, victory, damageDealt }).
- * @param {string} secret - The shared secret key.
- * @returns {Promise<string>} The hexadecimal signature.
- */
-export const generateCombatSignature = async (payload, secret) => {
-  // NOTE: This is client-side code using the Web Crypto API (`window.crypto`).
-  // It should be moved to a client-side script file.
-
-  // 1. Create a stable string from the payload.
-  const sortedPayload = Object.keys(payload)
-    .sort()
-    .map((k) => `${k}=${payload[k]}`)
-    .join("&");
-
-  // 2. Use the Web Crypto API for HMAC
-  const encoder = new TextEncoder();
-  const key = await window.crypto.subtle.importKey(
-    "raw",
-    encoder.encode(secret),
-    { name: "HMAC", hash: "SHA-256" },
-    false,
-    ["sign"],
-  );
-  const signatureBuffer = await window.crypto.subtle.sign(
-    "HMAC",
-    key,
-    encoder.encode(sortedPayload),
-  );
-
-  // 3. Convert the signature to a hexadecimal string.
-  const hashArray = Array.from(new Uint8Array(signatureBuffer));
-  const hexString = hashArray
-    .map((b) => b.toString(16).padStart(2, "0"))
-    .join("");
-  return hexString;
-};
 
 /**
  * Generates the HTML content for a TSP (Traveling Salesperson Problem) challenge.
@@ -567,53 +325,37 @@ export const isTicketValid = (ip, ticket) => {
     .digest("hex");
 
   // Use timingSafeEqual to prevent timing attacks
-  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expectedSig));
+  try {
+    return crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expectedSig, 'hex'));
+  } catch (e) {
+    // This can happen if the buffers have different lengths, which is a failure case.
+    return false;
+  }
 };
 
-/**
- * Creates a stable hash based on device characteristics, independent of the IP.
- * This is our "level 2 fingerprint".
- * @param {object} req - The Express request object.
- * @returns {string} A hash representing the device.
- */
-function getDeviceHash(req) {
-  const srv = new FingerprintBuilder();
-  srv.add("ua", req.headers["user-agent"]);
-  if (req.headers["sec-ch-ua-platform"])
-    srv.add("os", req.headers["sec-ch-ua-platform"]);
-  if (req.headers["sec-ch-ua"]) srv.add("ch", req.headers["sec-ch-ua"]);
-  return srv.toString(); // Returns the full fingerprint string for detailed comparison.
-}
 
 /**
  * Calculates suspicion indicators related to HTTP header anomalies.
- * @param {object} req - The Express request object.
+ * @param {object} context - The request context.
  * @returns {{headerAnomalyScore: number}}
  */
-function getHeaderAnomalies(req, consistencyScore) {
-  // FIX: consistencyScore est maintenant passé
+function getHeaderAnomalies(context) {
   let anomalyScore = 0;
   // Strong penalty if User-Agent is missing or very short (sign of a simple script)
-  if (!req.headers["user-agent"] || req.headers["user-agent"].length < 10) {
+  if (!context.headers["user-agent"] || context.headers["user-agent"].length < 10) {
     anomalyScore += 60;
   }
   // Penalty if Accept-Language header is missing
-  if (!req.headers["accept-language"]) {
+  if (!context.headers["accept-language"]) {
     anomalyScore += 25;
   }
   // Penalty for HTTP/1.0 requests, often used by old tools or bots
-  if (req.httpVersion === "1.0") {
+  if (context.httpVersion === "1.0") {
     anomalyScore += 15;
   }
 
-  // NEW: Inconsistency score (stolen cookie?)
-  // If the consistency score is low, add a massive penalty.
-  // A score of 0.2 means a huge difference.
-  const inconsistencyScore = Math.max(0, (1 - consistencyScore) * 200);
-
   return {
     headerAnomalyScore: Math.min(100, anomalyScore),
-    inconsistencyScore: Math.min(100, inconsistencyScore),
   };
 }
 
@@ -652,16 +394,16 @@ export const configureStore = (externalStore) => {
 /**
  * Orchestrates request identification using a persistent anchor (cookie)
  * and fingerprint verification.
- * @param {object} req - The Express request object.
- * @param {object} res - The Express response object (to set the cookie).
- * @returns {Promise<{deviceId: string, deviceData: object, consistencyScore: number}>} 
+ * @param {object} context - The request context.
+ * @returns {Promise<{deviceId: string, deviceData: object, consistencyScore: number, newCookie: object|null}>} 
  */
-async function resolveRequestIdentity(req, res) {
-  const existingDeviceId = req.cookies?.device_id;
-  const currentDeviceHash = getDeviceHash(req);
+async function resolveRequestIdentity(context) {
+  const existingDeviceId = context.cookies?.device_id;
+  const currentDeviceHash = getDeviceHash(context);
   let deviceId = existingDeviceId;
   let consistencyScore = 1.0; // 1.0 = perfectly consistent
   let deviceData = null;
+  let newCookie = null;
 
   if (deviceId) {
     deviceData = await store.get(`device:${deviceId}`);
@@ -680,13 +422,14 @@ async function resolveRequestIdentity(req, res) {
     // Case 2: New user or lost/invalid cookie.
     deviceId = crypto.randomUUID(); // Generate a new "passport".
 
-    // Set the cookie securely.
-    res.cookie("device_id", deviceId, {
-      httpOnly: true,
-      secure: process.env.NODE_ENV === "production",
-      sameSite: "strict",
-      maxAge: 31536000000, // 1 year
-    });
+    // Return the intention to set a cookie.
+    newCookie = {
+      name: "device_id",
+      value: deviceId,
+      options: {
+        httpOnly: true, secure: process.env.NODE_ENV === "production", sameSite: "strict", maxAge: 31536000000, // 1 year
+      }
+    };
 
     // Initialize tracking for this new device.
     deviceData = {
@@ -700,24 +443,24 @@ async function resolveRequestIdentity(req, res) {
     // The write will happen in getSuspicionVector after all modifications.
   }
 
-  return { deviceId, deviceData, consistencyScore };
+  return { deviceId, deviceData, consistencyScore, newCookie };
 }
 
 /*
  * Calcule les indicateurs de suspicion liés au comportement de l'appareil (historique, rotation).
- * @param {object} req - The Express request object.
+ * @param {object} context - The request context.
  * @param {object} deviceData - The device's activity data.
  * @returns {Promise<{historyScore: number, rotationScore: number}>}
  */
-async function getBehavioralIndicators(req, deviceData) {
+async function getBehavioralIndicators(context, deviceData) {
   const now = Date.now();
-  const clientIp = req.ip || req.socket?.remoteAddress || "unknown";
+  const clientIp = context.clientIp;
 
   // Get the IP type to modulate the score
   const ipProfile = (await store.get(`ip:${clientIp}`)) || { type: "residential" };
   const isSharedIp = ipProfile.type === "shared";
 
-  const currentFpHash = getDeviceHash(req); // Use the device hash
+  const currentFpHash = getDeviceHash(context); // Use the device hash
 
   // --- Behavior analysis (Change frequency) ---
   if (deviceData.lastFpHash && currentFpHash !== deviceData.lastFpHash) {
@@ -762,13 +505,20 @@ async function getBehavioralIndicators(req, deviceData) {
 
 /**
  * Returns a vector of raw (unweighted) suspicion scores.
- * @param {object} req - The Express request object.
+ * @param {object} context - The request context object.
  * @returns {Promise<{historyScore: number, rotationScore: number, headerAnomalyScore: number, inconsistencyScore: number}>}
  */
-export const getSuspicionVector = async (req, res) => {
-  const { deviceId, deviceData, consistencyScore } = await resolveRequestIdentity(req, res);
+export const getSuspicionVector = async (context) => {
+  const { deviceId, deviceData, consistencyScore, newCookie } = await resolveRequestIdentity(context);
 
-  const clientIp = req.ip || req.socket?.remoteAddress || "unknown";
+  const clientIp = context.clientIp;
+
+  // If a new cookie needs to be set, attach it to the request object
+  // so the middleware can handle it. This is a temporary state holder.
+  if (newCookie) {
+    context._newCookies = context._newCookies || [];
+    context._newCookies.push(newCookie);
+  }
   await store.set(`ip-device:${clientIp}`, deviceId); // Link the IP to the device
 
   // Periodically clean up device data
@@ -778,13 +528,16 @@ export const getSuspicionVector = async (req, res) => {
   }
   deviceData.lastUpdate = Date.now();
 
-  const behavioral = await getBehavioralIndicators(req, deviceData);
-  const anomalies = getHeaderAnomalies(req, consistencyScore);
+  const behavioral = await getBehavioralIndicators(context, deviceData);
+  const { headerAnomalyScore } = getHeaderAnomalies(context);
+  // Calculate the inconsistency score here, separately.
+  const inconsistencyScore = Math.min(100, Math.max(0, (1 - consistencyScore) * 200));
+
 
   // Save the updated device state to the store
   await store.set(`device:${deviceId}`, deviceData);
 
-  return { ...behavioral, ...anomalies };
+  return { ...behavioral, headerAnomalyScore, inconsistencyScore };
 };
 
 // A residential user can change networks (home, 4G, public wifi).
@@ -804,61 +557,29 @@ const MAX_RAPID_CHANGES_PER_DEVICE = 3; // Number of rapid fingerprint changes a
  * and IP, making spoofing more complex (requires changing the entire stack).
  */
 export const identifyRequest = async (req, res) => {
-  const clientIp = req.ip || req.socket?.remoteAddress || "unknown";
-  const deviceId = req.cookies?.device_id;
-
-  // --- Update IP reputation ---
-  const ipProfile = (await store.get(`ip:${clientIp}`)) || {
-    type: "residential",
-    deviceIds: new Set(),
-    statelessCount: 0,
-    lastSeen: 0,
+  // This function now acts as a lightweight wrapper around the engine's identifyRequest method.
+  // It requires a default configuration to work.
+  const defaultConfig = {
+    weights: { historyScore: 0.3, rotationScore: 0.5, headerAnomalyScore: 0.1, inconsistencyScore: 0.8 },
+    thresholds: { low: 20, medium: 40, high: 75 }
   };
-  ipProfile.lastSeen = Date.now();
-  if (deviceId) {
-    ipProfile.deviceIds.add(deviceId);
-  } else {
-    // Improved anti-"Amnesiac Bot" logic
-    ipProfile.statelessCount++;
-  }
+  const engine = new FingerprintEngine(defaultConfig);
 
-  // If an IP sees too many different devices, classify it as "shared".
-  if (ipProfile.deviceIds.size > SHARED_IP_DEVICE_THRESHOLD) {
-    ipProfile.type = "shared";
-  }
+  const requestContext = {
+      clientIp: req.ip || req.socket?.remoteAddress || "unknown",
+      cookies: req.cookies,
+      headers: req.headers,
+      rawHeaders: req.rawHeaders,
+      httpVersion: req.httpVersion,
+  };
 
-  // If a residential IP makes too many requests without a cookie, it's a bot.
-  // For a shared IP, we are more tolerant because new users are constantly arriving.
-  const statelessLimit = ipProfile.type === "shared" ? 50 : 10;
-  if (ipProfile.statelessCount > statelessLimit) {
-    return `suspicious_high:${clientIp}`;
-  }
-  await store.set(`ip:${clientIp}`, ipProfile);
-
-  // For compatibility with the rate-limiter, calculate a simple score.
-  // The PoW will use the more complex weighted system.
-  const vector = await getSuspicionVector(req, res);
-  const score =
-    vector.historyScore * 0.3 +
-    vector.rotationScore * 0.5 +
-    vector.headerAnomalyScore * 0.1 +
-    vector.inconsistencyScore * 0.8; // Inconsistency is a very strong signal
-
-  // Return a string for compatibility with rate limiters,
-  // but based on suspicion thresholds.
-  // NOTE: These thresholds are fixed here, but the PoW will use dynamic thresholds.
-  if (score >= 75) {
-    return `suspicious_high:${clientIp}`;
-  }
-  if (score >= 40) {
-    return `suspicious_medium:${clientIp}`;
+  const key = await engine.identifyRequest(requestContext);
+
+  if (requestContext._newCookies && res) {
+    requestContext._newCookies.forEach(c => res.cookie(c.name, c.value, c.options));
   }
 
-  // For normal requests, return a hash of the fingerprint for rate limiting.
-  // Use the device hash so the rate-limit follows the device, not the IP.
-  const deviceIdForIp = await store.get(`ip-device:${clientIp}`);
-  const finalDeviceId = deviceId || deviceIdForIp || clientIp;
-  return `device:${finalDeviceId}`;
+  return key;
 };
 // --- NOUVEAU CHALLENGE CPU "ANALOGIQUE" ---
 
@@ -1052,12 +773,11 @@ class FingerprintEngine {
     const { weights, thresholds, logger } = this.securityConfig;
 
     if (isStatic) {
-      return { action: 'next' };
+      return { action: 'next', score: 0, vector: {} };
     }
 
-    // We need to pass `req` and `res` to getSuspicionVector for cookie handling.
-    // This is a remaining coupling point that could be refactored further.
-    const suspicionVector = await __internal.getSuspicionVector(requestContext.rawReq, requestContext.rawRes);
+    // The engine now works with the context directly, no more rawReq dependency here.
+    const suspicionVector = await __internal.getSuspicionVector(requestContext);
 
     const finalScore =
       suspicionVector.historyScore * (weights.historyScore || 0) +
@@ -1079,11 +799,6 @@ class FingerprintEngine {
     const powCookie = cookies?.pow_clearance;    
     const { pow_type, pow_nonce, pow_solution, pow_solution_cpu, pow_solution_mem } = query;
 
-    // Basic log for each non-static request
-    if (logger && !isSuspicious) {
-        logger({ type: 'request_passed', deviceId: cookies?.device_id, score: finalScore, timestamp: Date.now() });
-    }
-
     if (isSuspicious && !isTicketValid(clientIp, powCookie)) {
         // --- CHALLENGE SOLUTION HANDLING ---
         if (pow_nonce && (pow_solution || (pow_solution_cpu && pow_solution_mem))) {
@@ -1140,6 +855,8 @@ class FingerprintEngine {
                 return {
                   action: 'redirect',
                   path: path,
+                  score: finalScore,
+                  vector: suspicionVector,
                   cookie: {
                     name: 'pow_clearance',
                     value: ticket,
@@ -1176,7 +893,7 @@ class FingerprintEngine {
 
             const page = generateCombinedPoWChallengePage(cpuChallengeDetails, memDifficulty, clientIp);
             return {
-                action: 'challenge',
+                action: 'challenge', score: finalScore, vector: suspicionVector,
                 status: 429, body: page
             };
         }
@@ -1195,11 +912,66 @@ class FingerprintEngine {
 
             // On utilise toujours la page combinée, même si la difficulté mémoire est 0 (le calcul sera quasi instantané).
             const page = generateCombinedPoWChallengePage(cpuChallengeDetails, memDifficulty, clientIp);
-            return { action: 'challenge', status: 429, body: page };
+            return { action: 'challenge', score: finalScore, vector: suspicionVector, status: 429, body: page };
         }
     }
 
-    return { action: 'next' };
+    // Basic log for each non-static request that passed without a challenge
+    if (logger) {
+        logger({ type: 'request_passed', deviceId: cookies?.device_id, score: finalScore, timestamp: Date.now() });
+    }
+
+    return { action: 'next', score: finalScore, vector: suspicionVector };
+  }
+
+  /**
+   * Identifies a request in a granular way for non-Express environments.
+   * @param {object} requestContext - The request context object.
+   * @returns {Promise<string>} An identification string (e.g., "device:<id>", "suspicious_high:<ip>").
+   */
+  async identifyRequest(requestContext) {
+    const { clientIp, cookies, rawReq, rawRes } = requestContext;
+
+    // --- Update IP reputation ---
+    const ipProfile = (await store.get(`ip:${clientIp}`)) || {
+      type: "residential",
+      deviceIds: new Set(),
+      statelessCount: 0,
+      lastSeen: 0,
+    };
+    ipProfile.lastSeen = Date.now();
+    if (cookies?.device_id) {
+      ipProfile.deviceIds.add(cookies.device_id);
+    } else {
+      ipProfile.statelessCount++;
+    }
+
+    if (ipProfile.deviceIds.size > SHARED_IP_DEVICE_THRESHOLD) {
+      ipProfile.type = "shared";
+    }
+
+    const statelessLimit = ipProfile.type === "shared" ? 50 : 10;
+    if (ipProfile.statelessCount > statelessLimit) {
+      return `suspicious_high:${clientIp}`;
+    }
+    await store.set(`ip:${clientIp}`, ipProfile);
+
+    const vector = await __internal.getSuspicionVector(requestContext);
+    const score =
+      vector.historyScore * (this.securityConfig.weights.historyScore || 0.3) +
+      vector.rotationScore * (this.securityConfig.weights.rotationScore || 0.5) +
+      vector.headerAnomalyScore * (this.securityConfig.weights.headerAnomalyScore || 0.1) +
+      vector.inconsistencyScore * (this.securityConfig.weights.inconsistencyScore || 0.8);
+
+    if (score >= this.securityConfig.thresholds.high) return `suspicious_high:${clientIp}`;
+    if (score >= this.securityConfig.thresholds.low) return `suspicious_medium:${clientIp}`; // Use medium for any suspicion
+    if (score >= this.securityConfig.thresholds.medium) return `suspicious_medium:${clientIp}`;
+
+    // If a new device_id was created, it's in the context.
+    const newDeviceId = requestContext._newCookies?.find(c => c.name === 'device_id')?.value;
+    const finalDeviceId = cookies?.device_id || newDeviceId || clientIp;
+
+    return `device:${finalDeviceId}`;
   }
 }
 
@@ -1215,14 +987,28 @@ export const powMiddleware = (securityConfig) => {
       query: req.query,
       headers: req.headers,
       isStatic: isStaticResource(req),
-      // Pass raw req/res for now to handle cookie setting in resolveRequestIdentity
-      rawReq: req,
-      rawRes: res,
+      // Add the newly required properties for full decoupling
+      rawHeaders: req.rawHeaders,
+      httpVersion: req.httpVersion,
     };
 
     const decision = await engine.processRequest(requestContext);
 
+    // Attach the fingerprinting result to the request object for downstream middlewares.
+    req.fingerprint = {
+      score: decision.score,
+      vector: decision.vector,
+    };
+
+    // After getSuspicionVector runs, it might have attached cookies to be set.
+    if (requestContext._newCookies) {
+      requestContext._newCookies.forEach(c => res.cookie(c.name, c.value, c.options));
+    }
+
     switch (decision.action) {
+      case 'block':
+        return res.status(decision.status).send(decision.body);
+
       case 'challenge':
         return res.status(decision.status).send(decision.body);
 
@@ -1245,7 +1031,10 @@ export const powMiddleware = (securityConfig) => {
  * This is a common pattern to allow mocking of ES module functions.
  */
 export const __internal = {
+    getDeviceHash,
     getSuspicionVector,
+    cyrb53, // Export for testing
+    FingerprintBuilder, // Export for testing
     calculateTarget,
     FingerprintEngine, // Expose for advanced testing
 };
@@ -1284,7 +1073,7 @@ function runThresholdOptimization(securityConfig, trafficData, minDataPoints) {
     const fitnessFunction = (solution) => {
         const [low, medium, high] = solution;
         // Constraints: thresholds must be ordered and within a reasonable range.
-        if (low >= medium || medium >= high || low < 10 || high > 90) return Infinity;
+        if (low >= medium || medium >= high || low <= 10 || high >= 90) return Infinity;
 
         let falsePositives = 0; // Humans challenged unnecessarily.
         let falseNegatives = 0; // Undetected bots.

package/library.js

@@ -1443,4 +1443,4 @@ Optimization.Operators.solveFraudDetection = (context, options = {}) => {
   );
 };
 
-export { Dichotomy, Optimization };
+export { Optimization };

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@anonympins/fingerprint",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "An HTTP(S) client mitigation and anti-bot protection library for Node.js/Express, based on digital fingerprinting and dynamic Proof-of-Work (PoW) challenges.",
   "main": "fingerprint.js",
   "type": "module",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "scripts": {
     "test": "vitest run"
@@ -42,9 +42,6 @@
   "devDependencies": {
     "cookie-parser": "^1.4.6",
     "express": "^4.18.2",
-    "vitest": "^1.4.0"
-  },
-  "dependencies": {
-
+    "vitest": "^4.1.11"
   }
 }