@blamejs/core 0.6.69 → 0.7.0

package/lib/error-page.js

@@ -39,61 +39,67 @@
  */
 
 var lazyRequire = require("./lazy-require");
+var logModule = require("./log");
 var requestHelpers = require("./request-helpers");
 var safeEnv = require("./parsers/safe-env");
 var template = require("./template");
 var audit = lazyRequire(function () { return require("./audit"); });
 
+var bootLog = logModule.boot("errors-page");
+
 var _esc = template.escapeHtml;
+var H = requestHelpers.HTTP_STATUS;
 
 // Status code → default short reason. Used when the error doesn't carry
-// its own message (e.g. a generic Error thrown from a route).
-var STATUS_REASONS = {
-  400: "Bad Request",
-  401: "Unauthorized",
-  403: "Forbidden",
-  404: "Not Found",
-  405: "Method Not Allowed",
-  409: "Conflict",
-  413: "Payload Too Large",
-  415: "Unsupported Media Type",
-  422: "Unprocessable Content",
-  429: "Too Many Requests",
-  500: "Internal Server Error",
-  502: "Bad Gateway",
-  503: "Service Unavailable",
-  504: "Gateway Timeout",
-};
+// its own message (e.g. a generic Error thrown from a route). Keyed by
+// the framework's centralized HTTP_STATUS hex IDs (RFC 9110 reason
+// phrases). JS coerces numeric keys to strings, so STATUS_REASONS[404]
+// == STATUS_REASONS[H.NOT_FOUND].
+var STATUS_REASONS = {};
+STATUS_REASONS[H.BAD_REQUEST]            = "Bad Request";
+STATUS_REASONS[H.UNAUTHORIZED]           = "Unauthorized";
+STATUS_REASONS[H.FORBIDDEN]              = "Forbidden";
+STATUS_REASONS[H.NOT_FOUND]              = "Not Found";
+STATUS_REASONS[H.METHOD_NOT_ALLOWED]     = "Method Not Allowed";
+STATUS_REASONS[H.CONFLICT]               = "Conflict";
+STATUS_REASONS[H.PAYLOAD_TOO_LARGE]      = "Payload Too Large";
+STATUS_REASONS[H.UNSUPPORTED_MEDIA_TYPE] = "Unsupported Media Type";
+STATUS_REASONS[H.UNPROCESSABLE_CONTENT]  = "Unprocessable Content";
+STATUS_REASONS[H.TOO_MANY_REQUESTS]      = "Too Many Requests";
+STATUS_REASONS[H.INTERNAL_SERVER_ERROR]  = "Internal Server Error";
+STATUS_REASONS[H.BAD_GATEWAY]            = "Bad Gateway";
+STATUS_REASONS[H.SERVICE_UNAVAILABLE]    = "Service Unavailable";
+STATUS_REASONS[H.GATEWAY_TIMEOUT]        = "Gateway Timeout";
 
 // Map common framework error classes → HTTP status. Operators who
 // throw their own AppError-like classes set isAppError + statusCode
 // and bypass this map entirely.
 function _classify(err) {
   if (!err || typeof err !== "object") {
-    return { status: 500, code: "INTERNAL_ERROR", message: "Internal Server Error", classified: false };
+    return { status: H.INTERNAL_SERVER_ERROR, code: "INTERNAL_ERROR", message: "Internal Server Error", classified: false };
   }
   // Apps that follow the standard convention: { isAppError, statusCode, code, message }
   if (err.isAppError) {
     return {
-      status:  err.statusCode || 500,
+      status:  err.statusCode || H.INTERNAL_SERVER_ERROR,
       code:    err.code || "APP_ERROR",
-      message: err.message || STATUS_REASONS[err.statusCode || 500] || "Error",
+      message: err.message || STATUS_REASONS[err.statusCode || H.INTERNAL_SERVER_ERROR] || "Error",
       classified: true,
     };
   }
   // Framework error subclasses we know map to specific HTTP statuses.
   if (err.isAuthError) {
-    return { status: 401, code: err.code || "AUTH_FAILED", message: err.message || "Unauthorized", classified: true };
+    return { status: H.UNAUTHORIZED, code: err.code || "AUTH_FAILED", message: err.message || "Unauthorized", classified: true };
   }
   if (err.code === "VALIDATION_ERROR" || err.name === "ValidationError") {
-    return { status: 400, code: err.code || "VALIDATION_ERROR", message: err.message || "Bad Request", classified: true };
+    return { status: H.BAD_REQUEST, code: err.code || "VALIDATION_ERROR", message: err.message || "Bad Request", classified: true };
   }
   if (err.isSafeJsonError) {
-    return { status: 400, code: err.code || "json/invalid", message: err.message || "Bad Request", path: err.path || null, classified: true };
+    return { status: H.BAD_REQUEST, code: err.code || "json/invalid", message: err.message || "Bad Request", path: err.path || null, classified: true };
   }
   // Permanent framework errors that map cleanly to 4xx
   if ((err.isStorageError || err.isQueueError || err.isExternalDbError) && err.permanent) {
-    return { status: 400, code: err.code || "ERROR", message: err.message || "Bad Request", classified: true };
+    return { status: H.BAD_REQUEST, code: err.code || "ERROR", message: err.message || "Bad Request", classified: true };
   }
   if (typeof err.statusCode === "number") {
     return {
@@ -103,7 +109,7 @@ function _classify(err) {
       classified: true,
     };
   }
-  return { status: 500, code: err.code || "INTERNAL_ERROR", message: err.message || "Internal Server Error", classified: false };
+  return { status: H.INTERNAL_SERVER_ERROR, code: err.code || "INTERNAL_ERROR", message: err.message || "Internal Server Error", classified: false };
 }
 
 function _wantsJson(req, defaultFormat) {
@@ -303,20 +309,7 @@ function create(opts) {
   var showEnvVars     = mode === "dev" && opts.showEnvVars     === true;
   var onErrorHook = typeof opts.onError === "function" ? opts.onError : null;
 
-  function _log(level, message, fields) {
-    if (log && typeof log[level] === "function") {
-      try { log[level](message, fields); }
-      catch (_e) { /* logger best-effort */ }
-      return;
-    }
-    // Fallback: framework console with status-aware severity
-    var line = "[blamejs:errors-page] " + message + " " + JSON.stringify(fields || {});
-    if (level === "error" || level === "fatal" || level === "warn") {
-      console.error(line);
-    } else {
-      console.log(line);
-    }
-  }
+  var _log = logModule.makeViaOrFallback(log, bootLog);
 
   function handler(err, req, res) {
     var info = _classify(err);

package/lib/external-db-migrate.js

@@ -51,6 +51,8 @@
 var path = require("path");
 var atomicFile = require("./atomic-file");
 var lazyRequire = require("./lazy-require");
+var migrationFiles = require("./migration-files");
+var numericBounds = require("./numeric-bounds");
 var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
 
@@ -67,9 +69,18 @@ var LOCK_TABLE     = "_blamejs_externaldb_migrations_lock";
 var Q_TRACKING = '"' + TRACKING_TABLE + '"';
 var Q_LOCK     = '"' + LOCK_TABLE + '"';
 
-// Filename grammar — mirrors lib/migrations.js so operators with a
-// mixed local + externalDb workflow use the same numeric-prefix pattern.
-var FILE_RE = /^(\d+)-([A-Za-z0-9_-]+)\.js$/;
+// Filename grammar lives in lib/migration-files (shared with the local
+// migrations.js + seeders.js runners). Length capped before the regex
+// test so a hostile directory listing can't drive the engine against
+// an unbounded filename string.
+var FILE_NAME_MAX = 255;
+
+function _isMigrationFile(name) {
+  return typeof name === "string" &&
+         name.length > 0 &&
+         name.length <= FILE_NAME_MAX &&
+         migrationFiles.MIGRATION_FILE_RE.test(name);
+}
 
 function _err(code, message) {
   return new ExternalDbMigrateError(code, message);
@@ -113,8 +124,15 @@ async function _acquireLock(xdb, opts) {
   await _ensureLockTable(xdb);
   var holder = _lockHolderId();
   var nowMs = Date.now();
-  var staleAfterMs = (opts && typeof opts.staleAfterMs === "number" && opts.staleAfterMs > 0)
-                       ? opts.staleAfterMs : 0;
+  // See migrations.acquireLock for the same fix — Infinity was
+  // silently identical to 0 (no staleness check) but obscured the typo.
+  var staleAfterMs = 0;
+  if (opts) {
+    numericBounds.requireNonNegativeFiniteIntIfPresent(opts.staleAfterMs,
+      "externalDb.migrate.acquireLock: staleAfterMs",
+      ExternalDbMigrateError, "externalDb-migrate/bad-opt");
+    if (opts.staleAfterMs !== undefined) staleAfterMs = opts.staleAfterMs;
+  }
   try {
     await xdb.query(
       "INSERT INTO " + Q_LOCK + " (scope, lockedAt, lockedBy) VALUES ('lock', $1, $2)",
@@ -175,7 +193,7 @@ async function _releaseLock(xdb, holder) {
 
 function _list(dir) {
   return atomicFile.listDir(dir, {
-    filter: function (f) { return FILE_RE.test(f); },
+    filter: _isMigrationFile,
   }).map(function (e) { return e.name; }).sort();
 }
 
@@ -236,20 +254,9 @@ function _resolveBackendName(opts) {
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, ["dir", "backend", "audit", "staleAfterMs"], "b.externalDb.migrate");
-  if (typeof opts.dir !== "string" || opts.dir.length === 0) {
-    throw _err("externaldb-migrate/no-dir",
-      "externalDb.migrate.create requires opts.dir (path to migrations directory)");
-  }
-  if (opts.staleAfterMs !== undefined &&
-      (typeof opts.staleAfterMs !== "number" || !isFinite(opts.staleAfterMs) || opts.staleAfterMs < 0)) {
-    throw _err("externaldb-migrate/bad-stale",
-      "staleAfterMs must be a non-negative finite number");
-  }
-  if (opts.audit !== undefined && opts.audit !== null &&
-      (typeof opts.audit !== "object" || typeof opts.audit.safeEmit !== "function")) {
-    throw _err("externaldb-migrate/bad-audit",
-      "audit must be a b.audit-shaped object (safeEmit fn)");
-  }
+  validateOpts.requireNonEmptyString(opts.dir, "externalDb.migrate.create: opts.dir (path to migrations directory)", ExternalDbMigrateError, "externaldb-migrate/no-dir");
+  validateOpts.optionalFiniteNonNegative(opts.staleAfterMs, "externalDb.migrate: staleAfterMs", ExternalDbMigrateError, "externaldb-migrate/bad-stale");
+  validateOpts.auditShape(opts.audit, "externalDb.migrate", ExternalDbMigrateError, "externaldb-migrate/bad-audit");
   var dir = opts.dir;
   var audit = opts.audit || null;
 

package/lib/external-db.js

@@ -53,11 +53,15 @@
 var retryHelper = require("./retry");
 var C = require("./constants");
 var dbRoleContext = require("./db-role-context");
+var externalDbMigrate = require("./external-db-migrate");
 var lazyRequire = require("./lazy-require");
+var { boot } = require("./log");
 var safeAsync = require("./safe-async");
 var safeSql = require("./safe-sql");
 var { ExternalDbError } = require("./framework-error");
 
+var log = boot("external-db");
+
 var audit         = lazyRequire(function () { return require("./audit"); });
 var db            = lazyRequire(function () { return require("./db"); });
 var observability = lazyRequire(function () { return require("./observability"); });
@@ -771,10 +775,14 @@ var write = {
 
 function _resetForTest() {
   Object.keys(backends).forEach(function (n) {
-    try { backends[n].pool.drain(); } catch (_e) {}
+    try { backends[n].pool.drain(); }
+    catch (e) { log.debug("test-reset pool drain failed", { backend: n, error: e.message }); }
     var bk = backends[n];
     if (bk && bk.replicas) {
-      bk.replicas.forEach(function (r) { try { r.pool.drain(); } catch (_e) {} });
+      bk.replicas.forEach(function (r) {
+        try { r.pool.drain(); }
+        catch (e2) { log.debug("test-reset replica drain failed", { backend: n, error: e2.message }); }
+      });
     }
   });
   backends = {};
@@ -1047,7 +1055,7 @@ module.exports = {
   // Migration runner targeting an externalDb backend. Mirrors b.migrations
   // (which targets local SQLite) but runs against externalDb. Tracking +
   // lock tables live on the externalDb side. See lib/external-db-migrate.js.
-  migrate:        require("./external-db-migrate"),
+  migrate:        externalDbMigrate,
   Pool:           Pool,
   _resetForTest:  _resetForTest,
 };

package/lib/file-type.js

@@ -42,11 +42,17 @@
  *     extensions are operator-controlled metadata, magic bytes are
  *     the wire truth.
  */
+var C = require("./constants");
 var { defineClass } = require("./framework-error");
 
 var FileTypeError = defineClass("FileTypeError", { alwaysPermanent: true });
 var _err = FileTypeError.factory;
 
+// Cap on bytes inspected for OOXML / WEBP shape-check probes. Set well
+// above any legitimate Office central-directory prefix and any RIFF
+// header — operators don't tune this, the magic-byte registry is fixed.
+var SNIFF_HEAD_BYTES = C.BYTES.kib(4);
+
 // Signature registry. Each entry: { name, mime, extension, category,
 // offset, magic: Buffer | [Buffer, ...], extra?: function(buffer)→bool }.
 // Order matters — earlier entries win on ambiguous matches (e.g. ZIP
@@ -62,21 +68,21 @@ var SIGNATURES = [
     extension: "docx", category: "document",
     offset: 0, magic: Buffer.from([0x50, 0x4B, 0x03, 0x04]),
     extra: function (buf) {
-      var head = buf.subarray(0, Math.min(buf.length, 4096)).toString("binary");
+      var head = buf.subarray(0, Math.min(buf.length, SNIFF_HEAD_BYTES)).toString("binary");
       return head.indexOf("word/") !== -1 || head.indexOf("[Content_Types].xml") !== -1 && head.indexOf("word") !== -1;
     } },
   { name: "xlsx", mime: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
     extension: "xlsx", category: "document",
     offset: 0, magic: Buffer.from([0x50, 0x4B, 0x03, 0x04]),
     extra: function (buf) {
-      var head = buf.subarray(0, Math.min(buf.length, 4096)).toString("binary");
+      var head = buf.subarray(0, Math.min(buf.length, SNIFF_HEAD_BYTES)).toString("binary");
       return head.indexOf("xl/") !== -1;
     } },
   { name: "pptx", mime: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
     extension: "pptx", category: "document",
     offset: 0, magic: Buffer.from([0x50, 0x4B, 0x03, 0x04]),
     extra: function (buf) {
-      var head = buf.subarray(0, Math.min(buf.length, 4096)).toString("binary");
+      var head = buf.subarray(0, Math.min(buf.length, SNIFF_HEAD_BYTES)).toString("binary");
       return head.indexOf("ppt/") !== -1;
     } },
   // ---- Plain ZIP (after OOXML so OOXML wins) ----
@@ -97,7 +103,9 @@ var SIGNATURES = [
   { name: "webp", mime: "image/webp", extension: "webp", category: "image",
     offset: 0, magic: Buffer.from("RIFF", "ascii"),
     extra: function (buf) {
-      return buf.length >= 12 && buf.subarray(8, 12).toString("ascii") === "WEBP";
+      // RIFF header: "RIFF" (0..3), file size (4..7), format tag at offset 8..11.
+      return buf.length >= C.BYTES.bytes(12) &&
+             buf.subarray(C.BYTES.bytes(0x08), C.BYTES.bytes(12)).toString("ascii") === "WEBP";
     } },
   { name: "bmp",  mime: "image/bmp",  extension: "bmp", category: "image",
     offset: 0, magic: Buffer.from([0x42, 0x4D]) },
@@ -168,10 +176,10 @@ var SIGNATURES = [
     offset: 0, magic: Buffer.from([0x7F, 0x45, 0x4C, 0x46]) },
   { name: "macho",  mime: "application/x-mach-binary", extension: "macho", category: "executable",
     offset: 0, magic: [
-      Buffer.from([0xFE, 0xED, 0xFA, 0xCE]),     // 32-bit BE
-      Buffer.from([0xFE, 0xED, 0xFA, 0xCF]),     // 64-bit BE
-      Buffer.from([0xCE, 0xFA, 0xED, 0xFE]),     // 32-bit LE
-      Buffer.from([0xCF, 0xFA, 0xED, 0xFE]),     // 64-bit LE
+      Buffer.from([0xFE, 0xED, 0xFA, 0xCE]),     // big-endian, narrow word
+      Buffer.from([0xFE, 0xED, 0xFA, 0xCF]),     // big-endian, wide word
+      Buffer.from([0xCE, 0xFA, 0xED, 0xFE]),     // little-endian, narrow word
+      Buffer.from([0xCF, 0xFA, 0xED, 0xFE]),     // little-endian, wide word
       Buffer.from([0xCA, 0xFE, 0xBA, 0xBE]),     // universal binary (also Java .class)
     ] },
 ];

package/lib/forms.js

@@ -35,7 +35,8 @@
  *   forms.escapeAttribute(value)       → string (double-quoted-attr context)
  *   forms.escapeHtml = template.escapeHtml (re-export for convenience)
  */
-var crypto = require("./crypto");
+var C = require("./constants");
+var { generateToken, timingSafeEqual } = require("./crypto");
 var safeSchema = require("./safe-schema");
 var safeUrl = require("./safe-url");
 var template = require("./template");
@@ -44,16 +45,24 @@ var template = require("./template");
 // CSRF token primitives
 // ============================================================
 
-var CSRF_TOKEN_BYTES = 32;
+var CSRF_TOKEN_BYTES = C.BYTES.bytes(32);
+
+// RFC 5321 §4.5.3.1.3 caps an email address at 254 chars; bound the
+// regex test on form submissions so a hostile caller can't stage a
+// pathological-length input against the engine.
+var MAX_EMAIL_LENGTH = 254;
+// RFC 7230 §3.1.1 doesn't fix a URL length but the conventional cap
+// (and what most servers / proxies enforce) is 8 KiB.
+var MAX_URL_LENGTH   = C.BYTES.kib(8);
 
 function generateCsrfToken() {
-  return crypto.generateToken(CSRF_TOKEN_BYTES);
+  return generateToken(CSRF_TOKEN_BYTES);
 }
 
 function verifyCsrfToken(submitted, expected) {
   if (typeof submitted !== "string" || typeof expected !== "string") return false;
   if (submitted.length === 0 || submitted.length !== expected.length) return false;
-  return crypto.timingSafeEqual(submitted, expected);
+  return timingSafeEqual(submitted, expected);
 }
 
 // ============================================================
@@ -129,7 +138,18 @@ function _renderInput(field) {
   if (field.disabled)     attrs.push("disabled");
   if (field.checked)      attrs.push("checked");
   if (field.autocomplete) attrs.push('autocomplete="' + escapeAttribute(field.autocomplete) + '"');
-  if (field.pattern)      attrs.push('pattern="' + escapeAttribute(field.pattern) + '"');
+  if (field.pattern) {
+    // Pattern is a RegExp at every boundary; render its source for the
+    // HTML attribute so client + server agree on the regex. String
+    // patterns are rejected at config time because validate() refuses
+    // them — symmetric handling avoids a silent server-validation gap.
+    if (!(field.pattern instanceof RegExp)) {
+      throw new Error("forms.render: field '" + field.name +
+        "'.pattern must be a pre-compiled RegExp; got " +
+        (typeof field.pattern) + ". Wrap the source string with `RegExp` at config time.");
+    }
+    attrs.push('pattern="' + escapeAttribute(field.pattern.source) + '"');
+  }
   if (field.min !== undefined)        attrs.push('min="' + escapeAttribute(field.min) + '"');
   if (field.max !== undefined)        attrs.push('max="' + escapeAttribute(field.max) + '"');
   if (field.step !== undefined)       attrs.push('step="' + escapeAttribute(field.step) + '"');
@@ -317,18 +337,27 @@ function validate(spec, body) {
       }
     }
     if (f.type === "email" && typeof coerced === "string") {
+      // Length cap before the regex test (RFC 5321 §4.5.3.1.3 = 254
+      // chars). Any longer is rejected without engaging the regex.
       // Same pragmatic check the rest of the framework uses
       // (safeSchema.EMAIL_RE — shared so we don't carry parallel
       // copies of the same /^[^\s@]+@[^\s@]+\.[^\s@]+$/ regex).
-      if (!safeSchema.EMAIL_RE.test(coerced)) {
+      if (coerced.length > MAX_EMAIL_LENGTH || !safeSchema.EMAIL_RE.test(coerced)) {
         errors[f.name] = (f.label || f.name) + " must be a valid email address";
         continue;
       }
     }
     if (f.type === "url" && typeof coerced === "string") {
       // Form `url` fields come from the request body — operator/external
-      // input. Route through safeUrl so the scheme allowlist is honored
-      // (https-only by default; operator opts in to http via field meta).
+      // input. Length cap (RFC 7230 §3.1.1 has no fixed limit; the
+      // conventional cap is 8 KiB) bounds the work before safeUrl.parse
+      // engages. Route through safeUrl so the scheme allowlist is
+      // honored (https-only by default; operator opts in to http via
+      // field meta).
+      if (coerced.length > MAX_URL_LENGTH) {
+        errors[f.name] = (f.label || f.name) + " must be a valid URL";
+        continue;
+      }
       try {
         safeUrl.parse(coerced, {
           allowedProtocols: f.allowHttp ? safeUrl.ALLOW_HTTP_ALL : safeUrl.ALLOW_HTTP_TLS,
@@ -348,10 +377,17 @@ function validate(spec, body) {
         continue;
       }
       if (f.pattern) {
-        var re;
-        try { re = new RegExp("^(?:" + f.pattern + ")$"); }
-        catch (_e) { /* invalid pattern in spec — operator bug; skip */ continue; }
-        if (!re.test(coerced)) {
+        // Pattern accepts a pre-compiled RegExp only — taking a string
+        // and compiling it here would be a ReDoS surface against the
+        // form-render engine. Operators construct the RegExp at config
+        // time so the framework never compiles operator-supplied source
+        // on the request path.
+        if (!(f.pattern instanceof RegExp)) {
+          throw new Error("forms.validate: field '" + f.name +
+            "'.pattern must be a pre-compiled RegExp; got " +
+            (typeof f.pattern) + ". Wrap the source string with `RegExp` at config time.");
+        }
+        if (!f.pattern.test(coerced)) {
           errors[f.name] = f.errorMessages && f.errorMessages.pattern
             ? f.errorMessages.pattern
             : (f.label || f.name) + " has an invalid format";

package/lib/framework-error.js

@@ -99,8 +99,7 @@ function defineClass(name, opts) {
       // call here even during framework-error's own load: observability's
       // dependencies on metrics + tracing are themselves lazy-required
       // and only resolve at first call (post-load).
-      try { observability.event("error.construct", 1, { class: name }); }
-      catch (_e) { /* defensive — no observability sink should ever break a constructor */ }
+      observability.safeEvent("error.construct", 1, { class: name });
     }
   };
   Object.defineProperty(GeneratedError, "name", { value: name, configurable: true });

package/lib/{internal-sha1-hibp.js → framework-sha1-hibp.js}

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * internal-sha1-hibp — SHA-1 hex digest, RESTRICTED to the
+ * framework-sha1-hibp — SHA-1 hex digest, RESTRICTED to the
  * HaveIBeenPwned k-anonymity API caller (lib/auth/password.js policy).
  *
  * SHA-1 is broken for collision-resistance and trivially extendable;

package/lib/handlers.js

@@ -91,7 +91,7 @@ var { boot } = require("./log");
 var DEFAULTS = {
   maxBatch:           100,
   maxAgeMs:           C.TIME.seconds(1),
-  maxBufferSize:      10000,
+  maxBufferSize:      C.BYTES.bytes(10000),
   shutdownTimeoutMs:  C.TIME.seconds(30),
   retry: {
     maxAttempts:    3,

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

@@ -63,7 +63,11 @@
 var fs = require("node:fs");
 var path = require("node:path");
 var C = require("./constants");
+var numericBounds = require("./numeric-bounds");
+var safeAsync = require("./safe-async");
+var safeJson = require("./safe-json");
 var safeUrl = require("./safe-url");
+var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
 
 var CookieJarError = defineClass("CookieJarError", { alwaysPermanent: true });
@@ -162,10 +166,7 @@ function create(opts) {
   }
   var filePath = null;
   if (persist === "file") {
-    if (typeof opts.file !== "string" || opts.file.length === 0) {
-      throw _err("BAD_OPT",
-        "cookieJar.create: persist: 'file' requires opts.file (absolute path)");
-    }
+    validateOpts.requireNonEmptyString(opts.file, "cookieJar.create: persist: 'file' opts.file (absolute path)", CookieJarError, "BAD_OPT");
     filePath = opts.file;
     // Refuse relative paths so a process running in a different cwd
     // doesn't accidentally serialize to a sibling directory.
@@ -174,8 +175,11 @@ function create(opts) {
         "cookieJar.create: opts.file must be an absolute path, got " + JSON.stringify(filePath));
     }
   }
-  var flushDebounceMs = (typeof opts.flushDebounceMs === "number" && opts.flushDebounceMs >= 0)
-    ? opts.flushDebounceMs : DEFAULTS.flushDebounceMs;
+  if (opts.flushDebounceMs !== undefined && !numericBounds.isNonNegativeFiniteInt(opts.flushDebounceMs)) {
+    throw _err("BAD_OPT", "cookieJar.create: flushDebounceMs must be a non-negative finite integer; got " +
+      numericBounds.shape(opts.flushDebounceMs));
+  }
+  var flushDebounceMs = opts.flushDebounceMs !== undefined ? opts.flushDebounceMs : DEFAULTS.flushDebounceMs;
   var clock = typeof opts.clock === "function" ? opts.clock : Date.now;
 
   // Storage map keyed by `<domain>|<path>|<name>` so a (domain, path)
@@ -194,7 +198,8 @@ function create(opts) {
 
   function _setOne(reqUrl, parsed) {
     var u;
-    try { u = new URL(reqUrl); } catch (_e) { return; }
+    try { u = safeUrl.parse(reqUrl, { allowedProtocols: safeUrl.ALLOW_HTTP_ALL }); }
+    catch (_e) { return; }
     var host = u.hostname.toLowerCase();
     var attrs = parsed.attrs || {};
 
@@ -274,7 +279,8 @@ function create(opts) {
 
   function cookieHeaderFor(reqUrl) {
     var u;
-    try { u = new URL(reqUrl); } catch (_e) { return null; }
+    try { u = safeUrl.parse(reqUrl, { allowedProtocols: safeUrl.ALLOW_HTTP_ALL }); }
+    catch (_e) { return null; }
     var host = u.hostname.toLowerCase();
     var path = u.pathname || "/";
     var isSecure = u.protocol === "https:";
@@ -419,7 +425,6 @@ function create(opts) {
   // is also passed, the file is sealed via vault.seal so the on-disk
   // bytes are encrypted at rest; otherwise plaintext (operator chose
   // the threat model by passing or omitting vault).
-  var flushTimer = null;
   function _flushSync() {
     if (!filePath) return;
     var rows = getAll();
@@ -427,21 +432,20 @@ function create(opts) {
     var blob = vault ? vault.seal(serialized) : serialized;
     fs.writeFileSync(filePath, blob);
   }
+  var flushScheduler = safeAsync.makeScheduledFlush(flushDebounceMs, function () {
+    if (!filePath) return;
+    try { _flushSync(); } catch (_e) { /* operator can call flush() to retry */ }
+  });
   function _scheduleFlush() {
     if (!filePath) return;
-    if (flushTimer) return;
-    flushTimer = setTimeout(function () {
-      flushTimer = null;
-      try { _flushSync(); } catch (_e) { /* operator can call flush() to retry */ }
-    }, flushDebounceMs);
-    if (flushTimer.unref) flushTimer.unref();
+    flushScheduler.schedule();
   }
   function flush() {
-    if (flushTimer) { clearTimeout(flushTimer); flushTimer = null; }
+    flushScheduler.cancel();
     _flushSync();
   }
   function close() {
-    if (flushTimer) { clearTimeout(flushTimer); flushTimer = null; }
+    flushScheduler.cancel();
     if (filePath) try { _flushSync(); } catch (_e) { /* best-effort */ }
   }
 
@@ -459,12 +463,15 @@ function create(opts) {
   };
 
   // Initial load from file. Missing file is fine (first run).
+  // Persist file may be operator-tampered (or vault-sealed) — route through
+  // safeJson with an explicit byte cap so a maliciously-large file can't
+  // OOM the process before the parse fails.
   if (filePath && fs.existsSync(filePath)) {
     try {
       var raw = fs.readFileSync(filePath, "utf8");
       var serialized = vault ? vault.unseal(raw) : raw;
       if (serialized && serialized.length > 0) {
-        var rows = JSON.parse(serialized);
+        var rows = safeJson.parse(serialized, { maxBytes: C.BYTES.mib(16) });
         setFromSerialized(rows);
       }
     } catch (e) {