@letterblack/lbe-sdk 0.4.0 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +136 -99
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,34 +1,76 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# `@letterblack/lbe-sdk`
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**Local-first AI execution governance.**
|
|
6
|
+
Sandboxed writes · Audit · Rollback · MCP · WASM engine
|
|
6
7
|
|
|
7
|
-
|
|
8
|
+
[](https://www.npmjs.com/package/@letterblack/lbe-sdk)
|
|
9
|
+
[](./LICENSE)
|
|
10
|
+
[](https://nodejs.org)
|
|
11
|
+
[](./runtime/lbe_engine.wasm)
|
|
8
12
|
|
|
9
|
-
|
|
13
|
+
</div>
|
|
10
14
|
|
|
11
|
-
|
|
12
|
-
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## How it works
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
AI Agent
|
|
21
|
+
│
|
|
22
|
+
│ propose action
|
|
23
|
+
▼
|
|
24
|
+
┌─────────────────────────────────────┐
|
|
25
|
+
│ @letterblack/lbe-sdk │
|
|
26
|
+
│ │
|
|
27
|
+
│ ┌─────────────────────────────┐ │
|
|
28
|
+
│ │ WASM Engine │ │
|
|
29
|
+
│ │ schema → timestamp → key │ │
|
|
30
|
+
│ │ → signature → rate-limit │ │
|
|
31
|
+
│ │ → nonce → policy │ │
|
|
32
|
+
│ └────────────┬────────────────┘ │
|
|
33
|
+
│ │ ok / deny │
|
|
34
|
+
│ ┌────────────▼────────────────┐ │
|
|
35
|
+
│ │ Adapter (file / shell) │ │
|
|
36
|
+
│ └────────────┬────────────────┘ │
|
|
37
|
+
│ │ │
|
|
38
|
+
│ ┌────────────▼────────────────┐ │
|
|
39
|
+
│ │ Audit log · Rollback │ │
|
|
40
|
+
│ └─────────────────────────────┘ │
|
|
41
|
+
└─────────────────────────────────────┘
|
|
42
|
+
│
|
|
43
|
+
│ result + audit entry
|
|
44
|
+
▼
|
|
45
|
+
Your app
|
|
13
46
|
```
|
|
14
47
|
|
|
15
|
-
|
|
48
|
+
Everything runs on your machine. No hosted service. No data leaves.
|
|
16
49
|
|
|
17
|
-
|
|
50
|
+
---
|
|
18
51
|
|
|
52
|
+
## Install
|
|
53
|
+
|
|
54
|
+
**PowerShell**
|
|
55
|
+
```powershell
|
|
56
|
+
npm install "@letterblack/lbe-sdk"
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
**bash / zsh / cmd**
|
|
19
60
|
```bash
|
|
20
|
-
|
|
61
|
+
npm install @letterblack/lbe-sdk
|
|
21
62
|
```
|
|
22
63
|
|
|
23
|
-
|
|
24
|
-
operate inside explicit project boundaries.
|
|
64
|
+
> Requires Node.js 20.9.0+
|
|
25
65
|
|
|
26
|
-
|
|
66
|
+
---
|
|
27
67
|
|
|
28
68
|
## Quick Start
|
|
29
69
|
|
|
70
|
+
### Sandbox (simple)
|
|
71
|
+
|
|
30
72
|
```js
|
|
31
|
-
import { sandbox } from
|
|
73
|
+
import { sandbox } from "@letterblack/lbe-sdk";
|
|
32
74
|
|
|
33
75
|
const sb = sandbox('./workspace');
|
|
34
76
|
|
|
@@ -36,32 +78,42 @@ await sb.write('output.txt', 'Hello\n');
|
|
|
36
78
|
const text = await sb.read('output.txt');
|
|
37
79
|
```
|
|
38
80
|
|
|
39
|
-
|
|
40
|
-
Use it as the boundary for all agent-facing file operations.
|
|
41
|
-
|
|
42
|
-
## Audit and Rollback
|
|
81
|
+
### With audit + rollback
|
|
43
82
|
|
|
44
83
|
```js
|
|
45
|
-
import { sandbox } from
|
|
84
|
+
import { sandbox } from "@letterblack/lbe-sdk";
|
|
46
85
|
|
|
47
86
|
const sb = sandbox('./workspace', {
|
|
48
87
|
audit: true,
|
|
49
88
|
rollback: true
|
|
50
89
|
});
|
|
51
90
|
|
|
52
|
-
await sb.write('
|
|
91
|
+
await sb.write('report.md', '# Report\n');
|
|
53
92
|
```
|
|
54
93
|
|
|
55
|
-
|
|
56
|
-
state when your team shares governance artifacts:
|
|
94
|
+
### Full SDK client
|
|
57
95
|
|
|
58
96
|
```js
|
|
59
|
-
|
|
97
|
+
import { createLBE } from "@letterblack/lbe-sdk";
|
|
98
|
+
|
|
99
|
+
const lbe = createLBE({ rootDir: process.cwd() });
|
|
100
|
+
|
|
101
|
+
const result = await lbe.execute({
|
|
102
|
+
actor: 'agent:sdk',
|
|
103
|
+
intent: 'write_file',
|
|
104
|
+
target: './output/report.md',
|
|
105
|
+
content: '# Report\n'
|
|
106
|
+
});
|
|
107
|
+
|
|
108
|
+
console.log(result.ok); // true
|
|
109
|
+
console.log(result.stage); // 'ok'
|
|
60
110
|
```
|
|
61
111
|
|
|
112
|
+
---
|
|
113
|
+
|
|
62
114
|
## MCP Server
|
|
63
115
|
|
|
64
|
-
Add LBE governance to any MCP-compatible AI host:
|
|
116
|
+
Add LBE governance to any MCP-compatible AI host in one config block:
|
|
65
117
|
|
|
66
118
|
```json
|
|
67
119
|
{
|
|
@@ -74,117 +126,102 @@ Add LBE governance to any MCP-compatible AI host:
|
|
|
74
126
|
}
|
|
75
127
|
```
|
|
76
128
|
|
|
77
|
-
### Agent
|
|
129
|
+
### Agent tools
|
|
78
130
|
|
|
79
131
|
| Tool | Purpose |
|
|
80
132
|
|---|---|
|
|
81
|
-
| `lbe_workspace_context` | Fetch
|
|
82
|
-
| `lbe_write_file` | Governed write with backup
|
|
133
|
+
| `lbe_workspace_context` | Fetch workspace constraints before planning |
|
|
134
|
+
| `lbe_write_file` | Governed write with backup + rollback |
|
|
83
135
|
| `lbe_read_file` | Governed read |
|
|
84
|
-
| `lbe_patch_file` | Governed append/patch |
|
|
85
|
-
| `lbe_shell_command` | Governed command
|
|
136
|
+
| `lbe_patch_file` | Governed append / patch |
|
|
137
|
+
| `lbe_shell_command` | Governed command via configured allowlist |
|
|
86
138
|
| `lbe_health` | Verify local SDK readiness |
|
|
87
139
|
|
|
88
|
-
|
|
140
|
+
---
|
|
89
141
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
```js
|
|
93
|
-
import { createLBE } from '@letterblack/lbe-sdk';
|
|
94
|
-
|
|
95
|
-
const lbe = createLBE({
|
|
96
|
-
rootDir: process.cwd()
|
|
97
|
-
});
|
|
98
|
-
|
|
99
|
-
const result = await lbe.execute({
|
|
100
|
-
actor: 'agent:sdk',
|
|
101
|
-
intent: 'write_file',
|
|
102
|
-
target: './output/report.md',
|
|
103
|
-
content: '# Report\n'
|
|
104
|
-
});
|
|
142
|
+
## CLI
|
|
105
143
|
|
|
106
|
-
|
|
107
|
-
|
|
144
|
+
```bash
|
|
145
|
+
npx lbe init # Initialize workspace governance
|
|
146
|
+
npx lbe health # Verify runtime readiness
|
|
147
|
+
npx lbe verify --in proposal.json # Validate a proposal (no execution)
|
|
148
|
+
npx lbe run --in proposal.json # Validate + execute
|
|
149
|
+
npx lbe audit-verify # Verify audit chain integrity
|
|
150
|
+
npx lbe-mcp # Start MCP server on stdio
|
|
108
151
|
```
|
|
109
152
|
|
|
110
|
-
|
|
153
|
+
---
|
|
111
154
|
|
|
112
|
-
|
|
155
|
+
## API
|
|
113
156
|
|
|
114
|
-
|
|
157
|
+
### `sandbox(root, opts?)`
|
|
115
158
|
|
|
116
159
|
| Option | Default | Description |
|
|
117
160
|
|---|---|---|
|
|
118
161
|
| `audit` | `false` | Record governed operations to the local audit log |
|
|
119
162
|
| `rollback` | `false` | Back up before writes; restore on failure |
|
|
120
|
-
| `state` | `'local'` |
|
|
163
|
+
| `state` | `'local'` | `'local'`, `'workspace'`, or custom adapter |
|
|
121
164
|
|
|
122
165
|
### `createLBE(options)`
|
|
123
166
|
|
|
124
|
-
Creates a full SDK client for application integrations.
|
|
125
|
-
|
|
126
167
|
| Option | Description |
|
|
127
168
|
|---|---|
|
|
128
|
-
| `rootDir` | Workspace root
|
|
129
|
-
| `secretKey` | Ed25519 signing key (base64)
|
|
130
|
-
| `keyStore` | Trusted key registry
|
|
131
|
-
| `policy` | Inline policy object
|
|
169
|
+
| `rootDir` | Workspace root |
|
|
170
|
+
| `secretKey` | Ed25519 signing key (base64) |
|
|
171
|
+
| `keyStore` | Trusted key registry |
|
|
172
|
+
| `policy` | Inline policy object |
|
|
132
173
|
| `state` | State storage mode |
|
|
133
|
-
| `logLevel` |
|
|
174
|
+
| `logLevel` | `DEBUG` · `INFO` · `WARN` · `ERROR` |
|
|
134
175
|
|
|
135
|
-
`
|
|
176
|
+
Returns: `execute()` · `writeFile()` · `readFile()` · `exportLogs()`
|
|
136
177
|
|
|
137
|
-
|
|
138
|
-
- `writeFile(target, content)` — convenience governed write
|
|
139
|
-
- `readFile(target)` — convenience governed read
|
|
140
|
-
- `exportLogs()` — return the in-memory operation log
|
|
178
|
+
---
|
|
141
179
|
|
|
142
|
-
##
|
|
180
|
+
## Validation pipeline
|
|
143
181
|
|
|
144
|
-
|
|
145
|
-
|---|---|
|
|
146
|
-
| `npx lbe init` | Initialize local workspace governance |
|
|
147
|
-
| `npx lbe health` | Verify local runtime readiness |
|
|
148
|
-
| `npx lbe verify --in proposal.json` | Validate an execution proposal |
|
|
149
|
-
| `npx lbe run --in proposal.json` | Validate and execute a proposal |
|
|
150
|
-
| `npx lbe audit-verify` | Verify local audit chain integrity |
|
|
151
|
-
| `npx lbe-mcp` | Start the LBE MCP server on stdio |
|
|
182
|
+
Every execution proposal passes 7 stages inside the compiled WASM engine:
|
|
152
183
|
|
|
153
|
-
|
|
184
|
+
```
|
|
185
|
+
[1] Schema — required fields, types, structure
|
|
186
|
+
[2] Timestamp — skew tolerance, replay window
|
|
187
|
+
[3] Key — lifecycle, expiry, revocation
|
|
188
|
+
[4] Signature — Ed25519, RFC 8785 canonicalization
|
|
189
|
+
[5] Rate limit — sliding window per requester
|
|
190
|
+
[6] Nonce — replay detection
|
|
191
|
+
[7] Policy — deny-by-default allowlist
|
|
192
|
+
│
|
|
193
|
+
▼
|
|
194
|
+
execute ──▶ audit entry ──▶ rollback state
|
|
195
|
+
```
|
|
154
196
|
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
audit hash chaining, risk classification, and rollback logic all execute inside
|
|
158
|
-
the compiled runtime. The JS layer handles file IO, adapter dispatch, and the
|
|
159
|
-
public API surface only.
|
|
197
|
+
All 7 stages execute inside `runtime/lbe_engine.wasm`.
|
|
198
|
+
The JS layer handles file IO, adapter dispatch, and the public API only.
|
|
160
199
|
|
|
161
|
-
|
|
162
|
-
No network access is required. No data leaves the machine.
|
|
200
|
+
---
|
|
163
201
|
|
|
164
|
-
##
|
|
202
|
+
## What LBE protects against
|
|
165
203
|
|
|
166
|
-
|
|
167
|
-
|
|
204
|
+
| Risk | Protection |
|
|
205
|
+
|---|---|
|
|
206
|
+
| Unauthorized workspace writes | Policy + sandbox boundary |
|
|
207
|
+
| Agent behavior drift | Deny-by-default allowlist |
|
|
208
|
+
| Accidental destructive ops | Rollback + backup |
|
|
209
|
+
| Replay attacks | Nonce deduplication |
|
|
210
|
+
| Rate abuse | Sliding window rate limit |
|
|
211
|
+
| Tampered audit records | SHA-256 hash chain |
|
|
212
|
+
| Key misuse | Ed25519 lifecycle enforcement |
|
|
168
213
|
|
|
169
|
-
LBE does not replace OS-level sandboxing, container isolation, network egress
|
|
170
|
-
controls, or multi-tenant workload isolation.
|
|
214
|
+
> LBE does not replace OS-level sandboxing, container isolation, or network egress controls.
|
|
171
215
|
|
|
172
|
-
|
|
216
|
+
---
|
|
173
217
|
|
|
174
|
-
|
|
175
|
-
- Policy bypass caused by agent behavior drift
|
|
176
|
-
- Accidental destructive operations (delete, overwrite)
|
|
177
|
-
- Loss of visibility into agent-driven changes
|
|
218
|
+
## License
|
|
178
219
|
|
|
179
|
-
|
|
220
|
+
Commercial. See [LICENSE](./LICENSE) and [COMMERCIAL_DISTRIBUTION.md](./COMMERCIAL_DISTRIBUTION.md).
|
|
221
|
+
Usage requires an applicable [LetterBlack](https://letterblack.ae) license, subscription, or evaluation agreement.
|
|
180
222
|
|
|
181
|
-
|
|
182
|
-
- Root or administrator access controls
|
|
183
|
-
- Malware protection
|
|
184
|
-
- Container or VM isolation
|
|
185
|
-
- Network security controls
|
|
223
|
+
<div align="center">
|
|
186
224
|
|
|
187
|
-
|
|
225
|
+
Built by [LetterBlack](https://letterblack.ae)
|
|
188
226
|
|
|
189
|
-
|
|
190
|
-
license, subscription, evaluation agreement, or other written authorization.
|
|
227
|
+
</div>
|