repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by bugabinga
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 { existsSync, realpathSync } from "node:fs";
import {
mkdir,
readdir,
readFile,
rm,
stat,
writeFile,
} from "node:fs/promises";
import { homedir, tmpdir } from "node:os";
import { basename, dirname, join, resolve } from "node:path";
import {
SpawnExitError,
SpawnTimeoutError,
spawnExpect,
spawnWithTimeout,
} from "./spawn.js";
// ── Constants ──────────────────────────────────────────────────────────────
const SIZE_LIMIT_BYTES = 500 * 1024 * 1024; // 500 MB
const FILE_COUNT_LIMIT = 10_000;
const CLONE_TIMEOUT_MS = 60_000; // 60s
const CHECKOUT_TIMEOUT_MS = 30_000; // 30s
const MARKER_FILE = ".pi-git-safe";
// ── Types ──────────────────────────────────────────────────────────────────
export interface SafeCloneResult {
path: string; // canonical (realpath) absolute path
url: string;
branch?: string;
fileCount: number;
totalSizeBytes: number;
symlinkCount: number; // demoted symlinks (stored as text files)
symlinks: string[]; // paths of demoted symlinks
warnings: string[];
}
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 */
function isDangerousPath(p: string): string | null {
const resolved = resolve(p);
const home = homedir();
const parts = resolved.split("/").filter(Boolean);
// Root
if (resolved === "/") 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): Promise<void> {
const markerContent = JSON.stringify(
{
url,
createdAt: new Date().toISOString(),
version: 1,
},
null,
2,
);
await writeFile(join(clonePath, MARKER_FILE), markerContent, "utf-8");
}
export function isMarkerPresent(clonePath: string): boolean {
return existsSync(join(clonePath, MARKER_FILE));
}
// ── 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 async function safeClone(
url: string,
path: string,
opts: { branch?: string; cwd: string },
): Promise<SafeCloneResult> {
const absPath = resolve(opts.cwd, path);
const warnings: string[] = [];
// ── Pre-flight: reject dangerous paths ─────────────────────────
const danger = isDangerousPath(absPath);
if (danger) {
throw new Error(
formatError(
`refusing to clone into unsafe path: ${absPath}`,
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(absPath)) {
if (isMarkerPresent(absPath)) {
// Our prior clone — safe to replace
await rm(absPath, { recursive: true, force: true });
} else {
throw new Error(
formatError(
`target directory already exists: ${absPath}`,
"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 " + absPath,
),
);
}
}
// ── Step 1: Clone with no checkout ─────────────────────────────
const cloneArgs = [
"clone",
"--no-checkout",
"--depth",
"1",
"--single-branch",
"-c",
"core.symlinks=false",
];
if (opts.branch) {
cloneArgs.push("--branch", opts.branch);
}
cloneArgs.push(url, absPath);
try {
await spawnExpect("git", cloneArgs, { timeout: CLONE_TIMEOUT_MS });
} catch (e) {
// Clean up partial clone
if (existsSync(absPath))
await rm(absPath, { recursive: true, force: true }).catch(() => {});
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 ${CLONE_TIMEOUT_MS / 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,
});
await spawnExpect("git", ["config", "lfs.skipSmudge", "true"], {
cwd: absPath,
});
// 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(() => {});
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;
try {
const lsTree = await spawnExpect("git", ["ls-tree", "-r", "-l", "HEAD"], {
cwd: absPath,
});
for (const line of lsTree.trim().split("\n")) {
if (!line.trim()) continue;
// Format: <mode> <type> <hash> <size>\t<path>
const sizeMatch = line.match(/\s+(\d+)\t/);
if (sizeMatch) {
totalSize += parseInt(sizeMatch[1]);
fileCount++;
}
}
} catch (e) {
// ls-tree may fail on empty repos — that's fine
warnings.push(
"Could not compute pre-checkout size (empty repo or ls-tree unavailable).",
);
}
if (totalSize > SIZE_LIMIT_BYTES) {
await rm(absPath, { recursive: true, force: true }).catch(() => {});
throw new Error(
formatError(
`repository content exceeds safety limit (${formatSize(totalSize)} > ${formatSize(SIZE_LIMIT_BYTES)})`,
"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 > FILE_COUNT_LIMIT) {
await rm(absPath, { recursive: true, force: true }).catch(() => {});
throw new Error(
formatError(
`repository has too many files (${fileCount} > ${FILE_COUNT_LIMIT})`,
"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 lsFiles = await spawnExpect("git", ["ls-files", "-s"], {
cwd: absPath,
});
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+(.+)$/);
if (pathMatch) symlinks.push(pathMatch[1]);
}
}
} catch {
// 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 {
await spawnExpect(
"git",
["-c", `core.hooksPath=${emptyHooksDir}`, "checkout"],
{ cwd: absPath, timeout: CHECKOUT_TIMEOUT_MS },
);
} catch (e) {
await rm(absPath, { recursive: true, force: true }).catch(() => {});
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;
}
// ── 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
await writeMarker(absPath, url);
// Canonical path
const canonicalPath = realpathSync(absPath);
return {
path: canonicalPath,
url,
branch: opts.branch,
fileCount,
totalSizeBytes: totalSize,
symlinkCount,
symlinks,
warnings,
};
}
// ── Helpers ────────────────────────────────────────────────────────────────
function formatSize(bytes: number): string {
if (bytes >= 1_000_000_000) return `${(bytes / 1_000_000_000).toFixed(1)}GB`;
if (bytes >= 1_000_000) return `${(bytes / 1_000_000).toFixed(1)}MB`;
if (bytes >= 1_000) return `${(bytes / 1_000).toFixed(1)}KB`;
return `${bytes}B`;
}
// ── Session recovery ───────────────────────────────────────────────────────
/**
* Walk known directories for .pi-git-safe marker files.
* Returns canonical (realpath) paths to clone directories.
*/
export async function recoverTrackedPaths(cwd: string): Promise<string[]> {
const roots = [
cwd,
tmpdir(),
join(homedir(), ".local", "state", "pi"),
homedir(),
];
const tracked: string[] = [];
for (const root of roots) {
if (!existsSync(root)) continue;
try {
const result = await spawnWithTimeout(
"find",
[root, "-name", MARKER_FILE, "-maxdepth", "4"],
{ timeout: 5_000 },
);
if (result.code === 0 && result.stdout.trim()) {
for (const line of result.stdout.trim().split("\n")) {
const markerPath = line.trim();
if (!markerPath) continue;
const cloneDir = dirname(markerPath);
try {
const canonical = realpathSync(cloneDir);
tracked.push(canonical);
} catch {
// realpath may fail on deleted paths
}
}
}
} catch {
// Permission denied, timeout, etc. — skip this root.
}
}
// Deduplicate
return [...new Set(tracked)];
}