@blamejs/core 0.14.26 → 0.15.0

package/lib/external-db.js

@@ -52,6 +52,10 @@ var log = boot("external-db");
 var audit         = lazyRequire(function () { return require("./audit"); });
 var db            = lazyRequire(function () { return require("./db"); });
 var observability = lazyRequire(function () { return require("./observability"); });
+// b.sql composes the framework's own internal queries against a backend
+// (e.g. the pg_roles hardening scan). Lazy because b.sql -> framework-schema
+// -> external-db would cycle at module load; resolved when a query runs.
+var sql    = lazyRequire(function () { return require("./sql"); });
 
 function _emitMetric(name, value, labels) {
   try { observability().event(name, value, labels || {}); }
@@ -79,7 +83,7 @@ function _emitMetric(name, value, labels) {
 // cannot backtrack polynomially (CWE-1333 ReDoS).
 var _STATEMENT_CLASS_RE = /^(?:\s|\/\*(?:[^*]|\*(?!\/))*\*\/|--[^\n]*\n)*([A-Za-z]+)/;
 var _STATEMENT_CLASS_MAP = Object.freeze({
-  SELECT: "SELECT", VALUES: "SELECT", TABLE: "SELECT",
+  SELECT: "SELECT", VALUES: "SELECT", TABLE: "SELECT",   // allow:hand-rolled-sql — leading-keyword classifier table, not composed SQL
   SHOW: "READ_INFO", DESCRIBE: "READ_INFO", DESC: "READ_INFO",
   PRAGMA: "READ_INFO", USE: "READ_INFO",
   INSERT: "DML", UPDATE: "DML", DELETE: "DML", MERGE: "DML",
@@ -762,7 +766,7 @@ function init(opts) {
         return async function () {
           var client = await cn();
           try {
-            await qn(client, "SET application_name TO " + quotedAppName, []);
+            await qn(client, "SET application_name TO " + quotedAppName, []);   // allow:hand-rolled-sql — Postgres session SET (no table; not a b.sql verb)
           } catch (_e) {
             // Best-effort. Real Postgres always supports SET
             // application_name; a driver that refuses it is a shim
@@ -1210,10 +1214,10 @@ async function transaction(fn, opts) {
         try {
           await b.beginTx(client);
           if (typeof stmtTimeoutMs === "number" && isFinite(stmtTimeoutMs) && stmtTimeoutMs > 0) {
-            await b.query(client, "SET LOCAL statement_timeout = " + Math.floor(stmtTimeoutMs), []);
+            await b.query(client, "SET LOCAL statement_timeout = " + Math.floor(stmtTimeoutMs), []);   // allow:hand-rolled-sql — Postgres session SET (no table; not a b.sql verb)
           }
           if (typeof idleTimeoutMs === "number" && isFinite(idleTimeoutMs) && idleTimeoutMs > 0) {
-            await b.query(client, "SET LOCAL idle_in_transaction_session_timeout = " + Math.floor(idleTimeoutMs), []);
+            await b.query(client, "SET LOCAL idle_in_transaction_session_timeout = " + Math.floor(idleTimeoutMs), []);   // allow:hand-rolled-sql — Postgres session SET (no table; not a b.sql verb)
           }
           for (var gi = 0; gi < prebuiltGucs.length; gi++) {
             await b.query(client, prebuiltGucs[gi], []);
@@ -1312,7 +1316,7 @@ async function _pingBackend(b) {
     var client = await b.pool.acquire();
     try {
       if (b.ping) await b.ping(client);
-      else        await b.query(client, "SELECT 1", []);
+      else        await b.query(client, "SELECT 1", []);   // allow:hand-rolled-sql — fixed connectivity ping (no table / b.sql verb)
       b.pool.release(client);
       return { ok: true, breakerState: b.breaker.getState(), pool: b.pool.stats() };
     } catch (e) {
@@ -1451,7 +1455,7 @@ function _buildSessionGucsStatements(sessionGucs) {
         "sessionGucs['" + name + "']: value must be a string, finite number, or boolean (got " +
         typeof value + ")", true);
     }
-    out.push("SET LOCAL " + qName + " = " + literal);
+    out.push("SET LOCAL " + qName + " = " + literal);   // allow:hand-rolled-sql — Postgres session GUC SET (no table; not a b.sql verb)
   }
   return out;
 }
@@ -2143,22 +2147,27 @@ function _connectAs(rawConnect, query, opts) {
 
   // Pre-compute the SET statements once — every fresh client runs the
   // same list, so building it per-connect would burn microbenchmarks.
+  // Postgres session-config statements (SET ROLE / search_path /
+  // application_name / statement_timeout / GUCs). These are session-state
+  // commands, not table DML — b.sql has no SET verb, so they stay
+  // hand-composed (identifiers double-quoted, string values single-quote
+  // escaped, numerics rendered after a finite-check below).
   var stmts = [];
   if (opts.role) {
-    stmts.push('SET ROLE "' + opts.role + '"');
+    stmts.push('SET ROLE "' + opts.role + '"');   // allow:hand-rolled-sql — Postgres session SET (no table; not a b.sql verb)
   }
   if (pathSegments) {
     var pathSql = pathSegments.map(function (s) { return '"' + s + '"'; }).join(", ");
-    stmts.push("SET search_path TO " + pathSql);
+    stmts.push("SET search_path TO " + pathSql);   // allow:hand-rolled-sql — Postgres session SET (no table; not a b.sql verb)
   }
   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 + "'");
+    stmts.push("SET application_name TO '" + an + "'");   // allow:hand-rolled-sql — Postgres session SET (no table; not a b.sql verb)
   }
   if (opts.statementTimeoutMs !== undefined) {
-    stmts.push("SET statement_timeout TO " + opts.statementTimeoutMs);
+    stmts.push("SET statement_timeout TO " + opts.statementTimeoutMs);   // allow:hand-rolled-sql — Postgres session SET (no table; not a b.sql verb)
   }
   if (opts.gucs) {
     for (var gn in opts.gucs) {
@@ -2467,11 +2476,12 @@ async function assertRoleHardening(opts) {
   var ignoreSystem = opts.ignoreSystem !== false;   // default true
   var rows;
   try {
-    var res = await query(
-      "SELECT rolname FROM pg_roles ORDER BY rolname",
-      [],
-      { backend: backendName }
-    );
+    // pg_roles is a Postgres system catalog (this path is Postgres-only —
+    // guarded above), so b.sql emits the bare unquoted catalog name with a
+    // quoted projection. No params, no `?`, so no placeholder translation.
+    var rolesBuilt = sql().select("pg_roles", { dialect: "postgres" })
+      .columns(["rolname"]).orderBy("rolname", "asc").toSql();
+    var res = await query(rolesBuilt.sql, rolesBuilt.params, { backend: backendName });
     rows = (res && res.rows) || [];
   } catch (e) {
     audit().safeEmit({

package/lib/file-upload.js

@@ -22,8 +22,12 @@
  *   content gate inspects the reassembled buffer, so it runs on uploads
  *   up to `maxStreamReassemblyBytes` (default 64 MiB); a larger upload
  *   is handed to `onFinalize` as a stream and the byte-content gate is
- *   skipped (MIME-sniff + filename gates still run, and the skip emits a
- *   `fileUpload.content_safety_skipped` warning audit). To guarantee
+ *   skipped (MIME-sniff + filename gates still run). Every skip path —
+ *   the upload streamed past the reassembly cap, no gate is registered
+ *   for the file's extension, or `contentSafety: null` disabled scanning
+ *   — emits a `fileUpload.content_safety_skipped` audit whose `reason`
+ *   names the cause, so a security review of the audit log can tell which
+ *   uploads reached storage without a content scan and why. To guarantee
  *   content-gating of a type, cap `maxFileBytes` at or below
  *   `maxStreamReassemblyBytes`. Per-chunk hooks
  *   (`onChunk`) are the integration point for virus scanners and
@@ -475,6 +479,32 @@ function create(opts) {
     if (opts.observability) opts.observability.safeEvent(name, value, labels || {});
   }
 
+  // Emit an audit row whenever the byte-level content-safety scan is
+  // SKIPPED for a finalized upload — so a security review of the audit
+  // log can tell that bytes reached storage without passing the
+  // content gate, and WHY. Without this, every skip path (operator
+  // opt-out, no gate registered for the file's extension, or the upload
+  // streamed past maxStreamReassemblyBytes) was silent: the audit log
+  // showed a clean `fileUpload.finalize` success indistinguishable from
+  // a scanned upload. `reason` names the skip cause so operators can
+  // alert / lower maxStreamReassemblyBytes / register the missing gate.
+  // Observability-only: `_emitAudit` wraps audit.safeEmit in try/catch
+  // (drop-silent — by design) so a throwing sink never breaks the upload.
+  function _emitContentSafetySkipped(uploadId, actor, reason, ext, size) {
+    _emitObs("fileUpload.content_safety_skipped", 1, { reason: reason, ext: ext || "" });
+    // outcome "success" — the upload itself finalized; the audit records
+    // that the byte-level scan did NOT run, with `reason` naming why
+    // (the only outcomes the audit chain accepts are success / failure /
+    // denied, so the skip-cause lives in `reason` + `metadata`).
+    _emitAudit("fileUpload.content_safety_skipped", {
+      actor:    requestHelpers.extractActorContext(actor),
+      resource: { kind: "fileUpload", id: uploadId },
+      outcome:  "success",
+      reason:   reason,
+      metadata: { uploadId: uploadId, ext: ext || null, size: size, reason: reason },
+    });
+  }
+
   // Staging dir mode 0o700 — only the framework process reads its own
   // staging files.
   atomicFile.ensureDir(stagingDir, 0o700);
@@ -1088,12 +1118,27 @@ function create(opts) {
         // upload streamed past maxStreamReassemblyBytes and was never
         // reassembled into a buffer the byte-level gate can inspect. The
         // MIME-sniff and filename gates still ran; the per-extension
-        // content gate did NOT. Surface it (rather than skipping silently)
-        // via an observability counter so operators can alert, lower
-        // maxStreamReassemblyBytes, or cap maxFileBytes to force
-        // content-gating of this type.
-        _emitObs("fileUpload.content_safety_skipped_streamed", 1, { ext: safetyExt });
+        // content gate did NOT. Audit the skip (with the streamed reason)
+        // so operators can alert, lower maxStreamReassemblyBytes, or cap
+        // maxFileBytes to force content-gating of this type.
+        _emitContentSafetySkipped(uploadId, actor, "streamed-over-reassembly-cap",
+                                  safetyExt, verified.totalBytes);
+      } else {
+        // contentSafety is wired but no gate is registered for this file's
+        // extension — the byte-level scan does not run. Audit the skip so
+        // a review can tell the upload bypassed content scanning (and
+        // register a gate for the extension if it should be scanned).
+        _emitContentSafetySkipped(uploadId, actor, "no-gate-for-extension",
+                                  safetyExt, verified.totalBytes);
       }
+    } else {
+      // Content-safety scanning is disabled for this upload manager
+      // (contentSafety: null opt-out at create()). The create-time audit
+      // recorded the disable; this per-upload audit makes the bypass
+      // visible at the point bytes reached storage.
+      _emitContentSafetySkipped(uploadId, actor, "content-safety-disabled",
+                                nodePath.extname(filename).toLowerCase(),
+                                verified.totalBytes);
     }
 
     // Hand to operator's onFinalize.

package/lib/framework-error.js

@@ -215,6 +215,16 @@ var GuardSvgError         = defineClass("GuardSvgError",         { alwaysPermane
 // (Windows strips them silently), unicode bidi/RTLO file-name spoofing,
 // overlong UTF-8 encoding, length caps. alwaysPermanent.
 var GuardFilenameError    = defineClass("GuardFilenameError",    { alwaysPermanent: true });
+// GuardSqlError covers raw-SQL refusals from the b.guardSql guard: the
+// OS-reach floor (file / exec / FDW / extension / privilege-pivot
+// across Postgres / SQLite / MySQL), stacked statements, comment
+// smuggling, embedded string literals in a fragment, invalid UTF-8
+// (CVE-2025-1094 encoding-bypass class), time-based probes, schema
+// recon, and the migration DDL-verb allowlist. DOT-style codes
+// (sql.refuse / sql.stacked / sql.file-access / ...) so they don't
+// collide with SafeSqlError's slash codes (sql/bad-shape / ...).
+// alwaysPermanent.
+var GuardSqlError         = defineClass("GuardSqlError",         { alwaysPermanent: true });
 // GuardArchiveError covers archive-shape violations: zip-slip path
 // traversal, symlink + hardlink escape, decompression-ratio bombs,
 // nested-archive depth, file-count + total-size + per-entry-size caps,
@@ -557,7 +567,9 @@ var WatcherError          = defineClass("WatcherError",          { alwaysPermane
 // caller-shape misuse or an irrecoverable on-disk condition.
 var LocalDbThinError      = defineClass("LocalDbThinError",      { alwaysPermanent: true });
 // RouterError covers operator-shape violations on the router primitive:
-// invalid `allowedRedirectOrigins` opt at create time, and cross-origin
+// invalid `allowedRedirectOrigins` opt at create time, a malformed
+// `use()` mount (non-string / non-array prefix, a prefix not beginning
+// with "/", a missing or non-function middleware), and cross-origin
 // `res.redirect()` targets that are not on the allowlist. alwaysPermanent
 // — every case is config-time programming bug or an outbound-redirect
 // shape error that retry will not recover.
@@ -685,6 +697,7 @@ module.exports = {
   GuardHtmlError:         GuardHtmlError,
   GuardSvgError:          GuardSvgError,
   GuardFilenameError:     GuardFilenameError,
+  GuardSqlError:          GuardSqlError,
   GuardArchiveError:      GuardArchiveError,
   GuardJsonError:         GuardJsonError,
   GuardYamlError:         GuardYamlError,

package/lib/framework-files.js

@@ -0,0 +1,73 @@
+"use strict";
+
+// framework-files — the single source of truth for the framework's on-disk
+// state file names. Centralized (mirroring framework-schema's table-name
+// registry) so a rename / relocation is a one-line change and no module
+// hardcodes the literal. Every owner resolves its file name through
+// fileName(logical) instead of embedding the string; the codebase-patterns
+// `no-hardcoded-framework-file-name` detector drives the remaining owners
+// onto this registry in reverse (a file that still hardcodes a registered
+// name fails the gate once it leaves the migration backlog).
+//
+// Internal infrastructure (not a public b.* namespace) — consumed by db /
+// vault / audit / backup the way constants.js is.
+
+var { FrameworkError } = require("./framework-error");
+
+// Canonical state file names. Each is a BARE file name (no path) joined onto
+// the operator's dataDir / a sub-path by the owner. Security-/durability-
+// sensitive files only — templated names (e.g. the hashed working-db file)
+// are not registered here.
+var DEFAULT_FILE_NAMES = Object.freeze({
+  dbEnc:         "db.enc",          // encrypted-at-rest database ciphertext
+  dbKeyEnc:      "db.key.enc",      // sealed database encryption key
+  vaultKey:      "vault.key",       // sealed vault keypair
+  auditTip:      "audit.tip",       // audit rollback-detection sidecar
+  auditSignKey:  "audit-sign.key",  // sealed audit-signing keypair
+  rowsEnc:       "rows.enc",        // archive/backup rows ciphertext member
+  checkpointEnc: "checkpoint.enc",  // archive/backup checkpoint ciphertext member
+});
+
+var _overrides = {};
+
+// fileName(logical) — resolve a logical file key to its configured (or
+// default) bare file name. Defensive request-shape reader: throws on an
+// unknown logical key (a typo is a boot-time bug, not a runtime default).
+function fileName(logical) {
+  if (Object.prototype.hasOwnProperty.call(_overrides, logical)) return _overrides[logical];
+  if (Object.prototype.hasOwnProperty.call(DEFAULT_FILE_NAMES, logical)) {
+    return DEFAULT_FILE_NAMES[logical];
+  }
+  throw new FrameworkError(
+    "frameworkFiles.fileName: unknown logical file '" + logical + "'",
+    "framework-files/unknown");
+}
+
+// setFileName(logical, name) — config-time override of a state file name.
+// THROW on bad input (entry-point tier): the override must name a known
+// logical key and be a bare file name (no path separators, no '..') so it
+// can't redirect a sealed-key write outside the data dir.
+function setFileName(logical, name) {
+  if (!Object.prototype.hasOwnProperty.call(DEFAULT_FILE_NAMES, logical)) {
+    throw new FrameworkError(
+      "frameworkFiles.setFileName: unknown logical file '" + logical + "'",
+      "framework-files/unknown");
+  }
+  if (typeof name !== "string" || name.length === 0 ||
+      name.indexOf("/") !== -1 || name.indexOf("\\") !== -1 || name.indexOf("..") !== -1) {
+    throw new FrameworkError(
+      "frameworkFiles.setFileName: name must be a non-empty bare file name " +
+      "(no path separators or '..')", "framework-files/bad-name");
+  }
+  _overrides[logical] = name;
+}
+
+// Test/boot helper — drop all overrides back to the defaults.
+function _resetForTest() { _overrides = {}; }
+
+module.exports = {
+  fileName:          fileName,
+  setFileName:       setFileName,
+  DEFAULT_FILE_NAMES: DEFAULT_FILE_NAMES,
+  _resetForTest:     _resetForTest,
+};