create-prisma-php-app 5.0.0-alpha.8 → 5.0.0

package/dist/src/Lib/Websocket/SocketPool.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Lib\Websocket;
+
+/**
+ * A broadcast pool: one `Socket` per open connection.
+ *
+ * How a handler shares its connection with the room it belongs to: keep one
+ * pool in shared state, `add` each socket when its conversation starts, and
+ * `broadcast` fans one value out to everyone. Connections whose browser is
+ * gone are pruned on the way. Keep authenticated and guest traffic in
+ * separate pools so a private broadcast can never reach a guest connection.
+ */
+final class SocketPool
+{
+    /** @var Socket[] */
+    private array $sockets = [];
+
+    public function count(): int
+    {
+        return count($this->sockets);
+    }
+
+    public function add(Socket $socket): void
+    {
+        $this->sockets[] = $socket;
+    }
+
+    public function discard(Socket $socket): void
+    {
+        $this->sockets = array_values(array_filter(
+            $this->sockets,
+            static fn (Socket $candidate): bool => $candidate !== $socket,
+        ));
+    }
+
+    /**
+     * Send one value to everyone, pruning closed connections.
+     */
+    public function broadcast(mixed $value): void
+    {
+        foreach ($this->sockets as $socket) {
+            if (!$socket->send($value)) {
+                $this->discard($socket);
+            }
+        }
+    }
+}

package/dist/src/Lib/Websocket/SocketRegistry.php

@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Lib\Websocket;
+
+use InvalidArgumentException;
+
+/**
+ * The named-socket registry: what `pp.socket("name", ...)` connects to.
+ *
+ * The client connects with a name and nothing else, so socket names are
+ * unique application-wide and a duplicate is refused at registration time.
+ * Registrations live in `src/Lib/Websocket/sockets.php`, which the socket
+ * server loads on startup.
+ */
+final class SocketRegistry
+{
+    /**
+     * @var array<string, array{
+     *     name: string,
+     *     handler: callable,
+     *     requireAuth: bool,
+     *     allowedRoles: string[],
+     * }>
+     */
+    private static array $sockets = [];
+
+    /**
+     * Register a function as a named socket.
+     *
+     * The handler receives `(Socket $socket, array $args)`: the open
+     * connection and the argument payload from the connection's first frame.
+     *
+     * - `requireAuth: true` refuses the connection unless the handshake
+     *   carries a valid auth cookie, before the handler runs.
+     * - `allowedRoles: [...]` adds RBAC on the verified payload, the same
+     *   rule as `#[Exposed(allowedRoles: [...])]`.
+     *
+     * @param string[] $allowedRoles
+     */
+    public static function register(
+        string $name,
+        callable $handler,
+        bool $requireAuth = false,
+        array $allowedRoles = [],
+    ): void {
+        if ($name === '') {
+            throw new InvalidArgumentException('A socket needs a non-empty name.');
+        }
+
+        if (isset(self::$sockets[$name])) {
+            throw new InvalidArgumentException(
+                "Two sockets are named `$name`. The client connects with a "
+                    . 'name and nothing else, so socket names must be unique '
+                    . 'application-wide.'
+            );
+        }
+
+        self::$sockets[$name] = [
+            'name' => $name,
+            'handler' => $handler,
+            'requireAuth' => $requireAuth,
+            'allowedRoles' => array_values($allowedRoles),
+        ];
+    }
+
+    /**
+     * @return array{
+     *     name: string,
+     *     handler: callable,
+     *     requireAuth: bool,
+     *     allowedRoles: string[],
+     * }|null
+     */
+    public static function get(string $name): ?array
+    {
+        return self::$sockets[$name] ?? null;
+    }
+
+    /**
+     * @return string[]
+     */
+    public static function names(): array
+    {
+        return array_keys(self::$sockets);
+    }
+}

package/dist/src/Lib/Websocket/sockets.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Named-socket registrations: the server half of `pp.socket(...)`.
+ *
+ * This file is loaded once by `websocket-server.php` on startup. Register
+ * each socket the app serves here; the name the client connects with is the
+ * registered one, and names are unique application-wide.
+ *
+ * From the browser:
+ *
+ * ```js
+ * const sock = pp.socket("echo", { label: "you" }, {
+ *     onMessage: (value) => append(value),
+ * });
+ * sock.send("hello");
+ * ```
+ */
+
+use Lib\Websocket\Socket;
+use Lib\Websocket\SocketPool;
+use Lib\Websocket\SocketRegistry;
+
+// A minimal example: echo every frame back, prefixed with the label the
+// page opened the socket with.
+SocketRegistry::register('echo', function (Socket $socket, array $args): void {
+    $label = is_string($args['label'] ?? null) ? $args['label'] : 'echo';
+
+    $socket->onMessage(function (mixed $value) use ($socket, $label): void {
+        $text = is_string($value) ? $value : json_encode($value, JSON_UNESCAPED_UNICODE);
+        $socket->send("$label: $text");
+    });
+});
+
+// A broadcast example: everyone connected to `chat` hears everyone else.
+$chatRoom = new SocketPool();
+
+SocketRegistry::register('chat', function (Socket $socket, array $args) use ($chatRoom): void {
+    $chatRoom->add($socket);
+
+    $socket->onMessage(function (mixed $value) use ($chatRoom): void {
+        $chatRoom->broadcast($value);
+    });
+
+    $socket->onClose(function () use ($chatRoom, $socket): void {
+        $chatRoom->discard($socket);
+    });
+});

package/dist/src/Lib/Websocket/websocket-server.php

@@ -54,7 +54,10 @@ if ($probe === false) {
 fclose($probe);
 
 // ── Build app ────────────────────────────────────────────────────────────────
-$manager = new ConnectionManager(); // your app component
+// Named-socket registrations: the functions `pp.socket("name", ...)` reaches.
+require __DIR__ . '/sockets.php';
+
+$manager = new ConnectionManager(); // The PulsePoint named-socket wire.
 $server  = IoServer::factory(
     new HttpServer(new WsServer($manager)),
     $port,
@@ -73,14 +76,18 @@ echo "   Port:       {$port}" . PHP_EOL;
 echo "   URL:        {$url}" . PHP_EOL;
 echo "   PID:        {$pid}" . PHP_EOL;
 echo "   Started:    {$ts}" . PHP_EOL;
+echo "   Sockets:    " . (implode(', ', \Lib\Websocket\SocketRegistry::names()) ?: '(none registered)') . PHP_EOL;
 
 // ── Graceful shutdown & periodic logs (if loop available) ────────────────────
 $loop = property_exists($server, 'loop') ? $server->loop : null;
 if ($loop instanceof LoopInterface) {
+    // First-frame timeout and idle sweep need the loop's timers.
+    $manager->attachLoop($loop);
+
     // Periodic stats every 60s
-    $loop->addPeriodicTimer(60, function () use ($ok) {
+    $loop->addPeriodicTimer(60, function () use ($ok, $manager) {
         $mem = function_exists('memory_get_usage') ? number_format(memory_get_usage(true) / 1048576, 2) . ' MB' : 'n/a';
-        $msg = "✓ Heartbeat — memory: {$mem}";
+        $msg = "✓ Heartbeat — connections: {$manager->openConnectionCount()}, memory: {$mem}";
         echo $ok($msg) . PHP_EOL;
     });
 

package/dist/src/app/globals.css

@@ -1,4 +1,6 @@
-@import "tailwindcss";
+@import "tailwindcss" source(none);
+@source "../";
+@source "../../ts";
 
 :root {
   --background: #ffffff;

package/dist/src/app/layout.php

@@ -15,7 +15,7 @@ MainLayout::$description = !empty(MainLayout::$description) ? MainLayout::$descr
     <!-- Dynamic Header Scripts -->
 </head>
 
-<body pp-spa="true" style="opacity:0;pointer-events:none;user-select:none;transition:opacity .18s ease-out;">
+<body style="opacity:0;pointer-events:none;user-select:none;transition:opacity .18s ease-out;">
     <?= MainLayout::$children; ?>
     <!-- Dynamic Footer Scripts -->
 </body>

package/dist/tests/AuthTest.php

@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests;
+
+use Firebase\JWT\JWT;
+use Lib\Auth\Auth;
+use PHPUnit\Framework\TestCase;
+use PP\Env;
+
+/**
+ * The JWT session tokens both wires trust: RPC auth reads them through the
+ * request session, and the socket server verifies the handshake cookie with
+ * `verifyToken(...)` alone.
+ */
+final class AuthTest extends TestCase
+{
+    public function testSignInReturnsATokenThatVerifiesBackToThePayload(): void
+    {
+        $auth = Auth::getInstance();
+
+        $jwt = $auth->signIn('admin');
+
+        self::assertSame('admin', $auth->verifyToken($jwt));
+    }
+
+    public function testATamperedTokenVerifiesToNull(): void
+    {
+        $auth = Auth::getInstance();
+        $jwt = $auth->signIn('admin');
+
+        self::assertNull($auth->verifyToken($jwt . 'x'));
+        self::assertNull($auth->verifyToken('not-a-jwt'));
+        self::assertNull($auth->verifyToken(null));
+    }
+
+    public function testAnExpiredTokenVerifiesToNull(): void
+    {
+        $expired = JWT::encode(
+            [Auth::PAYLOAD_NAME => 'admin', 'exp' => time() - 60],
+            Env::string('AUTH_SECRET', ''),
+            'HS256'
+        );
+
+        self::assertNull(Auth::getInstance()->verifyToken($expired));
+    }
+
+    public function testATokenSignedWithADifferentSecretVerifiesToNull(): void
+    {
+        $forged = JWT::encode(
+            [Auth::PAYLOAD_NAME => 'admin', 'exp' => time() + 3600],
+            'a-different-32-byte-signing-secret-key',
+            'HS256'
+        );
+
+        self::assertNull(Auth::getInstance()->verifyToken($forged));
+    }
+}

package/dist/tests/ConnectionManagerTest.php

@@ -0,0 +1,277 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests;
+
+use Lib\Auth\Auth;
+use Lib\Websocket\ConnectionManager;
+use Lib\Websocket\Socket;
+use Lib\Websocket\SocketRegistry;
+use PHPUnit\Framework\TestCase;
+use Tests\Support\FakeConnection;
+use Tests\Support\RequiresFeature;
+
+/**
+ * The named-socket wire from the server's side: where a connection must go,
+ * what the first frame is, and which failures travel as the reserved
+ * `{"error": ...}` frame.
+ *
+ * Mirrors the client runtime's SocketClient tests: name in the `name` query
+ * parameter, arguments as the first JSON object frame, refusals as an error
+ * frame followed by a close.
+ */
+final class ConnectionManagerTest extends TestCase
+{
+    use RequiresFeature;
+
+    /** @var array<string, string|false> */
+    private array $envBackup = [];
+
+    protected function setUp(): void
+    {
+        $this->requireFeature('websocket');
+        SocketRegistryTest::resetRegistry();
+    }
+
+    protected function tearDown(): void
+    {
+        SocketRegistryTest::resetRegistry();
+
+        foreach ($this->envBackup as $name => $previous) {
+            if ($previous === false) {
+                putenv($name);
+            } else {
+                putenv("$name=$previous");
+            }
+        }
+        $this->envBackup = [];
+    }
+
+    private function setEnv(string $name, string $value): void
+    {
+        if (!array_key_exists($name, $this->envBackup)) {
+            $this->envBackup[$name] = getenv($name);
+        }
+        putenv("$name=$value");
+    }
+
+    /** A connection from a dev-browser origin, upgraded and args sent. */
+    private function openWithArgs(
+        ConnectionManager $manager,
+        FakeConnection $conn,
+        array $args = [],
+    ): void {
+        $manager->onOpen($conn);
+        $manager->onMessage($conn, json_encode($args === [] ? new \stdClass() : $args));
+    }
+
+    private function devConnection(string $name): FakeConnection
+    {
+        return new FakeConnection(
+            "/__pulsepoint/ws?name=$name",
+            ['Origin' => 'http://localhost:3000'],
+        );
+    }
+
+    public function testUnknownNameIsRefusedWithAReadableErrorFrame(): void
+    {
+        $manager = new ConnectionManager();
+        $conn = $this->devConnection('nope');
+
+        $manager->onOpen($conn);
+
+        $frame = $conn->lastFrame();
+        self::assertIsArray($frame);
+        self::assertArrayHasKey('error', $frame);
+        self::assertStringContainsString('No socket named `nope`', $frame['error']);
+        self::assertSame([1008], $conn->closeCodes);
+    }
+
+    public function testMissingNameIsRefused(): void
+    {
+        $manager = new ConnectionManager();
+        $conn = new FakeConnection('/__pulsepoint/ws', ['Origin' => 'http://localhost:3000']);
+
+        $manager->onOpen($conn);
+
+        self::assertStringContainsString('named no socket', $conn->lastFrame()['error']);
+        self::assertSame([1008], $conn->closeCodes);
+    }
+
+    public function testArgumentsArriveAsTheFirstFrameAndReachTheHandler(): void
+    {
+        $received = null;
+        SocketRegistry::register('echo', function (Socket $socket, array $args) use (&$received): void {
+            $received = $args;
+            $socket->onMessage(fn (mixed $value) => $socket->send("you: $value"));
+        });
+
+        $manager = new ConnectionManager();
+        $conn = $this->devConnection('echo');
+
+        $this->openWithArgs($manager, $conn, ['room' => 'lobby']);
+        self::assertSame(['room' => 'lobby'], $received);
+
+        $manager->onMessage($conn, '"hello"');
+        self::assertSame('you: hello', $conn->lastFrame());
+        self::assertSame([], $conn->closeCodes, 'the conversation stays open');
+    }
+
+    public function testEmptyArgumentsObjectIsAccepted(): void
+    {
+        $received = null;
+        SocketRegistry::register('feed', function (Socket $socket, array $args) use (&$received): void {
+            $received = $args;
+        });
+
+        $manager = new ConnectionManager();
+        $conn = $this->devConnection('feed');
+
+        $this->openWithArgs($manager, $conn);
+
+        self::assertSame([], $received);
+        self::assertSame([], $conn->closeCodes);
+    }
+
+    public function testANonObjectFirstFrameIsRefused(): void
+    {
+        SocketRegistry::register('echo', static function (): void {});
+
+        $manager = new ConnectionManager();
+        $conn = $this->devConnection('echo');
+
+        $manager->onOpen($conn);
+        $manager->onMessage($conn, '[1, 2]');
+
+        self::assertStringContainsString('not a JSON object', $conn->lastFrame()['error']);
+        self::assertSame([1008], $conn->closeCodes);
+    }
+
+    public function testAnUnreadableFrameTravelsBackAsAnErrorFrame(): void
+    {
+        SocketRegistry::register('echo', function (Socket $socket): void {
+            $socket->onMessage(static function (): void {});
+        });
+
+        $manager = new ConnectionManager();
+        $conn = $this->devConnection('echo');
+
+        $this->openWithArgs($manager, $conn);
+        $manager->onMessage($conn, '{not json');
+
+        self::assertStringContainsString('could not read a frame', $conn->lastFrame()['error']);
+    }
+
+    public function testAnOversizedFrameClosesWith1009(): void
+    {
+        SocketRegistry::register('echo', static function (): void {});
+
+        $manager = new ConnectionManager();
+        $conn = $this->devConnection('echo');
+
+        $this->openWithArgs($manager, $conn);
+        $manager->onMessage($conn, json_encode(str_repeat('x', 5000)));
+
+        self::assertContains(1009, $conn->closeCodes);
+    }
+
+    public function testProductionRefusesAnUnknownOriginBeforeAnyFrame(): void
+    {
+        SocketRegistry::register('echo', static function (): void {});
+        $this->setEnv('APP_ENV', 'production');
+
+        $manager = new ConnectionManager();
+        $conn = new FakeConnection(
+            '/__pulsepoint/ws?name=echo',
+            ['Origin' => 'https://evil.example'],
+        );
+
+        $manager->onOpen($conn);
+
+        self::assertSame([], $conn->sentFrames, 'refused silently, before the wire speaks');
+        self::assertSame([1008], $conn->closeCodes);
+    }
+
+    public function testProductionAcceptsAnOriginNamedInTheAllowlist(): void
+    {
+        SocketRegistry::register('echo', static function (): void {});
+        $this->setEnv('APP_ENV', 'production');
+        $this->setEnv('WEBSOCKET_ALLOWED_ORIGINS', 'https://app.example');
+
+        $manager = new ConnectionManager();
+        $conn = new FakeConnection(
+            '/__pulsepoint/ws?name=echo',
+            ['Origin' => 'https://app.example'],
+        );
+
+        $manager->onOpen($conn);
+
+        self::assertSame([], $conn->closeCodes);
+    }
+
+    public function testRequireAuthRefusesAGuestConnection(): void
+    {
+        SocketRegistry::register('private', static function (): void {}, requireAuth: true);
+
+        $manager = new ConnectionManager();
+        $conn = $this->devConnection('private');
+
+        $manager->onOpen($conn);
+
+        self::assertStringContainsString('signed-in session', $conn->lastFrame()['error']);
+        self::assertSame([1008], $conn->closeCodes);
+    }
+
+    public function testAValidAuthCookieReachesTheHandlerAsThePayload(): void
+    {
+        $seenPayload = false;
+        SocketRegistry::register('private', function (Socket $socket) use (&$seenPayload): void {
+            $seenPayload = $socket->payload();
+        }, requireAuth: true);
+
+        $jwt = Auth::getInstance()->signIn('admin');
+
+        $manager = new ConnectionManager();
+        $conn = new FakeConnection('/__pulsepoint/ws?name=private', [
+            'Origin' => 'http://localhost:3000',
+            'Cookie' => Auth::$cookieName . '=' . $jwt,
+        ]);
+
+        $this->openWithArgs($manager, $conn);
+
+        self::assertSame('admin', $seenPayload);
+        self::assertSame([], $conn->closeCodes);
+    }
+
+    public function testAHandlerExceptionTravelsAsTheErrorFrame(): void
+    {
+        SocketRegistry::register('broken', static function (): void {
+            throw new \RuntimeException('boom');
+        });
+
+        $manager = new ConnectionManager();
+        $conn = $this->devConnection('broken');
+
+        $this->openWithArgs($manager, $conn);
+
+        $frame = $conn->lastFrame();
+        self::assertArrayHasKey('error', $frame);
+        self::assertStringContainsString('boom', $frame['error'], 'development shows the message');
+        self::assertSame([1008], $conn->closeCodes);
+    }
+
+    public function testCloseReleasesTheConnectionSlot(): void
+    {
+        SocketRegistry::register('echo', static function (): void {});
+
+        $manager = new ConnectionManager();
+        $conn = $this->devConnection('echo');
+
+        $this->openWithArgs($manager, $conn);
+        self::assertSame(1, $manager->openConnectionCount());
+
+        $manager->onClose($conn);
+        self::assertSame(0, $manager->openConnectionCount());
+    }
+}

package/dist/tests/CsrfTest.php

@@ -0,0 +1,119 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests;
+
+use PHPUnit\Framework\TestCase;
+use PP\Security\Csrf;
+
+/**
+ * The CSRF half of the RPC wire: the `pp_csrf` cookie family and the
+ * double-submit validation of the `X-CSRF-Token` header.
+ */
+final class CsrfTest extends TestCase
+{
+    protected function setUp(): void
+    {
+        $this->clearCsrfCookies();
+    }
+
+    protected function tearDown(): void
+    {
+        $this->clearCsrfCookies();
+    }
+
+    private function clearCsrfCookies(): void
+    {
+        foreach (array_keys($_COOKIE) as $name) {
+            if (str_starts_with((string) $name, 'pp_csrf')) {
+                unset($_COOKIE[$name]);
+            }
+        }
+    }
+
+    public function testCookieFamilyUsesThePpCsrfNamesTheRuntimeReads(): void
+    {
+        $names = Csrf::cookieNames();
+
+        self::assertNotEmpty($names);
+        self::assertSame('pp_csrf', end($names), 'plain pp_csrf is always the fallback name');
+
+        foreach ($names as $name) {
+            self::assertStringStartsWith('pp_csrf', $name);
+        }
+    }
+
+    public function testEnsureCookieMintsASignedTokenForEveryCookieName(): void
+    {
+        Csrf::ensureCookie();
+
+        foreach (Csrf::cookieNames() as $name) {
+            self::assertArrayHasKey($name, $_COOKIE);
+            self::assertMatchesRegularExpression(
+                '/^[0-9a-f]{32}\.[0-9a-f]{64}$/',
+                $_COOKIE[$name],
+                'token is nonce.hmac-sha256'
+            );
+        }
+
+        $values = array_map(static fn (string $name) => $_COOKIE[$name], Csrf::cookieNames());
+        self::assertCount(1, array_unique($values), 'every issued name carries the same token');
+    }
+
+    public function testEnsureCookieKeepsAnExistingValidToken(): void
+    {
+        Csrf::ensureCookie();
+        $first = $_COOKIE['pp_csrf'];
+
+        Csrf::ensureCookie();
+
+        self::assertSame($first, $_COOKIE['pp_csrf']);
+    }
+
+    public function testRotateReplacesTheToken(): void
+    {
+        Csrf::ensureCookie();
+        $first = $_COOKIE['pp_csrf'];
+
+        Csrf::rotate();
+
+        self::assertNotSame($first, $_COOKIE['pp_csrf']);
+    }
+
+    public function testValidTokenRoundTrip(): void
+    {
+        Csrf::ensureCookie();
+
+        self::assertNull(Csrf::validateHeaderToken($_COOKIE['pp_csrf']));
+    }
+
+    public function testMissingHeaderTokenIsRefused(): void
+    {
+        Csrf::ensureCookie();
+
+        self::assertSame('Missing CSRF token', Csrf::validateHeaderToken(''));
+    }
+
+    public function testHeaderThatMatchesNoCookieIsRefused(): void
+    {
+        Csrf::ensureCookie();
+
+        self::assertSame(
+            'Invalid CSRF token',
+            Csrf::validateHeaderToken(str_repeat('a', 32) . '.' . str_repeat('b', 64))
+        );
+    }
+
+    public function testTamperedSignatureIsRefusedEvenWhenTheCookieMatches(): void
+    {
+        // Double-submit alone is not enough: the signature must verify, so a
+        // token an attacker planted (cookie tossing) without the secret fails.
+        $forged = str_repeat('a', 32) . '.' . str_repeat('b', 64);
+        foreach (Csrf::cookieNames() as $name) {
+            $_COOKIE[$name] = $forged;
+        }
+
+        self::assertSame('Invalid CSRF token', Csrf::validateHeaderToken($forged));
+    }
+}