@blamejs/core 0.6.1 → 0.6.3

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **0.6.2** (2026-05-01) — input validation + identifier-quoting consistency
+- **0.6.1** (2026-05-01) — security tightenings + operator-facing jargon sweep
 - **0.6.0** (2026-05-01) — wiki restructured into 22 focused pages + missing-primitive coverage
 
 ## v0.5.x

package/README.md

@@ -17,7 +17,7 @@ The modern Node app is a 1,200-package supply-chain liability with no LTS calend
 
 ## Status
 
-Pre-1.0. Usable end-to-end — operators can build production apps on it today; the surface is still subject to change before 1.0. Recent line is **v0.6.1** ([releases](https://github.com/blamejs/blamejs/releases) · [npm](https://www.npmjs.com/package/@blamejs/core) · [container](https://github.com/blamejs/blamejs/pkgs/container/blamejs-wiki)).
+Pre-1.0. Usable end-to-end — operators can build production apps on it today; the surface is still subject to change before 1.0. Recent line is **v0.6.3** ([releases](https://github.com/blamejs/blamejs/releases) · [npm](https://www.npmjs.com/package/@blamejs/core) · [container](https://github.com/blamejs/blamejs/pkgs/container/blamejs-wiki)).
 
 ```js
 var b = require("@blamejs/core");
@@ -63,6 +63,7 @@ Full primitive-by-primitive docs live at [blamejs.com](https://blamejs.com), whi
 - **Validation** — [Safe Parsers](https://blamejs.com/safe-parsers)
 - **Communication** — [WebSockets](https://blamejs.com/websockets) · [Mail](https://blamejs.com/mail) · [Notifications](https://blamejs.com/notifications)
 - **Tools** — [Observability](https://blamejs.com/observability) · [Testing](https://blamejs.com/testing) · [i18n & Locale](https://blamejs.com/i18n-locale) · [Format Helpers](https://blamejs.com/format-helpers)
+- **Compliance** — [Compliance Patterns](https://blamejs.com/compliance-patterns)
 - **Production** — [Cluster Mode](https://blamejs.com/cluster) · [Reliability](https://blamejs.com/reliability) · [Backup & Restore](https://blamejs.com/backup-restore)
 
 ## CLI

package/lib/api-key.js

@@ -74,7 +74,12 @@ function _emitEvent(name, value, labels) {
 
 var _err = ApiKeyError.factory;
 
-var TABLE = "_blamejs_api_keys";
+var TABLE   = "_blamejs_api_keys";
+// Pre-quoted form for SQL interpolation. Defense-in-depth: even though
+// our constant is bare-identifier-shaped, every interpolation site uses
+// the wrapped form so a future rename to a reserved-word or
+// whitespace-bearing name would still resolve correctly.
+var Q_TABLE = '"' + TABLE + '"';
 
 // Column order used for INSERT — kept as a constant so the placeholders
 // list and the values list stay in sync. Must match _blamejs_api_keys'
@@ -286,7 +291,7 @@ function create(opts) {
   function _selectAll() {
     return "SELECT id, namespace, ownerId, ownerIdHash, secretHash, " +
            "secondarySecretHash, secondaryExpiresAt, " +
-           "scopes, metadata, createdAt, expiresAt, revokedAt, lastUsedAt, prefix FROM " + TABLE;
+           "scopes, metadata, createdAt, expiresAt, revokedAt, lastUsedAt, prefix FROM " + Q_TABLE;
   }
 
   function _scrubRecord(row) {
@@ -352,7 +357,7 @@ function create(opts) {
     var quoted = COLS.map(function (c) { return '"' + c + '"'; }).join(", ");
 
     await clusterStorage.execute(
-      "INSERT INTO " + TABLE + " (" + quoted + ") VALUES (" + placeholders + ")",
+      "INSERT INTO " + Q_TABLE + " (" + quoted + ") VALUES (" + placeholders + ")",
       values
     );
 
@@ -453,7 +458,7 @@ function create(opts) {
     if (trackLastUsedAt && cluster.isLeader()) {
       try {
         await clusterStorage.execute(
-          "UPDATE " + TABLE + " SET lastUsedAt = ? WHERE id = ?",
+          "UPDATE " + Q_TABLE + " SET lastUsedAt = ? WHERE id = ?",
           [nowMs, compositeId]
         );
       } catch (_e) { /* best-effort; verify success not blocked by lastUsed update */ }
@@ -480,7 +485,7 @@ function create(opts) {
     var compositeId = _composedId(namespace, idHex);
     var nowMs = clock();
     var result = await clusterStorage.execute(
-      "UPDATE " + TABLE + " SET revokedAt = ? WHERE id = ? AND revokedAt IS NULL",
+      "UPDATE " + Q_TABLE + " SET revokedAt = ? WHERE id = ? AND revokedAt IS NULL",
       [nowMs, compositeId]
     );
     var changed = (result.rowCount || 0) > 0;
@@ -537,7 +542,7 @@ function create(opts) {
     if (gracePeriodMs > 0) {
       // Move current hash → secondary slot, install new hash as primary.
       await clusterStorage.execute(
-        "UPDATE " + TABLE + " SET secretHash = ?, " +
+        "UPDATE " + Q_TABLE + " SET secretHash = ?, " +
         "secondarySecretHash = ?, secondaryExpiresAt = ? WHERE id = ?",
         [newHash, existing.secretHash, nowMs + gracePeriodMs, compositeId]
       );
@@ -545,7 +550,7 @@ function create(opts) {
       // Hard cutover — old secret stops working immediately. Clears
       // any prior secondary slot too.
       await clusterStorage.execute(
-        "UPDATE " + TABLE + " SET secretHash = ?, " +
+        "UPDATE " + Q_TABLE + " SET secretHash = ?, " +
         "secondarySecretHash = NULL, secondaryExpiresAt = NULL WHERE id = ?",
         [newHash, compositeId]
       );
@@ -639,7 +644,7 @@ function create(opts) {
     // extra round-trip per purge call which runs on a schedule (not
     // request-rate), so the cost is irrelevant.
     var idRows = await clusterStorage.execute(
-      "SELECT id FROM " + TABLE + " WHERE namespace = ? AND " +
+      "SELECT id FROM " + Q_TABLE + " WHERE namespace = ? AND " +
       "((revokedAt IS NOT NULL AND revokedAt < ?) OR " +
       " (expiresAt IS NOT NULL AND expiresAt < ?))",
       [namespace, threshold, threshold]
@@ -652,7 +657,7 @@ function create(opts) {
     }
 
     var result = await clusterStorage.execute(
-      "DELETE FROM " + TABLE + " WHERE namespace = ? AND " +
+      "DELETE FROM " + Q_TABLE + " WHERE namespace = ? AND " +
       "((revokedAt IS NOT NULL AND revokedAt < ?) OR " +
       " (expiresAt IS NOT NULL AND expiresAt < ?))",
       [namespace, threshold, threshold]

package/lib/break-glass.js

@@ -48,6 +48,7 @@ var observability = require("./observability");
 var requestHelpers = require("./request-helpers");
 var safeAsync = require("./safe-async");
 var safeJson = require("./safe-json");
+var safeSql = require("./safe-sql");
 var totp = require("./totp");
 var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
@@ -248,8 +249,12 @@ async function migrate(table, opts) {
   var lastId = "";
   // Iterate via _id-keyset paging so we don't load the whole table into memory.
   while (true) {
+    // table is already validated as a safe identifier shape via
+    // _validatePolicySet — wrap in "..." per the framework's
+    // identifier-quoting convention.
+    var qTable = '"' + table + '"';
     var rows = await clusterStorage.executeAll(
-      "SELECT * FROM " + table + " WHERE _id > ? ORDER BY _id ASC LIMIT ?",
+      "SELECT * FROM " + qTable + " WHERE _id > ? ORDER BY _id ASC LIMIT ?",
       [lastId, batchSize]
     );
     if (!rows || rows.length === 0) break;
@@ -275,11 +280,14 @@ async function migrate(table, opts) {
         // the cell ciphertext stays as a literal string, not double-sealed.
         var setCols = Object.keys(update).filter(function (k) { return k !== "_id"; });
         if (setCols.length > 0) {
-          var setSql = setCols.map(function (k) { return k + " = ?"; }).join(", ");
+          // Column names came from the validated policy.columns —
+          // also wrap each in "..." for the same identifier-quoting
+          // convention.
+          var setSql = setCols.map(function (k) { return '"' + k + '" = ?'; }).join(", ");
           var vals = setCols.map(function (k) { return update[k]; });
           vals.push(row._id);
           await clusterStorage.execute(
-            "UPDATE " + table + " SET " + setSql + " WHERE _id = ?",
+            "UPDATE " + qTable + " SET " + setSql + " WHERE _id = ?",
             vals
           );
           migratedRows++;
@@ -343,6 +351,20 @@ function _validatePolicySet(table, opts) {
     throw new BreakGlassError("breakglass/bad-policy",
       "policy.set: table must be a non-empty string");
   }
+  // Identifier safety: the table name flows raw into SQL via interpolation
+  // in migrate() / unsealRowAsService(). safeSql.validateIdentifier closes
+  // the shape so a malicious / mistyped name with embedded `"` or
+  // SQL-keyword shape can't break out of the wrapping quotes.
+  // allowReserved: true because every interpolation site quotes the
+  // identifier, so reserved-word names work via the SQL standard quoting
+  // rule.
+  try {
+    safeSql.validateIdentifier(table, { allowReserved: true });
+  } catch (e) {
+    throw new BreakGlassError("breakglass/bad-policy",
+      "policy.set: table '" + table + "' is not a valid SQL identifier: " +
+      ((e && e.message) || String(e)));
+  }
   if (!opts || typeof opts !== "object") {
     throw new BreakGlassError("breakglass/bad-policy",
       "policy.set: opts is required");
@@ -358,10 +380,20 @@ function _validatePolicySet(table, opts) {
       "policy.set: columns must be a non-empty array");
   }
   for (var i = 0; i < opts.columns.length; i++) {
-    if (typeof opts.columns[i] !== "string" || opts.columns[i].length === 0) {
+    var colName = opts.columns[i];
+    if (typeof colName !== "string" || colName.length === 0) {
       throw new BreakGlassError("breakglass/bad-policy",
         "policy.set: columns[" + i + "] must be a non-empty string");
     }
+    // Same identifier-shape check as the table — column names flow into
+    // the migrate() UPDATE statement as bare names.
+    try {
+      safeSql.validateIdentifier(colName, { allowReserved: true });
+    } catch (e) {
+      throw new BreakGlassError("breakglass/bad-policy",
+        "policy.set: columns[" + i + "]='" + colName + "' is not a valid SQL identifier: " +
+        ((e && e.message) || String(e)));
+    }
   }
   if (!Array.isArray(opts.factors) || opts.factors.length === 0) {
     throw new BreakGlassError("breakglass/bad-policy",
@@ -894,7 +926,7 @@ async function unsealRow(grantHandle, table, rowId, opts) {
   // glass-locked columns separately (their ciphertext was written
   // by encryptCell at app-write time, not by cryptoField.sealRow).
   var rows = await clusterStorage.executeAll(
-    "SELECT * FROM " + table + " WHERE _id = ?",
+    "SELECT * FROM " + '"' + table + '"' + " WHERE _id = ?",
     [String(rowId)]
   );
   if (!rows || rows.length === 0) {
@@ -1093,7 +1125,7 @@ async function unsealRowAsService(req, table, rowId, opts) {
   // Fetch + unseal the row (Model A or Model B path, same as
   // operator-initiated unsealRow).
   var rows = await clusterStorage.executeAll(
-    "SELECT * FROM " + table + " WHERE _id = ?",
+    "SELECT * FROM " + '"' + table + '"' + " WHERE _id = ?",
     [String(rowId)]
   );
   if (!rows || rows.length === 0) {

package/lib/cluster.js

@@ -57,6 +57,7 @@ var lazyRequire = require("./lazy-require");
 var { boot } = require("./log");
 var safeAsync = require("./safe-async");
 var safeJson = require("./safe-json");
+var safeSql = require("./safe-sql");
 var safeUrl = require("./safe-url");
 var { FrameworkError, ClusterError } = require("./framework-error");
 
@@ -273,12 +274,21 @@ async function init(opts) {
 //     hash → FATAL via process.exit(1). Same posture as the
 //     single-node audit.tip sidecar rollback check.
 async function _checkChainTipRollback(chainName, logTable, tipTable) {
+  // Both tables are framework-internal constants from the call sites
+  // (`_blamejs_audit_log`, `_blamejs_consent_log`, etc.). Validate +
+  // quote per the framework's identifier-quoting convention so a
+  // future rename can't silently break the query.
+  safeSql.validateIdentifier(logTable, { allowReserved: true });
+  safeSql.validateIdentifier(tipTable, { allowReserved: true });
+  var qLogTable = safeSql.quoteIdentifier(logTable);
+  var qTipTable = safeSql.quoteIdentifier(tipTable);
+
   var tipRows;
   try {
     tipRows = await externalDb().query(
-      "SELECT atMonotonicCounter, rowHash FROM " + tipTable +
-      " WHERE scope = '" + chainName + "'",
-      [],
+      "SELECT atMonotonicCounter, rowHash FROM " + qTipTable +
+      " WHERE scope = " + (configuredDialect === "postgres" ? "$1" : "?"),
+      [chainName],
       { backend: configuredExternalDbBackend }
     );
   } catch (e) {
@@ -298,7 +308,7 @@ async function _checkChainTipRollback(chainName, logTable, tipTable) {
   var tipHash = tip.rowHash;
 
   var currentRows = await externalDb().query(
-    "SELECT MAX(monotonicCounter) AS m FROM " + logTable,
+    "SELECT MAX(monotonicCounter) AS m FROM " + qLogTable,
     [],
     { backend: configuredExternalDbBackend }
   );
@@ -317,7 +327,7 @@ async function _checkChainTipRollback(chainName, logTable, tipTable) {
 
   if (tipHash) {
     var hashRows = await externalDb().query(
-      "SELECT rowHash FROM " + logTable + " WHERE monotonicCounter = " +
+      "SELECT rowHash FROM " + qLogTable + " WHERE monotonicCounter = " +
       (configuredDialect === "postgres" ? "$1" : "?"),
       [tipCounter],
       { backend: configuredExternalDbBackend }

package/lib/db-query.js

@@ -29,11 +29,33 @@
 var { Readable } = require("node:stream");
 var cryptoField = require("./crypto-field");
 var { generateToken } = require("./crypto");
+var safeSql = require("./safe-sql");
 
 var ALLOWED_OPS = new Set(["=", "!=", "<>", "<", "<=", ">", ">=", "IS", "IS NOT", "LIKE", "IN"]);
 
 class Query {
   constructor(database, tableName) {
+    // Identifier safety: tableName flows into SQL via interpolation
+    // (parameter placeholders only bind values, not names). Validate at
+    // construction so an attacker-controlled name with embedded `"` or
+    // SQL keywords can't break out of the wrapping quotes downstream.
+    // Cross-schema queries (e.g., Postgres `public.users`) need the
+    // schema-qualified API, not a dotted single-identifier — reject `.`
+    // here so the failure mode is explicit.
+    if (typeof tableName !== "string") {
+      throw new TypeError("Query: tableName must be a string, got " + typeof tableName);
+    }
+    if (tableName.indexOf(".") !== -1) {
+      throw new Error("Query: tableName '" + tableName + "' contains '.' — use a single " +
+        "identifier; cross-schema queries are not supported by db.from(). " +
+        "For Postgres-style schema.table access, use b.externalDb.query directly.");
+    }
+    // allowReserved: true — db-query always wraps the identifier in
+    // `"..."` so a table named `order` resolves correctly via the SQL
+    // standard quoting rule. The reserved-word block in safeSql is for
+    // call sites that interpolate unquoted.
+    safeSql.validateIdentifier(tableName, { allowReserved: true });
+
     this._db          = database;
     this._table       = tableName;
     this._where       = [];

package/lib/db-schema.js

@@ -33,10 +33,14 @@ function runSql(database, sql) { return database["exec"](sql); }
 // ---- 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 + '"';
 
 function ensureMigrationsTable(database) {
   runSql(database,
-    "CREATE TABLE IF NOT EXISTS " + MIGRATIONS_TABLE + " (" +
+    "CREATE TABLE IF NOT EXISTS " + Q_MIGRATIONS_TABLE + " (" +
     "  name        TEXT PRIMARY KEY," +
     "  description TEXT," +
     "  appliedAt   TEXT NOT NULL" +
@@ -200,7 +204,7 @@ function runMigrations(database, migrationDir) {
   }).map(function (e) { return e.name; }).sort();
 
   var appliedSet = new Set();
-  database.prepare("SELECT name FROM " + MIGRATIONS_TABLE).all().forEach(function (r) {
+  database.prepare("SELECT name FROM " + Q_MIGRATIONS_TABLE).all().forEach(function (r) {
     appliedSet.add(r.name);
   });
 
@@ -227,7 +231,7 @@ function runMigrations(database, migrationDir) {
       runSql(database, "BEGIN");
       mig.up(database);
       database.prepare(
-        "INSERT INTO " + MIGRATIONS_TABLE + " (name, description, appliedAt) VALUES (?, ?, ?)"
+        "INSERT INTO " + Q_MIGRATIONS_TABLE + " (name, description, appliedAt) VALUES (?, ?, ?)"
       ).run(file, mig.description || "", new Date().toISOString());
       runSql(database, "COMMIT");
     } catch (e) {

package/lib/external-db.js

@@ -54,6 +54,7 @@ var retryHelper = require("./retry");
 var C = require("./constants");
 var lazyRequire = require("./lazy-require");
 var safeAsync = require("./safe-async");
+var safeSql = require("./safe-sql");
 var { ExternalDbError } = require("./framework-error");
 
 var audit = lazyRequire(function () { return require("./audit"); });
@@ -187,6 +188,9 @@ function init(opts) {
       residencyTag:    cfg.residencyTag || "unrestricted",
       breaker:         new retryHelper.CircuitBreaker("externalDb:" + name, cfg.breaker),
       retryConfig:     cfg.retry || null,
+      replicas:        _buildReplicas(name, cfg),
+      replicaIdx:      0,    // round-robin cursor
+      replicaFallbackToPrimary: cfg.replicaFallbackToPrimary !== false,
     };
   }
 
@@ -380,6 +384,12 @@ async function shutdown() {
   if (!initialized) return;
   for (var name in backends) {
     try { await backends[name].pool.drain(); } catch (_e) { /* best effort */ }
+    var bk = backends[name];
+    if (bk && bk.replicas) {
+      for (var i = 0; i < bk.replicas.length; i++) {
+        try { await bk.replicas[i].pool.drain(); } catch (_e) { /* best effort */ }
+      }
+    }
   }
   backends = {};
   defaultBackend = null;
@@ -400,9 +410,173 @@ function _requireInit() {
   if (!initialized) throw _err("NOT_INITIALIZED", "externalDb.init() must be called first", true);
 }
 
+// ---- Read-replica routing ----
+//
+// Operators with a primary + replicas declare replicas alongside the
+// primary backend config:
+//
+//   externalDb.init({
+//     backends: {
+//       main: {
+//         connect, query,                          // primary
+//         replicas: [
+//           { connect: replica1, query, weight: 1 },
+//           { connect: replica2, query, weight: 2 },
+//         ],
+//         replicaFallbackToPrimary: true,          // default; on all-replicas-unhealthy,
+//                                                  //   read.query falls back to primary
+//       },
+//     },
+//   });
+//
+//   await externalDb.read.query("SELECT * FROM users");      // → replica
+//   await externalDb.write.query("INSERT INTO users ...");    // → primary
+//   await externalDb.query("...");                            // → primary (legacy, unchanged)
+//
+// Load balancing: weighted round-robin (default weight 1). Weights
+// expand into a static plan at init — a [w1, w2, w3] vector becomes a
+// pre-built index sequence, then read.query() advances replicaIdx.
+//
+// Health: each replica tracks `lastFailureAt`. After UNHEALTHY_COOLDOWN_MS
+// since the last failure, the replica re-enters the rotation. Operators
+// observing all-replicas-down see read.query() fall back to primary
+// (overridable via replicaFallbackToPrimary: false).
+
+var REPLICA_UNHEALTHY_COOLDOWN_MS = C.TIME.seconds(30);
+
+function _buildReplicas(backendName, cfg) {
+  if (!cfg.replicas) return null;
+  if (!Array.isArray(cfg.replicas) || cfg.replicas.length === 0) {
+    throw _err("INVALID_CONFIG",
+      "backend '" + backendName + "': replicas must be a non-empty array", true);
+  }
+  var out = [];
+  for (var i = 0; i < cfg.replicas.length; i++) {
+    var r = cfg.replicas[i];
+    if (!r || typeof r.connect !== "function") {
+      throw _err("INVALID_CONFIG",
+        "backend '" + backendName + "': replicas[" + i + "].connect must be a function", true);
+    }
+    if (typeof r.query !== "function") {
+      throw _err("INVALID_CONFIG",
+        "backend '" + backendName + "': replicas[" + i + "].query must be a function", true);
+    }
+    var weight = r.weight !== undefined ? r.weight : 1;
+    if (typeof weight !== "number" || !isFinite(weight) || weight <= 0 ||
+        Math.floor(weight) !== weight) {
+      throw _err("INVALID_CONFIG",
+        "backend '" + backendName + "': replicas[" + i + "].weight must be a positive integer", true);
+    }
+    out.push({
+      index:           i,
+      pool:            new Pool(backendName + ":replica:" + i, r),
+      query:           r.query,
+      weight:          weight,
+      lastFailureAt:   0,
+      consecutiveFailures: 0,
+    });
+  }
+  return out;
+}
+
+function _pickReplica(b) {
+  if (!b.replicas || b.replicas.length === 0) return null;
+  var now = Date.now();
+  // Build a healthy candidate set.
+  var healthy = [];
+  for (var i = 0; i < b.replicas.length; i++) {
+    var r = b.replicas[i];
+    if (now - r.lastFailureAt >= REPLICA_UNHEALTHY_COOLDOWN_MS) healthy.push(r);
+  }
+  if (healthy.length === 0) return null;
+  // Weighted round-robin: walk by weight, advancing replicaIdx by 1 each
+  // call and modding by total weight. Each replica's "slot" in the
+  // sequence repeats `weight` times.
+  var totalWeight = 0;
+  for (var w = 0; w < healthy.length; w++) totalWeight += healthy[w].weight;
+  var cursor = (b.replicaIdx++) % totalWeight;
+  var acc = 0;
+  for (var c = 0; c < healthy.length; c++) {
+    acc += healthy[c].weight;
+    if (cursor < acc) return healthy[c];
+  }
+  return healthy[0];   // unreachable; defensive
+}
+
+async function _readQuery(sql, params, opts) {
+  _requireInit();
+  opts = opts || {};
+  var b = _pickBackend(opts);
+  if (!b.replicas || b.replicas.length === 0) {
+    // No replicas configured — read.query() returns primary.
+    return query(sql, params, opts);
+  }
+  var replica = _pickReplica(b);
+  if (!replica) {
+    if (b.replicaFallbackToPrimary) return query(sql, params, opts);
+    throw _err("ALL_REPLICAS_UNHEALTHY",
+      "backend '" + b.name + "': all replicas unhealthy and fallback disabled", true);
+  }
+  var t0 = Date.now();
+  try {
+    var client = await replica.pool.acquire();
+    try {
+      var res = await replica.query(client, sql, params || []);
+      replica.pool.release(client);
+      replica.consecutiveFailures = 0;
+      _emit("system.externaldb.read", "success", {
+        backend:    b.name,
+        replicaIdx: replica.index,
+        durationMs: Date.now() - t0,
+        rowCount:   res && res.rowCount,
+      });
+      return res;
+    } catch (e) {
+      // Connection-shape errors mark unhealthy + destroy.
+      if (e && (e.code === "ECONNRESET" || e.code === "ECONNREFUSED" ||
+                e.code === "ETIMEDOUT" || e.code === "ENOTFOUND" ||
+                e.code === "EPIPE")) {
+        await replica.pool.destroy(client);
+        replica.lastFailureAt = Date.now();
+        replica.consecutiveFailures += 1;
+      } else {
+        replica.pool.release(client);
+      }
+      throw e;
+    }
+  } catch (e) {
+    _emit("system.externaldb.read", "failure", {
+      backend:    b.name,
+      replicaIdx: replica.index,
+      durationMs: Date.now() - t0,
+      errorCode:  e.code || null,
+    }, (e && e.message) || String(e));
+    // Fallback to primary on a failed replica read when allowed.
+    if (b.replicaFallbackToPrimary) {
+      return query(sql, params, opts);
+    }
+    throw e;
+  }
+}
+
+var read = {
+  query: _readQuery,
+};
+
+// write namespace — alias for the primary path. Lets operators express
+// intent symmetrically with read.query without a magic-comment hint.
+var write = {
+  query:       function (sql, params, opts) { return query(sql, params, opts); },
+  transaction: function (fn, opts) { return transaction(fn, opts); },
+};
+
 function _resetForTest() {
   Object.keys(backends).forEach(function (n) {
     try { backends[n].pool.drain(); } catch (_e) {}
+    var bk = backends[n];
+    if (bk && bk.replicas) {
+      bk.replicas.forEach(function (r) { try { r.pool.drain(); } catch (_e) {} });
+    }
   });
   backends = {};
   defaultBackend = null;
@@ -411,6 +585,198 @@ function _resetForTest() {
   db.reset();
 }
 
+// ---- configurePool — runtime resize of an existing backend's pool ----
+//
+// Operators tune pool sizing without restarting the app. Existing idle
+// clients are kept; new acquisitions respect the new max. min is honored
+// the next time the pool refills. idleTimeoutMs takes effect on the next
+// reaper tick.
+function configurePool(backendName, opts) {
+  _requireInit();
+  if (typeof backendName !== "string" || backendName.length === 0) {
+    throw _err("INVALID_CONFIG", "configurePool: backendName must be a non-empty string", true);
+  }
+  var bk = backends[backendName];
+  if (!bk) throw _err("UNKNOWN_BACKEND", "configurePool: no backend named '" + backendName + "'", true);
+  if (!opts || typeof opts !== "object") {
+    throw _err("INVALID_CONFIG", "configurePool: opts must be an object", true);
+  }
+  var allowed = ["min", "max", "idleTimeoutMs"];
+  for (var k in opts) {
+    if (!Object.prototype.hasOwnProperty.call(opts, k)) continue;
+    if (allowed.indexOf(k) === -1) {
+      throw _err("INVALID_CONFIG",
+        "configurePool: unknown option '" + k + "'. Allowed: " + allowed.join(", "), true);
+    }
+  }
+  function _requirePosInt(name, value) {
+    if (typeof value !== "number" || !isFinite(value) || value <= 0 || Math.floor(value) !== value) {
+      throw _err("INVALID_CONFIG",
+        "configurePool: " + name + " must be a positive integer, got " + JSON.stringify(value), true);
+    }
+  }
+  if (opts.min           !== undefined) _requirePosInt("min", opts.min);
+  if (opts.max           !== undefined) _requirePosInt("max", opts.max);
+  if (opts.idleTimeoutMs !== undefined) _requirePosInt("idleTimeoutMs", opts.idleTimeoutMs);
+  if (opts.min !== undefined && opts.max !== undefined && opts.min > opts.max) {
+    throw _err("INVALID_CONFIG", "configurePool: min must be <= max", true);
+  }
+  Object.assign(bk.pool.config, opts);
+}
+
+// ---- adapters.connectAs — Postgres role-aware connect wrapper ----
+//
+// Wraps an operator's connect() so that every fresh client runs
+// `SET ROLE`, `SET search_path`, `SET application_name`, and any other
+// operator-supplied GUCs at acquire time. The pattern enables the
+// search_path-views shape: the same SQL `SELECT * FROM sessions`
+// resolves to `public.sessions` for app_user and to
+// `analytics.sessions` (a view with PHI redacted) for analytics_user.
+// See the "Compliance Patterns" wiki page.
+//
+// Identifier inputs (role, schemas in searchPath) are validated via
+// safeSql.validateIdentifier — bad shapes throw at the call site. String
+// values (applicationName, statement_timeout) are quoted as SQL string
+// literals with single-quote escaping per the SQL standard.
+//
+//   connect: b.externalDb.adapters.connectAs(rawConnect, {
+//     role:               "analytics_user",
+//     searchPath:         ["analytics", "public"],
+//     applicationName:    "wiki:analytics",
+//     statementTimeoutMs: C.TIME.seconds(30),
+//     gucs: {
+//       idle_in_transaction_session_timeout: "60s",
+//     },
+//   })
+//
+// `query` is the same query function the backend declares; the wrapper
+// uses it to issue the SET statements.
+function _connectAs(rawConnect, query, opts) {
+  if (typeof rawConnect !== "function") {
+    throw _err("INVALID_CONFIG", "connectAs: connect must be a function", true);
+  }
+  if (typeof query !== "function") {
+    throw _err("INVALID_CONFIG", "connectAs: query must be a function", true);
+  }
+  opts = opts || {};
+  var allowed = ["role", "searchPath", "applicationName", "statementTimeoutMs", "gucs"];
+  for (var k in opts) {
+    if (!Object.prototype.hasOwnProperty.call(opts, k)) continue;
+    if (allowed.indexOf(k) === -1) {
+      throw _err("INVALID_CONFIG",
+        "connectAs: unknown option '" + k + "'. Allowed: " + allowed.join(", "), true);
+    }
+  }
+
+  // Validate inputs at config time so a malformed name surfaces at
+  // boot rather than on the first connection.
+  if (opts.role !== undefined) {
+    safeSql.validateIdentifier(String(opts.role), { allowReserved: false });
+  }
+  var pathSegments = null;
+  if (opts.searchPath !== undefined) {
+    var raw = Array.isArray(opts.searchPath) ? opts.searchPath : [opts.searchPath];
+    if (raw.length === 0) {
+      throw _err("INVALID_CONFIG", "connectAs: searchPath must have at least one schema", true);
+    }
+    pathSegments = [];
+    for (var pi = 0; pi < raw.length; pi++) {
+      safeSql.validateIdentifier(String(raw[pi]), { allowReserved: false });
+      pathSegments.push(String(raw[pi]));
+    }
+  }
+  if (opts.applicationName !== undefined && typeof opts.applicationName !== "string") {
+    throw _err("INVALID_CONFIG", "connectAs: applicationName must be a string", true);
+  }
+  if (opts.statementTimeoutMs !== undefined) {
+    if (typeof opts.statementTimeoutMs !== "number" || !isFinite(opts.statementTimeoutMs) ||
+        opts.statementTimeoutMs <= 0 || Math.floor(opts.statementTimeoutMs) !== opts.statementTimeoutMs) {
+      throw _err("INVALID_CONFIG",
+        "connectAs: statementTimeoutMs must be a positive integer", true);
+    }
+  }
+  if (opts.gucs !== undefined && (typeof opts.gucs !== "object" || opts.gucs === null)) {
+    throw _err("INVALID_CONFIG", "connectAs: gucs must be an object", true);
+  }
+  if (opts.gucs) {
+    for (var gname in opts.gucs) {
+      // GUC names: Postgres NAMEDATALEN-shaped identifiers.
+      safeSql.validateIdentifier(gname, { allowReserved: true });
+    }
+  }
+
+  // Pre-compute the SET statements once — every fresh client runs the
+  // same list, so building it per-connect would burn microbenchmarks.
+  var stmts = [];
+  if (opts.role) {
+    stmts.push('SET ROLE "' + opts.role + '"');
+  }
+  if (pathSegments) {
+    var pathSql = pathSegments.map(function (s) { return '"' + s + '"'; }).join(", ");
+    stmts.push("SET search_path TO " + pathSql);
+  }
+  if (opts.applicationName !== undefined) {
+    // Single-quoted string literal — SQL-standard escape doubles embedded
+    // single quotes.
+    var an = String(opts.applicationName).replace(/'/g, "''");
+    stmts.push("SET application_name TO '" + an + "'");
+  }
+  if (opts.statementTimeoutMs !== undefined) {
+    stmts.push("SET statement_timeout TO " + opts.statementTimeoutMs);
+  }
+  if (opts.gucs) {
+    for (var gn in opts.gucs) {
+      var gv = opts.gucs[gn];
+      if (typeof gv === "number") {
+        stmts.push('SET "' + gn + '" TO ' + gv);
+      } else {
+        var gvs = String(gv).replace(/'/g, "''");
+        stmts.push('SET "' + gn + '" TO \'' + gvs + "'");
+      }
+    }
+  }
+
+  return async function wrappedConnect() {
+    var client = await rawConnect();
+    try {
+      for (var i = 0; i < stmts.length; i++) {
+        await query(client, stmts[i], []);
+      }
+    } catch (e) {
+      // Initialization failed — the operator's close hook isn't visible
+      // here, so we throw and let the pool's catch destroy the partial
+      // client.
+      throw e;
+    }
+    return client;
+  };
+}
+
+// Operators import the helper as `b.externalDb.adapters.connectAs(connect, opts)`
+// — declarative wrapping with shared input validation.
+function _adaptersConnectAs(connect, opts) {
+  // The backend's query function is needed to issue SET statements on a
+  // freshly-acquired client. Operators pass it via opts.query — same
+  // function they declare on the backend itself.
+  if (!opts || typeof opts !== "object") {
+    throw _err("INVALID_CONFIG",
+      "adapters.connectAs: opts must be an object", true);
+  }
+  if (typeof opts.query !== "function") {
+    throw _err("INVALID_CONFIG",
+      "adapters.connectAs: opts.query is required (the backend's query function)", true);
+  }
+  // Pull query off and pass the remaining role-aware opts.
+  var query = opts.query;
+  var roleOpts = {};
+  for (var k in opts) {
+    if (Object.prototype.hasOwnProperty.call(opts, k) && k !== "query") {
+      roleOpts[k] = opts[k];
+    }
+  }
+  return _connectAs(connect, query, roleOpts);
+}
+
 module.exports = {
   init:           init,
   query:          query,
@@ -418,6 +784,12 @@ module.exports = {
   healthCheck:    healthCheck,
   listBackends:   listBackends,
   shutdown:       shutdown,
+  configurePool:  configurePool,
+  read:           read,
+  write:          write,
+  adapters: {
+    connectAs:    _adaptersConnectAs,
+  },
   Pool:           Pool,
   _resetForTest:  _resetForTest,
 };

package/lib/http-client.js

@@ -122,13 +122,62 @@ var _transports = new Map();
 // idle sockets reaped quickly between bursts. ecdhCurve / minVersion
 // come from pqc-agent and cannot be set here — the framework's
 // PQC-only TLS posture is one place, in lib/pqc-agent.js.
-var HTTP_CLIENT_AGENT_OPTS = {
+//
+// Operators tune at boot via `b.httpClient.configurePool({...})`.
+// Existing transports stay on whichever values were active when they
+// were created — reconfigure runs before any outbound request to take
+// effect on the per-origin cache.
+var DEFAULT_AGENT_OPTS = Object.freeze({
   keepAlive:        true,
   keepAliveMsecs:   1000,
   maxSockets:       16,
   maxFreeSockets:   8,
   scheduling:       "lifo",
-};
+});
+
+var HTTP_CLIENT_AGENT_OPTS = Object.assign({}, DEFAULT_AGENT_OPTS);
+
+function configurePool(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new Error("httpClient.configurePool: opts must be an object");
+  }
+  var allowed = ["keepAlive", "keepAliveMsecs", "maxSockets", "maxFreeSockets", "scheduling"];
+  for (var k in opts) {
+    if (!Object.prototype.hasOwnProperty.call(opts, k)) continue;
+    if (allowed.indexOf(k) === -1) {
+      throw new Error("httpClient.configurePool: unknown option '" + k +
+        "'. Allowed: " + allowed.join(", "));
+    }
+  }
+  function _requirePositiveInt(name, value) {
+    if (typeof value !== "number" || !isFinite(value) || value <= 0 || Math.floor(value) !== value) {
+      throw new Error("httpClient.configurePool: " + name +
+        " must be a positive integer, got " + JSON.stringify(value));
+    }
+  }
+  if (opts.maxSockets     !== undefined) _requirePositiveInt("maxSockets",     opts.maxSockets);
+  if (opts.maxFreeSockets !== undefined) _requirePositiveInt("maxFreeSockets", opts.maxFreeSockets);
+  if (opts.keepAliveMsecs !== undefined) _requirePositiveInt("keepAliveMsecs", opts.keepAliveMsecs);
+  if (opts.keepAlive      !== undefined && typeof opts.keepAlive !== "boolean") {
+    throw new Error("httpClient.configurePool: keepAlive must be a boolean");
+  }
+  if (opts.scheduling     !== undefined && opts.scheduling !== "lifo" && opts.scheduling !== "fifo") {
+    throw new Error("httpClient.configurePool: scheduling must be 'lifo' or 'fifo'");
+  }
+  Object.assign(HTTP_CLIENT_AGENT_OPTS, opts);
+  // Existing transports keep their old values (Agent constructor
+  // copies). Drop the per-origin cache + tear down idle sockets so
+  // subsequent requests build fresh transports with the new opts.
+  _transports.forEach(function (t) {
+    if (t && t.kind === "h1" && t.agent && typeof t.agent.destroy === "function") {
+      try { t.agent.destroy(); } catch (_e) {}
+    }
+    if (t && t.kind === "h2" && t.session && typeof t.session.close === "function") {
+      try { t.session.close(); } catch (_e) {}
+    }
+  });
+  _transports.clear();
+}
 
 // h2 session connect options. Same TLS posture as h1 Agent.
 var DEFAULT_H2_TLS_OPTS = {
@@ -1026,8 +1075,10 @@ function _getCachedTransportKind(url) {
 
 module.exports = {
   request:                    request,
+  configurePool:              configurePool,
   DEFAULT_CONTROL_PLANE_CAP:  DEFAULT_CONTROL_PLANE_CAP,
   DEFAULT_GET_CAP:            DEFAULT_GET_CAP,
+  DEFAULT_AGENT_OPTS:         DEFAULT_AGENT_OPTS,
   _resetForTest:              _resetForTest,
   _getCachedTransportCount:   _getCachedTransportCount,
   _getCachedTransportKind:    _getCachedTransportKind,

package/lib/middleware/body-parser.js

@@ -203,12 +203,31 @@ function _typeMatches(actual, allowed) {
   return false;
 }
 
+// RFC 9112 §6.1: Content-Length MUST be a sequence of decimal digits with
+// no whitespace, sign, or trailing garbage. parseInt("123abc") returning
+// 123 is the lenient parse that lets malformed headers slip past the
+// preflight cap; the strict regex catches them at the boundary.
+var STRICT_CONTENT_LENGTH = /^\d+$/;
+
+function _parseContentLength(cl) {
+  if (typeof cl !== "string" || !STRICT_CONTENT_LENGTH.test(cl)) return null;
+  var n = Number(cl);
+  return isFinite(n) ? n : null;
+}
+
 function _hasBody(req) {
   if (!BODY_BEARING_METHODS.has(req.method)) return false;
   var cl = req.headers && req.headers["content-length"];
-  if (cl === "0") return false;
-  // Either Content-Length > 0 OR Transfer-Encoding: chunked → there's a body.
-  if (typeof cl === "string" && cl !== "0") return true;
+  if (typeof cl === "string") {
+    var clNum = _parseContentLength(cl);
+    // Spec-shaped zero (the only RFC 9112 §6.1 zero) → no body. Malformed
+    // values (non-decimal-digits) flow through as "yes, has body" so the
+    // downstream _bufferBody call rejects with 400 — silently treating
+    // a malformed header as "no body" would let the request slip past
+    // the parser entirely.
+    if (clNum === 0) return false;
+    return true;
+  }
   var te = req.headers && req.headers["transfer-encoding"];
   if (typeof te === "string" && te.length > 0) return true;
   return false;
@@ -230,14 +249,22 @@ function _bufferBody(req, limit) {
   return new Promise(function (resolve, reject) {
     var cl = req.headers && req.headers["content-length"];
     if (typeof cl === "string") {
-      var clNum = parseInt(cl, 10);
-      if (!isNaN(clNum) && clNum > limit) {
-        var err = new BodyParserError(
+      var clNum = _parseContentLength(cl);
+      if (clNum === null) {
+        // RFC 9112 §6.1 — malformed Content-Length is a 400.
+        reject(new BodyParserError(
+          "body-parser/bad-content-length",
+          "Content-Length is not a sequence of decimal digits: " + JSON.stringify(cl),
+          true, 400
+        ));
+        return;
+      }
+      if (clNum > limit) {
+        reject(new BodyParserError(
           "body-parser/too-large",
           "request body exceeds limit (" + clNum + " > " + limit + ")",
           true, 413
-        );
-        reject(err);
+        ));
         return;
       }
     }

package/lib/middleware/cors.js

@@ -67,12 +67,26 @@ function _xffIpFor(trustProxy) {
 
 var CorsError = defineClass("CorsError", { alwaysPermanent: true });
 
+// allowList entries:
+//   - { kind: "string", canonical: "https://app.example.com", original: "..." }
+//   - { kind: "regex",  pattern: /.../  }
+// Both raw entry and the inbound origin run through _canonicalOrigin
+// before equality so case differences ("https://APP" vs "https://app")
+// and default-port differences ("https://x:443" vs "https://x") match.
 function _matchOrigin(origin, allowList) {
   if (!origin) return null;
+  var canon = _canonicalOrigin(origin);
   for (var i = 0; i < allowList.length; i++) {
     var entry = allowList[i];
-    if (typeof entry === "string" && entry === origin) return origin;
-    if (entry instanceof RegExp && entry.test(origin)) return origin;
+    if (entry.kind === "string") {
+      if (canon !== null && entry.canonical === canon) return origin;
+    } else if (entry.kind === "regex") {
+      // Regex entries match against the raw origin (operator wrote the
+      // pattern with whatever case / port shape they intended). Also try
+      // the canonical form so case-insensitive intent works without /i.
+      if (entry.pattern.test(origin)) return origin;
+      if (canon !== null && entry.pattern.test(canon)) return origin;
+    }
   }
   return null;
 }
@@ -153,12 +167,25 @@ function create(opts) {
     ? opts.trustProxy : false;
   var _xffIp = _xffIpFor(trustProxy);
 
-  var origins = opts.origins || [];
-
-  // Tier A validation on opts.origins — strings or RegExp only.
-  for (var oi = 0; oi < origins.length; oi++) {
-    var entry = origins[oi];
-    if (typeof entry !== "string" && !(entry instanceof RegExp)) {
+  // Build a canonicalized allowList at create() time. String entries
+  // get parsed through _canonicalOrigin so case + default-port
+  // differences match consistently between the configured value and
+  // the inbound Origin header. RegExp entries stay as the operator
+  // wrote them.
+  var rawOrigins = opts.origins || [];
+  var origins = [];
+  for (var oi = 0; oi < rawOrigins.length; oi++) {
+    var entry = rawOrigins[oi];
+    if (typeof entry === "string") {
+      var canonEntry = _canonicalOrigin(entry);
+      if (canonEntry === null) {
+        throw new CorsError("cors/bad-origin",
+          "origins[" + oi + "]='" + entry + "' is not a parseable http(s) URL");
+      }
+      origins.push({ kind: "string", canonical: canonEntry, original: entry });
+    } else if (entry instanceof RegExp) {
+      origins.push({ kind: "regex", pattern: entry });
+    } else {
       throw new CorsError("cors/bad-origin",
         "origins[" + oi + "] must be a string or RegExp (got " + typeof entry + ")");
     }

package/lib/migrations.js

@@ -55,6 +55,10 @@ class MigrationError extends FrameworkError {
 }
 
 var MIGRATIONS_TABLE = "_blamejs_migrations";
+// Always interpolate identifiers wrapped in `"..."` so a reserved-word
+// or whitespace-bearing name resolves correctly (defense-in-depth even
+// though our constant is bare-identifier-shaped).
+var Q_MIGRATIONS_TABLE = '"' + MIGRATIONS_TABLE + '"';
 // Filename grammar: leading numeric prefix (any width), then '-', then a
 // non-empty body, then '.js'. Numeric prefix orders execution. Letters
 // in the body include hyphens, underscores, and alphanumerics; anything
@@ -68,7 +72,7 @@ function _runSql(db, sql) { return db["exec"](sql); }
 
 function _ensureTable(db) {
   _runSql(db,
-    "CREATE TABLE IF NOT EXISTS " + MIGRATIONS_TABLE + " (" +
+    "CREATE TABLE IF NOT EXISTS " + Q_MIGRATIONS_TABLE + " (" +
     "  name        TEXT PRIMARY KEY," +
     "  description TEXT," +
     "  appliedAt   TEXT NOT NULL" +
@@ -80,11 +84,12 @@ function _ensureTable(db) {
 // concurrently against the same DB race on this table: the winner of
 // the INSERT acquires the lock; the loser sees a UNIQUE violation and
 // the operator gets a clear "lock held by other process" error.
-var LOCK_TABLE = "_blamejs_migrations_lock";
+var LOCK_TABLE   = "_blamejs_migrations_lock";
+var Q_LOCK_TABLE = '"' + LOCK_TABLE + '"';
 
 function _ensureLockTable(db) {
   _runSql(db,
-    "CREATE TABLE IF NOT EXISTS " + LOCK_TABLE + " (" +
+    "CREATE TABLE IF NOT EXISTS " + Q_LOCK_TABLE + " (" +
     "  scope     TEXT PRIMARY KEY," +
     "  lockedAt  INTEGER NOT NULL," +
     "  lockedBy  TEXT NOT NULL," +
@@ -108,19 +113,19 @@ function _acquireLock(db, opts) {
   // Try to insert; if there's a stale lock, optionally force-replace it.
   try {
     db.prepare(
-      "INSERT INTO " + LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
+      "INSERT INTO " + Q_LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
     ).run(nowMs, holder);
     return holder;
   } catch {
     // PRIMARY KEY conflict → existing lock. Inspect it.
     var existing = db.prepare(
-      "SELECT lockedAt, lockedBy FROM " + LOCK_TABLE + " WHERE scope = 'lock'"
+      "SELECT lockedAt, lockedBy FROM " + Q_LOCK_TABLE + " WHERE scope = 'lock'"
     ).get();
     if (!existing) {
       // Race window between INSERT failure and SELECT — try once more.
       try {
         db.prepare(
-          "INSERT INTO " + LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
+          "INSERT INTO " + Q_LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
         ).run(nowMs, holder);
         return holder;
       } catch (e2) {
@@ -135,10 +140,10 @@ function _acquireLock(db, opts) {
       // single transaction so the next process can't slip in between.
       _runSql(db, "BEGIN IMMEDIATE");
       try {
-        db.prepare("DELETE FROM " + LOCK_TABLE + " WHERE scope = 'lock' AND lockedAt = ?")
+        db.prepare("DELETE FROM " + Q_LOCK_TABLE + " WHERE scope = 'lock' AND lockedAt = ?")
           .run(existing.lockedAt);
         db.prepare(
-          "INSERT INTO " + LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
+          "INSERT INTO " + Q_LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
         ).run(nowMs, holder);
         _runSql(db, "COMMIT");
         return holder;
@@ -163,7 +168,7 @@ function _releaseLock(db, holder) {
   // the operator explicitly used the staleAfterMs path.
   try {
     db.prepare(
-      "DELETE FROM " + LOCK_TABLE + " WHERE scope = 'lock' AND lockedBy = ?"
+      "DELETE FROM " + Q_LOCK_TABLE + " WHERE scope = 'lock' AND lockedBy = ?"
     ).run(holder);
   } catch (_e) { /* best-effort release; operator can DELETE manually */ }
 }
@@ -240,7 +245,7 @@ function create(opts) {
     var db = _resolveDb(opts);
     _ensureTable(db);
     return db.prepare(
-      "SELECT name, description, appliedAt FROM " + MIGRATIONS_TABLE +
+      "SELECT name, description, appliedAt FROM " + Q_MIGRATIONS_TABLE +
       " ORDER BY appliedAt ASC, name ASC"
     ).all();
   }
@@ -262,7 +267,7 @@ function create(opts) {
     _ensureTable(db);
     return _withLock(db, opts, function () {
       var appliedSet = new Set(
-        db.prepare("SELECT name FROM " + MIGRATIONS_TABLE).all()
+        db.prepare("SELECT name FROM " + Q_MIGRATIONS_TABLE).all()
           .map(function (r) { return r.name; })
       );
       var files = _list(dir);
@@ -276,7 +281,7 @@ function create(opts) {
           _txn(db, function () {
             mod.up(db);
             db.prepare(
-              "INSERT INTO " + MIGRATIONS_TABLE +
+              "INSERT INTO " + Q_MIGRATIONS_TABLE +
               " (name, description, appliedAt) VALUES (?, ?, ?)"
             ).run(file, mod.description || "", new Date().toISOString());
           });
@@ -306,7 +311,7 @@ function create(opts) {
       // then by name as a stable tiebreaker for fixtures with identical
       // timestamps).
       var rows = db.prepare(
-        "SELECT name FROM " + MIGRATIONS_TABLE +
+        "SELECT name FROM " + Q_MIGRATIONS_TABLE +
         " ORDER BY appliedAt DESC, name DESC LIMIT ?"
       ).all(steps);
 
@@ -323,7 +328,7 @@ function create(opts) {
         try {
           _txn(db, function () {
             mod.down(db);
-            db.prepare("DELETE FROM " + MIGRATIONS_TABLE + " WHERE name = ?").run(file);
+            db.prepare("DELETE FROM " + Q_MIGRATIONS_TABLE + " WHERE name = ?").run(file);
           });
         } catch (e) {
           throw new MigrationError("migrations/down-failed",

package/lib/safe-sql.js

@@ -124,6 +124,43 @@ 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"'
+function quoteQualified(parts, dialect) {
+  var arr;
+  if (typeof parts === "string") {
+    if (parts.length === 0) {
+      throw new SafeSqlError("qualified name must not be empty", "sql/empty");
+    }
+    arr = parts.split(".");
+  } else if (Array.isArray(parts)) {
+    arr = parts.slice();
+  } else {
+    throw new SafeSqlError(
+      "qualified name must be a string or array, got " + typeof parts,
+      "sql/bad-type"
+    );
+  }
+  if (arr.length === 0) {
+    throw new SafeSqlError("qualified name must have at least one segment", "sql/empty");
+  }
+  var quoted = [];
+  for (var i = 0; i < arr.length; i++) {
+    quoted.push(quoteIdentifier(arr[i], dialect));
+  }
+  return quoted.join(".");
+}
+
 function assertOneOf(name, allowlist) {
   if (typeof name !== "string") {
     throw new SafeSqlError("name must be a string", "sql/bad-type");
@@ -149,6 +186,7 @@ function assertOneOf(name, allowlist) {
 module.exports = {
   validateIdentifier:  validateIdentifier,
   quoteIdentifier:     quoteIdentifier,
+  quoteQualified:      quoteQualified,
   assertOneOf:         assertOneOf,
   SafeSqlError:        SafeSqlError,
   // Exposed so consumers can compose their own validators

package/lib/seeders.js

@@ -68,6 +68,11 @@ var _err = SeederError.factory;
 
 var SEEDERS_TABLE = "_blamejs_seeders";
 var LOCK_TABLE    = "_blamejs_seeders_lock";
+// Pre-quoted forms used at every SQL interpolation site — defense in
+// depth so a future rename to a reserved-word or whitespace-bearing
+// table name doesn't silently break the query.
+var Q_SEEDERS_TABLE = '"' + SEEDERS_TABLE + '"';
+var Q_LOCK_TABLE    = '"' + LOCK_TABLE    + '"';
 
 // Filename grammar: leading numeric prefix (any width), '-', non-empty
 // body of [A-Za-z0-9_-], '.js'. Same shape as migrations to avoid
@@ -285,7 +290,7 @@ function _ensureTables(db) {
   // EXISTS here is defensive for tests that hand-seed a fresh
   // node:sqlite Database without going through b.db.
   _runSql(db,
-    "CREATE TABLE IF NOT EXISTS " + SEEDERS_TABLE + " (" +
+    "CREATE TABLE IF NOT EXISTS " + Q_SEEDERS_TABLE + " (" +
     "  env         TEXT NOT NULL," +
     "  name        TEXT NOT NULL," +
     "  description TEXT," +
@@ -295,7 +300,7 @@ function _ensureTables(db) {
     ")"
   );
   _runSql(db,
-    "CREATE TABLE IF NOT EXISTS " + LOCK_TABLE + " (" +
+    "CREATE TABLE IF NOT EXISTS " + Q_LOCK_TABLE + " (" +
     "  scope     TEXT PRIMARY KEY CHECK (scope = 'lock')," +
     "  lockedAt  INTEGER NOT NULL," +
     "  lockedBy  TEXT NOT NULL" +
@@ -312,18 +317,18 @@ function _acquireLock(db, lockStaleAfterMs, clock) {
   var nowMs = clock();
   try {
     db.prepare(
-      "INSERT INTO " + LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
+      "INSERT INTO " + Q_LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
     ).run(nowMs, holder);
     return holder;
   } catch (_e) {
     var existing = db.prepare(
-      "SELECT lockedAt, lockedBy FROM " + LOCK_TABLE + " WHERE scope = 'lock'"
+      "SELECT lockedAt, lockedBy FROM " + Q_LOCK_TABLE + " WHERE scope = 'lock'"
     ).get();
     if (!existing) {
       // Race window between INSERT failure and SELECT — try once more.
       try {
         db.prepare(
-          "INSERT INTO " + LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
+          "INSERT INTO " + Q_LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
         ).run(nowMs, holder);
         return holder;
       } catch (e2) {
@@ -335,10 +340,10 @@ function _acquireLock(db, lockStaleAfterMs, clock) {
     if (lockStaleAfterMs > 0 && ageMs > lockStaleAfterMs) {
       _runSql(db, "BEGIN IMMEDIATE");
       try {
-        db.prepare("DELETE FROM " + LOCK_TABLE + " WHERE scope = 'lock' AND lockedAt = ?")
+        db.prepare("DELETE FROM " + Q_LOCK_TABLE + " WHERE scope = 'lock' AND lockedAt = ?")
           .run(existing.lockedAt);
         db.prepare(
-          "INSERT INTO " + LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
+          "INSERT INTO " + Q_LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
         ).run(nowMs, holder);
         _runSql(db, "COMMIT");
         return holder;
@@ -358,7 +363,7 @@ function _acquireLock(db, lockStaleAfterMs, clock) {
 function _releaseLock(db, holder) {
   try {
     db.prepare(
-      "DELETE FROM " + LOCK_TABLE + " WHERE scope = 'lock' AND lockedBy = ?"
+      "DELETE FROM " + Q_LOCK_TABLE + " WHERE scope = 'lock' AND lockedBy = ?"
     ).run(holder);
   } catch (_e) { /* best-effort */ }
 }
@@ -409,7 +414,7 @@ function create(opts) {
 
   function _appliedRows(db, env) {
     return db.prepare(
-      "SELECT name, description, appliedAt, rerunnable FROM " + SEEDERS_TABLE +
+      "SELECT name, description, appliedAt, rerunnable FROM " + Q_SEEDERS_TABLE +
       " WHERE env = ? ORDER BY appliedAt ASC, name ASC"
     ).all(env);
   }
@@ -472,7 +477,7 @@ function create(opts) {
     var holder = _acquireLock(db, lockStaleAfterMs, clock);
     try {
       var appliedSet = new Set(
-        db.prepare("SELECT name FROM " + SEEDERS_TABLE + " WHERE env = ?").all(env)
+        db.prepare("SELECT name FROM " + Q_SEEDERS_TABLE + " WHERE env = ?").all(env)
           .map(function (r) { return r.name; })
       );
 
@@ -507,21 +512,21 @@ function create(opts) {
               await mod.run(db, ctx);
               if (alreadyApplied && mod.rerunnable) {
                 db.prepare(
-                  "UPDATE " + SEEDERS_TABLE +
+                  "UPDATE " + Q_SEEDERS_TABLE +
                   " SET appliedAt = ?, description = ?, rerunnable = ?" +
                   " WHERE env = ? AND name = ?"
                 ).run(new Date(clock()).toISOString(), mod.description || "",
                       mod.rerunnable ? 1 : 0, env, name);
               } else if (alreadyApplied && force) {
                 db.prepare(
-                  "UPDATE " + SEEDERS_TABLE +
+                  "UPDATE " + Q_SEEDERS_TABLE +
                   " SET appliedAt = ?, description = ?" +
                   " WHERE env = ? AND name = ?"
                 ).run(new Date(clock()).toISOString(), mod.description || "",
                       env, name);
               } else {
                 db.prepare(
-                  "INSERT INTO " + SEEDERS_TABLE +
+                  "INSERT INTO " + Q_SEEDERS_TABLE +
                   " (env, name, description, appliedAt, rerunnable) VALUES (?, ?, ?, ?, ?)"
                 ).run(env, name, mod.description || "",
                       new Date(clock()).toISOString(), mod.rerunnable ? 1 : 0);

package/lib/session.js

@@ -47,6 +47,22 @@ var { SessionError } = require("./framework-error");
 var _err = SessionError.factory;
 
 var DEFAULT_TTL_MS = C.TIME.days(7);
+// Sanity bound: any session that lives longer than this is almost
+// certainly a misconfigured Infinity / oversized literal. Keeps
+// expiresAt away from epoch overflow + database-int boundary issues.
+var MAX_TTL_MS     = C.TIME.days(3650);   // ~10 years
+
+function _validateTtl(ttl, where) {
+  if (typeof ttl !== "number" || !isFinite(ttl) || ttl <= 0) {
+    throw _err("INVALID_ARG",
+      where + ": ttlMs must be a positive finite number, got " + JSON.stringify(ttl), true);
+  }
+  if (ttl > MAX_TTL_MS) {
+    throw _err("INVALID_ARG",
+      where + ": ttlMs " + ttl + " exceeds maximum " + MAX_TTL_MS + " (~10 years). " +
+      "Sessions this long suggest a misconfigured value.", true);
+  }
+}
 var SID_NAMESPACE  = "bj-session:";
 
 // Column order used for INSERT — kept as a constant so the placeholders
@@ -76,8 +92,8 @@ async function create(opts) {
   if (!opts || !opts.userId) {
     throw _err("INVALID_ARG", "session.create requires { userId }", true);
   }
-  var ttl = typeof opts.ttlMs === "number" ? opts.ttlMs : DEFAULT_TTL_MS;
-  if (ttl <= 0) throw _err("INVALID_ARG", "session.create: ttlMs must be > 0", true);
+  var ttl = opts.ttlMs !== undefined ? opts.ttlMs : DEFAULT_TTL_MS;
+  _validateTtl(ttl, "session.create");
 
   var sid       = generateToken(32);             // 64 hex chars; only place the plaintext sid lives
   var sidHash   = _hashSid(sid);
@@ -243,8 +259,11 @@ async function rotate(oldToken, opts) {
   var newSidHash   = _hashSid(newSid);
   var oldSidHash   = _hashSid(oldToken);
   var nowMs        = Date.now();
-  var newExpires   = (typeof opts.ttlMs === "number" && opts.ttlMs > 0)
-                       ? nowMs + opts.ttlMs : null;
+  var newExpires = null;
+  if (opts.ttlMs !== undefined) {
+    _validateTtl(opts.ttlMs, "session.rotate");
+    newExpires = nowMs + opts.ttlMs;
+  }
 
   var setParts = ['"sidHash" = ?', '"lastActivity" = ?'];
   var setParams = [newSidHash, nowMs];

package/package.json

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