@anonympins/fingerprint 0.7.4 → 0.8.0

package/src/php/Config/SecurityProfiles.php

@@ -5,8 +5,8 @@ declare(strict_types=1);
 namespace Anonympins\Fingerprint\Config;
 
 /**
- * Définit les profils de sécurité prédéfinis pour la bibliothèque Fingerprint.
- * Ces profils contiennent les poids des scores de suspicion et les seuils de déclenchement.
+ * Defines predefined security profiles for the Fingerprint library.
+ * These profiles contain suspicion score weights and trigger thresholds.
  */
 class SecurityProfiles
 {
@@ -33,18 +33,21 @@ class SecurityProfiles
                 'crossLayerInconsistencyScore' => 0.4,
                 'timeInconsistencyScore' => 0.9,
                 'tlsSpoofingScore' => 0.8,
-                'botScore' => 1.0, // Poids pour le score de bot explicite
-                'cookieDroppingScore' => 0.9, // Pénalité élevée pour la suppression de cookies
-                'threatIntelScore' => 0.4, // Poids pour le renseignement sur les menaces (ex: IP de proxy connu)
-                'clientHintsInconsistencyScore' => 0.7, // Penalizes inconsistency between User-Agent and Client-Hints
-                'clickVarianceScore' => 0.6, // Poids pour la variance des clics
-                'subnetScore' => 0.5, // Pénalise les sous-réseaux IP avec une activité suspecte agrégée
-                'botnetClusterScore' => 0.6, // NOUVEAU: Poids pour le clustering botnet
+                'botScore' => 1.0,
+                'cookieDroppingScore' => 0.4,
+                'threatIntelScore' => 0.4,
+                'clientHintsInconsistencyScore' => 0.7,
+                'clickVarianceScore' => 0.6,
+                'subnetScore' => 0.5,
+                'ipReputationScore' => 0.5,
+                'botnetClusterScore' => 0.6,
                 'tcpAnomalyScore' => 0.8,
-                'protocolAnomalyScore' => 0.8, // NEW: Anomalie de protocole (HTTP/2 et QUIC)
-                'renderingAnomalyScore' => 0.8, // NEW: Anomalie de rendu
-                'ipReputationScore' => 0.5, // NOUVEAU: Poids pour la réputation IP
+                'protocolAnomalyScore' => 0.8,
+                'http2AnomalyScore' => 0.8,
+                'quicAnomalyScore' => 0.8,
+                'renderingAnomalyScore' => 0.8,
                 'virtualizationScore' => 0.8,
+                'mtuAnomalyScore' => 0.9,
             ],
             'thresholds' => ['low' => 20, 'medium' => 45, 'high' => 75, 'block' => 95],
             'patterns' => [
@@ -63,7 +66,7 @@ class SecurityProfiles
                 'minDifficultyBits' => 8,
                 'maxDifficultyBits' => 22,
             ],
-        'filterWhitelist' => 85.0, // Stratégie d'inspection modérée pour les IP/chemins en liste blanche
+        'filterWhitelist' => 85.0, // Moderate inspection strategy for allowlisted IPs/paths
         'wasm' => true,
         ],
 
@@ -88,16 +91,20 @@ class SecurityProfiles
                 'timeInconsistencyScore' => 1.0,
                 'tlsSpoofingScore' => 1.0,
                 'botScore' => 1.0,
-                'cookieDroppingScore' => 1.0, // Pénalité maximale
-                'threatIntelScore' => 0.7, // Poids élevé pour les menaces connues (Tor, etc.)
-                'clientHintsInconsistencyScore' => 0.9, // Very high penalty in strict mode
-                'clickVarianceScore' => 0.7, // High weight for click variance
-                'subnetScore' => 0.7, // Poids plus élevé en mode strict
-                'botnetClusterScore' => 0.8, // NOUVEAU: Poids pour le clustering botnet
-                'tcpAnomalyScore' => 1.0, // NEW: Anomalie de pile TCP/IP
-                'protocolAnomalyScore' => 1.0, // NEW: Anomalie de protocole (HTTP/2 et QUIC)
-                'renderingAnomalyScore' => 1.0, // NEW: Anomalie de rendu
-
+                'cookieDroppingScore' => 0.6,
+                'threatIntelScore' => 0.7,
+                'clientHintsInconsistencyScore' => 0.9,
+                'clickVarianceScore' => 0.7,
+                'subnetScore' => 0.7,
+                'ipReputationScore' => 0.7,
+                'botnetClusterScore' => 0.8,
+                'tcpAnomalyScore' => 1.0,
+                'protocolAnomalyScore' => 1.0,
+                'http2AnomalyScore' => 1.0,
+                'quicAnomalyScore' => 1.0,
+                'renderingAnomalyScore' => 1.0,
+                'virtualizationScore' => 1.0,
+                'mtuAnomalyScore' => 0.9,
             ],
             'thresholds' => ['low' => 10, 'medium' => 35, 'high' => 65, 'block' => 90],
             'patterns' => [
@@ -118,7 +125,7 @@ class SecurityProfiles
             ],
             'challengeNewDevices' => true, // Challenge all new devices
         'wasm' => true,
-        'filterWhitelist' => true, // Tout comportement d'attaque certain bypass immédiatement la liste blanche
+        'filterWhitelist' => true, // Any definite attack behavior immediately bypasses the allowlist
         ],
 
         /**
@@ -141,15 +148,20 @@ class SecurityProfiles
                 'timeInconsistencyScore' => 0.8,
                 'tlsSpoofingScore' => 0.7,
                 'botScore' => 0.5,
-                'cookieDroppingScore' => 0.8, // Important pour les clients API qui doivent maintenir un état
+                'cookieDroppingScore' => 0.5, // Important for API clients that need to maintain state
                 'threatIntelScore' => 0.5, // APIs are often targeted by malicious IPs
                 'clientHintsInconsistencyScore' => 0.6, // Relevant signal for APIs
                 'clickVarianceScore' => 0.3, // Low weight as not applicable to APIs
-                'subnetScore' => 0.8, // Très important pour les API pour détecter les botnets
-                'botnetClusterScore' => 0.7, // NOUVEAU: Poids pour le clustering botnet
-                'tcpAnomalyScore' => 0.8, // NEW: Anomalie de pile TCP/IP
-                'protocolAnomalyScore' => 0.8, // NEW: Anomalie de protocole (HTTP/2 et QUIC)
-
+                'subnetScore' => 0.8, // Highly important for APIs to detect botnets
+                'ipReputationScore' => 0.6,
+                'botnetClusterScore' => 0.7,
+                'tcpAnomalyScore' => 0.8,
+                'protocolAnomalyScore' => 0.8,
+                'http2AnomalyScore' => 0.8,
+                'quicAnomalyScore' => 0.8,
+                'renderingAnomalyScore' => 0.2,
+                'virtualizationScore' => 0.5,
+                'mtuAnomalyScore' => 0.9,
             ],
             'thresholds' => ['low' => 25, 'medium' => 50, 'high' => 80, 'block' => 95],
             'patterns' => [
@@ -170,7 +182,7 @@ class SecurityProfiles
             ],
             // This would be a callable in PHP, but for now, we represent its intent.
             'isApiRequest' => 'req.path.startsWith("/api/") || req.headers.accept?.includes("application/json")',
-        'filterWhitelist' => 75.0, // Seuil bas pour parer au vol de clés/tokens API légitimes
+        'filterWhitelist' => 75.0, // Low threshold to defend against stolen legitimate API keys/tokens
         'wasm' => true,
         ],
 
@@ -193,19 +205,22 @@ class SecurityProfiles
                 'honeypotScore' => 1.0, // Crucial for comment spam
                 'crossLayerInconsistencyScore' => 0.4,
                 'timeInconsistencyScore' => 0.8,
-                'tlsSpoofingScore' => 0.6, // Moins critique pour les blogs
+                'tlsSpoofingScore' => 0.6,
                 'botScore' => 0.8,
-                'cookieDroppingScore' => 0.7, // Moins critique, mais toujours un signal
-                'threatIntelScore' => 0.3, // Lower priority for a blog
+                'cookieDroppingScore' => 0.3,
+                'threatIntelScore' => 0.3,
                 'clientHintsInconsistencyScore' => 0.5,
-                'clickVarianceScore' => 0.5, // Moderate weight for click variance
-                'subnetScore' => 0.4, // Utile contre le spam de commentaires coordonné
-                'ipReputationScore' => 0.3, // NOUVEAU: Poids pour la réputation IP
-                'botnetClusterScore' => 0.5, // NOUVEAU: Poids pour le clustering botnet
-                'tcpAnomalyScore' => 0.5, // NEW: Anomalie de pile TCP/IP
-                'protocolAnomalyScore' => 0.5, // NEW: Anomalie de protocole (HTTP/2 et QUIC)
-                'renderingAnomalyScore' => 0.5, // NEW: Anomalie de rendu
-
+                'clickVarianceScore' => 0.5,
+                'subnetScore' => 0.4,
+                'ipReputationScore' => 0.3,
+                'botnetClusterScore' => 0.5,
+                'tcpAnomalyScore' => 0.5,
+                'protocolAnomalyScore' => 0.5,
+                'http2AnomalyScore' => 0.5,
+                'quicAnomalyScore' => 0.5,
+                'renderingAnomalyScore' => 0.5,
+                'virtualizationScore' => 0.6,
+                'mtuAnomalyScore' => 0.9,
             ],
             'thresholds' => ['low' => 25, 'medium' => 55, 'high' => 80, 'block' => 95],
             'patterns' => [
@@ -224,7 +239,7 @@ class SecurityProfiles
                 'minDifficultyBits' => 8,
                 'maxDifficultyBits' => 20,
             ],
-        'filterWhitelist' => 90.0, // Très tolérant, n'inspecte que si le score est presque au blocage
+        'filterWhitelist' => 90.0, // Highly lenient, only inspects if the score is near blocking
         'wasm' => true,
         ],
 
@@ -241,25 +256,28 @@ class SecurityProfiles
                 'historyScore' => 0.4,
                 'rotationScore' => 0.6,
                 'headerAnomalyScore' => 0.2,
+                'requestPatternScore' => 0.9,
                 'inconsistencyScore' => 1.0, // Crucial for preventing account takeover
                 'behaviorScore' => 0.8, // Important for checkout/login forms
                 'honeypotScore' => 1.0,
                 'crossLayerInconsistencyScore' => 0.7,
-                // NOUVEAU: Ajout des scores manquants pour une configuration complète
-                'requestPatternScore' => 0.9, // Poids unifié pour les patterns, remplace les scores scindés
                 'timeInconsistencyScore' => 0.9,
                 'tlsSpoofingScore' => 0.9,
                 'botScore' => 1.0,
-                'cookieDroppingScore' => 1.0, // Crucial pour la détection de bots e-commerce
+                'cookieDroppingScore' => 0.6, // Crucial for e-commerce bot detection
                 'threatIntelScore' => 0.8, // Very important for e-commerce (scalping proxies)
                 'clientHintsInconsistencyScore' => 0.9, // Very important for e-commerce
                 'clickVarianceScore' => 0.8, // Very high weight for click variance
-                'subnetScore' => 0.9, // Crucial contre les attaques de scalping distribuées
-                'botnetClusterScore' => 0.9, // NOUVEAU: Poids pour le clustering botnet
-                'tcpAnomalyScore' => 0.9, // NEW: Anomalie de pile TCP/IP
-                'protocolAnomalyScore' => 0.9, // NEW: Anomalie de protocole (HTTP/2 et QUIC)
-                'renderingAnomalyScore' => 0.9, // NEW: Anomalie de rendu
-
+                'subnetScore' => 0.9, // Crucial against distributed scalping attacks
+                'ipReputationScore' => 0.8,
+                'botnetClusterScore' => 0.9,
+                'tcpAnomalyScore' => 0.9,
+                'protocolAnomalyScore' => 0.9,
+                'http2AnomalyScore' => 0.9,
+                'quicAnomalyScore' => 0.9,
+                'renderingAnomalyScore' => 0.9,
+                'virtualizationScore' => 0.9,
+                'mtuAnomalyScore' => 0.9,
             ],
             'thresholds' => ['low' => 15, 'medium' => 40, 'high' => 70, 'block' => 90],
             'patterns' => [
@@ -282,16 +300,16 @@ class SecurityProfiles
             // This would be a callable in PHP, but for now, we represent its intent.
             'isApiRequest' => 'req.path.startsWith("/api/cart") || req.path.startsWith("/api/stock") || req.path.startsWith("/api/checkout")',
         'wasm' => true,
-        'filterWhitelist' => true, // Tolérance zéro pour le scraping / scalping distribué
+        'filterWhitelist' => true, // Zero tolerance for scraping / distributed scalping
         ],
     ];
 
     /**
-     * Crée une configuration de sécurité basée sur un profil nommé, avec des surcharges optionnelles.
+     * Creates a security configuration based on a named profile, with optional overrides.
      *
-     * @param string $profileName Le nom du profil à utiliser ('balanced', 'strict', 'api', etc.).
-     * @param array<string, mixed> $overrides Un tableau pour fusionner profondément avec le profil, permettant la personnalisation.
-     * @return array<string, mixed> L'objet de configuration de sécurité final.
+     * @param string $profileName The profile name to use ('balanced', 'strict', 'api', etc.).
+     * @param array<string, mixed> $overrides An array to deep-merge with the profile, allowing customization.
+     * @return array<string, mixed> The final security configuration object.
      */
     public static function createSecurityProfile(string $profileName = 'balanced', array $overrides = []): array
     {
@@ -300,11 +318,11 @@ class SecurityProfiles
     }
 
     /**
-     * Fusionne profondément deux tableaux. Les propriétés du tableau `$source` écrasent celles du tableau `$target`.
+     * Deep-merges two arrays. Properties of the `$source` array overwrite those of `$target`.
      *
-     * @param array<string, mixed> $target Le tableau cible.
-     * @param array<string, mixed> $source Le tableau source.
-     * @return array<string, mixed> Le tableau fusionné.
+     * @param array<string, mixed> $target The target array.
+     * @param array<string, mixed> $source The source array.
+     * @return array<string, mixed> The merged array.
      */
     public static function deepMerge(array $target, array $source): array
     {

package/src/php/DirectFingerprint.php

@@ -25,15 +25,10 @@ class DirectFingerprint
     }
 
     /**
-     * Protects the current entry point.
-     * Analyzes the incoming request and issues challenges or block responses, exiting the script if necessary.
-     * If the request is allowed, returns the fingerprint data.
-     *
-     * @return array{score: float, vector: array}|null Fingerprint data if allowed, null otherwise.
+     * Builds request context from PHP superglobals.
      */
-    public function protect(): ?array
+    public function buildRequestContext(): RequestContext
     {
-        // 1. Build request context from PHP superglobals
         // phpcs:ignore WordPress.Security.NonceVerification.Missing,WordPress.Security.NonceVerification.Recommended -- Direct WAF inspection firewall before WP core logic
         $body = $_POST ?: json_decode(file_get_contents('php://input'), true);
         $headers = function_exists('getallheaders') ? getallheaders() : [];
@@ -44,7 +39,7 @@ class DirectFingerprint
         $path = function_exists('wp_parse_url') ? (string)wp_parse_url($rawUri, PHP_URL_PATH) : (string)parse_url($rawUri, PHP_URL_PATH);
         $serverProtocol = isset($_SERVER['SERVER_PROTOCOL']) ? sanitize_text_field(wp_unslash($_SERVER['SERVER_PROTOCOL'])) : '1.1';
 
-        $context = new RequestContext(
+        return new RequestContext(
             $remoteAddr,
             !empty($path) ? $path : '/',
             $headers,
@@ -54,10 +49,62 @@ class DirectFingerprint
             $_COOKIE,
             $serverProtocol
         );
+    }
+
+    /**
+     * Inspects the incoming request without terminating execution or issuing redirects/exits.
+     *
+     * @param RequestContext|null $context
+     * @return array
+     */
+    public function inspect(?RequestContext $context = null): array
+    {
+        $context = $context ?? $this->buildRequestContext();
+        $decision = $this->engine->processRequest($context);
+
+        return [
+            'action'         => $decision['action'] ?? 'next',
+            'intendedAction' => $decision['intendedAction'] ?? null,
+            'score'          => (float)($decision['score'] ?? 0.0),
+            'suspicionScore' => (float)($decision['score'] ?? 0.0),
+            'vector'         => $decision['vector'] ?? [],
+            'status'         => $decision['status'] ?? 200,
+            'body'           => $decision['body'] ?? null,
+            'context'        => $context,
+        ];
+    }
+
+    /**
+     * Alias for inspect().
+     *
+     * @param RequestContext|null $context
+     * @return array
+     */
+    public function evaluate(?RequestContext $context = null): array
+    {
+        return $this->inspect($context);
+    }
+
+    /**
+     * Protects the current entry point.
+     * Analyzes the incoming request and issues challenges or block responses, exiting the script if necessary.
+     * If the request is allowed, returns the fingerprint data.
+     *
+     * @return array{score: float, vector: array}|null Fingerprint data if allowed, null otherwise.
+     */
+    public function protect(): ?array
+    {
+        // 1. Build request context from PHP superglobals
+        $context = $this->buildRequestContext();
 
         // 2. Process request with engine
         $decision = $this->engine->processRequest($context);
 
+        // 3. Callback hook before acting on decision (allows logging, telemetry, SSE recording)
+        if (isset($this->securityConfig['onDecision']) && is_callable($this->securityConfig['onDecision'])) {
+            call_user_func($this->securityConfig['onDecision'], $decision, $context);
+        }
+
         // 3. Act on decision
         if (isset($context->newCookieForResponse)) {
             $cookie = $context->newCookieForResponse;

package/src/php/FingerprintBuilder.php

@@ -5,7 +5,7 @@ declare(strict_types=1);
 namespace Anonympins\Fingerprint;
 
 /**
- * Class to build a composite fingerprint (Multi-Hash).
+ * Builds a composite fingerprint (Multi-Hash).
  * Output format: "grp1:hash1|grp2:hash2|grp3:hash3"
  */
 class FingerprintBuilder
@@ -17,7 +17,7 @@ class FingerprintBuilder
 
     /**
      * Adds a component to the fingerprint.
-     *
+     * 
      * @param string $group Group name (e.g. 'hw', 'screen', 'geo').
      * @param string|int|bool|null $value Raw value to hash.
      * @return self
@@ -27,14 +27,14 @@ class FingerprintBuilder
         if ($value === null || $value === '') {
             return $this;
         }
-        // Hash the value individually
+        // Hash the value individually to anonymize and normalize its length.
         $this->components[$group] = self::cyrb53((string)$value);
         return $this;
     }
 
     /**
      * Adds a raw component without hashing it.
-     * Useful for metrics that need to be read as-is on the server.
+     * Useful for metrics that need to be read as-is on the server side.
      *
      * @param string $group Group name.
      * @param string|int|null $value Raw value.
@@ -51,13 +51,13 @@ class FingerprintBuilder
 
     /**
      * Generates the final fingerprint string.
-     * Components are sorted by key to guarantee deterministic ordering.
+     * Components are sorted by key to ensure deterministic ordering.
      *
      * @return string
      */
     public function __toString(): string
     {
-        // Sort array by key
+        // Sort array by key.
         ksort($this->components);
 
         $parts = [];
@@ -70,7 +70,7 @@ class FingerprintBuilder
 
     /**
      * Compares two fingerprints and returns a similarity score (0 to 1).
-     * Uses weights to emphasize strong invariants (Canvas, GPU, JA3).
+     * Uses weights to emphasize strong invariants (e.g., Canvas, GPU, JA3).
      *
      * @param string|null $fpString1 Fingerprint A.
      * @param string|null $fpString2 Fingerprint B.
@@ -137,7 +137,7 @@ class FingerprintBuilder
 
     /**
      * cyrb53 hashing algorithm (fast and low collision rate).
-     * Ported from the JavaScript version.
+     * This is a direct port of the JavaScript version.
      *
      * @param string $str String to hash.
      * @param int $seed Optional seed.
@@ -157,8 +157,8 @@ class FingerprintBuilder
         $h1 = self::imul($h1 ^ ($h1 >> 16), 2246822507) ^ self::imul($h2 ^ ($h2 >> 13), 3266489909);
         $h2 = self::imul($h2 ^ ($h2 >> 16), 2246822507) ^ self::imul($h1 ^ ($h1 >> 13), 3266489909);
 
-        // On 64-bit platforms, PHP handles 64-bit signed ints natively.
-        // Use native shifts instead of bcmath for better performance.
+        // On 64-bit platforms, PHP handles 64-bit signed integers natively.
+        // Use native shifts instead of bcmath for improved performance.
         if (PHP_INT_SIZE === 8) {
             $h1_u = $h1 & 0xffffffff;
             $h2_u = $h2 & 0xffffffff;
@@ -166,7 +166,7 @@ class FingerprintBuilder
             return (string)$val_h2;
         }
 
-        // Fallback to bcmath on 32-bit platforms
+        // Fallback to bcmath on 32-bit platforms.
         $val_h2 = bcadd(bcmul((string)(2097151 & $h2), '4294967296'), (string)($h1 >= 0 ? $h1 : $h1 + 4294967296));
         return $val_h2;
     }
@@ -180,8 +180,8 @@ class FingerprintBuilder
      */
     private static function imul(int $a, int $b): int
     {
-        // Emulation of JavaScript's Math.imul for signed 32-bit integer multiplication.
-        // This version correctly handles overflows on 64-bit systems.
+        // Emulates JavaScript's Math.imul for signed 32-bit integer multiplication.
+        // This implementation correctly handles overflows on 64-bit systems.
         $ah = ($a >> 16) & 0xffff;
         $al = $a & 0xffff;
         $bh = ($b >> 16) & 0xffff;

package/src/php/FingerprintClient.php

@@ -6,8 +6,8 @@ namespace Anonympins\Fingerprint;
 use Anonympins\Fingerprint\Config\SecurityProfiles;
 
 /**
- * FingerprintClient - PHP wrapper for the client-side fingerprinting library.
- *
+ * PHP wrapper for the client-side fingerprinting library.
+ * 
  * Handles script injection and generation of polymorphic honeypot fields
  * inside HTML forms.
  */
@@ -64,7 +64,7 @@ class FingerprintClient
 
     /**
      * Generates a hidden honeypot form field.
-     * Traps automated bots while remaining invisible to human users.
+     * Traps automated bots while remaining invisible to human users and screen readers.
      *
      * @param string $fieldName Field name (must match client honeypot registration).
      * @return string Generated HTML markup.
@@ -76,7 +76,7 @@ class FingerprintClient
             $this->clientConfig['honeypots'][] = $fieldName;
         }
 
-        // Polymorphic CSS styling to robustly obscure honeypots
+        // Polymorphic CSS styling to robustly obscure honeypot fields
         $styleOptions = [
             'position:absolute; left:-9999px; top:-9999px; transform:scale(0); opacity:0; pointer-events:none;',
             'position:fixed; left:-8888px; top:-8888px; width:0; height:0; overflow:hidden; opacity:0; pointer-events:none;',
@@ -112,7 +112,7 @@ class FingerprintClient
         $configJson = json_encode($this->clientConfig);
         $nonceAttr = $this->nonce ? ' nonce="' . $this->nonce . '"' : '';
 
-        // Inline initialization script embedded in HTML
+        // Inline initialization script to be embedded in HTML
         $initScript = "document.addEventListener('DOMContentLoaded', function() {\n"
             . "    const config = " . $configJson . ";\n"
             . "    if (window.ClientLibrary) {\n"
@@ -129,7 +129,7 @@ class FingerprintClient
             . "    }\n"
             . "});";
 
-        // Combine library loader script and inline initialization
+        // Combine the main library loader script and the inline initialization script
         // phpcs:ignore WordPress.WP.EnqueuedResources.NonEnqueuedScript -- Polymorphic dynamic client script tag generation
         return '<script src="' . htmlspecialchars($this->clientScriptPath) . '"' . $nonceAttr . '></script>'
             . '<script' . $nonceAttr . '>' . $initScript . '</script>';