fix(cli): handle encoded lint asset paths

miguel-heygen · miguel-heygen · commit 526709cad219 · 2026-05-24T16:31:45.000-04:00
diff --git a/packages/cli/src/utils/lintProject.test.ts b/packages/cli/src/utils/lintProject.test.ts
@@ -1,14 +1,12 @@
 import { describe, it, expect, afterEach } from "vitest";
-import { mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { mkdirSync, mkdtempSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { lintProject, shouldBlockRender } from "./lintProject.js";
 import type { ProjectDir } from "./project.js";
 
 function tmpProject(name: string): string {
-  const dir = join(tmpdir(), `hf-test-${name}-${Date.now()}`);
-  mkdirSync(dir, { recursive: true });
-  return dir;
+  return mkdtempSync(join(tmpdir(), `hf-test-${name}-`));
 }
 
 function validHtml(compId = "main"): string {
@@ -182,6 +180,29 @@ function validHtmlWithAudio(compId = "main"): string {
 </body></html>`;
 }
 
+function validHtmlWithAudioSrc(src: string): string {
+  return `<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080">
+    <audio id="music" src="${src}" data-start="0" data-track-index="0" data-volume="1"></audio>
+  </div>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+}
+
+function validHtmlWithMaskImageUrl(url: string): string {
+  return `<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080">
+    <div class="hf-texture-text hf-texture-lava">TEXT</div>
+  </div>
+  <style>
+    .hf-texture-lava {
+      mask-image: url("${url}");
+    }
+  </style>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+}
+
 describe("audio_file_without_element", () => {
   it("warns when audio file exists but no <audio> element", () => {
     const project = makeProject(validHtml());
@@ -333,13 +354,7 @@ describe("audio_src_not_found", () => {
   it("does not error for percent-encoded non-Latin filenames that exist on disk", () => {
     const encodedFilename =
       "%D9%87%D9%86%D8%A7%20%D9%85%D8%B1%D9%88%D8%A7%20-%20%D9%85%D8%A8%D8%A7%D8%B1%D9%83.mp4";
-    const html = `<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080">
-    <audio id="music" src="assets/${encodedFilename}" data-start="0" data-track-index="0" data-volume="1"></audio>
-  </div>
-  <script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
-</body></html>`;
-    const project = makeProject(html);
+    const project = makeProject(validHtmlWithAudioSrc(`assets/${encodedFilename}`));
     mkdirSync(join(project.dir, "assets"), { recursive: true });
     writeFileSync(join(project.dir, "assets", decodeURIComponent(encodedFilename)), "fake");
 
@@ -351,6 +366,31 @@ describe("audio_src_not_found", () => {
     expect(finding).toBeUndefined();
   });
 
+  it("does not error for malformed percent sequences that are literal filenames", () => {
+    const filename = "100%-discount.mp4";
+    const project = makeProject(validHtmlWithAudioSrc(`assets/${filename}`));
+    mkdirSync(join(project.dir, "assets"), { recursive: true });
+    writeFileSync(join(project.dir, "assets", filename), "fake");
+
+    const { results } = lintProject(project);
+
+    const first = results[0];
+    expect(first).toBeDefined();
+    const finding = first?.result.findings.find((f) => f.code === "audio_src_not_found");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does not treat decoded traversal as an existing file outside the project", () => {
+    const project = makeProject(
+      validHtmlWithAudioSrc("assets/foo/%2E%2E/%2E%2E/%2E%2E/etc/passwd"),
+    );
+
+    const { results } = lintProject(project);
+
+    const finding = results[0]?.result.findings.find((f) => f.code === "audio_src_not_found");
+    expect(finding).toBeDefined();
+  });
+
   it("deduplicates missing files across compositions", () => {
     const project = makeProject(validHtmlWithAudio(), {
       "captions.html": validHtmlWithAudio("captions"),
@@ -514,6 +554,33 @@ describe("texture_mask_asset_not_found", () => {
 
     expect(finding).toBeUndefined();
   });
+
+  it("does not error for percent-encoded non-Latin mask filenames that exist on disk", () => {
+    const encodedFilename = "%E6%97%A5%E6%9C%AC%E8%AA%9E.png";
+    const project = makeProject(validHtmlWithMaskImageUrl(`assets/${encodedFilename}`));
+    mkdirSync(join(project.dir, "assets"), { recursive: true });
+    writeFileSync(join(project.dir, "assets", decodeURIComponent(encodedFilename)), "fake");
+
+    const { results } = lintProject(project);
+    const finding = results[0]?.result.findings.find(
+      (item) => item.code === "texture_mask_asset_not_found",
+    );
+
+    expect(finding).toBeUndefined();
+  });
+
+  it("does not treat decoded mask traversal as an existing file outside the project", () => {
+    const project = makeProject(
+      validHtmlWithMaskImageUrl("assets/foo/%2E%2E/%2E%2E/%2E%2E/etc/passwd"),
+    );
+
+    const { results } = lintProject(project);
+    const finding = results[0]?.result.findings.find(
+      (item) => item.code === "texture_mask_asset_not_found",
+    );
+
+    expect(finding).toBeDefined();
+  });
 });
 
 describe("multiple_root_compositions", () => {
diff --git a/packages/cli/src/utils/lintProject.ts b/packages/cli/src/utils/lintProject.ts
@@ -1,8 +1,8 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { dirname, join, resolve, extname } from "node:path";
+import { dirname, extname, isAbsolute, join, posix, relative, resolve } from "node:path";
 import { lintHyperframeHtml, type HyperframeLintResult } from "@hyperframes/core/lint";
 import type { HyperframeLintFinding } from "@hyperframes/core/lint";
-import { rewriteAssetPath } from "@hyperframes/core";
+import { decodeUrlPathVariants, rewriteAssetPath } from "@hyperframes/core";
 import type { ProjectDir } from "./project.js";
 
 /**
@@ -113,31 +113,53 @@ function cleanAssetUrl(url: string): string {
   return url.trim().split(/[?#]/, 1)[0] ?? "";
 }
 
+function isWithinProjectRoot(projectDir: string, candidate: string): boolean {
+  const projectRoot = resolve(projectDir);
+  const relativePath = relative(projectRoot, candidate);
+  return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
+}
+
+function addCandidate(candidates: string[], candidate: string): void {
+  if (!candidates.includes(candidate)) candidates.push(candidate);
+}
+
 function resolveLocalAssetCandidates(projectDir: string, url: string): string[] {
   const cleanUrl = cleanAssetUrl(url);
-  const variants = [cleanUrl];
-  try {
-    const decodedUrl = decodeURIComponent(cleanUrl);
-    if (decodedUrl !== cleanUrl) variants.unshift(decodedUrl);
-  } catch {
-    // Malformed percent sequences can be literal filenames.
+  const projectRoot = resolve(projectDir);
+  const candidates: string[] = [];
+
+  for (const variant of decodeUrlPathVariants(cleanUrl)) {
+    const projectRelative = variant.startsWith("/") ? variant.slice(1) : variant;
+    const resolved = resolve(projectRoot, projectRelative);
+    if (isWithinProjectRoot(projectRoot, resolved)) {
+      addCandidate(candidates, resolved);
+      continue;
+    }
+
+    const normalized = posix.normalize(projectRelative.replace(/\\/g, "/"));
+    const clamped = normalized.replace(/^(\.\.\/)+/, "");
+    if (clamped && !clamped.startsWith("..")) {
+      addCandidate(candidates, resolve(projectRoot, clamped));
+    }
   }
 
-  return [...new Set(variants)].map((variant) =>
-    variant.startsWith("/") ? resolve(projectDir, variant.slice(1)) : resolve(projectDir, variant),
-  );
+  return candidates;
 }
 
-function resolveCssAssetPath(
+function resolveCssAssetCandidates(
   projectDir: string,
   url: string,
   htmlCompSrcPath?: string,
   cssRootRelativePath?: string,
-): string {
-  if (url.startsWith("/")) return resolve(projectDir, url.slice(1));
-  if (cssRootRelativePath) return resolve(projectDir, join(dirname(cssRootRelativePath), url));
-  if (htmlCompSrcPath) return resolve(projectDir, rewriteAssetPath(htmlCompSrcPath, url));
-  return resolve(projectDir, url);
+): string[] {
+  if (url.startsWith("/")) return resolveLocalAssetCandidates(projectDir, url);
+  if (cssRootRelativePath) {
+    return resolveLocalAssetCandidates(projectDir, join(dirname(cssRootRelativePath), url));
+  }
+  if (htmlCompSrcPath) {
+    return resolveLocalAssetCandidates(projectDir, rewriteAssetPath(htmlCompSrcPath, url));
+  }
+  return resolveLocalAssetCandidates(projectDir, url);
 }
 
 /**
@@ -318,14 +340,14 @@ function lintTextureMaskAssetNotFound(
         if (!url || isRemoteOrInlineUrl(url)) continue;
         if (/^__[A-Z_]+__$/.test(url)) continue;
 
-        const resolved = resolveCssAssetPath(
+        const candidates = resolveCssAssetCandidates(
           projectDir,
           url,
           compSrcPath,
           cssSource.rootRelativePath,
         );
-        if (existsSync(resolved)) continue;
-        missing.set(url, resolved);
+        if (candidates.some(existsSync)) continue;
+        missing.set(url, candidates[0] ?? resolve(projectDir, url));
       }
     }
   }
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -137,6 +137,7 @@ export {
   rewriteAssetPath,
   rewriteCssAssetUrls,
 } from "./compiler/rewriteSubCompPaths";
+export { decodeUrlPathVariants } from "./utils/urlPath";
 
 // Inline scripts
 export {
diff --git a/packages/core/src/utils/urlPath.ts b/packages/core/src/utils/urlPath.ts
@@ -0,0 +1,11 @@
+export function decodeUrlPathVariants(path: string): string[] {
+  const variants = [path];
+  try {
+    const decoded = decodeURIComponent(path);
+    if (decoded !== path) variants.unshift(decoded);
+  } catch {
+    // Malformed percent sequences may be literal filesystem names.
+  }
+
+  return variants;
+}
diff --git a/packages/engine/src/services/videoFrameExtractor.test.ts b/packages/engine/src/services/videoFrameExtractor.test.ts
@@ -156,6 +156,16 @@ describe("resolveProjectRelativeSrc — sub-composition path clamping", () => {
       );
     }
   });
+
+  it("falls back to literal filenames when percent sequences are malformed", () => {
+    const projectDir = join(tmp, "project");
+    const filename = "100%-discount.mp4";
+    writeFileSync(join(projectDir, "assets", filename), "");
+
+    expect(resolveProjectRelativeSrc(`assets/${filename}`, projectDir)).toBe(
+      join(projectDir, "assets", filename),
+    );
+  });
 });
 
 describe("parseVideoElements", () => {
diff --git a/packages/engine/src/services/videoFrameExtractor.ts b/packages/engine/src/services/videoFrameExtractor.ts
@@ -9,6 +9,7 @@ import { spawn } from "child_process";
 import { existsSync, mkdirSync, readdirSync, rmSync } from "fs";
 import { isAbsolute, join, posix, resolve, sep } from "path";
 import { parseHTML } from "linkedom";
+import { decodeUrlPathVariants } from "@hyperframes/core";
 import { trackChildProcess } from "../utils/processTracker.js";
 import { extractMediaMetadata, type VideoMetadata } from "../utils/ffprobe.js";
 import {
@@ -518,19 +519,11 @@ export function resolveProjectRelativeSrc(
   const cleanSrc = qIdx >= 0 ? src.slice(0, qIdx) : src;
   const candidates: string[] = [];
 
-  const srcVariants = [cleanSrc];
-  try {
-    const decodedSrc = decodeURIComponent(cleanSrc);
-    if (decodedSrc !== cleanSrc) srcVariants.unshift(decodedSrc);
-  } catch {
-    // Keep malformed percent sequences as literal filenames.
-  }
-
   const addCandidate = (candidate: string): void => {
     if (!candidates.includes(candidate)) candidates.push(candidate);
   };
 
-  for (const variant of srcVariants) {
+  for (const variant of decodeUrlPathVariants(cleanSrc)) {
     const fromCompiled = compiledDir ? join(compiledDir, variant) : null;
     const fromBase = join(baseDir, variant);
 
