@letterblack/lbe-core 1.3.4 → 1.3.6

package/src/cli/commands/logs.js

@@ -0,0 +1,53 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveWorkspaceState } from '../../state/index.js';
+
+const DEFAULT_LIMIT = 20;
+
+/**
+ * lbe logs [--limit <n>]
+ *
+ * Reads central lbe-events.jsonl and prints the last N entries.
+ * If the file does not exist, prints a clear "not yet" message — it means
+ * hook dual-write (alpha2 of the hook change) has not been enabled yet.
+ *
+ * Reads only. Does not write, migrate, or modify anything.
+ *
+ * @returns {{ eventsPath, count, entries, missing }}
+ */
+export async function logsCommand(opts) {
+    const workspaceRoot = path.resolve(opts.root || process.cwd());
+    const { paths } = resolveWorkspaceState(workspaceRoot);
+    const limit = opts.limit ? parseInt(opts.limit, 10) : DEFAULT_LIMIT;
+
+    if (!fs.existsSync(paths.events)) {
+        console.log('\nLBE Central Logs');
+        console.log('  No central logs yet. Hook dual-write not enabled.');
+        console.log(`  Expected at: ${paths.events}`);
+        console.log('');
+        return { eventsPath: paths.events, count: 0, entries: [], missing: true };
+    }
+
+    const raw = fs.readFileSync(paths.events, 'utf8').trim();
+    const lines = raw ? raw.split('\n') : [];
+
+    const entries = lines
+        .map(line => { try { return JSON.parse(line); } catch (_) { return null; } })
+        .filter(Boolean);
+
+    const tail = entries.slice(-limit);
+
+    console.log(`\nLBE Central Logs — last ${tail.length} of ${entries.length} entries`);
+    console.log(`  source: ${paths.events}\n`);
+
+    for (const entry of tail) {
+        const ts     = entry.ts ? new Date(entry.ts * 1000).toISOString() : '?';
+        const action = entry.action   || '?';
+        const dec    = entry.decision || '?';
+        const target = entry.path || entry.cmd || '';
+        console.log(`  [${ts}] ${dec.toUpperCase().padEnd(5)} ${action} ${target}`);
+    }
+    console.log('');
+
+    return { eventsPath: paths.events, count: entries.length, entries: tail, missing: false };
+}

package/src/cli/commands/openState.js

@@ -0,0 +1,44 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { resolveWorkspaceState } from '../../state/index.js';
+
+/**
+ * lbe open-state
+ *
+ * Resolves the central state directory and opens it in the system file manager.
+ * Always prints the path regardless of whether the open succeeds — so the user
+ * can copy-paste it even if the file manager call fails.
+ *
+ * Set env LBE_NO_OPEN=1 to skip the subprocess (used in tests and CI).
+ *
+ * @returns {{ stateDir, opened }}
+ */
+export async function openStateCommand(opts) {
+    const workspaceRoot = path.resolve(opts.root || process.cwd());
+    const { stateDir } = resolveWorkspaceState(workspaceRoot);
+
+    console.log(`\nLBE Central State Directory`);
+    console.log(`  ${stateDir}\n`);
+
+    if (process.env.LBE_NO_OPEN === '1') {
+        return { stateDir, opened: false };
+    }
+
+    let opened = false;
+    try {
+        if (process.platform === 'win32') {
+            spawnSync('explorer.exe', [stateDir], { detached: true, stdio: 'ignore' });
+            opened = true;
+        } else if (process.platform === 'darwin') {
+            spawnSync('open', [stateDir], { detached: true, stdio: 'ignore' });
+            opened = true;
+        } else {
+            spawnSync('xdg-open', [stateDir], { detached: true, stdio: 'ignore' });
+            opened = true;
+        }
+    } catch (_) {
+        // Non-fatal — path was already printed above.
+    }
+
+    return { stateDir, opened };
+}

package/src/cli/commands/policyAdd.js

@@ -0,0 +1,8 @@
+import { addLocalPolicyRule } from '../../core/localPolicy.js';
+
+export async function policyAddCommand(opts = {}) {
+    const result = addLocalPolicyRule(opts.root || process.cwd(), {
+        effect: opts.effect, type: opts.type, pattern: opts.pattern, from: opts.from
+    }, opts.mode);
+    console.log(JSON.stringify(result, null, 2));
+}

package/src/cli/commands/policyMode.js

@@ -0,0 +1,7 @@
+import { loadLocalPolicy, writeLocalPolicy } from '../../core/localPolicy.js';
+
+export async function policyModeCommand(mode, opts = {}) {
+    const loaded = loadLocalPolicy(opts.root || process.cwd(), mode);
+    writeLocalPolicy(loaded.root, { ...loaded.policy, mode });
+    console.log(JSON.stringify({ mode, policy: loaded.policyPath }, null, 2));
+}

package/src/cli/commands/policySign.js

@@ -0,0 +1,72 @@
+// src/cli/commands/policySign.js
+// Sign policy.json and write signature envelope
+
+import fs from 'fs';
+import path from 'path';
+import { createPolicySignatureEnvelope } from '../../core/policySignature.js';
+
+export async function policySignCommand(opts) {
+    const policyPath = path.resolve(opts.config || opts.policy || '.lbe/config/policy.default.json');
+    const sigPath = path.resolve(opts['policy-sig'] || '.lbe/config/policy.sig.json');
+    const secretKeyPath = path.resolve(opts['secret-key-file'] || '.lbe/keys/secret.key');
+    const keyId = String(opts['policy-key-id'] || 'policy-signer-v1-2026Q1');
+
+    if (!fs.existsSync(policyPath)) {
+        console.error(JSON.stringify({
+            status: 'error',
+            error: 'POLICY_FILE_MISSING',
+            message: `Policy file not found: ${policyPath}`
+        }, null, 2));
+        process.exit(1);
+    }
+
+    if (!fs.existsSync(secretKeyPath)) {
+        console.error(JSON.stringify({
+            status: 'error',
+            error: 'SECRET_KEY_MISSING',
+            message: `Secret key file not found: ${secretKeyPath}`
+        }, null, 2));
+        process.exit(1);
+    }
+
+    const policyObj = JSON.parse(fs.readFileSync(policyPath, 'utf8'));
+    if (typeof policyObj.version === 'undefined' || typeof policyObj.createdAt === 'undefined') {
+        console.error(JSON.stringify({
+            status: 'error',
+            error: 'POLICY_VERSION_METADATA_MISSING',
+            message: 'Policy must include version and createdAt before signing'
+        }, null, 2));
+        process.exit(8);
+    }
+
+    const secretKeyB64 = fs.readFileSync(secretKeyPath, 'utf8').trim();
+    const signResult = createPolicySignatureEnvelope({
+        policyObj,
+        secretKeyB64,
+        keyId
+    });
+
+    if (!signResult.ok) {
+        console.error(JSON.stringify({
+            status: 'error',
+            error: signResult.reason || 'POLICY_SIGN_FAILED',
+            message: signResult.message
+        }, null, 2));
+        process.exit(8);
+    }
+
+    const outDir = path.dirname(sigPath);
+    if (!fs.existsSync(outDir)) {
+        fs.mkdirSync(outDir, { recursive: true });
+    }
+    fs.writeFileSync(sigPath, JSON.stringify(signResult.envelope, null, 2));
+
+    console.log(JSON.stringify({
+        status: 'ok',
+        message: 'Policy signature written',
+        policy: policyPath,
+        policySig: sigPath,
+        keyId
+    }, null, 2));
+    process.exit(0);
+}

package/src/cli/commands/proof.js

@@ -0,0 +1,102 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveWorkspaceState } from '../../state/index.js';
+import { loadLatestProof } from '../../state/proofRunner.js';
+
+function buildPublicProof(proof, targets) {
+    const lastTarget = Array.isArray(targets) && targets.length > 0
+        ? targets[targets.length - 1]
+        : null;
+
+    // Redact: only expose safe, non-identifying fields
+    const pub = {
+        result:      proof.result,
+        profile:     proof.profile,
+        checks:      proof.checks_run || [],
+        allow_deny:  (proof.failures && proof.failures.length > 0) ? 'deny' : 'allow',
+    };
+
+    if (lastTarget) {
+        pub.target_type  = lastTarget.kind        || null;
+        pub.target_label = lastTarget.label       || null;
+        // component_file is a relative path — safe to include as-is
+        pub.target_file  = lastTarget.component_file || null;
+    }
+
+    // Include failure reasons but NOT the raw file paths
+    if (proof.failures && proof.failures.length > 0) {
+        pub.failure_reasons = proof.failures.map(f => ({ check: f.check, reason: f.reason }));
+    }
+
+    return pub;
+}
+
+/**
+ * lbe proof [--json] [--public] [--root <path>]
+ *
+ * Reads proof/latest.json from the central state store and prints it.
+ * Does not re-run proof; use the programmatic API for that.
+ *
+ * @returns {{ result, profile, found } | null}
+ */
+export async function proofCommand(opts) {
+    const workspaceRoot = path.resolve(opts.root || process.cwd());
+    const { stateDir } = resolveWorkspaceState(workspaceRoot);
+
+    const proof = loadLatestProof(stateDir);
+    const isPublic = opts.public === true || opts.public === 'true';
+    const isJson   = opts.json   === true || opts.json   === 'true' || isPublic;
+
+    if (!proof) {
+        if (isJson) {
+            console.log(JSON.stringify({ found: false, message: 'No proof record found. Run lbe proof after using the hook.' }, null, 2));
+        } else {
+            console.log('\nNo proof record found.');
+            console.log('Use the hook-protected workflow and then run: lbe proof\n');
+        }
+        return { found: false };
+    }
+
+    // Load targets for public redaction
+    let targets = [];
+    if (isPublic) {
+        const targetPath = path.join(stateDir, 'target_registry.jsonl');
+        if (fs.existsSync(targetPath)) {
+            const raw = fs.readFileSync(targetPath, 'utf8').trim();
+            targets = raw ? raw.split('\n').reduce((acc, l) => {
+                try { acc.push(JSON.parse(l)); } catch (_) { /* ignore */ }
+                return acc;
+            }, []) : [];
+        }
+    }
+
+    if (isPublic) {
+        const pub = buildPublicProof(proof, targets);
+        console.log(JSON.stringify(pub, null, 2));
+        return { found: true, result: proof.result, profile: proof.profile, public: true };
+    }
+
+    if (isJson) {
+        console.log(JSON.stringify(proof, null, 2));
+        return { found: true, result: proof.result, profile: proof.profile };
+    }
+
+    // Human-readable output
+    const resultMark = proof.result === 'PASS' ? '✓' : proof.result === 'WEAK_PROOF' ? '⚠' : '✗';
+    const workspace  = path.basename(workspaceRoot);
+    console.log(`\nLBE Proof — ${workspace}`);
+    console.log(`  Result         ${resultMark} ${proof.result}`);
+    console.log(`  Profile        ${proof.profile}`);
+    console.log(`  Changed files  ${(proof.files_changed || []).length}`);
+    console.log(`  Checks run     ${(proof.checks_run || []).join(', ')}`);
+    if (proof.failures && proof.failures.length > 0) {
+        console.log(`  Failures       ${proof.failures.length}`);
+        for (const f of proof.failures) {
+            console.log(`    • [${f.check}] ${f.reason}${f.file ? ': ' + f.file : ''}`);
+        }
+    }
+    console.log(`  Recorded at    ${proof.ts}`);
+    console.log('');
+
+    return { found: true, result: proof.result, profile: proof.profile };
+}

package/src/cli/commands/run.js

@@ -0,0 +1,342 @@
+// src/cli/commands/run.js
+// Validate and execute a proposal
+
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { validateCommand } from '../../core/validator.js';
+import { NonceStore } from '../../core/nonceStore.js';
+import { executeAdapter } from '../../adapters/index.js';
+import { appendAudit } from '../../core/auditLog.js';
+import { loadKeysStore } from '../../core/trustedKeys.js';
+import { RequestRateLimiter } from '../../core/requestRateLimiter.js';
+import { verifyPolicySignature } from '../../core/policySignature.js';
+import { validateAndUpdatePolicyVersionState } from '../../core/policyVersionGuard.js';
+import { getApprovalManager } from '../../core/approval-token.js';
+import { createBackup, restoreBackup } from '../../core/backup.js';
+import { loadLocalPolicy, evaluateLocalPolicy, auditLocalPolicy } from '../../core/localPolicy.js';
+
+function sha256(obj) {
+    return crypto.createHash('sha256').update(JSON.stringify(obj)).digest('hex');
+}
+
+export async function runCommand(opts) {
+    const { in: inFile } = opts;
+    const config = opts.config || opts.policy;
+    const pubKey = opts['pub-key'];
+    const keysStorePath = opts['keys-store'] || path.resolve('.lbe/config/keys.json');
+    const policySigPath = opts['policy-sig'] || path.resolve('.lbe/config/policy.sig.json');
+    const policyStatePath = opts['policy-state'] || path.resolve('.lbe/data/policy.state.json');
+    const allowUnsignedPolicy = opts['policy-unsigned-ok'] === true || String(opts['policy-unsigned-ok']).toLowerCase() === 'true';
+    // Validate required arguments
+    if (!inFile) {
+        console.error('Error: --in <file> is required');
+        process.exit(1);
+    }
+
+    // Read proposal file
+    let proposal;
+    try {
+        const filePath = path.resolve(inFile);
+        const content = fs.readFileSync(filePath, 'utf-8');
+        proposal = JSON.parse(content);
+    } catch (error) {
+        console.error(JSON.stringify({
+            status: 'error',
+            error: 'INVALID_PROPOSAL_FILE',
+            message: error.message
+        }));
+        process.exit(5);
+    }
+
+    // Load policy
+    let policy;
+    try {
+        const policyPath = config || path.resolve('.lbe/config/policy.default.json');
+        if (!fs.existsSync(policyPath)) {
+            console.error(JSON.stringify({
+                status: 'error',
+                error: 'MISSING_POLICY',
+                message: `Policy file not found: ${policyPath}`
+            }));
+            process.exit(1);
+        }
+        const policyContent = fs.readFileSync(policyPath, 'utf-8');
+        policy = JSON.parse(policyContent);
+    } catch (error) {
+        console.error(JSON.stringify({
+            status: 'error',
+            error: 'INVALID_POLICY',
+            message: error.message
+        }));
+        process.exit(1);
+    }
+
+    // Project-local rules are controller-owned and take precedence over any
+    // observer allow. Observe mode records a would-deny decision only.
+    const rootDir = process.cwd();
+    let localPolicy;
+    try {
+        localPolicy = loadLocalPolicy(rootDir);
+    } catch (error) {
+        console.error(JSON.stringify({ status: 'error', error: 'LOCAL_POLICY_INVALID', message: error.message }));
+        process.exit(1);
+    }
+    const localDecision = evaluateLocalPolicy(localPolicy.policy, rootDir, {
+        target: proposal.payload?.target,
+        command: proposal.payload?.cmd
+    });
+    const localBlocked = localPolicy.policy.mode === 'enforce' && !localDecision.allowed;
+    auditLocalPolicy(rootDir, {
+        commandId: proposal.commandId || 'N/A', requesterId: proposal.requesterId || 'unknown',
+        mode: localPolicy.policy.mode, decision: localBlocked ? 'deny' : 'allow',
+        wouldDeny: !localDecision.allowed, ruleIds: localDecision.winningRules.map(rule => rule.id)
+    });
+    if (localBlocked) {
+        console.error(JSON.stringify({ status: 'blocked', error: 'LOCAL_POLICY_DENY', ruleIds: localDecision.winningRules.map(rule => rule.id) }, null, 2));
+        process.exit(2);
+    }
+
+    // Load key store (preferred) with legacy pub-key fallback
+    const keyStoreResult = loadKeysStore(keysStorePath);
+    const keyStore = keyStoreResult.ok ? keyStoreResult.store : null;
+
+    // Preflight: policy signature verification (strict by default)
+    const policySigCheck = verifyPolicySignature({
+        policyObj: policy,
+        keyStore,
+        policySigPath,
+        allowUnsigned: allowUnsignedPolicy
+    });
+    if (!policySigCheck.ok) {
+        console.error(JSON.stringify({
+            status: 'error',
+            error: policySigCheck.reason,
+            message: policySigCheck.message
+        }, null, 2));
+        process.exit(8);
+    }
+
+    const versionCheck = validateAndUpdatePolicyVersionState({
+        policyObj: policy,
+        statePath: policyStatePath,
+        maxCreatedAtSkewSec: policy?.security?.maxPolicyCreatedAtSkewSec
+    });
+    if (!versionCheck.ok) {
+        console.error(JSON.stringify({
+            status: 'error',
+            error: versionCheck.reason,
+            message: versionCheck.message
+        }, null, 2));
+        process.exit(8);
+    }
+
+    // Load nonce store
+    const nonceDb = new NonceStore(path.resolve('.lbe/data/nonce.db.json'));
+    await nonceDb.load();
+
+    if (!keyStore && !pubKey) {
+        console.error(JSON.stringify({
+            status: 'error',
+            error: 'MISSING_KEY_MATERIAL',
+            message: `${keyStoreResult.message}. Provide --pub-key/--pub-key-file or create .lbe/config/keys.json`
+        }));
+        process.exit(1);
+    }
+
+    // Load requester rate limiter
+    const rateLimiter = new RequestRateLimiter(path.resolve('.lbe/data/rate-limit.db.json'));
+    await rateLimiter.load();
+
+    // Validate command
+    const validateResult = validateCommand({
+        commandObj: proposal,
+        pubKeyB64: pubKey,
+        keyStore,
+        nonceDb,
+        policy,
+        rateLimiter
+    });
+
+    if (!validateResult.valid) {
+        // Persist state from checks that may record entries prior to rejection.
+        try {
+            await nonceDb.save();
+            await rateLimiter.save();
+        } catch {
+            // Continue with rejection path even if state persistence fails.
+        }
+
+        const output = {
+            status: 'invalid',
+            commandId: proposal.commandId || 'N/A',
+            checks: validateResult.checks,
+            errors: validateResult.errors || [],
+            executionResult: null
+        };
+        console.error(JSON.stringify(output, null, 2));
+
+        // Load audit log and append this rejection
+        const auditPath = path.resolve('.lbe/data/audit.log.jsonl');
+        try {
+            appendAudit(auditPath, {
+                commandId: proposal.commandId || 'N/A',
+                status: 'rejected',
+                requesterId: proposal.requesterId || 'unknown',
+                payloadHash: sha256(proposal),
+                reason: validateResult.checks,
+                timestamp: new Date().toISOString()
+            });
+        } catch (auditErr) {
+            console.error(JSON.stringify({
+                status: 'error',
+                error: 'AUDIT_WRITE_FAILED',
+                message: auditErr.message
+            }));
+            process.exit(10);
+        }
+
+        if (validateResult.checks.schema === false) process.exit(5);
+        if (validateResult.checks.signature === false) process.exit(3);
+        if (validateResult.checks.nonce === false) process.exit(4);
+        if (validateResult.checks.timestamp === false) process.exit(6);
+        if (validateResult.checks.rateLimit === false) process.exit(7);
+        if (validateResult.checks.policy === false) process.exit(2);
+        process.exit(9);
+    }
+
+    const risk = validateResult.risk || 'LOW';
+    const adapterName = proposal.payload.adapter || 'shell';
+    const requesterPolicy = policy.requesters?.[proposal.requesterId];
+
+    // Approval gate — pause if the requester policy marks this risk level for approval
+    const approvalRule = requesterPolicy?.requireApproval;
+    const approvalRequired = approvalRule === true
+        || (Array.isArray(approvalRule) && (
+            approvalRule.includes(risk)
+            || approvalRule.includes('*')
+            || (['HIGH', 'CRITICAL'].includes(risk) && approvalRule.includes('HIGH+'))
+        ));
+
+    if (approvalRequired) {
+        const mgr = getApprovalManager();
+        const tokenId = mgr.createToken(proposal.commandId, {
+            requesterId: proposal.requesterId,
+            adapter: adapterName,
+            risk
+        });
+
+        await nonceDb.save().catch(() => {});
+        await rateLimiter.save().catch(() => {});
+
+        console.log(JSON.stringify({
+            status: 'approval_required',
+            commandId: proposal.commandId || 'N/A',
+            risk,
+            approvalToken: tokenId,
+            message: `${risk} risk operation requires operator approval. Approve with: lbe approve --token ${tokenId}`
+        }, null, 2));
+        process.exit(11);
+    }
+
+    // Backup — create before execution for file adapter or when --backup flag is set
+    let backup = null;
+    const shouldBackup = opts.backup === true || adapterName === 'file';
+    if (shouldBackup && proposal.payload.target) {
+        try {
+            backup = createBackup(path.resolve(proposal.payload.target));
+        } catch {
+            // Non-fatal — execution continues without backup
+        }
+    }
+
+    // Execute with appropriate adapter
+    let executionResult;
+    try {
+        executionResult = await executeAdapter(adapterName, proposal, policy, requesterPolicy);
+    } catch (error) {
+        executionResult = {
+            adapter: adapterName,
+            status: 'error',
+            error: error.message,
+            exitCode: 1
+        };
+    }
+
+    const executionFailed = executionResult.status === 'error' || executionResult.exitCode !== 0;
+
+    // Rollback on failure — restore backup if execution failed and we have one
+    let rollbackResult = null;
+    if (executionFailed && backup && opts['rollback-on-failure'] !== false) {
+        try {
+            rollbackResult = restoreBackup(backup);
+        } catch (e) {
+            rollbackResult = { restored: false, error: e.message };
+        }
+    }
+
+    // Post-execution validation — verify target exists after a write/patch
+    let postValidation = null;
+    if (!executionFailed && proposal.payload.target) {
+        const writeActions = ['write', 'patch'];
+        if (writeActions.includes(proposal.payload.action)) {
+            const exists = fs.existsSync(path.resolve(proposal.payload.target));
+            postValidation = { ok: exists, check: 'target_exists', target: proposal.payload.target };
+            if (!exists && backup) {
+                rollbackResult = restoreBackup(backup);
+                executionResult.status = 'error';
+            }
+        }
+    }
+
+    // Log to audit trail
+    // payloadHash: SHA-256 of the validated proposal — proves what the adapter received
+    // executionHash: SHA-256 of the adapter result — proves what the adapter returned
+    // Together these bind the validation result to the execution result in the immutable log
+    const auditPath = path.resolve('.lbe/data/audit.log.jsonl');
+    try {
+        appendAudit(auditPath, {
+            commandId: proposal.commandId || 'N/A',
+            status: rollbackResult?.restored ? 'rolled_back' : (executionResult.status || 'completed'),
+            requesterId: proposal.requesterId || 'unknown',
+            payloadHash: sha256(proposal),
+            executionHash: sha256(executionResult),
+            adapter: executionResult.adapter,
+            riskLevel: risk,
+            exitCode: executionResult.exitCode || 0,
+            rolledBack: rollbackResult?.restored || false,
+            timestamp: new Date().toISOString()
+        });
+    } catch (auditErr) {
+        console.error(JSON.stringify({
+            status: 'error',
+            error: 'AUDIT_WRITE_FAILED',
+            message: auditErr.message
+        }));
+        process.exit(10);
+    }
+
+    // Save nonce DB (records the nonce as used)
+    await nonceDb.save();
+    await rateLimiter.save();
+
+    // Output structured result
+    const output = {
+        status: executionFailed || (postValidation && !postValidation.ok) ? 'failed' : 'executed',
+        commandId: proposal.commandId || 'N/A',
+        risk,
+        checks: validateResult.checks,
+        executionResult: {
+            adapter: executionResult.adapter,
+            status: executionResult.status || 'completed',
+            output: executionResult.output || executionResult.error || '',
+            exitCode: executionResult.exitCode || 0
+        },
+        backup: backup ? { path: backup.backupPath, existed: backup.existed, hash: backup.hash } : null,
+        rollback: rollbackResult,
+        postValidation
+    };
+
+    console.log(JSON.stringify(output, null, 2));
+    process.exit(executionResult.exitCode || 0);
+}