feat(vault): add key ring and secret versioning

Author: JoshuaEstes

docs/components/vault.md

@@ -6,13 +6,18 @@ The Vault component securely stores secrets using pluggable storage backends and
 
 ```php
 use SonsOfPHP\Component\Vault\Cipher\OpenSSLCipher;
+use SonsOfPHP\Component\Vault\KeyRing\InMemoryKeyRing;
 use SonsOfPHP\Component\Vault\Storage\InMemoryStorage;
 use SonsOfPHP\Component\Vault\Vault;
 
-$keys  = ['v1' => '32_byte_master_key_example!!'];
-$vault = new Vault(new InMemoryStorage(), new OpenSSLCipher(), $keys, 'v1');
-$vault->set('db_password', 'secret', 'app');
-$secret = $vault->get('db_password', 'app');
+$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']);
+
+// Store a new version of the secret
+$vault->set('db_password', 'new-secret', ['app']);
+$oldSecret = $vault->get('db_password', ['app'], 1); // retrieve version 1
 
 // Rotate the master key
 $vault->rotateKey('v2', 'another_32_byte_master_key!!');

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

@@ -4,18 +4,24 @@
 
 namespace SonsOfPHP\Component\Vault\Cipher;
 
+use SensitiveParameter;
+
 /**
  * Defines methods for encrypting and decrypting secrets.
  */
 interface CipherInterface
 {
     /**
      * Encrypts plaintext using the provided key and optional authenticated data.
+     *
+     * @param array<array-key, mixed> $aad Additional authenticated data.
      */
-    public function encrypt(string $plaintext, string $key, string $aad = ''): string;
+    public function encrypt(#[SensitiveParameter] string $plaintext, #[SensitiveParameter] string $key, array $aad = []): string;
 
     /**
      * Decrypts ciphertext using the provided key and optional authenticated data.
+     *
+     * @param array<array-key, mixed> $aad Additional authenticated data.
      */
-    public function decrypt(string $ciphertext, string $key, string $aad = ''): string;
+    public function decrypt(#[SensitiveParameter] string $ciphertext, #[SensitiveParameter] string $key, array $aad = []): string;
 }

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

@@ -5,6 +5,7 @@
 namespace SonsOfPHP\Component\Vault\Cipher;
 
 use RuntimeException;
+use SensitiveParameter;
 
 /**
  * Encrypts and decrypts secrets using OpenSSL.
@@ -16,20 +17,23 @@ class OpenSSLCipher implements CipherInterface
      */
     public function __construct(private readonly string $cipherMethod = 'aes-256-gcm') {}
 
-    public function encrypt(string $plaintext, string $key, string $aad = ''): string
+    /** @param array<array-key, mixed> $aad */
+    public function encrypt(#[SensitiveParameter] string $plaintext, #[SensitiveParameter] string $key, array $aad = []): string
     {
-        $ivLength = openssl_cipher_iv_length($this->cipherMethod);
-        $iv       = random_bytes($ivLength);
-        $tag      = '';
-        $encrypted = openssl_encrypt($plaintext, $this->cipherMethod, $key, OPENSSL_RAW_DATA, $iv, $tag, $aad, 16);
+        $ivLength   = openssl_cipher_iv_length($this->cipherMethod);
+        $iv         = random_bytes($ivLength);
+        $tag        = '';
+        $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.');
         }
 
         return base64_encode($iv . $tag . $encrypted);
     }
 
-    public function decrypt(string $ciphertext, string $key, string $aad = ''): string
+    /** @param array<array-key, mixed> $aad */
+    public function decrypt(#[SensitiveParameter] string $ciphertext, #[SensitiveParameter] string $key, array $aad = []): string
     {
         $data = base64_decode($ciphertext, true);
         if (false === $data) {
@@ -38,10 +42,11 @@ public function decrypt(string $ciphertext, string $key, string $aad = ''): stri
 
         $ivLength  = openssl_cipher_iv_length($this->cipherMethod);
         $tagLength = 16;
-        $iv        = substr($data, 0, $ivLength);
-        $tag       = substr($data, $ivLength, $tagLength);
-        $payload   = substr($data, $ivLength + $tagLength);
-        $decrypted = openssl_decrypt($payload, $this->cipherMethod, $key, OPENSSL_RAW_DATA, $iv, $tag, $aad);
+        $iv         = substr($data, 0, $ivLength);
+        $tag        = substr($data, $ivLength, $tagLength);
+        $payload    = substr($data, $ivLength + $tagLength);
+        $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.');
         }

src/SonsOfPHP/Component/Vault/KeyRing/InMemoryKeyRing.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Component\Vault\KeyRing;
+
+use SensitiveParameter;
+
+/**
+ * Simple key ring that keeps keys in memory.
+ */
+class InMemoryKeyRing implements KeyRingInterface
+{
+    /**
+     * @param array<string, string> $keys Map of key IDs to keys.
+     * @param string                $currentKeyId Identifier of the active key.
+     */
+    public function __construct(private array $keys, private string $currentKeyId) {}
+
+    public function getCurrentKeyId(): string
+    {
+        return $this->currentKeyId;
+    }
+
+    public function getCurrentKey(): string
+    {
+        return $this->keys[$this->currentKeyId];
+    }
+
+    public function getKey(string $keyId): ?string
+    {
+        return $this->keys[$keyId] ?? null;
+    }
+
+    public function rotate(string $keyId, #[SensitiveParameter] string $key): void
+    {
+        $this->keys[$keyId] = $key;
+        $this->currentKeyId = $keyId;
+    }
+}

src/SonsOfPHP/Component/Vault/KeyRing/KeyRingInterface.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Component\Vault\KeyRing;
+
+use SensitiveParameter;
+
+/**
+ * Manages encryption keys and their versions.
+ */
+interface KeyRingInterface
+{
+    /**
+     * Returns the identifier for the current key.
+     */
+    public function getCurrentKeyId(): string;
+
+    /**
+     * Returns the current encryption key.
+     */
+    public function getCurrentKey(): string;
+
+    /**
+     * Fetches a key by its identifier or null if missing.
+     */
+    public function getKey(string $keyId): ?string;
+
+    /**
+     * Rotates to a new key and sets it as current.
+     */
+    public function rotate(string $keyId, #[SensitiveParameter] string $key): void;
+}

src/SonsOfPHP/Component/Vault/README.md

@@ -1,7 +1,7 @@
 Sons of PHP - Vault
 ===================
 
-Secure secret storage with pluggable backends, key rotation, and support for additional authenticated data.
+Secure secret storage with pluggable backends, key rotation, secret versioning, and support for additional authenticated data.
 
 ## Learn More
 

src/SonsOfPHP/Component/Vault/ROADMAP.md

@@ -23,13 +23,6 @@
   - Redis adapter encrypts secrets and handles expirations.
   - Implementation meets the Global DoD.
 
-### Add secret versioning
-- [ ] Provide APIs to maintain secret history across updates.
-- **Acceptance Criteria**
-  - All Global DoR items are satisfied before implementation begins.
-  - Previous versions of a secret remain accessible.
-  - Implementation meets the Global DoD.
-
 ### Provide CLI tools for managing secrets
 - [ ] Expose commands to set, get, and rotate secrets.
 - **Acceptance Criteria**

src/SonsOfPHP/Component/Vault/Tests/VaultTest.php

@@ -7,6 +7,7 @@
 use PHPUnit\Framework\TestCase;
 use RuntimeException;
 use SonsOfPHP\Component\Vault\Cipher\OpenSSLCipher;
+use SonsOfPHP\Component\Vault\KeyRing\InMemoryKeyRing;
 use SonsOfPHP\Component\Vault\Storage\InMemoryStorage;
 use SonsOfPHP\Component\Vault\Vault;
 
@@ -23,9 +24,9 @@ private function createVault(?InMemoryStorage &$storage = null): Vault
     {
         $storage ??= new InMemoryStorage();
         $cipher  = new OpenSSLCipher();
-        $keys    = ['v1' => 'test_encryption_key_32_bytes!'];
+        $keyRing = new InMemoryKeyRing(['v1' => 'test_encryption_key_32_bytes!'], 'v1');
 
-        return new Vault($storage, $cipher, $keys, 'v1');
+        return new Vault($storage, $cipher, $keyRing);
     }
 
     public function testSecretCanBeRetrieved(): void
@@ -63,18 +64,18 @@ public function testSetAndGetWithArray(): void
     public function testSetAndGetWithAad(): void
     {
         $vault = $this->createVault();
-        $vault->set('token', 'secret', 'aad');
+        $vault->set('token', 'secret', ['aad']);
 
-        $this->assertSame('secret', $vault->get('token', 'aad'));
+        $this->assertSame('secret', $vault->get('token', ['aad']));
     }
 
     public function testGetThrowsWhenAadDoesNotMatch(): void
     {
         $vault = $this->createVault();
-        $vault->set('token', 'secret', 'aad');
+        $vault->set('token', 'secret', ['aad']);
 
         $this->expectException(RuntimeException::class);
-        $vault->get('token', 'bad');
+        $vault->get('token', ['bad']);
     }
 
     public function testSecretsEncryptedBeforeRotationAreStillAccessible(): void
@@ -93,6 +94,26 @@ public function testRotateKeyChangesActiveKey(): void
         $vault->rotateKey('v2', 'another_32_byte_encryption_key!!');
         $vault->set('current', 'secret');
 
-        $this->assertStringStartsWith('v2:', $storage->get('current'));
+        $stored   = $storage->get('current');
+        $versions = unserialize($stored, ['allowed_classes' => false]);
+        $this->assertStringStartsWith('v2:', $versions['1']);
+    }
+
+    public function testGetReturnsLatestVersion(): void
+    {
+        $vault = $this->createVault();
+        $vault->set('name', 'first');
+        $vault->set('name', 'second');
+
+        $this->assertSame('second', $vault->get('name'));
+    }
+
+    public function testSpecificVersionCanBeRetrieved(): void
+    {
+        $vault = $this->createVault();
+        $vault->set('name', 'first');
+        $vault->set('name', 'second');
+
+        $this->assertSame('first', $vault->get('name', [], 1));
     }
 }

src/SonsOfPHP/Component/Vault/Vault.php

@@ -5,7 +5,9 @@
 namespace SonsOfPHP\Component\Vault;
 
 use RuntimeException;
+use SensitiveParameter;
 use SonsOfPHP\Component\Vault\Cipher\CipherInterface;
+use SonsOfPHP\Component\Vault\KeyRing\KeyRingInterface;
 use SonsOfPHP\Component\Vault\Storage\StorageInterface;
 
 /**
@@ -15,47 +17,72 @@
 class Vault
 {
     /**
-     * @param StorageInterface       $storage       The storage backend.
-     * @param CipherInterface        $cipher        The cipher used for encryption.
-     * @param array<string,string>   $keys          Map of key IDs to encryption keys.
-     * @param string                 $currentKeyId  Identifier of the active key.
+     * @param StorageInterface $storage The storage backend.
+     * @param CipherInterface  $cipher  The cipher used for encryption.
+     * @param KeyRingInterface $keyRing Provides access to encryption keys.
      */
-    public function __construct(private readonly StorageInterface $storage, private readonly CipherInterface $cipher, private array $keys, private string $currentKeyId)
-    {
-    }
+    public function __construct(private readonly StorageInterface $storage, private readonly CipherInterface $cipher, private readonly KeyRingInterface $keyRing) {}
 
     /**
      * Stores a secret in the vault.
      *
-     * @param string $name  Identifier of the secret.
-     * @param mixed  $secret The secret to store.
-     * @param string $aad   Additional authenticated data.
+     * @param string                   $name   Identifier of the secret.
+     * @param mixed                    $secret The secret to store.
+     * @param array<array-key, mixed>  $aad    Additional authenticated data.
      */
-    public function set(string $name, mixed $secret, string $aad = ''): void
+    public function set(string $name, #[SensitiveParameter] mixed $secret, array $aad = []): void
     {
         $serialized = serialize($secret);
-        $key        = $this->keys[$this->currentKeyId];
+        $key        = $this->keyRing->getCurrentKey();
         $encrypted  = $this->cipher->encrypt($serialized, $key, $aad);
-        $this->storage->set($name, $this->currentKeyId . ':' . $encrypted);
+
+        $record = $this->storage->get($name);
+        if (null === $record) {
+            $versions = [];
+        } else {
+            $versions = @unserialize($record, ['allowed_classes' => false]);
+            if (!is_array($versions)) {
+                throw new RuntimeException('Invalid secret storage format.');
+            }
+        }
+
+        $version                     = $versions === [] ? 1 : max(array_map('intval', array_keys($versions))) + 1;
+        $versions[(string) $version] = $this->keyRing->getCurrentKeyId() . ':' . $encrypted;
+        $this->storage->set($name, serialize($versions));
     }
 
     /**
      * Retrieves a secret from the vault or null if it does not exist.
      *
-     * @param string $name Identifier of the secret.
-     * @param string $aad  Additional authenticated data.
+     * @param string                  $name    Identifier of the secret.
+     * @param array<array-key, mixed> $aad     Additional authenticated data.
+     * @param int|null                $version Specific version to retrieve or null for latest.
      *
      * @return mixed|null
      */
-    public function get(string $name, string $aad = ''): mixed
+    public function get(string $name, array $aad = [], ?int $version = null): mixed
     {
         $record = $this->storage->get($name);
         if (null === $record) {
             return null;
         }
 
-        [$keyId, $ciphertext] = explode(':', $record, 2);
-        $key = $this->keys[$keyId] ?? null;
+        $versions = @unserialize($record, ['allowed_classes' => false]);
+        if (!is_array($versions)) {
+            throw new RuntimeException('Invalid secret storage format.');
+        }
+
+        if (null === $version) {
+            $version = (int) max(array_map('intval', array_keys($versions)));
+        }
+
+        $entry = $versions[(string) $version] ?? null;
+        if (null === $entry) {
+            return null;
+        }
+
+        [$keyId, $ciphertext] = explode(':', (string) $entry, 2);
+        $key                   = $this->keyRing->getKey($keyId);
         if (null === $key) {
             throw new RuntimeException('Unknown key identifier.');
         }
@@ -84,9 +111,8 @@ public function delete(string $name): void
      * @param string $keyId Identifier for the new key.
      * @param string $key   The new encryption key.
      */
-    public function rotateKey(string $keyId, string $key): void
+    public function rotateKey(string $keyId, #[SensitiveParameter] string $key): void
     {
-        $this->keys[$keyId] = $key;
-        $this->currentKeyId = $keyId;
+        $this->keyRing->rotate($keyId, $key);
     }
 }