@vizejs/vite-plugin-musea 0.81.0 → 0.82.0

package/dist/index.mjs

@@ -7,6 +7,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { vizeConfigStore } from "@vizejs/vite-plugin";
 import { fileURLToPath } from "node:url";
+import { randomBytes, timingSafeEqual } from "node:crypto";
 //#region src/native-loader.ts
 /**
 * Native binding loader for @vizejs/native.
@@ -495,6 +496,126 @@ function generateGalleryStyles() {
 	return `${styles_base_default}\n${styles_layout_default}\n${styles_components_default}`;
 }
 //#endregion
+//#region src/security.ts
+const DEFAULT_API_BODY_LIMIT_BYTES = 1024 * 1024;
+var HttpError = class extends Error {
+	status;
+	constructor(message, status) {
+		super(message);
+		this.name = "HttpError";
+		this.status = status;
+	}
+};
+function createDevSessionToken() {
+	return randomBytes(32).toString("base64url");
+}
+function isPathInside(parentDir, candidatePath) {
+	const parent = path.resolve(parentDir);
+	const candidate = path.resolve(candidatePath);
+	const relative = path.relative(parent, candidate);
+	return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function resolveInside(parentDir, candidatePath, label = "path") {
+	if (candidatePath.includes("\0")) throw new HttpError(`${label} contains an invalid character`, 400);
+	const parent = path.resolve(parentDir);
+	const resolved = path.isAbsolute(candidatePath) ? path.resolve(candidatePath) : path.resolve(parent, candidatePath);
+	if (!isPathInside(parent, resolved)) throw new HttpError(`${label} escapes the allowed directory`, 400);
+	return resolved;
+}
+function resolveUrlPathInside(parentDir, requestUrl, label = "path") {
+	const rawPath = requestUrl.split(/[?#]/, 1)[0] || "/";
+	let pathname;
+	try {
+		pathname = decodeURIComponent(rawPath);
+	} catch {
+		throw new HttpError(`${label} is not valid URL encoding`, 400);
+	}
+	pathname = pathname.replaceAll("\\", "/");
+	if (pathname.split("/").includes("..")) throw new HttpError(`${label} must not contain parent directory segments`, 400);
+	return resolveInside(parentDir, `.${pathname}`, label);
+}
+function collectRequestBody(req, limit = DEFAULT_API_BODY_LIMIT_BYTES) {
+	return new Promise((resolve, reject) => {
+		let body = "";
+		let size = 0;
+		let completed = false;
+		req.on("data", (chunk) => {
+			if (completed) return;
+			const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+			size += buffer.byteLength;
+			if (size > limit) {
+				completed = true;
+				reject(new HttpError(`Request body exceeds ${limit} bytes`, 413));
+				return;
+			}
+			body += buffer.toString("utf-8");
+		});
+		req.on("end", () => {
+			if (!completed) {
+				completed = true;
+				resolve(body);
+			}
+		});
+		req.on("error", (error) => {
+			if (!completed) {
+				completed = true;
+				reject(error);
+			}
+		});
+	});
+}
+function validateDevApiRequest(req, sessionToken) {
+	const originError = validateOrigin(req);
+	if (originError) return originError;
+	if (!isUnsafeMethod(req.method)) return null;
+	if (!hasValidSessionToken(req, sessionToken)) return new HttpError("Invalid Musea dev session token", 403);
+	if (!isJsonRequest(req)) return new HttpError("Content-Type must be application/json", 415);
+	return null;
+}
+function serializeScriptValue(value) {
+	return (JSON.stringify(value) ?? "undefined").replace(/[<>&\u2028\u2029]/g, (char) => {
+		switch (char) {
+			case "<": return "\\u003C";
+			case ">": return "\\u003E";
+			case "&": return "\\u0026";
+			case "\u2028": return "\\u2028";
+			case "\u2029": return "\\u2029";
+			default: return char;
+		}
+	});
+}
+function isUnsafeMethod(method) {
+	return method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE";
+}
+function isJsonRequest(req) {
+	return getHeader(req, "content-type")?.split(";")[0]?.trim().toLowerCase() === "application/json";
+}
+function validateOrigin(req) {
+	if (getHeader(req, "sec-fetch-site") === "cross-site") return new HttpError("Cross-origin Musea API requests are not allowed", 403);
+	const origin = getHeader(req, "origin");
+	if (!origin) return null;
+	const host = getHeader(req, "host");
+	if (!host) return new HttpError("Missing Host header", 400);
+	try {
+		if (new URL(origin).host !== host) return new HttpError("Cross-origin Musea API requests are not allowed", 403);
+	} catch {
+		return new HttpError("Invalid Origin header", 400);
+	}
+	return null;
+}
+function hasValidSessionToken(req, expectedToken) {
+	const actualToken = getHeader(req, "x-musea-session");
+	if (!actualToken) return false;
+	const actual = Buffer.from(actualToken);
+	const expected = Buffer.from(expectedToken);
+	return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+function getHeader(req, name) {
+	const value = req.headers[name];
+	if (Array.isArray(value)) return value[0];
+	return value;
+}
+//#endregion
 //#region src/gallery/template.ts
 /**
 * HTML structure and inline JS generation for the Musea gallery.
@@ -564,7 +685,7 @@ function generateGalleryBody(basePath) {
 */
 function generateGalleryScript(basePath) {
 	return `
-    const basePath = '${basePath}';
+    const basePath = ${serializeScriptValue(basePath)};
     let arts = [];
     let selectedArt = null;
     let searchQuery = '';
@@ -737,14 +858,15 @@ function generateGalleryScript(basePath) {
 /**
 * Generate the inline gallery HTML page.
 */
-function generateGalleryHtml(basePath, themeConfig) {
+function generateGalleryHtml(basePath, devSessionToken, themeConfig) {
+	const themeScript = themeConfig ? `window.__MUSEA_THEME_CONFIG__=${serializeScriptValue(themeConfig)};` : "";
 	return `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Musea - Component Gallery</title>
-  <script>window.__MUSEA_BASE_PATH__='${basePath}';${themeConfig ? `window.__MUSEA_THEME_CONFIG__=${JSON.stringify(themeConfig)};` : ""}<\/script>
+  <script>window.__MUSEA_BASE_PATH__=${serializeScriptValue(basePath)};window.__MUSEA_SESSION_TOKEN__=${serializeScriptValue(devSessionToken)};${themeScript}<\/script>
   <style>${generateGalleryStyles()}
   </style>
 </head>
@@ -760,7 +882,7 @@ function generateGalleryHtml(basePath, themeConfig) {
 */
 function generateGalleryModule(basePath) {
 	return `
-export const basePath = '${basePath}';
+export const basePath = ${serializeScriptValue(basePath)};
 export async function loadArts() {
   const res = await fetch(basePath + '/api/arts');
   return res.json();
@@ -1226,6 +1348,30 @@ function ensureArtStyles(styles) {
   }
 }
 
+function renderError(title, error) {
+  container.textContent = '';
+  const root = document.createElement('div');
+  root.className = 'musea-error';
+
+  const titleEl = document.createElement('div');
+  titleEl.className = 'musea-error-title';
+  titleEl.textContent = title;
+  root.appendChild(titleEl);
+
+  const messageEl = document.createElement('div');
+  messageEl.textContent = error instanceof Error ? error.message : String(error);
+  root.appendChild(messageEl);
+
+  const stack = error instanceof Error ? error.stack : '';
+  if (stack) {
+    const stackEl = document.createElement('pre');
+    stackEl.textContent = stack;
+    root.appendChild(stackEl);
+  }
+
+  container.appendChild(root);
+}
+
 window.__museaSetProps = (props) => {
   // Clear old keys
   for (const key of Object.keys(propsOverride)) {
@@ -1281,13 +1427,7 @@ async function mount() {
     };
   } catch (error) {
     console.error('[musea-preview] Failed to mount:', error);
-    container.innerHTML = \`
-      <div class="musea-error">
-        <div class="musea-error-title">Failed to render component</div>
-        <div>\${error.message}</div>
-        <pre>\${error.stack || ''}</pre>
-      </div>
-    \`;
+    renderError('Failed to render component', error);
   }
 }
 
@@ -1300,7 +1440,7 @@ async function remountWithProps(Component) {
       return () => {
         const slotFns = {};
         for (const [name, content] of Object.entries(slotsOverride)) {
-          if (content) slotFns[name] = () => h('span', { innerHTML: content });
+          if (content) slotFns[name] = () => h('span', String(content));
         }
         return h(Component, { ...propsOverride }, slotFns);
       };
@@ -1353,6 +1493,23 @@ function ensureArtStyles(styles) {
   }
 }
 
+function renderError(title, error) {
+  container.textContent = '';
+  const root = document.createElement('div');
+  root.className = 'musea-error';
+
+  const titleEl = document.createElement('div');
+  titleEl.className = 'musea-error-title';
+  titleEl.textContent = title;
+  root.appendChild(titleEl);
+
+  const messageEl = document.createElement('div');
+  messageEl.textContent = error instanceof Error ? error.message : String(error);
+  root.appendChild(messageEl);
+
+  container.appendChild(root);
+}
+
 async function mount() {
   try {
     const VariantComponent = artModule['${variantComponentName}'];
@@ -1376,7 +1533,7 @@ async function mount() {
     __museaInitAddons(container, '${escapedVariantName}', ${actionEvents});
   } catch (error) {
     console.error('[musea-preview] Failed to mount:', error);
-    container.innerHTML = '<div class="musea-error"><div class="musea-error-title">Failed to render</div><div>' + error.message + '</div></div>';
+    renderError('Failed to render', error);
   }
 }
 
@@ -1395,7 +1552,11 @@ function resolveGallerySourceDir() {
 function toViteFsPath(filePath) {
 	return encodeURI(`/@fs${filePath.split(path.sep).join("/")}`);
 }
-async function tryLoadSourceGalleryHtml(devServer, url, basePath, themeConfig) {
+function generateDevGlobalsScript(basePath, devSessionToken, themeConfig) {
+	const themeScript = themeConfig ? `window.__MUSEA_THEME_CONFIG__=${serializeScriptValue(themeConfig)};` : "";
+	return `window.__MUSEA_BASE_PATH__=${serializeScriptValue(basePath)};window.__MUSEA_SESSION_TOKEN__=${serializeScriptValue(devSessionToken)};${themeScript}`;
+}
+async function tryLoadSourceGalleryHtml(devServer, url, basePath, devSessionToken, themeConfig) {
 	const gallerySourceDir = resolveGallerySourceDir();
 	const indexHtmlPath = path.join(gallerySourceDir, "index.html");
 	try {
@@ -1404,10 +1565,9 @@ async function tryLoadSourceGalleryHtml(devServer, url, basePath, themeConfig) {
 		return null;
 	}
 	const sourceEntryPath = toViteFsPath(path.join(gallerySourceDir, "main.ts"));
-	const themeScript = themeConfig ? `window.__MUSEA_THEME_CONFIG__=${JSON.stringify(themeConfig)};` : "";
 	let html = await fs.promises.readFile(indexHtmlPath, "utf-8");
 	html = html.replace("src=\"./main.ts\"", `src="${sourceEntryPath}"`);
-	html = html.replace("</head>", `<script>window.__MUSEA_BASE_PATH__='${basePath}';${themeScript}<\/script></head>`);
+	html = html.replace("</head>", `<script>${generateDevGlobalsScript(basePath, devSessionToken, themeConfig)}<\/script></head>`);
 	return devServer.transformIndexHtml(url, html);
 }
 /**
@@ -1422,7 +1582,7 @@ async function tryLoadSourceGalleryHtml(devServer, url, basePath, themeConfig) {
 * - Art module route
 */
 function registerMiddleware(devServer, ctx) {
-	const { basePath, themeConfig, artFiles } = ctx;
+	const { basePath, devSessionToken, themeConfig, artFiles } = ctx;
 	devServer.middlewares.use(basePath, async (req, res, next) => {
 		const url = req.url || "/";
 		if (url === "/" || url === "/index.html" || url.startsWith("/tokens") || url.startsWith("/component/") || url.startsWith("/tests")) {
@@ -1431,19 +1591,18 @@ function registerMiddleware(devServer, ctx) {
 			try {
 				await fs.promises.access(indexHtmlPath);
 				let html = await fs.promises.readFile(indexHtmlPath, "utf-8");
-				const themeScript = themeConfig ? `window.__MUSEA_THEME_CONFIG__=${JSON.stringify(themeConfig)};` : "";
-				html = html.replace("</head>", `<script>window.__MUSEA_BASE_PATH__='${basePath}';${themeScript}<\/script></head>`);
+				html = html.replace("</head>", `<script>${generateDevGlobalsScript(basePath, devSessionToken, themeConfig)}<\/script></head>`);
 				res.setHeader("Content-Type", "text/html");
 				res.end(html);
 				return;
 			} catch {
-				const sourceHtml = await tryLoadSourceGalleryHtml(devServer, url, basePath, themeConfig);
+				const sourceHtml = await tryLoadSourceGalleryHtml(devServer, url, basePath, devSessionToken, themeConfig);
 				if (sourceHtml) {
 					res.setHeader("Content-Type", "text/html");
 					res.end(sourceHtml);
 					return;
 				}
-				const html = generateGalleryHtml(basePath, themeConfig);
+				const html = generateGalleryHtml(basePath, devSessionToken, themeConfig);
 				res.setHeader("Content-Type", "text/html");
 				res.end(html);
 				return;
@@ -1451,8 +1610,8 @@ function registerMiddleware(devServer, ctx) {
 		}
 		if (url.startsWith("/assets/")) {
 			const galleryDistDir = resolveGalleryDistDir();
-			const filePath = path.join(galleryDistDir, url);
 			try {
+				const filePath = resolveUrlPathInside(galleryDistDir, url, "asset path");
 				if ((await fs.promises.stat(filePath)).isFile()) {
 					const content = await fs.promises.readFile(filePath);
 					const ext = path.extname(filePath);
@@ -1469,7 +1628,13 @@ function registerMiddleware(devServer, ctx) {
 					res.end(content);
 					return;
 				}
-			} catch {}
+			} catch (error) {
+				if (error instanceof HttpError) {
+					res.statusCode = error.status;
+					res.end(error.message);
+					return;
+				}
+			}
 		}
 		next();
 	});
@@ -1792,6 +1957,18 @@ function scanTokenUsage(artFiles, tokenMap) {
 */
 const REFERENCE_PATTERN = /^\{(.+)\}$/;
 const MAX_RESOLVE_DEPTH = 10;
+const UNSAFE_TOKEN_PATH_SEGMENTS = new Set([
+	"__proto__",
+	"prototype",
+	"constructor"
+]);
+function parseTokenPath(dotPath) {
+	const parts = dotPath.split(".");
+	if (parts.length === 0 || parts.some((part) => part.trim() === "")) throw new Error(`Invalid token path "${dotPath}"`);
+	const unsafeSegment = parts.find((part) => UNSAFE_TOKEN_PATH_SEGMENTS.has(part));
+	if (unsafeSegment) throw new Error(`Token path segment "${unsafeSegment}" is not allowed`);
+	return parts;
+}
 /**
 * Flatten nested categories into a flat map keyed by dot-path.
 */
@@ -1862,7 +2039,7 @@ async function writeRawTokenFile(tokensPath, data) {
 * Set a token at a dot-separated path in the raw JSON structure.
 */
 function setTokenAtPath(data, dotPath, token) {
-	const parts = dotPath.split(".");
+	const parts = parseTokenPath(dotPath);
 	let current = data;
 	for (let i = 0; i < parts.length - 1; i++) {
 		const key = parts[i];
@@ -1882,7 +2059,7 @@ function setTokenAtPath(data, dotPath, token) {
 * Delete a token at a dot-separated path, cleaning empty parents.
 */
 function deleteTokenAtPath(data, dotPath) {
-	const parts = dotPath.split(".");
+	const parts = parseTokenPath(dotPath);
 	const parents = [];
 	let current = data;
 	for (let i = 0; i < parts.length - 1; i++) {
@@ -1960,27 +2137,34 @@ function findDependentTokens(tokenMap, targetPath) {
 * Generates HTML, Markdown, and JSON documentation from parsed token categories,
 * and provides the main processStyleDictionary orchestrator function.
 */
+const SAFE_CSS_COLOR_PATTERN = /^(?:#[0-9a-fA-F]{3,8}|(?:rgb|hsl)a?\(\s*[-+.\d,%\s]+\))$/;
+function safeCssColor(value, type) {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	return (type === "color" || trimmed.startsWith("#") || trimmed.startsWith("rgb") || trimmed.startsWith("hsl")) && SAFE_CSS_COLOR_PATTERN.test(trimmed) ? trimmed : null;
+}
 /**
 * Generate HTML documentation for tokens.
 */
 function generateTokensHtml(categories) {
 	const renderToken = (name, token) => {
+		const color = safeCssColor(token.value, token.type);
 		return `
       <div class="token">
         <div class="token-preview">
-          ${typeof token.value === "string" && (token.value.startsWith("#") || token.value.startsWith("rgb") || token.value.startsWith("hsl") || token.type === "color") ? `<div class="color-swatch" style="background: ${token.value}"></div>` : ""}
+          ${color ? `<div class="color-swatch" style="background: ${color}"></div>` : ""}
         </div>
         <div class="token-info">
-          <div class="token-name">${name}</div>
-          <div class="token-value">${token.value}</div>
-          ${token.description ? `<div class="token-description">${token.description}</div>` : ""}
+          <div class="token-name">${escapeHtml(name)}</div>
+          <div class="token-value">${escapeHtml(String(token.value))}</div>
+          ${token.description ? `<div class="token-description">${escapeHtml(token.description)}</div>` : ""}
         </div>
       </div>
     `;
 	};
 	const renderCategory = (category, level = 2) => {
 		const heading = `h${Math.min(level, 6)}`;
-		let html = `<${heading}>${category.name}</${heading}>`;
+		let html = `<${heading}>${escapeHtml(category.name)}</${heading}>`;
 		html += "<div class=\"tokens-grid\">";
 		for (const [name, token] of Object.entries(category.tokens)) html += renderToken(name, token);
 		html += "</div>";
@@ -2130,16 +2314,20 @@ async function processStyleDictionary(config) {
 }
 //#endregion
 //#region src/api-tokens.ts
-/**
-* Musea gallery API token route handlers.
-*
-* Handles GET/POST/PUT/DELETE for /api/tokens endpoints:
-* - GET /tokens       -- list all resolved design tokens
-* - GET /tokens/usage -- token usage across art files
-* - POST /tokens      -- create a new token
-* - PUT /tokens       -- update an existing token
-* - DELETE /tokens    -- delete a token
-*/
+function resolveTokensPath(ctx) {
+	return resolveInside(ctx.config.root, ctx.tokensPath, "tokensPath");
+}
+function sendTokenMutationError(e, sendError) {
+	if (e instanceof HttpError) {
+		sendError(e.message, e.status);
+		return;
+	}
+	if (e instanceof Error && /token path/i.test(e.message)) {
+		sendError(e.message, 400);
+		return;
+	}
+	sendError(e instanceof Error ? e.message : String(e));
+}
 /** GET /api/tokens/usage */
 async function handleTokensUsage(ctx, sendJson) {
 	if (!ctx.tokensPath) {
@@ -2147,7 +2335,7 @@ async function handleTokensUsage(ctx, sendJson) {
 		return;
 	}
 	try {
-		const categories = await parseTokens(path.resolve(ctx.config.root, ctx.tokensPath));
+		const categories = await parseTokens(resolveTokensPath(ctx));
 		resolveReferences(categories, buildTokenMap(categories));
 		const resolvedTokenMap = buildTokenMap(categories);
 		sendJson(scanTokenUsage(ctx.artFiles, resolvedTokenMap));
@@ -2172,7 +2360,7 @@ async function handleTokensGet(ctx, sendJson) {
 		return;
 	}
 	try {
-		const absoluteTokensPath = path.resolve(ctx.config.root, ctx.tokensPath);
+		const absoluteTokensPath = resolveTokensPath(ctx);
 		const categories = await parseTokens(absoluteTokensPath);
 		resolveReferences(categories, buildTokenMap(categories));
 		const resolvedTokenMap = buildTokenMap(categories);
@@ -2212,7 +2400,7 @@ async function handleTokensCreate(ctx, readBody, sendJson, sendError) {
 			sendError("Missing required fields: path, token.value", 400);
 			return;
 		}
-		const absoluteTokensPath = path.resolve(ctx.config.root, ctx.tokensPath);
+		const absoluteTokensPath = resolveTokensPath(ctx);
 		const rawData = await readRawTokenFile(absoluteTokensPath);
 		const currentMap = buildTokenMap(await parseTokens(absoluteTokensPath));
 		if (currentMap[dotPath]) {
@@ -2237,7 +2425,7 @@ async function handleTokensCreate(ctx, readBody, sendJson, sendError) {
 			tokenMap: buildTokenMap(categories)
 		}, 201);
 	} catch (e) {
-		sendError(e instanceof Error ? e.message : String(e));
+		sendTokenMutationError(e, sendError);
 	}
 }
 /** PUT /api/tokens (update) */
@@ -2253,7 +2441,7 @@ async function handleTokensUpdate(ctx, readBody, sendJson, sendError) {
 			sendError("Missing required fields: path, token.value", 400);
 			return;
 		}
-		const absoluteTokensPath = path.resolve(ctx.config.root, ctx.tokensPath);
+		const absoluteTokensPath = resolveTokensPath(ctx);
 		if (token.$reference) {
 			const validation = validateSemanticReference(buildTokenMap(await parseTokens(absoluteTokensPath)), token.$reference, dotPath);
 			if (!validation.valid) {
@@ -2273,7 +2461,7 @@ async function handleTokensUpdate(ctx, readBody, sendJson, sendError) {
 			tokenMap: buildTokenMap(categories)
 		});
 	} catch (e) {
-		sendError(e instanceof Error ? e.message : String(e));
+		sendTokenMutationError(e, sendError);
 	}
 }
 /** DELETE /api/tokens */
@@ -2289,7 +2477,7 @@ async function handleTokensDelete(ctx, readBody, sendJson, sendError) {
 			sendError("Missing required field: path", 400);
 			return;
 		}
-		const absoluteTokensPath = path.resolve(ctx.config.root, ctx.tokensPath);
+		const absoluteTokensPath = resolveTokensPath(ctx);
 		const dependents = findDependentTokens(buildTokenMap(await parseTokens(absoluteTokensPath)), dotPath);
 		const rawData = await readRawTokenFile(absoluteTokensPath);
 		if (!deleteTokenAtPath(rawData, dotPath)) {
@@ -2305,7 +2493,7 @@ async function handleTokensDelete(ctx, readBody, sendJson, sendError) {
 			dependentsWarning: dependents.length > 0 ? dependents : void 0
 		});
 	} catch (e) {
-		sendError(e instanceof Error ? e.message : String(e));
+		sendTokenMutationError(e, sendError);
 	}
 }
 //#endregion
@@ -2512,15 +2700,23 @@ function handlePreviewWithProps(ctx, body, res, sendJson, sendError) {
 		res.setHeader("Content-Type", "application/javascript");
 		res.end(moduleCode);
 	} catch (e) {
+		if (e instanceof HttpError) {
+			sendError(e.message, e.status);
+			return;
+		}
 		sendError(e instanceof Error ? e.message : String(e));
 	}
 }
 /** POST /api/generate */
-async function handleGenerate(body, sendJson, sendError) {
+async function handleGenerate(ctx, body, sendJson, sendError) {
 	try {
 		const { componentPath: reqComponentPath, options: autogenOptions } = JSON.parse(body);
+		if (typeof reqComponentPath !== "string") {
+			sendError("Missing required field: componentPath", 400);
+			return;
+		}
 		const { generateArtFile: genArt } = await import("./autogen/index.mjs");
-		const result = await genArt(reqComponentPath, autogenOptions);
+		const result = await genArt(resolveInside(ctx.config.root, reqComponentPath, "componentPath"), autogenOptions);
 		sendJson({
 			generated: true,
 			componentName: result.componentName,
@@ -2528,6 +2724,10 @@ async function handleGenerate(body, sendJson, sendError) {
 			artFileContent: result.artFileContent
 		});
 	} catch (e) {
+		if (e instanceof HttpError) {
+			sendError(e.message, e.status);
+			return;
+		}
 		sendError(e instanceof Error ? e.message : String(e));
 	}
 }
@@ -2590,16 +2790,6 @@ async function handleRunVrt(ctx, body, sendJson, sendError) {
 }
 //#endregion
 //#region src/api-routes/index.ts
-/** Helper to read the full request body as a string. */
-function collectBody(req) {
-	return new Promise((resolve) => {
-		let body = "";
-		req.on("data", (chunk) => {
-			body += chunk;
-		});
-		req.on("end", () => resolve(body));
-	});
-}
 /**
 * Create the API middleware handler for the Musea gallery.
 *
@@ -2616,107 +2806,117 @@ function createApiMiddleware(ctx) {
 		const sendError = (message, status = 500) => {
 			sendJson({ error: message }, status);
 		};
-		const readBody = () => collectBody(req);
+		const readBody = () => collectRequestBody(req, ctx.apiBodyLimit ?? 1048576);
 		const url = req.url || "/";
-		if (url === "/arts" && req.method === "GET") {
-			sendJson(Array.from(ctx.artFiles.values()));
-			return;
-		}
-		if (url === "/tokens/usage" && req.method === "GET") {
-			await handleTokensUsage(ctx, sendJson);
-			return;
-		}
-		if (url === "/tokens" && req.method === "GET") {
-			await handleTokensGet(ctx, sendJson);
-			return;
-		}
-		if (url === "/tokens" && req.method === "POST") {
-			await handleTokensCreate(ctx, readBody, sendJson, sendError);
-			return;
-		}
-		if (url === "/tokens" && req.method === "PUT") {
-			await handleTokensUpdate(ctx, readBody, sendJson, sendError);
-			return;
-		}
-		if (url === "/tokens" && req.method === "DELETE") {
-			await handleTokensDelete(ctx, readBody, sendJson, sendError);
-			return;
-		}
-		if (url?.startsWith("/arts/") && req.method === "PUT") {
-			const sourceMatch = url.slice(6).match(/^(.+)\/source$/);
-			if (sourceMatch) {
-				const artPath = decodeURIComponent(sourceMatch[1]);
-				if (!ctx.artFiles.get(artPath)) {
-					sendError("Art not found", 404);
-					return;
-				}
-				const body = await collectBody(req);
-				try {
-					const { source } = JSON.parse(body);
-					if (typeof source !== "string") {
-						sendError("Missing required field: source", 400);
-						return;
-					}
-					await fs.promises.writeFile(artPath, source, "utf-8");
-					await ctx.processArtFile(artPath);
-					sendJson({ success: true });
-				} catch (e) {
-					sendError(e instanceof Error ? e.message : String(e));
-				}
+		try {
+			const requestError = validateDevApiRequest(req, ctx.devSessionToken);
+			if (requestError) {
+				sendError(requestError.message, requestError.status);
 				return;
 			}
-			next();
-			return;
-		}
-		if (url?.startsWith("/arts/") && req.method === "GET") {
-			const rest = url.slice(6);
-			const sourceMatch = rest.match(/^(.+)\/source$/);
-			const paletteMatch = rest.match(/^(.+)\/palette$/);
-			const analysisMatch = rest.match(/^(.+)\/analysis$/);
-			const docsMatch = rest.match(/^(.+)\/docs$/);
-			const a11yMatch = rest.match(/^(.+)\/variants\/([^/]+)\/a11y$/);
-			if (sourceMatch) {
-				await handleArtSource(ctx, sourceMatch, sendJson, sendError);
+			if (url === "/arts" && req.method === "GET") {
+				sendJson(Array.from(ctx.artFiles.values()));
 				return;
 			}
-			if (paletteMatch) {
-				await handleArtPalette(ctx, paletteMatch, sendJson, sendError);
+			if (url === "/tokens/usage" && req.method === "GET") {
+				await handleTokensUsage(ctx, sendJson);
 				return;
 			}
-			if (analysisMatch) {
-				await handleArtAnalysis(ctx, analysisMatch, sendJson, sendError);
+			if (url === "/tokens" && req.method === "GET") {
+				await handleTokensGet(ctx, sendJson);
 				return;
 			}
-			if (docsMatch) {
-				await handleArtDocs(ctx, docsMatch, sendJson, sendError);
+			if (url === "/tokens" && req.method === "POST") {
+				await handleTokensCreate(ctx, readBody, sendJson, sendError);
 				return;
 			}
-			if (a11yMatch) {
-				handleArtA11y(ctx, a11yMatch, sendJson, sendError);
+			if (url === "/tokens" && req.method === "PUT") {
+				await handleTokensUpdate(ctx, readBody, sendJson, sendError);
 				return;
 			}
-			const artPath = decodeURIComponent(rest);
-			const art = ctx.artFiles.get(artPath);
-			if (art) sendJson(art);
-			else sendError("Art not found", 404);
-			return;
-		}
-		if (req.method === "POST") {
-			const body = await collectBody(req);
-			if (url === "/preview-with-props") {
-				handlePreviewWithProps(ctx, body, res, sendJson, sendError);
+			if (url === "/tokens" && req.method === "DELETE") {
+				await handleTokensDelete(ctx, readBody, sendJson, sendError);
 				return;
 			}
-			if (url === "/generate") {
-				await handleGenerate(body, sendJson, sendError);
+			if (url?.startsWith("/arts/") && req.method === "PUT") {
+				const sourceMatch = url.slice(6).match(/^(.+)\/source$/);
+				if (sourceMatch) {
+					const artPath = decodeURIComponent(sourceMatch[1]);
+					if (!ctx.artFiles.get(artPath)) {
+						sendError("Art not found", 404);
+						return;
+					}
+					const safeArtPath = resolveInside(ctx.config.root, artPath, "art path");
+					const body = await readBody();
+					const { source } = JSON.parse(body);
+					if (typeof source !== "string") {
+						sendError("Missing required field: source", 400);
+						return;
+					}
+					await fs.promises.writeFile(safeArtPath, source, "utf-8");
+					await ctx.processArtFile(safeArtPath);
+					sendJson({ success: true });
+					return;
+				}
+				next();
 				return;
 			}
-			if (url === "/run-vrt") {
-				await handleRunVrt(ctx, body, sendJson, sendError);
+			if (url?.startsWith("/arts/") && req.method === "GET") {
+				const rest = url.slice(6);
+				const sourceMatch = rest.match(/^(.+)\/source$/);
+				const paletteMatch = rest.match(/^(.+)\/palette$/);
+				const analysisMatch = rest.match(/^(.+)\/analysis$/);
+				const docsMatch = rest.match(/^(.+)\/docs$/);
+				const a11yMatch = rest.match(/^(.+)\/variants\/([^/]+)\/a11y$/);
+				if (sourceMatch) {
+					await handleArtSource(ctx, sourceMatch, sendJson, sendError);
+					return;
+				}
+				if (paletteMatch) {
+					await handleArtPalette(ctx, paletteMatch, sendJson, sendError);
+					return;
+				}
+				if (analysisMatch) {
+					await handleArtAnalysis(ctx, analysisMatch, sendJson, sendError);
+					return;
+				}
+				if (docsMatch) {
+					await handleArtDocs(ctx, docsMatch, sendJson, sendError);
+					return;
+				}
+				if (a11yMatch) {
+					handleArtA11y(ctx, a11yMatch, sendJson, sendError);
+					return;
+				}
+				const artPath = decodeURIComponent(rest);
+				const art = ctx.artFiles.get(artPath);
+				if (art) sendJson(art);
+				else sendError("Art not found", 404);
+				return;
+			}
+			if (req.method === "POST") {
+				const body = await readBody();
+				if (url === "/preview-with-props") {
+					handlePreviewWithProps(ctx, body, res, sendJson, sendError);
+					return;
+				}
+				if (url === "/generate") {
+					await handleGenerate(ctx, body, sendJson, sendError);
+					return;
+				}
+				if (url === "/run-vrt") {
+					await handleRunVrt(ctx, body, sendJson, sendError);
+					return;
+				}
+			}
+			next();
+		} catch (e) {
+			if (e instanceof HttpError) {
+				sendError(e.message, e.status);
 				return;
 			}
+			sendError(e instanceof Error ? e.message : String(e));
 		}
-		next();
 	};
 }
 //#endregion
@@ -2855,6 +3055,7 @@ function musea(options = {}) {
 	const themeConfig = buildThemeConfig(options.theme);
 	const previewCss = options.previewCss ?? [];
 	const previewSetup = options.previewSetup;
+	const devSessionToken = createDevSessionToken();
 	let config;
 	let server = null;
 	const artFiles = /* @__PURE__ */ new Map();
@@ -2902,6 +3103,7 @@ function musea(options = {}) {
 			devServer.watcher.add(scanRoots);
 			registerMiddleware(devServer, {
 				basePath,
+				devSessionToken,
 				themeConfig,
 				artFiles,
 				resolvedPreviewCss,
@@ -2914,6 +3116,7 @@ function musea(options = {}) {
 				basePath,
 				resolvedPreviewCss,
 				resolvedPreviewSetup,
+				devSessionToken,
 				processArtFile,
 				getDevServerPort: () => devServer.config.server.port || 5173
 			}));