@blamejs/core 0.17.23 → 0.18.0

package/lib/mtls-ca.js

@@ -14,9 +14,9 @@
  *   tagging, and atomic commit. Cert issuance (CA generation, client
  *   cert signing, PKCS#12 packaging) delegates to a pluggable engine
  *   so the operator chooses the X.509 toolchain. The default pure-JS
- *   engine lives in `lib/mtls-engine-default.js` (backed by the
- *   vendored @peculiar/x509 + pkijs bundle); operators with custom
- *   requirements pass their own via `opts.engine`.
+ *   engine lives in `lib/mtls-engine-default.js` (backed by the vendored
+ *   zero-dep @blamejs/pki toolkit); operators with custom requirements
+ *   pass their own via `opts.engine`.
  *
  *   Files relative to `dataDir`: `ca.crt` (PEM cert, plaintext),
  *   `ca.key` (PEM key, plaintext — refused under `caKeySealedMode:
@@ -69,10 +69,10 @@ var safeJson = require("./safe-json");
 var validateOpts = require("./validate-opts");
 var { FrameworkError } = require("./framework-error");
 
-// The default engine carries a 600+ KB vendored bundle (peculiar/x509 +
-// pkijs + reflect-metadata). Lazy-require it so operators wiring a
-// custom engine never pay the cost. The lazyRequire wrapper keeps the
-// require at top-of-file declaration shape — no indented inline calls.
+// The default engine carries a vendored X.509 toolkit (@blamejs/pki).
+// Lazy-require it so operators wiring a custom engine never pay the cost.
+// The lazyRequire wrapper keeps the require at top-of-file declaration
+// shape — no indented inline calls.
 var mtlsEngineDefault = lazyRequire(function () { return require("./mtls-engine-default"); });
 
 var caLog = boot("mtls-ca");
@@ -148,6 +148,7 @@ function parseGeneration(certPem) {
   if (typeof certPem !== "string" && !Buffer.isBuffer(certPem)) return 0;
   try {
     var cert = new nodeCrypto.X509Certificate(certPem);
+    /* c8 ignore next -- defensive: a successfully-parsed X.509 certificate always exposes a subject DN */
     var subj = cert.subject || "";
     var m = /OU=CAv(\d+)/.exec(subj);
     return m ? parseInt(m[1], 10) : 1;
@@ -180,6 +181,7 @@ function parseGeneration(certPem) {
  *   caKeySealedMode:  string,                                  // "required" (default) | "disabled"
  *   generation:       number,                                  // current CA generation for OU=CAv{N}
  *   engine:           object,                                  // pluggable X.509 engine; default lib/mtls-engine-default
+ *   algorithm:        string,                                  // pin CA + leaf key algorithm; default ML-DSA-87. Pass "ECDSA-P384-SHA384" for a classical CA when a peer predates OpenSSL 3.5
  *
  * @example
  *   var fs   = require("fs");
@@ -194,11 +196,43 @@ function parseGeneration(certPem) {
  *   typeof ca.initCA;
  *   // → "function"
  */
+// Map an algorithm-pin label to the node KeyObject.asymmetricKeyType a stored CA
+// key of that algorithm reports, so a pin can be checked against an on-disk CA.
+// Returns null for a label this file can't map (a custom engine's own naming) —
+// the check is then skipped and the engine owns the semantics.
+// The OpenSSL curve name node reports for the framework's sole classical pin
+// (ECDSA-P384-SHA384). A stored EC CA must report this curve to satisfy that pin.
+var CLASSICAL_CA_CURVE = "secp384r1";
+
+function _expectedKeyTypeForPin(label) {
+  var l = String(label).toLowerCase();
+  if (l.indexOf("ecdsa") !== -1) return "ec";
+  var m = l.match(/ml-dsa-(\d+)/);
+  return m ? ("ml-dsa-" + m[1]) : null;
+}
+
+// The inverse of _expectedKeyTypeForPin: map a stored CA key's node
+// asymmetricKeyType to the algorithm label leaves should be issued under, so an
+// UNPINNED deployment (e.g. an upgrade that never set opts.algorithm) issues
+// leaves under the CA's OWN algorithm — a coherent chain the CA's existing peers
+// can verify — instead of the engine's newer process default. Returns undefined
+// for a key node cannot parse or a type this file doesn't map (the engine then
+// applies its own default).
+function _labelForCaKeyType(caKeyPem) {
+  var type;
+  /* c8 ignore next -- the "" fallback is defensive: a parsed KeyObject always reports a non-empty asymmetricKeyType, so it is never reached */
+  try { type = String(nodeCrypto.createPrivateKey(caKeyPem).asymmetricKeyType || "").toLowerCase(); }
+  catch (_e) { return undefined; }
+  if (type === "ec") return "ECDSA-P384-SHA384";
+  if (/^ml-dsa-\d+$/.test(type)) return type.toUpperCase();
+  return undefined;
+}
+
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
     "dataDir", "paths", "vault",
-    "caKeySealedMode", "generation", "engine", "revocationStore",
+    "caKeySealedMode", "generation", "engine", "revocationStore", "algorithm",
   ], "b.mtlsCa");
   validateOpts.requireNonEmptyString(opts.dataDir, "mtlsCa.create: opts.dataDir", MtlsCaError, "mtls-ca/no-datadir");
   // Auto-create the dataDir with restrictive perms (CA keys live here).
@@ -221,9 +255,29 @@ function create(opts) {
   var generation = typeof opts.generation === "number" && opts.generation >= 1
     ? Math.floor(opts.generation) : 1;
   // The default engine is lazy-loaded at top-of-file; resolve it only
-  // when no custom engine was passed.
+  // when no custom engine was passed. Whether the bundled engine is in use
+  // gates the CA-following algorithm inference below: _labelForCaKeyType maps a
+  // key to the BUNDLED engine's label set, which is meaningless (or wrong) for a
+  // custom engine's own labels / key curves. A falsy engine (null / undefined)
+  // selects the bundled engine, so the flag must match the `opts.engine || ...`
+  // fallback exactly — an explicit engine: null is the bundled engine, not custom.
+  var usesDefaultEngine = !opts.engine;
   var engine = opts.engine || mtlsEngineDefault();
 
+  // Optional algorithm pin. When set, it is threaded into BOTH CA generation
+  // (initCA) and every leaf/PKCS#12 issuance so the whole chain shares one
+  // algorithm — the operator opt-in for a classical (ECDSA-P384-SHA384) CA when
+  // a peer predates the OpenSSL 3.5 that verifies the ML-DSA-87 default. The
+  // label set is the engine's to validate (a custom engine may define its own),
+  // so this is a config-time type guard only; an unknown label surfaces from the
+  // engine at issuance.
+  var caAlgorithm = opts.algorithm;
+  if (caAlgorithm !== undefined && (typeof caAlgorithm !== "string" || caAlgorithm.length === 0)) {
+    throw new MtlsCaError("mtls-ca/bad-algorithm",
+      "opts.algorithm must be a non-empty string label " +
+      "(e.g. \"ECDSA-P384-SHA384\") when set");
+  }
+
   function _requireVault(reason) {
     if (!vault || typeof vault.seal !== "function" || typeof vault.unseal !== "function") {
       throw new MtlsCaError("mtls-ca/no-vault",
@@ -332,8 +386,10 @@ function create(opts) {
         while (w < buf.length) {
           w += nodeFs.writeSync(fd, buf, w, buf.length - w, null);
         }
+        /* c8 ignore next -- best-effort: fsync on a freshly-opened, still-valid fd does not throw here */
         try { nodeFs.fsyncSync(fd); } catch (_fe) { /* fsync best-effort */ }
       } finally {
+        /* c8 ignore next -- best-effort: closeSync on the just-written fd does not throw here */
         try { nodeFs.closeSync(fd); } catch (_ce) { /* close best-effort */ }
       }
     }
@@ -353,8 +409,10 @@ function create(opts) {
       // so a genuinely-broken filesystem state surfaces in operator logs
       // rather than getting silently swallowed.
       try { if (nodeFs.existsSync(keyTmp))  nodeFs.unlinkSync(keyTmp); }
+      /* c8 ignore next -- best-effort cleanup: unlink of a tmp file we just created does not throw here */
       catch (cleanupErr) { caLog.debug("cleanup-failed", { op: "fs.unlinkSync", path: keyTmp, error: cleanupErr.message }); }
       try { if (nodeFs.existsSync(certTmp)) nodeFs.unlinkSync(certTmp); }
+      /* c8 ignore next -- best-effort cleanup: unlink of a tmp file we just created does not throw here */
       catch (cleanupErr) { caLog.debug("cleanup-failed", { op: "fs.unlinkSync", path: certTmp, error: cleanupErr.message }); }
       throw new MtlsCaError("mtls-ca/commit-failed",
         "atomic CA commit failed: " + ((e && e.message) || String(e)));
@@ -368,9 +426,54 @@ function create(opts) {
 
   async function initCA() {
     if (exists()) {
-      return { caCertPem: loadCert().toString("utf8"), caKeyPem: loadKey().toString("utf8") };
+      var existingCertPem = loadCert().toString("utf8");
+      var existingKeyPem  = loadKey().toString("utf8");
+      // A stored CA is returned as-is (initCA never silently rotates). But an
+      // algorithm pin that DISAGREES with the stored CA cannot be honored: the
+      // CA's own signature over every leaf is what a peer verifies, so issuing an
+      // ECDSA leaf pinned for a legacy peer under a stored ML-DSA CA still yields
+      // an ML-DSA-signed chain that peer cannot verify. Refuse the mismatch and
+      // tell the operator to rotate, rather than issue an unusable credential.
+      if (caAlgorithm !== undefined) {
+        var expectedType = _expectedKeyTypeForPin(caAlgorithm);
+        var actualType   = null;
+        var actualCurve  = null;
+        // A custom engine may store a key node cannot parse — skip the check then.
+        try {
+          var caKeyObj = nodeCrypto.createPrivateKey(existingKeyPem);
+          /* c8 ignore next -- the "" fallback is defensive: a parsed KeyObject always reports a non-empty asymmetricKeyType, so it is never reached */
+          actualType  = String(caKeyObj.asymmetricKeyType || "").toLowerCase();
+          actualCurve = caKeyObj.asymmetricKeyDetails && caKeyObj.asymmetricKeyDetails.namedCurve
+            ? String(caKeyObj.asymmetricKeyDetails.namedCurve).toLowerCase() : null;
+        } catch (_e) { actualType = null; }
+        if (expectedType !== null && actualType && actualType !== expectedType) {
+          throw new MtlsCaError("mtls-ca/algorithm-mismatch",
+            "the CA at this dataDir was generated under " + actualType + ", but algorithm " +
+            JSON.stringify(caAlgorithm) + " (" + expectedType + ") was requested. A leaf issued " +
+            "under the pin would be signed by the mismatched CA and fail chain verification at a " +
+            "peer. Rotate to a new CA (a fresh dataDir, or a higher generation) to change algorithms.");
+        }
+        // Every ECDSA label maps to the generic "ec" type, so the type check alone
+        // would accept a P-256/P-521 stored CA under the ECDSA-P384 pin — leaving
+        // the operator believing they hold P-384 posture. The framework's sole
+        // classical pin is ECDSA-P384-SHA384 (secp384r1), so enforce the curve for
+        // it; a custom-engine label (unrecognized here) owns its own curve.
+        if (actualType === "ec" && /ecdsa-p384/i.test(String(caAlgorithm)) && actualCurve !== CLASSICAL_CA_CURVE) {
+          throw new MtlsCaError("mtls-ca/algorithm-mismatch",
+            "the CA at this dataDir uses EC curve " + actualCurve + ", but algorithm " +
+            JSON.stringify(caAlgorithm) + " requires P-384 (" + CLASSICAL_CA_CURVE + "). Rotate to a new " +
+            "CA (a fresh dataDir, or a higher generation) to change the curve.");
+        }
+      }
+      return { caCertPem: existingCertPem, caKeyPem: existingKeyPem };
     }
-    var fresh = await engine.generateCa({ generation: generation });
+    // Build the args conditionally so an `algorithm` key is present ONLY when the
+    // operator pinned one — a strict custom engine that validates its generateCa
+    // option shape would reject an own `algorithm: undefined` key on an unpinned
+    // first-time init (matching the conditional custom leaf-engine handling).
+    var caGenArgs = { generation: generation };
+    if (caAlgorithm !== undefined) caGenArgs.algorithm = caAlgorithm;
+    var fresh = await engine.generateCa(caGenArgs);
     if (!fresh || typeof fresh.caCertPem !== "string" || typeof fresh.caKeyPem !== "string") {
       throw new MtlsCaError("mtls-ca/bad-engine-output",
         "engine.generateCa must return { caCertPem, caKeyPem }");
@@ -402,10 +505,51 @@ function create(opts) {
     };
   }
 
+  // Build the engine call args for a leaf/PKCS#12 issuance. The leaf follows the
+  // CA's algorithm: the pin when set (initCA already verified it matches the
+  // stored CA), otherwise — for the BUNDLED engine only — the stored CA's own
+  // algorithm, so an unpinned upgrade over an existing classical CA keeps issuing
+  // classical leaves instead of the engine's ML-DSA process default. A custom
+  // engine gets no inferred algorithm (its label set / key curve is its own to
+  // resolve; the bundled ECDSA-P384-SHA384 label would break it). An explicit
+  // opts2.algorithm always wins.
+  function _leafEngineArgs(ca, opts2) {
+    var leafAlg = caAlgorithm;
+    if (leafAlg === undefined) {
+      // The stored CA's own key type maps to the BUNDLED engine's label set, so
+      // the inference is USED only for that engine — a custom engine resolves its
+      // own algorithm from its own key (injecting the bundled ECDSA-P384-SHA384
+      // label would break a P-256/P-521 or custom-labeled engine that validates
+      // its option shape).
+      var caKeyLabel = _labelForCaKeyType(ca.caKeyPem);
+      if (usesDefaultEngine) leafAlg = caKeyLabel;
+    }
+    var args = Object.assign({}, opts2, { caCertPem: ca.caCertPem, caKeyPem: ca.caKeyPem });
+    if (leafAlg !== undefined) {
+      // The resolved CA algorithm (a pin verified against the stored CA, or the
+      // bundled engine's stored-CA inference) is AUTHORITATIVE and wins over a
+      // per-issuance opts.algorithm: silently honoring a conflicting one would let
+      // a classical ECDSA CA issue an ML-DSA leaf its legacy peers can't
+      // authenticate (and mis-select the P12 MAC tier). Refuse a conflict outright
+      // rather than issue a leaf that doesn't match the CA the operator pinned.
+      if (opts2.algorithm !== undefined && opts2.algorithm !== leafAlg) {
+        throw new MtlsCaError("mtls-ca/algorithm-conflict",
+          "generateClientCert/generateClientP12: opts.algorithm " + JSON.stringify(opts2.algorithm) +
+          " conflicts with the CA's algorithm " + JSON.stringify(leafAlg) +
+          " (the leaf must match the CA; rotate to a fresh CA to change algorithms)");
+      }
+      args.algorithm = leafAlg;
+    }
+    // When leafAlg is undefined (a custom engine), opts2.algorithm passes through
+    // for the engine to resolve; caCertPem/caKeyPem are forced last so opts2 can't
+    // shadow them.
+    return args;
+  }
+
   async function generateClientCert(opts2) {
     opts2 = opts2 || {};
     var ca = await initCA();
-    var args = Object.assign({}, opts2, { caCertPem: ca.caCertPem, caKeyPem: ca.caKeyPem });
+    var args = _leafEngineArgs(ca, opts2);
     var result = await engine.signClientCert(args);
     if (!result || typeof result.cert !== "string" || typeof result.key !== "string") {
       throw new MtlsCaError("mtls-ca/bad-engine-output",
@@ -424,7 +568,10 @@ function create(opts) {
         "generateClientP12 requires opts.password (the PKCS#12 encryption password)");
     }
     var ca = await initCA();
-    var args = Object.assign({}, opts2, { caCertPem: ca.caCertPem, caKeyPem: ca.caKeyPem });
+    // Leaf (and its P12 MAC tier) follows the CA's algorithm via the shared
+    // arg-builder — the pin when set, else the bundled engine's stored-CA
+    // inference, never a custom engine's inferred label or the process default.
+    var args = _leafEngineArgs(ca, opts2);
     var result = await engine.packageP12(args);
     if (!result || !Buffer.isBuffer(result.p12)) {
       throw new MtlsCaError("mtls-ca/bad-engine-output",
@@ -456,6 +603,7 @@ function create(opts) {
           { maxBytes: C.BYTES.mib(16) });
         return (json && Array.isArray(json.revocations)) ? json.revocations : [];
       } catch (e) {
+        /* c8 ignore next 2 -- defensive: safeJson.parse throws an Error with a message, so the String(e) fallback is unreachable */
         throw new MtlsCaError("mtls-ca/revocation-corrupt",
           "could not parse " + paths.revocations + ": " + ((e && e.message) || String(e)));
       }
@@ -512,10 +660,12 @@ function create(opts) {
     return stripped.toLowerCase();
   }
 
-  // Map operator-friendly reason codes to RFC 5280 numeric codes used
-  // by X.509 CRLs. Default "unspecified" (0) when omitted. removeFromCRL
-  // uses hex 0x08 to express RFC 5280's reason code 8 — the literal is a
-  // protocol identifier, not a byte quantity.
+  // Map operator-friendly reason codes to RFC 5280 numeric codes used by X.509
+  // CRLs. Default "unspecified" (0) when omitted. removeFromCRL (code 8) is
+  // deliberately absent: it is a DELTA-CRL directive to UN-revoke a cert from the
+  // base CRL, not a revocation reason, and is invalid in a full CRL (all this CA
+  // issues) — the toolkit refuses it at sign time, so a persisted code-8 entry
+  // would poison every later generateCrl(). revoke() rejects it explicitly below.
   var CRL_REASON_BY_NAME = {
     "unspecified":          0,
     "keyCompromise":        1,
@@ -527,7 +677,6 @@ function create(opts) {
     "cessationOfOperation": 5,
     "cessation-of-operation": 5,
     "certificateHold":      6,
-    "removeFromCRL":        0x08,
     "privilegeWithdrawn":   9,
     "aACompromise":         10,
   };
@@ -552,6 +701,12 @@ function create(opts) {
         "revoke requires a serial number or a fingerprint " +
         "(revoke(serial, opts) or revoke({ serial, fingerprint }))");
     }
+    if (reasonName === "removeFromCRL") {
+      throw new MtlsCaError("mtls-ca/bad-reason",
+        "revoke: 'removeFromCRL' (RFC 5280 code 8) is a delta-CRL un-revocation " +
+        "directive, not a revocation reason — this CA issues full CRLs only, and a " +
+        "persisted code-8 entry would make every generateCrl() fail");
+    }
     var reasonCode = CRL_REASON_BY_NAME[reasonName];
     if (reasonCode === undefined) {
       throw new MtlsCaError("mtls-ca/bad-reason",