@letterblack/lbe-exec 1.2.3 → 1.2.5

package/README.md

@@ -2,9 +2,12 @@
 
 **Local-first execution governance for AI agents.**
 
+> Use `@letterblack/lbe-exec` if you want LBE to control agent actions in a workspace.
+> Use `@letterblack/lbe-sdk` if you only need validation decisions inside your own tool.
+
 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.
+through a local validation gate before it can execute. One package, any agent,
+zero cloud dependency, no daemon required.
 
 ---
 
@@ -26,22 +29,29 @@ dependency, no daemon required.
 
 ![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.
+Every request the agent produces enters a 7-gate pipeline. A failure at any
+gate returns a structured denial — the remaining gates are not evaluated.
 
-**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.
+```
+[1] Schema         required fields and structural validity
+        ↓
+[2] Timestamp      permitted clock-skew window (±10 minutes)
+        ↓
+[3] Key lifecycle  trusted key, active, not expired
+        ↓
+[4] Signature      Ed25519 request authenticity (signed locally, no network)
+        ↓
+[5] Rate limit     per-requester sliding-window limit
+        ↓
+[6] Nonce          single-use replay protection
+        ↓
+[7] Policy         configured authorization (deny-wins)
+        ↓
+  allow / deny / error — structured result returned to host
+```
 
-Only a request that clears all three gates reaches **Action** — the point
-where something is actually written to disk or a command actually runs.
+The executor signs every request with a host-held key before validation.
+No key material leaves the process.
 
 ---
 
@@ -51,20 +61,17 @@ where something is actually written to disk or a command actually runs.
 
 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.
+1. The agent calls a convenience method — `lbe.writeFile()`, `lbe.runShell()`, etc.
+2. The executor constructs and signs the request locally with a host-held Ed25519 key.
+3. All seven gates pass. The project policy approves the action.
 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.
+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 returns: 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.
+The application stays in control. The executor decides whether the action was
+permitted and hands the answer back.
 
 ---
 
@@ -100,32 +107,27 @@ 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 |
+| Agent writes outside the project root | Scope — sandbox 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 |
+| Injected payload (eval, exec, __proto__) | Content scan before pipeline |
+
+---
+
+## 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.
 
 ---
 
@@ -136,13 +138,15 @@ 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.
+`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, and creates
+`.lbe/AGENT_CONTRACT.md` as a machine-readable contract.
 
 Requires Node.js ≥ 20.9.0.
 
+---
+
 ## Use in agent code
 
 ```js
@@ -150,27 +154,102 @@ import { createLocalExecutor } from '@letterblack/lbe-exec';
 
 const lbe = createLocalExecutor({ rootDir: process.cwd() });
 
+// Every call routes through the full 7-gate pipeline
 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']);
 
+// Result shape
 const result = await lbe.writeFile('output/result.md', data);
-// { ok: true, decision: 'allow', executed: true }
-// { ok: false, decision: 'deny', error: { message: '...' } }
+// { ok: true,  decision: 'allow', executed: true,  auditId: '...' }
+// { ok: false, decision: 'deny',  executed: false, error: { code, message } }
+```
+
+No knowledge of the pipeline, request format, or policy internals required.
+All signing, validation, and auditing happens automatically.
+
+### Options
+
+```js
+const lbe = createLocalExecutor({
+  rootDir: process.cwd(),          // sandbox root — no writes escape this path
+  mode: 'observe',                 // 'observe' (log only) or 'enforce' (block)
+  shell: {
+    allowCommands: ['node', 'npm'], // only these commands may run
+    denyCommands:  ['rm', 'curl'],  // always blocked regardless of policy
+    maxRequests:   20               // per-minute shell rate limit
+  }
+});
 ```
 
-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.
+### Policy management
+
+```js
+// Propose a rule — returns an object for the host to review, writes nothing
+const proposal = lbe.policy.proposeRule({
+  effect: 'deny',
+  type: 'path',
+  pattern: 'secrets/**',
+  from: 'agent: these files should not be modified'
+});
+
+// Host accepts and writes the rule
+lbe.policy.addRule(proposal);
+
+// Read current policy
+const policy = lbe.policy.read();
+
+// Verify the audit chain has not been tampered with
+lbe.audit.verify();
+```
+
+---
+
+## CLI reference
+
+```bash
+npx lbe-exec init      # create lbe.policy.json in observer mode
+npx lbe-exec status    # show mode, rule count, and audit entry count
+npx lbe-exec enforce   # switch to blocking
+npx lbe-exec observe   # switch back to advisory
+npx lbe-exec policy    # list active rules
+```
+
+| Command | Purpose |
+|---|---|
+| `npx lbe-exec init` | Bootstrap governance — policy, keys, agent files |
+| `npx lbe-exec status` | Show mode, rule count, audit entry count |
+| `npx lbe-exec policy` | List active rules |
+| `npx lbe-exec observe` | Set advisory (log-only) mode |
+| `npx lbe-exec enforce` | Set blocking mode |
+| `npx lbe-exec execute` | Pipe a JSON request from stdin or `--input <file>` |
 
 ---
 
 ## What ships
 
-This package contains the in-process execution controller and the WASM
-validation runtime. It does not contain a hosted service, daemon, or network
-dependency.
+```
+dist/index.js          In-process executor — createLocalExecutor()
+dist/cli.js            Local CLI (npx lbe-exec)
+dist/lbe_engine.wasm   Verified WASM runtime binary
+dist/wasm.lock.json    Runtime integrity lock (SHA-256 of wasm binary)
+assets/lbe-gates.png   Gate sequence diagram
+assets/story-allow.png Approved-request storyboard
+assets/story-deny.png  Blocked-request storyboard
+assets/runtime-boundary.svg  Runtime boundary diagram
+types.d.ts             TypeScript declarations
+```
+
+Source code, tests, keys, and runtime state are not included.
+
+---
+
+## Limits
+
+This package governs actions routed through its executor. It does not provide
+kernel-level process isolation, network-egress control, multi-tenant separation,
+or a hosted control plane.
 
-Source code, tests, keys, and runtime state are never included.
+For the raw WASM runtime without a controller, see `@letterblack/lbe-sdk`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letterblack/lbe-exec",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "Local host-signed execution layer for LetterBlack LBE.",
   "type": "module",
   "main": "dist/index.js",