@blamejs/pki 0.4.14 → 0.5.0

package/lib/framework-error.js

@@ -47,6 +47,7 @@ var CODE_SHAPE = /^[a-z0-9-]+\/[a-z0-9-]+$/;
  * site instead of shipping prose into a code-switching consumer.
  *
  * @example
+ *   var bytes = Buffer.from([0x30, 0x80]);   // indefinite length -- not valid DER
  *   try { pki.asn1.decode(bytes); }
  *   catch (e) {
  *     if (e instanceof pki.errors.PkiError) console.error(e.code);
@@ -88,6 +89,7 @@ class PkiError extends Error {
  *   withCause:  boolean,  // default: false -- constructor becomes (code, message, cause)
  *
  * @example
+ *   // throws: my/bad-input -- raising the new error type IS what this shows
  *   var MyError = pki.errors.defineClass("MyError");
  *   throw new MyError("my/bad-input", "explanation");
  */
@@ -273,6 +275,16 @@ var CsrattrsError = defineClass("CsrattrsError", { withCause: true });
 // `.cause`.
 var EstError = defineClass("EstError", { withCause: true });
 
+// CmcError -- an RFC 5272 / 6402 Certificate Management over CMS message-layer
+// fault: a PKIData / PKIResponse whose structure, body-part identity, control
+// placement or status encoding is malformed, a control this side must act on
+// that cannot be decoded, or an exchange binding (transactionId / recipientNonce)
+// that does not match the request it answers. Distinct from EstError because the
+// CMC layer is the MESSAGE and EST is the TRANSPORT that carried it: an operator
+// needs to know whether the CA's answer was unreadable or the HTTP hop failed.
+// Carries the underlying cms/* or asn1/* leaf fault as `.cause`.
+var CmcError = defineClass("CmcError", { withCause: true });
+
 // TransportError -- a fault from the shared node:https transport (pki.transport):
 // a non-https / unparseable request URL, a missing trust anchor, a TLS handshake /
 // server-authentication failure, a negotiated protocol below the floor, a response
@@ -380,6 +392,7 @@ module.exports = {
   SmimeError:       SmimeError,
   CsrattrsError:    CsrattrsError,
   EstError:         EstError,
+  CmcError:         CmcError,
   TransportError:   TransportError,
   JoseError:        JoseError,
   AcmeError:        AcmeError,

package/lib/guard-bytes.js

@@ -57,4 +57,40 @@ function source(input, ErrorClass, code, label) {
   throw new ErrorClass(code, label + ": expected a BufferSource (ArrayBuffer / TypedArray / Buffer)");
 }
 
-module.exports = { view: view, source: source };
+// snapshot(input, ErrorClass, code, label) -> private Buffer copy | throws ErrorClass
+//
+// The parse-then-verify time-of-check/time-of-use defence. A verification entry
+// point that PARSES its input synchronously and then VERIFIES a signature over
+// the same bytes in a later promise turn is reading the caller's memory twice
+// with an await in between. Every byte range the parse surfaced -- the signed
+// content, the signer set, the values the verdict is built from -- is a VIEW into
+// that memory, so anything that rewrites the buffer in the gap makes the verdict
+// describe bytes other than the ones the signature was checked against
+// (CWE-367 TOCTOU reaching a CWE-347 wrong-verdict). The window is real without
+// an attacker in the process: a caller recycling a pooled read buffer across
+// concurrent verifies hits it by accident.
+//
+// So take one private copy at the boundary and read EVERYTHING from it. `view`
+// re-views and is the right guard where the input is consumed in one synchronous
+// pass; this is its sibling for the boundary that spans an await.
+// @enforced-by behavioral -- a copy has no rename-proof code shape to detect (any
+//   `Buffer.from(x)` is one, and most are legitimate). The guard is the RED vector
+//   that mutates the caller's buffer between parse and verify and asserts the
+//   verdict still describes the bytes that were verified.
+function snapshot(input, ErrorClass, code, label) {
+  return Buffer.from(view(input, ErrorClass, code, label));
+}
+
+// snapshotSource(input, ErrorClass, code, label) -> private Buffer copy | throws
+// The same parse-then-verify defence as `snapshot`, over the FULL W3C BufferSource
+// (raw ArrayBuffer / DataView / any typed-array view) rather than only the
+// Buffer / Uint8Array contract. A parser that accepts a BufferSource must snapshot
+// the same set: leaving an ArrayBuffer or a DataView aliased reopens the window for
+// exactly the inputs that took the wider path in.
+// @enforced-by behavioral -- a copy has no rename-proof shape to detect; the guard
+//   is the RED vector that mutates the caller's backing buffer across the await.
+function snapshotSource(input, ErrorClass, code, label) {
+  return Buffer.from(source(input, ErrorClass, code, label));
+}
+
+module.exports = { view: view, source: source, snapshot: snapshot, snapshotSource: snapshotSource };

package/lib/guard-range.js

@@ -99,4 +99,26 @@ function uint64(value, E, code, label) {
   return v;
 }
 
-module.exports = { int: int, uint31: uint31, positiveInt31: positiveInt31, uint64: uint64 };
+// authoredInteger(value, E, code, label) -> BigInt. The AUTHORING counterpart to
+// int(): a value a CALLER supplies for an ASN.1 INTEGER with no upper bound (a CMC
+// Transaction Identifier, a CRMF certReqId), normalized to the BigInt the builders
+// take. Accepts a bigint, or a Number that is a SAFE integer -- isSafeInteger, not
+// isInteger, because a Number above 2^53 has already lost precision by the time it
+// arrives, so a large identifier MUST come as a bigint rather than be silently
+// rounded to a neighbour. Everything else is a config-time reject.
+//
+// Distinct from int() on purpose: int() BOUNDS a value the wire decoded and narrows
+// it to Number; this one is unbounded and returns BigInt, because the field has no
+// ceiling to check against and the encoder wants the wide type.
+// @enforced-by guard-shape-reinlined
+// @guard-shape Number\.isSafeInteger\(\s*[A-Za-z_$][\w$]*\s*\)\s*\)\s*return BigInt
+function authoredInteger(value, E, code, label) {
+  if (typeof value === "bigint") return value;
+  if (typeof value === "number" && Number.isSafeInteger(value)) return BigInt(value);
+  throw E(code, label + " must be an integer (a safe-integer number, or a bigint for a large value)");
+}
+
+module.exports = {
+  int: int, uint31: uint31, positiveInt31: positiveInt31, uint64: uint64,
+  authoredInteger: authoredInteger,
+};

package/lib/http-transport.js

@@ -13,11 +13,17 @@
  *   drive -- `pki.est` now, `pki.acme` and `pki.cmp` next. This is the ONLY module in
  *   the toolkit that opens a socket; every protocol layer stays transport-agnostic and
  *   composes it (or an injected substitute) through one contract:
- *   `transport(request) -> Promise<{ status, headers, body }>`. The response triple is
+ *   `transport(request) -> Promise<{ status, headers, body, tls }>`. The first three are
  *   exactly what a message layer's classifier consumes, so no protocol semantics leak
  *   into the socket layer -- the transport owns socket lifecycle, the TLS trust policy,
  *   the streaming size cap, and the timeout budget; the caller owns HTTP status,
- *   content-type, redirect, and authentication decisions.
+ *   content-type, redirect, and authentication decisions. `tls` reports the negotiated
+ *   channel -- `{ protocol, cipher, peerCertificate }` -- which is the one fact a caller
+ *   cannot recover from the response bytes. An INJECTED substitute should return it too:
+ *   `pki.est.serverkeygen` asserts the negotiated cipher can protect the private key it
+ *   is about to accept, and a transport that reports no cipher is trusted rather than
+ *   refused (so a loopback test channel works), which means omitting the field silently
+ *   skips that assertion.
  *
  *   `pki.transport.https(defaults?)` binds TLS + budget defaults and returns a
  *   transport. Trust is EXPLICIT and fail-closed: a request is refused unless it
@@ -33,7 +39,7 @@
  * @card
  *   The shared fail-closed node:https transport (est / acme / cmp): explicit trust
  *   anchors, rejectUnauthorized always on, a TLS floor, a streaming response-size cap,
- *   and a timeout -- behind one `transport(request) -> {status, headers, body}` seam.
+ *   and a timeout -- behind one `transport(request) -> {status, headers, body, tls}` seam.
  */
 
 var nodeHttps = require("node:https");

package/lib/inspect.js

@@ -607,7 +607,7 @@ function _parse(input) {
  * @primitive pki.inspect.certificate
  * @signature pki.inspect.certificate(input) -> string
  * @since 0.2.4
- * @status experimental
+ * @status stable
  * @spec RFC 5280
  * @related pki.schema.x509.parse
  *
@@ -618,6 +618,10 @@ function _parse(input) {
  * hex dump rather than failing the whole report. Pure -- no OpenSSL dependency.
  *
  * @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 cert = pki.schema.x509.parse(der);
  *   pki.inspect.certificate(cert).split("\n")[0]; // "Certificate:"
  */
@@ -753,7 +757,7 @@ function _crlExtension(ext, pad) {
  * @primitive pki.inspect.crl
  * @signature pki.inspect.crl(input) -> string
  * @since 0.3.8
- * @status experimental
+ * @status stable
  * @spec RFC 5280
  * @related pki.schema.crl.parse, pki.inspect.certificate
  *
@@ -765,6 +769,13 @@ function _crlExtension(ext, pad) {
  * extension renders as hex rather than failing the report.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var caCert = await pki.x509.sign({ subject: "Issuing CA", 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: ["cRLSign"] } }, { key: key });
+ *   var crlDer = await pki.crl.sign({ thisUpdate: new Date("2026-01-01T00:00:00Z"), crlNumber: 1n, revoked: [] },
+ *     { cert: caCert, key: key });
  *   pki.inspect.crl(crlDer).split("\n")[0]; // "Certificate Revocation List (CRL):"
  */
 function crlReport(input) {
@@ -818,7 +829,7 @@ function _attribute(attr, pad) {
  * @primitive pki.inspect.csr
  * @signature pki.inspect.csr(input) -> string
  * @since 0.3.8
- * @status experimental
+ * @status stable
  * @spec RFC 2986
  * @related pki.schema.csr.parse, pki.inspect.certificate
  *
@@ -829,6 +840,9 @@ function _attribute(attr, pad) {
  * input `inspect/bad-input`. Best-effort like `certificate`.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var csrDer = await pki.csr.sign({ subject: "req.example", subjectPublicKey: await pki.key.export(pair.publicKey) },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   pki.inspect.csr(csrDer).split("\n")[0]; // "Certificate Request:"
  */
 function csrReport(input) {
@@ -927,7 +941,7 @@ function _signerInfo(si, pad) {
  * @primitive pki.inspect.cms
  * @signature pki.inspect.cms(input) -> string
  * @since 0.3.8
- * @status experimental
+ * @status stable
  * @spec RFC 5652
  * @related pki.schema.cms.parse, pki.inspect.certificate
  *
@@ -939,6 +953,11 @@ function _signerInfo(si, pad) {
  * `pki.schema.cms.parse` result; a non-CMS throws `inspect/bad-cms`. Best-effort.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var cert = 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: key });
+ *   var cmsDer = await pki.cms.sign(Buffer.from("hello"), { cert: cert, key: key });
  *   pki.inspect.cms(cmsDer).split("\n")[0]; // "CMS ContentInfo:"
  */
 // A ContentInfo whose content type pki.schema.cms.parse does not dispatch (id-data,
@@ -1003,7 +1022,7 @@ var _INSPECT_BY_FORMAT = { x509: certificate, crl: crlReport, csr: csrReport, cm
  * @primitive pki.inspect.any
  * @signature pki.inspect.any(input) -> string
  * @since 0.3.8
- * @status experimental
+ * @status stable
  * @spec RFC 5280
  * @related pki.schema.detectFormat, pki.inspect.certificate
  *
@@ -1015,6 +1034,10 @@ var _INSPECT_BY_FORMAT = { x509: certificate, crl: crlReport, csr: csrReport, cm
  * `inspect/bad-input`.
  *
  * @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.inspect.any(der);  // routes to the right report by detected format
  */
 function any(input) {

package/lib/jose.js

@@ -347,6 +347,11 @@ function assertPublicJwk(jwk) {
  *   key: object       // a public JWK, required unless the profile embeds jwk
  *
  * @example
+ *   var ec = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var accountJwk = await pki.webcrypto.subtle.exportKey("jwk", ec.publicKey);
+ *   var jws = await pki.jose.sign({ protected: { alg: "ES256", jwk: accountJwk,
+ *     nonce: "oFvnlFP1wIhRlYS2jTaXbA", url: "https://ca.example/acme/new-acct" },
+ *     payload: Buffer.from("{}"), key: ec.privateKey });
  *   var v = await pki.jose.verify(jws, { profile: "acme-outer", key: accountJwk });
  *   v.header.alg;   // -> "ES256"
  */
@@ -405,6 +410,10 @@ async function verify(jws, opts) {
  *   jwk: object          // the public JWK, when the header embeds jwk
  *
  * @example
+ *   var ec = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var priv = ec.privateKey;
+ *   var hdr = { alg: "ES256", jwk: await pki.webcrypto.subtle.exportKey("jwk", ec.publicKey),
+ *     nonce: "oFvnlFP1wIhRlYS2jTaXbA", url: "https://ca.example/acme/new-acct" };
  *   var jws = await pki.jose.sign({ protected: hdr, payload: Buffer.from("{}"), key: priv });
  */
 async function sign(opts) {
@@ -491,6 +500,12 @@ var THUMBPRINT_MEMBERS = {
  * always yields the same thumbprint (the ACME key-authorization anchor).
  *
  * @example
+ *   // the RFC 7638 sec. 3.1 worked example, so the thumbprint below is the spec's own
+ *   var accountJwk = { kty: "RSA", e: "AQAB", n: "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78L" +
+ *     "hWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXA" +
+ *     "rwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajr" +
+ *     "n1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-" +
+ *     "kEgU8awapJzKnqDKgw" };
  *   await pki.jose.thumbprint(accountJwk);   // -> "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs"
  */
 async function thumbprint(jwk) {

package/lib/lint.js

@@ -715,6 +715,10 @@ function _applyThreshold(report, severity) {
  * @opts  severity  Suppress findings below this floor (default `"notice"`). `counts` and
  *                  `worst` always reflect the complete, unfiltered result.
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var pemString = 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) }, { pem: true });
  *   var report = pki.lint.certificate(pemString);
  *   report.worst;                              // "notice" | "error" | ...
  *   report.findings.map(function (f) { return f.id; });

package/lib/merkle.js

@@ -102,7 +102,7 @@ function _ctEq(a, b) {
  * @primitive  pki.merkle.leafHash
  * @signature  pki.merkle.leafHash(entry) -> Buffer
  * @since      0.1.28
- * @status     experimental
+ * @status     stable
  * @spec       RFC 6962, RFC 9162
  * @related    pki.merkle.nodeHash, pki.merkle.verifyInclusion
  *
@@ -122,7 +122,7 @@ function leafHash(entry) {
  * @primitive  pki.merkle.nodeHash
  * @signature  pki.merkle.nodeHash(left, right) -> Buffer
  * @since      0.1.28
- * @status     experimental
+ * @status     stable
  * @spec       RFC 6962, RFC 9162
  * @related    pki.merkle.leafHash
  *
@@ -146,7 +146,7 @@ function nodeHash(left, right) {
  * @primitive  pki.merkle.emptyRootHash
  * @signature  pki.merkle.emptyRootHash() -> Buffer
  * @since      0.1.28
- * @status     experimental
+ * @status     stable
  * @spec       RFC 6962, RFC 9162
  * @related    pki.merkle.verifyConsistency
  *
@@ -164,7 +164,7 @@ function emptyRootHash() {
  * @primitive  pki.merkle.verifyInclusion
  * @signature  pki.merkle.verifyInclusion(opts) -> boolean
  * @since      0.1.28
- * @status     experimental
+ * @status     stable
  * @spec       RFC 6962, RFC 9162
  * @related    pki.merkle.leafHash, pki.merkle.verifyConsistency
  *
@@ -223,7 +223,7 @@ function verifyInclusion(opts) {
  * @primitive  pki.merkle.verifyConsistency
  * @signature  pki.merkle.verifyConsistency(opts) -> boolean
  * @since      0.1.28
- * @status     experimental
+ * @status     stable
  * @spec       RFC 6962, RFC 9162
  * @related    pki.merkle.verifyInclusion, pki.merkle.emptyRootHash
  *

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;