dsh-permission-rules 0.5.6 → 0.6.0

package/lib/index.js

@@ -1,9 +1,11 @@
 import { createRequire } from "node:module";
+import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import chokidar from "chokidar";
 import z from "@deepseek-ai/schemastery";
 import { parse } from "yaml";
+import { fileURLToPath } from "node:url";
 import { createServer, request } from "node:http";
 import { request as request$1 } from "node:https";
 import { connect } from "node:net";
@@ -291,6 +293,154 @@ function literalPrefixOf(x, y) {
 	return x.slice(0, min) === y.slice(0, min);
 }
 //#endregion
+//#region src/shell.ts
+/**
+* Decompose one shell command line into its simple commands and, within
+* each, its command word, argument tokens, and redirect targets. Empty
+* input yields an empty decomposition.
+* @param text - the raw command line.
+* @returns the decomposition.
+*/
+function decomposeShellCommand(text) {
+	const commands = [];
+	let words = [];
+	let buffer = "";
+	let started = false;
+	let redirect = false;
+	const flush = () => {
+		if (!started) return;
+		words.push({
+			text: buffer,
+			redirect
+		});
+		buffer = "";
+		started = false;
+		redirect = false;
+	};
+	const endCommand = () => {
+		flush();
+		if (words.length === 0) return;
+		const commandIndex = words.findIndex((word) => !word.redirect);
+		const command = commandIndex < 0 ? "" : words[commandIndex]?.text ?? "";
+		const args = [];
+		const redirects = [];
+		words.forEach((word, index) => {
+			if (index === commandIndex) return;
+			if (word.redirect) redirects.push(word.text);
+			else args.push(word.text);
+		});
+		commands.push({
+			command,
+			args,
+			redirects
+		});
+		words = [];
+	};
+	const endWordBeforeRedirect = () => {
+		if (started && /^\d+$/.test(buffer)) {
+			buffer = "";
+			started = false;
+			return;
+		}
+		flush();
+	};
+	let i = 0;
+	while (i < text.length) {
+		const ch = text[i];
+		if (ch === "\\") {
+			const next = text[i + 1];
+			buffer += next ?? "\\";
+			started = true;
+			i += 2;
+			continue;
+		}
+		if (ch === "'") {
+			started = true;
+			i += 1;
+			while (i < text.length && text[i] !== "'") {
+				buffer += text[i];
+				i += 1;
+			}
+			i += 1;
+			continue;
+		}
+		if (ch === "\"") {
+			started = true;
+			i += 1;
+			while (i < text.length && text[i] !== "\"") {
+				const next = text[i + 1];
+				if (text[i] === "\\" && (next === "\"" || next === "\\" || next === "$" || next === "`")) {
+					buffer += next;
+					i += 2;
+				} else {
+					buffer += text[i];
+					i += 1;
+				}
+			}
+			i += 1;
+			continue;
+		}
+		if (ch === "\n") {
+			flush();
+			endCommand();
+			i += 1;
+			continue;
+		}
+		if (ch === " " || ch === "	") {
+			flush();
+			i += 1;
+			continue;
+		}
+		if (ch === "|") {
+			flush();
+			i += text[i + 1] === "|" ? 2 : 1;
+			endCommand();
+			continue;
+		}
+		if (ch === ";") {
+			flush();
+			endCommand();
+			i += 1;
+			continue;
+		}
+		if (ch === "&") {
+			flush();
+			const next = text[i + 1];
+			if (next === "&") {
+				i += 2;
+				endCommand();
+				continue;
+			}
+			if (next === ">") {
+				i += text[i + 2] === ">" ? 3 : 2;
+				redirect = true;
+				continue;
+			}
+			i += 1;
+			endCommand();
+			continue;
+		}
+		if (ch === ">") {
+			endWordBeforeRedirect();
+			i += text[i + 1] === ">" ? 2 : 1;
+			redirect = true;
+			continue;
+		}
+		if (ch === "<") {
+			endWordBeforeRedirect();
+			if (text[i + 1] === "<") i += text[i + 2] === "<" ? 3 : 2;
+			else i += 1;
+			redirect = true;
+			continue;
+		}
+		buffer += ch;
+		started = true;
+		i += 1;
+	}
+	endCommand();
+	return { commands };
+}
+//#endregion
 //#region src/rules.ts
 /**
 * The pure rule vocabulary: parsing a `.dsh/rules.yaml` document into a
@@ -386,8 +536,41 @@ function parseRulesDocument(text) {
 */
 function compileRules(doc, options) {
 	if (doc.rules.length > options.maxRules) throw new RuleError(`rule count ${doc.rules.length} exceeds maxRules ${options.maxRules}`);
+	return mergeCompiledRules([compileSourceRules(doc, options)], options);
+}
+/**
+* Compile one parsed document into per-source compiled rules. The returned
+* rules carry source-local `index` values and `sourceIndex` 0 — the
+* cacheable unit a runtime can reuse across chains (keyed by source path +
+* content hash). The total-count cap is NOT applied here; it bounds the
+* merged chain in {@link mergeCompiledRules}.
+* @param doc - the parsed document.
+* @param options - compile options.
+* @returns the compiled rules of one source.
+*/
+function compileSourceRules(doc, options) {
+	return doc.rules.map((entry, index) => compileRule(entry, index, 0, options));
+}
+/**
+* Merge per-source compiled rule lists into one chain, assigning the
+* global 0-based `index` and per-list `sourceIndex` attribution. The TOTAL
+* rule count is capped by `maxRules`.
+* @param sources - one compiled rule list per source file, nearest first.
+* @param options - compile options (the cap).
+* @returns the merged ruleset.
+*/
+function mergeCompiledRules(sources, options) {
+	const merged = [];
+	sources.forEach((list, sourceIndex) => {
+		for (const rule of list) merged.push({
+			...rule,
+			index: merged.length,
+			sourceIndex
+		});
+	});
+	if (merged.length > options.maxRules) throw new RuleError(`rule count ${merged.length} exceeds maxRules ${options.maxRules}`);
 	return {
-		rules: doc.rules.map((entry, index) => compileRule(entry, index, 0, options)),
+		rules: merged,
 		caseInsensitivePaths: options.caseInsensitivePaths
 	};
 }
@@ -403,17 +586,8 @@ function compileRules(doc, options) {
 */
 function compileRulesChain(entries, options) {
 	const sources = entries.map((entry) => entry.path);
-	const merged = [];
-	for (const entry of entries) {
-		const doc = parseRulesDocument(entry.text);
-		for (const rule of doc.rules) merged.push(compileRule(rule, merged.length, sources.indexOf(entry.path), options));
-	}
-	if (merged.length > options.maxRules) throw new RuleError(`rule count ${merged.length} exceeds maxRules ${options.maxRules}`);
 	return {
-		ruleset: {
-			rules: merged,
-			caseInsensitivePaths: options.caseInsensitivePaths
-		},
+		ruleset: mergeCompiledRules(entries.map((entry) => compileSourceRules(parseRulesDocument(entry.text), options)), options),
 		sources
 	};
 }
@@ -426,6 +600,7 @@ function compileRule(entry, index, sourceIndex, options) {
 	const paths = entry.match.paths.map((pattern) => compilePathPattern(pattern, options));
 	const env = /* @__PURE__ */ new Map();
 	for (const [key, patterns] of Object.entries(entry.match.when.env)) env.set(key, patterns.map((pattern) => compileValuePattern(pattern, options.patternMode, options.maxGlobStars)));
+	const argv = entry.match.argv === void 0 ? void 0 : compileArgv(entry.match.argv, options);
 	return {
 		index,
 		sourceIndex,
@@ -443,10 +618,20 @@ function compileRule(entry, index, sourceIndex, options) {
 			env,
 			platform: entry.match.when.platform
 		} },
+		...argv === void 0 ? {} : { argv },
 		...entry.match.network === void 0 ? {} : { network: compileNetwork(entry.match.network, options.maxGlobStars) },
 		source: entry
 	};
 }
+/** Compile the `argv` block of one rule; pattern errors throw at load. */
+function compileArgv(doc, options) {
+	return {
+		command: doc.command.map((pattern) => compileToolPattern(pattern, options.maxGlobStars)),
+		args: compileParamPatterns("argv.args", doc.args, options),
+		anyArg: compileParamPatterns("argv.anyArg", doc.anyArg, options),
+		pipeline: doc.pipeline.map((pattern) => compileToolPattern(pattern, options.maxGlobStars))
+	};
+}
 /**
 * Evaluate rules in order against one pending tool call. First match wins;
 * no match returns `undefined` (passthrough). Pure and synchronous — this
@@ -468,6 +653,7 @@ function matchRules(ruleset, toolName, args, cwd, context = {}) {
 		if (!matchWhen(rule, context)) continue;
 		if (rule.params.size > 0 && (argRecord === void 0 || !matchParams(rule, argRecord))) continue;
 		if (rule.absent.length > 0 && !matchAbsent(rule, argRecord)) continue;
+		if (rule.argv !== void 0 && (argRecord === void 0 || !matchArgv(rule, argRecord))) continue;
 		if (rule.paths.length > 0 && (argRecord === void 0 || !matchPaths(rule, argRecord, cwd, ruleset.caseInsensitivePaths))) continue;
 		if (rule.network !== void 0 && (argRecord === void 0 || !matchNetwork(rule, argRecord))) continue;
 		return {
@@ -499,7 +685,7 @@ function findUnreachableRules(ruleset) {
 }
 /** Whether every match dimension of one rule is empty. */
 function isCatchAll(rule) {
-	return rule.tools.length === 0 && rule.agents.length === 0 && rule.params.size === 0 && rule.paths.length === 0 && rule.absent.length === 0 && rule.when === void 0 && rule.network === void 0;
+	return rule.tools.length === 0 && rule.agents.length === 0 && rule.params.size === 0 && rule.paths.length === 0 && rule.absent.length === 0 && rule.when === void 0 && rule.argv === void 0 && rule.network === void 0;
 }
 /**
 * One-line human summary of a compiled rule, for `/rules` output. The
@@ -521,6 +707,15 @@ function describeRule(rule, tokens, source) {
 	if (params.length > 0) parts.push(`${tokens.params}:${params}`);
 	if (rule.source.match.paths.length > 0) parts.push(`${tokens.paths}:${rule.source.match.paths.join(",")}`);
 	if (rule.source.match.absent.length > 0) parts.push(`${tokens.absent}:${rule.source.match.absent.join(",")}`);
+	const argvDoc = rule.source.match.argv;
+	if (argvDoc !== void 0) {
+		const argvParts = [];
+		if (argvDoc.command.length > 0) argvParts.push(`command=${argvDoc.command.join(",")}`);
+		if (argvDoc.args.length > 0) argvParts.push(`args=${argvDoc.args.join(",")}`);
+		if (argvDoc.anyArg.length > 0) argvParts.push(`anyArg=${argvDoc.anyArg.join(",")}`);
+		if (argvDoc.pipeline.length > 0) argvParts.push(`pipeline=${argvDoc.pipeline.join(",")}`);
+		parts.push(`${tokens.argv}:${argvParts.join(" ")}`);
+	}
 	const whenParts = Object.entries(rule.source.match.when.env).map(([key, patterns]) => `${key}=${patterns.join("|")}`).join(" ");
 	const platformPart = rule.source.match.when.platform.length > 0 ? `${tokens.platform}:${rule.source.match.when.platform.join(",")}` : "";
 	if (whenParts.length > 0 || platformPart.length > 0) parts.push(`${tokens.when}:${whenParts}${whenParts.length > 0 && platformPart.length > 0 ? " " : ""}${platformPart}`);
@@ -577,6 +772,50 @@ function matchAbsent(rule, argRecord) {
 	for (const key of rule.absent) if (argRecord !== void 0 && argRecord[key] !== void 0) return false;
 	return true;
 }
+/**
+* Whether a rule's `argv` dimension holds: at least one command-string
+* argument must decompose into simple commands satisfying EVERY listed
+* field. `command` matches any simple-command word; `pipeline` matches the
+* command words joined by `|` (e.g. `curl|sh`); `args` requires every
+* positive pattern to match some token and no negative to match any;
+* `anyArg` requires some token to match a positive pattern (when one is
+* listed) and no negative to match any. Argument tokens include redirect
+* targets, so `> /etc/passwd` feeds the same token set as an argument.
+*/
+function matchArgv(rule, args) {
+	const argv = rule.argv;
+	if (argv === void 0) return true;
+	const commands = extractCommandCandidates(args).flatMap((text) => decomposeShellCommand(text).commands);
+	if (commands.length === 0) return false;
+	if (argv.command.length > 0 && !commands.some((command) => argv.command.some((regex) => regex.test(command.command)))) return false;
+	if (argv.pipeline.length > 0 && !argv.pipeline.some((regex) => regex.test(commands.map((command) => command.command).join("|")))) return false;
+	const tokens = commands.flatMap((command) => [...command.args, ...command.redirects]);
+	if (argv.args.positive.length > 0) {
+		for (const pattern of argv.args.positive) if (!tokens.some((token) => pattern.test(token))) return false;
+	}
+	if (argv.args.negative.length > 0 && tokens.some((token) => argv.args.negative.some((regex) => regex.test(token)))) return false;
+	if (argv.anyArg.positive.length > 0 && !tokens.some((token) => argv.anyArg.positive.some((regex) => regex.test(token)))) return false;
+	if (argv.anyArg.negative.length > 0 && tokens.some((token) => argv.anyArg.negative.some((regex) => regex.test(token)))) return false;
+	return true;
+}
+/** Collect command-string candidates from tool arguments (the documented command keys, any depth). */
+function extractCommandCandidates(args) {
+	const candidates = [];
+	const walk = (node, depth) => {
+		if (depth > MAX_ARGUMENT_DEPTH) return;
+		if (Array.isArray(node)) {
+			for (const element of node) walk(element, depth + 1);
+			return;
+		}
+		if (typeof node !== "object" || node === null) return;
+		for (const [key, value] of Object.entries(node)) {
+			if (COMMAND_CANDIDATE_KEYS.includes(key) && typeof value === "string") candidates.push(value);
+			walk(value, depth + 1);
+		}
+	};
+	walk(args, 0);
+	return candidates;
+}
 /** Whether a rule's when dimension holds for the host facts. */
 function matchWhen(rule, context) {
 	const when = rule.when;
@@ -681,8 +920,8 @@ function parseMatch(raw, at) {
 		}
 	};
 	const record = asRecord(raw, `${at}.match`);
-	const unknownFields = Object.keys(record).filter((key) => key !== "tools" && key !== "agents" && key !== "params" && key !== "paths" && key !== "absent" && key !== "when" && key !== "network");
-	if (unknownFields.length > 0) throw new RuleError(`${at}.match: unknown field${unknownFields.length > 1 ? "s" : ""} ${unknownFields.map((k) => JSON.stringify(k)).join(", ")} (allowed: tools, agents, params, paths, absent, when, network)`);
+	const unknownFields = Object.keys(record).filter((key) => key !== "tools" && key !== "agents" && key !== "params" && key !== "paths" && key !== "absent" && key !== "when" && key !== "argv" && key !== "network");
+	if (unknownFields.length > 0) throw new RuleError(`${at}.match: unknown field${unknownFields.length > 1 ? "s" : ""} ${unknownFields.map((k) => JSON.stringify(k)).join(", ")} (allowed: tools, agents, params, paths, absent, when, argv, network)`);
 	return {
 		tools: parseStringList(record["tools"], `${at}.match.tools`),
 		agents: parseStringList(record["agents"], `${at}.match.agents`),
@@ -690,9 +929,31 @@ function parseMatch(raw, at) {
 		paths: parseStringList(record["paths"], `${at}.match.paths`),
 		absent: parseStringList(record["absent"], `${at}.match.absent`),
 		when: parseWhen(record["when"], `${at}.match.when`),
+		...record["argv"] === void 0 ? {} : { argv: parseArgv(record["argv"], `${at}.match.argv`) },
 		...record["network"] === void 0 ? {} : { network: parseNetwork(record["network"], `${at}.match.network`) }
 	};
 }
+/**
+* Validate the `argv` block of one rule: closed field vocabulary plus the
+* same pattern-shape rules as every other pattern list. A block with every
+* field empty is rejected — an `argv` rule must name at least one field.
+*/
+function parseArgv(raw, at) {
+	const record = asRecord(raw, at);
+	const unknownFields = Object.keys(record).filter((key) => key !== "command" && key !== "args" && key !== "anyArg" && key !== "pipeline");
+	if (unknownFields.length > 0) throw new RuleError(`${at}: unknown field${unknownFields.length > 1 ? "s" : ""} ${unknownFields.map((k) => JSON.stringify(k)).join(", ")} (allowed: command, args, anyArg, pipeline)`);
+	const command = parseStringList(record["command"], `${at}.command`);
+	const args = parsePatternValues(record["args"], `${at}.args`);
+	const anyArg = parsePatternValues(record["anyArg"], `${at}.anyArg`);
+	const pipeline = parseStringList(record["pipeline"], `${at}.pipeline`);
+	if (command.length === 0 && args.length === 0 && anyArg.length === 0 && pipeline.length === 0) throw new RuleError(`${at}: an argv block must name at least one of command, args, anyArg, pipeline (drop the block for a tool-level rule)`);
+	return {
+		command,
+		args,
+		anyArg,
+		pipeline
+	};
+}
 /** Validate the params map: non-empty string keys → one pattern or a pattern list. */
 function parseParams(raw, at) {
 	if (raw === void 0) return {};
@@ -1281,6 +1542,36 @@ function blockMessage(decision) {
 	}
 }
 //#endregion
+//#region src/builtin-rules.ts
+/**
+* The shipped high-risk permission baseline: the absolute path of the
+* bundled `rules/builtin-high-risk.yaml` data file and the resolution of a
+* possibly-custom builtin path. The shipped path is computed relative to
+* THIS module so it resolves identically from the source plane (tests,
+* where this file lives under `src/`) and the bundled plane (where it is
+* inlined into `lib/index.js`, one directory below the package root).
+* @module dsh-permission-rules/builtin-rules
+*/
+/** File name of the bundled baseline, under the package's `rules/` directory. */
+const BUILTIN_RULES_FILE = "builtin-high-risk.yaml";
+/**
+* Absolute path of the shipped baseline. Not existence-checked here — a
+* missing file is a mount-time failure in {@link PermissionRulesRuntime},
+* never a silent skip.
+*/
+const SHIPPED_BUILTIN_RULES = resolve(dirname(fileURLToPath(import.meta.url)), "..", "rules", BUILTIN_RULES_FILE);
+/**
+* Resolve the builtin ruleset path: an explicit `builtin.path` (absolute
+* as-is, relative against `process.cwd()` — mirroring `fallbackPath`), else
+* the shipped file.
+* @param custom - the optional `builtin.path` config value.
+* @returns the absolute builtin ruleset path.
+*/
+function resolveBuiltinRulesPath(custom) {
+	if (custom === void 0) return SHIPPED_BUILTIN_RULES;
+	return isAbsolute(custom) ? custom : resolve(custom);
+}
+//#endregion
 //#region src/config.ts
 /**
 * Config schema and resolution for `dsh-permission-rules`. Every tunable is
@@ -1323,6 +1614,10 @@ const Config = z.object({
 		loopback: z.union(["allow", "policy"]).default("allow"),
 		injectEnv: z.boolean().default(true),
 		noProxy: z.union(["clear", "preserve"]).default("clear")
+	}),
+	builtin: z.object({
+		enabled: z.boolean().default(true),
+		path: z.string()
 	})
 });
 /**
@@ -1363,6 +1658,7 @@ function resolveConfig(config = {}) {
 	assertBoolean("enforce", config.enforce ?? true);
 	assertBoolean("allowUnmarkedAudit", config.allowUnmarkedAudit ?? false);
 	const network = resolveNetworkConfig(config.network);
+	const builtin = resolveBuiltinConfig(config.builtin);
 	return {
 		rulesFile,
 		fallbackPath: config.fallbackPath,
@@ -1379,7 +1675,17 @@ function resolveConfig(config = {}) {
 		maxGlobStars,
 		enforce: config.enforce ?? true,
 		allowUnmarkedAudit: config.allowUnmarkedAudit ?? false,
-		network
+		network,
+		builtin
+	};
+}
+/** Validate and default the optional `builtin` block; bad values fail the mount loudly. */
+function resolveBuiltinConfig(raw) {
+	assertBoolean("builtin.enabled", raw?.enabled ?? true);
+	const path = resolveBuiltinRulesPath(raw?.path);
+	return {
+		enabled: raw?.enabled ?? true,
+		path
 	};
 }
 /** Validate and default the optional `network` block; bad values fail the mount loudly. */
@@ -1618,6 +1924,7 @@ const DESCRIBE_TOKENS = {
 		absent: "absent",
 		when: "when",
 		platform: "platform",
+		argv: "argv",
 		network: "network",
 		domains: "domains",
 		ips: "ips",
@@ -1636,6 +1943,7 @@ const DESCRIBE_TOKENS = {
 		absent: "缺省键",
 		when: "条件",
 		platform: "平台",
+		argv: "命令",
 		network: "网络",
 		domains: "域名",
 		ips: "IP",
@@ -1654,6 +1962,7 @@ const DESCRIBE_TOKENS = {
 		absent: "ausentes",
 		when: "cuándo",
 		platform: "plataforma",
+		argv: "comando",
 		network: "red",
 		domains: "dominios",
 		ips: "IP",
@@ -1672,6 +1981,7 @@ const DESCRIBE_TOKENS = {
 		absent: "ausentes",
 		when: "quando",
 		platform: "plataforma",
+		argv: "comando",
 		network: "rede",
 		domains: "domínios",
 		ips: "IP",
@@ -1690,6 +2000,7 @@ const DESCRIBE_TOKENS = {
 		absent: "अनुपस्थित",
 		when: "शर्त",
 		platform: "प्लेटफ़ॉर्म",
+		argv: "कमांड",
 		network: "नेटवर्क",
 		domains: "डोमेन",
 		ips: "IP",
@@ -2133,6 +2444,8 @@ var PermissionRulesRuntime = class {
 	ctx;
 	/** Loaded (or failed) rules per workspace cwd, least-recently-used first for eviction. */
 	byCwd = /* @__PURE__ */ new Map();
+	/** Compiled per-source rules keyed by absolute path, with the content hash they were compiled from (LRU-refreshed). */
+	compileCache = /* @__PURE__ */ new Map();
 	/** Live watchers per watched path (rule file or candidate ancestor directory), with the cwds each serves. */
 	watchers = /* @__PURE__ */ new Map();
 	/** Debounce timers per rule-file path. */
@@ -2170,15 +2483,28 @@ var PermissionRulesRuntime = class {
 		};
 	}
 	/**
-	* Resolve which files serve a workspace, nearest first: the project file
-	* under the session cwd (or an absolute `rulesFile`), with `searchUp`
-	* also merging every parent directory's file on the way to the root,
-	* else the configured fallback, else `[]` (empty rule set). Nearer files
-	* evaluate first, so a child can override a parent rule.
+	* Resolve which files serve a workspace, nearest first: the USER rule
+	* files (project file under the session cwd — or an absolute `rulesFile`
+	* — with `searchUp` also merging every parent directory's file on the
+	* way to the root, else the configured fallback, else `[]`), followed by
+	* the built-in high-risk baseline when enabled. The baseline sits LAST so
+	* first-match semantics let any nearer user rule override it; with no
+	* user files it applies alone. Nearer files evaluate first, so a child
+	* can override a parent rule.
 	* @param cwd - the session's absolute workspace root.
 	* @returns the absolute rule-file paths in effect, nearest first.
 	*/
 	resolveSources(cwd) {
+		const user = this.resolveUserSources(cwd);
+		const builtin = this.builtinSource();
+		return builtin === void 0 ? user : [...user, builtin];
+	}
+	/** The built-in baseline path when enabled, else `undefined`. */
+	builtinSource() {
+		return this.config.builtin.enabled ? this.config.builtin.path : void 0;
+	}
+	/** The user rule files serving a workspace (project chain → fallback → empty), nearest first. */
+	resolveUserSources(cwd) {
 		if (this.config.searchUp) {
 			const sources = [];
 			let dir = cwd;
@@ -2223,14 +2549,10 @@ var PermissionRulesRuntime = class {
 			}
 		};
 		try {
-			const { ruleset } = compileRulesChain(sources.map((path) => ({
-				path,
-				text: readFileSync(path, "utf8")
-			})), this.compileOptions());
 			return {
 				cwd,
 				sources,
-				compiled: ruleset
+				compiled: mergeCompiledRules(sources.map((path) => this.compileSourceFile(path)), this.compileOptions())
 			};
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
@@ -2250,6 +2572,41 @@ var PermissionRulesRuntime = class {
 		}
 	}
 	/**
+	* Compile one source file, reusing the cached compiled rules when the
+	* file's content hash is unchanged. The cache key is the source path plus
+	* the content hash, so the same file read by many workspaces (the
+	* built-in baseline and any shared fallback/absolute `rulesFile`) is
+	* parsed and compiled ONCE, not once per cwd.
+	* @param path - the absolute source path.
+	* @returns that source's compiled rules (source-local index, sourceIndex 0).
+	*/
+	compileSourceFile(path) {
+		const text = readFileSync(path, "utf8");
+		const hash = createHash("sha256").update(text).digest("hex");
+		const cached = this.compileCache.get(path);
+		if (cached !== void 0 && cached.hash === hash) {
+			this.compileCache.delete(path);
+			this.compileCache.set(path, cached);
+			return cached.rules;
+		}
+		const rules = compileSourceRules(parseRulesDocument(text), this.compileOptions());
+		this.compileCache.set(path, {
+			hash,
+			rules
+		});
+		this.evictCompileCache();
+		return rules;
+	}
+	/** Bound the compile cache: drop the least-recently-used source beyond the workspace cap (compile results are cheap to rebuild). */
+	evictCompileCache() {
+		const cap = this.config.maxCachedWorkspaces;
+		while (this.compileCache.size > cap) {
+			const oldest = this.compileCache.keys().next().value;
+			if (oldest === void 0) return;
+			this.compileCache.delete(oldest);
+		}
+	}
+	/**
 	* Canonical per-workspace cache key: the resolved root, case-folded on
 	* Windows so differently-spelled paths to the same workspace share one
 	* cache entry and one watcher set instead of doubling both.
@@ -2695,13 +3052,19 @@ var PermissionRulesRuntime = class {
 	* The rule-file paths the settings-page editor may read or write: every
 	* currently loaded source plus the per-workspace project files and the
 	* configured fallback (so a not-yet-existing project file can be
-	* created). The editor never touches arbitrary paths.
+	* created). The editor never touches arbitrary paths — and the built-in
+	* baseline is excluded entirely (it is a shipped, read-only baseline,
+	* shown via `/rules` attribution instead).
 	*/
 	knownRuleSources() {
 		const cfg = this.config;
+		const builtin = cfg.builtin.enabled ? cfg.builtin.path : void 0;
 		const set = /* @__PURE__ */ new Set();
 		for (const loaded of this.byCwd.values()) {
-			for (const source of loaded.sources) set.add(source);
+			for (const source of loaded.sources) {
+				if (source === builtin) continue;
+				set.add(source);
+			}
 			if (!isAbsolute(cfg.rulesFile)) set.add(join(loaded.cwd, cfg.rulesFile));
 		}
 		if (cfg.fallbackPath !== void 0) set.add(isAbsolute(cfg.fallbackPath) ? cfg.fallbackPath : resolve(cfg.fallbackPath));
@@ -2752,6 +3115,10 @@ var PermissionRulesRuntime = class {
 	* is in effect immediately.
 	*/
 	saveRuleFile(path, text) {
+		if (this.config.builtin.enabled && path === this.config.builtin.path) return {
+			ok: false,
+			error: `refusing to write ${path}: the built-in ruleset is read-only`
+		};
 		if (!this.knownRuleSources().includes(path)) return {
 			ok: false,
 			error: `refusing to write ${path}: not a known rule source`
@@ -3038,6 +3405,10 @@ var PermissionRulesRuntime = class {
 			if (!existsSync(fallbackPath)) throw new RuleError(`permission-rules: fallbackPath ${JSON.stringify(this.config.fallbackPath)} does not exist`);
 			this.loadForValidation(fallbackPath);
 		}
+		if (this.config.builtin.enabled) {
+			if (!existsSync(this.config.builtin.path)) throw new RuleError(`permission-rules: builtin ruleset ${JSON.stringify(this.config.builtin.path)} does not exist`);
+			this.loadForValidation(this.config.builtin.path);
+		}
 	}
 	/** Parse and compile one mandated file, rethrowing as a mount failure. */
 	loadForValidation(filePath) {
@@ -3050,7 +3421,7 @@ var PermissionRulesRuntime = class {
 	}
 	/** Attach (once per file path) the Chokidar watcher feeding {@link reload}. */
 	attachWatch(cwd, source) {
-		if (!this.config.watch || source === "") return;
+		if (!this.config.watch || source === "" || this.config.builtin.enabled && source === this.config.builtin.path) return;
 		const existing = this.watchers.get(source);
 		if (existing !== void 0) {
 			existing.cwds.add(cwd);
@@ -3217,6 +3588,10 @@ var PermissionRulesRuntime = class {
 	activeWatcherCount() {
 		return this.watchers.size;
 	}
+	/** Number of cached compiled source files, for observability and tests. */
+	compiledSourceCount() {
+		return this.compileCache.size;
+	}
 	/** Number of pending debounce timers, for observability and tests. */
 	pendingReloadCount() {
 		return this.timers.size;
@@ -3374,4 +3749,4 @@ function nextToken(text) {
 const name = "permission-rules";
 const inject = ["commands", "tools"];
 //#endregion
-export { Config, GlobError, NETWORK_MODES, NO_PROXY_ENV_NAMES, NetworkProxy, PATH_CANDIDATE_KEYS, PLATFORMS, PROXY_ENV_NAMES, PermissionRulesRuntime, RULE_ACTIONS, RuleError, SCHEMES, URL_CANDIDATE_KEYS, apply, blockMessage, compileGlob, compilePatternRegex, compileRules, compileRulesChain, decideNetworkTarget, defaultDecision, describeRule, extractPathCandidates, extractUrlCandidates, findUnreachableRules, inject, injectProxyEnv, isIpLiteral, isLoopbackTarget, isMarkedAuditEvent, isShellTool, isUnmarkedHostVersion, matchRules, matchTools, matchWhen, name, networkModeForSandbox, normalizeWorkspacePath, parseRulesDocument, parseUrlTarget, resolveConfig, targetMatchesNetwork };
+export { BUILTIN_RULES_FILE, Config, GlobError, NETWORK_MODES, NO_PROXY_ENV_NAMES, NetworkProxy, PATH_CANDIDATE_KEYS, PLATFORMS, PROXY_ENV_NAMES, PermissionRulesRuntime, RULE_ACTIONS, RuleError, SCHEMES, SHIPPED_BUILTIN_RULES, URL_CANDIDATE_KEYS, apply, blockMessage, compileGlob, compilePatternRegex, compileRules, compileRulesChain, compileSourceRules, decideNetworkTarget, decomposeShellCommand, defaultDecision, describeRule, extractPathCandidates, extractUrlCandidates, findUnreachableRules, inject, injectProxyEnv, isIpLiteral, isLoopbackTarget, isMarkedAuditEvent, isShellTool, isUnmarkedHostVersion, matchRules, matchTools, matchWhen, mergeCompiledRules, name, networkModeForSandbox, normalizeWorkspacePath, parseRulesDocument, parseUrlTarget, resolveBuiltinRulesPath, resolveConfig, targetMatchesNetwork };

package/lib/types/builtin-rules.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The shipped high-risk permission baseline: the absolute path of the
+ * bundled `rules/builtin-high-risk.yaml` data file and the resolution of a
+ * possibly-custom builtin path. The shipped path is computed relative to
+ * THIS module so it resolves identically from the source plane (tests,
+ * where this file lives under `src/`) and the bundled plane (where it is
+ * inlined into `lib/index.js`, one directory below the package root).
+ * @module dsh-permission-rules/builtin-rules
+ */
+/** File name of the bundled baseline, under the package's `rules/` directory. */
+export declare const BUILTIN_RULES_FILE = "builtin-high-risk.yaml";
+/**
+ * Absolute path of the shipped baseline. Not existence-checked here — a
+ * missing file is a mount-time failure in {@link PermissionRulesRuntime},
+ * never a silent skip.
+ */
+export declare const SHIPPED_BUILTIN_RULES: string;
+/**
+ * Resolve the builtin ruleset path: an explicit `builtin.path` (absolute
+ * as-is, relative against `process.cwd()` — mirroring `fallbackPath`), else
+ * the shipped file.
+ * @param custom - the optional `builtin.path` config value.
+ * @returns the absolute builtin ruleset path.
+ */
+export declare function resolveBuiltinRulesPath(custom: string | undefined): string;
+//# sourceMappingURL=builtin-rules.d.ts.map