@letterblack/lbe-sdk 0.4.2 → 0.4.4
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/LICENSE +1 -12
- package/README.md +83 -163
- package/config/policy.default.json +162 -0
- package/dist/cli.js +21 -64
- package/dist/index.js +12 -678
- package/dist/mcp-server.js +19 -29
- package/package.json +8 -18
- package/types.d.ts +26 -0
- package/CHANGELOG.md +0 -47
- package/COMMERCIAL_DISTRIBUTION.md +0 -29
- package/dist/engine.js +0 -78
- /package/{runtime → dist}/lbe_engine.wasm +0 -0
package/LICENSE
CHANGED
|
@@ -1,12 +1 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
All rights reserved.
|
|
4
|
-
|
|
5
|
-
This commercial SDK distribution is provided only under a separate written
|
|
6
|
-
license, subscription, evaluation agreement, or other authorization from
|
|
7
|
-
LetterBlack. You may not copy, modify, redistribute, sublicense, reverse
|
|
8
|
-
engineer, or use this package except as permitted by that agreement or by
|
|
9
|
-
applicable law.
|
|
10
|
-
|
|
11
|
-
If you received this package without an applicable license or authorization,
|
|
12
|
-
do not use or distribute it. Contact LetterBlack for licensing terms.
|
|
1
|
+
SEE LICENSE IN LICENSE
|
package/README.md
CHANGED
|
@@ -1,116 +1,47 @@
|
|
|
1
|
-
|
|
1
|
+
# @letterblack/lbe-sdk
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Local-first execution governance SDK for AI agents.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
LBE SDK gives MCP-compatible agents and Node.js tools a governed execution
|
|
6
|
+
boundary for local workspace actions: workspace context, policy checks, audit
|
|
7
|
+
logging, rollback-aware writes, and controlled shell/file operations.
|
|
6
8
|
|
|
7
|
-
|
|
8
|
-
Sandboxed writes · Audit · Rollback · MCP · WASM engine
|
|
9
|
-
|
|
10
|
-
[](https://www.npmjs.com/package/@letterblack/lbe-sdk)
|
|
11
|
-
[](./LICENSE)
|
|
12
|
-
[](https://nodejs.org)
|
|
13
|
-
[](./runtime/lbe_engine.wasm)
|
|
14
|
-
|
|
15
|
-
</div>
|
|
16
|
-
|
|
17
|
-
---
|
|
18
|
-
|
|
19
|
-
## What LBE is
|
|
20
|
-
|
|
21
|
-
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.
|
|
22
|
-
|
|
23
|
-
---
|
|
24
|
-
|
|
25
|
-
## The problem
|
|
26
|
-
|
|
27
|
-
AI agents can write files, run shell commands, and modify your system — and most frameworks let them do it without any gate.
|
|
28
|
-
|
|
29
|
-
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.
|
|
30
|
-
|
|
31
|
-
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.
|
|
32
|
-
|
|
33
|
-
<div align="center">
|
|
34
|
-
<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"/>
|
|
35
|
-
</div>
|
|
36
|
-
|
|
37
|
-
---
|
|
38
|
-
|
|
39
|
-
## How it works
|
|
40
|
-
|
|
41
|
-
<div align="center">
|
|
42
|
-
<img src="https://raw.githubusercontent.com/Letterblack0306/letterblack-Lockstep-boundry-engine/main/assets/architecture.svg" width="680" alt="LBE SDK architecture diagram"/>
|
|
43
|
-
</div>
|
|
44
|
-
|
|
45
|
-
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.
|
|
46
|
-
|
|
47
|
-
---
|
|
9
|
+
Everything runs on your machine. No cloud service is required.
|
|
48
10
|
|
|
49
11
|
## Install
|
|
50
12
|
|
|
51
|
-
**PowerShell**
|
|
52
|
-
```powershell
|
|
53
|
-
npm install "@letterblack/lbe-sdk"
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
**bash / zsh / cmd**
|
|
57
13
|
```bash
|
|
58
14
|
npm install @letterblack/lbe-sdk
|
|
59
15
|
```
|
|
60
16
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
---
|
|
64
|
-
|
|
65
|
-
## Quick Start
|
|
17
|
+
Requires Node.js >= 20.9.0.
|
|
66
18
|
|
|
67
|
-
|
|
19
|
+
## Initialize a workspace
|
|
68
20
|
|
|
69
|
-
|
|
70
|
-
import { sandbox } from "@letterblack/lbe-sdk";
|
|
71
|
-
|
|
72
|
-
const sb = sandbox('./workspace');
|
|
21
|
+
Run this once in each project you want LBE to govern:
|
|
73
22
|
|
|
74
|
-
|
|
75
|
-
|
|
23
|
+
```bash
|
|
24
|
+
npx lbe init
|
|
76
25
|
```
|
|
77
26
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
```js
|
|
81
|
-
import { sandbox } from "@letterblack/lbe-sdk";
|
|
27
|
+
This creates a local workspace contract:
|
|
82
28
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
rollback: true
|
|
86
|
-
});
|
|
87
|
-
|
|
88
|
-
await sb.write('report.md', '# Report\n');
|
|
29
|
+
```text
|
|
30
|
+
lbe.workspace.json
|
|
89
31
|
```
|
|
90
32
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
```js
|
|
94
|
-
import { createLBE } from "@letterblack/lbe-sdk";
|
|
95
|
-
|
|
96
|
-
const lbe = createLBE({ rootDir: process.cwd() });
|
|
97
|
-
|
|
98
|
-
const result = await lbe.execute({
|
|
99
|
-
actor: 'agent:sdk',
|
|
100
|
-
intent: 'write_file',
|
|
101
|
-
target: './output/report.md',
|
|
102
|
-
content: '# Report\n'
|
|
103
|
-
});
|
|
33
|
+
It also creates local keys and runtime state. Do not commit:
|
|
104
34
|
|
|
105
|
-
|
|
106
|
-
|
|
35
|
+
```text
|
|
36
|
+
keys/
|
|
37
|
+
config/keys.json
|
|
38
|
+
config/policy.sig.json
|
|
39
|
+
data/
|
|
107
40
|
```
|
|
108
41
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
## MCP Server
|
|
42
|
+
## MCP setup
|
|
112
43
|
|
|
113
|
-
Add LBE
|
|
44
|
+
Add LBE to any MCP-compatible host:
|
|
114
45
|
|
|
115
46
|
```json
|
|
116
47
|
{
|
|
@@ -123,95 +54,84 @@ Add LBE governance to any MCP-compatible AI host in one config block:
|
|
|
123
54
|
}
|
|
124
55
|
```
|
|
125
56
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|---|---|
|
|
130
|
-
| `lbe_workspace_context` | Fetch workspace constraints before planning |
|
|
131
|
-
| `lbe_write_file` | Governed write with backup + rollback |
|
|
132
|
-
| `lbe_read_file` | Governed read |
|
|
133
|
-
| `lbe_patch_file` | Governed append / patch |
|
|
134
|
-
| `lbe_shell_command` | Governed command via configured allowlist |
|
|
135
|
-
| `lbe_health` | Verify local SDK readiness |
|
|
57
|
+
If the workspace has not been initialized yet, the MCP server still starts and
|
|
58
|
+
returns a clear `npx lbe init` message from health/action tools instead of
|
|
59
|
+
failing the MCP handshake.
|
|
136
60
|
|
|
137
|
-
|
|
61
|
+
Agents should call `lbe_workspace_context` first, before planning or writing.
|
|
138
62
|
|
|
139
|
-
##
|
|
63
|
+
## MCP tools
|
|
140
64
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
65
|
+
| Tool | Purpose |
|
|
66
|
+
|---|---|
|
|
67
|
+
| `lbe_workspace_context` | Read the local workspace contract |
|
|
68
|
+
| `lbe_write_file` | Write a file with validation, backup, and audit |
|
|
69
|
+
| `lbe_read_file` | Read a file through policy checks |
|
|
70
|
+
| `lbe_patch_file` | Append/patch a file with backup and audit |
|
|
71
|
+
| `lbe_shell_command` | Run an allowlisted shell command |
|
|
72
|
+
| `lbe_health` | Report controller/workspace health |
|
|
149
73
|
|
|
150
|
-
|
|
74
|
+
## SDK usage
|
|
151
75
|
|
|
152
|
-
|
|
76
|
+
```js
|
|
77
|
+
import { sandbox } from '@letterblack/lbe-sdk';
|
|
153
78
|
|
|
154
|
-
|
|
79
|
+
const sb = sandbox('./workspace', { audit: true, rollback: true });
|
|
155
80
|
|
|
81
|
+
await sb.write('output.txt', 'Hello\n');
|
|
82
|
+
const text = await sb.read('output.txt');
|
|
156
83
|
```
|
|
157
|
-
[1] Schema — required fields, types, structure
|
|
158
|
-
[2] Timestamp — skew tolerance, replay window
|
|
159
|
-
[3] Key — lifecycle, expiry, revocation
|
|
160
|
-
[4] Signature — Ed25519, RFC 8785 canonicalization
|
|
161
|
-
[5] Rate limit — sliding window per requester
|
|
162
|
-
[6] Nonce — replay detection
|
|
163
|
-
[7] Policy — deny-by-default allowlist
|
|
164
|
-
│
|
|
165
|
-
▼
|
|
166
|
-
execute ──▶ audit entry ──▶ rollback state
|
|
167
|
-
```
|
|
168
|
-
|
|
169
|
-
All 7 stages execute inside `runtime/lbe_engine.wasm`. The JS layer handles file IO, adapter dispatch, and the public SDK surface only.
|
|
170
|
-
|
|
171
|
-
<div align="center">
|
|
172
|
-
<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"/>
|
|
173
|
-
</div>
|
|
174
84
|
|
|
175
|
-
|
|
85
|
+
For advanced policy-controlled execution:
|
|
176
86
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
The public SDK surface is intentionally minimal in v0.4.0.
|
|
87
|
+
```js
|
|
88
|
+
import { createLBE } from '@letterblack/lbe-sdk';
|
|
180
89
|
|
|
181
|
-
|
|
182
|
-
- `sandbox(root, opts?)`
|
|
183
|
-
- `createLBE(options)`
|
|
184
|
-
- `lbe.execute(proposal)`
|
|
185
|
-
- `lbe.readFile(path)`
|
|
186
|
-
- `lbe.writeFile(path, content)`
|
|
90
|
+
const lbe = createLBE({ rootDir: process.cwd() });
|
|
187
91
|
|
|
188
|
-
|
|
92
|
+
const result = await lbe.execute({
|
|
93
|
+
actor: 'agent:writer',
|
|
94
|
+
intent: 'write_file',
|
|
95
|
+
target: 'output/report.md',
|
|
96
|
+
content: '# Report\n',
|
|
97
|
+
transaction: { backup: true, rollbackOnFailure: true, audit: true }
|
|
98
|
+
});
|
|
189
99
|
|
|
190
|
-
|
|
100
|
+
console.log(result.ok, result.stage, result.commandId);
|
|
101
|
+
```
|
|
191
102
|
|
|
192
|
-
##
|
|
103
|
+
## CLI
|
|
193
104
|
|
|
194
|
-
|
|
|
105
|
+
| Command | Description |
|
|
195
106
|
|---|---|
|
|
196
|
-
|
|
|
197
|
-
|
|
|
198
|
-
|
|
|
199
|
-
|
|
|
200
|
-
|
|
|
201
|
-
|
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
107
|
+
| `npx lbe init` | Initialize workspace contract, keys, and policy state |
|
|
108
|
+
| `npx lbe health` | Check local workspace health |
|
|
109
|
+
| `npx lbe-mcp` | Start the MCP server on stdio |
|
|
110
|
+
| `npx lbe verify --in proposal.json` | Validate a proposal without execution |
|
|
111
|
+
| `npx lbe run --in proposal.json` | Validate and execute a proposal |
|
|
112
|
+
| `npx lbe audit-verify` | Verify audit log hash chain |
|
|
113
|
+
|
|
114
|
+
## What ships
|
|
115
|
+
|
|
116
|
+
The npm package contains the public SDK surface only:
|
|
117
|
+
|
|
118
|
+
```text
|
|
119
|
+
dist/
|
|
120
|
+
types.d.ts
|
|
121
|
+
README.md
|
|
122
|
+
LICENSE
|
|
123
|
+
config/policy.default.json
|
|
124
|
+
package.json
|
|
125
|
+
```
|
|
209
126
|
|
|
210
|
-
|
|
211
|
-
|
|
127
|
+
Private source files, tests, release scripts, keys, runtime data, and source maps
|
|
128
|
+
are not part of the public package.
|
|
212
129
|
|
|
213
|
-
|
|
130
|
+
## Security scope
|
|
214
131
|
|
|
215
|
-
|
|
132
|
+
LBE governs actions routed through the SDK. It helps protect against accidental
|
|
133
|
+
writes outside allowed roots, replayed proposals, policy drift, audit tampering,
|
|
134
|
+
and failed write operations that need rollback.
|
|
216
135
|
|
|
217
|
-
|
|
136
|
+
It is not a kernel-level sandbox, network egress firewall, or multi-tenant
|
|
137
|
+
isolation layer.
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
{
|
|
2
|
+
"version": 3,
|
|
3
|
+
"createdAt": "2026-06-16T09:00:00Z",
|
|
4
|
+
"default": "DENY",
|
|
5
|
+
"requesters": {
|
|
6
|
+
"agent:observer": {
|
|
7
|
+
"allowAdapters": [
|
|
8
|
+
"observer"
|
|
9
|
+
],
|
|
10
|
+
"allowCommands": [
|
|
11
|
+
"OBSERVE_IRREGULARITY"
|
|
12
|
+
],
|
|
13
|
+
"description": "Observer-only mode: AI reports issues without mutations"
|
|
14
|
+
},
|
|
15
|
+
"agent:gpt": {
|
|
16
|
+
"allowAdapters": [
|
|
17
|
+
"noop",
|
|
18
|
+
"shell",
|
|
19
|
+
"file"
|
|
20
|
+
],
|
|
21
|
+
"allowCommands": [
|
|
22
|
+
"RUN_SHELL",
|
|
23
|
+
"READ_FILE",
|
|
24
|
+
"WRITE_FILE",
|
|
25
|
+
"PATCH_FILE",
|
|
26
|
+
"DELETE_FILE"
|
|
27
|
+
],
|
|
28
|
+
"filesystem": {
|
|
29
|
+
"roots": [
|
|
30
|
+
"Z:\\Core_Control\\letterblack-sentinel"
|
|
31
|
+
],
|
|
32
|
+
"denyPatterns": [
|
|
33
|
+
"**/.git/**",
|
|
34
|
+
"**/secrets/**",
|
|
35
|
+
"**/*.key",
|
|
36
|
+
"**/keys/**"
|
|
37
|
+
]
|
|
38
|
+
},
|
|
39
|
+
"exec": {
|
|
40
|
+
"allowCmds": [
|
|
41
|
+
"ls",
|
|
42
|
+
"node",
|
|
43
|
+
"python",
|
|
44
|
+
"echo"
|
|
45
|
+
],
|
|
46
|
+
"denyCmds": [
|
|
47
|
+
"rm",
|
|
48
|
+
"chmod",
|
|
49
|
+
"chown",
|
|
50
|
+
"curl",
|
|
51
|
+
"wget",
|
|
52
|
+
"su",
|
|
53
|
+
"sudo"
|
|
54
|
+
]
|
|
55
|
+
}
|
|
56
|
+
},
|
|
57
|
+
"agent:ae-timeline-vision-v1": {
|
|
58
|
+
"allowAdapters": [
|
|
59
|
+
"cepTimelineVision"
|
|
60
|
+
],
|
|
61
|
+
"allowCommands": [
|
|
62
|
+
"EXTRACT_TIMELINE_FRAMES",
|
|
63
|
+
"ANALYZE_VISION",
|
|
64
|
+
"DETECT_OPTIMAL_MODEL",
|
|
65
|
+
"GENERATE_AUDIO_FROM_VISION"
|
|
66
|
+
],
|
|
67
|
+
"description": "After Effects timeline vision analysis and audio generation pipeline",
|
|
68
|
+
"capabilities": {
|
|
69
|
+
"cep": true,
|
|
70
|
+
"filesystem": true,
|
|
71
|
+
"network": true
|
|
72
|
+
},
|
|
73
|
+
"filesystem": {
|
|
74
|
+
"roots": [
|
|
75
|
+
"D:\\Developement\\Core_Control\\letterblack-sentinel\\data",
|
|
76
|
+
"D:\\Developement\\ElevenLabs_Audio_Toolkit_Professional_Edition"
|
|
77
|
+
],
|
|
78
|
+
"denyPatterns": [
|
|
79
|
+
"**/.git/**",
|
|
80
|
+
"**/secrets/**",
|
|
81
|
+
"**/*.key"
|
|
82
|
+
]
|
|
83
|
+
},
|
|
84
|
+
"exec": {
|
|
85
|
+
"allowCmds": [
|
|
86
|
+
|
|
87
|
+
]
|
|
88
|
+
}
|
|
89
|
+
},
|
|
90
|
+
"cep:ae-audio-sentinel-v1": {
|
|
91
|
+
"allowAdapters": [
|
|
92
|
+
"cepTimelineVision"
|
|
93
|
+
],
|
|
94
|
+
"allowCommands": [
|
|
95
|
+
"EXTRACT_TIMELINE_FRAMES",
|
|
96
|
+
"ANALYZE_VISION",
|
|
97
|
+
"DETECT_OPTIMAL_MODEL",
|
|
98
|
+
"GENERATE_AUDIO_FROM_VISION"
|
|
99
|
+
],
|
|
100
|
+
"description": "Audio Sentinel Pro CEP Extension"
|
|
101
|
+
},
|
|
102
|
+
"agent:letterblack-genai": {
|
|
103
|
+
"allowCommands": [
|
|
104
|
+
"EXECUTE_JSX",
|
|
105
|
+
"VALIDATE_JSX",
|
|
106
|
+
"DRYRUN_JSX"
|
|
107
|
+
],
|
|
108
|
+
"description": "LetterBlack GenAI CEP extension � AE JSX script execution via Sentinel",
|
|
109
|
+
"filesystem": {
|
|
110
|
+
"denyPatterns": [
|
|
111
|
+
"**/.git/**",
|
|
112
|
+
"**/secrets/**",
|
|
113
|
+
"**/*.key",
|
|
114
|
+
"**/node_modules/**"
|
|
115
|
+
],
|
|
116
|
+
"roots": [
|
|
117
|
+
"D:\\Developement\\LetterBlack_GenAI",
|
|
118
|
+
"D:\\Developement\\Core_Control\\letterblack-sentinel\\data"
|
|
119
|
+
]
|
|
120
|
+
},
|
|
121
|
+
"jsx": {
|
|
122
|
+
"maxScriptBytes": 65536,
|
|
123
|
+
"denyPatterns": [
|
|
124
|
+
"app.quit",
|
|
125
|
+
"system.callSystem",
|
|
126
|
+
"File.execute",
|
|
127
|
+
"Folder.execute"
|
|
128
|
+
]
|
|
129
|
+
},
|
|
130
|
+
"allowAdapters": [
|
|
131
|
+
"cep-jsx",
|
|
132
|
+
"noop"
|
|
133
|
+
],
|
|
134
|
+
"exec": {
|
|
135
|
+
"denyCmds": [
|
|
136
|
+
"rm",
|
|
137
|
+
"del",
|
|
138
|
+
"format",
|
|
139
|
+
"curl",
|
|
140
|
+
"wget",
|
|
141
|
+
"su",
|
|
142
|
+
"sudo"
|
|
143
|
+
],
|
|
144
|
+
"allowCmds": [
|
|
145
|
+
|
|
146
|
+
]
|
|
147
|
+
},
|
|
148
|
+
"rateLimit": {
|
|
149
|
+
"windowSec": 60,
|
|
150
|
+
"maxRequests": 20
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
},
|
|
154
|
+
"security": {
|
|
155
|
+
"maxClockSkewSec": 600,
|
|
156
|
+
"maxPolicyCreatedAtSkewSec": 31536000,
|
|
157
|
+
"defaultRateLimit": {
|
|
158
|
+
"windowSec": 60,
|
|
159
|
+
"maxRequests": 30
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
}
|