@blamejs/core 0.15.2 → 0.15.4

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.15.x
 
+- v0.15.4 (2026-06-12) — **Telemetry attribute values are redacted before they leave the process, per-row data residency is enforced on every write and export path, DDL routes through the single-statement gate, the DPoP middleware requires its replay store, and session rotation re-keys the device binding.** This release closes a set of egress, data-residency, and session-binding gaps. OTLP span, span-event, and resource attributes are now scrubbed through the telemetry redactor before serialization, on both the JSON and protobuf paths, matching the metric exporter - an attribute value holding a bearer token, password, or API key no longer reaches the collector verbatim. Per-row data residency, previously enforced only at the structured query builder, is now enforced on the three paths that bypassed it: raw SQL writes, read-replica fan-out, and backup export. Every CREATE TABLE / ALTER TABLE the schema reconciler and the DSR store emit now passes through the same single-statement gate the query builder uses. The DPoP middleware now requires its replay store at mount time instead of silently mounting a proof-of-possession gate that performed no replay check. And session rotation re-keys the device fingerprint to the new session id, so a rotated session stays bound to its device instead of falsely reporting drift on the next request. **Fixed:** *Session rotation re-keys the device fingerprint to the new session id* — A session's optional device fingerprint is keyed to its session id, so that a stolen database cannot replay the binding. `b.session.rotate` moved the session id but left the stored fingerprint keyed to the old id, so the next `verify` recomputed the fingerprint against the new id and mismatched - reporting a false `fingerprintDrift` (which destroys the session under strict operators, logging the user out on every rotation) or silently breaking the binding. Rotation now re-keys the fingerprint to the new session id from the live request: pass the same `{ req, fingerprintFields }` to `rotate`. A fingerprint-bound session rotated without `req` now throws, because the binding cannot otherwise follow the new id; unbound sessions are unaffected. **Security:** *OTLP exporter redacts span, event, and resource attribute values before egress* — Span, span-event, and resource attributes were serialized to the OTLP collector verbatim on both the JSON and protobuf encodings - the metric exporter scrubbed its attributes through the telemetry redactor, but the span exporter did not. An attribute value carrying a secret or PII (a bearer token in `authorization`, a `password`, an `api_key`) was therefore shipped in clear to whatever collector the deployment points at (CWE-532). Every attribute-map encoder now runs each value through `b.observability.redactAttrs` (default composes `b.redact.redact`, dropping any attribute whose redactor throws) before the wire payload, so telemetry is redacted like the log and audit egress paths. The new `b.observability.redactAttrs(attrs)` is available for operators building custom exporters. · *Per-row data residency is enforced on raw writes, read replicas, and backups* — Per-row residency was enforced only at the structured query builder. Three paths reached storage or left the deployment without it: raw SQL writes (`b.db.runSql` / `b.db.prepare().run()`, INSERT and UPDATE forms) bypassed the local residency check entirely, so a cross-border row could be written under a regulated posture with no refusal; read-replica fan-out dropped the row-residency tag, routing a regulated read with no row region identified to a residency-tagged, non-cross-border replica with no check; and `b.backup.create`'s residency check compared only the single deployment region to the destination, blind to a per-row-residency table that admits rows from several regions. Raw writes now parse the target table and residency value and apply the same gate the builder does; the replica read now fails closed when the row region is unidentified; and backup now emits a per-row cross-border advisory for any declared residency table whose admitted regions differ from the backup destination. · *Schema and DSR DDL routes through the single-statement gate* — The CREATE TABLE / ALTER TABLE statements emitted by the schema reconciler and the DSR ticket store were assembled and run without the single-statement / NUL / unterminated-quote / unbalanced-paren gate that every query the builder emits already passes. That gate is now a shared check both the builder's catalog emitter and the schema/DSR DDL path call, so a terminator, comment marker, or unbalanced quote that reached a DDL fragment is refused at emit time on every backend. · *DPoP middleware requires its replay store at mount time* — `b.middleware.dpop` documented `replayStore` as required, but the factory read it optionally and gated the jti-replay check behind its presence - omitting it mounted a proof-of-possession gate that performed no replay check, so a captured DPoP proof could be replayed indefinitely (RFC 9449 §11.1). The middleware now requires the store at config time: a missing store, or a store lacking `checkAndInsert`, throws when the middleware is created instead of failing open at request time. The low-level `b.auth.dpop.verify` primitive keeps `replayStore` optional for advanced callers that track jti themselves.
+
+- v0.15.3 (2026-06-12) — **DDL hardening in b.sql, schema-confined column introspection on Postgres and MySQL, and a classical-downgrade audit on proxy-tunneled TLS.** This release hardens the data layer and closes a transport audit gap. The b.sql builder refuses an unrecognised column type that carries a statement terminator, quote, or comment marker - the one position in an otherwise quote-by-construction DDL builder where a verbatim string reached the emitted statement - and routes the finished CREATE TABLE through the same single-statement gate every other verb uses. The schema reconciler's column introspection is now confined to the schema or database the bare-named CREATE TABLE actually writes into (current_schema() on Postgres, DATABASE() on MySQL), so a same-named table in another schema no longer pollutes the column set, silently skipping an ADD COLUMN or fabricating false schema drift that refuses a regulated-posture boot. Two further builder gaps are fixed: a column-level primary key combined with a composite primaryKey now fails at build time with a clear error instead of producing invalid DDL, and a MySQL upsert read-back keyed by a cast or a server-evaluated function now renders the cast (or refuses the function) instead of binding an internal wrapper. Finally, an HTTPS request sent through a configured proxy now emits the tls.classical_downgrade audit when the handshake falls back to a classical group, the same as a direct connection. **Fixed:** *Schema reconciliation reads columns from the right schema on Postgres and MySQL* — The reconciler's column introspection queried information_schema with no schema filter, so on a Postgres instance or MySQL server hosting more than one schema/database with a same-named table, the live column set was the union across schemas. That could silently skip an ADD COLUMN the table needed, or report false drift that refuses a boot under a pinned regulated posture. Introspection is now confined to current_schema() (Postgres) / DATABASE() (MySQL) - the schema the bare-named CREATE TABLE lands in. SQLite (PRAGMA, per-file) is unchanged. · *createTable rejects a contradictory primary-key declaration at build time* — Declaring both a column-level primary key (primaryKey / autoIncrement / serial) and a composite opts.primaryKey emitted two PRIMARY KEY clauses, which every dialect rejects at the driver mid-migration. The builder now refuses the contradiction at build time with a clear error; a single column PK, or a composite primaryKey with no column-level PK, is unaffected. · *MySQL upsert read-back resolves a cast or function conflict key instead of binding a wrapper* — On MySQL, an upsert whose conflict key was a b.sql.cast(...) or b.sql.fn(...) built a read-back SELECT that bound the wrapper object, so the read-back matched no rows. A cast conflict key now renders as CAST(? AS type) binding the inner value; a server-evaluated function conflict key (which has no stable read-back identity) is refused with a clear error. Plain scalar conflict keys are unchanged. · *Proxy-tunneled TLS emits the classical-downgrade audit* — An HTTPS upstream reached through a configured proxy performed its TLS handshake without emitting the tls.classical_downgrade audit on a classical-group fallback, leaving the post-quantum-readiness inventory incomplete for proxied requests. Both the upstream handshake and the proxy-leg handshake now emit the audit on a classical fallback, matching the direct connection path. The handshake itself is unchanged (still hybrid-preferred TLSv1.3). **Security:** *b.sql refuses an injection-bearing verbatim column type and gates every CREATE TABLE* — An unrecognised column type passed to b.sql.createTable / alterTable was emitted into the DDL verbatim - the single raw-emission position in a builder that otherwise quotes every identifier and guards every constraint fragment. A type such as "text); DROP TABLE secrets; --" could therefore smuggle a stacked statement. The builder now refuses, at build time, a verbatim type carrying a statement terminator or comment marker, and routes the finished CREATE TABLE / ALTER TABLE statement through the same single-statement / NUL / unterminated-quote / unbalanced-paren gate every SELECT / INSERT / UPDATE / DELETE / UPSERT already used - so an unbalanced quote is caught there. Legitimate types are unaffected: VARCHAR(255), NUMERIC(10,2), DOUBLE PRECISION, TIMESTAMP WITH TIME ZONE, and MySQL ENUM('a','b') / SET(...) (which need balanced quotes) all still pass.
+
 - v0.15.2 (2026-06-12) — **Object keys with a space, +, &, or other reserved characters now sign correctly against S3-compatible stores and Google Cloud Storage.** The SigV4 request signer (and the Google Cloud Storage V4 signer that shares it) URI-encoded the object-key path a second time when building the canonical request it signs, while the request on the wire carried the path encoded once. Amazon S3 — and every S3-compatible store such as MinIO, Cloudflare R2, Wasabi, and Backblaze B2, plus GCS — signs the canonical path encoded exactly once, so any object key containing a space, a +, an &, parentheses, or a non-ASCII character was signed over a path the server never received and the request was rejected with HTTP 403 SignatureDoesNotMatch. Keys built only from unreserved characters were unaffected, which is why the regression went unnoticed. This release makes the canonical-path encoding match the service: S3 and GCS encode the path once, while the AWS services that genuinely require a second encoding (SQS, CloudWatch Logs, SNS) keep it. Object reads, writes, deletes, listings, presigned URLs, and backup or restore through the object-store adapter now succeed for keys with reserved characters. Separately, the bucket-operations key encoder now uses the AWS reserved-character set, so a key containing !, *, ', or ( is escaped to match the bytes the store signs over. **Fixed:** *SigV4 and GCS V4 sign object-key paths with the single encoding S3 and GCS expect* — A request to read, write, delete, list, or presign an object whose key contained a space, +, &, (, ), or a non-ASCII character failed with 403 SignatureDoesNotMatch against S3, every S3-compatible store, and Google Cloud Storage, because the canonical request double-encoded the path the wire carried once. The signer is now service-aware: S3 and GCS sign the path encoded once (matching the wire and the store's own canonicalization), while SQS, CloudWatch Logs, and SNS keep the second encoding the AWS spec requires for those services. No configuration change or migration is needed — object operations and presigned URLs for keys with reserved characters simply start working. Object keys made only of unreserved characters are byte-for-byte unchanged. · *Bucket-operations key encoder escapes the AWS reserved set* — The bucket-level object operations encoded key path segments with a generic URI encoder that left !, *, ', and ( unescaped. Those now route through the same AWS encoder the read and write paths use, so a key containing one of those characters is escaped consistently and signs correctly.
 
 - v0.15.1 (2026-06-11) — **Sealed-column lookups find rows written before the v0.15.0 hash change, and API-key secrets re-hash to the active algorithm on verify.** v0.15.0 changed the default derived hash — the blind index a sealed column is looked up by — from an unkeyed salted hash to a keyed MAC, and promised a transparent migration via a dual read. But no lookup path actually performed the dual read, so on a deployment that already held data, a lookup by a sealed column (a session's user id, an API key's owner, an audit actor or resource, a consent or data-subject id, a mail thread) computed only the new keyed digest and missed every row written before the upgrade. This release wires the dual read into every lookup: a sealed-column equality now matches both the active keyed digest and the legacy salted digest, so pre-upgrade rows are found again. That restores two correctness guarantees the gap had quietly broken — revoking all of a user's sessions no longer skips sessions created before the upgrade, and a subject erasure no longer leaves pre-upgrade rows behind. Separately, the framework's API-key store now re-hashes a stored secret to the active hash algorithm on the next successful verify, the transparent rotation the credential-hash primitive documented but the store had never performed. **Fixed:** *Sealed-column lookups match rows written before the v0.15.0 keyed-MAC change* — After v0.15.0 flipped the default derived-hash mode to a keyed MAC, a lookup by a sealed column computed only the new keyed digest, so rows written under the previous salted-hash default were no longer found — a silent index miss on every existing deployment. Every framework lookup path now dual-reads: `b.db.from(...).where(sealedField, value)` and the framework's own api-key, session, audit, consent, data-subject, and mail-thread lookups match the column against both the active keyed digest and the legacy salted digest (`b.db.hashCandidatesFor` exposes the candidate list for operator code). No migration or operator action is required; rows re-hash to the keyed form on read over time and the candidate set collapses back to a single value. Two correctness consequences are restored: revoking all of a user's sessions now also revokes sessions created before the upgrade, and a data-subject erasure now also deletes (and crypto-shreds) the subject's pre-upgrade rows. · *API-key secret hashes upgrade to the active algorithm on verify* — The framework's API-key store now re-hashes a stored secret to the configured hash algorithm on the next successful verify (leader-gated, best-effort, primary-match only), emitting an `apikey.secret_rehash` audit and observability event. This is the transparent rotation `b.credentialHash` documents — a key stored under an older algorithm or parameter set silently moves to the current one as it is used, with no change to the verify result or the returned record.

package/lib/backup/index.js

@@ -66,6 +66,7 @@ var compliance = lazyRequire(function () { return require("../compliance"); });
 // module graph (CLI tools, stand-alone backup runners). The db()
 // callable resolves on first access.
 var dbModuleLazy = lazyRequire(function () { return require("../db"); });
+var cryptoField = lazyRequire(function () { return require("../crypto-field"); });
 var archiveLazy = lazyRequire(function () { return require("../archive"); });
 var archiveAdaptersLazy = lazyRequire(function () { return require("../archive-adapters"); });
 var { defineClass } = require("../framework-error");
@@ -417,6 +418,37 @@ function create(opts) {
         });
       } catch (_e) { /* drop-silent */ }
     }
+    // Per-row residency blind spot: the deployment-level check above only
+    // compares the single DB region to the destination. A per-row-residency
+    // table is DECLARED (cryptoField.declarePerRowResidency) to admit rows in
+    // several regions; rows tagged to a region other than the backup
+    // destination are a per-row cross-border transfer the deployment compare
+    // cannot see. Surface the declared cross-border regions (policy-based —
+    // no row scan) so the bundle's residency exposure is visible.
+    if (backupResidencyTag) {
+      try {
+        var perRowTables = cryptoField().listPerRowResidency();
+        var perRowCrossBorder = [];
+        for (var pri = 0; pri < perRowTables.length; pri++) {
+          var prt = perRowTables[pri];
+          var offending = (prt.allowedTags || []).filter(function (tag) {
+            return tag !== "global" && tag !== "unrestricted" && tag !== backupResidencyTag;
+          });
+          if (offending.length) perRowCrossBorder.push({ table: prt.table, regions: offending });
+        }
+        if (perRowCrossBorder.length) {
+          audit().safeEmit({
+            action:   "backup.residency.per_row_cross_border",
+            outcome:  "success",
+            metadata: {
+              severity: "warning", scope: "per-row", posture: posture,
+              destination: backupResidencyTag, tables: perRowCrossBorder,
+              recommendation: "a per-row-residency table admits rows in regions other than the backup destination; confirm the cross-border transfer is permitted (allowCrossBorder + documented legalBasis) or restrict the destination region",
+            },
+          });
+        }
+      } catch (_e) { /* drop-silent — advisory only */ }
+    }
   }
 
   var dataDir = opts.dataDir;

package/lib/crypto-field.js

@@ -1823,6 +1823,39 @@ function getPerRowResidency(table) {
   return { residencyColumn: spec.residencyColumn, allowedTags: spec.allowedTags.slice() };
 }
 
+/**
+ * @primitive b.cryptoField.listPerRowResidency
+ * @signature b.cryptoField.listPerRowResidency()
+ * @since     0.15.4
+ * @related   b.cryptoField.getPerRowResidency, b.cryptoField.declarePerRowResidency
+ *
+ * Enumerate every table opted into per-row residency. Returns one entry per
+ * declared table — `{ table, residencyColumn, allowedTags }` — where
+ * `allowedTags` lists the regions that table's rows may be tagged to.
+ * Read-only. Consumers that must reason about residency across the whole
+ * deployment rather than one table use this: `b.backup.create` enumerates it
+ * to surface the per-row cross-border regions a deployment-level region
+ * compare is blind to.
+ *
+ * @example
+ *   b.cryptoField.declarePerRowResidency("residents", {
+ *     residencyColumn: "region",
+ *     allowedTags:     ["eu-west-1", "us-east-1"],
+ *   });
+ *   b.cryptoField.listPerRowResidency();
+ *   // → [ { table: "residents", residencyColumn: "region",
+ *   //       allowedTags: ["eu-west-1", "us-east-1"] } ]
+ */
+function listPerRowResidency() {
+  return Object.keys(perRowResidency).map(function (t) {
+    return {
+      table:           t,
+      residencyColumn: perRowResidency[t].residencyColumn,
+      allowedTags:     perRowResidency[t].allowedTags.slice(),
+    };
+  });
+}
+
 /**
  * @primitive b.cryptoField.declarePerRowKey
  * @signature b.cryptoField.declarePerRowKey(table, opts)
@@ -2099,6 +2132,7 @@ module.exports = {
   assertColumnResidency:  assertColumnResidency,
   declarePerRowResidency: declarePerRowResidency,
   getPerRowResidency:     getPerRowResidency,
+  listPerRowResidency:    listPerRowResidency,
   declarePerRowKey:       declarePerRowKey,
   hasPerRowKey:           hasPerRowKey,
   materializePerRowKey:   materializePerRowKey,

package/lib/db-query.js

@@ -1365,4 +1365,157 @@ function _validateField(field) {
   }
 }
 
-module.exports = { Query: Query };
+// ---- raw-write residency gate (execRaw / prepared-statement execution) ----
+// The structured builder runs every insert/update through _assertLocalResidency.
+// The raw paths (b.db.runSql / execRaw, b.db.prepare(sql).run(...)) bypass it, so
+// a cross-border row could land straight on disk under a regulated posture. These
+// helpers extract the residency-column value from a raw INSERT / UPDATE / REPLACE
+// and run it through the SAME gate; a write to a residency table the framework
+// cannot parse fails CLOSED (refused) - a raw write never skips the check.
+var _RAW_WRITE_KEYWORD_RE = /^\s*(?:INSERT|REPLACE|UPDATE)\b/i;
+var _RAW_INSERT_RE = /^\s*(?:INSERT|REPLACE)\s+(?:OR\s+[A-Za-z]+\s+)?INTO\s+(?:[\x22\x27\x60]?[A-Za-z_]\w*[\x22\x27\x60]?\s*\.\s*){0,3}[\x22\x27\x60]?([A-Za-z_]\w*)[\x22\x27\x60]?\s*\(([^)]+)\)\s*VALUES\s*\(([\s\S]+)\)\s*;?\s*$/i;
+var _RAW_UPDATE_RE = /^\s*UPDATE\s+(?:[\x22\x27\x60]?[A-Za-z_]\w*[\x22\x27\x60]?\s*\.\s*){0,3}[\x22\x27\x60]?([A-Za-z_]\w*)[\x22\x27\x60]?\s+SET\s+([\s\S]+?)\s*;?\s*$/i;
+var _RAW_TABLE_RE = /^\s*(?:INSERT|REPLACE)\s+(?:OR\s+[A-Za-z]+\s+)?INTO\s+(?:[\x22\x27\x60]?[A-Za-z_]\w*[\x22\x27\x60]?\s*\.\s*){0,3}[\x22\x27\x60]?([A-Za-z_]\w*)[\x22\x27\x60]?|^\s*UPDATE\s+(?:[\x22\x27\x60]?[A-Za-z_]\w*[\x22\x27\x60]?\s*\.\s*){0,3}[\x22\x27\x60]?([A-Za-z_]\w*)[\x22\x27\x60]?/i;
+
+function _unquoteIdent(s) {
+  s = String(s).trim();
+  if (s.length >= 2 &&
+      (s.charAt(0) === '"' || s.charAt(0) === "'" || s.charAt(0) === "`") &&
+      s.charAt(s.length - 1) === s.charAt(0)) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+function _rawWriteTable(sql) {
+  // Both regexes are ^-anchored (leading write keyword + table head): they scan
+  // only the statement head, so they are constant-time regardless of SQL length.
+  if (typeof sql !== "string" || !_RAW_WRITE_KEYWORD_RE.test(sql)) return null;  // allow:regex-no-length-cap
+  var m = _RAW_TABLE_RE.exec(sql);  // allow:regex-no-length-cap
+  return m ? _unquoteIdent(m[1] || m[2]) : null;
+}
+
+// Cheap prepare-time pre-check so only writes to a residency table get wrapped.
+function _isRawWriteToResidencyTable(sql) {
+  var table = _rawWriteTable(sql);
+  if (!table) return false;
+  return !!(cryptoField.getPerRowResidency(table) || cryptoField.getColumnResidency(table));
+}
+
+function _splitTopLevelCommas(s) {
+  var out = [], depth = 0, cur = "", q = null;
+  for (var i = 0; i < s.length; i++) {
+    var c = s.charAt(i);
+    if (q) {
+      cur += c;
+      if (c === q) { if (s.charAt(i + 1) === q) { cur += s.charAt(++i); } else { q = null; } }
+      continue;
+    }
+    if (c === "'" || c === '"' || c === "`") { q = c; cur += c; continue; }
+    if (c === "(") { depth += 1; cur += c; continue; }
+    if (c === ")") { depth -= 1; cur += c; continue; }
+    if (c === "," && depth === 0) { out.push(cur); cur = ""; continue; }
+    cur += c;
+  }
+  if (cur.trim() !== "") out.push(cur);
+  return out.map(function (x) { return x.trim(); });
+}
+
+// Quote/paren-aware: return the SET-clause text up to the first top-level
+// WHERE keyword that is NOT inside a string literal or parenthesised
+// subexpression. A WHERE embedded in a quoted value (SET note='x WHERE
+// y', ...) is skipped, so a residency-column assignment after it is still
+// parsed and gated. Linear scan; fixed 5-char keyword peek, no per-char slice.
+function _setClauseBeforeWhere(s) {
+  var depth = 0, q = null, n = s.length;
+  for (var i = 0; i < n; i++) {
+    var c = s.charAt(i);
+    if (q) {
+      if (c === q) { if (s.charAt(i + 1) === q) { i++; } else { q = null; } }
+      continue;
+    }
+    if (c === "'" || c === '"' || c === "\x60") { q = c; continue; }
+    if (c === "(") { depth += 1; continue; }
+    if (c === ")") { depth -= 1; continue; }
+    if (depth === 0 && (c === " " || c === "\t" || c === "\n" || c === "\r")) {
+      var j = i;
+      while (j < n && /\s/.test(s.charAt(j))) j += 1;
+      if (s.substr(j, 5).toLowerCase() === "where" && !/\w/.test(s.charAt(j + 5) || "")) {
+        return s.slice(0, i);
+      }
+    }
+  }
+  return s;
+}
+
+function _rawValue(tok, boundParams, pc) {
+  tok = tok.trim();
+  if (tok === "?") { return boundParams[pc.i++]; }
+  if (tok.length >= 2 && (tok.charAt(0) === "'" || tok.charAt(0) === '"')) {
+    var qc = tok.charAt(0);
+    return tok.slice(1, -1).split(qc + qc).join(qc);
+  }
+  if (/^null$/i.test(tok)) return null;
+  if (/^-?\d+(?:\.\d+)?$/.test(tok)) return Number(tok);
+  return tok;  // bare expression / named param: opaque -> fails the allowedTags check -> refused
+}
+
+function _flattenRunParams(argsLike) {
+  var a = Array.prototype.slice.call(argsLike || []);
+  if (a.length === 1 && Array.isArray(a[0])) return a[0];
+  return a;
+}
+
+function _assertRawWriteResidency(sql, boundParams) {
+  var table = _rawWriteTable(sql);
+  if (!table) return;
+  if (!cryptoField.getPerRowResidency(table) && !cryptoField.getColumnResidency(table)) return;
+  boundParams = _flattenRunParams(boundParams);
+
+  // The INSERT/UPDATE body regexes below scan with [\s\S]+; bound the input
+  // first and fail CLOSED on an over-long statement - a residency write the
+  // framework cannot safely parse must be refused, never let past the gate.
+  if (sql.length > 100000) {
+    throw new DbQueryError("db-query/row-residency-raw-unparseable",
+      "raw write to residency table '" + table + "' exceeds the parse limit (" +
+      sql.length + " chars) - use b.db.from(\"" + table + "\") so residency is validated", true);
+  }
+
+  var mi = _RAW_INSERT_RE.exec(sql);  // allow:regex-no-length-cap — input length-capped above
+  var mu = mi ? null : _RAW_UPDATE_RE.exec(sql);  // allow:regex-no-length-cap — input length-capped above
+  if (!mi && !mu) {
+    throw new DbQueryError("db-query/row-residency-raw-unparseable",
+      "raw write to residency table '" + table + "' cannot be parsed to validate its " +
+      "residency tag - use b.db.from(\"" + table + "\").insertOne / .updateOne so the tag is checked", true);
+  }
+
+  var plaintextRow = {};
+  var pc = { i: 0 };
+  if (mi) {
+    var cols = _splitTopLevelCommas(mi[2]).map(_unquoteIdent);
+    var vals = _splitTopLevelCommas(mi[3]);
+    if (cols.length !== vals.length) {
+      throw new DbQueryError("db-query/row-residency-raw-unparseable",
+        "raw insert to residency table '" + table + "' has an unmodelled VALUES shape " +
+        "(multi-row / expression) - use the structured builder so residency is validated", true);
+    }
+    for (var ci = 0; ci < cols.length; ci++) {
+      plaintextRow[cols[ci]] = _rawValue(vals[ci], boundParams, pc);
+    }
+    _assertLocalResidency(table, plaintextRow, "insert");
+  } else {
+    var assigns = _splitTopLevelCommas(_setClauseBeforeWhere(mu[2]));
+    for (var ai = 0; ai < assigns.length; ai++) {
+      var eq = assigns[ai].indexOf("=");
+      if (eq === -1) continue;
+      plaintextRow[_unquoteIdent(assigns[ai].slice(0, eq))] = _rawValue(assigns[ai].slice(eq + 1), boundParams, pc);
+    }
+    _assertLocalResidency(table, plaintextRow, "update");
+  }
+}
+
+module.exports = {
+  Query: Query,
+  _isRawWriteToResidencyTable: _isRawWriteToResidencyTable,
+  _assertRawWriteResidency:    _assertRawWriteResidency,
+};

package/lib/db-schema.js

@@ -261,14 +261,18 @@ function reconcileTable(database, table, opts) {
   // Every identifier here is validated (validateIdent) + quoted by
   // construction, so quote-by-construction safety is preserved.
   // allow:hand-rolled-sql — operator verbatim column DDL + composite FK clauses outside b.sql.createTable's structured API
-  runSql(database, "CREATE TABLE IF NOT EXISTS " + q(name) + " (" + colDefs.join(", ") + ")");
+  runSql(database, safeSql.assertSingleStatement(
+    "CREATE TABLE IF NOT EXISTS " + q(name) + " (" + colDefs.join(", ") + ")",
+    { label: "schema.reconcile" }));
 
   var existingCols = listColumns(database, name);
   for (var newCol in table.columns) {
     if (!existingCols.has(newCol)) {
       try {
         // allow:hand-rolled-sql — operator verbatim ADD COLUMN DDL (validated + quoted identifier); type string is operator-controlled
-        runSql(database, "ALTER TABLE " + q(name) + " ADD COLUMN " + q(newCol) + " " + table.columns[newCol]);
+        runSql(database, safeSql.assertSingleStatement(
+          "ALTER TABLE " + q(name) + " ADD COLUMN " + q(newCol) + " " + table.columns[newCol],
+          { label: "schema.reconcile" }));
       } catch (e) {
         throw new Error("failed to add column '" + newCol + "' to '" + name + "': " + e.message);
       }
@@ -479,8 +483,8 @@ function keyTextType(database) {
 // it throws "syntax error at PRAGMA" on the others). The table name binds
 // as a `?` parameter (never concatenated into the SQL text), so an operator
 // table name with metacharacters can't break the introspection query. On
-// Postgres the unqualified information_schema query matches the table in
-// any schema on the search_path; an operator running the same table name in
+// Postgres / MySQL the introspection is confined to current_schema() /
+// DATABASE() (where the bare-named CREATE TABLE lands); an operator running
 // multiple schemas qualifies via the `schema.table` handle convention
 // elsewhere — listColumns reconciles by bare name here, matching the
 // reconciler's CREATE TABLE (which is also bare-named).
@@ -498,9 +502,24 @@ function listColumns(database, tableName) {
   // information_schema.columns view (a schema-qualified system table b.sql's
   // verb builders don't model); the ONLY value (table name) binds as a `?`,
   // every column/table reference is a static literal — no injection surface.
+  // The schema predicate confines introspection to the schema/database the
+  // reconciler's bare-named CREATE TABLE actually writes into (Postgres
+  // current_schema() = the first writable schema on the search_path; MySQL
+  // DATABASE() = the connection's default database). Without it a same-named
+  // table in another schema/database pollutes the column set - silently skipping
+  // a needed ADD COLUMN or fabricating a drift "extra" that refuses a regulated-
+  // posture boot. Both are zero-arg SQL functions in predicate position, so the
+  // table name stays the single bound parameter (no new placeholder).
+  // Two fully-static introspection strings, one per dialect: DATABASE() /
+  // current_schema() are SQL functions baked into the literal (never a
+  // concatenated value), so the only bound value remains the table name `?`.
   // allow:hand-rolled-sql — static information_schema introspection, single bound param
-  var infoSql = "SELECT column_name FROM information_schema.columns " +
-                "WHERE table_name = ?";
+  var infoSql = dialect === "mysql"
+    ? "SELECT column_name FROM information_schema.columns " +
+      "WHERE table_schema = DATABASE() AND table_name = ?"
+    // allow:hand-rolled-sql — Postgres branch, same static-introspection shape
+    : "SELECT column_name FROM information_schema.columns " +
+      "WHERE table_schema = current_schema() AND table_name = ?";
   var stmt = database.prepare(infoSql);
   var irows = stmt.all.apply(stmt, [tableName]);
   for (var j = 0; j < irows.length; j++) {

package/lib/db.js

@@ -57,7 +57,7 @@ var { generateToken, generateBytes, encryptPacked, decryptPacked, sha3Hash } = r
 var cryptoField = require("./crypto-field");
 var dbDeclareRowPolicy = require("./db-declare-row-policy");
 var dbDeclareView = require("./db-declare-view");
-var { Query } = require("./db-query");
+var { Query, _isRawWriteToResidencyTable, _assertRawWriteResidency } = require("./db-query");
 var dbSchema = require("./db-schema");
 var { defineClass } = require("./framework-error");
 var frameworkFiles = require("./framework-files");
@@ -1682,6 +1682,27 @@ var _prepareCache = new Map();
  *   typeof row.total;
  *   // → "object"
  */
+// Wrap a prepared statement that writes to a per-row-residency table so its
+// execution (run / get / all / iterate) validates the residency tag of the
+// bound row through the same gate the structured builder uses. Only residency
+// writes are wrapped (cheap prepare-time pre-check) so the common path is
+// untouched.
+function _gatedResidencyStmt(stmt, sql) {
+  var EXEC = { run: true, get: true, all: true, iterate: true };
+  return new Proxy(stmt, {
+    get: function (target, prop) {
+      var v = target[prop];
+      if (typeof prop === "string" && EXEC[prop] && typeof v === "function") {
+        return function () {
+          _assertRawWriteResidency(sql, Array.prototype.slice.call(arguments));
+          return v.apply(target, arguments);
+        };
+      }
+      return typeof v === "function" ? v.bind(target) : v;
+    },
+  });
+}
+
 function prepare(sql) {
   _requireInit();
   if (_prepareCache.has(sql)) {
@@ -1692,6 +1713,7 @@ function prepare(sql) {
     return hit;
   }
   var stmt = database.prepare(sql);
+  if (_isRawWriteToResidencyTable(sql)) stmt = _gatedResidencyStmt(stmt, sql);
   _prepareCache.set(sql, stmt);
   if (_prepareCache.size > PREPARE_CACHE_MAX) {
     var oldestKey = _prepareCache.keys().next().value;
@@ -1854,6 +1876,9 @@ function _reportSlowSqlite(durationMs, statement) {
 
 function execRaw(sql) {
   _requireInit();
+  // Raw writes bypass the structured builder's residency gate; validate the
+  // residency tag of an INSERT / UPDATE to a per-row-residency table here too.
+  _assertRawWriteResidency(sql);
   var startedAt = Date.now();
   var auditMod = (function () { try { return require("./audit"); } catch (_e) { return null; } })(); // allow:inline-require — circular-load defense (audit imports db)
   // DDL_RE only matches the leading keyword — bounded by `/\s*(KEYWORD)\b/`

package/lib/dsr.js

@@ -1065,7 +1065,9 @@ function dbTicketStore(opts) {
     var createCols = Object.keys(SCHEMA_COLUMNS).map(function (c) {
       return c + " " + SCHEMA_COLUMNS[c];
     }).join(", ");
-    db.runSql("CREATE TABLE IF NOT EXISTS " + qTable + " (" + createCols + ")");
+    db.runSql(safeSql.assertSingleStatement(
+      "CREATE TABLE IF NOT EXISTS " + qTable + " (" + createCols + ")",
+      { label: "dsr.schema" }));
     // Reconcile an existing (older-shape) table — add any column the
     // current schema declares that the live table lacks. PRAGMA table_info
     // returns one row per existing column.
@@ -1086,12 +1088,14 @@ function dbTicketStore(opts) {
       var addType = /NOT NULL/.test(SCHEMA_COLUMNS[col])
         ? SCHEMA_COLUMNS[col].replace(/PRIMARY KEY/g, "") + " DEFAULT ''"
         : SCHEMA_COLUMNS[col];
-      db.runSql("ALTER TABLE " + qTable + " ADD COLUMN " + col + " " + addType.trim());
+      db.runSql(safeSql.assertSingleStatement(
+        "ALTER TABLE " + qTable + " ADD COLUMN " + col + " " + addType.trim(),
+        { label: "dsr.schema" }));
     }
-    db.runSql("CREATE INDEX IF NOT EXISTS " + qEmailIdx + " ON " +
-              qTable + " (subject_email_hash)");
-    db.runSql("CREATE INDEX IF NOT EXISTS " + qStatusIdx + " ON " +
-              qTable + " (status)");
+    db.runSql(safeSql.assertSingleStatement("CREATE INDEX IF NOT EXISTS " + qEmailIdx + " ON " +
+              qTable + " (subject_email_hash)", { label: "dsr.schema" }));
+    db.runSql(safeSql.assertSingleStatement("CREATE INDEX IF NOT EXISTS " + qStatusIdx + " ON " +
+              qTable + " (status)", { label: "dsr.schema" }));
     // Backfill legacy / vault-less rows. A row written before the sealed-store
     // upgrade (or while no vault was configured) holds its subject identifiers
     // in plaintext with NULL derived-hash columns. Once a vault is present,

package/lib/external-db.js

@@ -1811,8 +1811,25 @@ async function _readQuery(sql, params, opts) {
   // region (opts.rowResidencyTag) under a regulated posture, a read
   // routed to an incompatible replica is refused unless the replica
   // was explicitly configured allowCrossBorder (which is audited).
-  if (opts.rowResidencyTag && typeof opts.rowResidencyTag === "string") {
-    var _readPosture = _activePosture();
+  var _readPosture = _activePosture();
+  var _tagPresent = opts.rowResidencyTag && typeof opts.rowResidencyTag === "string";
+  // Fail CLOSED when the row's region is not identified: a regulated read to a
+  // residency-tagged replica without opts.rowResidencyTag would otherwise route
+  // residency-restricted rows to an arbitrary-region replica with no check at
+  // all (symmetric with the write gate's RESIDENCY_GATE_REQUIRED).
+  if (!_tagPresent && _crossBorderRegulated(_readPosture) &&
+      replica.residencyTag && !replica.allowCrossBorder) {
+    _emit("db.residency.replica.tag_required", "denied", {
+      backend: b.name, replicaIdx: replica.index,
+      replicaTag: replica.residencyTag, posture: _readPosture,
+    });
+    throw _err("REPLICA_RESIDENCY_TAG_REQUIRED",
+      "read routed to residency-tagged replica " + replica.index + " of backend '" +
+      b.name + "' (residencyTag='" + replica.residencyTag + "') under '" + _readPosture +
+      "' posture without opts.rowResidencyTag - identify the row's region or set " +
+      "allowCrossBorder on the replica (audited)", true);
+  }
+  if (_tagPresent) {
     if (_crossBorderRegulated(_readPosture) &&
         opts.rowResidencyTag !== "global" && opts.rowResidencyTag !== "unrestricted" &&
         !_residencyCompatible(opts.rowResidencyTag, replica.residencyTag)) {

package/lib/middleware/dpop.js

@@ -239,6 +239,15 @@ function create(opts) {
   var auditOn = opts.audit !== false;
   var algorithms = opts.algorithms;
   var iatWindowSec = opts.iatWindowSec;
+  // replayStore is the jti-replay defense (RFC 9449 §11.1) — REQUIRED. Reading
+  // it optionally and gating the check behind `if (replayStore)` would silently
+  // mount a proof-of-possession gate that performs no replay check, letting a
+  // captured proof replay indefinitely. Fail closed at config time: a missing
+  // store and a store lacking checkAndInsert both throw here, not at the first
+  // request. (The low-level b.auth.dpop.verify primitive keeps replayStore
+  // optional for advanced callers that track jti themselves.)
+  validateOpts.requireMethods(opts.replayStore, ["checkAndInsert"],
+    "middleware.dpop: opts.replayStore", AuthError, "auth-dpop/replay-store-required");
   var replayStore = opts.replayStore;
   var requireNonce = opts.requireNonce === true;
 
@@ -328,7 +337,7 @@ function create(opts) {
     if (iatWindowSec !== undefined) verifyOpts.iatWindowSec = iatWindowSec;
     if (accessToken) verifyOpts.accessToken = accessToken;
     if (nonce) verifyOpts.nonce = nonce;
-    if (replayStore) verifyOpts.replayStore = replayStore;
+    verifyOpts.replayStore = replayStore;   // required at create() — always present
 
     var result;
     try { result = await dpop().verify(proofHeader, verifyOpts); }

package/lib/network-proxy.js

@@ -20,6 +20,11 @@ var DEFAULT_HTTPS_PORT   = 443;                 // RFC 9110 §4.2.2
 var DEFAULT_HTTP_PORT    = C.BYTES.bytes(80);   // RFC 9110 §4.2.1
 
 var observability = lazyRequire(function () { return require("./observability"); });
+// Lazy so pqc-agent's TLS/audit graph isn't pulled into every process that
+// imports network-proxy but never proxies an https upstream. Used only to audit
+// a classical-group fallback on a proxy-tunneled TLS handshake (the direct path
+// audits in pqc-agent.create()).
+var pqcAgent = lazyRequire(function () { return require("./pqc-agent"); });
 
 var STATE = {
   http:    null,
@@ -167,6 +172,13 @@ function _connectThroughTunnel(proxyUrl, targetHost, targetPort, callback) {
   function done(err, sock) { if (settled) return; settled = true; callback(err, sock); }
   proxySocket.on("error", function (e) { done(e); });
   proxySocket.on(proxyUrl.protocol === "https:" ? "secureConnect" : "connect", function () {
+    if (proxyUrl.protocol === "https:") {
+      // The CONNECT-tunnel leg to an https proxy is itself a TLS handshake;
+      // audit a classical fallback to the proxy too, not only to the upstream.
+      pqcAgent()._auditClassicalDowngrade(proxySocket, {
+        host: proxyUrl.hostname, port: proxyPort,
+      });
+    }
     var lines = [
       "CONNECT " + targetHost + ":" + targetPort + " HTTP/1.1",
       "Host: " + targetHost + ":" + targetPort,
@@ -218,7 +230,18 @@ function agentFor(targetUrl) {
           minVersion: "TLSv1.3",
           ecdhCurve:  C.TLS_GROUP_CURVE_STR,
           ALPNProtocols: options.ALPNProtocols,
-        }, function () { cb(null, secure); });
+        }, function () {
+          // Audit a classical-group fallback on the upstream (target) handshake
+          // reached through the proxy tunnel, so the "every outbound TLS path
+          // emits tls.classical_downgrade" guarantee holds for proxied requests
+          // too (the direct path audits in pqc-agent.create). Drop-silent; the
+          // handshake itself is unchanged (still hybrid-preferred TLSv1.3).
+          pqcAgent()._auditClassicalDowngrade(secure, {
+            host: options.servername || options.host,
+            port: options.port,
+          });
+          cb(null, secure);
+        });
         secure.on("error", function (e) { cb(e); });
       });
     };

package/lib/observability-otlp-exporter.js

@@ -98,6 +98,11 @@ var KIND_TO_OTLP = Object.freeze({
 function _attrToOtlp(attrs) {
   // OTLP attribute shape: [{ key, value: { stringValue | intValue |
   // doubleValue | boolValue | arrayValue: { values: [...] } } }, ...]
+  // Telemetry is a first-class EGRESS sink — scrub every value through the
+  // active redactor BEFORE serialization so a secret/PII attribute never
+  // reaches the collector (CWE-532). Redaction is baked into the encoder, not
+  // the call site, so no span/event/resource path can forget it.
+  attrs = observability().redactAttrs(attrs);
   var out = [];
   if (!attrs || typeof attrs !== "object") return out;
   var keys = Object.keys(attrs);
@@ -316,7 +321,10 @@ function _keyValueToProto(kvObj) {
 function _attrsToProto(attrs) {
   // attrs is the raw `{ key: value }` operator attribute object; OTLP
   // KeyValue gets emitted per entry with field 9 (attributes) on Span,
-  // field 1 (attributes) on Resource, etc.
+  // field 1 (attributes) on Resource, etc. Scrub every value through the
+  // active redactor BEFORE building the wire intermediate — the protobuf path
+  // is the same EGRESS sink as the JSON path and must not leak (CWE-532).
+  attrs = observability().redactAttrs(attrs);
   if (!attrs || typeof attrs !== "object") return [];
   var keys = Object.keys(attrs);
   var out = new Array(keys.length);

package/lib/observability.js

@@ -191,6 +191,42 @@ function getRedactor() {
   return _telemetryRedactor;
 }
 
+/**
+ * @primitive b.observability.redactAttrs
+ * @signature b.observability.redactAttrs(attrs)
+ * @since     0.15.4
+ * @related   b.observability.getRedactor, b.observability.setRedactor
+ *
+ * Run every value of a telemetry attribute map through the active redactor and
+ * return a NEW `{ key: redactedValue }` object. The OTLP exporters call this on
+ * span, span-event, metric, and resource attributes before serialization so no
+ * attribute value crosses the egress boundary unscrubbed (CWE-532: insertion of
+ * sensitive information into an externally-shipped sink). A key whose redactor
+ * throws is DROPPED — failing toward dropping, never exporting the raw value;
+ * `null` / `undefined` values pass through for the type-encoder to handle.
+ *
+ * @example
+ *   b.observability.redactAttrs({ "http.method": "GET", authorization: "Bearer x" });
+ *   // → { "http.method": "GET", authorization: "[REDACTED]" }
+ */
+function redactAttrs(attrs) {
+  var out = {};
+  if (!attrs || typeof attrs !== "object") return out;
+  var redactor = getRedactor();
+  var keys = Object.keys(attrs);
+  for (var i = 0; i < keys.length; i++) {
+    var k = keys[i];
+    try {
+      out[k] = redactor(attrs[k], k);
+    } catch (_e) {
+      // redactor threw on the export hot path — drop the attribute rather than
+      // fall through to the raw value. A throwing redactor must never widen the
+      // egress surface, and must never crash the request that produced the span.
+    }
+  }
+  return out;
+}
+
 /**
  * @primitive b.observability.tap
  * @signature b.observability.tap(name, attrs, fn)
@@ -837,6 +873,7 @@ module.exports = {
   setTap:        setTap,
   setRedactor:   setRedactor,
   getRedactor:   getRedactor,
+  redactAttrs:   redactAttrs,
   SEMCONV:       SEMCONV,
   traceContext:  traceContext,
   baggage:       baggage,

package/lib/otel-export.js

@@ -65,38 +65,23 @@ var MAX_RESPONSE_BYTES = C.BYTES.mib(1);
 // receiving backend handles the running sum.
 var TEMPORALITY_DELTA = 1;
 
-// Run a single attribute value through the active telemetry redactor.
-// Telemetry is a first-class EGRESS sink — an attribute value holding a
-// user email, bearer token, or vault-sealed ciphertext would otherwise
-// be serialized verbatim onto the OTLP wire (CWE-532: insertion of
-// sensitive information into an externally-shipped sink). The redactor is
-// resolved per-call from b.observability so an operator-installed
-// override (setRedactor) takes effect without re-creating the exporter.
-//
-// Drop-silent by design: this runs on the export hot path, where a throw
-// from the redactor must never crash the request that produced the span.
-// On a throw we DROP the attribute (signalled by the `_DROP` sentinel)
-// rather than fall through to the raw value — failing toward dropping,
-// not leaking.
-var _DROP = {};
-function _redactAttrValue(key, value) {
-  try {
-    return observability.getRedactor()(value, key);
-  } catch (_e) {
-    return _DROP;   // redactor threw — drop the attribute, never export raw
-  }
-}
-
 // ---- attribute encoding ----
 // OTLP attributes are KeyValue with typed `value` fields:
 //   { key, value: { stringValue | intValue | doubleValue | boolValue } }
+// Telemetry is a first-class EGRESS sink — an attribute value holding a user
+// email, bearer token, or vault-sealed ciphertext would otherwise be serialized
+// verbatim onto the OTLP wire (CWE-532). observability.redactAttrs scrubs every
+// value through the active redactor (operator overrides via setRedactor take
+// effect without re-creating the exporter) and drops any key whose redactor
+// throws — failing toward dropping, never leaking, on the export hot path.
 function _attrsToOtlp(attrs) {
-  if (!attrs || typeof attrs !== "object") return [];
+  attrs = observability.redactAttrs(attrs);
   var out = [];
-  for (var k in attrs) {
-    if (!Object.prototype.hasOwnProperty.call(attrs, k)) continue;
-    var v = _redactAttrValue(k, attrs[k]);
-    if (v === _DROP) continue;                // redactor threw — drop, don't leak
+  if (!attrs || typeof attrs !== "object") return out;
+  var keys = Object.keys(attrs);
+  for (var i = 0; i < keys.length; i++) {
+    var k = keys[i];
+    var v = attrs[k];
     var kv;
     if (typeof v === "string")  kv = { stringValue: v };
     else if (typeof v === "number") {

package/lib/safe-sql.js

@@ -470,8 +470,96 @@ function countPlaceholders(sql) {
  *   // → 63
  */
 
+/**
+ * @primitive b.safeSql.assertSingleStatement
+ * @signature b.safeSql.assertSingleStatement(sql, opts?)
+ * @since     0.15.4
+ * @status    stable
+ * @related   b.safeSql.quoteIdentifier, b.safeSql.countPlaceholders, b.sql
+ *
+ * The one quote/comment-aware single-statement gate for any FINISHED SQL
+ * string that reaches a driver. Refuses a NUL, a lone surrogate, a
+ * top-level ';' (stacked statement), an unterminated quote, and unbalanced
+ * parentheses - while CORRECTLY allowing those characters inside a balanced
+ * quoted label (e.g. a MySQL ENUM('a;b')). Hand-rolled DDL (schema
+ * reconcile, the DSR store, migrations) and the b.sql builder's own output
+ * gates route through this single scan so the injection backstop cannot
+ * drift between the structured builder and the raw-DDL paths. Returns the
+ * input string so a caller can wrap inline:
+ *   runSql(db, safeSql.assertSingleStatement(ddl, { label: "schema" }));
+ *
+ * @opts
+ *   label:     string,    // message prefix (default: "sql")
+ *   makeError: function,  // (message, codeSuffix) => Error  (default: SafeSqlError "sql/<suffix>")
+ *
+ * @example
+ *   var ddl = b.safeSql.assertSingleStatement("CREATE TABLE t (id INTEGER)", { label: "schema" });
+ *   // returns the input string; throws sql/stacked-statement on a stacked DDL
+ */
+function assertSingleStatement(sql, opts) {
+  opts = opts || {};
+  var label = typeof opts.label === "string" ? opts.label : "sql";
+  var mkErr = typeof opts.makeError === "function"
+    ? opts.makeError
+    : function (msg, suffix) { return new SafeSqlError(msg, "sql/" + suffix); };
+  // Backtick written via its code point so no NUL byte can reach this source.
+  var BACKTICK = String.fromCharCode(96);
+  if (typeof sql !== "string" || sql.length === 0) {
+    throw mkErr(label + ": SQL must be a non-empty string", "empty-sql");
+  }
+  if (sql.indexOf(String.fromCharCode(0)) !== -1) {
+    throw mkErr(label + ": SQL contains a NUL byte - rejected", "null-byte-sql");
+  }
+  if (typeof sql.isWellFormed === "function" && !sql.isWellFormed()) {
+    throw mkErr(label + ": SQL contains invalid Unicode (lone surrogates) - rejected",
+      "invalid-encoding-sql");
+  }
+  var i = 0;
+  var len = sql.length;
+  var depth = 0;
+  while (i < len) {
+    var ch = sql.charAt(i);
+    var next = i + 1 < len ? sql.charAt(i + 1) : "";
+    if (ch === "'" || ch === '"' || ch === BACKTICK) {
+      var qch = ch;
+      var closed = false;
+      i += 1;
+      while (i < len) {
+        if (sql.charAt(i) === qch) {
+          if (sql.charAt(i + 1) === qch) { i += 2; continue; }  // doubled quote = escaped literal
+          i += 1; closed = true; break;
+        }
+        i += 1;
+      }
+      if (!closed) {
+        throw mkErr(label + ": unterminated quote in SQL (quote-jump / breakout risk)",
+          "unterminated-quote");
+      }
+      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 === "(") { depth += 1; }
+    else if (ch === ")") { depth -= 1; }
+    else if (ch === ";") {
+      throw mkErr(label + ": emitted a top-level ';' - exactly one statement", "stacked-statement");
+    }
+    i += 1;
+  }
+  if (depth !== 0) {
+    throw mkErr(label + ": unbalanced parentheses in SQL", "unbalanced");
+  }
+  return sql;
+}
+
 module.exports = {
   validateIdentifier:  validateIdentifier,
+  assertSingleStatement: assertSingleStatement,
   quoteIdentifier:     quoteIdentifier,
   quoteQualified:      quoteQualified,
   quoteList:           quoteList,

package/lib/session.js

@@ -846,11 +846,20 @@ async function touch(token, opts) {
  * the new token verifies. Audit event `auth.session.rotate` fires
  * best-effort with `metadata.reason`.
  *
+ * Device binding: when the session was created with `{ req, fingerprintFields }`
+ * the bound fingerprint is keyed to the sid, so rotation re-keys it to the new
+ * sid from the live request. Pass the same `{ req, fingerprintFields }` to
+ * `rotate` — a fingerprint-bound session rotated without `req` throws, because
+ * the binding cannot follow the sid otherwise (it would silently break or make
+ * the next `verify` falsely report drift).
+ *
  * @opts
  *   {
- *     data?:   object,     // replacement session data (re-sealed)
- *     ttlMs?:  number,     // new TTL; if absent, existing expiresAt preserved
- *     reason?: string,     // audit metadata ("login", "mfa", "role-change")
+ *     data?:              object,     // replacement session data (re-sealed)
+ *     ttlMs?:             number,     // new TTL; if absent, existing expiresAt preserved
+ *     reason?:            string,     // audit metadata ("login", "mfa", "role-change")
+ *     req?:               IncomingMessage, // re-key the device fingerprint to the new sid
+ *     fingerprintFields?: Array<string|fn>, // default ["clientIp","userAgent","acceptLanguage"]
  *   }
  *
  * @example
@@ -882,8 +891,53 @@ async function rotate(oldToken, opts) {
 
   var setCols = { sidHash: newSidHash, lastActivity: nowMs };
 
-  if (opts.data !== undefined) {
-    var dataJson = opts.data ? JSON.stringify(opts.data) : null;
+  // Re-key the device binding to the NEW sid. __bj_fingerprint is sid-keyed
+  // (_hashFingerprint(sid, inputs), so a stolen DB can't replay it); a rotated
+  // session that kept the old-sid hash would make verify(newToken, sameReq)
+  // recompute against the new sid and mismatch — a false fingerprintDrift
+  // (strict operators destroy the session on every rotation) or a silently
+  // broken binding. Read the live row to learn whether the session was bound
+  // and to carry its payload forward when opts.data is not supplied.
+  var fpFields = Array.isArray(opts.fingerprintFields) && opts.fingerprintFields.length > 0
+    ? opts.fingerprintFields : DEFAULT_FINGERPRINT_FIELDS;
+  var existingData = null;
+  var rotSelBuilt = sql.select(_sessionSqlTable(), _sessionSqlOpts())
+    .columns(["data"])
+    .where("sidHash", oldSidHash)
+    .where("expiresAt", ">=", nowMs)
+    .toSql();
+  var existingRow = await _currentStore().executeOne(rotSelBuilt.sql, rotSelBuilt.params);
+  if (!existingRow) return null;   // unknown / expired old session
+  try {
+    var unsealedExisting = cryptoField.unsealRow(SESSION_TABLE, existingRow);
+    if (unsealedExisting.data) existingData = safeJson.parse(unsealedExisting.data);
+  } catch (_e) { existingData = null; }
+  var wasBound = existingData && typeof existingData === "object" &&
+                 typeof existingData.__bj_fingerprint === "string";
+
+  if (opts.data !== undefined || wasBound) {
+    // opts.data REPLACES the payload (documented rotate semantics); otherwise
+    // carry the existing payload forward. The reserved __bj_fingerprint is
+    // never copied verbatim (it is old-sid-keyed) — it is recomputed below.
+    var newDataObj;
+    if (opts.data !== undefined) {
+      newDataObj = (opts.data && typeof opts.data === "object") ? Object.assign({}, opts.data) : null;
+    } else {
+      newDataObj = (existingData && typeof existingData === "object") ? Object.assign({}, existingData) : null;
+    }
+    if (newDataObj) delete newDataObj.__bj_fingerprint;
+
+    if (wasBound) {
+      if (!opts.req) {
+        throw _err("ROTATE_FINGERPRINT_REQ_REQUIRED",
+          "session.rotate: this session is fingerprint-bound; pass { req, fingerprintFields } " +
+          "so the device binding can be re-keyed to the new session id", true);
+      }
+      if (!newDataObj) newDataObj = {};
+      newDataObj.__bj_fingerprint = _hashFingerprint(newSid, _buildFingerprintInputs(opts.req, fpFields));
+    }
+
+    var dataJson = newDataObj ? JSON.stringify(newDataObj) : null;
     var sealedRow = cryptoField.sealRow(SESSION_TABLE, { data: dataJson });
     setCols.data = sealedRow.data;
   }

package/lib/sql.js

@@ -229,9 +229,17 @@ function _ddlType(logical, dialect) {
   if (key === "JSON") {
     return dialect === "postgres" ? "JSONB" : (dialect === "mysql" ? "JSON" : "TEXT");
   }
-  // Unrecognised: a verbatim dialect-specific type. Emitted as the
-  // operator wrote it (it follows a quoted identifier, so it is in type
-  // position, never identifier position).
+  // Unrecognised: a verbatim dialect-specific type (VARCHAR(255), GEOGRAPHY,
+  // NUMERIC(10,2), DOUBLE PRECISION, TIMESTAMP WITH TIME ZONE, MySQL
+  // ENUM('a','b') / SET(...), ...). It follows a quoted identifier so it is in
+  // type position, never identifier position. Injection safety for the type
+  // token is enforced at the statement level: createTable / alterTable route
+  // the finished DDL through _assertCatalogEmittable, whose quote-aware
+  // single-statement scan refuses a top-level ';', a comment marker, an
+  // unbalanced quote, an unbalanced paren, and a NUL - while CORRECTLY allowing
+  // those same characters when they sit inside a balanced quoted label (e.g.
+  // ENUM('needs;review')). A non-quote-aware pre-scan here would over-reject
+  // such valid labels, so the one quote-aware gate is the right place to check.
   return logical;
 }
 
@@ -1377,57 +1385,10 @@ function _assertEmittable(sql, params) {
       " '?' placeholder(s) but " + n + " param(s); emitting this would " +
       "misalign bound values across columns", "sql-builder/param-mismatch");
   }
-  var i = 0;
-  var len = sql.length;
-  var depth = 0;
-  while (i < len) {
-    var ch = sql.charAt(i);
-    var next = i + 1 < len ? sql.charAt(i + 1) : "";
-    if (ch === "'" || ch === '"' || ch === "`") {
-      // Quote context. A string literal / quoted identifier escapes its own
-      // quote char by DOUBLING it; an UNTERMINATED quote is the signature of
-      // a quote-jump breakout - a value or identifier whose embedded quote
-      // escaped its context and ran to the end of the statement. (Backtick
-      // covers MySQL identifier quoting; ' and " cover string literals and
-      // ANSI / Postgres / SQLite identifiers.)
-      var q = ch;
-      var closed = false;
-      i += 1;
-      while (i < len) {
-        if (sql.charAt(i) === q) {
-          if (sql.charAt(i + 1) === q) { i += 2; continue; }
-          i += 1; closed = true; break;
-        }
-        i += 1;
-      }
-      if (!closed) {
-        throw _err("toSql: unterminated " +
-          (q === "'" ? "string literal" : "quoted identifier") +
-          " in emitted SQL - a quote escaped its context " +
-          "(quote-jump / breakout risk)", "sql-builder/unterminated-quote");
-      }
-      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 === "(") { depth += 1; }
-    else if (ch === ")") { depth -= 1; }
-    else if (ch === ";") {
-      throw _err("toSql: builder emitted a top-level ';' - exactly one " +
-        "statement per build; a stacked statement is never valid output",
-        "sql-builder/stacked-statement");
-    }
-    i += 1;
-  }
-  if (depth !== 0) {
-    throw _err("toSql: unbalanced parentheses in emitted SQL (builder bug)",
-      "sql-builder/unbalanced");
-  }
+  safeSql.assertSingleStatement(sql, {
+    label: "toSql",
+    makeError: function (m, suffix) { return _err(m, "sql-builder/" + suffix); },
+  });
 }
 
 // Terminal wrapper: validate then return the { sql, params } shape every
@@ -2486,8 +2447,25 @@ class UpsertBuilder extends Builder {
         throw _err("upsert readback: conflict key '" + keys[i] + "' is not in the value set",
           "sql-builder/bad-conflict");
       }
-      conds.push(_quoteId(keys[i], dialect) + " = ?");
-      params.push(this._values[idx]);
+      var keyVal = this._values[idx];
+      if (keyVal instanceof SqlFunction) {
+        // A server-evaluated function (NOW() / CURRENT_TIMESTAMP / ...) as a
+        // conflict key has no stable readback identity: the row holds the value
+        // the server computed at INSERT time, which a fresh evaluation in this
+        // WHERE would never equal, so the readback would silently match zero
+        // rows. Refuse rather than return a wrong (empty) result.
+        throw _err("upsert readback: conflict key '" + keys[i] + "' is a " +
+          "server-evaluated function (b.sql.fn) with no stable readback identity " +
+          "- use a literal/cast conflict key or read the row back explicitly",
+          "sql-builder/bad-conflict");
+      }
+      // Resolve the key value through the same cell renderer the VALUES tuple
+      // uses, so a b.sql.cast(...) conflict key emits `col = CAST(? AS type)`
+      // (Postgres `col = ?::type`) binding the inner value, and a plain scalar
+      // still emits `col = ?` binding the value unchanged.
+      var cell = _renderValueCell(keyVal, dialect);
+      conds.push(_quoteId(keys[i], dialect) + " = " + cell.sql);
+      for (var cp = 0; cp < cell.params.length; cp++) params.push(cell.params[cp]);
     }
     sql += " WHERE " + conds.join(" AND ");
     return { sql: sql, params: params };
@@ -2614,6 +2592,20 @@ function createTable(name, columns, opts) {
     return def;
   });
   if (Array.isArray(opts.primaryKey) && opts.primaryKey.length > 0) {
+    // A column-level primary key (primaryKey / autoIncrement / serial) and a
+    // composite opts.primaryKey are mutually exclusive: emitting both produces
+    // two PRIMARY KEY clauses, which sqlite / Postgres / MySQL all reject at the
+    // driver. Catch the contradiction at build time with a clear error rather
+    // than a cryptic "multiple primary keys" failure mid-migration. Lives in the
+    // shared composer so defineTable is covered too.
+    var colHasPk = columns.some(function (c) {
+      return c && (c.primaryKey || c.autoIncrement || c.serial);
+    });
+    if (colHasPk) {
+      throw _err("createTable: a column-level primary key (primaryKey / " +
+        "autoIncrement / serial) and a composite opts.primaryKey are mutually " +
+        "exclusive", "sql-builder/bad-column");
+    }
     opts.primaryKey.forEach(_validateColumn);
     pieces.push("PRIMARY KEY (" + opts.primaryKey.map(function (k) {
       return _quoteId(k, dialect);
@@ -2621,7 +2613,11 @@ function createTable(name, columns, opts) {
   }
   var ifNot = opts.ifNotExists === false ? "" : "IF NOT EXISTS ";
   var sql = "CREATE TABLE " + ifNot + ref.ref(dialect) + " (" + pieces.join(", ") + ")";
-  return { sql: sql, params: [] };
+  // Route the finished DDL through the same emittable gate every SELECT /
+  // INSERT / UPDATE / DELETE verb uses: it refuses a stacked top-level ';', a
+  // NUL, an unterminated quote, and unbalanced parens - a defence-in-depth
+  // backstop behind the per-column type / constraint guards.
+  return _assertCatalogEmittable(sql, []);
 }
 
 // DDL DEFAULT renderer - numeric / boolean / null inline; a string
@@ -2767,11 +2763,11 @@ function alterTable(name, change, opts) {
     if (col.notNull) def += " NOT NULL";
     if (col.unique) def += " UNIQUE";
     if (col.default !== undefined) def += " DEFAULT " + _ddlDefault(col.default);
-    return { sql: head + "ADD COLUMN " + def, params: [] };
+    return _assertCatalogEmittable(head + "ADD COLUMN " + def, []);
   }
   if (change.dropColumn) {
     _validateColumn(change.dropColumn);
-    return { sql: head + "DROP COLUMN " + _quoteId(change.dropColumn, dialect), params: [] };
+    return _assertCatalogEmittable(head + "DROP COLUMN " + _quoteId(change.dropColumn, dialect), []);
   }
   if (change.renameColumn) {
     var rc = change.renameColumn;
@@ -2780,10 +2776,8 @@ function alterTable(name, change, opts) {
     }
     _validateColumn(rc.from);
     _validateColumn(rc.to);
-    return {
-      sql: head + "RENAME COLUMN " + _quoteId(rc.from, dialect) + " TO " + _quoteId(rc.to, dialect),
-      params: [],
-    };
+    return _assertCatalogEmittable(
+      head + "RENAME COLUMN " + _quoteId(rc.from, dialect) + " TO " + _quoteId(rc.to, dialect), []);
   }
   throw _err("alterTable change must be addColumn / dropColumn / renameColumn",
     "sql-builder/bad-alter");
@@ -3255,47 +3249,10 @@ function _assertCatalogEmittable(sql, params) {
   // Quote/comment-aware single-statement + balanced-paren scan, identical
   // to _assertEmittable's tail. A stacked top-level ';' / unterminated
   // quote is refused here too.
-  var i = 0;
-  var len = sql.length;
-  var depth = 0;
-  while (i < len) {
-    var ch = sql.charAt(i);
-    var next = i + 1 < len ? sql.charAt(i + 1) : "";
-    if (ch === "'" || ch === '"' || ch === "`") {
-      var q = ch;
-      var closed = false;
-      i += 1;
-      while (i < len) {
-        if (sql.charAt(i) === q) {
-          if (sql.charAt(i + 1) === q) { i += 2; continue; }
-          i += 1; closed = true; break;
-        }
-        i += 1;
-      }
-      if (!closed) {
-        throw _err("catalog: unterminated quote in emitted SQL (quote-jump / breakout risk)",
-          "sql-builder/unterminated-quote");
-      }
-      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 === "(") { depth += 1; }
-    else if (ch === ")") { depth -= 1; }
-    else if (ch === ";") {
-      throw _err("catalog: emitted a top-level ';' - exactly one statement",
-        "sql-builder/stacked-statement");
-    }
-    i += 1;
-  }
-  if (depth !== 0) {
-    throw _err("catalog: unbalanced parentheses in emitted SQL (builder bug)", "sql-builder/unbalanced");
-  }
+  safeSql.assertSingleStatement(sql, {
+    label: "catalog",
+    makeError: function (m, suffix) { return _err(m, "sql-builder/" + suffix); },
+  });
   return { sql: sql, params: params };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.15.2",
+  "version": "0.15.4",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",
@@ -75,7 +75,7 @@
     "check:vendor-currency": "node scripts/check-vendor-currency.js"
   },
   "devDependencies": {
-    "esbuild": "0.28.0",
+    "esbuild": "0.28.1",
     "postject": "1.0.0-alpha.6"
   }
 }

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:ff927df0-9d1a-45d2-9e38-dfeac8f50738",
+  "serialNumber": "urn:uuid:58fea242-8071-4e16-965b-d1ea85e285ba",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-12T02:42:36.413Z",
+    "timestamp": "2026-06-13T02:42:24.654Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.15.2",
+      "bom-ref": "@blamejs/core@0.15.4",
       "type": "application",
       "name": "blamejs",
-      "version": "0.15.2",
+      "version": "0.15.4",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.15.2",
+      "purl": "pkg:npm/%40blamejs/core@0.15.4",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.15.2",
+      "ref": "@blamejs/core@0.15.4",
       "dependsOn": []
     }
   ]