[BUGFIX] Skip cHash validation for API query arguments

Classes/Middleware/T3apiPageArgumentsRestorer.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SourceBroker\T3api\Middleware;
+
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\MiddlewareInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+use TYPO3\CMS\Core\Routing\PageArguments;
+
+/**
+ * Restores page arguments replaced by T3apiPageArgumentsValidationBypass once TYPO3's
+ * PageArgumentValidator has run.
+ */
+class T3apiPageArgumentsRestorer implements MiddlewareInterface
+{
+    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
+    {
+        $originalPageArguments = $request->getAttribute(T3apiPageArgumentsValidationBypass::ORIGINAL_ROUTING_ATTRIBUTE);
+
+        if ($originalPageArguments instanceof PageArguments) {
+            $request = $request
+                ->withAttribute('routing', $originalPageArguments)
+                ->withoutAttribute(T3apiPageArgumentsValidationBypass::ORIGINAL_ROUTING_ATTRIBUTE);
+        }
+
+        return $handler->handle($request);
+    }
+}

Classes/Middleware/T3apiPageArgumentsValidationBypass.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SourceBroker\T3api\Middleware;
+
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\MiddlewareInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+use SourceBroker\T3api\Routing\Enhancer\ResourceEnhancer;
+use TYPO3\CMS\Core\Routing\PageArguments;
+
+/**
+ * API requests carry query arguments (filters, pagination, ordering) which are not page arguments
+ * and are never signed with a cHash. With `cacheHash.enforceValidation` enabled, TYPO3's
+ * PageArgumentValidator would answer such requests with 404 "&cHash empty". Excluding the API
+ * arguments globally via `cacheHash.excludedParameters` is not an option, as it would also affect
+ * regular pages (e.g. a `page` argument of a plugin).
+ *
+ * This middleware runs right before PageArgumentValidator and, for API requests only, hands it
+ * page arguments without query arguments and with the route arguments (`t3apiResource`) marked as
+ * static, so there is nothing left to validate. T3apiPageArgumentsRestorer (right after the validator)
+ * puts the original page arguments back, so all following middlewares see the unchanged request.
+ */
+class T3apiPageArgumentsValidationBypass implements MiddlewareInterface
+{
+    public const ORIGINAL_ROUTING_ATTRIBUTE = 't3api.originalRouting';
+
+    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
+    {
+        $pageArguments = $request->getAttribute('routing');
+
+        if (
+            $pageArguments instanceof PageArguments
+            && array_key_exists(ResourceEnhancer::PARAMETER_NAME, $pageArguments->getRouteArguments())
+        ) {
+            $request = $request
+                ->withAttribute(self::ORIGINAL_ROUTING_ATTRIBUTE, $pageArguments)
+                ->withAttribute('routing', new PageArguments(
+                    $pageArguments->getPageId(),
+                    $pageArguments->getPageType(),
+                    $pageArguments->getRouteArguments(),
+                    array_replace($pageArguments->getStaticArguments(), $pageArguments->getRouteArguments())
+                ));
+        }
+
+        return $handler->handle($request);
+    }
+}

Configuration/RequestMiddlewares.php

@@ -14,6 +14,28 @@
             'typo3/cms-frontend/shortcut-and-mountpoint-redirect',
         ],
     ],
+    // Keeps API query arguments (filters, pagination) away from cHash validation, see class docblock.
+    'sourcebroker/t3api/page-arguments-validation-bypass' => [
+        'target' => \SourceBroker\T3api\Middleware\T3apiPageArgumentsValidationBypass::class,
+        'after' => [
+            'typo3/cms-frontend/page-resolver',
+        ],
+        'before' => [
+            'typo3/cms-frontend/page-argument-validator',
+        ],
+    ],
+    'sourcebroker/t3api/page-arguments-restorer' => [
+        'target' => \SourceBroker\T3api\Middleware\T3apiPageArgumentsRestorer::class,
+        'after' => [
+            'typo3/cms-frontend/page-argument-validator',
+        ],
+        'before' => [
+            // `typo3/cms-frontend/tsfe` (directly after the validator) does not exist since TYPO3 v14
+            (new Typo3Version())->getMajorVersion() < 14
+                ? 'typo3/cms-frontend/tsfe'
+                : 'typo3/cms-frontend/prepare-tsfe-rendering',
+        ],
+    ],
 ];
 
 // Only required on TYPO3 v12: applies the X-Locale-style header language override before TSFE

Tests/Unit/Middleware/T3apiPageArgumentsValidationBypassTest.php

@@ -0,0 +1,94 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SourceBroker\T3api\Tests\Unit\Middleware;
+
+use PHPUnit\Framework\Attributes\Test;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+use SourceBroker\T3api\Middleware\T3apiPageArgumentsRestorer;
+use SourceBroker\T3api\Middleware\T3apiPageArgumentsValidationBypass;
+use TYPO3\CMS\Core\Http\Response;
+use TYPO3\CMS\Core\Http\ServerRequest;
+use TYPO3\CMS\Core\Routing\PageArguments;
+use TYPO3\TestingFramework\Core\Unit\UnitTestCase;
+
+class T3apiPageArgumentsValidationBypassTest extends UnitTestCase
+{
+    #[Test]
+    public function queryArgumentsOfApiRequestAreHiddenFromValidation(): void
+    {
+        $pageArguments = new PageArguments(1, '0', ['t3apiResource' => 'news/news'], [], ['istopnews' => '1', 'page' => '2']);
+
+        $request = $this->process(new T3apiPageArgumentsValidationBypass(), $this->createRequest($pageArguments));
+
+        $validatedPageArguments = $request->getAttribute('routing');
+        self::assertInstanceOf(PageArguments::class, $validatedPageArguments);
+        self::assertSame([], $validatedPageArguments->getDynamicArguments());
+        self::assertSame(1, $validatedPageArguments->getPageId());
+        self::assertSame($pageArguments, $request->getAttribute(T3apiPageArgumentsValidationBypass::ORIGINAL_ROUTING_ATTRIBUTE));
+    }
+
+    #[Test]
+    public function nonApiRequestIsNotModified(): void
+    {
+        $pageArguments = new PageArguments(1, '0', [], [], ['foo' => 'bar']);
+        $request = $this->createRequest($pageArguments);
+
+        $processedRequest = $this->process(new T3apiPageArgumentsValidationBypass(), $request);
+
+        self::assertSame($request, $processedRequest);
+    }
+
+    #[Test]
+    public function restorerPutsOriginalPageArgumentsBack(): void
+    {
+        $pageArguments = new PageArguments(1, '0', ['t3apiResource' => 'news/news'], [], ['istopnews' => '1']);
+        $request = $this->process(new T3apiPageArgumentsValidationBypass(), $this->createRequest($pageArguments));
+
+        $restoredRequest = $this->process(new T3apiPageArgumentsRestorer(), $request);
+
+        self::assertSame($pageArguments, $restoredRequest->getAttribute('routing'));
+        self::assertNull($restoredRequest->getAttribute(T3apiPageArgumentsValidationBypass::ORIGINAL_ROUTING_ATTRIBUTE));
+    }
+
+    #[Test]
+    public function restorerDoesNotModifyRequestWithoutOriginalPageArguments(): void
+    {
+        $request = $this->createRequest(new PageArguments(1, '0', [], [], ['foo' => 'bar']));
+
+        self::assertSame($request, $this->process(new T3apiPageArgumentsRestorer(), $request));
+    }
+
+    private function createRequest(PageArguments $pageArguments): ServerRequestInterface
+    {
+        return (new ServerRequest('https://example.com/_api/news/news'))->withAttribute('routing', $pageArguments);
+    }
+
+    /**
+     * Runs the middleware and returns the request it passed to the next handler.
+     */
+    private function process(
+        T3apiPageArgumentsValidationBypass|T3apiPageArgumentsRestorer $middleware,
+        ServerRequestInterface $request
+    ): ServerRequestInterface {
+        $handler = new class () implements RequestHandlerInterface {
+            public ?ServerRequestInterface $request = null;
+
+            public function handle(ServerRequestInterface $request): ResponseInterface
+            {
+                $this->request = $request;
+
+                return new Response();
+            }
+        };
+
+        $middleware->process($request, $handler);
+
+        self::assertInstanceOf(ServerRequestInterface::class, $handler->request);
+
+        return $handler->request;
+    }
+}