@blamejs/pki 0.5.6 → 0.5.8

package/lib/ocsp.js

@@ -12,10 +12,10 @@
  *   (`pki.ocsp.verify`). Parsing lives in `pki.schema.ocsp`; revocation during path validation is
  *   `pki.path.ocspChecker`. Signing rides the shared sign-scheme registry (the same classical +
  *   post-quantum set `pki.cms.sign` uses), so a response is signed under RSA / ECDSA / EdDSA /
- *   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
+ *   ML-DSA / SLH-DSA per the responder key. Verification composes the same hardened responder-
+ *   authorization, signature and 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, with ONE scoped exception -- a request-nonce mismatch downgrades only a
+ *   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
@@ -45,8 +45,8 @@ function _err(code, message, cause) { return new OcspError(code, message, cause)
 function _signE(kind, message, cause) { return new OcspError("ocsp/" + kind, message, cause); }
 
 // CertID / responder-ID hash algorithm name -> WebCrypto digest name. SHA-1 is the RFC 5019 interop
-// default for the CertID IDENTITY hash (not a signature; collision resistance is irrelevant to the
-// lookup, so SHAttered does not bar it -- the deliberate split path-validate makes too).
+// default for the CertID identity hash (not a signature; collision resistance is irrelevant to the
+// lookup, so SHAttered does not bar it, the same deliberate split path-validate makes).
 var HASH_WC = { sha1: "SHA-1", sha256: "SHA-256", sha384: "SHA-384", sha512: "SHA-512" };
 // A CRLReason name -> its enumerated value (RFC 5280 sec. 5.3.1), reverse of pki.C.NAMES.CRL_REASON.
 var REASON_CODE = {};
@@ -73,7 +73,7 @@ function _certOf(arg, what) {
 // The response, always parsed from the bytes the caller handed over. See verify's own comment for
 // why an object cannot be accepted here: the three parts of a signature check would come from three
 // independently-chosen properties. The claim is detected on any of the parsed-response fields, so a
-// caller who passes one is told what happened rather than getting a byte-parse fault about its type.
+// caller who passes one is told what happened, never given a byte-parse fault about its type.
 var _RESPONSE_CLAIM = ["responseStatus", "basicResponse", "tbsResponseDataBytes"];
 function _responseFromBytes(response) {
   return guard.parsed.fromTrustedSource(response, "ocspResponse", _RESPONSE_CLAIM, function (bytes) {
@@ -83,8 +83,7 @@ function _responseFromBytes(response) {
 }
 
 function _toDer(input, what) {
-  if (Buffer.isBuffer(input)) return input;
-  if (input instanceof Uint8Array) return Buffer.from(input);
+  if (Buffer.isBuffer(input) || input instanceof Uint8Array) return guard.bytes.snapshot(input, OcspError, "ocsp/bad-input", what || "input");
   if (typeof input === "string") { try { return ocspSchema.pemDecode(input); } catch (e) { throw _err("ocsp/bad-input", (what || "input") + " PEM could not be decoded", e); } }
   throw _err("ocsp/bad-input", (what || "input") + " must be a DER Buffer, Uint8Array, or PEM string");
 }
@@ -133,11 +132,11 @@ function _buildCertID(cert, issuer, hashName) {
  * `opts.pem` is set.
  *
  * @opts
- *   hashAlgorithm  `"sha1"` (default) / `"sha256"` / `"sha384"` / `"sha512"` -- the CertID identity hash.
+ *   hashAlgorithm  `"sha1"` (default) / `"sha256"` / `"sha384"` / `"sha512"`; the CertID identity hash.
  *   nonce          `true` for a fresh 32-octet CSPRNG nonce (RFC 9654), or a caller Buffer (1..128 octets).
  *   requestorName  a Name (RDN array) placed in the [1] requestorName as a directoryName.
  *   signer         `{ cert, key }` to sign the request (requires requestorName).
- *   profile        `"lightweight"` -- one Request, SHA-1 CertID, nonce-only extensions (RFC 5019).
+ *   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");
@@ -152,6 +151,15 @@ function _buildCertID(cert, issuer, hashName) {
  *   var der = await pki.ocsp.buildRequest({ cert: leafDer, issuer: caDer }, { nonce: true });
  */
 function buildRequest(query, opts) {
+  // Both arguments copied at entry and released when the call settles -- see the note on the same
+  // call in x509-sign. The request is assembled across several promise turns (each CertID is a
+  // hash), and opts carries byte fields -- the nonce and requestorName -- that reach the encoding.
+  return guard.bytes.fixedCall(OcspError, "ocsp/bad-input", [
+    [query, "the OCSP request query"], [opts, "pki.ocsp.buildRequest options"],
+  ], _buildRequest);
+}
+
+function _buildRequest(query, opts) {
   opts = opts || {};
   var lightweight = opts.profile === "lightweight";
   var hashName = opts.hashAlgorithm || "sha1";
@@ -201,7 +209,7 @@ function buildRequest(query, opts) {
 }
 function _emitReq(der, opts) { return opts.pem ? ocspSchema.pemEncode(der, "OCSP REQUEST") : der; }
 function _nameDer(name) {
-  if (Buffer.isBuffer(name)) return name;
+  if (Buffer.isBuffer(name)) return guard.bytes.snapshot(name, OcspError, "ocsp/bad-input", "requestorName");
   if (name && name.bytes) return name.bytes;   // a parsed Name
   throw _err("ocsp/bad-input", "requestorName must be a DER Name Buffer or a parsed Name");
 }
@@ -210,8 +218,7 @@ function _nameDer(name) {
 // a parsed certificate does not retain its full DER encoding, and re-encoding it would risk
 // byte drift from the signed original, so a parsed cert is rejected rather than reconstructed.
 function _normCertDer(cert, what) {
-  if (Buffer.isBuffer(cert)) return cert;
-  if (cert instanceof Uint8Array) return Buffer.from(cert);
+  if (Buffer.isBuffer(cert) || cert instanceof Uint8Array) return guard.bytes.snapshot(cert, OcspError, "ocsp/bad-input", what || "a certificate");
   if (typeof cert === "string") { try { return x509.pemDecode(cert); } catch (e) { throw _err("ocsp/bad-input", (what || "a certificate") + " PEM could not be decoded", e); } }
   if (cert && cert.tbsBytes && cert.subjectPublicKeyInfo) {
     throw _err("ocsp/bad-input", (what || "a certificate") + " to embed must be supplied as DER bytes or a PEM string, not a parsed certificate (the parser does not retain the full DER encoding needed to embed it verbatim)");
@@ -231,7 +238,7 @@ function _normCertDer(cert, what) {
  * responderID, an optional producedAt, and one or more per-certificate responses; `responder` is the
  * `{ cert, key }` signing the response (the issuing CA directly, or a CA-issued delegate bearing
  * id-kp-OCSPSigning + id-pkix-ocsp-nocheck). The signature is computed over the exact ResponseData
- * DER (RFC 6960 sec. 4.2.1 -- no CMS wrapper, no signed attributes). The responder certificate is
+ * DER (RFC 6960 sec. 4.2.1: no CMS wrapper, no signed attributes). The responder certificate is
  * embedded in `certs [0]` so a relying party can find it. Returns the response DER, or PEM.
  *
  * @opts
@@ -259,7 +266,11 @@ function _normCertDer(cert, what) {
 // Documented `-> Promise`, so a fault leaves as a REJECTION (guard-async); the checks stay
 // synchronous because they read the responder's mutable cert and key.
 function sign(responseData, responder, opts) {
-  return guard.async.deferred(function () { return _sign(responseData, responder, opts); });
+  // Every caller-owned argument copied at entry and released when the call settles -- see the note
+  // on the same call in x509-sign.
+  return guard.bytes.fixedCall(OcspError, "ocsp/bad-input", [
+    [responseData, "the OCSP responseData"], [responder, "the responder"], [opts, "pki.ocsp.sign options"],
+  ], _sign);
 }
 
 function _sign(responseData, responder, opts) {
@@ -438,15 +449,15 @@ function buildErrorResponse(status) {
  * an AUTHORIZED responder (the issuing CA directly, or a CA-issued delegate bearing id-kp-OCSPSigning
  * + id-pkix-ocsp-nocheck), verifies the signature over `tbsResponseData`, matches the CertID triple
  * 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
+ * (`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, 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
+ * The request-nonce check is reported, and downgrades `good` alone. 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
+ * 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`.
@@ -509,7 +520,8 @@ function verify(response, opts) {
     // 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 reqNonce = (Buffer.isBuffer(opts.requestNonce) || opts.requestNonce instanceof Uint8Array)
+      ? guard.bytes.snapshot(opts.requestNonce, OcspError, "ocsp/bad-input", "opts.requestNonce") : null;
     var matched = respNonce != null && reqNonce != null && guard.crypto.constantTimeEqual(respNonce, reqNonce);
     var out = Object.assign({}, verdict, { nonceMatched: matched });
     // The downgrade applies to `good` ONLY. `unknown` is the closed direction for a

package/lib/oid.js

@@ -13,12 +13,12 @@
  *   OID strings and their human names, plus arc conversion and DER
  *   encode/decode convenience. Every algorithm, attribute type, and
  *   extension in PKI is named by an OID, and resolving them through one
- *   registry -- rather than scattering magic dotted strings across the
- *   codebase -- is what lets a new algorithm be a data entry instead of a
+ *   registry, instead of scattering magic dotted strings across the
+ *   codebase, is what lets a new algorithm be a data entry instead of a
  *   code change.
  *
  *   The seed set is declared by FAMILY: an OID belongs to a class with a
- *   shared base arc (the "starting variable" -- `2.5.4` for the RFC 5280
+ *   shared base arc (the "starting variable": `2.5.4` for the RFC 5280
  *   attribute types, `2.5.29` for the extensions, `2.16.840.1.101.3.4` for
  *   the NIST algorithms), and each member names only its trailing arc. The
  *   full OID is derived from base + leaf at load, so the arc hierarchy that
@@ -48,7 +48,7 @@ function _oidError(c, m) { return new OidError(c, m); }
 // trailing arc (number) or a short arc array for a multi-level leaf; the full
 // arc is derived at load via base.concat(leaf). Declaring by family means no
 // dotted-decimal OID literal appears in this source at all, and adding a
-// member is one `name: leaf` line under its class -- no base to re-type.
+// member is one `name: leaf` line under its class, with no base to re-type.
 var FAMILIES = {
   // RFC 5280 attribute types.
   attributeType: { base: [2, 5, 4], of: {
@@ -142,7 +142,7 @@ var FAMILIES = {
   // The gaps are the specification's own: 12/13/14 (identityProof/popLinkRandom/popLinkWitness's
   // superseded siblings are retained below where RFC 6402 kept them) and 20 are unassigned in
   // RFC 5272 Appendix A. V2 forms exist because RFC 6402 replaced the originals to fix a hash
-  // agility gap -- BOTH are registered, since a v1 message is still legal to receive.
+  // agility gap. Both are registered, since a v1 message is still legal to receive.
   idCmc: { base: [1, 3, 6, 1, 5, 5, 7, 7], of: {
     "id-cmc-statusInfo": 1, "id-cmc-identification": 2, "id-cmc-identityProof": 3,
     "id-cmc-dataReturn": 4, "id-cmc-transactionId": 5, "id-cmc-senderNonce": 6,
@@ -155,7 +155,7 @@ var FAMILIES = {
     "id-cmc-authData": 27, "id-cmc-batchRequests": 28, "id-cmc-batchResponses": 29,
     "id-cmc-publishCert": 30, "id-cmc-modCertTemplate": 31, "id-cmc-controlProcessed": 32,
     // ---------------------------------------------------------------------
-    // 33 / 34 -- the specification assigns these two OIDs BOTH ways, and no
+    // 33 / 34: the specification assigns these two OIDs both ways, and no
     // erratum resolves it. Counted across every place either document states an
     // assignment, it is not an even split:
     //
@@ -167,7 +167,7 @@ var FAMILIES = {
     //     rfc6402.txt:1228 / :1245   RFC 6402 Appendix A.1 (1988 module)
     //
     //   identityProofV2 = 33, popLinkWitnessV2 = 34
-    //     rfc6402.txt:1938 / :1949   RFC 6402 Appendix A.2 (2008 module) ONLY
+    //     rfc6402.txt:1938 / :1949   RFC 6402 Appendix A.2 (2008 module) alone
     //
     // The rows below therefore follow the base specification's normative body
     // text and its module, which RFC 6402's own 1988 module agrees with. The
@@ -202,7 +202,7 @@ var FAMILIES = {
   cabfPolicy: { base: [2, 23, 140, 1], of: {
     "ev-guidelines": 1, "domain-validated": [2, 1], "organization-validated": [2, 2], "individual-validated": [2, 3] } },
 
-  // id-cp-ipAddr-asNumber (RFC 3779 / RFC 8360) on the id-pkix 14 arc -- the RPKI resource-certificate
+  // id-cp-ipAddr-asNumber (RFC 3779 / RFC 8360) on the id-pkix 14 arc: the RPKI resource-certificate
   // policy OIDs (sec. 8.9 ints 7-8).
   idCp: { base: [1, 3, 6, 1, 5, 5, 7, 14], of: { "id-cp-ipAddr-asNumber": 2, "id-cp-ipAddr-asNumber-v2": 3 } },
 
@@ -217,14 +217,14 @@ var FAMILIES = {
     "id-rspRole-ds-tls-v2": 6, "id-rspRole-ds-tls": [0, 0, 2, 0],
     "id-rspRole-ds-auth-v2": 7, "id-rspRole-ds-auth": [0, 0, 2, 1] } },
 
-  // id-qt policy qualifiers (RFC 5280 sec. 4.2.1.4) on the id-pkix 2 arc -- the C509 sec. 8.10 registry.
+  // id-qt policy qualifiers (RFC 5280 sec. 4.2.1.4) on the id-pkix 2 arc, which is the C509 sec. 8.10 registry.
   pkixQt: { base: [1, 3, 6, 1, 5, 5, 7, 2], of: { cps: 1, unotice: 2 } },
 
   // OCSP (RFC 6960) on the id-pkix-ocsp arc (= id-ad-ocsp). id-pkix-ocsp-basic is
   // the ResponseBytes.responseType this build decodes; id-pkix-ocsp-nonce (sec. 4.4.1)
   // names the nonce extension; the remaining members name the other OCSP extensions
-  // (CRL references, acceptable-response-types, archive-cutoff, service-locator,
-  // preferred-signature-algorithms, extended-revoke -- RFC 6960 sec. 4.4, RFC 9654).
+  // of RFC 6960 sec. 4.4 and RFC 9654 (CRL references, acceptable-response-types,
+  // archive-cutoff, service-locator, preferred-signature-algorithms, extended-revoke).
   ocsp: { base: [1, 3, 6, 1, 5, 5, 7, 48, 1], of: {
     ocspBasic: 1, ocspNonce: 2, ocspCrl: 3, ocspResponse: 4, ocspNoCheck: 5,
     ocspArchiveCutoff: 6, ocspServiceLocator: 7, ocspPrefSigAlgs: 8, ocspExtendedRevoke: 9 } },
@@ -232,13 +232,13 @@ var FAMILIES = {
   // CRMF (RFC 4211) registration controls (sec. 6) and registration info (sec. 7) on the
   // id-pkip arc (id-pkix 5). id-regCtrl (id-pkip 1) names the control types a
   // CertRequest carries; id-regInfo (id-pkip 2) names the registration-info types.
-  // The parser surfaces each control/info value RAW keyed by these names.
+  // The parser surfaces each control/info value raw, keyed by these names.
   regCtrl: { base: [1, 3, 6, 1, 5, 5, 7, 5, 1], of: {
     regToken: 1, authenticator: 2, pkiPublicationInfo: 3, pkiArchiveOptions: 4, oldCertID: 5, protocolEncrKey: 6 } },
   regInfo: { base: [1, 3, 6, 1, 5, 5, 7, 5, 2], of: { utf8Pairs: 1, certReq: 2 } },
 
-  // PKIX extended key purposes (id-kp, RFC 5280 sec. 4.2.1.12). timeStamping is required
-  // -- critical and sole -- on an RFC 3161 TSA signing certificate (sec. 2.3). The SSH
+  // PKIX extended key purposes (id-kp, RFC 5280 sec. 4.2.1.12). timeStamping is required,
+  // critical, and sole on an RFC 3161 TSA signing certificate (sec. 2.3). The SSH
   // (RFC 6187), CMC (RFC 6402), and Bundle Security (RFC 9174) purposes complete the C509
   // Extended Key Usages registry (draft-ietf-cose-cbor-encoded-cert sec. 8.12).
   pkixKp: { base: [1, 3, 6, 1, 5, 5, 7, 3], of: {
@@ -255,14 +255,14 @@ var FAMILIES = {
   // Google Certificate Transparency (RFC 6962) on the 1.3.6.1.4.1.11129.2.4 arc:
   // the SCT-list X.509 extension (sec. 3.3), the precertificate poison (sec. 3.1), the
   // precert-signing EKU (sec. 3.1, naming only), and the OCSP-delivered SCT list
-  // (sec. 3.3). The SCT payload itself is TLS presentation language, not DER -- it is
-  // parsed by lib/ct.js (pki.ct), never routed through the DER schema engine.
+  // (sec. 3.3). The SCT payload itself is TLS presentation language, so it is parsed
+  // by lib/ct.js (pki.ct) and never routed through the DER schema engine.
   ct: { base: [1, 3, 6, 1, 4, 1, 11129, 2, 4], of: {
     signedCertificateTimestampList: 2, precertificatePoison: 3,
     precertificateSigningCert: 4, ocspSignedCertificateTimestampList: 5 } },
 
   // Fulcio (Sigstore) X.509 certificate-extension arc. `.1.1`-`.1.6` are the
-  // DEPRECATED members whose values are RAW UTF-8 strings (no DER wrapping);
+  // DEPRECATED members whose values are raw UTF-8 strings (no DER wrapping);
   // `.1.7` is the OtherName SAN type; `.1.8` onward are DER-encoded ASN.1
   // UTF8String -- the decode MUST honor the raw-vs-DER split by member.
   fulcio: { base: [1, 3, 6, 1, 4, 1, 57264, 1], of: {
@@ -287,7 +287,7 @@ var FAMILIES = {
     data: 1, signedData: 2, envelopedData: 3, signedAndEnvelopedData: 4,
     digestedData: 5, encryptedData: 6 } },
 
-  // PKCS#9 attribute types -- incl. the CMS signed-attribute OIDs (RFC 5652 sec. 11)
+  // PKCS#9 attribute types, including the CMS signed-attribute OIDs (RFC 5652 sec. 11)
   // and the PKCS#12 bag attributes friendlyName / localKeyId (RFC 7292 sec. 4.2).
   pkcs9: { base: [1, 2, 840, 113549, 1, 9], of: {
     emailAddress: 1, contentType: 3, messageDigest: 4, signingTime: 5,
@@ -320,9 +320,9 @@ var FAMILIES = {
   pkcs12BagTypes: { base: [1, 2, 840, 113549, 1, 12, 10, 1], of: {
     keyBag: 1, pkcs8ShroudedKeyBag: 2, certBag: 3, crlBag: 4, secretBag: 5, safeContentsBag: 6 } },
 
-  // PKCS#12 password-based encryption schemes (RFC 7292 Appendix C) -- legacy
-  // PBE identifiers still emitted by deployed exporters; recognized so a
-  // shrouded bag's algorithm resolves to a name, never decrypted here.
+  // PKCS#12 password-based encryption schemes (RFC 7292 Appendix C). These legacy
+  // PBE identifiers are still emitted by deployed exporters; they are recognized so
+  // a shrouded bag's algorithm resolves to a name, never decrypted here.
   pkcs12Pbe: { base: [1, 2, 840, 113549, 1, 12, 1], of: {
     pbeWithSHAAnd128BitRC4: 1, pbeWithSHAAnd40BitRC4: 2,
     "pbeWithSHAAnd3-KeyTripleDES-CBC": 3, "pbeWithSHAAnd2-KeyTripleDES-CBC": 4,
@@ -354,7 +354,7 @@ var FAMILIES = {
     hkdfWithSha256: 28, hkdfWithSha384: 29, hkdfWithSha512: 30, cekHkdfSha256: 31 } },
 
   // RFC 5753 ephemeral-static ECDH key-agreement schemes -- the keyEncryptionAlgorithm OID of a
-  // kari, whose PARAMETER is the KeyWrapAlgorithm (so these are NOT params-absent). The X9.63 KDF
+  // kari, whose PARAMETER is the KeyWrapAlgorithm (so these are not params-absent). The X9.63 KDF
   // variants: stdDH (SECG arc 1.3.132.1.11) + cofactorDH (1.3.132.1.14) for SHA-224/256/384/512,
   // and the SHA-1 KDF pair on the ANSI-X9.63 arc (the OpenSSL default).
   secgStdDH: { base: [1, 3, 132, 1, 11], of: {
@@ -371,9 +371,9 @@ var FAMILIES = {
   // id-alg-hss-lms-hashsig OID above (RFC 9708 / RFC 9802 share it).
   pkixAlg: { base: [1, 3, 6, 1, 5, 5, 7, 6], of: {
     // id-alg-noSignature (RFC 6402 sec. 2.4, {id-pkix id-alg(6) 2}): the CMC
-    // "signature" algorithm for a request whose signer has no key yet -- the
+    // "signature" algorithm for a request whose signer has no key yet; the
     // SignerInfo carries a MAC-based proof instead. Registered so a decoder can
-    // NAME it and refuse it deliberately, rather than meeting an unknown OID.
+    // name it and refuse it deliberately.
     "id-alg-noSignature": 2,
     "id-alg-xmss-hashsig": 34, "id-alg-xmssmt-hashsig": 35,
     // Composite ML-DSA signature algorithms (draft-ietf-lamps-pq-composite-sigs
@@ -413,8 +413,8 @@ var FAMILIES = {
     signingCertificate: 12, timeStampToken: 14, decryptKeyID: 37, signingCertificateV2: 47,
     // id-aa-cmc-unsignedData (RFC 6402 sec. 2.7, {id-aa 34}): the CMC unsigned
     // attribute that carries body parts too large to sit inside the signed
-    // PKIData -- unsigned by design, so a consumer must treat its contents as
-    // untrusted data rather than as part of the authenticated message.
+    // PKIData. It is unsigned by design, so a consumer must treat its contents
+    // as untrusted data.
     cmcUnsignedData: 34,
     asymmDecryptKeyID: 54, certificationRequestInfoTemplate: 61, extensionReqTemplate: 62 } },
 
@@ -538,7 +538,7 @@ function _assertEncodable(dotted, who) {
 // X.660 encodability: the root arc is 0..2 and, under roots 0 and 1, the
 // second arc is 0..39 (the first two arcs pack into a single octet as
 // 40*X+Y). An OID outside these bounds can never be DER-encoded, so a
-// registration carrying one fails at config time rather than at first use.
+// registration carrying one fails at config time, before anything tries to use it.
 function _assertEncodableArcs(arcs, who) {
   if (arcs.length < 2) {
     throw new OidError("oid/bad-input", who + ": an OID must have at least 2 arcs");
@@ -616,8 +616,8 @@ function register(dotted, n) {
  * (the starting variable a class of OIDs has in common) and `members` maps
  * each name to its trailing arc -- a number, or a short arc array for a
  * multi-level leaf. Each full OID is derived as `base` followed by the leaf,
- * so a family is declared as its hierarchy rather than as re-spelled full
- * paths. This is the primitive the built-in seed set itself is built from.
+ * so a family is declared as its hierarchy and no full path is re-spelled.
+ * This is the primitive the built-in seed set itself is built from.
  *
  * @opts
  *   base:      number[],           // the shared arc prefix, e.g. [1,3,6,1,4,1,99999]