Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/git-safe/clone.ts

Raw
// clone.ts — Safe git clone with defense-in-depth against:
//   - Post-checkout hooks (RCE)
//   - Symlink traversal
//   - LFS smudge filters (RCE)
//   - Disk exhaustion
//   - Credential prompt hangs

import { randomUUID } from "node:crypto";
import { existsSync, lstatSync, realpathSync } from "node:fs";
import {
	lstat,
	mkdir,
	readdir,
	readFile,
	rename,
	rm,
	writeFile,
} from "node:fs/promises";
import { homedir } from "node:os";
import {
	basename,
	dirname,
	isAbsolute,
	join,
	normalize,
	parse,
	relative,
	resolve,
	sep,
} from "node:path";
import {
	formatSize,
	withFileMutationQueue,
} from "@earendil-works/pi-coding-agent";
import { isMarkerPresent, MARKER_FILE } from "./marker.js";
import { SpawnExitError, SpawnTimeoutError, spawnExpect } from "./spawn.js";

// ── Constants ──────────────────────────────────────────────────────────────

const CHECKOUT_TIMEOUT_MS = 30_000; // 30s

// ── Types ──────────────────────────────────────────────────────────────────

export interface SafeCloneLimits {
	sizeLimitBytes: number;
	fileCountLimit: number;
	cloneTimeoutMs: number;
}

export interface SafeCloneResult {
	path: string; // canonical (realpath) absolute path
	url: string;
	branch?: string | undefined;
	fileCount: number;
	totalSizeBytes: number;
	symlinkCount: number; // demoted symlinks (stored as text files)
	symlinks: string[]; // paths of demoted symlinks
	warnings: string[];
	sparse?: string[] | undefined;
}

export interface SafeCloneError {
	message: string; // The actionable error for the LLM
	cause: string; // Root cause detail
	nextStep: string; // What to do
	alternative?: string; // Plan B
	dont: string; // "DO NOT ..."
}

// ── Path safety ────────────────────────────────────────────────────────────

/** Reject obviously dangerous paths */
export function isDangerousPath(p: string): string | null {
	const resolved = resolve(p);
	const home = homedir();
	const root = parse(resolved).root;
	const parts = relative(root, resolved).split(sep).filter(Boolean);

	// Root
	if (resolved === root) return "path is root directory";
	// Home dir itself
	if (resolved === home) return "path is home directory";
	// Too shallow (depth < 2)
	if (parts.length < 2) return `path is too shallow (${resolved})`;
	// Common dangerous locations
	if (resolved === "/tmp") return "path is /tmp";
	if (resolved === "/var") return "path is /var";
	if (resolved === "/etc") return "path is /etc";
	if (resolved === "/usr") return "path is /usr";
	if (resolved.startsWith("/sys") || resolved.startsWith("/proc"))
		return "path is a virtual filesystem";

	return null;
}

// ── Marker file ────────────────────────────────────────────────────────────

async function writeMarker(
	clonePath: string,
	url: string,
	meta: { branch?: string | undefined; sparse?: string[] | undefined } = {},
): Promise<void> {
	const markerContent = JSON.stringify(
		{
			url,
			branch: meta.branch,
			sparse: meta.sparse,
			createdAt: new Date().toISOString(),
			version: 2,
		},
		null,
		2,
	);
	await writeFile(join(clonePath, MARKER_FILE), markerContent, "utf-8");
}

// ── Error formatting ───────────────────────────────────────────────────────

function formatError(
	what: string,
	cause: string,
	nextStep: string,
	dont: string,
	alternative?: string,
): string {
	let msg = `git_clone_safe failed: ${what}\n  Root cause: ${cause}`;
	msg += `\n  → ${nextStep}`;
	if (alternative) msg += `\n  → ${alternative}`;
	msg += `\n  ⛔ DO NOT ${dont}`;
	return msg;
}

// ── Main clone logic ──────────────────────────────────────────────────────

export function validateSparsePath(path: string): void {
	const normalized = normalize(path).replaceAll("\\", "/");
	if (
		!path ||
		isAbsolute(path) ||
		normalized === "." ||
		normalized === ".." ||
		normalized.startsWith("../") ||
		normalized.includes("/../") ||
		path.includes("\0")
	) {
		throw new Error(`unsafe sparse path: ${path}`);
	}
}

export function buildCloneArgs(
	url: string,
	absPath: string,
	opts: { branch?: string | undefined; sparse?: string[] | undefined },
): string[] {
	const cloneArgs = [
		"clone",
		"--no-checkout",
		"--depth",
		"1",
		"--single-branch",
	];
	if (opts.sparse?.length) cloneArgs.push("--filter=blob:none", "--sparse");
	cloneArgs.push("-c", "core.symlinks=false");
	if (opts.branch) cloneArgs.push("--branch", opts.branch);
	cloneArgs.push(url, absPath);
	return cloneArgs;
}

export async function safeClone(
	url: string,
	path: string,
	opts: {
		branch?: string | undefined;
		sparse?: string[] | undefined;
		cwd: string;
		limits: SafeCloneLimits;
		signal?: AbortSignal;
	},
): Promise<SafeCloneResult> {
	const absPath = resolve(opts.cwd, path);
	const canonicalPath = canonicalizeTarget(absPath);
	for (const activeTarget of activeCloneTargets.keys()) {
		if (
			activeTarget !== canonicalPath &&
			targetsOverlap(activeTarget, canonicalPath)
		) {
			throw new Error(
				`clone target overlaps active clone: ${canonicalPath} and ${activeTarget}`,
			);
		}
	}
	activeCloneTargets.set(
		canonicalPath,
		(activeCloneTargets.get(canonicalPath) ?? 0) + 1,
	);
	try {
		return await withFileMutationQueue(canonicalPath, async () => {
			if (opts.signal?.aborted) throw opts.signal.reason;
			return safeCloneUnlocked(url, canonicalPath, opts);
		});
	} finally {
		const remaining = (activeCloneTargets.get(canonicalPath) ?? 1) - 1;
		if (remaining > 0) activeCloneTargets.set(canonicalPath, remaining);
		else activeCloneTargets.delete(canonicalPath);
	}
}

const activeCloneTargets = new Map<string, number>();

function targetsOverlap(left: string, right: string): boolean {
	return isPathOrDescendant(left, right) || isPathOrDescendant(right, left);
}

function isPathOrDescendant(parent: string, candidate: string): boolean {
	const pathFromParent = relative(parent, candidate);
	return (
		pathFromParent === "" ||
		(!pathFromParent.startsWith(`..${sep}`) && pathFromParent !== "..")
	);
}

export function canonicalizeTarget(target: string): string {
	if (existsSync(target) && lstatSync(target).isSymbolicLink()) {
		return resolve(realpathSync(dirname(target)), basename(target));
	}
	let ancestor = target;
	const suffix: string[] = [];
	while (!existsSync(ancestor)) {
		const parent = dirname(ancestor);
		if (parent === ancestor)
			throw new Error(`cannot resolve clone target: ${target}`);
		suffix.unshift(basename(ancestor));
		ancestor = parent;
	}
	return resolve(realpathSync(ancestor), ...suffix);
}

async function safeCloneUnlocked(
	url: string,
	targetPath: string,
	opts: {
		branch?: string | undefined;
		sparse?: string[] | undefined;
		cwd: string;
		limits: SafeCloneLimits;
		signal?: AbortSignal;
	},
): Promise<SafeCloneResult> {
	const { sizeLimitBytes, fileCountLimit, cloneTimeoutMs } = opts.limits;
	const signalOption = opts.signal === undefined ? {} : { signal: opts.signal };
	const absPath = join(
		dirname(targetPath),
		`.${basename(targetPath)}.pi-git-safe-${randomUUID()}`,
	);
	const warnings: string[] = [];

	// ── Pre-flight: reject dangerous paths ─────────────────────────
	const danger = isDangerousPath(targetPath);
	if (danger) {
		throw new Error(
			formatError(
				`refusing to clone into unsafe path: ${targetPath}`,
				danger,
				"Choose a deeper subdirectory, e.g. ./repos/owner/project",
				"bypass this safety check or use raw git clone.",
			),
		);
	}

	// ── Pre-flight: handle existing directory ──────────────────────
	if (existsSync(targetPath)) {
		if (!isMarkerPresent(targetPath)) {
			throw new Error(
				formatError(
					`target directory already exists: ${targetPath}`,
					"Directory exists and was not created by git_clone_safe (no .pi-git-safe marker file).",
					"Remove the directory manually first, or choose a different path.",
					"use raw git clone to bypass this safety check.",
					"If you want to replace it, delete it first: rm -rf " + targetPath,
				),
			);
		}
	}

	const sparse = opts.sparse?.filter((p) => p.trim().length > 0);
	for (const p of sparse ?? []) validateSparsePath(p);

	// ── Step 1: Clone with no checkout ─────────────────────────────
	const cloneArgs = buildCloneArgs(url, absPath, {
		branch: opts.branch,
		sparse,
	});

	try {
		await spawnExpect("git", cloneArgs, {
			timeout: cloneTimeoutMs,
			...signalOption,
		});
	} catch (e) {
		// This serialized attempt owns any partial clone at its target.
		if (existsSync(absPath))
			await rm(absPath, { recursive: true, force: true }).catch(() => {});
		if (opts.signal?.aborted) throw opts.signal.reason;

		if (e instanceof SpawnExitError) {
			throw new Error(
				formatError(
					"git clone returned non-zero exit code",
					e.stderr.trim().split("\n").pop() || `exit code ${e.exitCode}`,
					"Verify the URL is correct and the repository is accessible. Check for typos in owner/repo.",
					"retry with raw git clone — it bypasses safety protections.",
					"If the repo is private, ask the user to configure SSH keys or provide a personal access token.",
				),
			);
		}
		if (e instanceof SpawnTimeoutError) {
			throw new Error(
				formatError(
					"git clone timed out",
					`Clone did not complete within ${cloneTimeoutMs / 1000}s. The repository may be very large or the server is unreachable.`,
					"Check your network connection and the repository size. Try a specific branch with shallow history.",
					"use raw git clone to bypass this safety check.",
				),
			);
		}
		throw e;
	}

	// ── Step 2: Configure safety (repo-local) ──────────────────────
	const emptyHooksDir = join(absPath, ".git", "pi-safe-hooks");
	try {
		await mkdir(emptyHooksDir, { recursive: true });
		await spawnExpect("git", ["config", "core.hooksPath", emptyHooksDir], {
			cwd: absPath,
			...signalOption,
		});
		await spawnExpect("git", ["config", "lfs.skipSmudge", "true"], {
			cwd: absPath,
			...signalOption,
		});

		if (sparse?.length) {
			await spawnExpect("git", ["sparse-checkout", "set", "--", ...sparse], {
				cwd: absPath,
				...signalOption,
			});
		}

		// Disable all filter drivers (LFS, custom filters)
		await writeFile(
			join(absPath, ".git", "info", "attributes"),
			"* -filter\n",
			"utf-8",
		);

		// Belt-and-suspenders: remove default hooks directory
		await rm(join(absPath, ".git", "hooks"), {
			recursive: true,
			force: true,
		}).catch(() => {});
	} catch (e) {
		await rm(absPath, { recursive: true, force: true }).catch(() => {});
		if (opts.signal?.aborted) throw opts.signal.reason;
		throw new Error(
			formatError(
				"failed to configure safety settings in cloned repository",
				(e as Error).message,
				"This may be a filesystem permissions issue. Check write access to the target path.",
				"use raw git clone — the safety configuration is essential.",
			),
		);
	}

	// ── Step 3: Pre-checkout size validation from metadata ──────────
	let totalSize = 0;
	let fileCount = 0;
	let emptyRepository = false;
	try {
		const lsTreeArgs = ["ls-tree", "-r", "-l", "HEAD"];
		if (sparse?.length) lsTreeArgs.push("--", ...sparse);
		const lsTree = await spawnExpect("git", lsTreeArgs, {
			cwd: absPath,
			...signalOption,
		});
		for (const line of lsTree.trim().split("\n")) {
			if (!line.trim()) continue;
			// Format: <mode> <type> <hash> <size>\t<path>
			const metadata = line.match(/^\d{6} (blob|commit) [0-9a-f]+\s+(\d+|-)\t/);
			if (!metadata) throw new Error("invalid repository tree metadata");
			if (metadata[1] === "commit" && metadata[2] === "-") continue;
			const size = Number(metadata[2]);
			if (!Number.isSafeInteger(size) || size < 0)
				throw new Error("invalid repository tree size");
			totalSize += size;
			fileCount++;
		}
	} catch (error) {
		// Only a successful status report can distinguish an unborn repository
		// from failed or truncated metadata inspection.
		if (!opts.signal?.aborted && error instanceof SpawnExitError) {
			try {
				const status = await spawnExpect(
					"git",
					["status", "--porcelain=v2", "--branch"],
					{ cwd: absPath, ...signalOption },
				);
				emptyRepository = status.split("\n").includes("# branch.oid (initial)");
			} catch {
				/* Failed verification is not evidence of an empty repository. */
			}
		}
		if (!emptyRepository) {
			await rm(absPath, { recursive: true, force: true }).catch(() => {});
			if (opts.signal?.aborted) throw opts.signal.reason;
			throw new Error("failed to inspect repository tree before checkout", {
				cause: error,
			});
		}
		warnings.push("Repository has no commits; no files were checked out.");
	}

	if (totalSize > sizeLimitBytes) {
		await rm(absPath, { recursive: true, force: true }).catch(() => {});
		throw new Error(
			formatError(
				`repository content exceeds safety limit (${formatSize(totalSize)} > ${formatSize(sizeLimitBytes)})`,
				"Tree metadata indicates the total file content exceeds the configured size limit.",
				"Use sparse checkout to clone specific directories only, or inspect the repository manually in a browser.",
				"increase the size limit or bypass this check — disk exhaustion risk.",
			),
		);
	}

	if (fileCount > fileCountLimit) {
		await rm(absPath, { recursive: true, force: true }).catch(() => {});
		throw new Error(
			formatError(
				`repository has too many files (${fileCount} > ${fileCountLimit})`,
				"Shallow clone with this many files risks excessive disk and memory usage.",
				"Use sparse checkout to clone specific directories only.",
				"bypass this file count limit.",
			),
		);
	}

	// ── Step 4: Pre-checkout symlink scan ──────────────────────────
	let symlinkCount = 0;
	const symlinks: string[] = [];
	try {
		const lsFilesArgs = ["ls-files", "-s"];
		if (sparse?.length) lsFilesArgs.push("--", ...sparse);
		const lsFiles = await spawnExpect("git", lsFilesArgs, {
			cwd: absPath,
			...signalOption,
		});
		for (const line of lsFiles.trim().split("\n")) {
			// Mode 120000 = symlink
			if (line.startsWith("120000 ")) {
				symlinkCount++;
				const pathMatch = line.match(/^\S+\s+\S+\s+\S+\s+(.+)$/);
				const symlinkPath = pathMatch?.[1];
				if (symlinkPath !== undefined) symlinks.push(symlinkPath);
			}
		}
	} catch {
		if (opts.signal?.aborted) {
			await rm(absPath, { recursive: true, force: true }).catch(() => {});
			throw opts.signal.reason;
		}
		// Best effort
	}

	if (symlinkCount > 0) {
		warnings.push(
			`Repository contains ${symlinkCount} symlink(s). ` +
				"core.symlinks=false ensures they are stored as text files, not followed. " +
				"Symlink targets: " +
				symlinks.slice(0, 5).join(", ") +
				(symlinkCount > 5 ? ` (and ${symlinkCount - 5} more)` : ""),
		);
	}

	// ── Step 5: Checkout with timeout ──────────────────────────────
	try {
		if (!emptyRepository)
			await spawnExpect(
				"git",
				["-c", `core.hooksPath=${emptyHooksDir}`, "checkout"],
				{ cwd: absPath, timeout: CHECKOUT_TIMEOUT_MS, ...signalOption },
			);
	} catch (e) {
		await rm(absPath, { recursive: true, force: true }).catch(() => {});
		if (opts.signal?.aborted) throw opts.signal.reason;
		if (e instanceof SpawnTimeoutError) {
			throw new Error(
				formatError(
					"git checkout timed out",
					`Checkout did not complete within ${CHECKOUT_TIMEOUT_MS / 1000}s. The repository may have too many/large files for on-demand fetching, or the server is slow.`,
					"Try a more specific branch or sparse checkout path. If the repo is large, clone specific directories.",
					"retry without changes or use raw git clone — safety controls are essential.",
				),
			);
		}
		if (e instanceof SpawnExitError) {
			throw new Error(
				formatError(
					"git checkout failed",
					e.stderr.trim().split("\n").pop() || `exit code ${e.exitCode}`,
					"The checkout step failed after clone succeeded. This may be a corrupt repository or filesystem issue.",
					"use raw git clone to bypass this check.",
				),
			);
		}
		throw e;
	}

	const materialized = await scanWorkingTree(absPath, opts.signal).catch(
		async (error: unknown) => {
			await rm(absPath, { recursive: true, force: true }).catch(() => {});
			throw error;
		},
	);
	fileCount = materialized.fileCount;
	totalSize = materialized.totalSizeBytes;
	if (totalSize > sizeLimitBytes) {
		await rm(absPath, { recursive: true, force: true }).catch(() => {});
		throw new Error(
			formatError(
				`checkout content exceeds safety limit (${formatSize(totalSize)} > ${formatSize(sizeLimitBytes)})`,
				"Working tree materialized more data than allowed.",
				"Use a narrower sparse checkout.",
				"bypass this post-checkout size check.",
			),
		);
	}
	if (fileCount > fileCountLimit) {
		await rm(absPath, { recursive: true, force: true }).catch(() => {});
		throw new Error(
			formatError(
				`checkout has too many files (${fileCount} > ${fileCountLimit})`,
				"Working tree materialized more files than allowed.",
				"Use a narrower sparse checkout.",
				"bypass this post-checkout file count check.",
			),
		);
	}

	// ── Step 6: Post-checkout verification ─────────────────────────

	// Audit .git/config for suspicious include directives
	try {
		const gitConfig = await readFile(join(absPath, ".git", "config"), "utf-8");
		if (/\binclude(?:If)?\s*=/i.test(gitConfig)) {
			warnings.push(
				".git/config contains include/includeIf directives. " +
					"These could reference paths outside the clone. " +
					"Review: " +
					gitConfig
						.split("\n")
						.filter((l) => /\binclude/i.test(l))
						.join(", "),
			);
		}
	} catch {
		// Best effort
	}

	// Write marker file
	if (opts.signal?.aborted) {
		await rm(absPath, { recursive: true, force: true }).catch(() => {});
		throw opts.signal.reason;
	}
	await writeMarker(absPath, url, { branch: opts.branch, sparse }).catch(
		async (error: unknown) => {
			await rm(absPath, { recursive: true, force: true }).catch(() => {});
			throw error;
		},
	);
	if (opts.signal?.aborted) {
		await rm(absPath, { recursive: true, force: true }).catch(() => {});
		throw opts.signal.reason;
	}

	// Cancellation commits before publishing: later aborts cannot discard old data.
	if (opts.signal?.aborted) {
		await rm(absPath, { recursive: true, force: true }).catch(() => {});
		throw opts.signal.reason;
	}
	await publishStagedClone(absPath, targetPath);

	// Canonical path
	const canonicalPath = realpathSync(targetPath);

	return {
		path: canonicalPath,
		url,
		branch: opts.branch,
		fileCount,
		totalSizeBytes: totalSize,
		symlinkCount,
		symlinks,
		warnings,
		sparse,
	};
}

// ── Helpers ────────────────────────────────────────────────────────────────

export async function publishStagedClone(
	stagedPath: string,
	targetPath: string,
	renamePath: (from: string, to: string) => Promise<void> = rename,
): Promise<void> {
	const backupPath = join(
		dirname(targetPath),
		`.${basename(targetPath)}.pi-git-safe-backup-${randomUUID()}`,
	);
	let oldCloneMoved = false;
	try {
		if (existsSync(targetPath)) {
			if (!isMarkerPresent(targetPath))
				throw new Error(`target directory changed during clone: ${targetPath}`);
			await renamePath(targetPath, backupPath);
			oldCloneMoved = true;
		}
		try {
			await renamePath(stagedPath, targetPath);
		} catch (publishError) {
			if (oldCloneMoved && !existsSync(targetPath)) {
				try {
					await renamePath(backupPath, targetPath);
				} catch (restoreError) {
					throw new AggregateError(
						[publishError, restoreError],
						`failed to publish staged clone and restore prior clone: ${targetPath}`,
					);
				}
			}
			throw publishError;
		}
		if (oldCloneMoved)
			await rm(backupPath, { recursive: true, force: true }).catch(() => {});
	} catch (error) {
		await rm(stagedPath, { recursive: true, force: true }).catch(() => {});
		throw error;
	}
}

async function scanWorkingTree(
	root: string,
	signal?: AbortSignal,
): Promise<{
	fileCount: number;
	totalSizeBytes: number;
}> {
	let fileCount = 0;
	let totalSizeBytes = 0;
	const stack = [root];
	while (stack.length > 0) {
		if (signal?.aborted) throw signal.reason;
		const dir = stack.pop();
		if (!dir) continue;
		for (const entry of await readdir(dir, { withFileTypes: true })) {
			if (signal?.aborted) throw signal.reason;
			if (dir === root && entry.name === ".git") continue;
			const p = join(dir, entry.name);
			if (entry.isDirectory()) {
				stack.push(p);
				continue;
			}
			const s = await lstat(p);
			if (!s.isFile()) continue;
			fileCount++;
			totalSizeBytes += s.size;
		}
	}
	return { fileCount, totalSizeBytes };
}