@anonympins/fingerprint 0.6.7 → 0.7.1

package/src/php/Ja3AnomalyDetector.php

@@ -1,228 +1,259 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Anonympins\Fingerprint;
-
-/**
- * Classe de détection d'anomalies et d'usurpation TLS (JA3) en PHP.
- */
-class Ja3AnomalyDetector
-{
-    // Liste décimale des valeurs GREASE (RFC 8701) utilisées par les moteurs Chromium/Safari récents
-    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
-    private const TLS_FINGERPRINT_DB = [
-        'e188a442b87f422c5a1e80b05399435b' => ['Chrome'],
-        'd8e35855049321c6042a4325c697858f' => ['Chrome'],
-        'a9f90958d44533748c139a5d1895b925' => ['Chrome'],
-        '3b5379916d2b3882253c42885956a350' => ['Chrome'],
-        '59822058c95c33d2d06e52f410855c8c' => ['Chrome'],
-        'b386946a5a586163c7c533636b45c355' => ['Firefox'],
-        '66236495a523c1785f8f3a105b248b11' => ['Firefox'],
-        'b73d470006575b5e35167a0b5a8540e2' => ['Firefox'],
-        '8443d7562933834333943465d52363cf' => ['Firefox'],
-        'b633f21d532d35967c8753c38536b4d3' => ['Safari'],
-        '4d7a28d5f55b359b69100a311013f03e' => ['Safari', 'Chrome', 'Firefox'],
-        '8dd3d7532873575314df23c447543001' => ['Safari', 'Chrome', 'Firefox'],
-        // Bibliothèques et scrapers automatisés connus
-        '47344a349b75c4e82333475553b5f358' => ['Python'],
-        'b29587b8a143c42546133ad7704b3310' => ['Go'],
-        'd435b5223b2884c5a832b842637e245f' => ['Java'],
-        'c72366b9551263d990b7fa574225332c' => ['curl'],
-    ];
-
-    /**
-     * Analyse une chaîne JA3 brute non hachée.
-     * Format attendu : "TLSVersion,Ciphers,Extensions,EllipticCurves,EllipticCurveFormats"
-     */
-    public static function parseJa3(string $ja3String): ?array
-    {
-        if (empty($ja3String)) {
-            return null;
-        }
-
-        $parts = explode(',', $ja3String);
-        if (count($parts) !== 5) {
-            return null;
-        }
-
-        return [
-            'tlsVersion' => (int)$parts[0],
-            'ciphers'    => $parts[1] !== '' ? array_map('intval', explode('-', $parts[1])) : [],
-            'extensions' => $parts[2] !== '' ? array_map('intval', explode('-', $parts[2])) : [],
-            'curves'     => $parts[3] !== '' ? array_map('intval', explode('-', $parts[3])) : [],
-            'points'     => $parts[4] !== '' ? array_map('intval', explode('-', $parts[4])) : []
-        ];
-    }
-
-    /**
-     * Vérifie si un tableau contient au moins une valeur GREASE.
-     */
-    public static function hasGrease(array $values): bool
-    {
-        foreach ($values as $val) {
-            if (in_array($val, self::GREASE_VALUES, true)) {
-                return true;
-            }
-        }
-        return false;
-    }
-
-    /**
-     * Parse sommairement le User-Agent pour en extraire la famille de navigateur.
-     */
-    public static function getBrowserFamily(string $userAgent): ?string
-    {
-        $ua = strtolower($userAgent);
-        if (strpos($ua, 'edg') !== false) {
-            return 'Edge';
-        }
-        if (strpos($ua, 'chrome') !== false) {
-            return 'Chrome';
-        }
-        if (strpos($ua, 'firefox') !== false) {
-            return 'Firefox';
-        }
-        if (strpos($ua, 'safari') !== false) {
-            return 'Safari';
-        }
-        return null;
-    }
-
-    /**
-     * Calcule le score global d'anomalie et d'usurpation JA3.
-     * 
-     * @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
-     */
-    public static function getJa3AnomalyScore(
-        ?string $ja3Hash,
-        ?string $ja3Raw,
-        string $userAgent,
-        string $httpVersion,
-        ?object $cacheInstance = null
-    ): int {
-        $score = 0;
-        $claimedBrowser = self::getBrowserFamily($userAgent);
-        $isHumanBrowser = in_array($claimedBrowser, ['Chrome', 'Firefox', 'Safari', 'Edge'], true);
-
-        // --- ANALYSE 1 : CONTRÔLE SUR LE MD5 DU JA3 ---
-        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
-                $isLibrary = array_intersect($expectedBrowsers, ['Python', 'Go', 'Java', 'curl']);
-                if (!empty($isLibrary) && $isHumanBrowser) {
-                    $score = max($score, 90); // Suspicion maximale : usurpation évidente
-                }
-                
-                // Cas B : Incohérence directe entre le UA prétendu et la stack TLS correspondante
-                if ($claimedBrowser !== null) {
-                    $matched = false;
-                    foreach ($expectedBrowsers as $expected) {
-                        if (stripos($claimedBrowser, $expected) === 0) {
-                            $matched = true;
-                            break;
-                        }
-                    }
-                    if (!$matched) {
-                        $score = max($score, 80); // Le navigateur déclaré ne correspond pas au client TLS utilisé
-                    }
-                }
-            }
-
-            // Cas C : Tracking de stagnation multi-UA (Stateful)
-            if ($cacheInstance && $claimedBrowser !== null && method_exists($cacheInstance, 'get') && method_exists($cacheInstance, 'set')) {
-                $cacheKey = "ja3-browsers:" . $ja3Hash;
-                
-                try {
-                    $rawCached = $cacheInstance->get($cacheKey);
-                    $seenBrowsers = $rawCached ? json_decode((string)$rawCached, true) : [];
-                    if (!is_array($seenBrowsers)) {
-                        $seenBrowsers = [];
-                    }
-
-                    if (!in_array($claimedBrowser, $seenBrowsers, true)) {
-                        $seenBrowsers[] = $claimedBrowser;
-                        // Cache pendant 24 heures (86400 secondes)
-                        if (method_exists($cacheInstance, 'setex')) {
-                            $cacheInstance->setex($cacheKey, 86400, json_encode($seenBrowsers));
-                        } else {
-                            $cacheInstance->set($cacheKey, json_encode($seenBrowsers), 86400);
-                        }
-                    }
-
-                    // Si une seule stack TLS génère des requêtes avec différents navigateurs, c'est un bot en rotation de UA
-                    if (count($seenBrowsers) > 1) {
-                        $score = max($score, 85);
-                    }
-                } catch (\Throwable $e) {
-                    // Tolérance aux pannes du cache
-                }
-            }
-        }
-
-        // --- ANALYSE 2 : CONTRÔLE PROFOND SUR L'EMPREINTE BRUTE (RAW JA3) ---
-        if ($ja3Raw) {
-            $parsed = self::parseJa3($ja3Raw);
-            if ($parsed) {
-                // Contrôle A : Mécanisme GREASE pour Chrome / Edge (obligatoire)
-                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é)
-                        $score = max($score, 75);
-                    }
-                }
-
-                // Contrôle B : HTTP/2 ou HTTP/3 sans négociation ALPN (Extension 16)
-                $isH2OrHigher = (
-                    strpos($httpVersion, '2.0') !== false || 
-                    strpos($httpVersion, 'HTTP/2') !== false || 
-                    strpos($httpVersion, 'HTTP/3') !== false
-                );
-                $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
-                    $score = max($score, 70);
-                }
-
-                // Contrôle C : Version TLS obsolète négociée par un navigateur moderne (ex: TLS < 1.2, id < 771)
-                if ($isHumanBrowser && $parsed['tlsVersion'] < 771) {
-                    $score = max($score, 80);
-                }
-            }
-        }
-
-        return $score;
-    }
-}
-
-// --- EXEMPLE D'UTILISATION PRATIQUE ---
-/*
-$userAgent = $_SERVER['HTTP_USER_AGENT'] ?? '';
-$httpVersion = $_SERVER['SERVER_PROTOCOL'] ?? '';
-
-// Récupération des en-têtes injectés par votre Reverse-Proxy (Nginx, HAProxy, etc.)
-$ja3Hash = $_SERVER['HTTP_X_JA3_HASH'] ?? null;
-$ja3Raw  = $_SERVER['HTTP_X_JA3_RAW'] ?? null; 
-
-// Redis facultatif pour la détection stateful de rotation UA
-$redis = new \Redis();
-$redis->connect('127.0.0.1', 6379);
-
-$suspicionScore = Ja3AnomalyDetector::getJa3AnomalyScore($ja3Hash, $ja3Raw, $userAgent, $httpVersion, $redis);
+<?php
+
+declare(strict_types=1);
+
+namespace Anonympins\Fingerprint;
+
+/**
+ * TLS (JA3) fingerprint anomaly and spoofing detector in PHP.
+ */
+class Ja3AnomalyDetector
+{
+    // 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
+    ];
+
+    // Known JA3 MD5 signatures for baseline cross-layer verification
+    private const TLS_FINGERPRINT_DB = [
+        'e188a442b87f422c5a1e80b05399435b' => ['Chrome'],
+        'd8e35855049321c6042a4325c697858f' => ['Chrome'],
+        'a9f90958d44533748c139a5d1895b925' => ['Chrome'],
+        '3b5379916d2b3882253c42885956a350' => ['Chrome'],
+        '59822058c95c33d2d06e52f410855c8c' => ['Chrome'],
+        'b386946a5a586163c7c533636b45c355' => ['Firefox'],
+        '66236495a523c1785f8f3a105b248b11' => ['Firefox'],
+        'b73d470006575b5e35167a0b5a8540e2' => ['Firefox'],
+        '8443d7562933834333943465d52363cf' => ['Firefox'],
+        'b633f21d532d35967c8753c38536b4d3' => ['Safari'],
+        '4d7a28d5f55b359b69100a311013f03e' => ['Safari', 'Chrome', 'Firefox'],
+        '8dd3d7532873575314df23c447543001' => ['Safari', 'Chrome', 'Firefox'],
+        // Automated scraper and library fingerprints
+        '47344a349b75c4e82333475553b5f358' => ['Python'],
+        'b29587b8a143c42546133ad7704b3310' => ['Go'],
+        'd435b5223b2884c5a832b842637e245f' => ['Java'],
+        'c72366b9551263d990b7fa574225332c' => ['curl'],
+    ];
+
+    /**
+     * Parses a raw JA3 string.
+     * Expected format: "TLSVersion,Ciphers,Extensions,EllipticCurves,EllipticCurveFormats"
+     */
+    public static function parseJa3(string $ja3String): ?array
+    {
+        if (empty($ja3String)) {
+            return null;
+        }
+
+        $parts = explode(',', $ja3String);
+        if (count($parts) !== 5) {
+            return null;
+        }
+
+        return [
+            'tlsVersion' => (int)$parts[0],
+            'ciphers'    => $parts[1] !== '' ? array_map('intval', explode('-', $parts[1])) : [],
+            'extensions' => $parts[2] !== '' ? array_map('intval', explode('-', $parts[2])) : [],
+            'curves'     => $parts[3] !== '' ? array_map('intval', explode('-', $parts[3])) : [],
+            'points'     => $parts[4] !== '' ? array_map('intval', explode('-', $parts[4])) : []
+        ];
+    }
+
+    /**
+     * Checks if a collection contains any GREASE value.
+     */
+    public static function hasGrease(array $values): bool
+    {
+        foreach ($values as $val) {
+            if (in_array($val, self::GREASE_VALUES, true)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Extracts browser family from User-Agent string.
+     */
+    public static function getBrowserFamily(string $userAgent): ?string
+    {
+        $ua = strtolower($userAgent);
+        if (strpos($ua, 'edg') !== false) {
+            return 'Edge';
+        }
+        if (strpos($ua, 'chrome') !== false) {
+            return 'Chrome';
+        }
+        if (strpos($ua, 'firefox') !== false) {
+            return 'Firefox';
+        }
+        if (strpos($ua, 'safari') !== false) {
+            return 'Safari';
+        }
+        return null;
+    }
+
+    /**
+     * Evaluates comprehensive JA3 spoofing and anomaly suspicion score.
+     * 
+     * @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,
+        ?string $ja3Raw,
+        string $userAgent,
+        string $httpVersion,
+        ?object $cacheInstance = null
+    ): int {
+        $score = 0;
+        $claimedBrowser = self::getBrowserFamily($userAgent);
+        $isHumanBrowser = in_array($claimedBrowser, ['Chrome', 'Firefox', 'Safari', 'Edge'], true);
+
+        // --- ANALYSIS 1: MD5 JA3 HASH VERIFICATION ---
+        if ($ja3Hash && strlen($ja3Hash) === 32) {
+            if (isset(self::TLS_FINGERPRINT_DB[$ja3Hash])) {
+                $expectedBrowsers = self::TLS_FINGERPRINT_DB[$ja3Hash];
+
+                // 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); // High confidence spoofing
+                }
+                
+                // Case B: Direct discrepancy between claimed browser and expected TLS stack
+                if ($claimedBrowser !== null) {
+                    $matched = false;
+                    foreach ($expectedBrowsers as $expected) {
+                        if (stripos($claimedBrowser, $expected) === 0) {
+                            $matched = true;
+                            break;
+                        }
+                    }
+                    if (!$matched) {
+                        $score = max($score, 80); // Browser family mismatch
+                    }
+                }
+            }
+
+            // Case C: Stateful multi-UA stagnation detection
+            if ($cacheInstance && $claimedBrowser !== null && method_exists($cacheInstance, 'get') && method_exists($cacheInstance, 'set')) {
+                $cacheKey = "ja3-browsers:" . $ja3Hash;
+                
+                try {
+                    $rawCached = $cacheInstance->get($cacheKey);
+                    $seenBrowsers = $rawCached ? json_decode((string)$rawCached, true) : [];
+                    if (!is_array($seenBrowsers)) {
+                        $seenBrowsers = [];
+                    }
+
+                    if (!in_array($claimedBrowser, $seenBrowsers, true)) {
+                        $seenBrowsers[] = $claimedBrowser;
+                        // Cache for 24 hours (86400 seconds)
+                        if (method_exists($cacheInstance, 'setex')) {
+                            $cacheInstance->setex($cacheKey, 86400, json_encode($seenBrowsers));
+                        } else {
+                            $cacheInstance->set($cacheKey, json_encode($seenBrowsers), 86400);
+                        }
+                    }
+
+                    // Multiple rotating browser UAs emitted from identical TLS stack
+                    if (count($seenBrowsers) > 1) {
+                        $score = max($score, 85);
+                    }
+                } catch (\Throwable $e) {
+                    // Fault-tolerant fallback on cache error
+                }
+            }
+        }
+
+        // --- ANALYSIS 2: DEEP INSPECTION ON RAW JA3 STRING ---
+        if ($ja3Raw) {
+            $parsed = self::parseJa3($ja3Raw);
+            if ($parsed) {
+                // 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) {
+                        // Modern Chromium missing GREASE indicates spoofing
+                        $score = max($score, 75);
+                    }
+                }
+
+                // Check B: HTTP/2 or HTTP/3 without ALPN extension (Extension 16)
+                $isH2OrHigher = (
+                    strpos($httpVersion, '2.0') !== false || 
+                    strpos($httpVersion, 'HTTP/2') !== false || 
+                    strpos($httpVersion, 'HTTP/3') !== false
+                );
+                $hasAlpnExtension = in_array(16, $parsed['extensions'], true);
+                
+                if ($isH2OrHigher && !$hasAlpnExtension) {
+                    // HTTP/2 active at server level but missing from client ALPN extension
+                    $score = max($score, 70);
+                }
+
+                // Check C: Deprecated TLS version negotiated by claimed modern browser
+                if ($isHumanBrowser && $parsed['tlsVersion'] < 771) {
+                    $score = max($score, 80);
+                }
+            }
+        }
+
+        return $score;
+    }
+
+    /**
+     * 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
+    {
+        $tcpRttHeader = $context->headers['x-tcp-rtt'] ?? $context->headers['x-real-rtt'] ?? null;
+        $tcpRtt = $tcpRttHeader !== null ? (int)$tcpRttHeader : null;
+
+        $behaviorHeader = $context->headers['x-behavior-metrics'] ?? null;
+        if ($behaviorHeader) {
+            $metrics = json_decode($behaviorHeader, true);
+            if (json_last_error() === JSON_ERROR_NONE && isset($metrics['clientTimestamp'])) {
+                $clientTimestamp = (int)$metrics['clientTimestamp'];
+                $appLatency = $context->requestTimestamp - $clientTimestamp;
+                if ($tcpRtt !== null && $tcpRtt > 0) {
+                    $clientToProxyDelta = $appLatency - $tcpRtt;
+                    if ($tcpRtt < 35 && $clientToProxyDelta > 150) {
+                        return 85;
+                    }
+                } else {
+                    if ($appLatency > 350) {
+                        return 40;
+                    }
+                }
+            }
+        }
+        return 0;
+    }
+}
+
+// --- EXEMPLE D'UTILISATION PRATIQUE ---
+/*
+$userAgent = $_SERVER['HTTP_USER_AGENT'] ?? '';
+$httpVersion = $_SERVER['SERVER_PROTOCOL'] ?? '';
+
+// Récupération des en-têtes injectés par votre Reverse-Proxy (Nginx, HAProxy, etc.)
+$ja3Hash = $_SERVER['HTTP_X_JA3_HASH'] ?? null;
+$ja3Raw  = $_SERVER['HTTP_X_JA3_RAW'] ?? null; 
+
+// Redis facultatif pour la détection stateful de rotation UA
+$redis = new \Redis();
+$redis->connect('127.0.0.1', 6379);
+
+$suspicionScore = Ja3AnomalyDetector::getJa3AnomalyScore($ja3Hash, $ja3Raw, $userAgent, $httpVersion, $redis);
 */

package/src/php/Optimization/FunctionRegistry.php

@@ -5,7 +5,7 @@ declare(strict_types=1);
 namespace Anonympins\Fingerprint\Optimization;
 
 /**
- * Registre pour exposer de manière contrôlée les fonctions de la bibliothèque d'optimisation.
+ * Registry to safely expose optimization library routines to task runners.
  */
 class FunctionRegistry
 {
@@ -13,17 +13,17 @@ class FunctionRegistry
     private static array $functions = [];
 
     /**
-     * Initialise le registre avec les fonctions disponibles.
+     * Initializes registry with built-in solvers and evaluators.
      */
     private static function initialize(): void
     {
         if (empty(self::$functions)) {
-            // Fonctions de "Scoring"
+            // Evaluators & Scoring Adapters
             self::$functions['tsp.calculateEnergy'] = [OptimizationUtils::class, 'evaluatePathDistance'];
             self::$functions['portfolio.calculateMetrics'] = [OptimizationOperators::class, 'calculatePortfolioMetrics'];
             self::$functions['facility.calculateEnergy'] = [OptimizationOperators::class, 'evaluateFacilityLocation'];
 
-            // Fonctions de "Résolution"
+            // Full Optimization Solvers
             self::$functions['tsp.solve'] = [OptimizationOperators::class, 'solveTSP'];
             self::$functions['portfolio.solve'] = [OptimizationOperators::class, 'solvePortfolio'];
             self::$functions['fraud.solve'] = [OptimizationOperators::class, 'solveFraudDetection'];
@@ -33,7 +33,7 @@ class FunctionRegistry
     }
 
     /**
-     * Récupère une fonction depuis le registre.
+     * Retrieves a function from the registry.
      */
     public static function get(string $name): ?callable
     {
@@ -41,7 +41,7 @@ class FunctionRegistry
         return self::$functions[$name] ?? null;
     }
     /**
-     * Enregistre une nouvelle fonction. Principalement pour les tests.
+     * Registers a custom function. Primarily intended for testing.
      * @internal
      * @param string $name
      * @param callable $function
@@ -54,7 +54,7 @@ class FunctionRegistry
     }
 
     /**
-     * Réinitialise le registre. Uniquement pour les tests.
+     * Resets function registry. Intended for testing.
      * @internal
      */
     public static function __internal_resetRegistry(): void