Files
hyperframes/packages/inspector/src/server.ts
T
Michael WangandClaude Opus 5.5 b8bb491900 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>
2026-11-10 20:26:12 +00:00

149 lines
4.6 KiB
TypeScript

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";
const version = (
JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as {
version: string;
}
).version;
const MAX_BODY = 64_000;
const BROWSER_MISSING = "Set HF_INSPECT_CHROME";
function codeOf(message: string) {
return /^[a-z][a-z0-9_-]*(?=:|$)/.exec(message)?.[0] ?? "invalid_request";
}
function send(res: ServerResponse, status: number, message: string) {
res.writeHead(status).end(JSON.stringify({ error: message, code: codeOf(message) }));
}
function failureOf(error: unknown) {
if (error instanceof TypeError) return { status: 500, message: "internal_error" };
const message = error instanceof Error ? error.message : "internal_error";
if (message.startsWith(BROWSER_MISSING)) return { status: 503, message: "browser_unavailable" };
if (!(error instanceof Error)) return { status: 500, message: "internal_error" };
return { status: message === "no-composition" ? 404 : 400, message };
}
function readBody(req: IncomingMessage): Promise<Buffer | "too_large"> {
return new Promise((resolve, reject) => {
const chunks: Buffer[] = [];
let size = 0;
let settled = false;
const finish = (value: Buffer | "too_large") => {
if (settled) return;
settled = true;
resolve(value);
};
req.on("data", (chunk: Buffer | string) => {
if (settled) return;
const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
size += bytes.length;
if (size > MAX_BODY) {
settled = true;
const done = () => resolve("too_large");
req.on("end", done);
req.on("error", done);
req.resume();
if (req.readableEnded) done();
return;
}
chunks.push(bytes);
});
req.on("end", () => finish(Buffer.concat(chunks)));
req.on("error", (error) => {
if (!settled) reject(error);
});
});
}
export function createInspectorServer(project: string) {
const inspector = new Inspector(project);
const server = createServer(async (req, res) => {
res.setHeader("Content-Type", "application/json");
if (!isLoopbackHost(req.headers.host)) {
send(res, 403, "host_not_allowed");
return;
}
if (req.headers.origin) {
send(res, 403, "browser_origin_not_allowed");
return;
}
if (req.method === "GET" && req.url === "/info") {
res.end(
JSON.stringify({
project: inspector.project,
version,
capability: "inspection",
stats: inspector.stats,
}),
);
return;
}
if (
req.method !== "POST" ||
!["/inspect", "/timeline", "/element-map"].includes(req.url ?? "")
) {
send(res, 404, "not_found");
return;
}
try {
const body = await readBody(req);
if (body === "too_large") {
send(res, 400, "request_too_large");
return;
}
const request: InspectRequest = JSON.parse(body.toString("utf8") || "{}");
if (req.url === "/element-map") res.end(JSON.stringify(await inspector.elementMap()));
else if (req.url === "/timeline") res.end(JSON.stringify(await inspector.timeline(request)));
else res.end(JSON.stringify(await inspector.inspect(request)));
} catch (error) {
const failure = failureOf(error);
send(res, failure.status, failure.message);
}
});
return { inspector, server };
}
function runCli() {
const project = process.argv[2];
if (!project)
throw new Error("Usage: server PROJECT [PORT] (bun src/server.ts, or node dist/server.js)");
const { inspector, server } = createInspectorServer(project);
server.listen(Number(process.argv[3] ?? 0), "127.0.0.1", () => {
const address = server.address();
if (address && typeof address !== "string")
console.log(
JSON.stringify({
url: `http://127.0.0.1:${address.port}`,
project: inspector.project,
}),
);
});
async function close() {
server.close();
await inspector.dispose();
}
process.once("SIGINT", () => {
void close();
});
process.once("SIGTERM", () => {
void close();
});
}
function launchedAsCli(entry: string | undefined) {
if (!entry) return false;
try {
return import.meta.url === pathToFileURL(realpathSync(entry)).href;
} catch {
return false;
}
}
if (launchedAsCli(process.argv[1])) runCli();