@danypops/pi-packed 0.3.0 → 0.4.0

package/README.md

@@ -10,9 +10,9 @@ inside the supervised Bun daemon.
 
 ```text
 ┌─ Pi extension (Node-compatible) ──────────────┐
-│ pkg_search · pkg_info · pkg_install           │
-│ /packages · /packed security settings          │
-│ policy-driven approval · no Bun/SQLite access  │
+│ pkg_search · pkg_info · pkg_install · pkg_remove│
+│ /packages · /packed permission settings         │
+│ operation-aware approval · no Bun/SQLite access │
 └──────────────────┬────────────────────────────┘
                    │ authenticated loopback HTTP
 ┌─ packed.service (Bun) ────────────────────────┐
@@ -37,7 +37,7 @@ packed installed --json
 /packages
 ```
 
-Packages execute arbitrary code. `pkg_install` uses daemon-owned security settings with secure default `installApproval: always`. Open `/packed` to choose **Always require approval** or explicitly opt out with **Never require approval**. The unsafe opt-out allows agent installs without an interactive UI. `/packages` remains the package browser.
+Packages execute arbitrary code and mutate Pi settings/install roots. One daemon-owned operation policy classifies every public package operation. Install, update, remove, and security-setting changes require explicit approval by default (`mutationApproval: always`); search, info, installed, catalog, and update-status reads are bounded reads, while mirror refresh is classified maintenance. Open `/packed` to retain the recommended approval policy or deliberately choose the unsafe **Never require mutation approval** opt-out. `/packages` uses the same policy for updates and removals.
 
 ## CLI
 
@@ -49,14 +49,14 @@ Packages execute arbitrary code. `pkg_install` uses daemon-owned security settin
 | `packed mirror [--json]` | Refresh the SQLite package index |
 | `packed installed [--json]` | Read Pi's installed package declarations |
 | `packed catalog [--json]` | Inspect the local package index |
-| `packed install <source> [--json]` | Authenticated daemon install for `npm:`, `git:`, or `https://` sources |
-| `packed remove <name> [--json]` | Authenticated daemon removal by bare npm name |
-| `packed security [always\|never] [--json]` | Read or set the install approval policy |
+| `packed install <source> [--approve] [--json]` | Authenticated daemon install for `npm:`, `git:`, or `https://` sources |
+| `packed remove <name> [--approve] [--json]` | Authenticated daemon removal by bare npm name |
+| `packed security [always\|never] [--approve] [--json]` | Read or set the package mutation approval policy |
 | `packed serve` | Run the loopback daemon |
 | `packed service` | Print the systemd user unit |
 | `packed version` | Print the package/service version |
 
-Install/remove JSON results are stable objects:
+Guarded CLI mutations require `--approve` under the secure default. This is pi-packed mutation authorization, distinct from Pi's project-trust `--approve` semantics. Install/remove JSON results are stable objects:
 
 ```json
 {"ok":true,"source":"npm:pi-lsp","output":"Installed npm:pi-lsp"}
@@ -77,11 +77,11 @@ The daemon listens on loopback only.
 | `GET` | `/info?name=` |
 | `GET` | `/installed` |
 | `GET` | `/security` |
-| `POST` | `/security` with `{ "installApproval": "always" | "never" }` |
+| `POST` | `/security` with `{ "mutationApproval": "always" | "never", "approved": true }` |
 | `GET` | `/updates` |
 | `GET` | `/catalog` |
-| `POST` | `/install` with `{ "source": "..." }` |
-| `POST` | `/remove` with `{ "name": "..." }` |
+| `POST` | `/install` with `{ "source": "...", "approved": true }` |
+| `POST` | `/remove` with `{ "name": "...", "approved": true }` |
 
 State defaults to `~/.cache/pi-packed/` and contains `token`, `port`,
 `updates.json`, `security.json`, and `packed.db`. Relevant environment variables:
@@ -102,6 +102,7 @@ State defaults to `~/.cache/pi-packed/` and contains `token`, `port`,
   loopback API and reconnect after daemon restarts.
 - **Ports and adapters:** registry and installer ports keep policy independent
   from npm, SQLite, subprocess, HTTP, and UI adapters.
+- **Operation-aware authorization:** one policy matrix classifies reads, maintenance, code execution, settings mutation, and security mutation; guarded daemon routes reject missing approval with stable `approval_required` errors.
 - **Allowlisted mutation input:** package sources and names reject shell
   metacharacters before reaching the installer.
 - **Bounded requests:** daemon calls use timeouts and return structured errors

package/extension/src/packed.ts

@@ -8,7 +8,7 @@
  */
 import type { PackageDaemonPort as ClientPackageDaemonPort } from "../../src/client.ts";
 import type { InstalledPkg, Pkg, PkgInfo, UpdateEntry } from "../../src/ports.ts";
-import type { InstallApproval, SecuritySettings } from "../../src/security.ts";
+import type { MutationApproval, SecuritySettings } from "../../src/security.ts";
 
 export type { InstalledPkg, UpdateEntry };
 export type PackageInfo = PkgInfo;
@@ -27,9 +27,9 @@ export interface Natives {
 	installed(): Promise<InstalledPkg[]>;
 	updates(): Promise<UpdateEntry[]>;
 	security(): Promise<SecuritySettings>;
-	setInstallApproval(value: InstallApproval): Promise<SecuritySettings>;
-	install(source: string): Promise<string>;
-	remove(name: string): Promise<string>;
+	setMutationApproval(value: MutationApproval, approved?: boolean): Promise<SecuritySettings>;
+	install(source: string, approved?: boolean): Promise<string>;
+	remove(name: string, approved?: boolean): Promise<string>;
 }
 
 export type PackageDaemonConnector = () => Promise<PackageDaemonPort>;
@@ -62,8 +62,8 @@ export async function createNatives(connect: PackageDaemonConnector = connectDef
 		installed: () => call((daemon) => daemon.installed()),
 		updates: () => call((daemon) => daemon.updates()),
 		security: () => call((daemon) => daemon.security()),
-		setInstallApproval: (value) => call((daemon) => daemon.setInstallApproval(value)),
-		install: (source) => call((daemon) => daemon.install(source)),
-		remove: (name) => call((daemon) => daemon.remove(name)),
+		setMutationApproval: (value, approved) => call((daemon) => daemon.setMutationApproval(value, approved)),
+		install: (source, approved) => call((daemon) => daemon.install(source, approved)),
+		remove: (name, approved) => call((daemon) => daemon.remove(name, approved)),
 	};
 }

package/extension/src/security-tui.ts

@@ -1,10 +1,10 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import type { InstallApproval } from "../../src/security.ts";
+import type { MutationApproval } from "../../src/security.ts";
 import type { Natives } from "./packed.ts";
 
-const OPTIONS: Array<{ value: InstallApproval; label: string }> = [
-	{ value: "always", label: "Always require approval (recommended)" },
-	{ value: "never", label: "Never require approval (unsafe opt-out)" },
+const OPTIONS: Array<{ value: MutationApproval; label: string }> = [
+	{ value: "always", label: "Always require mutation approval (recommended)" },
+	{ value: "never", label: "Never require mutation approval (unsafe opt-out)" },
 ];
 
 export async function showPackedSettings(ctx: ExtensionCommandContext, natives: Natives): Promise<void> {
@@ -15,17 +15,24 @@ export async function showPackedSettings(ctx: ExtensionCommandContext, natives:
 	try {
 		const current = await natives.security();
 		const choice = await ctx.ui.select(
-			`Package install approval · current: ${current.installApproval}`,
+			`Package mutation approval · current: ${current.mutationApproval}`,
 			[...OPTIONS.map(({ label }) => label), "Cancel"],
 		);
 		const selected = OPTIONS.find(({ label }) => label === choice);
-		if (!selected || selected.value === current.installApproval) return;
-		const updated = await natives.setInstallApproval(selected.value);
+		if (!selected || selected.value === current.mutationApproval) return;
+		const approved = await ctx.ui.confirm(
+			"Change package mutation approval",
+			selected.value === "never"
+				? "Disable confirmation for install, update, remove, and package security changes? Packages can execute arbitrary code."
+				: "Restore confirmation for install, update, remove, and package security changes?",
+		);
+		if (!approved) return;
+		const updated = await natives.setMutationApproval(selected.value, true);
 		ctx.ui.notify(
-			updated.installApproval === "always"
-				? "Package installs now require confirmation."
-				: "Package install confirmation disabled. Packages can execute arbitrary code.",
-			updated.installApproval === "always" ? "info" : "warning",
+			updated.mutationApproval === "always"
+				? "Package mutations now require confirmation."
+				: "Package mutation confirmation disabled. Packages can execute arbitrary code.",
+			updated.mutationApproval === "always" ? "info" : "warning",
 		);
 	} catch (error) {
 		ctx.ui.notify(`packed security settings failed: ${error instanceof Error ? error.message : error}`, "error");

package/extension/src/tools.ts

@@ -1,61 +1,88 @@
-/**
- * tools.ts — agent-facing tools. Thin by design: descriptions teach the
- * agent the packed CLI surface; logic lives in the Bun service.
- */
+/** Agent-facing package tools over the authenticated daemon. */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { packagePermissionDecision, type PackageOperation } from "../../src/security.ts";
 import type { Natives } from "./packed.js";
 
 function text(t: string, details: Record<string, unknown> = {}) {
 	return { content: [{ type: "text" as const, text: t }], details };
 }
 
+type ApprovalContext = {
+	hasUI: boolean;
+	ui: { confirm(title: string, message: string): Promise<boolean> };
+};
+
+export async function approvePackageOperation(
+	operation: PackageOperation,
+	command: string,
+	natives: Pick<Natives, "security">,
+	ctx: ApprovalContext,
+): Promise<{ allowed: boolean; approved: boolean; message?: string }> {
+	const settings = await natives.security();
+	const decision = packagePermissionDecision(settings, operation);
+	if (!decision.approvalRequired) return { allowed: true, approved: false };
+	if (!ctx.hasUI) {
+		return {
+			allowed: false,
+			approved: false,
+			message: `${operation} requires interactive approval; change mutationApproval in /packed only to deliberately opt out.`,
+		};
+	}
+	const approved = await ctx.ui.confirm(
+		`${operation[0]!.toUpperCase()}${operation.slice(1)} Pi package`,
+		`Run: ${command}\n\nThis operation can execute package code or mutate Pi settings/install roots. Continue?`,
+	);
+	return approved ? { allowed: true, approved: true } : { allowed: false, approved: false, message: `${operation} cancelled by user.` };
+}
+
 export async function installPackageWithPolicy(
 	source: string,
 	natives: Pick<Natives, "security" | "install">,
-	ctx: { hasUI: boolean; ui: { confirm(title: string, message: string): Promise<boolean> } },
+	ctx: ApprovalContext,
 ) {
 	try {
-		const { installApproval } = await natives.security();
-		if (installApproval === "always") {
-			if (!ctx.hasUI) return text("pkg_install requires interactive approval; change installApproval in /packed to opt out.");
-			const ok = await ctx.ui.confirm(
-				"Install Pi package",
-				`Run: pi install ${source}\n\nPackages execute arbitrary code. Continue?`,
-			);
-			if (!ok) return text("Install cancelled by user.");
-		}
-		const out = await natives.install(source);
+		const approval = await approvePackageOperation("install", `pi install ${source}`, natives, ctx);
+		if (!approval.allowed) return text(approval.message ?? "install denied");
+		const out = await natives.install(source, approval.approved);
 		return text(out || `Installed ${source}. Reload with /reload to activate.`);
 	} catch (error) {
 		return text(`install failed: ${error instanceof Error ? error.message : error}`);
 	}
 }
 
+export async function removePackageWithPolicy(
+	name: string,
+	natives: Pick<Natives, "security" | "remove">,
+	ctx: ApprovalContext,
+) {
+	try {
+		const approval = await approvePackageOperation("remove", `pi remove npm:${name}`, natives, ctx);
+		if (!approval.allowed) return text(approval.message ?? "remove denied");
+		const out = await natives.remove(name, approval.approved);
+		return text(out || `Removed ${name}. Reload with /reload to deactivate.`);
+	} catch (error) {
+		return text(`remove failed: ${error instanceof Error ? error.message : error}`);
+	}
+}
+
 export function registerTools(pi: ExtensionAPI, natives: Natives): void {
 	pi.registerTool({
 		name: "pkg_search",
 		label: "Pi Package Search",
-		description:
-			"Search Pi packages (extensions, skills, themes, prompts) on the npm registry. " +
-			"Scoped to the pi-package keyword automatically. Returns name, version, description.",
+		description: "Search Pi packages on npm. Bounded read operation; defaults to 10 results and caps at 50.",
 		parameters: Type.Object({
 			query: Type.String({ description: "Search terms, e.g. 'lsp' or 'telegram'" }),
 			limit: Type.Optional(Type.Number({ description: "Max results (default 10, max 50)" })),
 		}),
-		async execute(_id, params, _signal, _onUpdate, _ctx) {
+		async execute(_id, params) {
 			try {
 				const r = await natives.search(params.query, params.limit ?? 10);
 				if (r.results.length === 0) return text(`No Pi packages found for "${params.query}".`);
-				const lines = r.results.map(
-					(p, i) => `${i + 1}. ${p.name}@${p.version}\n   ${p.description ?? ""}`,
-				);
-				return text(
-					`Found ${r.total} pi package(s) (showing ${r.results.length}):\n\n${lines.join("\n")}`,
-					{ results: r.results, total: r.total },
-				);
-			} catch (e) {
-				return text(`pkg_search failed: ${e instanceof Error ? e.message : e}`);
+				const lines = r.results.map((p, i) => `${i + 1}. ${p.name}@${p.version}\n   ${p.description ?? ""}`);
+				return text(`Found ${r.total} pi package(s) (showing ${r.results.length}):\n\n${lines.join("\n")}`, { results: r.results, total: r.total });
+			} catch (error) {
+				return text(`pkg_search failed: ${error instanceof Error ? error.message : error}`);
 			}
 		},
 	});
@@ -63,13 +90,9 @@ export function registerTools(pi: ExtensionAPI, natives: Natives): void {
 	pi.registerTool({
 		name: "pkg_info",
 		label: "Pi Package Info",
-		description:
-			"Show details for a Pi package: latest version, description, repository, " +
-			"declared pi resources (extensions/skills/themes/prompts), size, license.",
-		parameters: Type.Object({
-			name: Type.String({ description: "npm package name, e.g. 'pi-lsp' or '@scope/pkg'" }),
-		}),
-		async execute(_id, params, _signal, _onUpdate, _ctx) {
+		description: "Show bounded metadata and declared Pi resources for one package.",
+		parameters: Type.Object({ name: Type.String({ description: "npm package name" }) }),
+		async execute(_id, params) {
 			try {
 				const info = await natives.info(params.name);
 				const lines = [
@@ -82,8 +105,8 @@ export function registerTools(pi: ExtensionAPI, natives: Natives): void {
 					info.modified ? `modified: ${info.modified}` : "",
 				].filter(Boolean);
 				return text(lines.join("\n"), { info });
-			} catch (e) {
-				return text(`pkg_info failed: ${e instanceof Error ? e.message : e}`);
+			} catch (error) {
+				return text(`pkg_info failed: ${error instanceof Error ? error.message : error}`);
 			}
 		},
 	});
@@ -91,14 +114,20 @@ export function registerTools(pi: ExtensionAPI, natives: Natives): void {
 	pi.registerTool({
 		name: "pkg_install",
 		label: "Pi Package Install",
-		description:
-			"Install a Pi package (pi install). Supports npm:<pkg>[@ver], git:<host>/<owner>/<repo>[@ref], " +
-			"or https:// URLs. Packages execute arbitrary code. Approval follows the installApproval policy configured in /packed (secure default: always).",
-		parameters: Type.Object({
-			source: Type.String({ description: "e.g. 'npm:pi-lsp', 'npm:@scope/pkg@1.2.3', 'git:github.com/u/r@v1'" }),
-		}),
+		description: "Install a Pi package through the authenticated daemon. Operation-aware approval is secure by default.",
+		parameters: Type.Object({ source: Type.String({ description: "npm:, git:, or https source" }) }),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			return installPackageWithPolicy(params.source, natives, ctx);
 		},
 	});
+
+	pi.registerTool({
+		name: "pkg_remove",
+		label: "Pi Package Remove",
+		description: "Remove an installed npm Pi package through the authenticated daemon. Operation-aware approval is secure by default.",
+		parameters: Type.Object({ name: Type.String({ description: "bare npm name, e.g. pi-lsp or @scope/pkg" }) }),
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return removePackageWithPolicy(params.name, natives, ctx);
+		},
+	});
 }

package/extension/src/tui.ts

@@ -10,6 +10,7 @@ import { Container, Input, Spacer, truncateToWidth, visibleWidth } from "@earend
 import { filterRows, mergeRows, nextMode, visibleRows } from "./model.js";
 import type { Row, ViewMode } from "./model.js";
 import type { Natives } from "./packed.js";
+import { approvePackageOperation } from "./tools.js";
 
 interface PanelAction {
 	type: "menu" | "refresh";
@@ -64,9 +65,14 @@ export async function showPackages(ctx: ExtensionCommandContext, natives: Native
 		);
 
 		if (choice?.startsWith("Update")) {
-			ctx.ui.notify(`Updating ${row.name}…`, "info");
 			try {
-				await natives.install(`npm:${row.name}@${row.latest}`);
+				const approval = await approvePackageOperation("update", `pi update --extension npm:${row.name}`, natives, ctx);
+				if (!approval.allowed) {
+					ctx.ui.notify(approval.message ?? "update denied", "warning");
+					continue;
+				}
+				ctx.ui.notify(`Updating ${row.name}…`, "info");
+				await natives.install(`npm:${row.name}@${row.latest}`, approval.approved);
 				ctx.ui.notify(`Updated ${row.name} to ${row.latest} (takes effect after /reload)`, "info");
 				row.version = row.latest ?? row.version;
 				row.hasUpdate = false;
@@ -74,15 +80,17 @@ export async function showPackages(ctx: ExtensionCommandContext, natives: Native
 				ctx.ui.notify(`update failed: ${e instanceof Error ? e.message : e}`, "error");
 			}
 		} else if (choice === "Remove") {
-			const sure = await ctx.ui.confirm("Remove package", `pi remove npm:${row.name}?`);
-			if (sure) {
-				try {
-					await natives.remove(row.name);
+			try {
+				const approval = await approvePackageOperation("remove", `pi remove npm:${row.name}`, natives, ctx);
+				if (approval.allowed) {
+					await natives.remove(row.name, approval.approved);
 					ctx.ui.notify(`Removed ${row.name}`, "info");
 					rows = rows.filter((r) => r.name !== row.name);
-				} catch (e) {
-					ctx.ui.notify(`remove failed: ${e instanceof Error ? e.message : e}`, "error");
+				} else {
+					ctx.ui.notify(approval.message ?? "remove denied", "warning");
 				}
+			} catch (e) {
+				ctx.ui.notify(`remove failed: ${e instanceof Error ? e.message : e}`, "error");
 			}
 		}
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-packed",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Package service for the Pi agent: search/info/install/updates + /packages TUI, backed by a long-running Bun service",
   "type": "module",
   "keywords": [

package/src/cli.ts

@@ -11,15 +11,21 @@ import { checkUpdates } from "./watcher.ts";
 import { syncCatalog } from "./catalog.ts";
 import { openDb, searchLocal, catalogList, getSyncMeta, latestVersion, dbPath } from "./db.ts";
 import { NAME_RE, defaultPiBin } from "./install.ts";
-import type { InstallApproval, SecuritySettingsPort } from "./security.ts";
+import {
+	assertPackagePermission,
+	type MutationApproval,
+	type PackageOperation,
+	type SecuritySettingsPort,
+} from "./security.ts";
 
 function defaultPiBinForUnit(): string | undefined {
 	const b = defaultPiBin();
 	return b === "pi" ? undefined : b; // bare name needs no pin
 }
 import {
-	VERSION, SEARCH_DEFAULT_LIMIT, SEARCH_MAX_LIMIT, NPM_REGISTRY_BASE, SEARCH_PAGE_SIZE, MIRROR_PAGE_DELAY_MS,
+	SEARCH_DEFAULT_LIMIT, SEARCH_MAX_LIMIT, NPM_REGISTRY_BASE, SEARCH_PAGE_SIZE, MIRROR_PAGE_DELAY_MS,
 } from "./constants.ts";
+import { VERSION } from "./version.ts";
 
 const SOURCE_RE = /^(npm:[A-Za-z0-9@._/-]+|git:[A-Za-z0-9@:._/-]+|https:\/\/[A-Za-z0-9@:._/?=&%~-]+)$/;
 
@@ -32,9 +38,9 @@ usage:
   packed mirror [--json]                       sync upstream into the local SQLite index
   packed installed [--json]                    installed pi packages
   packed catalog [--json]                      local package index (apt-cache stats)
-  packed install <source> [--json]             pi install npm:|git:|https://… via daemon
-  packed remove <name> [--json]                remove by bare npm name via daemon
-  packed security [always|never] [--json]       read or set install approval policy
+  packed install <source> [--approve] [--json] pi install npm:|git:|https://… via daemon
+  packed remove <name> [--approve] [--json]    remove by bare npm name via daemon
+  packed security [always|never] [--approve] [--json] read or set mutation approval policy
   packed serve                                 run the long-running daemon
   packed service                               print a systemd user unit
   packed version                               print version
@@ -61,16 +67,18 @@ interface Flags {
 	limit: number;
 	cached: boolean;
 	offline: boolean;
+	approved: boolean;
 }
 
 function parseFlags(rest: string[]): { flags: Flags; pos: string[] } {
-	const flags: Flags = { json: false, limit: SEARCH_DEFAULT_LIMIT, cached: false, offline: false };
+	const flags: Flags = { json: false, limit: SEARCH_DEFAULT_LIMIT, cached: false, offline: false, approved: false };
 	const pos: string[] = [];
 	for (let i = 0; i < rest.length; i++) {
 		const a = rest[i]!;
 		if (a === "--json") flags.json = true;
 		else if (a === "--cached") flags.cached = true;
 		else if (a === "--offline") flags.offline = true;
+		else if (a === "--approve") flags.approved = true;
 		else if (a === "--limit" && i + 1 < rest.length) flags.limit = Number(rest[++i]) || SEARCH_DEFAULT_LIMIT;
 		else if (a.startsWith("--limit=")) flags.limit = Number(a.slice(8)) || SEARCH_DEFAULT_LIMIT;
 		else pos.push(a);
@@ -84,6 +92,17 @@ const ok = (out: string): CliResult => ({ code: 0, out });
 const fail = (out: string, code = 1): CliResult => ({ code, out });
 const usageErr = (out: string): CliResult => ({ code: 2, out });
 
+const PACKAGE_COMMAND_OPERATIONS: Record<string, PackageOperation | undefined> = {
+	search: "search",
+	info: "info",
+	installed: "installed",
+	catalog: "catalog",
+	updates: "updates",
+	mirror: "mirror",
+	install: "install",
+	remove: "remove",
+};
+
 const commands: Record<string, { usage: string; run: Command }> = {
 	search: {
 		usage: "packed search <query> [--offline] [--limit N] [--json]",
@@ -193,7 +212,7 @@ const commands: Record<string, { usage: string; run: Command }> = {
 			const source = pos[0] ?? "";
 			if (!SOURCE_RE.test(source)) return usageErr(`usage: ${commands["install"]!.usage}\n`);
 			try {
-				const output = await d.inst.install(source);
+				const output = await d.inst.install(source, { approved: flags.approved });
 				return flags.json ? ok(`${JSON.stringify({ ok: true, source, output })}\n`) : ok(`${output}\n`);
 			} catch (e) {
 				const error = e instanceof Error ? e.message : String(e);
@@ -210,11 +229,11 @@ const commands: Record<string, { usage: string; run: Command }> = {
 				return usageErr(`usage: ${commands["security"]!.usage}\n`);
 			}
 			const settings = requested
-				? await d.security.setInstallApproval(requested as InstallApproval)
+				? await d.security.setMutationApproval(requested as MutationApproval, { approved: flags.approved })
 				: await d.security.security();
 			return flags.json
 				? ok(`${JSON.stringify(settings)}\n`)
-				: ok(`install approval: ${settings.installApproval}\n`);
+				: ok(`package mutation approval: ${settings.mutationApproval}\n`);
 		},
 	},
 
@@ -224,7 +243,7 @@ const commands: Record<string, { usage: string; run: Command }> = {
 			const name = pos[0] ?? "";
 			if (!NAME_RE.test(name)) return usageErr(`usage: ${commands["remove"]!.usage}\n`);
 			try {
-				const output = await d.inst.remove(`npm:${name}`);
+				const output = await d.inst.remove(`npm:${name}`, { approved: flags.approved });
 				return flags.json ? ok(`${JSON.stringify({ ok: true, name, output })}\n`) : ok(`${output}\n`);
 			} catch (e) {
 				const error = e instanceof Error ? e.message : String(e);
@@ -280,6 +299,15 @@ export async function cliRun(args: string[], d: CliDeps): Promise<CliResult> {
 	if (!cmd) return usageErr(`unknown command "${name}"\n${USAGE}`);
 	const { flags, pos } = parseFlags(rest);
 	try {
+		const validMutationInput = name === "install"
+			? SOURCE_RE.test(pos[0] ?? "")
+			: name === "remove" ? NAME_RE.test(pos[0] ?? "")
+				: name === "security" ? (pos[0] === undefined || pos[0] === "always" || pos[0] === "never")
+					: true;
+		const operation = name === "security"
+			? (pos[0] === undefined ? "security.read" : "security.write")
+			: PACKAGE_COMMAND_OPERATIONS[name];
+		if (operation && validMutationInput) assertPackagePermission(await d.security.security(), operation, flags.approved);
 		return await cmd.run(rest, d, flags, pos);
 	} catch (e) {
 		return fail(`${name} failed: ${e instanceof Error ? e.message : e}\n`);

package/src/client.ts

@@ -8,7 +8,7 @@ import { join } from "node:path";
 import type { InstalledPkg, Installer, PkgInfo, Registry, SearchPage, UpdateEntry, UpdatesSnapshot } from "./ports.ts";
 import { HttpRegistry } from "./registry.ts";
 import { DAEMON_HOST, PROBE_TIMEOUT_MS, REGISTRY_FETCH_TIMEOUT_MS, PORT_FILE, TOKEN_FILE } from "./constants.ts";
-import type { InstallApproval, SecuritySettings } from "./security.ts";
+import type { MutationApproval, SecuritySettings } from "./security.ts";
 
 export type FetchTransport = (request: Request) => Promise<Response>;
 
@@ -18,9 +18,9 @@ export interface PackageDaemonPort {
 	installed(): Promise<InstalledPkg[]>;
 	updates(): Promise<UpdateEntry[]>;
 	security(): Promise<SecuritySettings>;
-	setInstallApproval(value: InstallApproval): Promise<SecuritySettings>;
-	install(source: string): Promise<string>;
-	remove(name: string): Promise<string>;
+	setMutationApproval(value: MutationApproval, approved?: boolean): Promise<SecuritySettings>;
+	install(source: string, approved?: boolean): Promise<string>;
+	remove(name: string, approved?: boolean): Promise<string>;
 }
 
 interface MutationResponse {
@@ -92,23 +92,23 @@ export class PackageDaemonClient implements PackageDaemonPort {
 		return this.request("/security");
 	}
 
-	setInstallApproval(installApproval: InstallApproval): Promise<SecuritySettings> {
-		return this.request("/security", { method: "POST", body: JSON.stringify({ installApproval }) });
+	setMutationApproval(mutationApproval: MutationApproval, approved = false): Promise<SecuritySettings> {
+		return this.request("/security", { method: "POST", body: JSON.stringify({ mutationApproval, approved }) });
 	}
 
-	async install(source: string): Promise<string> {
+	async install(source: string, approved = false): Promise<string> {
 		const result = await this.request<MutationResponse>("/install", {
 			method: "POST",
-			body: JSON.stringify({ source }),
+			body: JSON.stringify({ source, approved }),
 		});
 		if (!result.ok) throw new PackageDaemonError(result.output || `failed to install ${source}`, "install");
 		return result.output;
 	}
 
-	async remove(name: string): Promise<string> {
+	async remove(name: string, approved = false): Promise<string> {
 		const result = await this.request<MutationResponse>("/remove", {
 			method: "POST",
-			body: JSON.stringify({ name }),
+			body: JSON.stringify({ name, approved }),
 		});
 		if (!result.ok) throw new PackageDaemonError(result.output || `failed to remove ${name}`, "remove");
 		return result.output;
@@ -118,15 +118,15 @@ export class PackageDaemonClient implements PackageDaemonPort {
 export class PackageDaemonInstaller implements Installer {
 	constructor(private readonly client: PackageDaemonClient) {}
 
-	install(source: string): Promise<string> {
-		return this.client.install(source);
+	install(source: string, options?: { approved?: boolean }): Promise<string> {
+		return this.client.install(source, options?.approved);
 	}
 
-	remove(source: string): Promise<string> {
+	remove(source: string, options?: { approved?: boolean }): Promise<string> {
 		if (!source.startsWith("npm:") || source.length <= 4) {
 			throw new PackageDaemonError("daemon package removal requires an npm: source", "remove");
 		}
-		return this.client.remove(source.slice(4));
+		return this.client.remove(source.slice(4), options?.approved);
 	}
 }
 
@@ -135,20 +135,20 @@ export class DaemonBackedSecurity {
 	async security(): Promise<SecuritySettings> {
 		return (await connectPackageDaemon(this.stateDirectory)).security();
 	}
-	async setInstallApproval(value: InstallApproval): Promise<SecuritySettings> {
-		return (await connectPackageDaemon(this.stateDirectory)).setInstallApproval(value);
+	async setMutationApproval(value: MutationApproval, options?: { approved?: boolean }): Promise<SecuritySettings> {
+		return (await connectPackageDaemon(this.stateDirectory)).setMutationApproval(value, options?.approved);
 	}
 }
 
 export class DaemonBackedInstaller implements Installer {
 	constructor(private readonly stateDirectory: string) {}
 
-	async install(source: string): Promise<string> {
-		return (await connectPackageDaemon(this.stateDirectory)).install(source);
+	async install(source: string, options?: { approved?: boolean }): Promise<string> {
+		return (await connectPackageDaemon(this.stateDirectory)).install(source, options?.approved);
 	}
 
-	async remove(source: string): Promise<string> {
-		return new PackageDaemonInstaller(await connectPackageDaemon(this.stateDirectory)).remove(source);
+	async remove(source: string, options?: { approved?: boolean }): Promise<string> {
+		return new PackageDaemonInstaller(await connectPackageDaemon(this.stateDirectory)).remove(source, options);
 	}
 }
 

package/src/constants.ts

@@ -31,7 +31,6 @@ export const IDLE_BUDGET_DEFAULT_MS = 10 * 60_000; // on-demand self-exit
 export const WATCHDOG_TICK_MS = 15_000;
 
 // --- Identity ---
-export const VERSION = "0.3.0";
 
 // --- State-dir file names ---
 export const TOKEN_FILE = "token";

package/src/install.ts

@@ -23,11 +23,11 @@ export class ExecInstaller implements Installer {
 		return out;
 	}
 
-	install(source: string): Promise<string> {
+	install(source: string, _options?: { approved?: boolean }): Promise<string> {
 		return this.run(["install", source]);
 	}
 
-	remove(source: string): Promise<string> {
+	remove(source: string, _options?: { approved?: boolean }): Promise<string> {
 		return this.run(["remove", source]);
 	}
 }

package/src/ports.ts

@@ -39,8 +39,8 @@ export interface Registry {
 
 /** Driven port: pi CLI mutations. */
 export interface Installer {
-	install(source: string): Promise<string>;
-	remove(source: string): Promise<string>;
+	install(source: string, options?: { approved?: boolean }): Promise<string>;
+	remove(source: string, options?: { approved?: boolean }): Promise<string>;
 }
 
 export interface InstalledPkg {

package/src/security.ts

@@ -2,21 +2,82 @@ import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { SECURITY_FILE } from "./constants.ts";
 
-export const INSTALL_APPROVAL_VALUES = ["always", "never"] as const;
-export type InstallApproval = typeof INSTALL_APPROVAL_VALUES[number];
-export interface SecuritySettings { installApproval: InstallApproval }
+export const MUTATION_APPROVAL_VALUES = ["always", "never"] as const;
+export type MutationApproval = typeof MUTATION_APPROVAL_VALUES[number];
+
+export const PACKAGE_OPERATIONS = [
+	"search",
+	"info",
+	"installed",
+	"catalog",
+	"updates",
+	"security.read",
+	"mirror",
+	"install",
+	"update",
+	"remove",
+	"security.write",
+] as const;
+export type PackageOperation = typeof PACKAGE_OPERATIONS[number];
+export type PackageOperationClassification = "read" | "maintenance" | "code-execution" | "settings-mutation" | "security-mutation";
+
+export interface SecuritySettings { mutationApproval: MutationApproval }
 export interface SecuritySettingsPort {
 	security(): Promise<SecuritySettings>;
-	setInstallApproval(value: InstallApproval): Promise<SecuritySettings>;
+	setMutationApproval(value: MutationApproval, options?: { approved?: boolean }): Promise<SecuritySettings>;
+}
+
+export interface PackagePermissionDecision {
+	operation: PackageOperation;
+	classification: PackageOperationClassification;
+	approvalRequired: boolean;
 }
 
-export const DEFAULT_SECURITY_SETTINGS: SecuritySettings = { installApproval: "always" };
+export const DEFAULT_SECURITY_SETTINGS: SecuritySettings = { mutationApproval: "always" };
+
+const CLASSIFICATIONS: Record<PackageOperation, PackageOperationClassification> = {
+	search: "read",
+	info: "read",
+	installed: "read",
+	catalog: "read",
+	updates: "read",
+	"security.read": "read",
+	mirror: "maintenance",
+	install: "code-execution",
+	update: "code-execution",
+	remove: "settings-mutation",
+	"security.write": "security-mutation",
+};
+
+export class PackageApprovalRequiredError extends Error {
+	readonly code = "approval_required";
+	constructor(readonly operation: PackageOperation) {
+		super(`approval required for package operation ${operation}`);
+		this.name = "PackageApprovalRequiredError";
+	}
+}
+
+export function packagePermissionDecision(settings: SecuritySettings, operation: PackageOperation): PackagePermissionDecision {
+	const classification = CLASSIFICATIONS[operation];
+	const guarded = classification === "code-execution" || classification === "settings-mutation" || classification === "security-mutation";
+	return { operation, classification, approvalRequired: guarded && settings.mutationApproval === "always" };
+}
+
+export function assertPackagePermission(settings: SecuritySettings, operation: PackageOperation, approved = false): void {
+	if (packagePermissionDecision(settings, operation).approvalRequired && !approved) {
+		throw new PackageApprovalRequiredError(operation);
+	}
+}
 
 export function readSecuritySettings(stateDir: string): SecuritySettings {
 	try {
-		const value = JSON.parse(readFileSync(join(stateDir, SECURITY_FILE), "utf8")) as { installApproval?: unknown };
-		return INSTALL_APPROVAL_VALUES.includes(value.installApproval as InstallApproval)
-			? { installApproval: value.installApproval as InstallApproval }
+		const value = JSON.parse(readFileSync(join(stateDir, SECURITY_FILE), "utf8")) as {
+			mutationApproval?: unknown;
+			installApproval?: unknown;
+		};
+		const stored = value.mutationApproval ?? value.installApproval;
+		return MUTATION_APPROVAL_VALUES.includes(stored as MutationApproval)
+			? { mutationApproval: stored as MutationApproval }
 			: { ...DEFAULT_SECURITY_SETTINGS };
 	} catch {
 		return { ...DEFAULT_SECURITY_SETTINGS };
@@ -24,7 +85,7 @@ export function readSecuritySettings(stateDir: string): SecuritySettings {
 }
 
 export function writeSecuritySettings(stateDir: string, settings: SecuritySettings): SecuritySettings {
-	if (!INSTALL_APPROVAL_VALUES.includes(settings.installApproval)) throw new Error("installApproval must be always or never");
+	if (!MUTATION_APPROVAL_VALUES.includes(settings.mutationApproval)) throw new Error("mutationApproval must be always or never");
 	mkdirSync(stateDir, { recursive: true, mode: 0o700 });
 	const target = join(stateDir, SECURITY_FILE);
 	const temporary = `${target}.tmp`;

package/src/service.ts

@@ -9,9 +9,17 @@ import { TTLCache } from "./cache.ts";
 import { loadUpdates } from "./watcher.ts";
 import { readInstalledPackages, defaultPiHome } from "./installed.ts";
 import { openDb, searchLocal, catalogList, getSyncMeta, dbPath } from "./db.ts";
-import { VERSION, SEARCH_DEFAULT_LIMIT, SEARCH_MAX_LIMIT } from "./constants.ts";
+import { SEARCH_DEFAULT_LIMIT, SEARCH_MAX_LIMIT } from "./constants.ts";
+import { VERSION } from "./version.ts";
 import { createLogger } from "./log.ts";
-import { readSecuritySettings, writeSecuritySettings, type InstallApproval } from "./security.ts";
+import {
+	assertPackagePermission,
+	PackageApprovalRequiredError,
+	readSecuritySettings,
+	writeSecuritySettings,
+	type MutationApproval,
+	type PackageOperation,
+} from "./security.ts";
 
 const log = createLogger("service");
 
@@ -31,13 +39,25 @@ function json(v: unknown, init?: ResponseInit): Response {
 	return Response.json(v, init);
 }
 
-function err(status: number, msg: string): Response {
-	return json({ error: msg }, { status });
+function err(status: number, msg: string, details: Record<string, unknown> = {}): Response {
+	return json({ error: msg, ...details }, { status });
 }
 
 export function createApp(deps: Deps): { fetch: (req: Request) => Promise<Response> } {
 	const cache = deps.cache ?? new TTLCache();
 
+	function authorize(operation: PackageOperation, approved: boolean): Response | undefined {
+		try {
+			assertPackagePermission(readSecuritySettings(deps.stateDir), operation, approved);
+			return undefined;
+		} catch (error) {
+			if (error instanceof PackageApprovalRequiredError) {
+				return err(403, error.message, { code: error.code, operation: error.operation });
+			}
+			throw error;
+		}
+	}
+
 	async function route(req: Request): Promise<Response> {
 		const url = new URL(req.url);
 		const path = url.pathname;
@@ -51,16 +71,18 @@ export function createApp(deps: Deps): { fetch: (req: Request) => Promise<Respon
 		}
 
 		if (path === "/security" && req.method === "POST") {
-			let installApproval: unknown;
+			let body: { mutationApproval?: unknown; approved?: unknown };
 			try {
-				installApproval = ((await req.json()) as { installApproval?: unknown }).installApproval;
+				body = (await req.json()) as typeof body;
 			} catch {
 				return err(400, "invalid security settings JSON");
 			}
-			if (installApproval !== "always" && installApproval !== "never") {
-				return err(400, "installApproval must be always or never");
+			if (body.mutationApproval !== "always" && body.mutationApproval !== "never") {
+				return err(400, "mutationApproval must be always or never");
 			}
-			return json(writeSecuritySettings(deps.stateDir, { installApproval: installApproval as InstallApproval }));
+			const denied = authorize("security.write", body.approved === true);
+			if (denied) return denied;
+			return json(writeSecuritySettings(deps.stateDir, { mutationApproval: body.mutationApproval as MutationApproval }));
 		}
 
 		if (path === "/search" && req.method === "GET") {
@@ -100,17 +122,21 @@ export function createApp(deps: Deps): { fetch: (req: Request) => Promise<Respon
 
 		if (path === "/remove" && req.method === "POST") {
 			let name = "";
+			let approved = false;
 			try {
-				const body = (await req.json()) as { name?: unknown };
+				const body = (await req.json()) as { name?: unknown; approved?: unknown };
 				name = String(body.name ?? "");
+				approved = body.approved === true;
 			} catch {
 				/* fall through to validation */
 			}
 			if (!NAME_RE.test(name)) {
 				return err(400, "invalid name; want a bare npm package name");
 			}
+			const denied = authorize("remove", approved);
+			if (denied) return denied;
 			try {
-				const output = await deps.inst.remove(`npm:${name}`);
+				const output = await deps.inst.remove(`npm:${name}`, { approved });
 				return json({ ok: true, name, output });
 			} catch (e) {
 				return json({ ok: false, name, output: e instanceof Error ? e.message : String(e) });
@@ -119,17 +145,21 @@ export function createApp(deps: Deps): { fetch: (req: Request) => Promise<Respon
 
 		if (path === "/install" && req.method === "POST") {
 			let source = "";
+			let approved = false;
 			try {
-				const body = (await req.json()) as { source?: unknown };
+				const body = (await req.json()) as { source?: unknown; approved?: unknown };
 				source = String(body.source ?? "");
+				approved = body.approved === true;
 			} catch {
 				/* fall through to validation */
 			}
 			if (!SOURCE_RE.test(source)) {
 				return err(400, "invalid source; want npm:<pkg>[@ver], git:<host>/<owner>/<repo>[@ref], or https://…");
 			}
+			const denied = authorize("install", approved);
+			if (denied) return denied;
 			try {
-				const output = await deps.inst.install(source);
+				const output = await deps.inst.install(source, { approved });
 				return json({ ok: true, source, output });
 			} catch (e) {
 				return json({ ok: false, source, output: e instanceof Error ? e.message : String(e) });

package/src/version.ts

@@ -0,0 +1,16 @@
+import { readFileSync } from "node:fs";
+
+function packageVersion(): string {
+	const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as unknown;
+	if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) {
+		throw new Error("pi-packed package manifest must be an object");
+	}
+	const version = (manifest as Record<string, unknown>)["version"];
+	if (typeof version !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+		throw new Error("pi-packed package manifest has an invalid version");
+	}
+	return version;
+}
+
+/** Runtime package version; package.json is the single release source of truth. */
+export const VERSION = packageVersion();