@pi-archimedes/sudo 2.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Cherubini and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @pi-archimedes/sudo
+
+Safe privileged execution for the [Pi coding agent](https://github.com/earendil-works/pi): a dedicated `sudo_exec` tool with a masked password prompt, plus a guard that keeps the ordinary `bash` tool from driving interactive `sudo`.
+
+## What you get
+
+- **`sudo_exec` tool** — runs a privileged command via `sudo -S`, showing the exact command and reason for confirmation before any credential is requested; on timeout/abort the kill applies to the command's entire process group, so privileged (root) descendants are killed too, not just the direct sudo process — except a command that intentionally detaches itself into its own session (`setsid`/daemonizing), which leaves the group by definition and is beyond any user-space kill (the same reach as `tmux kill-pane`): give such commands a managed lifecycle flag (e.g. `--foreground`) instead
+- **Masked password prompt** — the password is entered only through a masked UI, cached in memory for the session, and passed to sudo via stdin only — never in argv, env, logs, or files
+- **Defensive scrubbing** — command output lines containing the password are redacted before they appear in tool results
+- **Credential lifecycle** — single in-memory cache with TTL (default 15 min, `ttlMs`); cleared on auth failure, `session_start`/`session_shutdown`, and `/sudo forget`
+- **Headless sessions blocked** — subagent/headless sessions get a clear error from `sudo_exec` instead of a prompt; the masked prompt only ever appears in a human's TUI
+- **Bash guard** — active `tool_call` veto (ADR 0010): interactive `sudo` through the built-in `bash` tool is blocked, funneling privileged execution through `sudo_exec`
+- **`/sudo` + `/sudo forget`** — report the credential-cache state or clear it from memory
+
+## Install
+
+```bash
+pi install npm:@pi-archimedes/sudo
+```
+
+## Usage
+
+### The `sudo_exec` tool
+
+```jsonc
+{
+  "command": "apt install ripgrep", // exact argv string — no leading 'sudo'; no shell syntax (pipes, &&, redirects, env assignments)
+  "reason": "ripgrep is needed for the search tooling", // required — shown to the user before execution
+  "timeoutMs": 120000 // optional override of config.defaultTimeoutMs
+}
+```
+
+The tool uses pi's built-in `renderCall`/`renderResult`; command output is surfaced as plain text, scrubbed with the password masked.
+
+### The bash guard
+
+A pure, exhaustively-tested scanner vetoes `tool_call` events on the built-in `bash` tool:
+
+- **Blocked:** `sudo` in command position without a no-prompt flag — including through runner wrappers (`env`, `nohup`, `timeout`, `xargs`, …), nested shells (`bash -c`, `su -c`), `eval`, compound keywords, and heredoc bodies
+- **Allowed:** non-interactive sudo (`sudo -n`, `-l`, `-v`, `-K`, `-k`, `--non-interactive`) — these cannot prompt and pass through untouched
+
+The guard is a heuristic with accepted residual bypasses documented in the [ADR 0010 design notes](../../docs/adr/0010-archimedes-sudo-security.md) (e.g. cross-token variable indirection, and sudo inside `$(...)`/backtick interpolation whose text the word-position model cannot see). Over-blocking is the safe direction; the tested no-prompt flag set is a stable contract.
+
+## Commands
+
+- `/sudo` — report whether a credential is cached
+- `/sudo forget` — clear the credential from memory
+
+## Settings
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `ttlMs` | number | `900000` | Password cache TTL in milliseconds (default 15 minutes) |
+| `defaultTimeoutMs` | number | `120000` | `sudo_exec` default command timeout in milliseconds (default 120 seconds) |
+
+On/off is managed by the suite: toggle via `/plugins` (`archimedes.sudo.enabled`, default on). Config is JSON-only in the `archimedes.sudo` namespace of `~/.pi/agent/settings.json` — there is no settings-panel UI in v1.
+
+### Credential limitation on sudoers that retain no reusable ticket
+
+On sudoers policies that retain no reusable credential ticket (e.g. `timestamp_timeout=0` plus strict `Defaults`), an authenticated **command** failure is indistinguishable from an authentication failure to any non-interactive check — so the tool uses a two-consecutive-failure rule: the first failure keeps the cached password (with a visible warning), the second clears it. A wrong password on such a sudo is therefore detected on the second failure rather than the first — the bounded cost of a policy that exposes no ticket to verify against.
+
+## Integration
+
+When installed via `pi-archimedes` (the meta package), the sudo package is registered and gated by the suite's plugin manifest (ADR 0012); the bash guard and `sudo_exec` are loaded in both the main session and subagent children — the guard still vetoes there, while `sudo_exec` itself refuses to run headless. Standalone installs work independently.
+
+← Back to [pi-archimedes](../../README.md)

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@pi-archimedes/sudo",
+  "version": "2.4.0",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "description": "Safe privileged execution for pi — sudo_exec tool with masked password prompt and bash-sudo guard",
+  "files": [
+    "src"
+  ],
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./guard": "./src/guard.ts"
+  },
+  "dependencies": {
+    "@pi-archimedes/core": "2.4.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.1.0",
+    "@earendil-works/pi-tui": ">=0.1.0",
+    "typebox": ">=1.1.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@earendil-works/pi-tui": "^0.84.2",
+    "typebox": "^1.1.38",
+    "typescript": "^6.0.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}

package/src/argv-split.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { splitCommandIntoArgv } from "./argv-split.js";
+
+describe("splitCommandIntoArgv", () => {
+	it("splits simple whitespace-separated words", () => {
+		expect(splitCommandIntoArgv("apt install ripgrep")).toEqual(["apt", "install", "ripgrep"]);
+	});
+
+	it("collapses runs of spaces and trims leading/trailing whitespace", () => {
+		expect(splitCommandIntoArgv("  ls   -la  ")).toEqual(["ls", "-la"]);
+	});
+
+	it("keeps single-quoted strings together, stripping the quotes", () => {
+		expect(splitCommandIntoArgv("echo 'hello world'")).toEqual(["echo", "hello world"]);
+	});
+
+	it("keeps double-quoted strings together, stripping the quotes", () => {
+		expect(splitCommandIntoArgv('echo "hi there"')).toEqual(["echo", "hi there"]);
+	});
+
+	it("honours backslash escapes outside quotes", () => {
+		expect(splitCommandIntoArgv("echo a\\ b")).toEqual(["echo", "a b"]);
+	});
+
+	it("honours backslash-escaped quote characters inside double quotes", () => {
+		expect(splitCommandIntoArgv('echo "a\\"b"')).toEqual(["echo", 'a"b']);
+	});
+
+	it("honours escaped backslashes inside double quotes", () => {
+		expect(splitCommandIntoArgv('echo "a\\\\"')).toEqual(["echo", "a\\"]);
+	});
+
+	it("single quotes are fully literal (no backslash processing inside)", () => {
+		expect(splitCommandIntoArgv("echo 'a\\ b'")).toEqual(["echo", "a\\ b"]);
+	});
+
+	it("produces an empty word for a quoted empty string", () => {
+		expect(splitCommandIntoArgv('echo ""')).toEqual(["echo", ""]);
+		expect(splitCommandIntoArgv("echo ''")).toEqual(["echo", ""]);
+	});
+
+	it("empty and whitespace-only input produce no words", () => {
+		expect(splitCommandIntoArgv("")).toEqual([]);
+		expect(splitCommandIntoArgv("   ")).toEqual([]);
+	});
+
+	it("adjacent quotes and bare text merge into one word", () => {
+		expect(splitCommandIntoArgv('echo "a b"flag')).toEqual(["echo", "a bflag"]);
+	});
+
+	it("keeps shell metacharacters as their own words (no shell semantics)", () => {
+		expect(splitCommandIntoArgv("ls | grep foo")).toEqual(["ls", "|", "grep", "foo"]);
+		expect(splitCommandIntoArgv("echo a && echo b")).toEqual(["echo", "a", "&&", "echo", "b"]);
+	});
+
+	it("handles a missing closing double quote by running to end of input", () => {
+		expect(splitCommandIntoArgv('echo "unterminated')).toEqual(["echo", "unterminated"]);
+	});
+});

package/src/argv-split.ts

@@ -0,0 +1,82 @@
+/**
+ * A small POSIX-ish shell-word splitter for `sudo -S` argv construction.
+ *
+ * Handles single quotes (fully literal), double quotes (backslash escapes
+ * `\"` and `\\`), and backslash escapes outside quotes. It deliberately has
+ * NO other shell semantics: no pipes, redirects, globbing, `&&`, or env
+ * assignments are interpreted — those characters stay in the words, so a
+ * `command` param containing them passes through to sudo's argv rather than
+ * being executed by a shell. This is why the tool spawns a real argv and
+ * never interpolates into a shell string.
+ */
+export function splitCommandIntoArgv(command: string): string[] {
+	const args: string[] = [];
+	let current = "";
+	let hasWord = false;
+	let i = 0;
+
+	const appendWord = () => {
+		args.push(current);
+		current = "";
+		hasWord = false;
+	};
+
+	while (i < command.length) {
+		const ch = command.charAt(i);
+
+		if (ch === "'") {
+			// Single quotes: literal until the closing quote.
+			i++;
+			let closed = false;
+			while (i < command.length) {
+				const inner = command.charAt(i);
+				if (inner === "'") {
+					closed = true;
+					i++;
+					break;
+				}
+				current += inner;
+				i++;
+			}
+			hasWord = true;
+			if (!closed) break; // unterminated — rest was literal
+		} else if (ch === '"') {
+			// Double quotes: backslash only escapes " and \.
+			i++;
+			let closed = false;
+			while (i < command.length) {
+				const inner = command.charAt(i);
+				if (inner === "\\" && (command.charAt(i + 1) === '"' || command.charAt(i + 1) === "\\")) {
+					current += command.charAt(i + 1);
+					i += 2;
+					continue;
+				}
+				if (inner === '"') {
+					closed = true;
+					i++;
+					break;
+				}
+				current += inner;
+				i++;
+			}
+			hasWord = true;
+			if (!closed) break; // unterminated — rest was literal
+		} else if (ch === "\\") {
+			// Outside quotes: escape the next character.
+			const next = command.charAt(i + 1);
+			current += next === undefined ? "\\" : next;
+			i += 2;
+			hasWord = true;
+		} else if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r") {
+			if (hasWord) appendWord();
+			i++;
+		} else {
+			current += ch;
+			i++;
+			hasWord = true;
+		}
+	}
+
+	if (hasWord) appendWord();
+	return args;
+}

package/src/cache.test.ts

@@ -0,0 +1,91 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { CredentialCache } from "./cache.js";
+
+const TTL = 60_000;
+
+describe("CredentialCache", () => {
+	beforeEach(() => {
+		vi.useFakeTimers();
+	});
+	afterEach(() => {
+		vi.useRealTimers();
+	});
+
+	it("is empty before any set: get() null, isExpired false", () => {
+		const cache = new CredentialCache();
+		expect(cache.get()).toBeNull();
+		expect(cache.isExpired).toBe(false);
+	});
+
+	it("returns the credential while within the TTL", () => {
+		const cache = new CredentialCache();
+		cache.set("hunter2", TTL);
+		const got = cache.get();
+		expect(got).not.toBeNull();
+		expect(got?.password).toBe("hunter2");
+		expect(got?.expiresAt).toBe(Date.now() + TTL);
+		expect(cache.isExpired).toBe(false);
+	});
+
+	it("returns null once the TTL has elapsed (does not auto-clear the entry)", () => {
+		const cache = new CredentialCache();
+		cache.set("hunter2", TTL);
+		vi.advanceTimersByTime(TTL + 1);
+		expect(cache.get()).toBeNull();
+		// still set, just stale — isExpired flags it until clear()
+		expect(cache.isExpired).toBe(true);
+	});
+
+	it("isExpired is false exactly at set time and true once the deadline passes", () => {
+		const cache = new CredentialCache();
+		cache.set("hunter2", TTL);
+		expect(cache.isExpired).toBe(false);
+		vi.advanceTimersByTime(TTL);
+		expect(cache.isExpired).toBe(true);
+	});
+
+	it("clear() empties the cache and resets isExpired", () => {
+		const cache = new CredentialCache();
+		cache.set("hunter2", TTL);
+		vi.advanceTimersByTime(TTL + 1);
+		expect(cache.isExpired).toBe(true);
+		cache.clear();
+		expect(cache.get()).toBeNull();
+		expect(cache.isExpired).toBe(false);
+	});
+
+	it("set() replaces the previous entry with a fresh TTL", () => {
+		const cache = new CredentialCache();
+		cache.set("first", TTL);
+		vi.advanceTimersByTime(TTL - 1000);
+		cache.set("second", TTL);
+		const got = cache.get();
+		expect(got?.password).toBe("second");
+		// the fresh entry survives the original deadline
+		vi.advanceTimersByTime(1000);
+		expect(cache.get()).not.toBeNull();
+	});
+
+	it("set() initializes failStreak to 0; bumpFailStreak counts on the live entry; resetFailStreak restores 0", () => {
+		const cache = new CredentialCache();
+		cache.set("pw", TTL);
+		expect(cache.get()?.failStreak).toBe(0);
+		cache.bumpFailStreak();
+		cache.bumpFailStreak();
+		expect(cache.get()?.failStreak).toBe(2);
+		cache.resetFailStreak();
+		expect(cache.get()?.failStreak).toBe(0);
+	});
+
+	it("bumpFailStreak/resetFailStreak on an empty cache are no-ops; a fresh set() restarts the streak", () => {
+		const cache = new CredentialCache();
+		cache.bumpFailStreak();
+		cache.resetFailStreak();
+		expect(cache.get()).toBeNull();
+		cache.set("a", TTL);
+		cache.bumpFailStreak();
+		expect(cache.get()?.failStreak).toBe(1);
+		cache.set("b", TTL); // same cache, new credential — streak belongs to the entry
+		expect(cache.get()?.failStreak).toBe(0);
+	});
+});

package/src/cache.ts

@@ -0,0 +1,58 @@
+/**
+ * In-memory credential cache for sudo_exec (ADR 0010).
+ *
+ * A single credential at a time, kept ONLY in memory for the active session —
+ * never written to disk or the OS keyring. Expired entries return null from
+ * get() (triggering a re-prompt) but are not auto-cleared; clear() is called
+ * on session_shutdown, /sudo forget, and auth failure to drop the password
+ * from memory entirely. No host/user keying in v1.
+ */
+export interface CachedCredential {
+	password: string;
+	expiresAt: number;
+	/**
+	 * Consecutive ambiguous command failures (non-terminal credential probe
+	 * after an unrecognized-signature failure) under THIS entry. The tool's
+	 * two-strike rule bumps/resets it; a fresh set() restarts it at 0.
+	 */
+	failStreak: number;
+}
+
+export class CredentialCache {
+	private entry: CachedCredential | null = null;
+
+	/** Set (or replace) the cached credential with a fresh TTL (and a zeroed fail streak). */
+	set(password: string, ttlMs: number): void {
+		this.entry = { password, expiresAt: Date.now() + ttlMs, failStreak: 0 };
+	}
+
+	/** Return the cached credential, or null if unset or expired. */
+	get(): CachedCredential | null {
+		if (this.entry === null) return null;
+		if (Date.now() >= this.entry.expiresAt) return null;
+		return this.entry;
+	}
+
+	/** Drop the credential from memory entirely. */
+	clear(): void {
+		this.entry = null;
+	}
+
+	/** Bump the current entry's failStreak (no-op when the cache is empty). */
+	bumpFailStreak(): void {
+		if (this.entry !== null) this.entry.failStreak += 1;
+	}
+
+	/** Reset the current entry's failStreak (no-op when the cache is empty). */
+	resetFailStreak(): void {
+		if (this.entry !== null) this.entry.failStreak = 0;
+	}
+
+	/** True when an entry is present but past its expiry. */
+	get isExpired(): boolean {
+		return this.entry !== null && Date.now() >= this.entry.expiresAt;
+	}
+}
+
+/** Module-level singleton, recreated per session via clear() on session_start (Task 3 lifecycle). */
+export const credentialCache = new CredentialCache();

package/src/config.test.ts

@@ -0,0 +1,47 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock core/settings-io BEFORE importing loadSudoConfig — the real module
+// builds its settings path at module load and would read/write the user's
+// actual ~/.pi/agent/settings.json.
+const store = vi.hoisted(() => ({
+	settings: {} as Record<string, Record<string, unknown>>,
+	saveCalls: [] as Array<{ namespace: string; config: object }>,
+}));
+
+vi.mock("@pi-archimedes/core/settings-io", () => ({
+	loadConfig: (namespace: string, defaults: Record<string, unknown>) => ({
+		...defaults,
+		...store.settings[namespace],
+	}),
+	saveConfig: (namespace: string, config: Record<string, unknown>) => {
+		store.saveCalls.push({ namespace, config });
+		store.settings[namespace] = config;
+	},
+}));
+
+import { DEFAULT_SUDO_CONFIG, loadSudoConfig, saveSudoConfig } from "./config.js";
+
+describe("sudo config", () => {
+	beforeEach(() => {
+		for (const key of Object.keys(store.settings)) delete store.settings[key];
+		store.saveCalls.length = 0;
+	});
+
+	it("exposes the shared defaults (15 min TTL, 120 s command timeout)", () => {
+		expect(DEFAULT_SUDO_CONFIG).toEqual({ ttlMs: 900000, defaultTimeoutMs: 120000 });
+	});
+
+	it("returns the defaults when no archimedes.sudo section exists", () => {
+		expect(loadSudoConfig()).toEqual(DEFAULT_SUDO_CONFIG);
+	});
+
+	it("merges a partial archimedes.sudo section over the defaults", () => {
+		store.settings["archimedes.sudo"] = { ttlMs: 5000 };
+		expect(loadSudoConfig()).toEqual({ ttlMs: 5000, defaultTimeoutMs: 120000 });
+	});
+
+	it("saveSudoConfig writes to the archimedes.sudo namespace", () => {
+		saveSudoConfig({ ttlMs: 1234, defaultTimeoutMs: 5678 });
+		expect(store.saveCalls).toEqual([{ namespace: "archimedes.sudo", config: { ttlMs: 1234, defaultTimeoutMs: 5678 } }]);
+	});
+});

package/src/config.ts

@@ -0,0 +1,27 @@
+import { loadConfig, saveConfig } from "@pi-archimedes/core/settings-io";
+
+export interface SudoConfig {
+	/**
+	 * Suite-managed by meta's plugin gate (archimedes.sudo.enabled, ADR 0012).
+	 * sudo NEVER reads this key — when off, meta skips registerSudo entirely.
+	 * Declared here only so settings editors see the shape.
+	 */
+	enabled?: boolean;
+	/** Password cache TTL in ms. Default 15 min. */
+	ttlMs: number;
+	/** sudo_exec default command timeout in ms. Default 120 s. */
+	defaultTimeoutMs: number;
+}
+
+export const DEFAULT_SUDO_CONFIG: SudoConfig = {
+	ttlMs: 900_000,
+	defaultTimeoutMs: 120_000,
+};
+
+export function loadSudoConfig(): SudoConfig {
+	return loadConfig("archimedes.sudo", DEFAULT_SUDO_CONFIG);
+}
+
+export function saveSudoConfig(config: SudoConfig): void {
+	saveConfig("archimedes.sudo", config);
+}