@blamejs/core 0.4.1

package/lib/pqc-gate.js

@@ -0,0 +1,266 @@
+"use strict";
+/**
+ * pqc-gate — TCP-level enforcement of post-quantum key exchange.
+ *
+ * Inspects the TLS ClientHello before letting the connection reach the
+ * HTTPS server. Connections that don't offer a PQC hybrid group in
+ * supported_groups are rejected with a TLS handshake_failure alert.
+ *
+ * Architecture:
+ *
+ *   net.Server (public 443) → parse ClientHello → pipe to internal HTTPS server
+ *
+ * The HTTPS server binds to a private loopback port and never directly
+ * sees the internet. Operators set Node's TLS group preference at the
+ * HTTPS server level (so accepted connections still negotiate PQC) and
+ * use this gate as the outermost rejection point. Both layers must be
+ * configured PQC-only — gate without HTTPS-side enforcement leaves a
+ * connection that downgrades to a non-PQ group at handshake time.
+ *
+ *   var server = b.pqcGate.create({
+ *     internalPort: 8443,
+ *     internalHost: "127.0.0.1",
+ *     bypass:       ["127.0.0.1", "::1", "::ffff:127.0.0.1"],
+ *     clientHelloTimeoutMs: 5000,
+ *     maxClientHelloBytes:  16384,
+ *     log:          logInstance,
+ *   });
+ *   server.listen(443, "0.0.0.0");
+ *
+ * Bypass: localhost connections skip the gate so health probes and
+ * sidecars (which often do plain TCP or use older TLS configurations)
+ * still work without weakening the public-facing posture.
+ *
+ * Test seam: opts._connect / _server / _setTimeout / _clearTimeout
+ * default to net.createConnection / net.createServer / setTimeout /
+ * clearTimeout. The unit tests use fakes to drive the parser and
+ * connection lifecycle deterministically.
+ */
+var net = require("node:net");
+var { PQC_GROUPS } = require("./constants");
+var validateOpts = require("./validate-opts");
+var { boot } = require("./log");
+
+var DEFAULT_LOG = boot("pqc-gate");
+var DEFAULT_BYPASS = Object.freeze(["127.0.0.1", "::1", "::ffff:127.0.0.1"]);
+var DEFAULT_CLIENTHELLO_TIMEOUT_MS = 5000;
+var DEFAULT_MAX_CLIENTHELLO_BYTES = 16384;
+
+// TLS handshake_failure alert (fatal). Sent before destroying a socket
+// so a strict TLS client logs a precise reason rather than a vague
+// connection-reset.
+var TLS_ALERT_HANDSHAKE_FAILURE = Buffer.from([0x15, 0x03, 0x03, 0x00, 0x02, 0x02, 0x28]);
+
+// Set built once from the framework's PQC_GROUPS constant. New PQC
+// groups added there flow into the gate without code changes.
+var PQC_GROUP_IDS = new Set(Object.values(PQC_GROUPS));
+
+// clientHelloHasPQC — return true iff the parsed ClientHello buffer
+// includes any group listed in PQC_GROUP_IDS in its supported_groups
+// extension. Returns false on malformed input or when no PQC group is
+// present.
+function clientHelloHasPQC(buf) {
+  if (!buf || buf.length < 44) return false;
+
+  // TLS record header: type(1) version(2) length(2)
+  if (buf[0] !== 0x16) return false; // not a handshake record
+
+  var recordLen = buf.readUInt16BE(3);
+  var recordEnd = Math.min(5 + recordLen, buf.length);
+
+  // Handshake header: type(1) length(3)
+  if (buf.length < 10) return false;
+  if (buf[5] !== 0x01) return false; // not ClientHello
+
+  // Body: version(2) + random(32) = 34 bytes after handshake header
+  var offset = 9 + 2 + 32;
+  if (offset + 1 > recordEnd) return false;
+
+  // Session ID: length(1) + data
+  var sessionIdLen = buf[offset];
+  offset += 1 + sessionIdLen;
+  if (offset + 2 > recordEnd) return false;
+
+  // Cipher suites: length(2) + data
+  var cipherSuitesLen = buf.readUInt16BE(offset);
+  offset += 2 + cipherSuitesLen;
+  if (offset + 1 > recordEnd) return false;
+
+  // Compression methods: length(1) + data
+  var compLen = buf[offset];
+  offset += 1 + compLen;
+  if (offset + 2 > recordEnd) return false;
+
+  // Extensions: total_length(2)
+  var extensionsLen = buf.readUInt16BE(offset);
+  offset += 2;
+  var extensionsEnd = Math.min(offset + extensionsLen, recordEnd);
+
+  while (offset + 4 <= extensionsEnd) {
+    var extType = buf.readUInt16BE(offset);
+    var extLen  = buf.readUInt16BE(offset + 2);
+    offset += 4;
+
+    if (extType === 0x000A && extLen >= 2 && offset + extLen <= extensionsEnd) {
+      // supported_groups: list_length(2) + group_ids(2 each)
+      var listLen = buf.readUInt16BE(offset);
+      var groupsOffset = offset + 2;
+      var groupsEnd = Math.min(groupsOffset + listLen, offset + extLen);
+      while (groupsOffset + 2 <= groupsEnd) {
+        var groupId = buf.readUInt16BE(groupsOffset);
+        if (PQC_GROUP_IDS.has(groupId)) return true;
+        groupsOffset += 2;
+      }
+      return false;
+    }
+    offset += extLen;
+  }
+  return false;
+}
+
+function _isBypassed(remoteAddr, bypass) {
+  if (!remoteAddr) return false;
+  for (var i = 0; i < bypass.length; i++) {
+    if (bypass[i] === remoteAddr) return true;
+  }
+  return false;
+}
+
+function _logVia(log, level, msg, fields) {
+  if (log && typeof log[level] === "function") {
+    try { log[level](msg, fields); } catch (_e) { /* logger best-effort */ }
+    return;
+  }
+  // Fallback to the framework's per-module console channel
+  var line = msg + (fields ? " " + JSON.stringify(fields) : "");
+  if (level === "error" || level === "fatal" || level === "warn") {
+    DEFAULT_LOG.warn(line);
+  } else {
+    DEFAULT_LOG(line);
+  }
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "internalPort", "internalHost", "bypass",
+    "clientHelloTimeoutMs", "maxClientHelloBytes", "log",
+    "_connect", "_server", "_setTimeout", "_clearTimeout",
+  ], "b.pqcGate");
+  var internalPort = opts.internalPort;
+  if (typeof internalPort !== "number" || internalPort < 1 || internalPort > 65535) {
+    throw new Error("pqc-gate: opts.internalPort must be a port number (1-65535)");
+  }
+  var internalHost = typeof opts.internalHost === "string" ? opts.internalHost : "127.0.0.1";
+  var bypass       = Array.isArray(opts.bypass) ? opts.bypass.slice() : DEFAULT_BYPASS.slice();
+  var clientHelloTimeoutMs = typeof opts.clientHelloTimeoutMs === "number" && opts.clientHelloTimeoutMs > 0
+    ? opts.clientHelloTimeoutMs : DEFAULT_CLIENTHELLO_TIMEOUT_MS;
+  var maxClientHelloBytes  = typeof opts.maxClientHelloBytes === "number" && opts.maxClientHelloBytes > 0
+    ? opts.maxClientHelloBytes : DEFAULT_MAX_CLIENTHELLO_BYTES;
+  var log = opts.log || null;
+
+  // Test seams
+  var connectFn = opts._connect || function (cOpts, cb) { return net.createConnection(cOpts, cb); };
+  var serverFn  = opts._server  || function (sOpts, cb) { return net.createServer(sOpts, cb); };
+  var setTimeoutFn  = opts._setTimeout  || setTimeout;
+  var clearTimeoutFn = opts._clearTimeout || clearTimeout;
+
+  function pipeToInternal(socket, prependData) {
+    var internal = connectFn({ port: internalPort, host: internalHost }, function () {
+      if (prependData) internal.write(prependData);
+      socket.pipe(internal);
+      internal.pipe(socket);
+      socket.resume();
+    });
+    internal.on("error", function () { socket.destroy(); });
+    socket.on("error",   function () { internal.destroy(); });
+    internal.on("close", function () { socket.destroy(); });
+    socket.on("close",   function () { internal.destroy(); });
+  }
+
+  function _onConnection(socket) {
+    var clientIp = socket.remoteAddress || "";
+
+    if (_isBypassed(clientIp, bypass)) {
+      pipeToInternal(socket);
+      return;
+    }
+
+    var chunks = [];
+    var totalLen = 0;
+    var resolved = false;
+
+    var timeout = setTimeoutFn(function () {
+      if (resolved) return;
+      resolved = true;
+      _logVia(log, "warn", "ClientHello timeout", { ip: clientIp });
+      try { socket.destroy(); } catch (_e) { /* socket may already be torn down */ }
+    }, clientHelloTimeoutMs);
+
+    socket.on("data", function onData(chunk) {
+      if (resolved) return;
+      chunks.push(chunk);
+      totalLen += chunk.length;
+
+      if (totalLen > maxClientHelloBytes) {
+        resolved = true;
+        try { clearTimeoutFn(timeout); } catch (_e) {}
+        _logVia(log, "warn", "ClientHello too large", { ip: clientIp, size: totalLen });
+        try { socket.destroy(); } catch (_e) {}
+        return;
+      }
+
+      // Reject non-handshake first byte immediately
+      if (totalLen >= 1 && chunks[0][0] !== 0x16) {
+        resolved = true;
+        try { clearTimeoutFn(timeout); } catch (_e) {}
+        try { socket.destroy(); } catch (_e) {}
+        return;
+      }
+
+      if (totalLen < 5) return; // need at least the record header
+
+      var buf = Buffer.concat(chunks);
+      var recordLen = buf.readUInt16BE(3);
+      var neededLen = 5 + recordLen;
+
+      if (buf.length < Math.min(neededLen, maxClientHelloBytes)) return;
+
+      resolved = true;
+      try { clearTimeoutFn(timeout); } catch (_e) {}
+      socket.removeListener("data", onData);
+      socket.pause();
+
+      if (clientHelloHasPQC(buf)) {
+        pipeToInternal(socket, buf);
+      } else {
+        _logVia(log, "warn",
+          "connection rejected — no PQC group in ClientHello", { ip: clientIp });
+        try {
+          socket.write(TLS_ALERT_HANDSHAKE_FAILURE, function () {
+            try { socket.destroy(); } catch (_e) {}
+          });
+        } catch (_e) {
+          try { socket.destroy(); } catch (_e2) {}
+        }
+      }
+    });
+
+    socket.on("error", function () {
+      resolved = true;
+      try { clearTimeoutFn(timeout); } catch (_e) {}
+    });
+
+    socket.resume();
+  }
+
+  return serverFn({ pauseOnConnect: true }, _onConnection);
+}
+
+module.exports = {
+  create:                       create,
+  clientHelloHasPQC:            clientHelloHasPQC,
+  PQC_GROUP_IDS:                PQC_GROUP_IDS,
+  TLS_ALERT_HANDSHAKE_FAILURE:  TLS_ALERT_HANDSHAKE_FAILURE,
+  DEFAULT_BYPASS:               DEFAULT_BYPASS,
+};

package/lib/protocol-dispatcher.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * protocol-dispatcher — pluggable protocol resolver with deferred-protocol
+ * surfacing.
+ *
+ * Three framework modules ship a "pick a backend by protocol name" surface:
+ *   - lib/queue.js                 (local, deferred: redis/sqs/amqp/nats)
+ *   - lib/log-stream.js            (local + webhook, deferred: syslog/otlp/cloudwatch)
+ *   - lib/object-store/index.js    (local + http-put + sigv4 + gcs + azure-blob)
+ *
+ * Each previously copied a ~30-line dispatch block: validate config has a
+ * protocol, look up DEFERRED_PROTOCOLS for a clear "not yet implemented"
+ * error, look up PROTOCOLS for the real implementation, throw on unknown.
+ * This primitive owns that lookup + error shape so callers focus on
+ * post-resolve logic (retry+breaker wrapping, classification, etc.).
+ *
+ * Public API:
+ *
+ *   var dispatcher = protocolDispatcher.create({
+ *     name:             "queue",                // appears in error messages
+ *     errorClass:       QueueError,             // thrown on unknown/deferred/missing
+ *     protocols:        { local: localProto },  // protocol-name → module
+ *     deferred:         { redis: { description: "Redis Streams" } },
+ *     fallbackProtocol: "local",                // hinted in deferred-error
+ *   });
+ *
+ *   var proto = dispatcher.resolve(cfg.protocol);
+ *   //   throws errorClass when:
+ *   //     - cfg.protocol is undefined / empty                  → MISSING_PROTOCOL
+ *   //     - cfg.protocol matches a deferred-protocol entry      → PROTOCOL_NOT_IMPLEMENTED
+ *   //     - cfg.protocol is neither implemented nor deferred    → UNKNOWN_PROTOCOL
+ *   //   returns the protocol module (caller invokes proto.create(cfg) etc.)
+ *
+ *   dispatcher.protocols  // → ["local"]
+ *   dispatcher.deferred   // → ["redis"]
+ *
+ * Why resolve-only (not build): the post-resolve flow differs per module
+ * (retry+breaker for queue+object-store, batched dispatch for log-stream,
+ * classification routing for object-store). A one-size-fits-all builder
+ * would either miss those concerns or expose them as a sprawling opts
+ * surface. Resolve-only keeps the primitive small and the post-resolve
+ * code where it belongs.
+ *
+ * Error surface: every throw carries the dispatcher's `name` so an
+ * operator with multiple dispatchers (queue + log-stream) reading the
+ * error message knows which one rejected the protocol.
+ */
+var { defineClass } = require("./framework-error");
+
+// Default error class — operators / test fixtures that don't want to
+// supply their own get this generic shape with the same code namespace.
+var ProtocolDispatcherError = defineClass("ProtocolDispatcherError", { withStatusCode: true });
+
+// Tier A validation — called at create-time, throw on bad input so
+// operators catch typos at app boot, not first request.
+function _validateConfig(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new Error("protocolDispatcher.create: opts is required");
+  }
+  if (typeof opts.name !== "string" || opts.name.length === 0) {
+    throw new Error("protocolDispatcher.create: opts.name (string) is required");
+  }
+  if (!opts.protocols || typeof opts.protocols !== "object" || Array.isArray(opts.protocols)) {
+    throw new Error("protocolDispatcher.create: opts.protocols (object) is required");
+  }
+  // Each protocol value should look like a module with .create — operators
+  // wiring a typo'd reference get a clearer error than "undefined is not
+  // a function" when resolve() hits it.
+  var pkeys = Object.keys(opts.protocols);
+  for (var i = 0; i < pkeys.length; i++) {
+    var p = opts.protocols[pkeys[i]];
+    if (!p || typeof p !== "object" || typeof p.create !== "function") {
+      throw new Error("protocolDispatcher.create: opts.protocols['" + pkeys[i] +
+        "'] must be an object with a .create function (got " +
+        (p === null ? "null" : typeof p) + ")");
+    }
+  }
+  if (opts.deferred !== undefined && opts.deferred !== null) {
+    if (typeof opts.deferred !== "object" || Array.isArray(opts.deferred)) {
+      throw new Error("protocolDispatcher.create: opts.deferred must be an object (or omitted)");
+    }
+  }
+  if (opts.fallbackProtocol !== undefined && opts.fallbackProtocol !== null) {
+    if (typeof opts.fallbackProtocol !== "string" || opts.fallbackProtocol.length === 0) {
+      throw new Error("protocolDispatcher.create: opts.fallbackProtocol must be a non-empty string (or omitted)");
+    }
+  }
+  if (opts.errorClass !== undefined && opts.errorClass !== null) {
+    if (typeof opts.errorClass !== "function") {
+      throw new Error("protocolDispatcher.create: opts.errorClass must be a constructor (or omitted)");
+    }
+  }
+}
+
+function create(opts) {
+  _validateConfig(opts);
+  var name             = opts.name;
+  var protocols        = Object.assign({}, opts.protocols);
+  var deferred         = Object.assign({}, opts.deferred || {});
+  var fallbackProtocol = opts.fallbackProtocol || null;
+  var ErrorClass       = opts.errorClass || ProtocolDispatcherError;
+
+  function _err(code, message) {
+    // ErrorClass is expected to be a defineClass-built class with
+    // (code, message, permanent[, statusCode]) signature. Pass
+    // permanent=true since protocol mismatches are config errors, not
+    // transient failures.
+    return new ErrorClass(code, message, true);
+  }
+
+  function resolve(protocol) {
+    if (typeof protocol !== "string" || protocol.length === 0) {
+      throw _err("MISSING_PROTOCOL",
+        name + " backend requires { protocol }");
+    }
+    if (Object.prototype.hasOwnProperty.call(deferred, protocol)) {
+      var d = deferred[protocol];
+      var msg = name + " protocol '" + protocol + "' is not yet implemented";
+      if (d && d.description) msg += " (" + d.description + ")";
+      if (d && d.since)       msg += "; deferred to " + d.since;
+      if (fallbackProtocol)   msg += ". Use protocol: '" + fallbackProtocol + "' for now.";
+      throw _err("PROTOCOL_NOT_IMPLEMENTED", msg);
+    }
+    if (!Object.prototype.hasOwnProperty.call(protocols, protocol)) {
+      var known = Object.keys(protocols).sort().join(", ");
+      throw _err("UNKNOWN_PROTOCOL",
+        "unknown " + name + " protocol: '" + protocol +
+        "' (known: " + (known || "[none]") + ")");
+    }
+    return protocols[protocol];
+  }
+
+  return {
+    name:      name,
+    resolve:   resolve,
+    protocols: Object.keys(protocols).sort(),
+    deferred:  Object.keys(deferred).sort(),
+  };
+}
+
+module.exports = {
+  create:                    create,
+  ProtocolDispatcherError:   ProtocolDispatcherError,
+};