diff --git a/packages/cli/src/server/studioServer.ts b/packages/cli/src/server/studioServer.ts
index 13cf8e828f..9868f839e5 100644
--- a/packages/cli/src/server/studioServer.ts
+++ b/packages/cli/src/server/studioServer.ts
@@ -5,7 +5,7 @@
* providing a CLI-specific adapter for single-project, in-process rendering.
*/
-import { PREVIEW_NONCE_HEADER, previewProof } from "@hyperframes/core/preview-proof";
+import { PREVIEW_NONCE_HEADER, previewProof, previewToken } from "@hyperframes/core/preview-proof";
import type { HttpBindings } from "@hono/node-server";
import { Hono, type Context } from "hono";
import { streamSSE } from "hono/streaming";
@@ -496,6 +496,15 @@ function rewriteWrittenToHostViewport(projectDir: string, written: string[]): vo
}
}
+function previewDocumentStore(projectDir: string): PreviewApiAdapter["previewDocuments"] {
+ const secret = previewToken();
+ if (!secret) return undefined;
+ const salt = createHash("sha256")
+ .update(readFileSync(fileURLToPath(import.meta.url)))
+ .digest("hex");
+ return createPreviewDocumentStore(projectDir, salt, secret);
+}
+
function createStateFolderBeforeWatching(projectDir: string): void {
recordFolder(projectDir, "");
}
@@ -581,13 +590,8 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
listProjects: () => [project],
- // Salted with the running CLI file, so an upgraded CLI never serves an older build's document.
- previewDocuments: createPreviewDocumentStore(
- projectDir,
- createHash("sha256")
- .update(readFileSync(fileURLToPath(import.meta.url)))
- .digest("hex"),
- ),
+ // Salted with the running CLI file; keyed with this user's preview token, so a shipped document is never served.
+ previewDocuments: previewDocumentStore(projectDir),
resolveProject: (id: string) => (id === projectId ? project : null),
diff --git a/packages/studio-server/src/helpers/ownedFolders.test.ts b/packages/studio-server/src/helpers/ownedFolders.test.ts
index a21b8438cb..c77afc7de3 100644
--- a/packages/studio-server/src/helpers/ownedFolders.test.ts
+++ b/packages/studio-server/src/helpers/ownedFolders.test.ts
@@ -117,7 +117,7 @@ describe.skipIf(process.platform === "win32")("the tool's own folders inside a p
mkdirSync(join(project, ".hyperframes"));
symlinkSync(outside, join(project, ".hyperframes", "preview"));
- createPreviewDocumentStore(project, "salt").write("key", "");
+ createPreviewDocumentStore(project, "salt", "secret").write("key", "");
expect(listing(outside)).toEqual(["notes.txt"]);
});
diff --git a/packages/studio-server/src/helpers/previewDocumentStore.test.ts b/packages/studio-server/src/helpers/previewDocumentStore.test.ts
index f6f6b51739..b20683c9f2 100644
--- a/packages/studio-server/src/helpers/previewDocumentStore.test.ts
+++ b/packages/studio-server/src/helpers/previewDocumentStore.test.ts
@@ -1,4 +1,12 @@
-import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import {
+ existsSync,
+ mkdtempSync,
+ readdirSync,
+ renameSync,
+ rmSync,
+ symlinkSync,
+ writeFileSync,
+} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, expect, it } from "vitest";
@@ -9,19 +17,79 @@ afterEach(() => {
for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
});
+function tempDir(): string {
+ const dir = mkdtempSync(join(tmpdir(), "hf-preview-store-"));
+ dirs.push(dir);
+ return dir;
+}
+
+/** The one file a write left in the store, so a test can replace it the way a shipped project would. */
+function storedFile(projectDir: string): string {
+ const dir = join(projectDir, ".hyperframes", "preview");
+ const [name] = readdirSync(dir);
+ if (!name) throw new Error("nothing stored");
+ return join(dir, name);
+}
+
it("stores a built document inside the project", () => {
- const projectDir = mkdtempSync(join(tmpdir(), "hf-preview-store-"));
- dirs.push(projectDir);
- const store = createPreviewDocumentStore(projectDir, "salt");
+ const projectDir = tempDir();
+ const store = createPreviewDocumentStore(projectDir, "salt", "secret");
store.write("key", "");
expect(store.read("key")).toBe("");
});
it("does not recreate a project folder renamed away while its preview is open", () => {
- const parent = mkdtempSync(join(tmpdir(), "hf-preview-store-"));
- dirs.push(parent);
- const projectDir = join(parent, "film");
- const store = createPreviewDocumentStore(projectDir, "salt");
+ const projectDir = join(tempDir(), "film");
+ const store = createPreviewDocumentStore(projectDir, "salt", "secret");
store.write("key", "");
expect(existsSync(projectDir)).toBe(false);
});
+
+it("never serves a document written under another user's secret", () => {
+ const projectDir = tempDir();
+ createPreviewDocumentStore(projectDir, "salt", "the author's secret").write(
+ "key",
+ "
shipped
",
+ );
+ expect(createPreviewDocumentStore(projectDir, "salt", "secret").read("key")).toBeNull();
+});
+
+it("never serves a document the project shipped at a store name", () => {
+ const projectDir = tempDir();
+ const store = createPreviewDocumentStore(projectDir, "salt", "secret");
+ store.write("key", "");
+ writeFileSync(storedFile(projectDir), `${"0".repeat(64)}\nshipped
`);
+ expect(store.read("key")).toBeNull();
+});
+
+it.skipIf(process.platform === "win32")("never reads through a link at a store name", () => {
+ const projectDir = tempDir();
+ const outside = join(tempDir(), "document.html");
+ const store = createPreviewDocumentStore(projectDir, "salt", "secret");
+ store.write("key", "");
+ // The outside file is a valid document, so only the link check can refuse it.
+ const file = storedFile(projectDir);
+ renameSync(file, outside);
+ symlinkSync(outside, file);
+ expect(store.read("key")).toBeNull();
+});
+
+it.skipIf(process.platform === "win32")("never reads through a linked preview folder", () => {
+ const projectDir = tempDir();
+ const elsewhere = tempDir();
+ const store = createPreviewDocumentStore(projectDir, "salt", "secret");
+ store.write("key", "");
+ // The moved folder still holds a valid document, so only the link check can refuse it.
+ const preview = join(projectDir, ".hyperframes", "preview");
+ renameSync(preview, join(elsewhere, "preview"));
+ symlinkSync(join(elsewhere, "preview"), preview);
+ expect(store.read("key")).toBeNull();
+});
+
+it("keeps nothing without a secret", () => {
+ const projectDir = tempDir();
+ const store = createPreviewDocumentStore(projectDir, "salt", "");
+ store.write("key", "");
+ expect(store.read("key")).toBeNull();
+ expect(existsSync(join(projectDir, ".hyperframes"))).toBe(false);
+});
diff --git a/packages/studio-server/src/helpers/previewDocumentStore.ts b/packages/studio-server/src/helpers/previewDocumentStore.ts
index 2ada04e5bc..7449e87370 100644
--- a/packages/studio-server/src/helpers/previewDocumentStore.ts
+++ b/packages/studio-server/src/helpers/previewDocumentStore.ts
@@ -1,29 +1,42 @@
-import { createHash } from "node:crypto";
-import { readFileSync, readdirSync, rmSync } from "node:fs";
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { readdirSync, rmSync } from "node:fs";
import { join } from "node:path";
import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
-import { mkdirOwnedWithinProject } from "./safePath.js";
+import { mkdirOwnedWithinProject, readProjectCacheFile } 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
- * code never reads a document an older build wrote. A failed read or write only costs a rebuild. */
-export function createPreviewDocumentStore(projectDir: string, salt: string): PreviewDocumentStore {
+const MAX_DOCUMENT_BYTES = 256 * 1024 * 1024;
+const MAC_HEX_LENGTH = 64;
+
+/** One built preview document under the project's `.hyperframes/preview`. `salt` names the server build; the
+ * user's private `secret` signs each document, so one the project shipped is never served. A miss costs a rebuild. */
+export function createPreviewDocumentStore(
+ projectDir: string,
+ salt: string,
+ secret: string,
+): PreviewDocumentStore {
+ if (!secret) return { read: () => null, write: () => {} };
const dir = join(projectDir, ".hyperframes", "preview");
const fileFor = (key: string) =>
join(dir, `${createHash("sha256").update(`${salt}\n${key}`).digest("hex").slice(0, 32)}.html`);
+ const macFor = (key: string, html: string) =>
+ createHmac("sha256", secret)
+ .update(`preview-document\n${salt}\n${key}\n`)
+ .update(html)
+ .digest("hex");
return {
read(key) {
- try {
- return readFileSync(fileFor(key), "utf-8");
- } catch {
- return null;
- }
+ const stored = readProjectCacheFile(projectDir, fileFor(key), MAX_DOCUMENT_BYTES);
+ if (!stored || stored.length <= MAC_HEX_LENGTH) return null;
+ const html = stored.subarray(MAC_HEX_LENGTH + 1).toString("utf-8");
+ const mac = stored.subarray(0, MAC_HEX_LENGTH);
+ return timingSafeEqual(mac, Buffer.from(macFor(key, html))) ? html : null;
},
write(key, html) {
try {
mkdirOwnedWithinProject(projectDir, dir);
const file = fileFor(key);
- replaceFileAtomically(file, html, 0o644);
+ replaceFileAtomically(file, `${macFor(key, html)}\n${html}`, 0o644);
for (const name of readdirSync(dir)) {
if (join(dir, name) !== file) rmSync(join(dir, name), { force: true });
}
diff --git a/packages/studio-server/src/helpers/projectCacheFile.test.ts b/packages/studio-server/src/helpers/projectCacheFile.test.ts
new file mode 100644
index 0000000000..04a4de752e
--- /dev/null
+++ b/packages/studio-server/src/helpers/projectCacheFile.test.ts
@@ -0,0 +1,129 @@
+import {
+ linkSync,
+ lstatSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ rmSync,
+ symlinkSync,
+ writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { readCopyIndex, writeCopyIndex } from "./proxyCacheKey";
+import { isProjectCacheFile, readProjectCacheFile } from "./safePath";
+
+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-cache-file-"));
+ dirs.push(dir);
+ return dir;
+}
+
+const COPY = `${"a".repeat(64)}.mp4`;
+
+describe("readProjectCacheFile", () => {
+ it("reads a plain file in a plain folder", () => {
+ const project = tempDir();
+ mkdirSync(join(project, ".cache"));
+ writeFileSync(join(project, ".cache", "entry"), "data");
+ expect(readProjectCacheFile(project, join(project, ".cache", "entry"), 64)?.toString()).toBe(
+ "data",
+ );
+ expect(isProjectCacheFile(project, join(project, ".cache", "entry"))).toBe(true);
+ });
+
+ it("is a miss for a file over the size limit", () => {
+ const project = tempDir();
+ writeFileSync(join(project, "entry"), "data");
+ expect(readProjectCacheFile(project, join(project, "entry"), 3)).toBeNull();
+ });
+
+ it("is a miss for a folder at the entry", () => {
+ const project = tempDir();
+ mkdirSync(join(project, "entry"));
+ expect(readProjectCacheFile(project, join(project, "entry"), 64)).toBeNull();
+ expect(isProjectCacheFile(project, join(project, "entry"))).toBe(false);
+ });
+
+ describe.skipIf(process.platform === "win32")("links", () => {
+ it("is a miss for a link at the entry", () => {
+ const project = tempDir();
+ const secret = join(tempDir(), "id_rsa");
+ writeFileSync(secret, "PRIVATE KEY");
+ symlinkSync(secret, join(project, "entry"));
+ expect(readProjectCacheFile(project, join(project, "entry"), 64)).toBeNull();
+ expect(isProjectCacheFile(project, join(project, "entry"))).toBe(false);
+ });
+
+ it("is a miss for a hard link to a file outside the project", () => {
+ const project = tempDir();
+ const secret = join(tempDir(), "id_rsa");
+ writeFileSync(secret, "PRIVATE KEY");
+ linkSync(secret, join(project, "entry"));
+ expect(readProjectCacheFile(project, join(project, "entry"), 64)).toBeNull();
+ expect(isProjectCacheFile(project, join(project, "entry"))).toBe(false);
+ });
+
+ it("is a miss for a plain file under a linked folder", () => {
+ const project = tempDir();
+ const elsewhere = tempDir();
+ writeFileSync(join(elsewhere, "entry"), "outside");
+ symlinkSync(elsewhere, join(project, ".cache"));
+ expect(readProjectCacheFile(project, join(project, ".cache", "entry"), 64)).toBeNull();
+ expect(isProjectCacheFile(project, join(project, ".cache", "entry"))).toBe(false);
+ });
+ });
+});
+
+describe("readCopyIndex", () => {
+ it("names a plain copy in the same folder", () => {
+ const project = tempDir();
+ const cache = join(project, ".transcode-cache");
+ mkdirSync(cache);
+ writeFileSync(join(cache, COPY), "video");
+ writeCopyIndex(join(cache, ".fast-x"), join(cache, COPY));
+ expect(readCopyIndex(project, join(cache, ".fast-x"))).toBe(join(cache, COPY));
+ });
+
+ describe.skipIf(process.platform === "win32")("links", () => {
+ it("is a miss when the copy it names is a link", () => {
+ const project = tempDir();
+ const cache = join(project, ".transcode-cache");
+ mkdirSync(cache);
+ const secret = join(tempDir(), "id_rsa");
+ writeFileSync(secret, "PRIVATE KEY");
+ symlinkSync(secret, join(cache, COPY));
+ writeCopyIndex(join(cache, ".fast-x"), join(cache, COPY));
+ expect(readCopyIndex(project, join(cache, ".fast-x"))).toBeNull();
+ });
+
+ it("writes an index in place of a link at its name, leaving the link's target as it was", () => {
+ const project = tempDir();
+ const cache = join(project, ".transcode-cache");
+ mkdirSync(cache);
+ const outside = join(tempDir(), "notes.txt");
+ writeFileSync(outside, "mine");
+ symlinkSync(outside, join(cache, ".fast-x"));
+ writeCopyIndex(join(cache, ".fast-x"), join(cache, COPY));
+ expect(readFileSync(outside, "utf8")).toBe("mine");
+ expect(lstatSync(join(cache, ".fast-x")).isSymbolicLink()).toBe(false);
+ });
+
+ it("is a miss when the index itself is a link", () => {
+ const project = tempDir();
+ const cache = join(project, ".transcode-cache");
+ mkdirSync(cache);
+ writeFileSync(join(cache, COPY), "video");
+ const outsideIndex = join(tempDir(), "index");
+ writeFileSync(outsideIndex, COPY);
+ symlinkSync(outsideIndex, join(cache, ".fast-x"));
+ expect(readCopyIndex(project, join(cache, ".fast-x"))).toBeNull();
+ });
+ });
+});
diff --git a/packages/studio-server/src/helpers/proxyCacheKey.ts b/packages/studio-server/src/helpers/proxyCacheKey.ts
index 80d9262640..8d2346976a 100644
--- a/packages/studio-server/src/helpers/proxyCacheKey.ts
+++ b/packages/studio-server/src/helpers/proxyCacheKey.ts
@@ -1,16 +1,9 @@
import { createHash } from "node:crypto";
-import {
- closeSync,
- createReadStream,
- existsSync,
- fstatSync,
- openSync,
- readFileSync,
- statSync,
- writeFileSync,
-} from "node:fs";
+import { closeSync, createReadStream, fstatSync, openSync, readFileSync, statSync } from "node:fs";
import { basename, dirname, extname, join } from "node:path";
import { formatPreviewProxyBox, type PreviewProxyBox } from "@hyperframes/core";
+import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
+import { isProjectCacheFile, readProjectCacheFile } from "./safePath.js";
const SMALL_FILE_BYTES = 16 * 1024 * 1024;
const COPY_NAME = /^[0-9a-f]{64}\.(?:mp4|webm)$/;
@@ -83,17 +76,13 @@ export function contentIndexPath(cacheDir: string, contentKey: string): string {
return join(cacheDir, `.content-${contentKey}`);
}
-/** The copy an index file names, when it is a copy in the same folder and still there. */
-export function readCopyIndex(indexPath: string): string | null {
- try {
- const name = readFileSync(indexPath, "utf8").trim();
- const target = join(dirname(indexPath), name);
- return COPY_NAME.test(name) && existsSync(target) ? target : null;
- } catch {
- return null;
- }
+/** The copy an index file names, when it is a plain file in the same folder; a link at either is a miss. */
+export function readCopyIndex(projectDir: string, indexPath: string): string | null {
+ const name = readProjectCacheFile(projectDir, indexPath, 256)?.toString("utf8").trim() ?? "";
+ const target = join(dirname(indexPath), name);
+ return COPY_NAME.test(name) && isProjectCacheFile(projectDir, target) ? target : null;
}
export function writeCopyIndex(indexPath: string, copyPath: string): void {
- writeFileSync(indexPath, basename(copyPath));
+ replaceFileAtomically(indexPath, basename(copyPath), 0o644);
}
diff --git a/packages/studio-server/src/helpers/proxyLock.test.ts b/packages/studio-server/src/helpers/proxyLock.test.ts
index ebb1a124cf..4915c958bd 100644
--- a/packages/studio-server/src/helpers/proxyLock.test.ts
+++ b/packages/studio-server/src/helpers/proxyLock.test.ts
@@ -32,7 +32,7 @@ describe("acquireCopyLock", () => {
writeFileSync(join(dir, ".tmp-1234-.part-c-0.mp4"), "x");
const abort = new AbortController();
- const waiting = acquireCopyLock(cachePath, abort.signal, 60_000);
+ const waiting = acquireCopyLock(cachePath, () => false, abort.signal, 60_000);
setTimeout(() => abort.abort(new Error("stopped")), 400);
await expect(within(waiting, 3_000)).rejects.toThrow("stopped");
@@ -41,11 +41,14 @@ describe("acquireCopyLock", () => {
it("gives up on a live owner that has made no progress for the stall window, naming the copy", async () => {
const cachePath = staleLock("a.mp4");
- const waiting = acquireCopyLock(cachePath, new AbortController().signal, 300);
+ const waiting = acquireCopyLock(cachePath, () => false, new AbortController().signal, 300);
await expect(within(waiting, 3_000)).rejects.toThrow(CopyLockStalledError);
await expect(
- within(acquireCopyLock(cachePath, new AbortController().signal, 300), 3_000),
+ within(
+ acquireCopyLock(cachePath, () => false, new AbortController().signal, 300),
+ 3_000,
+ ),
).rejects.toThrow(/a\.mp4.*no progress/);
});
@@ -54,7 +57,7 @@ describe("acquireCopyLock", () => {
writeFileSync(join(dir, ".tmp-1234-b.mp4"), "x");
const abort = new AbortController();
- const waiting = acquireCopyLock(cachePath, abort.signal, 60_000);
+ const waiting = acquireCopyLock(cachePath, () => false, abort.signal, 60_000);
setTimeout(() => abort.abort(new Error("stopped")), 400);
await expect(within(waiting, 3_000)).rejects.toThrow("stopped");
diff --git a/packages/studio-server/src/helpers/proxyLock.ts b/packages/studio-server/src/helpers/proxyLock.ts
index b357b1c3bd..cb86013c01 100644
--- a/packages/studio-server/src/helpers/proxyLock.ts
+++ b/packages/studio-server/src/helpers/proxyLock.ts
@@ -1,6 +1,5 @@
import {
closeSync,
- existsSync,
openSync,
readdirSync,
readFileSync,
@@ -73,21 +72,22 @@ function pause(ms: number, signal: AbortSignal): Promise {
});
}
-/** The right to make the copy at `cachePath`; null once another process finished it; throws on a stalled live owner. */
+/** The right to make the copy at `cachePath`; null once `copyMade` holds; throws on a stalled live owner. */
export async function acquireCopyLock(
cachePath: string,
+ copyMade: (path: string) => boolean,
signal: AbortSignal,
stallMs: number,
): Promise<(() => void) | null> {
const lockPath = lockPathFor(cachePath);
for (;;) {
signal.throwIfAborted();
- if (existsSync(cachePath)) return null;
+ if (copyMade(cachePath)) return null;
try {
const fd = openSync(lockPath, "wx");
writeSync(fd, String(process.pid));
closeSync(fd);
- if (!existsSync(cachePath)) return () => rmSync(lockPath, { force: true });
+ if (!copyMade(cachePath)) return () => rmSync(lockPath, { force: true });
rmSync(lockPath, { force: true });
return null;
} catch (err) {
diff --git a/packages/studio-server/src/helpers/proxyTranscoder.test.ts b/packages/studio-server/src/helpers/proxyTranscoder.test.ts
index ac35bae281..a175c96d12 100644
--- a/packages/studio-server/src/helpers/proxyTranscoder.test.ts
+++ b/packages/studio-server/src/helpers/proxyTranscoder.test.ts
@@ -597,6 +597,31 @@ describe("resolveProxy", () => {
expect(calls).toHaveLength(0);
});
+ it.skipIf(process.platform === "win32")(
+ "makes the copy again when a link stands at its name, and never returns the link's target",
+ async () => {
+ const { spawn, calls } = createSpawnSpy();
+ const { resolveProxy, getProxyCachePath } = await loadModule(spawn, FFMPEG_PATH);
+ const projectDir = tmpProject();
+ const sourcePath = join(projectDir, "video.mov");
+ writeFileSync(sourcePath, "source-bytes");
+ const outside = join(tmpProject(), "id_rsa");
+ writeFileSync(outside, "PRIVATE KEY");
+ const cachePath = getProxyCachePath(projectDir, sourcePath);
+ mkdirSync(dirname(cachePath), { recursive: true });
+ symlinkSync(outside, cachePath);
+
+ const resultPromise = resolveProxy(projectDir, sourcePath);
+ await flush();
+ expect(calls).toHaveLength(1);
+ succeed(calls[0]!);
+ const result = await resultPromise;
+
+ expect(readFileSync(result, "utf8")).toBe("fake-h264-bytes");
+ expect(readFileSync(outside, "utf8")).toBe("PRIVATE KEY");
+ },
+ );
+
it("tone-maps HDR input before emitting browser-safe BT.709", async () => {
const { spawn, calls } = createSpawnSpy();
const { resolveProxy } = await loadModule(spawn, FFMPEG_PATH, true);
diff --git a/packages/studio-server/src/helpers/proxyTranscoder.ts b/packages/studio-server/src/helpers/proxyTranscoder.ts
index dbb5a5a5bd..99cf2904c0 100644
--- a/packages/studio-server/src/helpers/proxyTranscoder.ts
+++ b/packages/studio-server/src/helpers/proxyTranscoder.ts
@@ -29,7 +29,7 @@ import {
} from "./proxyCacheKey.js";
import { acquireCopyLock, CopyLockStalledError } from "./proxyLock.js";
import { PROXY_STILL_EXTENSION, PROXY_VARIANT_CONFIG, type ProxyVariant } from "./mediaCodecMap.js";
-import { mkdirWithinProject, realpath, realProjectRoot } from "./safePath.js";
+import { isProjectCacheFile, mkdirWithinProject, realpath, realProjectRoot } from "./safePath.js";
/**
* Transcodes browser-hostile local video sources (HEVC, ProRes, ...) into a
@@ -204,7 +204,9 @@ function getCanonicalProxyCachePath(
CACHE_DIR_NAME,
`${key}${PROXY_VARIANT_CONFIG[variant].extension}`,
);
- return existsSync(made) ? made : (readCopyIndex(fastIndexPath(made)) ?? made);
+ return isProjectCacheFile(source.projectDir, made)
+ ? made
+ : (readCopyIndex(source.projectDir, fastIndexPath(made)) ?? made);
}
/**
@@ -569,10 +571,12 @@ function createPieceGate(size: number): PieceGate {
};
}
+type ChunkFiles = { projectDir: string; prefix: string };
+
/** Copies a long source in pieces that stay in the cache, so a stopped copy continues from the first missing one. */
async function encodeInChunks(
ranges: ChunkRange[],
- chunkPrefix: string,
+ chunks: ChunkFiles,
tempPath: string,
encode: EncodeFn,
concat: (listPath: string, target: string) => Promise,
@@ -581,8 +585,9 @@ async function encodeInChunks(
onDone: (doneSeconds: number) => void = () => {},
): Promise {
const extension = extname(tempPath);
- const pieces = ranges.map((_, index) => `${chunkPrefix}${index}${extension}`);
- const pending = ranges.flatMap((_, index) => (existsSync(pieces[index]!) ? [] : [index]));
+ const pieces = ranges.map((_, index) => `${chunks.prefix}${index}${extension}`);
+ const madeAsPlainFile = (piece: string) => isProjectCacheFile(chunks.projectDir, piece);
+ const pending = ranges.flatMap((_, index) => (madeAsPlainFile(pieces[index]!) ? [] : [index]));
let doneSeconds = 0;
for (const [index, range] of ranges.entries()) {
if (!pending.includes(index)) doneSeconds += range.lengthSeconds;
@@ -732,7 +737,7 @@ async function buildVideoFilter(
async function runFfmpeg(
sourcePath: string,
outputPath: string,
- chunkPrefix: string,
+ chunks: ChunkFiles,
variant: ProxyVariant,
box: PreviewProxyBox | undefined,
limitSeconds: number | undefined,
@@ -796,7 +801,7 @@ async function runFfmpeg(
}
await encodeInChunks(
ranges,
- chunkPrefix,
+ chunks,
outputPath,
encode,
(listPath, target) =>
@@ -932,7 +937,7 @@ async function transcodeToCache(
await acquireSlot(job);
try {
// Another caller may have finished (or a pre-warm beat us) while queued.
- if (existsSync(cachePath)) return cachePath;
+ if (isProjectCacheFile(projectDir, cachePath)) return cachePath;
const cacheDir = dirname(cachePath);
mkdirWithinProject(projectDir, cacheDir);
@@ -946,13 +951,15 @@ async function transcodeToCache(
job.abandoned.signal,
),
);
- const sameContent = readCopyIndex(contentIndex);
+ const sameContent = readCopyIndex(projectDir, contentIndex);
if (sameContent) {
writeCopyIndex(fastIndexPath(cachePath), sameContent);
return sameContent;
}
+ const copyMade = (path: string) => isProjectCacheFile(projectDir, path);
const release = await acquireCopyLock(
cachePath,
+ copyMade,
job.abandoned.signal,
TRANSCODE_STALL_MS,
).catch((error: unknown) => {
@@ -960,17 +967,20 @@ async function transcodeToCache(
? new ProxyTranscodeError(error.message, null, "")
: error;
});
- if (!release) return cachePath;
+ if (!release) {
+ if (copyMade(cachePath)) return cachePath;
+ throw new ProxyTranscodeError("the copy is not a plain file in the cache", null, "");
+ }
const tempPath = join(cacheDir, `.tmp-${randomUUID()}-${basename(cachePath)}`);
try {
- const chunkPrefix = join(
- cacheDir,
- `${CHUNK_PREFIX}${basename(cachePath, extname(cachePath))}-`,
- );
+ const chunks = {
+ projectDir,
+ prefix: join(cacheDir, `${CHUNK_PREFIX}${basename(cachePath, extname(cachePath))}-`),
+ };
await runFfmpeg(
absoluteSourcePath,
tempPath,
- chunkPrefix,
+ chunks,
variant,
box,
limitSeconds,
@@ -1048,7 +1058,7 @@ export async function resolveProxy(
options.signal?.throwIfAborted();
const source = canonicalizeProxySource(projectDir, absoluteSourcePath);
const cachePath = getCanonicalProxyCachePath(source, variant, box, options.limitSeconds);
- if (existsSync(cachePath)) {
+ if (isProjectCacheFile(source.projectDir, cachePath)) {
markCacheEntryUsed(cachePath);
maintainProxyCache(dirname(cachePath));
return cachePath;
@@ -1178,7 +1188,7 @@ export function resolveStill(
const at = Math.max(0, Math.round(atSeconds * 10) / 10);
const key = fastCopyKey(source.sourcePath, PROXY_PARAMS_VERSION, `still@${at}`, box);
const cachePath = join(source.projectDir, CACHE_DIR_NAME, `${key}${PROXY_STILL_EXTENSION}`);
- if (existsSync(cachePath)) {
+ if (isProjectCacheFile(source.projectDir, cachePath)) {
markCacheEntryUsed(cachePath);
maintainProxyCache(dirname(cachePath), undefined, cachePath);
return Promise.resolve(cachePath);
diff --git a/packages/studio-server/src/helpers/safePath.ts b/packages/studio-server/src/helpers/safePath.ts
index 1b1983edf1..0b52850a44 100644
--- a/packages/studio-server/src/helpers/safePath.ts
+++ b/packages/studio-server/src/helpers/safePath.ts
@@ -1,5 +1,16 @@
import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { lstatSync, readdirSync, readFileSync, statSync, type Dirent } from "node:fs";
+import {
+ closeSync,
+ constants,
+ fstatSync,
+ lstatSync,
+ openSync,
+ readdirSync,
+ readFileSync,
+ statSync,
+ type Dirent,
+ type Stats,
+} from "node:fs";
import {
isStudioPrivatePath,
mkdirWithinProject,
@@ -213,6 +224,47 @@ export function isLinkFreeWithinProject(root: string, dir: string): boolean {
return true;
}
+/** A file Studio keeps under the project, such as a cache entry: a plain file, reached with no link from `root` down. */
+export function isProjectCacheFile(root: string, file: string): boolean {
+ if (!isLinkFreeWithinProject(root, dirname(file))) return false;
+ const stat = lstatSync(file, { throwIfNoEntry: false });
+ return stat !== undefined && isPlainFileWithOneName(stat);
+}
+
+const isPlainFileWithOneName = (stat: Stats) => stat.isFile() && stat.nlink === 1;
+
+const NO_FOLLOW_READ =
+ constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
+
+const sameFile = (a: Stats | undefined, b: Stats) =>
+ a !== undefined && !a.isSymbolicLink() && a.dev === b.dev && a.ino === b.ino;
+
+/** `isProjectCacheFile`'s bytes, opened without following a link, or null; a hard link or one over `maxBytes` is a miss too. */
+export function readProjectCacheFile(root: string, file: string, maxBytes: number): Buffer | null {
+ if (!isLinkFreeWithinProject(root, dirname(file))) return null;
+ let fd: number;
+ try {
+ fd = openSync(file, NO_FOLLOW_READ);
+ } catch {
+ return null;
+ }
+ try {
+ const stat = fstatSync(fd);
+ if (!isPlainFileWithOneName(stat) || stat.size > maxBytes) return null;
+ // Without O_NOFOLLOW (Windows) the open followed a link, so the name must still be this plain file.
+ if (
+ constants.O_NOFOLLOW === undefined &&
+ !sameFile(lstatSync(file, { throwIfNoEntry: false }), stat)
+ )
+ return null;
+ return readFileSync(fd);
+ } catch {
+ return null;
+ } finally {
+ closeSync(fd);
+ }
+}
+
/** `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}`);
diff --git a/packages/studio-server/src/helpers/waveform.ts b/packages/studio-server/src/helpers/waveform.ts
index ef8c9b49ab..fb8b210a52 100644
--- a/packages/studio-server/src/helpers/waveform.ts
+++ b/packages/studio-server/src/helpers/waveform.ts
@@ -14,6 +14,7 @@ import { dirname, join } from "node:path";
import { requireFfBinary } from "@hyperframes/parsers/ff-binaries";
import { probeAudioTrack } from "./mediaMetadata.js";
import { createStagingDir } from "@hyperframes/core/atomic-file";
+import { isProjectCacheFile, readProjectCacheFile } from "./safePath.js";
import { MEDIA_INPUT_ARGS } from "./mediaExtensions.js";
const SAMPLE_RATE = 4000;
@@ -160,13 +161,13 @@ export async function generateWaveformCache(projectDir: string, assetPath: strin
const stats = statSync(audioPath);
const cacheDir = join(projectDir, ".waveform-cache");
const cachePath = join(cacheDir, buildWaveformCacheKey(assetPath, stats));
- if (isWaveformCacheDirectory(cacheDir) && existsSync(cachePath)) return;
+ if (isProjectCacheFile(projectDir, cachePath)) return;
const peaks = await decodeAudioPeaks(audioPath);
writeWaveformCache(cachePath, peaks);
}
-export function isWaveformCacheDirectory(cacheDir: string): boolean {
+function isWaveformCacheDirectory(cacheDir: string): boolean {
return lstatSync(cacheDir, { throwIfNoEntry: false })?.isDirectory() ?? false;
}
@@ -200,6 +201,22 @@ export function writeWaveformCache(
}
}
+const PEAKS_CACHE_MAX_BYTES = 64 * 1024 * 1024;
+
+/** A peaks cache entry's numbers; a link, a non-file or anything but numbers is a miss and is decoded again. */
+export function readCachedPeaks(projectDir: string, cachePath: string): number[] | null {
+ const bytes = readProjectCacheFile(projectDir, cachePath, PEAKS_CACHE_MAX_BYTES);
+ if (!bytes) return null;
+ try {
+ const parsed: unknown = JSON.parse(bytes.toString("utf-8"));
+ if (!Array.isArray(parsed) || !parsed.every((n) => typeof n === "number")) return null;
+ markWaveformCacheUsed(cachePath);
+ return parsed;
+ } catch {
+ return null;
+ }
+}
+
/** Marks a cache entry as just used, so eviction drops the least recently used entries first. */
export function markWaveformCacheUsed(cachePath: string): void {
try {
diff --git a/packages/studio-server/src/routes/peaks.ts b/packages/studio-server/src/routes/peaks.ts
index b60b633410..a842b5d793 100644
--- a/packages/studio-server/src/routes/peaks.ts
+++ b/packages/studio-server/src/routes/peaks.ts
@@ -1,29 +1,13 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { statSync } from "node:fs";
import { join, relative, resolve } from "node:path";
import { isWithinProjectRoot } from "@hyperframes/parsers/asset-resolution";
import type { Hono } from "hono";
import type { StudioApiAdapter } from "../types.js";
-import {
- isWaveformCacheDirectory,
- markWaveformCacheUsed,
- writeWaveformCache,
-} from "../helpers/waveform.js";
+import { readCachedPeaks, writeWaveformCache } from "../helpers/waveform.js";
import { buildPeakMapCacheKey, decodePeakMap, PEAK_BIN_SECONDS } from "../helpers/peakMap.js";
import { requestSubPath } from "../helpers/requestSubPath.js";
import { decodeShared, type DecodeAudio } from "../helpers/audioDecodes.js";
-function readCachedBins(cacheDir: string, cachePath: string): number[] | null {
- try {
- if (!isWaveformCacheDirectory(cacheDir) || !existsSync(cachePath)) return null;
- const parsed: unknown = JSON.parse(readFileSync(cachePath, "utf-8"));
- if (!Array.isArray(parsed) || !parsed.every((n) => typeof n === "number")) return null;
- markWaveformCacheUsed(cachePath);
- return parsed;
- } catch {
- return null;
- }
-}
-
/** Absolute per-bin sample peaks for one media file, so the timeline can mark where a clip redlines. */
export function registerPeakRoutes(
api: Hono,
@@ -42,7 +26,7 @@ export function registerPeakRoutes(
const cacheDir = join(project.dir, ".waveform-cache");
const cachePath = join(cacheDir, buildPeakMapCacheKey(relative(project.dir, mediaPath), stats));
- const cached = readCachedBins(cacheDir, cachePath);
+ const cached = readCachedPeaks(project.dir, cachePath);
if (cached) return c.json({ binSeconds: PEAK_BIN_SECONDS, bins: cached });
let bins: number[];
diff --git a/packages/studio-server/src/routes/preview.test.ts b/packages/studio-server/src/routes/preview.test.ts
index 3ac8b54cf8..744bef17fd 100644
--- a/packages/studio-server/src/routes/preview.test.ts
+++ b/packages/studio-server/src/routes/preview.test.ts
@@ -1235,7 +1235,7 @@ describe("built preview reuse", () => {
app,
createAdapter(projectDir, {
bundle,
- previewDocuments: createPreviewDocumentStore(projectDir, salt),
+ previewDocuments: createPreviewDocumentStore(projectDir, salt, "secret"),
} as Partial),
);
const html = await (await app.request("http://localhost/projects/demo/preview")).text();
@@ -1258,7 +1258,7 @@ describe("built preview reuse", () => {
app,
createAdapter(projectDir, {
bundle,
- previewDocuments: createPreviewDocumentStore(projectDir, "build-a"),
+ previewDocuments: createPreviewDocumentStore(projectDir, "build-a", "secret"),
} as Partial),
);
for (const path of paths) await app.request(`http://localhost/projects/demo/${path}`);
@@ -3396,7 +3396,7 @@ describe("GSAP mirror configuration", () => {
);
const overrides = {
bundle,
- previewDocuments: createPreviewDocumentStore(projectDir, "same-build"),
+ previewDocuments: createPreviewDocumentStore(projectDir, "same-build", "secret"),
};
const first = appForMirror(projectDir, mirror, overrides);
const root = await first.request(previewUrl);
diff --git a/packages/studio-server/src/routes/thumbnail.test.ts b/packages/studio-server/src/routes/thumbnail.test.ts
index c195c9671f..e358e7a83a 100644
--- a/packages/studio-server/src/routes/thumbnail.test.ts
+++ b/packages/studio-server/src/routes/thumbnail.test.ts
@@ -6,7 +6,9 @@ import {
mkdtempSync,
readFileSync,
readdirSync,
+ renameSync,
rmSync,
+ symlinkSync,
truncateSync,
utimesSync,
writeFileSync,
@@ -619,3 +621,52 @@ describe("registerThumbnailRoutes", () => {
expect(existsSync(overflowPath)).toBe(false);
});
});
+
+describe.skipIf(process.platform === "win32")("a thumbnail cache entry the project ships", () => {
+ async function cachedThumbnail(): Promise<{
+ app: Hono;
+ dir: string;
+ entry: string;
+ url: string;
+ }> {
+ const adapter = createAdapter();
+ await writeComposition(adapter, 1920, 1080);
+ const project = await adapter.resolveProject("demo");
+ if (!project) throw new Error("missing project");
+ const app = new Hono();
+ registerThumbnailRoutes(app, adapter);
+ const url = "http://localhost/projects/demo/thumbnail/index.html?t=3";
+ expect(await (await app.request(url)).text()).toBe("thumb");
+ const [name] = readdirSync(join(project.dir, ".thumbnails"));
+ if (!name) throw new Error("nothing cached");
+ return { app, dir: project.dir, entry: join(project.dir, ".thumbnails", name), url };
+ }
+
+ function outsideDir(): string {
+ const dir = mkdtempSync(join(tmpdir(), "hf-thumbnail-outside-"));
+ tempProjectDirs.push(dir);
+ return dir;
+ }
+
+ it("is a miss when a link stands at the entry", async () => {
+ const { app, entry, url } = await cachedThumbnail();
+ const secret = join(outsideDir(), "id_rsa");
+ writeFileSync(secret, "PRIVATE KEY");
+ rmSync(entry);
+ symlinkSync(secret, entry);
+
+ const response = await app.request(`${url}&cached=1`);
+ expect(response.status).toBe(204);
+ expect(await response.text()).not.toContain("PRIVATE KEY");
+ });
+
+ it("is a miss when the cache folder is a link", async () => {
+ const { app, dir, url } = await cachedThumbnail();
+ const moved = join(outsideDir(), "thumbnails");
+ renameSync(join(dir, ".thumbnails"), moved);
+ symlinkSync(moved, join(dir, ".thumbnails"));
+
+ const response = await app.request(`${url}&cached=1`);
+ expect(response.status).toBe(204);
+ });
+});
diff --git a/packages/studio-server/src/routes/thumbnail.ts b/packages/studio-server/src/routes/thumbnail.ts
index 20cb672148..c0077f9884 100644
--- a/packages/studio-server/src/routes/thumbnail.ts
+++ b/packages/studio-server/src/routes/thumbnail.ts
@@ -29,6 +29,7 @@ import {
isProjectRootMissing,
mkdirWithinProject,
projectRelativePath,
+ readProjectCacheFile,
resolveWithinProject,
} from "../helpers/safePath.js";
import { proxyActivityMark } from "../helpers/proxyTranscoder.js";
@@ -231,9 +232,9 @@ export function registerThumbnailRoutes(
new Set([...thumbnailGenerationCoordinator.protectedKeys(), cachePath]),
);
}
- const cached = readFileOnce(cachePath);
- if (typeof cached === "object") {
- return new Response(new Uint8Array(cached.data), {
+ const cached = readProjectCacheFile(project.dir, cachePath, THUMBNAIL_CACHE_MAX_BYTES);
+ if (cached) {
+ return new Response(new Uint8Array(cached), {
headers: { "Content-Type": contentType, "Cache-Control": "no-cache" },
});
}
diff --git a/packages/studio-server/src/routes/waveform.test.ts b/packages/studio-server/src/routes/waveform.test.ts
index 72ce29c3a7..9c386faa72 100644
--- a/packages/studio-server/src/routes/waveform.test.ts
+++ b/packages/studio-server/src/routes/waveform.test.ts
@@ -1,9 +1,9 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import { Hono } from "hono";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { decodeAudioPeaks } from "../helpers/waveform.js";
+import { basename, join } from "node:path";
+import { buildWaveformCacheKey, decodeAudioPeaks } from "../helpers/waveform.js";
import { registerWaveformRoutes } from "./waveform";
import { stubAdapter } from "./stubAdapter.test-helpers";
@@ -53,4 +53,55 @@ describe("GET /projects/:id/waveform/*", () => {
for (const res of await both) expect(await res.json()).toEqual({ peaks: [0.6] });
expect(decode).toHaveBeenCalledTimes(1);
});
+ describe.skipIf(process.platform === "win32")("a cache entry the project ships", () => {
+ function projectWithCacheEntry(): { dir: string; entry: string; outside: string } {
+ const dir = mkdtempSync(join(tmpdir(), "hf-waveform-route-"));
+ const elsewhere = mkdtempSync(join(tmpdir(), "hf-waveform-outside-"));
+ dirs.push(dir, elsewhere);
+ writeFileSync(join(dir, "bed.wav"), "audio");
+ mkdirSync(join(dir, ".waveform-cache"));
+ const outside = join(elsewhere, "credentials.json");
+ writeFileSync(outside, JSON.stringify({ token: "secret-token" }));
+ const key = buildWaveformCacheKey("bed.wav", statSync(join(dir, "bed.wav")));
+ return { dir, entry: join(dir, ".waveform-cache", key), outside };
+ }
+
+ it("decodes again instead of reading through a link at the entry", async () => {
+ const { dir, entry, outside } = projectWithCacheEntry();
+ symlinkSync(outside, entry);
+ vi.mocked(decodeAudioPeaks).mockImplementation(async () => [0.4]);
+ const app = new Hono();
+ registerWaveformRoutes(app, stubAdapter(dir));
+
+ const body = await (await app.request("http://localhost/projects/p/waveform/bed.wav")).text();
+ expect(body).not.toContain("secret-token");
+ expect(JSON.parse(body)).toEqual({ peaks: [0.4] });
+ });
+
+ it("decodes again when the cache folder is a link", async () => {
+ const { dir, entry, outside } = projectWithCacheEntry();
+ rmSync(join(dir, ".waveform-cache"), { recursive: true });
+ const linkedFolder = join(outside, "..", "cache");
+ mkdirSync(linkedFolder);
+ writeFileSync(join(linkedFolder, basename(entry)), "[0.9]");
+ symlinkSync(linkedFolder, join(dir, ".waveform-cache"));
+ vi.mocked(decodeAudioPeaks).mockImplementation(async () => [0.4]);
+ const app = new Hono();
+ registerWaveformRoutes(app, stubAdapter(dir));
+
+ const res = await app.request("http://localhost/projects/p/waveform/bed.wav");
+ expect(await res.json()).toEqual({ peaks: [0.4] });
+ });
+
+ it("decodes again when a plain entry holds anything but numbers", async () => {
+ const { dir, entry } = projectWithCacheEntry();
+ writeFileSync(entry, JSON.stringify({ token: "secret-token" }));
+ vi.mocked(decodeAudioPeaks).mockImplementation(async () => [0.4]);
+ const app = new Hono();
+ registerWaveformRoutes(app, stubAdapter(dir));
+
+ const res = await app.request("http://localhost/projects/p/waveform/bed.wav");
+ expect(await res.json()).toEqual({ peaks: [0.4] });
+ });
+ });
});
diff --git a/packages/studio-server/src/routes/waveform.ts b/packages/studio-server/src/routes/waveform.ts
index efc113d9d7..c32a7b78c3 100644
--- a/packages/studio-server/src/routes/waveform.ts
+++ b/packages/studio-server/src/routes/waveform.ts
@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { statSync } from "node:fs";
import { join, relative, resolve } from "node:path";
import { isWithinProjectRoot } from "@hyperframes/parsers/asset-resolution";
import type { Hono } from "hono";
@@ -6,9 +6,8 @@ import type { StudioApiAdapter } from "../types.js";
import {
decodeAudioPeaks,
buildWaveformCacheKey,
+ readCachedPeaks,
writeWaveformCache,
- isWaveformCacheDirectory,
- markWaveformCacheUsed,
} from "../helpers/waveform.js";
import { requestSubPath } from "../helpers/requestSubPath.js";
import { decodeShared } from "../helpers/audioDecodes.js";
@@ -34,15 +33,8 @@ export function registerWaveformRoutes(api: Hono, adapter: StudioApiAdapter): vo
buildWaveformCacheKey(relative(project.dir, audioPath), stats),
);
- try {
- if (isWaveformCacheDirectory(cacheDir) && existsSync(cachePath)) {
- const peaks = JSON.parse(readFileSync(cachePath, "utf-8")) as number[];
- markWaveformCacheUsed(cachePath);
- return c.json({ peaks });
- }
- } catch {
- // corrupt or inaccessible cache — regenerate
- }
+ const cached = readCachedPeaks(project.dir, cachePath);
+ if (cached) return c.json({ peaks: cached });
let peaks: number[];
try {