@letterblack/lbe-sdk 0.4.0 → 0.4.2

package/README.md

@@ -1,34 +1,73 @@
-# @letterblack/lbe-sdk
+<div align="center">
 
-Lockstep Boundary Engine SDK for local-first AI execution governance.
+<img src="https://raw.githubusercontent.com/Letterblack0306/letterblack-Lockstep-boundry-engine/main/assets/logo.svg" width="100" alt="LetterBlack logo"/>
 
-Sandboxed writes. Workspace context. Audit. Rollback. MCP access.
+# `@letterblack/lbe-sdk`
 
-Everything runs on your machine. No hosted service is required.
+**Local-first AI execution governance.**  
+Sandboxed writes · Audit · Rollback · MCP · WASM engine
 
-## Install
+[![npm](https://img.shields.io/npm/v/@letterblack/lbe-sdk?color=black&label=npm)](https://www.npmjs.com/package/@letterblack/lbe-sdk)
+[![license](https://img.shields.io/badge/license-Commercial-red)](./LICENSE)
+[![node](https://img.shields.io/node/v/@letterblack/lbe-sdk?color=darkgreen)](https://nodejs.org)
+[![engine](https://img.shields.io/badge/engine-WASM-blueviolet)](./runtime/lbe_engine.wasm)
 
-```bash
-npm install @letterblack/lbe-sdk
-```
+</div>
+
+---
+
+## What LBE is
+
+LBE is a local SDK that enforces a cryptographic policy gate between an AI agent and your system. It installs as an npm package, runs entirely in your process, and requires no external service, cloud connection, or hosted API. Every action an agent proposes passes through the validation engine before anything executes. Nothing phones home.
+
+---
+
+## The problem
+
+AI agents can write files, run shell commands, and modify your system — and most frameworks let them do it without any gate.
+
+There is no policy asking "is this agent allowed to do this?" There is no audit trail recording what happened. There is no rollback if it goes wrong. If an agent overwrites a config file, deletes the wrong directory, or runs a command it shouldn't — you find out after the fact, with no record and no recovery.
+
+LBE is the enforcement layer that sits between an AI agent and your system. Every action the agent proposes must pass a cryptographic validation pipeline before anything executes. If it fails — nothing runs, nothing changes, and the denial is logged. If it passes — the action executes under a governed adapter, a hash-chained audit entry is written, and rollback state is saved.
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/Letterblack0306/letterblack-Lockstep-boundry-engine/main/assets/storyboard-deny.png" width="680" alt="Rogue agent blocked: bypass attempt denied, shell untouched, filesystem unchanged, audit sealed"/>
+</div>
+
+---
 
-Requires Node.js 20.9.0 or newer.
+## How it works
 
-## Initialize
+<div align="center">
+<img src="https://raw.githubusercontent.com/Letterblack0306/letterblack-Lockstep-boundry-engine/main/assets/architecture.svg" width="680" alt="LBE SDK architecture diagram"/>
+</div>
 
+Every action proposal from an agent is validated across 7 stages — schema, timestamp, key lifecycle, Ed25519 signature, rate limit, nonce deduplication, and policy — before the adapter executes anything. All 7 stages run inside the compiled WASM engine. A denial at any stage stops execution immediately and writes an audit entry. No cloud. No data leaves the machine.
+
+---
+
+## Install
+
+**PowerShell**
+```powershell
+npm install "@letterblack/lbe-sdk"
+```
+
+**bash / zsh / cmd**
 ```bash
-npx lbe init
+npm install @letterblack/lbe-sdk
 ```
 
-Initializes local governance settings for the current workspace so agents can
-operate inside explicit project boundaries.
+> Requires Node.js 20.9.0+
 
-Run once per workspace. Re-run when the workspace structure changes.
+---
 
 ## Quick Start
 
+### Sandbox
+
 ```js
-import { sandbox } from '@letterblack/lbe-sdk';
+import { sandbox } from "@letterblack/lbe-sdk";
 
 const sb = sandbox('./workspace');
 
@@ -36,32 +75,42 @@ await sb.write('output.txt', 'Hello\n');
 const text = await sb.read('output.txt');
 ```
 
-`sandbox()` routes reads and writes through the workspace root you provide.
-Use it as the boundary for all agent-facing file operations.
-
-## Audit and Rollback
+### With audit + rollback
 
 ```js
-import { sandbox } from '@letterblack/lbe-sdk';
+import { sandbox } from "@letterblack/lbe-sdk";
 
 const sb = sandbox('./workspace', {
     audit: true,
     rollback: true
 });
 
-await sb.write('output.txt', 'governed write\n');
+await sb.write('report.md', '# Report\n');
 ```
 
-Audit records and rollback state are stored locally. Use workspace-scoped
-state when your team shares governance artifacts:
+### Full SDK client
 
 ```js
-const sb = sandbox('./workspace', { state: 'workspace' });
+import { createLBE } from "@letterblack/lbe-sdk";
+
+const lbe = createLBE({ rootDir: process.cwd() });
+
+const result = await lbe.execute({
+    actor: 'agent:sdk',
+    intent: 'write_file',
+    target: './output/report.md',
+    content: '# Report\n'
+});
+
+console.log(result.ok);    // true
+console.log(result.stage); // 'ok'
 ```
 
+---
+
 ## MCP Server
 
-Add LBE governance to any MCP-compatible AI host:
+Add LBE governance to any MCP-compatible AI host in one config block:
 
 ```json
 {
@@ -74,117 +123,95 @@ Add LBE governance to any MCP-compatible AI host:
 }
 ```
 
-### Agent Tools
+### Agent tools
 
 | Tool | Purpose |
 |---|---|
-| `lbe_workspace_context` | Fetch local workspace constraints before planning actions |
-| `lbe_write_file` | Governed write with backup and rollback support |
+| `lbe_workspace_context` | Fetch workspace constraints before planning |
+| `lbe_write_file` | Governed write with backup + rollback |
 | `lbe_read_file` | Governed read |
-| `lbe_patch_file` | Governed append/patch |
-| `lbe_shell_command` | Governed command execution through the configured allowlist |
+| `lbe_patch_file` | Governed append / patch |
+| `lbe_shell_command` | Governed command via configured allowlist |
 | `lbe_health` | Verify local SDK readiness |
 
-## Programmatic Use
-
-Use `createLBE()` for full SDK integration:
-
-```js
-import { createLBE } from '@letterblack/lbe-sdk';
-
-const lbe = createLBE({
-    rootDir: process.cwd()
-});
+---
 
-const result = await lbe.execute({
-    actor: 'agent:sdk',
-    intent: 'write_file',
-    target: './output/report.md',
-    content: '# Report\n'
-});
+## CLI
 
-console.log(result.ok);
-console.log(result.stage);
+```bash
+npx lbe init                        # Initialize workspace governance
+npx lbe health                      # Verify runtime readiness
+npx lbe verify --in proposal.json   # Validate a proposal (no execution)
+npx lbe run    --in proposal.json   # Validate + execute
+npx lbe audit-verify                # Verify audit chain integrity
+npx lbe-mcp                         # Start MCP server on stdio
 ```
 
-## Public API
+---
 
-### `sandbox(root, opts?)`
+## Validation pipeline
 
-Creates a governed workspace helper.
+Every execution proposal passes 7 stages inside the compiled WASM engine:
 
-| Option | Default | Description |
-|---|---|---|
-| `audit` | `false` | Record governed operations to the local audit log |
-| `rollback` | `false` | Back up before writes; restore on failure |
-| `state` | `'local'` | State storage: `'local'`, `'workspace'`, or adapter |
-
-### `createLBE(options)`
-
-Creates a full SDK client for application integrations.
+```
+  [1] Schema      — required fields, types, structure
+  [2] Timestamp   — skew tolerance, replay window
+  [3] Key         — lifecycle, expiry, revocation
+  [4] Signature   — Ed25519, RFC 8785 canonicalization
+  [5] Rate limit  — sliding window per requester
+  [6] Nonce       — replay detection
+  [7] Policy      — deny-by-default allowlist
+       │
+       ▼
+    execute  ──▶  audit entry  ──▶  rollback state
+```
 
-| Option | Description |
-|---|---|
-| `rootDir` | Workspace root — enables automatic local setup |
-| `secretKey` | Ed25519 signing key (base64). Required for execution |
-| `keyStore` | Trusted key registry object |
-| `policy` | Inline policy object (overrides policy file) |
-| `state` | State storage mode |
-| `logLevel` | Runtime log level (`DEBUG`, `INFO`, `WARN`, `ERROR`) |
+All 7 stages execute inside `runtime/lbe_engine.wasm`. The JS layer handles file IO, adapter dispatch, and the public SDK surface only.
 
-`createLBE()` returns an object with:
+<div align="center">
+<img src="https://raw.githubusercontent.com/Letterblack0306/letterblack-Lockstep-boundry-engine/main/assets/storyboard-allow.png" width="680" alt="Trusted agent approved: identity confirmed, policy passed, governed write executed, audit chain extended"/>
+</div>
 
-- `execute({ actor, intent, target, content, args, transaction })` — run a governed operation
-- `writeFile(target, content)` — convenience governed write
-- `readFile(target)` — convenience governed read
-- `exportLogs()` — return the in-memory operation log
+---
 
-## CLI
+## SDK API status
 
-| Command | Description |
-|---|---|
-| `npx lbe init` | Initialize local workspace governance |
-| `npx lbe health` | Verify local runtime readiness |
-| `npx lbe verify --in proposal.json` | Validate an execution proposal |
-| `npx lbe run --in proposal.json` | Validate and execute a proposal |
-| `npx lbe audit-verify` | Verify local audit chain integrity |
-| `npx lbe-mcp` | Start the LBE MCP server on stdio |
+The public SDK surface is intentionally minimal in v0.4.0.
 
-## Runtime
+Current stable entry points:
+- `sandbox(root, opts?)`
+- `createLBE(options)`
+- `lbe.execute(proposal)`
+- `lbe.readFile(path)`
+- `lbe.writeFile(path, content)`
 
-The governance engine ships as a compiled WASM binary (`runtime/lbe_engine.wasm`).
-Validation pipeline, policy decisions, nonce deduplication, rate-limit enforcement,
-audit hash chaining, risk classification, and rollback logic all execute inside
-the compiled runtime. The JS layer handles file IO, adapter dispatch, and the
-public API surface only.
+Expanded API documentation will be published after the runtime contract stabilizes.
 
-The engine loads once on first call and is cached for the process lifetime.
-No network access is required. No data leaves the machine.
+---
 
-## Security Notes
+## What LBE protects against
 
-LBE governs agent actions routed through the SDK. It provides local policy
-enforcement, auditability, and rollback support for governed operations.
+| Risk | Protection |
+|---|---|
+| Unauthorized workspace writes | Policy + sandbox boundary |
+| Agent behavior drift | Deny-by-default allowlist |
+| Accidental destructive ops | Rollback + backup |
+| Replay attacks | Nonce deduplication |
+| Rate abuse | Sliding window rate limit |
+| Tampered audit records | SHA-256 hash chain |
+| Key misuse | Ed25519 lifecycle enforcement |
 
-LBE does not replace OS-level sandboxing, container isolation, network egress
-controls, or multi-tenant workload isolation.
+> LBE does not replace OS-level sandboxing, container isolation, or network egress controls.
 
-### What LBE reduces the risk of
+---
 
-- Unauthorized workspace modification by agent workflows
-- Policy bypass caused by agent behavior drift
-- Accidental destructive operations (delete, overwrite)
-- Loss of visibility into agent-driven changes
+## License
 
-### What LBE does not replace
+Commercial. See [LICENSE](./LICENSE) and [COMMERCIAL_DISTRIBUTION.md](./COMMERCIAL_DISTRIBUTION.md).  
+Usage requires an applicable [LetterBlack](https://letterblack.ae) license, subscription, or evaluation agreement.
 
-- Operating-system security and user permissions
-- Root or administrator access controls
-- Malware protection
-- Container or VM isolation
-- Network security controls
+<div align="center">
 
-## License
+Built by [LetterBlack](https://letterblack.ae)
 
-See [LICENSE](./LICENSE). Commercial usage requires an applicable LetterBlack
-license, subscription, evaluation agreement, or other written authorization.
+</div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letterblack/lbe-sdk",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Commercial SDK distribution for the Lockstep Boundary Engine.",
   "type": "module",
   "main": "dist/index.js",