@blamejs/pki 0.1.31 → 0.2.0

package/lib/guard-json.js

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal -- no operator-facing namespace. The documented surface is the
+// consumers whose JSON integrity composes this guard (pki.jose message parsing,
+// pki.acme resource objects, pki.webcrypto JWK unwrap).
+//
+// guard-json -- strict, bounded parse of an untrusted JSON document. JSON.parse
+// silently takes the LAST value of a DUPLICATE member, so a signed / wrapped
+// object carrying two members of the same name resolves differently for a
+// verifier than for a consumer -- the JSON smuggling / parser-differential class
+// (CWE-20 / CWE-436). It also caps neither size nor nesting (CWE-770 / CWE-400),
+// and over a Buffer substitutes U+FFFD for invalid UTF-8 rather than failing.
+//
+// This is a single hand-written recursive-descent reader that composes
+// guard.text.decode (the byte cap runs BEFORE the strict/fatal UTF-8 decode, so
+// an oversized document is rejected before it is materialized), then rejects a
+// duplicate member at EVERY nesting depth, caps nesting, assigns each member as
+// an OWN data property (a "__proto__" key becomes a normal member -- it cannot
+// mutate the prototype nor, being a non-own assignment for a primitive, silently
+// defeat the duplicate-member gate), and enforces the RFC 8259 number/string
+// grammar (no leading zero, a fraction/exponent needs a digit, no bare "-").
+//
+var text = require("./guard-text");
+var limits = require("./guard-limits");
+
+// parse(input, ErrorClass, spec) -> value. `input` is a Buffer or a string.
+// spec = { maxBytes, maxDepth, badJson, tooDeep, duplicateMember, tooLarge,
+//   badInput, label } -- the caller's caps + frozen domain/reason codes.
+// Both caps are REQUIRED authoring inputs: an omitted / NaN / fractional cap
+// would silently disable the bound it configures (a depth-uncapped recursive
+// descent escapes as a raw stack-overflow RangeError), so they are validated
+// through the shared cap guards at entry -- maxDepth additionally against the
+// stack-safe recursion ceiling, so no caller cap can exceed frame safety.
+// @enforced-by json-parse-not-via-guard
+function parse(input, ErrorClass, spec) {
+  function E(code, message, cause) { return new ErrorClass(code, message, cause); }
+  if (spec.maxBytes === undefined || spec.maxDepth === undefined) {
+    throw new TypeError("guard.json.parse: spec.maxBytes and spec.maxDepth are required");
+  }
+  var maxBytes = limits.cap(spec.maxBytes, "guard.json.parse spec.maxBytes", undefined);
+  var maxDepth = limits.depthCap(spec.maxDepth, "guard.json.parse spec.maxDepth", undefined);
+  // Byte cap BEFORE the fatal UTF-8 decode (an oversized/ill-encoded document is
+  // rejected before it is turned into a string).
+  var str = text.decode(input, maxBytes, ErrorClass, {
+    charset: "utf-8", fatal: true, tooLarge: spec.tooLarge, badDecode: spec.badJson, badInput: spec.badInput, label: spec.label,
+  });
+  var i = 0, n = str.length;
+  function ws() { while (i < n) { var c = str.charCodeAt(i); if (c === 0x20 || c === 0x09 || c === 0x0a || c === 0x0d) i++; else break; } }
+  function fail(msg) { throw E(spec.badJson, "invalid JSON at offset " + i + ": " + msg); }
+  function value(depth) {
+    if (depth > maxDepth) throw E(spec.tooDeep, "JSON nesting exceeds the depth cap");
+    ws();
+    if (i >= n) fail("unexpected end of input");
+    var c = str[i];
+    if (c === "{") return object(depth);
+    if (c === "[") return array(depth);
+    if (c === "\"") return string();
+    if (c === "-" || (c >= "0" && c <= "9")) return number();
+    if (str.substr(i, 4) === "true") { i += 4; return true; }
+    if (str.substr(i, 5) === "false") { i += 5; return false; }
+    if (str.substr(i, 4) === "null") { i += 4; return null; }
+    fail("unexpected token");
+    return undefined;
+  }
+  function object(depth) {
+    i++; // {
+    var out = {};
+    ws();
+    if (str[i] === "}") { i++; return out; }
+    for (;;) {
+      ws();
+      if (str[i] !== "\"") fail("expected a string key");
+      var key = string();
+      if (Object.prototype.hasOwnProperty.call(out, key)) throw E(spec.duplicateMember, "duplicate JSON member " + JSON.stringify(key));
+      ws();
+      if (str[i] !== ":") fail("expected ':'");
+      i++;
+      // Own data property (not out[key]=...): a "__proto__" key becomes a normal
+      // member, never a prototype mutation nor a silent duplicate-gate bypass.
+      Object.defineProperty(out, key, { value: value(depth + 1), writable: true, enumerable: true, configurable: true });
+      ws();
+      if (str[i] === ",") { i++; continue; }
+      if (str[i] === "}") { i++; return out; }
+      fail("expected ',' or '}'");
+    }
+  }
+  function array(depth) {
+    i++; // [
+    var out = [];
+    ws();
+    if (str[i] === "]") { i++; return out; }
+    for (;;) {
+      out.push(value(depth + 1));
+      ws();
+      if (str[i] === ",") { i++; continue; }
+      if (str[i] === "]") { i++; return out; }
+      fail("expected ',' or ']'");
+    }
+  }
+  function string() {
+    i++; // opening quote
+    var s = "";
+    for (;;) {
+      if (i >= n) fail("unterminated string");
+      var c = str[i++];
+      if (c === "\"") return s;
+      if (c === "\\") {
+        if (i >= n) fail("unterminated escape");
+        var e = str[i++];
+        if (e === "\"") s += "\"";
+        else if (e === "\\") s += "\\";
+        else if (e === "/") s += "/";
+        else if (e === "b") s += "\b";
+        else if (e === "f") s += "\f";
+        else if (e === "n") s += "\n";
+        else if (e === "r") s += "\r";
+        else if (e === "t") s += "\t";
+        else if (e === "u") {
+          var hex = str.substr(i, 4);
+          if (!/^[0-9a-fA-F]{4}$/.test(hex)) fail("bad \\u escape");
+          s += String.fromCharCode(parseInt(hex, 16));
+          i += 4;
+        } else fail("bad escape");
+      } else if (c.charCodeAt(0) < 0x20) {
+        fail("control character in string");
+      } else s += c;
+    }
+  }
+  function number() {
+    var start = i;
+    if (str[i] === "-") i++;
+    while (i < n && str[i] >= "0" && str[i] <= "9") i++;
+    if (str[i] === ".") { i++; while (i < n && str[i] >= "0" && str[i] <= "9") i++; }
+    if (str[i] === "e" || str[i] === "E") { i++; if (str[i] === "+" || str[i] === "-") i++; while (i < n && str[i] >= "0" && str[i] <= "9") i++; }
+    var tok = str.slice(start, i);
+    if (!/^-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?$/.test(tok)) fail("malformed number");
+    var v = Number(tok);
+    if (!isFinite(v)) fail("bad number");
+    return v;
+  }
+  var result = value(0);
+  ws();
+  if (i !== n) fail("trailing content after JSON value");
+  return result;
+}
+
+module.exports = { parse: parse };

package/lib/guard-limits.js

@@ -24,15 +24,39 @@
 
 var constants = require("./constants");
 
-// cap(value, key, dflt) -> a validated non-negative integer, or dflt when value
-// is undefined. A non-integer / non-finite / negative value is a config-time
-// TypeError (Number.isInteger already rejects non-numbers, NaN, and Infinity).
+// cap(value, key, dflt, opts) -> a validated bounded integer, or dflt when value
+// is undefined. A non-integer / non-finite / negative value fails closed
+// (Number.isInteger already rejects non-numbers, NaN, and Infinity).
+//
+// With no opts it is the config-time codec default: a bare TypeError with the
+// "decode:" prefix and a >= 0 floor (the asn1-der / cbor-det callers are
+// untouched). opts lets a caller in another currency reuse the same integer
+// floor with its OWN typed verdict and bounds -- so a fractional/negative/NaN
+// bound cannot be spelled a fifth way with a dropped Number.isInteger:
+//   E     - a (code, message) -> Error factory; when given, an out-of-range
+//           value throws E(code, ...) instead of the bare TypeError.
+//   code  - the domain/reason code passed to E.
+//   label - names the argument in the message (defaults to key).
+//   min   - inclusive lower bound (default 0).
+//   max   - inclusive upper bound (optional).
 // @enforced-by behavioral -- a config-time cap validator has no rename-proof code
-//   shape; the decode-rejects-a-bad-cap RED vectors (asn1/cbor) are the guard.
-function cap(value, key, dflt) {
+//   shape; the decode-rejects-a-bad-cap RED vectors (asn1/cbor/path) are the guard.
+function cap(value, key, dflt, opts) {
   if (value === undefined) return dflt;
-  if (!Number.isInteger(value) || value < 0) {
-    throw new TypeError("decode: " + key + " must be a non-negative integer");
+  opts = opts || {};
+  var min = opts.min === undefined ? 0 : opts.min;
+  // The bounds themselves are authoring inputs: a NaN / fractional min or max
+  // compares false against every value, silently disabling the check (a NaN min
+  // even REPLACES the default >= 0 floor). Always a config-time TypeError --
+  // the bound wiring is broken regardless of the value currency opts.E selects.
+  if (!Number.isInteger(min) || (opts.max !== undefined && !Number.isInteger(opts.max))) {
+    throw new TypeError("guard.limits.cap: the min/max bounds for " + key + " must be integers");
+  }
+  if (!Number.isInteger(value) || value < min || (opts.max !== undefined && value > opts.max)) {
+    var want = "an integer >= " + min + (opts.max !== undefined ? " and <= " + opts.max : "");
+    if (min === 0 && opts.max === undefined) want = "a non-negative integer";
+    if (opts.E) throw opts.E(opts.code, (opts.label || key) + " must be " + want);
+    throw new TypeError("decode: " + key + " must be " + want);
   }
   return value;
 }
@@ -53,4 +77,30 @@ function depthCap(value, key, dflt) {
   return n;
 }
 
-module.exports = { cap: cap, depthCap: depthCap };
+// counter(max, E, code, label) -> { tick }. A parse-time item counter: the
+// recursive decoder calls tick() once per decoded element so a small input
+// cannot fan out into a massive eager node/element tree (CWE-770 / CWE-400 memory
+// amplification -- the class pki.cbor closed with CBOR_MAX_ITEMS). Unlike cap
+// (config-time TypeError), this is Tier-2 parse validation: an over-count throws
+// the caller's typed PkiError via the E(code, message) factory. `max` is the
+// caller's already-validated ceiling (an opts.maxItems run through cap()).
+// @enforced-by behavioral -- a monotone counter has no rename-proof code shape
+//   distinct from any `n++ > max` loop bound; the memory-fanout RED vectors (a
+//   dense TLV run rejects at the cap) driving the composing decoders are the guard.
+function counter(max, E, code, label) {
+  // The ceiling is an authoring input: an undefined / NaN / fractional max
+  // builds a counter whose `n > max` NEVER fires -- a silently dead fanout
+  // defence. Reject at construction (config-time TypeError).
+  if (!Number.isInteger(max) || max < 0) {
+    throw new TypeError("guard.limits.counter: max must be a non-negative integer");
+  }
+  var n = 0;
+  return {
+    tick: function () {
+      n += 1;
+      if (n > max) throw E(code, (label || "decoded item") + " count exceeds the cap " + max);
+    },
+  };
+}
+
+module.exports = { cap: cap, depthCap: depthCap, counter: counter };

package/lib/guard-name.js

@@ -6,8 +6,9 @@
 // consumers whose name-string integrity composes this guard (pki.path.validate
 // DN chaining, pki.schema.x509 GeneralName / SAN decode).
 //
-// guard-name -- fail-closed rejection of an embedded control byte in a
-// distinguished-name / SAN string. Two policies over one concern.
+// guard-name -- fail-closed name integrity: reject an embedded control byte in a
+// distinguished-name / SAN string, and compare two distinguished names by their
+// RFC 5280 sec. 7.1 canonical identity rather than their raw bytes.
 //
 // Defends the name-truncation / display-confusion class (CVE-2009-2408): a NUL
 // or control byte embedded in a decoded name lets an attacker make two different
@@ -15,6 +16,14 @@
 // "good.example.com\0.evil.com" is treated as "good.example.com". CWE-158
 // (improper neutralization of null byte) / CWE-20. The reject is at decode, so a
 // truncation name never reaches a comparison or a display.
+//
+// Defends the DN identity-vs-bytes class (CWE-706): a distinguished name has many
+// RFC 5280 sec. 7.1-equal DER encodings (case, whitespace, PrintableString vs
+// UTF8String). Binding identity to raw bytes -- a byte compare, or hashing
+// name.bytes as a lookup key -- silently treats two equal names as different, so
+// certificate chaining breaks, a revocation issuer / OCSP responder fails to
+// match, or (the mirror risk) a name constraint is escaped. Every DN identity
+// decision routes through the one canonical comparison here.
 
 // assertNoControlBytes(str, E, code, label) -> str | throws E(code, ...)
 // DirectoryString policy (a DN attribute value): reject NUL and C0 control bytes
@@ -50,4 +59,53 @@ function assertPrintableIa5(buf, E, code, label) {
   return buf;
 }
 
-module.exports = { assertNoControlBytes: assertNoControlBytes, assertPrintableIa5: assertPrintableIa5 };
+// Canonical form of a single DN attribute value (RFC 5280 sec. 7.1): reject an
+// embedded control byte (CVE-2009-2408) then case-fold and collapse internal
+// whitespace. Every standard X.520 attribute uses caseIgnoreMatch, and this form
+// matches OpenSSL's X509_NAME_cmp, so a chain OpenSSL accepts is not rejected. This
+// canonicalization is the shape the guard-shape-reinlined detector keys on
+// (declared on dnEqual): a boundary hand-rolling it is re-implementing DN identity.
+function _canonAttrValue(v, E, code, label) {
+  if (typeof v !== "string") return v;
+  assertNoControlBytes(v, E, code, label);
+  return v.trim().replace(/\s+/g, " ").toLowerCase();
+}
+// rdnEqual(a, b, E, code, label) -> boolean. Canonical comparison of a single
+// RelativeDistinguishedName (an unordered SET of type/value pairs, compared as a
+// multiset). The RDN-level primitive a name-constraint directoryName prefix match
+// composes; dnEqual composes it over the RDN sequence. Comparing an RDN by raw DER
+// would treat two RFC 5280-equal names as different (or let a truncation name
+// compare equal).
+// @enforced-by guard-shape-reinlined  (shares the canonicalization shape declared on dnEqual)
+function rdnEqual(a, b, E, code, label) {
+  if (a.length !== b.length) return false;
+  var used = [];
+  for (var i = 0; i < a.length; i++) {
+    var found = false;
+    for (var j = 0; j < b.length; j++) {
+      if (used[j]) continue;
+      if (a[i].type === b[j].type && _canonAttrValue(a[i].value, E, code, label) === _canonAttrValue(b[j].value, E, code, label)) {
+        used[j] = true; found = true; break;
+      }
+    }
+    if (!found) return false;
+  }
+  return true;
+}
+// dnEqual(rdnsA, rdnsB, E, code, label) -> boolean. RFC 5280 sec. 7.1 canonical
+// distinguished-name comparison over the RDN sequence -- the ONE place a DN identity
+// is decided, so no caller binds identity to raw DER (a byte compare, or hashing
+// name.bytes, would treat two RFC 5280-equal names as different, breaking a chain /
+// a revocation match, or -- the mirror risk -- escaping a name constraint). The
+// per-RDN canonicalization + control-byte reject is in rdnEqual / _canonAttrValue.
+// @enforced-by guard-shape-reinlined
+// @guard-shape replace\(/\\s\+/g,
+function dnEqual(rdnsA, rdnsB, E, code, label) {
+  if (rdnsA.length !== rdnsB.length) return false;
+  for (var i = 0; i < rdnsA.length; i++) {
+    if (!rdnEqual(rdnsA[i], rdnsB[i], E, code, label)) return false;
+  }
+  return true;
+}
+
+module.exports = { assertNoControlBytes: assertNoControlBytes, assertPrintableIa5: assertPrintableIa5, dnEqual: dnEqual, rdnEqual: rdnEqual };

package/lib/guard-range.js

@@ -24,6 +24,9 @@
 var UINT31_MAX = 2147483647n;
 var SAFE_MAX   = 9007199254740991n;
 var SAFE_MIN   = -9007199254740991n;
+// 2^64 - 1 (also spelled 0xffffffffffffffffn). The uint64 ceiling lives ONLY here
+// (both spellings are flagged as a re-inline; see uint64's @guard-shape lines).
+var UINT64_MAX = 18446744073709551615n;
 
 // int(value, min, max, E, code, label) -> a Number in [min, max].
 //   value : the BigInt result of an ASN.1 INTEGER / ENUMERATED read.
@@ -37,12 +40,17 @@ var SAFE_MIN   = -9007199254740991n;
 // @enforced-by guard-shape-reinlined
 // @guard-shape 2147483647n
 function int(value, min, max, E, code, label) {
-  // Config-time authoring guard (Tier-1): narrowing to Number is lossless only
-  // when the WHOLE range sits inside the safe-integer band [-(2^53-1), 2^53-1].
-  // Both ends bind -- a min below the floor rounds a decoded value near it just
-  // as a max above the ceiling does. A wider range needs a BigInt-preserving
-  // guard, not this one (this is why the uint64 Merkle-coordinate domain must
-  // NOT route here).
+  // Config-time authoring guard (Tier-1): the bounds must be BigInt -- a Number
+  // bound (worst: NaN, which compares false against every BigInt) silently
+  // disables the range so ANY decoded value narrows. Then: narrowing to Number
+  // is lossless only when the WHOLE range sits inside the safe-integer band
+  // [-(2^53-1), 2^53-1]. Both ends bind -- a min below the floor rounds a
+  // decoded value near it just as a max above the ceiling does. A wider range
+  // needs a BigInt-preserving guard, not this one (this is why the uint64
+  // Merkle-coordinate domain must NOT route here).
+  if (typeof min !== "bigint" || typeof max !== "bigint") {
+    throw new TypeError("guard.range.int: the min/max bounds must be BigInt");
+  }
   if (max > SAFE_MAX) {
     throw new TypeError("guard.range.int: max " + max + " exceeds the safe-integer ceiling; use a BigInt-preserving guard");
   }
@@ -66,4 +74,29 @@ function uint31(value, E, code, label) { return int(value, 0n, UINT31_MAX, E, co
 // @enforced-by guard-shape-reinlined  (shares the 2147483647n shape declared on int)
 function positiveInt31(value, E, code, label) { return int(value, 1n, UINT31_MAX, E, code, label); }
 
-module.exports = { int: int, uint31: uint31, positiveInt31: positiveInt31 };
+// uint64(value, E, code, label) -> a BigInt in [0, 2^64-1], WITHOUT narrowing to
+// Number. Accepts a non-negative safe-integer Number (widened to BigInt) or a
+// BigInt; a Number past 2^53 (precision already lost), a negative, a non-integer,
+// or a non-number-non-bigint throws the caller's typed verdict. The uint64 domain
+// (a Merkle tree coordinate RFC 9162, an SCT timestamp RFC 6962) must NOT route
+// through int() -- narrowing to Number would corrupt the very value it guards, so
+// this is the BigInt-preserving sibling int()'s authoring guard points callers to.
+// @enforced-by guard-shape-reinlined
+// @guard-shape 18446744073709551615n
+// @guard-shape 0xffffffffffffffffn
+function uint64(value, E, code, label) {
+  var v;
+  if (typeof value === "bigint") {
+    v = value;
+  } else if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) {
+    v = BigInt(value);
+  } else {
+    throw E(code, label + " must be a non-negative safe-integer Number or a BigInt (a uint64)");
+  }
+  if (v < 0n || v > UINT64_MAX) {
+    throw E(code, label + " must be a uint64 in [0, 2^64)");
+  }
+  return v;
+}
+
+module.exports = { int: int, uint31: uint31, positiveInt31: positiveInt31, uint64: uint64 };

package/lib/guard-text.js

@@ -39,6 +39,13 @@ var LATIN1 = "latin1";
 //   over-cap RED vectors + the detached re-view through guard.bytes.view (itself
 //   enforced) are the guard.
 function decode(input, maxBytes, ErrorClass, spec) {
+  // maxBytes is an authoring input: an undefined / NaN / fractional cap makes
+  // the `length > maxBytes` comparison always false -- the size cap silently
+  // disabled on the guard whose contract is cap-BEFORE-copy. Config-time
+  // TypeError (every composing boundary passes a C.LIMITS constant).
+  if (!Number.isInteger(maxBytes) || maxBytes < 0) {
+    throw new TypeError("guard.text.decode: maxBytes must be a non-negative integer");
+  }
   var charset = spec.charset || LATIN1;
   if (Buffer.isBuffer(input)) {
     // Re-view through the byte guard FIRST so a detached backing ArrayBuffer (a

package/lib/jose.js

@@ -47,8 +47,6 @@ var LIMITS = constants.LIMITS;
 
 // ---- strict base64url codec (RFC 7515 sec. 2 / RFC 4648 sec. 5) ----------
 
-var B64U_ALPHABET = /^[A-Za-z0-9_-]*$/;
-
 /**
  * @primitive  pki.jose.base64url.encode
  * @signature  pki.jose.base64url.encode(bytes) -> string
@@ -65,6 +63,9 @@ var B64U_ALPHABET = /^[A-Za-z0-9_-]*$/;
  */
 function b64uEncode(bytes) {
   if (!Buffer.isBuffer(bytes)) throw E("jose/bad-input", "base64url.encode requires a Buffer");
+  // Re-view through the byte guard: a detached-backed Buffer reads as zero-length,
+  // so a bare .toString would silently encode "" -- fail closed instead.
+  bytes = guard.bytes.view(bytes, JoseError, "jose/bad-input", "base64url.encode input");
   return bytes.toString("base64url");
 }
 
@@ -85,131 +86,14 @@ function b64uEncode(bytes) {
  *   pki.jose.base64url.decode("AQID");   // -> <Buffer 01 02 03>
  */
 function b64uDecode(text) {
-  if (typeof text !== "string") throw E("jose/bad-base64url", "base64url.decode requires a string");
-  if (!B64U_ALPHABET.test(text)) throw E("jose/bad-base64url", "value is not base64url (padding or a non-alphabet character)");
-  // length % 4 === 1 is not a possible base64 encoding length.
-  if (text.length % 4 === 1) throw E("jose/bad-base64url", "base64url value has an impossible length");
-  var buf = Buffer.from(text, "base64url");
-  // Re-encode: a non-canonical final character (non-zero discarded bits) yields
-  // a different canonical form, so the round-trip fails closed.
-  if (buf.toString("base64url") !== text) throw E("jose/bad-base64url", "base64url value is not canonical");
-  return buf;
+  // The strict alphabet + impossible-length + canonical-round-trip discipline
+  // lives once in the shared encoding guard (RFC 4648 sec. 5 / RFC 8555 sec. 6.1);
+  // the frozen jose/bad-base64url code is threaded through.
+  return guard.encoding.base64url(text, null, E, "jose/bad-base64url", "base64url value");
 }
 
 // ---- strict bounded JSON reader ------------------------------------------
 
-// A single hand-written recursive-descent reader (never JSON.parse, which
-// silently takes the LAST of a duplicate member -- the smuggling class). It
-// enforces the byte-size cap, the depth cap, and duplicate-member rejection at
-// EVERY nesting level, and reads UTF-8 strictly. Returns the parsed value.
-function _jsonReader(str) {
-  var i = 0, n = str.length;
-  function ws() { while (i < n) { var c = str.charCodeAt(i); if (c === 0x20 || c === 0x09 || c === 0x0a || c === 0x0d) i++; else break; } }
-  function fail(msg) { throw E("jose/bad-json", "invalid JSON at offset " + i + ": " + msg); }
-  function value(depth) {
-    if (depth > LIMITS.JSON_MAX_DEPTH) throw E("jose/too-deep", "JSON nesting exceeds the depth cap");
-    ws();
-    if (i >= n) fail("unexpected end of input");
-    var c = str[i];
-    if (c === "{") return object(depth);
-    if (c === "[") return array(depth);
-    if (c === "\"") return string();
-    if (c === "-" || (c >= "0" && c <= "9")) return number();
-    if (str.substr(i, 4) === "true") { i += 4; return true; }
-    if (str.substr(i, 5) === "false") { i += 5; return false; }
-    if (str.substr(i, 4) === "null") { i += 4; return null; }
-    fail("unexpected token");
-    return undefined;
-  }
-  function object(depth) {
-    i++; // {
-    var out = {};
-    ws();
-    if (str[i] === "}") { i++; return out; }
-    for (;;) {
-      ws();
-      if (str[i] !== "\"") fail("expected a string key");
-      var key = string();
-      if (Object.prototype.hasOwnProperty.call(out, key)) throw E("jose/duplicate-member", "duplicate JSON member " + JSON.stringify(key));
-      ws();
-      if (str[i] !== ":") fail("expected ':'");
-      i++;
-      // Assign as an OWN data property via defineProperty (not out[key] = ...): a
-      // "__proto__" key must become a normal own member, not mutate the object's
-      // prototype. A bare `out["__proto__"] = v` would pollute the returned object
-      // AND (for a primitive v) create no own property, silently defeating the
-      // duplicate-member gate above on a repeated __proto__.
-      Object.defineProperty(out, key, { value: value(depth + 1), writable: true, enumerable: true, configurable: true });
-      ws();
-      if (str[i] === ",") { i++; continue; }
-      if (str[i] === "}") { i++; return out; }
-      fail("expected ',' or '}'");
-    }
-  }
-  function array(depth) {
-    i++; // [
-    var out = [];
-    ws();
-    if (str[i] === "]") { i++; return out; }
-    for (;;) {
-      out.push(value(depth + 1));
-      ws();
-      if (str[i] === ",") { i++; continue; }
-      if (str[i] === "]") { i++; return out; }
-      fail("expected ',' or ']'");
-    }
-  }
-  function string() {
-    i++; // opening quote
-    var s = "";
-    for (;;) {
-      if (i >= n) fail("unterminated string");
-      var c = str[i++];
-      if (c === "\"") return s;
-      if (c === "\\") {
-        if (i >= n) fail("unterminated escape");
-        var e = str[i++];
-        if (e === "\"") s += "\"";
-        else if (e === "\\") s += "\\";
-        else if (e === "/") s += "/";
-        else if (e === "b") s += "\b";
-        else if (e === "f") s += "\f";
-        else if (e === "n") s += "\n";
-        else if (e === "r") s += "\r";
-        else if (e === "t") s += "\t";
-        else if (e === "u") {
-          var hex = str.substr(i, 4);
-          if (!/^[0-9a-fA-F]{4}$/.test(hex)) fail("bad \\u escape");
-          s += String.fromCharCode(parseInt(hex, 16));
-          i += 4;
-        } else fail("bad escape");
-      } else if (c.charCodeAt(0) < 0x20) {
-        fail("control character in string");
-      } else s += c;
-    }
-  }
-  function number() {
-    var start = i;
-    if (str[i] === "-") i++;
-    while (i < n && str[i] >= "0" && str[i] <= "9") i++;
-    if (str[i] === ".") { i++; while (i < n && str[i] >= "0" && str[i] <= "9") i++; }
-    if (str[i] === "e" || str[i] === "E") { i++; if (str[i] === "+" || str[i] === "-") i++; while (i < n && str[i] >= "0" && str[i] <= "9") i++; }
-    var tok = str.slice(start, i);
-    // Enforce the RFC 8259 number grammar the greedy scan does not: no leading zero
-    // ("01"), a fraction and an exponent each need at least one digit ("1.", "1e",
-    // "1.e1"), and a bare "-" is not a number. A lenient Number() would accept these
-    // and reintroduce a parser differential against a strict JSON reader.
-    if (!/^-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?$/.test(tok)) fail("malformed number");
-    var v = Number(tok);
-    if (!isFinite(v)) fail("bad number");
-    return v;
-  }
-  var result = value(0);
-  ws();
-  if (i !== n) fail("trailing content after JSON value");
-  return result;
-}
-
 /**
  * @primitive  pki.jose.parseJson
  * @signature  pki.jose.parseJson(input) -> value
@@ -229,12 +113,14 @@ function _jsonReader(str) {
  *   pki.jose.parseJson('{"a":1}');   // -> { a: 1 }
  */
 function parseJson(input) {
-  // guard.text.decode caps the raw byte length BEFORE the (strict, fatal) UTF-8
-  // decode, so an oversized document is rejected before it is materialized.
-  var str = guard.text.decode(input, LIMITS.JSON_MAX_BYTES, JoseError, {
-    charset: "utf-8", fatal: true, tooLarge: "jose/too-large", badDecode: "jose/bad-json", badInput: "jose/bad-input", label: "the JSON document",
+  // The strict bounded reader (byte + depth caps, duplicate-member reject at every
+  // depth, __proto__-safe own-property assignment, fatal UTF-8, RFC 8259 grammar)
+  // lives once in the shared JSON guard; the frozen jose/* codes are threaded through.
+  return guard.json.parse(input, JoseError, {
+    maxBytes: LIMITS.JSON_MAX_BYTES, maxDepth: LIMITS.JSON_MAX_DEPTH,
+    badJson: "jose/bad-json", tooDeep: "jose/too-deep", duplicateMember: "jose/duplicate-member",
+    tooLarge: "jose/too-large", badInput: "jose/bad-input", label: "the JSON document",
   });
-  return _jsonReader(str);
 }
 
 // ---- JOSE algorithm registry (RFC 7518 / 8037 / 9964) --------------------
@@ -513,6 +399,9 @@ async function sign(opts) {
   var header = opts.protected;
   var payload = opts.payload;
   if (!Buffer.isBuffer(payload)) throw E("jose/bad-input", "payload must be a Buffer (empty Buffer for POST-as-GET)");
+  // Re-view before the length===0 fast-path: a DETACHED payload reads as zero-length
+  // and would be silently signed as an empty POST-as-GET body -- fail closed instead.
+  payload = guard.bytes.view(payload, JoseError, "jose/bad-input", "payload");
   // A non-CryptoKey (a raw Buffer, a string, a JWK object) would reach subtle.sign
   // and throw a bare TypeError; require a CryptoKey (it carries an `algorithm`) so
   // every caller -- and every acme builder that composes sign -- fails closed.

package/lib/merkle.js

@@ -48,8 +48,11 @@ var guard = require("./guard-all");
 
 var MerkleError = frameworkError.MerkleError;
 
+// (code, message) -> MerkleError, the factory the composed guards throw through
+// so a malformed coordinate keeps the merkle/* typed verdict.
+function _merkleErr(c, m) { return new MerkleError(c, m); }
+
 var SHA256_BYTES = 32;
-var UINT64_MAX = 18446744073709551615n; // 2n ** 64n - 1n
 var LEAF_PREFIX = Buffer.from([0x00]);
 var NODE_PREFIX = Buffer.from([0x01]);
 var EMPTY = Buffer.alloc(0);
@@ -75,21 +78,9 @@ function _node32(v, field) {
 // throws -- the number-narrows-unbounded-integer discipline for uint64 tree
 // coordinates.
 function _coerceCoord(v, field) {
-  var b;
-  if (typeof v === "bigint") {
-    b = v;
-  } else if (typeof v === "number") {
-    if (!Number.isSafeInteger(v) || v < 0) {
-      throw new MerkleError("merkle/bad-input", field + " must be a non-negative safe integer or a BigInt (a Number >= 2^53 loses precision)");
-    }
-    b = BigInt(v);
-  } else {
-    throw new MerkleError("merkle/bad-input", field + " must be a number or a BigInt");
-  }
-  if (b < 0n || b > UINT64_MAX) {
-    throw new MerkleError("merkle/bad-input", field + " must be in [0, 2^64)");
-  }
-  return b;
+  // A tree coordinate is a uint64 (RFC 9162): the BigInt-preserving range guard
+  // owns the 0..2^64-1 bound and the safe-integer widening in one place.
+  return guard.range.uint64(v, _merkleErr, "merkle/bad-input", field);
 }
 
 function _proofNodes(proof) {