@letterblack/lbe-core 1.3.3 → 1.3.5

package/README.md

@@ -1,506 +1,167 @@
-# LetterBlack LBE
-
-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.
-
-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
-
-```bash
-npm install @letterblack/lbe-core
-npx lbe init
-npx lbe status
-npx lbe logs
-npx lbe proof --public
-npx lbe open-state
-```
-
-`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.
-
-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.
-
----
-
-# 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.
+# @letterblack/lbe-core
 
----
-
-## 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.
+LBE Core is **local execution control for AI agents**.
 
-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.
+It evaluates file and shell actions routed through its execution boundary, records local evidence, and returns an allow/deny/proof outcome before agent work is treated as complete.
 
-## 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:
+LBE is not an AI model, IDE, full OS sandbox, cloud monitor, or hosted control plane. It only controls actions that are routed through LBE.
 
 ```text
-src/core/
-src/adapters/
-src/cli/
-scripts/
-test/
-keys/
-data/
-node_modules/
-*.map
+Agent wants to act
+        ↓
+LBE validates workspace, policy, target, and evidence
+        ↓
+allow / deny / weak proof / error
+        ↓
+Host executes only if LBE approved
+        ↓
+Audit and proof records are written locally
 ```
 
 ---
 
-## Install
-
-Internal source workspace:
+## Install and start
 
 ```bash
-npm install @letterblack/lbe-core
-```
-
-Public users install:
-
-```bash
-npm install @letterblack/lbe-core
+npm install @letterblack/lbe-core
+npx lbe init
+npx lbe status
+npx lbe logs
+npx lbe proof --public
+npx lbe open-state
 ```
 
-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.
+Requires Node.js `>= 20.9.0`.
 
----
+Command summary:
 
-## 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
-```
+| Command | Purpose |
+|---|---|
+| `npx lbe init` | Initialize LBE state for the current workspace |
+| `npx lbe status` | Show workspace policy, state, and proof status |
+| `npx lbe logs` | Show recent local LBE audit events |
+| `npx lbe open-state` | Open the central local state folder for this workspace |
+| `npx lbe proof` | Show the latest private proof result |
+| `npx lbe proof --json` | Print the latest proof as JSON |
+| `npx lbe proof --public` | Print a redacted proof safe for public sharing |
+| `npx lbe status --all` | List known local workspaces from the workspace registry |
 
 ---
 
-## 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.
+## What LBE does
 
----
+LBE gives agent builders a local execution boundary:
 
-## Add what you need
+- validates requested file and shell actions before execution
+- keeps governed actions inside the intended workspace
+- records local audit evidence
+- tracks intent, target, file-index snapshots, and proof results
+- supports private proof and public/redacted proof output
+- preserves legacy `.lbe/events.jsonl` logs while using central local state
 
-**Audit — see exactly what changed and when:**
-```js
-const sb = sandbox('./workspace', { audit: true });
-// appends to ~/.lbe/workspaces/<id>/audit.log.jsonl
-```
+Most systems ask only:
 
-**Rollback — undo failed writes automatically:**
-```js
-const sb = sandbox('./workspace', { audit: true, rollback: true });
-// backs up before every write, restores on failure
+```text
+Did the user approve this?
 ```
 
-**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.
+LBE asks a stricter question:
 
-To keep state inside the project instead (for team sharing):
-```js
-const sb = sandbox('./workspace', { state: 'workspace' });
-// writes to .lbe/ inside your project root
+```text
+Is this exact action allowed to reach the filesystem or terminal, and can we prove what happened?
 ```
 
 ---
 
-## 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).
-
----
-
-## Agent Safe Execution
-
-LBE Agent Safe Execution intercepts Node.js file and shell actions before they mutate the workspace.
-
-Choose the integration path that matches how your agent runs:
+## Local state and proof
 
-### 1. Agents you own — direct integration at the dispatch point
+LBE keeps state locally in a central per-user state folder. Each workspace has a stable workspace ID and its own event log.
 
-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.
+In v1.3, an existing `.lbe/events.jsonl` remains local fallback truth and is imported into central state once. The source file is preserved.
 
-```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']);
-```
+Proof combines:
 
-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`
+```text
+intent
+  ↓
+target
+  ↓
+file-index before action
+  ↓
+LBE audit event
+  ↓
+file-index after action
+  ↓
+proof/latest.json
+```
+
+Proof results:
+
+| Result | Meaning |
+|---|---|
+| `PASS` | Evidence is complete and actual changes match declared intent |
+| `FAIL` | Evidence violates intent, policy, or expected file changes |
+| `WEAK_PROOF` | Target evidence was uncertain or required user confirmation |
 
-Inject the hook into any npm script via `NODE_OPTIONS`:
+Use:
 
 ```bash
-npx lbe-exec npm run agent
+npx lbe proof --public
 ```
 
-> **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.
+for a redacted proof summary. Public proof redacts private paths, raw internal IDs, full diffs, hashes, and sensitive failure details.
 
 ---
 
-### Init — non-destructive script injection
-
-```bash
-npx lbe-exec init
-```
-
-Detects agent scripts in `package.json` and adds `:lbe` and `:lbe:enforce` variants alongside them. Originals are never overwritten.
-
-Input:
-```json
-{ "scripts": { "agent": "node ./src/agent.js" } }
-```
-
-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"
-  }
-}
-```
+## What ships
 
-### Status and audit
+The npm package ships the packaged runtime boundary, not the private source tree.
 
-```bash
-npx lbe-exec status   # hook state, PID liveness, patched function table
-npx lbe-exec audit    # stream .lbe/events.jsonl as a formatted table
+```text
+bin/lbe.js                    CLI shim
+dist/cli/lbe.js               Bundled CLI runtime
+dist/hooks/register.cjs       Hook preload runtime
+dist/state/index.cjs          Packaged CJS state resolver
+dist/state/appendCentral.cjs  Packaged central JSONL append helper
+README.md
+Release-README.md
+CHANGELOG.md
+LICENSE
+package.json
 ```
 
-`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 npm package must not include private implementation folders such as `src/core/**`, tests, local `.lbe/**` state, AppData state, diagnostic helpers, private keys, or workspace-local proof artifacts.
 
 ---
 
-## Full governance
-
-For teams, compliance workflows, or named actors with distinct permission sets:
-
-```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
-```
-
-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');
-```
+## Limits
 
----
+LBE controls only actions routed through its execution boundary.
 
-## How it works
+It does not provide:
 
-```
-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
-```
+- kernel-level process isolation
+- network-egress control
+- multi-tenant separation
+- hosted monitoring
+- universal control over tools outside LBE's execution boundary
 
-The controller is the only authority. Adapters execute — they do not decide.
+Central writes are best-effort. Local logs remain local.
 
 ---
 
-## Public SDK surface
-
-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 };
-}
-```
+## Release status
 
----
+Current aligned release:
 
-## 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';
+```text
+@letterblack/lbe-core@1.3.3
 ```
 
-## CLI
-
-| 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 |
-
----
-
-## 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).
+Earlier `1.3.0`, `1.3.1`, and `1.3.2` builds are superseded by `1.3.3`.
 
 ---
 
-## License
+## One-sentence summary
 
-MIT — LetterBlack 2026
+LBE Core does not make the agent smarter. It makes the agent's execution path controlled, evidence-backed, and locally auditable.