fix: render, capture and bundling refuse the app's .hyperframes records (#7828)

Render, capture and the HTML bundler used a narrow private-file rule that
only refused Git data and env files. A composition's script could read the
app's own records under .hyperframes/ (chat history, hand-off, comments,
job log) from the file server, or a data-composition-src could inline one.

Every file server a composition reaches now uses the rule Studio, play and
present already use: Git, env, and .hyperframes/ apart from Studio's own
files and the prepared-assets and requests folders. The rule now matches
Windows spellings too: any case, trailing dots or spaces, backslashes and
stream suffixes.
This commit is contained in:
Michael Wang
2026-11-15 17:10:00 +00:00
committed by GitHub
parent 88ffe087ca
commit 962ddb7c54
12 changed files with 219 additions and 22 deletions
@@ -1,5 +1,12 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync, type ReadStream } from "node:fs";
import {
mkdirSync,
mkdtempSync,
rmSync,
symlinkSync,
writeFileSync,
type ReadStream,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import fs from "node:fs";
@@ -721,3 +728,36 @@ describe("serveStaticProjectHtml private project files", () => {
},
);
});
function writeToolRecords(projectDir: string): void {
mkdirSync(join(projectDir, ".hyperframes", "prepared-assets"), { recursive: true });
for (const name of ["app-history.jsonl", "agent-handoff.json", "comments.jsonl"]) {
writeFileSync(join(projectDir, ".hyperframes", name), "PRIVATE_RECORD");
}
writeFileSync(join(projectDir, ".hyperframes", "prepared-assets", "clip.txt"), "prepared");
symlinkSync(
join(projectDir, ".hyperframes", "app-history.jsonl"),
join(projectDir, "linked-history.json"),
);
}
describe("serveStaticProjectHtml tool records", () => {
it.each([
".hyperframes/app-history.jsonl",
".hyperframes/agent-handoff.json",
".hyperframes/comments.jsonl",
"%2ehyperframes/agent-handoff.json",
".hyperframes%2fcomments.jsonl",
"linked-history.json",
])("answers %s with 404 and still serves prepared assets", async (requestPath) => {
dir = mkdtempSync(join(tmpdir(), "hf-static-records-"));
writeToolRecords(dir);
server = await serveStaticProjectHtml(dir, "<html></html>");
const res = await fetch(`${server.url}${requestPath}`);
expect(res.status).toBe(404);
expect(await res.text()).not.toContain("PRIVATE_RECORD");
const prepared = await fetch(`${server.url}.hyperframes/prepared-assets/clip.txt`);
expect(await prepared.text()).toBe("prepared");
});
});
@@ -2,7 +2,7 @@ import { createServer, request as httpRequest, type Server, type ServerResponse
import { Duplex } from "node:stream";
import { createReadStream, existsSync, readFileSync, statSync } from "node:fs";
import { stripSdrPngColourTags } from "@hyperframes/core/compiler/png-colour-tags";
import { isPrivateFileUnder, isVcsOrSecretPath } from "@hyperframes/core/safe-path";
import { isPrivateFileUnder, isStudioPrivatePath } from "@hyperframes/core/safe-path";
import { isAbsolute, relative, resolve } from "node:path";
import {
PREVIEW_PROXY_BOX_PARAM,
@@ -332,7 +332,7 @@ export async function serveStaticProjectHtml(
const filePath = resolve(root, requestPath);
const rel = relative(root, filePath);
if (rel.startsWith("..") || isAbsolute(rel)) continue; // traversal guard; try next root
if (isPrivateFileUnder(root, filePath, isVcsOrSecretPath)) continue;
if (isPrivateFileUnder(root, filePath, isStudioPrivatePath)) continue;
if (existsSync(filePath)) {
if (proxyRequest) {
void serveProxyRequest(
@@ -235,7 +235,7 @@ describe("bundleToSingleHtml", () => {
}
});
it("refuses the app's records only under the studio private-file policy", async () => {
it("refuses the app's records by default, and inlines them only when asked for git and env files alone", async () => {
const dir = makeTempProject({
"index.html": `<!doctype html><html><head>
<link rel="stylesheet" href=".hyperframes/handoff.css">
@@ -250,7 +250,10 @@ describe("bundleToSingleHtml", () => {
expect(studio).toContain('href=".hyperframes/handoff.css"');
expect(studio).toContain(".prepared { color: blue; }");
const plain = await bundleToSingleHtml(dir);
expect(plain).toContain(".app-record { color: red; }");
expect(plain).not.toContain(".app-record");
expect(plain).toContain(".prepared { color: blue; }");
const narrow = await bundleToSingleHtml(dir, { privateFiles: "vcs-and-secrets" });
expect(narrow).toContain(".app-record { color: red; }");
} finally {
rmSync(dir, { recursive: true, force: true });
}
+2 -2
View File
@@ -928,7 +928,7 @@ export interface BundleOptions {
onRead?: (filePath: string) => void;
/**
* Project files the build never reads; a refused file keeps its authored reference. Git metadata and env files
* always; `"studio"` also refuses the app's records under `.hyperframes/`, as Studio's file routes do.
* always; `"studio"`, the default, also refuses the app's records under `.hyperframes/`, as every file server does.
*/
privateFiles?: BundlePrivateFiles;
}
@@ -1069,7 +1069,7 @@ export function bundleToSingleHtml(projectDir: string, options?: BundleOptions):
};
const scope: BundleReadScope = {
projectDir,
privateFiles: options?.privateFiles ?? "vcs-and-secrets",
privateFiles: options?.privateFiles ?? "studio",
noteRead,
};
return bundleReads.run(scope, () => bundleProject(projectDir, options));
+31
View File
@@ -14,6 +14,7 @@ import {
folderGone,
isProjectRootMissing,
isSafePath,
isStudioPrivatePath,
mkdirWithinProject,
resolveWithinProject,
} from "./safePath.js";
@@ -263,3 +264,33 @@ describe("folderGone", () => {
},
);
});
describe("isStudioPrivatePath", () => {
it.each([
".hyperframes",
".hyperframes/app-history.jsonl",
".hyperframes/agent-handoff.json",
".HYPERFRAMES/comments.jsonl",
".hyperframes./heygen-jobs.jsonl",
".hyperframes /agent-handoff.json",
".hyperframes\\comments.jsonl",
".hyperframes:stream/comments.jsonl",
".git/config",
".env.local",
])("refuses %s", (path) => {
expect(isStudioPrivatePath(path)).toBe(true);
});
it.each([
".hyperframes/prepared-assets/gif/clip.gif",
".HYPERFRAMES/Prepared-Assets./heif/photo.png",
".hyperframes/requests/sketch.png",
".hyperframes/studio-motion.json",
".hyperframes/studio-manual-edits.json",
".hyperframes-pull.json",
"assets/.hyperframes/logo.png",
"assets/logo.png",
])("allows %s", (path) => {
expect(isStudioPrivatePath(path)).toBe(false);
});
});
+5 -5
View File
@@ -126,18 +126,18 @@ export function isVcsOrSecretPath(relPath: string): boolean {
);
}
// `.hyperframes/` holds the desktop app's and the CLI's own records (a hand-off, chat history, read marks): Studio
// reaches none of it, the folder itself included, but its own files and the app's request pictures.
// `.hyperframes/` holds the desktop app's and the CLI's own records (a hand-off, chat history, read marks): no file
// server serves any of it, the folder itself included, but Studio's own files and the assets compositions load.
const STUDIO_FILES = new Set([
".hyperframes/studio-motion.json",
".hyperframes/studio-manual-edits.json",
]);
const STUDIO_FOLDERS = [".hyperframes/prepared-assets", ".hyperframes/requests"];
/** Studio's private files, for a project-relative path with `/` separators: git, env, and the app's records. */
/** Files no composition loads, for a project-relative path in any spelling Windows opens: git, env, app records. */
export function isStudioPrivatePath(relPath: string): boolean {
const path = relPath.toLowerCase();
if (isVcsOrSecretPath(path)) return true;
if (isVcsOrSecretPath(relPath)) return true;
const path = projectPathSegments(relPath).join("/");
return (
(path === ".hyperframes" || path.startsWith(".hyperframes/")) &&
!STUDIO_FILES.has(path) &&
@@ -85,3 +85,51 @@ describe("fileServer private project files", () => {
},
);
});
describe("fileServer tool records", () => {
it.each([
".hyperframes/app-history.jsonl",
".hyperframes/agent-handoff.json",
".hyperframes/comments.jsonl",
"%2ehyperframes/agent-handoff.json",
".hyperframes%2fcomments.jsonl",
"linked-history.json",
])(
"answers %s with 404 from either root and still serves prepared assets",
async (requestPath) => {
const projectDir = fs.mkdtempSync(path.join(tmpdir(), "hf-fileserver-records-"));
const compiledDir = fs.mkdtempSync(path.join(tmpdir(), "hf-fileserver-records-compiled-"));
for (const root of [projectDir, compiledDir]) {
fs.mkdirSync(path.join(root, ".hyperframes", "prepared-assets"), { recursive: true });
for (const name of ["app-history.jsonl", "agent-handoff.json", "comments.jsonl"]) {
fs.writeFileSync(path.join(root, ".hyperframes", name), "PRIVATE_RECORD");
}
}
fs.writeFileSync(
path.join(projectDir, ".hyperframes", "prepared-assets", "clip.txt"),
"prepared",
);
fs.symlinkSync(
path.join(projectDir, ".hyperframes", "app-history.jsonl"),
path.join(projectDir, "linked-history.json"),
);
const server = await createFileServer({
headScripts: [],
bodyScripts: [],
projectDir,
compiledDir,
});
try {
const response = await fetch(`${server.url}/${requestPath}`);
expect(response.status).toBe(404);
expect(await response.text()).not.toContain("PRIVATE_RECORD");
const prepared = await fetch(`${server.url}/.hyperframes/prepared-assets/clip.txt`);
expect(await prepared.text()).toBe("prepared");
} finally {
server.close();
fs.rmSync(projectDir, { recursive: true, force: true });
fs.rmSync(compiledDir, { recursive: true, force: true });
}
},
);
});
+3 -3
View File
@@ -11,7 +11,7 @@ import { serve } from "@hono/node-server";
import { readFileSync, openSync, fstatSync, closeSync, statSync, constants } from "node:fs";
import { join, extname } from "node:path";
import { injectScriptsIntoHtml } from "@hyperframes/core/compiler";
import { isPrivateFileUnder, isVcsOrSecretPath } from "@hyperframes/core/safe-path";
import { isPrivateFileUnder, isStudioPrivatePath } from "@hyperframes/core/safe-path";
import { isWithinProjectRoot } from "@hyperframes/parsers/asset-resolution";
const MIME_TYPES: Record<string, string> = {
@@ -99,11 +99,11 @@ function resolveContainedPaths(
): { projectPath: string; compiledPath: string | null } | null {
const projectPath = join(projectDir, relativePath);
if (!isWithinProjectRoot(projectDir, projectPath)) return null;
if (isPrivateFileUnder(projectDir, projectPath, isVcsOrSecretPath)) return null;
if (isPrivateFileUnder(projectDir, projectPath, isStudioPrivatePath)) return null;
if (!compiledDir) return { projectPath, compiledPath: null };
const compiledPath = join(compiledDir, relativePath);
if (!isWithinProjectRoot(compiledDir, compiledPath)) return null;
if (isPrivateFileUnder(compiledDir, compiledPath, isVcsOrSecretPath)) return null;
if (isPrivateFileUnder(compiledDir, compiledPath, isStudioPrivatePath)) return null;
return { projectPath, compiledPath };
}
@@ -1190,3 +1190,53 @@ describe("createFileServer private project files", () => {
},
);
});
describe("createFileServer tool records", () => {
it.each([
".hyperframes/app-history.jsonl",
".hyperframes/agent-handoff.json",
".hyperframes/comments.jsonl",
"%2ehyperframes/agent-handoff.json",
".hyperframes%2fcomments.jsonl",
"linked-history.json",
])(
"answers %s with 404 from either root and still serves prepared assets",
async (requestPath) => {
const projectDir = mkdtempSync(join(tmpdir(), "hf-fs-records-"));
const compiledDir = mkdtempSync(join(tmpdir(), "hf-fs-records-compiled-"));
try {
writeEmptyIndex(projectDir);
for (const root of [projectDir, compiledDir]) {
mkdirSync(join(root, ".hyperframes", "prepared-assets"), { recursive: true });
for (const name of ["app-history.jsonl", "agent-handoff.json", "comments.jsonl"]) {
writeFileSync(join(root, ".hyperframes", name), "PRIVATE_RECORD");
}
}
writeFileSync(join(projectDir, ".hyperframes", "prepared-assets", "clip.txt"), "prepared");
symlinkSync(
join(projectDir, ".hyperframes", "app-history.jsonl"),
join(projectDir, "linked-history.json"),
);
const server = await createFileServer({
projectDir,
compiledDir,
preHeadScripts: [],
headScripts: [],
bodyScripts: [],
});
try {
const response = await fetch(`${server.url}/${requestPath}`);
expect(response.status).toBe(404);
expect(await response.text()).not.toContain("PRIVATE_RECORD");
const prepared = await fetch(`${server.url}/.hyperframes/prepared-assets/clip.txt`);
expect(await prepared.text()).toBe("prepared");
} finally {
server.close();
}
} finally {
rmSync(projectDir, { recursive: true, force: true });
rmSync(compiledDir, { recursive: true, force: true });
}
},
);
});
+2 -2
View File
@@ -29,7 +29,7 @@ import { Readable } from "node:stream";
import { join, extname, resolve, sep } from "node:path";
import { injectScriptsAtHeadStart, injectScriptsIntoHtml } from "@hyperframes/core/compiler";
import { fpsToNumber, type Fps } from "@hyperframes/core";
import { isPrivateFileUnder, isVcsOrSecretPath } from "@hyperframes/core/safe-path";
import { isPrivateFileUnder, isStudioPrivatePath } from "@hyperframes/core/safe-path";
import { stripSdrPngColourTags } from "@hyperframes/core/compiler/png-colour-tags";
import { openRangeEnd } from "@hyperframes/studio-server/media-range";
import { getVerifiedHyperframeRuntimeSource } from "./hyperframeRuntimeLoader.js";
@@ -837,7 +837,7 @@ export function createFileServer(options: FileServerOptions): Promise<FileServer
const candidate = join(root, relativePath);
const resolveSymlinks = !allowOutsideProjectAssets && root !== compiledDir;
if (!isPathInside(candidate, root, { resolveSymlinks })) continue;
if (isPrivateFileUnder(root, candidate, isVcsOrSecretPath)) continue;
if (isPrivateFileUnder(root, candidate, isStudioPrivatePath)) continue;
const checksLinks = allowOutsideProjectAssets && root !== compiledDir;
if (checksLinks && refusesOutsideLink(root, candidate, warnLeftOut)) continue;
file = openRegularFile(candidate);
@@ -1104,7 +1104,29 @@ describe("detectRenderModeHints", () => {
try {
await expect(
compileForRender(projectDir, join(projectDir, "index.html"), projectDir),
).rejects.toThrow(/compositions\/\.env\.html[\s\S]*git metadata or an env file/);
).rejects.toThrow(
/compositions\/\.env\.html[\s\S]*git metadata, an env file or a private tool record/,
);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
it("compileForRender refuses to inline the app's records under .hyperframes as a data-composition-src", async () => {
const projectDir = makeSubCompProject(
"hf-record-subcomp-",
[{ id: "intro", src: ".hyperframes/agent-handoff.html" }],
{},
);
try {
mkdirSync(join(projectDir, ".hyperframes"));
writeFileSync(
join(projectDir, ".hyperframes", "agent-handoff.html"),
validSubCompHtml("intro", "HANDOFF_SECRET_VALUE"),
);
await expect(
compileForRender(projectDir, join(projectDir, "index.html"), projectDir),
).rejects.toThrow(/\.hyperframes\/agent-handoff\.html[\s\S]*a private tool record/);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
@@ -90,7 +90,7 @@ import {
readTextFile,
resolveCompositionSrc,
} from "@hyperframes/parsers/asset-resolution";
import { isPrivateFileUnder, isVcsOrSecretPath } from "@hyperframes/core/safe-path";
import { isPrivateFileUnder, isStudioPrivatePath } from "@hyperframes/core/safe-path";
import { extractMediaMetadata, extractAudioMetadata } from "../utils/ffprobe.js";
import {
escapesAssetRoot,
@@ -270,9 +270,9 @@ function resolveCompositionFile(
return file !== null && COMPOSITION_FILE.test(file) ? file : null;
}
// Git metadata and env files are never inlined into a render, as the preview bundler refuses them.
// Git metadata, env files and the app's `.hyperframes/` records are never inlined into a render, as preview refuses them.
const isPrivateCompositionFile = (projectDir: string, filePath: string): boolean =>
isPrivateFileUnder(projectDir, filePath, isVcsOrSecretPath);
isPrivateFileUnder(projectDir, filePath, isStudioPrivatePath);
/**
* Recursively walk every `data-composition-src` reference reachable from
@@ -314,7 +314,10 @@ function assertSubCompositionsUsable(
continue;
}
if (isPrivateCompositionFile(projectDir, filePath)) {
problems.push({ srcPath, detail: "it is git metadata or an env file" });
problems.push({
srcPath,
detail: "it is git metadata, an env file or a private tool record",
});
continue;
}
if (!COMPOSITION_FILE.test(filePath)) {