feat: add encryption

innocenzi · innocenzi · commit b1bf38269ddd · 2025-07-03T21:59:19.000+02:00
diff --git a/packages/cryptography/src/Encryption/EncryptedData.php b/packages/cryptography/src/Encryption/EncryptedData.php
@@ -0,0 +1,54 @@
+<?php
+
+namespace Tempest\Cryptography\Encryption;
+
+use Stringable;
+use Tempest\Cryptography\Encryption\Exceptions\EncryptedDataWasInvalid;
+use Tempest\Cryptography\Signing\Signature;
+use Tempest\Support\Json;
+
+final readonly class EncryptedData implements Stringable
+{
+    public function __construct(
+        private(set) string $payload,
+        private(set) string $iv,
+        private(set) string $tag,
+        private(set) Signature $signature,
+        private(set) EncryptionAlgorithm $algorithm,
+    ) {}
+
+    public function serialize(): string
+    {
+        $data = [
+            'payload' => base64_encode($this->payload),
+            'iv' => base64_encode($this->iv),
+            'tag' => base64_encode($this->tag),
+            'signature' => $this->signature->value,
+            'algorithm' => $this->algorithm->value,
+        ];
+
+        return base64_encode(Json\encode($data));
+    }
+
+    public static function unserialize(string $data): self
+    {
+        $decoded = Json\decode(base64_decode($data));
+
+        if (! is_array($decoded) || ! isset($decoded['payload'], $decoded['iv'], $decoded['tag'], $decoded['signature'], $decoded['algorithm'])) {
+            throw EncryptedDataWasInvalid::dueToInvalidFormat();
+        }
+
+        return new self(
+            payload: base64_decode($decoded['payload']),
+            iv: base64_decode($decoded['iv']),
+            tag: base64_decode($decoded['tag']),
+            signature: new Signature($decoded['signature']),
+            algorithm: EncryptionAlgorithm::from($decoded['algorithm']),
+        );
+    }
+
+    public function __toString(): string
+    {
+        return $this->serialize();
+    }
+}
diff --git a/packages/cryptography/src/Encryption/Encrypter.php b/packages/cryptography/src/Encryption/Encrypter.php
@@ -0,0 +1,20 @@
+<?php
+
+namespace Tempest\Cryptography\Encryption;
+
+interface Encrypter
+{
+    public EncryptionAlgorithm $algorithm {
+        get;
+    }
+
+    /**
+     * Encrypts the specified data.
+     */
+    public function encrypt(#[\SensitiveParameter] string $data): EncryptedData;
+
+    /**
+     * Decrypts the specified data.
+     */
+    public function decrypt(string|EncryptedData $data): string;
+}
diff --git a/packages/cryptography/src/Encryption/EncrypterInitializer.php b/packages/cryptography/src/Encryption/EncrypterInitializer.php
@@ -0,0 +1,20 @@
+<?php
+
+namespace Tempest\Cryptography\Encryption;
+
+use Tempest\Container\Container;
+use Tempest\Container\Initializer;
+use Tempest\Container\Singleton;
+use Tempest\Cryptography\Signing\Signer;
+
+final class EncrypterInitializer implements Initializer
+{
+    #[Singleton]
+    public function initialize(Container $container): Encrypter
+    {
+        return new GenericEncrypter(
+            signer: $container->get(Signer::class),
+            config: $container->get(EncryptionConfig::class),
+        );
+    }
+}
diff --git a/packages/cryptography/src/Encryption/EncryptionAlgorithm.php b/packages/cryptography/src/Encryption/EncryptionAlgorithm.php
@@ -0,0 +1,30 @@
+<?php
+
+namespace Tempest\Cryptography\Encryption;
+
+enum EncryptionAlgorithm: string
+{
+    case AES_256_GCM = 'aes-256-gcm';
+    case AES_256_CBC = 'aes-256-cbc';
+    case AES_128_GCM = 'aes-128-gcm';
+    case AES_128_CBC = 'aes-128-cbc';
+    case CHACHA20_POLY1305 = 'chacha20-poly1305';
+
+    public function getKeyLength(): int
+    {
+        return openssl_cipher_key_length($this->value);
+    }
+
+    public function getIvLength(): int
+    {
+        return openssl_cipher_iv_length($this->value);
+    }
+
+    public function isAead(): bool
+    {
+        return match ($this) {
+            self::AES_256_GCM, self::AES_128_GCM, self::CHACHA20_POLY1305 => true,
+            self::AES_256_CBC, self::AES_128_CBC => false,
+        };
+    }
+}
diff --git a/packages/cryptography/src/Encryption/EncryptionConfig.php b/packages/cryptography/src/Encryption/EncryptionConfig.php
@@ -0,0 +1,16 @@
+<?php
+
+namespace Tempest\Cryptography\Encryption;
+
+final class EncryptionConfig
+{
+    /**
+     * @param EncryptionAlgorithm $algorithm The algorithm used for encrypting and decrypting values.
+     * @param non-empty-string $key A private, secure encryption key.
+     */
+    public function __construct(
+        public EncryptionAlgorithm $algorithm,
+        #[\SensitiveParameter]
+        public string $key,
+    ) {}
+}
diff --git a/packages/cryptography/src/Encryption/EncryptionKey.php b/packages/cryptography/src/Encryption/EncryptionKey.php
@@ -0,0 +1,43 @@
+<?php
+
+namespace Tempest\Cryptography\Encryption;
+
+use Stringable;
+use Tempest\Cryptography\Encryption\Exceptions\EncryptionKeyWasInvalid;
+
+final readonly class EncryptionKey implements Stringable
+{
+    public function __construct(
+        private(set) string $value,
+        private(set) EncryptionAlgorithm $algorithm,
+    ) {
+        if (trim($value) === '') {
+            throw EncryptionKeyWasInvalid::becauseItIsMissing($algorithm);
+        }
+
+        if (strlen($value) !== $algorithm->getKeyLength()) {
+            throw EncryptionKeyWasInvalid::becauseLengthMismatched($algorithm);
+        }
+    }
+
+    /**
+     * Generates a new cryptographically secure key using the specified algorithm.
+     */
+    public static function generate(EncryptionAlgorithm $algorithm): self
+    {
+        return new self(random_bytes($algorithm->getKeyLength()), $algorithm);
+    }
+
+    /**
+     * Creates an encryption key from a string.
+     */
+    public static function fromString(string $key, EncryptionAlgorithm $algorithm): self
+    {
+        return new self($key, $algorithm);
+    }
+
+    public function __toString(): string
+    {
+        return $this->value;
+    }
+}
diff --git a/packages/cryptography/src/Encryption/Exceptions/AlgorithmMismatched.php b/packages/cryptography/src/Encryption/Exceptions/AlgorithmMismatched.php
@@ -0,0 +1,13 @@
+<?php
+
+namespace Tempest\Cryptography\Encryption\Exceptions;
+
+use Exception;
+
+final class AlgorithmMismatched extends Exception implements EncryptionException
+{
+    public static function betweenKeyAndData(): self
+    {
+        return new self('The encryption algorithm used for the key does not match the algorithm used for the data. Ensure that both are using the same algorithm.');
+    }
+}
diff --git a/packages/cryptography/src/Encryption/Exceptions/DecryptionFailed.php b/packages/cryptography/src/Encryption/Exceptions/DecryptionFailed.php
@@ -0,0 +1,26 @@
+<?php
+
+namespace Tempest\Cryptography\Encryption\Exceptions;
+
+use Exception;
+use Tempest\Core\HasContext;
+
+final class DecryptionFailed extends Exception implements EncryptionException, HasContext
+{
+    public function __construct(
+        string $message,
+        private readonly array $context = [],
+    ) {
+        parent::__construct($message);
+    }
+
+    public static function becauseOpenSslFailed(string $error): self
+    {
+        return new self('OpenSSL encryption failed.', ['error' => $error]);
+    }
+
+    public function context(): array
+    {
+        return $this->context;
+    }
+}
diff --git a/packages/cryptography/src/Encryption/Exceptions/EncryptedDataWasInvalid.php b/packages/cryptography/src/Encryption/Exceptions/EncryptedDataWasInvalid.php
@@ -0,0 +1,13 @@
+<?php
+
+namespace Tempest\Cryptography\Encryption\Exceptions;
+
+use Exception;
+
+final class EncryptedDataWasInvalid extends Exception implements EncryptionException
+{
+    public static function dueToInvalidFormat(): self
+    {
+        return new self('The encrypted data is not in the expected format.');
+    }
+}
diff --git a/packages/cryptography/src/Encryption/Exceptions/EncryptionException.php b/packages/cryptography/src/Encryption/Exceptions/EncryptionException.php
@@ -0,0 +1,7 @@
+<?php
+
+namespace Tempest\Cryptography\Encryption\Exceptions;
+
+interface EncryptionException
+{
+}
diff --git a/packages/cryptography/src/Encryption/Exceptions/EncryptionFailed.php b/packages/cryptography/src/Encryption/Exceptions/EncryptionFailed.php
@@ -0,0 +1,26 @@
+<?php
+
+namespace Tempest\Cryptography\Encryption\Exceptions;
+
+use Exception;
+use Tempest\Core\HasContext;
+
+final class EncryptionFailed extends Exception implements EncryptionException, HasContext
+{
+    public function __construct(
+        string $message,
+        private readonly array $context = [],
+    ) {
+        parent::__construct($message);
+    }
+
+    public static function becauseOpenSslFailed(string $error): self
+    {
+        return new self('OpenSSL encryption failed.', ['error' => $error]);
+    }
+
+    public function context(): array
+    {
+        return $this->context;
+    }
+}
diff --git a/packages/cryptography/src/Encryption/Exceptions/EncryptionKeyWasInvalid.php b/packages/cryptography/src/Encryption/Exceptions/EncryptionKeyWasInvalid.php
@@ -0,0 +1,29 @@
+<?php
+
+namespace Tempest\Cryptography\Encryption\Exceptions;
+
+use Exception;
+use Tempest\Cryptography\Encryption\EncryptionAlgorithm;
+
+final class EncryptionKeyWasInvalid extends Exception implements EncryptionException
+{
+    public function __construct(
+        string $message,
+        public readonly EncryptionAlgorithm $algorithm,
+    ) {
+        parent::__construct($message);
+    }
+
+    public static function becauseItIsMissing(EncryptionAlgorithm $algorithm): self
+    {
+        return new self('The encryption key is missing or empty. Ensure you have a `SIGNING_KEY` environment variable.', $algorithm);
+    }
+
+    public static function becauseLengthMismatched(EncryptionAlgorithm $algorithm): self
+    {
+        return new self(
+            "The encryption key length does not match the expected length ({$algorithm->getKeyLength()}).",
+            $algorithm,
+        );
+    }
+}
diff --git a/packages/cryptography/src/Encryption/Exceptions/SignatureMismatched.php b/packages/cryptography/src/Encryption/Exceptions/SignatureMismatched.php
@@ -0,0 +1,13 @@
+<?php
+
+namespace Tempest\Cryptography\Encryption\Exceptions;
+
+use Exception;
+
+final class SignatureMismatched extends Exception implements EncryptionException
+{
+    public static function raise(): self
+    {
+        return new self('The signature does not match the data. This could indicate that the data has been tampered with or that the wrong key was used for verification.');
+    }
+}
diff --git a/packages/cryptography/src/Encryption/GenericEncrypter.php b/packages/cryptography/src/Encryption/GenericEncrypter.php
diff --git a/packages/cryptography/src/Encryption/encryption.config.php b/packages/cryptography/src/Encryption/encryption.config.php
diff --git a/packages/cryptography/tests/CreatesSigner.php b/packages/cryptography/tests/CreatesSigner.php
diff --git a/packages/cryptography/tests/Encryption/EncryptionTest.php b/packages/cryptography/tests/Encryption/EncryptionTest.php
diff --git a/packages/cryptography/tests/Signing/SignerTest.php b/packages/cryptography/tests/Signing/SignerTest.php
diff --git a/tests/Integration/Cryptography/EncrypterTest.php b/tests/Integration/Cryptography/EncrypterTest.php

-Original file line number
+Diff line change
@@ @@ -0,0 +1,7 @@ @@
 +<?php
++
 +namespace Tempest\Cryptography\Encryption\Exceptions;
++
 +interface EncryptionException
 +{
 +}