Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(cli): refuse capture folders that resolve outside the output root (#4789)
Leonel Rivasd2cdad418a63
diff --git a/packages/cli/src/capture/assetDownloader.test.ts b/packages/cli/src/capture/assetDownloader.test.tsindex 158551a445..715965485d 100644--- a/packages/cli/src/capture/assetDownloader.test.ts+++ b/packages/cli/src/capture/assetDownloader.test.ts@@ -1,5 +1,13 @@import { afterEach, describe, expect, it, vi } from "vitest";-import { mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";+import {+ existsSync,+ mkdirSync,+ mkdtempSync,+ readFileSync,+ readdirSync,+ rmSync,+ symlinkSync,+} from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";import {@@ -9,6 +17,7 @@ import {safeFetch,toStandaloneSvg,} from "./assetDownloader.js";+import { CaptureDirRefusedError } from "./captureErrors.js";import type { DesignTokens } from "./types.js";import type { IconCandidate } from "./faviconRanker.js";import { CAPTURE_USER_AGENT } from "./userAgent.js";@@ -741,3 +750,65 @@ describe("capture download security boundaries", () => {});});});++describe("a planted directory link inside the capture directory (#4304)", () => {+ // Creating symlinks needs elevated rights on Windows.+ const posixOnly = it.skipIf(process.platform === "win32");++ function plantedLink(root: string, link: string): { outputDir: string; outside: string } {+ const outputDir = join(root, "capture");+ const outside = join(root, "outside");+ mkdirSync(join(outputDir, link, ".."), { recursive: true });+ mkdirSync(outside);+ symlinkSync(outside, join(outputDir, link));+ return { outputDir, outside };+ }++ posixOnly.each(["assets", "assets/svgs"])(+ "refuses to write page-derived assets through a planted %s/ symlink",+ async (link) => {+ await withTempDir(async (root) => {+ const { outputDir, outside } = plantedLink(root, link);+ const svgs = [+ {+ outerHTML: `<svg viewBox="0 0 10 10"><rect width="10" height="10" fill="#abc"/></svg>`,+ isLogo: false,+ },+ ];++ await expect(+ downloadAssets({ svgs, sections: [], ogImage: "" } as unknown as DesignTokens, outputDir),+ ).rejects.toThrow(/outside the capture directory/);+ expect(readdirSync(outside)).toEqual([]);+ });+ },+ );++ posixOnly("refuses a dangling assets/ symlink before its svgs folder", async () => {+ await withTempDir(async (root) => {+ const outputDir = join(root, "capture");+ const target = join(root, "missing");+ mkdirSync(outputDir);+ symlinkSync(target, join(outputDir, "assets"));++ await expect(+ downloadAssets(+ { svgs: [], sections: [], ogImage: "" } as unknown as DesignTokens,+ outputDir,+ ),+ ).rejects.toThrow(CaptureDirRefusedError);+ expect(existsSync(target)).toBe(false);+ });+ });++ posixOnly("refuses to create the fonts directory through a planted assets/ symlink", async () => {+ await withTempDir(async (root) => {+ const { outputDir, outside } = plantedLink(root, "assets");++ await expect(downloadAndRewriteFonts("", outputDir)).rejects.toThrow(+ /outside the capture directory/,+ );+ expect(readdirSync(outside)).toEqual([]);+ });+ });+});diff --git a/packages/cli/src/capture/assetDownloader.ts b/packages/cli/src/capture/assetDownloader.tsindex c0d8d9bd5b..3dbf6188a1 100644--- a/packages/cli/src/capture/assetDownloader.ts+++ b/packages/cli/src/capture/assetDownloader.ts@@ -6,8 +6,7 @@*/import { isBlockedNetworkHost } from "@hyperframes/engine";-import { mkdirSync } from "node:fs";-import { writeCaptureFileSync } from "./captureFile.js";+import { ensureCaptureDirSync, writeCaptureFileSync } from "./captureFile.js";import { join, extname } from "node:path";import { createHash } from "node:crypto";import type { DesignTokens, DownloadedAsset } from "./types.js";@@ -317,14 +316,14 @@ export async function downloadAssets(): Promise<{ assets: DownloadedAsset[]; drops: AssetDropCounts; icons: IconManifest }> {options = { ...options, byteBudget: options.byteBudget ?? createCaptureDownloadBudget() };const assetsDir = join(outputDir, "assets");- mkdirSync(assetsDir, { recursive: true });+ ensureCaptureDirSync(outputDir, assetsDir);const assets: DownloadedAsset[] = [];const drops = noDrops();const downloadedUrls = new Set<string>();let icons: IconManifest = emptyIconManifest();- mkdirSync(join(outputDir, "assets", "svgs"), { recursive: true });+ ensureCaptureDirSync(outputDir, join(outputDir, "assets", "svgs"));const usedSvgNames = new Set<string>();const MAX_INLINE_SVGS = 30;drops["cap-reached"] += Math.max(0, tokens.svgs.length - MAX_INLINE_SVGS);@@ -542,7 +541,7 @@ export async function downloadAndRewriteFonts(): Promise<{ css: string; drops: AssetDropCounts }> {options = { ...options, byteBudget: options.byteBudget ?? createCaptureDownloadBudget() };const assetsDir = join(outputDir, "assets", "fonts");- mkdirSync(assetsDir, { recursive: true });+ ensureCaptureDirSync(outputDir, assetsDir);const drops = noDrops();const fontUrlRegex = /url\(['"]?(https?:\/\/[^'")\s]+\.(?:woff2?|ttf|otf)[^'")\s]*?)['"]?\)/g;diff --git a/packages/cli/src/capture/captureAttempt.test.ts b/packages/cli/src/capture/captureAttempt.test.tsnew file mode 100644index 0000000000..c78ca995bc--- /dev/null+++ b/packages/cli/src/capture/captureAttempt.test.ts@@ -0,0 +1,47 @@+import { mkdirSync, mkdtempSync, readdirSync, rmSync, symlinkSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { describe, expect, it, onTestFinished, vi } from "vitest";+import { captureWebsiteAttempt } from "./captureAttempt.js";+import { CaptureDirRefusedError } from "./captureErrors.js";+import type { CaptureWatchdog } from "./captureWatchdog.js";+import { createPartialCaptureState } from "./partialCapture.js";++const { ensureBrowserMock } = vi.hoisted(() => ({+ ensureBrowserMock: vi.fn(async () => {+ throw new Error("the browser must not start");+ }),+}));+vi.mock("../browser/manager.js", () => ({ ensureBrowser: ensureBrowserMock }));++const watchdog: CaptureWatchdog = {+ expired: () => false,+ promise: new Promise(() => {}),+ registerBrowser: () => {},+ unregisterBrowser: () => {},+ dispose: () => {},+};++describe("captureWebsiteAttempt output folders", () => {+ // Creating symlinks needs elevated rights on Windows.+ it.skipIf(process.platform === "win32").each(["extracted", "screenshots", "assets"])(+ "refuses a planted %s/ symlink before the browser starts (#4304)",+ async (link) => {+ const root = mkdtempSync(join(tmpdir(), "hf-capture-attempt-"));+ onTestFinished(() => rmSync(root, { recursive: true, force: true }));+ const outputDir = join(root, "capture");+ const outside = join(root, "outside");+ mkdirSync(outputDir);+ mkdirSync(outside);+ symlinkSync(outside, join(outputDir, link));+ const opts = { url: "https://example.com", outputDir };++ await expect(+ captureWebsiteAttempt(opts, undefined, false, watchdog, createPartialCaptureState(opts)),+ ).rejects.toThrow(CaptureDirRefusedError);++ expect(readdirSync(outside)).toEqual([]);+ expect(ensureBrowserMock).not.toHaveBeenCalled();+ },+ );+});diff --git a/packages/cli/src/capture/captureAttempt.ts b/packages/cli/src/capture/captureAttempt.tsindex 9c333c5d2f..9303d642cb 100644--- a/packages/cli/src/capture/captureAttempt.ts+++ b/packages/cli/src/capture/captureAttempt.ts@@ -5,9 +5,10 @@ import { createCaptureDownloadBudget } from "./readBoundedResponse.js";* - Rich animation metadata for Claude Code to recreate*/-import { mkdirSync, existsSync } from "node:fs";+import { existsSync } from "node:fs";import { join } from "node:path";import { noDrops } from "./assetDownloader.js";+import { ensureCaptureDirSync } from "./captureFile.js";import type { IconCandidate } from "./faviconRanker.js";import { CAPTURE_USER_AGENT } from "./userAgent.js";import { setupAnimationCapture, startCdpAnimationCapture } from "./animationCataloger.js";@@ -101,9 +102,9 @@ export async function captureWebsiteAttempt(loadEnvFile(outputDir);// Create output directories- mkdirSync(join(outputDir, "extracted"), { recursive: true });- mkdirSync(join(outputDir, "screenshots"), { recursive: true });- mkdirSync(join(outputDir, "assets"), { recursive: true });+ ensureCaptureDirSync(outputDir, join(outputDir, "extracted"));+ ensureCaptureDirSync(outputDir, join(outputDir, "screenshots"));+ ensureCaptureDirSync(outputDir, join(outputDir, "assets"));// Launch browserprogress("browser", "Launching headless Chrome...");diff --git a/packages/cli/src/capture/captureErrors.ts b/packages/cli/src/capture/captureErrors.tsindex e8a051bc54..e3733d2a45 100644--- a/packages/cli/src/capture/captureErrors.ts+++ b/packages/cli/src/capture/captureErrors.ts@@ -7,3 +7,10 @@ export class NavigationDeadlineError extends Error {this.name = "NavigationDeadlineError";}}++export class CaptureDirRefusedError extends Error {+ constructor(message: string) {+ super(message);+ this.name = "CaptureDirRefusedError";+ }+}diff --git a/packages/cli/src/capture/captureFile.test.ts b/packages/cli/src/capture/captureFile.test.tsindex fb83b61763..60b70cadb3 100644--- a/packages/cli/src/capture/captureFile.test.ts+++ b/packages/cli/src/capture/captureFile.test.ts@@ -12,7 +12,7 @@ import {import { tmpdir } from "node:os";import { join } from "node:path";import { afterEach, describe, expect, it } from "vitest";-import { writeCaptureFileSync } from "./captureFile.js";+import { ensureCaptureDirSync, writeCaptureFileSync } from "./captureFile.js";const temporaryDirectories: string[] = [];@@ -122,3 +122,76 @@ describe("writeCaptureFileSync", () => {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/,+ );+ });+});diff --git a/packages/cli/src/capture/captureFile.ts b/packages/cli/src/capture/captureFile.tsindex a1128d53ce..a483e107ef 100644--- a/packages/cli/src/capture/captureFile.ts+++ b/packages/cli/src/capture/captureFile.ts@@ -1,5 +1,14 @@-import { mkdtempSync, renameSync, rmSync, writeFileSync } from "node:fs";-import { basename, dirname, join } from "node:path";+import {+ mkdirSync,+ mkdtempSync,+ realpathSync,+ renameSync,+ rmSync,+ statSync,+ writeFileSync,+} from "node:fs";+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";+import { CaptureDirRefusedError } from "./captureErrors.js";type WriteOptions = Parameters<typeof writeFileSync>[2];@@ -40,3 +49,59 @@ export function writeCaptureFileSync(}writeFileSync(path, data, { ...normalized, mode: 0o600 });}++function hasCode(error: unknown, ...codes: string[]): boolean {+ return (+ error instanceof Error &&+ "code" in error &&+ typeof error.code === "string" &&+ codes.includes(error.code)+ );+}++// The JS `realpathSync`, deliberately not `realpathSync.native`: native returns the on-disk case+// on macOS/Windows, so an existing `Assets/` asked for as `assets` would be falsely refused. The+// JS walk only rewrites the components that are links, which is exactly what is being checked.+function resolvedPath(path: string): string | undefined {+ try {+ return realpathSync(path);+ } catch (error) {+ // A dangling or looping link resolves nowhere: refuse it like any other escaping link.+ if (hasCode(error, "ENOENT", "ELOOP")) return undefined;+ throw error;+ }+}++// Creates `dir` under the trusted capture root, refusing any directory whose real path leaves it (#4304).+// Checked on creation, not on every write: a link swapped in later by a racing process is out of scope.+export function ensureCaptureDirSync(root: string, dir: string): string {+ const rootPath = resolve(root);+ const target = resolve(dir);+ const rel = relative(rootPath, target);+ if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {+ throw new CaptureDirRefusedError(+ `Refusing to create ${target}: it is outside the capture directory ${rootPath}`,+ );+ }+ mkdirSync(rootPath, { recursive: true });+ let current = rootPath;+ let expected = realpathSync(rootPath);+ for (const segment of rel.split(sep).filter(Boolean)) {+ current = join(current, segment);+ expected = join(expected, segment);+ try {+ mkdirSync(current);+ } catch (error) {+ if (!hasCode(error, "EEXIST")) throw error;+ }+ if (resolvedPath(current) !== expected) {+ throw new CaptureDirRefusedError(+ `Refusing to write into ${current}: it resolves outside the capture directory ${rootPath}`,+ );+ }+ if (!statSync(current).isDirectory()) {+ throw new CaptureDirRefusedError(`Refusing to write into ${current}: it is not a directory`);+ }+ }+ return target;+}diff --git a/packages/cli/src/capture/coreExtractionPhase.ts b/packages/cli/src/capture/coreExtractionPhase.tsindex d64ef31014..717923ff33 100644--- a/packages/cli/src/capture/coreExtractionPhase.ts+++ b/packages/cli/src/capture/coreExtractionPhase.ts@@ -9,8 +9,8 @@ import type { IconCandidate } from "./faviconRanker.js";import { startCdpAnimationCapture } from "./animationCataloger.js";import { createCaptureDownloadBudget } from "./readBoundedResponse.js";import { detectLibraries } from "./contentExtractor.js";-import { mkdirSync } from "node:fs";import { writeCaptureFileSync } from "./captureFile.js";+import { CaptureDirRefusedError } from "./captureErrors.js";import { join } from "node:path";import { extractHtml } from "./htmlExtractor.js";import { extractTokens } from "./tokenExtractor.js";@@ -176,9 +176,13 @@ export async function runCoreExtraction(input: CoreExtractionInput): Promise<Corif (discoveredLotties.length > 0 && remainingMs() > 0) {const lottieDir = join(outputDir, "assets", "lottie");if (!canWrite()) return;- mkdirSync(lottieDir, { recursive: true });const lottieBudget = { remainingMs, byteBudget: downloadByteBudget };- const savedCount = await saveLottieAnimations(discoveredLotties, lottieDir, lottieBudget);+ const savedCount = await saveLottieAnimations(+ discoveredLotties,+ lottieDir,+ outputDir,+ lottieBudget,+ );// Generate manifest + preview thumbnails so the agent can SEE what each animation isif (savedCount > 0 && remainingMs() > 0 && canWrite()) {await renderLottiePreviews(chromeBrowser, lottieDir, outputDir, lottieBudget);@@ -348,8 +352,10 @@ export async function runCoreExtraction(input: CoreExtractionInput): Promise<CorremainingMs,});}- } catch {- /* non-blocking — video manifest is best-effort */+ } catch (err) {+ if (err instanceof CaptureDirRefusedError)+ warnings.push(`Video manifest skipped: ${err.message}`);+ /* otherwise non-blocking — video manifest is best-effort */}// Detect JS libraries via globals, DOM fingerprints, script URLs, and shadersdiff --git a/packages/cli/src/capture/mediaCapture.test.ts b/packages/cli/src/capture/mediaCapture.test.tsindex 3307763f12..2393a9ad83 100644--- a/packages/cli/src/capture/mediaCapture.test.ts+++ b/packages/cli/src/capture/mediaCapture.test.ts@@ -19,6 +19,7 @@ import {renderLottiePreviews,saveLottieAnimations,} from "./mediaCapture.js";+import { CaptureDirRefusedError } from "./captureErrors.js";const tempDirs: string[] = [];@@ -48,6 +49,7 @@ describe("Lottie capture budget", () => {const saved = await saveLottieAnimations([{ url: "https://one.example/a.json" }, { url: "https://two.example/b.json" }],dir,+ dir,{ remainingMs: () => remainingMs },);@@ -207,7 +209,9 @@ describe("Lottie capture rejects unsafe persistence", () => {"fetch",vi.fn(async () => new Response("not a zip")),);- expect(await saveLottieAnimations([{ url: "https://public.example/bad.lottie" }], dir)).toBe(0);+ expect(+ await saveLottieAnimations([{ url: "https://public.example/bad.lottie" }], dir, dir),+ ).toBe(0);expect(readdirSync(dir)).toEqual([]);});it("does not publish truthy non-array layers", async () => {@@ -216,7 +220,9 @@ describe("Lottie capture rejects unsafe persistence", () => {"fetch",vi.fn(async () => new Response('{"w":100,"h":100,"layers":true}')),);- expect(await saveLottieAnimations([{ url: "https://public.example/bad.json" }], dir)).toBe(0);+ expect(await saveLottieAnimations([{ url: "https://public.example/bad.json" }], dir, dir)).toBe(+ 0,+ );expect(readdirSync(dir)).toEqual([]);});});@@ -299,3 +305,90 @@ describe("media previews replace pre-planted links", () => {},);});++describe("media folders refuse a planted directory link (#4304)", () => {+ // captureVideoManifest keeps any http(s) video it finds; only the URL matters here.+ const descriptor = { src: "https://video.example/planted.mp4", filename: "planted.mp4" };++ function plantedCapture(link: string): { dir: string; outside: string } {+ const dir = tempDir();+ const outside = join(dir, "outside");+ mkdirSync(outside);+ mkdirSync(join(dir, "extracted"));+ mkdirSync(join(dir, link, ".."), { recursive: true });+ symlinkSync(outside, join(dir, link));+ return { dir, outside };+ }++ // Creating symlinks needs elevated rights on Windows.+ it.skipIf(process.platform === "win32").each(["assets/videos", "assets/videos/previews"])(+ "does not write the video manifest through a planted %s link",+ async (link) => {+ const { dir, outside } = plantedCapture(link);+ const screenshot = vi.fn();+ const page = { evaluate: vi.fn(async () => [descriptor]), screenshot } as unknown as Page;+ vi.stubGlobal(+ "fetch",+ vi.fn(async () => new Response(null, { status: 404 })),+ );++ await expect(captureVideoManifest(page, dir, () => {})).rejects.toThrow(+ CaptureDirRefusedError,+ );+ expect(readdirSync(outside)).toEqual([]);+ expect(screenshot).not.toHaveBeenCalled();+ },+ );++ it.skipIf(process.platform === "win32")(+ "refuses a dangling assets/videos link before its previews folder",+ async () => {+ const dir = tempDir();+ const target = join(dir, "missing");+ mkdirSync(join(dir, "assets"), { recursive: true });+ symlinkSync(target, join(dir, "assets", "videos"));+ const page = {+ evaluate: vi.fn(async () => [descriptor]),+ screenshot: vi.fn(),+ } as unknown as Page;++ await expect(captureVideoManifest(page, dir, () => {})).rejects.toThrow(+ CaptureDirRefusedError,+ );+ expect(existsSync(target)).toBe(false);+ },+ );++ it.skipIf(process.platform === "win32")(+ "does not save Lottie files through a planted assets/lottie link",+ async () => {+ const { dir, outside } = plantedCapture("assets/lottie");+ const fetchMock = vi.fn();+ vi.stubGlobal("fetch", fetchMock);++ await expect(+ saveLottieAnimations(+ [{ url: "https://public.example/a.json" }],+ join(dir, "assets", "lottie"),+ dir,+ ),+ ).rejects.toThrow(CaptureDirRefusedError);+ expect(readdirSync(outside)).toEqual([]);+ expect(fetchMock).not.toHaveBeenCalled();+ },+ );++ it.skipIf(process.platform === "win32")(+ "does not render Lottie previews through a planted previews link",+ async () => {+ const { dir, outside } = plantedCapture("assets/lottie/previews");+ const browser = { newPage: vi.fn() } as unknown as Browser;++ await expect(+ renderLottiePreviews(browser, join(dir, "assets", "lottie"), dir),+ ).rejects.toThrow(CaptureDirRefusedError);+ expect(readdirSync(outside)).toEqual([]);+ expect(browser.newPage).not.toHaveBeenCalled();+ },+ );+});diff --git a/packages/cli/src/capture/mediaCapture.ts b/packages/cli/src/capture/mediaCapture.tsindex bf178b86df..4005962cb5 100644--- a/packages/cli/src/capture/mediaCapture.ts+++ b/packages/cli/src/capture/mediaCapture.ts@@ -8,8 +8,8 @@*/import type { Browser, Page } from "puppeteer-core";-import { mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";-import { writeCaptureFileSync } from "./captureFile.js";+import { readdirSync, readFileSync, statSync } from "node:fs";+import { ensureCaptureDirSync, writeCaptureFileSync } from "./captureFile.js";import { join, extname } from "node:path";import { isPrivateUrl, safeFetch } from "./assetDownloader.js";import { CAPTURE_USER_AGENT } from "./userAgent.js";@@ -50,8 +50,10 @@ function liveRemainingMs(budget: RemainingBudget, fallbackMs: number): number {export async function saveLottieAnimations(discoveredLotties: DiscoveredLottie[],lottieDir: string,+ outputDir: string,budget: RemainingBudget = {},): Promise<number> {+ ensureCaptureDirSync(outputDir, lottieDir);const byteBudget = budget.byteBudget ?? createCaptureDownloadBudget();let savedCount = 0;const savedHashes = new Set<string>(); // Deduplicate by content@@ -130,7 +132,7 @@ export async function renderLottiePreviews(layers: number;}> = [];const previewDir = join(lottieDir, "previews");- mkdirSync(previewDir, { recursive: true });+ ensureCaptureDirSync(outputDir, previewDir);for (const file of readdirSync(lottieDir)) {if (!file.endsWith(".json")) continue;@@ -470,9 +472,9 @@ export async function captureVideoManifest(if (merged.length === 0) return;const videoManifestDir = join(outputDir, "assets", "videos");- mkdirSync(videoManifestDir, { recursive: true });+ ensureCaptureDirSync(outputDir, videoManifestDir);const previewDir = join(videoManifestDir, "previews");- mkdirSync(previewDir, { recursive: true });+ ensureCaptureDirSync(outputDir, previewDir);const videoManifest: Array<{index: number;diff --git a/packages/cli/src/capture/partialCapture.test.ts b/packages/cli/src/capture/partialCapture.test.tsindex 17392b228f..d23ea384fd 100644--- a/packages/cli/src/capture/partialCapture.test.ts+++ b/packages/cli/src/capture/partialCapture.test.ts@@ -1,4 +1,12 @@-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";+import {+ existsSync,+ mkdirSync,+ mkdtempSync,+ readFileSync,+ readdirSync,+ rmSync,+ symlinkSync,+} from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";import { afterEach, describe, expect, it } from "vitest";@@ -45,4 +53,30 @@ describe("writePartialCaptureBundle", () => {partial: true,});});++ // Creating symlinks needs elevated rights on Windows.+ it.skipIf(process.platform === "win32")(+ "refuses to write through a planted extracted/ symlink (#4304)",+ () => {+ const root = mkdtempSync(join(tmpdir(), "hyperframes-partial-capture-"));+ temporaryDirectories.push(root);+ const outputDir = join(root, "capture");+ const outside = join(root, "outside");+ mkdirSync(outputDir);+ mkdirSync(outside);+ symlinkSync(outside, join(outputDir, "extracted"));+ const opts = { url: "https://example.com", outputDir };++ expect(() =>+ writePartialCaptureBundle(opts, createPartialCaptureState(opts), {+ schema: CAPTURE_PHASE_SCHEMA,+ phase: "complete",+ status: "degraded",+ remainingMs: null,+ reason: "deadline",+ }),+ ).toThrow(/outside the capture directory/);+ expect(readdirSync(outside)).toEqual([]);+ },+ );});diff --git a/packages/cli/src/capture/partialCapture.ts b/packages/cli/src/capture/partialCapture.tsindex 08156e610a..63239d5abc 100644--- a/packages/cli/src/capture/partialCapture.ts+++ b/packages/cli/src/capture/partialCapture.ts@@ -1,5 +1,4 @@-import { mkdirSync } from "node:fs";-import { writeCaptureFileSync } from "./captureFile.js";+import { ensureCaptureDirSync, writeCaptureFileSync } from "./captureFile.js";import { join } from "node:path";import { noDrops } from "./assetDownloader.js";import type {@@ -74,9 +73,7 @@ export function writePartialCaptureBundle(lastPhase: CaptureResult["lastPhase"],): CaptureResult {const hostname = new URL(opts.url).hostname.replace(/^www\./, "");- mkdirSync(opts.outputDir, { recursive: true });- const extractedDir = join(opts.outputDir, "extracted");- mkdirSync(extractedDir, { recursive: true });+ const extractedDir = ensureCaptureDirSync(opts.outputDir, join(opts.outputDir, "extracted"));writeCaptureFileSync(join(extractedDir, "tokens.json"), serializeTokensForCapture(state.tokens));writeCaptureFileSync(join(extractedDir, "design-styles.json"),diff --git a/packages/cli/src/capture/postExtractionPhase.test.ts b/packages/cli/src/capture/postExtractionPhase.test.tsnew file mode 100644index 0000000000..454ebe1dac--- /dev/null+++ b/packages/cli/src/capture/postExtractionPhase.test.ts@@ -0,0 +1,58 @@+import { mkdirSync, mkdtempSync, readdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { describe, expect, it, onTestFinished } from "vitest";+import { noDrops } from "./assetDownloader.js";+import { createPartialCaptureState } from "./partialCapture.js";+import { runPostExtraction } from "./postExtractionPhase.js";+import { createCaptureDownloadBudget } from "./readBoundedResponse.js";++const PLANTED_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10"><rect width="10" height="10" fill="#abc"/></svg>`;++describe("runPostExtraction", () => {+ // Creating symlinks needs elevated rights on Windows.+ it.skipIf(process.platform === "win32")(+ "does not write the SVG contact sheet through a planted assets/svgs symlink under --skip-assets (#4304)",+ async () => {+ const root = mkdtempSync(join(tmpdir(), "hyperframes-post-extraction-"));+ onTestFinished(() => rmSync(root, { recursive: true, force: true }));+ const outputDir = join(root, "capture");+ const outside = join(root, "outside");+ for (const dir of ["extracted", "screenshots", "assets"]) {+ mkdirSync(join(outputDir, dir), { recursive: true });+ }+ mkdirSync(outside);+ writeFileSync(join(outside, "planted.svg"), PLANTED_SVG);+ symlinkSync(outside, join(outputDir, "assets", "svgs"));++ const state = createPartialCaptureState({ url: "https://example.com", outputDir });+ const warnings: string[] = [];+ await runPostExtraction({+ state,+ outputDir,+ warnings,+ progress: () => {},+ remainingMs: () => 60_000,+ phase: () => {},+ animationCatalog: undefined,+ catalogedAssets: [],+ visibleTextContent: "",+ faviconLinks: [],+ tokens: state.tokens,+ extracted: state.extracted,+ skipAssets: true,+ skipVision: true,+ downloadByteBudget: createCaptureDownloadBudget(),+ assets: [],+ dropped: noDrops(),+ fontDrops: noDrops(),+ canWrite: () => true,+ });++ expect(readdirSync(outside)).toEqual(["planted.svg"]);+ expect(warnings).toEqual([+ expect.stringMatching(/^SVG contact sheet skipped: Refusing to write/),+ ]);+ },+ );+});diff --git a/packages/cli/src/capture/postExtractionPhase.ts b/packages/cli/src/capture/postExtractionPhase.tsindex 1163e1f18d..8733462c53 100644--- a/packages/cli/src/capture/postExtractionPhase.ts+++ b/packages/cli/src/capture/postExtractionPhase.ts@@ -1,5 +1,6 @@import { existsSync } from "node:fs";-import { writeCaptureFileSync } from "./captureFile.js";+import { ensureCaptureDirSync, writeCaptureFileSync } from "./captureFile.js";+import { CaptureDirRefusedError } from "./captureErrors.js";import { join } from "node:path";import {downloadAssets,@@ -404,7 +405,9 @@ export async function runPostExtraction(input: PostExtractionInput): Promise<Pos// so sites like huly.io that only use external SVGs still get a gridconst svgsDir = join(outputDir, "assets", "svgs");const assetsRootDir = join(outputDir, "assets");- const svgOutputPath = existsSync(svgsDir)+ const hasSvgsDir = existsSync(svgsDir);+ if (hasSvgsDir) ensureCaptureDirSync(outputDir, svgsDir);+ const svgOutputPath = hasSvgsDir? join(outputDir, "assets", "svgs", "contact-sheet.jpg"): join(outputDir, "assets", "contact-sheet-svgs.jpg");const svgSheets = await createSvgContactSheet(@@ -420,8 +423,10 @@ export async function runPostExtraction(input: PostExtractionInput): Promise<Pos);};await runSvgContactSheet();- } catch {- /* contact sheets are non-critical — agent can still read images individually */+ } catch (err) {+ if (err instanceof CaptureDirRefusedError)+ warnings.push(`SVG contact sheet skipped: ${err.message}`);+ /* otherwise non-critical — agent can still read images individually */}phase("contact-sheets",diff --git a/packages/cli/src/capture/screenshotCapture.test.ts b/packages/cli/src/capture/screenshotCapture.test.tsindex a9478bd03a..9fc844ed6f 100644--- a/packages/cli/src/capture/screenshotCapture.test.ts+++ b/packages/cli/src/capture/screenshotCapture.test.ts@@ -1,5 +1,13 @@import { describe, expect, it, onTestFinished, vi } from "vitest";-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";+import {+ existsSync,+ mkdirSync,+ mkdtempSync,+ readFileSync,+ readdirSync,+ rmSync,+ symlinkSync,+} from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";import type { Page } from "puppeteer-core";@@ -9,6 +17,7 @@ import {MAX_PLATE_HEIGHT_PX,pngHeight,} from "./screenshotCapture.js";+import { CaptureDirRefusedError } from "./captureErrors.js";function tempDir(prefix: string): string {const dir = mkdtempSync(join(tmpdir(), prefix));@@ -263,3 +272,23 @@ describe("captureFullPagePlate — the guard sees the post-neutralisation page (expect(String(evaluate.mock.calls.at(-1)?.[0])).toContain("removeAttribute");});});++describe("captureScrollScreenshots — planted screenshots link (#4304)", () => {+ // Creating symlinks needs elevated rights on Windows.+ it.skipIf(process.platform === "win32")(+ "refuses a planted screenshots/ symlink before touching the page",+ async () => {+ const dir = tempDir("hf-scroll-planted-");+ const outside = join(dir, "outside");+ mkdirSync(outside);+ symlinkSync(outside, join(dir, "screenshots"));+ const { page, evaluate, screenshot } = fakePage();++ await expect(captureScrollScreenshots(page, dir)).rejects.toThrow(CaptureDirRefusedError);++ expect(readdirSync(outside)).toEqual([]);+ expect(evaluate).not.toHaveBeenCalled();+ expect(screenshot).not.toHaveBeenCalled();+ },+ );+});diff --git a/packages/cli/src/capture/screenshotCapture.ts b/packages/cli/src/capture/screenshotCapture.tsindex 57b36c00f1..bdde074316 100644--- a/packages/cli/src/capture/screenshotCapture.ts+++ b/packages/cli/src/capture/screenshotCapture.ts@@ -7,9 +7,8 @@import type { Page } from "puppeteer-core";import { isDegradableEvaluateTimeoutError } from "./captureTimeout.js";-import { mkdirSync } from "node:fs";import { join } from "node:path";-import { writeCaptureFileSync } from "./captureFile.js";+import { ensureCaptureDirSync, writeCaptureFileSync } from "./captureFile.js";/*** Capture viewport screenshots covering the entire page height.@@ -118,7 +117,7 @@ export async function captureScrollScreenshots(budget: { remainingMs?: () => number } = {},): Promise<string[]> {const screenshotsDir = join(outputDir, "screenshots");- mkdirSync(screenshotsDir, { recursive: true });+ ensureCaptureDirSync(outputDir, screenshotsDir);const MAX_SCREENSHOTS = 20;const filePaths: string[] = [];diff --git a/packages/cli/src/commands/capture/video.test.ts b/packages/cli/src/commands/capture/video.test.tsindex 4cfc0f50f5..a3f7c15444 100644--- a/packages/cli/src/commands/capture/video.test.ts+++ b/packages/cli/src/commands/capture/video.test.ts@@ -1,9 +1,14 @@-import { describe, expect, it } from "vitest";+import { existsSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { describe, expect, it, onTestFinished, vi } from "vitest";+import { consumeCommandResult } from "../../utils/commandResult.js";import {MAX_VIDEO_BYTES,VIDEO_CONTENT_TYPE_RE,findFilenameCollision,pickManifestEntry,+ runVideoMode,safeFilename,type ManifestEntry,} from "./video.js";@@ -160,3 +165,44 @@ describe("findFilenameCollision", () => {expect(collisions.every((c) => c.index !== 0)).toBe(true);});});++describe("runVideoMode", () => {+ // Creating symlinks needs elevated rights on Windows.+ it.skipIf(process.platform === "win32").each([+ { layout: "capture output", manifestDir: "extracted", planted: "assets" },+ { layout: "W2H project", manifestDir: "capture/extracted", planted: "capture" },+ ])(+ "refuses to download through a planted $planted symlink in a $layout (#4304)",+ async ({ manifestDir, planted }) => {+ const root = mkdtempSync(join(tmpdir(), "hf-video-mode-"));+ onTestFinished(() => rmSync(root, { recursive: true, force: true }));+ const projectDir = join(root, "project");+ const outside = join(root, "outside");+ mkdirSync(projectDir);+ mkdirSync(outside);+ symlinkSync(outside, join(projectDir, planted));+ mkdirSync(join(projectDir, manifestDir), { recursive: true });+ writeFileSync(+ join(projectDir, manifestDir, "video-manifest.json"),+ JSON.stringify([ENTRY(0)]),+ );+ const fetchMock = vi.fn(async () => {+ throw new Error("no network in tests");+ });+ vi.stubGlobal("fetch", fetchMock);+ vi.spyOn(console, "log").mockImplementation(() => {});+ const error = vi.spyOn(console, "error").mockImplementation(() => {});+ onTestFinished(() => {+ vi.unstubAllGlobals();+ vi.restoreAllMocks();+ });++ await runVideoMode({ project: projectDir, index: "0" });++ expect(consumeCommandResult().exitCode).toBe(1);+ expect(String(error.mock.calls[0]?.[0])).toContain("resolves outside the capture directory");+ expect(fetchMock).not.toHaveBeenCalled();+ expect(existsSync(join(outside, planted === "assets" ? "videos" : "assets"))).toBe(false);+ },+ );+});diff --git a/packages/cli/src/commands/capture/video.ts b/packages/cli/src/commands/capture/video.tsindex a62d0f27a7..ebb0dcf9c9 100644--- a/packages/cli/src/commands/capture/video.ts+++ b/packages/cli/src/commands/capture/video.ts@@ -1,8 +1,9 @@import { setCommandExitCode } from "../../utils/commandResult.js";-import { createWriteStream, existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";+import { createWriteStream, existsSync, readFileSync, unlinkSync } from "node:fs";import { resolve, join, basename } from "node:path";import { c } from "../../ui/colors.js";import { safeFetch } from "../../capture/assetDownloader.js";+import { ensureCaptureDirSync } from "../../capture/captureFile.js";import { CAPTURE_USER_AGENT } from "../../capture/userAgent.js";const MAX_VIDEO_BYTES = 250 * 1024 * 1024;@@ -254,7 +255,13 @@ export async function runVideoMode(args: VideoModeArgs): Promise<void> {const outDir = isW2hLayout? join(projectDir, "capture", "assets", "videos"): join(projectDir, "assets", "videos");- mkdirSync(outDir, { recursive: true });+ try {+ ensureCaptureDirSync(projectDir, outDir);+ } catch (e) {+ console.error(`${c.error("✗")} ${(e as Error).message}`);+ setCommandExitCode(1);+ return;+ }const fname = safeFilename(entry.filename || basename(entry.url));const outPath = join(outDir, fname);const relPath = isW2hLayout ? `capture/assets/videos/${fname}` : `assets/videos/${fname}`;