@blamejs/pki 0.4.13 → 0.4.14

package/lib/key.js

@@ -120,11 +120,23 @@ async function encrypt(privateKey, password, opts) {
   var iterations = pbes2.assertIterations(opts.iterations == null ? 600000 : opts.iterations, _err, "key");
   var salt = opts.salt != null ? pbes2.assertSalt(guard.bytes.view(opts.salt, KeyError, "key/bad-input", "salt"), _err, "key") : nodeCrypto.randomBytes(16);
   var iv = nodeCrypto.randomBytes(16);
-  var dk = nodeCrypto.pbkdf2Sync(pbes2.passwordBytes(password, _err, "key"), salt, iterations, keyBits / 8, prfNode);
-  var ciphertext = pbes2.cbcEncrypt(dk, iv, der, keyBits);
-  var epki = b.sequence([pbes2.pbes2AlgId(salt, iterations, prf, cipherName, iv), b.octetString(ciphertext)]);
-  pkcs8.parseEncrypted(epki);   // self-check: the produced EncryptedPrivateKeyInfo re-parses
-  return opts.pem ? pkcs8.pemEncode(epki, "ENCRYPTED PRIVATE KEY") : epki;
+  // The derived key protects a PRIVATE KEY, so it is cleared as soon as the encryption is done. The
+  // caller's password is untouched -- passwordBytes returns a supplied Buffer as-is.
+  // A string / Uint8Array password is encoded into a buffer THIS toolkit allocated -- a credential
+  // copy -- so it is cleared once the derivation has consumed it. A caller-supplied Buffer is
+  // borrowed and left intact.
+  var pwK = pbes2.passwordBytesOwned(password, _err, "key");
+  var dk;
+  try { dk = nodeCrypto.pbkdf2Sync(pwK.bytes, salt, iterations, keyBits / 8, prfNode); }
+  finally { if (pwK.owned) guard.secret.zeroize(pwK.bytes, KeyError, "key/bad-input", "the password encoding"); }
+  try {
+    var ciphertext = pbes2.cbcEncrypt(dk, iv, der, keyBits);
+    var epki = b.sequence([pbes2.pbes2AlgId(salt, iterations, prf, cipherName, iv), b.octetString(ciphertext)]);
+    pkcs8.parseEncrypted(epki);   // self-check: the produced EncryptedPrivateKeyInfo re-parses
+    return opts.pem ? pkcs8.pemEncode(epki, "ENCRYPTED PRIVATE KEY") : epki;
+  } finally {
+    guard.secret.zeroize(dk, KeyError, "key/bad-input", "the password-derived encryption key");
+  }
 }
 
 /**
@@ -176,7 +188,13 @@ function _decryptPbes2(encAlg, ciphertext, password, opts) {
   // The shared PBES2 decrypt home (strict params + the uniform decrypt-failed on a wrong key / bad pad). The
   // plaintext re-parse below is the MAC-less PBES2-CBC integrity check (RFC 8018 sec. 8): a bad pad and a
   // valid pad whose plaintext is not a PrivateKeyInfo are indistinguishable, and it MUST run (never skipped).
-  var plaintext = pbes2.pbes2Decrypt(pbes2.passwordBytes(password, _err, "key"), encAlg.parameters, ciphertext, opts, _err, "key");
+  // A string / Uint8Array password is encoded into a buffer THIS toolkit allocated -- a credential
+  // copy -- so it is cleared once the derivation has consumed it. A caller-supplied Buffer is
+  // borrowed and left intact.
+  var pwD = pbes2.passwordBytesOwned(password, _err, "key");
+  var plaintext;
+  try { plaintext = pbes2.pbes2Decrypt(pwD.bytes, encAlg.parameters, ciphertext, opts, _err, "key"); }
+  finally { if (pwD.owned) guard.secret.zeroize(pwD.bytes, KeyError, "key/bad-input", "the password encoding"); }
   try { pkcs8.parse(plaintext); }
   catch (_e) { throw _err("key/decrypt-failed", "decryption failed"); }
   return plaintext;

package/lib/pbes2.js

@@ -38,10 +38,17 @@ var CONTENT_KEYBITS = {}, CONTENT_MODE = {};
 
 // A password is an octet string (RFC 8018 sec. 2): a string is UTF-8-encoded deterministically (correct for
 // non-ASCII, and byte-identical to OpenSSL), a Buffer/Uint8Array used verbatim.
-function passwordBytes(p, E, prefix) {
-  if (Buffer.isBuffer(p)) return p;
-  if (p instanceof Uint8Array) return Buffer.from(p);
-  if (typeof p === "string") return Buffer.from(p, "utf8");
+function passwordBytes(p, E, prefix) { return passwordBytesOwned(p, E, prefix).bytes; }
+
+// The same conversion, reporting OWNERSHIP. A string or Uint8Array password is encoded into a fresh
+// Buffer this toolkit allocated -- a credential copy that must be cleared once the derivation has
+// consumed it -- while a caller-supplied Buffer is BORROWED and must be left intact. Without this
+// distinction a call site can only be safe by leaving every password encoding readable, which is
+// the common case, since a password arrives as a string far more often than as a Buffer.
+function passwordBytesOwned(p, E, prefix) {
+  if (Buffer.isBuffer(p)) return { bytes: p, owned: false };
+  if (p instanceof Uint8Array) return { bytes: Buffer.from(p), owned: true };
+  if (typeof p === "string") return { bytes: Buffer.from(p, "utf8"), owned: true };
   throw E(prefix + "/bad-input", "a password must be a string, Buffer, or Uint8Array");
 }
 
@@ -148,8 +155,19 @@ function pbes2Encrypt(pwBytes, plaintext, opts, E, prefix) {
   var iterations = assertIterations(opts.iterations == null ? 2048 : opts.iterations, E, prefix);
   var salt = opts.salt != null ? assertSalt(opts.salt, E, prefix) : nodeCrypto.randomBytes(16);
   var iv = opts.iv != null ? opts.iv : nodeCrypto.randomBytes(16);
+  // The derived key is this module's allocation and protects the caller's plaintext -- a private key
+  // in the pkcs8 / pkcs12 callers -- so it is cleared once the encryption has consumed it. pwBytes is
+  // NOT: the caller formatted it and may still own the buffer.
   var key = nodeCrypto.pbkdf2Sync(pwBytes, salt, iterations, keyBits / 8, prfNode);
-  return { algId: pbes2AlgId(salt, iterations, prf, cipherName, iv), ct: cbcEncrypt(key, iv, plaintext, keyBits) };
+  try {
+    return { algId: pbes2AlgId(salt, iterations, prf, cipherName, iv), ct: cbcEncrypt(key, iv, plaintext, keyBits) };
+  } 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
+    // allocated pbkdf2 buffer cannot be detached.
+    guard.secret.zeroize(key, E, prefix + "/bad-input", "the password-derived encryption key");
+  }
 }
 
 // PBES2 AES-CBC DECRYPT: parse the PBES2 params (PBKDF2 kdf + AES-CBC scheme), derive the key from
@@ -182,6 +200,7 @@ function pbes2Decrypt(pwBytes, params, ciphertext, opts, E, prefix) {
   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"); }
+  finally { guard.secret.zeroize(dk, E, prefix + "/bad-input", "the password-derived decryption key"); }
 }
 
 // ---- PBMAC1 (RFC 9579 / RFC 8018 App. A.5) : PBKDF2 -> HMAC over a message --
@@ -207,14 +226,24 @@ function pbmac1(pwBytes, salt, iterationCount, keyLength, prfHash, macHash, mess
   return subtle.importKey("raw", pwBytes, { name: "PBKDF2" }, false, ["deriveBits"]).then(function (baseKey) {
     return subtle.deriveBits({ name: "PBKDF2", salt: salt, iterations: iterationCount, hash: prfHash }, baseKey, keyLength * 8);
   }).then(function (bits) {
-    return subtle.importKey("raw", Buffer.from(bits), { name: "HMAC", hash: macHash }, false, ["sign"]).then(function (hmacKey) {
+    // The derived MAC key is this function's allocation, in two forms: the ArrayBuffer deriveBits
+    // returned and the Buffer view over it that is imported. Clearing the view clears both, and it
+    // runs whether the signing succeeds or throws -- the sibling PBES2 encrypt/decrypt above clear
+    // their derived keys, and every PBMAC1 consumer (PKCS#12 build and verification) inherits this.
+    var mk = Buffer.from(bits);
+    return subtle.importKey("raw", mk, { name: "HMAC", hash: macHash }, false, ["sign"]).then(function (hmacKey) {
       return subtle.sign({ name: "HMAC" }, hmacKey, message);
+    }).finally(function () {
+      // pbmac1 takes no caller error factory, and this key is engine-adjacent, so the engine's
+      // typed class is the right currency -- a raw TypeError must never escape a lib boundary.
+      // Unreachable in practice: a freshly allocated Buffer cannot be detached.
+      guard.secret.zeroize(mk, webcrypto.WebCryptoError, "webcrypto/operation", "the PBMAC1 key");
     });
   }).then(function (sig) { return Buffer.from(sig); });
 }
 
 module.exports = {
-  passwordBytes: passwordBytes, assertIterations: assertIterations, assertSalt: assertSalt,
+  passwordBytes: passwordBytes, passwordBytesOwned: passwordBytesOwned, assertIterations: assertIterations, assertSalt: assertSalt,
   prfNodeByName: prfNodeByName, prfNodeByOid: prfNodeByOid,
   pbkdf2ParamsSeq: pbkdf2ParamsSeq, pbes2AlgId: pbes2AlgId, parsePbkdf2Params: parsePbkdf2Params,
   requireChildren: requireChildren, seqChildren: seqChildren,

package/lib/pkcs12-build.js

@@ -100,7 +100,17 @@ var DIGEST_NAME = { sha1: "sha1", sha256: "sha256", sha384: "sha384", sha512: "s
 // RFC 7292 App. B.1: a PKCS#12 password is the BMPString (UTF-16BE) encoding of the string plus a trailing
 // 2-byte NULL terminator. "Beavis" -> 14 bytes. A non-BMP scalar (surrogate) is rejected. A Buffer/Uint8Array
 // is taken verbatim as already-formatted bytes (an escape hatch for a caller that pre-encodes).
-function _p12Password(pw) {
+function _p12Password(pw) { return _p12PasswordOwned(pw).bytes; }
+
+// 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
+// buffer this module allocated, which it must clear once a derivation has consumed it.
+function _p12PasswordOwned(pw) {
+  if (Buffer.isBuffer(pw)) return { bytes: pw, owned: false };
+  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);
@@ -148,16 +158,43 @@ function _blockFill(src, blockSize) {
 function _p12Kdf(hashName, id, pwBytes, salt, iterations, nBytes) {
   var uv = P12_KDF_UV[hashName], u = uv.u, v = uv.v;
   var D = Buffer.alloc(v, id);                                          // step 1: v copies of the ID diversifier
-  var I = Buffer.concat([_blockFill(salt, v), _blockFill(pwBytes, v)]); // steps 2-4: I = S || P
+  // Each fill is a full block-repeated copy of the salt / password; only their concatenation is
+  // used, so the sources are cleared rather than abandoned.
+  var sFill = _blockFill(salt, v), pFill = _blockFill(pwBytes, v);
+  var I = Buffer.concat([sFill, pFill]);                                // steps 2-4: I = S || P
+  guard.secret.zeroizeAll([sFill, pFill], Pkcs12Error, "pkcs12/bad-input", "a key-derivation fill");
   var c = Math.ceil(nBytes / u);                                        // step 5
-  var out = Buffer.alloc(0);
+  // The accumulator is allocated ONCE at its final size. Growing it with Buffer.concat per round
+  // would abandon a password-derived copy of everything derived so far on every iteration, and
+  // those copies could not be reached to clear. Each intermediate digest is cleared as it is
+  // superseded, so only the value actually in use is ever readable.
+  var out = Buffer.alloc(c * u);
   for (var i = 0; i < c; i++) {                                         // step 6
     var A = Buffer.concat([D, I]);
-    for (var r = 0; r < iterations; r++) A = nodeCrypto.createHash(hashName).update(A).digest();   // 6A: A = H^r(D||I)
-    out = Buffer.concat([out, A]);                                      // step 7 (accumulate A_1..A_c)
-    if (i < c - 1) _kdfStepC(I, _blockFill(A, v), v);                   // 6B+6C: modify I for the next block
+    for (var r = 0; r < iterations; r++) {                              // 6A: A = H^r(D||I)
+      var prev = A;
+      A = nodeCrypto.createHash(hashName).update(A).digest();
+      guard.secret.zeroize(prev, Pkcs12Error, "pkcs12/bad-input", "a key-derivation intermediate");
+    }
+    A.copy(out, i * u);                                                 // step 7 (accumulate A_1..A_c)
+    if (i < c - 1) {                                                    // 6B+6C: modify I for the next block
+      var B = _blockFill(A, v);                                         // a full password-derived block
+      _kdfStepC(I, B, v);
+      guard.secret.zeroize(B, Pkcs12Error, "pkcs12/bad-input", "a key-derivation intermediate");
+    }
+    guard.secret.zeroize(A, Pkcs12Error, "pkcs12/bad-input", "a key-derivation block");
   }
-  return out.subarray(0, nBytes);                                      // step 8: first nBytes of A
+  // I is S || P -- it carries the password bytes -- and is finished with here.
+  guard.secret.zeroize(I, Pkcs12Error, "pkcs12/bad-input", "the key-derivation input block");
+  // Step 8 is "the first nBytes of A", but returning a SUBARRAY would hand back a view over a
+  // larger allocation: a caller clearing what it received would leave the rest of the final digest
+  // block -- password-derived material -- readable in the same backing buffer (15 unused bytes
+  // behind a 5-byte RC2 key, 16 behind a 24-byte 3DES key). Copy into an exact-sized buffer the
+  // caller wholly owns, and clear the oversized accumulator here, where it was allocated.
+  var exact = Buffer.alloc(nBytes);
+  out.copy(exact, 0, 0, nBytes);
+  guard.secret.zeroize(out, Pkcs12Error, "pkcs12/bad-input", "the key-derivation accumulator");
+  return exact;
 }
 
 // RFC 7292 App. B.2 step 6C: treat I as consecutive v-byte blocks and set each I_j = (I_j + B + 1) mod 2^(8v)
@@ -344,10 +381,18 @@ async function _buildMacData(macOpts, sharedPassword, authSafeDer) {
     var node = DIGEST_NAME[hash];
     if (!node || !P12_KDF_UV[node]) throw _err("pkcs12/unsupported-algorithm", "unsupported classic MAC hash " + JSON.stringify(hash) + " (sha1 / sha256 / sha384 / sha512)");
     var iter = _assertMacIter(macOpts.iterations == null ? DEFAULT_MAC_ITER : macOpts.iterations, CLASSIC_MAC_MAX_ITERATIONS);
-    var macKey = _p12Kdf(node, 3, _p12Password(password), salt, iter, P12_KDF_UV[node].u);   // classic KDF -> BMPString
-    var digest = nodeCrypto.createHmac(node, macKey).update(authSafeDer).digest();
-    var digestInfo = b.sequence([b.sequence([b.oid(O(node)), b.nullValue()]), b.octetString(digest)]);
-    return b.sequence([digestInfo, b.octetString(salt), b.integer(BigInt(iter))]);
+    // _p12Password always ALLOCATES (it re-encodes to BMPString + NULL), so its result is this
+    // module's own credential copy and is cleared once the derivation has consumed it.
+    var macPw = _p12PasswordOwned(password);
+    var macKey = _p12Kdf(node, 3, macPw.bytes, salt, iter, P12_KDF_UV[node].u);   // classic KDF -> BMPString
+    if (macPw.owned) guard.secret.zeroize(macPw.bytes, Pkcs12Error, "pkcs12/bad-input", "the password encoding");
+    try {
+      var digest = nodeCrypto.createHmac(node, macKey).update(authSafeDer).digest();
+      var digestInfo = b.sequence([b.sequence([b.oid(O(node)), b.nullValue()]), b.octetString(digest)]);
+      return b.sequence([digestInfo, b.octetString(salt), b.integer(BigInt(iter))]);
+    } finally {
+      guard.secret.zeroize(macKey, Pkcs12Error, "pkcs12/bad-input", "the password-derived MAC key");
+    }
   }
   if (algorithm === "pbmac1") {
     var prf = PBMAC1_PRF[hash];
@@ -495,8 +540,11 @@ async function verifyMac(pfx, password, opts) {
     if (!P12_KDF_UV[node]) throw _err("pkcs12/unsupported-algorithm", "unsupported classic MAC hash " + m.mac.hashName);
     // The iteration count and salt are attacker-controlled work factors: bound them BEFORE the KDF runs.
     _capWork(m.mac.iterations, m.mac.macSalt, opts, undefined, CLASSIC_MAC_MAX_ITERATIONS);
-    var macKey = _p12Kdf(node, 3, _p12Password(password), m.mac.macSalt, m.mac.iterations, P12_KDF_UV[node].u);   // classic KDF -> BMPString
-    computed = nodeCrypto.createHmac(node, macKey).update(m.macedBytes).digest();
+    var vMacPw = _p12PasswordOwned(password);
+    var macKey = _p12Kdf(node, 3, vMacPw.bytes, m.mac.macSalt, m.mac.iterations, P12_KDF_UV[node].u);   // classic KDF -> BMPString
+    if (vMacPw.owned) guard.secret.zeroize(vMacPw.bytes, Pkcs12Error, "pkcs12/bad-input", "the password encoding");
+    try { computed = nodeCrypto.createHmac(node, macKey).update(m.macedBytes).digest(); }
+    finally { guard.secret.zeroize(macKey, Pkcs12Error, "pkcs12/bad-input", "the password-derived MAC key"); }
   } else {
     var kdf = m.mac.pbmac1.kdf;
     var prfWc = PRF_WC[kdf.prfName];
@@ -693,17 +741,22 @@ function _decryptLegacyPbe(ea, ct, password, opts, budget) {
   var u = P12_KDF_UV[scheme.hash].u;
   budget.rounds -= (Math.ceil(scheme.keyLen / u) + Math.ceil(scheme.ivLen / u)) * iterations;
   if (budget.rounds < 0) throw _err("pkcs12/iteration-limit", "the store's aggregate legacy PBE key-derivation work exceeds the budget (a hostile many-bag store)");
-  var p12pw = _p12Password(password);   // App. B.1 BMPString + NULL (NOT the PBES2 UTF-8 encoding)
-  var keyM = _p12Kdf(scheme.hash, 1, p12pw, salt, iterations, scheme.keyLen);
-  var iv = _p12Kdf(scheme.hash, 2, p12pw, salt, iterations, scheme.ivLen);
+  var p12pw = _p12PasswordOwned(password);   // App. B.1 BMPString + NULL (NOT the PBES2 UTF-8 encoding)
+  var keyM = _p12Kdf(scheme.hash, 1, p12pw.bytes, salt, iterations, scheme.keyLen);
+  var iv = _p12Kdf(scheme.hash, 2, p12pw.bytes, salt, iterations, scheme.ivLen);
+  if (p12pw.owned) guard.secret.zeroize(p12pw.bytes, Pkcs12Error, "pkcs12/bad-input", "the password encoding");
   // BOTH ciphers funnel through ONE uniform failure (same code AND message), so a bad-pad (secret-dependent)
   // and a valid-pad-wrong-content outcome are indistinguishable -- no CBC padding oracle (RFC 8018 sec. 8). RC2
   // is unavailable in node; the in-tree RFC 2268 primitive fills the gap and its typed reject is normalized here.
+  // keyM is a password-derived key this function allocated -- the PBES2 arm of the same dispatch
+  // clears its equivalent, so this arm owes it too, on the failing path an attacker drives. The
+  // derived IV is not secret and is left alone.
   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()]);
   } catch (_e) { throw _err("pkcs12/decrypt-failed", "decryption failed"); }
+  finally { guard.secret.zeroize(keyM, Pkcs12Error, "pkcs12/bad-input", "the password-derived decryption key"); }
 }
 
 // Decrypt a PBES2 (RFC 8018) or legacy-PBE (RFC 7292 App. C) bag/safe -- dispatch on the encryptionAlgorithm

package/lib/webcrypto.js

@@ -467,25 +467,31 @@ SubtleCrypto.prototype.encrypt = async function encrypt(algorithm, key, data) {
     var iv = _toBuf(alg.iv, "AES-GCM iv");
     var aad = alg.additionalData ? _toBuf(alg.additionalData, "AES-GCM aad") : null;
     return _toArrayBuffer(_runCipher(function () {
-      var cipher = nodeCrypto.createCipheriv("aes-" + key.algorithm.length + "-gcm", _secretBytes(key), iv, { authTagLength: (alg.tagLength || 128) / 8 });
-      if (aad) cipher.setAAD(aad);
-      var ct = Buffer.concat([cipher.update(buf), cipher.final()]);
-      return Buffer.concat([ct, cipher.getAuthTag()]);
+      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()]);
+        return Buffer.concat([ct, cipher.getAuthTag()]);
+      });
     }, "encrypt"));
   }
   if (name === "AES-CBC") {
     var cbcIv = _toBuf(alg.iv, "AES-CBC iv");
     return _toArrayBuffer(_runCipher(function () {
-      var c2 = nodeCrypto.createCipheriv("aes-" + key.algorithm.length + "-cbc", _secretBytes(key), cbcIv);
-      return Buffer.concat([c2.update(buf), c2.final()]);
+      return _withSecretBytes(key, function (kb) {
+        var c2 = nodeCrypto.createCipheriv("aes-" + key.algorithm.length + "-cbc", kb, cbcIv);
+        return Buffer.concat([c2.update(buf), c2.final()]);
+      });
     }, "encrypt"));
   }
   if (name === "AES-CTR") {
     _requireCtrLength128(alg);
     var ctrCounter = _toBuf(alg.counter, "AES-CTR counter");
     return _toArrayBuffer(_runCipher(function () {
-      var c3 = nodeCrypto.createCipheriv("aes-" + key.algorithm.length + "-ctr", _secretBytes(key), ctrCounter);
-      return Buffer.concat([c3.update(buf), c3.final()]);
+      return _withSecretBytes(key, function (kb) {
+        var c3 = nodeCrypto.createCipheriv("aes-" + key.algorithm.length + "-ctr", kb, ctrCounter);
+        return Buffer.concat([c3.update(buf), c3.final()]);
+      });
     }, "encrypt"));
   }
   throw new WebCryptoError("webcrypto/not-supported", "encrypt: unsupported algorithm " + JSON.stringify(name));
@@ -499,11 +505,16 @@ SubtleCrypto.prototype.decrypt = async function decrypt(algorithm, key, data) {
   if (!ENCRYPT_DECRYPT_NAMES[name]) throw new WebCryptoError("webcrypto/not-supported", "decrypt: unsupported algorithm " + JSON.stringify(name));
   _requireAlgMatch(alg, key, "decrypt");
   if (name === "RSA-OAEP") {
-    return _toArrayBuffer(nodeCrypto.privateDecrypt({
+    // For a CMS key-transport recipient this plaintext IS the recovered content-encryption key, and
+    // _toArrayBuffer copies it -- so the node-allocated buffer is finished with the moment the copy
+    // exists, and nothing outside this function can reach it to clear it.
+    var oaepOut = nodeCrypto.privateDecrypt({
       key: key._handle, padding: nodeCrypto.constants.RSA_PKCS1_OAEP_PADDING,
       oaepHash: _hashNode(key.algorithm.hash, "decrypt"),
       oaepLabel: alg.label ? _toBuf(alg.label, "decrypt label") : undefined,
-    }, buf));
+    }, buf);
+    try { return _toArrayBuffer(oaepOut); }
+    finally { guard.secret.zeroize(oaepOut, WebCryptoError, "webcrypto/operation", "the RSA-OAEP decryption output"); }
   }
   if (name === "AES-GCM") {
     var tagLen = (alg.tagLength || 128) / 8;
@@ -513,31 +524,71 @@ SubtleCrypto.prototype.decrypt = async function decrypt(algorithm, key, data) {
     var tag = buf.subarray(buf.length - tagLen);
     var gcmAad = alg.additionalData ? _toBuf(alg.additionalData, "AES-GCM aad") : null;
     return _toArrayBuffer(_runCipher(function () {
-      var d = nodeCrypto.createDecipheriv("aes-" + key.algorithm.length + "-gcm", _secretBytes(key), iv, { authTagLength: tagLen });
-      if (gcmAad) d.setAAD(gcmAad);
-      d.setAuthTag(tag);
-      return Buffer.concat([d.update(ct), d.final()]);
+      return _withSecretBytes(key, function (kb) {
+        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()]);
+      });
     }, "decrypt"));
   }
   if (name === "AES-CBC") {
     var cbcIv2 = _toBuf(alg.iv, "AES-CBC iv");
     return _toArrayBuffer(_runCipher(function () {
-      var d2 = nodeCrypto.createDecipheriv("aes-" + key.algorithm.length + "-cbc", _secretBytes(key), cbcIv2);
-      return Buffer.concat([d2.update(buf), d2.final()]);
+      return _withSecretBytes(key, function (kb) {
+        var d2 = nodeCrypto.createDecipheriv("aes-" + key.algorithm.length + "-cbc", kb, cbcIv2);
+        return Buffer.concat([d2.update(buf), d2.final()]);
+      });
     }, "decrypt"));
   }
   if (name === "AES-CTR") {
     _requireCtrLength128(alg);
     var ctrCounter2 = _toBuf(alg.counter, "AES-CTR counter");
     return _toArrayBuffer(_runCipher(function () {
-      var d3 = nodeCrypto.createDecipheriv("aes-" + key.algorithm.length + "-ctr", _secretBytes(key), ctrCounter2);
-      return Buffer.concat([d3.update(buf), d3.final()]);
+      return _withSecretBytes(key, function (kb) {
+        var d3 = nodeCrypto.createDecipheriv("aes-" + key.algorithm.length + "-ctr", kb, ctrCounter2);
+        return Buffer.concat([d3.update(buf), d3.final()]);
+      });
     }, "decrypt"));
   }
   throw new WebCryptoError("webcrypto/not-supported", "decrypt: unsupported algorithm " + JSON.stringify(name));
 };
 
-function _secretBytes(key) { return key._handle.export(); }
+// _withSecretBytes(key, fn) -- export a secret key's raw material, hand it to fn, and wipe
+// the export the moment fn is done with it (NIST SP 800-227 RS5 / sec. 4.2, RFC 9629 sec. 7).
+//
+// export() allocates a FRESH Buffer this module owns; the CryptoKey keeps its own copy inside
+// the node KeyObject, so wiping the export never destroys the caller's key or the key itself.
+// Node's cipher and KDF constructors copy the key into their own context, so the export's
+// useful life ends when the operation returns.
+//
+// This is the ONLY way to reach raw secret key material: there is deliberately no unwiped
+// `_secretBytes(key)` primitive to call, because a new consumer that forgot the wipe was the
+// live defect this replaced -- the AES content-encryption paths and two of the three KDF arms
+// each exported the key and left it readable while their sibling arms did not.
+//
+// When fn returns a PROMISE the wipe rides the settlement rather than the callback's return.
+// Node's async primitives copy their inputs when the job is queued, so an eager wipe would not
+// corrupt today's derivations -- but that is an implementation detail of the provider, not a
+// documented guarantee, and the export's useful life is the operation's, not the callback's.
+// Deferring costs nothing and keeps the rule true for any future asynchronous consumer.
+function _withSecretBytes(key, fn) {
+  var kb = key._handle.export();
+  // Set once the export's lifetime has been handed to the promise handlers below, so the
+  // `finally` does not clear a buffer the pending operation is still entitled to.
+  var deferred = false;
+  try {
+    var out = fn(kb);
+    if (out && typeof out.then === "function") {
+      deferred = true;
+      return out.then(function (v) { _wipeExport(kb); return v; }, function (e) { _wipeExport(kb); throw e; });
+    }
+    return out;
+  } finally {
+    if (!deferred) guard.secret.zeroize(kb, WebCryptoError, "webcrypto/operation", "the exported key material");
+  }
+}
+function _wipeExport(kb) { guard.secret.zeroize(kb, WebCryptoError, "webcrypto/operation", "the exported key material"); }
 
 // AES-CTR: node always treats the full 128-bit block as the counter and
 // never reads the spec's `length` (counter-width) parameter. A length < 128
@@ -595,41 +646,62 @@ async function _deriveBitsRaw(alg, key, length) {
   if (name === "ECDH" || name === "X25519" || name === "X448") {
     _requireAlgMatch(alg, alg.public, name + " public key");
     _requireOwnKey(alg.public, "deriveBits public key");
+    // The provider hands back z (ECDH) / mz (X25519, X448) in a Buffer this module owns. It is
+    // the raw key-agreement shared secret -- the same class of material as a KEM shared secret --
+    // so it is wiped once the caller's copy exists, on EVERY exit including the over-request
+    // throw. _toArrayBuffer copies via ArrayBuffer.slice, so the returned bits are unaffected.
     var secret = nodeCrypto.diffieHellman({ privateKey: key._handle, publicKey: alg.public._handle });
-    if (length == null) return _toArrayBuffer(secret);
-    _requireDeriveLength(length, name);
-    // subarray clamps at the end of the secret, so an unchecked over-request
-    // would silently return fewer bytes than asked. W3C deriveBits: throw an
-    // OperationError when the requested length cannot be satisfied.
-    if (length / 8 > secret.length) {
-      throw new WebCryptoError("webcrypto/operation", name + ": requested " + length + " bits but the shared secret has " + (secret.length * 8));
+    try {
+      if (length == null) return _toArrayBuffer(secret);
+      _requireDeriveLength(length, name);
+      // subarray clamps at the end of the secret, so an unchecked over-request
+      // would silently return fewer bytes than asked. W3C deriveBits: throw an
+      // OperationError when the requested length cannot be satisfied.
+      if (length / 8 > secret.length) {
+        throw new WebCryptoError("webcrypto/operation", name + ": requested " + length + " bits but the shared secret has " + (secret.length * 8));
+      }
+      return _toArrayBuffer(secret.subarray(0, length / 8));
+    } finally {
+      guard.secret.zeroize(secret, WebCryptoError, "webcrypto/operation", "the raw key-agreement shared secret");
     }
-    return _toArrayBuffer(secret.subarray(0, length / 8));
   }
   if (name === "HKDF") {
     _requireDeriveLength(length, "HKDF");
-    // _secretBytes EXPORTS the key material into a fresh Buffer this module owns -- for a KEM flow
-    // that Buffer is the shared secret itself. It is a controllable allocation, not one of the
-    // runtime-internal copies the best-effort caveat covers, so it is wiped once HKDF has consumed it.
-    var ikm = _secretBytes(key);
-    try {
+    // The export is a fresh Buffer this module owns -- for a KEM flow it is the shared secret
+    // itself. A controllable allocation, not one of the runtime-internal copies the best-effort
+    // caveat covers, so it is wiped once the derivation has consumed it.
+    return _withSecretBytes(key, function (ikm) {
       var derived = nodeCrypto.hkdfSync(_hashNode(alg.hash, "HKDF"), ikm, _toBuf(alg.salt, "HKDF salt"), _toBuf(alg.info || Buffer.alloc(0), "HKDF info"), length / 8);
       return derived instanceof ArrayBuffer ? derived : _toArrayBuffer(Buffer.from(derived));
-    } finally {
-      guard.secret.zeroize(ikm, WebCryptoError, "webcrypto/operation", "the HKDF input key material");
-    }
+    });
   }
   if (name === "PBKDF2") {
     _requireDeriveLength(length, "PBKDF2");
-    var out = await _pbkdf2Async(_secretBytes(key), _toBuf(alg.salt, "PBKDF2 salt"), alg.iterations, length / 8, _hashNode(alg.hash, "PBKDF2"));
-    return _toArrayBuffer(out);
+    // The derivation is asynchronous; _withSecretBytes defers the wipe to the promise's
+    // settlement so the export outlives the operation rather than the callback.
+    return _withSecretBytes(key, function (pw) {
+      return _pbkdf2Async(pw, _toBuf(alg.salt, "PBKDF2 salt"), alg.iterations, length / 8, _hashNode(alg.hash, "PBKDF2"))
+        .then(function (out) {
+          // _toArrayBuffer COPIES, so the node-allocated derivation buffer is finished with the
+          // moment the copy exists -- and nothing else can reach it to clear it.
+          try { return _toArrayBuffer(out); }
+          finally { guard.secret.zeroize(out, WebCryptoError, "webcrypto/operation", "the PBKDF2 output"); }
+        });
+    });
   }
   if (name === "X963KDF") {
     // ANSI-X9.63 / SEC1 sec. 3.6.1 single-step KDF: K = H(Z || INT32(counter) || SharedInfo)
     // concatenated over counter = 1, 2, ... The RFC 5753 kari KEK derivation; the base key holds
     // the ECDH shared secret Z, alg.info holds the DER ECC-CMS-SharedInfo.
     _requireDeriveLength(length, "X963KDF");
-    return _toArrayBuffer(_x963Kdf(_hashNode(alg.hash, "X963KDF"), _secretBytes(key), _toBuf(alg.info || Buffer.alloc(0), "X963KDF SharedInfo"), length / 8));
+    // The base key here HOLDS the ECDH shared secret Z of an RFC 5753 kari, so this export is
+    // exactly as sensitive as the raw agreement secret wiped above.
+    return _withSecretBytes(key, function (z) {
+      var derived = _x963Kdf(_hashNode(alg.hash, "X963KDF"), z, _toBuf(alg.info || Buffer.alloc(0), "X963KDF SharedInfo"), length / 8);
+      // Same as PBKDF2 above: the copy is what the caller receives, so the derived buffer is cleared.
+      try { return _toArrayBuffer(derived); }
+      finally { guard.secret.zeroize(derived, WebCryptoError, "webcrypto/operation", "the X9.63 KDF output"); }
+    });
   }
   throw new WebCryptoError("webcrypto/not-supported", "deriveBits: unsupported algorithm " + JSON.stringify(name));
 }
@@ -644,7 +716,16 @@ function _x963Kdf(hashNode, z, sharedInfo, lenBytes) {
     var h = nodeCrypto.createHash(hashNode).update(z).update(ctr).update(sharedInfo).digest();
     blocks.push(h); got += h.length; counter += 1;
   }
-  return Buffer.concat(blocks).subarray(0, lenBytes);
+  // Return an exact-sized buffer the caller wholly owns, not a VIEW over the joined blocks: a
+  // caller clearing what it received would otherwise leave the unused tail of the final digest
+  // block -- derived from the shared secret -- readable behind it. The accumulator and the
+  // per-block digests are cleared here, where they were allocated.
+  var joined = Buffer.concat(blocks);
+  var exact = Buffer.alloc(lenBytes);
+  joined.copy(exact, 0, 0, lenBytes);
+  guard.secret.zeroize(joined, WebCryptoError, "webcrypto/operation", "the KDF accumulator");
+  for (var bi = 0; bi < blocks.length; bi++) guard.secret.zeroize(blocks[bi], WebCryptoError, "webcrypto/operation", "a KDF block");
+  return exact;
 }
 
 SubtleCrypto.prototype.deriveBits = async function deriveBits(algorithm, key, length) {
@@ -686,8 +767,12 @@ SubtleCrypto.prototype.deriveKey = async function deriveKey(algorithm, baseKey,
     // material; a KDF base has no implicit output size and fails closed.
     bits = dk.length != null ? dk.length : null;
   }
+  // The derived bits are the KEY -- importKey copies them into a KeyObject, so this buffer is a
+  // transient copy nothing else can reach once the CryptoKey exists, and it is cleared on the
+  // failing import too (a bad derivedKeyType is caller-controlled).
   var raw = await _deriveBitsRaw(alg, baseKey, bits);
-  return this.importKey("raw", raw, dk, extractable, keyUsages);
+  try { return await this.importKey("raw", raw, dk, extractable, keyUsages); }
+  finally { guard.secret.zeroize(new Uint8Array(raw), WebCryptoError, "webcrypto/operation", "the derived key material"); }
 };
 
 // ML-KEM (FIPS 203) key encapsulation over Node's crypto.encapsulate/decapsulate.
@@ -766,8 +851,12 @@ SubtleCrypto.prototype.decapsulateBits = async function decapsulateBits(algorith
 };
 
 SubtleCrypto.prototype.wrapKey = async function wrapKey(format, key, wrappingKey, wrapAlgorithm) {
+  //  is the PLAINTEXT serialization of the key being wrapped -- the very material the wrap
+  // exists to protect. It is this function's allocation and is cleared once the wrap has consumed
+  // it, on the delegated branch as well as the AES-KW one.
   var exported = await this.exportKey(format, key);
   var bytes = (format === "jwk") ? Buffer.from(JSON.stringify(exported)) : Buffer.from(exported);
+  try {
   var alg = _normalizeAlg(wrapAlgorithm, "wrapKey");
   _requireUsage(wrappingKey, "wrapKey");
   if (alg.name !== "AES-KW" && !ENCRYPT_DECRYPT_NAMES[alg.name]) throw new WebCryptoError("webcrypto/not-supported", "wrapKey: unsupported algorithm " + JSON.stringify(alg.name));
@@ -782,17 +871,24 @@ SubtleCrypto.prototype.wrapKey = async function wrapKey(format, key, wrappingKey
     // The mirror of unwrapKey below: in a KEM flow this export is the SENDER's copy of the same
     // key-encryption key, so leaving it unwiped would keep a full copy of the KEK alive for the
     // process lifetime and make the wipes the CMS layer performs pointless in the encrypt direction.
-    var wkBytes = null;
     try {
-      wkBytes = _secretBytes(wrappingKey);
-      var c = nodeCrypto.createCipheriv("aes" + wrappingKey.algorithm.length + "-wrap", wkBytes, Buffer.from("A6A6A6A6A6A6A6A6", "hex"));
-      return _toArrayBuffer(Buffer.concat([c.update(bytes), c.final()]));
+      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()]));
+      });
     } catch (e) { throw new WebCryptoError("webcrypto/operation", "wrapKey: AES-KW key wrap failed", e); }
-    finally { guard.secret.zeroize(wkBytes, WebCryptoError, "webcrypto/operation", "the AES-KW wrapping key"); }
   }
   // Delegate to a content-encryption algorithm (RSA-OAEP / AES-GCM).
   var wrapKeyClone = _cloneWithUsage(wrappingKey, "encrypt");
-  return this.encrypt(wrapAlgorithm, wrapKeyClone, bytes);
+  return await this.encrypt(wrapAlgorithm, wrapKeyClone, bytes);
+  } finally {
+    // Clearing  also clears the export it came from: for every non-jwk format
+    // Buffer.from(<ArrayBuffer>) is a VIEW over that buffer, not a copy, so one wipe covers both.
+    // A "jwk" export is the residual -- its key material lives in immutable JavaScript strings that
+    // no code can overwrite -- so wrapping a jwk serialization cannot offer this guarantee, and the
+    // documentation does not claim it does.
+    guard.secret.zeroize(bytes, WebCryptoError, "webcrypto/operation", "the exported key being wrapped");
+  }
 };
 
 SubtleCrypto.prototype.unwrapKey = async function unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgorithm, unwrappedKeyAlgorithm, extractable, keyUsages) {
@@ -817,16 +913,15 @@ SubtleCrypto.prototype.unwrapKey = async function unwrapKey(format, wrappedKey,
     // The exported wrapping key is a Buffer this module owns; in a KEM flow it is the KEK derived
     // from the shared secret, so it is wiped once the unwrap has consumed it -- on the failing path
     // too, which is the one an attacker induces by tampering with the wrapped key.
-    // Declared outside so the finally can reach it, but EXPORTED INSIDE the try: a key whose handle
-    // cannot be exported must still surface the typed verdict this branch promises, not a raw node
-    // TypeError -- and a non-PkiError throw would also break the fuzz-harness contract.
-    var kwBytes = null;
+    // The export happens INSIDE the try: a key whose handle cannot be exported must still surface
+    // the typed verdict this branch promises, not a raw node TypeError -- and a non-PkiError throw
+    // would also break the fuzz-harness contract.
     try {
-      kwBytes = _secretBytes(unwrappingKey);
-      var d = nodeCrypto.createDecipheriv("aes" + unwrappingKey.algorithm.length + "-wrap", kwBytes, Buffer.from("A6A6A6A6A6A6A6A6", "hex"));
-      bytes = Buffer.concat([d.update(wrapped), d.final()]);
+      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()]);
+      });
     } catch (e) { throw new WebCryptoError("webcrypto/operation", "unwrapKey: AES-KW key unwrap failed (integrity or length)", e); }
-    finally { guard.secret.zeroize(kwBytes, WebCryptoError, "webcrypto/operation", "the AES-KW unwrapping key"); }
   } else {
     var unwrapKeyClone = _cloneWithUsage(unwrappingKey, "decrypt");
     bytes = Buffer.from(await this.decrypt(unwrapAlgorithm, unwrapKeyClone, wrappedKey));
@@ -1101,16 +1196,13 @@ SubtleCrypto.prototype.exportKey = async function exportKey(format, key) {
   if (!key.extractable) throw new WebCryptoError("webcrypto/invalid-access", "key is not extractable");
   if (format === "jwk") return key._handle.export({ format: "jwk" });
   if (key.type === "secret") {
-    // export() allocates a fresh Buffer holding the secret key, and _toArrayBuffer copies it via
-    // ArrayBuffer.slice -- so the export Buffer is a controllable allocation nothing references once
-    // the copy exists. Wiped in a `finally` so the unsupported-format throw below clears it too.
-    var raw = key._handle.export();
-    try {
+    // The export is a fresh Buffer holding the secret key, and _toArrayBuffer copies it via
+    // ArrayBuffer.slice -- so the export is a controllable allocation nothing references once the
+    // copy exists. The unsupported-format throw below clears it too.
+    return _withSecretBytes(key, function (raw) {
       if (format === "raw") return _toArrayBuffer(raw);
       throw new WebCryptoError("webcrypto/not-supported", "exportKey: secret keys support 'raw' / 'jwk' only");
-    } finally {
-      guard.secret.zeroize(raw, WebCryptoError, "webcrypto/operation", "the exported secret key");
-    }
+    });
   }
   if (format === "spki") return _toArrayBuffer(key._handle.export({ format: "der", type: "spki" }));
   if (format === "pkcs8") return _toArrayBuffer(key._handle.export({ format: "der", type: "pkcs8" }));

package/package.json

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