feat(vault): add marshaller and domain exceptions

Author: JoshuaEstes

docs/components/vault.md

@@ -1,28 +1,62 @@
 # Vault
 
-The Vault component securely stores secrets using pluggable storage backends and encryption with key rotation and support for additional authenticated data (AAD).
+The Vault component securely stores secrets using pluggable storage backends and encryption with key rotation, versioning, and additional authenticated data (AAD).
 
-## Basic Usage
+## Setup
 
 ```php
 use SonsOfPHP\Component\Vault\Cipher\OpenSSLCipher;
 use SonsOfPHP\Component\Vault\KeyRing\InMemoryKeyRing;
+use SonsOfPHP\Component\Vault\Marshaller\JsonMarshaller;
 use SonsOfPHP\Component\Vault\Storage\InMemoryStorage;
 use SonsOfPHP\Component\Vault\Vault;
 
-$keyRing = new InMemoryKeyRing(['v1' => '32_byte_master_key_example!!'], 'v1');
-$vault   = new Vault(new InMemoryStorage(), new OpenSSLCipher(), $keyRing);
-$vault->set('db_password', 'secret', ['app']);
-$secret = $vault->get('db_password', ['app']);
+$storage    = new InMemoryStorage();
+$cipher     = new OpenSSLCipher();
+$keyRing    = new InMemoryKeyRing(['v1' => '32_byte_master_key_example!!'], 'v1');
+$marshaller = new JsonMarshaller();
+$vault      = new Vault($storage, $cipher, $keyRing, $marshaller);
+```
+
+## Storing and Retrieving Secrets
+
+```php
+$vault->set('db_password', 'secret');
+$secret = $vault->get('db_password');
+```
+
+## Using Additional Authenticated Data
 
-// Store a new version of the secret
-$vault->set('db_password', 'new-secret', ['app']);
-$oldSecret = $vault->get('db_password', ['app'], 1); // retrieve version 1
+```php
+$vault->set('token', 'secret', ['app']);
+$secret = $vault->get('token', ['app']);
+```
+
+## Versioned Secrets
+
+```php
+$vault->set('db_password', 'old-secret');
+$vault->set('db_password', 'new-secret');
 
-// Rotate the master key
+// Retrieve specific version
+$old = $vault->get('db_password', [], 1);
+```
+
+## Rotating Keys
+
+```php
 $vault->rotateKey('v2', 'another_32_byte_master_key!!');
+```
 
-// Store non-string data
+Secrets encrypted with previous keys remain accessible because the key ring keeps old keys.
+
+## Storing Non-String Data
+
+```php
 $vault->set('config', ['user' => 'root']);
 $config = $vault->get('config');
 ```
+
+## Custom Marshallers
+
+Vault uses a marshaller to convert secrets to strings before encryption. The default `JsonMarshaller` handles arrays and scalars, but you can provide your own implementation of `MarshallerInterface` for advanced use cases.

src/SonsOfPHP/Component/Vault/AGENTS.md

@@ -12,3 +12,13 @@
 - Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Component/Vault/Tests' make test`
 - Style and static analysis: `make php-cs-fixer` and `make psalm`
 - Upgrade code (may modify files): `make upgrade-code`
+
+## Testing Guidelines
+
+- Use PHPUnit attributes such as `#[CoversClass]` for coverage.
+- Each test method should verify a single behavior.
+
+## Component Notes
+
+- Secrets are marshalled using implementations of `MarshallerInterface`.
+- Prefer domain-specific exceptions under `Exception/` when reporting errors.

src/SonsOfPHP/Component/Vault/Cipher/OpenSSLCipher.php

@@ -4,8 +4,10 @@
 
 namespace SonsOfPHP\Component\Vault\Cipher;
 
-use RuntimeException;
 use SensitiveParameter;
+use SonsOfPHP\Component\Vault\Exception\DecryptionFailedException;
+use SonsOfPHP\Component\Vault\Exception\EncryptionFailedException;
+use SonsOfPHP\Component\Vault\Exception\InvalidCiphertextException;
 
 /**
  * Encrypts and decrypts secrets using OpenSSL.
@@ -17,7 +19,11 @@ class OpenSSLCipher implements CipherInterface
      */
     public function __construct(private readonly string $cipherMethod = 'aes-256-gcm') {}
 
-    /** @param array<array-key, mixed> $aad */
+    /**
+     * @param array<array-key, mixed> $aad Additional authenticated data.
+     *
+     * @throws EncryptionFailedException
+     */
     public function encrypt(#[SensitiveParameter] string $plaintext, #[SensitiveParameter] string $key, array $aad = []): string
     {
         $ivLength   = openssl_cipher_iv_length($this->cipherMethod);
@@ -26,18 +32,23 @@ public function encrypt(#[SensitiveParameter] string $plaintext, #[SensitivePara
         $encodedAad = json_encode($aad);
         $encrypted  = openssl_encrypt($plaintext, $this->cipherMethod, $key, OPENSSL_RAW_DATA, $iv, $tag, $encodedAad, 16);
         if (false === $encrypted) {
-            throw new RuntimeException('Unable to encrypt secret.');
+            throw new EncryptionFailedException('Unable to encrypt secret.');
         }
 
         return base64_encode($iv . $tag . $encrypted);
     }
 
-    /** @param array<array-key, mixed> $aad */
+    /**
+     * @param array<array-key, mixed> $aad Additional authenticated data.
+     *
+     * @throws InvalidCiphertextException
+     * @throws DecryptionFailedException
+     */
     public function decrypt(#[SensitiveParameter] string $ciphertext, #[SensitiveParameter] string $key, array $aad = []): string
     {
         $data = base64_decode($ciphertext, true);
         if (false === $data) {
-            throw new RuntimeException('Invalid ciphertext.');
+            throw new InvalidCiphertextException('Invalid ciphertext.');
         }
 
         $ivLength  = openssl_cipher_iv_length($this->cipherMethod);
@@ -48,7 +59,7 @@ public function decrypt(#[SensitiveParameter] string $ciphertext, #[SensitivePar
         $encodedAad = json_encode($aad);
         $decrypted  = openssl_decrypt($payload, $this->cipherMethod, $key, OPENSSL_RAW_DATA, $iv, $tag, $encodedAad);
         if (false === $decrypted) {
-            throw new RuntimeException('Unable to decrypt secret.');
+            throw new DecryptionFailedException('Unable to decrypt secret.');
         }
 
         return $decrypted;

src/SonsOfPHP/Component/Vault/Exception/CipherException.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Component\Vault\Exception;
+
+/**
+ * Base exception for cipher related failures.
+ */
+class CipherException extends VaultException {}

src/SonsOfPHP/Component/Vault/Exception/DecryptionFailedException.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Component\Vault\Exception;
+
+/**
+ * Thrown when a value cannot be decrypted.
+ */
+class DecryptionFailedException extends CipherException {}

src/SonsOfPHP/Component/Vault/Exception/EncryptionFailedException.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Component\Vault\Exception;
+
+/**
+ * Thrown when a value cannot be encrypted.
+ */
+class EncryptionFailedException extends CipherException {}

src/SonsOfPHP/Component/Vault/Exception/InvalidCiphertextException.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Component\Vault\Exception;
+
+/**
+ * Thrown when ciphertext cannot be decoded before decryption.
+ */
+class InvalidCiphertextException extends CipherException {}

src/SonsOfPHP/Component/Vault/Exception/MarshallingException.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Component\Vault\Exception;
+
+/**
+ * Thrown when marshalling or unmarshalling secret data fails.
+ */
+class MarshallingException extends VaultException {}

src/SonsOfPHP/Component/Vault/Exception/SecretStorageCorruptedException.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Component\Vault\Exception;
+
+/**
+ * Thrown when the stored secret data is malformed or corrupted.
+ */
+class SecretStorageCorruptedException extends VaultException {}

src/SonsOfPHP/Component/Vault/Exception/UnknownKeyException.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Component\Vault\Exception;
+
+/**
+ * Thrown when a key cannot be found in the key ring.
+ */
+class UnknownKeyException extends VaultException {}