@blamejs/core 0.17.24 → 0.18.1

package/lib/daemon.js

@@ -72,6 +72,13 @@ var DEFAULT_STOP_TIMEOUT_MS = C.TIME.seconds(30);
 var DEFAULT_STOP_SIGNAL     = "SIGTERM";
 var DEFAULT_POLL_MS         = 100;
 var DEFAULT_LOG_FILE_MODE   = 0o600;
+// A detached child that exits within this window of spawn is treated as a boot
+// death (spawn_failed audit); an abnormal exit after it is a normal run/crash,
+// and a clean exit or an operator stop() is never a spawn failure.
+var BOOT_DEATH_WINDOW_MS    = C.TIME.seconds(5);
+// setTimeout clamps a delay above this 32-bit ceiling to ~1ms, which would
+// silently defeat the boot-window loop-hold — so the opt is refused above it.
+var MAX_BOOT_DEATH_WINDOW_MS = 0x7FFFFFFF;   // 2,147,483,647
 // Poll cadence for the Windows cooperative-stop sentinel (a synchronous
 // existsSync on this interval; see _installStopSentinelWatcher for why it is a
 // poll and not a filesystem watch). Runs for a foreground daemon's whole
@@ -90,6 +97,71 @@ function _safeAuditEmit(action, outcome, metadata) {
 var _isLivePid  = pidProbe.isLivePid;
 var _readPidFile = pidProbe.readPidFile;
 
+// An in-flight stop() writes a `<pidFile>.stopping` marker holding the pid it is
+// stopping. The detached boot-death exit handler consults it so a stop()-induced
+// exit within the boot window is not misread as a spawn failure — a FILESYSTEM
+// marker (not an in-process flag) so it works whether stop() runs in the same
+// process that called start() OR a different one (e.g. a `daemon stop` CLI). The
+// marker carries the target pid so a stale marker from a crashed stopper can
+// only ever suppress that same pid, never a later daemon reusing the pidfile.
+function _stoppingMarkerPath(pidFile) { return pidFile + ".stopping"; }
+
+// Reap the boot-dead child's OWN stale pidfile without a check-then-unlink race.
+// A naive `if (read(pidFile) === childPid) unlink(pidFile)` can delete the WRONG
+// file: a fast operator restart that rewrites pidFile with a NEW child's pid
+// between the read and the unlink leaves the new daemon unmanageable via stop().
+//
+// A NON-DESTRUCTIVE ownership pre-check runs first: only when the sidecar still
+// records THIS child's pid do we ATOMICALLY claim it (rename it to a per-pid path)
+// so the confirming check and the removal act on the same exclusive file. A fast
+// restart's replacement pidfile (a different pid) is thus never even temporarily
+// hidden — we leave it untouched. Should a restart land in the tiny window between
+// the pre-check and the claim, the post-claim re-check catches it (the claimed
+// file's pid won't match) and restores the file. `readPid` defaults to the
+// hardened reader and is injectable for tests. Returns whether the reaped sidecar
+// was this child's.
+function _reapOwnStalePidfile(pidFile, childPid, readPid) {
+  readPid = readPid || _readPidFile;
+  // Pre-check: don't claim (and momentarily hide) a pidfile that isn't ours.
+  var preOwned = false;
+  try { preOwned = String(readPid(pidFile)) === String(childPid); } catch (_pe) { preOwned = false; }
+  if (!preOwned) return false;
+  var claim = pidFile + ".reap-" + childPid;
+  try {
+    atomicFile.renameWithRetry(pidFile, claim);   // retries a transient Windows AV/indexer lock
+  } catch (_e) {
+    return false;   // pidFile vanished between the pre-check and the claim (stop() / a restart) — nothing to reap
+  }
+  // We now exclusively hold `claim`. Verify ownership against it (not pidFile) so
+  // the check and the removal act on the same file; a restart that rewrites
+  // pidFile after our rename creates a fresh, separate pidfile we never touch.
+  var mine = false;
+  try { mine = String(readPid(claim)) === String(childPid); } catch (_e2) { mine = false; }
+  if (mine) {
+    try { nodeFs.unlinkSync(claim); } catch (_e3) { /* best-effort reap — the sidecar is already off pidFile */ }
+  } else {
+    // Not ours (a fast restart's newer pidfile, or an unreadable one) — put it
+    // back so stop() still finds the running daemon's sidecar, but ONLY if nothing
+    // newer has since taken pidFile's place. linkSync is atomic and fails with
+    // EEXIST when a still-newer daemon already wrote pidFile during our inspection,
+    // so the restore never clobbers the newest pidfile with our older claimed one
+    // (a plain rename would). A NON-EEXIST failure means hard links aren't
+    // available on this filesystem (ENOTSUP on FAT / some network mounts), where
+    // nothing newer is present — fall back to a plain rename so the pidfile isn't
+    // lost entirely (it may clobber, but losing the running daemon's pidfile is
+    // worse). Either way, drop our claim afterward.
+    try {
+      nodeFs.linkSync(claim, pidFile);
+    } catch (linkErr) {
+      if (linkErr.code !== "EEXIST") {
+        try { atomicFile.renameWithRetry(claim, pidFile); } catch (_re) { /* best-effort restore */ }
+      }
+    }
+    try { nodeFs.unlinkSync(claim); } catch (_e5) { /* consumed by the rename fallback, or already gone */ }
+  }
+  return mine;
+}
+
 function _validateStartOpts(opts) {
   validateOpts.shape(opts, {
     pidFile: { rule: "required-string", code: "daemon/bad-pid-file",
@@ -118,6 +190,15 @@ function _validateStartOpts(opts) {
           "daemon.start: opts.args requires opts.command");
       }
     },
+    bootDeathWindowMs: function (value) {
+      if (value !== undefined && (typeof value !== "number" || !isFinite(value) ||
+                                  value < 0 || value > MAX_BOOT_DEATH_WINDOW_MS)) {
+        throw new DaemonError("daemon/bad-boot-window",
+          "daemon.start: opts.bootDeathWindowMs must be a finite number of " +
+          "milliseconds in [0, " + MAX_BOOT_DEATH_WINDOW_MS + "] when present " +
+          "(a larger delay clamps setTimeout to ~1ms and defeats the boot window)");
+      }
+    },
   }, "daemon.start", DaemonError, "daemon/bad-opts");
 }
 
@@ -166,6 +247,7 @@ function _maybeReapStale(pidFile) {
 // Used both by detached-spawn (passed via stdio) and by foreground
 // redirect of the current process' stdout/stderr.
 function _openLogFd(logFile) {
+  /* c8 ignore next -- every caller gates on a truthy logFile string, so this guard never returns null */
   if (typeof logFile !== "string" || logFile.length === 0) return null;
   atomicFile.ensureDir(nodePath.dirname(logFile));
   // O_NOFOLLOW append: refuse (ELOOP) a symlink planted at the daemon log
@@ -182,6 +264,7 @@ function _openLogFd(logFile) {
 // pattern for foreground daemons that don't want to lose output when
 // detached from a terminal.
 function _redirectStdio(fd) {
+  /* c8 ignore next -- only ever called with the numeric fd from _openLogFd; the non-number guard is unreachable */
   if (typeof fd !== "number") return;
   function _writer(chunk, encOrCb, maybeCb) {
     var enc = typeof encOrCb === "string" ? encOrCb : "utf8";
@@ -247,6 +330,7 @@ function _installStopSentinelWatcher(pidFile, orchestrator) {
     timer = null;
   }
   function _maybeFire() {
+    /* c8 ignore next -- _stopPolling clears the interval on the first fire, so _maybeFire can't re-enter with fired=true */
     if (fired) return;
     // Synchronous existsSync on the main thread — deliberately not an async
     // stat, so detection never queues behind a saturated libuv threadpool.
@@ -310,6 +394,7 @@ function _installStopSentinelWatcher(pidFile, orchestrator) {
  *   command: string,    // executable for detached-fork mode
  *   args:    string[],  // argv for the detached child
  *   cwd:     string,    // cwd for the detached child
+ *   bootDeathWindowMs: number,  // detached: keep the parent loop alive this long after spawn to observe a boot death (an abnormal exit in the window is audited as a spawn failure + reaps the pidfile); default 5000, 0 opts out (fire-and-forget)
  *
  * @example
  *   var handle = b.daemon.start({
@@ -378,6 +463,12 @@ function start(opts) {
       throw new DaemonError("daemon/spawn-failed",
         "daemon.start: spawn failed: " + ((e && e.message) || String(e)));
     }
+    // Boot-death window is measured from the moment the child was spawned. An
+    // abnormal exit within it is a boot failure; a later one is a normal
+    // run/crash. Operators tune it for a slow-booting child (default 5s).
+    var spawnedAt = Date.now();
+    var bootWindowMs = (typeof opts.bootDeathWindowMs === "number")
+      ? opts.bootDeathWindowMs : BOOT_DEATH_WINDOW_MS;
     // A bad command does NOT throw synchronously from spawn — child_process
     // reports it ASYNC via a 'error' event, with child.pid left undefined. The
     // sync try/catch above only covers spawn() itself, so without this the old
@@ -385,7 +476,18 @@ function start(opts) {
     // one-shot 'error' handler that reaps the sidecar + audits the failure, then
     // refuse to proceed for a child that never got a pid.
     child.on("error", function (err) {
-      try { nodeFs.unlinkSync(pidFile); } catch (_e) { /* best-effort — may not exist */ }
+      // Reap ONLY a pidfile this child actually wrote. A numeric pid means the
+      // sync path below wrote one, and the claim-then-verify reap removes only its
+      // own sidecar (never a fast restart's). A no-pid spawn failure (child.pid
+      // undefined) throws below BEFORE any pidfile write, so this late-firing
+      // callback must not touch pidFile at all — else a caller that catches that
+      // sync throw and retries with the same pidFile would have its replacement
+      // daemon's pidfile deleted. (A numeric-but-invalid pid never reaches here:
+      // child_process yields a positive int or undefined, and either way the
+      // claim-then-verify reap only removes a sidecar recording that exact pid.)
+      if (typeof child.pid === "number") {
+        _reapOwnStalePidfile(pidFile, child.pid);
+      }
       _safeAuditEmit("daemon.spawn_failed", "failure", {
         pidFile: pidFile,
         command: opts.command,
@@ -408,9 +510,76 @@ function start(opts) {
     // Write the child's PID via atomic temp+rename so a concurrent
     // observer never sees a half-written pidFile.
     atomicFile.ensureDir(nodePath.dirname(pidFile));
+    // Clear any STALE stop marker before claiming this pidfile: a stopper that was
+    // SIGKILLed mid-stop leaves `<pidFile>.stopping` behind, and if the OS later
+    // reuses that stopped pid for THIS fresh child, the stale marker would
+    // wrongly suppress a genuine boot-death audit. A fresh start means no stop is
+    // in flight, so the marker can only be stale.
+    try { nodeFs.unlinkSync(_stoppingMarkerPath(pidFile)); } catch (_sm) { /* best-effort — usually absent */ }
     var pidStr = String(child.pid) + "\n";
     atomicFile.writeSync(pidFile, pidStr, { fileMode: 0o600 });
-    // Detach so the child survives parent exit.
+    // A detached child can spawn cleanly (valid pid above) yet DIE AT BOOT —
+    // exit before it ever serves. The synchronous success handle is already
+    // committed (detached mode returns immediately, so the sync return contract
+    // stands), so recover asynchronously: a one-shot 'exit' handler reaps the
+    // sidecar we just wrote — but ONLY when the pidFile still records THIS
+    // child's pid, so a fast operator restart that rewrote it is never
+    // clobbered — and audits the boot death so it leaves a trail instead of a
+    // silently-stranded pidfile that daemon.stop would misread as running.
+    // bootWatch (installed after this handler) holds the parent loop open through
+    // the boot window so a short-lived launcher can't exit before observing the
+    // death; the handler clears it the instant the child exits.
+    var bootWatch = null;
+    child.on("exit", function (code, signal) {
+      if (bootWatch) { clearTimeout(bootWatch); bootWatch = null; }   // death observed — release the loop
+      // Was the sidecar still OURS at exit? Atomically claim-then-verify (see
+      // _reapOwnStalePidfile) so a fast operator restart that rewrote the pidfile
+      // can't make us delete the NEW daemon's sidecar, and so the boot-death
+      // signal survives a swallowed unlink failure. A stop() or a restart that
+      // rewrote/cleared it means someone else owns it now — not a boot death.
+      var wasOurs = _reapOwnStalePidfile(pidFile, child.pid);
+      // Only a BOOT DEATH is a spawn failure: an ABNORMAL exit (non-zero code or
+      // a terminating signal) SHORTLY after spawn, while the sidecar was still
+      // ours (nobody stop()'d it). A clean exit (code 0), a later run/crash, or
+      // an operator stop() is NOT a spawn failure — auditing those as one emits a
+      // contradictory failure alongside the daemon.stopped record.
+      var abnormal   = (typeof code === "number" && code !== 0) || signal != null;
+      var withinBoot = (Date.now() - spawnedAt) <= bootWindowMs;
+      // stop() (this process OR another) sends SIGTERM but unlinks the pidfile
+      // only after observing the exit, so wasOurs is still true here. A
+      // `<pidFile>.stopping` marker holding THIS child's pid means an operator
+      // stop is in flight, so the exit is intentional — not a boot death that
+      // should emit spawn_failed right before daemon.stopped.
+      // Read the marker through the HARDENED pid-sidecar reader (1 KiB cap,
+      // refuse-symlink, positive-int parse, null on any failure) — the marker
+      // lives in the pidfile directory, so a raw readFileSync here would follow a
+      // planted symlink or buffer an unbounded file (CWE-59 / DoS), the exact
+      // threat _readPidFile hardens the pid read against. null (no/garbage marker)
+      // !== child.pid, so a missing marker correctly reads as "not being stopped".
+      var beingStopped = _readPidFile(_stoppingMarkerPath(pidFile)) === child.pid;
+      if (wasOurs && abnormal && withinBoot && !beingStopped) {
+        _safeAuditEmit("daemon.spawn_failed", "failure", {
+          pidFile:  pidFile,
+          command:  opts.command,
+          exitCode: code,
+          signal:   signal || null,
+        });
+      }
+    });
+    // Keep the parent event loop alive through the boot-death window so the exit
+    // handler above can actually observe a child that dies at boot. A short-lived
+    // launcher (e.g. `blamejs daemon start`) would otherwise reach child.unref()
+    // and exit before the child dies — stranding the pidfile for a later stop()
+    // to misread, the very failure the handler exists to prevent. The timer is
+    // ref'd (holds the loop), is cleared the instant the child exits, and
+    // otherwise fires a no-op once the window elapses (boot succeeded → release
+    // the loop, which child.unref() no longer holds). bootDeathWindowMs:0 opts
+    // out entirely: no monitor, immediate exit (historical fire-and-forget).
+    if (bootWindowMs > 0) {
+      bootWatch = setTimeout(function () { bootWatch = null; }, bootWindowMs);
+    }
+    // Detach so a HEALTHY long-running child never holds the parent open past the
+    // boot window (bootWatch is the only remaining ref, and it self-clears).
     try { child.unref(); } catch (_u) { /* best-effort */ }
     if (typeof logFd === "number") {
       // Parent doesn't need its handle to the log; child inherited it.
@@ -446,6 +615,7 @@ function start(opts) {
       logFdForeground = _openLogFd(logFile);
       _redirectStdio(logFdForeground);
     } catch (e) {
+      /* c8 ignore next -- pidLock.release() swallows its own fs errors, so this guard never catches */
       try { lock.release(); } catch (_r) { /* best-effort */ }
       throw new DaemonError("daemon/log-open-failed",
         "daemon.start: failed to open logFile '" + logFile + "': " +
@@ -469,7 +639,9 @@ function start(opts) {
       {
         name: "pidLock-release",
         run:  function () {
+          /* c8 ignore next -- close() delegates to _stopPolling, which self-catches, so stopWatcher.close never throws */
           if (stopWatcher) { try { stopWatcher.close(); } catch (_w) { /* best-effort */ } }
+          /* c8 ignore next -- pidLock.release() swallows its own fs errors, so this guard never catches */
           try { lock.release(); } catch (_e) { /* best-effort */ }
           if (logFdForeground !== null) {
             try { nodeFs.closeSync(logFdForeground); } catch (_c) { /* best-effort */ }
@@ -555,6 +727,23 @@ async function stop(opts) {
     return { stopped: false, pid: pid, reason: "stale" };
   }
 
+  // Publish a `<pidFile>.stopping` marker (holding the pid we are stopping) so the
+  // boot-death exit handler — in THIS process or the still-alive starter of a
+  // cross-process stop — treats the SIGTERM-induced exit as intentional, not a
+  // boot death. The finally removes it on every exit (return OR a kill-failed
+  // throw) so a later start() at the same path is never suppressed.
+  var stopMarker = _stoppingMarkerPath(pidFile);
+  try { atomicFile.writeSync(stopMarker, String(pid), { fileMode: 0o600 }); } catch (_w) { /* best-effort hint */ }
+  try {
+    return await _stopLivePid(pidFile, pid, signal, timeoutMs, pollMs, opts);
+  } finally {
+    try { nodeFs.unlinkSync(stopMarker); } catch (_u) { /* best-effort */ }
+  }
+}
+
+// Signal a confirmed-live pid and wait for exit, escalating SIGTERM -> SIGKILL.
+// Extracted from stop() so the .stopping marker wraps every exit via try/finally.
+async function _stopLivePid(pidFile, pid, signal, timeoutMs, pollMs, opts) {
   var t0 = Date.now();
 
   // Windows has no cooperative signal: process.kill(pid, "SIGTERM") maps to
@@ -733,4 +922,5 @@ module.exports = {
   DEFAULT_STOP_SIGNAL:  DEFAULT_STOP_SIGNAL,
   DEFAULT_STOP_TIMEOUT_MS: DEFAULT_STOP_TIMEOUT_MS,
   _resetForTest:        _resetForTest,
+  _reapOwnStalePidfile: _reapOwnStalePidfile,
 };

package/lib/guard-tenant-id.js

@@ -27,6 +27,7 @@
 var { defineClass } = require("./framework-error");
 var gateContract = require("./gate-contract");
 var codepointClass = require("./codepoint-class");
+var pick = require("./pick");
 
 var GuardTenantIdError = defineClass("GuardTenantIdError", { alwaysPermanent: true });
 
@@ -78,10 +79,20 @@ function validate(tenantId, opts) {
     throw new GuardTenantIdError("tenant-id/oversize",
       "guardTenantId.validate: tenantId exceeds maxBytes=" + profile.maxBytes);
   }
-  if (RESERVED[tenantId]) {
+  if (Object.prototype.hasOwnProperty.call(RESERVED, tenantId)) {
     throw new GuardTenantIdError("tenant-id/reserved",
       "guardTenantId.validate: tenantId '" + tenantId + "' is framework-reserved");
   }
+  // Refuse the prototype-pollution key names outright via the framework's single
+  // poisoned-key predicate (lib/pick.js). The own-property RESERVED check above
+  // (deliberately) will not match these as inherited keys, and a tenant id used to
+  // key a plain-object store must never be __proto__ / constructor / prototype (or
+  // an operator-registered dangerous name), which would pollute the prototype
+  // chain instead of isolating the tenant.
+  if (pick.isPoisonedKey(tenantId)) {
+    throw new GuardTenantIdError("tenant-id/reserved",
+      "guardTenantId.validate: tenantId '" + tenantId + "' is a prototype-pollution key name");
+  }
   if (tenantId.charAt(0) === ".") {
     throw new GuardTenantIdError("tenant-id/hidden",
       "guardTenantId.validate: tenantId cannot start with '.'");

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",