Skip to content

Commit 42e872f

Browse files
committed
fix(producer): external assets work on Windows (GH #321)
Two Unix-only assumptions in the external-asset pipeline caused every absolute path on Windows to be rejected as "unsafe" at render time: 1. Containment checks used `child.startsWith(parent + "/")`. On Windows the separator is `\`, so the predicate is always false unless the paths are equal — every external asset tripped the safety guard in `renderOrchestrator.ts`. The reporter saw: [Render] Skipping external asset with unsafe path: hf-ext/D:\coder\reactGin\hyperframes\reading\assets\segment_001.wav Fix: use `path.relative()` through a shared helper `isPathInside(child, parent)` that normalises separators per-platform and correctly rejects siblings whose names start with the parent (e.g. `/foo/bar-sibling` is NOT inside `/foo/bar`). 2. The external-asset key was built as `"hf-ext/" + absPath.replace(/^\//, "")`. A Windows absolute path (`D:\coder\...`) became `"hf-ext/D:\\coder\\..."` — and because Node's `path.join` treats a drive-letter prefix as absolute, `join(compileDir, key)` silently escaped `compileDir`. Fix: `toExternalAssetKey()` strips the drive colon and normalises to forward slashes, producing `hf-ext/D/coder/...` — a pure relative path that `path.join` cannot promote to absolute on any OS. Both helpers live in `packages/producer/src/utils/paths.ts` and are exercised by 14 unit tests covering Unix paths, Windows drive-letter paths, mixed separators, sibling-prefix confusion, and `..` traversal. Docs: new "External assets" section in `docs/packages/producer.mdx` describes detection, sanitised keys, and the cross-platform containment invariant. Closes #321.
1 parent 0f4fcbe commit 42e872f

5 files changed

Lines changed: 188 additions & 6 deletions

File tree

‎docs/packages/producer.mdx‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -252,6 +252,30 @@ bun run benchmark
252252

253253
The benchmark runs several compositions with different quality and FPS settings and reports timing for each combination.
254254

255+
## External assets (files outside `projectDir`)
256+
257+
A composition can reference absolute paths to assets outside the project
258+
directory — a local voiceover in `~/Downloads`, a shared-drive image, a
259+
generated fixture at an absolute path. The producer handles these by:
260+
261+
1. **Detection.** During compilation, the HTML compiler walks every
262+
`[src]` / `[href]` and every `url(...)` in `<style>`. A path that
263+
resolves to a file outside `projectDir` is collected into an
264+
`externalAssets` map.
265+
2. **Sanitised keys.** Each absolute path is converted into a safe,
266+
cross-platform relative key prefixed with `hf-ext/`. Windows
267+
drive-letter colons are stripped (`D:\foo\x.wav` → `hf-ext/D/foo/x.wav`)
268+
so that `path.join(compileDir, key)` stays inside the compile
269+
directory on every OS.
270+
3. **Copy + rewrite.** The orchestrator copies the file under
271+
`<compileDir>/hf-ext/...` and the HTML is rewritten to point at the
272+
sanitised key. The file server then serves both project-internal and
273+
external assets from the same root.
274+
275+
The containment check uses `path.relative()` rather than a hardcoded
276+
separator, so external assets work identically on macOS, Linux, and
277+
Windows. See `packages/producer/src/utils/paths.ts` for the helpers.
278+
255279
## Related Packages
256280

257281
<CardGroup cols={2}>

‎packages/producer/src/services/htmlCompiler.ts‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ import {
2424
rewriteCssAssetUrls,
2525
} from "@hyperframes/core";
2626
import { extractVideoMetadata, extractAudioMetadata } from "../utils/ffprobe.js";
27+
import { isPathInside, toExternalAssetKey } from "../utils/paths.js";
2728
import {
2829
parseVideoElements,
2930
type VideoElement,
@@ -804,12 +805,14 @@ export function collectExternalAssets(
804805
return null;
805806
}
806807
const absPath = resolve(absProjectDir, trimmed);
807-
if (absPath.startsWith(absProjectDir + "/") || absPath === absProjectDir) {
808+
if (isPathInside(absPath, absProjectDir)) {
808809
return null; // inside projectDir, file server handles this
809810
}
810811
if (!existsSync(absPath)) return null;
811-
// resolve() already canonicalizes the path (no .. components remain)
812-
const safeKey = "hf-ext/" + absPath.replace(/^\//, "");
812+
// resolve() already canonicalises the path (no .. components remain);
813+
// toExternalAssetKey() produces a cross-platform relative key that
814+
// `path.join(compileDir, key)` cannot escape on any OS.
815+
const safeKey = toExternalAssetKey(absPath);
813816
externalAssets.set(safeKey, absPath);
814817
return safeKey;
815818
}

‎packages/producer/src/services/renderOrchestrator.ts‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@ import {
6868
type CompiledComposition,
6969
} from "./htmlCompiler.js";
7070
import { defaultLogger, type ProducerLogger } from "../logger.js";
71+
import { isPathInside } from "../utils/paths.js";
7172

7273
/**
7374
* Wrap a cleanup operation so it never throws, but logs any failure.
@@ -263,10 +264,13 @@ function writeCompiledArtifacts(
263264
}
264265

265266
// Copy external assets (files outside projectDir) into the compiled directory
266-
// so the file server can serve them.
267+
// so the file server can serve them. The safe-path check uses
268+
// `isPathInside()` rather than a hardcoded separator — on Windows,
269+
// `compileDir + "/"` never matches because paths use `\\`, which caused
270+
// every external asset to be wrongly rejected as "unsafe" (see GH #321).
267271
for (const [relativePath, absolutePath] of compiled.externalAssets) {
268272
const outPath = resolve(join(compileDir, relativePath));
269-
if (!outPath.startsWith(compileDir + "/")) {
273+
if (!isPathInside(outPath, compileDir)) {
270274
console.warn(`[Render] Skipping external asset with unsafe path: ${relativePath}`);
271275
continue;
272276
}
Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
/**
2+
* Cross-platform containment + external-asset-key tests.
3+
*
4+
* Regression coverage for GH #321 — on Windows, every external asset was
5+
* wrongly rejected as "unsafe path" because the containment check used
6+
* `startsWith(parent + "/")` and the safe key carried a drive-letter
7+
* colon that made the downstream `path.join` absolute.
8+
*
9+
* We exercise both OS layouts by posing the hypothetical paths the
10+
* respective platforms would generate — the logic itself is expressed
11+
* using `path.relative()` so it works regardless of the runtime OS.
12+
*/
13+
14+
import { describe, expect, it } from "vitest";
15+
import { resolve } from "node:path";
16+
17+
import { isPathInside, toExternalAssetKey } from "./paths.js";
18+
19+
describe("isPathInside", () => {
20+
it("returns true when child is directly inside parent", () => {
21+
expect(isPathInside(resolve("/foo/bar/baz.wav"), resolve("/foo/bar"))).toBe(true);
22+
});
23+
24+
it("returns true when child is deeply nested inside parent", () => {
25+
expect(isPathInside(resolve("/foo/bar/a/b/c/d.wav"), resolve("/foo/bar"))).toBe(true);
26+
});
27+
28+
it("returns true when child equals parent (a dir contains itself)", () => {
29+
expect(isPathInside(resolve("/foo/bar"), resolve("/foo/bar"))).toBe(true);
30+
});
31+
32+
it("returns false when child is a sibling whose name starts with parent", () => {
33+
// Regression: the old `startsWith(parent + "/")` accidentally worked for
34+
// this case, but a naive rewrite without the trailing separator would
35+
// admit `/foo/bar-sibling` as a child of `/foo/bar`. Verify we don't.
36+
expect(isPathInside(resolve("/foo/bar-sibling/x"), resolve("/foo/bar"))).toBe(false);
37+
});
38+
39+
it("returns false when child is outside parent", () => {
40+
expect(isPathInside(resolve("/tmp/evil/file.wav"), resolve("/foo/bar"))).toBe(false);
41+
});
42+
43+
it("returns false when child resolves above parent via ..", () => {
44+
expect(isPathInside(resolve("/foo/bar/../../etc/passwd"), resolve("/foo/bar"))).toBe(false);
45+
});
46+
47+
it("normalises trailing slashes on parent", () => {
48+
expect(isPathInside(resolve("/foo/bar/baz"), resolve("/foo/bar/"))).toBe(true);
49+
});
50+
});
51+
52+
describe("toExternalAssetKey", () => {
53+
it("prefixes with hf-ext/ and keeps a Unix absolute path", () => {
54+
expect(toExternalAssetKey("/Users/miguel/assets/segment.wav")).toBe(
55+
"hf-ext/Users/miguel/assets/segment.wav",
56+
);
57+
});
58+
59+
it("converts Windows drive-letter paths to a colonless, slash-delimited key", () => {
60+
// GH #321: `D:\coder\reactGin\hyperframes\reading\assets\segment_001.wav`
61+
// used to become `hf-ext/D:\coder\...`, which makes the downstream
62+
// `path.join(compileDir, key)` absolute on Windows (drive letter wins).
63+
expect(
64+
toExternalAssetKey("D:\\coder\\reactGin\\hyperframes\\reading\\assets\\segment_001.wav"),
65+
).toBe("hf-ext/D/coder/reactGin/hyperframes/reading/assets/segment_001.wav");
66+
});
67+
68+
it("handles Windows paths with forward slashes (mixed separators)", () => {
69+
expect(toExternalAssetKey("C:/Users/Alice/Downloads/clip.mp4")).toBe(
70+
"hf-ext/C/Users/Alice/Downloads/clip.mp4",
71+
);
72+
});
73+
74+
it("lowercases / uppercases drive letters faithfully (we don't munge)", () => {
75+
expect(toExternalAssetKey("e:\\data\\a.wav")).toBe("hf-ext/e/data/a.wav");
76+
expect(toExternalAssetKey("Z:\\data\\a.wav")).toBe("hf-ext/Z/data/a.wav");
77+
});
78+
79+
it("is idempotent for already-sanitised input", () => {
80+
// If someone double-wraps, the result is still a safe relative key.
81+
// The drive-letter detector only fires on the first char class.
82+
const once = toExternalAssetKey("/foo/bar.mp3");
83+
const twice = toExternalAssetKey(once);
84+
expect(twice.startsWith("hf-ext/")).toBe(true);
85+
expect(twice).not.toContain(":");
86+
expect(twice).not.toContain("\\");
87+
});
88+
89+
it("keeps UNIX paths stable after an extra leading slash", () => {
90+
expect(toExternalAssetKey("//foo/bar.mp3")).toBe("hf-ext/foo/bar.mp3");
91+
});
92+
93+
it("produces a key that path.join(compileDir, key) keeps inside compileDir", () => {
94+
// The real failure mode from #321: on Windows, join(compileDir, key) with
95+
// a key containing a drive letter silently escaped compileDir. Our key
96+
// must be a pure relative path — no `:`, no leading separator — so
97+
// `isPathInside(join(compileDir, key), compileDir)` is always true.
98+
const key = toExternalAssetKey("D:\\evil\\x.wav");
99+
// Key cannot start with a separator or drive letter.
100+
expect(key.startsWith("/")).toBe(false);
101+
expect(/^[A-Za-z]:/.test(key)).toBe(false);
102+
});
103+
});

‎packages/producer/src/utils/paths.ts‎

Lines changed: 49 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
* Path resolution utilities for the render pipeline.
33
*/
44

5-
import { resolve, basename, join } from "node:path";
5+
import { resolve, basename, join, relative, isAbsolute } from "node:path";
66

77
export interface RenderPaths {
88
absoluteProjectDir: string;
@@ -13,6 +13,54 @@ const DEFAULT_RENDERS_DIR =
1313
process.env.PRODUCER_RENDERS_DIR ??
1414
resolve(new URL(import.meta.url).pathname, "../../..", "renders");
1515

16+
/**
17+
* Cross-platform containment check.
18+
*
19+
* `child.startsWith(parent + "/")` breaks on Windows because the path
20+
* separator is `\`, not `/`. This helper uses `path.relative()` which
21+
* normalises separators per-platform and returns `..`-prefixed output
22+
* for out-of-tree paths — the canonical way to ask "is `child` inside
23+
* `parent`?" on every supported OS.
24+
*
25+
* Both inputs are normalised via `resolve()` so callers don't need to.
26+
* Equality counts as "inside" (a directory contains itself).
27+
*/
28+
export function isPathInside(childPath: string, parentPath: string): boolean {
29+
const absChild = resolve(childPath);
30+
const absParent = resolve(parentPath);
31+
if (absChild === absParent) return true;
32+
const rel = relative(absParent, absChild);
33+
// `relative()` returns "" when paths are equal, ".." or "..\\foo" when child
34+
// is above the parent, and an absolute path when they live on different
35+
// drives/volumes (Windows) — none of which count as "inside".
36+
return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
37+
}
38+
39+
/**
40+
* Build a safe, cross-platform relative key for an absolute asset path
41+
* that lives outside the project directory.
42+
*
43+
* Windows absolute paths (`D:\coder\assets\segment.wav`) break two
44+
* downstream assumptions when passed as-is to `path.join(compileDir, key)`:
45+
* 1. The drive letter makes the path absolute, so `join()` silently
46+
* discards `compileDir`.
47+
* 2. The backslashes and colon are invalid inside some OS sandboxes
48+
* and HTTP URL encodings.
49+
*
50+
* We sanitise into `hf-ext/<drive>/<path>` form using forward slashes
51+
* and stripping the colon after the drive letter. The result is a pure
52+
* relative path that joins cleanly on every platform.
53+
*/
54+
export function toExternalAssetKey(absPath: string): string {
55+
// Normalise to forward slashes first.
56+
let normalised = absPath.replace(/\\/g, "/");
57+
// Strip a leading forward slash (Unix absolute).
58+
normalised = normalised.replace(/^\/+/, "");
59+
// Strip a leading drive-letter colon (Windows: "D:/coder" → "D/coder").
60+
normalised = normalised.replace(/^([A-Za-z]):\/?/, "$1/");
61+
return "hf-ext/" + normalised;
62+
}
63+
1664
export function resolveRenderPaths(
1765
projectDir: string,
1866
outputPath: string | null | undefined,

0 commit comments

Comments
 (0)