feat: add csrf protection through sec-fetch

Author: innocenzi

docs/1-essentials/01-routing.md

@@ -542,20 +542,33 @@ final readonly class ValidateWebhook implements HttpMiddleware
 { /* … */ }
 ```
 
+### Cross-site request forgery protection
+
+Tempest provides [cross-site request forgery](https://en.wikipedia.org/wiki/Cross-site_request_forgery) protection based on the presence and values of the [`{txt}Sec-Fetch-Site`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Site) and [`{txt}Sec-Fetch-Mode`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Mode) headers through the {b`Tempest\Router\PreventCrossSiteRequestsMiddleware`} middleware, included by default in all requests.
+
+Unlike traditional CSRF tokens, this approach uses browser-generated headers that cannot be forged by external websites:
+
+- [`{txt}Sec-Fetch-Site`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Site) indicates whether the request came from the same domain, subdomain, a different site or if it was user-initiated, such as typing the URL directly,
+- [`{txt}Sec-Fetch-Mode`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Mode) allows distinguishing between requests originating from a user navigating between HTML pages, and requests to load images and other resources.
+
+:::info
+This middleware requires browsers that support `{txt}Sec-Fetch-*` headers, which is the case for all modern browsers. You may [exclude this middleware](#excluding-route-middleware) and implement traditional CSRF protection using tokens if you need to support older browsers.
+:::
+
 ### Excluding route middleware
 
-Some routes do not require specific global middleware to be applied. For instance, API routes do not need CSRF protection. Specific middleware can be skipped by using the `without` argument of the route attribute.
+Some routes do not require specific global middleware to be applied. For instance, a publicly accessible health check endpoint could bypass rate limiting that's applied to other routes. Specific middleware can be skipped by using the `without` argument of the route attribute.
 
-```php app/Slack/ReceiveInteractionController.php
-use Tempest\Router\Post;
+```php app/HealthCheckController.php
+use Tempest\Router\Get;
 use Tempest\Http\Response;
 
-final readonly class ReceiveInteractionController
+final readonly class HealthCheckController
 {
-    #[Post('/slack/interaction', without: [VerifyCsrfMiddleware::class, SetCookieMiddleware::class])]
+    #[Get('/health', without: [RateLimitMiddleware::class])]
     public function __invoke(): Response
     {
-        // …
+        return new Ok(['status' => 'healthy']);
     }
 }
 ```
@@ -639,8 +652,9 @@ Explicitly removes middleware to all associated routes.
 ```php
 use Tempest\Router\WithoutMiddleware;
 use Tempest\Router\Get;
+use Tempest\Router\PreventCrossSiteRequestsMiddleware;
 
-#[WithoutMiddleware(VerifyCsrfMiddleware::class, SetCookieMiddleware::class)]
+#[WithoutMiddleware(PreventCrossSiteRequestsMiddleware::class)]
 final readonly class StatelessController { /* … */ }
 ```
 

packages/http/src/RequestHeaders.php

@@ -8,6 +8,7 @@
 use ArrayIterator;
 use IteratorAggregate;
 use LogicException;
+use Tempest\Support\Str;
 use Traversable;
 
 final readonly class RequestHeaders implements ArrayAccess, IteratorAggregate
@@ -17,11 +18,10 @@
      */
     public static function normalizeFromArray(array $headers): self
     {
-        $normalized = array_combine(
+        return new self(array_combine(
             array_map(strtolower(...), array_keys($headers)),
-            array_values($headers),
-        );
-        return new self($normalized);
+            array_values(array_map(fn (mixed $value) => Str\parse($value), $headers)),
+        ));
     }
 
     /** @param array<string, string> $headers */

packages/http/src/Session/TrackPreviousUrlMiddleware.php

@@ -12,12 +12,12 @@
 final readonly class TrackPreviousUrlMiddleware implements HttpMiddleware
 {
     public function __construct(
-        private PreviousUrl $previousUrlTracker,
+        private PreviousUrl $previousUrl,
     ) {}
 
     public function __invoke(Request $request, HttpMiddlewareCallable $next): Response
     {
-        $this->previousUrlTracker->track($request);
+        $this->previousUrl->track($request);
 
         return $next($request);
     }

packages/router/src/PreventCrossSiteRequestsMiddleware.php

@@ -0,0 +1,81 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Router;
+
+use Tempest\Core\Priority;
+use Tempest\Http\Method;
+use Tempest\Http\Request;
+use Tempest\Http\Response;
+use Tempest\Http\Responses\Forbidden;
+
+/**
+ * Protects against cross-site requests using `Sec-Fetch-*` headers. This is a modern equivalent of session token-based cross-site forgery protection.
+ *
+ * - Safe HTTP methods are always allowed
+ * - Requests from same-origin or same-site are allowed
+ * - Cross-site requests that aren't navigation are blocked
+ * - Requests without Sec-Fetch-Site headers are blocked
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Site
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Mode
+ * @see https://web.dev/articles/fetch-metadata
+ */
+#[Priority(Priority::FRAMEWORK - 8)]
+final readonly class PreventCrossSiteRequestsMiddleware implements HttpMiddleware
+{
+    private const array SAFE_METHODS = [
+        Method::GET,
+        Method::HEAD,
+        Method::OPTIONS,
+        Method::TRACE,
+    ];
+
+    public function __invoke(Request $request, HttpMiddlewareCallable $next): Response
+    {
+        if ($this->shouldValidate($request) && ! $this->isValidRequest($request)) {
+            return new Forbidden();
+        }
+
+        return $next($request);
+    }
+
+    /**
+     * Determines if the request should be validated for CSRF.
+     */
+    private function shouldValidate(Request $request): bool
+    {
+        if (in_array($request->method, self::SAFE_METHODS, strict: true)) {
+            return false;
+        }
+
+        return true;
+    }
+
+    /**
+     * Validates the request using `Sec-Fetch-*` headers.
+     */
+    private function isValidRequest(Request $request): bool
+    {
+        $secFetchSite = SecFetchSite::tryFrom($request->headers->get('sec-fetch-site') ?? '');
+        $secFetchMode = SecFetchMode::tryFrom($request->headers->get('sec-fetch-mode') ?? '');
+
+        // prevent the request if there is no `sec-fetch-site` header
+        if ($secFetchSite === null) {
+            return false;
+        }
+
+        // allow cross-site only on navigation requests
+        if ($secFetchSite === SecFetchSite::CROSS_SITE && $secFetchMode === SecFetchMode::NAVIGATE) {
+            return true;
+        }
+
+        // same origin, same site and user-originated requests are always allowed
+        if ($secFetchSite !== SecFetchSite::CROSS_SITE) {
+            return true;
+        }
+
+        return false;
+    }
+}

packages/router/src/SecFetchMode.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Router;
+
+/**
+ * Represents the Sec-Fetch-Mode header value.
+ *
+ * This header indicates the mode of the request.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Mode
+ */
+enum SecFetchMode: string
+{
+    /**
+     * The request is for navigation between HTML pages.
+     */
+    case NAVIGATE = 'navigate';
+
+    /**
+     * The request is for CORS-enabled requests.
+     */
+    case CORS = 'cors';
+
+    /**
+     * The request is for no-CORS requests.
+     */
+    case NO_CORS = 'no-cors';
+
+    /**
+     * The request is for same-origin requests.
+     */
+    case SAME_ORIGIN = 'same-origin';
+
+    /**
+     * The request is for WebSocket connections.
+     */
+    case WEBSOCKET = 'websocket';
+}

packages/router/src/SecFetchSite.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Router;
+
+/**
+ * Represents the `Sec-Fetch-Site` header value.
+ *
+ * This header indicates the relationship between a request initiator's origin
+ * and the origin of the resource being requested.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Site
+ */
+enum SecFetchSite: string
+{
+    /**
+     * The request was initiated from the same origin.
+     */
+    case SAME_ORIGIN = 'same-origin';
+
+    /**
+     * The request was initiated from a same-site but cross-origin context.
+     */
+    case SAME_SITE = 'same-site';
+
+    /**
+     * The request was initiated from a cross-site context.
+     */
+    case CROSS_SITE = 'cross-site';
+
+    /**
+     * The request was initiated in a user-initiated way (e.g., entering a URL in the address bar).
+     */
+    case NONE = 'none';
+}

packages/router/src/Stateless.php

@@ -15,6 +15,7 @@ public function decorate(Route $route): Route
     {
         $route->without = [
             ...$route->without,
+            PreventCrossSiteRequestsMiddleware::class,
             ManageSessionLifecycleMiddleware::class,
             SetCookieHeadersMiddleware::class,
         ];

src/Tempest/Framework/Testing/Http/HttpRouterTester.php

@@ -4,6 +4,7 @@
 
 namespace Tempest\Framework\Testing\Http;
 
+use BackedEnum;
 use Laminas\Diactoros\ServerRequestFactory;
 use Psr\Http\Message\ServerRequestInterface as PsrRequest;
 use Tempest\Container\Container;
@@ -14,6 +15,8 @@
 use Tempest\Http\Request;
 use Tempest\Router\Exceptions\HttpExceptionHandler;
 use Tempest\Router\Router;
+use Tempest\Router\SecFetchMode;
+use Tempest\Router\SecFetchSite;
 use Tempest\Support\Uri;
 use Throwable;
 
@@ -23,6 +26,8 @@ final class HttpRouterTester
 {
     private(set) ?ContentType $contentType = null;
 
+    private(set) bool $includeSecFetchHeaders = true;
+
     public function __construct(
         private Container $container,
     ) {}
@@ -37,6 +42,16 @@ public function as(ContentType $contentType): self
         return $this;
     }
 
+    /**
+     * Specifies that subsequent requests should be sent without Sec-Fetch headers.
+     */
+    public function withoutSecFetchHeaders(): self
+    {
+        $this->includeSecFetchHeaders = false;
+
+        return $this;
+    }
+
     public function get(string $uri, array $query = [], array $headers = []): TestResponseHelper
     {
         return $this->sendRequest(new GenericRequest(
@@ -162,8 +177,12 @@ public function makePsrRequest(
         $_SERVER['REQUEST_URI'] = $uri;
         $_SERVER['REQUEST_METHOD'] = $method->value;
 
-        foreach ($headers as $key => $value) {
-            $key = strtoupper($key);
+        foreach ($this->createHeaders($headers) as $key => $value) {
+            if ($value instanceof BackedEnum) {
+                $value = $value->value;
+            }
+
+            $key = strtoupper(str_replace('-', '_', $key));
 
             $_SERVER["HTTP_{$key}"] = $value;
         }
@@ -185,6 +204,16 @@ private function createHeaders(array $headers = []): array
             $headers[$key ?? 'accept'] = $this->contentType->value;
         }
 
+        if ($this->includeSecFetchHeaders === true) {
+            if (! array_key_exists('sec-fetch-site', array_change_key_case($headers, case: CASE_LOWER))) {
+                $headers['sec-fetch-site'] = SecFetchSite::SAME_ORIGIN;
+            }
+
+            if (! array_key_exists('sec-fetch-mode', array_change_key_case($headers, case: CASE_LOWER))) {
+                $headers['sec-fetch-mode'] = SecFetchMode::CORS;
+            }
+        }
+
         return $headers;
     }
 }

tests/Integration/Route/ClientTest.php

@@ -53,6 +53,8 @@ public function test_form_post_request(): void
             ->withHeader('Referer', 'http://localhost:8088/request-test/form')
             ->withHeader('Accept', 'application/json')
             ->withHeader('Content-Type', 'application/x-www-form-urlencoded')
+            ->withHeader('Sec-Fetch-Site', 'same-origin')
+            ->withHeader('Sec-Fetch-Mode', 'cors')
             ->withBody(new StreamFactory()->createStream('name=a a&b.name=b'));
 
         try {
@@ -72,6 +74,8 @@ public function test_json_post_request(): void
             ->createRequest('POST', new Uri('http://localhost:8088/request-test/form'))
             ->withHeader('Accept', 'application/json')
             ->withHeader('Content-Type', 'application/json')
+            ->withHeader('Sec-Fetch-Site', 'same-origin')
+            ->withHeader('Sec-Fetch-Mode', 'cors')
             ->withBody(new StreamFactory()->createStream('{"name": "a a", "b": {"name": "b"}}'));
 
         try {

tests/Integration/Route/RequestTest.php

@@ -85,7 +85,7 @@ public function test_from_factory(): void
         $this->assertEquals(Method::POST->value, $request->getMethod());
         $this->assertEquals('/test', $request->getUri()->getPath());
         $this->assertEquals(['test' => 'test'], $request->getParsedBody());
-        $this->assertEquals(['x-test' => ['test']], $request->getHeaders());
+        $this->assertArrayIsEqualToArrayIgnoringListOfKeys(['x-test' => ['test']], $request->getHeaders(), ['sec-fetch-site', 'sec-fetch-mode']);
         $this->assertCount(1, $request->getCookieParams());
         $this->assertArrayHasKey('test', $request->getCookieParams());
         $this->assertSame('test', $this->container->get(Encrypter::class)->decrypt($request->getCookieParams()['test']));