immune-brain 2.8.3 → 3.0.2

package/plugins/immune-brain/runtime/assurance/verification.ts

@@ -0,0 +1,233 @@
+// Host-neutral verification descriptor runner.
+//
+// The strict canonical parser for `assurance_kernel/verification_descriptor/v1`
+// is `runtime/verification_descriptor.ts`. This module binds the frozen Bun
+// runner, compatibility gate, fixed execution, and findings digest.
+
+import { createHash } from "node:crypto";
+import { execFileSync, spawn } from "node:child_process";
+import { realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, resolve, sep, relative } from "node:path";
+
+
+export {
+	VERIFICATION_DESCRIPTOR_CONTRACT,
+	parseVerificationDescriptor,
+	canonicalDescriptorBytes,
+	VerificationDescriptorError,
+	VERIFICATION_DESCRIPTOR_BOUNDS,
+	type VerificationDescriptor,
+} from "../verification_descriptor";
+import {
+	VERIFICATION_DESCRIPTOR_BOUNDS,
+	VerificationDescriptorError,
+	type VerificationDescriptor,
+} from "../verification_descriptor";
+
+/** Host-owned frozen runner identity: absolute realpath, device/inode, content hash, version. */
+export interface FrozenRunner {
+	runner_id: "bun";
+	path: string;
+	dev: number;
+	ino: number;
+	content_hash: string;
+	version: string;
+}
+
+export function resolveBunRunner(): FrozenRunner {
+	let executable: string;
+	try {
+		executable = execFileSync("which", ["bun"], { encoding: "utf8" }).trim();
+	} catch {
+		throw new VerificationDescriptorError("bun runner is unavailable on this host");
+	}
+	let real: string;
+	try {
+		real = realpathSync(executable);
+	} catch {
+		throw new VerificationDescriptorError("bun runner realpath is unresolvable");
+	}
+	let stat: ReturnType<typeof statSync>;
+	try {
+		stat = statSync(real);
+	} catch {
+		throw new VerificationDescriptorError("bun runner is unreadable");
+	}
+	if (!stat.isFile())
+		throw new VerificationDescriptorError("bun runner is not a regular file");
+	const { readFileSync } = require("node:fs") as typeof import("node:fs");
+	const contentHash = `sha256:${createHash("sha256").update(readFileSync(real)).digest("hex")}`;
+	let version = "";
+	try {
+		version = execFileSync(real, ["--version"], { encoding: "utf8" }).trim();
+	} catch {
+		throw new VerificationDescriptorError("bun runner version is unreadable");
+	}
+	return {
+		runner_id: "bun",
+		path: real,
+		dev: stat.dev,
+		ino: stat.ino,
+		content_hash: contentHash,
+		version,
+	};
+}
+
+/** The descriptor's claimed runner version must equal the frozen host runner version. */
+export function assertRunnerCompatible(
+	descriptor: VerificationDescriptor,
+	runner: FrozenRunner,
+): void {
+	if (descriptor.runner_version !== runner.version)
+		throw new VerificationDescriptorError(
+			`frozen runner version mismatch: descriptor claims ${descriptor.runner_version}, host has ${runner.version}; assurance unavailable`,
+		);
+}
+
+/** Raised when the host cancels a running fixed verification. */
+export class VerificationAbortedError extends Error {
+	constructor() {
+		super("fixed verification aborted");
+		this.name = "VerificationAbortedError";
+	}
+}
+
+/** Run the frozen runner with the descriptor argv/cwd under minimal environment. */
+export async function runFixedVerification(
+	root: string,
+	descriptor: VerificationDescriptor,
+	runner: FrozenRunner,
+	options: { signal?: AbortSignal } = {},
+): Promise<{ exit_code: number; stdout: string; stderr: string; timed_out: boolean }> {
+	const canonicalRoot = resolve(root);
+	const cwd = resolve(canonicalRoot, descriptor.cwd);
+	if (cwd === canonicalRoot ? false : !relative(canonicalRoot, cwd).startsWith(".") === false)
+		throw new VerificationDescriptorError("verification cwd escapes the repository");
+	if (isAbsolute(descriptor.cwd) || relative(canonicalRoot, cwd).startsWith(`..${sep}`) || cwd === resolve(canonicalRoot, ".."))
+		throw new VerificationDescriptorError("verification cwd escapes the repository");
+	if (options.signal?.aborted) throw new VerificationAbortedError();
+	if (process.platform === "win32")
+		throw new VerificationDescriptorError("fixed verification process-group isolation requires a POSIX host");
+	const maxOutput = Math.min(descriptor.max_output_bytes, VERIFICATION_DESCRIPTOR_BOUNDS.max_output_bytes);
+	return new Promise((resolvePromise, rejectPromise) => {
+		let settled = false;
+		let stdout = Buffer.alloc(0);
+		let stderr = Buffer.alloc(0);
+		let capturedBytes = 0;
+		const child = spawn(runner.path, descriptor.argv, {
+			cwd,
+			env: { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "" },
+			detached: process.platform !== "win32",
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+
+		const killTree = () => {
+			if (child.pid === undefined) return;
+			try {
+				if (process.platform !== "win32") process.kill(-child.pid, "SIGKILL");
+				else child.kill("SIGKILL");
+			} catch {
+				// The process already exited.
+			}
+		};
+		const cleanup = () => {
+			clearTimeout(timeout);
+			options.signal?.removeEventListener("abort", onAbort);
+		};
+		const resolveOnce = (result: { exit_code: number; stdout: string; stderr: string; timed_out: boolean }) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			resolvePromise(result);
+		};
+		const rejectOnce = (error: Error) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			rejectPromise(error);
+		};
+		const appendBounded = (current: Buffer<ArrayBuffer>, chunk: Buffer<ArrayBuffer>): { content: Buffer<ArrayBuffer>; exceeded: boolean } => {
+			const available = Math.max(0, maxOutput - capturedBytes);
+			const accepted = chunk.subarray(0, available);
+			capturedBytes += accepted.length;
+			return {
+				content: accepted.length > 0 ? Buffer.concat([current, accepted]) : current,
+				exceeded: chunk.length > available,
+			};
+		};
+		const outputLimitExceeded = () => {
+			const marker = Buffer.from("verification output limit exceeded\n", "utf8");
+			stdout = stdout.subarray(0, Math.max(0, maxOutput - marker.length));
+			stderr = marker.subarray(0, maxOutput - stdout.length);
+			capturedBytes = stdout.length + stderr.length;
+			killTree();
+			child.stdout?.destroy();
+			child.stderr?.destroy();
+			resolveOnce({
+				exit_code: 1,
+				stdout: stdout.toString("utf8"),
+				stderr: stderr.toString("utf8"),
+				timed_out: false,
+			});
+		};
+		child.stdout?.on("data", (chunk: Buffer<ArrayBuffer>) => {
+			const appended = appendBounded(stdout, chunk);
+			stdout = appended.content;
+			if (appended.exceeded) outputLimitExceeded();
+		});
+		child.stderr?.on("data", (chunk: Buffer<ArrayBuffer>) => {
+			const appended = appendBounded(stderr, chunk);
+			stderr = appended.content;
+			if (appended.exceeded) outputLimitExceeded();
+		});
+		child.once("error", (error) => {
+			resolveOnce({
+				exit_code: 1,
+				stdout: stdout.toString("utf8"),
+				stderr: `${stderr.toString("utf8")}runner spawn failed: ${error.message}`.slice(0, maxOutput),
+				timed_out: false,
+			});
+		});
+		child.once("close", (code) => {
+			resolveOnce({
+				exit_code: code ?? 1,
+				stdout: stdout.toString("utf8"),
+				stderr: stderr.toString("utf8"),
+				timed_out: false,
+			});
+		});
+		const onAbort = () => {
+			killTree();
+			child.stdout?.destroy();
+			child.stderr?.destroy();
+			rejectOnce(new VerificationAbortedError());
+		};
+		options.signal?.addEventListener("abort", onAbort, { once: true });
+		const timeout = setTimeout(() => {
+			killTree();
+			child.stdout?.destroy();
+			child.stderr?.destroy();
+			resolveOnce({
+				exit_code: 1,
+				stdout: stdout.toString("utf8"),
+				stderr: stderr.toString("utf8"),
+				timed_out: true,
+			});
+		}, descriptor.timeout_ms);
+	});
+}
+
+/** Normalized findings digest: stable-sorted keys over id/kind/acceptance_id/summary. */
+export function findingsDigest(
+	findings: Array<{ id: string; kind: string; acceptance_id: string | null; summary: string }>,
+): string {
+	const normalized = findings.map((f) =>
+		JSON.stringify({
+			acceptance_id: f.acceptance_id,
+			id: f.id,
+			kind: f.kind,
+			summary: f.summary,
+		}),
+	);
+	return `sha256:${createHash("sha256").update(`[${normalized.join(",")}]`).digest("hex")}`;
+}

package/plugins/immune-brain/runtime/claude/capability.ts

@@ -0,0 +1,67 @@
+export const MIN_CLAUDE_CODE_VERSION = "2.1.199";
+export const HOST_ID = "claude-code" as const;
+export const CORE_CONTRACT = "assurance_kernel/host_adapter/claude-code/v1";
+export const SUPPORTED_PLATFORMS = ["darwin", "linux"] as const;
+
+export type PermissionMode = "manual" | "acceptEdits" | "auto" | "bypassPermissions" | "dontAsk";
+
+export type HostProbe =
+	| { ok: true; version: string; permissionMode: PermissionMode; platform: string }
+	| { ok: false; reason: string };
+
+function parseSemver(value: string): [number, number, number] | null {
+	// Prerelease and build suffixes are rejected: an unstable build such as
+	// 2.1.199-alpha never satisfies the stable minimum.
+	const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.exec(value.trim());
+	if (!match) return null;
+	return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+export function compareSemver(left: string, right: string): number {
+	const a = parseSemver(left);
+	const b = parseSemver(right);
+	if (!a || !b) throw new Error(`invalid semver: ${!a ? left : right}`);
+	return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+
+export function parsePermissionMode(raw: unknown): PermissionMode | null {
+	if (
+		raw === "manual"
+		|| raw === "acceptEdits"
+		|| raw === "auto"
+		|| raw === "bypassPermissions"
+		|| raw === "dontAsk"
+	) return raw;
+	return null;
+}
+
+/**
+ * Trusted version sources, in priority order: the MCP handshake clientInfo
+ * version announced by the connected Host (hostVersion), then the explicit
+ * environment override. An undeclared Host version fails closed.
+ */
+export function probeHost(
+	env: Record<string, string | undefined> = process.env,
+	platform = process.platform,
+	hostVersion?: string,
+): HostProbe {
+	const version = hostVersion ?? env.CLAUDE_CODE_VERSION ?? env.CLAUDE_CLI_VERSION;
+	if (!version) return { ok: false, reason: "Claude Code version is unavailable" };
+	if (!parseSemver(version)) return { ok: false, reason: `Claude Code version is invalid: ${version}` };
+	if (compareSemver(version, MIN_CLAUDE_CODE_VERSION) < 0) {
+		return {
+			ok: false,
+			reason: `Claude Code ${version} is below the minimum supported ${MIN_CLAUDE_CODE_VERSION}`,
+		};
+	}
+	if (platform !== "darwin" && platform !== "linux") {
+		return { ok: false, reason: `unsupported platform ${platform}; native Windows is out of scope` };
+	}
+	const rawPermissionMode = env.CLAUDE_CODE_PERMISSION_MODE;
+	if (rawPermissionMode !== undefined && rawPermissionMode !== "") {
+		const permissionMode = parsePermissionMode(rawPermissionMode);
+		if (!permissionMode) return { ok: false, reason: `unsupported permission mode ${rawPermissionMode}` };
+		return { ok: true, version, permissionMode, platform };
+	}
+	return { ok: true, version, permissionMode: "manual", platform };
+}

package/plugins/immune-brain/runtime/claude/interaction.ts

@@ -0,0 +1,70 @@
+import { createHash, randomUUID } from "node:crypto";
+import { parsePermissionMode, type PermissionMode } from "./capability";
+
+export const PRIVILEGED_OPERATIONS = [
+	"enroll",
+	"request_authorization",
+	"approve_breaking_intent_revision",
+	"stop",
+	"repair_authority_state",
+] as const;
+
+export type PrivilegedOperation = (typeof PRIVILEGED_OPERATIONS)[number];
+export type NativeDecision = "accept" | "deny" | "cancel";
+
+export function isPrivilegedOperation(operation: string): operation is PrivilegedOperation {
+	return (PRIVILEGED_OPERATIONS as readonly string[]).includes(operation);
+}
+
+export function privilegedAnnotations(): Record<string, unknown> {
+	return {
+		destructiveHint: true,
+		"anthropic/requiresUserInteraction": true,
+	};
+}
+
+export interface NativeGateInput {
+	operation: string;
+	permissionMode: PermissionMode | string;
+	requiresUserInteraction: boolean;
+	interactive: boolean;
+	decision?: NativeDecision;
+}
+
+export type NativeGateResult =
+	| { ok: true }
+	| { ok: false; reason: string };
+
+export function evaluateNativeGate(input: NativeGateInput): NativeGateResult {
+	if (!isPrivilegedOperation(input.operation)) return { ok: true };
+	if (!input.interactive) return { ok: false, reason: "non-interactive execution cannot mint authority" };
+	const mode = parsePermissionMode(input.permissionMode);
+	if (!mode) return { ok: false, reason: `unsupported permission mode ${String(input.permissionMode)}` };
+	if (mode === "dontAsk") return { ok: false, reason: "dontAsk cannot mint authority" };
+	if (!input.requiresUserInteraction) {
+		return { ok: false, reason: "privileged operation requires anthropic/requiresUserInteraction" };
+	}
+	if (input.decision === "deny") return { ok: false, reason: "native interaction denied" };
+	if (input.decision === "cancel") return { ok: false, reason: "native interaction cancelled" };
+	if (input.decision !== "accept") return { ok: false, reason: "native interaction missing" };
+	return { ok: true };
+}
+
+export function confirmationRef(input: {
+	sessionId: string;
+	toolCallId: string;
+	operation: string;
+	taskId: string;
+	intentRevision?: number;
+	intentContentHash?: string;
+	bindingDigest?: string;
+}): string {
+	return `claude-confirm-${createHash("sha256")
+		.update(`${input.sessionId}\0${input.toolCallId}\0${input.operation}\0${input.taskId}\0${input.intentRevision ?? ""}\0${input.intentContentHash ?? ""}\0${input.bindingDigest ?? ""}`)
+		.digest("hex")
+		.slice(0, 16)}`;
+}
+
+export function enrollmentNonce(): string {
+	return randomUUID();
+}