@blamejs/core 0.17.23 → 0.18.0

package/lib/mtls-engine-default.js

@@ -5,42 +5,52 @@
  * mtls-engine-default — pure-JS X.509 engine wired into b.mtlsCa.
  *
  * Implements the engine contract documented at the top of lib/mtls-ca.js:
- *   generateCa({ generation })            -> { caCertPem, caKeyPem }
- *   signClientCert({ cn, validityDays,
- *                    caCertPem, caKeyPem })   -> { cert, key, ca, issuedAt, expiresAt }
- *   packageP12({ cn, password, validityDays,
- *                caCertPem, caKeyPem })       -> { p12, certPem, issuedAt, expiresAt }
+ *   generateCa({ generation, algorithm })     -> { caCertPem, caKeyPem }
+ *   signClientCert({ cn, validityDays, usage, sans, algorithm,
+ *                    caCertPem, caKeyPem })    -> { cert, key, ca, issuedAt, expiresAt }
+ *   packageP12({ cn, password, validityDays, algorithm,
+ *                caCertPem, caKeyPem })        -> { p12, certPem, issuedAt, expiresAt }
+ *   generateCrl({ caCertPem, caKeyPem,
+ *                 revocations, thisUpdate,
+ *                 nextUpdate })                -> CRL PEM
  *
- * Backed by lib/vendor/pki.cjs (vendored @peculiar/x509 + pkijs +
- * reflect-metadata + ASN.1 schema chain). node:crypto.webcrypto is bound
- * inside the bundle entry; nothing here calls openssl CLI.
+ * Backed by lib/vendor/blamejs-pki.cjs (@blamejs/pki — zero-dep pure-CJS
+ * X.509 / CRL / PKCS#12 toolkit with a built-in WebCrypto over node:crypto).
+ * No openssl CLI is invoked.
  *
  * Algorithm envelope:
- *   CA + leaf signatures: ECDSA P-384 + SHA-384
- *   PKCS#12 key bag      : PBES2 + AES-256-CBC + PBKDF2-HMAC-SHA-512, 2,000,000 iter
- *   PKCS#12 cert bag     : same as key bag
- *   PKCS#12 outer MAC    : HMAC-SHA-512 + PBKDF2, 2,000,000 iter
- *
- * The X.509 ecosystem doesn't yet accept SLH-DSA / ML-DSA on shipping
- * client certs, so the cert sigs stay classical ECDSA-P384 — matching
- * the framework's hybrid KEM posture rather than its standalone PQ
- * signing posture. Swap atomically when browsers + OS cert stores can
- * verify a PQ algorithm; bump CA_GENERATION on the same release so
- * b.mtlsCa.status reports legacy correctly.
+ *   CA + leaf signatures: ML-DSA-87 by default (FIPS 204). node:tls verifies
+ *                         ML-DSA certificate chains + CertificateVerify on the
+ *                         supported Node LTS (OpenSSL 3.5), so PQC-signed mTLS
+ *                         certificates complete a real mutual-auth handshake.
+ *                         Operators whose peers are not yet on OpenSSL 3.5 pass
+ *                         algorithm: "ECDSA-P384-SHA384" (b.mtlsCa.create({ algorithm })
+ *                         threads it into both CA generation and leaf issuance)
+ *                         for a universally-interoperable classical CA. A pin is
+ *                         per-call: it never mutates the process-wide default, so
+ *                         one classical CA cannot downgrade another CA's ML-DSA-87
+ *                         default. SLH-DSA is intentionally not offered here:
+ *                         OpenSSL rejects it in the TLS handshake ("unknown
+ *                         certificate type").
+ *   PKCS#12 key + cert bags: PBES2 + AES-256-CBC + PBKDF2-HMAC-SHA-512, 2,000,000 iter
+ *   PKCS#12 outer MAC       : follows the cert tier — PBMAC1 + PBKDF2-HMAC-SHA-512
+ *                             @ 2,000,000 iter (RFC 9579) for the PQC default; the
+ *                             classical ECDSA-P384 bridge uses the legacy-importable
+ *                             RFC 7292 App. B HMAC-SHA-512 MacData so a pre-OpenSSL-3.5
+ *                             peer can verify it
  */
 
 var nodeCrypto = require("node:crypto");
-
-var pki = require("./vendor/pki.cjs");
+var pki = require("./vendor/blamejs-pki.cjs");
 
 var C = require("./constants");
 var bCrypto = require("./crypto");
+var ipUtils = require("./ip-utils");
 var numericBounds = require("./numeric-bounds");
+var safeBuffer = require("./safe-buffer");
 var { FrameworkError } = require("./framework-error");
 
-var x509 = pki.x509;
-var pkijs = pki.pkijs;
-var webcrypto = pki.crypto;
+var subtle = pki.webcrypto.subtle;
 
 class MtlsEngineError extends FrameworkError {
   constructor(code, message) {
@@ -53,164 +63,217 @@ class MtlsEngineError extends FrameworkError {
 
 var CA_KEY_USAGES = ["sign", "verify"];
 
-// Algorithm priority — each entry probed at first use; the first one
-// the vendored x509 library AND webcrypto can both honour wins.
-// Ordered highest-PQC-posture first so the engine self-upgrades the
-// moment the vendor bundle gains PQ-sig X.509 support.
+// Algorithm priority — each entry probed at first use; the first one the
+// vendored PKI toolkit AND webcrypto can both honour wins. Ordered
+// highest-PQC-posture first so the engine issues post-quantum certificates
+// by default. Every listed candidate has been confirmed to complete a real
+// node:tls mutual-auth handshake on the supported Node LTS.
 //
-// keyAlg: passed to webcrypto.subtle.generateKey + import
-// sigAlg: passed to x509.X509CertificateGenerator.create
-// label : surfaced via b.mtlsCa.status() so operators can audit
-//         which algorithm the in-flight CA generation is using
+// keyAlg : passed to webcrypto.subtle.generateKey; the certificate signature
+//          algorithm is resolved from the signing key by pki.x509.sign.
+// label  : surfaced via b.mtlsCa.status() so operators can audit which
+//          algorithm the in-flight CA generation is using, and passed to
+//          generateCa({ algorithm }) to pin a specific one.
 var ALG_CANDIDATES = [
-  // Pure-PQC stateless hash-based — matches lib/audit-sign's posture.
-  // FIPS 205 (SPHINCS+ family). Awaiting node:tls + browser cert-store
-  // verification support; currently issuance-only on most stacks.
-  {
-    label:  "SLH-DSA-SHAKE-256f",
-    keyAlg: { name: "SLH-DSA-SHAKE-256f" },
-    sigAlg: { name: "SLH-DSA-SHAKE-256f" },
-    posture: "pqc-pure",
-  },
-  {
-    label:  "SLH-DSA-SHAKE-128f",
-    keyAlg: { name: "SLH-DSA-SHAKE-128f" },
-    sigAlg: { name: "SLH-DSA-SHAKE-128f" },
-    posture: "pqc-pure",
-  },
-  // Pure-PQC lattice — FIPS 204 (Dilithium family). Smaller than SLH-DSA,
-  // accepted by the same emerging cert-store deployments.
+  // Pure-PQC lattice — FIPS 204 (ML-DSA / Dilithium family). Verified end to
+  // end in a node:tls mutual-auth handshake (chain + CertificateVerify).
   {
     label:  "ML-DSA-87",
     keyAlg: { name: "ML-DSA-87" },
-    sigAlg: { name: "ML-DSA-87" },
     posture: "pqc-pure",
   },
   {
     label:  "ML-DSA-65",
     keyAlg: { name: "ML-DSA-65" },
-    sigAlg: { name: "ML-DSA-65" },
     posture: "pqc-pure",
   },
-  // Documented bridge — used until cert ecosystems verify the above.
-  // The framework's hybrid KEM posture (X25519MLKEM768) covers handshake
-  // KEX; these certs sign with ECDSA P-384 + SHA-384.
+  // Classical bridge — for peers not yet on OpenSSL 3.5. Opt in with
+  // generateCa({ algorithm: "ECDSA-P384-SHA384" }).
   {
     label:  "ECDSA-P384-SHA384",
     keyAlg: { name: "ECDSA", namedCurve: "P-384" },
-    sigAlg: { name: "ECDSA", hash: "SHA-384" },
     posture: "classical",
+    // The signature digest MUST be passed to pki.x509.sign / pki.crl.sign — the
+    // toolkit defaults an EC key to SHA-256, which would silently downgrade this
+    // bridge below its SHA-384 posture (and below the framework's no-SHA-256
+    // default rule). ML-DSA needs no digest (it is no-prehash: the toolkit forces
+    // SHA-512 and ignores an explicit digest), so only the classical entry sets it.
+    digest: "sha384",
   },
 ];
 
-// First-call probe cache. Re-runs after engine reload (test reset path).
+// First-call probe cache for the process-wide DEFAULT (never written by a per-call
+// pin, so a pin can't downgrade the default). Re-runs after engine reload.
 var _selectedAlg = null;
+// The most-recent RESOLVED algorithm (pinned OR default) — reporting only, so
+// algorithmEnvelope() can describe a pinned selection accurately without poisoning
+// the default cache above.
+var _lastSelectedAlg = null;
 
 async function _probeCandidate(c) {
   try {
-    var pair = await webcrypto.subtle.generateKey(c.keyAlg, true, CA_KEY_USAGES);
+    var pair = await subtle.generateKey(c.keyAlg, true, CA_KEY_USAGES);
+    /* c8 ignore next -- defensive: webcrypto.generateKey always resolves a valid keypair here */
     if (!pair || !pair.publicKey) return false;
-    // Also confirm the x509 generator accepts the sigAlg by issuing a
-    // throwaway self-signed cert. Some keyAlgs work in webcrypto but
-    // aren't yet wired through @peculiar/x509's encoder — without this
-    // round-trip we'd select an algorithm we can't actually mint certs
-    // with and hit a confusing failure on first issuance.
-    await x509.X509CertificateGenerator.create({
-      serialNumber: "01",
-      subject:      "CN=probe",
-      issuer:       "CN=probe",
+    // Confirm the toolkit can also mint a certificate under this key — some
+    // key algorithms keygen in webcrypto but aren't wired through the X.509
+    // signer, and selecting one we can't issue with would surface a
+    // confusing failure on first real issuance.
+    var spki = Buffer.from(await subtle.exportKey("spki", pair.publicKey));
+    await pki.x509.sign({
+      subject:      "probe",
+      subjectPublicKey: spki,
+      serialNumber: "0x01",
       notBefore:    new Date(),
       notAfter:     new Date(Date.now() + C.TIME.seconds(1)),
-      signingAlgorithm: c.sigAlg,
-      publicKey:    pair.publicKey,
-      signingKey:   pair.privateKey,
-    });
+      extensions:   { basicConstraints: { cA: true } },
+    }, { key: pair.privateKey }, { pem: true });
     return true;
+  /* c8 ignore start -- probe never throws: every listed candidate algorithm is honoured by the runtime's OpenSSL 3.5+ */
   } catch (_e) {
     return false;
   }
+  /* c8 ignore stop */
+}
+
+function _emitAlgorithmSelected(c, candidatesProbed) {
+  setImmediate(function () {
+    try {
+      var auditMod = require("./audit");                                          // allow:inline-require — circular-load defense
+      auditMod.safeEmit({
+        action:   "mtls.engine.algorithm_selected",
+        outcome:  "success",
+        metadata: { label: c.label, posture: c.posture, candidatesProbed: candidatesProbed },
+      });
+    /* c8 ignore next -- belt-and-suspenders: audit.safeEmit is itself drop-silent, so this catch is unreachable */
+    } catch (_e) { /* drop-silent */ }
+  });
 }
 
-async function _selectAlgorithm() {
-  if (_selectedAlg) return _selectedAlg;
+// Resolve the signing algorithm. With no argument the highest-posture
+// candidate that probes clean is cached and reused. `preferredLabel` pins a
+// specific candidate (the generateCa({ algorithm }) opt-in) — it must exist
+// and probe clean, else the call throws rather than silently downgrading.
+async function _selectAlgorithm(preferredLabel) {
+  if (preferredLabel) {
+    var wanted = null;
+    for (var w = 0; w < ALG_CANDIDATES.length; w++) {
+      if (ALG_CANDIDATES[w].label === preferredLabel || ALG_CANDIDATES[w].keyAlg.name === preferredLabel) {
+        wanted = ALG_CANDIDATES[w];
+        break;
+      }
+    }
+    if (!wanted) {
+      throw new MtlsEngineError("mtls-engine/unknown-algorithm",
+        "unknown algorithm " + JSON.stringify(preferredLabel) + " — supported: " +
+        ALG_CANDIDATES.map(function (c) { return c.label; }).join(", "));
+    }
+    /* c8 ignore start -- unreachable: every pinnable candidate probes clean on the runtime's OpenSSL 3.5+ */
+    if (!(await _probeCandidate(wanted))) {
+      throw new MtlsEngineError("mtls-engine/algorithm-unavailable",
+        "algorithm " + JSON.stringify(preferredLabel) + " is not available in this runtime");
+    }
+    /* c8 ignore stop */
+    // A pinned algorithm is per-call and MUST NOT be cached as the process
+    // default. `_selectedAlg` is the shared fallback the no-argument path below
+    // returns; writing a classical pin here would make a single
+    // generateCa({ algorithm: "ECDSA-P384-SHA384" }) silently downgrade every
+    // later default CA/leaf off the ML-DSA-87 PQC-first default in the same
+    // process. Callers thread a pin explicitly through generateCa /
+    // signClientCert instead (b.mtlsCa.create({ algorithm })).
+    _lastSelectedAlg = wanted;   // reporting only — does NOT touch the default cache
+    _emitAlgorithmSelected(wanted, 1);
+    return wanted;
+  }
+  if (_selectedAlg) { _lastSelectedAlg = _selectedAlg; return _selectedAlg; }
   for (var i = 0; i < ALG_CANDIDATES.length; i++) {
     var c = ALG_CANDIDATES[i];
-    var ok = await _probeCandidate(c);
-    if (ok) {
+    if (await _probeCandidate(c)) {
       _selectedAlg = c;
-      // Emit an audit row at first probe so operators see which
-      // algorithm landed without having to call b.mtlsCa.status().
-      // Pre-PQC ecosystems land on the ECDSA-P384 bridge silently;
-      // this puts the choice on the chain so compliance dashboards
-      // alert when an operator's deployment hasn't yet picked up the
-      // PQ-signed-cert capability the framework would otherwise
-      // prefer.
-      setImmediate(function () {
-        try {
-          var auditMod = require("./audit");                                          // allow:inline-require — circular-load defense
-          auditMod.safeEmit({
-            action:   "mtls.engine.algorithm_selected",
-            outcome:  "success",
-            metadata: { label: c.label, posture: c.posture, candidatesProbed: i + 1 },
-          });
-        } catch (_e) { /* drop-silent */ }
-      });
+      _lastSelectedAlg = c;
+      _emitAlgorithmSelected(c, i + 1);
       return c;
     }
   }
-  // Should never happen — ECDSA-P384-SHA384 is universal.
+  /* c8 ignore start -- unreachable: ECDSA-P384-SHA384 is universal, so the candidate loop always returns first */
+  // Should never happen — ECDSA-P384 is universal.
   throw new MtlsEngineError("mtls-engine/no-algorithm",
     "no candidate algorithm passed the webcrypto + x509 probe");
+  /* c8 ignore stop */
 }
 
-// Backwards-compat shape for callers that read these directly. Resolved
-// lazily so the algorithm choice is the first-probe result.
-var CA_KEY_ALG = null;
-var CA_SIG_ALG = null;
-
-// AES-256 key length expressed in bits — webcrypto's contract for the
-// `length` field of AES-CBC. Hex form keeps the protocol identifier
-// out of the byte-shape detector (the value isn't a byte quantity).
-var P12_CONTENT_ENC = { name: "AES-CBC", length: 0x100 };
-var P12_KDF_HASH    = "SHA-512";
-var P12_MAC_HASH    = "SHA-512";
-// PKCS#12 PBKDF2 iteration count — protocol-fixed cost parameter, not
-// a byte quantity. Hex form per the same rationale as P12_CONTENT_ENC.length.
-var P12_ITER        = 0x1E8480;
+// PKCS#12 protection envelope. The cipher / PRF / MAC identifiers are
+// protocol-fixed strings, and the iteration count is a cost parameter, not a
+// byte quantity — hex form keeps it out of the byte-shape detector.
+var P12_CIPHER   = "aes-256-cbc";
+var P12_PRF      = "hmacWithSHA512";
+var P12_MAC_HASH = "sha512";
+var P12_ITER     = 0x1E8480; // 2,000,000 (PBMAC1 outer MAC + PBES2 bag KDF)
+// The classic App. B.2 MacData KDF (RFC 7292) is a synchronous per-iteration
+// hash loop, so it is capped ~10x below PBMAC1's native PBKDF2 — 1,000,000 is
+// the toolkit's classic-MAC ceiling (~1s wall clock). Used only for the
+// classical ECDSA-P384 bridge's legacy-importable MacData.
+var P12_CLASSIC_MAC_ITER = 0xF4240; // 1,000,000
 
 var CA_VALIDITY_DAYS    = 10 * 365; // 10y CA lifetime
 var LEAF_DEFAULT_DAYS   = 365;
 var DEFAULT_CA_NAME     = "blamejs CA";
-var BAG_ID_KEY          = "1.2.840.113549.1.12.10.1.2"; // pkcs-12-pkcs-8ShroudedKeyBag
-var BAG_ID_CERT         = "1.2.840.113549.1.12.10.1.3"; // pkcs-12-certBag
-var EKU_CLIENT_AUTH_OID = "1.3.6.1.5.5.7.3.2";
-var EKU_SERVER_AUTH_OID = "1.3.6.1.5.5.7.3.1";
-
-function _pemBlock(label, der) {
-  var b64 = Buffer.from(der).toString("base64");
-  return "-----BEGIN " + label + "-----\n" + b64.match(/.{1,64}/g).join("\n") + "\n-----END " + label + "-----\n";
+// RFC 5280 removeFromCRL CRLReason — a delta-CRL un-revocation directive invalid
+// in a full CRL; filtered out of full-CRL entries (see generateCrl).
+var CRL_REMOVE_FROM_CRL = 8;
+
+function _serial() {
+  // pki wants a decimal or 0x-hex integer; generateToken yields hex octets.
+  return "0x" + bCrypto.generateToken(C.BYTES.bytes(16));
 }
 
-async function _exportKeyPairToPem(keyPair) {
-  var pkcs8 = await webcrypto.subtle.exportKey("pkcs8", keyPair.privateKey);
-  var spki  = await webcrypto.subtle.exportKey("spki",  keyPair.publicKey);
-  return {
-    privatePem: _pemBlock("PRIVATE KEY", pkcs8),
-    publicPem:  _pemBlock("PUBLIC KEY",  spki),
-  };
+function _ekuNames(usage) {
+  var names = [];
+  if (usage === "client" || usage === "both") names.push("clientAuth");
+  if (usage === "server" || usage === "both") names.push("serverAuth");
+  return names;
 }
 
-// Import a PEM private key regardless of its on-disk encoding.
-// Existing keys may be SEC1, PKCS#1, or PKCS#8 — Node's createPrivateKey
-// normalises all three; webcrypto.importKey then reads the PKCS#8 DER.
-async function _importPemPrivateKey(pem, alg, usages, extractable) {
-  var keyObj  = nodeCrypto.createPrivateKey(pem);
-  var pkcs8   = keyObj.export({ format: "der", type: "pkcs8" });
-  return webcrypto.subtle.importKey("pkcs8", pkcs8, alg, !!extractable, usages);
+// Pack a textual IP into the DER octet form pki's iPAddress GeneralName
+// expects (4 octets for IPv4, 16 for IPv6). Composes lib/ip-utils.
+function _packIp(value) {
+  var s = String(value);
+  if (ipUtils.isIPv4(s)) {
+    var quads = s.split(".");
+    var buf4 = Buffer.alloc(4);
+    for (var i = 0; i < 4; i++) {
+      var n = parseInt(quads[i], 10);
+      /* c8 ignore next -- unreachable: the IPv4 arm is entered only after isIPv4() validated each octet 0-255 */
+      if (!(n >= 0 && n <= 255)) throw new MtlsEngineError("mtls-engine/bad-san", "invalid IPv4 SAN " + JSON.stringify(s));
+      buf4[i] = n;
+    }
+    return buf4;
+  }
+  var groups;
+  /* c8 ignore next -- unreachable: expandIpv6Groups returns null for malformed input rather than throwing */
+  try { groups = ipUtils.expandIpv6Groups(s); } catch (_e) { groups = null; }
+  if (Array.isArray(groups) && groups.length === 8) {
+    var buf16 = Buffer.alloc(16);
+    for (var g = 0; g < 8; g++) buf16.writeUInt16BE(groups[g] & 0xffff, g * 2);
+    return buf16;
+  }
+  throw new MtlsEngineError("mtls-engine/bad-san", "invalid IP SAN " + JSON.stringify(s));
 }
 
-function _parseCertPem(pem) {
-  return new x509.X509Certificate(pem);
+// Map operator SAN entries (strings, optionally "DNS:" / "IP:" prefixed) to
+// pki GeneralName objects.
+function _sanEntry(s) {
+  var str = String(s);
+  if (/^DNS:/i.test(str)) return { dNSName: str.slice(4) };
+  if (/^IP:/i.test(str))  return { iPAddress: _packIp(str.slice(3)) };
+  if (ipUtils.isIPv4(str)) return { iPAddress: _packIp(str) };
+  // A bare IPv6 literal is an IP SAN too — auto-detect it symmetrically with
+  // IPv4 (a colon-bearing literal can never be a valid DNS hostname, so it must
+  // not fall through to the dNSName default and become an unmatchable SAN).
+  var v6 = ipUtils.expandIpv6Groups(str);
+  if (Array.isArray(v6) && v6.length === 8) return { iPAddress: _packIp(str) };
+  // Bare non-IP entries default to DNS — matches operator expectation.
+  return { dNSName: str };
 }
 
 function _normaliseCn(cn) {
@@ -222,33 +285,44 @@ function _normaliseCn(cn) {
   return s;
 }
 
+// The signature digest a CA private key should sign with. generateCa /
+// signClientCert know their candidate's digest directly; generateCrl only has
+// the CA key, so derive it: an EC (P-384) CA signs with SHA-384, matching the
+// classical bridge's posture; ML-DSA is no-prehash (undefined -> the toolkit
+// forces SHA-512), so return undefined for a non-EC or unparseable key.
+function _digestForKey(caKeyPem) {
+  try {
+    return nodeCrypto.createPrivateKey(caKeyPem).asymmetricKeyType === "ec" ? "sha384" : undefined;
+  /* c8 ignore next -- defensive: the default engine only signs CRLs with the CA key it just generated (always a parseable EC/ML-DSA key), so the parse never throws here */
+  } catch (_e) { return undefined; }
+}
+
 async function generateCa(opts) {
   opts = opts || {};
   var generation = (typeof opts.generation === "number" && opts.generation >= 1)
     ? Math.floor(opts.generation) : 1;
   var caName = opts.name || DEFAULT_CA_NAME;
 
-  var alg = await _selectAlgorithm();
-  CA_KEY_ALG = alg.keyAlg; CA_SIG_ALG = alg.sigAlg;
-  var keys = await webcrypto.subtle.generateKey(CA_KEY_ALG, true, CA_KEY_USAGES);
+  var alg = await _selectAlgorithm(opts.algorithm);
+  var keys = await subtle.generateKey(alg.keyAlg, true, CA_KEY_USAGES);
+  var spki = Buffer.from(await subtle.exportKey("spki", keys.publicKey));
   var now  = new Date();
-  var ca = await x509.X509CertificateGenerator.createSelfSigned({
-    serialNumber: bCrypto.generateToken(C.BYTES.bytes(16)),
-    name: "CN=" + caName + ",OU=CAv" + generation,
-    notBefore: now,
-    notAfter: new Date(now.getTime() + C.TIME.days(CA_VALIDITY_DAYS)),
-    signingAlgorithm: CA_SIG_ALG,
-    keys: keys,
-    extensions: [
-      new x509.BasicConstraintsExtension(true, 0, true),
-      new x509.KeyUsagesExtension(
-        x509.KeyUsageFlags.keyCertSign | x509.KeyUsageFlags.cRLSign,
-        true
-      ),
-    ],
-  });
-  var pem = await _exportKeyPairToPem(keys);
-  return { caCertPem: ca.toString("pem"), caKeyPem: pem.privatePem };
+
+  var caCertPem = await pki.x509.sign({
+    // Structured DN — a bare string subject is taken by the toolkit as the CN
+    // VALUE (so "CN=name,OU=CAvN" would become a single CN literal, double-
+    // encoded as CN=CN=name\,OU=CAvN with no real OU). Pass RDN objects so the
+    // CN and the OU=CAv{N} generation tag are distinct attributes.
+    subject:          [{ commonName: caName }, { organizationalUnitName: "CAv" + generation }],
+    subjectPublicKey: spki,
+    serialNumber:     _serial(),
+    notBefore:        now,
+    notAfter:         new Date(now.getTime() + C.TIME.days(CA_VALIDITY_DAYS)),
+    extensions:       { basicConstraints: { cA: true, pathLen: 0 }, keyUsage: ["keyCertSign", "cRLSign"] },
+  }, { key: keys.privateKey }, { pem: true, digestAlgorithm: alg.digest });
+
+  var caKeyPem = await pki.key.export(keys.privateKey, { format: "pem" });
+  return { caCertPem: caCertPem, caKeyPem: caKeyPem };
 }
 
 async function signClientCert(opts) {
@@ -264,72 +338,57 @@ async function signClientCert(opts) {
   var cn = _normaliseCn(opts.cn);
 
   // Extended Key Usage: defaults to clientAuth (the historical behaviour).
-  // Operators issuing server certs for inbound mTLS reverse-proxy fronts
-  // pass `usage: "server"` (sets serverAuth EKU), or `usage: "both"`
-  // (clientAuth + serverAuth — dual-purpose certs for service-to-service
-  // mTLS where the same workload is both initiator and acceptor).
+  // usage: "server" -> serverAuth; "both" -> clientAuth + serverAuth.
   var usage = opts.usage || "client";
-  var ekuOids = [];
-  if (usage === "client" || usage === "both") ekuOids.push(EKU_CLIENT_AUTH_OID);
-  if (usage === "server" || usage === "both") ekuOids.push(EKU_SERVER_AUTH_OID);
-  if (ekuOids.length === 0) {
+  var ekuNames = _ekuNames(usage);
+  if (ekuNames.length === 0) {
     throw new MtlsEngineError("mtls-engine/bad-usage",
       "signClientCert: opts.usage must be 'client' | 'server' | 'both', got " +
       JSON.stringify(opts.usage));
   }
 
-  // Subject Alternative Names — required for serverAuth (modern TLS
-  // clients only honor SANs, not CN). Accept opts.sans as an array of
-  // strings (DNS names by default; "DNS:foo" / "IP:1.2.3.4" forms also).
-  var sanExt = null;
+  // Subject Alternative Names — required for serverAuth (modern TLS clients
+  // only honor SANs, not CN). Accept opts.sans as an array of strings.
+  var sans = null;
   if (Array.isArray(opts.sans) && opts.sans.length > 0) {
-    var sanEntries = opts.sans.map(function (s) {
-      var str = String(s);
-      if (/^DNS:/i.test(str)) return { type: "dns", value: str.slice(4) };
-      if (/^IP:/i.test(str))  return { type: "ip",  value: str.slice(3) };
-      // Bare entries default to DNS — matches operator expectation
-      return { type: "dns", value: str };
-    });
-    sanExt = new x509.SubjectAlternativeNameExtension(sanEntries);
+    sans = opts.sans.map(_sanEntry);
   } else if (usage === "server" || usage === "both") {
     // serverAuth without a SAN is unverifiable by modern TLS clients.
-    // Auto-add the CN as a DNS SAN so the most common case "just works".
-    sanExt = new x509.SubjectAlternativeNameExtension([{ type: "dns", value: cn }]);
+    sans = [{ dNSName: cn }];
   }
 
-  var alg = await _selectAlgorithm();
-  CA_KEY_ALG = alg.keyAlg; CA_SIG_ALG = alg.sigAlg;
-  var caKey   = await _importPemPrivateKey(opts.caKeyPem, CA_KEY_ALG, ["sign"]);
-  var caCert  = _parseCertPem(opts.caCertPem);
-  var clientKeys = await webcrypto.subtle.generateKey(CA_KEY_ALG, true, CA_KEY_USAGES);
+  // Leaf key algorithm follows the CA's: an ML-DSA-87 default, or the classical
+  // bridge when the caller pinned one (b.mtlsCa threads its create({ algorithm })
+  // through here). Undefined selects the process default.
+  var alg = await _selectAlgorithm(opts.algorithm);
+  var clientKeys = await subtle.generateKey(alg.keyAlg, true, CA_KEY_USAGES);
+  var clientSpki = Buffer.from(await subtle.exportKey("spki", clientKeys.publicKey));
 
   var now      = new Date();
   var notAfter = new Date(now.getTime() + C.TIME.days(validityDays));
-  var extensions = [
-    new x509.BasicConstraintsExtension(false, undefined, true),
-    new x509.KeyUsagesExtension(
-      x509.KeyUsageFlags.digitalSignature | x509.KeyUsageFlags.keyEncipherment,
-      true
-    ),
-    new x509.ExtendedKeyUsageExtension(ekuOids, true),
-  ];
-  if (sanExt) extensions.push(sanExt);
-
-  var clientCert = await x509.X509CertificateGenerator.create({
-    serialNumber: bCrypto.generateToken(C.BYTES.bytes(16)),
-    subject: "CN=" + cn,
-    issuer: caCert.subject,
-    notBefore: now,
-    notAfter: notAfter,
-    signingAlgorithm: CA_SIG_ALG,
-    publicKey: clientKeys.publicKey,
-    signingKey: caKey,
-    extensions: extensions,
-  });
-  var pem = await _exportKeyPairToPem(clientKeys);
+  var extensions = {
+    basicConstraints:         { cA: false },
+    keyUsage:                 ["digitalSignature", "keyEncipherment"],
+    extendedKeyUsage:         ekuNames,
+    extendedKeyUsageCritical: true,
+  };
+  if (sans) extensions.subjectAltName = sans;
+
+  var certPem = await pki.x509.sign({
+    // A bare string subject is the CN VALUE (the toolkit wraps it as CN=<value>);
+    // passing "CN=" + cn would double-encode to CN=CN=<cn>.
+    subject:          cn,
+    subjectPublicKey: clientSpki,
+    serialNumber:     _serial(),
+    notBefore:        now,
+    notAfter:         notAfter,
+    extensions:       extensions,
+  }, { cert: opts.caCertPem, key: opts.caKeyPem }, { pem: true, digestAlgorithm: alg.digest });
+
+  var keyPem = await pki.key.export(clientKeys.privateKey, { format: "pem" });
   return {
-    cert:      clientCert.toString("pem"),
-    key:       pem.privatePem,
+    cert:      certPem,
+    key:       keyPem,
     ca:        opts.caCertPem,
     issuedAt:  now.toISOString(),
     expiresAt: notAfter.toISOString(),
@@ -343,86 +402,35 @@ async function packageP12(opts) {
     throw new MtlsEngineError("mtls-engine/no-password",
       "packageP12 requires opts.password (non-empty string)");
   }
+  // Resolve the leaf's algorithm tier so the outer MAC matches it. (signClientCert
+  // resolves the same alg from opts.algorithm; undefined selects the default.)
+  var alg  = await _selectAlgorithm(opts.algorithm);
   var leaf = await signClientCert(opts);
 
-  // Re-import the leaf key as extractable so we can re-export PKCS#8 DER
-  // for the shrouded key bag.
-  var leafKey       = await _importPemPrivateKey(leaf.key, CA_KEY_ALG, ["sign"], true);
-  var leafPkcs8     = await webcrypto.subtle.exportKey("pkcs8", leafKey);
-  var privateKeyInfo = pkijs.PrivateKeyInfo.fromBER(leafPkcs8);
-
-  var leafX509  = _parseCertPem(leaf.cert);
-  var caX509    = _parseCertPem(leaf.ca);
-  var leafPkijsCert = pkijs.Certificate.fromBER(leafX509.rawData);
-  var caPkijsCert   = pkijs.Certificate.fromBER(caX509.rawData);
-
-  var passwordBuf = Buffer.from(opts.password, "utf8");
-
-  var pfx = new pkijs.PFX({
-    parsedValue: {
-      integrityMode: 0, // PasswordMode (outer HMAC-PBKDF2)
-      authenticatedSafe: new pkijs.AuthenticatedSafe({
-        parsedValue: {
-          safeContents: [
-            {
-              privacyMode: 1, // PasswordPrivacyMode (PBES2)
-              value: new pkijs.SafeContents({
-                safeBags: [
-                  new pkijs.SafeBag({
-                    bagId: BAG_ID_KEY,
-                    bagValue: new pkijs.PKCS8ShroudedKeyBag({ parsedValue: privateKeyInfo }),
-                  }),
-                ],
-              }),
-            },
-            {
-              privacyMode: 1,
-              value: new pkijs.SafeContents({
-                safeBags: [
-                  new pkijs.SafeBag({
-                    bagId: BAG_ID_CERT,
-                    bagValue: new pkijs.CertBag({ parsedValue: leafPkijsCert }),
-                  }),
-                  new pkijs.SafeBag({
-                    bagId: BAG_ID_CERT,
-                    bagValue: new pkijs.CertBag({ parsedValue: caPkijsCert }),
-                  }),
-                ],
-              }),
-            },
-          ],
-        },
-      }),
-    },
-  });
-
-  // Inner protection on the shrouded-key bag itself.
-  await pfx.parsedValue.authenticatedSafe.parsedValue.safeContents[0]
-    .value.safeBags[0].bagValue.makeInternalValues({
-      password: passwordBuf,
-      contentEncryptionAlgorithm: P12_CONTENT_ENC,
-      hmacHashAlgorithm: P12_KDF_HASH,
-      iterationCount: P12_ITER,
-    });
-
-  // Encrypt each SafeContents envelope.
-  await pfx.parsedValue.authenticatedSafe.makeInternalValues({
+  var pbe = { password: opts.password, cipher: P12_CIPHER, iterations: P12_ITER, prf: P12_PRF };
+  // The integrity MAC follows the cert's interop tier. The PQC-pure default uses
+  // PBMAC1 (RFC 9579) — an ML-DSA peer already runs the OpenSSL 3.5 that supports
+  // it. The classical ECDSA-P384 bridge exists FOR peers predating OpenSSL 3.5,
+  // and PBMAC1 (OpenSSL 3.4+) would make the file unverifiable by exactly those
+  // consumers, so it uses the universally-importable RFC 7292 App. B HMAC MacData
+  // (at the classic KDF's lower iteration ceiling). PBES2 bag protection is
+  // legacy-readable in both tiers, so only the MAC differs.
+  var mac = alg.posture === "classical"
+    ? { algorithm: "hmac",   hash: P12_MAC_HASH, iterations: P12_CLASSIC_MAC_ITER }
+    : { algorithm: "pbmac1", hash: P12_MAC_HASH, iterations: P12_ITER };
+  var p12 = await pki.pkcs12.build({
     safeContents: [
-      { password: passwordBuf, contentEncryptionAlgorithm: P12_CONTENT_ENC, hmacHashAlgorithm: P12_KDF_HASH, iterationCount: P12_ITER },
-      { password: passwordBuf, contentEncryptionAlgorithm: P12_CONTENT_ENC, hmacHashAlgorithm: P12_KDF_HASH, iterationCount: P12_ITER },
+      { bags: [{ type: "shroudedKey", key: leaf.key, encrypt: pbe }] },
+      { encrypt: pbe, bags: [
+        { type: "cert", cert: leaf.cert },
+        { type: "cert", cert: leaf.ca },
+      ] },
     ],
-  });
-
-  // Outer integrity MAC.
-  await pfx.makeInternalValues({
-    password: passwordBuf,
-    iterations: P12_ITER,
-    pbkdf2HashAlgorithm: P12_KDF_HASH,
-    hmacHashAlgorithm: P12_MAC_HASH,
-  });
+  }, { password: opts.password, mac: mac });
 
   return {
-    p12:       Buffer.from(pfx.toSchema().toBER(false)),
+    /* c8 ignore next -- defensive: pki.pkcs12.build always returns a Buffer, so the Buffer.from() arm is unreachable */
+    p12:       Buffer.isBuffer(p12) ? p12 : Buffer.from(p12),
     certPem:   leaf.cert,
     issuedAt:  leaf.issuedAt,
     expiresAt: leaf.expiresAt,
@@ -432,34 +440,42 @@ async function packageP12(opts) {
 function algorithmEnvelope() {
   return {
     cert: {
-      keyAlg:   CA_KEY_ALG,
-      sigAlg:   CA_SIG_ALG,
-      label:    _selectedAlg && _selectedAlg.label,
-      posture:  _selectedAlg && _selectedAlg.posture,
-      // Operators querying status() before any cert has been issued
-      // get the candidate priority list — the engine probes lazily so
-      // the chosen algorithm isn't known until first use.
+      // Report the most-recent resolved algorithm (a pinned selection or the
+      // default), so the envelope is accurate on the pinned issuance path too — not
+      // just _selectedAlg (the default cache a pin deliberately never writes).
+      keyAlg:   _lastSelectedAlg && _lastSelectedAlg.keyAlg,
+      label:    _lastSelectedAlg && _lastSelectedAlg.label,
+      posture:  _lastSelectedAlg && _lastSelectedAlg.posture,
+      // Operators querying status() before any cert has been issued get the
+      // candidate priority list — the engine probes lazily so the chosen
+      // algorithm isn't known until first use.
       priority: ALG_CANDIDATES.map(function (c) {
         return { label: c.label, posture: c.posture };
       }),
     },
-    p12:  {
-      contentEncryption: P12_CONTENT_ENC,
-      kdfHash: P12_KDF_HASH,
-      macHash: P12_MAC_HASH,
-      iterationCount: P12_ITER,
+    p12: {
+      contentEncryption: P12_CIPHER,       // PBES2 + AES-256-CBC bag protection (both tiers)
+      kdfPrf:            P12_PRF,           // PBKDF2-HMAC-SHA-512 (both tiers)
+      iterationCount:    P12_ITER,          // bag KDF iterations (both tiers)
+      // The outer integrity MAC is tier-dependent: packageP12 selects it from the
+      // cert algorithm's posture — PBMAC1 (RFC 9579) for the PQC default, the
+      // traditional RFC 7292 HMAC MacData for the classical bridge so a
+      // pre-OpenSSL-3.5 peer can verify it. Both are reported (keyed by posture)
+      // so a consumer describes the archive it actually builds under either pin.
+      mac: {
+        "pqc-pure": { algorithm: "pbmac1", hash: P12_MAC_HASH, iterations: P12_ITER },
+        classical:  { algorithm: "hmac",   hash: P12_MAC_HASH, iterations: P12_CLASSIC_MAC_ITER },
+      },
     },
     caValidityDays:   CA_VALIDITY_DAYS,
     leafDefaultDays:  LEAF_DEFAULT_DAYS,
   };
 }
 
-// Generate a signed X.509 CRL (RFC 5280) covering every revoked
-// serial number. The vendored peculiar/x509 library exposes
-// X509CrlGenerator.create which builds the TBSCertList, populates
-// the entries, and signs with the CA private key — same signature
-// algorithm the CA itself was issued under (auto-detected via
-// _selectAlgorithm + cached on first issuance).
+// Generate a signed X.509 CRL (RFC 5280) covering every revoked serial
+// number. pki.crl.sign builds the TBSCertList, populates the entries, and
+// signs under the CA private key — the signature algorithm is resolved from
+// the CA key, matching the algorithm the CA itself was issued under.
 async function generateCrl(opts) {
   opts = opts || {};
   if (!opts.caCertPem || !opts.caKeyPem) {
@@ -467,30 +483,39 @@ async function generateCrl(opts) {
       "generateCrl requires { caCertPem, caKeyPem, revocations, thisUpdate, nextUpdate }");
   }
   var revocations = Array.isArray(opts.revocations) ? opts.revocations : [];
-  var alg = await _selectAlgorithm();
-  CA_KEY_ALG = alg.keyAlg; CA_SIG_ALG = alg.sigAlg;
-
-  var caKey  = await _importPemPrivateKey(opts.caKeyPem, CA_KEY_ALG, ["sign"]);
-  var caCert = _parseCertPem(opts.caCertPem);
-
-  // X509CrlEntry expects { serialNumber: hex, revocationDate, reason }.
-  var entries = revocations.map(function (r) {
-    return {
-      serialNumber:    r.serialNumber,
-      revocationDate:  new Date(r.revokedAt || Date.now()),
-      reason:          (typeof r.reasonCode === "number") ? r.reasonCode : 0,
+
+  var revoked = revocations.map(function (r) {
+    var entry = {
+      serialNumber:   _normaliseRevokedSerial(r.serialNumber),
+      revocationDate: new Date(r.revokedAt || Date.now()),
     };
+    // A full CRL (the only kind this CA issues) cannot carry removeFromCRL
+    // (RFC 5280 code 8) — it is a delta-CRL un-revocation directive the toolkit
+    // rejects, failing the ENTIRE CRL. revoke() refuses it going forward, but a
+    // registry written by a pre-fix build (or hand-edited) may still hold one;
+    // keep the serial revoked (it IS in the store — fail-secure) and DROP only the
+    // invalid reason so one legacy entry can't block publishing every other
+    // revocation.
+    if (typeof r.reasonCode === "number" && r.reasonCode !== CRL_REMOVE_FROM_CRL) {
+      entry.reason = r.reasonCode;
+    }
+    return entry;
   });
 
-  var crl = await x509.X509CrlGenerator.create({
-    issuer:           caCert.subject,
-    thisUpdate:       opts.thisUpdate || new Date(),
-    nextUpdate:       opts.nextUpdate,
-    entries:          entries,
-    signingAlgorithm: CA_SIG_ALG,
-    signingKey:       caKey,
-  });
-  return crl.toString("pem");
+  return pki.crl.sign({
+    thisUpdate: opts.thisUpdate || new Date(),
+    nextUpdate: opts.nextUpdate,
+    revoked:    revoked,
+  }, { cert: opts.caCertPem, key: opts.caKeyPem }, { pem: true, digestAlgorithm: _digestForKey(opts.caKeyPem) });
+}
+
+// A revoked serial arrives as the hex string the engine issued (no 0x
+// prefix). pki wants a decimal or 0x-hex integer, so prefix bare hex.
+function _normaliseRevokedSerial(serial) {
+  var s = String(serial == null ? "" : serial);
+  if (/^0x/i.test(s)) return s;
+  if (safeBuffer.isHex(s)) return "0x" + s;
+  return s;
 }
 
 module.exports = {