@blamejs/core 0.6.13 → 0.6.21

package/lib/config-drift.js

@@ -0,0 +1,309 @@
+"use strict";
+/**
+ * config-drift — boot-time config-baseline capture + signed sidecar +
+ * next-boot drift detection.
+ *
+ * The framework's audit chain captures DATA writes (every row, every
+ * key change). It does NOT capture RUNTIME CONFIG (the operator
+ * silently changed `allowedOrigins` 3 weeks ago and we have no
+ * signal). config-drift fills that gap: at every boot, the operator
+ * passes the baseline config snapshot they want tracked. The
+ * primitive hashes it with SHA3-512, signs the digest with the audit-
+ * signing key, and writes the result to a sidecar at
+ * `<dataDir>/config-baseline.sig`. On the next boot, the sidecar is
+ * loaded + verified + diffed against the new snapshot. Drift surfaces
+ * as an audit event (`config.drift.detected`); no boot block — the
+ * operator may have a legitimate reason to change config and the
+ * framework's job is to make the change auditable, not to refuse to
+ * start.
+ *
+ *   var configDrift = b.configDrift.create({
+ *     dataDir: "/data",
+ *     audit:   b.audit,
+ *   });
+ *
+ *   await configDrift.checkpoint({
+ *     // operator decides what's tracked. JSON-stringifiable.
+ *     allowedOrigins: ["https://app.example.com"],
+ *     csp:            "default-src 'self'",
+ *     auditMode:      b.audit.getMode(),
+ *     vaultMode:      b.vault.getMode(),
+ *     dbAtRest:       b.db.getAtRestMode(),
+ *   });
+ *   // → { signed: true, drifted: false, previousAt: 1730000000000 }
+ *
+ * The signed sidecar uses b.auditSign — same SLH-DSA-SHAKE-256f keypair
+ * the audit chain anchors on. An attacker who flips a config value
+ * would also need to forge the signing key to update the sidecar
+ * cleanly; otherwise next-boot verify catches the tamper.
+ *
+ * Validation:
+ *   - create() opts: throw at boot on bad shape
+ *   - checkpoint() snapshot: must be a JSON-serialisable object
+ *   - sidecar verify failure (tampered, key rotated, missing pubkey)
+ *     surfaces as `config.baseline.tamper` audit event AND the call
+ *     returns { tamper: true } so the operator can decide whether
+ *     to refuse boot
+ */
+var fs = require("node:fs");
+var path = require("node:path");
+var auditSign = require("./audit-sign");
+var crypto = require("./crypto");
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+var ConfigDriftError = defineClass("ConfigDriftError", { alwaysPermanent: true });
+var _err = ConfigDriftError.factory;
+
+var SIDECAR_NAME = "config-baseline.sig";
+var SIDECAR_VERSION = 1;
+
+// Stable JSON serialization: deterministic key order so the same
+// snapshot always hashes to the same digest. Without this, an object
+// reordered between boots would falsely flag as drift.
+function _stableStringify(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return "[" + value.map(_stableStringify).join(",") + "]";
+  }
+  var keys = Object.keys(value).sort();
+  var pairs = [];
+  for (var i = 0; i < keys.length; i++) {
+    pairs.push(JSON.stringify(keys[i]) + ":" + _stableStringify(value[keys[i]]));
+  }
+  return "{" + pairs.join(",") + "}";
+}
+
+function _hashSnapshot(snapshot) {
+  return crypto.sha3Hash(_stableStringify(snapshot));
+}
+
+function _diffShallow(prev, next) {
+  // For drift reporting only — names the keys that changed without
+  // dumping the full snapshot (which may carry sensitive values like
+  // a CSP nonce-derivation key). Operators reading the drift event
+  // get "these keys changed" + a hash on each side.
+  var changed = [];
+  var added = [];
+  var removed = [];
+  var allKeys = {};
+  Object.keys(prev || {}).forEach(function (k) { allKeys[k] = true; });
+  Object.keys(next || {}).forEach(function (k) { allKeys[k] = true; });
+  Object.keys(allKeys).forEach(function (k) {
+    var inPrev = Object.prototype.hasOwnProperty.call(prev || {}, k);
+    var inNext = Object.prototype.hasOwnProperty.call(next || {}, k);
+    if (inPrev && !inNext) { removed.push(k); return; }
+    if (!inPrev && inNext) { added.push(k); return; }
+    if (_stableStringify(prev[k]) !== _stableStringify(next[k])) changed.push(k);
+  });
+  return { changed: changed, added: added, removed: removed };
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "dataDir", "audit", "baseline", "criticalKeys", "ignoreKeys",
+  ], "configDrift");
+  if (typeof opts.dataDir !== "string" || opts.dataDir.length === 0) {
+    throw _err("BAD_OPT", "create: opts.dataDir is required");
+  }
+  var dataDir = opts.dataDir;
+  var auditOn = opts.audit !== false;
+  var auditInstance = (opts.audit && opts.audit !== true) ? opts.audit : null;
+  // Multi-baseline support — each operator-named baseline lives in its
+  // own sidecar so production / staging / disaster-recovery deploys
+  // each track their own drift independently.
+  var baselineName = (typeof opts.baseline === "string" && opts.baseline.length > 0)
+    ? opts.baseline : "default";
+  // Critical-keys allowlist: drift in these keys raises severity to
+  // "high" in the audit emission so SIEM rules can page on them
+  // separately from cosmetic drift. null = every key is treated as
+  // high severity (the safer default).
+  var criticalKeys = Array.isArray(opts.criticalKeys) ? opts.criticalKeys.slice() : null;
+  // Ignore-keys: drift in these keys is excluded from drift detection
+  // (e.g. operator-tracked metadata that legitimately changes per
+  // boot). Captured in the snapshot but never flagged.
+  var ignoreKeys = Array.isArray(opts.ignoreKeys) ? opts.ignoreKeys.slice() : [];
+  var sidecarPath = path.join(dataDir,
+    baselineName === "default" ? SIDECAR_NAME : ("config-baseline-" + baselineName + ".sig"));
+
+  function _emit(action, info, outcome) {
+    if (!auditOn) return;
+    var sink = auditInstance || audit();
+    try {
+      sink.safeEmit({
+        action:   action,
+        outcome:  outcome,
+        metadata: info || {},
+        reason:   info && info.reason ? info.reason : null,
+      });
+    } catch (_e) { /* audit best-effort */ }
+  }
+
+  function _readSidecar() {
+    if (!fs.existsSync(sidecarPath)) return null;
+    var raw;
+    try { raw = fs.readFileSync(sidecarPath, "utf8"); }
+    catch (_e) { return null; }
+    var parsed;
+    try { parsed = JSON.parse(raw); }
+    catch (_e) { return { unreadable: true }; }
+    if (!parsed || parsed.version !== SIDECAR_VERSION) return { unreadable: true };
+    if (typeof parsed.digestHex !== "string" || typeof parsed.signatureBase64 !== "string" ||
+        typeof parsed.publicKeyPem !== "string" || typeof parsed.snapshot !== "object") {
+      return { unreadable: true };
+    }
+    return parsed;
+  }
+
+  function _writeSidecar(snapshot, digestHex) {
+    // Sign over the digest (not the snapshot bytes directly) so the
+    // sidecar stays small even when the snapshot is large.
+    var signature = auditSign.sign(digestHex);
+    var payload = {
+      version:          SIDECAR_VERSION,
+      capturedAt:       Date.now(),
+      digestHex:        digestHex,
+      signatureBase64:  Buffer.from(signature).toString("base64"),
+      publicKeyPem:     auditSign.getPublicKey(),
+      snapshot:         snapshot,
+    };
+    var tmp = sidecarPath + ".tmp";
+    fs.writeFileSync(tmp, JSON.stringify(payload, null, 2));
+    fs.renameSync(tmp, sidecarPath);
+  }
+
+  function _verifySidecar(parsed) {
+    // Verify the recorded signature against the recorded public key
+    // first — this catches tampering with the digest+sig pair on its
+    // own. Then verify the digest matches a re-hash of the recorded
+    // snapshot — catches tampering with the snapshot field.
+    var sigBuf = Buffer.from(parsed.signatureBase64, "base64");
+    if (!auditSign.verify(parsed.digestHex, sigBuf, parsed.publicKeyPem)) {
+      return { ok: false, reason: "signature-invalid" };
+    }
+    if (_hashSnapshot(parsed.snapshot) !== parsed.digestHex) {
+      return { ok: false, reason: "digest-mismatch" };
+    }
+    return { ok: true };
+  }
+
+  async function checkpoint(snapshot) {
+    if (!snapshot || typeof snapshot !== "object" || Array.isArray(snapshot)) {
+      throw _err("BAD_OPT", "checkpoint: snapshot must be a plain object");
+    }
+    var newDigest = _hashSnapshot(snapshot);
+
+    var existing = _readSidecar();
+    if (existing && existing.unreadable) {
+      _emit("config.baseline.unreadable",
+        { sidecar: sidecarPath, reason: "sidecar present but malformed or wrong version" },
+        "warning");
+      _writeSidecar(snapshot, newDigest);
+      return { signed: true, drifted: false, tamper: false, previousAt: null, reason: "sidecar-unreadable-rewritten" };
+    }
+    if (!existing) {
+      _writeSidecar(snapshot, newDigest);
+      _emit("config.baseline.captured",
+        { digestHex: newDigest, capturedAt: Date.now() }, "success");
+      return { signed: true, drifted: false, tamper: false, previousAt: null };
+    }
+
+    var verified = _verifySidecar(existing);
+    if (!verified.ok) {
+      _emit("config.baseline.tamper",
+        { sidecar: sidecarPath, reason: verified.reason, previousAt: existing.capturedAt },
+        "failure");
+      // DO NOT auto-rewrite on tamper — let the operator inspect first.
+      return { signed: false, drifted: false, tamper: true, reason: verified.reason, previousAt: existing.capturedAt };
+    }
+
+    if (existing.digestHex === newDigest) {
+      // No drift; refresh capturedAt so the sidecar timestamp moves
+      // forward each successful boot (operator can see "last verified
+      // clean at <T>" in the file).
+      _writeSidecar(snapshot, newDigest);
+      return { signed: true, drifted: false, tamper: false, previousAt: existing.capturedAt };
+    }
+
+    var diff = _diffShallow(existing.snapshot, snapshot);
+    // Filter ignore-keys out of the drift report.
+    function _stripIgnored(arr) {
+      return arr.filter(function (k) { return ignoreKeys.indexOf(k) === -1; });
+    }
+    diff.changed = _stripIgnored(diff.changed);
+    diff.added   = _stripIgnored(diff.added);
+    diff.removed = _stripIgnored(diff.removed);
+    if (diff.changed.length === 0 && diff.added.length === 0 && diff.removed.length === 0) {
+      // All drift was in ignore-keys — refresh sidecar without
+      // emitting a drift event.
+      _writeSidecar(snapshot, newDigest);
+      return { signed: true, drifted: false, tamper: false,
+        previousAt: existing.capturedAt, ignoredOnly: true };
+    }
+    // Severity classification: HIGH when any drifted key is in
+    // criticalKeys (or no allowlist is configured — every key is
+    // critical by default). LOW when criticalKeys is set and none
+    // of the drifted keys are in it.
+    var severity = "high";
+    if (criticalKeys !== null) {
+      var anyCritical = false;
+      var allDrifted = diff.changed.concat(diff.added, diff.removed);
+      for (var di = 0; di < allDrifted.length; di++) {
+        if (criticalKeys.indexOf(allDrifted[di]) !== -1) { anyCritical = true; break; }
+      }
+      severity = anyCritical ? "high" : "low";
+    }
+    _emit("config.drift.detected",
+      {
+        baseline:          baselineName,
+        previousDigestHex: existing.digestHex,
+        currentDigestHex:  newDigest,
+        previousAt:        existing.capturedAt,
+        keysChanged:       diff.changed,
+        keysAdded:         diff.added,
+        keysRemoved:       diff.removed,
+        severity:          severity,
+      },
+      severity === "high" ? "failure" : "warning");
+    _writeSidecar(snapshot, newDigest);
+    return {
+      signed:      true,
+      drifted:     true,
+      tamper:      false,
+      severity:    severity,
+      previousAt:  existing.capturedAt,
+      diff:        diff,
+    };
+  }
+
+  function read() {
+    var existing = _readSidecar();
+    if (!existing || existing.unreadable) return null;
+    var verified = _verifySidecar(existing);
+    return {
+      capturedAt:    existing.capturedAt,
+      digestHex:     existing.digestHex,
+      snapshot:      existing.snapshot,
+      verified:      verified.ok,
+      tamperReason:  verified.ok ? null : verified.reason,
+    };
+  }
+
+  return {
+    checkpoint:        checkpoint,
+    read:              read,
+    sidecarPath:       sidecarPath,
+  };
+}
+
+module.exports = {
+  create:            create,
+  ConfigDriftError:  ConfigDriftError,
+  // Test-only export for hashing — operators don't need this directly.
+  _hashSnapshot:     _hashSnapshot,
+  _stableStringify:  _stableStringify,
+};

package/lib/crypto-field.js

@@ -126,6 +126,42 @@ function unsealRow(table, row) {
   return out;
 }
 
+// ---- Erasure (GDPR Art. 17 / "right to be forgotten") ----
+//
+// eraseRow(table, row) returns a tombstoned copy of the row: every
+// sealed column is replaced with NULL, every derived hash column
+// (computed from a sealed source) is replaced with NULL, and a
+// `__erasedAt` field is added carrying the erasure timestamp. The
+// row itself stays in the table (referential integrity), but the
+// sealed cleartext is unrecoverable — even with the vault key, NULL
+// decrypts to NULL.
+//
+// Callers that need the row removed entirely should DELETE; eraseRow
+// is for the case where downstream FKs / audit references make
+// outright deletion infeasible.
+function eraseRow(table, row) {
+  if (!row) return row;
+  var s = schemas[table];
+  if (!s) return row;
+  var out = Object.assign({}, row);
+  // Erase sealed columns — set to null. After this, unsealRow on the
+  // erased row returns null for these columns; no key recovers them
+  // because there's no ciphertext to decrypt.
+  for (var i = 0; i < s.sealedFields.length; i++) {
+    out[s.sealedFields[i]] = null;
+  }
+  // Erase derived hashes — they're indexed lookup mirrors of sealed
+  // sources and would otherwise let an attacker reverse the cleartext
+  // via dictionary enumeration of the hash.
+  if (s.derivedHashes) {
+    for (var derivedField in s.derivedHashes) {
+      out[derivedField] = null;
+    }
+  }
+  out.__erasedAt = Date.now();
+  return out;
+}
+
 // ---- Lookup translation ----
 
 // where({ email: 'x' }) → where({ emailHash: hash(...) }).
@@ -153,6 +189,7 @@ module.exports = {
   getSealedFields:  getSealedFields,
   sealRow:          sealRow,
   unsealRow:        unsealRow,
+  eraseRow:         eraseRow,
   computeDerived:   computeDerived,
   lookupHash:       lookupHash,
   clearForTest:     clearForTest,

package/lib/crypto.js

@@ -80,6 +80,14 @@ function timingSafeEqual(a, b) {
 function sha3Hash(data) { return hash(data, "sha3-512").toString("hex"); }
 function hmacSha3(key, data) { return hmac(key, data, "sha3-512"); }
 
+// (SHA-1 is intentionally NOT exported from b.crypto. The framework's
+//  only legitimate SHA-1 use is the HaveIBeenPwned k-anonymity API in
+//  lib/auth/password.js, which imports lib/internal-sha1-hibp.js
+//  directly. Public b.crypto.sha1* is permanently off the table — a
+//  future caller wanting SHA-1 for storage / signing / fingerprinting
+//  would re-introduce a broken primitive into the crypto surface this
+//  framework spent every other line keeping out.)
+
 // ---- KDF ----
 function kdf(input, outputLength) { return hash(input, "shake256", outputLength); }
 

package/lib/db-query.js

@@ -148,7 +148,21 @@ class Query {
     if (direction !== "asc" && direction !== "desc") {
       throw new Error("orderBy direction must be 'asc' or 'desc'");
     }
-    this._orderBy = { field: field, direction: direction.toUpperCase() };
+    var entry = { field: field, direction: direction.toUpperCase() };
+    if (this._orderBy === null) {
+      // First call — keep the back-compat single-object shape so any
+      // legacy reader that does `query._orderBy.field` keeps working.
+      this._orderBy = entry;
+      return this;
+    }
+    // Second-or-later call — promote to an array. Multi-column ORDER BY
+    // is the keyset-pagination tiebreaker pattern: ORDER BY createdAt
+    // DESC, _id DESC means same-second rows still have a total order.
+    if (Array.isArray(this._orderBy)) {
+      this._orderBy.push(entry);
+    } else {
+      this._orderBy = [this._orderBy, entry];
+    }
     return this;
   }
 
@@ -173,7 +187,12 @@ class Query {
   _orderLimitOffset() {
     var s = "";
     if (this._orderBy) {
-      s += ' ORDER BY "' + this._orderBy.field + '" ' + this._orderBy.direction;
+      var entries = Array.isArray(this._orderBy) ? this._orderBy : [this._orderBy];
+      var fragments = [];
+      for (var i = 0; i < entries.length; i++) {
+        fragments.push('"' + entries[i].field + '" ' + entries[i].direction);
+      }
+      s += " ORDER BY " + fragments.join(", ");
     }
     if (this._limit !== null)  s += " LIMIT "  + this._limit;
     if (this._offset !== null) s += " OFFSET " + this._offset;

package/lib/db.js

@@ -399,6 +399,21 @@ var FRAMEWORK_SCHEMA = [
     indexes: ["expiresAt"],
     sealedFields: [],
   },
+  {
+    // _blamejs_cache_tags — junction table for tag→cacheKey lookup
+    // backing b.cache.invalidateTag(t) on the cluster backend. Composite
+    // PK (cacheKey, tag) lets one cacheKey carry many tags; index on
+    // tag makes invalidation a single indexed scan. Cleared together
+    // with the matching _blamejs_cache rows on del / clear / sweep.
+    name: "_blamejs_cache_tags",
+    columns: {
+      cacheKey:   "TEXT NOT NULL",
+      tag:        "TEXT NOT NULL",
+    },
+    primaryKey: ["cacheKey", "tag"],
+    indexes:    ["tag"],
+    sealedFields: [],
+  },
   {
     // _blamejs_seeders — registry of applied seed files for the
     // b.seeders primitive (lib/seeders.js). Composite PK (env, name)
@@ -1037,11 +1052,26 @@ async function _runNtpBootCheck(opts) {
   try { ntpCheck = require("./ntp-check"); }
   catch (_e) { return; /* module not present — skip silently */ }
 
+  var envServersRaw = safeEnv.readVar("BLAMEJS_NTP_SERVERS",         { default: "" });
+  var envTimeout    = safeEnv.readVar("BLAMEJS_NTP_TIMEOUT_MS",      { default: "" });
+  var envWarn       = safeEnv.readVar("BLAMEJS_NTP_DRIFT_WARN_MS",   { default: "" });
+  var envFatal      = safeEnv.readVar("BLAMEJS_NTP_DRIFT_FATAL_MS",  { default: "" });
+  var resolvedServers = (opts && opts.ntpServers) ||
+    (envServersRaw ? envServersRaw.split(",").map(function (s) { return s.trim(); }).filter(Boolean) : undefined);
+  var resolvedTimeout = (opts && opts.ntpTimeoutMs) ||
+    (envTimeout ? parseInt(envTimeout, 10) : undefined);
+  if (envWarn || envFatal) {
+    var thr = {};
+    if (envWarn)  thr.warnMs  = parseInt(envWarn, 10);
+    if (envFatal) thr.fatalMs = parseInt(envFatal, 10);
+    try { ntpCheck.setThresholds(thr); } catch (_e) {}
+  }
+
   var result;
   try {
     result = await ntpCheck.bootCheck({
-      servers:   opts && opts.ntpServers,
-      timeoutMs: opts && opts.ntpTimeoutMs,
+      servers:   resolvedServers,
+      timeoutMs: resolvedTimeout,
     });
   } catch (e) {
     log.error("ntp boot check threw unexpectedly: " + e.message + " (continuing)");