prae-cli 0.9.2 → 0.10.0

package/lib/docs/pilot-claude-code.md

@@ -0,0 +1,191 @@
+# Pilot: PRAE on one Claude Code laptop
+
+PRAE runs as a Claude Code `PreToolUse` hook. Before every tool call (built-in
+tools such as `Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`, `WebFetch`, and
+every MCP tool `mcp__<server>__<tool>`), Claude Code runs `prae hook
+claude-code`. The hook judges the call against a policy pack with the same
+kernel the other PRAE harnesses use, and appends the verdict to a signed,
+hash-chained ledger on this machine.
+
+It starts in **shadow mode**. Shadow mode records every verdict and blocks
+nothing. When the record looks right, one command switches it to **enforce**.
+
+There is no cloud account, no open port, no network call and no service to run.
+
+**Verified on Claude Code 2.1.233**, from a fresh clone, by following this
+guide in a temporary project:
+
+- **Shadow.** One headless session made 10 tool calls: `Read`, `Write`, `Edit`,
+  `Bash`, `Glob`, `Grep`, `WebFetch` and `mcp__prae__read_file`. All 10 ran,
+  and each one was sealed with its verdict. The `.env` read was sealed as a
+  shadow deny (`BASE-005`), and `rm -rf` as a shadow hold (`BASE-002`).
+- **Enforce.** Claude Code refused these: the `.env` read, the same read
+  through the MCP tool, a fetch to an unlisted host, edits to the pack and
+  to the hook settings, a shell command truncating the pack, and a read of
+  the signing key. `rm -rf` and a write outside the workspace were held, and
+  `claude -p` refused them. Nothing protected changed on disk.
+- **Record.** `prae verify` passed the chain, with 25 of 25 signatures.
+
+## 1. Install (one command)
+
+You need Node 22.19 or later and pnpm 10 (`corepack enable`). Until the
+release that carries this hook is on npm (`prae-cli` 0.9.2 does not have it),
+run it from a checkout of this repository, built once:
+
+```bash
+git clone https://github.com/taltara/prae-harness && cd prae-harness && pnpm install && pnpm --filter prae-cli build
+PRAE="node $PWD/packages/cli/lib/bin.js"     # used below; after the npm release this is just `prae`
+```
+
+Then preview the change, and apply it:
+
+```bash
+$PRAE init claude-code --scope user            # prints the settings diff, writes nothing
+$PRAE init claude-code --scope user --apply    # installs, shadow mode
+```
+
+You must name a target. `--scope user` is `~/.claude/settings.json`, which
+covers every project. `--scope project` is `./.claude/settings.json`.
+`--settings <file>` is any file you name, for example
+`.claude/settings.local.json`. Nothing is written without `--apply`. The file
+is written back as 2-space JSON, the format Claude Code itself writes, so a
+hand-formatted file shows layout changes in the diff. Its values do not change.
+
+`init` adds one entry and leaves every other setting and hook as it was:
+
+```json
+"PreToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "timeout": 10,
+  "command": "'/opt/homebrew/bin/node' '…/packages/cli/lib/bin.js' hook claude-code --shadow --pack '~/.prae/claude-code/prae-baseline.prae.json' --ledger '~/.prae/claude-code/ledger.jsonl' --key '~/.prae/claude-code/prae-signing.pem' --settings '~/.claude/settings.json'" }] }]
+```
+
+The real file holds absolute paths. The command names the node binary and
+PRAE's own script by absolute path, so it does not depend on `PATH`. If you
+move the checkout, run `init` again. Claude Code reloads settings on its own,
+so new tool calls go through PRAE without a restart.
+
+Options:
+
+- `--pack <file>`: use your own pack. The default copies the built-in baseline
+  (8 rules: download-and-execute, `rm -rf`, privilege escalation, block devices,
+  credential files, writes outside the workspace, force-push, publishes).
+  `prae check <file>` summarises a pack.
+- `--ledger <file>`: write the ledger somewhere else.
+- `--dir <dir>`: keep PRAE's state somewhere other than `~/.prae/claude-code/`.
+
+## 2. What it records, and where
+
+Everything lives in `~/.prae/claude-code/`, which is created with mode 0700:
+
+| File | What it is |
+| --- | --- |
+| `ledger.jsonl` | One row for each tool call. Every Claude Code session on the machine appends to this one file, under a lock, so parallel tool calls and parallel sessions stay one chain. |
+| `prae-signing.pem` | The Ed25519 key that signs each row. It is generated once with mode 0600. |
+| `prae-signing.pub.pem` | The public half. Give it to whoever verifies the record. |
+| `prae-baseline.prae.json` | The pack in force, unless you passed `--pack`. |
+
+Each row holds the time, the Claude Code `session_id`, the `tool_use_id` (as
+`correlation`), the tool, its capability (`fs:read`, `fs:write`,
+`proc:spawn`, `net:fetch`), the subject, the verdict, the rule and its reason,
+the pack's name, version and sha256, and, in shadow mode, `shadow: true`. The
+subject is the path or URL only. A shell call is stored as its program word
+and a hash, never the command line. File contents and tool output are never
+stored.
+
+Read the record:
+
+```bash
+P=~/.prae/claude-code
+$PRAE verify  $P/ledger.jsonl --key $P/prae-signing.pub.pem
+$PRAE report  $P/ledger.jsonl --pack $P/prae-baseline.prae.json --out report.html
+$PRAE console $P/ledger.jsonl --pack $P/prae-baseline.prae.json --out console/
+```
+
+In the report and the console, a shadow verdict is marked `· SHADOW`. It is
+never counted as vetoed or held.
+
+## 3. From shadow to enforce
+
+```bash
+$PRAE init claude-code --scope user --enforce --apply
+```
+
+This replaces PRAE's entry. It does not add a second one. In enforce mode:
+
+| Verdict | What Claude Code does |
+| --- | --- |
+| allow | The hook prints nothing. Claude Code's own permission flow decides, as before. PRAE never answers `allow`, because that would skip your permission prompt. |
+| deny | `permissionDecision: "deny"`. The call does not run, and Claude reads the reason, for example `PRAE BASE-005: … (ledger row 12)`. |
+| ask | `permissionDecision: "ask"`. You get a permission prompt. In a headless `claude -p` run nobody can answer it, so Claude Code refuses the call (verified on 2.1.233). |
+| gate error | The pack does not parse, the ledger cannot be written, the key is unreadable, the payload is broken, or the ledger lock is held for more than 3 seconds. The hook refuses the call (exit 2) and records the error in the ledger when it can. |
+
+In shadow mode a gate error lets the call run. It shows a `systemMessage`
+warning and records a `PRAE-ERROR` row marked `shadow`.
+
+## 4. Uninstall
+
+```bash
+$PRAE init claude-code --scope user --remove --apply
+```
+
+This removes PRAE's hook entry and nothing else. The ledger and the key stay
+in place, because they are the evidence of what ran. Delete
+`~/.prae/claude-code/` yourself when you no longer need them.
+
+## 5. Privacy
+
+Nothing leaves the machine. The hook reads the payload Claude Code passes on
+stdin, reads the pack, appends to a local file, and exits. It opens no port
+and makes no network request. A `WebFetch` is judged by its URL and is never
+fetched by PRAE. For credential checks the gate reads the file the agent is
+about to read, in its own process, and only the finding (type, line,
+confidence) reaches the ledger.
+
+## 6. Limits, stated plainly
+
+- **A hook that cannot start does not block, on current Claude Code.** In
+  enforce mode, PRAE refuses whenever it runs and fails: a bad pack, an
+  unwritable ledger, an exception, its own 3 s lock deadline, or broken
+  input. Before Claude Code 2.1.295, though, a hook that cannot start at all
+  (node or the checkout moved) or that hits Claude Code's 10 s timeout lets
+  the call through. This was checked on 2.1.233. Enforce writes
+  `onFailure: "block"`, which Claude Code 2.1.295 and later honour, and
+  which 2.1.233 ignores.
+- **The shell is judged by its command line, not by its effect.** The baseline
+  stops `Read` of `.env`, but `cat .env` in `Bash` is a different call, and
+  no path rule sees it. Write shell rules (`command`) for the programs you care
+  about. PRAE does not yet screen tool output in Claude Code. A `PostToolUse`
+  hook can only replace output in each tool's exact output shape, which this
+  release does not take on.
+- **PRAE's own files are protected only against plain attempts.** Writes to the
+  pack, the ledger and the hook settings are refused (`PRAE-SELF`), and so are
+  reads of the signing key. Shell commands that name the pack, the settings or
+  the key are refused too, even read-only ones such as `wc -c <pack>`. But the agent runs as you. A shell can spell a path
+  in ways no string check sees, so a determined agent with `Bash` can still
+  edit them. An edited ledger breaks its chain and its signatures. A wholesale
+  rewrite by someone who holds the key needs an external checkpoint
+  (`prae checkpoint`) to catch.
+- **What the hook never sees.** Files you attach with `@` in a prompt are read
+  without a tool call, so no hook fires. Managed settings can switch user hooks
+  off (`allowManagedHooksOnly`, `disableAllHooks`).
+- **Coverage depends on knowing what a tool does.** Built-in tools map to
+  capabilities by name. MCP tools map by their tool name: the reference
+  `filesystem` and `fetch` servers' tools, and `prae mcp`'s own, are
+  recognised. Any other MCP tool is recorded and matched only by rules that
+  name the tool. `WebSearch` has a query, not a URL, so host rules do not
+  apply to it. A path that only appears inside an array (for example
+  `read_multiple_files`) is not path-checked.
+- **What happens after a hold is not recorded.** The row says the call was
+  held (`ask`). Whether you then approved it in the prompt is not written
+  back, because a `PreToolUse` hook gets no outcome. The report lists every
+  enforced hold under "awaiting human".
+- **The agent's own account is not evidence.** In the verification runs the
+  model twice reported a refused call as having run. The ledger, Claude
+  Code's `permission_denials` and the file system agreed with each other, and
+  they are what to read.
+- **Budgets cost a ledger read.** A pack with a `count` rule makes each call
+  count this session's earlier rows in the ledger. Packs without one never
+  read the ledger.
+- **Latency.** Each tool call starts one node process. Measured on an M-series
+  Mac, the built `lib/bin.js` took 30 ms at p50 and 34 ms at p95. Run from
+  `src/bin.ts` with Node's type stripping, it took 60 ms at p50 and 64 ms at
+  p95. A bare `node -e 0` takes 20 ms on the same machine.

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

@@ -272,6 +272,28 @@ function withinAny(path, globs) {
 	return globs.some((glob) => within(path, glob));
 }
 /**
+* An absolute path under `cwd`, rewritten as the workspace-relative path a
+* pack's `./` globs speak about; anything else comes back as written.
+*
+* A model is free to name a workspace file by its absolute path — the first
+* real agent run through the gate did exactly that for its first three
+* reads — and a scope rule written as `outside: ["./src/**"]` must decide
+* that file by where it is, not by how it was spelled. The anchoring in
+* {@link within} is right to keep `/etc/hosts` out of `./**`; this is the
+* other half, applied by an adapter that knows the session's directory.
+* A path that climbs out of `cwd` with `..` stays absolute, so it stays
+* outside.
+*/
+function relativeTo(path, cwd) {
+	const target = normalize(path);
+	const base = normalize(cwd);
+	if (!target.absolute || !base.absolute || target.escaped) return path;
+	if (base.segments.length > target.segments.length) return path;
+	if (!base.segments.every((s, i) => s === target.segments[i])) return path;
+	const rest = target.segments.slice(base.segments.length);
+	return rest.length === 0 ? "." : `./${rest.join("/")}`;
+}
+/**
 * 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" —
@@ -496,4 +518,4 @@ function evaluate(pack, facts) {
 }
 
 //#endregion
-export { hostOf as n, withinAny as r, evaluate as t };
+export { withinAny as a, relativeTo as i, PATH_ARGS as n, segments as o, hostOf as r, evaluate as t };

package/lib/frameworks-BgZHGKiH.js

@@ -0,0 +1,118 @@
+//#region ../kernel/src/frameworks.ts
+const FRAMEWORKS = {
+	"owasp-llm-top-10-2026": {
+		name: "OWASP Top 10 for LLM Applications — 2026",
+		short: "OWASP LLM 2026",
+		controls: {
+			LLM01: {
+				name: "Prompt Injection",
+				summary: "Instructions in a prompt or in retrieved content alter what the model does."
+			},
+			LLM02: {
+				name: "Sensitive Information Disclosure",
+				summary: "Credentials, personal data or proprietary content reach the model or its output."
+			},
+			LLM03: {
+				name: "Excessive Agency",
+				summary: "The model can take actions, or holds permissions, beyond what its task needs."
+			},
+			LLM04: {
+				name: "Supply Chain",
+				summary: "A compromised model, dataset, plugin or dependency enters the application."
+			},
+			LLM05: {
+				name: "Data and Model Poisoning",
+				summary: "Training, fine-tuning or embedding data is manipulated to change behaviour."
+			},
+			LLM06: {
+				name: "Unbounded Consumption",
+				summary: "The application permits resource use without a limit, exhausting budget or service."
+			},
+			LLM07: {
+				name: "Misinformation",
+				summary: "The model produces false or misleading content that is acted on as if true."
+			},
+			LLM08: {
+				name: "Hidden Context Exposure",
+				summary: "System prompts, hidden instructions or internal context are revealed."
+			},
+			LLM09: {
+				name: "Vector and Embedding Weaknesses",
+				summary: "Retrieval stores are manipulated or leak across tenants and permissions."
+			},
+			LLM10: {
+				name: "Improper Output Handling",
+				summary: "Model output is passed to downstream systems without validation."
+			}
+		}
+	},
+	"owasp-agentic-top-10-2026": {
+		name: "OWASP Top 10 for Agentic Applications — 2026",
+		short: "OWASP Agentic 2026",
+		controls: {
+			ASI01: {
+				name: "Agent Goal Hijack",
+				summary: "Untrusted input redirects what the agent is trying to do, turning its objectives against its owner."
+			},
+			ASI02: {
+				name: "Tool Misuse and Exploitation",
+				summary: "A legitimate tool the agent already holds is turned to an attacker's ends."
+			},
+			ASI03: {
+				name: "Identity and Privilege Abuse",
+				summary: "The agent's own authority, credentials or delegated access is inherited or escalated."
+			},
+			ASI04: {
+				name: "Agentic Supply Chain",
+				summary: "A poisoned tool, model, plugin, skill or dependency is trusted before the agent runs."
+			},
+			ASI05: {
+				name: "Unexpected Code Execution",
+				summary: "The agent's output reaches something that runs it: a shell, an interpreter, a parser."
+			},
+			ASI06: {
+				name: "Memory and Context Poisoning",
+				summary: "Corrupted memory or retrieved context persists across sessions and steers future reasoning."
+			},
+			ASI07: {
+				name: "Insecure Inter-Agent Communication",
+				summary: "One agent trusts another's messages by default, so a compromised agent can steer its peers."
+			},
+			ASI08: {
+				name: "Cascading Failures",
+				summary: "A single fault propagates across agents, tools and workflows into system-wide impact."
+			},
+			ASI09: {
+				name: "Human-Agent Trust Exploitation",
+				summary: "Persuasive or misleading agent output moves a person to an unsafe action or approval."
+			},
+			ASI10: {
+				name: "Rogue Agents",
+				summary: "A compromised, misaligned or drifting agent keeps operating in unintended ways."
+			}
+		}
+	}
+};
+/**
+* Every framework control a rule cites, resolved to names.
+*
+* A pack that parsed cites only ids the registry knows, so the lookups here
+* cannot miss; the fallbacks exist for a `Rule` built by hand in code.
+*/
+function cite(rule) {
+	const out = [];
+	for (const [framework, controls] of Object.entries(rule.frameworks ?? {})) {
+		const known = FRAMEWORKS[framework];
+		for (const control of controls) out.push({
+			framework,
+			frameworkName: known?.name ?? framework,
+			frameworkShort: known?.short ?? framework,
+			control,
+			controlName: known?.controls[control]?.name ?? control
+		});
+	}
+	return out;
+}
+
+//#endregion
+export { cite as n, FRAMEWORKS as t };