diff --git a/packages/cli/src/registry/installer.test.ts b/packages/cli/src/registry/installer.test.ts index 142a5e0462..d486d677eb 100644 --- a/packages/cli/src/registry/installer.test.ts +++ b/packages/cli/src/registry/installer.test.ts @@ -121,6 +121,12 @@ describe("installItem", () => { "index.html", "src/index.js", "scripts\\postinstall.js", + "lib/package.json", + "compositions/pnpm-lock.yaml", + "lib/tsconfig.json", + "lib/vite.config.ts", + "compositions/Makefile", + "lib/AGENTS.md::$DATA", ])("refuses the install target %s before writing anything", async (planted) => { const dir = project(); const hostile = { ...item, files: [{ ...item.files[0]!, target: planted }] }; diff --git a/packages/cli/src/registry/installer.ts b/packages/cli/src/registry/installer.ts index 16a96f275e..dcc4a6b380 100644 --- a/packages/cli/src/registry/installer.ts +++ b/packages/cli/src/registry/installer.ts @@ -13,6 +13,7 @@ import { createHash } from "node:crypto"; import { existsSync, readFileSync } from "node:fs"; import { resolve, relative, isAbsolute } from "node:path"; import type { FileTarget, RegistryItem } from "@hyperframes/core"; +import { toolTrustedFileKind, type ToolTrustedKind } from "@hyperframes/core/safe-path"; import { fetchItemFile, DEFAULT_REGISTRY_URL } from "./remote.js"; import { applyVariableDefaults, @@ -136,10 +137,9 @@ function keptByProject( return !force && existsSync(destPath) && hasLocalEdits(record, target, readFileSync(destPath)); } -// Project and tool configuration is never registry content: VCS metadata, package-manager and -// agent or editor settings are executed or trusted by other tools. Only an example (a fresh `init`) -// may bring its own package.json and HyperFrames config. -const PROJECT_FILES = new Set(["package.json", "hyperframes.json", "hyperframes.lock.json"]); +// Project and tool configuration is never registry content: VCS metadata, package-manager and agent or editor settings +// are executed or trusted by other tools. Core's `toolTrustedFileKind` names the files other tools run or trust, the same +// rule Studio's write routes apply. Only an example (a fresh `init`) may bring its own package.json and HyperFrames config. const EXAMPLE_DOTFILES = new Set([".gitignore"]); // A Windows short name such as `CLAUDE~1` or `PACKAG~1.JSO` can open any long name on NTFS. @@ -151,12 +151,6 @@ const isShortName = (part: string): boolean => /~\d+(\.|$)/.test(part); const STANDARD_INSTALL_DIRS = ["compositions", "assets", "models", "lib"]; // The one file a block may leave at the project root: the catalog's usage note. Any other name could be one a tool loads. const ROOT_NOTES = new Set(["template.md"]); -// Coding agents load these on their own, wherever they sit. -const AGENT_INSTRUCTIONS = - /^(agents?|claude|gemini|qwen|crush|warp|conventions|copilot-instructions)(\.[a-z]+)?\.md$/; -// Programs and scripts a shell, an OS or another tool runs; a browser composition never needs them. -const EXECUTABLE = - /\.(exe|com|bat|cmd|ps1|psm1|vbs|vbe|wsf|hta|msi|scr|pif|cpl|lnk|dll|so|dylib|node|sh|bash|zsh|command|jar|appimage|py|rb|pl|php)$/; function withoutTrailingDotsOrSpaces(part: string): string { let end = part.length; @@ -205,12 +199,16 @@ type TargetRule = [ file: string, example: boolean, installDirs: string[][] | null, + trusted: ToolTrustedKind | null, ) => boolean, ]; const CONFIG_TARGET_RULES: TargetRule[] = [ ["it writes into git metadata", (dirs, file) => [...dirs, file].includes(".git")], - ["it uses a Windows short name", (dirs, file) => [...dirs, file].some(isShortName)], + [ + "it uses a Windows short name", + (_dirs, _file, _example, _installDirs, trusted) => trusted === "short-name", + ], ["it writes into a hidden tool directory", (dirs) => dirs.some((dir) => dir.startsWith("."))], [ "it writes a hidden configuration file", @@ -218,11 +216,20 @@ const CONFIG_TARGET_RULES: TargetRule[] = [ ], [ "it would replace project configuration", - (_dirs, file, example) => !example && PROJECT_FILES.has(file), + (_dirs, _file, example, _installDirs, trusted) => + (trusted === "project-config" && !example) || + trusted === "lock-file" || + trusted === "tool-config", ], ["it writes into node_modules", (dirs) => dirs.includes("node_modules")], - ["it writes an agent instruction file", (_dirs, file) => AGENT_INSTRUCTIONS.test(file)], - ["it writes a program or script", (_dirs, file) => EXECUTABLE.test(file)], + [ + "it writes an agent instruction file", + (_dirs, _file, _example, _installDirs, trusted) => trusted === "agent-instructions", + ], + [ + "it writes a program or script", + (_dirs, _file, _example, _installDirs, trusted) => trusted === "program", + ], [ "it writes outside the project's blocks, components and assets folders", (dirs, file, example, installDirs) => @@ -242,9 +249,11 @@ function configTargetError( const parts = targetSegments(target); const file = parts.pop() ?? ""; const example = type === "hyperframes:example"; + const trusted = toolTrustedFileKind(target); return ( - CONFIG_TARGET_RULES.find(([, applies]) => applies(parts, file, example, installDirs))?.[0] ?? - null + CONFIG_TARGET_RULES.find(([, applies]) => + applies(parts, file, example, installDirs, trusted), + )?.[0] ?? null ); } diff --git a/packages/core/src/safePath.test.ts b/packages/core/src/safePath.test.ts index a991c7e5fd..577a272cc4 100644 --- a/packages/core/src/safePath.test.ts +++ b/packages/core/src/safePath.test.ts @@ -17,6 +17,7 @@ import { isStudioPrivatePath, mkdirWithinProject, resolveWithinProject, + toolTrustedFileKind, } from "./safePath.js"; const recased = (path: string) => join(dirname(path), basename(path).toUpperCase()); @@ -323,3 +324,66 @@ describe("isStudioPrivatePath", () => { expect(isStudioPrivatePath(path)).toBe(false); }); }); + +describe("toolTrustedFileKind", () => { + it.each([ + ["package.json", "project-config"], + ["sub/Package.JSON", "project-config"], + ["hyperframes.json.", "project-config"], + ["hyperframes.lock.json", "project-config"], + ["package.json::$DATA", "project-config"], + ["pnpm-lock.yaml", "lock-file"], + ["nested/yarn.lock", "lock-file"], + ["bun.lockb ", "lock-file"], + ["tsconfig.json", "tool-config"], + ["Makefile", "tool-config"], + ["vite.config.ts", "tool-config"], + ["lib/eslint.config.mjs", "tool-config"], + ["AGENTS.md", "agent-instructions"], + ["deep/sub\\CLAUDE.local.md", "agent-instructions"], + ["compositions/gemini.md", "agent-instructions"], + ["scripts/postinstall.sh", "program"], + ["tools/run.PY", "program"], + ["assets/app.exe", "program"], + ["PACKAG~1.JSO", "short-name"], + ["CLAUDE~1/notes.md", "short-name"], + ["COPILO~1.MD", "short-name"], + ["AGENT\u017f.md", "agent-instructions"], + ["package.j\u017fon", "project-config"], + ["Make\ufb01le", "tool-config"], + ["run.\u017fh", "program"], + ["\uff50ackage.json", "project-config"], + ["pack\u200bage.json", "project-config"], + ["jest.config.json", "tool-config"], + ["docker-compose.yml", "tool-config"], + ["gulpfile.mjs", "tool-config"], + ["turbo.json", "tool-config"], + ["pyproject.toml", "tool-config"], + ] as const)("names %s %s", (path, kind) => { + expect(toolTrustedFileKind(path)).toBe(kind); + }); + + it("finds an agent file below a folder with a decomposed name", () => { + expect(toolTrustedFileKind("caf\u0065\u0301/AGENTS.md")).toBe("agent-instructions"); + }); + + it.each([ + "index.html", + "compositions/scene.html", + "assets/style.css", + "assets/gsap.min.js", + "lib/scene.mjs", + "assets/data.json", + "assets/logo.svg", + "notes.md", + "README.md", + "compositions/lockup.html", + "assets/package-art.png", + ".hyperframes/studio-motion.json", + "media/take~2.mp4", + "assets/scene~10.png", + "assets/config.json", + ])("leaves %s to the other rules", (path) => { + expect(toolTrustedFileKind(path)).toBeNull(); + }); +}); diff --git a/packages/core/src/safePath.ts b/packages/core/src/safePath.ts index f08aeb60bb..b09d48e802 100644 --- a/packages/core/src/safePath.ts +++ b/packages/core/src/safePath.ts @@ -105,10 +105,17 @@ export function resolveWithinProject(base: string, relativePath: string): string return isSafePath(base, resolved) ? resolved : null; } -/** Segments as Windows opens them: any case, no trailing dots or spaces, no `:stream` suffix. */ +/** + * Segments as a case-insensitive file system or Windows opens them: any case or Unicode form (a long s, a ligature or a + * full-width letter reads as its plain letters, an invisible character is dropped), no trailing dots or spaces, no + * `:stream` suffix. + */ export function projectPathSegments(relPath: string): string[] { return relPath + .normalize("NFKC") + .toUpperCase() .toLowerCase() + .replace(/\p{Default_Ignorable_Code_Point}/gu, "") .split(/[\\/]/) .map((segment) => withoutTrailingDotsOrSpaces(segment.split(":", 1)[0] ?? "")); } @@ -202,6 +209,98 @@ function isStudioOwnFile(path: string): boolean { ); } +// Files another program runs or trusts with the developer's rights: a package manager, a shell, a build or IDE tool, or +// a coding agent. No composition needs one, so registry content never installs one (an example may bring its own +// project configuration) and Studio's write routes never write, rename onto or delete one. +const PROJECT_CONFIG_FILES = new Set(["package.json", "hyperframes.json", "hyperframes.lock.json"]); +const LOCK_FILES = new Set([ + "package-lock.json", + "npm-shrinkwrap.json", + "pnpm-lock.yaml", + "pnpm-workspace.yaml", + "yarn.lock", + "bun.lock", + "bun.lockb", + "deno.lock", +]); +const TOOL_CONFIG_FILES = new Set([ + "tsconfig.json", + "jsconfig.json", + "deno.json", + "deno.jsonc", + "bunfig.toml", + "makefile", + "gnumakefile", + "justfile", + "dockerfile", + "procfile", + "lefthook.yml", + "lefthook.yaml", + "turbo.json", + "nx.json", + "docker-compose.yml", + "docker-compose.yaml", + "compose.yml", + "compose.yaml", + "taskfile.yml", + "taskfile.yaml", + "pyproject.toml", +]); +// Tools load these on their own: vite.config.ts, jest.config.json, docker-compose.yml, gulpfile.js and the like. +const TOOL_CONFIG = + /\.config\.(?:[cm]?[jt]sx?|json5?|ya?ml|toml)$|^(?:gulp|grunt)file\.[cm]?[jt]s$/; +// Coding agents load these on their own, wherever they sit. +const AGENT_INSTRUCTIONS = + /^(agents?|claude|gemini|qwen|crush|warp|conventions|copilot-instructions)(\.[a-z]+)?\.md$/; +// Programs and scripts a shell, an OS or another tool runs; a browser composition never needs them. +const PROGRAM_EXTENSIONS = + "exe com bat cmd ps1 psm1 vbs vbe wsf hta msi scr pif cpl lnk dll so dylib node sh bash zsh command jar appimage py rb pl php".split( + " ", + ); +const PROGRAM = new RegExp(`\\.(?:${PROGRAM_EXTENSIONS.join("|")})$`); +// A Windows short name such as `CLAUDE~1` or `PACKAG~1.JSO` opens a long name on NTFS. Its extension is the first three +// letters of the long one, so `take~2.mp4` cannot stand for any of the files above; a name with none may be a folder. +const SHORT_NAME = /^([^.]{1,6}~\d{1,6})(?:\.([^.]{1,3}))?$/; +const TRUSTED_EXTENSIONS = [ + ...PROGRAM_EXTENSIONS, + ...["json", "jsonc", "json5", "yaml", "yml", "toml", "lock", "lockb", "md"], + ...["js", "mjs", "cjs", "jsx", "ts", "mts", "cts", "tsx"], +]; + +function isShortName(segment: string): boolean { + const match = SHORT_NAME.exec(segment); + if (!match || match[1]!.length > 8) return false; + const extension = match[2]; + return !extension || TRUSTED_EXTENSIONS.some((trusted) => trusted.startsWith(extension)); +} + +/** What makes a file one another program runs or trusts; see `toolTrustedFileKind`. */ +export type ToolTrustedKind = + | "short-name" + | "project-config" + | "lock-file" + | "tool-config" + | "agent-instructions" + | "program"; + +/** + * Why another program runs or trusts the file at a project-relative path, or null for an ordinary project file. The + * path is read in every spelling a case-insensitive file system or Windows opens: any case or Unicode form, either + * separator, trailing dots or spaces, a `:stream` suffix, or a short name for any of these. + */ +export function toolTrustedFileKind(relPath: string): ToolTrustedKind | null { + const segments = projectPathSegments(relPath); + while (segments.length > 1 && segments.at(-1) === "") segments.pop(); + const name = segments.at(-1) ?? ""; + if (segments.some(isShortName)) return "short-name"; + if (PROJECT_CONFIG_FILES.has(name)) return "project-config"; + if (LOCK_FILES.has(name)) return "lock-file"; + if (TOOL_CONFIG_FILES.has(name) || TOOL_CONFIG.test(name)) return "tool-config"; + if (AGENT_INSTRUCTIONS.test(name)) return "agent-instructions"; + if (PROGRAM.test(name)) return "program"; + return null; +} + /** Whether `isPrivate` holds for a file under `projectDir`, spelled as given or with its links resolved. */ export function isPrivateFileUnder( projectDir: string, diff --git a/packages/studio-server/src/helpers/safePath.ts b/packages/studio-server/src/helpers/safePath.ts index 114ca91c28..2e1e348c0b 100644 --- a/packages/studio-server/src/helpers/safePath.ts +++ b/packages/studio-server/src/helpers/safePath.ts @@ -6,6 +6,7 @@ import { projectPathSegments, realpath, resolveWithinProject as resolveInProject, + toolTrustedFileKind, } from "@hyperframes/core/safe-path"; import { RENDER_TEMP_DIR } from "@hyperframes/core/project-folders"; @@ -56,9 +57,9 @@ export function isPrivateProjectFile(projectDir: string, filePath: string): bool const WRITABLE_HIDDEN_FOLDERS = new Set([".hyperframes", ".media"]); -/** Writes refuse the project folder, node_modules, and hidden paths but Studio's records and the media ledger. */ +/** Writes refuse the project folder, node_modules, hidden paths but Studio's records, and `toolTrustedFileKind` files. */ export function isWritableProjectPath(relPath: string): boolean { - if (!relPath || isPrivateProjectPath(relPath)) return false; + if (!relPath || isPrivateProjectPath(relPath) || toolTrustedFileKind(relPath)) return false; const segments = projectPathSegments(relPath); return segments.every( (segment, at) => @@ -72,6 +73,42 @@ export function isWritableProjectFile(projectDir: string, filePath: string): boo return projectRelatives(projectDir, filePath).every(isWritableProjectPath); } +/** + * The first `toolTrustedFileKind` file, `node_modules` or `.git` below `dir`, which a delete or move of the folder + * would take along. Links are not followed. + */ +export function toolTrustedFileWithin(projectDir: string, dir: string): string | null { + return protectedEntryWithin(dir, projectRelativePath(projectDir, dir)); +} + +const PROTECTED_FOLDERS = new Set(["node_modules", ".git"]); + +function protectedEntryWithin(dir: string, rel: string): string | null { + const entries = folderEntries(dir); + if (!entries) return rel || "."; + for (const entry of entries) { + const found = protectedEntry(dir, entry, rel ? `${rel}/${entry.name}` : entry.name); + if (found) return found; + } + return null; +} + +function protectedEntry(dir: string, entry: Dirent, at: string): string | null { + if (!entry.isDirectory()) return toolTrustedFileKind(at) ? at : null; + if (toolTrustedFileKind(at) || PROTECTED_FOLDERS.has(projectPathSegments(entry.name)[0] ?? "")) + return at; + return protectedEntryWithin(join(dir, entry.name), at); +} + +function folderEntries(dir: string): Dirent[] | null { + try { + return readdirSync(dir, { withFileTypes: true }); + } catch (err) { + if (UNREADABLE_DIR_CODES.has((err as NodeJS.ErrnoException).code ?? "")) return null; + throw err; + } +} + export function resolveWritableWithinProject(base: string, relativePath: string): string | null { const resolved = resolveWithinProject(base, relativePath); return resolved && isWritableProjectFile(base, resolved) ? resolved : null; diff --git a/packages/studio-server/src/routes/files.pathSafety.test.ts b/packages/studio-server/src/routes/files.pathSafety.test.ts index 219bc9e9a6..048802ca68 100644 --- a/packages/studio-server/src/routes/files.pathSafety.test.ts +++ b/packages/studio-server/src/routes/files.pathSafety.test.ts @@ -259,6 +259,127 @@ describe("file route containment", () => { }); }); +describe("files other programs run or trust", () => { + const TRUSTED = [ + "package.json", + "Package.JSON", + "hyperframes.json", + "pnpm-lock.yaml", + "tsconfig.json", + "vite.config.ts", + "AGENTS.md", + "compositions/CLAUDE.md", + "deep/nested/GEMINI.md", + "scripts/postinstall.sh", + "tools/run.py", + "PACKAG~1.JSO", + "package.json.", + "AGENT\u017f.md", + "package.j\u017fon", + "run.\u017fh", + "Make\ufb01le", + "jest.config.json", + ]; + const put = (app: Hono, path: string, headers: Record = {}) => + app.request(fileUrl(path), { method: "PUT", headers, body: "planted" }); + + it.each(TRUSTED)("never creates, renames onto or duplicates onto %s", async (path) => { + const { app, project } = fixture(); + expect((await put(app, path, { "If-None-Match": "*" })).status).toBe(403); + expect((await app.request(fileUrl(path), { method: "POST", body: "planted" })).status).toBe( + 403, + ); + const rename = await app.request(fileUrl("inside.txt"), { + method: "PATCH", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ newPath: path }), + }); + expect(rename.status).toBe(403); + expect(existsSync(join(project, path))).toBe(false); + expect(readFileSync(join(project, "inside.txt"), "utf8")).toBe("inside"); + const name = path.split("/").at(-1)!; + const uploaded = await upload(app, "", name); + expect(uploaded.status).toBe(201); + // The route reads a multipart file name as Latin-1, so only an ASCII name arrives as written. + if (/^[\x20-\x7e]+$/.test(name)) expect((await uploaded.json()).skipped).toContain(name); + expect(existsSync(join(project, name))).toBe(false); + }); + + it("never overwrites, deletes or renames the project's own package.json or AGENTS.md", async () => { + const { app, project } = fixture(); + writeFileSync(join(project, "package.json"), '{"name":"mine"}'); + mkdirSync(join(project, "docs")); + writeFileSync(join(project, "docs", "AGENTS.md"), "mine"); + const read = await app.request(fileUrl("package.json")); + expect(read.status).toBe(200); + const overwrite = await put(app, "package.json", { + "If-Match": fileContentVersion('{"name":"mine"}'), + }); + expect(overwrite.status).toBe(403); + expect((await app.request(fileUrl("package.json"), { method: "DELETE" })).status).toBe(403); + const moveAway = await app.request(fileUrl("docs/AGENTS.md"), { + method: "PATCH", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ newPath: "docs/notes.md" }), + }); + expect(moveAway.status).toBe(403); + expect(readFileSync(join(project, "package.json"), "utf8")).toBe('{"name":"mine"}'); + expect(readFileSync(join(project, "docs", "AGENTS.md"), "utf8")).toBe("mine"); + }); + + it("refuses to delete or move a folder that holds one, and still does both for an ordinary folder", async () => { + const { app, project } = fixture(); + mkdirSync(join(project, "tools", "bin"), { recursive: true }); + writeFileSync(join(project, "tools", "bin", "setup.sh"), "echo mine"); + writeFileSync(join(project, "tools", "readme.txt"), "mine"); + expect((await app.request(fileUrl("tools"), { method: "DELETE" })).status).toBe(403); + const move = await app.request(fileUrl("tools"), { + method: "PATCH", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ newPath: "elsewhere" }), + }); + expect(move.status).toBe(403); + expect(readFileSync(join(project, "tools", "bin", "setup.sh"), "utf8")).toBe("echo mine"); + + for (const kept of ["vendor/lib/node_modules", "vendor/.git"]) { + mkdirSync(join(project, kept), { recursive: true }); + expect((await app.request(fileUrl("vendor"), { method: "DELETE" })).status).toBe(403); + rmSync(join(project, kept), { recursive: true }); + } + + mkdirSync(join(project, "scenes")); + writeFileSync(join(project, "scenes", "a.html"), "
"); + const moved = await app.request(fileUrl("scenes"), { + method: "PATCH", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ newPath: "compositions" }), + }); + expect(moved.status).toBe(200); + expect((await app.request(fileUrl("compositions"), { method: "DELETE" })).status).toBe(200); + expect(existsSync(join(project, "compositions"))).toBe(false); + }); + + it("still writes compositions, stylesheets, script assets and uploads", async () => { + const { app, project } = fixture(); + for (const path of [ + "index.html", + "compositions/scene.html", + "assets/style.css", + "assets/scene.js", + "lib/helpers.mjs", + "assets/data.json", + "notes.md", + ]) { + expect((await put(app, path, { "If-None-Match": "*" })).status).toBe(200); + expect(readFileSync(join(project, path), "utf8")).toBe("planted"); + } + expect((await upload(app, "assets")).status).toBe(201); + expect(readFileSync(join(project, "assets", "upload.txt"), "utf8")).toBe("upload bytes"); + expect((await upload(app, "assets", "take~2.txt")).status).toBe(201); + expect(readFileSync(join(project, "assets", "take~2.txt"), "utf8")).toBe("upload bytes"); + }); +}); + describe("resolveProjectPath why", () => { // The CLI host's `resolveProject` is static — it answers with this project // for as long as the server runs, even after its folder is renamed or diff --git a/packages/studio-server/src/routes/files.ts b/packages/studio-server/src/routes/files.ts index 856abf4578..e3d019c95a 100644 --- a/packages/studio-server/src/routes/files.ts +++ b/packages/studio-server/src/routes/files.ts @@ -44,6 +44,7 @@ import { pinWritableWithinProject, resolveWithinProject, resolveWritableWithinProject, + toolTrustedFileWithin, walkDir, } from "../helpers/safePath.js"; import { backupPathForResponse, snapshotBeforeWrite } from "../helpers/backupJournal.js"; @@ -2749,8 +2750,10 @@ async function processUploadedFiles( // The collision suffix chooses a different path; validate that destination // too, including dangling symlinks that existsSync treats as absent. - if (!isSafePath(projectDir, finalPath) || !isWritableProjectFile(projectDir, finalPath)) + if (!isSafePath(projectDir, finalPath) || !isWritableProjectFile(projectDir, finalPath)) { + skipped.push(name); continue; + } const buffer = Buffer.from(await value.arrayBuffer()); const validation = validateUploadedMediaBuffer(finalName, buffer); @@ -3067,6 +3070,9 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void { if ("error" in res) return res.error; const stat = statSync(res.absPath); + if (stat.isDirectory() && toolTrustedFileWithin(res.project.dir, res.absPath)) { + return c.json({ error: "forbidden", why: "protected_path" }, 403); + } const backup = snapshotBeforeWrite(res.project.dir, res.absPath); if (backup.error) return c.json({ error: `backup failed: ${backup.error}` }, 500); if (stat.isDirectory()) { @@ -3766,6 +3772,9 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void { } const isDirectory = statSync(res.absPath, { throwIfNoEntry: false })?.isDirectory() ?? false; + if (isDirectory && toolTrustedFileWithin(res.project.dir, res.absPath)) { + return c.json({ error: "forbidden", why: "protected_path" }, 403); + } ensureDir(res.project.dir, newAbs); renameSync(res.absPath, newAbs);