@blamejs/pki 0.3.0 → 0.3.2

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,310 @@
+// 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
+  // GeneralNames ::= SEQUENCE SIZE(1..MAX) OF GeneralName. With no implicitTag it is a universal SEQUENCE
+  // (subjectAltName / issuerAltName / IssuerSerial.issuer). With an implicitTag it is a context-constructed
+  // [n] whose tag REPLACES the SEQUENCE tag (RFC 5755 IMPLICIT TAGS -- Holder.entityName [1],
+  // RoleSyntax.roleAuthority [0], IetfAttrSyntax.policyAuthority [0]); the [n] node's children ARE the
+  // GeneralName members, no inner SEQUENCE wrapper.
+  function encodeGeneralNames(entries, implicitTag) {
+    if (!Array.isArray(entries) || !entries.length) throw E("bad-input", "a GeneralNames must carry at least one GeneralName");
+    var members = entries.map(encodeGeneralName);
+    if (implicitTag == null) return b.sequence(members);
+    return b.contextConstructed(implicitTag, Buffer.concat(members));
+  }
+  function extSan(entries) { return encodeGeneralNames(entries); }
+  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");
+  }
+  // A positive, non-zero INTEGER of at most 20 content octets (RFC 5280 sec. 4.1.2.2 / RFC 5755 sec.
+  // 4.2.5 -- the identical serial rule for a certificate and an attribute certificate). A random 20-octet
+  // positive serial is generated when none is supplied. Accepts a BigInt, a safe integer, a decimal /
+  // 0x-hex string, or a raw magnitude Buffer.
+  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.isSafeInteger(serial)) throw E("bad-serial", "serialNumber number must be a safe integer (pass a BigInt, hex string, or Buffer for a value above 2^53-1)"); v = BigInt(serial); }
+    else if (typeof serial === "string") { try { v = BigInt(serial); } catch (e) { throw E("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 E("bad-serial", "serialNumber must be a BigInt, integer, hex string, or Buffer"); }
+    if (v <= 0n) throw E("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 E("bad-serial", "serialNumber must not exceed 20 octets (RFC 5280 sec. 4.1.2.2)");
+    return tlv;
+  }
+  // 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,
+    encodeGeneralNames: encodeGeneralNames, serialInteger: serialInteger,
+    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,
+  };
+}
+
+// The raw issuer / subject Name TLV of a parsed X.509 certificate (byte-identical). tbs field layout:
+// [version?] serial(0) signature(1) issuer(2) validity(3) subject(4). Used where a producer must chain a
+// name to an existing certificate exactly -- an issued certificate's issuer, a CMS SignerInfo issuer, an
+// attribute certificate's issuerName / holder baseCertificateID.
+function tbsNameField(cert, which) {
+  var tbs = asn1.decode(cert.tbsBytes);
+  var hasVersion = tbs.children[0].tagClass === "context" && tbs.children[0].tagNumber === 0;
+  return tbs.children[(hasVersion ? 1 : 0) + (which === "subject" ? 4 : 2)].bytes;
+}
+
+module.exports = { makeBuilder: makeBuilder, KU_BIT: KU_BIT, tbsNameField: tbsNameField };

package/lib/schema-attrcert.js

@@ -666,6 +666,21 @@ _AC_EXT_DECODERS[_Oav("noRevAvail")] = _noRevAvail;
 _AC_EXT_DECODERS[_Oav("aaControls")] = _aaControls;
 _AC_EXT_DECODERS[_Oav("acProxying")] = _acProxying;
 
+// @internal -- validate a pre-encoded AC attribute value / AC extension value against the SAME decoder
+// the parser runs, so the attrcert-sign escape hatches (a caller's pre-encoded Attribute / Extension DER)
+// cannot embed a structurally-malformed recognized value the strict parser would then reject. `type` /
+// `extnOid` are dotted-OID strings; `valueDer` / `extnValueDer` are the raw AttributeValue / extnValue
+// content Buffers (exactly what the parse loop passes). An unrecognized type returns null (stays opaque,
+// no validation); a recognized-but-malformed value throws the frozen attrcert/bad-* code.
+function validateAttributeValue(type, valueDer) {
+  var dec = _ATTR_VALUE_DECODERS[type];
+  return dec ? dec(valueDer) : null;
+}
+function validateExtensionValue(extnOid, extnValueDer) {
+  var dec = _AC_EXT_DECODERS[extnOid];
+  return dec ? dec(extnValueDer) : null;
+}
+
 module.exports = {
   parse: parse,
   parseV1: parseV1,
@@ -673,4 +688,6 @@ module.exports = {
   pemEncode: pemEncode,
   matches: matches,
   matchesV1: matchesV1,
+  validateAttributeValue: validateAttributeValue,
+  validateExtensionValue: validateExtensionValue,
 };