@letterblack/lbe-exec 1.2.7 → 1.2.10

package/README.md

@@ -1,255 +1,258 @@
-# @letterblack/lbe-exec
-
-**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 package, any agent,
-zero cloud dependency, no daemon required.
-
----
-
-## 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.](https://unpkg.com/@letterblack/lbe-exec/assets/lbe-gates.jpg)
-
-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.
-
-```
-[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
-```
-
-The executor signs every request with a host-held key before validation.
-No key material leaves the process.
-
----
-
-## When a request is approved
-
-![Happy path — agent proposes action, identity confirmed, policy approved, governed write executed, audit chain extended, result returned to app.](https://unpkg.com/@letterblack/lbe-exec/assets/story-allow.jpg)
-
-When a request clears every gate:
-
-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 returns: whether it succeeded, which rules matched, and
-   the audit entry identifier.
-
-The application stays in control. The executor 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.](https://unpkg.com/@letterblack/lbe-exec/assets/story-deny.jpg)
-
-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.
-
----
-
-## What this covers
-
-| Threat | Gate |
-|---|---|
-| 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.
-
----
-
-## 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, 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() });
-
-// 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,  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
-  }
-});
-```
-
-### 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
-
-```
-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.
-
-For the raw WASM runtime without a controller, see `@letterblack/lbe-sdk`.
+# @letterblack/lbe-exec
+
+**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 package, any agent,
+zero cloud dependency, no daemon required.
+
+---
+
+## 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.](https://unpkg.com/@letterblack/lbe-exec/assets/lbe-gates.jpg)
+
+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.
+
+```
+[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
+```
+
+The executor signs every request with a host-held key before validation.
+No key material leaves the process.
+
+---
+
+## When a request is approved
+
+![Happy path — agent proposes action, identity confirmed, policy approved, governed write executed, audit chain extended, result returned to app.](https://unpkg.com/@letterblack/lbe-exec/assets/story-allow.jpg)
+
+When a request clears every gate:
+
+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 returns: whether it succeeded, which rules matched, and
+   the audit entry identifier.
+
+The application stays in control. The executor 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.](https://unpkg.com/@letterblack/lbe-exec/assets/story-deny.jpg)
+
+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.
+
+---
+
+## What this covers
+
+| Threat | Gate |
+|---|---|
+| 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.
+
+---
+
+## 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, 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() });
+
+// 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,  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
+  }
+});
+```
+
+### 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
+
+```
+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.jpg        Gate sequence diagram
+assets/story-allow.jpg      Approved-request storyboard
+assets/story-deny.jpg       Blocked-request storyboard
+assets/runtime-boundary.svg Runtime boundary diagram
+assets/lbe-gates.png        Gate sequence diagram (full resolution)
+assets/story-allow.png      Approved-request storyboard (full resolution)
+assets/story-deny.png       Blocked-request storyboard (full resolution)
+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.
+
+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.7",
+  "version": "1.2.10",
   "description": "Local host-signed execution layer for LetterBlack LBE.",
   "type": "module",
   "main": "dist/index.js",