@letterblack/lbe-core 1.3.4 → 1.3.5

package/src/cli/commands/status.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveWorkspaceState } from '../../state/index.js';
+import { stateRoot } from '../../state/stateRoot.js';
+import { isWorkspaceRegistryReadable, listWorkspaces } from '../../state/workspaceRegistry.js';
+
+/**
+ * lbe status
+ *
+ * Resolves central state for the workspace and prints a summary.
+ * Policy authority stays in .lbe/policy.json — this command reads it
+ * for display only. It does not modify or migrate anything.
+ *
+ * @returns {{ workspaceId, stateDir, policySource, policyMode, hasProof, hasEvents }}
+ */
+export async function statusCommand(opts) {
+    if (opts.all) {
+        const registryPath = opts.registryPath || path.join(stateRoot(), 'registry.json');
+        if (!isWorkspaceRegistryReadable(registryPath)) {
+            console.log('Workspace registry unreadable');
+            return { workspaces: [], registryReadable: false };
+        }
+
+        const workspaces = listWorkspaces(registryPath);
+        if (workspaces.length === 0) {
+            console.log('No known workspaces yet');
+            return { workspaces, registryReadable: true };
+        }
+
+        console.log('\nKnown LBE workspaces');
+        for (const workspace of workspaces) {
+            console.log(`  ${workspace.alias}`);
+            console.log(`    workspace_id ${workspace.workspaceId}`);
+            console.log(`    path         ${workspace.path}`);
+            console.log(`    last_active  ${workspace.last_active}`);
+        }
+        console.log('');
+        return { workspaces, registryReadable: true };
+    }
+
+    const workspaceRoot = path.resolve(opts.root || process.cwd());
+    const { stateDir, workspaceId, paths } = resolveWorkspaceState(workspaceRoot);
+
+    // ── Policy source (read-only, .lbe/policy.json is authoritative) ──────────
+    const policyPath = path.join(workspaceRoot, '.lbe', 'policy.json');
+    let policySource = 'not found';
+    let policyMode   = 'unknown';
+    if (fs.existsSync(policyPath)) {
+        try {
+            const policy = JSON.parse(fs.readFileSync(policyPath, 'utf8'));
+            policyMode   = policy.mode || 'unknown';
+            policySource = policyPath;
+        } catch (_) {
+            policySource = policyPath + ' (unreadable)';
+        }
+    }
+
+    // ── Central state presence ─────────────────────────────────────────────────
+    const hasProof  = fs.existsSync(paths.proofLatest);
+    const hasEvents = fs.existsSync(paths.events);
+
+    // ── Output ─────────────────────────────────────────────────────────────────
+    console.log(`\nLBE Central State — ${workspaceRoot}`);
+    console.log(`  workspace_id  ${workspaceId}`);
+    console.log(`  state_dir     ${stateDir}`);
+    console.log(`  policy_source ${policySource}`);
+    console.log(`  policy_mode   ${policyMode}`);
+    console.log(`  central_proof ${hasProof  ? paths.proofLatest : 'No central proof yet'}`);
+    console.log(`  central_logs  ${hasEvents ? paths.events      : 'No central logs yet. Hook dual-write not enabled.'}`);
+    console.log('');
+
+    return { workspaceId, stateDir, policySource, policyMode, hasProof, hasEvents };
+}

package/src/cli/commands/verify.js

@@ -0,0 +1,144 @@
+// src/cli/commands/verify.js
+// Validate a proposal without executing
+
+import fs from 'fs';
+import path from 'path';
+import { validateCommand } from '../../core/validator.js';
+import { NonceStore } from '../../core/nonceStore.js';
+import { loadKeysStore } from '../../core/trustedKeys.js';
+import { verifyPolicySignature } from '../../core/policySignature.js';
+import { validateAndUpdatePolicyVersionState } from '../../core/policyVersionGuard.js';
+
+export async function verifyCommand(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);
+    }
+
+    // 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);
+    }
+
+    // Validate command
+    const result = validateCommand({
+        commandObj: proposal,
+        pubKeyB64: pubKey,
+        keyStore,
+        nonceDb,
+        policy
+    });
+
+    // Output structured result
+    const output = {
+        status: result.valid ? 'valid' : 'invalid',
+        commandId: proposal.commandId || 'N/A',
+        checks: result.checks,
+        errors: result.errors || [],
+        risk: result.risk || 'UNKNOWN'
+    };
+
+    console.log(JSON.stringify(output, null, 2));
+
+    // Exit with appropriate code
+    if (!result.valid) {
+        // Determine which validation failed for exit code
+        if (result.checks.schema === false) process.exit(5);       // Schema error
+        if (result.checks.signature === false) process.exit(3);    // Signature error
+        if (result.checks.nonce === false) process.exit(4);        // Replay detected
+        if (result.checks.timestamp === false) process.exit(6);    // Clock skew
+        if (result.checks.rateLimit === false) process.exit(7);    // Rate limited
+        if (result.checks.policy === false) process.exit(2);       // Policy blocked
+        process.exit(9);                                            // Generic error
+    }
+
+    process.exit(0);
+}

package/src/cli/main.js

@@ -0,0 +1,181 @@
+// src/cli/main.js
+// LetterBlack Sentinel CLI entrypoint
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { parseArgs, printHelp } from './parseArgs.js';
+import { initCommand } from './commands/init.js';
+import { verifyCommand } from './commands/verify.js';
+import { dryrunCommand } from './commands/dryrun.js';
+import { runCommand } from './commands/run.js';
+import { auditVerifyCommand } from './commands/auditVerify.js';
+import { integrityCheckCommand, integrityGenerateCommand } from './commands/integrityCheck.js';
+import { performIntegrityCheck } from '../core/integrity.js';
+import { policySignCommand } from './commands/policySign.js';
+import { healthCommand } from './commands/health.js';
+import { policyAddCommand } from './commands/policyAdd.js';
+import { policyModeCommand } from './commands/policyMode.js';
+import { statusCommand } from './commands/status.js';
+import { logsCommand } from './commands/logs.js';
+import { openStateCommand } from './commands/openState.js';
+import { proofCommand } from './commands/proof.js';
+import { assertConsumerCommand } from './commands/assertConsumer.js';
+
+function toBoolean(value, defaultValue = false) {
+    if (value === undefined) return defaultValue;
+    if (value === true || value === false) return value;
+    const normalized = String(value).trim().toLowerCase();
+    if (normalized === 'true' || normalized === '1' || normalized === 'yes') return true;
+    if (normalized === 'false' || normalized === '0' || normalized === 'no') return false;
+    return defaultValue;
+}
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = path.join(__dirname, '../../package.json');
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+
+export async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.includes('--version')) {
+        console.log(`LetterBlack Sentinel v${packageJson.version}`);
+        process.exit(0);
+    }
+    if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+        printHelp(packageJson.version);
+        process.exit(0);
+    }
+
+    const { command, opts } = parseArgs(argv);
+
+    // Handle version flag
+    if (opts.version) {
+        console.log(`LetterBlack Sentinel v${packageJson.version}`);
+        process.exit(0);
+    }
+
+    // Handle help flag or no command
+    if (opts.help || !command || command === 'help') {
+        printHelp(packageJson.version);
+        process.exit(0);
+    }
+
+    try {
+        // Parse --pub-key-file if provided
+        if (opts['pub-key-file']) {
+            try {
+                opts['pub-key'] = fs.readFileSync(path.resolve(opts['pub-key-file']), 'utf-8').trim();
+            } catch (error) {
+                console.error(`Error reading public key file: ${error.message}`);
+                process.exit(1);
+            }
+        }
+
+        // Route to command handler
+        if (['verify', 'dryrun', 'run'].includes(command)) {
+            const integrityStrict = toBoolean(opts['integrity-strict'], false);
+            const integrityManifestPath = path.resolve(opts['integrity-manifest'] || '.lbe/config/integrity.manifest.json');
+            const integrityResult = await performIntegrityCheck({
+                strict: integrityStrict,
+                manifestPath: integrityManifestPath
+            });
+            if (!integrityResult.valid) {
+                console.error(JSON.stringify({
+                    status: 'error',
+                    error: integrityResult.reason || 'INTEGRITY_CHECK_FAILED',
+                    message: integrityResult.message
+                }, null, 2));
+                process.exit(8);
+            }
+        }
+
+        switch (command) {
+            case 'init':
+                await initCommand(opts);
+                break;
+
+            case 'verify':
+                await verifyCommand(opts);
+                break;
+
+            case 'dryrun':
+                await dryrunCommand(opts);
+                break;
+
+            case 'run':
+                await runCommand(opts);
+                break;
+
+            case 'audit-verify':
+                await auditVerifyCommand(opts);
+                break;
+
+            case 'integrity-check':
+                await integrityCheckCommand(opts);
+                break;
+
+            case 'integrity-generate':
+                await integrityGenerateCommand(opts);
+                break;
+
+            case 'policy-sign':
+                await policySignCommand(opts);
+                break;
+
+            case 'health':
+                await healthCommand(opts);
+                break;
+
+            case 'policy-add':
+                await policyAddCommand(opts);
+                break;
+
+            case 'observe':
+            case 'enforce':
+                await policyModeCommand(command, opts);
+                break;
+
+            case 'status':
+                await statusCommand(opts);
+                break;
+
+            case 'logs':
+                await logsCommand(opts);
+                break;
+
+            case 'open-state':
+                await openStateCommand(opts);
+                break;
+
+            case 'proof':
+                await proofCommand(opts);
+                break;
+
+            case 'assert-consumer':
+                await assertConsumerCommand(opts);
+                break;
+
+            default:
+                console.error(`Unknown command: ${command}`);
+                printHelp(packageJson.version);
+                process.exit(1);
+        }
+    } catch (error) {
+        console.error(JSON.stringify({
+            status: 'error',
+            error: 'INTERNAL_ERROR',
+            message: error.message,
+            stack: process.env.DEBUG ? error.stack : undefined
+        }));
+        process.exit(9);
+    }
+}
+
+main().catch((error) => {
+    console.error(JSON.stringify({
+        status: 'error',
+        error: 'FATAL_ERROR',
+        message: error.message
+    }));
+    process.exit(9);
+});

package/src/cli/parseArgs.js

@@ -0,0 +1,115 @@
+// src/cli/parseArgs.js
+// Command-line argument parser
+
+export function parseArgs(argv) {
+    // argv should already have node and script removed
+    if (argv.length === 0) {
+        return { command: 'help', opts: {} };
+    }
+
+    const command = argv[0];
+    const opts = {};
+
+    for (let i = 1; i < argv.length; i++) {
+        if (argv[i].startsWith('--')) {
+            const key = argv[i].substring(2);
+            // Handle --key=value format
+            if (key.includes('=')) {
+                const [k, v] = key.split('=');
+                opts[k] = v;
+            } else {
+                const nextArg = argv[i + 1];
+                if (!nextArg || nextArg.startsWith('-')) {
+                    opts[key] = true;
+                } else {
+                    opts[key] = nextArg;
+                    i++;
+                }
+            }
+        } else if (argv[i].startsWith('-')) {
+            const key = argv[i].substring(1);
+            const nextArg = argv[i + 1];
+            if (!nextArg || nextArg.startsWith('-')) {
+                opts[key] = true;
+            } else {
+                opts[key] = nextArg;
+                i++;
+            }
+        }
+    }
+
+    return { command, opts };
+}
+
+export function printHelp(version = 'unknown') {
+    console.log(`
+╔═══════════════════════════════════════════════════════════╗
+║          LetterBlack Sentinel — CLI Governance            ║
+║     Local-first execution governance SDK  v${version.padEnd(12)}║
+╚═══════════════════════════════════════════════════════════╝
+
+USAGE:
+  lbe [command] [options]
+
+COMMANDS:
+  init      Initialize LetterBlack Sentinel environment
+  verify    Verify a proposal (validate, don't execute)
+  dryrun    Validate and simulate execution (no changes)
+  run       Validate and execute a proposal
+  policy-sign  Sign policy and write policy signature envelope
+  policy-add   Controller-only: add a rule to lbe.policy.json
+  observe   Set project-local policy to advisory mode
+  enforce   Set project-local policy to blocking mode
+  health    Run deployment/runtime health checks
+  integrity-check  Verify controller integrity manifest
+  integrity-generate  Generate controller integrity manifest
+  audit-verify  Verify audit log hash-chain integrity
+  status    Show central state summary for this workspace
+  logs      Print recent entries from central event log
+  open-state  Open the central state directory in the file manager
+  proof     Show latest proof result (--json for raw JSON, --public for redacted)
+  assert-consumer  Verify this project consumes LBE as an installed registry dependency
+  help      Show this help message
+
+OPTIONS:
+  --in              Input file (JSON proposal)
+  --config          Policy config file (default: ./.lbe/config/policy.default.json)
+  --policy          Alias for --config
+  --policy-sig      Policy signature file (default: ./.lbe/config/policy.sig.json)
+  --policy-state    Policy monotonic state file (default: ./data/policy.state.json)
+  --policy-unsigned-ok  Allow unsigned policy (dev-only; default: false)
+  --policy-key-id   Signer keyId for policy-sign (default: policy-signer-v1-2026Q1)
+  --secret-key-file Secret key for policy-sign (default: ./keys/secret.key)
+  --data-dir        Data directory for health checks (default: ./data)
+  --nonce-db        Nonce DB path for health checks
+  --rate-db         Rate-limit DB path for health checks
+  --keys-store      Trusted keys store (default: ./.lbe/config/keys.json)
+  --pub-key         Public key for verification (Ed25519 base64)
+  --pub-key-file    Legacy single-key file path (fallback mode)
+  --integrity-strict  Fail verify/dryrun/run if integrity check fails
+  --integrity-manifest Integrity manifest path (default: ./.lbe/config/integrity.manifest.json)
+  --manifest        Manifest path override for integrity-check
+  --out             Output path for integrity-generate
+  --audit           Audit log file (default: ./data/audit.log.jsonl)
+  --root            Project root for local policy commands (default: cwd)
+  --effect          Local rule effect: allow or deny
+  --type            Local rule type: path or command
+  --pattern         Local rule glob/pattern
+  --from            Required human-readable rule provenance
+  --json            JSON output (default: true)
+  --fail-fast       Stop at first audit integrity error (default: true)
+  --max             Max audit entries to process (optional)
+  --version         Show version
+  --help            Show this help message
+
+EXAMPLES:
+  lbe execute --input proposal.json
+  cat proposal.json | lbe execute
+  lbe policy-sign --config ./.lbe/config/policy.default.json --policy-sig ./.lbe/config/policy.sig.json
+  lbe integrity-generate --out ./.lbe/config/integrity.manifest.json
+  lbe integrity-check --integrity-strict --manifest ./.lbe/config/integrity.manifest.json
+  lbe audit-verify --audit ./data/audit.log.jsonl
+
+For more info, visit: https://github.com/Letterblack0306/LetterBlack-LBE-Core
+`);
+}