@blamejs/core 0.8.13 → 0.8.16

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.13",
+  "version": "0.8.16",
   "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",

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:52762d7e-86ab-4e69-9636-eacc1acc2d2d",
+  "serialNumber": "urn:uuid:9d91dfe3-4449-4315-ac6c-d78f5dd92d0c",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-07T04:52:07.494Z",
+    "timestamp": "2026-05-07T07:18:43.056Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.8.13",
+      "bom-ref": "@blamejs/core@0.8.16",
       "type": "library",
       "name": "blamejs",
-      "version": "0.8.13",
+      "version": "0.8.16",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.8.13",
+      "purl": "pkg:npm/%40blamejs/core@0.8.16",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.8.13",
+      "ref": "@blamejs/core@0.8.16",
       "dependsOn": []
     }
   ]