@jxsuite/server 2.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -20,6 +20,8 @@
     "./import-api": "./src/import-api.ts",
     "./packages": "./src/packages.ts",
     "./project-server": "./src/project-server.ts",
+    "./oauth-loopback": "./src/oauth-loopback.ts",
+    "./site-preview": "./src/site-preview.ts",
     "./refactor": "./src/refactor/index.ts",
     "./resolve": "./src/resolve.ts",
     "./types": "./src/types.ts",
@@ -30,26 +32,27 @@
     "provenance": true
   },
   "scripts": {
-    "upgrade": "bunx npm-check-updates -u && bun install",
-    "test": "bun test --isolate",
-    "test:coverage": "bun test --isolate --coverage"
+    "lint:errors": "bun run scripts/check-error-shapes.ts",
+    "test": "bun run lint:errors && bun test --isolate",
+    "test:coverage": "bun run lint:errors && bun test --isolate --coverage",
+    "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "dependencies": {
-    "@jxsuite/collab": "^0.6.0",
-    "@jxsuite/compiler": "^1.5.0",
-    "@jxsuite/create": "^1.2.2",
-    "@jxsuite/import": "^0.38.2",
-    "@jxsuite/protocol": "^1.0.0",
-    "@jxsuite/runtime": "^1.3.2",
-    "@jxsuite/schema": "^1.5.0",
-    "@jxsuite/starters": "^1.2.2",
+    "@jxsuite/collab": "^0.7.0",
+    "@jxsuite/compiler": "^2.0.0",
+    "@jxsuite/create": "^1.3.0",
+    "@jxsuite/import": "^0.39.0",
+    "@jxsuite/protocol": "^1.1.0",
+    "@jxsuite/runtime": "^2.0.0",
+    "@jxsuite/schema": "^1.6.0",
+    "@jxsuite/starters": "^1.3.0",
     "chokidar": "^5.0.0",
-    "kysely": "^0.29.4",
+    "kysely": "^0.29.5",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@jxsuite/auth": "^0.4.2",
-    "@jxsuite/connector": "^0.4.2",
-    "@jxsuite/parser": "^1.4.1"
+    "@jxsuite/auth": "^0.5.0",
+    "@jxsuite/connector": "^0.5.0",
+    "@jxsuite/parser": "^1.5.0"
   }
 }

package/src/ai-api.ts

@@ -19,6 +19,8 @@
  *
  * @license MIT
  */
+import { problem, problemTypeForStatus } from "./problem.ts";
+import { problemDetails } from "@jxsuite/protocol";
 
 // ─── Configuration ───────────────────────────────────────────────────────────
 
@@ -141,15 +143,15 @@ function writeSSE(controller: ReadableStreamDefaultController, event: unknown):
   controller.enqueue(new TextEncoder().encode(`data: ${data}\n\n`));
 }
 
-/** Write a JSON error response (for non-streaming endpoints and error cases). */
+/**
+ * Write a failure response for the non-streaming endpoints.
+ *
+ * The status is chosen by the caller here rather than by the type, because this file's callers
+ * forward an upstream provider's status — which is information, and collapsing it to the type's own
+ * would throw it away.
+ */
 function jsonError(status: number, message: string): Response {
-  return Response.json(
-    { error: message },
-    {
-      status,
-      headers: { "Content-Type": "application/json" },
-    },
-  );
+  return problem(problemTypeForStatus(status), message);
 }
 
 // ─── /__studio/ai/chat — SSE streaming proxy ───────────────────────────────
@@ -233,9 +235,16 @@ export async function handleChat(req: Request): Promise<Response> {
         if ((error as Error).name === "AbortError") {
           writeSSE(controller, { type: "done", stopReason: "cancelled" });
         } else {
+          const message = `Network error: ${(error as Error).message}`;
           writeSSE(controller, {
+            message,
+            /*
+             * The frame carries a problem rather than being one: the response began with a 200
+             * long before this failed, so nothing can change the status now. `message` stays for
+             * the readers that already show it (server.md §4.3).
+             */
+            problem: problemDetails("upstreamFailure", message),
             type: "error",
-            message: `Network error: ${(error as Error).message}`,
           });
         }
         controller.close();
@@ -264,9 +273,11 @@ export async function handleChat(req: Request): Promise<Response> {
           /* Not JSON — use the raw body. */
         }
         writeSSE(controller, {
-          type: "error",
-          message: cleanMessage,
           code: String(response.status),
+          message: cleanMessage,
+          // The upstream's own status is preserved in `code`; the problem names the KIND.
+          problem: problemDetails(problemTypeForStatus(response.status), cleanMessage),
+          type: "error",
         });
         controller.close();
         return;
@@ -274,7 +285,11 @@ export async function handleChat(req: Request): Promise<Response> {
 
       const reader = response.body?.getReader();
       if (!reader) {
-        writeSSE(controller, { type: "error", message: "No response body from upstream" });
+        writeSSE(controller, {
+          message: "No response body from upstream",
+          problem: problemDetails("upstreamFailure", "No response body from upstream"),
+          type: "error",
+        });
         controller.close();
         return;
       }
@@ -407,9 +422,11 @@ export async function handleChat(req: Request): Promise<Response> {
           controller.close();
           return;
         }
+        const message = `Stream error: ${(error as Error).message}`;
         writeSSE(controller, {
+          message,
+          problem: problemDetails("upstreamFailure", message),
           type: "error",
-          message: `Stream error: ${(error as Error).message}`,
         });
         controller.close();
       }

package/src/code-api.ts

@@ -11,6 +11,7 @@ import { dirname, join } from "node:path";
 import { existsSync } from "node:fs";
 import { unlink } from "node:fs/promises";
 import { format } from "oxfmt";
+import { problem } from "./problem.ts";
 
 interface OxcLabel {
   span: { offset: number; line: number; [key: string]: unknown };
@@ -121,7 +122,7 @@ export async function handleCodeApi(req: Request, url: URL) {
   try {
     body = (await req.json()) as CodeApiBody;
   } catch {
-    return new Response("Invalid JSON", { status: 400 });
+    return problem("invalidRequest", "Invalid JSON");
   }
 
   const action = path.slice("/__studio/code/".length);

package/src/collab.ts

@@ -17,9 +17,15 @@ import { resolve } from "node:path";
 import { readFile, writeFile } from "node:fs/promises";
 import { colorForKey } from "@jxsuite/collab/awareness-types";
 import { createCollabHost } from "@jxsuite/collab/room";
+import {
+  COLLAB_SUBPROTOCOL,
+  offeredSubprotocols,
+  selectSubprotocol,
+} from "@jxsuite/collab/negotiate";
 import { assertAccessible } from "./studio-api";
 import type { ServerWebSocket, WebSocketHandler } from "bun";
 import type { HostConnection } from "@jxsuite/collab/room";
+import { problem } from "./problem.ts";
 
 const EMPTY_ROOM_GRACE_MS = 30_000;
 
@@ -64,7 +70,12 @@ export interface CollabRegistry {
    */
   handleRequest: (
     req: Request,
-    server: { upgrade: (req: Request, opts: { data: CollabSocketData }) => boolean },
+    server: {
+      upgrade: (
+        req: Request,
+        opts: { data: CollabSocketData; headers?: Record<string, string> },
+      ) => boolean;
+    },
   ) => Response | undefined;
   /** Bun.serve websocket handlers backing the upgraded connections. */
   websocket: WebSocketHandler<CollabSocketData>;
@@ -192,10 +203,30 @@ export function createCollabRegistry(opts: {
 
     handleRequest(req, server) {
       if (req.headers.get("upgrade")?.toLowerCase() === "websocket") {
-        const upgraded = server.upgrade(req, { data: { connection: null } });
-        return upgraded ? undefined : new Response("Upgrade failed", { status: 400 });
+        /*
+         * RFC 6455 §4.2.2: echo one of the tokens the client offered, or none if it offered none.
+         * An offer we cannot satisfy is refused outright rather than upgraded — two peers whose
+         * envelopes disagree about merge granularity must not share a room, and a 400 here is a
+         * better outcome than the divergent-history merge that would follow.
+         */
+        const answer = selectSubprotocol(
+          offeredSubprotocols(req.headers.get("sec-websocket-protocol")),
+        );
+        if (answer.reject !== null) {
+          return problem("invalidRequest", answer.reject);
+        }
+        const upgraded = server.upgrade(req, {
+          data: { connection: null },
+          ...(answer.echo === null ? {} : { headers: { "Sec-WebSocket-Protocol": answer.echo } }),
+        });
+        return upgraded ? undefined : problem("invalidRequest", "Upgrade failed");
       }
-      return Response.json({ collab: true, version: 1 });
+      /*
+       * The capability probe, which is also the negotiation input: a client learns here what this
+       * server speaks, because offering a subprotocol the server cannot echo would fail the
+       * handshake (RFC 6455 §4.1) rather than degrade. `version` stays for older clients.
+       */
+      return Response.json({ collab: true, protocols: [COLLAB_SUBPROTOCOL], version: 1 });
     },
 
     async stop() {

package/src/data-api.ts

@@ -45,6 +45,7 @@ import type {
   SecretsSetRequest,
   SecretsSetResponse,
 } from "@jxsuite/protocol";
+import { problem, problemTypeForStatus } from "./problem.ts";
 
 // ─── Local section shapes (structural — the connector owns the full types) ───
 
@@ -868,7 +869,13 @@ export async function handleDataApi(
       }
     }
   } catch (error) {
+    /*
+     * The one place a status is computed rather than named, so the TYPE is derived from it here
+     * instead of at each throw. `ApiError` predates the registry and carries only a status; mapping
+     * it once keeps the alternative — a `ProblemTypeName` threaded through every throw site — out
+     * of a file whose failures are all shapes of "the request was wrong".
+     */
     const status = error instanceof ApiError ? error.status : 500;
-    return Response.json({ error: errorMessage(error) }, { status });
+    return problem(problemTypeForStatus(status), errorMessage(error));
   }
 }

package/src/import-api.ts

@@ -22,6 +22,7 @@
 
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { problem } from "./problem.ts";
 
 export interface ImportApiOptions {
   /**
@@ -81,15 +82,15 @@ async function handleImportSite(req: Request, opts: ImportApiOptions): Promise<R
   try {
     body = (await req.json()) as ImportRequestBody;
   } catch {
-    return Response.json({ error: "Invalid JSON body" }, { status: 400 });
+    return problem("invalidRequest", "Invalid JSON body");
   }
 
   const { url, directory } = body;
   if (!url || !directory) {
-    return Response.json({ error: "url and directory are required" }, { status: 400 });
+    return problem("invalidRequest", "url and directory are required");
   }
   if (!url.startsWith("http://") && !url.startsWith("https://")) {
-    return Response.json({ error: "url must start with http:// or https://" }, { status: 400 });
+    return problem("invalidRequest", "url must start with http:// or https://");
   }
 
   let destPath: string;
@@ -97,7 +98,7 @@ async function handleImportSite(req: Request, opts: ImportApiOptions): Promise<R
     destPath = opts.resolveDest(directory);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    return Response.json({ error: message }, { status: 400 });
+    return problem("invalidRequest", message);
   }
 
   const depth = clamp(body.depth ?? 1, 0, MAX_DEPTH);

package/src/jx-mounts.ts

@@ -59,6 +59,17 @@ export async function handleJxMounts(
   if (!runtime) {
     return null;
   }
+  /*
+   * Pin the dev server's own origin, once, unless the project already set one.
+   *
+   * This is what makes "is this deployment served over HTTPS" answerable rather than guessed. The
+   * auth mount derives its cookie prefix and `Secure` flag from the scheme and defaults to secure,
+   * because on Cloudflare Workers there is no other signal — so the plain-HTTP case has to say so,
+   * and the dev server is the only host that is one. Setting it here rather than in `buildRuntime`
+   * is deliberate: the port is not known until a request arrives. It also pins social-provider
+   * callbacks to the right origin in dev, which they were previously deriving per request.
+   */
+  runtime.env["BETTER_AUTH_URL"] ??= url.origin;
   for (const { basePath, handler } of runtime.handlers) {
     if (url.pathname === basePath || url.pathname.startsWith(`${basePath}/`)) {
       return handler(req, runtime.env);

package/src/net-guard.ts

@@ -20,26 +20,47 @@ import { isAbsolute, relative, resolve, sep } from "node:path";
 import { realpathSync } from "node:fs";
 import { resolveAssetUrl } from "@jxsuite/schema/asset-paths";
 import type { AssetMount } from "@jxsuite/schema/asset-paths";
+import { problem } from "./problem.ts";
 
 export const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
 
+/**
+ * The whole loopback block, not just `127.0.0.1`.
+ *
+ * IANA reserves `127.0.0.0/8` (RFC 1122 §3.2.1.3), and every address in it is the same machine —
+ * `127.0.0.2` reaches this process exactly as `127.0.0.1` does. A gate that recognized only the
+ * canonical spelling would reject a client that used any other, while granting nothing: an attacker
+ * who can send from `127.0.0.53` is already on the host.
+ */
+const IPV4_LOOPBACK = /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
+
+/**
+ * The unspecified address, accepted as a **Host** and never as an **Origin**.
+ *
+ * As a Host it is ordinary: a server bound to `0.0.0.0` inside a container is reached at that
+ * literal, and the request is as local as any other. As an Origin it is meaningless — no page is
+ * ever served from `http://0.0.0.0` — so a request claiming it is either confused or probing, and
+ * treating the two positions alike would widen the gate for nothing.
+ */
+const UNSPECIFIED_HOST = "0.0.0.0";
+
+/** Strip a trailing `:port`, keeping a bracketed IPv6 literal intact. */
+function bareHost(host: string): string {
+  if (host.startsWith("[")) {
+    const end = host.indexOf("]");
+    return end === -1 ? host : host.slice(0, end + 1);
+  }
+  const colon = host.indexOf(":");
+  return colon === -1 ? host : host.slice(0, colon);
+}
+
 /** True when a hostname (optionally with :port) is a loopback host. */
 export 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());
+  const h = bareHost(host).toLowerCase();
+  return LOOPBACK_HOSTS.has(h) || IPV4_LOOPBACK.test(h);
 }
 
 /**
@@ -53,6 +74,7 @@ export function originIsLoopbackOrAbsent(req: Request): boolean {
     return true;
   }
   try {
+    // Deliberately NOT accepting the unspecified address here; see UNSPECIFIED_HOST.
     return isLoopbackHost(new URL(origin).hostname);
   } catch {
     return false;
@@ -68,36 +90,169 @@ export function hostIsLoopbackOrAbsent(req: Request): boolean {
   if (!host) {
     return true;
   }
-  return isLoopbackHost(host);
+  return isLoopbackHost(host) || bareHost(host) === UNSPECIFIED_HOST;
 }
 
 /**
- * Origin/Host-only request gate (no token). Returns a 403 Response when the request is not
- * loopback-safe, else null. Suitable for a same-origin dev server: the browser sends a loopback
- * Origin on cross-origin POSTs, so this closes CSRF + DNS-rebinding without a shared token.
+ * How much cross-origin traffic a surface tolerates.
+ *
+ * `strict` is the default and what every privileged route uses. `embeddable` exists for exactly one
+ * reason: the desktop canvas renders the project inside an iframe on a **different origin**, so the
+ * subresources that page requests — its images, its stylesheets, its modules — legitimately arrive
+ * `cross-site`. Refusing those would break the canvas; accepting them for a route that can write a
+ * file or run an `import()` would hand away the containment. So the difference is a property of the
+ * surface, named at the call site.
  */
-export function originHostGate(req: Request): Response | null {
+export type FetchPolicy = "strict" | "embeddable";
+
+/**
+ * Whether `Sec-Fetch-*` says this request is one the surface accepts (Fetch Metadata Request
+ * Headers).
+ *
+ * The header states the requester's intent directly, which is what `Origin` cannot do: a
+ * same-origin GET omits `Origin` entirely, so the gate has to accept an absent one — a hole
+ * `Sec-Fetch-Site` does not have.
+ *
+ * **Absent means accept, and that is a hard requirement rather than a concession.** The header is
+ * browser-supplied. curl omits it, Bun-native clients omit it, the desktop RPC bridge omits it, and
+ * `packages/server/tests/**` builds well over a hundred bare `Request`s. Requiring it would refuse
+ * every non-browser client on the machine while stopping no attacker, because the threat model here
+ * is a _page_ — and a page always sends it. `fetchMetadataAbsentIsAccepted` in
+ * `tests/net-guard.test.ts` is the test that makes deleting this loud.
+ *
+ * Under `strict`:
+ *
+ * - `same-origin` and `none` — the served page and a typed URL. Allowed.
+ * - `cross-site` — allowed **only** for a top-level document navigation, which is a person following
+ *   a link. A cross-site _subresource_ or form POST is the CSRF this gate exists for.
+ * - `same-site` — **denied**, which is stricter than the standard's Resource Isolation Policy and
+ *   deliberate: on `127.0.0.1` there is no meaningful "site" wider than the origin, so `same-site`
+ *   means _a different port on this machine_ — precisely the other-local-process threat a loopback
+ *   bind cannot address.
+ *
+ * @param {Request} req
+ * @param {FetchPolicy} policy
+ * @returns {boolean}
+ */
+export function fetchMetadataAllows(req: Request, policy: FetchPolicy = "strict"): boolean {
+  const site = req.headers.get("sec-fetch-site");
+  if (!site) {
+    return true;
+  }
+  if (site === "same-origin" || site === "none") {
+    return true;
+  }
+  if (site === "cross-site") {
+    if (policy === "embeddable") {
+      return true;
+    }
+    // A person following a link, and nothing else.
+    return (
+      req.headers.get("sec-fetch-mode") === "navigate" &&
+      req.headers.get("sec-fetch-dest") === "document" &&
+      req.method === "GET"
+    );
+  }
+  // `same-site` and anything unrecognized.
+  return policy === "embeddable" && site === "same-site";
+}
+
+/**
+ * Origin/Host + Fetch Metadata request gate (no token). Returns a 403 Response when the request is
+ * not loopback-safe, else null.
+ *
+ * Suitable for a same-origin dev server: the browser sends a loopback Origin on cross-origin POSTs,
+ * so this closes CSRF + DNS-rebinding without a shared token. The Fetch Metadata check is folded in
+ * here rather than added at each call site, which is what makes it reach every gated surface at
+ * once — there are no new call sites to remember.
+ */
+export function originHostGate(req: Request, policy: FetchPolicy = "strict"): Response | null {
   if (!originIsLoopbackOrAbsent(req) || !hostIsLoopbackOrAbsent(req)) {
-    return new Response("Forbidden", { status: 403 });
+    return problem("forbidden", "Forbidden");
+  }
+  if (!fetchMetadataAllows(req, policy)) {
+    return problem("forbidden", "Forbidden");
   }
   return null;
 }
 
 /**
- * Token + Origin/Host gate. Returns a 403 Response when the token mismatches OR the request is not
- * loopback-safe, else null. Used by the cross-origin desktop server whose canvas iframe carries the
- * token in the URL. Pass `token: null` to skip the token check (Origin/Host only).
+ * Compare two secrets without leaking their common prefix through timing.
+ *
+ * The token is in a URL that a local process may be able to guess at but not read, so a
+ * character-by-character early return is a real oracle: an attacker who can time responses recovers
+ * it one character at a time. Length is compared first and separately, because a length mismatch is
+ * not secret — the token's length is fixed and public.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function secretsMatch(a: string, b: string): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    // oxlint-disable-next-line no-bitwise -- constant-time accumulation; a branch here is the leak.
+    diff |= (a.codePointAt(i) ?? 0) ^ (b.codePointAt(i) ?? 0);
+  }
+  return diff === 0;
+}
+
+/**
+ * The token a request presents, from either place it may carry one.
+ *
+ * The query parameter is what the canvas iframe uses, because an iframe's `src` is the only place
+ * it can put one. `Authorization: Bearer` is accepted **additively** for everything else — a fetch,
+ * a curl, a desktop bridge — since a secret in a URL is logged, referred and shoulder-surfable, and
+ * offering a header costs nothing.
+ *
+ * @param {Request} req
+ * @param {URL} url
+ * @returns {string | null}
  */
-export function loopbackGate(req: Request, url: URL, token: string | null): Response | null {
-  if (token !== null && url.searchParams.get("token") !== token) {
-    return new Response("Forbidden", { status: 403 });
+export function presentedToken(req: Request, url: URL): string | null {
+  const bearer = req.headers.get("authorization");
+  if (bearer?.toLowerCase().startsWith("bearer ")) {
+    const value = bearer.slice("bearer ".length).trim();
+    if (value !== "") {
+      return value;
+    }
   }
-  return originHostGate(req);
+  return url.searchParams.get("token");
+}
+
+/**
+ * Token + Origin/Host + Fetch Metadata gate. Returns a 403 Response when the token mismatches OR
+ * the request is not loopback-safe, else null. Used by the cross-origin desktop server whose canvas
+ * iframe carries the token in the URL. Pass `token: null` to skip the token check.
+ */
+export function loopbackGate(
+  req: Request,
+  url: URL,
+  token: string | null,
+  policy: FetchPolicy = "strict",
+): Response | null {
+  if (token !== null) {
+    const presented = presentedToken(req, url);
+    if (presented === null || !secretsMatch(presented, token)) {
+      return problem("forbidden", "Forbidden");
+    }
+  }
+  return originHostGate(req, policy);
 }
 
 /** Normalize a path for cross-platform containment comparison (separators + case on Windows). */
 export function normalizeForCompare(p: string): string {
-  const slashed = p.replaceAll("\\", "/");
+  /*
+   * NFC, and this is not cosmetic. `readdir` on macOS returns a decomposed filename while a path
+   * from a file picker, a config file or a URL arrives precomposed — two different strings for one
+   * file. Containment is a string comparison, so without normalizing, every path holding an accent
+   * silently failed to be contained: the file existed, the check said it was outside the root, and
+   * the request 404'd with nothing to search for.
+   */
+  const slashed = p.replaceAll("\\", "/").normalize("NFC");
   return process.platform === "win32" ? slashed.toLowerCase() : slashed;
 }
 
@@ -159,6 +314,11 @@ export async function serveContained(absPath: string, root: string): Promise<Res
  *
  * Mounts come first and are contained against their own directory rather than the project root:
  * they exist precisely to publish directories that may sit outside it (extensions.md §8.5).
+ *
+ * The project's BUILT OUTPUT is deliberately NOT here, nor anywhere else in an editing server's
+ * chain: these paths mean the project's SOURCES, and a built page addresses the same paths meaning
+ * its own output. The built site is served on its own origin instead — see
+ * {@link file://./site-preview.ts}.
  */
 export async function serveProjectFile(
   decodedPath: string,
@@ -219,10 +379,10 @@ export function decodeAndNormalizePath(url: URL): DecodedPath {
   try {
     path = decodeURIComponent(url.pathname);
   } catch {
-    return { reject: new Response("Bad request", { status: 400 }) };
+    return { reject: problem("invalidRequest", "Bad request") };
   }
   if (/%2e|%2f/i.test(path)) {
-    return { reject: new Response("Not found", { status: 404 }) };
+    return { reject: problem("notFound", "Not found") };
   }
   const normPath = path.replace(/^\/{2,}/, "/");
   return { path, normPath };