@blamejs/pki 0.6.14 → 0.6.16

package/lib/tls-cert-compress.js

@@ -53,8 +53,6 @@
 var C = require("./constants");
 var guard = require("./guard-all");
 var intrinsic = require("./guard-intrinsic");
-// Own-key membership through an operation taken at load. Written out, the question reads two
-// replaceable properties to answer one thing, and here it decides which algorithms are supported.
 var _hasOwn = intrinsic.hasOwn;
 var frameworkError = require("./framework-error");
 var validator = require("./validator-all");
@@ -64,55 +62,29 @@ var zlib = require("zlib");
 var TlsError = frameworkError.TlsError;
 function _err(code, message, cause) { return new TlsError(code, message, cause); }
 
-// RFC 8879 sec. 7.3 -- the CertificateCompressionAlgorithm registry. The wire value is
-// what travels; the name is what this toolkit's guard dispatches on. 0 is Reserved and
-// 16384..65535 are Experimental Use, but neither needs a row: anything absent here is
-// refused the same way, and adding a row for a value we cannot decompress would be the
-// fail-open. Every name here is checked against the decompression guard at load, so a
-// runtime without one of the three cannot advertise it.
 var ALG_BY_NUMBER = { 1: "zlib", 2: "brotli", 3: "zstd" };
 var ALG_BY_NAME = {};
 Object.keys(ALG_BY_NUMBER).forEach(function (n) { ALG_BY_NAME[ALG_BY_NUMBER[n]] = Number(n); });
 
-// The compressors, paired with the guard's decompressors. RFC 8879 sec. 4 binds each
-// algorithm to its format: zlib -> RFC 1950, brotli -> RFC 7932, zstd -> RFC 8478.
 var COMPRESS = { zlib: zlib.deflateSync, brotli: zlib.brotliCompressSync, zstd: zlib.zstdCompressSync };
 
-// Each codec takes its compression level through a DIFFERENT option: zlib as a top-level
-// `level`, brotli and zstd as numbered entries in `params`. Passing `{ level: n }` to the
-// latter two is silently ignored by node, so a caller asking for a level would quietly get the
-// default. Each is mapped to the option its codec actually reads.
 var LEVEL_OPT = {
   zlib: function (n) { return { level: n }; },
   brotli: function (n) { var p = {}; p[zlib.constants.BROTLI_PARAM_QUALITY] = n; return { params: p }; },
   zstd: function (n) { var p = {}; p[zlib.constants.ZSTD_c_compressionLevel] = n; return { params: p }; },
 };
 
-// The names that are both registered by RFC 8879 and reachable through the decompression
-// guard on this runtime. An algorithm the guard cannot decompress must never be offered
-// or accepted: advertising one would mean accepting a message we then cannot open.
 var SUPPORTED = guard.compress.algorithms().filter(function (n) {
   return _hasOwn(ALG_BY_NAME, n) && typeof COMPRESS[n] === "function";
 });
 
-// The minimum Certificate message size and the widest opaque<..2^24-1> vector, both owned
-// by validator-tls, alongside the rest of the framing rule set. A declared
-// uncompressed_length below the minimum cannot be a Certificate message, and refusing it
-// also keeps a zero-length declaration away from the decompression cap, which is a positive
-// integer by contract.
 var MIN_CERT_MSG_BYTES = validator.tls.MIN_CERT_MSG_BYTES;
 var MAX_VECTOR_24 = validator.tls.MAX_VECTOR_24;
 
-// The fault codes validator-tls raises for each framing violation it owns.
 var FRAMING_CODES = { truncated: "tls/truncated", framing: "tls/bad-framing", trailing: "tls/trailing-data" };
 
-// The fixed part of a CompressedCertificate: uint16 algorithm + uint24 uncompressed_length +
-// the uint24 length prefix of the compressed body (RFC 8879 sec. 4).
 var HEADER_BYTES = 8;
 
-// Resolve the caller's policy cap, which may only tighten the protocol ceiling DOWNWARD.
-// A cap that could be raised would let an option undo the framing limit RFC 8879 sec. 5
-// requires be applied "as if no compression were used".
 function _resolveCap(opts) {
   var cap = C.LIMITS.TLS_CERT_MSG_MAX_BYTES;
   if (opts.maxOutputBytes !== undefined) {
@@ -125,10 +97,6 @@ function _resolveCap(opts) {
   return cap;
 }
 
-// The algorithm names the caller will accept, defaulting to everything supported. This is
-// the peer's `compress_certificate` advertisement: RFC 8879 sec. 4 requires the algorithm
-// to be one the receiver offered, so accepting an unadvertised one would decompress bytes
-// under a codec we never agreed to.
 function _resolveAllowed(opts) {
   if (opts.allowedAlgorithms === undefined) return SUPPORTED.slice();
   var list = opts.allowedAlgorithms;
@@ -200,8 +168,6 @@ function _resolveAllowed(opts) {
 function decompressCertificate(bytes, opts) {
   opts = opts || {};
   var view = guard.bytes.view(bytes, TlsError, "tls/bad-input", "the compressed certificate message");
-  // The CompressedCertificate travels as a handshake message body, framed by RFC 8446 sec. 4
-  // with a uint24 length, so one longer than that ceiling could not have been sent at all.
   if (view.length > C.LIMITS.TLS_CERT_MSG_MAX_BYTES) {
     throw _err("tls/too-large", "the compressed certificate message is " + view.length +
       " bytes, over the " + C.LIMITS.TLS_CERT_MSG_MAX_BYTES + "-byte handshake framing limit");
@@ -209,20 +175,12 @@ function decompressCertificate(bytes, opts) {
   var cap = _resolveCap(opts);
   var allowed = _resolveAllowed(opts);
 
-  // Framing decode + bounds live in validator-tls (the type's rule set); which algorithms
-  // are acceptable, the output cap, and the length agreement are this codec's policy and
-  // stay here. Note the currency split the two families use: the validator takes the error
-  // CLASS, the guard below takes the `_err` FACTORY.
   var framed = validator.tls.compressedCertificate(view, TlsError, FRAMING_CODES);
   var algorithm = framed.algorithm;
   var name = ALG_BY_NUMBER[algorithm];
   if (!name) {
     throw _err("tls/unsupported-algorithm", "compression algorithm " + algorithm + " is not in the RFC 8879 registry");
   }
-  // SUPPORTED is the RFC 8879 registry intersected with what the decompression guard can
-  // actually open safely, so this fires wherever one of the three is dropped -- which is the
-  // long-term-support Node, where zstd cannot report a truncated frame. Covered there by the
-  // dropped-algorithm vector; unreachable on a runtime where all three qualify.
   if (SUPPORTED.indexOf(name) === -1) {
     throw _err("tls/unsupported-algorithm", "compression algorithm " + algorithm + " (" + name + ") is not decompressible on this runtime");
   }
@@ -238,12 +196,8 @@ function decompressCertificate(bytes, opts) {
   if (uncompressedLength > cap) {
     throw _err("tls/too-large", "uncompressed_length " + uncompressedLength + " exceeds the " + cap + "-byte limit");
   }
-  // The declared length IS the cap: a stream that expands past what the message itself
-  // claims is refused mid-decompression rather than after the memory is committed.
   var message = guard.compress.bounded(name, Buffer.from(body), uncompressedLength, _err,
     { tooLarge: "tls/too-large", failed: "tls/decompress-failed" }, "the compressed certificate message");
-  // RFC 8879 sec. 5: if the length after decompression does not match the declared one,
-  // the message is invalid. The cap above only bounds the OVER direction.
   if (message.length !== uncompressedLength) {
     throw _err("tls/length-mismatch", "the decompressed message is " + message.length +
       " bytes but uncompressed_length declared " + uncompressedLength);
@@ -305,10 +259,6 @@ function parseCertificateMessage(bytes, opts) {
     throw _err("tls/bad-input", "opts.certificateType must be \"X509\" or \"RawPublicKey\"");
   }
   var view = guard.bytes.view(bytes, TlsError, "tls/bad-input", "the certificate message");
-  // A Certificate message is a handshake message body, framed by RFC 8446 sec. 4 with a uint24
-  // length, so one longer than that ceiling could not have appeared on the wire. This entry point
-  // is public and reachable without going through decompression, so it applies the bound itself
-  // rather than inheriting the one the compression paths enforce.
   if (view.length > C.LIMITS.TLS_CERT_MSG_MAX_BYTES) {
     throw _err("tls/too-large", "the certificate message is " + view.length +
       " bytes, over the " + C.LIMITS.TLS_CERT_MSG_MAX_BYTES + "-byte handshake framing limit");
@@ -379,11 +329,6 @@ function compressCertificate(certificateMessage, opts) {
   } catch (e) {
     throw _err("tls/bad-input", "the certificate message could not be compressed (check opts.level)", e);
   }
-  // The CompressedCertificate is itself a handshake message body, so the WHOLE emitted message --
-  // not just the message it carries -- must fit the RFC 8446 sec. 4 uint24 framing. Incompressible
-  // content near the ceiling grows by the 8-byte header, so bounding only the input would emit a
-  // message that cannot be framed and no peer could receive. Checked BEFORE the writer so this
-  // stays one verdict rather than surfacing as the body vector's own bound.
   var wireLength = HEADER_BYTES + stream.length;
   if (wireLength > C.LIMITS.TLS_CERT_MSG_MAX_BYTES) {
     throw _err("tls/too-large", "the compressed certificate message would be " + wireLength +
@@ -394,14 +339,7 @@ function compressCertificate(certificateMessage, opts) {
   w.u24(view.length);
   w.vector(3, 1, MAX_VECTOR_24, stream, "tls/bad-framing");
   var wire = w.build();
-  // Self-check: a produced message must be one this decoder accepts, and must recover the
-  // input byte-for-byte. This is what stops a codec-level defect from shipping a message
-  // that only a permissive peer can read.
   var back = decompressCertificate(wire, { allowedAlgorithms: [name] });
-  // Coverage residual -- unreachable while the codec is correct, which is the point: this
-  // fires only if a compressor and its decompressor disagree, and there is no input that
-  // makes them. It stays as the assertion that a message this toolkit emits is one this
-  // toolkit accepts, so a future codec defect surfaces here rather than at a peer.
   if (!back.certificateMessage.equals(view)) {
     throw _err("tls/bad-input", "the compressed certificate message did not round-trip to the input");
   }