@andares/pi-toolkits 0.8.0 → 0.9.1

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

@@ -0,0 +1,111 @@
+/**
+ * Path canonicalization, containment, grant scoping, and add-dir state.
+ */
+import { mkdirSync, mkdtempSync, realpathSync, symlinkSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+	canonicalize,
+	expandHome,
+	grantRoot,
+	insideAnyRoot,
+	isWithin,
+	readAddedDirectories,
+	sessionRoots,
+} from "./paths.js";
+
+function tempProject(): string {
+	return realpathSync(mkdtempSync(join(tmpdir(), "pi-perm-paths-")));
+}
+
+describe("expandHome", () => {
+	it("expands only a leading ~", () => {
+		expect(expandHome("~")).toBe(homedir());
+		expect(expandHome("~/x")).toBe(join(homedir(), "x"));
+		expect(expandHome("~user/x")).toBe("~user/x");
+		expect(expandHome("/abs/~/x")).toBe("/abs/~/x");
+	});
+});
+
+describe("containment", () => {
+	it("matches the root and its contents but not a sibling prefix", () => {
+		expect(isWithin("/a/b", "/a/b")).toBe(true);
+		expect(isWithin("/a/b", "/a/b/c")).toBe(true);
+		expect(isWithin("/a/b", "/a/bc")).toBe(false);
+		expect(isWithin("/a/b", "/a")).toBe(false);
+	});
+
+	it("resolves missing suffixes through the nearest existing ancestor", () => {
+		const root = tempProject();
+		expect(canonicalize(join(root, "missing", "deep", "file"))).toBe(
+			join(realpathSync(root), "missing", "deep", "file"),
+		);
+	});
+
+	it("resolves symlinks, so a link cannot walk out of the root", () => {
+		const root = tempProject();
+		const outside = tempProject();
+		writeFileSync(join(outside, "secret"), "x");
+		symlinkSync(outside, join(root, "link"));
+		const resolved = canonicalize(join(root, "link", "secret"));
+		expect(isWithin(root, resolved)).toBe(false);
+	});
+
+	it("deduplicates and canonicalizes the session roots", () => {
+		const root = tempProject();
+		const outside = tempProject();
+		const roots = sessionRoots(root, [root, outside, outside]);
+		expect(roots).toHaveLength(2);
+		expect(insideAnyRoot(roots, join(outside, "x"))).toBe(true);
+		expect(insideAnyRoot(roots, "/definitely/not/here")).toBe(false);
+	});
+});
+
+describe("grantRoot", () => {
+	it("uses the directory itself for a directory", () => {
+		const root = tempProject();
+		const dir = join(root, "build");
+		mkdirSync(dir);
+		expect(grantRoot(dir)).toBe(dir);
+	});
+
+	it("uses the parent for an existing file", () => {
+		const root = tempProject();
+		const file = join(root, "notes.txt");
+		writeFileSync(file, "x");
+		expect(grantRoot(file)).toBe(root);
+	});
+
+	it("uses the parent for a path that does not exist yet", () => {
+		const root = tempProject();
+		expect(grantRoot(join(root, "build"))).toBe(root);
+	});
+});
+
+describe("readAddedDirectories", () => {
+	it("takes the last add-dir:state entry and ignores other entries", () => {
+		const entries = [
+			{ type: "message" },
+			{ type: "custom", customType: "other", data: { dirs: [{ absolutePath: "/no" }] } },
+			{
+				type: "custom",
+				customType: "add-dir:state",
+				data: { dirs: [{ absolutePath: "/a" }, { absolutePath: "/b" }] },
+			},
+			{
+				type: "custom",
+				customType: "add-dir:state",
+				data: { dirs: [{ absolutePath: "/c" }] },
+			},
+		];
+		expect(readAddedDirectories(entries)).toEqual(["/c"]);
+	});
+
+	it("returns nothing without pi-add-dir state or with a malformed payload", () => {
+		expect(readAddedDirectories([{ type: "message" }])).toEqual([]);
+		expect(
+			readAddedDirectories([{ type: "custom", customType: "add-dir:state", data: {} }]),
+		).toEqual([]);
+	});
+});

package/src/features/permission/paths.ts

@@ -0,0 +1,126 @@
+/**
+ * permission feature — path resolution and containment.
+ *
+ * "Inside the project" means inside the session working directory or inside a
+ * directory added to the session (pi-add-dir stores those in a session entry).
+ * Containment is decided on canonical paths, so `../` and symlinks cannot walk
+ * the check out of a root; a path that does not exist yet is resolved through
+ * its nearest existing ancestor.
+ */
+import { realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve, sep } from "node:path";
+
+/** Expand a leading `~` (and only a leading `~/` or bare `~`). */
+export function expandHome(pathValue: string): string {
+	if (pathValue === "~") return homedir();
+	if (pathValue.startsWith(`~${sep}`) || pathValue.startsWith("~/")) {
+		return join(homedir(), pathValue.slice(2));
+	}
+	return pathValue;
+}
+
+/**
+ * Absolute, symlink-resolved form of `pathValue`.
+ *
+ * The path itself may not exist (a write target, `mkdir` argument, …), so the
+ * nearest existing ancestor is resolved and the missing suffix re-appended.
+ */
+export function canonicalize(pathValue: string): string {
+	const absolute = resolve(pathValue);
+	const suffix: string[] = [];
+	let current = absolute;
+	for (;;) {
+		try {
+			const real = realpathSync.native(current);
+			return suffix.length === 0
+				? real
+				: join(real, ...suffix.reverse());
+		} catch {
+			const parent = dirname(current);
+			if (parent === current) return absolute;
+			suffix.push(basename(current));
+			current = parent;
+		}
+	}
+}
+
+function fold(value: string): string {
+	return process.platform === "win32" ? value.toLowerCase() : value;
+}
+
+/** Whether `pathValue` is `root` or under it. Both must be canonical. */
+export function isWithin(root: string, pathValue: string): boolean {
+	const a = fold(root);
+	const b = fold(pathValue);
+	return b === a || b.startsWith(a.endsWith(sep) ? a : `${a}${sep}`);
+}
+
+/** The directory a session grant on `pathValue` should cover. */
+export function grantRoot(pathValue: string): string {
+	try {
+		return statSync(pathValue).isDirectory() ? pathValue : dirname(pathValue);
+	} catch {
+		// A path that does not exist (a write target, a `mkdir` argument) is
+		// granted at its enclosing directory: the operator is approving an area,
+		// and a per-file grant would ask again for the next sibling.
+		return dirname(pathValue);
+	}
+}
+
+/** Structural shape of a session entry, so no host type is imported here. */
+interface SessionEntryLike {
+	readonly type: string;
+	readonly customType?: string;
+	readonly data?: unknown;
+}
+
+interface AddDirState {
+	readonly dirs?: ReadonlyArray<{ readonly absolutePath?: unknown }>;
+}
+
+/**
+ * Directories added to the session by pi-add-dir.
+ *
+ * pi exposes no directory-list API; pi-add-dir records its state as a session
+ * custom entry (`add-dir:state`, appended on every change). The last such
+ * entry on the branch wins. Absence of pi-add-dir is a normal, silent miss —
+ * only the working directory is then in scope.
+ */
+export function readAddedDirectories(
+	entries: readonly SessionEntryLike[],
+): string[] {
+	let dirs: string[] = [];
+	for (const entry of entries) {
+		if (entry.type !== "custom" || entry.customType !== "add-dir:state") {
+			continue;
+		}
+		const state = entry.data as AddDirState | undefined;
+		if (!Array.isArray(state?.dirs)) continue;
+		dirs = state.dirs
+			.map((dir) =>
+				typeof dir?.absolutePath === "string" ? dir.absolutePath : "",
+			)
+			.filter((dir) => dir !== "");
+	}
+	return dirs;
+}
+
+/** Canonical root list for one session: working directory plus added dirs. */
+export function sessionRoots(cwd: string, added: readonly string[]): string[] {
+	const roots = new Set<string>();
+	for (const value of [cwd, ...added]) {
+		if (!value) continue;
+		roots.add(canonicalize(expandHome(value)));
+	}
+	return [...roots];
+}
+
+/** `true` when `pathValue` is inside at least one root. */
+export function insideAnyRoot(
+	roots: readonly string[],
+	pathValue: string,
+): boolean {
+	return roots.some((root) => isWithin(root, pathValue));
+}
+

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

@@ -0,0 +1,237 @@
+/**
+ * Policy decisions: defaults, fixed safety tables, session grants, severity
+ * folding, and model-facing denial text.
+ */
+import { homedir } from "node:os";
+import { mkdtempSync, realpathSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { describe, expect, it } from "vitest";
+import { DEFAULT_MODES, type PermissionModes } from "./constants.js";
+import { canonicalize } from "./paths.js";
+import {
+	decideProgram,
+	decisionEffect,
+	decisionGrantRoot,
+	formatDenial,
+	type PolicyContext,
+} from "./policy.js";
+import { SessionRules } from "./session-rules.js";
+import { parseCommandUnits } from "./units.js";
+
+function project(): string {
+	return realpathSync(mkdtempSync(join(tmpdir(), "pi-perm-policy-")));
+}
+
+function makeContext(
+	cwd: string,
+	modes: PermissionModes = DEFAULT_MODES,
+	rules = new SessionRules(),
+): PolicyContext {
+	return { modes, roots: [canonicalize(cwd)], rules };
+}
+
+function decide(command: string, ctx: PolicyContext) {
+	return decideProgram(parseCommandUnits(command, ctx.roots[0] ?? "/"), ctx);
+}
+
+describe("four-mode policy", () => {
+	it("allows in-project reads and writes by default", () => {
+		const cwd = project();
+		const ctx = makeContext(cwd);
+		expect(decide(`rm -rf ${cwd}/build`, ctx).action).toBe("allow");
+		expect(decide(`cat ${cwd}/notes.txt`, ctx).action).toBe("allow");
+	});
+
+	it("asks for an outside write and allows an outside read by default", () => {
+		const cwd = project();
+		const ctx = makeContext(cwd);
+		expect(decide("rm -rf /tmp/outside", ctx).action).toBe("ask");
+		expect(decide("cat /etc/hostname", ctx).action).toBe("allow");
+	});
+
+	it("honours a deny mode for outside writes", () => {
+		const cwd = project();
+		const ctx = makeContext(cwd, { ...DEFAULT_MODES, outWrite: "deny" });
+		const decision = decide("rm -rf /tmp/outside", ctx);
+		expect(decision.action).toBe("deny");
+		expect(decision.reason).toContain("outside-project write");
+	});
+
+	it("honours ask for in-project writes", () => {
+		const cwd = project();
+		const ctx = makeContext(cwd, { ...DEFAULT_MODES, inWrite: "ask" });
+		expect(decide(`rm ${cwd}/x`, ctx).action).toBe("ask");
+	});
+});
+
+describe("fixed safety table", () => {
+	it("denies credential paths in every mode, even when reads are allowed", () => {
+		const cwd = project();
+		const ctx = makeContext(cwd);
+		const ssh = decide(`cat ${homedir()}/.ssh/id_rsa`, ctx);
+		expect(ssh.action).toBe("deny");
+		expect(ssh.reason).toContain("credentials");
+	});
+
+	it("denies .env files but not their templates", () => {
+		const cwd = project();
+		writeFileSync(join(cwd, ".env"), "SECRET=1");
+		const ctx = makeContext(cwd);
+		expect(decide(`cat ${cwd}/.env`, ctx).action).toBe("deny");
+		expect(decide(`cat ${cwd}/.env.example`, ctx).action).toBe("allow");
+	});
+
+	it("does not let a session allow override the secrets table", () => {
+		const cwd = project();
+		const rules = new SessionRules();
+		rules.allow({ effect: "read", root: join(homedir(), ".ssh") });
+		const ctx = makeContext(cwd, DEFAULT_MODES, rules);
+		expect(decide(`cat ${homedir()}/.ssh/id_rsa`, ctx).action).toBe("deny");
+	});
+
+	it("denies a privileged read of a credential instead of asking", () => {
+		const cwd = project();
+		expect(decide(`sudo cat ${homedir()}/.ssh/id_rsa`, makeContext(cwd)).action).toBe(
+			"deny",
+		);
+	});
+
+	it("asks for destructive commands even inside the project", () => {
+		const cwd = project();
+		const ctx = makeContext(cwd);
+		const decision = decide("rm -rf .", ctx);
+		expect(decision.action).toBe("ask");
+		expect(decision.reason).toContain("recursive delete");
+	});
+
+	it("asks for a forced push and a privileged command", () => {
+		const cwd = project();
+		const ctx = makeContext(cwd);
+		expect(decide("git push --force", ctx).action).toBe("ask");
+		expect(decide("sudo rm x", ctx).action).toBe("ask");
+	});
+});
+
+describe("session grants", () => {
+	it("allows a write under a granted directory", () => {
+		const cwd = project();
+		const rules = new SessionRules();
+		rules.allow({ effect: "write", root: "/tmp/granted" });
+		expect(
+			decide("rm -rf /tmp/granted/x", makeContext(cwd, DEFAULT_MODES, rules)).action,
+		).toBe("allow");
+	});
+
+	it("does not let a read grant cover a write", () => {
+		const cwd = project();
+		const rules = new SessionRules();
+		rules.allow({ effect: "read", root: "/tmp/granted" });
+		expect(
+			decide("rm -rf /tmp/granted/x", makeContext(cwd, DEFAULT_MODES, rules)).action,
+		).toBe("ask");
+	});
+
+	it("denies before allowing, even when the mode allows", () => {
+		const cwd = project();
+		const rules = new SessionRules();
+		rules.deny({ effect: "read", root: "/tmp/granted" });
+		const decision = decide("cat /tmp/granted/x", makeContext(cwd, DEFAULT_MODES, rules));
+		expect(decision.action).toBe("deny");
+		expect(decision.reason).toContain("denied for this session");
+	});
+
+	it("clears grants", () => {
+		const rules = new SessionRules();
+		rules.allow({ effect: "write", root: "/tmp/x" });
+		rules.deny({ effect: "read", root: "/tmp/y" });
+		expect(rules.counts()).toEqual({ allow: 1, deny: 1 });
+		rules.clear();
+		expect(rules.counts()).toEqual({ allow: 0, deny: 0 });
+	});
+});
+
+describe("severity folding", () => {
+	it("takes the strictest unit of a compound command", () => {
+		const cwd = project();
+		const ctx = makeContext(cwd, { ...DEFAULT_MODES, outWrite: "deny" });
+		const decision = decide(`cd ${cwd} && rm -rf /tmp/outside`, ctx);
+		expect(decision.action).toBe("deny");
+	});
+
+	it("does not let an allowed first segment mask a later ask", () => {
+		const cwd = project();
+		const decision = decide("echo hi && rm -rf /tmp/outside", makeContext(cwd));
+		expect(decision.action).toBe("ask");
+	});
+});
+
+describe("fail closed", () => {
+	it("asks for an opaque unit regardless of mode", () => {
+		const cwd = project();
+		const ctx = makeContext(cwd, {
+			inRead: "allow",
+			inWrite: "allow",
+			outRead: "allow",
+			outWrite: "allow",
+		});
+		const decision = decide('cd "$DIR" && rm x', ctx);
+		expect(decision.action).toBe("ask");
+	});
+});
+
+describe("decision helpers", () => {
+	it("derives the grant root and effect", () => {
+		const cwd = project();
+		writeFileSync(join(cwd, "notes.txt"), "x");
+		const decision = decide(`rm ${cwd}/notes.txt`, makeContext(cwd));
+		expect(decisionGrantRoot(decision, () => cwd)).toBe(cwd);
+		expect(decisionEffect(decision)).toBe("write");
+	});
+
+	it("formats a denial for the model", () => {
+		const cwd = project();
+		const decision = decide(
+			"cat ~/.ssh/id_rsa",
+			makeContext(cwd),
+		);
+		const text = formatDenial(decision);
+		expect(text).toContain("Permission denied");
+		expect(text).toContain("/ask-perm");
+		expect(text).toContain("Do not retry");
+	});
+});
+
+describe("session grants versus the danger table", () => {
+	it("lets a session allow cover a destructive command", () => {
+		const cwd = project();
+		const rules = new SessionRules();
+		expect(decide("rm -rf .", makeContext(cwd, DEFAULT_MODES, rules)).action).toBe(
+			"ask",
+		);
+		rules.allow({ effect: "write", root: canonicalize(cwd) });
+		expect(decide("rm -rf .", makeContext(cwd, DEFAULT_MODES, rules)).action).toBe(
+			"allow",
+		);
+	});
+
+	it("turns a session deny on a dangerous command into a denial", () => {
+		const cwd = project();
+		const rules = new SessionRules();
+		rules.deny({ effect: "write", root: canonicalize(cwd) });
+		expect(decide("git push --force", makeContext(cwd, DEFAULT_MODES, rules)).action).toBe(
+			"deny",
+		);
+	});
+
+	it("covers a repeat of the exact opaque command", () => {
+		const cwd = project();
+		const rules = new SessionRules();
+		const units = parseCommandUnits('cd "$DIR" && rm x', cwd);
+		const key = units.map((unit) => unit.raw).join(" ; ");
+		rules.allowCommand(key);
+		expect(decideProgram(units, makeContext(cwd, DEFAULT_MODES, rules)).action).toBe(
+			"allow",
+		);
+	});
+});