@jxsuite/server 0.32.0 → 0.34.0

package/src/project-server.ts

@@ -0,0 +1,408 @@
+/**
+ * Shared project server factory. Generalizes the chromium variant's ad-hoc in-process Bun.serve
+ * into one createProjectServer() used by the chromium desktop launcher (and, in Phase 7,
+ * electrobun).
+ *
+ * It serves three surfaces from a single loopback-bound Bun.serve:
+ *
+ * - The studio shell + canvas iframe doc + iframe bundle, under a non-colliding studio namespace (so
+ *   a project's own asset tree never collides);
+ * - Project files at their natural URLs (absolute-under-root, root-relative, and public/), each
+ *   contained against path traversal and symlink escape;
+ * - The canonical resolve routes (the jx-resolve and jx-server POST endpoints) plus the WS-RPC
+ *   dispatch, both gated by a per-server token.
+ *
+ * SECURITY MODEL (see the spec's SECURITY block):
+ *
+ * - Loopback bind (127.0.0.1) is the PRIMARY control: other local processes / LAN pages cannot read a
+ *   loopback page's location, so they cannot steal the URL token.
+ * - The token is the HARD gate on every privileged surface — the WS upgrade and the two HTTP resolve
+ *   routes (which both do dynamic import() and are therefore RCE-capable).
+ * - Origin/Host is BEST-EFFORT defense-in-depth: a loopback Origin host {127.0.0.1, localhost, ::1}
+ *   or an absent Origin is accepted; the privileged HTTP routes additionally reject a Host header
+ *   that is not loopback (anti-DNS-rebinding).
+ * - File reads and the project write-path are contained with a lexical relative() check plus a
+ *   realpath re-check (symlink containment).
+ */
+
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { realpathSync } from "node:fs";
+import { handleResolve, handleServerFunction } from "./resolve.ts";
+import { handleAiApi } from "./ai-api.ts";
+import { resolveNpmPath } from "./server.ts";
+
+/** A resolved per-window session: its project root plus its RPC handler map. */
+export interface ProjectServerSession {
+  projectRoot: string | null;
+  handlers: Record<string, (params: unknown) => Promise<unknown>>;
+}
+
+export interface CreateProjectServerOptions {
+  /**
+   * Resolve the session for a given window id (the `win` query param / stashed socket data).
+   * chromium passes `() => defaultSession`; electrobun (Phase 7) swaps it for a per-window lookup.
+   * A missing/unknown window returns `null`, which the routes treat as a 404 fail-closed.
+   */
+  resolveSession: (winId: string | null) => ProjectServerSession | null;
+  /** Absolute dir holding the studio shell + canvas.html + dist/. */
+  studioDir: string;
+  /** Per-server RPC token. Defaults to a fresh random UUID. */
+  rpcToken?: string;
+  /** Bind hostname. Defaults to loopback 127.0.0.1. */
+  hostname?: string;
+  /** Bind port. Defaults to 0 (ephemeral). */
+  port?: number;
+}
+
+export interface ProjectServerHandle {
+  server: ReturnType<typeof Bun.serve>;
+  url: string;
+  wsUrl: string;
+  rpcToken: string;
+  canvasUrl: string;
+  stop: () => void;
+}
+
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+
+/** True when a hostname (no port) is a loopback host. Used for best-effort Origin/Host checks. */
+function isLoopbackHost(host: string | null | undefined): boolean {
+  if (!host) {
+    return false;
+  }
+  // Strip a trailing :port (but keep bracketed IPv6 intact for the literal set).
+  let h = host;
+  if (h.startsWith("[")) {
+    const end = h.indexOf("]");
+    h = end === -1 ? h : h.slice(0, end + 1);
+  } else {
+    const colon = h.indexOf(":");
+    if (colon !== -1) {
+      h = h.slice(0, colon);
+    }
+  }
+  return LOOPBACK_HOSTS.has(h.toLowerCase());
+}
+
+/**
+ * Best-effort loopback Origin/Host check (defense-in-depth, not the hard gate).
+ *
+ * Accept when the Origin's host is loopback OR Origin is absent (Bun-native / test clients send no
+ * Origin). Do NOT hardcode-match one literal origin — localhost and 127.0.0.1 are distinct origins,
+ * and a too-strict check would 403 legitimate clients.
+ */
+function originIsLoopbackOrAbsent(req: Request): boolean {
+  const origin = req.headers.get("origin");
+  if (!origin) {
+    return true;
+  }
+  try {
+    return isLoopbackHost(new URL(origin).hostname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reject a Host header that is present and NOT loopback (defeats DNS-rebinding, where Host is the
+ * attacker domain). An absent Host (Bun-native clients) is accepted.
+ */
+function hostIsLoopbackOrAbsent(req: Request): boolean {
+  const host = req.headers.get("host");
+  if (!host) {
+    return true;
+  }
+  return isLoopbackHost(host);
+}
+
+/** Normalize a path for cross-platform containment comparison (separators + case on Windows). */
+function normalizeForCompare(p: string): string {
+  const slashed = p.replaceAll("\\", "/");
+  return process.platform === "win32" ? slashed.toLowerCase() : slashed;
+}
+
+/**
+ * Contain `absPath` within `root`: a lexical relative() check followed by a realpath re-check so a
+ * symlink inside the tree cannot point outside it. Returns the (possibly realpath'd) absolute path
+ * when contained, or null otherwise. The caller must already have decoded the URL pathname.
+ */
+function containedPath(absPath: string, root: string): string | null {
+  // (1) Lexical containment.
+  const rel = relative(root, absPath);
+  if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    return null;
+  }
+  // (2) realpath BOTH and re-check the realpath is still under realRoot (symlink containment).
+  let realRoot: string;
+  let realPath: string;
+  try {
+    realRoot = realpathSync(root);
+  } catch {
+    // Root itself is unresolvable: fall back to lexical-only containment.
+    return absPath;
+  }
+  try {
+    realPath = realpathSync(absPath);
+  } catch {
+    // Target does not exist yet — lexical containment already passed; let the caller's existence
+    // Check decide. (Reads will 404; the write-path resolves its own parent separately.)
+    return absPath;
+  }
+  const nRoot = normalizeForCompare(realRoot);
+  const nPath = normalizeForCompare(realPath);
+  if (nPath === nRoot || nPath.startsWith(nRoot.endsWith("/") ? nRoot : `${nRoot}/`)) {
+    return realPath;
+  }
+  return null;
+}
+
+/**
+ * Serve a file under studioDir (or any root) if it both exists and is contained. Returns the
+ * Response, or null when missing/traversed (caller decides the fallthrough status).
+ */
+async function serveContained(absPath: string, root: string): Promise<Response | null> {
+  const safe = containedPath(absPath, root);
+  if (!safe) {
+    return null;
+  }
+  const file = Bun.file(safe);
+  if (await file.exists()) {
+    return new Response(file);
+  }
+  return null;
+}
+
+/**
+ * Try to serve a project file at its natural URL: absolute-under-root, then root-relative, then
+ * public/. Each candidate goes through containedPath (realpath). `decodedPath` is the once-decoded
+ * URL pathname (leading slash, forward slashes).
+ */
+async function serveProjectFile(decodedPath: string, root: string): Promise<Response | null> {
+  // Map the URL pathname back to a filesystem path. On Windows the browser requests an absolute
+  // Path as /C:/Users/… (leading slash + forward slashes); drop the slash before the drive letter.
+  // A POSIX absolute path arrives as //abs/path.
+  const fsPath = decodedPath.startsWith("//")
+    ? decodedPath.slice(1)
+    : decodedPath.replace(/^\/([A-Za-z]:)/, "$1");
+
+  // 1. Absolute path that falls under the project root.
+  if (normalizeForCompare(fsPath).startsWith(normalizeForCompare(root))) {
+    const res = await serveContained(fsPath, root);
+    if (res) {
+      return res;
+    }
+  }
+
+  // 2. Root-relative.
+  const relRes = await serveContained(resolve(root, `.${decodedPath}`), root);
+  if (relRes) {
+    return relRes;
+  }
+
+  // 3. public/ subdirectory.
+  const pubRes = await serveContained(resolve(root, "public", `.${decodedPath}`), root);
+  if (pubRes) {
+    return pubRes;
+  }
+
+  return null;
+}
+
+/**
+ * Create and start a shared project server bound to loopback.
+ *
+ * @param options See {@link CreateProjectServerOptions}.
+ * @returns A handle with the bound url/wsUrl, the rpcToken, the canvas iframe URL, and stop().
+ */
+export function createProjectServer(options: CreateProjectServerOptions): ProjectServerHandle {
+  const {
+    resolveSession,
+    studioDir,
+    rpcToken = crypto.randomUUID(),
+    hostname = "127.0.0.1",
+    port = 0,
+  } = options;
+
+  // Bundle cache for npm bare specifiers (mirrors server.ts).
+  const bundleCache = new Map<string, string>();
+
+  const server = Bun.serve<{ winId: string | null }>({
+    hostname,
+    port,
+    // Keep SSE/AI streams alive (mirrors the dev server's generous idle timeout).
+    idleTimeout: 120,
+    async fetch(req, srv) {
+      const url = new URL(req.url);
+      // Decode the pathname ONCE, then run ALL containment on the decoded path. Reject a path that
+      // Still contains an encoded dot/slash after one decode (over-encoding bypass attempt).
+      let path: string;
+      try {
+        path = decodeURIComponent(url.pathname);
+      } catch {
+        return new Response("Bad request", { status: 400 });
+      }
+      if (/%2e|%2f/i.test(path)) {
+        return new Response("Not found", { status: 404 });
+      }
+      // Collapse runs of leading slashes to a single one. The natural-URL branch re-expands a POSIX
+      // //abs prefix explicitly, so a single leading slash here is the right normal form.
+      const normPath = path.replace(/^\/{2,}/, "/");
+
+      const winId = url.searchParams.get("win");
+
+      // 1. WebSocket upgrade — token + loopback Origin/Host are the hard gate.
+      const upgrade = req.headers.get("upgrade");
+      if (upgrade && upgrade.toLowerCase() === "websocket") {
+        const token = url.searchParams.get("token");
+        if (token !== rpcToken || !originIsLoopbackOrAbsent(req) || !hostIsLoopbackOrAbsent(req)) {
+          return new Response("Forbidden", { status: 403 });
+        }
+        if (srv.upgrade(req, { data: { winId } })) {
+          return;
+        }
+        return new Response("Upgrade failed", { status: 400 });
+      }
+
+      // 2. AI SSE — keep the existing handleAiApi behavior (rewrite the studio-ai prefix).
+      if (normPath.startsWith("/__studio__/ai/")) {
+        const aiUrl = new URL(req.url);
+        aiUrl.pathname = normPath.replace("/__studio__/ai/", "/__studio/ai/");
+        const aiResponse = await handleAiApi(req, aiUrl);
+        if (aiResponse) {
+          return aiResponse;
+        }
+      }
+
+      // 3. Studio assets under the non-colliding /__studio__/ namespace.
+      if (normPath.startsWith("/__studio__/")) {
+        const assetRel = normPath.slice("/__studio__/".length);
+        const assetPath = resolve(studioDir, `.${sep}${assetRel}`);
+        const res = await serveContained(assetPath, studioDir);
+        if (res) {
+          // Never leak the tokened URL cross-origin via Referer, while keeping same-origin requests
+          // Normal. MUST be `same-origin`, not `no-referrer`: under `no-referrer` Chromium serializes
+          // The Origin header of the canvas iframe's own same-origin POSTs as `null` (Fetch spec
+          // Origin-serialization respects referrer policy), which fails originIsLoopbackOrAbsent and
+          // Self-403s /__jx_resolve__ + /__jx_server__ from the very document this server serves.
+          const headers = new Headers(res.headers);
+          headers.set("Referrer-Policy", "same-origin");
+          return new Response(res.body, { headers, status: res.status });
+        }
+        return new Response("Not found", { status: 404 });
+      }
+
+      // 4. Resolve the session (fail-closed).
+      const session = resolveSession(winId);
+      if (!session) {
+        return new Response("Unknown window", { status: 404 });
+      }
+      const root = session.projectRoot;
+      if (!root) {
+        return new Response("No project", { status: 404 });
+      }
+
+      // 5. Privileged HTTP routes (RCE-capable: dynamic import()). Gate with token + loopback
+      //    Origin/Host BEFORE dispatch.
+      if (
+        (normPath === "/__jx_resolve__" || normPath === "/__jx_server__") &&
+        req.method === "POST"
+      ) {
+        const token = url.searchParams.get("token");
+        if (token !== rpcToken || !originIsLoopbackOrAbsent(req) || !hostIsLoopbackOrAbsent(req)) {
+          return new Response("Forbidden", { status: 403 });
+        }
+        if (normPath === "/__jx_resolve__") {
+          return handleResolve(req, root, root);
+        }
+        return handleServerFunction(req, root);
+      }
+
+      // 6. Project files at natural URLs.
+      const fileRes = await serveProjectFile(normPath, root);
+      if (fileRes) {
+        return fileRes;
+      }
+
+      // 7. npm bare specifiers via node_modules (on-demand bundle, mirrors server.ts).
+      const resolved = resolveNpmPath(root, normPath);
+      if (resolved) {
+        if (!bundleCache.has(resolved)) {
+          try {
+            const result = await Bun.build({
+              entrypoints: [resolved],
+              format: "esm",
+              minify: false,
+            });
+            if (result.success && result.outputs.length > 0) {
+              bundleCache.set(resolved, await result.outputs[0]!.text());
+            }
+          } catch (error) {
+            console.error("Bundle failed for", resolved, error);
+          }
+        }
+        const bundled = bundleCache.get(resolved);
+        if (bundled) {
+          return new Response(bundled, {
+            headers: { "Content-Type": "application/javascript; charset=utf-8" },
+          });
+        }
+      }
+
+      return new Response("Not found", { status: 404 });
+    },
+
+    websocket: {
+      async message(ws, raw) {
+        let msg: { id: number; method: string; params?: unknown };
+        try {
+          msg = JSON.parse(raw as string) as { id: number; method: string; params?: unknown };
+        } catch {
+          ws.send(JSON.stringify({ error: "Invalid JSON", id: 0 }));
+          return;
+        }
+
+        // Re-resolve the session FRESH each message (fail-closed for Phase 7 multi-window).
+        const session = resolveSession(ws.data.winId);
+        if (!session) {
+          ws.send(JSON.stringify({ error: "Unknown window", id: msg.id }));
+          ws.close();
+          return;
+        }
+
+        const handler = session.handlers[msg.method];
+        if (!handler) {
+          ws.send(JSON.stringify({ error: `Unknown method: ${msg.method}`, id: msg.id }));
+          return;
+        }
+
+        try {
+          const result = await handler(msg.params);
+          ws.send(JSON.stringify({ id: msg.id, result: result ?? null }));
+        } catch (error: unknown) {
+          ws.send(
+            JSON.stringify({
+              error: error instanceof Error ? error.message : String(error),
+              id: msg.id,
+            }),
+          );
+        }
+      },
+    },
+  });
+
+  const boundHost = hostname.includes(":") ? `[${hostname}]` : hostname;
+  const url = `http://${boundHost}:${server.port}`;
+  const wsUrl = `ws://${boundHost}:${server.port}`;
+  const canvasUrl = `${url}/__studio__/canvas.html`;
+
+  return {
+    server,
+    url,
+    wsUrl,
+    rpcToken,
+    canvasUrl,
+    stop: () => {
+      void server.stop(true);
+    },
+  };
+}

package/src/server.ts

@@ -19,6 +19,7 @@ import { createWatcher, injectSSE } from "./watch.ts";
 import { handleResolve, handleServerFunction } from "./resolve.ts";
 import { handleStudioApi } from "./studio-api.ts";
 import { handleCodeApi } from "./code-api.ts";
+import { handleAiApi } from "./ai-api.ts";
 import { existsSync, readFileSync } from "node:fs";
 
 /**
@@ -211,6 +212,14 @@ export async function createDevServer(options: {
   // Bundle cache for npm packages (bare specifier → bundled JS)
   const bundleCache = new Map<string, string>();
 
+  // Dev-server cache policy: always revalidate. Without any Cache-Control the browser HEURISTICALLY
+  // Caches responses (there are no validators either), so a plain reload can serve a stale
+  // Studio.js/canvas bundle — which shows up as half-updated UI after a rebuild (the iframe assets
+  // Are query-cache-busted per mount, the parent bundle is not).
+  const NO_CACHE = { "Cache-Control": "no-cache" };
+  const fileResponse = (file: ReturnType<typeof Bun.file>) =>
+    new Response(file, { headers: NO_CACHE });
+
   // Active studio project root (set via /__studio/activate, used for static file fallback)
   let activeProjectRoot: string | null = null;
 
@@ -252,6 +261,12 @@ export async function createDevServer(options: {
           return Response.json({ ok: true, root: activeProjectRoot });
         }
 
+        // AI proxy endpoints (/__studio/ai/chat, /__studio/ai/models)
+        const aiRes = await handleAiApi(req, url);
+        if (aiRes) {
+          return aiRes;
+        }
+
         const codeRes = await handleCodeApi(req, url);
         if (codeRes) {
           return codeRes;
@@ -282,7 +297,7 @@ export async function createDevServer(options: {
       if (activeProjectRoot && normSep(fsPath).startsWith(normSep(activeProjectRoot))) {
         const file = Bun.file(fsPath);
         if (await file.exists()) {
-          return new Response(file);
+          return fileResponse(file);
         }
       }
 
@@ -292,12 +307,12 @@ export async function createDevServer(options: {
         if (activeProjectRoot) {
           const projectFile = Bun.file(resolve(activeProjectRoot, `.${path}`));
           if (await projectFile.exists()) {
-            return new Response(projectFile);
+            return fileResponse(projectFile);
           }
           // Mirror production: public/ contents are served at root
           const publicFile = Bun.file(resolve(activeProjectRoot, "public", `.${path}`));
           if (await publicFile.exists()) {
-            return new Response(publicFile);
+            return fileResponse(publicFile);
           }
         }
 
@@ -324,6 +339,7 @@ export async function createDevServer(options: {
           if (bundled) {
             return new Response(bundled, {
               headers: {
+                ...NO_CACHE,
                 "Content-Type": "application/javascript; charset=utf-8",
               },
             });
@@ -332,17 +348,24 @@ export async function createDevServer(options: {
         return new Response("Not found", { status: 404 });
       }
 
-      if (handleSSE && path.endsWith(".html")) {
+      // Inject the live-reload script into served HTML — but NOT into the Studio editor.
+      // Studio manages its own state (open tabs, undo history, chat) and refreshes edited
+      // Files in-place; a blanket location.reload() would destroy that, e.g. when the AI
+      // Assistant writes a file matching a build glob inside the watched root.
+      if (handleSSE && path.endsWith(".html") && !path.startsWith("/packages/studio/")) {
         const html = await file.text();
         return new Response(injectSSE(html), {
-          headers: { "Content-Type": "text/html; charset=utf-8" },
+          headers: { ...NO_CACHE, "Content-Type": "text/html; charset=utf-8" },
         });
       }
 
-      return new Response(file);
+      return fileResponse(file);
     },
 
     port,
+    // Keep SSE connections alive — heartbeats are every 15 s, and AI streaming can take
+    // 30+ s. The default 10 s idleTimeout kills them prematurely.
+    idleTimeout: 120,
   });
 
   console.log(`\n@jxsuite/server listening on http://localhost:${server.port}`);

package/src/studio-api.ts

@@ -21,7 +21,6 @@ import {
   setPackageVersions,
 } from "./packages.ts";
 import type { FormatRegistry } from "@jxsuite/schema/format-registry";
-import * as claude from "./claude-session.ts";
 import type { ClassJsonDef } from "./types.ts";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 
@@ -1438,79 +1437,6 @@ export async function handleStudioApi(
     }
   }
 
-  // ─── AI Assistant ─────────────────────────────────────────────────────────
-
-  if (path === "/__studio/ai/auth-status" && req.method === "GET") {
-    const status = await claude.getAuthStatus();
-    return Response.json(status);
-  }
-
-  if (path === "/__studio/ai/session" && req.method === "POST") {
-    try {
-      const body = (await req.json()) as { message?: string; systemPrompt?: string };
-      const projectDir = activeProjectRoot || root;
-      const opts: { systemPrompt?: string } = {};
-      if (body.systemPrompt !== undefined) {
-        opts.systemPrompt = body.systemPrompt;
-      }
-      const result = claude.createSession(projectDir, body.message!, opts);
-      return Response.json(result);
-    } catch (error) {
-      return Response.json(
-        { error: error instanceof Error ? error.message : String(error) },
-        { status: 500 },
-      );
-    }
-  }
-
-  if (
-    path.startsWith("/__studio/ai/session/") &&
-    path.endsWith("/stream") &&
-    req.method === "GET"
-  ) {
-    const id = path.split("/").slice(4)[0]!;
-    return claude.streamSession(id);
-  }
-
-  if (
-    path.startsWith("/__studio/ai/session/") &&
-    path.endsWith("/message") &&
-    req.method === "POST"
-  ) {
-    try {
-      const id = path.split("/").slice(4)[0]!;
-      const body = (await req.json()) as { message?: string };
-      claude.sendMessage(id, body.message!);
-      return Response.json({ ok: true });
-    } catch (error) {
-      return Response.json(
-        { error: error instanceof Error ? error.message : String(error) },
-        { status: 500 },
-      );
-    }
-  }
-
-  if (path.startsWith("/__studio/ai/session/") && path.endsWith("/stop") && req.method === "POST") {
-    const id = path.split("/").slice(4)[0]!;
-    claude.stopSession(id);
-    return Response.json({ ok: true });
-  }
-
-  if (path.startsWith("/__studio/ai/session/") && req.method === "DELETE") {
-    const id = path.split("/").slice(4)[0]!;
-    claude.deleteSession(id);
-    return Response.json({ ok: true });
-  }
-
-  if (path.startsWith("/__studio/ai/session/") && req.method === "GET") {
-    const id = path.split("/").slice(4)[0]!;
-    const info = claude.getSession(id);
-    if (!info) {
-      return Response.json({ error: "Not found" }, { status: 404 });
-    }
-    return Response.json(info);
-  }
-
   return null;
 }
 

package/src/watch.ts

@@ -16,6 +16,9 @@ const DEFAULT_IGNORE = [
   "**/.direnv/**",
   "**/bun.lockb",
   "**/bun.lock",
+  // Bun test temporary directories — created/deleted transiently, cause EINVAL on
+  // Fs.watch when cleaned up mid-scan.
+  "**/__test-*/**",
 ];
 
 /** @param {string} value */
@@ -186,5 +189,14 @@ export function createWatcher(
     }, debounceMs);
   });
 
+  // Gracefully handle watch errors (e.g. EINVAL on transient Bun test dirs).
+  watcher.on("error", (err) => {
+    const error = err as Error;
+    if (error.message?.includes("EINVAL")) {
+      return;
+    }
+    console.error("[watch] chokidar error:", error.message ?? error);
+  });
+
   return { broadcast, broadcastEvent, handleSSE, watcher };
 }