@letterblack/lbe-sdk 0.4.0 → 0.4.1

package/README.md

@@ -1,34 +1,76 @@
-# @letterblack/lbe-sdk
+<div align="center">
 
-Lockstep Boundary Engine SDK for local-first AI execution governance.
+# `@letterblack/lbe-sdk`
 
-Sandboxed writes. Workspace context. Audit. Rollback. MCP access.
+**Local-first AI execution governance.**  
+Sandboxed writes · Audit · Rollback · MCP · WASM engine
 
-Everything runs on your machine. No hosted service is required.
+[![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)
 
-## Install
+</div>
 
-```bash
-npm install @letterblack/lbe-sdk
+---
+
+## How it works
+
+```
+  AI Agent
+     │
+     │  propose action
+     ▼
+┌─────────────────────────────────────┐
+│           @letterblack/lbe-sdk      │
+│                                     │
+│  ┌─────────────────────────────┐    │
+│  │      WASM Engine            │    │
+│  │  schema → timestamp → key   │    │
+│  │  → signature → rate-limit   │    │
+│  │  → nonce → policy           │    │
+│  └────────────┬────────────────┘    │
+│               │ ok / deny           │
+│  ┌────────────▼────────────────┐    │
+│  │   Adapter (file / shell)    │    │
+│  └────────────┬────────────────┘    │
+│               │                     │
+│  ┌────────────▼────────────────┐    │
+│  │   Audit log  ·  Rollback    │    │
+│  └─────────────────────────────┘    │
+└─────────────────────────────────────┘
+     │
+     │  result + audit entry
+     ▼
+  Your app
 ```
 
-Requires Node.js 20.9.0 or newer.
+Everything runs on your machine. No hosted service. No data leaves.
 
-## Initialize
+---
 
+## 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 (simple)
+
 ```js
-import { sandbox } from '@letterblack/lbe-sdk';
+import { sandbox } from "@letterblack/lbe-sdk";
 
 const sb = sandbox('./workspace');
 
@@ -36,32 +78,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 +126,102 @@ 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?)`
+## API
 
-Creates a governed workspace helper.
+### `sandbox(root, opts?)`
 
 | 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 |
+| `state` | `'local'` | `'local'`, `'workspace'`, or custom adapter |
 
 ### `createLBE(options)`
 
-Creates a full SDK client for application integrations.
-
 | 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) |
+| `rootDir` | Workspace root |
+| `secretKey` | Ed25519 signing key (base64) |
+| `keyStore` | Trusted key registry |
+| `policy` | Inline policy object |
 | `state` | State storage mode |
-| `logLevel` | Runtime log level (`DEBUG`, `INFO`, `WARN`, `ERROR`) |
+| `logLevel` | `DEBUG` · `INFO` · `WARN` · `ERROR` |
 
-`createLBE()` returns an object with:
+Returns: `execute()` · `writeFile()` · `readFile()` · `exportLogs()`
 
-- `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
+## Validation pipeline
 
-| 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 |
+Every execution proposal passes 7 stages inside the compiled WASM engine:
 
-## Runtime
+```
+  [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
+```
 
-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.
+All 7 stages execute inside `runtime/lbe_engine.wasm`.  
+The JS layer handles file IO, adapter dispatch, and the public API only.
 
-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.1",
   "description": "Commercial SDK distribution for the Lockstep Boundary Engine.",
   "type": "module",
   "main": "dist/index.js",