@blamejs/core 0.4.1

package/lib/safe-sql.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * SQL safety primitive — identifier validation and parameterized query
+ * helpers.
+ *
+ * The framework's own SQL is parameterized everywhere — values bind
+ * through node:sqlite or external-db drivers, never string-concatenated.
+ * That covers value injection. The remaining attack surface is
+ * IDENTIFIER injection: when a TABLE name or COLUMN name is interpolated
+ * into a SQL string, a malicious or misconfigured caller can break out
+ * of the intended structure. This is rare in framework-internal code
+ * (we control the names) but easy to get wrong if operator-supplied
+ * config flows in unchecked.
+ *
+ * This module provides the thin validator that any code interpolating
+ * identifiers should call first. It does NOT execute SQL; it just
+ * validates the inputs that get composed into SQL elsewhere.
+ *
+ * Public API:
+ *   safeSql.validateIdentifier(name, opts?)        throws on bad shape
+ *   safeSql.quoteIdentifier(name, dialect?)        returns "name" / `name`
+ *   safeSql.assertOneOf(name, allowlist)           throws unless in list
+ *   safeSql.SafeSqlError                           error class
+ *
+ * Identifier rule (default): `^[A-Za-z_][A-Za-z0-9_]*$` with length
+ *   1–63 chars (Postgres NAMEDATALEN default; SQLite has no hard
+ *   limit but matching the strictest dialect is the safe bound).
+ *
+ * Forbidden in identifiers regardless of regex:
+ *   - SQL reserved words (a small allowlist, not exhaustive — operators
+ *     who need reserved-word identifiers should quote them and accept
+ *     the dialect-specific quoting)
+ *   - Leading underscore prefixed `sqlite_` (SQLite-internal)
+ *   - Embedded null byte
+ *
+ * Quoting:
+ *   sqlite     "name"      (double-quote per SQL standard; SQLite
+ *                          accepts double quotes for identifiers
+ *                          per its quirks settings)
+ *   postgres   "name"
+ *   mysql      `name`      (MySQL's backtick convention)
+ *
+ * Allowlist usage (recommended):
+ *   var ALLOWED_TABLES = new Set(["audit_log", "consent_log", …]);
+ *   safeSql.assertOneOf(operatorTableName, ALLOWED_TABLES);
+ *   var sql = "INSERT INTO " + safeSql.quoteIdentifier(operatorTableName) + " …";
+ *
+ *   The allowlist is the strongest guarantee. Operators with dynamic
+ *   identifier needs (rare) use validateIdentifier alone, accepting
+ *   that any string passing the regex is allowed.
+ */
+
+// Reserved-word block list — the most dangerous to accept as a bare
+// identifier. Not exhaustive; the allowlist pattern below is preferred.
+var BANNED_IDENTIFIERS = new Set([
+  "select", "insert", "update", "delete", "drop", "create", "alter",
+  "truncate", "grant", "revoke", "union", "exec", "execute",
+  "where", "from", "join", "into", "values", "table", "database",
+  "schema", "index", "view", "trigger", "procedure", "function",
+  "begin", "commit", "rollback", "savepoint",
+]);
+
+// Default identifier shape — Postgres NAMEDATALEN (63 chars) is the
+// strictest of the dialects we support, so use it as the bound.
+var DEFAULT_IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var MAX_IDENTIFIER_LENGTH = 63;
+
+var { FrameworkError } = require("./framework-error");
+
+class SafeSqlError extends FrameworkError {
+  constructor(message, code) {
+    super(message);
+    this.name = "SafeSqlError";
+    this.code = code || "sql/invalid";
+    this.isSafeSqlError = true;
+  }
+}
+
+function validateIdentifier(name, opts) {
+  opts = opts || {};
+  if (typeof name !== "string") {
+    throw new SafeSqlError("identifier must be a string (got " + typeof name + ")",
+      "sql/bad-type");
+  }
+  if (name.length === 0) {
+    throw new SafeSqlError("identifier must not be empty", "sql/empty");
+  }
+  if (name.length > MAX_IDENTIFIER_LENGTH) {
+    throw new SafeSqlError(
+      "identifier '" + name + "' exceeds maxLength " + MAX_IDENTIFIER_LENGTH,
+      "sql/too-long"
+    );
+  }
+  if (name.indexOf("\0") >= 0) {
+    throw new SafeSqlError("identifier contains null byte", "sql/null-byte");
+  }
+  var pattern = opts.pattern || DEFAULT_IDENTIFIER_RE;
+  if (!pattern.test(name)) {
+    throw new SafeSqlError(
+      "identifier '" + name + "' does not match required pattern " + pattern,
+      "sql/bad-shape"
+    );
+  }
+  if (!opts.allowReserved && BANNED_IDENTIFIERS.has(name.toLowerCase())) {
+    throw new SafeSqlError(
+      "identifier '" + name + "' is a SQL reserved word",
+      "sql/reserved-word"
+    );
+  }
+  if (!opts.allowSqliteInternal && /^sqlite_/i.test(name)) {
+    throw new SafeSqlError(
+      "identifier '" + name + "' uses the SQLite-internal 'sqlite_' prefix",
+      "sql/internal-prefix"
+    );
+  }
+  return name;
+}
+
+function quoteIdentifier(name, dialect) {
+  validateIdentifier(name);
+  dialect = (dialect || "sqlite").toLowerCase();
+  if (dialect === "mysql") return "`" + name + "`";
+  // sqlite + postgres both use double-quote per SQL standard
+  return '"' + name + '"';
+}
+
+function assertOneOf(name, allowlist) {
+  if (typeof name !== "string") {
+    throw new SafeSqlError("name must be a string", "sql/bad-type");
+  }
+  // Accept either Set or array
+  var ok = false;
+  if (allowlist && typeof allowlist.has === "function") {
+    ok = allowlist.has(name);
+  } else if (Array.isArray(allowlist)) {
+    ok = allowlist.indexOf(name) !== -1;
+  } else {
+    throw new SafeSqlError("allowlist must be a Set or array", "sql/bad-allowlist");
+  }
+  if (!ok) {
+    throw new SafeSqlError(
+      "identifier '" + name + "' not in allowlist",
+      "sql/not-allowed"
+    );
+  }
+  return name;
+}
+
+module.exports = {
+  validateIdentifier:  validateIdentifier,
+  quoteIdentifier:     quoteIdentifier,
+  assertOneOf:         assertOneOf,
+  SafeSqlError:        SafeSqlError,
+  // Exposed so consumers can compose their own validators
+  DEFAULT_IDENTIFIER_RE: DEFAULT_IDENTIFIER_RE,
+  MAX_IDENTIFIER_LENGTH: MAX_IDENTIFIER_LENGTH,
+};

package/lib/safe-url.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * URL-safe — validate URL scheme + shape against an allowlist.
+ *
+ * Per the framework's modernity stance: outbound network calls
+ * REQUIRE TLS by default. Operators with internal cleartext
+ * endpoints (development, behind-VPN services, internal mesh) opt in
+ * explicitly via opts.allowedProtocols. The framework refuses to
+ * silently drop bytes on the wire as cleartext.
+ *
+ * Public API:
+ *
+ *   safeUrl.parse(url, opts?) → URL
+ *     Returns a parsed URL object. Throws if the URL is malformed
+ *     or its protocol is not in the allowlist.
+ *
+ *   opts:
+ *     allowedProtocols  — array of accepted protocol strings
+ *                         (e.g. ["https:"] or safeUrl.ALLOW_HTTP_TLS).
+ *                         Default: ALLOW_HTTP_TLS.
+ *     errorClass        — FrameworkError subclass for the thrown
+ *                         error. Lets callers (object-store,
+ *                         log-stream, http-client) surface their
+ *                         own decorated error class. Default:
+ *                         SafeUrlError.
+ *
+ * Constants — pre-baked allowlists for the common caller cases:
+ *
+ *   ALLOW_HTTP_TLS   ["https:"]                       (the secure HTTP default)
+ *   ALLOW_HTTP_ALL   ["http:", "https:"]              (HTTP + cleartext opt-in)
+ *   ALLOW_WS_TLS     ["wss:"]                         (the secure WS default)
+ *   ALLOW_WS_ALL     ["ws:", "wss:"]                  (WS + cleartext opt-in)
+ *   ALLOW_ANY        ["http:", "https:", "ws:", "wss:"]
+ *
+ * Why per-call constants instead of one global "secure" list:
+ *   The http-client only speaks HTTP, so wss:// is a category error
+ *   (operator passed a WebSocket URL to a non-WebSocket client). Each
+ *   caller declares its own narrow allowlist; an off-protocol URL
+ *   fails with a clear "protocol not allowed here" error rather than
+ *   trying and failing weirdly later.
+ */
+
+var { FrameworkError } = require("./framework-error");
+var { URL } = require("url");
+
+var ALLOW_HTTP_TLS = Object.freeze(["https:"]);
+var ALLOW_HTTP_ALL = Object.freeze(["http:", "https:"]);
+var ALLOW_WS_TLS   = Object.freeze(["wss:"]);
+var ALLOW_WS_ALL   = Object.freeze(["ws:", "wss:"]);
+var ALLOW_ANY      = Object.freeze(["http:", "https:", "ws:", "wss:"]);
+
+class SafeUrlError extends FrameworkError {
+  constructor(code, message) {
+    super(message, code);
+    this.name = "SafeUrlError";
+    this.isSafeUrlError = true;
+  }
+}
+
+function _makeError(errorClass, code, message) {
+  if (!errorClass || errorClass === SafeUrlError) {
+    return new SafeUrlError(code, message);
+  }
+  // Convention for operational classes (ObjectStoreError,
+  // LogStreamError, etc.): (code, message, permanent[, statusCode]).
+  // A protocol-violation URL is "permanent" — retry won't help.
+  return new errorClass(code, message, true);
+}
+
+function parse(url, opts) {
+  opts = opts || {};
+  var allowed = Array.isArray(opts.allowedProtocols) && opts.allowedProtocols.length > 0
+    ? opts.allowedProtocols
+    : ALLOW_HTTP_TLS;
+  var errClass = opts.errorClass;
+
+  if (url == null || url === "") {
+    throw _makeError(errClass, "safe-url/missing", "url is required");
+  }
+
+  var parsed;
+  if (url instanceof URL) {
+    parsed = url;
+  } else {
+    try {
+      parsed = new URL(String(url));
+    } catch (e) {
+      throw _makeError(errClass, "safe-url/malformed", "malformed URL: " + e.message);
+    }
+  }
+
+  if (allowed.indexOf(parsed.protocol) === -1) {
+    throw _makeError(errClass, "safe-url/protocol-disallowed",
+      "protocol '" + parsed.protocol + "' not in allowlist [" + allowed.join(", ") +
+      "]. Pass opts.allowedProtocols to override (e.g. safeUrl.ALLOW_HTTP_ALL for cleartext endpoints).");
+  }
+
+  return parsed;
+}
+
+module.exports = {
+  parse:           parse,
+  SafeUrlError:    SafeUrlError,
+  ALLOW_HTTP_TLS:  ALLOW_HTTP_TLS,
+  ALLOW_HTTP_ALL:  ALLOW_HTTP_ALL,
+  ALLOW_WS_TLS:    ALLOW_WS_TLS,
+  ALLOW_WS_ALL:    ALLOW_WS_ALL,
+  ALLOW_ANY:       ALLOW_ANY,
+};