@blamejs/core 0.8.12 → 0.8.15

package/lib/sse.js

@@ -0,0 +1,349 @@
+"use strict";
+/**
+ * Server-Sent Events primitive — text/event-stream transport with
+ * newline-injection refusal in event:/id:/data: fields.
+ *
+ * The SSE wire format is line-oriented (W3C HTML Living Standard
+ * §server-sent-events-spec): each field is a line of the form
+ * "<name>: <value>" terminated by a single LF, and an empty line
+ * separates events. Any LF/CR/NUL inside a value silently splits the
+ * field, letting an attacker forge subsequent events, the event id
+ * (which the client echoes back as Last-Event-ID on reconnect), or
+ * the message data. Three CVEs in one quarter — CVE-2026-33128 (h3),
+ * CVE-2026-29085 (Hono), CVE-2026-44217 (sse-channel) — published in
+ * the same vulnerability class.
+ *
+ * Public API:
+ *
+ *   sse.create(req, res, opts) → channel
+ *     Wires the response stream as text/event-stream, sets the
+ *     SSE-required headers, and returns a channel object. opts:
+ *       heartbeatMs    — interval for `:keepalive` comment frames
+ *                        (default 15 s; pass 0 to disable)
+ *       retryMs        — initial reconnection-time advisory sent on
+ *                        stream open (sets the `retry:` field once;
+ *                        omitted when null/undefined)
+ *       errorClass     — FrameworkError subclass to throw on bad
+ *                        input (default SseError)
+ *       audit          — bool, default true. Emit SSE lifecycle audit
+ *                        events.
+ *
+ *   channel.send({ event, id, data, retry })
+ *     Writes a single SSE event. Each field is validated; LF/CR/NUL
+ *     anywhere in event/id is refused via `errorClass`. data is
+ *     allowed to contain LF — the framework splits it into multiple
+ *     `data:` lines per the spec — but CR and NUL are refused. retry
+ *     must be a non-negative finite integer.
+ *
+ *   channel.comment(text)
+ *     Writes a `:<text>` comment line (used for keepalive). LF/CR/NUL
+ *     in `text` are refused.
+ *
+ *   channel.close()
+ *     Ends the underlying response stream and stops the heartbeat
+ *     timer. Idempotent.
+ *
+ *   channel.lastEventId
+ *     The Last-Event-ID header value from the initial request, or
+ *     null. Sanitized — any LF/CR/NUL renders the header null
+ *     (refuse-on-bad-input rather than passing through to handlers).
+ *
+ *   sse.serializeEvent({ event, id, data, retry })
+ *     Returns the SSE-encoded string for a single event. Same
+ *     validation rules as channel.send. Exposed for operators that
+ *     buffer events through their own queue before writing.
+ *
+ * Error discipline:
+ *   channel.send and serializeEvent THROW errorClass on bad input.
+ *   SSE is not a drop-silent surface — a refused event is a
+ *   programming bug, and silently dropping would mask the injection
+ *   attempt the refusal exists to flag. close() is idempotent and
+ *   never throws.
+ *
+ * Composition:
+ *   - Composes with router via raw req/res — no router-specific
+ *     coupling. Works under h1 and h2 (h2 keeps the stream open
+ *     identically; the response is just chunked-transfer at h1 and
+ *     a long-running DATA-frame stream at h2).
+ *   - Audit emissions go through audit.safeEmit so SSE doesn't
+ *     escape audit-bus failures back to the caller.
+ */
+
+var C = require("./constants");
+var audit = require("./audit");
+var { SseError } = require("./framework-error");
+
+// Per W3C SSE — the wire format uses LF as terminator. A single LF
+// inside any field splits the value at the parser. CR is canonicalized
+// to LF by the parser (CR-only and CRLF terminators are also valid),
+// so CR is equally injection-shaped. NUL is refused universally — it
+// has no place in an event-stream wire-form and any presence is
+// suspicious.
+// eslint-disable-next-line no-control-regex
+var INJECTION_RE = /[\r\n\u0000]/;
+
+// retry: must be a non-negative finite integer. Browsers floor /
+// reject non-integer or negative values; refuse them at the source so
+// downstream behavior is uniform.
+function _validateRetry(retry, errorClass) {
+  if (retry === undefined || retry === null) return null;
+  if (typeof retry !== "number" || !isFinite(retry) || retry < 0 ||
+      Math.floor(retry) !== retry) {
+    throw errorClass.factory("BAD_RETRY",
+      "sse.send: retry must be a non-negative finite integer (got " +
+      JSON.stringify(retry) + ")");
+  }
+  return retry;
+}
+
+function _refuseInjection(field, value, errorClass) {
+  if (typeof value !== "string") {
+    throw errorClass.factory("BAD_FIELD",
+      "sse.send: " + field + " must be a string");
+  }
+  // Length-bound BEFORE the regex test — _capField applies a tighter
+  // cap further along, but the regex itself runs against the full
+  // value so we bound here too.
+  if (value.length > MAX_DATA_BYTES) {
+    throw errorClass.factory("FIELD_TOO_LARGE",
+      "sse.send: " + field + " too large for injection scan");
+  }
+  if (INJECTION_RE.test(value)) {                                                          // allow:regex-no-length-cap — value length capped above
+    audit.safeEmit({
+      action:   "sse.injection_refused",
+      outcome:  "denied",
+      metadata: { field: field, length: value.length },
+    });
+    throw errorClass.factory("INJECTION",
+      "sse.send: " + field + " contains LF/CR/NUL — refused " +
+      "(CVE-2026-33128 / 29085 / 44217 class)");
+  }
+}
+
+// Field caps. Values aren't open-ended — a 100 MiB `id:` is an abuse
+// shape. Operators who need larger bodies use the chunked binary
+// transports (websocket / file-upload). SSE is for text events.
+var MAX_EVENT_BYTES = C.BYTES.kib(8);
+var MAX_ID_BYTES    = C.BYTES.kib(8);
+var MAX_DATA_BYTES  = C.BYTES.mib(1);
+
+function _capField(field, value, capBytes, errorClass) {
+  var len = Buffer.byteLength(value, "utf8");
+  if (len > capBytes) {
+    throw errorClass.factory("FIELD_TOO_LARGE",
+      "sse.send: " + field + " exceeds cap (" + len + " > " +
+      capBytes + " bytes)");
+  }
+}
+
+function serializeEvent(opts, errorClass) {
+  errorClass = errorClass || SseError;
+  if (!opts || typeof opts !== "object") {
+    throw errorClass.factory("BAD_OPTS", "sse.serializeEvent: opts required");
+  }
+  var out = "";
+  // Field order: id, event, retry, data — matches the framework's
+  // historical b.middleware.sse layout. The W3C SSE spec is order-
+  // agnostic, but consumers (incl. the existing wiki test fixtures)
+  // pin this order.
+  if (opts.id !== undefined && opts.id !== null) {
+    _refuseInjection("id", opts.id, errorClass);
+    _capField("id", opts.id, MAX_ID_BYTES, errorClass);
+    out += "id: " + opts.id + "\n";
+  }
+  if (opts.event !== undefined && opts.event !== null) {
+    _refuseInjection("event", opts.event, errorClass);
+    _capField("event", opts.event, MAX_EVENT_BYTES, errorClass);
+    out += "event: " + opts.event + "\n";
+  }
+  var retry = _validateRetry(opts.retry, errorClass);
+  if (retry !== null) {
+    out += "retry: " + retry + "\n";
+  }
+  if (opts.data !== undefined && opts.data !== null) {
+    if (typeof opts.data !== "string") {
+      throw errorClass.factory("BAD_FIELD",
+        "sse.send: data must be a string");
+    }
+    _capField("data", opts.data, MAX_DATA_BYTES, errorClass);
+    // CR / NUL refused; LF allowed (split into multiple data: lines).
+    // eslint-disable-next-line no-control-regex
+    if (/[\r\u0000]/.test(opts.data)) {
+      audit.safeEmit({
+        action:   "sse.injection_refused",
+        outcome:  "denied",
+        metadata: { field: "data", length: opts.data.length, char: "cr-or-nul" },
+      });
+      throw errorClass.factory("INJECTION",
+        "sse.send: data contains CR or NUL — refused");
+    }
+    var lines = opts.data.split("\n");
+    for (var i = 0; i < lines.length; i += 1) {
+      out += "data: " + lines[i] + "\n";
+    }
+  }
+  // Empty line separator.
+  out += "\n";
+  return out;
+}
+
+function _validateComment(text, errorClass) {
+  if (typeof text !== "string") {
+    throw errorClass.factory("BAD_FIELD",
+      "sse.comment: text must be a string");
+  }
+  if (text.length > MAX_DATA_BYTES) {
+    throw errorClass.factory("FIELD_TOO_LARGE",
+      "sse.comment: text too large for injection scan");
+  }
+  if (INJECTION_RE.test(text)) {                                                            // allow:regex-no-length-cap — text length capped above
+    audit.safeEmit({
+      action:   "sse.injection_refused",
+      outcome:  "denied",
+      metadata: { field: "comment", length: text.length },
+    });
+    throw errorClass.factory("INJECTION",
+      "sse.comment: text contains LF/CR/NUL — refused");
+  }
+}
+
+// Sanitize the Last-Event-ID header value the client echoed on
+// reconnect. Per the spec the client SHOULD send the most recent id,
+// but we receive raw header bytes — refuse the value entirely (return
+// null) if it carries any injection-shaped char.
+function _readLastEventId(req) {
+  if (!req || !req.headers) return null;
+  var raw = req.headers["last-event-id"];
+  if (typeof raw !== "string" || raw.length === 0) return null;
+  if (INJECTION_RE.test(raw)) return null;
+  if (Buffer.byteLength(raw, "utf8") > MAX_ID_BYTES) return null;
+  return raw;
+}
+
+function create(req, res, opts) {
+  opts = opts || {};
+  var errorClass = opts.errorClass || SseError;
+  if (!res || typeof res.write !== "function" || typeof res.end !== "function") {
+    throw errorClass.factory("BAD_RES",
+      "sse.create: res must be a writable response stream");
+  }
+  var heartbeatMs = opts.heartbeatMs;
+  if (heartbeatMs === undefined) heartbeatMs = C.TIME.seconds(15);
+  if (typeof heartbeatMs !== "number" || !isFinite(heartbeatMs) ||
+      heartbeatMs < 0 || Math.floor(heartbeatMs) !== heartbeatMs) {
+    throw errorClass.factory("BAD_OPTS",
+      "sse.create: heartbeatMs must be a non-negative integer ms (got " +
+      JSON.stringify(heartbeatMs) + ")");
+  }
+  var auditOn = opts.audit !== false;
+
+  var lastEventId = _readLastEventId(req);
+
+  // Headers. text/event-stream is the contract; Cache-Control: no-cache
+  // and Connection: keep-alive (h1) are the operationally required
+  // pair. X-Accel-Buffering: no defeats nginx-style proxy buffering;
+  // operators behind a proxy that doesn't honor this set proxyBuffer:
+  // false on their LB.
+  if (typeof res.setHeader === "function") {
+    res.setHeader("Content-Type",      "text/event-stream; charset=utf-8");
+    res.setHeader("Cache-Control",     "no-cache, no-transform");
+    res.setHeader("X-Accel-Buffering", "no");
+    // Connection: keep-alive only meaningful on h1; h2 streams stay
+    // open until either side closes. node:http2 surfaces res.stream
+    // (h2 ServerHttp2Stream) where setHeader works the same.
+    if (req && req.httpVersionMajor !== 2) {
+      res.setHeader("Connection", "keep-alive");
+    }
+  }
+  if (typeof res.flushHeaders === "function") {
+    try { res.flushHeaders(); } catch (_e) { /* response may have flushed already */ }
+  }
+
+  var closed = false;
+  var heartbeatTimer = null;
+
+  function _writeRaw(s) {
+    if (closed) {
+      throw errorClass.factory("CLOSED",
+        "sse.send: channel closed");
+    }
+    res.write(s);
+  }
+
+  function send(eventOpts) {
+    var encoded = serializeEvent(eventOpts || {}, errorClass);
+    _writeRaw(encoded);
+  }
+
+  function comment(text) {
+    _validateComment(text, errorClass);
+    _writeRaw(":" + text + "\n\n");
+  }
+
+  function close() {
+    if (closed) return;
+    closed = true;
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+    try { res.end(); } catch (_e) { /* already destroyed */ }
+    if (auditOn) {
+      audit.safeEmit({
+        action:   "sse.channel_closed",
+        outcome:  "success",
+        metadata: { lastEventId: lastEventId },
+      });
+    }
+  }
+
+  // Stream-side close detection — when the client disconnects, free
+  // the heartbeat timer.
+  if (typeof res.on === "function") {
+    res.on("close",  close);
+    res.on("error",  function (_e) { close(); });
+    res.on("finish", function () { closed = true; if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; } });
+  }
+
+  // Optional retry: advisory on open.
+  if (opts.retryMs !== undefined && opts.retryMs !== null) {
+    var validatedRetry = _validateRetry(opts.retryMs, errorClass);
+    _writeRaw("retry: " + validatedRetry + "\n\n");
+  }
+
+  // Heartbeat keeps intermediaries from idle-timing out the stream and
+  // gives the client a reliable progress signal. Timer is unref'd so a
+  // single live SSE channel doesn't pin the event loop on shutdown.
+  if (heartbeatMs > 0) {
+    heartbeatTimer = setInterval(function () {
+      if (closed) return;
+      try { _writeRaw(":keepalive\n\n"); }
+      catch (_e) { close(); }
+    }, heartbeatMs).unref();
+  }
+
+  if (auditOn) {
+    audit.safeEmit({
+      action:   "sse.channel_opened",
+      outcome:  "success",
+      metadata: { lastEventId: lastEventId, heartbeatMs: heartbeatMs },
+    });
+  }
+
+  return {
+    send:        send,
+    comment:     comment,
+    close:       close,
+    get lastEventId() { return lastEventId; },
+    get closed()      { return closed;      },
+  };
+}
+
+module.exports = {
+  create:          create,
+  serializeEvent:  serializeEvent,
+  // Cap exposure for operators wiring their own framing.
+  MAX_EVENT_BYTES: MAX_EVENT_BYTES,
+  MAX_ID_BYTES:    MAX_ID_BYTES,
+  MAX_DATA_BYTES:  MAX_DATA_BYTES,
+};

package/lib/vault/index.js

@@ -292,6 +292,8 @@ function getMode() {
 
 var vaultAad = require("../vault-aad");
 
+var sealPemFileModule = require("./seal-pem-file");
+
 module.exports = {
   init:                  init,
   seal:                  seal,
@@ -301,6 +303,8 @@ module.exports = {
   getCurrentPassphrase:  getCurrentPassphrase,
   getMode:               getMode,
   VaultError:            VaultError,
+  sealPemFile:           sealPemFileModule.sealPemFile,
+  SealPemFileError:      sealPemFileModule.SealPemFileError,
   // Testing helpers — not part of the public contract
   _resetForTest:         function () {
     if (currentPassphrase) safeBuffer.secureZero(currentPassphrase);

package/lib/vault/seal-pem-file.js

@@ -0,0 +1,283 @@
+"use strict";
+/**
+ * vault/seal-pem-file — seal a PEM file at rest with file-watch auto-
+ * reseal.
+ *
+ * Operator workflow this primitive solves: ACME / Let's Encrypt
+ * renewals run on a 30-60 day cadence, write fresh certbot output to
+ * `/etc/letsencrypt/live/<domain>/privkey.pem`, and signal the
+ * application to reload. The fresh PEM lives unencrypted on disk
+ * between the renewal write and the next operator-driven re-seal.
+ * Auto-reseal closes that window: every renewal writes the plaintext
+ * PEM, the framework's watcher sees the mtime change, re-seals on the
+ * spot, and the in-process key material rotates without human
+ * intervention.
+ *
+ * Surface:
+ *
+ *   var watcher = b.vault.sealPemFile({
+ *     source:       "/etc/letsencrypt/live/example.com/privkey.pem",
+ *     destination:  "/var/lib/blamejs/server.key.sealed",
+ *     audit:        true,                 // default
+ *     pollInterval: b.constants.TIME.seconds(2),  // fs.watchFile cadence
+ *     onResealed:   function (info) { ... }, // { srcPath, destPath, bytes,
+ *                                                resealedAt, generation }
+ *     onError:      function (err)  { ... }, // sealing failed
+ *   });
+ *   // watcher.stop()
+ *   // watcher.generation        — monotonically increases per reseal
+ *   // watcher.lastResealedAt    — Unix-ms of most recent successful reseal
+ *   // watcher.lastError         — most recent failure, or null
+ *
+ * Crash-safe write protocol:
+ *
+ *   1. Write `<destination>.tmp` with mode 0o600, fsync.
+ *   2. Create `<destination>.rewriting` marker (operator-visible).
+ *   3. Rename `<destination>.tmp` → `<destination>` (atomic on POSIX).
+ *   4. Remove `<destination>.rewriting` marker.
+ *
+ * If the framework crashes between steps 2 and 4, the marker remains
+ * on disk and the next sealPemFile() call detects it. Recovery: the
+ * sealedPath is either complete (rename happened) or still .tmp
+ * (rename did not happen). The recovery routine re-runs the seal from
+ * source — idempotent because the source PEM is the source of truth.
+ *
+ * fs.watchFile semantics:
+ *
+ * Node's fs.watchFile is a polling stat() loop with the configured
+ * pollInterval. It fires on mtime / size change. fs.watch (the
+ * inotify / kqueue backend) is more efficient but inconsistent across
+ * platforms — single rename events surface as multiple change events
+ * on Linux (events fire on the directory entry, the file, and the
+ * inode), and not at all on macOS for renamed-into files. Polling
+ * with watchFile is consistent everywhere and the latency cost (one
+ * pollInterval) is acceptable for renewal cadences measured in days.
+ */
+
+var fs = require("fs");
+var path = require("path");
+var atomicFile = require("../atomic-file");
+var C = require("../constants");
+var lazyRequire = require("../lazy-require");
+var validateOpts = require("../validate-opts");
+var { defineClass } = require("../framework-error");
+var { boot } = require("../log");
+
+var vault = lazyRequire(function () { return require("./index"); });
+var audit = lazyRequire(function () { return require("../audit"); });
+
+var log = boot("vault-seal-pem");
+
+var SealPemFileError = defineClass("SealPemFileError", { alwaysPermanent: true });
+
+// Default poll cadence balances latency against syscall pressure.
+// At 2s, ACME renewals (which happen every ~60 days) experience a
+// 2-second worst-case re-seal latency — negligible against the
+// renewal cadence. Operators with sub-second-sensitive use cases
+// override via opts.pollInterval.
+var DEFAULT_POLL_MS = C.TIME.seconds(2);
+
+function sealPemFile(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "source", "destination", "audit", "pollInterval",
+    "onResealed", "onError",
+  ], "vault.sealPemFile");
+
+  validateOpts.requireNonEmptyString(opts.source,
+    "vault.sealPemFile: source must be a non-empty path",
+    SealPemFileError, "seal-pem-file/bad-source");
+  validateOpts.requireNonEmptyString(opts.destination,
+    "vault.sealPemFile: destination must be a non-empty path",
+    SealPemFileError, "seal-pem-file/bad-destination");
+  if (opts.source === opts.destination) {
+    throw new SealPemFileError("seal-pem-file/same-path",
+      "vault.sealPemFile: source and destination must differ — sealing in place would overwrite the plaintext");
+  }
+  validateOpts.optionalPositiveFinite(opts.pollInterval,
+    "vault.sealPemFile: pollInterval", SealPemFileError, "seal-pem-file/bad-poll-interval");
+  validateOpts.optionalFunction(opts.onResealed,
+    "vault.sealPemFile: onResealed", SealPemFileError, "seal-pem-file/bad-on-resealed");
+  validateOpts.optionalFunction(opts.onError,
+    "vault.sealPemFile: onError", SealPemFileError, "seal-pem-file/bad-on-error");
+
+  var source        = opts.source;
+  var destination   = opts.destination;
+  // optionalPositiveFinite above already threw on a bad-shaped opts.pollInterval;
+  // here only undefined / null / valid-positive-finite remain.
+  var pollInterval  = opts.pollInterval || DEFAULT_POLL_MS;
+  var auditOn       = opts.audit !== false;
+  var onResealed    = typeof opts.onResealed === "function" ? opts.onResealed : null;
+  var onError       = typeof opts.onError === "function" ? opts.onError : null;
+
+  var generation       = 0;
+  var lastResealedAt   = null;
+  var lastError        = null;
+  var watching         = false;
+  var listener         = null;
+  var resealing        = false;
+  var pendingMtime     = null;
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   "vault.seal_pem_file." + action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+
+  function _writeSealed(plaintextBytes) {
+    // atomicFile.writeSync already does the .tmp + fsync + rename +
+    // fsyncDir sequence atomically. The marker is the framework's
+    // operator-visible crash-detection signal — created BEFORE the
+    // atomic rename, removed AFTER. If the framework crashes between
+    // marker create and marker remove, the marker remains on disk
+    // and _recoverIfNeeded() detects it on the next start().
+    var markerPath = destination + ".rewriting";
+    atomicFile.ensureDir(path.dirname(destination));
+    var sealed = vault().seal(plaintextBytes);
+    fs.writeFileSync(markerPath, String(Date.now()), { mode: 0o600 });   // allow:raw-byte-literal — POSIX file mode
+    try {
+      atomicFile.writeSync(destination, sealed, { fileMode: 0o600 });    // allow:raw-byte-literal — POSIX file mode
+    } catch (e) {
+      try { fs.unlinkSync(markerPath); } catch (_e) { /* best-effort */ }
+      throw e;
+    }
+    try { fs.unlinkSync(markerPath); } catch (_e) { /* marker cleanup best-effort */ }
+  }
+
+  function _resealNow() {
+    if (resealing) return;
+    resealing = true;
+    try {
+      var plaintext;
+      try { plaintext = fs.readFileSync(source); }
+      catch (e) {
+        var err = new SealPemFileError("seal-pem-file/source-read-failed",
+          "vault.sealPemFile: failed to read source '" + source + "': " + e.message);
+        lastError = err;
+        _emitAudit("read_failed", "failure", { source: source, error: e.message });
+        if (onError) { try { onError(err); } catch (_e) { /* drop-silent */ } }
+        return;
+      }
+      try {
+        _writeSealed(plaintext);
+      } catch (e2) {
+        var err2 = new SealPemFileError("seal-pem-file/seal-failed",
+          "vault.sealPemFile: failed to seal '" + source + "' to '" + destination + "': " + e2.message);
+        lastError = err2;
+        _emitAudit("seal_failed", "failure", {
+          source: source, destination: destination, error: e2.message,
+        });
+        if (onError) { try { onError(err2); } catch (_e) { /* drop-silent */ } }
+        return;
+      }
+      generation += 1;
+      lastResealedAt = Date.now();
+      lastError = null;
+      _emitAudit("resealed", "success", {
+        source:     source,
+        destination: destination,
+        bytes:      plaintext.length,
+        generation: generation,
+      });
+      if (onResealed) {
+        try {
+          onResealed({
+            srcPath:    source,
+            destPath:   destination,
+            bytes:      plaintext.length,
+            resealedAt: lastResealedAt,
+            generation: generation,
+          });
+        } catch (_e) { /* drop-silent */ }
+      }
+    } finally {
+      resealing = false;
+      if (pendingMtime) {
+        // A change event arrived while we were resealing — reseal again
+        // so the latest source bytes land. Single-flight: only one
+        // pending reseal is queued.
+        pendingMtime = null;
+        setImmediate(_resealNow);
+      }
+    }
+  }
+
+  // Recover from a prior crash: if the marker is present, the previous
+  // reseal was interrupted. Re-seal from source idempotently.
+  function _recoverIfNeeded() {
+    var markerPath = destination + ".rewriting";
+    if (fs.existsSync(markerPath)) {
+      log.info("vault.sealPemFile: recovery — marker '" + markerPath +
+        "' present from prior crashed reseal; re-sealing from source");
+      _emitAudit("recovery_started", "success", {
+        source: source, destination: destination,
+      });
+      // Don't unlink the marker yet — _writeSealed will rewrite it
+      // and remove it as part of the normal sequence.
+    }
+  }
+
+  function start() {
+    if (watching) return;
+    _recoverIfNeeded();
+    // Initial seal — operator gets the destination populated on
+    // start() even if the source's mtime never changes.
+    _resealNow();
+    listener = function (curr, prev) {
+      // mtime change OR the source appearing for the first time.
+      if (curr.mtimeMs !== prev.mtimeMs || curr.size !== prev.size) {
+        if (resealing) { pendingMtime = curr.mtimeMs; return; }
+        _resealNow();
+      }
+    };
+    fs.watchFile(source, { persistent: false, interval: pollInterval }, listener);
+    watching = true;
+    _emitAudit("watch_started", "success", {
+      source:       source,
+      destination:  destination,
+      pollInterval: pollInterval,
+    });
+  }
+
+  function stop() {
+    if (!watching) return;
+    fs.unwatchFile(source, listener);
+    listener = null;
+    watching = false;
+    _emitAudit("watch_stopped", "success", {
+      source:      source,
+      destination: destination,
+      generation:  generation,
+    });
+  }
+
+  // Auto-start so the operator's `var watcher = sealPemFile(...)` call
+  // produces a populated destination immediately. Operators wiring it
+  // into a deferred lifecycle override by passing autoStart: false —
+  // not yet a frequent enough use case to surface, opens cleanly when
+  // the first operator surfaces it.
+  start();
+
+  return {
+    stop:                  stop,
+    get generation()       { return generation; },
+    get lastResealedAt()   { return lastResealedAt; },
+    get lastError()        { return lastError; },
+    get watching()         { return watching; },
+    // Force a reseal — useful for tests and operator-triggered rotations
+    // (e.g. after a manual ACME renewal). Idempotent: produces an
+    // updated destination from the current source bytes.
+    forceReseal:           _resealNow,
+  };
+}
+
+module.exports = {
+  sealPemFile:        sealPemFile,
+  SealPemFileError:   SealPemFileError,
+  DEFAULT_POLL_MS:    DEFAULT_POLL_MS,
+};

package/lib/websocket.js

@@ -725,6 +725,21 @@ class WebSocketConnection extends EventEmitter {
       return this._abort(CLOSE_PROTOCOL_ERROR, "RSV1 on continuation frame (must be on start)");
     }
 
+    // RFC 6455 §5.5 — control frames (opcodes >= 0x8: CLOSE/PING/PONG)
+    // MUST have payload length ≤ 125 and MUST NOT be fragmented.
+    // Without the cap an attacker can send a 1 MiB PING and we echo it
+    // verbatim as PONG — a 2× outbound-bandwidth amplification DoS.
+    if (frame.opcode >= 0x8) {
+      if (frame.payload.length > 125) {
+        return this._abort(CLOSE_PROTOCOL_ERROR,
+          "control frame payload exceeds 125 bytes (RFC 6455 §5.5)");
+      }
+      if (!frame.fin) {
+        return this._abort(CLOSE_PROTOCOL_ERROR,
+          "control frame must not be fragmented (RFC 6455 §5.5)");
+      }
+    }
+
     if (frame.opcode === OPCODE_CONTINUATION) {
       if (this._fragOpcode === null) {
         return this._abort(CLOSE_PROTOCOL_ERROR, "continuation without start");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.8.12",
+  "version": "0.8.15",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",
@@ -54,7 +54,7 @@
     "owns-its-stack"
   ],
   "engines": {
-    "node": ">=24.0.0"
+    "node": ">=24.4.0"
   },
   "files": [
     "index.js",