Merge pull request #17 from yassinedoghri/feat/obfuscator

feat(obfuscator): add class to generate payload for altcha-widget obfuscation

Author: ovx

README.md

@@ -131,6 +131,31 @@ Finds a solution to the given challenge.
 
 **Returns:** `null|Solution`
 
+## Generate obfuscation payload
+
+Generate an obfuscated payload for client-side clarification:
+
+```php
+<?php
+
+// With optional maxNumber (defaults to 10_000)
+$obfuscator = new \AltchaOrg\Altcha\Obfuscator(); 
+
+// Text to reveal after client-side PoW
+$plaintext = 'mailto:[email protected]';
+
+// Optional shared key
+$key = 'shared-secret';
+
+// Optionally fix the counter; omit to use a random counter in [0, maxNumber]
+$fixedCounter = null;
+
+// Generate base64 obfuscated payload 
+$payload = $obfuscator->obfuscateData($plaintext, $key, $fixedCounter);
+
+echo $payload;
+// P7bJsUgzxP416d1voeF/QnQOD5g7GItB/zdfkoBrKgZK4N4IYkDJqg==
+```
 
 ## Tests
 

src/Obfuscator.php

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AltchaOrg\Altcha;
+
+use AltchaOrg\Altcha\Hasher\Algorithm;
+use AltchaOrg\Altcha\Hasher\Hasher;
+use AltchaOrg\Altcha\Hasher\HasherInterface;
+
+class Obfuscator
+{
+    public const DEFAULT_MAX_NUMBER = 10_000;
+
+    /**
+     * @param int $maxNumber Maximum number for the random number generator (default: 10,000)
+     */
+    public function __construct(
+        private readonly int $maxNumber = self::DEFAULT_MAX_NUMBER,
+        private readonly HasherInterface $hasher = new Hasher(),
+    ) {
+    }
+
+    /**
+     * Encrypts a payload for PoW-based reveal using AES-GCM.
+     *
+     * @param string   $raw     Plaintext payload to encrypt.
+     * @param string   $key     Symmetric key used to encrypt/decrypt the payload. Defaults to empty string, ie. no key.
+     * @param null|int $counter Optional fixed PoW counter used to derive the IV. If null, a random integer in [0, $this->maxNumber] inclusive is chosen.
+     *
+     * @return string Base64-encoded bytes of ciphertext followed by the 16‑byte GCM authentication tag ($ciphertext . $tag).
+     */
+    public function obfuscateData(string $raw, string $key = '', ?int $counter = null): string
+    {
+        $cipher = 'AES-256-GCM';
+        $keyHash = $this->hasher->hash(Algorithm::SHA256, $key);
+
+        $ivLength = openssl_cipher_iv_length($cipher);
+
+        if (false === $ivLength) {
+            throw new \RuntimeException('Getting cipher iv length failed.');
+        }
+
+        $iv = ''; // AES‑GCM initialization vector (IV), typically 12 bytes for AES-256-GCM
+        $num = $counter ?? $this->randomInt();
+
+        // Fill IV from the counter, one byte at a time (little‑endian)
+        for ($i = 0; $i < $ivLength; $i++) {
+            $iv .= \chr($num % 256);
+            $num = intdiv($num, 256);
+        }
+
+        $encryptedData = openssl_encrypt($raw, $cipher, $keyHash, \OPENSSL_RAW_DATA, $iv, $tag);
+
+        if (!$encryptedData) {
+            throw new \RuntimeException('Data encryption failed.');
+        }
+
+        return base64_encode($encryptedData . $tag);
+    }
+
+    private function randomInt(): int
+    {
+        return random_int(0, $this->maxNumber);
+    }
+}

tests/AltchaTest.php

@@ -6,6 +6,7 @@
 use AltchaOrg\Altcha\ChallengeOptions;
 use AltchaOrg\Altcha\Hasher\Algorithm;
 use AltchaOrg\Altcha\Hasher\Hasher;
+use AltchaOrg\Altcha\Obfuscator;
 use AltchaOrg\Altcha\Solution;
 use PHPUnit\Framework\TestCase;
 
@@ -217,4 +218,27 @@ public function testInvalidPayloads(): void
         ]);
         self::assertFalse($verification->verified);
     }
+
+    public function testDataObfuscation(): void
+    {
+        $obfuscator = new Obfuscator();
+        $counter = 1234;
+
+        $email = 'mailto:[email protected]';
+        $address = 'Big Company Ltd.' . \PHP_EOL . '123 Baker Street' . \PHP_EOL . 'London' . \PHP_EOL . 'NW1 6XE' . \PHP_EOL . 'United Kingdom';
+
+        $obfuscatedEmail = $obfuscator->obfuscateData($email, '', $counter);
+        $obfuscatedAddress = $obfuscator->obfuscateData($address, '', $counter);
+
+        self::assertEquals('0WkWnouD/fos4DdkwHP2yQ1/UejeYYUjP2vtH+F5+s8PYTJcvup6mg==', $obfuscatedEmail);
+        self::assertEquals('/mEY0ryDquIo4iIrzGLqhmo+D77QQIslSwgQNW1ojHqPmhU6DxlmZfKkXAfiCR2BabAg7E/K7kPttHA/c5sDe08H1tR822PCVNxRwGbVOg==', $obfuscatedAddress);
+
+        $key = 'shared-secret';
+
+        $obfuscatedEmailWithKey = $obfuscator->obfuscateData($email, $key, $counter);
+        $obfuscatedAddressWithKey = $obfuscator->obfuscateData($address, $key, $counter);
+
+        self::assertEquals('VYjBMLSjm0dasqAtnQvSlRiqG0V0paCoLFtNPZTB5jwmjPmV2Ja41w==', $obfuscatedEmailWithKey);
+        self::assertEquals('eoDPfIOjzF9esLVikRrO2n/rRRN6hK6ug4cwoWDJHYS9++OfBQjOUMP9oBHiGbNR0+3pj2whifZf/Cixj6oG+ybIQjx/t2apDsSLwr4qKg==', $obfuscatedAddressWithKey);
+    }
 }