@blamejs/pki 0.5.8 → 0.5.9

package/CHANGELOG.md

@@ -4,7 +4,20 @@ 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.5.8 — 2026-08-18
+## v0.5.9 — 2026-08-18
+
+A certificate can now carry an internationalized email address, which this toolkit could read and never write.
+
+### Added
+
+- pki.x509.sign accepts an otherName entry in a subjectAltName, given as { typeId, value } where typeId is an OID string and value is a Buffer holding one DER element. It encodes RFC 5280 section 4.2.1.6's otherName ::= SEQUENCE { type-id OBJECT IDENTIFIER, value [0] EXPLICIT ANY }, tagged [0] IMPLICIT. The value wrapper is EXPLICIT because ANY carries no tag of its own, which is what makes the encoding unambiguous and is the shape the decoder already required. This is what an SmtpUTF8Mailbox address needs, and it is equally the carrier for any other otherName a profile defines.
+- The value is validated before it is wrapped and signed, because a signer that emits a malformed encoding under a real signature has produced something strict relying parties reject. It must be exactly one element with no trailing bytes, and its contents must satisfy the rules for its type: a BOOLEAN whose octet is not 0x00 or 0xFF is refused, as is a SET whose members sit in no canonical order, and so on recursively through a constructed value. The accepted universal types are BOOLEAN, INTEGER, ENUMERATED, BIT STRING, OCTET STRING, NULL, OBJECT IDENTIFIER, UTCTime, GeneralizedTime, NumericString, and the DirectoryString family (UTF8String, PrintableString, IA5String, TeletexString, VisibleString, BMPString, UniversalString), plus SEQUENCE and SET. A universal type outside that set, such as REAL or RELATIVE-OID, has no content validator here and is refused rather than accepted on its framing alone. A context- or application-tagged value passes on its framing, since no content rule is knowable for it, and its children are still walked. One known limitation: a GeneralizedTime carrying fractional seconds, such as 20260101000000.5Z, is refused here even though X.690 section 11.7 permits it. That relaxation is scoped to the codec and to RFC 3161 timestamping on purpose, and this validator does not widen it. A constructed wrapper does not evade the rule, since the walk recurses into its children; a profile needing a fractional time must carry it under an implicit primitive context tag, which passes on framing because no content rule is knowable for it.
+
+### Fixed
+
+- pki.smime.verify's sender binding is now exercised against certificates carrying an otherName. Two behaviours that previously had no conformance vector are pinned: a certificate whose subjectAltName carries an SmtpUTF8Mailbox does not let a legacy subject distinguished-name emailAddress speak for it, and an otherName unrelated to email, such as a Microsoft user principal name, neither erases a matching rfc822Name nor turns a definite non-match into an undecidable one.
+
+## v0.5.8 — 2026-08-17
 
 Four verdicts that answered a question nobody had asked now say what they checked, and an email domain comparison no longer folds two registrable domains into one identity.
 

package/lib/guard-all.js

@@ -59,6 +59,7 @@ var range  = require("./guard-range");
 var time   = require("./guard-time");
 var name   = require("./guard-name");
 var encoding = require("./guard-encoding");
+var der = require("./guard-der");
 var json   = require("./guard-json");
 var identifier = require("./guard-identifier");
 var header = require("./guard-header");
@@ -76,6 +77,7 @@ module.exports = {
   time:   time,
   name:   name,
   encoding: encoding,
+  der:    der,
   json:   json,
   identifier: identifier,
   header: header,

package/lib/guard-der.js

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal -- no operator-facing namespace. The documented surface is the consumers
+// whose encoding integrity composes this guard (pki.schema.c509 reconstruct sites,
+// pki.x509.sign and its sibling builders on any subjectAltName otherName value).
+//
+// guard-der: the single choke point for "these raw bytes are exactly one strictly-valid
+// DER element", for every site that splices caller-supplied ANY bytes verbatim into
+// something it then signs or reconstructs.
+//
+// The bug class is framing mistaken for validation. asn1.decode checks TLV framing and
+// rejects trailing data, and stopping there feels sufficient. It is not: framing accepts
+// a BOOLEAN whose content octet is 0x01 where DER requires 0xFF, a NumericString holding
+// "@", and a SET whose members sit in no canonical order. None of those is DER. Spliced
+// into a certificate and signed, the issuer emits a structure that strict relying parties
+// reject, under a real signature, while the producing verb reported success (CWE-20).
+//
+// The rule is validate-or-refuse. A universal primitive runs through its strict content
+// reader, and a universal type with no reader here is REFUSED, so the table is exhaustive
+// by refusal and adding a type is a deliberate act. A non-universal element (a
+// legitimately context- or application-tagged ANY) passes on its framing because no
+// content rule is knowable for it, and its constructed children are still walked.
+//
+// Every entry point takes the CALLER's error factory and code, so a c509 splice reports in
+// the c509 domain and a certificate builder in the x509 domain.
+// asn1-der composes this guard family, so requiring the codec at module scope would read its
+// exports mid-initialisation and see an empty object. The require and the table it builds are
+// therefore both deferred to first use -- the documented circular-load exception to top-of-file
+// requires. Guards sit BELOW the codec in the dependency order; this is the one place that
+// order is inverted, and it is inverted lazily.
+var asn1 = null;
+function _asn1() { if (asn1 === null) asn1 = require("./asn1-der"); return asn1; }
+
+// The strict content reader per universal primitive tag. A tag absent from this table has no
+// validator here and is refused by `element` below -- that refusal is the point.
+var VALUE_READERS = null;
+function _readers() {
+  if (VALUE_READERS !== null) return VALUE_READERS;
+  var asn1 = _asn1();
+  var m = {}, R = asn1.read, T = asn1.TAGS;
+  // ENUMERATED shares INTEGER's content rules and is NOT constrained to non-negative
+  // values. X.680 (02/2021) sec. 20.2 requires each NamedNumber's SignedNumber to be
+  // distinct, and sec. 19 defines SignedNumber ::= number | "-" number; the non-negativity
+  // in sec. 20.3 governs only an EnumerationItem written as a bare identifier, which is
+  // auto-assigned. `ENUMERATED { lowPriority(-1), normal(0) }` is well-formed, so rejecting
+  // a negative here would refuse valid input. This guard validates the ENCODING; which
+  // values a particular ENUMERATED admits lives in a type definition an opaque ANY does
+  // not carry.
+  m[T.BOOLEAN] = R.boolean; m[T.INTEGER] = R.integer; m[T.ENUMERATED] = R.enumerated;
+  m[T.BIT_STRING] = R.bitString; m[T.OCTET_STRING] = R.octetString; m[T.NULL] = R.nullValue;
+  m[T.OBJECT_IDENTIFIER] = R.oid; m[T.UTC_TIME] = R.time; m[T.GENERALIZED_TIME] = R.time;
+  // NumericString reads through its own reader: it is not a DirectoryString type, and routing
+  // it through read.string would fold it into the RFC 5280 sec. 7.1 name-comparison identity
+  // class (see asn1-der.js).
+  m[T.NUMERIC_STRING] = R.numericString;
+  [T.UTF8_STRING, T.PRINTABLE_STRING, T.IA5_STRING, T.TELETEX_STRING, T.VISIBLE_STRING,
+    T.BMP_STRING, T.UNIVERSAL_STRING].forEach(function (t) { m[t] = R.string; });
+  VALUE_READERS = m;
+  return VALUE_READERS;
+}
+
+// A universal SET's required member order depends on a type the ANY does not carry: X.690
+// sec. 11.6 orders a SET OF by the members' full encodings, while a structured SET is ordered
+// by TAG (X.680 sec. 8.6), and the two differ whenever the constructed bit does (a SEQUENCE
+// member, tag 16, sorts before a PrintableString, tag 19, by tag but after it by octets). A
+// structured SET cannot repeat a tag, so a repeated tag proves SET OF and the octet rule binds;
+// with all-distinct tags either reading is possible, so accept a value that satisfies EITHER
+// (rejecting only what is non-canonical under both readings: sound in both directions, never a
+// guess).
+//
+// KNOWN LIMITATION, and the two consumers do not weigh it identically. The either-reading rule
+// admits a SET OF that is tag-ordered but not octet-ordered, which is not canonical DER. On a
+// RECONSTRUCT path the input already exists and the alternative would refuse a valid structured
+// SET, so accepting is the sound direction. On a SIGNING path the caller composes the bytes and
+// could be held to octet order, so the same permissiveness lets a signer emit a non-canonical
+// SET under a real signature. Tightening it for signers alone would mean a mode flag on a
+// security posture, which this family avoids, and tightening it for both would reject valid
+// structured SETs that c509 round-trips today. The rule is therefore unchanged and the cost is
+// written down rather than discovered later.
+var TAG_CLASS_RANK = { universal: 0, application: 1, context: 2, private: 3 };
+function setOrderOk(kids) {
+  var i, dup = false, seen = {};
+  for (i = 0; i < kids.length; i++) {
+    var key = kids[i].tagClass + ":" + kids[i].tagNumber;
+    if (seen[key]) { dup = true; break; }
+    seen[key] = true;
+  }
+  var octetAsc = true, tagAsc = true;
+  for (i = 1; i < kids.length; i++) {
+    if (Buffer.compare(kids[i - 1].bytes, kids[i].bytes) > 0) octetAsc = false;
+    // Tag order ranks by CLASS first (universal < application < context < private, X.680
+    // sec. 8.6), then by tag number. Compare the class's NUMBER: the names do not sort in
+    // class order.
+    var pc = TAG_CLASS_RANK[kids[i - 1].tagClass], cc = TAG_CLASS_RANK[kids[i].tagClass];
+    if (pc !== cc ? pc > cc : kids[i - 1].tagNumber > kids[i].tagNumber) tagAsc = false;
+  }
+  return dup ? octetAsc : (octetAsc || tagAsc);
+}
+
+// element(node, E, code, label). Strict-validate an already-decoded DER element at ANY depth.
+// Rejects the reserved EOC tag 0; runs a universal primitive through its strict content reader
+// (or refuses a type with none); recurses into a constructed element's children; holds a
+// universal SET to a canonical order. Only SEQUENCE and SET are accepted as universal
+// CONSTRUCTED types -- an EXTERNAL / EMBEDDED PDV / CHARACTER STRING has mandatory components
+// this gate cannot verify (the degenerate empty form is not a valid encoding of any of them),
+// so it is refused for the same reason an unvalidatable primitive is.
+//
+// @enforced-by guard-shape-reinlined
+// @guard-shape _ANY_VALUE_READERS\[
+function element(node, E, code, label) {
+  if (node.tagClass === "universal" && node.tagNumber === 0) {
+    throw E(code, label + " must not use the reserved end-of-contents encoding (tag 0)");
+  }
+  var T = _asn1().TAGS;
+  if (node.constructed) {
+    if (node.tagClass === "universal" && node.tagNumber !== T.SEQUENCE && node.tagNumber !== T.SET) {
+      throw E(code, label + " of universal constructed type " + node.tagNumber + " has no strict DER structure validator here");
+    }
+    var kids = node.children;   // asn1.decode always sets a (possibly empty) children array
+    for (var i = 0; i < kids.length; i++) element(kids[i], E, code, label);
+    if (node.tagClass === "universal" && node.tagNumber === T.SET && !setOrderOk(kids)) {
+      throw E(code, label + " has a SET whose members are in no canonical DER order (X.690 sec. 11.6 / X.680 sec. 8.6)");
+    }
+    return;
+  }
+  if (node.tagClass === "universal") {
+    var reader = _readers()[node.tagNumber];
+    if (!reader) throw E(code, label + " of universal type " + node.tagNumber + " has no strict DER content validator here");
+    try { reader(node); }
+    catch (e) { throw E(code, label + " is not a valid DER element for its type", e); }
+  }
+}
+
+// tlv(content, E, code, label) -> content. Raw ANY bytes about to be spliced verbatim must be
+// exactly one non-empty, well-formed AND strictly-valid DER element: framing + no-trailing-data
+// via asn1.decode, then content / structure / SET order via `element`. Returns the bytes so a
+// call site can wrap a splice inline.
+//
+// @enforced-by guard-shape-reinlined
+// @guard-shape must be exactly one well-formed DER element
+function tlv(content, E, code, label) {
+  if (!content || content.length === 0) throw E(code, label + " must be a non-empty DER element");
+  var node;
+  try { node = _asn1().decode(content); }
+  catch (e) { throw E(code, label + " must be exactly one well-formed DER element (no trailing data)", e); }
+  element(node, E, code, label);
+  return content;
+}
+
+module.exports = { element: element, tlv: tlv };

package/lib/pki-build.js

@@ -129,7 +129,33 @@ function makeBuilder(ctx) {
         if (!Buffer.isBuffer(ipBuf) || (ipBuf.length !== 4 && ipBuf.length !== 16)) throw E("bad-input", "iPAddress must be a 4- or 16-octet Buffer or an IPv4/IPv6 string");
         return b.contextPrimitive(7, ipBuf);
       case "directoryName": return b.explicit(4, encodeName(v));   // Name is a CHOICE -> the context tag is EXPLICIT
-      default: throw E("bad-input", "unsupported GeneralName form " + JSON.stringify(k) + " (supported: rfc822Name, dNSName, uniformResourceIdentifier, iPAddress, directoryName)");
+      case "otherName":
+        // otherName ::= SEQUENCE { type-id OBJECT IDENTIFIER, value [0] EXPLICIT ANY }, tagged
+        // [0] IMPLICIT (RFC 5280 sec. 4.2.1.6). The value is EXPLICIT because ANY carries no tag
+        // of its own, so the wrapper is what makes the encoding unambiguous -- the same shape the
+        // decoder requires, and without it an SmtpUTF8Mailbox (RFC 8398 sec. 3) could be read but
+        // never written.
+        if (typeof v !== "object" || Buffer.isBuffer(v)) throw E("bad-input", "otherName must be an object { typeId, value }");
+        if (typeof v.typeId !== "string" || !v.typeId) throw E("bad-input", "otherName requires a `typeId` OID string");
+        if (!Buffer.isBuffer(v.value) || v.value.length === 0) {
+          throw E("bad-input", "otherName requires a `value` Buffer holding one DER element");
+        }
+        // The value is spliced in raw and this verb SIGNS the result, so it is strictly
+        // validated rather than taken on the caller's word. Framing alone is not DER: a
+        // BOOLEAN whose content octet is 0x01, a NumericString holding "@", or a SET in no
+        // canonical order all frame cleanly and would ship inside a [0] EXPLICIT wrapper
+        // under a real signature. guard.der.tlv is the one place that rule lives.
+        guard.der.tlv(v.value, E, "bad-input", "otherName `value`");
+        // [0] IMPLICIT on a SEQUENCE replaces the SEQUENCE tag, so the content is the two
+        // members concatenated -- build.contextConstructed takes content bytes, not elements.
+        // The type-id encode is wrapped so a malformed OID reports in the CALLER's namespace
+        // (x509/bad-input, csr/bad-input, ...) like every other raw-OID path here, rather than
+        // surfacing the codec's own oid/* code from a shared builder the caller never named.
+        var typeIdDer;
+        try { typeIdDer = b.oid(v.typeId); }
+        catch (e) { throw E("bad-input", "invalid otherName type-id OID " + JSON.stringify(v.typeId) + " (violates the X.660 arc bounds)", e); }
+        return b.contextConstructed(0, Buffer.concat([typeIdDer, b.explicit(0, v.value)]));
+      default: throw E("bad-input", "unsupported GeneralName form " + JSON.stringify(k) + " (supported: rfc822Name, dNSName, uniformResourceIdentifier, iPAddress, directoryName, otherName)");
     }
   }
 

package/lib/schema-c509.js

@@ -1594,17 +1594,9 @@ function _extValueFromDer(name, der) {
 // and RFC 3161 timestamping, and must not creep into a third consumer). On the ENCODE path such a value simply
 // degrades to the byte-exact ~oid + byte-string form, losing nothing; on the DECODE path it is a fail-closed
 // verdict.
-var _ANY_VALUE_READERS = (function () {
-  var m = {}, R = asn1.read, T = asn1.TAGS;
-  m[T.BOOLEAN] = R.boolean; m[T.INTEGER] = R.integer; m[T.ENUMERATED] = R.enumerated;
-  m[T.BIT_STRING] = R.bitString; m[T.OCTET_STRING] = R.octetString; m[T.NULL] = R.nullValue;
-  m[T.OBJECT_IDENTIFIER] = R.oid; m[T.UTC_TIME] = R.time; m[T.GENERALIZED_TIME] = R.time;
-  // NumericString reads through its own reader: it is not a DirectoryString type, and routing it through
-  // read.string would fold it into the RFC 5280 sec. 7.1 name-comparison identity class (see asn1-der.js).
-  m[T.NUMERIC_STRING] = R.numericString;
-  [T.UTF8_STRING, T.PRINTABLE_STRING, T.IA5_STRING, T.TELETEX_STRING, T.VISIBLE_STRING, T.BMP_STRING, T.UNIVERSAL_STRING].forEach(function (t) { m[t] = R.string; });
-  return m;
-})();
+// The per-type strict content readers, the SET canonical-order rule and the recursive element
+// walk all moved to guard.der, so this module and pki-build cannot drift on what "one strictly
+// valid DER element" means.
 
 // A universal SET's required member order depends on a type the ANY does not carry: X.690 sec. 11.6 orders a
 // SET OF by the members' full encodings, while a structured SET is ordered by TAG (X.680 sec. 8.6), and the two
@@ -1612,24 +1604,6 @@ var _ANY_VALUE_READERS = (function () {
 // tag but after it by octets). A structured SET cannot repeat a tag, so a repeated tag proves SET OF and the
 // octet rule binds; with all-distinct tags either reading is possible, so accept a value that satisfies EITHER
 // (rejecting only what is non-canonical under both readings: sound in both directions, never a guess).
-var _TAG_CLASS_RANK = { universal: 0, application: 1, context: 2, private: 3 };
-function _setOrderOk(kids) {
-  var i, dup = false, seen = {};
-  for (i = 0; i < kids.length; i++) {
-    var key = kids[i].tagClass + ":" + kids[i].tagNumber;
-    if (seen[key]) { dup = true; break; }
-    seen[key] = true;
-  }
-  var octetAsc = true, tagAsc = true;
-  for (i = 1; i < kids.length; i++) {
-    if (Buffer.compare(kids[i - 1].bytes, kids[i].bytes) > 0) octetAsc = false;
-    // Tag order ranks by CLASS first (universal < application < context < private, X.680 sec. 8.6), then by tag
-    // number. Compare the class's NUMBER: the names do not sort in class order.
-    var pc = _TAG_CLASS_RANK[kids[i - 1].tagClass], cc = _TAG_CLASS_RANK[kids[i].tagClass];
-    if (pc !== cc ? pc > cc : kids[i - 1].tagNumber > kids[i].tagNumber) tagAsc = false;
-  }
-  return dup ? octetAsc : (octetAsc || tagAsc);
-}
 
 // Strict-validate a decoded DER element at ANY depth, in the caller's error domain. Rejects the reserved EOC tag
 // 0; runs a universal primitive through its strict content reader (or rejects a type with none); recurses into a
@@ -1638,37 +1612,13 @@ function _setOrderOk(kids) {
 // components this gate cannot verify (the degenerate empty form is not a valid encoding of any of them), so it is
 // refused for the same reason an unvalidatable primitive is. A NON-universal element (a legitimately context- or
 // application-tagged ANY) passes on its framing, but its constructed children are still walked.
-function _strictDerElement(node, code, label) {
-  if (node.tagClass === "universal" && node.tagNumber === 0) throw _err(code, label + " must not use the reserved end-of-contents encoding (tag 0)");
-  if (node.constructed) {
-    if (node.tagClass === "universal" && node.tagNumber !== asn1.TAGS.SEQUENCE && node.tagNumber !== asn1.TAGS.SET) {
-      throw _err(code, label + " of universal constructed type " + node.tagNumber + " has no strict DER structure validator here");
-    }
-    var kids = node.children;   // asn1.decode always sets a (possibly empty) children array on a constructed node
-    for (var i = 0; i < kids.length; i++) _strictDerElement(kids[i], code, label);
-    if (node.tagClass === "universal" && node.tagNumber === asn1.TAGS.SET && !_setOrderOk(kids)) {
-      throw _err(code, label + " has a SET whose members are in no canonical DER order (X.690 sec. 11.6 / X.680 sec. 8.6)");
-    }
-    return;
-  }
-  if (node.tagClass === "universal") {
-    // Validate-or-reject: a universal primitive with no strict content reader is never accepted on framing alone
-    // (asn1.decode frames a malformed NumericString "12 01 40" happily), so the map is exhaustive by refusal.
-    var reader = _ANY_VALUE_READERS[node.tagNumber];
-    if (!reader) throw _err(code, label + " of universal type " + node.tagNumber + " has no strict DER content validator here");
-    try { reader(node); } catch (e) { throw _err(code, label + " is not a valid DER element for its type", e); }
-  }
-}
 // Raw ANY bytes about to be spliced verbatim must be exactly one non-empty, well-formed AND strictly-valid DER
-// element: framing + no-trailing-data via asn1.decode, then content / structure / SET order via
-// _strictDerElement, both reported in the CALLER's error domain. Returns the bytes so a call site can wrap a
-// splice inline. Used by every reconstruct site that emits caller-supplied ANY bytes verbatim.
+// element. The rule itself lives in guard.der -- framing + no-trailing-data, then content / structure / SET
+// order -- so this module and the certificate builder cannot drift apart on what "one DER element" means. This
+// stays as a named local because every reconstruct site here reads better naming the intent than the guard.
+
 function _requireStrictDerTlv(content, code, label) {
-  if (content.length === 0) throw _err(code, label + " must be a non-empty DER element");
-  var node;
-  try { node = asn1.decode(content); } catch (e) { throw _err(code, label + " must be exactly one well-formed DER element (no trailing data)", e); }
-  _strictDerElement(node, code, label);
-  return content;
+  return guard.der.tlv(content, _err, code, label);
 }
 
 // asn1.build.set SORTS its members, so handing it a non-canonically-ordered values list would silently rewrite

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.5.8",
+  "version": "0.5.9",
   "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:7e436b38-9f18-4222-a517-c69211740ba0",
+  "serialNumber": "urn:uuid:0541b2cd-7339-4ee1-9122-38999da30d35",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-08-18T02:52:33.662Z",
+    "timestamp": "2026-08-18T06:52:40.138Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.5.8",
+      "bom-ref": "@blamejs/pki@0.5.9",
       "type": "application",
       "name": "pki",
-      "version": "0.5.8",
+      "version": "0.5.9",
       "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.5.8",
+      "purl": "pkg:npm/%40blamejs/pki@0.5.9",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.5.8",
+      "ref": "@blamejs/pki@0.5.9",
       "dependsOn": []
     }
   ]