@pi-archimedes/sudo 2.4.0

package/src/index.ts

@@ -0,0 +1,81 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+import { credentialCache } from "./cache.js";
+import { splitCommandIntoArgv } from "./argv-split.js";
+import { DEFAULT_SUDO_CONFIG, loadSudoConfig, saveSudoConfig, type SudoConfig } from "./config.js";
+import { handleBashToolCall, isInteractiveSudoAttempt, type GuardResult } from "./guard.js";
+import { confirmCommand, maskLine, promptForPassword } from "./prompt.js";
+import { buildSudoArgv, createSudoExecTool, registerSudoTool, scrubSecret, type SudoSpawner } from "./tool.js";
+
+/**
+ * Registers `sudo_exec` (Task 1), the bash-sudo guard (Task 2) — a
+ * `pi.on("tool_call")` veto that blocks interactive `sudo` issued through
+ * the built-in bash tool — and the session lifecycle + `/sudo` command
+ * (Task 3). ALL registrations happen at the top level of this function,
+ * never inside a session handler (nested registration accumulates on
+ * `/reload`).
+ */
+export function registerSudo(pi: ExtensionAPI, options?: { spawner?: SudoSpawner }): void {
+	registerSudoTool(pi, options);
+	// Active veto: the guard is pure (isInteractiveSudoAttempt) and exported for
+	// direct testing; handleBashToolCall only vets — it never mutates event.input.
+	pi.on("tool_call", (event) => handleBashToolCall(event));
+
+	// Session lifecycle: the credential is a module singleton and must never
+	// outlive a session — cleared at every session boundary (ADR 0010).
+	pi.on("session_start", () => {
+		credentialCache.clear();
+	});
+	pi.on("session_shutdown", () => {
+		credentialCache.clear();
+	});
+
+	// /sudo — manage the credential cache (v1: state + forget, JSON-only config).
+	pi.registerCommand("sudo", {
+		description: "Manage the sudo credential cache",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			const args = _args.trim();
+			if (args === "forget") {
+				credentialCache.clear();
+				ctx.ui.notify("Sudo credential cleared.", "info");
+				return;
+			}
+			if (args !== "") {
+				ctx.ui.notify("Unknown /sudo subcommand. Usage: /sudo, /sudo forget", "info");
+				return;
+			}
+			// Bare: report state. get() is expiry-aware, so a stale entry reads
+			// as "not cached" (it re-prompts on next use) without being dropped.
+			ctx.ui.notify(
+				credentialCache.get() !== null
+					? "Sudo credential cached."
+					: "No sudo credential cached.",
+				"info",
+			);
+		},
+	});
+}
+
+// Exports for Tasks 2–3 (guard wiring, /sudo command + session lifecycle)
+export {
+	credentialCache,
+	splitCommandIntoArgv,
+	buildSudoArgv,
+	scrubSecret,
+	confirmCommand,
+	promptForPassword,
+	maskLine,
+	loadSudoConfig,
+	saveSudoConfig,
+	DEFAULT_SUDO_CONFIG,
+	createSudoExecTool,
+	handleBashToolCall,
+	isInteractiveSudoAttempt,
+};
+export type { SudoConfig, SudoSpawner, GuardResult };
+
+// Standalone entry — pi's loader requires a default export (see the
+// image-paste fix precedent). Under meta, the named exports are used.
+export default function (pi: ExtensionAPI): void {
+	registerSudo(pi);
+}

package/src/lifecycle.test.ts

@@ -0,0 +1,165 @@
+/**
+ * Session lifecycle + /sudo command tests.
+ *
+ * The credential cache is a module singleton that must NEVER outlive a
+ * session: session_shutdown drops it from memory, session_start resets it
+ * for a fresh session, and `/sudo forget` clears it explicitly (ADR 0010).
+ * Handlers must be registered at the TOP level of registerSudo — these
+ * fake-`pi` tests double-check that, because a wrapper-building handler
+ * (nested registration) would not show up under the expected event key.
+ *
+ * I/O is mocked out: fake `pi` records `on()`/`registerCommand()` calls,
+ * fake ctx carries a `ui.notify` spy.
+ */
+import { afterEach, describe, expect, it } from "vitest";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { credentialCache } from "./cache.js";
+import { registerSudo } from "./index.js";
+
+interface FakePi {
+	pi: ExtensionAPI;
+	/** event name → handlers in registration order */
+	handlers: Map<string, Function[]>;
+	commands: Map<string, { description: string; handler: Function }>;
+	tools: unknown[];
+}
+
+function fakePi(): FakePi {
+	const handlers = new Map<string, Function[]>();
+	const commands = new Map<string, { description: string; handler: Function }>();
+	const tools: unknown[] = [];
+	const pi = {
+		on(event: string, fn: Function) {
+			const list = handlers.get(event) ?? [];
+			list.push(fn);
+			handlers.set(event, list);
+		},
+		registerTool(tool: unknown) {
+			tools.push(tool);
+		},
+		registerCommand(name: string, def: { description: string; handler: Function }) {
+			commands.set(name, def);
+		},
+	} as unknown as ExtensionAPI;
+	return { pi, handlers, commands, tools };
+}
+
+function fakeCtx() {
+	const notified: string[] = [];
+	const ctx = {
+		ui: {
+			notify(message: string, _kind?: string) {
+				notified.push(message);
+			},
+		},
+	} as unknown as ExtensionCommandContext;
+	return { ctx, notified };
+}
+
+function lastHandler(fake: FakePi, event: string): Function {
+	const list = fake.handlers.get(event);
+	expect(list, `no handler registered for "${event}"`).toBeDefined();
+	const fn = list![list!.length - 1];
+	expect(fn, `last handler for "${event}" must be a function`).toBeTypeOf("function");
+	if (typeof fn !== "function") throw new Error(`missing handler for "${event}"`);
+	return fn;
+}
+
+describe("registerSudo — session lifecycle + /sudo command", () => {
+	afterEach(() => {
+		credentialCache.clear();
+	});
+
+	it("registers session_shutdown and session_start at the top level, both clearing the credential cache", () => {
+		const fake = fakePi();
+		registerSudo(fake.pi);
+
+		// Top-level registration (no accumulation on /reload).
+		expect(lastHandler(fake, "session_shutdown")).toBeTypeOf("function");
+		expect(lastHandler(fake, "session_start")).toBeTypeOf("function");
+
+		// Sentinel entry survives until either handler runs.
+		credentialCache.set("hunter2", 900_000);
+		expect(credentialCache.get()).not.toBeNull();
+
+		lastHandler(fake, "session_shutdown")(undefined, undefined);
+		expect(credentialCache.get()).toBeNull();
+
+		// A fresh session must not inherit a credential either.
+		credentialCache.set("hunter2", 900_000);
+		expect(credentialCache.get()).not.toBeNull();
+
+		lastHandler(fake, "session_start")(undefined, undefined);
+		expect(credentialCache.get()).toBeNull();
+	});
+
+	it("registers the sudo_exec tool whose parameters are exactly {command, reason, timeoutMs}", () => {
+		const fake = fakePi();
+		registerSudo(fake.pi);
+
+		expect(fake.tools).toHaveLength(1);
+		const tool = fake.tools[0] as {
+			name: string;
+			parameters: { properties: Record<string, unknown>; required?: string[] };
+		};
+		expect(tool.name).toBe("sudo_exec");
+		expect(Object.keys(tool.parameters.properties).sort()).toEqual(["command", "reason", "timeoutMs"]);
+		expect(tool.parameters.required?.sort()).toEqual(["command", "reason"]);
+	});
+
+	it("registers a /sudo command whose forget subcommand clears the credential cache", async () => {
+		const fake = fakePi();
+		registerSudo(fake.pi);
+
+		const def = fake.commands.get("sudo");
+		expect(def).toBeDefined();
+		expect(def!.description).toBe("Manage the sudo credential cache");
+
+		credentialCache.set("hunter2", 900_000);
+		expect(credentialCache.get()).not.toBeNull();
+
+		const { ctx, notified } = fakeCtx();
+		await def!.handler("forget", ctx);
+
+		expect(credentialCache.get()).toBeNull();
+		expect(notified).toEqual(["Sudo credential cleared."]);
+	});
+
+	it("responds to an unknown /sudo subcommand with usage info — no exception, cache unchanged", async () => {
+		const fake = fakePi();
+		registerSudo(fake.pi);
+		const def = fake.commands.get("sudo")!;
+
+		credentialCache.set("hunter2", 900_000);
+		const { ctx, notified } = fakeCtx();
+		await expect(def.handler("noop", ctx)).resolves.toBeUndefined(); // must not throw
+
+		expect(notified).toEqual(["Unknown /sudo subcommand. Usage: /sudo, /sudo forget"]);
+		expect(credentialCache.get()).not.toBeNull(); // live credential untouched
+	});
+
+	it("bare /sudo reports the cache state (expiry-aware) and does not clear a live credential", async () => {
+		const fake = fakePi();
+		registerSudo(fake.pi);
+		const def = fake.commands.get("sudo")!;
+
+		// Not cached.
+		const notCached = fakeCtx();
+		await def.handler("", notCached.ctx);
+		expect(notCached.notified).toEqual(["No sudo credential cached."]);
+
+		// Cached (live entry).
+		credentialCache.set("hunter2", 900_000);
+		const cached = fakeCtx();
+		await def.handler("", cached.ctx);
+		expect(cached.notified).toEqual(["Sudo credential cached."]);
+		expect(credentialCache.get()).not.toBeNull();
+
+		// Expired entry reads as not-cached (get() is expiry-aware).
+		credentialCache.set("hunter2", 1);
+		await new Promise((r) => setTimeout(r, 5));
+		const expired = fakeCtx();
+		await def.handler("", expired.ctx);
+		expect(expired.notified).toEqual(["No sudo credential cached."]);
+	});
+});

package/src/prompt.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it, vi } from "vitest";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { confirmCommand, maskLine, promptForPassword } from "./prompt.js";
+
+// ── minimal ui.custom fakes ──────────────────────────────────────────────────
+
+interface MaskedComponent {
+	handleInput(data: string): void;
+	render(width: number): string[];
+}
+
+interface UnmaskedFactory {
+	(
+		tui: { requestRender(): void },
+		theme: { fg: (token: string, text: string) => string },
+		keybindings: unknown,
+		done: (value: string) => void,
+	): { handleInput(data: string): void; render(width: number): string[]; focused: boolean };
+}
+
+function maskedPromptUi(): { ctx: ExtensionContext; component(): MaskedComponent } {
+	let active: MaskedComponent | undefined;
+	const ui = {
+		custom: (factory: UnmaskedFactory): Promise<string> =>
+			new Promise<string>((resolve) => {
+				active = factory({ requestRender: () => {} }, { fg: (_token, text) => text }, {}, resolve);
+			}),
+	} as unknown as ExtensionContext["ui"];
+	const ctx = { mode: "tui" as const, hasUI: true, ui } as unknown as ExtensionContext;
+	return { ctx, component: () => active as MaskedComponent };
+}
+
+const headlessCtx = (mode: string): ExtensionContext =>
+	({ mode, hasUI: mode === "rpc", ui: {} }) as unknown as ExtensionContext;
+
+// ── maskLine ─────────────────────────────────────────────────────────────────
+
+describe("maskLine", () => {
+	it("returns an empty string for an empty buffer", () => {
+		expect(maskLine("")).toBe("");
+	});
+
+	it("renders one • per character and never leaks the raw value", () => {
+		for (const secret of ["s", "supersecret", "pässword123"]) {
+			expect(maskLine(secret)).toBe("•".repeat(secret.length));
+			expect(maskLine(secret)).not.toContain(secret);
+		}
+	});
+});
+
+// ── headless block ────────────────────────────────────────────────────────────
+
+describe("promptForPassword — headless block", () => {
+	it("rejects when ctx.mode is json", async () => {
+		await expect(promptForPassword(headlessCtx("json"))).rejects.toThrow();
+	});
+
+	it("rejects in print mode", async () => {
+		await expect(promptForPassword(headlessCtx("print"))).rejects.toThrow();
+	});
+
+	it("rejects in rpc mode (hasUI is true there, but custom components need a TUI)", async () => {
+		const ctx = headlessCtx("rpc");
+		expect(ctx.hasUI).toBe(true);
+		await expect(promptForPassword(ctx)).rejects.toThrow();
+	});
+});
+
+// ── confirmCommand ─────────────────────────────────────────────────────────
+
+describe("confirmCommand", () => {
+	function confirmCtx(answer: boolean) {
+		const confirm = vi.fn(async (_title: string, _message: string) => answer);
+		const ctx = { mode: "tui" as const, hasUI: true, ui: { confirm } } as unknown as ExtensionContext;
+		return { ctx, confirm };
+	}
+
+	it("resolves true when the user confirms", async () => {
+		const { ctx, confirm } = confirmCtx(true);
+		await expect(confirmCommand(ctx, "apt install ripgrep", "install ripgrep")).resolves.toBe(true);
+		expect(confirm).toHaveBeenCalledTimes(1);
+	});
+
+	it("resolves false when the user declines", async () => {
+		const { ctx, confirm } = confirmCtx(false);
+		await expect(confirmCommand(ctx, "reboot", "retry service")).resolves.toBe(false);
+		expect(confirm).toHaveBeenCalledTimes(1);
+	});
+
+	it("shows the exact command and reason in the confirmation message", async () => {
+		const { ctx, confirm } = confirmCtx(true);
+		await confirmCommand(ctx, "systemctl restart 'open rest api'", "service keeps wedging");
+
+		expect(confirm).toHaveBeenCalledTimes(1);
+		const [title, message] = confirm.mock.calls[0] as [string, string];
+		expect(title).toMatch(/confirm privileged command/i);
+		expect(message).toContain(`$ systemctl restart 'open rest api'`);
+		expect(message).toContain("service keeps wedging");
+		expect(message).toMatch(/elevated privileges/i);
+	});
+});
+
+describe("promptForPassword — masked component", () => {
+	it("buffers printable chars, applies Backspace, resolves on Enter, and never renders raw chars", async () => {
+		const { ctx, component } = maskedPromptUi();
+		const promise = promptForPassword(ctx);
+
+		const c = component();
+		for (const ch of ["s", "e", "c", "r", "e", "t"]) c.handleInput(ch);
+		c.handleInput("\x7f"); // backspace drops the last char
+
+		const renderedText = c.render(120).join("\n");
+		expect(renderedText).toContain("•••••"); // 5 chars typed after backspace
+		expect(renderedText).not.toContain("secre");
+		expect(renderedText).not.toContain("secret");
+
+		c.handleInput("\r"); // enter confirms
+		await expect(promise).resolves.toBe("secre");
+	});
+
+	it("ignores non-printable control characters", async () => {
+		const { ctx, component } = maskedPromptUi();
+		const promise = promptForPassword(ctx);
+
+		const c = component();
+		c.handleInput("\x01"); // control char — not a printable
+		c.handleInput("a");
+		c.handleInput("\r");
+		await expect(promise).resolves.toBe("a");
+	});
+
+	it("resolves with an empty string on Esc (cancellation)", async () => {
+		const { ctx, component } = maskedPromptUi();
+		const promise = promptForPassword(ctx);
+
+		const c = component();
+		c.handleInput("x");
+		c.handleInput("y");
+		c.handleInput("\x1b"); // escape
+		await expect(promise).resolves.toBe("");
+	});
+
+	it("resolves with an empty string when Enter is pressed with no input", async () => {
+		const { ctx, component } = maskedPromptUi();
+		const promise = promptForPassword(ctx);
+		component().handleInput("\r");
+		await expect(promise).resolves.toBe("");
+	});
+});

package/src/prompt.ts

@@ -0,0 +1,99 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+
+/**
+ * Render one `•` per typed character — pure, so the masking itself is
+ * unit-testable without a TUI. The raw buffer must never appear in
+ * rendered output.
+ */
+export function maskLine(buffer: string): string {
+	return "•".repeat(buffer.length);
+}
+
+/**
+ * Prompt for the sudo password through a masked `ui.custom` component
+ * (ask's picker.ts pattern, extended for a text field).
+ *
+ * Hard requirement (ADR 0010): the password ONLY ever comes from this
+ * masked interactive UI — never from a tool parameter. Headless sessions
+ * (json / print, RPC, subagent children) have no TUI surface, so we reject
+ * with a clear error rather than prompt. `ctx.mode === "tui"` is the
+ * precise gate: `hasUI` is also true in RPC mode, where custom components
+ * cannot run.
+ *
+ * Resolves to the typed password, or `""` when the user cancels (Esc)
+ * or confirms with an empty buffer — callers treat `""` as cancellation.
+ */
+export function promptForPassword(ctx: ExtensionContext, command?: string, reason?: string): Promise<string> {
+	if (ctx.mode !== "tui") {
+		return Promise.reject(
+			new Error(
+				"sudo_exec can only prompt for a password in an interactive session (TUI). Headless/RPC/subagent sessions have no masked input surface.",
+			),
+		);
+	}
+
+	return ctx.ui.custom<string>((tui, theme, _keybindings, done) => {
+		let buffer = "";
+
+		const isPrintable = (data: string): boolean => {
+			if (data.length !== 1) return false;
+			const code = data.codePointAt(0);
+			return code !== undefined && code >= 0x20 && code !== 0x7f;
+		};
+
+		const render = (width: number): string[] => {
+			const lines: string[] = [];
+			lines.push(truncateToWidth(theme.fg("warning", "  ⚠ sudo — enter your password (input is masked)"), width));
+			if (command) lines.push(truncateToWidth(theme.fg("text", `  $ ${command}`), width));
+			if (reason) lines.push(truncateToWidth(theme.fg("muted", `  ${reason}`), width));
+			lines.push("");
+			const masked = maskLine(buffer);
+			lines.push(
+				truncateToWidth(`  password: ${theme.fg("accent", masked)}${masked.length > 0 ? "" : theme.fg("dim", "(hidden)")}`, width),
+			);
+			lines.push(theme.fg("dim", "  Enter confirm · Esc cancel · Backspace delete"));
+			return lines;
+		};
+
+		const handleInput = (data: string): void => {
+			if (matchesKey(data, Key.ctrl("c")) || matchesKey(data, Key.escape)) {
+				done("");
+				return;
+			}
+			if (matchesKey(data, Key.enter)) {
+				done(buffer);
+				return;
+			}
+			if (matchesKey(data, Key.backspace) || matchesKey(data, Key.delete)) {
+				buffer = buffer.slice(0, -1);
+				tui.requestRender();
+				return;
+			}
+			if (isPrintable(data)) {
+				buffer += data;
+				tui.requestRender();
+				return;
+			}
+			// everything else (alt-sequences, other control chars): ignore
+		};
+
+		return {
+			focused: true,
+			render,
+			invalidate: () => {},
+			handleInput,
+		};
+	});
+}
+
+/**
+ * Display the exact privileged command and the human-readable reason to
+ * the user and require an explicit confirmation BEFORE any credential is
+ * requested. Declining returns false — the tool must fail without
+ * prompting for a password.
+ */
+export async function confirmCommand(ctx: ExtensionContext, command: string, reason: string): Promise<boolean> {
+	const message = ["This will run with elevated privileges (password required until cached):", "", `$ ${command}`, "", `Reason: ${reason}`].join("\n");
+	return ctx.ui.confirm("Confirm privileged command", message);
+}