@blamejs/pki 0.5.6 → 0.5.8

package/lib/guard-bytes.js

@@ -6,6 +6,8 @@
 // primitives whose input boundaries compose these guards (pki.asn1.decode,
 // pki.cbor.decode, pki.ct.parseSctList, pki.webcrypto.*).
 //
+var async = require("./guard-async");
+
 // guard-bytes -- fail-closed coercion of an untrusted byte-source input to a
 // Buffer view. One of the enforced choke points of the guard family: a
 // codebase-patterns detector requires every byte-input boundary to route
@@ -19,10 +21,30 @@
 // 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 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
+// 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
+// constructed, anything else is called.
+function _raise(E, code, message, cause) {
+  return (E.prototype instanceof Error) ? new E(code, message, cause) : E(code, message, cause);
+}
+
 // view(input, ErrorClass, code, label) -> Buffer view | throws ErrorClass(code, msg, cause)
 // Accepts a Buffer / Uint8Array -- the DER / CBOR / CT / Merkle input contract.
 // ErrorClass MUST be a withCause PkiError subclass (the raw detach failure is
@@ -34,20 +56,20 @@ function view(input, ErrorClass, code, label) {
     try {
       return Buffer.from(input.buffer, input.byteOffset, input.byteLength);
     } catch (e) {
-      throw new ErrorClass(code, label + ": input is not a usable byte view (detached backing buffer?)", e);
+      throw _raise(ErrorClass, code, label + ": input is not a usable byte view (detached backing buffer?)", e);
     }
   }
-  throw new ErrorClass(code, label + ": expected a Buffer / Uint8Array");
+  throw _raise(ErrorClass, code, label + ": expected a Buffer / Uint8Array");
 }
 
 // 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;
@@ -55,10 +77,10 @@ function source(input, ErrorClass, code, label) {
     try {
       return isAb ? Buffer.from(input) : Buffer.from(input.buffer, input.byteOffset, input.byteLength);
     } catch (e) {
-      throw new ErrorClass(code, label + ": input is not a usable byte source (detached backing buffer?)", e);
+      throw _raise(ErrorClass, code, label + ": input is not a usable byte source (detached backing buffer?)", e);
     }
   }
-  throw new ErrorClass(code, label + ": expected a BufferSource (ArrayBuffer / TypedArray / Buffer)");
+  throw _raise(ErrorClass, code, label + ": expected a BufferSource (ArrayBuffer / TypedArray / Buffer)");
 }
 
 // snapshot(input, ErrorClass, code, label) -> private Buffer copy | throws ErrorClass
@@ -66,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
@@ -86,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.
@@ -97,4 +119,345 @@ function snapshotSource(input, ErrorClass, code, label) {
   return Buffer.from(source(input, ErrorClass, code, label));
 }
 
-module.exports = { view: view, source: source, snapshot: snapshot, snapshotSource: snapshotSource };
+// 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
+// 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 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
+// 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
+// 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
+//   verb has returned its promise and asserts the emitted artifact carries the entry value, and
+//   the vector that holds a reference to every copy and asserts it reads all-zero after the call.
+function snapshotDeep(value, ErrorClass, code, label, opts) {
+  var o = opts || {};
+  var cap = o.maxDepth == null ? 64 : o.maxDepth;
+  return _deep(value, ErrorClass, code, label, cap, 0, o.collect || null);
+}
+
+// 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, 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
+// 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 };
+// The same, for the other kinds whose state cannot be copied: what belongs to the kind, so that
+// anything else on the object is recognizably the caller's own and gets the refusal below.
+var _ERROR_SURFACE = { message: 1, stack: 1, name: 1, cause: 1 };
+var _REGEXP_SURFACE = { lastIndex: 1, source: 1, flags: 1, global: 1, ignoreCase: 1, multiline: 1,
+  sticky: 1, unicode: 1, unicodeSets: 1, hasIndices: 1, dotAll: 1 };
+var _THENABLE_SURFACE = { then: 1, catch: 1, finally: 1 };
+
+// Is this an object whose state this module cannot read, and therefore cannot copy?
+//
+// 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. 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.
+function _opaqueSurface(v, ErrorClass, code, label) {
+  var proto = Object.getPrototypeOf(v);
+  if (proto === Object.prototype || proto === null) return null;
+  if (v instanceof WeakMap || v instanceof WeakSet) return {};   // deliberately not enumerable
+  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 and never escapes raw from a
+  // question this module asked on its own behalf.
+  var then;
+  try { then = v.then; }
+  catch (e) { throw _raise(ErrorClass, code, label + ": reading \"then\" threw", e); }
+  if (typeof then === "function") return _THENABLE_SURFACE;      // a pending result, not a value
+  return null;
+}
+
+// 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
+// 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
+    // 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`
+    // holding a function is neither false nor a method of anything.
+    if (!_wasEnumerable(v, keys[i])) continue;
+    return false;
+  }
+  return true;
+}
+
+// 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),
+// 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
+// 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) {
+  var names = [];
+  var seen = Object.create(null);
+  for (var o = v; o && o !== Object.prototype; o = Object.getPrototypeOf(o)) {
+    var own = Object.getOwnPropertyNames(o);
+    for (var i = 0; i < own.length; i++) {
+      if (own[i] === "constructor" || seen[own[i]]) continue;
+      seen[own[i]] = true;
+      names.push(own[i]);
+    }
+  }
+  return names;
+}
+
+// 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
+// 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
+  var owned = new ArrayBuffer(src.length);
+  new Uint8Array(owned).set(src);
+  // What `release` clears: a Buffer over the whole private store, whatever kind is handed back.
+  if (collect) collect.push(Buffer.from(owned, 0, src.length));
+  if (Buffer.isBuffer(v)) return Buffer.from(owned, 0, src.length);
+  if (v instanceof ArrayBuffer) return owned;
+  if (v instanceof DataView) return new DataView(owned);
+  return new v.constructor(owned, 0, src.length / v.BYTES_PER_ELEMENT);
+}
+
+function _deep(v, ErrorClass, code, label, cap, depth, collect) {
+  if (depth > cap) throw _raise(ErrorClass, code, label + " is nested too deeply to copy");
+  if (v == null || typeof v !== "object") return v;
+  if (Buffer.isBuffer(v) || ArrayBuffer.isView(v) || v instanceof ArrayBuffer) {
+    var bytesCopy = _copyBytesSameKind(v, ErrorClass, code, label, collect);
+    // A byte value can carry named properties too, and a verb reads an option by name whatever the
+    // argument's type: `opts = new Uint8Array(0); opts.pem = true` is an options object as far as
+    // `opts.pem` is concerned. An ArrayBuffer is extensible and takes them the same way.
+    _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
+  // 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, 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
+    // 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 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
+  // 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 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;
+    throw _raise(ErrorClass, code, label + ": a " + (v.constructor && v.constructor.name || "value") +
+      " carrying its own fields cannot be used here -- its state cannot be copied, so those fields " +
+      "would stay changeable after they were checked; pass the fields as a plain object");
+  }
+  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 and
+  // never assumed.
+  var out = Object.create(Object.getPrototypeOf(v));
+  _copyNamed(v, out, ErrorClass, code, label, cap, depth, collect);
+  return out;
+}
+
+// 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
+// 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, 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
+// 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) {
+  var indexed = Array.isArray(dst) || ArrayBuffer.isView(dst);
+  var kind = indexed || dst instanceof Map || dst instanceof Set || dst instanceof ArrayBuffer;
+  if (!kind) return _reachableKeys(src);
+  var own = Object.getOwnPropertyNames(src);
+  var out = [];
+  for (var i = 0; i < own.length; i++) {
+    if (own[i] === "length" || (indexed && String(Number(own[i])) === own[i])) continue;
+    out.push(own[i]);
+  }
+  return out;
+}
+
+// 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.
+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);
+    if (dst instanceof Set) dst.add(copiedValue);
+    else dst.set(_deep(key, ErrorClass, code, label, cap, depth + 1, collect), copiedValue);
+  });
+  _copyNamed(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.
+//
+// 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
+// copy is what makes an inherited value stop tracking the caller's prototype. A method is left
+// 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,
+    // 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, 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], {
+      value: typeof value === "function" ? value
+        : _deep(value, ErrorClass, code, label, cap, depth + 1, collect),
+      writable: true, enumerable: _wasEnumerable(src, keys[k]), configurable: true,
+    });
+  }
+}
+
+// Whether a name lookup on `v` would have found this property as an enumerable one, anywhere on
+// the chain -- so the copy's own keys enumerate the way the original's did.
+function _wasEnumerable(v, name) {
+  for (var o = v; o && o !== Object.prototype; o = Object.getPrototypeOf(o)) {
+    var d = Object.getOwnPropertyDescriptor(o, name);
+    if (d) return !!d.enumerable;
+  }
+  return false;
+}
+
+// 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, 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
+// 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
+// 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
+//   guard is the per-verb RED vector that mutates each argument after the verb returns its promise
+//   and asserts the artifact carries the entry value.
+function fixArguments(ErrorClass, code, args) {
+  var copies = [];
+  var values = [];
+  // 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
+      "a copy of a caller-supplied argument");
+  }
+  try {
+    for (var i = 0; i < args.length; i++) {
+      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 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.
+    release();
+    throw e;
+  }
+  return { values: values, release: release };
+}
+
+// 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<...>`, 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.
+// @enforced-by behavioral -- an arrangement of two calls has no rename-proof shape to detect. The
+//   guards are promise-contract.test.js (every documented Promise verb refuses by rejecting, now
+//   including a fault raised by the copy itself) and the per-verb entry-value vectors.
+function fixedCall(ErrorClass, code, args, body) {
+  var handle = null;
+  return async.deferred(function () {
+    handle = fixArguments(ErrorClass, code, args);
+    return body.apply(null, handle.values);
+  }).finally(function () { if (handle) handle.release(); });
+}
+
+module.exports = {
+  view: view, source: source, snapshot: snapshot, snapshotSource: snapshotSource,
+  snapshotDeep: snapshotDeep, fixArguments: fixArguments, fixedCall: fixedCall,
+};

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);