opencode-workflow-guard 1.3.1 → 1.3.2

package/README.md

@@ -27,7 +27,7 @@ Add to your project's `opencode.json` or global `~/.config/opencode/opencode.jso
 
 ```bash
 npm run typecheck    # Strict TypeScript check (0 errors)
-npm test             # Run 320+ unit and adversarial tests
+npm test             # Run 400+ unit and adversarial tests
 npm run test:all     # Run full verification suite (typecheck + unit + live e2e)
 ```
 
@@ -43,11 +43,11 @@ opencode-workflow-guard/
 │   ├── policies/              # Per-policy implementations (task gate, git, secrets, shell-safety, ...)
 │   └── lib/                   # Engine services (state, verify, audit, review, worktree, utils, types)
 ├── test/                      # Test suites
-│   ├── test.mts               # 320+ in-memory unit & adversarial tests
+│   ├── test.mts               # 400+ in-memory unit & adversarial tests
 │   └── test-e2e.mts           # npm tarball resolution + live runtime OpenCode loader tests
 ├── docs/                      # In-depth documentation & guides
 │   ├── installation.md        # Full setup options, worktrees & permissions
-│   ├── policies.md            # Detailed 23-policy reference & overrides
+│   ├── policies.md            # Detailed 24-policy reference & overrides
 │   ├── troubleshooting.md     # Error diagnosis & bypass explanations
 │   └── testing.md             # Test architecture & coverage matrix
 ├── .changeset/                # Fragment-based versioning & release changelogs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "OpenCode plugin enforcing workflow discipline through deterministic tool.execute.before hooks",
   "license": "MIT",
   "type": "module",

package/src/lib/audit.ts

@@ -1,4 +1,4 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, openSync, readSync, closeSync, statSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import type { AuditEntry, VerifyResult } from "./types.ts";
@@ -46,13 +46,32 @@ export function loadVerifyCache(): VerifyResult | undefined {
 	return undefined;
 }
 
+/**
+ * Reads recent audit entries from the end of the JSONL audit log with a bounded
+ * buffer window to prevent memory spikes on long-lived installations.
+ */
 export function getRecentAuditEntries(limit = 10): AuditEntry[] {
 	try {
 		if (!existsSync(AUDIT_FILE)) return [];
-		const lines = readFileSync(AUDIT_FILE, "utf8").trim().split("\n");
+		const stat = statSync(AUDIT_FILE);
+		if (stat.size === 0) return [];
+
+		const maxBytesToRead = Math.min(stat.size, 65_536);
+		const buffer = Buffer.alloc(maxBytesToRead);
+		const fd = openSync(AUDIT_FILE, "r");
+		try {
+			readSync(fd, buffer, 0, maxBytesToRead, stat.size - maxBytesToRead);
+		} finally {
+			closeSync(fd);
+		}
+
+		const text = buffer.toString("utf8");
+		const lines = text.trim().split("\n");
+		const completeLines = maxBytesToRead < stat.size ? lines.slice(1) : lines;
+
 		const entries: AuditEntry[] = [];
-		for (let i = lines.length - 1; i >= 0 && entries.length < limit; i--) {
-			const line = lines[i]?.trim();
+		for (let i = completeLines.length - 1; i >= 0 && entries.length < limit; i--) {
+			const line = completeLines[i]?.trim();
 			if (line) {
 				try {
 					entries.push(JSON.parse(line));

package/src/policies/boundary.ts

@@ -1,5 +1,6 @@
 import { realpathSync } from "node:fs";
-import { resolve } from "node:path";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
 import type { ShellMutation } from "../lib/types.ts";
 import {
 	getWorkspaceRoot,
@@ -16,9 +17,47 @@ import {
 	hasActiveTodo,
 } from "./todo.ts";
 
+/**
+ * Expands leading `~`, `~user`, `$HOME`, and `${HOME}` in candidate targets so
+ * shell-level expansion cannot evade workspace boundary checks. Paths that
+ * contain unresolvable `$VARIABLE` references return `null` so callers treat
+ * indeterminate destinations as outside-workspace (fail-closed).
+ */
+export function expandShellTargetPath(targetPath: string): string | null {
+	if (!targetPath) return targetPath;
+	const trimmed = targetPath.trim().replace(/^["']|["']$/g, "");
+	if (!trimmed) return trimmed;
+
+	const home = process.env.HOME || homedir();
+
+	if (trimmed === "~") return home;
+	if (trimmed.startsWith("~/") || trimmed.startsWith("~\\")) {
+		return join(home, trimmed.slice(2));
+	}
+	if (/^~[A-Za-z0-9_.-]+(?:\/|\\|$)/.test(trimmed)) {
+		const parts = trimmed.slice(1).split(/[/\\]/);
+		const user = parts[0]!;
+		const rest = parts.slice(1);
+		return join(dirname(home), user, ...rest);
+	}
+
+	let out = trimmed;
+	if (/^\$(?:HOME|\{HOME\})(?=$|[/\\])/.test(out)) {
+		out = out.replace(/^\$(?:HOME|\{HOME\})/, home);
+	}
+
+	if (out.includes("$")) {
+		return null;
+	}
+
+	return out;
+}
+
 export function isPathOutsideWorkspace(targetPath: string, root: string): boolean {
 	if (!targetPath) return false;
-	const resolved = resolve(root, targetPath);
+	const expanded = expandShellTargetPath(targetPath);
+	if (expanded === null) return true;
+	const resolved = resolve(root, expanded);
 	const normalizedRoot = root.endsWith("/") ? root : root + "/";
 	if (resolved !== root && !resolved.startsWith(normalizedRoot)) {
 		return true;
@@ -64,26 +103,53 @@ export function extractPatchPaths(patchText: string): string[] {
 	return paths;
 }
 
+export function teeTargetsIn(segment: string): string[] {
+	const words = shellWords(unwrapShellCommand(segment));
+	if (words[0] !== "tee") {
+		const teeIdx = words.indexOf("tee");
+		if (teeIdx === -1) return [];
+	}
+	const startIdx = words[0] === "tee" ? 1 : words.indexOf("tee") + 1;
+	const targets: string[] = [];
+	let stopFlags = false;
+	for (let i = startIdx; i < words.length; i++) {
+		const w = words[i]!;
+		if (/^[|;&<>]/.test(w)) break;
+		if (!stopFlags) {
+			if (w === "--") {
+				stopFlags = true;
+				continue;
+			}
+			if (w.startsWith("-")) continue;
+		}
+		targets.push(w);
+	}
+	return targets;
+}
+
 export function shellMutationIn(segment: string): ShellMutation | undefined {
 	const redirectMatch = segment.match(
-		/(?:^|\s|>)(?:[0-9]*>>?)\s*["']?([^\s>&|;"']+)/,
+		/(?:^|[\s>]|(?<=[^\s"']))([0-9]*&?>>?&?)\s*["']?([^\s>&|;"']+)/,
 	);
-	if (redirectMatch?.[1]) {
-		if (/^\/dev\/(?:null|stdout|stderr|tty|fd\/\d+)$/.test(redirectMatch[1])) {
-			return undefined;
+	if (redirectMatch?.[1] && redirectMatch?.[2]) {
+		const op = redirectMatch[1];
+		const target = redirectMatch[2];
+		// Filter fd duplication (e.g. 2>&1, >&2) where target is purely an fd number
+		const isFdDup = op.endsWith("&") && /^\d+$/.test(target);
+		if (!isFdDup && !/^\/dev\/(?:null|stdout|stderr|tty|fd\/\d+)$/.test(target)) {
+			return {
+				kind: "redirect",
+				target,
+				what: `file redirect to '${target}'`,
+			};
 		}
-		return {
-			kind: "redirect",
-			target: redirectMatch[1],
-			what: `file redirect to '${redirectMatch[1]}'`,
-		};
 	}
-	const teeMatch = segment.match(/\btee\s+(?:-a\s+)?["']?([^\s;&|"']+)/);
-	if (teeMatch?.[1]) {
+	const teeTargets = teeTargetsIn(segment);
+	if (teeTargets.length > 0) {
 		return {
 			kind: "command",
-			target: teeMatch[1],
-			what: `tee to '${teeMatch[1]}'`,
+			target: teeTargets[0]!,
+			what: `tee to '${teeTargets[0]!}'`,
 		};
 	}
 	const sedMatch = segment.match(/\bsed\s+(?:-(?:[a-zA-Z]*i[a-zA-Z]*|i\S*)\s+)+[^\s;&|]+/);
@@ -205,12 +271,20 @@ export async function guardShellMutation(
 			}
 		}
 		const simpleMutations = simpleFilesystemMutations(segment);
+		const teeTargets = teeTargetsIn(segment);
+		const teeMutations: ShellMutation[] = teeTargets.map((target) => ({
+			kind: "command" as const,
+			target,
+			what: `tee to '${target}'`,
+		}));
 		const fallbackMutation = shellMutationIn(segment.trim());
 		const mutations = simpleMutations.length > 0
 			? simpleMutations
-			: fallbackMutation
-				? [fallbackMutation]
-				: [];
+			: teeMutations.length > 0
+				? teeMutations
+				: fallbackMutation
+					? [fallbackMutation]
+					: [];
 		for (const mutation of mutations) {
 			hasMutation = true;
 			const secret = secretIn(segment);

package/src/policies/git.ts

@@ -44,6 +44,9 @@ const GIT_GLOBAL_BOOLEAN_OPTIONS = new Set([
 	"--exec-path",
 ]);
 
+const GIT_ENV_DIR_RE =
+	/(?:^|\s)(?:env\s+(?:-\S+\s+)*)?(?:GIT_DIR|GIT_WORK_TREE|GIT_COMMON_DIR)=(?:"([^"]*)"|'([^']*)'|(\S+))/;
+
 export function parseGitInvocation(command: string): GitInvocation | undefined {
 	const root = getWorkspaceRoot();
 	const tokens = unwrapShellWords(command);
@@ -51,12 +54,22 @@ export function parseGitInvocation(command: string): GitInvocation | undefined {
 	let i = 1;
 	let repoDir = root;
 	let sawDirOption = false;
+
+	const envDirMatch = command.match(GIT_ENV_DIR_RE);
+	if (envDirMatch) {
+		const envVal = envDirMatch[1] ?? envDirMatch[2] ?? envDirMatch[3];
+		if (envVal) {
+			repoDir = resolve(root, envVal);
+			sawDirOption = true;
+		}
+	}
+
 	while (i < tokens.length) {
 		const tok = tokens[i]!;
 		if (GIT_DIR_OPTION_TAKES_VALUE.has(tok)) {
 			const value = tokens[i + 1];
 			if (value === undefined) return { repoDir, rest: "" };
-			if (tok === "-C" || tok === "--git-dir") {
+			if (tok === "-C" || tok === "--git-dir" || tok === "--work-tree") {
 				repoDir = resolve(root, value);
 				sawDirOption = true;
 			}
@@ -67,6 +80,9 @@ export function parseGitInvocation(command: string): GitInvocation | undefined {
 			if (tok.startsWith("--git-dir=")) {
 				repoDir = resolve(root, tok.slice("--git-dir=".length));
 				sawDirOption = true;
+			} else if (tok.startsWith("--work-tree=")) {
+				repoDir = resolve(root, tok.slice("--work-tree=".length));
+				sawDirOption = true;
 			}
 			i += 1;
 			continue;

package/src/policies/interpreter.ts

@@ -1,7 +1,10 @@
+import { isSecretPath } from "./secrets.ts";
+import { isPathOutsideWorkspace } from "./boundary.ts";
+
 export function extractInterpreterPayload(segment: string): string[] {
 	const payloads: string[] = [];
 	const inlineMatch = segment.match(
-		/\b(?:python3?|node|perl|ruby|osascript)\s+(?:-[a-zA-Z]*[ce]\s+)(?:"([^"]*)"|'([^']*)')/i,
+		/\b(?:python3?|node|perl|ruby|osascript|bash|sh|zsh|dash|ksh)\s+(?:-[a-zA-Z]*[ce]\s+)(?:"([^"]*)"|'([^']*)')/i,
 	);
 	if (inlineMatch?.[1] || inlineMatch?.[2]) {
 		payloads.push(inlineMatch[1] ?? inlineMatch[2] ?? "");
@@ -26,3 +29,52 @@ export function extractInterpreterPayload(segment: string): string[] {
 	}
 	return payloads;
 }
+
+const FILE_ACCESS_VERB_RE =
+	/\b(?:open|cat|read|readFile|readFileSync|read_text|readTextFile|write|writeFile|writeFileSync|write_text|writeTextFile|source|slurp|appendFile|appendFileSync|createReadStream|createWriteStream|load|loads|exec|execSync|spawn|spawnSync)\b/i;
+
+/**
+ * Detects sensitive credential/secret file targets referenced inside inline
+ * interpreter scripts or subshells.
+ */
+export function secretPathInPayload(payload: string): string | undefined {
+	if (!FILE_ACCESS_VERB_RE.test(payload)) return undefined;
+	const tokens = payload.match(/["'][^"']*["']|[^\s(){}[\];,|&<>]+/g) ?? [];
+	for (const token of tokens) {
+		const cleaned = token.replace(/^["']|["']$/g, "");
+		if (cleaned && isSecretPath(cleaned)) {
+			return cleaned;
+		}
+	}
+	return undefined;
+}
+
+const WRITE_VERB_RE =
+	/\b(?:write|writeFile|writeFileSync|write_text|writeTextFile|appendFile|appendFileSync|createWriteStream|unlink|unlinkSync|rm|rmSync|rmdir|rmdirSync|mkdir|mkdirSync|rename|renameSync|copy|cp|cpSync|truncate|move|shutil|remove|delete)\b|\bopen\s*\(\s*["'][^"']*["']\s*,\s*["'][wa]/i;
+
+/**
+ * Detects workspace boundary escapes (writes/redirects to paths outside the
+ * workspace root) initiated from inline interpreter payloads.
+ */
+export function outsideWritePathInPayload(payload: string, root: string): string | undefined {
+	const hasWrite = WRITE_VERB_RE.test(payload) || /[>]{1,2}\s*\S/.test(payload);
+	if (!hasWrite) return undefined;
+
+	const candidates = new Set<string>();
+	const redirectMatches = payload.matchAll(/[>]{1,2}\s*["']?([^\s;&"'|)]+)/g);
+	for (const m of redirectMatches) {
+		if (m[1]) candidates.add(m[1]);
+	}
+	const literalMatches = payload.matchAll(/["']([^"']{2,})["']/g);
+	for (const m of literalMatches) {
+		if (m[1]) candidates.add(m[1]);
+	}
+
+	for (const candidate of candidates) {
+		if (/^\/dev\/(?:null|stdout|stderr|tty|fd\/\d+)$/.test(candidate)) continue;
+		if (isPathOutsideWorkspace(candidate, root)) {
+			return candidate;
+		}
+	}
+	return undefined;
+}

package/src/policies/secrets.ts

@@ -100,18 +100,43 @@ export function isEnvFilePath(targetPath: string): boolean {
 
 /**
  * Parses a raw .env file and returns a sanitized schema mask where variable
- * names and comment structures are preserved, but sensitive values are
- * redacted to '********'.
+ * names and comment structures are preserved, but sensitive values (including
+ * multiline secret continuations) are redacted to '********'.
  */
 export function generateMaskedEnvSchema(content: string): string {
 	const lines = content.split("\n");
+	let inMultilineQuote: string | null = null;
+
 	return lines
 		.map((line) => {
 			const trimmed = line.trim();
-			if (!trimmed || trimmed.startsWith("#")) return line;
+			if (!trimmed || trimmed.startsWith("#")) {
+				inMultilineQuote = null;
+				return line;
+			}
+
+			if (inMultilineQuote) {
+				if (trimmed.endsWith(inMultilineQuote) || trimmed.includes(inMultilineQuote)) {
+					inMultilineQuote = null;
+				}
+				return "********";
+			}
+
 			const eqIdx = line.indexOf("=");
-			if (eqIdx === -1) return line;
+			if (eqIdx === -1) {
+				return "********";
+			}
+
 			const key = line.slice(0, eqIdx);
+			const val = line.slice(eqIdx + 1).trim();
+
+			if (
+				(val.startsWith('"') && !val.slice(1).includes('"')) ||
+				(val.startsWith("'") && !val.slice(1).includes("'"))
+			) {
+				inMultilineQuote = val[0]!;
+			}
+
 			return `${key}=********`;
 		})
 		.join("\n");

package/src/policies/shell-safety.ts

@@ -97,6 +97,17 @@ export function checkInteractiveTtyCommand(command: string): { isInteractive: bo
 	return { isInteractive: false };
 }
 
+/**
+ * Escapes strings safely for interpolation into AppleScript string literals.
+ * Replaces newlines/CRs with spaces, escapes backslashes first, then double quotes.
+ */
+export function escapeAppleScriptString(str: string): string {
+	return str
+		.replace(/[\r\n]+/g, " ")
+		.replace(/\\/g, "\\\\")
+		.replace(/"/g, '\\"');
+}
+
 /**
  * Dispatches a native OS desktop notification (macOS osascript or Linux notify-send)
  * on important guard events (policy blocks, verification completion).
@@ -104,11 +115,11 @@ export function checkInteractiveTtyCommand(command: string): { isInteractive: bo
  */
 export function sendDesktopNotification(title: string, message: string): void {
 	if (process.env.WORKFLOW_GUARD_NOTIFY === "0") return;
-	const safeTitle = title.replace(/"/g, '\\"');
-	const safeMsg = message.slice(0, 150).replace(/"/g, '\\"');
 
 	try {
 		if (process.platform === "darwin") {
+			const safeTitle = escapeAppleScriptString(title);
+			const safeMsg = escapeAppleScriptString(message.slice(0, 150));
 			const child = spawn(
 				"osascript",
 				["-e", `display notification "${safeMsg}" with title "${safeTitle}"`],
@@ -117,6 +128,8 @@ export function sendDesktopNotification(title: string, message: string): void {
 			child.on("error", () => {});
 			child.unref();
 		} else if (process.platform === "linux") {
+			const safeTitle = title.replace(/[\r\n\0]/g, " ");
+			const safeMsg = message.slice(0, 150).replace(/[\0]/g, "");
 			const child = spawn("notify-send", [safeTitle, safeMsg], {
 				stdio: "ignore",
 				detached: true,

package/src/workflow-guard.ts

@@ -201,8 +201,12 @@ import { isSecretPath, secretIn, secretFileReadIn, isEnvFilePath, generateMasked
 
 export { isSecretPath, isEnvFilePath, generateMaskedEnvSchema };
 
-import { extractInterpreterPayload } from "./policies/interpreter.ts";
-export { extractInterpreterPayload };
+import {
+	extractInterpreterPayload,
+	secretPathInPayload,
+	outsideWritePathInPayload,
+} from "./policies/interpreter.ts";
+export { extractInterpreterPayload, secretPathInPayload, outsideWritePathInPayload };
 
 import { branchHasDocumentationChange } from "./policies/docs.ts";
 export { branchHasDocumentationChange };
@@ -211,13 +215,14 @@ import {
 	checkInteractiveTtyCommand,
 	checkPackageHygiene,
 	sendDesktopNotification,
+	escapeAppleScriptString,
 } from "./policies/shell-safety.ts";
 
 import { checkCompletionClaims } from "./policies/completion.ts";
 
 export { checkCompletionClaims };
 
-export { checkInteractiveTtyCommand, checkPackageHygiene, sendDesktopNotification };
+export { checkInteractiveTtyCommand, checkPackageHygiene, sendDesktopNotification, escapeAppleScriptString };
 
 const SHELL_TOOL_NAMES = new Set(["bash", "run_commands", "execute_command", "shell"]);
 
@@ -610,8 +615,18 @@ async function guardToolCallImpl(
 		}
 
 		// ── Policy 18: interpreter inline evasion scanner ──
-		if (!allowLive) {
-			for (const payload of extractInterpreterPayload(command)) {
+		for (const payload of extractInterpreterPayload(command)) {
+			// Workspace boundary check inside inline interpreter payloads has no
+			// allow-live override (same invariant as file redirects).
+			const outsidePath = outsideWritePathInPayload(payload, currentRoot);
+			if (outsidePath) {
+				logBlock(
+					`[workflow-guard] blocked interpreter payload writing outside workspace: ${outsidePath}`,
+				);
+				return `Blocked: inline interpreter script targets file '${outsidePath}' outside workspace root (${currentRoot}). All changes must stay within the workspace.`;
+			}
+
+			if (!allowLive) {
 				const normPayload = normalizeGitCommands(normalize(payload));
 				const liveCheck = liveMutationIn(normPayload);
 				if (liveCheck) {
@@ -626,6 +641,16 @@ async function guardToolCallImpl(
 					);
 					return PROTECTED_PATH_REASON;
 				}
+				const secretPath = secretPathInPayload(payload);
+				if (secretPath) {
+					logBlock(
+						`[workflow-guard] blocked interpreter payload accessing secret file: ${secretPath}`,
+					);
+					return (
+						`Blocked: reading sensitive credential/secret file '${secretPath}' via inline interpreter script is not permitted. ` +
+						"Reference environment variables by name or inspect safe templates (e.g. .env.example) instead."
+					);
+				}
 			}
 		}
 
@@ -993,14 +1018,20 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 						.describe("Base ref to diff against (default: origin/main, origin/master, main)"),
 				},
 				execute: async (args) => {
-					const bases = args.base
-						? [args.base]
+					const sanitizedBase =
+						typeof args.base === "string" &&
+						!args.base.startsWith("-") &&
+						!/[\s;'"\0]/.test(args.base)
+							? args.base
+							: undefined;
+					const bases = sanitizedBase
+						? [sanitizedBase]
 						: ["origin/main", "origin/master", "main", "master"];
 					let diffText = "";
 					for (const base of bases) {
 						const res = spawnSync(
 							"git",
-							["diff", `${base}...HEAD`],
+							["diff", "--", `${base}...HEAD`],
 							{ cwd: getWorkspaceRoot(), encoding: "utf8", timeout: 10_000 },
 						);
 						if (res.status === 0 && res.stdout.trim()) {
@@ -1009,7 +1040,7 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 						}
 					}
 					if (!diffText) {
-						const last = spawnSync("git", ["diff", "HEAD~1"], {
+						const last = spawnSync("git", ["diff", "--", "HEAD~1"], {
 							cwd: getWorkspaceRoot(),
 							encoding: "utf8",
 							timeout: 10_000,