@blamejs/core 0.4.1

package/lib/safe-async.js

@@ -0,0 +1,520 @@
+"use strict";
+/**
+ * Async resilience + safety primitives.
+ *
+ * The framework's async surfaces (external-db queries, cluster
+ * coordination, queue operations, audit chain writes) all share the
+ * same hazards: races between interleaved awaits, unbounded retries
+ * masking real failures, hangs from unresponsive backends, and partial
+ * results from operator-supplied drivers. This module collects the
+ * primitives the framework uses to handle those hazards consistently.
+ *
+ * Design posture:
+ *
+ *   - **AbortSignal everywhere.** Every primitive that takes time
+ *     accepts an `AbortSignal` and aborts cleanly when the signal
+ *     fires. This is the modern Node.js convention (Node 18+) and
+ *     replaces the older "cancellation token" pattern. Operators who
+ *     don't pass a signal get the legacy non-cancellable behaviour.
+ *
+ *   - **Error.cause preserved.** Wrapper errors set `.cause` to the
+ *     original failure so debugging traces back to the root. Callers
+ *     who walk `.cause` chains see the full picture.
+ *
+ *   - **No leaked Promises.** Mutex / Semaphore release on path-out
+ *     in finally blocks — even cancellation. No pending acquirer
+ *     stays referenced after its abort.
+ *
+ *   - **Bounded by default.** Semaphore / Queue have explicit limits
+ *     and reject acquisitions over the limit rather than growing
+ *     unboundedly. Operators size limits explicitly for their workload.
+ *
+ *   - **Fail loud.** Errors propagate; primitives never silently
+ *     swallow. safeAwait() opt-in for callers who need {error, value}
+ *     tuples; everything else throws / rejects.
+ *
+ * Public API:
+ *
+ *   withTimeout(promise, ms, opts?)        promise; rejects on timeout
+ *   withSignal(promise, signal)            promise; rejects on abort
+ *   withTimeoutSignal(signal, ms)          AbortSignal composing user
+ *                                          signal + a fresh timeout. Used
+ *                                          by I/O primitives that already
+ *                                          accept a signal and want to
+ *                                          add a wall-clock deadline.
+ *   sleep(ms, opts?)                       promise that resolves after ms;
+ *                                          opts.signal aborts mid-sleep,
+ *                                          timer is unref'd so a pending
+ *                                          sleep doesn't keep the process
+ *                                          alive
+ *   safeAwait(promise)                     [error, value] never throws
+ *
+ *   Mutex                                  class; .runExclusive(fn)
+ *   Semaphore(limit)                       class; .runWith(fn)
+ *   Once(fn)                               class; .invoke()
+ *
+ *   asyncRetry(fn, opts?)                  re-export from object-store-retry
+ *   CircuitBreaker(name, opts?)            re-export from object-store-retry
+ *
+ *   SafeAsyncError                         error class
+ *
+ * Best-practice notes for callers:
+ *
+ *   - Always pair `withTimeout` with the external-db / network calls
+ *     where operator-supplied drivers might hang. The framework's
+ *     external-db wrapper already retries; timeout puts a ceiling on
+ *     each individual attempt.
+ *
+ *   - Wrap chain-writes with Mutex.runExclusive. Audit chain hashing
+ *     reads the previous tip and writes a successor; without
+ *     serialization, concurrent awaiting record() calls can hash
+ *     against the same prev-tip and produce a forked chain. Mutex
+ *     prevents this in single-process; for cross-process coordination
+ *     the cluster module's leader election is the correct primitive.
+ *
+ *   - Use Once for boot-time lazy init (counter primer, schema
+ *     check). Multiple concurrent first-callers correctly all wait
+ *     on the same in-flight init Promise rather than each starting
+ *     their own.
+ *
+ *   - Use safeAwait for fire-and-forget paths (audit hooks in
+ *     middleware) that previously used try/catch — preserves the
+ *     "log + continue" pattern without unhandled-rejection warnings.
+ *
+ *   - Prefer Promise.allSettled over Promise.all when partial failure
+ *     is acceptable (e.g. emitting to multiple log sinks; one sink
+ *     down shouldn't block the others). The framework's log-stream
+ *     dispatcher already does this.
+ */
+
+var { FrameworkError } = require("./framework-error");
+
+class SafeAsyncError extends FrameworkError {
+  constructor(message, code, cause) {
+    super(message);
+    this.name = "SafeAsyncError";
+    this.code = code || "async/invalid";
+    if (cause !== undefined) this.cause = cause;
+    this.isSafeAsyncError = true;
+  }
+}
+
+// ---- withTimeout ----
+//
+// Race the promise against a timer. On timeout, the wrapper rejects with
+// SafeAsyncError(code=async/timeout). The original promise continues
+// running in the background — the framework cannot cancel an arbitrary
+// async operation; only signal-aware ones can be aborted (see withSignal).
+//
+// opts.signal: AbortSignal — aborting the signal also rejects the wrapper
+//              with code=async/aborted.
+// opts.name:   diagnostic label included in the timeout message.
+
+function withTimeout(promise, ms, opts) {
+  opts = opts || {};
+  if (typeof ms !== "number" || ms <= 0 || !Number.isFinite(ms)) {
+    throw new SafeAsyncError("withTimeout: ms must be a positive finite number", "async/bad-arg");
+  }
+  return new Promise(function (resolve, reject) {
+    var settled = false;
+    // The timer is ref'd intentionally: while a withTimeout is pending,
+    // the process should stay alive until either the underlying promise
+    // settles or the timeout fires. unref'ing here would let Node exit
+    // mid-await and the awaited Promise would never resolve.
+    var timer = setTimeout(function () {
+      if (settled) return;
+      settled = true;
+      reject(new SafeAsyncError(
+        "operation timed out after " + ms + "ms" + (opts.name ? " (" + opts.name + ")" : ""),
+        "async/timeout"
+      ));
+    }, ms);
+
+    function _onAbort() {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(new SafeAsyncError(
+        "operation aborted" + (opts.name ? " (" + opts.name + ")" : ""),
+        "async/aborted",
+        opts.signal && opts.signal.reason
+      ));
+    }
+    if (opts.signal) {
+      if (opts.signal.aborted) { _onAbort(); return; }
+      opts.signal.addEventListener("abort", _onAbort, { once: true });
+    }
+
+    Promise.resolve(promise).then(function (v) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (opts.signal) opts.signal.removeEventListener("abort", _onAbort);
+      resolve(v);
+    }, function (e) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (opts.signal) opts.signal.removeEventListener("abort", _onAbort);
+      reject(e);
+    });
+  });
+}
+
+// ---- withSignal ----
+//
+// Race the promise against an AbortSignal. The original promise continues
+// running in the background; only the wrapper's resolution is short-
+// circuited. Useful for plumbing a single signal through a chain of awaits.
+
+function withSignal(promise, signal) {
+  if (!signal) return Promise.resolve(promise);
+  return new Promise(function (resolve, reject) {
+    var settled = false;
+    function _onAbort() {
+      if (settled) return;
+      settled = true;
+      reject(new SafeAsyncError(
+        "operation aborted",
+        "async/aborted",
+        signal.reason
+      ));
+    }
+    if (signal.aborted) { _onAbort(); return; }
+    signal.addEventListener("abort", _onAbort, { once: true });
+    Promise.resolve(promise).then(function (v) {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener("abort", _onAbort);
+      resolve(v);
+    }, function (e) {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener("abort", _onAbort);
+      reject(e);
+    });
+  });
+}
+
+// ---- sleep ----
+//
+// Promise that resolves after `ms` milliseconds. opts.signal aborts the
+// sleep cleanly — the wrapper rejects with SafeAsyncError(async/aborted).
+//
+// opts.unref (default false): if true, the timer is unref'd so a pending
+// sleep does NOT keep the process alive. Use for fire-and-forget /
+// heartbeat-style patterns where the program should be free to exit if
+// nothing else is keeping it busy. The default is ref'd to match the
+// natural meaning of `await sleep(ms)` — "I'm waiting, this IS my work,
+// don't exit out from under me." (An unref'd-only event loop in Node
+// exits even with pending awaits — the unref'd timer is not enough to
+// hold the loop alive, so the awaiting promise never resolves.)
+//
+// ms <= 0 resolves immediately (matches setTimeout's clamp-to-1ms but
+// without the wasted tick). Non-finite ms rejects.
+
+function sleep(ms, opts) {
+  if (typeof ms !== "number" || !Number.isFinite(ms)) {
+    return Promise.reject(new SafeAsyncError(
+      "sleep: ms must be a finite number", "async/bad-arg"
+    ));
+  }
+  if (ms <= 0) return Promise.resolve();
+
+  var signal = opts && opts.signal;
+  if (signal && signal.aborted) {
+    return Promise.reject(new SafeAsyncError(
+      "sleep aborted before start", "async/aborted", signal.reason
+    ));
+  }
+
+  return new Promise(function (resolve, reject) {
+    var settled = false;
+    var timer = setTimeout(function () {
+      if (settled) return;
+      settled = true;
+      if (signal) signal.removeEventListener("abort", _onAbort);
+      resolve();
+    }, ms);
+    if (opts && opts.unref) timer.unref();
+
+    function _onAbort() {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(new SafeAsyncError(
+        "sleep aborted", "async/aborted", signal.reason
+      ));
+    }
+    if (signal) signal.addEventListener("abort", _onAbort, { once: true });
+  });
+}
+
+// ---- withTimeoutSignal ----
+//
+// Returns an AbortSignal that fires when EITHER the input signal aborts
+// OR `ms` milliseconds elapse. Wraps the I/O-primitive composition that
+// http-client was doing inline twice (h1 + h2 paths).
+//
+//   var sig = withTimeoutSignal(userSignal, 5000);
+//   await fetch(url, { signal: sig });
+//
+// Edge cases:
+//   - userSignal == null and ms not positive → returns null
+//     (caller's "no signal needed" path)
+//   - userSignal == null              → returns AbortSignal.timeout(ms)
+//   - ms not positive (0/undefined)   → returns userSignal unchanged
+//   - both                            → AbortSignal.any([user, timeout])
+//
+// Returning null when neither is requested means the caller can pass
+// the result straight to APIs that treat null as "no abort" (the http
+// `signal` option does), with no special-case branching needed.
+
+function withTimeoutSignal(signal, ms) {
+  var hasTimeout = typeof ms === "number" && ms > 0 && Number.isFinite(ms);
+  if (!signal && !hasTimeout) return null;
+  if (!signal)  return AbortSignal.timeout(ms);
+  if (!hasTimeout) return signal;
+  return AbortSignal.any([signal, AbortSignal.timeout(ms)]);
+}
+
+// ---- safeAwait ----
+//
+// Go-style [error, value] tuple. Never throws. Lets callers handle the
+// "expected may fail; log and continue" pattern without try/catch
+// scaffolding.
+//
+//   var [err, value] = await safeAwait(somePromise);
+//   if (err) { /* log + continue */ }
+
+async function safeAwait(promise) {
+  try {
+    var v = await promise;
+    return [null, v];
+  } catch (e) {
+    return [e, null];
+  }
+}
+
+// ---- Mutex ----
+//
+// Async mutex — only one async region holds the lock at a time. Acquirers
+// queue in arrival order. .runExclusive(fn) is the recommended call form
+// (lock release is automatic via finally even if fn throws); .acquire()
+// + .release() are exposed for callers needing finer control.
+//
+// Implementation note: a queued acquirer that's never released (operator
+// bug) blocks the entire mutex. We don't add a hard-coded timeout because
+// timeouts mask bugs and the real fix is releasing properly. If a caller
+// wants a deadline, wrap the runExclusive call with withTimeout.
+
+class Mutex {
+  constructor() {
+    this._waiters = [];     // [{ resolve, reject, signal, onAbort }]
+    this._held = false;
+  }
+
+  // acquire(opts?) — opts.signal aborts a waiting acquirer cleanly.
+  // When the signal fires, the waiter is removed from the queue and
+  // its Promise rejects with async/aborted. The slot it WOULD have
+  // taken stays free for the next waiter. If the mutex isn't held,
+  // acquire returns immediately regardless of signal state.
+  acquire(opts) {
+    var self = this;
+    var signal = opts && opts.signal;
+    if (!self._held) {
+      self._held = true;
+      return Promise.resolve();
+    }
+    if (signal && signal.aborted) {
+      return Promise.reject(new SafeAsyncError(
+        "Mutex.acquire aborted", "async/aborted", signal.reason
+      ));
+    }
+    return new Promise(function (resolve, reject) {
+      var entry = { resolve: resolve, reject: reject, signal: signal, onAbort: null };
+      if (signal) {
+        entry.onAbort = function () {
+          var idx = self._waiters.indexOf(entry);
+          if (idx === -1) return;     // already taken or already aborted
+          self._waiters.splice(idx, 1);
+          reject(new SafeAsyncError(
+            "Mutex.acquire aborted while waiting", "async/aborted", signal.reason
+          ));
+        };
+        signal.addEventListener("abort", entry.onAbort, { once: true });
+      }
+      self._waiters.push(entry);
+    });
+  }
+
+  release() {
+    if (!this._held) {
+      throw new SafeAsyncError("release on unheld Mutex", "async/bad-release");
+    }
+    if (this._waiters.length > 0) {
+      var next = this._waiters.shift();
+      if (next.signal && next.onAbort) {
+        next.signal.removeEventListener("abort", next.onAbort);
+      }
+      next.resolve();
+    } else {
+      this._held = false;
+    }
+  }
+
+  async runExclusive(fn, opts) {
+    await this.acquire(opts);
+    try {
+      return await fn();
+    } finally {
+      this.release();
+    }
+  }
+
+  isHeld() { return this._held; }
+  pendingCount() { return this._waiters.length; }
+}
+
+// ---- Semaphore ----
+//
+// Bounded concurrency: at most `limit` simultaneous holders. Acquirers
+// over the limit wait their turn. Use cases: limit external-db query
+// concurrency, throttle outbound webhook fan-out, cap parallel file I/O.
+//
+// .runWith(fn) is the recommended form (release on finally); .acquire/
+// .release are exposed for finer control.
+
+class Semaphore {
+  constructor(limit) {
+    if (typeof limit !== "number" || limit < 1 || !Number.isInteger(limit)) {
+      throw new SafeAsyncError("Semaphore limit must be a positive integer", "async/bad-arg");
+    }
+    this._limit = limit;
+    this._inFlight = 0;
+    this._waiters = [];     // [{ resolve, reject, signal, onAbort }]
+  }
+
+  // acquire(opts?) — opts.signal aborts a waiting acquirer cleanly.
+  acquire(opts) {
+    var self = this;
+    var signal = opts && opts.signal;
+    if (self._inFlight < self._limit) {
+      self._inFlight += 1;
+      return Promise.resolve();
+    }
+    if (signal && signal.aborted) {
+      return Promise.reject(new SafeAsyncError(
+        "Semaphore.acquire aborted", "async/aborted", signal.reason
+      ));
+    }
+    return new Promise(function (resolve, reject) {
+      var entry = { resolve: resolve, reject: reject, signal: signal, onAbort: null };
+      if (signal) {
+        entry.onAbort = function () {
+          var idx = self._waiters.indexOf(entry);
+          if (idx === -1) return;
+          self._waiters.splice(idx, 1);
+          reject(new SafeAsyncError(
+            "Semaphore.acquire aborted while waiting", "async/aborted", signal.reason
+          ));
+        };
+        signal.addEventListener("abort", entry.onAbort, { once: true });
+      }
+      self._waiters.push(entry);
+    });
+  }
+
+  release() {
+    if (this._inFlight === 0) {
+      throw new SafeAsyncError("release on idle Semaphore", "async/bad-release");
+    }
+    if (this._waiters.length > 0) {
+      var next = this._waiters.shift();
+      if (next.signal && next.onAbort) {
+        next.signal.removeEventListener("abort", next.onAbort);
+      }
+      next.resolve();
+    } else {
+      this._inFlight -= 1;
+    }
+  }
+
+  async runWith(fn, opts) {
+    await this.acquire(opts);
+    try {
+      return await fn();
+    } finally {
+      this.release();
+    }
+  }
+
+  inFlight() { return this._inFlight; }
+  pendingCount() { return this._waiters.length; }
+}
+
+// ---- Once ----
+//
+// Single-flight memoization. The first .invoke() call runs the function;
+// subsequent calls (concurrent or later) await the same in-flight Promise
+// and receive the same result. If the first invocation throws, the cached
+// result is the rejected Promise — re-invocation will NOT retry.
+//
+// Use case: lazy boot-time init where multiple call sites might first-
+// touch concurrently (counter primer, schema-check, key load). Without
+// Once, the second concurrent caller would start its own init and produce
+// double-initialization.
+//
+// .reset() clears the cached Promise so the next .invoke() runs fresh.
+// Useful for tests, hot-reload, and operator-driven re-init after a
+// transient init failure. To make resets explicit (avoid silent stale
+// state), reset() does NOT cancel an in-flight first invocation —
+// callers awaiting the prior invoke continue to see its result.
+
+class Once {
+  constructor(fn) {
+    if (typeof fn !== "function") {
+      throw new SafeAsyncError("Once: argument must be a function", "async/bad-arg");
+    }
+    this._fn = fn;
+    this._promise = null;
+  }
+
+  invoke() {
+    if (this._promise === null) {
+      this._promise = Promise.resolve().then(this._fn);
+    }
+    return this._promise;
+  }
+
+  reset() {
+    this._promise = null;
+  }
+
+  hasInvoked() { return this._promise !== null; }
+}
+
+// ---- Re-exports of resilience primitives from lib/retry.js ----
+//
+// withRetry + CircuitBreaker live in lib/retry.js (the canonical home).
+// We re-export them here under safe-async-shaped names so call sites
+// reaching for async safety primitives find them in one place.
+
+var retryHelper = require("./retry");
+
+var asyncRetry     = retryHelper.withRetry;
+var CircuitBreaker = retryHelper.CircuitBreaker;
+
+module.exports = {
+  withTimeout:        withTimeout,
+  withSignal:         withSignal,
+  withTimeoutSignal:  withTimeoutSignal,
+  sleep:              sleep,
+  safeAwait:          safeAwait,
+  Mutex:              Mutex,
+  Semaphore:          Semaphore,
+  Once:               Once,
+  asyncRetry:         asyncRetry,
+  CircuitBreaker:     CircuitBreaker,
+  SafeAsyncError:     SafeAsyncError,
+};

package/lib/safe-buffer.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * Buffer-safety primitives — centralizes the input-normalize, capped
+ * chunk collection, and secure-zero patterns that were scattered across
+ * lib/parsers/*, lib/atomic-file.js, lib/object-store-*.js, and
+ * lib/log-stream-*.js.
+ *
+ * Public API:
+ *   safeBuffer.normalizeText(input, { maxBytes, stripBom, errorClass })
+ *     Accept string | Buffer | Uint8Array → returns string. Strips a
+ *     leading UTF-8 BOM (U+FEFF) by default. Throws errorClass(message,
+ *     code) if input is the wrong type or exceeds maxBytes.
+ *
+ *   safeBuffer.toBuffer(data, { maxBytes, errorClass })
+ *     Accept Buffer | Uint8Array | string → returns Buffer. Throws
+ *     errorClass on type mismatch or oversize.
+ *
+ *   safeBuffer.boundedChunkCollector({ maxBytes, errorClass })
+ *     Returns { push(chunk), result(), bytesCollected() }. Each push()
+ *     enforces the cap on every chunk — the OOM defense for unbounded
+ *     HTTP response bodies replacing the previous `chunks.push(c)` +
+ *     `Buffer.concat(chunks)` pattern that accumulated arbitrary bytes
+ *     before checking size.
+ *
+ *   safeBuffer.secureZero(buf)
+ *     Best-effort zero of buf contents (`buf.fill(0)`). JavaScript can't
+ *     truly zero memory — V8 may have copies — but `fill(0)` removes the
+ *     in-Buffer reference so a heap-dump won't show the secret in this
+ *     particular Buffer. No-op on non-Buffers.
+ *
+ * Why a default error class:
+ *   Each caller (xml-safe, json-safe, atomic-file, ...) wants to throw
+ *   its own format-specific error class with a particular `code`. The
+ *   helpers accept `{ errorClass }` so the byte-handling lives here but
+ *   the error type stays format-aware (existing tests check
+ *   e.code === "xml/too-large" etc.). A default SafeBufferError is used
+ *   if the caller doesn't pass one.
+ */
+
+var { FrameworkError } = require("./framework-error");
+
+class SafeBufferError extends FrameworkError {
+  constructor(message, code) {
+    super(message);
+    this.name = "SafeBufferError";
+    this.code = code || "buffer/invalid";
+    this.isSafeBufferError = true;
+  }
+}
+
+function _throw(errorClass, message, code) {
+  var Cls = errorClass || SafeBufferError;
+  throw new Cls(message, code);
+}
+
+// ---- normalizeText ----
+
+function normalizeText(input, opts) {
+  opts = opts || {};
+  var maxBytes  = (typeof opts.maxBytes === "number" && opts.maxBytes > 0) ? opts.maxBytes : null;
+  var stripBom  = opts.stripBom !== false;  // default true
+  var errClass  = opts.errorClass;
+  var typeCode  = opts.typeCode  || "buffer/wrong-input-type";
+  var sizeCode  = opts.sizeCode  || "buffer/too-large";
+  var typeMsg   = opts.typeMessage || "input must be string, Buffer, or Uint8Array";
+  var sizeMsg   = opts.sizeMessage || "input exceeds maxBytes";
+
+  var text;
+  if (typeof input === "string")            text = input;
+  else if (Buffer.isBuffer(input))          text = input.toString("utf8");
+  else if (input instanceof Uint8Array)     text = Buffer.from(input).toString("utf8");
+  else _throw(errClass, typeMsg, typeCode);
+
+  if (stripBom && text.charCodeAt(0) === 0xFEFF) text = text.slice(1);
+
+  if (maxBytes !== null && Buffer.byteLength(text, "utf8") > maxBytes) {
+    _throw(errClass, sizeMsg, sizeCode);
+  }
+  return text;
+}
+
+// ---- toBuffer ----
+
+function toBuffer(data, opts) {
+  opts = opts || {};
+  var maxBytes = (typeof opts.maxBytes === "number" && opts.maxBytes > 0) ? opts.maxBytes : null;
+  var errClass = opts.errorClass;
+  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";
+
+  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 (maxBytes !== null && buf.length > maxBytes) {
+    _throw(errClass, sizeMsg, sizeCode);
+  }
+  return buf;
+}
+
+// ---- boundedChunkCollector ----
+//
+// Replaces the unbounded `chunks.push(c); ... Buffer.concat(chunks)`
+// pattern in HTTP response handlers. The cap is enforced at push() time
+// so a 10-GB response from a hostile/misbehaving upstream rejects on the
+// chunk that overflows — without first accumulating the whole 10 GB in
+// the chunks array.
+
+function boundedChunkCollector(opts) {
+  opts = opts || {};
+  var maxBytes = (typeof opts.maxBytes === "number" && opts.maxBytes > 0) ? opts.maxBytes : null;
+  if (maxBytes === null) {
+    throw new SafeBufferError("boundedChunkCollector requires maxBytes", "buffer/bad-arg");
+  }
+  var errClass = opts.errorClass;
+  var sizeCode = opts.sizeCode  || "buffer/too-large";
+  var sizeMsg  = opts.sizeMessage || "stream body exceeds maxBytes";
+
+  var chunks = [];
+  var total = 0;
+
+  return {
+    push: function (chunk) {
+      // Accept Buffer or Uint8Array (Node's res.on('data') yields Buffer
+      // by default but consumers may have set encoding to get strings).
+      if (typeof chunk === "string") chunk = Buffer.from(chunk, "utf8");
+      else if (!Buffer.isBuffer(chunk) && chunk instanceof Uint8Array) chunk = Buffer.from(chunk);
+      if (!Buffer.isBuffer(chunk)) {
+        _throw(errClass, "chunk must be Buffer, Uint8Array, or string", "buffer/wrong-input-type");
+      }
+      if (total + chunk.length > maxBytes) {
+        _throw(errClass, sizeMsg, sizeCode);
+      }
+      chunks.push(chunk);
+      total += chunk.length;
+    },
+    result: function () {
+      return Buffer.concat(chunks, total);
+    },
+    bytesCollected: function () { return total; },
+  };
+}
+
+// ---- secureZero ----
+
+function secureZero(buf) {
+  if (Buffer.isBuffer(buf) || buf instanceof Uint8Array) {
+    try { buf.fill(0); } catch (_e) { /* best effort — locked memory etc. */ }
+  }
+}
+
+module.exports = {
+  normalizeText:         normalizeText,
+  toBuffer:              toBuffer,
+  boundedChunkCollector: boundedChunkCollector,
+  secureZero:            secureZero,
+  SafeBufferError:       SafeBufferError,
+};