fix(core,cli): route render + play composition paths through isSafePath

Review on #1397 found a third call site with the same vulnerable
startsWith pattern. Apply Rule 2: fix every site sharing the contract
(gate an attacker-influenced path before a symlink-following fs op).

- studio-api routes/render.ts: body.composition (from c.req.json()) was
  checked with `resolved.startsWith(resolve(project.dir) + sep)`, which
  doesn't dereference symlinks — an in-project symlink to an external
  target escaped the project root. Now uses isSafePath().
- cli commands/play.ts: the `/composition/*` server route used
  `filePath.startsWith(project.dir)` with no trailing-separator guard, so
  both a sibling dir sharing the prefix (`<dir>-evil`) and symlink escapes
  passed. Now uses isSafePath() via @hyperframes/core/studio-api (the same
  lazy-import pattern commands/validate.ts already uses).

Tests: render.test.ts gains a "composition path safety" block (in-base
allow, `..` reject, in-project-symlink-to-outside reject, in-project
symlink staying inside allow). The shared render test adapter now points
at a real dir since isSafePath fails closed on an unresolvable base
(production project dirs always exist on disk).

Not in this change: compiler/htmlBundler.ts has the same class at two
sites (safePath helper + inline CSS @import check), but the compiler sits
below studio-api in the dependency graph and can't import isSafePath
without a backwards edge; that fix needs the helper promoted to a neutral
module and is tracked as a follow-up. renderArgs.ts / videoFrameExtractor.ts
carry the trailing-sep guard and a local-CLI/engine-internal threat model.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jrusso1020

packages/cli/src/commands/play.ts

@@ -100,6 +100,7 @@ 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();
 
@@ -124,8 +125,11 @@ export default defineCommand({
       const reqPath = ctx.req.path.replace("/composition/", "");
       const filePath = resolve(project.dir, reqPath);
 
-      // Security: don't allow path traversal outside project dir
-      if (!filePath.startsWith(project.dir)) return ctx.text("Forbidden", 403);
+      // Security: don't allow path traversal outside project dir. isSafePath
+      // canonicalizes symlinks and applies a trailing-separator guard, so neither
+      // an in-project symlink to an external target nor a sibling dir whose name
+      // shares the project-dir prefix (e.g. `<dir>-evil`) can escape.
+      if (!isSafePath(project.dir, filePath)) return ctx.text("Forbidden", 403);
       if (!existsSync(filePath)) return ctx.text("Not found", 404);
 
       const content = readFileSync(filePath, "utf-8");

packages/core/src/studio-api/routes/render.test.ts

@@ -1,6 +1,6 @@
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { Hono } from "hono";
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { VALID_CANVAS_RESOLUTIONS } from "../../core.types";
@@ -13,7 +13,9 @@ function createAdapter(
 ): { adapter: StudioApiAdapter; rendersDir: string } {
   const adapter: StudioApiAdapter = {
     listProjects: () => [],
-    resolveProject: async (id: string) => ({ id, dir: "/tmp/proj" }),
+    // Use a real, existing dir: isSafePath() canonicalizes the project dir with
+    // realpath and fails closed if it doesn't exist (real projects always do).
+    resolveProject: async (id: string) => ({ id, dir: tmpdir() }),
     bundle: async () => null,
     lint: async () => ({ findings: [] }),
     runtimeUrl: "/api/runtime.js",
@@ -261,3 +263,83 @@ describe("POST /projects/:id/render — fps wire format", () => {
     }
   });
 });
+
+describe("POST /projects/:id/render — composition path safety", () => {
+  const tmpDirs: string[] = [];
+
+  function buildAppWithProjectDir(spy: ReturnType<typeof vi.fn>): {
+    app: Hono;
+    projectDir: string;
+  } {
+    const projectDir = mkdtempSync(join(tmpdir(), "hf-render-proj-"));
+    const rendersDir = mkdtempSync(join(tmpdir(), "hf-render-out-"));
+    tmpDirs.push(projectDir, rendersDir);
+    const adapter: StudioApiAdapter = {
+      listProjects: () => [],
+      resolveProject: async (id: string) => ({ id, dir: projectDir }),
+      bundle: async () => null,
+      lint: async () => ({ findings: [] }),
+      runtimeUrl: "/api/runtime.js",
+      rendersDir: () => rendersDir,
+      startRender: (opts) => {
+        spy(opts);
+        return { id: opts.jobId, status: "rendering", progress: 0, outputPath: opts.outputPath };
+      },
+    };
+    const app = new Hono();
+    registerRenderRoutes(app, adapter);
+    return { app, projectDir };
+  }
+
+  afterEach(() => {
+    for (const d of tmpDirs) rmSync(d, { recursive: true, force: true });
+    tmpDirs.length = 0;
+  });
+
+  async function postComposition(app: Hono, composition: string): Promise<Response> {
+    return app.request("http://localhost/projects/demo/render", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ fps: 30, quality: "standard", format: "mp4", composition }),
+    });
+  }
+
+  it("accepts a composition path inside the project directory", async () => {
+    const spy = vi.fn();
+    const { app } = buildAppWithProjectDir(spy);
+    const res = await postComposition(app, "scenes/intro.html");
+    expect(res.status).toBe(200);
+    expect(spy).toHaveBeenCalledOnce();
+  });
+
+  it("rejects a `..` traversal in the composition path", async () => {
+    const spy = vi.fn();
+    const { app } = buildAppWithProjectDir(spy);
+    const res = await postComposition(app, "../../etc/passwd");
+    expect(res.status).toBe(400);
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it("rejects a composition reached through an in-project symlink pointing outside the project", async () => {
+    const spy = vi.fn();
+    const { app, projectDir } = buildAppWithProjectDir(spy);
+    const external = mkdtempSync(join(tmpdir(), "hf-render-external-"));
+    tmpDirs.push(external);
+    writeFileSync(join(external, "secret.html"), "<html></html>");
+    symlinkSync(external, join(projectDir, "link"), "dir");
+    const res = await postComposition(app, "link/secret.html");
+    expect(res.status).toBe(400);
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it("allows a composition reached through an in-project symlink that stays inside the project", async () => {
+    const spy = vi.fn();
+    const { app, projectDir } = buildAppWithProjectDir(spy);
+    mkdirSync(join(projectDir, "real"));
+    writeFileSync(join(projectDir, "real", "scene.html"), "<html></html>");
+    symlinkSync(join(projectDir, "real"), join(projectDir, "alias"), "dir");
+    const res = await postComposition(app, "alias/scene.html");
+    expect(res.status).toBe(200);
+    expect(spy).toHaveBeenCalledOnce();
+  });
+});

packages/core/src/studio-api/routes/render.ts

@@ -1,9 +1,10 @@
 import type { Hono } from "hono";
 import { streamSSE } from "hono/streaming";
 import { existsSync, readFileSync, mkdirSync, unlinkSync, readdirSync, statSync } from "node:fs";
-import { join, resolve, sep } from "node:path";
+import { join, resolve } from "node:path";
 import type { StudioApiAdapter, RenderJobState } from "../types.js";
 import { VALID_CANVAS_RESOLUTIONS, parseFps, type CanvasResolution } from "../../core.types.js";
+import { isSafePath } from "../helpers/safePath.js";
 
 const VALID_RESOLUTIONS = new Set<string>(VALID_CANVAS_RESOLUTIONS);
 
@@ -80,7 +81,10 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
     let composition: string | undefined;
     if (typeof body.composition === "string" && body.composition.length > 0) {
       const resolved = resolve(project.dir, body.composition);
-      if (!resolved.startsWith(resolve(project.dir) + sep)) {
+      // `body.composition` is attacker-controlled (from c.req.json()). isSafePath
+      // dereferences symlinks so an in-project symlink pointing outside the root
+      // can't smuggle the render target out of the project dir.
+      if (!isSafePath(project.dir, resolved)) {
         return c.json({ error: "composition path must be within the project directory" }, 400);
       }
       composition = body.composition;