@blamejs/core 0.12.54 → 0.12.56

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.56 (2026-05-25) — **`b.canonicalJson` — RFC 8785 JSON Canonicalization Scheme, now a public primitive.** The deterministic JSON serializer the framework uses internally for audit-chain and config-drift fingerprints is now an operator-facing primitive, for signing your own JSON (custom credentials, receipts, deterministic request signing). b.canonicalJson.stringifyJcs is strict RFC 8785: keys sorted in UTF-16 code-unit order at every depth, numbers in the ECMAScript format JCS references, and types JCS does not define (BigInt / Buffer / Date / Map / Set / circular references) refused rather than silently lost. b.canonicalJson.stringify is a lenient variant that also serializes Buffers (hex), Dates (ISO-8601), and BigInts. Exposing it surfaced and fixed a latent ordering bug: the serializer built a sorted-key object and let JSON.stringify emit it, but V8 hoists integer-like keys ("1", "10") to the front — so canonical output was wrong for objects with integer-like string keys. Members are now written in sorted order directly. Validated against the official cyberphone/json-canonicalization conformance vectors. **Added:** *`b.canonicalJson.stringifyJcs(value)` / `stringify(value, opts?)` / `sortKeys(obj)`* — `stringifyJcs` produces strict RFC 8785 canonical JSON — the byte-for-byte stable form to hash or sign — with UTF-16 code-unit key sorting and ECMAScript number formatting, refusing BigInt / Buffer / Date / Map / Set / RegExp / Symbol / function / circular references. `stringify` is the lenient framework variant (Buffers → hex, Dates → ISO-8601, BigInts → decimal; `opts.bufferAs: "reject"` to forbid binary). `sortKeys` returns an object's own keys in the canonical UTF-16 ordering. These were framework-internal; they are now documented public API. **Fixed:** *Canonical JSON now emits integer-like keys in sorted order* — The canonical serializer built a sorted-key object and serialized it with JSON.stringify, which hoists integer-like string keys ("1", "10") to the front per V8 own-property ordering — producing non-canonical output for objects containing such keys (a violation of RFC 8785 §3.2.3). Members are now written in sorted-key order directly. Real-world consumers (audit-chain, config-drift) use named fields and are unaffected; only objects with integer-like string keys change, and the new output is the correct canonical form.
+
+- v0.12.55 (2026-05-25) — **`b.structuredFields` — RFC 9651 Date and Display String types.** Brings the Structured Fields codec up to RFC 9651, which obsoletes RFC 8941 by adding two bare-item types. A Date (`@1659578233`) is an Integer number of seconds since the Unix epoch; a Display String (`%"f%c3%bc%c3%bc"`) is a Unicode string conveyed as percent-escaped UTF-8. parse returns them as distinct SfDate / SfDisplayString values, and serialize emits them canonically — a Date as `@` + integer, a Display String as `%"`-wrapped lowercase-percent-escaped UTF-8 that escapes only what RFC 9651 requires. Parsing is strict: a Date rejects a decimal / out-of-range value, and a Display String rejects uppercase escapes, raw non-ASCII, bad hex, and invalid UTF-8. Validated against the official httpwg structured-field-tests date and display-string vectors. **Added:** *RFC 9651 Date (`@…`) and Display String (`%"…"`) in `b.structuredFields`* — `parse` now reads the two RFC 9651 types: `@` + an Integer yields an `SfDate` (rejecting a decimal `@1.5`, an empty `@`, a sign-only `@-`, and out-of-range values), and `%"…"` yields an `SfDisplayString` (decoding lowercase `%XX` escapes as UTF-8, rejecting uppercase escapes, raw non-ASCII or control characters, malformed hex, and invalid UTF-8). `serialize` is the inverse — a Date as `@` + the integer, a Display String percent-escaping only non-printable / non-ASCII bytes plus `%` and `"`. The new `b.structuredFields.Date` and `b.structuredFields.DisplayString` wrappers construct these values. The module now tracks RFC 9651 (which obsoletes RFC 8941); the existing Item / List / Dictionary parsing is unchanged.
+
 - 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).

package/README.md

@@ -98,7 +98,8 @@ 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
+- **Canonical JSON** — RFC 8785 JSON Canonicalization Scheme (`b.canonicalJson.stringifyJcs`): the deterministic, sorted-key byte form to hash or sign (custom credentials, receipts, deterministic request signing); UTF-16 key ordering + ECMAScript number formatting, with a lenient `stringify` variant for Buffers / Dates / BigInts
+- **Structured Fields** — full RFC 9651 codec (`b.structuredFields.parse` / `serialize`): Items / Lists / Dictionaries, Inner Lists, Parameters, and every bare-item type (Integer / Decimal / String / Token / Byte Sequence / Boolean / Date / Display String) 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/index.js

@@ -396,6 +396,7 @@ var dbsc = require("./lib/dbsc");
 var importmapIntegrity = require("./lib/importmap-integrity");
 var privacyPass = require("./lib/privacy-pass");
 var contentDigest = require("./lib/content-digest");
+var canonicalJson = require("./lib/canonical-json");
 var standardWebhooks = require("./lib/standard-webhooks");
 var lro = require("./lib/lro");
 var jsonApi = require("./lib/jsonapi");
@@ -413,6 +414,7 @@ module.exports = {
   importmapIntegrity: importmapIntegrity,
   privacyPass:      privacyPass,
   contentDigest:    contentDigest,
+  canonicalJson:    canonicalJson,
   standardWebhooks: standardWebhooks,
   lro:              lro,
   jsonApi:          jsonApi,

package/lib/canonical-json.js

@@ -1,79 +1,83 @@
 "use strict";
 /**
- * Canonical JSON — deterministic stringify with sorted keys at every depth.
+ * @module b.canonicalJson
+ * @nav    Data
+ * @title  Canonical JSON
  *
- * Replaces the four near-identical implementations that grew up across
- * `lib/audit-chain.js`, `lib/audit-tools.js`, `lib/config-drift.js`, and
- * `lib/pagination.js`. They all walked `typeof === "object"` with
- * `Object.keys(...).sort()` and silently round-tripped Date as `{}`,
- * Buffer as `{"0":97,"1":98,…}`, Map / Set / RegExp as `{}`, Symbol /
- * function as missing keys, and BigInt as a thrown
- * `Do not know how to serialize a BigInt` mid-emit. Circular references
- * stack-overflowed instead of producing a clean framework error.
+ * @intro
+ *   Deterministic JSON serialization with keys sorted at every depth —
+ *   the byte-for-byte stable form you hash or sign so two parties that
+ *   build the same data produce the same bytes. <code>stringifyJcs</code>
+ *   is strict RFC 8785 (JSON Canonicalization Scheme); <code>stringify</code>
+ *   is a lenient variant that additionally serializes Buffers (as hex),
+ *   Dates (ISO-8601), and BigInts (decimal) for the framework's own audit
+ *   / config-drift fingerprints.
  *
- * The walk:
+ *   Both walks close the silent-data-loss class that ad-hoc
+ *   <code>Object.keys(...).sort()</code> serializers fall into: Map /
+ *   Set / RegExp / class instances, Symbols, functions, and circular
+ *   references all throw a clean error rather than emitting <code>{}</code>
+ *   or stack-overflowing. RFC 8785 strict mode additionally refuses
+ *   BigInt / Buffer / Date (types JCS does not define) so the operator
+ *   converts them to JSON-native shapes before signing.
  *
- *   primitives + null + undefined → JSON.stringify (undefined → "null")
- *   bigint                        → decimal string  ("123" not 123n)
- *   Date                          → ISO string
- *   Buffer / Uint8Array           → hex (when bufferAs = "hex", default)
- *                                   throw     (when bufferAs = "reject")
- *   Map / Set / RegExp            → throw with constructor name
- *   symbol / function             → throw with type name
- *   circular reference            → throw via WeakSet detection
- *   plain array                   → recurse, preserve order
- *   plain object                  → recurse with sorted keys
+ *   Key ordering is V8's <code>Object.keys(...).sort()</code> —
+ *   lexicographic UTF-16 code-unit order, which is exactly RFC 8785
+ *   §3.2.3 — and numbers are formatted by <code>JSON.stringify</code>,
+ *   whose output is the ECMA-262 Number-to-string algorithm that RFC
+ *   8785 §3.2.2.3 references.
  *
- * Two consumer policies on Buffer / Uint8Array are documented because
- * the framework historically chose differently per call site:
- *
- *   bufferAs: "hex"     audit-chain / audit-tools / config-drift —
- *                        binary data is legitimate (cert PEMs, key
- *                        material, hash bytes); preserve as hex so the
- *                        canonical output is reversible.
- *   bufferAs: "reject"  pagination — cursor state is operator-supplied
- *                        primitive data; binary in a cursor is almost
- *                        always a bug; reject loudly.
- *
- * Operators don't call this directly — it's a framework-internal walker.
+ * @card
+ *   Canonical JSON (RFC 8785 JCS) — the deterministic, sorted-key byte
+ *   form you sign or hash. Strict <code>stringifyJcs</code> for
+ *   interop, plus a lenient framework variant that serializes Buffers /
+ *   Dates / BigInts. Lossy ad-hoc serializers (Map / Set / circular →
+ *   <code>{}</code>) are refused.
  */
 
-function _scrub(value, seen, bufferAs) {
-  if (value === null || typeof value === "undefined") return null;
+// Emit the canonical JSON STRING in one ordered pass. Object members are
+// written in sorted-key order directly — building a plain object and
+// relying on JSON.stringify would silently hoist integer-like keys
+// ("1", "10") to the front (V8 own-property ordering), breaking the
+// RFC 8785 §3.2.3 sort. Primitives, strings, and numbers use
+// JSON.stringify, whose escaping (§3.2.2.2) and ECMAScript number format
+// (§3.2.2.3) are exactly what JCS references.
+function _emit(value, seen, bufferAs) {
+  if (value === null || typeof value === "undefined") return "null";
   var t = typeof value;
-  if (t === "string" || t === "boolean" || t === "number") return value;
+  if (t === "number" || t === "string" || t === "boolean") return JSON.stringify(value);
   if (t === "bigint") {
     if (bufferAs === "reject-jcs") {
       throw new Error("canonical-json: BigInt is not serialisable under " +
         "RFC 8785 (JCS); convert to a string or number before passing in");
     }
-    return String(value);
+    return JSON.stringify(String(value));
   }
   if (t === "symbol" || t === "function") {
     throw new Error("canonical-json: " + t + " value is not " +
       "serialisable; convert to a string before passing in");
   }
   // Buffer / Uint8Array — policy-driven
-  if (Buffer.isBuffer(value))           {
+  if (Buffer.isBuffer(value)) {
     if (bufferAs === "reject" || bufferAs === "reject-jcs") {
       throw new Error("canonical-json: Buffer is not serialisable in this " +
         "context (bufferAs=reject); convert to a string or hex first");
     }
-    return value.toString("hex");
+    return JSON.stringify(value.toString("hex"));
   }
   if (value instanceof Uint8Array) {
     if (bufferAs === "reject" || bufferAs === "reject-jcs") {
       throw new Error("canonical-json: Uint8Array is not serialisable in " +
         "this context (bufferAs=reject); convert to a string or hex first");
     }
-    return Buffer.from(value).toString("hex");
+    return JSON.stringify(Buffer.from(value).toString("hex"));
   }
   if (value instanceof Date) {
     if (bufferAs === "reject-jcs") {
       throw new Error("canonical-json: Date is not serialisable under " +
         "RFC 8785 (JCS); convert to ISO-8601 string before passing in");
     }
-    return value.toISOString();
+    return JSON.stringify(value.toISOString());
   }
   // After primitives + Date + Buffer + Uint8Array, any remaining "object"
   // must be a plain object or array. Map / Set / RegExp / class instances
@@ -88,35 +92,73 @@ function _scrub(value, seen, bufferAs) {
   }
   seen.add(value);
   if (Array.isArray(value)) {
-    return value.map(function (v) { return _scrub(v, seen, bufferAs); });
+    // Index loop, not .map(): map() skips holes in a sparse array,
+    // which join() would then render as invalid elisions ([,1]). A hole
+    // reads as undefined → _emit returns "null" (matching JSON.stringify).
+    var items = [];
+    for (var ai = 0; ai < value.length; ai += 1) {
+      items.push(_emit(value[ai], seen, bufferAs));
+    }
+    return "[" + items.join(",") + "]";
   }
   // Canonical-json IS the destination for sorted-keys walks across the
   // codebase; the keys-then-sort here is the canonical primitive itself.
   var keys = Object.keys(value);
   keys.sort();
-  var out = {};
+  var parts = [];
   for (var i = 0; i < keys.length; i++) {
-    out[keys[i]] = _scrub(value[keys[i]], seen, bufferAs);
+    parts.push(JSON.stringify(keys[i]) + ":" + _emit(value[keys[i]], seen, bufferAs));
   }
-  return out;
+  return "{" + parts.join(",") + "}";
 }
 
-// Return the deterministic JSON string. opts.bufferAs picks the Buffer
-// policy ("hex" default, "reject" for callers like pagination).
+/**
+ * @primitive b.canonicalJson.stringify
+ * @signature b.canonicalJson.stringify(value, opts?)
+ * @since     0.5.0
+ * @status    stable
+ * @related   b.canonicalJson.stringifyJcs, b.canonicalJson.sortKeys
+ *
+ * Deterministic JSON with keys sorted at every depth — the lenient
+ * framework variant. Beyond JSON-native values it serializes Buffers /
+ * Uint8Arrays (hex), Dates (ISO-8601), and BigInts (decimal string); Map
+ * / Set / RegExp / class instances, Symbols, functions, and circular
+ * references throw rather than silently emitting <code>{}</code>. Use
+ * <code>stringifyJcs</code> for strict RFC 8785 interop.
+ *
+ * @opts
+ *   bufferAs: string,   // "hex" (default) | "reject" — Buffer / Uint8Array policy
+ *
+ * @example
+ *   b.canonicalJson.stringify({ b: 1, a: 2 });
+ *   // → '{"a":2,"b":1}'
+ */
 function stringify(value, opts) {
   var bufferAs = (opts && opts.bufferAs) || "hex";
   if (bufferAs !== "hex" && bufferAs !== "reject" && bufferAs !== "reject-jcs") {
     throw new Error("canonical-json: bufferAs must be 'hex' / 'reject' / 'reject-jcs'; got " +
       JSON.stringify(bufferAs));
   }
-  return JSON.stringify(_scrub(value, null, bufferAs));
+  return _emit(value, null, bufferAs);
 }
 
-// Stable key ordering for an object — same lexicographic sort used by
-// the canonical-json walker. Exposed so call sites that need a sorted
-// key list (CLI report ordering, fingerprint inputs) route through
-// the framework's single source-of-truth ordering rule rather than
-// re-implementing the keys-then-sort dance inline.
+/**
+ * @primitive b.canonicalJson.sortKeys
+ * @signature b.canonicalJson.sortKeys(obj)
+ * @since     0.5.0
+ * @status    stable
+ * @related   b.canonicalJson.stringify
+ *
+ * The object's own keys in the framework's single canonical ordering —
+ * lexicographic UTF-16 code-unit sort (the same ordering the canonical
+ * serializers use). Returns an empty array for a non-object. Route
+ * fingerprint / report ordering through this rather than re-implementing
+ * the keys-then-sort dance inline.
+ *
+ * @example
+ *   b.canonicalJson.sortKeys({ b: 1, a: 2, c: 3 });
+ *   // → ["a", "b", "c"]
+ */
 function sortKeys(obj) {
   if (!obj || typeof obj !== "object") return [];
   var keys = Object.keys(obj);
@@ -124,16 +166,30 @@ function sortKeys(obj) {
   return keys;
 }
 
-// stringifyJcs — RFC 8785 (JSON Canonicalization Scheme) strict mode.
-// Refuses inputs JCS does NOT cover (BigInt, Buffer / Uint8Array, Date,
-// Map, Set, RegExp, Symbol, function); operators carrying those types
-// must convert to JSON-native shapes upfront. Object key ordering and
-// number formatting already match JCS §3.2.2 — V8's
-// `Object.keys(...).sort()` is lexicographic UTF-16 code-unit order
-// (JCS §3.2.3) and `JSON.stringify` formats numbers per
-// ECMA-262 §7.1.12.1 which JCS §3.2.2.3 references.
+/**
+ * @primitive b.canonicalJson.stringifyJcs
+ * @signature b.canonicalJson.stringifyJcs(value)
+ * @since     0.12.56
+ * @status    stable
+ * @compliance soc2
+ * @related   b.canonicalJson.stringify, b.vc.issue, b.scitt.signStatement
+ *
+ * Strict RFC 8785 JSON Canonicalization Scheme — the deterministic byte
+ * form to hash or sign when two parties must agree on the exact bytes
+ * (signed JSON credentials, receipts, deterministic request signing).
+ * Keys are sorted in UTF-16 code-unit order at every depth (§3.2.3) and
+ * numbers use the ECMAScript Number-to-string formatting §3.2.2.3
+ * references. Inputs JCS does not define — BigInt, Buffer / Uint8Array,
+ * Date, Map, Set, RegExp, Symbol, function, and circular references —
+ * are refused, so the operator converts them to JSON-native shapes
+ * before signing rather than getting a silently lossy result.
+ *
+ * @example
+ *   b.canonicalJson.stringifyJcs({ "€": 1, "$": 2 });
+ *   // → '{"$":2,"€":1}'   (keys sorted by UTF-16 code unit)
+ */
 function stringifyJcs(value) {
-  return JSON.stringify(_scrub(value, null, "reject-jcs"));
+  return _emit(value, null, "reject-jcs");
 }
 
 module.exports = {

package/lib/structured-fields.js

@@ -2,7 +2,7 @@
 /**
  * @module     b.structuredFields
  * @nav        HTTP
- * @title      RFC 8941 Structured Fields helpers
+ * @title      RFC 9651 Structured Fields
  * @order      317
  *
  * @intro
@@ -67,6 +67,10 @@
  *   b.structuredFields.splitTopLevel('alg="x;y";nonce=42', ";");
  *   // → ['alg="x;y"', 'nonce=42']
  */
+// node:util is a builtin (no lib require cycle) — used for strict UTF-8
+// validation of RFC 9651 Display Strings.
+var TextDecoder = require("node:util").TextDecoder;
+
 function splitTopLevel(s, sep) {
   if (typeof s !== "string") return [];
   if (sep !== "," && sep !== ";") {
@@ -237,13 +241,15 @@ function containsControlBytes(value, opts) {
 }
 
 // ---------------------------------------------------------------------------
-// Full RFC 8941 codec (parse + serialize). The helpers above are the
+// Full RFC 9651 codec (parse + serialize; RFC 9651 obsoletes RFC 8941
+// and adds the Date and Display String types). 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
+// Value model (RFC 9651, which obsoletes RFC 8941):
+//   bare item  → number (Integer) | SfDecimal | string | boolean | SfToken
+//                | SfByteSequence | SfDate | SfDisplayString
 //   item       → { value: bareItem, params: Map<string, bareItem> }
 //   inner list → { items: item[], params: Map<string, bareItem> }
 //   list       → (item | innerList)[]
@@ -268,6 +274,18 @@ function SfDecimal(value) {
   if (!(this instanceof SfDecimal)) return new SfDecimal(value);
   this.value = Number(value);
 }
+// RFC 9651 §3.3.7 Date (an Integer number of seconds since the Unix
+// epoch) and §3.3.8 Display String (a Unicode string conveyed as
+// percent-escaped UTF-8). Wrapped so they stay distinct from Integers
+// and plain Strings.
+function SfDate(value) {
+  if (!(this instanceof SfDate)) return new SfDate(value);
+  this.value = Number(value);
+}
+function SfDisplayString(value) {
+  if (!(this instanceof SfDisplayString)) return new SfDisplayString(value);
+  this.value = String(value);
+}
 
 function _sfErr(opts) {
   if (opts && typeof opts.ErrorClass === "function") {
@@ -359,12 +377,47 @@ function _parseToken(cx) {
   return new SfToken(cx.s.slice(start, cx.i));
 }
 
+var _utf8Strict = new TextDecoder("utf-8", { fatal: true });
+
+function _parseDate(cx, E) {
+  cx.i += 1; // "@"
+  var n = _parseNumber(cx, E);
+  if (n instanceof SfDecimal) throw E("structured-fields/parse", "date must be an integer number of seconds");
+  return new SfDate(n);
+}
+
+function _parseDisplayString(cx, E) {
+  cx.i += 1; // "%"
+  if (cx.s.charAt(cx.i) !== "\"") throw E("structured-fields/parse", "display string must open with %\"");
+  cx.i += 1;
+  var bytes = [];
+  while (cx.i < cx.s.length) {
+    var c = cx.s.charAt(cx.i); cx.i += 1;
+    if (c === "%") {
+      var h = cx.s.substr(cx.i, 2);
+      if (h.length !== 2 || !/^[0-9a-f]{2}$/.test(h)) throw E("structured-fields/parse", "display string escape must be %<lowercase-hex><lowercase-hex>");   // allow:raw-byte-literal — RFC 9651 §4.2.10 two-hex-digit escape
+      bytes.push(parseInt(h, 16));
+      cx.i += 2;
+    } else if (c === "\"") {
+      try { return new SfDisplayString(_utf8Strict.decode(Buffer.from(bytes))); }
+      catch (_e) { throw E("structured-fields/parse", "display string is not valid UTF-8"); }
+    } else {
+      var cc = c.charCodeAt(0);
+      if (cc < 0x20 || cc > 0x7e) throw E("structured-fields/parse", "display string contains a raw non-printable / non-ASCII character");   // allow:raw-byte-literal — RFC 9651 §4.2.10 printable-ASCII range
+      bytes.push(cc);
+    }
+  }
+  throw E("structured-fields/parse", "unterminated display string");
+}
+
 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 === "@") return _parseDate(cx, E);
+  if (c === "%") return _parseDisplayString(cx, E);
   if (c === "*" || _isAlpha(c)) return _parseToken(cx);
   throw E("structured-fields/parse", "unexpected character '" + (c || "<eof>") + "' at index " + cx.i);
 }
@@ -455,9 +508,11 @@ function _parseDict(cx, E) {
  * <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
+ * lists; a dictionary is a <code>Map</code>. Tokens, byte sequences,
+ * dates, and display strings come back as <code>SfToken</code> /
+ * <code>SfByteSequence</code> / <code>SfDate</code> /
+ * <code>SfDisplayString</code> instances so they stay distinct from
+ * plain strings and integers. 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).
@@ -493,10 +548,31 @@ function _serDecimal(v, E) {
   if (s.indexOf(".") === -1) s += ".0";                  // a Decimal must carry a fractional part
   return s;
 }
+function _serDisplayString(s, E) {
+  if (typeof s !== "string") throw E("structured-fields/serialize", "display string value must be a string");
+  // RFC 9651 §4.1.10: serialize fails unless the value is a sequence of
+  // Unicode scalar values. A lone UTF-16 surrogate would otherwise be
+  // silently replaced with U+FFFD by Buffer.from, corrupting the output.
+  if (typeof s.isWellFormed === "function" ? !s.isWellFormed() : /[\uD800-\uDFFF]/.test(s.replace(/[\uD800-\uDBFF][\uDC00-\uDFFF]/g, ""))) {
+    throw E("structured-fields/serialize", "display string contains a lone surrogate (not a valid Unicode string)");
+  }
+  var bytes = Buffer.from(s, "utf8"), out = "%\"";
+  for (var i = 0; i < bytes.length; i += 1) {
+    var b = bytes[i];
+    if (b >= 0x20 && b <= 0x7e && b !== 0x25 && b !== 0x22) out += String.fromCharCode(b);   // allow:raw-byte-literal — RFC 9651 §4.1.10 printable ASCII except % and "
+    else out += "%" + (b < 0x10 ? "0" : "") + b.toString(16);                                // allow:raw-byte-literal — lowercase 2-hex escape
+  }
+  return out + "\"";
+}
 function _serBareItem(v, E) {
   if (v === true) return "?1";
   if (v === false) return "?0";
   if (v instanceof SfDecimal) return _serDecimal(v.value, E);
+  if (v instanceof SfDate) {
+    if (!Number.isInteger(v.value) || v.value > INT_MAX || v.value < INT_MIN) throw E("structured-fields/serialize", "date must be an integer in RFC 9651 range");
+    return "@" + String(v.value);
+  }
+  if (v instanceof SfDisplayString) return _serDisplayString(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)) {
@@ -603,4 +679,6 @@ module.exports = {
   Token:                SfToken,
   ByteSequence:         SfByteSequence,
   Decimal:              SfDecimal,
+  Date:                 SfDate,
+  DisplayString:        SfDisplayString,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.54",
+  "version": "0.12.56",
   "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:14059245-176a-4c8f-b9d4-123c8285acfa",
+  "serialNumber": "urn:uuid:e2f305ce-05d6-4941-bcd8-41d2de6298c4",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-25T19:38:02.951Z",
+    "timestamp": "2026-05-25T21:50:24.224Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.54",
+      "bom-ref": "@blamejs/core@0.12.56",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.54",
+      "version": "0.12.56",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.54",
+      "purl": "pkg:npm/%40blamejs/core@0.12.56",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.54",
+      "ref": "@blamejs/core@0.12.56",
       "dependsOn": []
     }
   ]