@letterblack/lbe-sdk 0.4.1 → 0.4.3

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.
Files changed (12) hide show
  1. package/LICENSE +1 -12
  2. package/README.md +83 -173
  3. package/config/policy.default.json +162 -0
  4. package/dist/cli.js +21 -64
  5. package/dist/index.js +12 -678
  6. package/dist/mcp-server.js +19 -29
  7. package/package.json +8 -18
  8. package/types.d.ts +26 -0
  9. package/CHANGELOG.md +0 -47
  10. package/COMMERCIAL_DISTRIBUTION.md +0 -29
  11. package/dist/engine.js +0 -78
  12. /package/{runtime → dist}/lbe_engine.wasm +0 -0
package/LICENSE CHANGED
@@ -1,12 +1 @@
1
- Copyright (c) LetterBlack.
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,119 +1,47 @@
1
- <div align="center">
1
+ # @letterblack/lbe-sdk
2
2
 
3
- # `@letterblack/lbe-sdk`
3
+ Local-first execution governance SDK for AI agents.
4
4
 
5
- **Local-first AI execution governance.**
6
- Sandboxed writes · Audit · Rollback · MCP · WASM engine
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.
7
8
 
8
- [![npm](https://img.shields.io/npm/v/@letterblack/lbe-sdk?color=black&label=npm)](https://www.npmjs.com/package/@letterblack/lbe-sdk)
9
- [![license](https://img.shields.io/badge/license-Commercial-red)](./LICENSE)
10
- [![node](https://img.shields.io/node/v/@letterblack/lbe-sdk?color=darkgreen)](https://nodejs.org)
11
- [![engine](https://img.shields.io/badge/engine-WASM-blueviolet)](./runtime/lbe_engine.wasm)
12
-
13
- </div>
14
-
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
46
- ```
47
-
48
- Everything runs on your machine. No hosted service. No data leaves.
49
-
50
- ---
9
+ Everything runs on your machine. No cloud service is required.
51
10
 
52
11
  ## Install
53
12
 
54
- **PowerShell**
55
- ```powershell
56
- npm install "@letterblack/lbe-sdk"
57
- ```
58
-
59
- **bash / zsh / cmd**
60
13
  ```bash
61
14
  npm install @letterblack/lbe-sdk
62
15
  ```
63
16
 
64
- > Requires Node.js 20.9.0+
65
-
66
- ---
17
+ Requires Node.js >= 20.9.0.
67
18
 
68
- ## Quick Start
69
-
70
- ### Sandbox (simple)
71
-
72
- ```js
73
- import { sandbox } from "@letterblack/lbe-sdk";
19
+ ## Initialize a workspace
74
20
 
75
- const sb = sandbox('./workspace');
21
+ Run this once in each project you want LBE to govern:
76
22
 
77
- await sb.write('output.txt', 'Hello\n');
78
- const text = await sb.read('output.txt');
23
+ ```bash
24
+ npx lbe init
79
25
  ```
80
26
 
81
- ### With audit + rollback
82
-
83
- ```js
84
- import { sandbox } from "@letterblack/lbe-sdk";
85
-
86
- const sb = sandbox('./workspace', {
87
- audit: true,
88
- rollback: true
89
- });
27
+ This creates a local workspace contract:
90
28
 
91
- await sb.write('report.md', '# Report\n');
29
+ ```text
30
+ lbe.workspace.json
92
31
  ```
93
32
 
94
- ### Full SDK client
95
-
96
- ```js
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
- });
33
+ It also creates local keys and runtime state. Do not commit:
107
34
 
108
- console.log(result.ok); // true
109
- console.log(result.stage); // 'ok'
35
+ ```text
36
+ keys/
37
+ config/keys.json
38
+ config/policy.sig.json
39
+ data/
110
40
  ```
111
41
 
112
- ---
42
+ ## MCP setup
113
43
 
114
- ## MCP Server
115
-
116
- Add LBE governance to any MCP-compatible AI host in one config block:
44
+ Add LBE to any MCP-compatible host:
117
45
 
118
46
  ```json
119
47
  {
@@ -126,102 +54,84 @@ Add LBE governance to any MCP-compatible AI host in one config block:
126
54
  }
127
55
  ```
128
56
 
129
- ### Agent tools
130
-
131
- | Tool | Purpose |
132
- |---|---|
133
- | `lbe_workspace_context` | Fetch workspace constraints before planning |
134
- | `lbe_write_file` | Governed write with backup + rollback |
135
- | `lbe_read_file` | Governed read |
136
- | `lbe_patch_file` | Governed append / patch |
137
- | `lbe_shell_command` | Governed command via configured allowlist |
138
- | `lbe_health` | Verify local SDK readiness |
139
-
140
- ---
141
-
142
- ## CLI
143
-
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
151
- ```
152
-
153
- ---
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.
154
60
 
155
- ## API
61
+ Agents should call `lbe_workspace_context` first, before planning or writing.
156
62
 
157
- ### `sandbox(root, opts?)`
63
+ ## MCP tools
158
64
 
159
- | Option | Default | Description |
160
- |---|---|---|
161
- | `audit` | `false` | Record governed operations to the local audit log |
162
- | `rollback` | `false` | Back up before writes; restore on failure |
163
- | `state` | `'local'` | `'local'`, `'workspace'`, or custom adapter |
164
-
165
- ### `createLBE(options)`
166
-
167
- | Option | Description |
65
+ | Tool | Purpose |
168
66
  |---|---|
169
- | `rootDir` | Workspace root |
170
- | `secretKey` | Ed25519 signing key (base64) |
171
- | `keyStore` | Trusted key registry |
172
- | `policy` | Inline policy object |
173
- | `state` | State storage mode |
174
- | `logLevel` | `DEBUG` · `INFO` · `WARN` · `ERROR` |
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 |
175
73
 
176
- Returns: `execute()` · `writeFile()` · `readFile()` · `exportLogs()`
74
+ ## SDK usage
177
75
 
178
- ---
179
-
180
- ## Validation pipeline
76
+ ```js
77
+ import { sandbox } from '@letterblack/lbe-sdk';
181
78
 
182
- Every execution proposal passes 7 stages inside the compiled WASM engine:
79
+ const sb = sandbox('./workspace', { audit: true, rollback: true });
183
80
 
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
81
+ await sb.write('output.txt', 'Hello\n');
82
+ const text = await sb.read('output.txt');
195
83
  ```
196
84
 
197
- All 7 stages execute inside `runtime/lbe_engine.wasm`.
198
- The JS layer handles file IO, adapter dispatch, and the public API only.
85
+ For advanced policy-controlled execution:
199
86
 
200
- ---
87
+ ```js
88
+ import { createLBE } from '@letterblack/lbe-sdk';
201
89
 
202
- ## What LBE protects against
90
+ const lbe = createLBE({ rootDir: process.cwd() });
203
91
 
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 |
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
+ });
213
99
 
214
- > LBE does not replace OS-level sandboxing, container isolation, or network egress controls.
100
+ console.log(result.ok, result.stage, result.commandId);
101
+ ```
215
102
 
216
- ---
103
+ ## CLI
217
104
 
218
- ## License
105
+ | Command | Description |
106
+ |---|---|
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
+ ```
219
126
 
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.
127
+ Private source files, tests, release scripts, keys, runtime data, and source maps
128
+ are not part of the public package.
222
129
 
223
- <div align="center">
130
+ ## Security scope
224
131
 
225
- Built by [LetterBlack](https://letterblack.ae)
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.
226
135
 
227
- </div>
136
+ It is not a kernel-level sandbox, network egress firewall, or multi-tenant
137
+ isolation layer.
package/config/policy.default.json ADDED
@@ -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
+ }