@blamejs/pki 0.5.7 → 0.5.9

package/lib/attrcert-sign.js

@@ -10,14 +10,14 @@
  *   `AttributeCertificateInfo` binding a Holder to a set of privilege attributes (role, clearance,
  *   group, ...) over a validity window, signs it with an Attribute Authority's private key, and emits an
  *   `AttributeCertificate` that `pki.schema.attrcert.parse` accepts and re-validates byte for byte.
- *   Unlike a public-key certificate an attribute certificate is never self-signed -- the holder has no
+ *   Unlike a public-key certificate an attribute certificate is never self-signed: the holder has no
  *   key, so the issuing AA is always a distinct signer. Parsing lives at `pki.schema.attrcert.parse`.
  * @spec RFC 5755
  * @card Build and sign an RFC 5755 attribute certificate as an Attribute Authority.
  */
 //
-// RFC 5755 is DEFINITIONS IMPLICIT TAGS (App. B): a context [n] on a non-CHOICE component REPLACES the
-// underlying tag (its children ARE the component's fields -- Holder [0]/[1]/[2], AttCertIssuer v2Form [0],
+// RFC 5755 is DEFINITIONS IMPLICIT TAGS (App. B): a context [n] on a non-CHOICE component replaces the
+// underlying tag (its children are the component's fields: Holder [0]/[1]/[2], AttCertIssuer v2Form [0],
 // RoleSyntax roleAuthority [0], IetfAttrSyntax policyAuthority [0], AAControls [0]/[1]), built with
 // b.contextConstructed(n, ...); a context [n] wrapping a GeneralName CHOICE (roleName [1], Target [0]/[1])
 // is EXPLICIT, built with b.explicit(n, ...). The signature algorithm resolves from the AA public key
@@ -75,7 +75,7 @@ var EXT_META = {
 // hatch so an escape-hatch extension cannot ship with a criticality the profile forbids.
 var REQUIRED_CRITICALITY = {};
 Object.keys(EXT_META).forEach(function (k) { REQUIRED_CRITICALITY[O(EXT_META[k].name)] = EXT_META[k].critical; });
-// ClassList ::= BIT STRING { unmarked(0) .. topSecret(5) } (RFC 5755 sec. 4.4.4) -- the encode inverse of
+// ClassList ::= BIT STRING { unmarked(0) .. topSecret(5) } (RFC 5755 sec. 4.4.4), the encode inverse of
 // the schema-attrcert.js _CLASSLIST_NAMES decode array; DEFAULT {unclassified} (bit 1) is omitted.
 var CLASSLIST_BIT = { unmarked: 0, unclassified: 1, restricted: 2, confidential: 3, secret: 4, topSecret: 5 };
 
@@ -91,7 +91,7 @@ function _parseCert(cert, what) {
     catch (e) { if (e instanceof AttrCertError) throw e; throw _err("attrcert/bad-input", what + " is not a well-formed certificate", e); }
   }, _err, "attrcert/bad-input", what);
 }
-// The raw content octets of an OBJECT IDENTIFIER (past its own tag+len) -- the body of a [0] IMPLICIT OID.
+// The raw content octets of an OBJECT IDENTIFIER (past its own tag+len): the body of a [0] IMPLICIT OID.
 function _oidContent(name) {
   var dotted = O(name) || name;
   var enc;
@@ -107,7 +107,7 @@ function _gnList(spec) {
 // ---- structural encoders (byte-exact inverses of the schema-attrcert.js readers) ----
 
 // IssuerSerial ::= SEQUENCE { issuer GeneralNames, serial CertificateSerialNumber, issuerUID BIT STRING
-// OPTIONAL }. Returns the CONTENT (concatenated field TLVs) so a [n] IMPLICIT caller wraps it directly.
+// OPTIONAL }. Returns the content (concatenated field TLVs) so a [n] IMPLICIT caller wraps it directly.
 function _issuerSerialContent(is) {
   if (!is || typeof is !== "object" || Buffer.isBuffer(is)) throw _err("attrcert/bad-input", "baseCertificateID must be an object { issuer, serial, issuerUID? }");
   if (is.issuer == null) throw _err("attrcert/bad-input", "baseCertificateID.issuer (a GeneralNames) is required");
@@ -120,7 +120,7 @@ function _issuerSerialContent(is) {
 }
 // ObjectDigestInfo ::= SEQUENCE { digestedObjectType ENUMERATED, otherObjectTypeID OID OPTIONAL,
 // digestAlgorithm AlgorithmIdentifier, objectDigest BIT STRING }. otherObjectTypes(2) is forbidden (sec.
-// 7.3), so otherObjectTypeID is never emitted. Returns the CONTENT for a [n] IMPLICIT caller.
+// 7.3), so otherObjectTypeID is never emitted. Returns the content for a [n] IMPLICIT caller.
 var ODT_CODE = { publicKey: 0, publicKeyCert: 1 };
 function _objectDigestInfoContent(odi) {
   if (!odi || typeof odi !== "object" || Buffer.isBuffer(odi)) throw _err("attrcert/bad-input", "objectDigestInfo must be an object");
@@ -134,7 +134,7 @@ function _objectDigestInfoContent(odi) {
   return Buffer.concat([b.enumerated(BigInt(code)), algTlv, b.bitString(odi.objectDigest, 0)]);
 }
 // Holder ::= SEQUENCE { baseCertificateID [0] IMPLICIT IssuerSerial, entityName [1] IMPLICIT GeneralNames,
-// objectDigestInfo [2] IMPLICIT ObjectDigestInfo } -- exactly one form (the profile binds a real holder).
+// objectDigestInfo [2] IMPLICIT ObjectDigestInfo }, exactly one form (the profile binds a real holder).
 function _encodeHolder(holder) {
   if (!holder || typeof holder !== "object" || Buffer.isBuffer(holder)) throw _err("attrcert/bad-input", "holder must be an object with exactly one form");
   guard.identifier.assertKnownKeys(holder, KNOWN_HOLDER_KEYS, _err, "attrcert/bad-input", "unknown holder form ");
@@ -150,7 +150,7 @@ function _encodeHolder(holder) {
   if (holder.fromCertificate != null) {
     // Bind to a public-key certificate's identity: baseCertificateID = { issuer = the PKC's issuer DN as a
     // directoryName, serial = the PKC serialNumber } (RFC 5755 sec. 4.1 / 7.3).
-    // BOTH halves from the signed bytes. issuer and serial together ARE the identity, so deriving
+    // Both halves come from the signed bytes. issuer and serial together are the identity, so deriving
     // the issuer from tbsBytes while reading the serial off the object let the two name different
     // certificates: a Holder with a genuine issuer DN and whatever serial the caller wrote.
     var pkc = _parseCert(holder.fromCertificate, "holder.fromCertificate");
@@ -161,7 +161,7 @@ function _encodeHolder(holder) {
   return b.sequence([b.contextConstructed(2, _objectDigestInfoContent(holder.objectDigestInfo))]);
 }
 
-// AttCertIssuer v2Form [0] IMPLICIT V2Form { issuerName GeneralNames } -- issuerName is exactly one
+// AttCertIssuer v2Form [0] IMPLICIT V2Form { issuerName GeneralNames }, where issuerName is exactly one
 // directoryName [4] over a non-empty DN (RFC 5755 sec. 4.2.3). The [0] replaces the V2Form SEQUENCE tag.
 function _encodeV2FormIssuer(dnSpec) {
   var dnDer = _b.encodeName(dnSpec == null ? [] : dnSpec);
@@ -170,7 +170,7 @@ function _encodeV2FormIssuer(dnSpec) {
   return b.contextConstructed(0, issuerNameGns);
 }
 // AttCertValidityPeriod ::= SEQUENCE { notBeforeTime GeneralizedTime, notAfterTime GeneralizedTime }
-// (RFC 5755 sec. 4.2.6) -- ALWAYS GeneralizedTime, never UTCTime; reject an inverted window.
+// (RFC 5755 sec. 4.2.6): always GeneralizedTime, never UTCTime; reject an inverted window.
 function _encodeValidity(notBefore, notAfter) {
   guard.time.assertValid(notBefore, _err, "attrcert/bad-input", "notBeforeTime");
   guard.time.assertValid(notAfter, _err, "attrcert/bad-input", "notAfterTime");
@@ -263,7 +263,7 @@ var ATTR_VALUE_ENCODER = {
 // ---- extension-value encoders (sec. 4.3 / 7.4) ----
 
 // Target ::= CHOICE { targetName [0] EXPLICIT GeneralName, targetGroup [1] EXPLICIT GeneralName }
-// (targetCert [2] is out of v1 scope -- use a pre-encoded Extension DER for a targetCert-bearing value).
+// (targetCert [2] is out of v1 scope; use a pre-encoded Extension DER for a targetCert-bearing value).
 function _encodeTarget(t) {
   if (!t || typeof t !== "object") throw _err("attrcert/bad-input", "each target must be { targetName } or { targetGroup }");
   if (t.targetName != null) return b.explicit(0, _b.encodeGeneralName(t.targetName));
@@ -291,7 +291,7 @@ function _encodeAAControls(aac) {
   var parts = [];
   if (aac.pathLenConstraint != null) {
     // The parser narrows pathLenConstraint through guard.range.uint31 (0..2^31-1), so a larger value the
-    // builder emits would fail the round trip -- bound it to the same range at build time.
+    // builder emits would fail the round trip, so bound it to the same range at build time.
     if (typeof aac.pathLenConstraint !== "number" || !Number.isInteger(aac.pathLenConstraint) || aac.pathLenConstraint < 0 || aac.pathLenConstraint > 0x7fffffff) throw _err("attrcert/bad-input", "aaControls.pathLenConstraint must be an integer in 0..2147483647 (RFC 5755 sec. 7.4)");
     parts.push(b.integer(BigInt(aac.pathLenConstraint)));
   }
@@ -319,7 +319,7 @@ function _extensionValue(key, val, aaSpki) {
 
 // ---- attributes / extensions assembly ----
 
-// attributes ::= SEQUENCE OF Attribute (RFC 5755 sec. 4.2.7) -- non-empty, each AttributeType OID unique;
+// attributes ::= SEQUENCE OF Attribute (RFC 5755 sec. 4.2.7): non-empty, each AttributeType OID unique;
 // or an array of pre-encoded Attribute DER (validated in shape AND value). Each Attribute value SET is
 // DER-sorted.
 function _buildAttributes(attrSpec) {
@@ -362,7 +362,7 @@ function _buildAttributes(attrSpec) {
   return b.sequence(attrs);
 }
 
-// extensions ::= SEQUENCE OF Extension (RFC 5755 sec. 4.2.9) -- the recognized object form, or an array
+// extensions ::= SEQUENCE OF Extension (RFC 5755 sec. 4.2.9): the recognized object form, or an array
 // of pre-encoded Extension DER. At most one instance of a particular extension OID. Returns a universal
 // SEQUENCE OF Extension, or null when none are requested.
 function _buildExtensions(extSpec, aaSpki) {
@@ -427,21 +427,21 @@ function _buildExtensions(extSpec, aaSpki) {
  * syntaxes -- role / clearance / group / chargingIdentity / accessIdentity / authenticationInfo -- or an
  * array of pre-encoded Attribute DER), and optional `extensions` (an object of auditIdentity /
  * targetInformation / noRevAvail / aaControls / acProxying / authorityKeyIdentifier, or an array of
- * pre-encoded Extension DER). `issuer` is the signing AA -- `{ cert, key }` (the AA certificate DER/PEM
+ * pre-encoded Extension DER). `issuer` is the signing AA: `{ cert, key }` (the AA certificate DER/PEM
  * and its private key) or `{ name, publicKey, key }` (an explicit issuer DN, AA SPKI DER, and key); an
  * attribute certificate is never self-signed. The signature algorithm is resolved from the AA key (RSA
  * PKCS#1 v1.5 or PSS, ECDSA, EdDSA, ML-DSA, SLH-DSA, or a composite arm), and the signature is verified
  * under the AA public key before the certificate is returned. Returns DER, or a PEM `ATTRIBUTE
  * CERTIFICATE` with `opts.pem`. Malformed input throws a typed `AttrCertError`; where the spec carries
- * raw DER -- a holder or issuer `Name` Buffer, a pre-encoded `Extension` -- a malformed leaf inside
+ * raw DER (a holder or issuer `Name` Buffer, a pre-encoded `Extension`) a malformed leaf inside
  * those bytes throws `Asn1Error`. The AA certificate's own
- * profile (RFC 5755 sec. 4.5) and validity are a verification-layer concern -- validate the AA
+ * profile (RFC 5755 sec. 4.5) and validity are a verification-layer concern, so validate the AA
  * certificate with `pki.path.validate` before trusting the attribute certificate. Parsing is
  * `pki.schema.attrcert.parse`.
  *
  * @opts
  *   - `pem` (boolean) -- return a PEM `ATTRIBUTE CERTIFICATE` string instead of DER.
- *   - `pss` (boolean) -- sign an RSA key with RSASSA-PSS rather than PKCS#1 v1.5.
+ *   - `pss` (boolean) -- sign an RSA key with RSASSA-PSS instead of PKCS#1 v1.5.
  *   - `digestAlgorithm` (string) -- override the message digest where the algorithm permits a choice.
  * @example
  *   var pair = await pki.key.generate("Ed25519");

package/lib/byte-reader.js

@@ -7,10 +7,10 @@
  * primitive under the toolkit's non-ASN.1 length-prefixed wire formats (TLS-vector
  * SCTs in pki.ct, the packed big-endian TPM2B_* / authenticatorData structures in
  * pki.webauthn). Every read is length-checked against a hard [pos, end) window
- * BEFORE a byte is taken, so a lying inner length can overrun only the current
- * sub-reader's `end`, never the parent buffer -- bounds-before-slice is structural,
- * not a per-call discipline. It carries the CALLER's typed ErrorClass so every wire
- * format keeps its own `domain/reason` fault code, exactly as the guard family does.
+ * before a byte is taken, so a lying inner length can overrun only the current
+ * sub-reader's `end`, never the parent buffer. Bounds-before-slice is structural
+ * here, not a per-call discipline. It carries the caller's typed ErrorClass so every
+ * wire format keeps its own `domain/reason` fault code, exactly as the guard family does.
  *
  * This is an engine primitive, not a format: a new fixed-width or length-prefixed
  * wire field is a method here (with its own bounds check), never a hand-rolled
@@ -47,9 +47,9 @@ 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> -- a length-prefixed vector (lenWidth-byte big-endian prefix:
+// 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`.
+// 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);

package/lib/byte-writer.js

@@ -7,10 +7,10 @@
  * lib/byte-reader.js, the shared producer under the toolkit's non-ASN.1 length-prefixed
  * wire formats (the TLS-vector SCT list pki.ct emits; any future TLS-presentation
  * producer). Every fixed-width integer is range-checked against its field width and
- * every length-prefixed vector against its declared bound BEFORE a byte is committed,
+ * every length-prefixed vector against its declared bound before a byte is committed,
  * so an out-of-range value or an over-long body faults through the caller's typed
- * ErrorClass rather than silently truncating mod 2^(8*width). It carries the CALLER's
- * ErrorClass exactly as ByteReader / the guard family do, so every wire format keeps
+ * ErrorClass instead of silently truncating mod 2^(8*width). It carries the caller's
+ * ErrorClass exactly as ByteReader and the guard family do, so every wire format keeps
  * its own `domain/reason` fault code.
  *
  * This is an engine primitive, not a format: a new fixed-width or length-prefixed wire
@@ -30,7 +30,7 @@ function ByteWriter(E, defaultCode) {
 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 rather than silently wrapping.
+// 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;
@@ -59,7 +59,7 @@ ByteWriter.prototype.bytes = function (buf, code) {
   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
+// 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");

package/lib/cbor-det.js

@@ -15,12 +15,13 @@
  *   codec that owns its stack, rejects every non-canonical shape before it
  *   returns a value, and bounds size and depth before it walks a byte.
  *
- *   Anything a lenient CBOR reader would tolerate -- an indefinite-length
- *   item, a non-minimal ("preferred") integer / length / tag argument, a
- *   non-shortest or non-canonical-NaN float, out-of-order or duplicate map
- *   keys, ill-formed UTF-8, or trailing bytes -- is a permanent `CborError`
- *   here, because deterministic CBOR is a canonical encoding and a producer
- *   that violates it produced invalid bytes. There is no lenient mode.
+ *   A lenient CBOR reader tolerates a good deal this one refuses: an
+ *   indefinite-length item, a non-minimal ("preferred") integer / length /
+ *   tag argument, a non-shortest or non-canonical-NaN float, out-of-order or
+ *   duplicate map keys, ill-formed UTF-8, trailing bytes. Every one of them
+ *   is a permanent `CborError` here, because deterministic CBOR is a
+ *   canonical encoding and a producer that violates it produced invalid
+ *   bytes. There is no lenient mode.
  *
  *   `decode` returns a navigable node tree with zero-copy `bytes` / `content`
  *   views (the raw ranges an external verifier hashes); the `read.*` leaf
@@ -47,12 +48,12 @@ 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 -- the fail-open class the toolkit
-// refuses, mirroring asn1-der's strict text decode.
+// 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
+// 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;
@@ -135,8 +136,9 @@ 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 -- for every major type but 7, where the
-    // "argument" is raw float bits governed by the shortest-float rule instead.
+    // 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) {
@@ -249,7 +251,7 @@ function _decodeItem(buf, start, limit, depth, maxD, rules, state) {
  *   maxBytes:       number,   // default: C.LIMITS.CBOR_MAX_BYTES (16 MiB)
  *   maxDepth:       number,   // default: C.LIMITS.CBOR_MAX_DEPTH (64)
  *   maxItems:       number,   // default: C.LIMITS.CBOR_MAX_ITEMS (1,000,000 total decoded items)
- *   allowTrailing:  boolean,  // default: false -- true returns the first item and permits bytes after it (CBOR Sequence)
+ *   allowTrailing:  boolean,  // default: false; true returns the first item and permits bytes after it (CBOR Sequence)
  *   profile:        string,   // default: "deterministic" (the only value v1 accepts)
  *
  * @example
@@ -429,18 +431,19 @@ function readMap(node) {
  * @status     stable
  * @spec       RFC 8949 sec. 3.1 (major type 5)
  *
- * The value node of the map entry whose key equals `key` -- a text string
- * (matched against text-string keys) or an integer (a safe-integer number or a
- * BigInt, matched against integer keys, as COSE labels are) -- or null when the
- * map has no such entry. Key matching never coerces across types: a text key
- * only matches a text-string key node, an integer key only an integer key node.
- * At most one entry can match -- decode already enforced key uniqueness. This is
- * the single keyed-lookup home over a decoded map: a consumer composes it (or
- * `read.map`) rather than walking `children` as pairs, so a lookup can never
- * pair-index a non-map's children (single nodes, whose pair index reads
- * undefined). Throws `cbor/unexpected-major` when `node` is not a map -- a
- * lookup on a non-map is malformed input, never an absent-entry verdict -- and
- * a TypeError for a key that is neither a text string nor an integer.
+ * The value node of the map entry whose key equals `key`, or null when the map
+ * has no such entry. A key is a text string (matched against text-string keys)
+ * or an integer (a safe-integer number or a BigInt, matched against integer
+ * keys, as COSE labels are). Key matching never coerces across types: a text
+ * key only matches a text-string key node, an integer key only an integer key
+ * node. At most one entry can match, because decode already enforced key
+ * uniqueness. This is the single keyed-lookup home over a decoded map. A
+ * consumer composes it, or `read.map`; hand-walking `children` as pairs is what
+ * lets a lookup pair-index a non-map's children (single nodes, whose pair index
+ * reads undefined). Throws `cbor/unexpected-major` when `node` is not a map,
+ * treating a lookup on a non-map as malformed input and never as an
+ * absent-entry verdict, and a TypeError for a key that is neither a text string
+ * nor an integer.
  *
  * @example
  *   // a WebAuthn-shaped map: {3: -7, "fmt": "packed"} in deterministic key order