@blamejs/core 0.10.6 → 0.10.8

package/lib/safe-mime.js

@@ -53,7 +53,15 @@ var DEFAULT_MAX_PARTS         = 64;                          // allow:raw-byte-l
 var DEFAULT_MAX_NESTING_DEPTH = 16;
 var DEFAULT_MAX_BOUNDARY      = 70;                          // RFC 2046 §5.1.1
 var DEFAULT_MAX_HEADER_BYTES  = C.BYTES.kib(64);
-var DEFAULT_MAX_HEADER_LINE   = 998;                         // allow:raw-byte-literal — RFC 5322 §2.1.1 line cap
+// RFC 5322 §2.1.1 line cap. The spec defines TWO limits: a SHOULD of
+// 78 bytes (the readability target) and a MUST of 998 bytes (the
+// hard ceiling). The 78-byte SHOULD is intentionally NOT enforced
+// here — modern senders routinely emit header lines longer than 78
+// bytes (long URLs in List-Unsubscribe, EAI display names) and a
+// strict 78-byte refusal would reject legitimate mail. We enforce
+// only the 998-byte MUST. Future drift attempting to "fix" this to
+// 78 would be a regression and should fail the audit gate.
+var DEFAULT_MAX_HEADER_LINE   = 998;                         // allow:raw-byte-literal — RFC 5322 §2.1.1 MUST (998); the SHOULD (78) is by design not enforced
 // Per-message header-count cap. RFC 5322 places no upper bound on
 // the number of headers in a message; without one, a sender can pack
 // tens of thousands of one-byte headers into the maxHeaderBytes budget
@@ -77,8 +85,15 @@ var DEFAULT_CHARSETS = Object.freeze([
   "euc-kr", "euc-jp",
 ]);
 
+// RFC 3030 §3 — `binary` CTE on receive REQUIRES the receiving MTA
+// to have advertised BINARYMIME during ESMTP negotiation. Inbound
+// flows without explicit BINARYMIME wiring must refuse `binary`
+// because consumers downstream (DKIM canonicalization, message
+// rewriting) assume CRLF line structure that `binary` doesn't
+// guarantee. Operators that wire BINARYMIME end-to-end opt back in
+// via `transferEncodingAllowlist: ["7bit", ..., "binary"]`.
 var DEFAULT_TRANSFER_ENCODINGS = Object.freeze([
-  "7bit", "8bit", "binary", "quoted-printable", "base64",
+  "7bit", "8bit", "quoted-printable", "base64",
 ]);
 
 /**
@@ -453,12 +468,18 @@ function _parseHeaders(buf, ctx) {
     // Refuse NUL, CR, LF, and other C0 control chars in header values.
     // Tab (0x09) is allowed (header folding). C1 control range
     // (0x80-0x9F) NOT refused — legitimate non-ASCII via EAI/RFC 2047
-    // decoded-words can produce bytes in that range.
+    // decoded-words can produce bytes in that range. Error metadata
+    // surfaces the BYTE offset (via `Buffer.byteLength` on the JS
+    // string prefix) rather than the UTF-16 code-unit index, so the
+    // operator audit log lines up with the wire-level byte stream
+    // they're inspecting.
     for (var hci = 0; hci < value.length; hci += 1) {
       var hcc = value.charCodeAt(hci);
       if ((hcc < 0x20 && hcc !== 0x09) || hcc === 0x7F) {                                          // allow:raw-byte-literal — C0 control char + DEL refusal
+        var byteOffset = Buffer.byteLength(value.slice(0, hci), "utf8");
         throw new SafeMimeError("safe-mime/control-char-in-header",
-          "safeMime.parse: header '" + name + "' contains control char 0x" + hcc.toString(16));
+          "safeMime.parse: header '" + name + "' contains control char 0x" +
+          hcc.toString(16) + " at byte offset " + byteOffset);                                            // allow:raw-byte-literal — toString radix 16 hex, not bytes
       }
     }
     value = _decodeRfc2047Words(value);
@@ -673,9 +694,35 @@ function _decodeBufferAs(buf, charset) {
   if (c === "us-ascii" || c === "ascii") return buf.toString("ascii");
   if (c === "iso-8859-1" || c === "latin1") return buf.toString("latin1");
   if (c === "utf-16le") return buf.toString("utf16le");
+  if (c === "utf-16be") return _decodeUtf16BE(buf);
+  if (c === "utf-16") {
+    // RFC 2781 §3.3 — `utf-16` with a leading BOM (FE FF = BE, FF FE
+    // = LE). When no BOM is present the spec defaults to BE; Node
+    // doesn't speak BE natively so we transcode either way.
+    if (buf.length >= 2 && buf[0] === 0xff && buf[1] === 0xfe) {
+      return buf.subarray(2).toString("utf16le");
+    }
+    if (buf.length >= 2 && buf[0] === 0xfe && buf[1] === 0xff) {
+      return _decodeUtf16BE(buf.subarray(2));
+    }
+    return _decodeUtf16BE(buf);   // RFC 2781 §3.3 BE default with no BOM
+  }
   return buf.toString("utf8");
 }
 
+// utf-16be → utf-16le swap (Node has no direct utf-16be decoder).
+// Byte-pair endian flip into a temporary buffer, then decode as
+// utf-16le. Allocates a single buffer (no per-character churn).
+function _decodeUtf16BE(buf) {
+  var n = buf.length & ~1;                                                                                // allow:raw-byte-literal — pair alignment mask
+  var swapped = Buffer.alloc(n);
+  for (var i = 0; i < n; i += 2) {
+    swapped[i]     = buf[i + 1];
+    swapped[i + 1] = buf[i];
+  }
+  return swapped.toString("utf16le");
+}
+
 function _materializeText(part) {
   return {
     contentType: part.leaf.contentType,

package/lib/sd-notify.js

@@ -0,0 +1,269 @@
+"use strict";
+/**
+ * @module b.sdNotify
+ * @nav    Process
+ * @title  systemd Notify
+ *
+ * @intro
+ *   `sd_notify` protocol surface for daemons running under
+ *   `Type=notify` systemd units. Composes the standard lifecycle
+ *   messages — `READY=1` on boot, `WATCHDOG=1` on heartbeat,
+ *   `STOPPING=1` on shutdown, `RELOADING=1` on hot-reload — against
+ *   the `$NOTIFY_SOCKET` env var systemd populates for the child
+ *   process.
+ *
+ *   Transport: Node has no unix-DGRAM socket support in its `dgram`
+ *   module, so the v1 path shells out to `systemd-notify(1)` via
+ *   `execFile` (NOT `exec` — no shell-string parsing on the
+ *   message bytes). Operators running under systemd already have
+ *   `systemd-tools` installed by definition, so the dependency is
+ *   no expansion of the trust surface.
+ *
+ *   Compose with `b.appShutdown` for the STOPPING signal: register a
+ *   priority-0 phase that calls `b.sdNotify.stopping()` so systemd
+ *   sees the shutdown intent before the framework tears anything
+ *   down. Compose with a periodic `WATCHDOG=1` against the unit's
+ *   `WatchdogSec=` interval so systemd auto-restarts the daemon if
+ *   the event loop wedges.
+ *
+ *   When `$NOTIFY_SOCKET` is unset (process running outside systemd
+ *   — bare invocation, foreground dev, container without
+ *   `--notify-ready`), every call is a no-op that surfaces a single
+ *   boot-time audit entry. Operators get observability of the
+ *   degraded state without per-call log noise.
+ *
+ * @card
+ *   sd_notify protocol for systemd Type=notify daemons — READY / WATCHDOG / STOPPING / RELOADING. Composes b.appShutdown for shutdown signaling.
+ */
+
+var { execFile } = require("node:child_process");
+var C = require("./constants");
+var safeEnv = require("./parsers/safe-env");
+var audit = require("./audit");
+var { defineClass } = require("./framework-error");
+
+var SdNotifyError = defineClass("SdNotifyError", { alwaysPermanent: true });
+
+// Whitelist of sd_notify state= values we ship as named helpers. The
+// underlying `send({ state })` accepts any string but the helpers are
+// the operator-facing surface — `READY=1` etc. — and the audit log
+// records the named state, not arbitrary payload bytes.
+var KNOWN_STATES = Object.freeze({
+  ready:     "READY=1",
+  stopping:  "STOPPING=1",
+  reloading: "RELOADING=1",
+  watchdog:  "WATCHDOG=1",
+});
+
+function _notifySocketPath() {
+  var p = safeEnv.readVar("NOTIFY_SOCKET");
+  if (typeof p !== "string" || p.length === 0) return null;
+  // Abstract namespace socket (Linux-only) prefixed with `@` —
+  // systemd-notify(1) accepts the same form, so we don't normalize.
+  return p;
+}
+
+function _runNotify(payload) {
+  return new Promise(function (resolve, reject) {
+    var args = [];
+    var lines = String(payload).split("\n");
+    for (var i = 0; i < lines.length; i += 1) {
+      if (lines[i].length > 0) args.push(lines[i]);
+    }
+    if (args.length === 0) { resolve(); return; }
+    // execFile (not exec) — no shell evaluation; the message bytes
+    // pass through argv exactly. systemd-notify accepts one or more
+    // KEY=VALUE arguments. The `--no-block` flag returns immediately
+    // without waiting for the notification to be processed.
+    execFile("systemd-notify", ["--no-block"].concat(args),
+      { timeout: C.TIME.seconds(5), windowsHide: true },
+      function (err) {
+        if (err) reject(err);
+        else resolve();
+      });
+  });
+}
+
+/**
+ * @primitive b.sdNotify.send
+ * @signature b.sdNotify.send(opts)
+ * @since     0.10.8
+ * @status    stable
+ * @related   b.sdNotify.ready, b.sdNotify.stopping, b.appShutdown.create
+ *
+ * Generic sd_notify dispatch. Sends one or more `KEY=VALUE` payload
+ * lines to systemd via `systemd-notify(1)`. No-op when
+ * `$NOTIFY_SOCKET` is unset (foreground / container without
+ * `--notify-ready` / non-systemd init). Returns a Promise resolving
+ * on dispatch success.
+ *
+ * @opts
+ *   state:    string,                     // e.g. "READY=1" / "STOPPING=1"
+ *   status:   string,                     // free-form status text → `STATUS=`
+ *   mainpid:  number,                     // PID override → `MAINPID=`
+ *   audit:    boolean,                     // default true
+ *
+ * @example
+ *   await b.sdNotify.send({ state: "READY=1", status: "Listening on :8080" });
+ */
+function send(opts) {
+  opts = opts || {};
+  var lines = [];
+  if (typeof opts.state === "string" && opts.state.length > 0) lines.push(opts.state);
+  if (typeof opts.status === "string" && opts.status.length > 0) {
+    // STATUS= permits arbitrary UTF-8 except newline — refuse newline
+    // so a hostile status string can't smuggle a second key.
+    if (opts.status.indexOf("\n") !== -1 || opts.status.indexOf("\r") !== -1) {
+      throw new SdNotifyError("sd-notify/control-char-in-status",
+        "send: status field must not contain CR/LF (sd_notify framing)");
+    }
+    lines.push("STATUS=" + opts.status);
+  }
+  if (opts.mainpid !== undefined) {
+    if (typeof opts.mainpid !== "number" || !isFinite(opts.mainpid) ||
+        Math.floor(opts.mainpid) !== opts.mainpid || opts.mainpid < 1) {
+      throw new SdNotifyError("sd-notify/bad-mainpid",
+        "send: mainpid must be a positive integer");
+    }
+    lines.push("MAINPID=" + opts.mainpid);
+  }
+  if (lines.length === 0) return Promise.resolve();
+
+  var socketPath = _notifySocketPath();
+  if (socketPath === null) {
+    if (opts.audit !== false) {
+      try {
+        audit.safeEmit({
+          action:   "sdnotify.send.skipped",
+          outcome:  "denied",
+          metadata: { reason: "no-notify-socket", state: opts.state || null },
+        });
+      } catch (_e) { /* drop-silent */ }
+    }
+    return Promise.resolve();
+  }
+  var auditOn = opts.audit !== false;
+  return _runNotify(lines.join("\n")).then(function () {
+    if (auditOn) {
+      try {
+        audit.safeEmit({
+          action:   "sdnotify.send",
+          outcome:  "success",
+          metadata: { state: opts.state || null, status: opts.status || null },
+        });
+      } catch (_e) { /* drop-silent */ }
+    }
+  }).catch(function (err) {
+    if (auditOn) {
+      try {
+        audit.safeEmit({
+          action:   "sdnotify.send",
+          outcome:  "failure",
+          metadata: { state: opts.state || null, error: (err && err.message) || String(err) },
+        });
+      } catch (_e2) { /* drop-silent */ }
+    }
+    throw new SdNotifyError("sd-notify/dispatch-failed",
+      "send: systemd-notify dispatch failed: " + ((err && err.message) || String(err)));
+  });
+}
+
+/**
+ * @primitive b.sdNotify.ready
+ * @signature b.sdNotify.ready(opts?)
+ * @since     0.10.8
+ * @status    stable
+ * @related   b.sdNotify.send, b.sdNotify.stopping
+ *
+ * Send `READY=1` to systemd, signaling boot complete. Use once the
+ * listener is bound and the daemon is accepting work.
+ *
+ * @opts
+ *   status:  string,    // free-form status text → STATUS=
+ *
+ * @opts
+ *   status:  string,    // free-form status text → STATUS=
+ *   audit:   boolean,    // default true
+ *
+ * @example
+ *   await b.sdNotify.ready({ status: "Listening on :8080" });
+ */
+function ready(opts) {
+  return send(Object.assign({}, opts || {}, { state: KNOWN_STATES.ready }));
+}
+
+/**
+ * @primitive b.sdNotify.stopping
+ * @signature b.sdNotify.stopping(opts?)
+ * @since     0.10.8
+ * @status    stable
+ * @related   b.sdNotify.send, b.appShutdown.create
+ *
+ * Send `STOPPING=1`. Operators wire this into `b.appShutdown` as the
+ * earliest shutdown phase (priority 0) so systemd sees the shutdown
+ * intent before any teardown begins.
+ *
+ * @opts
+ *   status:  string,    // free-form status text → STATUS=
+ *   audit:   boolean,    // default true
+ *
+ * @example
+ *   b.appShutdown.create({ name: "sd-notify-stopping", priority: 0,
+ *     run: function () { return b.sdNotify.stopping(); } });
+ */
+function stopping(opts) {
+  return send(Object.assign({}, opts || {}, { state: KNOWN_STATES.stopping }));
+}
+
+/**
+ * @primitive b.sdNotify.reloading
+ * @signature b.sdNotify.reloading(opts?)
+ * @since     0.10.8
+ * @status    stable
+ *
+ * Send `RELOADING=1` then (after the reload completes) `READY=1`.
+ * Use during hot-config-reload paths; systemd treats the unit as
+ * "reloading" until the next `READY=1`.
+ *
+ * @opts
+ *   status:  string,    // free-form status text → STATUS=
+ *   audit:   boolean,    // default true
+ *
+ * @example
+ *   await b.sdNotify.reloading();
+ *   await reloadConfig();
+ *   await b.sdNotify.ready();
+ */
+function reloading(opts) {
+  return send(Object.assign({}, opts || {}, { state: KNOWN_STATES.reloading }));
+}
+
+/**
+ * @primitive b.sdNotify.watchdog
+ * @signature b.sdNotify.watchdog(opts?)
+ * @since     0.10.8
+ * @status    stable
+ *
+ * Send `WATCHDOG=1`. Operators with `WatchdogSec=` configured on
+ * their unit call this periodically (e.g. every `WatchdogSec/2`)
+ * so systemd auto-restarts the daemon when the event loop wedges.
+ *
+ * @opts
+ *   audit:   boolean,    // default true
+ *
+ * @example
+ *   setInterval(function () { b.sdNotify.watchdog(); }, 15000);
+ */
+function watchdog(opts) {
+  return send(Object.assign({}, opts || {}, { state: KNOWN_STATES.watchdog }));
+}
+
+module.exports = {
+  send:          send,
+  ready:         ready,
+  stopping:      stopping,
+  reloading:     reloading,
+  watchdog:      watchdog,
+  isAvailable:   function () { return _notifySocketPath() !== null; },
+  SdNotifyError: SdNotifyError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.10.6",
+  "version": "0.10.8",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.6",
-  "serialNumber": "urn:uuid:eeaab12e-3641-448e-8bad-29a2842f802b",
+  "serialNumber": "urn:uuid:2db3bd59-b835-4672-aac5-7c874f2f9276",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-17T18:41:38.896Z",
+    "timestamp": "2026-05-18T00:17:19.942Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.10.6",
+      "bom-ref": "@blamejs/core@0.10.8",
       "type": "library",
       "name": "blamejs",
-      "version": "0.10.6",
+      "version": "0.10.8",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.10.6",
+      "purl": "pkg:npm/%40blamejs/core@0.10.8",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.10.6",
+      "ref": "@blamejs/core@0.10.8",
       "dependsOn": []
     }
   ]