import { resolve, sep, join, dirname, basename, relative, isAbsolute } from "node:path"; import { lstatSync, mkdirSync, realpathSync, statSync } from "node:fs"; export function realpath(path: string): string { try { return realpathSync.native(path); } catch (error) { // Some Windows volumes (RAM disks) refuse the native call with EISDIR. if ((error as NodeJS.ErrnoException).code === "EISDIR") return realpathSync(path); throw error; } } // realpath also fails for dangling/cyclic symlinks. Existing entries must not // become missing segments: writes could follow them outside the project. function isMissingPath(path: string): boolean { try { lstatSync(path); return false; } catch (error) { return Boolean( error && typeof error === "object" && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR"), ); } } /** * Reject paths that escape the `base` directory — including via symlinks. * * `path.resolve()` collapses `.`/`..` but does NOT dereference symlinks, so a * plain prefix check (`resolved.startsWith(base + sep)`) can be defeated by a * symlink that lives *inside* `base` but points outside it (e.g. * `base/link -> /etc`). A downstream `readFileSync`/`writeFileSync`/`statSync` * then follows that link to a file outside `base`. To close this we canonicalize * both sides with `realpathSync.native` (the on-disk letter case too) before comparing. * * The target may not exist yet (e.g. creating a new file), so we canonicalize the * deepest *existing* ancestor and re-attach the trailing not-yet-existing * segments. Segments that don't exist cannot be symlinks at check time, so they * can't redirect the path outside `base` right now. (A symlink swapped in between * this check and the subsequent fs call is an inherent TOCTOU race this helper * does not, and cannot by itself, defend against.) * * Lives at the package root rather than under `studio-api/` because callers span * layers — `studio-api` routes, the `compiler`, the CLI, and the engine — and * `compiler` sits below `studio-api` in the dependency graph, so it cannot import * from there without a backwards edge. */ export function isSafePath(base: string, resolved: string): boolean { let baseReal: string; try { baseReal = realpath(resolve(base)); } catch { // Base must exist and be resolvable; fail closed if not. return false; } const target = resolve(resolved); const trailing: string[] = []; let probe = target; for (;;) { let ancestorReal: string; try { ancestorReal = realpath(probe); } catch { if (!isMissingPath(probe)) return false; const parent = dirname(probe); if (parent === probe) return false; // walked past the filesystem root trailing.push(basename(probe)); probe = parent; continue; } // Copy before reverse(): the array is only consumed once today, but a future // edit that loops would otherwise silently misorder the rebuilt segments. const targetReal = trailing.length ? join(ancestorReal, ...[...trailing].reverse()) : ancestorReal; return targetReal === baseReal || targetReal.startsWith(baseReal + sep); } } /** * Resolve `relativePath` against `base` and return the absolute path only if it * stays within `base` (after symlink resolution); otherwise return `null`. * * Prefer this over a bare `resolve()` followed by a separate `isSafePath()` * check: collapsing the two into one call means a caller cannot resolve a * project-relative path and then forget the containment guard — the gap that * let the symlink-escape slip past several call sites historically. */ export function resolveWithinProject(base: string, relativePath: string): string | null { const resolved = resolve(base, relativePath); return isSafePath(base, resolved) ? resolved : null; } /** The project folder is gone, renamed or deleted while open; a write must not bring it back. */ export class ProjectRootMissingError extends Error { constructor(readonly root: string) { super(`Project folder not found: ${root}`); this.name = "ProjectRootMissingError"; } } // By name, so a copy of this module bundled into another package still matches. export const isProjectRootMissing = (error: unknown): boolean => error instanceof Error && error.name === "ProjectRootMissingError"; /** True only when nothing is at `dir` any more; a folder that cannot be looked at (EACCES, EIO) is not gone. */ export function folderGone(dir: string): boolean { try { return !statSync(dir, { throwIfNoEntry: false }); } catch { return false; } } /** The project folder's real path; ProjectRootMissingError when it is gone. */ export function realProjectRoot(root: string): string { try { return realpath(root); } catch (error) { if (folderGone(root)) throw new ProjectRootMissingError(root); throw error; } } /** * Creates `dir` below `root` one folder at a time, so a root moved away fails instead of reappearing. * A `dir` outside `root` is created recursively, but only while `root` exists. */ export function mkdirWithinProject(root: string, dir: string): void { if (folderGone(root)) throw new ProjectRootMissingError(root); const inside = relative(resolve(root), resolve(dir)); if (inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside)) { mkdirSync(dir, { recursive: true }); return; } let path = resolve(root); for (const part of inside.split(sep).filter(Boolean)) { path = join(path, part); try { mkdirSync(path); } catch (error) { const code = (error as NodeJS.ErrnoException).code; if (code === "ENOENT" && folderGone(root)) throw new ProjectRootMissingError(root); if (code !== "EEXIST") throw error; } } }