@anonympins/fingerprint 0.7.0 → 0.7.2

package/src/php/FingerprintClient.php

@@ -1,149 +1,148 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Anonympins\Fingerprint;
-use Anonympins\Fingerprint\Config\SecurityProfiles;
-
-/**
- * FingerprintClient - Wrapper PHP pour la bibliothèque de fingerprinting côté client.
- *
- * Cette classe facilite l'intégration de la bibliothèque JavaScript `fingerprint.client.js`
- * dans une application PHP. Elle gère l'injection sécurisée du script et la création
- * de "honeypots" (pièges à bots) dans les formulaires.
- */
-class FingerprintClient
-{
-    /**
-     * @var string Le chemin vers le fichier de la bibliothèque client JavaScript.
-     */
-    private string $clientScriptPath;
-
-    /**
-     * @var array La configuration à passer à la fonction `initializeClient` de la bibliothèque JS.
-     */
-    private array $clientConfig;
-
-    /**
-     * @var string|null Un nonce cryptographique pour la Content Security Policy (CSP).
-     */
-    private ?string $nonce;
-
-    /**
-     * Constructeur de la classe.
-     *
-     * @param string $clientScriptPath Le chemin d'accès web au fichier `fingerprint.client.js`.
-     * @param array $clientConfig La configuration pour la bibliothèque client (souris, frappes, honeypots, etc.).
-     */
-    public function __construct(string $clientScriptPath, array $clientConfig = [])
-    {
-        $this->clientScriptPath = $clientScriptPath;
-
-        $defaultConfig = [
-            'mouse' => true,
-            'keystrokes' => true,
-            'clicks' => true,
-            'honeypots' => [],
-            'fetch' => [
-                'handleChallenges' => true,
-                'probationaryTtl' => 30000, // 30 seconds
-            ],
-            'wasm' => true, // Activer la tentative de chargement du module WASM
-            'wasmPath' => '/fp.js' // Chemin vers le script de chargement WASM
-        ];
-
-        // Utiliser une fusion profonde pour permettre de surcharger des sous-clés
-        $this->clientConfig = SecurityProfiles::deepMerge($defaultConfig, $clientConfig);
-
-        try {
-            // Génère un nonce pour CSP si possible, pour une sécurité renforcée.
-            $this->nonce = bin2hex(random_bytes(16));
-        } catch (\Exception $e) {
-            $this->nonce = null;
-        }
-    }
-
-    /**
-     * Génère un champ de formulaire "honeypot" caché.
-     * Les bots le rempliront, mais il sera invisible pour les humains.
-     *
-     * @param string $fieldName Le nom du champ (doit correspondre à la configuration client).
-     * @return string Le code HTML du champ honeypot.
-     */
-    public function generateHoneypotField(string $fieldName): string
-    {
-        // Ajoute le champ à la configuration pour que le script client le surveille.
-        if (!in_array($fieldName, $this->clientConfig['honeypots'])) {
-            $this->clientConfig['honeypots'][] = $fieldName;
-        }
-
-        // Styles CSS polymorphiques pour cacher le champ de manière robuste.
-        $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;',
-            'display:none; visibility:hidden; pointer-events:none;'
-        ];
-        $styles = $styleOptions[array_rand($styleOptions)];
-
-        $containerTags = ['div', 'span', 'p', 'section'];
-        $tag = $containerTags[array_rand($containerTags)];
-
-        $nestingType = rand(0, 1);
-        if ($nestingType === 1) {
-            return '<' . $tag . ' style="' . $styles . '" aria-hidden="true">'
-                . '<label for="' . htmlspecialchars($fieldName) . '">' . htmlspecialchars($fieldName) 
-                . '<input type="text" id="' . htmlspecialchars($fieldName) . '" name="' . htmlspecialchars($fieldName) . '" tabindex="-1" autocomplete="off">'
-                . '</label>'
-                . '</' . $tag . '>';
-        }
-
-        return '<' . $tag . ' style="' . $styles . '" aria-hidden="true">'
-            . '<label for="' . htmlspecialchars($fieldName) . '">' . htmlspecialchars($fieldName) . '</label>'
-            . '<input type="text" id="' . htmlspecialchars($fieldName) . '" name="' . htmlspecialchars($fieldName) . '" tabindex="-1" autocomplete="off">'
-            . '</' . $tag . '>';
-    }
-
-    /**
-     * Génère le bloc de script complet à inclure dans une page HTML.
-     *
-     * @return string Le code HTML des balises <script>.
-     */
-    public function getScriptTag(): string
-    {
-        $configJson = json_encode($this->clientConfig);
-        $nonceAttr = $this->nonce ? ' nonce="' . $this->nonce . '"' : '';
-
-        // Le script d'initialisation qui sera inclus dans la page.
-        $initScript = <<<JS
-document.addEventListener('DOMContentLoaded', function() {
-    const config = {$configJson};
-    if (window.ClientLibrary) {
-        if (config.wasmPath) {
-            const wasmScript = document.createElement('script');
-            wasmScript.src = config.wasmPath;
-            wasmScript.async = true;
-            wasmScript.nonce = '{$this->nonce}';
-            document.head.appendChild(wasmScript);
-        }
-
-        window.ClientLibrary.initializeClient(config);
-    } else {
-        console.error('Fingerprint client library not loaded.');
-    }
-});
-JS;
-
-        // On combine le chargement de la bibliothèque et le script d'initialisation.
-        return '<script src="' . htmlspecialchars($this->clientScriptPath) . '"' . $nonceAttr . '></script>'
-            . '<script' . $nonceAttr . '>' . $initScript . '</script>';
-    }
-
-    /**
-     * Retourne le nonce généré pour pouvoir l'utiliser dans les en-têtes CSP.
-     * @return string|null
-     */
-    public function getNonce(): ?string
-    {
-        return $this->nonce;
-    }
+<?php
+
+declare(strict_types=1);
+
+namespace Anonympins\Fingerprint;
+use Anonympins\Fingerprint\Config\SecurityProfiles;
+
+/**
+ * FingerprintClient - PHP wrapper for the client-side fingerprinting library.
+ *
+ * Handles script injection and generation of polymorphic honeypot fields
+ * inside HTML forms.
+ */
+class FingerprintClient
+{
+    /**
+     * @var string Path to client script asset.
+     */
+    private string $clientScriptPath;
+
+    /**
+     * @var array Configuration payload passed to `initializeClient`.
+     */
+    private array $clientConfig;
+
+    /**
+     * @var string|null Cryptographic nonce for Content Security Policy (CSP).
+     */
+    private ?string $nonce;
+
+    /**
+     * Constructor.
+     *
+     * @param string $clientScriptPath Web-accessible path to `fingerprint.client.js`.
+     * @param array $clientConfig Client initialization options.
+     */
+    public function __construct(string $clientScriptPath, array $clientConfig = [])
+    {
+        $this->clientScriptPath = $clientScriptPath;
+
+        $defaultConfig = [
+            'mouse' => true,
+            'keystrokes' => true,
+            'clicks' => true,
+            'honeypots' => [],
+            'fetch' => [
+                'handleChallenges' => true,
+                'probationaryTtl' => 30000, // 30 seconds
+            ],
+            'wasm' => true, // Attempt to load WASM module
+            'wasmPath' => '/fp.js' // Path to WASM loader script
+        ];
+
+        // Deep merge configuration overrides
+        $this->clientConfig = SecurityProfiles::deepMerge($defaultConfig, $clientConfig);
+
+        try {
+            // Generate CSP nonce when possible
+            $this->nonce = bin2hex(random_bytes(16));
+        } catch (\Exception $e) {
+            $this->nonce = null;
+        }
+    }
+
+    /**
+     * Generates a hidden honeypot form field.
+     * Traps automated bots while remaining invisible to human users.
+     *
+     * @param string $fieldName Field name (must match client honeypot registration).
+     * @return string Generated HTML markup.
+     */
+    public function generateHoneypotField(string $fieldName): string
+    {
+        // Register field in client configuration for monitoring
+        if (!in_array($fieldName, $this->clientConfig['honeypots'])) {
+            $this->clientConfig['honeypots'][] = $fieldName;
+        }
+
+        // Polymorphic CSS styling to robustly obscure honeypots
+        $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;',
+            'display:none; visibility:hidden; pointer-events:none;'
+        ];
+        $styles = $styleOptions[array_rand($styleOptions)];
+
+        $containerTags = ['div', 'span', 'p', 'section'];
+        $tag = $containerTags[array_rand($containerTags)];
+
+        $nestingType = rand(0, 1);
+        if ($nestingType === 1) {
+            return '<' . $tag . ' style="' . $styles . '" aria-hidden="true">'
+                . '<label for="' . htmlspecialchars($fieldName) . '">' . htmlspecialchars($fieldName) 
+                . '<input type="text" id="' . htmlspecialchars($fieldName) . '" name="' . htmlspecialchars($fieldName) . '" tabindex="-1" autocomplete="off">'
+                . '</label>'
+                . '</' . $tag . '>';
+        }
+
+        return '<' . $tag . ' style="' . $styles . '" aria-hidden="true">'
+            . '<label for="' . htmlspecialchars($fieldName) . '">' . htmlspecialchars($fieldName) . '</label>'
+            . '<input type="text" id="' . htmlspecialchars($fieldName) . '" name="' . htmlspecialchars($fieldName) . '" tabindex="-1" autocomplete="off">'
+            . '</' . $tag . '>';
+    }
+
+    /**
+     * Generates HTML script tags to embed the client library on a page.
+     *
+     * @return string HTML <script> markup.
+     */
+    public function getScriptTag(): string
+    {
+        $configJson = json_encode($this->clientConfig);
+        $nonceAttr = $this->nonce ? ' nonce="' . $this->nonce . '"' : '';
+
+        // Inline initialization script embedded in HTML
+        $initScript = <<<JS
+document.addEventListener('DOMContentLoaded', function() {
+    const config = {$configJson};
+    if (window.ClientLibrary) {
+        if (config.wasmPath) {
+            const wasmScript = document.createElement('script');
+            wasmScript.src = config.wasmPath;
+            wasmScript.async = true;
+            wasmScript.nonce = '{$this->nonce}';
+            document.head.appendChild(wasmScript);
+        }
+
+        window.ClientLibrary.initializeClient(config);
+    } else {
+        console.error('Fingerprint client library not loaded.');
+    }
+});
+JS;
+
+        // Combine library loader script and inline initialization
+        return '<script src="' . htmlspecialchars($this->clientScriptPath) . '"' . $nonceAttr . '></script>'
+            . '<script' . $nonceAttr . '>' . $initScript . '</script>';
+    }
+
+    /**
+     * Returns the generated CSP nonce.
+     * @return string|null
+     */
+    public function getNonce(): ?string
+    {
+        return $this->nonce;
+    }
 }

package/src/php/FingerprintEngine.php

@@ -179,6 +179,12 @@
                  }
              }
          }
+
+         // Si aucune liste blanche n'est explicitement fournie, appliquer la liste par défaut.
+         if (!isset($securityConfig['whitelist'])) {
+             $securityConfig['whitelist'] = self::default_whitelist();
+         }
+
          $this->securityConfig = $securityConfig;
          $this->verbose = $securityConfig['verbose'] ?? false;
          $this->allowlist = $this->buildAllowlist();
@@ -229,7 +235,8 @@
              'autotuning', 'enableUsefulWork', 'usefulWorkConfigPath', 'challengeNewDevices', 'graphql_operation_allowlist', 'dryRun',
              'similarityThreshold', 'summary', 'description',
              'ed25519_private_key', 'ed25519_public_key',
-             'wasm', 'enableProofOfSpace', 'pospace', 'federatedPeers', 'federationSecret', 'reset'
+             'wasm', 'enableProofOfSpace', 'pospace', 'federatedPeers', 'federationSecret', 'reset',
+             'filterWhitelist'
          ];
 
          if (empty($config['weights'])) {
@@ -550,10 +557,8 @@
 
              $deviceId = bin2hex(random_bytes(16)); // UUID-like
 
-             $isHttps = (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] !== 'off') ||
-                 (isset($_SERVER['SERVER_PORT']) && $_SERVER['SERVER_PORT'] == 443) ||
-                 ($context->getHeader('x-forwarded-proto') === 'https');
-             $secureOption = $isHttps || $this->isProduction;
+             $isHttps = !empty($context->isHttps);
+             $secureOption = $isHttps;
 
              // Préparer le cookie à envoyer
              $newCookie = [
@@ -562,7 +567,6 @@
                  'options' => [
                      'httponly' => true,
                      'secure' => $secureOption,
-                     'partitioned' => $secureOption,
                      'samesite' => 'Strict',
                      'path' => '/',
                  ]
@@ -745,7 +749,7 @@
          $botnetCluster = RequestUtils::getBotnetClusterScore($context, $stableFpHash);
 
          // NOUVEAU: Score de réputation du sous-réseau IP
-         $subnetScore = RequestUtils::getSubnetScore($context, $deviceId);
+         $subnetScore = RequestUtils::getSubnetScore($context, $deviceId, $this->securityConfig);
 
          // Score d'anomalie de pile TCP/IP
          $tcpAnomaly = RequestUtils::getTcpAnomalyScore($context);
@@ -985,13 +989,36 @@
                      // Le fingerprint est cohérent, on peut valider la solution
                      if ($powType === 'cpu_target' || $powType === 'cpu_mem') {
                          $cpuSolution = $context->query['pow_solution_cpu'] ?? $context->query['pow_solution'] ?? null;
-                         if ($cpuSolution) {
-                             $ticket = ChallengeUtils::verifyCpuTargetPoWAndGenerateTicket($context->clientIp, 3600000, $powNonce, $cpuSolution, $challengeContext);
+                         if ($cpuSolution !== null && $cpuSolution !== '') {
+                             $identity = $this->resolveRequestIdentity($context, $suspicionVector);
+                             $deviceId = (string)($identity['deviceId'] ?? '');
+                             $currentDeviceHash = (string)($identity['currentDeviceHash'] ?? RequestUtils::getCompositeDeviceHash($context));
+
+                             $ticket = ChallengeUtils::verifyCpuTargetPoWAndGenerateTicket(
+                                 $context->clientIp,
+                                 3600000,
+                                 $powNonce,
+                                 (string)$cpuSolution,
+                                 $challengeContext,
+                                 $deviceId,
+                                 $currentDeviceHash
+                             );
                              $isValid = $ticket !== null;
  
                              if ($powType === 'cpu_mem') {
-                                 $memSolution = $context->query['pow_solution_mem'] ?? null;
-                                 $isMemValid = $memSolution ? ChallengeUtils::verifyMemoryPoW($powNonce, $memSolution, $challengeContext['memDifficulty'] ?? 0, $challengeContext['clientSecret'] ?? '') : false;
+                                 if (!empty($challengeContext['isHttp'])) {
+                                     $isMemValid = true;
+                                 } else {
+                                     $memSolution = $context->query['pow_solution_mem'] ?? null;
+                                     $isMemValid = ($memSolution !== null && $memSolution !== '')
+                                         ? ChallengeUtils::verifyMemoryPoW(
+                                             $powNonce,
+                                             (string)$memSolution,
+                                             $challengeContext['memDifficulty'] ?? 0,
+                                             $challengeContext['clientSecret'] ?? ''
+                                         )
+                                         : false;
+                                 }
                                  $isValid = $isValid && $isMemValid;
                              }
                          }
@@ -1073,10 +1100,8 @@
                      MetricsManager::incrementCounter('challenges_solved_total');
                      $this->log('Challenge solution valid - issuing ticket', ['ticketMaxAge' => $ticketTtl]);
 
-                     $isHttps = (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] !== 'off') ||
-                         (isset($_SERVER['SERVER_PORT']) && $_SERVER['SERVER_PORT'] == 443) ||
-                         ($context->getHeader('x-forwarded-proto') === 'https');
-                     $secureOption = $isHttps || $this->isProduction;
+                     $isHttps = !empty($context->isHttps);
+                     $secureOption = $isHttps;
 
                      return [
                          'action' => 'redirect',
@@ -1092,7 +1117,6 @@
                                  'samesite' => 'Strict',
                                  'expires' => time() + ($ticketTtl / 1000),
                                  'path' => '/',
-                                 'partitioned' => $secureOption,
                              ]
                          ]
                      ];
@@ -1399,6 +1423,7 @@
                  $tlsSessionId = $context->tlsSessionId ?? '';
                  $baseBlock = ChallengeUtils::createCpuChallengeBaseBlock($nonce, $clientSecret, $originalFingerprint, $context->clientIp, $tlsSessionId);
 
+                 $isHttps = !empty($context->isHttps);
                  $challengeContext = [
                      'clientSecret' => $clientSecret,
                      'cpuTarget' => $cpuChallengeDetails['target'],
@@ -1407,6 +1432,7 @@
                      'memDifficulty' => $memDifficulty,
                      'baseBlock' => $baseBlock,
                      'originalPath' => $context->path,
+                     'isHttp' => !$isHttps,
                  ];
 
                  $store->set("secret:{$nonce}", $challengeContext, $this->securityConfig['challengeTtl'] ?? 300);
@@ -1441,7 +1467,8 @@
                      // Pour les navigateurs, retourner une page HTML
                      $pageBody = ChallengeUtils::generateCombinedPoWChallengePage(
                          $cpuChallengeDetails, $memDifficulty, $clientSecret,
-                         $this->securityConfig, $trapUrls, $originalFingerprint
+                         $this->securityConfig, $trapUrls, $originalFingerprint,
+                         $context->clientIp, $tlsSessionId, $baseBlock, $isHttps
                      );
                      $decision['body'] = $pageBody;
                  }

package/src/php/Ja3AnomalyDetector.php

@@ -5,17 +5,17 @@ declare(strict_types=1);
 namespace Anonympins\Fingerprint;
 
 /**
- * Classe de détection d'anomalies et d'usurpation TLS (JA3) en PHP.
+ * TLS (JA3) fingerprint anomaly and spoofing detector in PHP.
  */
 class Ja3AnomalyDetector
 {
-    // Liste décimale des valeurs GREASE (RFC 8701) utilisées par les moteurs Chromium/Safari récents
+    // Decimal GREASE values (RFC 8701) used by Chromium and Safari TLS stacks
     private const GREASE_VALUES = [
         2570, 6682, 10794, 14906, 19018, 23130, 27242, 31354,
         35466, 39578, 43690, 47802, 51914, 55926, 60038, 64150
     ];
 
-    // Base de données locale de signatures JA3 MD5 connues pour la corroboration de base
+    // Known JA3 MD5 signatures for baseline cross-layer verification
     private const TLS_FINGERPRINT_DB = [
         'e188a442b87f422c5a1e80b05399435b' => ['Chrome'],
         'd8e35855049321c6042a4325c697858f' => ['Chrome'],
@@ -29,7 +29,7 @@ class Ja3AnomalyDetector
         'b633f21d532d35967c8753c38536b4d3' => ['Safari'],
         '4d7a28d5f55b359b69100a311013f03e' => ['Safari', 'Chrome', 'Firefox'],
         '8dd3d7532873575314df23c447543001' => ['Safari', 'Chrome', 'Firefox'],
-        // Bibliothèques et scrapers automatisés connus
+        // Automated scraper and library fingerprints
         '47344a349b75c4e82333475553b5f358' => ['Python'],
         'b29587b8a143c42546133ad7704b3310' => ['Go'],
         'd435b5223b2884c5a832b842637e245f' => ['Java'],
@@ -37,8 +37,8 @@ class Ja3AnomalyDetector
     ];
 
     /**
-     * Analyse une chaîne JA3 brute non hachée.
-     * Format attendu : "TLSVersion,Ciphers,Extensions,EllipticCurves,EllipticCurveFormats"
+     * Parses a raw JA3 string.
+     * Expected format: "TLSVersion,Ciphers,Extensions,EllipticCurves,EllipticCurveFormats"
      */
     public static function parseJa3(string $ja3String): ?array
     {
@@ -61,7 +61,7 @@ class Ja3AnomalyDetector
     }
 
     /**
-     * Vérifie si un tableau contient au moins une valeur GREASE.
+     * Checks if a collection contains any GREASE value.
      */
     public static function hasGrease(array $values): bool
     {
@@ -74,7 +74,7 @@ class Ja3AnomalyDetector
     }
 
     /**
-     * Parse sommairement le User-Agent pour en extraire la famille de navigateur.
+     * Extracts browser family from User-Agent string.
      */
     public static function getBrowserFamily(string $userAgent): ?string
     {
@@ -95,14 +95,14 @@ class Ja3AnomalyDetector
     }
 
     /**
-     * Calcule le score global d'anomalie et d'usurpation JA3.
+     * Evaluates comprehensive JA3 spoofing and anomaly suspicion score.
      * 
-     * @param string|null $ja3Hash L'empreinte MD5 du JA3 (32 caractères)
-     * @param string|null $ja3Raw L'empreinte brute non hachée (si disponible)
-     * @param string $userAgent Le User-Agent de la requête
-     * @param string $httpVersion La version HTTP de la requête (ex: "HTTP/2", "HTTP/1.1", ou "2.0")
-     * @param object|null $cacheInstance Un driver de cache (ex: instance Redis) supportant get() et set() pour la détection de stagnation
-     * @return int Un score de suspicion compris entre 0 et 100
+     * @param string|null $ja3Hash MD5 hash of JA3 fingerprint (32 hex characters).
+     * @param string|null $ja3Raw Raw unhashed JA3 string if available.
+     * @param string $userAgent Request User-Agent header.
+     * @param string $httpVersion HTTP protocol version string.
+     * @param object|null $cacheInstance Cache store for multi-UA stagnation detection.
+     * @return int Suspicion score between 0 and 100.
      */
     public static function getJa3AnomalyScore(
         ?string $ja3Hash,
@@ -115,18 +115,18 @@ class Ja3AnomalyDetector
         $claimedBrowser = self::getBrowserFamily($userAgent);
         $isHumanBrowser = in_array($claimedBrowser, ['Chrome', 'Firefox', 'Safari', 'Edge'], true);
 
-        // --- ANALYSE 1 : CONTRÔLE SUR LE MD5 DU JA3 ---
+        // --- ANALYSIS 1: MD5 JA3 HASH VERIFICATION ---
         if ($ja3Hash && strlen($ja3Hash) === 32) {
             if (isset(self::TLS_FINGERPRINT_DB[$ja3Hash])) {
                 $expectedBrowsers = self::TLS_FINGERPRINT_DB[$ja3Hash];
 
-                // Cas A : L'empreinte correspond à un outil de scraping mais le UA prétend être humain
+                // Case A: TLS matches known automated library but UA claims standard browser
                 $isLibrary = array_intersect($expectedBrowsers, ['Python', 'Go', 'Java', 'curl']);
                 if (!empty($isLibrary) && $isHumanBrowser) {
-                    $score = max($score, 90); // Suspicion maximale : usurpation évidente
+                    $score = max($score, 90); // High confidence spoofing
                 }
                 
-                // Cas B : Incohérence directe entre le UA prétendu et la stack TLS correspondante
+                // Case B: Direct discrepancy between claimed browser and expected TLS stack
                 if ($claimedBrowser !== null) {
                     $matched = false;
                     foreach ($expectedBrowsers as $expected) {
@@ -136,12 +136,12 @@ class Ja3AnomalyDetector
                         }
                     }
                     if (!$matched) {
-                        $score = max($score, 80); // Le navigateur déclaré ne correspond pas au client TLS utilisé
+                        $score = max($score, 80); // Browser family mismatch
                     }
                 }
             }
 
-            // Cas C : Tracking de stagnation multi-UA (Stateful)
+            // Case C: Stateful multi-UA stagnation detection
             if ($cacheInstance && $claimedBrowser !== null && method_exists($cacheInstance, 'get') && method_exists($cacheInstance, 'set')) {
                 $cacheKey = "ja3-browsers:" . $ja3Hash;
                 
@@ -154,7 +154,7 @@ class Ja3AnomalyDetector
 
                     if (!in_array($claimedBrowser, $seenBrowsers, true)) {
                         $seenBrowsers[] = $claimedBrowser;
-                        // Cache pendant 24 heures (86400 secondes)
+                        // Cache for 24 hours (86400 seconds)
                         if (method_exists($cacheInstance, 'setex')) {
                             $cacheInstance->setex($cacheKey, 86400, json_encode($seenBrowsers));
                         } else {
@@ -162,32 +162,32 @@ class Ja3AnomalyDetector
                         }
                     }
 
-                    // Si une seule stack TLS génère des requêtes avec différents navigateurs, c'est un bot en rotation de UA
+                    // Multiple rotating browser UAs emitted from identical TLS stack
                     if (count($seenBrowsers) > 1) {
                         $score = max($score, 85);
                     }
                 } catch (\Throwable $e) {
-                    // Tolérance aux pannes du cache
+                    // Fault-tolerant fallback on cache error
                 }
             }
         }
 
-        // --- ANALYSE 2 : CONTRÔLE PROFOND SUR L'EMPREINTE BRUTE (RAW JA3) ---
+        // --- ANALYSIS 2: DEEP INSPECTION ON RAW JA3 STRING ---
         if ($ja3Raw) {
             $parsed = self::parseJa3($ja3Raw);
             if ($parsed) {
-                // Contrôle A : Mécanisme GREASE pour Chrome / Edge (obligatoire)
+                // Check A: GREASE presence for Chrome / Edge
                 if ($claimedBrowser === 'Chrome' || $claimedBrowser === 'Edge') {
                     $hasCiphersGrease = self::hasGrease($parsed['ciphers']);
                     $hasExtensionsGrease = self::hasGrease($parsed['extensions']);
                     
                     if (!$hasCiphersGrease && !$hasExtensionsGrease) {
-                        // Chrome ou Edge moderne sans GREASE = spoofing de bas niveau (ex: python-requests déguisé)
+                        // Modern Chromium missing GREASE indicates spoofing
                         $score = max($score, 75);
                     }
                 }
 
-                // Contrôle B : HTTP/2 ou HTTP/3 sans négociation ALPN (Extension 16)
+                // Check B: HTTP/2 or HTTP/3 without ALPN extension (Extension 16)
                 $isH2OrHigher = (
                     strpos($httpVersion, '2.0') !== false || 
                     strpos($httpVersion, 'HTTP/2') !== false || 
@@ -196,11 +196,11 @@ class Ja3AnomalyDetector
                 $hasAlpnExtension = in_array(16, $parsed['extensions'], true);
                 
                 if ($isH2OrHigher && !$hasAlpnExtension) {
-                    // Négociation HTTP/2 active au niveau serveur mais absente au niveau des extensions TLS du client
+                    // HTTP/2 active at server level but missing from client ALPN extension
                     $score = max($score, 70);
                 }
 
-                // Contrôle C : Version TLS obsolète négociée par un navigateur moderne (ex: TLS < 1.2, id < 771)
+                // Check C: Deprecated TLS version negotiated by claimed modern browser
                 if ($isHumanBrowser && $parsed['tlsVersion'] < 771) {
                     $score = max($score, 80);
                 }
@@ -211,8 +211,9 @@ class Ja3AnomalyDetector
     }
 
     /**
-     * Feature 7 : Corrélation RTT & Latence de Proxy Résidentiel
-     * Calcule un score d'anomalie en corrélant le RTT TCP de bas niveau avec la latence applicative.
+     * Correlates low-level TCP RTT with application layer latency to detect residential proxy hops.
+     * @param RequestContext $context
+     * @return int Suspicion score
      */
     public static function getRttProxyScore(RequestContext $context): int
     {