@blamejs/core 0.15.11 → 0.15.13

package/lib/middleware/security-txt.js

@@ -27,6 +27,7 @@
 
 var lazyRequire = require("../lazy-require");
 var validateOpts = require("../validate-opts");
+var denyResponse = require("./deny-response");
 var { defineClass } = require("../framework-error");
 
 var SecurityTxtError = defineClass("SecurityTxtError", { alwaysPermanent: true });
@@ -143,12 +144,7 @@ function create(opts) {
                   (alsoAtRoot && path === "/security.txt");
     if (!matches) return next();
     if (req.method !== "GET" && req.method !== "HEAD") {
-      res.writeHead(405, {                                                       // HTTP 405 status
-        "Allow":          "GET, HEAD",
-        "Content-Type":   "text/plain; charset=utf-8",
-        "Content-Length": 18,                                                    // len of "Method Not Allowed"
-      });
-      res.end("Method Not Allowed");
+      denyResponse.methodNotAllowed(res, "GET, HEAD");
       return;
     }
     res.writeHead(200, {                                                         // HTTP 200 status

package/lib/middleware/tus-upload.js

@@ -150,10 +150,10 @@ function _parseChecksumHeader(headerValue, allowedSet) {
   // alphabet); refuse those on the RAW value BEFORE the slice/trim
   // normalisation (same v0.8.90 trim-before-validate bug class).
   if (structuredFields.containsControlBytes(headerValue)) return { error: "malformed" };
-  var sp = headerValue.indexOf(" ");
-  if (sp === -1) return { error: "malformed" };
-  var algo = headerValue.slice(0, sp).trim().toLowerCase();
-  var digestB64 = headerValue.slice(sp + 1).trim();
+  var kvp = structuredFields.parseKeyValuePiece(headerValue, " ");
+  if (kvp.value === null) return { error: "malformed" };
+  var algo = kvp.key;
+  var digestB64 = kvp.value.trim();
   if (algo.length === 0 || digestB64.length === 0) return { error: "malformed" };
   if (!allowedSet[algo]) return { error: "algo-unsupported" };
   if (!/^[A-Za-z0-9+/=]+$/.test(digestB64)) return { error: "malformed" };
@@ -311,19 +311,11 @@ function _emitTusBaseHeaders(res, extra) {
 }
 
 function _readChunk(req, maxChunkSize) {
-  return new Promise(function (resolve, reject) {
-    var collector = safeBuffer.boundedChunkCollector({
-      maxBytes:    maxChunkSize,
-      errorClass:  TusError,
-      sizeCode:    "tus/chunk-too-large",
-      sizeMessage: "PATCH body exceeded maxChunkSize",
-    });
-    req.on("data", function (c) {
-      try { collector.push(c); }
-      catch (e) { req.removeAllListeners("data"); reject(e); }
-    });
-    req.on("end", function () { resolve(collector.result()); });
-    req.on("error", function (e) { reject(e); });
+  return safeBuffer.collectStream(req, {
+    maxBytes:    maxChunkSize,
+    errorClass:  TusError,
+    sizeCode:    "tus/chunk-too-large",
+    sizeMessage: "PATCH body exceeded maxChunkSize",
   });
 }
 
@@ -388,11 +380,8 @@ function create(opts) {
   }
 
   var store = opts.store;
-  if (!store || typeof store.create !== "function" || typeof store.head !== "function" ||
-      typeof store.append !== "function" || typeof store.terminate !== "function") {
-    throw new TusError("tus/bad-store",
-      "middleware.tusUpload: store must implement { create, head, append, terminate }");
-  }
+  validateOpts.requireMethods(store, ["create", "head", "append", "terminate"],
+    "middleware.tusUpload: store", TusError, "tus/bad-store");
 
   var maxSize = opts.maxSize;
   if (maxSize !== undefined && (typeof maxSize !== "number" || !isFinite(maxSize) || maxSize <= 0)) {
@@ -451,11 +440,7 @@ function create(opts) {
     return new Date(rec.expireAt).toUTCString();
   }
 
-  function _emitMetric(verb, _outcome, _metadata) {
-    if (!auditOn) return;
-    try { observability().safeEvent("middleware.tusUpload." + verb, 1, {}); }
-    catch (_e) { /* drop-silent — observability sink */ }
-  }
+  var _emitMetric = observability().namespaced("middleware.tusUpload", auditOn);
 
   async function _handleOptions(req, res) {
     var headers = _emitTusBaseHeaders(res, {

package/lib/middleware/web-app-manifest.js

@@ -29,6 +29,7 @@
 var lazyRequire = require("../lazy-require");
 var safeJson = require("../safe-json");
 var validateOpts = require("../validate-opts");
+var denyResponse = require("./deny-response");
 var { defineClass } = require("../framework-error");
 
 var WebAppManifestError = defineClass("WebAppManifestError", { alwaysPermanent: true });
@@ -135,13 +136,7 @@ function create(opts) {
                   (alsoAtJsonPath && path === "/manifest.json");
     if (!matches) return next();
     if (req.method !== "GET" && req.method !== "HEAD") {
-      var bodyMsg = "Method Not Allowed";
-      res.writeHead(405, {                                                       // HTTP 405 status
-        "Allow":          "GET, HEAD",
-        "Content-Type":   "text/plain; charset=utf-8",
-        "Content-Length": Buffer.byteLength(bodyMsg),
-      });
-      res.end(bodyMsg);
+      denyResponse.methodNotAllowed(res, "GET, HEAD");
       return;
     }
     res.writeHead(200, {                                                         // HTTP 200 status

package/lib/migrations.js

@@ -39,6 +39,7 @@
  */
 
 var nodePath = require("node:path");
+var moduleLoader = require("./module-loader");
 var atomicFile = require("./atomic-file");
 var dbSchema = require("./db-schema");
 var frameworkSchema = require("./framework-schema");
@@ -269,21 +270,11 @@ function _resolveDb(opts) {
 }
 
 function _loadMigration(file, dir) {
-  var fullPath = nodePath.join(dir, file);
-  // Drop the require cache for this path before loading so a test that
-  // changes a migration file between calls picks up the new content.
-  // Production deployments would always restart the process, but this
-  // keeps test fixtures sane.
-  try { delete require.cache[require.resolve(fullPath)]; } catch (_e) { /* not yet cached */ }
-  var mod;
-  // Operator-supplied migration — dynamic by design, can't be bundle-
-  // traced. Host-CLI scope; deploying via SEA / pkg drops this surface.
-  try { mod = require(fullPath); }   // allow:dynamic-require — operator-supplied migration
-  catch (e) {
-    throw new MigrationError("migrations/load-failed",
+  var mod = moduleLoader.requireFresh(nodePath.join(dir, file), function (e) {
+    return new MigrationError("migrations/load-failed",
       "migration '" + file + "' failed to load: " + ((e && e.message) || String(e)),
       true);
-  }
+  });
   if (!mod || typeof mod.up !== "function") {
     throw new MigrationError("migrations/missing-up",
       "migration '" + file + "' must export an `up(db)` function", true);

package/lib/mime-parse.js

@@ -37,32 +37,48 @@
  * mdn: 1 MiB) so this module's hot-path doesn't add its own cap.
  */
 
-function parseHeaderBlock(text) {
-  // RFC 5322 §2.2.3 — continuation lines (lines starting with WSP)
-  // fold onto the previous header value. The header section ends at
-  // the first empty line; subsequent lines belong to the body.
-  var lines = text.split(/\r?\n/);
-  var unfolded = [];
+function classifyHeaderBlock(text) {
+  // RFC 5322 §2.2 — every line of a header section is either a header field
+  // (`name: value`), a folding continuation (leading WSP), or the empty line
+  // that ends the section. Anything else is MALFORMED — and a colon-less line
+  // sitting in the header section is the header-injection / SMTP-smuggling
+  // signal (attacker content on a bare line followed by an injected
+  // Bcc/To/From header). `fields` is the parsed headers (boundary-aware,
+  // continuation-unfolded); `malformed` is the injection/structure evidence the
+  // silent-skip parsers (email, mime, dsn, arc) all dropped on the floor.
+  var lines = String(text == null ? "" : text).split(/\r?\n/);
+  var unfolded = [];                                                            // [{ line, lineIndex }]
   for (var i = 0; i < lines.length; i += 1) {
     var line = lines[i];
-    if (line.length === 0) break;
+    if (line.length === 0) break;                                              // header/body boundary
     if ((line.charAt(0) === " " || line.charAt(0) === "\t") && unfolded.length > 0) {
-      unfolded[unfolded.length - 1] += " " + line.replace(/^\s+/, "");
+      unfolded[unfolded.length - 1].line += " " + line.replace(/^\s+/, "");
     } else {
-      unfolded.push(line);
+      unfolded.push({ line: line, lineIndex: i });
     }
   }
-  var headers = [];
+  var fields = [];
+  var malformed = [];
   for (var j = 0; j < unfolded.length; j += 1) {
-    var l = unfolded[j];
-    var colonAt = l.indexOf(":");
-    if (colonAt === -1) continue;
-    headers.push({
-      name:  l.slice(0, colonAt).trim(),
-      value: l.slice(colonAt + 1).trim(),
+    var entry = unfolded[j];
+    var colonAt = entry.line.indexOf(":");
+    if (colonAt === -1) {
+      malformed.push({ lineIndex: entry.lineIndex, line: entry.line, reason: "no-colon" });
+      continue;
+    }
+    fields.push({
+      name:  entry.line.slice(0, colonAt).trim(),
+      value: entry.line.slice(colonAt + 1).trim(),
     });
   }
-  return headers;
+  return { fields: fields, malformed: malformed };
+}
+
+function parseHeaderBlock(text) {
+  // The fields view of the shared classifier — kept for every caller that only
+  // wants the parsed headers (the malformed lines are reached via
+  // classifyHeaderBlock for structure/injection validation).
+  return classifyHeaderBlock(text).fields;
 }
 
 function splitHeadersAndBody(text) {
@@ -189,6 +205,7 @@ function addressType(addr) {
 
 module.exports = {
   parseHeaderBlock:    parseHeaderBlock,
+  classifyHeaderBlock: classifyHeaderBlock,
   splitHeadersAndBody: splitHeadersAndBody,
   findHeader:          findHeader,
   parseContentType:    parseContentType,

package/lib/module-loader.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * lib/module-loader.js — the single audited entry point for loading an
+ * operator-supplied module file (a migration or a seed) by path.
+ *
+ * Operator modules execute arbitrary code on `require`, so the dynamic
+ * `require()` lives here behind ONE `allow:dynamic-require` marker rather
+ * than scattered across every host-CLI loader (`b.migrations`,
+ * `b.seeders`, `b.externalDb.migrate`). The require cache is busted first
+ * so a dev / test rewriting a fixture between calls picks up the new
+ * content (production deployments restart the process). The dynamic
+ * require does not survive SEA / esbuild bundling — operator migrations
+ * and seeds are host-CLI scope, not framework-internal scope.
+ *
+ * The caller owns path construction (it knows its own directory layout)
+ * and the typed, domain-specific error it throws on a load failure
+ * (parse error, throwing top-level code), so resolution stays identical
+ * to the per-loader form it replaces.
+ */
+
+/**
+ * requireFresh(absPath, onLoadError) — bust the require cache for
+ * `absPath`, then require it fresh. `absPath` MUST be absolute (a bare
+ * relative path would resolve against node_modules, which is never an
+ * operator file). On a load failure, `onLoadError(err)` builds the
+ * caller's typed error, which is thrown.
+ *
+ *   var mod = moduleLoader.requireFresh(path.join(dir, file), function (e) {
+ *     return new MigrationError("migrations/load-failed",
+ *       "migration '" + file + "' failed to load: " + ((e && e.message) || String(e)), true);
+ *   });
+ */
+function requireFresh(absPath, onLoadError) {
+  try { delete require.cache[require.resolve(absPath)]; } catch (_e) { /* not yet cached */ }
+  try {
+    return require(absPath);   // allow:dynamic-require — operator-supplied module (migration / seed)
+  } catch (e) {
+    throw onLoadError(e);
+  }
+}
+
+module.exports = {
+  requireFresh: requireFresh,
+};

package/lib/money.js

@@ -277,6 +277,32 @@ Money.prototype.multiply = function (factor, opts) {
   return new Money(quotient, this.currency);
 };
 
+/**
+ * @primitive  b.money.Money.roundToIncrement
+ * @signature  b.money.Money.roundToIncrement(step, opts?)
+ * @since      0.15.13
+ * @status     stable
+ * @related    b.money.roundMinor, b.money.Money
+ *
+ * Snap this amount to the nearest multiple of `step` minor units, returning a
+ * new `Money` in the same currency — the cash-rounding step a coarser
+ * denomination needs (CHF to the nearest 0.05, SEK to the nearest 0.10, a
+ * 100-unit price step) without leaving the type. Integer-only; immutable;
+ * negative amounts (refund previews) round on the correct side of the tie. See
+ * `b.money.roundMinor` for the raw-integer form and the mode semantics.
+ *
+ * @opts
+ *   mode:  "half-even" | "half-up" | "half-down" | "ceiling" | "floor",  // default: half-even
+ *
+ * @example
+ *   b.money.of("12.32", "CHF").roundToIncrement(5, { mode: "half-up" });  // → CHF 12.30
+ *   b.money.of("19.97", "SEK").roundToIncrement(10);                      // → SEK 20.00
+ */
+Money.prototype.roundToIncrement = function (step, opts) {
+  opts = opts || {};
+  return new Money(roundMinor(this._minor, step, opts.mode || "half-even"), this.currency);
+};
+
 // _rationalFromDecimalString -- `"1.085"` -> { num: 1085n, den: 1000n }.
 // Strict shape; same refusals as _parseDecimalString.
 function _rationalFromDecimalString(s) {
@@ -333,6 +359,84 @@ function _divRound(n, d, rounding) {
   return r < 0n ? q - 1n : q + 1n;
 }
 
+// Cash-rounding modes for roundMinor / Money.roundToIncrement. half-even
+// (banker's) is the default and matches the rest of the module; half-up rounds
+// a tie away from zero, half-down toward zero; ceiling/floor are directional
+// (toward +inf / -inf) regardless of distance.
+var INCREMENT_MODES = {
+  "half-even": true, "half-up": true, "half-down": true, "ceiling": true, "floor": true,
+};
+
+function _toIncrementBigInt(step) {
+  if (typeof step === "bigint") {
+    if (step <= 0n) throw new MoneyError("money/bad-increment",
+      "step must be a positive integer of minor units");
+    return step;
+  }
+  if (typeof step === "number" && Number.isInteger(step) && step > 0) return BigInt(step);
+  throw new MoneyError("money/bad-increment",
+    "step must be a positive integer (BigInt or safe integer Number) of minor units; got " +
+    (typeof step === "number" ? String(step) : typeof step));
+}
+
+/**
+ * @primitive  b.money.roundMinor
+ * @signature  b.money.roundMinor(minor, step, mode?)
+ * @since      0.15.13
+ * @status     stable
+ * @related    b.money.Money, b.money.fromMinorUnits
+ *
+ * Snap a raw minor-unit integer to the nearest multiple of `step` minor units —
+ * the cash-rounding step a coarser cash denomination needs even though the
+ * currency's ISO 4217 minor unit is finer (a CHF total to the nearest 5 rappen
+ * after the 1/2-rappen coins were retired, a SEK total to the nearest 10 öre, a
+ * JPY total to a 100-unit psychological-pricing step). Pure BigInt math — no
+ * `Number` in the value path — and the remainder sign is handled so a negative
+ * amount (a refund preview) rounds on the correct side of the tie.
+ *
+ * `minor` accepts a BigInt or a safe integer `Number`; the return is a BigInt.
+ *
+ * @opts
+ *   mode:  "half-even" | "half-up" | "half-down" | "ceiling" | "floor",  // default: half-even
+ *
+ * @example
+ *   b.money.roundMinor(1232n, 5n);              // CHF 12.32 → nearest 0.05 → 1230n (12.30)
+ *   b.money.roundMinor(25n, 10n, "half-even");  // tie → even multiple → 20n
+ *   b.money.roundMinor(25n, 10n, "half-up");    // tie away from zero → 30n
+ *   b.money.roundMinor(-25n, 10n, "half-up");   // refund tie away from zero → -30n
+ */
+function roundMinor(minor, step, mode) {
+  mode = mode || "half-even";
+  if (typeof minor === "number" && Number.isInteger(minor)) minor = BigInt(minor);
+  if (typeof minor !== "bigint") {
+    throw new MoneyError("money/bad-minor-units",
+      "minor must be an integer (BigInt or safe integer Number); got " + (typeof minor));
+  }
+  if (!INCREMENT_MODES[mode]) {
+    throw new MoneyError("money/bad-rounding-mode",
+      "mode must be one of half-even | half-up | half-down | ceiling | floor; got " + String(mode));
+  }
+  var stepBig = _toIncrementBigInt(step);
+  var q = minor / stepBig;
+  var r = minor - q * stepBig;
+  if (r === 0n) return minor;
+  // lower = the multiple toward -inf, upper = toward +inf. BigInt division
+  // truncates toward zero, so the bracket flips by sign of `minor`.
+  var lower, upper;
+  if (minor >= 0n) { lower = q * stepBig; upper = lower + stepBig; }
+  else { upper = q * stepBig; lower = upper - stepBig; }
+  if (mode === "floor") return lower;
+  if (mode === "ceiling") return upper;
+  var distLow = minor - lower;     // >= 0
+  var distHigh = upper - minor;    // >= 0
+  if (distLow < distHigh) return lower;
+  if (distHigh < distLow) return upper;
+  // Exactly on the tie.
+  if (mode === "half-up") return (minor >= 0n) ? upper : lower;     // away from zero
+  if (mode === "half-down") return (minor >= 0n) ? lower : upper;   // toward zero
+  return ((lower / stepBig) % 2n === 0n) ? lower : upper;           // half-even
+}
+
 // allocate -- split `this` into `weights.length` parts proportional to
 // the weights, distributing every minor unit. Largest-remainder
 // method: floor each share, then hand out the leftover units to the
@@ -693,6 +797,7 @@ module.exports = {
   parse:           parse,
   zero:            zero,
   convert:         convert,
+  roundMinor:      roundMinor,
   CURRENCIES:      CURRENCIES,
   Money:           Money,
   MoneyError:      MoneyError,

package/lib/mtls-ca.js

@@ -58,6 +58,9 @@ var nodeCrypto = require("node:crypto");
 var atomicFile = require("./atomic-file");
 var C = require("./constants");
 var lazyRequire = require("./lazy-require");
+// Lazy — the SHA3-512 fingerprint surfaced from issuance must match the one
+// the require-mtls gate pins (b.crypto.sha3Hash(certPem)).
+var bCrypto = lazyRequire(function () { return require("./crypto"); });
 var { boot } = require("./log");
 var safeBuffer = require("./safe-buffer");
 var safeJson = require("./safe-json");
@@ -193,7 +196,7 @@ function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
     "dataDir", "paths", "vault",
-    "caKeySealedMode", "generation", "engine",
+    "caKeySealedMode", "generation", "engine", "revocationStore",
   ], "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).
@@ -370,6 +373,29 @@ function create(opts) {
     return fresh;
   }
 
+  // Recover the issued certificate's identity from its PEM so issuance and
+  // any later revocation/indexing share identifiers without a round-trip back
+  // through an X.509 parser. serialNumber is normalized to the same hex form
+  // revoke() stores; fingerprint is the SHA3-512 the require-mtls gate pins.
+  function _certIdentity(certPem) {
+    // serialNumber comes from an X.509 parse, which is best-effort: a custom
+    // engine (or a test double) may return a cert in a shape this Node build
+    // cannot parse as X.509. The fingerprint is a hash of the returned bytes,
+    // so it is always available and is what the require-mtls gate pins —
+    // revoke()/isRevoked() by fingerprint keep working even when the serial
+    // can't be recovered. Never let optional identity enrichment crash issuance.
+    var serialNumber = null;
+    try {
+      serialNumber = _normalizeSerial(new nodeCrypto.X509Certificate(certPem).serialNumber);
+    } catch (_e) {
+      serialNumber = null;
+    }
+    return {
+      serialNumber: serialNumber,
+      fingerprint:  bCrypto().sha3Hash(certPem),
+    };
+  }
+
   async function generateClientCert(opts2) {
     opts2 = opts2 || {};
     var ca = await initCA();
@@ -379,7 +405,10 @@ function create(opts) {
       throw new MtlsCaError("mtls-ca/bad-engine-output",
         "engine.signClientCert must return { cert, key, ca?, issuedAt?, expiresAt? }");
     }
-    return result;
+    // Surface the issued serial + fingerprint so the caller can track/revoke
+    // the cert by the same identifiers without re-parsing the PEM.
+    var id = _certIdentity(result.cert);
+    return Object.assign({}, result, { serialNumber: id.serialNumber, fingerprint: id.fingerprint });
   }
 
   async function generateClientP12(opts2) {
@@ -395,32 +424,63 @@ function create(opts) {
       throw new MtlsCaError("mtls-ca/bad-engine-output",
         "engine.packageP12 must return { p12: Buffer, certPem, issuedAt, expiresAt }");
     }
+    if (typeof result.certPem === "string") {
+      var id12 = _certIdentity(result.certPem);
+      return Object.assign({}, result, { serialNumber: id12.serialNumber, fingerprint: id12.fingerprint });
+    }
     return result;
   }
 
   // ---- Revocation registry + CRL ----
 
-  function _loadRevocations() {
-    if (!nodeFs.existsSync(paths.revocations)) return { revocations: [] };
-    try {
-      // safeJson.parse caps depth + size + protects against
-      // proto-pollution; the revocation file is under the operator's
-      // dataDir but a tampered or truncated file shouldn't be able to
-      // corrupt the rotator process.
-      var json = safeJson.parse(nodeFs.readFileSync(paths.revocations, "utf8"),
-        { maxBytes: C.BYTES.mib(16) });
-      if (!json || !Array.isArray(json.revocations)) return { revocations: [] };
-      return json;
-    } catch (e) {
-      throw new MtlsCaError("mtls-ca/revocation-corrupt",
-        "could not parse " + paths.revocations + ": " +
-        ((e && e.message) || String(e)));
+  // Revocation entries are read + written through a store so the registry can
+  // live somewhere other than the default plaintext revocations.json — e.g. an
+  // operator-supplied encrypted / clustered store (the bring-your-own-store
+  // precedent b.queue's config.db set). Contract (sync):
+  //   list()     -> array of revocation entries
+  //   add(entry) -> append one entry (the caller has already deduped)
+  function _defaultFileStore() {
+    function _list() {
+      if (!nodeFs.existsSync(paths.revocations)) return [];
+      try {
+        // safeJson.parse caps depth + size + protects against
+        // proto-pollution; a tampered or truncated file shouldn't be able to
+        // corrupt the rotator process.
+        var json = safeJson.parse(nodeFs.readFileSync(paths.revocations, "utf8"),
+          { maxBytes: C.BYTES.mib(16) });
+        return (json && Array.isArray(json.revocations)) ? json.revocations : [];
+      } catch (e) {
+        throw new MtlsCaError("mtls-ca/revocation-corrupt",
+          "could not parse " + paths.revocations + ": " + ((e && e.message) || String(e)));
+      }
     }
+    return {
+      list: _list,
+      add:  function (entry) {
+        var entries = _list();
+        entries.push(entry);
+        atomicFile.writeSync(paths.revocations,
+          JSON.stringify({ revocations: entries }, null, 2) + "\n", { mode: 0o600 });
+      },
+    };
   }
+  var revocationStore = opts.revocationStore || _defaultFileStore();
+  validateOpts.requireMethods(revocationStore, ["list", "add"],
+    "opts.revocationStore", MtlsCaError, "mtls-ca/bad-revocation-store");
 
-  function _saveRevocations(state) {
-    atomicFile.writeSync(paths.revocations,
-      JSON.stringify(state, null, 2) + "\n", { mode: 0o600 });
+  // A fingerprint is the SHA3-512 hex the require-mtls gate pins. Normalize it
+  // like a serial (strip 0x / separators / whitespace, lowercase, hex-validate)
+  // so a consumer can revoke by the same value the gate compares against.
+  function _normalizeFingerprint(fp) {
+    if (!fp || typeof fp !== "string") {
+      throw new MtlsCaError("mtls-ca/bad-fingerprint", "fingerprint must be a non-empty string");
+    }
+    var stripped = fp.replace(/^0x/i, "").replace(/[:\-\s]/g, "");
+    if (!safeBuffer.isHex(stripped)) {
+      throw new MtlsCaError("mtls-ca/bad-fingerprint",
+        "fingerprint contains non-hex characters: " + JSON.stringify(fp));
+    }
+    return stripped.toLowerCase();
   }
 
   function _normalizeSerial(s) {
@@ -466,46 +526,66 @@ function create(opts) {
     "aACompromise":         10,
   };
 
-  function revoke(serialNumber, opts3) {
-    var serial = _normalizeSerial(serialNumber);
+  function revoke(idOrOpts, opts3) {
+    // Accept either revoke(serialString, { reason, fingerprint }) — the
+    // backward-compatible serial-keyed form — or revoke({ serial?,
+    // fingerprint?, reason? }). The require-mtls gate denies by fingerprint,
+    // so a fingerprint-indexed consumer can revoke by the same value it pins
+    // on; serial-keyed behavior stays the default. At least one key required.
+    var spec = (idOrOpts && typeof idOrOpts === "object") ? idOrOpts : null;
     opts3 = opts3 || {};
-    var reasonName = opts3.reason || "unspecified";
+    var serialIn      = spec ? spec.serial      : idOrOpts;
+    var fingerprintIn = spec ? spec.fingerprint : opts3.fingerprint;
+    var reasonName    = (spec ? spec.reason : opts3.reason) || "unspecified";
+
+    var serial = (serialIn !== undefined && serialIn !== null) ? _normalizeSerial(serialIn) : null;
+    var fingerprint = (fingerprintIn !== undefined && fingerprintIn !== null)
+      ? _normalizeFingerprint(fingerprintIn) : null;
+    if (!serial && !fingerprint) {
+      throw new MtlsCaError("mtls-ca/no-revocation-key",
+        "revoke requires a serial number or a fingerprint " +
+        "(revoke(serial, opts) or revoke({ serial, fingerprint }))");
+    }
     var reasonCode = CRL_REASON_BY_NAME[reasonName];
     if (reasonCode === undefined) {
       throw new MtlsCaError("mtls-ca/bad-reason",
         "revoke: unknown reason '" + reasonName + "' (valid: " +
         Object.keys(CRL_REASON_BY_NAME).join(", ") + ")");
     }
-    var state = _loadRevocations();
-    var existing = state.revocations.find(function (r) {
-      return r.serialNumber === serial;
+    var existing = revocationStore.list().find(function (r) {
+      return (serial && r.serialNumber === serial) || (fingerprint && r.fingerprint === fingerprint);
     });
     if (existing) {
-      // Idempotent — repeated revoke() of the same serial doesn't
+      // Idempotent — repeated revoke() of the same serial/fingerprint doesn't
       // shift the revokedAt timestamp.
       return existing;
     }
     var entry = {
       serialNumber: serial,
+      fingerprint:  fingerprint,
       reason:       reasonName,
       reasonCode:   reasonCode,
       revokedAt:    Date.now(),
     };
-    state.revocations.push(entry);
-    _saveRevocations(state);
+    revocationStore.add(entry);
     return entry;
   }
 
-  function isRevoked(serialNumber) {
-    var serial = _normalizeSerial(serialNumber);
-    var state = _loadRevocations();
-    return state.revocations.some(function (r) {
-      return r.serialNumber === serial;
+  function isRevoked(serialOrFingerprint) {
+    // Accept a serial number OR a SHA3-512 fingerprint — both are hex, so one
+    // normalized form is matched against either key each entry carries.
+    if (!serialOrFingerprint || typeof serialOrFingerprint !== "string") {
+      throw new MtlsCaError("mtls-ca/bad-revocation-key",
+        "isRevoked requires a serial number or a fingerprint (hex string)");
+    }
+    var norm = _normalizeFingerprint(serialOrFingerprint);
+    return revocationStore.list().some(function (r) {
+      return r.serialNumber === norm || r.fingerprint === norm;
     });
   }
 
   function getRevocations() {
-    return _loadRevocations().revocations.slice();
+    return revocationStore.list().slice();
   }
 
   // Generate a signed X.509 CRL covering every entry in the registry.
@@ -521,7 +601,7 @@ function create(opts) {
         "framework's bundled CA engine, which supports it");
     }
     var ca = await initCA();
-    var revocations = _loadRevocations().revocations;
+    var revocations = revocationStore.list();
     var nowMs = Date.now();
     var thisUpdate = opts3.thisUpdate || new Date(nowMs);
     var nextUpdate = opts3.nextUpdate ||