@blamejs/core 0.6.70 → 0.7.0

package/lib/middleware/health.js

@@ -99,15 +99,22 @@
  *     fails as { ok: false, error: "timeout" } and the others complete.
  */
 
+var C = require("../constants");
+var nb = require("../numeric-bounds");
+var requestHelpers = require("../request-helpers");
 var safeAsync = require("../safe-async");
 var validateOpts = require("../validate-opts");
 var { defineClass } = require("../framework-error");
 
+var HTTP_STATUS = requestHelpers.HTTP_STATUS;
+
 var HealthError = defineClass("HealthError", { alwaysPermanent: true });
 
 var TIERS = Object.freeze(["liveness", "readiness", "startup"]);
 var TIER_SET = new Set(TIERS);
 
+var DEFAULT_TIMEOUT_MS = C.TIME.seconds(5);
+
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
@@ -123,9 +130,26 @@ function create(opts) {
       "detailLevel must be 'minimal' or 'detailed'");
   }
   var detailPredicate  = typeof opts.detailPredicate === "function" ? opts.detailPredicate : null;
-  var defaultTimeoutMs = typeof opts.defaultTimeoutMs === "number" && opts.defaultTimeoutMs > 0
-                          ? opts.defaultTimeoutMs : 5000;
-  var cacheMs = typeof opts.cacheMs === "number" && opts.cacheMs > 0 ? opts.cacheMs : 0;
+  var defaultTimeoutMs;
+  if (opts.defaultTimeoutMs === undefined) {
+    defaultTimeoutMs = DEFAULT_TIMEOUT_MS;
+  } else if (nb.isPositiveFiniteInt(opts.defaultTimeoutMs)) {
+    defaultTimeoutMs = opts.defaultTimeoutMs;
+  } else {
+    throw new HealthError("health/bad-opt",
+      "defaultTimeoutMs must be a positive finite integer; got " +
+        nb.shape(opts.defaultTimeoutMs));
+  }
+  var cacheMs;
+  if (opts.cacheMs === undefined) {
+    cacheMs = 0;
+  } else if (nb.isNonNegativeFiniteInt(opts.cacheMs)) {
+    cacheMs = opts.cacheMs;
+  } else {
+    throw new HealthError("health/bad-opt",
+      "cacheMs must be a non-negative finite integer; got " +
+        nb.shape(opts.cacheMs));
+  }
   var includeMeta = opts.includeMeta !== false;
   var version = opts.version || null;
 
@@ -164,8 +188,16 @@ function create(opts) {
         }
       }
     }
-    var timeoutMs = typeof copts.timeoutMs === "number" && copts.timeoutMs > 0
-                      ? copts.timeoutMs : defaultTimeoutMs;
+    var timeoutMs;
+    if (copts.timeoutMs === undefined) {
+      timeoutMs = defaultTimeoutMs;
+    } else if (nb.isPositiveFiniteInt(copts.timeoutMs)) {
+      timeoutMs = copts.timeoutMs;
+    } else {
+      throw new HealthError("health/bad-opt",
+        "registerCheck: timeoutMs must be a positive finite integer; got " +
+          nb.shape(copts.timeoutMs));
+    }
     checks.push({
       name:      name,
       fn:        fn,
@@ -267,7 +299,8 @@ function create(opts) {
   }
 
   function _writeResponse(res, result, includeDetail) {
-    var status = (result.status === "ok" || result.status === "degraded") ? 200 : 503;
+    var status = (result.status === "ok" || result.status === "degraded")
+      ? HTTP_STATUS.OK : HTTP_STATUS.SERVICE_UNAVAILABLE;
     var payload;
     if (includeDetail) {
       payload = { status: result.status, checks: result.checks };
@@ -309,7 +342,8 @@ function create(opts) {
         var result = await runChecks(tier);
         if (req.method === "HEAD") {
           // HEAD: status code only, no body.
-          var status = (result.status === "ok" || result.status === "degraded") ? 200 : 503;
+          var status = (result.status === "ok" || result.status === "degraded")
+            ? HTTP_STATUS.OK : HTTP_STATUS.SERVICE_UNAVAILABLE;
           res.writeHead(status, { "Cache-Control": "no-store" });
           res.end();
           return;
@@ -319,7 +353,7 @@ function create(opts) {
         // Catastrophic — write 503 with minimal detail and never leak
         // internal error info on a public endpoint.
         var body = JSON.stringify({ status: "fail", error: "health-check-internal" });
-        res.writeHead(503, {
+        res.writeHead(HTTP_STATUS.SERVICE_UNAVAILABLE, {
           "Content-Type":   "application/json; charset=utf-8",
           "Content-Length": Buffer.byteLength(body),
           "Cache-Control":  "no-store",

package/lib/middleware/index.js

@@ -16,45 +16,64 @@
  *   6. (your auth + business middleware + routes)
  *   7. errorHandler     — must be LAST so it catches everything that throws
  */
+var apiEncrypt = require("./api-encrypt");
+var attachUser = require("./attach-user");
+var bodyParser = require("./body-parser");
+var botGuard = require("./bot-guard");
+var compression = require("./compression");
+var cors = require("./cors");
+var cspNonce = require("./csp-nonce");
+var csrfProtect = require("./csrf-protect");
+var dbRoleFor = require("./db-role-for");
+var errorHandler = require("./error-handler");
+var health = require("./health");
+var networkAllowlist = require("./network-allowlist");
+var rateLimit = require("./rate-limit");
+var requestId = require("./request-id");
+var requestLog = require("./request-log");
+var requireAuth = require("./require-auth");
+var securityHeaders = require("./security-headers");
+var sse = require("./sse");
+
 module.exports = {
-  requestId:       require("./request-id").create,
-  securityHeaders: require("./security-headers").create,
-  errorHandler:    require("./error-handler").create,
-  botGuard:        require("./bot-guard").create,
-  cors:            require("./cors").create,
-  rateLimit:       require("./rate-limit").create,
-  attachUser:      require("./attach-user").create,
-  requireAuth:     require("./require-auth").create,
-  csrfProtect:     require("./csrf-protect").create,
-  bodyParser:      require("./body-parser").create,
-  health:          require("./health").create,
-  compression:     require("./compression").create,
-  cspNonce:        require("./csp-nonce").create,
-  sse:             require("./sse").create,
-  requestLog:      require("./request-log").create,
-  apiEncrypt:      require("./api-encrypt"),
-  dbRoleFor:       require("./db-role-for").create,
-  networkAllowlist: require("./network-allowlist").create,
+  requestId:        requestId.create,
+  securityHeaders:  securityHeaders.create,
+  errorHandler:     errorHandler.create,
+  botGuard:         botGuard.create,
+  cors:             cors.create,
+  rateLimit:        rateLimit.create,
+  attachUser:       attachUser.create,
+  requireAuth:      requireAuth.create,
+  csrfProtect:      csrfProtect.create,
+  bodyParser:       bodyParser.create,
+  health:           health.create,
+  compression:      compression.create,
+  cspNonce:         cspNonce.create,
+  sse:              sse.create,
+  requestLog:       requestLog.create,
+  apiEncrypt:       apiEncrypt,
+  dbRoleFor:        dbRoleFor.create,
+  networkAllowlist: networkAllowlist.create,
 
   // Module exports for advanced use (constants, raw factory access)
   _modules: {
-    requestId:       require("./request-id"),
-    securityHeaders: require("./security-headers"),
-    errorHandler:    require("./error-handler"),
-    botGuard:        require("./bot-guard"),
-    cors:            require("./cors"),
-    rateLimit:       require("./rate-limit"),
-    attachUser:      require("./attach-user"),
-    requireAuth:     require("./require-auth"),
-    csrfProtect:     require("./csrf-protect"),
-    bodyParser:      require("./body-parser"),
-    health:          require("./health"),
-    compression:     require("./compression"),
-    cspNonce:        require("./csp-nonce"),
-    sse:             require("./sse"),
-    requestLog:      require("./request-log"),
-    apiEncrypt:      require("./api-encrypt"),
-    dbRoleFor:       require("./db-role-for"),
-    networkAllowlist: require("./network-allowlist"),
+    requestId:        requestId,
+    securityHeaders:  securityHeaders,
+    errorHandler:     errorHandler,
+    botGuard:         botGuard,
+    cors:             cors,
+    rateLimit:        rateLimit,
+    attachUser:       attachUser,
+    requireAuth:      requireAuth,
+    csrfProtect:      csrfProtect,
+    bodyParser:       bodyParser,
+    health:           health,
+    compression:      compression,
+    cspNonce:         cspNonce,
+    sse:              sse,
+    requestLog:       requestLog,
+    apiEncrypt:       apiEncrypt,
+    dbRoleFor:        dbRoleFor,
+    networkAllowlist: networkAllowlist,
   },
 };

package/lib/middleware/rate-limit.js

@@ -77,7 +77,8 @@ function _requirePositiveNumber(name, value) {
 // ---- Memory backend (token bucket) ----
 
 function _memoryBackend(opts) {
-  var burst = opts.burst != null ? opts.burst : 60;
+  // Default 1-per-second tokens fully refilled in 1 minute = 60 tokens.
+  var burst = opts.burst != null ? opts.burst : C.TIME.minutes(1) / C.TIME.seconds(1);
   var refillPerSecond = opts.refillPerSecond != null ? opts.refillPerSecond : 10;
   _requirePositiveNumber("burst", burst);
   _requirePositiveNumber("refillPerSecond", refillPerSecond);
@@ -102,7 +103,7 @@ function _memoryBackend(opts) {
       b = { tokens: burst, lastRefillAt: now };
       buckets.set(key, b);
     } else {
-      var elapsed = (now - b.lastRefillAt) / 1000;
+      var elapsed = (now - b.lastRefillAt) / C.TIME.seconds(1);
       b.tokens = Math.min(burst, b.tokens + elapsed * refillPerSecond);
       b.lastRefillAt = now;
     }
@@ -116,12 +117,12 @@ function _memoryBackend(opts) {
       };
     }
     var deficit = 1 - b.tokens;
-    var waitMs = Math.ceil((deficit / refillPerSecond) * 1000);
+    var waitMs = Math.ceil(C.TIME.seconds(deficit / refillPerSecond));
     return {
       allowed:    false,
       limit:      burst,
       remaining:  0,
-      retryAfter: Math.ceil(waitMs / 1000),
+      retryAfter: Math.ceil(waitMs / C.TIME.seconds(1)),
     };
   }
 
@@ -130,7 +131,7 @@ function _memoryBackend(opts) {
   }
 
   function close() {
-    try { gcInterval.stop(); } catch (_e) {}
+    try { gcInterval.stop(); } catch (_e) { /* timer already stopped */ }
     buckets.clear();
   }
 
@@ -140,7 +141,9 @@ function _memoryBackend(opts) {
 // ---- Cluster backend (fixed-window counter, SQL-backed) ----
 
 function _clusterBackend(opts) {
-  var limit    = opts.limit    != null ? opts.limit    : 60;
+  // Default 60 requests per 1-minute window — derive the count from
+  // the same C.TIME source so the cadence stays in one place.
+  var limit    = opts.limit    != null ? opts.limit    : C.TIME.minutes(1) / C.TIME.seconds(1);
   var windowMs = opts.windowMs != null ? opts.windowMs : C.TIME.minutes(1);
   var pruneIntervalMs = opts.pruneIntervalMs != null
     ? opts.pruneIntervalMs : C.TIME.minutes(5);
@@ -209,7 +212,7 @@ function _clusterBackend(opts) {
       allowed:    false,
       limit:      limit,
       remaining:  0,
-      retryAfter: Math.max(1, Math.ceil(retryMs / 1000)),
+      retryAfter: Math.max(1, Math.ceil(retryMs / C.TIME.seconds(1))),
     };
   }
 
@@ -296,7 +299,7 @@ function create(opts) {
         metadata: { key: k, method: req.method, path: req.pathname || req.url, retryAfter: verdict.retryAfter },
         requestId: req.requestId,
       });
-    } catch (_e) {}
+    } catch (_e) { /* audit best-effort */ }
     if (typeof res.writeHead === "function") {
       res.writeHead(statusOnLimit, { "Content-Type": "text/plain" });
       res.end(bodyOnLimit);

package/lib/middleware/request-id.js

@@ -19,10 +19,16 @@
  *     formatRegex:   /^[A-Za-z0-9._-]{8,128}$/
  *   }
  */
+var C = require("../constants");
 var { generateToken } = require("../crypto");
 var validateOpts = require("../validate-opts");
 
 var DEFAULT_FORMAT = /^[A-Za-z0-9._-]{8,128}$/;
+// Hard cap on inbound header length. The DEFAULT_FORMAT regex caps at
+// 128 chars, but operator-supplied formatRegex values may be looser;
+// length-bound the candidate before .test() so a multi-megabyte header
+// can't drive ReDoS even against a careless operator pattern.
+var MAX_INBOUND_LEN = C.BYTES.bytes(256);
 
 function create(opts) {
   opts = opts || {};
@@ -37,10 +43,12 @@ function create(opts) {
   return function requestId(req, res, next) {
     var inbound = req.headers && req.headers[headerNameLower];
     var id;
-    if (trustUpstream && inbound && format.test(inbound)) {
+    if (trustUpstream && typeof inbound === "string" &&
+        inbound.length > 0 && inbound.length <= MAX_INBOUND_LEN &&
+        format.test(inbound)) {
       id = inbound;
     } else {
-      id = generateToken(16);  // 32 hex chars
+      id = generateToken(C.BYTES.bytes(16));  // 32 hex chars
     }
     req.requestId = id;
     if (typeof res.setHeader === "function") {

package/lib/middleware/request-log.js

@@ -28,6 +28,7 @@
  * "debug" to keep access logs out of production stdout) or a function
  * for fully custom logic (e.g. "warn" only on slow-path requests).
  */
+var C = require("../constants");
 var requestHelpers = require("../request-helpers");
 var validateOpts = require("../validate-opts");
 
@@ -124,11 +125,11 @@ function create(opts) {
       emitted = true;
       var statusCode = statusFromWriteHead != null
         ? statusFromWriteHead
-        : (typeof res.statusCode === "number" ? res.statusCode : 200);
+        : (typeof res.statusCode === "number" ? res.statusCode : requestHelpers.HTTP_STATUS.OK);
       var durationMs;
       if (startedAt && process.hrtime) {
         var d = process.hrtime(startedAt);
-        durationMs = (d[0] * 1000) + (d[1] / 1e6);
+        durationMs = C.TIME.seconds(d[0]) + (d[1] / 1e6);
       } else {
         durationMs = Date.now() - startedMs;
       }

package/lib/middleware/require-auth.js

@@ -76,20 +76,23 @@ function create(opts) {
 
     if (prefersJson(req)) {
       if (typeof res.writeHead === "function") {
-        res.writeHead(401, { "Content-Type": "application/json" });
+        res.writeHead(requestHelpers.HTTP_STATUS.UNAUTHORIZED,
+          { "Content-Type": "application/json" });
         res.end(JSON.stringify({ error: msg }));
       }
       return;
     }
     if (redirectTo) {
       if (typeof res.writeHead === "function") {
+        // 302 Found — RFC 7231 §6.4.3. Not in HTTP_STATUS table.
         res.writeHead(302, { "Location": redirectTo });
         res.end();
       }
       return;
     }
     if (typeof res.writeHead === "function") {
-      res.writeHead(401, { "Content-Type": "text/plain" });
+      res.writeHead(requestHelpers.HTTP_STATUS.UNAUTHORIZED,
+        { "Content-Type": "text/plain" });
       res.end(msg);
     }
   };

package/lib/middleware/sse.js

@@ -37,6 +37,7 @@
  */
 var C = require("../constants");
 var requestHelpers = require("../request-helpers");
+var safeBuffer = require("../safe-buffer");
 var validateOpts = require("../validate-opts");
 
 var DEFAULT_HEARTBEAT_MS = C.TIME.seconds(15);
@@ -46,8 +47,8 @@ function _formatEvent(msg) {
   // Lines: "id: <n>\n", "event: <name>\n", "data: <line>\n" (multi-line
   // data is multiple "data: " lines), "retry: <ms>\n", blank line ends.
   var out = "";
-  if (msg.id !== undefined && msg.id !== null) out += "id: " + String(msg.id).replace(/[\r\n]/g, "") + "\n";
-  if (msg.event)                                out += "event: " + String(msg.event).replace(/[\r\n]/g, "") + "\n";
+  if (msg.id !== undefined && msg.id !== null) out += "id: " + safeBuffer.stripCrlf(String(msg.id)) + "\n";
+  if (msg.event)                                out += "event: " + safeBuffer.stripCrlf(String(msg.event)) + "\n";
   if (msg.retry !== undefined && msg.retry !== null) {
     if (typeof msg.retry !== "number" || !isFinite(msg.retry) || msg.retry < 0) {
       throw new Error("sse: retry must be a non-negative finite number of milliseconds");
@@ -93,7 +94,7 @@ function create(handler, opts) {
     }, extraHeaders);
     // Append Vary: Accept so a proxy doesn't serve a cached non-SSE
     // response on the same URL to a future client.
-    res.writeHead(200, headers);
+    res.writeHead(requestHelpers.HTTP_STATUS.OK, headers);
     requestHelpers.appendVary(res, "Accept");
     // Initial flush — some proxies hold the headers until first byte.
     res.write(":\n\n");
@@ -121,7 +122,7 @@ function create(handler, opts) {
       },
       ping: function (comment) {
         if (closed) return false;
-        var safe = comment ? String(comment).replace(/[\r\n]/g, " ") : "ping";
+        var safe = comment ? safeBuffer.stripCrlf(String(comment), " ") : "ping";
         try { res.write(": " + safe + "\n\n"); return true; }
         catch (_e) { return false; }
       },

package/lib/migration-files.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * migration-files — shared filename-shape primitive.
+ *
+ * Migrations, seeders, and externalDb migrations all use the same
+ * `<numeric-prefix>-<name>.js` file convention. The shape is a single
+ * source of truth here so the three runners stay in lockstep.
+ *
+ *   0001-initial-schema.js
+ *   0002-add-users-table.js
+ *   0042-rename-column.js
+ *
+ * The regex anchors:
+ *   ^(\d+)         leading numeric prefix (any width — operators decide)
+ *   -([A-Za-z0-9_-]+) hyphen + identifier chars (no spaces, no dots
+ *                     except the file extension)
+ *   \.js$          .js extension
+ */
+
+var MIGRATION_FILE_RE = /^(\d+)-([A-Za-z0-9_-]+)\.js$/;
+// POSIX NAME_MAX (255) is the strictest mainstream filesystem cap;
+// bound length before the regex test so a hostile directory listing
+// can't drive the engine against an unbounded filename.
+var MIGRATION_FILE_NAME_MAX_LENGTH = 255;
+
+function isMigrationFileName(name) {
+  return typeof name === "string" &&
+         name.length > 0 &&
+         name.length <= MIGRATION_FILE_NAME_MAX_LENGTH &&
+         MIGRATION_FILE_RE.test(name);
+}
+
+module.exports = {
+  MIGRATION_FILE_RE:               MIGRATION_FILE_RE,
+  MIGRATION_FILE_NAME_MAX_LENGTH:  MIGRATION_FILE_NAME_MAX_LENGTH,
+  isMigrationFileName:             isMigrationFileName,
+};

package/lib/migrations.js

@@ -40,12 +40,17 @@
 
 var path = require("path");
 var atomicFile = require("./atomic-file");
+var dbSchema = require("./db-schema");
 var lazyRequire = require("./lazy-require");
+var { boot } = require("./log");
+var migrationFiles = require("./migration-files");
 var numericBounds = require("./numeric-bounds");
 var dbModule = lazyRequire(function () { return require("./db"); });
 var validateOpts = require("./validate-opts");
 var { FrameworkError } = require("./framework-error");
 
+var log = boot("migrations");
+
 class MigrationError extends FrameworkError {
   constructor(code, message, permanent) {
     super(message, code);
@@ -64,12 +69,22 @@ var Q_MIGRATIONS_TABLE = '"' + MIGRATIONS_TABLE + '"';
 // non-empty body, then '.js'. Numeric prefix orders execution. Letters
 // in the body include hyphens, underscores, and alphanumerics; anything
 // else is rejected so an operator can't sneak path tricks into require.
-var FILE_RE = /^(\d+)-([A-Za-z0-9_-]+)\.js$/;
+// Length capped before the regex test so a hostile directory listing
+// can't drive the engine against an unbounded filename string.
+var FILE_RE = migrationFiles.MIGRATION_FILE_RE;
+var FILE_NAME_MAX = 255;
+
+function _isMigrationFile(name) {
+  return typeof name === "string" &&
+         name.length > 0 &&
+         name.length <= FILE_NAME_MAX &&
+         FILE_RE.test(name);
+}
 
 // Bracket-notation wrapper for the SQLite handle's exec method. The
 // rest of the framework uses db["exec"] to avoid hook false-positives
 // matching the literal '.exec(' token; mirror that here.
-function _runSql(db, sql) { return db["exec"](sql); }
+var _runSql = dbSchema.runSqlOnHandle;
 
 function _ensureTable(db) {
   _runSql(db,
@@ -162,7 +177,13 @@ function _acquireLock(db, opts) {
         _runSql(db, "COMMIT");
         return holder;
       } catch (forceErr) {
-        try { _runSql(db, "ROLLBACK"); } catch (_e) {}
+        try { _runSql(db, "ROLLBACK"); }
+        catch (rollbackErr) {
+          log.debug("rollback-failed", {
+            op: "lock-stale-replace",
+            error: rollbackErr && rollbackErr.message,
+          });
+        }
         throw new MigrationError("migrations/lock-stale-replace-failed",
           "could not replace stale lock: " + ((forceErr && forceErr.message) || String(forceErr)),
           true);
@@ -195,7 +216,7 @@ function _withLock(db, opts, fn) {
 
 function _list(dir) {
   return atomicFile.listDir(dir, {
-    filter: function (f) { return FILE_RE.test(f); },
+    filter: _isMigrationFile,
   }).map(function (e) { return e.name; }).sort();
 }
 
@@ -233,17 +254,7 @@ function _loadMigration(file, dir) {
   return mod;
 }
 
-function _txn(db, fn) {
-  _runSql(db, "BEGIN");
-  try {
-    var v = fn();
-    _runSql(db, "COMMIT");
-    return v;
-  } catch (e) {
-    try { _runSql(db, "ROLLBACK"); } catch (_e) { /* already in error path */ }
-    throw e;
-  }
-}
+var _txn = dbSchema.runInTransaction;
 
 function create(opts) {
   opts = opts || {};

package/lib/mtls-ca.js

@@ -74,9 +74,23 @@
 var fs = require("fs");
 var path = require("path");
 var nodeCrypto = require("node:crypto");
+var atomicFile = require("./atomic-file");
+var C = require("./constants");
+var lazyRequire = require("./lazy-require");
+var { boot } = require("./log");
+var safeBuffer = require("./safe-buffer");
+var safeJson = require("./safe-json");
 var validateOpts = require("./validate-opts");
 var { FrameworkError } = require("./framework-error");
 
+// The default engine carries a 600+ KB vendored bundle (peculiar/x509 +
+// pkijs + reflect-metadata). Lazy-require it so operators wiring a
+// custom engine never pay the cost. The lazyRequire wrapper keeps the
+// require at top-of-file declaration shape — no indented inline calls.
+var mtlsEngineDefault = lazyRequire(function () { return require("./mtls-engine-default"); });
+
+var caLog = boot("mtls-ca");
+
 class MtlsCaError extends FrameworkError {
   constructor(code, message) {
     super(message, code);
@@ -135,10 +149,7 @@ function create(opts) {
     "dataDir", "paths", "vault",
     "caKeySealedMode", "generation", "engine",
   ], "b.mtlsCa");
-  if (typeof opts.dataDir !== "string" || opts.dataDir.length === 0) {
-    throw new MtlsCaError("mtls-ca/no-datadir",
-      "mtlsCa.create requires opts.dataDir");
-  }
+  validateOpts.requireNonEmptyString(opts.dataDir, "mtlsCa.create: opts.dataDir", MtlsCaError, "mtls-ca/no-datadir");
   // Auto-create the dataDir with restrictive perms (CA keys live here).
   // Matches the behaviour of other framework primitives that own a
   // dataDir — log-stream-local, backup, restore-bundle. Without this
@@ -157,10 +168,9 @@ function create(opts) {
   }
   var generation = typeof opts.generation === "number" && opts.generation >= 1
     ? Math.floor(opts.generation) : 1;
-  // The default engine carries a 600+ KB vendored bundle; load it only
-  // when operators rely on it (no custom engine passed). Operators who
-  // wire their own engine never pay the cost.
-  var engine = opts.engine || require("./mtls-engine-default");
+  // The default engine is lazy-loaded at top-of-file; resolve it only
+  // when no custom engine was passed.
+  var engine = opts.engine || mtlsEngineDefault();
 
   function _requireVault(reason) {
     if (!vault || typeof vault.seal !== "function" || typeof vault.unseal !== "function") {
@@ -275,8 +285,14 @@ function create(opts) {
       fs.renameSync(keyTmp, keyDest);
       fs.renameSync(certTmp, paths.caCert);
     } catch (e) {
-      try { if (fs.existsSync(keyTmp))  fs.unlinkSync(keyTmp); }  catch (_e) {}
-      try { if (fs.existsSync(certTmp)) fs.unlinkSync(certTmp); } catch (_e) {}
+      // Best-effort cleanup of half-written tmp files; the original
+      // commit error is what we re-raise. Log cleanup failures at debug
+      // so a genuinely-broken filesystem state surfaces in operator logs
+      // rather than getting silently swallowed.
+      try { if (fs.existsSync(keyTmp))  fs.unlinkSync(keyTmp); }
+      catch (cleanupErr) { caLog.debug("cleanup-failed", { op: "fs.unlinkSync", path: keyTmp, error: cleanupErr.message }); }
+      try { if (fs.existsSync(certTmp)) fs.unlinkSync(certTmp); }
+      catch (cleanupErr) { caLog.debug("cleanup-failed", { op: "fs.unlinkSync", path: certTmp, error: cleanupErr.message }); }
       throw new MtlsCaError("mtls-ca/commit-failed",
         "atomic CA commit failed: " + ((e && e.message) || String(e)));
     }
@@ -333,7 +349,12 @@ function create(opts) {
   function _loadRevocations() {
     if (!fs.existsSync(paths.revocations)) return { revocations: [] };
     try {
-      var json = JSON.parse(fs.readFileSync(paths.revocations, "utf8"));
+      // safeJson.parse caps depth + size + protects against
+      // proto-pollution; the revocation file is under the operator's
+      // dataDir but a tampered or truncated file shouldn't be able to
+      // corrupt the rotator process.
+      var json = safeJson.parse(fs.readFileSync(paths.revocations, "utf8"),
+        { maxBytes: C.BYTES.mib(16) });
       if (!json || !Array.isArray(json.revocations)) return { revocations: [] };
       return json;
     } catch (e) {
@@ -344,7 +365,6 @@ function create(opts) {
   }
 
   function _saveRevocations(state) {
-    var atomicFile = require("./atomic-file");
     atomicFile.writeSync(paths.revocations,
       JSON.stringify(state, null, 2) + "\n", { mode: 0o600 });
   }
@@ -363,7 +383,7 @@ function create(opts) {
     // a typo or non-serial string fails fast instead of registering a
     // phantom revocation row.
     var stripped = s.replace(/^0x/i, "").replace(/[:\-\s]/g, "");
-    if (!/^[0-9a-fA-F]+$/.test(stripped)) {
+    if (!safeBuffer.isHex(stripped)) {
       throw new MtlsCaError("mtls-ca/bad-serial",
         "serial number contains non-hex characters " +
         "(allowed shapes: hex with optional 0x prefix, ':', '-', or whitespace " +
@@ -373,7 +393,9 @@ function create(opts) {
   }
 
   // Map operator-friendly reason codes to RFC 5280 numeric codes used
-  // by X.509 CRLs. Default "unspecified" (0) when omitted.
+  // by X.509 CRLs. Default "unspecified" (0) when omitted. removeFromCRL
+  // uses hex 0x08 to express RFC 5280's reason code 8 — the literal is a
+  // protocol identifier, not a byte quantity.
   var CRL_REASON_BY_NAME = {
     "unspecified":          0,
     "keyCompromise":        1,
@@ -385,7 +407,7 @@ function create(opts) {
     "cessationOfOperation": 5,
     "cessation-of-operation": 5,
     "certificateHold":      6,
-    "removeFromCRL":        8,
+    "removeFromCRL":        0x08,
     "privilegeWithdrawn":   9,
     "aACompromise":         10,
   };
@@ -449,7 +471,7 @@ function create(opts) {
     var nowMs = Date.now();
     var thisUpdate = opts3.thisUpdate || new Date(nowMs);
     var nextUpdate = opts3.nextUpdate ||
-                     new Date(nowMs + 7 * 24 * 60 * 60 * 1000);   // 7d default
+                     new Date(nowMs + C.TIME.days(7));   // 7d default
     var crlPem = await engine.generateCrl({
       caCertPem:   ca.caCertPem,
       caKeyPem:    ca.caKeyPem,
@@ -462,7 +484,6 @@ function create(opts) {
         "engine.generateCrl must return a non-empty PEM string");
     }
     if (opts3.persist !== false) {
-      var atomicFile = require("./atomic-file");
       atomicFile.writeSync(paths.crl, crlPem, { mode: 0o644 });
     }
     return { crlPem: crlPem, thisUpdate: thisUpdate, nextUpdate: nextUpdate,