From 3d8c1cfdb2ac537e1bcf486d8a9d0800bebfb952 Mon Sep 17 00:00:00 2001
From: Keith Solomon <keith@vincentdesign.ca>
Date: Sat, 25 Jul 2026 22:39:29 -0500
Subject: [PATCH] feat: add TurnToken HMAC for match-action anti-cheat

---
 src/Application/TurnToken.php            | 79 +++++++++++++++++++++
 tests/Unit/Application/TurnTokenTest.php | 88 ++++++++++++++++++++++++
 2 files changed, 167 insertions(+)
 create mode 100644 src/Application/TurnToken.php
 create mode 100644 tests/Unit/Application/TurnTokenTest.php

diff --git a/src/Application/TurnToken.php b/src/Application/TurnToken.php
new file mode 100644
index 0000000..33f13fd
--- /dev/null
+++ b/src/Application/TurnToken.php
@@ -0,0 +1,79 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Application;
+
+use InvalidArgumentException;
+
+final class TurnToken
+{
+    private const MATCH_ID_PATTERN = '/^[a-f0-9]{16,}$/';
+
+    public static function issue(
+        string $secret,
+        string $matchId,
+        string $activeTeamId,
+        int $round,
+        int $lastActionIndex
+    ): string {
+        self::assertValidInputs($matchId, $activeTeamId, $round, $lastActionIndex);
+
+        $payload = self::payload($matchId, $activeTeamId, $round, $lastActionIndex);
+
+        return substr(hash_hmac('sha256', $payload, $secret), 0, 32);
+    }
+
+    public static function verify(
+        string $secret,
+        string $matchId,
+        string $activeTeamId,
+        int $round,
+        int $lastActionIndex,
+        string $token
+    ): bool {
+        if (
+            $token === ''
+            || !self::isValidMatchId($matchId)
+            || $activeTeamId === ''
+            || $round < 1
+            || $lastActionIndex < 0
+        ) {
+            return false;
+        }
+
+        $expected = self::issue($secret, $matchId, $activeTeamId, $round, $lastActionIndex);
+
+        return hash_equals($expected, $token);
+    }
+
+    private static function assertValidInputs(
+        string $matchId,
+        string $activeTeamId,
+        int $round,
+        int $lastActionIndex
+    ): void {
+        if (!self::isValidMatchId($matchId)) {
+            throw new InvalidArgumentException('Match id must be 16+ lowercase hex characters.');
+        }
+        if ($activeTeamId === '') {
+            throw new InvalidArgumentException('Active team id cannot be empty.');
+        }
+        if ($round < 1) {
+            throw new InvalidArgumentException('Round must be at least 1.');
+        }
+        if ($lastActionIndex < 0) {
+            throw new InvalidArgumentException('Last action index cannot be negative.');
+        }
+    }
+
+    private static function isValidMatchId(string $matchId): bool
+    {
+        return preg_match(self::MATCH_ID_PATTERN, $matchId) === 1;
+    }
+
+    private static function payload(string $matchId, string $activeTeamId, int $round, int $lastActionIndex): string
+    {
+        return implode('|', [$matchId, $activeTeamId, (string) $round, (string) $lastActionIndex]);
+    }
+}
diff --git a/tests/Unit/Application/TurnTokenTest.php b/tests/Unit/Application/TurnTokenTest.php
new file mode 100644
index 0000000..66d85a6
--- /dev/null
+++ b/tests/Unit/Application/TurnTokenTest.php
@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Unit\Application;
+
+use BattleForge\Application\TurnToken;
+use InvalidArgumentException;
+use PHPUnit\Framework\TestCase;
+
+final class TurnTokenTest extends TestCase
+{
+    private const SECRET = 'turn-token-test-secret';
+
+    public function testIssueIsDeterministicForTheSameInputs(): void
+    {
+        $a = TurnToken::issue(self::SECRET, '0123456789abcdef', 'alpha', 1, 0);
+        $b = TurnToken::issue(self::SECRET, '0123456789abcdef', 'alpha', 1, 0);
+
+        self::assertSame($a, $b);
+        self::assertSame(32, strlen($a));
+        self::assertMatchesRegularExpression('/^[a-f0-9]{32}$/', $a);
+    }
+
+    public function testVerifyAcceptsAFreshlyIssuedToken(): void
+    {
+        $token = TurnToken::issue(self::SECRET, '0123456789abcdef', 'alpha', 1, 0);
+
+        self::assertTrue(TurnToken::verify(self::SECRET, '0123456789abcdef', 'alpha', 1, 0, $token));
+    }
+
+    public function testVerifyRejectsAMutatedToken(): void
+    {
+        $token = TurnToken::issue(self::SECRET, '0123456789abcdef', 'alpha', 1, 0);
+        $tampered = substr($token, 0, -1) . '0';
+
+        self::assertFalse(TurnToken::verify(self::SECRET, '0123456789abcdef', 'alpha', 1, 0, $tampered));
+    }
+
+    public function testVerifyRejectsATokenFromADifferentMatch(): void
+    {
+        $token = TurnToken::issue(self::SECRET, '0123456789abcdef', 'alpha', 1, 0);
+
+        self::assertFalse(TurnToken::verify(self::SECRET, 'fedcba9876543210', 'alpha', 1, 0, $token));
+    }
+
+    public function testVerifyRejectsATokenFromADifferentTeam(): void
+    {
+        $token = TurnToken::issue(self::SECRET, '0123456789abcdef', 'alpha', 1, 0);
+
+        self::assertFalse(TurnToken::verify(self::SECRET, '0123456789abcdef', 'bravo', 1, 0, $token));
+    }
+
+    public function testVerifyRejectsATokenFromADifferentRound(): void
+    {
+        $token = TurnToken::issue(self::SECRET, '0123456789abcdef', 'alpha', 1, 0);
+
+        self::assertFalse(TurnToken::verify(self::SECRET, '0123456789abcdef', 'alpha', 2, 0, $token));
+    }
+
+    public function testVerifyRejectsATokenFromADifferentLastActionIndex(): void
+    {
+        $token = TurnToken::issue(self::SECRET, '0123456789abcdef', 'alpha', 1, 0);
+
+        self::assertFalse(TurnToken::verify(self::SECRET, '0123456789abcdef', 'alpha', 1, 1, $token));
+    }
+
+    public function testIssueRejectsAMalformedMatchId(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        TurnToken::issue(self::SECRET, 'not-hex!', 'alpha', 1, 0);
+    }
+
+    public function testIssueRejectsAnEmptyActiveTeamId(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        TurnToken::issue(self::SECRET, '0123456789abcdef', '', 1, 0);
+    }
+
+    public function testIssueRejectsANegativeRound(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        TurnToken::issue(self::SECRET, '0123456789abcdef', 'alpha', 0, 0);
+    }
+}