@blamejs/core 0.6.11 → 0.6.12

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **0.6.12** (2026-05-02) — `b.safeUrl.parse` now rejects URLs with `user:pass@` userinfo by default (opt in per-call via `allowUserinfo: true`); `b.session.touch({ extendBy })` enforces the same `MAX_TTL_MS` ceiling as `create` / `rotate`; `b.queue.consume({ rateLimit })` rejects negative / zero / `NaN` / `Infinity` / fractional `max`; `b.middleware.requireAuth` no longer treats request `Content-Type: application/json` as a JSON-preference signal (only `Accept` and `X-Requested-With` count); `b.backup.create({ requireFlush: true })` opt-in fails the backup if pre-flush fails instead of producing a stale snapshot; `b.restore.create({ maxPulledBytes, maxPulledFiles })` preflight bounds bundle footprint before and after pull (defaults 4 GiB / 100K files); `b.mail.transports.console({ redactBcc: true })` opt-in prints recipient count instead of addresses; `b.logStream.transports.webhook({ onDrop })` callback fires on overflow + retry-exhausted batch drops. Wiki: admin login wired through `b.auth.lockout` (exponential-backoff after bad-cred attempts) and cookie `Secure` flag now routes through `b.requestHelpers.requestProtocol` with `WIKI_TRUST_PROXY` opt-in instead of trusting raw `x-forwarded-proto`. Wiki README documents the trust model for editable page bodies and the sanitization pattern operators should adopt before expanding the editor surface.
 - **0.6.11** (2026-05-01) — wiki example-execution validator: fixture init no longer reaches across module realms (unblocks the npm-publish workflow's wiki-e2e gate, which `npm install --install-links` copies the framework into the wiki's node_modules — two distinct singletons before this fix)
 - **0.6.10** (2026-05-01) — README / SECURITY / CONTRIBUTING / wiki: removed stale version stamps and an inaccurate vendored-dep list; SECURITY now points at `lib/vendor/MANIFEST.json` for the authoritative vendor list; supported-versions table no longer pins to a specific minor; wiki archive example names the digest variable correctly (was `sha256`, output is SHA3-512 hex)
 - **0.6.9** (2026-05-01) — b.archive.zip().digest() returns a SHA3-512 hex string (was SHA-256); operators reconciling against an external SHA-256 must hash the bytes themselves

package/lib/backup/index.js

@@ -238,6 +238,13 @@ function create(opts) {
   var flushBeforeBackup = typeof opts.flushBeforeBackup === "function"
     ? opts.flushBeforeBackup
     : (opts.flushBeforeBackup === false ? null : null);
+  // requireFlush — when true, a flush failure FAILS the backup instead
+  // of producing a (potentially stale) snapshot. Operators on
+  // encrypted-at-rest with hard freshness requirements (compliance,
+  // audit, point-in-time recovery) opt in. Default false preserves the
+  // long-standing best-effort posture for operators who care about
+  // backup completing more than freshness.
+  var requireFlush = opts.requireFlush === true;
   // Default: try b.db.flushToDisk if available. Wired this way so the
   // backup primitive doesn't take a hard dependency on b.db (operators
   // running backup against an external db handle still work).
@@ -272,15 +279,24 @@ function create(opts) {
     var stagingDir = path.join(os.tmpdir(),
       "blamejs-backup-staging-" + bundleId.replace(/[:.]/g, "-"));
 
-    // Flush the live DB to disk so the snapshot is current. Best-effort —
-    // a flush failure logs but doesn't fail the whole backup; the bundle
-    // will just snapshot whatever's on disk.
+    // Flush the live DB to disk so the snapshot is current. Default
+    // posture is best-effort — a flush failure logs but doesn't fail
+    // the whole backup. With requireFlush:true the failure aborts the
+    // backup so a stale snapshot never lands in storage.
     if (flushBeforeBackup) {
       try { await flushBeforeBackup(); }
       catch (e) {
+        var flushReason = (e && e.message) || String(e);
         _emitAudit("backup.flush.failure",
-          { bundleId: bundleId, reason: (e && e.message) || String(e) },
-          "warning");
+          { bundleId: bundleId, reason: flushReason },
+          requireFlush ? "failure" : "warning");
+        if (requireFlush) {
+          _emitAudit("backup.failure",
+            { bundleId: bundleId, reason: "flush-required-but-failed: " + flushReason },
+            "failure");
+          throw new BackupError("backup/flush-required-failed",
+            "backup flush required but failed: " + flushReason);
+        }
       }
     }
 

package/lib/log-stream-webhook.js

@@ -97,6 +97,19 @@ function create(config) {
     errorClass:       LogStreamError,
   });
   var headers = Object.assign({ "Content-Type": cfg.contentType }, _authHeaders(cfg));
+  // onDrop callback: invoked when a batch is dropped, either by buffer
+  // overflow ("overflow") or by retry exhaustion ("retry-exhausted").
+  // Operator wiring this directly (without the framework's dispatcher
+  // wrapping) needs visibility into permanent-drop events; the
+  // dispatcher path emits its own audit, but a sink used in isolation
+  // would otherwise lose drops silently. The callback is invoked
+  // best-effort — a throw inside it is swallowed.
+  var onDrop = typeof cfg.onDrop === "function" ? cfg.onDrop : null;
+  function _emitDrop(reason, batch, err) {
+    if (!onDrop) return;
+    try { onDrop({ reason: reason, batch: batch, error: err || null }); }
+    catch (_e) { /* drop callback is best-effort by design */ }
+  }
   var buffer = [];
   var dropCount = 0;
   var flushTimer = null;
@@ -121,9 +134,13 @@ function create(config) {
           await retryHelper.withRetry(function () {
             return _post(cfg.url, body, headers, cfg.timeoutMs, cfg.allowedProtocols, cfg.allowInternal);
           }, cfg.retry);
-        } catch {
-          // Batch permanently rejected — surface via the dropped counter.
-          // Caller's audit hook recorded the drop already at the dispatcher.
+        } catch (e) {
+          // Batch permanently rejected — surface via dropCount AND the
+          // operator-supplied onDrop callback. The dispatcher path
+          // wraps its own audit hook around emit(); operators using
+          // this sink directly rely on dropCount + onDrop.
+          dropCount += batch.length;
+          _emitDrop("retry-exhausted", batch, e);
           break;
         }
       }
@@ -136,8 +153,9 @@ function create(config) {
   function emit(record) {
     if (closed) return Promise.resolve({ accepted: false, reason: "sink closed" });
     if (buffer.length >= cfg.bufferLimit) {
-      buffer.shift();   // drop oldest
+      var dropped = buffer.shift();   // drop oldest
       dropCount += 1;
+      _emitDrop("overflow", [dropped], null);
     }
     buffer.push(record);
     if (buffer.length >= cfg.batchSize) {

package/lib/mail.js

@@ -246,6 +246,14 @@ function _toArray(v) {
 function consoleTransport(opts) {
   opts = opts || {};
   var stream = opts.stream || process.stderr;
+  // redactBcc: print only the recipient COUNT instead of the addresses.
+  // Default false preserves the dev-visibility purpose of this
+  // transport. Operators piping dev logs into shared / centralized
+  // sinks (Slack, log aggregator, ticket system) opt in to avoid
+  // leaking the BCC list — the property exists precisely so a recipient
+  // doesn't see who else got the message, and that promise breaks the
+  // moment the addresses land in a non-private log.
+  var redactBcc = opts.redactBcc === true;
   return {
     name: "console",
     send: async function (message) {
@@ -255,7 +263,14 @@ function consoleTransport(opts) {
         "[mail.console] Subject: " + (message.subject || ""),
       ];
       if (message.cc)  lines.push("[mail.console] Cc: " + (Array.isArray(message.cc)  ? message.cc.join(", ")  : message.cc));
-      if (message.bcc) lines.push("[mail.console] Bcc: " + (Array.isArray(message.bcc) ? message.bcc.join(", ") : message.bcc));
+      if (message.bcc) {
+        if (redactBcc) {
+          var bccCount = Array.isArray(message.bcc) ? message.bcc.length : 1;
+          lines.push("[mail.console] Bcc: <" + bccCount + " recipient" + (bccCount === 1 ? "" : "s") + " — redacted>");
+        } else {
+          lines.push("[mail.console] Bcc: " + (Array.isArray(message.bcc) ? message.bcc.join(", ") : message.bcc));
+        }
+      }
       var body = message.text || (message.html ? "(html body, " + message.html.length + " bytes)" : "");
       lines.push("");
       lines.push(body);

package/lib/middleware/require-auth.js

@@ -5,14 +5,21 @@
  * either lets the request through or rejects it.
  *
  * Rejection shape:
- *   - JSON-preferring caller (Accept: application/json, or X-Requested-With:
- *     XMLHttpRequest, or content-type starts application/json):
+ *   - JSON-preferring caller (Accept includes application/json, or
+ *     X-Requested-With: XMLHttpRequest):
  *     401 application/json with { error: "Authentication required." }
  *   - Browser-preferring caller, when opts.redirectTo is set:
  *     302 with Location header
  *   - Otherwise:
  *     401 text/plain
  *
+ * Note: the Content-Type of the REQUEST is intentionally NOT a signal.
+ * A server-to-server POST with `Content-Type: application/json` and no
+ * `Accept` header should get the same response shape as any other
+ * unauthenticated request — Content-Type describes what the client
+ * SENT, not what they want back. Operators with a non-default
+ * preference contract supply opts.prefersJson.
+ *
  * Always emits `auth.required.denied` audit event on rejection (when
  * opts.audit !== false). The event records request method + path +
  * client IP — keys-only, no body content.
@@ -37,8 +44,6 @@ function _defaultPrefersJson(req) {
   var h = req.headers || {};
   if (typeof h.accept === "string" && h.accept.indexOf("application/json") !== -1) return true;
   if (h["x-requested-with"] === "XMLHttpRequest") return true;
-  if (typeof h["content-type"] === "string" &&
-      h["content-type"].indexOf("application/json") === 0) return true;
   return false;
 }
 

package/lib/queue.js

@@ -188,16 +188,20 @@ function consume(queueName, handler, opts) {
   // accounting keeps it cheap (just a sliding deque of timestamps).
   var rateLimit = null;
   if (opts.rateLimit) {
-    if (!opts.rateLimit.max || !opts.rateLimit.perSeconds ||
-        typeof opts.rateLimit.max !== "number" ||
-        typeof opts.rateLimit.perSeconds !== "number") {
+    var rlMax = opts.rateLimit.max;
+    var rlPer = opts.rateLimit.perSeconds;
+    // Strict positive-finite on both: NaN, Infinity, 0, and negatives
+    // all produce undefined throttling math (NaN deque comparisons,
+    // perma-locked queues, perma-open windows). Reject at config time.
+    if (typeof rlMax !== "number" || !isFinite(rlMax) || rlMax <= 0 || Math.floor(rlMax) !== rlMax ||
+        typeof rlPer !== "number" || !isFinite(rlPer) || rlPer <= 0) {
       throw _err("BAD_RATE_LIMIT",
-        "consume({ rateLimit }): expected { max: number, perSeconds: number }, got " +
+        "consume({ rateLimit }): expected { max: positive integer, perSeconds: positive finite number }, got " +
         JSON.stringify(opts.rateLimit), true);
     }
     rateLimit = {
-      max:        opts.rateLimit.max,
-      windowMs:   C.TIME.seconds(opts.rateLimit.perSeconds),
+      max:        rlMax,
+      windowMs:   C.TIME.seconds(rlPer),
       timestamps: [],
     };
   }

package/lib/restore.js

@@ -89,6 +89,7 @@ function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
     "dataDir", "storage", "passphrase", "rollbackRoot", "audit",
+    "maxPulledBytes", "maxPulledFiles",
   ], "restore");
   if (typeof opts.dataDir !== "string" || opts.dataDir.length === 0) {
     throw new RestoreError("restore/no-datadir",
@@ -106,6 +107,47 @@ function create(opts) {
   var rollbackRoot = opts.rollbackRoot || (dataDir + ".rollbacks");
   var auditOn = opts.audit !== false;
 
+  // Preflight footprint caps. Defended against storage that returns a
+  // tampered or oversized bundle: we cap both the storage-reported size
+  // (cheap, before pull) AND the actually-pulled bytes/file-count
+  // (defense-in-depth in case the backend lied). Default 4 GiB / 100K
+  // files keeps the small-bundle path uncapped while bounding the
+  // pathological case.
+  var maxPulledBytes = typeof opts.maxPulledBytes === "number" && isFinite(opts.maxPulledBytes) && opts.maxPulledBytes > 0
+    ? opts.maxPulledBytes : 4 * 1024 * 1024 * 1024;
+  var maxPulledFiles = typeof opts.maxPulledFiles === "number" && isFinite(opts.maxPulledFiles) && opts.maxPulledFiles > 0
+    ? opts.maxPulledFiles : 100000;
+
+  function _walkPullDirFootprint(dir) {
+    var totalBytes = 0, fileCount = 0;
+    var stack = [dir];
+    while (stack.length > 0) {
+      var current = stack.pop();
+      var entries;
+      try { entries = fs.readdirSync(current, { withFileTypes: true }); }
+      catch (_e) { continue; }
+      for (var i = 0; i < entries.length; i++) {
+        var entry = entries[i];
+        var full = path.join(current, entry.name);
+        if (entry.isDirectory()) {
+          stack.push(full);
+        } else if (entry.isFile()) {
+          fileCount++;
+          if (fileCount > maxPulledFiles) {
+            return { tooManyFiles: true, fileCount: fileCount };
+          }
+          try {
+            totalBytes += fs.statSync(full).size;
+            if (totalBytes > maxPulledBytes) {
+              return { tooManyBytes: true, totalBytes: totalBytes };
+            }
+          } catch (_e) { /* file vanished mid-walk */ }
+        }
+      }
+    }
+    return { totalBytes: totalBytes, fileCount: fileCount };
+  }
+
   function _emitAudit(action, info, outcome) {
     if (!auditOn) return;
     audit().safeEmit({
@@ -118,6 +160,32 @@ function create(opts) {
 
   async function list() { return await storage.listBundles(); }
 
+  // Find a bundle in storage.listBundles() output and check its
+  // reported size against maxPulledBytes BEFORE pulling. listBundles()
+  // returns the storage-reported size; cheap to scan and rejects an
+  // oversized object before any bytes hit local disk. Returns the
+  // bundle metadata when within bounds, throws when oversized, returns
+  // null when listBundles doesn't surface the bundle (e.g. listing is
+  // truncated by the backend).
+  async function _preflightBundleSize(bundleId) {
+    var listed;
+    try { listed = await storage.listBundles(); }
+    catch (_e) { return null; }
+    if (!Array.isArray(listed)) return null;
+    for (var i = 0; i < listed.length; i++) {
+      var entry = listed[i];
+      if (entry && entry.bundleId === bundleId) {
+        if (typeof entry.size === "number" && entry.size > maxPulledBytes) {
+          throw new RestoreError("restore/bundle-too-large",
+            "bundle '" + bundleId + "' reports size " + entry.size +
+            " bytes, exceeds maxPulledBytes " + maxPulledBytes);
+        }
+        return entry;
+      }
+    }
+    return null;
+  }
+
   async function inspect(bundleId) {
     if (typeof bundleId !== "string" || bundleId.length === 0) {
       throw new RestoreError("restore/bad-bundle-id", "inspect: bundleId is required");
@@ -127,10 +195,22 @@ function create(opts) {
       throw new RestoreError("restore/bundle-not-found",
         "inspect: bundle '" + bundleId + "' not in storage");
     }
+    await _preflightBundleSize(bundleId);
     var pullDir = path.join(os.tmpdir(),
       "blamejs-restore-inspect-" + crypto.generateToken(4));
     try {
       await storage.readBundle(bundleId, pullDir);
+      var pulled = _walkPullDirFootprint(pullDir);
+      if (pulled.tooManyBytes) {
+        throw new RestoreError("restore/pulled-too-large",
+          "bundle '" + bundleId + "' pulled " + pulled.totalBytes +
+          " bytes (caught mid-pull), exceeds maxPulledBytes " + maxPulledBytes);
+      }
+      if (pulled.tooManyFiles) {
+        throw new RestoreError("restore/pulled-too-many-files",
+          "bundle '" + bundleId + "' pulled " + pulled.fileCount +
+          " files, exceeds maxPulledFiles " + maxPulledFiles);
+      }
       return restoreBundle.inspect({ bundleDir: pullDir });
     } finally {
       try { fs.rmSync(pullDir, { recursive: true, force: true }); } catch (_e) {}
@@ -160,6 +240,17 @@ function create(opts) {
     }
 
     // 1. Pull bundle out of storage
+    // Preflight: reject an oversized bundle BEFORE pulling bytes to
+    // disk. Cheap when the backend lists size; no-op when it doesn't.
+    try {
+      await _preflightBundleSize(bundleId);
+    } catch (e) {
+      _cleanupTmp();
+      _emitAudit("restore.failure",
+        { bundleId: bundleId, reason: (e && e.message) || String(e) },
+        "failure");
+      throw e;
+    }
     try {
       await storage.readBundle(bundleId, pullDir);
     } catch (e) {
@@ -170,6 +261,19 @@ function create(opts) {
       throw new RestoreError("restore/storage-read-failed",
         "pulling bundle from storage failed: " + ((e && e.message) || String(e)));
     }
+    // Defense-in-depth: walk the pulled bundle and re-check footprint.
+    // Catches a backend that under-reported size in listBundles or that
+    // doesn't surface size at all.
+    var pulled = _walkPullDirFootprint(pullDir);
+    if (pulled.tooManyBytes || pulled.tooManyFiles) {
+      _cleanupTmp();
+      var capCode = pulled.tooManyBytes ? "restore/pulled-too-large" : "restore/pulled-too-many-files";
+      var capMsg = pulled.tooManyBytes
+        ? "bundle '" + bundleId + "' pulled " + pulled.totalBytes + " bytes, exceeds maxPulledBytes " + maxPulledBytes
+        : "bundle '" + bundleId + "' pulled " + pulled.fileCount + " files, exceeds maxPulledFiles " + maxPulledFiles;
+      _emitAudit("restore.failure", { bundleId: bundleId, reason: capMsg }, "failure");
+      throw new RestoreError(capCode, capMsg);
+    }
 
     // 2. Decrypt + verify into stagingDir
     var extracted;

package/lib/safe-url.js

@@ -23,6 +23,14 @@
  *                         log-stream, http-client) surface their
  *                         own decorated error class. Default:
  *                         SafeUrlError.
+ *     allowUserinfo     — accept URLs that carry user:pass@ credentials
+ *                         in the authority. Default: false. Userinfo in
+ *                         outbound URLs leaks into request logs, error
+ *                         messages, metric labels, and trace spans;
+ *                         credential placement belongs in headers /
+ *                         cookies / a credential store, not the URL.
+ *                         Operators with a legacy endpoint that
+ *                         REQUIRES userinfo opt in explicitly per call.
  *
  * Constants — pre-baked allowlists for the common caller cases:
  *
@@ -95,6 +103,14 @@ function parse(url, opts) {
       "]. Pass opts.allowedProtocols to override (e.g. safeUrl.ALLOW_HTTP_ALL for cleartext endpoints).");
   }
 
+  if (opts.allowUserinfo !== true && (parsed.username !== "" || parsed.password !== "")) {
+    throw _makeError(errClass, "safe-url/userinfo-disallowed",
+      "URL contains user:pass@ credentials in the authority. These leak into " +
+      "request logs / error messages / metric labels / trace spans. Move the " +
+      "credential to an Authorization header (or a credential store the client " +
+      "reads at call time), or pass opts.allowUserinfo: true to opt this URL in.");
+  }
+
   return parsed;
 }
 

package/lib/session.js

@@ -212,8 +212,11 @@ async function touch(token, opts) {
   // assembly) and matches the call shape clusterStorage expects.
   // extendBy resets expiresAt relative to NOW, not relative to the
   // current expiresAt — a soaked session with continuous traffic
-  // shouldn't accumulate unbounded expiry.
-  if (typeof opts.extendBy === "number" && opts.extendBy > 0) {
+  // shouldn't accumulate unbounded expiry. The same MAX_TTL_MS
+  // ceiling create() and rotate() apply gates extendBy too — repeated
+  // touch() calls cannot push expiresAt past the framework's bound.
+  if (opts.extendBy !== undefined && opts.extendBy !== null) {
+    _validateTtl(opts.extendBy, "session.touch");
     var newExpires = nowMs + opts.extendBy;
     var result = await clusterStorage.execute(
       "UPDATE _blamejs_sessions SET lastActivity = ?, expiresAt = ? " +

package/package.json

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