@andares/pi-toolkits 0.8.0 → 0.9.0

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",
+		);
+	});
+});

package/src/features/permission/policy.ts

@@ -0,0 +1,338 @@
+/**
+ * permission feature — per-call decisions.
+ *
+ * The policy is evaluated per command unit: every touched path is canonicalized,
+ * classified as inside or outside the session roots, and answered by, in order:
+ *
+ *  1. the fixed secrets table (deny in every mode),
+ *  2. the fixed danger table (ask in every mode),
+ *  3. session grants (deny wins over allow),
+ *  4. the four modes.
+ *
+ * The strictest unit of a compound command wins (`deny > ask > allow`), so
+ * `cd safe && rm -rf /` cannot ride on the first segment's verdict.
+ */
+import type { PermissionModes } from "./constants.js";
+import { dangerReason, secretReason, type Effect } from "./constants.js";
+import { canonicalize, grantRoot, insideAnyRoot } from "./paths.js";
+import type { SessionRules } from "./session-rules.js";
+import type { CommandUnit } from "./units.js";
+
+export type PolicyAction = "allow" | "ask" | "deny";
+
+/** One resolved access a decision was made about. */
+export interface PolicyTarget {
+	/** Canonical absolute path. */
+	readonly path: string;
+	readonly effect: Effect;
+	readonly scope: "in" | "out";
+}
+
+export interface PolicyDecision {
+	readonly action: PolicyAction;
+	readonly unit: CommandUnit;
+	readonly target?: PolicyTarget;
+	/** Human/model-facing explanation for ask and deny. */
+	readonly reason?: string;
+}
+
+export interface PolicyContext {
+	readonly modes: PermissionModes;
+	/** Canonical session roots (working directory plus added directories). */
+	readonly roots: readonly string[];
+	readonly rules: SessionRules;
+}
+
+const SEVERITY: Record<PolicyAction, number> = { allow: 0, ask: 1, deny: 2 };
+
+/** What the session grants alone say about one access. */
+function decideSession(
+	effect: Effect,
+	pathValue: string,
+	ctx: PolicyContext,
+): "allow" | "deny" | undefined {
+	if (ctx.rules.denies(effect, pathValue)) return "deny";
+	if (ctx.rules.allows(effect, pathValue)) return "allow";
+	return undefined;
+}
+
+function worse(a: PolicyDecision, b: PolicyDecision): PolicyDecision {
+	return SEVERITY[b.action] > SEVERITY[a.action] ? b : a;
+}
+
+function modeFor(
+	modes: PermissionModes,
+	effect: Effect,
+	scope: "in" | "out",
+): "ask" | "allow" | "deny" {
+	if (effect === "read") return scope === "in" ? modes.inRead : modes.outRead;
+	return scope === "in" ? modes.inWrite : modes.outWrite;
+}
+
+/** Scope and session-grant answer for one already-canonical path. */
+function decidePath(
+	unit: CommandUnit,
+	pathValue: string,
+	effect: Effect,
+	ctx: PolicyContext,
+): PolicyDecision {
+	const scope = insideAnyRoot(ctx.roots, pathValue) ? "in" : "out";
+	const secret = secretReason(pathValue);
+	if (secret !== undefined) {
+		return {
+			action: "deny",
+			unit,
+			target: { path: pathValue, effect, scope },
+			reason: `${secret} — denied by the fixed safety table`,
+		};
+	}
+	const target: PolicyTarget = { path: pathValue, effect, scope };
+	if (ctx.rules.denies(effect, pathValue)) {
+		return {
+			action: "deny",
+			unit,
+			target,
+			reason: `${effect} under ${pathValue} was denied for this session`,
+		};
+	}
+	if (ctx.rules.allows(effect, pathValue)) {
+		return { action: "allow", unit, target };
+	}
+	const mode = modeFor(ctx.modes, effect, scope);
+	if (mode === "allow") return { action: "allow", unit, target };
+	if (mode === "deny") {
+		return {
+			action: "deny",
+			unit,
+			target,
+			reason: `${scope === "out" ? "outside-project" : "in-project"} ${effect} is set to deny`,
+		};
+	}
+	return {
+		action: "ask",
+		unit,
+		target,
+		reason:
+			scope === "out"
+				? `outside-project ${effect} requires confirmation`
+				: `in-project ${effect} requires confirmation`,
+	};
+}
+
+/** Decide one command unit. */
+export function decideUnit(
+	unit: CommandUnit,
+	ctx: PolicyContext,
+): PolicyDecision {
+	if (unit.opaque) {
+		// Session grants for an opaque program are keyed on the whole command
+		// text and checked in {@link decideProgram}; a single unit has no path
+		// to grant.
+		return {
+			action: "ask",
+			unit,
+			reason: unit.note ?? "this command could not be analysed",
+		};
+	}
+
+	const resolvedTargets = unit.targets.map((target) => ({
+		...target,
+		path: canonicalize(target.path),
+	}));
+	const canonicalBase = unit.base === null ? null : canonicalize(unit.base);
+
+	// The secrets table is absolute: it outranks both the danger table and the
+	// modes, so `sudo cat ~/.ssh/id_rsa` denies instead of asking.
+	const secret = resolvedTargets
+		.map((target) => ({ target, reason: secretReason(target.path) }))
+		.find((entry) => entry.reason !== undefined);
+	if (secret?.reason !== undefined) {
+		return {
+			action: "deny",
+			unit,
+			target: {
+				path: secret.target.path,
+				effect: secret.target.effect,
+				scope: insideAnyRoot(ctx.roots, secret.target.path) ? "in" : "out",
+			},
+			reason: `${secret.reason} — denied by the fixed safety table`,
+		};
+	}
+	if (resolvedTargets.length === 0 && canonicalBase !== null) {
+		const baseSecret = secretReason(canonicalBase);
+		if (baseSecret !== undefined) {
+			return {
+				action: "deny",
+				unit,
+				target: {
+					path: canonicalBase,
+					effect: unit.effect,
+					scope: insideAnyRoot(ctx.roots, canonicalBase) ? "in" : "out",
+				},
+				reason: `${baseSecret} — denied by the fixed safety table`,
+			};
+		}
+	}
+
+	// Session grants are the operator's explicit decision and outrank the danger
+	// table: once an operation is allowed for the session, repeating it must not
+	// ask again. A deny likewise turns a dangerous command into a denial instead
+	// of a prompt.
+	let sessionVerdict: "allow" | "deny" | undefined;
+	if (resolvedTargets.length === 0) {
+		sessionVerdict =
+			canonicalBase === null
+				? undefined
+				: decideSession(unit.effect, canonicalBase, ctx);
+	} else {
+		const verdicts = resolvedTargets.map((target) =>
+			decideSession(target.effect, target.path, ctx),
+		);
+		if (verdicts.includes("deny")) {
+			const denied = resolvedTargets[verdicts.indexOf("deny")];
+			return decidePath(unit, denied.path, denied.effect, ctx);
+		}
+		sessionVerdict = verdicts.every((verdict) => verdict === "allow")
+			? "allow"
+			: undefined;
+	}
+	if (sessionVerdict === "deny" && canonicalBase !== null) {
+		return decidePath(unit, canonicalBase, unit.effect, ctx);
+	}
+
+	// The fixed danger table asks regardless of mode: `rm -rf .` inside the
+	// project is still destructive, and scope alone cannot express that.
+	const danger = dangerReason(
+		unit.command,
+		unit.args,
+		resolvedTargets.map((target) => target.path),
+		canonicalBase,
+	);
+	const privileged = unit.headWord === "sudo" || unit.headWord === "doas";
+	if (sessionVerdict !== "allow" && (danger !== undefined || privileged)) {
+		const first = resolvedTargets[0];
+		let target: PolicyTarget | undefined;
+		if (first !== undefined) {
+			target = {
+				path: first.path,
+				effect: first.effect,
+				scope: insideAnyRoot(ctx.roots, first.path) ? "in" : "out",
+			};
+		}
+		return {
+			action: "ask",
+			unit,
+			target,
+			reason: danger ?? "privileged command",
+		};
+	}
+
+	if (resolvedTargets.length === 0) {
+		if (canonicalBase === null) {
+			return {
+				action: "ask",
+				unit,
+				reason: "the working directory could not be resolved",
+			};
+		}
+		return decidePath(unit, canonicalBase, unit.effect, ctx);
+	}
+
+	let decision = decidePath(
+		unit,
+		resolvedTargets[0].path,
+		resolvedTargets[0].effect,
+		ctx,
+	);
+	for (const target of resolvedTargets.slice(1)) {
+		decision = worse(decision, decidePath(unit, target.path, target.effect, ctx));
+	}
+	return decision;
+}
+
+/** Decide a whole bash program (or the single unit of a path-bearing tool). */
+/** Stable key for a session grant on an opaque program. */
+export function programKey(units: readonly CommandUnit[]): string {
+	return units.map((unit) => unit.raw).join(" ; ");
+}
+
+export function decideProgram(
+	units: readonly CommandUnit[],
+	ctx: PolicyContext,
+): PolicyDecision {
+	if (units.length === 0) {
+		return {
+			action: "allow",
+			unit: {
+				raw: "",
+				headWord: "",
+				command: "",
+				args: [],
+				effect: "read",
+				opaque: false,
+				base: null,
+				targets: [],
+			},
+		};
+	}
+	// A program the parser could not fully resolve has no path-level grant;
+	// the operator's "allow this session" covers the exact command text, so a
+	// repeat of the same opaque program does not ask again.
+	const opaqueUnit = units.find((unit) => unit.opaque);
+	if (opaqueUnit) {
+		const key = programKey(units);
+		if (ctx.rules.deniesCommand(key)) {
+			return {
+				action: "deny",
+				unit: opaqueUnit,
+				reason: "this command was denied for this session",
+			};
+		}
+		if (ctx.rules.allowsCommand(key)) {
+			return { action: "allow", unit: opaqueUnit };
+		}
+	}
+
+	let decision = decideUnit(units[0], ctx);
+	for (const unit of units.slice(1)) {
+		decision = worse(decision, decideUnit(unit, ctx));
+	}
+	return decision;
+}
+
+/** Root a session grant for this decision should cover. */
+export function decisionGrantRoot(
+	decision: PolicyDecision,
+	getCwd: () => string,
+): string {
+	if (decision.target) return grantRoot(decision.target.path);
+	if (decision.unit.base !== null) return grantRoot(canonicalize(decision.unit.base));
+	return grantRoot(canonicalize(getCwd()));
+}
+
+/** Effect a session grant for this decision should cover. */
+export function decisionEffect(decision: PolicyDecision): Effect {
+	return decision.target?.effect ?? decision.unit.effect;
+}
+
+/**
+ * Model-facing denial. The model receives this as the tool result, so it names
+ * the offending segment, the resolved target, and the policy that denied it —
+ * and tells the model not to retry an equivalent command.
+ */
+export function formatDenial(decision: PolicyDecision): string {
+	const lines = [`Permission denied: ${decision.unit.raw || "(empty command)"}`];
+	if (decision.target) {
+		const scope = decision.target.scope === "out" ? "outside project" : "inside project";
+		lines.push(
+			`Target: ${decision.target.path} (${scope}, ${decision.target.effect})`,
+		);
+	}
+	if (decision.reason) lines.push(`Reason: ${decision.reason}`);
+	lines.push(
+		decision.reason?.includes("fixed safety table") === true
+			? "This is a fixed safety rule; /ask-perm cannot override it. Do not retry an equivalent command."
+			: "The operator controls this with /ask-perm. Do not retry the same operation through an equivalent command.",
+	);
+	return lines.join("\n");
+}