pi-harness-runtime 0.10.7 → 0.10.11

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

@@ -1,142 +0,0 @@
-/**
- * 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

@@ -1,110 +0,0 @@
-/**
- * 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

@@ -1,46 +0,0 @@
-/**
- * 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

@@ -1,98 +0,0 @@
-/**
- * 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

@@ -1,105 +0,0 @@
-/**
- * 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

@@ -1,22 +0,0 @@
-{
-  "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"]
-}