@blamejs/core 0.14.27 → 0.15.0

package/lib/db-schema.js

@@ -37,10 +37,18 @@
  *                             swallowing the original error.
  */
 var nodePath = require("node:path");
+var lazyRequire = require("./lazy-require");
 var atomicFile = require("./atomic-file");
+var frameworkSchema = require("./framework-schema");
 var safeSql = require("./safe-sql");
+var sql = require("./sql");
 var observability = require("./observability");
 
+// Lazy to break the db-schema -> compliance -> (audit/db) load chain.
+// resolveDriftMode reads the globally-pinned posture so a regulated
+// deployment refuses to boot under undeclared schema drift by default.
+var compliance = lazyRequire(function () { return require("./compliance"); });
+
 // SQLite raw-SQL helper. node:sqlite DatabaseSync exposes a method on the
 // database object that runs raw SQL without bind parameters — used for DDL,
 // BEGIN/COMMIT/ROLLBACK, and PRAGMA. Bracket notation here avoids a
@@ -92,20 +100,22 @@ function runInTransaction(db, fn, opts) {
 
 // ---- Internal migrations table ----
 
-var MIGRATIONS_TABLE = "_blamejs_migrations";
-// Pre-quoted for SQL interpolation — keeps the call sites consistent
-// with lib/migrations.js and lib/seeders.js so an identifier rename
-// doesn't silently break.
-var Q_MIGRATIONS_TABLE = '"' + MIGRATIONS_TABLE + '"';
+// Logical name; the physical name + configured prefix resolve through
+// frameworkSchema.tableName, and every statement composes b.sql
+// (quoteName: true) so the resolved name is quoted by construction.
+var MIGRATIONS_TABLE = "_blamejs_migrations";  // allow:hand-rolled-sql — logical name declaration; physical name + prefix resolve via frameworkSchema.tableName
+function _migrationsTable() { return frameworkSchema.tableName(MIGRATIONS_TABLE); }
+// b.sql opts for the local single-node sqlite handle this module's helpers
+// run against (database.exec / database.prepare, never clusterStorage):
+// "sqlite" dialect + quoteName so the resolved framework name quotes.
+var _SQL_OPTS = { dialect: "sqlite", quoteName: true };
 
 function ensureMigrationsTable(database) {
-  runSql(database,
-    "CREATE TABLE IF NOT EXISTS " + Q_MIGRATIONS_TABLE + " (" +
-    "  name        TEXT PRIMARY KEY," +
-    "  description TEXT," +
-    "  appliedAt   TEXT NOT NULL" +
-    ")"
-  );
+  runSql(database, sql.createTable(_migrationsTable(), [
+    { name: "name",        type: "text", primaryKey: true },
+    { name: "description", type: "text" },
+    { name: "appliedAt",   type: "text", notNull: true },
+  ], _SQL_OPTS).sql);
 }
 
 // ---- Declarative reconcile ----
@@ -114,7 +124,7 @@ function ensureMigrationsTable(database) {
 // additive ALTER TABLE ADD COLUMN + CREATE INDEX IF NOT EXISTS for every
 // table in `schema`. Never drops columns or tables (data-loss safety).
 //
-// `opts.onDrift` adds opt-in detection of config-vs-live divergence — a
+// `opts.onDrift` controls detection of config-vs-live divergence — a
 // compliance-evidence concern: the live DB should match the declared data
 // model so an auditor can trust the schema config as ground truth (the
 // change-/configuration-management control families in ISO 27001:2022
@@ -131,14 +141,24 @@ function ensureMigrationsTable(database) {
 // contract; this is detection + an operator-chosen reaction only.
 //
 // onDrift values (config-time enum; bad value throws):
-//   "ignore"  (default) — pre-detection behavior, byte-for-byte; no
-//                         detection side effects. Existing deployments
-//                         with drift are not broken.
+//   "ignore"  — no detection side effects. Existing deployments with
+//               benign drift are not broken.
 //   "warn"    — detect + emit a "db.schema.drift" observability event per
 //               drifted table; never throws.
 //   "refuse"  — detect + THROW on the first drifted table, so a strict-
-//               schema posture refuses to boot under divergence. The
-//               operator's explicit posture choice.
+//               schema posture refuses to boot under divergence.
+//
+// Default (v0.15.0): "ignore" on an unpinned / non-regulated deployment
+// (back-compat); "refuse" when a regulated compliance posture is
+// globally pinned (b.compliance.set) and the operator did not pass an
+// explicit onDrift. The live DB diverging from the declared data model
+// is a change-/configuration-management finding the auditor reads as
+// ground truth (ISO 27001:2022 A.8.9 + SOC 2 CC8.1 turn on "the running
+// system equals the approved definition"); under a regulated posture
+// the safe default is to refuse boot rather than silently serve a
+// schema no one approved. Operators who knowingly run with drift under
+// a regulated posture opt back to the prior behaviour with an explicit
+// onDrift: "ignore" (or "warn" to keep the signal without the throw).
 //
 // Returns a { tables: [...], drifted: boolean } report.
 function reconcile(database, schema, opts) {
@@ -165,6 +185,13 @@ function reconcileTable(database, table, opts) {
     throw new Error("schema entry '" + table.name + "' missing 'columns' object");
   }
   var driftMode = resolveDriftMode(opts);
+  // Identifier quoting follows the handle's dialect (double-quote on
+  // sqlite/postgres, backtick on mysql) so the reconciler's CREATE / ALTER
+  // / FK DDL is portable. Reserved-word column names stay safe by being
+  // quoted; the operator's verbatim TYPE strings are emitted unchanged in
+  // type position (after a quoted identifier), never in identifier position.
+  var dialect = _handleDialect(database);
+  function q(ident) { return safeSql.quoteIdentifier(ident, dialect, { allowReserved: true }); }
 
   var name = table.name;
   validateIdent(name, "table name");
@@ -172,7 +199,7 @@ function reconcileTable(database, table, opts) {
   var colDefs = [];
   for (var col in table.columns) {
     validateIdent(col, "column name");
-    colDefs.push('"' + col + '" ' + table.columns[col]);
+    colDefs.push(q(col) + " " + table.columns[col]);
   }
   if (colDefs.length === 0) {
     throw new Error("schema entry '" + name + "' has no columns");
@@ -188,7 +215,7 @@ function reconcileTable(database, table, opts) {
         throw new Error("primaryKey '" + c + "' is not declared in columns of table '" + name + "'");
       }
     });
-    colDefs.push("PRIMARY KEY (" + pkCols.map(function (c) { return '"' + c + '"'; }).join(", ") + ")");
+    colDefs.push("PRIMARY KEY (" + pkCols.map(function (c) { return q(c); }).join(", ") + ")");
   }
 
   // Structured FOREIGN KEY declarations. Each entry:
@@ -217,21 +244,31 @@ function reconcileTable(database, table, opts) {
       if (localCols.length !== refCols.length) {
         throw new Error("foreignKey on '" + name + "': local-column count must match referenced-column count");
       }
-      var clause = "FOREIGN KEY (" + localCols.map(function (c) { return '"' + c + '"'; }).join(", ") + ")" +
-        ' REFERENCES "' + refTable + '" (' + refCols.map(function (c) { return '"' + c + '"'; }).join(", ") + ")";
+      var clause = "FOREIGN KEY (" + localCols.map(function (c) { return q(c); }).join(", ") + ")" +
+        " REFERENCES " + q(refTable) + " (" + refCols.map(function (c) { return q(c); }).join(", ") + ")";
       if (fk.onDelete) clause += " ON DELETE " + _validateAction(fk.onDelete, "ON DELETE", name);
       if (fk.onUpdate) clause += " ON UPDATE " + _validateAction(fk.onUpdate, "ON UPDATE", name);
       colDefs.push(clause);
     }
   }
 
-  runSql(database, 'CREATE TABLE IF NOT EXISTS "' + name + '" (' + colDefs.join(", ") + ")");
+  // Operator-schema reconcile: colDefs carries the operator's VERBATIM
+  // per-column DDL strings (e.g. "TEXT PRIMARY KEY", "INTEGER NOT NULL
+  // DEFAULT 0") plus composite FOREIGN KEY clauses with referential
+  // actions — a grammar b.sql.createTable's structured { name, type,
+  // notNull, references } column specs cannot faithfully reproduce
+  // (no table-level composite-FK or arbitrary-inline-constraint slot).
+  // Every identifier here is validated (validateIdent) + quoted by
+  // construction, so quote-by-construction safety is preserved.
+  // allow:hand-rolled-sql — operator verbatim column DDL + composite FK clauses outside b.sql.createTable's structured API
+  runSql(database, "CREATE TABLE IF NOT EXISTS " + q(name) + " (" + colDefs.join(", ") + ")");
 
   var existingCols = listColumns(database, name);
   for (var newCol in table.columns) {
     if (!existingCols.has(newCol)) {
       try {
-        runSql(database, 'ALTER TABLE "' + name + '" ADD COLUMN "' + newCol + '" ' + table.columns[newCol]);
+        // allow:hand-rolled-sql — operator verbatim ADD COLUMN DDL (validated + quoted identifier); type string is operator-controlled
+        runSql(database, "ALTER TABLE " + q(name) + " ADD COLUMN " + q(newCol) + " " + table.columns[newCol]);
       } catch (e) {
         throw new Error("failed to add column '" + newCol + "' to '" + name + "': " + e.message);
       }
@@ -244,9 +281,10 @@ function reconcileTable(database, table, opts) {
     }
   }
 
-  // Schema-drift detection (opt-in; default "ignore" => no-op). Compares
-  // the live table's columns against the declared model AFTER the additive
-  // ADD COLUMN pass so the diff reflects what reconcile could not fix:
+  // Schema-drift detection. Default mode is posture-driven: "refuse"
+  // under a regulated pinned posture, "ignore" otherwise (resolveDriftMode).
+  // Compares the live table's columns against the declared model AFTER the
+  // additive ADD COLUMN pass so the diff reflects what reconcile could not fix:
   //   - extra    = live-but-undeclared (out-of-band ALTER / hand-edit);
   //   - missing  = declared-but-still-absent (ADD COLUMN could not apply).
   // Dropped columns are never acted on — reconcile stays non-destructive.
@@ -310,17 +348,51 @@ function _validateAction(action, label, tableName) {
   return up;
 }
 
-// onDrift reaction modes. "ignore" preserves pre-drift-detection
-// behavior byte-for-byte; "warn" emits an observability signal and
-// reports; "refuse" throws so a strict-schema posture refuses to boot
-// when the live DB has diverged from the declared model.
+// onDrift reaction modes. "ignore" takes no action on detected drift;
+// "warn" emits an observability signal and reports; "refuse" throws so a
+// strict-schema posture refuses to boot when the live DB has diverged
+// from the declared model.
 var DRIFT_MODES = ["ignore", "warn", "refuse"];
 
-// resolveDriftMode — config-time enum validation. Undefined => "ignore"
-// (default; existing deployments see zero behavior change). A bad value
-// is an operator typo at config time → THROW (entry-point tier).
+// Compliance postures under which schema conformance is an audit-evidence
+// floor (change-/configuration-management control families: ISO 27001:2022
+// A.8.9, SOC 2 CC8.1). When one of these is the globally-pinned posture
+// and the operator left onDrift unset, the default flips from "ignore" to
+// "refuse" so an unapproved live schema fails boot rather than serving
+// silently. Membership match is exact against compliance().current().
+var REGULATED_DRIFT_REFUSE = Object.freeze({
+  "hipaa": true, "pci-dss": true, "gdpr": true, "soc2": true,
+  "iso-27001-2022": true, "dora": true, "fedramp-rev5-moderate": true,
+  "nist-800-53": true, "nist-800-53-r5-privacy": true, "dpdp": true,
+  "lgpd-br": true, "pipl-cn": true, "uk-gdpr": true,
+});
+
+// _pinnedRegulatedDrift — the posture-driven default when onDrift is unset.
+// Returns "refuse" when a regulated posture is globally pinned, "ignore"
+// otherwise. Drop-safe: any failure resolving the posture (compliance not
+// loaded, no posture pinned) yields the back-compat "ignore" — the gate
+// only tightens the default when a regulated posture is provably pinned,
+// never the reverse.
+function _pinnedRegulatedDrift() {
+  try {
+    var pinned = compliance().current();
+    if (typeof pinned === "string" && REGULATED_DRIFT_REFUSE[pinned] === true) {
+      return "refuse";
+    }
+  } catch (_e) { /* compliance unavailable — fall through to back-compat */ }
+  return "ignore";
+}
+
+// resolveDriftMode — config-time enum validation. Unset => the
+// posture-driven default ("refuse" under a regulated pinned posture,
+// "ignore" otherwise; see REGULATED_DRIFT_REFUSE). An explicit value
+// always wins, including "ignore" to opt back out under a regulated
+// posture. A bad value is an operator typo at config time => THROW
+// (entry-point tier).
 function resolveDriftMode(opts) {
-  if (!opts || opts.onDrift === undefined || opts.onDrift === null) return "ignore";
+  if (!opts || opts.onDrift === undefined || opts.onDrift === null) {
+    return _pinnedRegulatedDrift();
+  }
   var mode = opts.onDrift;
   if (typeof mode !== "string" || DRIFT_MODES.indexOf(mode) === -1) {
     throw new TypeError(
@@ -345,17 +417,99 @@ function reconcileIndex(database, tableName, idx) {
   }
   validateIdent(indexName, "index name");
   cols.forEach(function (c) { validateIdent(c, "indexed column"); });
-  var quotedCols = cols.map(function (c) { return '"' + c + '"'; }).join(", ");
+  var dialect = _handleDialect(database);
+  function q(ident) { return safeSql.quoteIdentifier(ident, dialect, { allowReserved: true }); }
+  var quotedCols = cols.map(function (c) { return q(c); }).join(", ");
+  // MySQL has no CREATE INDEX IF NOT EXISTS; a re-run of a declared index
+  // would error "Duplicate key name". The reconciler is idempotent by
+  // contract, so on MySQL a duplicate-index error is swallowed (the index
+  // already exists, which is the desired end state). Postgres + SQLite use
+  // the IF NOT EXISTS form natively.
+  if (dialect === "mysql") {
+    try {
+      runSql(database,
+        "CREATE " + (unique ? "UNIQUE " : "") + "INDEX " + q(indexName) +
+        " ON " + q(tableName) + " (" + quotedCols + ")");
+    } catch (e) {
+      if (!/exist|duplicate/i.test((e && e.message) || "")) throw e;
+    }
+    return;
+  }
   runSql(database,
-    "CREATE " + (unique ? "UNIQUE " : "") + "INDEX IF NOT EXISTS \"" + indexName + "\"" +
-    ' ON "' + tableName + '" (' + quotedCols + ")"
+    "CREATE " + (unique ? "UNIQUE " : "") + "INDEX IF NOT EXISTS " + q(indexName) +
+    " ON " + q(tableName) + " (" + quotedCols + ")"
   );
 }
 
+// The dialect of a data-layer handle. db.init / db.from drive the
+// framework's local node:sqlite handle (the default). An operator who
+// reconciles / migrates / seeds their OWN Postgres / MySQL handle declares
+// the dialect on the handle via `handle.dialect` so the SQL matches the
+// backend. Absent / unknown falls back to "sqlite" — every existing
+// local-handle caller is byte-identical. Shared by db-schema's reconciler,
+// migrations.js, and seeders.js (the three sync data-layer files that drive
+// a handle directly), so the resolution lives in one place.
+function handleDialect(database) {
+  var d = database && database.dialect;
+  if (d === "postgres" || d === "mysql" || d === "sqlite") return d;
+  return "sqlite";
+}
+// Back-compat internal alias used throughout this module.
+var _handleDialect = handleDialect;
+
+// b.sql opts for a statement run directly against `database` (db.prepare /
+// runSqlOnHandle, never clusterStorage): the handle's dialect + quoteName so
+// the resolved framework table name quotes by construction.
+function sqlOpts(database) {
+  return { dialect: handleDialect(database), quoteName: true };
+}
+
+// A registry/lock PRIMARY-KEY (or composite-PK / indexed) TEXT column type.
+// MySQL refuses an unbounded TEXT/BLOB in a key without a prefix length, so
+// a key-participating text column is VARCHAR(191) there (utf8mb4
+// index-safe); Postgres + SQLite index TEXT directly. The value is emitted
+// verbatim by b.sql in type position (after a quoted identifier), never as
+// an identifier.
+function keyTextType(database) {
+  return handleDialect(database) === "mysql" ? "VARCHAR(191)" : "text";
+}
+
+// List the live column names of a table. SQLite reads `PRAGMA table_info`;
+// Postgres + MySQL read information_schema.columns (PRAGMA is SQLite-only —
+// it throws "syntax error at PRAGMA" on the others). The table name binds
+// as a `?` parameter (never concatenated into the SQL text), so an operator
+// table name with metacharacters can't break the introspection query. On
+// Postgres the unqualified information_schema query matches the table in
+// any schema on the search_path; an operator running the same table name in
+// multiple schemas qualifies via the `schema.table` handle convention
+// elsewhere — listColumns reconciles by bare name here, matching the
+// reconciler's CREATE TABLE (which is also bare-named).
 function listColumns(database, tableName) {
-  var rows = database.prepare('PRAGMA table_info("' + tableName + '")').all();
+  var dialect = _handleDialect(database);
   var set = new Set();
-  for (var i = 0; i < rows.length; i++) set.add(rows[i].name);
+  if (dialect === "sqlite") {
+    var rows = database.prepare('PRAGMA table_info("' + tableName + '")').all();
+    for (var i = 0; i < rows.length; i++) set.add(rows[i].name);
+    return set;
+  }
+  // Postgres + MySQL: information_schema.columns is SQL-standard on both.
+  // The column-name column is `column_name` on both; the table name binds.
+  // A fixed catalog-introspection SELECT against the SQL-standard
+  // information_schema.columns view (a schema-qualified system table b.sql's
+  // verb builders don't model); the ONLY value (table name) binds as a `?`,
+  // every column/table reference is a static literal — no injection surface.
+  // allow:hand-rolled-sql — static information_schema introspection, single bound param
+  var infoSql = "SELECT column_name FROM information_schema.columns " +
+                "WHERE table_name = ?";
+  var stmt = database.prepare(infoSql);
+  var irows = stmt.all.apply(stmt, [tableName]);
+  for (var j = 0; j < irows.length; j++) {
+    // node-postgres folds unquoted output column names to lowercase, so the
+    // result key is `column_name` on every driver; read it directly.
+    var name = irows[j].column_name;
+    if (name === undefined) name = irows[j].COLUMN_NAME;  // some MySQL drivers upper-case
+    if (name !== undefined && name !== null) set.add(name);
+  }
   return set;
 }
 
@@ -384,7 +538,9 @@ function runMigrations(database, migrationDir) {
   }).map(function (e) { return e.name; }).sort();
 
   var appliedSet = new Set();
-  database.prepare("SELECT name FROM " + Q_MIGRATIONS_TABLE).all().forEach(function (r) {
+  var namesQ = sql.select(_migrationsTable(), _SQL_OPTS).columns(["name"]).toSql();
+  var namesStmt = database.prepare(namesQ.sql);
+  namesStmt.all.apply(namesStmt, namesQ.params).forEach(function (r) {
     appliedSet.add(r.name);
   });
 
@@ -413,9 +569,11 @@ function runMigrations(database, migrationDir) {
     try {
       runInTransaction(database, function () {
         mig.up(database);
-        database.prepare(
-          "INSERT INTO " + Q_MIGRATIONS_TABLE + " (name, description, appliedAt) VALUES (?, ?, ?)"
-        ).run(file, mig.description || "", new Date().toISOString());
+        var insQ = sql.insert(_migrationsTable(), _SQL_OPTS)
+          .values({ name: file, description: mig.description || "",
+                    appliedAt: new Date().toISOString() }).toSql();
+        var insStmt = database.prepare(insQ.sql);
+        insStmt.run.apply(insStmt, insQ.params);
       });
     } catch (e) {
       throw new Error("migration '" + file + "' failed: " + e.message);
@@ -434,6 +592,13 @@ module.exports = {
   runSql:           runSql,
   runSqlOnHandle:   runSqlOnHandle,
   runInTransaction: runInTransaction,
+  // Shared data-layer dialect resolution — composed by migrations.js +
+  // seeders.js so the handle-dialect / b.sql-opts / key-text-type logic
+  // lives in exactly one place.
+  handleDialect:    handleDialect,
+  sqlOpts:          sqlOpts,
+  keyTextType:      keyTextType,
+  listColumns:      listColumns,
   MIGRATIONS_TABLE: MIGRATIONS_TABLE,
   DRIFT_MODES:      DRIFT_MODES,
 };