@blamejs/pki 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -4,6 +4,34 @@ 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.2 — 2026-07-04
+
+Fail-closed hardening across the DER codec, WebCrypto engine, and X.509 parser.
+
+### Changed
+
+- pki.oid gains registerFamily(base, members): register a whole OID arc family in one call by its shared base arc and each member's trailing leaf. The built-in registry is now declared this way, so a new object identifier is a data entry under its family rather than a re-spelled full path.
+- Every primitive now declares the normative reference it is derived from (@spec) and, where it guards a known attack, the class it defends (@defends). The generated reference documentation links each citation to its source — RFC section anchors, NIST FIPS, ITU-T, W3C, CVE and CWE — so the surface is traceable to the standards it implements.
+
+### Fixed
+
+- pki.asn1.read.time rejects semantically invalid UTCTime/GeneralizedTime values (Feb 30, month 13, hour 25, second 60, day 00) instead of silently normalizing them, and preserves a four-digit GeneralizedTime year below 100 instead of remapping it a century, so a malformed or edge-case certificate validity window no longer parses to a shifted instant that disagrees with a strict verifier.
+- The DER encoder is now symmetric with the decoder — no builder can emit DER the decoder would reject: build.utcTime rejects a year outside RFC 5280's 1950-2049 window rather than wrapping it a century, build.generalizedTime zero-pads the year to four digits, build.set orders its components as DER requires, build.integer/enumerated reject an empty or non-minimal content buffer, build.oid caps each sub-identifier, and build.ia5 rejects non-ASCII bytes.
+- String decoding validates each restricted type: IA5String and VisibleString reject bytes outside their permitted range, PrintableString rejects characters outside its restricted set, and UTF8String rejects malformed UTF-8 instead of substituting the Unicode replacement character — closing a parser-differential on certificate name fields.
+- BIT STRING decoding enforces DER's requirement that unused trailing bits be zero and rejects an empty BIT STRING that declares unused bits; UniversalString and BMPString decoding reject out-of-range and lone-surrogate code points with a typed Asn1Error instead of a bare RangeError.
+- HMAC verify resolves false for a wrong-length signature instead of throwing, per the Web Cryptography API. AES-CTR encrypt/decrypt reject a counter length other than 128 rather than silently ignoring the parameter.
+- pki.x509.parse raises a typed CertificateError (not a generic TypeError) for a truncated tbsCertificate, rejects a certificate carrying duplicate extensions (RFC 5280 §4.2), rejects a tbsCertificate with a repeated or out-of-order trailing field — a second extensions [3] wrapper (which would otherwise hide the first extension block and split duplicate extension OIDs across two wrappers past the per-extension check), or an out-of-order or unknown context field (RFC 5280 §4.1), rejects an empty issuer distinguished name (RFC 5280 §4.1.2.4) while still permitting an empty subject for the subjectAltName case, rejects an empty or non-SEQUENCE extensions field (RFC 5280 §4.1.2.9) with a typed error rather than a raw TypeError, validates the certificate version against the RFC 5280 set, and fails closed on a malformed string in a distinguished name (an invalid-UTF8 or out-of-range name value) instead of hex-escaping the invalid bytes away, so the decoder's strict string validation is enforced on the name path; a genuinely non-string attribute value (a primitive ANY-typed value, or a constructed non-string type such as a SEQUENCE) still renders as its RFC 4514 hex-encoded DER so the name stays representable.
+- pki.oid.fromArcs rejects a negative or unsafe-integer arc instead of emitting a malformed OID string; the OID sub-identifier ceiling admits a 128-bit UUID-based arc; and the INTEGER ceiling admits a key at the magnitude cap with its DER sign octet.
+- pki.version, pki.C.version, and the CLI now report the installed package version — the value is single-sourced from the package manifest and can no longer drift from the published release.
+
+### Security
+
+- The DER decoder now builds every INTEGER and OID sub-identifier in a single linear pass and refuses any that exceed a per-value byte ceiling (C.LIMITS.DER_MAX_INTEGER_BYTES / OID sub-identifier limit), before reading them. Previously these values were accumulated a byte at a time, which is quadratic in their length: a certificate carrying an oversized serial number or OID arc — well within the overall size cap — could pin a CPU for minutes. This closes a remotely-triggerable decode denial-of-service reachable through pki.x509.parse and pki.asn1.read.*.
+- The DER decoder rejects a primitive-encoded SEQUENCE or SET (X.690 §8.9.1/§8.11.1 require these to be constructed) rather than producing a leaf node. Previously such input decoded to a leaf that pki.x509.parse dereferenced as a structured node, crashing with an uncaught TypeError on attacker-controlled bytes; it now fails closed with a typed error.
+- The DER decoder also rejects the mirror violation — a constructed encoding of a universal primitive-only type (INTEGER, OBJECT IDENTIFIER, BOOLEAN, the restricted strings, UTCTime/GeneralizedTime, BIT/OCTET STRING), which is valid BER but not valid DER (X.690 §10.2). Previously a constructed string tag decoded to a childless node that a certificate distinguished name would hex-render, letting an invalid BER/DER name value parse despite the restricted-string content checks; it now fails closed at decode.
+- pki.webcrypto.subtle.unwrapKey now enforces the 'unwrapKey' key usage on every unwrap path, including the RSA-OAEP and AES-GCM delegate paths that previously skipped it — an unwrapping key without the 'unwrapKey' usage is now rejected. deriveKey now enforces the distinct 'deriveKey' usage rather than inheriting 'deriveBits'. Both close cases where an operator-set key-usage restriction could be bypassed.
+- pki.x509.parse now rejects a certificate whose outer signatureAlgorithm does not match the signature algorithm inside the signed tbsCertificate (RFC 5280 §4.1.1.2). Surfacing the two AlgorithmIdentifiers without enforcing their equality let a certificate claim one algorithm in the signed body and another in the outer wrapper — a signature-algorithm-substitution vector; the two fields must now be identical.
+
 ## v0.1.1 — 2026-07-04
 
 First published release of the 0.1.x foundation.

package/lib/asn1-der.js

@@ -65,6 +65,20 @@ var CLASS_CONTEXT     = 0x80;
 var CLASS_PRIVATE     = 0xc0;
 var CONSTRUCTED_BIT   = 0x20;
 
+// X.690 §8.x / §10.2 (DER) — every universal type the codec handles other than
+// SEQUENCE and SET is a primitive-only type: it MUST be encoded primitive, and
+// a constructed encoding (BOOLEAN, INTEGER, OID, the restricted strings,
+// UTC/GeneralizedTime, and — DER-strict — BIT STRING / OCTET STRING) is not
+// valid DER. Derived from TAGS so a newly-registered primitive type is covered
+// automatically. This is the mirror of the primitive-SEQUENCE/SET rejection.
+var PRIMITIVE_ONLY_UNIVERSAL_TAGS = (function () {
+  var s = Object.create(null);
+  Object.keys(TAGS).forEach(function (k) {
+    if (k !== "SEQUENCE" && k !== "SET") s[TAGS[k]] = true;
+  });
+  return s;
+})();
+
 function _className(bits) {
   switch (bits) {
     case CLASS_UNIVERSAL:   return "universal";
@@ -88,6 +102,8 @@ function _asBuffer(input, who) {
  * @signature  pki.asn1.decode(bytes, opts?) -> node
  * @since      0.1.0
  * @status     stable
+ * @spec       X.690, ISO/IEC 8825-1
+ * @defends    ASN.1-parser-DoS (CWE-400)
  * @related    pki.asn1.encode
  *
  * Parse DER into a node tree. Each node is
@@ -156,6 +172,22 @@ function _decodeTLV(buf, start, limit, depth, maxDepth) {
     }
   }
 
+  // X.690 8.9.1 / 8.11.1 — a universal SEQUENCE or SET is always constructed;
+  // a primitive-tagged 0x10 / 0x11 is not valid DER (and would decode to a
+  // leaf that constructed-structure consumers dereference as a parent).
+  if (tagClassBits === CLASS_UNIVERSAL && (tagNumber === TAGS.SEQUENCE || tagNumber === TAGS.SET) && !constructed) {
+    throw new Asn1Error("asn1/bad-tlv", "SEQUENCE/SET must be constructed");
+  }
+
+  // X.690 §8.x / §10.2 — the mirror rule: a universal primitive-only type
+  // (INTEGER, OID, BOOLEAN, the restricted strings, times, BIT/OCTET STRING)
+  // encoded constructed is not valid DER. Without this a constructed string
+  // tag decodes to a childless node that later paths (an X.509 DN attribute
+  // value) would hex-render or dereference instead of failing closed.
+  if (tagClassBits === CLASS_UNIVERSAL && constructed && PRIMITIVE_ONLY_UNIVERSAL_TAGS[tagNumber]) {
+    throw new Asn1Error("asn1/constructed-primitive-type", "a universal primitive-only type must be encoded primitive in DER");
+  }
+
   if (p >= limit) throw new Asn1Error("asn1/truncated", "expected a length octet");
   var lenByte = buf[p]; p += 1;
   var length;
@@ -239,15 +271,23 @@ function readInteger(node) {
   _expectPrimitive(node, "readInteger");
   var c = node.content;
   if (c.length === 0) throw new Asn1Error("asn1/bad-integer", "INTEGER must have at least 1 content octet");
+  // Defense-in-depth: refuse an over-cap magnitude before touching BigInt.
+  // A one-shot hex parse is linear, but the length still bounds worst-case
+  // work — reject a hostile length prefix up front. The cap bounds the
+  // MAGNITUDE; a positive INTEGER whose top bit is set carries one leading
+  // 0x00 DER sign octet, so allow cap + 1 content bytes (an RSA-131072
+  // modulus is 16384 magnitude bytes plus that sign pad).
+  if (c.length > constants.LIMITS.DER_MAX_INTEGER_BYTES + 1) {
+    throw new Asn1Error("asn1/integer-too-large",
+      "INTEGER content " + c.length + " bytes exceeds cap " + (constants.LIMITS.DER_MAX_INTEGER_BYTES + 1));
+  }
   if (c.length > 1) {
     if (c[0] === 0x00 && (c[1] & 0x80) === 0) throw new Asn1Error("asn1/non-minimal-integer", "non-minimal positive INTEGER");
     if (c[0] === 0xff && (c[1] & 0x80) !== 0) throw new Asn1Error("asn1/non-minimal-integer", "non-minimal negative INTEGER");
   }
   var neg = (c[0] & 0x80) !== 0;
-  var v = 0n;
-  for (var i = 0; i < c.length; i++) v = (v << 8n) | BigInt(c[i]);
-  if (neg) v -= (1n << BigInt(8 * c.length));
-  return v;
+  var mag = c.length ? BigInt("0x" + Buffer.from(c).toString("hex")) : 0n;
+  return neg ? mag - (1n << BigInt(c.length * 8)) : mag;
 }
 
 function readBitString(node) {
@@ -258,6 +298,12 @@ function readBitString(node) {
   var unusedBits = c[0];
   if (unusedBits > 7) throw new Asn1Error("asn1/bad-bit-string", "unused-bit count " + unusedBits + " > 7");
   if (unusedBits > 0 && c.length === 1) throw new Asn1Error("asn1/bad-bit-string", "unused bits declared over an empty body");
+  // X.690 11.2.1 — the declared unused low bits of the final octet must be
+  // zero in DER.
+  if (unusedBits > 0 && c.length > 1) {
+    var mask = (1 << unusedBits) - 1;
+    if ((c[c.length - 1] & mask) !== 0) throw new Asn1Error("asn1/bad-bit-string", "DER requires unused bits to be zero");
+  }
   return { unusedBits: unusedBits, bytes: c.subarray(1) };
 }
 
@@ -279,6 +325,7 @@ function readNull(node) {
  * @signature  pki.asn1.read.oid(node) -> "1.2.840.113549.1.1.11"
  * @since      0.1.0
  * @status     stable
+ * @spec       X.690 §8.19
  * @related    pki.oid.name
  *
  * Decode an OBJECT IDENTIFIER node to its dotted-decimal string, enforcing
@@ -296,16 +343,27 @@ function readOid(node) {
 function decodeOidContent(buf) {
   if (buf.length === 0) throw new OidError("oid/empty", "OBJECT IDENTIFIER content is empty");
   var arcs = [];
-  var value = 0n;
-  var started = false;
+  var arcStart = 0;
   for (var i = 0; i < buf.length; i++) {
     var b = buf[i];
-    if (!started && b === 0x80) throw new OidError("oid/non-minimal", "non-minimal sub-identifier (leading 0x80)");
-    value = (value << 7n) | BigInt(b & 0x7f);
-    started = true;
-    if ((b & 0x80) === 0) { arcs.push(value); value = 0n; started = false; }
+    if (i === arcStart && b === 0x80) throw new OidError("oid/non-minimal", "non-minimal sub-identifier (leading 0x80)");
+    // Cap the continuation-byte run so a single arc can't drive unbounded
+    // BigInt growth before it terminates.
+    if (i - arcStart >= constants.LIMITS.OID_MAX_SUBIDENTIFIER_BYTES) {
+      throw new OidError("oid/subidentifier-too-large",
+        "OID sub-identifier exceeds " + constants.LIMITS.OID_MAX_SUBIDENTIFIER_BYTES + " octets");
+    }
+    if ((b & 0x80) === 0) {
+      // Terminal octet: fold the whole [arcStart..i] slice base-128 in one
+      // bounded pass (the run is capped above), no per-bit accumulation
+      // across the full OID content.
+      var value = 0n;
+      for (var k = arcStart; k <= i; k++) value = value * 128n + BigInt(buf[k] & 0x7f);
+      arcs.push(value);
+      arcStart = i + 1;
+    }
   }
-  if (started) throw new OidError("oid/truncated", "OBJECT IDENTIFIER ends mid sub-identifier");
+  if (arcStart !== buf.length) throw new OidError("oid/truncated", "OBJECT IDENTIFIER ends mid sub-identifier");
   var first = arcs[0];
   var a1, a2;
   if (first < 40n) { a1 = 0n; a2 = first; }
@@ -320,15 +378,49 @@ function _decodeText(buf, encoding) {
   return buf.toString(encoding);
 }
 
+// IA5String is 7-bit ASCII (T.50 / IA5) — every content octet is 0x00..0x7F.
+function _decodeIa5(buf) {
+  for (var i = 0; i < buf.length; i++) {
+    if (buf[i] > 0x7F) throw new Asn1Error("asn1/bad-ia5-string", "IA5String requires 7-bit ASCII");
+  }
+  return buf.toString("latin1");
+}
+
+// VisibleString (ISO 646 IRV / X.690) is the printable ASCII range 0x20..0x7E
+// — no control characters and no bytes with the high bit set.
+function _decodeVisible(buf) {
+  for (var i = 0; i < buf.length; i++) {
+    if (buf[i] < 0x20 || buf[i] > 0x7E) throw new Asn1Error("asn1/bad-visible-string", "VisibleString must be 0x20..0x7E");
+  }
+  return buf.toString("latin1");
+}
+
+// PrintableString is restricted to A-Z a-z 0-9 space and ' ( ) + , - . / : = ?
+function _decodePrintable(buf) {
+  var s = buf.toString("latin1");
+  if (!PRINTABLE_RE.test(s)) throw new Asn1Error("asn1/bad-printable-string", "PrintableString has characters outside the restricted set");
+  return s;
+}
+
+// UTF8String must be well-formed UTF-8; a lenient decoder substitutes U+FFFD
+// for invalid sequences, silently mangling hostile input into valid text.
+function _decodeUtf8Strict(buf) {
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(buf);
+  } catch (_e) {
+    throw new Asn1Error("asn1/bad-utf8-string", "invalid UTF-8 in UTF8String");
+  }
+}
+
 function readString(node) {
   if (node.tagClass !== "universal") throw new Asn1Error("asn1/expected-string", "readString: not a universal string type");
   _expectPrimitive(node, "readString");
   switch (node.tagNumber) {
-    case TAGS.UTF8_STRING:      return _decodeText(node.content, "utf8");
-    case TAGS.PRINTABLE_STRING: return _decodeText(node.content, "latin1");
-    case TAGS.IA5_STRING:       return _decodeText(node.content, "latin1");
+    case TAGS.UTF8_STRING:      return _decodeUtf8Strict(node.content);
+    case TAGS.PRINTABLE_STRING: return _decodePrintable(node.content);
+    case TAGS.IA5_STRING:       return _decodeIa5(node.content);
     case TAGS.TELETEX_STRING:   return _decodeText(node.content, "latin1");
-    case TAGS.VISIBLE_STRING:   return _decodeText(node.content, "latin1");
+    case TAGS.VISIBLE_STRING:   return _decodeVisible(node.content);
     case TAGS.BMP_STRING:       return _decodeUtf16be(node.content);
     case TAGS.UNIVERSAL_STRING: return _decodeUtf32be(node.content);
     default:
@@ -338,6 +430,12 @@ function readString(node) {
 
 function _decodeUtf16be(buf) {
   if (buf.length % 2 !== 0) throw new Asn1Error("asn1/bad-bmp-string", "BMPString length must be even");
+  // BMPString encodes BMP scalar values only; a UTF-16 surrogate code unit
+  // here is a lone surrogate, not valid text.
+  for (var i = 0; i < buf.length; i += 2) {
+    var u = (buf[i] << 8) | buf[i + 1];
+    if (u >= 0xD800 && u <= 0xDFFF) throw new Asn1Error("asn1/bad-bmp-string", "code point out of range");
+  }
   var swapped = Buffer.from(buf);
   swapped.swap16();
   return swapped.toString("utf16le");
@@ -348,6 +446,11 @@ function _decodeUtf32be(buf) {
   var out = "";
   for (var i = 0; i < buf.length; i += 4) {
     var cp = (buf[i] * 0x1000000) + (buf[i + 1] << 16) + (buf[i + 2] << 8) + buf[i + 3];
+    // Reject non-scalar values (> U+10FFFF or a surrogate) before
+    // String.fromCodePoint would throw a bare RangeError / emit a lone surrogate.
+    if (cp > 0x10FFFF || (cp >= 0xD800 && cp <= 0xDFFF)) {
+      throw new Asn1Error("asn1/bad-universal-string", "code point out of range");
+    }
     out += String.fromCodePoint(cp);
   }
   return out;
@@ -379,9 +482,23 @@ function readTime(node) {
   var hour  = parseInt(m[4], 10);
   var min   = parseInt(m[5], 10);
   var sec   = parseInt(m[6], 10);
-  var t = Date.UTC(year, month - 1, day, hour, min, sec);
-  if (isNaN(t)) throw new Asn1Error("asn1/bad-time", "unparseable time " + JSON.stringify(s));
-  return new Date(t);
+  // Build from the LITERAL year via setUTCFullYear: the Date.UTC() / new Date()
+  // constructors remap a year in 0..99 to 1900..1999, which would corrupt a
+  // GeneralizedTime year below 100 (0099 -> 1999). setUTCFullYear(year, ...)
+  // takes the year literally and uses that year's own calendar, so years
+  // below 100 and proleptic leap years are handled correctly.
+  var d = new Date(0);
+  d.setUTCFullYear(year, month - 1, day);
+  d.setUTCHours(hour, min, sec, 0);
+  if (isNaN(d.getTime())) throw new Asn1Error("asn1/bad-time", "unparseable time " + JSON.stringify(s));
+  // Date/setUTC* silently roll over out-of-range fields (Feb 30 -> Mar 2,
+  // month 13 -> next Jan, hour 25 -> +1 day). Reject unless every component
+  // round-trips exactly.
+  if (d.getUTCFullYear() !== year || d.getUTCMonth() !== month - 1 || d.getUTCDate() !== day ||
+      d.getUTCHours() !== hour || d.getUTCMinutes() !== min || d.getUTCSeconds() !== sec) {
+    throw new Asn1Error("asn1/bad-time", "time component out of range " + JSON.stringify(s));
+  }
+  return d;
 }
 
 // ---- Encoder / builders ---------------------------------------------
@@ -413,6 +530,7 @@ function encodeIdentifier(classBits, constructed, tagNumber) {
  * @signature  pki.asn1.encode(classBits, constructed, tagNumber, content) -> Buffer
  * @since      0.1.0
  * @status     stable
+ * @spec       X.690, ISO/IEC 8825-1
  * @related    pki.asn1.decode
  *
  * Low-level TLV encoder — prepend the identifier + DER length to a content
@@ -471,6 +589,12 @@ function encodeOidContent(dotted) {
     var body = [];
     var v = subids[s];
     do { body.unshift(Number(v & 0x7fn)); v >>= 7n; } while (v > 0n);
+    // Keep the encoder symmetric with the decoder's per-arc cap so build.oid
+    // can't emit a sub-identifier read.oid would reject as hostile.
+    if (body.length > constants.LIMITS.OID_MAX_SUBIDENTIFIER_BYTES) {
+      throw new OidError("oid/subidentifier-too-large",
+        "OID sub-identifier exceeds " + constants.LIMITS.OID_MAX_SUBIDENTIFIER_BYTES + " octets");
+    }
     for (var k = 0; k < body.length - 1; k++) body[k] |= 0x80;
     for (var j = 0; j < body.length; j++) out.push(body[j]);
   }
@@ -482,13 +606,22 @@ var PRINTABLE_RE = /^[A-Za-z0-9 '()+,\-./:=?]*$/;
 function _fmtTwo(n) { return (n < 10 ? "0" : "") + n; }
 
 function _generalizedTimeString(date) {
-  return "" + date.getUTCFullYear() +
+  // GeneralizedTime is YYYYMMDDHHMMSSZ — a year below 1000 must still emit
+  // four digits, or read.time rejects the short (12-14 char) content.
+  var y = date.getUTCFullYear();
+  if (y < 0 || y > 9999) throw new Asn1Error("asn1/bad-generalizedtime", "GeneralizedTime year " + y + " outside 0000..9999");
+  var yyyy = ("000" + y).slice(-4);
+  return yyyy +
     _fmtTwo(date.getUTCMonth() + 1) + _fmtTwo(date.getUTCDate()) +
     _fmtTwo(date.getUTCHours()) + _fmtTwo(date.getUTCMinutes()) + _fmtTwo(date.getUTCSeconds()) + "Z";
 }
 
 function _utcTimeString(date) {
-  var yy = date.getUTCFullYear() % 100;
+  // RFC 5280 §4.1.2.5.1 restricts UTCTime to 1950..2049; a year outside that
+  // wraps to the wrong century (2050 -> "50" -> decodes as 1950).
+  var y = date.getUTCFullYear();
+  if (y < 1950 || y > 2049) throw new Asn1Error("asn1/bad-utctime", "UTCTime year " + y + " outside 1950..2049; use GeneralizedTime");
+  var yy = y % 100;
   return _fmtTwo(yy) +
     _fmtTwo(date.getUTCMonth() + 1) + _fmtTwo(date.getUTCDate()) +
     _fmtTwo(date.getUTCHours()) + _fmtTwo(date.getUTCMinutes()) + _fmtTwo(date.getUTCSeconds()) + "Z";
@@ -499,6 +632,7 @@ function _utcTimeString(date) {
  * @signature  pki.asn1.build.sequence([ ...tlvBuffers ]) -> Buffer
  * @since      0.1.0
  * @status     stable
+ * @spec       X.690, ISO/IEC 8825-1
  * @related    pki.asn1.encode
  *
  * Canonical-DER value builders. Each returns the full TLV Buffer for one
@@ -513,18 +647,36 @@ function _utcTimeString(date) {
  */
 var build = {
   boolean:  function (v) { return _universal(TAGS.BOOLEAN, false, Buffer.from([v ? 0xff : 0x00])); },
-  integer:  function (v) { return _universal(TAGS.INTEGER, false, Buffer.isBuffer(v) ? v : intToDer(v)); },
-  enumerated: function (v) { return _universal(TAGS.ENUMERATED, false, Buffer.isBuffer(v) ? v : intToDer(v)); },
+  integer:  function (v) { return _universal(TAGS.INTEGER, false, _intContent(v, "build.integer")); },
+  enumerated: function (v) { return _universal(TAGS.ENUMERATED, false, _intContent(v, "build.enumerated")); },
   nullValue: function () { return _universal(TAGS.NULL, false, Buffer.alloc(0)); },
   oid:      function (dotted) { return _universal(TAGS.OBJECT_IDENTIFIER, false, encodeOidContent(dotted)); },
   octetString: function (buf) { return _universal(TAGS.OCTET_STRING, false, _asBuffer(buf, "build.octetString")); },
   bitString: function (buf, unusedBits) {
     var u = unusedBits || 0;
     if (u < 0 || u > 7) throw new Asn1Error("asn1/bad-bit-string", "unusedBits must be 0..7");
-    return _universal(TAGS.BIT_STRING, false, Buffer.concat([Buffer.from([u]), _asBuffer(buf, "build.bitString")]));
+    var body = _asBuffer(buf, "build.bitString");
+    // X.690 8.6.2.3: an empty BIT STRING has no content octets, so its
+    // unused-bit count must be zero — there are no bits to leave unused.
+    if (u > 0 && body.length === 0) throw new Asn1Error("asn1/bad-bit-string", "empty BIT STRING must declare zero unused bits");
+    // Stay canonical: refuse a tail whose declared unused low bits are set.
+    if (u > 0 && body.length > 0) {
+      var mask = (1 << u) - 1;
+      if ((body[body.length - 1] & mask) !== 0) throw new Asn1Error("asn1/bad-bit-string", "unused bits must be zero");
+    }
+    return _universal(TAGS.BIT_STRING, false, Buffer.concat([Buffer.from([u]), body]));
   },
   utf8:     function (s) { return _universal(TAGS.UTF8_STRING, false, Buffer.from(String(s), "utf8")); },
-  ia5:      function (s) { return _universal(TAGS.IA5_STRING, false, Buffer.from(String(s), "latin1")); },
+  ia5:      function (s) {
+    // Validate the INPUT code points, not the latin1 output bytes: latin1
+    // truncates a code point > 0xFF to its low byte (U+0141 -> 0x41), which
+    // would silently pass a non-IA5 character through as a different one.
+    s = String(s);
+    for (var i = 0; i < s.length; i++) {
+      if (s.charCodeAt(i) > 0x7F) throw new Asn1Error("asn1/bad-ia5-string", "IA5String requires 7-bit ASCII");
+    }
+    return _universal(TAGS.IA5_STRING, false, Buffer.from(s, "latin1"));
+  },
   printable: function (s) {
     s = String(s);
     if (!PRINTABLE_RE.test(s)) throw new Asn1Error("asn1/bad-printable-string", "value has characters outside the PrintableString set");
@@ -533,7 +685,12 @@ var build = {
   utcTime:  function (date) { return _universal(TAGS.UTC_TIME, false, Buffer.from(_utcTimeString(date), "latin1")); },
   generalizedTime: function (date) { return _universal(TAGS.GENERALIZED_TIME, false, Buffer.from(_generalizedTimeString(date), "latin1")); },
   sequence: function (children) { return _universal(TAGS.SEQUENCE, true, Buffer.concat(_asBufferArray(children, "build.sequence"))); },
-  set:      function (children) { return _universal(TAGS.SET, true, Buffer.concat(_asBufferArray(children, "build.set"))); },
+  set:      function (children) {
+    // DER (X.690 11.6) requires SET component encodings in ascending order.
+    var arr = _asBufferArray(children, "build.set").slice();
+    arr.sort(Buffer.compare);
+    return _universal(TAGS.SET, true, Buffer.concat(arr));
+  },
   setOf:    function (children) {
     var arr = _asBufferArray(children, "build.setOf").slice();
     arr.sort(Buffer.compare);
@@ -546,6 +703,26 @@ var build = {
   raw:      function (buf) { return _asBuffer(buf, "build.raw"); },
 };
 
+// A raw INTEGER/ENUMERATED content Buffer must satisfy the same DER shape
+// read.integer enforces: non-empty and minimally encoded (no redundant sign
+// octet). A BigInt/number goes through intToDer, which is minimal by build.
+function _intContent(v, who) {
+  if (Buffer.isBuffer(v)) {
+    if (v.length === 0) throw new Asn1Error("asn1/bad-integer", who + ": INTEGER content is empty");
+    if (v.length > 1) {
+      if (v[0] === 0x00 && (v[1] & 0x80) === 0) throw new Asn1Error("asn1/non-minimal-integer", who + ": non-minimal positive INTEGER");
+      if (v[0] === 0xff && (v[1] & 0x80) !== 0) throw new Asn1Error("asn1/non-minimal-integer", who + ": non-minimal negative INTEGER");
+    }
+  }
+  var content = Buffer.isBuffer(v) ? v : intToDer(v);
+  // Symmetric with read.integer's per-value ceiling (magnitude + DER sign
+  // octet), so a builder can't emit an INTEGER the decoder would refuse.
+  if (content.length > constants.LIMITS.DER_MAX_INTEGER_BYTES + 1) {
+    throw new Asn1Error("asn1/integer-too-large", who + ": INTEGER content " + content.length + " bytes exceeds cap " + (constants.LIMITS.DER_MAX_INTEGER_BYTES + 1));
+  }
+  return content;
+}
+
 function _asBufferArray(arr, who) {
   if (!Array.isArray(arr)) throw new Asn1Error("asn1/bad-children", who + ": expected an array of TLV buffers");
   return arr.map(function (b) { return _asBuffer(b, who); });

package/lib/constants.js

@@ -52,6 +52,7 @@ var DAYS_PER_WEEK = 7;
  * @signature  C.TIME.days(n) -> milliseconds
  * @since      0.1.0
  * @status     stable
+ * @spec       internal (design: functional time-scale helpers)
  *
  * Duration helpers. Each returns an integer count of milliseconds so the
  * value drops straight into `setTimeout`, a validity window, or an OCSP
@@ -78,6 +79,7 @@ var BYTES_PER_KIB = 1024;
  * @signature  C.BYTES.mib(n) -> bytes
  * @since      0.1.0
  * @status     stable
+ * @spec       IEC 80000-13
  *
  * Binary-magnitude size helpers. Each returns an integer byte count for
  * codec limits (max DER input, max PEM block) so a size bound reads as
@@ -99,13 +101,29 @@ var BYTES = {
 // unbounded length prefix or a pathologically-nested SEQUENCE is a
 // classic decoder-DoS, so the bound is a fail-closed default rather
 // than a tunable an operator must remember to set.
+//
+// DER_MAX_INTEGER_BYTES and OID_MAX_SUBIDENTIFIER_BYTES are per-value
+// ceilings the whole-document cap can't provide: a single INTEGER or OID
+// sub-identifier under the 16 MiB limit can still carry hundreds of KiB,
+// so a value reader that scales super-linearly in its content length is a
+// decoder-DoS the document cap does not stop. 16 KiB covers any real key
+// material (an RSA-131072 modulus), and 32 bytes covers any real OID arc:
+// the largest standard sub-identifier is a 128-bit UUID-based arc (X.667,
+// e.g. 2.25.<uuid>), which is 19 base-128 bytes — so the cap must exceed
+// that, not sit at 16. Anything larger than 32 bytes is refused as hostile.
 var LIMITS = {
   DER_MAX_BYTES: BYTES.mib(16),
   DER_MAX_DEPTH: 64,
   PEM_MAX_BYTES: BYTES.mib(16),
+  DER_MAX_INTEGER_BYTES: BYTES.kib(16),
+  OID_MAX_SUBIDENTIFIER_BYTES: 32,
 };
 
-var VERSION = "0.1.0";
+// Single-sourced from the package manifest so the reported version can
+// never drift from the published package (package.json is always present
+// in the installed tarball). A hand-maintained literal here silently
+// shipped 0.1.0 on a 0.1.1 release.
+var VERSION = require("../package.json").version;
 
 module.exports = {
   TIME:    TIME,

package/lib/framework-error.js

@@ -32,6 +32,7 @@
  * @signature  new PkiError(message, code)
  * @since      0.1.0
  * @status     stable
+ * @spec       internal (design: error taxonomy base class)
  *
  * Base class every toolkit error extends. Provides the unified
  * `instanceof` check plus the `{ name, code, isPkiError }` shape.
@@ -57,6 +58,7 @@ class PkiError extends Error {
  * @signature  pki.errors.defineClass(name, opts?) -> constructor
  * @since      0.1.0
  * @status     stable
+ * @spec       internal (design: error-class factory)
  *
  * Factory that produces a `PkiError` subclass with the standard shape —
  * eliminating the per-domain boilerplate. The returned constructor takes

package/lib/oid.js

@@ -17,14 +17,20 @@
  *   codebase — is what lets a new algorithm be a data entry instead of a
  *   code change.
  *
- *   The seed set covers the RFC 5280 attribute types and extensions, the
+ *   The seed set is declared by FAMILY: an OID belongs to a class with a
+ *   shared base arc (the "starting variable" — `2.5.4` for the RFC 5280
+ *   attribute types, `2.5.29` for the extensions, `2.16.840.1.101.3.4` for
+ *   the NIST algorithms), and each member names only its trailing arc. The
+ *   full OID is derived from base + leaf at load, so the arc hierarchy that
+ *   IS the OID namespace is modelled directly instead of re-spelled per
+ *   entry. It covers the RFC 5280 attribute types and extensions, the
  *   classical signature / public-key / digest algorithms, and the
  *   NIST-assigned post-quantum arcs (ML-DSA, ML-KEM, SLH-DSA). Operators
- *   extend it with `register`.
+ *   extend it with `register` (one OID) or `registerFamily` (a whole arc).
  *
  * @card
- *   Two-way OID ↔ name registry with arc conversion, seeded with the
- *   RFC 5280 and NIST post-quantum object identifiers.
+ *   Two-way OID ↔ name registry with arc conversion, seeded by family from
+ *   the RFC 5280 and NIST post-quantum object identifiers.
  */
 
 var asn1 = require("./asn1-der");
@@ -32,77 +38,64 @@ var frameworkError = require("./framework-error");
 
 var OidError = frameworkError.OidError;
 
-// SEED — [dotted, canonicalName]. Kept as a flat table so it reads as
-// data and diffs cleanly when an arc is added.
-var SEED = [
-  // --- RFC 5280 attribute types (2.5.4.*) ---
-  ["2.5.4.3",  "commonName"],
-  ["2.5.4.4",  "surname"],
-  ["2.5.4.5",  "serialNumber"],
-  ["2.5.4.6",  "countryName"],
-  ["2.5.4.7",  "localityName"],
-  ["2.5.4.8",  "stateOrProvinceName"],
-  ["2.5.4.9",  "streetAddress"],
-  ["2.5.4.10", "organizationName"],
-  ["2.5.4.11", "organizationalUnitName"],
-  ["2.5.4.12", "title"],
-  ["2.5.4.42", "givenName"],
-  ["0.9.2342.19200300.100.1.25", "domainComponent"],
-  ["1.2.840.113549.1.9.1",       "emailAddress"],
-
-  // --- Public-key + signature algorithms ---
-  ["1.2.840.113549.1.1.1",  "rsaEncryption"],
-  ["1.2.840.113549.1.1.10", "rsassaPss"],
-  ["1.2.840.113549.1.1.11", "sha256WithRSAEncryption"],
-  ["1.2.840.113549.1.1.12", "sha384WithRSAEncryption"],
-  ["1.2.840.113549.1.1.13", "sha512WithRSAEncryption"],
-  ["1.2.840.10045.2.1",     "ecPublicKey"],
-  ["1.2.840.10045.4.3.2",   "ecdsaWithSHA256"],
-  ["1.2.840.10045.4.3.3",   "ecdsaWithSHA384"],
-  ["1.2.840.10045.4.3.4",   "ecdsaWithSHA512"],
-  ["1.2.840.10045.3.1.7",   "prime256v1"],
-  ["1.3.132.0.34",          "secp384r1"],
-  ["1.3.132.0.35",          "secp521r1"],
-  ["1.3.101.110",           "X25519"],
-  ["1.3.101.111",           "X448"],
-  ["1.3.101.112",           "Ed25519"],
-  ["1.3.101.113",           "Ed448"],
-
-  // --- Digests ---
-  ["2.16.840.1.101.3.4.2.1",  "sha256"],
-  ["2.16.840.1.101.3.4.2.2",  "sha384"],
-  ["2.16.840.1.101.3.4.2.3",  "sha512"],
-  ["2.16.840.1.101.3.4.2.8",  "sha3-256"],
-  ["2.16.840.1.101.3.4.2.10", "sha3-512"],
-  ["2.16.840.1.101.3.4.2.12", "shake256"],
-
-  // --- RFC 5280 certificate extensions (2.5.29.*) ---
-  ["2.5.29.14", "subjectKeyIdentifier"],
-  ["2.5.29.15", "keyUsage"],
-  ["2.5.29.17", "subjectAltName"],
-  ["2.5.29.18", "issuerAltName"],
-  ["2.5.29.19", "basicConstraints"],
-  ["2.5.29.30", "nameConstraints"],
-  ["2.5.29.31", "cRLDistributionPoints"],
-  ["2.5.29.32", "certificatePolicies"],
-  ["2.5.29.35", "authorityKeyIdentifier"],
-  ["2.5.29.37", "extKeyUsage"],
-  ["1.3.6.1.5.5.7.1.1", "authorityInfoAccess"],
-
-  // --- NIST post-quantum algorithms ---
-  // FIPS 204 ML-DSA (signature-algorithm arc 2.16.840.1.101.3.4.3.*).
-  ["2.16.840.1.101.3.4.3.17", "id-ml-dsa-44"],
-  ["2.16.840.1.101.3.4.3.18", "id-ml-dsa-65"],
-  ["2.16.840.1.101.3.4.3.19", "id-ml-dsa-87"],
-  // FIPS 203 ML-KEM (KEM arc 2.16.840.1.101.3.4.4.*).
-  ["2.16.840.1.101.3.4.4.1",  "id-ml-kem-512"],
-  ["2.16.840.1.101.3.4.4.2",  "id-ml-kem-768"],
-  ["2.16.840.1.101.3.4.4.3",  "id-ml-kem-1024"],
-  // FIPS 205 SLH-DSA (a representative slice of the SHAKE-256 family).
-  ["2.16.840.1.101.3.4.3.20", "id-slh-dsa-sha2-128s"],
-  ["2.16.840.1.101.3.4.3.24", "id-slh-dsa-shake-128s"],
-  ["2.16.840.1.101.3.4.3.27", "id-slh-dsa-shake-256s"],
-];
+// FAMILIES — OIDs grouped by their shared base arc (the "similar starting
+// variable" that defines a class). A member is `name: leaf`, where leaf is a
+// trailing arc (number) or a short arc array for a multi-level leaf; the full
+// arc is derived at load via base.concat(leaf). Declaring by family means no
+// dotted-decimal OID literal appears in this source at all, and adding a
+// member is one `name: leaf` line under its class — no base to re-type.
+var FAMILIES = {
+  // RFC 5280 attribute types.
+  attributeType: { base: [2, 5, 4], of: {
+    commonName: 3, surname: 4, serialNumber: 5, countryName: 6,
+    localityName: 7, stateOrProvinceName: 8, streetAddress: 9,
+    organizationName: 10, organizationalUnitName: 11, title: 12, givenName: 42 } },
+
+  // RFC 5280 certificate extensions.
+  certExtension: { base: [2, 5, 29], of: {
+    subjectKeyIdentifier: 14, keyUsage: 15, subjectAltName: 17, issuerAltName: 18,
+    basicConstraints: 19, nameConstraints: 30, cRLDistributionPoints: 31,
+    certificatePolicies: 32, authorityKeyIdentifier: 35, extKeyUsage: 37 } },
+
+  // PKIX private extensions (authorityInfoAccess et al).
+  pkixAccess: { base: [1, 3, 6, 1, 5, 5, 7, 1], of: { authorityInfoAccess: 1 } },
+
+  // PKCS#1 RSA public-key + RSASSA signature algorithms.
+  rsa: { base: [1, 2, 840, 113549, 1, 1], of: {
+    rsaEncryption: 1, rsassaPss: 10, sha256WithRSAEncryption: 11,
+    sha384WithRSAEncryption: 12, sha512WithRSAEncryption: 13 } },
+
+  // PKCS#9 attribute types.
+  pkcs9: { base: [1, 2, 840, 113549, 1, 9], of: { emailAddress: 1 } },
+
+  // ANSI X9.62 EC public key, named curve, and ECDSA signatures.
+  ansiX962: { base: [1, 2, 840, 10045], of: {
+    ecPublicKey: [2, 1], prime256v1: [3, 1, 7],
+    ecdsaWithSHA256: [4, 3, 2], ecdsaWithSHA384: [4, 3, 3], ecdsaWithSHA512: [4, 3, 4] } },
+
+  // SECG named curves.
+  secg: { base: [1, 3, 132, 0], of: { secp384r1: 34, secp521r1: 35 } },
+
+  // Edwards / Montgomery curves (RFC 8410).
+  edwards: { base: [1, 3, 101], of: { X25519: 110, X448: 111, Ed25519: 112, Ed448: 113 } },
+
+  // NIST hash functions (SHA-2, SHA-3, SHAKE).
+  nistHash: { base: [2, 16, 840, 1, 101, 3, 4, 2], of: {
+    sha256: 1, sha384: 2, sha512: 3, "sha3-256": 8, "sha3-512": 10, shake256: 12 } },
+
+  // NIST signature algorithms — FIPS 204 ML-DSA + FIPS 205 SLH-DSA share the
+  // signature arc 2.16.840.1.101.3.4.3.
+  nistSig: { base: [2, 16, 840, 1, 101, 3, 4, 3], of: {
+    "id-ml-dsa-44": 17, "id-ml-dsa-65": 18, "id-ml-dsa-87": 19,
+    "id-slh-dsa-sha2-128s": 20, "id-slh-dsa-shake-128s": 24, "id-slh-dsa-shake-256s": 27 } },
+
+  // NIST KEM — FIPS 203 ML-KEM (arc 2.16.840.1.101.3.4.4).
+  nistKem: { base: [2, 16, 840, 1, 101, 3, 4, 4], of: {
+    "id-ml-kem-512": 1, "id-ml-kem-768": 2, "id-ml-kem-1024": 3 } },
+
+  // Misc datatypes (RFC 4519 domainComponent).
+  datatype: { base: [0, 9, 2342, 19200300, 100, 1], of: { domainComponent: 25 } },
+};
 
 var _byOid = new Map();
 var _byName = new Map();
@@ -113,7 +106,20 @@ function _index(dotted, name) {
   if (!_byName.has(name)) _byName.set(name, dotted);
 }
 
-for (var _i = 0; _i < SEED.length; _i++) _index(SEED[_i][0], SEED[_i][1]);
+// An arc is a non-negative integer. Large arcs (a 128-bit UUID-based arc
+// exceeds 2^53) must be BigInt to survive without precision loss, so both
+// a non-negative safe-integer Number and a non-negative BigInt are valid.
+function _isArc(a) {
+  if (typeof a === "bigint") return a >= 0n;
+  return typeof a === "number" && Number.isSafeInteger(a) && a >= 0;
+}
+
+// Seed the registry family by family — the built-in set is registered through
+// the exact same primitive an operator uses (registerFamily), so there is one
+// path from a declared family to indexed OIDs and no dotted literals anywhere.
+Object.keys(FAMILIES).forEach(function (fam) {
+  registerFamily(FAMILIES[fam].base, FAMILIES[fam].of);
+});
 
 function _assertDotted(dotted, who) {
   if (typeof dotted !== "string" || !/^\d+(\.\d+)+$/.test(dotted)) {
@@ -126,6 +132,7 @@ function _assertDotted(dotted, who) {
  * @signature  pki.oid.name(dotted) -> string | undefined
  * @since      0.1.0
  * @status     stable
+ * @spec       X.660, RFC 5280
  * @related    pki.oid.byName, pki.oid.register
  *
  * Resolve a dotted OID to its registered name. Returns `undefined` for an
@@ -155,7 +162,8 @@ function has(dotted) {
  * @signature  pki.oid.register(dotted, name) -> void
  * @since      0.1.0
  * @status     stable
- * @related    pki.oid.name
+ * @spec       X.660, RFC 5280
+ * @related    pki.oid.registerFamily, pki.oid.name
  *
  * Add (or override) an OID → name mapping so an operator's private or
  * newly-standardized arc resolves through the same registry as the seed
@@ -171,6 +179,51 @@ function register(dotted, n) {
   _index(dotted, n);
 }
 
+/**
+ * @primitive  pki.oid.registerFamily
+ * @signature  pki.oid.registerFamily(base, members) -> void
+ * @since      0.1.2
+ * @status     stable
+ * @spec       X.660
+ * @related    pki.oid.register, pki.oid.name
+ *
+ * Register a whole OID family in one call. `base` is the shared arc prefix
+ * (the starting variable a class of OIDs has in common) and `members` maps
+ * each name to its trailing arc — a number, or a short arc array for a
+ * multi-level leaf. Each full OID is derived as `base` followed by the leaf,
+ * so a family is declared as its hierarchy rather than as re-spelled full
+ * paths. This is the primitive the built-in seed set itself is built from.
+ *
+ * @opts
+ *   base:      number[],           // the shared arc prefix, e.g. [1,3,6,1,4,1,99999]
+ *   members:   object,             // name -> number | number[] trailing arc
+ *
+ * @example
+ *   pki.oid.registerFamily([1, 3, 6, 1, 4, 1, 99999], {
+ *     widgetPolicy: 1,
+ *     gadgetPolicy: [2, 4],
+ *   });
+ *   pki.oid.name("1.3.6.1.4.1.99999.2.4"); // -> "gadgetPolicy"
+ */
+function registerFamily(base, members) {
+  if (!Array.isArray(base) || base.length < 1 || !base.every(_isArc)) {
+    throw new OidError("oid/bad-input", "registerFamily: base must be a non-empty array of non-negative integer arcs");
+  }
+  if (!members || typeof members !== "object") {
+    throw new OidError("oid/bad-input", "registerFamily: members must be an object of name -> leaf arc(s)");
+  }
+  Object.keys(members).forEach(function (nm) {
+    if (typeof nm !== "string" || nm.length === 0) {
+      throw new OidError("oid/bad-input", "registerFamily: member names must be non-empty strings");
+    }
+    var arcs = base.concat(members[nm]);
+    if (!arcs.every(_isArc)) {
+      throw new OidError("oid/bad-arc", "registerFamily: member " + JSON.stringify(nm) + " has a non-arc leaf");
+    }
+    _index(arcs.join("."), nm);
+  });
+}
+
 function all() {
   var out = {};
   _byOid.forEach(function (v, k) { out[k] = v; });
@@ -191,8 +244,11 @@ function toArcs(dotted) {
 function fromArcs(arcs) {
   if (!Array.isArray(arcs) || arcs.length < 2) throw new OidError("oid/bad-input", "fromArcs: expected an array of >= 2 arcs");
   return arcs.map(function (a) {
-    if (typeof a === "bigint") return a.toString();
-    if (typeof a === "number" && Number.isInteger(a) && a >= 0) return String(a);
+    if (typeof a === "bigint") {
+      if (a < 0n) throw new OidError("oid/bad-arc", "fromArcs: arc " + String(a) + " is not a non-negative integer");
+      return a.toString();
+    }
+    if (typeof a === "number" && Number.isSafeInteger(a) && a >= 0) return String(a);
     throw new OidError("oid/bad-arc", "fromArcs: arc " + String(a) + " is not a non-negative integer");
   }).join(".");
 }
@@ -207,13 +263,14 @@ function fromDER(input) {
 }
 
 module.exports = {
-  name:     name,
-  byName:   byName,
-  has:      has,
-  register: register,
-  all:      all,
-  toArcs:   toArcs,
-  fromArcs: fromArcs,
-  toDER:    toDER,
-  fromDER:  fromDER,
+  name:           name,
+  byName:         byName,
+  has:            has,
+  register:       register,
+  registerFamily: registerFamily,
+  all:            all,
+  toArcs:         toArcs,
+  fromArcs:       fromArcs,
+  toDER:          toDER,
+  fromDER:        fromDER,
 };

package/lib/webcrypto.js

@@ -111,6 +111,7 @@ var SLH_DSA_NODE = {};
  * @signature  new pki.webcrypto.CryptoKey(type, extractable, algorithm, usages, handle)
  * @since      0.1.0
  * @status     stable
+ * @spec       W3C WebCrypto §cryptokey
  *
  * Opaque handle to key material, matching the W3C `CryptoKey` shape:
  * `{ type, extractable, algorithm, usages }`. The underlying
@@ -266,7 +267,12 @@ SubtleCrypto.prototype.verify = async function verify(algorithm, key, signature,
   if (name === "HMAC") {
     var hm = nodeCrypto.createHmac(_hashNode(key.algorithm.hash, "verify"), key._handle);
     hm.update(buf);
-    return nodeCrypto.timingSafeEqual(hm.digest(), sig);
+    // Verify must RESOLVE false for any invalid signature, including one of
+    // the wrong length. timingSafeEqual throws RangeError on a length
+    // mismatch, so gate on length first; the length is already public, so
+    // this leaks nothing a constant-time compare would protect.
+    var mac = hm.digest();
+    return mac.length === sig.length && nodeCrypto.timingSafeEqual(mac, sig);
   }
   throw new WebCryptoError("webcrypto/not-supported", "verify: unsupported algorithm " + JSON.stringify(name));
 };
@@ -295,6 +301,7 @@ SubtleCrypto.prototype.encrypt = async function encrypt(algorithm, key, data) {
     return _toArrayBuffer(Buffer.concat([c2.update(buf), c2.final()]));
   }
   if (name === "AES-CTR") {
+    _requireCtrLength128(alg);
     var c3 = nodeCrypto.createCipheriv("aes-" + key.algorithm.length + "-ctr", _secretBytes(key), _toBuf(alg.counter, "AES-CTR counter"));
     return _toArrayBuffer(Buffer.concat([c3.update(buf), c3.final()]));
   }
@@ -328,6 +335,7 @@ SubtleCrypto.prototype.decrypt = async function decrypt(algorithm, key, data) {
     return _toArrayBuffer(Buffer.concat([d2.update(buf), d2.final()]));
   }
   if (name === "AES-CTR") {
+    _requireCtrLength128(alg);
     var d3 = nodeCrypto.createDecipheriv("aes-" + key.algorithm.length + "-ctr", _secretBytes(key), _toBuf(alg.counter, "AES-CTR counter"));
     return _toArrayBuffer(Buffer.concat([d3.update(buf), d3.final()]));
   }
@@ -336,9 +344,21 @@ SubtleCrypto.prototype.decrypt = async function decrypt(algorithm, key, data) {
 
 function _secretBytes(key) { return key._handle.export(); }
 
-SubtleCrypto.prototype.deriveBits = async function deriveBits(algorithm, key, length) {
-  var alg = _normalizeAlg(algorithm, "deriveBits");
-  _requireUsage(key, "deriveBits");
+// AES-CTR: node always treats the full 128-bit block as the counter and
+// never reads the spec's `length` (counter-width) parameter. A length < 128
+// would silently diverge from the W3C definition, so fail closed — accept
+// only the one value node can honor.
+function _requireCtrLength128(alg) {
+  if (alg.length !== 128) {
+    throw new WebCryptoError("webcrypto/not-supported", "AES-CTR length must be 128");
+  }
+}
+
+// Raw key-agreement / KDF derivation with NO usage check — the usage a
+// caller must hold differs by entry point (deriveBits requires "deriveBits",
+// deriveKey requires "deriveKey"), so each public method checks its own
+// usage and then routes the actual derivation through here.
+function _deriveBitsRaw(alg, key, length) {
   var name = alg.name;
   if (name === "ECDH" || name === "X25519" || name === "X448") {
     var secret = nodeCrypto.diffieHellman({ privateKey: key._handle, publicKey: alg.public._handle });
@@ -353,12 +373,24 @@ SubtleCrypto.prototype.deriveBits = async function deriveBits(algorithm, key, le
     return _toArrayBuffer(out);
   }
   throw new WebCryptoError("webcrypto/not-supported", "deriveBits: unsupported algorithm " + JSON.stringify(name));
+}
+
+SubtleCrypto.prototype.deriveBits = async function deriveBits(algorithm, key, length) {
+  var alg = _normalizeAlg(algorithm, "deriveBits");
+  _requireUsage(key, "deriveBits");
+  return _deriveBitsRaw(alg, key, length);
 };
 
 SubtleCrypto.prototype.deriveKey = async function deriveKey(algorithm, baseKey, derivedKeyType, extractable, keyUsages) {
+  // deriveKey requires the "deriveKey" usage — NOT "deriveBits". Delegating
+  // to this.deriveBits would false-reject a key created with ["deriveKey"]
+  // and fail-open on a ["deriveBits"]-only key, so check the correct usage
+  // here and route the raw derivation past deriveBits' own usage gate.
+  _requireUsage(baseKey, "deriveKey");
+  var alg = _normalizeAlg(algorithm, "deriveKey");
   var dk = _normalizeAlg(derivedKeyType, "deriveKey");
   var bits = dk.length || (dk.name.indexOf("AES") === 0 ? dk.length : 256);
-  var raw = await this.deriveBits(algorithm, baseKey, bits);
+  var raw = _deriveBitsRaw(alg, baseKey, bits);
   return this.importKey("raw", raw, dk, extractable, keyUsages);
 };
 
@@ -378,9 +410,14 @@ SubtleCrypto.prototype.wrapKey = async function wrapKey(format, key, wrappingKey
 
 SubtleCrypto.prototype.unwrapKey = async function unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgorithm, unwrappedKeyAlgorithm, extractable, keyUsages) {
   var alg = _normalizeAlg(unwrapAlgorithm, "unwrapKey");
+  // Enforce the "unwrapKey" usage before EITHER path. The delegated
+  // (RSA-OAEP / AES-GCM) branch clones the key with "decrypt" and hands off
+  // to this.decrypt, so without this top-level check the else branch would
+  // never verify the caller was actually permitted to unwrap (mirrors
+  // wrapKey, which checks before both of its paths).
+  _requireUsage(unwrappingKey, "unwrapKey");
   var bytes;
   if (alg.name === "AES-KW") {
-    _requireUsage(unwrappingKey, "unwrapKey");
     var d = nodeCrypto.createDecipheriv("aes" + unwrappingKey.algorithm.length + "-wrap", _secretBytes(unwrappingKey), Buffer.from("A6A6A6A6A6A6A6A6", "hex"));
     bytes = Buffer.concat([d.update(_toBuf(wrappedKey, "unwrapKey")), d.final()]);
   } else {
@@ -470,6 +507,7 @@ function _curveFromKey(ko) {
  * @signature  await pki.webcrypto.subtle.exportKey(format, key)
  * @since      0.1.0
  * @status     stable
+ * @spec       W3C WebCrypto §subtlecrypto, FIPS 186-5, FIPS 203, FIPS 204, FIPS 205, RFC 8017
  * @related    pki.webcrypto.CryptoKey
  *
  * Export a `CryptoKey` to `spki` (public), `pkcs8` (private), `jwk`
@@ -507,6 +545,7 @@ function _rawPublic(key) {
  * @signature  pki.webcrypto.getRandomValues(typedArray) / pki.webcrypto.subtle
  * @since      0.1.0
  * @status     stable
+ * @spec       W3C WebCrypto
  * @related    pki.webcrypto.subtle
  *
  * A ready `Crypto` instance (the shape of `globalThis.crypto`) exposing

package/lib/x509.js

@@ -64,6 +64,7 @@ var PEM_RE = /-----BEGIN ([A-Z0-9 ]+)-----([\s\S]*?)-----END \1-----/;
  * @signature  pki.x509.pemDecode(text, label?) -> Buffer
  * @since      0.1.0
  * @status     stable
+ * @spec       RFC 7468, RFC 5280
  * @related    pki.x509.pemEncode
  *
  * Extract the DER bytes from a PEM block. With `label` given (e.g.
@@ -91,6 +92,7 @@ function pemDecode(text, label) {
  * @signature  pki.x509.pemEncode(der, label) -> string
  * @since      0.1.0
  * @status     stable
+ * @spec       RFC 7468, RFC 5280
  * @related    pki.x509.pemDecode
  *
  * Wrap DER bytes in a PEM envelope with 64-column base64 lines.
@@ -121,10 +123,25 @@ function _algId(node) {
 
 function _attrValueToString(node) {
   try { return asn1.read.string(node); }
-  catch (_e) {
-    // Not a recognized string type (e.g. an ANY-typed value) — surface
-    // the raw bytes as hex so the DN is still representable.
-    return "#" + (node.content ? node.content.toString("hex") : node.bytes.toString("hex"));
+  catch (e) {
+    // A malformed KNOWN string type (invalid UTF-8, a non-IA5 byte, a
+    // PrintableString character outside its set, ...) is a malformed
+    // certificate and must fail closed — do NOT hex-encode it away, or the
+    // decoder's strict string validation is silently bypassed on the DN path.
+    // Those surface as asn1/bad-* content errors; raise a CertificateError so
+    // parse fails closed on the documented x509/* contract.
+    //
+    // A value that simply is not a decodable primitive string is NOT malformed
+    // and must stay representable: an ANY-typed non-string tag
+    // (asn1/expected-string) or a constructed universal type such as a SEQUENCE
+    // (asn1/expected-primitive). Per RFC 4514 §2.4 it is rendered as "#" plus
+    // the hex of its FULL DER encoding (tag + length + content — node.bytes),
+    // so a constructed value round-trips intact rather than being dropped or
+    // rejecting the whole certificate.
+    if (!e || (e.code !== "asn1/expected-string" && e.code !== "asn1/expected-primitive")) {
+      throw new CertificateError("x509/bad-atv", "malformed string in attribute value: " + ((e && e.message) || String(e)));
+    }
+    return "#" + node.bytes.toString("hex");
   }
 }
 
@@ -171,13 +188,30 @@ function _parseValidityTime(node) {
 }
 
 function _parseExtensions(seqNode) {
+  // RFC 5280 §4.1.2.9 — Extensions ::= SEQUENCE SIZE (1..MAX) OF Extension.
+  // The wrapped value must be a SEQUENCE (not a primitive, which would read
+  // seqNode.children as null and throw a raw TypeError) and must carry at
+  // least one extension.
+  if (seqNode.tagClass !== "universal" || seqNode.tagNumber !== TAGS.SEQUENCE || !seqNode.children) {
+    throw new CertificateError("x509/bad-extensions", "extensions [3] must wrap a SEQUENCE");
+  }
+  if (seqNode.children.length === 0) {
+    throw new CertificateError("x509/bad-extensions", "extensions SEQUENCE must contain at least one extension");
+  }
   var out = [];
+  var seen = new Set();
   for (var i = 0; i < seqNode.children.length; i++) {
     var ext = seqNode.children[i];
     if (!ext.children || ext.children.length < 2) {
       throw new CertificateError("x509/bad-extension", "Extension must be a SEQUENCE");
     }
     var extnID = asn1.read.oid(ext.children[0]);
+    // RFC 5280 §4.2 — a certificate MUST NOT include more than one
+    // instance of a particular extension.
+    if (seen.has(extnID)) {
+      throw new CertificateError("x509/duplicate-extension", "certificate repeats extension " + extnID);
+    }
+    seen.add(extnID);
     var critical = false;
     var valueNode;
     if (ext.children.length === 3) {
@@ -203,6 +237,8 @@ function _parseExtensions(seqNode) {
  * @signature  pki.x509.parse(input) -> certificate
  * @since      0.1.0
  * @status     stable
+ * @spec       RFC 5280, X.509
+ * @defends    malformed-certificate-parse (CWE-20)
  * @related    pki.asn1.decode, pki.oid.name
  *
  * Parse a DER `Buffer` or a PEM string/Buffer into a structured
@@ -245,17 +281,37 @@ function parse(input) {
   var tbs = root.children[0];
   var outerSigAlg = root.children[1];
   var sigValueNode = root.children[2];
-  if (!tbs.children || tbs.children.length < 6) {
-    throw new CertificateError("x509/bad-tbs", "tbsCertificate is too short");
+  if (!tbs.children || !tbs.children.length) {
+    throw new CertificateError("x509/bad-tbs", "tbsCertificate is empty");
   }
 
   var idx = 0;
-  var version = 1;
+  var version;
   var first = tbs.children[0];
   if (first.tagClass === "context" && first.tagNumber === 0) {
     if (!first.children || !first.children.length) throw new CertificateError("x509/bad-version", "version [0] must wrap an INTEGER");
-    version = Number(asn1.read.integer(first.children[0])) + 1;
+    // RFC 5280 §4.1.2.1 — version is INTEGER { v1(0), v2(1), v3(2) }; read
+    // it as a BigInt so an out-of-range value can't be coerced to a float,
+    // and reject an explicitly-encoded v1 (DER forbids encoding the DEFAULT).
+    var versionValue = asn1.read.integer(first.children[0]);
+    if (versionValue === 0n) {
+      throw new CertificateError("x509/bad-version", "DER forbids explicitly encoding the default version v1");
+    } else if (versionValue === 1n) {
+      version = 2;
+    } else if (versionValue === 2n) {
+      version = 3;
+    } else {
+      throw new CertificateError("x509/bad-version", "unsupported certificate version " + versionValue.toString());
+    }
     idx = 1;
+  } else {
+    version = 1;
+  }
+
+  // Six positional fields follow any [0] version; a shorter tbs would read
+  // `undefined` and throw a raw TypeError on the first property access.
+  if (tbs.children.length < idx + 6) {
+    throw new CertificateError("x509/bad-tbs", "tbsCertificate is too short");
   }
 
   var serialNode = tbs.children[idx++];
@@ -266,6 +322,21 @@ function parse(input) {
   var subject = _parseName(tbs.children[idx++]);
   var spkiNode = tbs.children[idx++];
 
+  // RFC 5280 §4.1.1.2 — the outer signatureAlgorithm MUST contain the same
+  // AlgorithmIdentifier (OID and parameters) as tbsCertificate.signature. A
+  // mismatch is a signature-algorithm-substitution vector, so compare the full
+  // DER of both fields rather than surfacing two disagreeing algorithms.
+  if (!outerSigAlg.bytes.equals(innerSigAlg.bytes)) {
+    throw new CertificateError("x509/bad-signature-algorithm", "signatureAlgorithm must match tbsCertificate.signature (RFC 5280 §4.1.1.2)");
+  }
+
+  // RFC 5280 §4.1.2.4 — the issuer field MUST contain a non-empty distinguished
+  // name. (An empty subject is permitted when a subjectAltName carries the
+  // identity — §4.1.2.6 — so only the issuer is required non-empty here.)
+  if (!issuer.rdns.length) {
+    throw new CertificateError("x509/bad-issuer", "issuer must be a non-empty distinguished name");
+  }
+
   if (!validityNode.children || validityNode.children.length !== 2) {
     throw new CertificateError("x509/bad-validity", "Validity must be a SEQUENCE of {notBefore, notAfter}");
   }
@@ -285,16 +356,36 @@ function parse(input) {
   };
 
   // Remaining tbs children: optional issuerUniqueID [1], subjectUniqueID
-  // [2], and extensions [3] EXPLICIT. Only extensions are surfaced.
+  // [2], and extensions [3] EXPLICIT. Only extensions are surfaced. RFC 5280
+  // §4.1 fixes these as the trailing fields, each at most once and in strictly
+  // increasing tag order; a repeated or out-of-order tag (or an unknown /
+  // non-context field) is malformed. Without the monotonic guard a second [3]
+  // silently overwrites the first, hiding its extensions and splitting
+  // duplicate extension OIDs across two wrappers past the per-sequence check.
   var extensions = [];
+  var hasExtensions = false;
+  var lastTrailingTag = 0;
   for (; idx < tbs.children.length; idx++) {
     var t = tbs.children[idx];
-    if (t.tagClass === "context" && t.tagNumber === 3) {
+    if (t.tagClass !== "context" || t.tagNumber < 1 || t.tagNumber > 3) {
+      throw new CertificateError("x509/bad-tbs", "unexpected field after subjectPublicKeyInfo; tbsCertificate allows only issuerUniqueID [1], subjectUniqueID [2], extensions [3]");
+    }
+    if (t.tagNumber <= lastTrailingTag) {
+      throw new CertificateError("x509/bad-tbs", "tbsCertificate trailing field [" + t.tagNumber + "] is repeated or out of order");
+    }
+    lastTrailingTag = t.tagNumber;
+    if (t.tagNumber === 3) {
+      hasExtensions = true;
       if (!t.children || !t.children.length) throw new CertificateError("x509/bad-extensions", "extensions [3] must wrap a SEQUENCE");
       extensions = _parseExtensions(t.children[0]);
     }
   }
 
+  // RFC 5280 §4.1.2.9 — the extensions field appears only in a v3 cert.
+  if (hasExtensions && version !== 3) {
+    throw new CertificateError("x509/bad-version", "extensions are only permitted in a v3 certificate");
+  }
+
   var sigBits = asn1.read.bitString(sigValueNode);
 
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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:3eef8bae-7aaa-4ecf-a97b-3774a378db59",
+  "serialNumber": "urn:uuid:61f60234-7f86-4857-9542-58817209d84d",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-04T12:48:34.391Z",
+    "timestamp": "2026-07-04T19:11:06.976Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.1.1",
+      "bom-ref": "@blamejs/pki@0.1.2",
       "type": "application",
       "name": "pki",
-      "version": "0.1.1",
+      "version": "0.1.2",
       "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.1",
+      "purl": "pkg:npm/%40blamejs/pki@0.1.2",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.1.1",
+      "ref": "@blamejs/pki@0.1.2",
       "dependsOn": []
     }
   ]