@blamejs/pki 0.6.14 → 0.6.15

package/lib/attrcert-verify.js

@@ -1,19 +1,13 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- the RFC 5755 attribute-certificate signature seam, shared by pki.attrcert.verify and
-// by any path that accepts an inbound AC. The slot, the wiring assertion and the octet-alignment
-// refusal are the shared seam (lib/verify-seam.js); what is domain-specific is the error class and
-// the byte range the signature covers. It is not wired into index.js and is reached only by require.
+// @internal
 
 var frameworkError = require("./framework-error");
 var seam = require("./verify-seam");
 
 var _seam = seam.makeSeam("attrcert-verify", frameworkError.AttrCertError, "attrcert/bad-input");
 
-// Verify a parsed attribute certificate's signature over its exact AttributeCertificateInfo bytes
-// under the AC issuer's SubjectPublicKeyInfo DER (RFC 5755 sec. 5, item 2).
 function verifyAcSignature(ac, spkiBytes) {
   return _seam.verify(ac.signatureAlgorithm, ac.signatureValue, spkiBytes, ac.tbsBytes);
 }

package/lib/byte-reader.js

@@ -17,9 +17,6 @@
  * offset walk in a format module.
  */
 
-// A bounded cursor over `buf[start, end)`, faulting through the caller's ErrorClass
-// `E` (constructed `new E(code, message)`). `defaultCode` is the fault code used
-// when a read is not given its own.
 function ByteReader(buf, start, end, E, defaultCode) {
   if (!Buffer.isBuffer(buf)) throw new TypeError("ByteReader: buf must be a Buffer");
   this.buf = buf;
@@ -42,14 +39,10 @@ ByteReader.prototype.u24 = function (code) {
 };
 ByteReader.prototype.u32 = function (code) { this._need(4, code); var v = this.buf.readUInt32BE(this.pos); this.pos += 4; return v; };
 ByteReader.prototype.u64 = function (code) { this._need(8, code); var v = this.buf.readBigUInt64BE(this.pos); this.pos += 8; return v; };
-// A fixed-width opaque slice (zero-copy view into the backing buffer).
 ByteReader.prototype.fixed = function (n, code) {
   this._need(n, code);
   var s = this.buf.subarray(this.pos, this.pos + n); this.pos += n; return s;
 };
-// opaque<min..max> is a length-prefixed vector (lenWidth-byte big-endian prefix:
-// 2 or 3). The length prefix itself is a plain read (a truncation there is the
-// default code); only a lying length whose body overruns the bound carries `code`.
 ByteReader.prototype.vector = function (lenWidth, min, max, code) {
   var len = lenWidth === 3 ? this.u24() : this.u16();
   if (len < min) throw new this.E(code, "vector length " + len + " below minimum " + min);
@@ -57,7 +50,6 @@ ByteReader.prototype.vector = function (lenWidth, min, max, code) {
   this._need(len, code);
   var s = this.buf.subarray(this.pos, this.pos + len); this.pos += len; return s;
 };
-// A bounded child cursor over the next `len` bytes, sharing the same ErrorClass.
 ByteReader.prototype.subReader = function (len, code) {
   this._need(len, code);
   var r = new ByteReader(this.buf, this.pos, this.pos + len, this.E, this.defaultCode); this.pos += len; return r;

package/lib/byte-writer.js

@@ -18,9 +18,6 @@
  * in a format module.
  */
 
-// A growable big-endian sink, faulting through the caller's ErrorClass `E`
-// (constructed `new E(code, message)`). `defaultCode` is the fault code used when a
-// write is not given its own.
 function ByteWriter(E, defaultCode) {
   this.parts = [];
   this.len = 0;
@@ -28,9 +25,6 @@ function ByteWriter(E, defaultCode) {
   this.defaultCode = defaultCode || "byte-writer/bad-value";
 }
 ByteWriter.prototype._push = function (buf) { this.parts.push(buf); this.len += buf.length; };
-// A non-negative integer that fills exactly `width` big-endian octets; the width MUST be 1..4 (a wider
-// or malformed width would break the max computation via 32-bit shift wrap-around and mis-size the
-// field), and a value outside [0, 2^(8*width)-1] (or a non-integer) faults instead of silently wrapping.
 ByteWriter.prototype._uint = function (v, width, code) {
   if (!Number.isInteger(width) || width < 1 || width > 4) throw new this.E(code || this.defaultCode, "an integer width must be 1..4, got " + width);
   var max = width === 4 ? 0xffffffff : (1 << (8 * width)) - 1;
@@ -43,7 +37,6 @@ ByteWriter.prototype.u8 = function (v, code) { this._uint(v, 1, code); return th
 ByteWriter.prototype.u16 = function (v, code) { this._uint(v, 2, code); return this; };
 ByteWriter.prototype.u24 = function (v, code) { this._uint(v, 3, code); return this; };
 ByteWriter.prototype.u32 = function (v, code) { this._uint(v, 4, code); return this; };
-// A uint64 from a BigInt or a safe-integer Number; refused if out of [0, 2^64-1].
 ByteWriter.prototype.u64 = function (v, code) {
   var big;
   if (typeof v === "bigint") big = v;
@@ -53,14 +46,10 @@ ByteWriter.prototype.u64 = function (v, code) {
   var b = Buffer.alloc(8); b.writeBigUInt64BE(big); this._push(b);
   return this;
 };
-// Append a raw opaque slice verbatim (a fixed-width field).
 ByteWriter.prototype.bytes = function (buf, code) {
   if (!Buffer.isBuffer(buf)) throw new this.E(code || this.defaultCode, "bytes() requires a Buffer");
   this._push(buf); return this;
 };
-// opaque<min..max> -- a `lenWidth`-byte big-endian length prefix (1..4) then `body`.
-// The body length is bounded [min, max] before the prefix is written, so an over-long
-// body cannot emit a prefix that disagrees with what follows.
 ByteWriter.prototype.vector = function (lenWidth, min, max, body, code) {
   if (!Buffer.isBuffer(body)) throw new this.E(code || this.defaultCode, "vector() body must be a Buffer");
   if (body.length < min) throw new this.E(code || this.defaultCode, "vector body " + body.length + " below minimum " + min);

package/lib/cbor-det.js

@@ -43,30 +43,17 @@ var guard = require("./guard-all");
 
 var CborError = frameworkError.CborError;
 
-// Reusable little-work scratch for IEEE-754 float decode + the shortest-form
-// round-trip checks. Single-threaded synchronous use, reset on every write.
 var _fbuf = new ArrayBuffer(8);
 var _fdv = new DataView(_fbuf);
 
-// Strict UTF-8 validator (fatal); a lone continuation / truncated sequence
-// throws instead of substituting U+FFFD, which is the fail-open class the
-// toolkit refuses. This mirrors asn1-der's strict text decode.
 var _utf8 = new TextDecoder("utf-8", { fatal: true });
 
-// The ECMAScript Date-valid window is +/- 8,640,000,000,000,000 ms; in seconds
-// that is +/- 8.64e12. read.time bounds an epoch value to this window before
-// narrowing the BigInt to a Number, so the narrowing is lossless (well under
-// 2^53) and the millisecond result stays a safe integer.
 var _MAX_EPOCH_SECONDS = 8640000000000n;
 
 function _asBuffer(input, who) {
   return guard.bytes.view(input, CborError, "cbor/not-buffer", who);
 }
 
-// Determinism profile -> a ruleset. v1 whitelists only "deterministic"
-// (RFC 8949 sec. 4.2 core); an unknown profile is a config-time TypeError, so
-// there is no path to a lenient decode. A future "ctap2" (length-first map
-// ordering) is a data row here, not a switch through the decoder.
 function _profile(name) {
   var p = name === undefined ? "deterministic" : name;
   if (p === "deterministic") return { mapKeyCompare: Buffer.compare };
@@ -81,28 +68,21 @@ function _assertUtf8(buf) {
   }
 }
 
-// Decode the raw IEEE-754 bits (carried in the argument) to a JS double, per
-// the additional-info width: 25 half, 26 single, 27 double.
 function _readFloatBits(argument, ai) {
   if (ai === 25) { _fdv.setUint16(0, Number(argument)); return _fdv.getFloat16(0); }
   if (ai === 26) { _fdv.setUint32(0, Number(argument)); return _fdv.getFloat32(0); }
   _fdv.setBigUint64(0, argument); return _fdv.getFloat64(0);
 }
 
-// Is d exactly representable as a half float? (round-trip through float16;
-// Object.is keeps -0 and the NaN/Inf cases honest).
 function _halfRoundtrips(d) {
   _fdv.setFloat16(0, d);
   return Object.is(_fdv.getFloat16(0), d);
 }
 
-// Is d exactly representable as a single float?
 function _singleRoundtrips(d) {
   return Object.is(Math.fround(d), d);
 }
 
-// Recursive-descent decode of one CBOR item over [start, limit): fail-closed,
-// depth-budgeted, zero-copy. Mirrors asn1-der's _decodeTLV.
 function _decodeItem(buf, start, limit, depth, maxD, rules, state) {
   if (depth > maxD) throw new CborError("cbor/too-deep", "nesting exceeds depth cap " + maxD);
   state.n += 1;
@@ -113,7 +93,6 @@ function _decodeItem(buf, start, limit, depth, maxD, rules, state) {
   var mt = ib >> 5;
   var ai = ib & 0x1f;
 
-  // Head well-formedness, before reading the argument.
   if (ib === 0xff) throw new CborError("cbor/unexpected-break", "stray break byte (0xff) at an item head");
   if (ai === 28 || ai === 29 || ai === 30) throw new CborError("cbor/reserved-ai", "reserved additional-info " + ai);
   if (ai === 31) {
@@ -123,7 +102,6 @@ function _decodeItem(buf, start, limit, depth, maxD, rules, state) {
     throw new CborError("cbor/reserved-ai", "additional-info 31 is undefined for major type " + mt);
   }
 
-  // The argument, minimal-checked, as a lossless BigInt.
   var argument;
   var contentStart;
   if (ai <= 23) {
@@ -137,9 +115,6 @@ function _decodeItem(buf, start, limit, depth, maxD, rules, state) {
     else if (nBytes === 4) argument = BigInt(buf.readUInt32BE(p));
     else argument = buf.readBigUInt64BE(p);
     p += nBytes;
-    // Preferred (shortest) argument, required for every major type but 7. In
-    // type 7 the "argument" is raw float bits, governed by the shortest-float
-    // rule.
     if (mt !== 7) {
       var minForWidth = nBytes === 1 ? 24n : nBytes === 2 ? 256n : nBytes === 4 ? 65536n : 4294967296n;
       if (argument < minForWidth) {
@@ -191,7 +166,6 @@ function _decodeItem(buf, start, limit, depth, maxD, rules, state) {
     children = [inner.node];
     end = inner.end;
   } else {
-    // mt === 7: simple value or float.
     if (ai <= 23) {
       end = contentStart;
     } else if (ai === 24) {
@@ -281,7 +255,6 @@ function _expectMajor(node, mt, who) {
   }
 }
 
-// Assert a tag node with a specific tag number, and return its one inner item.
 function _tagInner(node, tagNum, who) {
   if (!node || node.majorType !== 6 || node.argument !== BigInt(tagNum)) {
     throw new CborError("cbor/unexpected-tag", who + ": expected tag " + tagNum);
@@ -615,8 +588,6 @@ function readTime(node) {
   }
   var ns = Number(secs);
   var d = new Date(ns < 0 ? -constants.TIME.seconds(-ns) : constants.TIME.seconds(ns));
-  // Coverage residual -- the epoch-window bound above already rejects any value the
-  // Date constructor cannot represent, so this backstop is defense-in-depth.
   if (isNaN(guard.time.instantOf(d))) throw new CborError("cbor/bad-time", "epoch time out of range");
   return d;
 }
@@ -644,33 +615,18 @@ function readOid(node) {
   return asn1.decodeOidContent(inner.content);
 }
 
-// ---- deterministic-CBOR encoder (RFC 8949 sec. 4.2) -- the byte-exact inverse of decode ----
-// Every emitted head is the shortest form (the exact mirror of decode's cbor/non-minimal-argument reject),
-// every length is definite, and map keys are sorted bytewise + unique -- so decode(build.x(...)) round-trips
-// or the builder produced a shape its own strict decoder rejects. Nested items are pre-encoded CBOR item
-// Buffers (the asn1.build pattern); the CBOR-encoded PKI surfaces (C509, COSE) compose these leaves.
 function _cbItem(x, who) {
   if (!Buffer.isBuffer(x)) throw new CborError("cbor/not-buffer", who + ": expected a pre-encoded CBOR item Buffer");
   return x;
 }
-// Validate an assembled container decodes: well-formed nested items (no malformed head, indefinite length,
-// stray break, or trailing bytes), AND within the decoder's depth cap -- a container adds ONE nesting
-// level, so a child AT the cap would overflow the output. Decoding the whole output in one pass catches
-// both, so the encoder never produces bytes its own strict decoder rejects.
 function _assertDecodes(out, who) {
   try { decode(out); } catch (e) { throw new CborError("cbor/bad-item", who + ": produced bytes the strict decoder rejects (" + (e && e.code) + ")", e); }
   return out;
 }
-// Mirror the decoder's total-size cap (constants.LIMITS.CBOR_MAX_BYTES) so a string leaf never emits an
-// item the strict reader would reject as too large -- the encode/decode round trip stays closed under the
-// default limits.
 function _capString(out, who) {
   if (out.length > constants.LIMITS.CBOR_MAX_BYTES) throw new CborError("cbor/too-large", who + ": encoded " + out.length + " bytes exceeds cap " + constants.LIMITS.CBOR_MAX_BYTES);
   return out;
 }
-// Reject a JS string carrying an unpaired UTF-16 surrogate: Buffer.from(..., "utf8") would silently
-// substitute U+FFFD, so the emitted text string would not be the input (and read.text enforces well-formed
-// UTF-8). Fail closed to match the decoder rather than corrupt the text.
 function _assertWellFormedText(str, who) {
   for (var i = 0; i < str.length; i++) {
     var c = str.charCodeAt(i);
@@ -678,7 +634,6 @@ function _assertWellFormedText(str, who) {
     else if (c >= 0xdc00 && c <= 0xdfff) throw new CborError("cbor/bad-utf8", who + ": the string has an unpaired low surrogate");
   }
 }
-// The initial byte + minimal-width argument for major type `mt` and unsigned `argument`.
 function _head(mt, argument, who) {
   var a = typeof argument === "bigint" ? argument : BigInt(argument);
   if (a < 0n) throw new CborError("cbor/bad-argument", who + ": a CBOR head argument must be non-negative");
@@ -704,10 +659,6 @@ var build = {
   map: function (pairs) {
     if (!Array.isArray(pairs)) throw new CborError("cbor/bad-argument", "build.map: expected an array of [key, value] pairs");
     var enc = pairs.map(function (p, i) { if (!Array.isArray(p) || p.length !== 2) throw new CborError("cbor/bad-argument", "build.map[" + i + "]: each entry is a [key, value] pair"); return [_cbItem(p[0], "build.map key"), _cbItem(p[1], "build.map value")]; });
-    // RFC 8949 sec. 4.2.1 Core Deterministic: keys sorted in the BYTEWISE lexicographic order of their
-    // encodings -- NOT the length-first order of sec. 4.2.3 (the older RFC 7049 "Canonical CBOR" variant).
-    // This MUST match the decoder, which enforces bytewise order (_profile "deterministic" -> Buffer.compare
-    // at :70); a length-first sort here would emit a map the strict decoder then rejects as unsorted.
     enc.sort(function (a, b) { return Buffer.compare(a[0], b[0]); });
     for (var i = 1; i < enc.length; i++) { if (Buffer.compare(enc[i - 1][0], enc[i][0]) === 0) throw new CborError("cbor/duplicate-map-key", "build.map: duplicate map key"); }
     var flat = [_head(5, pairs.length, "build.map")];
@@ -718,14 +669,12 @@ var build = {
   boolean: function (v) { return Buffer.from([v ? 0xf5 : 0xf4]); },
   nullValue: function () { return Buffer.from([0xf6]); },
   raw: function (buf) { return _assertDecodes(_asBuffer(buf, "build.raw"), "build.raw"); },
-  // Tagged leaves -- the inverse of read.biguint / read.time / read.oid.
   biguint: function (n) {
     var a = typeof n === "bigint" ? n : BigInt(n);
     if (a < 0n) throw new CborError("cbor/bad-argument", "build.biguint: value must be non-negative");
     var hex = a.toString(16); if (hex.length % 2) hex = "0" + hex;
     var mag = a === 0n ? Buffer.alloc(0) : Buffer.from(hex, "hex");
     if (mag.length <= 8) throw new CborError("cbor/bad-argument", "build.biguint: a value that fits 8 bytes must use build.uint (RFC 8949 preferred serialization)");
-    // Mirror read.biguint's cap so the tagged bignum builder never emits a value the strict reader rejects.
     if (mag.length > constants.LIMITS.CBOR_MAX_BIGUINT_BYTES) throw new CborError("cbor/biguint-too-large", "build.biguint: " + mag.length + " bytes exceeds cap " + constants.LIMITS.CBOR_MAX_BIGUINT_BYTES);
     return build.tag(2, build.byteString(mag));
   },
@@ -734,12 +683,9 @@ var build = {
     if (guard.time.isDate(v)) {
       ms = guard.time.instantOf(v);
       if (Number.isNaN(ms)) throw new CborError("cbor/bad-time", "build.time: an Invalid Date has no epoch value");
-      // read.time reads only an integer (second-granularity) tag-1, so a sub-second Date cannot round-trip:
-      // reject it rather than silently truncate the milliseconds.
       if (ms % 1000 !== 0) throw new CborError("cbor/bad-time", "build.time: a Date with sub-second precision cannot be a second-granularity CBOR epoch; round to whole seconds");
     }
     var secs = guard.time.isDate(v) ? BigInt(Math.floor(ms / 1000)) : (typeof v === "bigint" ? v : BigInt(v));
-    // Mirror read.time's bound so build.time never emits a tag-1 the strict reader would reject as out of range.
     if (secs < -_MAX_EPOCH_SECONDS || secs > _MAX_EPOCH_SECONDS) throw new CborError("cbor/bad-time", "build.time: epoch seconds " + secs + " are outside the representable Date range");
     return build.tag(1, build.int(secs));
   },