From c74c33fc9cff7d6d3d981f4272cca9198438516d Mon Sep 17 00:00:00 2001
From: Ostap Brehin <osbre@protonmail.com>
Date: Sun, 6 Sep 2026 18:19:00 +0100
Subject: [PATCH] feat(http): validate session identifiers

---
 .../http/src/Session/InvalidSessionId.php     | 17 +++++++
 packages/http/src/Session/SessionId.php       | 12 ++++-
 packages/http/tests/Session/SessionIdTest.php | 50 +++++++++++++++++++
 3 files changed, 78 insertions(+), 1 deletion(-)
 create mode 100644 packages/http/src/Session/InvalidSessionId.php
 create mode 100644 packages/http/tests/Session/SessionIdTest.php

diff --git a/packages/http/src/Session/InvalidSessionId.php b/packages/http/src/Session/InvalidSessionId.php
new file mode 100644
index 0000000000..8b1c519ca5
--- /dev/null
+++ b/packages/http/src/Session/InvalidSessionId.php
@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Http\Session;
+
+use Exception;
+
+final class InvalidSessionId extends Exception
+{
+    public function __construct(string $id)
+    {
+        parent::__construct(
+            sprintf('The session identifier `%s` is not a valid session id.', $id),
+        );
+    }
+}
diff --git a/packages/http/src/Session/SessionId.php b/packages/http/src/Session/SessionId.php
index d7d3d24194..5eccc463bc 100644
--- a/packages/http/src/Session/SessionId.php
+++ b/packages/http/src/Session/SessionId.php
@@ -11,9 +11,19 @@
  */
 final readonly class SessionId implements Stringable
 {
+    /**
+     * Restricts session IDs to safe characters to prevent path traversal
+     * when used as filenames (e.g., by {@see Managers\FileSessionManager}).
+     */
+    private const string PATTERN = '/^[A-Za-z0-9_-]{1,128}\z/';
+
     public function __construct(
         private string $id,
-    ) {}
+    ) {
+        if (preg_match(self::PATTERN, $id) !== 1) {
+            throw new InvalidSessionId($id);
+        }
+    }
 
     public function __toString(): string
     {
diff --git a/packages/http/tests/Session/SessionIdTest.php b/packages/http/tests/Session/SessionIdTest.php
new file mode 100644
index 0000000000..f21f367422
--- /dev/null
+++ b/packages/http/tests/Session/SessionIdTest.php
@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Http\Tests\Session;
+
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\Attributes\TestWith;
+use PHPUnit\Framework\TestCase;
+use Tempest\Http\Session\InvalidSessionId;
+use Tempest\Http\Session\SessionId;
+
+/**
+ * @internal
+ */
+final class SessionIdTest extends TestCase
+{
+    #[Test]
+    #[TestWith(['0197c5f0-8b3a-7c2e-9d1f-2a3b4c5d6e7f'])] // UUID (cookie/header resolver)
+    #[TestWith(['test-session'])]
+    #[TestWith(['abcDEF_123-456'])]
+    public function accepts_valid_identifiers(string $id): void
+    {
+        $this->assertSame($id, (string) new SessionId($id));
+    }
+
+    #[Test]
+    #[TestWith(['../../../../etc/passwd'])]
+    #[TestWith(['../../tmp/marker'])]
+    #[TestWith(['foo/bar'])]
+    #[TestWith(['with space'])]
+    #[TestWith(['with.dot'])]
+    #[TestWith(["null\0byte"])]
+    #[TestWith(["trailing-newline\n"])]
+    #[TestWith([''])]
+    public function rejects_traversal_and_unsafe_identifiers(string $id): void
+    {
+        $this->expectException(InvalidSessionId::class);
+
+        new SessionId($id);
+    }
+
+    #[Test]
+    public function rejects_overly_long_identifiers(): void
+    {
+        $this->expectException(InvalidSessionId::class);
+
+        new SessionId(str_repeat('a', 129));
+    }
+}