@blamejs/core 0.14.5 → 0.14.7

package/lib/db-query.js

@@ -33,6 +33,7 @@ var { generateToken } = require("./crypto");
 var safeJson = require("./safe-json");
 var safeJsonPath = require("./safe-jsonpath");
 var safeSql = require("./safe-sql");
+var audit = require("./audit");
 
 // "@>" / "?" / "?|" / "?&" are JSONB containment + key-existence
 // operators. Routed through safeJsonPath validation before binding so
@@ -46,7 +47,7 @@ var JSONB_CONTAINMENT_OPS = new Set(["@>"]);
 var JSONB_KEY_OPS         = new Set(["?", "?|", "?&"]);
 
 class Query {
-  constructor(database, tableName) {
+  constructor(database, tableName, opts) {
     // 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
@@ -84,6 +85,62 @@ class Query {
     this._orderBy       = null;
     this._limit         = null;
     this._offset        = null;
+
+    // Column-membership gate. `db.from()` passes the table's
+    // declared columns + the configured gate mode so an operator-
+    // supplied column name that isn't a real column of the table is
+    // refused before it interpolates into SQL as an identifier
+    // (ORDER-BY / sealed-column-disclosure injection — CWE-89 /
+    // CWE-1336). A bare `new Query(db, name)` with no opts leaves the
+    // gate disabled (declaredColumns null), so direct/internal
+    // construction is unaffected.
+    opts = opts || {};
+    this._declaredColumns = (opts.declaredColumns instanceof Set) ? opts.declaredColumns
+      : (Array.isArray(opts.declaredColumns) ? new Set(opts.declaredColumns) : null);
+    this._columnGateMode  = opts.columnGateMode || "reject";
+    this._allowedColumns  = null;
+  }
+
+  // Restrict the operator-allowable columns to an explicit subset
+  // (tighter than the schema-declared set). Use when a query is built
+  // from request input and must only ever touch a known-safe list.
+  // Throws on a non-array or an invalid identifier.
+  allowedColumns(cols) {
+    if (!Array.isArray(cols) || cols.length === 0) {
+      throw new TypeError("allowedColumns(cols): expected a non-empty array of column names");
+    }
+    cols.forEach(_validateField);
+    this._allowedColumns = new Set(cols);
+    return this;
+  }
+
+  // Assert `field` is a member of the allowed/declared column set
+  // before it is interpolated into SQL as an identifier. The operator
+  // `allowedColumns()` set (when present) is ALWAYS enforced; the
+  // schema gate respects the configured mode ("reject" default
+  // throws | "warn" drop-silent audits + allows | "off" / no declared
+  // set skips).
+  _assertColumnMember(field, where) {
+    if (this._allowedColumns && !this._allowedColumns.has(field)) {
+      throw new Error("column '" + field + "' is not in the allowedColumns() set" +
+        (where ? " (" + where + ")" : ""));
+    }
+    if (this._declaredColumns === null || this._columnGateMode === "off") return;
+    if (this._declaredColumns.has(field)) return;
+    if (this._columnGateMode === "warn") {
+      try {
+        audit.safeEmit({
+          action:   "db.query.unknown_column",
+          outcome:  "failure",
+          metadata: { table: this._qualifiedKey, column: field, where: where || null },
+        });
+      } catch (_e) { /* drop-silent — observability sink, by design */ }
+      return;
+    }
+    throw new Error("column '" + field + "' is not a declared column of '" +
+      this._qualifiedKey + "'" + (where ? " (" + where + ")" : "") +
+      ". Declared columns: " + Array.from(this._declaredColumns).join(", ") +
+      ". Use .allowedColumns([...]) or db.init({ columnGate: 'off' }) to bypass.");
   }
 
   // Quoted SQL form: `"schema"."table"` if schema-qualified, else `"table"`.
@@ -114,7 +171,7 @@ class Query {
     if (!ALLOWED_OPS.has(op)) {
       throw new Error("invalid where operator: " + op);
     }
-    // D-M4 — JSONB / JSON-path injection guard. Routes operator-
+    // JSONB / JSON-path injection guard. Routes operator-
     // supplied JSONB containment + key-existence values through
     // safe-jsonpath before they reach the engine. Bound via `?`
     // placeholder so the value still doesn't interpolate; this is
@@ -171,6 +228,10 @@ class Query {
       value = lookup.value;
     }
     cryptoField && _validateField(field);
+    // Gate the post-sealed-rewrite physical column (derived-hash
+    // columns are declared physical columns, so the rewrite target
+    // passes membership).
+    this._assertColumnMember(field, "where");
     if (op === "IN") {
       // node:sqlite ? does not support array-binding. Pre-v0.8.18
       // `where(field, "IN", [1,2,3])` silently bound the entire
@@ -228,10 +289,11 @@ class Query {
   // text used to build expressions the chainable .where() can't express
   // (compound OR, row-value comparison for cursor pagination, etc.).
   // Placeholder count must match params.length.
-  whereRaw(sql, params) {
+  whereRaw(sql, params, opts) {
     if (typeof sql !== "string" || sql.length === 0) {
       throw new Error("whereRaw: sql must be a non-empty string");
     }
+    if (!(opts && opts.allowLiterals === true)) _assertRawNoStringLiteral(sql, "whereRaw");
     var p = Array.isArray(params) ? params : (params == null ? [] : [params]);
     // Count `?` placeholders, but skip occurrences inside string
     // literals ('...'  or "..."), line comments (-- to EOL), and
@@ -255,12 +317,15 @@ class Query {
       throw new Error("select() expects an array of column names");
     }
     columns.forEach(_validateField);
+    var self = this;
+    columns.forEach(function (c) { self._assertColumnMember(c, "select"); });
     this._select = columns.slice();
     return this;
   }
 
   orderBy(field, direction) {
     _validateField(field);
+    this._assertColumnMember(field, "orderBy");
     direction = (direction || "asc").toLowerCase();
     if (direction !== "asc" && direction !== "desc") {
       throw new Error("orderBy direction must be 'asc' or 'desc'");
@@ -348,7 +413,7 @@ class Query {
   // the bound table's sealedFields registration before it lands in the
   // operator's pipeline. For large result sets (audit exports, backup
   // table dumps) this avoids materializing the full rowset in memory.
-  // D-M5 — streamLimit ceiling enforced from the module-level db
+  // StreamLimit ceiling enforced from the module-level db
   // config; per-call opts.streamLimit overrides for one-off bumps.
   stream(opts) {
     var sql = "SELECT " + this._projection() + " FROM " + this._quotedTable() +
@@ -455,6 +520,8 @@ class Query {
       throw new Error("update changes object is empty");
     }
     setKeys.forEach(_validateField);
+    var selfUpd = this;
+    setKeys.forEach(function (k) { selfUpd._assertColumnMember(k, "update"); });
     var setClause = setKeys.map(function (k) { return '"' + k + '" = ?'; }).join(", ");
     var setValues = setKeys.map(function (k) { return sealed[k]; });
 
@@ -498,6 +565,7 @@ class Query {
       throw new Error("increment(column, delta): column must be a non-empty string");
     }
     _validateField(column);
+    this._assertColumnMember(column, "increment");
     if (delta === undefined) delta = 1;
     if (typeof delta !== "number" || !Number.isFinite(delta) || !Number.isInteger(delta)) {
       throw new Error("increment(column, delta): delta must be a finite integer (default 1)");
@@ -532,7 +600,7 @@ class Query {
     if (typeof closure !== "function") {
       throw new Error("whereGroup(closure): expected function (qb) => ...");
     }
-    var sub = new WhereBuilder();
+    var sub = new WhereBuilder(this);
     closure(sub);
     var built = sub.build();
     if (!built.sql) return this;
@@ -551,7 +619,7 @@ class Query {
       throw new Error("orWhere(...): no prior where(...) — start the chain with where(...)");
     }
     if (typeof fieldOrObjOrFn === "function") {
-      var sub = new WhereBuilder();
+      var sub = new WhereBuilder(this);
       fieldOrObjOrFn(sub);
       var built = sub.build();
       if (!built.sql) return this;
@@ -562,7 +630,7 @@ class Query {
     }
     // For non-closure shapes, build a transient single-leaf Query and
     // splice it. We compile to a `WhereBuilder` for symmetry.
-    var sub2 = new WhereBuilder();
+    var sub2 = new WhereBuilder(this);
     if (fieldOrObjOrFn !== null && typeof fieldOrObjOrFn === "object" && !Array.isArray(fieldOrObjOrFn)) {
       Object.keys(fieldOrObjOrFn).forEach(function (k) { sub2.eq(k, fieldOrObjOrFn[k]); });
     } else if (op === undefined) {
@@ -592,6 +660,8 @@ class Query {
       throw new Error("search(fields, term): fields must be a non-empty array of column names");
     }
     fields.forEach(_validateField);
+    var selfS = this;
+    fields.forEach(function (f) { selfS._assertColumnMember(f, "search"); });
     if (term === undefined || term === null) return this;
     if (typeof term !== "string") {
       throw new Error("search(fields, term): term must be a string");
@@ -684,14 +754,18 @@ class Query {
 // `.build()` returns `{ sql, params }`. Empty builder → `{ sql: "",
 // params: [] }`.
 class WhereBuilder {
-  constructor() {
+  constructor(gate) {
     this._parts = [];   // [{ joiner: "AND"|"OR", sql: "...", params: [...] }]
+    // The owning Query, so grouped/OR sub-expressions enforce the
+    // same column-membership gate as the top-level chain.
+    this._gate = gate || null;
   }
   _push(joiner, field, op, value) {
     if (typeof field !== "string" || field.length === 0) {
       throw new Error("WhereBuilder: field must be a non-empty string");
     }
     _validateField(field);
+    if (this._gate) this._gate._assertColumnMember(field, "whereGroup");
     var qf = '"' + field + '"';
     if (op === "IN" || op === "NOT IN") {
       if (!Array.isArray(value) || value.length === 0) {
@@ -723,10 +797,11 @@ class WhereBuilder {
   orLte(f, v)  { return this._push("OR", f, "<=", v); }
   orIn(f, vs)  { return this._push("OR", f, "IN", vs); }
   orLike(f, v) { return this._push("OR", f, "LIKE", v); }
-  raw(sql, params) {
+  raw(sql, params, opts) {
     if (typeof sql !== "string" || sql.length === 0) {
       throw new Error("WhereBuilder.raw: sql must be a non-empty string");
     }
+    if (!(opts && opts.allowLiterals === true)) _assertRawNoStringLiteral(sql, "WhereBuilder.raw");
     var p = Array.isArray(params) ? params : (params == null ? [] : [params]);
     if (_countPlaceholders(sql) !== p.length) {
       throw new Error("WhereBuilder.raw: placeholder count mismatch");
@@ -752,6 +827,53 @@ class WhereBuilder {
 // Tracks SQL single-quoted, double-quoted, line-comment, and block-
 // comment state to avoid counting `?` characters that are part of
 // literal text the SQL engine never interprets as a binding marker.
+// Refuse raw SQL fragments that embed a single-quoted string
+// literal. A whereRaw / WhereBuilder.raw fragment is meant to be a
+// STATIC template whose every value is bound through a `?` placeholder;
+// an embedded `'...'` literal is the signature of operator input
+// concatenated into the query (CWE-89 / CWE-564 — concat into a
+// query builder). Double-quoted identifiers (`"col"`), line comments,
+// and block comments are skipped. Operators with a deliberate static
+// literal pass `{ allowLiterals: true }`. Shares the quote/comment
+// scanning shape with _countPlaceholders.
+function _assertRawNoStringLiteral(sql, where) {
+  var i = 0;
+  var len = sql.length;
+  while (i < len) {
+    var ch = sql.charAt(i);
+    var next = i + 1 < len ? sql.charAt(i + 1) : "";
+    if (ch === '"') {
+      i += 1;
+      while (i < len) {
+        if (sql.charAt(i) === '"') {
+          if (sql.charAt(i + 1) === '"') { i += 2; continue; }
+          i += 1; break;
+        }
+        i += 1;
+      }
+      continue;
+    }
+    if (ch === "-" && next === "-") {
+      while (i < len && sql.charAt(i) !== "\n") i += 1;
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      i += 2;
+      while (i < len && !(sql.charAt(i) === "*" && sql.charAt(i + 1) === "/")) i += 1;
+      i += 2;
+      continue;
+    }
+    if (ch === "'") {
+      throw new safeSql.SafeSqlError(
+        where + ": raw SQL must not contain a string literal ('...') — bind every " +
+        "value with a ? placeholder, or pass { allowLiterals: true } when the literal " +
+        "is static and operator-controlled.",
+        "sql/raw-literal");
+    }
+    i += 1;
+  }
+}
+
 function _countPlaceholders(sql) {
   var count = 0;
   var i = 0;

package/lib/db.js

@@ -70,6 +70,7 @@ var safeJson = require("./safe-json");
 var safeSql = require("./safe-sql");
 var validateOpts = require("./validate-opts");
 var vault = require("./vault");
+var vaultAad = require("./vault-aad");
 
 var DbError = defineClass("DbError", { alwaysPermanent: true });
 var WormViolationError = require("./framework-error").WormViolationError;
@@ -153,12 +154,18 @@ var initialized = false;
 var dataResidency = null;   // operator's declared region config (validated by storage backends)
 var subjectTables = [];     // [{ name, subjectField, personalDataCategories }] — for subject.export/erase
 var tableMetadata = {};     // table name → metadata snapshot (PK/FK/sealed/derived) for getTableMetadata
-// D-M5 — streamLimit ceiling. db.stream() / Query.stream() consult this
+// StreamLimit ceiling. db.stream() / Query.stream() consult this
 // (overridden per-call via opts.streamLimit). Default cap matches a
 // generous-but-bounded 1M rows so an accidentally-unbounded export
 // surfaces a thrown error instead of OOM. v0.7.67's maxRowsPerQuery
 // bounds .all() / .first() — this is its streaming counterpart.
 var streamLimit = C.BYTES.bytes(1000000);                                                              // row-count ceiling, not bytes
+// Column-membership gate mode, set by db.init({ columnGate }). Default
+// "reject" (security-on): a query that orders / selects / filters on a
+// column that is not declared in the table's schema is refused before
+// the identifier interpolates into SQL. "warn" audits + allows; "off"
+// disables the gate.
+var columnGateMode = "reject";
 
 // ---- Framework-baked tables ----
 //
@@ -287,7 +294,7 @@ var FRAMEWORK_SCHEMA = [
     indexes: ["placedAt"],
   },
   {
-    // Per-row crypto-erasure key registry — F-RTBF-3 per-row keys.
+    // Per-row crypto-erasure key registry — per-row keys.
     // Each entry holds a sealed wrapped K_row keyed by (table,
     // rowId). b.subject.eraseHard deletes the entry, leaving WAL /
     // replica residuals undecryptable.
@@ -614,8 +621,8 @@ var FRAMEWORK_SCHEMA = [
   {
     // _blamejs_break_glass_grants — issued grants. Each successful
     // step-up creates one row; each row read decrements rowsRemaining.
-    // Default maxRowsPerGrant=1 enforces "row by row" auth per the
-    // operator-confirmed shape (each row access = its own grant).
+    // Default maxRowsPerGrant=1 enforces "row by row" auth
+    // (each row access = its own grant).
     // Sealed columns hold reason + scopeColumns so audit-readable
     // metadata doesn't leak in cleartext.
     name: "_blamejs_break_glass_grants",
@@ -661,25 +668,58 @@ function resolveTmpDir(optsTmpDir) {
 
 // ---- DB encryption key management ----
 
+// AAD binds the sealed DB encryption key to the deployment's dataDir
+// + key-file path, so a key file substituted from another deployment
+// fails the AEAD tag check on unseal (cross-deployment ciphertext
+// substitution / silent re-key — CWE-345 / CWE-441; the AAD itself is
+// NIST SP 800-38D additional-authenticated-data over the XChaCha20-
+// Poly1305 seal). nodePath.resolve (not realpathSync) — the key file
+// may not exist yet at first-run seal.
+function _dbKeyAad(dataDirPath, keyPath) {
+  return vaultAad.buildContextAad({
+    purpose: "blamejs/db-encryption-key/v1",
+    dataDir: nodePath.resolve(dataDirPath),
+    keyPath: nodePath.resolve(keyPath),
+  });
+}
+
 function loadOrCreateDbKey(dataDirPath, keyPathOverride) {
   // Operator opt: `opts.dbKeyPath` — useful when the encryption key
   // needs to live outside `dataDir` (e.g. a separate volume mounted
   // from a KMS-fronted secret store). Default places it next to the
   // encrypted DB so backup capture is one-tarball.
   var keyPath = keyPathOverride || nodePath.join(dataDirPath, "db.key.enc");
+  var aad = _dbKeyAad(dataDirPath, keyPath);
   if (nodeFs.existsSync(keyPath)) {
     var sealed = atomicFile.readSync(keyPath, { encoding: "utf8" }).trim();
-    var b64 = vault.unseal(sealed);
+    var b64;
+    // isAadSealed is checked FIRST and is load-bearing: AAD_PREFIX
+    // ("vault.aad:") is NOT a prefix of VAULT_PREFIX ("vault:"), so a
+    // plain vault.unseal would silently pass an AAD-sealed value
+    // through unchanged. AAD-bound keys verify the deployment context;
+    // a key file lifted from another deployment fails the tag check.
+    if (vaultAad.isAadSealed(sealed)) {
+      b64 = vaultAad.unseal(sealed, aad);
+    } else {
+      // Legacy plain-sealed key (pre-AAD): unseal with the classic
+      // path, then re-seal in place with the deployment-path binding so
+      // the next boot is AAD-verified. Read-migration preserves the key
+      // bytes — no re-key, no operator action.
+      b64 = vault.unseal(sealed);
+      if (b64) {
+        atomicFile.writeSync(keyPath, vaultAad.seal(b64, aad), { fileMode: 0o600 });
+        log("re-sealed DB encryption key with deployment-path binding at " + keyPath);
+      }
+    }
     if (!b64) {
       throw _dbErr("db/key-unseal-empty",
         "FATAL: db.key.enc unseal returned empty — vault may not be initialized or key file corrupted");
     }
     return Buffer.from(b64, "base64");
   }
-  // First run — generate, seal, persist (atomic)
+  // First run — generate, AAD-seal, persist (atomic).
   var raw = generateBytes(C.BYTES.bytes(32));
-  // allow:seal-without-aad — whole-file DB encryption key, not a row column
-  var sealedKey = vault.seal(raw.toString("base64"));
+  var sealedKey = vaultAad.seal(raw.toString("base64"), aad);
   atomicFile.writeSync(keyPath, sealedKey, { fileMode: 0o600 });
   log("generated DB encryption key at " + keyPath);
   return raw;
@@ -918,6 +958,7 @@ function cleanStaleTmpDbs(tmpDir) {
  *   tmpDir:                  string,            // override the encrypted-mode tmpfs path (default /dev/shm or BLAMEJS_TMPDIR)
  *   migrationDir:            string,            // optional — path to ./migrations/ (run-once each)
  *   streamLimit:             number,            // default 1_000_000 — db.stream row ceiling
+ *   columnGate:              "reject"|"warn"|"off", // default "reject" — refuse queries on columns not declared in the table schema
  *   skipBootIntegrityCheck:  boolean,           // default false — skip PRAGMA integrity_check
  *   skipIntegrityCheck:      boolean,           // default false — alias
  *   auditSigning:            { mode, algorithm }, // default { mode: "wrapped" }
@@ -966,7 +1007,7 @@ async function init(opts) {
     throw new DbError("db/bad-at-rest",
       "db.init: atRest must be 'encrypted' or 'plain', got: " + opts.atRest);
   }
-  // D-M5 — operator-tunable streamLimit ceiling. Throw at config-time
+  // Operator-tunable streamLimit ceiling. Throw at config-time
   // on bad shape so a typo surfaces at boot rather than as an
   // unbounded stream at first export.
   if (opts.streamLimit !== undefined) {
@@ -978,6 +1019,15 @@ async function init(opts) {
     }
     streamLimit = opts.streamLimit;
   }
+  // Column-membership gate mode — throw at config-time on a typo so it
+  // surfaces at boot, not as a query that silently bypasses the gate.
+  if (opts.columnGate !== undefined &&
+      opts.columnGate !== "reject" && opts.columnGate !== "warn" && opts.columnGate !== "off") {
+    throw new DbError("db/bad-init",
+      "db.init: columnGate must be 'reject' (default), 'warn', or 'off'; got " +
+      JSON.stringify(opts.columnGate));
+  }
+  columnGateMode = opts.columnGate || "reject";
   dataDir = opts.dataDir;
   if (!nodeFs.existsSync(dataDir)) nodeFs.mkdirSync(dataDir, { recursive: true });
 
@@ -990,7 +1040,7 @@ async function init(opts) {
     }
     if (!nodeFs.existsSync(tmpDir)) nodeFs.mkdirSync(tmpDir, { recursive: true });
 
-    // D-H7 — if the resolved tmpDir is NOT actually tmpfs, the
+    // If the resolved tmpDir is NOT actually tmpfs, the
     // plaintext DB file lives on persistent storage. We check that tmpDir
     // resolves under /dev/shm or /run/shm on Linux as a heuristic; on other
     // platforms we warn that the operator must verify tmpfs binding
@@ -1264,9 +1314,10 @@ async function init(opts) {
   for (var i = 0; i < fullSchema.length; i++) {
     var t = fullSchema[i];
     cryptoField.registerTable(t.name, {
-      sealedFields:   t.sealedFields,
-      derivedHashes:  t.derivedHashes,
-      hashNamespaces: t.hashNamespaces,
+      sealedFields:    t.sealedFields,
+      derivedHashes:   t.derivedHashes,
+      hashNamespaces:  t.hashNamespaces,
+      derivedHashMode: t.derivedHashMode,
     });
     tableMetadata[t.name] = {
       primaryKey:             _normalizePk(t),
@@ -1349,7 +1400,7 @@ async function init(opts) {
   // is BELOW tip — the DB was rolled back to an older snapshot. Refuse boot.
   _checkRollback(dataDir);
 
-  // ---- F-RET-2 — WORM posture assertion ----
+  // ---- WORM posture assertion ----
   // Under sec-17a-4 / finra-4511 / fda-21cfr11 postures the operator
   // MUST have declared row-level WORM on at least one business-record
   // table. Refuse boot otherwise so missing-declaration drift is
@@ -1491,10 +1542,41 @@ async function init(opts) {
  */
 function from(tableName) {
   _requireInit();
-  return new Query(database, tableName);
+  return new Query(database, tableName, {
+    declaredColumns: getDeclaredColumns(tableName),
+    columnGateMode:  columnGateMode,
+  });
+}
+
+/**
+ * @primitive b.db.getDeclaredColumns
+ * @signature b.db.getDeclaredColumns(tableName)
+ * @since     0.14.7
+ * @status    stable
+ * @related   b.db.from, b.db.getTableMetadata
+ *
+ * Returns the declared column names for a table as an array, or `null`
+ * when the table has no registered schema metadata (a cross- or
+ * attached-schema table — the column-membership gate is a no-op for
+ * those). The declared set includes `_id` and any derived-hash columns,
+ * so sealed-field queries (which rewrite to the hash column) and `_id`
+ * lookups pass the gate. Backs the `db.init({ columnGate })` gate that
+ * refuses queries ordering / selecting / filtering on an undeclared
+ * column before the identifier interpolates into SQL.
+ *
+ * @example
+ *   b.db.getDeclaredColumns("orders");
+ *   // → ["_id", "customerId", "total", "createdAt"]
+ */
+// The declared set includes `_id` and any derived-hash columns, so
+// sealed-field queries (which rewrite to the hash column) and `_id`
+// lookups pass membership.
+function getDeclaredColumns(tableName) {
+  var md = tableMetadata[tableName];
+  return (md && md.columns) ? Object.keys(md.columns) : null;
 }
 
-// D-M6 — bounded prepared-statement cache for SQLite. Long-running
+// Bounded prepared-statement cache for SQLite. Long-running
 // daemons with diverse query shapes accumulate node:sqlite Statement
 // handles indefinitely; the LRU here caps at PREPARE_CACHE_MAX (256)
 // distinct SQL strings and finalizes the oldest when over. Reuse of
@@ -1611,7 +1693,7 @@ function stream(sql) {
   var table = opts && typeof opts.table === "string" ? opts.table : null;
   var unseal = table ? cryptoField : null;
 
-  // D-M5 — streamLimit ceiling. Per-call opts.streamLimit overrides
+  // StreamLimit ceiling. Per-call opts.streamLimit overrides
   // the module-level default; bad shape throws at call time so the
   // typo surfaces instead of an unbounded stream.
   var perCallLimit = streamLimit;
@@ -1661,10 +1743,10 @@ function stream(sql) {
 
 // DDL_RE — case-insensitive prefix match for the eight statement
 // shapes that MUTATE schema. Audited individually so a forensic
-// review can reconstruct schema evolution from the chain alone (D-M1).
+// review can reconstruct schema evolution from the chain alone.
 var DDL_RE = /^\s*(CREATE|DROP|ALTER|TRUNCATE|RENAME|ATTACH|DETACH|REINDEX)\b/i;
 
-// D-L7 — slow-query observability buckets for the local SQLite nodePath.
+// Slow-query observability buckets for the local SQLite nodePath.
 // Highest matched bucket wins so the per-query emit is single-shot;
 // operators dashboard on the `bucket` label.
 var _SLOW_QUERY_BUCKETS_LOCAL = Object.freeze([
@@ -1712,7 +1794,7 @@ function execRaw(sql) {
         action:   "db.ddl.executed",
         outcome:  "success",
         metadata: {
-          // OTel db.* semconv (F-RFC-4) — emit framework-conventional
+          // OTel db.* semconv — emit framework-conventional
           // attributes alongside the audit row so dashboards built on
           // OTel can correlate without an adapter.
           "db.system":     "sqlite",
@@ -2701,7 +2783,7 @@ function vacuumAfterErase(opts) {
   } catch (_e) { /* audit best-effort */ }
 }
 
-// F-POSTURE-1 — cascade-installed posture name. b.compliance.set(p)
+// Cascade-installed posture name. b.compliance.set(p)
 // calls applyPosture(p) which records the posture; the downstream
 // cryptoField.eraseRow path consults this via getActivePosture() to
 // auto-vacuum under postures whose POSTURE_DEFAULTS sets
@@ -3054,10 +3136,12 @@ module.exports = {
   getActivePosture:    getActivePosture,
   vacuumAfterErase:    vacuumAfterErase,
   from:                from,
+  getDeclaredColumns:  getDeclaredColumns,
+  _checkDualControlGate: _checkDualControlGate,
   collection:          require("./db-collection").collection,                              // allow:inline-require — db-collection lazy-requires db.js back; the inline require here breaks the cycle without needing a stub
   prepare:             prepare,
   stream:              stream,
-  // D-M5 — runtime read-only accessor so Query.stream picks up the
+  // Runtime read-only accessor so Query.stream picks up the
   // configured ceiling without re-importing module state.
   getStreamLimit:      function () { return streamLimit; },
   runSql:              execRaw,