@anonympins/fingerprint 0.7.4 → 0.8.0

package/src/php/Utils/BigInt.php

@@ -1,203 +1,203 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Anonympins\Fingerprint\Utils;
-
-class BigInt
-{
-    private static ?bool $useGmp = null;
-    /** @var \GMP|string */
-    private $value;
-
-    private static function useGmp(): bool
-    {
-        if (self::$useGmp === null) {
-            self::$useGmp = extension_loaded('gmp');
-        }
-        return self::$useGmp;
-    }
-
-    /**
-     * @param \GMP|string|int $number Le nombre initial.
-     */
-    public function __construct($number)
-    {
-        if (self::useGmp()) {
-            if ($number instanceof \GMP) {
-                $this->value = $number;
-            } else {
-                $str = (string)$number;
-                if (($dot = strpos($str, '.')) !== false) {
-                    $str = substr($str, 0, $dot);
-                }
-                $this->value = gmp_init($str);
-            }
-        } else {
-            if ($number instanceof BigInt) {
-                $this->value = $number->value;
-            } else {
-                $str = (string)$number;
-                if (($dot = strpos($str, '.')) !== false) {
-                    $str = substr($str, 0, $dot);
-                }
-                $this->value = $str;
-            }
-        }
-    }
-
-    /**
-     * Crée une instance à partir d'une chaîne hexadécimale.
-     */
-    public static function fromHex(string $hex): BigInt
-    {
-        $hex = trim(strtolower($hex));
-        if (substr($hex, 0, 2) === '0x') {
-            $hex = substr($hex, 2);
-        }
-        if (self::useGmp()) {
-            return new self(gmp_init($hex, 16));
-        } else {
-            $dec = '0';
-            $len = strlen($hex);
-            for ($i = 0; $i < $len; $i++) {
-                $dec = bcadd(bcmul($dec, '16', 0), (string)hexdec($hex[$i]), 0);
-            }
-            return new self($dec);
-        }
-    }
-
-    /**
-     * Compare cette instance avec une autre.
-     * @return int < 0 si this < other, 0 si this == other, > 0 si this > other.
-     */
-    public function compareTo(BigInt $other): int
-    {
-        if (self::useGmp()) {
-            return gmp_cmp($this->value, $other->value);
-        } else {
-            return bccomp($this->value, $other->value, 0);
-        }
-    }
-
-    /**
-     * Effectue un décalage de bits vers la gauche (<<).
-     */
-    public function shiftLeft(int $bits): BigInt
-    {
-        if (self::useGmp()) {
-            return new self(gmp_mul($this->value, gmp_pow("2", $bits)));
-        } else {
-            return new self(bcmul($this->value, bcpow("2", (string)$bits, 0), 0));
-        }
-    }
-
-    /**
-     * Effectue un décalage de bits vers la droite (>>).
-     */
-    public function shiftRight(int $bits): BigInt
-    {
-        if (self::useGmp()) {
-            return new self(gmp_div_q($this->value, gmp_pow("2", $bits)));
-        } else {
-            return new self(bcdiv($this->value, bcpow("2", (string)$bits, 0), 0));
-        }
-    }
-
-    /**
-     * Retourne la représentation en chaîne de caractères.
-     */
-    public function __toString(): string
-    {
-        if (self::useGmp()) {
-            return gmp_strval($this->value);
-        } else {
-            return $this->value;
-        }
-    }
-
-    /**
-     * Retourne la représentation hexadécimale.
-     */
-    public function toHex(): string
-    {
-        if (self::useGmp()) {
-            return gmp_strval($this->value, 16);
-        } else {
-            $hex = '';
-            $dec = $this->value;
-            while (bccomp($dec, '0', 0) > 0) {
-                $rem = bcmod($dec, '16', 0);
-                $hex = dechex((int)$rem) . $hex;
-                $dec = bcdiv($dec, '16', 0);
-            }
-            return $hex ?: '0';
-        }
-    }
-
-    /**
-     * Crée une instance à partir d'une puissance de 2.
-     */
-    public static function pow(int $base, int $exp): BigInt
-    {
-        if (self::useGmp()) {
-            return new self(gmp_pow((string)$base, $exp));
-        } else {
-            return new self(bcpow((string)$base, (string)$exp, 0));
-        }
-    }
-
-    /**
-     * Soustrait un autre BigInt.
-     */
-    public function sub(BigInt $other): BigInt
-    {
-        if (self::useGmp()) {
-            return new self(gmp_sub($this->value, $other->value));
-        } else {
-            return new self(bcsub($this->value, $other->value, 0));
-        }
-    }
-
-    /**
-     * Computes ($this ^ $exponent) % $modulus
-     */
-    public function modPow(BigInt $exponent, BigInt $modulus): BigInt
-    {
-        if (self::useGmp()) {
-            return new self(gmp_powm($this->value, $exponent->value, $modulus->value));
-        } else {
-            return new self(bcpowmod((string)$this->value, (string)$exponent->value, (string)$modulus->value, 0));
-        }
-    }
-
-    /**
-     * Computes $this % $modulus
-     */
-    public function mod(BigInt $modulus): BigInt
-    {
-        if (self::useGmp()) {
-            return new self(gmp_mod($this->value, $modulus->value));
-        } else {
-            return new self(bcmod((string)$this->value, (string)$modulus->value, 0));
-        }
-    }
-
-    public function add(BigInt $other): BigInt
-    {
-        if (self::useGmp()) {
-            return new self(gmp_add($this->value, $other->value));
-        } else {
-            return new self(bcadd((string)$this->value, (string)$other->value, 0));
-        }
-    }
-
-    public function mul(BigInt $other): BigInt
-    {
-        if (self::useGmp()) {
-            return new self(gmp_mul($this->value, $other->value));
-        } else {
-            return new self(bcmul((string)$this->value, (string)$other->value, 0));
-        }
-    }
+<?php
+
+declare(strict_types=1);
+
+namespace Anonympins\Fingerprint\Utils;
+
+class BigInt
+{
+    private static ?bool $useGmp = null;
+    /** @var \GMP|string */
+    private $value;
+
+    private static function useGmp(): bool
+    {
+        if (self::$useGmp === null) {
+            self::$useGmp = extension_loaded('gmp');
+        }
+        return self::$useGmp;
+    }
+
+    /**
+     * @param \GMP|string|int $number Initial number.
+     */
+    public function __construct($number)
+    {
+        if (self::useGmp()) {
+            if ($number instanceof \GMP) {
+                $this->value = $number;
+            } else {
+                $str = (string)$number;
+                if (($dot = strpos($str, '.')) !== false) {
+                    $str = substr($str, 0, $dot);
+                }
+                $this->value = gmp_init($str);
+            }
+        } else {
+            if ($number instanceof BigInt) {
+                $this->value = $number->value;
+            } else {
+                $str = (string)$number;
+                if (($dot = strpos($str, '.')) !== false) {
+                    $str = substr($str, 0, $dot);
+                }
+                $this->value = $str;
+            }
+        }
+    }
+
+    /**
+     * Creates an instance from a hexadecimal string.
+     */
+    public static function fromHex(string $hex): BigInt
+    {
+        $hex = trim(strtolower($hex));
+        if (substr($hex, 0, 2) === '0x') {
+            $hex = substr($hex, 2);
+        }
+        if (self::useGmp()) {
+            return new self(gmp_init($hex, 16));
+        } else {
+            $dec = '0';
+            $len = strlen($hex);
+            for ($i = 0; $i < $len; $i++) {
+                $dec = bcadd(bcmul($dec, '16', 0), (string)hexdec($hex[$i]), 0);
+            }
+            return new self($dec);
+        }
+    }
+
+    /**
+     * Compares this instance with another.
+     * @return int < 0 if this < other, 0 if this == other, > 0 if this > other.
+     */
+    public function compareTo(BigInt $other): int
+    {
+        if (self::useGmp()) {
+            return gmp_cmp($this->value, $other->value);
+        } else {
+            return bccomp($this->value, $other->value, 0);
+        }
+    }
+
+    /**
+     * Performs bitwise left shift (<<).
+     */
+    public function shiftLeft(int $bits): BigInt
+    {
+        if (self::useGmp()) {
+            return new self(gmp_mul($this->value, gmp_pow("2", $bits)));
+        } else {
+            return new self(bcmul($this->value, bcpow("2", (string)$bits, 0), 0));
+        }
+    }
+
+    /**
+     * Performs bitwise right shift (>>).
+     */
+    public function shiftRight(int $bits): BigInt
+    {
+        if (self::useGmp()) {
+            return new self(gmp_div_q($this->value, gmp_pow("2", $bits)));
+        } else {
+            return new self(bcdiv($this->value, bcpow("2", (string)$bits, 0), 0));
+        }
+    }
+
+    /**
+     * Returns the string representation.
+     */
+    public function __toString(): string
+    {
+        if (self::useGmp()) {
+            return gmp_strval($this->value);
+        } else {
+            return $this->value;
+        }
+    }
+
+    /**
+     * Returns the hexadecimal representation.
+     */
+    public function toHex(): string
+    {
+        if (self::useGmp()) {
+            return gmp_strval($this->value, 16);
+        } else {
+            $hex = '';
+            $dec = $this->value;
+            while (bccomp($dec, '0', 0) > 0) {
+                $rem = bcmod($dec, '16', 0);
+                $hex = dechex((int)$rem) . $hex;
+                $dec = bcdiv($dec, '16', 0);
+            }
+            return $hex ?: '0';
+        }
+    }
+
+    /**
+     * Creates an instance from a power of two.
+     */
+    public static function pow(int $base, int $exp): BigInt
+    {
+        if (self::useGmp()) {
+            return new self(gmp_pow((string)$base, $exp));
+        } else {
+            return new self(bcpow((string)$base, (string)$exp, 0));
+        }
+    }
+
+    /**
+     * Subtracts another BigInt.
+     */
+    public function sub(BigInt $other): BigInt
+    {
+        if (self::useGmp()) {
+            return new self(gmp_sub($this->value, $other->value));
+        } else {
+            return new self(bcsub($this->value, $other->value, 0));
+        }
+    }
+
+    /**
+     * Computes ($this ^ $exponent) % $modulus
+     */
+    public function modPow(BigInt $exponent, BigInt $modulus): BigInt
+    {
+        if (self::useGmp()) {
+            return new self(gmp_powm($this->value, $exponent->value, $modulus->value));
+        } else {
+            return new self(bcpowmod((string)$this->value, (string)$exponent->value, (string)$modulus->value, 0));
+        }
+    }
+
+    /**
+     * Computes $this % $modulus
+     */
+    public function mod(BigInt $modulus): BigInt
+    {
+        if (self::useGmp()) {
+            return new self(gmp_mod($this->value, $modulus->value));
+        } else {
+            return new self(bcmod((string)$this->value, (string)$modulus->value, 0));
+        }
+    }
+
+    public function add(BigInt $other): BigInt
+    {
+        if (self::useGmp()) {
+            return new self(gmp_add($this->value, $other->value));
+        } else {
+            return new self(bcadd((string)$this->value, (string)$other->value, 0));
+        }
+    }
+
+    public function mul(BigInt $other): BigInt
+    {
+        if (self::useGmp()) {
+            return new self(gmp_mul($this->value, $other->value));
+        } else {
+            return new self(bcmul((string)$this->value, (string)$other->value, 0));
+        }
+    }
 }

package/src/php/Utils/BlockList.php

@@ -5,18 +5,18 @@ declare(strict_types=1);
 namespace Anonympins\Fingerprint\Utils;
 
 /**
- * Implémentation PHP d'une liste de blocage IP/CIDR, similaire à Node.js `net.BlockList`.
+ * PHP implementation of an IP/CIDR blocklist, similar to Node.js `net.BlockList`.
  */
 class BlockList
 {
     /**
-     * @var array<string> Liste des IPs ou CIDR à bloquer.
+     * @var array<string> List of IPs or CIDR blocks to filter.
      */
     private array $entries = [];
 
     /**
-     * Ajoute une adresse IP ou une plage CIDR à la liste.
-     * @param string $entry Une adresse IP (ex: '192.168.1.1') ou une plage CIDR (ex: '192.168.1.0/24').
+     * Adds an IP address or CIDR range to the list.
+     * @param string $entry An IP address (e.g. '192.168.1.1') or CIDR range (e.g. '192.168.1.0/24').
      * @return void
      */
     public function add(string $entry): void
@@ -25,20 +25,20 @@ class BlockList
     }
 
     /**
-     * Vérifie si une adresse IP est présente dans la liste de blocage.
-     * @param string $ip L'adresse IP à vérifier.
-     * @return bool True si l'IP est bloquée, false sinon.
+     * Checks if an IP address exists in the blocklist.
+     * @param string $ip The IP address to verify.
+     * @return bool True if the IP matches, false otherwise.
      */
     public function check(string $ip): bool
     {
         foreach ($this->entries as $entry) {
             if (str_contains($entry, '/')) {
-                // C'est une plage CIDR
+                // CIDR range
                 if ($this->ipInCidr($ip, $entry)) {
                     return true;
                 }
             } else {
-                // C'est une IP directe
+                // Direct IP match
                 if ($ip === $entry) {
                     return true;
                 }
@@ -48,10 +48,10 @@ class BlockList
     }
 
     /**
-     * Vérifie si une adresse IP se trouve dans une plage CIDR donnée.
-     * @param string $ip L'adresse IP à vérifier.
-     * @param string $cidr La plage CIDR (ex: '192.168.1.0/24').
-     * @return bool True si l'IP est dans la plage, false sinon.
+     * Checks if an IP address belongs to a given CIDR range.
+     * @param string $ip The IP address to verify.
+     * @param string $cidr The CIDR range (e.g. '192.168.1.0/24').
+     * @return bool True if the IP is within the range, false otherwise.
      */
     private function ipInCidr(string $ip, string $cidr): bool
     {

package/src/php/Utils/Logger.php

@@ -5,7 +5,7 @@ declare(strict_types=1);
 namespace Anonympins\Fingerprint\Utils;
 
 /**
- * Un simple wrapper de logger pour passer les données à une fonction de rappel.
+ * A simple logger wrapper to forward data to a callback function.
  */
 class Logger
 {
@@ -14,11 +14,29 @@ class Logger
      */
     private $callback;
 
+    /**
+     * Creates a new Logger instance with the given callback.
+     * The callback will be invoked with a single log entry array argument
+     * each time `log()` is called.
+     *
+     * @param callable $callback The callback used to process log entries.
+     */
     public function __construct(callable $callback)
     {
         $this->callback = $callback;
     }
 
+    /**
+     * Emits a log entry by merging the provided data with a type and a
+     * millisecond-precision timestamp, then forwarding it to the callback.
+     * Note: the `$level` parameter is currently accepted but not included
+     * in the emitted log entry.
+     *
+     * @param string $level The log level (e.g. "info", "warning", "error").
+     * @param string $type The log entry type/category.
+     * @param array $data Additional data to include in the log entry.
+     * @return void
+     */
     public function log(string $level, string $type, array $data): void
     {
         $logEntry = array_merge($data, [

package/src/php/Utils/MaliciousPatterns.php

@@ -5,12 +5,12 @@ declare(strict_types=1);
 namespace Anonympins\Fingerprint\Utils;
 
 /**
- * Fournit des fonctions pour détecter les patterns d'injection malveillants.
+ * Provides utilities to detect malicious injection patterns.
  */
 class MaliciousPatterns
 {
     /**
-     * @var array<string, string> Map des patterns malveillants regroupés par type.
+     * @var array<string, string> Map of malicious patterns grouped by threat category.
      */
     private const INJECTION_PATTERNS = [
         // SQL/NoSQL injections, including time-based attacks
@@ -44,10 +44,10 @@ class MaliciousPatterns
     ];
 
     /**
-     * Vérifie si une chaîne de caractères contient des patterns d'injection connus.
-     * @param string $str La chaîne à vérifier.
-     * @param array<string> $typesToDetect Les types d'injections à détecter (par défaut, tous).
-     * @return bool True si un pattern malveillant est détecté, false sinon.
+     * Checks whether a string matches known injection patterns.
+     * @param string $str The input string to inspect.
+     * @param array<string> $typesToDetect Specific injection categories to detect (defaults to all).
+     * @return bool True if a malicious pattern is detected, false otherwise.
      */
     public static function isMalicious(string $str, array $typesToDetect = []): bool
     {