fix: serve projects and assets whose names contain @ % # & or ? (#4415)

* fix(studio-server): serve projects whose names contain @ % # & or ?

Five routes cut the decoded project id out of Hono's c.req.path, which leaves %40 %25 %23 %26 %3F
encoded, so the cut missed and files, preview assets, sub-compositions, thumbnails and waveforms
404ed or 403ed for those names. One helper now takes the sub-path by segment from the raw URL.

* fix(studio-server): thumbnails and waveforms stay inside the project for any name

The thumbnail route built its preview URL from the raw project id and path, so # ? and % broke it,
and neither route checked that the decoded path stays inside the project. Thumbnails now use the
composition guard and an encoded URL; waveforms use the read-only asset guard.

* fix(cli): play and present serve assets whose names contain @ % # & or ?

Both /composition/* routes cut a prefix out of Hono's c.req.path with no decode. They now share
studio-server's requestSubPath (renamed from projectSubPath and generalised to any route) with the
five studio-server routes, so one helper owns how a request path becomes a file path.

* fix(studio-server): a thumbnail request for the project folder answers 404

An empty thumbnail path resolved to the project directory and crashed reading it (500).

* fix(studio-server): read the thumbnail's composition with one open

Checking the path with stat and then reading it let the file change in between (CodeQL
js/file-system-race). One open now serves the type check, the mtime and the read; a missing file
still thumbnails from the preview as before, anything that is not a file answers 404.

Author: miguel-heygen

packages/cli/src/commands/compositionRoute.encoding.test.ts

@@ -0,0 +1,53 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Hono } from "hono";
+import type { ProjectDir } from "../utils/project.js";
+import { registerCompositionRoute } from "./play.js";
+import { registerPresentCompositionRoute } from "./present.js";
+
+// Hono's c.req.path leaves %40 %25 %23 %26 %3F encoded; Windows file names cannot hold "?".
+const NAMES = [
+  "A @HyperFrames launch",
+  "50% off",
+  "#2 take",
+  "Tom & Jerry",
+  ...(process.platform === "win32" ? [] : ["why?"]),
+  "two  spaces",
+  "café crème",
+  "🎬 film",
+];
+
+const ROUTES = [
+  ["play", (app: Hono, project: ProjectDir) => registerCompositionRoute(app, project, false)],
+  ["present", registerPresentCompositionRoute],
+] as const;
+
+let dir: string | undefined;
+
+afterEach(() => {
+  if (dir) rmSync(dir, { recursive: true, force: true });
+  dir = undefined;
+});
+
+async function requestAsset(
+  register: (app: Hono, project: ProjectDir) => Promise<void>,
+  name: string,
+) {
+  dir = mkdtempSync(join(tmpdir(), "hf-composition-route-"));
+  mkdirSync(join(dir, "scenes"));
+  writeFileSync(join(dir, "scenes", `${name}.txt`), `ASSET ${name}`);
+  const app = new Hono();
+  await register(app, { dir, name: "test-project", indexPath: join(dir, "index.html") });
+  const response = await app.request(`/composition/scenes/${encodeURIComponent(`${name}.txt`)}`);
+  return { status: response.status, text: await response.text() };
+}
+
+describe.each(ROUTES)("%s /composition/*", (_route, register) => {
+  it.each(NAMES)("serves an asset named %j", async (name) => {
+    const result = await requestAsset(register, name);
+    expect(result.status).toBe(200);
+    expect(result.text).toBe(`ASSET ${name}`);
+  });
+});

packages/cli/src/commands/play.ts

@@ -20,6 +20,7 @@ export const examples: Example[] = [
 ];
 import { resolve } from "node:path";
 import type { Hono } from "hono";
+import { requestSubPath } from "@hyperframes/studio-server";
 import * as clack from "@clack/prompts";
 import { c } from "../ui/colors.js";
 import { resolveProject, type ProjectDir } from "../utils/project.js";
@@ -213,7 +214,7 @@ export async function registerCompositionRoute(
 
   // fallow-ignore-next-line complexity
   app.get("/composition/*", async (ctx) => {
-    const reqPath = ctx.req.path.replace("/composition/", "");
+    const reqPath = requestSubPath(ctx.req.url, "composition");
     const filePath = resolve(project.dir, reqPath);
 
     // Security: don't allow path traversal outside project dir. isSafePath

packages/cli/src/commands/present.ts

@@ -13,7 +13,9 @@ export const examples: Example[] = [
 import { resolve } from "node:path";
 import * as clack from "@clack/prompts";
 import { c } from "../ui/colors.js";
-import { resolveProject } from "../utils/project.js";
+import { resolveProject, type ProjectDir } from "../utils/project.js";
+import type { Hono } from "hono";
+import { requestSubPath } from "@hyperframes/studio-server";
 import {
   openBrowser,
   parseRemoteDebuggingPort,
@@ -113,7 +115,6 @@ export default defineCommand({
 
     const { Hono } = await import("hono");
     const { createAdaptorServer } = await import("@hono/node-server");
-    const { isSafePath } = await import("@hyperframes/core/studio-api");
 
     const app = new Hono();
 
@@ -133,16 +134,7 @@ export default defineCommand({
     // timelines (no engine runtime injected) — the same model demo.html / the
     // standalone harness use; injecting a runtime would leave the composition
     // engine-paused and blank.
-    app.get("/composition/*", (ctx) => {
-      const reqPath = ctx.req.path.replace("/composition/", "");
-      const filePath = resolve(project.dir, reqPath);
-      // Security: canonicalizes symlinks + guards the trailing separator so neither
-      // an in-project symlink nor a sibling dir sharing the prefix can escape.
-      if (!isSafePath(project.dir, filePath)) return ctx.text("Forbidden", 403);
-      if (!existsSync(filePath)) return ctx.text("Not found", 404);
-      if (filePath.endsWith(".html")) return ctx.html(readFileSync(filePath, "utf-8"));
-      return ctx.body(readFileSync(filePath), 200, { "Content-Type": assetContentType(filePath) });
-    });
+    await registerPresentCompositionRoute(app, project);
 
     // Both the presenter window and the audience window (opened by present() with
     // ?mode=audience) load this same page; the component reads the mode from the URL.
@@ -309,3 +301,20 @@ function escHtml(value: string): string {
     .replace(/>/g, ">")
     .replace(/"/g, """);
 }
+
+export async function registerPresentCompositionRoute(
+  app: Hono,
+  project: ProjectDir,
+): Promise<void> {
+  const { isSafePath } = await import("@hyperframes/core/studio-api");
+  app.get("/composition/*", (ctx) => {
+    const reqPath = requestSubPath(ctx.req.url, "composition");
+    const filePath = resolve(project.dir, reqPath);
+    // Security: canonicalizes symlinks + guards the trailing separator so neither
+    // an in-project symlink nor a sibling dir sharing the prefix can escape.
+    if (!isSafePath(project.dir, filePath)) return ctx.text("Forbidden", 403);
+    if (!existsSync(filePath)) return ctx.text("Not found", 404);
+    if (filePath.endsWith(".html")) return ctx.html(readFileSync(filePath, "utf-8"));
+    return ctx.body(readFileSync(filePath), 200, { "Content-Type": assetContentType(filePath) });
+  });
+}

packages/studio-server/src/helpers/requestSubPath.ts

@@ -0,0 +1,8 @@
+// The decoded path after `route` ("projects/:id/preview", "composition"), cut by segment from the raw URL:
+// Hono's c.req.path leaves %40 %25 %23 %26 %3F encoded, so cutting a decoded prefix out of it misses.
+export function requestSubPath(url: string, route: string): string {
+  const routeSegments = route.split("/");
+  const segments = new URL(url).pathname.split("/");
+  const start = segments.indexOf(routeSegments[0] ?? "");
+  return decodeURIComponent(segments.slice(start + routeSegments.length).join("/"));
+}

packages/studio-server/src/index.ts

@@ -31,6 +31,7 @@ export {
 export type { PreviewApiAdapter } from "./helpers/mediaProxyPreview.js";
 export { PREVIEW_BUNDLE_OPTIONS } from "./routes/preview.js";
 export { getMimeType, MIME_TYPES } from "./helpers/mime.js";
+export { requestSubPath } from "./helpers/requestSubPath.js";
 export {
   consumeFileWriteReceipt,
   identifyFileWrite,

packages/studio-server/src/routes/files.ts

@@ -89,6 +89,7 @@ import {
   insertCompositionIntoSource,
 } from "../helpers/compositionInsertion.js";
 import { resolveGsapWriter } from "./gsapMutationCapabilities.js";
+import { requestSubPath } from "../helpers/requestSubPath.js";
 
 // ── Server cutover flag ─────────────────────────────────────────────────────
 
@@ -114,7 +115,7 @@ async function loadGsapParser() {
 interface RouteContext {
   req: {
     param: (name: string) => string;
-    path: string;
+    url: string;
     query: (name: string) => string | undefined;
     header: (name: string) => string | undefined;
   };
@@ -172,7 +173,7 @@ function isDanglingSymlinkInProject(projectDir: string, lexicalPath: string): bo
 async function resolveProjectPath(
   c: RouteContext,
   adapter: StudioApiAdapter,
-  pathPrefix: (projectId: string) => string,
+  route: string,
   opts?: { mustExist?: boolean },
 ) {
   const id = c.req.param("id");
@@ -195,7 +196,7 @@ async function resolveProjectPath(
     } as const;
   }
 
-  const filePath = decodeURIComponent(c.req.path.replace(pathPrefix(project.id), ""));
+  const filePath = requestSubPath(c.req.url, `projects/:id/${route}`);
   if (filePath.includes("\0")) {
     return { error: c.json({ error: "forbidden", why: "nul" }, 403) } as const;
   }
@@ -220,11 +221,11 @@ function resolveProjectFile(
   adapter: StudioApiAdapter,
   opts?: { mustExist?: boolean },
 ) {
-  return resolveProjectPath(c, adapter, (id) => `/projects/${id}/files/`, opts);
+  return resolveProjectPath(c, adapter, "files", opts);
 }
 
 function resolveFileMutationContext(c: RouteContext, adapter: StudioApiAdapter, operation: string) {
-  return resolveProjectPath(c, adapter, (id) => `/projects/${id}/file-mutations/${operation}/`);
+  return resolveProjectPath(c, adapter, `file-mutations/${operation}`);
 }
 
 type MutationTarget = {
@@ -3222,7 +3223,7 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
   // ── GSAP Animations (parse) ──
 
   api.get("/projects/:id/gsap-animations/*", async (c) => {
-    const res = await resolveProjectPath(c, adapter, (id) => `/projects/${id}/gsap-animations/`, {
+    const res = await resolveProjectPath(c, adapter, "gsap-animations", {
       mustExist: true,
     });
     if ("error" in res) return res.error;
@@ -3251,7 +3252,7 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
   });
 
   api.post("/projects/:id/gsap-mutations/*", async (c) => {
-    const res = await resolveProjectPath(c, adapter, (id) => `/projects/${id}/gsap-mutations/`, {
+    const res = await resolveProjectPath(c, adapter, "gsap-mutations", {
       mustExist: true,
     });
     if ("error" in res) return res.error;
@@ -3264,12 +3265,7 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
   });
 
   api.post("/projects/:id/gsap-mutations-batch/*", async (c) => {
-    const res = await resolveProjectPath(
-      c,
-      adapter,
-      (id) => `/projects/${id}/gsap-mutations-batch/`,
-      { mustExist: true },
-    );
+    const res = await resolveProjectPath(c, adapter, "gsap-mutations-batch", { mustExist: true });
     if ("error" in res) return res.error;
 
     const body = (await c.req.json().catch(() => null)) as {
@@ -3289,12 +3285,7 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
   // mutation wrote. Keep compare + write in this synchronous server section so
   // another request cannot land between a client-side check and the restore.
   api.post("/projects/:id/gsap-mutation-rollback/*", async (c) => {
-    const res = await resolveProjectPath(
-      c,
-      adapter,
-      (id) => `/projects/${id}/gsap-mutation-rollback/`,
-      { mustExist: true },
-    );
+    const res = await resolveProjectPath(c, adapter, "gsap-mutation-rollback", { mustExist: true });
     if ("error" in res) return res.error;
 
     const body = (await c.req.json().catch(() => null)) as {

packages/studio-server/src/routes/preview.ts

@@ -47,6 +47,7 @@ import {
   resolvePreviewMediaCodecProbeCache,
   type PreviewApiAdapter,
 } from "../helpers/mediaProxyPreview.js";
+import { requestSubPath } from "../helpers/requestSubPath.js";
 
 const PROJECT_SIGNATURE_META = "hyperframes-project-signature";
 const GSAP_CDN_VERSION = "3.15.0";
@@ -471,9 +472,7 @@ export function registerPreviewRoutes(api: Hono, adapter: PreviewApiAdapter): vo
     const vars = previewVariablesFromRequest(c.req.query("variables"));
     if (vars.error !== undefined) return c.json({ error: vars.error }, 400);
     const previewVariables = vars.values;
-    const compPath = decodeURIComponent(
-      c.req.path.replace(`/projects/${project.id}/preview/comp/`, "").split("?")[0] ?? "",
-    );
+    const compPath = requestSubPath(c.req.url, "projects/:id/preview/comp");
     const compFile = resolveWithinProject(project.dir, compPath);
     if (!compFile || !existsSync(compFile) || !statSync(compFile).isFile()) {
       return c.text("not found", 404);
@@ -516,9 +515,7 @@ export function registerPreviewRoutes(api: Hono, adapter: PreviewApiAdapter): vo
   api.get("/projects/:id/preview/*", async (c) => {
     const project = await adapter.resolveProject(c.req.param("id"));
     if (!project) return c.json({ error: "not found" }, 404);
-    const subPath = decodeURIComponent(
-      c.req.path.replace(`/projects/${project.id}/preview/`, "").split("?")[0] ?? "",
-    );
+    const subPath = requestSubPath(c.req.url, "projects/:id/preview");
     // Assets are read-only and should mirror the renderer: permit a path that
     // is lexically inside the project even if an explicit project symlink
     // targets a shared directory outside it. Composition source files still