@blamejs/core 0.6.37 → 0.6.58

package/lib/log-stream-otlp-grpc.js

@@ -0,0 +1,413 @@
+"use strict";
+/**
+ * OTLP gRPC log sink — OpenTelemetry Protocol logs over gRPC.
+ *
+ * Companion to lib/log-stream-otlp.js (HTTP/JSON). The OTel collector
+ * accepts both transports; gRPC is the higher-throughput path with
+ * less per-batch overhead and is preferred for production deployments
+ * pushing >100K logs/s.
+ *
+ * Wire format:
+ *   - HTTP/2 (node:http2) POST to
+ *     /opentelemetry.proto.collector.logs.v1.LogsService/Export
+ *   - content-type: application/grpc+proto
+ *   - te: trailers
+ *   - Body: 1-byte compression flag (0 = none) + 4-byte big-endian
+ *           length + protobuf-encoded ExportLogsServiceRequest
+ *   - Response status: HTTP/2 trailer `grpc-status` (0 = OK)
+ *
+ * The protobuf body is encoded by hand via lib/protobuf-encoder.js —
+ * no schema parser ships in the bundle, consistent with the framework's
+ * vendoring stance. The OTel logs schema is small and stable
+ * (https://github.com/open-telemetry/opentelemetry-proto/blob/main/
+ *  opentelemetry/proto/logs/v1/logs.proto).
+ *
+ * Severity mapping follows the OTel spec: debug=5 / info=9 / warn=13 /
+ * error=17.
+ */
+var http2 = require("node:http2");
+var C = require("./constants");
+var pb = require("./protobuf-encoder");
+var safeUrl = require("./safe-url");
+var { LogStreamError } = require("./framework-error");
+
+var _err = LogStreamError.factory;
+
+var DEFAULTS = {
+  scopeName:     "blamejs",
+  batchSize:     100,
+  maxBatchAgeMs: C.TIME.seconds(5),
+  timeoutMs:     C.TIME.seconds(30),
+  bufferLimit:   10000,
+};
+
+var SEVERITY = {
+  debug: { number: 5,  text: "DEBUG" },
+  info:  { number: 9,  text: "INFO"  },
+  warn:  { number: 13, text: "WARN"  },
+  error: { number: 17, text: "ERROR" },
+};
+
+// ---- Protobuf message shapes (OTel logs.proto) ----
+//
+// Field numbers match
+// https://github.com/open-telemetry/opentelemetry-proto/blob/main/
+//   opentelemetry/proto/{common,resource,logs}/v1/*.proto
+//
+// AnyValue (common.proto) — proto3 oneof; we emit one of:
+//   string_value = 1, bool_value = 2, int_value = 3 (int64 varint),
+//   double_value = 4, bytes_value = 7
+function _encodeAnyValue(v) {
+  if (v == null)             return pb.string(1, "");                   // string_value=""
+  if (typeof v === "string") return pb.string(1, v);
+  if (typeof v === "boolean")return pb.bool(2, v);
+  if (typeof v === "number") {
+    if (Number.isInteger(v) && v >= 0) return pb.uint64(3, v);          // int_value (proto3 int64 varint)
+    return pb.double(4, v);                                              // double_value
+  }
+  if (Buffer.isBuffer(v))    return pb.bytes(7, v);
+  // Fallback — JSON-stringify objects/arrays into string_value rather
+  // than implementing the full ArrayValue / KeyValueList branches.
+  // Operators wanting structured nested attributes shape their record
+  // up-front into top-level scalars or stringified JSON.
+  try { return pb.string(1, JSON.stringify(v)); }
+  catch (_e) { return pb.string(1, String(v)); }
+}
+
+// KeyValue (common.proto): key=1 (string), value=2 (AnyValue)
+function _encodeKeyValue(key, value) {
+  return Buffer.concat([
+    pb.string(1, key),
+    pb.embeddedMessage(2, _encodeAnyValue(value)),
+  ]);
+}
+
+function _encodeAttributes(obj) {
+  if (!obj) return [];
+  var out = [];
+  var keys = Object.keys(obj);
+  for (var i = 0; i < keys.length; i++) {
+    var k = keys[i];
+    var v = obj[k];
+    if (v === undefined) continue;
+    out.push(_encodeKeyValue(k, v));
+  }
+  return out;
+}
+
+// Resource (resource.proto): attributes=1 (repeated KeyValue),
+// dropped_attributes_count=2
+function _encodeResource(attrs) {
+  var kvs = _encodeAttributes(attrs);
+  if (kvs.length === 0) return Buffer.alloc(0);
+  var pieces = kvs.map(function (kvBody) { return pb.embeddedMessage(1, kvBody); });
+  return Buffer.concat(pieces);
+}
+
+// InstrumentationScope (common.proto): name=1, version=2
+function _encodeScope(name, version) {
+  return Buffer.concat([
+    pb.string(1, name || DEFAULTS.scopeName),
+    pb.string(2, version || ""),
+  ]);
+}
+
+// LogRecord (logs.proto):
+//   time_unix_nano = 1 (fixed64)
+//   severity_number = 2 (enum / varint)
+//   severity_text = 3 (string)
+//   body = 5 (AnyValue)
+//   attributes = 6 (repeated KeyValue)
+//   observed_time_unix_nano = 11 (fixed64)
+function _encodeLogRecord(record) {
+  var sev = SEVERITY[record.level] || SEVERITY.info;
+  var tsMs = record.ts || Date.now();
+  // Convert ms to ns. Use BigInt to avoid 53-bit precision loss on
+  // operators emitting > year-2255 timestamps. For ms-resolution
+  // records the LSB nanos are 0; we still send fixed64.
+  var tsNs = BigInt(tsMs) * 1000000n;
+  var attrPieces = _encodeAttributes(record.meta).map(function (kvBody) {
+    return pb.embeddedMessage(6, kvBody);
+  });
+  var msg = (record.message != null ? String(record.message) : "");
+  return Buffer.concat([
+    pb.fixed64(1, tsNs),
+    pb.uint32(2, sev.number),
+    pb.string(3, sev.text),
+    pb.embeddedMessage(5, pb.string(1, msg)),   // body.string_value
+    Buffer.concat(attrPieces),
+    pb.fixed64(11, tsNs),
+  ]);
+}
+
+// ScopeLogs (logs.proto): scope=1 (InstrumentationScope),
+// log_records=2 (repeated LogRecord), schema_url=3
+function _encodeScopeLogs(records, scopeName, scopeVersion) {
+  var recordPieces = records.map(function (rec) {
+    return pb.embeddedMessage(2, _encodeLogRecord(rec));
+  });
+  return Buffer.concat([
+    pb.embeddedMessage(1, _encodeScope(scopeName, scopeVersion)),
+    Buffer.concat(recordPieces),
+  ]);
+}
+
+// ResourceLogs (logs.proto): resource=1 (Resource),
+// scope_logs=2 (repeated ScopeLogs), schema_url=3
+function _encodeResourceLogs(records, cfg) {
+  var resourceBody = _encodeResource(_resourceAttrs(cfg));
+  var scopeLogsBody = _encodeScopeLogs(records, cfg.scopeName, cfg.scopeVersion);
+  return Buffer.concat([
+    pb.embeddedMessage(1, resourceBody),
+    pb.embeddedMessage(2, scopeLogsBody),
+  ]);
+}
+
+// ExportLogsServiceRequest (collector logs.proto):
+//   resource_logs = 1 (repeated ResourceLogs)
+function _encodeExportRequest(records, cfg) {
+  return pb.embeddedMessage(1, _encodeResourceLogs(records, cfg));
+}
+
+function _resourceAttrs(cfg) {
+  var attrs = Object.assign({}, cfg.resourceAttributes || {});
+  if (cfg.serviceName)    attrs["service.name"]    = cfg.serviceName;
+  if (cfg.serviceVersion) attrs["service.version"] = cfg.serviceVersion;
+  return attrs;
+}
+
+// ---- gRPC framing ----
+
+function _frame(messageBuf) {
+  // 1 byte (compression flag, 0 = uncompressed) + 4 bytes (length, BE)
+  // + message bytes.
+  var hdr = Buffer.alloc(5);
+  hdr[0] = 0;
+  hdr.writeUInt32BE(messageBuf.length, 1);
+  return Buffer.concat([hdr, messageBuf]);
+}
+
+// ---- HTTP/2 client ----
+//
+// One client per sink instance. The OTLP gRPC server keeps the
+// connection alive across many Export calls; we re-create on
+// disconnect.
+function _makeClient(cfg) {
+  var url = new URL(cfg.url);
+  var authority = url.protocol + "//" + url.host;
+  var sessionOpts = {};
+  if (cfg.ca) sessionOpts.ca = cfg.ca;
+  if (cfg.servername) sessionOpts.servername = cfg.servername;
+  if (cfg.allowInsecure) sessionOpts.rejectUnauthorized = false;
+  var session = http2.connect(authority, sessionOpts);
+  session.on("error", function () { /* surfaced through request err */ });
+  if (typeof session.unref === "function") session.unref();
+  return session;
+}
+
+function _doExport(session, cfg, records) {
+  return new Promise(function (resolve, reject) {
+    var body = _encodeExportRequest(records, cfg);
+    var framed = _frame(body);
+
+    var headers = Object.assign({
+      ":method":             "POST",
+      ":path":               "/opentelemetry.proto.collector.logs.v1.LogsService/Export",
+      "content-type":        "application/grpc+proto",
+      "te":                  "trailers",
+      "grpc-encoding":       "identity",
+      "grpc-accept-encoding": "identity",
+    }, cfg.headers || {});
+
+    var req = session.request(headers);
+    var resStatus = null;
+    var trailers = null;
+    var errored = false;
+
+    var timer = setTimeout(function () {
+      errored = true;
+      try { req.close(http2.constants.NGHTTP2_CANCEL); } catch (_e) {}
+      reject(_err("ETIMEDOUT",
+        "otlp-grpc: request timed out after " + cfg.timeoutMs + "ms"));
+    }, cfg.timeoutMs);
+
+    req.on("response", function (h) {
+      resStatus = h[":status"];
+    });
+    req.on("trailers", function (t) { trailers = t; });
+    req.on("error", function (e) {
+      if (errored) return;
+      errored = true;
+      clearTimeout(timer);
+      reject(_err("HTTP2_ERROR", "otlp-grpc: " + (e && e.message || String(e))));
+    });
+    req.on("close", function () {
+      if (errored) return;
+      clearTimeout(timer);
+      if (resStatus !== 200) {
+        return reject(_err("HTTP_ERROR",
+          "otlp-grpc: HTTP/2 status " + resStatus));
+      }
+      // Trailers MUST carry grpc-status. The OTel collector returns
+      // grpc-status: 0 on success.
+      var grpcStatus = trailers && trailers["grpc-status"];
+      var grpcMessage = trailers && trailers["grpc-message"];
+      if (grpcStatus === undefined) {
+        return reject(_err("HTTP_ERROR",
+          "otlp-grpc: response missing grpc-status trailer"));
+      }
+      if (String(grpcStatus) !== "0") {
+        return reject(_err("HTTP_ERROR",
+          "otlp-grpc: grpc-status " + grpcStatus +
+          (grpcMessage ? " — " + grpcMessage : "")));
+      }
+      resolve();
+    });
+
+    req.end(framed);
+  });
+}
+
+// ---- Public sink factory ----
+
+function create(config) {
+  if (!config || !config.url) {
+    throw _err("BAD_OPT", "log-stream otlp-grpc: { url } is required");
+  }
+  // Reject http:// without explicit allowInsecure — gRPC endpoints
+  // are virtually always TLS in real deployments.
+  var allowedProtocols = config.allowedProtocols || safeUrl.ALLOW_HTTP_TLS;
+  safeUrl.parse(config.url, {
+    allowedProtocols: allowedProtocols,
+    errorClass:       LogStreamError,
+  });
+
+  var cfg = Object.assign({}, DEFAULTS, config);
+  cfg.batchSize     = Number(cfg.batchSize)     || DEFAULTS.batchSize;
+  cfg.maxBatchAgeMs = Number(cfg.maxBatchAgeMs) || DEFAULTS.maxBatchAgeMs;
+  cfg.timeoutMs     = Number(cfg.timeoutMs)     || DEFAULTS.timeoutMs;
+  cfg.bufferLimit   = Number(cfg.bufferLimit)   || DEFAULTS.bufferLimit;
+
+  var onDrop = typeof config.onDrop === "function" ? config.onDrop : null;
+  function _emitDrop(reason, batch, err) {
+    if (!onDrop) return;
+    try { onDrop({ reason: reason, batch: batch, error: err || null }); }
+    catch (_e) {}
+  }
+
+  var buffer = [];
+  var inFlight = false;
+  var closed = false;
+  var flushTimer = null;
+  var session = null;
+  var inflightPromise = null;
+
+  function _ensureSession() {
+    if (session && !session.destroyed) return session;
+    session = _makeClient(cfg);
+    return session;
+  }
+
+  function _scheduleFlush() {
+    if (flushTimer || closed) return;
+    flushTimer = setTimeout(function () {
+      flushTimer = null;
+      _flush().catch(function () { /* drained internally */ });
+    }, cfg.maxBatchAgeMs);
+    if (typeof flushTimer.unref === "function") flushTimer.unref();
+  }
+
+  async function _flush() {
+    if (inFlight || buffer.length === 0) return;
+    inFlight = true;
+    try {
+      while (buffer.length > 0 && !closed) {
+        var batch = buffer.splice(0, cfg.batchSize);
+        try {
+          var s = _ensureSession();
+          inflightPromise = _doExport(s, cfg, batch);
+          await inflightPromise;
+        } catch (e) {
+          _emitDrop("send-failed", batch, e);
+        } finally {
+          inflightPromise = null;
+        }
+      }
+    } finally {
+      inFlight = false;
+    }
+  }
+
+  function emit(record) {
+    if (closed) {
+      _emitDrop("sink-closed", [record], null);
+      return Promise.resolve({ accepted: false, reason: "closed" });
+    }
+    if (buffer.length >= cfg.bufferLimit) {
+      var dropped = buffer.shift();
+      _emitDrop("overflow", [dropped], null);
+    }
+    buffer.push(record);
+    if (buffer.length >= cfg.batchSize) {
+      // Drain immediately; don't await — emit is fire-and-forget on the
+      // hot path. Errors surface via onDrop.
+      _flush().catch(function () {});
+    } else {
+      _scheduleFlush();
+    }
+    return Promise.resolve({ accepted: true, queued: buffer.length });
+  }
+
+  async function close() {
+    closed = true;
+    if (flushTimer) { clearTimeout(flushTimer); flushTimer = null; }
+    // Drain buffered records before tearing down the HTTP/2 session.
+    if (inflightPromise) { try { await inflightPromise; } catch (_e) {} }
+    var pending = buffer.splice(0, buffer.length);
+    if (pending.length > 0) {
+      try {
+        var s = _ensureSession();
+        await _doExport(s, cfg, pending);
+      } catch (e) {
+        _emitDrop("send-failed", pending, e);
+      }
+    }
+    // Tear down the HTTP/2 session. `session.close()` is the *graceful*
+    // close — it waits for in-flight streams to complete on their own
+    // and won't free the underlying socket while any stream is still
+    // open. By this point we've already awaited `inflightPromise` and
+    // run a final `_doExport` for any buffered records, so there's
+    // nothing left to drain; `session.destroy()` is the structurally
+    // correct call. (Calling only close() left the test fixture's
+    // server.close() hanging indefinitely on Linux CI runners — the
+    // close() was returning while the underlying TCP socket stayed
+    // connected, blocking the server-side close from completing.)
+    try {
+      if (session) {
+        try { session.close(); } catch (_e1) { /* best-effort graceful */ }
+        try { session.destroy(); } catch (_e2) { /* socket teardown */ }
+      }
+    } catch (_e) {}
+    session = null;
+  }
+
+  return {
+    protocol: "otlp-grpc",
+    emit:     emit,
+    close:    close,
+    // Test hooks — encode without sending.
+    _encodeForTest:    function (records) { return _encodeExportRequest(records, cfg); },
+    _frameForTest:     _frame,
+  };
+}
+
+module.exports = {
+  create:                create,
+  // Exposed for layer-0 tests that verify the wire encoding without
+  // standing up an HTTP/2 server.
+  _encodeAnyValue:       _encodeAnyValue,
+  _encodeKeyValue:       _encodeKeyValue,
+  _encodeLogRecord:      _encodeLogRecord,
+  _encodeExportRequest:  _encodeExportRequest,
+  _frame:                _frame,
+};

package/lib/log-stream.js

@@ -14,6 +14,12 @@
  *              Model. Operators with an OTel collector running
  *              (k8s, cloud) get standard log forwarding without a
  *              vendor-specific adapter.
+ *   otlp-grpc — same OTel Logs Data Model but over gRPC (HTTP/2 +
+ *              hand-encoded protobuf). Higher-throughput than the
+ *              JSON variant; preferred for production deployments
+ *              pushing >100K logs/s straight to a remote OTel
+ *              collector. No protobuf parser ships in the bundle —
+ *              the encoder is the framework's own (lib/protobuf-encoder.js).
  *   cloudwatch — AWS CloudWatch Logs (PutLogEvents) over HTTPS with
  *              SigV4. Pass { autoCreate: true } to have the framework
  *              issue CreateLogGroup + CreateLogStream on first emit
@@ -49,6 +55,7 @@
 var localProto      = require("./log-stream-local");
 var webhookProto    = require("./log-stream-webhook");
 var otlpProto       = require("./log-stream-otlp");
+var otlpGrpcProto   = require("./log-stream-otlp-grpc");
 var cloudwatchProto = require("./log-stream-cloudwatch");
 var syslogProto     = require("./log-stream-syslog");
 var redactor        = require("./redact");
@@ -63,6 +70,7 @@ var dispatcher = protocolDispatcher.create({
     "local":      localProto,
     "webhook":    webhookProto,
     "otlp":       otlpProto,
+    "otlp-grpc":  otlpGrpcProto,
     "cloudwatch": cloudwatchProto,
     "syslog":     syslogProto,
   },

package/lib/mail.js

@@ -454,8 +454,20 @@ function smtpTransport(opts) {
   if (opts.ecdhCurve) tlsOpts.ecdhCurve = opts.ecdhCurve;
   if (opts.ca)        tlsOpts.ca = opts.ca;
 
+  // SNI is only legal for hostnames; IP literals must omit servername
+  // (Node's tls.connect throws "Setting the TLS ServerName to an IP
+  // address is not permitted" otherwise). Operators with private CAs
+  // and an IP-only target pass `opts.servername: "expected-cn.example"`
+  // explicitly. Same convention as lib/redis-client.js.
+  var host = opts.host;
+  var servername = opts.servername;
+  if (servername === undefined) {
+    servername = (/^\d+\.\d+\.\d+\.\d+$/.test(host) || (host && host.indexOf(":") !== -1))
+                   ? undefined : host;
+  }
+
   var cfg = {
-    host:           opts.host,
+    host:           host,
     port:           port,
     user:           opts.user,
     pass:           opts.pass,
@@ -463,6 +475,7 @@ function smtpTransport(opts) {
     ehloName:       ehloName,
     timeoutMs:      timeoutMs,
     tlsOpts:        tlsOpts,
+    servername:     servername,
     dkimSigner:     opts.dkimSigner || null,
   };
 
@@ -542,7 +555,8 @@ function _smtpSend(message, cfg) {
 
     function connect() {
       if (cfg.useImplicitTLS) {
-        var tlsConnectOpts = Object.assign({ servername: cfg.host }, cfg.tlsOpts);
+        var tlsConnectOpts = Object.assign({}, cfg.tlsOpts);
+        if (cfg.servername) tlsConnectOpts.servername = cfg.servername;
         attachSocket(tls().connect(cfg.port, cfg.host, tlsConnectOpts));
       } else {
         attachSocket(net().createConnection(cfg.port, cfg.host));
@@ -562,7 +576,8 @@ function _smtpSend(message, cfg) {
       }
       else if (step === 10) {
         if (code !== 220) { fail("starttls-rejected (code " + code + ")"); return; }
-        var tlsConnectOpts = Object.assign({ socket: socket, servername: cfg.host }, cfg.tlsOpts);
+        var tlsConnectOpts = Object.assign({ socket: socket }, cfg.tlsOpts);
+        if (cfg.servername) tlsConnectOpts.servername = cfg.servername;
         var tlsSocket = tls().connect(tlsConnectOpts, function () {
           upgradedToTLS = true;
           try { socket.removeAllListeners("data"); } catch (_e) { /* listeners migrate to upgraded socket */ }

package/lib/mtls-ca.js

@@ -90,6 +90,14 @@ var DEFAULT_PATHS = {
   caKey:        "ca.key",
   caKeySealed:  "ca.key.sealed",
   caCert:       "ca.crt",
+  // Revocation registry — JSON file under dataDir tracking revoked
+  // serial numbers. Operators export this as a CRL via
+  // ca.generateCrl() (engine.generateCrl signs the list with the CA
+  // key). Persisted as JSON rather than a stored CRL because the
+  // signed CRL is a derivative artifact — the registry survives CA
+  // rotation, the CRL doesn't.
+  revocations:  "revocations.json",
+  crl:          "ca.crl",
 };
 
 var VALID_SEAL_MODES = { auto: 1, required: 1, disabled: 1 };
@@ -100,6 +108,8 @@ function _resolvePaths(dataDir, paths) {
     caKey:        path.join(dataDir, p.caKey),
     caKeySealed:  path.join(dataDir, p.caKeySealed),
     caCert:       path.join(dataDir, p.caCert),
+    revocations:  path.join(dataDir, p.revocations),
+    crl:          path.join(dataDir, p.crl),
   };
 }
 
@@ -318,6 +328,147 @@ function create(opts) {
     return result;
   }
 
+  // ---- Revocation registry + CRL ----
+
+  function _loadRevocations() {
+    if (!fs.existsSync(paths.revocations)) return { revocations: [] };
+    try {
+      var json = JSON.parse(fs.readFileSync(paths.revocations, "utf8"));
+      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)));
+    }
+  }
+
+  function _saveRevocations(state) {
+    var atomicFile = require("./atomic-file");
+    atomicFile.writeSync(paths.revocations,
+      JSON.stringify(state, null, 2) + "\n", { mode: 0o600 });
+  }
+
+  function _normalizeSerial(s) {
+    if (!s || typeof s !== "string") {
+      throw new MtlsCaError("mtls-ca/bad-serial",
+        "serial number must be a non-empty string");
+    }
+    // Strip the optional leading `0x` and any common separators
+    // (`:` or `-` or whitespace). What remains MUST be hex — otherwise
+    // we silently accept gibberish like "xyz-not-hex" (which previously
+    // normalised to a single "e" because the strip-non-hex regex left
+    // exactly one valid char). Operators pasting an openssl-printed
+    // serial use any of: "0xABC123", "AB:C1:23", "AB-C1-23", "abc 123";
+    // a typo or non-serial string fails fast instead of registering a
+    // phantom revocation row.
+    var stripped = s.replace(/^0x/i, "").replace(/[:\-\s]/g, "");
+    if (!/^[0-9a-fA-F]+$/.test(stripped)) {
+      throw new MtlsCaError("mtls-ca/bad-serial",
+        "serial number contains non-hex characters " +
+        "(allowed shapes: hex with optional 0x prefix, ':', '-', or whitespace " +
+        "as separators): " + JSON.stringify(s));
+    }
+    return stripped.toLowerCase();
+  }
+
+  // Map operator-friendly reason codes to RFC 5280 numeric codes used
+  // by X.509 CRLs. Default "unspecified" (0) when omitted.
+  var CRL_REASON_BY_NAME = {
+    "unspecified":          0,
+    "keyCompromise":        1,
+    "key-compromise":       1,
+    "caCompromise":         2,
+    "ca-compromise":        2,
+    "affiliationChanged":   3,
+    "superseded":           4,
+    "cessationOfOperation": 5,
+    "cessation-of-operation": 5,
+    "certificateHold":      6,
+    "removeFromCRL":        8,
+    "privilegeWithdrawn":   9,
+    "aACompromise":         10,
+  };
+
+  function revoke(serialNumber, opts3) {
+    var serial = _normalizeSerial(serialNumber);
+    opts3 = opts3 || {};
+    var reasonName = opts3.reason || "unspecified";
+    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;
+    });
+    if (existing) {
+      // Idempotent — repeated revoke() of the same serial doesn't
+      // shift the revokedAt timestamp.
+      return existing;
+    }
+    var entry = {
+      serialNumber: serial,
+      reason:       reasonName,
+      reasonCode:   reasonCode,
+      revokedAt:    Date.now(),
+    };
+    state.revocations.push(entry);
+    _saveRevocations(state);
+    return entry;
+  }
+
+  function isRevoked(serialNumber) {
+    var serial = _normalizeSerial(serialNumber);
+    var state = _loadRevocations();
+    return state.revocations.some(function (r) {
+      return r.serialNumber === serial;
+    });
+  }
+
+  function getRevocations() {
+    return _loadRevocations().revocations.slice();
+  }
+
+  // Generate a signed X.509 CRL covering every entry in the registry.
+  // RFC 5280 — issuer = CA subject, signed by the CA private key.
+  // Operators publish the resulting PEM at a CRL distribution point
+  // referenced from issued certs (cert extension support is on the
+  // engine roadmap; for now operators set up the URL externally).
+  async function generateCrl(opts3) {
+    opts3 = opts3 || {};
+    if (typeof engine.generateCrl !== "function") {
+      throw new MtlsCaError("mtls-ca/engine-no-crl",
+        "configured engine does not implement generateCrl(); the bundled " +
+        "engine ships in v0.6.45+");
+    }
+    var ca = await initCA();
+    var revocations = _loadRevocations().revocations;
+    var nowMs = Date.now();
+    var thisUpdate = opts3.thisUpdate || new Date(nowMs);
+    var nextUpdate = opts3.nextUpdate ||
+                     new Date(nowMs + 7 * 24 * 60 * 60 * 1000);   // 7d default
+    var crlPem = await engine.generateCrl({
+      caCertPem:   ca.caCertPem,
+      caKeyPem:    ca.caKeyPem,
+      revocations: revocations,
+      thisUpdate:  thisUpdate,
+      nextUpdate:  nextUpdate,
+    });
+    if (typeof crlPem !== "string" || crlPem.length === 0) {
+      throw new MtlsCaError("mtls-ca/bad-engine-output",
+        "engine.generateCrl must return a non-empty PEM string");
+    }
+    if (opts3.persist !== false) {
+      var atomicFile = require("./atomic-file");
+      atomicFile.writeSync(paths.crl, crlPem, { mode: 0o644 });
+    }
+    return { crlPem: crlPem, thisUpdate: thisUpdate, nextUpdate: nextUpdate,
+             entryCount: revocations.length, path: paths.crl };
+  }
+
   return {
     exists:               exists,
     keyExists:            keyExists,
@@ -328,6 +479,10 @@ function create(opts) {
     initCA:               initCA,
     generateClientCert:   generateClientCert,
     generateClientP12:    generateClientP12,
+    revoke:               revoke,
+    isRevoked:            isRevoked,
+    getRevocations:       getRevocations,
+    generateCrl:          generateCrl,
     paths:                paths,
     generation:           generation,
     caKeySealedMode:      caKeySealedMode,