@letterblack/lbe-core 1.3.2 → 1.3.4

package/release-exec/README.md

@@ -1,215 +0,0 @@
-# @letterblack/lbe-exec
-
-LBE puts a local policy gate between what an AI agent proposes and what the system actually executes. Every action — file write, shell command, anything — is validated locally before it runs. No cloud service. No daemon.
-
-`lbe-exec` is the full in-process controller. It handles signing, execution, and auditing for you — your agent code just calls `lbe.writeFile()` or `lbe.runShell()`.
-
-> **Used in production:** LBE is the safety engine inside [Letterblack for After Effects](https://letterblack.net) — every AI-generated script and automation command passes through it before touching a live project.
-
----
-
-## Which package do you need?
-
-| I want… | Package |
-|---|---|
-| LBE to handle file writes and shell commands for me (full controller) | `@letterblack/lbe-exec` ← you are here |
-| Just the allow/deny decision — I'll execute it myself | `@letterblack/lbe-sdk` |
-
----
-
-## Install
-
-```bash
-npm install @letterblack/lbe-exec
-npx lbe-exec init
-```
-
-`npx lbe-exec init` creates `lbe.policy.json` in observer mode, generates `CLAUDE.md` and `.github/copilot-instructions.md` so AI agents automatically discover and follow governance, and writes `.lbe/AGENT_CONTRACT.md` as a machine-readable contract.
-
-Requires Node.js ≥ 20.9.0.
-
----
-
-## Quick start
-
-```js
-import { createLocalExecutor } from '@letterblack/lbe-exec';
-
-const lbe = createLocalExecutor({ rootDir: process.cwd() });
-
-// Every call routes through the full 7-gate pipeline automatically
-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 — same for every method
-// { 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
-
-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.
-
-```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();
-```
-
----
-
-## 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.
-
-```bash
-npx lbe-exec init      # create lbe.policy.json in observer mode
-npx lbe-exec enforce   # switch to blocking
-npx lbe-exec observe   # switch back to advisory
-```
-
----
-
-## CLI reference
-
-| 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>` |
-
----
-
-## How the gate pipeline works
-
-![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 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)
-
-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.
-
----
-
-## 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)
-
-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.
-4. The denial is written to the immutable audit log — chain sealed, evidence preserved.
-
-No partial execution. No silent failures. Denial is a first-class outcome, not an error.
-
----
-
-## 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 |
-
----
-
-## 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/release-exec/assets/runtime-boundary.svg

@@ -1,36 +0,0 @@
-<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>