@blamejs/core 0.6.69 → 0.7.0

package/lib/cluster-storage.js

@@ -64,6 +64,74 @@ function tableName(local) {
   return local;
 }
 
+// Precomputed rewrite table for resolveTables(). Built once at module
+// load from the static frozen frameworkSchema.LOCAL_TO_EXTERNAL mapping —
+// not from operator/request input. Order longest-first so prefix matches
+// don't collide (audit_log before audit). Identity mappings are filtered
+// out so the loop body has no no-op iterations. Framework table names
+// are entirely [A-Za-z0-9_], so a manual word-boundary scan replaces
+// the regex `\b...\b` exactly without runtime regex compilation.
+// Character-code bounds for the word-character class \w that JavaScript
+// regex `\b` uses. Stored as code-from-literal so the magic numbers are
+// self-evident at the source rather than needing a comment to decode.
+var _CC_0          = "0".charCodeAt(0);
+var _CC_9          = "9".charCodeAt(0);
+var _CC_A          = "A".charCodeAt(0);
+var _CC_Z          = "Z".charCodeAt(0);
+var _CC_UNDERSCORE = "_".charCodeAt(0);
+var _CC_a          = "a".charCodeAt(0);
+var _CC_z          = "z".charCodeAt(0);
+
+function _isWordChar(code) {
+  return (code >= _CC_0 && code <= _CC_9) ||
+         (code >= _CC_A && code <= _CC_Z) ||
+         code === _CC_UNDERSCORE          ||
+         (code >= _CC_a && code <= _CC_z);
+}
+
+function _replaceWordBoundaryAll(haystack, needle, replacement) {
+  if (haystack.length < needle.length) return haystack;
+  var out = "";
+  var cursor = 0;
+  var matched = false;
+  var idx = haystack.indexOf(needle);
+  while (idx !== -1) {
+    var beforeCode = idx === 0 ? -1 : haystack.charCodeAt(idx - 1);
+    var afterPos   = idx + needle.length;
+    var afterCode  = afterPos >= haystack.length ? -1 : haystack.charCodeAt(afterPos);
+    var leftBoundary  = beforeCode === -1 || !_isWordChar(beforeCode);
+    var rightBoundary = afterCode  === -1 || !_isWordChar(afterCode);
+    if (leftBoundary && rightBoundary) {
+      out += haystack.slice(cursor, idx) + replacement;
+      cursor = afterPos;
+      matched = true;
+      idx = haystack.indexOf(needle, cursor);
+    } else {
+      // Boundary mismatch — advance past this position by one and keep
+      // scanning. We do NOT flush partial output here; the final
+      // haystack.slice(cursor) below covers any non-rewritten tail.
+      idx = haystack.indexOf(needle, idx + 1);
+    }
+  }
+  if (!matched) return haystack;
+  return out + haystack.slice(cursor);
+}
+
+var _REWRITE_TABLE = (function () {
+  var mapping = frameworkSchema.LOCAL_TO_EXTERNAL;
+  var names = Object.keys(mapping).sort(function (a, b) {
+    return b.length - a.length;
+  });
+  var entries = [];
+  for (var i = 0; i < names.length; i++) {
+    var local = names[i];
+    var external = mapping[local];
+    if (local === external) continue;
+    entries.push({ local: local, external: external });
+  }
+  return Object.freeze(entries);
+})();
+
 // Rewrite bare table names in SQL when running in cluster mode. We only
 // touch tokens that are exactly one of the framework's known table names
 // (audit_log, consent_log, …) — anything else passes through unchanged
@@ -71,18 +139,10 @@ function tableName(local) {
 // migrations) isn't rewritten by accident.
 function resolveTables(sql) {
   if (!cluster.isClusterMode()) return sql;
-  var mapping = frameworkSchema.LOCAL_TO_EXTERNAL;
-  // Order longest-first so prefix matches don't collide (audit_log
-  // before audit). Match on word boundaries so we don't rewrite a
-  // suffix of a longer identifier.
-  var localNames = Object.keys(mapping).sort(function (a, b) { return b.length - a.length; });
   var translated = sql;
-  for (var i = 0; i < localNames.length; i++) {
-    var local = localNames[i];
-    var external = mapping[local];
-    if (local === external) continue;          // identity mapping — no-op
-    var re = new RegExp("\\b" + local.replace(/[\\.-]/g, "\\$&") + "\\b", "g");
-    translated = translated.replace(re, external);
+  for (var i = 0; i < _REWRITE_TABLE.length; i++) {
+    var entry = _REWRITE_TABLE[i];
+    translated = _replaceWordBoundaryAll(translated, entry.local, entry.external);
   }
   return translated;
 }

package/lib/cluster.js

@@ -317,12 +317,13 @@ async function _checkChainTipRollback(chainName, logTable, tipTable) {
     : 0;
 
   if (currentMax < tipCounter) {
-    log.error("FATAL: cluster-mode " + chainName + "-log rollback detected.");
-    log.error("  " + chainName + "-tip counter:    " + tipCounter);
-    log.error("  current external-db max:  " + currentMax);
-    log.error("Either external-db was restored from an older snapshot, or " +
-      logTable + " rows have been deleted. Investigate before continuing.");
-    process.exit(1);
+    throw _err("ROLLBACK_DETECTED",
+      "FATAL: cluster-mode " + chainName + "-log rollback detected. " +
+      chainName + "-tip counter: " + tipCounter +
+      "; current external-db max: " + currentMax +
+      ". Either external-db was restored from an older snapshot, or " +
+      logTable + " rows have been deleted. Investigate before continuing.",
+      true);
   }
 
   if (tipHash) {
@@ -335,13 +336,14 @@ async function _checkChainTipRollback(chainName, logTable, tipTable) {
     if (hashRows.rows && hashRows.rows.length > 0) {
       var rowAtTip = hashRows.rows[0].rowHash;
       if (rowAtTip !== tipHash) {
-        log.error("FATAL: cluster-mode " + chainName + "-log rollback detected (row-hash mismatch).");
-        log.error("  " + chainName + "-tip counter:    " + tipCounter);
-        log.error("  " + chainName + "-tip rowHash:    " + tipHash);
-        log.error("  current row rowHash:    " + rowAtTip);
-        log.error("The row at the recorded tip counter has a different hash — " +
-          "indicates row substitution at the chain head. Investigate before continuing.");
-        process.exit(1);
+        throw _err("ROLLBACK_DETECTED",
+          "FATAL: cluster-mode " + chainName + "-log rollback detected (row-hash mismatch). " +
+          chainName + "-tip counter: " + tipCounter +
+          "; " + chainName + "-tip rowHash: " + tipHash +
+          "; current row rowHash: " + rowAtTip +
+          ". The row at the recorded tip counter has a different hash — " +
+          "indicates row substitution at the chain head. Investigate before continuing.",
+          true);
       }
     }
   }
@@ -429,25 +431,28 @@ async function _checkVaultKeyConsistency() {
   if (!rows.rows || rows.rows.length === 0) {
     // Should never happen — we just INSERTed. Surface as fatal so the
     // condition isn't silently ignored.
-    log.error("FATAL: cluster-state row missing immediately after INSERT — " +
-      "external-db may not be honoring writes. Refusing boot.");
-    process.exit(1);
+    throw _err("CLUSTER_STATE_MISSING",
+      "FATAL: cluster-state row missing immediately after INSERT — " +
+      "external-db may not be honoring writes. Refusing boot.",
+      true);
   }
   var canonical = rows.rows[0];
   if (canonical.vaultKeyFp !== localFp) {
-    log.error("FATAL: vault-key drift detected.");
-    log.error("  local node:           " + nodeId);
-    log.error("  local fingerprint:    " + localFp.slice(0, 16) + "…");
-    log.error("  canonical recorded by: " + canonical.recordedByNode);
-    log.error("  canonical fingerprint: " + canonical.vaultKeyFp.slice(0, 16) + "…");
-    log.error("This node holds a DIFFERENT vault key than the rest of the " +
+    var fpPrefix = C.BYTES.bytes(16);
+    throw _err("VAULT_KEY_DRIFT",
+      "FATAL: vault-key drift detected. " +
+      "local node: " + nodeId +
+      "; local fingerprint: " + localFp.slice(0, fpPrefix) + "…" +
+      "; canonical recorded by: " + canonical.recordedByNode +
+      "; canonical fingerprint: " + canonical.vaultKeyFp.slice(0, fpPrefix) + "…" +
+      ". This node holds a DIFFERENT vault key than the rest of the " +
       "cluster. Sealed-column writes from this node would be unreadable " +
       "by the others (and vice versa). Restore the same vault key file " +
-      "before booting this node into the cluster.");
-    process.exit(1);
+      "before booting this node into the cluster.",
+      true);
   }
   log("cluster vault-key consistency ok (fingerprint " +
-    localFp.slice(0, 16) + "… recorded by " + canonical.recordedByNode + ")");
+    localFp.slice(0, C.BYTES.bytes(16)) + "… recorded by " + canonical.recordedByNode + ")");
 }
 
 async function _tryAcquire() {

package/lib/config-drift.js

@@ -51,6 +51,7 @@ var auditSign = require("./audit-sign");
 var canonicalJson = require("./canonical-json");
 var crypto = require("./crypto");
 var lazyRequire = require("./lazy-require");
+var safeJson = require("./safe-json");
 var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
 
@@ -100,9 +101,7 @@ function create(opts) {
   validateOpts(opts, [
     "dataDir", "audit", "baseline", "criticalKeys", "ignoreKeys",
   ], "configDrift");
-  if (typeof opts.dataDir !== "string" || opts.dataDir.length === 0) {
-    throw _err("BAD_OPT", "create: opts.dataDir is required");
-  }
+  validateOpts.requireNonEmptyString(opts.dataDir, "create: opts.dataDir", ConfigDriftError, "BAD_OPT");
   var dataDir = opts.dataDir;
   var auditOn = opts.audit !== false;
   var auditInstance = (opts.audit && opts.audit !== true) ? opts.audit : null;
@@ -142,7 +141,7 @@ function create(opts) {
     try { raw = fs.readFileSync(sidecarPath, "utf8"); }
     catch (_e) { return null; }
     var parsed;
-    try { parsed = JSON.parse(raw); }
+    try { parsed = safeJson.parse(raw); }
     catch (_e) { return { unreadable: true }; }
     if (!parsed || parsed.version !== SIDECAR_VERSION) return { unreadable: true };
     if (typeof parsed.digestHex !== "string" || typeof parsed.signatureBase64 !== "string" ||

package/lib/constants.js

@@ -51,9 +51,14 @@ function _validateBytes(unit, n) {
   }
 }
 var BYTES = Object.freeze({
-  kib: function (n) { _validateBytes("kib", n); return n * 1024; },
-  mib: function (n) { _validateBytes("mib", n); return n * 1024 * 1024; },
-  gib: function (n) { _validateBytes("gib", n); return n * 1024 * 1024 * 1024; },
+  // Passthrough for protocol-fixed byte counts (32-byte salt, 16-byte
+  // nonce, 8-byte counter, etc.) — keeps every byte literal routed
+  // through C.BYTES so the codebase has a single source of truth.
+  // Equivalent to `n` but names the unit at the call site.
+  bytes: function (n) { _validateBytes("bytes", n); return n; },
+  kib:   function (n) { _validateBytes("kib",   n); return n * 1024; },
+  mib:   function (n) { _validateBytes("mib",   n); return n * 1024 * 1024; },
+  gib:   function (n) { _validateBytes("gib",   n); return n * 1024 * 1024 * 1024; },
 });
 
 // ---- Crypto envelope versioning ----

package/lib/cookies.js

@@ -72,14 +72,23 @@ var TOKEN_RE = /^[!#$%&'*+\-.0-9A-Z^_`a-z|~]+$/;
 // Reject CRLF, NUL, semicolon, comma in cookie value pre-encoding.
 var FORBIDDEN_VALUE_RE = /[\r\n\0;,]/;
 
+// Length caps applied before the regex tests so a hostile caller can't
+// stage a pathological-length input against the engine. RFC 6265 doesn't
+// pin a name/value length; browsers vary, with a practical 4 KiB total
+// envelope. The framework caps name + value to leave headroom.
+var MAX_NAME_LENGTH  = C.BYTES.bytes(256);
+var MAX_VALUE_LENGTH = C.BYTES.kib(4);
+
 function _validateName(name) {
   if (typeof name !== "string" || name.length === 0) {
     throw new CookieError("cookies/invalid-name",
       "cookie name must be a non-empty string");
   }
-  if (!TOKEN_RE.test(name)) {
+  // Length cap before the regex test — bound the engine on hostile
+  // input lengths even though the regex is anchored.
+  if (name.length > MAX_NAME_LENGTH || !TOKEN_RE.test(name)) {
     throw new CookieError("cookies/invalid-name",
-      "cookie name '" + name + "' contains forbidden characters");
+      "cookie name '" + name + "' is empty, too long, or contains forbidden characters");
   }
 }
 
@@ -88,9 +97,12 @@ function _validateValue(value) {
     throw new CookieError("cookies/invalid-value",
       "cookie value must be a string");
   }
-  if (FORBIDDEN_VALUE_RE.test(value)) {
+  // Length cap before the regex test (defense in depth — the regex
+  // here is a simple character class, but the same discipline that
+  // bounds longer regexes elsewhere applies).
+  if (value.length > MAX_VALUE_LENGTH || FORBIDDEN_VALUE_RE.test(value)) {
     throw new CookieError("cookies/invalid-value",
-      "cookie value contains forbidden control character (CRLF/NUL/;/,)");
+      "cookie value is too long or contains forbidden control character (CRLF/NUL/;/,)");
   }
 }
 

package/lib/credential-hash.js

@@ -77,10 +77,7 @@ var { FrameworkError } = require("./framework-error");
 
 var observability = lazyRequire(function () { return require("./observability"); });
 
-function _emitEvent(name, value, labels) {
-  try { observability().event(name, value, labels || {}); }
-  catch (_e) { /* hot-path observability sink — drops silent on internal throws */ }
-}
+function _emitEvent(n, v, l) { observability().safeEvent(n, v, l || {}); }
 
 // Default SHAKE256 output size for newly-issued credentials. 128
 // bytes (1024 bits) is double the SHAKE256 capacity (512 bits, which
@@ -92,14 +89,14 @@ function _emitEvent(name, value, labels) {
 // posture (highest practical bar where cost is negligible), default
 // to the larger size; operators pass `{ params: { length: 64 } }`
 // to opt into the SHA3-512-comparable byte count if they need it.
-var SHAKE256_DEFAULT_LENGTH = 128;
+var SHAKE256_DEFAULT_LENGTH = C.BYTES.bytes(128);
 // Minimum payload length both hash() and verify() enforce. 16 bytes
 // (128 bits) is the floor below which the digest's collision space
 // becomes brute-forceable. The asymmetry between hash() (rejected < 16
 // at config time) and verify() (silently accepted any length) let a
 // truncated stored envelope verify with trivial work; both ends now
 // refuse short payloads symmetrically.
-var SHAKE256_MIN_LENGTH = 16;
+var SHAKE256_MIN_LENGTH = C.BYTES.bytes(16);
 
 function _shake256(secret, length) {
   // crypto.kdf wraps SHAKE256 with arbitrary output length. That's the
@@ -227,7 +224,7 @@ async function hash(secret, opts) {
   }
   // Unreachable — _validateOpts rejects unknown algos.
   throw new CredentialHashError(
-    "credentialHash.hash: unsupported algo id 0x" + algoId.toString(16),
+    "credentialHash.hash: unsupported algo id 0x" + algoId.toString(0x10),
     "credential-hash/unsupported");
 }
 

package/lib/crypto.js

@@ -82,7 +82,7 @@ function hmacSha3(key, data) { return hmac(key, data, "sha3-512"); }
 
 // (SHA-1 is intentionally NOT exported from b.crypto. The framework's
 //  only legitimate SHA-1 use is the HaveIBeenPwned k-anonymity API in
-//  lib/auth/password.js, which imports lib/internal-sha1-hibp.js
+//  lib/auth/password.js, which imports lib/framework-sha1-hibp.js
 //  directly. Public b.crypto.sha1* is permanently off the table — a
 //  future caller wanting SHA-1 for storage / signing / fingerprinting
 //  would re-introduce a broken primitive into the crypto surface this
@@ -137,8 +137,8 @@ function encrypt(plaintext, publicKeys) {
     privateKey: nodeCrypto.createPrivateKey(ephEc.privateKey),
     publicKey:  nodeCrypto.createPublicKey(ecPubPem),
   });
-  var key = kdf(Buffer.concat([kem.sharedKey, ecSs]), 32);
-  var nonce = generateBytes(24);
+  var key = kdf(Buffer.concat([kem.sharedKey, ecSs]), C.BYTES.bytes(32));
+  var nonce = generateBytes(C.BYTES.bytes(24));
   var ct = xchacha20poly1305(key, nonce).encrypt(Buffer.from(plaintext, "utf8"));
 
   var kemCtLen = Buffer.alloc(2); kemCtLen.writeUInt16BE(kem.ciphertext.length);
@@ -153,8 +153,8 @@ function encrypt(plaintext, publicKeys) {
 
 function encryptMlkemOnly(plaintext, publicKeyPem) {
   var kem = nodeCrypto.encapsulate(nodeCrypto.createPublicKey(publicKeyPem));
-  var key = kdf(kem.sharedKey, 32);
-  var nonce = generateBytes(24);
+  var key = kdf(kem.sharedKey, C.BYTES.bytes(32));
+  var nonce = generateBytes(C.BYTES.bytes(24));
   var ct = xchacha20poly1305(key, nonce).encrypt(Buffer.from(plaintext, "utf8"));
   var kemCtLen = Buffer.alloc(2); kemCtLen.writeUInt16BE(kem.ciphertext.length);
   return Buffer.concat([
@@ -200,14 +200,14 @@ function decryptEnvelope(packed, privateKeys) {
       privateKey: nodeCrypto.createPrivateKey(ecPrivPem),
       publicKey:  nodeCrypto.createPublicKey({ key: ecEphDer, type: "spki", format: "der" }),
     });
-    symmetricKey = kdf(Buffer.concat([mlkemSs, ecSs]), 32);
+    symmetricKey = kdf(Buffer.concat([mlkemSs, ecSs]), C.BYTES.bytes(32));
   } else if (kemId === C.KEM_IDS.ML_KEM_1024) {
-    symmetricKey = kdf(mlkemSs, 32);
+    symmetricKey = kdf(mlkemSs, C.BYTES.bytes(32));
   } else {
     throw new Error("Invalid envelope: unsupported KEM ID " + kemId);
   }
 
-  var nonce = packed.subarray(pos, pos + 24); pos += 24;
+  var nonce = packed.subarray(pos, pos + C.BYTES.bytes(24)); pos += C.BYTES.bytes(24);
   return Buffer.from(
     xchacha20poly1305(symmetricKey, nonce).decrypt(packed.subarray(pos))
   ).toString("utf8");
@@ -222,7 +222,7 @@ function decryptEnvelope(packed, privateKeys) {
 // ciphertext from row A literally cannot decrypt as row B even with
 // the same key).
 function encryptPacked(buffer, key, aad) {
-  var nonce = random(24);
+  var nonce = random(C.BYTES.bytes(24));
   var ct = xchacha20poly1305(key, nonce, aad ? Buffer.from(aad) : undefined).encrypt(buffer);
   return Buffer.concat([
     Buffer.from([C.FORMAT.XCHACHA20_POLY1305]),

package/lib/csv.js

@@ -53,7 +53,7 @@ var DEFAULTS_PARSE = {
   quote:         "\"",
   trim:          false,
   maxBytes:      C.BYTES.mib(16),
-  maxRows:       1000000,
+  maxRows:       1_000_000,
   maxFieldBytes: C.BYTES.mib(1),
   onBadRow:      "throw",
 };
@@ -84,13 +84,16 @@ function _validateDelim(name, value) {
 
 function parse(input, opts) {
   opts = Object.assign({}, DEFAULTS_PARSE, opts || {});
-  // maxBytes via shared lib/numeric-bounds — Infinity / NaN bypass the
-  // body cap and let a hostile multi-megabyte CSV through unbounded.
-  if (!numericBounds.isPositiveFiniteInt(opts.maxBytes)) {
-    throw new CsvError("csv/bad-opt",
-      "csv.parse: maxBytes must be a positive finite integer; got " +
-        numericBounds.shape(opts.maxBytes));
-  }
+  // maxBytes / maxRows / maxFieldBytes via shared lib/numeric-bounds —
+  // Infinity / NaN bypass the corresponding caps and let a hostile
+  // multi-megabyte CSV (or a single hostile row / single hostile field)
+  // through unbounded.
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxBytes,
+    "csv.parse: maxBytes", CsvError, "csv/bad-opt");
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxRows,
+    "csv.parse: maxRows", CsvError, "csv/bad-opt");
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxFieldBytes,
+    "csv.parse: maxFieldBytes", CsvError, "csv/bad-opt");
 
   var s;
   if (typeof input === "string") s = input;

package/lib/db-declare-row-policy.js

@@ -54,6 +54,7 @@
  *   }
  */
 var safeSql = require("./safe-sql");
+var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
 
 var DeclareRowPolicyError = defineClass("DeclareRowPolicyError", { alwaysPermanent: true });
@@ -103,19 +104,13 @@ function _validateOpts(opts) {
     }
   }
 
-  if (typeof opts.schema !== "string" || opts.schema.length === 0) {
-    throw _err("declare-row-policy/missing-opt", "schema is required");
-  }
+  validateOpts.requireNonEmptyString(opts.schema, "schema", DeclareRowPolicyError, "declare-row-policy/missing-opt");
   _validateIdent("schema", opts.schema);
 
-  if (typeof opts.table !== "string" || opts.table.length === 0) {
-    throw _err("declare-row-policy/missing-opt", "table is required");
-  }
+  validateOpts.requireNonEmptyString(opts.table, "table", DeclareRowPolicyError, "declare-row-policy/missing-opt");
   _validateIdent("table", opts.table);
 
-  if (typeof opts.name !== "string" || opts.name.length === 0) {
-    throw _err("declare-row-policy/missing-opt", "name is required");
-  }
+  validateOpts.requireNonEmptyString(opts.name, "name", DeclareRowPolicyError, "declare-row-policy/missing-opt");
   _validateIdent("name", opts.name);
 
   var role = null;

package/lib/db-declare-view.js

@@ -61,6 +61,7 @@
  *   }
  */
 var safeSql = require("./safe-sql");
+var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
 
 var DeclareViewError = defineClass("DeclareViewError", { alwaysPermanent: true });
@@ -135,14 +136,10 @@ function _validateOpts(opts) {
     }
   }
 
-  if (typeof opts.schema !== "string" || opts.schema.length === 0) {
-    throw _err("declare-view/missing-opt", "schema is required");
-  }
+  validateOpts.requireNonEmptyString(opts.schema, "schema", DeclareViewError, "declare-view/missing-opt");
   _validateIdent("schema", opts.schema);
 
-  if (typeof opts.name !== "string" || opts.name.length === 0) {
-    throw _err("declare-view/missing-opt", "name is required");
-  }
+  validateOpts.requireNonEmptyString(opts.name, "name", DeclareViewError, "declare-view/missing-opt");
   _validateIdent("name", opts.name);
 
   if (opts.source === undefined) {

package/lib/db-query.js

@@ -27,6 +27,7 @@
  *     would always return zero rows; failing loudly is safer).
  */
 var { Readable } = require("node:stream");
+var C = require("./constants");
 var cryptoField = require("./crypto-field");
 var { generateToken } = require("./crypto");
 var safeSql = require("./safe-sql");
@@ -298,7 +299,7 @@ class Query {
     }
     var withId = Object.assign({}, row);
     if (withId._id === undefined || withId._id === null) {
-      withId._id = generateToken(16);
+      withId._id = generateToken(C.BYTES.bytes(16));
     }
     var sealed = cryptoField.sealRow(this._cryptoFieldKey(), withId);
     var cols = Object.keys(sealed);
@@ -392,8 +393,13 @@ class Query {
 }
 
 function _validateField(field) {
-  if (typeof field !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(field)) {
-    throw new Error("invalid field name: '" + field + "' (must match [A-Za-z_][A-Za-z0-9_]*)");
+  if (typeof field !== "string" ||
+      field.length === 0 ||
+      field.length > safeSql.MAX_IDENTIFIER_LENGTH ||
+      !safeSql.DEFAULT_IDENTIFIER_RE.test(field)) {
+    throw new Error("invalid field name: '" + field +
+      "' (must match " + safeSql.DEFAULT_IDENTIFIER_RE + ", length 1.." +
+      safeSql.MAX_IDENTIFIER_LENGTH + ")");
   }
 }
 

package/lib/db-schema.js

@@ -1,6 +1,7 @@
 "use strict";
 /**
- * Schema reconciler + imperative migration runner.
+ * Schema reconciler + imperative migration runner + shared SQL
+ * execution helpers used by every db-touching primitive.
  *
  * Hybrid migration strategy (per roadmap Q2):
  *
@@ -19,9 +20,25 @@
  * Apps mix both: declarative covers structural changes (CREATE/ALTER),
  * imperative covers data backfills, transformations, conditional schema
  * changes that need code.
+ *
+ * Shared SQL execution helpers used by lib/migrations / lib/seeders /
+ * lib/vault/rotate / lib/db etc.:
+ *
+ *   - runSql                — raw DDL / BEGIN / COMMIT / PRAGMA on
+ *                             the framework's better-sqlite3 handle.
+ *   - runSqlOnHandle        — handles BOTH raw better-sqlite3 and
+ *                             b.db framework wrapper shapes —
+ *                             operator-supplied handles can be either.
+ *   - runInTransaction      — wrap fn in BEGIN / COMMIT / ROLLBACK on
+ *                             the supplied db handle. opts.lockMode
+ *                             appends to BEGIN ("IMMEDIATE" /
+ *                             "EXCLUSIVE" on SQLite). opts.onRollbackFail
+ *                             surfaces a rollback throw without
+ *                             swallowing the original error.
  */
 var path = require("path");
 var atomicFile = require("./atomic-file");
+var safeSql = require("./safe-sql");
 
 // SQLite raw-SQL helper. node:sqlite DatabaseSync exposes a method on the
 // database object that runs raw SQL without bind parameters — used for DDL,
@@ -30,6 +47,48 @@ var atomicFile = require("./atomic-file");
 // `.exec(` regardless of receiver type.
 function runSql(database, sql) { return database["exec"](sql); }
 
+// runSqlOnHandle — execute SQL against either handle shape:
+//   - raw better-sqlite3 / node:sqlite Database (db.exec)
+//   - b.db framework wrapper (db.runSql)
+// Migrations / seeders / break-glass migrate accept operator-supplied
+// handles in either shape; this wrapper normalizes the call. The
+// 'exec'/'runSql' lookups use bracket notation so the eslint rule
+// banning bare-identifier db method calls (collapsing prepare → field)
+// stays satisfied.
+function runSqlOnHandle(db, sql) {
+  if (db && typeof db["exec"] === "function") return db["exec"](sql);
+  if (db && typeof db["runSql"] === "function") return db["runSql"](sql);
+  throw new Error("dbSchema.runSqlOnHandle: handle exposes no DDL runner (exec / runSql)");
+}
+
+// runInTransaction — wrap fn in BEGIN / COMMIT / ROLLBACK on the
+// supplied db handle. Used by migrations / seeders / any operator-
+// facing transaction. opts.lockMode appends to BEGIN ("IMMEDIATE",
+// "EXCLUSIVE" — SQLite-specific). opts.onRollbackFail surfaces a
+// rollback throw without swallowing the original error (the original
+// always re-throws).
+function runInTransaction(db, fn, opts) {
+  if (typeof fn !== "function") {
+    throw new TypeError("dbSchema.runInTransaction: fn must be a function");
+  }
+  opts = opts || {};
+  var beginSql = opts.lockMode ? "BEGIN " + opts.lockMode : "BEGIN";
+  runSqlOnHandle(db, beginSql);
+  try {
+    var result = fn();
+    runSqlOnHandle(db, "COMMIT");
+    return result;
+  } catch (e) {
+    try { runSqlOnHandle(db, "ROLLBACK"); }
+    catch (rollbackErr) {
+      if (typeof opts.onRollbackFail === "function") {
+        try { opts.onRollbackFail(rollbackErr); } catch (_e) { /* nested handler must not bubble */ }
+      }
+    }
+    throw e;
+  }
+}
+
 // ---- Internal migrations table ----
 
 var MIGRATIONS_TABLE = "_blamejs_migrations";
@@ -186,8 +245,13 @@ function listColumns(database, tableName) {
 
 // SQL identifier safety: alphanumeric + underscore, starts with letter or underscore.
 function validateIdent(ident, kind) {
-  if (typeof ident !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(ident)) {
-    throw new Error("invalid " + kind + ": '" + ident + "' (must match [A-Za-z_][A-Za-z0-9_]*)");
+  if (typeof ident !== "string" ||
+      ident.length === 0 ||
+      ident.length > safeSql.MAX_IDENTIFIER_LENGTH ||
+      !safeSql.DEFAULT_IDENTIFIER_RE.test(ident)) {
+    throw new Error("invalid " + kind + ": '" + ident +
+      "' (must match " + safeSql.DEFAULT_IDENTIFIER_RE + ", length 1.." +
+      safeSql.MAX_IDENTIFIER_LENGTH + ")");
   }
 }
 
@@ -228,14 +292,13 @@ function runMigrations(database, migrationDir) {
     }
 
     try {
-      runSql(database, "BEGIN");
-      mig.up(database);
-      database.prepare(
-        "INSERT INTO " + Q_MIGRATIONS_TABLE + " (name, description, appliedAt) VALUES (?, ?, ?)"
-      ).run(file, mig.description || "", new Date().toISOString());
-      runSql(database, "COMMIT");
+      runInTransaction(database, function () {
+        mig.up(database);
+        database.prepare(
+          "INSERT INTO " + Q_MIGRATIONS_TABLE + " (name, description, appliedAt) VALUES (?, ?, ?)"
+        ).run(file, mig.description || "", new Date().toISOString());
+      });
     } catch (e) {
-      try { runSql(database, "ROLLBACK"); } catch (_e) { /* ignored — already in error path */ }
       throw new Error("migration '" + file + "' failed: " + e.message);
     }
     applied.push(file);
@@ -250,5 +313,7 @@ module.exports = {
   runMigrations:    runMigrations,
   validateIdent:    validateIdent,
   runSql:           runSql,
+  runSqlOnHandle:   runSqlOnHandle,
+  runInTransaction: runInTransaction,
   MIGRATIONS_TABLE: MIGRATIONS_TABLE,
 };