@blamejs/core 0.12.53 → 0.12.54

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.54 (2026-05-25) — **`b.structuredFields.parse` / `serialize` — full RFC 8941 Structured Fields codec.** The structured-fields module gains a complete RFC 8941 parser and serializer alongside its existing quote-aware helpers. b.structuredFields.parse reads an Item, List, or Dictionary into a typed value model — items are { value, params }, lists are arrays of items / inner lists, dictionaries are Maps — with Tokens and byte sequences returned as distinct SfToken / SfByteSequence instances. It enforces the grammar strictly: integer and decimal digit caps, printable-ASCII strings, canonical base64 byte sequences, valid token and key grammar, and no trailing characters. b.structuredFields.serialize is the exact inverse. This is the real parser the framework's Content-Digest, Client Hints, Web Push, and HTTP Message Signature surfaces can build on instead of open-coding each field. Validated against the official httpwg structured-field-tests conformance vectors. **Added:** *`b.structuredFields.parse(input, type, opts?)` / `serialize(value, type, opts?)` / `Token` / `ByteSequence`* — `parse` accepts `type` of `"item"`, `"list"`, or `"dictionary"` and returns the value model (items as `{ value, params }` with a `Map` of parameters; lists as arrays of items or inner lists; dictionaries as `Map`s). Bare items are JS numbers (Integer / Decimal), strings, booleans, `SfToken`, or `SfByteSequence`. Malformed input is rejected — out-of-range integers, over-long decimals, non-printable string bytes, non-canonical base64, invalid tokens / keys, and any trailing characters — and `opts.ErrorClass` yields a typed error. `serialize` is the inverse, rounding decimals to three fractional digits and refusing values outside the RFC's ranges or grammar. `b.structuredFields.Token` and `b.structuredFields.ByteSequence` wrap those bare-item types for serialization. The existing `splitTopLevel` / `refuseControlBytes` / `unquoteSfString` helpers are unchanged.
+
 - v0.12.53 (2026-05-25) — **`b.contentDigest` — HTTP Content-Digest / Repr-Digest fields (RFC 9530).** Emit and verify the Content-Digest / Repr-Digest HTTP fields so a recipient can detect a corrupted or tampered message body. b.contentDigest.create builds the RFC 8941 dictionary value (sha-256=:base64:, sha-512=:base64:) over a body; b.contentDigest.verify recomputes each modern digest over the body and compares it in constant time. Only SHA-256 and SHA-512 are computed — the legacy algorithms RFC 9530 §6 marks insecure (MD5, SHA-1, the unix checksums) are ignored on verify, and a field carrying no modern digest is refused, so an attacker cannot downgrade integrity to an MD5-only digest. Content-Digest is the integrity companion to HTTP Message Signatures (b.httpSig, RFC 9421): sign the digest rather than the whole body. Verified against the RFC 9530 Appendix D worked examples. **Added:** *`b.contentDigest.create(body, opts?)` / `b.contentDigest.verify(fieldValue, body, opts?)`* — `create` returns a Content-Digest / Repr-Digest field value over the body — SHA-256 by default, or any subset of `["sha-256","sha-512"]` via `opts.algorithms` — and refuses insecure or unknown algorithms. `verify` parses the field, recomputes each SHA-256 / SHA-512 entry over the body, and compares constant-time; it throws `content-digest/mismatch` on any mismatch, ignores legacy / unknown entries, throws `content-digest/no-modern-digest` if the field has no SHA-256 / SHA-512 entry at all, and honours `opts.required` to force specific algorithms to be present and match. Composes the framework's structured-field helpers and constant-time compare; Repr-Digest is the same machinery over the selected representation (RFC 9110).
 
 - v0.12.52 (2026-05-25) — **`b.privacyPass` — Privacy Pass origin-side token verification (RFC 9577 / 9578).** Anonymous, publicly verifiable authorization: an origin issues a WWW-Authenticate: PrivateToken challenge and verifies a presented token cryptographically, without learning who the client is and without a callback to the issuer. b.privacyPass implements the publicly verifiable token type 0x0002 (Blind RSA, 2048-bit): the token's authenticator is an RSA Blind Signature (RFC 9474) checked as RSASSA-PSS (SHA-384, 48-byte salt) over token_input = token_type ‖ nonce ‖ challenge_digest ‖ token_key_id, using only the issuer's public key. The token is bound to that key (token_key_id) and, optionally, to the challenge it answers, so a token minted for another origin is refused. Blind RSA is the algorithm Privacy Pass defines on the wire — like the DNSSEC / DANE verifiers it validates an external protocol's signatures rather than introducing classical crypto as a framework default. Verified against the RFC 9578 §8.2 test vector. **Added:** *`b.privacyPass.verifyToken(opts)` / `parseToken` / `buildChallenge`* — `buildChallenge` builds a TokenChallenge (RFC 9577 §2.1) and the matching `WWW-Authenticate: PrivateToken challenge=…, token-key=…` header an origin returns to request a token, scoped to an issuer (and optionally an origin and a 32-byte redemption context). `parseToken` splits a token into its fields (type / nonce / challenge_digest / token_key_id / authenticator). `verifyToken` verifies a type 0x0002 (Blind RSA) token: it confirms the token's `token_key_id` is the SHA-256 of the supplied issuer public key, optionally that its `challenge_digest` matches `opts.challenge`, and that the authenticator is a valid RSASSA-PSS signature over the token input. Refuses unknown / privately verifiable token types (the VOPRF type 0x0001 needs the issuer secret and is an issuer-side operation), key-id and challenge mismatches, and tampered authenticators. Marked experimental while the issuance protocols see deployment.

package/README.md

@@ -98,6 +98,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **AAD-bound sealed columns** — AEAD tag tied to `(table, rowId, column, schemaVersion)`; copy-paste between rows or schema-version replay surfaces as refused decrypt (`b.vault.aad`)
 - **Signed webhooks + API encryption** — SLH-DSA-SHAKE-256f default; ML-DSA-65 opt-in; ECIES API encryption (`b.webhook`, `b.crypto`)
 - **HPKE / HTTP signatures** — RFC 9180 HPKE with ML-KEM-1024 + HKDF-SHA3-512 + ChaCha20-Poly1305 (`b.crypto.hpke`); RFC 9421 HTTP Message Signatures with derived components and ed25519 / ML-DSA-65 (`b.crypto.httpSig`); RFC 9530 Content-Digest / Repr-Digest body-integrity fields (SHA-256 / SHA-512, legacy algorithms refused — `b.contentDigest`) to sign the digest rather than the whole body
+- **Structured Fields** — full RFC 8941 codec (`b.structuredFields.parse` / `serialize`): Items / Lists / Dictionaries, Inner Lists, Parameters, and all bare-item types (Integer / Decimal / String / Token / Byte Sequence / Boolean) with strict grammar + range enforcement — the parser behind Content-Digest, Client Hints, and HTTP Message Signatures
 - **CMS codec** — RFC 5652 Cryptographic Message Syntax encoder + decoder with PQC signers (ML-DSA-65 / ML-DSA-87 / SLH-DSA-SHAKE-256f; RFC 9909 + 9881) and KEMRecipientInfo recipients (ML-KEM-1024; RFC 9629 + 9936); ChaCha20-Poly1305 content encryption (RFC 8103) so Efail-class malleability cannot apply (`b.cms`)
 - **Stream throttle** — shared token-bucket bandwidth limiter (RFC 2697 srTCM shape); N concurrent `node:stream` pipelines draw from one operator-configured `bytesPerSec` budget (`b.streamThrottle`)
 - **TLS-RPT receiver** — RFC 8460 inbound aggregate-report ingest; HTTPS POST handler + §4.4 schema parser with gzip-bomb / ratio-bomb / depth-bomb defenses (`b.mail.deploy.parseTlsRptReport` / `b.mail.deploy.tlsRptIngestHttp`)

package/lib/structured-fields.js

@@ -236,9 +236,371 @@ function containsControlBytes(value, opts) {
   return false;
 }
 
+// ---------------------------------------------------------------------------
+// Full RFC 8941 codec (parse + serialize). The helpers above are the
+// quote-aware splitters individual parsers reach for; the codec below is
+// the complete grammar — Items, Lists, Dictionaries, Inner Lists,
+// Parameters, and every bare-item type.
+//
+// Value model:
+//   bare item  → number (Integer) | SfDecimal | string | boolean | SfToken | SfByteSequence
+//   item       → { value: bareItem, params: Map<string, bareItem> }
+//   inner list → { items: item[], params: Map<string, bareItem> }
+//   list       → (item | innerList)[]
+//   dictionary → Map<string, item | innerList>
+// ---------------------------------------------------------------------------
+
+// RFC 8941 §3.3.4 Token / §3.3.5 Byte Sequence are wrapped so they stay
+// distinct from plain strings on both parse output and serialize input.
+function SfToken(value) {
+  if (!(this instanceof SfToken)) return new SfToken(value);
+  this.value = String(value);
+}
+function SfByteSequence(value) {
+  if (!(this instanceof SfByteSequence)) return new SfByteSequence(value);
+  this.value = Buffer.isBuffer(value) ? value : Buffer.from(value);
+}
+// A Decimal preserves its type across parse → serialize even when its
+// value is numerically integral ("1.0" must not serialize back to "1").
+// A plain JS number serializes as an Integer when integral, a Decimal
+// otherwise; wrap in SfDecimal to force the Decimal form.
+function SfDecimal(value) {
+  if (!(this instanceof SfDecimal)) return new SfDecimal(value);
+  this.value = Number(value);
+}
+
+function _sfErr(opts) {
+  if (opts && typeof opts.ErrorClass === "function") {
+    return function (code, msg) { return opts.useNativeError === true ? new opts.ErrorClass(msg) : new opts.ErrorClass(code, msg); };
+  }
+  return function (code, msg) { var e = new Error(msg); e.code = code; return e; };
+}
+
+var INT_MAX = 999999999999999;          // 15 digits (RFC 8941 §3.3.1)
+var INT_MIN = -999999999999999;
+function _isDigit(c) { return c >= "0" && c <= "9"; }
+function _isLcAlpha(c) { return c >= "a" && c <= "z"; }
+function _isAlpha(c) { return (c >= "A" && c <= "Z") || (c >= "a" && c <= "z"); }
+function _isTchar(c) { return _isAlpha(c) || _isDigit(c) || "!#$%&'*+-.^_`|~".indexOf(c) !== -1; }
+function _isKeyChar(c) { return _isLcAlpha(c) || _isDigit(c) || c === "_" || c === "-" || c === "." || c === "*"; }
+
+function _parseNumber(cx, E) {
+  var sign = 1, type = "integer", num = "";
+  if (cx.s.charAt(cx.i) === "-") { sign = -1; cx.i += 1; }
+  if (cx.i >= cx.s.length || !_isDigit(cx.s.charAt(cx.i))) throw E("structured-fields/parse", "expected a digit at index " + cx.i);
+  for (;;) {
+    if (cx.i >= cx.s.length) break;
+    var c = cx.s.charAt(cx.i);
+    if (_isDigit(c)) { num += c; cx.i += 1; }
+    else if (type === "integer" && c === ".") {
+      if (num.length > 12) throw E("structured-fields/parse", "integer part of a decimal exceeds 12 digits");   // allow:raw-byte-literal — RFC 8941 §4.2.4 decimal integer-part cap
+      num += "."; type = "decimal"; cx.i += 1;
+    } else break;
+    if (type === "integer" && num.length > 15) throw E("structured-fields/parse", "integer exceeds 15 digits");  // allow:raw-byte-literal — §3.3.1 integer digit cap
+    if (type === "decimal" && num.length > 16) throw E("structured-fields/parse", "decimal exceeds the digit limit");   // allow:raw-byte-literal — 12 int + "." + 3 frac
+  }
+  if (type === "integer") return sign * parseInt(num, 10);
+  if (num.charAt(num.length - 1) === ".") throw E("structured-fields/parse", "decimal must not end with '.'");
+  if (num.length - num.indexOf(".") - 1 > 3) throw E("structured-fields/parse", "decimal fraction exceeds 3 digits");
+  return new SfDecimal(sign * parseFloat(num));
+}
+
+function _parseString(cx, E) {
+  cx.i += 1; // opening DQUOTE
+  var out = "";
+  while (cx.i < cx.s.length) {
+    var c = cx.s.charAt(cx.i); cx.i += 1;
+    if (c === "\\") {
+      if (cx.i >= cx.s.length) throw E("structured-fields/parse", "trailing backslash in string");
+      var n = cx.s.charAt(cx.i); cx.i += 1;
+      if (n !== "\\" && n !== "\"") throw E("structured-fields/parse", "invalid backslash escape in string");
+      out += n;
+    } else if (c === "\"") { return out; }
+    else {
+      var cc = c.charCodeAt(0);
+      if (cc < 0x20 || cc > 0x7e) throw E("structured-fields/parse", "non-printable character in string");   // allow:raw-byte-literal — RFC 8941 §4.2.5 printable-ASCII range
+      out += c;
+    }
+  }
+  throw E("structured-fields/parse", "unterminated string");
+}
+
+function _parseByteSeq(cx, E) {
+  cx.i += 1; // opening ":"
+  var start = cx.i;
+  while (cx.i < cx.s.length && cx.s.charAt(cx.i) !== ":") cx.i += 1;
+  if (cx.i >= cx.s.length) throw E("structured-fields/parse", "unterminated byte sequence");
+  var b64 = cx.s.slice(start, cx.i); cx.i += 1; // closing ":"
+  // RFC 8941 §4.2.7 synthesizes padding, so an unpadded value like
+  // `:aGVsbG8:` is valid input. Pad an unpadded value to a base64
+  // quantum, then require the decoded bytes to re-encode to exactly that
+  // padded text — rejecting stray characters, misplaced "=" padding, and
+  // non-zero trailing bits (Node's decoder is otherwise permissive).
+  var padded = b64.indexOf("=") === -1 ? b64 + "====".slice(0, (4 - (b64.length % 4)) % 4) : b64;
+  var buf = Buffer.from(padded, "base64");
+  if (buf.toString("base64") !== padded) throw E("structured-fields/parse", "byte sequence is not valid base64");
+  return new SfByteSequence(buf);
+}
+
+function _parseBoolean(cx, E) {
+  cx.i += 1; // "?"
+  var c = cx.s.charAt(cx.i); cx.i += 1;
+  if (c === "1") return true;
+  if (c === "0") return false;
+  throw E("structured-fields/parse", "boolean must be ?0 or ?1");
+}
+
+function _parseToken(cx) {
+  var start = cx.i; cx.i += 1; // first char already ALPHA / "*"
+  while (cx.i < cx.s.length) {
+    var c = cx.s.charAt(cx.i);
+    if (_isTchar(c) || c === ":" || c === "/") cx.i += 1; else break;
+  }
+  return new SfToken(cx.s.slice(start, cx.i));
+}
+
+function _parseBareItem(cx, E) {
+  var c = cx.s.charAt(cx.i);
+  if (c === "-" || _isDigit(c)) return _parseNumber(cx, E);
+  if (c === "\"") return _parseString(cx, E);
+  if (c === ":") return _parseByteSeq(cx, E);
+  if (c === "?") return _parseBoolean(cx, E);
+  if (c === "*" || _isAlpha(c)) return _parseToken(cx);
+  throw E("structured-fields/parse", "unexpected character '" + (c || "<eof>") + "' at index " + cx.i);
+}
+
+function _parseKey(cx, E) {
+  var c = cx.s.charAt(cx.i);
+  if (!(c === "*" || _isLcAlpha(c))) throw E("structured-fields/parse", "key must start with lcalpha or '*'");
+  var start = cx.i; cx.i += 1;
+  while (cx.i < cx.s.length && _isKeyChar(cx.s.charAt(cx.i))) cx.i += 1;
+  return cx.s.slice(start, cx.i);
+}
+
+function _parseParams(cx, E) {
+  var params = new Map();
+  while (cx.i < cx.s.length && cx.s.charAt(cx.i) === ";") {
+    cx.i += 1;
+    while (cx.s.charAt(cx.i) === " ") cx.i += 1;
+    var key = _parseKey(cx, E);
+    var val = true;
+    if (cx.s.charAt(cx.i) === "=") { cx.i += 1; val = _parseBareItem(cx, E); }
+    params.set(key, val);   // last value wins (RFC 8941 §4.2.3.2)
+  }
+  return params;
+}
+
+function _parseItem(cx, E) {
+  var value = _parseBareItem(cx, E);
+  return { value: value, params: _parseParams(cx, E) };
+}
+
+function _parseInnerList(cx, E) {
+  cx.i += 1; // "("
+  var items = [];
+  for (;;) {
+    while (cx.s.charAt(cx.i) === " ") cx.i += 1;
+    if (cx.i >= cx.s.length) throw E("structured-fields/parse", "unterminated inner list");
+    if (cx.s.charAt(cx.i) === ")") { cx.i += 1; return { items: items, params: _parseParams(cx, E) }; }
+    items.push(_parseItem(cx, E));
+    var c = cx.s.charAt(cx.i);
+    if (c !== " " && c !== ")") throw E("structured-fields/parse", "inner-list items must be space-separated");
+  }
+}
+
+function _parseItemOrInnerList(cx, E) {
+  return cx.s.charAt(cx.i) === "(" ? _parseInnerList(cx, E) : _parseItem(cx, E);
+}
+
+function _skipOWS(cx) { while (cx.s.charAt(cx.i) === " " || cx.s.charAt(cx.i) === "\t") cx.i += 1; }
+
+function _parseList(cx, E) {
+  var members = [];
+  if (cx.i >= cx.s.length) return members;
+  for (;;) {
+    members.push(_parseItemOrInnerList(cx, E));
+    _skipOWS(cx);
+    if (cx.i >= cx.s.length) return members;
+    if (cx.s.charAt(cx.i) !== ",") throw E("structured-fields/parse", "expected ',' between list members");
+    cx.i += 1; _skipOWS(cx);
+    if (cx.i >= cx.s.length) throw E("structured-fields/parse", "trailing comma in list");
+  }
+}
+
+function _parseDict(cx, E) {
+  var dict = new Map();
+  if (cx.i >= cx.s.length) return dict;
+  for (;;) {
+    var key = _parseKey(cx, E);
+    var member;
+    if (cx.s.charAt(cx.i) === "=") { cx.i += 1; member = _parseItemOrInnerList(cx, E); }
+    else { member = { value: true, params: _parseParams(cx, E) }; }
+    dict.set(key, member);   // last key wins (RFC 8941 §4.2.2)
+    _skipOWS(cx);
+    if (cx.i >= cx.s.length) return dict;
+    if (cx.s.charAt(cx.i) !== ",") throw E("structured-fields/parse", "expected ',' between dictionary members");
+    cx.i += 1; _skipOWS(cx);
+    if (cx.i >= cx.s.length) throw E("structured-fields/parse", "trailing comma in dictionary");
+  }
+}
+
+/**
+ * @primitive b.structuredFields.parse
+ * @signature b.structuredFields.parse(input, type, opts?)
+ * @since     0.12.54
+ * @status    stable
+ * @related   b.structuredFields.serialize, b.structuredFields.splitTopLevel
+ *
+ * Parse an RFC 8941 Structured Field value. <code>type</code> is
+ * <code>"item"</code>, <code>"list"</code>, or <code>"dictionary"</code>.
+ * Returns the value model: an item is <code>{ value, params }</code>
+ * (params is a <code>Map</code>); a list is an array of items / inner
+ * lists; a dictionary is a <code>Map</code>. Tokens and byte sequences
+ * come back as <code>SfToken</code> / <code>SfByteSequence</code>
+ * instances so they stay distinct from plain strings. Strictly enforces
+ * the grammar — integer / decimal digit caps, printable-ASCII strings,
+ * canonical base64, no trailing characters — and throws on any malformed
+ * input (pass <code>opts.ErrorClass</code> for a typed error).
+ *
+ * @opts
+ *   ErrorClass?: Function,   // typed error class (default: native Error with .code)
+ *
+ * @example
+ *   b.structuredFields.parse("a=1, b=(x y);q=2", "dictionary");
+ *   // → Map { "a" => { value: 1, params: Map{} },
+ *   //         "b" => { items: [...], params: Map{ "q" => 2 } } }
+ */
+function parse(input, type, opts) {
+  var E = _sfErr(opts);
+  if (typeof input !== "string") throw E("structured-fields/bad-input", "structuredFields.parse: input must be a string");
+  var cx = { s: input, i: 0 };
+  while (cx.s.charAt(cx.i) === " ") cx.i += 1;          // §4.2 discard leading SP
+  var out;
+  if (type === "item") out = _parseItem(cx, E);
+  else if (type === "list") out = _parseList(cx, E);
+  else if (type === "dictionary") out = _parseDict(cx, E);
+  else throw E("structured-fields/bad-type", "structuredFields.parse: type must be 'item' | 'list' | 'dictionary'");
+  while (cx.s.charAt(cx.i) === " ") cx.i += 1;          // §4.2 discard trailing SP
+  if (cx.i !== cx.s.length) throw E("structured-fields/parse", "trailing characters after the field value");
+  return out;
+}
+
+function _serDecimal(v, E) {
+  if (!isFinite(v)) throw E("structured-fields/serialize", "cannot serialize a non-finite decimal");
+  var n = Math.round(v * 1000) / 1000;                   // allow:raw-byte-literal allow:raw-time-literal — RFC 8941 §4.1.5 decimal scale 10^3 (3 fractional digits), not a size or duration
+  if (Math.abs(Math.trunc(n)).toString().length > 12) throw E("structured-fields/serialize", "decimal integer part exceeds 12 digits");   // allow:raw-byte-literal — §4.1.5 cap
+  var s = n.toString();
+  if (s.indexOf(".") === -1) s += ".0";                  // a Decimal must carry a fractional part
+  return s;
+}
+function _serBareItem(v, E) {
+  if (v === true) return "?1";
+  if (v === false) return "?0";
+  if (v instanceof SfDecimal) return _serDecimal(v.value, E);
+  if (typeof v === "number") {
+    if (!isFinite(v)) throw E("structured-fields/serialize", "cannot serialize a non-finite number");
+    if (Number.isInteger(v)) {
+      if (v > INT_MAX || v < INT_MIN) throw E("structured-fields/serialize", "integer out of RFC 8941 range");
+      return String(v);
+    }
+    return _serDecimal(v, E);                            // a fractional JS number serializes as a Decimal
+  }
+  if (typeof v === "string") {
+    var out = "\"";
+    for (var i = 0; i < v.length; i += 1) {
+      var c = v.charAt(i), cc = v.charCodeAt(i);
+      if (cc < 0x20 || cc > 0x7e) throw E("structured-fields/serialize", "string contains a non-printable character");   // allow:raw-byte-literal — §4.1.6 printable-ASCII range
+      if (c === "\\" || c === "\"") out += "\\";
+      out += c;
+    }
+    return out + "\"";
+  }
+  if (v instanceof SfToken) {
+    var t = v.value;
+    if (t.length === 0 || !(t.charAt(0) === "*" || _isAlpha(t.charAt(0)))) throw E("structured-fields/serialize", "invalid token");
+    for (var j = 1; j < t.length; j += 1) { var tc = t.charAt(j); if (!(_isTchar(tc) || tc === ":" || tc === "/")) throw E("structured-fields/serialize", "invalid token character"); }
+    return t;
+  }
+  if (v instanceof SfByteSequence) return ":" + v.value.toString("base64") + ":";
+  throw E("structured-fields/serialize", "unsupported bare-item type");
+}
+
+function _serParams(params, E) {
+  if (!params) return "";
+  var out = "";
+  params.forEach(function (val, key) {
+    out += ";" + _serKey(key, E);
+    if (val !== true) out += "=" + _serBareItem(val, E);
+  });
+  return out;
+}
+function _serKey(key, E) {
+  if (typeof key !== "string" || key.length === 0 || !(key.charAt(0) === "*" || _isLcAlpha(key.charAt(0)))) throw E("structured-fields/serialize", "invalid parameter/dictionary key");
+  for (var i = 1; i < key.length; i += 1) { if (!_isKeyChar(key.charAt(i))) throw E("structured-fields/serialize", "invalid key character"); }
+  return key;
+}
+function _serItem(item, E) { return _serBareItem(item.value, E) + _serParams(item.params, E); }
+function _serMember(m, E) {
+  if (m && Array.isArray(m.items)) {
+    return "(" + m.items.map(function (it) { return _serItem(it, E); }).join(" ") + ")" + _serParams(m.params, E);
+  }
+  return _serItem(m, E);
+}
+
+/**
+ * @primitive b.structuredFields.serialize
+ * @signature b.structuredFields.serialize(value, type, opts?)
+ * @since     0.12.54
+ * @status    stable
+ * @related   b.structuredFields.parse
+ *
+ * Serialize a value model back to an RFC 8941 field value (the inverse
+ * of <code>parse</code>). <code>type</code> is <code>"item"</code>,
+ * <code>"list"</code>, or <code>"dictionary"</code>. Numbers serialize as
+ * Integers when integral and Decimals (rounded to 3 fractional digits)
+ * otherwise; wrap Tokens / byte strings in <code>SfToken</code> /
+ * <code>SfByteSequence</code>. Throws on values outside the RFC's ranges
+ * or grammar (out-of-range integers, non-printable string characters,
+ * invalid tokens / keys).
+ *
+ * @opts
+ *   ErrorClass?: Function,   // typed error class (default: native Error with .code)
+ *
+ * @example
+ *   var sf = b.structuredFields;
+ *   sf.serialize({ value: new sf.Token("gzip"), params: new Map([["q", 1]]) }, "item");
+ *   // → "gzip;q=1"
+ */
+function serialize(value, type, opts) {
+  var E = _sfErr(opts);
+  if (type === "item") {
+    if (!value || typeof value !== "object" || !("value" in value)) throw E("structured-fields/serialize", "item must be { value, params }");
+    return _serItem(value, E);
+  }
+  if (type === "list") {
+    if (!Array.isArray(value)) throw E("structured-fields/serialize", "list must be an array");
+    return value.map(function (m) { return _serMember(m, E); }).join(", ");
+  }
+  if (type === "dictionary") {
+    var entries = value instanceof Map ? Array.from(value.entries()) : (value && typeof value === "object" ? Object.keys(value).map(function (k) { return [k, value[k]]; }) : null);
+    if (!entries) throw E("structured-fields/serialize", "dictionary must be a Map or object");
+    return entries.map(function (e) {
+      var key = _serKey(e[0], E), m = e[1];
+      if (m && !Array.isArray(m.items) && m.value === true) return key + _serParams(m.params, E);   // bare-true member omits "=?1"
+      return key + "=" + _serMember(m, E);
+    }).join(", ");
+  }
+  throw E("structured-fields/bad-type", "structuredFields.serialize: type must be 'item' | 'list' | 'dictionary'");
+}
+
 module.exports = {
   splitTopLevel:        splitTopLevel,
   refuseControlBytes:   refuseControlBytes,
   containsControlBytes: containsControlBytes,
   unquoteSfString:      unquoteSfString,
+  parse:                parse,
+  serialize:            serialize,
+  Token:                SfToken,
+  ByteSequence:         SfByteSequence,
+  Decimal:              SfDecimal,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.53",
+  "version": "0.12.54",
   "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:20868c28-f68f-42c3-a926-c9e46216c41e",
+  "serialNumber": "urn:uuid:14059245-176a-4c8f-b9d4-123c8285acfa",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-25T18:23:33.227Z",
+    "timestamp": "2026-05-25T19:38:02.951Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.53",
+      "bom-ref": "@blamejs/core@0.12.54",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.53",
+      "version": "0.12.54",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.53",
+      "purl": "pkg:npm/%40blamejs/core@0.12.54",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.53",
+      "ref": "@blamejs/core@0.12.54",
       "dependsOn": []
     }
   ]