@letterblack/lbe-core 1.3.3 → 1.3.4

package/LICENSE

@@ -1 +1 @@
-SEE LICENSE IN LICENSE
+SEE LICENSE IN LICENSE

package/README.md

@@ -1,506 +1,194 @@
-# LetterBlack LBE
+# @letterblack/lbe-core
 
 LBE is local execution control for AI agents. It evaluates file and shell
-actions routed through its execution boundary, records local evidence, and
-returns an allow/deny outcome before the governed action runs.
+actions routed through its execution boundary and records local evidence.
+It is not an AI model, IDE, full OS sandbox, or cloud monitor.
 
-LBE is not an AI model, IDE, full OS sandbox, or cloud monitor. It does not
-control direct actions outside its execution boundary.
-
-## Install and start
+## Setup and workspace initialization
 
 ```bash
 npm install @letterblack/lbe-core
 npx lbe init
 npx lbe status
 npx lbe logs
-npx lbe proof --public
 npx lbe open-state
+npx lbe proof
+npx lbe proof --public
 ```
 
-`init` creates project policy material. `status` shows the local central state
-for the current workspace; `logs` reads its event history; `proof` shows the
-latest proof result; and `open-state` opens the central state folder.
-
-## Local state and proof
-
-LBE keeps state locally in a central per-user state folder. Each workspace has
-a stable workspace ID and its own event log. In v1.3, an existing
-`.lbe/events.jsonl` remains local fallback truth and is imported into central
-state once; the source file is preserved.
+`npx lbe init` creates the workspace policy and state material in the central
+per-user folder keyed by workspace ID. `npx lbe status`, `logs`, and
+`open-state` read that local state, while `proof` writes the proof record and
+`--public` redacts sensitive proof details.
 
-Proof combines an intent, optional target, file index, LBE events, and
-`proof/latest.json`. Use `lbe proof --public` for a redacted proof summary.
-Non-inspectable targets can produce `WEAK_PROOF` rather than a stronger claim.
-
-## Limits
-
-Only actions routed through LBE are controlled. Central writes are best-effort,
-logs remain local, and LBE does not provide process isolation or network
-egress control.
+In v1.3, `.lbe/events.jsonl` remains local fallback truth and is imported once
+without changing the original file. Proof uses intent, target, file index, LBE
+events, and `proof/latest.json`. Central writes are best-effort, logs remain
+local, and non-inspectable targets may produce `WEAK_PROOF`.
 
 ---
 
-# Internal source workspace
-
-This workspace is not the public npm package. It contains readable source,
-tests, and release tooling. The public package is generated into
-`release-public/` as `@letterblack/lbe-core`.
-
-Every AI action passes through a local gate before it can execute.
-
-**Local-first execution governance for AI agents.**  
-Deterministic execution. Workspace context. Audit. Rollback.
-
-Everything runs on your machine. No cloud required.
-
-**Distribution model:** this private package owns source truth. The public SDK
-package ships only the generated public surface: bundled/minified `dist/`
-entrypoints, `types.d.ts`, README, default policy template, and the WASM runtime.
-LBE is SDK-only and local-only. It does not ship an MCP server, daemon, HTTP
-API, hosted service, deployment infrastructure, or companion platform.
-
----
-
-## Private/Public Release Contract
-
-Do internal development here:
-
-```bash
-npm install
-npm run lint
-npm test
-npm run pack:check
-```
-
-Build the public SDK package here:
-
-```bash
-npm run build:engine
-npm run validate:all
-npm run verify:public-sdk
-```
-
-Before publishing, install the generated tarball in a clean temporary project
-and exercise the supported CLI workflow (`lbe init`, `lbe status`, `lbe policy`,
-and `lbe enforce`). Publish only from `release-public/` after that test passes.
-
-### Public repository release
-
-`../.github/workflows/release-public.yml` publishes only the generated
-`release-public/` tree to `Letterblack0306/LetterBlack-Sentinel`; it never
-pushes this private source repository, its history, or its internal files.
-
-Set `PUBLIC_REPO_TOKEN` and `NPM_TOKEN` as Actions secrets in this repository.
-The former needs Contents read/write permission to the public repository; the
-latter needs npm publish permission for `@letterblack/lbe-core`. Push a matching
-`v<package-version>` tag from current `main` to release automatically, or run
-the workflow manually with the same tag value. The workflow verifies the
-artifact and tests first, publishes npm, replaces the public repository working
-tree with the release artifact, then creates its tag and GitHub release. It
-blocks release unless the checked-out commit is the current `main` head.
-
-## Source authority
-
-Only `main` in the primary working tree is a source of truth. Do not develop,
-commit, validate, or push from feature branches, detached HEADs, or linked Git
-worktrees. Run `npm run hooks:install` after cloning; see
-[`docs/governance/mainhead.md`](docs/governance/mainhead.md) for the blocker
-rules.
-
-Publish only from:
-
-```text
-release-public/
-```
-
-The generated public package must not contain:
-
-```text
-src/core/
-src/adapters/
-src/cli/
-scripts/
-test/
-keys/
-data/
-node_modules/
-*.map
-```
-
----
-
-## Install
-
-Internal source workspace:
+LBE puts a local policy gate between what an AI agent proposes and what the
+system actually executes. Every action — file write, shell command, anything —
+is validated locally before it runs. No cloud service. No daemon.
 
-```bash
-npm install @letterblack/lbe-core
-```
-
-Public users install:
+> **Used in production:** LBE is the safety engine inside [Letterblack for After Effects](https://letterblack.net) — every AI-generated script and automation command passes through it before touching a live project.
 
+---
+
+## Install
+
 ```bash
 npm install @letterblack/lbe-core
-```
-
-Requires Node.js ≥ 20.9.0.
-
-The current preview uses the audited JavaScript governance engine. The commercial
-runtime target is a compiled engine loaded locally through WASM, with the same
-public SDK and CLI surface.
-
----
-
-## After install
-
-```bash
-npx lbe execute --input input.json
-```
-
-`input.json` must contain a signed LBE execution request. You can also pipe the
-same JSON request through stdin:
-
-```bash
-cat input.json | npx lbe execute
-```
-
----
-
-## Quick Start
-
-```js
-import crypto from 'node:crypto';
-import { execute } from '@letterblack/lbe-core';
-
-const buildRequest = (name, payload = {}) => ({
-    version: '1.0',
-    request_id: crypto.randomUUID(),
-    timestamp: Math.floor(Date.now() / 1000),
-    actor: { id: 'agent:local', role: 'agent' },
-    intent: { type: 'command', name, payload },
-    context: { workspace: process.cwd(), env: {}, history: [] },
-    constraints: { policy_mode: 'strict', timeout_ms: 5000 },
-    auth: { signature: 'provided-by-host', nonce: crypto.randomUUID() }
-});
-
-const output = execute(JSON.stringify(buildRequest('status')));
-console.log(JSON.parse(output));
-```
-
-The public contract is `execute(input: string): string`. This repo still
-contains the private source package and its internal SDK helpers below, but the
-published surface is the generated `@letterblack/lbe-core` package.
+```
+
+Requires Node.js ≥ 20.9.0.
 
 ---
 
-## Add what you need
-
-**Audit — see exactly what changed and when:**
-```js
-const sb = sandbox('./workspace', { audit: true });
-// appends to ~/.lbe/workspaces/<id>/audit.log.jsonl
-```
-
-**Rollback — undo failed writes automatically:**
-```js
-const sb = sandbox('./workspace', { audit: true, rollback: true });
-// backs up before every write, restores on failure
-```
-
-**State stays local** — all runtime state (audit logs, nonce store, backups) goes to  
-`~/.lbe/workspaces/<workspace-id>/` by default. Never inside your project, never sent anywhere.
+## Quick start
 
-To keep state inside the project instead (for team sharing):
 ```js
-const sb = sandbox('./workspace', { state: 'workspace' });
-// writes to .lbe/ inside your project root
-```
+import { execute } from '@letterblack/lbe-core';
+
+const request = {
+  version: '1.0',
+  request_id: 'req-001',
+  timestamp: Math.floor(Date.now() / 1000),
+  actor: { id: 'agent:local', role: 'agent' },
+  intent: { type: 'command', name: 'write_file', payload: { target: 'out.txt' } },
+  context: { workspace: process.cwd(), env: {}, history: [] },
+  constraints: { policy_mode: 'strict', timeout_ms: 5000 },
+  auth: { signature: '<host-signed>', nonce: '<unique-per-request>' }
+};
+
+const result = JSON.parse(execute(JSON.stringify(request)));
+// Approved:  { ok: true,  decision: 'allow', ... }
+// Blocked:   { ok: false, decision: 'deny',  error: { stage, message } }
+```
+
+`execute(input: string): string` — accepts JSON, returns JSON. The runtime validates and returns a decision. The host acts on the decision.
+
+### Request fields
+
+| Field | Required | Description |
+|---|---:|---|
+| `version` | Yes | `"1.0"` |
+| `request_id` | Yes | Caller-supplied unique identifier |
+| `timestamp` | Yes | Unix timestamp in seconds |
+| `actor` | Yes | `{ id, role }` — identity of the requesting agent |
+| `intent` | Yes | `{ type, name, payload }` — what the agent wants to do |
+| `context` | Yes | Workspace path and caller context |
+| `constraints` | Yes | `policy_mode` and `timeout_ms` |
+| `auth` | Yes | Host-supplied `signature` and `nonce` |
 
 ---
 
-## Integration boundary
-
-LBE is embedded directly in the user's existing application through
-`execute(input)` or `createLBE().execute()`. It requires no companion service
-or separate runtime system. The calling code submits structured action requests
-and remains responsible for giving the SDK-governed path exclusive authority.
-
-The Model Context Protocol integration was removed because an MCP server only
-offers LBE as an optional tool; an agent host with native tools can act outside
-the governed execution boundary.
-See [`docs/decisions/ADR-001-remove-mcp-execution-surface.md`](docs/decisions/ADR-001-remove-mcp-execution-surface.md).
+## CLI reference
+
+| Command | Purpose |
+|---|---|
+| `npx lbe init` | Initialize the workspace policy and state material |
+| `npx lbe status` | Show the current workspace and proof status |
+| `npx lbe logs` | Inspect local evidence and event logs |
+| `npx lbe open-state` | Open the central local state folder |
+| `npx lbe proof` | Write the current proof record |
+| `npx lbe proof --public` | Write a redacted proof record for public surfaces |
 
 ---
 
-## Agent Safe Execution
-
-LBE Agent Safe Execution intercepts Node.js file and shell actions before they mutate the workspace.
+## How the gate pipeline works
 
-Choose the integration path that matches how your agent runs:
+![LBE gate sequence — Request flows through Policy, Identity, and Scope gates before reaching Action. A rejected request is routed to denial before it reaches execution.](https://unpkg.com/@letterblack/lbe-exec/assets/lbe-gates.jpg)
 
-### 1. Agents you own — direct integration at the dispatch point
+Every request enters a 7-gate pipeline. A failure at any gate returns a structured denial — the remaining gates are not evaluated.
 
-If you control the agent's dispatch loop, integrate `lbe-exec` at the point where actions are issued. No preload hook needed — LBE governs each action directly through the SDK.
-
-```js
-import { createLocalExecutor } from '@letterblack/lbe-exec';
-
-const lbe = createLocalExecutor({ rootDir: process.cwd(), mode: 'enforce' });
-
-await lbe.writeFile('src/output.ts', content);
-await lbe.deleteFile('src/old.ts');
-await lbe.runShell('npm', ['test']);
-```
-
-Every call passes through the full 7-gate pipeline: local policy, key lifecycle, signature, rate limit, nonce, and audit.
-
-### 2. Node agents you launch — `run-node`
-
-Use `run-node` to launch any Node.js agent under the preload hook. The hook patches `fs` and `child_process` before the agent's entry module runs — including actions taken by the agent's own npm dependencies.
-
-```bash
-npx lbe-exec run-node ./agent.js
-npx lbe-exec run-node --mode enforce ./agent.js
 ```
-
-Patched APIs: `fs.writeFile`, `fs.writeFileSync`, `fs.rm`, `fs.rmSync`, `fs.unlink`, `fs.unlinkSync`, `fs.rename`, `fs.renameSync`, `fs.promises.*` variants, `child_process.spawn`, `spawnSync`, `exec`, `execSync`.
-
-### 3. Existing npm scripts — `lbe-exec npm`
-
-Inject the hook into any npm script via `NODE_OPTIONS`:
-
-```bash
-npx lbe-exec npm run agent
+[1] Schema         required fields and structural validity
+        ↓
+[2] Timestamp      permitted clock-skew window (±10 minutes)
+        ↓
+[3] Key lifecycle  trusted key, active, not expired
+        ↓
+[4] Signature      Ed25519 request authenticity
+        ↓
+[5] Rate limit     per-requester sliding-window limit
+        ↓
+[6] Nonce          single-use replay protection
+        ↓
+[7] Policy         configured authorization (deny-wins)
+        ↓
+  allow / deny / error — structured result returned to host
 ```
 
-> **Note:** `NODE_OPTIONS`-based injection is less reliable than `run-node`. Some runtimes strip or override `NODE_OPTIONS`. Use `run-node` when the agent entry point is known.
-
-### 4. Opaque or external agents — sandbox mode (future)
-
-For agents that run outside Node.js, inside containers, or as opaque binaries — sandbox mode is planned. Not available in this release.
+The WASM runtime owns all gate decisions. Your host receives the decision and acts on it. Nothing executes inside the runtime.
 
 ---
 
-### Init — non-destructive script injection
+## When a request is approved
 
-```bash
-npx lbe-exec init
-```
-
-Detects agent scripts in `package.json` and adds `:lbe` and `:lbe:enforce` variants alongside them. Originals are never overwritten.
+![Happy path — agent proposes action, identity confirmed, policy approved, governed write executed, audit chain extended, result returned to app.](https://unpkg.com/@letterblack/lbe-exec/assets/story-allow.jpg)
 
-Input:
-```json
-{ "scripts": { "agent": "node ./src/agent.js" } }
-```
+1. The agent produces a signed action proposal.
+2. Identity is confirmed against a locally held key — no network call required.
+3. The project policy is evaluated. The action is approved.
+4. The host executes the write or command inside the allowed workspace.
+5. The audit chain is extended — every approved action appends a hash-linked entry to the local log, permanently verifiable, impossible to silently remove.
+6. A structured result returns: whether it succeeded, which rules matched, and the audit entry identifier.
 
-Output:
-```json
-{
-  "scripts": {
-    "agent":              "node ./src/agent.js",
-    "agent:lbe":          "lbe-exec run-node --mode observe ./src/agent.js",
-    "agent:lbe:enforce":  "lbe-exec run-node --mode enforce ./src/agent.js",
-    "lbe:status":         "lbe-exec status",
-    "lbe:audit":          "lbe-exec audit"
-  }
-}
-```
-
-### Status and audit
-
-```bash
-npx lbe-exec status   # hook state, PID liveness, patched function table
-npx lbe-exec audit    # stream .lbe/events.jsonl as a formatted table
-```
-
-`status` reads `.lbe/runtime/hook-status.json` written by the hook at preload time and checks PID liveness in a separate process — no shared memory required.
+The application stays in control. @letterblack/lbe-core decides whether the action was permitted and hands the answer back. It does not execute for you.
 
 ---
 
-## Full governance
+## When a request is blocked
 
-For teams, compliance workflows, or named actors with distinct permission sets:
+![Deny path — policy rejection before a governed action, shell untouched, filesystem unchanged, audit entry written, final state clean.](https://unpkg.com/@letterblack/lbe-exec/assets/story-deny.jpg)
 
-```js
-import { createLBE, generateKeyPair, createKeyStore } from '@letterblack/lbe-core';
-
-const { secretKey, publicKey } = generateKeyPair();
-
-const lbe = createLBE({
-    secretKey,
-    keyId: 'prod-key',
-    keyStore: createKeyStore({ publicKey, keyId: 'prod-key' }),
-    policy: {
-        version: 1,
-        default: 'DENY',
-        requesters: {
-            'agent:writer': {
-                allowCommands: ['write_file', 'read_file'],
-                allowAdapters: ['file'],
-                filesystem: {
-                    roots:        ['./output/'],
-                    denyPatterns: ['*.key', '*.env']
-                }
-            }
-        }
-    }
-});
-
-const result = await lbe.execute({
-    actor:   'agent:writer',
-    intent:  'write_file',
-    target:  './output/report.md',
-    content: '# Report\n',
-    transaction: { backup: true, rollbackOnFailure: true, audit: true }
-});
-
-console.log(result.ok);        // true | false
-console.log(result.stage);     // 'executed' | 'validate' | 'invariant_gate' | ...
-console.log(result.commandId); // matches audit log entry
-```
+1. The agent proposes an action that is outside the permitted policy.
+2. The policy gate closes immediately. The WASM runtime stamps the request denied before any adapter is reached.
+3. The shell is untouched. The filesystem is unchanged.
+4. The denial is written to the immutable audit log — chain sealed, evidence preserved.
 
-Zero-config alternative — auto-generates keys and policy for `rootDir`:
-
-```js
-const lbe = createLBE({ rootDir: process.cwd() });
-await lbe.writeFile('data/output.txt', 'result\n');
-const text = await lbe.readFile('data/output.txt');
-```
+No partial execution. No silent failures. Denial is a first-class outcome, not an error.
 
 ---
 
-## How it works
+## What this covers
 
-```
-Agent
-  │  proposes intent
-  ▼
-Invariant Gate ── key present? policy signed? keyStore loaded?
-  │
-  ▼
-7-Gate Validation
-  ├── schema
-  ├── key lifecycle
-  ├── timestamp skew
-  ├── signature
-  ├── rate limit
-  ├── nonce replay
-  └── policy (deny-by-default)
-  │
-  ▼  all gates pass
-Adapter ── file | shell | noop
-  │
-  ▼
-Audit Log ── SHA-256 hash-chained JSONL, append-only
-```
-
-The controller is the only authority. Adapters execute — they do not decide.
+| Threat | Gate |
+|---|---|
+| Malformed or incomplete request | Schema |
+| Stale or replayed request | Timestamp + Nonce |
+| Tampered or expired key | Key lifecycle + Signature |
+| Excessive requests from one actor | Rate limit |
+| Action not permitted by project policy | Policy — deny-wins |
+| Agent writing outside project root | Scope check in host after decision |
 
 ---
 
-## Public SDK surface
+## What ships
 
-The published package (`@letterblack/lbe-core`) exposes one function:
-
-```ts
-export function execute(input: string): string;
-```
-
-`input` is a JSON-serialized `LBEExecuteInput`. The return value is a
-JSON-serialized `LBEExecuteOutput`. Full type definitions are in `types.d.ts`.
-
-```ts
-interface LBEExecuteOutput {
-  ok: boolean;
-  result: { type: 'allowed' | 'denied' | 'error'; action: string; data: Record<string, unknown> };
-  policy: { decision: 'allow' | 'deny' | 'escalate'; reason: string; rules: string[] };
-  trace:  { id: string; steps: unknown[]; hash: string };
-  error:  null | { code: string; message: string };
-}
 ```
-
----
-
-## Internal source API (private package only)
-
-These helpers exist in `@letterblack/lbe-core` (this package) for
-repository development and testing. They are **not** exported from the public
-`@letterblack/lbe-core` package.
-
-### `sandbox(root, opts?)` → `{ write, read, patch, lbe }`
-
-| Option | Default | Description |
-|---|---|---|
-| `audit` | `false` | Append to audit log on every operation |
-| `rollback` | `false` | Back up before write; restore on failure |
-| `state` | `'local'` | `'local'` → `~/.lbe/` · `'workspace'` → `.lbe/` inside project |
-
-### `createLBE(options)` → `{ execute, writeFile, readFile, exportLogs }`
-
-| Option | Type | Description |
-|---|---|---|
-| `rootDir` | `string` | Auto-configure keys, policy, and state for this directory |
-| `secretKey` | `string` | Ed25519 secret key (base64) |
-| `keyId` | `string` | Key identifier |
-| `policy` | `object` | Inline policy object |
-| `state` | `string` | `'local'` (default) · `'workspace'` · `{ adapter }` |
-| `logLevel` | `string` | `DEBUG` · `INFO` · `WARN` · `ERROR` |
-
-### Additional exports
-
-```js
-import { AVAILABLE_ADAPTERS } from '@letterblack/lbe-core/adapters';
-// → ['noop', 'shell', 'file']
-
-import {
-    validateCommand,
-    appendAudit,
-    createBackup, restoreBackup,
-    signEd25519, verifyEd25519, generateKeyPair,
-    createLogger, deepFreeze,
-    checkInvariants, assertInvariants, InvariantGateError
-} from '@letterblack/lbe-core';
+dist/index.js               WebAssembly runtime loader and execute()
+dist/cli.js                 Local CLI (npx lbe)
+dist/lbe_engine.wasm        Verified runtime binary
+dist/wasm.lock.json         Runtime integrity lock (SHA-256 of wasm binary)
+assets/lbe-gates.jpg        Gate sequence diagram
+assets/story-allow.jpg      Approved-request storyboard
+assets/story-deny.jpg       Blocked-request storyboard
+assets/runtime-boundary.svg Runtime boundary diagram
+assets/lbe-gates.png        Gate sequence diagram (full resolution)
+assets/story-allow.png      Approved-request storyboard (full resolution)
+assets/story-deny.png       Blocked-request storyboard (full resolution)
+types.d.ts                  TypeScript declarations
 ```
 
-## CLI
+At load time the runtime verifies `lbe_engine.wasm` against `wasm.lock.json`. A missing, modified, or swapped binary fails before any request is processed.
 
-| Command | Description |
-|---|---|
-| `npx lbe execute --input input.json` | Execute one JSON request through the public runtime |
-| `cat input.json \| npx lbe execute` | Execute one JSON request from stdin |
+Source code, controller implementation, adapters, tests, keys, and runtime state are not included.
 
 ---
 
-## Security model
-
-- **Ed25519 signatures** — every proposal is signed; the controller verifies before any gate runs
-- **Nonce replay protection** — each `commandId` is single-use; replays are hard-rejected
-- **Rate limiting** — per-requester, configurable window
-- **Timestamp skew guard** — rejects proposals outside ±10 minutes
-- **Policy signature verification** — the policy file itself is signed; tampering fails the invariant gate
-- **Immutable audit trail** — SHA-256 hash-chained JSONL; any deletion or edit is detectable
-- **Atomic writes** — all state files use write-then-rename; no partial state
-
-**What is never committed:**  
-`keys/secret.key` · `keys/*.key` · `config/keys.json` · `config/policy.sig.json` · `data/`
-
-**Scope — what this hardens against:**  
-Accidental writes outside allowed roots. Replay attacks. Policy drift. Audit log tampering. Rollback on failure.
-
-**Not in scope:**  
-Kernel-level process isolation. Network egress control. Multi-tenant workload separation.  
-This SDK does not sandbox the agent process — it governs the actions that agent routes through the SDK.
-
----
-
-## Changelog
-
-See [`CHANGELOG.md`](CHANGELOG.md).
-
----
-
-## License
-
-MIT — LetterBlack 2026
+## Limits
+
+This package validates requests routed through its runtime. It does not provide kernel-level process isolation, network-egress control, multi-tenant separation, or a hosted control plane.