create-prisma-php-app 5.1.0-alpha.3 → 5.1.0-alpha.30

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));
+    }
+}

package/dist/tests/DeferComponentRootsTest.php

@@ -0,0 +1,147 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests;
+
+use PHPUnit\Framework\TestCase;
+use PP\PHPX\TemplateCompiler;
+
+/**
+ * The server-deferred component-root contract, as the app depends on it.
+ *
+ * The final document wraps every outermost `[pp-component]` root inside
+ * `<body>` in an inert `<template pp-component="...">`. The browser never
+ * executes scripts or parses `{...}` placeholders inside a template, so
+ * component scripts cannot run before the PulsePoint runtime module loads
+ * ("pp is not defined") and raw placeholders cannot trigger bogus requests
+ * or value coercion before hydration. `pp.mount()` materializes
+ * `template[pp-component]` back into live DOM before scanning for roots.
+ */
+final class DeferComponentRootsTest extends TestCase
+{
+    private function document(string $bodyContent): string
+    {
+        return "<html>\n<head><title>t</title></head>\n<body>\n"
+            . $bodyContent
+            . "\n</body>\n</html>";
+    }
+
+    public function testWrapsRouteRootInInertTemplate(): void
+    {
+        $html = $this->document(
+            '<div pp-component="page_abc123">'
+            . '<p>Count: {count}</p>'
+            . '<script>const [count, setCount] = pp.state(0);</script>'
+            . '</div>'
+        );
+
+        $deferred = TemplateCompiler::deferComponentRoots($html);
+
+        self::assertStringContainsString(
+            '<template pp-component="page_abc123"><div pp-component="page_abc123">',
+            $deferred
+        );
+        self::assertStringContainsString('</div></template>', $deferred);
+        // The component script rides along inside the inert template, unchanged.
+        self::assertStringContainsString(
+            '<script>const [count, setCount] = pp.state(0);</script>',
+            $deferred
+        );
+    }
+
+    public function testOnlyOutermostBoundaryIsWrapped(): void
+    {
+        $html = $this->document(
+            '<div pp-component="layout_1">'
+            . '<div pp-component="page_2"><p>{msg}</p></div>'
+            . '</div>'
+        );
+
+        $deferred = TemplateCompiler::deferComponentRoots($html);
+
+        self::assertSame(1, substr_count($deferred, '<template pp-component='));
+        self::assertStringContainsString('<template pp-component="layout_1">', $deferred);
+        // The nested boundary stays a plain element inside the inert content.
+        self::assertStringContainsString('<div pp-component="page_2">', $deferred);
+    }
+
+    public function testWrapsFooterComponentScript(): void
+    {
+        $html = $this->document(
+            '<div pp-component="page_1"><p>hi</p></div>'
+            . '<script pp-component="s9footer">pp.state(1);</script>'
+        );
+
+        $deferred = TemplateCompiler::deferComponentRoots($html);
+
+        self::assertStringContainsString(
+            '<template pp-component="s9footer"><script pp-component="s9footer">pp.state(1);</script></template>',
+            $deferred
+        );
+    }
+
+    public function testSiblingBoundariesAreEachWrapped(): void
+    {
+        $html = $this->document(
+            '<main><div pp-component="a"><span>x</span></div>'
+            . '<div pp-component="b"><span>y</span></div></main>'
+        );
+
+        $deferred = TemplateCompiler::deferComponentRoots($html);
+
+        self::assertStringContainsString('<template pp-component="a"><div pp-component="a">', $deferred);
+        self::assertStringContainsString('<template pp-component="b"><div pp-component="b">', $deferred);
+    }
+
+    public function testEscapedBraceEntitiesGainOneEncodingLayer(): void
+    {
+        // The browser's parse of the template content consumes one entity
+        // layer; the extra `&amp;` keeps the escape visible to the runtime.
+        $html = $this->document(
+            '<div pp-component="page_1"><code>&#123;literal&#125;</code>'
+            . '<script>const s = "&#123;";</script></div>'
+        );
+
+        $deferred = TemplateCompiler::deferComponentRoots($html);
+
+        self::assertStringContainsString('<code>&amp;#123;literal&amp;#125;</code>', $deferred);
+        // Script content is raw text in the template parse — left untouched.
+        self::assertStringContainsString('const s = "&#123;";', $deferred);
+    }
+
+    public function testHeadContentIsNeverWrapped(): void
+    {
+        $html = "<html>\n<head><meta name=\"x\" pp-component=\"nope\"></head>\n<body>\n"
+            . '<div pp-component="page_1"><p>hi</p></div>'
+            . "\n</body>\n</html>";
+
+        $deferred = TemplateCompiler::deferComponentRoots($html);
+
+        self::assertStringNotContainsString('<template pp-component="nope">', $deferred);
+        self::assertStringContainsString('<template pp-component="page_1">', $deferred);
+    }
+
+    public function testAlreadyDeferredTemplateIsLeftAlone(): void
+    {
+        $html = $this->document(
+            '<template pp-component="page_1"><div pp-component="page_1"><p>hi</p></div></template>'
+        );
+
+        self::assertSame($html, TemplateCompiler::deferComponentRoots($html));
+    }
+
+    public function testDocumentWithoutBoundariesIsUnchanged(): void
+    {
+        $html = $this->document('<div><p>plain</p></div>');
+
+        self::assertSame($html, TemplateCompiler::deferComponentRoots($html));
+    }
+
+    public function testUnbalancedBoundaryMarkupLeavesDocumentUntouched(): void
+    {
+        $html = $this->document('<div pp-component="page_1"><p>never closed');
+
+        self::assertSame($html, TemplateCompiler::deferComponentRoots($html));
+    }
+}

package/dist/tests/FeaturesTest.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests;
+
+use PHPUnit\Framework\TestCase;
+use Tests\Support\Features;
+
+/**
+ * The suite's own feature awareness: flags come from `prisma-php.json`, the
+ * single source of truth for which optional scaffolds exist in this app.
+ */
+final class FeaturesTest extends TestCase
+{
+    public function testConfigIsReadFromPrismaPhpJson(): void
+    {
+        $raw = json_decode((string) file_get_contents(DOCUMENT_PATH . '/prisma-php.json'), true);
+
+        self::assertIsArray($raw);
+        self::assertSame($raw, Features::config());
+    }
+
+    public function testEnabledMirrorsTheBooleanFlags(): void
+    {
+        $config = Features::config();
+
+        foreach (['websocket', 'mcp', 'swaggerDocs', 'prisma', 'tailwindcss', 'typescript'] as $flag) {
+            self::assertSame(
+                ($config[$flag] ?? false) === true,
+                Features::enabled($flag),
+                "Features::enabled('$flag') mirrors prisma-php.json"
+            );
+        }
+    }
+
+    public function testAnUnknownFlagIsDisabled(): void
+    {
+        self::assertFalse(Features::enabled('not-a-real-feature'));
+    }
+}