@blamejs/core 0.12.65 → 0.12.66

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.66 (2026-05-26) — **`b.uriTemplate` — RFC 6570 URI Template expansion.** Expand RFC 6570 URI Templates — the {var} syntax that OpenAPI links, HAL _links, and hypermedia API clients use to turn a template plus a set of variables into a concrete URI. The full Level 4 grammar is supported: every operator ({+var} reserved, {#var} fragment, {.var} label, {/var} path, {;var} path-style parameters, {?var} query, {&var} query continuation), the {var:3} prefix modifier, and the {var*} explode modifier for lists and associative arrays. b.uriTemplate.expand(template, vars) returns the expanded string; b.uriTemplate.compile(template) parses once for templates applied to many variable sets. A malformed template (unclosed expression, reserved operator, non-numeric prefix, unmatched brace) throws UriTemplateError. Verified against the official uritemplate-test conformance suite (all 135 spec, extended, and negative cases). **Added:** *`b.uriTemplate.expand` / `b.uriTemplate.compile`* — RFC 6570 URI Template expansion, full Level 4. `expand(template, vars)` substitutes variables into a template and returns the URI; `compile(template)` returns a reusable `{ expand }` for repeated use. Variable values may be strings, numbers, booleans, arrays (lists), or plain objects (associative arrays); undefined, null, and empty list/map variables are omitted. All eight operators, the `:N` prefix modifier, and the `*` explode modifier follow §3.2, including reserved-set encoding for `{+var}` / `{#var}`. Composes naturally with `b.hal`, `b.linkHeader`, and `b.openapi` link objects. A malformed template throws `UriTemplateError`.
+
 - v0.12.65 (2026-05-26) — **`b.base32` — RFC 4648 Base32 encode / decode.** Encode and decode RFC 4648 Base32 — the case-insensitive alphabet behind TOTP / 2FA secrets, DNSSEC NSEC3 hashes, and human-transcribable identifiers. Both RFC 4648 variants are supported: the standard alphabet (the default) and the extended-hex alphabet. b.base32.encode pads to an 8-character boundary by default (pass padding: false for the bare form TOTP key URIs use); b.base32.decode is strict by default but accepts the real-world shapes humans produce — lower-case, embedded spaces and dashes, missing padding — under loose: true. Verified against the RFC 4648 §10 test vectors for both alphabets. The TOTP primitive now composes this codec instead of carrying its own Base32 implementation. **Added:** *`b.base32.encode` / `b.base32.decode`* — RFC 4648 Base32 codec. `encode(buf, opts)` takes a Buffer or Uint8Array and returns a Base32 string, padded to an 8-character boundary unless `padding: false`; `decode(str, opts)` returns a Buffer. The `variant` option selects the standard (`"rfc4648"`, default) or extended-hex (`"rfc4648-hex"`) alphabet. Decoding is strict by default — any character outside the alphabet throws `Base32Error` — and `loose: true` up-cases the input and ignores embedded spaces, dashes, and missing padding, which is how copied TOTP keys and hand-typed codes arrive. **Changed:** *TOTP composes `b.base32`* — `b.auth.totp` now encodes and decodes its secrets through `b.base32` rather than a private Base32 implementation. Behavior is unchanged — secrets are still emitted unpadded and parsed leniently (case-insensitive, ignoring spaces and dashes).
 
 - v0.12.64 (2026-05-25) — **`b.jsonSchema` — JSON Schema 2020-12 validation.** Validate JSON against a JSON Schema 2020-12 document — the dialect OpenAPI 3.1 adopted and the most widely implemented schema language. b.jsonSchema.compile(schema) returns a reusable validator; b.jsonSchema.validate(schema, instance) compiles and runs in one call, returning { valid, errors } where each error names the failing instance location, keyword, and schema path. The full 2020-12 vocabulary is supported: every applicator (allOf / anyOf / oneOf / not / if-then-else, properties / patternProperties / additionalProperties / prefixItems / items / contains), the annotation-aware unevaluatedProperties / unevaluatedItems, every assertion keyword, and reference resolution ($ref / $anchor / $dynamicRef / $dynamicAnchor / $defs / $id base URIs). format is an annotation by default (opt in to assertion with assertFormat). External references resolve through an operator-supplied schema map — never a network fetch. Verified against the official JSON-Schema-Test-Suite (1292 of 1295 draft2020-12 cases; the remainder need the bundled dialect metaschema or $vocabulary selection, both opt-in). This is the standards-track counterpart to the fluent b.safeSchema builder and the portable b.jtd. **Added:** *`b.jsonSchema` — JSON Schema 2020-12* — `compile(schema, opts)` returns `{ validate, isValid }`; `validate(schema, instance, opts)` and `isValid(schema, instance, opts)` compile and run in one call. `validate` returns `{ valid, errors }`, each error a `{ instancePath, keyword, schemaPath, message }`. The full 2020-12 vocabulary is implemented — applicators, annotation-aware `unevaluatedProperties` / `unevaluatedItems`, every assertion keyword, and `$ref` / `$anchor` / `$dynamicRef` / `$dynamicAnchor` / `$defs` / `$id` resolution. `format` is an annotation by default (`assertFormat: true` to assert). External references resolve through `opts.schemas` (a URI→schema map), never a network fetch. Reach for it when the schema is an existing JSON Schema document (an API contract, OpenAPI component, or config schema); `b.safeSchema` remains the fluent in-process builder and `b.jtd` the portable codegen-friendly option. Validating a schema document against the dialect metaschema requires supplying that metaschema via `opts.schemas`, and `$vocabulary`-based keyword selection is not honored (every standard keyword always asserts).

package/README.md

@@ -99,6 +99,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **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)
+- **URI Templates** — RFC 6570 expansion (`b.uriTemplate.expand` / `compile`): full Level 4 — every operator, the `:N` prefix and `*` explode modifiers — turning `{/path}{?q*}` plus variables into a concrete URI; validated against the official uritemplate-test suite. The `{var}` syntax behind OpenAPI links and HAL `_links`
 - **JSON Type Definition** — RFC 8927 validation (`b.jtd.validate` / `isValid`): portable, cross-implementation schema validation (all eight forms — type / enum / elements / properties / values / discriminator / ref / empty), returning instancePath / schemaPath errors; validated against the official 316-case suite. Interop companion to the fluent `b.safeSchema` builder
 - **JSON Schema 2020-12** — the OpenAPI 3.1 dialect (`b.jsonSchema.compile` / `validate` / `isValid`): full vocabulary including every applicator, annotation-aware `unevaluatedProperties` / `unevaluatedItems`, and `$ref` / `$dynamicRef` / `$anchor` / `$id` resolution (external refs via an operator-supplied schema map, never a network fetch); `format` is an annotation unless `assertFormat` is set; returns located `{ valid, errors }`. Validated against the official JSON-Schema-Test-Suite. Standards-track counterpart to `b.safeSchema` and `b.jtd`
 - **Base32** — RFC 4648 codec (`b.base32.encode` / `decode`): standard + extended-hex alphabets, padded or bare, strict or lenient decode (case-insensitive, ignoring spaces / dashes for copied TOTP keys); validated against the RFC 4648 §10 vectors. The codec behind `b.auth.totp` secrets

package/index.js

@@ -405,6 +405,7 @@ var jsonPath = require("./lib/json-path");
 var jtd = require("./lib/jtd");
 var jsonSchema = require("./lib/json-schema");
 var base32 = require("./lib/base32");
+var uriTemplate = require("./lib/uri-template");
 var standardWebhooks = require("./lib/standard-webhooks");
 var lro = require("./lib/lro");
 var jsonApi = require("./lib/jsonapi");
@@ -431,6 +432,7 @@ module.exports = {
   jtd:              jtd,
   jsonSchema:       jsonSchema,
   base32:           base32,
+  uriTemplate:      uriTemplate,
   standardWebhooks: standardWebhooks,
   lro:              lro,
   jsonApi:          jsonApi,

package/lib/uri-template.js

@@ -0,0 +1,286 @@
+"use strict";
+/**
+ * @module b.uriTemplate
+ * @nav    HTTP
+ * @title  URI Templates
+ *
+ * @intro
+ *   Expand <a href="https://www.rfc-editor.org/rfc/rfc6570">RFC 6570</a> URI
+ *   Templates — the <code>{var}</code> syntax that OpenAPI links, HAL
+ *   <code>_links</code>, and hypermedia API clients use to turn a template
+ *   plus a set of variables into a concrete URI. The full Level 4 grammar
+ *   is supported: every operator (<code>{+var}</code> reserved,
+ *   <code>{#var}</code> fragment, <code>{.var}</code> label,
+ *   <code>{/var}</code> path, <code>{;var}</code> path-style parameters,
+ *   <code>{?var}</code> query, <code>{&amp;var}</code> query continuation),
+ *   the <code>{var:3}</code> prefix modifier, and the <code>{var*}</code>
+ *   explode modifier for lists and associative arrays.
+ *
+ *   <code>expand(template, vars)</code> returns the expanded string;
+ *   <code>compile(template)</code> parses once and returns a reusable
+ *   <code>{ expand }</code> for templates applied to many variable sets. A
+ *   malformed template (an unclosed expression, an unknown operator, or a
+ *   non-numeric prefix) throws <code>UriTemplateError</code>.
+ *
+ * @card
+ *   RFC 6570 URI Template expansion (full Level 4 — every operator, the
+ *   <code>:N</code> prefix and <code>*</code> explode modifiers) — the
+ *   <code>{var}</code> syntax behind OpenAPI links and HAL hypermedia.
+ */
+
+var { defineClass } = require("./framework-error");
+
+var UriTemplateError = defineClass("UriTemplateError", { alwaysPermanent: true });
+
+var MAX_PREFIX = 10000;                                     // allow:raw-byte-literal — RFC 6570 caps prefix length at 9999
+
+// Operator table (RFC 6570 §2.2 / §3.2.1). first = prefix when any value is
+// present; sep = separator between values; named = emit "name=value";
+// ifemp = string used when a named value is empty; reserved = allow the
+// reserved set through unencoded.
+var OPERATORS = {
+  "":  { first: "",  sep: ",", named: false, ifemp: "",  reserved: false },
+  "+": { first: "",  sep: ",", named: false, ifemp: "",  reserved: true },
+  "#": { first: "#", sep: ",", named: false, ifemp: "",  reserved: true },
+  ".": { first: ".", sep: ".", named: false, ifemp: "",  reserved: false },
+  "/": { first: "/", sep: "/", named: false, ifemp: "",  reserved: false },
+  ";": { first: ";", sep: ";", named: true,  ifemp: "",  reserved: false },
+  "?": { first: "?", sep: "&", named: true,  ifemp: "=", reserved: false },
+  "&": { first: "&", sep: "&", named: true,  ifemp: "=", reserved: false },
+};
+
+var UNRESERVED = /[A-Za-z0-9\-._~]/;
+// Reserved = gen-delims + sub-delims (RFC 3986 §2.2).
+var RESERVED = /[:/?#[\]@!$&'()*+,;=]/;
+
+function _pctEncode(str, allowReserved) {
+  var out = "";
+  for (var i = 0; i < str.length; i++) {
+    var ch = str.charAt(i);
+    // Preserve existing percent-encoded triplets when the reserved set is
+    // allowed (operators "+" and "#").
+    if (allowReserved && ch === "%" && /^[0-9A-Fa-f]{2}$/.test(str.substr(i + 1, 2))) {
+      out += str.substr(i, 3); i += 2; continue;
+    }
+    if (UNRESERVED.test(ch) || (allowReserved && RESERVED.test(ch))) { out += ch; continue; }
+    // Percent-encode the character's raw UTF-8 bytes (handles surrogate
+    // pairs). encodeURIComponent is not used — it leaves !*'() unencoded,
+    // which RFC 6570 unreserved-only expansion must escape.
+    var cp = str.codePointAt(i);
+    var bytes = Buffer.from(String.fromCodePoint(cp), "utf8");
+    for (var b = 0; b < bytes.length; b++) out += "%" + bytes[b].toString(16).toUpperCase().padStart(2, "0");   // allow:raw-byte-literal — hex radix
+    if (cp > 0xFFFF) i++;   // consumed a surrogate pair   // allow:raw-byte-literal — BMP boundary for surrogate-pair detection
+  }
+  return out;
+}
+
+function _allDigits(s) {
+  if (s.length === 0) return false;
+  for (var i = 0; i < s.length; i++) { var c = s.charCodeAt(i); if (c < 48 || c > 57) return false; }   // allow:raw-byte-literal — ASCII '0'..'9' code-point bounds
+  return true;
+}
+
+// A composite member/value is "defined" unless it is undefined or null
+// (an empty string, 0, or false is defined and expands).
+function _memberDefined(v) { return v !== undefined && v !== null; }
+
+function _isDefined(v) {
+  if (v === undefined || v === null) return false;
+  if (Array.isArray(v)) return v.length > 0;
+  if (typeof v === "object") return Object.keys(v).length > 0;
+  return true;
+}
+function _toStr(v) {
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  return String(v);
+}
+
+// A literal run may not contain a stray "}" (an unmatched expression close)
+// — RFC 6570 literals exclude "{" and "}".
+function _checkLiteral(lit) {
+  if (lit.indexOf("}") !== -1) throw new UriTemplateError("uri-template/unmatched-brace", "uriTemplate: unmatched '}' in template literal");
+}
+
+// Parse a template into an array of literal strings + expression objects.
+function _parse(template) {
+  if (typeof template !== "string") throw new UriTemplateError("uri-template/bad-template", "uriTemplate: template must be a string");
+  var parts = [];
+  var i = 0;
+  while (i < template.length) {
+    var open = template.indexOf("{", i);
+    if (open === -1) { _checkLiteral(template.slice(i)); parts.push({ literal: template.slice(i) }); break; }
+    if (open > i) { _checkLiteral(template.slice(i, open)); parts.push({ literal: template.slice(i, open) }); }
+    var close = template.indexOf("}", open);
+    if (close === -1) throw new UriTemplateError("uri-template/unclosed", "uriTemplate: unclosed expression at index " + open);
+    parts.push(_parseExpr(template.slice(open + 1, close)));
+    i = close + 1;
+  }
+  return parts;
+}
+
+function _parseExpr(body) {
+  if (body.length === 0) throw new UriTemplateError("uri-template/empty-expression", "uriTemplate: empty expression {}");
+  var op = "";
+  var c0 = body.charAt(0);
+  if ("+#./;?&".indexOf(c0) !== -1) { op = c0; body = body.slice(1); }
+  else if ("=,!@|".indexOf(c0) !== -1) {
+    // Operators reserved by RFC 6570 §2.2 for future extensions → error.
+    throw new UriTemplateError("uri-template/reserved-operator", "uriTemplate: operator '" + c0 + "' is reserved");
+  }
+  var specs = body.split(",").map(function (raw) {
+    if (raw.length === 0) throw new UriTemplateError("uri-template/bad-varspec", "uriTemplate: empty variable name");
+    var explode = false, prefix = null;
+    var name = raw;
+    if (raw.charAt(raw.length - 1) === "*") { explode = true; name = raw.slice(0, -1); }
+    else {
+      var colon = raw.indexOf(":");
+      if (colon !== -1) {
+        name = raw.slice(0, colon);
+        var n = raw.slice(colon + 1);
+        if (!_allDigits(n)) throw new UriTemplateError("uri-template/bad-prefix", "uriTemplate: prefix length must be a non-negative integer");
+        prefix = parseInt(n, 10);
+        if (prefix >= MAX_PREFIX) throw new UriTemplateError("uri-template/bad-prefix", "uriTemplate: prefix length exceeds 9999");
+      }
+    }
+    if (!/^(?:[A-Za-z0-9_]|%[0-9A-Fa-f]{2})(?:\.?(?:[A-Za-z0-9_]|%[0-9A-Fa-f]{2}))*$/.test(name)) {
+      throw new UriTemplateError("uri-template/bad-varname", "uriTemplate: invalid variable name '" + name + "'");
+    }
+    return { name: name, explode: explode, prefix: prefix };
+  });
+  return { op: op, specs: specs };
+}
+
+function _expandExpr(expr, vars) {
+  var o = OPERATORS[expr.op];
+  var pieces = [];
+  expr.specs.forEach(function (spec) {
+    var value = vars[spec.name];
+    if (!_isDefined(value)) return;
+
+    if (typeof value !== "object") {
+      // Simple string/number/boolean value.
+      var s = _toStr(value);
+      if (spec.prefix !== null) s = _sliceChars(s, spec.prefix);
+      pieces.push(_named(o, spec.name, _pctEncode(s, o.reserved), s.length === 0));
+    } else if (Array.isArray(value)) {
+      if (spec.prefix !== null) throw new UriTemplateError("uri-template/prefix-on-list", "uriTemplate: prefix modifier cannot apply to a list");
+      // Undefined / null members are ignored (RFC 6570 §3.2.1); a list with
+      // no defined members is treated as undefined and omitted entirely.
+      var members = value.filter(_memberDefined);
+      if (members.length === 0) return;
+      if (!spec.explode) {
+        var joined = members.map(function (m) { return _pctEncode(_toStr(m), o.reserved); }).join(",");
+        pieces.push(_named(o, spec.name, joined, false));
+      } else {
+        members.forEach(function (m) {
+          pieces.push(_named(o, spec.name, _pctEncode(_toStr(m), o.reserved), _toStr(m).length === 0));
+        });
+      }
+    } else {
+      // Associative array (object). Pairs whose value is undefined / null
+      // are omitted (RFC 6570 §3.2.1).
+      if (spec.prefix !== null) throw new UriTemplateError("uri-template/prefix-on-map", "uriTemplate: prefix modifier cannot apply to a map");
+      var keys = Object.keys(value).filter(function (k) { return _memberDefined(value[k]); });
+      if (keys.length === 0) return;
+      if (!spec.explode) {
+        var pairs = [];
+        keys.forEach(function (k) { pairs.push(_pctEncode(k, o.reserved)); pairs.push(_pctEncode(_toStr(value[k]), o.reserved)); });
+        pieces.push(_named(o, spec.name, pairs.join(","), false));
+      } else {
+        keys.forEach(function (k) {
+          // Exploded map: the key becomes the name.
+          pieces.push(_namedPair(o, _pctEncode(k, o.reserved), _pctEncode(_toStr(value[k]), o.reserved)));
+        });
+      }
+    }
+  });
+  if (pieces.length === 0) return "";
+  return o.first + pieces.join(o.sep);
+}
+
+// Build one "name=value" (or bare value) piece for a non-exploded or
+// string varspec.
+function _named(o, name, encodedValue, isEmpty) {
+  if (!o.named) return encodedValue;
+  if (isEmpty) return name + o.ifemp;
+  return name + "=" + encodedValue;
+}
+// Exploded map pair: key is already the name.
+function _namedPair(o, encodedKey, encodedValue) {
+  if (!o.named) return encodedKey + "=" + encodedValue;
+  if (encodedValue.length === 0) return encodedKey + o.ifemp;
+  return encodedKey + "=" + encodedValue;
+}
+
+// Truncate to N Unicode code points (RFC 6570 prefix length is in chars).
+function _sliceChars(s, n) {
+  var out = "", count = 0;
+  for (var i = 0; i < s.length && count < n; i++) {
+    var cp = s.codePointAt(i);
+    out += String.fromCodePoint(cp);
+    if (cp > 0xFFFF) i++;   // allow:raw-byte-literal — BMP boundary for surrogate pairs
+    count++;
+  }
+  return out;
+}
+
+/**
+ * @primitive  b.uriTemplate.compile
+ * @signature  b.uriTemplate.compile(template)
+ * @since      0.12.66
+ * @status     stable
+ * @related    b.uriTemplate.expand, b.hal, b.linkHeader
+ *
+ * Parse an RFC 6570 URI Template once and return a reusable
+ * <code>{ expand(vars) }</code>, so a template applied to many variable
+ * sets is parsed a single time. Throws <code>UriTemplateError</code> if the
+ * template is malformed.
+ *
+ * @example
+ *   var t = b.uriTemplate.compile("/users/{id}{?fields*}");
+ *   t.expand({ id: 7, fields: ["name", "email"] });
+ *   // → "/users/7?fields=name&fields=email"
+ */
+function compile(template) {
+  var parts = _parse(template);
+  return {
+    expand: function (vars) {
+      vars = vars || {};
+      var out = "";
+      for (var i = 0; i < parts.length; i++) {
+        out += Object.prototype.hasOwnProperty.call(parts[i], "literal") ? parts[i].literal : _expandExpr(parts[i], vars);
+      }
+      return out;
+    },
+  };
+}
+
+/**
+ * @primitive  b.uriTemplate.expand
+ * @signature  b.uriTemplate.expand(template, vars)
+ * @since      0.12.66
+ * @status     stable
+ * @related    b.uriTemplate.compile
+ *
+ * Expand an RFC 6570 URI Template against a set of variables and return the
+ * resulting URI string. Variable values may be strings, numbers, booleans,
+ * arrays (lists), or plain objects (associative arrays); an undefined,
+ * null, or empty list/map variable is omitted. Reserved-set encoding,
+ * <code>:N</code> prefixes, and <code>*</code> explosion follow RFC 6570
+ * §3.2. Throws <code>UriTemplateError</code> on a malformed template.
+ *
+ * @example
+ *   b.uriTemplate.expand("{/path}/here{?q,limit}",
+ *     { path: "search", q: "json schema", limit: 10 });
+ *   // → "/search/here?q=json%20schema&limit=10"
+ */
+function expand(template, vars) {
+  return compile(template).expand(vars);
+}
+
+module.exports = {
+  expand:           expand,
+  compile:          compile,
+  UriTemplateError: UriTemplateError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.65",
+  "version": "0.12.66",
   "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:9f4770af-2b1a-425d-be19-619f1b638c9e",
+  "serialNumber": "urn:uuid:4e9da547-078d-46ac-833b-3eae7e281a06",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-26T08:53:06.102Z",
+    "timestamp": "2026-05-26T10:01:10.136Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.65",
+      "bom-ref": "@blamejs/core@0.12.66",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.65",
+      "version": "0.12.66",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.65",
+      "purl": "pkg:npm/%40blamejs/core@0.12.66",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.65",
+      "ref": "@blamejs/core@0.12.66",
       "dependsOn": []
     }
   ]