Files
hyperframes/packages/cli/src/capture/captureFile.test.ts
T
Leonel RivasandMiguel Angel Simon Sierra d2cdad418a fix(cli): refuse capture folders that resolve outside the output root (#4789)
* fix(cli): refuse capture directories that resolve outside the output root

writeCaptureFileSync guards the final path entry, but a directory in the
path that is itself a planted symlink (assets -> ~/somewhere) still carried
the staging directory and the rename into wherever it pointed, with a
filename the captured page chose.

Every capture directory is now created through ensureCaptureDirSync(root,
dir), which walks from the output root one level at a time and refuses any
directory whose real path is not the one it has under the root, before
creating anything inside it. The root itself stays trusted as given, so a
symlinked root like /tmp on macOS keeps working.

Fixes #4304

* fix(cli): vet assets/svgs before the SVG contact sheet writes into it

Under --skip-assets, downloadAssets never runs, so nothing checked
assets/svgs before createSvgContactSheet wrote its thumbnails and
contact-sheet.jpg into it; a planted assets/svgs link received them.
The sheet now runs ensureCaptureDirSync on the directory first, and a
refusal just skips the sheet.

A dangling or looping directory link is now refused with the same
message instead of a raw ENOENT/ELOOP, and a comment records why the
check uses the JS realpathSync rather than realpathSync.native.

Refs #4304

* fix(cli): vet capture --video's download folder

Video mode created assets/videos (or capture/assets/videos in a W2H
project) with a plain mkdirSync, so a planted assets or capture link
carried the downloaded clip outside the project. It now goes through
ensureCaptureDirSync with the project folder as the trusted root, and
a refused folder is reported before anything is downloaded.

* fix(cli): warn when a best-effort capture phase refuses a folder

Folder refusals now throw CaptureDirRefusedError. The contact sheets
and the video manifest still skip on any error, but a refusal adds a
warning so a planted link doesn't go unnoticed.

saveLottieAnimations now vets assets/lottie itself, taking the output
root like renderLottiePreviews, and every folder check in the capture
pipeline is pinned by a test.

* style(cli): trim the ensureCaptureDirSync doc comment to two lines

---------

Co-authored-by: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
2026-10-02 05:53:31 -07:00

198 lines
6.9 KiB
TypeScript

import {
linkSync,
lstatSync,
mkdirSync,
mkdtempSync,
readFileSync,
readdirSync,
rmSync,
symlinkSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import { ensureCaptureDirSync, writeCaptureFileSync } from "./captureFile.js";
const temporaryDirectories: string[] = [];
afterEach(() => {
for (const directory of temporaryDirectories.splice(0))
rmSync(directory, { recursive: true, force: true });
});
function scratch(): { outputDir: string; victim: string } {
const root = mkdtempSync(join(tmpdir(), "hyperframes-capture-file-"));
temporaryDirectories.push(root);
const outputDir = join(root, "capture");
mkdirSync(outputDir);
const victim = join(root, "victim.txt");
writeFileSync(victim, "do not touch");
return { outputDir, victim };
}
// Creating symlinks needs elevated rights on Windows, and POSIX modes don't apply there.
const posixOnly = it.skipIf(process.platform === "win32");
describe("writeCaptureFileSync", () => {
posixOnly("replaces a pre-planted symlink instead of writing through it", () => {
const { outputDir, victim } = scratch();
const target = join(outputDir, "page.html");
symlinkSync(victim, target);
writeCaptureFileSync(target, "<html></html>", "utf-8");
expect(readFileSync(victim, "utf8")).toBe("do not touch");
expect(readFileSync(target, "utf8")).toBe("<html></html>");
expect(lstatSync(target).isSymbolicLink()).toBe(false);
});
it("replaces a pre-planted hard link instead of truncating the shared file", () => {
const { outputDir, victim } = scratch();
const target = join(outputDir, "tokens.json");
linkSync(victim, target);
writeCaptureFileSync(target, "{}");
expect(readFileSync(victim, "utf8")).toBe("do not touch");
expect(readFileSync(target, "utf8")).toBe("{}");
});
it("still overwrites a capture file written earlier in the run", () => {
const { outputDir } = scratch();
const target = join(outputDir, "page.html");
writeCaptureFileSync(target, "first attempt");
writeCaptureFileSync(target, "partial bundle");
expect(readFileSync(target, "utf8")).toBe("partial bundle");
});
posixOnly("creates the file readable by the owner only", () => {
const { outputDir } = scratch();
const target = join(outputDir, "meta.json");
writeCaptureFileSync(target, "{}");
expect(lstatSync(target).mode & 0o777).toBe(0o600);
});
it("keeps a caller's exclusive-create flag", () => {
const { outputDir } = scratch();
const target = join(outputDir, "meta.json");
writeCaptureFileSync(target, "real meta");
expect(() => writeCaptureFileSync(target, "partial meta", { flag: "wx" })).toThrow(
expect.objectContaining({ code: "EEXIST" }),
);
expect(readFileSync(target, "utf8")).toBe("real meta");
});
posixOnly("refuses a pre-planted symlink under a caller's exclusive-create flag", () => {
const { outputDir, victim } = scratch();
const target = join(outputDir, "meta.json");
symlinkSync(victim, target);
expect(() => writeCaptureFileSync(target, "partial meta", { flag: "wx" })).toThrow(
expect.objectContaining({ code: "EEXIST" }),
);
expect(readFileSync(victim, "utf8")).toBe("do not touch");
});
it("cleans up only what it created, even when the final rename fails", () => {
const { outputDir } = scratch();
const neighbour = join(outputDir, ".capture-keep");
writeFileSync(neighbour, "someone else's file");
mkdirSync(join(outputDir, "occupied"));
writeCaptureFileSync(join(outputDir, "a.txt"), "a");
expect(() => writeCaptureFileSync(join(outputDir, "occupied"), "b")).toThrow();
expect(readFileSync(neighbour, "utf8")).toBe("someone else's file");
expect(readdirSync(outputDir).sort()).toEqual([".capture-keep", "a.txt", "occupied"]);
});
it("leaves no temporary file behind, even when the final rename fails", () => {
const { outputDir } = scratch();
writeCaptureFileSync(join(outputDir, "a.txt"), "a");
mkdirSync(join(outputDir, "occupied"));
expect(() => writeCaptureFileSync(join(outputDir, "occupied"), "b")).toThrow();
expect(readdirSync(outputDir).sort()).toEqual(["a.txt", "occupied"]);
});
});
describe("ensureCaptureDirSync", () => {
it("creates nested directories under the root, and accepts them again on a re-run", () => {
const { outputDir } = scratch();
const fonts = join(outputDir, "assets", "fonts");
expect(ensureCaptureDirSync(outputDir, fonts)).toBe(fonts);
expect(ensureCaptureDirSync(outputDir, fonts)).toBe(fonts);
expect(lstatSync(fonts).isDirectory()).toBe(true);
});
posixOnly("refuses a planted directory symlink and creates nothing in its target", () => {
const { outputDir } = scratch();
const outside = join(outputDir, "..", "outside");
mkdirSync(outside);
symlinkSync(outside, join(outputDir, "assets"));
expect(() => ensureCaptureDirSync(outputDir, join(outputDir, "assets", "fonts"))).toThrow(
/outside the capture directory/,
);
expect(readdirSync(outside)).toEqual([]);
});
posixOnly("refuses a directory symlink even when it points elsewhere inside the root", () => {
const { outputDir } = scratch();
mkdirSync(join(outputDir, "extracted"));
symlinkSync(join(outputDir, "extracted"), join(outputDir, "assets"));
expect(() => ensureCaptureDirSync(outputDir, join(outputDir, "assets"))).toThrow(
/outside the capture directory/,
);
});
posixOnly("refuses a dangling or looping directory symlink with the same message", () => {
const { outputDir } = scratch();
symlinkSync(join(outputDir, "..", "missing"), join(outputDir, "assets"));
symlinkSync(join(outputDir, "screenshots"), join(outputDir, "screenshots"));
for (const name of ["assets", "screenshots"]) {
expect(() => ensureCaptureDirSync(outputDir, join(outputDir, name))).toThrow(
/outside the capture directory/,
);
}
});
posixOnly("trusts a root that is itself a symlink, as /tmp is on macOS", () => {
const { outputDir } = scratch();
const linkedRoot = join(outputDir, "..", "linked-capture");
symlinkSync(outputDir, linkedRoot);
ensureCaptureDirSync(linkedRoot, join(linkedRoot, "assets", "svgs"));
expect(lstatSync(join(outputDir, "assets", "svgs")).isDirectory()).toBe(true);
});
it("refuses a file sitting where a directory belongs", () => {
const { outputDir } = scratch();
writeFileSync(join(outputDir, "assets"), "not a directory");
expect(() => ensureCaptureDirSync(outputDir, join(outputDir, "assets"))).toThrow(
/not a directory/,
);
});
it("refuses a directory that is not under the root", () => {
const { outputDir } = scratch();
expect(() => ensureCaptureDirSync(outputDir, join(outputDir, "..", "elsewhere"))).toThrow(
/outside the capture directory/,
);
});
});