@anonympins/fingerprint 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## Version 0.4.3
+
+### 🔒 Rotation Score Hardening (Anti-Spoofing & No-JS Parity)
+- **Server-Only Rotation Analysis**: Completely removed all client-side telemetry (`X-Device-Fingerprint`, canvas, gpu, hardware concurrency) from the `rotationScore` computation across all engines (Node.js, PHP, Python).
+- **Zero-Trust Client Inputs**: Fixed a vulnerability where client-side fingerprint spoofing or the absence of JS headers on static/API requests could trick the engines into triggering false-positive rotation alerts. The stable part analysis now relies exclusively on server-side signatures (`ua`, `ja3`, `ja4`, `h2`, `tcp`).
+
+### 🐍 Python Engine Parity & uPoW
+- **Useful Proof-of-Work (uPoW) in Python**: Fully implemented uPoW support in Python, bringing complete parity to task dispatching and solution integration with the Node.js and PHP versions.
+- **Dry Run & Score Matching**: Added robust Dry Run mode and suspicion score calculations in the Python engine, allowing passive security evaluation without request interruption.
+
+### 🐘 PHP Engine Enhancements
+- **PHP uPoW Coverage**: Greatly expanded test coverage for the PHP `ProblemManager` and useful work integrations, ensuring reliability under heavy workloads.
+
+### 🛡️ Challenge Routing & Better Re-challenge
+- **Refined Challenge Router**: Restructured challenge routing and solution validation pipelines for direct, consistent handling of cryptographic results.
+- **Smarter Re-challenging**: Improved re-challenge behavior across all engines. If an already cleared device's score spikes above the high threshold again, the existing clearance ticket is bypassed, instantly prompting a fresh security challenge.
+
 ## Version 0.4.2 (Hotfix)
 
 ### 🧬 Auto-Tuner Rework & Sanity Guardrails

package/README.md

@@ -1,61 +1,67 @@
-# Fingerprint anti-bot protection
-
-NodeJS tests : [![Test NodeJS](https://img.shields.io/github/actions/workflow/status/anonympins/fingerprint/ci-nodejs.yml)](https://github.com/anonympins/fingerprint/actions/workflows/ci.yml) / PHP tests : [![PHP](https://img.shields.io/github/actions/workflow/status/anonympins/fingerprint/ci-php.yml)](https://github.com/anonympins/fingerprint/actions/workflows/ci-php.yml) / Python tests : [![PHP](https://img.shields.io/github/actions/workflow/status/anonympins/fingerprint/ci-php.yml)](https://github.com/anonympins/fingerprint/actions/workflows/ci-python.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)
-![GitHub commit activity](https://img.shields.io/github/commit-activity/w/anonympins/fingerprint)
-
-A multi-layered behavioral, cryptographic, and network analysis engine designed to identify and mitigate malicious requests (bots, scrapers, session hijacking) in real-time. Supports both **Node.js** and **PHP** environments.
-
-![illustration](https://i.ibb.co/fV1QT6Mf/image-c6e10859baae53bb595112ec08fc9e27.png)
-
-## Key Features
-
-- **Multi-Layered Detection**: Combines TLS/JA3/JA4 analysis, HTTP header consistency checks, IP reputation, and behavioral tracking (mouse movements, keystrokes).
-- **Adaptive Mitigation**: Imposes progressive cryptographic Proof-of-Work (PoW) challenges to block automated clients without impacting legitimate human users.
-- **Predefined Profiles**: Ready-to-use security profiles (`balanced`, `strict`, `api`, `blog`, `ecommerce`) tailored to your specific use case.
-
-## Quick Start
-
-### Node.js
-
-```bash
-npm install @anonympins/fingerprint
-```
-
-### PHP
-
-```bash
-composer require anonympins/fingerprint
-```
-
-## Documentation
-
-To prevent documentation drift, all detailed guides and reference materials are maintained in the `doc/` directory. Please refer to [these resources](https://github.com/anonympins/fingerprint/wiki/home) to configure and integrate the engine:
-
-1. **[Key Concepts & Suspicion Vectors](https://github.com/anonympins/fingerprint/wiki/concepts)**: Learn how the engine calculates suspicion scores across the 15 distinct vectors and manages the Proof-of-Work mitigation layers.
-2. **[Node.js Integration Guide](https://github.com/anonympins/fingerprint/wiki/nodejs_integration)**: Step-by-step instructions for Express.js middleware and raw HTTP server integrations.
-3. **[PHP Integration Guide](https://github.com/anonympins/fingerprint/wiki/php_integration)**: Configuration details for direct PHP integration, TLS fingerprinting forwarding via Nginx/Apache, and securing Prometheus metrics.
-4. **[Full Configuration Options](https://github.com/anonympins/fingerprint/wiki/full_options)**: Complete parameter list for fine-tuning weights, custom honeypots, and security profile overrides.
-5. **[API Reference](https://github.com/anonympins/fingerprint/wiki/api_reference)**: Public API signatures and guides on substituting the in-memory datastore with Redis or MongoDB.
-
-Start with the **[Documentation Portal](https://github.com/anonympins/fingerprint/wiki/home)** for a complete index.
-
-## Contributing
-
-We welcome community contributions! Please read our **[Contributing Guidelines](https://github.com/anonympins/fingerprint/blob/main/CONTRIBUTING.md)** for information on:
-- Setting up your local environment (Node.js and PHP).
-- Running the test suites (`Vitest` and `PHPUnit`).
-- Coding and pull request standards.
-
-Thanks to our contributors : 
-- [anonympins](https://github.com/anonympins)
-
-## Used actively on
-
-- https://primals.net and sub-sites
-
-## License
-
+# Fingerprint anti-bot protection
+
+NodeJS tests : [![Test NodeJS](https://img.shields.io/github/actions/workflow/status/anonympins/fingerprint/ci-nodejs.yml)](https://github.com/anonympins/fingerprint/actions/workflows/ci.yml) / PHP tests : [![PHP](https://img.shields.io/github/actions/workflow/status/anonympins/fingerprint/ci-php.yml)](https://github.com/anonympins/fingerprint/actions/workflows/ci-php.yml) / Python tests : [![PHP](https://img.shields.io/github/actions/workflow/status/anonympins/fingerprint/ci-php.yml)](https://github.com/anonympins/fingerprint/actions/workflows/ci-python.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)
+![GitHub commit activity](https://img.shields.io/github/commit-activity/w/anonympins/fingerprint)
+
+A multi-layered behavioral, cryptographic, and network analysis engine designed to identify and mitigate malicious requests (bots, scrapers, session hijacking) in real-time. Supports both **Node.js** and **PHP** environments.
+
+![illustration](https://i.ibb.co/fV1QT6Mf/image-c6e10859baae53bb595112ec08fc9e27.png)
+
+## Key Features
+
+- **Multi-Layered Detection**: Combines TLS/JA3/JA4 analysis, HTTP header consistency checks, IP reputation, and behavioral tracking (mouse movements, keystrokes).
+- **Adaptive Mitigation**: Imposes progressive cryptographic Proof-of-Work (PoW) challenges to block automated clients without impacting legitimate human users.
+- **Predefined Profiles**: Ready-to-use security profiles (`balanced`, `strict`, `api`, `blog`, `ecommerce`) tailored to your specific use case.
+
+## Quick Start
+
+### Node.js
+
+```bash
+npm install @anonympins/fingerprint
+```
+
+### PHP
+
+```bash
+composer require anonympins/fingerprint
+```
+
+### Python
+```bash
+pip install fingerprint-engine
+```
+
+## Documentation
+
+To prevent documentation drift, all detailed guides and reference materials are maintained in the `doc/` directory. Please refer to [these resources](https://github.com/anonympins/fingerprint/wiki/home) to configure and integrate the engine:
+
+1. **[Key Concepts & Suspicion Vectors](https://github.com/anonympins/fingerprint/wiki/concepts)**: Learn how the engine calculates suspicion scores across the 15 distinct vectors and manages the Proof-of-Work mitigation layers.
+2. **[Node.js Integration Guide](https://github.com/anonympins/fingerprint/wiki/nodejs_integration)**: Step-by-step instructions for Express.js middleware and raw HTTP server integrations.
+3. **[PHP Integration Guide](https://github.com/anonympins/fingerprint/wiki/php_integration)**: Configuration details for direct PHP integration, TLS fingerprinting forwarding via Nginx/Apache, and securing Prometheus metrics.
+3. **[Python Integration Guide](https://github.com/anonympins/fingerprint/wiki/python_integration)**: Python middleware for ASGI and WSGI integration.
+4. **[Full Configuration Options](https://github.com/anonympins/fingerprint/wiki/full_options)**: Complete parameter list for fine-tuning weights, custom honeypots, and security profile overrides.
+5. **[API Reference](https://github.com/anonympins/fingerprint/wiki/api_reference)**: Public API signatures and guides on substituting the in-memory datastore with Redis or MongoDB.
+
+Start with the **[Documentation Portal](https://github.com/anonympins/fingerprint/wiki/home)** for a complete index.
+
+## Contributing
+
+We welcome community contributions! Please read our **[Contributing Guidelines](https://github.com/anonympins/fingerprint/blob/main/CONTRIBUTING.md)** for information on:
+- Setting up your local environment (Node.js and PHP).
+- Running the test suites (`Vitest` and `PHPUnit`).
+- Coding and pull request standards.
+
+Thanks to our contributors : 
+- [anonympins](https://github.com/anonympins)
+
+## Used actively on
+
+- https://primals.net and sub-sites
+
+## License
+
 This project is licensed under the MIT License.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anonympins/fingerprint",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Advanced anti-bot library for Node.js using multi-layer fingerprinting (JA3, client-side, headers), behavioral analysis, and adaptive Proof-of-Work (PoW) challenges to mitigate scraping, scalping, and automated threats.",
   "main": "index.js",
   "type": "module",

package/src/js/fingerprint.js

@@ -263,7 +263,7 @@ function extractStablePart(fpString) {
     if (!fpString) {
         return '';
     }
-    const stableKeys = ['cvs', 'gpu', 'hw', 'client_fp_hash', 'os', 'scr'];
+    const stableKeys = ['ua', 'ja3', 'ja4', 'h2', 'tcp'];
     const parts = fpString.split('|');
     const stableParts = [];
     for (const part of parts) {
@@ -3421,7 +3421,15 @@ export class FingerprintEngine {
         }
 
         if (isSuspicious && usefulWorkDispatched) {
-            return { action: 'challenge', score: finalScore, vector: suspicionVector, status: 404, body: challengePayload };
+            const isApi = requestContext.rawReq && this.securityConfig?.isApiRequest?.(requestContext.rawReq);
+            if (isApi) {
+                return { action: 'challenge', score: finalScore, vector: suspicionVector, status: 404, body: challengePayload };
+            } else {
+                const html = `<html><body><script>
+                    window.location.href = "${path}?pow_type=useful_work_task&pow_nonce=${nonce}&pow_problem_id=${challengePayload.challenge.usefulWorkTask.problemId}&pow_solution_work_result=" + encodeURIComponent(JSON.stringify({ solution: [], energy: 0 }));
+                </script></body></html>`;
+                return { action: 'challenge', score: finalScore, vector: suspicionVector, status: 404, body: html };
+            }
         } else if (isSuspicious) { // Pour les scores bas/moyens ou si le travail utile n'est pas choisi / a échoué                
             const decision = { action: 'challenge', score: finalScore, vector: suspicionVector, status: 404 };
                 if (this.dryRun) {