@blamejs/pki 0.1.28 → 0.1.30

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.28 — 2026-07-11
+## 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.
+
+### Fixed
+
+- pki.webcrypto digest / sign / verify no longer silently process a detached-backed Buffer as EMPTY input (a fail-open where a transferred backing ArrayBuffer left the view zero-length); a detached BufferSource is now rejected with a typed webcrypto/data error, as is getRandomValues.
+- pki.asn1.decode, pki.cbor.decode, and pki.ct.parseSctList reject a detached-backed Buffer or view with a typed error (asn1/not-buffer, cbor/not-buffer, ct/bad-input) instead of a raw TypeError or a misleading truncated-input verdict. The underlying byte-view failure is threaded as the error cause.
+
+## v0.1.28 — 2026-07-10
 
 Merkle transparency proof verification joins the toolkit as pki.merkle.
 

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,9 +106,7 @@ function _className(bits) {
 }
 
 function _asBuffer(input, who) {
-  if (Buffer.isBuffer(input)) return input;
-  if (input instanceof Uint8Array) return Buffer.from(input);
-  throw new Asn1Error("asn1/not-buffer", who + ": expected a Buffer / Uint8Array");
+  return guard.bytes.view(input, Asn1Error, "asn1/not-buffer", who);
 }
 
 // ---- Decoder --------------------------------------------------------
@@ -150,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,19 +58,7 @@ var _utf8 = new TextDecoder("utf-8", { fatal: true });
 var _MAX_EPOCH_SECONDS = 8640000000000n;
 
 function _asBuffer(input, who) {
-  if (Buffer.isBuffer(input)) return input;
-  if (input instanceof Uint8Array) return Buffer.from(input.buffer, input.byteOffset, input.byteLength);
-  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"
@@ -271,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,9 +112,7 @@ function _peelInner(extValue) {
 }
 
 function _toBuffer(v, field) {
-  if (Buffer.isBuffer(v)) return v;
-  if (v instanceof Uint8Array) return Buffer.from(v);
-  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
@@ -199,10 +198,7 @@ function _parseSct(r, sctLen) {
  *   }
  */
 function parseSctList(extValue) {
-  if (!Buffer.isBuffer(extValue) && !(extValue instanceof Uint8Array)) {
-    throw new CtError("ct/bad-input", "parseSctList expects the SCT-list extension value as a Buffer or Uint8Array");
-  }
-  var blob = _peelInner(Buffer.isBuffer(extValue) ? extValue : Buffer.from(extValue));
+  var blob = _peelInner(_toBuffer(extValue, "the SCT-list extension value"));
   if (blob.length > C.LIMITS.SCT_MAX_BYTES) {
     throw new CtError("ct/too-large", "SCT list " + blob.length + " bytes exceeds the cap " + C.LIMITS.SCT_MAX_BYTES);
   }

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

@@ -127,8 +127,9 @@ var ConstantsError = defineClass("ConstantsError");
 // Asn1Error -- malformed / non-canonical DER: truncated TLV, indefinite
 // length, non-minimal length or integer, leftover trailing bytes, depth
 // or size cap exceeded. DER is a canonical encoding, so anything the
-// decoder rejects is permanently invalid.
-var Asn1Error = defineClass("Asn1Error");
+// decoder rejects is permanently invalid. withCause threads a raw byte-view
+// failure (a detached backing ArrayBuffer) as the cause rather than discarding it.
+var Asn1Error = defineClass("Asn1Error", { withCause: true });
 
 // CborError -- malformed / non-deterministic CBOR: a reserved or indefinite
 // additional-info value, a stray break, a non-minimal ("preferred") argument,
@@ -136,17 +137,19 @@ var Asn1Error = defineClass("Asn1Error");
 // key, a non-minimal / oversized bignum, bad UTF-8, a wrong-typed tag body,
 // leftover trailing bytes, or a depth / size cap exceeded. RFC 8949 core-
 // deterministic encoding (sec. 4.2.1) is canonical, so anything the decoder
-// rejects is permanently invalid.
-var CborError = defineClass("CborError");
+// rejects is permanently invalid. withCause threads a raw byte-view failure
+// (a detached backing ArrayBuffer) as the cause rather than discarding it.
+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,38 @@
+// 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)
+//
+// 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");
+
+module.exports = {
+  bytes:  bytes,
+  text:   text,
+  limits: limits,
+  crypto: crypto,
+};

package/lib/guard-bytes.js

@@ -0,0 +1,57 @@
+// 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).
+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.
+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,32 @@
+// 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.
+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,49 @@
+// 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).
+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.
+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-text.js

@@ -0,0 +1,63 @@
+// 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 }
+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 };

package/lib/jose.js

@@ -38,6 +38,7 @@
 var constants = require("./constants");
 var webcrypto = require("./webcrypto").webcrypto;
 var frameworkError = require("./framework-error");
+var guard = require("./guard-all");
 
 var JoseError = frameworkError.JoseError;
 function E(code, message, cause) { return new JoseError(code, message, cause); }
@@ -228,17 +229,11 @@ function _jsonReader(str) {
  *   pki.jose.parseJson('{"a":1}');   // -> { a: 1 }
  */
 function parseJson(input) {
-  var str;
-  if (Buffer.isBuffer(input)) {
-    if (input.length > LIMITS.JSON_MAX_BYTES) throw E("jose/too-large", "the JSON document exceeds the size cap");
-    try { str = new TextDecoder("utf-8", { fatal: true }).decode(input); }
-    catch (e) { throw E("jose/bad-json", "the JSON document is not valid UTF-8", e); }
-  } else if (typeof input === "string") {
-    if (Buffer.byteLength(input, "utf8") > LIMITS.JSON_MAX_BYTES) throw E("jose/too-large", "the JSON document exceeds the size cap");
-    str = input;
-  } else {
-    throw E("jose/bad-input", "parseJson requires a Buffer or string");
-  }
+  // 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",
+  });
   return _jsonReader(str);
 }
 

package/lib/merkle.js

@@ -44,6 +44,7 @@
 var nodeCrypto = require("node:crypto");
 var constants = require("./constants");
 var frameworkError = require("./framework-error");
+var guard = require("./guard-all");
 
 var MerkleError = frameworkError.MerkleError;
 
@@ -58,17 +59,7 @@ function _sha256(buf) {
 }
 
 function _toBuffer(v, field) {
-  if (!Buffer.isBuffer(v) && !(v instanceof Uint8Array)) {
-    throw new MerkleError("merkle/bad-input", field + " must be a Buffer or Uint8Array");
-  }
-  try {
-    // A zero-copy view over the same bytes; this also surfaces a detached
-    // backing ArrayBuffer (a transferred / structuredClone'd view) as a typed
-    // error here rather than a raw TypeError from a later concat / digest.
-    return Buffer.from(v.buffer, v.byteOffset, v.byteLength);
-  } catch (e) {
-    throw new MerkleError("merkle/bad-input", field + " is not a usable byte view", e);
-  }
+  return guard.bytes.view(v, MerkleError, "merkle/bad-input", field);
 }
 
 function _node32(v, field) {
@@ -113,7 +104,7 @@ function _proofNodes(proof) {
 
 // Constant-time equality of two already-validated equal-length 32-byte buffers.
 function _ctEq(a, b) {
-  return a.length === b.length && nodeCrypto.timingSafeEqual(a, b);
+  return guard.crypto.constantTimeEqual(a, b);
 }
 
 /**

package/lib/oid.js

@@ -35,6 +35,7 @@
 
 var asn1 = require("./asn1-der");
 var frameworkError = require("./framework-error");
+var guard = require("./guard-all");
 
 var OidError = frameworkError.OidError;
 
@@ -454,7 +455,7 @@ function fromArcs(arcs) {
 // one namespace when they have a dotted string in hand.
 function toDER(dotted) { _assertDotted(dotted, "toDER"); return asn1.build.oid(dotted); }
 function fromDER(input) {
-  var buf = Buffer.isBuffer(input) ? input : Buffer.from(input);
+  var buf = guard.bytes.view(input, OidError, "oid/bad-input", "fromDER");
   var node = asn1.decode(buf);
   return asn1.read.oid(node);
 }

package/lib/schema-pkix.js

@@ -16,6 +16,7 @@
 var asn1 = require("./asn1-der");
 var constants = require("./constants");
 var schema = require("./schema-engine");
+var guard = require("./guard-all");
 // ct is a leaf format module (requires only the codec / oid / constants / error
 // core, never pkix) so the SCT-list extension VALUE decoder registers here as a
 // registry row, not a switch. The one-directional edge keeps the layering acyclic.
@@ -35,16 +36,13 @@ var PEM_RE = /-----BEGIN ([A-Z0-9 ]+)-----([\s\S]*?)-----END \1-----/;
 // lenient Buffer.from would otherwise let several distinct PEM texts alias one
 // DER (PEM-layer malleability) and silently drop trailing content bits.
 function pemDecode(text, label, PemError) {
-  // The size cap is enforced on the raw byte length BEFORE the latin1 string
-  // copy: converting first would allocate a full-size string for an input the
-  // cap is about to reject, and a buffer above Node's max string length would
-  // escape as an untyped ERR_STRING_TOO_LONG instead of pem/too-large.
-  if (Buffer.isBuffer(text)) {
-    if (text.length > constants.LIMITS.PEM_MAX_BYTES) throw new PemError("pem/too-large", "PEM input exceeds size cap");
-    text = text.toString("latin1");
-  }
-  if (typeof text !== "string") throw new PemError("pem/bad-input", "pemDecode expects a string or Buffer");
-  if (text.length > constants.LIMITS.PEM_MAX_BYTES) throw new PemError("pem/too-large", "PEM input exceeds size cap");
+  // guard.text.decode caps the raw byte length BEFORE the latin1 string copy:
+  // converting first would allocate a full-size string for input the cap is
+  // about to reject, and a buffer above Node's max string length would escape as
+  // an untyped ERR_STRING_TOO_LONG instead of pem/too-large.
+  text = guard.text.decode(text, constants.LIMITS.PEM_MAX_BYTES, PemError, {
+    charset: "latin1", tooLarge: "pem/too-large", badInput: "pem/bad-input", label: "PEM input",
+  });
   var m = PEM_RE.exec(text);
   if (!m) throw new PemError("pem/no-block", "no PEM block found");
   if (label && m[1] !== label) throw new PemError("pem/label-mismatch", "expected " + JSON.stringify(label) + " block, got " + JSON.stringify(m[1]));
@@ -64,12 +62,9 @@ function pemDecode(text, label, PemError) {
 // base64 body is canonical (the pemDecode rule); returns an array of DER buffers.
 function pemDecodeAll(text, label, PemError) {
   label = label || "CERTIFICATE";
-  if (Buffer.isBuffer(text)) {
-    if (text.length > constants.LIMITS.PEM_MAX_BYTES) throw new PemError("pem/too-large", "PEM input exceeds size cap");
-    text = text.toString("latin1");
-  }
-  if (typeof text !== "string") throw new PemError("pem/bad-input", "pemDecodeAll expects a string or Buffer");
-  if (text.length > constants.LIMITS.PEM_MAX_BYTES) throw new PemError("pem/too-large", "PEM input exceeds size cap");
+  text = guard.text.decode(text, constants.LIMITS.PEM_MAX_BYTES, PemError, {
+    charset: "latin1", tooLarge: "pem/too-large", badInput: "pem/bad-input", label: "PEM input",
+  });
   var re = /-----BEGIN ([A-Z0-9 ]+)-----([\s\S]*?)-----END \1-----/g;
   var blocks = [];
   var lastEnd = 0, m;
@@ -107,9 +102,12 @@ function pemEncode(der, label, PemError) {
 // Uint8Array is taken as bytes. opts: { pemLabel, PemError, ErrorClass, prefix }.
 function coerceToDer(input, opts) {
   if (typeof input === "string") return pemDecode(input, opts.pemLabel, opts.PemError);
-  if (input instanceof Uint8Array && !Buffer.isBuffer(input)) input = Buffer.from(input);
-  if (Buffer.isBuffer(input)) {
-    return _isPemArmor(input) ? pemDecode(input, opts.pemLabel, opts.PemError) : input;
+  if (Buffer.isBuffer(input) || input instanceof Uint8Array) {
+    // Route the DER Buffer / Uint8Array through the shared byte guard so a
+    // detached backing store fails closed here for EVERY format that composes
+    // this boundary (x509/crl/csr/pkcs8/cms/pkcs12), not per-format.
+    var buf = guard.bytes.view(input, opts.ErrorClass, opts.prefix + "/bad-input", "parse");
+    return _isPemArmor(buf) ? pemDecode(buf, opts.pemLabel, opts.PemError) : buf;
   }
   throw new opts.ErrorClass(opts.prefix + "/bad-input", "parse expects a DER Buffer or a PEM string");
 }

package/lib/webcrypto.js

@@ -35,6 +35,7 @@
 
 var nodeCrypto = require("node:crypto");
 var frameworkError = require("./framework-error");
+var guard = require("./guard-all");
 
 // Single-owner error class -- co-located with its module (framework-error
 // stays the cross-module home; this is webcrypto-private). withCause: a
@@ -47,10 +48,7 @@ var MAX_RANDOM_BYTES = 65536;
 // ---- value helpers ---------------------------------------------------
 
 function _toBuf(data, who) {
-  if (Buffer.isBuffer(data)) return data;
-  if (data instanceof ArrayBuffer) return Buffer.from(data);
-  if (ArrayBuffer.isView(data)) return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
-  throw new WebCryptoError("webcrypto/data", (who || "input") + ": expected BufferSource (ArrayBuffer / TypedArray / Buffer)");
+  return guard.bytes.source(data, WebCryptoError, "webcrypto/data", who || "input");
 }
 
 function _toArrayBuffer(buf) {
@@ -343,7 +341,7 @@ SubtleCrypto.prototype.verify = async function verify(algorithm, key, signature,
     // in constant time. The length check leaks nothing a constant-time compare
     // would protect; the secret-dependent byte comparison is timingSafeEqual.
     var digest = hm.digest();
-    return digest.length === sig.length && nodeCrypto.timingSafeEqual(digest, sig);
+    return guard.crypto.constantTimeEqual(digest, sig);
   }
   throw new WebCryptoError("webcrypto/not-supported", "verify: unsupported algorithm " + JSON.stringify(name));
 };
@@ -718,7 +716,11 @@ Crypto.prototype.getRandomValues = function getRandomValues(typedArray) {
   if (typedArray.byteLength > MAX_RANDOM_BYTES) {
     throw new WebCryptoError("webcrypto/data", "getRandomValues: byteLength exceeds " + MAX_RANDOM_BYTES);
   }
-  nodeCrypto.randomFillSync(Buffer.from(typedArray.buffer, typedArray.byteOffset, typedArray.byteLength));
+  // Re-view the (already integer-TypedArray-validated) output buffer via
+  // guard.bytes.source -- any TypedArray, not just Uint8Array -- so a detached
+  // backing store fails closed here; the returned Buffer aliases typedArray, so
+  // randomFillSync writes through to the caller's array.
+  nodeCrypto.randomFillSync(guard.bytes.source(typedArray, WebCryptoError, "webcrypto/data", "getRandomValues"));
   return typedArray;
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
   "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:e10c86e3-914c-4324-abeb-585344830973",
+  "serialNumber": "urn:uuid:9b3c1a14-9eb9-492b-a652-b6fa68d6b4b4",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-11T04:47:27.941Z",
+    "timestamp": "2026-07-11T07:38:46.451Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.1.28",
+      "bom-ref": "@blamejs/pki@0.1.30",
       "type": "application",
       "name": "pki",
-      "version": "0.1.28",
+      "version": "0.1.30",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
-      "purl": "pkg:npm/%40blamejs/pki@0.1.28",
+      "purl": "pkg:npm/%40blamejs/pki@0.1.30",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.1.28",
+      "ref": "@blamejs/pki@0.1.30",
       "dependsOn": []
     }
   ]