@blamejs/core 0.16.8 → 0.16.9

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.16.x
 
+- v0.16.9 (2026-07-10) — **`b.safeBuffer.quoteString` — one RFC quoted-string serializer behind eight header and protocol emitters — plus a consolidated per-primitive test suite and a static gate that refuses a documented primitive no test references.** Eight places in the framework serialized an RFC quoted-string by hand — escape backslash and DQUOTE, wrap in DQUOTEs — for Cache-Status and Signature-Input sf-strings, Link header parameters, Authentication-Results reason, IMAP quoted strings and METADATA values, ManageSieve responses, and Server-Timing descriptions. Those copies are consolidated into one primitive, b.safeBuffer.quoteString, so an unescaped quote can never terminate a string early and smuggle extra parameters into a protocol line, and the escaping cannot drift between emitters. Output is byte-identical to before. The test suite is reorganized so every primitive's tests live in a canonical per-primitive file (thirty-eight auxiliary files folded or renamed; every assertion preserved — the full suite passes with the exact same check count). On top of that reorganization, the comment-block validator gains a primitive-without-test check: a documented @primitive that no test references — neither the full dotted form nor its namespace plus a method invocation — now fails the static gate. One hundred six existing primitives currently lack any test reference; they are recorded in an explicit shrink-only register in the validator, each entry an open test-backfill item, and the gate refuses any new primitive shipping untested. **Added:** *b.safeBuffer.quoteString — RFC quoted-string serialization* — Coerces to string, escapes every backslash and DQUOTE with a leading backslash, and wraps the result in DQUOTEs — the quoted-string grammar shared by RFC 8941 §3.3.3 Structured Fields sf-string, RFC 8288 Link header parameters, RFC 8601 §2.2 Authentication-Results reason, RFC 3501 §4.3 IMAP quoted strings, and RFC 5804 §1.2 ManageSieve strings. Escaping only: a grammar with a restricted character range (sf-string is printable-ASCII; IMAP quoted strings cannot carry CR/LF) enforces its range check before calling it. · *Static gate: a documented primitive must be referenced by a test* — The comment-block validator now scans the test corpus for every @primitive: the full dotted form (b.namespace.method) anywhere under test/, or the namespace / owning module referenced together with the method invoked in the same test file — the same-file rule stops a ubiquitous method name like .create( in an unrelated test from counting as coverage. A primitive with no reference fails the pre-push static gate. One hundred six existing primitives currently have no reference; they are listed in a shrink-only register inside the validator — each entry an open test-backfill item that is deleted when its test lands — and a new primitive cannot ship untested. **Changed:** *Eight quoted-string emitters route through the one serializer* — Cache-Status key/detail, Signature-Input sf-strings, Link header parameter values, Authentication-Results reason, IMAP METADATA values and quoted strings, ManageSieve OK/NO/BYE/LISTSCRIPTS responses, and Server-Timing desc now compose b.safeBuffer.quoteString instead of hand-rolling the escape. Emitted bytes are unchanged. · *Per-primitive canonical test files* — Thirty-eight auxiliary test files are folded into (or renamed to) their primitive's canonical test file — one file per primitive domain, concern-named splits kept (e.g. http-client-cache / -stream / -throttle). No assertion was changed, added, or removed by the reorganization; the full suite passes with the exact same check count before and after. The b.*-surface reference gate that previously ran inside the smoke suite is superseded by the stronger validator check above. **Detectors:** *rfc-quoted-string-escape-owned-by-safeBuffer* — Flags an inline backslash-then-DQUOTE escape chain in lib/ outside the primitive's home — the quoted-string serializer re-implemented, whose escaping can drift from the canonical one. While being proven against the pre-consolidation tree it caught an eighth emitter the manual sweep had missed (an IMAP response-literal helper), which is consolidated in this release too.
+
 - v0.16.8 (2026-07-10) — **`b.metrics.snapshot.render` now emits the labeled registry — counters, gauges and histogram buckets with their label sets — matching the live exposition endpoint byte-for-byte, plus a Public Suffix List refresh and supply-chain pin maintenance.** A snapshot written with b.metrics.snapshot.startWriter's registry option always carried the full labeled registry in its metrics field, but b.metrics.snapshot.render ignored that field: the prometheus format emitted only the flat numeric fields, so a sidecar wanting a complete /metrics exposition of labeled series had to re-implement label-value escaping and bucketed line formatting itself. Both render formats now emit the labeled series. The prometheus output is produced by the same family encoder the live exposition() endpoint uses — one encoder now backs the live exposition, the shadow registry and snapshot rendering — so series names and escaping are identical whichever source a scraper reads. Snapshot files are parsed defensively: a malformed family, a non-Prometheus metric or label name, or a non-numeric sample in a hand-edited snapshot file is dropped rather than rendered, so a tampered file cannot forge exposition lines. Separately, twelve documentation examples opened with require("blamejs").create(), a factory the export does not have; the examples are corrected and the @example-execution test no longer supplies a substitute create(), so any future example calling a method the shipped export lacks fails the suite. The vendored Public Suffix List is refreshed to the 2026-07-09 upstream revision, and the CI toolchain pins (github/codeql-action, the ClusterFuzzLite base-builder digest) are brought current. **Changed:** *One shared Prometheus family encoder behind every exposition surface* — The live registry exposition(), the shadow registry's prometheus render and the new snapshot rendering now share a single labeled-sample encoder (label ordering, value escaping, histogram bucket lines). Output of the existing surfaces is unchanged, including the guarantee that a label literally named constructor / prototype / __proto__ survives rendering. · *Public Suffix List refreshed to the 2026-07-09 upstream revision* — The vendored, signature-verified Public Suffix List bundle is rebuilt from the current upstream publication (previously 2026-07-02). This keeps DMARC / BIMI organizational-domain alignment and cookie-scope decisions current with registry changes. · *CI toolchain pins brought current* — github/codeql-action is pinned to v4.37.0 across the CodeQL and Scorecard workflows in one change (its init / analyze / upload-sarif sub-actions must move together — mixed versions break the CodeQL analysis run), and Dependabot now groups codeql-action updates into a single pull request. The ClusterFuzzLite base-builder image digest is bumped to the current upstream publication, with the oss-fuzz submission mirror kept in sync. **Fixed:** *b.metrics.snapshot.render emits the labeled registry from snap.metrics (#430)* — Snapshots written with startWriter's registry option carry every registered counter / gauge / histogram — label sets and bucket counts — in a structured metrics field, but render() only emitted the flat numeric fields. The prometheus format now renders those families with the same labeled / bucketed sample lines (name{label="value"} n, name_bucket{le=…}, name_sum, name_count) the live exposition() endpoint serves, family names verbatim rather than prefix-qualified, so dashboards see one series name regardless of scrape source; the text format lists each labeled sample as a name{label="value"} row. Malformed families, non-Prometheus metric / label names, and non-numeric samples in a snapshot file are dropped rather than rendered, so a hand-edited file cannot forge exposition lines. · *Twelve documentation examples no longer call a nonexistent create() factory* — @example blocks in b.a2a, b.cloudEvents, b.pqcSoftware and b.tlsExporter opened with var b = require("blamejs").create(), but the top-level export has no create() — copying those examples threw a TypeError on the first line. The examples now open with var b = require("blamejs"). The @example-execution test previously supplied a substitute create() to the examples' require, which masked exactly this drift; the substitute is removed, so an example calling any method the shipped export lacks now fails the suite. **Detectors:** *prometheus-exposition-escape-owned-by-metrics* — Flags a hand-rolled Prometheus escape chain (backslash-doubling plus newline escaping) outside lib/metrics.js — the signature of a second exposition encoder growing whose escaping can drift from the canonical one. The two-step backslash+quote escapes used by RFC quoted-string wire formats (sf-string, IMAP, Sieve, Link header) are out of scope.
 
 - v0.16.7 (2026-07-06) — **Restore two APIs that silently didn't work — the Clear-Site-Data header helper and data-subject export — and correct five documentation examples, all surfaced by a new test that executes every JSDoc @example end-to-end.** The comment-block validator only ever PARSE-checked each documentation @example, so an example could compile and still be dead — calling a method that no longer exists, passing an option the API rejects, or misreading a return shape. A new test now EXECUTES every self-contained @example against the real framework, and on its first run it caught two genuine framework defects plus five stale examples. b.middleware.clearSiteData.headerValue (documented @status stable since 0.15.9) was unreachable: the middleware export was a bare factory that never carried the headerValue helper (nor KNOWN_TYPES / DEFAULT_TYPES), so calling it threw — it is now attached to the export, mirroring b.middleware.idempotencyKey. b.subject.export / b.subject.exportData returned undefined instead of the documented empty object when no data-subject tables are declared, so an operator running an export before tagging any subjectField column got undefined and crashed on the first property access — it now returns {}. Five @example blocks are corrected to runnable code (b.guardRegex.gate's return usage; the invalid title option on b.openapi.create / b.asyncapi.create, which belongs under info; b.retention.complianceFloor; b.safeSchema.object). No security surface changes. **Added:** *JSDoc @example execution validation* — A new test executes every self-contained JSDoc @example against the real framework — not just parse-checks it — so an example that references a renamed or removed method, passes an option the API rejects, or misreads a return shape now fails the suite instead of shipping as dead documentation. Examples with side effects (network, database, filesystem, long-lived work) or that abstract external setup are skipped; the executed set runs in a sandbox with a wall-clock ceiling. **Fixed:** *b.middleware.clearSiteData.headerValue is reachable again* — b.middleware.clearSiteData was exported as a bare factory function, so the advertised b.middleware.clearSiteData.headerValue(types, label?) — plus KNOWN_TYPES and DEFAULT_TYPES — were undefined off the export and threw a TypeError, even though the helper (documented stable since 0.15.9) existed on the module. Those members are now attached to the middleware export, so the documented call works. · *b.subject.export / exportData returns {} when no data-subject tables are declared* — On the no-subject-tables path, export returned the value of its internal audit-write helper — which has no return statement, i.e. undefined — instead of the documented empty dump. An operator running a data-subject export before tagging any subjectField column therefore received undefined and crashed on Object.keys(dump) / dump.<table>. It now returns {} as documented (export and exportData are the same function). · *Five documentation examples corrected to runnable code* — b.guardRegex.gate's example now uses the gate return value correctly; b.openapi.create and b.asyncapi.create examples move title/version under info (title is not a top-level option); and the b.retention.complianceFloor and b.safeSchema.object examples are made self-contained. These are documentation-only corrections.

package/lib/cache-status.js

@@ -34,6 +34,7 @@
  *   RFC 9211 Cache-Status header — documents which intermediate caches handled a request with structured `hit` / `fwd` / `ttl` parameters so operators diagnose cache-decision chains.
  */
 
+var safeBuffer = require("./safe-buffer");
 var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
 
@@ -58,11 +59,6 @@ var BOOLEAN_PARAMS = Object.freeze(["hit", "stored", "collapsed"]);
 // passing other keys get passed-through verbatim as token=value.
 var KNOWN_PARAMS = Object.freeze(["hit", "fwd", "fwd-status", "ttl", "stored", "collapsed", "key", "detail"]);
 
-function _sfStringQuote(s) {
-  // RFC 8941 sf-string — quoted-string with escaping for " and \.
-  // Operator-supplied detail/key strings get the full quote-escape.
-  return "\"" + String(s).replace(/\\/g, "\\\\").replace(/"/g, "\\\"") + "\"";
-}
 
 /**
  * @primitive b.cacheStatus.append
@@ -178,14 +174,14 @@ function entryString(entry) {
       throw new CacheStatusError("cache-status/bad-key",
         "entry.key must be a string when provided");
     }
-    parts.push("key=" + _sfStringQuote(entry.key));
+    parts.push("key=" + safeBuffer.quoteString(entry.key));
   }
   if (entry.detail !== undefined && entry.detail !== null) {
     if (typeof entry.detail !== "string") {
       throw new CacheStatusError("cache-status/bad-detail",
         "entry.detail must be a string when provided");
     }
-    parts.push("detail=" + _sfStringQuote(entry.detail));
+    parts.push("detail=" + safeBuffer.quoteString(entry.detail));
   }
   return parts.join("; ");
 }

package/lib/http-message-signature.js

@@ -104,7 +104,7 @@ function _sfQuotedString(s) {
         "httpSig: parameter string contains non-printable byte at offset " + i);
     }
   }
-  return "\"" + s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"") + "\"";
+  return safeBuffer.quoteString(s);
 }
 
 // _serializeCovered — RFC 9421 §2.5 covered-components list.

package/lib/link-header.js

@@ -29,6 +29,7 @@
  *   parameter never splits the list.
  */
 
+var safeBuffer = require("./safe-buffer");
 var structuredFields = require("./structured-fields");
 var { defineClass } = require("./framework-error");
 
@@ -114,7 +115,7 @@ function parse(headerValue) {
 // common convention (RFC 8288 examples, REST pagination) quotes too.
 function _serParam(name, value) {
   if (value === "" || value === true) return name;            // valueless parameter
-  return name + "=\"" + String(value).replace(/\\/g, "\\\\").replace(/"/g, "\\\"") + "\"";
+  return name + "=" + safeBuffer.quoteString(value);
 }
 
 /**

package/lib/mail-auth.js

@@ -2158,7 +2158,7 @@ function authResultsEmit(opts) {
       // (`\"`). Pre-v0.8.32 the framework collapsed `"` to `'` which
       // is lossy. Use the spec-correct escape so the receiver can
       // round-trip the original reason.
-      clause += ' reason="' + r.reason.replace(/\\/g, "\\\\").replace(/"/g, '\\"') + '"';
+      clause += " reason=" + safeBuffer.quoteString(r.reason);
     }
     // Method-specific properties (ptype.property=value triples per
     // RFC 8601 §2.3). Operators pass them as flat object keys.

package/lib/mail-server-imap.js

@@ -789,7 +789,7 @@ function create(opts) {
       .then(function (rows) {
         if (Array.isArray(rows) && rows.length > 0) {
           var pairs = rows.map(function (r) {
-            var v = r.value === null || r.value === undefined ? "NIL" : '"' + String(r.value).replace(/\\/g, "\\\\").replace(/"/g, "\\\"") + '"';
+            var v = r.value === null || r.value === undefined ? "NIL" : safeBuffer.quoteString(r.value);
             return r.entry + " " + v;
           }).join(" ");
           _writeUntagged(socket, "METADATA " + (mailbox === "" ? '""' : mailbox) + " (" + pairs + ")");
@@ -1247,7 +1247,7 @@ function create(opts) {
         for (var i = 0; i < folders.length; i += 1) {
           var f = folders[i];
           var attrs = (f.attributes || []).map(function (a) { return "\\" + a; }).join(" ");
-          _writeUntagged(socket, "LIST (" + attrs + ") \"/\" " + _quote(f.name));
+          _writeUntagged(socket, "LIST (" + attrs + ") \"/\" " + safeBuffer.quoteString(f.name));
         }
         _writeTagged(socket, tag, "OK LIST completed");
       })
@@ -1282,7 +1282,7 @@ function create(opts) {
           var key = items[k].toUpperCase();
           if (info[key] !== undefined) parts.push(key + " " + info[key]);
         }
-        _writeUntagged(socket, "STATUS " + _quote(name) + " (" + parts.join(" ") + ")");
+        _writeUntagged(socket, "STATUS " + safeBuffer.quoteString(name) + " (" + parts.join(" ") + ")");
         _writeTagged(socket, tag, "OK STATUS completed");
       })
       .catch(function (err) {
@@ -1780,7 +1780,6 @@ function create(opts) {
     try { socket.destroy(); } catch (_e2) { /* idempotent */ }
     connections.delete(socket);
   }
-  function _quote(s) { return '"' + String(s).replace(/\\/g, "\\\\").replace(/"/g, "\\\"") + '"'; }
   function _unquote(s) {
     if (typeof s !== "string") return "";
     if (s[0] === "\"" && s[s.length - 1] === "\"") return s.slice(1, -1);

package/lib/mail-server-managesieve.js

@@ -730,7 +730,7 @@ function create(opts) {
           var s = list[i];
           var nm = String(s.name || "");
           var active = s.active === true ? " ACTIVE" : "";
-          socket.write('"' + _quoteEscape(nm) + '"' + active + "\r\n");
+          socket.write(safeBuffer.quoteString(nm) + active + "\r\n");
         }
         _emit("mail.server.managesieve.listscripts",
           { connectionId: state.id, count: list.length });
@@ -813,24 +813,20 @@ function create(opts) {
       });
   }
 
-  // RFC 5804 §1.2 quoted-string escaping: backslash + DQUOTE inside
-  // the value get escaped with a leading backslash.
-  function _quoteEscape(s) {
-    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');                                               // allow:regex-no-length-cap — backslash + DQUOTE escape on bounded-input
-  }
-
+  // RFC 5804 §1.2 quoted strings — serialization routes through
+  // safeBuffer.quoteString (one quoted-string escaper framework-wide).
   function _writeOk(socket, msg) {
-    try { socket.write('OK "' + _quoteEscape(msg) + '"\r\n'); } catch (_e) { /* socket down */ }
+    try { socket.write("OK " + safeBuffer.quoteString(msg) + "\r\n"); } catch (_e) { /* socket down */ }
   }
   function _writeOkWithTag(socket, tag, msg) {
-    try { socket.write('OK (TAG "' + _quoteEscape(tag) + '") "' + _quoteEscape(msg) + '"\r\n'); }
+    try { socket.write("OK (TAG " + safeBuffer.quoteString(tag) + ") " + safeBuffer.quoteString(msg) + "\r\n"); }
     catch (_e) { /* socket down */ }
   }
   function _writeNo(socket, msg) {
-    try { socket.write('NO "' + _quoteEscape(msg) + '"\r\n'); } catch (_e) { /* socket down */ }
+    try { socket.write("NO " + safeBuffer.quoteString(msg) + "\r\n"); } catch (_e) { /* socket down */ }
   }
   function _writeBye(socket, msg) {
-    try { socket.write('BYE "' + _quoteEscape(msg) + '"\r\n'); } catch (_e) { /* socket down */ }
+    try { socket.write("BYE " + safeBuffer.quoteString(msg) + "\r\n"); } catch (_e) { /* socket down */ }
   }
   function _close(socket) {
     try { socket.end(); } catch (_e) { /* idempotent */ }

package/lib/safe-buffer.js

@@ -872,6 +872,41 @@ function assertHeaderSafe(value, label, ErrorClass, code) {
   return value;
 }
 
+/**
+ * @primitive b.safeBuffer.quoteString
+ * @signature b.safeBuffer.quoteString(s)
+ * @since     0.16.9
+ * @status    stable
+ * @related   b.safeBuffer.assertHeaderSafe, b.safeBuffer.foldHeaderText
+ *
+ * Serialize a value as an RFC quoted-string: coerce to string, escape
+ * every backslash and DQUOTE with a leading backslash, and wrap the
+ * result in DQUOTEs. One serializer for the quoted-string grammars the
+ * framework emits — RFC 8941 §3.3.3 Structured Fields sf-string
+ * (Cache-Status, Signature-Input, Server-Timing desc), RFC 8288 Link
+ * header parameters, RFC 8601 §2.2 Authentication-Results reason,
+ * RFC 3501 §4.3 IMAP quoted strings, and RFC 5804 §1.2 ManageSieve
+ * strings — so an unescaped quote can never terminate the string early
+ * and smuggle extra parameters into the protocol line.
+ *
+ * Escaping only — it does not validate a grammar's character range. A
+ * grammar that forbids bytes a quoted-string cannot carry (sf-string is
+ * printable-ASCII only; IMAP quoted strings cannot carry CR / LF)
+ * enforces its range check before calling this.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeBuffer.quoteString("cache miss");
+ *   // → "\"cache miss\""
+ *
+ *   // A quote or backslash in the value cannot break out of the string.
+ *   b.safeBuffer.quoteString('say "hi"');
+ *   // → "\"say \\\"hi\\\"\""
+ */
+function quoteString(s) {
+  return "\"" + String(s).replace(/\\/g, "\\\\").replace(/"/g, "\\\"") + "\"";                       // allow:regex-no-length-cap — fixed-char-set escape on caller-bounded input
+}
+
 module.exports = {
   normalizeText:         normalizeText,
   toBuffer:              toBuffer,
@@ -885,6 +920,7 @@ module.exports = {
   stripCrlf:             stripCrlf,
   foldHeaderText:        foldHeaderText,
   assertHeaderSafe:      assertHeaderSafe,
+  quoteString:           quoteString,
   stripTrailingHspace:   stripTrailingHspace,
   indexAfterOpenTag:     indexAfterOpenTag,
   HEX_RE:                HEX_RE,

package/lib/server-timing.js

@@ -37,6 +37,7 @@
  *   W3C Server-Timing response header builder — per-request timing-metric collector that surfaces server-side latency in the browser's Performance API.
  */
 
+var safeBuffer = require("./safe-buffer");
 var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
 
@@ -46,9 +47,6 @@ var ServerTimingError = defineClass("ServerTimingError", { alwaysPermanent: true
 // at 128 chars for sanity; operator-supplied desc is sf-string.
 var METRIC_NAME_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]{1,128}$/;                                       // RFC 7230 token shape + length cap
 
-function _quoteDesc(s) {
-  return "\"" + String(s).replace(/\\/g, "\\\\").replace(/"/g, "\\\"") + "\"";
-}
 
 /**
  * @primitive b.serverTiming.create
@@ -120,7 +118,7 @@ function create() {
     return entries.map(function (e) {
       var parts = [e.name];
       if (e.dur !== null) parts.push("dur=" + _formatDur(e.dur));
-      if (e.desc !== null) parts.push("desc=" + _quoteDesc(e.desc));
+      if (e.desc !== null) parts.push("desc=" + safeBuffer.quoteString(e.desc));
       return parts.join("; ");
     }).join(", ");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.16.8",
+  "version": "0.16.9",
   "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.5",
-  "serialNumber": "urn:uuid:e3fe6fd4-45fd-4d3d-bff7-7b6d7526ee36",
+  "serialNumber": "urn:uuid:68353b7c-580f-428e-ae5e-90364fa6a380",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-10T16:20:31.784Z",
+    "timestamp": "2026-07-10T22:44:46.568Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.16.8",
+      "bom-ref": "@blamejs/core@0.16.9",
       "type": "application",
       "name": "blamejs",
-      "version": "0.16.8",
+      "version": "0.16.9",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.16.8",
+      "purl": "pkg:npm/%40blamejs/core@0.16.9",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.16.8",
+      "ref": "@blamejs/core@0.16.9",
       "dependsOn": []
     }
   ]