@blamejs/pki 0.5.7 → 0.5.8

package/lib/guard-bytes.js

@@ -21,22 +21,22 @@ var async = require("./guard-async");
 // validation feeding a CWE-347-style verification-of-nothing). Always re-viewing
 // through Buffer.from(x.buffer, x.byteOffset, x.byteLength) turns the detached
 // read into a typed reject at the boundary. Size / length-field allocation
-// bounds (CWE-770 / CWE-400, the parser-DoS class) are NOT enforced here -- they
+// bounds (CWE-770 / CWE-400, the parser-DoS class) are not enforced here. They
 // are per-format (a multi-MB CRL is legitimate, a Merkle proof is tiny), so they
 // live in guard-params and each decoder's own cap.
 
 // Choosing between `view` and `snapshot` at a boundary: a byte argument that is read only
-// during the synchronous pass that received it can be re-VIEWED, because nothing can run
-// between the check and the use. One that survives that pass -- stored in state, compared
-// after an await, embedded into output the verb assembles later -- must be SNAPSHOT, or the
+// during the synchronous pass that received it can be re-viewed, because nothing can run
+// between the check and the use. One that survives that pass (stored in state, compared
+// after an await, embedded into output the verb assembles later) must be snapshotted, or the
 // caller can still rewrite the bytes after they were validated. The exceptions are the two
 // places holding a caller's SECRET, where a copy is the worse defect: a password or a private
 // key is re-viewed and left borrowed only when this module also clears the copy it made, so
 // no plaintext duplicate outlives the derivation.
 
 // The guard family threads a caller's typed error under two conventions: most guards take a
-// FACTORY (`E(code, message, cause)`, no `new`) because the engines that call them -- sign-scheme,
-// composite-sig, pki-build -- carry a bound factory that prefixes the caller's domain onto the
+// FACTORY (`E(code, message, cause)`, no `new`) because the engines that call them (sign-scheme,
+// composite-sig, pki-build) carry a bound factory that prefixes the caller's domain onto the
 // code; guard-bytes and guard-header take the error CLASS. A boundary that has only one of the two
 // would otherwise have to hand-roll the re-view to reach this guard at all, which is precisely what
 // the re-inline detector forbids, so accept either: a class (its prototype is an Error) is
@@ -64,12 +64,12 @@ function view(input, ErrorClass, code, label) {
 
 // source(input, ErrorClass, code, label) -> Buffer | throws ErrorClass
 // Accepts the full W3C BufferSource (Buffer / TypedArray view / raw ArrayBuffer)
-// -- the WebCrypto input contract. Re-VIEWS in every case, sharing the caller's
-// memory rather than taking a copy: `Buffer.from(arrayBuffer)` wraps the backing
+// -- the WebCrypto input contract. Re-views in every case, sharing the caller's
+// memory instead of taking a copy: `Buffer.from(arrayBuffer)` wraps the backing
 // store, it does not duplicate it. That is what makes this safe to call before a
-// size ceiling has been applied -- nothing is materialized -- and it is also why a
+// size ceiling has been applied (nothing is materialized), and it is also why a
 // caller that must hold the bytes across an await wants `snapshotSource`, which
-// copies, rather than this. Throws on a detached backing store.
+// copies. Throws on a detached backing store.
 // @enforced-by guard-shape-reinlined  (the re-view shape is declared on view above)
 function source(input, ErrorClass, code, label) {
   var isAb = input instanceof ArrayBuffer;
@@ -88,15 +88,15 @@ function source(input, ErrorClass, code, label) {
 // 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
+// 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`
+// 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
@@ -108,8 +108,8 @@ function snapshot(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
+// The same parse-then-verify defence as `snapshot`, over the whole W3C BufferSource
+// (raw ArrayBuffer / DataView / any typed-array view) and not 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.
@@ -121,25 +121,25 @@ function snapshotSource(input, ErrorClass, code, label) {
 
 // snapshotDeep(value, ErrorClass, code, label) -> a private copy of every byte leaf | throws
 //
-// `snapshot` closes the parse-then-verify window for ONE buffer. This closes it for a whole
-// caller-supplied SPEC -- the object a producing verb is handed and then reads across several
+// `snapshot` closes the parse-then-verify window for one buffer. This closes it for a whole
+// caller-supplied spec: the object a producing verb is handed and then reads across several
 // promise turns while it resolves a key, hashes, and signs. Every byte the verb ends up
 // encoding reaches it through some field of that object, and the caller still owns all of them,
 // so a spec validated at entry and read again after the first turn need not describe the same
 // certificate, CRL, or request. It is the same defect as an aliased buffer, one level up: the
 // value that passed the checks and the value that gets signed are two different reads.
 //
-// Copies byte views (through `snapshotSource`, so a detached backing store is refused rather
-// than copied as empty), arrays, dates, and PLAIN objects. Everything else -- a string, number,
-// bigint, boolean, a CryptoKey, any class instance -- is passed through by reference, because a
+// Copies byte views (through `snapshotSource`, so a detached backing store is refused instead
+// of copied as empty), arrays, dates, and plain objects. Everything else (a string, number,
+// bigint, boolean, a CryptoKey, any class instance) is passed through by reference, because a
 // non-plain object is a platform or library handle whose identity is what makes it work; cloning
 // one would break it. `opts.maxDepth` bounds a cyclic or hostile structure; the cap is set far
 // above any real spec (the deepest is a certificate policy's UserNotice noticeRef, around 12).
 //
-// **A spec that carries SECRET material must pass `opts.collect`**, an array this fills with every
+// A spec that carries secret material must pass `opts.collect`, an array this fills with every
 // buffer it copied. Copying a password or a private key produces a plaintext duplicate, and a
 // module whose ownership rules say "a caller's Buffer is borrowed, so leave it alone" will not
-// clear it -- the copy outlives the operation with no one accountable for it. Collect the copies
+// clear it: the copy outlives the operation with no one accountable for it. Collect the copies
 // and zeroize them in a `finally`, so the fix for one defect does not open another.
 // @enforced-by behavioral -- a copy has no rename-proof code shape to detect (any `Buffer.from(x)`
 //   is one). The guards are the RED vector that rewrites a field of the caller's spec after the
@@ -151,21 +151,21 @@ function snapshotDeep(value, ErrorClass, code, label, opts) {
   return _deep(value, ErrorClass, code, label, cap, 0, o.collect || null);
 }
 
-// Is this object a HANDLE -- something a copy would break rather than duplicate?
+// Is this object a handle, meaning something a copy would break instead of duplicate?
 //
 // The line is not "does it have Object.prototype". A caller's own class instance used as an
 // options bag is data, and passing it through by reference on the strength of its prototype left
 // exactly the window this exists to close: `cms.sign` accepts any non-Buffer object as options, so
 // an instance whose `signedAttributes` flipped to false after the call still reached the signing
 // turn. What a copy genuinely breaks is an object whose meaning lives somewhere other than its own
-// properties -- a key handle, a live collection, a pending result. Those are named here rather than
+// properties: a key handle, a live collection, a pending result. Those are named here, never
 // inferred, because inference gets it wrong in both directions: this engine's own CryptoKey carries
 // its Node key handle as an own property, so "has no own keys" would have copied it into a shell
 // that cannot sign, while a URL has none and would have copied into one that cannot be read.
-// isCryptoKeyLike is the toolkit's own answer to "is this a key handle" -- the same one key.js and
-// jose.js ask -- so a foreign implementation's CryptoKey is recognized here too.
-// The WebCrypto surface a CryptoKey presents, and nothing else. A real one -- this engine's, the
-// platform's, or another implementation's -- carries exactly these (its key material lives in an
+// isCryptoKeyLike is the toolkit's own answer to "is this a key handle", the same one key.js and
+// jose.js ask, so a foreign implementation's CryptoKey is recognized here too.
+// The WebCrypto surface a CryptoKey presents, and nothing else. A real one (this engine's, the
+// platform's, or another implementation's) carries exactly these (its key material lives in an
 // internal slot or a non-enumerable own property). A caller's options bag that happens to satisfy
 // the structural predicate carries its own fields alongside, and those are what give it away.
 var _CRYPTO_KEY_SURFACE = { type: 1, extractable: 1, algorithm: 1, usages: 1 };
@@ -181,9 +181,9 @@ var _THENABLE_SURFACE = { then: 1, catch: 1, finally: 1 };
 // Everything else is copied. Enumerating "handle shapes" to pass through was the wrong shape of
 // answer and lost repeatedly: every kind named as a handle turned out to be usable as an options
 // bag with fields glued on, and each new shape reopened the window for exactly the fields that
-// were glued on. There are only two honest outcomes for a caller's argument -- copy it, or refuse
-// it -- and this names the small set where copying is impossible, so the refusal below can be the
-// rule for all of them at once rather than a shape to be found later.
+// were glued on. There are only two honest outcomes for a caller's argument: copy it, or refuse
+// it. This names the small set where copying is impossible, so the refusal below can be the
+// rule for all of them at once, never a shape to be found later.
 // The surface an opaque kind is defined by, or null when the value is not one of them. A plain
 // object literal is never opaque whatever it looks like: it is data this module can read and copy,
 // and isCryptoKeyLike is structural by design so a literal can wear the key shape.
@@ -194,8 +194,8 @@ function _opaqueSurface(v, ErrorClass, code, label) {
   if (v instanceof Error) return _ERROR_SURFACE;
   if (v instanceof RegExp) return _REGEXP_SURFACE;
   if (require("./webcrypto").isCryptoKeyLike(v)) return _CRYPTO_KEY_SURFACE;   // allow:inline-require -- circular load: webcrypto requires this module
-  // Asking whether it is a thenable READS a property, and a caller's accessor can throw -- the
-  // same fault the copy itself types, so it is typed here too rather than escaping raw from a
+  // Asking whether it is a thenable reads a property, and a caller's accessor can throw: the
+  // same fault the copy itself types, so it is typed here too and never escapes raw from a
   // question this module asked on its own behalf.
   var then;
   try { then = v.then; }
@@ -204,17 +204,17 @@ function _opaqueSurface(v, ErrorClass, code, label) {
   return null;
 }
 
-// Is this opaque object safe to pass through -- carrying nothing beyond the surface its kind is
+// Is this opaque object safe to pass through, carrying nothing beyond the surface its kind is
 // defined by? Anything more is the case with no safe answer: the object cannot be copied, and
 // passing it through would leave that data the caller's to change after the checks have read it.
-// Every reachable name is examined, not only the own ones -- a verb reads a field by name and does
+// Every reachable name is examined, not only the own ones; a verb reads a field by name and does
 // not care where on the chain it sits.
 function _opaqueIsSafeToPass(v, surface) {
   var keys = _reachableKeys(v);
   for (var i = 0; i < keys.length; i++) {
     if (surface[keys[i]]) continue;
-    // Only what the CALLER put there. An implementation's own internals are non-enumerable by
-    // construction -- this engine's key handle, a platform object's slots -- and so are the methods
+    // Only what the caller put there. An implementation's own internals are non-enumerable by
+    // construction (this engine's key handle, a platform object's slots), and so are the methods
     // on any prototype, built-in or class-declared. What a caller adds, they add by assignment,
     // which is enumerable; that is the case the refusal is for, whatever the value's type. A
     // callable value is no exemption: an option is read for what it is, and `signedAttributes`
@@ -228,9 +228,9 @@ function _opaqueIsSafeToPass(v, surface) {
 // Every property name a `v.field` lookup could resolve: own and inherited, enumerable or not.
 //
 // The enumerable-only version of this was wrong three times running, each time in the same
-// direction -- own keys missed an inherited field, enumerable keys missed a non-enumerable one --
+// direction (own keys missed an inherited field, enumerable keys missed a non-enumerable one),
 // and each miss left the caller's object reachable behind a copy that looked complete. A verb reads
-// an option BY NAME, so the set that has to be fixed is the set a name lookup can reach, and
+// an option by name, so the set that has to be fixed is the set a name lookup can reach, and
 // nothing narrower. Object.prototype's own members are excluded: they are the language's, not the
 // caller's, and copying them onto every spec would shadow the prototype for no gain.
 function _reachableKeys(v) {
@@ -247,11 +247,11 @@ function _reachableKeys(v) {
   return names;
 }
 
-// A private copy of a byte value that is the SAME KIND as what the caller passed. The kind is
+// A private copy of a byte value of the same kind the caller passed. The kind is
 // load-bearing: each verb's own field validators decide which byte forms that field accepts, and
 // most accept only Buffer / Uint8Array. Handing them a Buffer made from a DataView or a
-// Uint16Array would have those inputs quietly accepted -- reinterpreted through a platform's own
-// element layout -- where they were rejected before. Copying is not the place to decide what a
+// Uint16Array would have those inputs quietly accepted, reinterpreted through a platform's own
+// element layout, where they were rejected before. Copying is not the place to decide what a
 // field takes, so the copy preserves the type and the validator still sees what it was given.
 function _copyBytesSameKind(v, ErrorClass, code, label, collect) {
   var src = source(v, ErrorClass, code, label);   // re-views; a detached backing store is refused
@@ -276,30 +276,30 @@ function _deep(v, ErrorClass, code, label, cap, depth, collect) {
     _copyNamed(v, bytesCopy, ErrorClass, code, label, cap, depth, collect);
     return bytesCopy;
   }
-  // A parsed structure carrying guard-parsed's provenance record is a HANDLE: the record is keyed
+  // A parsed structure carrying guard-parsed's provenance record is a handle: the record is keyed
   // on the object's identity, so a copy of it carries none and every door that decides integrity
-  // refuses the copy. It is also safe to leave alone -- that door re-derives from the bytes the
-  // record names, so nothing done to the object since matters. That holds for it AS A PARSE
-  // RESULT; a caller who adds an option to one and passes it where options are read by name has
-  // added a field no door re-derives, so `AsProduced` is what is asked rather than `isRecorded`.
+  // refuses the copy. It is also safe to leave alone, since that door re-derives from the bytes the
+  // record names, so nothing done to the object since matters. That holds for it as a parse
+  // result; a caller who adds an option to one and passes it where options are read by name has
+  // added a field no door re-derives, so `AsProduced` is what is asked, not `isRecorded`.
   // Required inline because guard-parsed requires this module; at call time it is fully loaded.
   if (require("./guard-parsed").isRecordedAsProduced(v)) return v;   // allow:inline-require -- circular load: guard-parsed requires this module
   if (v instanceof Date) return new Date(v.getTime());
   if (Array.isArray(v)) {
     var arr = [];
     for (var i = 0; i < v.length; i++) arr.push(_deep(v[i], ErrorClass, code, label, cap, depth + 1, collect));
-    // An array can carry NAMED properties too, and a verb reads an option by name whatever the
+    // An array can carry named properties too, and a verb reads an option by name whatever the
     // argument's type: `opts = []; opts.pem = true` is an options object as far as `opts.pem` is
     // concerned. Copying only the indexed elements dropped those fields, which silently changed
-    // what the verb was asked to do rather than failing.
+    // what the verb was asked to do instead of failing.
     _copyNamed(v, arr, ErrorClass, code, label, cap, depth, collect);
     return arr;
   }
   // The only kinds this module cannot read the state of. One carrying nothing of its own is passed
-  // through -- there is no data on it to fix, and a copy would break it. One carrying its own
+  // through: there is no data on it to fix, and a copy would break it. One carrying its own
   // fields has no safe handling at all: it cannot be copied, and passing it through would leave
-  // those fields the caller's to rewrite after the checks read them. That is refused rather than
-  // half-handled, which is what keeps this from being another shape to be found later.
+  // those fields the caller's to rewrite after the checks read them. That case is refused outright,
+  // never half-handled, which is what keeps this from being another shape to be found later.
   var surface = _opaqueSurface(v, ErrorClass, code, label);
   if (surface) {
     if (_opaqueIsSafeToPass(v, surface)) return v;
@@ -309,10 +309,10 @@ function _deep(v, ErrorClass, code, label, cap, depth, collect) {
   }
   if (v instanceof Map) return _copyEntries(v, new Map(), ErrorClass, code, label, cap, depth, collect);
   if (v instanceof Set) return _copyEntries(v, new Set(), ErrorClass, code, label, cap, depth, collect);
-  // The prototype is kept so an instance's methods still resolve. A null-prototype dictionary --
-  // what `JSON.parse` or an explicit `Object.create(null)` produces -- must not come back
-  // inheriting from Object.prototype either, which is why the prototype is carried across rather
-  // than assumed.
+  // The prototype is kept so an instance's methods still resolve. A null-prototype dictionary
+  // (what `JSON.parse` or an explicit `Object.create(null)` produces) must not come back
+  // inheriting from Object.prototype either, which is why the prototype is carried across and
+  // never assumed.
   var out = Object.create(Object.getPrototypeOf(v));
   _copyNamed(v, out, ErrorClass, code, label, cap, depth, collect);
   return out;
@@ -320,13 +320,13 @@ function _deep(v, ErrorClass, code, label, cap, depth, collect) {
 
 // Which names to carry across, given what the copy is.
 //
-// For a plain object or a class instance -- the shapes an options bag actually takes -- it is every
+// For a plain object or a class instance (the shapes an options bag actually takes) it is every
 // name a lookup could resolve, inherited included, because that is what the verb reads.
 //
-// For an array, a byte view, a Map or a Set, it is the caller's OWN added names only. Their
-// prototypes are full of accessors that describe the kind rather than the caller (`length`,
+// For an array, a byte view, a Map or a Set, it is the caller's own added names only. Their
+// prototypes are full of accessors that describe the kind, not the caller (`length`,
 // `buffer`, `size`, and Node's `parent`, which hands back the 64 KiB arena a small Buffer was
-// allocated from) -- every one of those is already correct on the copy, and reading them would
+// allocated from). Every one of those is already correct on the copy, and reading them would
 // copy things the caller never passed. Enumerating the accessors to skip is the wrong way round;
 // what the caller added is exactly what is own and not an index.
 function _namesToCopy(src, dst) {
@@ -343,7 +343,7 @@ function _namesToCopy(src, dst) {
 }
 
 // A Map or a Set is data the caller can still change, entry by entry, so it is copied like any
-// other -- entries first, then the named properties one can carry alongside them.
+// other: entries first, then the named properties one can carry alongside them.
 function _copyEntries(src, dst, ErrorClass, code, label, cap, depth, collect) {
   src.forEach(function (value, key) {
     var copiedValue = _deep(value, ErrorClass, code, label, cap, depth + 1, collect);
@@ -354,25 +354,25 @@ function _copyEntries(src, dst, ErrorClass, code, label, cap, depth, collect) {
   return dst;
 }
 
-// Copy every value a name lookup on `src` could reach onto `dst`, as an OWN data property.
+// Copy every value a name lookup on `src` could reach onto `dst`, as an own data property.
 //
 // Own matters: a key literally named `__proto__` would otherwise re-point `dst`, so the field the
 // caller passed disappears from Object.keys and an unknown-option check walks a different object
-// than the verb goes on to read. Shadowing matters for the same reason it is done at all -- an own
+// than the verb goes on to read. Shadowing matters for the same reason it is done at all: an own
 // copy is what makes an inherited value stop tracking the caller's prototype. A method is left
-// where it is: copying a function would only move it, and it is the prototype's behaviour rather
-// than the caller's data.
+// where it is, since copying a function would only move it, and it is the prototype's behaviour,
+// not the caller's data.
 function _copyNamed(src, dst, ErrorClass, code, label, cap, depth, collect) {
   var keys = _namesToCopy(src, dst);
   for (var k = 0; k < keys.length; k++) {
     var value;
     // Reading a caller's property can run a caller's accessor, and one that throws is a bad input
-    // like any other -- the fault gets this boundary's typed code with the raw error as its cause,
-    // rather than escaping as itself from inside a verb the caller called for something else.
+    // like any other: the fault gets this boundary's typed code with the raw error as its cause,
+    // and never escapes as itself from inside a verb the caller called for something else.
     try { value = src[keys[k]]; }
     catch (e) { throw _raise(ErrorClass, code, label + ": reading " + JSON.stringify(keys[k]) + " threw", e); }
-    // A function is carried across by reference rather than copied -- there is nothing in it to
-    // copy -- but it is still carried. Dropping it changed what the caller passed: an unknown spec
+    // A function is carried across by reference, since there is nothing in it to copy, but it is
+    // still carried. Dropping it changed what the caller passed: an unknown spec
     // field whose value happened to be a function stopped reaching the verb's own key check, so a
     // typo that used to be refused was silently accepted.
     Object.defineProperty(dst, keys[k], {
@@ -396,17 +396,17 @@ function _wasEnumerable(v, name) {
 // fixArguments(ErrorClass, code, args) -> { values, release }
 //
 // The whole rule for a verb that spans a promise turn, in one call. `args` is a list of
-// `[value, label]` pairs -- every argument the verb was handed. Each is deep-copied, so no field
+// `[value, label]` pairs, one per argument the verb was handed. Each is deep-copied, so no field
 // of any of them, at any depth, is still the caller's to change once the verb has begun; `release`
 // clears every copy that was made and belongs in a `finally`, so a copied password or private key
 // does not outlive the call.
 //
 // Both halves are needed and neither is optional. Copying only the argument that looks like data
-// leaves a secret nested inside the one that looks like a handle -- `opts.mac.secret` sitting a
-// level below a shallow copy -- readable and rewritable across the turn. Copying without releasing
+// leaves a secret nested inside the one that looks like a handle (`opts.mac.secret` sitting a
+// level below a shallow copy) readable and rewritable across the turn. Copying without releasing
 // answers that by duplicating the secret instead. Deciding per field which is which is the judgment
 // that keeps going wrong, so there is no per-field decision here: everything is copied, everything
-// copied is cleared, and the only things left alone are the ones a copy would BREAK -- a CryptoKey
+// copied is cleared, and the only things left alone are the ones a copy would break: a CryptoKey
 // or any class instance (its identity is what makes it work) and a recorded parse result (its
 // provenance is keyed to the object).
 // @enforced-by behavioral -- there is no rename-proof code shape for "copied every argument". The
@@ -415,7 +415,7 @@ function _wasEnumerable(v, name) {
 function fixArguments(ErrorClass, code, args) {
   var copies = [];
   var values = [];
-  // Through guard.secret, which owns what clearing a secret means -- required inline because
+  // Through guard.secret, which owns what clearing a secret means. Required inline because
   // guard-secret requires this module; at call time it is fully loaded.
   function release() {
     require("./guard-secret").zeroizeAll(copies, ErrorClass, code,   // allow:inline-require -- circular load: guard-secret requires this module
@@ -426,8 +426,8 @@ function fixArguments(ErrorClass, code, args) {
       values.push(snapshotDeep(args[i][0], ErrorClass, code, args[i][1], { collect: copies }));
     }
   } catch (e) {
-    // The copying itself can fail partway -- a detached leaf, a structure past the depth cap, a
-    // getter that throws -- and the arguments already copied by then are just as much ours as if
+    // The copying itself can fail partway (a detached leaf, a structure past the depth cap, a
+    // getter that throws), and the arguments already copied by then are just as much ours as if
     // the call had gone on to succeed. Returning nothing would leave the caller with no handle to
     // release them, so a signer key or a password copied before the fault would stay readable for
     // as long as the heap held it. Clear what was made, then let the fault out unchanged.
@@ -440,9 +440,9 @@ function fixArguments(ErrorClass, code, args) {
 // fixedCall(ErrorClass, code, args, body) -> Promise
 //
 // The form every Promise-returning producing verb uses, because the halves have to be arranged in
-// exactly one way and this is it. The copy runs INSIDE guard-async's boundary, so a fault in the
-// copy itself -- a detached view, a structure nested past the cap, a getter that throws -- leaves
-// as a REJECTION like every other fault of a verb documented `-> Promise<...>`, rather than as a
+// exactly one way and this is it. The copy runs inside guard-async's boundary, so a fault in the
+// copy itself (a detached view, a structure nested past the cap, a getter that throws) leaves
+// as a rejection like every other fault of a verb documented `-> Promise<...>`, never as a
 // synchronous throw past the caller's `.catch`. It still runs at the call, before any turn passes,
 // which is what fixes the arguments. And the release runs whether the body resolved, rejected, or
 // never ran, so a copied secret is cleared on every path out.

package/lib/guard-compress.js

@@ -28,7 +28,7 @@
 // `info: true`, each raises ERR_BUFFER_TOO_LARGE on a cap breach, and each
 // accepts trailing bytes when left unchecked.
 //
-// E is the caller's (code, message, cause) typed-error FACTORY -- never an error
+// E is the caller's (code, message, cause) typed-error factory, never an error
 // class. Passing a class here crashes on the error path ("class cannot be invoked
 // without new"), which converts a rejection into a fail-open. `codes` names the
 // two verdicts a caller distinguishes: `tooLarge` when the output would exceed
@@ -45,8 +45,8 @@ var DECOMPRESS = {
   zstd: zlib.zstdDecompressSync,        // RFC 8478
 };
 
-// The compressors, used ONLY by the truncation probe below. Producing a compressed stream is
-// not the guarded shape -- decompressing an untrusted one is.
+// The compressors, used only by the truncation probe below. Producing a compressed stream is
+// not the guarded shape; decompressing an untrusted one is.
 var _PROBE_COMPRESS = {
   zlib: zlib.deflateSync,
   brotli: zlib.brotliCompressSync,
@@ -55,22 +55,22 @@ var _PROBE_COMPRESS = {
 
 // A decompressor must REPORT a frame it could not finish. Not all of them do: on some supported
 // runtimes the zstd binding returns a SHORT (often empty) result for a truncated frame instead
-// of faulting, and reports the entire input as consumed -- so neither the returned bytes nor the
+// of faulting, and reports the entire input as consumed, so neither the returned bytes nor the
 // consumed-length check below can see that the frame was cut. That is a silent truncation: a peer
 // strips a frame's tail and the receiver processes a prefix as though it were the whole message.
 //
 // An algorithm whose runtime cannot report this cannot be decompressed safely here, so it is
-// dropped from the advertised set at load rather than accepted with a defect. Consumers build
+// dropped from the advertised set at load instead of accepted with a defect. Consumers build
 // their wire registries by intersecting with algorithms(), so a protocol simply does not offer
 // or accept it, and it returns on its own once the runtime reports truncation.
-// Nothing here is enabled by an exception alone: an algorithm qualifies only by POSITIVE proof
-// that a whole frame round-trips AND that a cut frame is refused. Every other outcome -- a
-// missing function, a compressor fault, a wrong round-trip, an unrelated error -- leaves it out.
+// Nothing here is enabled by an exception alone: an algorithm qualifies only by positive proof
+// that a whole frame round-trips and that a cut frame is refused. Every other outcome (a
+// missing function, a compressor fault, a wrong round-trip, an unrelated error) leaves it out.
 //
 // Coverage residual: the early-return branches are reachable only on a runtime whose own
 // compression library is broken (a missing export, a compressor that throws on 46 ASCII bytes, a
 // round-trip that does not reproduce its input). The tables are captured at module load, so those
-// states cannot be induced from a test without replacing node:zlib beforehand -- and forcing them
+// states cannot be induced from a test without replacing node:zlib beforehand, and forcing them
 // would assert nothing about the property this function exists to establish. They stay because
 // their absence is what would make a broken runtime silently qualify an algorithm.
 function _reportsTruncation(name) {
@@ -82,13 +82,13 @@ function _reportsTruncation(name) {
   try { frame = compress(sample); }
   catch (_e) { /* allow:swallow-unverified a compressor that cannot compress 46 ASCII bytes is a broken runtime; the algorithm simply does not qualify, which is the fail-closed direction */ return false; }
   // A cut of 2 removes the frame's end marker; the sample is long enough that what remains is
-  // still a plausible frame head rather than nothing at all.
+  // still a plausible frame head and not nothing at all.
   if (!Buffer.isBuffer(frame) || frame.length < 4) return false;
   try { whole = decompress(frame, { maxOutputLength: 4096 }); }
   catch (_e2) { /* allow:swallow-unverified a decompressor that rejects its own compressor's whole frame is a broken runtime; the algorithm does not qualify, again fail-closed */ return false; }
   if (!Buffer.isBuffer(whole) || !whole.equals(sample)) return false;
-  // The cut frame must be REFUSED. A returned value of any length -- including the empty buffer
-  // some bindings hand back -- means a truncation would pass through unseen.
+  // The cut frame must be refused. A returned value of any length, including the empty buffer
+  // some bindings hand back, means a truncation would pass through unseen.
   var cutAccepted = false;
   try {
     decompress(frame.subarray(0, frame.length - 2), { maxOutputLength: 4096 });
@@ -115,7 +115,7 @@ function bounded(algorithm, stream, cap, E, codes, label) {
   // An unknown algorithm -- or one this runtime cannot decompress safely -- is an authoring
   // fault, not untrusted input: a caller resolves a wire value to a name against algorithms()
   // and rejects one it does not find, before reaching here. Arriving with a name outside that
-  // set means the consumer skipped the step, so it faults loudly rather than silently.
+  // set means the consumer skipped the step, so it faults loudly and never silently.
   if (!Object.prototype.hasOwnProperty.call(SAFE, algorithm) || !decompress) {
     throw new TypeError("guard.compress.bounded: unknown or unsafe algorithm " + JSON.stringify(algorithm));
   }
@@ -127,7 +127,7 @@ function bounded(algorithm, stream, cap, E, codes, label) {
   // The ceiling is an authoring input: an undefined / NaN / fractional / negative
   // cap would silently disable the bomb defence. It must also be at least 1 --
   // node rejects maxOutputLength 0 with a different fault than a cap breach, so a
-  // zero cap would surface as a malformed-stream verdict rather than a config error.
+  // zero cap would surface as a malformed-stream verdict instead of a config error.
   if (!Number.isInteger(cap) || cap < 1) {
     throw new TypeError("guard.compress.bounded: cap must be a positive integer");
   }
@@ -142,8 +142,8 @@ function bounded(algorithm, stream, cap, E, codes, label) {
     throw E(codes.failed, what + " could not be decompressed", e);
   }
   // `bytesWritten` is the count of INPUT bytes the engine consumed. A frame that
-  // ends before the input does means the remainder was ignored -- the malleability
-  // above -- so the whole input must be exactly one frame.
+  // ends before the input does means the remainder was ignored, which is the
+  // malleability above, so the whole input must be exactly one frame.
   var consumed = res.engine.bytesWritten;
   if (consumed !== stream.length) {
     throw E(codes.failed, what + " carries " + (stream.length - consumed) +
@@ -152,7 +152,7 @@ function bounded(algorithm, stream, cap, E, codes, label) {
   return res.buffer;
 }
 
-// The algorithm names this guard can decompress SAFELY on this runtime -- the registry
+// The algorithm names this guard can decompress safely on this runtime: the registry
 // minus any whose decompressor cannot report an unfinished frame. A consumer intersects
 // its protocol's algorithm registry with this, so it never advertises or accepts something
 // it could not refuse a truncation of.

package/lib/guard-crypto.js

@@ -25,7 +25,7 @@
 // MAC / digest BIT STRING with a non-zero unused-bits count is not whole octets,
 // so trailing sub-octet bits let two encodings carry "one" signature. Every RFC
 // 9481/4211/6960/5280 signature output is a whole number of octets, so a value
-// with unusedBits !== 0 fails closed BEFORE its bytes reach a verifier.
+// with unusedBits !== 0 fails closed before its bytes reach a verifier.
 
 var nodeCrypto = require("node:crypto");
 

package/lib/guard-encoding.js

@@ -10,28 +10,28 @@
 // guard-encoding -- strict decode of an untrusted base64 / base64url / hex text
 // to bytes. Node's Buffer.from(x, "base64"|"base64url"|"hex") is LENIENT: it
 // silently drops the first invalid character (and everything after a stray one),
-// accepts non-canonical trailing bits, and tolerates missing/extra padding, so
-// two distinct texts alias one byte string -- or a malformed text decodes to a
-// SHORTER, different value than intended. And it allocates the whole decode
-// before any size is checked. This is CWE-172 (encoding-transformation error) /
+// accepts non-canonical trailing bits, and tolerates missing/extra padding. Two
+// distinct texts can therefore alias one byte string, and a malformed text can
+// decode to a shorter, different value than intended. And it allocates the whole
+// decode before any size is checked. This is CWE-172 (encoding-transformation error) /
 // CWE-20 (canonicalization malleability) + CWE-770 (allocate-before-cap): RFC
 // 4648 sec. 3.5 / sec. 5 and RFC 8555 sec. 6.1 require the UNIQUE canonical
 // encoding. Each decoder here gates the alphabet, rejects an impossible length,
-// enforces the byte cap BEFORE the copy, decodes, and verifies canonicality by a
-// re-encode round-trip -- so a value that is not the one canonical encoding of
+// enforces the byte cap before the copy, decodes, and verifies canonicality by a
+// re-encode round-trip, so a value that is not the one canonical encoding of
 // its bytes fails closed with the caller's typed error.
 //
 // E is the caller's (code, message) typed-error factory; `code` the frozen
 // domain/reason; `label` the field phrase; `maxBytes` an optional decoded-size
 // cap (null/undefined = uncapped, for a PEM cert body already bounded upstream).
 
-// The alphabets are TABLES, walked one character at a time, rather than regular
-// expressions. A guard runs on the most hostile input the toolkit sees, and a
-// pattern engine's cost on a non-matching string is a property of the pattern
-// rather than of the length -- the one thing a bound cannot be placed on from the
-// outside. A table lookup is one array index per character and its cost is the
-// length, which the caller already caps. It is also the more honest statement of
-// the rule: the set of permitted characters IS the rule, written out.
+// The alphabets are tables, walked one character at a time. Regular expressions
+// would be the obvious alternative, but a guard runs on the most hostile input
+// the toolkit sees, and a pattern engine's cost on a non-matching string is
+// decided by the pattern, which is the one thing a bound cannot be placed on from
+// the outside. A table lookup is one array index per character, so its cost
+// follows the length, which the caller already caps. It is also the more honest
+// statement of the rule: the set of permitted characters is the rule, written out.
 function _alphabet(chars) {
   var t = new Uint8Array(128);
   for (var i = 0; i < chars.length; i++) t[chars.charCodeAt(i)] = 1;
@@ -43,8 +43,8 @@ var B64_ALPHABET = _alphabet(UPPER + LOWER + DIGITS + "+/");
 var HEX_ALPHABET = _alphabet(DIGITS + "abcdef" + "ABCDEF");
 
 // Every character of `text` is in `table`. A code point outside Latin-1's low half
-// (including every astral half) is outside all three alphabets, so the table bound
-// is the reject rather than an index that reads undefined.
+// (including every astral half) is outside all three alphabets, and the explicit
+// bound rejects it, so no lookup can read undefined off the end of the table.
 function _inAlphabet(text, table) {
   for (var i = 0; i < text.length; i++) {
     var c = text.charCodeAt(i);

package/lib/guard-header.js

@@ -20,9 +20,9 @@
 var C = require("./constants");
 
 // assertField(name, value, E, code) -> value | throws new E(code, ...)
-// name: RFC 5322 ftext -- printable ASCII [0x21, 0x7e] except ':' (0x3a), non-empty
+// name: RFC 5322 ftext, printable ASCII [0x21, 0x7e] except ':' (0x3a), non-empty
 //   (a space, control byte, or ':' in a field name breaks the "Name: value" grammar).
-// value: reject CR (0x0d) / LF (0x0a) / NUL (0x00) -- the injection bytes; TAB
+// value: reject CR (0x0d), LF (0x0a) and NUL (0x00), the injection bytes; TAB
 //   (0x09, folding whitespace) and printable non-ASCII (a UTF-8 header value, RFC
 //   6532) pass. E is the caller's typed-error CLASS, thrown `new E(code, message)`
 //   -- the same convention lib/mime.js (this guard's caller) and guard.bytes/text use.
@@ -42,7 +42,7 @@ function assertField(name, value, E, code) {
     if (vc === 0x00 || vc === 0x0d || vc === 0x0a) throw new E(code, "a header field value must not contain CR / LF / NUL (header injection) in " + JSON.stringify(name));
   }
   // RFC 5322 sec. 2.1.1: the serialized "Name: value" line (UTF-8 octets, excluding CRLF) must not exceed
-  // the line limit, or a relay may re-fold it -- silently changing the signed bytes of a protected header.
+  // the line limit, or a relay may re-fold it and silently change the signed bytes of a protected header.
   if (Buffer.byteLength(name, "utf8") + 2 + Buffer.byteLength(v, "utf8") > C.LIMITS.HEADER_LINE_MAX_OCTETS) {
     throw new E(code, "a header field line exceeds RFC 5322's " + C.LIMITS.HEADER_LINE_MAX_OCTETS + "-octet limit: " + JSON.stringify(name));
   }