@letterblack/lbe-exec 1.2.2 → 1.2.3

package/README.md

@@ -1,26 +1,176 @@
 # @letterblack/lbe-exec
 
-Local host-signed execution for LetterBlack LBE.
+**Local-first execution governance for AI agents.**
 
-This package is the trusted, in-process controller layer. It accepts simple
-requests, creates the timestamp/nonce/signature envelope locally, validates it
-through the bundled WASM runtime, and executes approved file or allowlisted
-shell operations inside the configured project root.
+Every action any agent proposes — file write, shell command, anything — passes
+through a local validation gate before it can execute. One SDK, any agent,
+zero cloud dependency.
+
+---
+
+## The problem
+
+AI agents are capable. They can write files, invoke tools, and change state —
+and they will, the moment they are given a reason to. The host is the only
+thing standing between a plausible-looking request and irreversible damage.
+
+That is not enough.
+
+`@letterblack/lbe-exec` puts a deterministic local gate between what the agent
+proposes and what the system actually executes — fully in-process, no cloud
+dependency, no daemon required.
+
+---
+
+## How every request travels
+
+![LBE gate sequence — Request flows through Policy, Identity, and Scope gates before reaching Action. A rejected request is routed to denial before it reaches execution.](assets/lbe-gates.png)
+
+Every request the agent produces enters a gate sequence:
+
+**Policy** — does the current project policy allow this action? Deny rules
+always win. If any deny rule matches, the gate closes before any other check
+runs.
+
+**Identity** — is the request signed by a trusted, active key? The executor
+signs every request locally with an Ed25519 key it holds in memory. Expired
+keys, tampered signatures, and replayed nonces are all rejected.
+
+**Scope** — is the target inside the allowed workspace? Paths outside the
+project root, symlink escapes, and commands outside the explicit allowlist
+are blocked regardless of policy.
+
+Only a request that clears all three gates reaches **Action** — the point
+where something is actually written to disk or a command actually runs.
+
+---
+
+## When a request is approved
+
+![Happy path — agent proposes action, identity confirmed, policy approved, governed write executed, audit chain extended, result returned to app.](assets/story-allow.png)
+
+When a request clears every gate:
+
+1. The agent produces an action proposal — intent, target, content.
+2. The executor signs it locally with a host-held Ed25519 key. No key material
+   leaves the process.
+3. The project policy is evaluated. The action is approved.
+4. The write or command executes inside the configured project root.
+5. The audit chain is extended. Every approved action appends a hash-linked
+   entry to `lbe.audit.jsonl` — permanently verifiable, impossible to silently
+   remove.
+6. A structured result is returned: whether it succeeded, which rules matched,
+   and the audit entry identifier.
+
+The application stays in control. The executor does not decide what to do with
+the result — it decides whether the action was permitted and hands the answer
+back.
+
+---
+
+## When a request is blocked
+
+![Deny path — rogue agent bypass attempt, policy gate immediate rejection, shell untouched, filesystem unchanged, immutable audit entry written, final state clean.](assets/story-deny.png)
+
+When a request fails any gate:
+
+1. The agent attempts an action — whether by mistake, misconfiguration,
+   or a deliberate bypass attempt.
+2. The policy gate closes immediately. The request is denied before any adapter
+   is reached.
+3. The shell is untouched. The filesystem is unchanged. Nothing that should not
+   have happened, happened.
+4. The denial is written to the immutable audit log — chain sealed, evidence
+   preserved.
+5. The final state is clean, verifiable, and consistent.
+
+No partial execution. No silent failures. Denial is a first-class outcome, not
+an error.
+
+---
+
+## Policy — who writes the rules
+
+Only the host application writes policy. Agents may propose a rule — the
+proposal is returned as a plain object for the host to review. Until the host
+explicitly accepts and writes it, the proposal has no effect on any gate.
+
+This separation is intentional. An agent that can write its own policy rules
+is an agent that can grant itself permission.
+
+---
+
+## Observer mode — start here
+
+Not ready to block? Start in observer mode. Every request is fully validated
+and logged exactly as it would be in enforcement — but nothing is blocked.
+
+Watch what the agent is doing before you decide what to deny. Your rules take
+effect the moment you switch to enforcement.
+
+```bash
+npx lbe-exec init      # create lbe.policy.json — starts in observer mode
+npx lbe-exec status    # see mode, rule count, audit entry count
+npx lbe-exec enforce   # switch to blocking
+```
+
+---
+
+## What this covers
+
+| Threat | Gate |
+|---|---|
+| Agent writes outside the project root | Scope — path check |
+| Replayed or stale request | Identity — nonce and timestamp |
+| Tampered or expired key | Identity — key lifecycle |
+| Excessive requests | Identity — rate limit |
+| Action not permitted by project policy | Policy — deny-wins evaluation |
+| Unauthorized shell command | Scope — explicit command allowlist |
+
+---
+
+## Install
+
+```bash
+npm install @letterblack/lbe-exec
+npx lbe-exec init
+```
+
+`npx lbe-exec init` scans the project, writes `lbe.policy.json` in observer mode,
+generates `CLAUDE.md` and `.github/copilot-instructions.md` so every AI agent
+automatically discovers and follows governance without the user explaining it,
+and creates `.lbe/AGENT_CONTRACT.md` as a machine-readable contract.
+
+Requires Node.js ≥ 20.9.0.
+
+## Use in agent code
 
 ```js
 import { createLocalExecutor } from '@letterblack/lbe-exec';
 
 const lbe = createLocalExecutor({ rootDir: process.cwd() });
-const preview = await lbe.dryRun({ intent: 'write_file', target: 'report.md', content: 'draft' });
-const result = await lbe.execute({ intent: 'write_file', target: 'report.md', content: 'approved' });
+
+await lbe.writeFile('output/report.md', content);
+await lbe.readFile('src/config.json');
+await lbe.patchFile('src/index.js', patch);
+await lbe.deleteFile('tmp/scratch.txt');
+await lbe.runShell('node', ['scripts/build.js']);
+
+const result = await lbe.writeFile('output/result.md', data);
+// { ok: true, decision: 'allow', executed: true }
+// { ok: false, decision: 'deny', error: { message: '...' } }
 ```
 
-`dryRun()` is strictly non-mutating: it does not create backups, write audit
-records, execute commands, modify files, or change policy.
+No knowledge of the validation pipeline, request format, or policy internals
+required. Every method routes through the full gate sequence and returns a
+structured result.
+
+---
+
+## What ships
 
-Shell execution is denied unless its command is explicitly listed in
-`shell.allowCommands`. File operations are constrained to `rootDir`, including
-against traversal and symlink escapes.
+This package contains the in-process execution controller and the WASM
+validation runtime. It does not contain a hosted service, daemon, or network
+dependency.
 
-Agents may call `policy.proposeRule()`. Only the trusted host/controller should
-call `policy.addRule()`.
+Source code, tests, keys, and runtime state are never included.

package/assets/runtime-boundary.svg

@@ -0,0 +1,36 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="440" viewBox="0 0 960 440" role="img" aria-labelledby="title desc">
+  <title id="title">LetterBlack LBE runtime boundary</title>
+  <desc id="desc">An application sends a serialized request to the local LBE WASM validation runtime, which returns a structured allow, deny, or error decision to the application.</desc>
+  <defs>
+    <linearGradient id="panel" x1="0" x2="1"><stop stop-color="#172033"/><stop offset="1" stop-color="#202d47"/></linearGradient>
+    <linearGradient id="runtime" x1="0" x2="1"><stop stop-color="#3756d6"/><stop offset="1" stop-color="#7356d6"/></linearGradient>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" fill="#8fa3c9"/></marker>
+  </defs>
+  <rect width="960" height="440" rx="24" fill="#0e1524"/>
+  <text x="56" y="65" fill="#f5f8ff" font-family="Arial, sans-serif" font-size="28" font-weight="700">Local validation boundary</text>
+  <text x="56" y="98" fill="#aab9d4" font-family="Arial, sans-serif" font-size="17">The host owns execution. LBE returns a deterministic decision before the host accepts an action.</text>
+
+  <rect x="55" y="165" width="220" height="170" rx="16" fill="url(#panel)" stroke="#405273"/>
+  <text x="165" y="220" text-anchor="middle" fill="#fff" font-family="Arial, sans-serif" font-size="21" font-weight="700">Host application</text>
+  <text x="165" y="254" text-anchor="middle" fill="#b9c7df" font-family="Arial, sans-serif" font-size="15">agent, tool, or service</text>
+  <text x="165" y="286" text-anchor="middle" fill="#7fe1c3" font-family="Arial, sans-serif" font-size="15">serializes request</text>
+
+  <line x1="285" y1="250" x2="402" y2="250" stroke="#8fa3c9" stroke-width="4" marker-end="url(#arrow)"/>
+  <text x="343" y="229" text-anchor="middle" fill="#aab9d4" font-family="Arial, sans-serif" font-size="14">JSON request</text>
+
+  <rect x="415" y="132" width="290" height="236" rx="18" fill="url(#runtime)" stroke="#9a8cff" stroke-width="2"/>
+  <text x="560" y="183" text-anchor="middle" fill="#fff" font-family="Arial, sans-serif" font-size="23" font-weight="700">LBE WASM runtime</text>
+  <line x1="453" y1="205" x2="667" y2="205" stroke="#bfc8ff" opacity=".55"/>
+  <text x="560" y="242" text-anchor="middle" fill="#f0efff" font-family="Arial, sans-serif" font-size="16">schema · timestamp · key lifecycle</text>
+  <text x="560" y="271" text-anchor="middle" fill="#f0efff" font-family="Arial, sans-serif" font-size="16">signature · rate limit · nonce · policy</text>
+  <text x="560" y="319" text-anchor="middle" fill="#d7d1ff" font-family="Arial, sans-serif" font-size="14">local, deterministic validation</text>
+
+  <line x1="718" y1="250" x2="825" y2="250" stroke="#8fa3c9" stroke-width="4" marker-end="url(#arrow)"/>
+  <text x="770" y="229" text-anchor="middle" fill="#aab9d4" font-family="Arial, sans-serif" font-size="14">structured result</text>
+
+  <rect x="838" y="165" width="80" height="170" rx="16" fill="url(#panel)" stroke="#405273"/>
+  <text x="878" y="215" text-anchor="middle" fill="#fff" font-family="Arial, sans-serif" font-size="16" font-weight="700">Host</text>
+  <text x="878" y="249" text-anchor="middle" fill="#7fe1c3" font-family="Arial, sans-serif" font-size="14">allow</text>
+  <text x="878" y="275" text-anchor="middle" fill="#ffadad" font-family="Arial, sans-serif" font-size="14">deny</text>
+  <text x="878" y="301" text-anchor="middle" fill="#ffd28a" font-family="Arial, sans-serif" font-size="14">error</text>
+</svg>