@anonympins/fingerprint 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -0,0 +1,172 @@
+## Version 0.3.3
+
+This release introduces significant enhancements to client-side behavioral analysis, adds a crucial "dry run" mode for safe production testing, and improves the overall developer experience with an event-driven client library and better packaging.
+
+### ✨ New Features
+
+*   **Advanced Behavioral Analysis: Click Variance**:
+    *   The client-side library now tracks the exact coordinates of user clicks on interactive elements.
+    *   A new `clickVarianceScore` is calculated on the server-side (for both PHP and Node.js) to penalize unnaturally precise, bot-like clicking patterns (e.g., always hitting the exact same pixel). This adds a powerful new dimension to detecting sophisticated automation.
+
+*   **"Dry Run" Mode**:
+    *   A `dryRun: true` option can now be added to the security configuration. When enabled, the engine performs all calculations and logs the action it *would* have taken (`block`, `challenge`) but never actually interrupts the request.
+    *   This is invaluable for safely testing new or stricter configurations in a live production environment without affecting real users.
+
+*   **Client-Side Event Emitter**:
+    *   The client library now emits events for key actions (e.g., `challenge_issued`, `challenge_solved`, `honeypot_triggered`). This allows developers to easily hook into the library's lifecycle to trigger custom UI changes, analytics, or logging.
+
+### 🚀 Improvements
+
+*   **Enhanced Mouse Tracking Analysis**: The server-side analysis of mouse movement data has been refined to better distinguish between natural, human-like cursor paths and the linear or predictable movements typical of bots.
+*   **PHP Code Quality**: The entire PHP codebase has undergone a syntax normalization pass, improving consistency and long-term maintainability.
+*   **Test Suite Reliability**:
+    *   Unit tests for the client-side `initializeClient` function have been added and improved.
+    *   New unit tests cover the "Dry Run" mode functionality.
+    *   Fixed existing unit tests for the `ProblemManager` to ensure the stability of the Useful-Proof-of-Work system.
+
+### 📦 Build & Internals
+
+*   **Corrected NPM Package Files**: The `files` array in `package.json` has been updated to ensure all necessary JavaScript source files (`library.js`, `fingerprint.builder.js`, etc.) are correctly included in the published package, fixing potential `import` issues for users.
+*   **Project Structure**: The JavaScript source files have been consolidated into the `src/js` directory for a cleaner and more organized project structure.
+
+## Version 0.3.2
+
+This release brings major new capabilities to both the Node.js and PHP versions of the library. Key highlights include the full implementation of the "Useful Proof-of-Work" (uPoW) system in PHP, client-side acceleration via WebAssembly (WASM), direct JA3 fingerprinting in Node.js, and significant reliability improvements to the auto-tuner.
+
+### ✨ New Features
+
+*   **Useful Proof-of-Work (uPoW) in PHP**: The PHP version now has full feature parity with Node.js for uPoW.
+    *   The `ProblemManager` is now fully implemented in PHP, allowing it to load, manage, and dispatch complex optimization problems (e.g., TSP, Portfolio Allocation) to suspicious clients.
+    *   Client solutions are integrated back into the system, enabling distributed, collaborative problem-solving.
+
+*   **WASM-Accelerated Client**: The client-side library can now be accelerated with a WebAssembly module for high-performance hashing.
+    *   The build process (`build-client.js`) now includes a step to compile the C++ hashing utility into a WASM module.
+    *   The client library (`fingerprint.client.js`) can dynamically load the WASM module if available, falling back gracefully to the pure JavaScript implementation. This makes client-side fingerprinting faster and harder to tamper with.
+
+*   **Direct JA3 Fingerprinting in Node.js**: The Node.js engine can now calculate the JA3 fingerprint directly from the raw TLS `clientHello` object. This is a major enhancement, as it removes the hard dependency on a reverse proxy (like Nginx or Cloudflare) to provide the JA3 hash, making the library more versatile and easier to deploy in various environments.
+
+*   **Auto-Tuner Solution API**: A new `getBestTuningSolution()` function has been added to the Node.js version. This allows developers to programmatically retrieve and inspect the optimal configuration (`weights`, `thresholds`, `patterns`) found by the auto-tuner, which is useful for auditing and "FinOps".
+
+### 🚀 Improvements
+
+*   **Probationary Tickets in PHP**: The PHP engine now supports issuing short-lived "probationary" tickets for moderately suspicious users who solve a challenge. This forces a quicker re-evaluation, increasing security for borderline cases.
+*   **Auto-Tuner Reliability**: The auto-tuning mechanism has been made more robust, with fixes to default score calculations to improve its initial learning phase and overall stability.
+*   **PHP 64-Bit Compatibility**: The PHP implementation of the `cyrb53` hashing algorithm and other arithmetic operations has been improved using the `gmp` extension to ensure correct and consistent results on 64-bit systems, matching the JavaScript output.
+*   **Expanded PHP Test Coverage**: The PHPUnit test suite has been significantly expanded to cover the new `ProblemManager`, uPoW logic, and other core engine features, increasing overall reliability.
+
+## Version 0.3.1
+
+This release marks a major expansion of the library, introducing a full-featured PHP version that mirrors the capabilities of the Node.js module. It also adds GraphQL operation whitelisting and an obfuscated client build for enhanced security.
+
+### ✨ New Features
+
+*   **Full PHP Support**: The library is now available for PHP 7.4+ with a feature set equivalent to the Node.js version.
+    *   **Direct Integration**: A `DirectFingerprint` class allows for easy integration into any PHP application, including legacy codebases, by interacting directly with PHP's superglobals.
+    *   **PSR-15 Middleware**: A `FingerprintMiddleware` is provided for modern, framework-agnostic integration with applications that follow PSR-7, PSR-15, and PSR-17 standards (e.g., Slim, Laminas).
+    *   **Pluggable Datastores**: The PHP version supports the same pluggable store architecture, allowing state to be persisted in Redis, databases, or other external systems.
+    *   **Security Profiles**: The same pre-configured security profiles (`balanced`, `strict`, `api`, etc.) are available in PHP via `SecurityProfiles::createSecurityProfile()`.
+    *   **Client-Side Helper**: A `FingerprintClient` class is included to simplify the injection of the client-side JavaScript library and honeypot fields into PHP-rendered HTML pages.
+
+*   **GraphQL Whitelisting**: You can now whitelist specific GraphQL operations to bypass security checks. This is ideal for allowing public queries (like `GetPublicPosts`) while protecting sensitive mutations. This is supported in both Node.js and PHP.
+    *   Example rule: `{ type: 'graphql_operation_allowlist', entries: ['query:GetPublicPosts', 'mutation:*'] }`
+
+### 🚀 Improvements
+
+*   **Obfuscated Client Script**: The build process now generates an obfuscated version of the client-side JavaScript library (`fingerprint.client.obfuscated.js`). This makes it significantly more difficult for attackers to reverse-engineer the client-side fingerprinting and behavioral analysis logic.
+*   **Expanded PHP Test Coverage**: The new PHP module includes a comprehensive suite of PHPUnit tests, ensuring the reliability and correctness of the `FingerprintEngine`, challenge verification, and scoring logic.
+*   **Unified Documentation**: The `README.md` has been updated with dedicated sections and quick-start guides for both Node.js and the new PHP integrations, providing clear instructions for both platforms.
+
+### 📦 Build & Internals
+
+*   The project structure now includes a `src/php` directory containing the full PHP library implementation.
+*   A `phpunit.xml` configuration has been added to manage the PHP test suite.
+
+## Version 0.3.0 
+
+This is a major release focused on security hardening, distributed system capabilities, and overall robustness. It introduces advanced TLS spoofing detection, protection against various resource exhaustion and data poisoning attacks, and makes the "Useful Proof-of-Work" system truly scalable.
+
+### 🔒 Security Enhancements
+
+*   **Advanced TLS Spoofing Detection**: The engine now performs a much deeper analysis to detect when a client is faking its identity. It cross-references the TLS JA3 fingerprint against an internal database of known browser and library signatures. A request with a `User-Agent` for Chrome but a JA3 fingerprint for a Python `requests` library will now be heavily penalized.
+*   **uPoW Resource Drain Protection**: Implemented a hard cap on the difficulty of "Useful Proof-of-Work" (uPoW) tasks. This prevents a malicious client from being assigned a computationally impossible task that could drain server resources during verification.
+*   **Memory PoW DoS Protection**: A hard cap has been added to the memory allocation size for the memory-based PoW challenge, preventing a malicious client from forcing the server to allocate excessive amounts of memory.
+*   **Auto-Tuner Data Poisoning Protection**: The auto-tuner is now more robust against data poisoning attacks. It better distinguishes between legitimate traffic patterns and malicious attempts to skew its learning process, ensuring the optimized parameters remain effective.
+*   **Invalid Nonce Protection**: The challenge-response mechanism is now hardened. Any attempt to submit a solution for an invalid or expired nonce is immediately flagged as a high-risk honeypot interaction, resulting in a block or a maximum-difficulty challenge.
+*   **Cryptographically Secure Randomness**: The internal library now uses `crypto.randomBytes` instead of `Math.random` for all security-sensitive operations, ensuring higher quality randomness for tasks like genetic algorithm mutations and selection.
+
+### ✨ New Features
+
+*   **Distributed uPoW State**: The state of "Useful Proof-of-Work" problems (e.g., the best solution found for a TSP problem) is now persisted through the configured datastore (e.g., Redis, MongoDB). This allows a cluster of server instances to collaborate on solving the same complex problems, making the system truly distributed and more powerful.
+
+### 🚀 Improvements
+
+*   **Smarter Fingerprint Comparison**: The `FingerprintBuilder.compare()` method is now more precise. It applies a penalty for unknown or missing keys in a fingerprint, making it better at detecting subtle differences between a legitimate user and an attacker attempting to mimic a fingerprint.
+*   **Configuration Validation**: The engine now checks for unknown keys in the `securityConfig` object upon initialization and will log a warning. This helps developers quickly identify typos or misconfigurations.
+*   **Asynchronous Problem Loading**: The `problems.config.json` file is now read asynchronously and debounced at startup, improving application start time and preventing race conditions.
+*   **Optional Peer Dependencies**: The `package.json` has been updated to mark datastore drivers (`ioredis`, `mongodb`, `knex`, `sqlite3`) as optional `peerDependencies`. This provides a cleaner installation for users who do not need a specific external store.
+
+## Version 0.2.3
+
+This release introduces major improvements in ease of use and flexibility. It adds pre-configured security profiles for rapid setup, more granular whitelisting controls, and expands the "Useful Proof-of-Work" system with a new range of complex optimization problems.
+
+### ✨ New Features
+
+*   **Security Profiles & Quick Init**:
+    *   To simplify setup, you can now use the `createSecurityProfile()` helper to load pre-configured profiles tailored for common use cases: `balanced` (default), `strict`, `api`, `blog`, and `ecommerce`.
+    *   These profiles provide a solid starting point and can be easily customized with your own overrides.
+
+*   **Advanced Whitelisting Controls**:
+    *   **`path_allowlist`**: A new whitelisting rule to bypass checks for specific URL paths. It's perfect for public API endpoints, webhooks, or static content that doesn't require protection. Supports wildcards (e.g., `/api/public/*`).
+    *   **`host_path_allowlist`**: Provides even more granular control by whitelisting a path only when it's on a specific host. This is ideal for multi-tenant applications or for securing an API on one domain but not another (e.g., `api.example.com/v1/webhooks/*`).
+
+*   **Expanded Useful Proof-of-Work (uPoW) Problems**:
+    *   The `ProblemManager` is now more powerful, with support for a wider range of real-world optimization tasks that can be offloaded to suspicious clients.
+    *   The `problems.config.json` has been updated with new examples, including:
+        *   **Fraud Detection Tuning**: Finding optimal thresholds for fraud detection systems.
+        *   **Facility Location**: Solving complex logistical placement problems.
+        *   **Security Auto-Tuning**: Using client CPU to dynamically optimize the library's own security parameters.
+        *   **CPC Optimization**: Finding optimal Cost-Per-Click values in a simulated ad-tech environment.
+    *   The `FunctionRegistry` in `problem-manager.js` has been updated to support these new problem types.
+
+### 🚀 Improvements
+
+*   **Documentation**: The `README.md` has been updated to reflect the new security profiles and whitelisting options, with clear examples for each.
+
+
+## Version 0.2.2 
+
+This version marks a significant evolution from simple Proof-of-Work (PoW) to "Useful Proof-of-Work" (uPoW). Instead of solving arbitrary computational puzzles, clients now contribute to solving complex optimization problems, making the work done to verify a client's legitimacy valuable.
+
+### ✨ New Features
+
+*   **Useful Proof-of-Work (uPoW) System**:
+    *   Introduced the `ProblemManager` to oversee long-running optimization problems (e.g., Traveling Salesperson Problem, Portfolio Optimization).
+    *   Clients' PoW challenges now consist of running optimization algorithms (like Simulated Annealing or Genetic Algorithms) for a specific number of iterations/generations.
+    *   Solutions submitted by clients are integrated back into the system, continuously improving the best-known solution for each problem over time.
+
+*   **Dynamic Problem Configuration**:
+    *   The `problems.config.json` file now supports dynamic data generation. You can specify functions like `generate:randomPoints` or `generate:randomAssets` to create new problem instances on startup without manual data entry.
+
+*   **Best Solution API**:
+    *   A new method, `fingerprint.getBestSolutions(problemId?)`, has been added. This allows you to retrieve the best solution found so far for a specific problem or for all active problems. This makes the results of the uPoW system accessible and useful.
+
+*   **Re-challenge for High-Suspicion Clients**:
+    *   Clients with a very high `suspicionFactor` are now automatically issued a second challenge upon successful completion of the first. This significantly increases the cost of verification for highly suspicious actors without affecting legitimate users.
+
+
+### 🚀 Improvements
+
+*   **Smarter Challenge Difficulty**:
+    *   The difficulty of optimization challenges now scales more intelligently with the client's `suspicionFactor`.
+    *   A minimum difficulty has been established for challenges to ensure they are always meaningful, preventing trivial PoW tasks even for low-suspicion clients.
+    *   Added a linear "decay" mode as an alternative to exponential scaling. If a `scalingFactor` is not defined for a problem, the difficulty increases linearly, providing a gentler curve for low-suspicion clients.
+
+*   **Data Point Capping**:
+    *   Added a `maxDataPoints` option to problem configurations to prevent datasets (e.g., TSP points) from growing indefinitely. This ensures stable performance and memory usage over time. (Thanks, @anonympins!)
+*   **Enhanced Test Suite**:
+    *   Added comprehensive unit tests for the new `ProblemManager`, ensuring the reliability of problem loading, work dispatching, solution integration, and the new dynamic configuration features.
+
+### Internal & Developer Experience
+
+*   The core logic for managing, dispatching, and updating optimization problems is now encapsulated within `problem-manager.js`.
+*   The project now uses `vitest` for running tests, as configured in `package.json`.

package/README.md

@@ -5,7 +5,14 @@
 ![GitHub commit activity](https://img.shields.io/github/commit-activity/w/anonympins/fingerprint)
 [![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.
+An HTTP(S) client mitigation and anti-bot protection library for both PHP and Node.js/Express, based on digital fingerprinting and dynamic Proof-of-Work (PoW) challenges.
+
+## Installation and Usage
+
+This library is available for both **Node.js** and **PHP**.
+
+*   [PHP Quickstart](#php-quickstart)
+*   [Node.js Quickstart](#nodejs-quickstart)
 
 ## How It Works
 
@@ -47,17 +54,9 @@ For API clients, the challenge is delivered as a `404` JSON response, and the cl
 -   **Timing Attack Protection**: Uses `crypto.timingSafeEqual` for secure validation of tickets and other signatures.
 -   **Bot Whitelisting**: Includes a DNS-based verification mechanism to reliably identify and whitelist legitimate crawlers like Googlebot and Bingbot, preventing them from being challenged. The results are cached for optimal performance.
 -   **Automatic Parameter Tuning**: Includes a genetic algorithm-based optimizer (`startThresholdAutoTuning`) that analyzes real traffic to dynamically adjust suspicion thresholds, weights, and behavioral pattern detection parameters, improving accuracy and reducing false positives over time. The tuner is hardened against data poisoning attempts.
+-   **Optional WASM Acceleration**: The client-side library can be accelerated with a WebAssembly module for high-performance hashing. The build process handles this optionally, and the client gracefully falls back to a pure JavaScript implementation if WASM is unavailable.
 -   **Hardened Security**: Protects against various attacks, including DoS via memory exhaustion, invalid nonce submission, and uses cryptographically secure randomness for all sensitive operations.
 
-## Installation and Usage
-
-This library is available for both **Node.js** and **PHP**.
-
-*   [Node.js (Express) Quickstart](#nodejs-express)
-*   [PHP Quickstart](#php)
-    *   [PHP Quickstart (Direct Integration)](#php-quickstart-direct-integration)
-    *   [PHP Quickstart (PSR-15 Middleware)](#php-quickstart-psr-15-middleware)
-
 ### Prerequisites
 
 *   **PHP 7.4+**
@@ -66,7 +65,7 @@ This library is available for both **Node.js** and **PHP**.
 
 ---
 
-### Prerequisites
+<a id="php-quickstart"></a>
 
 ## PHP Quickstart (Direct Integration)
 
@@ -114,6 +113,15 @@ $securityConfig = SecurityProfiles::createSecurityProfile('balanced', [
     'verbose' => true,
 ]);
 
+/*
+ * IMPORTANT: Unlike Node.js, standard PHP environments (like PHP-FPM) cannot directly access
+ * the raw TLS handshake to compute JA3/JA4 fingerprints.
+ * To enable robust TLS fingerprinting in PHP, you must use a reverse proxy (like Nginx,
+ * HAProxy, or a cloud load balancer) configured to extract the fingerprint and pass it
+ * to your application via an HTTP header (e.g., `X-JA3-Hash`). The library is already
+ * built to consume these headers automatically.
+ */
+
 // 2. Create an instance of the DirectFingerprint protector.
 $protector = new DirectFingerprint($securityConfig);
 
@@ -134,13 +142,244 @@ echo "<p>Your suspicion score was: " . round($score, 2) . "</p>";
 ?>
 ```
 
-### [NodeJS Configuration](nodejs-express)
+### Full Configuration Example (PHP)
 
-#### Prerequisites for Node.js
+If you prefer to define the entire configuration manually instead of using a profile, you can create a `$securityConfig` array with all the parameters. All parameters are optional, but it is highly recommended to review and adjust them for your specific needs. The engine will warn you about any unknown keys in this configuration, helping you catch typos.
+
+```php
+<?php
+
+use Anonympins\Fingerprint\Utils\DefaultWhitelist;
+
+// Array to store traffic analysis data for the auto-tuner.
+// In a real application, this could be a more robust logging system.
+$trafficData = [];
+
+// Configuration of weights and thresholds for calculating the suspicion score.
+// These values should be adjusted based on traffic and expected user behavior.
+$securityConfig = [
+    'weights' => [
+        'historyScore' => 0.3,       // Penalizes IP rotation (proxy)
+        'rotationScore' => 0.5,      // Penalizes rapid fingerprint changes (user-agent, etc.)
+        '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
+        'crossLayerInconsistencyScore' => 0.4, // Penalizes mismatches between client-side data (e.g., OS) and server-side headers (e.g., User-Agent)
+        'timeInconsistencyScore' => 0.9, // Strongly penalizes large time gaps between client metric collection and server reception (replay attack)
+        'tlsSpoofingScore' => 0.8,     // Penalizes mismatches between the TLS fingerprint (JA3/JA4) and the User-Agent (client spoofing)
+        'botScore' => 1.0,             // Penalizes explicit bot markers from the client
+        'cookieDroppingScore' => 0.9,  // Penalizes clients that appear to be intentionally dropping cookies
+        'threatIntelScore' => 0.4,     // Penalizes requests from known malicious IPs (proxies, Tor, etc.)
+    ],
+    '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)
+    ],
+    '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.
+    'deviceIdCookieMaxAge' => null, // By default, it's a session cookie. Set a value in ms for a persistent cookie.
+    'challengePagePath' => './path/to/your/custom-challenge-page.html', // (Optional) Path to a custom HTML template for the challenge page.
+    'verbose' => ($_ENV['APP_ENV'] ?? 'production') !== 'production', // Log detailed info in development.
+    'patterns' => [ // (Optional) Initial values for request pattern detection, optimized by auto-tuner if enabled.
+        'historySize' => 10,          // Number of requests to keep for pattern analysis
+        '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.
+        'fields' => ['email_confirm', 'user_nickname', 'debug', 'test_mode', 'admin'], // (Optional)
+        // List of URL paths that should never be accessed by a legitimate user.
+        'trapUrls' => ['/wp-admin', '/.env', '/admin.php', '/phpmyadmin'], // (Optional)
+        // Automatically detect common injection patterns. Can be a boolean or an array of specific types.
+        'detectInjections' => ['sql', 'rce', 'traversal', 'xxe', 'ssti', 'log4shell'], // (Optional, default: true)
+        // (Optional) Plug in external analyzers. Each must be a callable that receives request data
+        // and returns `true` if a threat is detected.
+        'analyzers' => [
+            // Example: A custom function to detect specific keywords (e.g., for anti-spam).
+            function ($data) {
+                $spamKeywords = ['viagra', 'free money', 'crypto pump'];
+                $dataString = strtolower(json_encode($data));
+                foreach ($spamKeywords as $keyword) {
+                    if (str_contains($dataString, $keyword)) {
+                        return true;
+                    }
+                }
+                return false;
+            }
+        ]
+    ],
+    // (Optional) Whitelisting configuration.
+    'whitelist' => [
+        // Option 1: Static IP Allowlist (IPs or CIDR ranges).
+        [
+            '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
+            ]
+        ],
+        // Option 2: Host + Path Allowlist (supports wildcards).
+        [
+            'type' => 'host_path_allowlist',
+            'entries' => [
+                'api.yourdomain.com/v1/webhooks/*', // All paths under /v1/webhooks on a specific host
+            ]
+        ],
+        // Option 3: Path Allowlist (supports wildcards).
+        [
+            'type' => 'path_allowlist',
+            'entries' => [
+                '/api/v2/public-stats', // Exact path
+                '/callbacks/trusted-source/*', // All paths under /callbacks/trusted-source/
+            ]
+        ],
+        // Option 4: GraphQL Operation Allowlist (supports wildcards).
+        [
+            'type' => 'graphql_operation_allowlist',
+            'entries' => [
+                'query:GetPublicPosts', // A specific query
+                'mutation:*'            // All mutations
+            ]
+        ],
+        // Option 5: DNS-verified bots (e.g., search engine crawlers).
+        // You can use the provided default list and extend it.
+        ...DefaultWhitelist::getRules(), // Use the defaults
+        ['userAgent' => 'MyCustomBot', 'hostnameSuffix' => '.my-bot-verifier.com'], // Add a custom bot
+    ],
+    // (Optional) Custom function to identify API requests. Must be a callable.
+    'isApiRequest' => function (RequestContext $context) {
+        return str_starts_with($context->path, '/api/') ||
+               str_contains($context->getHeader('accept') ?? '', 'application/json');
+    },
+    // The logger is required for auto-tuning. It must be a callable.
+    'logger' => function ($log) use (&$trafficData) {
+        $trafficData[] = $log;
+    },
+    // (Optional) Configuration for the automatic threshold and pattern tuning.
+    'autotuning' => [
+        'trafficData' => &$trafficData, // Pass the data source by reference.
+        'interval' => 1800,              // Optimization cycle every 30 minutes (in seconds for a cron job).
+        'minDataPoints' => 200,
+        'maxDataPoints' => 20000,
+        'savePath' => './security-config.optimized.json' // (Optional) Save the best config found.
+    ],
+    // Enables "Useful Proof-of-Work" for suspicious activity.
+    'enableUsefulWork' => true,
+    // Provide either a path to a JSON file or the configuration as an array.
+    'usefulWorkConfigPath' => './path/to/your/problems.config.json', // (Optional)
+    // Or provide the configuration directly as an array.
+    // 'usefulWorkConfig' => [ /* ... your problem definitions ... */ ]
+];
+
+```
+## TLS Fingerprinting (JA3/JA4) with Nginx and Apache
+
+Unlike Node.js, which can directly inspect the TLS handshake, a standard PHP environment (such as PHP-FPM) runs behind a web server (Nginx, Apache) that terminates the TLS connection. Consequently, the PHP script lacks direct access to the low-level information required to calculate the JA3 fingerprint.
+
+If you want a **better protection**, the standard solution is to delegate this calculation to the front-end web server (or a reverse proxy like HAProxy) and pass the result to PHP via an HTTP header. The library is designed to automatically detect and utilize these headers.
+
+### Automatic Detection in the Library
+
+The PHP `RequestContext` class automatically looks for the following headers.
+
+Once these headers are present, the `FingerprintEngine` incorporates them into the composite device fingerprint, providing the same level of robustness as the Node.js version.
+
+---
+
+### Configuration with Nginx
+
+Nginx is the simplest and most common solution. It requires your Nginx instance to be compiled with the `ngx_http_ssl_ja3_module` module. Many modern Nginx builds or distribution-provided packages include it. Here is an example configuration:
+
+```nginx
+http {
+# ... other http configurations ...
+
+# Declare a variable to store the JA3 fingerprint. 
+# Nginx automatically populates $ssl_ja3_hash if the module is active. 
+map $ssl_ja3_hash $ja3_hash {
+default $ssl_ja3_hash; 
+}
+
+server {
+listen 443 ssl http2; 
+server_name yourdomain.com; 
+
+# ... SSL configuration (certificates, etc.) ...
+ssl_certificate /path/to/your/fullchain.pem; 
+ssl_certificate_key /path/to/your/privkey.pem; 
+
+location / {
+# ... your application configuration ...
+try_files $uri $uri/ /index.php?$query_string; 
+}
+
+location ~ \.php$ {
+include fastcgi_params; 
+fastcgi_pass unix:/var/run/php/php8.1-fpm.sock; # Adjust for your PHP version
+fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; 
+
+# Add the JA3 fingerprint as a FastCGI parameter. 
+# PHP will make it available in $_SERVER['HTTP_X_JA3_HASH']. 
+fastcgi_param HTTP_X_JA3_HASH $ja3_hash; 
+}
+}
+}
+```
+
+After reloading the Nginx configuration, the `X-JA3-Hash` header will be automatically available to your PHP application.
+
+---
+
+### Configuration with Apache
+
+For Apache, obtaining the JA3 fingerprint is less straightforward because there is no standard module as widely available as the one for Nginx.
+
+#### Option 1: `mod_ssl_ja3` module (Recommended)
+
+The best approach is to use a third-party module like `mod_ssl_ja3`. You will need to compile and load it into your Apache configuration. Once the module is installed and enabled, you can add the JA3 header to your requests using the `RequestHeader` directive in your Virtual Host configuration:
+
+```apache
+<VirtualHost *:443>
+ServerName yourdomain.com
+# ... SSL configuration ...
+
+# The JA3_HASH environment variable is provided by mod_ssl_ja3
+RequestHeader set X-JA3-Hash "%{JA3_HASH}e"
+
+# ... your PHP application configuration ...
+</VirtualHost>
+```
+
+#### Option 2: Using a Reverse Proxy in front of Apache
+
+If you cannot compile modules for Apache, a very robust alternative is to place another service in front to handle TLS termination. **HAProxy** is an excellent choice for this, as it can calculate the JA3 hash natively and add it as a header before forwarding the request (via plain HTTP) to Apache.
+
+This architecture is common in high-performance environments and offers great flexibility.
+
+---
+
+<a id="nodejs-quickstart"></a>
+## NodeJS Quickstart
+
+### Prerequisites for Node.js
 
 Ensure you have middleware for parsing cookies (like `cookie-parser`) and request bodies (like `express.json` and `express.urlencoded`) set up in your Express application *before* the `powMiddleware`.
 
-#### Configuration
+### Configuration
 Define a secret key for signing PoW tickets in your environment variables.
 
 ```bash
@@ -162,7 +401,7 @@ Available profiles:
 import express from 'express';
 import bodyParser from 'body-parser';
 import cookieParser from 'cookie-parser';
-import { powMiddleware, createSecurityProfile } from './fingerprint.js'; // Adjust the path
+import { powMiddleware, createSecurityProfile } from '@anonympins/fingerprint'; // Adjust the path
 
 const app = express();
 app.use(cookieParser());
@@ -189,7 +428,8 @@ const securityConfig = createSecurityProfile('api', {
         trafficData: trafficData,
         interval: 1800000, // 30 minutes
         minDataPoints: 200,
-    }
+        savePath: './security-config.optimized.json' // (Optional) Save the best config found.
+    },
 });
 
 // Create an instance of the middleware with your security configuration.
@@ -221,7 +461,7 @@ app.listen(3000, () => console.log('Server started on port 3000'));
 If you prefer to define the entire configuration manually instead of using a profile, you can create a `securityConfig` object with all the parameters. All parameters are optional, but it is highly recommended to review and adjust them for your specific needs. The engine will warn you about any unknown keys in this configuration, helping you catch typos.
 
 ```javascript
-import { default_whitelist, default_analyzers } from './fingerprint.js';
+import { powMiddleware, default_whitelist, default_analyzers } from '@anonympins/fingerprint';
 
 const app = express();
 app.use(cookieParser());
@@ -255,7 +495,7 @@ const securityConfig = {
     },
     cpu: {
         minDifficultyBits: 8,
-        maxDifficultyBits: 24,
+        maxDifficultyBits: 32,
     },
     // (Optional) Configure the duration (in milliseconds) for various temporary data.
     ticketMaxAge: 3600000, // 1 hour. Duration for which a solved challenge ticket is valid.
@@ -313,7 +553,8 @@ const securityConfig = {
         { 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
+                '2001:db8::/32',      // An IPv6 range
+                '2a01:e0a:129:57c0::1' // A specific IPv6 address
             ]},
         { type: 'hostname_allowlist', entries: [
                 'google.com',      // A specific hostname
@@ -355,12 +596,22 @@ const securityConfig = {
         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.
-        maxDataPoints: 20000              // Minimum requests before starting an optimization cycle.
+        maxDataPoints: 20000,             // Maximum log entries to keep in memory.
+        savePath: './security-config.optimized.json' // (Optional) Save the best config found.
     },
     // Enables problem solving for suspicious activity (configurable in problems.config.json)
     enableUsefulWork: true,
-    usefulWorkConfigPath: './path/to/your/problems.config.json' // (Optional) Path to the useful work configuration.
+    // (Optional) Path to the useful work configuration.
+    usefulWorkConfigPath: './path/to/your/problems.config.json',
+    // or usefulWorkConfig: [ /* ... your problem definitions ... */ ],
+    // (Optional) Enable "dry run" mode. The engine will calculate scores and log intended actions
+    // but will never actually block or challenge a request. Useful for testing new configs in production.
+    dryRun: false,
 };
+
+
+// Create an instance of the middleware with your security configuration.
+const powMiddlewareInstance = powMiddleware(securityConfig);
 ```
 
 
@@ -368,32 +619,28 @@ const securityConfig = {
 
 ## Advanced Behavioral Analysis
 
-The FingerprintEngine includes sophisticated behavioral analysis to detect non-human patterns. This analysis is performed by the `getRequestPatternScore` function, which is a stateful check that looks for repetitive or unnaturally fast requests from a single device.
+The `FingerprintEngine` includes sophisticated behavioral analysis to detect non-human patterns. This analysis is performed by the `getRequestPatternScore` function, which is a stateful check that looks for repetitive or unnaturally fast requests from a single device.
 
 This function uses several configurable parameters to identify suspicious behavior:
 
-### Core Pattern Detection
+### Statistical Analysis (Regularity and Benford's Law)
 
-These parameters form the basis of the request pattern analysis:
+To counter more advanced bots that might try to randomize their request timings, the engine employs statistical analysis.
 
-*   `velocityThreshold`: (Default: 800ms) Penalizes requests that are too fast to be humanly possible. If the time since the last request from a device is less than this value, the suspicion score increases.
-*   `burstThreshold`: (Default: 1500ms) Adds a significant penalty for multiple identical requests (same path and query parameters) occurring in a very short time frame. This is a strong indicator of automated retries or brute-force attacks.
-*   `scrapeThreshold`: (Default: 1000ms) Penalizes sequential requests to the same path but with different query parameters. This pattern is typical of scraping bots that iterate through pages or product IDs.
-*   `sequenceLength`: (Default: 3) Detects repetitive sequences of requests (e.g., A -> B -> C -> A -> B -> C), which is a common pattern for scripted bots navigating a site.
+*   **Regularity Detection**: The system also calculates the standard deviation of the time intervals between requests. A very low standard deviation indicates an unnaturally regular, "cron-like" behavior, which is a strong signal of automation.
+*   **Benford's Law Analysis**: Benford's Law states that in many naturally occurring sets of numbers, the leading digit is more likely to be small. The timings between a human's requests tend to follow this natural distribution, whereas a bot's randomized delays often do not. The engine penalizes distributions that violate this law.
 
-### Statistical Analysis (Benford's Law)
+### Core Pattern Detection Parameters
 
-To counter more advanced bots that might try to randomize their request timings, the engine employs statistical analysis based on Benford's Law.
+These parameters form the basis of the statistical request pattern analysis:
 
-*   **How it works**: Benford's Law states that in many naturally occurring sets of numbers, the leading digit is more likely to be small. For example, the number 1 appears as the leading digit about 30% of the time, while 9 appears less than 5% of the time. The timings between a human's requests tend to follow this natural distribution, whereas a bot's randomized delays often do not.
+*   `regularityThreshold`: (Default: 50ms) The standard deviation in milliseconds below which the request timing is considered "too regular" and robotic.
+*   `benfordThreshold`: (Default: 0.15) The deviation score from Benford's Law above which the timing distribution is considered "unnatural".
+*   `patternWeight`: (Default: 80) A strong, one-time penalty applied to the suspicion score if either a regularity or Benford's Law anomaly is detected.
 
 *   `benfordMinSamples`: (Default: 15) The minimum number of request timings to collect before performing a Benford's Law test.
 *   `benfordWeight`: (Default: 50) The weight applied to the suspicion score if the distribution of timings significantly deviates from Benford's Law.
 
-### Configuration and Auto-Tuning
-
-All these parameters are part of the `patterns` object within the main security configuration and can be fine-tuned.
-
 ## Customizing the Challenge Page
 
 You can provide your own HTML template for the Proof-of-Work challenge page to maintain a consistent user experience with your brand.
@@ -454,7 +701,7 @@ The library provides ready-to-use adapters for popular datastores like **Redis**
 **Redis Example:**
 
 ```javascript
-import { configureStore } from './fingerprint.js';
+import { configureStore } from '@anonympins/fingerprint';
 import { createRedisStore } from './redis-store.js';
 import Redis from 'ioredis';
 
@@ -617,6 +864,15 @@ initializeClient({
  
   // (Optional) An array of `name` attributes for hidden form fields that act as bot traps.
   honeypots: ['email_confirm', 'user_nickname', 'website_url'],
+
+  // (Optional) An array of signed trap URLs provided by the server. The client will
+  // dynamically inject these into the DOM to trap bots that parse the live DOM.
+  trapUrls: ['/backups/db.sql.gz?sig=...', '/.env?sig=...'],
+ 
+  // (Optional) Path to the WebAssembly loader script (`fp.js`) for accelerated hashing.
+  // If provided, the client will attempt to load the WASM module. If it fails or is not available,
+  // it will gracefully fall back to the pure JavaScript implementation.
+  wasmPath: '/fp.js',
  
   // (Optional) Enables automatic protection for `fetch` requests.
   // If the `fetch` object is present, the protection is active.
@@ -743,6 +999,11 @@ app.get('/api/problems/solutions', (req, res) => {
 
 ```
 
+#### `getBestTuningSolution()`
+
+Returns the last best solution object found by the auto-tuner. This is particularly useful for "FinOps" or for auditing the tuner's performance, as it allows you to log the exact configuration that the genetic algorithm identified as optimal.
+
+*   **Returns**: (`object|null`) The best solution object `{ solution, objectives }` or `null` if no tuning cycle has completed yet. The `solution` property contains the optimized `weights`, `thresholds`, and `patterns`, while `objectives` contains the performance scores (e.g., false positive/negative rates) for that solution.
 
 #### `problemManager.updateProblemPayload(problemId, newPayload)`
 
@@ -768,7 +1029,7 @@ Updates the payload (parameters) of a specific problem by its ID. This allows fo
 
 ```javascript
 import http from 'http';
-import { FingerprintEngine } from './fingerprint.js'; // Adjust path
+import { FingerprintEngine } from '@anonympins/fingerprint'; // Adjust path
 
 const securityConfig = { /* ... your config ... */ };
 const engine = new FingerprintEngine(securityConfig);