@blamejs/core 0.4.27 → 0.4.29

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- **0.4.28** (2026-04-30) — primitive-drift sweep: inline-require hoisting + safeAsync.sleep + time-math
+- **0.4.27** (2026-04-30) — primitive-drift sweep: regex + escape consolidation, IPv6 completion
 - **0.4.26** (2026-04-30) — primitive-drift sweep: middleware audit context + safeUrl
 - **0.4.25** (2026-04-30) — b.objectStore.bucketOps: bucket-level operations (SigV4)
 - **0.4.24** (2026-04-30) — b.objectStore: multipart upload + server-side encryption

package/lib/api-key.js

@@ -13,7 +13,7 @@
  *     ownerId:   "user-42",
  *     scopes:    ["read:users", "write:posts"],
  *     metadata:  { name: "Mobile app v3" },
- *     expiresAt: Date.now() + 90 * 86400 * 1000,
+ *     expiresAt: Date.now() + b.constants.TIME.days(90),
  *   });
  *   // issued.key  — "bk_live_<idHex>_<secretHex>"  (returned ONCE)
  *   // issued.id   — "<idHex>"
@@ -277,16 +277,10 @@ function create(opts) {
   // The audit chain treats null fields as "unknown", so partial
   // context is always safe.
   function _actor(callerOpts, userId) {
-    var override = {};
-    if (userId) override.userId = userId;
-    if (callerOpts && callerOpts.context && typeof callerOpts.context === "object") {
-      for (var k in callerOpts.context) {
-        if (Object.prototype.hasOwnProperty.call(callerOpts.context, k)) {
-          override[k] = callerOpts.context[k];
-        }
-      }
-    }
-    return requestHelpers.extractActorContext(callerOpts && callerOpts.req, override);
+    return requestHelpers.resolveActorWithOverride(
+      callerOpts,
+      userId ? { userId: userId } : null
+    );
   }
 
   function _selectAll() {

package/lib/audit-tools.js

@@ -57,9 +57,17 @@ var atomicFile = require("./atomic-file");
 var auditChain = require("./audit-chain");
 var auditSign = require("./audit-sign");
 var backupCrypto = require("./backup/crypto");
+var clusterStorage = require("./cluster-storage");
+var lazyRequire = require("./lazy-require");
 var jsonSafe = require("./safe-json");
 var { defineClass } = require("./framework-error");
 
+// Lazy `db` — db requires audit at top-of-file, audit transitively
+// reaches into audit-tools via the operator-supplied default fns,
+// so importing db at audit-tools' top would close the cycle. Lazy
+// keeps the load order one-way.
+var db = lazyRequire(function () { return require("./db"); });
+
 var AuditToolsError = defineClass("AuditToolsError", { alwaysPermanent: true });
 
 var BUNDLE_FORMAT  = "blamejs-audit-bundle-v1";
@@ -197,7 +205,6 @@ function _verifyChainSlice(rows, startPrevHash) {
 // cluster-storage reader so the tooling works in both single-node and
 // cluster deployments without the caller knowing which mode is active.
 async function _defaultReadRows(criteria) {
-  var clusterStorage = require("./cluster-storage");
   var sql = 'SELECT * FROM "audit_log"';
   var conds = [];
   var params = [];
@@ -213,7 +220,6 @@ async function _defaultReadRows(criteria) {
 }
 
 async function _defaultReadCoveringCheckpoint(lastCounter) {
-  var clusterStorage = require("./cluster-storage");
   return clusterStorage.executeOne(
     "SELECT * FROM audit_checkpoints " +
     "WHERE atMonotonicCounter >= ? " +
@@ -224,7 +230,6 @@ async function _defaultReadCoveringCheckpoint(lastCounter) {
 
 async function _defaultReadPredecessorRowHash(firstCounter) {
   if (firstCounter <= 1) return auditChain.ZERO_HASH;
-  var clusterStorage = require("./cluster-storage");
   var row = await clusterStorage.executeOne(
     "SELECT rowHash FROM audit_log WHERE monotonicCounter = ?",
     [firstCounter - 1]
@@ -640,16 +645,13 @@ async function purge(opts) {
 }
 
 async function _defaultReadPurgeAnchor() {
-  var clusterStorage = require("./cluster-storage");
   return clusterStorage.executeOne(
     "SELECT * FROM _blamejs_audit_purge_anchor WHERE scope = 'audit'"
   );
 }
 
 async function _defaultApplyPurge(args) {
-  var db = require("./db");
-  var clusterStorage = require("./cluster-storage");
-  var del = await db.purgeAuditChain({ lastPurgedCounter: args.lastPurgedCounter });
+  var del = await db().purgeAuditChain({ lastPurgedCounter: args.lastPurgedCounter });
   // UPSERT the single-row anchor. SQLite + Postgres both support
   // INSERT ... ON CONFLICT(scope) DO UPDATE.
   await clusterStorage.execute(

package/lib/auth/oauth.js

@@ -106,11 +106,18 @@
 
 var nodeCrypto = require("node:crypto");
 var cache = require("../cache");
+var safeJson = require("../safe-json");
 var safeUrl = require("../safe-url");
 var C = require("../constants");
 var { defineClass } = require("../framework-error");
 var { boot } = require("../log");
 
+// Cap on responses parsed from upstream OAuth providers. Token /
+// userinfo / discovery responses are tiny in spec; 256 KiB leaves
+// huge headroom and prevents a hostile (or compromised) upstream
+// from staging a parse-bomb against the framework.
+var OAUTH_MAX_RESPONSE_BYTES = C.BYTES.kib(256);
+
 var OAuthError = defineClass("OAuthError", { alwaysPermanent: true });
 var log = boot("auth.oauth");
 
@@ -360,7 +367,7 @@ function create(opts) {
         url + " returned " + res.statusCode + ": " + bodyText.slice(0, 500));
     }
     if (!res.body) return null;
-    try { return JSON.parse(res.body.toString("utf8")); }
+    try { return safeJson.parse(res.body.toString("utf8"), { maxBytes: OAUTH_MAX_RESPONSE_BYTES }); }
     catch (e) {
       throw new OAuthError("auth-oauth/bad-json",
         url + " response not JSON: " + ((e && e.message) || String(e)));
@@ -547,7 +554,7 @@ function create(opts) {
         endpoint + " returned " + res.statusCode + ": " + text.slice(0, 500));
     }
     var parsed;
-    try { parsed = JSON.parse(text); }
+    try { parsed = safeJson.parse(text, { maxBytes: OAUTH_MAX_RESPONSE_BYTES }); }
     catch (e) {
       throw new OAuthError("auth-oauth/bad-token-json",
         "token endpoint response not JSON: " + ((e && e.message) || String(e)));
@@ -604,8 +611,8 @@ function create(opts) {
     }
     var header, payload;
     try {
-      header  = JSON.parse(_b64urlDecode(parts[0]).toString("utf8"));
-      payload = JSON.parse(_b64urlDecode(parts[1]).toString("utf8"));
+      header  = safeJson.parse(_b64urlDecode(parts[0]).toString("utf8"), { maxBytes: OAUTH_MAX_RESPONSE_BYTES });
+      payload = safeJson.parse(_b64urlDecode(parts[1]).toString("utf8"), { maxBytes: OAUTH_MAX_RESPONSE_BYTES });
     } catch (e) {
       throw new OAuthError("auth-oauth/malformed-jwt",
         "ID token header/payload base64 decode failed: " + ((e && e.message) || String(e)));

package/lib/backup/manifest.js

@@ -69,6 +69,7 @@
  */
 
 var C = require("../constants");
+var safeJson = require("../safe-json");
 var { FrameworkError } = require("../framework-error");
 
 class BackupManifestError extends FrameworkError {
@@ -250,7 +251,9 @@ function parse(jsonStr) {
   }
   var s = Buffer.isBuffer(jsonStr) ? jsonStr.toString("utf8") : jsonStr;
   var obj;
-  try { obj = JSON.parse(s); }
+  // Backup manifests are file-bounded operator-supplied input. 16 MiB
+  // is generous; real manifests are kilobytes.
+  try { obj = safeJson.parse(s, { maxBytes: C.BYTES.mib(16) }); }
   catch (e) {
     throw new BackupManifestError("backup-manifest/bad-json",
       "parse: not valid JSON: " + ((e && e.message) || String(e)));

package/lib/cache.js

@@ -683,15 +683,7 @@ function create(opts) {
   }
 
   function _actor(callerOpts) {
-    var override = {};
-    if (callerOpts && callerOpts.context && typeof callerOpts.context === "object") {
-      for (var k in callerOpts.context) {
-        if (Object.prototype.hasOwnProperty.call(callerOpts.context, k)) {
-          override[k] = callerOpts.context[k];
-        }
-      }
-    }
-    return requestHelpers.extractActorContext(callerOpts && callerOpts.req, override);
+    return requestHelpers.resolveActorWithOverride(callerOpts);
   }
 
   function _backendFailedAudit(op, err) {

package/lib/cli.js

@@ -34,6 +34,9 @@
  * before encryption or temporarily switch the file to plaintext.
  */
 
+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");
@@ -898,11 +901,7 @@ async function _runBackup(args, ctx) {
   }
 
   if (sub === "verify") {
-    var fs2 = require("node:fs");
-    var os2 = require("node:os");
-    var nodePath = require("node:path");
-    var nodeCrypto = require("node:crypto");
-    var stagingDir = nodePath.join(os2.tmpdir(),
+    var stagingDir = path.join(os.tmpdir(),
       "blamejs-backup-verify-" + nodeCrypto.randomBytes(8).toString("hex"));
     try {
       var r = await restoreBundle.extract({
@@ -917,7 +916,7 @@ async function _runBackup(args, ctx) {
     } catch (e) {
       return report.error((e && e.message) || String(e));
     } finally {
-      try { fs2.rmSync(stagingDir, { recursive: true, force: true }); } catch (_e) { /* best-effort */ }
+      try { fs.rmSync(stagingDir, { recursive: true, force: true }); } catch (_e) { /* best-effort */ }
     }
   }
 
@@ -1118,7 +1117,7 @@ async function _runMtls(args, ctx) {
           validityDays: daysP,
         });
         if (outPath) {
-          require("node:fs").writeFileSync(outPath, p12.p12, { mode: 0o600 });
+          fs.writeFileSync(outPath, p12.p12, { mode: 0o600 });
           report.write("p12 written: " + outPath);
         } else {
           // No --out: stream the bytes to stdout for piping. Operators

package/lib/db-query.js

@@ -26,6 +26,7 @@
  *     a derived hash throws (every encryption uses a fresh nonce — the lookup
  *     would always return zero rows; failing loudly is safer).
  */
+var { Readable } = require("node:stream");
 var cryptoField = require("./crypto-field");
 var { generateToken } = require("./crypto");
 
@@ -194,7 +195,6 @@ class Query {
     var stmt = this._db.prepare(sql);
     var table = this._table;
     var iter;
-    var Readable = require("node:stream").Readable;
     try { iter = stmt.iterate.apply(stmt, this._whereParams); }
     catch (e) {
       var r = new Readable({ objectMode: true, read: function () {} });

package/lib/db.js

@@ -42,6 +42,7 @@
 var fs = require("fs");
 var path = require("path");
 var { DatabaseSync } = require("node:sqlite");
+var { Readable } = require("node:stream");
 var atomicFile = require("./atomic-file");
 var audit = require("./audit");
 var auditSign = require("./audit-sign");
@@ -796,7 +797,6 @@ function stream(sql) {
   var table = opts && typeof opts.table === "string" ? opts.table : null;
   var unseal = table ? cryptoField : null;
 
-  var Readable = require("node:stream").Readable;
   var stmt;
   var iter;
   try {

package/lib/http-client.js

@@ -64,6 +64,8 @@
 var http  = require("http");
 var https = require("https");
 var http2 = require("http2");
+var nodeCrypto = require("node:crypto");
+var nodeStream = require("node:stream");
 var { URL } = require("url");
 var C = require("./constants");
 var pqcAgent = require("./pqc-agent");
@@ -321,7 +323,6 @@ function _attachJarCookie(headers, jar, url) {
 // parser accepts so round-trip from one blamejs app's outbound to
 // another's inbound is exact.
 function _buildMultipartBody(spec) {
-  var nodeCrypto = require("node:crypto");
   var boundary = "----blamejs-mp-" + nodeCrypto.randomBytes(16).toString("hex");
   var CRLF = "\r\n";
   var parts = [];
@@ -701,7 +702,7 @@ function _requestH1(transport, u, opts) {
           // The framework's contract is to hand back the response stream
           // unmodified; fix-up via a passthrough keeps that contract while
           // observing the chunk sizes.
-          var passthrough = new (require("node:stream").PassThrough)();
+          var passthrough = new nodeStream.PassThrough();
           res.on("data", function (chunk) { _emitDownload(chunk.length); passthrough.write(chunk); });
           res.on("end",  function () { passthrough.end(); });
           res.on("error", function (e) { passthrough.destroy(e); });

package/lib/mail.js

@@ -62,15 +62,22 @@
  * resend-*. Vendor-specific presets carry their own code prefix so
  * diagnostic logs identify the provider that rejected the message.
  */
+var C = require("./constants");
 var lazyRequire = require("./lazy-require");
+var nodeCrypto = require("node:crypto");
 var audit = lazyRequire(function () { return require("./audit"); });
 var httpClient = lazyRequire(function () { return require("./http-client"); });
 var net = lazyRequire(function () { return require("net"); });
 var tls = lazyRequire(function () { return require("tls"); });
+var safeJson = require("./safe-json");
 var safeSchema = require("./safe-schema");
 var validateOpts = require("./validate-opts");
 var { FrameworkError } = require("./framework-error");
 
+// Cap on responses parsed from upstream mail providers (Resend, etc.).
+// Vendor responses are tiny in spec; 256 KiB is generous headroom.
+var MAIL_RESPONSE_MAX_BYTES = C.BYTES.kib(256);
+
 class MailError extends FrameworkError {
   constructor(code, message, permanent, statusCode) {
     super(message, code);
@@ -286,7 +293,11 @@ function memoryTransport() {
 // to send AUTH or DATA in cleartext if the upgrade is rejected.
 
 function _newBoundary(label) {
-  return "blamejs-" + label + "-" + Date.now() + "-" + Math.floor(Math.random() * 1e9);
+  // crypto.randomBytes for the boundary suffix matches the framework
+  // convention. RFC 5322 only requires uniqueness within a message,
+  // but consistency with how every other identifier in lib/ is built
+  // wins over premature differentiation.
+  return "blamejs-" + label + "-" + Date.now() + "-" + nodeCrypto.randomBytes(8).toString("hex");
 }
 
 // base64-encode the buffer with line wrapping at 76 chars (RFC 2045
@@ -773,7 +784,7 @@ function resendTransport(opts) {
     interpret: function (res) {
       var text = res.body ? res.body.toString("utf8") : "";
       var data;
-      try { data = JSON.parse(text); }
+      try { data = safeJson.parse(text, { maxBytes: MAIL_RESPONSE_MAX_BYTES }); }
       catch (_e) {
         throw new MailError("mail/resend-bad-response",
           "resend response was not JSON: " + text.slice(0, 200), false);

package/lib/middleware/api-encrypt.js

@@ -100,6 +100,8 @@ var crypto = require("../crypto");
 var C = require("../constants");
 var lazyRequire = require("../lazy-require");
 var nonceStoreLib = require("../nonce-store");
+var requestHelpers = require("../request-helpers");
+var safeJson = require("../safe-json");
 var validateOpts = require("../validate-opts");
 var { defineClass } = require("../framework-error");
 
@@ -172,10 +174,19 @@ function create(opts) {
   validateOpts(opts, [
     "keypair", "keypairs", "replayWindowMs", "pruneIntervalMs",
     "nonceStore", "exemptPaths", "contentTypes", "audit",
+    "maxDecryptedBytes",
   ], "middleware.apiEncrypt");
   var keypairs       = _resolveKeypairs(opts);
   var activeKeypair  = keypairs[0];
   var replayWindowMs = opts.replayWindowMs || DEFAULT_REPLAY_WINDOW_MS;
+  // Cap on decrypted-payload size handed to safeJson.parse. Defaults
+  // to 4 MiB (bodyParser's default 1 MiB plus headroom for crypto +
+  // base64 round-trip). Operators with chunkier inbound payloads
+  // raise this; the framework refuses to parse anything larger as a
+  // parse-bomb defense.
+  var maxDecryptedBytes = opts.maxDecryptedBytes != null
+    ? opts.maxDecryptedBytes
+    : C.BYTES.mib(4);
   // The spec calls for a sweep cadence of replayWindowMs/2 — short
   // enough that expired nonces don't pile up but not so frequent the
   // sweep query becomes a hot path. Operators can override.
@@ -230,7 +241,7 @@ function create(opts) {
     };
     if (auditOn) {
       audit().safeEmit({
-        actor:    { ip: info.ip },
+        actor:    requestHelpers.extractActorContext(req),
         action:   "system.api_encrypt.failure",
         outcome:  "denied",
         reason:   reason,
@@ -348,7 +359,7 @@ function create(opts) {
     try {
       var ctBuf = Buffer.from(ct, "base64");
       var ptBuf = crypto.decryptPacked(ctBuf, sessionKey);
-      clearObj = JSON.parse(ptBuf.toString("utf8"));
+      clearObj = safeJson.parse(ptBuf.toString("utf8"), { maxBytes: maxDecryptedBytes });
     } catch (_e) {
       _emitFailure(req, "tag");
       return _writeRejection(res, 400, { error: "encrypted-payload-rejected" });
@@ -403,7 +414,7 @@ function create(opts) {
 
 function client(opts) {
   opts = opts || {};
-  validateOpts(opts, ["pubkey"], "middleware.apiEncrypt.client");
+  validateOpts(opts, ["pubkey", "maxDecryptedBytes"], "middleware.apiEncrypt.client");
   if (!opts.pubkey || typeof opts.pubkey !== "object") {
     throw _err("CLIENT_INVALID_PUBKEY",
       "apiEncrypt.client: opts.pubkey is required ({ publicKey, ecPublicKey })", 500);
@@ -414,6 +425,9 @@ function client(opts) {
       "apiEncrypt.client: pubkey.publicKey + ecPublicKey must be PEM strings", 500);
   }
   var pubkey = opts.pubkey;
+  var maxDecryptedBytes = opts.maxDecryptedBytes != null
+    ? opts.maxDecryptedBytes
+    : C.BYTES.mib(4);
 
   function encryptRequest(payload) {
     if (payload === undefined) payload = null;
@@ -441,7 +455,7 @@ function client(opts) {
         }
         var resCtBuf = Buffer.from(responseBody._ct, "base64");
         var resPtBuf = crypto.decryptPacked(resCtBuf, sessionKey);
-        return JSON.parse(resPtBuf.toString("utf8"));
+        return safeJson.parse(resPtBuf.toString("utf8"), { maxBytes: maxDecryptedBytes });
       },
     };
   }
@@ -474,13 +488,16 @@ function client(opts) {
 function httpClientEncrypted(opts) {
   opts = opts || {};
   validateOpts(opts, [
-    "pubkey", "baseUrl", "headers", "method",
+    "pubkey", "baseUrl", "headers", "method", "maxDecryptedBytes",
   ], "middleware.apiEncrypt.httpClient");
   if (!opts.pubkey) {
     throw _err("CLIENT_INVALID_PUBKEY",
       "httpClient.encrypted: opts.pubkey is required (the callee's bootstrap doc)", 500);
   }
-  var clientCtx     = client({ pubkey: opts.pubkey });
+  var maxDecryptedBytes = opts.maxDecryptedBytes != null
+    ? opts.maxDecryptedBytes
+    : C.BYTES.mib(4);
+  var clientCtx     = client({ pubkey: opts.pubkey, maxDecryptedBytes: maxDecryptedBytes });
   var baseUrl       = opts.baseUrl ? String(opts.baseUrl).replace(/\/$/, "") : "";
   var defaultHdrs   = opts.headers || {};
   var defaultMethod = opts.method  || "POST";
@@ -531,7 +548,7 @@ function httpClientEncrypted(opts) {
       return { statusCode: resp.statusCode, headers: resp.headers, body: null };
     }
     var parsed;
-    try { parsed = JSON.parse(resp.body.toString("utf8")); }
+    try { parsed = safeJson.parse(resp.body.toString("utf8"), { maxBytes: maxDecryptedBytes }); }
     catch (e) {
       throw _err("CLIENT_RESPONSE_NOT_JSON",
         "httpClient.encrypted: response body is not valid JSON: " + e.message);

package/lib/middleware/attach-user.js

@@ -43,6 +43,7 @@
  */
 var lazyRequire = require("../lazy-require");
 var cookies = require("../cookies");
+var requestHelpers = require("../request-helpers");
 var validateOpts = require("../validate-opts");
 var session = lazyRequire(function () { return require("../session"); });
 var audit   = lazyRequire(function () { return require("../audit"); });
@@ -120,7 +121,7 @@ function create(opts) {
           audit().emit({
             action:   "auth.session.user_loader_threw",
             outcome:  "failure",
-            actor:    { userId: verified.userId, ip: req.socket && req.socket.remoteAddress },
+            actor:    requestHelpers.extractActorContext(req, { userId: verified.userId }),
             reason:   (e && e.message) || String(e),
           });
         } catch (_ignored) { /* audit best-effort */ }
@@ -135,7 +136,7 @@ function create(opts) {
           audit().emit({
             action:   "auth.session.user_unloadable",
             outcome:  "failure",
-            actor:    { userId: verified.userId, ip: req.socket && req.socket.remoteAddress },
+            actor:    requestHelpers.extractActorContext(req, { userId: verified.userId }),
           });
         } catch (_ignored) { /* audit best-effort */ }
       }

package/lib/middleware/body-parser.js

@@ -26,23 +26,23 @@
  *
  *   var bp = b.middleware.bodyParser({
  *     json: {
- *       limit:        1024 * 1024,
+ *       limit:        b.constants.BYTES.mib(1),
  *       strict:       true,                  // require the body to start with {/[
  *       parseHook:    function (parsed) { ... return validatedShape; },
  *     },
  *     urlencoded: {
- *       limit:        1024 * 1024,
+ *       limit:        b.constants.BYTES.mib(1),
  *       arrayLimit:   100,                   // for ?tag=a&tag=b → tag: ["a","b"]
  *     },
- *     text:        { limit: 1024 * 1024, charset: "utf-8" },
- *     raw:         { limit: 10 * 1024 * 1024, contentTypes: ["application/octet-stream"] },
+ *     text:        { limit: b.constants.BYTES.mib(1), charset: "utf-8" },
+ *     raw:         { limit: b.constants.BYTES.mib(10), contentTypes: ["application/octet-stream"] },
  *     multipart: {
  *       tmpDir:       os.tmpdir(),
- *       fileSize:     10 * 1024 * 1024,
- *       totalSize:    50 * 1024 * 1024,
+ *       fileSize:     b.constants.BYTES.mib(10),
+ *       totalSize:    b.constants.BYTES.mib(50),
  *       fileCount:    20,
  *       fieldCount:   100,
- *       fieldSize:    1024 * 1024,
+ *       fieldSize:    b.constants.BYTES.mib(1),
  *       mimeAllowlist: ["image/jpeg", "image/png", "application/pdf"], // null = any
  *
  *       // Per-part predicate. Runs after sanitization + MIME checks but
@@ -64,8 +64,8 @@
  *       // global mimeAllowlist for the named field; other fields still
  *       // use the global list.
  *       fields: {
- *         avatar:   { maxBytes: 2 * 1024 * 1024, mimeTypes: ["image/jpeg", "image/png"] },
- *         document: { maxBytes: 25 * 1024 * 1024 },
+ *         avatar:   { maxBytes: b.constants.BYTES.mib(2),  mimeTypes: ["image/jpeg", "image/png"] },
+ *         document: { maxBytes: b.constants.BYTES.mib(25) },
  *       },
  *
  *       // When wired, fileFilter rejections emit body-parser.multipart.file_rejected

package/lib/middleware/cors.js

@@ -44,10 +44,20 @@
  */
 var lazyRequire = require("../lazy-require");
 var audit = lazyRequire(function () { return require("../audit"); });
+var requestHelpers = require("../request-helpers");
 var safeUrl = require("../safe-url");
 var validateOpts = require("../validate-opts");
 var { defineClass } = require("../framework-error");
 
+// CORS audit events trust the proxy header for actor.ip — same
+// semantics as bot-guard (the apparent origin is what matters when
+// blocking cross-origin attempts behind a CDN).
+function _xffIp(req) {
+  var xff = req.headers && req.headers["x-forwarded-for"];
+  if (xff) return String(xff).split(",")[0].trim();
+  return (req.socket && req.socket.remoteAddress) || null;
+}
+
 var CorsError = defineClass("CorsError", { alwaysPermanent: true });
 
 function _matchOrigin(origin, allowList) {
@@ -188,7 +198,7 @@ function create(opts) {
       if (refuseUnknown) {
         try {
           audit().emit({
-            actor:    { ip: (req.headers && req.headers["x-forwarded-for"]) || (req.socket && req.socket.remoteAddress) },
+            actor:    requestHelpers.extractActorContext(req, { ip: _xffIp(req) }),
             action:   "system.cors.block",
             outcome:  "denied",
             reason:   "origin not in allow-list",

package/lib/notify.js

@@ -370,15 +370,7 @@ function create(opts) {
   }
 
   function _actor(callerOpts) {
-    var override = {};
-    if (callerOpts && callerOpts.context && typeof callerOpts.context === "object") {
-      for (var k in callerOpts.context) {
-        if (Object.prototype.hasOwnProperty.call(callerOpts.context, k)) {
-          override[k] = callerOpts.context[k];
-        }
-      }
-    }
-    return requestHelpers.extractActorContext(callerOpts && callerOpts.req, override);
+    return requestHelpers.resolveActorWithOverride(callerOpts);
   }
 
   function _redactedMetadata(channel, message, extra) {

package/lib/object-store/gcs.js

@@ -175,7 +175,7 @@ function create(config) {
     if (!tokenResp.access_token) {
       throw _err("AUTH_FAILED", "GCS token endpoint returned no access_token: " + res.body.toString("utf8"), true);
     }
-    var expiresInMs = (tokenResp.expires_in || 3600) * 1000;
+    var expiresInMs = C.TIME.seconds(tokenResp.expires_in || 3600);
     cachedToken = {
       accessToken: tokenResp.access_token,
       expiresAt:   Date.now() + expiresInMs,

package/lib/queue-local.js

@@ -33,8 +33,9 @@ var cluster = require("./cluster");
 var clusterStorage = require("./cluster-storage");
 var { generateToken } = require("./crypto");
 var cryptoField = require("./crypto-field");
-var safeJson = require("./safe-json");
 var lazyRequire = require("./lazy-require");
+var safeJson = require("./safe-json");
+var scheduler = require("./scheduler");
 var { QueueError } = require("./framework-error");
 
 var _err = QueueError.factory;
@@ -241,7 +242,6 @@ function create(_config) {
     if (row && row.repeatCron) {
       try {
         var unsealedRow = cryptoField.unsealRow("_blamejs_jobs", row);
-        var scheduler = require("./scheduler");
         var cron = scheduler.parseCron(unsealedRow.repeatCron);
         var nextMs = scheduler.nextCronFire(cron, new Date(nowMs), unsealedRow.repeatTimezone || null);
         await enqueue(unsealedRow.queueName,

package/lib/queue.js

@@ -31,12 +31,13 @@
  *                                       failed (status='failed')
  */
 var C = require("./constants");
-var localProto = require("./queue-local");
-var retryHelper = require("./retry");
-var safeAsync = require("./safe-async");
 var lazyRequire = require("./lazy-require");
+var nodeCrypto = require("node:crypto");
 var observability = require("./observability");
 var protocolDispatcher = require("./protocol-dispatcher");
+var localProto = require("./queue-local");
+var retryHelper = require("./retry");
+var safeAsync = require("./safe-async");
 var { QueueError } = require("./framework-error");
 
 var dispatcher = protocolDispatcher.create({
@@ -565,7 +566,6 @@ function enqueueFlow(spec) {
     return Promise.reject(e);
   }
 
-  var nodeCrypto = require("node:crypto");
   var flowId = "flow-" + nodeCrypto.randomBytes(8).toString("hex");
 
   return observability.tap("queue.enqueueFlow",

package/lib/request-helpers.js

@@ -87,6 +87,31 @@ function extractActorContext(req, override) {
   return ctx;
 }
 
+// Convenience wrapper for primitives that accept an optional
+// `{ req, context }` shape and want to thread it into an audit-emit
+// `actor` field. Replaces the four near-identical `_actor()` helpers
+// that lived in api-key, cache, seeders, and notify before v0.4.29.
+//
+//   callerOpts:    operator-supplied `{ req?, context? }` (e.g. the
+//                  primitive's call-site opts bag)
+//   baseOverride:  optional seed values applied BEFORE callerOpts.context
+//                  so `context` wins. api-key seeds `{ userId }` here so
+//                  the resolved key's owner becomes the default actor
+//                  unless the operator passes their own context.userId.
+//
+// Returns the same shape as extractActorContext.
+function resolveActorWithOverride(callerOpts, baseOverride) {
+  var override = baseOverride ? Object.assign({}, baseOverride) : {};
+  if (callerOpts && callerOpts.context && typeof callerOpts.context === "object") {
+    for (var k in callerOpts.context) {
+      if (Object.prototype.hasOwnProperty.call(callerOpts.context, k)) {
+        override[k] = callerOpts.context[k];
+      }
+    }
+  }
+  return extractActorContext(callerOpts && callerOpts.req, override);
+}
+
 function resolveRoute(req) {
   if (req && typeof req.routePattern === "string" && req.routePattern.length > 0) {
     return req.routePattern;
@@ -171,8 +196,9 @@ function parseQualityList(headerValue, opts) {
 }
 
 module.exports = {
-  resolveRoute:          resolveRoute,
-  captureResponseStatus: captureResponseStatus,
-  extractActorContext:   extractActorContext,
-  parseQualityList:      parseQualityList,
+  resolveRoute:              resolveRoute,
+  captureResponseStatus:     captureResponseStatus,
+  extractActorContext:       extractActorContext,
+  resolveActorWithOverride:  resolveActorWithOverride,
+  parseQualityList:          parseQualityList,
 };

package/lib/restore-rollback.js

@@ -56,6 +56,8 @@
 var fs = require("fs");
 var path = require("path");
 var atomicFile = require("./atomic-file");
+var C = require("./constants");
+var safeJson = require("./safe-json");
 var { defineClass } = require("./framework-error");
 
 var RestoreRollbackError = defineClass("RestoreRollbackError", { alwaysPermanent: true });
@@ -199,7 +201,7 @@ function list(opts) {
     var markerPath = p + ".marker.json";
     var marker = null;
     if (fs.existsSync(markerPath)) {
-      try { marker = JSON.parse(fs.readFileSync(markerPath, "utf8")); }
+      try { marker = safeJson.parse(fs.readFileSync(markerPath, "utf8"), { maxBytes: C.BYTES.kib(64) }); }
       catch (_e) { marker = null; }
     }
     var stat;

package/lib/router.js

@@ -25,6 +25,7 @@ var fs = require("fs");
 var path = require("path");
 var { URL } = require("url");
 var C = require("./constants");
+var safeAsync = require("./safe-async");
 var websocket = require("./websocket");
 var { boot } = require("./log");
 
@@ -217,12 +218,13 @@ class Router {
       });
     });
 
-    var allClosed = Promise.all(closes);
-    var timeout = new Promise(function (resolve) {
-      var t = setTimeout(resolve, timeoutMs);
-      t.unref();
-    });
-    await Promise.race([allClosed, timeout]);
+    // Wait up to `timeoutMs` for graceful WS closes, then force-destroy
+    // any laggards. `safeAsync.sleep({ unref: true })` matches the
+    // framework's outbound-timeout convention.
+    await Promise.race([
+      Promise.all(closes),
+      safeAsync.sleep(timeoutMs, { unref: true }),
+    ]);
     // Force-destroy any laggards — at this point we've waited the full
     // timeout and they didn't ack. The operator chose timeoutMs; honor it.
     this._activeWsConns.forEach(function (conn) {

package/lib/seeders.js

@@ -404,15 +404,7 @@ function create(opts) {
   }
 
   function _actor(callerOpts) {
-    var override = {};
-    if (callerOpts && callerOpts.context && typeof callerOpts.context === "object") {
-      for (var k in callerOpts.context) {
-        if (Object.prototype.hasOwnProperty.call(callerOpts.context, k)) {
-          override[k] = callerOpts.context[k];
-        }
-      }
-    }
-    return requestHelpers.extractActorContext(callerOpts && callerOpts.req, override);
+    return requestHelpers.resolveActorWithOverride(callerOpts);
   }
 
   function _appliedRows(db, env) {

package/lib/session.js

@@ -35,12 +35,13 @@
  *   verify / count
  *     — anywhere (any node can read shared session state)
  */
-var { generateToken, sha3Hash } = require("./crypto");
-var safeJson = require("./safe-json");
-var cryptoField = require("./crypto-field");
-var clusterStorage = require("./cluster-storage");
+var audit = require("./audit");
 var cluster = require("./cluster");
+var clusterStorage = require("./cluster-storage");
 var C = require("./constants");
+var { generateToken, sha3Hash } = require("./crypto");
+var cryptoField = require("./crypto-field");
+var safeJson = require("./safe-json");
 var { SessionError } = require("./framework-error");
 
 var _err = SessionError.factory;
@@ -260,13 +261,12 @@ async function rotate(oldToken, opts) {
   // privilege transition so post-incident review can trace which
   // session id covered which privilege state.
   try {
-    var audit = require("./audit");
     audit.emit({
       action:  "auth.session.rotate",
       outcome: "success",
       metadata: { reason: opts.reason || "explicit" },
     });
-  } catch (_e) { /* boot-order tolerance */ }
+  } catch (_e) { /* audit emit best-effort — never block rotate() */ }
 
   return { token: newSid, expiresAt: expiresAt };
 }

package/lib/vault/rotate.js

@@ -56,6 +56,7 @@ var C = require("../constants");
 var cryptoField = require("../crypto-field");
 var cryptoLib = require("../crypto");
 var lazyRequire = require("../lazy-require");
+var safeJson = require("../safe-json");
 var vaultWrap = lazyRequire(function () { return require("./wrap"); });
 var { defineClass } = require("../framework-error");
 
@@ -479,7 +480,10 @@ function _rotateOverflow(db, table, oldKeys, newKeys, batchSize, progress, warni
       for (var i = 0; i < rows.length; i++) {
         var row = rows[i];
         var doc;
-        try { doc = JSON.parse(row.data); }
+        // Vault overflow rows are framework-written but read at rotate
+        // time — gate the parse via safeJson so a corrupted row can't
+        // stage a parse-bomb against the rotation worker.
+        try { doc = safeJson.parse(row.data, { maxBytes: C.BYTES.mib(16) }); }
         catch (_e) {
           warnings.push("malformed overflow JSON at " + table + "._id=" + row._id + " — left unrotated");
           continue;

package/package.json

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