prae-cli 0.3.0 → 0.5.0

package/lib/evaluate-BilZez15.js

@@ -0,0 +1,419 @@
+//#region ../kernel/src/command.ts
+/** Wrappers whose first operand is the program actually being run. */
+const WRAPPERS = new Set([
+	"sudo",
+	"command",
+	"env",
+	"nohup",
+	"time",
+	"xargs"
+]);
+/** Wrapper options that consume the next token, so it is not the program. */
+const OPTION_WITH_VALUE = new Set([
+	"-u",
+	"-g",
+	"-p",
+	"-h",
+	"-C",
+	"-r",
+	"-t",
+	"-U",
+	"-I",
+	"-n",
+	"-P",
+	"-L",
+	"-s"
+]);
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+/**
+* Split a line into pipeline segments of words, one scan, quote-aware.
+*
+* Splitting on `|` before parsing quotes is the classic mistake — it turns
+* `echo "a | b"` into two segments — so quoting and separators are read
+* together.
+*/
+function scan(command) {
+	const parts = [];
+	let tokens = [];
+	let current = "";
+	let quote;
+	const endToken = () => {
+		if (current !== "") tokens.push(current);
+		current = "";
+	};
+	const endSegment = () => {
+		endToken();
+		if (tokens.length > 0) parts.push(tokens);
+		tokens = [];
+	};
+	for (let at = 0; at < command.length; at += 1) {
+		const ch = command[at];
+		if (quote !== void 0) {
+			if (ch === quote) quote = void 0;
+			else current += ch;
+			continue;
+		}
+		if (ch === "'" || ch === "\"") {
+			quote = ch;
+			continue;
+		}
+		if (ch === ";") {
+			endSegment();
+			continue;
+		}
+		if (ch === "|" || ch === "&") {
+			endSegment();
+			if (command[at + 1] === ch) at += 1;
+			continue;
+		}
+		if (/\s/.test(ch)) {
+			endToken();
+			continue;
+		}
+		current += ch;
+	}
+	endSegment();
+	return parts;
+}
+/** Decompose a command line into pipeline segments. */
+function segments(command) {
+	const found = [];
+	for (const tokens of scan(command)) {
+		let at = 0;
+		while (at < tokens.length) {
+			const token = tokens[at];
+			if (ASSIGNMENT.test(token)) {
+				at += 1;
+				continue;
+			}
+			if (WRAPPERS.has(token)) {
+				at += 1;
+				while (at < tokens.length) {
+					const option = tokens[at];
+					if (!option.startsWith("-")) break;
+					at += OPTION_WITH_VALUE.has(option) ? 2 : 1;
+				}
+				continue;
+			}
+			break;
+		}
+		const name = tokens[at];
+		if (name === void 0) continue;
+		found.push({
+			name: (name.split("/").pop() ?? name).toLowerCase(),
+			tokens: tokens.slice(at + 1)
+		});
+	}
+	return found;
+}
+/** `git*` matches `git`, `github`; bare strings match exactly. */
+function matches$1(pattern, value) {
+	if (pattern.endsWith("*")) return value.startsWith(pattern.slice(0, -1));
+	return value === pattern;
+}
+const list = (v) => v === void 0 ? [] : typeof v === "string" ? [v] : v;
+/**
+* Judge one command line against one matcher. Every present field must hold.
+*/
+function commandMatches(match, command) {
+	const parts = segments(command);
+	if (parts.length === 0) return false;
+	const names = list(match.name);
+	const args = list(match.token);
+	const pipes = list(match.pipedTo);
+	if (names.length > 0) {
+		const hit = parts.filter((segment) => names.some((pattern) => matches$1(pattern, segment.name)));
+		if (hit.length === 0) return false;
+		if (args.length > 0 && !hit.some((segment) => args.every((wanted) => segment.tokens.some((token) => matches$1(wanted, token))))) return false;
+	} else if (args.length > 0) {
+		if (!parts.some((segment) => args.every((wanted) => segment.tokens.some((token) => matches$1(wanted, token))))) return false;
+	}
+	if (pipes.length > 0) {
+		if (!parts.slice(1).some((segment) => pipes.some((pattern) => matches$1(pattern, segment.name)))) return false;
+	}
+	return true;
+}
+
+//#endregion
+//#region ../kernel/src/path.ts
+/**
+* Path normalization and glob containment, with no filesystem access.
+*
+* The contract, stated here because getting it wrong is how path policies
+* become theatre: **this module compares strings.** It resolves `.` and `..`
+* lexically so that `./src/../../etc/passwd` cannot pose as a workspace path,
+* but it cannot see a symlink. A link inside an allowed directory pointing out
+* of it will pass every check here.
+*
+* That is not a gap to paper over in the matcher — it is a gap the caller
+* closes by resolving before it asks. `dsh-overlay-check` learned this the
+* hard way during the plugin-store gate review: lexical containment accepted a
+* symlink escape cleanly, and the fix was to resolve both the path and its
+* nearest existing ancestor before deciding. Adapters that can touch the
+* filesystem must resolve first and pass the resolved path in.
+*/
+/** Split a path into segments, resolving `.` and `..` lexically. */
+function normalize(path) {
+	const absolute = path.startsWith("/");
+	const out = [];
+	let escaped = false;
+	for (const raw of path.split(/[/\\]+/)) {
+		if (raw === "" || raw === ".") continue;
+		if (raw === "..") {
+			if (out.length > 0) out.pop();
+			else escaped = true;
+			continue;
+		}
+		out.push(raw);
+	}
+	return {
+		segments: out,
+		absolute,
+		escaped
+	};
+}
+/** Turn one glob segment into an anchored regular expression. */
+function segmentPattern(segment) {
+	const body = segment.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*");
+	return /* @__PURE__ */ new RegExp(`^${body}$`);
+}
+/**
+* Wildcard segment matching, where `**` spans zero or more segments.
+*
+* Two-pointer with backtracking rather than a recursive walk: the pattern
+* comes from a policy pack and the path from a tool call, and a catastrophic
+* backtrack in the hot path of every call would be a denial of service handed
+* to whoever writes the pack.
+*/
+function matchSegments(path, pattern) {
+	let i = 0;
+	let j = 0;
+	let starPattern = -1;
+	let starPath = 0;
+	while (i < path.length) {
+		const segment = j < pattern.length ? pattern[j] : void 0;
+		const here = path[i];
+		if (segment === "**") {
+			starPattern = j;
+			starPath = i;
+			j += 1;
+			continue;
+		}
+		if (segment !== void 0 && here !== void 0 && segmentPattern(segment).test(here)) {
+			i += 1;
+			j += 1;
+			continue;
+		}
+		if (starPattern >= 0) {
+			starPath += 1;
+			i = starPath;
+			j = starPattern + 1;
+			continue;
+		}
+		return false;
+	}
+	while (j < pattern.length && pattern[j] === "**") j += 1;
+	return j === pattern.length;
+}
+/**
+* Is `path` contained by `glob`?
+*
+* A glob naming a directory contains everything under it: `./src` and
+* `./src/**` both match `src/app/main.ts`. Writing the shorter form is the
+* common intent, and treating it as "this exact directory entry only" is a
+* trap that silently grants the whole subtree past the rule.
+*/
+function within(path, glob) {
+	const target = normalize(path);
+	if (target.escaped) return false;
+	const trimmed = glob.trim();
+	if (!(trimmed === "**" || trimmed.startsWith("**/")) && target.absolute !== trimmed.startsWith("/")) return false;
+	const pattern = normalize(glob);
+	if (matchSegments(target.segments, pattern.segments)) return true;
+	return matchSegments(target.segments, [...pattern.segments, "**"]);
+}
+/** Is `path` inside any of these globs? */
+function withinAny(path, globs) {
+	return globs.some((glob) => within(path, glob));
+}
+/**
+* The host of a URL, or undefined when it is not a URL we can read.
+*
+* Unparseable input returns undefined, and callers treat that as "no host" —
+* which for a `notIn` rule means the rule matches. Failing toward the rule is
+* the only safe direction: a string we cannot parse is exactly the shape an
+* evasion attempt takes.
+*/
+function hostOf(url) {
+	try {
+		return new URL(url).hostname.toLowerCase();
+	} catch {
+		return;
+	}
+}
+/**
+* Host list membership, where a leading dot means "this domain or below".
+*
+* `example.com` matches only that host. `.example.com` also matches
+* `api.example.com`, and deliberately still matches `example.com` itself —
+* an operator writing the suffix form means the organisation, not a rule that
+* covers every subdomain except the one they first thought of.
+*/
+function hostIn(host, list$1) {
+	return list$1.some((entry) => {
+		const want = entry.toLowerCase();
+		if (want.startsWith(".")) return host === want.slice(1) || host.endsWith(want);
+		return host === want;
+	});
+}
+
+//#endregion
+//#region ../kernel/src/rule.ts
+/**
+* Strength ordering, used when several rules match one call.
+*
+* Higher wins. This is the property that makes a pack safe to extend: adding a
+* rule can raise the strength of a decision and never lower it, so an operator
+* appending to a pack can never accidentally widen what an agent may do.
+*/
+const STRENGTH = {
+	warn: 1,
+	correct: 2,
+	ask: 3,
+	deny: 4
+};
+
+//#endregion
+//#region ../kernel/src/evaluate.ts
+function listed(value, want) {
+	if (want === void 0) return true;
+	if (value === void 0) return false;
+	return typeof want === "string" ? value === want : want.includes(value);
+}
+function argMatches(match, args) {
+	const has = Object.hasOwn(args, match.name);
+	if (match.present !== void 0 && match.present !== has) return false;
+	if (!has) return match.above === void 0 && match.below === void 0 && match.equals === void 0 && match.oneOf === void 0;
+	const value = args[match.name];
+	if (match.above !== void 0) {
+		if (typeof value !== "number" || !(value > match.above)) return false;
+	}
+	if (match.below !== void 0) {
+		if (typeof value !== "number" || !(value < match.below)) return false;
+	}
+	if (match.equals !== void 0 && value !== match.equals) return false;
+	if (match.oneOf !== void 0) {
+		if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") return false;
+		if (!match.oneOf.includes(value)) return false;
+	}
+	return true;
+}
+function matches(when, facts) {
+	if (!listed(facts.tool, when.tool)) return false;
+	if (!listed(facts.capability, when.capability)) return false;
+	if (!listed(facts.plugin, when.plugin)) return false;
+	if (!listed(facts.agent, when.agent)) return false;
+	if (when.command !== void 0) {
+		const raw = facts.args.command ?? facts.args.cmd ?? facts.args.script;
+		if (typeof raw !== "string") return false;
+		if (!commandMatches(when.command, raw)) return false;
+	}
+	if (when.path !== void 0) {
+		const raw = facts.args[when.path.arg ?? "path"];
+		if (typeof raw !== "string") return false;
+		if (when.path.inside !== void 0 && !withinAny(raw, when.path.inside)) return false;
+		if (when.path.outside !== void 0 && withinAny(raw, when.path.outside)) return false;
+	}
+	if (when.host !== void 0) {
+		const raw = facts.args[when.host.arg ?? "url"];
+		if (typeof raw !== "string") return false;
+		const host = hostOf(raw);
+		if (host === void 0) return when.host.notIn !== void 0;
+		if (when.host.in !== void 0 && !hostIn(host, when.host.in)) return false;
+		if (when.host.notIn !== void 0 && hostIn(host, when.host.notIn)) return false;
+	}
+	if (when.arg !== void 0) {
+		for (const one of when.arg) if (!argMatches(one, facts.args)) return false;
+	}
+	if (when.count !== void 0) {
+		const key = facts.capability;
+		if (key === void 0) return false;
+		if (!((facts.counts?.[key] ?? 0) > when.count.above)) return false;
+	}
+	if (when.secrets !== void 0) {
+		const floor = when.secrets.minConfidence ?? 0;
+		const wanted = when.secrets.types;
+		if ((facts.secrets ?? []).filter((finding) => finding.confidence >= floor && (wanted === void 0 || wanted.includes(finding.type))).length < (when.secrets.atLeast ?? 1)) return false;
+	}
+	return true;
+}
+function step(rule, effect) {
+	return {
+		rule: rule.id,
+		...rule.title === void 0 ? {} : { title: rule.title },
+		effect: effect.kind,
+		because: effect.because
+	};
+}
+/**
+* Decide one call against one pack.
+*
+* Every matching rule lands in the trace; the strongest effect decides. Ties
+* go to the first rule in pack order, so a pack reads top-down the way its
+* author wrote it.
+*
+* `correct` is the effect the rest of this ecosystem does not have. A rival
+* guardrail can allow a call or refuse it; a rule here can also rewrite an
+* argument and let it through, recording what it changed. Refusing is not
+* always the safe option — an agent denied mid-task retries, and the retry is
+* rarely safer than the clamp would have been.
+*/
+function evaluate(pack, facts) {
+	const hits = [];
+	for (const rule of pack.rules) if (matches(rule.when, facts)) hits.push({
+		rule,
+		effect: rule.effect
+	});
+	if (hits.length === 0) return {
+		kind: "allow",
+		trace: [],
+		evaluated: pack.rules.length
+	};
+	hits.sort((a, b) => STRENGTH[b.effect.kind] - STRENGTH[a.effect.kind]);
+	const trace = hits.map((hit) => step(hit.rule, hit.effect));
+	const evaluated = pack.rules.length;
+	const strongest = hits[0];
+	if (strongest === void 0) return {
+		kind: "allow",
+		trace: [],
+		evaluated
+	};
+	const winner = strongest.effect.kind;
+	if (winner === "deny" || winner === "ask") return {
+		kind: winner,
+		rule: strongest.rule.id,
+		reason: strongest.effect.because,
+		trace,
+		evaluated
+	};
+	if (winner === "correct") {
+		const args = { ...facts.args };
+		for (const hit of hits) if (hit.effect.kind === "correct") Object.assign(args, hit.effect.set);
+		return {
+			kind: "correct",
+			rule: strongest.rule.id,
+			reason: strongest.effect.because,
+			args,
+			trace,
+			evaluated
+		};
+	}
+	return {
+		kind: "allow",
+		trace,
+		evaluated
+	};
+}
+
+//#endregion
+export { evaluate as t };

package/lib/index.js

@@ -1,5 +1,6 @@
-import { a as planWrite, i as dshHome, n as applyWrite, o as praeRow, r as defaultProfile, s as profileAt, t as main } from "./cli-DZ0FPdSr.js";
-import "./src-DGWTvmRZ.js";
-import "./views-CLLfJPWB.js";
+import "./evaluate-BilZez15.js";
+import { a as planWrite, i as dshHome, n as applyWrite, o as praeRow, r as defaultProfile, s as profileAt, t as main } from "./cli-ZfwhJKRw.js";
+import "./src-CXU0_W1P.js";
+import "./views-DalPkBZZ.js";
 
 export { applyWrite, defaultProfile, dshHome, main, planWrite, praeRow, profileAt };

package/lib/{instructions-C6jwClPO.js → instructions-D4VOn2lk.js}

@@ -1,4 +1,4 @@
-import { c as renderShell, o as esc, s as renderNav, t as navFor } from "./views-CLLfJPWB.js";
+import { c as renderShell, o as esc, s as renderNav, t as navFor } from "./views-DalPkBZZ.js";
 
 //#region src/console/instructions.ts
 const STYLE = `

package/lib/mcp-BH5I4Eyu.js

@@ -0,0 +1,208 @@
+import { t as evaluate } from "./evaluate-BilZez15.js";
+import { a as scan, n as MAX_SCAN_BYTES } from "./src-Br1tGPtS.js";
+import { readFile, readdir, stat } from "node:fs/promises";
+import { resolve, sep } from "node:path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+
+//#region src/mcp.ts
+/** The one denial shape, agent-readable. Mirrors the dsh plugin's. */
+function structuredDeny(kind, resource, types, policy, message) {
+	return JSON.stringify({
+		decision: kind,
+		reason: types.length > 0 ? "secret_detected" : "policy",
+		resource,
+		...types.length > 0 ? { secret_types: [...new Set(types)] } : {},
+		...policy === void 0 ? {} : { policy },
+		retry: false,
+		message
+	});
+}
+/**
+* Judge one read the way the dsh plugin does, minus the harness: confine to
+* the root, inspect the content, evaluate the pack, seal the row.
+*/
+async function judgeRead(options, requested) {
+	const path = resolve(options.root, requested);
+	const rootPrefix = options.root.endsWith(sep) ? options.root : options.root + sep;
+	const at = (/* @__PURE__ */ new Date()).toISOString();
+	const record = (partial) => {
+		options.ledger?.append({
+			at,
+			...options.session === void 0 ? {} : { session: options.session },
+			tool: "read_file",
+			pack: {
+				name: options.pack.pack,
+				version: options.pack.version
+			},
+			...partial
+		});
+	};
+	if (path !== options.root && !path.startsWith(rootPrefix)) {
+		const refusal = structuredDeny("deny", requested, [], "root", `reads are confined to ${options.root}`);
+		record({
+			subject: requested,
+			capability: "fs:read",
+			verdict: "deny",
+			rule: "root",
+			reason: `outside the served root ${options.root}`,
+			trace: []
+		});
+		return {
+			ok: false,
+			refusal
+		};
+	}
+	let content;
+	try {
+		const info = await stat(path);
+		if (info.size > MAX_SCAN_BYTES) {
+			const refusal = structuredDeny("deny", requested, [], "scan-limit", `files over ${MAX_SCAN_BYTES} bytes are not served through the gate`);
+			record({
+				subject: path,
+				capability: "fs:read",
+				verdict: "deny",
+				rule: "scan-limit",
+				reason: `${info.size} bytes exceeds the inspection limit`,
+				trace: []
+			});
+			return {
+				ok: false,
+				refusal
+			};
+		}
+		content = await readFile(path, "utf8");
+	} catch {
+		return {
+			ok: false,
+			refusal: JSON.stringify({
+				decision: "error",
+				reason: "unreadable",
+				resource: requested,
+				retry: false,
+				message: "the file does not exist or cannot be read"
+			})
+		};
+	}
+	const findings = scan(content);
+	const decision = evaluate(options.pack, {
+		tool: "read_file",
+		capability: "fs:read",
+		args: { path },
+		...findings.length > 0 ? { secrets: findings } : {}
+	});
+	record({
+		subject: path,
+		capability: "fs:read",
+		verdict: decision.kind === "correct" ? "deny" : decision.kind,
+		...decision.rule === void 0 ? {} : { rule: decision.rule },
+		...decision.reason === void 0 ? {} : { reason: decision.reason },
+		trace: decision.trace,
+		...findings.length > 0 ? { secrets: findings.map(({ rule, type, line, confidence }) => ({
+			rule,
+			type,
+			line,
+			confidence
+		})) } : {}
+	});
+	if (decision.kind === "deny" || decision.kind === "ask" || decision.kind === "correct") return {
+		ok: false,
+		refusal: structuredDeny(decision.kind === "ask" ? "ask" : "deny", path, findings.map((f) => f.type), decision.rule, decision.reason ?? "refused by policy")
+	};
+	return {
+		ok: true,
+		content
+	};
+}
+/** Mount the gate on stdio and serve until the client hangs up. */
+async function serveMcp(options) {
+	const server = new Server({
+		name: "prae-gate",
+		version: "0.4.0"
+	}, { capabilities: { tools: {} } });
+	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: [{
+		name: "read_file",
+		description: "Read a file through the PRAE gate. Contents are inspected for credentials before they are returned; a refusal is structured JSON and never contains the credential.",
+		inputSchema: {
+			type: "object",
+			properties: { path: {
+				type: "string",
+				description: "File path, relative to the served root."
+			} },
+			required: ["path"]
+		}
+	}, {
+		name: "list_dir",
+		description: "List a directory under the served root.",
+		inputSchema: {
+			type: "object",
+			properties: { path: {
+				type: "string",
+				description: "Directory path, relative to the served root."
+			} },
+			required: ["path"]
+		}
+	}] }));
+	server.setRequestHandler(CallToolRequestSchema, async (request) => {
+		const name = request.params.name;
+		const args = request.params.arguments ?? {};
+		const requested = typeof args.path === "string" ? args.path : void 0;
+		if (requested === void 0) return {
+			content: [{
+				type: "text",
+				text: "missing required argument `path`"
+			}],
+			isError: true
+		};
+		if (name === "read_file") {
+			const result = await judgeRead(options, requested);
+			return result.ok ? { content: [{
+				type: "text",
+				text: result.content
+			}] } : {
+				content: [{
+					type: "text",
+					text: result.refusal
+				}],
+				isError: true
+			};
+		}
+		if (name === "list_dir") {
+			const path = resolve(options.root, requested);
+			const rootPrefix = options.root.endsWith(sep) ? options.root : options.root + sep;
+			if (path !== options.root && !path.startsWith(rootPrefix)) return {
+				content: [{
+					type: "text",
+					text: `listing is confined to ${options.root}`
+				}],
+				isError: true
+			};
+			try {
+				return { content: [{
+					type: "text",
+					text: (await readdir(path, { withFileTypes: true })).map((entry) => entry.isDirectory() ? `${entry.name}/` : entry.name).join("\n")
+				}] };
+			} catch {
+				return {
+					content: [{
+						type: "text",
+						text: "not a readable directory"
+					}],
+					isError: true
+				};
+			}
+		}
+		return {
+			content: [{
+				type: "text",
+				text: `unknown tool \`${name}\``
+			}],
+			isError: true
+		};
+	});
+	await server.connect(new StdioServerTransport());
+}
+
+//#endregion
+export { judgeRead, serveMcp };

package/lib/playground.js

@@ -343,6 +343,11 @@
 			if (key === void 0) return false;
 			if (!((facts.counts?.[key] ?? 0) > when.count.above)) return false;
 		}
+		if (when.secrets !== void 0) {
+			const floor = when.secrets.minConfidence ?? 0;
+			const wanted = when.secrets.types;
+			if ((facts.secrets ?? []).filter((finding) => finding.confidence >= floor && (wanted === void 0 || wanted.includes(finding.type))).length < (when.secrets.atLeast ?? 1)) return false;
+		}
 		return true;
 	}
 	function step(rule, effect) {
@@ -579,6 +584,33 @@
 		else out.present = value.present;
 		return out;
 	}
+	function readSecretsMatch(check, path, value) {
+		if (!isObject(value)) {
+			check.fail(path, "expected an object");
+			return;
+		}
+		check.keys(path, value, [
+			"types",
+			"minConfidence",
+			"atLeast"
+		]);
+		const out = {};
+		if (value.types !== void 0) {
+			const types = check.globs(`${path}.types`, value.types);
+			if (types !== void 0) out.types = types;
+		}
+		if (value.minConfidence !== void 0) {
+			const n = check.number(`${path}.minConfidence`, value.minConfidence);
+			if (n !== void 0) if (n < 0 || n > 1) check.fail(`${path}.minConfidence`, "expected a number between 0 and 1");
+			else out.minConfidence = n;
+		}
+		if (value.atLeast !== void 0) {
+			const n = check.number(`${path}.atLeast`, value.atLeast);
+			if (n !== void 0) if (!Number.isInteger(n) || n < 1) check.fail(`${path}.atLeast`, "expected an integer of at least 1");
+			else out.atLeast = n;
+		}
+		return out;
+	}
 	function readMatch(check, path, value) {
 		if (!isObject(value)) {
 			check.fail(path, "expected an object");
@@ -593,7 +625,8 @@
 			"path",
 			"host",
 			"arg",
-			"count"
+			"count",
+			"secrets"
 		]);
 		const out = {};
 		for (const key of [
@@ -632,6 +665,10 @@
 			const above = check.number(`${path}.count.above`, value.count.above);
 			if (above !== void 0) out.count = { above };
 		}
+		if (value.secrets !== void 0) {
+			const match = readSecretsMatch(check, `${path}.secrets`, value.secrets);
+			if (match !== void 0) out.secrets = match;
+		}
 		return out;
 	}
 	function readEffect(check, path, value) {