@blamejs/core 0.6.13 → 0.6.21

package/lib/cli.js

@@ -1283,6 +1283,572 @@ async function _runVault(args, ctx) {
   return 2;
 }
 
+// ---- Subcommand: security ----------------------------------------
+//
+// Runs b.security.assertProduction against the live framework. Useful
+// out-of-band: ops can re-check posture without rebooting the app.
+// Boots the framework so resolvers see the actual vault / db / audit-
+// signing modes; reports pass / fail with the failure-code list.
+
+var SECURITY_USAGE = [
+  "Usage: blamejs security <subcommand> [flags]",
+  "",
+  "Subcommands:",
+  "  assert            Run b.security.assertProduction against the framework's",
+  "                    live posture (vault / dbAtRest / auditSigning / NTP / env",
+  "                    vars / dataDir POSIX-mode / NODE_ENV). Exit 0 = clean,",
+  "                    exit 1 = one or more assertions failed.",
+  "",
+  "Flags:",
+  "  --data-dir <path>            Required for `assert` (the boot dir)",
+  "  --vault-mode <mode>          plaintext | wrapped (default wrapped)",
+  "  --no-ntp-strict              Skip the BLAMEJS_NTP_STRICT check",
+  "  --require-env <KEY,KEY,...>  Comma-separated env vars that MUST be set",
+  "  --forbid-env  <KEY,KEY,...>  Comma-separated env vars that must NOT be set",
+  "  --no-vault                   Skip vault posture check",
+  "  --no-db-at-rest              Skip dbAtRest posture check",
+  "  --no-audit-signing           Skip auditSigning posture check",
+].join("\n");
+
+async function _runSecurity(args, ctx) {
+  if (args.pos.length === 0) {
+    return cliHelpers.makeReporter(ctx, "blamejs security").usage(SECURITY_USAGE);
+  }
+  var sub = args.pos[0];
+  var report = cliHelpers.makeReporter(ctx, "blamejs security " + sub);
+  if (sub === "help" || args.flags.help || args.flags.h) {
+    return report.helpStdout(SECURITY_USAGE);
+  }
+  if (sub !== "assert") {
+    cliHelpers.makeReporter(ctx, "blamejs security").error("unknown subcommand '" + sub + "'", 2);
+    return cliHelpers.makeReporter(ctx, "blamejs security").usage(SECURITY_USAGE);
+  }
+  var dataDirFlag = args.flags["data-dir"];
+  if (!dataDirFlag || dataDirFlag === true) {
+    return report.error("--data-dir <path> is required", 2);
+  }
+  var dataDir = _resolvePath(String(dataDirFlag), ctx.cwd);
+  var vaultMode = args.flags["vault-mode"] || "wrapped";
+  if (vaultMode !== "wrapped" && vaultMode !== "plaintext") {
+    return report.error("--vault-mode must be 'wrapped' or 'plaintext'", 2);
+  }
+  var booted;
+  try {
+    booted = await cliHelpers.bootApp({ dataDir: dataDir, vaultMode: vaultMode, env: ctx.env });
+  } catch (e) {
+    return report.error("boot failed: " + ((e && e.message) || String(e)));
+  }
+  try {
+    var assertOpts = {
+      audit:        booted.b.audit,
+      dataDir:      dataDir,
+      vault:        args.flags["no-vault"]         ? false : "wrapped",
+      dbAtRest:     args.flags["no-db-at-rest"]    ? false : "encrypted",
+      auditSigning: args.flags["no-audit-signing"] ? false : "wrapped",
+      ntpStrict:    !args.flags["no-ntp-strict"],
+    };
+    if (args.flags["require-env"] && args.flags["require-env"] !== true) {
+      assertOpts.requireEnv = requestHelpers.parseListHeader(args.flags["require-env"]);
+    }
+    if (args.flags["forbid-env"] && args.flags["forbid-env"] !== true) {
+      assertOpts.forbidEnv = requestHelpers.parseListHeader(args.flags["forbid-env"]);
+    }
+    try {
+      await booted.b.security.assertProduction(assertOpts);
+      return report.ok("production posture clean");
+    } catch (e) {
+      if (e && e.isSecurityAssertError && Array.isArray(e.failures)) {
+        report.write("FAIL: " + e.failures.length + " assertion(s):");
+        for (var fi = 0; fi < e.failures.length; fi++) {
+          report.write("  - " + e.failures[fi].code + ": " + e.failures[fi].message);
+        }
+        return 1;
+      }
+      return report.error((e && e.message) || String(e));
+    }
+  } finally {
+    try { await booted.app.shutdown(); } catch (_e) { /* best-effort */ }
+  }
+}
+
+// ---- Subcommand: config-drift -------------------------------------
+//
+// Inspect / verify the b.configDrift sidecar without rebooting. The
+// sidecar is signed with the audit-signing key, so we boot the
+// framework to access it. `inspect` prints the full snapshot;
+// `verify` only reports the verified flag (exit 0 = signed +
+// untampered, exit 1 = tampered or missing).
+
+var CONFIG_DRIFT_USAGE = [
+  "Usage: blamejs config-drift <subcommand> [flags]",
+  "",
+  "Subcommands:",
+  "  inspect           Print the sidecar's snapshot + capturedAt + verified flag",
+  "  verify            Verify the sidecar's signature (exit code reflects status)",
+  "",
+  "Flags:",
+  "  --data-dir <path>      Required (sidecar location)",
+  "  --baseline <name>      Multi-baseline name (default: \"default\")",
+  "  --vault-mode <mode>    plaintext | wrapped (default wrapped)",
+  "  --json                 inspect: print machine-readable JSON",
+].join("\n");
+
+async function _runConfigDrift(args, ctx) {
+  if (args.pos.length === 0) {
+    return cliHelpers.makeReporter(ctx, "blamejs config-drift").usage(CONFIG_DRIFT_USAGE);
+  }
+  var sub = args.pos[0];
+  var report = cliHelpers.makeReporter(ctx, "blamejs config-drift " + sub);
+  if (sub === "help" || args.flags.help || args.flags.h) {
+    return report.helpStdout(CONFIG_DRIFT_USAGE);
+  }
+  if (["inspect", "verify"].indexOf(sub) === -1) {
+    cliHelpers.makeReporter(ctx, "blamejs config-drift").error("unknown subcommand '" + sub + "'", 2);
+    return cliHelpers.makeReporter(ctx, "blamejs config-drift").usage(CONFIG_DRIFT_USAGE);
+  }
+  var dataDirFlag = args.flags["data-dir"];
+  if (!dataDirFlag || dataDirFlag === true) {
+    return report.error("--data-dir <path> is required", 2);
+  }
+  var dataDir = _resolvePath(String(dataDirFlag), ctx.cwd);
+  var vaultMode = args.flags["vault-mode"] || "wrapped";
+  var booted;
+  try {
+    booted = await cliHelpers.bootApp({ dataDir: dataDir, vaultMode: vaultMode, env: ctx.env });
+  } catch (e) {
+    return report.error("boot failed: " + ((e && e.message) || String(e)));
+  }
+  try {
+    var driftOpts = { dataDir: dataDir, audit: booted.b.audit };
+    if (args.flags.baseline && args.flags.baseline !== true) {
+      driftOpts.baseline = String(args.flags.baseline);
+    }
+    var drift = booted.b.configDrift.create(driftOpts);
+    var sidecar = drift.read();
+    if (!sidecar) {
+      report.write("no sidecar present at " + drift.sidecarPath);
+      return sub === "verify" ? 1 : 0;
+    }
+    if (sub === "verify") {
+      if (sidecar.verified) {
+        return report.ok("sidecar verified at " + new Date(sidecar.capturedAt).toISOString());
+      }
+      report.error("sidecar tamper detected: " + sidecar.tamperReason);
+      return 1;
+    }
+    if (args.flags.json) {
+      report.write(JSON.stringify({
+        capturedAt:    sidecar.capturedAt,
+        digestHex:     sidecar.digestHex,
+        verified:      sidecar.verified,
+        tamperReason:  sidecar.tamperReason,
+        snapshot:      sidecar.snapshot,
+      }, null, 2));
+    } else {
+      report.write("sidecar:    " + drift.sidecarPath);
+      report.write("capturedAt: " + new Date(sidecar.capturedAt).toISOString());
+      report.write("digestHex:  " + sidecar.digestHex);
+      report.write("verified:   " + (sidecar.verified ? "yes" : "no — " + sidecar.tamperReason));
+      report.write("snapshot:");
+      report.write(JSON.stringify(sidecar.snapshot, null, 2));
+    }
+    return sidecar.verified ? 0 : 1;
+  } finally {
+    try { await booted.app.shutdown(); } catch (_e) { /* best-effort */ }
+  }
+}
+
+// ---- Subcommand: file-type ---------------------------------------
+//
+// Pure utility — magic-byte content classification. No framework
+// boot. Useful for upload debugging ("the user said this was a PDF
+// but is it really?") and as a CI-side sanity check.
+
+var FILE_TYPE_USAGE = [
+  "Usage: blamejs file-type detect <file> [flags]",
+  "",
+  "Inspects the leading bytes of <file> against the b.fileType signature",
+  "registry. Prints the detected mime / extension / category; exit 1 when",
+  "no signature matches (the actual format is unknown to the registry).",
+  "",
+  "Flags:",
+  "  --json                 Print machine-readable JSON",
+  "  --allowlist <list>     Comma-separated mime / category list — exits 1",
+  "                         when the detected type is NOT in the allowlist",
+  "                         (mirrors b.fileType.assertOneOf).",
+].join("\n");
+
+function _runFileType(args, ctx) {
+  if (args.pos.length === 0) {
+    return cliHelpers.makeReporter(ctx, "blamejs file-type").usage(FILE_TYPE_USAGE);
+  }
+  var sub = args.pos[0];
+  var report = cliHelpers.makeReporter(ctx, "blamejs file-type " + sub);
+  if (sub === "help" || args.flags.help || args.flags.h) {
+    return report.helpStdout(FILE_TYPE_USAGE);
+  }
+  if (sub !== "detect") {
+    cliHelpers.makeReporter(ctx, "blamejs file-type").error("unknown subcommand '" + sub + "'", 2);
+    return cliHelpers.makeReporter(ctx, "blamejs file-type").usage(FILE_TYPE_USAGE);
+  }
+  var file = args.pos[1];
+  if (!file) return report.error("file path is required (positional arg after 'detect')", 2);
+  var resolved = _resolvePath(String(file), ctx.cwd);
+  var buf;
+  try { buf = fs.readFileSync(resolved); }
+  catch (e) {
+    return report.error("read failed: " + ((e && e.message) || String(e)));
+  }
+  var fileType = require("./file-type");
+  if (args.flags.allowlist && args.flags.allowlist !== true) {
+    var allowed = requestHelpers.parseListHeader(args.flags.allowlist);
+    try {
+      var det = fileType.assertOneOf(buf, allowed);
+      if (args.flags.json) report.write(JSON.stringify(det));
+      else {
+        report.write("mime:      " + det.mime);
+        report.write("extension: " + det.extension);
+        report.write("category:  " + det.category);
+        report.write("name:      " + det.name);
+      }
+      return report.ok("matched allowlist " + JSON.stringify(allowed));
+    } catch (e) {
+      return report.error(e.code + ": " + e.message);
+    }
+  }
+  var detected = fileType.detect(buf);
+  if (!detected) {
+    if (args.flags.json) report.write("null");
+    return report.error("unknown — no signature matched the leading bytes (" +
+      buf.length + " bytes read)");
+  }
+  if (args.flags.json) {
+    report.write(JSON.stringify(detected));
+  } else {
+    report.write("mime:      " + detected.mime);
+    report.write("extension: " + detected.extension);
+    report.write("category:  " + detected.category);
+    report.write("name:      " + detected.name);
+  }
+  return report.ok();
+}
+
+// ---- Subcommand: password ----------------------------------------
+//
+// Test b.auth.password.policy from the CLI without rebooting the app.
+// Useful for ops dashboards that want to surface "your policy
+// requires X" or for CI checks of operator-supplied passwords.
+
+var PASSWORD_USAGE = [
+  "Usage: blamejs password check [flags]",
+  "",
+  "Runs b.auth.password.policy({ profile, ... }).check(plaintext, context).",
+  "Exit 0 = ok, exit 1 = policy rejected, exit 2 = bad args.",
+  "",
+  "Flags:",
+  "  --plaintext <s>        REQUIRED — the plaintext to test (or use stdin)",
+  "  --stdin                Read the plaintext from stdin (newline-trimmed)",
+  "  --profile <name>       Named profile: nist-aal2 | pci-4.0 | hipaa-aal2",
+  "  --min-length <n>       Override the profile minLength",
+  "  --max-length <n>       Override the profile maxLength",
+  "  --breach-check         Enable HaveIBeenPwned k-anonymity check (NETWORK)",
+  "  --fail-closed          With --breach-check: HIBP outage → fail (default ok)",
+  "  --email <addr>         Context for the deny-context-substrings check",
+  "  --username <name>      Context for the deny-context-substrings check",
+  "  --json                 Print machine-readable JSON",
+].join("\n");
+
+async function _runPassword(args, ctx) {
+  if (args.pos.length === 0) {
+    return cliHelpers.makeReporter(ctx, "blamejs password").usage(PASSWORD_USAGE);
+  }
+  var sub = args.pos[0];
+  var report = cliHelpers.makeReporter(ctx, "blamejs password " + sub);
+  if (sub === "help" || args.flags.help || args.flags.h) {
+    return report.helpStdout(PASSWORD_USAGE);
+  }
+  if (sub !== "check") {
+    cliHelpers.makeReporter(ctx, "blamejs password").error("unknown subcommand '" + sub + "'", 2);
+    return cliHelpers.makeReporter(ctx, "blamejs password").usage(PASSWORD_USAGE);
+  }
+  var plaintext;
+  if (args.flags.stdin) {
+    try { plaintext = fs.readFileSync(0, "utf8").replace(/\r?\n$/, ""); }
+    catch (e) { return report.error("stdin read failed: " + ((e && e.message) || String(e))); }
+  } else if (args.flags.plaintext && args.flags.plaintext !== true) {
+    plaintext = String(args.flags.plaintext);
+  } else {
+    return report.error("--plaintext <s> or --stdin is required", 2);
+  }
+  var policyOpts = {};
+  if (args.flags.profile && args.flags.profile !== true) policyOpts.profile = String(args.flags.profile);
+  if (args.flags["min-length"] && args.flags["min-length"] !== true) {
+    policyOpts.minLength = Number(args.flags["min-length"]);
+  }
+  if (args.flags["max-length"] && args.flags["max-length"] !== true) {
+    policyOpts.maxLength = Number(args.flags["max-length"]);
+  }
+  if (args.flags["breach-check"]) {
+    policyOpts.breachCheck = "haveibeenpwned";
+    if (args.flags["fail-closed"]) policyOpts.failClosed = true;
+  }
+  var passwordModule = require("./auth/password");
+  var policy;
+  try { policy = passwordModule.policy(policyOpts); }
+  catch (e) { return report.error("bad policy: " + ((e && e.message) || String(e)), 2); }
+  var context = {};
+  if (args.flags.email && args.flags.email !== true)       context.email    = String(args.flags.email);
+  if (args.flags.username && args.flags.username !== true) context.username = String(args.flags.username);
+  var verdict;
+  try { verdict = await policy.check(plaintext, context); }
+  catch (e) { return report.error("check threw: " + ((e && e.message) || String(e))); }
+  if (args.flags.json) {
+    report.write(JSON.stringify(verdict));
+    return verdict.ok ? 0 : 1;
+  }
+  if (verdict.ok) {
+    report.write("ok");
+    if (verdict.breachCheckSkipped) {
+      report.write("  (HIBP skipped: " + verdict.breachCheckSkipReason + ")");
+    } else if (typeof verdict.breachCheckCount === "number") {
+      report.write("  (HIBP breach count: " + verdict.breachCheckCount + ")");
+    }
+    return 0;
+  }
+  report.write("REJECTED: " + verdict.code);
+  report.write("  " + verdict.message);
+  return 1;
+}
+
+// ---- Subcommand: erase -------------------------------------------
+//
+// Cryptographic-erasure of a single row. The right tool for one-off
+// GDPR Art. 17 / right-to-erasure flows that don't fit the periodic
+// retention sweep. Replaces every sealed column + derived hash with
+// NULL, sets __erasedAt, and writes the row back. Cleartext is
+// unrecoverable even with the vault key.
+
+var ERASE_USAGE = [
+  "Usage: blamejs erase --table <table> --row-id <id> [flags]",
+  "",
+  "Tombstones a single row's sealed columns + derived hashes. Used for",
+  "one-off compliance erasure (GDPR Art. 17). The row stays in the table",
+  "(referential integrity) but the cleartext is unrecoverable.",
+  "",
+  "Flags:",
+  "  --data-dir <path>      Required",
+  "  --table <name>         Required — the table containing the row",
+  "  --row-id <id>          Required — the _id of the row to erase",
+  "  --vault-mode <mode>    plaintext | wrapped (default wrapped)",
+  "  --reason <text>        Reason recorded on the audit row (recommended)",
+  "  --confirm              Required — confirms the erase is intentional",
+].join("\n");
+
+async function _runErase(args, ctx) {
+  var report = cliHelpers.makeReporter(ctx, "blamejs erase");
+  if (args.flags.help || args.flags.h) {
+    return report.helpStdout(ERASE_USAGE);
+  }
+  var table = args.flags.table;
+  var rowId = args.flags["row-id"];
+  if (!table || table === true)  return report.error("--table <name> is required", 2);
+  if (!rowId || rowId === true)  return report.error("--row-id <id> is required", 2);
+  if (!args.flags.confirm) {
+    return report.error("--confirm is required (this operation is irreversible)", 2);
+  }
+  var dataDirFlag = args.flags["data-dir"];
+  if (!dataDirFlag || dataDirFlag === true) {
+    return report.error("--data-dir <path> is required", 2);
+  }
+  var dataDir = _resolvePath(String(dataDirFlag), ctx.cwd);
+  var vaultMode = args.flags["vault-mode"] || "wrapped";
+  var reason = (args.flags.reason && args.flags.reason !== true) ? String(args.flags.reason) : null;
+  var booted;
+  try {
+    booted = await cliHelpers.bootApp({ dataDir: dataDir, vaultMode: vaultMode, env: ctx.env });
+  } catch (e) {
+    return report.error("boot failed: " + ((e && e.message) || String(e)));
+  }
+  try {
+    var b = booted.b;
+    var safeTable = String(table).replace(/[^A-Za-z0-9_]/g, "");
+    if (safeTable !== String(table) || safeTable.length === 0) {
+      return report.error("--table must be a valid identifier (got " + JSON.stringify(table) + ")", 2);
+    }
+    var row;
+    try {
+      row = b.db.prepare("SELECT * FROM \"" + safeTable + "\" WHERE _id = ?").get(String(rowId));
+    } catch (e) {
+      return report.error("row lookup failed: " + ((e && e.message) || String(e)));
+    }
+    if (!row) {
+      return report.error("no row with _id=" + JSON.stringify(rowId) + " in table " + safeTable);
+    }
+    var schema = b.cryptoField.getSchema(safeTable);
+    var sealedFields = schema && Array.isArray(schema.sealedFields) ? schema.sealedFields : [];
+    var derivedHashes = schema && schema.derivedHashes ? Object.keys(schema.derivedHashes) : [];
+    if (sealedFields.length === 0 && derivedHashes.length === 0) {
+      return report.error("table " + safeTable + " has no sealed columns or derived hashes; " +
+        "use a regular DELETE for non-sealed rows");
+    }
+    var setClauses = [];
+    var values = [];
+    for (var si = 0; si < sealedFields.length; si++) {
+      setClauses.push('"' + sealedFields[si] + '" = ?');
+      values.push(null);
+    }
+    for (var di = 0; di < derivedHashes.length; di++) {
+      setClauses.push('"' + derivedHashes[di] + '" = ?');
+      values.push(null);
+    }
+    values.push(String(rowId));
+    try {
+      var upd = b.db.prepare("UPDATE \"" + safeTable + "\" SET " + setClauses.join(", ") + " WHERE _id = ?");
+      upd.run.apply(upd, values);
+    } catch (e) {
+      return report.error("UPDATE failed: " + ((e && e.message) || String(e)));
+    }
+    try {
+      b.audit.safeEmit({
+        action:  "system.erase",
+        outcome: "success",
+        resource: { kind: "row.erase", id: safeTable + "/" + String(rowId) },
+        reason:  reason,
+        metadata: {
+          table: safeTable, rowId: String(rowId),
+          sealedFieldCount: sealedFields.length,
+          derivedHashCount: derivedHashes.length,
+        },
+      });
+    } catch (_e) { /* audit best-effort */ }
+    report.write("erased: " + safeTable + "/" + String(rowId));
+    report.write("  sealed columns nulled: " + sealedFields.join(", "));
+    if (derivedHashes.length > 0) {
+      report.write("  derived hashes nulled: " + derivedHashes.join(", "));
+    }
+    return report.ok();
+  } finally {
+    try { await booted.app.shutdown(); } catch (_e) { /* best-effort */ }
+  }
+}
+
+// ---- Subcommand: retention ---------------------------------------
+//
+// Run / preview an ad-hoc retention rule from the CLI. Operators
+// supply the rule shape on the command line — table + ageField +
+// ttlMs + action — for one-off cleanups outside the scheduler-
+// driven sweep wired in lib code.
+
+var RETENTION_USAGE = [
+  "Usage: blamejs retention <subcommand> [flags]",
+  "",
+  "Subcommands:",
+  "  preview           Dry-run: report what WOULD be processed without acting",
+  "  run               Run the rule once (acts on the rows it finds)",
+  "",
+  "Flags (all subcommands):",
+  "  --data-dir <path>      Required",
+  "  --vault-mode <mode>    plaintext | wrapped (default wrapped)",
+  "  --table <name>         Required — table to sweep",
+  "  --age-field <col>      Required — column holding the ms-epoch timestamp",
+  "  --ttl-ms <ms>          Required — rows older than (now - ttlMs) are matched",
+  "  --action <a>           erase (default) | delete | soft-delete",
+  "  --soft-delete-field <col>",
+  "                         For action=soft-delete — column to write the",
+  "                         deletion timestamp into (required when action=soft-delete)",
+  "  --legal-hold-field <col>",
+  "                         Per-row legal-hold exemption column; rows where this",
+  "                         is truthy are skipped",
+  "  --batch-size <n>       Rows per batch (default 500)",
+  "  --json                 Print machine-readable JSON summary",
+].join("\n");
+
+async function _runRetention(args, ctx) {
+  if (args.pos.length === 0) {
+    return cliHelpers.makeReporter(ctx, "blamejs retention").usage(RETENTION_USAGE);
+  }
+  var sub = args.pos[0];
+  var report = cliHelpers.makeReporter(ctx, "blamejs retention " + sub);
+  if (sub === "help" || args.flags.help || args.flags.h) {
+    return report.helpStdout(RETENTION_USAGE);
+  }
+  if (["preview", "run"].indexOf(sub) === -1) {
+    cliHelpers.makeReporter(ctx, "blamejs retention").error("unknown subcommand '" + sub + "'", 2);
+    return cliHelpers.makeReporter(ctx, "blamejs retention").usage(RETENTION_USAGE);
+  }
+  var dataDirFlag = args.flags["data-dir"];
+  if (!dataDirFlag || dataDirFlag === true) return report.error("--data-dir <path> is required", 2);
+  var table   = args.flags.table;
+  var ageField = args.flags["age-field"];
+  var ttlMs   = args.flags["ttl-ms"];
+  if (!table   || table === true)    return report.error("--table <name> is required", 2);
+  if (!ageField || ageField === true) return report.error("--age-field <col> is required", 2);
+  if (!ttlMs   || ttlMs === true)    return report.error("--ttl-ms <ms> is required", 2);
+  var ttlMsNum = Number(ttlMs);
+  if (!isFinite(ttlMsNum) || ttlMsNum <= 0) {
+    return report.error("--ttl-ms must be a positive finite number", 2);
+  }
+  var action = args.flags.action ? String(args.flags.action) : "erase";
+  if (["erase", "delete", "soft-delete"].indexOf(action) === -1) {
+    return report.error("--action must be erase / delete / soft-delete", 2);
+  }
+  if (action === "soft-delete" &&
+      (!args.flags["soft-delete-field"] || args.flags["soft-delete-field"] === true)) {
+    return report.error("--soft-delete-field <col> required when --action=soft-delete", 2);
+  }
+  var batchSize = args.flags["batch-size"] && args.flags["batch-size"] !== true
+    ? Number(args.flags["batch-size"]) : 500;
+  var dataDir = _resolvePath(String(dataDirFlag), ctx.cwd);
+  var vaultMode = args.flags["vault-mode"] || "wrapped";
+  var booted;
+  try {
+    booted = await cliHelpers.bootApp({ dataDir: dataDir, vaultMode: vaultMode, env: ctx.env });
+  } catch (e) {
+    return report.error("boot failed: " + ((e && e.message) || String(e)));
+  }
+  try {
+    var rules = booted.b.retention.create({ db: booted.b.db, audit: booted.b.audit });
+    var ruleSpec = {
+      name:      "cli-" + String(table) + "-" + Date.now(),
+      table:     String(table),
+      ageField:  String(ageField),
+      ttlMs:     ttlMsNum,
+      action:    action,
+      batchSize: batchSize,
+    };
+    if (args.flags["soft-delete-field"] && args.flags["soft-delete-field"] !== true) {
+      ruleSpec.softDeleteField = String(args.flags["soft-delete-field"]);
+    }
+    if (args.flags["legal-hold-field"] && args.flags["legal-hold-field"] !== true) {
+      ruleSpec.legalHoldField = String(args.flags["legal-hold-field"]);
+    }
+    rules.declare(ruleSpec);
+    var summary = await rules.run(ruleSpec.name, { dryRun: sub === "preview" });
+    if (args.flags.json) {
+      report.write(JSON.stringify(summary, null, 2));
+    } else {
+      report.write((sub === "preview" ? "DRY-RUN " : "") + "rule:    " + ruleSpec.name);
+      report.write("table:    " + ruleSpec.table);
+      report.write("scanned:  " + summary.scanned);
+      report.write("processed:" + summary.processed);
+      report.write("skipped:  " + summary.skipped);
+      report.write("legalHoldsHonored: " + summary.legalHoldsHonored);
+      if (summary.errors && summary.errors.length > 0) {
+        report.write("errors:   " + summary.errors.length);
+        for (var ei = 0; ei < Math.min(summary.errors.length, 5); ei++) {
+          report.write("  - " + (summary.errors[ei].rowId || "?") + ": " + summary.errors[ei].reason);
+        }
+      }
+      report.write("durationMs: " + summary.durationMs);
+    }
+    return summary.errors && summary.errors.length > 0 ? 1 : 0;
+  } catch (e) {
+    return report.error((e && e.message) || String(e));
+  } finally {
+    try { await booted.app.shutdown(); } catch (_e) { /* best-effort */ }
+  }
+}
+
 var TOP_USAGE = [
   "Usage: blamejs <command> [args]",
   "",
@@ -1296,6 +1862,12 @@ var TOP_USAGE = [
   "  backup            Inspect / verify / extract a backup bundle from disk",
   "  mtls              Inspect or generate the in-box mTLS CA + leaf certs (status / show-cert / init / issue / issue-p12)",
   "  vault             Seal / unseal / rotate the on-disk vault keypair (plaintext ↔ wrapped)",
+  "  security          Run b.security.assertProduction against the live framework",
+  "  config-drift      Inspect / verify the b.configDrift signed sidecar",
+  "  file-type         Magic-byte content classification (b.fileType.detect)",
+  "  password          Test b.auth.password.policy against a candidate plaintext",
+  "  erase             Cryptographically erase a single row's sealed columns (GDPR Art. 17)",
+  "  retention         Run / preview an ad-hoc b.retention rule",
   "  version           Print framework version",
   "  help [<command>]  Show this message or details for a command",
 ].join("\n");
@@ -1320,14 +1892,24 @@ async function main(argv, opts) {
     _writeLine(ctx.stdout, constants.version);
     return 0;
   }
-  if (args.flags.help || args.flags.h) {
-    _printTopHelp(ctx);
-    return 0;
-  }
 
   var cmd = args.pos[0];
 
+  // --help routing:
+  //   `blamejs --help`            → top-level help
+  //   `blamejs <cmd> --help`      → that command's USAGE (via the
+  //                                 existing `help <cmd>` dispatch
+  //                                 block below). Synthesizing the
+  //                                 positional form keeps every
+  //                                 subcommand's per-command usage
+  //                                 reachable via `--help` without
+  //                                 each handler having to special-case
+  //                                 the flag-only-no-subcommand path.
   if (cmd === undefined) { _printTopHelp(ctx); return 0; }
+  if (args.flags.help || args.flags.h) {
+    args = _parseArgs(["help", cmd]);
+    cmd  = "help";
+  }
   if (cmd === "help") {
     var subTopic = args.pos[1];
     if (subTopic === "migrate")      { _writeLine(ctx.stdout, MIGRATE_USAGE);      return 0; }
@@ -1339,6 +1921,12 @@ async function main(argv, opts) {
     if (subTopic === "backup")       { _writeLine(ctx.stdout, BACKUP_USAGE);       return 0; }
     if (subTopic === "mtls")         { _writeLine(ctx.stdout, MTLS_USAGE);         return 0; }
     if (subTopic === "vault")        { _writeLine(ctx.stdout, VAULT_USAGE);        return 0; }
+    if (subTopic === "security")     { _writeLine(ctx.stdout, SECURITY_USAGE);     return 0; }
+    if (subTopic === "config-drift") { _writeLine(ctx.stdout, CONFIG_DRIFT_USAGE); return 0; }
+    if (subTopic === "file-type")    { _writeLine(ctx.stdout, FILE_TYPE_USAGE);    return 0; }
+    if (subTopic === "password")     { _writeLine(ctx.stdout, PASSWORD_USAGE);     return 0; }
+    if (subTopic === "erase")        { _writeLine(ctx.stdout, ERASE_USAGE);        return 0; }
+    if (subTopic === "retention")    { _writeLine(ctx.stdout, RETENTION_USAGE);    return 0; }
     _printTopHelp(ctx);
     return 0;
   }
@@ -1354,6 +1942,12 @@ async function main(argv, opts) {
   if (cmd === "backup")       return await _runBackup(rest, ctx);
   if (cmd === "mtls")         return await _runMtls(rest, ctx);
   if (cmd === "vault")        return await _runVault(rest, ctx);
+  if (cmd === "security")     return await _runSecurity(rest, ctx);
+  if (cmd === "config-drift") return await _runConfigDrift(rest, ctx);
+  if (cmd === "file-type")    return _runFileType(rest, ctx);
+  if (cmd === "password")     return await _runPassword(rest, ctx);
+  if (cmd === "erase")        return await _runErase(rest, ctx);
+  if (cmd === "retention")    return await _runRetention(rest, ctx);
 
   _writeLine(ctx.stderr, "blamejs: unknown command '" + cmd + "'");
   _printTopHelp(ctx);