@anonympins/fingerprint 0.7.4 → 0.8.0

package/src/php/Ja3AnomalyDetector.php

@@ -5,7 +5,7 @@ declare(strict_types=1);
 namespace Anonympins\Fingerprint;
 
 /**
- * TLS (JA3) fingerprint anomaly and spoofing detector in PHP.
+ * TLS (JA3) fingerprint anomaly and spoofing detector.
  */
 class Ja3AnomalyDetector
 {
@@ -38,7 +38,7 @@ class Ja3AnomalyDetector
 
     /**
      * Parses a raw JA3 string.
-     * Expected format: "TLSVersion,Ciphers,Extensions,EllipticCurves,EllipticCurveFormats"
+     * Format: "TLSVersion,Ciphers,Extensions,EllipticCurves,EllipticCurveFormats"
      */
     public static function parseJa3(string $ja3String): ?array
     {
@@ -74,7 +74,7 @@ class Ja3AnomalyDetector
     }
 
     /**
-     * Extracts browser family from User-Agent string.
+     * Extracts the browser family from a User-Agent string.
      */
     public static function getBrowserFamily(string $userAgent): ?string
     {
@@ -95,13 +95,13 @@ class Ja3AnomalyDetector
     }
 
     /**
-     * Evaluates comprehensive JA3 spoofing and anomaly suspicion score.
+     * Evaluates the 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.
+     * @param object|null $cacheInstance A cache store for multi-UA stagnation detection.
      * @return int Suspicion score between 0 and 100.
      */
     public static function getJa3AnomalyScore(
@@ -120,13 +120,13 @@ class Ja3AnomalyDetector
             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
+                // Case A: TLS matches a known automated library, but the UA claims to be a 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
+                // Case B: Direct discrepancy between the claimed browser and the expected TLS stack.
                 if ($claimedBrowser !== null) {
                     $matched = false;
                     foreach ($expectedBrowsers as $expected) {
@@ -141,7 +141,7 @@ class Ja3AnomalyDetector
                 }
             }
 
-            // Case C: Stateful multi-UA stagnation detection
+            // Case C: Stateful multi-UA stagnation detection.
             if ($cacheInstance && $claimedBrowser !== null && method_exists($cacheInstance, 'get') && method_exists($cacheInstance, 'set')) {
                 $cacheKey = "ja3-browsers:" . $ja3Hash;
                 
@@ -162,7 +162,7 @@ class Ja3AnomalyDetector
                         }
                     }
 
-                    // Multiple rotating browser UAs emitted from identical TLS stack
+                    // Multiple rotating browser UAs are being emitted from an identical TLS stack.
                     if (count($seenBrowsers) > 1) {
                         $score = max($score, 85);
                     }
@@ -172,22 +172,22 @@ class Ja3AnomalyDetector
             }
         }
 
-        // --- ANALYSIS 2: DEEP INSPECTION ON RAW JA3 STRING ---
+        // --- ANALYSIS 2: DEEP INSPECTION OF THE RAW JA3 STRING ---
         if ($ja3Raw) {
             $parsed = self::parseJa3($ja3Raw);
             if ($parsed) {
-                // Check A: GREASE presence for Chrome / Edge
+                // 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
+                        // Modern Chromium missing GREASE indicates spoofing.
                         $score = max($score, 75);
                     }
                 }
 
-                // Check B: HTTP/2 or HTTP/3 without ALPN extension (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) {
-                    // HTTP/2 active at server level but missing from client ALPN extension
+                    // HTTP/2 is active at the server level but missing from the client's ALPN extension.
                     $score = max($score, 70);
                 }
 
-                // Check C: Deprecated TLS version negotiated by claimed modern browser
+                // Check C: A deprecated TLS version was negotiated by a claimed modern browser.
                 if ($isHumanBrowser && $parsed['tlsVersion'] < 771) {
                     $score = max($score, 80);
                 }
@@ -212,7 +212,7 @@ class Ja3AnomalyDetector
 
     /**
      * Correlates low-level TCP RTT with application layer latency to detect residential proxy hops.
-     * Evaluates continuous physical transit discrepancies rather than arbitrary step numbers.
+     * Evaluates continuous physical transit discrepancies rather than arbitrary step numbers. 
      * 
      * @param RequestContext $context
      * @return float Suspicion score between 0.0 and 95.0
@@ -229,14 +229,14 @@ class Ja3AnomalyDetector
                 $clientTimestamp = (int)$metrics['clientTimestamp'];
                 $appLatency = $context->requestTimestamp - $clientTimestamp;
 
-                if ($tcpRtt !== null && $tcpRtt > 0 && $appLatency > 0) {
-                    // Marge de tolérance défensive contre le jitter réseau et le scheduling JS / Garbage Collection
+                if ($tcpRtt !== null && $tcpRtt > 0 && $appLatency > 0) { // @phpstan-ignore-line
+                    // Defensive tolerance margin against network jitter and JS scheduling/Garbage Collection.
                     $jitterAllowance = 60.0;
                     $effectiveRtt = max((float)$tcpRtt, 5.0);
                     $tunnelDelta = $appLatency - ($tcpRtt + $jitterAllowance);
                     $divergenceRatio = $appLatency / $effectiveRtt;
 
-                    // Condition de disjonction : liaison edge ultra-proche (< 40ms) + transit applicatif au moins 3x supérieur
+                    // Disjunction condition: ultra-close edge link (< 40ms) + application transit at least 3x higher.
                     if ($tcpRtt <= 40 && $divergenceRatio >= 3.0 && $tunnelDelta > 0) {
                         $scaling = 120.0;
                         $ratioWeight = min(1.0, ($divergenceRatio - 3.0) / 5.0);
@@ -250,16 +250,16 @@ class Ja3AnomalyDetector
     }
 }
 
-// --- EXEMPLE D'UTILISATION PRATIQUE ---
+// --- PRACTICAL USAGE EXAMPLE ---
 /*
 $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.)
+// Retrieve headers injected by your 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
+// Optional Redis for stateful UA rotation detection
 $redis = new \Redis();
 $redis->connect('127.0.0.1', 6379);
 

package/src/php/Optimization/FunctionRegistry.php

@@ -5,7 +5,7 @@ declare(strict_types=1);
 namespace Anonympins\Fingerprint\Optimization;
 
 /**
- * Registry to safely expose optimization library routines to task runners.
+ * A registry to safely expose optimization library routines to task runners.
  */
 class FunctionRegistry
 {
@@ -42,7 +42,7 @@ class FunctionRegistry
     }
     /**
      * Registers a custom function. Primarily intended for testing.
-     * @internal
+     * @internal For testing purposes only.
      * @param string $name
      * @param callable $function
      * @return void
@@ -54,8 +54,8 @@ class FunctionRegistry
     }
 
     /**
-     * Resets function registry. Intended for testing.
-     * @internal
+     * Resets the function registry. Intended for testing.
+     * @internal For testing purposes only.
      */
     public static function __internal_resetRegistry(): void
     {

package/src/php/Optimization/Optimization.php

@@ -5,7 +5,7 @@ declare(strict_types=1);
 namespace Anonympins\Fingerprint\Optimization;
 
 /**
- * Optimization algorithms library.
+ * A library of optimization algorithms.
  */
 class Optimization
 {
@@ -17,7 +17,7 @@ class Optimization
         try {
             return random_int(0, PHP_INT_MAX - 1) / PHP_INT_MAX;
         } catch (\Exception $e) {
-            if (function_exists('wp_rand')) {
+            if (function_exists('wp_rand')) { // WordPress fallback
                 return (float)wp_rand(0, 1000000) / 1000000.0;
             }
             // phpcs:ignore WordPress.WP.AlternativeFunctions.rand_mt_rand -- Standalone fallback
@@ -133,7 +133,7 @@ class Optimization
     }
 
     /**
-     * Sorts population into non-dominated Pareto fronts (NSGA-II).
+     * Sorts a population into non-dominated Pareto fronts (NSGA-II).
      * @param array<int, array> &$populationWithObjectives
      * @return array<int, array>
      */
@@ -186,7 +186,7 @@ class Optimization
     }
 
     /**
-     * Computes crowding distance for a front to preserve diversity.
+     * Computes the crowding distance for a front to preserve diversity.
      * @param array<int, array> &$front
      */
     private static function calculateCrowdingDistance(array &$front): void
@@ -207,7 +207,7 @@ class Optimization
             $minObj = $front[0]['objectives'][$i];
             $maxObj = $front[$l - 1]['objectives'][$i];
 
-            // Boundary solutions receive infinite distance to encourage spread
+            // Boundary solutions receive infinite distance to encourage population spread.
             $front[0]['crowdingDistance'] = INF;
             $front[$l - 1]['crowdingDistance'] = INF;
 
@@ -222,7 +222,7 @@ class Optimization
     }
 
     /**
-     * Calculates deviation from Benford's Law distribution.
+     * Calculates the deviation from Benford's Law distribution.
      * Elevated values indicate synthetic or automated intervals.
      * @param array<int|float> $numbers
      */

package/src/php/RequestContext.php

@@ -5,10 +5,10 @@ declare(strict_types=1);
 namespace Anonympins\Fingerprint;
 
 /**
- * Représente le contexte d'une requête HTTP, fournissant un accès unifié
- * aux informations nécessaires pour l'analyse de l'empreinte.
- * Cette classe est conçue pour être créée à partir d'un objet de requête
- * standard (ex: PSR-7, Symfony, Laravel).
+ * Represents the context of an HTTP request, providing unified access
+ * to information required for fingerprint analysis.
+ * This class is designed to be instantiated from a standard request object
+ * (e.g., PSR-7, Symfony, Laravel).
  */
 class RequestContext
 {
@@ -40,7 +40,7 @@ class RequestContext
     /** @var ?array<string, float> */
     public ?array $preCalculatedVector = null;
 
-    // Propriétés spécifiques qui peuvent être fournies par un proxy inverse
+    // Specific properties that may be provided by a reverse proxy
     public ?string $ja3 = null;
     public ?string $ja4 = null;
     public ?string $ja4s = null;
@@ -48,7 +48,7 @@ class RequestContext
     public ?string $http2Fingerprint = null;
     public ?string $quicFingerprint = null;
     public ?string $tcpFingerprint = null;
-    public ?string $zkpY = null; // NOUVEAU: Clé publique ZKP du client
+    public ?string $zkpY = null; // Client ZKP public key
 
     /**
      * @param string $clientIp
@@ -73,7 +73,7 @@ class RequestContext
     ) {
         $this->clientIp = $clientIp;
         $this->path = $path;
-        // Normaliser les en-têtes en minuscules pour un accès cohérent
+        // Normalize headers to lowercase for consistent access
         $this->headers = array_change_key_case($headers, CASE_LOWER);
         $this->query = $query;
         $this->body = $body;
@@ -86,7 +86,7 @@ class RequestContext
             ($this->getHeader('x-forwarded-proto') === 'https')
         );
 
-        // Extraire les empreintes TLS/HTTP2/TCP si elles sont fournies par les en-têtes
+        // Extract TLS/HTTP2/TCP fingerprints if provided by headers
         $this->ja3 = $this->headers['x-ja3-hash'] ?? null;
         $this->ja4 = $this->headers['x-ja4-hash'] ?? null;
         $this->ja4s = $this->headers['x-ja4s-hash'] ?? null;
@@ -98,10 +98,10 @@ class RequestContext
         $this->tlsSessionId = $this->headers['x-tls-session-id'] ?? $this->headers['x-ssl-session-id'] ?? null;
     }
     /**
-     * Récupère la valeur d'un en-tête HTTP de manière insensible à la casse.
+     * Retrieves the value of an HTTP header in a case-insensitive manner.
      *
-     * @param string $name Le nom de l'en-tête.
-     * @return string|null La valeur de l'en-tête ou null si non trouvé.
+     * @param string $name Header name.
+     * @return string|null Header value or null if not found.
      */
 
     public function getHeader(string $name): ?string

package/src/php/Store/InMemoryStore.php

@@ -1,67 +1,97 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Anonympins\Fingerprint\Store;
-
-/**
- * In-memory implementation of the IStore interface.
- * Suitable for local development, tests, or single-instance deployments.
- */
-class InMemoryStore implements IStore
-{
-    /**
-     * @var array<string, array{value: mixed, expiresAt: int|null}>
-     */
-    private array $data = [];
-
-    public function get(string $key)
-    {
-        if (!isset($this->data[$key])) {
-            return null;
-        }
-
-        $item = $this->data[$key];
-        if ($item['expiresAt'] !== null && $item['expiresAt'] < time()) {
-            $this->delete($key); // Delete expired item
-            return null;
-        }
-
-        return $item['value'];
-    }
-
-    public function set(string $key, $value, ?int $ttl = null): void
-    {
-        $expiresAt = $ttl !== null ? time() + $ttl : null;
-
-        $this->data[$key] = ['value' => $value, 'expiresAt' => $expiresAt];
-    }
-
-    public function has(string $key): bool
-    {
-        if (!isset($this->data[$key])) {
-            return false;
-        }
-
-        $item = $this->data[$key];
-        if ($item['expiresAt'] !== null && $item['expiresAt'] < time()) {
-            $this->delete($key);
-            return false;
-        }
-
-        return true;
-    }
-
-    public function delete(string $key): void
-    {
-        unset($this->data[$key]);
-    }
-
-    /**
-     * Clears all data from the store. Useful for testing.
-     */
-    public function clear(): void
-    {
-        $this->data = [];
-    }
+<?php
+
+declare(strict_types=1);
+
+namespace Anonympins\Fingerprint\Store;
+
+/**
+ * In-memory implementation of the IStore interface.
+ * Suitable for local development, tests, or single-instance deployments.
+ */
+class InMemoryStore implements IStore
+{
+    /**
+     * @var array<string, array{value: mixed, expiresAt: int|null}>
+     */
+    private array $data = [];
+
+    /**
+     * Retrieves the value associated with the given key.
+     * If the stored item has expired, it is deleted and null is returned.
+     *
+     * @param string $key The key to look up.
+     * @return mixed The stored value, or null if the key is missing or expired.
+     */
+    public function get(string $key)
+    {
+        if (!isset($this->data[$key])) {
+            return null;
+        }
+
+        $item = $this->data[$key];
+        if ($item['expiresAt'] !== null && $item['expiresAt'] < time()) { // Active expiration check
+            $this->delete($key); // Delete expired item
+            return null;
+        }
+
+        return $item['value'];
+    }
+
+    /**
+     * Stores a value under the given key, with an optional TTL (in seconds).
+     * If `$ttl` is null, the item never expires.
+     *
+     * @param string $key The key to store the value under.
+     * @param mixed $value The value to store.
+     * @param int|null $ttl Optional time-to-live in seconds.
+     * @return void
+     */
+    public function set(string $key, $value, ?int $ttl = null): void
+    {
+        $expiresAt = $ttl !== null ? time() + $ttl : null;
+
+        $this->data[$key] = ['value' => $value, 'expiresAt' => $expiresAt];
+    }
+
+    /**
+     * Checks whether the given key exists and has not expired.
+     * Expired items are deleted on access.
+     *
+     * @param string $key The key to check.
+     * @return bool True if the key exists and is valid, false otherwise.
+     */
+    public function has(string $key): bool
+    {
+        if (!isset($this->data[$key])) {
+            return false;
+        }
+
+        $item = $this->data[$key];
+        if ($item['expiresAt'] !== null && $item['expiresAt'] < time()) {
+            $this->delete($key);
+            return false;
+        }
+
+        return true;
+    }
+
+    /**
+     * Deletes the value associated with the given key.
+     * Does nothing if the key does not exist.
+     *
+     * @param string $key The key to delete.
+     * @return void
+     */
+    public function delete(string $key): void
+    {
+        unset($this->data[$key]);
+    }
+
+    /**
+     * Clears all data from the store. Useful for test isolation.
+     */
+    public function clear(): void
+    {
+        $this->data = [];
+    }
 }

package/src/php/Store/MongoDbStore.php

@@ -69,7 +69,7 @@ class MongoDbStore implements IStore
                 return null;
             }
 
-            // Active TTL check to bypass MongoDB daemon 60-second cleanup latency
+            // Active TTL check to bypass MongoDB's 60-second TTL cleanup daemon latency.
             if (isset($doc['expiresAt'])) {
                 $expiresAt = $doc['expiresAt'];
                 if ($expiresAt instanceof \MongoDB\BSON\UTCDateTime) {
@@ -168,7 +168,7 @@ class MongoDbStore implements IStore
     }
 
     /**
-     * Automatically initializes required TTL index in MongoDB collection.
+     * Automatically initializes the required TTL index in the MongoDB collection.
      */
     public function init(): void
     {

package/src/php/Store/RedisStore.php

@@ -5,7 +5,7 @@ declare(strict_types=1);
 namespace Anonympins\Fingerprint\Store;
 
 /**
- * Redis storage adapter for the Fingerprint engine.
+ * A Redis storage adapter for the Fingerprint engine.
  * Compatible with phpredis and predis clients.
  */
 class RedisStore implements IStore

package/src/php/Store/StoreManager.php

@@ -1,36 +1,49 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Anonympins\Fingerprint\Store;
-
-/**
- * Manages the global store singleton instance.
- */
-class StoreManager
-{
-    private static ?IStore $store = null;
-
-    public static function getStore(): IStore
-    {
-        if (self::$store === null) {
-            self::$store = new InMemoryStore();
-        }
-        return self::$store;
-    }
-
-    public static function configureStore(IStore $externalStore): void
-    {
-        self::$store = $externalStore;
-    }
-
-    /**
-     * Sets the active store instance (useful for dependency injection and tests).
-     *
-     * @param mixed $store
-     */
-    public static function setStore($store): void
-    {
-        self::$store = $store;
-    }
+<?php
+
+declare(strict_types=1);
+
+namespace Anonympins\Fingerprint\Store;
+
+/**
+ * Manages the global store singleton instance for the application.
+ */
+class StoreManager
+{
+    private static ?IStore $store = null;
+
+    /**
+     * Returns the current global store instance.
+     * Lazily instantiates an InMemoryStore if no store has been configured yet.
+     *
+     * @return IStore The active store instance.
+     */
+    public static function getStore(): IStore
+    {
+        if (self::$store === null) {
+            self::$store = new InMemoryStore();
+        }
+        return self::$store;
+    }
+
+    /**
+     * Replaces the active store with an externally provided IStore implementation.
+     * Typically used at bootstrap to plug in a persistent store (Redis, database, etc.).
+     *
+     * @param IStore $externalStore The external store implementation to use.
+     * @return void
+     */
+    public static function configureStore(IStore $externalStore): void
+    {
+        self::$store = $externalStore;
+    }
+
+    /**
+     * Sets the active store instance. Useful for dependency injection and testing.
+     *
+     * @param mixed $store
+     */
+    public static function setStore($store): void
+    {
+        self::$store = $store;
+    }
 }

package/src/php/Tests/ChallengeUtilsTest.php

@@ -263,6 +263,37 @@ class ChallengeUtilsTest extends TestCase
         Env::clear('ED25519_PUBLIC_KEY');
     }
 
+    public function testGenerateIssuerPemKeys(): void
+    {
+        if (!extension_loaded('openssl') || !defined('OPENSSL_KEYTYPE_ED25519')) {
+            $this->markTestSkipped('OpenSSL Ed25519 is not supported in this environment.');
+        }
+
+        $pkey = @openssl_pkey_new(["private_key_type" => constant('OPENSSL_KEYTYPE_ED25519')]);
+        if (!$pkey || !@openssl_pkey_export($pkey, $testPem)) {
+            $this->markTestSkipped('Ed25519 key generation or export is not supported in this PHP/OpenSSL environment.');
+        }
+
+        $tempDir = sys_get_temp_dir() . '/fp-issuer-keys-' . time();
+        try {
+            $result = ChallengeUtils::generateIssuerPemKeys($tempDir);
+            $this->assertFileExists($result['privateKeyPath']);
+            $this->assertFileExists($result['publicKeyPath']);
+            $this->assertStringContainsString('-----BEGIN PRIVATE KEY-----', $result['privateKey']);
+            $this->assertStringContainsString('-----BEGIN PUBLIC KEY-----', $result['publicKey']);
+        } finally {
+            if (file_exists($tempDir . '/issuer-private.pem')) {
+                unlink($tempDir . '/issuer-private.pem');
+            }
+            if (file_exists($tempDir . '/issuer-public.pem')) {
+                unlink($tempDir . '/issuer-public.pem');
+            }
+            if (is_dir($tempDir)) {
+                rmdir($tempDir);
+            }
+        }
+    }
+
     public function testCooperativePoSpaceWorkflow(): void
     {
         $clientIp = '127.0.0.1';