@blamejs/core 0.14.26 → 0.15.0

package/lib/guard-yaml.js

@@ -553,12 +553,8 @@ function parse(input, opts) {
     throw _err("yaml.bad-input", "parse requires string input");
   }
   var issues = _detectIssues(input, opts);
-  for (var i = 0; i < issues.length; i += 1) {
-    if (issues[i].severity === "critical") {
-      throw _err(issues[i].ruleId || "yaml.refused",
-        "guardYaml.parse: " + issues[i].snippet);
-    }
-  }
+  gateContract.throwOnRefusalSeverity(issues,
+    { errorClass: GuardYamlError, codePrefix: "yaml", severities: ["critical"], op: "parse" });
   return safeYamlLazy().parse(input, {
     maxBytes:  opts.maxBytes,
     maxDepth:  opts.maxDepth,
@@ -566,161 +562,53 @@ function parse(input, opts) {
   });
 }
 
-/**
- * @primitive  b.guardYaml.gate
- * @signature  b.guardYaml.gate(opts?)
- * @since      0.7.14
- * @status     stable
- * @compliance hipaa, pci-dss, gdpr, soc2
- * @related    b.guardYaml.validate, b.guardYaml.parse, b.staticServe.create, b.fileUpload.create
- *
- * Build a `b.gateContract` gate suitable for plugging into
- * `b.staticServe({ contentSafety: { ".yaml": gate } })`,
- * `b.fileUpload({ contentSafety: { "application/yaml": gate } })`,
- * or any host primitive that consumes the gate-contract shape.
- * Action chain on validation: `serve` (no issues) → `audit-only`
- * (warn-only issues) → `refuse` (any high/critical issue). YAML
- * sanitize is intentionally not offered — there's no safe re-emit
- * for tag-injection / alias-explosion shapes; the only correct
- * response is refusal.
- *
- * @opts
- *   profile:    "strict"|"balanced"|"permissive",
- *   compliancePosture: "hipaa"|"pci-dss"|"gdpr"|"soc2",
- *   name:       string,    // gate identity for audit / observability
- *
- * @example
- *   var yamlGate = b.guardYaml.gate({ profile: "strict" });
- *   var hostile = Buffer.from("!!python/object/new:cls\nargs: [x]\n", "utf8");
- *   var verdict = await yamlGate.check({ bytes: hostile });
- *   verdict.action;                                     // → "refuse"
- */
-function gate(opts) {
-  opts = _resolveOpts(opts);
-  return gateContract.buildGuardGate(
-    opts.name || "guardYaml:" + (opts.profile || "default"),
-    opts,
-    async function (ctx) {
-      var text = gateContract.extractBytesAsText(ctx);
-      if (!text) return { ok: true, action: "serve" };
-      var rv = validate(text, opts);
-      if (rv.issues.length === 0) return { ok: true, action: "serve" };
-      var hasCritical = rv.issues.some(function (i) {
-        return i.severity === "critical" || i.severity === "high";
-      });
-      if (!hasCritical) return { ok: true, action: "audit-only", issues: rv.issues };
-      return { ok: false, action: "refuse", issues: rv.issues };
-    });
-}
-
-/**
- * @primitive  b.guardYaml.buildProfile
- * @signature  b.guardYaml.buildProfile(opts)
- * @since      0.7.14
- * @status     stable
- * @related    b.guardYaml.gate, b.guardYaml.compliancePosture
- *
- * Compose a derived profile from one or more named bases plus
- * inline overrides. `opts.extends` is a profile name (`"strict"` /
- * `"balanced"` / `"permissive"`) or an array of names; later entries
- * shadow earlier ones. Inline `opts` keys win last. Used to keep
- * operator-defined profiles traceable to a baseline rather than re-
- * typing every key.
- *
- * @opts
- *   extends: string|string[],   // base profile name(s) to compose
- *   ...:     any guard-yaml key, // inline override of resolved keys
- *
- * @example
- *   var custom = b.guardYaml.buildProfile({
- *     extends: "balanced",
- *     tagPolicy: "reject",
- *     maxAnchors: 8,
- *   });
- *   custom.tagPolicy;                                   // → "reject"
- *   custom.maxAnchors;                                  // → 8
- */
-var buildProfile = gateContract.makeProfileBuilder(PROFILES);
-
-/**
- * @primitive  b.guardYaml.compliancePosture
- * @signature  b.guardYaml.compliancePosture(name)
- * @since      0.7.14
- * @status     stable
- * @compliance hipaa, pci-dss, gdpr, soc2
- * @related    b.guardYaml.gate, b.guardYaml.buildProfile
- *
- * Look up a compliance-posture overlay by name (`"hipaa"` /
- * `"pci-dss"` / `"gdpr"` / `"soc2"`). Returns a shallow clone of the
- * posture object — the caller may mutate freely. Throws
- * `GuardYamlError("yaml.bad-posture")` on unknown name.
- *
- * @example
- *   var posture = b.guardYaml.compliancePosture("hipaa");
- *   posture.tagPolicy;                                  // → "reject"
- *   posture.forensicSnippetBytes;                       // → 256
- */
-function compliancePosture(name) {
-  return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES, _err, "yaml");
-}
+// The gate is the standard serve -> audit-only -> refuse chain (content
+// kind, reading ctx.bytes); it is assembled by gateContract.defineGuard's
+// default gate below. YAML sanitize is intentionally not offered — there's
+// no safe re-emit for tag-injection / alias-explosion shapes; the only
+// correct response is refusal, which the default chain (no sanitize action)
+// matches exactly. Its "guardYaml:<profile>" gate name and
+// serve/audit-only/refuse decisions are identical to the hand-written gate
+// this replaced.
+
+// buildProfile / compliancePosture / loadRulePack are assembled by
+// gateContract.defineGuard below; their wiki sections render from the
+// single-sourced @abiTemplate (defineGuard) blocks in gate-contract.js,
+// instantiated per guard by the page generator.
+
+var INTEGRATION_FIXTURES = Object.freeze({
+  kind:         "content",
+  contentType:  "application/yaml",
+  extension:    ".yaml",
+  benignBytes:  Buffer.from('name: alice\nage: 30\n', "utf8"),
+  // Hostile: deserialization-tag injection (CVE-2026-24009 PyYAML
+  // class). Parser-runtime would attempt to instantiate the named
+  // language-specific class.
+  hostileBytes: Buffer.from("!!python/object/new:cls\nargs: [\"x\"]\n", "utf8"),
+});
 
-var _yamlRulePacks = gateContract.makeRulePackLoader(GuardYamlError, "yaml");
-/**
- * @primitive  b.guardYaml.loadRulePack
- * @signature  b.guardYaml.loadRulePack(pack)
- * @since      0.7.14
- * @status     stable
- * @related    b.guardYaml.gate
- *
- * Register an operator-supplied rule pack with the guard-yaml
- * registry. The pack is identified by `pack.id` (non-empty string)
- * and stored for later inspection / dispatch by gates that opt in
- * via `opts.rulePackId`. Returns the pack object unchanged on
- * success; throws `GuardYamlError("yaml.bad-opt")` when `pack` is
- * missing or `pack.id` is not a non-empty string.
- *
- * @example
- *   var pack = b.guardYaml.loadRulePack({
- *     id: "deploy-keys",
- *     rules: [
- *       { id: "no-image-latest", severity: "high",
- *         detect: function (text) { return /image:\s*\S+:latest\b/.test(text); },
- *         reason: "deployment YAML must pin image tag (no :latest)" },
- *     ],
- *   });
- *   pack.id;                                            // → "deploy-keys"
- */
-var loadRulePack = _yamlRulePacks.load;
-
-module.exports = {
-  // ---- guard-* family registry exports ----
-  NAME:                "yaml",
-  KIND:                "content",
-  MIME_TYPES:          Object.freeze([
-    "application/yaml", "application/x-yaml", "text/yaml", "text/x-yaml",
-  ]),
-  EXTENSIONS:          Object.freeze([".yml", ".yaml"]),
-  INTEGRATION_FIXTURES: Object.freeze({
-    kind:         "content",
-    contentType:  "application/yaml",
-    extension:    ".yaml",
-    benignBytes:  Buffer.from('name: alice\nage: 30\n', "utf8"),
-    // Hostile: deserialization-tag injection (CVE-2026-24009 PyYAML
-    // class). Parser-runtime would attempt to instantiate the named
-    // language-specific class.
-    hostileBytes: Buffer.from("!!python/object/new:cls\nargs: [\"x\"]\n", "utf8"),
-  }),
-  // ---- primitive surface ----
-  validate:            validate,
-  parse:               parse,
-  gate:                gate,
-  buildProfile:        buildProfile,
-  compliancePosture:   compliancePosture,
-  loadRulePack:        loadRulePack,
-  PROFILES:            PROFILES,
-  DEFAULTS:            DEFAULTS,
-  COMPLIANCE_POSTURES: COMPLIANCE_POSTURES,
-  DANGEROUS_TAG_PREFIXES: DANGEROUS_TAG_PREFIXES,
-  SAFE_CORE_TAGS:      SAFE_CORE_TAGS,
-  GuardYamlError:      GuardYamlError,
-};
+// Assembled from the gate-contract guard factory: error class, registry
+// exports (NAME / KIND / MIME_TYPES / EXTENSIONS / INTEGRATION_FIXTURES),
+// buildProfile / compliancePosture / loadRulePack wiring, plus the
+// per-guard inspection surface (validate) and YAML extras
+// (parse / DANGEROUS_TAG_PREFIXES / SAFE_CORE_TAGS) passed through
+// verbatim. The gate is the factory default serve/audit-only/refuse chain
+// (content kind, no sanitize action — there's no safe re-emit for
+// tag-injection / alias-explosion shapes).
+module.exports = gateContract.defineGuard({
+  name:        "yaml",
+  kind:        "content",
+  errorClass:  GuardYamlError,
+  profiles:    PROFILES,
+  defaults:    DEFAULTS,
+  postures:    COMPLIANCE_POSTURES,
+  mimeTypes:   ["application/yaml", "application/x-yaml", "text/yaml", "text/x-yaml"],
+  extensions:  [".yml", ".yaml"],
+  integrationFixtures: INTEGRATION_FIXTURES,
+  validate:    validate,
+  extra: {
+    parse:                  parse,
+    DANGEROUS_TAG_PREFIXES: DANGEROUS_TAG_PREFIXES,
+    SAFE_CORE_TAGS:         SAFE_CORE_TAGS,
+  },
+});

package/lib/http-client.js

@@ -275,6 +275,9 @@ function _connectHttpsWithAlpn(u, ips) {
     session.once("connect", function () {
       var alpn = session.alpnProtocol;
       if (alpn === "h2") {
+        // node:http2 connects directly (not via pqcAgent), so observe the
+        // negotiated group here too and audit a classical (non-PQC) downgrade.
+        pqcAgent._auditClassicalDowngrade(session.socket, { host: u.hostname, port: u.port });
         _wireH2Session(session, _originKey(u));
         _done({ kind: "h2", session: session });
         return;
@@ -285,6 +288,17 @@ function _connectHttpsWithAlpn(u, ips) {
     });
     session.once("error", function (err) {
       _tearDownH2Session(session);
+      // An HTTP/1.1-only TLS server has no "h2" to select and replies with
+      // the no_application_protocol alert (RFC 7301). node:http2 forces an
+      // h2-only ALPN offer, so the connect event never fires for such a
+      // server and the http/1.1-selection fallback above can't run — catch
+      // the alert here and fall back to an h1 transport for this origin.
+      // Real Azure / S3 / Keycloak support h2; Azurite, Azure Stack, and
+      // many private / older endpoints are h1-only.
+      if (err && err.code === "ERR_SSL_TLSV1_ALERT_NO_APPLICATION_PROTOCOL") {
+        _done(_makeH1Transport(u, ips));
+        return;
+      }
       _fail(err);
     });
   });
@@ -1925,7 +1939,21 @@ async function downloadStream(opts) {
   });
   counter.bytesWritten = 0;
 
-  var fileStream = nodeFs.createWriteStream(tmpPath, { mode: DEFAULT_DOWNLOAD_FILE_MODE, flags: "w" });
+  // CWE-377 (insecure temporary file) / CWE-59 (symlink follow): stage
+  // the download into the sibling tmp file with an EXCLUSIVE, no-follow
+  // create. The legacy "w" flag is O_WRONLY|O_CREAT|O_TRUNC — it would
+  // open (and truncate, or write through) a file an attacker pre-planted
+  // at tmpPath, including a symlink aimed at a victim path this process
+  // can write. O_EXCL fails with EEXIST if anything already exists at
+  // tmpPath; O_NOFOLLOW rejects a symlink in the final path component
+  // where the platform defines it (Windows leaves it undefined → `|| 0`).
+  // tmpPath already carries a 64-bit CSPRNG suffix (line above), so an
+  // EEXIST here is a hostile-collision signal, not a benign retry.
+  var fileStream = nodeFs.createWriteStream(tmpPath, {
+    mode:  DEFAULT_DOWNLOAD_FILE_MODE,
+    flags: nodeFs.constants.O_WRONLY | nodeFs.constants.O_CREAT |
+           nodeFs.constants.O_EXCL | (nodeFs.constants.O_NOFOLLOW || 0),
+  });
 
   try {
     await streamPromises.pipeline(res.body, counter, fileStream);
@@ -1944,14 +1972,14 @@ async function downloadStream(opts) {
   // across platforms but matches the discipline of the rest of the
   // framework's atomic-write paths.
   //
-  // CodeQL js/insecure-temporary-file: tmpPath = dest + ".tmp-" +
-  // bCrypto.generateToken(C.BYTES.bytes(8)) (line 1802), where
-  // bCrypto.generateToken produces 16 hex chars of CSPRNG-derived
-  // randomness. The path lives next to operator-supplied `dest`
-  // (downloadStream contract — never under os.tmpdir()), and the
-  // 64-bit unpredictable suffix defeats the symlink-pre-creation
-  // attack the rule flags. The fd is used solely for fsync; the
-  // file's bytes were already written by the upstream pipeline.
+  // CodeQL js/insecure-temporary-file (CWE-377 / CWE-59): the tmp file
+  // was already created above with O_EXCL | O_NOFOLLOW, so this reopen
+  // binds to an inode this process exclusively created at a path
+  // carrying a 64-bit CSPRNG suffix (line above) next to operator-
+  // supplied `dest` (downloadStream contract — never under os.tmpdir()).
+  // The earlier exclusive create — not the reopen — is the symlink-
+  // pre-creation defense; this fd is used solely for fsync, after the
+  // upstream pipeline already wrote the bytes.
   try {
     var fd = nodeFs.openSync(tmpPath, "r+");
     try { atomicFile.fsync(fd); } finally { try { nodeFs.closeSync(fd); } catch (_c) { /* best-effort fd close */ } }

package/lib/inbox.js

@@ -46,6 +46,7 @@ var C = require("./constants");
 var lazyRequire = require("./lazy-require");
 var safeJson = require("./safe-json");
 var safeSql = require("./safe-sql");
+var sql = require("./sql");
 var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
 
@@ -63,14 +64,19 @@ function _validateTableName(name) {
   }
 }
 
-function _utcNowExpr(externalDb) {
-  // Both backends accept this expression; SQLite returns ISO-8601,
-  // Postgres returns timestamptz.
-  if (externalDb && typeof externalDb.dialect === "string" &&
-      externalDb.dialect === "postgres") {
-    return "NOW()";
-  }
-  return "CURRENT_TIMESTAMP";
+// Map the operator backend's dialect tag to the b.sql dialect vocabulary
+// (postgres -> $1..$N at toExternalSql; sqlite/other -> `?`).
+function _sqlDialect(externalDb) {
+  return (externalDb && externalDb.dialect === "postgres") ? "postgres" : "sqlite";
+}
+
+// The server-clock timestamp expression, as an allowlisted b.sql function
+// cell (emits the keyword the engine evaluates, binds no param). Postgres
+// returns timestamptz from NOW(); the portable CURRENT_TIMESTAMP serves
+// sqlite. Used directly in a b.sql values()/set() cell.
+function _utcNowCell(externalDb) {
+  return (externalDb && externalDb.dialect === "postgres")
+    ? sql.fn("NOW") : sql.fn("CURRENT_TIMESTAMP");
 }
 
 /**
@@ -144,12 +150,9 @@ function create(opts) {
 
   var externalDb     = opts.externalDb;
   var tableRaw       = opts.table;
-  // Identifiers reach SQL through safeSql.quoteIdentifier — runs
-  // validateIdentifier internally + emits the dialect-correct quoted
-  // form. sqlite + postgres both use the double-quote dialect (per
-  // lib/safe-sql.js), so one quoted form serves both inbox paths.
-  var qTable         = safeSql.quoteIdentifier(tableRaw, "sqlite");
-  var qIndex         = safeSql.quoteIdentifier(tableRaw + "_received_at_idx", "sqlite");
+  // The table identifier reaches SQL through b.sql, which validates +
+  // quotes it by construction on every emitted statement; _validateTableName
+  // above fails fast at create() time on a bad name.
   var retentionDays  = (typeof opts.retentionDays === "number" && opts.retentionDays > 0)        // allow:numeric-opt-Infinity
     ? opts.retentionDays : 30;                                                                   // default retention days
   var auditOn        = opts.audit !== false;
@@ -227,43 +230,38 @@ function create(opts) {
       }
       metaJson = serialized;
     }
-    var nowExpr = _utcNowExpr(externalDb);
-    var dialect = (externalDb.dialect === "postgres") ? "postgres" : "sqlite";
+    var dialect = _sqlDialect(externalDb);
+    var nowCell = _utcNowCell(externalDb);
 
-    if (dialect === "postgres") {
-      var rs = await txn.query(
-        "INSERT INTO " + qTable +
-        " (message_id, source, received_at, metadata_json) " +
-        " VALUES ($1, $2, " + nowExpr + ", $3::jsonb) " +
-        " ON CONFLICT (source, message_id) DO NOTHING " +
-        " RETURNING message_id",
-        [receiveOpts.messageId, receiveOpts.source, metaJson]);
-      var fresh = rs && rs.rows && rs.rows.length === 1;
-      _emitAudit("inbox.received", "success", {
-        source: receiveOpts.source, messageId: receiveOpts.messageId,
-        fresh: fresh,
-      });
-      return fresh;
-    }
-
-    // SQLite path — INSERT OR IGNORE ... RETURNING 1 (SQLite 3.35+,
-    // March 2021). The previous two-statement INSERT + SELECT
-    // changes() pattern raced when callers issued an intervening
-    // statement on the same txn handle (e.g. trace logging) — a
-    // legitimate use case on the public recordReceive(opts, txn) API
-    // that the framework can't prevent. RETURNING 1 collapses both
-    // round-trips into one and removes the changes() dependency.
-    var sqlInsert = await txn.query(
-      "INSERT OR IGNORE INTO " + qTable +
-      " (message_id, source, received_at, metadata_json) " +
-      " VALUES (?, ?, " + nowExpr + ", ?) RETURNING 1",
-      [receiveOpts.messageId, receiveOpts.source, metaJson]);
-    var sqlFresh = !!(sqlInsert && sqlInsert.rows && sqlInsert.rows.length === 1);
+    // ON CONFLICT (source, message_id) DO NOTHING RETURNING message_id:
+    // a fresh insert returns one row, a duplicate redelivery returns none
+    // (the collision short-circuits). received_at takes the server-clock
+    // function cell (NOW() / CURRENT_TIMESTAMP, no param); metadata_json
+    // binds with a ::jsonb cast on Postgres and as a plain `?` on sqlite.
+    // RETURNING message_id (rather than RETURNING 1) is the portable
+    // presence sentinel - one row iff the insert landed - across both
+    // dialects, collapsing the prior INSERT-then-SELECT-changes() race
+    // into one round-trip on sqlite too.
+    var metaCell = (dialect === "postgres") ? sql.cast(metaJson, "jsonb") : metaJson;
+    var stmt = sql.upsert(tableRaw, { dialect: dialect })
+      .columns(["message_id", "source", "received_at", "metadata_json"])
+      .values({
+        message_id:    receiveOpts.messageId,
+        source:        receiveOpts.source,
+        received_at:   nowCell,
+        metadata_json: metaCell,
+      })
+      .onConflict(["source", "message_id"])
+      .doNothing()
+      .returning(["message_id"])
+      .toExternalSql(dialect);
+    var rs = await txn.query(stmt.sql, stmt.params);
+    var fresh = !!(rs && rs.rows && rs.rows.length === 1);
     _emitAudit("inbox.received", "success", {
       source: receiveOpts.source, messageId: receiveOpts.messageId,
-      fresh: sqlFresh,
+      fresh: fresh,
     });
-    return sqlFresh;
+    return fresh;
   }
 
   async function markProcessed(receiveOpts, txn) {
@@ -272,13 +270,13 @@ function create(opts) {
         "markProcessed: txn must be a transaction handle");
     }
     _validateReceiveOpts(receiveOpts, "markProcessed");
-    var nowExpr = _utcNowExpr(externalDb);
-    var dialect = (externalDb.dialect === "postgres") ? "postgres" : "sqlite";
-    var sql = "UPDATE " + qTable +
-              " SET processed_at = " + nowExpr +
-              " WHERE source = " + (dialect === "postgres" ? "$1" : "?") +
-              " AND message_id = " + (dialect === "postgres" ? "$2" : "?");
-    await txn.query(sql, [receiveOpts.source, receiveOpts.messageId]);
+    var dialect = _sqlDialect(externalDb);
+    var stmt = sql.update(tableRaw, { dialect: dialect })
+      .set({ processed_at: _utcNowCell(externalDb) })
+      .where("source", receiveOpts.source)
+      .where("message_id", receiveOpts.messageId)
+      .toExternalSql(dialect);
+    await txn.query(stmt.sql, stmt.params);
   }
 
   async function handle(receiveOpts, handler) {
@@ -321,56 +319,65 @@ function create(opts) {
   }
 
   async function declareSchema(xdb) {
-    var dialect = (xdb && xdb.dialect === "postgres") ? "postgres" : "sqlite";
-    if (dialect === "postgres") {
-      await xdb.query(
-        "CREATE TABLE IF NOT EXISTS " + qTable + " (" +
-        "  message_id   TEXT NOT NULL," +
-        "  source       TEXT NOT NULL," +
-        "  received_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()," +
-        "  processed_at TIMESTAMPTZ NULL," +
-        "  metadata_json JSONB NULL," +
-        "  PRIMARY KEY (source, message_id)" +
-        ")");
-      await xdb.query(
-        "CREATE INDEX IF NOT EXISTS " + qIndex + " " +
-        "ON " + qTable + " (received_at)");
-    } else {
-      await xdb.query(
-        "CREATE TABLE IF NOT EXISTS " + qTable + " (" +
-        "  message_id   TEXT NOT NULL," +
-        "  source       TEXT NOT NULL," +
-        "  received_at  TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP," +
-        "  processed_at TEXT NULL," +
-        "  metadata_json TEXT NULL," +
-        "  PRIMARY KEY (source, message_id)" +
-        ")");
-      await xdb.query(
-        "CREATE INDEX IF NOT EXISTS " + qIndex + " " +
-        "ON " + qTable + " (received_at)");
-    }
+    var dialect = _sqlDialect(xdb);
+    // received_at / processed_at are a timestamp-with-zone column on
+    // Postgres and a TEXT (ISO-8601) column on sqlite; metadata_json is
+    // JSONB on Postgres and TEXT on sqlite. The composite (source,
+    // message_id) primary key is the dedupe collision boundary. Verbatim
+    // type strings sit in type position after the quoted column name.
+    var tsType = dialect === "postgres" ? "TIMESTAMPTZ" : "TEXT";
+    var tsDefault = dialect === "postgres" ? "NOW()" : "CURRENT_TIMESTAMP";
+    var jsonType = dialect === "postgres" ? "JSONB" : "TEXT";
+    var ddl = sql.toExternalSql(sql.createTable(tableRaw, [
+      { name: "message_id",    type: "TEXT",   notNull: true },
+      { name: "source",        type: "TEXT",   notNull: true },
+      // The DEFAULT here is a SQL function keyword, not a bound literal -
+      // expressed via the `constraints` verbatim clause so the type map
+      // does not quote NOW() / CURRENT_TIMESTAMP as a string default.
+      { name: "received_at",   type: tsType,   notNull: true, constraints: "DEFAULT " + tsDefault },
+      { name: "processed_at",  type: tsType },
+      { name: "metadata_json", type: jsonType },
+    ], { dialect: dialect, primaryKey: ["source", "message_id"] }), dialect);
+    await xdb.query(ddl.sql, ddl.params);
+
+    var idx = sql.toExternalSql(sql.createIndex(tableRaw + "_received_at_idx", tableRaw,
+      ["received_at"], { dialect: dialect }), dialect);
+    await xdb.query(idx.sql, idx.params);
   }
 
   async function sweep() {
-    var dialect = (externalDb.dialect === "postgres") ? "postgres" : "sqlite";
+    var dialect = _sqlDialect(externalDb);
     var deleted = 0;
     await externalDb.transaction(async function (xdb) {
       if (dialect === "postgres") {
-        var rs = await xdb.query(
-          "DELETE FROM " + qTable +
-          " WHERE received_at < NOW() - $1::interval " +
-          " AND (processed_at IS NOT NULL OR received_at < NOW() - $2::interval)",
-          [retentionDays + " days", (retentionDays * 2) + " days"]);
+        // received_at < NOW() - <retention>::interval, with the
+        // unprocessed grace of 2x retention. The interval STRINGS bind as
+        // a ::interval-cast `?` (the cast value-cell form); NOW() is the
+        // server-clock function token in the predicate (a guarded raw
+        // fragment - no string literal, no bound value).
+        var delStmt = sql.delete(tableRaw, { dialect: "postgres" })
+          .whereRaw("received_at < NOW() - ?::interval", [retentionDays + " days"])
+          .whereRaw("(processed_at IS NOT NULL OR received_at < NOW() - ?::interval)",
+            [(retentionDays * 2) + " days"])
+          .toExternalSql("postgres");
+        var rs = await xdb.query(delStmt.sql, delStmt.params);
         deleted = (rs && typeof rs.rowCount === "number") ? rs.rowCount : 0;
       } else {
         var staleDate = new Date(Date.now() - retentionDays * C.TIME.days(1)).toISOString();
         var unprocStaleDate = new Date(Date.now() - retentionDays * 2 * C.TIME.days(1)).toISOString();
-        await xdb.query(
-          "DELETE FROM " + qTable +
-          " WHERE received_at < ? " +
-          " AND (processed_at IS NOT NULL OR received_at < ?)",
-          [staleDate, unprocStaleDate]);
-        var changedResult = await xdb.query("SELECT changes() AS c");
+        var delSqlite = sql.delete(tableRaw, { dialect: "sqlite" })
+          .where("received_at", "<", staleDate)
+          .whereRaw("(processed_at IS NOT NULL OR received_at < ?)", [unprocStaleDate])
+          .toExternalSql("sqlite");
+        await xdb.query(delSqlite.sql, delSqlite.params);
+        // SELECT changes() reports the row count of the last sqlite write
+        // on this connection. b.sql.catalog has no changes() builder (it
+        // is a sqlite-internal scalar with no table), so emit it through
+        // the same dialect-final terminal as a guarded raw projection on a
+        // zero-table SELECT is not expressible; the single-statement
+        // changes() probe is a fixed, parameter-free sqlite scalar query.
+        var changedResult = await xdb.query(
+          sql.toExternalSql(sql.catalog.changes(), "sqlite").sql);
         var changedRow = changedResult.rows && changedResult.rows[0];
         deleted = changedRow ? Number(changedRow.c) : 0;
       }
@@ -383,12 +390,16 @@ function create(opts) {
 
   async function isFresh(receiveOpts) {
     _validateReceiveOpts(receiveOpts, "isFresh");
-    var dialect = (externalDb.dialect === "postgres") ? "postgres" : "sqlite";
-    var sql = "SELECT 1 FROM " + qTable +
-              " WHERE source = " + (dialect === "postgres" ? "$1" : "?") +
-              " AND message_id = " + (dialect === "postgres" ? "$2" : "?");
+    var dialect = _sqlDialect(externalDb);
+    // SELECT 1 ... is a presence probe; the constant 1 projection is a
+    // builder-emitted raw scalar (no column, no bound value).
+    var stmt = sql.select(tableRaw, { dialect: dialect })
+      .selectRaw("1")
+      .where("source", receiveOpts.source)
+      .where("message_id", receiveOpts.messageId)
+      .toExternalSql(dialect);
     var rs = await externalDb.transaction(async function (xdb) {
-      return await xdb.query(sql, [receiveOpts.source, receiveOpts.messageId]);
+      return await xdb.query(stmt.sql, stmt.params);
     });
     return !rs || !rs.rows || rs.rows.length === 0;
   }
@@ -397,15 +408,17 @@ function create(opts) {
     opts2 = opts2 || {};
     var sourceFilter = (typeof opts2.source === "string" && opts2.source.length > 0)
       ? opts2.source : null;
-    var dialect = (externalDb.dialect === "postgres") ? "postgres" : "sqlite";
+    var dialect = _sqlDialect(externalDb);
     var stats = await externalDb.transaction(async function (xdb) {
-      var sql = "SELECT COUNT(*) AS total," +
-                "       COUNT(processed_at) AS processed " +
-                "  FROM " + qTable +
-                (sourceFilter ? " WHERE source = " +
-                  (dialect === "postgres" ? "$1" : "?") : "");
-      var args = sourceFilter ? [sourceFilter] : [];
-      var rs = await xdb.query(sql, args);
+      // COUNT(*) total + COUNT(processed_at) processed (the latter counts
+      // only non-NULL processed_at, i.e. handled rows), optionally scoped
+      // to one source.
+      var builder = sql.select(tableRaw, { dialect: dialect })
+        .count("*", "total")
+        .count("processed_at", "processed");
+      if (sourceFilter) builder.where("source", sourceFilter);
+      var stmt = builder.toExternalSql(dialect);
+      var rs = await xdb.query(stmt.sql, stmt.params);
       var row = rs.rows && rs.rows[0];
       return {
         total:     row ? Number(row.total) : 0,