opencode-workflow-guard 1.15.5 → 1.17.0

package/src/lib/plugin-instance.ts

@@ -0,0 +1,124 @@
+/**
+ * Process-local plugin instance registry.
+ *
+ * OpenCode 2 merges plugin arrays instead of replacing them, so naming the same
+ * package in both the global and the project config loads the same entrypoint
+ * twice under two ids. Two instances register duplicate hooks and duplicate
+ * tool definitions: every tool call is evaluated and audited twice, and the two
+ * instances can disagree about `effectiveRoot` in the same tick, which primes
+ * the process-global workspace latch from two roots.
+ *
+ * The first instance for a (module path, workspace root) key owns enforcement.
+ * A later instance with the same key stays inert and records a warn-level
+ * duplicate so the misconfiguration is visible in the audit trail. Different
+ * workspace roots are legitimate (concurrent loops share one process) and get
+ * independent keys.
+ */
+
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+import { audit } from "./audit.ts";
+
+export interface PluginInstanceInfo {
+	/** Stable key: resolved module path plus resolved workspace root. */
+	key: string;
+	modulePath: string;
+	workspaceRoot: string;
+	/** True when this key already had an active instance in this process. */
+	duplicate: boolean;
+}
+
+interface ActiveInstance {
+	modulePath: string;
+	workspaceRoot: string;
+	registrations: number;
+}
+
+// Deliberately process-global, not module-global: OpenCode can load the same
+// package twice from two distinct paths (a cache copy plus a source checkout),
+// and each copy evaluates this module separately. A `Symbol.for` slot on
+// `globalThis` gives both copies one registry so the duplicate stays visible
+// even when the module instances differ.
+const INSTANCE_REGISTRY = Symbol.for("opencode-workflow-guard.plugin-instances.v1");
+const globalRegistry = globalThis as unknown as Record<symbol, Map<string, ActiveInstance> | undefined>;
+const activeInstances: Map<string, ActiveInstance> =
+	globalRegistry[INSTANCE_REGISTRY] ?? (globalRegistry[INSTANCE_REGISTRY] = new Map());
+
+/** Resolved path of the loaded plugin module; the stable half of the key. */
+export function loadedPluginModulePath(moduleUrl: string = import.meta.url): string {
+	const lexical = (() => {
+		try {
+			return fileURLToPath(moduleUrl);
+		} catch {
+			return moduleUrl;
+		}
+	})();
+	try {
+		return realpathSync(lexical);
+	} catch {
+		return lexical;
+	}
+}
+
+function canonicalRoot(root: string): string {
+	try {
+		return realpathSync(resolve(root));
+	} catch {
+		return resolve(root);
+	}
+}
+
+export function pluginInstanceKey(modulePath: string, workspaceRoot: string): string {
+	return `${canonicalRoot(workspaceRoot)}::${modulePath}`;
+}
+
+/**
+ * Register one setup call. A duplicate key is journaled at warn level and the
+ * caller must stay inert: returning early is what makes the load count one
+ * policy decision per tool call instead of two.
+ */
+export function registerPluginInstance(options: {
+	modulePath?: string;
+	workspaceRoot: string;
+}): PluginInstanceInfo {
+	const modulePath = options.modulePath ?? loadedPluginModulePath();
+	const workspaceRoot = canonicalRoot(options.workspaceRoot);
+	const key = pluginInstanceKey(modulePath, workspaceRoot);
+	const existing = activeInstances.get(key);
+	if (existing) {
+		existing.registrations++;
+		audit({
+			ts: new Date().toISOString(),
+			tool: "plugin.instance",
+			decision: "allow",
+			phase: "event",
+			reason: "duplicate_plugin_load",
+			input: { instanceKey: key, modulePath, workspaceRoot, registrations: existing.registrations },
+		});
+		return { key, modulePath, workspaceRoot, duplicate: true };
+	}
+	activeInstances.set(key, { modulePath, workspaceRoot, registrations: 1 });
+	audit({
+		ts: new Date().toISOString(),
+		tool: "plugin.instance",
+		decision: "allow",
+		phase: "event",
+		reason: "plugin_loaded",
+		input: { instanceKey: key, modulePath, workspaceRoot },
+	});
+	return { key, modulePath, workspaceRoot, duplicate: false };
+}
+
+/** Drop one registration. The key is reusable once every registration is gone. */
+export function releasePluginInstance(key: string): void {
+	const existing = activeInstances.get(key);
+	if (!existing) return;
+	existing.registrations--;
+	if (existing.registrations <= 0) activeInstances.delete(key);
+}
+
+/** Test seam: forget every live instance so fixtures can re-register. */
+export function resetPluginInstancesForTesting(): void {
+	activeInstances.clear();
+}

package/src/lib/policy-posture.ts

@@ -0,0 +1,227 @@
+/**
+ * Static policy posture for OpenCode 2.
+ *
+ * Three enforcement seats exist, and this module feeds the only one a
+ * repository cannot lift. `ctx.permission.hook("evaluate")` and
+ * `execute.before` run inside the plugin, so removing the plugin removes them.
+ * Static policies are configuration the host evaluates itself.
+ *
+ * Two host shapes exist and they are not interchangeable:
+ *
+ * - **OpenCode 2.0.x** reads `experimental.policies` and requires
+ *   `action: "permission"`. Its evaluator matches the composite string
+ *   `<permission action>:<resource>` as a whole-string glob
+ *   (`opencode.config.policy` in the 2.0.15 binary). A deny surfaces as
+ *   "Blocked by configuration policy".
+ * - **OpenCode 2.1.x** reads a top-level `policies` array and requires
+ *   `action: "tool.use"` instead. It ignores `experimental.policies`.
+ *
+ * Each host silently ignores the key it does not read, which makes a
+ * single-key posture look applied while enforcing nothing. The default
+ * therefore emits both keys. `--format 2.0` and `--format next` remain for
+ * pinning one host, and the reason to avoid them is the failure above.
+ *
+ * Schema acceptance is not runtime acceptance: `@opencode/schema` 2.0.10
+ * admits a top-level `policies` array that the 2.0.15 runtime never reads.
+ * The envelopes below were verified by live denial canaries on both hosts,
+ * not by decoding config.
+ *
+ * The plugin never writes another tool's configuration. The caller prints the
+ * block and the operator decides where it lands, because a plugin that can
+ * install its own static rails has just moved them back inside the plugin.
+ */
+
+/** Static invariants: each one holds for every session, with no runtime input. */
+export interface StaticInvariant {
+	/** Stable id, used by tests and documentation. */
+	id: string;
+	/** Host permission action the rule applies to. */
+	action: string;
+	/** Resources denied for that action, before the `<action>:` prefix. */
+	resources: readonly string[];
+	/** Why this cannot be left to a runtime hook. */
+	reason: string;
+}
+
+/**
+ * The invariants, in the order they are emitted.
+ *
+ * Every entry is a denial. A posture that grants access would be a second,
+ * weaker policy engine living in a config file, and the plugin already owns
+ * that job.
+ */
+export const STATIC_INVARIANTS: readonly StaticInvariant[] = [
+	{
+		id: "protected-trunk-push",
+		action: "shell",
+		resources: [
+			// The host matches the whole command string, so `git push * main`
+			// covers `git push origin main` and `git push -f origin main`, while
+			// the refspec forms need their own entries.
+			"git push * main",
+			"git push * master",
+			"git push * HEAD:main",
+			"git push * HEAD:master",
+		],
+		reason:
+			"Pushing to protected trunk must stay blocked even when the plugin is absent or disabled. The runtime git policy already refuses this; the static rule removes the dependency on it. A whole-string glob cannot see a compound command line or an exotic refspec, so this is a floor, not a sandbox: the plugin seat covers the rest.",
+	},
+	{
+		id: "live-control-plane-write",
+		action: "edit",
+		resources: [
+			// No `~/` here. On 2.0.x, `~` and `$HOME` are expanded only for the
+			// `permissions` key, not for `experimental.policies`, so a tilde
+			// resource would never match an absolute path. A leading `*/` is
+			// version-independent and covers every home directory.
+			"*/.config/opencode/*",
+			"/etc/opencode/*",
+			"*/Library/Application Support/opencode/*",
+		],
+		reason:
+			"An agent that can edit the live control plane can rewrite the rules that constrain it, including the plugin list. The tamper policy is a runtime check; this rule is a configuration-level one.",
+	},
+	{
+		id: "secret-material-read",
+		action: "read",
+		resources: ["*/.ssh/*", "*id_rsa*"],
+		reason:
+			"Private keys should never enter a model context, regardless of which session or role asks. The secret policy depends on the plugin being loaded.",
+	},
+	{
+		id: "external-directory-widening",
+		action: "external_directory",
+		resources: ["*"],
+		reason:
+			"`external_directory` defaults to allow, so a foreign read needs no approval. Denying it statically is what keeps the write boundary a boundary rather than an advisory. This is the strict posture: drop this rule if cross-repository reads are part of normal work.",
+	},
+	{
+		id: "code-mode-surface",
+		action: "execute",
+		resources: ["*"],
+		reason:
+			"Code Mode wraps tools behind a single `execute` surface, and its nested calls reach the tool layer on a path this guard does not evaluate. Denying `execute` removes that surface where the host asserts the action. The qualified hosts (2.0.15 and 2.1.3) register no `execute` tool and never assert an `execute` permission action, so this rule is inert on both; the plugin's read-only pruning plus `execute.before` remain the coverage.",
+	},
+];
+
+export type PolicyPostureFormat = "2.0" | "next" | "both";
+
+export interface StaticPolicyRule {
+	action: string;
+	resource: string;
+	effect: "deny";
+}
+
+export interface PolicyPosture {
+	format: PolicyPostureFormat;
+	/**
+	 * Rules as `{ action, resource }` pairs with the resource unprefixed. The
+	 * host builds the `<action>:<resource>` string when it matches; `config`
+	 * holds the enveloped form that is actually pasted into a config file.
+	 */
+	rules: StaticPolicyRule[];
+	/** Config fragment, ready to print. Never written by the plugin. */
+	config: Record<string, unknown>;
+	/** Human-readable rationale per invariant, for the printed header. */
+	rationale: Array<{ id: string; reason: string }>;
+}
+
+/**
+ * Compose one rule. The host matches `resource` against `<action>:<resource>`,
+ * so the action name is part of the string, not a separate field.
+ */
+function ruleFor(invariant: StaticInvariant, resource: string): StaticPolicyRule {
+	return { action: invariant.action, resource, effect: "deny" };
+}
+
+function rulesFor(invariants: readonly StaticInvariant[]): StaticPolicyRule[] {
+	return invariants.flatMap((invariant) => invariant.resources.map((resource) => ruleFor(invariant, resource)));
+}
+
+/**
+ * Envelope a rule list for the target host.
+ *
+ * `2.0` uses `experimental.policies` with the `permission` action, which is
+ * what the 2.0.x evaluator compares. `next` uses the top-level `policies`
+ * array with `tool.use`, which is what 2.1.x reads. `both` emits each rule
+ * under its own host's key: neither host reads the other's key, so the
+ * duplicate cannot double-apply or conflict.
+ */
+function envelope(
+	format: PolicyPostureFormat,
+	rules: readonly StaticPolicyRule[],
+): Record<string, unknown> {
+	const legacy = {
+		experimental: {
+			policies: rules.map((rule) => ({
+				action: "permission",
+				resource: `${rule.action}:${rule.resource}`,
+				effect: rule.effect,
+			})),
+		},
+	};
+	const current = {
+		policies: rules.map((rule) => ({
+			action: "tool.use",
+			resource: `${rule.action}:${rule.resource}`,
+			effect: rule.effect,
+		})),
+	};
+	if (format === "2.0") return legacy;
+	if (format === "next") return current;
+	return { ...legacy, ...current };
+}
+
+export function buildPolicyPosture(options?: { format?: PolicyPostureFormat }): PolicyPosture {
+	const format = options?.format ?? "both";
+	const rules = rulesFor(STATIC_INVARIANTS);
+	return {
+		format,
+		rules,
+		config: envelope(format, rules),
+		rationale: STATIC_INVARIANTS.map((invariant) => ({ id: invariant.id, reason: invariant.reason })),
+	};
+}
+
+function commentLines(lines: readonly string[]): string {
+	return lines
+		.flatMap((line) => line.split("\n"))
+		.map((line) => (line.trim() ? `// ${line}` : "//"))
+		.join("\n");
+}
+
+/**
+ * Render the posture as JSONC.
+ *
+ * The header states precedence and residual risk, because the file that
+ * carries these rules is also the file an operator will trim. A trimmed rule
+ * that was never explained looks like cruft, and cruft gets deleted.
+ */
+export function renderPolicyPosture(options?: { format?: PolicyPostureFormat }): string {
+	const posture = buildPolicyPosture(options);
+	const header = commentLines([
+		"Workflow Guard static policy posture. Generated, never installed automatically.",
+		"",
+		`Target: OpenCode ${
+			posture.format === "2.0"
+				? "2.0.x only (experimental.policies, action \"permission\")"
+				: posture.format === "next"
+					? "2.1.x only (top-level policies, action \"tool.use\")"
+					: "2.0.x and 2.1.x (both keys; each host reads its own and ignores the other)"
+		}.`,
+		"",
+		"Precedence, highest first: managed preferences and Console policies, then /etc/opencode,",
+		"then ~/.config/opencode, then project opencode.json(c). Later rules win within one",
+		"ruleset, so keep these denies after any broad allow you add.",
+		"",
+		"Residual risk: policies are configuration. They do not sandbox plugin code, and any",
+		"process that can write the file that carries them can remove them. Place this block",
+		"in the system or global config, not in a project file.",
+		"",
+		"Every rule below is a deny. Nothing here grants access; runtime decisions stay with",
+		"the plugin's permission-evaluate and execute-before seats.",
+		"",
+		...posture.rationale.flatMap(({ id, reason }) => [`${id}: ${reason}`, ""]),
+	]);
+	return `${header}\n${JSON.stringify(posture.config, null, 2)}\n`;
+}

package/src/lib/read-only-tools.ts

@@ -0,0 +1,61 @@
+/**
+ * Tool pruning for read-only subagent roles.
+ *
+ * `execute.before` already denies a mutation from a read-only role, but only
+ * after the model has planned the call and the host has admitted it. The V2
+ * `session.hook("context")` sees the per-request tool snapshot, so the
+ * stronger invariant is to remove the mutating tools before the model can
+ * choose them.
+ *
+ * This is a narrowing only. The `execute.before` seat stays in place as the
+ * backstop: tools supplied by an ACP agent or a nested Code Mode call may not
+ * appear in the host snapshot, and a pruned list is not an authorization
+ * boundary on its own.
+ */
+
+/**
+ * Tools removed from a read-only role's request.
+ *
+ * - `write`/`edit`/`patch`/`apply_patch` author file contents.
+ * - `shell`/`bash` author bytes through redirects and can mutate git state.
+ * - `execute` is Code Mode, which runs nested tool calls. Nested calls are not
+ *   documented to fire the guard's hooks, so a read-only role must not reach
+ *   them.
+ * - `todowrite` replaces the whole task list; read-only roles do not plan work.
+ * - `subagent`/`task` can delegate a mutation to a child that runs with the
+ *   child's own role.
+ * - `guard_worktree_create`/`guard_worktree_cleanup` mutate repository state
+ *   and are already denied by the dispatcher for this role.
+ */
+export const READ_ONLY_PRUNED_TOOLS: readonly string[] = [
+	"write",
+	"edit",
+	"patch",
+	"apply_patch",
+	"shell",
+	"bash",
+	"execute",
+	"todowrite",
+	"subagent",
+	"task",
+	"guard_worktree_create",
+	"guard_worktree_cleanup",
+];
+
+/**
+ * Delete the mutating tools from a per-request tool snapshot.
+ *
+ * Returns the ids actually removed, so the caller can journal the narrowing.
+ * The snapshot is host-owned and mutable for the duration of the request;
+ * deleting a key affects only the outgoing call.
+ */
+export function pruneToolsForReadOnlyRole(tools: Record<string, unknown> | undefined): string[] {
+	if (!tools || typeof tools !== "object") return [];
+	const removed: string[] = [];
+	for (const id of READ_ONLY_PRUNED_TOOLS) {
+		if (!(id in tools)) continue;
+		delete tools[id];
+		removed.push(id);
+	}
+	return removed;
+}