From 9ce0c2ac203c6df87979d038a38d4aefafa9e93a Mon Sep 17 00:00:00 2001
From: Keith Solomon <keith@vincentdesign.ca>
Date: Mon, 6 Jul 2026 17:44:41 -0500
Subject: [PATCH] feat: add CSRF token store and verifier

---
 src/Http/CsrfToken.php            | 24 +++++++++++++
 tests/Unit/Http/CsrfTokenTest.php | 60 +++++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+)
 create mode 100644 src/Http/CsrfToken.php
 create mode 100644 tests/Unit/Http/CsrfTokenTest.php

diff --git a/src/Http/CsrfToken.php b/src/Http/CsrfToken.php
new file mode 100644
index 0000000..42df84d
--- /dev/null
+++ b/src/Http/CsrfToken.php
@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Http;
+
+final class CsrfToken
+{
+    /** @return array{0: string, 1: string} */
+    public static function issue(string $secret): array
+    {
+        $token = bin2hex(random_bytes(32));
+        $cookie = hash_hmac('sha256', $token, $secret);
+
+        return [$token, $cookie];
+    }
+
+    public static function verify(string $submitted, string $secret, string $expectedCookieValue): bool
+    {
+        $computed = hash_hmac('sha256', $submitted, $secret);
+
+        return hash_equals($expectedCookieValue, $computed);
+    }
+}
diff --git a/tests/Unit/Http/CsrfTokenTest.php b/tests/Unit/Http/CsrfTokenTest.php
new file mode 100644
index 0000000..9e635f8
--- /dev/null
+++ b/tests/Unit/Http/CsrfTokenTest.php
@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Unit\Http;
+
+use BattleForge\Http\CsrfToken;
+use PHPUnit\Framework\TestCase;
+
+final class CsrfTokenTest extends TestCase
+{
+    private const SECRET = 'unit-test-secret';
+
+    public function testIssueReturnsTokenAndCookieValue(): void
+    {
+        [$token, $cookie] = CsrfToken::issue(self::SECRET);
+
+        self::assertNotSame('', $token);
+        self::assertNotSame('', $cookie);
+        self::assertSame(64, strlen($token));
+    }
+
+    public function testVerifyAcceptsAValidPair(): void
+    {
+        [$token, $cookie] = CsrfToken::issue(self::SECRET);
+
+        self::assertTrue(CsrfToken::verify($token, self::SECRET, $cookie));
+    }
+
+    public function testVerifyRejectsATamperedCookieValue(): void
+    {
+        [$token] = CsrfToken::issue(self::SECRET);
+
+        self::assertFalse(CsrfToken::verify($token, self::SECRET, 'not-the-cookie'));
+    }
+
+    public function testVerifyRejectsATamperedToken(): void
+    {
+        [, $cookie] = CsrfToken::issue(self::SECRET);
+
+        self::assertFalse(CsrfToken::verify('not-the-token', self::SECRET, $cookie));
+    }
+
+    public function testIssueProducesDifferentTokensAcrossCalls(): void
+    {
+        [$tokenA] = CsrfToken::issue(self::SECRET);
+        [$tokenB] = CsrfToken::issue(self::SECRET);
+
+        self::assertNotSame($tokenA, $tokenB);
+    }
+
+    public function testDifferentSecretsProduceDifferentCookieValues(): void
+    {
+        [$tokenA, $cookieA] = CsrfToken::issue('secret-a');
+        [, $cookieB] = CsrfToken::issue('secret-b');
+
+        self::assertTrue(CsrfToken::verify($tokenA, 'secret-a', $cookieA));
+        self::assertFalse(CsrfToken::verify($tokenA, 'secret-b', $cookieB));
+    }
+}