@blamejs/pki 0.6.13 → 0.6.15

package/lib/ip-utils.js

@@ -1,24 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- no operator-facing namespace. Textual IP-literal validation, shared so a
-// consumer (pki.lint's commonName-in-SAN check today; the SAN iPAddress GeneralName shorthand
-// and name-constraint surfaces) does not hand-roll a partial regex that misses a valid IPv6 form.
-//
-// The IPv4 grammar is strict per-octet 0-255 (RFC 791); the IPv6 parser follows RFC 4291
-// sec. 2.2 (8 groups of 1-4 hex, one "::" run compressing a contiguous zero run) plus the
-// RFC 4291 sec. 2.5.5.2 / RFC 5952 sec. 5 IPv4-mapped + dual-stack "::ffff:1.2.3.4" tail.
-// This mirrors the vetted validation in the sibling blamejs framework (lib/ip-utils.js);
-// this toolkit keeps its own copy, since Hard rule #1 rules out a runtime dependency.
+// @internal
 
-// This parser uses no regular expression. packIpLiteral gates a GeneralName form decision (iPAddress
-// vs dNSName), and a regex is matched through a live, replaceable protocol -- RegExp.prototype.exec /
-// test and String.prototype.match / split consult the regex's own `exec` and the `[Symbol.match]` /
-// `[Symbol.split]` hooks, and RegExp.prototype.compile can mutate a pattern in place -- so co-resident
-// code could steer the decision after load. Instead every byte is read directly through captured string
-// primitives, and separation on a literal is done by scanning with captured indexOf/slice, so nothing the
-// decision rests on is re-dispatchable.
 var intrinsic = require("./guard-intrinsic");
 var _slice = intrinsic.uncurry(String.prototype.slice);
 var _padStart = intrinsic.uncurry(String.prototype.padStart);
@@ -31,15 +15,7 @@ var _bufferFrom = intrinsic.bufferFrom;
 var _bufferAlloc = intrinsic.bufferAlloc;
 var _defineProperty = intrinsic.defineProperty;
 var _Number = intrinsic.Number;
-// Every array here is built and read as own elements only. Appending through a captured Object.defineProperty
-// (not `arr[i] = v`) creates an own element, so a co-resident Array.prototype numeric setter is never invoked
-// and the own element shadows any inherited getter on read; and no Array.prototype.map / concat runs, so
-// Array[Symbol.species] is never consulted. Both are routes a hostile prototype could otherwise use to
-// rewrite a packed octet and make a certificate carry an attacker-chosen address. The emitted octets are
-// written straight into a Buffer, whose integer-indexed store bypasses the prototype entirely.
 function _push(arr, v) { _defineProperty(arr, arr.length, { value: v, writable: true, enumerable: true, configurable: true }); }
-// Split on a literal string separator without String.prototype.split, which consults the separator's
-// `[Symbol.split]`; this scans with captured indexOf/slice only.
 function _splitOn(str, sep) {
   var out = [], from = 0, at;
   while ((at = _indexOf(str, sep, from)) !== -1) { _push(out, _slice(str, from, at)); from = at + sep.length; }
@@ -47,19 +23,17 @@ function _splitOn(str, sep) {
   return out;
 }
 
-function _isDigitCode(c) { return c >= 48 && c <= 57; }                                      // 0-9
+function _isDigitCode(c) { return c >= 48 && c <= 57; }
 function _isHexCode(c) { return (c >= 48 && c <= 57) || (c >= 97 && c <= 102) || (c >= 65 && c <= 70); }
 
-// A strict RFC 791 dotted-quad octet: 1-3 digits, value 0-255, no leading zero beyond "0" itself.
 function _isOctet(p) {
   var n = p.length, i, c;
   if (n < 1 || n > 3) return false;
   for (i = 0; i < n; i += 1) { c = _charCodeAt(p, i); if (!_isDigitCode(c)) return false; }
-  if (n > 1 && _charCodeAt(p, 0) === 48) return false;   // a leading zero is not the canonical form
+  if (n > 1 && _charCodeAt(p, 0) === 48) return false;
   return _Number(p) <= 255;
 }
 
-// Strict RFC 791 dotted quad: four 0-255 octets, nothing else.
 function isIPv4(s) {
   if (typeof s !== "string") return false;
   var parts = _splitOn(s, ".");
@@ -68,7 +42,6 @@ function isIPv4(s) {
   return true;
 }
 
-// A single 1-4 hex-digit IPv6 group.
 function _isHexGroup(g) {
   var n = g.length, i;
   if (n < 1 || n > 4) return false;
@@ -76,8 +49,6 @@ function _isHexGroup(g) {
   return true;
 }
 
-// The RFC 4291 sec. 2.5.5.2 dual-stack tail SHAPE: exactly four 1-3 digit groups joined by dots. Validity
-// (0-255 per octet) is a separate isIPv4 check, matching the historical two-step (shape then value).
 function _isDottedQuadShape(t) {
   var q = _splitOn(t, "."), i, p, j;
   if (q.length !== 4) return false;
@@ -89,14 +60,9 @@ function _isDottedQuadShape(t) {
   return true;
 }
 
-// Expand an IPv6 textual address to its 32-hex-character form, or null on any parse failure
-// (bad hex group, group count != 8, more than one "::", an over-length group). Accepts the
-// IPv4-mapped / dual-stack ".d.d.d.d" tail.
-var IPV6_TEXT_MAX_LEN = 45;   // 8 groups x4 hex + 7 colons + a dotted-quad tail headroom
+var IPV6_TEXT_MAX_LEN = 45;
 function expandIpv6Hex(ip) {
   if (typeof ip !== "string" || ip.length > IPV6_TEXT_MAX_LEN || _indexOf(ip, ":") === -1) return null;
-  // RFC 4291 sec. 2.5.5.2 IPv4-mapped / dual-stack: fold a trailing dotted-quad (the suffix after the
-  // last colon, when it carries a dot) into two 16-bit hex groups before the pure-hex parse.
   var lastColon = _lastIndexOf(ip, ":");
   var tail = _slice(ip, lastColon + 1);
   if (_indexOf(tail, ".") !== -1) {
@@ -110,10 +76,8 @@ function expandIpv6Hex(ip) {
   var right = dbl.length === 2 ? (dbl[1] === "" ? [] : _splitOn(dbl[1], ":")) : [];
   if (dbl.length === 1 && left.length !== 8) return null;
   var fill = 8 - left.length - right.length;
-  // A "::" run MUST compress at least one zero group (RFC 4291 sec. 2.2 / RFC 5952 sec.
-  // 4.2.2): a "::" with fill 0 is a full 8-group address that must not use compression.
   if (dbl.length === 2 ? fill < 1 : fill !== 0) return null;
-  var groups = left, i;   // `left` is a fresh own-element array; append through _push (no inherited setter)
+  var groups = left, i;
   for (i = 0; i < fill; i += 1) _push(groups, "0");
   for (i = 0; i < right.length; i += 1) _push(groups, right[i]);
   if (groups.length !== 8) return null;
@@ -126,17 +90,12 @@ function expandIpv6Hex(ip) {
   return hex;
 }
 
-// Is `s` a syntactically valid IPv4 or IPv6 textual literal?
 function isIpLiteral(s) { return isIPv4(s) || expandIpv6Hex(s) !== null; }
 
-// Pack an IPv4/IPv6 textual literal to its network-order octets (4 for IPv4, 16 for IPv6),
-// or null when `s` is not a valid literal. The binary inverse of the textual forms isIPv4 /
-// expandIpv6Hex validate, so a SAN/GeneralName iPAddress (RFC 5280 sec. 4.2.1.6, always a bare
-// host address of 4 or 16 octets) can be given as a string instead of a pre-packed Buffer.
 function packIpLiteral(s) {
   if (isIPv4(s)) {
     var parts = _splitOn(s, "."), buf = _bufferAlloc(4), i;
-    for (i = 0; i < 4; i += 1) buf[i] = _Number(parts[i]);   // Buffer integer-index store; each octet range-checked by _isOctet
+    for (i = 0; i < 4; i += 1) buf[i] = _Number(parts[i]);
     return buf;
   }
   var hex = expandIpv6Hex(s);

package/lib/jose.js

@@ -42,12 +42,6 @@ var webcrypto = wcEngine.webcrypto;
 var frameworkError = require("./framework-error");
 var guard = require("./guard-all");
 var edwardsPoint = require("./edwards-point");
-// What this module reads from the runtime while it is deciding something, taken at load. A JWS is
-// signed and verified against a header the caller owns, and the reads below are the ones that decide
-// what that header IS: whether a value is a list, whether a name is the caller's own, which
-// conversion turns a claim into the string compared against a profile. A caller who receives control
-// afterwards -- through an accessor on the header, or a `toJSON` while it is being serialized -- can
-// replace any of them, and every check around them still runs and still passes. See guard-intrinsic.
 var intrinsic = require("./guard-intrinsic");
 var _isArray = intrinsic.isArray;
 var _hasOwn = intrinsic.hasOwn;
@@ -66,7 +60,6 @@ function E(code, message, cause) { return new JoseError(code, message, cause); }
 
 var LIMITS = constants.LIMITS;
 
-// ---- strict base64url codec (RFC 7515 sec. 2 / RFC 4648 sec. 5) ----------
 
 /**
  * @primitive  pki.jose.base64url.encode
@@ -84,8 +77,6 @@ var LIMITS = constants.LIMITS;
  */
 function b64uEncode(bytes) {
   if (!_isBuffer(bytes)) throw E("jose/bad-input", "base64url.encode requires a Buffer");
-  // Re-view through the byte guard: a detached-backed Buffer reads as zero-length,
-  // so a bare .toString would silently encode "" -- fail closed instead.
   bytes = guard.bytes.view(bytes, JoseError, "jose/bad-input", "base64url.encode input");
   return _bufToString(bytes, "base64url");
 }
@@ -107,13 +98,9 @@ function b64uEncode(bytes) {
  *   pki.jose.base64url.decode("AQID");   // -> <Buffer 01 02 03>
  */
 function b64uDecode(text) {
-  // The strict alphabet + impossible-length + canonical-round-trip discipline
-  // lives once in the shared encoding guard (RFC 4648 sec. 5 / RFC 8555 sec. 6.1);
-  // the frozen jose/bad-base64url code is threaded through.
   return guard.encoding.base64url(text, null, E, "jose/bad-base64url", "base64url value");
 }
 
-// ---- strict bounded JSON reader ------------------------------------------
 
 /**
  * @primitive  pki.jose.parseJson
@@ -134,9 +121,6 @@ function b64uDecode(text) {
  *   pki.jose.parseJson('{"a":1}');   // -> { a: 1 }
  */
 function parseJson(input) {
-  // The strict bounded reader (byte + depth caps, duplicate-member reject at every
-  // depth, __proto__-safe own-property assignment, fatal UTF-8, RFC 8259 grammar)
-  // lives once in the shared JSON guard; the frozen jose/* codes are threaded through.
   return guard.json.parse(input, E, {
     maxBytes: LIMITS.JSON_MAX_BYTES, maxDepth: LIMITS.JSON_MAX_DEPTH,
     badJson: "jose/bad-json", tooDeep: "jose/too-deep", duplicateMember: "jose/duplicate-member",
@@ -144,15 +128,7 @@ function parseJson(input) {
   });
 }
 
-// ---- JOSE algorithm registry (RFC 7518 / 8037 / 9964) --------------------
 
-// One data row per JWS `alg`, keyed for O(1) resolution -- never a switch. Each
-// row binds the alg to its JWK key type (and, for EC/OKP, the exact curve), the
-// hash, and the WebCrypto import/verify parameters, plus the exact signature
-// byte length (fixed for EC / EdDSA / ML-DSA; the RSA modulus length for RS*/PS*,
-// resolved from the key). Binding alg->kty in DATA is what kills the RS256->HS256
-// key-confusion class: an ES256 header with an RSA key is rejected here, before
-// any crypto call. `HS*`/`none` are absent from this table by construction.
 var SIG_ALGS = {
   ES256: { kty: "EC", crv: "P-256", hash: "SHA-256", subtle: "ECDSA", sigBytes: 64 },
   ES384: { kty: "EC", crv: "P-384", hash: "SHA-384", subtle: "ECDSA", sigBytes: 96 },
@@ -169,66 +145,41 @@ var SIG_ALGS = {
   "ML-DSA-87": { kty: "AKP", subtle: "ML-DSA-87", sigBytes: 4627 },
 };
 
-// The MAC table exists ONLY for the RFC 8555 sec. 7.3.4 externalAccountBinding
-// inner JWS -- HS* appears nowhere in the outer/signature profiles, so an
-// `alg:"HS256"` on an ACME request rejects (the RS256->HS256 downgrade class).
 var MAC_ALGS = {
   HS256: { kty: "oct", hash: "SHA-256", sigBytes: 32 },
   HS384: { kty: "oct", hash: "SHA-384", sigBytes: 48 },
   HS512: { kty: "oct", hash: "SHA-512", sigBytes: 64 },
 };
 
-// The header parameter names this implementation understands. A `crit` naming
-// anything outside this set is unprocessable -> the JWS is invalid (RFC 7515
-// sec. 4.1.11); ACME defines no extension params, so any `crit` entry rejects.
 var UNDERSTOOD_HEADER = { alg: 1, nonce: 1, url: 1, jwk: 1, kid: 1, crit: 1 };
 
-// ---- JWS profiles (declarative -- one table drives sign AND verify) ------
 
-// Each profile is DATA: the algorithm table it permits, the required params,
-// whether `nonce` is required/forbidden, and the key-identification rule
-// (exactly-one-of jwk/kid, or one specifically). The profile carries the rule,
-// not the code path -- so the EAB-inner table ACCEPTS HS256 where the ACME-outer
-// table REJECTS it, from the same walker.
 var PROFILES = {
   "acme-outer":     { algs: SIG_ALGS, nonce: "required",  keyId: "one-of", requireUrl: true },
   "eab-inner":      { algs: MAC_ALGS, nonce: "forbidden", keyId: "kid",    requireUrl: true },
   "keychange-inner": { algs: SIG_ALGS, nonce: "forbidden", keyId: "jwk",    requireUrl: true },
 };
 
-// Validate a decoded protected header against a profile. Returns the resolved
-// { alg, algRow, header }; throws a typed jose/* fault on any violation.
 function _checkHeader(header, profileName) {
   var profile = PROFILES[profileName];
   if (!profile) throw E("jose/bad-input", "unknown JWS profile " + _stringify(profileName));
   if (!header || typeof header !== "object" || _isArray(header)) throw E("jose/bad-header", "the protected header must be a JSON object");
-  // Every field is read as an OWN property. JSON.stringify (used by sign) omits
-  // inherited members, so an alg/nonce/url living on the prototype (a polluted or
-  // Object.create(...) header) would pass here yet serialize to a header MISSING
-  // them -- so require own-ness, matching what the serialized JWS will actually carry.
   var own = function (k) { return _hasOwn(header, k); };
-  // b64 (RFC 7797) MUST NOT be present at all -- the unencoded-payload downgrade.
   if (own("b64")) throw E("jose/bad-jws", "the RFC 7797 b64 header parameter is forbidden");
   var alg = header.alg;
   if (!own("alg") || typeof alg !== "string") throw E("jose/bad-header", "the protected header must carry a string alg");
   var algRow = profile.algs[alg];
   if (!algRow) throw E("jose/bad-alg", "unsupported or forbidden algorithm " + _stringify(alg) + " for this JWS profile");
   if (profile.requireUrl && (!own("url") || typeof header.url !== "string" || header.url.length === 0)) throw E("jose/bad-header", "the protected header must carry a non-empty string url");
-  // nonce discipline.
   var hasNonce = own("nonce");
   if (profile.nonce === "required") {
-    // A Replay-Nonce is 1*base64url -- NON-empty (RFC 8555 sec. 6.5.2); "" decodes as
-    // canonical base64url but no server issues it, so reject it locally.
     if (!hasNonce || typeof header.nonce !== "string" || header.nonce.length === 0) throw E("jose/bad-header", "the protected header must carry a non-empty nonce");
-    // a nonce that is not valid base64url is malformed (RFC 8555 sec. 6.5.2).
     try { b64uDecode(header.nonce); } catch (e) { throw E("jose/bad-header", "the nonce is not valid base64url", e); }
   } else if (profile.nonce === "forbidden" && hasNonce) {
     throw E("jose/bad-header", "a nonce is forbidden in this inner JWS");
   }
-  // key identification.
   var hasJwk = own("jwk");
   var hasKid = own("kid");
-  // A kid is a non-empty account URL string.
   if (hasKid && (typeof header.kid !== "string" || header.kid.length === 0)) throw E("jose/bad-header", "kid must be a non-empty string");
   if (profile.keyId === "one-of") {
     if (hasJwk === hasKid) throw E("jose/bad-header", "the protected header must carry EXACTLY ONE of jwk / kid");
@@ -238,7 +189,6 @@ function _checkHeader(header, profileName) {
     if (!hasJwk || hasKid) throw E("jose/bad-header", "this JWS must carry an embedded jwk, not kid");
   }
   if (hasJwk && (!header.jwk || typeof header.jwk !== "object" || _isArray(header.jwk))) throw E("jose/bad-header", "jwk must be a JSON object");
-  // crit: protected-only, non-empty, no standard names, no duplicates, all understood.
   if (_hasOwn(header, "crit")) {
     var crit = header.crit;
     if (!_isArray(crit) || crit.length === 0) throw E("jose/bad-crit", "crit must be a non-empty array");
@@ -249,72 +199,53 @@ function _checkHeader(header, profileName) {
       if (_hasOwn(seen, name)) throw E("jose/bad-crit", "duplicate crit entry " + _stringify(name));
       seen[name] = 1;
       if (UNDERSTOOD_HEADER[name]) throw E("jose/bad-crit", "crit must not name a standard header parameter " + _stringify(name));
-      // Anything else is an extension parameter this implementation does not process.
       throw E("jose/bad-crit", "unprocessed critical header parameter " + _stringify(name));
     }
   }
   return { alg: alg, algRow: algRow, header: header };
 }
 
-// ---- flattened-JWS verify (RFC 7515 sec. 5.2) ----------------------------
 
-// Resolve the WebCrypto import parameters for a JWK under an alg row.
 function _importParams(algRow, jwk) {
   if (algRow.kty === "EC") return { name: "ECDSA", namedCurve: algRow.crv };
   if (algRow.kty === "RSA") return { name: algRow.subtle, hash: algRow.hash };
-  if (algRow.kty === "OKP") return { name: jwk.crv };            // Ed25519 / Ed448
-  if (algRow.kty === "AKP") return { name: algRow.subtle };      // ML-DSA-44/65/87
-  if (algRow.kty === "oct") return { name: "HMAC", hash: algRow.hash }; // EAB inner (HS*)
+  if (algRow.kty === "OKP") return { name: jwk.crv };
+  if (algRow.kty === "AKP") return { name: algRow.subtle };
+  if (algRow.kty === "oct") return { name: "HMAC", hash: algRow.hash };
   throw E("jose/bad-alg", "unsupported key type");
 }
 
-// The WebCrypto verify/sign algorithm for an alg row + JWK.
 function _cryptoAlg(algRow, jwk, key) {
   if (algRow.kty === "EC") return { name: "ECDSA", hash: algRow.hash };
   if (algRow.kty === "RSA") return algRow.subtle === "RSA-PSS" ? { name: "RSA-PSS", saltLength: algRow.saltLength } : { name: "RSASSA-PKCS1-V1_5" };
-  // EdDSA carries the curve (Ed25519 / Ed448) as the WebCrypto algorithm name. In
-  // a kid-signed request there is no header/opts jwk to read it from, so fall back
-  // to the signing key's own algorithm -- an Ed25519 account key must stay usable
-  // after account creation, not only in the embedded-jwk (newAccount) case.
   if (algRow.kty === "OKP") return { name: (jwk && jwk.crv) || (key && key.algorithm && key.algorithm.name) };
   if (algRow.kty === "AKP") return { name: algRow.subtle };
   if (algRow.kty === "oct") return { name: "HMAC" };
   throw E("jose/bad-alg", "unsupported key type");
 }
 
-// The key type the JWK MUST have for this alg (fail closed on confusion).
 function _assertKeyType(algRow, jwk) {
   if (!jwk || typeof jwk !== "object" || typeof jwk.kty !== "string") throw E("jose/bad-key", "a JWK object with a kty is required");
   if (jwk.kty !== algRow.kty) throw E("jose/bad-alg", "the key type " + _stringify(jwk.kty) + " does not match the algorithm");
   if (algRow.kty === "EC" && jwk.crv !== algRow.crv) throw E("jose/bad-alg", "the EC curve does not match the algorithm");
   if (algRow.kty === "OKP" && jwk.crv !== "Ed25519" && jwk.crv !== "Ed448") throw E("jose/bad-alg", "unsupported OKP curve " + _stringify(jwk.crv));
-  // node/OpenSSL import a low-order (e.g. identity) OKP point without complaint and it verifies a
-  // forged signature; reject a non-full-order Edwards point through the shared gate, the same check
-  // every EdDSA verify path in the toolkit applies.
   if (algRow.kty === "OKP" && typeof jwk.x === "string" && !edwardsPoint.validate(b64uDecode(jwk.x), jwk.crv === "Ed25519" ? 6 : 7)) {
     throw E("jose/bad-key", "the OKP public key is not a valid, full-order Edwards point");
   }
-  // An AKP (ML-DSA) JWK carries its parameter set in `alg` (RFC 9964); it MUST match
-  // the algorithm's set, or an ML-DSA-44 key could embed an ML-DSA-65 public JWK.
   if (algRow.kty === "AKP" && jwk.alg !== algRow.subtle) throw E("jose/bad-alg", "the AKP parameter set " + _stringify(jwk.alg) + " does not match the algorithm " + algRow.subtle);
 }
 
-// The exact signature byte length this alg + key must produce.
 function _expectedSigBytes(algRow, jwk, key) {
   if (algRow.sigBytes != null) return algRow.sigBytes;
-  // EdDSA: the curve fixes the length. On the verify side it is read from the JWK;
-  // on the sign side (kid mode, no JWK) it comes from the signing key's algorithm.
   if (algRow.sigBytesByCrv) return algRow.sigBytesByCrv[(jwk && jwk.crv) || (key && key.algorithm && key.algorithm.name)] || null;
   if (algRow.kty === "RSA") {
-    if (jwk && typeof jwk.n === "string") return b64uDecode(jwk.n).length;          // verify: modulus from the JWK
-    if (key && key.algorithm && key.algorithm.modulusLength) return key.algorithm.modulusLength / 8; // sign: from the key
+    if (jwk && typeof jwk.n === "string") return b64uDecode(jwk.n).length;
+    if (key && key.algorithm && key.algorithm.modulusLength) return key.algorithm.modulusLength / 8;
     return null;
   }
   return null;
 }
 
-// The JWK members that carry PRIVATE key material across every key type -- EC/OKP
-// `d`, the RSA CRT set, the symmetric `k`, and the AKP `priv`.
 var PRIVATE_JWK_MEMBERS = ["d", "p", "q", "dp", "dq", "qi", "k", "priv"];
 
 /**
@@ -384,10 +315,6 @@ function assertPublicJwk(jwk) {
  *   var v = await pki.jose.verify(jws, { profile: "acme-outer", key: accountJwk });
  *   v.header.alg;   // -> "ES256"
  */
-// `key` NAMES the key this message must be signed under and `profile` selects which header rules
-// apply -- both narrow what verifies, so a misspelling of either silently widens it back to the
-// default. That is the shape this check exists for: the caller asked for something stricter and got
-// the looser behavior, with nothing said.
 var _VERIFY_KEYS = { key: 1, profile: 1 };
 async function verify(jws, opts) {
   opts = opts || {};
@@ -400,17 +327,6 @@ async function verify(jws, opts) {
   var header = parseJson(b64uDecode(jws.protected));
   var profileName = opts.profile || "acme-outer";
   var checked = _checkHeader(header, profileName);
-  // A caller supplying opts.key is NAMING the key this message must be signed under. A profile
-  // that also permits an embedded jwk lets the message carry one, and preferring that would let
-  // the sender choose which key verifies it -- exactly the question opts.key was asked to settle.
-  // So when both are present they must be the SAME key, compared as RFC 7638 thumbprints: that
-  // canonicalizes member order and ignores members outside the key itself, so two spellings of
-  // one key agree and two different keys cannot.
-  // A SUPPLIED key that cannot be used is refused, never quietly treated as absent. Falling back
-  // to the embedded jwk there would drop the caller's intent to pin a signer at the moment it
-  // matters most -- a `key` that came back null from a lookup would verify against whatever the
-  // message carried, and the verdict would report the embedded key as though none was named.
-  // `undefined` alone means "not supplied", so spreading an options object stays safe.
   if (opts.key !== undefined && (typeof opts.key !== "object" || opts.key === null || _isArray(opts.key))) {
     throw E("jose/bad-key", "opts.key was supplied but is not a JWK object, so the key this message must be signed under cannot be established");
   }
@@ -436,20 +352,15 @@ async function verify(jws, opts) {
   var sig = b64uDecode(jws.signature);
   var want = _expectedSigBytes(checked.algRow, jwk);
   if (want != null && sig.length !== want) throw E("jose/bad-signature", "the signature length " + sig.length + " is not the " + want + " bytes " + checked.alg + " requires");
-  // Signing input from the RECEIVED base64url strings verbatim (never a re-serialize).
   var signingInput = _bufferFrom(jws.protected + "." + jws.payload, "ascii");
   var key;
   try { key = await webcrypto.subtle.importKey("jwk", jwk, _importParams(checked.algRow, jwk), false, ["verify"]); }
   catch (e) { throw E("jose/bad-key", "the JWK could not be imported for verification", e); }
   var ok = await webcrypto.subtle.verify(_cryptoAlg(checked.algRow, jwk), key, sig, signingInput);
   if (!ok) throw E("jose/verify-failed", "the JWS signature did not verify");
-  // WHICH key answered. A caller auditing the decision needs "checked against the key I named"
-  // to be distinguishable from "checked against the one the message brought with it"; the two
-  // are different claims and only the first says anything about who the signer is.
   return { header: header, payload: b64uDecode(jws.payload), keySource: keySource };
 }
 
-// ---- flattened-JWS sign (RFC 7515 sec. 5.1) ------------------------------
 
 /**
  * @primitive  pki.jose.sign
@@ -484,31 +395,16 @@ async function verify(jws, opts) {
  *     nonce: "oFvnlFP1wIhRlYS2jTaXbA", url: "https://ca.example/acme/new-acct" };
  *   var jws = await pki.jose.sign({ protected: hdr, payload: Buffer.from("{}"), key: priv });
  */
-// The public JWK has two sources and the embedded one wins, so opts.jwk is read only in kid mode.
-// Supplied alongside a header that embeds its own, it selected nothing: the signature parameters
-// came from the header's key while the caller had named a different one.
 var _SIGN_KEYS = { protected: 1, payload: 1, key: 1, jwk: 1, profile: 1 };
 var _SIGN_KEYS_EMBEDDED_JWK = { protected: 1, payload: 1, key: 1, profile: 1 };
 async function sign(opts) {
   opts = opts || {};
-  // The options are checked BEFORE the header is touched. Serializing it runs the caller's own code
-  // -- a toJSON, an accessor -- and that code can delete an option from the very bag being checked,
-  // so a misspelling reached the door already removed and the message went out signed.
   guard.identifier.assertKnownKeys(opts, _SIGN_KEYS, E, "jose/bad-input", "unknown pki.jose.sign option ");
-  // The header is then serialized ONCE, and every read below comes from a snapshot of those exact
-  // bytes: the header validated, the header embedded in the JWS and the key confirmed against the
-  // produced signature are then all the same values. Read live, a caller getter answers each of
-  // those questions separately -- assertPublicJwk sees a public JWK while the bytes that ship carry
-  // the private one, and the door sees a jwk-mode header while the signer sees a kid-mode one.
   var headerJson;
   try { headerJson = _stringify(opts.protected); }
   catch (e) { throw E("jose/bad-header", "the protected header must be JSON-serializable", e); }
-  // Read back through the same bounded reader a received JWS goes through, so a header this side
-  // produces is held to the caps and the duplicate-member rule the other side enforces.
   var headerBytes = headerJson === undefined ? null : _bufferFrom(headerJson, "utf8");
   var header = headerBytes === null ? opts.protected : parseJson(headerBytes);
-  // Which of the two key sources is in force is known only once the header has been read, so the
-  // narrower table runs here. It re-walks the bag, which also catches a name that code added.
   var embedsJwk = !!(header && typeof header === "object" && header.jwk);
   if (embedsJwk) {
     guard.identifier.assertKnownKeys(opts, _SIGN_KEYS_EMBEDDED_JWK, E, "jose/bad-input", function (k) {
@@ -518,47 +414,22 @@ async function sign(opts) {
   }
   var payload = opts.payload;
   if (!_isBuffer(payload)) throw E("jose/bad-input", "payload must be a Buffer (empty Buffer for POST-as-GET)");
-  // Re-view before the length===0 fast-path: a DETACHED payload reads as zero-length
-  // and would be silently signed as an empty POST-as-GET body -- fail closed instead.
   payload = guard.bytes.view(payload, JoseError, "jose/bad-input", "payload");
-  // A non-CryptoKey (a raw Buffer, a string, a JWK object) would reach subtle.sign
-  // and throw a bare TypeError; require a CryptoKey (it carries an `algorithm`) so
-  // every caller -- and every acme builder that composes sign -- fails closed.
   if (!wcEngine.isCryptoKeyLike(opts.key)) throw E("jose/bad-input", "a private or secret CryptoKey (opts.key) is required");
   var checked = _checkHeader(header, opts.profile || "acme-outer");
-  // An RSA / HMAC key binds its hash at import; the signature-length pin below cannot
-  // see a hash mismatch (the modulus / MAC size is unchanged), so a SHA-512 key under
-  // RS256 would sign here yet fail verification. Reject the hash disagreement up front.
   if ((checked.algRow.kty === "RSA" || checked.algRow.kty === "oct") &&
       (!opts.key.algorithm.hash || opts.key.algorithm.hash.name !== checked.algRow.hash)) {
     throw E("jose/bad-key", "the signing key's hash does not match the algorithm " + checked.alg);
   }
-  // An embedded jwk (jwk mode / keychange-inner) is the public key a verifier will
-  // use, so it MUST match the alg exactly as verify enforces -- otherwise the header
-  // advertises a key that cannot verify this signature. (No jwk in kid mode.) It is
-  // also PUBLISHED to the server, so it must be public-only: an accidentally exported
-  // private JWK must never be serialized into the protected header.
   if (header.jwk) { _assertKeyType(checked.algRow, header.jwk); assertPublicJwk(header.jwk); }
-  var protectedB64 = b64uEncode(headerBytes);   // the exact bytes every check above read
+  var protectedB64 = b64uEncode(headerBytes);
   var payloadB64 = payload.length === 0 ? "" : b64uEncode(payload);
   var signingInput = _bufferFrom(protectedB64 + "." + payloadB64, "ascii");
   var jwk = header.jwk || opts.jwk || {};
-  // opts.key is documented as a CryptoKey, so one created outside this engine signs here too: it
-  // carries none of the material this engine signs with, and is re-imported through it rather than
-  // reaching subtle.sign as a key it cannot read. A key whose material this process cannot reach at
-  // all -- non-extractable, or held behind another implementation's interface -- is refused there.
   var signKey = await wcEngine.adoptKey(opts.key, null, ["sign"], E, "jose/bad-input");
   var sigBuf = _bufferFrom(await webcrypto.subtle.sign(_cryptoAlg(checked.algRow, jwk, signKey), signKey, signingInput));
-  // Pin the produced signature length the same way verify does. A key whose curve /
-  // hash / modulus does not match the header alg (a P-384 key under ES256, an
-  // HS512 key under HS256) still signs, but emits the wrong length -- caught here
-  // so the builder fails locally instead of shipping a JWS the server will reject.
   var want = _expectedSigBytes(checked.algRow, jwk, opts.key);
   if (want != null && sigBuf.length !== want) throw E("jose/bad-key", "the signing key produced a " + sigBuf.length + "-byte signature but " + checked.alg + " requires " + want + " (the key does not match the algorithm)");
-  // In jwk mode the EMBEDDED public jwk is what verifiers use. Confirm it actually
-  // verifies this signature -- i.e. it is the signing key's public half -- so a
-  // key-pair mix-up (a jwk from a different key of the same type) fails locally
-  // instead of producing a JWS the CA rejects. Same-type/curve is not enough.
   if (header.jwk) {
     var pubKey;
     try { pubKey = await webcrypto.subtle.importKey("jwk", header.jwk, _importParams(checked.algRow, header.jwk), false, ["verify"]); }
@@ -570,17 +441,13 @@ async function sign(opts) {
   return { protected: protectedB64, payload: payloadB64, signature: b64uEncode(sigBuf) };
 }
 
-// ---- JWK thumbprint (RFC 7638 + RFC 8037 + RFC 9964) ---------------------
 
-// The required-member templates per key type (RFC 7638 sec. 3.2 / RFC 8037 sec. 2
-// / RFC 9964). ONLY these members, in lexicographic order, no whitespace, feed
-// the SHA-256; optional members (alg/use/kid) never enter the hash.
 var THUMBPRINT_MEMBERS = {
   EC: ["crv", "kty", "x", "y"],
   RSA: ["e", "kty", "n"],
   oct: ["k", "kty"],
   OKP: ["crv", "kty", "x"],
-  AKP: ["alg", "kty", "pub"],   // RFC 9964 sec. 6: alg, kty, pub in lexicographic order
+  AKP: ["alg", "kty", "pub"],
 };
 
 /**
@@ -613,8 +480,6 @@ async function thumbprint(jwk) {
   for (var i = 0; i < members.length; i++) {
     var m = members[i];
     if (typeof jwk[m] !== "string") throw E("jose/bad-key", "the JWK is missing the required member " + _stringify(m));
-    // The canonical form IS the thumbprint preimage (RFC 7638 sec. 3.3), so the serializer that
-    // builds it is the captured one: a replacement changes the identity every consumer compares.
     _push(parts, _stringify(m) + ":" + _stringify(jwk[m]));
   }
   var canonical = "{" + _join(parts, ",") + "}";