@letterblack/lbe-sdk

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.

Used in production: LBE is the safety engine inside Letterblack for After Effects — 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 | | Just the allow/deny decision — I'll execute it myself | @letterblack/lbe-sdk ← you are here |

Install

npm install @letterblack/lbe-sdk

Requires Node.js ≥ 20.9.0.

Quick start

import { execute } from '@letterblack/lbe-sdk';

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)));
// Approved:  { ok: true,  decision: 'allow', ... }
// Blocked:   { ok: false, decision: 'deny',  error: { stage, message } }

execute(input: string): string — accepts JSON, returns JSON. The runtime validates and returns a decision. The host acts on the decision.

Request fields

| Field | Required | Description | |---|---:|---| | version | Yes | "1.0" | | request_id | Yes | Caller-supplied unique identifier | | timestamp | Yes | Unix timestamp in seconds | | actor | Yes | { id, role } — identity of the requesting agent | | intent | Yes | { type, name, payload } — what the agent wants to do | | context | Yes | Workspace path and caller context | | constraints | Yes | policy_mode and timeout_ms | | auth | Yes | Host-supplied signature and nonce |

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.

npx lbe init      # create lbe.policy.json in observer mode
npx lbe enforce   # switch to blocking
npx lbe observe   # switch back to advisory

CLI reference

| Command | Purpose | |---|---| | npx lbe init | Create project-local policy and key state in observer mode | | 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 all required files are present and readable | | npx lbe audit-verify | Verify the audit log hash chain |

How the gate pipeline works

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
        ↓
[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 WASM runtime owns all gate decisions. Your host receives the decision and acts on it. Nothing executes inside the runtime.

When a request is approved

1. The agent produces a signed action proposal.
2. Identity is confirmed against a locally held key — no network call required.
3. The project policy is evaluated. The action is approved.
4. The host executes the write or command inside the allowed workspace.
5. The audit chain is extended — every approved action appends a hash-linked entry to the local log, 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. @letterblack/lbe-sdk decides whether the action was permitted and hands the answer back. It does not execute for you.

When a request is blocked

1. The agent attempts an action — whether by mistake, misconfiguration, or a deliberate bypass attempt.
2. The policy gate closes immediately. The WASM runtime stamps the request 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 | |---|---| | Malformed or incomplete request | Schema | | Stale or replayed request | Timestamp + Nonce | | Tampered or expired key | Key lifecycle + Signature | | Excessive requests from one actor | Rate limit | | Action not permitted by project policy | Policy — deny-wins | | Agent writing outside project root | Scope check in host after decision |

What ships

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.

Limits

This package validates requests routed through its runtime. It does not provide kernel-level process isolation, network-egress control, multi-tenant separation, or a hosted control plane.

For an in-process controller with file operations, shell, and policy management built in, see @letterblack/lbe-exec.