@anonympins/fingerprint 0.7.0 → 0.7.2

package/src/php/DirectFingerprint.php

@@ -1,146 +1,191 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Anonympins\Fingerprint;
-
-use Anonympins\Fingerprint\Utils\MetricsManager;
-
-/**
- * Intégration directe du moteur de fingerprinting pour les applications PHP sans framework PSR.
- * Cette classe interagit directement avec les superglobales PHP et les fonctions de réponse.
- */
-class DirectFingerprint
-{
-    private array $securityConfig;
-    private FingerprintEngine $engine;
-
-    /**
-     * @param array $securityConfig La configuration de sécurité pour le moteur.
-     */
-    public function __construct(array $securityConfig)
-    {
-        $this->engine = new FingerprintEngine($securityConfig);
-        $this->securityConfig = $securityConfig;
-    }
-
-    /**
-     * Protège le point d'entrée actuel.
-     * Analyse la requête entrante et, si nécessaire, envoie une réponse de challenge/blocage et termine le script.
-     * Si la requête est autorisée, la méthode retourne simplement et le reste du script peut s'exécuter.
-     *
-     * @return array{score: float, vector: array}|null Les données du fingerprint si la requête est autorisée, null sinon.
-     */
-    public function protect(): ?array
-    {
-        // 1. Construire le contexte de la requête à partir des superglobales PHP.
-        $body = $_POST ?: json_decode(file_get_contents('php://input'), true);
-        $headers = function_exists('getallheaders') ? getallheaders() : [];
-
-        $context = new RequestContext(
-            $_SERVER['REMOTE_ADDR'] ?? '127.0.0.1',
-            parse_url($_SERVER['REQUEST_URI'] ?? '', PHP_URL_PATH) ?: '/',
-            $headers,
-            $_GET,
-            $body,
-            $_COOKIE,
-            $_SERVER['SERVER_PROTOCOL'] ?? '1.1'
-        );
-
-        // 2. Traiter la requête avec le moteur.
-        $decision = $this->engine->processRequest($context);
-
-        // 3. Agir sur la décision.
-        if (isset($context->newCookieForResponse)) {
-            $cookie = $context->newCookieForResponse;
-            setcookie($cookie['name'], $cookie['value'], $cookie['options']);
-        }
-
-        switch ($decision['action']) {
-            case 'block':
-            case 'challenge':
-                http_response_code($decision['status'] ?? 403);
-                if (is_array($decision['body'])) {
-                    header('Content-Type: application/json');
-                    echo json_encode($decision['body']);
-                } else {
-                    header('Content-Type: text/html; charset=utf-8');
-                    echo $decision['body'];
-                }
-                exit(); // Termine le script.
-
-            case 'redirect':
-                if (isset($decision['cookie'])) {
-                    setcookie($decision['cookie']['name'], $decision['cookie']['value'], $decision['cookie']['options']);
-                }
-                header('Location: ' . $decision['path'], true, 302);
-                exit(); // Termine le script.
-
-            case 'next':
-            default:
-                // La requête est autorisée, on retourne les informations du fingerprint.
-                return ['score' => $decision['score'], 'vector' => $decision['vector']];
-        }
-    }
-
-    /**
-     * Handles a request to the /metrics endpoint, applying authorization rules.
-     * If metrics are enabled and authorized, it outputs Prometheus formatted metrics and exits.
-     * Otherwise, it handles unauthorized access or returns a 404 if metrics are not enabled.
-     *
-     * @param RequestContext $context The current request context.
-     */
-    public function handleMetricsRequest(RequestContext $context): void
-    {
-        // 2. Appliquer le callback d'autorisation personnalisé si défini.
-        $authorizationCallback = $this->securityConfig['metricsAuthorizationCallback'] ?? null;
-        if (is_callable($authorizationCallback)) {
-            $decision = call_user_func($authorizationCallback, $context);
-
-            if (is_bool($decision)) {
-                if (!$decision) {
-                    http_response_code(403); // Forbidden
-                    echo "Access to metrics denied.";
-                    exit();
-                }
-            } elseif (is_array($decision) && isset($decision['action'])) {
-                switch ($decision['action']) {
-                    case 'block':
-                        http_response_code($decision['status'] ?? 403);
-                        echo $decision['body'] ?? "Access denied.";
-                        exit();
-                    case 'redirect':
-                        header('Location: ' . $decision['path'], true, $decision['status'] ?? 302);
-                        exit();
-                    case 'next':
-                        // Autorisé, continuer pour servir les métriques
-                        break;
-                    default:
-                        // Action inconnue, refuser par défaut
-                        http_response_code(403);
-                        echo "Invalid authorization decision.";
-                        exit();
-                }
-            } else {
-                // Retour inattendu du callback, refuser par défaut
-                http_response_code(403);
-                echo "Invalid authorization callback response.";
-                exit();
-            }
-        }
-
-        // 3. Si autorisé, servir les métriques.
-        header('Content-Type: text/plain; version=0.0.4; charset=utf-8');
-        echo MetricsManager::getPrometheusMetrics();
-        exit();
-    }
-
-    /**
-     * Returns Prometheus formatted metrics if enabled in the security configuration.
-     * @return string|null
-     */
-    public function getPrometheusMetrics(): ?string
-    {
-        return MetricsManager::getPrometheusMetrics();
-    }
+<?php
+
+declare(strict_types=1);
+
+namespace Anonympins\Fingerprint;
+
+use Anonympins\Fingerprint\Utils\MetricsManager;
+
+/**
+ * Direct integration of the fingerprint engine for PHP applications without a PSR framework.
+ * Interacts directly with PHP superglobals and response headers.
+ */
+class DirectFingerprint
+{
+    private array $securityConfig;
+    private FingerprintEngine $engine;
+
+    /**
+     * @param array $securityConfig Security configuration for the engine.
+     */
+    public function __construct(array $securityConfig)
+    {
+        $this->engine = new FingerprintEngine($securityConfig);
+        $this->securityConfig = $securityConfig;
+    }
+
+    /**
+     * 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
+        $body = $_POST ?: json_decode(file_get_contents('php://input'), true);
+        $headers = function_exists('getallheaders') ? getallheaders() : [];
+
+        $context = new RequestContext(
+            $_SERVER['REMOTE_ADDR'] ?? '127.0.0.1',
+            parse_url($_SERVER['REQUEST_URI'] ?? '', PHP_URL_PATH) ?: '/',
+            $headers,
+            $_GET,
+            $body,
+            $_COOKIE,
+            $_SERVER['SERVER_PROTOCOL'] ?? '1.1'
+        );
+
+        // 2. Process request with engine
+        $decision = $this->engine->processRequest($context);
+
+        // 3. Act on decision
+        if (isset($context->newCookieForResponse)) {
+            $cookie = $context->newCookieForResponse;
+            $this->sendCookie($cookie['name'], $cookie['value'], $cookie['options'] ?? []);
+        }
+
+        switch ($decision['action']) {
+            case 'block':
+            case 'challenge':
+                http_response_code($decision['status'] ?? 403);
+                if (is_array($decision['body'])) {
+                    header('Content-Type: application/json');
+                    echo json_encode($decision['body']);
+                } else {
+                    header('Content-Type: text/html; charset=utf-8');
+                    echo $decision['body'];
+                }
+                exit();
+
+            case 'redirect':
+                if (isset($decision['cookie'])) {
+                    $this->sendCookie($decision['cookie']['name'], $decision['cookie']['value'], $decision['cookie']['options'] ?? []);
+                }
+                header('Location: ' . $decision['path'], true, 302);
+                exit();
+
+            case 'next':
+            default:
+                // Request allowed, return fingerprint metrics
+                return ['score' => $decision['score'], 'vector' => $decision['vector']];
+        }
+    }
+
+    /**
+     * Sends an HTTP cookie while handling modern flags like 'partitioned'.
+     *
+     * @param string $name
+     * @param string $value
+     * @param array<string, mixed> $options
+     */
+    private function sendCookie(string $name, string $value, array $options): void
+    {
+        $isPartitioned = !empty($options['partitioned']);
+        unset($options['partitioned']);
+
+        // PHP setcookie() does not natively support 'partitioned'.
+        // If the cookie is secure and partitioned, emit raw header manually.
+        if ($isPartitioned && !empty($options['secure'])) {
+            $header = rawurlencode($name) . '=' . rawurlencode($value);
+            if (!empty($options['expires'])) {
+                $header .= '; Expires=' . gmdate('D, d M Y H:i:s T', (int)$options['expires']);
+                $header .= '; Max-Age=' . max(0, (int)$options['expires'] - time());
+            }
+            if (!empty($options['path'])) {
+                $header .= '; Path=' . $options['path'];
+            }
+            if (!empty($options['domain'])) {
+                $header .= '; Domain=' . $options['domain'];
+            }
+            if (!empty($options['secure'])) {
+                $header .= '; Secure';
+            }
+            if (!empty($options['httponly'])) {
+                $header .= '; HttpOnly';
+            }
+            if (!empty($options['samesite'])) {
+                $header .= '; SameSite=' . $options['samesite'];
+            }
+            $header .= '; Partitioned';
+            header('Set-Cookie: ' . $header, false);
+            return;
+        }
+
+        $allowedKeys = ['expires', 'path', 'domain', 'secure', 'httponly', 'samesite'];
+        $cleanOptions = array_intersect_key($options, array_flip($allowedKeys));
+        setcookie($name, $value, $cleanOptions);
+    }
+
+    /**
+     * Handles a request to the /metrics endpoint, applying authorization rules.
+     * If metrics are enabled and authorized, it outputs Prometheus formatted metrics and exits.
+     * Otherwise, it handles unauthorized access or returns a 404 if metrics are not enabled.
+     *
+     * @param RequestContext $context The current request context.
+     */
+    public function handleMetricsRequest(RequestContext $context): void
+    {
+        // 2. Apply custom authorization callback if configured
+        $authorizationCallback = $this->securityConfig['metricsAuthorizationCallback'] ?? null;
+        if (is_callable($authorizationCallback)) {
+            $decision = call_user_func($authorizationCallback, $context);
+
+            if (is_bool($decision)) {
+                if (!$decision) {
+                    http_response_code(403); // Forbidden
+                    echo "Access to metrics denied.";
+                    exit();
+                }
+            } elseif (is_array($decision) && isset($decision['action'])) {
+                switch ($decision['action']) {
+                    case 'block':
+                        http_response_code($decision['status'] ?? 403);
+                        echo $decision['body'] ?? "Access denied.";
+                        exit();
+                    case 'redirect':
+                        header('Location: ' . $decision['path'], true, $decision['status'] ?? 302);
+                        exit();
+                    case 'next':
+                        // Authorized; proceed to serve metrics
+                        break;
+                    default:
+                        // Unknown action; deny by default
+                        http_response_code(403);
+                        echo "Invalid authorization decision.";
+                        exit();
+                }
+            } else {
+                // Unexpected return type; deny by default
+                http_response_code(403);
+                echo "Invalid authorization callback response.";
+                exit();
+            }
+        }
+
+        // 3. If authorized, stream metrics output
+        header('Content-Type: text/plain; version=0.0.4; charset=utf-8');
+        echo MetricsManager::getPrometheusMetrics();
+        exit();
+    }
+
+    /**
+     * Returns Prometheus formatted metrics if enabled in the security configuration.
+     * @return string|null
+     */
+    public function getPrometheusMetrics(): ?string
+    {
+        return MetricsManager::getPrometheusMetrics();
+    }
 }

package/src/php/FingerprintBuilder.php

@@ -5,8 +5,8 @@ declare(strict_types=1);
 namespace Anonympins\Fingerprint;
 
 /**
- * Classe pour construire une empreinte composite (Multi-Hash).
- * Format de sortie : "grp1:hash1|grp2:hash2|grp3:hash3"
+ * Class to build a composite fingerprint (Multi-Hash).
+ * Output format: "grp1:hash1|grp2:hash2|grp3:hash3"
  */
 class FingerprintBuilder
 {
@@ -16,11 +16,10 @@ class FingerprintBuilder
     private array $components = [];
 
     /**
-     * Ajoute un composant à l'empreinte.
-     * La valeur est hachée pour l'anonymiser et réduire sa taille.
+     * Adds a component to the fingerprint.
      *
-     * @param string $group Le nom du groupe (ex: 'hw', 'screen', 'geo').
-     * @param string|int|bool|null $value La valeur brute à hacher.
+     * @param string $group Group name (e.g. 'hw', 'screen', 'geo').
+     * @param string|int|bool|null $value Raw value to hash.
      * @return self
      */
     public function add(string $group, $value): self
@@ -28,17 +27,17 @@ class FingerprintBuilder
         if ($value === null || $value === '') {
             return $this;
         }
-        // On hache la valeur individuellement.
+        // Hash the value individually
         $this->components[$group] = self::cyrb53((string)$value);
         return $this;
     }
 
     /**
-     * Ajoute un composant brut sans le hacher.
-     * Utile pour les métriques qui doivent être lues telles quelles par le serveur.
+     * Adds a raw component without hashing it.
+     * Useful for metrics that need to be read as-is on the server.
      *
-     * @param string $group Le nom du groupe.
-     * @param string|int|null $value La valeur brute.
+     * @param string $group Group name.
+     * @param string|int|null $value Raw value.
      * @return self
      */
     public function addRaw(string $group, $value): self
@@ -51,14 +50,14 @@ class FingerprintBuilder
     }
 
     /**
-     * Génère la chaîne de l'empreinte finale.
-     * Les composants sont triés par clé pour garantir un ordre déterministe.
+     * Generates the final fingerprint string.
+     * Components are sorted by key to guarantee deterministic ordering.
      *
      * @return string
      */
     public function __toString(): string
     {
-        // ksort trie le tableau par clé.
+        // Sort array by key
         ksort($this->components);
 
         $parts = [];
@@ -70,11 +69,11 @@ class FingerprintBuilder
     }
 
     /**
-     * Compare deux empreintes et retourne un score de similarité (de 0 à 1).
-     * Utilise une pondération pour donner plus d'importance aux invariants forts (Canvas, GPU, JA3).
+     * Compares two fingerprints and returns a similarity score (0 to 1).
+     * Uses weights to emphasize strong invariants (Canvas, GPU, JA3).
      *
-     * @param string|null $fpString1 Empreinte A.
-     * @param string|null $fpString2 Empreinte B.
+     * @param string|null $fpString1 Fingerprint A.
+     * @param string|null $fpString2 Fingerprint B.
      * @return float
      */
     public static function compare(?string $fpString1, ?string $fpString2): float
@@ -116,12 +115,12 @@ class FingerprintBuilder
         $allKeys = array_unique(array_merge(array_keys($map1), array_keys($map2)));
 
         foreach ($allKeys as $key) {
-            // On ignore les clés volatiles pour cette comparaison spécifique.
+            // Ignore volatile keys for this comparison
             if (in_array($key, $volatileKeys, true)) { // @phpstan-ignore-line
                 continue;
             }
 
-            // On ne compare que les clés qui ont un poids défini.
+            // Only compare keys that have an assigned weight
             $weight = $weights[$key] ?? null;
             if ($weight === null) continue;
 
@@ -137,12 +136,12 @@ class FingerprintBuilder
     }
 
     /**
-     * Algorithme de hachage cyrb53 (rapide et faible taux de collision).
-     * Porté depuis la version JavaScript.
+     * cyrb53 hashing algorithm (fast and low collision rate).
+     * Ported from the JavaScript version.
      *
-     * @param string $str La chaîne à hacher.
-     * @param int $seed Une graine optionnelle.
-     * @return string Le hash sous forme de chaîne de caractères.
+     * @param string $str String to hash.
+     * @param int $seed Optional seed.
+     * @return string Hash as string.
      */
     public static function cyrb53(string $str, int $seed = 0): string
     {
@@ -158,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);
 
-        // Sur les architectures 64 bits (standard en production), PHP gère nativement les entiers 64 bits signés.
-        // Nous pouvons éviter bcmath en effectuant des décalages binaires natifs pour un gain drastique de performances.
+        // On 64-bit platforms, PHP handles 64-bit signed ints natively.
+        // Use native shifts instead of bcmath for better performance.
         if (PHP_INT_SIZE === 8) {
             $h1_u = $h1 & 0xffffffff;
             $h2_u = $h2 & 0xffffffff;
@@ -167,17 +166,17 @@ class FingerprintBuilder
             return (string)$val_h2;
         }
 
-        // Fallback bcmath uniquement sur l'architecture obsolète 32 bits.
+        // Fallback to bcmath on 32-bit platforms
         $val_h2 = bcadd(bcmul((string)(2097151 & $h2), '4294967296'), (string)($h1 >= 0 ? $h1 : $h1 + 4294967296));
         return $val_h2;
     }
 
     /**
-     * Émule la multiplication 32-bit `Math.imul` de JavaScript.
+     * Emulates JavaScript's 32-bit `Math.imul` multiplication.
      *
      * @param int $a
      * @param int $b
-     * @return int Un entier signé 32-bit.
+     * @return int Signed 32-bit integer.
      */
     private static function imul(int $a, int $b): int
     {