@blamejs/core 0.12.64 → 0.12.65

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- 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).
 
 - v0.12.63 (2026-05-25) — **`b.cloudEvents` gains the JSON event format, batch, and the HTTP binding.** b.cloudEvents grows beyond wrap / parse into a full CloudEvents 1.0.2 surface. b.cloudEvents.validate / isValid check an envelope against the spec without throwing (the non-throwing companion to parse). toJSON / fromJSON serialize and parse the JSON event format, and toJSONBatch / fromJSONBatch handle the JSON batch format; untrusted bodies parse through the framework's bounded, prototype-pollution-safe JSON reader. The new http.* binding speaks both content modes the spec defines — binary mode spreads context attributes across percent-encoded ce-* headers with the data in the body, structured mode carries the whole event as application/cloudevents+json — plus the batch mode, and http.decode auto-detects the incoming mode from Content-Type exactly as a conformant receiver does. Verified against the spec's normative example events. **Added:** *`b.cloudEvents` JSON event format, batch, and HTTP binding* — `validate` / `isValid` report spec violations without throwing (the non-throwing companion to `parse`). `toJSON` / `fromJSON` and `toJSONBatch` / `fromJSONBatch` serialize and parse the JSON event and batch formats over the existing envelope shape. `http.encodeBinary` / `http.encodeStructured` / `http.encodeBatch` render the three HTTP content modes — binary spreads attributes across percent-encoded `ce-*` headers, structured and batched carry the event(s) as `application/cloudevents+json` / `application/cloudevents-batch+json` — and `http.decode` parses a request back into an envelope (or array) by auto-detecting the mode from `Content-Type`. `b.jtd` or `b.safeSchema` still validate the event's `data` payload. **Fixed:** *`b.csp.build` accepts `fenced-frame-src` and `webrtc`* — The CSP3 `fenced-frame-src` directive — which the default security-headers policy emits to block `<fencedframe>` embeds — was missing from the builder's recognized-directive set, so the default policy could not round-trip through `b.csp.build` (it threw `csp/unknown-directive`). Both `fenced-frame-src` and the CSP3 `webrtc` directive are now recognized.

package/README.md

@@ -101,6 +101,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **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)
 - **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
 - **JSONPath** — full RFC 9535 query evaluator (`b.jsonPath.query` / `paths`): name / wildcard / index / slice / descendant selectors, `?filter` expressions, and the five standard functions, with compile-time well-typedness checks (validated against the official 703-case compliance suite); complements the JSONPath guards
 - **JSON Pointer / Patch** — RFC 6901 `b.jsonPointer.get` (reference a value by `/foo/0/bar`) + RFC 6902 `b.jsonPatch.apply` (atomic add / remove / replace / move / copy / test for HTTP PATCH; the input document is never mutated, structural `test` comparison) + RFC 7396 `b.jsonMergePatch.merge` (the `merge-patch+json` partial-document format; both PATCH formats are prototype-pollution-safe)
 - **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

package/index.js

@@ -404,6 +404,7 @@ var jsonMergePatch = require("./lib/json-merge-patch");
 var jsonPath = require("./lib/json-path");
 var jtd = require("./lib/jtd");
 var jsonSchema = require("./lib/json-schema");
+var base32 = require("./lib/base32");
 var standardWebhooks = require("./lib/standard-webhooks");
 var lro = require("./lib/lro");
 var jsonApi = require("./lib/jsonapi");
@@ -429,6 +430,7 @@ module.exports = {
   jsonPath:         jsonPath,
   jtd:              jtd,
   jsonSchema:       jsonSchema,
+  base32:           base32,
   standardWebhooks: standardWebhooks,
   lro:              lro,
   jsonApi:          jsonApi,

package/lib/base32.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * @module b.base32
+ * @nav    Data
+ * @title  Base32
+ *
+ * @intro
+ *   Encode and decode <a href="https://www.rfc-editor.org/rfc/rfc4648">RFC
+ *   4648</a> Base32 — the case-insensitive, digit-light alphabet used for
+ *   TOTP / 2FA secrets, DNSSEC NSEC3 hashes, and human-transcribable
+ *   identifiers. Both RFC 4648 variants are supported: the standard
+ *   alphabet (<code>variant: "rfc4648"</code>, default) and the
+ *   extended-hex alphabet (<code>variant: "rfc4648-hex"</code>, which sorts
+ *   in the same order as the underlying bytes).
+ *
+ *   <code>encode</code> pads to an 8-character boundary with
+ *   <code>=</code> by default (pass <code>padding: false</code> for the
+ *   bare form TOTP key URIs use). <code>decode</code> is strict by default
+ *   — it rejects any character outside the alphabet — but
+ *   <code>loose: true</code> accepts the real-world shapes humans produce:
+ *   lower-case input, embedded spaces and dashes, and missing padding.
+ *
+ * @card
+ *   RFC 4648 Base32 encode / decode (standard + extended-hex alphabets,
+ *   padded or bare, strict or lenient) — the codec behind TOTP secrets and
+ *   transcribable identifiers.
+ */
+
+var { defineClass } = require("./framework-error");
+
+var Base32Error = defineClass("Base32Error", { alwaysPermanent: true });
+
+var ALPHABETS = {
+  "rfc4648": "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567",
+  "rfc4648-hex": "0123456789ABCDEFGHIJKLMNOPQRSTUV",
+};
+// Reverse lookups per variant: char-code → 5-bit value.
+var LOOKUPS = {};
+Object.keys(ALPHABETS).forEach(function (v) {
+  var map = {};
+  for (var i = 0; i < ALPHABETS[v].length; i++) map[ALPHABETS[v].charAt(i)] = i;
+  LOOKUPS[v] = map;
+});
+
+var GROUP = 8;                                              // allow:raw-byte-literal — Base32 emits 8 chars per 5 input bytes (RFC 4648 §6)
+var BITS = 5;                                               // 5 bits per Base32 symbol
+
+function _alphabet(variant) {
+  var a = ALPHABETS[variant || "rfc4648"];
+  if (!a) throw new Base32Error("base32/bad-variant", "base32: variant must be 'rfc4648' or 'rfc4648-hex'");
+  return a;
+}
+
+/**
+ * @primitive  b.base32.encode
+ * @signature  b.base32.encode(input, opts?)
+ * @since      0.12.65
+ * @status     stable
+ * @related    b.base32.decode
+ *
+ * Encode a Buffer (or Uint8Array) to an RFC 4648 Base32 string. Output is
+ * padded to an 8-character boundary with <code>=</code> unless
+ * <code>padding: false</code>. The empty input encodes to the empty string.
+ *
+ * @opts
+ *   variant:   "rfc4648" | "rfc4648-hex",   // default: "rfc4648"
+ *   padding:   boolean,                      // default: true
+ *
+ * @example
+ *   b.base32.encode(Buffer.from("foobar"));
+ *   // → "MFRGGZDFMZTWQ===="
+ */
+function encode(input, opts) {
+  opts = opts || {};
+  var buf;
+  if (Buffer.isBuffer(input)) buf = input;
+  else if (input instanceof Uint8Array) buf = Buffer.from(input);
+  else throw new Base32Error("base32/bad-input", "base32.encode: input must be a Buffer or Uint8Array");
+  var alphabet = _alphabet(opts.variant);
+  var pad = opts.padding !== false;
+
+  var out = "";
+  var value = 0, bits = 0;
+  for (var i = 0; i < buf.length; i++) {
+    value = (value << 8) | buf[i];                          // allow:raw-byte-literal — shift in one input byte
+    bits += 8;                                              // allow:raw-byte-literal — eight bits per input byte
+    while (bits >= BITS) {
+      out += alphabet.charAt((value >>> (bits - BITS)) & 31);   // allow:raw-byte-literal — low 5 bits mask (2^5 - 1)
+      bits -= BITS;
+    }
+  }
+  if (bits > 0) out += alphabet.charAt((value << (BITS - bits)) & 31);   // allow:raw-byte-literal — final partial group, low 5 bits
+  if (pad) while (out.length % GROUP !== 0) out += "=";
+  return out;
+}
+
+/**
+ * @primitive  b.base32.decode
+ * @signature  b.base32.decode(str, opts?)
+ * @since      0.12.65
+ * @status     stable
+ * @related    b.base32.encode
+ *
+ * Decode an RFC 4648 Base32 string to a Buffer. Strict by default: any
+ * character outside the variant's alphabet (other than trailing
+ * <code>=</code> padding) throws <code>Base32Error</code>. With
+ * <code>loose: true</code> the decoder up-cases the input and ignores
+ * embedded spaces and dashes (and missing padding) — the shapes TOTP keys
+ * and hand-typed codes take.
+ *
+ * @opts
+ *   variant:   "rfc4648" | "rfc4648-hex",   // default: "rfc4648"
+ *   loose:     boolean,                      // default: false
+ *
+ * @example
+ *   b.base32.decode("MFRGGZDFMZTWQ====").toString();
+ *   // → "foobar"
+ */
+function decode(str, opts) {
+  opts = opts || {};
+  if (typeof str !== "string") throw new Base32Error("base32/bad-input", "base32.decode: input must be a string");
+  _alphabet(opts.variant);
+  var lookup = LOOKUPS[opts.variant || "rfc4648"];
+  var loose = opts.loose === true;
+
+  var bytes = [];
+  var value = 0, bits = 0;
+  var inPad = false;   // once "=" padding starts, only more "=" may follow
+  for (var i = 0; i < str.length; i++) {
+    var ch = str.charAt(i);
+    if (ch === "=") { inPad = true; continue; }             // trailing padding
+    if (loose && (ch === " " || ch === "-")) continue;      // ignore separators
+    // A data character after padding is malformed in either mode — the "="
+    // run must be trailing (rejects "M=Y======" / "MZXW=6YTB").
+    if (inPad) throw new Base32Error("base32/bad-char", "base32.decode: data character '" + ch + "' after padding at index " + i);
+    if (loose) ch = ch.toUpperCase();
+    var idx = lookup[ch];
+    if (idx === undefined) throw new Base32Error("base32/bad-char", "base32.decode: invalid Base32 character '" + str.charAt(i) + "' at index " + i);
+    value = (value << BITS) | idx;
+    bits += BITS;
+    if (bits >= 8) {                                        // allow:raw-byte-literal — emit a full output byte
+      bytes.push((value >>> (bits - 8)) & 0xff);            // allow:raw-byte-literal — eight-bit output byte mask
+      bits -= 8;                                            // allow:raw-byte-literal — consumed eight bits
+    }
+  }
+  return Buffer.from(bytes);
+}
+
+module.exports = {
+  encode:      encode,
+  decode:      decode,
+  ALPHABETS:   ALPHABETS,
+  Base32Error: Base32Error,
+};

package/lib/totp.js

@@ -61,6 +61,7 @@
  */
 var nodeCrypto = require("node:crypto");
 var C = require("./constants");
+var base32 = require("./base32");
 var { generateBytes, generateToken, timingSafeEqual } = require("./crypto");
 var { AuthError } = require("./framework-error");
 
@@ -84,45 +85,23 @@ var DEFAULT_SECRET_BYTES = C.BYTES.bytes(128);
 var MIN_SECRET_BYTES     = 20;
 // HOTP counter is an 8-byte big-endian field per RFC 4226 §5.1.
 var HOTP_COUNTER_BYTES   = C.BYTES.bytes(8);
-// Base32 (RFC 4648) packs 5 bits per char; bit + byte widths used by the
-// encoder/decoder below. Routed through C.BYTES so every byte literal in
-// the file lives behind the same helper.
-var BITS_PER_BYTE        = C.BYTES.bytes(8);
 
 // ---- Base32 (RFC 4648, no padding — TOTP convention) ----
-
-var BASE32 = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+// Composes b.base32: secrets are emitted unpadded and parsed leniently
+// (case-insensitive, ignoring the spaces / dashes humans add when copying
+// a key). An invalid character is surfaced as the TOTP-specific error code.
 
 function _base32Encode(buf) {
-  var bits = "";
-  for (var i = 0; i < buf.length; i++) {
-    bits += buf[i].toString(2).padStart(BITS_PER_BYTE, "0");
-  }
-  var out = "";
-  for (var j = 0; j < bits.length; j += 5) {
-    var chunk = bits.substring(j, j + 5).padEnd(5, "0");
-    out += BASE32[parseInt(chunk, 2)];
-  }
-  return out;
+  return base32.encode(buf, { padding: false });
 }
 
 function _base32Decode(str) {
-  var bits = "";
-  for (var i = 0; i < str.length; i++) {
-    var c = str[i].toUpperCase();
-    if (c === "=" || c === " " || c === "-") continue;     // spaces + dashes + padding
-    var idx = BASE32.indexOf(c);
-    if (idx === -1) {
-      throw new AuthError("auth-totp/bad-secret",
-        "secret contains invalid base32 character: '" + str[i] + "'");
-    }
-    bits += idx.toString(2).padStart(5, "0");
-  }
-  var bytes = [];
-  for (var j = 0; j + BITS_PER_BYTE <= bits.length; j += BITS_PER_BYTE) {
-    bytes.push(parseInt(bits.substring(j, j + BITS_PER_BYTE), 2));
+  try {
+    return base32.decode(str, { loose: true });
+  } catch (e) {
+    throw new AuthError("auth-totp/bad-secret",
+      "secret contains invalid base32 character" + (e && e.message ? ": " + e.message : ""));
   }
-  return Buffer.from(bytes);
 }
 
 // ---- Core HOTP (RFC 4226 §5.3) ----

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.64",
+  "version": "0.12.65",
   "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:35a8fec8-fa70-4913-a315-c839ce432741",
+  "serialNumber": "urn:uuid:9f4770af-2b1a-425d-be19-619f1b638c9e",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-26T07:36:53.769Z",
+    "timestamp": "2026-05-26T08:53:06.102Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.64",
+      "bom-ref": "@blamejs/core@0.12.65",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.64",
+      "version": "0.12.65",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.64",
+      "purl": "pkg:npm/%40blamejs/core@0.12.65",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.64",
+      "ref": "@blamejs/core@0.12.65",
       "dependsOn": []
     }
   ]