feat: add MatchActionSupport for shared CSRF/turn/state verification

src/Http/MatchActionResult.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Http;
+
+use BattleForge\Domain\MatchState;
+
+/**
+ * @phpstan-type MatchIdAndMatch = array{matchId: string, match: MatchState}
+ */
+final readonly class MatchActionResult
+{
+    /**
+     * @param ?MatchIdAndMatch $matchIdAndMatch
+     */
+    public function __construct(
+        public ?Response $response,
+        public ?array $matchIdAndMatch,
+    ) {
+    }
+
+    /** @param MatchIdAndMatch $pair */
+    public static function ok(array $pair): self
+    {
+        return new self(null, $pair);
+    }
+
+    public static function reject(Response $response): self
+    {
+        return new self($response, null);
+    }
+}

src/Http/MatchActionSupport.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Http;
+
+use BattleForge\Application\ScenarioSerializer;
+use BattleForge\Application\TurnToken;
+
+final class MatchActionSupport
+{
+    public function __construct(private readonly string $secret)
+    {
+    }
+
+    public function verify(Request $request): MatchActionResult
+    {
+        $submitted = (string) ($request->server['HTTP_X_CSRF_TOKEN'] ?? '');
+        $expected = (string) ($request->cookies['__csrf'] ?? '');
+        $secret = (string) ($request->server['__csrf_secret'] ?? '');
+
+        if ($secret === '' || $expected === '' || !CsrfToken::verify($submitted, $secret, $expected)) {
+            return MatchActionResult::reject(Response::json(403, ['error' => 'csrf']));
+        }
+
+        $payload = json_decode($request->rawBody, true);
+        if (!is_array($payload)) {
+            return MatchActionResult::reject(Response::json(400, ['errors' => ['Malformed JSON.']]));
+        }
+
+        $matchId = (string) ($payload['matchId'] ?? '');
+        $matchData = $payload['match'] ?? null;
+        if (!is_array($matchData)) {
+            return MatchActionResult::reject(Response::json(400, ['errors' => ['Match is required.']]));
+        }
+
+        try {
+            $match = ScenarioSerializer::matchFromArray($matchData);
+        } catch (\JsonException $exception) {
+            return MatchActionResult::reject(Response::json(400, ['errors' => ['Malformed JSON.']]));
+        } catch (\InvalidArgumentException $exception) {
+            return MatchActionResult::reject(Response::json(400, ['errors' => [$exception->getMessage()]]));
+        }
+
+        $supplied = (string) ($request->server['HTTP_X_TURN_TOKEN'] ?? '');
+        if (
+            !TurnToken::verify(
+                $this->secret,
+                $matchId,
+                $match->activeTeamId,
+                $match->round,
+                count($match->actionLog),
+                $supplied,
+            )
+        ) {
+            return MatchActionResult::reject(Response::json(409, ['error' => 'turn']));
+        }
+
+        return MatchActionResult::ok(['matchId' => $matchId, 'match' => $match]);
+    }
+}