@blamejs/blamejs-shop 0.4.55 → 0.4.57

package/lib/vendor/blamejs/lib/safe-async.js

@@ -605,6 +605,459 @@ function makeScheduledFlush(delayMs, flushFn) {
   };
 }
 
+/**
+ * @primitive b.safeAsync.makeBufferedEnqueue
+ * @signature b.safeAsync.makeBufferedEnqueue(buffer, opts)
+ * @since     0.15.13
+ * @status    stable
+ * @related   b.safeAsync.makeScheduledFlush, b.safeAsync.makeDropCallback
+ *
+ * Backpressure enqueue for batching egress sinks. Returns an
+ * `enqueue(entry)` function that pushes `entry` onto the operator-owned
+ * `buffer` array with drop-oldest overflow protection, then either kicks
+ * a flush when the batch is full or defers to a coalescing scheduler.
+ * Resolves `{ accepted: true, queued }` with the post-enqueue depth.
+ *
+ * This is the shared hot-path decision every batching log-stream sink
+ * (CloudWatch, OTLP/HTTP, webhook) makes per record: bound the buffer,
+ * surface dropped records to drop accounting, and trigger delivery on a
+ * full batch without awaiting it. Bounding is mandatory — an unbounded
+ * buffer behind a slow or dead collector is an out-of-memory vector.
+ *
+ * `opts.flush` returns the in-flight drain promise (its rejection is
+ * swallowed here — the sink reports failures through its own onDrop).
+ * `opts.schedule` is the coalescing deferral (typically a
+ * `makeScheduledFlush` handle's `schedule`). `opts.onOverflow(dropped)`
+ * is invoked with the evicted record so the caller can increment its
+ * drop counter and emit a drop event. Validates wiring at construction
+ * (`TypeError`) so a sink author's typo surfaces at setup, not under load.
+ *
+ * @opts
+ *   batchSize:   number,    // flush when buffer reaches this depth
+ *   bufferLimit: number,    // drop oldest once buffer exceeds this depth
+ *   flush:       Function,  // () => Promise — non-awaited batch drain
+ *   schedule:    Function,  // () => void  — coalescing deferred flush
+ *   onOverflow:  Function,  // (dropped) => void — drop accounting (optional)
+ *
+ * @example
+ *   var b = require("blamejs");
+ *
+ *   var buffer = [];
+ *   var dropped = 0;
+ *   var sched = b.safeAsync.makeScheduledFlush(20, drain);
+ *   var enqueue = b.safeAsync.makeBufferedEnqueue(buffer, {
+ *     batchSize:   100,
+ *     bufferLimit: 1000,
+ *     flush:       drain,
+ *     schedule:    sched.schedule,
+ *     onOverflow:  function () { dropped += 1; },
+ *   });
+ *   function drain() { buffer.length = 0; return Promise.resolve(); }
+ *
+ *   await enqueue({ message: "hi" });
+ *   // → { accepted: true, queued: 1 }
+ */
+function makeBufferedEnqueue(buffer, opts) {
+  if (!Array.isArray(buffer)) {
+    throw new TypeError("safeAsync.makeBufferedEnqueue: buffer must be an array");
+  }
+  if (!opts || typeof opts !== "object") {
+    throw new TypeError("safeAsync.makeBufferedEnqueue: opts is required");
+  }
+  if (typeof opts.batchSize !== "number" || !isFinite(opts.batchSize) || opts.batchSize < 1) {
+    throw new TypeError("safeAsync.makeBufferedEnqueue: opts.batchSize must be a positive finite number");
+  }
+  if (typeof opts.bufferLimit !== "number" || !isFinite(opts.bufferLimit) || opts.bufferLimit < 1) {
+    throw new TypeError("safeAsync.makeBufferedEnqueue: opts.bufferLimit must be a positive finite number");
+  }
+  if (typeof opts.flush !== "function") {
+    throw new TypeError("safeAsync.makeBufferedEnqueue: opts.flush must be a function");
+  }
+  if (typeof opts.schedule !== "function") {
+    throw new TypeError("safeAsync.makeBufferedEnqueue: opts.schedule must be a function");
+  }
+  if (opts.onOverflow != null && typeof opts.onOverflow !== "function") {
+    throw new TypeError("safeAsync.makeBufferedEnqueue: opts.onOverflow must be a function when provided");
+  }
+  var batchSize   = opts.batchSize;
+  var bufferLimit = opts.bufferLimit;
+  var flush       = opts.flush;
+  var schedule    = opts.schedule;
+  var onOverflow  = opts.onOverflow || null;
+  return function enqueue(entry) {
+    if (buffer.length >= bufferLimit) {
+      var dropped = buffer.shift();
+      if (onOverflow) onOverflow(dropped);
+    }
+    buffer.push(entry);
+    if (buffer.length >= batchSize) {
+      flush().catch(function () {});
+    } else {
+      schedule();
+    }
+    return Promise.resolve({ accepted: true, queued: buffer.length });
+  };
+}
+
+/**
+ * @primitive b.safeAsync.makeDrainingClose
+ * @signature b.safeAsync.makeDrainingClose(opts)
+ * @since     0.15.13
+ * @status    stable
+ * @related   b.safeAsync.makeBufferedEnqueue, b.safeAsync.makeScheduledFlush
+ *
+ * Graceful shutdown for a batching egress sink. Returns an async
+ * `close()` that cancels the coalescing scheduler, awaits any in-flight
+ * drain, runs one final flush, then marks the sink closed — in that
+ * order, because the order is load-bearing.
+ *
+ * The flush loop typically guards on `!closed` to stop pulling from the
+ * buffer; flipping `closed` first would strand the records an operator
+ * queued in the moment before shutdown. Draining before the flip is the
+ * difference between a clean shutdown and silently dropped tail records
+ * (lost logs, lost audit). This primitive encodes that invariant once so
+ * each sink can't reintroduce the reorder.
+ *
+ * `opts.getInflight` is read at close time (not construction) so it
+ * observes whatever drain is running then; its rejection is swallowed —
+ * the sink surfaces flush failures through its own onDrop. `opts.flush`
+ * runs the final drain; `opts.markClosed` flips the sink's closed flag.
+ *
+ * @opts
+ *   scheduler:   Object,    // { cancel() } — the coalescing flush handle
+ *   getInflight: Function,  // () => Promise|null — current in-flight drain
+ *   flush:       Function,  // () => Promise — final drain
+ *   markClosed:  Function,  // () => void — flip the closed flag last
+ *
+ * @example
+ *   var b = require("blamejs");
+ *
+ *   var closed = false, inflight = null, buffer = [];
+ *   var sched = b.safeAsync.makeScheduledFlush(20, drain);
+ *   function drain() { inflight = Promise.resolve(); return inflight; }
+ *   var close = b.safeAsync.makeDrainingClose({
+ *     scheduler:   sched,
+ *     getInflight: function () { return inflight; },
+ *     flush:       drain,
+ *     markClosed:  function () { closed = true; },
+ *   });
+ *
+ *   await close();
+ *   closed;
+ *   // → true
+ */
+function makeDrainingClose(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new TypeError("safeAsync.makeDrainingClose: opts is required");
+  }
+  if (!opts.scheduler || typeof opts.scheduler.cancel !== "function") {
+    throw new TypeError("safeAsync.makeDrainingClose: opts.scheduler must expose cancel()");
+  }
+  if (typeof opts.getInflight !== "function") {
+    throw new TypeError("safeAsync.makeDrainingClose: opts.getInflight must be a function");
+  }
+  if (typeof opts.flush !== "function") {
+    throw new TypeError("safeAsync.makeDrainingClose: opts.flush must be a function");
+  }
+  if (typeof opts.markClosed !== "function") {
+    throw new TypeError("safeAsync.makeDrainingClose: opts.markClosed must be a function");
+  }
+  var scheduler   = opts.scheduler;
+  var getInflight = opts.getInflight;
+  var flush       = opts.flush;
+  var markClosed  = opts.markClosed;
+  return async function close() {
+    scheduler.cancel();
+    var inflight = getInflight();
+    if (inflight) {
+      try { await inflight; } catch (_e) { /* surfaced via the sink's onDrop */ }
+    }
+    await flush();
+    markClosed();
+  };
+}
+
+/**
+ * @primitive b.safeAsync.makeBatchDrain
+ * @signature b.safeAsync.makeBatchDrain(opts)
+ * @since     0.15.13
+ * @status    stable
+ * @related   b.safeAsync.makeBufferedEnqueue, b.safeAsync.makeDrainingClose
+ *
+ * The drain loop behind a batching egress sink. Owns the single-flight
+ * latch and returns `{ flush, getInflight, isInFlight }`. Calling
+ * `flush()` while a drain is in progress returns that same in-flight
+ * promise (one drain at a time); otherwise it pulls batches off the
+ * operator-owned `buffer` and ships each via `opts.sendBatch` until the
+ * buffer empties or the sink closes, rescheduling itself if records
+ * remain.
+ *
+ * `opts.sendBatch(batch)` is the per-sink transport (serialize + send,
+ * typically wrapped in retry); a throw means the batch is permanently
+ * rejected — the loop reports it via `opts.onRetryExhausted(batch, err)`
+ * and stops (the buffer keeps the rest for the next cycle). `opts.isClosed`
+ * is polled each iteration so a shutdown stops the loop promptly.
+ *
+ * Two optional hooks cover sinks that need more than a plain splice:
+ * `opts.takeBatch(buffer)` returns the next batch (default
+ * `buffer.splice(0, batchSize)`) for sinks with a byte-size cap; and
+ * `opts.beforeDrain()` runs once before the loop (e.g. ensure a remote
+ * log stream exists) — if it throws, the whole buffer is drained to
+ * `opts.onBeforeDrainFail(records, err)` as a permanent drop, since every
+ * batch would hit the same failure.
+ *
+ * @opts
+ *   buffer:           Array,    // operator-owned record buffer
+ *   batchSize:        number,   // default splice width
+ *   scheduler:        Object,   // { schedule() } — reschedule when records remain
+ *   isClosed:         Function, // () => boolean — polled each iteration
+ *   sendBatch:        Function, // (batch) => Promise — throw ⇒ permanent reject
+ *   onRetryExhausted: Function, // (batch, err) => void — permanent-reject accounting
+ *   takeBatch:        Function, // (buffer) => batch — optional; default splice(0, batchSize)
+ *   beforeDrain:      Function, // () => Promise — optional pre-loop step
+ *   onBeforeDrainFail: Function,// (records, err) => void — optional; beforeDrain threw
+ *
+ * @example
+ *   var b = require("blamejs");
+ *
+ *   var buffer = [{ n: 1 }, { n: 2 }];
+ *   var sent = [];
+ *   var sched = b.safeAsync.makeScheduledFlush(20, function () {});
+ *   var drain = b.safeAsync.makeBatchDrain({
+ *     buffer:           buffer,
+ *     batchSize:        10,
+ *     scheduler:        sched,
+ *     isClosed:         function () { return false; },
+ *     sendBatch:        function (batch) { sent.push(batch); return Promise.resolve(); },
+ *     onRetryExhausted: function () {},
+ *   });
+ *   await drain.flush();
+ *   sent.length;
+ *   // → 1
+ */
+function makeBatchDrain(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new TypeError("safeAsync.makeBatchDrain: opts is required");
+  }
+  if (!Array.isArray(opts.buffer)) {
+    throw new TypeError("safeAsync.makeBatchDrain: opts.buffer must be an array");
+  }
+  if (typeof opts.batchSize !== "number" || !isFinite(opts.batchSize) || opts.batchSize < 1) {
+    throw new TypeError("safeAsync.makeBatchDrain: opts.batchSize must be a positive finite number");
+  }
+  if (!opts.scheduler || typeof opts.scheduler.schedule !== "function") {
+    throw new TypeError("safeAsync.makeBatchDrain: opts.scheduler must expose schedule()");
+  }
+  if (typeof opts.isClosed !== "function") {
+    throw new TypeError("safeAsync.makeBatchDrain: opts.isClosed must be a function");
+  }
+  if (typeof opts.sendBatch !== "function") {
+    throw new TypeError("safeAsync.makeBatchDrain: opts.sendBatch must be a function");
+  }
+  if (typeof opts.onRetryExhausted !== "function") {
+    throw new TypeError("safeAsync.makeBatchDrain: opts.onRetryExhausted must be a function");
+  }
+  if (opts.takeBatch != null && typeof opts.takeBatch !== "function") {
+    throw new TypeError("safeAsync.makeBatchDrain: opts.takeBatch must be a function when provided");
+  }
+  if (opts.beforeDrain != null && typeof opts.beforeDrain !== "function") {
+    throw new TypeError("safeAsync.makeBatchDrain: opts.beforeDrain must be a function when provided");
+  }
+  if (opts.onBeforeDrainFail != null && typeof opts.onBeforeDrainFail !== "function") {
+    throw new TypeError("safeAsync.makeBatchDrain: opts.onBeforeDrainFail must be a function when provided");
+  }
+  var buffer           = opts.buffer;
+  var batchSize        = opts.batchSize;
+  var scheduler        = opts.scheduler;
+  var isClosed         = opts.isClosed;
+  var sendBatch        = opts.sendBatch;
+  var onRetryExhausted = opts.onRetryExhausted;
+  var takeBatch        = opts.takeBatch || function (buf) { return buf.splice(0, batchSize); };
+  var beforeDrain      = opts.beforeDrain || null;
+  var onBeforeDrainFail = opts.onBeforeDrainFail || null;
+
+  var inFlight = false;
+  var inFlightPromise = null;
+
+  async function flush() {
+    if (inFlight) return inFlightPromise;
+    if (buffer.length === 0) return;
+    inFlight = true;
+    inFlightPromise = (async function () {
+      try {
+        if (beforeDrain) {
+          try { await beforeDrain(); }
+          catch (e) {
+            // The pre-drain step failed permanently — every batch would hit
+            // the same error. Drain the whole buffer to onBeforeDrainFail so
+            // the operator sees exactly which records were lost, then bail.
+            var allBuffered = buffer.splice(0, buffer.length);
+            if (onBeforeDrainFail) onBeforeDrainFail(allBuffered, e);
+            return;
+          }
+        }
+        while (buffer.length > 0 && !isClosed()) {
+          var batch = takeBatch(buffer);
+          if (batch.length === 0) break;
+          try {
+            await sendBatch(batch);
+          } catch (sendErr) {
+            onRetryExhausted(batch, sendErr);
+            break;
+          }
+        }
+      } finally {
+        inFlight = false;
+        inFlightPromise = null;
+        if (buffer.length > 0) scheduler.schedule();
+      }
+    })();
+    return inFlightPromise;
+  }
+
+  return {
+    flush:       flush,
+    getInflight: function () { return inFlightPromise; },
+    isInFlight:  function () { return inFlight; },
+  };
+}
+
+/**
+ * @primitive b.safeAsync.makeBatchingSink
+ * @signature b.safeAsync.makeBatchingSink(opts)
+ * @since     0.15.13
+ * @status    stable
+ * @related   b.safeAsync.makeBatchDrain, b.safeAsync.makeBufferedEnqueue
+ *
+ * The complete batching egress-sink core — buffer, drop accounting,
+ * single-flight drain, and graceful close, wired together. Returns
+ * `{ emit, close, flush, stats }`. A sink built on this provides only
+ * its transport (`sendBatch`) and config; the bounded buffer, overflow
+ * and retry-exhaustion drop counting, batch-full flushing, and
+ * drain-before-close shutdown all come from here.
+ *
+ * It composes the three lower-level primitives —
+ * `makeBufferedEnqueue` (backpressure), `makeBatchDrain` (single-flight
+ * drain), `makeDrainingClose` (shutdown) — so every sink shares one
+ * implementation of the parts that are easy to get subtly wrong (an
+ * unbounded buffer is an OOM vector; flipping closed before the final
+ * drain strands tail records).
+ *
+ * `opts.sendBatch(batch)` is the transport; a throw means permanent
+ * rejection (counted as a drop, reported via onDrop "retry-exhausted").
+ * `opts.prepareRecord(record)` optionally transforms or rejects a record
+ * before buffering — return `{ entry }` to buffer `entry`, or
+ * `{ rejected: true, reason, dropKind?, drop?, error? }` to refuse it
+ * (e.g. an oversize event past a provider's hard cap). `opts.takeBatch`
+ * and `opts.beforeDrain` are forwarded to the drain (byte-cap batching;
+ * a pre-drain handshake whose failure drops the buffer under
+ * `opts.beforeDrainDropKind`).
+ *
+ * @opts
+ *   batchSize:           number,   // flush at this depth
+ *   bufferLimit:         number,   // drop oldest past this depth
+ *   maxBatchAgeMs:       number,   // coalescing flush delay
+ *   sendBatch:           Function, // (batch) => Promise — transport
+ *   onDrop:              Function, // ({reason,batch,error}) => void (optional)
+ *   prepareRecord:       Function, // (record) => {entry}|{rejected,...} (optional)
+ *   takeBatch:           Function, // () => batch (optional; byte-cap sinks)
+ *   beforeDrain:         Function, // () => Promise (optional pre-drain step)
+ *   beforeDrainDropKind: string,   // drop kind when beforeDrain fails
+ *
+ * @example
+ *   var b = require("blamejs");
+ *
+ *   var sent = [];
+ *   var sink = b.safeAsync.makeBatchingSink({
+ *     batchSize:     2,
+ *     bufferLimit:   100,
+ *     maxBatchAgeMs: 50,
+ *     sendBatch:     function (batch) { sent.push(batch); return Promise.resolve(); },
+ *   });
+ *   await sink.emit({ message: "a" });
+ *   await sink.emit({ message: "b" });  // batch full → flush
+ *   await sink.close();
+ *   sent.length;
+ *   // → 1
+ */
+function makeBatchingSink(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new TypeError("safeAsync.makeBatchingSink: opts is required");
+  }
+  if (typeof opts.sendBatch !== "function") {
+    throw new TypeError("safeAsync.makeBatchingSink: opts.sendBatch must be a function");
+  }
+  if (opts.prepareRecord != null && typeof opts.prepareRecord !== "function") {
+    throw new TypeError("safeAsync.makeBatchingSink: opts.prepareRecord must be a function when provided");
+  }
+  // batchSize / bufferLimit / maxBatchAgeMs are validated by the sub-primitives.
+  var prepareRecord = opts.prepareRecord || null;
+  var beforeDrainDropKind = opts.beforeDrainDropKind || "before-drain-failed";
+  var onDrop = makeDropCallback(opts.onDrop);
+
+  var buffer = [];
+  var dropCount = 0;
+  var closed = false;
+
+  var flushScheduler = makeScheduledFlush(opts.maxBatchAgeMs, function () { return _flush(); });
+
+  var drain = makeBatchDrain({
+    buffer:      buffer,
+    batchSize:   opts.batchSize,
+    scheduler:   flushScheduler,
+    isClosed:    function () { return closed; },
+    takeBatch:   opts.takeBatch,
+    beforeDrain: opts.beforeDrain,
+    onBeforeDrainFail: opts.beforeDrain
+      ? function (records, e) { dropCount += records.length; onDrop(beforeDrainDropKind, records, e); }
+      : undefined,
+    sendBatch:   opts.sendBatch,
+    onRetryExhausted: function (batch, e) { dropCount += batch.length; onDrop("retry-exhausted", batch, e); },
+  });
+  var _flush = drain.flush;
+
+  var enqueue = makeBufferedEnqueue(buffer, {
+    batchSize:   opts.batchSize,
+    bufferLimit: opts.bufferLimit,
+    flush:       _flush,
+    schedule:    flushScheduler.schedule,
+    onOverflow:  function (dropped) { dropCount += 1; onDrop("overflow", [dropped], null); },
+  });
+
+  function emit(record) {
+    if (closed) return Promise.resolve({ accepted: false, reason: "sink closed" });
+    if (prepareRecord) {
+      var prepared = prepareRecord(record);
+      if (prepared && prepared.rejected) {
+        dropCount += 1;
+        if (prepared.drop) onDrop(prepared.dropKind || prepared.reason, prepared.drop, prepared.error || null);
+        return Promise.resolve({ accepted: false, reason: prepared.reason });
+      }
+      return enqueue(prepared && "entry" in prepared ? prepared.entry : record);
+    }
+    return enqueue(record);
+  }
+
+  var close = makeDrainingClose({
+    scheduler:   flushScheduler,
+    getInflight: drain.getInflight,
+    flush:       _flush,
+    markClosed:  function () { closed = true; },
+  });
+
+  return {
+    emit:  emit,
+    close: close,
+    flush: _flush,
+    // `extra` merges sink-specific fields (resolved URL, sequence token …)
+    // over the shared { queued, dropped, inFlight } base.
+    stats: function (extra) {
+      var base = { queued: buffer.length, dropped: dropCount, inFlight: drain.isInFlight() };
+      return extra ? Object.assign(base, extra) : base;
+    },
+  };
+}
+
 // ---- parallel ----
 //
 // Bounded-concurrency mapAsync. Runs `fn(item, index)` over `items`
@@ -1174,6 +1627,10 @@ module.exports = {
   safeInvoke:         safeInvoke,
   makeDropCallback:   makeDropCallback,
   makeScheduledFlush: makeScheduledFlush,
+  makeBufferedEnqueue: makeBufferedEnqueue,
+  makeDrainingClose:  makeDrainingClose,
+  makeBatchDrain:     makeBatchDrain,
+  makeBatchingSink:   makeBatchingSink,
   parallel:           parallel,
   Mutex:              Mutex,
   Semaphore:          Semaphore,

package/lib/vendor/blamejs/lib/safe-buffer.js

@@ -167,7 +167,13 @@ function normalizeText(input, opts) {
  *
  * @opts
  *   maxBytes: number,        // optional positive finite int; byte cap
- *   errorClass: Function,    // caller-supplied Error subclass
+ *   encoding: string,        // string→Buffer encoding. default "utf8" (e.g. "hex", "base64")
+ *   allowString: boolean,    // accept a string input (coerced via `encoding`). default true;
+ *                            //   false = byte inputs only (Buffer/Uint8Array) — a string throws
+ *                            //   (COSE_Key / mdoc CBOR / DNSSEC bytes are byte-only by spec)
+ *   errorClass: Function,    // caller-supplied Error subclass; thrown as new Class(message, code)
+ *   errorFactory: Function,  // (code, message) -> Error; for caller error classes whose
+ *                            //   constructor is (code, message) — sidesteps the errorClass order
  *   typeCode: string,        // default "buffer/wrong-input-type"
  *   sizeCode: string,        // default "buffer/too-large"
  *   typeMessage: string,     // override the wrong-input-type message
@@ -208,23 +214,146 @@ function toBuffer(data, opts) {
     maxBytes = opts.maxBytes;
   }
   var errClass = opts.errorClass;
+  var errFactory = opts.errorFactory;
+  var encoding = opts.encoding || "utf8";
+  var allowString = opts.allowString !== false;   // default true; false = byte inputs only (string throws)
   var typeCode = opts.typeCode  || "buffer/wrong-input-type";
   var sizeCode = opts.sizeCode  || "buffer/too-large";
   var typeMsg  = opts.typeMessage || "data must be Buffer, Uint8Array, or string";
   var sizeMsg  = opts.sizeMessage || "data exceeds maxBytes";
+  // errorFactory wins when supplied (caller's class is (code, message)-shaped);
+  // otherwise fall back to the (message, code) errorClass path.
+  function _raise(message, code) {
+    if (typeof errFactory === "function") throw errFactory(code, message);
+    _throw(errClass, message, code);
+  }
 
   var buf;
-  if (Buffer.isBuffer(data))             buf = data;
-  else if (typeof data === "string")     buf = Buffer.from(data, "utf8");
-  else if (data instanceof Uint8Array)   buf = Buffer.from(data);
-  else _throw(errClass, typeMsg, typeCode);
+  if (Buffer.isBuffer(data))                          buf = data;
+  else if (allowString && typeof data === "string")  buf = Buffer.from(data, encoding);
+  else if (data instanceof Uint8Array)               buf = Buffer.from(data);
+  else _raise(typeMsg, typeCode);   // a string under allowString:false falls through here
 
   if (maxBytes !== null && buf.length > maxBytes) {
-    _throw(errClass, sizeMsg, sizeCode);
+    _raise(sizeMsg, sizeCode);
   }
   return buf;
 }
 
+/**
+ * @primitive b.safeBuffer.makeByteCoercer
+ * @signature b.safeBuffer.makeByteCoercer(opts)
+ * @since     0.15.13
+ * @status    stable
+ * @related   b.safeBuffer.toBuffer, b.safeBuffer.byteLengthOf
+ *
+ * Bind `toBuffer` to one module's error contract, returning a
+ * `coerce(value, what)` that validates `value` is a byte input (with the
+ * module's `allowString` / `encoding` policy) and, on a type mismatch,
+ * throws the module's own error class with a per-field message
+ * `messagePrefix + what + messageSuffix`. The mirror of
+ * `b.audit.namespaced` / `b.observability.namespaced` for the byte-input
+ * boundary: each module bound `toBuffer` to its error class + code +
+ * message template in a hand-rolled `function _bytes(x, what) { return
+ * toBuffer(x, { errorFactory: (c, m) => new XError(c, m), … }); }`
+ * wrapper — this owns that binding once.
+ *
+ * `what` names the field being coerced (`"issuerAuth"`, `"x coordinate"`)
+ * and is interpolated into the message so one coercer serves every call
+ * site in a module. The byte-mode is whatever `toBuffer` accepts:
+ * `allowString: false` for strict byte-only inputs (COSE / mdoc / DNSSEC
+ * wire data), or `encoding` (`"hex"` / `"base64"`) for modules that
+ * accept an encoded string alongside raw bytes.
+ *
+ * @opts
+ *   errorClass:    Function,  // required — (code, message) error constructor
+ *   typeCode:      string,    // required — error code on a type mismatch
+ *   messagePrefix: string,    // text before `what`. default: ""
+ *   messageSuffix: string,    // text after `what`. default: ""
+ *   allowString:   boolean,   // forwarded to toBuffer. default: true
+ *   encoding:      string,    // forwarded to toBuffer. default: "utf8"
+ *
+ * @example
+ *   var b = require("blamejs");
+ *
+ *   function DnssecError(code, msg) { this.code = code; this.message = msg; }
+ *   var toBytes = b.safeBuffer.makeByteCoercer({
+ *     errorClass:    DnssecError,
+ *     typeCode:      "dnssec/bad-bytes",
+ *     messagePrefix: "dnssec: ",
+ *     messageSuffix: " must be a Buffer",
+ *     allowString:   false,
+ *   });
+ *   toBytes(Buffer.from([1, 2]), "RRSIG");   // → <Buffer 01 02>
+ *   // toBytes("nope", "RRSIG") throws DnssecError("dnssec/bad-bytes",
+ *   //   "dnssec: RRSIG must be a Buffer")
+ */
+function makeByteCoercer(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new SafeBufferError("makeByteCoercer: opts is required", "buffer/bad-arg");
+  }
+  if (typeof opts.errorClass !== "function") {
+    throw new SafeBufferError("makeByteCoercer: opts.errorClass must be a constructor", "buffer/bad-arg");
+  }
+  if (typeof opts.typeCode !== "string" || opts.typeCode.length === 0) {
+    throw new SafeBufferError("makeByteCoercer: opts.typeCode must be a non-empty string", "buffer/bad-arg");
+  }
+  var ErrorClass = opts.errorClass;
+  var errorFactory = function (code, message) { return new ErrorClass(code, message); };
+  var typeCode = opts.typeCode;
+  var prefix = opts.messagePrefix != null ? opts.messagePrefix : "";
+  var suffix = opts.messageSuffix != null ? opts.messageSuffix : "";
+  var allowString = opts.allowString;
+  var encoding = opts.encoding;
+  return function coerce(value, what) {
+    return toBuffer(value, {
+      allowString:  allowString,
+      encoding:     encoding,
+      errorFactory: errorFactory,
+      typeCode:     typeCode,
+      typeMessage:  prefix + (what == null ? "" : what) + suffix,
+    });
+  };
+}
+
+/**
+ * @primitive b.safeBuffer.byteLengthOf
+ * @signature b.safeBuffer.byteLengthOf(value, encoding?)
+ * @since     0.15.13
+ * @related   b.safeBuffer.toBuffer, b.safeBuffer.normalizeText
+ *
+ * The byte length of a string OR a byte container, measured correctly
+ * for either. A `String`'s `.length` counts UTF-16 code units, NOT
+ * bytes — comparing it to a cap named in bytes under-enforces the cap
+ * on multibyte input (a 2-4 byte character counts as 1, so the real
+ * ceiling is up to ~4x the configured limit). This primitive returns
+ * `Buffer.byteLength(value, encoding)` for a string and `value.length`
+ * for a `Buffer` / `Uint8Array` (whose `.length` already IS the byte
+ * count), so a byte cap is enforced the same way regardless of whether
+ * the value arrived decoded or raw. Route every byte-cap comparison
+ * through it instead of `value.length > someBytesCap`.
+ *
+ * Throws `TypeError` on any other type (a defensive net — callers
+ * type-check their input before measuring).
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeBuffer.byteLengthOf("a");          // → 1
+ *   b.safeBuffer.byteLengthOf("中");     // → 3  (one CJK char, 3 UTF-8 bytes)
+ *   "中".length;                          // → 1  (UTF-16 code units — the trap)
+ *   b.safeBuffer.byteLengthOf(Buffer.from([1, 2, 3])); // → 3
+ */
+function byteLengthOf(value, encoding) {
+  if (typeof value === "string") {
+    return Buffer.byteLength(value, encoding || "utf8");
+  }
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    return value.length;
+  }
+  throw new TypeError("safeBuffer.byteLengthOf: value must be a string, " +
+    "Buffer, or Uint8Array; got " + (value === null ? "null" : typeof value));
+}
+
 // ---- boundedChunkCollector ----
 //
 // Replaces the unbounded `chunks.push(c); ... Buffer.concat(chunks)`
@@ -672,6 +801,8 @@ function stripCrlf(s, replacement) {
 module.exports = {
   normalizeText:         normalizeText,
   toBuffer:              toBuffer,
+  makeByteCoercer:       makeByteCoercer,
+  byteLengthOf:          byteLengthOf,
   boundedChunkCollector: boundedChunkCollector,
   collectStream: collectStream,
   secureZero:            secureZero,

package/lib/vendor/blamejs/lib/safe-decompress.js

@@ -81,6 +81,7 @@
  */
 
 var zlib = require("node:zlib");
+var safeBuffer = require("./safe-buffer");
 var lazyRequire = require("./lazy-require");
 var validateOpts = require("./validate-opts");
 var numericBounds = require("./numeric-bounds");
@@ -202,7 +203,7 @@ function safeDecompress(input, opts) {
   if (opts.maxCompressedBytes !== undefined && opts.maxCompressedBytes !== null) {
     maxCompressedBytes = opts.maxCompressedBytes;
   }
-  if (buf.length > maxCompressedBytes) {
+  if (safeBuffer.byteLengthOf(buf) > maxCompressedBytes) {
     _refuse(opts, "safe-decompress/oversized-input",
       "compressed input " + buf.length + " bytes exceeds maxCompressedBytes " +
       maxCompressedBytes);

package/lib/vendor/blamejs/lib/safe-dns.js

@@ -56,6 +56,7 @@
  */
 
 var C                  = require("./constants");
+var safeBuffer         = require("./safe-buffer");
 var { defineClass }    = require("./framework-error");
 var gateContract       = require("./gate-contract");
 
@@ -206,7 +207,7 @@ function parseResponse(buf, opts) {
       "safeDns.parseResponse: buf must be a Buffer; got " + (typeof buf));
   }
   var caps = _resolveProfile(opts);
-  if (buf.length > caps.maxResponseBytes) {
+  if (safeBuffer.byteLengthOf(buf) > caps.maxResponseBytes) {
     throw new SafeDnsError("safe-dns/oversize-response",
       "safeDns.parseResponse: " + buf.length + " bytes exceeds maxResponseBytes=" +
       caps.maxResponseBytes + " (RFC 6891 §6.1 EDNS0 advertised buffer size)");