prae-cli 0.2.1 → 0.4.0

package/lib/secret-catcher.prae.json

@@ -0,0 +1,49 @@
+{
+  "prae": "0.1",
+  "pack": "secret-catcher",
+  "version": "1.0.0",
+  "rules": [
+    {
+      "id": "SEC-001",
+      "title": "Reads carrying credentials are refused",
+      "when": {
+        "capability": "fs:read",
+        "path": {
+          "outside": [
+            "./**/test/**",
+            "./**/tests/**",
+            "./**/fixtures/**",
+            "./**/*.example",
+            "./**/*.sample"
+          ]
+        },
+        "secrets": { "minConfidence": 0.8 }
+      },
+      "effect": {
+        "kind": "deny",
+        "because": "the requested file contains a protected credential; the contents were not returned"
+      }
+    },
+    {
+      "id": "SEC-002",
+      "title": "Private keys are refused everywhere",
+      "when": {
+        "capability": "fs:read",
+        "secrets": { "types": ["private-key"] }
+      },
+      "effect": {
+        "kind": "deny",
+        "because": "the requested file contains a private key; the contents were not returned"
+      }
+    },
+    {
+      "id": "SEC-003",
+      "title": "Anything credential-shaped is at least recorded",
+      "when": { "capability": "fs:read", "secrets": { "minConfidence": 0.5 } },
+      "effect": {
+        "kind": "warn",
+        "because": "a possible credential was noticed in this file; where no stronger rule fired, the read proceeded and this row is the record"
+      }
+    }
+  ]
+}

package/lib/src-Br1tGPtS.js

@@ -0,0 +1,182 @@
+//#region ../inspect/src/index.ts
+/**
+* The built-in detectors.
+*
+* Anchored provider formats first — those prefixes exist precisely so that
+* scanners can find them, and they carry the confidence to prove it. The
+* loose assignment patterns at the bottom earn their keep only with an
+* entropy check, because `password = "password"` is not a leak, it is a test.
+*/
+const DETECTORS = [
+	{
+		rule: "private-key",
+		type: "private-key",
+		pattern: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?-----/g,
+		confidence: .99
+	},
+	{
+		rule: "aws-access-key-id",
+		type: "cloud-credential",
+		pattern: /\b(?:AKIA|ASIA|ABIA|ACCA)[A-Z0-9]{16}\b/g,
+		confidence: .9
+	},
+	{
+		rule: "github-token",
+		type: "token",
+		pattern: /\b(?:gh[poasur]_[A-Za-z0-9]{36,251}|github_pat_[A-Za-z0-9_]{22,255})\b/g,
+		confidence: .95
+	},
+	{
+		rule: "gitlab-token",
+		type: "token",
+		pattern: /\bglpat-[A-Za-z0-9_-]{20,}\b/g,
+		confidence: .95
+	},
+	{
+		rule: "slack-token",
+		type: "token",
+		pattern: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g,
+		confidence: .9
+	},
+	{
+		rule: "stripe-live-key",
+		type: "api-key",
+		pattern: /\b[sr]k_live_[A-Za-z0-9]{16,}\b/g,
+		confidence: .95
+	},
+	{
+		rule: "google-api-key",
+		type: "api-key",
+		pattern: /\bAIza[0-9A-Za-z_-]{35}\b/g,
+		confidence: .9
+	},
+	{
+		rule: "anthropic-key",
+		type: "api-key",
+		pattern: /\bsk-ant-[A-Za-z0-9-]{32,}\b/g,
+		confidence: .95
+	},
+	{
+		rule: "openai-key",
+		type: "api-key",
+		pattern: /\bsk-(?:proj-)?[A-Za-z0-9_-]{32,}\b/g,
+		confidence: .8
+	},
+	{
+		rule: "npm-token",
+		type: "token",
+		pattern: /\bnpm_[A-Za-z0-9]{36}\b/g,
+		confidence: .95
+	},
+	{
+		rule: "credential-in-url",
+		type: "credential-in-url",
+		pattern: /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis|amqps?|ftp):\/\/[^:\s/@'"]+:[^@\s/'"]+@/g,
+		confidence: .85
+	},
+	{
+		rule: "jwt",
+		type: "token",
+		pattern: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}\b/g,
+		confidence: .6
+	},
+	{
+		rule: "password-assignment",
+		type: "password",
+		pattern: /\b(?:password|passwd|pwd)\b\s*[:=]\s*['"]([^'"\s]{6,})['"]/gi,
+		confidence: .5,
+		minEntropy: 3
+	},
+	{
+		rule: "secret-assignment",
+		type: "generic-secret",
+		pattern: /\b(?:secret|token|api[_-]?key|auth[_-]?token|access[_-]?key)\b\w*\s*[:=]\s*['"]([A-Za-z0-9/+_=-]{20,})['"]/gi,
+		confidence: .6,
+		minEntropy: 3.5
+	}
+];
+/**
+* Markers of a value that exists to be seen.
+*
+* A finding whose match carries one of these is dropped, not down-scored:
+* `AKIAIOSFODNN7EXAMPLE` is in more documentation than any real key is in
+* code, and a gate that denies the README teaches operators to turn it off.
+* The AWS docs key is listed literally because it does not say "example"
+* anywhere a case-insensitive substring would find. Real secrets do not
+* contain these words; a placeholder that does is doing its job.
+*/
+const PLACEHOLDER = /example|changeme|change-me|placeholder|your[_-]|xxxx|dummy|sample|redacted|<[a-z_-]+>|AKIAIOSFODNN7/i;
+/** Shannon entropy in bits per character. */
+function entropy(text) {
+	if (text.length === 0) return 0;
+	const counts = /* @__PURE__ */ new Map();
+	for (const ch of text) counts.set(ch, (counts.get(ch) ?? 0) + 1);
+	let sum = 0;
+	for (const n of counts.values()) {
+		const p = n / text.length;
+		sum -= p * Math.log2(p);
+	}
+	return sum;
+}
+/**
+* Content larger than this is not scanned — the caller is told, not silently
+* covered. Regex over an unbounded file in the hot path of every read is how
+* a gate becomes an outage; 2 MiB covers any file a secret plausibly lives in.
+*/
+const MAX_SCAN_BYTES = 2 * 1024 * 1024;
+/** NUL in the first 8 KiB: binary, not text. Scanned as nothing. */
+function looksBinary(content) {
+	return content.slice(0, 8192).includes("\0");
+}
+/**
+* Scan text for secrets. Findings in document order, deduplicated by span —
+* when two rules claim the same region, the higher confidence keeps it.
+*/
+function scan(content, options = {}) {
+	if (looksBinary(content)) return [];
+	const detectors = options.detectors ?? DETECTORS;
+	const floor = options.minConfidence ?? 0;
+	const starts = [0];
+	for (let i = 0; i < content.length; i++) if (content[i] === "\n") starts.push(i + 1);
+	const position = (offset) => {
+		let low = 0;
+		let high = starts.length - 1;
+		while (low < high) {
+			const mid = low + high + 1 >> 1;
+			if (starts[mid] <= offset) low = mid;
+			else high = mid - 1;
+		}
+		return {
+			line: low + 1,
+			column: offset - starts[low] + 1
+		};
+	};
+	const bySpan = /* @__PURE__ */ new Map();
+	for (const detector of detectors) {
+		const pattern = new RegExp(detector.pattern.source, detector.pattern.flags);
+		for (const match of content.matchAll(pattern)) {
+			const text = match[0];
+			if (PLACEHOLDER.test(text)) continue;
+			if (detector.minEntropy !== void 0) {
+				if (entropy(match[1] ?? text) < detector.minEntropy) continue;
+			}
+			if (detector.confidence < floor) continue;
+			const key = `${match.index}:${text.length}`;
+			const standing = bySpan.get(key);
+			if (standing !== void 0 && standing.confidence >= detector.confidence) continue;
+			const { line, column } = position(match.index);
+			bySpan.set(key, {
+				rule: detector.rule,
+				type: detector.type,
+				line,
+				column,
+				length: text.length,
+				confidence: detector.confidence
+			});
+		}
+	}
+	return [...bySpan.values()].sort((a, b) => a.line - b.line || a.column - b.column);
+}
+
+//#endregion
+export { scan as a, looksBinary as i, MAX_SCAN_BYTES as n, entropy as r, DETECTORS as t };

package/lib/src-CAUNqZJ1.js

@@ -0,0 +1,225 @@
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, 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
+	};
+}
+/**
+* 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/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
+	};
+}
+var Ledger = class Ledger {
+	path;
+	seq;
+	last;
+	constructor(path, seq, last) {
+		this.path = path;
+		this.seq = seq;
+		this.last = last;
+	}
+	/**
+	* 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;
+	static open(path, options = {}) {
+		const ledger = Ledger.openUnsigned(path);
+		ledger.signWith = options.signWith;
+		return ledger;
+	}
+	static openUnsigned(path) {
+		mkdirSync(dirname(path), { recursive: true });
+		let text = "";
+		try {
+			text = readFileSync(path, "utf8");
+		} catch (error) {
+			if (error.code !== "ENOENT") throw error;
+			writeFileSync(path, "", { flag: "wx" });
+			return new Ledger(path, 0, GENESIS);
+		}
+		const tail = text.split("\n").filter((line) => line.trim() !== "").at(-1);
+		if (tail === void 0) return new Ledger(path, 0, 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 new Ledger(path, entry.seq + 1, entry.hash);
+	}
+	/** Append one decision and return the entry as written. */
+	append(record) {
+		const sealed = chain(record, this.seq, this.last);
+		const entry = this.signWith === void 0 ? sealed : {
+			...sealed,
+			sig: signEntry(sealed, this.signWith)
+		};
+		appendFileSync(this.path, `${JSON.stringify(entry)}\n`);
+		this.seq += 1;
+		this.last = entry.hash;
+		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
+export { generateKeypair as a, verifySignature as c, chain as d, hashEntry as f, fingerprint as i, GENESIS as l, readEntries as n, makeReceipt as o, seal as p, verifyEntries as r, signEntry as s, Ledger as t, canonical as u };

package/lib/src-CBK_quVO.js

@@ -0,0 +1,3 @@
+import { a as generateKeypair, c as verifySignature, d as chain, f as hashEntry, i as fingerprint, l as GENESIS, n as readEntries, o as makeReceipt, p as seal, r as verifyEntries, s as signEntry, t as Ledger, u as canonical } from "./src-CAUNqZJ1.js";
+
+export { GENESIS, Ledger, canonical, chain, fingerprint, generateKeypair, hashEntry, makeReceipt, readEntries, seal, signEntry, verifyEntries, verifySignature };

package/lib/src-Vnr0fcpK.js

@@ -0,0 +1,3 @@
+import { a as scan, i as looksBinary, n as MAX_SCAN_BYTES, r as entropy, t as DETECTORS } from "./src-Br1tGPtS.js";
+
+export { DETECTORS, MAX_SCAN_BYTES, entropy, looksBinary, scan };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prae-cli",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Operator policy for agent harnesses: validate packs, explain a decision, verify a decision log, and provision a governed DSH profile.",
   "keywords": [
     "dsh-plugin",
@@ -31,6 +31,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "capmark": "^0.3.1",
     "dsh-overlay-check": "^0.4.0"
   },
@@ -41,10 +42,11 @@
     "vitest": "^3.2.4",
     "@prae/controls": "0.1.0",
     "@prae/extract": "0.1.0",
+    "@prae/inspect": "0.1.0",
     "@prae/instructions": "0.1.0",
+    "@prae/kernel": "0.1.0",
     "@prae/ledger": "0.1.0",
-    "@prae/tokens": "0.1.0",
-    "@prae/kernel": "0.1.0"
+    "@prae/tokens": "0.1.0"
   },
   "scripts": {
     "test": "vitest run",