@blamejs/core 0.8.43 → 0.8.49

package/lib/safe-sql.js

@@ -1,53 +1,44 @@
 "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
+ * @module b.safeSql
+ * @nav    Validation
+ * @title  Safe Sql
+ *
+ * @intro
+ *   SQL identifier validation + dialect-aware quoting + allowlist
+ *   gating. Defends against IDENTIFIER injection — the residual attack
+ *   surface left over when a TABLE name or COLUMN name flows from
+ *   operator-supplied config into a SQL string. Values bind through
+ *   parameterized queries everywhere in the framework, but parameters
+ *   can't carry identifiers; that interpolation is what this module
+ *   guards.
+ *
+ *   Default identifier shape: `^[A-Za-z_][A-Za-z0-9_]*$`, length 1–63
+ *   (Postgres NAMEDATALEN — the strictest of the supported dialects).
+ *   Reserved words (SELECT / DROP / PRAGMA / ATTACH / …) and the
+ *   SQLite-internal `sqlite_` prefix are refused unless the caller
+ *   explicitly opts in. Quoting follows dialect convention: SQLite +
+ *   Postgres double-quote, MySQL backtick. Multi-segment names
+ *   (`schema.table`) validate + quote each segment independently so
+ *   the dotted form `"schema"."table"` resolves correctly instead of
+ *   collapsing into one literal identifier with a dot in it.
+ *
+ *   Recommended pattern is the closed allowlist:
+ *
+ *     var ALLOWED = new Set(["audit_log", "consent_log"]);
+ *     b.safeSql.assertOneOf(name, ALLOWED);
+ *     var sql = "INSERT INTO " + b.safeSql.quoteIdentifier(name) + " ...";
+ *
+ *   The allowlist is the strongest guarantee. Operators with genuinely
+ *   dynamic identifier needs use `validateIdentifier` alone, accepting
  *   that any string passing the regex is allowed.
+ *
+ *   Validation policy: every primitive throws `SafeSqlError` on bad
+ *   input — these run at SQL-composition time, well before the query
+ *   reaches the database. The throw IS the security signal.
+ *
+ * @card
+ *   SQL identifier validation + dialect-aware quoting + allowlist gating.
  */
 
 // Reserved-word block list — the most dangerous to accept as a bare
@@ -73,6 +64,30 @@ var MAX_IDENTIFIER_LENGTH = 63;
 
 var { FrameworkError } = require("./framework-error");
 
+/**
+ * @primitive b.safeSql.SafeSqlError
+ * @signature b.safeSql.SafeSqlError
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSql.validateIdentifier, b.safeSql.quoteIdentifier, b.safeSql.assertOneOf
+ *
+ * Error class thrown by every `b.safeSql` primitive on bad input.
+ * Extends `FrameworkError`. Carries a stable `.code` —
+ * `sql/bad-type` / `sql/empty` / `sql/too-long` / `sql/null-byte` /
+ * `sql/bad-shape` / `sql/reserved-word` / `sql/internal-prefix` /
+ * `sql/not-allowed` / `sql/bad-allowlist`. Operators catch these at
+ * SQL-composition boundaries; the throw fires before the query
+ * reaches the database driver.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   try {
+ *     b.safeSql.validateIdentifier("drop");
+ *   } catch (e) {
+ *     e instanceof b.safeSql.SafeSqlError;   // → true
+ *     e.code;                                // → "sql/reserved-word"
+ *   }
+ */
 class SafeSqlError extends FrameworkError {
   constructor(message, code) {
     super(message);
@@ -82,6 +97,42 @@ class SafeSqlError extends FrameworkError {
   }
 }
 
+/**
+ * @primitive b.safeSql.validateIdentifier
+ * @signature b.safeSql.validateIdentifier(name, opts?)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSql.quoteIdentifier, b.safeSql.assertOneOf, b.safeSql.SafeSqlError
+ *
+ * Throw-on-bad-shape validator for SQL table / column / index names.
+ * Enforces the default identifier regex (`[A-Za-z_][A-Za-z0-9_]*`),
+ * a 63-character cap (Postgres NAMEDATALEN — strictest supported
+ * dialect), no embedded null byte, no SQL reserved word, no
+ * SQLite-internal `sqlite_` prefix. Returns `name` on success so the
+ * call composes inside a SQL fragment without an extra temporary.
+ *
+ * @opts
+ *   pattern:              RegExp,  // override the default shape regex
+ *   allowReserved:        boolean, // default false; permit reserved words like "select"/"drop"
+ *   allowSqliteInternal:  boolean, // default false; permit "sqlite_..." identifiers
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeSql.validateIdentifier("audit_log");
+ *   // → "audit_log"
+ *
+ *   try { b.safeSql.validateIdentifier("drop"); }
+ *   catch (e) { e.code; }
+ *   // → "sql/reserved-word"
+ *
+ *   try { b.safeSql.validateIdentifier("evil; DROP"); }
+ *   catch (e) { e.code; }
+ *   // → "sql/bad-shape"
+ *
+ *   // Operator opts in to a custom shape (still ASCII-only, still capped).
+ *   b.safeSql.validateIdentifier("col-1", { pattern: /^[A-Za-z][A-Za-z0-9_-]*$/ });
+ *   // → "col-1"
+ */
 function validateIdentifier(name, opts) {
   opts = opts || {};
   if (typeof name !== "string") {
@@ -122,6 +173,29 @@ function validateIdentifier(name, opts) {
   return name;
 }
 
+/**
+ * @primitive b.safeSql.quoteIdentifier
+ * @signature b.safeSql.quoteIdentifier(name, dialect?)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSql.validateIdentifier, b.safeSql.quoteQualified
+ *
+ * Validate `name` then wrap it in dialect-appropriate quotes —
+ * double-quote for SQLite + Postgres (per SQL standard), backtick for
+ * MySQL. Default dialect is `"sqlite"`. Throws `SafeSqlError` if the
+ * identifier fails `validateIdentifier`.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeSql.quoteIdentifier("users");
+ *   // → '"users"'
+ *
+ *   b.safeSql.quoteIdentifier("Order", "postgres");
+ *   // → '"Order"'
+ *
+ *   b.safeSql.quoteIdentifier("users", "mysql");
+ *   // → "`users`"
+ */
 function quoteIdentifier(name, dialect) {
   validateIdentifier(name);
   dialect = (dialect || "sqlite").toLowerCase();
@@ -130,18 +204,35 @@ function quoteIdentifier(name, dialect) {
   return '"' + name + '"';
 }
 
-// Quote a multi-part qualified name like `schema.table` or
-// `database.schema.table`. Each segment is validated + quoted
-// independently so the dotted form `"schema"."table"` resolves
-// correctly. Replaces the wrong shape `"schema.table"` (one literal
-// identifier with a dot in it). Accepts an array of parts OR a string
-// with `.` as the separator.
-//
-//   quoteQualified(["public", "users"])     → '"public"."users"'
-//   quoteQualified("public.users")          → '"public"."users"'
-//   quoteQualified(["public", "Order"], "postgres")
-//                                          → '"public"."Order"'   (case preserved)
-//   quoteQualified("dbA.public.users")      → '"dbA"."public"."users"'
+/**
+ * @primitive b.safeSql.quoteQualified
+ * @signature b.safeSql.quoteQualified(parts, dialect?)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSql.quoteIdentifier, b.safeSql.validateIdentifier
+ *
+ * Quote a multi-part qualified name like `schema.table` or
+ * `database.schema.table`. Each segment is validated and quoted
+ * independently so the resulting SQL is `"schema"."table"` (three
+ * lookups against the catalog) instead of `"schema.table"` (one
+ * literal identifier with a dot in its name — a different and
+ * usually-nonexistent object). Accepts an array of parts OR a
+ * dot-separated string.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeSql.quoteQualified(["public", "users"]);
+ *   // → '"public"."users"'
+ *
+ *   b.safeSql.quoteQualified("public.users");
+ *   // → '"public"."users"'
+ *
+ *   b.safeSql.quoteQualified("dbA.public.users");
+ *   // → '"dbA"."public"."users"'
+ *
+ *   b.safeSql.quoteQualified(["app", "orders"], "mysql");
+ *   // → "`app`.`orders`"
+ */
 function quoteQualified(parts, dialect) {
   var arr;
   if (typeof parts === "string") {
@@ -167,6 +258,36 @@ function quoteQualified(parts, dialect) {
   return quoted.join(".");
 }
 
+/**
+ * @primitive b.safeSql.assertOneOf
+ * @signature b.safeSql.assertOneOf(name, allowlist)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSql.validateIdentifier, b.safeSql.quoteIdentifier
+ *
+ * Closed-allowlist gate — the strongest guarantee against identifier
+ * injection. `allowlist` is a `Set` or `Array` of permitted names;
+ * anything outside throws `SafeSqlError` with `.code = "sql/not-allowed"`.
+ * Returns `name` on success so the call composes inline with
+ * `quoteIdentifier`. Use this whenever the operator-supplied identifier
+ * is drawn from a known finite set (which is most cases — table names
+ * are config, not user input).
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var ALLOWED = new Set(["audit_log", "consent_log", "session"]);
+ *
+ *   b.safeSql.assertOneOf("audit_log", ALLOWED);
+ *   // → "audit_log"
+ *
+ *   try { b.safeSql.assertOneOf("users", ALLOWED); }
+ *   catch (e) { e.code; }
+ *   // → "sql/not-allowed"
+ *
+ *   // Array form works too.
+ *   b.safeSql.assertOneOf("audit_log", ["audit_log", "consent_log"]);
+ *   // → "audit_log"
+ */
 function assertOneOf(name, allowlist) {
   if (typeof name !== "string") {
     throw new SafeSqlError("name must be a string", "sql/bad-type");
@@ -189,6 +310,47 @@ function assertOneOf(name, allowlist) {
   return name;
 }
 
+/**
+ * @primitive b.safeSql.DEFAULT_IDENTIFIER_RE
+ * @signature b.safeSql.DEFAULT_IDENTIFIER_RE
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSql.validateIdentifier, b.safeSql.MAX_IDENTIFIER_LENGTH
+ *
+ * The default identifier shape regex — `/^[A-Za-z_][A-Za-z0-9_]*$/`.
+ * Exposed so operator code that needs a slightly-wider or
+ * slightly-narrower shape can compose against it instead of
+ * re-deriving the pattern. ASCII-only by design — Unicode
+ * identifiers are dialect-specific and surface in mismatched-encoding
+ * footguns we don't want to default into.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeSql.DEFAULT_IDENTIFIER_RE.test("audit_log");
+ *   // → true
+ *
+ *   b.safeSql.DEFAULT_IDENTIFIER_RE.test("1starts_with_digit");
+ *   // → false
+ */
+
+/**
+ * @primitive b.safeSql.MAX_IDENTIFIER_LENGTH
+ * @signature b.safeSql.MAX_IDENTIFIER_LENGTH
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSql.validateIdentifier, b.safeSql.DEFAULT_IDENTIFIER_RE
+ *
+ * Hard cap on identifier length — 63 characters. Matches Postgres'
+ * NAMEDATALEN default; SQLite and MySQL accept longer names but
+ * defaulting to the strictest dialect keeps cross-dialect SQL
+ * portable.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeSql.MAX_IDENTIFIER_LENGTH;
+ *   // → 63
+ */
+
 module.exports = {
   validateIdentifier:  validateIdentifier,
   quoteIdentifier:     quoteIdentifier,