Add encoders

Author: paulbalandan

src/Nexus/Encryption/Encoding/AbstractBase64Encoder.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <paulbalandan@gmail.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Encryption\Encoding;
+
+abstract class AbstractBase64Encoder implements EncoderInterface
+{
+    public function encode(#[\SensitiveParameter] string $binaryString): string
+    {
+        return sodium_bin2base64($binaryString, $this->getBase64Variant());
+    }
+
+    public function decode(#[\SensitiveParameter] string $encodedString, string $ignore = ''): string
+    {
+        return sodium_base642bin($encodedString, $this->getBase64Variant(), $ignore);
+    }
+
+    /**
+     * Get the variant of Base64 encoding to use.
+     */
+    abstract protected function getBase64Variant(): int;
+}

src/Nexus/Encryption/Encoding/Base64OriginalEncoder.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <paulbalandan@gmail.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Encryption\Encoding;
+
+/**
+ * Standard (A-Za-z0-9/\+) Base64 encoder.
+ */
+final class Base64OriginalEncoder extends AbstractBase64Encoder
+{
+    protected function getBase64Variant(): int
+    {
+        return SODIUM_BASE64_VARIANT_ORIGINAL;
+    }
+}

src/Nexus/Encryption/Encoding/Base64OriginalNoPaddingEncoder.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <paulbalandan@gmail.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Encryption\Encoding;
+
+/**
+ * Standard (A-Za-z0-9/\+) Base64 encoder without `=` padding characters.
+ */
+final class Base64OriginalNoPaddingEncoder extends AbstractBase64Encoder
+{
+    protected function getBase64Variant(): int
+    {
+        return SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING;
+    }
+}

src/Nexus/Encryption/Encoding/Base64UrlSafeEncoder.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <paulbalandan@gmail.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Encryption\Encoding;
+
+/**
+ * URL-safe (A-Za-z0-9\-_) Base64 encoder.
+ */
+final class Base64UrlSafeEncoder extends AbstractBase64Encoder
+{
+    protected function getBase64Variant(): int
+    {
+        return SODIUM_BASE64_VARIANT_URLSAFE;
+    }
+}

src/Nexus/Encryption/Encoding/Base64UrlSafeNoPaddingEncoder.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <paulbalandan@gmail.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Encryption\Encoding;
+
+/**
+ * URL-safe (A-Za-z0-9\-_) Base64 encoder, without `=` padding characters.
+ */
+final class Base64UrlSafeNoPaddingEncoder extends AbstractBase64Encoder
+{
+    protected function getBase64Variant(): int
+    {
+        return SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING;
+    }
+}

src/Nexus/Encryption/Encoding/EncoderInterface.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <paulbalandan@gmail.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Encryption\Encoding;
+
+interface EncoderInterface
+{
+    /**
+     * Encodes a binary string into a readable format without cache-timing attacks.
+     */
+    public function encode(#[\SensitiveParameter] string $binaryString): string;
+
+    /**
+     * Converts an encoded string back to its original binary format without cache-timing attacks.
+     *
+     * @param string $ignore Characters to ignore when decoding (e.g. whitespace characters)
+     */
+    public function decode(#[\SensitiveParameter] string $encodedString, string $ignore = ''): string;
+}

src/Nexus/Encryption/Encoding/HexEncoder.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <paulbalandan@gmail.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Encryption\Encoding;
+
+/**
+ * Encode/decode binary data to/from hexadecimal strings without any side-channel attacks.
+ */
+final class HexEncoder implements EncoderInterface
+{
+    public function encode(#[\SensitiveParameter] string $binaryString): string
+    {
+        return sodium_bin2hex($binaryString);
+    }
+
+    public function decode(#[\SensitiveParameter] string $encodedString, string $ignore = ''): string
+    {
+        return sodium_hex2bin($encodedString, $ignore);
+    }
+}

src/Nexus/Encryption/Encoding/NullEncoder.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <paulbalandan@gmail.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Encryption\Encoding;
+
+final class NullEncoder implements EncoderInterface
+{
+    public function encode(#[\SensitiveParameter] string $binaryString): string
+    {
+        return $binaryString;
+    }
+
+    public function decode(#[\SensitiveParameter] string $encodedString, string $ignore = ''): string
+    {
+        return $encodedString;
+    }
+}

tests/Encryption/Encoding/AbstractEncoderTestCase.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <paulbalandan@gmail.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Tests\Encryption\Encoding;
+
+use Nexus\Encryption\Encoding\EncoderInterface;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @internal
+ */
+abstract class AbstractEncoderTestCase extends TestCase
+{
+    /**
+     * @param int<1, 32> $i
+     */
+    #[DataProvider('provideEncodeDecodeCases')]
+    public function testEncodeDecode(int $i): void
+    {
+        $encoder = $this->createEncoder();
+        $data = random_bytes($i);
+
+        $encoded = $encoder->encode($data);
+        $decoded = $encoder->decode($encoded);
+
+        self::assertSame($data, $decoded);
+        self::assertSame($this->nativeEncode($data), $encoded);
+        self::assertSame($this->nativeDecode($encoded), $decoded);
+    }
+
+    /**
+     * @return iterable<string, array{int}>
+     */
+    public static function provideEncodeDecodeCases(): iterable
+    {
+        for ($i = 1; $i <= 32; ++$i) {
+            yield \sprintf('%02d bytes', $i) => [$i];
+        }
+    }
+
+    abstract protected function createEncoder(): EncoderInterface;
+
+    abstract protected function nativeEncode(string $data): string;
+
+    abstract protected function nativeDecode(string $encoded): string;
+}

tests/Encryption/Encoding/Base64OriginalEncoderTest.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <paulbalandan@gmail.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Tests\Encryption\Encoding;
+
+use Nexus\Encryption\Encoding\AbstractBase64Encoder;
+use Nexus\Encryption\Encoding\Base64OriginalEncoder;
+use Nexus\Encryption\Encoding\EncoderInterface;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Group;
+
+/**
+ * @internal
+ */
+#[CoversClass(AbstractBase64Encoder::class)]
+#[CoversClass(Base64OriginalEncoder::class)]
+#[Group('unit-test')]
+final class Base64OriginalEncoderTest extends AbstractEncoderTestCase
+{
+    protected function createEncoder(): EncoderInterface
+    {
+        return new Base64OriginalEncoder();
+    }
+
+    protected function nativeEncode(string $data): string
+    {
+        return sodium_bin2base64($data, SODIUM_BASE64_VARIANT_ORIGINAL);
+    }
+
+    protected function nativeDecode(string $encoded): string
+    {
+        return sodium_base642bin($encoded, SODIUM_BASE64_VARIANT_ORIGINAL);
+    }
+}