prae-cli 0.8.0 → 0.9.2

package/lib/{evaluate-wMPkjcIC.js → evaluate-BqLxhYiP.js}

@@ -348,6 +348,7 @@ function pathArgOf(args, explicit) {
 * appending to a pack can never accidentally widen what an agent may do.
 */
 const STRENGTH = {
+	allow: 0,
 	warn: 1,
 	correct: 2,
 	ask: 3,
@@ -479,6 +480,14 @@ function evaluate(pack, facts) {
 			evaluated
 		};
 	}
+	const allowed = hits.find((hit) => hit.effect.kind === "allow");
+	if (allowed !== void 0) return {
+		kind: "allow",
+		rule: allowed.rule.id,
+		reason: allowed.effect.because,
+		trace,
+		evaluated
+	};
 	return {
 		kind: "allow",
 		trace,
@@ -487,4 +496,4 @@ function evaluate(pack, facts) {
 }
 
 //#endregion
-export { evaluate as t };
+export { hostOf as n, withinAny as r, evaluate as t };

package/lib/index.d.ts

@@ -36,6 +36,8 @@ declare function praeRow(options: {
   readonly pack?: string;
   /** The pack as a file the gate watches (hot reload); wins over `pack`. */
   readonly packFile?: string;
+  /** The workspace's own packs, loaded and watched beside `pack` / `packFile`. */
+  readonly packDir?: string;
   /** `shadow` seals every verdict and lets every call through. */
   readonly mode?: 'enforce' | 'shadow';
   readonly ledger?: string;

package/lib/index.js

@@ -1,6 +1,6 @@
-import "./evaluate-wMPkjcIC.js";
-import "./views-CCwVXpo2.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-UAE968If.js";
-import "./src-Ciggx9ja.js";
+import "./evaluate-BqLxhYiP.js";
+import "./views-D4UEfbzt.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-B_B6-bUZ.js";
+import "./src-LA7NdLKb.js";
 
 export { applyWrite, defaultProfile, dshHome, main, planWrite, praeRow, profileAt };

package/lib/{instructions-DulxSqFd.js → instructions-ya0LVnZy.js}

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

package/lib/{mcp-doNYU-1C.js → mcp-BCXbpqu4.js}

@@ -1,4 +1,4 @@
-import { t as evaluate } from "./evaluate-wMPkjcIC.js";
+import { t as evaluate } from "./evaluate-BqLxhYiP.js";
 import { a as scan, n as MAX_SCAN_BYTES } from "./src-B25SHWcz.js";
 import { readFile, readdir, stat } from "node:fs/promises";
 import { resolve, sep } from "node:path";

package/lib/playground.js

@@ -351,6 +351,7 @@
 	* appending to a pack can never accidentally widen what an agent may do.
 	*/
 	const STRENGTH = {
+		allow: 0,
 		warn: 1,
 		correct: 2,
 		ask: 3,
@@ -482,6 +483,14 @@
 				evaluated
 			};
 		}
+		const allowed = hits.find((hit) => hit.effect.kind === "allow");
+		if (allowed !== void 0) return {
+			kind: "allow",
+			rule: allowed.rule.id,
+			reason: allowed.effect.because,
+			trace,
+			evaluated
+		};
 		return {
 			kind: "allow",
 			trace,
@@ -854,9 +863,9 @@
 			check.fail(path, "expected an object");
 			return;
 		}
-		const kind = value.kind;
-		if (kind !== "deny" && kind !== "ask" && kind !== "correct" && kind !== "warn") {
-			check.fail(`${path}.kind`, "expected `deny`, `ask`, `correct`, or `warn`");
+		const kind = value.kind === "hold" ? "ask" : value.kind;
+		if (kind !== "deny" && kind !== "ask" && kind !== "correct" && kind !== "warn" && kind !== "allow") {
+			check.fail(`${path}.kind`, "expected `allow`, `deny`, `hold` (or `ask`), `correct`, or `warn`");
 			return;
 		}
 		check.keys(path, value, kind === "correct" ? [
@@ -890,6 +899,7 @@
 		check.keys(path, value, [
 			"id",
 			"title",
+			"description",
 			"when",
 			"effect",
 			"frameworks"
@@ -908,6 +918,10 @@
 			const title = check.text(`${path}.title`, value.title);
 			if (title !== void 0) rule.title = title;
 		}
+		if (value.description !== void 0) {
+			const description = check.text(`${path}.description`, value.description);
+			if (description !== void 0) rule.description = description;
+		}
 		if (value.frameworks !== void 0) {
 			const frameworks = readFrameworks(check, `${path}.frameworks`, value.frameworks);
 			if (frameworks !== void 0) rule.frameworks = frameworks;
@@ -968,12 +982,16 @@
 			"prae",
 			"pack",
 			"version",
+			"description",
+			"owner",
 			"baseline",
 			"rules"
 		]);
 		if (raw.prae !== "0.1") check.fail(".prae", "expected `\"0.1\"`; this is the only pack version this build reads");
 		const name = check.text(".pack", raw.pack);
 		const version = check.text(".version", raw.version);
+		const description = raw.description === void 0 ? void 0 : check.text(".description", raw.description);
+		const owner = raw.owner === void 0 ? void 0 : check.text(".owner", raw.owner);
 		let baseline;
 		if (raw.baseline !== void 0) if (!isObject(raw.baseline)) check.fail(".baseline", "expected an object");
 		else {
@@ -1010,6 +1028,8 @@
 				prae: "0.1",
 				pack: name,
 				version,
+				...description === void 0 ? {} : { description },
+				...owner === void 0 ? {} : { owner },
 				...baseline === void 0 ? {} : { baseline },
 				rules
 			}

package/lib/{receipt-check-s3Aryyz-.js → receipt-check-DQK_gVPc.js}

@@ -1,4 +1,4 @@
-import { c as verifyReceipt, i as fingerprint } from "./src-Ciggx9ja.js";
+import { c as fingerprint, f as verifyReceipt } from "./src-LA7NdLKb.js";
 
 //#region src/receipt-check.ts
 /** Shape we require before we will call it a receipt at all. */

package/lib/src-7X6dO7gC.js

@@ -0,0 +1,3 @@
+import { _ as hashEntry, a as signBytes, c as fingerprint, d as signEntry, f as verifyReceipt, g as chain, h as canonical, i as sealedKeypair, l as generateKeypair, m as GENESIS, n as readEntries, o as unsealPrivateKey, p as verifySignature, r as verifyEntries, s as verifyBytes, t as Ledger, u as makeReceipt, v as seal } from "./src-LA7NdLKb.js";
+
+export { GENESIS, Ledger, canonical, chain, fingerprint, generateKeypair, hashEntry, makeReceipt, readEntries, seal, sealedKeypair, signBytes, signEntry, unsealPrivateKey, verifyBytes, verifyEntries, verifyReceipt, verifySignature };

package/lib/src-LA7NdLKb.js

@@ -0,0 +1,399 @@
+import { appendFileSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createCipheriv, createDecipheriv, createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomBytes, scryptSync, sign, verify } from "node:crypto";
+
+//#region ../ledger/src/entry.ts
+/** The hash a chain starts from. */
+const GENESIS = "0".repeat(64);
+/**
+* Deterministic serialization: object keys sorted at every depth.
+*
+* A hash over `JSON.stringify(entry)` would depend on key insertion order,
+* which means a re-serialized entry could hash differently while saying
+* exactly the same thing — and a verifier that reports tampering on a
+* faithful copy trains its operators to ignore it.
+*/
+function canonical(value) {
+	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+	return `{${Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(",")}}`;
+}
+/** Hash one entry's content together with its position and predecessor. */
+function hashEntry(record, seq, prev) {
+	return createHash("sha256").update(canonical({
+		...record,
+		seq,
+		prev
+	})).digest("hex");
+}
+/** Chain a record onto a predecessor. */
+function chain(record, seq, prev) {
+	return {
+		...record,
+		seq,
+		prev,
+		hash: hashEntry(record, seq, prev)
+	};
+}
+/** The short form an auditor quotes from a screenshot. */
+function seal(entry) {
+	return `${entry.hash.slice(0, 4)}…${entry.hash.slice(-4)}`;
+}
+
+//#endregion
+//#region ../ledger/src/receipt.ts
+function generateKeypair() {
+	const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+	return {
+		publicKey: publicKey.export({
+			type: "spki",
+			format: "pem"
+		}).toString(),
+		privateKey: privateKey.export({
+			type: "pkcs8",
+			format: "pem"
+		}).toString()
+	};
+}
+/** Sign a row's seal. The seal already covers the whole canonical record. */
+function signEntry(entry, privateKeyPem) {
+	const key = createPrivateKey(privateKeyPem);
+	return sign(null, Buffer.from(entry.hash, "hex"), key).toString("base64");
+}
+function verifySignature(entry, signature, publicKeyPem) {
+	try {
+		const key = createPublicKey(publicKeyPem);
+		return verify(null, Buffer.from(entry.hash, "hex"), key, Buffer.from(signature, "base64"));
+	} catch {
+		return false;
+	}
+}
+function makeReceipt(entry, privateKeyPem, publicKeyPem) {
+	return {
+		receipt: "prae/1",
+		entry,
+		signature: signEntry(entry, privateKeyPem),
+		publicKey: publicKeyPem
+	};
+}
+/** Verify a receipt from nothing but the receipt. */
+function verifyReceipt(receipt) {
+	if (receipt.receipt !== "prae/1") return {
+		ok: false,
+		reason: `unknown receipt format ${String(receipt.receipt)}`
+	};
+	const { seq, prev, hash, sig,...record } = receipt.entry;
+	if (hashEntry(record, seq, prev) !== hash) return {
+		ok: false,
+		reason: "entry contents do not match their seal; the row was altered"
+	};
+	if (!verifySignature(receipt.entry, receipt.signature, receipt.publicKey)) return {
+		ok: false,
+		reason: "signature does not verify; not sealed by this key"
+	};
+	return { ok: true };
+}
+/**
+* A short identifier for a public key, for pinning by eye.
+*
+* A counterparty checks a receipt against a key they already trust; comparing
+* the whole PEM by hand invites skimming, and eight grouped hex bytes do not.
+*/
+function fingerprint(publicKeyPem) {
+	const der = createPublicKey(publicKeyPem).export({
+		type: "spki",
+		format: "der"
+	});
+	return createHash("sha256").update(der).digest("hex").slice(0, 16).replace(/(.{4})/g, "$1 ").trim();
+}
+
+//#endregion
+//#region ../ledger/src/authority.ts
+const priv = (k) => typeof k === "string" ? createPrivateKey(k) : k;
+/** How long a signed answer is good for, by default. */
+const ANSWER_TTL_MS = 5 * 6e4;
+/** A detached signature over exact bytes (a policy pack's file). */
+function signBytes(bytes, privateKey) {
+	return sign(null, Buffer.from(bytes), priv(privateKey)).toString("base64");
+}
+function verifyBytes(bytes, signature, publicKeyPem) {
+	try {
+		return verify(null, Buffer.from(bytes), createPublicKey(publicKeyPem), Buffer.from(signature.trim(), "base64"));
+	} catch {
+		return false;
+	}
+}
+/**
+* How a private key is sealed at rest: scrypt (N = 2^17, r = 8, p = 1) over
+* the passphrase, AES-256-GCM over the key. The sealed file can sit where an
+* agent can read it; each guess at the passphrase costs ~128 MiB and a
+* noticeable fraction of a second, so a strong passphrase holds against an
+* offline attack. (PKCS#8 as Node writes it uses PBKDF2 at 2,048 rounds —
+* too cheap for a file the agent can copy.)
+*/
+const SCRYPT = {
+	N: 2 ** 17,
+	r: 8,
+	p: 1,
+	maxmem: 512 * 1024 * 1024
+};
+const MIN_PASSPHRASE = 12;
+const SEALED = "PRAE SEALED KEY";
+function sealPrivateKey(key, passphrase) {
+	if (passphrase.length < MIN_PASSPHRASE) throw new Error(`passphrase: ${MIN_PASSPHRASE} characters or more`);
+	const salt = randomBytes(16);
+	const iv = randomBytes(12);
+	const cipher = createCipheriv("aes-256-gcm", scryptSync(passphrase, salt, 32, SCRYPT), iv);
+	const der = key.export({
+		type: "pkcs8",
+		format: "der"
+	});
+	const data = Buffer.concat([cipher.update(der), cipher.final()]);
+	return `-----BEGIN ${SEALED}-----\n${(Buffer.from(JSON.stringify({
+		v: 1,
+		kdf: "scrypt",
+		N: SCRYPT.N,
+		r: SCRYPT.r,
+		p: SCRYPT.p,
+		salt: salt.toString("base64"),
+		iv: iv.toString("base64"),
+		tag: cipher.getAuthTag().toString("base64"),
+		data: data.toString("base64")
+	})).toString("base64").match(/.{1,64}/g) ?? []).join("\n")}\n-----END ${SEALED}-----\n`;
+}
+/** A keypair whose private half is sealed under a passphrase. */
+function sealedKeypair(passphrase) {
+	const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+	return {
+		publicKey: publicKey.export({
+			type: "spki",
+			format: "pem"
+		}).toString(),
+		sealedPrivateKey: sealPrivateKey(privateKey, passphrase)
+	};
+}
+/** Unseal into memory. Throws on a wrong passphrase or a tampered file. */
+function unsealPrivateKey(sealed, passphrase) {
+	const match = sealed.match(/* @__PURE__ */ new RegExp(`-----BEGIN ${SEALED}-----([\\s\\S]+?)-----END ${SEALED}-----`));
+	if (match === null) throw new Error("not a PRAE sealed key (an older format?): make a new one with prae keygen --role");
+	const box = JSON.parse(Buffer.from((match[1] ?? "").replace(/\s/g, ""), "base64").toString("utf8"));
+	if (box.v !== 1 || box.kdf !== "scrypt") throw new Error("unknown sealing");
+	const decipher = createDecipheriv("aes-256-gcm", scryptSync(passphrase, Buffer.from(String(box.salt), "base64"), 32, {
+		N: Number(box.N),
+		r: Number(box.r),
+		p: Number(box.p),
+		maxmem: SCRYPT.maxmem
+	}), Buffer.from(String(box.iv), "base64"));
+	decipher.setAuthTag(Buffer.from(String(box.tag), "base64"));
+	return createPrivateKey({
+		key: Buffer.concat([decipher.update(Buffer.from(String(box.data), "base64")), decipher.final()]),
+		format: "der",
+		type: "pkcs8"
+	});
+}
+
+//#endregion
+//#region ../ledger/src/ledger.ts
+/**
+* Read a ledger held as text.
+*
+* Split out from the class because a ledger is not always a file being
+* appended to: a build step renders one it imported, and a reader pastes one
+* in. Those callers need the same parsing and the same verification the CLI
+* runs, and a second implementation of either is how two answers to "does this
+* chain hold" come to exist.
+*/
+function readEntries(text) {
+	return text.split("\n").filter((line) => line.trim() !== "").map((line) => JSON.parse(line));
+}
+/** Re-derive every hash and confirm each entry names its predecessor. */
+function verifyEntries(text) {
+	const problems = [];
+	let expectedPrev = GENESIS;
+	let expectedSeq = 0;
+	let count = 0;
+	const lines = text.split("\n").filter((line) => line.trim() !== "");
+	for (const [index, line] of lines.entries()) {
+		const at = index + 1;
+		count += 1;
+		let entry;
+		try {
+			entry = JSON.parse(line);
+		} catch {
+			problems.push({
+				line: at,
+				message: "not valid JSON"
+			});
+			return {
+				ok: false,
+				entries: count,
+				problems
+			};
+		}
+		if (entry.seq !== expectedSeq) problems.push({
+			line: at,
+			message: `expected seq ${expectedSeq}, found ${entry.seq}`
+		});
+		if (entry.prev !== expectedPrev) problems.push({
+			line: at,
+			message: "does not name the previous entry; a row was removed or reordered"
+		});
+		const { seq, prev, hash, sig: _sig,...record } = entry;
+		if (hashEntry(record, seq, prev) !== hash) problems.push({
+			line: at,
+			message: "contents do not match the sealed hash"
+		});
+		expectedPrev = entry.hash;
+		expectedSeq = entry.seq + 1;
+	}
+	return {
+		ok: problems.length === 0,
+		entries: count,
+		problems
+	};
+}
+/** The last complete line of a file, reading only its end when it can. */
+function lastLine(path) {
+	const fd = openSync(path, "r");
+	try {
+		const size = fstatSync(fd).size;
+		for (let span = 64 * 1024;; span *= 4) {
+			const start = Math.max(0, size - span);
+			const buffer = Buffer.alloc(size - start);
+			readSync(fd, buffer, 0, buffer.length, start);
+			const lines = buffer.toString("utf8").split("\n").filter((line) => line.trim() !== "");
+			if (start === 0 || lines.length > 1) return lines.at(-1);
+		}
+	} finally {
+		closeSync(fd);
+	}
+}
+/** Where the chain ends now: the next seq and the hash to continue from. */
+function tailOf(path) {
+	let tail;
+	try {
+		tail = lastLine(path);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+		return {
+			seq: 0,
+			last: GENESIS
+		};
+	}
+	if (tail === void 0) return {
+		seq: 0,
+		last: GENESIS
+	};
+	let entry;
+	try {
+		entry = JSON.parse(tail);
+	} catch {
+		throw new Error(`prae ledger: last line of ${path} is not readable; refusing to append onto a chain that cannot be continued`);
+	}
+	return {
+		seq: entry.seq + 1,
+		last: entry.hash
+	};
+}
+const SLEEP = new Int32Array(new SharedArrayBuffer(4));
+/** A lock older than this was left by a writer that died holding it. */
+const STALE_LOCK_MS = 1e4;
+/** Run `fn` holding an exclusive lock file; synchronous, like the append. */
+function withLock(lock, fn) {
+	const deadline = Date.now() + 3e4;
+	for (;;) {
+		let fd;
+		try {
+			fd = openSync(lock, "wx");
+		} catch (error) {
+			if (error.code !== "EEXIST") throw error;
+			try {
+				if (Date.now() - statSync(lock).mtimeMs > STALE_LOCK_MS) {
+					unlinkSync(lock);
+					continue;
+				}
+			} catch {}
+			if (Date.now() > deadline) throw new Error(`prae ledger: ${lock} has been held for 30 s; refusing to append without it`);
+			Atomics.wait(SLEEP, 0, 0, 2);
+			continue;
+		}
+		try {
+			return fn();
+		} finally {
+			closeSync(fd);
+			try {
+				unlinkSync(lock);
+			} catch {}
+		}
+	}
+}
+var Ledger = class Ledger {
+	path;
+	constructor(path) {
+		this.path = path;
+	}
+	/**
+	* Open a ledger, reading the tail to continue an existing chain.
+	*
+	* A corrupt or truncated final line is a hard error rather than something to
+	* skip past: appending onto a chain whose end we could not read would bury
+	* the damage under valid-looking entries.
+	*/
+	/** Sign every appended row with this Ed25519 private key (PEM). */
+	signWith;
+	/** Or through a signing boundary that holds the key (PRA-108). */
+	signer;
+	static open(path, options = {}) {
+		const ledger = Ledger.openUnsigned(path);
+		ledger.signWith = options.signWith;
+		ledger.signer = options.signer;
+		return ledger;
+	}
+	static openUnsigned(path) {
+		mkdirSync(dirname(path), { recursive: true });
+		try {
+			writeFileSync(path, "", { flag: "wx" });
+		} catch (error) {
+			if (error.code !== "EEXIST") throw error;
+		}
+		tailOf(path);
+		return new Ledger(path);
+	}
+	/** Append one decision and return the entry as written. */
+	append(record) {
+		return withLock(`${this.path}.lock`, () => {
+			const { seq, last } = tailOf(this.path);
+			const sealed = chain(record, seq, last);
+			const entry = this.signer !== void 0 ? {
+				...sealed,
+				sig: this.signer(sealed)
+			} : this.signWith === void 0 ? sealed : {
+				...sealed,
+				sig: signEntry(sealed, this.signWith)
+			};
+			appendFileSync(this.path, `${JSON.stringify(entry)}\n`);
+			return entry;
+		});
+	}
+	/** Every entry, in order. */
+	read() {
+		return readEntries(readFileSync(this.path, "utf8"));
+	}
+	/**
+	* Re-derive every hash and confirm each entry names its predecessor.
+	*
+	* Catches a deleted row, an edited field, and a reordering. Does not catch a
+	* wholesale rewrite of the file by someone holding the same code — see the
+	* note in `entry.ts`.
+	*/
+	verify() {
+		return verifyEntries(readFileSync(this.path, "utf8"));
+	}
+};
+
+//#endregion
+//#region ../ledger/src/signer.ts
+const nap = new Int32Array(new SharedArrayBuffer(4));
+
+//#endregion
+export { hashEntry as _, signBytes as a, fingerprint as c, signEntry as d, verifyReceipt as f, chain as g, canonical as h, sealedKeypair as i, generateKeypair as l, GENESIS as m, readEntries as n, unsealPrivateKey as o, verifySignature as p, verifyEntries as r, verifyBytes as s, Ledger as t, makeReceipt as u, seal as v };

package/lib/{test-run-XNIRHKOu.js → test-run-CCDgJ0Dp.js}

@@ -1,4 +1,4 @@
-import { t as evaluate } from "./evaluate-wMPkjcIC.js";
+import { t as evaluate } from "./evaluate-BqLxhYiP.js";
 
 //#region src/test-run.ts
 /** The path argument a scenario's call carries, if any. */