singularity-forge/web/lib/secure-path.ts

import { existsSync, realpathSync } from "node:fs";
import { dirname, isAbsolute, relative, resolve } from "node:path";

function isWithinRoot(rootRealPath: string, candidateRealPath: string): boolean {
  const rel = relative(rootRealPath, candidateRealPath);
  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
}

/**
 * Validate and resolve a requested path against the given root directory.
 * Returns the resolved absolute path or null if the path is invalid.
 */
export function resolveSecurePath(requestedPath: string, root: string, options: { mustExist?: boolean } = {}): string | null {
  if (requestedPath.startsWith("/") || requestedPath.startsWith("\\")) {
    return null;
  }
  if (requestedPath.includes("..")) {
    return null;
  }

  let rootRealPath: string;
  try {
    rootRealPath = realpathSync.native(root);
  } catch {
    return null;
  }

  const resolved = resolve(rootRealPath, requestedPath);
  const rel = relative(rootRealPath, resolved);
  if (rel.startsWith("..") || isAbsolute(rel)) {
    return null;
  }

  try {
    if (existsSync(resolved)) {
      const targetRealPath = realpathSync.native(resolved);
      if (!isWithinRoot(rootRealPath, targetRealPath)) return null;
    } else {
      if (options.mustExist) return null;
      const parentRealPath = realpathSync.native(dirname(resolved));
      if (!isWithinRoot(rootRealPath, parentRealPath)) return null;
    }
  } catch {
    return null;
  }

  return resolved;
}