@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/core/safe-exec.ts

@@ -0,0 +1,193 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { clampTimerDelayMs } from "./timers.js";
+
+export const SAFE_EXEC_DEFAULT_TIMEOUT_MS = 120_000;
+export const SAFE_EXEC_DEFAULT_MAX_OUTPUT_BYTES = 600_000;
+
+const ENV_ALLOWLIST = [
+	"PATH",
+	"HOME",
+	"USER",
+	"LOGNAME",
+	"LANG",
+	"LC_ALL",
+	"TMPDIR",
+	"TEMP",
+	"TMP",
+	"CI",
+	"NO_COLOR",
+] as const;
+
+export interface SafeCommandResult {
+	file: string;
+	args: string[];
+	cwd: string;
+	stdout: string;
+	stderr: string;
+	exitCode: number | null;
+	signal: NodeJS.Signals | null;
+	aborted: boolean;
+	timedOut: boolean;
+	outputCapped: boolean;
+	durationMs: number;
+}
+
+export interface RunCommandVectorOptions {
+	cwd?: string;
+	workspaceRoot?: string;
+	timeoutMs?: number;
+	maxOutputBytes?: number;
+	signal?: AbortSignal;
+	env?: Record<string, string>;
+}
+
+export function buildSafeToolEnv(extra: Record<string, string> = {}): NodeJS.ProcessEnv {
+	const env: NodeJS.ProcessEnv = {};
+	for (const key of ENV_ALLOWLIST) {
+		const value = process.env[key];
+		if (value !== undefined) env[key] = value;
+	}
+	for (const [key, value] of Object.entries(extra)) {
+		if (!/^[A-Z_][A-Z0-9_]*$/i.test(key)) continue;
+		env[key] = value;
+	}
+	return env;
+}
+
+export function resolveSafeCwd(cwd: string | undefined, workspaceRoot: string = process.cwd()): string {
+	const root = path.resolve(workspaceRoot);
+	const resolved = cwd === undefined ? root : path.isAbsolute(cwd) ? path.resolve(cwd) : path.resolve(root, cwd);
+	const rel = path.relative(root, resolved);
+	if (rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel))) return resolved;
+	throw new Error(`cwd escapes workspace root: ${resolved}`);
+}
+
+export function runCommandVector(
+	file: string,
+	args: ReadonlyArray<string>,
+	options: RunCommandVectorOptions = {},
+): Promise<SafeCommandResult> {
+	return new Promise((resolve) => {
+		const startedAt = performance.now();
+		const cwd = resolveSafeCwd(options.cwd, options.workspaceRoot);
+		const timeoutMs = clampTimerDelayMs(options.timeoutMs ?? SAFE_EXEC_DEFAULT_TIMEOUT_MS);
+		const maxOutputBytes = options.maxOutputBytes ?? SAFE_EXEC_DEFAULT_MAX_OUTPUT_BYTES;
+		let aborted = false;
+		let timedOut = false;
+		let outputCapped = false;
+		let outputBytes = 0;
+		let stdout = "";
+		let stderr = "";
+		let settled = false;
+		let killSent = false;
+		let timeoutId: ReturnType<typeof setTimeout> | null = null;
+		let killGraceTimer: ReturnType<typeof setTimeout> | null = null;
+
+		const child = spawn(file, [...args], {
+			cwd,
+			env: buildSafeToolEnv(options.env),
+			detached: process.platform !== "win32",
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+
+		const clearKillGraceTimer = (): void => {
+			if (killGraceTimer) clearTimeout(killGraceTimer);
+			killGraceTimer = null;
+		};
+
+		const sendSignal = (signalName: NodeJS.Signals): void => {
+			const pid = child.pid;
+			if (pid && process.platform !== "win32") {
+				try {
+					process.kill(-pid, signalName);
+					return;
+				} catch {
+					// Fall through to killing the direct child.
+				}
+			}
+			child.kill(signalName);
+		};
+
+		const killChild = (): void => {
+			if (killSent) return;
+			killSent = true;
+			sendSignal("SIGTERM");
+			killGraceTimer = setTimeout(() => sendSignal("SIGKILL"), 3000);
+		};
+
+		const onAbort = (): void => {
+			aborted = true;
+			killChild();
+		};
+
+		if (timeoutMs > 0) {
+			timeoutId = setTimeout(() => {
+				timedOut = true;
+				killChild();
+			}, timeoutMs);
+		}
+		if (options.signal?.aborted) onAbort();
+		else options.signal?.addEventListener("abort", onAbort, { once: true });
+
+		const appendChunk = (target: "stdout" | "stderr", chunk: Buffer): void => {
+			outputBytes += chunk.byteLength;
+			if (outputBytes > maxOutputBytes) {
+				outputCapped = true;
+				killChild();
+				return;
+			}
+			if (target === "stdout") stdout += chunk.toString("utf8");
+			else stderr += chunk.toString("utf8");
+		};
+
+		child.stdout?.on("data", (chunk: Buffer) => appendChunk("stdout", chunk));
+		child.stderr?.on("data", (chunk: Buffer) => appendChunk("stderr", chunk));
+		child.on("error", (error) => {
+			if (settled) return;
+			settled = true;
+			if (timeoutId) clearTimeout(timeoutId);
+			clearKillGraceTimer();
+			options.signal?.removeEventListener("abort", onAbort);
+			resolve({
+				file,
+				args: [...args],
+				cwd,
+				stdout,
+				stderr: stderr.length > 0 ? stderr : error.message,
+				exitCode: null,
+				signal: null,
+				aborted,
+				timedOut,
+				outputCapped,
+				durationMs: Math.round(performance.now() - startedAt),
+			});
+		});
+		child.on("close", (code, signalName) => {
+			if (settled) return;
+			settled = true;
+			if (timeoutId) clearTimeout(timeoutId);
+			clearKillGraceTimer();
+			options.signal?.removeEventListener("abort", onAbort);
+			resolve({
+				file,
+				args: [...args],
+				cwd,
+				stdout,
+				stderr,
+				exitCode: code,
+				signal: signalName,
+				aborted,
+				timedOut,
+				outputCapped,
+				durationMs: Math.round(performance.now() - startedAt),
+			});
+		});
+	});
+}
+
+export function combineSafeOutput(result: Pick<SafeCommandResult, "stdout" | "stderr">): string {
+	const { stdout, stderr } = result;
+	return stderr.length > 0 ? `${stdout}${stdout.endsWith("\n") || stdout.length === 0 ? "" : "\n"}${stderr}` : stdout;
+}

package/src/core/safe-id.ts

@@ -0,0 +1,37 @@
+/**
+ * Store ids (evidence ids, eval ids, session ids) are identifiers, not
+ * filesystem paths. A store resolves them by joining under a fixed root, so an
+ * id carrying a path separator, a `.`/`..` segment, a NUL, or an absolute path
+ * could escape that root and read or write an unintended file. Validate the id
+ * before any join. This lives in `core` so every store and CLI surface shares
+ * one rule and one error type.
+ */
+
+/** Thrown when a caller-supplied store id is not a safe identifier. */
+export class InvalidIdError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "InvalidIdError";
+	}
+}
+
+/**
+ * A safe id is non-empty, contains no path separator (`/` or `\`), no NUL, and
+ * is not a bare `.`/`..` segment. Those are the only tokens that let `join`
+ * escape a fixed root, so rejecting them is sufficient without an allowlist that
+ * would break existing id shapes.
+ */
+function isSafeId(id: string): boolean {
+	if (id.length === 0) return false;
+	if (id.includes("/") || id.includes("\\")) return false;
+	if (id.includes("\0")) return false;
+	if (id === "." || id === "..") return false;
+	return true;
+}
+
+/** Throw {@link InvalidIdError} unless `id` is a safe identifier. `kind` names the id in the message. */
+export function assertSafeId(id: string, kind: string): void {
+	if (!isSafeId(id)) {
+		throw new InvalidIdError(`invalid ${kind} id '${id}': must not contain path separators or path segments`);
+	}
+}

package/src/core/safe-resource-write.ts

@@ -0,0 +1,162 @@
+import { randomBytes } from "node:crypto";
+import {
+	closeSync,
+	copyFileSync,
+	existsSync,
+	fsyncSync,
+	mkdirSync,
+	openSync,
+	renameSync,
+	rmSync,
+	statSync,
+	writeSync,
+} from "node:fs";
+import path from "node:path";
+
+export interface SafeResourceBackupOptions {
+	path?: string;
+	suffix?: string;
+}
+
+export interface SafeResourceWriteRenameContext {
+	targetPath: string;
+	tempPath: string;
+	bytes: number;
+	backupPath?: string;
+}
+
+export interface SafeResourceWriteOptions {
+	backup?: boolean | SafeResourceBackupOptions;
+	encoding?: BufferEncoding;
+	mode?: number;
+	beforeRename?: (context: SafeResourceWriteRenameContext) => void;
+}
+
+export interface SafeResourceWriteResult {
+	path: string;
+	tempPath: string;
+	bytes: number;
+	backupPath?: string;
+}
+
+let resourceWriteSequence = 0;
+
+export function safeResourceBackupPath(targetPath: string, suffix = ".bak"): string {
+	return `${targetPath}${suffix}`;
+}
+
+/**
+ * Flush a directory entry so a completed rename survives a crash.
+ *
+ * Best effort by design: directory fsync is not supported on every filesystem
+ * or platform, and a rejection there is not a failed write. The temp-file
+ * fsync plus rename still preserves the property that matters, which is that
+ * no reader ever sees a torn file. Swallowing the error is what keeps an
+ * unsupported filesystem from failing a write that in fact landed.
+ */
+export function fsyncDirectory(dir: string): void {
+	let fd: number | null = null;
+	try {
+		fd = openSync(dir, "r");
+		fsyncSync(fd);
+	} catch {
+		// Unsupported here, and not evidence the write failed. See above.
+	} finally {
+		if (fd !== null) closeSync(fd);
+	}
+}
+
+function fsyncFile(filePath: string): void {
+	const fd = openSync(filePath, "r");
+	try {
+		fsyncSync(fd);
+	} finally {
+		closeSync(fd);
+	}
+}
+
+function tempPathFor(targetPath: string): string {
+	const dir = path.dirname(targetPath);
+	const base = path.basename(targetPath);
+	const suffix = `${process.pid}-${Date.now()}-${++resourceWriteSequence}-${randomBytes(6).toString("hex")}`;
+	return path.join(dir, `.${base}.tmp-${suffix}`);
+}
+
+function writeMode(targetPath: string, mode: number | undefined): number {
+	if (mode !== undefined) return mode;
+	try {
+		return statSync(targetPath).mode & 0o777;
+	} catch {
+		return 0o666;
+	}
+}
+
+function bufferFrom(contents: string | Uint8Array, encoding: BufferEncoding | undefined): Buffer {
+	if (typeof contents === "string") return Buffer.from(contents, encoding ?? "utf8");
+	return Buffer.from(contents);
+}
+
+function writeAll(fd: number, buffer: Buffer): void {
+	let offset = 0;
+	while (offset < buffer.byteLength) {
+		offset += writeSync(fd, buffer, offset, buffer.byteLength - offset);
+	}
+}
+
+function backupOptions(backup: boolean | SafeResourceBackupOptions | undefined): SafeResourceBackupOptions | null {
+	if (backup === true) return {};
+	if (!backup) return null;
+	return backup;
+}
+
+export function safeResourceWrite(
+	targetPath: string,
+	contents: string | Uint8Array,
+	options: SafeResourceWriteOptions = {},
+): SafeResourceWriteResult {
+	const dir = path.dirname(targetPath);
+	mkdirSync(dir, { recursive: true });
+	const tempPath = tempPathFor(targetPath);
+	const buffer = bufferFrom(contents, options.encoding);
+	let tempExists = false;
+	let backupPath: string | undefined;
+
+	try {
+		const fd = openSync(tempPath, "wx", writeMode(targetPath, options.mode));
+		tempExists = true;
+		try {
+			writeAll(fd, buffer);
+			fsyncSync(fd);
+		} finally {
+			closeSync(fd);
+		}
+
+		const backup = backupOptions(options.backup);
+		if (backup && existsSync(targetPath)) {
+			backupPath = backup.path ?? safeResourceBackupPath(targetPath, backup.suffix ?? ".bak");
+			mkdirSync(path.dirname(backupPath), { recursive: true });
+			copyFileSync(targetPath, backupPath);
+			fsyncFile(backupPath);
+			fsyncDirectory(path.dirname(backupPath));
+		}
+
+		options.beforeRename?.({
+			targetPath,
+			tempPath,
+			bytes: buffer.byteLength,
+			...(backupPath ? { backupPath } : {}),
+		});
+		renameSync(tempPath, targetPath);
+		tempExists = false;
+		fsyncDirectory(dir);
+		return {
+			path: targetPath,
+			tempPath,
+			bytes: buffer.byteLength,
+			...(backupPath ? { backupPath } : {}),
+		};
+	} catch (err) {
+		if (tempExists) rmSync(tempPath, { force: true });
+		throw err;
+	}
+}