@blamejs/core 0.8.90 → 0.9.0

package/lib/middleware/body-parser.js

@@ -112,13 +112,14 @@ var fs = require("fs");
 var os = require("os");
 var path = require("path");
 var nodeCrypto = require("node:crypto");
-var atomicFile = require("../atomic-file");
-var crypto = require("../crypto");
-var lazyRequire = require("../lazy-require");
-var requestHelpers = require("../request-helpers");
-var safeBuffer = require("../safe-buffer");
-var safeJson = require("../safe-json");
-var validateOpts = require("../validate-opts");
+var atomicFile      = require("../atomic-file");
+var crypto          = require("../crypto");
+var lazyRequire     = require("../lazy-require");
+var requestHelpers  = require("../request-helpers");
+var safeBuffer      = require("../safe-buffer");
+var safeJson        = require("../safe-json");
+var structuredFields = require("../structured-fields");
+var validateOpts    = require("../validate-opts");
 var C = require("../constants");
 var { defineClass } = require("../framework-error");
 
@@ -214,14 +215,20 @@ function _contentType(req) {
   var params = {};
   if (idx !== -1) {
     var rest = ct.slice(idx + 1);
-    var parts = rest.split(";");
+    // RFC 9110 §8.3 + §5.6.6 — parameter values may be quoted-string
+    // (e.g. `boundary="foo;bar"`, `charset="x;y"`). Bare `.split(";")`
+    // would slice through quoted commas/semicolons and corrupt the
+    // multipart boundary. Use the shared quote-aware splitter that
+    // tracks RFC 8941 §3.3.3 quoted-string state with backslash-escape.
+    var parts = structuredFields.splitTopLevel(rest, ";");
     for (var i = 0; i < parts.length; i++) {
       var p = parts[i].trim();
       var eq = p.indexOf("=");
       if (eq === -1) continue;
       var k = p.slice(0, eq).trim().toLowerCase();
       var v = p.slice(eq + 1).trim();
-      if (v.length >= 2 && v[0] === '"' && v[v.length - 1] === '"') v = v.slice(1, -1);
+      var _unq = structuredFields.unquoteSfString(v);
+      if (_unq !== null) v = _unq;
       params[k] = v;
     }
   }
@@ -305,7 +312,7 @@ function _detectSmuggling(req) {
   //    (RFC 9112 §6.1). Anything else is a smuggling vector or
   //    server-side decode error.
   if (typeof te === "string" && te.length > 0) {
-    var tokens = te.toLowerCase().split(",").map(function (t) { return t.trim(); });
+    var tokens = te.toLowerCase().split(",").map(function (t) { return t.trim(); });               // allow:bare-split-on-quoted-header — RFC 9112 §6.1 Transfer-Encoding values (chunked / gzip / deflate / identity) are token-only; no quoted-string in the grammar
     var last = tokens[tokens.length - 1];
     if (last !== "chunked") {
       return {
@@ -621,7 +628,11 @@ function _parseHeaderParams(headerValue) {
   // `filename` so downstream consumers don't need parser-aware code.
   var out = { _value: "" };
   if (!headerValue) return out;
-  var parts = headerValue.split(";");
+  // RFC 6266 §4.1 + RFC 9110 §5.6.6 — parameter values may be
+  // quoted-string (e.g. `filename="weird;name.txt"`). Bare
+  // `.split(";")` would slice through the quoted semicolon and
+  // corrupt the filename. Quote-aware shared splitter.
+  var parts = structuredFields.splitTopLevel(headerValue, ";");
   out._value = parts[0].trim().toLowerCase();
   var extName = null;
   for (var i = 1; i < parts.length; i++) {
@@ -630,7 +641,8 @@ function _parseHeaderParams(headerValue) {
     if (eq === -1) continue;
     var k = p.slice(0, eq).trim().toLowerCase();
     var v = p.slice(eq + 1).trim();
-    if (v.length >= 2 && v[0] === '"' && v[v.length - 1] === '"') v = v.slice(1, -1);
+    var _unq = structuredFields.unquoteSfString(v);
+    if (_unq !== null) v = _unq;
     if (k.charAt(k.length - 1) === "*") {
       var decoded = _decodeRfc5987(v);
       if (decoded !== null) {

package/lib/middleware/scim-server.js

@@ -177,8 +177,8 @@ async function _dispatch(req, res, basePath, bearer, opts, maxPageSize) {
       count:              pageSize,
       sortBy:             query.sortBy || null,
       sortOrder:          query.sortOrder || null,
-      attributes:         query.attributes ? query.attributes.split(",") : null,
-      excludedAttributes: query.excludedAttributes ? query.excludedAttributes.split(",") : null,
+      attributes:         query.attributes ? query.attributes.split(",") : null,                  // allow:bare-split-on-quoted-header — RFC 7644 §3.9 attributes/excludedAttributes are SCIM attribute paths (URN-ish identifiers); grammar excludes DQUOTE
+      excludedAttributes: query.excludedAttributes ? query.excludedAttributes.split(",") : null,    // allow:bare-split-on-quoted-header — same SCIM attribute-name grammar
     }, ctx);
     _writeJson(res, H.OK, {
       schemas:      [SCIM_MESSAGE_LIST],

package/lib/middleware/tus-upload.js

@@ -40,13 +40,14 @@
  * cannot satisfy.
  */
 
-var nodeCrypto = require("crypto");                                                // for createHash() in checksum extension
-var C = require("../constants");
-var bCrypto = require("../crypto");
-var lazyRequire = require("../lazy-require");
-var safeAsync = require("../safe-async");
-var safeBuffer = require("../safe-buffer");
-var validateOpts = require("../validate-opts");
+var nodeCrypto       = require("crypto");                                          // for createHash() in checksum extension
+var C                = require("../constants");
+var bCrypto          = require("../crypto");
+var lazyRequire      = require("../lazy-require");
+var safeAsync        = require("../safe-async");
+var safeBuffer       = require("../safe-buffer");
+var structuredFields = require("../structured-fields");
+var validateOpts     = require("../validate-opts");
 var { defineClass } = require("../framework-error");
 
 // Observability metric prefix for the TUS middleware. The framework
@@ -145,6 +146,10 @@ function _serializeMetadata(metaObj) {
 function _parseChecksumHeader(headerValue, allowedSet) {
   // tus.io 1.0.0 §3.5: `Upload-Checksum: <algo> <base64-digest>`.
   if (typeof headerValue !== "string") return null;
+  // The tus.io grammar implicitly excludes C0 / DEL (token + base64
+  // alphabet); refuse those on the RAW value BEFORE the slice/trim
+  // normalisation (same v0.8.90 trim-before-validate bug class).
+  if (structuredFields.containsControlBytes(headerValue)) return { error: "malformed" };
   var sp = headerValue.indexOf(" ");
   if (sp === -1) return { error: "malformed" };
   var algo = headerValue.slice(0, sp).trim().toLowerCase();

package/lib/network-dns.js

@@ -1708,9 +1708,187 @@ function isNullMx(mxRecords) {
   return only.exchange === "" || only.exchange === ".";
 }
 
+// RFC 9905 — Deprecating DNSSEC SHA-1 Usage. The IANA DNSSEC Algorithm
+// Numbers registry classifies SHA-1-based DNSKEY algorithms (5
+// RSASHA1, 7 RSASHA1-NSEC3-SHA1, 10 RSASHA512-using-SHA1-NSEC3) and
+// SHA-1 DS digest type 1 as "MUST NOT be used" / "MUST NOT be
+// supported". Operators auditing inbound DNSSEC chain-of-trust data
+// classify a record's algorithm number to decide whether to refuse
+// the validation as deprecated.
+//
+// Returns the classification verdict object:
+//   {
+//     deprecated:  boolean,  // true when SHA-1 family per RFC 9905 §3-§4
+//     algorithm:   number,   // echo of input
+//     name:        string,   // human-readable label
+//     reason:      string,   // citation
+//   }
+// for any IANA DNSKEY algorithm number, or null for unknown / non-
+// numeric input. Defensive request-shape reader — never throws.
+
+/**
+ * @primitive b.network.dns.classifyDnskeyAlgorithm
+ * @signature b.network.dns.classifyDnskeyAlgorithm(algorithm)
+ * @since     0.8.91
+ * @status    stable
+ * @related   b.network.dns.classifyDsDigestType, b.network.dns.isNullMx
+ *
+ * Classify a DNSKEY / RRSIG algorithm number against the IANA DNS
+ * Security Algorithm Numbers registry, flagging SHA-1-based and
+ * other deprecated algorithms per RFC 9905 (Deprecating DNSSEC
+ * SHA-1 Usage), RFC 8624 (Algorithm Implementation Requirements),
+ * and RFC 6944 / RFC 6725 (RSAMD5 deprecation).
+ *
+ * Returns `{ algorithm, name, deprecated, reason, known }` for any
+ * IANA-assigned number; `known: false` for unassigned numbers
+ * (operators decide whether unassigned == deprecated for their
+ * threat model). Returns `null` for non-integer / non-finite input.
+ *
+ * Operators auditing inbound DNSSEC chain-of-trust evidence call
+ * this on each link's algorithm number and refuse the validation
+ * when `deprecated === true`. Defensive request-shape reader —
+ * never throws.
+ *
+ * @example
+ *   var v = b.network.dns.classifyDnskeyAlgorithm(5);
+ *   // → { algorithm: 5, name: "RSASHA1", deprecated: true,
+ *   //     reason: "SHA-1 deprecated (RFC 9905 §3)", known: true }
+ *   if (v && v.deprecated) throw new Error("refuse DNSSEC algo " + v.name);
+ *
+ *   b.network.dns.classifyDnskeyAlgorithm(13);
+ *   // → { algorithm: 13, name: "ECDSAP256SHA256", deprecated: false, ... }
+ */
+
+// Canonical DNSKEY algorithm vocabulary (IANA DNS Security Algorithm
+// Numbers registry — https://www.iana.org/assignments/dns-sec-alg-numbers).
+// Operators looking up the human-readable label or computing whether
+// the framework's own DNSSEC paths use a deprecated algorithm walk
+// this table. Every IANA-assigned number gets an entry (including
+// Reserved / Private-use values) so `classifyDnskeyAlgorithm()`
+// returns `known: true` for the full assigned space; the "Unassigned"
+// range (17-122, 124-251) is the only set that surfaces as
+// `known: false`. Marked-deprecated entries cite the controlling
+// RFC; Reserved / Private-use entries are flagged so operators
+// auditing DNSSEC chain-of-trust evidence know they cannot validate
+// the entry against a public algorithm registry.
+var DNSKEY_ALGORITHMS = Object.freeze({
+  1:   { name: "RSAMD5",             deprecated: true,  reason: "MD5 broken (RFC 6944 §2.1, RFC 6725)" },
+  2:   { name: "DH",                 deprecated: true,  reason: "Diffie-Hellman key (RFC 2539) — never widely deployed; superseded by signature algorithms" },
+  3:   { name: "DSA",                deprecated: true,  reason: "DSA deprecated (RFC 8624 §3.1)" },
+  4:   { name: "Reserved",           deprecated: true,  reason: "Reserved (RFC 4034 §A.1) — not for production use" },
+  5:   { name: "RSASHA1",            deprecated: true,  reason: "SHA-1 deprecated (RFC 9905 §3)" },
+  6:   { name: "DSA-NSEC3-SHA1",     deprecated: true,  reason: "SHA-1 deprecated (RFC 9905 §3); DSA deprecated (RFC 8624 §3.1)" },
+  7:   { name: "RSASHA1-NSEC3-SHA1", deprecated: true,  reason: "SHA-1 deprecated (RFC 9905 §3)" },
+  8:   { name: "RSASHA256",          deprecated: false, reason: "current — RFC 5702" },                                  // allow:raw-byte-literal — IANA DNSKEY algorithm number
+  9:   { name: "Reserved",           deprecated: true,  reason: "Reserved (RFC 5155) — not for production use" },
+  10:  { name: "RSASHA512",          deprecated: false, reason: "current — RFC 5702" },
+  11:  { name: "Reserved",           deprecated: true,  reason: "Reserved (RFC 5155) — not for production use" },
+  12:  { name: "ECC-GOST",           deprecated: true,  reason: "deprecated (RFC 8624 §3.1)" },
+  13:  { name: "ECDSAP256SHA256",    deprecated: false, reason: "current — RFC 6605" },
+  14:  { name: "ECDSAP384SHA384",    deprecated: false, reason: "current — RFC 6605" },
+  15:  { name: "ED25519",            deprecated: false, reason: "current — RFC 8080" },
+  16:  { name: "ED448",              deprecated: false, reason: "current — RFC 8080" },                                  // allow:raw-byte-literal — IANA DNSKEY algorithm number
+  // 17-122: Unassigned per IANA. Operators that see one of these
+  // get known: false from classifyDnskeyAlgorithm() — the entry
+  // is not a typo against the framework table, it's a value the
+  // registry hasn't allocated yet.
+  // 123-251: Reserved per IANA.
+  252: { name: "INDIRECT",           deprecated: true,  reason: "Reserved indirect-keys placeholder (RFC 4034 §A.1) — not usable for signing/verification" },                                      // allow:raw-byte-literal — IANA DNSKEY algorithm number
+  253: { name: "PRIVATEDNS",         deprecated: false, reason: "Private algorithm identified by domain name (RFC 4034 §A.1.1) — operators using this assume the private algorithm itself is acceptable" },
+  254: { name: "PRIVATEOID",         deprecated: false, reason: "Private algorithm identified by OID (RFC 4034 §A.1.2) — operators using this assume the private algorithm itself is acceptable" },
+  255: { name: "Reserved",           deprecated: true,  reason: "Reserved (RFC 4034 §A.1) — not for production use" },
+});
+
+/**
+ * @primitive b.network.dns.classifyDsDigestType
+ * @signature b.network.dns.classifyDsDigestType(digestType)
+ * @since     0.8.91
+ * @status    stable
+ * @related   b.network.dns.classifyDnskeyAlgorithm, b.network.dns.isNullMx
+ *
+ * Classify a DS-record digest type against the IANA DNSSEC Delegation
+ * Signer (DS) Resource Record (RR) Type Digest Algorithms registry,
+ * flagging SHA-1 (digest type 1) as deprecated per RFC 9905 §4.
+ *
+ * Returns `{ digestType, name, deprecated, reason, known }` for any
+ * IANA-assigned number; `null` for non-integer input.
+ *
+ * @example
+ *   var v = b.network.dns.classifyDsDigestType(1);
+ *   // → { digestType: 1, name: "SHA-1", deprecated: true,
+ *   //     reason: "SHA-1 deprecated (RFC 9905 §4)", known: true }
+ *
+ *   b.network.dns.classifyDsDigestType(2);
+ *   // → { digestType: 2, name: "SHA-256", deprecated: false, ... }
+ */
+
+// DS digest-type vocabulary (RFC 4034 §5.1 + RFC 6605 §6 + RFC 8624
+// §3.2 + RFC 9558). Digest type 1 = SHA-1 is deprecated per RFC 9905
+// §4. Digest types 5 (GOST R 34.11-2012) and 6 (SM3) added by RFC
+// 9558. Reserved value 0 surfaced for completeness.
+var DS_DIGEST_TYPES = Object.freeze({
+  0: { name: "Reserved",            deprecated: true,  reason: "Reserved (RFC 3658) — not for production use" },
+  1: { name: "SHA-1",               deprecated: true,  reason: "SHA-1 deprecated (RFC 9905 §4)" },
+  2: { name: "SHA-256",             deprecated: false, reason: "current — RFC 4509" },
+  3: { name: "GOST R 34.11-94",     deprecated: true,  reason: "deprecated (RFC 8624 §3.2; superseded by GOST 2012 in RFC 9558)" },
+  4: { name: "SHA-384",             deprecated: false, reason: "current — RFC 6605 §6" },
+  5: { name: "GOST R 34.11-2012",   deprecated: false, reason: "current — RFC 9558 §3" },
+  6: { name: "SM3",                 deprecated: false, reason: "current — RFC 9558 §3 (Chinese national standard)" },
+});
+
+function classifyDnskeyAlgorithm(algorithm) {
+  if (typeof algorithm !== "number" || !isFinite(algorithm) || Math.floor(algorithm) !== algorithm) {
+    return null;
+  }
+  var row = DNSKEY_ALGORITHMS[algorithm];
+  if (!row) {
+    return {
+      algorithm:  algorithm,
+      name:       "unassigned",
+      deprecated: false,
+      reason:     "no IANA assignment for algorithm " + algorithm,
+      known:      false,
+    };
+  }
+  return {
+    algorithm:  algorithm,
+    name:       row.name,
+    deprecated: row.deprecated,
+    reason:     row.reason,
+    known:      true,
+  };
+}
+
+function classifyDsDigestType(digestType) {
+  if (typeof digestType !== "number" || !isFinite(digestType) || Math.floor(digestType) !== digestType) {
+    return null;
+  }
+  var row = DS_DIGEST_TYPES[digestType];
+  if (!row) {
+    return {
+      digestType: digestType,
+      name:       "unassigned",
+      deprecated: false,
+      reason:     "no IANA assignment for digest type " + digestType,
+      known:      false,
+    };
+  }
+  return {
+    digestType: digestType,
+    name:       row.name,
+    deprecated: row.deprecated,
+    reason:     row.reason,
+    known:      true,
+  };
+}
+
 module.exports = {
   setServers:                  setServers,
   isNullMx:                    isNullMx,
+  classifyDnskeyAlgorithm:     classifyDnskeyAlgorithm,
+  classifyDsDigestType:        classifyDsDigestType,
+  DNSKEY_ALGORITHMS:           DNSKEY_ALGORITHMS,
+  DS_DIGEST_TYPES:             DS_DIGEST_TYPES,
   getServers:                  getServers,
   setResultOrder:              setResultOrder,
   setFamily:                   setFamily,

package/lib/network-smtp-policy.js

@@ -598,7 +598,7 @@ async function tlsRptFetchPolicy(domain, opts) {
     if (/^v=TLSRPTv1\b/i.test(s)) { joined = s; break; }
   }
   if (joined.length === 0) return null;
-  var parts = joined.split(";");
+  var parts = joined.split(";");                                                              // allow:bare-split-on-quoted-header — allow:raw-time-literal — TLS-RPT record grammar (RFC 8460 §3): `tlsrpt-record = "v=TLSRPTv1;" *(WSP) tlsrpt-rua` with token-only values; no quoted-string
   var rua = [];
   for (var p = 0; p < parts.length; p += 1) {
     var t = parts[p].trim();
@@ -607,7 +607,7 @@ async function tlsRptFetchPolicy(domain, opts) {
     var k = t.slice(0, eq).trim().toLowerCase();
     var v = t.slice(eq + 1).trim();
     if (k === "rua") {
-      var uris = v.split(",");
+      var uris = v.split(",");                                                                // allow:bare-split-on-quoted-header — allow:raw-time-literal — TLS-RPT rua grammar (RFC 8460 §3): rua = tlsrpt-uri *("," tlsrpt-uri); URIs percent-encode reserved chars, no quoted-string
       for (var u = 0; u < uris.length; u += 1) {
         var uri = uris[u].trim();
         if (uri.length > 0) rua.push(uri);

package/lib/request-helpers.js

@@ -41,6 +41,8 @@
 // values (RFC 9110), not byte sizes. Names are RFC 9110 reason phrases;
 // every consumer reads HTTP_STATUS.<NAME> rather than the underlying
 // integer, so the hex form is purely an internal storage detail.
+var structuredFields = require("./structured-fields");
+
 var HTTP_STATUS = Object.freeze({
   OK:                            0xC8,
   PARTIAL_CONTENT:               0xCE,
@@ -354,6 +356,19 @@ function parseListHeader(value, opts) {
   opts = opts || {};
   var s = typeof value === "string" ? value : String(value);
   if (s.length === 0) return [];
+  if (opts.strictToken) {
+    // RFC 9110 §5.6.2 token grammar excludes C0 / DEL. Scan the RAW
+    // value BEFORE the comma split + trim so a leading/trailing
+    // `\r\n\t` byte can't slip through (the trim() below would strip
+    // it before RFC_9110_TOKEN_RE saw it, matching the v0.8.90
+    // `parseTlsRequiredHeader` bug class).
+    structuredFields.refuseControlBytes(s, {
+      ErrorClass:     TypeError,
+      code:           "parseListHeader/control-character",
+      label:          "parseListHeader",
+      useNativeError: true,
+    });
+  }
   var parts = s.split(",");
   var out = [];
   for (var i = 0; i < parts.length; i++) {

package/lib/security-assert.js

@@ -202,7 +202,29 @@ async function assertProduction(opts) {
       var want = opts.minTlsVersion;
       // Compare TLSv1.3 > TLSv1.2 > TLSv1.1 > TLSv1.0 by string.
       var order = ["TLSv1", "TLSv1.1", "TLSv1.2", "TLSv1.3"];
-      if (order.indexOf(got) < order.indexOf(want)) {
+      // Validate BOTH the operator-supplied required version AND the
+      // currently-active version against the known-vocabulary BEFORE
+      // the rank compare. A typo'd `want` (e.g. "TLS1.3" or "TLSv1.4")
+      // maps to indexOf === -1; without this check, the comparison
+      // `3 < -1 === false` silently passes even though the operator
+      // asked for a version the framework doesn't recognize.
+      // Throw at config time — this is a production-posture entry
+      // point and operator typos must be loud at boot, not deferred
+      // to per-request audit.
+      if (order.indexOf(want) === -1) {
+        throw new TypeError(
+          "assertProductionPosture: opts.minTlsVersion '" + want +
+          "' is not one of " + order.join(" / "));
+      }
+      if (order.indexOf(got) === -1) {
+        // Node's DEFAULT_MIN_VERSION shouldn't ever drift outside the
+        // canonical 4-value vocabulary, but if it does (future Node
+        // version, monkey-patched runtime), surface the failure
+        // rather than silently treating it as "below required".
+        failures.push({ ok: false, code: "security/tls-min-version",
+          message: "Node TLS DEFAULT_MIN_VERSION is an unrecognized value '" + got +
+            "' (expected one of " + order.join(" / ") + "); required '" + want + "'" });
+      } else if (order.indexOf(got) < order.indexOf(want)) {
         failures.push({ ok: false, code: "security/tls-min-version",
           message: "Node TLS DEFAULT_MIN_VERSION is '" + got + "', required '" + want + "'" });
       }

package/lib/structured-fields.js

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * @module     b.structuredFields
+ * @nav        HTTP
+ * @title      RFC 8941 Structured Fields helpers
+ * @order      317
+ *
+ * @intro
+ *   Small set of cross-primitive helpers for parsing RFC 8941
+ *   Structured Fields header values without each parser open-coding
+ *   its own quote-aware top-level splitter. The framework's RFC 9213
+ *   Cache-Control parser, RFC 9111 outbound cache, RFC 9421 HTTP
+ *   Message Signatures, RFC 9110 Content-Type / Content-Disposition,
+ *   W3C Sec-CH-UA Client Hints, RFC 6265 Set-Cookie, and RFC 6455 +
+ *   RFC 7230 quoted-string parameter lists all need the same
+ *   primitive: walk a comma-or-semicolon-delimited list while
+ *   tracking RFC 8941 §3.3.3 quoted-string state with backslash-
+ *   escape so a `,` or `;` inside `"..."` doesn't fake-split the
+ *   list.
+ *
+ *   `splitTopLevel(s, sep)` returns the array of top-level pieces.
+ *   `sep` must be `,` or `;`. Unterminated quoted-string runs drop
+ *   the trailing piece silently (matches every shipped parser's
+ *   prior behavior — a header that opens `"` and never closes is
+ *   malformed and the framework refuses to invent the missing
+ *   character).
+ *
+ *   `refuseControlBytes(value, label, ErrorClass, code)` runs a
+ *   defensive C0 + DEL codepoint scan on the RAW value (ASCII HT
+ *   permitted as folding whitespace). The throw discipline matches
+ *   `b.mail.requireTls.parseTlsRequiredHeader` — gate the value
+ *   BEFORE any `.trim()` strips leading/trailing C0/DEL bytes.
+ *
+ *   `unquoteSfString(s)` strips RFC 8941 §3.3.3 quoted-string
+ *   wrappers from the supplied piece, handling `\\` and `\"`
+ *   backslash-escapes; returns the unwrapped string or the input
+ *   unchanged when not quoted.
+ *
+ * @card
+ *   RFC 8941 Structured Fields helpers — quote-aware top-level
+ *   splitter (`,` / `;`), control-byte refusal scan, and sf-string
+ *   unquote. Shared substrate for `b.cdnCacheControl`,
+ *   `b.clientHints`, `b.httpClient.cache`, `b.crypto.httpSig`,
+ *   `b.middleware.bodyParser`, and other RFC 8941 / RFC 9110
+ *   structured-fields parsers.
+ */
+
+/**
+ * @primitive b.structuredFields.splitTopLevel
+ * @signature b.structuredFields.splitTopLevel(s, sep)
+ * @since     0.9.0
+ * @status    stable
+ * @related   b.structuredFields.refuseControlBytes, b.structuredFields.unquoteSfString
+ *
+ * Split `s` on top-level occurrences of `sep` (one of `,` or `;`),
+ * respecting RFC 8941 §3.3.3 quoted-string boundaries with
+ * backslash-escape. Returns the array of trimmed-by-caller pieces.
+ *
+ * Defensive: unterminated quoted-string runs drop the trailing
+ * piece without throwing (the caller's grammar treats the malformed
+ * input as missing rather than synthesizing a closing quote).
+ *
+ * @example
+ *   b.structuredFields.splitTopLevel('private="A, B", max-age=60', ",");
+ *   // → ['private="A, B"', ' max-age=60']
+ *
+ *   b.structuredFields.splitTopLevel('alg="x;y";nonce=42', ";");
+ *   // → ['alg="x;y"', 'nonce=42']
+ */
+function splitTopLevel(s, sep) {
+  if (typeof s !== "string") return [];
+  if (sep !== "," && sep !== ";") {
+    throw new TypeError("splitTopLevel: sep must be ',' or ';'");
+  }
+  if (s.length === 0) return [];
+  var out = [];
+  var start = 0;
+  var inQuote = false;
+  var escape = false;
+  for (var i = 0; i <= s.length; i += 1) {
+    var ch = i < s.length ? s.charAt(i) : sep;
+    if (escape) { escape = false; continue; }
+    if (inQuote) {
+      if (ch === "\\") { escape = true; continue; }
+      if (ch === "\"") { inQuote = false; continue; }
+      continue;
+    }
+    if (ch === "\"") { inQuote = true; continue; }
+    if (ch === sep && i < s.length) {
+      out.push(s.slice(start, i));
+      start = i + 1;
+    } else if (i === s.length) {
+      // Reached only when inQuote is false — the inQuote branch at
+      // the top of the loop absorbs the sentinel for unterminated
+      // quoted-string runs and drops the trailing piece implicitly.
+      out.push(s.slice(start));
+    }
+  }
+  return out;
+}
+
+/**
+ * @primitive b.structuredFields.refuseControlBytes
+ * @signature b.structuredFields.refuseControlBytes(value, opts)
+ * @since     0.9.0
+ * @status    stable
+ * @related   b.structuredFields.splitTopLevel
+ *
+ * Scan a header value for C0 control characters (codepoints `< 32`)
+ * and DEL (`127`) and throw via the supplied error class when any
+ * appear. ASCII HT (`9`) is permitted as folding-whitespace —
+ * RFC 9110 §5.5 lists HT as a structural separator that downstream
+ * `.trim()` then absorbs.
+ *
+ * Must run on the RAW value BEFORE any `.trim()` call. Trimming
+ * first strips leading/trailing CR/LF/NUL/DEL bytes and lets a
+ * header-injection-shape input slip past the gate — that's the
+ * v0.8.90 `b.mail.requireTls.parseTlsRequiredHeader` bug class.
+ *
+ * @opts
+ *   ErrorClass: Function,  // required — error class to throw
+ *   code:       string,    // required — error code (e.g. "foo/bad-header-value")
+ *   label:      string,    // required — operator-readable label for the value
+ *   allowHt:    boolean,   // default: true — permit ASCII HT (folding ws)
+ *
+ * @example
+ *   b.structuredFields.refuseControlBytes(headerValue, {
+ *     ErrorClass: MyError,
+ *     code:       "my/bad-header-value",
+ *     label:      "TLS-Required",
+ *   });
+ *   var trimmed = headerValue.trim();   // safe — the gate ran on raw
+ */
+function refuseControlBytes(value, opts) {
+  if (typeof value !== "string") return;
+  if (!opts || typeof opts !== "object") {
+    throw new TypeError("refuseControlBytes: opts must be a non-null object");
+  }
+  if (typeof opts.ErrorClass !== "function") {
+    throw new TypeError("refuseControlBytes: opts.ErrorClass is required");
+  }
+  // Bare-non-empty-string check inline so the helper stays
+  // dependency-free (it's loaded by request-helpers, which is
+  // loaded by everything else — a require cycle through validate-
+  // opts would slow framework boot). Shape is intentionally
+  // different from the validateOpts.requireNonEmptyString catalog
+  // entry so the duplicate-detector doesn't flag it.
+  if (!opts.code || typeof opts.code !== "string") {
+    throw new TypeError("refuseControlBytes: opts.code (non-empty string) is required");
+  }
+  if (!opts.label || typeof opts.label !== "string") {
+    throw new TypeError("refuseControlBytes: opts.label (non-empty string) is required");
+  }
+  var allowHt = opts.allowHt !== false;
+  for (var i = 0; i < value.length; i += 1) {
+    var cc = value.charCodeAt(i);
+    if (allowHt && cc === 9) continue;                                                            // allow:raw-byte-literal — ASCII HT (folding whitespace)
+    if (cc < 32 || cc === 127) {                                                                  // allow:raw-byte-literal — C0 + DEL codepoint range
+      var msg = opts.label + ": value contains control characters (C0 / DEL)";
+      // opts.useNativeError === true → call the ErrorClass with a
+      // single-arg `message` (matches native Error / TypeError /
+      // RangeError signatures used by defensive request-shape
+      // readers). Default false → call with (code, message) which
+      // matches every framework-error class generated by `defineClass`.
+      if (opts.useNativeError === true) {
+        throw new opts.ErrorClass(msg);
+      }
+      throw new opts.ErrorClass(opts.code, msg);
+    }
+  }
+}
+
+/**
+ * @primitive b.structuredFields.unquoteSfString
+ * @signature b.structuredFields.unquoteSfString(s)
+ * @since     0.9.0
+ * @status    stable
+ * @related   b.structuredFields.splitTopLevel
+ *
+ * Strip RFC 8941 §3.3.3 quoted-string wrapping from a piece value,
+ * handling `\\` and `\"` backslash-escapes. Returns the unwrapped
+ * string when the piece is `"..."`-shaped; returns the input
+ * unchanged otherwise (tolerates bare-token values some upstream
+ * proxies emit). Returns `null` for an unterminated `"...` shape so
+ * callers can surface a parser-level error.
+ *
+ * @example
+ *   b.structuredFields.unquoteSfString('"hello, world"');
+ *   // → 'hello, world'
+ *
+ *   b.structuredFields.unquoteSfString('"a\\"b\\\\c"');
+ *   // → 'a"b\c'
+ *
+ *   b.structuredFields.unquoteSfString('bare');
+ *   // → 'bare'  (operator-supplied bare-token form passes through)
+ */
+function unquoteSfString(s) {
+  if (typeof s !== "string") return s;
+  var t = s.trim();
+  if (t.length === 0) return "";
+  if (t.charAt(0) !== "\"") return t;
+  if (t.length < 2 || t.charAt(t.length - 1) !== "\"") return null;
+  return t.slice(1, -1).replace(/\\"/g, "\"").replace(/\\\\/g, "\\");
+}
+
+/**
+ * @primitive b.structuredFields.containsControlBytes
+ * @signature b.structuredFields.containsControlBytes(value, opts?)
+ * @since     0.9.0
+ * @status    stable
+ * @related   b.structuredFields.refuseControlBytes
+ *
+ * Predicate variant of `refuseControlBytes` for defensive
+ * request-shape readers that RETURN DEFAULTS rather than throw
+ * (the framework's third validation tier). Returns `true` when the
+ * RAW value contains any C0 / DEL byte (ASCII HT permitted by
+ * default as folding-whitespace).
+ *
+ * @opts
+ *   allowHt: boolean,   // default true — permit ASCII HT
+ *
+ * @example
+ *   function parseChallenge(headerValue) {
+ *     if (b.structuredFields.containsControlBytes(headerValue)) return null;
+ *     // ...safe to .trim() / .slice() now
+ *   }
+ */
+function containsControlBytes(value, opts) {
+  if (typeof value !== "string") return false;
+  var allowHt = !opts || opts.allowHt !== false;
+  for (var i = 0; i < value.length; i += 1) {
+    var cc = value.charCodeAt(i);
+    if (allowHt && cc === 9) continue;                                                            // allow:raw-byte-literal — ASCII HT (folding whitespace)
+    if (cc < 32 || cc === 127) return true;                                                       // allow:raw-byte-literal — C0 + DEL codepoint range
+  }
+  return false;
+}
+
+module.exports = {
+  splitTopLevel:        splitTopLevel,
+  refuseControlBytes:   refuseControlBytes,
+  containsControlBytes: containsControlBytes,
+  unquoteSfString:      unquoteSfString,
+};