@blamejs/pki 0.5.25 → 0.5.26

package/lib/cmp-session.js

@@ -21,6 +21,10 @@ var asn1 = require("./asn1-der");
 var oid = require("./oid");
 var x509 = require("./schema-x509");
 var schemaCmp = require("./schema-cmp");
+var schemaCrmf = require("./schema-crmf");
+var schemaCrl = require("./schema-crl");
+var crmfSign = require("./crmf-sign");
+var cmpBuild = require("./cmp-build");
 var csr = require("./schema-csr");
 var guard = require("./guard-all");
 var compositeSig = require("./composite-sig");
@@ -58,6 +62,15 @@ var SIG_OID_TO_HASH = {};
 });
 var OID_RSASSA_PSS = oid.byName("rsassaPss");
 var OID_RSA_ENCRYPTION = oid.byName("rsaEncryption");
+// A CRL states the point it speaks for in this extension (RFC 5280 sec. 5.2.5); taken at load, by
+// identifier, so a later pki.oid.register cannot rename the extension the scope is read from.
+var OID_IDP = oid.byName("issuingDistributionPoint");
+// The two extensions that decide whether a certificate can act as an authority, taken at load and
+// matched by identifier. pki.oid.register replaces an OID's display name, so a test asking whether
+// an extension is NAMED basicConstraints reads a present one as absent after a rename, and every
+// valid root key update is refused.
+var OID_BASIC_CONSTRAINTS = oid.byName("basicConstraints");
+var OID_KEY_USAGE = oid.byName("keyUsage");
 // Message-digest OID -> the WebCrypto digest name, for the RSASSA-PSS hashAlgorithm parameter, dispatched by
 // the immutable OID (never oid.name, which pki.oid.register can rename). Resolved to a dotted-OID map at load.
 var HASH_OID_TO_DIGEST = {};
@@ -84,7 +97,84 @@ var P10CR_CERT_REQ_ID = -1;    // a PKCS#10 request has no CRMF id; a conforming
 var ENROLL_ARMS = { ir: 1, cr: 1, kur: 1, p10cr: 1 };   // the initial request arms enroll() accepts
 // The response body arm each enrollment request is answered by (RFC 9810 sec. 5.3.2/5.3.4): ir->ip, cr/p10cr
 // ->cp, kur->kup. A response on a different cert-response arm than the request is misrouted, never confirmed.
-var RESPONSE_ARM = { ir: "ip", cr: "cp", kur: "kup", p10cr: "cp" };
+var RESPONSE_ARM = { ir: "ip", cr: "cp", kur: "kup", p10cr: "cp", rr: "rp", genm: "genp" };
+// A pollReq for a non-enrollment operation refers to the WHOLE message rather than to a
+// CertResponse element inside it. RFC 9483 sec. 4.4: an entity "sends a poll request with certReqId
+// 0 if referring to the CertResponse element contained in the ip/cp/kup message, else -1 to refer
+// to the whole message". A revocation or a support message has no CertResponse element, so the
+// second half of that sentence is the one that applies and the id is -1. The 0 is not a default for
+// polling; it is the id OF an element these operations do not carry.
+var WHOLE_MESSAGE_CERT_REQ_ID = -1;
+
+// The four support messages RFC 9483 sec. 4.3 defines, keyed by the name a caller asks for.
+// `requestOid` and `responseOid` differ only for rootCaCert (sec. 4.3.2), which is the reason
+// the pair is a table rather than one field: a response echoing the request OID is a different
+// operation's answer, and only the table can say so. `value` is absent for an operation whose
+// request carries no infoValue (sec. 4.3.1 and sec. 4.3.3 both say it MUST be absent).
+// The table is null-prototype: the key comes from a caller's request object, so a plain literal
+// would answer `toString` or `constructor` with an inherited value and dispatch on it.
+var INFO_OPS = Object.assign(Object.create(null), {
+  caCerts: { name: "caCerts", requestOid: "caCerts", responseOid: "caCerts", value: false, read: "readCaCerts" },
+  rootCaCert: { name: "rootCaCert", requestOid: "rootCaCert", responseOid: "rootCaKeyUpdate", value: "cert", read: "readRootCaKeyUpdate" },
+  certReqTemplate: { name: "certReqTemplate", requestOid: "certReqTemplate", responseOid: "certReqTemplate", value: false, read: "readCertReqTemplate" },
+  crlUpdate: { name: "crlUpdate", requestOid: "crlStatusList", responseOid: "crls", value: "crlStatus", read: "readCrls" },
+});
+var KNOWN_REVOKE_KEYS = { certificate: 1, certDetails: 1, reason: 1 };
+// The CRLReason names a revocation may state, read off the same shared table pki.crl.sign and
+// pki.cmp.build encode from, so the three cannot drift apart on what a reason is called. Checked at
+// this door so a mistyped name reads as the request-shape error it is, before the transport engages.
+// A keySpec algId (RFC 9483 sec. 4.3.3, RFC 9480 sec. 2.16) MUST "give an algorithm other than RSA",
+// and that is the ONLY constraint the responder is held to: the control names a public-key type an
+// entity MAY be asked to generate, one AttributeTypeAndValue per algorithm the CA supports, and the
+// entity picks one it can do. So the check refuses an algId ONLY when it names an RSA algorithm (whose
+// requirement is stated with rsaKeyLen instead); every other value -- a non-RSA algorithm this toolkit
+// knows, or an OID it does not recognize -- is surfaced to the caller. Refusing an unrecognized
+// algorithm would break interop with a CA offering one newer than this registry AND drop the other
+// algorithms the same keySpec offers, since one bad element fails the whole exchange.
+//
+// "RSA" is decided by OID FAMILY, not a hand-list. An RSA-DEDICATED arc -- one whose members are RSA --
+// is matched by its prefix, so a standardized member this registry has not named is caught with the ones
+// it has: PKCS#1 (rsaEncryption, PSS, OAEP, every sha*/md*WithRSAEncryption), the TeleTrusT rsaSignature
+// arc (RSA with SHA-1 and the RIPEMD family), and the BSI TR-03110 id-TA-RSA arc (EAC Terminal
+// Authentication, RSA v1.5/PSS over SHA-1/256/512). Each prefix is the arc a registered member sits
+// directly under, read from the registry, so no dotted-decimal literal appears here and pki.oid.register
+// cannot move it. The PKCS#1 arc also carries two auxiliary identifiers that are NOT RSA algorithms --
+// mgf1 and pSpecified, the mask-generation and OAEP-label parameters -- so those are excluded from the
+// match by name (RSA_ARC_EXCLUDE) and surfaced. RSA also sits off those arcs on ones it SHARES with non-RSA
+// algorithms, where no prefix can isolate it, so those are listed by name: id-rsa-kem (S/MIME) and
+// id-kem-rsa (ISO 18033-2); the RSASSA-PKCS1-v1_5-with-SHA-3 set on the NIST signature arc, shared with
+// ML-DSA and SLH-DSA; RSASSA-PSS-with-SHAKE (RFC 8692) on the PKIX arc; every RSA identifier the OIW SIG
+// assigned on the OIW Secsig arc (the md4/md5-WithRSA, rsaSignature, mdc2/sha-WithRSA, rsaKeyTransport,
+// and md2/md5/sha1-WithRSASignature identifiers), which is shared with DES, DSA, DH, and the hashes so no
+// prefix isolates it; and the X.500 directory RSA OIDs on the 2.5.8 arc -- rsa (2.5.8.1.1), distinct from
+// PKCS#1 rsaEncryption, and sqMod-nWithRSA / mdc2WithRSA on the signatureAlgorithm sub-arc; and the
+// Chinese GM/T sm3WithRSAEncryption (1.2.156.10197.1.504), an RSA-over-SM3 signature on the SM arc it
+// shares with SM2 and SM3. A composite signature naming RSA as one half is a composite key, not an RSA
+// one, and lives on the PKIX arc, so it is outside all of these.
+var RSA_ARCS = ["rsaEncryption", "rsaSignatureWithripemd160", "id-TA-RSA-v1-5-SHA-256"].map(function (n) {
+  return oid.toArcs(oid.byName(n)).slice(0, -1);   // the RSA-dedicated arc a registered member sits directly under
+});
+var RSA_OFF_ARC = Object.create(null);
+["id-rsa-kem", "id-kem-rsa",
+  "id-rsassa-pkcs1-v1_5-with-sha3-224", "id-rsassa-pkcs1-v1_5-with-sha3-256",
+  "id-rsassa-pkcs1-v1_5-with-sha3-384", "id-rsassa-pkcs1-v1_5-with-sha3-512",
+  "id-RSASSA-PSS-SHAKE128", "id-RSASSA-PSS-SHAKE256",
+  "md4WithRSA", "md5WithRSA", "md4WithRSAEncryption", "rsaSignature", "mdc2WithRSASignature",
+  "shaWithRSAEncryption", "rsaKeyTransport",
+  "md2WithRSASignature", "md5WithRSASignature", "sha1WithRSASignature",
+  "rsa",   // the X.509 directory rsa public-key OID (2.5.8.1.1), distinct from PKCS#1 rsaEncryption
+  "sqMod-nWithRSA", "mdc2WithRSA",   // the X.500 directory signatureAlgorithm RSA OIDs (2.5.8.3.1, 2.5.8.3.100)
+  "sm3WithRSAEncryption",   // the Chinese GM/T RSA-with-SM3 signature (1.2.156.10197.1.504)
+].forEach(function (n) { var d = oid.byName(n); if (d) RSA_OFF_ARC[d] = 1; });
+// The PKCS#1 arc carries two identifiers that are NOT RSA algorithms: mgf1 (the mask-generation function
+// RSA-PSS and RSA-OAEP parametrize) and pSpecified (the OAEP label source). The prefix match would sweep
+// them in, but a keySpec algId naming one states no RSA key requirement -- the entity does not generate an
+// "mgf1 key" -- so they are surfaced, not refused, and are excluded from the arc match by name.
+var RSA_ARC_EXCLUDE = Object.create(null);
+["mgf1", "pSpecified"].forEach(function (n) { var d = oid.byName(n); if (d) RSA_ARC_EXCLUDE[d] = 1; });
+
+var CRL_REASON_NAMES = Object.create(null);
+Object.keys(constants.NAMES.CRL_REASON).forEach(function (v) { CRL_REASON_NAMES[constants.NAMES.CRL_REASON[v]] = 1; });
 
 // PKIStatus codes (RFC 9810 sec. 5.2.3): 0 accepted, 1 grantedWithMods, 2 rejection, 3 waiting.
 function _isGranted(code) { return code === 0 || code === 1; }
@@ -311,6 +401,7 @@ function _certConfHash(certDer) {
  * (PBMAC1). A crypto-valid response is not enough: the signer must chain to a supplied trust anchor
  * (signature) or the shared secret must match (MAC); a valid-but-untrusted response is a hard stop, so the
  * signature flavor REQUIRES `opts.trustAnchors` at construction. Returns a session with `enroll(request)`,
+ * `revoke(request)`, `info(request)`,
  * and read-only `transactionID` + `transcript` (each leg's request/response bytes, retained up to a
  * transaction-wide cap; a later leg beyond the cap keeps its metadata + `byteLength` but drops the payload as
  * `bytes: null, truncated: true`, so a padded-response flood across polls cannot exhaust memory). The granted certificate must be valid X.509, carry the key
@@ -326,6 +417,33 @@ function _certConfHash(certDer) {
  * issued leaf plus any authenticated `caPubs` the CA delivered (chain material, never trust anchors); a
  * server-generated (central key generation) private key is out of scope and the grant is refused.
  *
+ * `revoke(request)` drives the RFC 9483 sec. 4.2 revocation exchange (`rr` -> `rp`) through the same shell.
+ * The request names the certificate, either as `{ certificate }` or as `{ certDetails: { issuer,
+ * serialNumber } }`, plus an optional `reason` (a CRLReason name). A session revokes ITS OWN certificate:
+ * the signature over the request is the proof of authorization to revoke, so the named certificate must be
+ * `opts.cert`, and a PBMAC1 session, holding no certificate, is refused. The `crlEntryDetails` reasonCode
+ * is always emitted, at `unspecified(0)` when no reason is given, which sec. 4.2 requires and is the
+ * opposite of the RFC 5280 sec. 5.3.1 rule for a CRL entry. Terminal `outcome`: `revoked` (the response's
+ * single accepted status), `rejected`, or `poll-timeout`.
+ *
+ * `info(request)` drives the sec. 4.3 support messages (`genm` -> `genp`), one operation per call:
+ * `{ caCerts: true }` for the CA certificates available for chain construction; `{ rootCaCert: <cert> }`
+ * for a root CA key update, whose response carries a DIFFERENT infoType and must include the `newWithOld`
+ * certificate an entity trusting the old root needs; `{ certReqTemplate: true }` for the certificate-request
+ * requirements, whose template must omit `publicKey`, `serialNumber`, `signingAlg`, `issuerUID` and
+ * `subjectUID`, and whose `keySpec` states key requirements as `algId` (a non-RSA AlgorithmIdentifier) or
+ * `rsaKeyLen` (a positive integer); and `{ crlUpdate: { issuer, dpn?, thisUpdate? } }` for a CRL from a
+ * named source, held to that source -- the issuer under the RFC 5280 sec. 7.1 rule, a distribution point
+ * against the CRL's own `issuingDistributionPoint` where it states one -- and to the supplied `thisUpdate`.
+ * A request naming both sends the dpn (sec. 4.3.4: the dpn choice when a distribution point name is
+ * available) and holds the answer to the issuer as well. The issuer is REQUIRED, since a distribution
+ * point name alone leaves the answer unbound: a complete CRL states no scope to compare it against.
+ * Terminal `outcome`: `answered` (with `operation`, `present`, and the decoded `value`),
+ * `rejected`, or `poll-timeout`. An absent response value is `present: false` with a null `value`, which is
+ * how each of the four says "nothing available" -- never conflated with an empty result. Delayed delivery
+ * for both verbs arrives as an error message carrying the `waiting` status (sec. 4.4) and drives the same
+ * bounded poll loop, with the `pollReq` referring to the whole message.
+ *
  * @opts
  *   - `url` -- REQUIRED: the CMP endpoint URL.
  *   - `key` + `cert` -- signature protection (the enrolling key pair + its cert), XOR `mac: { secret, ... }` for PBMAC1 protection.
@@ -343,10 +461,18 @@ function _certConfHash(certDer) {
  *   var session = pki.cmp.session({ url: "https://ca.example/cmp", key: signerKeyPkcs8, cert: signerCertDer, trustAnchors: [cmpCaCert], transport: cmpTransport });
  *   var result = await session.enroll({ ir: { certTemplate: { subject: [{ commonName: "device-42" }], publicKey: signerSpki } } });
  *   if (result.outcome === "issued") { var leaf = result.certificate; }
+ *
+ *   var revoking = pki.cmp.session({ url: "https://ca.example/cmp", key: signerKeyPkcs8, cert: signerCertDer, trustAnchors: [cmpCaCert], transport: cmpTransport });
+ *   var gone = await revoking.revoke({ certificate: signerCertDer, reason: "keyCompromise" });
+ *   if (gone.outcome === "revoked") { var when = gone.status; }
+ *
+ *   var asking = pki.cmp.session({ url: "https://ca.example/cmp", key: signerKeyPkcs8, cert: signerCertDer, trustAnchors: [cmpCaCert], transport: cmpTransport });
+ *   var answer = await asking.info({ caCerts: true });
+ *   if (answer.outcome === "answered" && answer.present) { var caCerts = answer.value; }
  */
 function session(opts) {
   if (opts == null) opts = {};
-  if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("cmp/bad-input", "opts must be an object");
+  guard.identifier.assertPlainRecord(opts, _err, "cmp/bad-input", "opts");
   guard.identifier.assertKnownKeys(opts, KNOWN_SESSION_OPTS, _err, "cmp/bad-input", "unknown session opts field ");
   // Work on a SHALLOW COPY so a later normalization (e.g. an empty MAC trustAnchors list) never mutates the
   // caller's object -- which may be frozen or reused across sessions -- and normalizing a frozen input does not
@@ -462,7 +588,14 @@ function session(opts) {
   var caPubsBytes = 0;   // running total of retained caPubs bytes -- a transaction-wide byte budget (below) bounds it independent of the count cap, since a single certificate can approach the DER limit
   var caPubsWaitingCount = 0;   // WAITING-leg entries retained at the FRONT of caPubsAccum -- only these are evictable to fit a grant entry; a grant entry (at the back) is the issued leaf's own chain and is never evicted
   var activeCertReqId = DEFAULT_CERT_REQ_ID;   // the certReqId of the in-flight enrollment; echoed in pollReq / certConf
-  var expectedRespArm = "ip";   // the cert-response arm the in-flight enrollment must be answered by (RESPONSE_ARM)
+  var expectedRespArm = "ip";   // the response arm the in-flight transaction must be answered by (RESPONSE_ARM)
+  // Which operation is in flight: it decides how the expected arm's body is read, and, for an error
+  // body, whether a `waiting` status announces delayed delivery. RFC 9483 sec. 4.4 puts that status
+  // in the ip/cp/kup of an enrollment and in an error message for every other operation, so the two
+  // readings are exclusive rather than a leniency applied to both.
+  var txnKind = "enroll";
+  var expectedInfoOp = null;   // the INFO_OPS row of an in-flight support message
+  var crlQuery = null;   // what a crlUpdate asked for: the encoded issuer Name and any thisUpdate
   var requestedSpki = null;   // the SPKI DER of the key the enrollment requested; the issued cert MUST carry it
   var inFlight = false, completed = false, started = false;   // one transaction per session; `started` = a request may have hit the transport
   var transcript = [];
@@ -694,6 +827,8 @@ function session(opts) {
   function _classify(verdict) {
     var body = verdict.body || {};
     var arm = body.arm;
+    if (arm === expectedRespArm && txnKind === "revoke") return _classifyRevRep(body);
+    if (arm === expectedRespArm && txnKind === "info") return _classifyGenRep(body);
     if (arm === expectedRespArm) {
       // Select the CertResponse for OUR request by its certReqId (RFC 9810 sec. 5.3.4) -- never blindly
       // response[0], so a batch / misrouted response for a different request id is not read as ours.
@@ -744,10 +879,74 @@ function session(opts) {
       if (code === 2) return { state: "rejected", resp: resp };
       return { state: "unexpected", reason: "a " + arm + " CertResponse status code " + code + " has no transition" };
     }
-    if (arm === "error") return { state: "rejected", status: body.decoded && body.decoded.pKIStatusInfo };
+    if (arm === "error") return _classifyError(body);
     if (arm === "pollRep") return { state: "pollRep", entries: body.decoded };
     if (arm === "pkiconf") return { state: "pkiconf" };
-    return { state: "unexpected", reason: "response arm " + JSON.stringify(arm) + " has no transition in an enrollment transaction" };
+    return { state: "unexpected", reason: "response arm " + JSON.stringify(arm) + " has no transition in a " + txnKind + " transaction" };
+  }
+
+  // An error body. For a revocation or a support message it is ALSO how delayed delivery is announced:
+  // RFC 9483 sec. 4.4 puts the "waiting" status in an ip/cp/kup for ir/cr/kur/p10cr "and for responses
+  // to other request message types in an error message". An error answering an ENROLLMENT therefore
+  // stays a rejection -- that operation announces its own delay in its own cert-response arm, so
+  // reading waiting out of an error there would accept a shape the profile does not produce.
+  function _classifyError(body) {
+    var si = body.decoded && body.decoded.pKIStatusInfo;
+    var code = si && si.status ? si.status.code : null;
+    if (code === 3) {
+      // sec. 4.4 puts waiting in an ip/cp/kup when answering an enrollment and in an error message for
+      // anything else, so a waiting error drives the poll loop only for revoke/info. For an enrollment a
+      // waiting ERROR is off-profile and refused, not coerced to a rejection whose own status reads
+      // "waiting". A wait is not a failure, so sec. 4.4 forbids failInfo on it -- a waiting error carrying
+      // one is contradictory and refused rather than polled.
+      if (txnKind === "enroll") throw _err("cmp/bad-error", "an error message answering an enrollment must not carry status waiting -- the profile places enrollment waiting in an ip/cp/kup (RFC 9483 sec. 4.4)");
+      if (si.failInfo != null) throw _err("cmp/bad-error", "an error message with status waiting must not carry failInfo (RFC 9483 sec. 4.4)");
+      return { state: "waiting", resp: { status: si } };
+    }
+    // sec. 4.2 / 3.6.4: an error message that is not delayed delivery is a rejection, whose status is
+    // rejection(2). accepted(0), grantedWithMods(1), a status in 4..6, an unknown value, or an absent
+    // status is malformed for an error message, so it is refused rather than surfaced as a definitive
+    // rejected verdict a caller would act on -- the same call the rp classifier makes for an unsupported
+    // status (a trusted "rejected" whose PKIStatusInfo says "accepted" is a contradiction, not a verdict).
+    if (code !== 2) throw _err("cmp/bad-error", "an error message carries status rejection(2), or waiting(3) for a revoke/info delayed delivery (RFC 9483 sec. 4.2); got " + (code == null ? "no status" : code));
+    return { state: "rejected", status: si };
+  }
+
+  // RevRepContent. RFC 9483 sec. 4.2: the response to an rr "MUST be an rp message containing a single
+  // status field", whose positive value is "accepted" and negative "rejection", with failInfo "MUST be
+  // absent if the status is accepted". A status with no transition here is a hard stop, never a verdict.
+  function _classifyRevRep(body) {
+    var d = body.decoded || {};
+    var list = d.status || [];
+    if (list.length !== 1) {
+      return { state: "unexpected", reason: "an rp answering a revocation must carry exactly one status (RFC 9483 sec. 4.2); got " + list.length };
+    }
+    var si = list[0];
+    var code = si && si.status ? si.status.code : null;
+    if (code === 0) {
+      if (si.failInfo != null) {
+        return { state: "unexpected", reason: "an accepted rp must not carry failInfo (RFC 9483 sec. 4.2)" };
+      }
+      return { state: "granted", status: si, revCerts: d.revCerts, crls: d.crls };
+    }
+    if (code === 2) return { state: "rejected", status: si };
+    return { state: "unexpected", reason: "an rp status code " + code + " has no transition in a revocation (RFC 9483 sec. 4.2 allows accepted or rejection)" };
+  }
+
+  // GenRepContent. RFC 9483 sec. 4.3: a genp "MUST contain a sequence of one element of type
+  // InfoTypeAndValue" whose infoType names the operation. The OID is checked against the RESPONSE
+  // side of the INFO_OPS row, which for rootCaCert is not the OID the request carried.
+  function _classifyGenRep(body) {
+    var items = body.decoded || [];
+    if (items.length !== 1) {
+      return { state: "unexpected", reason: "a genp must carry exactly one InfoTypeAndValue (RFC 9483 sec. 4.3); got " + items.length };
+    }
+    var itav = items[0];
+    var want = oid.byName(expectedInfoOp.responseOid);
+    if (itav.type !== want) {
+      return { state: "unexpected", reason: "a genp answering " + expectedInfoOp.name + " must carry infoType " + expectedInfoOp.responseOid + " (" + want + "); got " + itav.type };
+    }
+    return { state: "granted", itav: itav };
   }
 
   function _statusOf(resp) { return resp && resp.status ? resp.status : null; }
@@ -969,14 +1168,45 @@ function session(opts) {
     });
   }
 
+  // One transaction per session (RFC 9810 sec. 5.1.1: one transactionID per transaction). A second or
+  // concurrent call on any verb would reuse this transaction's transactionID / nonce chain / certReqId --
+  // a replay or a corrupted interleave -- so it is refused. Every verb checks this BEFORE marking the
+  // transaction in flight, so a malformed-request call does not consume the session.
+  function _assertFresh(what) {
+    if (completed || inFlight) {
+      throw _err("cmp/bad-input", "this pki.cmp.session transaction is already " + (completed ? "completed" : "in flight") + "; create a new session per " + what + " (RFC 9810 sec. 5.1.1: one transactionID per transaction)");
+    }
+  }
+
+  // The shared tail of a non-enrollment transaction: send the one request, poll through a delayed
+  // delivery, and hand back the terminal classification. Both verbs reach a verdict the same way, so
+  // the poll budget, the nonce chaining and the verify-before-read ordering cannot differ between them.
+  async function _runOneShot(bodySpec, arm, kind) {
+    txnKind = kind;
+    expectedRespArm = RESPONSE_ARM[arm];
+    // A pollReq raised by this transaction refers to the whole message (RFC 9483 sec. 4.4).
+    activeCertReqId = WHOLE_MESSAGE_CERT_REQ_ID;
+    var verdict = await _send(bodySpec, arm);
+    var t = _classify(verdict);
+    var polls = 0;
+    if (t.state === "waiting") {
+      var polled = await _pollLoop(t.resp);
+      polls = polled.polls;
+      if (polled.timeout) return { timeout: true, polls: polls, status: polled.status };
+      t = polled.done;
+    }
+    return { done: t, polls: polls };
+  }
+
   // The transaction driver: build the initial request arm, send it, then poll / confirm / terminate.
   async function enroll(request) {
-    // One transaction per session (RFC 9810: one transactionID per transaction). A second or concurrent
-    // enroll would reuse this transaction's transactionID / nonce chain / certReqId -- a replay or a corrupted
-    // interleave -- so it is refused. The request-shape checks run BEFORE the transaction is marked in-flight,
-    // so a malformed-request call does not consume the session and the caller may retry with a valid request.
-    if (completed || inFlight) throw _err("cmp/bad-input", "this pki.cmp.session transaction is already " + (completed ? "completed" : "in flight") + "; create a new session per enrollment (RFC 9810 sec. 5.1.1: one transactionID per transaction)");
-    if (!request || typeof request !== "object" || Buffer.isBuffer(request)) throw _err("cmp/bad-input", "enroll(request) requires a body spec object { ir | cr | kur | p10cr }");
+    _assertFresh("enrollment");
+    guard.identifier.assertPlainRecord(request, _err, "cmp/bad-input", "enroll(request), a body spec { ir | cr | kur | p10cr },");
+    // A key here that is not an arm needs no door of its own: this whole object becomes the message
+    // body, and pki.cmp.build counts the body's keys without filtering out the null-valued ones, so
+    // a misspelling set to null is already refused there ("must have exactly one arm, got 2"). The
+    // info() request is the opposite case and does carry a door, because that object is read for a
+    // name and never handed to the builder.
     var arms = Object.keys(request).filter(function (k) { return request[k] != null; });
     if (arms.length !== 1 || !ENROLL_ARMS[arms[0]]) {
       throw _err("cmp/bad-input", "enroll(request) must carry EXACTLY ONE enrollment arm (ir / cr / kur / p10cr)");
@@ -1013,6 +1243,7 @@ function session(opts) {
     }
     inFlight = true;
     try {
+      txnKind = "enroll";
       expectedRespArm = RESPONSE_ARM[arms[0]];   // ir->ip, cr/p10cr->cp, kur->kup: the arm this request must be answered by
       // The certReqId the session echoes in pollReq / certConf and matches in every CertResponse: the caller's
       // CRMF request id (ir / cr / kur) when supplied, else the arm default -- a p10cr has no CRMF id, so a
@@ -1043,8 +1274,519 @@ function session(opts) {
     }
   }
 
+  // RFC 9483 sec. 4.2: "The revocation request message MUST be signed using the certificate that is to
+  // be revoked to prove the authorization to revoke." The signature over this message IS the
+  // authorization, so the certificate named in certDetails has to be the one this session protects with.
+  // Both request shapes are compared here, through the same encode-then-read path, so the certificate
+  // form and the explicit certDetails form cannot diverge on what counts as the same certificate.
+  // The issuer comparison is the RFC 5280 sec. 7.1 canonical one, since two spellings of a
+  // distinguished name name the same issuer and a byte compare would refuse a caller who wrote it out.
+  function _assertRevokingOwnCertificate(certTemplateDer) {
+    var own;
+    try {
+      own = guard.parsed.acceptDerived(opts.cert, "certificate", x509.parse, _err, "cmp/bad-input", "opts.cert");
+    } catch (e) {
+      if (e && e.isCmpError) throw e;
+      throw _err("cmp/bad-input", "opts.cert must be a certificate to revoke one (RFC 9483 sec. 4.2)", e);
+    }
+    var tmpl = schemaCrmf.walkCertTemplate(asn1.decode(certTemplateDer));
+    var sameSerial = tmpl.serialNumber != null && own.serialNumber != null && BigInt(tmpl.serialNumber) === BigInt(own.serialNumber);
+    var sameIssuer = tmpl.issuer != null && guard.name.dnEqual(tmpl.issuer.rdns, own.issuer.rdns, _err, "cmp/bad-input", "the revoked certificate issuer");
+    if (!sameSerial || !sameIssuer) {
+      throw _err("cmp/bad-input", "a session revokes ITS OWN certificate: the issuer and serialNumber in certDetails must name opts.cert, because the signature over the request is the proof of authorization to revoke (RFC 9483 sec. 4.2). Revocation on behalf of another entity is an RA operation -- drive it with pki.cmp.build + pki.cmp.transfer.");
+    }
+    return own;   // the parsed session certificate, so the response's revCerts can be bound to it
+  }
+
+  // An rp MAY name the certificates it revoked in revCerts (RFC 4210 RevRepContent). This session
+  // revokes exactly one -- its own -- so a conforming rp names exactly that one, and a response that
+  // names another issuer/serial, or several, is not a verdict about this request. Left unbound, a
+  // verified verdict would report an unrelated certificate as revoked. Compared to the session
+  // certificate `own` the request was already held to, by serialNumber and the RFC 5280 sec. 7.1
+  // canonical issuer rule. A CertId issuer is a GeneralName; a certificate's issuer is a directoryName,
+  // so any other arm cannot name the revoked certificate.
+  function _bindRevCerts(revCerts, own) {
+    if (revCerts == null) return null;
+    if (revCerts.length !== 1) {
+      throw _err("cmp/bad-rev-rep", "an rp for a single revocation must name exactly one certificate in revCerts (RFC 9483 sec. 4.2); got " + revCerts.length);
+    }
+    var cid = revCerts[0];
+    var dn = cid.issuer && cid.issuer.tagClass === "context" && cid.issuer.tagNumber === 4 ? cid.issuer.value : null;
+    var sameSerial = cid.serialNumber != null && own.serialNumber != null && BigInt(cid.serialNumber) === BigInt(own.serialNumber);
+    var sameIssuer = dn != null && guard.name.dnEqual(dn.rdns, own.issuer.rdns, _err, "cmp/bad-rev-rep", "the revCerts issuer");
+    if (!sameSerial || !sameIssuer) {
+      throw _err("cmp/bad-rev-rep", "the rp revCerts names a certificate other than the one this session revoked (RFC 9483 sec. 4.2), so a verified verdict must not report it as revoked");
+    }
+    return revCerts;
+  }
+
+  /**
+   * Request revocation of this session's own certificate (RFC 9483 sec. 4.2).
+   * `request` is `{ certificate }` or `{ certDetails: { issuer, serialNumber } }`, plus an optional
+   * `reason` (a CRLReason name). Returns a terminal verdict: `revoked`, `rejected`, or `poll-timeout`.
+   */
+  async function revoke(request) {
+    _assertFresh("revocation");
+    guard.identifier.assertPlainRecord(request, _err, "cmp/bad-input", "revoke(request), an object { certificate | certDetails, reason? },");
+    guard.identifier.assertKnownKeys(request, KNOWN_REVOKE_KEYS, _err, "cmp/bad-input", "unknown revoke request field ");
+    // A PBMAC1 session shares a secret with the CA; it holds no certificate, so it has nothing to sign
+    // the request with and no way to demonstrate which certificate it is entitled to revoke.
+    if (isMac) throw _err("cmp/bad-input", "a PBMAC1 session cannot revoke: the request must be signature-protected with the certificate being revoked (RFC 9483 sec. 4.2). Use a signature session ({ key, cert }).");
+    // Each field is read ONCE, here, and every use below is of the value that was read. A caller
+    // field can be an accessor, so a second read can answer with a different certificate or reason
+    // from the one that was checked, and the message would carry what the checks never saw.
+    var certificateArg = request.certificate, reasonArg = request.reason;
+    var certDetails = request.certDetails;
+    if ((certificateArg == null) === (certDetails == null)) {
+      throw _err("cmp/bad-input", "revoke(request) names the certificate by EXACTLY ONE of certificate (the certificate itself) or certDetails ({ issuer, serialNumber })");
+    }
+    if (reasonArg != null && (typeof reasonArg !== "string" || !CRL_REASON_NAMES[reasonArg])) {
+      throw _err("cmp/bad-input", "revoke request.reason must be a CRLReason name (RFC 5280 sec. 5.3.1); got " + JSON.stringify(reasonArg));
+    }
+    if (certificateArg != null) {
+      var target;
+      try {
+        target = guard.parsed.acceptDerived(certificateArg, "certificate", x509.parse, _err, "cmp/bad-input", "revoke request.certificate");
+      } catch (e) {
+        if (e && e.isCmpError) throw e;
+        throw _err("cmp/bad-input", "revoke request.certificate must be a certificate (DER / PEM / parsed)", e);
+      }
+      certDetails = { issuer: target.issuer.bytes, serialNumber: target.serialNumber };
+    }
+    // Encode the CertTemplate HERE rather than letting cmp.build do it, so the identity check below
+    // reads the same bytes the message will carry instead of a second interpretation of the spec.
+    var certTemplateDer;
+    try {
+      certTemplateDer = crmfSign.buildCertTemplate(certDetails);
+    } catch (e) {
+      if (e && e.isCmpError) throw e;
+      throw _err("cmp/bad-rev-req", "revoke request.certDetails must be a CertTemplate naming issuer and serialNumber -- " + ((e && e.message) || e), e);
+    }
+    var own = _assertRevokingOwnCertificate(certTemplateDer);
+    // sec. 4.2: exactly one RevDetails, and crlEntryDetails REQUIRED carrying one reasonCode. The
+    // builder emits the reasonCode even at unspecified(0), which the same clause requires.
+    var body = { rr: [{ certDetails: certTemplateDer, crlEntryDetails: { reason: reasonArg == null ? undefined : reasonArg } }] };
+    inFlight = true;
+    try {
+      var out = await _runOneShot(body, "rr", "revoke");
+      if (out.timeout) return _terminal("poll-timeout", { status: out.status, polls: out.polls });
+      var t = out.done;
+      if (t.state === "granted") {
+        return _terminal("revoked", {
+          status: t.status, polls: out.polls,
+          revokedCerts: _bindRevCerts(t.revCerts, own),   // the CertIds the responder confirms it revoked, bound to the certificate this session revoked
+          // An rp MAY deliver CRLs, and the schema reads those slots as raw SEQUENCEs for the same
+          // reason it does in a genp. They are surfaced on a verdict an operator acts on, so they
+          // are held to being CertificateLists here, exactly as the support-message values are.
+          crls: (t.crls || []).map(_asCrl),
+        });
+      }
+      if (t.state === "rejected") return _terminal("rejected", { status: t.status || null, polls: out.polls });
+      throw _err("cmp/unexpected-arm", t.reason || "the revocation transaction reached an unexpected state");
+    } finally {
+      inFlight = false;
+      completed = started;
+    }
+  }
+
+  /**
+   * Ask the PKI management entity for one of the RFC 9483 sec. 4.3 support values.
+   * `request` names exactly one operation: `{ caCerts: true }`, `{ rootCaCert: <cert> }`,
+   * `{ certReqTemplate: true }`, or `{ crlUpdate: { issuer, dpn?, thisUpdate? } }`.
+   * Returns a terminal verdict: `answered` (with `value` and `present`), `rejected`, or `poll-timeout`.
+   */
+  async function info(request) {
+    _assertFresh("support message");
+    guard.identifier.assertPlainRecord(request, _err, "cmp/bad-input", "info(request), an object naming one support operation (caCerts / rootCaCert / certReqTemplate / crlUpdate),");
+    // The name door runs BEFORE the arm count, so a key that is not an operation is refused whatever
+    // its value is. Counting non-null keys alone would let a misspelled one set to null pass as
+    // absent, and the caller would watch a different operation go out than the one they wrote.
+    guard.identifier.assertKnownKeys(request, INFO_OPS, _err, "cmp/bad-input", "unknown info request field ");
+    // Each field is read ONCE, here, and everything below uses the value that was read. A caller
+    // field can be an accessor, so a second read can answer with a different request from the one
+    // the arm count was taken over, and what goes on the wire would not be what was checked.
+    var keys = Object.keys(request), names = [], values = [];
+    for (var ki = 0; ki < keys.length; ki++) {
+      var kv = request[keys[ki]];
+      if (kv == null) continue;
+      names[names.length] = keys[ki];
+      values[values.length] = kv;
+    }
+    if (names.length !== 1) {
+      throw _err("cmp/bad-input", "info(request) must name EXACTLY ONE support operation (caCerts / rootCaCert / certReqTemplate / crlUpdate); a genm carries a sequence of one InfoTypeAndValue (RFC 9483 sec. 4.3)");
+    }
+    var op = INFO_OPS[names[0]], asked = values[0];
+    var itav = { infoType: op.requestOid };
+    // sec. 4.3.1 and sec. 4.3.3 both make the request infoValue absent; the other two carry one.
+    // For the two that carry none, the only accepted value is `true` -- a caller who supplies a
+    // certificate or a template to one of them means something this operation cannot send, and
+    // taking it silently would have the request go out without the constraint they wrote.
+    if (op.value === false) {
+      if (asked !== true) throw _err("cmp/bad-input", "info request." + op.name + " takes `true`: this operation's genm carries no infoValue (RFC 9483 sec. 4.3.1 and sec. 4.3.3)");
+    } else if (op.value === "cert") {
+      // sec. 4.3.2: the request SHOULD carry the root CA certificate the update is requested for,
+      // and the field is a CMPCertificate. It goes through the SAME door revoke() gives a
+      // certificate -- DER, PEM, or an already-parsed one -- because it is the same kind of value
+      // and a caller should not have to remember which of the two verbs takes which form. Holding
+      // it to being a certificate here keeps a mistake a local refusal; sending it unchecked would
+      // put a malformed request on the wire and consume this one-shot transaction to learn what the
+      // caller could have been told before it started.
+      var rootCaCertDer = _certificateArgument(asked, "info request rootCaCert");
+      // sec. 4.3.2: rootCaCert names the CURRENT root the update chains from, which is a CA. An
+      // end-entity certificate here would let a cross-certificate signed by that non-CA key read as a
+      // rollover (the response path verifies newWithOld / oldWithNew against this certificate's key), so
+      // it is held to being a CA before the one-shot transaction engages rather than after.
+      _assertCaCapable(x509.parse(rootCaCertDer), "info request rootCaCert", "cmp/bad-input");
+      itav.infoValue = rootCaCertDer;
+    } else if (op.value === "crlStatus") {
+      var built = cmpBuild.buildCrlStatusList(asked);
+      itav.infoValue = built.der;
+      // What the request asked for, kept so the answer can be held to it. sec. 4.3.4 says the
+      // responder returns the latest CRL FROM THE REFERENCED SOURCE, and only when it is more
+      // recent than a supplied thisUpdate; in every other case the response value is absent.
+      // The cutoff comes back FROM the builder, which read it once while encoding. Reading the
+      // caller's field a second time here would let an accessor, or a Date moved during the
+      // transport round-trip, judge the response against a query the request never carried.
+      crlQuery = { issuerName: built.issuerName, thisUpdate: built.thisUpdate, dpn: built.dpn };
+    }
+    expectedInfoOp = op;
+    inFlight = true;
+    try {
+      var out = await _runOneShot({ genm: [itav] }, "genm", "info");
+      if (out.timeout) return _terminal("poll-timeout", { operation: op.name, status: out.status, polls: out.polls });
+      var t = out.done;
+      if (t.state === "granted") {
+        // sec. 4.3: the infoValue is OPTIONAL in every one of the four responses, and its absence is
+        // the answer "nothing is available" rather than a malformed message -- so `present` reports
+        // which of the two a caller received, and never conflates them into an empty value.
+        var raw = t.itav.value;
+        var value = null;
+        if (raw != null) {
+          try {
+            value = schemaCmp[op.read](raw);
+          } catch (e) {
+            if (e && e.isCmpError) throw e;
+            throw _err("cmp/bad-info-value", "the " + op.name + " response value is malformed -- " + ((e && e.message) || e), e);
+          }
+          value = await _checkInfoValue(op, value, itav.infoValue);
+        }
+        return _terminal("answered", { operation: op.name, present: raw != null, value: value, status: null, polls: out.polls });
+      }
+      if (t.state === "rejected") return _terminal("rejected", { operation: op.name, status: t.status || null, polls: out.polls });
+      throw _err("cmp/unexpected-arm", t.reason || "the support-message transaction reached an unexpected state");
+    } finally {
+      inFlight = false;
+      completed = started;
+    }
+  }
+
+  // The RFC 9483 profile rules that sit ON TOP of the RFC 9480 syntax the decoders enforce. Each is a
+  // requirement the ASN.1 cannot express, so a structurally valid response can still be non-conforming.
+  // `requestValue` is the infoValue this operation SENT, which the rootCaCert rules compare against:
+  // the old root the caller named is what the update has to chain from. It is read here rather than
+  // off `request`, so the comparison uses the bytes that went on the wire.
+  function _checkInfoValue(op, value, requestValue) {
+    if (op.name === "rootCaCert") {
+      // sec. 4.3.2 makes newWithOld REQUIRED of a response ("it is needed for the receiving entity
+      // trusting the old root CA certificate to gain trust in the new one"), where RFC 9480's ASN.1
+      // marks it OPTIONAL. Without it the update cannot be trusted by the entity that asked for it.
+      if (value.newWithOld == null) throw _err("cmp/bad-info-value", "a rootCaKeyUpdate response must carry newWithOld -- the certificate that lets an entity trusting the OLD root gain trust in the new one (RFC 9483 sec. 4.3.2)");
+      return _checkRootCaKeyUpdate(value, requestValue);
+    }
+    if (op.name === "certReqTemplate") {
+      var t = value.certTemplate;
+      // sec. 4.3.3: "The publicKey field of type SubjectPublicKeyInfo in the CertTemplate of the
+      // CertReqTemplateValue MUST be omitted", and "the serialNumber, signingAlg, issuerUID, and
+      // subjectUID fields MUST be omitted". A template stating a key would tell an entity to request
+      // a certificate over a key the responder chose, which is what the keySpec field exists to avoid.
+      ["publicKey", "serialNumber", "signingAlg", "issuerUID", "subjectUID"].forEach(function (f) {
+        if (t[f] != null) throw _err("cmp/bad-info-value", "a certReqTemplate certTemplate must omit " + f + " (RFC 9483 sec. 4.3.3)");
+      });
+      if (value.keySpec != null) value.keySpec.forEach(_checkKeySpec);
+      return value;
+    }
+    if (op.name === "caCerts") return value.map(function (d) {
+      // sec. 4.3.1 returns CA certificates for chain construction, so each is held to being one: an
+      // authenticated responder placing an end-entity certificate here would hand back a list nothing
+      // can chain through. The same CA-capability rule the rootCaKeyUpdate rollover certificates get.
+      var der = _asCertificate(d, "a caCerts entry");
+      _assertCaCapable(x509.parse(der), "caCerts entry");
+      return der;
+    });
+    if (op.name === "crlUpdate") {
+      // sec. 4.3.4: the request carries exactly one CRLStatus (one source), and the response "represents
+      // the latest CRL available from the referenced CRL source" -- one CRL. The ASN.1 list is SIZE
+      // (1..MAX), so the responder could return several; accepting them all would surface an older CRL
+      // beside the latest and let a caller act on a stale value[0]. Exactly one is required, and it is
+      // then bound to the query that asked for it.
+      if (value.length !== 1) throw _err("cmp/bad-info-value", "a crlUpdate response answers a single-source query with exactly one CRL -- the latest from the named source (RFC 9483 sec. 4.3.4); got " + value.length);
+      return value.map(_bindCrlToQuery);
+    }
+    // Unreachable while INFO_OPS holds exactly the four operations above, each with a branch here.
+    // It refuses rather than passing the value through, so adding a fifth operation without its
+    // profile rules fails at once instead of surfacing a value nothing checked.
+    throw _err("cmp/bad-info-value", "no response rules are defined for the " + op.name + " support message");
+  }
+
+  // A support-message response is surfaced as an ANSWER an operator acts on, so what it carries is
+  // held to being the structure it claims. The CMP schema reads these slots as raw SEQUENCEs on
+  // purpose (the parser confers no trust and a CMPCertificate slot is opaque to it), which leaves
+  // "is this actually a certificate" to the verb that hands the bytes back -- the same division
+  // this module already applies to an authenticated caPubs entry. Without it a responder could
+  // answer a chain-construction request with any well-formed SEQUENCE and have it read as a
+  // certificate, and a CRL request with a certificate. Returns a COPY, since the decoded value is
+  // a slice of the response buffer.
+  // A root CA key update is three certificates in NAMED relationships, and the relationships are the
+  // whole mechanism (RFC 9483 sec. 4.3.2): newWithOld carries "the new public root CA key signed
+  // with the old private root CA key", which is what lets an entity that trusts the old root reach
+  // the new one, and oldWithNew carries "the old public root CA key signed with the new private root
+  // CA key" for the reverse. Three certificates that merely parse establish neither, so a responder
+  // could answer with any three it holds and the update would be reported as usable. Each signature
+  // is checked by the path engine, so the EdDSA low-order-point and algorithm-confusion gates apply
+  // here as they do to any other untrusted signature.
+  async function _checkRootCaKeyUpdate(value, oldRootDer) {
+    var newWithNew = _asCertificate(value.newWithNew, "the rootCaKeyUpdate newWithNew");
+    var newWithOld = _asCertificate(value.newWithOld, "the rootCaKeyUpdate newWithOld");
+    var oldWithNew = value.oldWithNew == null ? null : _asCertificate(value.oldWithNew, "the rootCaKeyUpdate oldWithNew");
+    var pNewNew = x509.parse(newWithNew), pNewOld = x509.parse(newWithOld), pOldRoot = x509.parse(oldRootDer);
+    _assertCaCapable(pNewNew, "rootCaKeyUpdate newWithNew");
+    _assertCaCapable(pNewOld, "rootCaKeyUpdate newWithOld");
+    if (!cmpBuild.samePublicKey(pNewOld.subjectPublicKeyInfo.bytes, pNewNew.subjectPublicKeyInfo.bytes)) {
+      throw _err("cmp/bad-info-value", "the rootCaKeyUpdate newWithOld must certify the NEW root key, the one newWithNew carries (RFC 9483 sec. 4.3.2)");
+    }
+    // A key alone does not make a trust transition. If the old CA has ever signed ANY certificate
+    // for the new key -- an ordinary end-entity certificate its holder legitimately obtained --
+    // then key equality plus a valid signature is satisfied by that certificate, and its holder
+    // could pair it with a self-signed newWithNew of their own choosing and have the result read as
+    // the authority's own rollover. What sec. 4.3.2 describes is a certificate FOR the new root
+    // issued BY the old one, so both names are bound too, under the RFC 5280 sec. 7.1 comparison.
+    _assertSameName(pNewOld.issuer, pOldRoot.subject, "newWithOld", "be issued by the OLD root named in the request");
+    _assertSameName(pNewOld.subject, pNewNew.subject, "newWithOld", "name the same subject as newWithNew, the certificate it vouches for");
+    // newWithNew is the replacement certificate, and for a root it is self-issued, so its own key is
+    // the only thing that can vouch for the name, validity and extensions the caller would install.
+    // sec. 4.3.2's note extends this operation to "trusted non-root certificates, e.g., directly
+    // trusted intermediate or issuing CA certificates", and such a certificate is signed by an
+    // issuer this message does not carry -- there is nothing here to check it against, and claiming
+    // otherwise would refuse a use the profile allows. So the signature is verified exactly when it
+    // is verifiable: when the certificate is self-issued. Either way the new KEY is authenticated by
+    // newWithOld below, which the old root signed and which must carry this same key.
+    if (guard.name.dnEqual(pNewNew.issuer.rdns, pNewNew.subject.rdns, _err, "cmp/bad-info-value", "the rootCaKeyUpdate newWithNew name")) {
+      await _assertSignedBy(pNewNew, pNewNew, "newWithNew", "its own key, which a self-issued root certificate must be");
+    }
+    await _assertSignedBy(pNewOld, pOldRoot, "newWithOld", "the OLD root CA key");
+    if (oldWithNew !== null) {
+      var pOldNew = x509.parse(oldWithNew);
+      _assertCaCapable(pOldNew, "rootCaKeyUpdate oldWithNew");
+      if (!cmpBuild.samePublicKey(pOldNew.subjectPublicKeyInfo.bytes, pOldRoot.subjectPublicKeyInfo.bytes)) {
+        throw _err("cmp/bad-info-value", "the rootCaKeyUpdate oldWithNew must certify the OLD root key (RFC 9483 sec. 4.3.2)");
+      }
+      _assertSameName(pOldNew.issuer, pNewNew.subject, "oldWithNew", "be issued by the NEW root");
+      _assertSameName(pOldNew.subject, pOldRoot.subject, "oldWithNew", "name the OLD root it vouches for");
+      await _assertSignedBy(pOldNew, pNewNew, "oldWithNew", "the NEW root CA key");
+    }
+    return { newWithNew: newWithNew, newWithOld: newWithOld, oldWithNew: oldWithNew };
+  }
+  // A certificate a caller will build a chain from -- a rootCaKeyUpdate rollover certificate or a
+  // caCerts entry -- has to actually be a CA. Names, a key and a signature are satisfied by an
+  // ordinary end-entity certificate that certifies nothing, so surfacing one as an issuer reports the
+  // answer as usable while handing back a list nothing can chain through. The rule is RFC 5280 sec.
+  // 6.1.4's, the one pki.path.validate applies to any intermediate: basicConstraints cA TRUE, marked
+  // critical (sec. 4.2.1.9), and keyUsage, where present, allowing keyCertSign. Criticality matters
+  // because a relying party that skips extensions it does not recognize would not see the cA bit at
+  // all, which is why the path validator refuses a non-critical cA:TRUE; this check holds to the same
+  // line so the two never disagree on what a CA certificate is. `which` names the surface for the
+  // error. Extensions are read through the shared certificate-extension decoders rather than walked here.
+  function _assertCaCapable(cert, which, code) {
+    code = code || "cmp/bad-info-value";   // a response cert is cmp/bad-info-value; a caller-supplied one (rootCaCert request) is cmp/bad-input
+    var bc = null, ku = null, bcCritical = false;
+    cert.extensions.forEach(function (e) {
+      if (e.oid === OID_BASIC_CONSTRAINTS) { bc = cmpBuild.decodeCertExtension(e.oid, e.value); bcCritical = e.critical === true; }
+      if (e.oid === OID_KEY_USAGE) ku = cmpBuild.decodeCertExtension(e.oid, e.value);
+    });
+    if (!bc || bc.cA !== true) {
+      throw _err(code, "the " + which + " must be a CA certificate (basicConstraints cA TRUE): an end-entity certificate certifies nothing and cannot serve as an issuer for chain construction (RFC 5280 sec. 6.1.4)");
+    }
+    if (!bcCritical) {
+      throw _err(code, "the " + which + " marks basicConstraints non-critical, so a relying party that skips unrecognized extensions would not see the cA bit it must act on (RFC 5280 sec. 4.2.1.9)");
+    }
+    if (ku && ku.keyCertSign !== true) {
+      throw _err(code, "the " + which + " carries a keyUsage that withholds keyCertSign, so it cannot sign certificates as a CA must (RFC 5280 sec. 6.1.4)");
+    }
+  }
+
+  // Names are compared through guard-name's RFC 5280 sec. 7.1 canonical rule, the one place a
+  // distinguished-name identity is decided here: two spellings of the same name are the same
+  // authority, and a byte compare would refuse a re-encoded but equal one.
+  function _assertSameName(a, b, which, must) {
+    if (!guard.name.dnEqual(a.rdns, b.rdns, _err, "cmp/bad-info-value", "a rootCaKeyUpdate name")) {
+      throw _err("cmp/bad-info-value", "the rootCaKeyUpdate " + which + " must " + must + " (RFC 9483 sec. 4.3.2); got " + JSON.stringify(a.dn));
+    }
+  }
+  async function _assertSignedBy(cert, signer, which, whose) {
+    if (!_engine || !_engine.verifyWithSpki) {
+      throw _err("cmp/bad-info-value", "the signature engine is unavailable, so a rootCaKeyUpdate cannot be checked; require pki.path to install it");
+    }
+    // The signature is a BIT STRING and a valid one is octet-aligned (no unused bits). Passing only its
+    // octets to the engine would drop the unusedBits metadata, so a signature declaring unused bits would
+    // verify on its octets while being a malformed shape the path verifier refuses (path-validate) before
+    // the engine. Hold a rollover signature to the same rule.
+    if (!guard.crypto.isOctetAligned(cert.signatureValue)) {
+      throw _err("cmp/bad-info-value", "the rootCaKeyUpdate " + which + " signature is not octet-aligned (a BIT STRING with unused bits), which no valid signature is (RFC 9483 sec. 4.3.2)");
+    }
+    var ok = await _engine.verifyWithSpki(cert.signatureAlgorithm, cert.signatureValue.bytes, signer.subjectPublicKeyInfo.bytes, cert.tbsBytes);
+    if (ok !== true) {
+      throw _err("cmp/bad-info-value", "the rootCaKeyUpdate " + which + " is not signed by " + whose + ", so it cannot carry the trust transition it exists for (RFC 9483 sec. 4.3.2)");
+    }
+  }
+
+  // A certificate this verb has to put BACK on the wire, so it takes the two forms that carry their
+  // own bytes: DER, and PEM which decodes to them. An already-parsed certificate is refused rather
+  // than re-encoded -- the parsed form retains no source DER, and rebuilding one would emit bytes
+  // that are not the ones the issuer signed. revoke() takes the parsed form because it reads an
+  // issuer and a serial out of it and never re-emits the certificate itself.
+  function _certificateArgument(value, what) {
+    var der;
+    if (typeof value === "string") {
+      try { der = x509.pemDecode(value); }
+      catch (e) { throw _err("cmp/bad-input", what + " is a string but not a PEM certificate", e); }
+    } else if (value != null && Buffer.isBuffer(value.tbsBytes)) {
+      throw _err("cmp/bad-input", what + " must carry the certificate's own bytes (DER or PEM): a parsed certificate keeps no source DER, and this request has to send the bytes the issuer signed");
+    } else {
+      der = guard.bytes.snapshot(value, CmpError, "cmp/bad-input", what);
+    }
+    return _asCertificate(der, what, "cmp/bad-input");
+  }
+
+  // `code` names the boundary: a response value is malformed protocol (cmp/bad-info-value), while a
+  // value the CALLER supplied for a request is an authoring error (cmp/bad-input), and the two must
+  // not read alike to whoever catches them.
+  function _asCertificate(der, what, code) {
+    try { x509.parse(der); }
+    catch (e) { throw _err(code || "cmp/bad-info-value", what + " is not a valid X.509 certificate (RFC 9483 sec. 4.3)", e); }
+    return Buffer.from(der);
+  }
+  function _asCrl(der) {
+    try { schemaCrl.parse(der); }
+    catch (e) { throw _err("cmp/bad-info-value", "a crlUpdate entry is not a valid CertificateList (RFC 9483 sec. 4.3.4)", e); }
+    return Buffer.from(der);
+  }
+  // sec. 4.3.4 does not say "a CRL", it says the latest one FROM THE REFERENCED SOURCE, and only
+  // when it is more recent than a supplied thisUpdate; in every other case the value is absent.
+  // A CRL that answers some other query is not the answer to this one, and reporting it as one
+  // hands the caller a list whose scope they did not ask about.
+  //
+  // The issuer arm is bound by name. The dpn arm is bound where a CRL says which point it speaks
+  // for: RFC 5280 sec. 5.2.5 puts that in the issuingDistributionPoint extension, and sec. 4.3.4's
+  // own note points there for where a distribution point name comes from. A CRL carrying no such
+  // scope is claiming to be its issuer's complete list, which sec. 5.2.5 permits and which answers
+  // a request for any point of that issuer, so there is nothing to refuse -- and nothing to bind,
+  // since the request named no issuer. The freshness rule applies to both arms.
+  function _bindCrlToQuery(der) {
+    var parsed;
+    try { parsed = schemaCrl.parse(der); }
+    catch (e) { throw _err("cmp/bad-info-value", "a crlUpdate entry is not a valid CertificateList (RFC 9483 sec. 4.3.4)", e); }
+    if (crlQuery && crlQuery.issuerName != null) {
+      var want = schemaCmp.readName(crlQuery.issuerName);
+      if (!guard.name.dnEqual(parsed.issuer.rdns, want.rdns, _err, "cmp/bad-info-value", "the crlUpdate issuer")) {
+        throw _err("cmp/bad-info-value", "the returned CRL was issued by " + JSON.stringify(parsed.issuer.dn) + ", not by the source this request named (RFC 9483 sec. 4.3.4)");
+      }
+    }
+    if (crlQuery && crlQuery.dpn != null) {
+      var idpDpn = null, idpCritical = false, crlExts = parsed.crlExtensions || [];
+      for (var xi = 0; xi < crlExts.length; xi++) {
+        if (crlExts[xi].oid !== OID_IDP) continue;
+        idpDpn = cmpBuild.decodeIdpDistributionPoint(crlExts[xi].value);
+        idpCritical = crlExts[xi].critical === true;
+        break;
+      }
+      // The comparison is the one the path validator applies to a shard CRL, so a CRL either speaks
+      // for the point this request named or it does not, and the answer does not depend on which verb
+      // is asking. Only a CRITICAL issuingDistributionPoint establishes that scope (sec. 5.2.5): a
+      // relying party may ignore a non-critical one, so a scope it could ignore cannot bind the answer
+      // to the named point -- the path validator makes the same fail-closed decision for a shard CRL.
+      // A CRL naming no point is a complete list and is left to the freshness rule.
+      if (idpDpn !== null && (!idpCritical || !guard.name.dpnCorresponds(crlQuery.dpn, idpDpn, _err, "cmp/bad-info-value", "the crlUpdate distribution point"))) {
+        throw _err("cmp/bad-info-value", "the returned CRL is scoped to a distribution point other than the one this request named, or marks that scope non-critical where a relying party may ignore it (RFC 9483 sec. 4.3.4, RFC 5280 sec. 5.2.5)");
+      }
+    }
+    if (crlQuery && crlQuery.thisUpdate != null) {
+      var asked = crlQuery.thisUpdate;   // already an instant, reduced when the request was built
+      // The CRL's own thisUpdate goes through the same door: it arrived from a responder, so it is
+      // the side more likely to be missing or unusable, and reading its epoch value directly would
+      // compare NaN and quietly answer false.
+      var got = guard.time.instantOf(parsed.thisUpdate, _err, "cmp/bad-info-value", "the returned CRL's thisUpdate");
+      if (got <= asked) {
+        throw _err("cmp/bad-info-value", "the returned CRL is no more recent than the thisUpdate this request supplied, so sec. 4.3.4 requires the response to carry no value at all");
+      }
+    }
+    return Buffer.from(der);
+  }
+
+  var OID_REG_CTRL_ALG_ID = oid.byName("algId");
+  var OID_REG_CTRL_RSA_KEY_LEN = oid.byName("rsaKeyLen");
+  // True for an RSA algorithm, which sec. 4.3.3 excludes from a keySpec algId (RSA uses rsaKeyLen).
+  // Membership is decided by OID family: any OID under the PKCS#1 arc, plus the two RSA identifiers
+  // that sit off it. A standardized RSA OID the registry has not named (sha1WithRSAEncryption, the
+  // md*/sha224 variants) is still under the arc, so it is caught without being listed. An OID that is
+  // not an encodable dotted string, or one outside every RSA arc, is NOT RSA here -- it is surfaced.
+  function _isRsaAlgorithm(dotted) {
+    if (RSA_ARC_EXCLUDE[dotted] === 1) return false;   // mgf1 / pSpecified: auxiliary OIDs on the PKCS#1 arc, not RSA algorithms
+    var arcs = oid.toArcs(dotted);   // dotted is a decoded OID string (readAlgorithmIdentifier), always encodable
+    var underAny = false;
+    for (var a = 0; !underAny && a < RSA_ARCS.length; a++) {
+      var arc = RSA_ARCS[a];
+      if (arcs.length > arc.length) {   // the arc node itself is not an algorithm
+        underAny = true;
+        for (var i = 0; underAny && i < arc.length; i++) { underAny = arcs[i] === arc[i]; }
+      }
+    }
+    return underAny || RSA_OFF_ARC[dotted] === 1;
+  }
+  // sec. 4.3.3: a keySpec element carries "attribute id-regCtrl-algId or id-regCtrl-rsaKeyLen", the
+  // first "MUST be of type AlgorithmIdentifier and give an algorithm other than RSA", the second
+  // "MUST be a positive integer value". A control outside the pair states a requirement this
+  // operation has no meaning for, so it is refused rather than surfaced as an understood one.
+  function _checkKeySpec(ctrl) {
+    if (ctrl.type === OID_REG_CTRL_RSA_KEY_LEN) {
+      var len;
+      try { len = asn1.read.integer(asn1.decode(ctrl.value)); }
+      catch (e) { throw _err("cmp/bad-info-value", "a keySpec rsaKeyLen must be an INTEGER (RFC 9483 sec. 4.3.3)", e); }
+      if (len <= 0n) throw _err("cmp/bad-info-value", "a keySpec rsaKeyLen must be a positive integer (RFC 9483 sec. 4.3.3); got " + len);
+      ctrl.rsaKeyLen = len;
+      return;
+    }
+    if (ctrl.type === OID_REG_CTRL_ALG_ID) {
+      // Read through the shared AlgorithmIdentifier sub-schema rather than probing the node, so the
+      // structure is held to its whole definition: a SEQUENCE of an OID and at most one parameters
+      // field. A hand-rolled tag test says only that the first child is an OID, which a SEQUENCE of
+      // three fields also satisfies -- and that value would then reach the caller as an algorithm
+      // requirement no conforming responder can have meant.
+      var alg;
+      try { alg = schemaCmp.readAlgorithmIdentifier(ctrl.value); }
+      catch (e) {
+        if (e && e.isCmpError) throw e;
+        throw _err("cmp/bad-info-value", "a keySpec algId must be an AlgorithmIdentifier (RFC 9483 sec. 4.3.3)", e);
+      }
+      // sec. 4.3.3 / RFC 9480 sec. 2.16 hold the algId to ONE rule: not RSA. A known RSA algorithm is
+      // refused (its requirement is stated with rsaKeyLen); every other value -- a known non-RSA
+      // algorithm OR an OID the registry does not name -- is surfaced. The responder offers one control
+      // per algorithm it supports and the entity picks one, so an unrecognized offer must not fail the
+      // whole exchange.
+      if (_isRsaAlgorithm(alg.oid)) {
+        throw _err("cmp/bad-info-value", "a keySpec algId must give an algorithm other than RSA, whose requirement is stated with rsaKeyLen instead (RFC 9483 sec. 4.3.3); got " + (alg.name || alg.oid));
+      }
+      ctrl.algorithm = alg.oid;
+      ctrl.algorithmName = alg.name;   // null for an OID the registry does not name -- surfaced as-is for the caller to weigh
+      ctrl.algorithmParameters = alg.parameters;
+      return;
+    }
+    throw _err("cmp/bad-info-value", "a keySpec control must be id-regCtrl-algId or id-regCtrl-rsaKeyLen (RFC 9483 sec. 4.3.3); got " + ctrl.type);
+  }
+
   return {
     enroll: enroll,
+    revoke: revoke,
+    info: info,
     get transactionID() { return Buffer.from(transactionID); },   // a copy: a caller mutating it must not desync the transaction
     get transcript() { return _transcriptSnapshot(); },   // a defensive snapshot; never the mutable internal array
   };