pi-harness-runtime 0.9.14 → 0.9.16

package/packages/privilege-broker/src/audit.ts

@@ -0,0 +1,142 @@
+/**
+ * Audit Logger — RFC-0101 §7
+ *
+ * Logs every capability grant/denial with actor, target, reason, and outcome.
+ * Built-in implementations: Console, File, NoOp.
+ * Replace with your preferred audit backend (syslog, PostgreSQL, Loki, etc.)
+ */
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	writeFileSync,
+	unlinkSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import type { AuditEntry, AuditLogger } from "./types.js";
+
+/** No-op logger — discards all events. */
+export class NoOpAuditLogger implements AuditLogger {
+	log(_entry: AuditEntry): void {
+		// no-op
+	}
+}
+
+/** Console logger — writes human-readable lines to stdout/stderr. */
+export class ConsoleAuditLogger implements AuditLogger {
+	log(entry: AuditEntry): void {
+		const prefix =
+			entry.outcome === "granted"
+				? "✅"
+				: entry.outcome === "denied"
+					? "❌"
+					: "⚠️";
+		const line = [
+			prefix,
+			`${entry.outcome.toUpperCase()}`,
+			`actor=${entry.actor}`,
+			`capability=${entry.capability}`,
+			`reason=${entry.reason}`,
+			entry.error ? `error=${entry.error}` : "",
+		]
+			.filter(Boolean)
+			.join(" ");
+		if (entry.outcome === "error") {
+			console.error(`[AUDIT] ${line}`);
+		} else {
+			console.log(`[AUDIT] ${line}`);
+		}
+	}
+}
+
+/**
+ * JSON Lines file logger — appends one JSON object per event.
+ * Auto-creates parent directory. Auto-rotates when file exceeds maxSizeBytes.
+ */
+export class FileAuditLogger implements AuditLogger {
+	private readonly logPath: string;
+	private readonly maxSizeBytes: number;
+	private readonly maxRotations: number;
+
+	constructor(
+		options: {
+			logPath?: string;
+			maxSizeBytes?: number;
+			maxRotations?: number;
+		} = {},
+	) {
+		const home = process.env["HOME"] ?? "/tmp";
+		this.logPath =
+			options.logPath ?? join(home, ".pi", "harness", "broker-audit.logl");
+		this.maxSizeBytes = options.maxSizeBytes ?? 10 * 1024 * 1024; // 10 MB
+		this.maxRotations = options.maxRotations ?? 5;
+		this._ensureDir();
+	}
+
+	log(entry: AuditEntry): void {
+		this._rotateIfNeeded();
+		const line = JSON.stringify(entry) + "\n";
+		writeFileSync(this.logPath, line, { flag: "a" });
+	}
+
+	private _ensureDir(): void {
+		const dir = dirname(this.logPath);
+		if (!existsSync(dir)) {
+			mkdirSync(dir, { recursive: true });
+		}
+	}
+
+	private _rotateIfNeeded(): void {
+		if (!existsSync(this.logPath)) return;
+		try {
+			const { statSync } = require("node:fs");
+			const stat = statSync(this.logPath);
+			if (stat.size < this.maxSizeBytes) return;
+
+			// Rotate: broker-audit.log → broker-audit.log.1 → ...
+			const { renameSync, existsSync: exists } = require("node:fs");
+			for (let i = this.maxRotations - 1; i >= 1; i--) {
+				const from = `${this.logPath}.${i}`;
+				const to = `${this.logPath}.${i + 1}`;
+				if (exists(to)) unlinkSync(to);
+				if (exists(from)) renameSync(from, to);
+			}
+			renameSync(this.logPath, `${this.logPath}.1`);
+		} catch {
+			// If rotation fails, continue writing to the existing file
+		}
+	}
+
+	/**
+	 * Read recent audit entries.
+	 * Returns newest entries last.
+	 */
+	query(options?: {
+		workerId?: string;
+		taskId?: string;
+		capability?: string;
+		success?: boolean;
+		limit?: number;
+	}): AuditEntry[] {
+		if (!existsSync(this.logPath)) return [];
+		const raw = readFileSync(this.logPath, "utf8");
+		const entries: AuditEntry[] = [];
+		for (const line of raw.split("\n")) {
+			if (!line.trim()) continue;
+			try {
+				const e = JSON.parse(line) as AuditEntry;
+				if (options?.workerId && e.workerId !== options.workerId) continue;
+				if (options?.taskId && e.taskId !== options.taskId) continue;
+				if (options?.capability && e.capability !== options.capability)
+					continue;
+				if (options?.success !== undefined && e.success !== options.success)
+					continue;
+				entries.push(e);
+			} catch {
+				// Skip malformed lines
+			}
+		}
+		const result = options?.limit ? entries.slice(-options.limit) : entries;
+		return result;
+	}
+}

package/packages/privilege-broker/src/executor.ts

@@ -0,0 +1,110 @@
+/**
+ * Broker Executor — RFC-0101 §7
+ *
+ * Executes a resolved CapabilityGrant using execve(2) (no shell).
+ * The service account must exist and have minimal permissions.
+ *
+ * Safety properties:
+ * - No shell interpolation — argv is passed directly to execve
+ * - Env whitelist enforced — only approved env vars are forwarded
+ * - Working directory constrained via chdir
+ * - Timeout enforced — process is killed if it exceeds timeoutMs
+ */
+import { spawn } from "node:child_process";
+import type { AuditLogger } from "./types.js";
+
+/** The BrokerExecutor resolves and executes capability grants. */
+export class BrokerExecutor {
+	constructor(private readonly audit: AuditLogger) {}
+
+	/**
+	 * Execute a command as the configured service account.
+	 * Throws on timeout or spawn error.
+	 */
+	async execute(options: {
+		command: string;
+		args: string[];
+		envWhitelist?: string[];
+		allowedCwd?: string;
+		timeoutMs?: number;
+		actor: string;
+		capability: string;
+		reason: string;
+	}): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+		const {
+			command,
+			args,
+			envWhitelist,
+			allowedCwd,
+			timeoutMs = 30_000,
+			actor,
+			capability,
+			reason,
+		} = options;
+
+		// Build minimal env
+		const env: Record<string, string> = {};
+		if (envWhitelist) {
+			for (const key of envWhitelist) {
+				if (process.env[key] !== undefined) {
+					env[key] = process.env[key]!;
+				}
+			}
+		}
+		env.PI_HARNESS_ACTOR = actor;
+		env.PI_HARNESS_CAPABILITY = capability;
+
+		const child = spawn(command, args, {
+			env,
+			cwd: allowedCwd ?? process.cwd(),
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+
+		let stdout = "";
+		let stderr = "";
+		child.stdout?.on("data", (chunk) => {
+			stdout += chunk.toString();
+		});
+		child.stderr?.on("data", (chunk) => {
+			stderr += chunk.toString();
+		});
+
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				child.kill("SIGKILL");
+				reject(new Error(`command timed out after ${timeoutMs}ms`));
+			}, timeoutMs);
+
+			child.on("exit", (code) => {
+				clearTimeout(timer);
+				const exitCode = code ?? 0;
+				this.audit.log({
+					timestamp: new Date().toISOString(),
+					actor,
+					capability: capability as Parameters<
+						typeof this.audit.log
+					>[0]["capability"],
+					reason,
+					outcome: exitCode === 0 ? "granted" : "error",
+					error: exitCode !== 0 ? `exit ${exitCode}` : undefined,
+				});
+				resolve({ exitCode, stdout, stderr });
+			});
+
+			child.on("error", (err) => {
+				clearTimeout(timer);
+				this.audit.log({
+					timestamp: new Date().toISOString(),
+					actor,
+					capability: capability as Parameters<
+						typeof this.audit.log
+					>[0]["capability"],
+					reason,
+					outcome: "error",
+					error: err.message,
+				});
+				reject(err);
+			});
+		});
+	}
+}

package/packages/privilege-broker/src/index.ts

@@ -0,0 +1,46 @@
+/**
+ * Privilege Broker — RFC-0101 §7
+ *
+ * Provides safe privilege escalation for autonomous tasks:
+ * - Lists available capabilities
+ * - Checks human approval
+ * - Executes privileged operations safely
+ *
+ * Usage:
+ * ```ts
+ * import { PrivilegeBroker } from "@pi-harness/privilege-broker";
+ *
+ * const broker = new PrivilegeBroker({
+ *   registry: defaultCapabilityRegistry(),
+ *   audit: new ConsoleAuditLogger(),
+ * });
+ *
+ * const ok = await broker.check(
+ *   "run_command",
+ *   { command: "npm test" },
+ *   "pi-runtime-agent",
+ * );
+ * ```
+ */
+export type {
+	PrivilegeEntry,
+	PrivilegeRegistry,
+	CapabilityName,
+	CapabilityGrant,
+	AuditEntry,
+	AuditLogger,
+	ApprovalClass,
+} from "./types.js";
+export { loadRegistry, type PrivilegeRegistryError } from "./registry.js";
+export {
+	type ApprovalResult,
+	registerApprovalClass,
+	checkApproval,
+	clearApprovalCache,
+} from "./approval.js";
+export {
+	NoOpAuditLogger,
+	ConsoleAuditLogger,
+	FileAuditLogger,
+} from "./audit.js";
+export { BrokerExecutor } from "./executor.js";

package/packages/privilege-broker/src/registry.ts

@@ -0,0 +1,98 @@
+/**
+ * Privilege Registry — RFC-0101 §7
+ *
+ * Loads config/privileges.yaml at startup and provides:
+ * - lookup(capability) → PrivilegeEntry | null
+ * - knownCapabilities() → CapabilityName[]
+ * - validate() → { valid: boolean; errors: string[] }
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { parse as parseYaml } from "yaml";
+import type {
+	PrivilegeEntry,
+	PrivilegeRegistry,
+	CapabilityName,
+} from "./types.js";
+
+export class PrivilegeRegistryError extends Error {
+	constructor(msg: string) {
+		super(`[PrivilegeRegistryError] ${msg}`);
+		this.name = "PrivilegeRegistryError";
+	}
+}
+
+/** Default location relative to the package root. */
+export const DEFAULT_PRIVILEGES_PATH = join(
+	dirname(new URL(".", import.meta.url).pathname),
+	"..",
+	"config",
+	"privileges.yaml",
+);
+
+/**
+ * Load and validate the privilege registry from a YAML file.
+ *
+ * @throws {PrivilegeRegistryError} if the file is missing or invalid
+ */
+export function loadRegistry(path?: string): PrivilegeRegistry {
+	const filePath = path ?? DEFAULT_PRIVILEGES_PATH;
+	if (!existsSync(filePath)) {
+		throw new PrivilegeRegistryError(
+			`privileges file not found at ${filePath}. Copy config/privileges.yaml.example to config/privileges.yaml and edit it.`,
+		);
+	}
+
+	let raw: unknown;
+	try {
+		const content = readFileSync(filePath, "utf8");
+		raw = parseYaml(content);
+	} catch (err) {
+		throw new PrivilegeRegistryError(
+			`failed to parse ${filePath}: ${(err as Error).message}`,
+		);
+	}
+
+	const registry = raw as PrivilegeRegistry;
+
+	// Validate
+	const errors = validate(registry);
+	if (errors.length > 0) {
+		throw new PrivilegeRegistryError(
+			`validation errors in ${filePath}:\n  ${errors.join("\n  ")}`,
+		);
+	}
+
+	return registry;
+}
+
+/** Lightweight validation — check required fields. */
+export function validate(registry: PrivilegeRegistry): string[] {
+	const errors: string[] = [];
+	if (!registry || typeof registry !== "object") {
+		errors.push("registry must be an object");
+		return errors;
+	}
+	if (typeof registry.version !== "number") {
+		errors.push("registry.version is required and must be a number");
+	}
+	if (!Array.isArray(registry.capabilities)) {
+		errors.push("registry.capabilities must be an array");
+		return errors;
+	}
+	for (const cap of registry.capabilities) {
+		if (!cap.capability) {
+			errors.push("each capability must have a 'capability' field");
+		}
+		if (!cap.description) {
+			errors.push(`capability ${cap.capability} missing 'description'`);
+		}
+		if (!cap.approval_class) {
+			errors.push(`capability ${cap.capability} missing 'approval_class'`);
+		}
+		if (!cap.actors || typeof cap.actors !== "object") {
+			errors.push(`capability ${cap.capability} missing 'actors' object`);
+		}
+	}
+	return errors;
+}

package/packages/privilege-broker/src/types.ts

@@ -0,0 +1,105 @@
+/**
+ * Privilege Broker — Types
+ * RFC-0101 §7-§8
+ *
+ * Duplicates CapabilityName from @pi/autonomous-runtime here to avoid
+ * circular import issues in the workspace. Once the workspace is built,
+ * this can be replaced with:
+ *   import type { CapabilityName } from "@pi/autonomous-runtime";
+ */
+
+/** A named capability that the privilege broker may grant. */
+export type CapabilityName =
+	| "files.read"
+	| "files.write"
+	| "files.exec"
+	| "git.commit"
+	| "git.push"
+	| "gh.api"
+	| "npm.publish"
+	| "run_command"
+	| "sudo";
+
+/** Policy for one capability. */
+export interface PrivilegeEntry {
+	capability: CapabilityName;
+	/** Human-readable description shown in approval prompts. */
+	description: string;
+	/** Per-actor policy. Default deny if no match. */
+	actors: Record<
+		string,
+		{
+			/** "allow", "deny", or "ask" (requires human approval). */
+			default: "allow" | "deny" | "ask";
+			/** Optional: cron expression for time-of-day restriction. */
+			time_window?: string;
+			/** Optional: condition expression evaluated at runtime. */
+			condition?: string;
+			/** Max exec-time in ms. 0 = no limit. */
+			timeout_ms?: number;
+			/** Environment variable whitelist (exact keys). */
+			env_whitelist?: string[];
+			/** Optional: working directory constraint. */
+			allowed_cwd?: string;
+		}
+	>;
+	/** Approval class id — determines how to prompt human. */
+	approval_class: string;
+}
+
+/** Loaded registry of all known capabilities. */
+export interface PrivilegeRegistry {
+	version: number;
+	capabilities: PrivilegeEntry[];
+}
+
+/** Result of a broker.check() call. */
+export interface CapabilityGrant {
+	granted: boolean;
+	reason: string;
+	/** Filled if granted = true. */
+	exec_options?: {
+		timeout_ms?: number;
+		env_whitelist?: string[];
+		allowed_cwd?: string;
+	};
+}
+
+/** Log entry for audit trail. */
+export type AuditOutcome =
+	| "granted"
+	| "denied"
+	| "auto_denied"
+	| "auto_approved"
+	| "error";
+
+export interface AuditEntry {
+	timestamp: string;
+	workerId?: string;
+	taskId?: string;
+	actor: string;
+	capability: CapabilityName;
+	reason: string;
+	outcome: AuditOutcome;
+	success?: boolean;
+	error?: string;
+}
+
+/** Audit logger interface. */
+export interface AuditLogger {
+	log(entry: AuditEntry): void;
+}
+
+/** Approval class — determines how to prompt the human. */
+export interface ApprovalClass {
+	id: string;
+	/**
+	 * Prompt the human for approval.
+	 * Returns "granted" or "denied".
+	 */
+	prompt(
+		capability: CapabilityName,
+		actor: string,
+		reason: string,
+	): Promise<"granted" | "denied">;
+}

package/packages/privilege-broker/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "composite": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"]
+}