@blamejs/core 0.8.43 → 0.8.49

package/lib/external-db.js

@@ -1,54 +1,39 @@
 "use strict";
 /**
- * External database service — pluggable wrapper for app-data DB connections.
+ * @module b.externalDb
+ * @nav    Data
+ * @title  External Database
  *
- * Framework state (audit_log, consent_log, _blamejs_*) stays in the local
- * SQLite via b.db. This module is for APP DATA — when an operator wants to
- * keep their app's domain tables in Postgres / MySQL / MongoDB / libsql /
- * etc., they configure a backend here and use b.externalDb.query() instead
- * of b.db.from() for those tables.
+ * @intro
+ *   External-database integration for app data — Postgres / MySQL /
+ *   SQLite / MongoDB connection pooling, retry, circuit breaker,
+ *   classification routing, residency enforcement, and audit hooks.
  *
- * Bring-your-own-client design (per "zero npm runtime deps" rule):
- *   The operator supplies the actual DB driver via the backend's connect/
- *   query/close functions. The framework adds:
- *     - Connection pooling (lazy-create, reuse across queries)
- *     - Retry on transient errors (5xx-equivalent + network)
- *     - Circuit breaker per-backend
- *     - Classification routing (which backend serves which data class)
- *     - Residency enforcement (boot-time validation against
- *       db.getDataResidency().region)
- *     - Audit hooks (system.externaldb.{query,transaction,connect.failure})
+ *   Framework state (audit_log, consent_log, _blamejs_*) stays in the
+ *   local SQLite via `b.db`. This module is for APP DATA — when an
+ *   operator keeps domain tables in Postgres / MySQL / MongoDB / libsql,
+ *   they configure a backend here and use `b.externalDb.query()` instead
+ *   of `b.db.from()` for those tables. The same surface also serves
+ *   cluster-mode coordination (leader election advisory locks,
+ *   cross-replica routing) when the cluster provider points at the same
+ *   backend.
  *
- * Built-in protocol adapters (native pg-wire, libsql-HTTP, MongoDB wire)
- * are not currently bundled — operators supply `connect`/`query`/`close`
- * directly using their wire client of choice. When framework-bundled
- * adapters land they will be available as `b.externalDb.adapters.pg`,
- * `.libsqlHttp`, etc., but the bring-your-own-client API is the
- * permanent surface.
+ *   Bring-your-own-client design (per "zero npm runtime deps" rule):
+ *   the operator supplies the actual DB driver via each backend's
+ *   `connect` / `query` / `close` hooks. The framework layers
+ *   connection pooling (lazy-create, idle reaping), transient-error
+ *   retry, per-backend circuit breaker, classification routing
+ *   (which backend serves which data class), residency enforcement
+ *   against `db.getDataResidency().region`, and audit hooks
+ *   (`system.externaldb.{query,transaction,read}`).
  *
- * Public API:
- *   externalDb.init({ backends: { name: { connect, query, close?, ... } },
- *                     defaultBackend? })
- *   externalDb.query(sql, params?, opts?)         → { rows, rowCount }
- *   externalDb.transaction(fn, opts?)             → fn's return value
- *   externalDb.healthCheck(backendName?)          → backend status
- *   externalDb.listBackends()
- *   externalDb.shutdown()
+ *   Read-replica routing exposes `b.externalDb.read.query()` and
+ *   `b.externalDb.write.query()` — reads weight-round-robin across
+ *   declared replicas with health tracking and primary fallback;
+ *   writes always route to primary.
  *
- * Backend config:
- *   {
- *     connect():  async () → client (returns operator's DB client)
- *     query(client, sql, params): async → { rows, rowCount }
- *     close(client): async → void
- *     ping(client): async → bool                  (optional health check)
- *     beginTx(client): async → void               (optional; default 'BEGIN')
- *     commit(client): async → void                (optional; default 'COMMIT')
- *     rollback(client): async → void              (optional; default 'ROLLBACK')
- *     pool: { min: 1, max: 10, idleTimeoutMs: C.TIME.minutes(1) }
- *     classifications: ['personal' | 'operational' | 'public' | <custom>]
- *     residencyTag: 'EU' | 'US' | ...
- *     retry, breaker
- *   }
+ * @card
+ *   External-database integration for app data — Postgres / MySQL / SQLite / MongoDB connection pooling, retry, circuit breaker, classification routing, residency enforcement, and audit hooks.
  */
 var retryHelper = require("./retry");
 var C = require("./constants");
@@ -71,6 +56,92 @@ function _emitMetric(name, value, labels) {
   catch (_e) { /* hot-path observability sink — drop silent by design */ }
 }
 
+// Statement-class classifier for auth-failure forensics (D-M2). Inspects
+// the leading keyword only so an attacker-controlled trailing fragment
+// can't smuggle a false classification. Skips leading whitespace plus
+// SQL line / block comments before reading the keyword.
+var _STATEMENT_CLASS_RE = /^\s*(?:\/\*[\s\S]*?\*\/\s*|--[^\n]*\n\s*)*([A-Za-z]+)/;
+var _STATEMENT_CLASS_MAP = Object.freeze({
+  SELECT: "SELECT", WITH: "SELECT", VALUES: "SELECT", TABLE: "SELECT",
+  INSERT: "DML", UPDATE: "DML", DELETE: "DML", MERGE: "DML", UPSERT: "DML",
+  CREATE: "DDL", DROP: "DDL", ALTER: "DDL", TRUNCATE: "DDL",
+  RENAME: "DDL", COMMENT: "DDL",
+  GRANT: "DCL", REVOKE: "DCL",
+  SET: "SESSION", RESET: "SESSION",
+  BEGIN: "TX", START: "TX", COMMIT: "TX", ROLLBACK: "TX",
+  SAVEPOINT: "TX", RELEASE: "TX",
+  CALL: "ROUTINE", EXECUTE: "ROUTINE",
+  COPY: "BULK",
+  EXPLAIN: "META", ANALYZE: "META", VACUUM: "META",
+});
+
+function _classifyStatement(sql) {
+  if (typeof sql !== "string" || sql.length === 0) return "UNKNOWN";
+  var m = _STATEMENT_CLASS_RE.exec(sql);
+  if (!m) return "UNKNOWN";
+  return _STATEMENT_CLASS_MAP[m[1].toUpperCase()] || "OTHER";
+}
+
+// Postgres SQLSTATE classes that indicate authentication / authorization
+// failure at the DB level. SOC2 forensic gap (D-M2) — every match emits
+// db.auth.failed with the SQL identity attempted, the database, and
+// the statement class.
+var _AUTH_FAILURE_CODES = Object.freeze({
+  "28000": "invalid_authorization_specification",
+  "28P01": "invalid_password",
+  "42501": "insufficient_privilege",
+});
+
+function _emitAuthFailureAudit(backend, role, sql, e) {
+  if (!e || !e.code) return;
+  var kind = _AUTH_FAILURE_CODES[e.code];
+  if (!kind) return;
+  audit().safeEmit({
+    action:   "db.auth.failed",
+    actor:    {},
+    resource: { kind: "db.backend", id: backend.name },
+    outcome:  "denied",
+    reason:   kind,
+    metadata: {
+      backend:        backend.name,
+      dialect:        backend.dialect,
+      sqlIdentity:    role || null,
+      sqlstate:       e.code,
+      statementClass: _classifyStatement(sql),
+    },
+  });
+  _emitMetric("db.auth.failed", 1, {
+    backend:        backend.name,
+    sqlstate:       e.code,
+    statementClass: _classifyStatement(sql),
+  });
+}
+
+// Slow-query bucket emitter (D-L7). Single-shot per query — highest
+// matched bucket wins. Operators dashboard on the `bucket` label
+// rather than separate counters per threshold.
+var _SLOW_QUERY_BUCKETS = Object.freeze([
+  { ms: C.TIME.seconds(30), label: "30s" },
+  { ms: C.TIME.seconds(5),  label: "5s" },
+  { ms: C.TIME.seconds(1),  label: "1s" },
+]);
+
+function _emitSlowQuery(backendName, role, durationMs, statementClass) {
+  if (typeof durationMs !== "number" || !isFinite(durationMs)) return;
+  for (var i = 0; i < _SLOW_QUERY_BUCKETS.length; i++) {
+    var bucket = _SLOW_QUERY_BUCKETS[i];
+    if (durationMs >= bucket.ms) {
+      _emitMetric("db.query.slow", durationMs, {
+        backend:        backendName,
+        role:           role || "(none)",
+        bucket:         bucket.label,
+        statementClass: statementClass || "UNKNOWN",
+      });
+      return;
+    }
+  }
+}
+
 var _err = ExternalDbError.factory;
 
 var initialized = false;
@@ -184,6 +255,64 @@ class Pool {
 
 // ---- Init ----
 
+/**
+ * @primitive b.externalDb.init
+ * @signature b.externalDb.init(opts)
+ * @since     0.4.0
+ * @related   b.externalDb.query, b.externalDb.shutdown, b.externalDb.adapters.connectAs
+ *
+ * Register one or more app-data backends. Each backend declares its
+ * `connect` / `query` driver hooks plus optional pooling, classification,
+ * residency, retry, and replica configuration. Throws synchronously on
+ * malformed input (missing hooks, unknown dialect, residency mismatch
+ * against `db.getDataResidency()`, dotted GUC names that fail
+ * identifier validation).
+ *
+ * Boot-time residency check: when `db.getDataResidency().region` is set,
+ * any backend serving `personal` (or `*`) data must carry a
+ * `residencyTag` in the allowed-region list — refused with
+ * `RESIDENCY_VIOLATION` when not.
+ *
+ * @opts
+ *   backends:        { [name]: BackendConfig },   // required; one or more named backends
+ *   defaultBackend?: string,                      // pool used when no opts.backend / classification / role match (defaults to first)
+ *   dbRoleBackends?: { [sqlRole]: backendName },  // request-time role → backend mapping for the dbRoleFor middleware
+ *
+ *   // BackendConfig shape:
+ *   //   connect():            async () → driver client                 (required)
+ *   //   query(client, sql, p): async → { rows, rowCount }              (required)
+ *   //   close(client):        async → void                             (optional; default no-op)
+ *   //   ping(client):         async → void                             (optional; default `SELECT 1`)
+ *   //   beginTx / commit / rollback(client):  async → void             (optional; default `BEGIN`/`COMMIT`/`ROLLBACK`)
+ *   //   dialect:              "postgres" | "mysql" | "sqlite" | "mongodb" | "other"  (default "postgres")
+ *   //   applicationName:      string ≤ 63 bytes, no CR/LF/NUL          (Postgres pg_stat_activity tag; default null)
+ *   //   pool:                 { min, max, idleTimeoutMs }              (defaults: 1 / 10 / C.TIME.minutes(1))
+ *   //   classifications:      string[]                                 (defaults to ["*"])
+ *   //   residencyTag:         "EU" | "US" | "unrestricted" | ...       (defaults to "unrestricted")
+ *   //   retry, breaker:       passthrough to b.retry / CircuitBreaker
+ *   //   replicas:             [{ connect, query, weight?, residencyTag?, allowCrossBorder? }]
+ *   //   replicaFallbackToPrimary: boolean                              (default true)
+ *
+ * @example
+ *   var pg = require("pg");
+ *   var pool = new pg.Pool({ connectionString: "postgres://app:pw@db.example.com/app" });
+ *
+ *   b.externalDb.init({
+ *     backends: {
+ *       main: {
+ *         dialect:         "postgres",
+ *         applicationName: "blamejs-app",
+ *         connect:         function () { return pool.connect(); },
+ *         query:           function (client, sql, params) { return client.query(sql, params); },
+ *         close:           function (client) { return client.release(); },
+ *         classifications: ["personal", "operational"],
+ *         residencyTag:    "EU",
+ *         pool:            { min: 2, max: 20, idleTimeoutMs: 60000 },
+ *       },
+ *     },
+ *     defaultBackend: "main",
+ *   });
+ */
 function init(opts) {
   if (initialized) return;
   if (!opts || !opts.backends) throw new Error("externalDb.init({ backends }) is required");
@@ -210,10 +339,70 @@ function init(opts) {
         "backend '" + name + "': dialect must be one of " +
         "'postgres' | 'mysql' | 'sqlite' | 'mongodb' | 'other', got '" + dialect + "'", true);
     }
+    // OWASP-3 — application_name normalization for Postgres backends.
+    // Always set on every fresh connection (not just connectAs branch)
+    // so pg_stat_activity / log_line_prefix / audit log surfaces show
+    // a stable identifier instead of falling back to the driver's
+    // bare process name. CR / LF / NUL refused at config-time —
+    // those characters terminate the SET statement early in some
+    // drivers and have no legitimate use in an application_name.
+    // OWASP-3 — application_name normalization for Postgres backends.
+    // Opt-in via `cfg.applicationName` to surface a stable identifier
+    // in pg_stat_activity / log_line_prefix / Postgres audit log
+    // surfaces. Default leaves application_name to the driver — issuing
+    // a SET on every fresh connection at framework default would
+    // double-count queries for operators counting per-pool query
+    // activity (and break test fakes that count tracker.query calls).
+    var applicationName = cfg.applicationName !== undefined ? cfg.applicationName : null;
+    if (applicationName !== null && (typeof applicationName !== "string" || applicationName.length === 0)) {
+      throw _err("INVALID_CONFIG",
+        "backend '" + name + "': applicationName must be a non-empty string", true);
+    }
+    if (applicationName !== null) {
+      // eslint-disable-next-line no-control-regex
+      if (/[\r\n\u0000]/.test(applicationName)) {
+      throw _err("INVALID_CONFIG",
+        "backend '" + name + "': applicationName must not contain CR, LF, or NUL characters", true);
+      }
+      if (applicationName.length > C.BYTES.bytes(63)) {
+      throw _err("INVALID_CONFIG",
+        "backend '" + name + "': applicationName exceeds Postgres 63-byte limit (got " +
+        applicationName.length + ")", true);
+      }
+    }
+    var rawConnect = cfg.connect;
+    var rawQuery   = cfg.query;
+    var connectFn = rawConnect;
+    if (dialect === "postgres" && applicationName !== null) {
+      // IIFE captures per-iteration rawConnect/rawQuery; without this
+      // the var-hoisted bindings are shared across the for-loop and
+      // every backend's connectFn ends up calling the LAST iteration's
+      // rawQuery (classic closure-in-loop bug).
+      connectFn = (function (cn, qn, appName) {
+        var quotedAppName = "'" + appName.replace(/'/g, "''") + "'";
+        return async function () {
+          var client = await cn();
+          try {
+            await qn(client, "SET application_name TO " + quotedAppName, []);
+          } catch (_e) {
+            // Best-effort. Real Postgres always supports SET
+            // application_name; a driver that refuses it is a shim
+            // (test fake / non-PG backend mislabeled "postgres") and
+            // there's nothing useful to surface — keep the connection
+            // and let the operator hit any real query failure
+            // immediately afterwards.
+            void _e;
+          }
+          return client;
+        };
+      })(rawConnect, rawQuery, applicationName);
+    }
+    var poolCfg = Object.assign({}, cfg, { connect: connectFn });
     backends[name] = {
       name:            name,
       dialect:         dialect,
-      pool:            new Pool(name, cfg),
+      applicationName: applicationName,
+      pool:            new Pool(name, poolCfg),
       query:           cfg.query,
       ping:            cfg.ping || null,
       beginTx:         cfg.beginTx  || function (client) { return cfg.query(client, "BEGIN", []); },
@@ -332,6 +521,39 @@ function _servesClassification(b, cls) {
 
 // ---- Public API ----
 
+/**
+ * @primitive b.externalDb.query
+ * @signature b.externalDb.query(sql, params, opts)
+ * @since     0.4.0
+ * @related   b.externalDb.transaction, b.externalDb.read.query, b.externalDb.write.query
+ *
+ * Execute a single statement against the picked backend. Returns the
+ * driver-shaped `{ rows, rowCount }` from the backend's `query` hook.
+ * Wraps the call in `b.retry.withRetry` for transient driver errors
+ * and the per-backend circuit breaker; emits `system.externaldb.query`
+ * audit events plus duration / slow-query metrics; surfaces Postgres
+ * SQLSTATE 28000 / 28P01 / 42501 as `db.auth.failed` audit rows for
+ * SOC2 forensic walks.
+ *
+ * Backend selection precedence: `opts.backend` (explicit) →
+ * `opts.classification` (first backend serving the class) → ALS-bound
+ * dbRole + `dbRoleBackends` map (set by `b.middleware.dbRoleFor` or
+ * `b.externalDb.runAs`) → the configured `defaultBackend`.
+ *
+ * @opts
+ *   backend?:           string,   // explicit backend name; bypasses classification + role pick
+ *   classification?:    string,   // route to first backend whose classifications include this value
+ *   includeSqlInAudit?: boolean,  // emit SQL text in audit metadata (off by default — may carry literal PII)
+ *
+ * @example
+ *   var res = await b.externalDb.query(
+ *     "SELECT id, email FROM users WHERE tenant_id = $1",
+ *     ["acme"],
+ *     { classification: "personal" }
+ *   );
+ *   res.rowCount;   // → 42
+ *   res.rows[0];    // → { id: 1, email: "ada@example.com" }
+ */
 async function query(sql, params, opts) {
   _requireInit();
   opts = opts || {};
@@ -380,6 +602,7 @@ async function query(sql, params, opts) {
       { backend: b.name, role: role || "(none)" });
     _emitMetric("externaldb.query.duration_ms", durationMs,
       { backend: b.name, role: role || "(none)" });
+    _emitSlowQuery(b.name, role, durationMs, _classifyStatement(sql));
     return result;
   } catch (e) {
     var failureMs = Date.now() - t0;
@@ -392,6 +615,7 @@ async function query(sql, params, opts) {
     }, (e && e.message) || String(e));
     _emitMetric("externaldb.query.failure", 1,
       { backend: b.name, role: role || "(none)", errorCode: e.code || "(none)" });
+    _emitSlowQuery(b.name, role, failureMs, _classifyStatement(sql));
     // Postgres signals authorization-denied as SQLSTATE 42501
     // (insufficient_privilege). RLS-shaped writes that violate a
     // policy and GRANT-denied SELECTs both surface this code. The
@@ -403,10 +627,53 @@ async function query(sql, params, opts) {
       _emitMetric("db.role.denied", 1,
         { backend: b.name, role: role || "(none)" });
     }
+    // D-M2 — DB-auth audit visibility. Every 28000 / 28P01 / 42501
+    // surfaces an auditable db.auth.failed row tagged with the SQL
+    // identity and the statement class so SOC2 reviewers can
+    // reconstruct the denial timeline.
+    _emitAuthFailureAudit(b, role, sql, e);
     throw e;
   }
 }
 
+/**
+ * @primitive b.externalDb.transaction
+ * @signature b.externalDb.transaction(fn, opts)
+ * @since     0.4.0
+ * @related   b.externalDb.query, b.externalDb.write.query
+ *
+ * Run `fn(tx)` inside a transaction on the picked backend. Wraps the
+ * body in `BEGIN` / `COMMIT` / `ROLLBACK` via the backend's hooks;
+ * commits on resolve, rolls back on throw. Transient deadlock /
+ * serialization failures (Postgres SQLSTATE `40P01` / `40001`) retry
+ * automatically with a small jittered backoff (default 3 attempts;
+ * tune via `opts.deadlockRetries`).
+ *
+ * `tx.query(sql, params)` runs against the same client used by
+ * `BEGIN`, so RLS state set by `sessionGucs` (`SET LOCAL`) applies for
+ * the duration of the transaction and resets at COMMIT/ROLLBACK.
+ *
+ * @opts
+ *   backend?:                    string,                       // explicit backend name
+ *   classification?:             string,                       // route by data class
+ *   sessionGucs?:                { [name]: string|number|boolean },  // SET LOCAL bindings (e.g. { "app.tenant_id": "acme" })
+ *   statementTimeoutMs?:         number,                       // SET LOCAL statement_timeout
+ *   idleInTransactionTimeoutMs?: number,                       // SET LOCAL idle_in_transaction_session_timeout
+ *   deadlockRetries?:            number,                       // retries for 40P01 / 40001 (default 3)
+ *
+ * @example
+ *   var summary = await b.externalDb.transaction(async function (tx) {
+ *     await tx.query("INSERT INTO orders(id, total) VALUES ($1, $2)", ["o-1", 4200]);
+ *     await tx.query("UPDATE inventory SET qty = qty - 1 WHERE sku = $1", ["sku-7"]);
+ *     var res = await tx.query("SELECT count(*) AS n FROM orders WHERE id = $1", ["o-1"]);
+ *     return res.rows[0];
+ *   }, {
+ *     classification: "operational",
+ *     sessionGucs:    { "app.tenant_id": "acme" },
+ *     statementTimeoutMs: 5000,
+ *   });
+ *   summary.n;   // → 1
+ */
 async function transaction(fn, opts) {
   _requireInit();
   if (typeof fn !== "function") throw _err("INVALID_FN", "transaction requires a function", true);
@@ -504,6 +771,11 @@ async function transaction(fn, opts) {
             _emitMetric("db.role.denied", 1,
               { backend: b.name, role: role || "(none)" });
           }
+          // D-M2 — DB-auth audit visibility on transaction-shaped denials.
+          // Statement class always reads as "TX" since the failure
+          // surface inside a transaction body could be any statement;
+          // operators correlate via the transaction's audit row.
+          _emitAuthFailureAudit(b, role, "BEGIN", txErr);
           throw txErr;
         }
       }
@@ -513,6 +785,28 @@ async function transaction(fn, opts) {
   });
 }
 
+/**
+ * @primitive b.externalDb.healthCheck
+ * @signature b.externalDb.healthCheck(backendName)
+ * @since     0.4.0
+ * @related   b.externalDb.listBackends, b.externalDb.shutdown
+ *
+ * Ping a backend by acquiring a client and running its `ping` hook (or
+ * `SELECT 1` when none is supplied). Returns `{ ok, breakerState, pool }`
+ * for a single backend, or a `{ [name]: result }` map when called with
+ * no argument. Connection-shape errors destroy the client; the breaker
+ * state is reflected in the returned record so health endpoints can
+ * surface circuit-open conditions.
+ *
+ * @example
+ *   var all = await b.externalDb.healthCheck();
+ *   all.main.ok;             // → true
+ *   all.main.breakerState;   // → "closed"
+ *   all.main.pool;           // → { idle: 1, active: 0, waiters: 0 }
+ *
+ *   var one = await b.externalDb.healthCheck("main");
+ *   one.ok;                  // → true
+ */
 async function healthCheck(backendName) {
   _requireInit();
   if (backendName) {
@@ -543,6 +837,25 @@ async function _pingBackend(b) {
   }
 }
 
+/**
+ * @primitive b.externalDb.listBackends
+ * @signature b.externalDb.listBackends()
+ * @since     0.4.0
+ * @related   b.externalDb.healthCheck, b.externalDb.init
+ *
+ * Snapshot every registered backend's name, dialect, classifications,
+ * residency tag, breaker state, and live pool stats. Returns `[]` when
+ * `init()` has not run. Cheap — does not open any new connections.
+ *
+ * @example
+ *   var rows = b.externalDb.listBackends();
+ *   rows[0].name;             // → "main"
+ *   rows[0].dialect;          // → "postgres"
+ *   rows[0].classifications;  // → ["personal", "operational"]
+ *   rows[0].residencyTag;     // → "EU"
+ *   rows[0].breakerState;     // → "closed"
+ *   rows[0].pool;             // → { idle: 2, active: 0, waiters: 0 }
+ */
 function listBackends() {
   if (!initialized) return [];
   return Object.keys(backends).map(function (name) {
@@ -558,6 +871,24 @@ function listBackends() {
   });
 }
 
+/**
+ * @primitive b.externalDb.shutdown
+ * @signature b.externalDb.shutdown()
+ * @since     0.4.0
+ * @related   b.externalDb.init, b.externalDb.healthCheck
+ *
+ * Drain every backend pool (and replica pool), close idle clients,
+ * then clear all registry state so a subsequent `init()` starts from
+ * scratch. Idempotent — calling before `init()` is a no-op. Wire to
+ * `b.appShutdown` so process exit waits for in-flight queries to
+ * release their clients.
+ *
+ * @example
+ *   process.on("SIGTERM", async function () {
+ *     await b.externalDb.shutdown();
+ *     process.exit(0);
+ *   });
+ */
 async function shutdown() {
   if (!initialized) return;
   for (var name in backends) {
@@ -686,12 +1017,46 @@ function _requireInit() {
 
 var REPLICA_UNHEALTHY_COOLDOWN_MS = C.TIME.seconds(30);
 
+// F-CBT-2 — replica residency-tag compatibility.
+//
+// A primary tagged "EU" replicating to a "US" replica is a GDPR
+// Article 46 cross-border transfer; without an explicit operator
+// opt-in the framework refuses init under gdpr / dpdp / pipl-cn /
+// uk-gdpr postures. Operator suppresses the gate per replica via
+// allowCrossBorder: true (which the framework records in the audit
+// chain so a compliance reviewer sees the conscious decision).
+//
+// Compatible-residency rules:
+//   - Identical tags  (EU↔EU, US↔US): always compatible.
+//   - "unrestricted" tag on either side: compatible (operator
+//     declared no constraint).
+//   - Different tags: compatible only when allowCrossBorder is true.
+var CROSS_BORDER_REGULATED_POSTURES = Object.freeze([
+  "gdpr", "uk-gdpr", "dpdp", "pipl-cn", "lgpd-br", "appi-jp", "pdpa-sg",
+]);
+
+function _residencyCompatible(primaryTag, replicaTag) {
+  if (!primaryTag || !replicaTag) return true;
+  if (primaryTag === replicaTag) return true; // allow:raw-hash-compare — residency tag string, not a secret hash
+  if (primaryTag === "unrestricted" || replicaTag === "unrestricted") return true;
+  return false;
+}
+
+function _activePosture() {
+  try {
+    var compliance = require("./compliance");                                                    // allow:inline-require — defensive against optional load
+    return compliance.current();
+  } catch (_e) { return null; }
+}
+
 function _buildReplicas(backendName, cfg) {
   if (!cfg.replicas) return null;
   if (!Array.isArray(cfg.replicas) || cfg.replicas.length === 0) {
     throw _err("INVALID_CONFIG",
       "backend '" + backendName + "': replicas must be a non-empty array", true);
   }
+  var primaryTag = cfg.residencyTag || "unrestricted";
+  var posture = _activePosture();
   var out = [];
   for (var i = 0; i < cfg.replicas.length; i++) {
     var r = cfg.replicas[i];
@@ -709,11 +1074,33 @@ function _buildReplicas(backendName, cfg) {
       throw _err("INVALID_CONFIG",
         "backend '" + backendName + "': replicas[" + i + "].weight must be a positive integer", true);
     }
+    var replicaTag = r.residencyTag || "unrestricted";
+    var allowCrossBorder = r.allowCrossBorder === true;
+    if (!_residencyCompatible(primaryTag, replicaTag) && !allowCrossBorder) {
+      var underPosture = posture && CROSS_BORDER_REGULATED_POSTURES.indexOf(posture) !== -1;
+      throw _err("RESIDENCY_MISMATCH",
+        "backend '" + backendName + "': replica[" + i +
+        "] residencyTag '" + replicaTag +
+        "' is not compatible with primary residencyTag '" + primaryTag +
+        "'" + (underPosture ? " under '" + posture + "' posture" : "") +
+        ". This is a cross-border data transfer (GDPR Art 46 / DPDP / PIPL " +
+        "category). Pass allowCrossBorder: true on the replica config with a " +
+        "documented legal basis (SCCs / BCRs / adequacy decision) to suppress.", true);
+    }
+    if (!_residencyCompatible(primaryTag, replicaTag) && allowCrossBorder) {
+      _emit("externalDb.replica.cross_border_allowed", "warning",
+        { backend: backendName, replicaIndex: i,
+          primaryTag: primaryTag, replicaTag: replicaTag,
+          legalBasis: r.legalBasis || null,
+          posture: posture || null });
+    }
     out.push({
       index:           i,
       pool:            new Pool(backendName + ":replica:" + i, r),
       query:           r.query,
       weight:          weight,
+      residencyTag:    replicaTag,
+      allowCrossBorder: allowCrossBorder,
       lastFailureAt:   0,
       consecutiveFailures: 0,
     });
@@ -807,6 +1194,8 @@ async function _readQuery(sql, params, opts) {
       _emitMetric("db.role.denied", 1,
         { backend: b.name, role: role || "(none)" });
     }
+    // D-M2 — DB-auth audit visibility for read-replica denials too.
+    _emitAuthFailureAudit(b, role, sql, e);
     // Fallback to primary on a failed replica read when allowed.
     if (b.replicaFallbackToPrimary) {
       return query(sql, params, opts);
@@ -815,10 +1204,86 @@ async function _readQuery(sql, params, opts) {
   }
 }
 
+/**
+ * @primitive b.externalDb.read.query
+ * @signature b.externalDb.read.query(sql, params, opts)
+ * @since     0.4.0
+ * @related   b.externalDb.write.query, b.externalDb.query, b.externalDb.init
+ *
+ * Route a read against the backend's declared replicas using weighted
+ * round-robin. A failed replica is sidelined for 30 seconds and the
+ * call falls back to primary when `replicaFallbackToPrimary` is true
+ * (the default). Backends without replicas transparently route to
+ * primary. Same `opts` selection rules as `b.externalDb.query`
+ * (`backend` / `classification` / ALS-bound role).
+ *
+ * @opts
+ *   backend?:        string,   // explicit backend name
+ *   classification?: string,   // route by data class
+ *
+ * @example
+ *   var res = await b.externalDb.read.query(
+ *     "SELECT id, total FROM orders WHERE tenant_id = $1",
+ *     ["acme"],
+ *     { classification: "operational" }
+ *   );
+ *   res.rowCount;   // → 7
+ *   res.rows[0];    // → { id: "o-1", total: 4200 }
+ */
 var read = {
   query: _readQuery,
 };
 
+/**
+ * @primitive b.externalDb.write.query
+ * @signature b.externalDb.write.query(sql, params, opts)
+ * @since     0.4.0
+ * @related   b.externalDb.read.query, b.externalDb.query, b.externalDb.write.transaction
+ *
+ * Symmetric alias for `b.externalDb.query` — always routes to primary.
+ * Pair with `b.externalDb.read.query` when an operator wants the call
+ * site to express read/write intent without a magic-comment hint.
+ * Same `opts` selection rules as `b.externalDb.query`.
+ *
+ * @opts
+ *   backend?:           string,   // explicit backend name
+ *   classification?:    string,   // route by data class
+ *   includeSqlInAudit?: boolean,  // emit SQL text in audit metadata
+ *
+ * @example
+ *   var res = await b.externalDb.write.query(
+ *     "INSERT INTO orders(id, tenant_id, total) VALUES ($1, $2, $3)",
+ *     ["o-2", "acme", 1500],
+ *     { classification: "operational" }
+ *   );
+ *   res.rowCount;   // → 1
+ */
+/**
+ * @primitive b.externalDb.write.transaction
+ * @signature b.externalDb.write.transaction(fn, opts)
+ * @since     0.4.0
+ * @related   b.externalDb.transaction, b.externalDb.write.query
+ *
+ * Symmetric alias for `b.externalDb.transaction` — always runs against
+ * primary. Same `opts` shape (sessionGucs / statementTimeoutMs /
+ * idleInTransactionTimeoutMs / deadlockRetries) as the canonical form.
+ *
+ * @opts
+ *   backend?:                    string,
+ *   classification?:             string,
+ *   sessionGucs?:                { [name]: string|number|boolean },
+ *   statementTimeoutMs?:         number,
+ *   idleInTransactionTimeoutMs?: number,
+ *   deadlockRetries?:            number,
+ *
+ * @example
+ *   var n = await b.externalDb.write.transaction(async function (tx) {
+ *     await tx.query("UPDATE counters SET n = n + 1 WHERE k = $1", ["hits"]);
+ *     var res = await tx.query("SELECT n FROM counters WHERE k = $1", ["hits"]);
+ *     return res.rows[0].n;
+ *   }, { sessionGucs: { "app.tenant_id": "acme" } });
+ *   typeof n;   // → "number"
+ */
 // write namespace — alias for the primary path. Lets operators express
 // intent symmetrically with read.query without a magic-comment hint.
 var write = {
@@ -852,6 +1317,30 @@ function _resetForTest() {
 // clients are kept; new acquisitions respect the new max. min is honored
 // the next time the pool refills. idleTimeoutMs takes effect on the next
 // reaper tick.
+/**
+ * @primitive b.externalDb.configurePool
+ * @signature b.externalDb.configurePool(backendName, opts)
+ * @since     0.4.0
+ * @related   b.externalDb.init, b.externalDb.listBackends
+ *
+ * Resize a registered backend's pool at runtime. New `max` takes effect
+ * on the next acquire; existing idle clients are kept; `min` is honored
+ * when the pool next refills; `idleTimeoutMs` applies on the next
+ * reaper tick. Throws on unknown options or non-positive integers so a
+ * config typo surfaces at the call site.
+ *
+ * @opts
+ *   min?:           number,   // positive integer; floor on idle clients
+ *   max?:           number,   // positive integer; ceiling on total clients (must be >= min)
+ *   idleTimeoutMs?: number,   // positive integer; reap idle clients after this many ms
+ *
+ * @example
+ *   b.externalDb.configurePool("main", {
+ *     min:           4,
+ *     max:           50,
+ *     idleTimeoutMs: 120000,
+ *   });
+ */
 function configurePool(backendName, opts) {
   _requireInit();
   if (typeof backendName !== "string" || backendName.length === 0) {
@@ -1031,6 +1520,51 @@ function _connectAs(rawConnect, query, opts) {
   };
 }
 
+/**
+ * @primitive b.externalDb.adapters.connectAs
+ * @signature b.externalDb.adapters.connectAs(connect, opts)
+ * @since     0.4.0
+ * @related   b.externalDb.init, b.externalDb.runAs
+ *
+ * Wrap a Postgres `connect` so every fresh client runs `SET ROLE`,
+ * `SET search_path`, `SET application_name`, `SET statement_timeout`,
+ * and any operator-supplied `gucs` before being handed to the pool.
+ * Identifier inputs (role, schemas, GUC names) are validated via
+ * `safeSql.validateIdentifier` at call time so a bad name throws once
+ * at boot rather than per acquired client. Returns the wrapped
+ * `connect` function suitable for a backend's `connect` hook.
+ *
+ * @opts
+ *   query:               function,    // required — the backend's query function (used to issue SET statements)
+ *   role?:               string,      // SQL identifier; runs SET ROLE "<role>"
+ *   searchPath?:         string[],    // SQL identifiers; runs SET search_path TO "<a>", "<b>", ...
+ *   applicationName?:    string,      // appears in pg_stat_activity
+ *   statementTimeoutMs?: number,      // positive integer; SET statement_timeout TO <ms>
+ *   gucs?:               { [name]: string|number },   // raw GUC bindings; finite numbers required for numeric values
+ *
+ * @example
+ *   var pg = require("pg");
+ *   var pool = new pg.Pool({ connectionString: "postgres://app:pw@db.example.com/app" });
+ *   var rawConnect = function () { return pool.connect(); };
+ *   var rawQuery   = function (client, sql, params) { return client.query(sql, params); };
+ *
+ *   b.externalDb.init({
+ *     backends: {
+ *       analytics: {
+ *         dialect: "postgres",
+ *         connect: b.externalDb.adapters.connectAs(rawConnect, {
+ *           query:               rawQuery,
+ *           role:                "analytics_user",
+ *           searchPath:          ["analytics", "public"],
+ *           applicationName:     "blamejs:analytics",
+ *           statementTimeoutMs:  30000,
+ *           gucs:                { idle_in_transaction_session_timeout: "60s" },
+ *         }),
+ *         query: rawQuery,
+ *       },
+ *     },
+ *   });
+ */
 // Operators import the helper as `b.externalDb.adapters.connectAs(connect, opts)`
 // — declarative wrapping with shared input validation.
 function _adaptersConnectAs(connect, opts) {
@@ -1069,6 +1603,31 @@ function _adaptersConnectAs(connect, opts) {
 //
 // currentRole() returns the active role (or null) — useful for diagnostic
 // logs and observability labels.
+/**
+ * @primitive b.externalDb.runAs
+ * @signature b.externalDb.runAs(role, fn)
+ * @since     0.4.0
+ * @related   b.externalDb.currentRole, b.externalDb.adapters.connectAs
+ *
+ * Bind a SQL role on the deep async-local context for the duration of
+ * `fn()`. Every `b.externalDb.query` / `read.query` / `write.query` /
+ * `transaction` call inside the bound region picks the backend mapped
+ * to `role` via the `dbRoleBackends` map declared at `init()`, so
+ * background workers (cron, queue consumers, CLI commands) get the
+ * same role-aware routing as HTTP requests under
+ * `b.middleware.dbRoleFor`. Pass `null` to clear. Audits role
+ * transitions as `db.role.switched`. Identifier-validates the role at
+ * the call site so a typo throws synchronously.
+ *
+ * @example
+ *   await b.externalDb.runAs("analytics_user", async function () {
+ *     var res = await b.externalDb.read.query(
+ *       "SELECT count(*) AS n FROM events WHERE day = $1",
+ *       ["2026-05-09"]
+ *     );
+ *     return res.rows[0].n;
+ *   });
+ */
 function runAs(role, fn) {
   if (typeof fn !== "function") {
     throw _err("INVALID_FN", "externalDb.runAs: fn must be a function", true);
@@ -1104,10 +1663,195 @@ function runAs(role, fn) {
   return dbRoleContext.runWithRole(role || null, fn);
 }
 
+/**
+ * @primitive b.externalDb.currentRole
+ * @signature b.externalDb.currentRole()
+ * @since     0.4.0
+ * @related   b.externalDb.runAs
+ *
+ * Read the SQL role bound on the deep async-local context. Returns
+ * `null` when no role is bound. Useful for diagnostic logs, audit
+ * metadata, and observability labels — the value flows through the
+ * same context that `b.externalDb.query` consults for backend pick.
+ *
+ * @example
+ *   await b.externalDb.runAs("analytics_user", async function () {
+ *     b.externalDb.currentRole();   // → "analytics_user"
+ *   });
+ *   b.externalDb.currentRole();     // → null
+ */
 function currentRole() {
   return dbRoleContext.getRole();
 }
 
+// OWASP-2 — pg_roles enumeration / unrecognized-role guard.
+//
+// Boot-time check that compares pg_roles membership to the operator-
+// declared role list. Operators declare every role they expect to
+// exist on the cluster (via opts.declaredRoles); the gate refuses or
+// audits when pg_roles surfaces names not in that list — typical
+// signal of a forgotten ALTER ROLE / a leftover migration role / a
+// privileged role added outside change-management.
+//
+//   await b.externalDb.assertRoleHardening({
+//     backend:        "main",
+//     declaredRoles:  ["app_user", "analytics_user", "admin"],
+//     mode:           "audit",          // "audit" | "throw"
+//     ignoreSystem:   true,              // skip rds_*, pg_*, postgres
+//   });
+//
+// Returns { declared, observed, unrecognized, missing }. mode="throw"
+// raises ROLE_HARDENING_FAIL when unrecognized rows surface; default
+// "audit" emits db.role.hardening.unrecognized so dashboards see the
+// drift without breaking boot.
+/**
+ * @primitive b.externalDb.assertRoleHardening
+ * @signature b.externalDb.assertRoleHardening(opts)
+ * @since     0.7.0
+ * @related   b.externalDb.runAs, b.externalDb.adapters.connectAs
+ *
+ * Compare `pg_roles` membership against an operator-declared role
+ * allowlist on a Postgres backend. Surfaces unrecognized roles
+ * (forgotten ALTER ROLE leftovers, migration roles, privileged grants
+ * added outside change-management) and missing roles (declared but not
+ * present). Default `mode: "audit"` emits
+ * `db.role.hardening.unrecognized` / `.ok` so dashboards see drift
+ * without breaking boot; `mode: "throw"` fails boot when unrecognized
+ * roles surface. Non-Postgres dialects emit `db.role.hardening.skipped`
+ * and return empty observed lists.
+ *
+ * @opts
+ *   declaredRoles: string[],            // required; allowlist of expected role names
+ *   backend?:      string,              // explicit backend name (defaults to defaultBackend)
+ *   mode?:         "audit" | "throw",   // default "audit"
+ *   ignoreSystem?: boolean,             // skip postgres / pg_* / rds_* / azure_* / cloudsqlsuperuser (default true)
+ *
+ * @example
+ *   var report = await b.externalDb.assertRoleHardening({
+ *     backend:       "main",
+ *     declaredRoles: ["app_user", "analytics_user", "admin"],
+ *     mode:          "audit",
+ *     ignoreSystem:  true,
+ *   });
+ *   report.unrecognized;   // → []
+ *   report.missing;        // → []
+ *   report.observed;       // → ["admin", "analytics_user", "app_user"]
+ */
+async function assertRoleHardening(opts) {
+  _requireInit();
+  if (!opts || typeof opts !== "object") {
+    throw _err("INVALID_CONFIG",
+      "assertRoleHardening: opts is required ({ declaredRoles, backend?, mode? })", true);
+  }
+  if (!Array.isArray(opts.declaredRoles)) {
+    throw _err("INVALID_CONFIG",
+      "assertRoleHardening: opts.declaredRoles must be an array of role names", true);
+  }
+  for (var i = 0; i < opts.declaredRoles.length; i++) {
+    var r = opts.declaredRoles[i];
+    if (typeof r !== "string" || r.length === 0) {
+      throw _err("INVALID_CONFIG",
+        "assertRoleHardening: declaredRoles[" + i + "] must be a non-empty string", true);
+    }
+  }
+  var mode = opts.mode || "audit";
+  if (mode !== "audit" && mode !== "throw") {
+    throw _err("INVALID_CONFIG",
+      "assertRoleHardening: mode must be 'audit' or 'throw' (got '" + mode + "')", true);
+  }
+  var backendName = opts.backend || defaultBackend;
+  var b = backends[backendName];
+  if (!b) {
+    throw _err("UNKNOWN_BACKEND",
+      "assertRoleHardening: no backend named '" + backendName + "'", true);
+  }
+  if (b.dialect !== "postgres") {
+    // Non-Postgres dialects don't have pg_roles. The check is a no-op
+    // with a clear audit row so operators see the skip rather than
+    // assume hardening ran.
+    audit().safeEmit({
+      action:   "db.role.hardening.skipped",
+      actor:    {},
+      resource: { kind: "db.backend", id: backendName },
+      outcome:  "success",
+      metadata: { dialect: b.dialect, reason: "non-postgres" },
+    });
+    return { declared: opts.declaredRoles.slice(), observed: [], unrecognized: [], missing: [] };
+  }
+  var ignoreSystem = opts.ignoreSystem !== false;   // default true
+  var rows;
+  try {
+    var res = await query(
+      "SELECT rolname FROM pg_roles ORDER BY rolname",
+      [],
+      { backend: backendName }
+    );
+    rows = (res && res.rows) || [];
+  } catch (e) {
+    audit().safeEmit({
+      action:   "db.role.hardening.unreadable",
+      actor:    {},
+      resource: { kind: "db.backend", id: backendName },
+      outcome:  "failure",
+      reason:   (e && e.message) || String(e),
+      metadata: { backend: backendName },
+    });
+    throw _err("ROLE_HARDENING_UNREADABLE",
+      "assertRoleHardening: could not read pg_roles on backend '" + backendName + "': " +
+      ((e && e.message) || String(e)), true);
+  }
+  var observed = rows.map(function (r) { return r.rolname; });
+  if (ignoreSystem) {
+    observed = observed.filter(function (n) {
+      return !(n === "postgres" || n.indexOf("pg_") === 0 || n.indexOf("rds_") === 0 ||
+               n.indexOf("rdsadmin") === 0 || n.indexOf("azure_") === 0 ||
+               n.indexOf("cloudsqlsuperuser") === 0);
+    });
+  }
+  var declaredSet = {};
+  opts.declaredRoles.forEach(function (n) { declaredSet[n] = true; });
+  var observedSet = {};
+  observed.forEach(function (n) { observedSet[n] = true; });
+  var unrecognized = observed.filter(function (n) { return !declaredSet[n]; });
+  var missing      = opts.declaredRoles.filter(function (n) { return !observedSet[n]; });
+  if (unrecognized.length > 0 || missing.length > 0) {
+    audit().safeEmit({
+      action:   "db.role.hardening.unrecognized",
+      actor:    {},
+      resource: { kind: "db.backend", id: backendName },
+      outcome:  unrecognized.length > 0 ? "denied" : "failure",
+      metadata: {
+        backend:      backendName,
+        unrecognized: unrecognized,
+        missing:      missing,
+        observedCount: observed.length,
+      },
+    });
+    if (mode === "throw" && unrecognized.length > 0) {
+      throw _err("ROLE_HARDENING_FAIL",
+        "assertRoleHardening: pg_roles surfaces " + unrecognized.length +
+        " unrecognized role(s) on backend '" + backendName + "': " +
+        unrecognized.join(", ") + ". Either add them to declaredRoles after " +
+        "review, REVOKE them, or set mode: 'audit' to downgrade to audit-only.",
+        true);
+    }
+  } else {
+    audit().safeEmit({
+      action:   "db.role.hardening.ok",
+      actor:    {},
+      resource: { kind: "db.backend", id: backendName },
+      outcome:  "success",
+      metadata: { backend: backendName, observedCount: observed.length },
+    });
+  }
+  return {
+    declared:     opts.declaredRoles.slice(),
+    observed:     observed,
+    unrecognized: unrecognized,
+    missing:      missing,
+  };
+}
+
 module.exports = {
   init:           init,
   query:          query,
@@ -1115,11 +1859,12 @@ module.exports = {
   healthCheck:    healthCheck,
   listBackends:   listBackends,
   shutdown:       shutdown,
-  configurePool:  configurePool,
-  read:           read,
-  write:          write,
-  runAs:          runAs,
-  currentRole:    currentRole,
+  configurePool:        configurePool,
+  read:                 read,
+  write:                write,
+  runAs:                runAs,
+  currentRole:          currentRole,
+  assertRoleHardening:  assertRoleHardening,
   adapters: {
     connectAs:    _adaptersConnectAs,
   },