@blamejs/pki 0.6.13 → 0.6.15

package/lib/key.js

@@ -18,16 +18,6 @@
  * @spec RFC 5958, RFC 8018, RFC 5280
  * @card Export / import PKCS#8 and SPKI keys and encrypt a private key under RFC 8018 PBES2.
  */
-//
-// PBES2 is composed from lib/pbes2.js (the single PBKDF2 + AES-CBC home shared with pki.cms), bound to the key
-// namespace through the `_err` error FACTORY + the "key" domain prefix so every reject keeps a key/* code.
-// A MAC-less PBES2-CBC decrypt is not a padding oracle (RFC 8018 sec. 8): every post-derivation failure
-// (a bad PKCS#7 pad, or a valid pad that does not re-parse as a PrivateKeyInfo) collapses into one uniform
-// key/decrypt-failed; the structural pre-derivation faults (a non-PBKDF2 KDF, a non-AES-CBC scheme, an
-// over-cap salt / iteration count, a wrong-length IV, a malformed parameter SEQUENCE) stay distinct and are
-// thrown before any key derivation, so they leak nothing password-dependent. Unencrypted export / import
-// and publicFromPrivate delegate to the WebCrypto / node key engines and re-serialize no
-// AlgorithmIdentifier. A re-encode is exactly where a params-absent-vs-NULL divergence sneaks back in.
 
 var nodeCrypto = require("crypto");
 var asn1 = require("./asn1-der");
@@ -44,23 +34,15 @@ var subtle = webcrypto.webcrypto.subtle;
 var KeyError = frameworkError.KeyError;
 var PemError = frameworkError.PemError;
 function O(n) { return oid.byName(n); }
-// The guard / pbes2 error convention: a (code, msg, cause) factory, never the KeyError class, because pbes2
-// and the guards invoke it as E(code, msg) with no `new` (a class there crashes on the error path).
 function _err(code, msg, cause) { return new KeyError(code, msg, cause); }
 
-// The operator-facing node cipher name <-> the AES-CBC registry name the PBES2 home speaks.
 var CIPHER_NAME = { "aes-128-cbc": "aes128-CBC", "aes-192-cbc": "aes192-CBC", "aes-256-cbc": "aes256-CBC" };
 
-// import inference: the algorithm OIDs that name exactly one WebCrypto algorithm and need no parameters --
-// the Edwards/Montgomery curves and the FIPS post-quantum ML-DSA, ML-KEM, and SLH-DSA (all signing-only or
-// agreement-only, so unambiguous). RSA (sign vs OAEP) and EC (ECDSA vs ECDH) are deliberately absent. Each
-// is ambiguous, so import fails closed there and asks for opts.algorithm.
 var INFER_ALG = {};
 ["Ed25519", "Ed448", "X25519", "X448"].forEach(function (n) { INFER_ALG[O(n)] = { name: n }; });
 [["id-ml-dsa-44", "ML-DSA-44"], ["id-ml-dsa-65", "ML-DSA-65"], ["id-ml-dsa-87", "ML-DSA-87"],
  ["id-ml-kem-512", "ML-KEM-512"], ["id-ml-kem-768", "ML-KEM-768"], ["id-ml-kem-1024", "ML-KEM-1024"]
 ].forEach(function (r) { INFER_ALG[O(r[0])] = { name: r[1] }; });
-// SLH-DSA (FIPS 205) -- all twelve parameter sets; the WebCrypto name is the OID name minus "id-", uppercased.
 ["sha2-128s", "sha2-128f", "sha2-192s", "sha2-192f", "sha2-256s", "sha2-256f",
  "shake-128s", "shake-128f", "shake-192s", "shake-192f", "shake-256s", "shake-256f"
 ].forEach(function (s) { INFER_ALG[O("id-slh-dsa-" + s)] = { name: ("SLH-DSA-" + s).toUpperCase() }; });
@@ -68,7 +50,6 @@ var INFER_ALG = {};
 function _isCryptoKey(x) { return webcrypto.isCryptoKeyLike(x); }
 function _algName(a) { return typeof a === "string" ? a : (a && a.name); }
 
-// A private-key input (CryptoKey | DER Buffer | 'PRIVATE KEY' PEM) -> the raw PKCS#8 PrivateKeyInfo DER.
 async function _toPrivateKeyDer(input) {
   if (_isCryptoKey(input)) {
     if (input.type !== "private") throw _err("key/bad-input", "a private CryptoKey is required (got a " + input.type + " key)");
@@ -107,9 +88,6 @@ async function _toPrivateKeyDer(input) {
  *   var enc = await pki.key.encrypt(der, "s3cr3t", { pem: true });
  *   var back = await pki.key.decrypt(enc, "s3cr3t");
  */
-// Every option pki.key.encrypt reads. `iterations` here answers a different question from
-// `maxIterations` on decrypt. This side chooses a PBKDF2 count, and that side caps the one it
-// will honor. Passing either name to the other verb is silently nothing, so both are refused.
 var _ENCRYPT_OPTS = { cipher: 1, iterations: 1, pem: 1, prf: 1, salt: 1 };
 
 async function encrypt(privateKey, password, opts) {
@@ -118,8 +96,6 @@ async function encrypt(privateKey, password, opts) {
     "pki.key.encrypt has an unknown option (the PBKDF2 count here is `iterations`; " +
     "`maxIterations` is the decrypt-side cap): ");
   var der = await _toPrivateKeyDer(privateKey);
-  // RFC 5958 sec. 3: the plaintext is the DER PrivateKeyInfo -- validate it IS one (the strict parser
-  // rejects BER / non-canonical / trailing bytes) before encrypting, so we never wrap opaque input.
   try { pkcs8.parse(der); } catch (e) { throw _err("key/bad-input", "the private key is not a well-formed PKCS#8 PrivateKeyInfo", e); }
   var cipherName = CIPHER_NAME[opts.cipher || "aes-256-cbc"];
   if (!cipherName) throw _err("key/bad-input", "unsupported cipher " + JSON.stringify(opts.cipher) + " (aes-128-cbc / aes-192-cbc / aes-256-cbc)");
@@ -129,11 +105,6 @@ 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);
-  // 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); }
@@ -141,7 +112,7 @@ async function encrypt(privateKey, password, opts) {
   try {
     var ciphertext = pbes2.cbcEncrypt(dk, iv, der, keyBits, KeyError, "key/bad-input");
     var epki = b.sequence([pbes2.pbes2AlgId(salt, iterations, prf, cipherName, iv), b.octetString(ciphertext)]);
-    pkcs8.parseEncrypted(epki);   // self-check: the produced EncryptedPrivateKeyInfo re-parses
+    pkcs8.parseEncrypted(epki);
     return opts.pem ? pkcs8.pemEncode(epki, "ENCRYPTED PRIVATE KEY") : epki;
   } finally {
     guard.secret.zeroize(dk, KeyError, "key/bad-input", "the password-derived encryption key");
@@ -175,8 +146,6 @@ async function encrypt(privateKey, password, opts) {
  *   var enc = await pki.key.encrypt(await pki.key.export(pair.privateKey), "s3cr3t", { pem: true });
  *   var der = await pki.key.decrypt(enc, "s3cr3t");
  */
-// Every option pki.key.decrypt reads. `maxIterations` is the cap this side honors, not the
-// `iterations` the encrypt side chooses; see the note above _ENCRYPT_OPTS.
 var _DECRYPT_OPTS = { maxIterations: 1, pem: 1 };
 
 async function decrypt(encrypted, password, opts) {
@@ -184,9 +153,6 @@ async function decrypt(encrypted, password, opts) {
   guard.identifier.assertKnownKeys(opts, _DECRYPT_OPTS, _err, "key/bad-input",
     "pki.key.decrypt has an unknown option (the PBKDF2 cap here is `maxIterations`; " +
     "`iterations` is the encrypt-side count): ");
-  // opts.maxIterations is a CALLER authoring bound (a downward-only cap): validate it config-time so an
-  // invalid value is a key/bad-input, never a NaN that silently disables the DoS cap and never mis-coded as
-  // a fault in the attacker-controlled input parameters.
   if (opts.maxIterations != null && (typeof opts.maxIterations !== "number" || !isFinite(opts.maxIterations) || opts.maxIterations < 1 || Math.floor(opts.maxIterations) !== opts.maxIterations)) {
     throw _err("key/bad-input", "maxIterations must be a positive integer");
   }
@@ -201,12 +167,6 @@ async function decrypt(encrypted, password, opts) {
 }
 
 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).
-  // 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"); }
@@ -242,16 +202,10 @@ function _decryptPbes2(encAlg, ciphertext, password, opts) {
  *   var pair = await pki.key.generate("Ed25519");
  *   var spkiPem = await pki.key.export(pair.publicKey, { format: "pem" });
  */
-// Every option pki.key.export reads. Adding one here is the only way to make it accepted.
 var _EXPORT_OPTS = { format: 1, label: 1 };
 
 async function export_(key, opts) {
   opts = guard.identifier.optionsObject(opts, _err, "key/bad-input", "pki.key.export options");
-  // This verb does NOT encrypt, and `password` is the option a caller reaches for when they
-  // think it does. Ignoring it writes the private key in the clear while the call site reads
-  // as though it were protected. Every other unknown option here costs a setting that does
-  // nothing; this one costs a plaintext key on disk. `pki.key.encrypt(key, password, opts)`
-  // is the verb that encrypts; export serializes whatever it is handed.
   guard.identifier.assertKnownKeys(opts, _EXPORT_OPTS, _err, "key/bad-input",
     "pki.key.export has an unknown option. It serializes only. To protect a private key, call " +
     "pki.key.encrypt(key, password) first and export its result. The unknown option was: ");
@@ -291,7 +245,6 @@ async function export_(key, opts) {
  *   var spki = await pki.key.export(pair.publicKey);
  *   var pub = await pki.key.import(spki);                       // Ed25519 -- algorithm inferred
  */
-// Every option pki.key.import reads.
 var _IMPORT_OPTS = { algorithm: 1, extractable: 1, password: 1, usages: 1 };
 
 async function import_(input, opts) {
@@ -305,9 +258,6 @@ async function import_(input, opts) {
   }
   var algorithm = opts.algorithm != null ? opts.algorithm : _inferAlgorithm(detected);
   var isPublic = detected.format === "spki";
-  // Checked at this verb's own door rather than left for the engine to discover: a non-list reached
-  // the CryptoKey copy, where `Array.prototype.slice` on a number yields an empty list, so the key
-  // was minted permitted for NOTHING instead of the call naming the argument that was wrong.
   if (opts.usages != null && !Array.isArray(opts.usages)) throw _err("key/bad-input", "opts.usages must be an array of key-usage strings");
   var usages = opts.usages || _importUsages(_algName(algorithm), isPublic);
   var extractable = opts.extractable != null ? opts.extractable : false;
@@ -339,8 +289,6 @@ async function import_(input, opts) {
  *   var pair = await pki.key.generate("Ed25519");
  *   var pkcs8 = await pki.key.export(pair.privateKey);
  */
-// Every option pki.key.generate reads. `extractable` follows the WebCrypto spelling; a
-// misspelling would leave a key extractable by default, which is the permissive direction.
 var _GENERATE_OPTS = { extractable: 1, usages: 1 };
 
 async function generate(algorithm, opts) {
@@ -348,7 +296,6 @@ async function generate(algorithm, opts) {
   guard.identifier.assertKnownKeys(opts, _GENERATE_OPTS, _err, "key/bad-input",
     "pki.key.generate has an unknown option (the WebCrypto spelling is `extractable`): ");
   var extractable = opts.extractable != null ? opts.extractable : true;
-  // The same door as import: a non-list is named here rather than becoming an empty usage set.
   if (opts.usages != null && !Array.isArray(opts.usages)) throw _err("key/bad-input", "opts.usages must be an array of key-usage strings");
   var usages = opts.usages || _generateUsages(_algName(algorithm));
   var pair;
@@ -377,7 +324,6 @@ async function generate(algorithm, opts) {
  *   var pair = await pki.key.generate("Ed25519");
  *   var spki = await pki.key.publicFromPrivate(await pki.key.export(pair.privateKey));
  */
-// Every option pki.key.publicFromPrivate reads.
 var _PUBLIC_FROM_PRIVATE_OPTS = { pem: 1 };
 
 async function publicFromPrivate(privateKey, opts) {
@@ -393,11 +339,7 @@ async function publicFromPrivate(privateKey, opts) {
   return opts.pem ? pkix.pemEncode(spki, "PUBLIC KEY", PemError) : spki;
 }
 
-// ---- import helpers --------------------------------------------------------
 
-// Auto-detect a key input by structure (works for a raw DER Buffer or a label-agnostic PEM): a PrivateKeyInfo
-// leads with an INTEGER version; an SPKI is SEQ{ algId, BIT STRING }; an EncryptedPrivateKeyInfo is
-// SEQ{ algId, OCTET STRING }. Returns { format, der }.
 function _detectKeyInput(input) {
   var der = pkix.coerceToDer(input, { pemLabel: null, PemError: PemError, ErrorClass: KeyError, prefix: "key" });
   var root;
@@ -409,13 +351,9 @@ function _detectKeyInput(input) {
   throw _err("key/bad-input", "the input is not a recognized PKCS#8, SPKI, or EncryptedPrivateKeyInfo");
 }
 
-// The AlgorithmIdentifier OID from a detected key: privateKeyAlgorithm (PKCS#8) or algorithm (SPKI).
 function _readAlgOid(detected) {
   try {
     if (detected.format === "pkcs8") return pkcs8.parse(detected.der).privateKeyAlgorithm.oid;
-    // SPKI: SEQUENCE { algorithm AlgorithmIdentifier SEQUENCE { OID, ... }, subjectPublicKey BIT STRING }.
-    // Validate the algorithm SEQUENCE shape before dereferencing its OID -- a malformed SPKI must be a typed
-    // reject, never a raw children[] fault.
     var alg = asn1.decode(detected.der).children[0];
     if (!alg || alg.tagClass !== "universal" || alg.tagNumber !== asn1.TAGS.SEQUENCE || !alg.children || !alg.children.length) {
       throw _err("key/bad-input", "malformed SubjectPublicKeyInfo algorithm identifier");
@@ -435,15 +373,12 @@ function _inferAlgorithm(detected) {
     " (RSA and EC are ambiguous between signing and key agreement -- pass opts.algorithm)");
 }
 
-// Default key usages by algorithm CLASS. The name is normalized to upper case first: WebCrypto matches
-// algorithm names case-insensitively, so a caller passing { name: "x25519" } / "ml-kem-768" must land on the
-// same usage class as the canonical spelling rather than fall through to the signing default.
 function _importUsages(name, isPublic) {
   var n = String(name == null ? "" : name).toUpperCase();
   if (n === "X25519" || n === "X448" || n === "ECDH") return isPublic ? [] : ["deriveBits", "deriveKey"];
   if (n.indexOf("ML-KEM") === 0) return isPublic ? ["encapsulateBits"] : ["decapsulateBits"];
   if (n === "RSA-OAEP") return isPublic ? ["encrypt"] : ["decrypt"];
-  return isPublic ? ["verify"] : ["sign"];   // signing default (Ed / ECDSA / RSA-* sign / ML-DSA / SLH-DSA)
+  return isPublic ? ["verify"] : ["sign"];
 }
 
 function _generateUsages(name) {