@letterblack/lbe-core 1.3.0

package/.githooks/pre-commit

@@ -0,0 +1,2 @@
+#!/bin/sh
+node letterblack-sentinel/scripts/mainhead-guard.mjs

package/.githooks/pre-push

@@ -0,0 +1,2 @@
+#!/bin/sh
+node letterblack-sentinel/scripts/mainhead-guard.mjs

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+## 1.3.0 — 2026-06-23
+
+### Added
+- Central local workspace state, proof summaries, and one-time import of legacy
+  `.lbe/events.jsonl` entries while preserving the original local log.
+
+## 1.2.0 — 2026-06-20
+
+### Added
+- **Real JS governance engine** — `createLBE()` now uses the full 7-gate validation pipeline (schema → key lifecycle → timestamp skew → rate limit → nonce replay → policy) with backup, rollback, and audit. Previously backed by a thin WASM wrapper.
+- **Observer mode** — `createLBE({ mode: 'observe' })` or `npx lbe observe`. All gates run silently, audit log is written, nothing is blocked. Default for new and half-built projects.
+- **Policy file** (`lbe.policy.json`) — human-readable rule store per project. Records `effect`, `type`, `pattern`, the original user message (`from`), and timestamp (`at`). Deny always wins over allow.
+- **New CLI commands:**
+  - `npx lbe observe` — switch to observer mode
+  - `npx lbe enforce` — switch to enforcement mode
+  - `npx lbe policy` — list all rules with source context
+- **Universal CLI interface** — non-JS projects (Python, Rust, Go, any language) can pipe JSON to `npx lbe execute`. Exit 0 = allowed, exit 1 = denied, exit 2 = error.
+- **Language-agnostic design** — WASM runtime path documented as the path to non-JS bindings. JS engine is the current production runtime.
+
+### Changed
+- `LBEResult` now includes `commandId`, `stage`, `risk`, `output` fields.
+- `LBEOptions` removes `policy_mode` / `timeout_ms` — these are managed by the governance engine internally.
+- `wrapTools().dispatch()` now returns `Promise<LBEResult>` (async) to match the real engine contract.
+- Types updated throughout to reflect observer mode result shape (`LBEObservedResult`).
+
+---
+
+## 1.0.4 — 2026-06-19
+
+### Removed
+- MCP execution surface — `lbe-mcp` command, MCP adapter, and configuration examples removed.  
+  An MCP server only offers LBE as one optional tool; agent hosts with native tools can act outside that boundary, so it cannot enforce the governance boundary. See `docs/decisions/ADR-001-remove-mcp-execution-surface.md`.
+- HTTP server surface — `lbe-serve` command and HTTP adapter removed.  
+  An HTTP endpoint replicates governance in a separate process and creates a second attack surface without guaranteeing the calling agent routes through it. See `docs/decisions/ADR-002-remove-http-server-surface.md`.
+
+### Changed
+- Established SDK-only product boundary: LBE ships as one local SDK and CLI embedded in the caller's application. No daemon, host platform, Docker deployment, or companion system. See `docs/decisions/ADR-003-sdk-only-product-boundary.md`.
+- Workspace pruned to SDK-only source; all optional execution surfaces removed from `src/`, `bin/`, and CI config.
+- Public package identity (`LBE_PUBLIC_PACKAGE_NAME`, `LBE_PUBLIC_PACKAGE_VERSION`) is now parameterised via environment variables in the build script.
+- Test command made portable across Node.js versions (no `--experimental-vm-modules` flag needed).
+
+### Public surface
+The public package (`@letterblack/lbe-sdk`) exports exactly one function:
+
+```ts
+export function execute(input: string): string;
+```
+
+No server, daemon, MCP surface, or optional execution layer ships in the public package.
+
+---
+
+## 1.0.3 and earlier
+
+Pre-release development. No public changelog maintained.

package/LICENSE

@@ -0,0 +1 @@
+SEE LICENSE IN LICENSE

package/README.md

@@ -0,0 +1,506 @@
+# 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-sdk
+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-sdk`.
+
+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-sdk`. 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:
+
+```bash
+npm install @letterblack/lbe-core
+```
+
+Public users install:
+
+```bash
+npm install @letterblack/lbe-sdk
+```
+
+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-sdk';
+
+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-sdk` package.
+
+---
+
+## 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.
+
+To keep state inside the project instead (for team sharing):
+```js
+const sb = sandbox('./workspace', { state: 'workspace' });
+// writes to .lbe/ inside your project root
+```
+
+---
+
+## 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:
+
+### 1. Agents you own — direct integration at the dispatch point
+
+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
+```
+
+> **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.
+
+---
+
+### 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"
+  }
+}
+```
+
+### 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.
+
+---
+
+## 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');
+```
+
+---
+
+## How it works
+
+```
+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.
+
+---
+
+## Public SDK surface
+
+The published package (`@letterblack/lbe-sdk`) 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 private package) for
+repository development and testing. They are **not** exported from the public
+`@letterblack/lbe-sdk` 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';
+```
+
+## 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).
+
+---
+
+## License
+
+MIT — LetterBlack 2026