Merge release 1.17.0 into 2.0.x

phpstan-baseline.neon

@@ -18,6 +18,54 @@ parameters:
 			count: 1
 			path: src/Cryptography/PersonalDataPayloadCryptographer.php
 
+		-
+			message: '#^Offset ''k'' on array\{v\: 1, a\: non\-empty\-string, k\: non\-empty\-string, n\?\: non\-empty\-string, d\: non\-empty\-string, t\?\: non\-empty\-string\} on left side of \?\? always exists and is not nullable\.$#'
+			identifier: nullCoalesce.offset
+			count: 1
+			path: src/Extension/Cryptography/BaseCryptographer.php
+
+		-
+			message: '#^Parameter \#1 \$subjectId of callable Patchlevel\\Hydrator\\Extension\\Cryptography\\Cipher\\CipherKeyFactory expects non\-empty\-string, string given\.$#'
+			identifier: argument.type
+			count: 1
+			path: src/Extension/Cryptography/BaseCryptographer.php
+
+		-
+			message: '#^Strict comparison using \=\=\= between non\-empty\-string and null will always evaluate to false\.$#'
+			identifier: identical.alwaysFalse
+			count: 1
+			path: src/Extension/Cryptography/BaseCryptographer.php
+
+		-
+			message: '#^Parameter \#1 \$data of class Patchlevel\\Hydrator\\Extension\\Cryptography\\Cipher\\EncryptedData constructor expects non\-empty\-string, string given\.$#'
+			identifier: argument.type
+			count: 1
+			path: src/Extension/Cryptography/Cipher/OpensslCipher.php
+
+		-
+			message: '#^Parameter \#1 \$data of function openssl_decrypt expects string, string\|false given\.$#'
+			identifier: argument.type
+			count: 1
+			path: src/Extension/Cryptography/Cipher/OpensslCipher.php
+
+		-
+			message: '#^Parameter \#3 \$nonce of class Patchlevel\\Hydrator\\Extension\\Cryptography\\Cipher\\EncryptedData constructor expects non\-empty\-string\|null, string\|null given\.$#'
+			identifier: argument.type
+			count: 1
+			path: src/Extension/Cryptography/Cipher/OpensslCipher.php
+
+		-
+			message: '#^Parameter \#1 \$id of class Patchlevel\\Hydrator\\Extension\\Cryptography\\Cipher\\CipherKey constructor expects non\-empty\-string, string given\.$#'
+			identifier: argument.type
+			count: 1
+			path: src/Extension/Cryptography/Cipher/OpensslCipherKeyFactory.php
+
+		-
+			message: '#^Parameter \#3 \$key of class Patchlevel\\Hydrator\\Extension\\Cryptography\\Cipher\\CipherKey constructor expects non\-empty\-string, string given\.$#'
+			identifier: argument.type
+			count: 1
+			path: src/Extension/Cryptography/Cipher/OpensslCipherKeyFactory.php
+
 		-
 			message: '#^Method Patchlevel\\Hydrator\\Guesser\\BuiltInGuesser\:\:guess\(\) has parameter \$type with generic class Symfony\\Component\\TypeInfo\\Type\\ObjectType but does not specify its types\: T$#'
 			identifier: missingType.generics
@@ -67,31 +115,31 @@ parameters:
 			path: src/Metadata/AttributeMetadataFactory.php
 
 		-
-			message: '#^Property Patchlevel\\Hydrator\\Metadata\\ClassMetadata\<T of object \= object\>\:\:\$reflection \(ReflectionClass\<T of object \= object\>\) does not accept ReflectionClass\<object\>\.$#'
+			message: '#^Property Patchlevel\\Hydrator\\Normalizer\\EnumNormalizer\:\:\$enum \(class\-string\<BackedEnum\>\|null\) does not accept string\.$#'
 			identifier: assign.propertyType
 			count: 1
-			path: src/Metadata/ClassMetadata.php
+			path: src/Normalizer/EnumNormalizer.php
 
 		-
-			message: '#^Dead catch \- Patchlevel\\Hydrator\\CircularReference is never thrown in the try block\.$#'
-			identifier: catch.neverThrown
+			message: '#^Parameter \#2 \$data of method Patchlevel\\Hydrator\\Hydrator\:\:hydrate\(\) expects array\<string, mixed\>, array given\.$#'
+			identifier: argument.type
 			count: 1
-			path: src/MetadataHydrator.php
+			path: src/Normalizer/ObjectMapNormalizer.php
 
 		-
-			message: '#^Property Patchlevel\\Hydrator\\Normalizer\\EnumNormalizer\:\:\$enum \(class\-string\<BackedEnum\>\|null\) does not accept string\.$#'
-			identifier: assign.propertyType
+			message: '#^Parameter \#2 \$data of method Patchlevel\\Hydrator\\HydratorWithContext\:\:hydrate\(\) expects array\<string, mixed\>, array given\.$#'
+			identifier: argument.type
 			count: 1
-			path: src/Normalizer/EnumNormalizer.php
+			path: src/Normalizer/ObjectMapNormalizer.php
 
 		-
-			message: '#^Parameter \#2 \$data of method Patchlevel\\Hydrator\\Hydrator\:\:hydrate\(\) expects array\<string, mixed\>, array given\.$#'
+			message: '#^Parameter \#2 \$data of method Patchlevel\\Hydrator\\Hydrator\:\:hydrate\(\) expects array\<string, mixed\>, array\<mixed, mixed\> given\.$#'
 			identifier: argument.type
 			count: 1
-			path: src/Normalizer/ObjectMapNormalizer.php
+			path: src/Normalizer/ObjectNormalizer.php
 
 		-
-			message: '#^Parameter \#2 \$data of method Patchlevel\\Hydrator\\Hydrator\:\:hydrate\(\) expects array\<string, mixed\>, array\<mixed, mixed\> given\.$#'
+			message: '#^Parameter \#2 \$data of method Patchlevel\\Hydrator\\HydratorWithContext\:\:hydrate\(\) expects array\<string, mixed\>, array\<mixed, mixed\> given\.$#'
 			identifier: argument.type
 			count: 1
 			path: src/Normalizer/ObjectNormalizer.php
@@ -108,6 +156,12 @@ parameters:
 			count: 1
 			path: src/Normalizer/ReflectionTypeUtil.php
 
+		-
+			message: '#^Property Patchlevel\\Hydrator\\Tests\\Unit\\Extension\\Cryptography\\Fixture\\ChildWithSensitiveDataWithIdentifierDto\:\:\$email is never read, only written\.$#'
+			identifier: property.onlyWritten
+			count: 1
+			path: tests/Unit/Extension/Cryptography/Fixture/ChildWithSensitiveDataWithIdentifierDto.php
+
 		-
 			message: '#^Method Patchlevel\\Hydrator\\Tests\\Unit\\Fixture\\DtoWithHooks\:\:postHydrate\(\) is unused\.$#'
 			identifier: method.unused
@@ -179,3 +233,9 @@ parameters:
 			identifier: cast.string
 			count: 2
 			path: tests/Unit/Normalizer/ArrayShapeNormalizerTest.php
+
+		-
+			message: '#^Parameter \#1 \$class of method Patchlevel\\Hydrator\\StackHydrator\:\:hydrate\(\) expects class\-string\<Unknown\>, string given\.$#'
+			identifier: argument.type
+			count: 1
+			path: tests/Unit/StackHydratorTest.php

src/CoreExtension.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator;
+
+use Patchlevel\Hydrator\Guesser\BuiltInGuesser;
+use Patchlevel\Hydrator\Middleware\TransformMiddleware;
+
+/** @experimental */
+final class CoreExtension implements Extension
+{
+    public function configure(StackHydratorBuilder $builder): void
+    {
+        $builder->addMiddleware(new TransformMiddleware(), -64);
+        $builder->addGuesser(new BuiltInGuesser(), -64);
+    }
+}

src/Extension.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator;
+
+/** @experimental */
+interface Extension
+{
+    public function configure(StackHydratorBuilder $builder): void;
+}

src/Extension/Cryptography/Attribute/DataSubjectId.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator\Extension\Cryptography\Attribute;
+
+use Attribute;
+
+/** @experimental */
+#[Attribute(Attribute::TARGET_PROPERTY)]
+final class DataSubjectId
+{
+    public function __construct(
+        public readonly string $name = 'default',
+    ) {
+    }
+}

src/Extension/Cryptography/Attribute/SensitiveData.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator\Extension\Cryptography\Attribute;
+
+use Attribute;
+use InvalidArgumentException;
+
+/** @experimental */
+#[Attribute(Attribute::TARGET_PROPERTY)]
+final class SensitiveData
+{
+    /** @var (callable(string):mixed)|null */
+    public readonly mixed $fallbackCallable;
+
+    public function __construct(
+        public readonly mixed $fallback = null,
+        callable|null $fallbackCallable = null,
+        public readonly string $subjectIdName = 'default',
+    ) {
+        $this->fallbackCallable = $fallbackCallable;
+
+        if ($this->fallbackCallable !== null && $this->fallback !== null) {
+            throw new InvalidArgumentException('You can only set one of fallback or fallbackCallable');
+        }
+    }
+}

src/Extension/Cryptography/BaseCryptographer.php

@@ -0,0 +1,125 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator\Extension\Cryptography;
+
+use Patchlevel\Hydrator\Extension\Cryptography\Cipher\Cipher;
+use Patchlevel\Hydrator\Extension\Cryptography\Cipher\CipherKeyFactory;
+use Patchlevel\Hydrator\Extension\Cryptography\Cipher\DecryptionFailed;
+use Patchlevel\Hydrator\Extension\Cryptography\Cipher\EncryptedData;
+use Patchlevel\Hydrator\Extension\Cryptography\Cipher\EncryptionFailed;
+use Patchlevel\Hydrator\Extension\Cryptography\Cipher\OpensslCipher;
+use Patchlevel\Hydrator\Extension\Cryptography\Cipher\OpensslCipherKeyFactory;
+use Patchlevel\Hydrator\Extension\Cryptography\Store\CipherKeyNotExists;
+use Patchlevel\Hydrator\Extension\Cryptography\Store\CipherKeyStore;
+
+use function is_array;
+
+/**
+ * @experimental
+ * @phpstan-type EncryptedDataArray array{
+ *   v: 1,
+ *   a: non-empty-string,
+ *   k: non-empty-string,
+ *   n?: non-empty-string,      // base64
+ *   d: non-empty-string,        // base64 ciphertext
+ *   t?: non-empty-string,       // base64 (for AEAD)
+ * }
+ */
+final class BaseCryptographer implements Cryptographer
+{
+    private const VERSION_KEY = 'v';
+    private const METHOD_KEY = 'a';
+    private const KEY_ID_KEY = 'k';
+    private const NONCE_KEY = 'n';
+    private const DATA_KEY = 'd';
+    private const TAG_KEY = 't';
+
+    public function __construct(
+        private readonly Cipher $cipher,
+        private readonly CipherKeyStore $cipherKeyStore,
+        private readonly CipherKeyFactory $cipherKeyFactory,
+    ) {
+    }
+
+    /**
+     * @return EncryptedDataArray
+     *
+     * @throws EncryptionFailed
+     */
+    public function encrypt(string $subjectId, mixed $value): array
+    {
+        try {
+            $cipherKey = $this->cipherKeyStore->currentKeyFor($subjectId);
+        } catch (CipherKeyNotExists) {
+            $cipherKey = ($this->cipherKeyFactory)($subjectId);
+            $this->cipherKeyStore->store($cipherKey->id, $cipherKey);
+        }
+
+        $parameter = $this->cipher->encrypt($cipherKey, $value);
+
+        $result = [
+            self::VERSION_KEY => 1,
+            self::METHOD_KEY => $parameter->method,
+            self::KEY_ID_KEY => $cipherKey->id,
+            self::DATA_KEY => $parameter->data,
+        ];
+
+        if ($parameter->nonce !== null) {
+            $result[self::NONCE_KEY] = $parameter->nonce;
+        }
+
+        if ($parameter->tag !== null) {
+            $result[self::TAG_KEY] = $parameter->tag;
+        }
+
+        return $result;
+    }
+
+    /**
+     * @param EncryptedDataArray $encryptedData
+     *
+     * @throws CipherKeyNotExists
+     * @throws DecryptionFailed
+     */
+    public function decrypt(string $subjectId, mixed $encryptedData): mixed
+    {
+        $keyId = $encryptedData[self::KEY_ID_KEY] ?? null;
+
+        if ($keyId === null) {
+            throw DecryptionFailed::missingKeyId();
+        }
+
+        $cipherKey = $this->cipherKeyStore->get($keyId);
+
+        return $this->cipher->decrypt(
+            $cipherKey,
+            new EncryptedData(
+                $encryptedData[self::DATA_KEY],
+                $encryptedData[self::METHOD_KEY],
+                $encryptedData[self::NONCE_KEY] ?? null,
+                $encryptedData[self::TAG_KEY] ?? null,
+            ),
+        );
+    }
+
+    public function supports(mixed $value): bool
+    {
+        return is_array($value)
+            && isset($value[self::VERSION_KEY], $value[self::METHOD_KEY], $value[self::KEY_ID_KEY], $value[self::DATA_KEY])
+            && $value[self::VERSION_KEY] === 1;
+    }
+
+    /** @param non-empty-string $method */
+    public static function createWithOpenssl(
+        CipherKeyStore $cryptoStore,
+        string $method = OpensslCipherKeyFactory::DEFAULT_METHOD,
+    ): static {
+        return new self(
+            new OpensslCipher(),
+            $cryptoStore,
+            new OpensslCipherKeyFactory($method),
+        );
+    }
+}

src/Extension/Cryptography/Cipher/Cipher.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator\Extension\Cryptography\Cipher;
+
+/** @experimental */
+interface Cipher
+{
+    /** @throws EncryptionFailed */
+    public function encrypt(CipherKey $key, mixed $data): EncryptedData;
+
+    /** @throws DecryptionFailed */
+    public function decrypt(CipherKey $key, EncryptedData $parameter): mixed;
+}

src/Extension/Cryptography/Cipher/CipherKey.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator\Extension\Cryptography\Cipher;
+
+use DateTimeImmutable;
+use SensitiveParameter;
+
+/** @experimental */
+final class CipherKey
+{
+    /**
+     * @param non-empty-string $id
+     * @param non-empty-string $subjectId
+     * @param non-empty-string $key
+     * @param non-empty-string $method
+     */
+    public function __construct(
+        public readonly string $id,
+        public readonly string $subjectId,
+        #[SensitiveParameter]
+        public readonly string $key,
+        public readonly string $method,
+        public readonly DateTimeImmutable $createdAt,
+    ) {
+    }
+}

src/Extension/Cryptography/Cipher/CipherKeyFactory.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator\Extension\Cryptography\Cipher;
+
+/** @experimental */
+interface CipherKeyFactory
+{
+    /**
+     * @param non-empty-string $subjectId
+     *
+     * @throws CreateCipherKeyFailed
+     */
+    public function __invoke(string $subjectId): CipherKey;
+}