@blamejs/pki 0.5.7 → 0.5.8

package/lib/est.js

@@ -13,8 +13,8 @@
  *   The network verbs -- `cacerts`, `simpleenroll`, `simplereenroll` -- run the thin
  *   RFC 7030 client: they compose the codecs below over the shared `pki.transport`
  *   (a caller MAY inject `opts.transport`; the default is a fail-closed
- *   `pki.transport.https`). This module opens no socket itself -- the sole socket
- *   choke point is `pki.transport` -- so the verbs stay a thin, fail-closed shell:
+ *   `pki.transport.https`). This module opens no socket itself: the sole socket
+ *   choke point is `pki.transport`, so the verbs stay a thin, fail-closed shell:
  *   https-only (`est/insecure-url`), an explicit trust anchor required
  *   (`est/no-trust-anchors`), same-origin redirects followed but a downgrade / loop
  *   refused, a 202 Retry-After SURFACED and never slept, HTTP Basic answered only
@@ -22,10 +22,10 @@
  *   by public-key match. Under them sit the transport-agnostic codecs, validators, and
  *   request builders over the shipped CMS / CSR / PKCS#8 / X.509 parsers:
  *   `transferDecode` / `transferEncode` are the RFC 8951
- *   sec. 3 base64 transfer codec (RFC 4648, and DELIBERATELY blind to any
- *   Content-Transfer-Encoding header -- errata 5904/5107); `splitMultipartMixed`
+ *   sec. 3 base64 transfer codec (RFC 4648, and deliberately blind to any
+ *   Content-Transfer-Encoding header, per errata 5904/5107); `splitMultipartMixed`
  *   is the /serverkeygen `multipart/mixed` splitter; `parseCertsOnly` validates a
- *   certs-only Simple PKI Response (RFC 5272 sec. 4.1) OVER `cms.parse` output;
+ *   certs-only Simple PKI Response (RFC 5272 sec. 4.1) over `cms.parse` output;
  *   `parseServerKeygenResponse` dispatches the two-part key + certificate
  *   response with recipient-arm coherence; `classifyResponse` is the HTTP status
  *   / content-type / Retry-After state machine (202 accepted-not-ready surfaces
@@ -35,20 +35,20 @@
  *   out-of-band-key identifiers, SMIMECapabilities, and the RFC 9908
  *   template-priority enroll plan.
  *
- *   Altitude MATCHES the toolkit: structural validation, no crypto verdicts.
- *   Certificates come back RAW and UNORDERED ("Clients MUST NOT assume the
- *   certificates are in any order", RFC 5272 sec. 4.1) -- `findIssuedCert` picks
+ *   Altitude matches the toolkit: structural validation, no crypto verdicts.
+ *   Certificates come back raw and unordered ("Clients MUST NOT assume the
+ *   certificates are in any order", RFC 5272 sec. 4.1), so `findIssuedCert` picks
  *   the issued certificate by a public-key match, never a positional guess. The
  *   serverkeygen encrypted-key part's EnvelopedData is surfaced structurally
- *   (ciphertext raw, decryption external). A /fullcmc response is CLASSIFIED:
+ *   (ciphertext raw, decryption external). A /fullcmc response is classified:
  *   a 200 may carry either arm RFC 7030 sec. 4.3.2 permits (`certs-only` or
  *   `CMC-response`), and a 404 or 501 is the distinct `not-implemented`
- *   verdict -- this service absent, rather than a transport fault. Reading the
+ *   verdict, meaning this service is absent, not that the transport faulted. Reading the
  *   CMC message itself is the CMC module's job. DER-only where DER,
  *   fail-closed everywhere.
  *
  * @card
- *   EST (RFC 7030 / 8951 / 9908) client -- the cacerts / simpleenroll / simplereenroll
+ *   EST (RFC 7030 / 8951 / 9908) client: the cacerts / simpleenroll / simplereenroll
  *   verbs over the shared pki.transport, plus the codecs they compose: base64 transfer,
  *   multipart splitter, certs-only + serverkeygen validators over CMS, the
  *   enroll-attribute builders, and the HTTP response classifier. Fail-closed.
@@ -88,7 +88,7 @@ var OPERATIONS = ["cacerts", "simpleenroll", "simplereenroll", "fullcmc", "serve
 
 // ---- the option surface each verb accepts -----------------------------------
 //
-// A misspelled option reads as an omission rather than as a value: nothing is out of range and
+// A misspelled option reads as an omission, never as a value: nothing is out of range and
 // nothing fails to parse, so the caller who asked for something stricter gets the looser default
 // and is told nothing. That is worst here, where the options carry the security posture of a
 // network exchange -- a misspelled `tls` leaves the anchors unset (the no-anchors refusal names
@@ -97,7 +97,7 @@ var OPERATIONS = ["cacerts", "simpleenroll", "simplereenroll", "fullcmc", "serve
 // server-generated private key, and a misspelled `oldCert` fails the re-enrollment outright.
 //
 // Every network verb shares the client surface, because every one of them goes through _client and
-// the redirect / authentication plumbing it drives. The per-verb tables extend it rather than
+// the redirect / authentication plumbing it drives. The per-verb tables extend it instead of
 // restating it, so a key added to the client reaches every verb at once and none of them drifts.
 var CLIENT_OPTS = {
   transport: 1, tls: 1, label: 1, timeout: 1, maxResponseBytes: 1, maxRedirects: 1, now: 1,
@@ -114,7 +114,7 @@ function _withClient(extra) {
 var CACERTS_OPTS = _withClient(null);
 var SIMPLEENROLL_OPTS = _withClient({ strict: 1 });
 var SIMPLEREENROLL_OPTS = _withClient({ strict: 1, oldCert: 1 });
-// expectedRecipientKind is NOT here: it is derived from the CSR's own advertised attribute, never
+// expectedRecipientKind is deliberately absent: it is derived from the CSR's own advertised attribute, never
 // taken from the caller, so listing it would offer a pin that nothing reads.
 var SERVERKEYGEN_OPTS = _withClient({
   requestedEncryption: 1, expectedRecipientKeyId: 1, expectedRecipientIssuerSerial: 1,
@@ -122,7 +122,7 @@ var SERVERKEYGEN_OPTS = _withClient({
 var CSRATTRS_OPTS = _withClient(null);
 var FULLCMC_OPTS = _withClient({
   transactionId: 1, senderNonce: 1, dataReturn: 1,
-  responderCerts: 1, responseRecipient: 1, allowUnverifiedResponse: 1,
+  responderCerts: 1, responseRecipient: 1, allowUnverifiedResponse: 1, allowUnboundResponse: 1,
 });
 // The two verbs that take options without going near the network.
 var CLASSIFY_OPTS = { op: 1, now: 1 };
@@ -151,8 +151,8 @@ function _knownOpts(opts, known, verb) {
  *
  * Decode an EST payload body (a base64 string or Buffer) to DER. CR/LF/space/tab
  * are stripped anywhere (RFC 8951 sec. 3.1); any other non-alphabet byte fails
- * closed with `est/bad-base64`. A Content-Transfer-Encoding header is NEVER read
- * (errata 5904/5107). Bounded twice -- the raw length before decode and the
+ * closed with `est/bad-base64`. A Content-Transfer-Encoding header is never read
+ * (errata 5904/5107). Bounded twice: the raw length before decode and the
  * decoded DER against `DER_MAX_BYTES` (`est/too-large`).
  *
  * @example
@@ -276,8 +276,8 @@ function splitMultipartMixed(body, contentType) {
  * shipped `cms.parse` output: a SignedData with no eContent and EMPTY
  * signerInfos, carrying at least one plain X.509 certificate (a context-tagged
  * CertificateChoices alternative is rejected `est/bad-certificate-choice`). CRLs
- * MAY be present. Certificates come back RAW and in AS-RECEIVED order (never
- * sorted -- RFC 5272 sec. 4.1). A non-conformant response throws a typed
+ * MAY be present. Certificates come back raw and in as-received order (never
+ * sorted, per RFC 5272 sec. 4.1). A non-conformant response throws a typed
  * `EstError` (`est/not-certs-only`, `est/no-certificates`).
  *
  * @example
@@ -1135,28 +1135,39 @@ function _certsResult(op, res, opts, csrSpki) {
  * `application/pkcs7-mime; smime-type=CMC-request`, base64 per RFC 8951, over the shared
  * `pki.transport`.
  *
- * A 200 answers with EITHER `smime-type=certs-only` (a Simple PKI Response) or
- * `smime-type=CMC-response` (a Full PKI Response) -- RFC 7030 sec. 4.3.2 names both, and the label
+ * A 200 answers with either `smime-type=certs-only` (a Simple PKI Response) or
+ * `smime-type=CMC-response` (a Full PKI Response). RFC 7030 sec. 4.3.2 names both, and the label
  * must agree with the bytes. Either way the result is the `pki.cmc.verify` verdict shape, so a
  * caller reads one `outcome` (`issued` / `pending` / `confirm-required` / `pop-required` /
- * `rejected`) regardless of which arm the server chose. Pass `transactionId` / `senderNonce` /
- * `dataReturn` to have the exchange bound to the request that was sent.
+ * `rejected`) regardless of which arm the server chose.
  *
- * A 404 **or** a 501 is the distinct `est/not-implemented` verdict -- support for this verb is
- * OPTIONAL on both sides (sec. 4.3). A 202 surfaces its Retry-After rather than sleeping. A
+ * The exchange binding is read out of the request itself, never taken on the caller's word: whatever
+ * Transaction Identifier, Sender Nonce or Data Return the submitted bytes carry is what the response
+ * must echo, and `transactionId` / `senderNonce` / `dataReturn` are a cross-check that is refused if
+ * it disagrees. A request that carries none of the three leaves nothing for the response to echo, so
+ * the answer is refused instead of being accepted as an enrollment result that could be a replay of
+ * any earlier exchange. The code is `cmc/unbound-response` on the `CMC-response` arm, which the CMC
+ * layer interprets, and `est/unbound-response` on the `certs-only` arm, which this verb owns. Build
+ * the request with a `senderNonce` (`pki.cmc.build`) to bind it, or pass `allowUnboundResponse: true` to
+ * accept that it is unbound. The verdict reports which halves ran as `bound` and `boundToRequest`.
+ *
+ * A 404 **or** a 501 is the distinct `est/not-implemented` verdict, since support for this verb is
+ * optional on both sides (sec. 4.3). A 202 surfaces its Retry-After and does not sleep. A
  * rejection carries a CMC response (sec. 4.3.2 makes it a MUST), which is decoded and attached to
- * a typed `est/cmc-failed` as `err.cmc` and `err.httpStatus` -- but a body that cannot be read
+ * a typed `est/cmc-failed` as `err.cmc` and `err.httpStatus`, while a body that cannot be read
  * never masks the HTTP fault it arrived with.
  *
- * On the `certs-only` arm the issued certificates are identified by PUBLIC-KEY MATCH against the
- * requests that were submitted -- the only identification RFC 5272 sec. 4.1 sanctions, since "the
- * certificates are in any order" -- and EVERY certification request in the message must be answered
- * before the exchange reads as `issued` -- a key wanted by N requests needs N certificates, so a
- * bag that answers only some of them, or none, is a refusal rather than a partial success. That arm
+ * On the `certs-only` arm the issued certificates are identified by public-key match against the
+ * requests that were submitted, the only identification RFC 5272 sec. 4.1 sanctions, since "the
+ * certificates are in any order". Every certification request in the message must be answered
+ * before the exchange reads as `issued`: a key wanted by N requests needs N certificates, so a
+ * bag that answers only some of them, or none, is a refusal and not a partial success. That arm
  * carries no controls, so it cannot echo a Transaction Identifier, Sender Nonce or Data Return: a
- * request that sent those asked for replay binding it cannot provide -- the key match is not one,
- * since an old response for the same key still matches -- and it is refused as
- * `est/unbound-response` rather than accepted with silently none of what was asked for. They are
+ * request that sent those asked for replay binding it cannot provide (the key match is not one,
+ * since an old response for the same key still matches), and it is refused as
+ * `est/unbound-response`, never accepted with silently none of what was asked for. A request
+ * that asked for no binding reaches the same refusal on this arm, for the same reason: nothing here
+ * can tie the bag to the exchange, so `allowUnboundResponse: true` is what accepts it. They are
  * surfaced as `issuedCertificates` (with `certificate` the first), distinct from `certificates`,
  * which is the whole returned bag including any chain. Where the requested keys are distinct that
  * list is in request order; where several requests deliberately SHARE one key it is not, and does
@@ -1170,18 +1181,23 @@ function _certsResult(op, res, opts, csrSpki) {
  * response is SURFACED, never acted on (RFC 5272 sec. 6.15 makes accepting one a manual decision).
  *
  * @opts
- *   - `transport` / `tls` / `label` / `timeout` / `maxResponseBytes` / `maxRedirects` / `now` -- as pki.est.cacerts.
- *   - `transactionId` / `senderNonce` / `dataReturn` -- what the request sent, for the exchange binding.
- *   - `responderCerts` -- EXTRA certificates for CMC signer lookup, for a response that does not carry
+ *   - `transport` / `tls` / `label` / `timeout` / `maxResponseBytes` / `maxRedirects` / `now`, as in pki.est.cacerts.
+ *   - `transactionId` / `senderNonce` / `dataReturn`: what the request sent. The values are read out
+ *     of the request itself; supplying them here cross-checks that, and a disagreement is refused.
+ *   - `responderCerts`: extra certificates for CMC signer lookup, for a response that does not carry
  *     its own signer; the certificates the response carries are searched either way. The carrier's
  *     signature MUST be verified (RFC 5272 sec. 3.2.1.3.4), so a `CMC-response` whose signer is found
  *     nowhere and which does not name the opt-out below is refused.
  *   - `responseRecipient` -- key material for a response carried in AuthenticatedData, in the shape
  *     `pki.cms.decrypt` takes. Its MAC is then checked and the verdict reports
- *     `signatureVerified: true`, rather than the carrier being reachable only unauthenticated.
+ *     `signatureVerified: true`, so the carrier is not reachable only unauthenticated.
  *   - `allowUnverifiedResponse` -- accept a `CMC-response` whose signer certificate cannot be found,
  *     without checking its signature; the verdict then reports `signatureVerified: false`. For an
  *     unauthenticated bootstrap only, and it never excuses a signature that is present and wrong.
+ *   - `allowUnboundResponse` -- accept an answer to a request that carried no Transaction Identifier,
+ *     Sender Nonce or Data Return, so nothing ties it to this exchange; the verdict then reports
+ *     `boundToRequest: false`. A separate question from the one above, because a replayed response
+ *     is authentic, so naming one does not name the other.
  *   - `username` / `password` / `allowCrossOriginRedirect` -- as pki.est.simpleenroll.
  * @example
  *   var pair = await pki.key.generate("Ed25519");
@@ -1417,6 +1433,12 @@ function _cmcSent(opts, der) {
     // would exist one layer down and be unreachable from the one operators call.
     recipient: _copyRecipient(opts.responseRecipient),
     allowUnverified: opts.allowUnverifiedResponse === true,
+    // The binding opt-out travels the same way. Without it the capability would
+    // exist one layer down and be unreachable from the verb operators call: a
+    // request built with no Transaction Identifier, Sender Nonce or Data Return
+    // carries nothing for the response to echo, so pki.cmc.verify would refuse
+    // every answer to it and no option here could say that was intended.
+    allowUnbound: opts.allowUnboundResponse === true,
   };
 }
 
@@ -1681,6 +1703,19 @@ function _fullcmcResult(res, opts, wanted, sent) {
         "the request carried " + unecho.join(" / ") + ", which a certs-only response has no controls to " +
         "echo, so the replay binding it asked for cannot be checked (RFC 5272 sec. 6.6 / 6.4)");
     }
+    // Reaching here means the request asked for no binding, so nothing whatever
+    // ties this bag of certificates to this exchange. The public-key correlation
+    // below is explicitly not a binding, since an old response for the same key
+    // matches just as well. pki.cmc.verify takes this posture on the other arm,
+    // and it is taken here too: one arm quietly accepting what the other refuses
+    // would make which rule applied depend on the smime-type the server chose.
+    if (sent.allowUnbound !== true) {
+      throw E("est/unbound-response",
+        "nothing ties this certs-only response to the request just sent: a certs-only body carries no " +
+        "controls at all, so build the request with a `senderNonce` (pki.cmc.build) and use a server that " +
+        "answers with a CMC-response, or pass `allowUnboundResponse: true` to accept a bag of certificates " +
+        "that could answer any earlier request for the same key (RFC 5272 sec. 6.6)");
+    }
     var certs = parseCertsOnly(der);            // throws est/not-certs-only on a Full PKI Response
     // A certs-only body says nothing about WHICH request it answers -- no status,
     // no body-part reference. So the issued certificate is identified the one way
@@ -1699,10 +1734,18 @@ function _fullcmcResult(res, opts, wanted, sent) {
     // depending on which arm the server happened to choose. RFC 7030 secures this
     // arm through the authenticated TLS channel instead, and the certificates stay
     // `trusted: false` for the caller to run through pki.path.validate.
+    // `bound` and `boundToRequest` are stated here for the same reason
+    // `signatureVerified` is: leaving them undefined while the CMC-response arm
+    // sets them would give a caller a different kind of answer depending on which
+    // arm the server chose. Every one is false and cannot be otherwise, because a
+    // certs-only body has no controls to echo. That is what the refusal above
+    // makes the caller acknowledge before reading this verdict at all.
     return { outcome: "issued", certificate: issued, issuedCertificates: issuedCerts,
       certificates: certs.certificates, crls: certs.crls,
       controls: [], statuses: [], publishTrustAnchors: null, trusted: false,
-      signatureVerified: false };
+      signatureVerified: false,
+      bound: { transactionId: false, senderNonce: false, dataReturn: false, bodyPartIDs: false },
+      boundToRequest: false };
   }
   // smime-type=cmc-response: the Full PKI Response, interpreted into one verdict.
   // pki.cmc.verify owns the transaction binding and the status reduction; this
@@ -1804,11 +1847,11 @@ function _enroll(op, baseUrl, csrInput, opts) {
  * (`{ certificates, crls }`), or `{ retry: true, retryAfterSeconds }` on a 202 (surfaced,
  * never slept). https-only (`est/insecure-url`); an explicit `opts.tls.anchors` (or an
  * `opts.tls.useSystemStore` opt-in) is required (`est/no-trust-anchors`); the returned CA
- * certificate is NOT auto-trusted -- the caller path-validates it and supplies the accepted
+ * certificate is not auto-trusted: the caller path-validates it and supplies the accepted
  * anchor on the next call.
  *
  * @opts
- *   - `transport` -- an injected transport(request) -> {status, headers, body, tls}; default pki.transport.https.
+ *   - `transport`: an injected transport(request) -> {status, headers, body, tls}; default pki.transport.https.
  *   - `tls` -- { anchors, useSystemStore, cert, key, minVersion, servername, checkServerIdentity }.
  *   - `label` -- an OPTIONAL CA label path segment; `timeout` / `maxResponseBytes` / `maxRedirects` -- budgets.
  *   - `now` -- receipt time (epoch ms) to render a 202 Retry-After HTTP-date as seconds.
@@ -1849,12 +1892,12 @@ function cacerts(baseUrl, opts) {
  * certificates (`chain`), and the raw set (`certificates`); or `{ retry: true,
  * retryAfterSeconds }` on a 202. No returned certificate matching the CSR key fails closed
  * (`est/issued-cert-not-found`); `opts.strict` requires exactly the issued certificate. A
- * 401 is answered once with HTTP Basic ONLY when `opts.username`/`password` are supplied and
+ * 401 is answered once with HTTP Basic only when `opts.username`/`password` are supplied and
  * the transport already authenticated the server.
  *
  * @opts
- *   - `transport` / `tls` / `label` / `timeout` / `maxResponseBytes` / `maxRedirects` / `now` -- as pki.est.cacerts.
- *   - `strict` -- reject an enroll response that carries more than the single issued certificate.
+ *   - `transport` / `tls` / `label` / `timeout` / `maxResponseBytes` / `maxRedirects` / `now`, as in pki.est.cacerts.
+ *   - `strict`: reject an enroll response that carries more than the single issued certificate.
  *   - `username` / `password` -- HTTP Basic credentials, answered only after server authorization (empty username allowed).
  *   - `allowCrossOriginRedirect` -- opt in to following a cross-origin redirect on this POST.
  * @example
@@ -1884,7 +1927,7 @@ function simpleenroll(baseUrl, csrInput, opts) {
  * `/.well-known/est/simplereenroll` and REQUIRES `opts.oldCert` (the certificate being
  * renewed). Before anything crosses the wire, `reenrollGuard` enforces that the CSR's
  * Subject and SubjectAltName (names and criticality) are byte-identical to `opts.oldCert`
- * (RFC 7030 sec. 4.2.2) -- a mismatch fails closed (`est/reenroll-subject-mismatch` /
+ * (RFC 7030 sec. 4.2.2). A mismatch fails closed (`est/reenroll-subject-mismatch` /
  * `est/reenroll-san-mismatch`) and the transport is never called. A missing `opts.oldCert`
  * is `est/bad-input`.
  *
@@ -2039,14 +2082,14 @@ async function _serverkeygenResult(res, opts, derived) {
  * application/pkcs10`, identical request encoding to `simpleenroll`) to
  * `<baseUrl>/.well-known/est/serverkeygen`. The two-part `multipart/mixed` response is surfaced as
  * `{ certificates, privateKey }` (a cleartext PKCS#8 `PrivateKeyInfo`) or `{ certificates,
- * encryptedKey }` (the CMS `EnvelopedData` the caller decrypts out-of-band with its key-encryption key --
- * the verb NEVER decrypts, so it is not a decryption oracle), or `{ retry, retryAfterSeconds }` on a 202.
- * The certificates are RAW/unordered -- unlike `simpleenroll` no leaf is picked, because the CA generated
- * the key so the issued certificate's public key is the generated one, not the throwaway CSR key. A CLEARTEXT
+ * encryptedKey }` (the CMS `EnvelopedData` the caller decrypts out-of-band with its key-encryption key;
+ * the verb never decrypts, so it is not a decryption oracle), or `{ retry, retryAfterSeconds }` on a 202.
+ * The certificates are raw and unordered: unlike `simpleenroll` no leaf is picked, because the CA generated
+ * the key so the issued certificate's public key is the generated one, not the throwaway CSR key. A cleartext
  * key is bound to its certificate before it resolves: the delivered private key's public half MUST match
- * EXACTLY ONE returned certificate (`est/key-cert-mismatch` on none, `est/ambiguous-issued-cert` on more than
- * one), so a mis-associated key is refused rather than handed back unusable.
- * The encryption requirement + expected recipient are DERIVED from the CSR's own DecryptKeyIdentifier /
+ * exactly one returned certificate (`est/key-cert-mismatch` on none, `est/ambiguous-issued-cert` on more than
+ * one), so a mis-associated key is refused, never handed back unusable.
+ * The encryption requirement + expected recipient are derived from the CSR's own DecryptKeyIdentifier /
  * AsymmetricDecryptKeyIdentifier attribute; an `opts` value that contradicts the CSR is `est/bad-input`
  * (a cleartext-key downgrade cannot slip past). The delivered key's channel is asserted confidentiality-
  * bearing (a NULL / anonymous / EXPORT cipher is `est/weak-cipher`). https-only, explicit-anchor, and the
@@ -2116,10 +2159,10 @@ function _csrattrsResult(res, opts) {
  *
  * Fetch the CA's CSR-attributes policy: GET `<baseUrl>/.well-known/est/csrattrs` (`Accept:
  * application/csrattrs`). A 200 body is base64-decoded, parsed as an RFC 9908 `CsrAttrs`, and returned
- * with a `plan` (`buildEnrollAttributes`) the caller applies to its NEXT CSR -- the verb NEVER auto-applies
+ * with a `plan` (`buildEnrollAttributes`) the caller applies to its next CSR; the verb never auto-applies
  * attributes to a CSR (single responsibility). A 204 or 404 is `{ available: false }` (a valid "no specific
- * attributes"), NOT an error; an empty SEQUENCE (`30 00`) is a COMPLETE empty policy (`attrs.items` empty),
- * distinct from an empty HTTP body (`est/empty-body`). Server auth is NOT required for this policy GET but a
+ * attributes") and not an error; an empty SEQUENCE (`30 00`) is a complete empty policy (`attrs.items` empty),
+ * distinct from an empty HTTP body (`est/empty-body`). Server auth is not required for this policy GET but a
  * 401 is tolerated (the shared auth path stays live). https-only + explicit-anchor as elsewhere.
  *
  * @opts

package/lib/framework-error.js

@@ -16,10 +16,10 @@
  *   `{ name, code, message, permanent, isPkiError: true }`.
  *
  *   `code` is a stable, greppable `domain/reason` string
- *   (`asn1/indefinite-length`, `x509/not-a-certificate`) -- safe to switch
+ *   (`asn1/indefinite-length`, `x509/not-a-certificate`): safe to switch
  *   on and safe to log. Because every failure here is a deterministic
  *   verdict on the bytes in hand (a malformed length, an unknown OID
- *   shape, a truncated certificate), errors are `permanent: true` -- the
+ *   shape, a truncated certificate), errors are `permanent: true`. The
  *   same input will never parse on retry.
  *
  * @card
@@ -41,7 +41,7 @@ var CODE_SHAPE = /^[a-z0-9-]+\/[a-z0-9-]+$/;
  * Base class every toolkit error extends. Provides the unified
  * `instanceof` check plus the `{ name, code, isPkiError }` shape.
  * A supplied `code` must be a `domain/reason` string (lowercase
- * alphanumerics and dashes) -- the construction throws a `TypeError`
+ * alphanumerics and dashes); the construction throws a `TypeError`
  * otherwise, which catches an argument-order swap with the
  * `defineClass` subclasses' `(code, message)` convention at the call
  * site instead of shipping prose into a code-switching consumer.
@@ -83,10 +83,10 @@ class PkiError extends Error {
  * a `.factory` static for the common `var _err = XxxError.factory` shape.
  * The `code` must be a `domain/reason` string (the base-class contract);
  * without `withCause`, a third constructor argument throws a `TypeError`
- * rather than silently discarding a cause the caller meant to thread.
+ * instead of silently discarding a cause the caller meant to thread.
  *
  * @opts
- *   withCause:  boolean,  // default: false -- constructor becomes (code, message, cause)
+ *   withCause:  boolean,  // default false; constructor becomes (code, message, cause)
  *
  * @example
  *   // throws: my/bad-input -- raising the new error type IS what this shows

package/lib/guard-all.js

@@ -8,11 +8,11 @@
 // guard-all -- the guard-family orchestrator (schema-all's role for the guard
 // family). It assembles the per-shape fail-closed guards into one namespaced
 // surface every input boundary composes, so a boundary depends on the family
-// rather than re-implementing a guard inline:
+// itself, with no guard re-implemented inline:
 //
 //   guard.bytes.view / .source        -- untrusted byte-source -> Buffer re-view
 //                                         (detached-buffer fail-open defence)
-//   guard.text.decode                 -- byte-source -> string, cap BEFORE copy
+//   guard.text.decode                 -- byte-source -> string, cap before copy
 //                                         (parser-DoS string-allocation defence)
 //   guard.limits.cap / .depthCap      -- config-time resource-cap validation
 //                                         (recursion / allocation DoS defence)
@@ -47,7 +47,7 @@
 //
 // Each shape is enforced by a codebase-patterns detector: the characteristic
 // token of a guard (the Buffer.from(x.buffer, byteOffset) re-view, the
-// timingSafeEqual call, the MAX_DECODE_DEPTH_CEILING check) must appear ONLY in
+// timingSafeEqual call, the MAX_DECODE_DEPTH_CEILING check) must appear only in
 // its guard module, so a new boundary cannot re-inline the shape and forget the
 // defence.
 

package/lib/guard-async.js

@@ -12,14 +12,14 @@
 //
 //     pki.acme.newOrder(opts).catch(handleIt);
 //
-// A validation that runs BEFORE the promise is created throws straight past that `.catch`, so a
+// A validation that runs before the promise is created throws straight past that `.catch`, so a
 // misspelled option or a malformed input becomes an uncaught exception in code that already handles
 // errors -- and nothing in the shape of the call tells the caller which verbs do that. Eleven verbs
 // across five modules had it (pki.cms.verify / sign / countersign, pki.ocsp.sign, pki.tsp.sign and
 // six pki.acme verbs), each having grown the same way: a cheap synchronous check added at the top of
 // a function that returns a promise further down.
 //
-// What this does NOT change is WHEN the work happens. The body still runs synchronously, because
+// What this does not change is when the work happens. The body still runs synchronously, because
 // several of these verbs must resolve a caller's mutable options object before any turn passes --
 // reading a key, a nonce, or a request's bytes a turn later is a different value than the one that
 // was checked. Only the exit changes: a fault leaves as a rejection instead of a throw.
@@ -27,8 +27,8 @@
 // @enforced-by behavioral -- the rule has no rename-proof code shape (it is the ABSENCE of a wrapper
 //   around a synchronous prefix, which no lexical pattern can see). The guard is the derived test
 //   test/layer-0-primitives/promise-contract.test.js, which reads every `-> Promise<` @signature out
-//   of lib/ and calls each verb to prove the refusal arrives as a rejection -- so a new verb is in
-//   scope the day it is documented, and no list here can go stale.
+//   of lib/ and calls each verb to prove the refusal arrives as a rejection. A new verb is in
+//   scope the day it is documented, so no list here can go stale.
 function deferred(body) {
   try { return Promise.resolve(body()); }
   catch (e) { return Promise.reject(e); }