@blamejs/core 0.6.66 → 0.6.67

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **0.6.67** (2026-05-03) — canonical-JSON walker extracted to `lib/canonical-json.js` and applied to `lib/audit-tools.js` + `lib/config-drift.js`. Same bug class as v0.6.60 (pagination) and v0.6.66 (audit-chain) lived in two more sites: `audit-tools._canonicalize` (used for backup-bundle JSONL serialisation, requires byte-equivalence with audit-chain) and `config-drift._stableStringify` (used to hash framework config for post-boot tamper detection). Both still had the silent-data-loss walk — Date → `{}`, Buffer → `{"0":97,…}`, Map / Set → `{}`, BigInt throws, circular references stack-overflow. New `lib/canonical-json.js` exposes `stringify(value, opts?)` with `opts.bufferAs = "hex" | "reject"` (default `"hex"` for crypto / config / audit; `"reject"` for pagination's strict-cursor policy). All four call sites — audit-chain, audit-tools, config-drift, pagination — now route through it; the four near-identical inline walkers collapse to one. **Stored-row + bundle compatibility** preserved: existing audit rows verify identically (their `metadata` columns are JSON strings); backup bundles produced pre-v0.6.67 round-trip correctly because byte output for plain types is unchanged. **Tests** — 17 layer-0 audit-chain assertions from v0.6.66 cover the unified walker; existing pagination tests cover `bufferAs: "reject"`. Smoke 7251 / wiki e2e 178 / Linux 86.3s / eslint clean / shellcheck clean.
+
 - **0.6.66** (2026-05-03) — `b.auditChain.canonicalize` deep-walks values and rejects non-plain types instead of silently round-tripping garbage. Same bug class as the v0.6.60 pagination canonicalize fix: pre-fix the walker did `Object.keys(row).map(...)` and JSON.stringify'd whatever fell through, which silently encoded **Map / Set / RegExp** as `{}`, **Symbol / function** as missing keys, **BigInt** as a thrown `Do not know how to serialize` mid-emit (DoS-shape on any operator routing bigint IDs into audit metadata), and **circular references** as the unwrapped JSON.stringify error message. The post-fix walker: BigInt → decimal string (no data loss for large account IDs / 64-bit counters from external-DB drivers); Date → ISO string (already worked via JSON.stringify but now explicit before the recursive walk); Map / Set / RegExp / Symbol / function reject with a clear constructor-name message; circular refs detected via WeakSet and rejected as a framework error. Walks recursively so nested structures (`{ a: [BigInt(1), BigInt(2)] }`, `{ a: { b: Uint8Array(…) } }`) all serialise correctly. **Stored-row compat** — existing audit rows verify identically because their stored `metadata` columns are already JSON strings; the change only affects EMIT-time serialisation. **Tests** — 17 new layer-0 assertions in `test/00-primitives.js`. Smoke 7234 → 7251 / wiki e2e 178 / Linux 86.1s / eslint clean / shellcheck clean.
 
 - **0.6.65** (2026-05-03) — `b.scheduler.parseCron` rejects step values exceeding the field's range. Pre-fix `*/99999 * * * *` was silently accepted and degenerated to "minute 0 of every hour" (because the for-loop adding values stopped at the first iteration when `step > range`); an operator typing the typo got a once-per-hour schedule when they probably meant once per N minutes. Now `_parseCronField` rejects with `scheduler/invalid-cron` when `step > (range.max - range.min + 1)`. The bound is inclusive so `*/60 * * * *` (= "minute 0 of every hour" written with a redundant explicit step) still accepts. **Tests** — 4 new layer-0 assertions: `*/60` accepts, `*/61` rejects, `*/99999` rejects (the silent-degenerate case), `* */25 * * *` rejects (step > 24-hour range). Smoke 7230 → 7234 / wiki e2e 178 / Linux 86.9s / eslint clean / shellcheck clean.

package/lib/audit-chain.js

@@ -18,6 +18,7 @@
  * lib/audit-sign.js. This module owns the chain hash math only;
  * verification is O(n) and walks every row at boot.
  */
+var canonicalJson = require("./canonical-json");
 var { sha3Hash } = require("./crypto");
 
 // All-zero SHA3-512 (128 hex chars) — sentinel prevHash for the first row.
@@ -25,58 +26,19 @@ var ZERO_HASH = "0".repeat(128);
 
 // Canonicalize a row for hashing. Excludes the hash/nonce columns themselves
 // and any caller-specified columns. Sorted keys, JSON-encoded values; Buffer
-// values converted to hex for stable byte serialization.
-//
-// Deeply walks the value tree so non-plain types reject cleanly instead of
-// silently round-tripping as `{}` (Map / Set / RegExp), as `{"0":97,…}`
-// (Buffer / typed-array nested inside arrays / objects), or as missing
-// keys (Symbol / function). BigInt converts to its decimal string —
-// large account IDs / monotonic counters from external-DB drivers
-// frequently land as BigInt, and crashing the audit emit on those would
-// turn them into availability incidents. Circular refs throw a clean
-// framework Error rather than the raw JSON.stringify message.
-function _scrub(value, seen) {
-  if (value === null || typeof value === "undefined") return null;
-  var t = typeof value;
-  if (t === "string" || t === "boolean" || t === "number") return value;
-  if (t === "bigint") return String(value);
-  if (t === "symbol" || t === "function") {
-    throw new Error("audit-chain canonicalize: " + t + " value is not " +
-      "serialisable; convert to a string before emit");
-  }
-  if (Buffer.isBuffer(value))            return value.toString("hex");
-  if (value instanceof Uint8Array)       return Buffer.from(value).toString("hex");
-  if (value instanceof Date)             return value.toISOString();
-  // After the primitives + Buffer + Date, any remaining "object" must be
-  // a plain object or array. Map / Set / RegExp / class instances all
-  // reject with a clear constructor name in the error so operators see
-  // exactly which audit metadata field is the culprit.
-  if (value instanceof Map || value instanceof Set || value instanceof RegExp) {
-    throw new Error("audit-chain canonicalize: " + value.constructor.name +
-      " is not serialisable; convert to a plain primitive / array / object first");
-  }
-  seen = seen || new WeakSet();
-  if (seen.has(value)) {
-    throw new Error("audit-chain canonicalize: circular reference in audit row");
-  }
-  seen.add(value);
-  if (Array.isArray(value)) return value.map(function (v) { return _scrub(v, seen); });
-  var keys = Object.keys(value).sort();
-  var out = {};
-  for (var i = 0; i < keys.length; i++) {
-    out[keys[i]] = _scrub(value[keys[i]], seen);
-  }
-  return out;
-}
-
+// values converted to hex for stable byte serialization. Routes through
+// the shared `lib/canonical-json` walker so the four canonicalize sites
+// (this one, audit-tools, config-drift, pagination) share one
+// implementation of the bug-class fix that started in v0.6.60 and
+// completed in v0.6.67.
 function canonicalize(row, excludeKeys) {
   var ex = new Set(excludeKeys || []);
   var keys = Object.keys(row).filter(function (k) { return !ex.has(k); }).sort();
   var pairs = {};
   for (var i = 0; i < keys.length; i++) {
-    pairs[keys[i]] = _scrub(row[keys[i]]);
+    pairs[keys[i]] = row[keys[i]];
   }
-  return JSON.stringify(pairs);
+  return canonicalJson.stringify(pairs);
 }
 
 // Compute a row's hash given its predecessor's hash, the row's logical fields

package/lib/audit-tools.js

@@ -55,6 +55,7 @@ var fs = require("fs");
 var path = require("path");
 var atomicFile = require("./atomic-file");
 var auditChain = require("./audit-chain");
+var canonicalJson = require("./canonical-json");
 var auditSign = require("./audit-sign");
 var backupCrypto = require("./backup/crypto");
 var clusterStorage = require("./cluster-storage");
@@ -116,20 +117,12 @@ function _requireOutDir(outDir, kind) {
   }
 }
 
-// Canonical-JSON: JSON.stringify with sorted keys at every depth. Mirrors
-// backup-manifest's serialize so operators have one canonicalization rule.
-function _canonicalize(value) {
-  if (value === null || typeof value !== "object") return JSON.stringify(value);
-  if (Array.isArray(value)) {
-    return "[" + value.map(_canonicalize).join(",") + "]";
-  }
-  var keys = Object.keys(value).sort();
-  var parts = [];
-  for (var i = 0; i < keys.length; i++) {
-    parts.push(JSON.stringify(keys[i]) + ":" + _canonicalize(value[keys[i]]));
-  }
-  return "{" + parts.join(",") + "}";
-}
+// Canonical-JSON via the shared lib/canonical-json walker — same bytes
+// as audit-chain.canonicalize, config-drift._stableStringify, and
+// pagination._canonicalize for the same input. Pre-v0.6.67 each site
+// had its own copy of the walk, all carrying the same silent-loss bug
+// for Date / Buffer / Map / Set / BigInt / circular refs.
+function _canonicalize(value) { return canonicalJson.stringify(value); }
 
 // Convert a single audit_log row to its on-disk-canonical JSON shape.
 // Buffers become hex strings (matches audit-chain.canonicalize). Used

package/lib/canonical-json.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * Canonical JSON — deterministic stringify with sorted keys at every depth.
+ *
+ * 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.
+ *
+ * The walk:
+ *
+ *   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
+ *
+ * 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.
+ */
+
+function _scrub(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 === "bigint") return 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 (bufferAs === "reject") {
+      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");
+  }
+  if (value instanceof Uint8Array) {
+    if (bufferAs === "reject") {
+      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");
+  }
+  if (value instanceof Date) return value.toISOString();
+  // After primitives + Date + Buffer + Uint8Array, any remaining "object"
+  // must be a plain object or array. Map / Set / RegExp / class instances
+  // all reject so the silent-data-loss class is closed.
+  if (value instanceof Map || value instanceof Set || value instanceof RegExp) {
+    throw new Error("canonical-json: " + value.constructor.name +
+      " is not serialisable; convert to a plain primitive / array / object first");
+  }
+  seen = seen || new WeakSet();
+  if (seen.has(value)) {
+    throw new Error("canonical-json: circular reference detected");
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return value.map(function (v) { return _scrub(v, seen, bufferAs); });
+  }
+  var keys = Object.keys(value).sort();
+  var out = {};
+  for (var i = 0; i < keys.length; i++) {
+    out[keys[i]] = _scrub(value[keys[i]], seen, bufferAs);
+  }
+  return out;
+}
+
+// Return the deterministic JSON string. opts.bufferAs picks the Buffer
+// policy ("hex" default, "reject" for callers like pagination).
+function stringify(value, opts) {
+  var bufferAs = (opts && opts.bufferAs) || "hex";
+  if (bufferAs !== "hex" && bufferAs !== "reject") {
+    throw new Error("canonical-json: bufferAs must be 'hex' or 'reject'; got " +
+      JSON.stringify(bufferAs));
+  }
+  return JSON.stringify(_scrub(value, null, bufferAs));
+}
+
+module.exports = { stringify: stringify };

package/lib/config-drift.js

@@ -48,6 +48,7 @@
 var fs = require("node:fs");
 var path = require("node:path");
 var auditSign = require("./audit-sign");
+var canonicalJson = require("./canonical-json");
 var crypto = require("./crypto");
 var lazyRequire = require("./lazy-require");
 var validateOpts = require("./validate-opts");
@@ -61,21 +62,13 @@ var _err = ConfigDriftError.factory;
 var SIDECAR_NAME = "config-baseline.sig";
 var SIDECAR_VERSION = 1;
 
-// Stable JSON serialization: deterministic key order so the same
-// snapshot always hashes to the same digest. Without this, an object
-// reordered between boots would falsely flag as drift.
-function _stableStringify(value) {
-  if (value === null || typeof value !== "object") return JSON.stringify(value);
-  if (Array.isArray(value)) {
-    return "[" + value.map(_stableStringify).join(",") + "]";
-  }
-  var keys = Object.keys(value).sort();
-  var pairs = [];
-  for (var i = 0; i < keys.length; i++) {
-    pairs.push(JSON.stringify(keys[i]) + ":" + _stableStringify(value[keys[i]]));
-  }
-  return "{" + pairs.join(",") + "}";
-}
+// Stable JSON serialization via the shared lib/canonical-json walker.
+// Deterministic key order so the same snapshot always hashes to the same
+// digest. Pre-v0.6.67 the in-line implementation silently lost Date /
+// Map / Set / Buffer / BigInt content; the shared walker handles all
+// of those + circular refs. Same bytes as audit-chain / audit-tools /
+// pagination would produce for the same input.
+function _stableStringify(value) { return canonicalJson.stringify(value); }
 
 function _hashSnapshot(snapshot) {
   return crypto.sha3Hash(_stableStringify(snapshot));

package/lib/pagination.js

@@ -96,6 +96,7 @@
  */
 
 var nodeCrypto = require("node:crypto");
+var canonicalJson = require("./canonical-json");
 var crypto = require("./crypto");
 var { defineClass } = require("./framework-error");
 
@@ -106,41 +107,17 @@ var TAG_BYTES = 16;            // 128-bit HMAC tag truncated from SHA3-512
 var DEFAULT_LIMIT = 25;
 var DEFAULT_MAX_LIMIT = 100;
 
-// Canonical JSON — sorted keys at every depth. Mirrors safe-schema /
-// audit-tools so verifier and producer hash exactly the same bytes.
-//
-// Cursor state must contain only plain data (string, number, boolean,
-// null, plain object, array, Date). Buffer / typed-arrays / Map / Set /
-// RegExp are rejected because the prior `Object.keys` walk silently
-// serialised them as `{}` (Date) or `{"0":97,"1":98,…}` (Buffer) — the
-// operator's data round-tripped through encode/decode as garbage. Date
-// gets an explicit ISO-string conversion (matches stdlib JSON.stringify).
-// Circular references throw cleanly instead of stack-overflowing.
-function _canonicalize(value, seen) {
-  if (value === null || typeof value !== "object") return JSON.stringify(value);
-  if (value instanceof Date) return JSON.stringify(value.toISOString());
-  if (Buffer.isBuffer(value) || value instanceof Uint8Array ||
-      value instanceof Map  || value instanceof Set ||
-      value instanceof RegExp) {
-    throw new PaginationError("pagination/bad-state",
-      "cursor state cannot contain " + value.constructor.name +
-      "; convert to a plain primitive (string / number / iso-string) first");
-  }
-  seen = seen || new WeakSet();
-  if (seen.has(value)) {
-    throw new PaginationError("pagination/bad-state",
-      "cursor state contains a circular reference");
-  }
-  seen.add(value);
-  if (Array.isArray(value)) {
-    return "[" + value.map(function (v) { return _canonicalize(v, seen); }).join(",") + "]";
-  }
-  var keys = Object.keys(value).sort();
-  var parts = [];
-  for (var i = 0; i < keys.length; i++) {
-    parts.push(JSON.stringify(keys[i]) + ":" + _canonicalize(value[keys[i]], seen));
+// Canonical JSON via the shared lib/canonical-json walker with
+// bufferAs: "reject" — cursor state must contain only plain data, so
+// Buffer / Uint8Array reject loudly. Map / Set / RegExp / Symbol /
+// function / circular always reject; Date → ISO; BigInt → decimal
+// string. Wraps the walker's generic Error in a PaginationError so
+// callers can route on `pagination/bad-state`.
+function _canonicalize(value) {
+  try { return canonicalJson.stringify(value, { bufferAs: "reject" }); }
+  catch (e) {
+    throw new PaginationError("pagination/bad-state", e.message);
   }
-  return "{" + parts.join(",") + "}";
 }
 
 function _toBuf(secret) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.6.66",
+  "version": "0.6.67",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:cfffbb8d-56d9-4859-af94-b238e781b705",
+  "serialNumber": "urn:uuid:28be00e0-fbc9-4324-9213-5bfe704f8667",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-03T14:41:25.970Z",
+    "timestamp": "2026-05-03T14:50:38.247Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.6.66",
+      "bom-ref": "@blamejs/core@0.6.67",
       "type": "library",
       "name": "blamejs",
-      "version": "0.6.66",
+      "version": "0.6.67",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.6.66",
+      "purl": "pkg:npm/%40blamejs/core@0.6.67",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.6.66",
+      "ref": "@blamejs/core@0.6.67",
       "dependsOn": []
     }
   ]