@blamejs/core 0.12.56 → 0.12.57

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.57 (2026-05-25) — **`b.linkHeader` — RFC 8288 Web Linking (HTTP Link header) codec.** Parse and build the HTTP Link header (RFC 8288) — the standard way to convey resource relations, most visibly REST pagination (Link: <…?page=2>; rel="next"). b.linkHeader.parse returns one { uri, rel, params } per link, splitting multiple links on top-level commas and unwrapping quoted parameter values via the framework's RFC 8941 structured-field helpers, so a comma inside a quoted title never fake-splits the list; rel is exposed as its array of space-separated relation types. b.linkHeader.serialize is the inverse, angle-bracketing the URI, emitting rel first, and double-quoting parameter values. Verified against the RFC 8288 §3.5 examples and GitHub-style pagination links. **Added:** *`b.linkHeader.parse(headerValue)` / `b.linkHeader.serialize(links)`* — `parse` reads an HTTP Link header into `[{ uri, rel, params }]` — `uri` is the angle-bracketed target, `rel` the array of space-separated relation types, `params` the remaining parameters with quoted values unwrapped (a repeated parameter keeps the first occurrence per RFC 8288 §3.4). It refuses a link without a bracketed URI, an unterminated URI or quoted parameter, control bytes, and oversized headers. `serialize` builds the header value from `{ uri, rel, params? }` objects (or a single one), angle-bracketing the URI and double-quoting parameter values. Composes the framework's structured-field splitter so quoting is handled consistently; pair with `b.pagination` to emit standard `rel="next"` / `rel="prev"` navigation.
+
 - 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.

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
+- **Link header** — RFC 8288 Web Linking codec (`b.linkHeader.parse` / `serialize`): parse and build `Link: <uri>; rel="next"` relations, the standard REST pagination mechanism; quote-aware (a comma inside a quoted parameter never splits the list)
 - **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`)

package/index.js

@@ -397,6 +397,7 @@ 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 linkHeader = require("./lib/link-header");
 var standardWebhooks = require("./lib/standard-webhooks");
 var lro = require("./lib/lro");
 var jsonApi = require("./lib/jsonapi");
@@ -415,6 +416,7 @@ module.exports = {
   privacyPass:      privacyPass,
   contentDigest:    contentDigest,
   canonicalJson:    canonicalJson,
+  linkHeader:       linkHeader,
   standardWebhooks: standardWebhooks,
   lro:              lro,
   jsonApi:          jsonApi,

package/lib/link-header.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * @module b.linkHeader
+ * @nav    HTTP
+ * @title  Link header
+ *
+ * @intro
+ *   Parse and build the HTTP <code>Link</code> header (RFC 8288 Web
+ *   Linking) — the standard way to convey relations between resources,
+ *   most visibly REST pagination
+ *   (<code>Link: &lt;…?page=2&gt;; rel="next"</code>). A header carries
+ *   one or more comma-separated links, each an angle-bracketed URI
+ *   reference followed by <code>;</code>-separated parameters
+ *   (<code>rel</code>, <code>title</code>, <code>type</code>, …).
+ *
+ *   <code>parse</code> returns one object per link with its
+ *   <code>uri</code>, the (space-split) <code>rel</code> relation types,
+ *   and the remaining <code>params</code>; <code>serialize</code> is the
+ *   inverse. The comma split and quoted-parameter unwrapping reuse the
+ *   framework's RFC 8941 structured-field helpers so a comma inside a
+ *   quoted <code>title</code> never fake-splits the list.
+ *
+ * @card
+ *   HTTP Link header codec (RFC 8288 Web Linking) — parse and build
+ *   <code>Link: &lt;uri&gt;; rel="next"</code> relations, the standard
+ *   REST pagination mechanism. Quote-aware so a comma inside a quoted
+ *   parameter never splits the list.
+ */
+
+var structuredFields = require("./structured-fields");
+var { defineClass } = require("./framework-error");
+
+var LinkHeaderError = defineClass("LinkHeaderError", { alwaysPermanent: true });
+
+var MAX_HEADER_BYTES = 16384;                                // allow:raw-byte-literal — defensive cap on a parsed Link header
+
+// Split a Link header on the commas that separate links — those OUTSIDE
+// a <uri-reference> and outside a quoted-string. structuredFields'
+// splitter is quote-aware but not angle-bracket-aware, so a comma inside
+// a URI (`<https://x/a,b>`) must not split the list (RFC 8288 §3.5).
+function _splitLinks(s) {
+  var out = [], start = 0, inUri = false, inQuote = false, esc = false;
+  for (var i = 0; i < s.length; i += 1) {
+    var c = s.charAt(i);
+    if (esc) { esc = false; continue; }
+    if (inQuote) { if (c === "\\") esc = true; else if (c === "\"") inQuote = false; continue; }
+    if (c === "\"") { inQuote = true; }
+    else if (c === "<") { inUri = true; }
+    else if (c === ">") { inUri = false; }
+    else if (c === "," && !inUri) { out.push(s.slice(start, i)); start = i + 1; }
+  }
+  out.push(s.slice(start));
+  return out;
+}
+
+/**
+ * @primitive b.linkHeader.parse
+ * @signature b.linkHeader.parse(headerValue)
+ * @since     0.12.57
+ * @status    stable
+ * @related   b.linkHeader.serialize, b.pagination.cursor
+ *
+ * Parse an HTTP <code>Link</code> header value (RFC 8288) into an array
+ * of <code>{ uri, rel, params }</code> — one per link. <code>uri</code>
+ * is the angle-bracketed target, <code>rel</code> is the array of
+ * (space-separated) relation types, and <code>params</code> is the
+ * remaining parameters with quoted values unwrapped. A comma inside a
+ * quoted parameter value does not split the list. A link without a
+ * bracketed URI is refused.
+ *
+ * @example
+ *   b.linkHeader.parse('<https://api/x?page=2>; rel="next", <https://api/x?page=9>; rel="last"');
+ *   // → [ { uri: "https://api/x?page=2", rel: ["next"], params: {} },
+ *   //     { uri: "https://api/x?page=9", rel: ["last"], params: {} } ]
+ */
+function parse(headerValue) {
+  if (typeof headerValue !== "string") throw new LinkHeaderError("link-header/bad-input", "linkHeader.parse: headerValue must be a string");
+  if (headerValue.length > MAX_HEADER_BYTES) throw new LinkHeaderError("link-header/too-large", "linkHeader.parse: Link header exceeds " + MAX_HEADER_BYTES + " bytes");
+  structuredFields.refuseControlBytes(headerValue, { ErrorClass: LinkHeaderError, code: "link-header/bad-input", label: "Link header" });
+  var out = [];
+  var members = _splitLinks(headerValue);
+  for (var i = 0; i < members.length; i++) {
+    var raw = members[i].trim();
+    if (raw === "") continue;
+    if (raw.charAt(0) !== "<") throw new LinkHeaderError("link-header/bad-link", "linkHeader.parse: link must start with a <uri-reference>");
+    var close = raw.indexOf(">");
+    if (close === -1) throw new LinkHeaderError("link-header/bad-link", "linkHeader.parse: unterminated <uri-reference>");
+    var uri = raw.slice(1, close);
+    var rest = raw.slice(close + 1);
+    var paramParts = structuredFields.splitTopLevel(rest, ";");
+    var rel = [], relSet = false, params = Object.create(null);
+    for (var p = 0; p < paramParts.length; p++) {
+      var piece = paramParts[p].trim();
+      if (piece === "") continue;
+      var eq = piece.indexOf("=");
+      var name = (eq === -1 ? piece : piece.slice(0, eq)).trim().toLowerCase();
+      if (name === "") continue;
+      var value = eq === -1 ? "" : structuredFields.unquoteSfString(piece.slice(eq + 1).trim());
+      if (value === null) throw new LinkHeaderError("link-header/bad-link", "linkHeader.parse: unterminated quoted parameter on '" + name + "'");
+      // RFC 8288 §3.3 / §3.4: a repeated rel (or any parameter) keeps the
+      // FIRST occurrence; later ones are ignored.
+      if (name === "rel") { if (!relSet) { rel = value.split(/\s+/).filter(Boolean); relSet = true; } continue; }
+      if (!(name in params)) params[name] = value;
+    }
+    out.push({ uri: uri, rel: rel, params: params });
+  }
+  return out;
+}
+
+// Quote every parameter value (always valid RFC 8288, and required for
+// space-separated multi-rel and non-token values like "text/html"); the
+// 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, "\\\"") + "\"";
+}
+
+/**
+ * @primitive b.linkHeader.serialize
+ * @signature b.linkHeader.serialize(links)
+ * @since     0.12.57
+ * @status    stable
+ * @related   b.linkHeader.parse
+ *
+ * Build an HTTP <code>Link</code> header value from an array of
+ * <code>{ uri, rel, params? }</code> (or a single such object). The URI
+ * is angle-bracketed, <code>rel</code> (string or array) is emitted
+ * first, and parameters are token-valued when they fit RFC 7230 token
+ * grammar or double-quoted otherwise. Useful for emitting standard REST
+ * pagination links.
+ *
+ * @example
+ *   b.linkHeader.serialize([
+ *     { uri: "https://api/x?page=2", rel: "next" },
+ *     { uri: "https://api/x?page=9", rel: "last", params: { title: "end" } },
+ *   ]);
+ *   // → '<https://api/x?page=2>; rel="next", <https://api/x?page=9>; rel="last"; title="end"'
+ */
+function serialize(links) {
+  var arr = Array.isArray(links) ? links : [links];
+  var parts = [];
+  for (var i = 0; i < arr.length; i++) {
+    var link = arr[i];
+    if (!link || typeof link !== "object" || typeof link.uri !== "string" || link.uri === "") {
+      throw new LinkHeaderError("link-header/bad-link", "linkHeader.serialize: links[" + i + "] requires a non-empty uri");
+    }
+    if (link.uri.indexOf(">") !== -1 || link.uri.indexOf("<") !== -1) {
+      throw new LinkHeaderError("link-header/bad-link", "linkHeader.serialize: uri must not contain angle brackets");
+    }
+    var seg = "<" + link.uri + ">";
+    var rel = Array.isArray(link.rel) ? link.rel.join(" ") : (link.rel || "");
+    if (rel !== "") seg += "; " + _serParam("rel", rel);
+    if (link.params && typeof link.params === "object") {
+      var keys = Object.keys(link.params);
+      for (var k = 0; k < keys.length; k++) {
+        if (keys[k].toLowerCase() === "rel") continue;        // rel is emitted from link.rel
+        seg += "; " + _serParam(keys[k].toLowerCase(), link.params[keys[k]]);
+      }
+    }
+    parts.push(seg);
+  }
+  return parts.join(", ");
+}
+
+module.exports = {
+  parse:           parse,
+  serialize:       serialize,
+  LinkHeaderError: LinkHeaderError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.56",
+  "version": "0.12.57",
   "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:e2f305ce-05d6-4941-bcd8-41d2de6298c4",
+  "serialNumber": "urn:uuid:a145d843-4618-44c4-8e2b-082f70687064",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-25T21:50:24.224Z",
+    "timestamp": "2026-05-25T23:07:17.164Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.56",
+      "bom-ref": "@blamejs/core@0.12.57",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.56",
+      "version": "0.12.57",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.56",
+      "purl": "pkg:npm/%40blamejs/core@0.12.57",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.56",
+      "ref": "@blamejs/core@0.12.57",
       "dependsOn": []
     }
   ]