@blamejs/core 0.5.17 → 0.5.18

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.5.x
 
+- **0.5.17** (2026-05-01) — primitive-drift sweep: csv unify + 3 new shared primitives
 - **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

package/lib/backup/index.js

@@ -243,6 +243,11 @@ function create(opts) {
   // running backup against an external db handle still work).
   if (flushBeforeBackup === null && opts.flushBeforeBackup !== false) {
     try {
+      // Inline require: backup is a leaf module the framework re-exports
+      // without forcing operators to also bring in lib/db. Hoisting to
+      // top-of-file would require everyone using `b.backup` from
+      // outside the framework to have ./db loadable in the same module
+      // graph, which CLI tools and stand-alone backup runners don't.
       var dbModule = require("../db");
       if (typeof dbModule.flushToDisk === "function") {
         flushBeforeBackup = function () { dbModule.flushToDisk(); };

package/lib/cluster.js

@@ -51,11 +51,21 @@
  *   await cluster.shutdown()             releases lease, stops heartbeat
  */
 var C = require("./constants");
+var clusterProviderDb = require("./cluster-provider-db");
+var crypto = require("./crypto");
+var lazyRequire = require("./lazy-require");
 var { boot } = require("./log");
 var safeAsync = require("./safe-async");
+var safeJson = require("./safe-json");
 var safeUrl = require("./safe-url");
 var { FrameworkError, ClusterError } = require("./framework-error");
 
+// Lazy: vault → db → cluster forms a load-time chain, and external-db is
+// loaded before its init has run; both are safe to call once cluster
+// reaches runtime, but eager require here would deadlock the load order.
+var externalDb = lazyRequire(function () { return require("./external-db"); });
+var vault = lazyRequire(function () { return require("./vault"); });
+
 var DEFAULT_LEASE_TTL    = C.TIME.seconds(30);
 var DEFAULT_HEARTBEAT    = C.TIME.seconds(10);
 var MIN_LEASE_TTL        = C.TIME.seconds(5);
@@ -185,8 +195,7 @@ async function init(opts) {
       throw _err("INVALID_CONFIG",
         "cluster.init requires either { provider } or { externalDbBackend }", true);
     }
-    var dbProvider = require("./cluster-provider-db");
-    provider = dbProvider.create({
+    provider = clusterProviderDb.create({
       externalDbBackend: opts.externalDbBackend,
       dialect:           opts.dialect,
     });
@@ -264,15 +273,9 @@ async function init(opts) {
 //     hash → FATAL via process.exit(1). Same posture as the
 //     single-node audit.tip sidecar rollback check.
 async function _checkChainTipRollback(chainName, logTable, tipTable) {
-  // Lazy require because external-db isn't available before
-  // cluster.init (and cluster is required from many subsystems —
-  // a top-of-file require would form a circular load with
-  // external-db's audit emit path).
-  var externalDb = require("./external-db");
-
   var tipRows;
   try {
-    tipRows = await externalDb.query(
+    tipRows = await externalDb().query(
       "SELECT atMonotonicCounter, rowHash FROM " + tipTable +
       " WHERE scope = '" + chainName + "'",
       [],
@@ -294,7 +297,7 @@ async function _checkChainTipRollback(chainName, logTable, tipTable) {
   var tipCounter = Number(tip.atMonotonicCounter);
   var tipHash = tip.rowHash;
 
-  var currentRows = await externalDb.query(
+  var currentRows = await externalDb().query(
     "SELECT MAX(monotonicCounter) AS m FROM " + logTable,
     [],
     { backend: configuredExternalDbBackend }
@@ -313,7 +316,7 @@ async function _checkChainTipRollback(chainName, logTable, tipTable) {
   }
 
   if (tipHash) {
-    var hashRows = await externalDb.query(
+    var hashRows = await externalDb().query(
       "SELECT rowHash FROM " + logTable + " WHERE monotonicCounter = " +
       (configuredDialect === "postgres" ? "$1" : "?"),
       [tipCounter],
@@ -347,14 +350,9 @@ async function _checkChainTipRollback(chainName, logTable, tipTable) {
 // posture as the audit-tip rollback check skipping when there's no
 // audit-tip table.
 function _vaultKeyFingerprint() {
-  // Lazy require to avoid the circular load risk: vault → db → cluster
-  // (the audit module pulls cluster in, db loads audit at init).
-  var vault = require("./vault");
-  var crypto = require("./crypto");
-  var safeJson = require("./safe-json");
   var keysJson;
   try {
-    keysJson = vault.getKeysJson();
+    keysJson = vault().getKeysJson();
   } catch (e) {
     // vault.init() not called — gates-only mode. Skip silently.
     if (/vault.init\(\) must be awaited/.test((e && e.message) || "")) {
@@ -380,7 +378,6 @@ async function _checkVaultKeyConsistency() {
     log("vault not initialized — skipping vault-key consistency check (cluster gates-only mode)");
     return;
   }
-  var externalDb = require("./external-db");
   var nowMs = Date.now();
   var ph = configuredDialect === "postgres";
 
@@ -390,7 +387,7 @@ async function _checkVaultKeyConsistency() {
   // compares — any mismatch (including ours after a losing race)
   // surfaces the drift.
   try {
-    await externalDb.query(
+    await externalDb().query(
       "INSERT INTO _blamejs_cluster_state " +
       "  (scope, vaultKeyFp, recordedAt, recordedByNode) " +
       "VALUES ('state', " +
@@ -413,7 +410,7 @@ async function _checkVaultKeyConsistency() {
 
   // Read whatever fingerprint is canonical (ours if first boot,
   // someone else's if we lost the race or are joining an existing cluster).
-  var rows = await externalDb.query(
+  var rows = await externalDb().query(
     "SELECT vaultKeyFp, recordedByNode, recordedAt FROM _blamejs_cluster_state " +
     "WHERE scope = 'state'",
     [],

package/lib/db.js

@@ -55,11 +55,17 @@ var cryptoField = require("./crypto-field");
 var { Query } = require("./db-query");
 var dbSchema = require("./db-schema");
 var { boot } = require("./log");
+var lazyRequire = require("./lazy-require");
 var safeAsync = require("./safe-async");
 var safeEnv = require("./parsers/safe-env");
 var safeJson = require("./safe-json");
 var vault = require("./vault");
 
+// Lazy: cluster-storage's _localDb pulls db back in, so eager require
+// would deadlock the load order. cluster-storage is only used on the
+// purge-audit-chain external-db path, which always runs after init.
+var clusterStorage = lazyRequire(function () { return require("./cluster-storage"); });
+
 var AUDIT_TIP_SCHEMA = {
   type: "object",
   required: ["atMonotonicCounter"],
@@ -1119,10 +1125,9 @@ module.exports = {
     if (!Number.isFinite(lastPurgedCounter) || lastPurgedCounter < 0) {
       throw new Error("purgeAuditChain: lastPurgedCounter must be a non-negative number");
     }
-    var c = require("./cluster");
-    if (c.isClusterMode()) {
+    if (cluster.isClusterMode()) {
       // External-db has no append-only triggers; ordinary DELETE works.
-      var cs = require("./cluster-storage");
+      var cs = clusterStorage();
       var d = await cs.execute(
         "DELETE FROM audit_log WHERE monotonicCounter <= ?", [lastPurgedCounter]
       );

package/lib/deprecate.js

@@ -50,6 +50,7 @@
  * call counter is still incremented so dep.list() shows usage volume.
  */
 
+var safeEnv = require("./parsers/safe-env");
 var { FrameworkError } = require("./framework-error");
 
 class DeprecateError extends FrameworkError {
@@ -65,12 +66,12 @@ class DeprecateError extends FrameworkError {
 var _seen = new Map();
 
 function _modeFromEnv() {
-  var env = process.env.BLAMEJS_DEPRECATIONS;
+  var env = safeEnv.readVar("BLAMEJS_DEPRECATIONS");
   if (typeof env === "string" && env.length > 0) {
     var v = env.toLowerCase();
     if (v === "warn" || v === "silent" || v === "error") return v;
   }
-  if (process.env.NODE_ENV === "production") return "silent";
+  if (safeEnv.readVar("NODE_ENV") === "production") return "silent";
   return "warn";
 }
 

package/lib/error-page.js

@@ -40,6 +40,7 @@
 
 var lazyRequire = require("./lazy-require");
 var requestHelpers = require("./request-helpers");
+var safeEnv = require("./parsers/safe-env");
 var template = require("./template");
 var audit = lazyRequire(function () { return require("./audit"); });
 
@@ -273,7 +274,7 @@ function create(opts) {
   if (modeOpt === "dev" || modeOpt === "prod") {
     mode = modeOpt;
   } else {
-    var nodeEnv = process.env.NODE_ENV;
+    var nodeEnv = safeEnv.readVar("NODE_ENV");
     mode = (nodeEnv === "production") ? "prod" : "dev";
   }
 

package/lib/http-client-cookie-jar.js

@@ -43,6 +43,7 @@
  *   }
  */
 
+var C = require("./constants");
 var safeUrl = require("./safe-url");
 var { defineClass } = require("./framework-error");
 
@@ -186,7 +187,7 @@ function create(opts) {
     if (attrs["max-age"] !== undefined) {
       var maxAge = parseInt(attrs["max-age"], 10);
       if (!isNaN(maxAge)) {
-        expiresAt = maxAge <= 0 ? 0 : (now + maxAge * 1000);
+        expiresAt = maxAge <= 0 ? 0 : (now + C.TIME.seconds(maxAge));
       }
     } else if (attrs.expires) {
       expiresAt = _parseHttpDate(attrs.expires);

package/lib/log.js

@@ -60,6 +60,7 @@
  */
 
 var { AsyncLocalStorage } = require("node:async_hooks");
+var nodeCrypto = require("node:crypto");
 var redact = require("./redact");
 var validateOpts = require("./validate-opts");
 var { FrameworkError } = require("./framework-error");
@@ -315,7 +316,7 @@ function create(opts) {
         ? mwOpts.generate
         : function () {
           // 16 random hex chars — short, sufficient correlation entropy
-          return require("crypto").randomBytes(8).toString("hex");
+          return nodeCrypto.randomBytes(8).toString("hex");
         };
       return function logRequestIdMiddleware(req, res, next) {
         var inbound = req.headers && req.headers[headerName];

package/lib/middleware/api-encrypt.js

@@ -174,7 +174,7 @@ function create(opts) {
   validateOpts(opts, [
     "keypair", "keypairs", "replayWindowMs", "pruneIntervalMs",
     "nonceStore", "exemptPaths", "contentTypes", "audit",
-    "maxDecryptedBytes",
+    "maxDecryptedBytes", "trustProxy",
   ], "middleware.apiEncrypt");
   var keypairs       = _resolveKeypairs(opts);
   var activeKeypair  = keypairs[0];
@@ -205,6 +205,7 @@ function create(opts) {
         ? opts.contentTypes.slice()
         : DEFAULT_CONTENT_TYPES.slice());
   var auditOn        = opts.audit !== false;
+  var trustProxy     = opts.trustProxy === true;
   var lastPruneAt    = 0;
 
   function _isExempt(req) {
@@ -233,7 +234,7 @@ function create(opts) {
   function _emitFailure(req, reason) {
     var info = {
       reason:    reason,
-      ip:        (req.socket && req.socket.remoteAddress) || null,
+      ip:        requestHelpers.clientIp(req, { trustProxy: trustProxy }),
       path:      req.pathname || (req.url || "/").split("?")[0],
       method:    req.method,
       ts:        new Date().toISOString(),

package/lib/notify.js

@@ -48,6 +48,7 @@
  */
 
 var lazyRequire = require("./lazy-require");
+var bootLog = require("./log");
 var requestHelpers = require("./request-helpers");
 var safeAsync = require("./safe-async");
 var safeUrl = require("./safe-url");
@@ -274,7 +275,6 @@ function logTransport(opts) {
   if (opts.logger && typeof opts.logger.info === "function") {
     logger = opts.logger;
   } else {
-    var bootLog = require("./log");
     logger = bootLog.boot("notify.log");
     // boot returns a fn-with-fields shape; tolerate both.
     if (typeof logger === "function") {

package/lib/pagination.js

@@ -89,6 +89,7 @@
  */
 
 var nodeCrypto = require("node:crypto");
+var crypto = require("./crypto");
 var { defineClass } = require("./framework-error");
 
 var PaginationError = defineClass("PaginationError", { alwaysPermanent: true });
@@ -171,7 +172,7 @@ function decodeCursor(token, secret) {
     throw new PaginationError("pagination/bad-cursor", "cursor base64 decode failed");
   }
   var expected = _tag(sb, json);
-  if (tag.length !== expected.length || !nodeCrypto.timingSafeEqual(tag, expected)) {
+  if (!crypto.timingSafeEqual(tag, expected)) {
     throw new PaginationError("pagination/cursor-tag-mismatch",
       "cursor HMAC verification failed (tampered or wrong secret)");
   }

package/lib/parsers/safe-env.js

@@ -57,6 +57,7 @@
 var C = require("../constants");
 var atomicFile = require("../atomic-file");
 var safeBuffer = require("../safe-buffer");
+var safeJson = require("../safe-json");
 var { FrameworkError } = require("../framework-error");
 var { boot } = require("../log");
 
@@ -275,7 +276,6 @@ function _coerceType(rawValue, type, key) {
     );
   }
   if (type === "json") {
-    var safeJson = require("./../safe-json");
     try { return safeJson.parse(rawValue); }
     catch (e) {
       throw new SafeEnvError("invalid JSON for key '" + key + "': " + e.message,
@@ -437,7 +437,6 @@ function load(filepath, opts) {
   if (snapshotPath && atomicFile.exists(snapshotPath)) {
     try {
       var snapBuf = atomicFile.readSync(snapshotPath);
-      var safeJson = require("./../safe-json");
       prevValues = safeJson.parse(snapBuf) || {};
     } catch (_e) { /* missing/corrupt snapshot → treat as empty */ }
   }

package/lib/queue-local.js

@@ -31,6 +31,7 @@
  */
 var cluster = require("./cluster");
 var clusterStorage = require("./cluster-storage");
+var C = require("./constants");
 var { generateToken } = require("./crypto");
 var cryptoField = require("./crypto-field");
 var lazyRequire = require("./lazy-require");
@@ -108,7 +109,7 @@ function create(_config) {
     cluster.requireLeader();
     opts = opts || {};
     var nowMs = Date.now();
-    var availableAt = nowMs + (opts.delaySeconds ? opts.delaySeconds * 1000 : 0);
+    var availableAt = nowMs + (opts.delaySeconds ? C.TIME.seconds(opts.delaySeconds) : 0);
 
     var priority = (typeof opts.priority === "number" && isFinite(opts.priority))
       ? Math.floor(opts.priority) : 0;

package/lib/queue.js

@@ -31,6 +31,7 @@
  *                                       failed (status='failed')
  */
 var C = require("./constants");
+var clusterStorage = require("./cluster-storage");
 var crypto = require("./crypto");
 var lazyRequire = require("./lazy-require");
 var observability = require("./observability");
@@ -196,7 +197,7 @@ function consume(queueName, handler, opts) {
     }
     rateLimit = {
       max:        opts.rateLimit.max,
-      windowMs:   opts.rateLimit.perSeconds * 1000,
+      windowMs:   C.TIME.seconds(opts.rateLimit.perSeconds),
       timestamps: [],
     };
   }
@@ -602,7 +603,6 @@ function enqueueFlow(spec) {
       }
       // Second pass: write dependsOn (translated to jobIds) for children
       // that need it, and parking-lot their availableAt to MAX_SAFE_INTEGER.
-      var clusterStorage = require("./cluster-storage");
       for (var q = 0; q < jobs.length; q++) {
         var j = jobs[q];
         if (j.dependsOn.length === 0) continue;

package/lib/router.js

@@ -26,6 +26,7 @@ var path = require("path");
 var { URL } = require("url");
 var C = require("./constants");
 var safeAsync = require("./safe-async");
+var safeEnv = require("./parsers/safe-env");
 var websocket = require("./websocket");
 var { boot } = require("./log");
 
@@ -112,7 +113,7 @@ function _makeResponseValidator(spec) {
   //   - BLAMEJS_VALIDATE_RESPONSES=warn (or per-route validateResponse: "warn")
   //     → log a warning; ship the response as-is (prod-safe).
   var perRoute = spec.validateResponse;
-  var globalMode = process.env.BLAMEJS_VALIDATE_RESPONSES;
+  var globalMode = safeEnv.readVar("BLAMEJS_VALIDATE_RESPONSES");
   var mode = (perRoute === "throw" || perRoute === "warn") ? perRoute :
              (globalMode === "throw" || globalMode === "warn") ? globalMode : null;
   if (!mode) return function passthrough(_req, _res, next) { next(); };
@@ -260,9 +261,10 @@ class Router {
       // route dispatch) but before any route-specific handler.
       handlers = [_makeSchemaValidator(split.spec)].concat(handlers);
       // Response validation (dev/opt-in via env or per-route opt).
+      var globalValidateMode = safeEnv.readVar("BLAMEJS_VALIDATE_RESPONSES");
       if (split.spec.response &&
-          (process.env.BLAMEJS_VALIDATE_RESPONSES === "throw" ||
-           process.env.BLAMEJS_VALIDATE_RESPONSES === "warn" ||
+          (globalValidateMode === "throw" ||
+           globalValidateMode === "warn" ||
            split.spec.validateResponse)) {
         handlers = [_makeResponseValidator(split.spec)].concat(handlers);
       }

package/lib/testing.js

@@ -60,6 +60,7 @@
  */
 
 var fs = require("node:fs");
+var http = require("node:http");
 var os = require("node:os");
 var nodePath = require("node:path");
 var EventEmitter = require("node:events").EventEmitter;
@@ -567,7 +568,6 @@ function listenOnRandomPort(server, host) {
 // production traffic takes. Server is closed automatically when the
 // promise resolves or rejects.
 function request(target) {
-  var http = require("node:http");
   // Resolve target → request listener
   var server;
   var ownsServer = false;

package/lib/totp.js

@@ -60,6 +60,7 @@
  * 1Password, Bitwarden, Aegis, Microsoft Authenticator all do).
  */
 var nodeCrypto = require("crypto");
+var crypto = require("./crypto");
 var { generateBytes, generateToken } = require("./crypto");
 var { AuthError } = require("./framework-error");
 
@@ -214,8 +215,7 @@ function verify(secret, code, opts) {
     try { expected = compute(secret, step, opts); }
     catch (_e) { return false; }
     var expectedBuf = Buffer.from(expected);
-    if (expectedBuf.length === userBuf.length &&
-        nodeCrypto.timingSafeEqual(expectedBuf, userBuf)) {
+    if (crypto.timingSafeEqual(expectedBuf, userBuf)) {
       return step;
     }
   }

package/lib/webhook.js

@@ -539,7 +539,7 @@ function verifier(opts) {
 
     // Timestamp window: signed in seconds, compare to ms clock.
     var nowMs = nowFn();
-    var ageMs = nowMs - (ts * 1000);
+    var ageMs = nowMs - C.TIME.seconds(ts);
     if (ageMs > toleranceMs) {
       throw _failure("EXPIRED", "webhook: timestamp older than toleranceMs (age=" + ageMs + "ms)", "expired", ctxReq);
     }
@@ -570,7 +570,7 @@ function verifier(opts) {
     }
 
     if (nonceStore) {
-      var expireAt = (ts * 1000) + toleranceMs;
+      var expireAt = C.TIME.seconds(ts) + toleranceMs;
       var fresh = await nonceStore.checkAndInsert(parsed.id, expireAt);
       if (!fresh) {
         throw _failure("REPLAY", "webhook: id '" + parsed.id + "' has been seen before", "replay", ctxReq);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.5.17",
+  "version": "0.5.18",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",