@blamejs/core 0.5.15 → 0.5.17

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.5.x
 
+- **0.5.16** (2026-04-30) — b.otelExport: OTLP/HTTP exporter for b.observability
+- **0.5.15** (2026-04-30) — b.archive: ZIP creation
 - **0.5.14** (2026-04-30) — b.time: timezone-aware datetime arithmetic + formatting
 - **0.5.13** (2026-04-30) — b.testing.request: supertest-style chainable HTTP test helper
 - **0.5.12** (2026-04-30) — b.middleware.requestLog: HTTP access-log middleware

package/index.js

@@ -145,6 +145,7 @@ var pagination = require("./lib/pagination");
 var metrics = require("./lib/metrics");
 var tracing = require("./lib/tracing");
 var observability = require("./lib/observability");
+var otelExport = require("./lib/otel-export");
 var protocolDispatcher = require("./lib/protocol-dispatcher");
 var requestHelpers = require("./lib/request-helpers");
 var appShutdown = require("./lib/app-shutdown");
@@ -251,6 +252,7 @@ module.exports = {
   metrics:          metrics,
   tracing:          tracing,
   observability:    observability,
+  otelExport:       otelExport,
   protocolDispatcher: protocolDispatcher,
   requestHelpers:   requestHelpers,
   appShutdown:      appShutdown,

package/lib/backup/index.js

@@ -60,9 +60,9 @@
  */
 
 var fs = require("fs");
-var nodeCrypto = require("node:crypto");
 var os = require("os");
 var path = require("path");
+var crypto = require("../crypto");
 var atomicFile = require("../atomic-file");
 var backupBundle = require("./bundle");
 var lazyRequire = require("../lazy-require");
@@ -80,7 +80,7 @@ function _isValidBundleId(s) {
 }
 
 function _generateBundleId() {
-  return atomicFile.pathTimestamp() + "-" + nodeCrypto.randomBytes(4).toString("hex");
+  return atomicFile.pathTimestamp() + "-" + crypto.generateToken(4);
 }
 
 function _dirSize(p) {

package/lib/cache.js

@@ -94,6 +94,7 @@ var clusterStorage = require("./cluster-storage");
 var C = require("./constants");
 var lazyRequire = require("./lazy-require");
 var requestHelpers = require("./request-helpers");
+var safeAsync = require("./safe-async");
 var validateOpts = require("./validate-opts");
 var { CacheError } = require("./framework-error");
 
@@ -434,12 +435,11 @@ function _memoryBackend(cfg) {
 
   function _startSweep(intervalMs) {
     if (sweepTimer) return;
-    sweepTimer = setInterval(_sweep, intervalMs);
-    if (typeof sweepTimer.unref === "function") sweepTimer.unref();
+    sweepTimer = safeAsync.repeating(_sweep, intervalMs, { name: "cache-sweep" });
   }
 
   async function close() {
-    if (sweepTimer) { clearInterval(sweepTimer); sweepTimer = null; }
+    if (sweepTimer) { sweepTimer.stop(); sweepTimer = null; }
     entries.clear();
     tagIndex.clear();
     totalBytes = 0;
@@ -579,15 +579,11 @@ function _clusterBackend(cfg) {
   }
 
   function _startSweep(intervalMs) {
-    var t = setInterval(function () {
-      _sweep().catch(function () { /* sweeper best-effort; next pass picks it up */ });
-    }, intervalMs);
-    if (typeof t.unref === "function") t.unref();
-    cfg._sweepTimer = t;
+    cfg._sweepTimer = safeAsync.repeating(_sweep, intervalMs, { name: "cache-sweep-cluster" });
   }
 
   async function close() {
-    if (cfg._sweepTimer) { clearInterval(cfg._sweepTimer); cfg._sweepTimer = null; }
+    if (cfg._sweepTimer) { cfg._sweepTimer.stop(); cfg._sweepTimer = null; }
   }
 
   return {

package/lib/cli.js

@@ -35,15 +35,16 @@
  */
 
 var fs = require("node:fs");
-var nodeCrypto = require("node:crypto");
 var os = require("node:os");
 var path = require("path");
 var apiSnapshot = require("./api-snapshot");
 var auditTools = require("./audit-tools");
 var cliHelpers = require("./cli-helpers");
 var constants = require("./constants");
+var crypto = require("./crypto");
 var dev = require("./dev");
 var migrations = require("./migrations");
+var requestHelpers = require("./request-helpers");
 var restoreBundle = require("./restore-bundle");
 var seeders = require("./seeders");
 var vaultPassphraseOps = require("./vault/passphrase-ops");
@@ -746,7 +747,7 @@ async function _runApiKey(args, ctx) {
       var scopes  = args.flags.scopes;
       if (!ownerId || ownerId === true) return report.error("--owner-id <id> is required", 2);
       if (!scopes  || scopes === true)  return report.error("--scopes <comma-separated> is required", 2);
-      var scopeList = String(scopes).split(",").map(function (s) { return s.trim(); }).filter(Boolean);
+      var scopeList = requestHelpers.parseListHeader(scopes);
       if (scopeList.length === 0) {
         return report.error("--scopes must contain at least one non-empty scope", 2);
       }
@@ -902,7 +903,7 @@ async function _runBackup(args, ctx) {
 
   if (sub === "verify") {
     var stagingDir = path.join(os.tmpdir(),
-      "blamejs-backup-verify-" + nodeCrypto.randomBytes(8).toString("hex"));
+      "blamejs-backup-verify-" + crypto.generateToken(8));
     try {
       var r = await restoreBundle.extract({
         bundleDir:  bundleDir,

package/lib/cluster.js

@@ -52,6 +52,7 @@
  */
 var C = require("./constants");
 var { boot } = require("./log");
+var safeAsync = require("./safe-async");
 var safeUrl = require("./safe-url");
 var { FrameworkError, ClusterError } = require("./framework-error");
 
@@ -227,8 +228,7 @@ async function init(opts) {
   }
 
   // Start heartbeat
-  heartbeatTimer = setInterval(_heartbeat, heartbeatMs);
-  heartbeatTimer.unref();
+  heartbeatTimer = safeAsync.repeating(_heartbeat, heartbeatMs, { name: "cluster-heartbeat" });
 }
 
 // Cluster-mode equivalent of db.js's single-node audit.tip-sidecar
@@ -619,7 +619,7 @@ function onTransition(handler) {
 async function shutdown() {
   if (!initialized) return;
   if (heartbeatTimer) {
-    clearInterval(heartbeatTimer);
+    heartbeatTimer.stop();
     heartbeatTimer = null;
   }
   if (lease) {
@@ -649,7 +649,7 @@ async function shutdown() {
 // ---- test helpers — not part of public contract ----
 
 function _resetForTest() {
-  if (heartbeatTimer) clearInterval(heartbeatTimer);
+  if (heartbeatTimer) heartbeatTimer.stop();
   heartbeatTimer = null;
   initialized = false;
   terminated = false;

package/lib/csv.js

@@ -1,229 +1,275 @@
 "use strict";
 /**
- * csv — RFC 4180 parser + serializer.
+ * csv — RFC 4180 parser + serializer with operator-friendly defaults.
  *
- * Public API:
+ *   var rows = b.csv.parse(text);
+ *     // header row by default — returns array of objects keyed by header
+ *     // [ { name: "alice", age: "30" }, ... ]
  *
- *   b.csv.parse(text, opts?)        → { headers, rows }  (or { rows } if no header)
- *   b.csv.stringify(rows, opts?)    → string
+ *   var arrays = b.csv.parse(text, { header: false });
+ *     // returns array of arrays
  *
- * Opts (parse):
- *   delimiter:    ","   default
- *   header:       true  default — first row becomes column names; rows
- *                       are objects keyed by header
- *   maxBytes:     8 MiB default — refuses parse-bombs the same way
- *                       safeJson does
- *   onBadRow:     "throw" default | "skip" — what to do when a row has
- *                       a different column count than the header
+ *   var out = b.csv.stringify(rows);
+ *     // RFC 4180 + Excel-formula-injection prevention by default
  *
- * Opts (stringify):
- *   delimiter:    ","   default
- *   header:       true  default — emit a header row from object keys
- *   columns:      array of explicit column order (default: first row's keys)
- *   eol:          "\r\n" default — RFC 4180 mandates CRLF; some parsers
- *                       want LF. Operators choose.
+ * Defaults:
+ *   parse:
+ *     header:        true              first row is column names
+ *     delimiter:     ","               single byte; "\t" / ";" supported
+ *     quote:         '"'
+ *     trim:          false             cell whitespace preserved
+ *     maxBytes:      16 MiB
+ *     maxRows:       1,000,000
+ *     maxFieldBytes: 1 MiB
+ *     onBadRow:      "throw"           "skip" tolerates short/long rows
  *
- * Format support:
- *   - Quoted fields with embedded commas, quotes ("" → "), newlines.
- *   - Optional BOM at file start (consumed silently if present).
- *   - Trailing newline tolerated (RFC 4180 says SHOULD; we tolerate).
+ *   stringify:
+ *     header:                  true (or array of explicit columns)
+ *     delimiter:               ","
+ *     quote:                   '"'
+ *     eol:                     "\r\n"  RFC 4180; "\n" via opt
+ *     alwaysQuote:             false   only quote when needed
+ *     preventFormulaInjection: true    prefix '=' / '+' / '-' / '@' / TAB / CR
+ *                                       cells with "'" so Excel doesn't
+ *                                       execute them when the CSV is opened
+ *     formulaPrefixChars:      ["=","+","-","@","\t","\r"]
  *
- * Throws CsvError (FrameworkError) on shape violations.
+ * SECURITY: stringify defends against CSV-injection (Excel/Sheets execute
+ * cells starting with "=" / "+" / "-" / "@" / TAB / CR as formulas).
+ * Operator-controlled cells stay safe; user-supplied cells get the leading
+ * single-quote so the formula engine sees a literal string.
+ *
+ * Throws CsvError (FrameworkError, permanent) on shape violations.
  */
 var C = require("./constants");
 var { defineClass } = require("./framework-error");
 
 var CsvError = defineClass("CsvError", { alwaysPermanent: true });
 
-var DEFAULT_MAX_BYTES = C.BYTES.mib(8);
-var DEFAULT_DELIMITER = ",";
-var DEFAULT_EOL       = "\r\n";
+var DEFAULTS_PARSE = {
+  header:        true,
+  delimiter:     ",",
+  quote:         "\"",
+  trim:          false,
+  maxBytes:      C.BYTES.mib(16),
+  maxRows:       1000000,
+  maxFieldBytes: C.BYTES.mib(1),
+  onBadRow:      "throw",
+};
+
+var DEFAULTS_STRINGIFY = {
+  header:                  true,
+  delimiter:               ",",
+  quote:                   "\"",
+  eol:                     "\r\n",
+  alwaysQuote:             false,
+  preventFormulaInjection: true,
+  formulaPrefixChars:      ["=", "+", "-", "@", "\t", "\r"],
+  columns:                 null,
+};
+
+function _validateDelim(name, value) {
+  if (typeof value !== "string" || value.length !== 1) {
+    throw new CsvError("csv/bad-delimiter",
+      name + " must be a single character, got " + JSON.stringify(value));
+  }
+  if (value === "\r" || value === "\n") {
+    throw new CsvError("csv/bad-delimiter",
+      name + " cannot be CR or LF");
+  }
+}
 
 // ---- parse ----
 
-function parse(text, opts) {
-  opts = opts || {};
-  if (typeof text !== "string" && !Buffer.isBuffer(text)) {
+function parse(input, opts) {
+  opts = Object.assign({}, DEFAULTS_PARSE, opts || {});
+
+  var s;
+  if (typeof input === "string") s = input;
+  else if (Buffer.isBuffer(input)) s = input.toString("utf8");
+  else if (input instanceof Uint8Array) s = Buffer.from(input).toString("utf8");
+  else {
     throw new CsvError("csv/bad-input",
-      "parse: input must be a string or Buffer, got " + typeof text);
+      "parse: input must be string, Buffer, or Uint8Array, got " + typeof input);
   }
-  var s = Buffer.isBuffer(text) ? text.toString("utf8") : text;
-  var maxBytes = opts.maxBytes != null ? opts.maxBytes : DEFAULT_MAX_BYTES;
-  if (Buffer.byteLength(s, "utf8") > maxBytes) {
+  if (s.charCodeAt(0) === 0xFEFF) s = s.slice(1);
+  if (Buffer.byteLength(s, "utf8") > opts.maxBytes) {
     throw new CsvError("csv/too-large",
-      "parse: input exceeds maxBytes (" + maxBytes + ")");
-  }
-  var delimiter = opts.delimiter || DEFAULT_DELIMITER;
-  if (typeof delimiter !== "string" || delimiter.length !== 1) {
-    throw new CsvError("csv/bad-delimiter",
-      "parse: delimiter must be a single character, got " + JSON.stringify(delimiter));
+      "parse: input exceeds maxBytes (" + opts.maxBytes + ")");
   }
-  if (delimiter === "\"" || delimiter === "\r" || delimiter === "\n") {
+
+  _validateDelim("delimiter", opts.delimiter);
+  _validateDelim("quote",     opts.quote);
+  if (opts.delimiter === opts.quote) {
     throw new CsvError("csv/bad-delimiter",
-      "parse: delimiter cannot be quote / CR / LF");
+      "delimiter and quote must differ");
   }
-  var hasHeader = opts.header !== false;
-  var onBadRow = opts.onBadRow || "throw";
-  if (onBadRow !== "throw" && onBadRow !== "skip") {
+  if (opts.onBadRow !== "throw" && opts.onBadRow !== "skip") {
     throw new CsvError("csv/bad-opt",
-      "parse: onBadRow must be 'throw' or 'skip'");
+      "onBadRow must be 'throw' or 'skip'");
   }
 
-  // Strip BOM if present.
-  if (s.charCodeAt(0) === 0xfeff) s = s.slice(1);
-
+  var len = s.length;
+  var pos = 0;
   var rows = [];
-  var field = "";
   var row = [];
-  var inQuotes = false;
-  var i = 0;
-  var len = s.length;
-  while (i < len) {
-    var c = s.charAt(i);
-    if (inQuotes) {
-      if (c === "\"") {
-        if (i + 1 < len && s.charAt(i + 1) === "\"") {
-          field += "\"";    // escaped quote
-          i += 2;
+  var field = "";
+  var inQuote = false;
+
+  function pushField() {
+    if (Buffer.byteLength(field, "utf8") > opts.maxFieldBytes) {
+      throw new CsvError("csv/field-too-large",
+        "field exceeds maxFieldBytes at row " + (rows.length + 1));
+    }
+    row.push(opts.trim ? field.trim() : field);
+    field = "";
+  }
+  function pushRow() {
+    pushField();
+    rows.push(row);
+    if (rows.length > opts.maxRows) {
+      throw new CsvError("csv/too-many-rows",
+        "row count exceeds maxRows (" + opts.maxRows + ")");
+    }
+    row = [];
+  }
+
+  while (pos < len) {
+    var ch = s.charAt(pos);
+    if (inQuote) {
+      if (ch === opts.quote) {
+        if (pos + 1 < len && s.charAt(pos + 1) === opts.quote) {
+          field += opts.quote;
+          pos += 2;
           continue;
         }
-        inQuotes = false;
-        i++;
+        inQuote = false;
+        pos += 1;
         continue;
       }
-      field += c;
-      i++;
-      continue;
-    }
-    if (c === "\"") {
-      // Quote at the start of a field (or anywhere — treat as start of
-      // quoted run). RFC 4180 says quoted fields begin with a quote;
-      // fields that contain a quote not at the start are technically
-      // malformed but we tolerate by appending literally.
-      if (field.length === 0) {
-        inQuotes = true;
-        i++;
-        continue;
+      field += ch;
+      pos += 1;
+    } else {
+      if (ch === opts.delimiter) {
+        pushField();
+        pos += 1;
+      } else if (ch === "\r") {
+        pushRow();
+        pos += 1;
+        if (pos < len && s.charAt(pos) === "\n") pos += 1;
+      } else if (ch === "\n") {
+        pushRow();
+        pos += 1;
+      } else if (ch === opts.quote && field === "") {
+        inQuote = true;
+        pos += 1;
+      } else {
+        field += ch;
+        pos += 1;
       }
-      field += "\"";
-      i++;
-      continue;
-    }
-    if (c === delimiter) {
-      row.push(field);
-      field = "";
-      i++;
-      continue;
-    }
-    if (c === "\r") {
-      // CRLF or bare CR — treat both as row terminator.
-      row.push(field);
-      rows.push(row);
-      field = "";
-      row = [];
-      if (i + 1 < len && s.charAt(i + 1) === "\n") i += 2;
-      else i++;
-      continue;
-    }
-    if (c === "\n") {
-      row.push(field);
-      rows.push(row);
-      field = "";
-      row = [];
-      i++;
-      continue;
     }
-    field += c;
-    i++;
   }
-  // Flush any trailing field/row (no trailing newline case)
-  if (field.length > 0 || row.length > 0) {
-    row.push(field);
-    rows.push(row);
+  if (inQuote) {
+    throw new CsvError("csv/unterminated-quote",
+      "unterminated quoted field");
   }
+  if (field.length > 0 || row.length > 0) pushRow();
 
-  if (!hasHeader) {
-    return { rows: rows };
-  }
-  if (rows.length === 0) {
-    return { headers: [], rows: [] };
-  }
-  var headers = rows[0];
+  if (!opts.header) return rows;
+  if (rows.length === 0) return [];
+
+  var header = rows[0];
   var out = [];
   for (var r = 1; r < rows.length; r++) {
-    var current = rows[r];
-    if (current.length === 1 && current[0] === "") continue;   // skip blank lines
-    if (current.length !== headers.length) {
-      if (onBadRow === "skip") continue;
+    var rec = rows[r];
+    if (rec.length !== header.length) {
+      if (opts.onBadRow === "skip") continue;
       throw new CsvError("csv/row-length-mismatch",
-        "parse: row " + r + " has " + current.length + " columns, expected " + headers.length);
+        "row " + r + " has " + rec.length + " fields, header has " + header.length);
     }
     var obj = {};
-    for (var k = 0; k < headers.length; k++) obj[headers[k]] = current[k];
+    for (var i = 0; i < header.length; i++) obj[header[i]] = rec[i];
     out.push(obj);
   }
-  return { headers: headers, rows: out };
+  return out;
 }
 
 // ---- stringify ----
 
 function stringify(rows, opts) {
-  opts = opts || {};
+  opts = Object.assign({}, DEFAULTS_STRINGIFY, opts || {});
   if (!Array.isArray(rows)) {
     throw new CsvError("csv/bad-input",
-      "stringify: rows must be an array");
+      "stringify: rows must be an array, got " + typeof rows);
+  }
+  _validateDelim("delimiter", opts.delimiter);
+  _validateDelim("quote",     opts.quote);
+  if (opts.delimiter === opts.quote) {
+    throw new CsvError("csv/bad-delimiter",
+      "delimiter and quote must differ");
+  }
+  if (opts.eol !== "\r\n" && opts.eol !== "\n") {
+    throw new CsvError("csv/bad-opt",
+      "eol must be '\\r\\n' or '\\n'");
   }
-  var delimiter = opts.delimiter || DEFAULT_DELIMITER;
-  var eol       = opts.eol || DEFAULT_EOL;
-  var hasHeader = opts.header !== false;
   if (rows.length === 0) return "";
 
-  var columns;
-  if (Array.isArray(opts.columns)) {
-    columns = opts.columns.slice();
-  } else if (Array.isArray(rows[0])) {
-    // Array-of-arrays input — no headers to derive; emit as-is.
-    columns = null;
-  } else if (rows[0] && typeof rows[0] === "object") {
-    columns = Object.keys(rows[0]);
+  var first = rows[0];
+  var asObjects;
+  var header;
+  if (Array.isArray(first)) {
+    asObjects = false;
+    header = Array.isArray(opts.columns) ? opts.columns : null;
+  } else if (first !== null && typeof first === "object") {
+    asObjects = true;
+    header = Array.isArray(opts.columns) ? opts.columns : Object.keys(first);
   } else {
     throw new CsvError("csv/bad-input",
-      "stringify: rows[0] must be an object or array");
+      "stringify: rows must be arrays or plain objects");
   }
 
-  var lines = [];
-  if (hasHeader && columns) lines.push(columns.map(_quoteCell).join(delimiter));
+  var prefixSet = Object.create(null);
+  for (var pi = 0; pi < opts.formulaPrefixChars.length; pi++) {
+    prefixSet[opts.formulaPrefixChars[pi]] = true;
+  }
 
-  for (var r = 0; r < rows.length; r++) {
-    var row = rows[r];
-    var cells;
-    if (Array.isArray(row)) {
-      cells = row.map(_quoteCell);
-    } else if (row && typeof row === "object") {
-      cells = (columns || Object.keys(row)).map(function (col) {
-        return _quoteCell(row[col]);
-      });
-    } else {
-      throw new CsvError("csv/bad-input",
-        "stringify: rows[" + r + "] must be an object or array");
+  function escapeCell(value) {
+    var str = value == null ? "" : String(value);
+    if (opts.preventFormulaInjection && str.length > 0 && prefixSet[str.charAt(0)]) {
+      str = "'" + str;
+    }
+    var needsQuote = opts.alwaysQuote ||
+      str.indexOf(opts.delimiter) !== -1 ||
+      str.indexOf(opts.quote) !== -1 ||
+      str.indexOf("\n") !== -1 ||
+      str.indexOf("\r") !== -1;
+    if (needsQuote) {
+      str = opts.quote + str.split(opts.quote).join(opts.quote + opts.quote) + opts.quote;
     }
-    lines.push(cells.join(delimiter));
+    return str;
   }
-  return lines.join(eol) + eol;
-}
 
-function _quoteCell(value) {
-  if (value === null || value === undefined) return "";
-  var s = typeof value === "string" ? value : String(value);
-  if (s.indexOf("\"") !== -1 || s.indexOf(",") !== -1 ||
-      s.indexOf("\r") !== -1 || s.indexOf("\n") !== -1) {
-    return "\"" + s.replace(/"/g, "\"\"") + "\"";
+  var out = [];
+  if (opts.header && header) {
+    out.push(header.map(escapeCell).join(opts.delimiter));
+  }
+  for (var i = 0; i < rows.length; i++) {
+    var rec = rows[i];
+    var cells;
+    if (asObjects) {
+      cells = header.map(function (k) { return escapeCell(rec[k]); });
+    } else {
+      cells = rec.map(escapeCell);
+    }
+    out.push(cells.join(opts.delimiter));
   }
-  return s;
+  return out.join(opts.eol);
 }
 
 module.exports = {
-  parse:     parse,
-  stringify: stringify,
-  CsvError:  CsvError,
+  parse:               parse,
+  stringify:           stringify,
+  CsvError:            CsvError,
+  DEFAULTS_PARSE:      DEFAULTS_PARSE,
+  DEFAULTS_STRINGIFY:  DEFAULTS_STRINGIFY,
 };

package/lib/db.js

@@ -55,6 +55,7 @@ var cryptoField = require("./crypto-field");
 var { Query } = require("./db-query");
 var dbSchema = require("./db-schema");
 var { boot } = require("./log");
+var safeAsync = require("./safe-async");
 var safeEnv = require("./parsers/safe-env");
 var safeJson = require("./safe-json");
 var vault = require("./vault");
@@ -797,12 +798,11 @@ async function init(opts) {
 
   // Start periodic encrypt timer (encrypted mode only)
   if (atRest === "encrypted") {
-    encTimer = setInterval(function () {
+    encTimer = safeAsync.repeating(function () {
       try { encryptToDisk(); } catch (e) {
         log.error("periodic encrypt failed: " + e.message);
       }
-    }, C.TIME.minutes(5));
-    encTimer.unref();
+    }, C.TIME.minutes(5), { name: "db-periodic-encrypt" });
 
     // Final encrypt on process exit. We don't try to unlink the plaintext
     // here — the SQLite handle may still be open, and the OS reclaims tmpfs
@@ -914,7 +914,7 @@ function hashFor(table, field, value) {
 function close() {
   if (!initialized) return;
   if (encTimer) {
-    clearInterval(encTimer);
+    encTimer.stop();
     encTimer = null;
   }
   // Best-effort final checkpoint before shutdown so the audit.tip sidecar
@@ -1070,7 +1070,7 @@ async function _runNtpBootCheck(opts) {
 
 // Test helpers — not part of public contract
 function _resetForTest() {
-  if (encTimer) { clearInterval(encTimer); encTimer = null; }
+  if (encTimer) { encTimer.stop(); encTimer = null; }
   try { if (database) database.close(); } catch (_e) {}
   database = null;
   dbPath = null;