@blamejs/pki 0.2.32 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.3.0 — 2026-07-17
+
+pki.x509.sign issues X.509 certificates -- self-signed or CA-signed, over every signature algorithm the toolkit supports, from RSA and ECDSA through EdDSA, ML-DSA, and SLH-DSA.
+
+### Added
+
+- pki.x509.sign(spec, issuer, opts) builds and signs an X.509 certificate -- self-signed (a signing key alone) or CA-signed (an explicit issuer name and public key, or an issuing certificate) -- and returns DER, or a PEM CERTIFICATE string with opts.pem. The signing algorithm is resolved from the key: RSA PKCS#1 v1.5, RSASSA-PSS (opts.pss), ECDSA P-256/P-384/P-521, Ed25519, Ed448, ML-DSA-44/65/87, the twelve SLH-DSA parameter sets, and the composite arms. The version, serial-number bounds, UTCTime/GeneralizedTime cutover, DER default omissions, and the CA cross-field rules are enforced; malformed input throws a typed CertificateError. Certificate parsing remains pki.schema.x509.parse.
+- pki.asn1.build.namedBitString(positions) encodes a minimal DER NamedBitList (X.690 section 11.2.2) -- the asserted bit positions with every trailing zero bit removed -- the single canonical home the keyUsage and PKIFailureInfo encoders now compose.
+
+### Security
+
+- The Sigstore bundle verifier now routes an Ed25519 or Ed448 key through the shared full-order, on-curve Edwards-point gate at the raw signature-verification sink, not only at key parsing -- a low-order or off-curve key that would verify a forged EdDSA signature is refused wherever a verify path handles one. This completes the defense across every EdDSA verification sink in the toolkit.
+
+## v0.2.33 — 2026-07-16
+
+Attribute certificates now decode their RFC 5755 attribute values and attribute-certificate extensions, not just the certificate structure.
+
+### Added
+
+- pki.schema.attrcert.parse decodes the RFC 5755 section 4.4 attribute values -- role (RoleSyntax), clearance (Clearance, including the classification bit list and security categories), authenticationInfo and accessIdentity (SvceAuthInfo), and group and chargingIdentity (IetfAttrSyntax) -- and the section 4.3 attribute-certificate extensions -- auditIdentity, targetInformation and proxyInfo (Targets, with targetCert reusing the IssuerSerial decoder), noRevAvail, and aaControls. Each is surfaced additively (a decoded field alongside the raw value) through the parse consumer path; an unrecognized attribute type or extension id is preserved opaque, and a malformed recognized value fails closed with a typed error. Every GeneralName inside these structures is validated through the shared name decoder.
+
 ## v0.2.32 — 2026-07-16
 
 X.509 certificates now decode the Microsoft Active Directory Certificate Services enrollment extensions, and pki.lint's critical-extension check is aligned with certification-path validation.

package/README.md

@@ -211,7 +211,7 @@ is callable today; nothing below is a stub.
 | `pki.schema.cms` | Parse DER / PEM CMS per RFC 5652 / 5083 / 9629 — SignedData (§5, signer infos + raw signed-attribute bytes for external verification), EnvelopedData (§6, all five RecipientInfo kinds incl. RFC 5753 key-agreement and RFC 9629 KEM recipients with ML-KEM validation), EncryptedData (§8), AuthenticatedData (§9, MAC surface + raw `authAttrsBytes`), and AuthEnvelopedData (RFC 5083, with RFC 5084 AES-GCM/CCM parameter validation); §11 attribute placement enforced, countersignatures validated recursively, certificates / CRLs validated against the closed CHOICE sets and kept raw, every result tagged `contentTypeName`, fail-closed — `parse`, `pemDecode`, `pemEncode` |
 | `pki.schema.ocsp` | Parse DER / PEM OCSP requests and responses per RFC 6960 — per-certificate status (good / revoked / unknown), responder identity, raw tbs bytes for external verification, certificates kept raw, fail-closed; non-basic response types recognized (not decoded) — `parseRequest`, `parseResponse`, `pemDecode`, `pemEncode` |
 | `pki.schema.tsp` | Parse DER / PEM RFC 3161 timestamp requests, responses, and tokens — the TimeStampReq a client sends (imprint, requested policy, nonce, certReq), the TSTInfo payload (imprint, genTime with sub-second precision, serial, nonce, accuracy), the status-to-token coupling, and the token wrapper composed over CMS with the single-signer rule, fail-closed — `parse`, `parseRequest`, `parseResponse`, `parseTstInfo`, `parseToken`, `pemDecode`, `pemEncode` |
-| `pki.schema.attrcert` | Parse DER / PEM RFC 5755 attribute certificates — the holder and issuer identities (validated GeneralNames), the validity window (real `Date`s), the privilege attributes (role / group / clearance) and extensions, with the raw signed region for a verifier; the obsolete v1 form is recognized and deferred, fail-closed — `parse`, `pemDecode`, `pemEncode` |
+| `pki.schema.attrcert` | Parse DER / PEM RFC 5755 attribute certificates — the holder and issuer identities (validated GeneralNames), the validity window (real `Date`s), the privilege attributes and extensions **decoded to structured values** (role, clearance, service/access identity, group, charging identity; audit identity, target/proxy information, no-rev-avail, AA controls — unknown types preserved opaque), with the raw signed region for a verifier; the obsolete v1 form is recognized and deferred, fail-closed — `parse`, `pemDecode`, `pemEncode` |
 | `pki.schema.crmf` | Parse DER / PEM RFC 4211 certificate request messages (CertReqMessages — the CMP / EST enrollment body) — the requested-certificate template (subject, public key, validity, extensions), proof-of-possession, and registration controls, with the raw `CertRequest` region a POP verifier hashes; names dual-accepted (IMPLICIT and EXPLICIT), fail-closed — `parse`, `pemDecode`, `pemEncode` |
 | `pki.schema.pkcs12` | Parse DER / BER / PEM RFC 7292 PKCS#12 (PFX) stores — key bags via the PKCS#8 parser, shrouded keys (algorithm surfaced, ciphertext opaque), cert / CRL / secret bags raw and byte-exact, encrypted and enveloped safes structurally via CMS, `friendlyName` / `localKeyId` decoded, and the exact MAC byte range (`macedBytes`) plus RFC 9579 PBMAC1 recognition for external verification; BER accepted exactly where §4.1 requires it, fail-closed — `parse`, `pemDecode`, `pemEncode` |
 | `pki.schema.cmp` | Parse DER / PEM RFC 9810 Certificate Management Protocol messages (PKIMessage) — the header (version, sender / recipient incl. the anonymous NULL-DN, nonces, transaction id, general info), the 27-arm body (certificate requests via the CRMF parser, an encrypted certificate's EnvelopedData via CMS, response / revocation / confirmation / error / support / polling arms structural, the rest raw), and the exact `headerBytes` / `bodyBytes` slices an external verifier reconstructs the protected part from; the CMP-before-OCSP dispatch order is enforced, fail-closed — `parse`, `pemDecode`, `pemEncode` |
@@ -222,6 +222,7 @@ is callable today; nothing below is a stub.
 | `pki.schema.smime` | Decode S/MIME ESS signed-attribute values (RFC 5035 / RFC 8551) — `parseSigningCertificate` / `parseSigningCertificateV2` bind a signature to its signing certificate (cert hash, hash algorithm, issuer `GeneralNames` + serial), `parseSmimeCapabilities` decodes the ordered capability list, and `decodeAttribute` OID-dispatches a CMS attribute (enforcing the single-value rule, recognize-and-defer for unknown types). A companion decoder for CMS signed attributes, not an auto-routed format, fail-closed — `parseSigningCertificate`, `parseSigningCertificateV2`, `parseSmimeCapabilities`, `decodeAttribute` |
 | `pki.schema.engine` | The declarative ASN.1 structure-schema engine every format parser composes — `walk` / `encode` / `embeddedDer` plus the schema combinators |
 | `pki.path` | RFC 5280 §6 certification-path validation — `validate` runs the §6.1 state machine (signature chaining across RSA, ECDSA, EdDSA, ML-DSA, SLH-DSA and hybrid composite ML-DSA signatures — a composite is accepted only when **both** its post-quantum and traditional components verify; validity windows, name chaining, basic constraints and path length, key usage, name constraints, the certificate-policy tree) over an ordered path and a trust anchor, returning a structured verdict with per-check reason codes, and enforces a `pki.trust` anchor's per-purpose distrust-after dates and delegator purposes via `checkPurpose`; `crlChecker` supplies CRL-based revocation — including partitioned/sharded CRLs, whose §6.3.3 Distribution Point ↔ IDP correspondence lets a corresponding full-reason shard establish non-revocation — and `ocspChecker` supplies OCSP-based revocation (RFC 6960 — CertID binding, responder authorization, signature, currency) over the same pluggable hook. Pure and re-entrant, fail-closed — `validate`, `crlChecker`, `ocspChecker` |
+| `pki.x509` | X.509 certificate issuance (RFC 5280 §4) — `sign(spec, issuer, opts)` builds and signs a certificate: a `spec` of subject (a common-name string, an array of RDNs, or raw Name DER), the public key being certified, the validity window, an optional serial, and an optional `extensions` object; an `issuer` that is a key alone (self-signed — issuer equals subject, signed with that key) or a name + public key + key, or an issuing certificate + key (CA-signed). The signature algorithm is resolved from the signing key through the shared registry, so RSA (PKCS#1 v1.5 / PSS via `opts.pss`), ECDSA P-256/384/521, Ed25519, Ed448, ML-DSA-44/65/87, the twelve SLH-DSA sets, and the composite arms all issue without a per-algorithm branch. It encodes basic constraints, key usage, extended key usage, subject and authority key identifiers (the SKI auto-derived by SHA-1 of the subject key), subject alternative names, and certificate policies from the spec — any other extension supplied as pre-encoded DER — derives the version from the field set, and enforces the serial bounds, the UTCTime/GeneralizedTime cutover, the DER default omissions, and the CA cross-field rules; a violation throws a typed `CertificateError`. Returns DER, or a PEM `CERTIFICATE` with `opts.pem`; every arm is independently verified by OpenSSL. Parsing stays at `pki.schema.x509.parse` — `sign` |
 | `pki.cms` | RFC 5652 §5 CMS SignedData signing + signature verification — `sign(content, signers, opts)` produces a SignedData (attached or detached, one or many signers, RSA / RSASSA-PSS / ECDSA / EdDSA, the post-quantum ML-DSA-44/65/87 (RFC 9882) and SLH-DSA (all twelve FIPS 205 sets, RFC 9814), and composite ML-DSA (pairing ML-DSA with a traditional RSA / ECDSA / EdDSA — accepted only when **both** components verify — draft-ietf-lamps-cms-composite-sigs)); it builds the signed attributes (content-type, message-digest, signing-time) as canonical DER, signs the exact §5.4 preimage, and emits a DER `Buffer` or PEM. `verify(input, opts)` parses a SignedData over the strict `pki.schema.cms` codec, locates each SignerInfo's signer certificate by its issuerAndSerialNumber or subjectKeyIdentifier, and checks the signature over the exact §5.4 preimage: when signed attributes are present it confirms the message-digest attribute equals the content digest and verifies over the DER re-encoding of the SignedAttributes (the on-wire `[0]` tag replaced by a universal SET OF), otherwise directly over the content. It returns a per-signer verdict with the matched signer certificate; it does not chain that certificate to a trust anchor — that is the caller's step through `pki.path.validate`. **Content encryption** (RFC 5652/5083/5084/9629): `encrypt(content, recipients, opts)` produces an EnvelopedData, AuthEnvelopedData (AES-GCM, the authenticated default), or EncryptedData — recipients auto-dispatch off the certificate key to key-transport (RSAES-OAEP; v1.5 never emitted), key-agreement (ephemeral-static ECDH over P-256/384/521 with the X9.63 KDF, and X25519/X448 with HKDF), symmetric key-wrap, password (PBKDF2 + RFC 3211 PWRI-KEK), or the post-quantum ML-KEM KEMRecipientInfo (RFC 9629/9936) — one fresh content key wrapped for every recipient. `decrypt(input, keyMaterial, opts)` recovers the content through the matching arm and returns it with an `authenticated` flag; every secret-dependent failure collapses to one uniform `cms/decrypt-failed` verdict (Bleichenbacher / EFAIL / password-oracle freedom), and PKCS#1 v1.5 is decrypt-only under the RFC 3218 implicit-rejection countermeasure. **Compression** (RFC 3274): `compress(content, opts)` / `decompress(input, opts)` produce and consume a CompressedData (ZLIB, version 0, id-alg-zlibCompress); decompress bounds the uncompressed output at 16 MiB and stops before it is materialized, so a decompression bomb fails closed as `cms/decompress-too-large` — a size transform with no integrity/confidentiality (RFC 8551 §2.4.5). Fail-closed with typed `cms/*` errors — `sign`, `verify`, `encrypt`, `decrypt`, `compress`, `decompress` |
 | `pki.smime` | RFC 8551 S/MIME message assembly, verification, encryption, and compression over the CMS layer — `sign(content, signers, opts)` wraps a MIME entity as a signed S/MIME message in either form: `multipart/signed` (clear-signed — the content stays readable in any MUA, a detached CMS SignedData rides alongside as `application/pkcs7-signature` with a matching `micalg`) or `application/pkcs7-mime; smime-type=signed-data` (opaque — the whole entity is a base64 CMS SignedData). The signed bytes are the entity's RFC 8551 §3.1.1 canonical form (CRLF line endings); `verify(message, opts)` unwraps both forms and recomputes over the same canonicalizer, so a transport that re-wraps line endings still verifies and a tampered part fails. `encrypt(content, recipients, opts)` envelopes a MIME entity as an opaque `application/pkcs7-mime` message and `decrypt(message, keyMaterial, opts)` opens one — `smime-type=authEnveloped-data` (AES-GCM, confidentiality and integrity, the default) or `smime-type=enveloped-data` (AES-CBC, confidentiality only, so `decrypt` reports `authenticated: false`, the §3.3 no-integrity caveat); the `smime-type` is derived from the CMS body, not the header, and decryption is fail-closed and oracle-free. The crypto is entirely `pki.cms.sign` / `verify` / `encrypt` / `decrypt` — any RSA / RSASSA-PSS / ECDSA / EdDSA / ML-DSA / SLH-DSA signer and any RSA-OAEP / ECDH / X25519 / X448 / AES-KW / PBKDF2 / ML-KEM recipient carries through (algorithm-agnostic). Like `cms.verify`, `verify` returns the per-signer cryptographic verdict plus the recovered content; chaining a signer to a trust anchor is the caller's `pki.path.validate` step. `compress(content, opts)` / `decompress(message, opts)` add the opaque `application/pkcs7-mime; smime-type=compressed-data; name=smime.p7z` frame (RFC 8551 §3.6, RFC 3274) — a size transform with no integrity/confidentiality (§2.4.5), decompress bounded against a bomb; the recovered content, which may itself be signed or enveloped, is returned for the caller to re-verify. Bidirectionally interoperable with `openssl smime` / `openssl cms`. Fail-closed with typed `smime/*` errors — `sign`, `verify`, `encrypt`, `decrypt`, `compress`, `decompress` |
 | `pki.tsp` | RFC 3161 Time-Stamp Protocol — `sign(messageImprint, tsa, opts)` produces a TimeStampToken: a CMS SignedData (over `pki.cms.sign`) whose content is a `TSTInfo` carrying the timestamped message imprint, the TSA policy, a serial number, and `genTime` (with optional accuracy / nonce / ordering), plus the RFC 3161 §2.4.2 signing-certificate attribute binding the token to the TSA certificate (SHA-2 imprints, any `pki.cms.sign` TSA key). `request` / `parseRequest` build and parse the TimeStampReq a client sends (imprint, requested policy, nonce, certReq), `response` / `parseResponse` the TimeStampResp a TSA returns — a granted status wrapping a token, or a rejection with PKIStatus and failure info, the §2.4.2 status↔token coupling enforced in both directions. `verify(token, data, opts)` verifies a token fail-closed: the CMS signature over the exact signed bytes, the message imprint recomputed from the data, the TSTInfo content type, the ESSCertID(V2) binding to the TSA certificate, the §2.3 critical timeStamping-only extendedKeyUsage, the request nonce when used, and — with a trust anchor supplied — full certification-path validation of the TSA certificate at the token's `genTime`, returning `{ valid, genTime, serialNumber, tstInfo, … }` — `sign`, `request`, `parseRequest`, `response`, `parseResponse`, `verify` |

package/index.js

@@ -40,6 +40,7 @@ var cms       = require("./lib/cms-verify");
 var smime     = require("./lib/smime");
 var tsp       = require("./lib/tsp-sign");
 var ocsp      = require("./lib/ocsp");
+var x509      = require("./lib/x509-sign");
 var merkle    = require("./lib/merkle");
 var shbs      = require("./lib/shbs");
 var hpke      = require("./lib/hpke");
@@ -81,6 +82,11 @@ module.exports = {
   smime:     smime,
   tsp:       tsp,
   ocsp:      ocsp,
+  // `x509` is the certificate-issuance producing side -- pki.x509.sign builds and
+  // signs an X.509 certificate (RFC 5280 sec. 4), self-signed or CA-signed, over any
+  // signature algorithm the registry resolves (RSA/ECDSA/EdDSA/ML-DSA/SLH-DSA/composite).
+  // Parsing lives at pki.schema.x509.parse.
+  x509:      x509,
   // `merkle` is the RFC 6962 / RFC 9162 Merkle-tree proof-verification core --
   // pki.merkle.leafHash / nodeHash / emptyRootHash build the domain-separated
   // (0x00 leaf / 0x01 node) SHA-256 tree hashes; pki.merkle.verifyInclusion and

package/lib/asn1-der.js

@@ -937,6 +937,24 @@ var build = {
     }
     return _universal(TAGS.BIT_STRING, false, Buffer.concat([Buffer.from([u]), body]));
   },
+  // A minimal DER NamedBitList BIT STRING (X.690 sec. 11.2.2): the asserted `positions` (0-based bit
+  // indices, 0 = the MSB of the first octet) with every trailing zero bit removed and the unused-bit
+  // count set below the last set bit. The single home the keyUsage / PKIFailureInfo / any named-bit
+  // encoder composes, so the minimal-encoding rule lives once (the CHECK side is
+  // schema.assertMinimalNamedBits). No bits asserted -> the empty BIT STRING.
+  namedBitString: function (positions) {
+    if (!Array.isArray(positions)) throw new Asn1Error("asn1/bad-bit-string", "namedBitString requires an array of bit positions");
+    var hi = -1, i, p;
+    for (i = 0; i < positions.length; i++) {
+      p = positions[i];
+      if (typeof p !== "number" || !isFinite(p) || p < 0 || (p | 0) !== p) throw new Asn1Error("asn1/bad-bit-string", "a named-bit position must be a non-negative integer");
+      if (p > hi) hi = p;
+    }
+    if (hi < 0) return build.bitString(Buffer.alloc(0), 0);
+    var buf = Buffer.alloc((hi >> 3) + 1);
+    for (i = 0; i < positions.length; i++) { p = positions[i]; buf[p >> 3] |= 0x80 >> (p & 7); }
+    return build.bitString(buf, 7 - (hi & 7));
+  },
   utf8:     function (s) { return _universal(TAGS.UTF8_STRING, false, Buffer.from(String(s), "utf8")); },
   ia5:      function (s) {
     // Validate the INPUT code points, not the latin1 output bytes: latin1

package/lib/schema-attrcert.js

@@ -281,7 +281,24 @@ var ATTRIBUTE_CERTIFICATE = pkix.signedEnvelope(NS, ACINFO, {
     // kept stable for consumers keying off `form`.
     var issuer = { form: "v2Form", v2Form: acinfo.fields.issuer.value.result, v1Form: null };
 
+    // RFC 5755 sec. 4.4 -- decode each attribute's value(s) additively: a recognized attribute type
+    // gains `decoded` (parallel to `values`); an unrecognized type falls back to { opaque, bytes } so
+    // the parse never fails on an unknown attribute, and a recognized-but-malformed value fails closed.
+    var attributes = acinfo.fields.attributes.value.result;
+    attributes.forEach(function (a) {
+      var dec = _ATTR_VALUE_DECODERS[a.type];
+      a.decoded = a.values.map(function (v) { return dec ? dec(v) : { opaque: true, bytes: v }; });
+    });
+
+    // RFC 5755 sec. 4.3 -- decode each AC extension additively (extensions[i].decoded), same opaque
+    // fallback + fail-closed-on-malformed contract as the attributes above.
     var extField = acinfo.fields.extensions;
+    var extensions = (extField && extField.present) ? extField.value.result : [];
+    extensions.forEach(function (x) {
+      var dec = _AC_EXT_DECODERS[x.oid];
+      x.decoded = dec ? dec(x.value) : { opaque: true, bytes: x.value };
+    });
+
     return {
       version:               acinfo.fields.version.value,     // 2
       holder:                acinfo.fields.holder.value.result,
@@ -291,9 +308,9 @@ var ATTRIBUTE_CERTIFICATE = pkix.signedEnvelope(NS, ACINFO, {
       serialNumber:          acinfo.fields.serialNumber.value,
       serialNumberHex:       sc.toString("hex"),
       validity:              acinfo.fields.attrCertValidityPeriod.value.result,
-      attributes:            acinfo.fields.attributes.value.result,
+      attributes:            attributes,
       issuerUniqueID:        acinfo.fields.issuerUniqueID.present ? acinfo.fields.issuerUniqueID.value : null,
-      extensions:            (extField && extField.present) ? extField.value.result : [],
+      extensions:            extensions,
       tbsBytes:              e.tbsBytes,
       signatureValue:        e.signatureValue,
     };
@@ -417,6 +434,238 @@ function matchesV1(root) {
   return schema.isUniversal(k[1], TAGS.SEQUENCE);
 }
 
+// ---- RFC 5755 sec. 4.4 attribute-value decoders ----------------------
+// A per-attribute-type decoder table (mirroring pkix.certExtensionDecoders): each takes the raw
+// AttributeValue TLV Buffer and returns a structured value, throwing a typed attrcert/bad-* error on
+// any non-conformant shape. Composes pkix's shared imperative helpers + generalName/generalNames.
+// A single GeneralName decodes as the walk OBJECT itself (gn.tagNumber / gn.value); generalNames
+// (plural) returns { names:[...] } on .result.
+var _AV = pkix._decodeHelpers(NS);
+var _decodeTop = _AV.decodeTop, _seqChildren = _AV.seqChildren, _readInt = _AV.readInt, _Oav = _AV.O;
+var _GN = pkix.generalName(NS, { decodeValue: true, code: "attrcert/bad-general-name" });
+var _GNS_0 = pkix.generalNames(NS, { implicitTag: 0, decodeValue: true, code: "attrcert/bad-general-names" });
+function _isCtx(node, n) { return node && node.tagClass === "context" && node.tagNumber === n; }
+function _isU(node, tag) { return node && node.tagClass === "universal" && node.tagNumber === tag; }
+function _oneGN(node, code) {
+  if (!_isCtx(node, 0) && !_isCtx(node, 1) && !_isCtx(node, 2) && !_isCtx(node, 3) &&
+      !_isCtx(node, 4) && !_isCtx(node, 5) && !_isCtx(node, 6) && !_isCtx(node, 7) && !_isCtx(node, 8)) {
+    throw NS.E(code, "a GeneralName must be a context-tagged [0]..[8] CHOICE alternative");
+  }
+  var gn = schema.walk(_GN, node, NS);
+  return { tagNumber: gn.tagNumber, value: gn.value };
+}
+
+// SvceAuthInfo ::= SEQUENCE { service GeneralName, ident GeneralName, authInfo OCTET STRING OPTIONAL }
+// -- authenticationInfo (sec. 4.4.1) allows authInfo; accessIdentity (sec. 4.4.2) MUST omit it.
+function _svceAuthInfo(authInfoAllowed, code) {
+  return function (buf) {
+    var kids = _seqChildren(buf, code, "SvceAuthInfo");
+    if (kids.length < 2 || kids.length > 3) throw NS.E(code, "SvceAuthInfo must be a SEQUENCE { service, ident, authInfo? }");
+    var service = _oneGN(kids[0], code);
+    var ident = _oneGN(kids[1], code);
+    var authInfo = null;
+    if (kids.length === 3) {
+      if (!authInfoAllowed) throw NS.E(code, "this attribute must not carry authInfo (RFC 5755 sec. 4.4.2)");
+      if (!_isU(kids[2], TAGS.OCTET_STRING)) throw NS.E(code, "SvceAuthInfo authInfo must be an OCTET STRING");
+      authInfo = Buffer.concat([asn1.read.octetString(kids[2])]);
+    }
+    return { service: service, ident: ident, authInfo: authInfo };
+  };
+}
+
+// IetfAttrSyntax ::= SEQUENCE { policyAuthority [0] IMPLICIT GeneralNames OPTIONAL,
+//   values SEQUENCE OF CHOICE { octets OCTET STRING, oid OBJECT IDENTIFIER, string UTF8String } }
+function _ietfAttrSyntax(buf) {
+  var C = "attrcert/bad-ietf-attr";
+  var kids = _seqChildren(buf, C, "IetfAttrSyntax");
+  if (!kids.length || kids.length > 2) throw NS.E(C, "IetfAttrSyntax must be a SEQUENCE { policyAuthority [0]?, values }");
+  var policyAuthority = null, i = 0;
+  if (_isCtx(kids[0], 0)) { policyAuthority = schema.walk(_GNS_0, kids[0], NS).result; i = 1; }
+  var valuesNode = kids[i];
+  if (!valuesNode || !_isU(valuesNode, TAGS.SEQUENCE) || !valuesNode.children || !valuesNode.children.length) {
+    throw NS.E(C, "IetfAttrSyntax values must be a non-empty SEQUENCE OF value");
+  }
+  if (i + 1 !== kids.length) throw NS.E(C, "IetfAttrSyntax has unexpected trailing fields (a [0] must precede values)");
+  var kinds = {};
+  var values = valuesNode.children.map(function (v) {
+    if (_isU(v, TAGS.OCTET_STRING)) { kinds.octets = true; return { kind: "octets", value: Buffer.concat([asn1.read.octetString(v)]) }; }
+    if (_isU(v, TAGS.OBJECT_IDENTIFIER)) { kinds.oid = true; return { kind: "oid", value: asn1.read.oid(v) }; }
+    if (_isU(v, TAGS.UTF8_STRING)) { kinds.string = true; return { kind: "string", value: asn1.read.string(v) }; }
+    throw NS.E(C, "IetfAttrSyntax value must be an OCTET STRING, OBJECT IDENTIFIER, or UTF8String");
+  });
+  return { policyAuthority: policyAuthority, values: values, homogeneous: Object.keys(kinds).length === 1 };
+}
+
+// RoleSyntax ::= SEQUENCE { roleAuthority [0] IMPLICIT GeneralNames OPTIONAL, roleName [1] EXPLICIT GeneralName }
+function _role(buf) {
+  var C = "attrcert/bad-role";
+  var kids = _seqChildren(buf, C, "RoleSyntax");
+  if (!kids.length || kids.length > 2) throw NS.E(C, "RoleSyntax must be a SEQUENCE { roleAuthority [0]?, roleName [1] }");
+  var roleAuthority = null, i = 0;
+  if (_isCtx(kids[0], 0)) { roleAuthority = schema.walk(_GNS_0, kids[0], NS).result; i = 1; }
+  var rn = kids[i];
+  if (!_isCtx(rn, 1) || !rn.children || rn.children.length !== 1) throw NS.E(C, "RoleSyntax roleName must be an EXPLICIT [1] wrapping exactly one GeneralName");
+  if (i + 1 !== kids.length) throw NS.E(C, "RoleSyntax has unexpected trailing fields");
+  return { roleAuthority: roleAuthority, roleName: _oneGN(rn.children[0], C) };
+}
+
+// Clearance ::= SEQUENCE { policyId OBJECT IDENTIFIER, classList ClassList DEFAULT {unclassified},
+//   securityCategories SET OF SecurityCategory OPTIONAL }.
+// ClassList ::= BIT STRING { unmarked(0), unclassified(1), restricted(2), confidential(3), secret(4), topSecret(5) }.
+var _CLASSLIST_NAMES = ["unmarked", "unclassified", "restricted", "confidential", "secret", "topSecret"];
+function _decodeClassList(node, C) {
+  var bs;
+  try { bs = asn1.read.bitString(node); } catch (e) { throw NS.E(C, "Clearance classList must be a BIT STRING", e); }
+  schema.assertMinimalNamedBits(bs.unusedBits, bs.bytes, function (m) { throw NS.E(C, m); });
+  var names = [], flags = {}, reserved = [];
+  var total = bs.bytes.length * 8 - bs.unusedBits;
+  for (var bit = 0; bit < total; bit++) {
+    if ((bs.bytes[bit >> 3] & (0x80 >> (bit & 7))) === 0) continue;
+    if (bit < _CLASSLIST_NAMES.length) { names.push(_CLASSLIST_NAMES[bit]); flags[_CLASSLIST_NAMES[bit]] = true; }
+    else reserved.push(bit);
+  }
+  return { names: names, flags: flags, reservedBits: reserved };
+}
+// SecurityCategory ::= SEQUENCE { type [0] IMPLICIT OBJECT IDENTIFIER, value [1] EXPLICIT ANY }.
+function _securityCategory(node, C) {
+  if (!_isU(node, TAGS.SEQUENCE) || !node.children || node.children.length !== 2) throw NS.E(C, "a SecurityCategory must be a SEQUENCE of a type and a value");
+  var typeNode = node.children[0], valueNode = node.children[1];
+  if (!_isCtx(typeNode, 0) || typeNode.children) throw NS.E(C, "SecurityCategory type must be a primitive [0] IMPLICIT OBJECT IDENTIFIER");
+  var type; try { type = asn1.decodeOidContent(typeNode.content); } catch (e) { throw NS.E(C, "SecurityCategory type is not a valid OBJECT IDENTIFIER", e); }
+  if (!_isCtx(valueNode, 1) || !valueNode.children || valueNode.children.length !== 1) throw NS.E(C, "SecurityCategory value must be an EXPLICIT [1] wrapping one element");
+  return { type: type, valueBytes: Buffer.concat([valueNode.children[0].bytes]) };
+}
+function _clearance(buf) {
+  var C = "attrcert/bad-clearance";
+  var kids = _seqChildren(buf, C, "Clearance");
+  if (!kids.length || kids.length > 3) throw NS.E(C, "Clearance must be a SEQUENCE { policyId, classList?, securityCategories? }");
+  if (!_isU(kids[0], TAGS.OBJECT_IDENTIFIER)) throw NS.E(C, "Clearance policyId must be an OBJECT IDENTIFIER");
+  var policyId; try { policyId = asn1.read.oid(kids[0]); } catch (e) { throw NS.E(C, "Clearance policyId must be an OBJECT IDENTIFIER", e); }
+  var classList = { names: ["unclassified"], flags: { unclassified: true }, reservedBits: [] }, i = 1;   // DEFAULT {unclassified}
+  if (kids[i] && _isU(kids[i], TAGS.BIT_STRING)) {
+    classList = _decodeClassList(kids[i], C);
+    if (classList.names.length === 1 && classList.flags.unclassified && !classList.reservedBits.length) {
+      throw NS.E(C, "Clearance classList equal to the DEFAULT {unclassified} must be omitted (non-canonical DER)");
+    }
+    i++;
+  }
+  var securityCategories = null;
+  if (kids[i]) {
+    var setNode = kids[i];
+    if (!_isU(setNode, TAGS.SET) || !setNode.children || !setNode.children.length) throw NS.E(C, "Clearance securityCategories must be a non-empty SET OF SecurityCategory");
+    securityCategories = setNode.children.map(function (categoryNode) { return _securityCategory(categoryNode, C); });
+    i++;
+  }
+  if (i !== kids.length) throw NS.E(C, "Clearance has fields out of order or unexpected trailing fields");
+  return { policyId: policyId, classList: classList, securityCategories: securityCategories };
+}
+
+var _ATTR_VALUE_DECODERS = {};
+_ATTR_VALUE_DECODERS[_Oav("role")] = _role;
+_ATTR_VALUE_DECODERS[_Oav("clearance")] = _clearance;
+// RFC 5755 sec. 4.4.6 requires decoding the legacy RFC 3281 id-at-clearance too (the X.501
+// selected-attribute-types arc, an alias of "clearance" -- built from arcs, never a dotted literal).
+_ATTR_VALUE_DECODERS[oid.fromArcs([2, 5, 1, 5, 55])] = _clearance;
+_ATTR_VALUE_DECODERS[_Oav("authenticationInfo")] = _svceAuthInfo(true, "attrcert/bad-svce-auth-info");
+_ATTR_VALUE_DECODERS[_Oav("accessIdentity")] = _svceAuthInfo(false, "attrcert/bad-access-identity");
+_ATTR_VALUE_DECODERS[_Oav("chargingIdentity")] = _ietfAttrSyntax;
+_ATTR_VALUE_DECODERS[_Oav("group")] = _ietfAttrSyntax;
+
+// ---- RFC 5755 sec. 4.3 AC-extension decoders -------------------------
+// A per-extension-OID decoder table for the AC-specific extensions (kept in the AC domain, not the
+// shared cert-extension table, because Targets/TargetCert reuse the local IssuerSerial). Each takes
+// the raw extnValue content Buffer and returns a structured value, fail-closed with a typed error.
+
+// AuditIdentity ::= OCTET STRING (sec. 4.3.1) -- an opaque audit tag, unconstrained (no SIZE), so an
+// empty OCTET STRING (04 00) is valid; only the OCTET STRING type is enforced.
+function _acAuditIdentity(buf) {
+  var C = "attrcert/bad-audit-identity";
+  var n = _decodeTop(buf, C, "AuditIdentity");
+  if (!_isU(n, TAGS.OCTET_STRING)) throw NS.E(C, "AuditIdentity must be an OCTET STRING");
+  return Buffer.concat([asn1.read.octetString(n)]);
+}
+
+// NoRevAvail syntax is NULL (sec. 4.3.6: '0500'H is the DER encoding) -- the extnValue OCTET STRING
+// contains a DER NULL. An empty or any-other-shape value is malformed and fails closed.
+function _noRevAvail(buf) {
+  var C = "attrcert/bad-no-rev-avail";
+  var n = _decodeTop(buf, C, "NoRevAvail");
+  try { asn1.read.nullValue(n); } catch (e) { throw NS.E(C, "NoRevAvail must be a DER NULL (RFC 5755 sec. 4.3.6)", e); }
+  return { noRevAvail: true };
+}
+
+// Target ::= CHOICE { targetName [0] GeneralName, targetGroup [1] GeneralName, targetCert [2] TargetCert }.
+// [0]/[1] wrap a GeneralName CHOICE (EXPLICIT); [2] is an IMPLICIT TargetCert SEQUENCE.
+function _acTargetCert(node, C) {
+  if (!node.children || !node.children.length) throw NS.E(C, "a targetCert [2] must be a non-empty TargetCert SEQUENCE");
+  var out = { kind: "targetCert", targetCertificate: null, targetName: null, certDigestInfo: null }, i = 0;
+  out.targetCertificate = schema.walk(ISSUER_SERIAL, node.children[i++], NS).result;
+  if (node.children[i] && node.children[i].tagClass === "context") out.targetName = _oneGN(node.children[i++], C);
+  if (node.children[i] && _isU(node.children[i], TAGS.SEQUENCE)) out.certDigestInfo = schema.walk(OBJECT_DIGEST_INFO, node.children[i++], NS).result;
+  if (i !== node.children.length) throw NS.E(C, "a targetCert has unexpected trailing fields");
+  return out;
+}
+function _acTarget(node, C, allowTargetCert) {
+  if (_isCtx(node, 0) || _isCtx(node, 1)) {
+    if (!node.children || node.children.length !== 1) throw NS.E(C, "a Target name must be an EXPLICIT [0]/[1] wrapping one GeneralName");
+    return { kind: node.tagNumber === 0 ? "targetName" : "targetGroup", name: _oneGN(node.children[0], C) };
+  }
+  if (_isCtx(node, 2)) {
+    if (!allowTargetCert) throw NS.E(C, "the targetCert [2] CHOICE MUST NOT be used in proxying information (RFC 5755 sec. 7.4)");
+    return _acTargetCert(node, C);
+  }
+  throw NS.E(C, "a Target must be [0] targetName, [1] targetGroup, or [2] targetCert");
+}
+// Targets ::= SEQUENCE OF Target -- decode a Targets SEQUENCE node into an array of Target.
+function _acDecodeTargets(node, C, allowTargetCert) {
+  if (!_isU(node, TAGS.SEQUENCE) || !node.children || !node.children.length) throw NS.E(C, "Targets must be a non-empty SEQUENCE OF Target");
+  return node.children.map(function (t) { return _acTarget(t, C, allowTargetCert); });
+}
+// Both targetInformation (sec. 4.3.2) and ProxyInfo (sec. 7.4) are SEQUENCE OF Targets -- an outer
+// SEQUENCE whose every element is itself a Targets (SEQUENCE OF Target). A conforming issuer emits one
+// Targets, but users MUST accept several. proxying additionally forbids the targetCert [2] alternative.
+function _seqOfTargets(buf, C, allowTargetCert) {
+  var kids = _seqChildren(buf, C, "SEQUENCE OF Targets");
+  if (!kids.length) throw NS.E(C, "a SEQUENCE OF Targets must be non-empty");
+  return kids.map(function (targetsNode) { return _acDecodeTargets(targetsNode, C, allowTargetCert); });
+}
+function _targetInformation(buf) { return _seqOfTargets(buf, "attrcert/bad-targets", true); }
+function _acProxying(buf) { return _seqOfTargets(buf, "attrcert/bad-proxy-info", false); }
+
+// AAControls ::= SEQUENCE { pathLenConstraint INTEGER (0..MAX) OPTIONAL, permittedAttrs [0] AttrSpec
+//   OPTIONAL, excludedAttrs [1] AttrSpec OPTIONAL, permitUnSpecified BOOLEAN DEFAULT TRUE }.
+// AttrSpec ::= SEQUENCE OF OBJECT IDENTIFIER (the [0]/[1] IMPLICIT tag replaces the SEQUENCE tag).
+function _acAttrSpec(node, C) {
+  if (!node.children) throw NS.E(C, "an AttrSpec must be a SEQUENCE OF OBJECT IDENTIFIER");
+  return node.children.map(function (o) {
+    if (!_isU(o, TAGS.OBJECT_IDENTIFIER)) throw NS.E(C, "an AttrSpec element must be an OBJECT IDENTIFIER");
+    try { return asn1.read.oid(o); } catch (e) { throw NS.E(C, "an AttrSpec element must be an OBJECT IDENTIFIER", e); }
+  });
+}
+function _aaControls(buf) {
+  var C = "attrcert/bad-aa-controls";
+  var kids = _seqChildren(buf, C, "AAControls");
+  if (kids.length > 4) throw NS.E(C, "AAControls has too many fields");
+  var out = { pathLenConstraint: null, permittedAttrs: null, excludedAttrs: null, permitUnSpecified: true }, i = 0;
+  if (kids[i] && _isU(kids[i], TAGS.INTEGER)) { out.pathLenConstraint = guard.range.uint31(_readInt(kids[i], C, "pathLenConstraint"), NS.E, C, "AAControls pathLenConstraint"); i++; }
+  if (kids[i] && _isCtx(kids[i], 0)) { out.permittedAttrs = _acAttrSpec(kids[i], C); i++; }
+  if (kids[i] && _isCtx(kids[i], 1)) { out.excludedAttrs = _acAttrSpec(kids[i], C); i++; }
+  if (kids[i] && _isU(kids[i], TAGS.BOOLEAN)) {
+    var v = asn1.read.boolean(kids[i]);
+    if (v === true) throw NS.E(C, "AAControls permitUnSpecified TRUE equals the DEFAULT and must be omitted (non-canonical DER)");
+    out.permitUnSpecified = v; i++;
+  }
+  if (i !== kids.length) throw NS.E(C, "AAControls has fields out of order or unexpected trailing fields");
+  return out;
+}
+
+var _AC_EXT_DECODERS = {};
+_AC_EXT_DECODERS[_Oav("acAuditIdentity")] = _acAuditIdentity;
+_AC_EXT_DECODERS[_Oav("targetInformation")] = _targetInformation;
+_AC_EXT_DECODERS[_Oav("noRevAvail")] = _noRevAvail;
+_AC_EXT_DECODERS[_Oav("aaControls")] = _aaControls;
+_AC_EXT_DECODERS[_Oav("acProxying")] = _acProxying;
+
 module.exports = {
   parse: parse,
   parseV1: parseV1,

package/lib/schema-pkix.js

@@ -598,13 +598,14 @@ function assertPolicyQualifiers(qNode, fail) {
   });
 }
 
-function certExtensionDecoders(ns) {
-  var GN_SUBTREE = generalName(ns, { decodeValue: true, subtreeBase: true, code: ns.prefix + "/bad-name-constraints" });
-
+// Shared imperative decode helpers for the certExtensionDecoders + attrValueDecoders factories. Both
+// take the caller's ns, so the helpers close over ns.E / ns.oid; extracted once so the two factories
+// share one copy (a per-OID value-decoder body is the identical idiom to a per-OID extension body).
+function _decodeHelpers(ns) {
   function decodeTop(buf, code, what) {
     var n;
     try { n = asn1.decode(buf); }
-    catch (e) { throw ns.E(code, "malformed " + what + " extension value: " + ((e && e.message) || String(e)), e); }
+    catch (e) { throw ns.E(code, "malformed " + what + " value: " + ((e && e.message) || String(e)), e); }
     return n;
   }
   function seqChildren(buf, code, what) {
@@ -618,6 +619,19 @@ function certExtensionDecoders(ns) {
     try { return asn1.read.integer(node); }
     catch (e) { throw ns.E(code, what + " must be an INTEGER", e); }
   }
+  // Resolve a registered OID name -> dotted string, throwing at module load on a typo (a decoder keyed
+  // by an unresolved name would silently never match, treating a real extension/attribute as opaque).
+  function O(nm) {
+    var d = ns.oid.byName(nm);
+    if (typeof d !== "string") throw new TypeError("pki.schema.pkix: " + JSON.stringify(nm) + " is not a registered OID name");
+    return d;
+  }
+  return { decodeTop: decodeTop, seqChildren: seqChildren, readInt: readInt, O: O };
+}
+
+function certExtensionDecoders(ns) {
+  var GN_SUBTREE = generalName(ns, { decodeValue: true, subtreeBase: true, code: ns.prefix + "/bad-name-constraints" });
+  var _h = _decodeHelpers(ns), decodeTop = _h.decodeTop, seqChildren = _h.seqChildren, readInt = _h.readInt, O = _h.O;
 
   // basicConstraints ::= SEQUENCE { cA BOOLEAN DEFAULT FALSE, pathLen INTEGER (0..MAX) OPTIONAL }
   function basicConstraints(buf) {
@@ -910,15 +924,6 @@ function certExtensionDecoders(ns) {
     });
   }
 
-  // byName returns undefined for an unregistered name; keying a decoder row
-  // under "undefined" would silently drop that extension from dispatch (the
-  // consumer would treat the extension as structurally unvalidated / absent),
-  // so a typo'd key-list entry must fail here, at module load.
-  function O(nm) {
-    var d = ns.oid.byName(nm);
-    if (typeof d !== "string") throw new TypeError("certExtensionDecoders: " + JSON.stringify(nm) + " is not a registered OID name");
-    return d;
-  }
   // qcStatements ::= SEQUENCE OF QCStatement (RFC 3739 sec. 3.2.6). QCStatement ::= SEQUENCE {
   // statementId OBJECT IDENTIFIER, statementInfo ANY DEFINED BY statementId OPTIONAL }. Known statementIds
   // (RFC 3739 id-qcs + the ETSI EN 319 412-5 esi4 catalog) decode their statementInfo; an unknown statementId
@@ -1319,6 +1324,7 @@ module.exports = {
   rawNonEmptySequence: rawNonEmptySequence,
   CRL_REASON_NAMES: CRL_REASON_NAMES,
   certExtensionDecoders: certExtensionDecoders,
+  _decodeHelpers: _decodeHelpers,
   attribute: attribute,
   extension: extension,
   extensions: extensions,

package/lib/sigstore.js

@@ -179,7 +179,14 @@ function _chainDers(vm) {
 // Verify a DER ECDSA / Ed25519 signature over `data` under a node public key.
 function _rawVerify(keyObj, data, derSig) {
   var t = keyObj.asymmetricKeyType;
-  if (t === "ed25519" || t === "ed448") return nodeCrypto.verify(null, data, keyObj, derSig);
+  if (t === "ed25519" || t === "ed448") {
+    // Defense in depth at the verify SINK (not only at _pubFromSpki): node imports a low-order /
+    // off-curve OKP key without complaint and such a key verifies a FORGED EdDSA signature, so re-gate
+    // the point here regardless of how keyObj was obtained -- no verify sink may hand an unvalidated
+    // Edwards key to node's verify.
+    edwardsPoint.validateSpki(keyObj.export({ type: "spki", format: "der" }), t === "ed25519" ? 6 : 7, SigstoreError, "sigstore/bad-key");
+    return nodeCrypto.verify(null, data, keyObj, derSig);
+  }
   var crv = keyObj.asymmetricKeyDetails && keyObj.asymmetricKeyDetails.namedCurve;
   var hash = crv === "secp384r1" ? "sha384" : (crv === "secp521r1" ? "sha512" : "sha256");
   return nodeCrypto.verify(hash, data, { key: keyObj, dsaEncoding: "der" }, derSig);

package/lib/tsp-sign.js

@@ -178,15 +178,7 @@ function _failInfoBits(names) {
     if (i == null) throw _err("tsp/bad-input", "unknown PKIFailureInfo name " + JSON.stringify(n) + " (RFC 3161 sec. 2.4.2)");
     return i;
   });
-  if (!idxs.length) return b.bitString(Buffer.alloc(0), 0);          // no bits -> empty BIT STRING
-  // buf is sized to the highest set bit, so its last octet always carries that bit (non-zero) --
-  // there is never a trailing zero octet to strip; only the trailing zero BITS of the last octet
-  // are removed, via the DER unusedBits count (X.690 sec. 11.2.2).
-  var buf = Buffer.alloc((Math.max.apply(null, idxs) >> 3) + 1);
-  idxs.forEach(function (i) { buf[i >> 3] |= 0x80 >> (i & 7); });
-  var unused = 0, last = buf[buf.length - 1];
-  while (unused < 7 && ((last >> unused) & 1) === 0) unused++;       // unusedBits below the lowest set bit
-  return b.bitString(buf, unused);
+  return b.namedBitString(idxs);   // minimal NamedBitList DER (X.690 sec. 11.2.2), empty when no bits set
 }
 
 // Coerce a timeStampToken (a CMS ContentInfo the token producer emits) to DER for embedding in a

package/lib/x509-sign.js

@@ -0,0 +1,637 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+
+/**
+ * @module     pki.x509
+ * @nav        Signing
+ * @title      Certificates
+ * @intro The X.509 certificate-issuance producing side. `pki.x509.sign` builds a `TBSCertificate`,
+ *   signs it, and emits a `Certificate` (RFC 5280 sec. 4) that `pki.schema.x509.parse`,
+ *   `pki.path.validate`, and OpenSSL all accept -- self-signed or CA-signed, over any signature
+ *   algorithm the toolkit registry resolves: RSA (PKCS#1 v1.5 / PSS), ECDSA, EdDSA, ML-DSA, SLH-DSA,
+ *   and the composite (hybrid) arms. Parsing lives at `pki.schema.x509.parse`.
+ * @spec RFC 5280
+ * @card Build and sign an X.509 certificate -- self-signed or CA-signed, over any registry algorithm.
+ */
+//
+// The whole algorithm matrix comes from the shared sign-scheme resolver (the same registry
+// pki.cms.sign / pki.tsp.sign drive), so a new algorithm is a registry row, never a branch here. The
+// TBS + extension DER is hand-assembled through the canonical asn1.build.* layer (the shipped
+// cms/tsp/ocsp producing pattern); the strict schema-x509 decoder round-trips it, and that round-trip
+// -- plus OpenSSL interop -- is the divergence guard.
+
+var nodeCrypto = require("crypto");
+var asn1 = require("./asn1-der");
+var oid = require("./oid");
+var x509 = require("./schema-x509");
+var signScheme = require("./sign-scheme");
+var compositeSig = require("./composite-sig");
+var guard = require("./guard-all");
+var frameworkError = require("./framework-error");
+var schema = require("./schema-engine");
+var pkix = require("./schema-pkix");
+
+var CertificateError = frameworkError.CertificateError;
+// The x509 schema namespace + Name parser -- the SAME RDNSequence parser pki.schema.x509.parse uses, so
+// a raw Name DER is validated fully (structure, DirectoryString types) with the frozen x509/* codes.
+var NS = pkix.makeNS("x509", CertificateError, oid);
+var NAME_SCHEMA = pkix.name(NS);
+var SPKI_SCHEMA = pkix.spki(NS);
+// The SAME RFC 5280 sec. 4.2.1 extension value decoders pki.schema.x509.parse uses, so a recognized
+// pre-encoded (array-form) extension is fully validated with the frozen x509/* codes.
+var EXT_DECODERS = pkix.certExtensionDecoders(NS).byOid;
+var b = asn1.build;
+// Two error factories (cms-sign.js pattern): `_err` takes a full x509/* code; `_signE` prepends the
+// domain so the shared sign-scheme resolver/signer faults keep the x509/* codes. Both are FACTORIES
+// -- guard.time.assertValid and resolveSignScheme invoke them as `E(code, msg)` with no `new`.
+function _err(code, message, cause) { return new CertificateError(code, message, cause); }
+function _signE(kind, message, cause) { return new CertificateError("x509/" + kind, message, cause); }
+function O(n) { return oid.byName(n); }
+
+var OID_SKI = O("subjectKeyIdentifier");
+
+// The recognized keys of the `extensions` spec object; an unknown key is a typo and throws at
+// config-time (a custom extension is passed as pre-encoded DER via the array form).
+var KNOWN_EXT_KEYS = {
+  subjectKeyIdentifier: 1, authorityKeyIdentifier: 1, keyUsage: 1, keyUsageCritical: 1,
+  extendedKeyUsage: 1, extendedKeyUsageCritical: 1, basicConstraints: 1, subjectAltName: 1,
+  certificatePolicies: 1, certificatePoliciesCritical: 1,
+};
+
+// KeyUsage named-bit positions (RFC 5280 sec. 4.2.1.3); contentCommitment is the RFC 5280 rename of
+// the X.509 nonRepudiation bit (1).
+var KU_BIT = {
+  digitalSignature: 0, nonRepudiation: 1, contentCommitment: 1, keyEncipherment: 2,
+  dataEncipherment: 3, keyAgreement: 4, keyCertSign: 5, cRLSign: 6, encipherOnly: 7, decipherOnly: 8,
+};
+
+// ---- distinguished name encoding (RFC 5280 sec. 4.1.2.4) -------------------
+
+// countryName is a PrintableString, emailAddress an IA5String; every other new-certificate attribute
+// is a UTF8String (Teletex/BMP/Universal are backward-compat only and never emitted).
+function _atvString(attrName, value) {
+  if (attrName === "countryName") {
+    // countryName is a PrintableString SIZE(2) -- the two-letter ISO 3166 alpha-2 code (RFC 5280 /
+    // X.520). Reject any other length at config-time.
+    if (String(value).length !== 2) throw _err("x509/bad-name", "countryName must be a two-letter ISO 3166 code (PrintableString SIZE(2))");
+    return b.printable(value);
+  }
+  if (attrName === "emailAddress") return b.ia5(value);
+  return b.utf8(value);
+}
+function _encodeAtv(attrName, value) {
+  if (value == null || value === "") throw _err("x509/bad-name", "the " + attrName + " attribute value must be a non-empty string");
+  var typeOid;
+  try { typeOid = O(attrName); }
+  catch (e) { throw _err("x509/bad-name", "unknown distinguished-name attribute " + JSON.stringify(attrName), e); }
+  var valueTlv;
+  try { valueTlv = _atvString(attrName, value); }
+  catch (e) { if (e instanceof CertificateError) throw e; throw _err("x509/bad-name", "the " + attrName + " value has characters invalid for its string type", e); }
+  return b.sequence([b.oid(typeOid), valueTlv]);
+}
+function _encodeRdn(rdnSpec) {
+  if (!rdnSpec || typeof rdnSpec !== "object" || Buffer.isBuffer(rdnSpec)) throw _err("x509/bad-name", "each RDN must be an object of { attributeName: value }");
+  var keys = Object.keys(rdnSpec);
+  if (!keys.length) throw _err("x509/bad-name", "an RDN must carry at least one attribute");
+  // build.set DER-sorts the AttributeTypeAndValue members (X.690 SET-OF ordering) for a multi-valued RDN.
+  return b.set(keys.map(function (k) { return _encodeAtv(k, rdnSpec[k]); }));
+}
+// A DN spec -> RDNSequence DER. A string is shorthand for a single commonName RDN; a Buffer is raw
+// pre-encoded Name DER (the escape hatch). An empty array yields an empty RDNSequence (a subject MAY
+// be empty with a critical SAN; the issuer non-empty rule is enforced by the caller).
+function _encodeName(spec) {
+  if (Buffer.isBuffer(spec)) { _assertValidNameDer(spec); return spec; }
+  if (typeof spec === "string") spec = [{ commonName: spec }];
+  if (!Array.isArray(spec)) throw _err("x509/bad-name", "a name must be a string, an array of RDNs, or raw Name DER");
+  return b.sequence(spec.map(_encodeRdn));
+}
+// A raw Name DER is embedded verbatim, so validate it is a well-formed RDNSequence -- a SEQUENCE OF
+// RelativeDistinguishedName, each a non-empty SET OF AttributeTypeAndValue{ type OID, value } -- before
+// it is embedded. An empty RDNSequence is permitted (an empty subject; the issuer non-empty rule is
+// enforced separately). asn1.decode already rejects trailing bytes.
+function _assertValidNameDer(der) {
+  var node;
+  try { node = asn1.decode(der); }
+  catch (e) { throw _err("x509/bad-name", "the raw Name DER is not valid DER", e); }
+  // Full validation: walk the raw Name through the exact RDNSequence parser the certificate parser
+  // uses (the SET-OF structure, the AttributeTypeAndValue arity, the DirectoryString value types),
+  // not a partial hand-rolled shape check -- so an embedded raw Name is exactly what parses back.
+  try { schema.walk(NAME_SCHEMA, node, NS); }
+  catch (e) {
+    if (e instanceof CertificateError || (e && e.name === "Asn1Error")) throw e;
+    throw _err("x509/bad-name", "the raw Name DER is not a well-formed distinguished name", e);
+  }
+}
+function _isEmptyName(nameDer) { return asn1.decode(nameDer).children.length === 0; }
+
+// ---- GeneralName encoding (RFC 5280 sec. 4.2.1.6) --------------------------
+
+function _ia5Content(s) {
+  s = String(s);
+  for (var i = 0; i < s.length; i++) {
+    if (s.charCodeAt(i) > 0x7F) throw _err("x509/bad-input", "value requires 7-bit ASCII (IA5String): " + JSON.stringify(s));
+  }
+  return Buffer.from(s, "latin1");
+}
+function _encodeGeneralName(entry) {
+  if (!entry || typeof entry !== "object" || Buffer.isBuffer(entry)) throw _err("x509/bad-input", "a GeneralName must be an object with exactly one name form");
+  var keys = Object.keys(entry);
+  if (keys.length !== 1) throw _err("x509/bad-input", "a GeneralName entry must have exactly one form, got " + keys.length);
+  var k = keys[0], v = entry[k];
+  if (v == null || v === "") throw _err("x509/bad-input", "an empty GeneralName value is not permitted (RFC 5280 sec. 4.2.1.6)");
+  switch (k) {
+    // IMPLICIT [1]/[2]/[6] IA5String -- context-primitive over the raw ASCII content.
+    case "rfc822Name": return b.contextPrimitive(1, _ia5Content(v));
+    case "dNSName": return b.contextPrimitive(2, _ia5Content(v));
+    case "uniformResourceIdentifier": case "uri": return b.contextPrimitive(6, _ia5Content(v));
+    // IMPLICIT [7] OCTET STRING -- 4 octets (IPv4) or 16 (IPv6).
+    case "iPAddress":
+      if (!Buffer.isBuffer(v) || (v.length !== 4 && v.length !== 16)) throw _err("x509/bad-input", "iPAddress must be a 4- or 16-octet Buffer");
+      return b.contextPrimitive(7, v);
+    // [4] Name -- Name is a CHOICE, so the context tag is necessarily EXPLICIT.
+    case "directoryName": return b.explicit(4, _encodeName(v));
+    default: throw _err("x509/bad-input", "unsupported GeneralName form " + JSON.stringify(k) + " (supported: rfc822Name, dNSName, uniformResourceIdentifier, iPAddress, directoryName)");
+  }
+}
+
+// ---- extension-value encoders (the inverse of certExtensionDecoders) -------
+
+function _extKeyUsage(names) {
+  if (!Array.isArray(names) || !names.length) throw _err("x509/bad-input", "keyUsage must assert at least one bit (RFC 5280 sec. 4.2.1.3)");
+  var positions = names.map(function (n) {
+    var pos = KU_BIT[n];
+    if (pos == null) throw _err("x509/bad-input", "unknown keyUsage bit " + JSON.stringify(n));
+    return pos;
+  });
+  return b.namedBitString(positions);   // minimal NamedBitList DER (X.690 sec. 11.2.2)
+}
+function _extExtKeyUsage(names) {
+  if (!Array.isArray(names) || !names.length) throw _err("x509/bad-input", "extendedKeyUsage must list at least one KeyPurposeId");
+  return b.sequence(names.map(function (n) {
+    var purposeOid;
+    try { purposeOid = O(n); }
+    catch (e) { throw _err("x509/bad-input", "unknown extendedKeyUsage purpose " + JSON.stringify(n), e); }
+    return b.oid(purposeOid);
+  }));
+}
+// Validate a basicConstraints spec object before it drives the coherence checks + encoding: cA must be
+// an explicit boolean (a truthy non-true value like 1 or "true" would silently encode as a non-CA),
+// pathLen a non-negative integer, and only cA/pathLen/critical are recognized.
+function _validateBcSpec(bc) {
+  if (bc.cA != null && typeof bc.cA !== "boolean") throw _err("x509/bad-input", "basicConstraints cA must be a boolean");
+  if (bc.critical != null && typeof bc.critical !== "boolean") throw _err("x509/bad-input", "basicConstraints critical must be a boolean");
+  if (bc.pathLen != null) _pathLen(bc.pathLen);
+  Object.keys(bc).forEach(function (k) {
+    if (k !== "cA" && k !== "pathLen" && k !== "critical") throw _err("x509/bad-input", "unknown basicConstraints field " + JSON.stringify(k));
+  });
+}
+function _extBasicConstraints(spec) {
+  var children = [];
+  if (spec.cA === true) children.push(b.boolean(true));   // cA=FALSE omitted (DER DEFAULT)
+  if (spec.pathLen != null) children.push(b.integer(_pathLen(spec.pathLen)));
+  return b.sequence(children);
+}
+function _pathLen(v) {
+  if (typeof v !== "number" || !isFinite(v) || v < 0 || (v | 0) !== v) throw _err("x509/bad-input", "basicConstraints pathLenConstraint must be a non-negative integer");
+  return BigInt(v);
+}
+function _extSki(keyid) { return b.octetString(keyid); }
+function _extAki(keyid) { return b.sequence([b.contextPrimitive(0, keyid)]); }   // keyIdentifier [0] IMPLICIT OCTET STRING
+function _extSan(entries) {
+  if (!Array.isArray(entries) || !entries.length) throw _err("x509/bad-input", "subjectAltName must carry at least one GeneralName");
+  return b.sequence(entries.map(_encodeGeneralName));
+}
+function _extCertPolicies(names) {
+  if (!Array.isArray(names) || !names.length) throw _err("x509/bad-input", "certificatePolicies must list at least one policy OID");
+  var seen = {};
+  return b.sequence(names.map(function (n) {
+    var pOid;
+    try { pOid = O(n); }
+    catch (e) { throw _err("x509/bad-input", "unknown certificate policy " + JSON.stringify(n), e); }
+    if (seen[pOid]) throw _err("x509/bad-input", "duplicate certificate policy " + JSON.stringify(n) + " (RFC 5280 sec. 4.2.1.4)");
+    seen[pOid] = true;
+    return b.sequence([b.oid(pOid)]);   // PolicyInformation ::= SEQUENCE { policyIdentifier OID }
+  }));
+}
+// Wrap an encoded extension value in Extension ::= SEQUENCE { extnID, critical?, extnValue }. A
+// FALSE critical bit is omitted (DER DEFAULT), so the boolean appears only when the extension is critical.
+function _ext(oidStr, critical, valueDer) {
+  var children = [b.oid(oidStr)];
+  if (critical) children.push(b.boolean(true));
+  children.push(b.octetString(valueDer));
+  return b.sequence(children);
+}
+
+// The SHA-1 subjectKeyIdentifier (RFC 5280 sec. 4.2.1.2 method 1): the hash of the subjectPublicKey
+// BIT STRING CONTENT (past the unused-bits octet), NOT the whole SPKI or the whole BIT STRING TLV.
+function _spkiKeyId(spkiDer) {
+  var keyBytes = asn1.read.bitString(asn1.decode(spkiDer).children[1]).bytes;
+  // nosemgrep: pki-weak-hash-md5-sha1 -- RFC 5280 sec. 4.2.1.2 method 1 DEFINES the subjectKeyIdentifier
+  // as the SHA-1 of the subjectPublicKey; this is a key identifier, not a signature or a
+  // collision-resistance use, and the algorithm is fixed by the standard.
+  return nodeCrypto.createHash("sha1").update(keyBytes).digest();
+}
+function _skiValueOf(caCert) {
+  var ext = (caCert.extensions || []).filter(function (e) { return e.oid === OID_SKI; })[0];
+  if (ext) { try { return asn1.read.octetString(asn1.decode(ext.value)); } catch (_e) { /* fall through to re-derive from the issuer SPKI */ } }
+  return null;
+}
+function _skiKeyId(val, spkiDer) {
+  if (Buffer.isBuffer(val)) return val;
+  if (val === true) return _spkiKeyId(spkiDer);
+  throw _err("x509/bad-input", "subjectKeyIdentifier must be true (auto-derive) or a Buffer key id");
+}
+function _akiKeyId(val, ctx) {
+  if (Buffer.isBuffer(val)) return val;
+  if (val === true) {
+    if (ctx.issuerCert) { var ski = _skiValueOf(ctx.issuerCert); if (ski) return ski; }
+    return _spkiKeyId(ctx.issuerSpki);
+  }
+  throw _err("x509/bad-input", "authorityKeyIdentifier must be true (auto-derive from the issuer) or a Buffer key id");
+}
+
+// Build the extensions [3] block from the spec object (or pass through an array of pre-encoded
+// Extension DER buffers). Enforces the RFC 5280 CA cross-field gates, then emits a deterministic order.
+function _buildExtensions(extSpec, ctx) {
+  if (extSpec == null) return [];
+  if (Array.isArray(extSpec)) {
+    // Validate each pre-encoded extension, reject a duplicate extnID (RFC 5280 sec. 4.2 -- at most one
+    // instance of an extension), and decode basicConstraints + keyUsage to apply the same CA
+    // cross-field rules the object form enforces (below), so the array escape hatch cannot bypass them.
+    var seenExt = {}, arrCa = false, arrKeyCertSign = false, arrPathLen = false;
+    var oidBc = O("basicConstraints"), oidKu = O("keyUsage");
+    var arr = extSpec.map(function (e, i) {
+      var der = _reqDer(e, "extension");
+      _assertValidExtension(der, i);
+      var n = asn1.decode(der);
+      var extnId = asn1.read.oid(n.children[0]);
+      if (seenExt[extnId]) throw _err("x509/bad-input", "duplicate extension " + extnId + " in the extensions array (RFC 5280 sec. 4.2 -- at most one instance of an extension)");
+      seenExt[extnId] = true;
+      // Fully validate a RECOGNIZED extension by running its real value decoder (which enforces the
+      // RFC 5280 sec. 4.2.1 rules and throws a typed x509/* on malformed), and take the CA cross-field
+      // inputs from the decoded value; an unrecognized extension is opaque (the caller's own concern).
+      var dec = EXT_DECODERS[extnId];
+      if (dec) {
+        var decoded;
+        try { decoded = dec(asn1.read.octetString(n.children[n.children.length - 1])); }
+        catch (e) {
+          if (e instanceof CertificateError) throw e;
+          throw _err("x509/bad-input", "pre-encoded " + (oid.name(extnId) || extnId) + " extension value is malformed", e);
+        }
+        if (extnId === oidBc) {
+          arrCa = decoded.cA === true; arrPathLen = decoded.pathLenConstraint != null;
+          // RFC 5280 sec. 4.2.1.9 -- a CA's basicConstraints MUST be critical (3 children = an explicit
+          // TRUE critical flag, since _assertValidExtension already rejects an explicit FALSE).
+          if (arrCa && n.children.length !== 3) throw _err("x509/bad-input", "a CA certificate's basicConstraints MUST be critical (RFC 5280 sec. 4.2.1.9)");
+        }
+        else if (extnId === oidKu) { arrKeyCertSign = decoded.keyCertSign === true; }
+      }
+      return b.raw(der);
+    });
+    if (arrKeyCertSign && !arrCa) throw _err("x509/bad-input", "keyUsage keyCertSign requires basicConstraints cA=TRUE (RFC 5280 sec. 4.2.1.3)");
+    if (arrPathLen && (!arrCa || !arrKeyCertSign)) throw _err("x509/bad-input", "basicConstraints pathLenConstraint requires cA=TRUE and keyUsage keyCertSign (RFC 5280 sec. 4.2.1.9)");
+    return arr;
+  }
+  if (typeof extSpec !== "object") throw _err("x509/bad-input", "extensions must be an object or an array of pre-encoded Extension DER");
+  // Reject a typo'd / unsupported extension key at config-time rather than silently dropping it (a
+  // misspelled `keyUsag` would otherwise omit keyUsage). A custom extension goes in the array form.
+  Object.keys(extSpec).forEach(function (k) {
+    if (!KNOWN_EXT_KEYS[k]) throw _err("x509/bad-input", "unknown extension " + JSON.stringify(k) + " in the extensions spec; pass a pre-encoded Extension DER via the array form for a custom extension");
+  });
+
+  var bc = extSpec.basicConstraints;
+  if (bc != null) _validateBcSpec(bc);
+  var caTrue = !!(bc && bc.cA === true);
+  var ku = extSpec.keyUsage;
+  var assertsKeyCertSign = Array.isArray(ku) && ku.indexOf("keyCertSign") >= 0;
+  // RFC 5280 sec. 4.2.1.3 -- keyCertSign requires basicConstraints cA=TRUE.
+  if (assertsKeyCertSign && !caTrue) throw _err("x509/bad-input", "keyUsage keyCertSign requires basicConstraints cA=TRUE (RFC 5280 sec. 4.2.1.3)");
+  // RFC 5280 sec. 4.2.1.9 -- pathLenConstraint requires cA=TRUE AND keyCertSign.
+  if (bc && bc.pathLen != null) {
+    if (!caTrue) throw _err("x509/bad-input", "basicConstraints pathLenConstraint requires cA=TRUE (RFC 5280 sec. 4.2.1.9)");
+    if (!assertsKeyCertSign) throw _err("x509/bad-input", "basicConstraints pathLenConstraint requires keyUsage keyCertSign (RFC 5280 sec. 4.2.1.9)");
+  }
+
+  var out = [];
+  if (extSpec.subjectKeyIdentifier != null) out.push(_ext(O("subjectKeyIdentifier"), false, _extSki(_skiKeyId(extSpec.subjectKeyIdentifier, ctx.spki))));
+  if (extSpec.authorityKeyIdentifier != null) out.push(_ext(O("authorityKeyIdentifier"), false, _extAki(_akiKeyId(extSpec.authorityKeyIdentifier, ctx))));
+  if (ku != null) out.push(_ext(O("keyUsage"), extSpec.keyUsageCritical !== false, _extKeyUsage(ku)));
+  if (extSpec.extendedKeyUsage != null) out.push(_ext(O("extKeyUsage"), !!extSpec.extendedKeyUsageCritical, _extExtKeyUsage(extSpec.extendedKeyUsage)));
+  if (bc != null) {
+    // RFC 5280 sec. 4.2.1.9 -- a CA certificate's basicConstraints MUST be critical.
+    if (bc.cA === true && bc.critical === false) throw _err("x509/bad-input", "a CA certificate's basicConstraints MUST be critical (RFC 5280 sec. 4.2.1.9)");
+    out.push(_ext(O("basicConstraints"), bc.critical !== false, _extBasicConstraints(bc)));
+  }
+  if (extSpec.subjectAltName != null) out.push(_ext(O("subjectAltName"), ctx.subjectEmpty, _extSan(extSpec.subjectAltName)));
+  if (extSpec.certificatePolicies != null) out.push(_ext(O("certificatePolicies"), !!extSpec.certificatePoliciesCritical, _extCertPolicies(extSpec.certificatePolicies)));
+  return out;
+}
+
+// ---- serial + validity + key plumbing --------------------------------------
+
+// RFC 5280 sec. 4.1.2.2 -- a positive, non-zero INTEGER of at most 20 content octets. A random
+// 20-octet positive serial is generated when none is supplied.
+function _serialInteger(serial) {
+  var v;
+  if (serial == null) {
+    var rnd = nodeCrypto.randomBytes(20);
+    rnd[0] &= 0x7f;                      // keep the top bit clear so the magnitude stays <= 20 octets and positive
+    if (rnd[0] === 0) rnd[0] = 0x01;     // never all-zero leading -> non-zero and no redundant sign octet
+    v = BigInt("0x" + rnd.toString("hex"));
+  } else if (typeof serial === "bigint") { v = serial; }
+  else if (typeof serial === "number") { if (!Number.isInteger(serial)) throw _err("x509/bad-serial", "serialNumber must be an integer"); v = BigInt(serial); }
+  else if (typeof serial === "string") { try { v = BigInt(serial); } catch (e) { throw _err("x509/bad-serial", "serialNumber string must be a decimal or 0x-hex integer", e); } }
+  else if (Buffer.isBuffer(serial)) { v = serial.length ? BigInt("0x" + serial.toString("hex")) : 0n; }
+  else { throw _err("x509/bad-serial", "serialNumber must be a BigInt, integer, hex string, or Buffer"); }
+  if (v <= 0n) throw _err("x509/bad-serial", "serialNumber must be a positive integer (RFC 5280 sec. 4.1.2.2)");
+  var tlv = b.integer(v);
+  if (asn1.decode(tlv).content.length > 20) throw _err("x509/bad-serial", "serialNumber must not exceed 20 octets (RFC 5280 sec. 4.1.2.2)");
+  return tlv;
+}
+// RFC 5280 sec. 4.1.2.5 -- UTCTime for 1950..2049, GeneralizedTime otherwise. UTCTime's two-digit year
+// only represents 1950..2049 (sec. 4.1.2.5.1), so a pre-1950 date MUST use GeneralizedTime (the same
+// arm as a date from 2050 on); using UTCTime for a pre-1950 year would be unrepresentable.
+function _timeDer(date, which) {
+  guard.time.assertValid(date, _err, "x509/bad-input", "certificate " + which);
+  var y = date.getUTCFullYear();
+  return (y >= 1950 && y <= 2049) ? b.utcTime(date) : b.generalizedTime(date);
+}
+function _reqDer(v, what) {
+  if (Buffer.isBuffer(v)) return v;
+  if (v instanceof Uint8Array) return Buffer.from(v);
+  throw _err("x509/bad-input", what + " must be a DER Buffer");
+}
+// A well-formed SubjectPublicKeyInfo is a SEQUENCE { algorithm AlgorithmIdentifier, subjectPublicKey
+// BIT STRING }. The subject key is embedded verbatim (b.raw), so reject a malformed one AT ISSUANCE
+// rather than emitting a certificate that fails to parse. (asn1.decode already rejects trailing bytes.)
+function _assertValidSpki(spkiDer, what) {
+  var node;
+  try { node = asn1.decode(spkiDer); }
+  catch (e) { throw _err("x509/bad-input", what + " is not valid DER", e); }
+  // Full validation: run it through the SAME SubjectPublicKeyInfo parser pki.schema.x509.parse uses
+  // (the AlgorithmIdentifier + the subjectPublicKey BIT STRING), not a partial hand-rolled shape check.
+  try { schema.walk(SPKI_SCHEMA, node, NS); }
+  catch (e) {
+    if (e instanceof CertificateError || (e && e.name === "Asn1Error")) throw e;
+    throw _err("x509/bad-input", what + " is not a well-formed SubjectPublicKeyInfo", e);
+  }
+}
+// A well-formed Extension is a SEQUENCE { extnID OID, critical BOOLEAN OPTIONAL, extnValue OCTET
+// STRING }. A pre-encoded (array-form) extension is embedded verbatim, so validate its shape here.
+function _assertValidExtension(der, idx) {
+  var n;
+  try { n = asn1.decode(der); }
+  catch (e) { throw _err("x509/bad-input", "pre-encoded extension [" + idx + "] is not valid DER", e); }
+  if (n.tagNumber !== asn1.TAGS.SEQUENCE || n.tagClass !== "universal" || !n.children || n.children.length < 2 || n.children.length > 3) throw _err("x509/bad-input", "pre-encoded extension [" + idx + "] must be an Extension SEQUENCE { extnID, critical?, extnValue }");
+  try { asn1.read.oid(n.children[0]); }
+  catch (e) { throw _err("x509/bad-input", "pre-encoded extension [" + idx + "] extnID is not an OBJECT IDENTIFIER", e); }
+  if (n.children.length === 3) {
+    var crit;
+    try { crit = asn1.read.boolean(n.children[1]); }
+    catch (e) { throw _err("x509/bad-input", "pre-encoded extension [" + idx + "] critical must be a BOOLEAN", e); }
+    // DER DEFAULT: a FALSE criticality MUST be omitted, so an explicitly-encoded critical=FALSE is
+    // non-canonical (RFC 5280 sec. 4.2 / X.690 sec. 11.5).
+    if (crit !== true) throw _err("x509/bad-input", "pre-encoded extension [" + idx + "] critical=FALSE must be omitted (DER DEFAULT)");
+  }
+  var last = n.children[n.children.length - 1];
+  if (last.tagNumber !== asn1.TAGS.OCTET_STRING || last.tagClass !== "universal") throw _err("x509/bad-input", "pre-encoded extension [" + idx + "] extnValue must be an OCTET STRING");
+}
+// Synthesize the parsed-cert shape resolveSignScheme reads (it only needs subjectPublicKeyInfo.algorithm)
+// from a raw SPKI DER: { algorithm: { oid, parameters } }. `parameters` is the raw params TLV (or undefined).
+function _certLikeFromSpki(spkiDer) {
+  var spki = asn1.decode(spkiDer);
+  if (!spki.children || !spki.children.length) throw _err("x509/bad-input", "the signing key SPKI is not a SubjectPublicKeyInfo");
+  var alg = spki.children[0];
+  var keyOid;
+  try { keyOid = asn1.read.oid(alg.children[0]); }
+  catch (e) { throw _err("x509/bad-input", "the signing key SPKI algorithm is not an OID", e); }
+  return { subjectPublicKeyInfo: { algorithm: { oid: keyOid, parameters: alg.children.length > 1 ? alg.children[1].bytes : undefined } } };
+}
+// The raw subject Name TLV of a parsed CA certificate (byte-identical, so the child issuer chains to
+// the CA subject exactly). The subject follows the optional version [0], serial, signature, issuer,
+// and validity in the tbsCertificate.
+function _caSubjectBytes(caCert) {
+  var tbs = asn1.decode(caCert.tbsBytes);
+  var hasVersion = tbs.children[0].tagClass === "context" && tbs.children[0].tagNumber === 0;
+  return tbs.children[(hasVersion ? 1 : 0) + 4].bytes;   // [version?] serial(0) sig(1) issuer(2) validity(3) SUBJECT(4)
+}
+// A supplied issuer certificate MUST be a CA that may sign certificates: basicConstraints present AND
+// critical AND cA=TRUE (RFC 5280 sec. 4.2.1.9), and -- when a keyUsage extension is present -- the
+// keyCertSign bit (sec. 4.2.1.3). Refuse a non-CA issuer rather than mint a certificate that will not
+// chain. Returns the issuer's pathLenConstraint (or null) so the caller can honor it.
+function _assertIssuerIsCa(issuerCert) {
+  var exts = issuerCert.extensions || [];
+  function ext(name) { return exts.filter(function (x) { return x.oid === O(name); })[0] || null; }
+  var bcExt = ext("basicConstraints");
+  if (!bcExt) throw _err("x509/bad-input", "the issuer certificate is not a CA -- it has no basicConstraints extension (RFC 5280 sec. 4.2.1.9)");
+  if (bcExt.critical !== true) throw _err("x509/bad-input", "the issuer certificate basicConstraints is not marked critical (RFC 5280 sec. 4.2.1.9 requires it on a CA)");
+  var bc;
+  try { bc = EXT_DECODERS[O("basicConstraints")](bcExt.value); }
+  catch (e) { if (e instanceof CertificateError) throw e; throw _err("x509/bad-input", "the issuer certificate basicConstraints is malformed", e); }
+  if (bc.cA !== true) throw _err("x509/bad-input", "the issuer certificate is not a CA (basicConstraints cA is not TRUE)");
+  var kuExt = ext("keyUsage");
+  if (kuExt) {
+    var ku;
+    try { ku = EXT_DECODERS[O("keyUsage")](kuExt.value); }
+    catch (e) { if (e instanceof CertificateError) throw e; throw _err("x509/bad-input", "the issuer certificate keyUsage is malformed", e); }
+    if (ku.keyCertSign !== true) throw _err("x509/bad-input", "the issuer certificate keyUsage does not assert keyCertSign -- it cannot sign certificates (RFC 5280 sec. 4.2.1.3)");
+  }
+  return bc.pathLenConstraint;   // BigInt-narrowed integer or null
+}
+// The cA flag + pathLenConstraint of the certificate being issued, from either the object or the
+// pre-encoded array extensions form (used to honor a supplied issuer's pathLenConstraint).
+function _issuedCaInfo(extSpec) {
+  if (extSpec == null) return { cA: false, pathLen: null };
+  if (!Array.isArray(extSpec)) {
+    var bc = extSpec.basicConstraints;
+    return { cA: !!(bc && bc.cA === true), pathLen: bc && bc.pathLen != null ? Number(bc.pathLen) : null };
+  }
+  for (var i = 0; i < extSpec.length; i++) {
+    var n = asn1.decode(_reqDer(extSpec[i], "extension"));
+    if (asn1.read.oid(n.children[0]) !== O("basicConstraints")) continue;
+    var dec = EXT_DECODERS[O("basicConstraints")](asn1.read.octetString(n.children[n.children.length - 1]));
+    return { cA: dec.cA === true, pathLen: dec.pathLenConstraint != null ? Number(dec.pathLenConstraint) : null };
+  }
+  return { cA: false, pathLen: null };
+}
+// Confirm the produced signature verifies under the ISSUER public key, so a signing key that does not
+// correspond to it cannot silently yield a certificate that fails to chain. Verifying the actual
+// signature is key-type-agnostic -- it holds for a PKCS#8 key, a WebCrypto CryptoKey, or any signer --
+// where deriving-and-comparing the public key cannot (a non-extractable CryptoKey has no exportable
+// public half). A composite {mldsa, trad} arm is the caller's to pair and is skipped here.
+function _assertCertVerifies(tbsDer, sig, issuerSpki, scheme) {
+  if (scheme.composite) {
+    // Verify BOTH composite component signatures against the composite public key.
+    return compositeSig.compositeVerify(issuerSpki, sig, tbsDer, scheme.composite, CertificateError, "x509/unsupported-algorithm", "x509/bad-input").then(function (r) {
+      if (!r.ok) throw _err("x509/bad-input", "the composite signing key does not correspond to the issuer public key -- the certificate would not chain");
+    });
+  }
+  var pub;
+  try { pub = nodeCrypto.createPublicKey({ key: issuerSpki, format: "der", type: "spki" }); }
+  catch (e) { throw _err("x509/bad-input", "the issuer public key could not be imported for the chain self-check", e); }
+  var s = scheme.sign, ok;
+  try {
+    if (s.name === "ECDSA") ok = nodeCrypto.verify(scheme.digest, tbsDer, { key: pub, dsaEncoding: "der" }, sig);
+    else if (s.name === "RSA-PSS") ok = nodeCrypto.verify(scheme.digest, tbsDer, { key: pub, padding: nodeCrypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: s.saltLength }, sig);
+    else if (s.name === "RSASSA-PKCS1-v1_5") ok = nodeCrypto.verify(scheme.digest, tbsDer, pub, sig);
+    // allow:eddsa-verify-without-loworder-gate -- this is a self-check that OUR just-produced signature
+    // verifies under the issuer key the caller controls, not a security verify of an untrusted EdDSA
+    // signature, so the low-order-point gate (a forged-signature defense) does not apply.
+    else ok = nodeCrypto.verify(null, tbsDer, pub, sig);   // Ed25519 / Ed448 / ML-DSA / SLH-DSA
+  } catch (e) { throw _err("x509/bad-input", "the chain self-check could not run against the issuer public key", e); }
+  if (!ok) throw _err("x509/bad-input", "the signing key does not correspond to the issuer public key -- the certificate would not chain");
+}
+// Does the extensions spec carry a subjectAltName that will be emitted critical? The object form forces
+// SAN critical when the subject is empty (so any subjectAltName qualifies); the pre-encoded array form
+// is decoded to look for an Extension whose extnID is subjectAltName with a TRUE critical flag.
+function _hasCriticalSan(extSpec) {
+  if (extSpec == null) return false;
+  if (!Array.isArray(extSpec)) return !!extSpec.subjectAltName;
+  var sanOid = O("subjectAltName");
+  for (var i = 0; i < extSpec.length; i++) {
+    var n = asn1.decode(_reqDer(extSpec[i], "extension"));
+    if (n.children.length === 3 && asn1.read.oid(n.children[0]) === sanOid && asn1.read.boolean(n.children[1]) === true) return true;
+  }
+  return false;
+}
+
+// ---- the primitive ---------------------------------------------------------
+
+/**
+ * @primitive pki.x509.sign
+ * @signature pki.x509.sign(spec, issuer, opts?) -> Promise<Buffer|string>
+ * @since 0.3.0
+ * @status stable
+ * @spec RFC 5280 sec. 4, RFC 9909, RFC 9814
+ * @defends forged-certificate-issuance (CWE-347)
+ * @related pki.schema.x509.parse, pki.path.validate, pki.cms.sign
+ *
+ * Build, sign, and DER-encode an X.509 certificate. `spec` describes the certificate to issue --
+ * `subject` (a string CN, an array of RDNs, or raw Name DER), `subjectPublicKey` (the SPKI DER of the
+ * key being certified), `notBefore` / `notAfter` (`Date`s), an optional `serialNumber`, and an optional
+ * `extensions` object. `issuer` is the signing side: `{ key }` alone issues a self-signed certificate
+ * (issuer = subject, signed with the subject's own key); `{ name, publicKey, key }` or `{ cert, key }`
+ * issues a CA-signed one. The signature algorithm is resolved from the signing key -- RSA (PKCS#1 v1.5
+ * or PSS via `opts.pss`), ECDSA, EdDSA, ML-DSA, SLH-DSA, or a composite arm -- so every algorithm the
+ * toolkit signs with is available here without a per-algorithm branch.
+ *
+ * The version is derived from the field set (v3 when extensions are present, else v1). Serial bounds
+ * (positive, <= 20 octets), the validity UTCTime/GeneralizedTime cutover, the DER DEFAULT omissions
+ * (v1 tag, `critical=FALSE`, `cA=FALSE`), and the CA cross-field rules (keyCertSign and
+ * pathLenConstraint require cA=TRUE) are all enforced; a violation throws a typed `CertificateError`.
+ *
+ * @opts
+ *   - `pem` (boolean) -- return a PEM `CERTIFICATE` string instead of DER.
+ *   - `pss` (boolean) -- sign an RSA key with RSASSA-PSS rather than PKCS#1 v1.5.
+ *   - `digestAlgorithm` (string) -- override the message digest where the algorithm permits a choice.
+ * @example
+ *   var root = await pki.x509.sign(
+ *     { subject: "Example Root CA", subjectPublicKey: signerSpki,
+ *       notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *       extensions: { basicConstraints: { cA: true }, keyUsage: ["keyCertSign", "cRLSign"], subjectKeyIdentifier: true } },
+ *     { key: signerKeyPkcs8 });
+ *   pki.schema.x509.parse(root).subject.dn;   // "CN=Example Root CA"
+ */
+function sign(spec, issuer, opts) {
+  return Promise.resolve().then(function () { return _sign(spec, issuer, opts); });
+}
+
+function _sign(spec, issuer, opts) {
+  opts = opts || {};
+  if (!spec || typeof spec !== "object" || Buffer.isBuffer(spec)) throw _err("x509/bad-input", "the certificate spec must be an object");
+  issuer = issuer || {};
+  if (issuer.key == null) throw _err("x509/bad-input", "a signing key (issuer.key, a PKCS#8 private key) is required");
+
+  var spki = _reqDer(spec.subjectPublicKey, "spec.subjectPublicKey (the SPKI DER of the certified key)");
+  _assertValidSpki(spki, "spec.subjectPublicKey");
+  var subjectDer = _encodeName(spec.subject == null ? [] : spec.subject);
+  var subjectEmpty = _isEmptyName(subjectDer);
+
+  // Resolve the issuer name + signing-key SPKI. `{ key }` alone -> self-signed.
+  var issuerDer, issuerSpki, issuerCert = null, issuerPathLen = null;
+  var selfSigned = issuer.name == null && issuer.cert == null && issuer.publicKey == null;
+  if (selfSigned) {
+    issuerDer = subjectDer;
+    issuerSpki = spki;
+  } else if (issuer.cert != null) {
+    issuerCert = (Buffer.isBuffer(issuer.cert) || typeof issuer.cert === "string") ? x509.parse(issuer.cert) : issuer.cert;
+    if (!issuerCert || !issuerCert.tbsBytes) throw _err("x509/bad-input", "issuer.cert must be a certificate DER/PEM or a parsed certificate");
+    issuerPathLen = _assertIssuerIsCa(issuerCert);
+    issuerDer = _caSubjectBytes(issuerCert);
+    issuerSpki = issuerCert.subjectPublicKeyInfo.bytes;
+  } else {
+    issuerDer = _encodeName(issuer.name == null ? [] : issuer.name);
+    issuerSpki = _reqDer(issuer.publicKey, "issuer.publicKey (the issuer SPKI DER)");
+    _assertValidSpki(issuerSpki, "issuer.publicKey");
+  }
+  // RFC 5280 sec. 4.1.2.4 -- the issuer MUST be a non-empty distinguished name.
+  if (_isEmptyName(issuerDer)) throw _err("x509/bad-issuer", "issuer must be a non-empty distinguished name");
+
+  // Resolve the signature scheme from the SIGNING key's SPKI algorithm (the whole registry, for free).
+  var scheme = signScheme.resolveSignScheme(_certLikeFromSpki(issuerSpki), { combinedRsaSig: true, pss: opts.pss, digestAlgorithm: opts.digestAlgorithm }, true, _signE);
+
+  var serialTlv = _serialInteger(spec.serialNumber);
+  // Validate both instants, then reject an inverted window before encoding (a notBefore after notAfter
+  // is a nonsensical validity period, RFC 5280 sec. 4.1.2.5).
+  guard.time.assertValid(spec.notBefore, _err, "x509/bad-input", "notBefore");
+  guard.time.assertValid(spec.notAfter, _err, "x509/bad-input", "notAfter");
+  // allow:nan-date-comparison-unguarded -- both operands are guard.time.assertValid'd on the two lines above (an Invalid Date throws before this comparison).
+  if (spec.notBefore.getTime() > spec.notAfter.getTime()) throw _err("x509/bad-input", "notBefore must not be after notAfter (RFC 5280 sec. 4.1.2.5)");
+  var validityDer = b.sequence([_timeDer(spec.notBefore, "notBefore"), _timeDer(spec.notAfter, "notAfter")]);
+
+  var exts = _buildExtensions(spec.extensions, { spki: spki, issuerSpki: issuerSpki, issuerCert: issuerCert, subjectEmpty: subjectEmpty });
+  // RFC 5280 sec. 4.1.2.6 -- an empty subject requires a critical subjectAltName (recognized in both the
+  // object form and a pre-encoded array-form extension).
+  if (subjectEmpty && !_hasCriticalSan(spec.extensions)) {
+    throw _err("x509/bad-input", "an empty subject requires a critical subjectAltName (RFC 5280 sec. 4.1.2.6)");
+  }
+  // Honor a supplied issuer's pathLenConstraint (RFC 5280 sec. 4.2.1.9): a CA certificate issued below
+  // it consumes one unit of path length, so pathLen=0 forbids issuing a CA below it, and an issued CA's
+  // own pathLenConstraint must leave room within the issuer's remaining depth.
+  if (issuerPathLen != null) {
+    var issued = _issuedCaInfo(spec.extensions);
+    // A self-issued CA certificate (subject == issuer, e.g. a CA key rollover) does NOT consume path
+    // length (RFC 5280 sec. 6.1 counts only non-self-issued intermediates), so it is permitted even at
+    // pathLen 0. Compare canonically (sec. 7.1) via the parsed RDN sequences.
+    var selfIssued = guard.name.dnEqual(
+      schema.walk(NAME_SCHEMA, asn1.decode(subjectDer), NS).result.rdns,
+      schema.walk(NAME_SCHEMA, asn1.decode(issuerDer), NS).result.rdns,
+      _err, "x509/bad-input", "issuer/subject DN");
+    if (issued.cA && !selfIssued) {
+      if (issuerPathLen < 1) throw _err("x509/bad-input", "the issuer certificate pathLenConstraint (0) forbids issuing a non-self-issued CA certificate below it (RFC 5280 sec. 4.2.1.9)");
+      if (issued.pathLen != null && issued.pathLen > issuerPathLen - 1) throw _err("x509/bad-input", "the issued CA certificate pathLenConstraint exceeds the issuer's remaining path length (RFC 5280 sec. 4.2.1.9)");
+    }
+  }
+  // Version is derived from the emitted field set (RFC 5280 sec. 4.1.2.1); the builder never emits
+  // unique identifiers, so extensions => v3, otherwise v1 (the [0] tag is omitted under DER DEFAULT).
+  var version = exts.length ? 3 : 1;
+
+  var tbsChildren = [];
+  if (version !== 1) tbsChildren.push(b.explicit(0, b.integer(BigInt(version - 1))));   // v2->INTEGER 1, v3->INTEGER 2
+  tbsChildren.push(serialTlv);
+  tbsChildren.push(scheme.sigAlgId);   // signature == signatureAlgorithm (RFC 5280 sec. 4.1.1.2), single source
+  tbsChildren.push(issuerDer);
+  tbsChildren.push(validityDer);
+  tbsChildren.push(subjectDer);
+  tbsChildren.push(b.raw(spki));
+  if (exts.length) tbsChildren.push(b.explicit(3, b.sequence(exts)));
+  var tbsDer = b.sequence(tbsChildren);
+
+  return signScheme.signOverTbs(scheme, issuer.key, tbsDer, _signE).then(function (sig) {
+    // The signature MUST verify under the issuer public key, or the certificate would not chain (the
+    // composite arm returns a promise; the classical/PQC path throws synchronously on a mismatch).
+    return Promise.resolve(_assertCertVerifies(tbsDer, sig, issuerSpki, scheme)).then(function () {
+      var certDer = b.sequence([tbsDer, scheme.sigAlgId, b.bitString(sig, 0)]);
+      return opts.pem ? x509.pemEncode(certDer, "CERTIFICATE") : certDer;
+    });
+  }, function (e) {
+    // A signing failure at a well-formed tbs is a bad signing key or a key/algorithm mismatch; keep a
+    // typed CertificateError (composite key-shape faults already are), and re-type a raw WebCrypto
+    // rejection to x509/bad-input rather than leaking a DOMException from the boundary.
+    if (e instanceof CertificateError) throw e;
+    throw _err("x509/bad-input", "signing the certificate failed -- the signing key does not match the resolved algorithm or is invalid", e);
+  });
+}
+
+module.exports = { sign: sign };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.2.32",
+  "version": "0.3.0",
   "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:c1caa29b-a81a-443d-9296-76988e159993",
+  "serialNumber": "urn:uuid:6f299c9a-151b-4a48-9580-bc19e1ab66b0",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-16T23:57:14.646Z",
+    "timestamp": "2026-07-17T06:00:11.553Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.2.32",
+      "bom-ref": "@blamejs/pki@0.3.0",
       "type": "application",
       "name": "pki",
-      "version": "0.2.32",
+      "version": "0.3.0",
       "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.2.32",
+      "purl": "pkg:npm/%40blamejs/pki@0.3.0",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.2.32",
+      "ref": "@blamejs/pki@0.3.0",
       "dependsOn": []
     }
   ]