fix(studio-server): harden preview paths, cache folders and local servers (#7510)

* fix(studio-server): keep cache writes inside the project and canonicalize preview paths

- The tool's own folders (.hyperframes records, backups, preview documents,
  .thumbnails, .transcode-cache) are no longer written, pruned or emptied
  through a link that points outside the project. Thumbnails are still
  served when their cache folder is a link; they are just not cached.
- The hf-id stamp record and the history id are replaced atomically instead
  of written through an existing link.
- Sub-composition previews and thumbnails use the composition's canonical
  project-relative path, and the path is attribute-encoded in the document.
- Thumbnail requests from another site are refused before any capture.
- Saved GSAP scripts escape a `</script` sequence so the script element
  keeps its contents.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(core): refuse a UNC or device path on another root before any disk access

isSafePath now rejects a target whose root is a UNC or device root other than
the project's own before it calls realpath or lstat. Projects on a share keep working.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(studio): answer WebMCP clients only from Studio's own page

The polyfill now starts with its tab transport limited to Studio's origin and
its frame transport off, so a page that frames Studio cannot list or call its tools.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(inspector): check Host on the per-session preview server

The preview page server applies the inspector API's loopback Host rule, so a
rebound DNS name cannot read the bundled composition or project files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* revert(studio-server): keep writing media proxies through a linked .transcode-cache

Refusing the folder made every proxied video in such a project answer 502.
A linked cache folder now receives copies again; it is still never swept,
so nothing already in the folder it points at is removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(studio-server): drop a comment the comment ratchet refuses

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): skip HEIF and GIF preview prep when .hyperframes/prepared-assets is a link

The preview transform wrote converted images into .hyperframes/prepared-assets
through a link, so a project shipping .hyperframes as a link to another folder
had files written there. Such a project now gets its preview with the images
as written in the composition, unconverted, and nothing is written.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(studio-server): never sweep a linked .transcode-cache, from Studio or hyperframes clean

The link check moves into cleanupProxyCache, which both Studio's cache
maintenance and `hyperframes clean` call, so neither removes files from the
folder a linked .transcode-cache points at.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Michael Wang
2026-11-10 20:26:12 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 24508ce2da
commit b8bb491900
28 changed files with 740 additions and 41 deletions
@@ -8,9 +8,11 @@ import {
existsSync,
mkdirSync,
mkdtempSync,
readdirSync,
readFileSync,
renameSync,
rmSync,
symlinkSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
@@ -48,6 +50,27 @@ vi.mock("@hyperframes/producer", () => ({
executeRenderJob: (...args: Parameters<typeof producerState.executeRenderJob>) =>
producerState.executeRenderJob(...args),
}));
// Stand-ins for the HEIF and GIF steps: each writes a converted file where a real conversion would.
const imagePrep = vi.hoisted(() => ({
convert: async (html: string, options: { outputDir: string }) => {
const { mkdirSync, writeFileSync } = await import("node:fs");
mkdirSync(options.outputDir, { recursive: true });
writeFileSync(`${options.outputDir}/converted`, "image");
return { html, preparedAssets: new Map<string, string>() };
},
}));
vi.mock("../../../producer/src/services/heifImagePrep.js", () => ({
prepareHeifImageInputs: async (html: string, options: { outputDir: string }) => ({
...(await imagePrep.convert(html, options)),
preparedImages: [],
}),
}));
vi.mock("../../../producer/src/services/animatedGifPrep.js", () => ({
prepareAnimatedGifInputs: async (html: string, options: { outputDir: string }) => ({
...(await imagePrep.convert(html, options)),
preparedGifs: [],
}),
}));
const engineState = vi.hoisted(() => ({
acquireBrowser: async (..._args: unknown[]): Promise<unknown> => {
throw new Error("acquireBrowser called without a test double");
@@ -1201,3 +1224,43 @@ describe("createStudioServer Host check on every route", () => {
}
});
});
describe("createStudioServer preview image preparation", () => {
const html = '<div data-composition-id="main"><img src="photo.png"></div>';
const prepared = (projectDir: string) =>
["heif", "gif"].filter((kind) =>
existsSync(join(projectDir, ".hyperframes", "prepared-assets", kind, "converted")),
);
it("prepares HEIF and GIF images inside a project's own .hyperframes folder", async () => {
const projectDir = tmpProject();
server = createStudioServer({ projectDir });
await server.adapter.transformPreviewHtml?.({
html,
project: { id: "p", dir: projectDir },
activeCompositionPath: "index.html",
});
expect(prepared(projectDir)).toEqual(["heif", "gif"]);
});
it.skipIf(process.platform === "win32")(
"serves images unprepared when .hyperframes is a link, and writes nothing where it points",
async () => {
const projectDir = tmpProject();
const outside = tmpProject();
symlinkSync(outside, join(projectDir, ".hyperframes"));
server = createStudioServer({ projectDir });
const served = await server.adapter.transformPreviewHtml?.({
html,
project: { id: "p", dir: projectDir },
activeCompositionPath: "index.html",
});
expect(served).toContain('src="photo.png"');
expect(readdirSync(outside)).toEqual([]);
},
);
});
+4
View File
@@ -73,6 +73,7 @@ import {
historyCache,
} from "@hyperframes/studio-server";
import { encoderJobOptions } from "@hyperframes/studio-server/encoder-options";
import { isLinkFreeWithinProject } from "@hyperframes/studio-server/safe-path";
import { resolveAutoProxy } from "../utils/projectConfig.js";
import {
clearElementScreenshotIsolation,
@@ -564,6 +565,9 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
const gifOutputDir = join(project.dir, ".hyperframes", "prepared-assets", "gif");
const gifDownloadDir = join(project.dir, ".hyperframes", "prepared-assets", "downloads");
const heifOutputDir = join(project.dir, ".hyperframes", "prepared-assets", "heif");
const preparedDirs = [gifOutputDir, gifDownloadDir, heifOutputDir];
if (!preparedDirs.every((dir) => isLinkFreeWithinProject(project.dir, dir)))
return injectDeterministicFontFaces(html);
const { html: htmlWithJpegs } = await prepareHeifImageInputs(html, {
projectDir: project.dir,
downloadDir: gifDownloadDir,
@@ -0,0 +1,39 @@
import { describe, expect, it, vi } from "vitest";
// Windows path rules on any host, and a disk that records every look at it.
const probes = vi.hoisted(() => [] as string[]);
vi.mock("node:path", async () => {
const path = await vi.importActual<typeof import("node:path")>("node:path");
return { ...path.win32, default: path.win32 };
});
vi.mock("node:fs", async () => {
const fs = await vi.importActual<typeof import("node:fs")>("node:fs");
const missing = (path: string) => {
probes.push(path);
throw Object.assign(new Error(`ENOENT: ${path}`), { code: "ENOENT" });
};
const realpathSync = Object.assign(missing, { native: missing });
const mocked = { ...fs, realpathSync, lstatSync: missing };
return { ...mocked, default: mocked };
});
const { resolveWithinProject } = await import("./safePath.js");
describe("a request path on another network root", () => {
it.each([
"\\\\attacker.example\\share\\x.html",
"//attacker.example/share/x.html",
"\\\\?\\UNC\\attacker.example\\share\\x.html",
"\\\\.\\pipe\\x",
])("is refused without touching the disk: %s", (path) => {
probes.length = 0;
expect(resolveWithinProject("C:\\project", path)).toBeNull();
expect(probes).toEqual([]);
});
it("does not stop a project that itself lives on a share", () => {
probes.length = 0;
resolveWithinProject("\\\\nas\\films\\project", "scenes\\intro.html");
expect(probes.length).toBeGreaterThan(0);
});
});
+9 -2
View File
@@ -1,4 +1,4 @@
import { resolve, sep, join, dirname, basename, relative, isAbsolute } from "node:path";
import { resolve, sep, join, dirname, basename, relative, isAbsolute, parse } from "node:path";
import { lstatSync, mkdirSync, realpathSync, statSync } from "node:fs";
export function realpath(path: string): string {
@@ -27,6 +27,12 @@ function isMissingPath(path: string): boolean {
}
}
// On Windows even a realpath or lstat of a UNC or device path (\\host\share, \\?\, \\.\) connects to that host.
function namesAnotherNetworkRoot(base: string, target: string): boolean {
const root = parse(target).root;
return /^[\\/]{2}/.test(root) && root.toLowerCase() !== parse(base).root.toLowerCase();
}
/**
* Reject paths that escape the `base` directory — including via symlinks.
*
@@ -50,6 +56,8 @@ function isMissingPath(path: string): boolean {
* from there without a backwards edge.
*/
export function isSafePath(base: string, resolved: string): boolean {
const target = resolve(resolved);
if (namesAnotherNetworkRoot(resolve(base), target)) return false;
let baseReal: string;
try {
baseReal = realpath(resolve(base));
@@ -58,7 +66,6 @@ export function isSafePath(base: string, resolved: string): boolean {
return false;
}
const target = resolve(resolved);
const trailing: string[] = [];
let probe = target;
+9
View File
@@ -6,3 +6,12 @@ export function closeServer(server: Server): Promise<void> {
server.removeAllListeners("request");
return closed;
}
export function isLoopbackHost(host: string | undefined): boolean {
if (!host) return true;
const name = host
.replace(/:\d+$/, "")
.replace(/^\[|\]$/g, "")
.toLowerCase();
return name === "127.0.0.1" || name === "localhost" || name === "::1";
}
+2 -10
View File
@@ -1,6 +1,7 @@
import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
import { readFileSync, realpathSync } from "node:fs";
import { pathToFileURL } from "node:url";
import { isLoopbackHost } from "./pageServer";
import { Inspector } from "./service";
import type { InspectRequest } from "./types";
@@ -28,15 +29,6 @@ function failureOf(error: unknown) {
return { status: message === "no-composition" ? 404 : 400, message };
}
function loopback(host: string | undefined) {
if (!host) return true;
const name = host
.replace(/:\d+$/, "")
.replace(/^\[|\]$/g, "")
.toLowerCase();
return name === "127.0.0.1" || name === "localhost" || name === "::1";
}
function readBody(req: IncomingMessage): Promise<Buffer | "too_large"> {
return new Promise((resolve, reject) => {
const chunks: Buffer[] = [];
@@ -73,7 +65,7 @@ export function createInspectorServer(project: string) {
const inspector = new Inspector(project);
const server = createServer(async (req, res) => {
res.setHeader("Content-Type", "application/json");
if (!loopback(req.headers.host)) {
if (!isLoopbackHost(req.headers.host)) {
send(res, 403, "host_not_allowed");
return;
}
+2 -1
View File
@@ -28,7 +28,7 @@ import {
bundleToSingleHtml,
type BundleScriptProvenance,
} from "../../core/src/compiler/htmlBundler";
import { closeServer } from "./pageServer";
import { closeServer, isLoopbackHost } from "./pageServer";
import { Sources, fingerprint } from "./sources";
import type { InspectRequest, Snippet } from "./types";
import { hyperframesCacheDir } from "../../core/src/cacheDir";
@@ -121,6 +121,7 @@ export class Inspector {
if (fingerprint(this.project) !== digest)
throw new Error("source_changed_during_load: retry against a stable project");
const server = createServer((req, res) => {
if (!isLoopbackHost(req.headers.host)) return void res.writeHead(403).end();
try {
const path = decodeURIComponent(new URL(req.url ?? "/", "http://localhost").pathname);
if (path === "/" || path === "/index.html") {
@@ -0,0 +1,65 @@
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { request } from "node:http";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { expect, it, vi } from "vitest";
import { Inspector } from "../src/service";
const pages = vi.hoisted(() => [] as string[]);
vi.mock("puppeteer-core", () => ({
default: {
launch: async () => ({
close: async () => {},
newPage: async () => ({
setViewport: async () => {},
goto: async (url: string) => {
pages.push(url);
await fetch(url);
},
waitForFunction: async () => {},
evaluate: async () => {},
content: async () => "",
close: async () => {},
}),
}),
},
}));
function statusFor(url: string, host: string): Promise<number> {
return new Promise((resolve, reject) => {
request(url, { headers: { host } }, (res) => {
res.resume();
resolve(res.statusCode ?? 0);
})
.on("error", reject)
.end();
});
}
it("serves the preview page to its own browser and refuses a foreign Host", async () => {
const project = mkdtempSync(join(tmpdir(), "inspect-preview-host-"));
writeFileSync(
join(project, "index.html"),
'<!doctype html><html><head></head><body><main data-composition-id="root" data-duration="1" data-width="320" data-height="180"></main></body></html>',
);
writeFileSync(join(project, "notes.txt"), "project file");
const inspector = new Inspector(project, {
executablePath: "browser-stand-in",
instrument: false,
});
try {
await inspector.withPage(async () => {});
const origin = new URL(pages.at(-1)!).origin;
const port = new URL(origin).port;
expect(await statusFor(`${origin}/`, `127.0.0.1:${port}`)).toBe(200);
expect(await statusFor(`${origin}/notes.txt`, `localhost:${port}`)).toBe(200);
for (const path of ["/", "/__hf-runtime.js", "/notes.txt"]) {
expect(await statusFor(`${origin}${path}`, `attacker.example:${port}`)).toBe(403);
}
} finally {
await inspector.dispose();
rmSync(project, { recursive: true, force: true });
}
});
+13 -4
View File
@@ -38,13 +38,21 @@ async function answerRefusedFrameWithPage(c: Context, next: Next) {
});
}
const fromAnotherSite = (c: Context) => {
const site = c.req.header("sec-fetch-site");
return site === "cross-site" || site === "same-site";
};
async function sandboxPreviewOpenedFromAnotherSite(c: Context, next: Next) {
await next();
c.header("Vary", "Sec-Fetch-Site", { append: true });
const site = c.req.header("sec-fetch-site");
if (site === "cross-site" || site === "same-site") {
c.header("Content-Security-Policy", "sandbox allow-scripts");
}
if (fromAnotherSite(c)) c.header("Content-Security-Policy", "sandbox allow-scripts");
}
async function refuseThumbnailForAnotherSite(c: Context, next: Next) {
if (fromAnotherSite(c))
return c.json({ error: "forbidden: thumbnail requested by another site" }, 403);
return next();
}
function urlHost(url: string): string | undefined {
@@ -70,6 +78,7 @@ export interface StudioApiOptions {
export function createStudioApi(adapter: StudioApiAdapter, options: StudioApiOptions = {}): Hono {
const api = new Hono();
api.use("/projects/:id/preview/*", sandboxPreviewOpenedFromAnotherSite);
api.use("/projects/:id/thumbnail/*", refuseThumbnailForAnotherSite);
// This API is unauthenticated and simple cross-origin POSTs need no
// preflight, so the guard rejects writes the shared predicate refuses.
api.use(async function rejectCrossOriginWrites(c, next) {
@@ -2,7 +2,12 @@ import { readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
import { Buffer } from "node:buffer";
import { createHash } from "node:crypto";
import { join, relative } from "node:path";
import { isProjectRootMissing, isSafePath, mkdirWithinProject } from "./safePath.js";
import {
isLinkFreeWithinProject,
isProjectRootMissing,
isSafePath,
mkdirWithinProject,
} from "./safePath.js";
const DEFAULT_KEEP_PER_FILE = 10;
@@ -37,6 +42,7 @@ export function snapshotBeforeWrite(
const relativePath = relative(projectDir, absPath);
const backupDir = join(projectDir, ".hyperframes", "backup");
if (!isLinkFreeWithinProject(projectDir, backupDir)) return { backupPath: null };
mkdirWithinProject(projectDir, backupDir);
const pathKey = Buffer.from(relativePath, "utf-8").toString("base64url");
@@ -45,7 +51,7 @@ export function snapshotBeforeWrite(
? pathKey
: `sha256~${createHash("sha256").update(relativePath).digest("hex")}`;
const backupPath = nextBackupPath(backupDir, backupKey);
writeFileSync(backupPath, content);
writeFileSync(backupPath, content, { flag: "wx" });
pruneBackups(backupDir, [pathKey, backupKey], options.keepPerFile ?? DEFAULT_KEEP_PER_FILE);
return { backupPath };
} catch (error) {
@@ -1,9 +1,9 @@
import { stampHfIdsInPlace } from "@hyperframes/parsers/hf-ids";
import { createHash } from "node:crypto";
import { closeSync, constants, fstatSync, openSync, readFileSync, writeFileSync } from "node:fs";
import { closeSync, constants, fstatSync, openSync, readFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
import { isInHiddenOrVendorDir, mkdirWithinProject, walkDir } from "./safePath.js";
import { isInHiddenOrVendorDir, mkdirOwnedWithinProject, walkDir } from "./safePath.js";
export const isCompositionSource = (html: string): boolean => /data-composition-id\s*=/.test(html);
@@ -48,8 +48,8 @@ function readStampRecord(recordPath: string): Record<string, string> {
function writeStampRecord(projectDir: string, recordPath: string, next: Record<string, string>) {
try {
mkdirWithinProject(projectDir, dirname(recordPath));
writeFileSync(recordPath, JSON.stringify(next));
mkdirOwnedWithinProject(projectDir, dirname(recordPath));
replaceFileAtomically(recordPath, JSON.stringify(next));
} catch {
// read-only project: the next start parses again
}
@@ -0,0 +1,135 @@
import {
existsSync,
mkdirSync,
mkdtempSync,
readdirSync,
readFileSync,
rmSync,
symlinkSync,
utimesSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import { snapshotBeforeWrite } from "./backupJournal";
import { stampProjectHfIds } from "./hfIdPersist";
import { createPreviewDocumentStore } from "./previewDocumentStore";
import { isLinkFreeWithinProject, mkdirOwnedWithinProject } from "./safePath";
import { projectHistoryId } from "../history/historyId";
import { pruneThumbnailCache } from "../routes/thumbnail";
const dirs: string[] = [];
afterEach(() => {
for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
});
function tempDir(): string {
const dir = mkdtempSync(join(tmpdir(), "hf-owned-folders-"));
dirs.push(dir);
return dir;
}
/** A project and, beside it, a folder of the person's own files that a link in the project points at. */
function projectWithOutsideFolder() {
const root = tempDir();
const project = join(root, "project");
const outside = join(root, "outside");
mkdirSync(project);
mkdirSync(outside);
writeFileSync(join(outside, "notes.txt"), "keep me");
writeFileSync(join(project, "index.html"), '<div data-composition-id="main"><p>Hi</p></div>');
return { project, outside };
}
const listing = (dir: string) => readdirSync(dir).sort();
// Windows needs a privilege to create symlinks.
describe.skipIf(process.platform === "win32")("the tool's own folders inside a project", () => {
it("are made as real folders when nothing is there yet", () => {
const project = tempDir();
mkdirOwnedWithinProject(project, join(project, ".hyperframes", "preview"));
expect(isLinkFreeWithinProject(project, join(project, ".hyperframes", "preview"))).toBe(true);
});
it("are refused when a folder on the way is a link, and nothing is made at its target", () => {
const { project, outside } = projectWithOutsideFolder();
symlinkSync(outside, join(project, ".hyperframes"));
expect(() =>
mkdirOwnedWithinProject(project, join(project, ".hyperframes", "backup")),
).toThrow();
expect(listing(outside)).toEqual(["notes.txt"]);
});
it("still work when the project folder itself is reached through a link", () => {
const { project } = projectWithOutsideFolder();
const linkedProject = join(tempDir(), "linked");
symlinkSync(project, linkedProject);
mkdirOwnedWithinProject(linkedProject, join(linkedProject, ".thumbnails"));
expect(existsSync(join(project, ".thumbnails"))).toBe(true);
});
it("keep the hf-id stamp record from writing through a linked record file", () => {
const { project, outside } = projectWithOutsideFolder();
mkdirSync(join(project, ".hyperframes"));
symlinkSync(join(outside, "notes.txt"), join(project, ".hyperframes", "hf-ids-stamped.json"));
stampProjectHfIds(project);
expect(readFileSync(join(outside, "notes.txt"), "utf-8")).toBe("keep me");
});
it("keep the hf-id stamp record out of a linked .hyperframes folder", () => {
const { project, outside } = projectWithOutsideFolder();
symlinkSync(outside, join(project, ".hyperframes"));
stampProjectHfIds(project);
expect(listing(outside)).toEqual(["notes.txt"]);
});
it("keep a new history id from creating the target of a dangling link", () => {
const { project, outside } = projectWithOutsideFolder();
mkdirSync(join(project, ".hyperframes"));
symlinkSync(join(outside, "planted"), join(project, ".hyperframes", "history-id"));
const id = projectHistoryId(project, tempDir());
expect(listing(outside)).toEqual(["notes.txt"]);
expect(readFileSync(join(project, ".hyperframes", "history-id"), "utf-8")).toBe(`${id}\n`);
});
it("keep edit backups out of a linked backup folder", () => {
const { project, outside } = projectWithOutsideFolder();
mkdirSync(join(project, ".hyperframes"));
symlinkSync(outside, join(project, ".hyperframes", "backup"));
const result = snapshotBeforeWrite(project, join(project, "index.html"));
expect(result.backupPath).toBeNull();
expect(listing(outside)).toEqual(["notes.txt"]);
});
it("keep built preview documents from writing into or emptying a linked preview folder", () => {
const { project, outside } = projectWithOutsideFolder();
mkdirSync(join(project, ".hyperframes"));
symlinkSync(outside, join(project, ".hyperframes", "preview"));
createPreviewDocumentStore(project, "salt").write("key", "<html></html>");
expect(listing(outside)).toEqual(["notes.txt"]);
});
it("keep the thumbnail cache sweep out of a linked .thumbnails folder", () => {
const { project, outside } = projectWithOutsideFolder();
const old = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
utimesSync(join(outside, "notes.txt"), old, old);
symlinkSync(outside, join(project, ".thumbnails"));
pruneThumbnailCache(join(project, ".thumbnails"), new Set());
expect(listing(outside)).toEqual(["notes.txt"]);
});
});
@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
import { readFileSync, readdirSync, rmSync } from "node:fs";
import { join } from "node:path";
import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
import { mkdirWithinProject } from "./safePath.js";
import { mkdirOwnedWithinProject } from "./safePath.js";
import type { PreviewDocumentStore } from "./mediaProxyPreview.js";
/** One built preview document under the project's `.hyperframes/preview`. `salt` names the server build, so new
@@ -21,7 +21,7 @@ export function createPreviewDocumentStore(projectDir: string, salt: string): Pr
},
write(key, html) {
try {
mkdirWithinProject(projectDir, dir);
mkdirOwnedWithinProject(projectDir, dir);
const file = fileFor(key);
replaceFileAtomically(file, html, 0o644);
for (const name of readdirSync(dir)) {
@@ -1,5 +1,13 @@
import { createHash, randomUUID } from "node:crypto";
import { existsSync, mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from "node:fs";
import {
existsSync,
mkdirSync,
mkdtempSync,
rmSync,
symlinkSync,
utimesSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { basename, join } from "node:path";
import { afterEach, describe, expect, it } from "vitest";
@@ -30,6 +38,29 @@ afterEach(() => {
});
describe("cleanupProxyCache", () => {
it.skipIf(process.platform === "win32")(
"removes nothing from the folder a linked .transcode-cache points at",
() => {
const project = mkdtempSync(join(tmpdir(), "hf-proxy-cache-project-"));
const outside = mkdtempSync(join(tmpdir(), "hf-proxy-cache-outside-"));
tempDirs.push(project, outside);
const now = 1_800_000_000_000;
const theirs = proxy(outside, "someone-elses-file");
writeEntry(theirs, 4, now - 31 * 24 * 60 * 60 * 1000);
symlinkSync(outside, join(project, ".transcode-cache"));
const result = cleanupProxyCache(join(project, ".transcode-cache"), {
now,
maxBytes: Number.POSITIVE_INFINITY,
maxIdleMs: 60 * 60 * 1000,
minSweepIntervalMs: 0,
});
expect(result.removed).toEqual([]);
expect(existsSync(theirs)).toBe(true);
},
);
it("removes idle and oldest entries until the cache is within its byte budget", () => {
const cache = cacheDir();
const now = 1_800_000_000_000;
@@ -1,6 +1,7 @@
import { existsSync, readdirSync, statSync, unlinkSync } from "node:fs";
import { extname, join } from "node:path";
import { dirname, extname, join } from "node:path";
import { PROXY_STILL_EXTENSION, PROXY_VARIANT_CONFIG } from "./mediaCodecMap.js";
import { isLinkFreeWithinProject } from "./safePath.js";
const DEFAULT_MAX_BYTES = 10 * 1024 * 1024 * 1024;
const DEFAULT_STALE_TEMP_MS = 60 * 60 * 1000;
@@ -167,7 +168,7 @@ export function cleanupProxyCache(
if (shouldSkipSweep(cacheDir, now, minSweepIntervalMs)) {
return { removed: [], bytesBefore: 0, bytesAfter: 0, skipped: true };
}
if (!existsSync(cacheDir)) {
if (!existsSync(cacheDir) || !isLinkFreeWithinProject(dirname(cacheDir), cacheDir)) {
return { removed: [], bytesBefore: 0, bytesAfter: 0, skipped: false };
}
@@ -1079,6 +1079,34 @@ describe("resolveProxy", () => {
expect(existsSync(live)).toBe(true);
});
it.skipIf(process.platform === "win32")(
"still makes a copy in a .transcode-cache that links outside the project, but never sweeps it",
async () => {
const { spawn, calls } = createSpawnSpy();
const { resolveProxies } = await loadModule(spawn, FFMPEG_PATH);
const projectDir = tmpProject();
const sourcePath = join(projectDir, "clip.mov");
writeFileSync(sourcePath, "source");
const outside = mkdtempSync(join(tmpdir(), "hf-proxy-outside-"));
const stale = join(
outside,
`.tmp-11111111-1111-1111-1111-111111111111-${"a".repeat(64)}.mp4`,
);
writeFileSync(stale, "someone else's file");
const longAgo = new Date(Date.now() - 60 * 60_000);
utimesSync(stale, longAgo, longAgo);
symlinkSync(outside, join(projectDir, ".transcode-cache"));
const batch = resolveProxies(projectDir, [{ sourcePath, variant: "h264" }]);
await answerUntilIdle(calls, (call) => succeed(call));
const [result] = await batch;
expect(result?.status).toBe("fulfilled");
expect(existsSync(stale)).toBe(true);
rmSync(outside, { recursive: true, force: true });
},
);
it("settles each request of a batch on its own when one of them fails", async () => {
const { spawn, calls } = createSpawnSpy();
const { resolveProxies } = await loadModule(spawn, FFMPEG_PATH);
+32 -3
View File
@@ -1,6 +1,10 @@
import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
import { readdirSync, type Dirent } from "node:fs";
import { realpath, resolveWithinProject as resolveInProject } from "@hyperframes/core/safe-path";
import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { lstatSync, readdirSync, type Dirent } from "node:fs";
import {
mkdirWithinProject,
realpath,
resolveWithinProject as resolveInProject,
} from "@hyperframes/core/safe-path";
import { RENDER_TEMP_DIR } from "@hyperframes/core/project-folders";
import { STUDIO_MANUAL_EDITS_PATH } from "./manualEditsRenderScript.js";
import { STUDIO_MOTION_PATH } from "./studioMotionRenderScript.js";
@@ -23,6 +27,11 @@ export function resolveWithinProject(base: string, relativePath: string): string
return resolved && !isPrivateProjectFile(base, resolved) ? resolved : null;
}
/** A path inside the project spelled one way: relative to `base`, `/`-separated, no `.` or `..` segments. */
export function projectRelativePath(base: string, file: string): string {
return relative(resolve(base), resolve(file)).split(sep).join("/");
}
/** The real path; for a path not there (yet, or any more), the nearest existing folder's real path plus the rest. */
export function realFilePath(filePath: string): string {
try {
@@ -75,6 +84,26 @@ function pinResolved(base: string, checked: string | null): string | null {
return escapes ? null : join(base, inside);
}
/** True when no entry from `root` down to `dir` is a link. A file in the way is left for mkdir or readdir to report. */
export function isLinkFreeWithinProject(root: string, dir: string): boolean {
const inside = relative(resolve(root), resolve(dir));
if (inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside)) return false;
let path = resolve(root);
for (const part of inside.split(sep).filter(Boolean)) {
path = join(path, part);
const stat = lstatSync(path, { throwIfNoEntry: false });
if (stat?.isSymbolicLink()) return false;
if (!stat?.isDirectory()) return true;
}
return true;
}
/** `mkdirWithinProject` for the tool's own caches and records: a link on the way would put their files outside the project. */
export function mkdirOwnedWithinProject(root: string, dir: string): void {
if (!isLinkFreeWithinProject(root, dir)) throw new Error(`A link stands in for a folder: ${dir}`);
mkdirWithinProject(root, dir);
}
const IGNORE_DIRS = new Set([
".thumbnails",
".transcode-cache",
@@ -20,6 +20,23 @@ function makeTempProject(files: Record<string, string>): string {
}
describe("buildSubCompositionHtml", () => {
// Windows does not allow a quote in a file name.
it.skipIf(process.platform === "win32")(
"writes the composition's path into its root as attribute text",
() => {
const name = 'a"b&c.html';
const dir = makeTempProject({
"index.html": "<!doctype html><html><head></head><body></body></html>",
[name]: '<div data-composition-id="scene"></div>',
});
const html = buildSubCompositionHtml(dir, name, "/runtime.js") ?? "";
const { document } = parseHTML(html);
const root = document.querySelector("[data-composition-id]");
expect(root?.getAttribute("data-composition-file")).toBe(name);
expect(root?.getAttributeNames()).not.toContain('b&c.html"');
},
);
it("returns null for a composition path that resolves outside the project", () => {
const outside = makeTempProject({ "secret.txt": "outside-secret" });
const dir = makeTempProject({
@@ -240,7 +240,9 @@ function tagRootCompositionFile(bodyHtml: string, compPath: string): string {
if (tagEnd === -1) return bodyHtml;
if (bodyHtml.slice(match.index, tagEnd).includes("data-composition-file")) return bodyHtml;
return (
bodyHtml.slice(0, tagEnd) + ` data-composition-file="${compPath}"` + bodyHtml.slice(tagEnd)
bodyHtml.slice(0, tagEnd) +
` data-composition-file="${escapeAttrValue(compPath)}"` +
bodyHtml.slice(tagEnd)
);
}
@@ -1,8 +1,8 @@
import { randomUUID } from "node:crypto";
import { existsSync, mkdirSync, readFileSync, statSync, utimesSync, writeFileSync } from "node:fs";
import { existsSync, mkdirSync, readFileSync, statSync, utimesSync } from "node:fs";
import { basename, join, resolve } from "node:path";
import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
import { mkdirWithinProject } from "../helpers/safePath.js";
import { mkdirOwnedWithinProject } from "../helpers/safePath.js";
export const ID_PATH = join(".hyperframes", "history-id");
/** The only shape minted here; the id is project content and becomes a path, so nothing else is trusted. */
@@ -70,8 +70,8 @@ export function projectHistoryId(projectDir: string, historyRoot: string): strin
(existsSync(join(historyRoot, id)) && !isRecordedFolder(join(historyRoot, id), folder))
) {
id = randomUUID();
mkdirWithinProject(dir, join(dir, ".hyperframes"));
writeFileSync(join(dir, ID_PATH), `${id}\n`);
mkdirOwnedWithinProject(dir, join(dir, ".hyperframes"));
replaceFileAtomically(join(dir, ID_PATH), `${id}\n`);
}
recordProject(join(historyRoot, id), dir, folder);
return id;
@@ -1852,6 +1852,30 @@ const tl = gsap.timeline({ paused: true });
expect(readFileSync(join(projectDir, "comp.html"), "utf8")).toBe(FROMTO_COMP);
});
it("keeps a saved ease that holds a script end tag inside the script", async () => {
const projectDir = createProjectDir();
writeHtml(projectDir, "comp.html", FROMTO_COMP);
const app = new Hono();
registerFileRoutes(app, createAdapter(projectDir));
const animation = await getFirstAnimation(app, "comp.html");
const scriptsBefore = parseHTML(FROMTO_COMP).document.querySelectorAll("script").length;
const response = await app.request("http://localhost/projects/demo/gsap-mutations/comp.html", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
type: "update-meta",
animationId: animation.id,
updates: { ease: "none</script><script>window.injected = 1</script>" },
}),
});
expect(response.status).toBe(200);
const saved = readFileSync(join(projectDir, "comp.html"), "utf8");
expect(saved).not.toContain("</script><script>window.injected");
expect(parseHTML(saved).document.querySelectorAll("script")).toHaveLength(scriptsBefore);
});
it("update-from-property updates a fromTo start value in place", async () => {
const projectDir = createProjectDir();
writeHtml(projectDir, "comp.html", FROMTO_COMP);
+3 -1
View File
@@ -1070,6 +1070,8 @@ function updateReferences(
// ── GSAP script extraction ──────────────────────────────────────────────────
const escapeScriptEndTags = (code: string) => code.replace(/<\/(script)/gi, "<\\/$1");
/**
* Mint the HTML's ids (so a tween saved on a served id writes that id too), parse it with
* linkedom, locate the inline `<script>` holding GSAP timeline code, and return its text and
@@ -1095,7 +1097,7 @@ function extractGsapScriptBlock(html: string): {
document,
root: clipQueryRoot(script),
replaceScript(newText: string): string {
script.textContent = newText;
script.textContent = escapeScriptEndTags(newText);
return document.toString();
},
};
@@ -0,0 +1,47 @@
// @vitest-environment node
import { afterAll, describe, expect, it } from "vitest";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createStudioApi } from "../createStudioApi";
import type { StudioApiAdapter } from "../types";
const projectDir = mkdtempSync(join(tmpdir(), "hf-preview-comp-path-"));
mkdirSync(join(projectDir, "scenes"));
writeFileSync(join(projectDir, "index.html"), "<html><head></head><body></body></html>");
writeFileSync(
join(projectDir, "scenes", "intro.html"),
'<div data-composition-id="intro" data-width="320" data-height="180"><p>Hi</p></div>',
);
afterAll(() => rmSync(projectDir, { recursive: true, force: true }));
const adapter: StudioApiAdapter = {
listProjects: () => [],
resolveProject: async (id: string) => ({ id, dir: projectDir }),
bundle: async () => null,
lint: async () => ({ findings: [] }),
runtimeUrl: "/api/runtime.js",
rendersDir: () => join(projectDir, "renders"),
startRender: () => ({ id: "job", status: "rendering", progress: 0, outputPath: "/tmp/out.mp4" }),
};
const api = createStudioApi(adapter);
const compositionFile = (html: string) => html.match(/data-composition-file="([^"]*)"/)?.[1];
describe("a sub-composition preview", () => {
it("names its root's file by the composition's own path", async () => {
const res = await api.request("http://localhost/projects/demo/preview/comp/scenes/intro.html");
expect(res.status).toBe(200);
expect(compositionFile(await res.text())).toBe("scenes/intro.html");
});
it("keeps request text that path resolution drops out of the document", async () => {
const res = await api.request(
"http://localhost/projects/demo/preview/comp/x%22%20onmouseover%3D%22alert(1)%2F..%2Fscenes%2Fintro.html",
);
expect(res.status).toBe(200);
const html = await res.text();
expect(compositionFile(html)).toBe("scenes/intro.html");
expect(html).not.toContain("onmouseover");
});
});
+6 -2
View File
@@ -42,6 +42,7 @@ import type { ResolvedProject, StudioApiAdapter } from "../types.js";
import {
isPrivateProjectFile,
isProjectRootMissing,
projectRelativePath,
resolveWithinProject,
} from "../helpers/safePath.js";
import { getMimeType } from "../helpers/mime.js";
@@ -649,14 +650,17 @@ 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 = requestSubPath(c.req.url, "projects/:id/preview/comp");
const compFile = resolveWithinProject(project.dir, compPath);
const compFile = resolveWithinProject(
project.dir,
requestSubPath(c.req.url, "projects/:id/preview/comp"),
);
if (compFile) recordPreviewRead(project.dir, compFile);
// The sub-composition document takes its head from the root.
recordPreviewRead(project.dir, "index.html");
if (!compFile || !existsSync(compFile) || !statSync(compFile).isFile()) {
return c.text("not found", 404);
}
const compPath = projectRelativePath(project.dir, compFile);
// "v2" salts the etag for the hf-id-pinning change below: a client holding
// a pre-pin cached response (preview-only ids, unstamped disk file) must
@@ -0,0 +1,105 @@
// @vitest-environment node
import { afterEach, describe, expect, it, vi } from "vitest";
import { mkdirSync, mkdtempSync, readdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createStudioApi } from "../createStudioApi";
import type { StudioApiAdapter } from "../types";
vi.mock("../helpers/proxyTranscoder.js", async (importOriginal) => ({
...(await importOriginal<typeof import("../helpers/proxyTranscoder.js")>()),
proxyActivityMark: vi.fn(() => "0"),
}));
const dirs: string[] = [];
afterEach(() => {
for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
});
function setup() {
const root = mkdtempSync(join(tmpdir(), "hf-thumbnail-requests-"));
dirs.push(root);
const projectDir = join(root, "project");
mkdirSync(join(projectDir, "scenes"), { recursive: true });
writeFileSync(join(projectDir, "index.html"), '<div data-width="320" data-height="180"></div>');
writeFileSync(
join(projectDir, "scenes", "intro.html"),
'<div data-composition-id="intro"></div>',
);
const captures: { compPath: string; previewUrl: string }[] = [];
const adapter: StudioApiAdapter = {
listProjects: () => [],
resolveProject: async (id: string) => ({ id, dir: projectDir }),
bundle: async () => null,
lint: async () => ({ findings: [] }),
runtimeUrl: "/api/runtime.js",
rendersDir: () => join(projectDir, "renders"),
startRender: () => ({ id: "job", status: "rendering", progress: 0, outputPath: "/tmp/o.mp4" }),
serverOrigin: () => "http://127.0.0.1:3002",
generateThumbnail: async ({ compPath, previewUrl }) => {
captures.push({ compPath, previewUrl });
return Buffer.from("thumb");
},
};
const api = createStudioApi(adapter);
let seek = 0;
const request = (path: string, headers: Record<string, string> = {}) =>
api.request(`http://localhost/projects/demo/thumbnail/${path}?t=${(seek += 0.25)}`, {
headers,
});
return { root, projectDir, request, captures };
}
describe("thumbnail requests", () => {
it.each(["cross-site", "same-site"])("are refused before any capture when %s", async (site) => {
const { request, captures } = setup();
const res = await request("index.html?selector=p", { "sec-fetch-site": site });
expect(res.status).toBe(403);
expect(captures).toEqual([]);
});
it.each([["same-origin"], ["none"], [undefined]])(
"are answered when Sec-Fetch-Site is %s",
async (site) => {
const { request, captures } = setup();
const res = await request("index.html", site ? { "sec-fetch-site": site } : {});
expect(res.status).toBe(200);
expect(captures).toHaveLength(1);
},
);
it("capture the composition under its own path, however the request spells it", async () => {
const { request, captures } = setup();
expect((await request("scenes%2Fintro.html")).status).toBe(200);
expect((await request("x%22%20onload%3D1%2F..%2Fscenes%2Fintro.html")).status).toBe(200);
expect(captures.map((capture) => capture.compPath)).toEqual([
"scenes/intro.html",
"scenes/intro.html",
]);
for (const { previewUrl } of captures) {
expect(previewUrl).toMatch(/\/api\/projects\/demo\/preview\/comp\/scenes\/intro\.html\?/);
}
});
it.skipIf(process.platform === "win32")(
"still answer, but cache nothing, when .thumbnails links outside the project",
async () => {
const { root, projectDir, request, captures } = setup();
const outside = join(root, "outside");
mkdirSync(outside);
symlinkSync(outside, join(projectDir, ".thumbnails"));
const res = await request("index.html");
expect(res.status).toBe(200);
expect(captures).toHaveLength(1);
expect(readdirSync(outside)).toEqual([]);
},
);
});
@@ -12,7 +12,7 @@ import {
unlinkSync,
writeFileSync,
} from "node:fs";
import { join } from "node:path";
import { dirname, join } from "node:path";
import { createHash, randomUUID } from "node:crypto";
import type { StudioApiAdapter } from "../types.js";
import { STUDIO_MANUAL_EDITS_PATH } from "../helpers/manualEditsRenderScript.js";
@@ -25,8 +25,10 @@ import { STUDIO_MOTION_PATH } from "../helpers/studioMotionRenderScript.js";
import { thumbnailGenerationCoordinator } from "./thumbnailGenerationCoordinator.js";
import { requestSubPath } from "../helpers/requestSubPath.js";
import {
isLinkFreeWithinProject,
isProjectRootMissing,
mkdirWithinProject,
projectRelativePath,
resolveWithinProject,
} from "../helpers/safePath.js";
import { proxyActivityMark } from "../helpers/proxyTranscoder.js";
@@ -45,6 +47,7 @@ export function pruneThumbnailCache(
protectedPaths: ReadonlySet<string>,
now = Date.now(),
): void {
if (!isLinkFreeWithinProject(dirname(cacheDir), cacheDir)) return;
let entries: Dirent[];
try {
entries = readdirSync(cacheDir, { withFileTypes: true });
@@ -136,7 +139,8 @@ export function registerThumbnailRoutes(api: Hono, adapter: StudioApiAdapter): v
if (compPath && !compPath.includes(".")) compPath += ".html";
const htmlFile = resolveWithinProject(project.dir, compPath);
const source = htmlFile ? readFileOnce(htmlFile) : "not-a-file";
if (source === "not-a-file") return c.json({ error: "not found" }, 404);
if (!htmlFile || source === "not-a-file") return c.json({ error: "not found" }, 404);
compPath = projectRelativePath(project.dir, htmlFile);
// Keyed on what this composition renders from, so editing one scene leaves the others cached.
const inputSignature = await compositionInputSignature(project.dir, compPath, projectSignature);
@@ -267,6 +271,7 @@ export function registerThumbnailRoutes(api: Hono, adapter: StudioApiAdapter): v
// but never file them under a signature they do not prove.
return generated;
}
if (!isLinkFreeWithinProject(project.dir, cacheDir)) return generated;
mkdirWithinProject(project.dir, cacheDir);
writeThumbnailAtomically(cachePath, generated);
return generated;
@@ -0,0 +1,59 @@
// @vitest-environment jsdom
/**
* Loads the REAL `@mcp-b/global` through Studio's loader, inside a page that is
* framed by another site, and checks that neither of the package's message
* transports answers anyone but Studio's own page.
*/
import { afterAll, expect, it, vi } from "vitest";
vi.mock("../telemetry/client", () => ({ trackEvent: vi.fn() }));
const framer = { postMessage: vi.fn() };
const ownParent = Object.getOwnPropertyDescriptor(window, "parent");
afterAll(() => {
if (ownParent) Object.defineProperty(window, "parent", ownParent);
else Reflect.deleteProperty(window, "parent");
});
const settle = () => new Promise((resolve) => setTimeout(resolve, 20));
it("answers no MCP client but Studio's own page when another site frames Studio", async () => {
Object.defineProperty(window, "parent", { value: framer, configurable: true });
const ownMessages = vi.spyOn(window, "postMessage");
const { loadModelContextPolyfill } = await import("./polyfill");
expect(await loadModelContextPolyfill()).not.toBeNull();
await settle();
expect(framer.postMessage).not.toHaveBeenCalled();
ownMessages.mockClear();
window.dispatchEvent(
new MessageEvent("message", {
data: {
channel: "mcp-default",
type: "mcp",
direction: "client-to-server",
payload: "mcp-check-ready",
},
origin: "https://other.example",
source: window,
}),
);
await settle();
expect(ownMessages).not.toHaveBeenCalled();
window.dispatchEvent(
new MessageEvent("message", {
data: {
channel: "mcp-default",
type: "mcp",
direction: "client-to-server",
payload: "mcp-check-ready",
},
origin: window.location.origin,
source: window,
}),
);
await settle();
expect(ownMessages).toHaveBeenCalled();
});
+15
View File
@@ -12,6 +12,7 @@
* and so it lands in its own chunk rather than the entry bundle.
*/
import type { WebModelContextInitOptions } from "@mcp-b/global";
import { makeStudioDebugLogger } from "../utils/studioDebug";
import { trackEvent } from "../telemetry/client";
import { getModelContext, type ModelContext } from "./types";
@@ -24,8 +25,22 @@ const log = makeStudioDebugLogger("webmcp");
*/
let pending: Promise<ModelContext | null> | null = null;
/**
* Left to its defaults the package answers MCP messages from any origin, and from
* whatever page frames Studio. Only Studio's own page may be a client.
*/
function ownPageOnly(): WebModelContextInitOptions {
return {
transport: {
tabServer: { allowedOrigins: [window.location.origin] },
iframeServer: false,
},
};
}
async function importPolyfill(): Promise<ModelContext | null> {
try {
window.__webModelContextOptions = ownPageOnly();
await import("@mcp-b/global");
const modelContext = getModelContext();
if (!modelContext) {