@north-light/crouter 0.3.173 → 0.3.174

package/dist/clients/web/server.js

@@ -1,661 +0,0 @@
-// server.ts — the `surface web serve` dev shell: a thin reverse proxy in front
-// of crtrd (spec §7.5, C-1). It hosts NO canvas writer of its own — crtrd is the
-// sole writer. This process opens NO `canvas.db`, spawns NO subprocess bridge,
-// and terminates NO WebSocket. It serves, on one origin:
-//   • /v1/*                 → REVERSE PROXY to crtrd's unix socket. The SPA (and
-//                             any /v1 client) reaches the REST API THROUGH this
-//                             shell; the shell owns the auth boundary (crtrd
-//                             applies none), then streams the request/response
-//                             verbatim to/from the socket.
-//   • WS   /node/<id>       → TRANSPARENT TUNNEL to crtrd's
-//                             `GET /v1/nodes/{id}/attach`. The shell does NOT
-//                             terminate the WebSocket — it forwards the upgrade
-//                             rewritten to the attach path and pipes bytes both
-//                             directions. crtrd owns the handshake and
-//                             attach-implies-revive; the browser is the SAME
-//                             protocol peer as `crtr surface attach`.
-//   • GET  /*               → the shell SPA (static dist/web-client/, or Vite
-//                             middleware in --dev) + SPA fallback.
-//   • GET  /__crtr/events   → the SSE change-invalidation lane (events.ts).
-//                             canvas.db-free; explicitly out of P1 scope, kept.
-//   • Web push (§push)      → GET  /__crtr/push/vapid-public-key, POST/DELETE
-//                             /__crtr/push/subscribe. A server-side diff engine
-//                             (push-engine.ts) watches the SAME SSE invalidations
-//                             above and sends web-push to a persisted, auth-scoped
-//                             registry (push-registry.ts). Its canvas reads go
-//                             through the crtrd API (via `cliClient()` command
-//                             leaves), never `canvas.db`. Out of P1 scope, kept.
-//
-// §0 ONE-WRITER INVARIANT: this process never mutates the canvas. Every write
-// and every canvas read flows to crtrd — the `/v1/*` proxy and the `/node/<id>`
-// attach tunnel both terminate at crtrd's unix socket, and the push engine's
-// reads route through the crtrd-backed command leaves. There is no local
-// transport, no `canvas.db` handle, and no direct broker socket here.
-import { createServer as createHttpServer, request as httpRequest } from 'node:http';
-import { createConnection, isIP } from 'node:net';
-import { createHash } from 'node:crypto';
-import { createReadStream, existsSync, statSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, extname, join, normalize, resolve } from 'node:path';
-import webpush from 'web-push';
-import { apiSocketPath, isSafeNodeId } from '../../core/canvas/paths.js';
-import { emitEvent } from '../../core/events/emit.js';
-import { bindWebEventSource } from '../../core/events/source.js';
-import { canvasRosterLeaf } from '../../commands/canvas-roster.js';
-import { startEventHub } from './events.js';
-import { createDevServer } from './dev-server.js';
-import { PushLastSeenStore, PushRegistryStore, PushRequestError, loadOrCreateVapidKeypair, parsePushDeleteBody, parsePushSubscriptionBody, pushBodyMaxBytes, } from './push-registry.js';
-import { PushDiffEngine } from './push-engine.js';
-const HERE = dirname(fileURLToPath(import.meta.url));
-/** Candidate dirs to serve the shell SPA bundle from, in priority order: an
- *  explicit override, the compiled-module-relative `dist/web-client/` (what
- *  `vite build` emits and what we serve in production), and the placeholder
- *  copied from source. The first that exists wins. (--dev bypasses this entirely
- *  — Vite middleware owns asset serving in that mode.) */
-function resolveClientDir() {
-    const candidates = [
-        process.env['CRTR_WEB_CLIENT_DIR'],
-        join(HERE, '../../web-client'),
-        resolve(HERE, '../../../dist/web-client'),
-    ].filter((p) => p !== undefined && p !== '');
-    for (const dir of candidates) {
-        if (existsSync(dir))
-            return dir;
-    }
-    // Fall back to the module-relative path even if absent; missing-file handling
-    // below returns a clear 503 so a not-yet-built shell is diagnosable.
-    return join(HERE, '../../web-client');
-}
-const CONTENT_TYPES = {
-    '.html': 'text/html; charset=utf-8',
-    '.js': 'text/javascript; charset=utf-8',
-    '.mjs': 'text/javascript; charset=utf-8',
-    '.css': 'text/css; charset=utf-8',
-    '.json': 'application/json; charset=utf-8',
-    '.webmanifest': 'application/manifest+json',
-    '.svg': 'image/svg+xml',
-    '.png': 'image/png',
-    '.jpg': 'image/jpeg',
-    '.jpeg': 'image/jpeg',
-    '.gif': 'image/gif',
-    '.webp': 'image/webp',
-    '.ico': 'image/x-icon',
-    '.woff': 'font/woff',
-    '.woff2': 'font/woff2',
-    '.map': 'application/json; charset=utf-8',
-};
-function contentTypeFor(path) {
-    return CONTENT_TYPES[extname(path).toLowerCase()] ?? 'application/octet-stream';
-}
-/** Match a WS/GET path of the shape `/node/<id>` (with any number of leading
- *  segments, future-proofing a mount prefix). Returns the decoded node id, or
- *  null if the path doesn't match or the id is undecodable (malformed `%`). The
- *  caller must still validate the decoded id with the shared persisted-node-ID
- *  predicate before building a filesystem path — see {@link isSafeNodeId}. */
-function nodeIdFromPath(pathname) {
-    const m = /\/node\/([^/?#]+)\/?$/.exec(pathname);
-    if (m === null)
-        return null;
-    try {
-        return decodeURIComponent(m[1]);
-    }
-    catch {
-        return null; // malformed percent-encoding — treat as no match
-    }
-}
-function isLoopbackHost(host) {
-    const lower = host.toLowerCase();
-    const ipVersion = isIP(host);
-    if (lower === 'localhost' || lower === '::1')
-        return true;
-    if (ipVersion === 4 && host.startsWith('127.'))
-        return true;
-    if (lower === '::ffff:127.0.0.1')
-        return true;
-    if (ipVersion === 6 && lower.startsWith('::ffff:127.'))
-        return true;
-    return false;
-}
-function hostForUrl(host) {
-    return host.includes(':') ? `[${host}]` : host;
-}
-function requestTokens(req) {
-    const url = new URL(req.url ?? '/', 'http://127.0.0.1');
-    const tokens = [];
-    const queryToken = url.searchParams.get('token');
-    if (queryToken !== null && queryToken !== '')
-        tokens.push(queryToken);
-    const authorization = req.headers.authorization;
-    if (typeof authorization === 'string') {
-        const match = /^Bearer\s+(.+)$/.exec(authorization);
-        if (match !== null && match[1] !== '')
-            tokens.push(match[1]);
-    }
-    return tokens;
-}
-function requestTokenMatches(req, secret) {
-    if (secret === undefined)
-        return false;
-    return requestTokens(req).some((token) => token === secret);
-}
-/** Read a request body into a string, aborting the moment the accumulated body exceeds
- *  `maxBytes` — so a push endpoint never buffers arbitrary attacker memory
- *  before validation rejects it. Rejects with PushRequestError(413), which the
- *  push error handler maps to a 413 response. */
-function readBodyCapped(req, maxBytes) {
-    return new Promise((resolve, reject) => {
-        const chunks = [];
-        let total = 0;
-        req.on('data', (c) => {
-            total += c.length;
-            if (total > maxBytes) {
-                reject(new PushRequestError(413, 'push subscription body is too large'));
-                req.destroy();
-                return;
-            }
-            chunks.push(c);
-        });
-        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
-        req.on('error', reject);
-    });
-}
-/** Derive the persisted auth scope from a bearer token: a short, stable hash so
- *  the raw secret never touches disk. */
-function scopeForToken(secret) {
-    return `token:${createHash('sha256').update(secret).digest('base64url').slice(0, 16)}`;
-}
-/** Serve a static file from the client dir, with SPA fallback to index.html for
- *  any unmatched (non-asset) GET — so `/` and `/node/<id>` both boot the app
- *  shell. Returns true if it wrote a response. */
-function serveStatic(clientDir, req, res) {
-    const url = new URL(req.url ?? '/', 'http://127.0.0.1');
-    let pathname;
-    try {
-        pathname = decodeURIComponent(url.pathname);
-    }
-    catch {
-        // Malformed percent-encoding (e.g. `GET /%`) — never let it throw out of
-        // the request listener and crash the whole multiplexing server (C1).
-        res.writeHead(400, { 'content-type': 'text/plain; charset=utf-8' });
-        res.end('bad request\n');
-        return;
-    }
-    // Resolve within clientDir; reject traversal.
-    const rel = normalize(pathname).replace(/^(\.\.(\/|\\|$))+/, '');
-    let filePath = join(clientDir, rel);
-    if (!filePath.startsWith(clientDir)) {
-        res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
-        res.end('forbidden\n');
-        return;
-    }
-    // Directory or root → index.html. A path with no file extension that does not
-    // exist → SPA fallback to index.html (so deep links like /node/<id> boot).
-    const isFile = existsSync(filePath) && statSync(filePath).isFile();
-    if (!isFile) {
-        filePath = join(clientDir, 'index.html');
-    }
-    if (!existsSync(filePath)) {
-        res.writeHead(503, { 'content-type': 'text/plain; charset=utf-8' });
-        res.end('crtr surface web shell bundle not found — run `npm run build` to emit it into ' +
-            `${clientDir} (or pass --dev for Vite middleware)\n`);
-        return;
-    }
-    res.writeHead(200, { 'content-type': contentTypeFor(filePath), 'cache-control': 'no-cache' });
-    if (req.method === 'HEAD') {
-        res.end();
-        return;
-    }
-    const stream = createReadStream(filePath);
-    stream.on('error', () => {
-        if (!res.headersSent)
-            res.writeHead(500);
-        res.end();
-    });
-    stream.pipe(res);
-}
-/** RFC 7230 §6.1 hop-by-hop headers: meaningful only for a single transport hop,
- *  never forwarded through a proxy. Stripping them keeps this shell's browser↔shell
- *  and shell↔crtrd connection lifetimes independent instead of leaning on Node's
- *  re-framing to paper over a forwarded `Transfer-Encoding`/`Connection` (m5). */
-const HOP_BY_HOP_HEADERS = new Set([
-    'connection',
-    'keep-alive',
-    'proxy-authenticate',
-    'proxy-authorization',
-    'te',
-    'trailer',
-    'transfer-encoding',
-    'upgrade',
-]);
-/** Copy incoming headers minus the hop-by-hop set. Node lowercases incoming
- *  header names, so a lowercase-keyed delete is exhaustive. */
-function withoutHopByHop(headers) {
-    const out = { ...headers };
-    for (const key of HOP_BY_HOP_HEADERS)
-        delete out[key];
-    return out;
-}
-/** Parse a request URL and strip the `token` auth param — it authorizes THIS
- *  shell hop only; forwarding it into crtrd's request path would leak the secret
- *  into crtrd's (loggable) request line, and crtrd doesn't consume it (m4). Any
- *  OTHER query survives (e.g. crtrd's browser-only `?revive=0` opt-out). */
-function stripTokenParam(rawUrl) {
-    const url = new URL(rawUrl, 'http://127.0.0.1');
-    url.searchParams.delete('token');
-    return url;
-}
-/** Proxy a `/v1/*` REST request to crtrd's unix socket. The dev shell adds only
- *  its auth boundary (crtrd applies none) then streams the request body up and
- *  the response back verbatim. No `canvas.db`, no subprocess: pure reverse proxy. */
-function proxyToCrtrd(req, res) {
-    const target = stripTokenParam(req.url ?? '/');
-    const upstream = httpRequest({
-        socketPath: apiSocketPath(),
-        method: req.method,
-        path: `${target.pathname}${target.search}`,
-        headers: withoutHopByHop(req.headers),
-    }, (upstreamRes) => {
-        res.writeHead(upstreamRes.statusCode ?? 502, withoutHopByHop(upstreamRes.headers));
-        upstreamRes.pipe(res);
-    });
-    upstream.on('error', () => {
-        // Once headers are on the wire we can no longer signal an error in-band —
-        // appending a JSON error to a partially-streamed body would corrupt it, so
-        // truncate the response instead (m1). Before headersSent, a clean 502.
-        if (res.headersSent) {
-            res.destroy();
-            return;
-        }
-        res.writeHead(502, { 'content-type': 'application/json; charset=utf-8' });
-        res.end(JSON.stringify({ error: { code: 'daemon_unavailable', message: 'crtrd is not reachable' } }));
-    });
-    // Propagate a browser abort/response-close upstream: without this an aborted
-    // request leaves the crtrd response paused and its in-flight work pinned until
-    // upstream completes on its own (M1). `destroy` on a finished exchange no-ops.
-    res.on('close', () => upstream.destroy());
-    req.pipe(upstream);
-}
-/** Transparently tunnel a browser `/node/<id>` WS upgrade to crtrd's
- *  `GET /v1/nodes/{id}/attach`. The dev shell does NOT terminate the WebSocket:
- *  it opens a raw connection to crtrd's unix socket, forwards the upgrade request
- *  rewritten to the attach path (headers verbatim), and pipes bytes both
- *  directions. crtrd performs the 101 handshake (which flows back through the
- *  tunnel) and owns attach-implies-revive — so the browser is the SAME protocol
- *  peer as `crtr surface attach` and this process only relays. Idempotent
- *  teardown; the tunneled socket is tracked so shutdown can drop it. */
-function tunnelAttachUpgrade(req, socket, head, nodeId, track) {
-    if (!isSafeNodeId(nodeId)) {
-        try {
-            socket.write('HTTP/1.1 400 Bad Request\r\n\r\n');
-            socket.destroy();
-        }
-        catch {
-            /* ignore */
-        }
-        return;
-    }
-    const upstream = createConnection(apiSocketPath());
-    track.add(socket);
-    let tornDown = false;
-    let relayStarted = false;
-    const teardown = () => {
-        if (tornDown)
-            return;
-        tornDown = true;
-        track.delete(socket);
-        if (!socket.destroyed)
-            socket.destroy();
-        if (!upstream.destroyed)
-            upstream.destroy();
-    };
-    upstream.on('connect', () => {
-        // Preserve any non-token query (crtrd honors a browser-only `?revive=0`
-        // opt-out here — a WS handshake can't set the equivalent request header, so
-        // this query is the browser's ONLY channel for it); the token is stripped
-        // for the same reason as the REST proxy (m2/m4).
-        const path = `/v1/nodes/${encodeURIComponent(nodeId)}/attach${stripTokenParam(req.url ?? '/').search}`;
-        const lines = [`GET ${path} HTTP/1.1`];
-        for (let i = 0; i + 1 < req.rawHeaders.length; i += 2) {
-            lines.push(`${req.rawHeaders[i]}: ${req.rawHeaders[i + 1]}`);
-        }
-        try {
-            upstream.write(lines.join('\r\n') + '\r\n\r\n');
-            if (head.length > 0)
-                upstream.write(head);
-        }
-        catch {
-            teardown();
-            return;
-        }
-        relayStarted = true;
-        socket.pipe(upstream);
-        upstream.pipe(socket);
-    });
-    upstream.on('error', () => {
-        // A pre-handshake upstream failure (crtrd down) leaves the browser with a
-        // bare TCP reset, indistinguishable from any other failure. Before any byte
-        // has been relayed, answer a 502 so the browser sees a distinct gateway
-        // error; once relaying is underway a bare reset is the correct WS signal (m3).
-        if (!relayStarted && !tornDown && !socket.destroyed) {
-            try {
-                socket.write('HTTP/1.1 502 Bad Gateway\r\n\r\n');
-            }
-            catch {
-                /* ignore */
-            }
-        }
-        teardown();
-    });
-    socket.on('error', teardown);
-    upstream.on('close', teardown);
-    socket.on('close', teardown);
-}
-/** Build + start the unified web server. Binds the requested host/port and
- *  resolves once the server is listening. Async because --dev awaits a Vite
- *  middleware server before listening. */
-export async function startWebServer(opts) {
-    const host = opts.host ?? '127.0.0.1';
-    const token = opts.token !== undefined && opts.token !== '' ? opts.token : undefined;
-    const dev = opts.dev ?? false;
-    const tokenRequired = !isLoopbackHost(host);
-    if (tokenRequired && (token === undefined || token === '')) {
-        throw new Error(`crtr surface web serve --host ${host} requires --token for remote-capable endpoints`);
-    }
-    const clientDir = resolveClientDir();
-    // The SSE change lane — one hub, fanned to every connected EventSource.
-    const eventHub = startEventHub();
-    // Live `/node/<id>` attach tunnels to crtrd — tracked so shutdown drops them.
-    const activeTunnels = new Set();
-    // Same-origin allowlist: tokenless localhost pages are implicitly allowed,
-    // while a valid relay token can authorize remote/guest route origins that would
-    // otherwise be rejected by originAllowed().
-    let allowedOrigins = new Set();
-    const originAllowed = (origin) => {
-        if (origin === undefined || origin === '')
-            return true;
-        return allowedOrigins.has(origin);
-    };
-    const authorizeRequest = (req) => {
-        if (token !== undefined && requestTokenMatches(req, token)) {
-            return { allowed: true, scope: scopeForToken(token) };
-        }
-        if (tokenRequired)
-            return { allowed: false };
-        if (!originAllowed(req.headers.origin))
-            return { allowed: false };
-        return { allowed: true, scope: 'local' };
-    };
-    // The set of auth scopes this server actually authorizes — the push diff
-    // engine sends ONLY to subscriptions whose authScope is in this set (the same
-    // auth boundary that gates the /v1 proxy, SSE, and attach tunnel). Mirrors authorizeRequest:
-    // a token authorizes scopeForToken(token); a tokenless request is authorized
-    // only when !tokenRequired, as scope 'local'. A record left by a rotated/old
-    // token has a different digest and is therefore excluded.
-    const targetScopes = new Set();
-    if (token !== undefined)
-        targetScopes.add(scopeForToken(token));
-    if (!tokenRequired)
-        targetScopes.add('local');
-    // §push — the server-side web-push registry + diff engine (design D8). One
-    // persisted, auth-scoped subscription registry; one locally-generated VAPID
-    // identity signing every send; one diff engine that re-reads the canvas on
-    // node invalidations received through eventHub.subscribe (no HTTP self-loop)
-    // and pushes done-transition notifications.
-    const pushRegistry = new PushRegistryStore();
-    const pushLastSeen = new PushLastSeenStore();
-    const vapid = loadOrCreateVapidKeypair();
-    webpush.setVapidDetails(vapid.subject, vapid.publicKey, vapid.privateKey);
-    const pushEngine = new PushDiffEngine({
-        registry: pushRegistry,
-        lastSeen: pushLastSeen,
-        // The lean roster (node_id/parent/status/attention_count is exactly the
-        // CanvasNodeRow subset this diff engine needs) instead of the enriched
-        // snapshot — this fires on every 'nodes' invalidation, not on a bounded
-        // interval, so it must never force the enrichRows/per-row getNode pass.
-        readCanvasNodes: async () => {
-            const snap = (await canvasRosterLeaf.run({}));
-            return snap.nodes;
-        },
-        isTargetScope: (s) => targetScopes.has(s),
-        sendPush: async (record, payload) => {
-            try {
-                await webpush.sendNotification({ endpoint: record.endpoint, keys: record.keys }, JSON.stringify(payload));
-                return 'sent';
-            }
-            catch (err) {
-                const statusCode = err.statusCode;
-                return statusCode === 404 || statusCode === 410 ? 'gone' : 'error';
-            }
-        },
-    });
-    // A restart is not an attention event — record current state, send nothing.
-    await pushEngine.seed();
-    const unsubscribePush = eventHub.subscribe((kind) => {
-        if (kind === 'nodes')
-            void pushEngine.onNodesInvalidation();
-    });
-    // Assigned before listen() when --dev; the request handler closes over it.
-    let vite;
-    const httpServer = createHttpServer((req, res) => {
-        try {
-            const url = new URL(req.url ?? '/', 'http://127.0.0.1');
-            const pathname = url.pathname;
-            // The crtrd REST proxy: /v1/* → reverse-proxy to crtrd's unix socket. The
-            // SPA (and any /v1 client) reaches the API THROUGH this dev shell. The
-            // shell owns the auth boundary (crtrd applies none); token-or-origin gated
-            // like the SSE lane and the attach tunnel. No canvas.db, no subprocess.
-            if (pathname === '/v1' || pathname.startsWith('/v1/')) {
-                if (!authorizeRequest(req).allowed) {
-                    res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
-                    res.end('forbidden\n');
-                    return;
-                }
-                proxyToCrtrd(req, res);
-                return;
-            }
-            // The SSE change-invalidation lane: GET /__crtr/events. Token-or-origin
-            // gated too — a foreign page should not even learn the user's graph is
-            // mutating.
-            if (pathname === '/__crtr/events') {
-                if (req.method !== 'GET') {
-                    res.writeHead(405, { 'content-type': 'text/plain; charset=utf-8', allow: 'GET' });
-                    res.end('method not allowed\n');
-                    return;
-                }
-                if (!authorizeRequest(req).allowed) {
-                    res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
-                    res.end('forbidden\n');
-                    return;
-                }
-                eventHub.addClient(res);
-                return;
-            }
-            // §push — the VAPID public key a browser needs to subscribe. Read-only,
-            // non-secret, but behind the same auth boundary as everything else so a
-            // foreign page can't even enumerate the surface.
-            if (pathname === '/__crtr/push/vapid-public-key') {
-                if (req.method !== 'GET') {
-                    res.writeHead(405, { 'content-type': 'text/plain; charset=utf-8', allow: 'GET' });
-                    res.end('method not allowed\n');
-                    return;
-                }
-                if (!authorizeRequest(req).allowed) {
-                    res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
-                    res.end('forbidden\n');
-                    return;
-                }
-                res.writeHead(200, { 'content-type': 'application/json' });
-                res.end(JSON.stringify({ publicKey: vapid.publicKey }));
-                return;
-            }
-            // §push — subscribe (POST) / unsubscribe (DELETE). Validation lives in
-            // parsePush*Body, which rejects oversized/malformed/private/http/file
-            // shapes BEFORE any persistence, throwing PushRequestError with a status.
-            if (pathname === '/__crtr/push/subscribe') {
-                const auth = authorizeRequest(req);
-                if (!auth.allowed) {
-                    res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
-                    res.end('forbidden\n');
-                    return;
-                }
-                const handlePushError = (e) => {
-                    if (e instanceof PushRequestError) {
-                        res.writeHead(e.statusCode, { 'content-type': 'application/json' });
-                        res.end(JSON.stringify({ ok: false, error: e.message }));
-                        return;
-                    }
-                    res.writeHead(500, { 'content-type': 'application/json' });
-                    res.end(JSON.stringify({ ok: false, error: e instanceof Error ? e.message : String(e) }));
-                };
-                if (req.method === 'POST') {
-                    void readBodyCapped(req, pushBodyMaxBytes())
-                        .then((body) => {
-                        const record = parsePushSubscriptionBody(body, auth.scope);
-                        const stored = pushRegistry.upsert(record);
-                        res.writeHead(200, { 'content-type': 'application/json' });
-                        res.end(JSON.stringify({ ok: true, id: stored.id, authScope: stored.authScope }));
-                    })
-                        .catch(handlePushError);
-                    return;
-                }
-                if (req.method === 'DELETE') {
-                    void readBodyCapped(req, pushBodyMaxBytes())
-                        .then((body) => {
-                        const { endpoint } = parsePushDeleteBody(body);
-                        // Scoped: a caller may only delete a subscription it owns.
-                        const deleted = pushRegistry.deleteByEndpoint(endpoint, auth.scope);
-                        res.writeHead(200, { 'content-type': 'application/json' });
-                        res.end(JSON.stringify({ ok: true, deleted }));
-                    })
-                        .catch(handlePushError);
-                    return;
-                }
-                res.writeHead(405, { 'content-type': 'text/plain; charset=utf-8', allow: 'POST, DELETE' });
-                res.end('method not allowed\n');
-                return;
-            }
-            // --dev: Vite middleware owns all remaining asset/HTML serving (incl. its
-            // own SPA fallback). It is mounted AFTER the bridge + SSE checks above, so
-            // those never fall through to Vite.
-            if (vite !== undefined) {
-                vite.middlewares(req, res);
-                return;
-            }
-            // Shipped: static shell bundle + SPA fallback.
-            if (req.method !== 'GET' && req.method !== 'HEAD') {
-                res.writeHead(405, { 'content-type': 'text/plain; charset=utf-8', allow: 'GET, HEAD' });
-                res.end('method not allowed\n');
-                return;
-            }
-            serveStatic(clientDir, req, res);
-        }
-        catch {
-            // Belt-and-suspenders: nothing in the handler should throw now (C1), but a
-            // request listener that throws crashes the whole daemon — never allow it.
-            if (!res.headersSent)
-                res.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' });
-            res.end('internal error\n');
-        }
-    });
-    httpServer.on('upgrade', (req, socket, head) => {
-        // A raw upgrade socket with no 'error' listener throws on a write to a reset
-        // peer — attach one before we ever write/destroy it (n8).
-        socket.on('error', () => {
-            /* peer reset mid-handshake — destroy below or already destroyed */
-        });
-        try {
-            const url = new URL(req.url ?? '/', 'http://127.0.0.1');
-            const nodeId = nodeIdFromPath(url.pathname);
-            if (nodeId === null) {
-                // --dev: Vite's HMR WebSocket shares this HTTP server. Vite registers its
-                // OWN 'upgrade' listener (via server.hmr.server); leave every non-`/node/`
-                // upgrade for it instead of destroying the socket.
-                if (vite !== undefined)
-                    return;
-                socket.write('HTTP/1.1 404 Not Found\r\n\r\n');
-                socket.destroy();
-                return;
-            }
-            if (!authorizeRequest(req).allowed) {
-                socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
-                socket.destroy();
-                return;
-            }
-            // Transparent tunnel to crtrd's attach endpoint — the shell never
-            // terminates the WS; crtrd owns the handshake and attach-implies-revive.
-            tunnelAttachUpgrade(req, socket, head, nodeId, activeTunnels);
-        }
-        catch {
-            // Never let an upgrade-handler throw escape and crash the daemon (C1).
-            try {
-                socket.destroy();
-            }
-            catch {
-                /* ignore */
-            }
-        }
-    });
-    // --dev: create the Vite middleware server BEFORE listen so the request
-    // handler's `vite` is set and Vite's HMR upgrade listener is attached (ours
-    // was added first, so a vite-hmr upgrade hits ours → nodeId null → returns →
-    // Vite's listener handles it).
-    if (dev) {
-        vite = await createDevServer(httpServer);
-    }
-    return new Promise((resolveListening, rejectListening) => {
-        httpServer.once('error', rejectListening);
-        httpServer.listen(opts.port, host, () => {
-            let port;
-            try {
-                const addr = httpServer.address();
-                if (typeof addr !== 'object' || addr === null) {
-                    throw new Error('web server address is unavailable after listen');
-                }
-                port = addr.port;
-                bindWebEventSource(host, port);
-            }
-            catch (error) {
-                httpServer.close(() => {
-                    httpServer.off('error', rejectListening);
-                    rejectListening(error);
-                });
-                httpServer.closeAllConnections();
-                return;
-            }
-            httpServer.off('error', rejectListening);
-            // A server error AFTER listen (e.g. an accept failure) must not be an
-            // unhandled 'error' that crashes the process (n9) — emit + carry on.
-            httpServer.on('error', (err) => {
-                emitEvent({ event: 'web.server.failed', level: 'error', error: err });
-            });
-            const hostUrl = hostForUrl(host);
-            const url = `http://${hostUrl}:${port}`;
-            allowedOrigins = new Set([
-                `http://${hostUrl}:${port}`,
-                `http://127.0.0.1:${port}`,
-                `http://localhost:${port}`,
-            ]);
-            const close = () => new Promise((done) => {
-                unsubscribePush();
-                eventHub.close();
-                void vite?.close().catch(() => {
-                    /* best-effort */
-                });
-                for (const s of activeTunnels) {
-                    try {
-                        s.destroy();
-                    }
-                    catch {
-                        /* ignore */
-                    }
-                }
-                activeTunnels.clear();
-                httpServer.close(() => done());
-                // Idle keep-alive HTTP connections would otherwise keep close()'s
-                // callback from ever firing — drop them so shutdown completes (m4).
-                httpServer.closeAllConnections();
-            });
-            resolveListening({ url, port, clientDir, close });
-        });
-    });
-}