@andares/pi-toolkits 0.7.3 → 0.9.0

package/src/features/permission/constants.ts

@@ -0,0 +1,158 @@
+/**
+ * permission feature — modes, labels, and the fixed safety tables.
+ *
+ * The four modes are deliberately small: project boundary (in/out) crossed
+ * with operation kind (read/write, exec folded into write). There is no rule
+ * matrix — session grants cover the exceptions.
+ *
+ * Two tables sit outside the four modes on purpose:
+ *  - {@link SECRET_ROOTS} / {@link isSecretFile}: reads and writes of
+ *    credential material are denied in every mode. Without this, the default
+ *    `outside read = allow` would hand the agent `~/.ssh/id_rsa`.
+ *  - {@link DANGER_REASON}: destructive commands are always asked about, even
+ *    when their scope says allow (`rm -rf .` inside the project is still a
+ *    guarded operation). Scope alone cannot express "destructive".
+ */
+import { homedir } from "node:os";
+import { basename, join, sep } from "node:path";
+
+/** Three-way mode, used for outside-project operations. */
+export type TriMode = "ask" | "allow" | "deny";
+
+/** Two-way mode, used for inside-project operations. */
+export type PairMode = "ask" | "allow";
+
+/** What one tool call does to the filesystem. */
+export type Effect = "read" | "write";
+
+/** The four permission modes, all at once. */
+export interface PermissionModes {
+	inRead: PairMode;
+	inWrite: PairMode;
+	outRead: TriMode;
+	outWrite: TriMode;
+}
+
+/**
+ * Defaults: project-internal work is uninterrupted; outside reads are allowed
+ * (the secrets table is what protects credentials); outside writes ask.
+ */
+export const DEFAULT_MODES: PermissionModes = {
+	inRead: "allow",
+	inWrite: "allow",
+	outRead: "allow",
+	outWrite: "ask",
+};
+
+/** Footer status key (extension-scoped; `/ask` uses its own). */
+export const PERMISSION_STATUS_KEY = "perm-mode";
+
+/** Values offered by the mode panel, in cycle order. */
+export const IN_VALUES: readonly PairMode[] = ["allow", "ask"];
+export const OUT_VALUES: readonly TriMode[] = ["allow", "ask", "deny"];
+
+/**
+ * Credential locations denied in every mode. `~` is expanded at match time so
+ * the table survives a moved home directory.
+ */
+export const SECRET_ROOTS: readonly string[] = [
+	"~/.ssh",
+	"~/.gnupg",
+	"~/.aws",
+	"~/.pi/agent/auth.json",
+];
+
+/** `.env` family: secrets by convention, except the sample templates. */
+const ENV_TEMPLATES = new Set([".env.example", ".env.sample", ".env.template"]);
+
+/** pi's own credential files other than the exact `auth.json` entry. */
+function isPiAuthFile(pathValue: string): boolean {
+	const authPrefix = join(homedir(), ".pi", "agent", "auth");
+	return pathValue.startsWith(authPrefix) && basename(pathValue).endsWith(".json");
+}
+
+/** Containment: `pathValue` is `root` itself or under it (with sep boundaries). */
+function pathWithin(root: string, pathValue: string): boolean {
+	const a = process.platform === "win32" ? root.toLowerCase() : root;
+	const b = process.platform === "win32" ? pathValue.toLowerCase() : pathValue;
+	return b === a || b.startsWith(a.endsWith(sep) ? a : `${a}${sep}`);
+}
+
+/** `true` when `pathValue` is `.env`-shaped and not a template. */
+function isSecretEnvFile(pathValue: string): boolean {
+	const name = basename(pathValue);
+	if (ENV_TEMPLATES.has(name)) return false;
+	return name === ".env" || name.startsWith(".env.");
+}
+
+/** Absolute secret prefixes, `~` expanded. */
+export function secretRoots(): string[] {
+	return SECRET_ROOTS.map((root) =>
+		root.startsWith("~") ? join(homedir(), root.slice(1)) : root,
+	);
+}
+
+/** Why `pathValue` is secret, or `undefined` when it is not. */
+export function secretReason(pathValue: string): string | undefined {
+	if (isPiAuthFile(pathValue)) return "pi credentials";
+	if (isSecretEnvFile(pathValue)) return "environment file";
+	for (const root of secretRoots()) {
+		if (pathWithin(root, pathValue)) return "credentials";
+	}
+	return undefined;
+}
+
+/**
+ * Commands always confirmed regardless of mode. Returns the human-facing
+ * reason, or `undefined` for an ordinary command.
+ *
+ * `targets` are the unit's already-resolved absolute paths.
+ */
+export function dangerReason(
+	command: string,
+	args: readonly string[],
+	targets: readonly string[],
+	base: string | null,
+): string | undefined {
+	const home = homedir();
+	const inDangerousRoot = (pathValue: string): boolean =>
+		pathValue === "/" ||
+		pathValue === home ||
+		(base !== null && pathValue === base);
+
+	if (command === "sudo" || command === "doas") return "privileged command";
+	if (command === "rm" && targets.some(inDangerousRoot)) {
+		return "recursive delete of /, the home directory, or the working directory";
+	}
+	if (command === "git") {
+		const [verb, ...rest] = args;
+		if (verb === "reset" && rest.includes("--hard")) return "git reset --hard";
+		if (verb === "clean" && rest.some((a) => /^-[a-zA-Z]*f/.test(a))) {
+			return "git clean -f";
+		}
+		if (verb === "push" && rest.some((a) => a === "-f" || a === "--force")) {
+			return "forced git push";
+		}
+	}
+	if (
+		["npm", "pnpm", "yarn", "bun"].includes(command) &&
+		args[0] === "publish"
+	) {
+		return "package publish";
+	}
+	if (command === "dd" && targets.some((t) => t.startsWith("/dev/"))) {
+		return "raw device write";
+	}
+	if (command.startsWith("mkfs")) return "filesystem creation";
+	if (["shutdown", "reboot", "poweroff", "halt"].includes(command)) {
+		return "system power command";
+	}
+	if (
+		command === "chmod" &&
+		args.some((a) => /^-[a-zA-Z]*R/.test(a)) &&
+		args.includes("777")
+	) {
+		return "recursive world-writable chmod";
+	}
+	return undefined;
+}

package/src/features/permission/index.test.ts

@@ -0,0 +1,340 @@
+/**
+ * `/ask-perm` integration over a captured gate and a mocked pi surface.
+ *
+ * The UI components are not rendered here (that needs a terminal); the
+ * dialog contract is exercised through `AskRequest.present` with a host
+ * selector, and the rest through the gate's verdicts and the command handler.
+ */
+import { mkdtempSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	ToolCallEvent,
+} from "@earendil-works/pi-coding-agent";
+import type { AskDecision, GateHub, ToolGate } from "../../lib/gates.js";
+import { registerPermission } from "./index.js";
+
+function bashEvent(command: string): ToolCallEvent {
+	return {
+		type: "tool_call",
+		toolCallId: "call-1",
+		toolName: "bash",
+		input: { command },
+	} as unknown as ToolCallEvent;
+}
+
+function pathEvent(toolName: string, path: string): ToolCallEvent {
+	return {
+		type: "tool_call",
+		toolCallId: "call-1",
+		toolName,
+		input: { path },
+	} as unknown as ToolCallEvent;
+}
+
+function customEvent(toolName: string): ToolCallEvent {
+	return {
+		type: "tool_call",
+		toolCallId: "call-1",
+		toolName,
+		input: {},
+	} as unknown as ToolCallEvent;
+}
+
+interface Harness {
+	readonly cwd: string;
+	readonly ctx: ExtensionContext;
+	readonly gate: ToolGate;
+	readonly statuses: Array<[string, string | undefined]>;
+	readonly notes: Array<{ message: string; kind?: string }>;
+	readonly branch: Array<Record<string, unknown>>;
+	evaluate(event: ToolCallEvent): Promise<unknown>;
+	command(args: string): Promise<void>;
+	sessionStart(): Promise<void>;
+	banner(): { systemPrompt: string } | undefined;
+}
+
+function makeHarness(): Harness {
+	const cwd = realpathSync(mkdtempSync(join(tmpdir(), "pi-perm-test-")));
+	const statuses: Harness["statuses"] = [];
+	const notes: Harness["notes"] = [];
+	const branch: Harness["branch"] = [];
+	const ctx = {
+		cwd,
+		hasUI: true,
+		mode: "tui",
+		ui: {
+			notify: (message: string, kind?: string) => notes.push({ message, kind }),
+			setStatus: (key: string, value: string | undefined) => statuses.push([key, value]),
+			theme: { fg: (_color: string, text: string) => text },
+			custom: async () => undefined,
+			select: async () => undefined,
+		},
+		sessionManager: { getBranch: () => branch },
+	} as unknown as ExtensionContext;
+
+	const captured: ToolGate[] = [];
+	const hub = {
+		register(gate: ToolGate) {
+			captured.push(gate);
+		},
+		handle: async () => undefined,
+		install: () => {},
+	} as unknown as GateHub;
+
+	const handlers = new Map<string, (...args: unknown[]) => unknown>();
+	let commandHandler: ((args: string, ctx: ExtensionContext) => unknown) | undefined;
+	const pi = {
+		on(event: string, handler: (...args: unknown[]) => unknown) {
+			handlers.set(event, handler);
+		},
+		registerCommand(
+			name: string,
+			options: { handler: (args: string, ctx: ExtensionContext) => unknown },
+		) {
+			if (name === "ask-perm") commandHandler = options.handler;
+		},
+	} as unknown as ExtensionAPI;
+
+	registerPermission(pi, hub);
+	const gate = captured[0];
+	if (!gate || !commandHandler) throw new Error("permission did not register");
+
+	return {
+		cwd,
+		ctx,
+		gate,
+		statuses,
+		notes,
+		branch,
+		async evaluate(event) {
+			return gate.evaluate(event, ctx);
+		},
+		async command(args) {
+			await commandHandler?.(args, ctx);
+		},
+		async sessionStart() {
+			await handlers.get("session_start")?.( { reason: "new" }, ctx);
+		},
+		banner() {
+			return handlers.get("before_agent_start")?.(
+				{ systemPrompt: "base", type: "before_agent_start" },
+				ctx,
+			) as { systemPrompt: string } | undefined;
+		},
+	};
+}
+
+interface AskVerdict {
+	kind: "ask";
+	request: {
+		details: readonly string[];
+		root: string;
+		present(ctx: ExtensionContext): Promise<AskDecision | undefined>;
+		apply(decision: AskDecision): void;
+	};
+}
+
+function asAsk(verdict: unknown): AskVerdict {
+	expect(verdict).toMatchObject({ kind: "ask" });
+	return verdict as AskVerdict;
+}
+
+describe("/ask-perm", () => {
+	it("is off by default", async () => {
+		const h = makeHarness();
+		expect(await h.evaluate(bashEvent("rm -rf /tmp/outside"))).toBeUndefined();
+	});
+
+	it("enables from arguments, reports status, and asks for an outside write", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		expect(h.statuses.at(-1)?.[0]).toBe("perm-mode");
+		expect(h.statuses.at(-1)?.[1]).toContain("perm");
+		const verdict = asAsk(await h.evaluate(bashEvent("rm -rf /tmp/outside")));
+		expect(verdict.request.details.join("\n")).toContain("/tmp/outside");
+		expect(verdict.request.root).toBe("/tmp");
+	});
+
+	it("blocks immediately when outside writes are denied", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow deny");
+		const verdict = (await h.evaluate(bashEvent("rm -rf /tmp/outside"))) as {
+			kind: "block";
+			reason: string;
+		};
+		expect(verdict.kind).toBe("block");
+		expect(verdict.reason).toContain("Permission denied");
+		expect(verdict.reason).toContain("outside-project write");
+	});
+
+	it("records a session grant and applies it to later calls", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		const first = asAsk(await h.evaluate(bashEvent("rm -rf /tmp/outside/x")));
+		first.request.apply("allow-session");
+		expect(await h.evaluate(bashEvent("rm -rf /tmp/outside/y"))).toBeUndefined();
+	});
+
+	it("records a session deny and blocks later calls", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		const first = asAsk(await h.evaluate(bashEvent("rm -rf /tmp/outside/x")));
+		first.request.apply("deny-session");
+		const later = (await h.evaluate(bashEvent("rm -rf /tmp/outside/y"))) as {
+			kind: "block";
+			reason: string;
+		};
+		expect(later.kind).toBe("block");
+		expect(later.reason).toContain("denied for this session");
+	});
+
+	it("toggles off with no arguments and clears the status", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		await h.command("");
+		expect(h.statuses.at(-1)?.[1]).toBeUndefined();
+		expect(await h.evaluate(bashEvent("rm -rf /tmp/outside"))).toBeUndefined();
+	});
+
+	it("keeps the mode off when the panel is cancelled", async () => {
+		const h = makeHarness();
+		await h.command("");
+		expect(h.notes.at(-1)?.message).toContain("cancelled");
+		expect(await h.evaluate(bashEvent("rm -rf /tmp/outside"))).toBeUndefined();
+	});
+
+	it("rejects invalid arguments without enabling", async () => {
+		const h = makeHarness();
+		await h.command("deny");
+		expect(h.notes.at(-1)?.kind).toBe("error");
+		expect(await h.evaluate(bashEvent("rm -rf /tmp/outside"))).toBeUndefined();
+	});
+
+	it("resets on session_start", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		await h.sessionStart();
+		expect(await h.evaluate(bashEvent("rm -rf /tmp/outside"))).toBeUndefined();
+		expect(h.statuses.at(-1)?.[1]).toBeUndefined();
+	});
+
+	it("treats add-dir directories as inside the project", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		expect(asAsk(await h.evaluate(bashEvent("rm -rf /tmp/added/x"))).kind).toBe("ask");
+
+		h.branch.push({
+			type: "custom",
+			customType: "add-dir:state",
+			data: { dirs: [{ absolutePath: "/tmp/added" }] },
+		});
+		expect(await h.evaluate(bashEvent("rm -rf /tmp/added/x"))).toBeUndefined();
+	});
+
+	it("treats a redirect write to a credential path as a fixed deny, not a write ask", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		const verdict = (await h.evaluate(
+			bashEvent("echo a > ~/.ssh/authorized_keys"),
+		)) as { kind: "block"; reason: string };
+		expect(verdict.kind).toBe("block");
+		expect(verdict.reason).toContain("fixed safety table");
+	});
+
+	it("judges git -C by the -C directory, not the working directory", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		expect(await h.evaluate(bashEvent("git -C ../outside log"))).toBeUndefined();
+		expect(asAsk(await h.evaluate(bashEvent("git -C ../outside push"))).kind).toBe("ask");
+	});
+
+	it("answers path-bearing tools by their own path", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		expect(await h.evaluate(pathEvent("write", "notes.txt"))).toBeUndefined();
+		expect(asAsk(await h.evaluate(pathEvent("write", "/tmp/outside.txt"))).kind).toBe("ask");
+		const denied = (await h.evaluate(pathEvent("read", "~/.ssh/id_rsa"))) as {
+			kind: "block";
+		};
+		expect(denied.kind).toBe("block");
+	});
+
+	it("judges a pathless tool by the working directory", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		expect(await h.evaluate(customEvent("mcp"))).toBeUndefined();
+	});
+
+	it("clears session grants when the mode is reconfigured", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		asAsk(await h.evaluate(bashEvent("rm -rf /tmp/outside/x"))).request.apply(
+			"allow-session",
+		);
+		expect(await h.evaluate(bashEvent("rm -rf /tmp/outside/y"))).toBeUndefined();
+
+		await h.command("allow allow allow ask");
+		expect(asAsk(await h.evaluate(bashEvent("rm -rf /tmp/outside/y"))).kind).toBe("ask");
+	});
+});
+
+describe("dialog contract", () => {
+	it("fails closed without a UI", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		const verdict = asAsk(await h.evaluate(bashEvent("rm -rf /tmp/outside")));
+		const noUi = { ...h.ctx, hasUI: false } as ExtensionContext;
+		await expect(verdict.request.present(noUi)).resolves.toBeUndefined();
+	});
+
+	it("falls back to the host selector in non-TUI modes", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		const verdict = asAsk(await h.evaluate(bashEvent("rm -rf /tmp/outside")));
+		const rpc = {
+			cwd: h.cwd,
+			hasUI: true,
+			mode: "rpc",
+			ui: {
+				select: async () => "Allow once (a)",
+				theme: { fg: (_color: string, text: string) => text },
+			},
+		} as unknown as ExtensionContext;
+		await expect(verdict.request.present(rpc)).resolves.toBe("allow");
+	});
+});
+
+describe("model-facing banner", () => {
+	it("appends the policy only while enabled", async () => {
+		const h = makeHarness();
+		expect(h.banner()).toBeUndefined();
+		await h.command("allow allow allow ask");
+		expect(h.banner()?.systemPrompt).toContain("Permission mode");
+		expect(h.banner()?.systemPrompt).toContain("in allow/allow, out allow/ask");
+	});
+});
+
+describe("session grants cover repeat asks", () => {
+	it("stops asking for a destructive in-project command once allowed", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		const first = asAsk(await h.evaluate(bashEvent("rm -rf .")));
+		expect(first.request.details.join("\n")).toContain("recursive delete");
+		first.request.apply("allow-session");
+		expect(await h.evaluate(bashEvent("rm -rf ."))).toBeUndefined();
+	});
+
+	it("stops asking for the same opaque command once allowed", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		const command = 'cd "$DIR" && rm x';
+		const first = asAsk(await h.evaluate(bashEvent(command)));
+		expect(first.request.details.join("\n")).toContain("this exact command");
+		first.request.apply("allow-session");
+		expect(await h.evaluate(bashEvent(command))).toBeUndefined();
+	});
+});