@blamejs/pki 0.1.29 → 0.1.31

package/CHANGELOG.md

@@ -4,7 +4,29 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## v0.1.29 — 2026-07-11
+## v0.1.31 — 2026-07-11
+
+The DER format cohort and the JOSE surface graduate to stable.
+
+### Changed
+
+- pki.schema.pkcs12 / attrcert / crmf / cmp / csrattrs (parse, pemDecode, pemEncode), pki.schema.all and pki.schema.parse, and the pki.jose signing / verification / thumbprint / base64url / JSON surface graduate from experimental to stable.
+- The LTS-CALENDAR graduation criterion now states that a settled, well-tested format no mainstream tool implements graduates on the toolkit's own conformance-vector round-trip plus coverage-guided fuzzing, rather than on a harness oracle that does not exist.
+
+## v0.1.30 — 2026-07-11
+
+Fail-closed hardening of the byte-input and text-decode boundaries.
+
+### Changed
+
+- A detached-backed BufferSource (a transferred / structuredClone'd view) passed to any DER format parser -- pki.schema.x509 / crl / csr / pkcs8 / cms / pkcs12 -- fails closed with the format's typed bad-input error at the shared parse-input boundary rather than being decoded as an empty buffer.
+
+### Fixed
+
+- The EST transfer and multipart-mixed decoders enforce their size cap on the raw byte length before decoding the payload to a string, and an HTTP error response body is decoded only up to the prefix shown in the message -- closing a single-input string-allocation amplification where an oversized body was materialized in full before the cap rejected it.
+- pki.oid.fromDER rejects a non-Buffer or detached-backed input with a typed oid/bad-input error instead of a raw TypeError.
+
+## v0.1.29 — 2026-07-10
 
 A detached-backed BufferSource now fails closed with a typed error at every byte-input boundary.
 

package/lib/asn1-der.js

@@ -32,6 +32,7 @@
 
 var constants = require("./constants");
 var frameworkError = require("./framework-error");
+var guard = require("./guard-all");
 
 var Asn1Error = frameworkError.Asn1Error;
 var OidError = frameworkError.OidError;
@@ -105,19 +106,7 @@ function _className(bits) {
 }
 
 function _asBuffer(input, who) {
-  // A Buffer is a Uint8Array, so it routes through the same guarded re-view --
-  // NOT a `Buffer.isBuffer` fast-path that returns it as-is. A detached backing
-  // ArrayBuffer (a transferred / structuredClone'd view) reads as zero-length;
-  // re-viewing through Buffer.from surfaces it as a typed error here rather than
-  // a misleading downstream truncated-DER verdict on an empty buffer.
-  if (Buffer.isBuffer(input) || input instanceof Uint8Array) {
-    try {
-      return Buffer.from(input.buffer, input.byteOffset, input.byteLength);
-    } catch (e) {
-      throw new Asn1Error("asn1/not-buffer", who + ": input is not a usable byte view (detached backing buffer?)", e);
-    }
-  }
-  throw new Asn1Error("asn1/not-buffer", who + ": expected a Buffer / Uint8Array");
+  return guard.bytes.view(input, Asn1Error, "asn1/not-buffer", who);
 }
 
 // ---- Decoder --------------------------------------------------------
@@ -160,27 +149,15 @@ function _asBuffer(input, who) {
  *   var node = pki.asn1.decode(der);
  *   node.tagNumber === pki.asn1.TAGS.SEQUENCE;
  */
-// A size/depth cap opt: absent means the constants.LIMITS default; a provided
-// value must be a non-negative finite integer. A non-finite cap (NaN, Infinity)
-// silently DISABLES the guard -- every `>` compare against it is false -- so a
-// deeply nested input would run to a bare RangeError instead of the typed
-// asn1/too-deep verdict. A bad cap is a config fault: throw at entry.
-function _capOpt(v, key, dflt) {
-  if (v === undefined) return dflt;
-  if (typeof v !== "number" || !isFinite(v) || v < 0 || Math.floor(v) !== v) {
-    throw new TypeError("decode: " + key + " must be a non-negative integer");
-  }
-  return v;
-}
-
 function decode(input, opts) {
   opts = opts || {};
   var buf = _asBuffer(input, "decode");
-  var maxBytes = _capOpt(opts.maxBytes, "maxBytes", constants.LIMITS.DER_MAX_BYTES);
-  var maxDepth = _capOpt(opts.maxDepth, "maxDepth", constants.LIMITS.DER_MAX_DEPTH);
-  if (maxDepth > constants.LIMITS.MAX_DECODE_DEPTH_CEILING) {
-    throw new TypeError("decode: maxDepth " + maxDepth + " exceeds the stack-safe ceiling " + constants.LIMITS.MAX_DECODE_DEPTH_CEILING);
-  }
+  // A size/depth cap opt: absent means the constants.LIMITS default; a provided
+  // value must be a non-negative integer (guard.limits.cap). depthCap also
+  // refuses a maxDepth above the stack-safe ceiling so a raised cap cannot drive
+  // recursive descent into a bare RangeError instead of the typed asn1/too-deep.
+  var maxBytes = guard.limits.cap(opts.maxBytes, "maxBytes", constants.LIMITS.DER_MAX_BYTES);
+  var maxDepth = guard.limits.depthCap(opts.maxDepth, "maxDepth", constants.LIMITS.DER_MAX_DEPTH);
   if (buf.length > maxBytes) {
     throw new Asn1Error("asn1/too-large", "input " + buf.length + " bytes exceeds cap " + maxBytes);
   }

package/lib/cbor-det.js

@@ -37,6 +37,7 @@
 var constants = require("./constants");
 var frameworkError = require("./framework-error");
 var asn1 = require("./asn1-der");
+var guard = require("./guard-all");
 
 var CborError = frameworkError.CborError;
 
@@ -57,31 +58,7 @@ var _utf8 = new TextDecoder("utf-8", { fatal: true });
 var _MAX_EPOCH_SECONDS = 8640000000000n;
 
 function _asBuffer(input, who) {
-  // A Buffer is itself a Uint8Array, so it goes through the same guarded re-view
-  // -- NOT a `Buffer.isBuffer` fast-path that would return it as-is. A detached
-  // backing ArrayBuffer (a transferred / structuredClone'd view) has had its
-  // bytes removed and reads as zero-length; the fast-path would hand the byte
-  // walk an empty buffer. Always re-view through Buffer.from so a detached input
-  // fails closed here as a typed error rather than a raw TypeError deeper in the
-  // walk (or a misleading truncated-input verdict).
-  if (Buffer.isBuffer(input) || input instanceof Uint8Array) {
-    try {
-      return Buffer.from(input.buffer, input.byteOffset, input.byteLength);
-    } catch (e) {
-      throw new CborError("cbor/not-buffer", who + ": input is not a usable byte view (detached backing buffer?)", e);
-    }
-  }
-  throw new CborError("cbor/not-buffer", who + ": expected a Buffer / Uint8Array");
-}
-
-// Config-time cap validation: a bad cap is an authoring bug, so it throws a
-// TypeError (not a CborError) exactly like asn1-der's _capOpt.
-function _capOpt(v, key, dflt) {
-  if (v === undefined) return dflt;
-  if (typeof v !== "number" || !Number.isInteger(v) || v < 0) {
-    throw new TypeError("decode: " + key + " must be a non-negative integer");
-  }
-  return v;
+  return guard.bytes.view(input, CborError, "cbor/not-buffer", who);
 }
 
 // Determinism profile -> a ruleset. v1 whitelists only "deterministic"
@@ -283,12 +260,9 @@ function _decodeItem(buf, start, limit, depth, maxD, rules, state) {
 function decode(input, opts) {
   opts = opts || {};
   var buf = _asBuffer(input, "decode");
-  var maxBytes = _capOpt(opts.maxBytes, "maxBytes", constants.LIMITS.CBOR_MAX_BYTES);
-  var maxDepth = _capOpt(opts.maxDepth, "maxDepth", constants.LIMITS.CBOR_MAX_DEPTH);
-  if (maxDepth > constants.LIMITS.MAX_DECODE_DEPTH_CEILING) {
-    throw new TypeError("decode: maxDepth " + maxDepth + " exceeds the stack-safe ceiling " + constants.LIMITS.MAX_DECODE_DEPTH_CEILING);
-  }
-  var maxItems = _capOpt(opts.maxItems, "maxItems", constants.LIMITS.CBOR_MAX_ITEMS);
+  var maxBytes = guard.limits.cap(opts.maxBytes, "maxBytes", constants.LIMITS.CBOR_MAX_BYTES);
+  var maxDepth = guard.limits.depthCap(opts.maxDepth, "maxDepth", constants.LIMITS.CBOR_MAX_DEPTH);
+  var maxItems = guard.limits.cap(opts.maxItems, "maxItems", constants.LIMITS.CBOR_MAX_ITEMS);
   var rules = _profile(opts.profile);
   if (buf.length > maxBytes) throw new CborError("cbor/too-large", "input " + buf.length + " bytes exceeds cap " + maxBytes);
   var r = _decodeItem(buf, 0, buf.length, 0, maxDepth, rules, { n: 0, max: maxItems });

package/lib/ct.js

@@ -41,6 +41,7 @@
 var asn1 = require("./asn1-der.js");
 var constants = require("./constants.js");
 var frameworkError = require("./framework-error.js");
+var guard = require("./guard-all.js");
 
 var CtError = frameworkError.CtError;
 var C = constants;
@@ -111,19 +112,7 @@ function _peelInner(extValue) {
 }
 
 function _toBuffer(v, field) {
-  // A Buffer is a Uint8Array, so it routes through the same guarded re-view --
-  // NOT a `Buffer.isBuffer` fast-path that returns it as-is. A detached backing
-  // ArrayBuffer (a transferred / structuredClone'd view) reads as zero-length;
-  // re-viewing through Buffer.from surfaces it as a typed error here rather than
-  // a misleading downstream bad-DER verdict on an empty buffer.
-  if (Buffer.isBuffer(v) || v instanceof Uint8Array) {
-    try {
-      return Buffer.from(v.buffer, v.byteOffset, v.byteLength);
-    } catch (e) {
-      throw new CtError("ct/bad-input", field + " is not a usable byte view (detached backing buffer?)", e);
-    }
-  }
-  throw new CtError("ct/bad-input", field + " must be a Buffer or Uint8Array");
+  return guard.bytes.view(v, CtError, "ct/bad-input", field);
 }
 
 // Parse one SerializedSCT body inside a sub-reader bounded to the element (so a

package/lib/est.js

@@ -50,6 +50,7 @@ var crl = require("./schema-crl");
 var pkcs8 = require("./schema-pkcs8");
 var csr = require("./schema-csr");
 var frameworkError = require("./framework-error");
+var guard = require("./guard-all");
 
 var EstError = frameworkError.EstError;
 function E(code, message, cause) { return new EstError(code, message, cause); }
@@ -128,14 +129,16 @@ function _httpDateMs(s) {
  *   var roundTripped = pki.est.transferDecode(pki.est.transferEncode(der));
  */
 function transferDecode(body) {
-  var s = Buffer.isBuffer(body) ? body.toString("latin1") : String(body);
   // The pre-decode ceiling: the largest base64 that could yield a DER_MAX_BYTES
   // document, plus a generous line-wrapping allowance (CRLF at 64/76-char lines is
   // ~3%; 1/8 leaves ample margin) so a normally-wrapped near-limit body is not
   // rejected before the real DER_MAX_BYTES limit is enforced on the decode below.
+  // guard.text.decode caps the raw byte length BEFORE the latin1 copy.
   var b64Len = Math.ceil(constants.LIMITS.DER_MAX_BYTES * 4 / 3);
   var cap = b64Len + Math.ceil(b64Len / 8) + constants.BYTES.kib(64);
-  if (s.length > cap) throw E("est/too-large", "the EST payload exceeds the transfer size cap");
+  var s = guard.text.decode(body, cap, EstError, {
+    charset: "latin1", tooLarge: "est/too-large", badInput: "est/bad-input", label: "the EST payload",
+  });
   var stripped = s.replace(/[\r\n \t]/g, "");
   if (!/^[A-Za-z0-9+/]*={0,2}$/.test(stripped)) throw E("est/bad-base64", "the EST payload is not RFC 4648 base64 (RFC 8951 sec. 3.1)");
   var der = Buffer.from(stripped, "base64");
@@ -186,8 +189,9 @@ function _multipartBoundary(contentType) {
 function splitMultipartMixed(body, contentType) {
   var boundary = _multipartBoundary(contentType);
   if (!boundary) throw E("est/bad-multipart", "a serverkeygen response must be multipart/mixed with a boundary (RFC 7030 sec. 4.4.2)");
-  var text = Buffer.isBuffer(body) ? body.toString("latin1") : String(body);
-  if (text.length > constants.LIMITS.DER_MAX_BYTES * 2) throw E("est/too-large", "the multipart body exceeds the size cap");
+  var text = guard.text.decode(body, constants.LIMITS.DER_MAX_BYTES * 2, EstError, {
+    charset: "latin1", tooLarge: "est/too-large", badInput: "est/bad-input", label: "the multipart body",
+  });
   var esc = boundary.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   var delimRe = new RegExp("(?:^|\\r?\\n)--" + esc + "(--)?[ \\t]*(?:\\r?\\n|$)", "g");
   var marks = [], m;
@@ -526,8 +530,13 @@ function classifyResponse(status, headers, body, opts) {
   }
   if (status >= 300 && status < 400) return { status: "redirect", location: h["location"] || null };
   if (status >= 400) {
-    var text = Buffer.isBuffer(body) ? body.toString("utf8") : String(body || "");
-    throw E("est/http-error", "EST server returned HTTP " + status + (text ? ": " + text.slice(0, 512) : ""));
+    // Decode only a bounded prefix for the message -- a huge error body must not
+    // be materialized as a full string just to show its first 512 characters.
+    // toString(enc, start, end) bounds the decode WITHOUT constructing a subarray
+    // view, so a detached body reads as "" here rather than throwing a raw
+    // TypeError that would mask the est/http-error verdict.
+    var text = Buffer.isBuffer(body) ? body.toString("utf8", 0, 512) : String(body || "").slice(0, 512);
+    throw E("est/http-error", "EST server returned HTTP " + status + (text ? ": " + text : ""));
   }
   return { status: "unexpected", httpStatus: status };
 }

package/lib/framework-error.js

@@ -143,12 +143,13 @@ var CborError = defineClass("CborError", { withCause: true });
 
 // OidError -- a malformed object-identifier: fewer than two arcs, a first
 // arc outside 0..2, a second arc >= 40 under arcs 0/1, or a non-minimal
-// base-128 sub-identifier.
-var OidError = defineClass("OidError");
+// base-128 sub-identifier. withCause threads a raw byte-view failure (a detached
+// backing ArrayBuffer at fromDER) as the cause rather than discarding it.
+var OidError = defineClass("OidError", { withCause: true });
 
 // PemError -- a malformed PEM envelope: missing / mismatched BEGIN/END
 // markers, a bad label, or non-base64 body.
-var PemError = defineClass("PemError");
+var PemError = defineClass("PemError", { withCause: true });
 
 // CertificateError -- a byte sequence that is not a well-formed X.509
 // certificate (wrong outer structure, unparseable field, unsupported

package/lib/guard-all.js

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal -- no operator-facing namespace. This is lib composition only; the
+// documented surface is the primitives whose boundaries compose these guards.
+//
+// guard-all -- the guard-family orchestrator (schema-all's role for the guard
+// family). It assembles the per-shape fail-closed guards into one namespaced
+// surface every input boundary composes, so a boundary depends on the family
+// rather than re-implementing a guard inline:
+//
+//   guard.bytes.view / .source        -- untrusted byte-source -> Buffer re-view
+//                                         (detached-buffer fail-open defence)
+//   guard.text.decode                 -- byte-source -> string, cap BEFORE copy
+//                                         (parser-DoS string-allocation defence)
+//   guard.limits.cap / .depthCap      -- config-time resource-cap validation
+//                                         (recursion / allocation DoS defence)
+//   guard.crypto.constantTimeEqual    -- length-checked constant-time compare
+//                                         (timing side-channel defence)
+//   guard.range.int / .uint31 / .positiveInt31
+//                                     -- bound a decoded integer before narrowing
+//                                        to Number (silent-narrowing defence)
+//
+// Each shape is enforced by a codebase-patterns detector: the characteristic
+// token of a guard (the Buffer.from(x.buffer, byteOffset) re-view, the
+// timingSafeEqual call, the MAX_DECODE_DEPTH_CEILING check) must appear ONLY in
+// its guard module, so a new boundary cannot re-inline the shape and forget the
+// defence.
+
+var bytes  = require("./guard-bytes");
+var text   = require("./guard-text");
+var limits = require("./guard-limits");
+var crypto = require("./guard-crypto");
+var range  = require("./guard-range");
+var name   = require("./guard-name");
+
+module.exports = {
+  bytes:  bytes,
+  text:   text,
+  limits: limits,
+  crypto: crypto,
+  range:  range,
+  name:   name,
+};

package/lib/guard-bytes.js

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal -- no operator-facing namespace. The documented surface is the
+// primitives whose input boundaries compose these guards (pki.asn1.decode,
+// pki.cbor.decode, pki.ct.parseSctList, pki.webcrypto.*).
+//
+// guard-bytes -- fail-closed coercion of an untrusted byte-source input to a
+// Buffer view. One of the enforced choke points of the guard family: a
+// codebase-patterns detector requires every byte-input boundary to route
+// through here, so the defence below cannot be forgotten at a new boundary.
+//
+// Defends the detached-buffer fail-OPEN: a transferred / structuredClone'd
+// Buffer or view has a detached backing ArrayBuffer and reads as ZERO-LENGTH.
+// An identity fast-path (`Buffer.isBuffer(x) return x`) that skips the re-view
+// hands the caller an empty buffer, so a downstream digest / signature / parse
+// silently processes EMPTY input instead of failing (CWE-20 improper input
+// validation feeding a CWE-347-style verification-of-nothing). Always re-viewing
+// through Buffer.from(x.buffer, x.byteOffset, x.byteLength) turns the detached
+// read into a typed reject at the boundary. Size / length-field allocation
+// bounds (CWE-770 / CWE-400, the parser-DoS class) are NOT enforced here -- they
+// are per-format (a multi-MB CRL is legitimate, a Merkle proof is tiny), so they
+// live in guard-params and each decoder's own cap.
+
+// view(input, ErrorClass, code, label) -> Buffer view | throws ErrorClass(code, msg, cause)
+// Accepts a Buffer / Uint8Array -- the DER / CBOR / CT / Merkle input contract.
+// ErrorClass MUST be a withCause PkiError subclass (the raw detach failure is
+// threaded as the cause).
+// @enforced-by guard-shape-reinlined
+// @guard-shape Buffer\.from\(\s*([A-Za-z_$][\w$]*)\.buffer\s*,\s*\1\.byteOffset
+function view(input, ErrorClass, code, label) {
+  if (Buffer.isBuffer(input) || input instanceof Uint8Array) {
+    try {
+      return Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+    } catch (e) {
+      throw new ErrorClass(code, label + ": input is not a usable byte view (detached backing buffer?)", e);
+    }
+  }
+  throw new ErrorClass(code, label + ": expected a Buffer / Uint8Array");
+}
+
+// source(input, ErrorClass, code, label) -> Buffer | throws ErrorClass
+// Accepts the full W3C BufferSource (Buffer / TypedArray view / raw ArrayBuffer)
+// -- the WebCrypto input contract. A raw ArrayBuffer is copied via Buffer.from,
+// which also throws on a detached backing store.
+// @enforced-by guard-shape-reinlined  (the re-view shape is declared on view above)
+function source(input, ErrorClass, code, label) {
+  var isAb = input instanceof ArrayBuffer;
+  if (isAb || ArrayBuffer.isView(input)) {
+    try {
+      return isAb ? Buffer.from(input) : Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+    } catch (e) {
+      throw new ErrorClass(code, label + ": input is not a usable byte source (detached backing buffer?)", e);
+    }
+  }
+  throw new ErrorClass(code, label + ": expected a BufferSource (ArrayBuffer / TypedArray / Buffer)");
+}
+
+module.exports = { view: view, source: source };

package/lib/guard-crypto.js

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal -- no operator-facing namespace. The documented surface is the
+// verify paths whose comparison composes this guard (pki.merkle,
+// pki.webcrypto.subtle.verify).
+//
+// guard-crypto -- fail-closed cryptographic-invariant guards. Enforced choke
+// point: a codebase-patterns detector requires every constant-time byte
+// comparison to route through here, so no verify path re-implements it with a
+// timing leak.
+//
+// Defends the timing side-channel class (CWE-208 observable timing discrepancy;
+// the Lucky13 / MAC-forgery family). A secret-dependent byte comparison with an
+// early exit (=== or a short-circuited &&) leaks the position of the first
+// differing byte, letting an attacker recover a MAC / tag / tree root
+// byte-by-byte. constantTimeEqual runs the whole comparison: a public length
+// gate (lengths are not secret; crypto.timingSafeEqual RangeErrors on unequal
+// lengths, so the gate must precede it) then a single timingSafeEqual over the
+// equal-length buffers -- both operands are always read, no data-dependent
+// branch. A length mismatch is an honest false, never a throw.
+
+var nodeCrypto = require("node:crypto");
+
+// constantTimeEqual(a, b) -> boolean. Length-checked, then constant-time over
+// equal lengths. a and b are Buffers.
+// @enforced-by guard-shape-reinlined
+// @guard-shape \.timingSafeEqual\s*\(
+function constantTimeEqual(a, b) {
+  return a.length === b.length && nodeCrypto.timingSafeEqual(a, b);
+}
+
+module.exports = { constantTimeEqual: constantTimeEqual };

package/lib/guard-limits.js

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal -- no operator-facing namespace. The documented surface is the
+// decoders whose option validation composes these guards (pki.asn1.decode,
+// pki.cbor.decode).
+//
+// guard-limits -- fail-closed validation of operator-supplied decode limits at
+// config time (the tier that throws on a bad argument so the operator catches
+// the typo at boot). Enforced choke point: a codebase-patterns detector requires
+// the stack-safe recursion ceiling to live only here, so a new decoder cannot be
+// configured past it.
+//
+// Defends the parser-DoS / resource-exhaustion class (CWE-834 excessive
+// recursion, CWE-770 allocation without limits; MITRE T1499.001; D3FEND
+// Recursion-Bounding + Input-Size-Restriction). A recursive-descent decoder
+// bounded only by a caller-tunable maxDepth overflows the native call stack (a
+// raw RangeError, not a typed verdict) once the cap is raised past the frame
+// limit; depthCap refuses a maxDepth above the stack-safe ceiling. A bad limit
+// is an authoring bug, so this tier throws a TypeError (not a PkiError). NIST
+// 800-53 SI-10 / SC-5 do not require these bounds (framework lag) -- the bound
+// at the parser is the actual control.
+
+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).
+// @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) {
+  if (value === undefined) return dflt;
+  if (!Number.isInteger(value) || value < 0) {
+    throw new TypeError("decode: " + key + " must be a non-negative integer");
+  }
+  return value;
+}
+
+// depthCap(value, key, dflt) -> a validated recursion-depth cap: cap() plus the
+// stack-safe ceiling, so a raised maxDepth cannot drive recursive descent into a
+// raw RangeError past the native frame limit.
+// @enforced-by guard-shape-reinlined
+// @guard-scope file
+// @guard-shape \bopts\.maxDepth\b
+// @guard-shape \bdepth\s*\+\s*1\b
+// @guard-via \.depthCap\s*\(
+function depthCap(value, key, dflt) {
+  var n = cap(value, key, dflt);
+  if (n > constants.LIMITS.MAX_DECODE_DEPTH_CEILING) {
+    throw new TypeError("decode: " + key + " " + n + " exceeds the stack-safe ceiling " + constants.LIMITS.MAX_DECODE_DEPTH_CEILING);
+  }
+  return n;
+}
+
+module.exports = { cap: cap, depthCap: depthCap };

package/lib/guard-name.js

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal -- no operator-facing namespace. The documented surface is the
+// 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.
+//
+// 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
+// names compare equal (or a UI truncate at the NUL), so a cert issued for
+// "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.
+
+// assertNoControlBytes(str, E, code, label) -> str | throws E(code, ...)
+// DirectoryString policy (a DN attribute value): reject NUL and C0 control bytes
+// in a DECODED name string. TAB (0x09) is exempt; printable non-ASCII (a
+// UTF8String CN carries accented / CJK characters) is allowed. `str` is assumed a
+// string (the caller guards typeof). E is the (code, message) typed-error factory.
+// @enforced-by behavioral -- the control-byte reject has no rename-proof code
+//   shape distinct from the ASN.1 charset readers; the CVE-2009-2408 RED vectors
+//   (a DN string with an embedded NUL / control byte rejects) are the guard.
+function assertNoControlBytes(str, E, code, label) {
+  for (var i = 0; i < str.length; i++) {
+    var c = str.charCodeAt(i);
+    if (c === 0 || (c < 0x20 && c !== 0x09)) {
+      throw E(code, label + " contains an embedded control byte (CVE-2009-2408)");
+    }
+  }
+  return str;
+}
+
+// assertPrintableIa5(buf, E, code, label) -> buf | throws E(code, ...)
+// IA5String policy (a dNSName / rfc822Name / URI GeneralName): every byte must be
+// printable 7-bit ASCII [0x20, 0x7e] -- an embedded NUL / control byte enables the
+// same name-truncation bypass downstream. `buf` is the raw GeneralName content.
+// @enforced-by behavioral -- the printable-IA5 byte-range reject has no rename-proof
+//   code shape distinct from the ASN.1 IA5 reader; the CVE-2009-2408 RED vectors
+//   (a SAN with a control byte rejects) are the guard.
+function assertPrintableIa5(buf, E, code, label) {
+  for (var i = 0; i < buf.length; i++) {
+    if (buf[i] < 0x20 || buf[i] > 0x7e) {
+      throw E(code, label + " must be a printable IA5String (no control bytes)");
+    }
+  }
+  return buf;
+}
+
+module.exports = { assertNoControlBytes: assertNoControlBytes, assertPrintableIa5: assertPrintableIa5 };

package/lib/guard-range.js

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal -- no operator-facing namespace. The documented surface is the
+// parsers whose decoded-integer bounds compose this guard (pki.schema.x509 /
+// crl / pkcs12 / cmp, pki.path.validate).
+//
+// guard-range -- fail-closed bound of an untrusted DECODED integer before it is
+// narrowed to a JS Number. Parse-time (Tier-2): the value is malformed content,
+// so it throws the caller's typed PkiError -- distinct from guard-limits, which
+// validates an operator-supplied option at config time (Tier-1, TypeError).
+//
+// Defends the silent-narrowing class (a decoded ASN.1 INTEGER past 2^53 rounds
+// when coerced to a Number, so a caller acting on the result -- a pathLen /
+// skipCerts / saltLength / iteration counter -- acts on the WRONG number;
+// CWE-190 integer overflow / CWE-681 incorrect conversion). The bound and the
+// narrow are ATOMIC here: a caller cannot obtain the Number without the range
+// having been enforced, so the value can never round silently and be acted on.
+
+// 2^31 - 1 -- the shared skip-cert / path-length / salt / iteration ceiling.
+// This literal lives ONLY here (a re-inline anywhere else is flagged: the
+// guard-shape walk anchors on the literal). 2^53 - 1 is the safe-narrow ceiling.
+var UINT31_MAX = 2147483647n;
+var SAFE_MAX   = 9007199254740991n;
+var SAFE_MIN   = -9007199254740991n;
+
+// int(value, min, max, E, code, label) -> a Number in [min, max].
+//   value : the BigInt result of an ASN.1 INTEGER / ENUMERATED read.
+//   min, max : inclusive BigInt bounds.
+//   E     : the (code, message, cause) typed-error factory in scope at the call
+//           site (ns.E / ctx.E / the module-local E) -- guard-range injects the
+//           caller's typed error through it, the tier-appropriate currency (a
+//           parse boundary carries a factory, not a bare ErrorClass).
+//   code  : the frozen domain/reason code this field rejects under.
+//   label : field phrase (+ optional RFC cite) for the message.
+// @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).
+  if (max > SAFE_MAX) {
+    throw new TypeError("guard.range.int: max " + max + " exceeds the safe-integer ceiling; use a BigInt-preserving guard");
+  }
+  if (min < SAFE_MIN) {
+    throw new TypeError("guard.range.int: min " + min + " is below the safe-integer floor; use a BigInt-preserving guard");
+  }
+  // Parse-time reject (Tier-2): malformed / out-of-range decoded content.
+  if (typeof value !== "bigint" || value < min || value > max) {
+    throw E(code, label + " must be an integer within " + min + ".." + max);
+  }
+  return Number(value);
+}
+
+// uint31(value, E, code, label) -> Number in [0, 2^31-1]. The DER-INTEGER
+// non-negative skip/path/salt shape (RFC 5280 / 4211 / 9810).
+// @enforced-by guard-shape-reinlined  (shares the 2147483647n shape declared on int)
+function uint31(value, E, code, label) { return int(value, 0n, UINT31_MAX, E, code, label); }
+
+// positiveInt31(value, E, code, label) -> Number in [1, 2^31-1]. The PKCS#12
+// PBKDF2 / MAC iteration-count shape (a count of at least one).
+// @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 };

package/lib/guard-text.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal -- no operator-facing namespace. The documented surface is the
+// primitives whose text boundaries compose this guard (pki.jose.parseJson, the
+// PEM decoders, the EST transfer decoders).
+//
+// guard-text -- fail-closed decode of an untrusted byte-source input to a
+// string, capping the RAW byte length BEFORE the string is materialized.
+// Enforced choke point for the byte->string boundary.
+//
+// Defends the parser-DoS string-allocation class (CWE-770 allocation without
+// limits, CWE-400 uncontrolled resource consumption; MITRE T1499.001). The
+// ORDERING is the invariant: cap the byte length, THEN decode. Decoding a Buffer
+// to a string first allocates a full-size string for input the cap is about to
+// reject; worse, a buffer above Node's max string length escapes the decode as
+// an untyped ERR_STRING_TOO_LONG instead of the caller's typed <tooLarge>. This
+// guard defines the cap-before-copy ordering and the fatal-UTF-8 decode once so
+// no boundary re-derives it (and drifts to cap-after, as some had).
+
+var bytes = require("./guard-bytes");
+
+var LATIN1 = "latin1";
+
+// decode(input, maxBytes, ErrorClass, spec) -> string.
+//   input     : a Buffer (decoded per spec.charset) or a string (taken as-is).
+//   maxBytes  : the raw byte-length ceiling, checked BEFORE any string copy.
+//   ErrorClass: a PkiError subclass (withCause where spec.fatal is set).
+//   spec      : { charset: "latin1"|"utf-8" (default latin1),
+//                 fatal:   boolean -- strict UTF-8 (a lone continuation /
+//                          truncated sequence throws, never substitutes U+FFFD),
+//                 tooLarge: code for the over-cap reject,
+//                 badDecode: code for a fatal-charset (bad-UTF-8) reject
+//                            (required only when fatal is set),
+//                 badInput: code for a non-Buffer/non-string reject,
+//                 label:    human phrase for the message }
+// @enforced-by behavioral -- cap-before-copy has no rename-proof code shape; the
+//   over-cap RED vectors + the detached re-view through guard.bytes.view (itself
+//   enforced) are the guard.
+function decode(input, maxBytes, ErrorClass, spec) {
+  var charset = spec.charset || LATIN1;
+  if (Buffer.isBuffer(input)) {
+    // Re-view through the byte guard FIRST so a detached backing ArrayBuffer (a
+    // transferred / structuredClone'd Buffer, which reads as zero-length) fails
+    // closed here -- the same detached-buffer defence the byte boundaries get --
+    // instead of being decoded as an empty string. Then cap, then decode.
+    input = bytes.view(input, ErrorClass, spec.badInput, spec.label);
+    if (input.length > maxBytes) throw new ErrorClass(spec.tooLarge, spec.label + " exceeds the size cap");
+    if (spec.fatal) {
+      try { return new TextDecoder(charset, { fatal: true }).decode(input); }
+      catch (e) { throw new ErrorClass(spec.badDecode, spec.label + " is not valid " + charset, e); }
+    }
+    return input.toString(charset);
+  }
+  if (typeof input === "string") {
+    // A latin1 string's char length equals its byte length; a UTF-8 string's
+    // does not, so bound the encoded byte length.
+    var byteLen = charset === LATIN1 ? input.length : Buffer.byteLength(input, "utf8");
+    if (byteLen > maxBytes) throw new ErrorClass(spec.tooLarge, spec.label + " exceeds the size cap");
+    return input;
+  }
+  throw new ErrorClass(spec.badInput, spec.label + " expects a string or Buffer");
+}
+
+module.exports = { decode: decode };