@genn-inc/cluebase-cli 0.0.1

package/src/setup-doctor-file-boundary.mjs

@@ -0,0 +1,426 @@
+import { constants } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+import { throwIfSetupDoctorDeadlineExceeded } from "./setup-doctor-deadline.mjs";
+
+// Setup-doctor reads customer-controlled source/configuration files. Keep the
+// cap local to this boundary so every setup-doctor file consumer is bounded by
+// the same one-megabyte limit.
+export const SETUP_DOCTOR_MAX_FILE_BYTES = 1024 * 1024;
+
+const SAFE_OPEN_FLAGS =
+	constants.O_RDONLY |
+	(constants.O_NOFOLLOW ?? 0) |
+	(constants.O_NONBLOCK ?? 0);
+export const SETUP_DOCTOR_FILE_BOUNDARY_ERROR_CODE =
+	"SETUP_DOCTOR_FILE_BOUNDARY";
+export const SETUP_DOCTOR_REPOSITORY_ROOT_ERROR_CODE =
+	"SETUP_DOCTOR_REPOSITORY_ROOT";
+
+const isInside = (root, candidate) => {
+	const relativePath = relative(root, candidate);
+	return (
+		relativePath === "" ||
+		(!relativePath.startsWith("..") && !isAbsolute(relativePath))
+	);
+};
+
+const isPathLike = (value) =>
+	isAbsolute(value) || value.includes("/") || value.includes("\\");
+
+const safeError = (
+	relativePath,
+	reason,
+	code = SETUP_DOCTOR_FILE_BOUNDARY_ERROR_CODE,
+	originalCode = null,
+) => {
+	const error = new Error(
+		`setup-doctor repository file "${relativePath}": ${reason}.`,
+	);
+	error.code = code;
+	error.relativePath = relativePath;
+	if (originalCode) error.originalCode = originalCode;
+	return error;
+};
+
+export const isSetupDoctorFileBoundaryError = (error) =>
+	error?.code === SETUP_DOCTOR_FILE_BOUNDARY_ERROR_CODE ||
+	error?.code === SETUP_DOCTOR_REPOSITORY_ROOT_ERROR_CODE;
+
+const stableStatIdentity = (entry) => {
+	if (
+		entry?.dev === undefined ||
+		entry?.dev === null ||
+		entry?.ino === undefined ||
+		entry?.ino === null
+	) {
+		return null;
+	}
+	return `${entry.dev}:${entry.ino}`;
+};
+
+const normalizePath = ({ repoRoot, path }) => {
+	const rootAbs = resolve(repoRoot);
+	const input = typeof path === "string" ? path : String(path ?? "");
+	if (!input.trim()) throw safeError("<invalid>", "path is empty");
+
+	const rawRelativePath = isAbsolute(input)
+		? relative(rootAbs, resolve(input))
+		: input;
+	const rawParts = rawRelativePath.split(/[\\/]+/).filter(Boolean);
+	if (rawParts.includes("..")) {
+		throw safeError("<outside-repo>", "path escapes the selected repository");
+	}
+
+	const absolutePath = resolve(rootAbs, rawRelativePath);
+	if (!isInside(rootAbs, absolutePath)) {
+		throw safeError("<outside-repo>", "path escapes the selected repository");
+	}
+	const relativePath = relative(rootAbs, absolutePath) || ".";
+	return { rootAbs, absolutePath, relativePath };
+};
+
+const checkedRepository = async (rootAbs, signal) => {
+	try {
+		const rootEntry = await lstat(rootAbs);
+		if (rootEntry.isSymbolicLink()) {
+			throw safeError(".", "selected repository root is a symlink");
+		}
+		if (!rootEntry.isDirectory()) {
+			throw safeError(".", "selected repository root is not a directory");
+		}
+		const rootRealPath = await realpath(rootAbs);
+		return rootRealPath;
+	} catch (error) {
+		throwIfSetupDoctorDeadlineExceeded(signal, error);
+		if (isSetupDoctorFileBoundaryError(error)) throw error;
+		if (error?.code === "ENOENT") {
+			throw safeError(
+				".",
+				"selected repository root cannot be accessed",
+				SETUP_DOCTOR_REPOSITORY_ROOT_ERROR_CODE,
+			);
+		}
+		throw safeError(
+			".",
+			"selected repository root cannot be accessed",
+			SETUP_DOCTOR_REPOSITORY_ROOT_ERROR_CODE,
+		);
+	}
+};
+
+const checkPathComponents = async ({
+	rootAbs,
+	absolutePath,
+	relativePath,
+	signal,
+}) => {
+	const rootRealPath = await checkedRepository(rootAbs, signal);
+	const parts = relativePath === "." ? [] : relativePath.split(/[\\/]+/);
+	let currentPath = rootAbs;
+	let targetEntry = null;
+
+	try {
+		for (const [index, part] of parts.entries()) {
+			currentPath = join(currentPath, part);
+			const entry = await lstat(currentPath);
+			if (entry.isSymbolicLink()) {
+				throw safeError(relativePath, "symlink paths are not allowed");
+			}
+			if (index < parts.length - 1 && !entry.isDirectory()) {
+				throw safeError(relativePath, "a parent path is not a directory");
+			}
+			targetEntry = entry;
+		}
+
+		if (targetEntry === null) targetEntry = await lstat(absolutePath);
+		if (targetEntry.isSymbolicLink()) {
+			throw safeError(relativePath, "symlink paths are not allowed");
+		}
+		const targetRealPath = await realpath(absolutePath);
+		if (!isInside(rootRealPath, targetRealPath)) {
+			throw safeError(
+				relativePath,
+				"resolved path escapes the selected repository",
+			);
+		}
+		return { targetEntry, targetRealPath };
+	} catch (error) {
+		throwIfSetupDoctorDeadlineExceeded(signal, error);
+		if (isSetupDoctorFileBoundaryError(error)) throw error;
+		if (error?.code === "ENOENT") {
+			throw safeError(
+				relativePath,
+				"path cannot be accessed",
+				SETUP_DOCTOR_FILE_BOUNDARY_ERROR_CODE,
+				"ENOENT",
+			);
+		}
+		throw safeError(relativePath, "path cannot be accessed");
+	}
+};
+
+const runBoundaryOperation = async ({
+	relativePath,
+	signal,
+	optional,
+	operation,
+}) => {
+	try {
+		return await operation();
+	} catch (error) {
+		throwIfSetupDoctorDeadlineExceeded(signal, error);
+		if (
+			optional &&
+			(error?.code === "ENOENT" || error?.originalCode === "ENOENT")
+		) {
+			return null;
+		}
+		if (isSetupDoctorFileBoundaryError(error)) throw error;
+		throw safeError(relativePath, "read failed");
+	}
+};
+
+export const readSetupDoctorFile = async ({
+	repoRoot,
+	path,
+	signal,
+	optional = false,
+}) => {
+	const normalized = normalizePath({ repoRoot, path });
+	return runBoundaryOperation({
+		relativePath: normalized.relativePath,
+		signal,
+		optional,
+		operation: async () => {
+			const { targetEntry } = await checkPathComponents({
+				...normalized,
+				signal,
+			});
+			const targetIdentity = stableStatIdentity(targetEntry);
+			if (!targetEntry.isFile()) {
+				throw safeError(
+					normalized.relativePath,
+					"target is not a regular file",
+				);
+			}
+			if (targetIdentity === null) {
+				throw safeError(
+					normalized.relativePath,
+					"target identity is unavailable",
+				);
+			}
+
+			const handle = await open(normalized.absolutePath, SAFE_OPEN_FLAGS);
+			try {
+				const openedEntry = await handle.stat();
+				if (!openedEntry.isFile()) {
+					throw safeError(
+						normalized.relativePath,
+						"opened target is not a regular file",
+					);
+				}
+				const openedIdentity = stableStatIdentity(openedEntry);
+				if (openedIdentity === null) {
+					throw safeError(
+						normalized.relativePath,
+						"opened target identity is unavailable",
+					);
+				}
+				if (openedIdentity !== targetIdentity) {
+					throw safeError(
+						normalized.relativePath,
+						"target changed during read (device/inode mismatch)",
+					);
+				}
+				if (openedEntry.size > SETUP_DOCTOR_MAX_FILE_BYTES) {
+					throw safeError(
+						normalized.relativePath,
+						"file exceeds the size limit",
+					);
+				}
+
+				const buffer = Buffer.allocUnsafe(SETUP_DOCTOR_MAX_FILE_BYTES + 1);
+				let totalBytes = 0;
+				while (totalBytes < buffer.length) {
+					throwIfSetupDoctorDeadlineExceeded(signal);
+					const { bytesRead } = await handle.read({
+						buffer,
+						offset: totalBytes,
+						length: buffer.length - totalBytes,
+						position: totalBytes,
+						signal,
+					});
+					totalBytes += bytesRead;
+					if (bytesRead === 0) break;
+				}
+				if (totalBytes > SETUP_DOCTOR_MAX_FILE_BYTES) {
+					throw safeError(
+						normalized.relativePath,
+						"file exceeds the size limit",
+					);
+				}
+				return buffer.subarray(0, totalBytes).toString("utf8");
+			} finally {
+				await handle.close();
+			}
+		},
+	});
+};
+
+export const readSetupDoctorJson = async ({
+	repoRoot,
+	path,
+	signal,
+	optional = false,
+}) => {
+	const content = await readSetupDoctorFile({
+		repoRoot,
+		path,
+		signal,
+		optional,
+	});
+	if (content === null) return null;
+	try {
+		return JSON.parse(content);
+	} catch {
+		const relativePath = normalizePath({ repoRoot, path }).relativePath;
+		throw safeError(relativePath, "file contains invalid JSON");
+	}
+};
+
+export const validateSetupDoctorDirectory = async ({
+	repoRoot,
+	path,
+	signal,
+}) => {
+	const normalized = normalizePath({ repoRoot, path });
+	return runBoundaryOperation({
+		relativePath: normalized.relativePath,
+		signal,
+		optional: false,
+		operation: async () => {
+			const { targetEntry, targetRealPath } = await checkPathComponents({
+				...normalized,
+				signal,
+			});
+			if (!targetEntry.isDirectory()) {
+				throw safeError(normalized.relativePath, "target is not a directory");
+			}
+			return {
+				absolutePath: normalized.absolutePath,
+				relativePath: normalized.relativePath,
+				realPath: targetRealPath,
+			};
+		},
+	});
+};
+
+export const validateSetupDoctorFile = async ({
+	repoRoot,
+	path,
+	signal,
+	optional = false,
+}) => {
+	const normalized = normalizePath({ repoRoot, path });
+	return runBoundaryOperation({
+		relativePath: normalized.relativePath,
+		signal,
+		optional,
+		operation: async () => {
+			const { targetEntry, targetRealPath } = await checkPathComponents({
+				...normalized,
+				signal,
+			});
+			if (!targetEntry.isFile()) {
+				throw safeError(
+					normalized.relativePath,
+					"target is not a regular file",
+				);
+			}
+			const targetIdentity = stableStatIdentity(targetEntry);
+			if (targetIdentity === null) {
+				throw safeError(
+					normalized.relativePath,
+					"target identity is unavailable",
+				);
+			}
+			const handle = await open(normalized.absolutePath, SAFE_OPEN_FLAGS);
+			try {
+				const openedEntry = await handle.stat();
+				if (!openedEntry.isFile()) {
+					throw safeError(
+						normalized.relativePath,
+						"opened target is not a regular file",
+					);
+				}
+				const openedIdentity = stableStatIdentity(openedEntry);
+				if (openedIdentity === null) {
+					throw safeError(
+						normalized.relativePath,
+						"opened target identity is unavailable",
+					);
+				}
+				if (openedIdentity !== targetIdentity) {
+					throw safeError(
+						normalized.relativePath,
+						"target changed during validation",
+					);
+				}
+			} finally {
+				await handle.close();
+			}
+			return {
+				absolutePath: normalized.absolutePath,
+				relativePath: normalized.relativePath,
+				realPath: targetRealPath,
+			};
+		},
+	});
+};
+
+export const prepareSetupDoctorPythonProbe = async ({
+	repoRoot,
+	backendRootPath,
+	candidates,
+	createCandidates,
+	signal,
+}) => {
+	const repository = await validateSetupDoctorDirectory({
+		repoRoot,
+		path: ".",
+		signal,
+	});
+	const backendRoot =
+		typeof backendRootPath === "string" && backendRootPath.trim()
+			? await validateSetupDoctorDirectory({
+					repoRoot: repository.realPath,
+					path: backendRootPath,
+					signal,
+				})
+			: repository;
+	const candidateList =
+		candidates ??
+		createCandidates({
+			repoRoot: repository.realPath,
+			backendRootPath: backendRoot.relativePath,
+		});
+	const validatedCandidates = [];
+	for (const candidate of candidateList) {
+		const validated = isPathLike(candidate)
+			? await validateSetupDoctorFile({
+					repoRoot: repository.realPath,
+					path: candidate,
+					signal,
+					optional: true,
+				})
+			: null;
+		if (isPathLike(candidate) && validated === null) continue;
+		validatedCandidates.push({
+			candidate,
+			executable: validated?.realPath ?? candidate,
+		});
+	}
+	return { candidates: validatedCandidates };
+};