@blamejs/core 0.6.7 → 0.6.12

package/lib/middleware/csrf-protect.js

@@ -34,7 +34,7 @@
  *      (e.g. req.session.data.csrfToken). Issuance + req.csrfToken
  *      exposure are the operator's responsibility in this mode.
  *
- * If neither is supplied, the middleware throws at create() — Tier A
+ * If neither is supplied, the middleware throws at create() —
  * config-time validation, no silent passthrough.
  *
  * Submitted-token sources tried in order on state-changing requests:
@@ -177,7 +177,7 @@ function create(opts) {
     ? opts.trustProxy : false;
   var _isHttps = _isHttpsFor(trustProxy);
 
-  // Tier A — exactly one issuance source.
+  // Throw at create() — exactly one issuance source allowed.
   var hasCookie = opts.cookie != null && opts.cookie !== false;
   var hasLookup = typeof opts.tokenLookup === "function";
   if (hasCookie && hasLookup) {

package/lib/middleware/rate-limit.js

@@ -256,8 +256,8 @@ function create(opts) {
   var bodyOnLimit = opts.bodyOnLimit !== undefined ? opts.bodyOnLimit : "Too Many Requests";
   var emitHeaders = opts.header !== false;
   var skipPaths = opts.skipPaths || [];
-  // Tier-A: each entry must be a string prefix or a RegExp. Anything
-  // else would crash _shouldSkip with TypeError on the first request.
+  // Throw at create(): each entry must be a string prefix or a RegExp.
+  // Anything else would crash _shouldSkip with TypeError on the first request.
   for (var sp = 0; sp < skipPaths.length; sp++) {
     if (typeof skipPaths[sp] !== "string" && !(skipPaths[sp] instanceof RegExp)) {
       throw new Error("middleware.rateLimit: skipPaths[" + sp +

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/notify.js

@@ -74,7 +74,7 @@ var DEFAULTS = Object.freeze({
   // we get the framework's policy without forking the constants.
 });
 
-// ---- Tier-A validation ----
+// ---- Call-site validation (throw on bad input) ----
 
 function _isFiniteNonNegative(n) {
   return typeof n === "number" && isFinite(n) && n >= 0;
@@ -360,7 +360,7 @@ function create(opts) {
 
   function _emitObs(name, labels) {
     try { observability().event(name, 1, labels || {}); }
-    catch (_e) { /* Tier B */ }
+    catch (_e) { /* drop-silent — observability sink must not crash send() */ }
   }
 
   function _emitAudit(action, info) {

package/lib/object-store/sigv4-bucket-ops.js

@@ -44,13 +44,14 @@
  *     maxAgeSeconds:  3600,
  *   }]);
  *
- * Validation is Tier-A: every input shape is rejected at the call
- * site rather than producing a server-side 400. Errors surface as
- * ObjectStoreError with codes (BUCKET_INVALID_NAME, INVALID_LIFECYCLE,
- * INVALID_CORS_RULE, BUCKET_ALREADY_OWNED, BUCKET_NOT_EMPTY, etc.).
+ * Validation rejects every bad input shape at the call site rather
+ * than producing a server-side 400. Errors surface as ObjectStoreError
+ * with codes (BUCKET_INVALID_NAME, INVALID_LIFECYCLE, INVALID_CORS_RULE,
+ * BUCKET_ALREADY_OWNED, BUCKET_NOT_EMPTY, etc.).
  */
 var { URL } = require("url");
 var nodeCrypto = require("crypto");
+var C = require("../constants");
 var sigv4 = require("./sigv4");
 var safeXml = require("../parsers/safe-xml");
 var safeUrl = require("../safe-url");
@@ -261,7 +262,7 @@ function _buildCorsXml(rules) {
     body += "</CORSRule>";
   }
   body += "</CORSConfiguration>";
-  if (Buffer.byteLength(body, "utf8") > 64 * 1024) {
+  if (Buffer.byteLength(body, "utf8") > C.BYTES.kib(64)) {
     throw _err("INVALID_CORS_RULE",
       "CORS configuration exceeds 64 KB (S3 spec)", true);
   }

package/lib/object-store/sigv4.js

@@ -214,17 +214,17 @@ function _request(method, url, headers, body, opts) {
 // CompleteMultipartUpload with EntityTooSmall. The framework refuses
 // configurations below this floor at create() time so operators don't
 // see surprising failures only on large uploads.
-var MIN_PART_SIZE_BYTES = 5 * 1024 * 1024;
+var MIN_PART_SIZE_BYTES = C.BYTES.mib(5);
 // S3 spec ceiling on part count. CompleteMultipartUpload rejects
 // uploads with more than 10000 parts.
 var MAX_PARTS = 10000;
 // Auto-multipart trigger: buffered bodies under this stay single-PUT.
 // Streams always go multipart since size isn't known up-front.
-var DEFAULT_MULTIPART_THRESHOLD_BYTES = 64 * 1024 * 1024;
+var DEFAULT_MULTIPART_THRESHOLD_BYTES = C.BYTES.mib(64);
 // Conservative default part size — large enough to keep round-trip
 // overhead small relative to payload, small enough to fit comfortably
 // in a 4-way-concurrent upload's memory footprint.
-var DEFAULT_PART_SIZE_BYTES = 16 * 1024 * 1024;
+var DEFAULT_PART_SIZE_BYTES = C.BYTES.mib(16);
 var DEFAULT_PART_CONCURRENCY = 4;
 
 // ---- SSE option handling ----

package/lib/observability.js

@@ -59,18 +59,43 @@ var lazyRequire = require("./lazy-require");
 var tracing = lazyRequire(function () { return require("./tracing"); });
 var metrics = lazyRequire(function () { return require("./metrics"); });
 
+// Operator-installed tap handler — wired via setTap(). When non-null,
+// every observability event/tap dispatch routes here in addition to
+// the framework's metrics module. Used by b.otelExport.create() so an
+// OTLP/HTTP exporter receives the same hot-path counters the framework
+// emits internally.
+var _externalTap = null;
+
 function _safeMetricsTap(name, value, labels) {
   try { metrics().tap(name, value, labels); }
   catch (_e) { /* boot-order tolerance — metrics may not be loaded */ }
+  if (_externalTap !== null) {
+    try { _externalTap(name, value, labels); }
+    catch (_e) { /* operator-installed handler — drop-silent on its throws */ }
+  }
+}
+
+// setTap — install an external tap handler. Operators wire this from
+// `b.otelExport.create({...}).tapHandler` so every framework counter
+// also lands in the operator's metrics pipeline.
+//
+// The handler signature mirrors metrics.tap: (name, value, labels).
+// Pass null to remove the previously-installed handler.
+function setTap(handler) {
+  if (handler !== null && typeof handler !== "function") {
+    throw new TypeError("observability.setTap: handler must be a function or null, got " +
+      typeof handler);
+  }
+  _externalTap = handler;
 }
 
 function tap(name, attrs, fn) {
   if (typeof attrs === "function") { fn = attrs; attrs = null; }
-  // Tier A validation: tap is called from many call sites and a typo
-  // in the name (e.g. variable holding undefined) silently corrupts both
-  // the span tree AND the metrics counter route, with no obvious symptom
-  // until somebody opens a dashboard. Throw at first call so the
-  // operator catches it.
+  // Throw on bad input: tap is called from many call sites and a typo
+  // in the name (e.g. variable holding undefined) silently corrupts
+  // both the span tree AND the metrics counter route, with no obvious
+  // symptom until somebody opens a dashboard. Throw at first call so
+  // the operator catches it.
   if (typeof name !== "string" || name.length === 0) {
     throw new TypeError("observability.tap: name must be a non-empty string, got " +
       (typeof name) + " " + JSON.stringify(name));
@@ -97,18 +122,19 @@ function tap(name, attrs, fn) {
   });
 }
 
-// Tier B (drop-silent): event is the fire-and-forget shape called from
-// hot paths where throwing would crash the request that triggered it.
-// Bad input is silently dropped — operators with a misnamed event see
-// the missing counter, not a 500. metrics.tap performs its own label-
-// name regex validation; an invalid call surfaces in the metrics module
-// log, not via a thrown exception.
+// Drop-silent on bad input by design: event is the fire-and-forget
+// shape called from hot paths where throwing would crash the request
+// that triggered it. Operators with a misnamed event see the missing
+// counter, not a 500. metrics.tap performs its own label-name regex
+// validation; an invalid call surfaces in the metrics module log, not
+// via a thrown exception.
 function event(name, value, labels) {
   if (typeof name !== "string" || name.length === 0) return;
   _safeMetricsTap(name, value, labels);
 }
 
 module.exports = {
-  tap:   tap,
-  event: event,
+  tap:    tap,
+  event:  event,
+  setTap: setTap,
 };

package/lib/otel-export.js

@@ -27,8 +27,8 @@
  *
  * Wiring with `b.observability`:
  *
- *   // Option A: replace the metrics tap entirely
- *   b.observability._setTap(otel.tapHandler);
+ *   // Option A: install as an external tap on b.observability
+ *   b.observability.setTap(otel.tapHandler);
  *
  *   // Option B: alongside b.metrics — operators write their own
  *   // multi-tap fan-out (or pick one or the other for v1).

package/lib/pagination.js

@@ -215,10 +215,10 @@ async function cursor(query, opts) {
   }
   var limit     = _resolveLimit(opts);
   var orderBy   = typeof opts.orderBy === "string" && opts.orderBy.length > 0 ? opts.orderBy : "_id";
-  // Tier-A on orderBy — the value is interpolated into a raw SQL fragment
-  // for the keyset where-clause. Restrict to identifier-safe characters
-  // so a careless caller piping `req.query.orderBy` through doesn't
-  // create an SQL-injection vector.
+  // Throw at call site on bad orderBy — the value is interpolated into
+  // a raw SQL fragment for the keyset where-clause. Restrict to
+  // identifier-safe characters so a careless caller piping
+  // `req.query.orderBy` through doesn't create an SQL-injection vector.
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(orderBy)) {
     throw new PaginationError("pagination/bad-orderby",
       "cursor: orderBy must match /^[A-Za-z_][A-Za-z0-9_]*$/ (identifier-safe), got " +
@@ -342,8 +342,8 @@ async function offset(query, opts) {
   var page = parseInt(opts.page, 10);
   if (isNaN(page) || page < 1) page = 1;
   var orderBy = typeof opts.orderBy === "string" && opts.orderBy.length > 0 ? opts.orderBy : "_id";
-  // Same Tier-A on offset() as cursor() — orderBy passes through to the
-  // db Query; identifier-safe-only to prevent SQL injection.
+  // Same identifier-only check on offset() as cursor() — orderBy passes
+  // through to the db Query; throw at call site to prevent SQL injection.
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(orderBy)) {
     throw new PaginationError("pagination/bad-orderby",
       "offset: orderBy must match /^[A-Za-z_][A-Za-z0-9_]*$/ (identifier-safe), got " +

package/lib/permissions.js

@@ -31,14 +31,14 @@
  *   "users:*:read"  matches "users:foo:read" (per-segment *)
  *   "users:read"    matches "users:read" only — no implicit sub-resource grant
  *
- * Validation tiers:
+ * Validation policy:
  *
- *   - create() role table / scope formats → Tier A (throw at app init)
- *   - require(scope) registration arg     → Tier A (throw at route declaration)
- *   - check(actor, scope) bad actor       → Tier C (return false)
+ *   - create() role table / scope formats → throw at app init
+ *   - require(scope) registration arg     → throw at route declaration
+ *   - check(actor, scope) bad actor       → return false (tolerant read)
  *   - resolver returns null in middleware → 401 (missingActorStatus)
  *   - actor lacks scope in middleware     → 403 (denyStatus)
- *   - audit/observability emit failures   → Tier B (drop silent)
+ *   - audit/observability emit failures   → drop silent (hot-path sink)
  *
  * Audit defaults follow the framework's security-defaults stance
  * default: `auditFailures: true`
@@ -57,7 +57,7 @@ var observability = lazyRequire(function () { return require("./observability");
 
 function _emitEvent(name, value, labels) {
   try { observability().event(name, value, labels || {}); }
-  catch (_e) { /* Tier B: hot-path observability sink */ }
+  catch (_e) { /* hot-path observability sink — drops silent on internal throws */ }
 }
 
 // Lowercase tokens, digits, dash, underscore, and `*` allowed per
@@ -331,7 +331,7 @@ function create(opts) {
   }
 
   // Middleware factory. `mode` is "single" | "all" | "any"; `requested`
-  // is the scope or scope list. Tier A on registration arg.
+  // is the scope or scope list. Throw at registration time on bad shape.
   function _middleware(mode, requested) {
     if (mode === "single") {
       _validateScopePattern(requested, "permissions.require");

package/lib/protocol-dispatcher.js

@@ -51,8 +51,8 @@ var { defineClass } = require("./framework-error");
 // supply their own get this generic shape with the same code namespace.
 var ProtocolDispatcherError = defineClass("ProtocolDispatcherError", { withStatusCode: true });
 
-// Tier A validation — called at create-time, throw on bad input so
-// operators catch typos at app boot, not first request.
+// Throw at create-time on bad input so operators catch typos at app
+// boot, not first request.
 function _validateConfig(opts) {
   if (!opts || typeof opts !== "object") {
     throw new Error("protocolDispatcher.create: opts is required");

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: [],
     };
   }
@@ -505,7 +509,7 @@ function _resetForTest() {
 //     ],
 //   });
 //
-// Cycle detection runs at registration (Tier-A throw). Each child enters
+// Cycle detection runs at registration (throws at call site). Each child enters
 // the queue with availableAt = MAX_SAFE_INTEGER until parent completion
 // bumps it. Returns { flowId, jobs: [{ name, jobId }, ...] }.
 function enqueueFlow(spec) {

package/lib/request-helpers.js

@@ -175,9 +175,9 @@ function requestProtocol(req, opts) {
 //   parseListHeader(undefined)             → []
 //   parseListHeader("")                    → []
 //
-// Tier-C: tolerant of non-string input (returns []) — these are read
-// from request headers that the network might omit. Callers needing
-// stricter checks layer their own validation on the result.
+// Tolerant read: non-string input returns [] — these are read from
+// request headers that the network might omit. Callers needing stricter
+// checks layer their own validation on the result.
 function parseListHeader(value, opts) {
   if (value == null) return [];
   opts = opts || {};

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/retry.js

@@ -18,14 +18,14 @@
  * compose freely with `safeAsync.withTimeout`, AbortSignals, and any
  * caller-side instrumentation.
  *
- * Validation tiers:
+ * Validation policy:
  *
- *   - withRetry opts at first call            → Tier A (throw)
- *   - CircuitBreaker constructor opts         → Tier A (throw)
- *   - backoffDelay(attempt) attempt argument  → Tier A (throw)
- *   - isRetryable(err) defensive read         → Tier C (return defaults)
- *   - onRetry callback throw                  → Tier B (drop silent)
- *   - breaker internal _onSuccess/_onFailure  → Tier B (drop silent)
+ *   - withRetry opts at first call            → throw at call site
+ *   - CircuitBreaker constructor opts         → throw at call site
+ *   - backoffDelay(attempt) attempt argument  → throw at call site
+ *   - isRetryable(err) defensive read         → tolerant (return defaults)
+ *   - onRetry callback throw                  → drop silent (hot-path sink)
+ *   - breaker internal _onSuccess/_onFailure  → drop silent (hot-path sink)
  *
  * HTTP-client auto-retry is intentionally NOT provided here. Callers
  * wrap their own outbound calls in `b.retry.withRetry(...)` to keep
@@ -40,13 +40,13 @@ var lazyRequire = require("./lazy-require");
 // are fully loaded.
 var safeAsync = lazyRequire(function () { return require("./safe-async"); });
 // observability is also lazy-required because the metrics + tracing
-// registry boots after this file loads. event() is Tier B — any
-// throw inside the metrics sink is swallowed by observability itself.
+// registry boots after this file loads. event() is fire-and-forget —
+// any throw inside the metrics sink is swallowed by observability itself.
 var observability = lazyRequire(function () { return require("./observability"); });
 
 function _emitEvent(name, value, labels) {
   try { observability().event(name, value, labels || {}); }
-  catch (_e) { /* Tier B: hot-path observability sink */ }
+  catch (_e) { /* hot-path observability sink — drops silent on internal throws */ }
 }
 
 // ---- Defaults ----
@@ -80,7 +80,7 @@ var DEFAULT_BREAKER = Object.freeze({
   successThreshold:  2,                   // consecutive HALF probes that close it
 });
 
-// ---- Tier-A validation helpers ----
+// ---- Call-site validation helpers (throw on bad input) ----
 
 function _isPositiveInt(n) {
   return typeof n === "number" && isFinite(n) && n >= 1 && Math.floor(n) === n;
@@ -147,7 +147,7 @@ function _validateBreakerOpts(name, opts) {
 
 // ---- Public surface ----
 
-// Tier C: defensive read of err shape; missing fields → false.
+// Tolerant read of err shape; missing fields → false.
 function isRetryable(err) {
   if (!err) return false;
   if (err.isObjectStoreError && err.permanent) return false;
@@ -162,11 +162,12 @@ function isRetryable(err) {
   return false;                                   // default: not retryable (avoid masking bugs)
 }
 
-// Tier A: attempt must be a positive int; opts (when supplied) must
-// have non-neg-finite baseDelayMs/maxDelayMs and finite jitterFactor in [0,1].
-// We don't full-validate opts here every call (hot path) — defaults are
-// frozen, so the only way a bad opts reaches here is via withRetry which
-// already validated, OR a caller using backoffDelay directly. For that
+// Throw on bad input: attempt must be a positive int; opts (when supplied)
+// must have non-neg-finite baseDelayMs/maxDelayMs and finite jitterFactor
+// in [0,1]. We don't full-validate opts here every call (hot path) —
+// defaults are frozen, so the only way a bad opts reaches here is via
+// withRetry which already validated, OR a caller using backoffDelay
+// directly. For that
 // direct case we still validate the attempt arg loudly.
 function backoffDelay(attempt, opts) {
   if (!_isPositiveInt(attempt)) {
@@ -212,8 +213,8 @@ async function withRetry(fn, opts) {
       var delay = backoffDelay(attempt, opts);
       _emitEvent("retry.attempt", 1, { attempt: attempt });
       if (typeof opts.onRetry === "function") {
-        // Tier B: hot-path observability sink. A thrown observer must
-        // not crash the retry loop — by design.
+        // Hot-path observability sink — drops silent on observer throw
+        // so a thrown observer can't crash the retry loop.
         try { opts.onRetry({ attempt: attempt, delay: delay, error: err }); } catch (_e) {}
       }
       // Honor opts.signal during the backoff sleep — a caller who aborts

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;
 }