@blamejs/pki 0.5.15 → 0.5.17

package/lib/pbes2.js

@@ -133,13 +133,21 @@ function parsePbkdf2Params(paramsDer, opts, E, prefix, strictPrf) {
 
 // AES-CBC content encryption / decryption (PKCS#7 pad). decrypt's final() throws on bad pad, and the caller
 // collapses that into its uniform decrypt-failed verdict.
-function cbcEncrypt(key, iv, plaintext, keyBits) {
+// cbcEncrypt(key, iv, plaintext, keyBits, E, code) -> the ciphertext.
+// Takes the caller's typed error for the same reason cbcDecrypt does: the cipher runs through the
+// shared guard, whose one throw has to keep the calling domain's own code.
+function cbcEncrypt(key, iv, plaintext, keyBits, E, code) {
   var c = nodeCrypto.createCipheriv("aes-" + keyBits + "-cbc", key, iv);
-  return Buffer.concat([c.update(plaintext), c.final()]);
+  return guard.secret.cipherFinish(c, plaintext, E, code, "a content-encryption intermediate");
 }
-function cbcDecrypt(key, iv, ct, keyBits) {
+// cbcDecrypt(key, iv, ct, keyBits, E, code) -> the recovered plaintext.
+// Takes the caller's typed error the way rc2.cbcDecrypt does, so a refusal keeps its own domain.
+function cbcDecrypt(key, iv, ct, keyBits, E, code) {
   var d = nodeCrypto.createDecipheriv("aes-" + keyBits + "-cbc", key, iv);
-  return Buffer.concat([d.update(ct), d.final()]);
+  // A wrong key fails inside final(), on the padding check, and update() has by then produced every
+  // block but the last. Through the guard so that partial plaintext is cleared on both exits rather
+  // than abandoned readable on exactly the path an attacker induces.
+  return guard.secret.cipherFinish(d, ct, E, code, "the partially recovered plaintext");
 }
 
 // Higher-level PBES2 AES-CBC encrypt: derive an AES key from PRE-FORMATTED password bytes (the caller owns
@@ -160,11 +168,11 @@ function pbes2Encrypt(pwBytes, plaintext, opts, E, prefix) {
   // is not cleared: the caller formatted it and may still own the buffer.
   var key = nodeCrypto.pbkdf2Sync(pwBytes, salt, iterations, keyBits / 8, prfNode);
   try {
-    return { algId: pbes2AlgId(salt, iterations, prf, cipherName, iv), ct: cbcEncrypt(key, iv, plaintext, keyBits) };
+    return { algId: pbes2AlgId(salt, iterations, prf, cipherName, iv), ct: cbcEncrypt(key, iv, plaintext, keyBits, E, prefix + "/bad-input") };
   } finally {
     // E is the caller's error FACTORY, not a class; guard-secret delegates its only throw to
-    // guard-bytes, which constructs.  yields the error the factory returns, so the
-    // currency is compatible -- and the throw is unreachable here regardless, because a freshly
+    // guard-bytes, which constructs. `new` on a factory yields the object the factory returns, so
+    // the currency is compatible -- and the throw is unreachable here regardless, because a freshly
     // allocated pbkdf2 buffer cannot be detached.
     guard.secret.zeroize(key, E, prefix + "/bad-input", "the password-derived encryption key");
   }
@@ -208,7 +216,7 @@ function pbes2Decrypt(pwBytes, params, ciphertext, opts, E, prefix, budget) {
     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); }
+  try { return cbcDecrypt(dk, iv, ciphertext, keyBits, E, prefix + "/decrypt-failed"); }
   catch (_e) { throw E(prefix + "/decrypt-failed", "decryption failed"); }
   finally { guard.secret.zeroize(dk, E, prefix + "/bad-input", "the password-derived decryption key"); }
 }

package/lib/pkcs12-build.js

@@ -5,6 +5,7 @@
  * @module     pki.pkcs12
  * @nav        Signing
  * @title      PKCS#12
+ * @fullname   PKCS#12 keystores (.p12 and .pfx): build and open
  * @intro The PKCS#12 (.p12 / .pfx) producing side (RFC 7292, RFC 9579). `pki.pkcs12.build` assembles a
  *   password-integrity PFX -- key, certificate, CRL, and secret bags (shrouded keys and cert safes encrypted
  *   under RFC 8018 PBES2) wrapped in an AuthenticatedSafe, protected by either a classic Appendix B HMAC or
@@ -848,7 +849,7 @@ function _decryptLegacyPbe(ea, ct, password, opts, budget) {
   try {
     if (scheme.rc2) return rc2.cbcDecrypt(keyM, scheme.rc2, iv, ct, _err, "pkcs12/decrypt-failed");
     var d = nodeCrypto.createDecipheriv(scheme.cipher, keyM, iv);
-    return Buffer.concat([d.update(ct), d.final()]);
+    return guard.secret.cipherFinish(d, ct, Pkcs12Error, "pkcs12/bad-input", "the recovered safe contents");
   } catch (_e) { throw _err("pkcs12/decrypt-failed", "decryption failed"); }
   finally { guard.secret.zeroize(keyM, Pkcs12Error, "pkcs12/bad-input", "the password-derived decryption key"); }
 }

package/lib/schema-all.js

@@ -5,6 +5,7 @@
  * @module     pki.schema
  * @nav        Schema
  * @title      Schema
+ * @fullname   Format detection: parse DER without knowing the format first
  * @order      10
  * @featured   true
  * @slug       schema

package/lib/schema-c509.js

@@ -5,6 +5,7 @@
  * @module pki.schema.c509
  * @nav    Schema
  * @title  C509
+ * @fullname   C509 compact certificates (CBOR-encoded X.509)
  * @intro  C509 CBOR-encoded certificates (draft-ietf-cose-cbor-encoded-cert). A compact CBOR
  *   re-encoding of an X.509 v3 certificate: a deterministic-CBOR array of exactly 11 elements
  *   (10 TBS fields + the issuer signature). Two modes: c509CertificateType 2 is a natively-signed

package/lib/schema-csrattrs.js

@@ -5,6 +5,7 @@
  * @module     pki.schema.csrattrs
  * @nav        Schema
  * @title      CSR Attributes
+ * @fullname   CSR attributes: what an EST server asks an enrollee to include
  * @order      185
  * @slug       csrattrs
  *

package/lib/schema-engine.js

@@ -5,6 +5,7 @@
  * @module     pki.schema.engine
  * @nav        Schema
  * @title      Schema engine
+ * @fullname   ASN.1 schema engine: one definition drives encode and decode
  * @order      60
  *
  * @intro

package/lib/schema-pkcs8.js

@@ -5,6 +5,7 @@
  * @module     pki.schema.pkcs8
  * @nav        Schema
  * @title      PKCS#8
+ * @fullname   PKCS#8 private keys, encrypted and unencrypted
  * @order      140
  * @slug       pkcs8
  *

package/lib/schema-smime.js

@@ -5,6 +5,7 @@
  * @module     pki.schema.smime
  * @nav        Schema
  * @title      S/MIME (ESS)
+ * @fullname   S/MIME signed and encrypted mail, with ESS security labels
  * @order      180
  * @slug       smime
  *

package/lib/schema-tsp.js

@@ -5,6 +5,7 @@
  * @module     pki.schema.tsp
  * @nav        Schema
  * @title      TSP
+ * @fullname   RFC 3161 timestamps (TSP): request, sign and verify
  * @order      170
  * @slug       tsp
  *

package/lib/schema-x509.js

@@ -5,6 +5,7 @@
  * @module     pki.schema.x509
  * @nav        Schema
  * @title      X.509
+ * @fullname   X.509 certificates: parse, sign and inspect
  * @order      100
  * @featured   true
  * @slug       x509

package/lib/shbs.js

@@ -5,6 +5,7 @@
  * @module pki.shbs
  * @nav        Signatures
  * @title      Stateful hash-based
+ * @fullname   Stateful hash-based signatures: LMS and XMSS
  * @intro Stateful hash-based signature VERIFICATION -- HSS/LMS (RFC 8554),
  *   carried in X.509 by RFC 9802 and in CMS by RFC 9708, profiled by NIST
  *   SP 800-208. Verify only, by deliberate design: stateful hash-based signing

package/lib/sigstore.js

@@ -5,6 +5,7 @@
  * @module pki.sigstore
  * @nav        Supply chain
  * @title      Sigstore
+ * @fullname   Sigstore bundles: keyless signing and provenance
  * @intro Zero-dependency verifier for a Sigstore bundle, the exact artifact
  *   `npm publish --provenance` produces and the npm registry serves at its
  *   attestations API. A bundle is a keyless (Fulcio) signature over a DSSE-wrapped

package/lib/smime.js

@@ -5,6 +5,7 @@
  * @module     pki.smime
  * @nav        Messaging
  * @title      S/MIME
+ * @fullname   S/MIME signed and encrypted mail
  * @order      175
  * @slug       smime
  *

package/lib/tls-cert-compress.js

@@ -5,6 +5,7 @@
  * @module     pki.tls
  * @nav        Transparency
  * @title      TLS
+ * @fullname   TLS certificate compression (RFC 8879)
  * @order      215
  * @slug       tls
  *

package/lib/trust.js

@@ -5,6 +5,7 @@
  * @module     pki.trust
  * @nav        Path validation
  * @title      Trust-store ingestion
+ * @fullname   Trust stores: load and pin root certificate anchors
  * @order      230
  * @slug       trust
  *

package/lib/tsp-sign.js

@@ -5,6 +5,7 @@
  * @module     pki.tsp
  * @nav        Signing
  * @title      Timestamps
+ * @fullname   RFC 3161 trusted timestamps: request, sign and verify
  * @intro Create an RFC 3161 timestamp token. A TimeStampToken IS a CMS SignedData whose
  *   encapsulated content is a `TSTInfo` (the timestamped message imprint + trusted time), so
  *   `sign(messageImprint, tsa, opts)` builds the `TSTInfo`, attaches the RFC 3161 sec. 2.4.2

package/lib/webauthn.js

@@ -5,6 +5,7 @@
  * @module pki.webauthn
  * @nav        Validation
  * @title      WebAuthn
+ * @fullname   WebAuthn: verify registration attestation and assertions
  * @intro Trust evaluation of a W3C WebAuthn (Level 3) / passkey attestation: parse
  *   the attestation object + authenticatorData, decode the COSE credential public
  *   key, and verify each defined attestation-statement format (packed, tpm,

package/lib/webcrypto.js

@@ -5,6 +5,7 @@
  * @module     pki.webcrypto
  * @nav        Core
  * @title      WebCrypto
+ * @fullname   WebCrypto: a SubtleCrypto surface over node:crypto
  * @order      50
  * @featured   true
  * @slug       webcrypto
@@ -470,7 +471,7 @@ SubtleCrypto.prototype.encrypt = async function encrypt(algorithm, key, data) {
       return _withSecretBytes(key, function (kb) {
         var cipher = nodeCrypto.createCipheriv("aes-" + key.algorithm.length + "-gcm", kb, iv, { authTagLength: (alg.tagLength || 128) / 8 });
         if (aad) cipher.setAAD(aad);
-        var ct = Buffer.concat([cipher.update(buf), cipher.final()]);
+        var ct = guard.secret.cipherFinish(cipher, buf, WebCryptoError, "webcrypto/operation", "an AES-GCM encrypt intermediate");
         return Buffer.concat([ct, cipher.getAuthTag()]);
       });
     }, "encrypt"));
@@ -480,7 +481,7 @@ SubtleCrypto.prototype.encrypt = async function encrypt(algorithm, key, data) {
     return _toArrayBuffer(_runCipher(function () {
       return _withSecretBytes(key, function (kb) {
         var c2 = nodeCrypto.createCipheriv("aes-" + key.algorithm.length + "-cbc", kb, cbcIv);
-        return Buffer.concat([c2.update(buf), c2.final()]);
+        return guard.secret.cipherFinish(c2, buf, WebCryptoError, "webcrypto/operation", "an AES-CBC encrypt intermediate");
       });
     }, "encrypt"));
   }
@@ -490,7 +491,7 @@ SubtleCrypto.prototype.encrypt = async function encrypt(algorithm, key, data) {
     return _toArrayBuffer(_runCipher(function () {
       return _withSecretBytes(key, function (kb) {
         var c3 = nodeCrypto.createCipheriv("aes-" + key.algorithm.length + "-ctr", kb, ctrCounter);
-        return Buffer.concat([c3.update(buf), c3.final()]);
+        return guard.secret.cipherFinish(c3, buf, WebCryptoError, "webcrypto/operation", "an AES-CTR encrypt intermediate");
       });
     }, "encrypt"));
   }
@@ -528,7 +529,9 @@ SubtleCrypto.prototype.decrypt = async function decrypt(algorithm, key, data) {
         var d = nodeCrypto.createDecipheriv("aes-" + key.algorithm.length + "-gcm", kb, iv, { authTagLength: tagLen });
         if (gcmAad) d.setAAD(gcmAad);
         d.setAuthTag(tag);
-        return Buffer.concat([d.update(ct), d.final()]);
+        // The recovered plaintext exists in full before final() judges the tag, so a forged message
+        // would otherwise abandon a readable copy on the throw path.
+        return guard.secret.cipherFinish(d, ct, WebCryptoError, "webcrypto/operation", "the recovered AES-GCM plaintext");
       });
     }, "decrypt"));
   }
@@ -537,7 +540,7 @@ SubtleCrypto.prototype.decrypt = async function decrypt(algorithm, key, data) {
     return _toArrayBuffer(_runCipher(function () {
       return _withSecretBytes(key, function (kb) {
         var d2 = nodeCrypto.createDecipheriv("aes-" + key.algorithm.length + "-cbc", kb, cbcIv2);
-        return Buffer.concat([d2.update(buf), d2.final()]);
+        return guard.secret.cipherFinish(d2, buf, WebCryptoError, "webcrypto/operation", "the recovered AES-CBC plaintext");
       });
     }, "decrypt"));
   }
@@ -547,7 +550,7 @@ SubtleCrypto.prototype.decrypt = async function decrypt(algorithm, key, data) {
     return _toArrayBuffer(_runCipher(function () {
       return _withSecretBytes(key, function (kb) {
         var d3 = nodeCrypto.createDecipheriv("aes-" + key.algorithm.length + "-ctr", kb, ctrCounter2);
-        return Buffer.concat([d3.update(buf), d3.final()]);
+        return guard.secret.cipherFinish(d3, buf, WebCryptoError, "webcrypto/operation", "the recovered AES-CTR plaintext");
       });
     }, "decrypt"));
   }
@@ -874,7 +877,7 @@ SubtleCrypto.prototype.wrapKey = async function wrapKey(format, key, wrappingKey
     try {
       return _withSecretBytes(wrappingKey, function (wkBytes) {
         var c = nodeCrypto.createCipheriv("aes" + wrappingKey.algorithm.length + "-wrap", wkBytes, Buffer.from("A6A6A6A6A6A6A6A6", "hex"));
-        return _toArrayBuffer(Buffer.concat([c.update(bytes), c.final()]));
+        return _toArrayBuffer(guard.secret.cipherFinish(c, bytes, WebCryptoError, "webcrypto/operation", "an AES-KW wrap intermediate"));
       });
     } catch (e) { throw new WebCryptoError("webcrypto/operation", "wrapKey: AES-KW key wrap failed", e); }
   }
@@ -919,7 +922,7 @@ SubtleCrypto.prototype.unwrapKey = async function unwrapKey(format, wrappedKey,
     try {
       bytes = _withSecretBytes(unwrappingKey, function (kwBytes) {
         var d = nodeCrypto.createDecipheriv("aes" + unwrappingKey.algorithm.length + "-wrap", kwBytes, Buffer.from("A6A6A6A6A6A6A6A6", "hex"));
-        return Buffer.concat([d.update(wrapped), d.final()]);
+        return guard.secret.cipherFinish(d, wrapped, WebCryptoError, "webcrypto/operation", "the unwrapped key material");
       });
     } catch (e) { throw new WebCryptoError("webcrypto/operation", "unwrapKey: AES-KW key unwrap failed (integrity or length)", e); }
   } else {

package/lib/x509-sign.js

@@ -6,6 +6,7 @@
  * @module     pki.x509
  * @nav        Signing
  * @title      Certificates
+ * @fullname   X.509 certificates: parse, sign and inspect
  * @intro The X.509 certificate-issuance producing side. `pki.x509.sign` builds a `TBSCertificate`,
  *   signs it, and emits a `Certificate` (RFC 5280 sec. 4) that `pki.schema.x509.parse`,
  *   `pki.path.validate`, and OpenSSL all accept, self-signed or CA-signed, over any signature

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.5.15",
+  "version": "0.5.17",
   "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:75f14a7c-3b79-4cbc-8db6-fb4987becceb",
+  "serialNumber": "urn:uuid:b8b3d2cf-001e-4a5b-8644-a627ed3ce3c5",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-08-19T13:58:32.723Z",
+    "timestamp": "2026-08-20T14:50:41.972Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.5.15",
+      "bom-ref": "@blamejs/pki@0.5.17",
       "type": "application",
       "name": "pki",
-      "version": "0.5.15",
+      "version": "0.5.17",
       "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.15",
+      "purl": "pkg:npm/%40blamejs/pki@0.5.17",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.5.15",
+      "ref": "@blamejs/pki@0.5.17",
       "dependsOn": []
     }
   ]