@blamejs/pki 0.4.5 → 0.4.6

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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.4.6 — 2026-08-08
+
+A C509 certificate now has one encoding where the specification defines one -- nine alternative spellings that rebuilt a byte-identical X.509 certificate, so that a single signature covered all of them, are refused, and the encoder emits the spelling it accepts.
+
+### Fixed
+
+- An attribute value now carries the one spelling the specification assigns it. A text value of even length drawn only from the characters 0-9 and a-f is a byte string; a value in EUI-64 form is a tagged MAC address, 48-bit when it matches the FF-FE marker pattern and 64-bit otherwise; anything else is text. Each alternative spelling rebuilt the identical certificate, so the one signature over it covered them all. An empty value spelled as an empty byte string is refused for the same reason -- it renders as the empty text, which already has a spelling.
+- A name holding a single common name is the bare value, not an array of one pair; an extensions field holding only a key usage is the single integer, not an array of two; and an alternative name holding exactly one DNS name is the bare text, not an array. Each of these compact forms is the encoding the specification defines for that case, and the long form of the same value is now refused rather than accepted alongside it. The long form remains the encoding for every case that is not the single one -- a name with two attributes, a key usage beside another extension, an alternative name with two entries.
+- A certificate whose issuer is identical to its subject encodes that issuer as the CBOR simple value null, which the specification requires and which this toolkit previously wrote out in full. Both directions changed: the encoder emits the null, and a certificate that spells the issuer out instead is refused. The comparison is made on the certificate's own bytes rather than on a normalized name, because the reconstruction rebuilds a null issuer from the subject -- two names that merely compare equal would rebuild different bytes and break the signature over them.
+- Algorithm parameters must be a complete element. An empty byte string is none, and it rebuilt the same algorithm identifier as the form that omits parameters entirely, giving one algorithm two encodings.
+- The encoder walks the same rules it enforces on the way in, so a certificate it emits is one it reads back. Previously it wrote an even-length-hex attribute value as text -- a spelling its own parser now refuses -- and wrote a self-signed certificate's issuer out in full.
+
+### Known limitations
+
+- One redundancy remains because the specification permits it: a registered algorithm may be encoded either as its registry integer or as its object identifier, and both are accepted, so a certificate using one is byte-different from the same certificate using the other. Identify a certificate by the X.509 bytes it reconstructs rather than by its C509 bytes.
+
 ## v0.4.5 — 2026-08-08
 
 A private key created outside this toolkit's own WebCrypto now signs and exports across the toolkit -- a key from the platform's WebCrypto, or from a separately-installed copy of this toolkit, previously reached the crypto library as a key it could not read and failed with a type error instead of a reason.

package/lib/jose.js

@@ -437,9 +437,10 @@ async function sign(opts) {
   var payloadB64 = payload.length === 0 ? "" : b64uEncode(payload);
   var signingInput = Buffer.from(protectedB64 + "." + payloadB64, "ascii");
   var jwk = header.jwk || opts.jwk || {};
-  // opts.key is documented as a CryptoKey, so a CryptoKey from any WebCrypto implementation signs
-  // here; one from another implementation carries none of the material this engine signs with and
-  // is re-imported through it, rather than reaching subtle.sign as a key it cannot read.
+  // opts.key is documented as a CryptoKey, so one created outside this engine signs here too: it
+  // carries none of the material this engine signs with, and is re-imported through it rather than
+  // reaching subtle.sign as a key it cannot read. A key whose material this process cannot reach at
+  // all -- non-extractable, or held behind another implementation's interface -- is refused there.
   var signKey = await wcEngine.adoptKey(opts.key, null, ["sign"], E, "jose/bad-input");
   var sigBuf = Buffer.from(await webcrypto.subtle.sign(_cryptoAlg(checked.algRow, jwk, signKey), signKey, signingInput));
   // Pin the produced signature length the same way verify does. A key whose curve /

package/lib/schema-c509.js

@@ -225,6 +225,11 @@ function _algorithm(node, byInt, code, label) {
     // The [~oid, params] form carries the DER parameters as a CBOR byte string; a non-byte-string here
     // is malformed and cannot be reconstructed (b.raw would append garbage) -- fail closed.
     if (node.children[1].majorType !== 2) throw _err(code, label + " algorithm parameters must be a CBOR byte string");
+    // The parameters carry ONE complete DER element spliced into the reconstruction. An empty byte
+    // string is no element at all: it rebuilds the same AlgorithmIdentifier as the bare ~oid form,
+    // which is how the CDDL already spells "no parameters" -- so accepting it would give one
+    // algorithm two encodings, and one X.509 signature would cover both.
+    if (node.children[1].content.length === 0) throw _err(code, label + " algorithm parameters must not be an empty byte string; omit them with the bare ~oid form (draft sec. 3.1.3)");
     return { name: a.name, oid: a.oid, parameters: node.children[1].content };
   }
   throw _err(code, label + " is not a C509 AlgorithmIdentifier (int / ~oid / [~oid, params])");
@@ -248,6 +253,40 @@ function _specialText(node) {
   throw _err("c509/bad-name", "an attribute value is not a C509 SpecialText (text / bytes / tag-48)");
 }
 
+// draft sec. 3.1.4 fixes WHICH of the three SpecialText spellings a value takes -- the choice belongs to
+// the specification, not the sender. A text string of an even length >= 2 drawn only from '0'-'9'/'a'-'f'
+// is encoded as a byte string; a text string of the form "HH-HH-HH-HH-HH-HH-HH-HH" is encoded as a tag-48
+// MAC address, 48-bit when it matches "HH-HH-HH-FF-FE-HH-HH-HH" and 64-bit otherwise; anything else is a
+// text string. Accepting a second spelling of one value would give the reconstructed certificate more than
+// one C509 encoding, so a single X.509 signature would cover them all and two distinct byte strings would
+// name one certificate. NOT enforced for a natively signed certificate: sec. 3.1.4 says bytes and tag 48
+// there "do not correspond to any predefined text string encoding and may also be used for other attribute
+// types", so no canonical text spelling exists to hold one to.
+var _HEX_OPTIMIZED = /^(?:[0-9a-f]{2})+$/;
+var _EUI64_TEXT = /^(?:[0-9A-F]{2}-){7}[0-9A-F]{2}$/;
+function _assertCanonicalSpecialText(node, isNative, E) {
+  if (isNative) return;
+  if (node.majorType === 3) {
+    var t = cbor.read.textString(node);
+    if (t.length >= 2 && _HEX_OPTIMIZED.test(t)) {
+      throw _err(E, "a text attribute value of even-length hex characters must be encoded as a CBOR byte string (draft sec. 3.1.4)");
+    }
+    if (_EUI64_TEXT.test(t)) {
+      throw _err(E, "a text attribute value in EUI-64 form must be encoded as a CBOR tag-48 MAC address (draft sec. 3.1.4)");
+    }
+    return;
+  }
+  if (node.majorType === 2) {
+    // An empty byte string renders as the empty text, whose canonical spelling is a text string.
+    if (node.content.length === 0) throw _err(E, "an empty attribute value must be encoded as a CBOR text string (draft sec. 3.1.4)");
+    return;
+  }
+  var eui = node.children[0].content;
+  if (eui.length === 8 && eui[3] === 0xff && eui[4] === 0xfe) {
+    throw _err(E, "an EUI-64 of the form HH-HH-HH-FF-FE-HH-HH-HH must be encoded as a 48-bit MAC address (draft sec. 3.1.4)");
+  }
+}
+
 // A single Name (sec. 3.1.4/sec. 3.1.6): the CBOR simple null (issuer only) | a bare SpecialText single
 // commonName | an array of RDNAttributes. Surfaces { dn, rdns, eui64? } shape-compatible with x509.
 // An rdn's (attribute type, sign) pair DECLARES an X.509 string type, so its text must be valid for that type --
@@ -269,6 +308,7 @@ function _name509(node, isSubject, isNative) {
   // A bare SpecialText (not an array) is a single commonName attribute (attributeType == +1).
   if (node.majorType === 3 || node.majorType === 2 || node.majorType === 6) {
     var sv = _specialText(node);
+    _assertCanonicalSpecialText(node, isNative, "c509/bad-name");
     // The bare form is a single commonName -- hold its value to the SAME rules the array form applies, so a
     // natively-signed certificate (which never reconstructs) cannot carry a value the reconstruction would refuse.
     // A tag-48 MAC renders to a fixed 17-character EUI-64 string that satisfies every value rule by
@@ -307,6 +347,7 @@ function _name509(node, isSubject, isNative) {
     var tname = ATTR_BY_INT[Math.abs(ti)];
     if (tname === undefined) throw _err("c509/bad-name", "attribute type integer " + ti + " has no C509 registry row");
     var v = _specialText(kids[i + 1]);
+    _assertCanonicalSpecialText(kids[i + 1], isNative, "c509/bad-name");
     var vv = v.text !== undefined ? v.text : (v.hex !== undefined ? v.hex : _macToEui64String(v.eui64));
     // The RENDERED text is what carries into the rdn -- deliberately NOT the raw eui64, because the EUI shortcut
     // in _reconAttrValue is unconditional and would take precedence over the attribute's declared string type,
@@ -317,6 +358,13 @@ function _name509(node, isSubject, isNative) {
     rdns.push(rdn);
     parts.push(_shortName(tname) + "=" + guard.name.escapeDnValue(vv));
   }
+  // sec. 3.1.4: "If Name contains a single 'common name' attribute with attributeType = +1, it is for
+  // compactness encoded as just the SpecialText containing the single attribute value." The array
+  // spelling of that one case is therefore a second encoding of a name that already has a canonical
+  // one. Only +1 has a bare form -- a negative (printableString) commonName keeps the array.
+  if (!isNative && rdns.length === 1 && rdns[0].type === "commonName" && !rdns[0].printable) {
+    throw _err("c509/bad-name", "a Name holding a single +1 commonName must be encoded as a bare SpecialText, not an array (draft sec. 3.1.4)");
+  }
   return { rdns: rdns, dn: parts.join(",") };
 }
 // The rendered dn is an RFC 4514 string, so every VALUE is escaped through the shared guard the rest of the
@@ -1109,6 +1157,14 @@ function _extValueToDer(name, node, isNative) {
     case "subjectAltName":
     case "issuerAltName":          // SubjectAltName = GeneralNames / text (exactly one dNSName -> bare text)
       if (node.majorType === 3) return b.sequence([b.contextPrimitive(2, _ia5Bytes(node, 2))]);
+      // sec. 3.3: "If subjectAltName contains exactly one dNSName, the array and the int are omitted and
+      // extensionValue is the dNSName encoded as a CBOR text string." The array spelling of that one case
+      // is a second encoding of the same extension value.
+      if (!isNative && node.majorType === 4 && node.children && node.children.length === 2 &&
+          node.children[0].majorType === 0 && Number(cbor.read.int(node.children[0])) === 2 &&
+          node.children[1].majorType === 3) {
+        throw _err("c509/bad-extensions", "a " + name + " holding exactly one dNSName must be encoded as a bare CBOR text string, not an array (draft sec. 3.3)");
+      }
       return b.sequence(_generalNamesToDer(node, isNative));
     case "nameConstraints": {      // [ permittedSubtrees / null, excludedSubtrees / null ]
       if (node.majorType !== 4 || !node.children || node.children.length !== 2) throw _err("c509/bad-extensions", "a nameConstraints value must be a 2-element CBOR array [ permitted, excluded ] (sec. 3.3)");
@@ -1747,6 +1803,14 @@ function _extensions(node, isNative) {
   // Each extension is an (extensionID, extensionValue) pair; an odd-length array is a dangling
   // extension identifier with no value -- reject rather than silently drop the trailing element.
   if (kids.length % 2 !== 0) throw _err("c509/bad-extensions", "a C509 extensions array must be id/value pairs (dangling extension identifier)");
+  // sec. 3.1.10: "If the CBOR array contains exactly two ints and the absolute value of the first int is
+  // 2 (corresponding to keyUsage), the CBOR array is omitted and the 'extensions' field is encoded as a
+  // single CBOR int." The array spelling of that one case is a second encoding of the same extensions.
+  if (!isNative && kids.length === 2 &&
+      (kids[0].majorType === 0 || kids[0].majorType === 1) && (kids[1].majorType === 0 || kids[1].majorType === 1) &&
+      Math.abs(Number(cbor.read.int(kids[0]))) === 2) {
+    throw _err("c509/bad-extensions", "an extensions field holding only keyUsage must be encoded as a single CBOR int, not an array (draft sec. 3.1.10)");
+  }
   for (var i = 0; i + 1 < kids.length; i += 2) {
     var idNode = kids[i], valNode = kids[i + 1];
     var name, extOid, critical, valContent;
@@ -1921,13 +1985,21 @@ function _reconAlgId(alg) {
 // The full type-3 -> DER Certificate reconstruction, byte-for-byte.
 function _reconstructDer(r, sigNode) {
   var sigAlgSeq = _reconAlgId(r.signatureAlgorithm);
+  var subjectName = _reconName(r.subject);
+  var spelledIssuer = r.issuer && r.issuer.rdns ? _reconName(r.issuer) : null;
+  // sec. 3.1.4: an issuer identical to the subject MUST be the CBOR simple value null. Spelling it
+  // out instead rebuilds the same DER, so one certificate would have two C509 encodings and the one
+  // X.509 signature over that DER would cover both.
+  if (spelledIssuer !== null && spelledIssuer.equals(subjectName)) {
+    throw _err("c509/bad-name", "an issuer identical to the subject must be encoded as the CBOR simple value null (draft sec. 3.1.4)");
+  }
   var tbsFields = [
     b.explicit(0, b.integer(2n)),                                  // version v3 (type-3 is X.509 v3)
     b.integer(r.serialNumber),
     sigAlgSeq,
-    _reconName(r.issuer && r.issuer.rdns ? r.issuer : r.subject),  // null issuer -> issuer == subject
+    spelledIssuer === null ? subjectName : spelledIssuer,          // null issuer -> issuer == subject
     b.sequence([_reconTime(r.validity.notBefore), _reconTime(r.validity.notAfter)]),
-    _reconName(r.subject),
+    subjectName,
     _reconSpki(r.subjectPublicKeyAlgorithm, r.subjectPublicKey, r.rsaPublicKey),
   ];
   // RFC 5280 sec. 4.1: the [3] extensions field is OPTIONAL and, when present, SHALL contain at least one
@@ -2088,6 +2160,10 @@ function _minBytes(n) {
   return Buffer.from(hex, "hex");
 }
 // A C509 AlgorithmIdentifier -> int (registry) | ~oid (bare bytes) | [~oid, params]. `key` selects the row.
+// The bare-~oid arm is unreachable from either call site as the type-3 encoder stands, and is kept as
+// the honest fallback rather than an assumption: the signature slot refuses every non-ECDSA algorithm
+// before this runs, and every curve the subjectPublicKey slot accepts (prime256v1 / secp384r1 /
+// secp521r1) carries an ecPublicKey registry row. Adding a curve without its row would reach it.
 function _encAlgorithm(alg, toInt, key) {
   var i = toInt[key];
   if (i !== undefined && !(alg.parameters && alg.parameters.length)) return cbor.build.int(BigInt(i));
@@ -2095,10 +2171,16 @@ function _encAlgorithm(alg, toInt, key) {
   if (alg.parameters && alg.parameters.length) return cbor.build.array([oidBytes, cbor.build.byteString(alg.parameters)]);
   return oidBytes;
 }
-// A SpecialText attribute value -> CBOR (text | tag-48 EUI). v1 encodes the text + eui64 forms.
+// A SpecialText attribute value -> CBOR, walking the sec. 3.1.4 cascade: an EUI-64 is a tag-48 MAC
+// address, a text string of even length >= 2 drawn only from '0'-'9'/'a'-'f' is a byte string, and
+// anything else is a text string. The decoder holds an incoming certificate to exactly this cascade,
+// so the encoder walks it too -- a spelling chosen here that the decoder refuses would make this
+// encoder emit certificates its own parser rejects.
 function _encSpecialText(rdn) {
   if (rdn.eui64) return cbor.build.tag(48, cbor.build.byteString(rdn.eui64));
-  return cbor.build.textString(String(rdn.value));
+  var v = String(rdn.value);
+  if (v.length >= 2 && _HEX_OPTIMIZED.test(v)) return cbor.build.byteString(Buffer.from(v, "hex"));
+  return cbor.build.textString(v);
 }
 // A Name -> CBOR: null (issuer only) | a bare SpecialText single utf8 commonName | an array of RDN pairs.
 function _encName(name, isSubject) {
@@ -2375,7 +2457,13 @@ _derToType3 = function (input, opts) {
     certificateType: 3,
     serialNumber: c.serialNumber,          // no serialNumberHex -> the encoder uses the minimal ~biguint magnitude
     signatureAlgorithm: { name: c.signatureAlgorithm.name, oid: c.signatureAlgorithm.oid },
-    issuer: _c509NameFromDer(c.issuer.bytes),
+    // sec. 3.1.4: "If the 'issuer' field is identical to the 'subject' field, e.g., in case of
+    // self-signed certificates, then the 'issuer' field MUST be encoded as the CBOR simple value
+    // null." Compared on the RAW DER bytes, not on a canonicalized name: the reconstruction rebuilds
+    // a null issuer FROM the subject, so two names that merely compare equal (a PrintableString
+    // against a UTF8String of the same characters) would rebuild different bytes and break the
+    // signature that covers them. Byte-identical is exactly the condition under which that is safe.
+    issuer: c.issuer.bytes.equals(c.subject.bytes) ? null : _c509NameFromDer(c.issuer.bytes),
     validity: { notBefore: c.validity.notBefore, notAfter: c.validity.notAfter.getTime() === _NO_EXPIRY ? null : c.validity.notAfter },
     subject: _c509NameFromDer(c.subject.bytes),
     subjectPublicKeyAlgorithm: { name: "ecPublicKey", oid: c.subjectPublicKeyInfo.algorithm.oid, curve: curve },

package/lib/sign-scheme.js

@@ -170,9 +170,9 @@ function _normCompositeKeys(key, comp, E) {
 function _importKey(key, imp, E) {
   if (key && typeof key === "object" && !Buffer.isBuffer(key) && !(key instanceof Uint8Array) && key.type === "private") {
     _assertKeyMatchesScheme(key, imp, E);
-    // `key` is documented as taking a CryptoKey, so a CryptoKey from any WebCrypto implementation
-    // signs here -- one from another implementation is re-imported through this engine, because it
-    // carries none of the key material this engine signs with.
+    // `key` is documented as taking a CryptoKey, so one created outside this engine signs here too --
+    // it is re-imported through this engine, because it carries none of the key material this engine
+    // signs with. One whose material this process cannot reach is refused with that as the reason.
     return webcrypto.adoptKey(key, imp, ["sign"], E, "bad-input");
   }
   var der;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "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:1b37cc21-0807-4acb-b565-ce23bee1bd57",
+  "serialNumber": "urn:uuid:1feef474-ddbd-4d2d-ae82-845a967ba69b",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-08-08T19:12:34.134Z",
+    "timestamp": "2026-08-08T20:12:36.384Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.4.5",
+      "bom-ref": "@blamejs/pki@0.4.6",
       "type": "application",
       "name": "pki",
-      "version": "0.4.5",
+      "version": "0.4.6",
       "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.4.5",
+      "purl": "pkg:npm/%40blamejs/pki@0.4.6",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.4.5",
+      "ref": "@blamejs/pki@0.4.6",
       "dependsOn": []
     }
   ]