opencode-workflow-guard 1.1.5 → 1.2.1

package/src/lib/verify.ts

@@ -0,0 +1,169 @@
+import { spawn, spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getCleanEnv, normalize } from "./utils.ts";
+import { getProjectConfig } from "./state.ts";
+import { normalizeGitCommands } from "../policies/git.ts";
+import { liveMutationIn } from "../policies/destructive.ts";
+import { isSettingsTamper } from "../policies/tamper.ts";
+
+export function detectVerifyCommand(root: string): string | undefined {
+	if (process.env.WORKFLOW_GUARD_VERIFY !== undefined) {
+		const cmd = process.env.WORKFLOW_GUARD_VERIFY.trim();
+		return cmd || undefined;
+	}
+	const cfg = getProjectConfig(root);
+	if (typeof cfg.verifyCommand === "string") {
+		const cmd = cfg.verifyCommand.trim();
+		return cmd || undefined;
+	}
+	try {
+		const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as {
+			scripts?: Record<string, string>;
+		};
+		if (pkg.scripts?.test) return "npm test";
+	} catch {}
+	return undefined;
+}
+
+/**
+ * Truncates and snips verification stdout/stderr for token efficiency.
+ * When a test suite or compiler passes, verbose log lines are trimmed to a
+ * concise summary. When it fails, failure context, error markers, and stack
+ * traces are prioritized.
+ */
+export function snipVerifyOutput(output: string, passed: boolean, maxLines = 40): string {
+	if (!output) return "(no output)";
+	const lines = output.trim().split("\n");
+	if (lines.length <= maxLines) return output.trim();
+
+	if (passed) {
+		const head = lines.slice(0, 5).join("\n");
+		const tail = lines.slice(-15).join("\n");
+		return `${head}\n... [${lines.length - 20} lines omitted - all tests passing] ...\n${tail}`;
+	}
+
+	const errorLines: string[] = [];
+	for (const line of lines) {
+		if (/(?:fail|error|exception|panic|assert|reject|expected|received|err:)/i.test(line)) {
+			errorLines.push(line);
+		}
+	}
+
+	const head = lines.slice(0, 5).join("\n");
+	const tail = lines.slice(-20).join("\n");
+	const errorSummary = errorLines.slice(-15).join("\n");
+
+	return [
+		head,
+		`\n--- [Verification Failed: ${lines.length} total lines captured] ---`,
+		errorSummary ? `Key Failures:\n${errorSummary}` : "",
+		`Output Tail:\n${tail}`,
+	]
+		.filter(Boolean)
+		.join("\n");
+}
+
+export function getCurrentGitCommitHash(root: string): string | undefined {
+	try {
+		const res = spawnSync("git", ["rev-parse", "HEAD"], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (res.status === 0 && res.stdout.trim()) {
+			return res.stdout.trim();
+		}
+	} catch {}
+	return undefined;
+}
+
+export function getGitStatusSummary(root: string): string | undefined {
+	try {
+		const res = spawnSync("git", ["status", "--porcelain"], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (res.status === 0) {
+			return res.stdout.trim();
+		}
+	} catch {}
+	return undefined;
+}
+
+export async function runVerify(
+	command: string,
+	root: string,
+	timeoutMs = 30_000,
+): Promise<{ passed: boolean; output: string; durationMs: number }> {
+	const start = Date.now();
+	const allowLive = process.env.WORKFLOW_GUARD_ALLOW_LIVE === "1";
+
+	if (!allowLive) {
+		const normalized = normalizeGitCommands(normalize(command));
+		const liveCheck = liveMutationIn(normalized);
+		if (liveCheck) {
+			return {
+				passed: false,
+				output: `Verification command blocked: contains live destructive command (${liveCheck})`,
+				durationMs: 0,
+			};
+		}
+		if (isSettingsTamper(command)) {
+			return {
+				passed: false,
+				output: "Verification command blocked: contains settings tamper command",
+				durationMs: 0,
+			};
+		}
+	}
+
+	return new Promise((resolve) => {
+		let output = "";
+		let timer: NodeJS.Timeout | undefined;
+		let child: ReturnType<typeof spawn>;
+		try {
+			child = spawn(command, {
+				cwd: root,
+				shell: true,
+				env: getCleanEnv(),
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+		} catch (err: any) {
+			return resolve({
+				passed: false,
+				output: `(spawn failed: ${err?.message ?? "unknown error"})`,
+				durationMs: Date.now() - start,
+			});
+		}
+
+		timer = setTimeout(() => {
+			try {
+				child.kill("SIGKILL");
+			} catch {}
+			resolve({
+				passed: false,
+				output: output + `\n(Verification timed out after ${Math.round(timeoutMs / 1000)}s)`,
+				durationMs: Date.now() - start,
+			});
+		}, timeoutMs);
+
+		child.stdout?.on("data", (d) => {
+			output += d.toString();
+			if (output.length > 50_000) output = output.slice(-50_000);
+		});
+		child.stderr?.on("data", (d) => {
+			output += d.toString();
+			if (output.length > 50_000) output = output.slice(-50_000);
+		});
+		child.on("close", (code) => {
+			if (timer) clearTimeout(timer);
+			resolve({ passed: code === 0, output, durationMs: Date.now() - start });
+		});
+		child.on("error", (err) => {
+			if (timer) clearTimeout(timer);
+			resolve({ passed: false, output: `(spawn failed: ${err.message})`, durationMs: Date.now() - start });
+		});
+	});
+}

package/src/lib/worktree.ts

@@ -0,0 +1,216 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, symlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve, sep } from "node:path";
+import { getWorkspaceRoot } from "./state.ts";
+import { isProtectedBranchName } from "../policies/git.ts";
+
+export function getWorktreeStorageDir(root = getWorkspaceRoot()): string {
+	const base =
+		process.env.WORKFLOW_GUARD_WORKTREE_DIR ??
+		join(process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"), "opencode", "worktrees");
+	return join(base, basename(root));
+}
+
+/**
+ * Returns a copy of process.env with git context variables removed so spawned
+ * git commands resolve the repository from their cwd alone. Without this, a
+ * caller nested inside a git hook (which exports GIT_INDEX_FILE and friends)
+ * would make `git worktree add` fail: the internal checkout of the new
+ * worktree resolves the inherited relative GIT_INDEX_FILE against the new
+ * worktree root, where `.git` is a file, not a directory.
+ */
+export function getCleanGitEnv(): Record<string, string> {
+	const env: Record<string, string> = { ...(process.env as Record<string, string>) };
+	for (const key of [
+		"GIT_INDEX_FILE",
+		"GIT_DIR",
+		"GIT_WORK_TREE",
+		"GIT_COMMON_DIR",
+		"GIT_OBJECT_DIRECTORY",
+		"GIT_ALTERNATE_OBJECT_DIRECTORIES",
+		"GIT_PREFIX",
+	]) {
+		delete env[key];
+	}
+	return env;
+}
+
+/**
+ * Validates a branch name using git itself (`git check-ref-format --branch`),
+ * with fast local pre-filters for names that must never be passed as arguments
+ * at all (a leading dash would be parsed as an option).
+ */
+export function isValidBranchName(name: string): boolean {
+	if (!name || name.length > 255) return false;
+	if (name.startsWith("-") || name.startsWith(".") || name.endsWith(".") || name.endsWith(".lock")) return false;
+	if (name.includes("..") || name.includes("@{") || name.includes("//")) return false;
+	const res = spawnSync("git", ["check-ref-format", "--branch", name], {
+		encoding: "utf8",
+		timeout: 5_000,
+		env: getCleanGitEnv(),
+	});
+	return res.status === 0;
+}
+
+function localBranchExists(branch: string, root: string): boolean {
+	const res = spawnSync("git", ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], {
+		cwd: root,
+		encoding: "utf8",
+		timeout: 5_000,
+		env: getCleanGitEnv(),
+	});
+	return res.status === 0;
+}
+
+export function createGitWorktree(
+	branch: string,
+	baseBranch = "HEAD",
+	root = getWorkspaceRoot(),
+): { success: boolean; worktreePath?: string; error?: string } {
+	if (!branch || !isValidBranchName(branch)) {
+		return { success: false, error: `Invalid branch name '${branch}' for worktree creation.` };
+	}
+	if (isProtectedBranchName(branch, root)) {
+		return { success: false, error: `Cannot create worktree on protected branch '${branch}'.` };
+	}
+
+	const storageBase = getWorktreeStorageDir(root);
+	const targetPath = join(storageBase, branch.replace(/[/\\:]/g, "-"));
+
+	try {
+		mkdirSync(storageBase, { recursive: true });
+
+		const exists = localBranchExists(branch, root);
+		const gitArgs = exists
+			? ["worktree", "add", targetPath, branch]
+			: ["worktree", "add", "-b", branch, targetPath, baseBranch];
+
+		const addRes = spawnSync("git", gitArgs, {
+			cwd: root,
+			env: getCleanGitEnv(),
+			encoding: "utf8",
+			timeout: 15_000,
+		});
+		if (addRes.status !== 0) {
+			return { success: false, error: addRes.stderr.trim() || `git worktree add failed` };
+		}
+
+		// Symlink the parent's node_modules so tooling works without a fresh install.
+		const nodeModulesSrc = join(root, "node_modules");
+		const nodeModulesDest = join(targetPath, "node_modules");
+		if (existsSync(nodeModulesSrc) && !existsSync(nodeModulesDest)) {
+			try {
+				symlinkSync(nodeModulesSrc, nodeModulesDest, "dir");
+			} catch {}
+		}
+
+		return { success: true, worktreePath: targetPath };
+	} catch (e: any) {
+		return { success: false, error: e?.message ?? String(e) };
+	}
+}
+
+function registeredWorktreePaths(root: string): string[] | undefined {
+	const res = spawnSync("git", ["worktree", "list", "--porcelain"], {
+		cwd: root,
+		encoding: "utf8",
+		timeout: 10_000,
+		env: getCleanGitEnv(),
+	});
+	if (res.status !== 0) return undefined;
+	return res.stdout
+		.split("\n")
+		.filter((line) => line.startsWith("worktree "))
+		.map((line) => line.slice("worktree ".length))
+		.filter((path) => path.length > 0);
+}
+
+export function cleanupGitWorktree(
+	worktreePath: string,
+	root = getWorkspaceRoot(),
+): { success: boolean; error?: string } {
+	try {
+		if (!existsSync(worktreePath)) {
+			return { success: false, error: `Worktree path '${worktreePath}' does not exist.` };
+		}
+
+		// Ownership validation: the path must live under the configured worktree
+		// storage directory AND be a registered worktree of this repository. This
+		// refuses arbitrary directories, other repos' worktrees, and the primary
+		// working tree - cleanup must never be an unrestricted delete primitive.
+		const resolved = resolve(worktreePath);
+		const storageBase = resolve(getWorktreeStorageDir(root));
+		if (resolved !== storageBase && !resolved.startsWith(storageBase + sep)) {
+			return {
+				success: false,
+				error: `Refusing to clean up '${worktreePath}': path is outside the worktree storage directory (${storageBase}).`,
+			};
+		}
+		const registered = registeredWorktreePaths(root);
+		if (!registered) {
+			return { success: false, error: "Failed to list registered worktrees - aborting cleanup." };
+		}
+		const resolvedRegistered = registered.map((path) => resolve(path));
+		if (!resolvedRegistered.includes(resolved)) {
+			return {
+				success: false,
+				error: `Refusing to clean up '${worktreePath}': not a registered worktree of this repository.`,
+			};
+		}
+		if (resolvedRegistered[0] === resolved) {
+			return { success: false, error: "Refusing to remove the primary working tree." };
+		}
+
+		// Snapshot: stage and commit remaining changes. If the snapshot cannot be
+		// established (hook failure, missing identity, lock error, timeout), abort -
+		// never destroy uncommitted work.
+		const addArgs = ["add", "-A", "--", "."];
+		try {
+			// Exclude the plugin-created node_modules symlink so repos that do not
+			// ignore it never commit a machine-local link.
+			if (lstatSync(join(resolved, "node_modules")).isSymbolicLink()) {
+				addArgs.push(":(exclude)node_modules");
+			}
+		} catch {}
+		const addRes = spawnSync("git", addArgs, {
+			cwd: worktreePath,
+			env: getCleanGitEnv(),
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (addRes.status !== 0) {
+			return {
+				success: false,
+				error: `Snapshot failed (git add: ${(addRes.stderr ?? "").trim()}) - worktree left intact.`,
+			};
+		}
+		const commitRes = spawnSync(
+			"git",
+			["commit", "-m", "chore(worktree): auto-snapshot before cleanup", "--allow-empty"],
+			{ cwd: worktreePath, env: getCleanGitEnv(), encoding: "utf8", timeout: 5_000 },
+		);
+		if (commitRes.status !== 0) {
+			return {
+				success: false,
+				error: `Snapshot failed (git commit: ${(commitRes.stderr ?? "").trim().split("\n").pop()?.trim() ?? "unknown error"}) - worktree left intact.`,
+			};
+		}
+
+		const res = spawnSync("git", ["worktree", "remove", "--force", worktreePath], {
+			cwd: root,
+			env: getCleanGitEnv(),
+			encoding: "utf8",
+			timeout: 10_000,
+		});
+		if (res.status !== 0) {
+			// A failed git removal is an error - never authorization for a raw
+			// recursive delete of the directory.
+			return { success: false, error: res.stderr.trim() || "git worktree remove failed." };
+		}
+
+		return { success: true };
+	} catch (e: any) {
+		return { success: false, error: e?.message ?? String(e) };
+	}
+}

package/src/policies/boundary.ts

@@ -0,0 +1,248 @@
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import type { ShellMutation } from "../lib/types.ts";
+import {
+	getWorkspaceRoot,
+	getWorkspaceRootReal,
+	recordMutation,
+} from "../lib/state.ts";
+import { shellWords, unwrapShellCommand } from "../lib/utils.ts";
+import { isProtectedPath, PROTECTED_PATH_REASON } from "./tamper.ts";
+import { isSecretPath, secretIn } from "./secrets.ts";
+import { onProtectedBranch, branchGuardReason } from "./git.ts";
+import {
+	effectiveTodos,
+	effectiveTodoOwnerSessionID,
+	hasActiveTodo,
+} from "./todo.ts";
+
+export function isPathOutsideWorkspace(targetPath: string, root: string): boolean {
+	if (!targetPath) return false;
+	const resolved = resolve(root, targetPath);
+	const normalizedRoot = root.endsWith("/") ? root : root + "/";
+	if (resolved !== root && !resolved.startsWith(normalizedRoot)) {
+		return true;
+	}
+	const realRootVal = getWorkspaceRootReal();
+	try {
+		const real = realpathSync(resolved);
+		const realRoot = realRootVal.endsWith("/") ? realRootVal : realRootVal + "/";
+		if (real !== realRootVal && !real.startsWith(realRoot)) {
+			return true;
+		}
+	} catch {
+		let curr = resolved;
+		while (curr && curr !== "/" && curr !== ".") {
+			const parent = resolve(curr, "..");
+			if (parent === curr) break;
+			curr = parent;
+			try {
+				const realParent = realpathSync(curr);
+				const realRoot = realRootVal.endsWith("/") ? realRootVal : realRootVal + "/";
+				if (realParent !== realRootVal && !realParent.startsWith(realRoot)) {
+					return true;
+				}
+				break;
+			} catch {}
+		}
+	}
+	return false;
+}
+
+export function extractPatchPaths(patchText: string): string[] {
+	const paths: string[] = [];
+	const markerRe =
+		/^\*\*\*\s+(?:Add File|Update File|Delete File|Move to|Move from):\s*(\S+)/gm;
+	let match: RegExpExecArray | null;
+	while ((match = markerRe.exec(patchText)) !== null) {
+		if (match[1]) paths.push(match[1]);
+	}
+	const diffRe = /^(?:---|\+\+\+)\s+(?:[ab]\/)?(\S+)/gm;
+	while ((match = diffRe.exec(patchText)) !== null) {
+		if (match[1] && match[1] !== "/dev/null") paths.push(match[1]);
+	}
+	return paths;
+}
+
+export function shellMutationIn(segment: string): ShellMutation | undefined {
+	const redirectMatch = segment.match(
+		/(?:^|\s|>)(?:[0-9]*>>?)\s*["']?([^\s>&|;"']+)/,
+	);
+	if (redirectMatch?.[1]) {
+		if (/^\/dev\/(?:null|stdout|stderr|tty|fd\/\d+)$/.test(redirectMatch[1])) {
+			return undefined;
+		}
+		return {
+			kind: "redirect",
+			target: redirectMatch[1],
+			what: `file redirect to '${redirectMatch[1]}'`,
+		};
+	}
+	const teeMatch = segment.match(/\btee\s+(?:-a\s+)?["']?([^\s;&|"']+)/);
+	if (teeMatch?.[1]) {
+		return {
+			kind: "command",
+			target: teeMatch[1],
+			what: `tee to '${teeMatch[1]}'`,
+		};
+	}
+	const sedMatch = segment.match(/\bsed\s+(?:-(?:[a-zA-Z]*i[a-zA-Z]*|i\S*)\s+)+[^\s;&|]+/);
+	if (sedMatch) {
+		const tokens = sedMatch[0]!.split(/\s+/);
+		const target = tokens[tokens.length - 1];
+		return { kind: "command", target, what: `sed -i on '${target}'` };
+	}
+	const transfer = filesystemTransferInfo(segment);
+	if (transfer?.destination) {
+		return {
+			kind: "command",
+			target: transfer.destination,
+			what: `copy/move/link to '${transfer.destination}'`,
+		};
+	}
+	const fsMutationMatch = segment.match(
+		/\b(?:touch|mkdir|rm|unlink|rmdir|ln)\b[^|;&]*\s+["']?([^\s;&|"']+)["']?\s*$/,
+	);
+	if (fsMutationMatch?.[1] && !fsMutationMatch[1].startsWith("-")) {
+		return {
+			kind: "command",
+			target: fsMutationMatch[1],
+			what: `filesystem mutation of '${fsMutationMatch[1]}'`,
+		};
+	}
+	const copyMatch = segment.match(
+		/\b(?:cp|mv|rsync|install|cpio|scp|wget|curl)\b[^|;&]*?(-o\s+)?(["']?)([^\s;&|"']+)\2?\s*$/,
+	);
+	if (copyMatch?.[3] && /\b(?:cp|mv|rsync|install)\b/.test(segment)) {
+		return {
+			kind: "command",
+			target: copyMatch[3],
+			what: `copy/move to '${copyMatch[3]}'`,
+		};
+	}
+	if (/\bgit\s+(?:apply|am)\b/.test(segment)) {
+		return { kind: "command", what: "git apply/am (patch via shell)" };
+	}
+	return undefined;
+}
+
+export function simpleFilesystemMutations(segment: string): ShellMutation[] {
+	const words = shellWords(unwrapShellCommand(segment));
+	const command = words[0];
+	if (!command || !new Set(["touch", "mkdir", "rm", "unlink", "rmdir"]).has(command)) {
+		return [];
+	}
+	return words
+		.slice(1)
+		.filter((word) => !word.startsWith("-"))
+		.map((target) => ({
+			kind: "command" as const,
+			target,
+			what: `filesystem mutation of '${target}'`,
+		}));
+}
+
+export function filesystemTransferInfo(
+	segment: string,
+): { sources: string[]; destination?: string } | undefined {
+	const words = shellWords(unwrapShellCommand(segment));
+	if (!words[0] || !new Set(["cp", "mv", "ln"]).has(words[0])) return undefined;
+	const operands: string[] = [];
+	let targetDirectory: string | undefined;
+	for (let i = 1; i < words.length; i++) {
+		const word = words[i]!;
+		if (word === "-t" || word === "--target-directory") {
+			targetDirectory = words[++i];
+			continue;
+		}
+		if (word.startsWith("--target-directory=")) {
+			targetDirectory = word.slice("--target-directory=".length);
+			continue;
+		}
+		if (word.startsWith("-")) continue;
+		operands.push(word);
+	}
+	if (targetDirectory) return { sources: operands, destination: targetDirectory };
+	return {
+		sources: operands.slice(0, -1),
+		destination: operands.at(-1),
+	};
+}
+
+export function secretSourceInFilesystemCommand(segment: string): string | undefined {
+	const transfer = filesystemTransferInfo(segment);
+	if (!transfer) return undefined;
+	for (const source of transfer.sources) {
+		if (isSecretPath(source)) return source;
+	}
+	return undefined;
+}
+
+export async function guardShellMutation(
+	command: string,
+	sessionID: string | undefined,
+): Promise<string | undefined> {
+	const root = getWorkspaceRoot();
+	let hasMutation = false;
+	for (const segment of command.split(/[\n|;&]+/)) {
+		const secretSource = secretSourceInFilesystemCommand(segment);
+		if (secretSource) {
+			return `Blocked: shell command would copy, move, or link sensitive file '${secretSource}' under a non-secret name.`;
+		}
+		// mv mutates its SOURCES too (they are removed from their origin), so
+		// sources must respect the same boundaries as mutation targets: no
+		// moving files in from outside the workspace, no moving protected
+		// (settings/plugin) files to innocuous names.
+		const transfer = filesystemTransferInfo(segment);
+		if (transfer && shellWords(unwrapShellCommand(segment))[0] === "mv") {
+			for (const source of transfer.sources) {
+				if (isProtectedPath(source)) {
+					return PROTECTED_PATH_REASON;
+				}
+				if (isPathOutsideWorkspace(source, root)) {
+					return `Blocked: mv would remove source '${source}' from outside the workspace root (${root}). File mutations must stay within the workspace.`;
+				}
+			}
+		}
+		const simpleMutations = simpleFilesystemMutations(segment);
+		const fallbackMutation = shellMutationIn(segment.trim());
+		const mutations = simpleMutations.length > 0
+			? simpleMutations
+			: fallbackMutation
+				? [fallbackMutation]
+				: [];
+		for (const mutation of mutations) {
+			hasMutation = true;
+			const secret = secretIn(segment);
+			if (secret) {
+				return `Blocked: shell file mutation payload appears to contain a ${secret}. Secrets must not be written to disk from agent commands.`;
+			}
+			const target = mutation.target ?? "";
+			if (target && isProtectedPath(target)) {
+				return PROTECTED_PATH_REASON;
+			}
+			if (target && isPathOutsideWorkspace(target, root)) {
+				// The workspace boundary has no override: a write outside the
+				// workspace is out of bounds even with WORKFLOW_GUARD_ALLOW_LIVE
+				// (that override covers live-system commands, not the boundary).
+				return `Blocked: shell mutation '${mutation.what}' targets a path outside the workspace root (${root}). All changes must stay within the workspace.`;
+			}
+			if (onProtectedBranch(root)) {
+				return branchGuardReason();
+			}
+			const todos = await effectiveTodos(sessionID);
+			if (todos !== undefined && !hasActiveTodo(todos)) {
+				return (
+					"Blocked: shell file mutation with no active todo item. " +
+					"Break the request down with todowrite first, then apply " +
+					"changes (the same gates apply to shell redirects, tee, " +
+					"sed -i, cp/mv and git apply as to the edit tools)."
+				);
+			}
+		}
+	}
+	if (hasMutation) {
+		recordMutation(await effectiveTodoOwnerSessionID(sessionID));
+	}
+	return undefined;
+}