@letterblack/lbe-core 1.3.4 → 1.3.6

package/release/exec-types.d.ts

@@ -0,0 +1,50 @@
+export interface LBEResult {
+  ok: boolean;
+  decision: 'allow' | 'deny' | 'observe';
+  executed: boolean;
+  dryRun: boolean;
+  error?: { code: string; message: string; recoverable: boolean };
+  matchedRules?: string[];
+  auditId?: string;
+  rollback?: { available: boolean; performed: boolean; backupId?: string };
+}
+
+export interface LBEPolicyRule {
+  effect: 'allow' | 'deny';
+  type: 'path' | 'command';
+  pattern: string;
+  from: string;
+}
+
+export interface LocalExecutor {
+  rootDir: string;
+
+  // High-level API — use these in agent code
+  writeFile(target: string, content: string): Promise<LBEResult>;
+  readFile(target: string): Promise<LBEResult>;
+  patchFile(target: string, content: string): Promise<LBEResult>;
+  deleteFile(target: string): Promise<LBEResult>;
+  runShell(cmd: string, args?: string[], opts?: { cwd?: string; timeoutMs?: number; maxOutputBytes?: number }): Promise<LBEResult>;
+
+  // Policy management
+  policy: {
+    read(): unknown;
+    proposeRule(rule: LBEPolicyRule): unknown;
+    addRule(rule: LBEPolicyRule): unknown;
+  };
+
+  // Audit
+  audit: { verify(): unknown };
+
+  // Low-level — for advanced / non-standard use only
+  validate(request: unknown): Promise<LBEResult>;
+  dryRun(request: unknown): Promise<LBEResult>;
+  execute(request: unknown): Promise<LBEResult>;
+}
+
+export function createLocalExecutor(options?: {
+  rootDir?: string;
+  keyId?: string;
+  mode?: 'observe' | 'enforce';
+  shell?: { allowCommands?: string[]; denyCommands?: string[]; maxRequests?: number };
+}): LocalExecutor;

package/release-exec/LICENSE

@@ -0,0 +1 @@
+SEE LICENSE IN LICENSE

package/release-exec/README.md

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

@@ -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>