@letterblack/lbe-core 1.3.0

package/Release-README.md

@@ -0,0 +1,339 @@
+# {{PACKAGE_NAME}}
+
+LBE is local execution control for AI agents. It evaluates file and shell
+actions routed through its execution boundary and records local evidence.
+It is not an AI model, IDE, full OS sandbox, or cloud monitor.
+
+## Setup
+
+```bash
+npm install {{PACKAGE_NAME}}
+npx lbe init
+npx lbe status
+npx lbe logs
+npx lbe proof --public
+npx lbe open-state
+```
+
+State is stored locally in a central per-user folder, keyed by workspace ID.
+In v1.3, `.lbe/events.jsonl` remains local fallback truth and is imported once
+without changing the original file. Proof uses intent, target, file index, LBE
+events, and `proof/latest.json`; `--public` redacts sensitive proof details.
+
+LBE controls only actions routed through its execution boundary. Central writes
+are best-effort, logs remain local, and non-inspectable targets may produce
+`WEAK_PROOF`.
+
+---
+
+AI agents are starting to touch real files, terminals, tools, projects, and production workflows.
+
+The risky part is not only what the model thinks.
+
+The risky part is what happens **after the agent decides to act**.
+
+LBE is a local execution boundary for AI agents. It sits between an agent and the workspace, validates the requested action, applies policy, records evidence, and returns a structured allow/deny result before anything reaches the filesystem, terminal, or tool layer.
+
+```text
+Agent wants to act
+        ↓
+LBE validates identity, scope, replay, rate limits, and policy
+        ↓
+allow / deny / error
+        ↓
+Host executes only if LBE approved
+        ↓
+Audit evidence is written locally
+```
+
+No hosted service. No cloud control plane. No remote dependency.
+
+> **Used in production:** LBE is the safety engine inside [Letterblack for After Effects](https://letterblack.net), where AI-generated scripts and automation commands are checked before touching a live creative project.
+
+---
+
+## The problem LBE is built for
+
+A user asks an agent to do one thing:
+
+```text
+"Move the Save button 20px to the right."
+```
+
+The agent may correctly understand the task, but still attempt extra actions:
+
+```text
+edit settings-panel.jsx       expected
+edit navbar.jsx               unexpected
+edit sidebar.jsx              unexpected
+run shell command             unexpected
+```
+
+Most systems treat this as:
+
+```text
+agent output → approval dialog → execution
+```
+
+LBE treats approval as only one signal.
+
+```text
+user claim      is not truth
+agent claim     is not truth
+approval dialog is not truth
+runtime evidence is truth
+```
+
+LBE asks a different question before execution:
+
+```text
+Is this action authentic?
+Is it fresh, or replayed?
+Is the requester allowed?
+Is the target inside scope?
+Does policy allow it?
+Can the result be audited?
+```
+
+That is the execution boundary.
+
+---
+
+## What LBE is not
+
+LBE is **not** another AI agent framework.
+
+It does not replace:
+
+- the model
+- the IDE
+- the chat UI
+- Git
+- human review
+- an OS sandbox
+
+Git can revert source history after a change. Approval dialogs ask a human for permission. LBE exists earlier in the chain: between the agent's proposed action and the actual execution path.
+
+---
+
+## What LBE does
+
+| Need | What LBE provides |
+|---|---|
+| Stop blind execution | Local allow/deny gate before execution |
+| Avoid random tool access | Structured action proposal instead of direct tool calls |
+| Verify requester identity | Signed requests, trusted keys, nonce checks |
+| Block stale/replayed actions | Timestamp and single-use nonce validation |
+| Enforce project rules | Local deny-wins policy evaluation |
+| Understand what happened | Hash-linked audit log |
+| Integrate without cloud | Runs locally through SDK / CLI / runtime package |
+
+---
+
+## Package choice
+
+| I want… | Package |
+|---|---|
+| LBE to handle file writes and shell commands for me | `@letterblack/lbe-exec` |
+| Just the allow/deny decision — my app executes after approval | `{{PACKAGE_NAME}}` |
+
+This package documents the SDK boundary. For the in-process controller that performs governed file and shell operations, use `@letterblack/lbe-exec`.
+
+---
+
+## Install
+
+```bash
+npm install {{PACKAGE_NAME}}
+```
+
+Requires Node.js >= 20.9.0.
+
+For the full local execution controller:
+
+```bash
+npm install @letterblack/lbe-exec
+npx lbe init
+```
+
+---
+
+## Quick start: decision boundary
+
+```js
+import { execute } from '{{PACKAGE_NAME}}';
+
+const request = {
+  version: '1.0',
+  request_id: 'req-001',
+  timestamp: Math.floor(Date.now() / 1000),
+  actor: { id: 'agent:local', role: 'agent' },
+  intent: {
+    type: 'command',
+    name: 'write_file',
+    payload: { target: 'out.txt' }
+  },
+  context: {
+    workspace: process.cwd(),
+    env: {},
+    history: []
+  },
+  constraints: {
+    policy_mode: 'strict',
+    timeout_ms: 5000
+  },
+  auth: {
+    signature: '<host-signed>',
+    nonce: '<unique-per-request>'
+  }
+};
+
+const result = JSON.parse(execute(JSON.stringify(request)));
+
+if (result.ok && result.decision === 'allow') {
+  // Host executes the action here.
+  // The SDK decides; your host acts.
+}
+```
+
+`execute(input: string): string` accepts JSON and returns JSON. The SDK validates and returns a decision. It does not perform the file write or shell command itself.
+
+---
+
+## Observer mode
+
+Not ready to block yet? Start in observer mode.
+
+Observer mode validates and logs requests as if enforcement were active, but does not block. This lets you see what the agent is doing before deciding what to deny.
+
+```bash
+npx lbe init      # create project-local policy and key state
+npx lbe observe   # advisory / log-only mode
+npx lbe enforce   # blocking mode
+```
+
+---
+
+## CLI reference
+
+| Command | Purpose |
+|---|---|
+| `npx lbe init` | Create project-local policy and key state |
+| `npx lbe policy-add` | Add a rule to the active policy |
+| `npx lbe observe` | Set advisory / log-only mode |
+| `npx lbe enforce` | Set blocking mode |
+| `npx lbe run` | Validate and execute a proposal from `--in <file>` |
+| `npx lbe verify` | Validate a proposal without executing |
+| `npx lbe dryrun` | Validate and simulate without executing |
+| `npx lbe health` | Check required files are present and readable |
+| `npx lbe audit-verify` | Verify the audit log hash chain |
+
+---
+
+## Gate pipeline
+
+![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 enters the same local gate pipeline. A failure at any gate returns a structured denial. The remaining gates are not evaluated.
+
+```text
+[1] Schema         required fields and structural validity
+        ↓
+[2] Timestamp      permitted clock-skew window
+        ↓
+[3] Key lifecycle  trusted key, active, not expired
+        ↓
+[4] Signature      Ed25519 request authenticity
+        ↓
+[5] Rate limit     per-requester sliding-window limit
+        ↓
+[6] Nonce          single-use replay protection
+        ↓
+[7] Policy         configured authorization, deny-wins
+        ↓
+allow / deny / error
+```
+
+The WASM runtime owns the gate decisions. The host receives the decision and acts on it.
+
+---
+
+## Approved path
+
+![Happy path — agent proposes action, identity confirmed, policy approved, governed write executed, audit chain extended, result returned to app.](assets/story-allow.png)
+
+1. Agent or host creates a signed action proposal.
+2. LBE verifies request structure, identity, freshness, nonce, rate limit, and policy.
+3. The result is `allow`.
+4. The host executes the write or command inside the allowed workspace.
+5. A hash-linked audit entry records the decision and result.
+6. The host receives structured evidence: decision, matched rules, result, and audit identifier.
+
+---
+
+## Blocked path
+
+![Deny path — policy rejection before a governed action, shell untouched, filesystem unchanged, audit entry written, final state clean.](assets/story-deny.png)
+
+1. Agent attempts an action that is malformed, stale, replayed, unsigned, too frequent, or not allowed by policy.
+2. LBE returns `deny` before any adapter is reached.
+3. The shell is untouched.
+4. The filesystem is unchanged.
+5. The denial is written to the audit chain.
+
+Denial is not a crash. It is a valid controlled outcome.
+
+---
+
+## What this covers
+
+| Threat / failure mode | Gate / mechanism |
+|---|---|
+| Malformed or incomplete request | Schema |
+| Stale request | Timestamp |
+| Replayed request | Nonce |
+| Unknown or expired key | Key lifecycle |
+| Tampered request | Signature |
+| Request burst from one actor | Rate limit |
+| Action not permitted by project rules | Policy |
+| Agent writing outside project root | Host scope check after decision |
+| Later dispute over what happened | Hash-linked audit log |
+
+---
+
+## What ships
+
+```text
+dist/index.js               WebAssembly runtime loader and execute()
+dist/cli.js                 Local CLI, npx lbe
+dist/lbe_engine.wasm        Verified 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
+```
+
+At load time, the runtime verifies `lbe_engine.wasm` against `wasm.lock.json`. A missing, modified, or swapped binary fails before any request is processed.
+
+Source code, controller implementation, adapters, tests, keys, and runtime state are not included in this package.
+
+---
+
+## Limits
+
+LBE validates requests routed through its runtime. It is not a kernel-level sandbox and does not provide OS process isolation, network-egress control, multi-tenant separation, or a hosted control plane.
+
+If a tool writes directly to disk outside the LBE execution boundary, that write
+is outside this package's control. Place LBE on the execution path between the
+agent and the tools it uses.
+
+---
+
+## One-sentence summary
+
+LBE does not make the agent smarter. It makes the agent's execution path controlled, evidence-backed, and locally auditable.