@jxsuite/server 1.1.1 → 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Shenk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -35,21 +35,21 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/collab": "^0.4.1",
-    "@jxsuite/compiler": "^1.2.0",
-    "@jxsuite/create": "^1.1.1",
-    "@jxsuite/import": "^0.37.1",
-    "@jxsuite/protocol": "^0.5.1",
-    "@jxsuite/runtime": "^1.2.0",
-    "@jxsuite/schema": "^1.2.0",
-    "@jxsuite/starters": "^1.1.1",
+    "@jxsuite/collab": "^0.5.1",
+    "@jxsuite/compiler": "^1.4.0",
+    "@jxsuite/create": "^1.2.1",
+    "@jxsuite/import": "^0.38.1",
+    "@jxsuite/protocol": "^0.6.1",
+    "@jxsuite/runtime": "^1.3.1",
+    "@jxsuite/schema": "^1.4.0",
+    "@jxsuite/starters": "^1.2.1",
     "chokidar": "^5.0.0",
     "kysely": "^0.29.4",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@jxsuite/auth": "^0.3.1",
-    "@jxsuite/connector": "^0.3.1",
-    "@jxsuite/parser": "^1.2.0"
+    "@jxsuite/auth": "^0.4.1",
+    "@jxsuite/connector": "^0.4.1",
+    "@jxsuite/parser": "^1.4.0"
   }
 }

package/src/ai-api.ts

@@ -7,13 +7,15 @@
  *
  * API key flow:
  *   1. Request header X-Api-Key or Authorization: Bearer <key>
- *   2. Fallback: OPENAI_API_KEY env var
+ *   2. Fallback: OPENAI_API_KEY env var — attached ONLY to the env/default base URL, never to a
+ *      caller-supplied X-Api-Base-URL (prevents exfiltrating the server key to a chosen endpoint)
  *   3. If neither → 401 with error message
  *
  * Base URL flow:
- *   1. Request header X-Api-Base-URL
+ *   1. Request header X-Api-Base-URL — allowed only alongside a header API key
  *   2. Fallback: OPENAI_BASE_URL env var
  *   3. Default: https://api.openai.com/v1
+ *   A base URL resolving to a cloud metadata / link-local host is refused (SSRF defense).
  *
  * @license MIT
  */
@@ -46,31 +48,88 @@ interface ModelEntry {
   owned_by?: string;
 }
 
-function getConfig(req: Request): { apiKey: string | null; baseUrl: string; missingKey: boolean } {
+/**
+ * SSRF defense: refuse to proxy to a cloud metadata endpoint or a link-local host. Loopback and
+ * private-LAN hosts are intentionally allowed — self-hosted / local LLMs run there. An unparseable
+ * base URL is blocked. `169.254.169.254` (the AWS/GCP/Azure metadata IP) lives in the link-local
+ * `169.254.0.0/16` range, which is the primary thing this stops.
+ */
+function isBlockedHost(rawUrl: string): boolean {
+  let host: string;
+  try {
+    host = new URL(rawUrl).hostname.toLowerCase();
+  } catch {
+    return true;
+  }
+  const h = host.startsWith("[") ? host.slice(1, -1) : host;
+  if (h === "metadata.google.internal") {
+    return true;
+  }
+  if (h.startsWith("169.254.")) {
+    return true; // IPv4 link-local, incl. the cloud metadata IP
+  }
+  if (h.startsWith("fe80:")) {
+    return true; // IPv6 link-local
+  }
+  return false;
+}
+
+interface AiConfig {
+  apiKey: string | null;
+  baseUrl: string;
+  missingKey: boolean;
+  reject?: { status: number; message: string };
+}
+
+function getConfig(req: Request): AiConfig {
   const authHeader = req.headers.get("Authorization") || "";
   const apiKeyHeader = req.headers.get("X-Api-Key") || "";
   const baseUrlHeader = req.headers.get("X-Api-Base-URL") || "";
 
-  let apiKey = null;
-
-  // Check Authorization: Bearer <key>
+  // Track the PROVENANCE of the key: a header-supplied key may ride a caller's custom base URL; the
+  // Server's env key never leaves for a caller-chosen endpoint (key-exfiltration defense).
+  let apiKey: string | null = null;
+  let keyFromHeader = false;
   if (authHeader.startsWith("Bearer ")) {
     apiKey = authHeader.slice(7).trim();
+    keyFromHeader = true;
   }
-
-  // Check X-Api-Key header (overrides Bearer)
   if (apiKeyHeader) {
-    apiKey = apiKeyHeader.trim();
+    apiKey = apiKeyHeader.trim(); // X-Api-Key overrides Bearer
+    keyFromHeader = true;
   }
 
-  // Check env var (fallback)
+  const baseFromHeader = Boolean(baseUrlHeader);
+  const baseUrl = baseUrlHeader || process.env.OPENAI_BASE_URL || DEFAULT_BASE_URL;
+
+  if (isBlockedHost(baseUrl)) {
+    return {
+      apiKey: null,
+      baseUrl,
+      missingKey: true,
+      reject: { status: 403, message: "Base URL host is not permitted." },
+    };
+  }
+
+  // A caller-supplied base URL requires a caller-supplied key. Refuse to forward the env
+  // OPENAI_API_KEY to an endpoint the request chose.
+  if (baseFromHeader && !keyFromHeader) {
+    return {
+      apiKey: null,
+      baseUrl,
+      missingKey: true,
+      reject: {
+        status: 401,
+        message: "A custom base URL requires an explicit API key (X-Api-Key).",
+      },
+    };
+  }
+
+  // Env key is only ever attached to the env/default base URL.
   if (!apiKey && process.env.OPENAI_API_KEY) {
     apiKey = process.env.OPENAI_API_KEY;
   }
 
-  // Check base URL
-  const baseUrl = baseUrlHeader || process.env.OPENAI_BASE_URL || DEFAULT_BASE_URL;
-
   return { apiKey, baseUrl, missingKey: !apiKey };
 }
 
@@ -97,7 +156,10 @@ function jsonError(status: number, message: string): Response {
 
 /** Handle POST /__studio/ai/chat — proxy chat completions to OpenAI via SSE. */
 export async function handleChat(req: Request): Promise<Response> {
-  const { apiKey, baseUrl, missingKey } = getConfig(req);
+  const { apiKey, baseUrl, missingKey, reject } = getConfig(req);
+  if (reject) {
+    return jsonError(reject.status, reject.message);
+  }
   if (missingKey) {
     return jsonError(
       401,
@@ -374,7 +436,10 @@ export async function handleChat(req: Request): Promise<Response> {
  * key is available.
  */
 export async function handleModels(req: Request): Promise<Response> {
-  const { apiKey, baseUrl, missingKey } = getConfig(req);
+  const { apiKey, baseUrl, missingKey, reject } = getConfig(req);
+  if (reject) {
+    return jsonError(reject.status, reject.message);
+  }
 
   // No key available → return hardcoded defaults so the UI can at least render.
   if (missingKey) {

package/src/code-api.ts

@@ -7,7 +7,8 @@
 
 import { tmpdir } from "node:os";
 import { errorMessage } from "@jxsuite/schema/parse";
-import { join, resolve } from "node:path";
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
 import { unlink } from "node:fs/promises";
 import { format } from "oxfmt";
 
@@ -26,11 +27,32 @@ interface CodeApiBody {
   args?: string[];
 }
 
-const OXLINT_BIN = resolve(
-  import.meta.dir,
-  "../../node_modules/.bin",
-  process.platform === "win32" ? "oxlint.exe" : "oxlint",
-);
+const OXLINT_NAME = process.platform === "win32" ? "oxlint.exe" : "oxlint";
+
+/**
+ * Locate the oxlint CLI: explicit JX_OXLINT_BIN override (empty value = disable lint outright),
+ * then a walk up from this module probing node_modules/.bin (finds the workspace root in the
+ * monorepo and the hoisted bin for npm consumers), then PATH. Null when oxlint is unavailable —
+ * e.g. the packaged desktop app, where the lint endpoint quietly returns no diagnostics.
+ */
+export function resolveOxlintBin(startDir: string = import.meta.dir): string | null {
+  const override = process.env.JX_OXLINT_BIN;
+  if (override !== undefined) {
+    return override || null;
+  }
+  let dir = startDir;
+  for (;;) {
+    const candidate = join(dir, "node_modules", ".bin", OXLINT_NAME);
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return Bun.which("oxlint", { PATH: process.env.PATH ?? "" });
+    }
+    dir = parent;
+  }
+}
 
 // ─── Wrapper utilities ───────────────────────────────────────────────────────
 
@@ -151,6 +173,12 @@ export async function handleCodeApi(req: Request, url: URL) {
       return Response.json({ diagnostics: [] });
     }
 
+    const oxlintBin = resolveOxlintBin();
+    if (!oxlintBin) {
+      // No oxlint anywhere (packaged desktop app) — lint quietly disables.
+      return Response.json({ diagnostics: [] });
+    }
+
     const wrapped = wrapBody(code, args);
     const headerLen = wrapped.indexOf("\n") + 1;
     const tmpFile = join(
@@ -160,7 +188,7 @@ export async function handleCodeApi(req: Request, url: URL) {
 
     try {
       await Bun.write(tmpFile, wrapped);
-      const proc = Bun.spawn([OXLINT_BIN, "--format=json", "-A", "no-unused-vars", tmpFile], {
+      const proc = Bun.spawn([oxlintBin, "--format=json", "-A", "no-unused-vars", tmpFile], {
         stderr: "pipe",
         stdout: "pipe",
       });

package/src/net-guard.ts

@@ -0,0 +1,229 @@
+/**
+ * Shared network/path security primitives for the server package.
+ *
+ * These were originally private to `project-server.ts` (the hardened, token-gated desktop server).
+ * They are extracted here so the plain dev server (`server.ts`) can reuse the SAME loopback checks,
+ * realpath containment, and URL-decode hardening instead of its previous string-prefix logic.
+ *
+ * Security model. Loopback bind (127.0.0.1) is the primary control: LAN pages and other local
+ * processes cannot read a loopback page's location, so cross-origin requests are the realistic
+ * threat. `originHostGate` and `loopbackGate` are the request-level gate that rejects a
+ * non-loopback Origin or a non-loopback Host (anti-CSRF and anti-DNS-rebinding); `loopbackGate`
+ * additionally checks a token, which the desktop server's cross-origin canvas iframe needs but the
+ * same-origin dev server does not. `containedPath`, `serveContained`, and `serveProjectFile`
+ * contain a filesystem path within a root via a lexical relative() check plus a realpath re-check
+ * (symlink escape defense). `decodeAndNormalizePath` decodes the URL pathname once and rejects
+ * over-encoded dot and slash sequences.
+ */
+
+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";
+
+export const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+
+/** 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());
+}
+
+/**
+ * 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.
+ */
+export 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.
+ */
+export function hostIsLoopbackOrAbsent(req: Request): boolean {
+  const host = req.headers.get("host");
+  if (!host) {
+    return true;
+  }
+  return isLoopbackHost(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.
+ */
+export function originHostGate(req: Request): Response | null {
+  if (!originIsLoopbackOrAbsent(req) || !hostIsLoopbackOrAbsent(req)) {
+    return new Response("Forbidden", { status: 403 });
+  }
+  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).
+ */
+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 });
+  }
+  return originHostGate(req);
+}
+
+/** Normalize a path for cross-platform containment comparison (separators + case on Windows). */
+export 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.
+ */
+export 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 `root` if it both exists and is contained. Returns the Response, or null when
+ * missing/traversed (caller decides the fallthrough status).
+ */
+export 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: an extension asset mount, then
+ * 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).
+ *
+ * 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).
+ */
+export async function serveProjectFile(
+  decodedPath: string,
+  root: string,
+  mounts: readonly AssetMount[] = [],
+): Promise<Response | null> {
+  for (const mount of [...mounts].toSorted((a, b) => b.urlPrefix.length - a.urlPrefix.length)) {
+    const mounted = resolveAssetUrl([mount], decodedPath);
+    if (!mounted) {
+      continue;
+    }
+    const res = await serveContained(mounted, mount.dir);
+    if (res) {
+      return res;
+    }
+  }
+  // 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;
+}
+
+/** Result of decoding a URL pathname: the safe decoded/normalized path, or a rejection Response. */
+export type DecodedPath = { path: string; normPath: string } | { reject: Response };
+
+/**
+ * Decode a URL pathname ONCE and reject over-encoding bypasses. Returns `{ path, normPath }` where
+ * `path` is the once-decoded pathname and `normPath` collapses runs of leading slashes to one, or
+ * `{ reject }` with a 400/404 Response when the input is malformed or still contains an encoded
+ * dot/slash after one decode.
+ */
+export function decodeAndNormalizePath(url: URL): DecodedPath {
+  let path: string;
+  try {
+    path = decodeURIComponent(url.pathname);
+  } catch {
+    return { reject: new Response("Bad request", { status: 400 }) };
+  }
+  if (/%2e|%2f/i.test(path)) {
+    return { reject: new Response("Not found", { status: 404 }) };
+  }
+  const normPath = path.replace(/^\/{2,}/, "/");
+  return { path, normPath };
+}

package/src/project-server.ts

@@ -25,14 +25,19 @@
  *   realpath re-check (symlink containment).
  */
 
-import { isAbsolute, relative, resolve, sep } from "node:path";
-import { realpathSync } from "node:fs";
+import { resolve, sep } from "node:path";
 import { handleJxMounts } from "./jx-mounts.ts";
-import { handleResolve, handleServerFunction } from "./resolve.ts";
+import { handleResolve, handleServerFunction, projectAssetMounts } from "./resolve.ts";
 import { handleAiApi } from "./ai-api.ts";
 import { handleImportApi } from "./import-api.ts";
 import { resolveNpmPath } from "./server.ts";
 import type { ImportApiOptions } from "./import-api.ts";
+import {
+  decodeAndNormalizePath,
+  loopbackGate,
+  serveContained,
+  serveProjectFile,
+} from "./net-guard.ts";
 
 /** A resolved per-window session: its project root plus its RPC handler map. */
 export interface ProjectServerSession {
@@ -71,151 +76,6 @@ export interface ProjectServerHandle {
   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.
  *
@@ -243,27 +103,20 @@ export function createProjectServer(options: CreateProjectServerOptions): Projec
       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 });
+      const decoded = decodeAndNormalizePath(url);
+      if ("reject" in decoded) {
+        return decoded.reject;
       }
-      // 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 { normPath } = decoded;
 
       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 });
+        const gate = loopbackGate(req, url, rpcToken);
+        if (gate) {
+          return gate;
         }
         if (srv.upgrade(req, { data: { winId } })) {
           return;
@@ -288,9 +141,9 @@ export function createProjectServer(options: CreateProjectServerOptions): Projec
         if (!importApi) {
           return new Response("Not found", { status: 404 });
         }
-        const token = url.searchParams.get("token");
-        if (token !== rpcToken || !originIsLoopbackOrAbsent(req) || !hostIsLoopbackOrAbsent(req)) {
-          return new Response("Forbidden", { status: 403 });
+        const gate = loopbackGate(req, url, rpcToken);
+        if (gate) {
+          return gate;
         }
         const importUrl = new URL(req.url);
         importUrl.pathname = "/__studio/import-site";
@@ -343,9 +196,9 @@ export function createProjectServer(options: CreateProjectServerOptions): Projec
         (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 });
+        const gate = loopbackGate(req, url, rpcToken);
+        if (gate) {
+          return gate;
         }
         if (normPath === "/__jx_resolve__") {
           return handleResolve(req, root, root);
@@ -353,8 +206,9 @@ export function createProjectServer(options: CreateProjectServerOptions): Projec
         return handleServerFunction(req, root);
       }
 
-      // 6. Project files at natural URLs.
-      const fileRes = await serveProjectFile(normPath, root);
+      // 6. Project files at natural URLs, including extension asset mounts (§8.5) — that is what
+      // Lets a canvas preview show an image a content entry references relative to itself.
+      const fileRes = await serveProjectFile(normPath, root, await projectAssetMounts(root));
       if (fileRes) {
         return fileRes;
       }

package/src/resolve.ts

@@ -4,8 +4,11 @@ import { dirname, relative, resolve } from "node:path";
 import { errorMessage, parseClassDef } from "@jxsuite/schema/parse";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
+import { containedPath } from "./net-guard.ts";
 import { buildProjectExtensionRegistry } from "@jxsuite/compiler/format-host";
 import { loadProjectSections } from "@jxsuite/compiler/project-sections";
+import { loadAssetMounts } from "@jxsuite/compiler/asset-mounts";
+import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import type { DynamicClass } from "@jxsuite/runtime/types";
 import type { JxClassDef, ProjectConfig } from "@jxsuite/schema/types";
 
@@ -36,8 +39,26 @@ interface ServerFunctionBody {
   [key: string]: unknown;
 }
 
+/**
+ * True when `p` is contained within `root` or (when set) `activeProjectRoot`. Guards every
+ * `import()`/read of a caller-supplied `$src`/`$base`/`$implementation` so a `../` or absolute path
+ * cannot pull in arbitrary modules from the filesystem.
+ */
+function isImportable(p: string, root: string, activeProjectRoot: string | null): boolean {
+  if (containedPath(p, root) !== null) {
+    return true;
+  }
+  if (activeProjectRoot && containedPath(p, activeProjectRoot) !== null) {
+    return true;
+  }
+  return false;
+}
+
 /** Per-project context cache, invalidated when project.json changes on disk. */
-const projectContextCache = new Map<string, { mtime: number; context: Record<string, unknown> }>();
+const projectContextCache = new Map<
+  string,
+  { mtime: number; context: Record<string, unknown>; mounts: AssetMount[] }
+>();
 
 /**
  * Lazy-load project context (project.json + extension-loaded sections) for class instantiation.
@@ -48,6 +69,12 @@ const projectContextCache = new Map<string, { mtime: number; context: Record<str
  * @returns {Promise<Record<string, unknown> | null>} `{ config, root, ...sections }` or null
  */
 async function loadProjectContext(projectRoot: string) {
+  const entry = await loadProjectEntry(projectRoot);
+  return entry?.context ?? null;
+}
+
+/** Load (or reuse) the cached project context plus its extension asset mounts. */
+async function loadProjectEntry(projectRoot: string) {
   const projectJsonPath = resolve(projectRoot, "project.json");
   if (!existsSync(projectJsonPath)) {
     return null;
@@ -56,19 +83,33 @@ async function loadProjectContext(projectRoot: string) {
     const { mtimeMs } = statSync(projectJsonPath);
     const cached = projectContextCache.get(projectRoot);
     if (cached && cached.mtime === mtimeMs) {
-      return cached.context;
+      return cached;
     }
     const config = JSON.parse(readFileSync(projectJsonPath, "utf8")) as ProjectConfig;
     const registry = await buildProjectExtensionRegistry(projectRoot, config);
     const sections = await loadProjectSections(projectRoot, config, registry);
+    const { mounts } = await loadAssetMounts(registry, config, projectRoot);
     const context = { config, root: projectRoot, ...sections };
-    projectContextCache.set(projectRoot, { context, mtime: mtimeMs });
-    return context;
+    const entry = { context, mounts, mtime: mtimeMs };
+    projectContextCache.set(projectRoot, entry);
+    return entry;
   } catch {
     return null;
   }
 }
 
+/**
+ * Extension asset mounts for a project (specs/extensions.md §8.5) — the directories the dev server
+ * serves at their site URLs, so content-relative images resolve exactly as they will once built.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<AssetMount[]>} Mounts, or an empty list when there is no project here
+ */
+export async function projectAssetMounts(projectRoot: string): Promise<AssetMount[]> {
+  const entry = await loadProjectEntry(projectRoot);
+  return entry?.mounts ?? [];
+}
+
 /**
  * Handle POST /**jx_resolve** — proxy $prototype + $src entries.
  *
@@ -94,6 +135,10 @@ export async function handleResolve(
   }
 
   let moduleAbsPath;
+  // A bare specifier resolves through Node's module resolution (an installed package), so the
+  // Class file — and the `$implementation` sibling it names — are as trusted as the package's own
+  // Code. The root-escape guard only binds a caller-supplied relative `$src`/`$base`.
+  let trustedResolution = false;
   try {
     if ($src.startsWith("./") || $src.startsWith("../")) {
       // Relative path
@@ -104,6 +149,9 @@ export async function handleResolve(
       } else {
         moduleAbsPath = resolve(activeProjectRoot || root, $src);
       }
+      if (!isImportable(moduleAbsPath, root, activeProjectRoot)) {
+        return new Response(`$src "${$src}" escapes the project root`, { status: 403 });
+      }
     } else {
       // Npm/bare specifier — use createRequire from project root, fall back to server package
       const projectRoot = activeProjectRoot || root;
@@ -114,6 +162,7 @@ export async function handleResolve(
         const serverRequire = createRequire(import.meta.url);
         moduleAbsPath = serverRequire.resolve($src);
       }
+      trustedResolution = true;
     }
   } catch (error) {
     return new Response(`Cannot resolve $src "${$src}": ${errorMessage(error)}`, { status: 400 });
@@ -148,6 +197,11 @@ export async function handleResolve(
       if (classDef.$implementation) {
         // Hybrid mode: redirect to the JS implementation
         const implPath = resolve(dirname(moduleAbsPath), classDef.$implementation);
+        // A trusted (bare-specifier) class file names its own sibling implementation; only a
+        // Project-local relative $src is held to the root-escape guard.
+        if (!trustedResolution && !isImportable(implPath, root, activeProjectRoot)) {
+          return new Response(`$implementation escapes the project root`, { status: 403 });
+        }
         const exportName = xport ?? classDef.title ?? $prototype;
         const mod = (await import(implPath)) as ModuleNamespace;
         const ExportedClass =
@@ -229,6 +283,10 @@ export async function handleServerFunction(req: Request, root: string) {
     });
   }
 
+  if (!isImportable(moduleAbsPath, root, null)) {
+    return new Response(`$src "${$src}" escapes the project root`, { status: 403 });
+  }
+
   let mod: ModuleNamespace;
   try {
     mod = (await import(moduleAbsPath)) as ModuleNamespace;
@@ -246,7 +304,12 @@ export async function handleServerFunction(req: Request, root: string) {
   }
 
   try {
-    const result = await (fn as (args: Record<string, unknown>) => unknown)(args);
+    // Match the production contract `fn(args, env)` (compiler emits `fn(args, c.env)`): the dev
+    // Proxy runs server-side, so `process.env` is the analogous environment binding.
+    const result = await (fn as (args: Record<string, unknown>, env: unknown) => unknown)(
+      args,
+      process.env,
+    );
     return Response.json(result ?? null);
   } catch (error) {
     return Response.json({ error: errorMessage(error) }, { status: 500 });

package/src/server.ts

@@ -18,8 +18,14 @@ import { buildAll } from "./build.ts";
 import { createCollabRegistry } from "./collab.ts";
 import { createWatcher, injectSSE } from "./watch.ts";
 import { handleJxMounts } from "./jx-mounts.ts";
-import { handleResolve, handleServerFunction } from "./resolve.ts";
+import { handleResolve, handleServerFunction, projectAssetMounts } from "./resolve.ts";
 import { assertAccessible, handleStudioApi } from "./studio-api.ts";
+import {
+  containedPath,
+  decodeAndNormalizePath,
+  originHostGate,
+  serveProjectFile,
+} from "./net-guard.ts";
 import { handleCodeApi } from "./code-api.ts";
 import { handleAiApi } from "./ai-api.ts";
 import { handleImportApi } from "./import-api.ts";
@@ -173,6 +179,18 @@ export { resolveNpmPath };
 export async function createDevServer(options: {
   root: string;
   port?: number;
+  /**
+   * Bind hostname. Defaults to loopback `127.0.0.1` — the primary security control. Binding a
+   * non-loopback host (e.g. `0.0.0.0` inside a container) exposes the RCE-capable resolve routes
+   * and the filesystem API to the network; only do so behind trusted isolation.
+   */
+  hostname?: string;
+  /**
+   * Extra filesystem roots (besides `root`) that `/__studio/activate` may switch to. Studio can
+   * activate an external project dir; a root that is neither under `root` nor listed here is
+   * refused.
+   */
+  allowedRoots?: string[];
   builds?: {
     entrypoints: string[];
     outdir: string;
@@ -186,6 +204,8 @@ export async function createDevServer(options: {
   const {
     root,
     port = 3000,
+    hostname = "127.0.0.1",
+    allowedRoots = [],
     builds = [],
     watch = true,
     studio: enableStudio = true,
@@ -247,7 +267,14 @@ export async function createDevServer(options: {
   const server = Bun.serve({
     async fetch(req, bunServer) {
       const url = new URL(req.url);
-      let path = decodeURIComponent(url.pathname);
+      // Decode the pathname ONCE and reject over-encoded traversal (%252e → %2e). Single-encoded
+      // ".." is caught later by realpath containment on the static path.
+      const decoded = decodeAndNormalizePath(url);
+      if ("reject" in decoded) {
+        return decoded.reject;
+      }
+      // Keep the un-collapsed decoded path: the static branch detects a POSIX-absolute "//abs" prefix.
+      let { path } = decoded;
       if (path.endsWith("/")) {
         path += "index.html";
       } else if (path === "") {
@@ -259,6 +286,24 @@ export async function createDevServer(options: {
         return handleSSE();
       }
 
+      /*
+       * The RCE-capable resolve routes, the extension mounts, and the studio API are gated by a
+       * loopback Origin/Host check: the browser Studio and the served site are same-origin (they
+       * send a loopback Origin on cross-origin POSTs), while a malicious external page is rejected.
+       * The loopback bind is the primary control; this defeats CSRF + DNS-rebinding on top of it.
+       */
+      const isPrivileged =
+        path === "/__jx_resolve__" ||
+        path === "/__jx_server__" ||
+        path.startsWith("/_jx/") ||
+        (enableStudio && path.startsWith("/__studio/"));
+      if (isPrivileged) {
+        const gate = originHostGate(req);
+        if (gate) {
+          return gate;
+        }
+      }
+
       // $prototype + $src proxy
       if (path === "/__jx_resolve__" && req.method === "POST") {
         return handleResolve(req, absRoot, activeProjectRoot);
@@ -285,12 +330,24 @@ export async function createDevServer(options: {
           return collabRegistry.handleRequest(req, bunServer);
         }
 
-        // Activate project — tells the server which project root to use for static file fallback
+        // Activate project — tells the server which project root to use for static file fallback.
+        // Contain the requested root: it must be under absRoot or an explicitly allowed root, so a
+        // Hostile activate cannot widen the filesystem API to arbitrary directories.
         if (path === "/__studio/activate" && req.method === "POST") {
           const body = (await req.json()) as { root?: string };
           const raw = body.root || null;
-          // Always store as absolute path
-          activeProjectRoot = raw ? resolve(absRoot, raw) : null;
+          if (!raw) {
+            activeProjectRoot = null;
+            return Response.json({ ok: true, root: null });
+          }
+          const requested = resolve(absRoot, raw);
+          const permitted =
+            containedPath(requested, absRoot) !== null ||
+            allowedRoots.some((allowed) => containedPath(requested, resolve(allowed)) !== null);
+          if (!permitted) {
+            return Response.json({ ok: false, error: "root not permitted" }, { status: 403 });
+          }
+          activeProjectRoot = requested;
           return Response.json({ ok: true, root: activeProjectRoot });
         }
 
@@ -332,7 +389,8 @@ export async function createDevServer(options: {
         }
       }
 
-      // Static files
+      // Static files. Every candidate is contained (lexical + realpath) against its root, so an
+      // Encoded "../" traversal that survived URL normalization cannot escape to arbitrary files.
 
       // If the URL path is an absolute filesystem path under the active project, serve directly.
       // A POSIX absolute path arrives as "//abs/path"; a Windows one as "/C:/dir/file" (leading
@@ -341,24 +399,54 @@ export async function createDevServer(options: {
       const fsPath = path.startsWith("//") ? path.slice(1) : path.replace(/^\/([A-Za-z]:)/, "$1");
       const normSep = (p: string) => p.replaceAll("\\", "/");
       if (activeProjectRoot && normSep(fsPath).startsWith(normSep(activeProjectRoot))) {
-        const file = Bun.file(fsPath);
-        if (await file.exists()) {
-          return fileResponse(file);
+        const safe = containedPath(fsPath, activeProjectRoot);
+        if (safe) {
+          const file = Bun.file(safe);
+          if (await file.exists()) {
+            return fileResponse(file);
+          }
         }
       }
 
-      const file = Bun.file(resolve(absRoot, `.${path}`));
-      if (!(await file.exists())) {
+      // Extension asset mounts (§8.5) publish directories that may sit outside the project root,
+      // Such as an external content source's co-located images. They resolve here exactly as they
+      // Will once the site is built, so dev and production render the same URLs.
+      if (activeProjectRoot) {
+        const mountRes = await serveProjectFile(
+          path,
+          activeProjectRoot,
+          await projectAssetMounts(activeProjectRoot),
+        );
+        if (mountRes) {
+          return new Response(mountRes.body, { headers: NO_CACHE });
+        }
+      }
+
+      const rootSafe = containedPath(resolve(absRoot, `.${path}`), absRoot);
+      const file = rootSafe ? Bun.file(rootSafe) : null;
+      if (!file || !(await file.exists())) {
         // Try resolving relative to active studio project root
         if (activeProjectRoot) {
-          const projectFile = Bun.file(resolve(activeProjectRoot, `.${path}`));
-          if (await projectFile.exists()) {
-            return fileResponse(projectFile);
+          const projectSafe = containedPath(
+            resolve(activeProjectRoot, `.${path}`),
+            activeProjectRoot,
+          );
+          if (projectSafe) {
+            const projectFile = Bun.file(projectSafe);
+            if (await projectFile.exists()) {
+              return fileResponse(projectFile);
+            }
           }
           // Mirror production: public/ contents are served at root
-          const publicFile = Bun.file(resolve(activeProjectRoot, "public", `.${path}`));
-          if (await publicFile.exists()) {
-            return fileResponse(publicFile);
+          const publicSafe = containedPath(
+            resolve(activeProjectRoot, "public", `.${path}`),
+            activeProjectRoot,
+          );
+          if (publicSafe) {
+            const publicFile = Bun.file(publicSafe);
+            if (await publicFile.exists()) {
+              return fileResponse(publicFile);
+            }
           }
         }
 
@@ -408,6 +496,7 @@ export async function createDevServer(options: {
       return fileResponse(file);
     },
 
+    hostname,
     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.
@@ -415,7 +504,7 @@ export async function createDevServer(options: {
     websocket: collabRegistry.websocket,
   });
 
-  console.log(`\n@jxsuite/server listening on http://localhost:${server.port}`);
+  console.log(`\n@jxsuite/server listening on http://${hostname}:${server.port}`);
 
   return server;
 }

package/src/studio-api.ts

@@ -17,6 +17,7 @@ import {
 } from "@jxsuite/compiler/format-host";
 import { readBundledProjectSchemas } from "@jxsuite/compiler/schema-command";
 import { handleDataApi } from "./data-api.ts";
+import { containedPath } from "./net-guard.ts";
 import { applyRename } from "./refactor/apply.ts";
 import {
   bunExecutable,
@@ -164,15 +165,12 @@ async function getFormatRegistry(projectRoot: string): Promise<FormatRegistry> {
  * @param {string | null} activeProjectRoot
  */
 export function assertAccessible(filePath: string, root: string, activeProjectRoot: string | null) {
-  const rel = relative(root, filePath);
-  if (!rel.startsWith("..") && !rel.startsWith("/")) {
+  // Realpath containment (symlink-safe) against the server root, or an explicitly-activated project.
+  if (containedPath(filePath, root) !== null) {
     return;
   }
-  if (activeProjectRoot) {
-    const relActive = relative(activeProjectRoot, filePath);
-    if (!relActive.startsWith("..") && !relActive.startsWith("/")) {
-      return;
-    }
+  if (activeProjectRoot && containedPath(filePath, activeProjectRoot) !== null) {
+    return;
   }
   throw new Error("Path outside project root");
 }