feat(http): add support to mark Request properties as #[SensitiveField] (#1746)

Co-authored-by: Brent Roose <[email protected]>

Author: xHeaven

docs/1-essentials/01-routing.md

@@ -387,6 +387,33 @@ final readonly class AirportController
 The `map()` function allows mapping any data from any source into objects of your choice. You may read more about them in [their documentation](../2-features/01-mapper.md).
 :::
 
+### Sensitive fields
+
+When handling sensitive data such as passwords or tokens, you may not want these values to be stored in the session or re-displayed in forms after validation errors. You can mark request properties as sensitive using the {b`#[Tempest\Http\SensitiveField]`} attribute:
+
+```php app/ResetPasswordRequest.php
+use Tempest\Http\Request;
+use Tempest\Http\IsRequest;
+use Tempest\Http\SensitiveField;
+use Tempest\Validation\Rules\HasMinLength;
+
+final class ResetPasswordRequest implements Request
+{
+    use IsRequest;
+
+    public string $email;
+
+    #[SensitiveField]
+    #[HasMinLength(8)]
+    public string $password;
+
+    #[SensitiveField]
+    public string $password_confirmation;
+}
+```
+
+When a validation error occurs, Tempest will filter out sensitive fields from the original values stored in the session. This prevents sensitive data from being re-populated in forms after a redirect.
+
 ### Retrieving data directly
 
 For simpler use cases, you may simply retrieve a value from the body or the query parameter using the request's `get` method.

packages/http/src/Mappers/RequestToObjectMapper.php

@@ -58,7 +58,8 @@ public function map(mixed $from, mixed $to): array|object
         $failingRules = $this->validator->validateValuesForClass($to, $data);
 
         if ($failingRules !== []) {
-            throw $this->validator->createValidationFailureException($failingRules, $from);
+            $targetClass = is_string($to) ? $to : $to::class;
+            throw $this->validator->createValidationFailureException($failingRules, $from, $targetClass);
         }
 
         return map($data)->with(ArrayToObjectMapper::class)->to($to);

packages/http/src/Responses/Invalid.php

@@ -7,8 +7,10 @@
 use Tempest\Http\IsResponse;
 use Tempest\Http\Request;
 use Tempest\Http\Response;
+use Tempest\Http\SensitiveField;
 use Tempest\Http\Session\Session;
 use Tempest\Http\Status;
+use Tempest\Reflection\ClassReflector;
 use Tempest\Support\Json;
 use Tempest\Validation\Rule;
 use Tempest\Validation\Validator;
@@ -24,10 +26,14 @@ final class Invalid implements Response
         get => get(Validator::class);
     }
 
+    /**
+     * @param class-string|null $targetClass
+     */
     public function __construct(
         Request $request,
         /** @var \Tempest\Validation\Rule[][] $failingRules */
         array $failingRules = [],
+        ?string $targetClass = null,
     ) {
         if ($referer = $request->headers['referer'] ?? null) {
             $this->addHeader('Location', $referer);
@@ -37,7 +43,7 @@ public function __construct(
         }
 
         $this->flash(Session::VALIDATION_ERRORS, $failingRules);
-        $this->flash(Session::ORIGINAL_VALUES, $request->body);
+        $this->flash(Session::ORIGINAL_VALUES, $this->filterSensitiveFields($request, $targetClass));
         $this->addHeader(
             'x-validation',
             Json\encode(
@@ -49,4 +55,26 @@ public function __construct(
             ),
         );
     }
+
+    /**
+     * @param class-string|null $targetClass
+     */
+    private function filterSensitiveFields(Request $request, ?string $targetClass): array
+    {
+        $body = $request->body;
+
+        if ($targetClass === null) {
+            return $body;
+        }
+
+        $reflector = new ClassReflector($targetClass);
+
+        foreach ($reflector->getPublicProperties() as $property) {
+            if ($property->hasAttribute(SensitiveField::class)) {
+                unset($body[$property->getName()]);
+            }
+        }
+
+        return $body;
+    }
 }

packages/http/src/SensitiveField.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Http;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+final class SensitiveField
+{
+}

packages/router/src/HandleRouteExceptionMiddleware.php

@@ -47,7 +47,7 @@ private function forward(Request $request, HttpMiddlewareCallable $next): Respon
         } catch (RouteBindingFailed) {
             return new NotFound();
         } catch (ValidationFailed $validationException) {
-            return new Invalid($validationException->subject, $validationException->failingRules);
+            return new Invalid($validationException->subject, $validationException->failingRules, $validationException->targetClass);
         }
     }
 }

packages/validation/src/Exceptions/ValidationFailed.php

@@ -14,11 +14,13 @@ final class ValidationFailed extends Exception
      *
      * @param array<TKey,Rule[]> $failingRules
      * @param array<TKey,string> $errorMessages
+     * @param class-string|null $targetClass
      */
     public function __construct(
         public readonly array $failingRules,
         public readonly null|object|string $subject = null,
         public readonly array $errorMessages = [],
+        public readonly ?string $targetClass = null,
     ) {
         parent::__construct(match (true) {
             is_null($subject) => 'Validation failed.',

packages/validation/src/Validator.php

@@ -56,12 +56,18 @@ public function validateObject(object $object): void
      * Creates a {@see ValidationFailed} exception from the given rule failures, populated with error messages.
      *
      * @param array<string,Rule[]> $failingRules
+     * @param class-string|null $targetClass
      */
-    public function createValidationFailureException(array $failingRules, null|object|string $subject = null): ValidationFailed
+    public function createValidationFailureException(array $failingRules, null|object|string $subject = null, ?string $targetClass = null): ValidationFailed
     {
-        return new ValidationFailed($failingRules, $subject, Arr\map_iterable($failingRules, function (array $rules, string $field) {
-            return Arr\map_iterable($rules, fn (Rule $rule) => $this->getErrorMessage($rule, $field));
-        }));
+        return new ValidationFailed(
+            $failingRules,
+            $subject,
+            Arr\map_iterable($failingRules, function (array $rules, string $field) {
+                return Arr\map_iterable($rules, fn (Rule $rule) => $this->getErrorMessage($rule, $field));
+            }),
+            $targetClass,
+        );
     }
 
     /**

tests/Fixtures/Controllers/ValidationController.php

@@ -12,6 +12,7 @@
 use Tempest\Router\Post;
 use Tests\Tempest\Fixtures\Modules\Books\Models\Book;
 use Tests\Tempest\Fixtures\Requests\BookRequest;
+use Tests\Tempest\Fixtures\Requests\SensitiveFieldRequest;
 use Tests\Tempest\Fixtures\Requests\ValidationRequest;
 
 use function Tempest\Router\uri;
@@ -30,6 +31,12 @@ public function store(ValidationRequest $request): Response
         return new Redirect(uri([self::class, 'get']));
     }
 
+    #[Post('/test-sensitive-validation')]
+    public function storeSensitive(SensitiveFieldRequest $request): Response
+    {
+        return new Redirect(uri([self::class, 'get']));
+    }
+
     #[Get(uri: '/test-validation-responses-json/{book}')]
     public function book(Book $book): Response
     {

tests/Fixtures/Requests/SensitiveFieldRequest.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Tempest\Fixtures\Requests;
+
+use Tempest\Http\IsRequest;
+use Tempest\Http\Request;
+use Tempest\Http\SensitiveField;
+use Tempest\Validation\Rules\IsNotEmptyString;
+
+final class SensitiveFieldRequest implements Request
+{
+    use IsRequest;
+
+    #[IsNotEmptyString]
+    public string $not_sensitive_param;
+
+    #[SensitiveField]
+    #[IsNotEmptyString]
+    public string $sensitive_param;
+}

tests/Integration/Http/ValidationResponseTest.php

@@ -102,4 +102,19 @@ public function test_failing_post_request(): void
 
         $this->assertSame('Timeline Taxi', Book::find(id: 1)->first()->title);
     }
+
+    public function test_sensitive_fields_are_excluded_from_original_values(): void
+    {
+        $this->http
+            ->post(
+                uri: uri([ValidationController::class, 'storeSensitive']),
+                body: ['not_sensitive_param' => '', 'sensitive_param' => 'secret123'],
+                headers: ['referer' => '/test-sensitive-validation'],
+            )
+            ->assertHasValidationError('not_sensitive_param')
+            ->assertHasSession(Session::ORIGINAL_VALUES, function (Session $_session, array $data): void {
+                $this->assertArrayNotHasKey('sensitive_param', $data);
+                $this->assertArrayHasKey('not_sensitive_param', $data);
+            });
+    }
 }