@blamejs/pki 0.4.15 → 0.5.1

package/lib/framework-error.js

@@ -47,6 +47,7 @@ var CODE_SHAPE = /^[a-z0-9-]+\/[a-z0-9-]+$/;
  * site instead of shipping prose into a code-switching consumer.
  *
  * @example
+ *   var bytes = Buffer.from([0x30, 0x80]);   // indefinite length -- not valid DER
  *   try { pki.asn1.decode(bytes); }
  *   catch (e) {
  *     if (e instanceof pki.errors.PkiError) console.error(e.code);
@@ -88,6 +89,7 @@ class PkiError extends Error {
  *   withCause:  boolean,  // default: false -- constructor becomes (code, message, cause)
  *
  * @example
+ *   // throws: my/bad-input -- raising the new error type IS what this shows
  *   var MyError = pki.errors.defineClass("MyError");
  *   throw new MyError("my/bad-input", "explanation");
  */
@@ -273,6 +275,16 @@ var CsrattrsError = defineClass("CsrattrsError", { withCause: true });
 // `.cause`.
 var EstError = defineClass("EstError", { withCause: true });
 
+// CmcError -- an RFC 5272 / 6402 Certificate Management over CMS message-layer
+// fault: a PKIData / PKIResponse whose structure, body-part identity, control
+// placement or status encoding is malformed, a control this side must act on
+// that cannot be decoded, or an exchange binding (transactionId / recipientNonce)
+// that does not match the request it answers. Distinct from EstError because the
+// CMC layer is the MESSAGE and EST is the TRANSPORT that carried it: an operator
+// needs to know whether the CA's answer was unreadable or the HTTP hop failed.
+// Carries the underlying cms/* or asn1/* leaf fault as `.cause`.
+var CmcError = defineClass("CmcError", { withCause: true });
+
 // TransportError -- a fault from the shared node:https transport (pki.transport):
 // a non-https / unparseable request URL, a missing trust anchor, a TLS handshake /
 // server-authentication failure, a negotiated protocol below the floor, a response
@@ -380,6 +392,7 @@ module.exports = {
   SmimeError:       SmimeError,
   CsrattrsError:    CsrattrsError,
   EstError:         EstError,
+  CmcError:         CmcError,
   TransportError:   TransportError,
   JoseError:        JoseError,
   AcmeError:        AcmeError,

package/lib/guard-bytes.js

@@ -57,4 +57,40 @@ function source(input, ErrorClass, code, label) {
   throw new ErrorClass(code, label + ": expected a BufferSource (ArrayBuffer / TypedArray / Buffer)");
 }
 
-module.exports = { view: view, source: source };
+// snapshot(input, ErrorClass, code, label) -> private Buffer copy | throws ErrorClass
+//
+// The parse-then-verify time-of-check/time-of-use defence. A verification entry
+// point that PARSES its input synchronously and then VERIFIES a signature over
+// the same bytes in a later promise turn is reading the caller's memory twice
+// with an await in between. Every byte range the parse surfaced -- the signed
+// content, the signer set, the values the verdict is built from -- is a VIEW into
+// that memory, so anything that rewrites the buffer in the gap makes the verdict
+// describe bytes other than the ones the signature was checked against
+// (CWE-367 TOCTOU reaching a CWE-347 wrong-verdict). The window is real without
+// an attacker in the process: a caller recycling a pooled read buffer across
+// concurrent verifies hits it by accident.
+//
+// So take one private copy at the boundary and read EVERYTHING from it. `view`
+// re-views and is the right guard where the input is consumed in one synchronous
+// pass; this is its sibling for the boundary that spans an await.
+// @enforced-by behavioral -- a copy has no rename-proof code shape to detect (any
+//   `Buffer.from(x)` is one, and most are legitimate). The guard is the RED vector
+//   that mutates the caller's buffer between parse and verify and asserts the
+//   verdict still describes the bytes that were verified.
+function snapshot(input, ErrorClass, code, label) {
+  return Buffer.from(view(input, ErrorClass, code, label));
+}
+
+// snapshotSource(input, ErrorClass, code, label) -> private Buffer copy | throws
+// The same parse-then-verify defence as `snapshot`, over the FULL W3C BufferSource
+// (raw ArrayBuffer / DataView / any typed-array view) rather than only the
+// Buffer / Uint8Array contract. A parser that accepts a BufferSource must snapshot
+// the same set: leaving an ArrayBuffer or a DataView aliased reopens the window for
+// exactly the inputs that took the wider path in.
+// @enforced-by behavioral -- a copy has no rename-proof shape to detect; the guard
+//   is the RED vector that mutates the caller's backing buffer across the await.
+function snapshotSource(input, ErrorClass, code, label) {
+  return Buffer.from(source(input, ErrorClass, code, label));
+}
+
+module.exports = { view: view, source: source, snapshot: snapshot, snapshotSource: snapshotSource };

package/lib/guard-range.js

@@ -99,4 +99,26 @@ function uint64(value, E, code, label) {
   return v;
 }
 
-module.exports = { int: int, uint31: uint31, positiveInt31: positiveInt31, uint64: uint64 };
+// authoredInteger(value, E, code, label) -> BigInt. The AUTHORING counterpart to
+// int(): a value a CALLER supplies for an ASN.1 INTEGER with no upper bound (a CMC
+// Transaction Identifier, a CRMF certReqId), normalized to the BigInt the builders
+// take. Accepts a bigint, or a Number that is a SAFE integer -- isSafeInteger, not
+// isInteger, because a Number above 2^53 has already lost precision by the time it
+// arrives, so a large identifier MUST come as a bigint rather than be silently
+// rounded to a neighbour. Everything else is a config-time reject.
+//
+// Distinct from int() on purpose: int() BOUNDS a value the wire decoded and narrows
+// it to Number; this one is unbounded and returns BigInt, because the field has no
+// ceiling to check against and the encoder wants the wide type.
+// @enforced-by guard-shape-reinlined
+// @guard-shape Number\.isSafeInteger\(\s*[A-Za-z_$][\w$]*\s*\)\s*\)\s*return BigInt
+function authoredInteger(value, E, code, label) {
+  if (typeof value === "bigint") return value;
+  if (typeof value === "number" && Number.isSafeInteger(value)) return BigInt(value);
+  throw E(code, label + " must be an integer (a safe-integer number, or a bigint for a large value)");
+}
+
+module.exports = {
+  int: int, uint31: uint31, positiveInt31: positiveInt31, uint64: uint64,
+  authoredInteger: authoredInteger,
+};

package/lib/http-transport.js

@@ -13,11 +13,17 @@
  *   drive -- `pki.est` now, `pki.acme` and `pki.cmp` next. This is the ONLY module in
  *   the toolkit that opens a socket; every protocol layer stays transport-agnostic and
  *   composes it (or an injected substitute) through one contract:
- *   `transport(request) -> Promise<{ status, headers, body }>`. The response triple is
+ *   `transport(request) -> Promise<{ status, headers, body, tls }>`. The first three are
  *   exactly what a message layer's classifier consumes, so no protocol semantics leak
  *   into the socket layer -- the transport owns socket lifecycle, the TLS trust policy,
  *   the streaming size cap, and the timeout budget; the caller owns HTTP status,
- *   content-type, redirect, and authentication decisions.
+ *   content-type, redirect, and authentication decisions. `tls` reports the negotiated
+ *   channel -- `{ protocol, cipher, peerCertificate }` -- which is the one fact a caller
+ *   cannot recover from the response bytes. An INJECTED substitute should return it too:
+ *   `pki.est.serverkeygen` asserts the negotiated cipher can protect the private key it
+ *   is about to accept, and a transport that reports no cipher is trusted rather than
+ *   refused (so a loopback test channel works), which means omitting the field silently
+ *   skips that assertion.
  *
  *   `pki.transport.https(defaults?)` binds TLS + budget defaults and returns a
  *   transport. Trust is EXPLICIT and fail-closed: a request is refused unless it
@@ -33,7 +39,7 @@
  * @card
  *   The shared fail-closed node:https transport (est / acme / cmp): explicit trust
  *   anchors, rejectUnauthorized always on, a TLS floor, a streaming response-size cap,
- *   and a timeout -- behind one `transport(request) -> {status, headers, body}` seam.
+ *   and a timeout -- behind one `transport(request) -> {status, headers, body, tls}` seam.
  */
 
 var nodeHttps = require("node:https");

package/lib/inspect.js

@@ -607,7 +607,7 @@ function _parse(input) {
  * @primitive pki.inspect.certificate
  * @signature pki.inspect.certificate(input) -> string
  * @since 0.2.4
- * @status experimental
+ * @status stable
  * @spec RFC 5280
  * @related pki.schema.x509.parse
  *
@@ -618,6 +618,10 @@ function _parse(input) {
  * hex dump rather than failing the whole report. Pure -- no OpenSSL dependency.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = await pki.x509.sign({ subject: "example.com", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   var cert = pki.schema.x509.parse(der);
  *   pki.inspect.certificate(cert).split("\n")[0]; // "Certificate:"
  */
@@ -753,7 +757,7 @@ function _crlExtension(ext, pad) {
  * @primitive pki.inspect.crl
  * @signature pki.inspect.crl(input) -> string
  * @since 0.3.8
- * @status experimental
+ * @status stable
  * @spec RFC 5280
  * @related pki.schema.crl.parse, pki.inspect.certificate
  *
@@ -765,6 +769,13 @@ function _crlExtension(ext, pad) {
  * extension renders as hex rather than failing the report.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var caCert = await pki.x509.sign({ subject: "Issuing CA", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { basicConstraints: { cA: true }, keyUsage: ["cRLSign"] } }, { key: key });
+ *   var crlDer = await pki.crl.sign({ thisUpdate: new Date("2026-01-01T00:00:00Z"), crlNumber: 1n, revoked: [] },
+ *     { cert: caCert, key: key });
  *   pki.inspect.crl(crlDer).split("\n")[0]; // "Certificate Revocation List (CRL):"
  */
 function crlReport(input) {
@@ -818,7 +829,7 @@ function _attribute(attr, pad) {
  * @primitive pki.inspect.csr
  * @signature pki.inspect.csr(input) -> string
  * @since 0.3.8
- * @status experimental
+ * @status stable
  * @spec RFC 2986
  * @related pki.schema.csr.parse, pki.inspect.certificate
  *
@@ -829,6 +840,9 @@ function _attribute(attr, pad) {
  * input `inspect/bad-input`. Best-effort like `certificate`.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var csrDer = await pki.csr.sign({ subject: "req.example", subjectPublicKey: await pki.key.export(pair.publicKey) },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   pki.inspect.csr(csrDer).split("\n")[0]; // "Certificate Request:"
  */
 function csrReport(input) {
@@ -927,7 +941,7 @@ function _signerInfo(si, pad) {
  * @primitive pki.inspect.cms
  * @signature pki.inspect.cms(input) -> string
  * @since 0.3.8
- * @status experimental
+ * @status stable
  * @spec RFC 5652
  * @related pki.schema.cms.parse, pki.inspect.certificate
  *
@@ -939,6 +953,11 @@ function _signerInfo(si, pad) {
  * `pki.schema.cms.parse` result; a non-CMS throws `inspect/bad-cms`. Best-effort.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var cert = await pki.x509.sign({ subject: "Signer", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: key });
+ *   var cmsDer = await pki.cms.sign(Buffer.from("hello"), { cert: cert, key: key });
  *   pki.inspect.cms(cmsDer).split("\n")[0]; // "CMS ContentInfo:"
  */
 // A ContentInfo whose content type pki.schema.cms.parse does not dispatch (id-data,
@@ -1003,7 +1022,7 @@ var _INSPECT_BY_FORMAT = { x509: certificate, crl: crlReport, csr: csrReport, cm
  * @primitive pki.inspect.any
  * @signature pki.inspect.any(input) -> string
  * @since 0.3.8
- * @status experimental
+ * @status stable
  * @spec RFC 5280
  * @related pki.schema.detectFormat, pki.inspect.certificate
  *
@@ -1015,6 +1034,10 @@ var _INSPECT_BY_FORMAT = { x509: certificate, crl: crlReport, csr: csrReport, cm
  * `inspect/bad-input`.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = await pki.x509.sign({ subject: "example.com", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   pki.inspect.any(der);  // routes to the right report by detected format
  */
 function any(input) {

package/lib/jose.js

@@ -327,7 +327,7 @@ function assertPublicJwk(jwk) {
 
 /**
  * @primitive  pki.jose.verify
- * @signature  pki.jose.verify(jws, opts) -> Promise<{ header, payload }>
+ * @signature  pki.jose.verify(jws, opts) -> Promise<{ header, payload, keySource }>
  * @since      0.1.25
  * @status     stable
  * @spec       RFC 7515, RFC 7518, RFC 8555
@@ -337,16 +337,31 @@ function assertPublicJwk(jwk) {
  * `"acme-outer"`). Structural rules fail closed BEFORE any crypto: the
  * `signatures`/`header` members and a detached payload are rejected, the
  * protected header is validated against the profile (alg registry, nonce, url,
- * exactly-one-of jwk/kid, crit), the signature byte length is pinned per alg, and
- * the verification key is the header `jwk` (only where the profile permits it) or
- * `opts.key` (a JWK). Returns the decoded `{ header, payload }` (payload a raw
- * `Buffer`); a failed signature throws `jose/verify-failed`.
+ * exactly-one-of jwk/kid, crit), and the signature byte length is pinned per alg.
+ *
+ * `opts.key` names the key the message must be signed under, and it governs: where
+ * the profile also permits an embedded header `jwk`, the two must be the SAME key
+ * or the message is refused with `jose/key-mismatch`. They are compared as RFC 7638
+ * thumbprints, so member order and members outside the key itself cannot make equal
+ * keys look different. Without `opts.key` the embedded `jwk` is used where the
+ * profile permits one -- which verifies that the message is internally consistent,
+ * not that any particular signer produced it. `keySource` reports which of the two
+ * answered, so a signature checked against a caller-named key is distinguishable
+ * from one checked against the key the message brought with it.
+ *
+ * Returns `{ header, payload, keySource }` (payload a raw `Buffer`); a failed
+ * signature throws `jose/verify-failed`.
  *
  * @opts
  *   profile: string   // "acme-outer" | "eab-inner" | "keychange-inner"
  *   key: object       // a public JWK, required unless the profile embeds jwk
  *
  * @example
+ *   var ec = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var accountJwk = await pki.webcrypto.subtle.exportKey("jwk", ec.publicKey);
+ *   var jws = await pki.jose.sign({ protected: { alg: "ES256", jwk: accountJwk,
+ *     nonce: "oFvnlFP1wIhRlYS2jTaXbA", url: "https://ca.example/acme/new-acct" },
+ *     payload: Buffer.from("{}"), key: ec.privateKey });
  *   var v = await pki.jose.verify(jws, { profile: "acme-outer", key: accountJwk });
  *   v.header.alg;   // -> "ES256"
  */
@@ -360,8 +375,38 @@ 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 || Array.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");
+  }
   var jwk = header.jwk || opts.key;
   if (!jwk) throw E("jose/bad-key", "a verification key is required (opts.key) when the profile does not embed a jwk");
+  var keySource = "embedded-jwk";
+  if (opts.key) {
+    keySource = "opts.key";
+    if (header.jwk) {
+      var embeddedTp, suppliedTp;
+      try { embeddedTp = await thumbprint(header.jwk); suppliedTp = await thumbprint(opts.key); }
+      catch (e) { throw E("jose/bad-key", "the embedded jwk and opts.key could not be compared as RFC 7638 thumbprints", e); }
+      if (embeddedTp !== suppliedTp) {
+        throw E("jose/key-mismatch",
+          "the JWS embeds a jwk that is not the key supplied as opts.key, so the message names a " +
+          "different signer than the caller expects (embedded thumbprint " + embeddedTp +
+          ", supplied " + suppliedTp + ")");
+      }
+    }
+    jwk = opts.key;
+  }
   _assertKeyType(checked.algRow, jwk);
   var sig = b64uDecode(jws.signature);
   var want = _expectedSigBytes(checked.algRow, jwk);
@@ -373,7 +418,10 @@ async function verify(jws, opts) {
   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");
-  return { header: header, payload: b64uDecode(jws.payload) };
+  // 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) ------------------------------
@@ -405,6 +453,10 @@ async function verify(jws, opts) {
  *   jwk: object          // the public JWK, when the header embeds jwk
  *
  * @example
+ *   var ec = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var priv = ec.privateKey;
+ *   var hdr = { alg: "ES256", jwk: await pki.webcrypto.subtle.exportKey("jwk", ec.publicKey),
+ *     nonce: "oFvnlFP1wIhRlYS2jTaXbA", url: "https://ca.example/acme/new-acct" };
  *   var jws = await pki.jose.sign({ protected: hdr, payload: Buffer.from("{}"), key: priv });
  */
 async function sign(opts) {
@@ -491,6 +543,12 @@ var THUMBPRINT_MEMBERS = {
  * always yields the same thumbprint (the ACME key-authorization anchor).
  *
  * @example
+ *   // the RFC 7638 sec. 3.1 worked example, so the thumbprint below is the spec's own
+ *   var accountJwk = { kty: "RSA", e: "AQAB", n: "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78L" +
+ *     "hWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXA" +
+ *     "rwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajr" +
+ *     "n1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-" +
+ *     "kEgU8awapJzKnqDKgw" };
  *   await pki.jose.thumbprint(accountJwk);   // -> "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs"
  */
 async function thumbprint(jwk) {

package/lib/lint.js

@@ -715,6 +715,10 @@ function _applyThreshold(report, severity) {
  * @opts  severity  Suppress findings below this floor (default `"notice"`). `counts` and
  *                  `worst` always reflect the complete, unfiltered result.
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var pemString = await pki.x509.sign({ subject: "example.com", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(pair.privateKey) }, { pem: true });
  *   var report = pki.lint.certificate(pemString);
  *   report.worst;                              // "notice" | "error" | ...
  *   report.findings.map(function (f) { return f.id; });

package/lib/merkle.js

@@ -102,7 +102,7 @@ function _ctEq(a, b) {
  * @primitive  pki.merkle.leafHash
  * @signature  pki.merkle.leafHash(entry) -> Buffer
  * @since      0.1.28
- * @status     experimental
+ * @status     stable
  * @spec       RFC 6962, RFC 9162
  * @related    pki.merkle.nodeHash, pki.merkle.verifyInclusion
  *
@@ -122,7 +122,7 @@ function leafHash(entry) {
  * @primitive  pki.merkle.nodeHash
  * @signature  pki.merkle.nodeHash(left, right) -> Buffer
  * @since      0.1.28
- * @status     experimental
+ * @status     stable
  * @spec       RFC 6962, RFC 9162
  * @related    pki.merkle.leafHash
  *
@@ -146,7 +146,7 @@ function nodeHash(left, right) {
  * @primitive  pki.merkle.emptyRootHash
  * @signature  pki.merkle.emptyRootHash() -> Buffer
  * @since      0.1.28
- * @status     experimental
+ * @status     stable
  * @spec       RFC 6962, RFC 9162
  * @related    pki.merkle.verifyConsistency
  *
@@ -164,7 +164,7 @@ function emptyRootHash() {
  * @primitive  pki.merkle.verifyInclusion
  * @signature  pki.merkle.verifyInclusion(opts) -> boolean
  * @since      0.1.28
- * @status     experimental
+ * @status     stable
  * @spec       RFC 6962, RFC 9162
  * @related    pki.merkle.leafHash, pki.merkle.verifyConsistency
  *
@@ -223,7 +223,7 @@ function verifyInclusion(opts) {
  * @primitive  pki.merkle.verifyConsistency
  * @signature  pki.merkle.verifyConsistency(opts) -> boolean
  * @since      0.1.28
- * @status     experimental
+ * @status     stable
  * @spec       RFC 6962, RFC 9162
  * @related    pki.merkle.verifyInclusion, pki.merkle.emptyRootHash
  *