@blamejs/pki 0.2.33 → 0.3.1

package/CHANGELOG.md

@@ -4,6 +4,31 @@ 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.1 — 2026-07-17
+
+pki.csr.sign issues PKCS#10 certification requests -- self-signed by the subject key for proof of possession, over every signature algorithm the toolkit supports.
+
+### Added
+
+- pki.csr.sign(spec, key, opts) builds and signs a PKCS#10 certification request -- self-signed by the subject's own key for proof of possession -- and returns DER, or a PEM CERTIFICATE REQUEST with opts.pem. The subject may be empty; requested v3 extensions (subject alternative names, key usage, extended key usage, basic constraints, certificate policies, subject key identifier, or pre-encoded Extension DER) ride in a PKCS#9 extensionRequest attribute a CA copies into the issued certificate, and an optional challengePassword is carried too. The signing algorithm is resolved from the subject key: RSA PKCS#1 v1.5 / PSS, ECDSA, EdDSA, ML-DSA, SLH-DSA, or a composite arm. Request parsing remains pki.schema.csr.parse.
+
+### Fixed
+
+- The certificate and certification-request distinguished-name and extension encoders now reject an unrecognized attribute, extended-key-usage purpose, or certificate-policy name at build time with a typed error, rather than emitting a malformed object identifier -- an unknown name in a pki.x509.sign or pki.csr.sign spec fails closed instead of producing an unparseable structure.
+
+## v0.3.0 — 2026-07-16
+
+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.

package/README.md

@@ -222,6 +222,8 @@ 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.csr` | PKCS#10 certification-request issuance (RFC 2986 / RFC 2985) — `sign(spec, key, opts)` builds and signs a `CertificationRequest`: a `spec` of subject (a common-name string, an array of RDNs, or raw Name DER; may be empty), the public key being certified, an optional `extensionRequest` (requested v3 extensions — subject alternative names, key usage, extended key usage, basic constraints, certificate policies, subject key identifier, or an array of pre-encoded Extension DER — that a CA copies into the issued certificate), and an optional `challengePassword`. `key` (or `{ key }`) is the subject's own private key: the request is self-signed to prove possession of the private half of `subjectPublicKey`, and that proof is verified before the request is returned (what `openssl req -verify` checks). The signature algorithm is resolved from the subject key, so RSA (PKCS#1 v1.5 / PSS via `opts.pss`), ECDSA, EdDSA, ML-DSA, SLH-DSA, and the composite arms all sign without a per-algorithm branch. Returns DER, or a PEM `CERTIFICATE REQUEST` with `opts.pem`; malformed input throws a typed `CsrError`. Parsing stays at `pki.schema.csr.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,8 @@ 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 csr       = require("./lib/csr-sign");
 var merkle    = require("./lib/merkle");
 var shbs      = require("./lib/shbs");
 var hpke      = require("./lib/hpke");
@@ -81,6 +83,16 @@ 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,
+  // `csr` is the PKCS#10 certification-request producing side -- pki.csr.sign builds and
+  // signs a CertificationRequest (RFC 2986), self-signed by the subject key for proof of
+  // possession, with requested extensions in a PKCS#9 extensionRequest attribute. Parsing
+  // lives at pki.schema.csr.parse.
+  csr:       csr,
   // `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/csr-sign.js

@@ -0,0 +1,209 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+
+/**
+ * @module     pki.csr
+ * @nav        Signing
+ * @title      Certification requests
+ * @intro The PKCS#10 certification-request producing side. `pki.csr.sign` builds a
+ *   `CertificationRequestInfo`, signs it with the SUBJECT's own private key (proof of possession -- a
+ *   CSR has no issuer), and emits a `CertificationRequest` (RFC 2986) that `pki.schema.csr.parse`,
+ *   OpenSSL, and a CA enrollment pipeline all accept. Requested v3 extensions ride in a PKCS#9
+ *   `extensionRequest` attribute (RFC 2985) a CA copies into the issued certificate. Parsing lives at
+ *   `pki.schema.csr.parse`.
+ * @spec RFC 2986
+ * @card Build and sign a PKCS#10 certification request (proof of possession by the subject key).
+ */
+//
+// The signature algorithm resolves from the SUBJECT public key through the shared sign-scheme registry
+// (RSA / ECDSA / EdDSA / ML-DSA / SLH-DSA / composite), so there is no per-algorithm branch here. The
+// distinguished-name / extension / SPKI encoders + the post-sign self-check are the shared lib/pki-build
+// primitives (the same ones pki.x509.sign composes), bound to the csr namespace.
+
+var asn1 = require("./asn1-der");
+var oid = require("./oid");
+var csr = require("./schema-csr");
+var signScheme = require("./sign-scheme");
+var pkix = require("./schema-pkix");
+var pkiBuild = require("./pki-build");
+var frameworkError = require("./framework-error");
+
+var CsrError = frameworkError.CsrError;
+var b = asn1.build;
+function _err(code, message, cause) { return new CsrError(code, message, cause); }
+function _signE(kind, message, cause) { return new CsrError("csr/" + kind, message, cause); }
+function O(n) { return oid.byName(n); }
+
+var NS = pkix.makeNS("csr", CsrError, oid);
+var EXT_DECODERS = pkix.certExtensionDecoders(NS).byOid;
+var _b = pkiBuild.makeBuilder({
+  ErrorClass: CsrError, prefix: "csr", O: O, NS: NS,
+  NAME_SCHEMA: pkix.name(NS), SPKI_SCHEMA: pkix.spki(NS), EXT_DECODERS: EXT_DECODERS,
+});
+
+// The requested-extension object keys (a CSR REQUESTS extensions; it does NOT enforce issuance policy,
+// so there are no CA cross-field gates and no authorityKeyIdentifier auto-derivation).
+var KNOWN_REQ_EXT_KEYS = {
+  subjectAltName: 1, keyUsage: 1, keyUsageCritical: 1, extendedKeyUsage: 1, extendedKeyUsageCritical: 1,
+  basicConstraints: 1, certificatePolicies: 1, certificatePoliciesCritical: 1, subjectKeyIdentifier: 1,
+};
+// challengePassword DirectoryString charset (PrintableString set); anything else uses UTF8String.
+var PRINTABLE_RE = /^[A-Za-z0-9 '()+,\-./:=?]*$/;
+
+// attributes ::= [0] IMPLICIT SET OF Attribute (RFC 2986). The IMPLICIT tag replaces the universal SET,
+// so it is a context-constructed [0] whose DER-sorted members ARE the SET-OF; empty -> A0 00.
+function _implicitSetOf0(members) {
+  return b.contextConstructed(0, Buffer.concat(members.slice().sort(Buffer.compare)));
+}
+
+// The requested v3 Extensions (a bare SEQUENCE OF Extension, RFC 2985 sec. 5.4.2) from the object form,
+// or an array of pre-encoded Extension DER. Reuses the shared extension-value encoders; no CA gates.
+function _buildRequestedExtensions(extSpec, subjectSpki) {
+  if (Array.isArray(extSpec)) {
+    if (!extSpec.length) throw _err("csr/bad-input", "extensionRequest must carry at least one extension");
+    var seen = {};
+    return b.sequence(extSpec.map(function (e, i) {
+      var der = _b.reqDer(e, "extension");
+      _b.assertValidExtension(der, i);
+      var n = asn1.decode(der);
+      var extnId = asn1.read.oid(n.children[0]);
+      if (seen[extnId]) throw _err("csr/bad-input", "duplicate extension " + extnId + " in extensionRequest (RFC 5280 sec. 4.2)");
+      seen[extnId] = true;
+      // Fully validate a RECOGNIZED extension via its real RFC 5280 sec. 4.2.1 value decoder (a malformed
+      // value fails closed with the decoder's typed code); an unrecognized extension stays opaque.
+      var dec = EXT_DECODERS[extnId];
+      if (dec) {
+        try { dec(asn1.read.octetString(n.children[n.children.length - 1])); }
+        catch (err) { if (err instanceof CsrError) throw err; throw _err("csr/bad-input", "pre-encoded " + (oid.name(extnId) || extnId) + " extension value is malformed", err); }
+      }
+      return b.raw(der);
+    }));
+  }
+  if (!extSpec || typeof extSpec !== "object") throw _err("csr/bad-input", "extensionRequest must be an object or an array of pre-encoded Extension DER");
+  Object.keys(extSpec).forEach(function (k) {
+    if (!KNOWN_REQ_EXT_KEYS[k]) throw _err("csr/bad-input", "unknown extensionRequest extension " + JSON.stringify(k) + "; pass a pre-encoded Extension DER via the array form for a custom extension");
+  });
+  var out = [];
+  if (extSpec.subjectKeyIdentifier != null) out.push(_b.ext(O("subjectKeyIdentifier"), false, _b.extSki(_b.skiKeyId(extSpec.subjectKeyIdentifier, subjectSpki))));
+  if (extSpec.keyUsage != null) out.push(_b.ext(O("keyUsage"), extSpec.keyUsageCritical !== false, _b.extKeyUsage(extSpec.keyUsage)));
+  if (extSpec.extendedKeyUsage != null) out.push(_b.ext(O("extKeyUsage"), !!extSpec.extendedKeyUsageCritical, _b.extExtKeyUsage(extSpec.extendedKeyUsage)));
+  if (extSpec.basicConstraints != null) { _b.validateBcSpec(extSpec.basicConstraints); out.push(_b.ext(O("basicConstraints"), extSpec.basicConstraints.critical !== false, _b.extBasicConstraints(extSpec.basicConstraints))); }
+  if (extSpec.subjectAltName != null) out.push(_b.ext(O("subjectAltName"), false, _b.extSan(extSpec.subjectAltName)));
+  if (extSpec.certificatePolicies != null) out.push(_b.ext(O("certificatePolicies"), !!extSpec.certificatePoliciesCritical, _b.extCertPolicies(extSpec.certificatePolicies)));
+  if (!out.length) throw _err("csr/bad-input", "extensionRequest must request at least one extension");
+  return b.sequence(out);
+}
+
+// challengePassword ::= DirectoryString bounded 1..255 (RFC 2985 sec. 5.4.1). PrintableString when the
+// value is in that charset, else UTF8String; never a Teletex/BMP/Universal string for a new value.
+function _challengePassword(pw) {
+  if (typeof pw !== "string" || pw.length < 1 || pw.length > 255) throw _err("csr/bad-input", "challengePassword must be a 1..255 character string (RFC 2985 sec. 5.4.1)");
+  return PRINTABLE_RE.test(pw) ? b.printable(pw) : b.utf8(pw);
+}
+
+/**
+ * @primitive pki.csr.sign
+ * @signature pki.csr.sign(spec, key, opts?) -> Promise<Buffer|string>
+ * @since 0.3.1
+ * @status stable
+ * @spec RFC 2986, RFC 2985
+ * @defends forged-certification-request (CWE-347)
+ * @related pki.schema.csr.parse, pki.x509.sign
+ *
+ * Build, sign, and DER-encode a PKCS#10 certification request. `spec` describes the request -- `subject`
+ * (a common-name string, an array of RDNs, or raw Name DER; MAY be empty), `subjectPublicKey` (the SPKI
+ * DER of the key being certified), and optional `extensionRequest` (requested v3 extensions -- an object
+ * of subjectAltName / keyUsage / extendedKeyUsage / basicConstraints / certificatePolicies /
+ * subjectKeyIdentifier, or an array of pre-encoded Extension DER) and `challengePassword`. `key` (or
+ * `{ key }`) is the SUBJECT's own PKCS#8 private key / WebCrypto CryptoKey -- the request is self-signed
+ * to prove possession of the private half of `subjectPublicKey`, and that proof is verified before the
+ * request is returned. The signature algorithm is resolved from the subject key (RSA PKCS#1 v1.5 or PSS,
+ * ECDSA, EdDSA, ML-DSA, SLH-DSA, or a composite arm). Returns DER, or a PEM `CERTIFICATE REQUEST` with
+ * `opts.pem`. Malformed input throws a typed `CsrError`. Certificate-request parsing is `pki.schema.csr.parse`.
+ *
+ * @opts
+ *   - `pem` (boolean) -- return a PEM `CERTIFICATE REQUEST` 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 req = await pki.csr.sign(
+ *     { subject: "req.example.com", subjectPublicKey: signerSpki,
+ *       extensionRequest: { subjectAltName: [{ dNSName: "req.example.com" }] } },
+ *     { key: signerKeyPkcs8 });
+ *   pki.schema.csr.parse(req).subject.dn;   // "CN=req.example.com"
+ */
+function sign(spec, key, opts) {
+  return Promise.resolve().then(function () { return _sign(spec, key, opts); });
+}
+
+function _sign(spec, key, opts) {
+  opts = opts || {};
+  if (!spec || typeof spec !== "object" || Buffer.isBuffer(spec)) throw _err("csr/bad-input", "the certification-request spec must be an object");
+  // Reject a typo'd spec field at config-time rather than silently dropping it (a misspelled `subjcet`
+  // would otherwise yield an empty-subject request).
+  Object.keys(spec).forEach(function (k) {
+    if (k !== "subject" && k !== "subjectPublicKey" && k !== "extensionRequest" && k !== "challengePassword" && k !== "attributes") throw _err("csr/bad-input", "unknown spec field " + JSON.stringify(k));
+  });
+  // The signing key is the second argument (a PKCS#8 key / CryptoKey / composite key pair), or { key }.
+  var signingKey = (key && typeof key === "object" && !Buffer.isBuffer(key) && !(key instanceof Uint8Array) && key.type == null && "key" in key) ? key.key : key;
+  if (signingKey == null) throw _err("csr/bad-input", "a signing key (the subject's private key) is required");
+
+  var subjectSpki = _b.reqDer(spec.subjectPublicKey, "spec.subjectPublicKey (the SPKI DER of the requested key)");
+  _b.assertValidSpki(subjectSpki, "spec.subjectPublicKey");
+  var subjectDer = _b.encodeName(spec.subject == null ? [] : spec.subject);
+
+  // attributes: extensionRequest + challengePassword + pre-encoded opaque Attribute DER (the escape
+  // hatch). A recognized attribute may appear at most once (RFC 2985 SINGLE VALUE + producer hygiene).
+  var attrs = [], seenAttr = {};
+  function addAttr(attrType, valueTlv) {
+    if (seenAttr[attrType]) throw _err("csr/bad-input", "duplicate " + (oid.name(attrType) || attrType) + " attribute");
+    seenAttr[attrType] = true;
+    attrs.push(b.sequence([b.oid(attrType), b.set([valueTlv])]));   // Attribute ::= SEQUENCE { type, SET OF value }
+  }
+  if (spec.extensionRequest != null) addAttr(O("extensionRequest"), _buildRequestedExtensions(spec.extensionRequest, subjectSpki));
+  if (spec.challengePassword != null) addAttr(O("challengePassword"), _challengePassword(spec.challengePassword));
+  if (spec.attributes != null) {
+    if (!Array.isArray(spec.attributes)) throw _err("csr/bad-input", "spec.attributes must be an array of pre-encoded Attribute DER");
+    spec.attributes.forEach(function (a, i) {
+      var der = _b.reqDer(a, "attribute [" + i + "]");
+      var n;
+      try { n = asn1.decode(der); }
+      catch (e) { throw _err("csr/bad-input", "pre-encoded attribute [" + i + "] is not valid DER", e); }
+      if (n.tagNumber !== asn1.TAGS.SEQUENCE || n.tagClass !== "universal" || !n.children || n.children.length !== 2 || n.children[1].tagNumber !== asn1.TAGS.SET) throw _err("csr/bad-input", "pre-encoded attribute [" + i + "] must be an Attribute SEQUENCE { type OID, SET OF value }");
+      var at;
+      try { at = asn1.read.oid(n.children[0]); }
+      catch (e) { throw _err("csr/bad-input", "pre-encoded attribute [" + i + "] type is not an OBJECT IDENTIFIER", e); }
+      // A type with a dedicated typed spec field must go through that field so its value syntax is always
+      // enforced (RFC 2985 sec. 5.4): the opaque escape hatch is for UNRECOGNIZED attribute types only and
+      // must never carry a recognized type with an unvalidated value the strict parser would then reject.
+      if (at === O("extensionRequest")) throw _err("csr/bad-input", "pass requested extensions via spec.extensionRequest, not a pre-encoded extensionRequest attribute");
+      if (at === O("challengePassword")) throw _err("csr/bad-input", "pass the challenge password via spec.challengePassword, not a pre-encoded challengePassword attribute");
+      // Attribute ::= SEQUENCE { type, values SET SIZE(1..MAX) }: an empty value SET is malformed and the
+      // strict parser rejects it, so reject at build time -- a signed request must always round-trip.
+      if (!n.children[1].children || n.children[1].children.length === 0) throw _err("csr/bad-input", "pre-encoded attribute [" + i + "] value SET must contain at least one value (RFC 2986 SET SIZE(1..MAX))");
+      if (seenAttr[at]) throw _err("csr/bad-input", "duplicate " + (oid.name(at) || at) + " attribute");
+      seenAttr[at] = true;
+      attrs.push(b.raw(der));
+    });
+  }
+
+  // Resolve the signature scheme from the SUBJECT public key (the request proves possession of its private half).
+  var scheme = signScheme.resolveSignScheme(_b.certLikeFromSpki(subjectSpki), { combinedRsaSig: true, pss: opts.pss, digestAlgorithm: opts.digestAlgorithm }, true, _signE);
+
+  // CertificationRequestInfo ::= SEQUENCE { version INTEGER(0), subject, subjectPKInfo, attributes [0] }.
+  var criDer = b.sequence([b.integer(0n), subjectDer, b.raw(subjectSpki), _implicitSetOf0(attrs)]);
+
+  return signScheme.signOverTbs(scheme, signingKey, criDer, _signE).then(function (sig) {
+    // Proof of possession: the signature MUST verify under the subject public key (what openssl req -verify checks).
+    return Promise.resolve(_b.assertSignatureVerifies(criDer, sig, subjectSpki, scheme)).then(function () {
+      var der = b.sequence([criDer, scheme.sigAlgId, b.bitString(sig, 0)]);
+      return opts.pem ? csr.pemEncode(der, "CERTIFICATE REQUEST") : der;
+    });
+  }, function (e) {
+    if (e instanceof CsrError) throw e;
+    throw _err("csr/bad-input", "signing the certification request failed -- the signing key does not match the subject public key or is invalid", e);
+  });
+}
+
+module.exports = { sign: sign };

package/lib/pki-build.js

@@ -0,0 +1,270 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal -- the ENCODE-direction sibling of schema-pkix.js (which is decode-only). `makeBuilder(ctx)`
+// binds a domain namespace once and returns the shared PKIX producing primitives every signer module
+// composes: the distinguished-name encoder, the GeneralName + RFC 5280 sec. 4.2.1 extension-value
+// encoders, the embedded-input validators (a raw Name / a SubjectPublicKeyInfo / a pre-encoded Extension
+// run through the SAME parser the decoder uses), the sign-scheme bridge, and the post-sign signature
+// self-check (the key-match / proof-of-possession verify). Each is parameterized on the CALLER's error
+// class + code prefix, so pki.x509.sign keeps x509/* codes and pki.csr.sign keeps csr/*.
+
+var asn1 = require("./asn1-der");
+var schema = require("./schema-engine");
+var compositeSig = require("./composite-sig");
+var nodeCrypto = require("crypto");
+
+var b = asn1.build;
+
+// 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,
+};
+
+// makeBuilder(ctx) -> the bound producing primitives. ctx = { ErrorClass, prefix, O, NS, NAME_SCHEMA,
+// SPKI_SCHEMA, EXT_DECODERS }. `E(kind, msg, cause)` builds a `<prefix>/<kind>` typed error.
+function makeBuilder(ctx) {
+  var ErrorClass = ctx.ErrorClass, O = ctx.O, NS = ctx.NS;
+  var NAME_SCHEMA = ctx.NAME_SCHEMA, SPKI_SCHEMA = ctx.SPKI_SCHEMA;
+  function E(kind, message, cause) { return new ErrorClass(ctx.prefix + "/" + kind, message, cause); }
+  function code(kind) { return ctx.prefix + "/" + kind; }
+
+  // ---- distinguished name encoding (RFC 5280 sec. 4.1.2.4) ----
+  // countryName is a PrintableString SIZE(2), emailAddress an IA5String; every other new-name attribute
+  // is a UTF8String (Teletex/BMP/Universal are backward-compat only and never emitted).
+  function atvString(attrName, value) {
+    if (attrName === "countryName") {
+      if (String(value).length !== 2) throw E("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 E("bad-name", "the " + attrName + " attribute value must be a non-empty string");
+    // oid.byName returns undefined (does not throw) for an unrecognized name -- reject it explicitly.
+    var typeOid = O(attrName);
+    if (typeOid == null) throw E("bad-name", "unknown distinguished-name attribute " + JSON.stringify(attrName));
+    var valueTlv;
+    try { valueTlv = atvString(attrName, value); }
+    catch (e) { if (e instanceof ErrorClass) throw e; throw E("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 E("bad-name", "each RDN must be an object of { attributeName: value }");
+    var keys = Object.keys(rdnSpec);
+    if (!keys.length) throw E("bad-name", "an RDN must carry at least one attribute");
+    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 (validated through the parser). An empty array yields an empty RDNSequence.
+  function encodeName(spec) {
+    if (Buffer.isBuffer(spec)) { assertValidNameDer(spec); return spec; }
+    if (typeof spec === "string") spec = [{ commonName: spec }];
+    if (!Array.isArray(spec)) throw E("bad-name", "a name must be a string, an array of RDNs, or raw Name DER");
+    return b.sequence(spec.map(encodeRdn));
+  }
+  // Full validation of a raw Name DER: walk it through the exact RDNSequence parser the decoder uses.
+  function assertValidNameDer(der) {
+    var node;
+    try { node = asn1.decode(der); }
+    catch (e) { throw E("bad-name", "the raw Name DER is not valid DER", e); }
+    try { schema.walk(NAME_SCHEMA, node, NS); }
+    catch (e) {
+      if (e instanceof ErrorClass || (e && e.name === "Asn1Error")) throw e;
+      throw E("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 E("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 E("bad-input", "a GeneralName must be an object with exactly one name form");
+    var keys = Object.keys(entry);
+    if (keys.length !== 1) throw E("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 E("bad-input", "an empty GeneralName value is not permitted (RFC 5280 sec. 4.2.1.6)");
+    switch (k) {
+      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));
+      case "iPAddress":
+        if (!Buffer.isBuffer(v) || (v.length !== 4 && v.length !== 16)) throw E("bad-input", "iPAddress must be a 4- or 16-octet Buffer");
+        return b.contextPrimitive(7, v);
+      case "directoryName": return b.explicit(4, encodeName(v));   // Name is a CHOICE -> the context tag is EXPLICIT
+      default: throw E("bad-input", "unsupported GeneralName form " + JSON.stringify(k) + " (supported: rfc822Name, dNSName, uniformResourceIdentifier, iPAddress, directoryName)");
+    }
+  }
+
+  // ---- extension-value encoders (the inverse of certExtensionDecoders) ----
+  function extKeyUsage(names) {
+    if (!Array.isArray(names) || !names.length) throw E("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 E("bad-input", "unknown keyUsage bit " + JSON.stringify(n));
+      return pos;
+    });
+    return b.namedBitString(positions);
+  }
+  function extExtKeyUsage(names) {
+    if (!Array.isArray(names) || !names.length) throw E("bad-input", "extendedKeyUsage must list at least one KeyPurposeId");
+    return b.sequence(names.map(function (n) {
+      var purposeOid = O(n);
+      if (purposeOid == null) throw E("bad-input", "unknown extendedKeyUsage purpose " + JSON.stringify(n));
+      return b.oid(purposeOid);
+    }));
+  }
+  function validateBcSpec(bc) {
+    if (bc.cA != null && typeof bc.cA !== "boolean") throw E("bad-input", "basicConstraints cA must be a boolean");
+    if (bc.critical != null && typeof bc.critical !== "boolean") throw E("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 E("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 E("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 E("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 E("bad-input", "certificatePolicies must list at least one policy OID");
+    var seen = {};
+    return b.sequence(names.map(function (n) {
+      var pOid = O(n);
+      if (pOid == null) throw E("bad-input", "unknown certificate policy " + JSON.stringify(n));
+      if (seen[pOid]) throw E("bad-input", "duplicate certificate policy " + JSON.stringify(n) + " (RFC 5280 sec. 4.2.1.4)");
+      seen[pOid] = true;
+      return b.sequence([b.oid(pOid)]);
+    }));
+  }
+  // Wrap a value in Extension ::= SEQUENCE { extnID, critical?, extnValue }; a FALSE critical is omitted.
+  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): SHA-1 of the subjectPublicKey BIT
+  // STRING CONTENT (past the unused-bits octet), NOT the whole SPKI or the BIT STRING TLV.
+  function spkiKeyId(spkiDer) {
+    var keyBytes = asn1.read.bitString(asn1.decode(spkiDer).children[1]).bytes;
+    // 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.
+    // nosemgrep: pki-weak-hash-md5-sha1
+    return nodeCrypto.createHash("sha1").update(keyBytes).digest();
+  }
+  function skiKeyId(val, spkiDer) {
+    if (Buffer.isBuffer(val)) return val;
+    if (val === true) return spkiKeyId(spkiDer);
+    throw E("bad-input", "subjectKeyIdentifier must be true (auto-derive) or a Buffer key id");
+  }
+
+  // ---- embedded-input validators ----
+  function reqDer(v, what) {
+    if (Buffer.isBuffer(v)) return v;
+    if (v instanceof Uint8Array) return Buffer.from(v);
+    throw E("bad-input", what + " must be a DER Buffer");
+  }
+  // Full validation of an embedded SubjectPublicKeyInfo via the SAME parser the decoder uses.
+  function assertValidSpki(spkiDer, what) {
+    var node;
+    try { node = asn1.decode(spkiDer); }
+    catch (e) { throw E("bad-input", what + " is not valid DER", e); }
+    try { schema.walk(SPKI_SCHEMA, node, NS); }
+    catch (e) {
+      if (e instanceof ErrorClass || (e && e.name === "Asn1Error")) throw e;
+      throw E("bad-input", what + " is not a well-formed SubjectPublicKeyInfo", e);
+    }
+  }
+  // A pre-encoded Extension ::= SEQUENCE { extnID OID, critical BOOLEAN OPTIONAL, extnValue OCTET STRING };
+  // an explicit critical=FALSE is non-canonical (DER DEFAULT) and rejected.
+  function assertValidExtension(der, idx) {
+    var n;
+    try { n = asn1.decode(der); }
+    catch (e) { throw E("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 E("bad-input", "pre-encoded extension [" + idx + "] must be an Extension SEQUENCE { extnID, critical?, extnValue }");
+    try { asn1.read.oid(n.children[0]); }
+    catch (e) { throw E("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 E("bad-input", "pre-encoded extension [" + idx + "] critical must be a BOOLEAN", e); }
+      if (crit !== true) throw E("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 E("bad-input", "pre-encoded extension [" + idx + "] extnValue must be an OCTET STRING");
+  }
+  // Synthesize the parsed-cert shape resolveSignScheme reads (subjectPublicKeyInfo.algorithm) from a raw SPKI.
+  function certLikeFromSpki(spkiDer) {
+    var spki = asn1.decode(spkiDer);
+    if (!spki.children || !spki.children.length) throw E("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 E("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 } } };
+  }
+
+  // Confirm the produced signature verifies under `spki` -- key-type-agnostic (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). This is the x509 chain self-check AND the CSR proof of
+  // possession. Composite verifies both components. Returns a promise for composite, sync-throws for classical.
+  function assertSignatureVerifies(preimage, sig, spki, scheme) {
+    if (scheme.composite) {
+      return compositeSig.compositeVerify(spki, sig, preimage, scheme.composite, ErrorClass, code("unsupported-algorithm"), code("bad-input")).then(function (r) {
+        if (!r.ok) throw E("bad-input", "the composite signing key does not correspond to the public key -- the signature would not verify");
+      });
+    }
+    var pub;
+    try { pub = nodeCrypto.createPublicKey({ key: spki, format: "der", type: "spki" }); }
+    catch (e) { throw E("bad-input", "the public key could not be imported for the signature self-check", e); }
+    var s = scheme.sign, ok;
+    try {
+      if (s.name === "ECDSA") ok = nodeCrypto.verify(scheme.digest, preimage, { key: pub, dsaEncoding: "der" }, sig);
+      else if (s.name === "RSA-PSS") ok = nodeCrypto.verify(scheme.digest, preimage, { 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, preimage, pub, sig);
+      // allow:eddsa-verify-without-loworder-gate -- a self-check that OUR just-produced signature verifies
+      // under the 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, preimage, pub, sig);   // Ed25519 / Ed448 / ML-DSA / SLH-DSA
+    } catch (e) { throw E("bad-input", "the signature self-check could not run against the public key", e); }
+    if (!ok) throw E("bad-input", "the signing key does not correspond to the public key -- the signature would not verify");
+  }
+
+  return {
+    E: E, code: code, KU_BIT: KU_BIT,
+    encodeName: encodeName, isEmptyName: isEmptyName, encodeGeneralName: encodeGeneralName,
+    extKeyUsage: extKeyUsage, extExtKeyUsage: extExtKeyUsage, validateBcSpec: validateBcSpec,
+    extBasicConstraints: extBasicConstraints, pathLen: pathLen, extSki: extSki, extAki: extAki,
+    extSan: extSan, extCertPolicies: extCertPolicies, ext: ext,
+    spkiKeyId: spkiKeyId, skiKeyId: skiKeyId,
+    reqDer: reqDer, assertValidSpki: assertValidSpki, assertValidExtension: assertValidExtension,
+    certLikeFromSpki: certLikeFromSpki, assertSignatureVerifies: assertSignatureVerifies,
+  };
+}
+
+module.exports = { makeBuilder: makeBuilder, KU_BIT: KU_BIT };

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,395 @@
+// 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 guard = require("./guard-all");
+var frameworkError = require("./framework-error");
+var schema = require("./schema-engine");
+var pkix = require("./schema-pkix");
+var pkiBuild = require("./pki-build");
+
+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,
+};
+
+// The shared PKIX producing primitives (lib/pki-build.js), bound to the x509 namespace so they keep the
+// frozen x509/* codes. Thin local aliases let the x509 call sites read unchanged. csr-sign binds the same
+// builder to its own namespace (Hard rule #5 -- one encode definition, no per-format hand-roll).
+var _b = pkiBuild.makeBuilder({ ErrorClass: CertificateError, prefix: "x509", O: O, NS: NS, NAME_SCHEMA: NAME_SCHEMA, SPKI_SCHEMA: SPKI_SCHEMA, EXT_DECODERS: EXT_DECODERS });
+var _encodeName = _b.encodeName, _isEmptyName = _b.isEmptyName, _reqDer = _b.reqDer,
+  _assertValidSpki = _b.assertValidSpki, _assertValidExtension = _b.assertValidExtension,
+  _certLikeFromSpki = _b.certLikeFromSpki, _assertCertVerifies = _b.assertSignatureVerifies,
+  _ext = _b.ext, _extBasicConstraints = _b.extBasicConstraints, _validateBcSpec = _b.validateBcSpec,
+  _extKeyUsage = _b.extKeyUsage, _extExtKeyUsage = _b.extExtKeyUsage, _extSki = _b.extSki,
+  _extAki = _b.extAki, _extSan = _b.extSan, _extCertPolicies = _b.extCertPolicies,
+  _skiKeyId = _b.skiKeyId, _spkiKeyId = _b.spkiKeyId;
+
+// ---- issuer-side extension helpers (subjectKeyIdentifier lookup + authorityKeyIdentifier) ----
+
+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 _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);
+}
+// 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 };
+}
+// 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.33",
+  "version": "0.3.1",
   "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:81b0b6a6-dee2-4e3f-b995-abbe40a0f560",
+  "serialNumber": "urn:uuid:d4ed0583-0ef7-424e-90b1-6a5b7b80e23d",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-17T00:29:40.078Z",
+    "timestamp": "2026-07-17T07:12:45.777Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.2.33",
+      "bom-ref": "@blamejs/pki@0.3.1",
       "type": "application",
       "name": "pki",
-      "version": "0.2.33",
+      "version": "0.3.1",
       "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.33",
+      "purl": "pkg:npm/%40blamejs/pki@0.3.1",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.2.33",
+      "ref": "@blamejs/pki@0.3.1",
       "dependsOn": []
     }
   ]