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 };
}