@blamejs/pki 0.4.15 → 0.5.1

package/lib/ocsp.js

@@ -15,7 +15,9 @@
  *   ML-DSA / SLH-DSA per the responder key. Verification composes the SAME hardened responder-
  *   authorization + signature + currency gates `pki.path.ocspChecker` runs -- there is no weaker
  *   second verify path. Fail-closed: `verify` returns a `"unknown"` verdict (never a silent accept)
- *   for any unmet gate; malformed input throws a typed `OcspError`.
+ *   for any unmet gate, with ONE scoped exception -- a request-nonce mismatch downgrades only a
+ *   `good` to `"unknown"`, leaving a signed, current, authorized `revoked` reported as `revoked`
+ *   with `nonceMatched: false` (see `verify`). Malformed input throws a typed `OcspError`.
  * @spec RFC 6960, RFC 9654, RFC 5019
  * @card Build, sign, and verify RFC 6960 OCSP requests + responses (a responder + a relying party).
  */
@@ -103,7 +105,7 @@ function _buildCertID(cert, issuer, hashName) {
  * @primitive pki.ocsp.buildRequest
  * @signature pki.ocsp.buildRequest(query, opts?) -> Buffer | string
  * @since 0.2.22
- * @status experimental
+ * @status stable
  * @spec RFC 6960, RFC 9654, RFC 5019
  * @related pki.ocsp.verify, pki.schema.ocsp.parseRequest
  *
@@ -121,6 +123,15 @@ function _buildCertID(cert, issuer, hashName) {
  *   profile        `"lightweight"` -- one Request, SHA-1 CertID, nonce-only extensions (RFC 5019).
  *   pem            emit a PEM `OCSP REQUEST` string instead of DER.
  * @example
+ *   var ca = await pki.key.generate("Ed25519");
+ *   var caKey = await pki.key.export(ca.privateKey);
+ *   var caDer = await pki.x509.sign({ subject: "Example CA", subjectPublicKey: await pki.key.export(ca.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { basicConstraints: { cA: true }, keyUsage: ["keyCertSign"], subjectKeyIdentifier: true } }, { key: caKey });
+ *   var leaf = await pki.key.generate("Ed25519");
+ *   var leafDer = await pki.x509.sign({ subject: "leaf.example", subjectPublicKey: await pki.key.export(leaf.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { cert: caDer, key: caKey });
  *   var der = await pki.ocsp.buildRequest({ cert: leafDer, issuer: caDer }, { nonce: true });
  */
 function buildRequest(query, opts) {
@@ -195,7 +206,7 @@ function _normCertDer(cert, what) {
  * @primitive pki.ocsp.sign
  * @signature pki.ocsp.sign(responseData, responder, opts?) -> Promise<Buffer | string>
  * @since 0.2.22
- * @status experimental
+ * @status stable
  * @spec RFC 6960, RFC 9654
  * @related pki.ocsp.verify, pki.ocsp.buildErrorResponse
  *
@@ -212,6 +223,18 @@ function _normCertDer(cert, what) {
  *   embedCert       `false` to omit certs [0] (a direct-CA response the client already trusts).
  *   pem             emit a PEM `OCSP RESPONSE` string instead of DER.
  * @example
+ *   var ca = await pki.key.generate("Ed25519");
+ *   var responderPkcs8 = await pki.key.export(ca.privateKey);
+ *   // the issuing CA responds directly here, so its own certificate is the responder's
+ *   var caDer = await pki.x509.sign({ subject: "Example CA", subjectPublicKey: await pki.key.export(ca.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { basicConstraints: { cA: true }, keyUsage: ["keyCertSign"], subjectKeyIdentifier: true } },
+ *     { key: responderPkcs8 });
+ *   var responderCertDer = caDer;
+ *   var leaf = await pki.key.generate("Ed25519");
+ *   var leafDer = await pki.x509.sign({ subject: "leaf.example", subjectPublicKey: await pki.key.export(leaf.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { cert: caDer, key: responderPkcs8 });
  *   var resp = await pki.ocsp.sign(
  *     { responderID: "byName", responses: [{ cert: leafDer, issuer: caDer, status: "good" }] },
  *     { cert: responderCertDer, key: responderPkcs8 });
@@ -222,6 +245,43 @@ function sign(responseData, responder, opts) {
   if (!responder || responder.cert == null || responder.key == null) throw _err("ocsp/bad-input", "a responder must be { cert, key }");
   var respCertDer = _normCertDer(responder.cert, "the responder certificate");
   var respCert = _certOf(respCertDer, "the responder certificate");
+  // Read with the certificate, not after the awaits below. The ResponderID and the
+  // embedded certificate are both fixed from `respCert` here; the signature is made
+  // several promise turns later, so a `responder` whose key was replaced in between
+  // would produce a response naming one responder and signed by another key.
+  //
+  // Capturing the REFERENCE only closes half of that: it stops `responder.key = other`,
+  // but PKCS#8 arrives as caller-owned BYTES and a composite key as a caller-owned
+  // { mldsa, trad } object, either of which can be rewritten in place across the same
+  // gap with the same result -- a response carrying this responder's ID and certificate
+  // over a signature made by a different key, which no relying party can verify. So the
+  // material itself is snapshotted here, not just the binding to it. A CryptoKey is
+  // opaque and a PEM string is immutable, so both are already safe by reference.
+  var ownedKeyBytes = [];
+  var responderKey = _snapshotSignerKey(responder.key, ownedKeyBytes);
+  // The copy is cleared on the failing path as well as the succeeding one -- a wrong or
+  // malformed key is the case an attacker can force, so a success-only wipe would keep the
+  // secret exactly when it matters. The wipe covers the WHOLE window the copy exists, not
+  // just the signing call: the copy is taken before the response list, the responder ID, the
+  // SingleResponses, the dates, the nonce and the signature scheme are validated, and every
+  // one of those can fail. Attaching cleanup to signing alone leaves the secret in the heap
+  // on each of those earlier exits, which are the easiest ones for a caller to reach.
+  function _wipeOwnedKey() {
+    if (ownedKeyBytes.length) guard.secret.zeroizeAll(ownedKeyBytes, OcspError, "ocsp/bad-input", "the responder key copy");
+    ownedKeyBytes.length = 0;
+  }
+  var pending;
+  try {
+    pending = _signResponse(responseData, responder, respCert, respCertDer, responderKey, opts);
+  } catch (e) { _wipeOwnedKey(); throw e; }
+  return pending.then(function (out) { _wipeOwnedKey(); return out; },
+    function (e) { _wipeOwnedKey(); throw e; });
+}
+
+// Everything from the key snapshot onward, so a single cleanup in the caller covers every
+// exit -- sync throw and async rejection alike -- rather than each fallible step needing to
+// remember. `responderKey` is the private copy; it is never the caller's object.
+function _signResponse(responseData, responder, respCert, respCertDer, responderKey, opts) {
   var responses = responseData.responses || [];
   if (!responses.length) throw _err("ocsp/bad-input", "a response MUST include at least one SingleResponse (RFC 6960 sec. 4.2.1)");
 
@@ -234,7 +294,7 @@ function sign(responseData, responder, opts) {
       if (respExts.length) rdChildren.push(b.explicit(1, b.sequence(respExts)));
       var responseDataDer = b.sequence(rdChildren);
       var scheme = signScheme.resolveSignScheme(respCert, { combinedRsaSig: true }, true, _signE);
-      return signScheme.signOverTbs(scheme, responder.key, responseDataDer, _signE).then(function (sig) {
+      return signScheme.signOverTbs(scheme, responderKey, responseDataDer, _signE).then(function (sig) {
         var basicChildren = [responseDataDer, scheme.sigAlgId, b.bitString(sig, 0)];
         if (opts.embedCert !== false) basicChildren.push(b.explicit(0, b.sequence([b.raw(respCertDer)])));
         var responseBytes = b.sequence([b.oid(OID_OCSP_BASIC), b.octetString(b.sequence(basicChildren))]);
@@ -253,6 +313,36 @@ function _asDate(d) {
   if (isNaN(dt.getTime())) throw _err("ocsp/bad-input", "an invalid date value " + JSON.stringify(d));
   return dt;
 }
+// A private copy of whatever signer-key material the caller owns, taken at the entry
+// point because signing happens several promise turns later (see `sign`). Bytes are
+// copied; a composite { mldsa, trad } is rebuilt with each component copied, since
+// rewriting a component is the same attack one level down. Anything else -- a CryptoKey,
+// a PEM string -- is not caller-mutable in a way that changes the key, so it rides as-is
+// rather than being coerced into a shape this function does not understand.
+// `owned` collects every buffer THIS function allocated, so the caller can clear them once
+// signing is done. A copy of a private key is a second copy of a secret, which is precisely
+// what this project's secret-lifetime discipline exists to avoid -- so the copy that closes
+// the aliasing window is wiped rather than left to the garbage collector. Only our own
+// allocations are listed: the caller's key is never written to.
+function _snapshotSignerKey(key, owned) {
+  if (Buffer.isBuffer(key) || key instanceof Uint8Array) {
+    var copy = guard.bytes.snapshot(key, OcspError, "ocsp/bad-input", "the responder key");
+    owned.push(copy);
+    return copy;
+  }
+  // The test is "is this a composite DESCRIPTOR", not "does it currently hold bytes". A
+  // composite whose components are both PEM strings carries nothing mutable inside it, but
+  // the OBJECT is still the caller's: reassigning `key.mldsa` after the call reaches the
+  // deferred signing operation just as rewriting a buffer would, and yields a response whose
+  // responder ID and embedded certificate describe one responder over a signature made by
+  // another key. So the container is always rebuilt, and each component is snapshotted by
+  // its own type -- bytes copied, an immutable PEM string passed through.
+  if (key && typeof key === "object" && (key.mldsa != null || key.trad != null)) {
+    return Object.assign({}, key, { mldsa: _snapshotSignerKey(key.mldsa, owned), trad: _snapshotSignerKey(key.trad, owned) });
+  }
+  return key;
+}
+
 function _responderID(rid, respCert) {
   if (rid == null || rid === "byName") return Promise.resolve(b.explicit(1, b.raw(respCert.subject.bytes)));   // byName [1] EXPLICIT Name
   if (rid === "byKey") return _digest("SHA-1", _keyValue(respCert.subjectPublicKeyInfo.bytes)).then(function (kh) { return b.explicit(2, b.octetString(kh)); });
@@ -261,7 +351,10 @@ function _responderID(rid, respCert) {
 function _buildSingleResponse(r, opts) {
   r = r || {};
   var certIdP;
-  if (r.certID != null) certIdP = Promise.resolve(b.raw(Buffer.isBuffer(r.certID) ? r.certID : Buffer.from(r.certID)));
+  // A pre-encoded CertID is spliced in RAW, so its type is checked rather than coerced:
+  // Buffer.from(20) would allocate twenty zero octets and emit a structurally broken
+  // CertID inside a response this responder then SIGNS.
+  if (r.certID != null) certIdP = Promise.resolve(b.raw(guard.bytes.view(r.certID, OcspError, "ocsp/bad-input", "a response entry's certID")));
   else if (r.cert != null && r.issuer != null) certIdP = _buildCertID(_certOf(r.cert, "a response certificate"), _certOf(r.issuer, "a response issuer"), r.hashAlgorithm || "sha1");
   else return Promise.reject(_err("ocsp/bad-input", "each response entry needs { certID } or { cert, issuer }"));
   return certIdP.then(function (certID) {
@@ -292,7 +385,7 @@ function _certStatusNode(status, opts) {
  * @primitive pki.ocsp.buildErrorResponse
  * @signature pki.ocsp.buildErrorResponse(status) -> Buffer | string
  * @since 0.2.22
- * @status experimental
+ * @status stable
  * @spec RFC 6960
  * @related pki.ocsp.sign
  *
@@ -314,7 +407,7 @@ function buildErrorResponse(status) {
  * @primitive pki.ocsp.verify
  * @signature pki.ocsp.verify(response, opts) -> Promise<{ status, responderAuthorized, signatureValid, thisUpdate, nextUpdate, revocationReason?, nonceMatched?, reason }>
  * @since 0.2.22
- * @status experimental
+ * @status stable
  * @spec RFC 6960, RFC 9654, RFC 5019
  * @related pki.path.ocspChecker, pki.ocsp.buildRequest
  *
@@ -324,8 +417,16 @@ function buildErrorResponse(status) {
  * to the target certificate under the CertID's own hashAlgorithm, checks currency
  * (`thisUpdate`/`nextUpdate`), and -- when `opts.requestNonce` is supplied -- confirms the response
  * nonce echoes it. This runs the SAME hardened gates `pki.path.ocspChecker` does. Fail-closed: an
- * unauthorized, stale, mismatched, or nonce-mismatched response is a `"unknown"` verdict (never a
- * silent accept); a malformed response's parse fault surfaces as the parser's `ocsp/*` / `asn1/*`.
+ * unauthorized, stale, or CertID-mismatched response is a `"unknown"` verdict (never a silent
+ * accept); a malformed response's parse fault surfaces as the parser's `ocsp/*` / `asn1/*`.
+ *
+ * The request-nonce check is reported, and downgrades `good` ONLY. Every verdict carries
+ * `nonceMatched` (true / false / null when the client sent no nonce). An unmatched nonce turns a
+ * `good` into `"unknown"`, because a response that is not an answer to this request cannot be relied
+ * on to say the certificate is still fine. It does NOT touch `revoked`: revocation does not go stale
+ * the way non-revocation does, so discarding a signed, current, authorized `revoked` because it was
+ * replayed would hand a soft-failing caller the very certificate the responder refused. A replayed
+ * `revoked` is therefore reported as `revoked` with `nonceMatched: false`.
  *
  * @opts
  *   cert            the target certificate (parsed, DER, or PEM) -- REQUIRED.
@@ -334,6 +435,19 @@ function buildErrorResponse(status) {
  *   requestNonce    the nonce the client sent; when given, the response MUST echo it (constant-time).
  *   historicalMode  defer a strictly-future revocation (report good) instead of revoking on skew.
  * @example
+ *   var ca = await pki.key.generate("Ed25519");
+ *   var caKey = await pki.key.export(ca.privateKey);
+ *   var caDer = await pki.x509.sign({ subject: "Example CA", subjectPublicKey: await pki.key.export(ca.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { basicConstraints: { cA: true }, keyUsage: ["keyCertSign"], subjectKeyIdentifier: true } },
+ *     { key: caKey });
+ *   var leaf = await pki.key.generate("Ed25519");
+ *   var leafDer = await pki.x509.sign({ subject: "leaf.example", subjectPublicKey: await pki.key.export(leaf.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { cert: caDer, key: caKey });
+ *   var responseDer = await pki.ocsp.sign(
+ *     { responderID: "byName", responses: [{ cert: leafDer, issuer: caDer, status: "good" }] },
+ *     { cert: caDer, key: caKey });
  *   var res = await pki.ocsp.verify(responseDer, { cert: leafDer, issuer: caDer });
  *   res.status;   // "good" | "revoked" | "unknown"
  */
@@ -350,14 +464,28 @@ function verify(response, opts) {
     time = opts.time == null ? new Date() : _asDate(opts.time);
   } catch (e) { return Promise.reject(e); }
   return pathValidate.verifyOcspResponse(parsed, cert, issuerCert, time, { historicalMode: opts.historicalMode === true }).then(function (verdict) {
-    if (opts.requestNonce == null) return verdict;
+    // A client that sent no nonce still gets the field, as null. Leaving it absent would make
+    // "not requested" indistinguishable from "the field is not there yet" for a consumer reading
+    // res.nonceMatched, and the three-state contract is the whole point: true bound, false not
+    // bound, null never asked. The verdict is copied rather than mutated, since it is the lower
+    // primitive's object and this layer does not own it.
+    if (opts.requestNonce == null) return Object.assign({}, verdict, { nonceMatched: null });
     // A client that sent a nonce binds it (RFC 9654 / RFC 5019 sec. 4): a missing or mismatched
     // response nonce fails the verdict closed, even if the status/signature were otherwise good.
     var respNonce = _responseNonce(parsed);
     var reqNonce = Buffer.isBuffer(opts.requestNonce) ? opts.requestNonce : (opts.requestNonce instanceof Uint8Array ? Buffer.from(opts.requestNonce) : null);
     var matched = respNonce != null && reqNonce != null && guard.crypto.constantTimeEqual(respNonce, reqNonce);
     var out = Object.assign({}, verdict, { nonceMatched: matched });
-    if (!matched && verdict.status !== "unknown") {
+    // The downgrade applies to `good` ONLY. `unknown` is the closed direction for a
+    // response claiming the certificate is fine, because an unmatched nonce means
+    // this is not an answer to this request and the "fine" may be stale. It is NOT
+    // the closed direction for `revoked`: revocation does not expire the way
+    // non-revocation does, so discarding a signed, current, authorized revoked
+    // verdict because it was replayed would hand a soft-fail caller the certificate
+    // the responder just refused -- turning the anti-replay defence into the thing
+    // that accepts a revoked certificate. `nonceMatched: false` still reports that
+    // this response was not bound to this request.
+    if (!matched && verdict.status === "good") {
       return Object.assign(out, { status: "unknown", reason: "the OCSP response nonce does not echo the request nonce (RFC 9654)" });
     }
     return out;

package/lib/oid.js

@@ -132,7 +132,65 @@ var FAMILIES = {
   // name->OID reverse stays unambiguous next to the id-kp "timeStamping" purpose (a distinct arc).
   adAccess: { base: [1, 3, 6, 1, 5, 5, 7, 48], of: { ocsp: 1, caIssuers: 2,
     "id-ad-timeStamping": 3, "id-ad-caRepository": 5, "id-ad-rpkiManifest": 10,
-    "id-ad-signedObject": 11, "id-ad-rpkiNotify": 13 } },
+    "id-ad-signedObject": 11, "id-ad-rpkiNotify": 13, "id-ad-cmc": 12 } },
+
+  // CMC control attributes -- id-cmc ::= {id-pkix 7} (RFC 5272 sec. 6, extended by RFC 6402
+  // sec. 2.2/2.8). The whole registry is declared, not just the controls used today: a control
+  // this side does not act on must still be RECOGNIZED to be reported by name, and a decoder that
+  // meets an unknown OID cannot tell "control this build ignores" from "attacker-supplied filler".
+  //
+  // The gaps are the specification's own: 12/13/14 (identityProof/popLinkRandom/popLinkWitness's
+  // superseded siblings are retained below where RFC 6402 kept them) and 20 are unassigned in
+  // RFC 5272 Appendix A. V2 forms exist because RFC 6402 replaced the originals to fix a hash
+  // agility gap -- BOTH are registered, since a v1 message is still legal to receive.
+  idCmc: { base: [1, 3, 6, 1, 5, 5, 7, 7], of: {
+    "id-cmc-statusInfo": 1, "id-cmc-identification": 2, "id-cmc-identityProof": 3,
+    "id-cmc-dataReturn": 4, "id-cmc-transactionId": 5, "id-cmc-senderNonce": 6,
+    "id-cmc-recipientNonce": 7, "id-cmc-addExtensions": 8, "id-cmc-encryptedPOP": 9,
+    "id-cmc-decryptedPOP": 10, "id-cmc-lraPOPWitness": 11,
+    "id-cmc-getCert": 15, "id-cmc-getCRL": 16, "id-cmc-revokeRequest": 17,
+    "id-cmc-regInfo": 18, "id-cmc-responseInfo": 19,
+    "id-cmc-queryPending": 21, "id-cmc-popLinkRandom": 22, "id-cmc-popLinkWitness": 23,
+    "id-cmc-confirmCertAcceptance": 24, "id-cmc-statusInfoV2": 25, "id-cmc-trustedAnchors": 26,
+    "id-cmc-authData": 27, "id-cmc-batchRequests": 28, "id-cmc-batchResponses": 29,
+    "id-cmc-publishCert": 30, "id-cmc-modCertTemplate": 31, "id-cmc-controlProcessed": 32,
+    // ---------------------------------------------------------------------
+    // 33 / 34 -- the specification assigns these two OIDs BOTH ways, and no
+    // erratum resolves it. Counted across every place either document states an
+    // assignment, it is not an even split:
+    //
+    //   identityProofV2 = 34, popLinkWitnessV2 = 33
+    //     rfc5272.txt:1494 / :1504   the sec. 6 control summary table
+    //     rfc5272.txt:1846           sec. 6.2.1 body
+    //     rfc5272.txt:2037           sec. 6.3.1.1 body
+    //     rfc5272.txt:4041 / :4049   RFC 5272's own ASN.1 module
+    //     rfc6402.txt:1228 / :1245   RFC 6402 Appendix A.1 (1988 module)
+    //
+    //   identityProofV2 = 33, popLinkWitnessV2 = 34
+    //     rfc6402.txt:1938 / :1949   RFC 6402 Appendix A.2 (2008 module) ONLY
+    //
+    // The rows below therefore follow the base specification's normative body
+    // text and its module, which RFC 6402's own 1988 module agrees with. The
+    // 2008 module is the lone outlier and is treated as its typo.
+    //
+    // This binds what the toolkit EMITS, and it is load-bearing because the two
+    // controls cannot be told apart by SHAPE: both are SEQUENCE {
+    // AlgorithmIdentifier, AlgorithmIdentifier, OCTET STRING } (rfc6402.txt:1238,
+    // :1246), so the OID is the only discriminator. Emitting the A.2 reading
+    // would hand a peer built on RFC 5272 an Identity Proof it reads as a POP
+    // Link Witness. A CONSUMER must still not infer meaning from these names
+    // alone -- a peer built against A.2 means the other one, and nothing on the
+    // wire says which module it read.
+    "id-cmc-identityProofV2": 34, "id-cmc-popLinkWitnessV2": 33,
+    "id-cmc-raIdentityWitness": 35, "id-cmc-changeSubjectName": 36, "id-cmc-responseBody": 37,
+  } },
+
+  // CMC content types -- id-cct ::= {id-pkix 12} (RFC 5272 Appendix A). The eContentType a CMC
+  // message rides under inside its CMS SignedData wrapper. RFC 5272 Appendix B repeatedly writes
+  // "id-ct-PKIData"; that is erratum 4775 (Verified) and the correct prefix is id-cct-.
+  idCct: { base: [1, 3, 6, 1, 5, 5, 7, 12], of: {
+    "id-cct-PKIData": 2, "id-cct-PKIResponse": 3,
+  } },
 
   // id-on -- RFC 5280 sec. 4.2.1.6 otherName type-ids the C509 sec. 8.13 registry gives their own
   // negative ints: id-on-hardwareModuleName (RFC 4108), id-on-SmtpUTF8Mailbox (RFC 9598),
@@ -312,6 +370,11 @@ var FAMILIES = {
   // identifiers (RFC 9802 sec. 4). HSS/LMS additionally has the SMIME
   // id-alg-hss-lms-hashsig OID above (RFC 9708 / RFC 9802 share it).
   pkixAlg: { base: [1, 3, 6, 1, 5, 5, 7, 6], of: {
+    // id-alg-noSignature (RFC 6402 sec. 2.4, {id-pkix id-alg(6) 2}): the CMC
+    // "signature" algorithm for a request whose signer has no key yet -- the
+    // SignerInfo carries a MAC-based proof instead. Registered so a decoder can
+    // NAME it and refuse it deliberately, rather than meeting an unknown OID.
+    "id-alg-noSignature": 2,
     "id-alg-xmss-hashsig": 34, "id-alg-xmssmt-hashsig": 35,
     // Composite ML-DSA signature algorithms (draft-ietf-lamps-pq-composite-sigs
     // sec. 6): a PQ ML-DSA paired with a traditional RSA / ECDSA / EdDSA so the
@@ -348,6 +411,11 @@ var FAMILIES = {
     receiptRequest: 1, eSSSecurityLabel: 2, mlExpansionHistory: 3, contentHints: 4,
     msgSigDigest: 5, contentIdentifier: 7, equivalentLabels: 9, contentReference: 10,
     signingCertificate: 12, timeStampToken: 14, decryptKeyID: 37, signingCertificateV2: 47,
+    // id-aa-cmc-unsignedData (RFC 6402 sec. 2.7, {id-aa 34}): the CMC unsigned
+    // attribute that carries body parts too large to sit inside the signed
+    // PKIData -- unsigned by design, so a consumer must treat its contents as
+    // untrusted data rather than as part of the authenticated message.
+    cmcUnsignedData: 34,
     asymmDecryptKeyID: 54, certificationRequestInfoTemplate: 61, extensionReqTemplate: 62 } },
 
   // ANSI X9.62 EC public key, named curve, and ECDSA signatures.

package/lib/path-validate.js

@@ -1107,7 +1107,7 @@ function validateCriticalExtensionStructure(cert) {
  * @primitive  pki.path.validate
  * @signature  pki.path.validate(path, opts) -> Promise<result>
  * @since      0.1.16
- * @status     experimental
+ * @status     stable
  * @spec       RFC 5280
  * @related    pki.schema.x509.parse, pki.path.crlChecker
  *
@@ -1134,6 +1134,10 @@ function validateCriticalExtensionStructure(cert) {
  * throws a typed `PathError`.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = await pki.x509.sign({ subject: "example.com", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2019-01-01T00:00:00Z"), notAfter: new Date("2029-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   var cert = pki.schema.x509.parse(der);
  *   var res = await pki.path.validate([cert], {
  *     time: new Date("2020-01-01T00:00:00Z"),
@@ -1769,7 +1773,7 @@ function selectDelta(candidates) {
  * @primitive  pki.path.crlChecker
  * @signature  pki.path.crlChecker(crls, opts?) -> RevocationChecker
  * @since      0.1.16
- * @status     experimental
+ * @status     stable
  * @spec       RFC 5280
  * @related    pki.path.validate, pki.schema.crl.parse
  *
@@ -2212,7 +2216,7 @@ cmpSession.setEngine({ build: build, validate: validate, toAnchor: toAnchor, coe
  * @primitive  pki.path.ocspChecker
  * @signature  pki.path.ocspChecker(responses) -> RevocationChecker
  * @since      0.1.32
- * @status     experimental
+ * @status     stable
  * @spec       RFC 6960
  * @related    pki.path.validate, pki.schema.ocsp.parseResponse, pki.path.crlChecker
  *
@@ -2291,7 +2295,7 @@ function ocspChecker(responses) {
  * @primitive  pki.path.verifyOcspResponse
  * @signature  pki.path.verifyOcspResponse(parsedResponse, cert, issuerCert, time, opts?) -> Promise<{ status, responderAuthorized, signatureValid, matched, thisUpdate, nextUpdate, revocationReason?, reason }>
  * @since       0.2.22
- * @status      experimental
+ * @status      stable
  * @spec        RFC 6960
  * @related     pki.ocsp.verify, pki.path.ocspChecker
  *
@@ -2318,6 +2322,20 @@ function ocspChecker(responses) {
  * fault surfaces as the parser's typed `ocsp/*` / `asn1/*` error.
  *
  * @example
+ *   var ca = await pki.key.generate("Ed25519");
+ *   var caKey = await pki.key.export(ca.privateKey);
+ *   var caDer = await pki.x509.sign({ subject: "Example CA", subjectPublicKey: await pki.key.export(ca.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { basicConstraints: { cA: true }, keyUsage: ["keyCertSign"], subjectKeyIdentifier: true } },
+ *     { key: caKey });
+ *   var leaf = await pki.key.generate("Ed25519");
+ *   var leafDer = await pki.x509.sign({ subject: "leaf.example", subjectPublicKey: await pki.key.export(leaf.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { cert: caDer, key: caKey });
+ *   var der = await pki.ocsp.sign(
+ *     { responderID: "byName", responses: [{ cert: leafDer, issuer: caDer, status: "good" }] },
+ *     { cert: caDer, key: caKey });
+ *   var cert = pki.schema.x509.parse(leafDer), issuerCert = pki.schema.x509.parse(caDer);
  *   var resp = pki.schema.ocsp.parseResponse(der);
  *   var v = await pki.path.verifyOcspResponse(resp, cert, issuerCert, new Date());
  *   v.status;   // "good" | "revoked" | "unknown"
@@ -2674,6 +2692,11 @@ async function _fetchAiaIssuers(current, aia) {
  * @opts  maxResponseBytes       Per-fetch response size cap, forwarded to the transport (tightenable downward only).
  * @opts  (validate options)     Every `pki.path.validate` option (`requiredEku`, `revocationChecker`, `checkPurpose`, the initial policy inputs, ...) is forwarded unchanged.
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var pemString = await pki.x509.sign({ subject: "Example Root", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { basicConstraints: { cA: true }, keyUsage: ["keyCertSign"], subjectKeyIdentifier: true } },
+ *     { key: await pki.key.export(pair.privateKey) }, { pem: true });
  *   var result = await pki.path.build(pemString, {
  *     candidates: [],              // untrusted intermediates (the openssl -untrusted set)
  *     trustAnchors: [pemString],   // a self-signed root, or a { name, publicKey, algorithm } tuple

package/lib/pkcs12-build.js

@@ -469,6 +469,10 @@ function _normalizeSpec(spec, opts) {
  *   - `recipientCerts` -- (public-key privacy convenience) `[certDer|PEM, ...]`; the convenience-form cert + key are placed in one recipient-enveloped safe (a plaintext keyBag). For the full form, set per-`safeContents` `recipients: [{ cert }, ...]` -- CERTIFICATE recipients only (RSA-OAEP / ECDH / X25519 / X448 / ML-KEM, dispatched off the cert key); a password or KEK recipient is not public-key privacy and is rejected -- with an optional `contentEncryptionAlgorithm` (`aes-128|192|256-cbc`, default 256; GCM/AEAD rejected). `encrypt` (password) and `recipients` (public-key) on the same safe is rejected; privacy is independent of integrity.
  *   - `pem` (boolean) -- return a PEM `PKCS12` string instead of DER.
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var signerCertDer = await pki.x509.sign({ subject: "Signer", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: signerKeyPkcs8 });
  *   var p12 = await pki.pkcs12.build({ safeContents: [{ bags: [
  *     { type: 'cert', cert: signerCertDer },
  *     { type: 'shroudedKey', key: signerKeyPkcs8, encrypt: { password: 'changeit' } } ] }] },
@@ -526,6 +530,10 @@ async function build(spec, opts) {
  * or public-key-integrity store, or an unsupported MAC algorithm (never a falsy verdict standing in for an error).
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var signerCertDer = await pki.x509.sign({ subject: "Signer", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: signerKeyPkcs8 });
  *   var p12 = await pki.pkcs12.build({ key: signerKeyPkcs8, cert: signerCertDer }, { password: 'changeit' });
  *   var ok = await pki.pkcs12.verifyMac(p12, 'changeit');
  */
@@ -614,6 +622,10 @@ function _capWork(iterations, salt, opts, keyLength, hardCap) {
  *   - `keys` (string) -- `der` (default) or `crypto` (also `pki.key.import` each private key to a CryptoKey).
  *   - `importAlgorithm` -- forwarded to `pki.key.import` for the ambiguous RSA / EC arms when `keys: crypto`.
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var signerCertDer = await pki.x509.sign({ subject: "Signer", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: signerKeyPkcs8 });
  *   var p12 = await pki.pkcs12.build({ key: signerKeyPkcs8, cert: signerCertDer }, { password: 'changeit' });
  *   var store = await pki.pkcs12.open(p12, 'changeit');
  *   var keyDer = store.keys[0].pkcs8, certDer = store.certs[0].cert;

package/lib/schema-all.js

@@ -50,6 +50,15 @@ var attrcert = require("./schema-attrcert");
 // SEQUENCE) so it is deliberately absent from FORMATS / the detect-and-route
 // `parse`; it is reached only by explicit OID dispatch on a CMS attribute.
 var smime = require("./schema-smime");
+// cmc is likewise a COMPANION decoder, for the same reason arrived at from the
+// other direction: a CMC message's outer DER root IS a CMS ContentInfo, which
+// `cms.matches` already claims below. A `cmc` FORMATS row would either shadow CMS
+// or be shadowed by it, and there is no structurally disjoint root to detect --
+// the discriminator is the encapsulated content type, one layer in. So it is
+// reached by explicit call, or by dispatching on
+// `pki.schema.cms.parse(der).encapContentInfo.eContentType`, and exports no
+// `matches` for nobody to call.
+var cmc = require("./schema-cmc");
 var frameworkError = require("./framework-error");
 
 var SchemaError = frameworkError.SchemaError;
@@ -276,6 +285,10 @@ function all() { return FORMATS.map(function (f) { return f.name; }); }
  * errors of the matched format propagate unchanged.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = await pki.x509.sign({ subject: "example.com", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   var parsed = pki.schema.parse(der);  // cert -> the pki.schema.x509 shape
  */
 function parse(input) {
@@ -294,7 +307,7 @@ function parse(input) {
  * @primitive  pki.schema.detectFormat
  * @signature  pki.schema.detectFormat(input) -> string | null
  * @since       0.3.8
- * @status      experimental
+ * @status      stable
  * @spec        RFC 5280
  * @related     pki.schema.parse, pki.schema.all
  *
@@ -307,6 +320,10 @@ function parse(input) {
  * same coercion / decode error `parse` throws.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = await pki.x509.sign({ subject: "example.com", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   pki.schema.detectFormat(der);  // "x509" | "crl" | "csr" | "cms" | ... | null
  */
 function detectFormat(input) {
@@ -339,6 +356,7 @@ module.exports = {
   csrattrs: { parse: csrattrs.parse },
   attrcert: { parse: attrcert.parse, pemDecode: attrcert.pemDecode, pemEncode: attrcert.pemEncode },
   smime: { parseSigningCertificate: smime.parseSigningCertificate, parseSigningCertificateV2: smime.parseSigningCertificateV2, parseSmimeCapabilities: smime.parseSmimeCapabilities, decodeAttribute: smime.decodeAttribute },
+  cmc: { parse: cmc.parse, parsePkiData: cmc.parsePkiData, parsePkiResponse: cmc.parsePkiResponse },
   all: all,
   parse: parse,
   detectFormat: detectFormat,

package/lib/schema-attrcert.js

@@ -340,6 +340,15 @@ var ATTRIBUTE_CERTIFICATE = pkix.signedEnvelope(NS, ACINFO, {
  * and `Asn1Error` when the underlying DER is malformed.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var aaCert = await pki.x509.sign({ subject: "Attribute Authority", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: key });
+ *   var der = await pki.attrcert.sign(
+ *     { holder: { entityName: { directoryName: "CN=Alice" } },
+ *       notBeforeTime: new Date("2026-01-01T00:00:00Z"), notAfterTime: new Date("2027-01-01T00:00:00Z"),
+ *       attributes: { role: { roleName: { uniformResourceIdentifier: "urn:role:admin" } } } },
+ *     { cert: aaCert, key: key });
  *   var ac = pki.schema.attrcert.parse(der);
  *   ac.attributes[0].name;   // "role"
  *   ac.validity.notAfterTime;// Date
@@ -383,6 +392,15 @@ function parseV1(input) {
  * `PemError` on a missing / mismatched envelope or a non-base64 body.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var aaCert = await pki.x509.sign({ subject: "Attribute Authority", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: key });
+ *   var pemText = await pki.attrcert.sign(
+ *     { holder: { entityName: { directoryName: "CN=Alice" } },
+ *       notBeforeTime: new Date("2026-01-01T00:00:00Z"), notAfterTime: new Date("2027-01-01T00:00:00Z"),
+ *       attributes: { role: { roleName: { uniformResourceIdentifier: "urn:role:admin" } } } },
+ *     { cert: aaCert, key: key }, { pem: true });
  *   var der = pki.schema.attrcert.pemDecode(pemText);
  */
 function pemDecode(text, label) { return pkix.pemDecode(text, label === null ? null : (label || "ATTRIBUTE CERTIFICATE"), PemError); }
@@ -399,6 +417,15 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label === null ? n
  * same default `pemDecode` reads). Throws `PemError` on a malformed label.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var aaCert = await pki.x509.sign({ subject: "Attribute Authority", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: key });
+ *   var der = await pki.attrcert.sign(
+ *     { holder: { entityName: { directoryName: "CN=Alice" } },
+ *       notBeforeTime: new Date("2026-01-01T00:00:00Z"), notAfterTime: new Date("2027-01-01T00:00:00Z"),
+ *       attributes: { role: { roleName: { uniformResourceIdentifier: "urn:role:admin" } } } },
+ *     { cert: aaCert, key: key });
  *   var pem = pki.schema.attrcert.pemEncode(der);
  */
 function pemEncode(der, label) { return pkix.pemEncode(der, label || "ATTRIBUTE CERTIFICATE", PemError); }

package/lib/schema-c509.js

@@ -2327,6 +2327,12 @@ function _encodeC509Array(r) {
  *     only for the DER -> type-3 path; ignored when re-emitting a parse result.
  *
  * @example
+ *   // the type-3 (natively signed) encoding covers ECDSA-signed X.509 v3 certificates
+ *   var pair = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var signerCertDer = await pki.x509.sign({ subject: "example.com", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { keyUsage: ["digitalSignature"] } },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   var cbor = pki.schema.c509.encode(signerCertDer);   // a DER cert -> a compact type-3 C509
  *   pki.schema.c509.parse(cbor).certificateType;        // 3
  */