@blamejs/pki 0.6.13 → 0.6.15

package/lib/guard-secret.js

@@ -1,127 +1,30 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- no operator-facing namespace. The documented surface is the KEM
-// key-establishment paths that compose this guard (pki.cms.encrypt / decrypt).
-//
-// guard-secret -- wipe a secret buffer the TOOLKIT ALLOCATED at the moment it
-// stops being needed. NIST SP 800-227 RS5 / sec. 4.2 requires that a KEM shared
-// secret and every intermediate value be destroyed as soon as they are no longer
-// needed; RFC 9629 sec. 7 says the same of the KEK a KEMRecipientInfo derives.
-//
-// The defended class is secret lifetime, not secret disclosure: a shared secret
-// or KEK left readable in the heap widens the window in which a later memory
-// disclosure -- a core dump, a swapped page, a same-process read primitive --
-// yields key material for traffic that was already decrypted.
-//
-// SCOPE, stated honestly because the docstring is the only place a reader learns
-// it: this is BEST EFFORT. The runtime copies buffers into places no JS can
-// reach (node's decapsulate return is copied on the way out; importKey("raw")
-// copies into a KeyObject), and V8 may relocate a backing store, leaving the
-// original bytes behind. Wiping the copies the toolkit holds shortens the
-// window. It does not support a claim that a secret never persists in memory,
-// and no operator-facing text may imply that it does.
-//
-// Ownership is the contract. Only a buffer the toolkit allocated may be wiped:
-// never a caller's opts.key / opts.cert / opts.kek / opts.password, and never the
-// input DER. Silently destroying a caller's own memory is a worse defect than
-// leaving a secret readable, and it is the failure mode a zeroization patch
-// reaches for first, so the call sites pass only their own intermediates.
+// @internal
 
 var bytes = require("./guard-bytes");
 var intrinsic = require("./guard-intrinsic");
 
-// The fill this guard performs, taken from the typed-array prototype at module load and uncurried
-// so the wipe site reads no property at all. Buffer overrides the fill with a writable
-// `Buffer.prototype.fill`, so reading the method off the value would let a caller decide what
-// wiping means; reading `call` off the captured function would let them decide it again, since
-// that function is still the one sitting on the prototype (see guard-intrinsic).
 var _fill = intrinsic.uncurry(Uint8Array.prototype.fill);
-// The join that produces the buffer cipherFinish hands back. Captured for the same reason as
-// the fill: a replaced `Buffer.concat` decides what the caller receives, and it would receive it
-// while the two intermediates this module is responsible for clearing were cleared as promised.
 var _concat = intrinsic.bufferConcat;
 
-// zeroize(value, ErrorClass, code, label) -> the same object, cleared.
-//   value      : a Buffer / TypedArray the TOOLKIT allocated, or null / undefined
-//                (absent is a no-op so a `finally` needs no branch around it).
-//   ErrorClass : the caller's typed error CONSTRUCTOR, declared with
-//                `{ withCause: true }`. The guard family carries two currencies --
-//                most guards take a (code, message) factory and call it without
-//                `new`, while guard-bytes / guard-header take the class and
-//                construct it. This module's one throw is the delegated re-view
-//                below, so it must pass what guard-bytes expects: the class, and
-//                one that accepts a cause, because guard-bytes threads the raw
-//                detach fault through as one. A plain class fails to construct at
-//                the single moment the caller needs a real error.
-//   code       : the frozen domain/reason code a detached buffer rejects under.
-//   label      : field phrase for the message.
-//
-// A detached ArrayBuffer cannot be written, and reaching one here means a caller
-// handed over memory that was transferred away. That is a real fault and not
-// something to swallow, so it routes through the shared re-view guard and throws
-// typed.
-//
-// The `.fill(0)` shape lives only in this module. A wipe re-inlined anywhere in
-// lib/, including a module not yet written, is flagged, so the safe implementation
-// is also the tripwire that stops the next consumer from rolling its own partial
-// one.
 // @enforced-by guard-shape-reinlined
 // @guard-shape \.fill\s*\(\s*0\s*[,)]
 function zeroize(value, ErrorClass, code, label) {
   if (value === null || value === undefined) return value;
-  // Re-view through the shared bytes guard: it is the single place that decides
-  // what counts as a writable BufferSource and rejects a detached one typed.
   var view = bytes.view(value, ErrorClass, code, label);
-  // Through the fill captured at module load, never `view.fill(0)`. Buffer overrides the typed-array
-  // fill with its own, and that property is writable, so a caller who replaces it with a no-op turns
-  // every wipe in the toolkit into a silent nothing -- and nothing observable changes, because the
-  // wipe still runs, still walks the right buffer, and still returns. A secret that survives a call
-  // whose whole purpose was to clear it is the failure this guard exists to prevent, so the one
-  // operation it performs is the one operation a caller must not be able to reach.
   _fill(view, 0);
   return value;
 }
 
-// zeroizeAll(list, ErrorClass, code, label) wipes every present member, tolerating
-// holes so a `finally` can name intermediates that may not have been reached.
-//
 // @enforced-by behavioral -- this is a loop over zeroize, which carries the family's only
-// rename-proof shape (the `.fill(0)` above). It introduces no shape of its own, so a lexical
-// detector here would anchor on a renameable symbol and go silently green (drift rule sec. 3).
-// The behavioral guards are guard-secret.test.js (holes tolerated, every member cleared) and the
-// CMS vectors that assert the shared secret and KEK are wiped on both the success and failure paths.
 function zeroizeAll(list, ErrorClass, code, label) {
   if (!list) return list;
   for (var i = 0; i < list.length; i++) zeroize(list[i], ErrorClass, code, label);
   return list;
 }
 
-// cipherFinish(transform, input, ErrorClass, code, label) -> the output, as one fresh buffer
-//   transform : a node:crypto Cipher or Decipher the CALLER built and configured (key, iv, AAD,
-//               auth tag, padding mode). This guard performs the two calls and nothing else.
-//   input     : the bytes to feed it.
-//
-// The single place this toolkit runs a configured cipher to completion, because
-// `Buffer.concat([c.update(x), c.final()])` abandons a copy on BOTH of its exits and the leak is
-// invisible at the call site.
-//
-// On a DECIPHER the abandoned copy is plaintext. `update` returns the recovered plaintext while
-// `final` is what decides whether the message was authentic at all -- a GCM tag mismatch, a CBC
-// padding failure -- so on a forged message the whole plaintext exists before anything has judged
-// it, and the `concat` never runs: that buffer becomes unreferenced garbage holding readable
-// plaintext. RFC 5083 sec. 1 requires a receiver whose integrity check fails to destroy the
-// plaintext, and withholding it from the caller is not destroying it. On the success path `concat`
-// COPIES, so the update buffer is a second full copy the caller never receives and nothing else
-// will ever clear.
-//
-// It covers the ENCRYPT direction too, where the intermediates are ciphertext and clearing them
-// buys little. That is deliberate: any rule for which of the two directions must clear is a
-// judgment made at each call site, and the sites where it is wrong are the ones nobody re-reads.
-// One shape, cleared everywhere, needs no such judgment -- and the encrypt intermediates of a
-// key-wrap are not obviously worthless to an attacker either.
-//
 // @enforced-by guard-shape-reinlined
 // @guard-shape \.update\s*\([\s\S]{0,300}?\)\s*,\s*[A-Za-z_$][\w$]*\s*\.\s*final\s*\(\s*\)
 function cipherFinish(transform, input, ErrorClass, code, label) {
@@ -129,8 +32,6 @@ function cipherFinish(transform, input, ErrorClass, code, label) {
   try {
     head = transform.update(input);
     tail = transform.final();
-    // Always a fresh copy, never `head` itself: the returned buffer belongs to the caller and the
-    // two intermediates have to be clearable independently of it.
     return _concat([head, tail]);
   } finally {
     zeroize(head, ErrorClass, code, label);
@@ -138,6 +39,4 @@ function cipherFinish(transform, input, ErrorClass, code, label) {
   }
 }
 
-// Frozen for the reason the family header gives: a boundary reads its guard off this object at the
-// call, so a writable export would let a caller replace the check rather than pass it.
 module.exports = intrinsic.freeze({ zeroize: zeroize, zeroizeAll: zeroizeAll, cipherFinish: cipherFinish });

package/lib/guard-text.js

@@ -1,86 +1,27 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- no operator-facing namespace. The documented surface is the
-// primitives whose text boundaries compose this guard (pki.jose.parseJson, the
-// PEM decoders, the EST transfer decoders).
-//
-// guard-text -- fail-closed decode of an untrusted byte-source input to a
-// string, capping the raw byte length before the string is materialized.
-// Enforced choke point for the byte->string boundary.
-//
-// Defends the parser-DoS string-allocation class (CWE-770 allocation without
-// limits, CWE-400 uncontrolled resource consumption; MITRE T1499.001). The
-// ORDERING is the invariant: cap the byte length, THEN decode. Decoding a Buffer
-// to a string first allocates a full-size string for input the cap is about to
-// reject; worse, a buffer above Node's max string length escapes the decode as
-// an untyped ERR_STRING_TOO_LONG instead of the caller's typed <tooLarge>. This
-// guard defines the cap-before-copy ordering and the fatal-UTF-8 decode once so
-// no boundary re-derives it (and drifts to cap-after, as some had).
+// @internal
 
 var bytes = require("./guard-bytes");
 var intrinsic = require("./guard-intrinsic");
 
-// Everything this guard does to a caller's input, taken at module load. Each name below is an
-// ordinary writable property of a global, so reading it at call time would let a caller decide what
-// the guard does at the moment it does it. Between them these four cover both of the guard's
-// contracts, and both of its input arms:
-//
-//   _toString / _decode  produce the guard's entire output on the Buffer arm. Replaced with a
-//                        function returning a constant, they hand a PEM header, a JOSE segment or a
-//                        DN attribute value a string the caller chose in place of the bytes that
-//                        were checked -- while the cap, the detached-view refusal and the strict
-//                        UTF-8 rule all still run and all still pass.
-//   _byteLength          measures the string arm against the cap. One returning 0 admits a string
-//                        of any size, which is the allocation-DoS this guard exists to bound.
-//   _isInteger           decides whether the cap itself is usable; guard.bytes.isByteSource decides
-//                        whether an input takes the byte arm or the string arm.
-// The two method captures are uncurried, so their call sites read no property of them; see
-// guard-intrinsic for why capturing a method and then reading `.call` on it reopens the hole.
 var _toString = intrinsic.uncurry(Buffer.prototype.toString);
 var _decode = intrinsic.uncurry(TextDecoder.prototype.decode);
-// Already plain functions rather than methods, so these are invoked directly.
 var _byteLength = Buffer.byteLength;
 var _isInteger = Number.isInteger;
 var _TextDecoder = TextDecoder;
 
 var LATIN1 = "latin1";
 
-// decode(input, maxBytes, ErrorClass, spec) -> string.
-//   input     : a Buffer (decoded per spec.charset) or a string (taken as-is).
-//   maxBytes  : the raw byte-length ceiling, checked before any string copy.
-//   ErrorClass: a PkiError subclass (withCause where spec.fatal is set).
-//   spec      : { charset: "latin1"|"utf-8" (default latin1),
-//                 fatal:   boolean, strict UTF-8 (a lone continuation /
-//                          truncated sequence throws, never substitutes U+FFFD),
-//                 tooLarge: code for the over-cap reject,
-//                 badDecode: code for a fatal-charset (bad-UTF-8) reject
-//                            (required only when fatal is set),
-//                 badInput: code for a non-byte-source/non-string reject,
-//                 label:    human phrase for the message }
 // @enforced-by behavioral -- cap-before-copy has no rename-proof code shape; the
-//   over-cap RED vectors + the detached re-view through guard.bytes.source (itself
-//   enforced) are the guard.
 function decode(input, maxBytes, ErrorClass, spec) {
-  // maxBytes is an authoring input: an undefined / NaN / fractional cap makes
-  // the `length > maxBytes` comparison always false, silently disabling the size
-  // cap on the guard whose whole contract is cap-before-copy. Config-time
-  // TypeError (every composing boundary passes a C.LIMITS constant).
   if (!_isInteger(maxBytes) || maxBytes < 0) {
     throw new TypeError("guard.text.decode: maxBytes must be a non-negative integer");
   }
   var charset = spec.charset || LATIN1;
   if (bytes.isByteSource(input)) {
-    // Re-view through the byte guard first so any byte source (a Buffer, a Uint8Array or other typed array, a
-    // DataView, or a raw ArrayBuffer -- a caller-injected transport may return any of these) is normalized to a
-    // usable view, and a detached backing ArrayBuffer (a transferred / structuredClone'd view, which reads as
-    // zero-length) fails closed here instead of being decoded as an empty string. Then cap, then decode.
     input = bytes.source(input, ErrorClass, spec.badInput, spec.label);
-    // Measured through the byte guard's captured intrinsic getter, never `input.length`. On a typed
-    // array `length` is an accessor on the prototype and it is configurable, so a replacement
-    // returning 0 lets a buffer of any size past the cap and straight into the decode -- the
-    // allocation this guard exists to bound, defeated by the one read that bounds it.
     if (bytes.lengthOf(input) > maxBytes) throw new ErrorClass(spec.tooLarge, spec.label + " exceeds the size cap");
     if (spec.fatal) {
       try { return _decode(new _TextDecoder(charset, { fatal: true }), input); }
@@ -89,8 +30,6 @@ function decode(input, maxBytes, ErrorClass, spec) {
     return _toString(input, charset);
   }
   if (typeof input === "string") {
-    // A latin1 string's char length equals its byte length; a UTF-8 string's
-    // does not, so bound the encoded byte length.
     var byteLen = charset === LATIN1 ? input.length : _byteLength(input, "utf8");
     if (byteLen > maxBytes) throw new ErrorClass(spec.tooLarge, spec.label + " exceeds the size cap");
     return input;
@@ -98,6 +37,4 @@ function decode(input, maxBytes, ErrorClass, spec) {
   throw new ErrorClass(spec.badInput, spec.label + " expects a string or a byte source (Buffer / TypedArray / DataView / ArrayBuffer)");
 }
 
-// Frozen for the reason the family header gives: a boundary reads its guard off this object at the
-// call, so a writable export would let a caller replace the check rather than pass it.
 module.exports = intrinsic.freeze({ decode: decode });

package/lib/guard-time.js

@@ -1,138 +1,42 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- no operator-facing namespace. The documented surface is the
-// verifiers whose validity / currency / temporal gates compose this guard
-// (pki.path.validate, pki.ocsp.verify, pki.tsp.*, pki.ct.*, pki.cms.sign).
-//
-// guard-time -- fail-closed Date-instant validation before a temporal comparison.
-//
-// Defends the NaN-Date fail-open class (CWE-20 improper input validation feeding
-// a silent security-gate bypass). An Invalid Date is still `instanceof Date`, and
-// every relational comparison against its NaN getTime() (NaN < x, NaN >= x) is
-// false, so a validity / not-before / not-after / currency window built on an
-// unvalidated Date silently accepts when it should reject. The class recurred at
-// three independent boundaries (TSP genTime, OCSP producedAt/thisUpdate, CT
-// temporal-interval) before it was centralized here; the sibling
-// nan-date-comparison-unguarded codebase-patterns detector flags any lib function
-// that re-inlines a `.getTime()` comparison without first rejecting a NaN, so a
-// new boundary is routed to this guard instead of re-growing the bug.
-//
-// Tier split: `value instanceof Date` with a NaN time is malformed caller input
-// (a config-time or entry-point Date, such as an operator-supplied distrustAfter
-// or a caller `opts.time`), so assertValid throws the caller's typed error instead
-// of returning a silent default. within() is the fail-closed window primitive: it
-// THROWS on a malformed operand but RETURNS a boolean for in/out-of-window, so the
-// OCSP / CRL currency callers that treat out-of-window as a `continue` skip keep
-// their control flow while a NaN operand can never slip through as a false.
+// @internal
 
-// The slot predicates and the NaN test, snapshotted at load. `util.types` is an ordinary object,
-// so a later `util.types.isDate = () => true` would otherwise decide what this guard calls a Date;
-// the global `isNaN` is writable, and one returning false makes an invalid Date pass the check
-// below, which is the fail-open direction.
 var util = { types: require("./guard-intrinsic").types };
 var _freeze = require("./guard-intrinsic").freeze;
 var _isNaN = Number.isNaN;
 
-// assertValid(value, E, code, label) -> the same Date, once proven valid.
-//   value : a Date (or an alleged one) from a caller boundary.
-//   E     : the (code, message[, cause]) typed-error FACTORY in scope at the call
-//           site (ns.E / the module-local _err), never a defineClass class, which
-//           would crash `class cannot be invoked without new` on the error path.
-//   code  : the frozen domain/reason code this boundary rejects malformed time under.
-//   label : field phrase for the message.
-// The instant a Date holds, asked of the language rather than of the Date.
-//
-// `getTime` is an ordinary method on `Date.prototype`, so `class T extends Date { getTime() {} }`
-// and an own `getTime` on any instance both answer it. Reading it off the value let a caller throw
-// a raw exception out of a guard whose contract is a typed error, and let one return a fabricated
-// instant that passed the check while the real one did not. It also made the read repeatable: a
-// method asked twice may answer twice, so a window check could validate one instant and compare
-// another.
-//
-// The intrinsic is called against the value, which reaches the internal slot whatever the value's
-// own class says, and refuses a receiver with no slot behind it.
-//
-// The capture is of whatever `Date.prototype.getTime` holds when this module first loads, so it
-// is the language's own function only if nothing replaced it earlier in the process. Code that
-// runs before this module is inside the trust boundary already and can reach further than this
-// one method, so there is no defense here to add; what the capture buys is immunity to every
-// replacement that happens afterwards, which is the case a caller's argument can reach.
-//
-// The capture is uncurried through guard-intrinsic, so `instantOf` reads no property of it either.
-// The captured function is still the one on `Date.prototype`, and an own `call` assigned to it
-// would shadow `Function.prototype.call` and decide every instant this toolkit evaluates against.
 var _dateGetTime = require("./guard-intrinsic").uncurry(Date.prototype.getTime);
 
-// instantOf(value) -> the epoch milliseconds a Date holds, read through the intrinsic.
-//
-// The shape is the method call itself, wherever it appears. There is no boundary at which reading
-// `getTime` off a value is the safe spelling: a caller's Date reaches the read through an override,
-// and this toolkit's own Date reaches it through whatever `Date.prototype.getTime` has been made
-// to be, which a dependency loaded before this module gets to decide. So the rule is that lib/
-// calls no `getTime` at all, and the one capture above is where it lives.
-//
 // @enforced-by guard-shape-reinlined
 // @guard-shape \.getTime\s*\(
 function instantOf(value) { return _dateGetTime(value); }
 
 // @enforced-by nan-date-comparison-unguarded
 function assertValid(value, E, code, label) {
-  // The slot, never the prototype. `instanceof Date` asks what a value inherits from, and
-  // `Object.create(Date.prototype)` inherits everything while holding no instant, so it passes
-  // that test and `getTime()` then throws a raw TypeError out of this guard. `util.types.isDate`
-  // reads the internal slot, which a caller cannot fake and which answers the same across realms.
   if (!util.types.isDate(value) || _isNaN(instantOf(value))) {
     throw E(code, (label || "value") + " must be a valid Date");
   }
   return value;
 }
 
-// within(instant, lower, upper, E, code, label, opts) -> boolean (instant in window).
-//   Rejects a malformed instant / lower / upper by THROWING (assertValid), then
-//   answers containment as a boolean. Half-open [lower, upper) by default (a CT
-//   temporal-interval / an OCSP-CRL currency window); pass opts.upperInclusive for
-//   the closed [notBefore, notAfter] certificate-validity shape.
 // @enforced-by nan-date-comparison-unguarded
 function within(instant, lower, upper, E, code, label, opts) {
-  // assertValid rejects a non-Date / Invalid Date operand up front, so t/lo/hi below are
-  // guaranteed non-NaN -- the containment comparisons can never be a silent NaN-false. The
-  // getTime() results are bound to locals (not compared inline), so this home carries no
-  // unguarded `.getTime()`-in-a-comparison shape for the nan-date-comparison-unguarded detector.
   assertValid(instant, E, code, label);
   assertValid(lower, E, code, (label || "window") + " lower bound");
   assertValid(upper, E, code, (label || "window") + " upper bound");
-  // Read through the intrinsic, so the instants compared here are the ones assertValid just
-  // proved. A caller's `getTime` override answers each call afresh, which made the value checked
-  // and the value compared two different reads of the same argument.
   var t = instantOf(instant);
   var lo = instantOf(lower);
   var hi = instantOf(upper);
   return t >= lo && (opts && opts.upperInclusive ? t <= hi : t < hi);
 }
 
-// isDate(value) -> boolean: does this value actually hold an instant?
-//
-// The predicate half of assertValid, for the boundaries that choose a default rather than refuse
-// (`opts.genTime instanceof Date ? opts.genTime : new Date()`). `instanceof` asks what a value
-// inherits from, so `Object.create(Date.prototype)` passes it while holding no instant, and the
-// `.getTime()` that follows throws a raw TypeError out of a verb whose contract is a typed error.
-// A caller who supplied one and got the default instead would be worse served still: the value
-// they passed would have been silently replaced. This reads the slot, which cannot be faked and
-// answers the same for a Date built in another realm.
-//
-// An Invalid Date has the slot and a NaN instant, so this says yes to one. A boundary that
-// compares instants wants assertValid, which rejects both shapes.
 // @enforced-by behavioral -- a prototype test in place of a slot test has no rename-proof code
-// shape; the RED vectors (a slot-less Date lookalike at cms.verify / cms.sign / tsp.sign) are
-// the guard.
 function isDate(value) {
   return util.types.isDate(value);
 }
 
-// Frozen for the reason the family header gives: a boundary reads its guard off this object at the
-// call, so a writable export would let a caller replace the check rather than pass it.
 module.exports = _freeze({
   assertValid: assertValid,
   instantOf: instantOf,