@blamejs/core 0.9.45 → 0.9.49

package/lib/metrics.js

@@ -853,18 +853,43 @@ function snapshotRead(p) {
  * Format a snapshot object for human or machine consumption.
  *
  *   format: "text"       — operator-readable lines, one field per row (default)
- *   format: "prometheus" — Prometheus 0.0.4 text format, gauge metrics
- *                          named with a configurable prefix; only top-level
- *                          numeric fields under `snap.fields` are emitted
+ *   format: "prometheus" — Prometheus 0.0.4 text format
+ *
+ * ## Type detection (`prometheus` format only)
+ *
+ * Per Prometheus naming convention + OpenMetrics 1.0.0 §6.2, counter
+ * metric families MUST carry the `_total` suffix; every other numeric
+ * field renders as a gauge. The renderer auto-detects by suffix:
+ *
+ *   - field name ends in `_total` → `# TYPE <name> counter`
+ *   - everything else             → `# TYPE <name> gauge`
+ *
+ * Operators with metrics that don't fit the convention (e.g. a counter
+ * named `bytes_sent` without the `_total` suffix, or a gauge that
+ * happens to end in `_total`) opt the right type via `opts.fieldTypes`:
+ *
+ *   render(snap, { format: "prometheus", fieldTypes: {
+ *     bytes_sent: "counter",     // override default gauge
+ *     ratio_total: "gauge",       // override default counter
+ *   }});
+ *
+ * Pre-v0.9.47 every field rendered as gauge regardless of name, which
+ * broke `rate()` queries against counter-shaped series. Operators
+ * scraping a long-running deployment will see `rate(*_total[5m])`
+ * queries start returning the right answer once the new types reach
+ * the scrape target.
  *
  * @opts
- *   format:  "text" | "prometheus",   // default: "text"
- *   prefix:  string,                   // prometheus-only; default: "blamejs"
+ *   format:      "text" | "prometheus",   // default: "text"
+ *   prefix:      string,                   // prometheus-only; default: "blamejs"
+ *   fieldTypes:  Object,                   // prometheus-only; per-field type override
+ *                                          // map. Values: "counter" | "gauge".
  *
  * @example
  *   var snap = b.metrics.snapshot.read("/run/blamejs/metrics.json");
  *   process.stdout.write(b.metrics.snapshot.render(snap));
- *   // or for Prometheus scraping:
+ *   // or for Prometheus scraping (auto-detects http_requests_total
+ *   // as a counter via the _total suffix):
  *   res.setHeader("Content-Type", "text/plain; version=0.0.4");
  *   res.end(b.metrics.snapshot.render(snap, { format: "prometheus", prefix: "myapp" }));
  */
@@ -899,6 +924,11 @@ function snapshotRender(snap, opts) {
       throw new MetricsError("metrics-snapshot/bad-prefix",
         "metrics.snapshot.render: prometheus prefix must match [a-zA-Z_][a-zA-Z0-9_]*, got '" + prefix + "'");
     }
+    var fieldTypes = opts.fieldTypes || {};
+    if (typeof fieldTypes !== "object" || fieldTypes === null || Array.isArray(fieldTypes)) {
+      throw new MetricsError("metrics-snapshot/bad-field-types",
+        "metrics.snapshot.render: opts.fieldTypes must be an object mapping field-name → 'counter' | 'gauge'");
+    }
     var out = [];
     // allow:bare-canonicalize-walk — sort is for stable Prometheus
     // exposition output ordering, not canonicalize-for-hashing
@@ -909,7 +939,20 @@ function snapshotRender(snap, opts) {
       if (typeof v2 !== "number" || !isFinite(v2)) continue;   // only numeric scalars
       if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(k2)) continue;       // skip prom-incompatible names
       var metric = prefix + "_" + k2;
-      out.push("# TYPE " + metric + " gauge");
+      var declared = fieldTypes[k2];
+      var fieldType;
+      if (declared !== undefined) {
+        if (declared !== "counter" && declared !== "gauge") {
+          throw new MetricsError("metrics-snapshot/bad-field-type",
+            "metrics.snapshot.render: opts.fieldTypes." + k2 + " must be 'counter' or 'gauge', got '" + declared + "'");
+        }
+        fieldType = declared;
+      } else {
+        // Prometheus naming convention + OpenMetrics 1.0.0 §6.2:
+        // counter family names carry the _total suffix.
+        fieldType = /_total$/.test(k2) ? "counter" : "gauge";
+      }
+      out.push("# TYPE " + metric + " " + fieldType);
       out.push(metric + " " + v2);
     }
     return out.join("\n") + "\n";

package/lib/middleware/protected-resource-metadata.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * @module     b.middleware.protectedResourceMetadata
- * @nav        Identity & access
+ * @nav        Identity
  * @title      Protected Resource Metadata
  * @order      210
  * @slug       protected-resource-metadata

package/lib/safe-smtp.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * @module     b.safeSmtp
+ * @nav        Parsers
+ * @title      Safe SMTP
+ * @order      215
+ *
+ * @intro
+ *   Wire-protocol parsing helpers for SMTP (RFC 5321) bytes.
+ *   Operators consuming the framework's MX listener (`b.mail.server.mx`),
+ *   submission listener (slice that follows), or building their own
+ *   SMTP-shaped tooling (proxies, log analyzers, test fixtures) reach
+ *   for these primitives rather than reinventing the dot-terminator
+ *   scan + dot-stuffing reversal.
+ *
+ *   Separates the "what shape is the wire data" parsing concern from
+ *   the "is this wire data hostile" guard concern (which lives in
+ *   `b.guardSmtpCommand`). A safe-* parser primitive returns a
+ *   bounded shape or `-1`; a guard-* primitive returns a boolean
+ *   threat verdict or throws a typed error.
+ *
+ *   Wire-protocol references:
+ *     - RFC 5321 §2.3.8 — line termination MUST be CRLF
+ *     - RFC 5321 §4.5.2 — dot-stuffing on the SMTP body
+ *     - RFC 5321 §4.1.1.4 — DATA command terminates with `<CRLF>.<CRLF>`
+ *     - CVE-2023-51764 / -51765 / -51766 / 2024-32178 — SMTP
+ *       smuggling (parsers that accept bare-LF dot-terminators).
+ *       The guard primitive `b.guardSmtpCommand.detectBodySmuggling`
+ *       owns smuggling detection; the safe-* terminator scanner
+ *       here is strict CRLF-only by construction.
+ *
+ * @card
+ *   Wire-protocol parsing helpers for SMTP (RFC 5321) bytes —
+ *   findDotTerminator + dotUnstuff. Strict CRLF-only by construction
+ *   (bare-LF terminators are not honored — the smuggling-detection
+ *   guard lives in b.guardSmtpCommand.detectBodySmuggling).
+ */
+
+var { defineClass } = require("./framework-error");
+
+var SafeSmtpError = defineClass("SafeSmtpError", { alwaysPermanent: true });
+
+/**
+ * @primitive b.safeSmtp.findDotTerminator
+ * @signature b.safeSmtp.findDotTerminator(buf)
+ * @since     0.9.46
+ * @status    stable
+ * @related   b.safeSmtp.dotUnstuff, b.guardSmtpCommand.detectBodySmuggling
+ *
+ * Scan `buf` for the canonical RFC 5321 §4.1.1.4 DATA-body terminator
+ * `<CRLF>.<CRLF>` (5 bytes: 0x0d 0x0a 0x2e 0x0d 0x0a). Returns the
+ * byte index where the body ends (exclusive — the index of the
+ * trailing CRLF the terminator starts on), or `-1` if the terminator
+ * is not yet present.
+ *
+ * Strict CRLF-only by construction — bare-LF alternate terminators
+ * are NOT honored. Operators worried about smuggling shape route the
+ * SAME body through `b.guardSmtpCommand.detectBodySmuggling` before
+ * trusting the terminator index returned here.
+ *
+ * @example
+ *   var body = Buffer.from("Hello world.\r\n.\r\n");
+ *   b.safeSmtp.findDotTerminator(body);
+ *   // → 13  (index of \r in \r\n.\r\n)
+ *
+ *   b.safeSmtp.findDotTerminator(Buffer.from("incomplete body"));
+ *   // → -1
+ */
+function findDotTerminator(buf) {
+  if (!Buffer.isBuffer(buf)) {
+    throw new SafeSmtpError("safe-smtp/bad-input",
+      "findDotTerminator: input must be a Buffer");
+  }
+  for (var i = 0; i <= buf.length - 5; i += 1) {                                                     // allow:raw-byte-literal — 5-byte CRLF.CRLF terminator length
+    if (buf[i] === 0x0d && buf[i + 1] === 0x0a &&
+        buf[i + 2] === 0x2e &&
+        buf[i + 3] === 0x0d && buf[i + 4] === 0x0a) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+/**
+ * @primitive b.safeSmtp.dotUnstuff
+ * @signature b.safeSmtp.dotUnstuff(buf)
+ * @since     0.9.46
+ * @status    stable
+ * @related   b.safeSmtp.findDotTerminator
+ *
+ * Reverse RFC 5321 §4.5.2 dot-stuffing on a DATA-body buffer. SMTP
+ * senders that need to transmit a body line beginning with `.` MUST
+ * prepend an extra `.` (so the line on the wire begins with `..`);
+ * the receiver strips the leading `.` from any body line that
+ * begins with one before storing the message. Returns a fresh
+ * Buffer with the dots reversed; the input is never mutated. Result
+ * length is always `<= input length`.
+ *
+ * @example
+ *   var wire = Buffer.from("hello\r\n..secret\r\nworld\r\n");
+ *   b.safeSmtp.dotUnstuff(wire).toString("utf8");
+ *   // → "hello\r\n.secret\r\nworld\r\n"
+ */
+function dotUnstuff(buf) {
+  if (!Buffer.isBuffer(buf)) {
+    throw new SafeSmtpError("safe-smtp/bad-input",
+      "dotUnstuff: input must be a Buffer");
+  }
+  var out = Buffer.alloc(buf.length);
+  var oi = 0;
+  for (var i = 0; i < buf.length; i += 1) {
+    out[oi++] = buf[i];
+    // After \r\n, if the next byte is `.` followed by another non-CR
+    // byte (i.e., not the terminator itself), strip the stuffing dot.
+    if (i >= 1 && buf[i - 1] === 0x0d && buf[i] === 0x0a &&
+        i + 1 < buf.length && buf[i + 1] === 0x2e &&
+        i + 2 < buf.length && buf[i + 2] !== 0x0d) {
+      i += 1;
+    }
+  }
+  return out.subarray(0, oi);
+}
+
+module.exports = {
+  findDotTerminator: findDotTerminator,
+  dotUnstuff:        dotUnstuff,
+  SafeSmtpError:     SafeSmtpError,
+};

package/lib/self-update.js

@@ -86,14 +86,41 @@ function _safeAuditEmit(action, outcome, metadata) {
 }
 
 // ---- semver-shaped comparison (tag_name like "v0.7.30" or "0.7.30") ----
-// Strips a leading "v" / "V" then parses dot-separated numeric components.
-// Non-numeric components are compared lexicographically (handles release
-// suffixes like "1.0.0-rc.1" by falling back to string comparison after
-// the matching numeric prefix). Returns -1 / 0 / +1.
 function _normalizeTag(tag) {
   if (typeof tag !== "string") return "";
   return tag.replace(/^v/i, "").trim();
 }
+
+/**
+ * @primitive b.selfUpdate.compareTags
+ * @signature b.selfUpdate.compareTags(a, b)
+ * @since     0.9.47
+ * @status    stable
+ *
+ * Compare two release tags / version strings. Returns `-1` if `a < b`,
+ * `+1` if `a > b`, `0` if equal. Strips a leading `v` / `V`, then walks
+ * dot-separated components: numeric pairs compared numerically; any
+ * non-numeric component (release suffixes like `1.0.0-rc.1`) falls back
+ * to lexicographic compare on that component. Missing components on
+ * either side are treated as `"0"`.
+ *
+ * Shape follows SemVer 2.0.0 §11 precedence rules for the numeric prefix.
+ * Deviations from the full SemVer §11 spec — pre-release identifiers
+ * (`-rc.1` < release) are compared lexicographically rather than the
+ * SemVer-mandated "alphanumeric identifiers compared as numbers if all
+ * numeric" rule. For most version-shaped strings the result is identical;
+ * exotic pre-release shapes (`1.0.0-alpha.10` vs `1.0.0-alpha.9`) sort
+ * lexicographically here (`10` < `9` as strings) rather than numerically.
+ * Operators with strict SemVer §11 needs should use a dedicated SemVer
+ * parser; this primitive targets the common framework-update polling
+ * shape (`v0.9.46` vs `v0.9.47`) where pre-release tags are rare.
+ *
+ * @example
+ *   b.selfUpdate.compareTags("v0.9.46", "v0.9.47");   // → -1
+ *   b.selfUpdate.compareTags("v0.9.47", "0.9.47");    // → 0  (leading "v" stripped)
+ *   b.selfUpdate.compareTags("1.10.0",  "1.9.0");     // → +1 (numeric, not lex)
+ *   b.selfUpdate.compareTags("v0.7.30", "v0.7.30");   // → 0
+ */
 function _compareTags(a, b) {
   var na = _normalizeTag(a);
   var nb2 = _normalizeTag(b);
@@ -648,6 +675,10 @@ module.exports = {
   SelfUpdateError:       SelfUpdateError,
   ALLOWED_HASH_ALGS:     ALLOWED_HASH_ALGS,
   DEFAULT_HASH_ALG:      DEFAULT_HASH_ALG,
+  // Public surface — same impl as the internal `_compareTags`;
+  // downstream consumers replacing one-off compareVersions helpers
+  // call this.
+  compareTags:           _compareTags,
   // Internal — exposed for the layer-0 test suite only.
   _compareTags:          _compareTags,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.9.45",
+  "version": "0.9.49",
   "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:b87538c7-3bfe-497b-aa53-9191876a4e1f",
+  "serialNumber": "urn:uuid:21323cdb-5bfe-4b88-a63f-906795a497e6",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-15T19:42:01.531Z",
+    "timestamp": "2026-05-16T03:34:31.380Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.9.45",
+      "bom-ref": "@blamejs/core@0.9.49",
       "type": "library",
       "name": "blamejs",
-      "version": "0.9.45",
+      "version": "0.9.49",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.9.45",
+      "purl": "pkg:npm/%40blamejs/core@0.9.49",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.9.45",
+      "ref": "@blamejs/core@0.9.49",
       "dependsOn": []
     }
   ]