@blamejs/pki 0.5.5 → 0.5.6

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.5.6 — 2026-08-16
+
+A CMS SignedData is verified over the bytes it was parsed from, an omitted PKCS#12 password is refused rather than encoded as the empty one, and a verb documented as returning a Promise rejects instead of throwing past your .catch.
+
+### Changed
+
+- A verb documented as returning a Promise now rejects; it never throws synchronously. An operator reads -> Promise<...> in the reference and writes the documented shape, pki.cms.sign(content, signers).catch(handleIt) -- and a validation that ran before the promise was created threw straight past that .catch, so a misspelled option or a malformed input became an uncaught exception in code that already handles errors. Nothing in the shape of the call said which verbs did it. Eleven did: pki.cms.verify, pki.cms.sign, pki.cms.countersign, pki.ocsp.sign, pki.tsp.sign, and six pki.acme verbs. Nine more on the client pki.acme.client(...) returns did the same, including getAuthorization, which an ordinary ACME loop reaches with a URL that came from the CA rather than from the caller. The checks still run synchronously, so a caller's mutable options are read before any turn passes; only the way a fault leaves has changed. If you wrapped one of these verbs in a synchronous try/catch without awaiting it -- which the documented signature never supported, but which worked by accident on exactly these verbs -- that catch no longer fires and the rejection surfaces as an unhandled one instead. Await the call, or attach .catch to it.
+- pki.tsp.verify reports whether revocation was established, not only whether the timestamp authority chained. Revocation runs only when a revocationChecker is supplied, so a token whose TSA was never checked against a CRL or an OCSP responder read identically to one established un-revoked -- and that is the default. The verdict now carries revocationChecked and anchorConstraints from the path validation, in pki.path.validate's own vocabulary, so a timestamp archived to be re-read years later can still answer what was actually checked. The trustAnchor documentation no longer lists revocation unconditionally.
+
+### Fixed
+
+- pki.cms.verify computes its verdict over the bytes the parser read. A SignedData's meaning is a signature over a byte range, but a parsed one presents that range, the signature, the algorithms and the certificates as separate properties, and the verb read them as though the parser had produced them together. The forgery that follows is concrete: take a message a trusted signer really signed, keep its SignerInfo and signature untouched, set signedAttrsBytes to null, and present the signature's own preimage -- the signed attributes re-tagged as the SET OF the signature covers -- as the encapsulated content under any content type you like. With no signed attributes the signature is checked against the content directly, which is exactly those bytes, and neither the content-type nor the message-digest check runs, so the message verifies as valid content the signer never signed. pki.schema.cms.parse now records what it read, pki.cms.verify re-derives from that record, and a SignedData a caller assembled rather than parsed is refused with a typed error instead of dereferenced into a raw TypeError. Passing DER, PEM, or the parser's own unmodified result is unaffected.
+- pki.pkcs12.build refuses a store with no password instead of building one under the empty password. An omitted password and the empty password are different credentials, and the difference was invisible at the call site: pki.pkcs12.build(spec) with no options at all, or with the option name misspelled, returned a well-formed store whose shrouded private key opened under "" -- a key protected by nothing, with no error anywhere. The empty password is still available; it has to be asked for, as "".
+- pki.pkcs12.build validates opts.integrity.mode against the value it accepts. Compared against a single literal, any other spelling read as "not public-key" and silently selected password integrity, dropping the signer with it: a caller who wrote mode: 'publicKey' asked for a CMS signature over the AuthenticatedSafe and got a password MAC. Combined with the previous item, a caller who misspelled both options got a store MACed under the empty password while believing it was signature-protected. An unrecognized key on opts.integrity is refused too.
+- pki.pkcs12.open bounds the key-derivation work of a modern store, not only a legacy one. The aggregate budget existed because a per-bag iteration cap resets on every bag, so a store that repeats a costly bag up to the parser's element limit multiplies the cap by that limit -- but it was charged only on the RFC 7292 Appendix C path, leaving the RFC 8018 PBES2 path -- the one OpenSSL and NSS emit, and the one this toolkit itself builds -- free to do exactly that. Measured before the fix: ten bags at a million iterations each ran ten million aggregate rounds of blocking PBKDF2 with no refusal. Both schemes now charge one budget, and it is charged before the derivation runs rather than after.
+- A PKCS#12 password this toolkit encoded is cleared once the derivation has consumed it, on the PBES2 and PBMAC1 paths as well as the classic ones. The Appendix B.1 copy taken from a password argument was wiped while the UTF-8 copy taken from the same argument in the same call was not, leaving a plaintext password in the heap after every modern bag encryption, bag decryption and MAC. A Buffer you supply is never written to: it is yours, and clearing it would destroy your credential rather than protect it.
+- pki.tsp.request validates a pre-encoded extension instead of splicing it in. Elements of opts.extensions were checked only for being byte-like and then concatenated straight into the request, so a caller relaying an extension blob it did not author put fully chosen bytes into the structure -- and the encoder emitted requests its own pki.tsp.parseRequest refuses: an undecodable value, a repeated extension identifier, an explicit critical=FALSE that DER requires be omitted. Each element now goes through the same pre-encoded-Extension gate every other request builder in the toolkit applies, including the duplicate-identifier check.
+- pki.tsp.sign, pki.tsp.request and pki.tsp.verify report a bad serial number or nonce as a typed tsp/bad-input. A value that is not an integer reached BigInt() directly and raised a raw SyntaxError or RangeError out of a public verb -- an untyped fault a caller handling tsp/* codes cannot catch.
+- pki.sigstore.verifyBundle refuses an option it does not recognize. The identity policy one level down already did, for the reason that applies just as much at the top: the signer pin goes by other names in other Sigstore tooling, and a spelling this verb swallowed checked nothing under a name the operator believed pinned the signer. At the top level the same slip also loses the SLSA predicate pin, and unlike the identity fields there is no report field to reveal it -- the verdict said verified: true with the signer and the predicate entirely unpinned.
+
 ## v0.5.5 — 2026-08-15
 
 A verdict is computed over the bytes the parser read, an identity is derived from the bytes that carry it, and the guards match no patterns.

package/MIGRATING.md

@@ -14,6 +14,47 @@ The toolkit has no `deprecate()`-marked surface awaiting removal.
 
 Listed newest-first.
 
+### v0.5.6 — `try { pki.<verb>(...) } catch`
+
+A verb documented `-> Promise` rejects on a bad input instead of throwing before the promise exists.
+
+If you awaited the call, or attached `.catch`, nothing changes and there is nothing to do.
+
+What changes is the undocumented shape: a synchronous `try`/`catch` that never consumed the
+returned promise.
+
+```js
+try {
+  pki.cms.verify(bytes);            // no await, no .catch
+} catch (e) { /* used to fire on a malformed input */ }
+```
+
+That `catch` no longer runs, and the rejection surfaces as an unhandled one. It worked by
+accident on exactly the verbs where a check happened to run before the promise existed --
+`pki.cms.verify`, `pki.cms.sign`, `pki.cms.countersign`, `pki.ocsp.sign`, `pki.tsp.sign`, six
+`pki.acme` verbs, and nine verbs on the client `pki.acme.client(...)` returns. Which verbs
+those were was not visible from the call, which is why they are now uniform.
+
+```js
+await pki.cms.verify(bytes);        // or pki.cms.verify(bytes).catch(handleIt)
+```
+
+### v0.5.6 — `pki.pkcs12.build(spec)`
+
+An omitted password is refused rather than encoded as the empty one.
+
+A store whose password option was missing or misspelled no longer builds silently under `""`.
+
+```js
+await pki.pkcs12.build(spec);                    // now pkcs12/bad-input
+await pki.pkcs12.build(spec, { password: "" });  // the empty password, asked for
+```
+
+If you were relying on the default, the second form restores the previous output byte for
+byte. `opts.integrity.mode` is validated the same way: a spelling other than `"public-key"`
+is now `pkcs12/bad-integrity-mode` instead of silently selecting password integrity and
+dropping the signer.
+
 ### v0.5.5 — `require("@blamejs/pki/lib/...")`
 
 The package resolves one entry point; a path into the package no longer resolves.

package/lib/acme.js

@@ -684,6 +684,12 @@ function _payloadBuf(obj) {
   if (obj === undefined) return Buffer.alloc(0);                 // POST-as-GET
   return Buffer.from(JSON.stringify(obj), "utf8");
 }
+// A verb documented `-> Promise` refuses by REJECTING, never by throwing (guard-async).
+//
+// The validation stays SYNCHRONOUS: these verbs read a caller's options object -- the key, the
+// nonce, the identifiers -- and resolving those before any turn passes is what stops a value being
+// swapped between the check and the use. Only the exit changes.
+var _promised = guard.async.deferred;
 function _signOuter(o, payloadObj) {
   if (!_isObject(o)) throw E("acme/bad-input", "a request options object is required");
   if (!o.key) throw E("acme/bad-input", "a signing key (opts.key) is required");
@@ -707,10 +713,12 @@ function _signOuter(o, payloadObj) {
  *   await pki.acme.postAsGet({ key, alg: "ES256", nonce, url: orderUrl, kid });
  */
 function postAsGet(o) {
-  if (!_isObject(o)) throw E("acme/bad-input", "a request options object is required");
-  // An authenticated read is ALWAYS kid-signed; copy only the kid-mode fields so a
-  // leftover jwk (e.g. reused from a newAccount options object) cannot embed a key.
-  return _signOuter({ key: o.key, alg: o.alg, nonce: o.nonce, url: o.url, kid: o.kid }, undefined);
+  return _promised(function () {
+    if (!_isObject(o)) throw E("acme/bad-input", "a request options object is required");
+    // An authenticated read is ALWAYS kid-signed; copy only the kid-mode fields so a
+    // leftover jwk (e.g. reused from a newAccount options object) cannot embed a key.
+    return _signOuter({ key: o.key, alg: o.alg, nonce: o.nonce, url: o.url, kid: o.kid }, undefined);
+  });
 }
 
 // A contact URL (RFC 8555 sec. 7.3): a `mailto:` addr-spec carries no header
@@ -750,6 +758,7 @@ function _assertContacts(contacts) {
  *   await pki.acme.newAccount({ key, alg: "ES256", nonce, url, jwk, termsOfServiceAgreed: true });
  */
 function newAccount(o) {
+  return _promised(function () {
   if (!_isObject(o) || !_isObject(o.jwk)) throw E("acme/bad-input", "newAccount must embed the account public jwk (RFC 8555 sec. 7.3)");
   var payload = {};
   if (o.contact !== undefined) { _assertContacts(o.contact); payload.contact = o.contact; }
@@ -769,6 +778,7 @@ function newAccount(o) {
     payload.externalAccountBinding = o.externalAccountBinding;
   }
   return jose.sign({ protected: { alg: o.alg, nonce: o.nonce, url: o.url, jwk: o.jwk }, payload: _payloadBuf(payload), key: o.key, jwk: o.jwk, profile: "acme-outer" });
+  });
 }
 
 var _HMAC_HASH = { HS256: "SHA-256", HS384: "SHA-384", HS512: "SHA-512" };
@@ -855,6 +865,7 @@ function _validateOrderIdentifier(id) {
  *   await pki.acme.newOrder({ key, alg: "ES256", nonce, url, kid, identifiers: [{ type: "dns", value: "example.org" }] });
  */
 function newOrder(o) {
+  return _promised(function () {
   if (!_isObject(o) || !Array.isArray(o.identifiers) || o.identifiers.length === 0) throw E("acme/bad-order", "newOrder requires a non-empty identifiers array (RFC 8555 sec. 7.4)");
   // Serialize the CANONICAL { type, value } each validator returns, never the caller's objects (which may carry
   // getter-backed / inherited fields JSON.stringify would drop, or extra enumerable fields it would send).
@@ -863,6 +874,7 @@ function newOrder(o) {
   if (o.notAfter !== undefined) { if (!_isRfc3339(o.notAfter)) throw E("acme/bad-order", "notAfter must be an RFC 3339 date-time"); payload.notAfter = o.notAfter; }
   if (o.replaces !== undefined) { if (!_isString(o.replaces)) throw E("acme/bad-order", "replaces must be an ARI certID string (RFC 9773 sec. 5)"); payload.replaces = o.replaces; }
   return _signOuter({ key: o.key, alg: o.alg, nonce: o.nonce, url: o.url, kid: o.kid }, payload);
+  });
 }
 
 /**
@@ -1035,10 +1047,12 @@ async function finalize(o) {
  *   await pki.acme.challengeResponse({ key, alg: "ES256", nonce, url: challUrl, kid });
  */
 function challengeResponse(o) {
-  if (!_isObject(o)) throw E("acme/bad-input", "a request options object is required");
-  var payload = o.payload !== undefined ? o.payload : {};
-  if (!_isObject(payload)) throw E("acme/bad-input", "a challenge response payload must be a JSON object (RFC 8555 sec. 7.5.1)");
-  return _signOuter({ key: o.key, alg: o.alg, nonce: o.nonce, url: o.url, kid: o.kid }, payload);
+  return _promised(function () {
+    if (!_isObject(o)) throw E("acme/bad-input", "a request options object is required");
+    var payload = o.payload !== undefined ? o.payload : {};
+    if (!_isObject(payload)) throw E("acme/bad-input", "a challenge response payload must be a JSON object (RFC 8555 sec. 7.5.1)");
+    return _signOuter({ key: o.key, alg: o.alg, nonce: o.nonce, url: o.url, kid: o.kid }, payload);
+  });
 }
 
 /**
@@ -1061,8 +1075,10 @@ function challengeResponse(o) {
  *   await pki.acme.deactivate({ key, alg: "ES256", nonce, url: authzUrl, kid });
  */
 function deactivate(o) {
-  if (!_isObject(o)) throw E("acme/bad-input", "a request options object is required");
-  return _signOuter({ key: o.key, alg: o.alg, nonce: o.nonce, url: o.url, kid: o.kid }, { status: "deactivated" });
+  return _promised(function () {
+    if (!_isObject(o)) throw E("acme/bad-input", "a request options object is required");
+    return _signOuter({ key: o.key, alg: o.alg, nonce: o.nonce, url: o.url, kid: o.kid }, { status: "deactivated" });
+  });
 }
 
 /**
@@ -1091,6 +1107,7 @@ function deactivate(o) {
  *   await pki.acme.revokeCert({ key, alg: "ES256", nonce, url, kid, certificate: certDer, reason: 1 });
  */
 function revokeCert(o) {
+  return _promised(function () {
   if (!_isObject(o) || !Buffer.isBuffer(o.certificate)) throw E("acme/bad-input", "revokeCert requires a DER certificate Buffer (opts.certificate)");
   x509.parse(o.certificate);                              // structural validation of the target
   var hasKid = Object.prototype.hasOwnProperty.call(o, "kid");
@@ -1106,6 +1123,7 @@ function revokeCert(o) {
   var header = { alg: o.alg, nonce: o.nonce, url: o.url };
   if (hasKid) header.kid = o.kid; else header.jwk = o.jwk;
   return jose.sign({ protected: header, payload: _payloadBuf(payload), key: o.key, jwk: o.jwk, profile: "acme-outer" });
+  });
 }
 
 /**
@@ -2015,12 +2033,18 @@ function client(directoryUrl, opts) {
     });
     });
   }
-  function _getOrder(url) { return _postAsGet(_clientUrl(url)).then(function (res) { return validate("order", _json(res)); }); }
-  function _getAuthorization(url) { return _postAsGet(_clientUrl(url)).then(function (res) { return validate("authorization", _json(res)); }); }
-  function _getChallenge(url) { return _postAsGet(_clientUrl(url)).then(function (res) { return validate("challenge", _json(res)); }); }
-  function _respondToChallenge(url) { return _post(_clientUrl(url), challengeResponse, null, "kid").then(function (res) { return validate("challenge", _json(res)); }); }
-
-  function _finalize(order, o) {
+  // A bad URL leaves as a REJECTION, like every other verb on this client. It is not only a caller
+  // typo that reaches here: the message layer deliberately accepts http as well as https, so an
+  // order whose `authorizations` array carries an http URL validates, and the very next step --
+  // getAuthorization(order.authorizations[0]) -- threw out of the middle of an async ACME loop
+  // rather than rejecting into the handler already wrapped around it.
+  function _getOrder(url) { return _promised(function () { return _postAsGet(_clientUrl(url)).then(function (res) { return validate("order", _json(res)); }); }); }
+  function _getAuthorization(url) { return _promised(function () { return _postAsGet(_clientUrl(url)).then(function (res) { return validate("authorization", _json(res)); }); }); }
+  function _getChallenge(url) { return _promised(function () { return _postAsGet(_clientUrl(url)).then(function (res) { return validate("challenge", _json(res)); }); }); }
+  function _respondToChallenge(url) { return _promised(function () { return _post(_clientUrl(url), challengeResponse, null, "kid").then(function (res) { return validate("challenge", _json(res)); }); }); }
+
+  function _finalize(order, o) { return _promised(function () { return _finalizeBody(order, o); }); }
+  function _finalizeBody(order, o) {
     o = o || {};
     if (!_isObject(order) || !_isString(order.finalize)) throw E("acme/bad-input", "finalize requires the order object with its finalize URL");
     if (!Array.isArray(order.identifiers)) throw E("acme/bad-input", "finalize requires the order's identifiers to enforce the RFC 8555 sec. 7.4 CSR-set match");
@@ -2155,10 +2179,11 @@ function client(directoryUrl, opts) {
     });
   }
 
-  function _deactivateAccount() { return _post(_requireKid(), deactivate, null, "kid").then(function (res) { return validate("account", _json(res)); }); }
-  function _deactivateAuthorization(url) { return _post(_clientUrl(url), deactivate, null, "kid").then(function (res) { return validate("authorization", _json(res)); }); }
+  function _deactivateAccount() { return _promised(function () { return _post(_requireKid(), deactivate, null, "kid").then(function (res) { return validate("account", _json(res)); }); }); }
+  function _deactivateAuthorization(url) { return _promised(function () { return _post(_clientUrl(url), deactivate, null, "kid").then(function (res) { return validate("authorization", _json(res)); }); }); }
 
-  function _keyChange(o) {
+  function _keyChange(o) { return _promised(function () { return _keyChangeBody(o); }); }
+  function _keyChangeBody(o) {
     o = o || {};
     if (!o.newKey || !_isObject(o.newJwk) || !_isString(o.newAlg)) throw E("acme/bad-input", "keyChange requires newKey, newJwk, and newAlg");
     var account = _requireKid();
@@ -2181,6 +2206,9 @@ function client(directoryUrl, opts) {
 
   // ARI RenewalInfo (RFC 9773 sec. 4.1) -- the SOLE UNAUTHENTICATED GET (no JWS, no nonce).
   function _renewalInfo(certDer, clockFn, retryAfterCapSeconds) {
+    return _promised(function () { return _renewalInfoBody(certDer, clockFn, retryAfterCapSeconds); });
+  }
+  function _renewalInfoBody(certDer, clockFn, retryAfterCapSeconds) {
     if (!Buffer.isBuffer(certDer)) throw E("acme/bad-input", "renewalInfo requires a DER certificate Buffer");
     var _rawClk = typeof clockFn === "function" ? clockFn : clock;   // renewalWindow may pass a per-call clock
     // The clock MUST return finite epoch ms: a NaN / Infinity would make the expiry comparison below silently

package/lib/cms-sign.js

@@ -337,7 +337,13 @@ function _pemToDer(text) {
 }
 
 // pki.cms.sign -- documented by the @primitive block in cms-verify.js (the @module pki.cms home).
+// Documented `-> Promise`, so a fault leaves as a REJECTION (guard-async); the checks stay
+// synchronous because they read the caller's mutable content and signer list.
 function sign(content, signers, opts) {
+  return guard.async.deferred(function () { return _sign(content, signers, opts); });
+}
+
+function _sign(content, signers, opts) {
   opts = opts || {};
   if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("cms/bad-input", "pki.cms.sign options must be an object");
   var contentBuf = _toBuf(content, "content");
@@ -533,7 +539,12 @@ function _targetPreimage(siNode, opts) {
 }
 
 // pki.cms.countersign -- documented by the @primitive block in cms-verify.js (the @module pki.cms home).
+// Documented `-> Promise`, so a fault leaves as a REJECTION (guard-async).
 function countersign(cmsInput, signers, opts) {
+  return guard.async.deferred(function () { return _countersign(cmsInput, signers, opts); });
+}
+
+function _countersign(cmsInput, signers, opts) {
   opts = opts || {};
   if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("cms/bad-input", "pki.cms.countersign options must be an object");
   var list = Array.isArray(signers) ? signers : [signers];

package/lib/cms-verify.js

@@ -538,7 +538,10 @@ function _surfaceUnsignedAttrs(si) {
 // Verify every countersignature attached to `si` (RFC 5652 sec. 11.4): each id-countersignature
 // value is a SignerInfo over `si`'s signature octets. Returns per-countersignature verdicts; a
 // countersignature's OWN countersignatures verify over ITS signature octets (recursive). A
-// present-but-invalid countersignature is surfaced ok:false -- never silently dropped. The recursion
+// countersignature that FAILS TO VERIFY is surfaced ok:false -- never silently dropped, and never
+// allowed to change the primary verdict. A countersignature value that is not a well-formed
+// SignerInfo does not reach here at all: the decoder validates every id-countersignature value by
+// content rather than on the attribute type, so such a message is refused whole. The recursion
 // terminates because it only walks the FINITE parsed structure: each nested countersignature value
 // is a sub-encoding of its parent, and the strict decoder already bounds total nesting by
 // C.LIMITS.DER_MAX_DEPTH at parse (CWE-834/770), so a hostile deep chain fails closed before verify.
@@ -650,7 +653,14 @@ function _snapshotIfBytes(input, label) {
 // capability cannot arrive with its option silently ignored at this boundary.
 var _VERIFY_OPTS = { certs: 1, content: 1, trustAnchors: 1, time: 1, requiredEku: 1, checkPurpose: 1 };
 
+// Documented `-> Promise`, so a fault leaves as a REJECTION (guard-async). The checks below stay
+// synchronous -- they read a caller's mutable options and bytes, and resolving those before any turn
+// passes is what stops a value being swapped between the check and the use.
 function verify(input, opts) {
+  return guard.async.deferred(function () { return _verify(input, opts); });
+}
+
+function _verify(input, opts) {
   opts = opts || {};
   if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("cms/bad-input", "pki.cms.verify options must be an object");
   // An unrecognized option is refused, not swallowed. This is what kept the missing trust seam
@@ -663,13 +673,17 @@ function verify(input, opts) {
   // the parse surfaced -- the signed content above all -- stays a view into the
   // caller's memory across that await, and a buffer rewritten in the gap would leave
   // the result describing one message while the signature was checked over another.
-  // Only a Buffer / Uint8Array can change underneath us: a PEM string is immutable
-  // and passes through untouched, and an already-parsed object is a lifetime the
-  // caller chose. Narrow rather than blanket, so neither input form is refused here
-  // that pki.cms.parse itself accepts.
-  var parsed = (input && typeof input === "object" && !Buffer.isBuffer(input) && Array.isArray(input.signerInfos))
-    ? input
-    : cms.parse(_snapshotIfBytes(input, "pki.cms.verify"));
+  // Re-derived from the bytes the parser read, never trusted as the object it arrives as. A
+  // SignedData's meaning is a signature over a byte range, but a parsed one presents that range
+  // (`signedAttrsBytes`, or the encapsulated `eContent` when there are no signed attributes), the
+  // signature, the algorithms and the certificates as SEPARATE properties. Keep a genuine signer's
+  // signature and signed attributes and put different content beside them and every part of this
+  // check passes for a message that signer never signed -- the forgery this verb's own block claims
+  // to defend (CWE-347). A duck-type test on `signerInfos` cannot see that, because every field is
+  // individually well-formed; only re-deriving them all from one byte string can.
+  var parsed = guard.parsed.acceptDerived(input, "cms", function (bytes) {
+    return cms.parse(_snapshotIfBytes(bytes, "pki.cms.verify"));
+  }, _err, "cms/bad-input", "the SignedData");
   if (!Array.isArray(parsed.signerInfos)) throw _err("cms/bad-input", "input is not a CMS SignedData");
   var content = parsed.encapContentInfo.eContent;
   if (content == null) {

package/lib/guard-all.js

@@ -65,6 +65,7 @@ var header = require("./guard-header");
 var compress = require("./guard-compress");
 var secret = require("./guard-secret");
 var parsed = require("./guard-parsed");
+var async_ = require("./guard-async");
 
 module.exports = {
   bytes:  bytes,
@@ -81,4 +82,5 @@ module.exports = {
   compress: compress,
   secret: secret,
   parsed: parsed,
+  async:  async_,
 };

package/lib/guard-async.js

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal -- no operator-facing namespace. The documented surface is every verb whose
+// @signature says `-> Promise<...>`; this is how each of them refuses.
+//
+// guard-async -- a verb documented as Promise-returning refuses by REJECTING, never by throwing.
+//
+// The failure is invisible at the call site, which is what makes it worth a choke point. An operator
+// reads `-> Promise<...>` in the reference and writes the documented shape:
+//
+//     pki.acme.newOrder(opts).catch(handleIt);
+//
+// A validation that runs BEFORE the promise is created throws straight past that `.catch`, so a
+// misspelled option or a malformed input becomes an uncaught exception in code that already handles
+// errors -- and nothing in the shape of the call tells the caller which verbs do that. Eleven verbs
+// across five modules had it (pki.cms.verify / sign / countersign, pki.ocsp.sign, pki.tsp.sign and
+// six pki.acme verbs), each having grown the same way: a cheap synchronous check added at the top of
+// a function that returns a promise further down.
+//
+// What this does NOT change is WHEN the work happens. The body still runs synchronously, because
+// several of these verbs must resolve a caller's mutable options object before any turn passes --
+// reading a key, a nonce, or a request's bytes a turn later is a different value than the one that
+// was checked. Only the exit changes: a fault leaves as a rejection instead of a throw.
+//
+// @enforced-by behavioral -- the rule has no rename-proof code shape (it is the ABSENCE of a wrapper
+//   around a synchronous prefix, which no lexical pattern can see). The guard is the derived test
+//   test/layer-0-primitives/promise-contract.test.js, which reads every `-> Promise<` @signature out
+//   of lib/ and calls each verb to prove the refusal arrives as a rejection -- so a new verb is in
+//   scope the day it is documented, and no list here can go stale.
+function deferred(body) {
+  try { return Promise.resolve(body()); }
+  catch (e) { return Promise.reject(e); }
+}
+
+module.exports = { deferred: deferred };

package/lib/guard-parsed.js

@@ -342,12 +342,45 @@ function recordingParser(kind, parse, ErrorClass, code, label) {
   };
 }
 
-// The recorded bytes for `obj`, or undefined. @internal to this module: touches no
+// recordingWalker(kind, walkNode, decodeBytes) -> function (node) -> the walked structure.
+//
+// The recordingParser sibling for a producer handed an already-DECODED node rather than bytes.
+// One structure needs it: the RFC 7292 authSafe's SignedData. A PFX is decoded BER-tolerantly
+// because real stores carry the indefinite-length encoding, so its inner SignedData cannot be
+// re-derived by the strict `parse` entry the byte doors use -- that entry would refuse a store
+// this toolkit accepts today. The record therefore names the bytes AND how to walk them again.
+//
+// The same three properties hold as for recordingParser, and for the same reasons. The record can
+// only be obtained by actually running the walk, so no code can assert provenance for a structure
+// it did not produce. The recorded bytes are a private COPY of the node's, because the walked
+// result surfaces views onto the buffer the PFX was decoded from and a caller holding one could
+// otherwise write through it into the very bytes the record names. And `derive` re-runs THIS
+// walker over that copy, so a re-derivation reproduces the structure exactly -- the decode is the
+// producer's own, never a stricter one substituted at the door.
+//
+// @enforced-by guard-shape-reinlined -- shares recordingParser's shape below: the PROVENANCE.set
+//   that binds a structure to the bytes it was derived from appears only in this module, so no
+//   producer elsewhere can mint a record for a structure it did not itself walk.
+function recordingWalker(kind, walkNode, decodeBytes) {
+  return function (node) {
+    var out = walkNode(node);
+    if (out && typeof out === "object" && node && _isBytes(node.bytes)) {
+      PROVENANCE.set(out, {
+        kind: kind,
+        source: Buffer.from(node.bytes),
+        derive: function (src) { return walkNode(decodeBytes(src)); },
+      });
+    }
+    return out;
+  };
+}
+
+// The provenance record for `obj`, or undefined. @internal to this module: touches no
 // property of `obj` at all -- the lookup is on the object's identity.
-function _sourceOf(obj, kind) {
+function _recordOf(obj, kind) {
   if (!obj || typeof obj !== "object") return undefined;
   var rec = PROVENANCE.get(obj);
-  return (rec && rec.kind === kind) ? rec.source : undefined;
+  return (rec && rec.kind === kind) ? rec : undefined;
 }
 
 // fromTrustedSource(input, kind, claimFields, parse, E, code, why) -> the parsed
@@ -368,8 +401,10 @@ function _sourceOf(obj, kind) {
 // @guard-via guard\.parsed\.(?:fromTrustedSource|recordingParser)\(
 function fromTrustedSource(input, kind, claimFields, parse, E, code, why) {
   if (input && typeof input === "object" && !_isBytes(input)) {
-    var source = _sourceOf(input, kind);
-    if (source !== undefined) return parse(source);
+    // A structure the walker recorded carries its own way back; the byte doors re-derive with the
+    // parser they were given.
+    var rec = _recordOf(input, kind);
+    if (rec !== undefined) return (rec.derive || parse)(rec.source);
     for (var i = 0; i < claimFields.length; i++) {
       // A claim field can be an accessor that throws; a guard answers, it does not relay.
       var claims;
@@ -404,10 +439,12 @@ function fromTrustedSource(input, kind, claimFields, parse, E, code, why) {
 var _CLAIMS = {
   certificate: ["tbsBytes", "subjectPublicKeyInfo", "serialNumberHex"],
   crl: ["tbsBytes", "revokedCertificates", "crlExtensions"],
+  cms: ["signerInfos", "encapContentInfo"],
 };
 var _WHY = {
   certificate: "the signed byte range, the signature and the fields that range encodes are separate properties of a parsed object, so a REBUILT certificate (Object.assign, spread, a JSON round-trip) could have them describe different certificates -- keep a real CA certificate's signed bytes and signature and replace only its public key and every field is still well-formed",
   crl: "the signed byte range, the revocation list and the scope extensions are separate properties of a parsed object, so a REBUILT CRL could have them describe different CRLs -- empty the revocation list and a correctly signed CRL reports a revoked certificate as good",
+  cms: "the signed attribute bytes, the signature, the encapsulated content and the certificates that verify it are separate properties of a parsed object, so a REBUILT SignedData could have them describe different messages -- keep a genuine signer's signature and signed attributes and put other content beside them, and every part of the check passes for content that signer never signed",
 };
 // @enforced-by guard-shape-reinlined -- shares the fromTrustedSource shape it composes: a door that
 //   tests the claim fields itself, rather than routing here, is the re-inline both replace.
@@ -431,13 +468,15 @@ function acceptDerived(input, kind, parse, E, code, label) {
       throw E(code, who + " must be a " + kind + " DER Buffer, a PEM string, or a parsed " + kind);
     }
   }
+  var ns = { certificate: "x509", crl: "crl", cms: "cms" }[kind];
   return fromTrustedSource(input, kind, claims, parse, E, code,
-    who + " must be its DER bytes, a PEM string, or an unmodified pki.schema." +
-    (kind === "crl" ? "crl" : "x509") + ".parse result: " + _WHY[kind]);
+    who + " must be its DER bytes, a PEM string, or an unmodified pki.schema." + ns +
+    ".parse result: " + _WHY[kind]);
 }
 
 module.exports = {
   accept: accept, acceptDerived: acceptDerived,
   fromTrustedSource: fromTrustedSource, recordingParser: recordingParser,
+  recordingWalker: recordingWalker,
   isCert: certShape, isCrl: crlShape,
 };

package/lib/ocsp.js

@@ -256,7 +256,13 @@ function _normCertDer(cert, what) {
  *     { responderID: "byName", responses: [{ cert: leafDer, issuer: caDer, status: "good" }] },
  *     { cert: responderCertDer, key: responderPkcs8 });
  */
+// Documented `-> Promise`, so a fault leaves as a REJECTION (guard-async); the checks stay
+// synchronous because they read the responder's mutable cert and key.
 function sign(responseData, responder, opts) {
+  return guard.async.deferred(function () { return _sign(responseData, responder, opts); });
+}
+
+function _sign(responseData, responder, opts) {
   opts = opts || {};
   responseData = responseData || {};
   if (!responder || responder.cert == null || responder.key == null) throw _err("ocsp/bad-input", "a responder must be { cert, key }");

package/lib/pbes2.js

@@ -177,7 +177,12 @@ function pbes2Encrypt(pwBytes, plaintext, opts, E, prefix) {
 // <prefix>/bad-input a param guard raises is normalized to the structural <prefix>/bad-algorithm-parameters.
 // A wrong key / bad PKCS#7 pad collapses to the UNIFORM <prefix>/decrypt-failed (RFC 8018 sec. 8). The
 // plaintext integrity re-check (re-parse as a PrivateKeyInfo / SafeContents) is the CALLER's step.
-function pbes2Decrypt(pwBytes, params, ciphertext, opts, E, prefix) {
+// `budget` (optional) is a shared { rounds } tally a caller decrypting MANY structures under one
+// call charges against, so the per-structure iteration cap cannot simply reset each time: PBKDF2
+// runs on the event loop, and a store that repeats a costly bag up to the parser's element limit
+// otherwise multiplies the cap by that limit. A caller decrypting exactly one structure passes
+// nothing and is bounded by the cap alone.
+function pbes2Decrypt(pwBytes, params, ciphertext, opts, E, prefix, budget) {
   var keyBits, iv, pb;
   try {
     var p = seqChildren(params, 2, "PBES2 parameters", E, prefix);
@@ -197,6 +202,11 @@ function pbes2Decrypt(pwBytes, params, ciphertext, opts, E, prefix) {
     }
     throw E(prefix + "/bad-algorithm-parameters", "malformed PBES2 parameters", e);
   }
+  // Charge the shared budget BEFORE deriving, so the work is refused rather than performed.
+  if (budget) {
+    budget.rounds -= pb.iterations;
+    if (budget.rounds < 0) throw E(prefix + "/iteration-limit", "the aggregate PBKDF2 key-derivation work exceeds the budget (a hostile many-element input)");
+  }
   var dk = nodeCrypto.pbkdf2Sync(pwBytes, pb.salt, pb.iterations, keyBits / 8, pb.prfNode);
   try { return cbcDecrypt(dk, iv, ciphertext, keyBits); }
   catch (_e) { throw E(prefix + "/decrypt-failed", "decryption failed"); }

package/lib/pkcs12-build.js

@@ -69,12 +69,14 @@ var MAX_PBMAC1_KEYLEN = 1024;   // an HMAC key beyond a hash block is pointless
 // pkcs12-local (its KDF is bespoke here) while PBMAC1 reuses the toolkit-wide PBKDF2 ceiling. 1e6 is ~500x
 // the OpenSSL default (2048) yet still bounds the loop to ~1 second.
 var CLASSIC_MAC_MAX_ITERATIONS = 1000000;
-// The AGGREGATE cap on synchronous legacy-PBE App. B KDF work across a single open() -- SHA-1 rounds summed
-// over every legacy bag (its KDF block count x iterations). The per-bag iteration cap resets per bag, so a
-// hostile store that duplicates a costly legacy bag up to the parser's 1024-bag limit would otherwise block
-// the event loop for minutes; this bounds the total to ~the classic MAC ceiling. A conforming store runs only
-// a few thousand rounds (its handful of bags at ~2048 iterations).
-var LEGACY_KDF_MAX_ROUNDS = CLASSIC_MAC_MAX_ITERATIONS;
+// The AGGREGATE cap on synchronous KDF work across a single open() -- rounds summed over every encrypted
+// bag and safe, whichever scheme it uses: the legacy App. B KDF (its block count x iterations) and PBKDF2
+// alike. The per-bag iteration cap resets per bag, so a hostile store that duplicates a costly bag up to the
+// parser's 1024-element limit would otherwise block the event loop for minutes; this bounds the total to
+// ~the classic MAC ceiling. It covers BOTH schemes because covering only the legacy one left the modern
+// path -- the one every current producer emits -- free to multiply its cap by the element limit.
+// A conforming store runs only a few thousand rounds (its handful of bags at ~2048 iterations).
+var KDF_MAX_ROUNDS = CLASSIC_MAC_MAX_ITERATIONS;
 
 // The classic App. B.2 KDF (u = hash output bytes, v = compression block bytes) per RFC 7292 App. B.2.
 var P12_KDF_UV = {
@@ -102,6 +104,18 @@ var DIGEST_NAME = { sha1: "sha1", sha256: "sha256", sha384: "sha384", sha512: "s
 // is taken verbatim as already-formatted bytes (an escape hatch for a caller that pre-encodes).
 function _p12Password(pw) { return _p12PasswordOwned(pw).bytes; }
 
+// An ABSENT password is refused rather than encoded as the empty one. The two are not the same
+// credential, and the difference is invisible at the call site: a caller who misspells the option,
+// or threads it through a layer that drops it, otherwise gets a store whose private key is
+// protected by nothing and no error anywhere saying so. The empty password remains available --
+// it just has to be asked for, as "".
+var _MISSING_PASSWORD = "a password must be a string, Buffer, or Uint8Array -- an omitted password " +
+  "is not the empty password; pass \"\" to use the empty one deliberately";
+
+// Every field opts.integrity reads. Adding one here is the only way to make it accepted, so a
+// capability cannot arrive with its option silently ignored at this boundary.
+var _INTEGRITY_OPTS = { mode: 1, signer: 1, signers: 1, certificates: 1, sid: 1, signingTime: 1 };
+
 // The same encoding, reporting OWNERSHIP -- mirroring pbes2.passwordBytesOwned. A caller-supplied
 // Buffer is returned AS-IS and is BORROWED: clearing it would destroy the caller's own credential,
 // which is a worse defect than leaving a copy readable. Every other input is re-encoded into a
@@ -111,10 +125,9 @@ function _p12PasswordOwned(pw) {
   return { bytes: _p12Encode(pw), owned: true };
 }
 function _p12Encode(pw) {
-  if (pw == null) pw = "";
   if (Buffer.isBuffer(pw)) return pw;
   if (pw instanceof Uint8Array) return Buffer.from(pw);
-  if (typeof pw !== "string") throw _err("pkcs12/bad-input", "a password must be a string, Buffer, or Uint8Array");
+  if (typeof pw !== "string") throw _err("pkcs12/bad-input", _MISSING_PASSWORD);
   var out = Buffer.alloc(pw.length * 2 + 2);   // + the 2-byte NULL terminator
   for (var i = 0; i < pw.length; i++) {
     var u = pw.charCodeAt(i);
@@ -130,12 +143,19 @@ function _p12Encode(pw) {
 // PBKDF2 the raw UTF-8 password for these modern schemes (confirmed byte-for-byte against `openssl pkcs12`),
 // reserving the BMPString+NULL form for the bespoke Appendix B KDF only. A file we emit must open in OpenSSL,
 // so the modern schemes use UTF-8 here; only the classic Appendix B MAC uses `_p12Password`.
-function _pbePassword(pw) {
-  if (pw == null) pw = "";
-  if (Buffer.isBuffer(pw)) return pw;
-  if (pw instanceof Uint8Array) return Buffer.from(pw);
-  if (typeof pw !== "string") throw _err("pkcs12/bad-input", "a password must be a string, Buffer, or Uint8Array");
-  return Buffer.from(pw, "utf8");
+// The UTF-8 encoding, reporting OWNERSHIP -- the sibling of _p12PasswordOwned, and it exists
+// for the same reason. A caller-supplied Buffer is BORROWED and left alone; every other input is
+// re-encoded into a buffer this module allocated, and a plaintext password copy this module made
+// is cleared once the derivation has consumed it. Without it the App. B.1 copy taken from the same
+// argument in the same call was wiped while this one was not.
+function _pbePasswordOwned(pw) {
+  if (Buffer.isBuffer(pw)) return { bytes: pw, owned: false };
+  if (pw instanceof Uint8Array) return { bytes: Buffer.from(pw), owned: true };
+  if (typeof pw !== "string") throw _err("pkcs12/bad-input", _MISSING_PASSWORD);
+  return { bytes: Buffer.from(pw, "utf8"), owned: true };
+}
+function _wipePw(owned) {
+  if (owned.owned) guard.secret.zeroize(owned.bytes, Pkcs12Error, "pkcs12/bad-input", "the password encoding");
 }
 
 // Concatenate copies of `src` to the smallest positive multiple of `blockSize` (>= src length), truncating
@@ -267,8 +287,10 @@ function _buildBag(bag, opts, depth) {
       var kDer = _coerceDer(bag.key, "shroudedKey key");
       try { pkcs8.parse(kDer); } catch (e2) { throw _err("pkcs12/bad-input", "shroudedKey key is not a well-formed PKCS#8 PrivateKeyInfo", e2); }
       var enc = bag.encrypt || {};
-      var pw = _pbePassword(enc.password != null ? enc.password : opts.password);
-      var r = pbes2.pbes2Encrypt(pw, kDer, _pbeOpts(enc), _err, "pkcs12");
+      var pw = _pbePasswordOwned(enc.password != null ? enc.password : opts.password);
+      var r;
+      try { r = pbes2.pbes2Encrypt(pw.bytes, kDer, _pbeOpts(enc), _err, "pkcs12"); }
+      finally { _wipePw(pw); }
       return _safeBag("pkcs8ShroudedKeyBag", b.sequence([r.algId, b.octetString(r.ct)]), bag);   // EncryptedPrivateKeyInfo
     }
     case "cert": {
@@ -376,8 +398,10 @@ async function _buildAuthSafeElement(sc, opts) {
     return b.sequence([b.oid(O("data")), b.explicit(0, b.octetString(safeContentsDer))]);
   }
   if (!sc.encrypt || typeof sc.encrypt !== "object") throw _err("pkcs12/bad-input", "safeContents.encrypt must be an object { password? } (RFC 7292 sec. 5.1) -- omit it entirely for a plaintext safe");
-  var pw = _pbePassword(sc.encrypt.password != null ? sc.encrypt.password : opts.password);
-  var r = pbes2.pbes2Encrypt(pw, safeContentsDer, _pbeOpts(sc.encrypt), _err, "pkcs12");
+  var pw = _pbePasswordOwned(sc.encrypt.password != null ? sc.encrypt.password : opts.password);
+  var r;
+  try { r = pbes2.pbes2Encrypt(pw.bytes, safeContentsDer, _pbeOpts(sc.encrypt), _err, "pkcs12"); }
+  finally { _wipePw(pw); }
   var eci = b.sequence([b.oid(O("data")), r.algId, b.contextPrimitive(0, r.ct)]);   // EncryptedContentInfo, [0] IMPLICIT ct
   var encData = b.sequence([b.integer(0n), eci]);                                    // EncryptedData { version 0, eci }
   return b.sequence([b.oid(O("encryptedData")), b.explicit(0, encData)]);
@@ -420,7 +444,10 @@ async function _buildMacData(macOpts, sharedPassword, authSafeDer) {
     var iter2 = _assertMacIter(macOpts.iterations == null ? DEFAULT_PBMAC1_ITER : macOpts.iterations, C.LIMITS.PBKDF2_MAX_ITERATIONS);
     var keyLen = macOpts.keyLength != null ? macOpts.keyLength : prf.keyLen;
     if (typeof keyLen !== "number" || !Number.isInteger(keyLen) || keyLen < 20 || keyLen > MAX_PBMAC1_KEYLEN) throw _err("pkcs12/bad-input", "PBMAC1 keyLength must be an integer in [20, " + MAX_PBMAC1_KEYLEN + "] (RFC 9579 sec. 9)");
-    var mac = await pbes2.pbmac1(_pbePassword(password), salt, iter2, keyLen, prf.wc, prf.wc, authSafeDer);   // PBKDF2 -> UTF-8; prf == messageAuthScheme on build
+    var macPw2 = _pbePasswordOwned(password);
+    var mac;
+    try { mac = await pbes2.pbmac1(macPw2.bytes, salt, iter2, keyLen, prf.wc, prf.wc, authSafeDer); }   // PBKDF2 -> UTF-8; prf == messageAuthScheme on build
+    finally { _wipePw(macPw2); }
     var desc = { salt: salt, iterationCount: iter2, keyLength: keyLen, prfName: prf.prfName, macName: prf.prfName };
     var digestInfo2 = b.sequence([pbes2.pbmac1AlgId(desc), b.octetString(mac)]);
     // MacData.macSalt + iterations are ignored on a PBMAC1 verify but MUST be present + non-1 (RFC 9579 4c/4d).
@@ -498,7 +525,18 @@ function _normalizeSpec(spec, opts) {
  */
 async function build(spec, opts) {
   opts = opts || {};
-  var pubKey = opts.integrity != null && opts.integrity.mode === "public-key";
+  // The integrity mode is checked against the permitted set rather than compared to one literal.
+  // Compared, any other spelling reads as "not public-key" and silently selects password integrity,
+  // dropping the signer with it: a caller who wrote "publicKey" gets a MAC where they asked for a
+  // signature, and nothing in the store or the call says which they got.
+  if (opts.integrity != null) {
+    if (typeof opts.integrity !== "object" || Array.isArray(opts.integrity)) throw _err("pkcs12/bad-input", "opts.integrity must be an object { mode, signer|signers, ... }");
+    guard.identifier.assertKnownKeys(opts.integrity, _INTEGRITY_OPTS, _err, "pkcs12/bad-input", "opts.integrity has an unknown option ");
+    if (opts.integrity.mode !== "public-key") {
+      throw _err("pkcs12/bad-integrity-mode", "opts.integrity.mode must be \"public-key\" (the only mode it selects); omit opts.integrity for password integrity, got " + JSON.stringify(opts.integrity.mode));
+    }
+  }
+  var pubKey = opts.integrity != null;
   // RFC 7292 sec. 4: public-key integrity OMITS MacData entirely -- a caller combining opts.mac with it is a
   // config-time reject (the self-check re-parse would otherwise fail the coherence rule anyway).
   if (pubKey && opts.mac != null && opts.mac !== false) throw _err("pkcs12/bad-integrity-mode", "public-key integrity has no MacData -- do not combine opts.mac with opts.integrity.mode 'public-key' (RFC 7292 sec. 4)");
@@ -590,7 +628,9 @@ async function _verifyMacOfStore(m, password, opts) {
     // downgraded store cannot pass under a weak MAC even though the algorithm identifiers parse.
     if (prfWc === "SHA-1" || macWc === "SHA-1") throw _err("pkcs12/unsupported-algorithm", "PBMAC1 with a <= 160-bit digest (SHA-1) is refused (RFC 9579 sec. 5/7)");
     _capWork(kdf.iterationCount, kdf.salt, opts, kdf.keyLength, C.LIMITS.PBKDF2_MAX_ITERATIONS);
-    computed = await pbes2.pbmac1(_pbePassword(password), kdf.salt, kdf.iterationCount, kdf.keyLength, prfWc, macWc, m.macedBytes);   // PBKDF2 -> UTF-8
+    var vPw = _pbePasswordOwned(password);
+    try { computed = await pbes2.pbmac1(vPw.bytes, kdf.salt, kdf.iterationCount, kdf.keyLength, prfWc, macWc, m.macedBytes); }   // PBKDF2 -> UTF-8
+    finally { _wipePw(vPw); }
   }
   return computed.length === expected.length && guard.crypto.constantTimeEqual(computed, expected);
 }
@@ -687,7 +727,7 @@ async function open(pfx, password, opts) {
   // wrong bag password fails at the first encrypted bag as the uniform pkcs12/decrypt-failed.
   var out = { integrityMode: m.integrityMode, macVerified: macVerified, signers: signers, keys: [], certs: [], crls: [], secrets: [] };
   var i;
-  var kdfBudget = { rounds: LEGACY_KDF_MAX_ROUNDS };   // aggregate legacy-PBE KDF work budget for this whole open()
+  var kdfBudget = { rounds: KDF_MAX_ROUNDS };   // aggregate KDF work budget for this whole open(), both schemes
   for (i = 0; i < m.safeBags.length; i++) _openBag(m.safeBags[i], password, opts, out, 0, kdfBudget);
   for (i = 0; i < m.encryptedSafes.length; i++) await _openEncryptedSafe(m.encryptedSafes[i], password, opts, out, 0, kdfBudget);
   if (opts.keys === "crypto") {
@@ -801,7 +841,15 @@ function _decryptLegacyPbe(ea, ct, password, opts, budget) {
 // Decrypt a PBES2 (RFC 8018) or legacy-PBE (RFC 7292 App. C) bag/safe -- dispatch on the encryptionAlgorithm
 // OID. PBES2 uses the UTF-8 password (the pinned interop convention); legacy PBE uses the App. B.1 BMPString.
 function _decryptBag(ea, ct, password, opts, budget) {
-  if (ea.oid === O("pbes2")) return pbes2.pbes2Decrypt(_pbePassword(password), ea.parameters, ct, opts, _err, "pkcs12");
+  // BOTH arms charge the one shared budget. Charging only the legacy arm left the modern one --
+  // the arm every current producer emits -- able to reset its per-bag cap on every bag, so a store
+  // that repeats a costly PBES2 bag up to the parser's element limit multiplied the cap by that
+  // limit in blocking pbkdf2Sync work.
+  if (ea.oid === O("pbes2")) {
+    var pw = _pbePasswordOwned(password);
+    try { return pbes2.pbes2Decrypt(pw.bytes, ea.parameters, ct, opts, _err, "pkcs12", budget); }
+    finally { _wipePw(pw); }
+  }
   return _decryptLegacyPbe(ea, ct, password, opts, budget);
 }
 

package/lib/schema-cms.js

@@ -47,6 +47,7 @@
 var asn1 = require("./asn1-der");
 var schema = require("./schema-engine");
 var pkix = require("./schema-pkix");
+var guard = require("./guard-all");
 var oid = require("./oid");
 var frameworkError = require("./framework-error");
 var schemaX509 = require("./schema-x509");
@@ -1150,7 +1151,15 @@ var CONTENT_INFO = schema.seq([
  *   cms.signerInfos[0].sid.serialNumberHex;   // -> "0a1b"
  *   cms.encapContentInfo.eContent;            // -> Buffer | null (detached)
  */
-var parse = pkix.makeParser({ pemLabel: "CMS", PemError: PemError, ErrorClass: CmsError, prefix: "cms", what: "CMS ContentInfo", topSchema: CONTENT_INFO, ns: NS });
+// Recording, for the reason the certificate and CRL parsers are: a SignedData is one or more
+// signatures over byte ranges, and a parsed one presents those ranges (`signedAttrsBytes`, the
+// encapsulated `eContent`), the signatures, and the certificates that verify them as separate
+// properties of one object. Keep a genuine signer's `signature` and `signedAttrsBytes` and replace
+// the `eContent` beside them, and every part of the check still passes for content that signer never
+// signed -- which is exactly the forgery pki.cms.verify's own block claims to defend. The verdict
+// verbs re-derive from what is recorded here, so the object a caller passes names bytes rather than
+// asserting facts.
+var parse = pkix.makeRecordingParser({ pemLabel: "CMS", PemError: PemError, ErrorClass: CmsError, prefix: "cms", what: "CMS ContentInfo", topSchema: CONTENT_INFO, ns: NS }, "cms");
 
 /**
  * @primitive  pki.schema.cms.pemDecode
@@ -1220,7 +1229,13 @@ function walkEnvelopedData(node) { return schema.walk(ENVELOPED_DATA, node, NS).
 // (an RFC 7292 PFX authSafe or encrypted safe, whose wire encoding may be BER
 // that the strict `parse` entry would refuse). Same contract as
 // walkEnvelopedData: the node is the bare structure, typed cms/* on rejection.
-function walkSignedData(node) { return schema.walk(SIGNED_DATA, node, NS).result; }
+// Records provenance, like parse: the structure a consumer hands to pki.cms.verify must be
+// re-derivable from the bytes it was walked from, and a PFX authSafe reaches verify this way. The
+// walker's own BER-tolerant decode is what replays it -- the strict `parse` entry would refuse the
+// indefinite-length encoding real stores carry.
+var walkSignedData = guard.parsed.recordingWalker("cms", function (node) {
+  return schema.walk(SIGNED_DATA, node, NS).result;
+}, function (der) { return asn1.decode(der, { ber: true }); });
 function walkEncryptedData(node) { return schema.walk(ENCRYPTED_DATA, node, NS).result; }
 // Validate + surface one countersignature value (RFC 5652 sec. 11.4, Countersignature ::=
 // SignerInfo) into the same parsed shape parse() gives a top-level SignerInfo -- so pki.cms.verify

package/lib/sigstore.js

@@ -522,6 +522,9 @@ var IDENTITY_FIELDS = ["san", "issuer", "sourceRepositoryURI"];
 // The guard tests membership with hasOwnProperty, so the permitted set is a lookup object --
 // an array would treat "0"/"1" as the known keys and reject every real field name.
 var IDENTITY_KEYS = { san: 1, issuer: 1, sourceRepositoryURI: 1 };
+// Every option pki.sigstore.verifyBundle reads. Adding one here is the only way to make it
+// accepted, so a capability cannot arrive with its option silently ignored at this boundary.
+var _VERIFY_BUNDLE_OPTS = { fulcioRoots: 1, rekorKeys: 1, identity: 1, predicateType: 1, time: 1 };
 
 // Returns WHICH fields were actually compared. A bundle verifies its own signature and log
 // inclusion whoever signed it -- Fulcio issues to anyone who completes an OIDC flow -- so
@@ -633,6 +636,13 @@ async function verifyBundle(bundle, opts) {
     throw new TypeError("verifyBundle: bundle must be an object, JSON string, or Buffer");
   }
   opts = opts || {};
+  // An unrecognized option is refused, not swallowed. The identity policy one level down already
+  // closes this door for exactly the reason it needs closing here too: cosign spells the signer pin
+  // `certificateIdentity`, and a swallowed spelling checks nothing under a name the operator
+  // believes pins the signer. At the top level the same slip loses the SLSA predicate pin as well,
+  // and `predicateType` has no `identityChecked`-style field, so nothing in the verdict reveals
+  // that the pin never ran.
+  guard.identifier.assertKnownKeys(opts, _VERIFY_BUNDLE_OPTS, _err, "sigstore/bad-input", "pki.sigstore.verifyBundle has an unknown option ");
   var b = parseBundle(bundle);
   var vm = b.verificationMaterial;
   var env = b.dsseEnvelope;

package/lib/tsp-sign.js

@@ -27,18 +27,40 @@ var guard = require("./guard-all");
 var frameworkError = require("./framework-error");
 
 var pkix = require("./schema-pkix");
+var pkiBuild = require("./pki-build");
 var TspError = frameworkError.TspError;
 var _NS = pkix.makeNS("tsp", TspError, oid);
 var b = asn1.build;
 function _err(code, message, cause) { return new TspError(code, message, cause); }
 function O(name) { return oid.byName(name); }
 
+// The shared authoring-side builder, for the same pre-encoded-Extension validation every other
+// request builder uses (a CSR's extensionRequest, a CRMF CertTemplate, a CRL's entry extensions).
+var _b = pkiBuild.makeBuilder({
+  ErrorClass: TspError, prefix: "tsp", O: O, NS: _NS,
+  NAME_SCHEMA: pkix.name(_NS), SPKI_SCHEMA: pkix.spki(_NS),
+});
+
 // Digest names whose imprint / certHash this producer supports (the SHA-2 family).
 var NODE_DIGEST = { sha256: "sha256", sha384: "sha384", sha512: "sha512" };
 // The message-imprint hash MUST be exactly the digest algorithm's output length (RFC 3161 sec.
 // 2.4.1 -- hashedMessage is "the hash of the datum to be time-stamped").
 var HASH_LEN = { sha256: 32, sha384: 48, sha512: 64 };
 
+// How much a `pki.path.validate` revocationChecked outcome ESTABLISHED, ordered. `false` is "no
+// checker ran at all"; "undetermined" is "one ran and could not answer"; "waived" is an
+// undetermined one a caller chose to pass; "determined" is an explicit good-or-revoked answer.
+// Ranking them lets a caller trying several candidate paths keep the most established outcome any
+// of them reached, rather than whichever happened to run last.
+var _REVOCATION_RANK = { "false": 0, "undetermined": 1, "waived": 2, "determined": 3 };
+function _rankRevocation(v) {
+  var r = _REVOCATION_RANK[String(v)];
+  return r === undefined ? 0 : r;   // an unrecognized value establishes nothing
+}
+function _moreEstablished(candidate, current) {
+  return _rankRevocation(candidate) > _rankRevocation(current);
+}
+
 // A hash AlgorithmIdentifier { OID, NULL } -- messageImprint and ESSCertIDv2 hash algorithms
 // carry an explicit NULL parameter (the form RFC 3161 / RFC 5035 producers emit).
 function _hashAlgId(name) {
@@ -109,7 +131,13 @@ function _signingCertV2(certDer, hashName) {
  *   var token = await pki.tsp.sign(imprint, { cert: signerCertDer, key: signerKeyPkcs8 }, { policy: "1.3.6.1.4.1.1", serialNumber: 1 });
  *   (await pki.cms.verify(token)).valid;   // true
  */
+// Documented `-> Promise`, so a fault leaves as a REJECTION (guard-async); the checks stay
+// synchronous because they read the caller's mutable imprint, TSA material and options.
 function sign(messageImprint, tsa, opts) {
+  return guard.async.deferred(function () { return _sign(messageImprint, tsa, opts); });
+}
+
+function _sign(messageImprint, tsa, opts) {
   opts = opts || {};
   if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("tsp/bad-input", "pki.tsp.sign options must be an object");
   var mi = messageImprint || {};
@@ -130,10 +158,14 @@ function sign(messageImprint, tsa, opts) {
   // non-Date or an Invalid Date that would encode a garbage GeneralizedTime).
   if (opts.genTime != null) guard.time.assertValid(opts.genTime, _err, "tsp/bad-input", "genTime");
   var genTime = opts.genTime instanceof Date ? opts.genTime : new Date();
-  var fields = [b.integer(1n), _policy(opts.policy), imprint, b.integer(BigInt(opts.serialNumber)), b.generalizedTime(genTime)];
+  // A caller-authored INTEGER is coerced through the shared guard, so a value that is not one is a
+  // typed tsp/bad-input rather than a raw SyntaxError or RangeError out of BigInt() -- an untyped
+  // fault escaping a public verb, which a caller cannot catch by code.
+  var serial = guard.range.authoredInteger(opts.serialNumber, _err, "tsp/bad-input", "serialNumber");
+  var fields = [b.integer(1n), _policy(opts.policy), imprint, b.integer(serial), b.generalizedTime(genTime)];
   if (opts.accuracy) fields.push(_accuracy(opts.accuracy));
   if (opts.ordering === true) fields.push(b.boolean(true));
-  if (opts.nonce != null) fields.push(b.integer(BigInt(opts.nonce)));
+  if (opts.nonce != null) fields.push(b.integer(guard.range.authoredInteger(opts.nonce, _err, "tsp/bad-input", "nonce")));
   var tstInfo = b.sequence(fields);
 
   var signCert = { type: "signingCertificateV2", values: [_signingCertV2(certDer, certHashAlg)] };
@@ -237,12 +269,26 @@ function request(messageImprint, opts) {
   // extensions in schema order. certReq DEFAULT FALSE -> only an explicit TRUE is encoded (DER).
   var fields = [b.integer(1n), imprint];
   if (opts.reqPolicy != null) fields.push(_policy(opts.reqPolicy));
-  if (opts.nonce != null) fields.push(b.integer(BigInt(opts.nonce)));
+  if (opts.nonce != null) fields.push(b.integer(guard.range.authoredInteger(opts.nonce, _err, "tsp/bad-input", "nonce")));
   if (opts.certReq != null && typeof opts.certReq !== "boolean") throw _err("tsp/bad-input", "certReq must be a boolean");
   if (opts.certReq === true) fields.push(b.boolean(true));
   if (opts.extensions != null) {
     if (!Array.isArray(opts.extensions) || !opts.extensions.every(function (e) { return Buffer.isBuffer(e) || e instanceof Uint8Array; })) throw _err("tsp/bad-input", "extensions must be an array of encoded Extension DER buffers");
-    if (opts.extensions.length) fields.push(b.contextConstructed(0, Buffer.concat(opts.extensions.map(function (e) { return Buffer.from(e); }))));
+    // Each pre-encoded Extension is validated as one, and its extnID must not repeat -- the same
+    // gate every other request builder applies. Spliced in unchecked, a caller relaying a blob it
+    // did not author put fully chosen bytes inside [0] and this encoder emitted DER its own
+    // parseRequest refuses: an undecodable value, a duplicate extnID, an explicit critical=FALSE
+    // the DER DEFAULT rule forbids.
+    var seenExt = {};
+    var encoded = opts.extensions.map(function (e, i) {
+      var der = Buffer.from(e);
+      _b.assertValidExtension(der, i);
+      var extnId = asn1.read.oid(asn1.decode(der).children[0]);
+      if (seenExt[extnId]) throw _err("tsp/bad-input", "duplicate request extension " + extnId + " (RFC 5280 sec. 4.2)");
+      seenExt[extnId] = true;
+      return der;
+    });
+    if (encoded.length) fields.push(b.contextConstructed(0, Buffer.concat(encoded)));
   }
   var der = b.sequence(fields);
   return opts.pem ? schemaTsp.pemEncode(der, "TIMESTAMP REQUEST") : der;
@@ -564,7 +610,8 @@ function _buildTsaChains(leaf, pool) {
  * PEM (never a parsed object -- every checked field is read from the CMS-verified eContent, so a
  * mutated parsed structure cannot desynchronize the checks from the signed bytes). `data` is the
  * original bytes (hashed under the token's messageImprint algorithm) or a precomputed
- * `{ hashAlgorithm, hashedMessage }`. Returns `{ valid, trusted, genTime, accuracy, serialNumber,
+ * `{ hashAlgorithm, hashedMessage }`. Returns `{ valid, trusted, revocationChecked,
+ * anchorConstraints, genTime, accuracy, serialNumber,
  * serialNumberHex, policy, nonce, tsa, tstInfo, signer, code?, reason? }`. `valid` is true only
  * when the CMS signature, the imprint match, the eContentType, the ESSCertID(V2) binding, the
  * RFC 3161 sec. 2.3 critical single-`timeStamping` extendedKeyUsage rule, the requested nonce (when
@@ -579,11 +626,19 @@ function _buildTsaChains(leaf, pool) {
  * accepting one. A timestamp is archived precisely to be re-read years later, and one boolean
  * cannot answer both questions then.
  *
+ * `revocationChecked` is the third claim, for the same reason. Revocation runs only when a
+ * `revocationChecker` is supplied, so a `trusted` token whose TSA was never checked against a CRL
+ * or an OCSP responder reads identically to one established un-revoked -- unless the verdict says
+ * which. It is `false` whenever no path ran at all. `anchorConstraints` carries whatever the anchor
+ * itself constrained, from `pki.path.validate`.
+ *
  * @opts  trustAnchor   Anchor `{ name, publicKey, algorithm }` -- runs `pki.path.validate` on the
  *                       TSA certificate chain ordered from the token's embedded certificates
- *                       (validity at genTime, requiredEku timeStamping, revocation), so a TSA under
- *                       an intermediate CA validates, not only one directly under the anchor. Omit
- *                       to verify signature + imprint + binding + EKU only and anchor the cert yourself.
+ *                       (validity at genTime, requiredEku timeStamping, and revocation when a
+ *                       `revocationChecker` is supplied -- `revocationChecked` reports which), so a
+ *                       TSA under an intermediate CA validates, not only one directly under the
+ *                       anchor. Omit to verify signature + imprint + binding + EKU only and anchor
+ *                       the cert yourself.
  * @opts  nonce         Require the token's TSTInfo.nonce to equal this (a number/BigInt).
  * @opts  reqPolicy     Require the token's policy to equal this (an OID name or dotted string).
  * @opts  certs         Out-of-band TSA certificates (an array of DER `Buffer`s) added to the signer
@@ -630,8 +685,15 @@ async function verify(token, data, opts) {
   // `res.trusted` must get an answer on both branches -- an undefined on the failure path is the
   // same "cannot tell what was checked" the field was added to remove, and `!res.trusted` reading
   // true by accident is not the same as its reading true because nothing anchored the TSA.
+  // What a path established travels with the REFUSAL as well. Hardcoding these to false/null here
+  // would misreport the one case the field matters most for: a path that ran, established the TSA
+  // REVOKED, and refused on that basis did check revocation, and saying it did not is the same
+  // "cannot tell what was checked" the field was added to remove. They stay false/null until a path
+  // actually produces them, which is the honest answer before one runs.
+  var revocationChecked = false;
+  var anchorConstraints = null;
   function fail(code, reason) {
-    return { valid: false, trusted: false, code: code, reason: reason || null, genTime: tst.genTime, accuracy: tst.accuracy, serialNumber: tst.serialNumber, serialNumberHex: tst.serialNumberHex, policy: tst.policy, nonce: tst.nonce, tsa: tst.tsa, tstInfo: tst, signer: null };
+    return { valid: false, trusted: false, revocationChecked: revocationChecked, anchorConstraints: anchorConstraints, code: code, reason: reason || null, genTime: tst.genTime, accuracy: tst.accuracy, serialNumber: tst.serialNumber, serialNumberHex: tst.serialNumberHex, policy: tst.policy, nonce: tst.nonce, tsa: tst.tsa, tstInfo: tst, signer: null };
   }
   // M12 -- the CMS signature over the exact RFC 5652 sec. 5.4 preimage (message-digest bound to the
   // authenticated eContent). cms.verify re-parses the same bytes; a failure is a fail-closed verdict.
@@ -647,7 +709,7 @@ async function verify(token, data, opts) {
   if (mi !== true) return fail(mi);
   // M14 -- if a request nonce is supplied, the token MUST echo it (BigInt-exact).
   if (opts.nonce != null) {
-    var wantNonce = BigInt(opts.nonce);
+    var wantNonce = guard.range.authoredInteger(opts.nonce, _err, "tsp/bad-input", "opts.nonce");
     if (tst.nonce == null || tst.nonce !== wantNonce) return fail("tsp/nonce-mismatch");
   }
   // M15 -- if the requested policy is supplied, the token's policy MUST equal it.
@@ -713,23 +775,54 @@ async function verify(token, data, opts) {
       // end of the chain and not the other, and a root explicitly distrusted for timestamping would
       // still answer trusted. The purpose is not a caller choice here: this verb validates timestamp
       // tokens and nothing else, so there is exactly one purpose its anchors can be judged under.
+      // EVERY path result goes through this one function, so none can be produced without being
+      // accumulated. The alternative -- validating in several places and accumulating afterwards --
+      // is what let a result be overwritten before it was counted, first across candidate chains and
+      // then across the two endpoints of one candidate. There is now one door and it always counts.
+      //
+      // The two fields accumulate INDEPENDENTLY because they are independent facts. Whether
+      // revocation was established and which anchor constraints were consulted do not imply each
+      // other: an anchor that rejects the TSA on its own purposes or distrustAfter metadata, with no
+      // revocationChecker configured, establishes constraints while establishing nothing about
+      // revocation.
+      async function validateAt(chain, when) {
+        var res = await pathValidate.validate(chain, {
+          time: when, trustAnchor: opts.trustAnchor, requiredEku: ["timeStamping"], checkPurpose: "timeStamping", revocationChecker: opts.revocationChecker,
+        });
+        // The most any attempt ESTABLISHED, kept across every attempt: backtracking tries several
+        // chains for one TSA certificate and a fractional genTime validates each at two endpoints,
+        // so an attempt that fails earlier than another must not erase what that other established.
+        if (_moreEstablished(res.revocationChecked, revocationChecked)) revocationChecked = res.revocationChecked;
+        // Every attempt validates against the SAME opts.trustAnchor under the same purpose, so any
+        // non-null value describes that one anchor; the first to report them is as good as the last.
+        if (anchorConstraints == null && res.anchorConstraints != null) anchorConstraints = res.anchorConstraints;
+        return res;
+      }
       var chains = _buildTsaChains(pkiX509.parse(tsaCertDer), pool);
       for (var ci = 0; ci < chains.length && !(pathRes && pathRes.valid); ci++) {
-        pathRes = await pathValidate.validate(chains[ci], {
-          time: floorT, trustAnchor: opts.trustAnchor, requiredEku: ["timeStamping"], checkPurpose: "timeStamping", revocationChecker: opts.revocationChecker,
-        });
-        if (pathRes.valid && ceilT !== floorT) {
-          pathRes = await pathValidate.validate(chains[ci], {
-            time: ceilT, trustAnchor: opts.trustAnchor, requiredEku: ["timeStamping"], checkPurpose: "timeStamping", revocationChecker: opts.revocationChecker,
-          });
-        }
+        pathRes = await validateAt(chains[ci], floorT);
+        if (pathRes.valid && ceilT !== floorT) pathRes = await validateAt(chains[ci], ceilT);
       }
     } catch (e) { return fail("tsp/untrusted-tsa", (e && e.message) || String(e)); }
+    // On a REFUSAL the question is whether ANYTHING established the TSA's revocation status, so the
+    // accumulated best answers it: a candidate that reached the checker and was rejected as revoked
+    // did check revocation, and saying otherwise would misdescribe the reason for the refusal.
     if (!pathRes || !pathRes.valid) return fail("tsp/untrusted-tsa", "the TSA certificate did not validate to the trust anchor at genTime");
+    // On ACCEPTANCE the question is narrower and the accumulated best would OVERCLAIM: what matters
+    // is what was checked on the path actually accepted, not what some rejected candidate managed.
+    // The loop stops at the first valid path, so `pathRes` is that path.
+    revocationChecked = pathRes.revocationChecked;
+    anchorConstraints = pathRes.anchorConstraints;
+    // Reduced to a bare `trusted: true`, this answered the same way whether the TSA was established
+    // un-revoked or revocation was never consulted at all -- and revocation only runs when a
+    // revocationChecker is supplied, so the second case is the DEFAULT. A caller archiving a
+    // timestamp verdict could not tell the two apart later, which is the distinction the
+    // valid/trusted split exists to keep.
     trusted = true;
   }
   return {
-    valid: true, trusted: trusted, genTime: tst.genTime, accuracy: tst.accuracy,
+    valid: true, trusted: trusted, revocationChecked: revocationChecked, anchorConstraints: anchorConstraints,
+    genTime: tst.genTime, accuracy: tst.accuracy,
     serialNumber: tst.serialNumber, serialNumberHex: tst.serialNumberHex,
     policy: tst.policy, policyName: tst.policyName, nonce: tst.nonce, tsa: tst.tsa,
     tstInfo: tst, signer: { cert: tsaCertDer, sid: signer.sid },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:e4afed62-75b0-4b79-b65c-4d16c17ee70b",
+  "serialNumber": "urn:uuid:f56149c0-58f9-40e1-a0f0-36a0dd2e4ee9",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-08-15T23:54:15.184Z",
+    "timestamp": "2026-08-16T03:23:32.715Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.5.5",
+      "bom-ref": "@blamejs/pki@0.5.6",
       "type": "application",
       "name": "pki",
-      "version": "0.5.5",
+      "version": "0.5.6",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
-      "purl": "pkg:npm/%40blamejs/pki@0.5.5",
+      "purl": "pkg:npm/%40blamejs/pki@0.5.6",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.5.5",
+      "ref": "@blamejs/pki@0.5.6",
       "dependsOn": []
     }
   ]