Hotfix 0.2.1 (stable)

Changelog

Improved Security Challenges

• CPU Challenge Rework: The CPU Proof-of-Work (PoW) challenge mechanism has been significantly refactored to resolve previous issues, ensuring a more robust and reliable defense against automated threats. This enhancement improves the effectiveness of the challenge without impacting legitimate users.

Enhanced Test Coverage

• Unit Test Refactor: The unit tests for the challenge features have been completely rewritten. This ensures comprehensive coverage and validates the stability and correctness of the updated challenge logic, providing greater confidence in the system's security.

Tested gracefully in production on https://primals.net

Release 0.2.0

Changelog

• isApiRequest / isStaticResource](1813021)

Cryptographic Binding of the Solver Fingerprint to the Proof of Work

To counter sophisticated attacks where a bot might offload challenge solving to a server farm (workers), we have introduced a new security layer. The system now cryptographically binds the digital fingerprint of the machine solving the challenge to the solution itself.

Technical Details

1. Client Side (Solver):

• The solver (pow.solver.inline.js) now generates the client machine's fingerprint.
• This fingerprint is included in the message hashed for the Proof of Work (PoW) when clientSecret is used.
• Upon solution submission, the solver fingerprint is sent to the server via a new URL parameter: pow_fp.

2. Server Side (Verification):

• When issuing a challenge, the server stores the digital fingerprint of the original request within the challenge context.
• Upon receiving a solution, the server performs a double check:

1. Consistency Check: It compares the solver fingerprint (pow_fp) with the stored original fingerprint. If they do not match, validation fails immediately. This blocks attempts to solve the challenge on a remote machine.

2. Cryptographic Verification: If the fingerprints match, the solver fingerprint is included in the hash recalculation to validate the Proof of Work, ensuring the solution was indeed calculated using the correct fingerprint.

3. Unit Test Updates:

• Tests simulating challenge solving have been updated to include the solver fingerprint in hash calculations and submission requests. * Tests setting up a challenge context within the mocked store now include the expected fingerprint.

Impact

This change significantly increases the system's robustness. It ensures that the Proof-of-Work "effort" is actually performed by the client machine that initiated the request, rendering parallelization attacks using external servers ineffective and much more costly to implement.

Feature: Useful Proof-of-Work (U-PoW)

This update introduces a new challenge mechanism called "Useful Proof-of-Work" (U-PoW), which can be enabled via the enableUsefulWork: true flag in the security configuration.

Instead of making the client's browser perform computationally expensive but otherwise useless hash calculations, U-PoW leverages the client's processing power to contribute to solving complex optimization problems that are beneficial to the platform.

How It Works

1. Dynamic Challenge Issuance: When a request is flagged as suspicious, the system can now randomly issue a U-PoW challenge instead of a traditional PoW. This makes bot automation more difficult, as attackers cannot predict the type of challenge they will receive.

2. Problem Dispatching: The server maintains a pool of complex problems (e.g., Traveling Salesperson Problem, Portfolio Optimization) via a problemManager. When a U-PoW challenge is needed, the manager dispatches a small, discrete unit of work to the client. The difficulty and size of the work unit are proportional to the request's suspicion score.

3. Client-Side Computation: The client's browser receives the work unit and uses its own CPU resources to perform the calculations. This is handled by the solveUsefulWorkTask function in the client-side solver. The client-side library includes lightweight versions of advanced optimization algorithms (like Simulated Annealing and Genetic Algorithms) to solve these tasks.

4. Solution Integration: Once the computation is complete, the client sends the result back to the server. The server then integrates this partial solution into the main problem being solved, advancing it towards a final, optimal solution.

5. Verification and Clearance: If the submitted work is valid, the client is granted a clearance ticket, just like with a standard PoW, and their original request is allowed to proceed.

Key Benefits

• Resource Monetization: Turns the cost of bot mitigation into a productive asset. The CPU cycles of suspicious clients are harnessed to solve real business or research problems, effectively creating a distributed computing network.
• Enhanced Security: The variety of challenge types (standard PoW vs. different U-PoW tasks) significantly increases the complexity and cost for bot developers, as they must implement solvers for multiple, non-trivial algorithms.
• Scalable Problem Solving: The system is designed to manage and aggregate solutions for large-scale optimization problems, making it suitable for tasks that would be too costly to run on a single server.

New Components

• problem-manager.js: A new server-side module responsible for managing the lifecycle of optimization problems, dispatching work units, and integrating solutions.
• solveUsefulWorkTask (in pow.solver.js): A new client-side function that acts as a router to solve various types of optimization tasks sent by the server.

Release 0.1.4

Summary of Recent Improvements

This update focuses on strengthening security, improving the user experience during security challenges, and enhancing the overall robustness of the system.

1. Security Challenge Enhancements

• Non-Blocking Memory Challenges: The memory-based challenges (Memory PoW) have been optimized to include regular pauses. This prevents the browser from freezing during intensive calculations, providing a smoother user experience without sacrificing security.
• BigInt Conversion Fix: The handling of very large numbers (BigInt) used in CPU challenges has been made more reliable. Conversion from strings is now more robust, preventing potential errors during challenge resolution.
• XSS Injection Prevention: The HTML challenge pages generated by the server have been secured. Dynamic data (like the nonce or redirect URL) is now correctly escaped using JSON.stringify, eliminating any risk of malicious code injection (XSS) by an attacker.

2. Enhanced Threat Detection

• Improved Command Injection Detection: The regular expression (RegExp) used to detect command injection attempts has been refined. It is now more precise and targets dangerous patterns (ping, rm, bash, etc.) while significantly reducing false positives that could occur with legitimate data.

3. Introduction of the "Probationary Ticket"

A new "probationary ticket" system has been implemented to make automated attacks much more costly while preserving the experience for legitimate users.

• How It Works:

  • Normal Activity: A legitimate user who solves a challenge receives a long-duration ticket, minimizing interruptions.
  • Suspicious Activity: A request deemed suspicious receives a very short-duration ticket (e.g., 30 seconds).

• Benefits:

  1. Increased Cost for Bots: A bot is forced to solve challenges continuously, making scraping or brute-force attacks economically and technically unsustainable.
  2. Reduced Attack Window: Even if a bot successfully solves a challenge, its access is time-limited, preventing it from carrying out a large-scale attack.
  3. Better User Experience: This system better distinguishes unusual but legitimate behavior from persistent malicious activity, thus reducing friction for real users.

4. Improved Code Quality and Testing

• Strengthened Unit Tests: New unit tests have been added to cover the security modifications, particularly XSS prevention and the probationary ticket logic. This ensures that these protections remain effective and prevents future regressions.

Tested in production on https://primals.net

Hotfix 0.1.3

Changelog

• no false positive on command injection
• client pow solver fix + UT
• custom html page

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.

1. Configuration: In your securityConfig, specify the path to your template file using the challengePagePath option.

   const securityConfig = {
       // ... other options
       challengePagePath: './path/to/your/custom-challenge-page.html',
   };

2. Template Placeholders: Your HTML file must contain the following placeholders. The system will replace them with the dynamic JavaScript code required to run the challenge.

   • <!-- FINGERPRINT_SOLVER_SCRIPT -->: This will be replaced by the script that contains the logic for solving the CPU and memory challenges.
   • <!-- FINGERPRINT_CHALLENGE_SCRIPT -->: This will be replaced by the script that initiates the challenge with the specific parameters for the current request (nonce, difficulty, etc.).
   • <!-- FINGERPRINT_TRAPS -->: This will be replaced by hidden "honeypot" links designed to trap simple bots. This placeholder is crucial for an effective defense.

Example Custom HTML Template

Here is a basic example of what your custom-challenge-page.html could look like:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Security Verification</title>
    <style>
        body { font-family: sans-serif; text-align: center; padding-top: 50px; }
        h1 { color: #333; }
    </style>
</head>
<body>
    <h1>Please wait while we verify your connection...</h1>
    <div id="loader" style="margin:20px;">⚙️ Initializing verification...</div>

    <script><!-- FINGERPRINT_SOLVER_SCRIPT --></script>
    <script><!-- FINGERPRINT_CHALLENGE_SCRIPT --></script>
    <!-- FINGERPRINT_TRAPS -->
</body>
</html>

Hotfix 0.1.1

• The solver in the HTML was inefficient. We use the pow solver now.
• Using a better isMalicious default method
• Added a verbose mode
• Better fingerprints
• We use 404 errors to be detected as no threat by the robots. Very efficient.
• Velocity/burst default modified
• Default isApiRequest used
• Client issue when using the initializeClient on the browser (window bind)

Release 0.1.0

Release 0.1.0 (August 23, 2026)

This initial release introduces the core functionality of the fingerprint library, establishing a robust framework for bot detection and mitigation through device fingerprinting and dynamic Proof-of-Work challenges.

✨ New Features

• Core Fingerprinting Engine: Implemented the initial FingerprintEngine for identifying devices based on a combination of client-side and server-side signals.
• Client-Side Behavioral Analysis (behaviorScore): The system now analyzes client-side behavior (mouse movement, typing speed) via the X-Behavior-Metrics header to generate a behaviorScore, providing a powerful new signal for detecting non-human patterns.
• Automatic PoW Challenge Resolution: The client-side library can now automatically intercept 429 JSON responses containing a Proof-of-Work challenge, solve it in the background, and seamlessly retry the original request.
• Web Worker for CPU Challenges: CPU-intensive Proof-of-Work challenges are now offloaded to a dedicated Web Worker (pow.worker.js), preventing the user's browser UI from freezing during complex calculations.
• Multi-Objective Optimization (Pareto Front): Implemented advanced genetic algorithms (inspired by NSGA-II) to solve multi-objective problems, such as finding the optimal ticket TTL that balances security risk and user friction.
• "Challenge New Devices" Policy: Added a challengeNewDevices configuration option. When enabled, all new, previously unseen devices will receive a minimal, low-friction challenge to validate their identity.

🚀 Improvements & Fixes

• Dynamic Ticket TTL: The ticketMaxAge configuration can now be a function that accepts the suspicion score, allowing for dynamic ticket durations (e.g., shorter validity for more suspicious users).
• Enhanced Genetic Algorithms: Improved the mutation operators in the optimization library for better and faster convergence when auto-tuning parameters.
• Refined Challenge Validation: Strengthened the server-side validation logic for all types of PoW solutions to prevent bypasses.
• Test Suite Reliability: Added retries to flaky tests to improve the stability and reliability of the CI pipeline.
• Documentation: Significantly updated the README.md to reflect all new features, provide clearer integration examples, and explain the client-server synergy.

📦 Build & Dependencies

• Updated package.json with the latest project information.

↩️ Reverts

• Reverted the "curved menace factor" implementation to maintain a more predictable scoring model for this release.

Release 0.0.9

Tested in production (stable enough for now)

Release Notes - v0.0.9

This release introduces major features for scalability, security, and ease of use, alongside significant documentation improvements.

✨New Features

• External Storage Adapters (c88af59, 99ca8ee):

• Introduced support for external datastores to enable persistence and scalability across multiple server instances.

• Added ready-to-use adapters for Redis (redis-store.js), MongoDB (mongodb-store.js), and SQL databases via Knex (sql-store.js).

• These adapters automatically handle the expiration of temporary data (TTL), such as PoW challenge secrets.

• IP and Network Whitelist (33142b3):

• Added a new whitelist configuration option to bypass all security checks for trusted IP addresses or CIDR ranges.

• This is useful for internal tools, trusted partners, or monitoring services.

🚀Improvements

• Unified Client-Side Initialization (75f16b5):

• Added the initializeClient function to the client library (fingerprint.client.js) to configure all protections (mouse tracking, keystroke tracking, honeypots, fetch interception) via a single, simple configuration object.

• Improved Documentation (811036e):

• Completely revised the README.md file to include detailed explanations regarding the new storage adapters, whitelist configuration, and the new initializeClient function. ### 🐛Corrections

• Dependencies and Tests (e246a39, dc80343):

• Fixed peerDependencies in package.json to make them optional, preventing unnecessary installations.

• Updated and fixed unit tests to ensure stability and compatibility with new features.

Release 0.0.8

Release v0.0.8 - Whitelisting Engine & Proactive Client-Side Defenses

This release introduces two major features designed to improve accuracy and proactively detect threats: a sophisticated whitelisting engine to reliably allow legitimate bots, and a powerful client-side library to gather rich behavioral data and stop bots before they even reach the server.

🎉 New Features

1. Advanced Bot Whitelisting Engine

A new two-tiered whitelisting system has been integrated to prevent legitimate crawlers and trusted services from being challenged, ensuring that SEO and critical services are not impacted. These checks are performed at the very beginning of the request lifecycle for maximum efficiency.

• Static IP/CIDR Allowlist: You can now configure a static list of IP addresses and CIDR ranges that will always bypass all security checks. This is ideal for whitelisting internal tools, monitoring services, or trusted partners.

• DNS-Based Bot Verification: The library can now reliably identify legitimate crawlers (like Googlebot, Bingbot, etc.) using a secure DNS verification method (reverse lookup followed by a forward lookup). To avoid performance overhead, verification results are cached per IP.

• Comprehensive Default Whitelist: A default_whitelist() function is now exported, providing a pre-configured list of over 50 common and legitimate crawlers from search engines, SEO tools, social media platforms, and monitoring services. This list can be easily extended with your own custom rules.

2. Proactive Client-Side Library (fingerprint.client.js)

The new client-side library acts as a "force multiplier" for the server-side defenses. It enables proactive threat detection directly in the user's browser, saving server resources and providing much richer data for suspicion scoring.

• Richer Fingerprinting: getDeviceFingerprint() now collects hardware-level signals (Canvas, WebGL, CPU cores, device memory) that are significantly harder for bots to spoof consistently compared to server-side headers.

• Behavioral Analysis: The client can now track non-human interaction patterns that are invisible to the server:

  • startMouseEntropyTracker(): Detects unnatural mouse movements (or lack thereof).
  • startKeystrokeDynamicsTracker(): Analyzes typing rhythm to distinguish between human and automated input.

• Client-Side Honeypots: initializeHoneypots() sets up traps on hidden form fields. If a bot fills one, it is flagged instantly on the client-side, and this information is sent to the server for an immediate block.

• Seamless Integration: The new initializeClient() function allows you to enable all client-side protections with a single line of code. It automatically patches the global fetch API to enrich outgoing requests with security headers (X-Device-Fingerprint and X-Behavior-Metrics), providing the server with valuable data for more accurate decision-making.

Release 0.0.7

Changelog

Version 0.0.7

✨ New Features

• Pluggable Honeypot Analyzers: The honeypot system now supports external, user-provided analyzer functions. This allows for integration with specialized libraries (e.g., WAFs, anti-spam services) for more robust threat detection in request bodies and query parameters.

const securityConfig = {
    // ... autres configurations de poids et de seuils
    honeypot: {
        // ... autres configurations de honeypot
        
        // (Optional) Plug in external, more robust analyzers. This allows you to extend the default detection 
        // with specialized libraries (e.g., WAFs, anti-spam) or your own custom logic.
        // Each function receives an object with all query and body data and should return `true` if a threat is detected.
        analyzers: [
            // Example 1: Using a general-purpose WAF library.
            // (You would need to install it: `npm install generic-waf`)
            (data) => {
                try {
                    const WAF = require('generic-waf');
                    const waf = new WAF();
                    // This WAF expects a string, so we stringify the data to check all values at once.
                    return waf.isMalicious(JSON.stringify(data));
                } catch (e) {
                    console.error("Could not load 'generic-waf'. Make sure it is installed.", e);
                    return false;
                }
            },

            // Example 2: Using a specialized library for XSS detection.
            // (You would need to install it: `npm install xss`)
            (data) => {
                try {
                    const xss = require('xss');
                    const originalData = JSON.stringify(data);
                    // If the sanitized string is different from the original, it means malicious HTML/JS was found and removed.
                    return xss(originalData) !== originalData;
                } catch (e) {
                    console.error("Could not load 'xss'. Make sure it is installed.", e);
                    return false;
                }
            },

            // Example 3: A custom function to detect specific keywords (e.g., for anti-spam).
            (data) => {
                const spamKeywords = ['viagra', 'free money', 'crypto pump'];
                const dataString = JSON.stringify(data).toLowerCase();
                return spamKeywords.some(keyword => dataString.includes(keyword));
            }
        ]
    },
    // ...
};

• JA3 Fingerprinting from Reverse Proxy: The system can now utilize the x-ja3-hash header, typically provided by reverse proxies like Nginx or Cloudflare, for more reliable TLS fingerprinting without needing direct access to the Node.js TLS socket.

🚀 Improvements

• Enhanced Request Pattern Analysis: The sequence detection logic has been improved to identify more complex repetitive request patterns (e.g., A -> B -> C -> A -> B -> C), making it more effective against sophisticated scraping bots.
• Internal Refactoring: The core FingerprintEngine has been refactored for better encapsulation. Internal functions are now exposed correcly, improving code clarity and maintainability.

Release 0.0.6

Description of the requestPatternScore feature

The getRequestPatternScore function is a behavioral detection mechanism that assigns a suspicion score by analyzing the sequence and frequency of HTTP requests originating from a single device. Its goal is to identify non-human behaviors—such as automated scraping or brute-force attacks—characterized by rapid, repetitive request patterns.

The score is calculated based on several indicators, each with a configurable weight:

1. Velocity:

• Detection: Measures the time elapsed since the last request from the same device. If this time falls below a specific threshold (e.g., 200ms), it is considered too fast for normal human activity.
• Objective: To penalize scripts that send requests in rapid succession without pauses for user thought or interaction.

2. Burst:

• Detection: Identifies whether a request is identical (same path and parameters) to the previous one and occurred within a very short time interval (e.g., 500ms).
• Objective: To apply an additional penalty for identical repeated requests, which is a strong indicator of automated retries or "hammering" an endpoint.

3. Sequential Scraping:

• Detection: Detects requests targeting the same path (e.g., /api/products) but with different query parameters (e.g., ?page=1, ?page=2, etc.) within a short timeframe (e.g., 1000ms).

• Objective: To detect scraping bots that sequentially iterate through result pages or item IDs. A higher penalty is applied if the pattern repeats across multiple consecutive requests. Dynamic operation:

• History: The function maintains a history of recent requests (e.g., the last 10) for each device to provide context for analysis.

• Decay: The score is not static. It is recalculated with every request by applying a decay factor to the previous score before adding the score from the new request. This means that a user who returns to "normal" behavior will see their suspicion score gradually decrease.

• Inactivity Reset: If a device makes no requests for a set period (e.g., 30 seconds), its pattern score is completely reset. This prevents indefinitely penalizing a legitimate user who simply experienced a brief burst of activity.

• Self-adjustment: Time thresholds (speed, burst, scraping) and associated weights can be dynamically adjusted by the self-tuning module (startThresholdAutoTuning), which analyzes actual traffic to optimize detection and reduce false positives.

In summary, requestPatternScore is a dynamic, stateful defense mechanism that focuses not on what a request is, but on how it fits into a sequence of actions, offering effective protection against many types of bots.