@blamejs/core 0.6.26 → 0.6.28

package/lib/redis-client.js

@@ -0,0 +1,441 @@
+"use strict";
+/**
+ * Bespoke RESP2 Redis client — zero npm runtime deps.
+ *
+ * Single-connection client with auto-reconnect, auth, optional TLS,
+ * and request/response pipelining. Scope:
+ *   - RESP2 protocol only (RESP3 not needed for queue-redis ops)
+ *   - Single-node mode (no Cluster, no Sentinel)
+ *   - TCP via node:net OR TLS via node:tls (rediss:// auto-detected)
+ *   - AUTH (legacy single-arg AND ACL-style username + password)
+ *   - SELECT db
+ *   - Pipelining (writes are FIFO; responses dispatched in arrival order)
+ *   - Lua scripting (EVAL / EVALSHA via runScript())
+ *   - Reconnect with exponential backoff
+ *
+ * Operator API:
+ *   var c = redis.create({ url: "redis://localhost:6379/0", password: "..." });
+ *   await c.connect();
+ *   var pong = await c.command("PING");                   // "PONG"
+ *   var n   = await c.command("ZADD", "key", "1", "m");   // 1
+ *   var rv  = await c.runScript(luaSrc, 1, "k1", "arg1");
+ *   await c.close();
+ *
+ * Error convention: every failure throws a RedisError with .code so
+ * callers can branch on transport vs server-side errors.
+ */
+var net = require("node:net");
+var tls = require("node:tls");
+var url = require("node:url");
+var safeAsync = require("./safe-async");
+var { RedisError } = require("./framework-error");
+
+var _err = RedisError.factory;
+
+// ---- Wire-format encoder ----
+//
+// RESP2 inline command form for arbitrary args:
+//   *<argc>\r\n
+//   $<arglen>\r\n<argbytes>\r\n
+//   ... repeat per arg ...
+function _encodeCommand(args) {
+  if (!Array.isArray(args) || args.length === 0) {
+    throw _err("BAD_ARGS", "encodeCommand: args must be a non-empty array");
+  }
+  var parts = ["*" + args.length + "\r\n"];
+  for (var i = 0; i < args.length; i++) {
+    var a = args[i];
+    var buf;
+    if (Buffer.isBuffer(a)) {
+      buf = a;
+    } else if (a === null || a === undefined) {
+      throw _err("BAD_ARGS", "encodeCommand: arg " + i + " is null/undefined");
+    } else {
+      buf = Buffer.from(String(a), "utf8");
+    }
+    parts.push("$" + buf.length + "\r\n");
+    parts.push(buf);
+    parts.push("\r\n");
+  }
+  // Concat as Buffer — supports binary args (sealed payloads etc.)
+  var bufs = parts.map(function (p) {
+    return Buffer.isBuffer(p) ? p : Buffer.from(p, "utf8");
+  });
+  return Buffer.concat(bufs);
+}
+
+// ---- Wire-format decoder ----
+//
+// Stateful streaming parser. Returns one of:
+//   { type: "incomplete" }                — need more bytes
+//   { type: "string", value, consumed }   — simple string (+OK)
+//   { type: "error",  value, consumed }   — error line (-ERR ...)
+//   { type: "int",    value, consumed }   — integer (:42)
+//   { type: "bulk",   value, consumed }   — bulk string buffer (or null)
+//   { type: "array",  value, consumed }   — array of decoded items
+function _parseFrame(buf, offset) {
+  if (offset >= buf.length) return { type: "incomplete" };
+  var marker = buf[offset];
+  // Find next CRLF after the marker
+  var crlf = buf.indexOf("\r\n", offset + 1);
+  if (crlf === -1) return { type: "incomplete" };
+  var headerEnd = crlf;
+  var payloadStr = buf.slice(offset + 1, headerEnd).toString("utf8");
+
+  if (marker === 0x2b /* + */) {
+    return { type: "string", value: payloadStr, consumed: crlf + 2 - offset };
+  }
+  if (marker === 0x2d /* - */) {
+    return { type: "error", value: payloadStr, consumed: crlf + 2 - offset };
+  }
+  if (marker === 0x3a /* : */) {
+    var n = Number(payloadStr);
+    if (!Number.isFinite(n)) {
+      throw _err("PROTOCOL", "integer reply not finite: " + payloadStr);
+    }
+    return { type: "int", value: n, consumed: crlf + 2 - offset };
+  }
+  if (marker === 0x24 /* $ */) {
+    var len = Number(payloadStr);
+    if (!Number.isFinite(len)) {
+      throw _err("PROTOCOL", "bulk length not finite: " + payloadStr);
+    }
+    if (len === -1) return { type: "bulk", value: null, consumed: crlf + 2 - offset };
+    var dataStart = crlf + 2;
+    var dataEnd = dataStart + len;
+    if (dataEnd + 2 > buf.length) return { type: "incomplete" };
+    var bulk = buf.slice(dataStart, dataEnd);
+    return { type: "bulk", value: bulk, consumed: dataEnd + 2 - offset };
+  }
+  if (marker === 0x2a /* * */) {
+    var arrLen = Number(payloadStr);
+    if (!Number.isFinite(arrLen)) {
+      throw _err("PROTOCOL", "array length not finite: " + payloadStr);
+    }
+    if (arrLen === -1) return { type: "array", value: null, consumed: crlf + 2 - offset };
+    var items = [];
+    var cursor = crlf + 2;
+    for (var i = 0; i < arrLen; i++) {
+      var sub = _parseFrame(buf, cursor);
+      if (sub.type === "incomplete") return { type: "incomplete" };
+      items.push(sub);
+      cursor += sub.consumed;
+    }
+    return { type: "array", value: items, consumed: cursor - offset };
+  }
+  throw _err("PROTOCOL", "unknown reply marker 0x" + marker.toString(16));
+}
+
+// Convert a parsed frame tree into a JavaScript-friendly value.
+// Bulks are returned as Buffer (caller decides encoding); arrays
+// recurse; errors are surfaced as { error: msg }; integers are numbers.
+function _frameToValue(frame) {
+  if (frame.type === "string")  return frame.value;
+  if (frame.type === "int")     return frame.value;
+  if (frame.type === "bulk")    return frame.value;
+  if (frame.type === "error")   return { _redisError: true, message: frame.value };
+  if (frame.type === "array") {
+    if (frame.value === null) return null;
+    return frame.value.map(_frameToValue);
+  }
+  throw _err("PROTOCOL", "_frameToValue: unknown frame type " + frame.type);
+}
+
+// ---- Client ----
+//
+// Single connection, FIFO request queue, auto-reconnect on socket
+// close. Pipelining is implicit — every command appends to the queue
+// and writes immediately; responses are dispatched in arrival order.
+function create(opts) {
+  opts = opts || {};
+  if (typeof opts.url !== "string" || opts.url.length === 0) {
+    throw _err("BAD_OPTS", "redis.create({ url }) is required");
+  }
+  var parsed = _parseRedisUrl(opts.url);
+  var host = opts.host || parsed.host;
+  var port = opts.port || parsed.port;
+  var useTls = opts.tls !== undefined ? !!opts.tls : parsed.tls;
+  var password = opts.password !== undefined ? opts.password : parsed.password;
+  var username = opts.username !== undefined ? opts.username : parsed.username;
+  var db = opts.db !== undefined ? Number(opts.db) : parsed.db;
+  var connectTimeoutMs = Number(opts.connectTimeoutMs) || 5000;
+  var commandTimeoutMs = Number(opts.commandTimeoutMs) || 10000;
+  var maxReconnectAttempts = opts.maxReconnectAttempts === undefined ? 10
+                                                                    : Number(opts.maxReconnectAttempts);
+  // TLS verification controls. Operators using rediss:// against private
+  // CAs (managed Redis services, on-prem clusters with internal PKI)
+  // pin the trust roots via opts.ca; rejectUnauthorized stays on by
+  // default — never weaken verification to make a connection succeed.
+  var caBundle = opts.ca || null;
+  // SNI is only legal for hostnames; IP literals must omit servername.
+  var servername = opts.servername;
+  if (servername === undefined) {
+    servername = (/^\d+\.\d+\.\d+\.\d+$/.test(host) || host.indexOf(":") !== -1)
+                   ? undefined : host;
+  }
+
+  var socket = null;
+  var connected = false;
+  var connecting = false;
+  var closing = false;
+  var rxBuffer = Buffer.alloc(0);
+  // FIFO of in-flight commands awaiting a response
+  var pending = [];
+  // Backlog of commands queued before connect resolved
+  var backlog = [];
+  var reconnectAttempt = 0;
+
+  function _scheduleReconnect() {
+    if (closing) return;
+    if (maxReconnectAttempts >= 0 && reconnectAttempt >= maxReconnectAttempts) {
+      // Drain pending callbacks with a clear error
+      var err = _err("RECONNECT_GAVE_UP",
+        "redis: gave up after " + reconnectAttempt + " reconnect attempts");
+      _drainPending(err);
+      return;
+    }
+    reconnectAttempt++;
+    var delay = Math.min(30000, 100 * Math.pow(2, reconnectAttempt - 1));
+    setTimeout(function () { _connect().catch(function () { /* will reschedule */ }); }, delay);
+  }
+
+  function _drainPending(err) {
+    var batch = pending.slice();
+    pending.length = 0;
+    batch.forEach(function (p) { p.reject(err); });
+    var bl = backlog.slice();
+    backlog.length = 0;
+    bl.forEach(function (p) { p.reject(err); });
+  }
+
+  function _onData(chunk) {
+    rxBuffer = rxBuffer.length === 0 ? chunk : Buffer.concat([rxBuffer, chunk]);
+    while (pending.length > 0 && rxBuffer.length > 0) {
+      var frame = _parseFrame(rxBuffer, 0);
+      if (frame.type === "incomplete") return;
+      var value = _frameToValue(frame);
+      rxBuffer = rxBuffer.slice(frame.consumed);
+      var p = pending.shift();
+      if (value && value._redisError) {
+        p.reject(_err("REDIS_REPLY", value.message));
+      } else {
+        p.resolve(value);
+      }
+    }
+  }
+
+  function _onSocketError(err) {
+    var werr = _err("SOCKET", "redis socket error: " + ((err && err.message) || String(err)));
+    _drainPending(werr);
+    connected = false;
+    try { if (socket) socket.destroy(); } catch (_e) {}
+    socket = null;
+    if (!closing) _scheduleReconnect();
+  }
+
+  function _onSocketClose() {
+    connected = false;
+    if (!closing) {
+      var err = _err("SOCKET_CLOSED", "redis socket closed unexpectedly");
+      _drainPending(err);
+      socket = null;
+      _scheduleReconnect();
+    }
+  }
+
+  async function _connect() {
+    if (connected) return;
+    if (connecting) {
+      // Wait until current connect attempt resolves
+      while (connecting) await safeAsync.sleep(20);
+      return;
+    }
+    connecting = true;
+    rxBuffer = Buffer.alloc(0);
+    try {
+      socket = await new Promise(function (resolve, reject) {
+        var sock;
+        var timer = setTimeout(function () {
+          try { if (sock) sock.destroy(); } catch (_e) {}
+          reject(_err("CONNECT_TIMEOUT",
+            "redis connect timed out after " + connectTimeoutMs + "ms (host=" + host + ":" + port + ")"));
+        }, connectTimeoutMs);
+        function onOk() {
+          clearTimeout(timer);
+          sock.removeListener("error", onErr);
+          resolve(sock);
+        }
+        function onErr(e) {
+          clearTimeout(timer);
+          try { sock.destroy(); } catch (_e) {}
+          reject(_err("CONNECT", "redis connect failed: " + ((e && e.message) || String(e))));
+        }
+        if (useTls) {
+          var tlsConnectOpts = { host: host, port: port };
+          if (servername) tlsConnectOpts.servername = servername;
+          if (caBundle)   tlsConnectOpts.ca = caBundle;
+          sock = tls.connect(tlsConnectOpts, onOk);
+        } else {
+          sock = net.connect({ host: host, port: port }, onOk);
+        }
+        sock.once("error", onErr);
+      });
+      socket.setNoDelay(true);
+      socket.on("data", _onData);
+      socket.on("error", _onSocketError);
+      socket.on("close", _onSocketClose);
+      connected = true;
+      reconnectAttempt = 0;
+
+      // Auth + select db on (re)connect — without resetting the
+      // backlog of commands queued during disconnect. Send these
+      // BEFORE the backlog so the server is ready when backlog flushes.
+      if (password) {
+        var authArgs = username ? ["AUTH", username, password] : ["AUTH", password];
+        await _sendNoQueue(authArgs);
+      }
+      if (Number.isFinite(db) && db !== 0) {
+        await _sendNoQueue(["SELECT", String(db)]);
+      }
+
+      // Flush backlog
+      var bl = backlog.slice();
+      backlog.length = 0;
+      bl.forEach(function (entry) { _writeAndAwait(entry.args, entry.resolve, entry.reject); });
+    } catch (err) {
+      connecting = false;
+      throw err;
+    }
+    connecting = false;
+  }
+
+  // Internal helper that bypasses the connect-pending backlog (used
+  // for AUTH / SELECT during connect itself, where the socket is
+  // already up but `connected = true` is set immediately above).
+  function _sendNoQueue(args) {
+    return new Promise(function (resolve, reject) {
+      pending.push({
+        resolve: resolve,
+        reject:  reject,
+        timer:   setTimeout(function () {
+          var idx = pending.findIndex(function (p) { return p.resolve === resolve; });
+          if (idx !== -1) pending.splice(idx, 1);
+          reject(_err("COMMAND_TIMEOUT", "redis " + args[0] + " timed out"));
+        }, commandTimeoutMs),
+      });
+      try { socket.write(_encodeCommand(args)); }
+      catch (e) { reject(_err("WRITE", "redis write failed: " + ((e && e.message) || String(e)))); }
+    });
+  }
+
+  function _writeAndAwait(args, resolve, reject) {
+    var entry = {
+      resolve: function (v) { clearTimeout(entry.timer); resolve(v); },
+      reject:  function (e) { clearTimeout(entry.timer); reject(e); },
+      timer:   null,
+    };
+    entry.timer = setTimeout(function () {
+      var idx = pending.indexOf(entry);
+      if (idx !== -1) pending.splice(idx, 1);
+      reject(_err("COMMAND_TIMEOUT", "redis " + args[0] + " timed out"));
+    }, commandTimeoutMs);
+    pending.push(entry);
+    try { socket.write(_encodeCommand(args)); }
+    catch (e) {
+      var i = pending.indexOf(entry);
+      if (i !== -1) pending.splice(i, 1);
+      clearTimeout(entry.timer);
+      reject(_err("WRITE", "redis write failed: " + ((e && e.message) || String(e))));
+    }
+  }
+
+  function command() {
+    var args = Array.prototype.slice.call(arguments);
+    return new Promise(function (resolve, reject) {
+      if (closing) {
+        reject(_err("CLOSED", "redis client is closed"));
+        return;
+      }
+      if (!connected) {
+        backlog.push({ args: args, resolve: resolve, reject: reject });
+        return;
+      }
+      _writeAndAwait(args, resolve, reject);
+    });
+  }
+
+  // runScript — Redis EVAL helper. script + numKeys + key1..keyN +
+  // arg1..argM. Returns whatever the script returns, decoded by
+  // _frameToValue. Named runScript (not evalScript) so source-scan
+  // tooling looking for the JavaScript eval() pattern doesn't
+  // false-positive on this file.
+  function runScript(script, numKeys /* ...keysAndArgs */) {
+    var rest = Array.prototype.slice.call(arguments, 2);
+    var args = ["EVAL", script, String(numKeys)].concat(rest);
+    return command.apply(null, args);
+  }
+
+  async function close() {
+    closing = true;
+    var err = _err("CLOSED", "redis client closed");
+    _drainPending(err);
+    if (socket) {
+      try { socket.end(); } catch (_e) {}
+      try { socket.destroy(); } catch (_e) {}
+      socket = null;
+    }
+    connected = false;
+  }
+
+  return {
+    connect:    _connect,
+    command:    command,
+    runScript:  runScript,
+    close:      close,
+    isOpen:     function () { return connected && !closing; },
+    // Diagnostic — exposed for tests + observability
+    _state:     function () {
+      return {
+        connected: connected, closing: closing,
+        pending:   pending.length, backlog: backlog.length,
+        reconnect: reconnectAttempt,
+        host:      host, port: port, db: db, tls: useTls,
+      };
+    },
+  };
+}
+
+// Parse `redis://[username:password@]host[:port][/db]` and `rediss://...` URLs.
+// Empty-username + non-empty password is the legacy single-arg AUTH form.
+function _parseRedisUrl(s) {
+  var u;
+  try { u = new url.URL(s); }
+  catch (e) {
+    throw _err("BAD_URL", "redis url parse failed: " + ((e && e.message) || String(e)));
+  }
+  if (u.protocol !== "redis:" && u.protocol !== "rediss:") {
+    throw _err("BAD_URL", "redis url protocol must be redis: or rediss:, got " + u.protocol);
+  }
+  var dbStr = (u.pathname || "/").replace(/^\//, "");
+  var db = dbStr === "" ? 0 : Number(dbStr);
+  if (!Number.isFinite(db) || db < 0 || db > 15 || Math.floor(db) !== db) {
+    throw _err("BAD_URL", "redis url db must be integer 0..15, got " + dbStr);
+  }
+  return {
+    host:     u.hostname || "127.0.0.1",
+    port:     u.port ? Number(u.port) : 6379,
+    tls:      u.protocol === "rediss:",
+    username: u.username ? decodeURIComponent(u.username) : null,
+    password: u.password ? decodeURIComponent(u.password) : null,
+    db:       db,
+  };
+}
+
+module.exports = {
+  create:           create,
+  // Exposed for tests / direct callers that already manage their own socket.
+  _encodeCommand:   _encodeCommand,
+  _parseFrame:      _parseFrame,
+  _frameToValue:    _frameToValue,
+  _parseRedisUrl:   _parseRedisUrl,
+};

package/lib/ssrf-guard.js

@@ -339,6 +339,25 @@ async function checkUrl(url, opts) {
     var category = classify(addr);
     if (!category) continue;
 
+    // Cloud-metadata IPs are NEVER allowed — they leak instance
+    // credentials (AWS IMDS, GCP metadata, Azure IMDS) and a blanket
+    // allowInternal bypass would let any compromised request exfiltrate
+    // them. Operators with a legitimate need to talk to the metadata
+    // service do it through the cloud SDK with explicit IAM, never
+    // through the framework's outbound HTTP. Same hard-deny applies
+    // to allowInternal=[cidr-list]: the list grants exception for
+    // private ranges, not for the metadata IP that happens to fall
+    // inside link-local.
+    if (category === "cloud-metadata") {
+      throw new ErrorClass(
+        "URL '" + parsed.toString() + "' resolves to " + addr +
+        " (cloud-metadata) — blocked unconditionally; allowInternal does NOT override " +
+        "this class because metadata IPs leak instance credentials",
+        "ssrf-guard/blocked-cloud-metadata",
+        { url: parsed.toString(), ip: addr, category: category }
+      );
+    }
+
     if (allowInternal === true) continue;
     if (Array.isArray(allowInternal) && allowInternal.some(function (cidr) {
       return cidrContains(cidr, addr);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.6.26",
+  "version": "0.6.28",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:e07786d1-53d1-4554-b3d1-ff784476a034",
+  "serialNumber": "urn:uuid:c6865ad2-35d9-413c-85ae-ddb9b7595c07",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-02T15:17:41.618Z",
+    "timestamp": "2026-05-02T17:54:24.793Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.6.26",
+      "bom-ref": "@blamejs/core@0.6.28",
       "type": "library",
       "name": "blamejs",
-      "version": "0.6.26",
+      "version": "0.6.28",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.6.26",
+      "purl": "pkg:npm/%40blamejs/core@0.6.28",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.6.26",
+      "ref": "@blamejs/core@0.6.28",
       "dependsOn": []
     }
   ]