@blamejs/core 0.6.5 → 0.6.6

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **0.6.5** (2026-05-01) — b.db.declareView + b.externalDb.migrate
 - **0.6.4** (2026-05-01) — wiki schema docs realigned with the actual lib API
 - **0.6.3** (2026-05-01) — externalDb pool tuning + role-aware connect + read-replica routing
 - **0.6.2** (2026-05-01) — input validation + identifier-quoting consistency

package/lib/db-declare-row-policy.js

@@ -0,0 +1,272 @@
+"use strict";
+/**
+ * b.db.declareRowPolicy — declarative Postgres ROW LEVEL SECURITY policy
+ * migration spec.
+ *
+ * Returns a migration-shape object that b.externalDb.migrate(...) applies
+ * against a Postgres backend. Generates:
+ *
+ *   ALTER TABLE <schema>.<table> ENABLE ROW LEVEL SECURITY;     -- idempotent
+ *   CREATE POLICY <name> ON <schema>.<table>
+ *     [AS PERMISSIVE | RESTRICTIVE]
+ *     FOR <command>
+ *     [TO <role>]
+ *     USING (<expr>)
+ *     [WITH CHECK (<expr>)];
+ *
+ * Pairs with b.externalDb.transaction({ sessionGucs: { 'app.tenant_id': uuid } })
+ * for the per-request `SET LOCAL` plumbing. The recommended tenant-per-row
+ * shape:
+ *
+ *   b.db.declareRowPolicy({
+ *     schema:    "public",
+ *     table:     "sessions",
+ *     name:      "tenant_isolation",
+ *     role:      "app_user",
+ *     using:     "tenant_id = current_setting('app.tenant_id')::uuid",
+ *     withCheck: "tenant_id = current_setting('app.tenant_id')::uuid",
+ *     command:   "ALL",
+ *   });
+ *
+ *   await b.externalDb.transaction(async function (tx) {
+ *     return await tx.query("SELECT * FROM sessions WHERE _id = $1", [sid]);
+ *   }, { sessionGucs: { "app.tenant_id": req.user.tenantId } });
+ *
+ * Postgres-only: SQLite + MySQL have no equivalent grammar. Apply throws
+ * NOT_SUPPORTED at migration-apply time when the targeted backend's
+ * dialect isn't "postgres".
+ *
+ * Validation at declareRowPolicy() call time — bad shape throws here, not
+ * at apply time:
+ *   - schema, table, name, role → safeSql.validateIdentifier
+ *   - command ∈ {ALL, SELECT, INSERT, UPDATE, DELETE}
+ *   - permissive boolean
+ *   - using / withCheck operator-supplied SQL strings; semicolons rejected
+ *
+ * Audit metadata emitted on apply:
+ *   {
+ *     policy:    "schema.table.name",
+ *     table:     "schema.table",
+ *     role:      "...",
+ *     command:   "ALL"|...,
+ *     permissive: true|false,
+ *     hasWithCheck: bool,
+ *   }
+ */
+var safeSql = require("./safe-sql");
+var { defineClass } = require("./framework-error");
+
+var DeclareRowPolicyError = defineClass("DeclareRowPolicyError", { alwaysPermanent: true });
+
+var ALLOWED_OPTS = [
+  "schema", "table", "name", "role",
+  "using", "withCheck", "command", "permissive", "backend",
+];
+
+var ALLOWED_COMMANDS = ["ALL", "SELECT", "INSERT", "UPDATE", "DELETE"];
+
+function _err(code, message) {
+  return new DeclareRowPolicyError(code, message);
+}
+
+function _validateIdent(where, value) {
+  try {
+    safeSql.validateIdentifier(value, { allowReserved: true });
+  } catch (e) {
+    throw _err("declare-row-policy/bad-identifier",
+      where + ": invalid identifier '" + value + "': " + ((e && e.message) || String(e)));
+  }
+}
+
+function _validateExpression(where, value) {
+  if (typeof value !== "string") {
+    throw _err("declare-row-policy/bad-type", where + " must be a string");
+  }
+  if (value.length === 0) {
+    throw _err("declare-row-policy/empty-expression", where + " must be a non-empty boolean expression");
+  }
+  if (value.indexOf(";") !== -1) {
+    throw _err("declare-row-policy/bad-expression",
+      where + " must not contain ';' — use a single boolean expression");
+  }
+  return value;
+}
+
+function _validateOpts(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw _err("declare-row-policy/bad-opts", "declareRowPolicy requires an opts object");
+  }
+  for (var k in opts) {
+    if (Object.prototype.hasOwnProperty.call(opts, k) && ALLOWED_OPTS.indexOf(k) === -1) {
+      throw _err("declare-row-policy/unknown-opt",
+        "unknown opt '" + k + "'. Allowed: " + ALLOWED_OPTS.join(", "));
+    }
+  }
+
+  if (typeof opts.schema !== "string" || opts.schema.length === 0) {
+    throw _err("declare-row-policy/missing-opt", "schema is required");
+  }
+  _validateIdent("schema", opts.schema);
+
+  if (typeof opts.table !== "string" || opts.table.length === 0) {
+    throw _err("declare-row-policy/missing-opt", "table is required");
+  }
+  _validateIdent("table", opts.table);
+
+  if (typeof opts.name !== "string" || opts.name.length === 0) {
+    throw _err("declare-row-policy/missing-opt", "name is required");
+  }
+  _validateIdent("name", opts.name);
+
+  var role = null;
+  if (opts.role !== undefined && opts.role !== null) {
+    if (typeof opts.role !== "string" || opts.role.length === 0) {
+      throw _err("declare-row-policy/bad-type", "role must be a non-empty string");
+    }
+    _validateIdent("role", opts.role);
+    role = opts.role;
+  }
+
+  if (opts.using === undefined || opts.using === null) {
+    throw _err("declare-row-policy/missing-opt", "using is required (USING expression)");
+  }
+  var using = _validateExpression("using", opts.using);
+
+  var withCheck = null;
+  if (opts.withCheck !== undefined && opts.withCheck !== null) {
+    withCheck = _validateExpression("withCheck", opts.withCheck);
+  }
+
+  var command = "ALL";
+  if (opts.command !== undefined && opts.command !== null) {
+    if (typeof opts.command !== "string") {
+      throw _err("declare-row-policy/bad-type", "command must be a string");
+    }
+    var upper = opts.command.toUpperCase();
+    if (ALLOWED_COMMANDS.indexOf(upper) === -1) {
+      throw _err("declare-row-policy/bad-command",
+        "command must be one of " + ALLOWED_COMMANDS.join(", ") + ", got '" + opts.command + "'");
+    }
+    command = upper;
+  }
+
+  var permissive = true;
+  if (opts.permissive !== undefined && opts.permissive !== null) {
+    if (typeof opts.permissive !== "boolean") {
+      throw _err("declare-row-policy/bad-type", "permissive must be a boolean");
+    }
+    permissive = opts.permissive;
+  }
+
+  if (opts.backend !== undefined && opts.backend !== null) {
+    if (typeof opts.backend !== "string" || opts.backend.length === 0) {
+      throw _err("declare-row-policy/bad-type", "backend must be a non-empty string");
+    }
+  }
+
+  return {
+    schema:     opts.schema,
+    table:      opts.table,
+    name:       opts.name,
+    role:       role,
+    using:      using,
+    withCheck:  withCheck,
+    command:    command,
+    permissive: permissive,
+    backend:    opts.backend || null,
+  };
+}
+
+function _ensureBackendIsPostgres(externalDb, backendName) {
+  var list = externalDb.listBackends();
+  var found = null;
+  for (var i = 0; i < list.length; i++) {
+    if (list[i].name === backendName) { found = list[i]; break; }
+  }
+  if (!found) {
+    throw _err("declare-row-policy/unknown-backend",
+      "no externalDb backend named '" + backendName + "' — declared backends: " +
+      list.map(function (b) { return b.name; }).join(", "));
+  }
+  if (found.dialect !== "postgres") {
+    throw _err("declare-row-policy/not-supported",
+      "declareRowPolicy is Postgres-only; backend '" + backendName + "' has dialect='" +
+      found.dialect + "'. Write the policy as a hand-rolled migration for this dialect.");
+  }
+}
+
+function declareRowPolicy(opts) {
+  var spec = _validateOpts(opts);
+  var qTable  = safeSql.quoteQualified([spec.schema, spec.table], "postgres");
+  var qPolicy = safeSql.quoteIdentifier(spec.name, "postgres");
+  var qRole   = spec.role ? safeSql.quoteIdentifier(spec.role, "postgres") : null;
+
+  var description = "declareRowPolicy " + spec.schema + "." + spec.table + "." + spec.name;
+
+  async function up(xdb, ctx) {
+    if (ctx && ctx.externalDb && ctx.backendName) {
+      _ensureBackendIsPostgres(ctx.externalDb, ctx.backendName);
+    }
+
+    // Idempotent ENABLE — Postgres has no IF NOT EXISTS for this. Read
+    // the current setting from pg_class and skip the ALTER when already
+    // on, so re-running a migration set in a partially-applied state
+    // doesn't fail with a no-op error from the lock acquisition.
+    var rlsCheck = await xdb.query(
+      "SELECT relrowsecurity FROM pg_class c " +
+      "JOIN pg_namespace n ON n.oid = c.relnamespace " +
+      "WHERE n.nspname = $1 AND c.relname = $2",
+      [spec.schema, spec.table]
+    );
+    var rows = (rlsCheck && rlsCheck.rows) || [];
+    if (rows.length === 0) {
+      throw _err("declare-row-policy/table-not-found",
+        "source table '" + spec.schema + "." + spec.table +
+        "' not found (does it exist? does the migration role have visibility?)");
+    }
+    if (!rows[0].relrowsecurity) {
+      await xdb.query("ALTER TABLE " + qTable + " ENABLE ROW LEVEL SECURITY", []);
+    }
+
+    // CREATE POLICY assembled in canonical order: name → table → AS
+    // PERMISSIVE/RESTRICTIVE → FOR command → TO role → USING → WITH CHECK.
+    var sql = "CREATE POLICY " + qPolicy + " ON " + qTable;
+    sql += " AS " + (spec.permissive ? "PERMISSIVE" : "RESTRICTIVE");
+    sql += " FOR " + spec.command;
+    if (qRole) sql += " TO " + qRole;
+    sql += " USING (" + spec.using + ")";
+    if (spec.withCheck) sql += " WITH CHECK (" + spec.withCheck + ")";
+
+    await xdb.query(sql, []);
+
+    return {
+      policy:       spec.schema + "." + spec.table + "." + spec.name,
+      table:        spec.schema + "." + spec.table,
+      role:         spec.role,
+      command:      spec.command,
+      permissive:   spec.permissive,
+      hasWithCheck: !!spec.withCheck,
+    };
+  }
+
+  async function down(xdb, ctx) {
+    if (ctx && ctx.externalDb && ctx.backendName) {
+      _ensureBackendIsPostgres(ctx.externalDb, ctx.backendName);
+    }
+    await xdb.query("DROP POLICY IF EXISTS " + qPolicy + " ON " + qTable, []);
+  }
+
+  return {
+    description: description,
+    target:      "externalDb",
+    backend:     spec.backend,
+    up:          up,
+    down:        down,
+    _spec:       spec,
+  };
+}
+
+module.exports = {
+  declareRowPolicy:        declareRowPolicy,
+  DeclareRowPolicyError:   DeclareRowPolicyError,
+};

package/lib/db-role-context.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * db-role-context — shared AsyncLocalStorage registry for the request-time
+ * DB role binding.
+ *
+ * The b.middleware.dbRoleFor middleware enters a scope with { role }; the
+ * externalDb backend picker reads the same store at query time. Anything
+ * deep in the async stack — handler, db query, transaction body, audit
+ * write — sees the same role without explicit threading.
+ *
+ * Out-of-request callers (jobs, schedulers, CLIs) use externalDb.runAs to
+ * push a role into the same store for the body of their work.
+ *
+ * Public API (consumed by externalDb / middleware / permissions):
+ *   getRole()                → string | null
+ *   runWithRole(role, fn)    → fn() inside the role-bound ALS scope
+ *
+ * The role string must be a SQL-identifier-shaped value; callers are
+ * responsible for validating before pushing into the store. The store
+ * holds a frozen { role } shape so consumers can't mutate it sideways.
+ */
+var { AsyncLocalStorage } = require("node:async_hooks");
+
+var _als = new AsyncLocalStorage();
+
+function getStore() {
+  return _als.getStore() || null;
+}
+
+function getRole() {
+  var s = getStore();
+  return s && s.role ? s.role : null;
+}
+
+function runWithRole(role, fn) {
+  if (typeof fn !== "function") {
+    throw new TypeError("db-role-context.runWithRole: fn must be a function");
+  }
+  // Null / undefined role passes through as "no binding" — useful for
+  // explicitly entering a scope that resets any inherited role.
+  var store = role ? Object.freeze({ role: String(role) }) : Object.freeze({ role: null });
+  return _als.run(store, fn);
+}
+
+module.exports = {
+  getRole:      getRole,
+  runWithRole:  runWithRole,
+  // For diagnostic use; consumers should prefer getRole.
+  _als:         _als,
+};

package/lib/db.js

@@ -1173,6 +1173,11 @@ module.exports = {
   // b.externalDb.migrate. Postgres-only; fail-fast at apply time on other
   // dialects. See lib/db-declare-view.js.
   declareView:         require("./db-declare-view").declareView,
+  // declareRowPolicy — declarative Postgres ROW LEVEL SECURITY migration
+  // spec. Pairs with externalDb.transaction({ sessionGucs }) for the
+  // per-request `SET LOCAL` plumbing. Postgres-only; fail-fast on other
+  // dialects. See lib/db-declare-row-policy.js.
+  declareRowPolicy:    require("./db-declare-row-policy").declareRowPolicy,
   // Internal accessors used by audit / subject / consent modules.
   // Not part of the public contract — apps should not depend on them.
   _getSubjectTables:   function () { return subjectTables.slice(); },

package/lib/external-db.js

@@ -52,6 +52,7 @@
  */
 var retryHelper = require("./retry");
 var C = require("./constants");
+var dbRoleContext = require("./db-role-context");
 var lazyRequire = require("./lazy-require");
 var safeAsync = require("./safe-async");
 var safeSql = require("./safe-sql");
@@ -65,6 +66,10 @@ var _err = ExternalDbError.factory;
 var initialized = false;
 var backends = {};
 var defaultBackend = null;
+// Operator-declared { role: backendName } map for request-time pool pick.
+// Populated at init() from opts.dbRoleBackends. Read by _pickBackend
+// when no explicit opts.backend is supplied AND the ALS scope has a role.
+var dbRoleBackends = {};
 
 // ---- Pool ----
 //
@@ -166,6 +171,7 @@ function init(opts) {
   if (!opts || !opts.backends) throw new Error("externalDb.init({ backends }) is required");
 
   backends = {};
+  dbRoleBackends = {};
   for (var name in opts.backends) {
     var cfg = opts.backends[name];
     if (typeof cfg.connect !== "function") {
@@ -208,6 +214,39 @@ function init(opts) {
   }
 
   defaultBackend = opts.defaultBackend || Object.keys(backends)[0];
+
+  // dbRoleBackends — request-time role → backend mapping. Each role name
+  // validates as a SQL identifier at init (matches the dbRoleFor
+  // middleware's runtime check) so a typo surfaces at boot rather than
+  // as a silent default-backend fallback at the first request.
+  if (opts.dbRoleBackends !== undefined && opts.dbRoleBackends !== null) {
+    if (typeof opts.dbRoleBackends !== "object" || Array.isArray(opts.dbRoleBackends)) {
+      throw _err("INVALID_CONFIG",
+        "dbRoleBackends must be an object map of role → backendName", true);
+    }
+    for (var role in opts.dbRoleBackends) {
+      if (!Object.prototype.hasOwnProperty.call(opts.dbRoleBackends, role)) continue;
+      try {
+        safeSql.validateIdentifier(role, { allowReserved: false });
+      } catch (e) {
+        throw _err("INVALID_CONFIG",
+          "dbRoleBackends: role '" + role + "' is not a valid SQL identifier: " +
+          ((e && e.message) || String(e)), true);
+      }
+      var bn = opts.dbRoleBackends[role];
+      if (typeof bn !== "string" || bn.length === 0) {
+        throw _err("INVALID_CONFIG",
+          "dbRoleBackends['" + role + "']: backend name must be a non-empty string", true);
+      }
+      if (!Object.prototype.hasOwnProperty.call(backends, bn)) {
+        throw _err("INVALID_CONFIG",
+          "dbRoleBackends['" + role + "']: no backend named '" + bn + "' " +
+          "(declared backends: " + Object.keys(backends).join(", ") + ")", true);
+      }
+      dbRoleBackends[role] = bn;
+    }
+  }
+
   _validateResidency();
   initialized = true;
 }
@@ -232,6 +271,16 @@ function _validateResidency() {
 }
 
 // ---- Backend selection ----
+//
+// Pick precedence:
+//   1. opts.backend                       — explicit override always wins
+//   2. opts.classification                — first backend serving that class
+//   3. ALS-bound dbRole + dbRoleBackends  — request-time auto-pick
+//   4. defaultBackend                     — final fallback
+//
+// The ALS path matches the dbRoleFor middleware shape: middleware sets
+// the role; deep async reads pick up the matching backend without having
+// to thread `req` through every call site.
 
 function _pickBackend(opts) {
   opts = opts || {};
@@ -252,6 +301,10 @@ function _pickBackend(opts) {
     throw _err("NO_BACKEND_FOR_CLASSIFICATION",
       "no backend serves classification '" + classification + "'", true);
   }
+  var role = dbRoleContext.getRole();
+  if (role && Object.prototype.hasOwnProperty.call(dbRoleBackends, role)) {
+    return backends[dbRoleBackends[role]];
+  }
   return backends[defaultBackend] || null;
 }
 
@@ -320,6 +373,16 @@ async function transaction(fn, opts) {
   opts = opts || {};
   var b = _pickBackend(opts);
 
+  // sessionGucs — per-transaction `SET LOCAL "name" = value` plumbing.
+  // Each name validates as a SQL identifier (Postgres GUC names follow
+  // the same NAMEDATALEN-shaped rules; dotted GUCs like 'app.tenant_id'
+  // validate per-segment via quoteQualified). Values are emitted as SQL
+  // string literals (single-quote escaped) for strings, raw for finite
+  // numbers. SET LOCAL ties the binding to the surrounding transaction
+  // so the tenant_id used by RLS policies resets cleanly at
+  // COMMIT/ROLLBACK without caller cleanup.
+  var prebuiltGucs = _buildSessionGucsStatements(opts.sessionGucs);
+
   var t0 = Date.now();
   return await b.breaker.wrap(async function () {
     var client = await b.pool.acquire();
@@ -329,6 +392,9 @@ async function transaction(fn, opts) {
     var committed = false;
     try {
       await b.beginTx(client);
+      for (var gi = 0; gi < prebuiltGucs.length; gi++) {
+        await b.query(client, prebuiltGucs[gi], []);
+      }
       var result = await fn(txClient);
       await b.commit(client);
       committed = true;
@@ -410,6 +476,60 @@ async function shutdown() {
   initialized = false;
 }
 
+// Build the SET LOCAL statements for a transaction's sessionGucs map.
+// Identifier-validates each GUC name (per dot-segment so dotted names
+// like 'app.tenant_id' work), quotes them with the Postgres dialect,
+// and renders the value as either a SQL string literal (single-quoted,
+// embedded quotes doubled) or a numeric literal for finite numbers.
+// Bad shapes throw at the call site rather than as a confused Postgres
+// error mid-transaction.
+function _buildSessionGucsStatements(sessionGucs) {
+  if (sessionGucs === undefined || sessionGucs === null) return [];
+  if (typeof sessionGucs !== "object" || Array.isArray(sessionGucs)) {
+    throw _err("INVALID_SESSION_GUCS",
+      "sessionGucs must be an object map of name → value", true);
+  }
+  var out = [];
+  for (var name in sessionGucs) {
+    if (!Object.prototype.hasOwnProperty.call(sessionGucs, name)) continue;
+    if (typeof name !== "string" || name.length === 0) {
+      throw _err("INVALID_SESSION_GUCS",
+        "sessionGucs: GUC name must be a non-empty string", true);
+    }
+    // Validate per-segment so dotted GUCs (Postgres custom GUC class.
+    // setting form) pass. quoteQualified handles both the validation
+    // and the dot-quoted rendering.
+    var qName;
+    try {
+      qName = safeSql.quoteQualified(name, "postgres");
+    } catch (e) {
+      throw _err("INVALID_SESSION_GUCS",
+        "sessionGucs: name '" + name + "' is not a valid identifier: " +
+        ((e && e.message) || String(e)), true);
+    }
+    var value = sessionGucs[name];
+    var literal;
+    if (typeof value === "number" && isFinite(value)) {
+      literal = String(value);
+    } else if (typeof value === "boolean") {
+      // Postgres SET accepts on/off/true/false — render true/false.
+      literal = value ? "true" : "false";
+    } else if (typeof value === "string") {
+      literal = "'" + value.replace(/'/g, "''") + "'";
+    } else if (value === null || value === undefined) {
+      throw _err("INVALID_SESSION_GUCS",
+        "sessionGucs['" + name + "']: value must be a string, finite number, or boolean (got " +
+        (value === null ? "null" : "undefined") + ")", true);
+    } else {
+      throw _err("INVALID_SESSION_GUCS",
+        "sessionGucs['" + name + "']: value must be a string, finite number, or boolean (got " +
+        typeof value + ")", true);
+    }
+    out.push("SET LOCAL " + qName + " = " + literal);
+  }
+  return out;
+}
+
 // Fire-and-forget audit emission. We CANNOT await this in cluster mode:
 // audit storage routes back through external-db when cluster mode is
 // active, so awaiting would create a recursive dependency (every audit
@@ -594,6 +714,7 @@ function _resetForTest() {
   });
   backends = {};
   defaultBackend = null;
+  dbRoleBackends = {};
   initialized = false;
   audit.reset();
   db.reset();
@@ -791,6 +912,37 @@ function _adaptersConnectAs(connect, opts) {
   return _connectAs(connect, query, roleOpts);
 }
 
+// ---- runAs / currentRole — out-of-request role binding ----
+//
+// Inside an HTTP request the dbRoleFor middleware already pushes the
+// role into the shared db-role-context ALS. Background workers (jobs,
+// schedulers, CLI commands) don't run under that middleware — they wrap
+// their work in runAs(role, fn) so the same backend-pick logic applies.
+//
+//   await b.externalDb.runAs("analytics_user", async function () {
+//     return await b.externalDb.read.query("SELECT ...");   // → analytics backend
+//   });
+//
+// currentRole() returns the active role (or null) — useful for diagnostic
+// logs and observability labels.
+function runAs(role, fn) {
+  if (typeof fn !== "function") {
+    throw _err("INVALID_FN", "externalDb.runAs: fn must be a function", true);
+  }
+  if (role !== null && role !== undefined) {
+    if (typeof role !== "string" || role.length === 0) {
+      throw _err("INVALID_ROLE",
+        "externalDb.runAs: role must be a non-empty string or null", true);
+    }
+    safeSql.validateIdentifier(role, { allowReserved: false });
+  }
+  return dbRoleContext.runWithRole(role || null, fn);
+}
+
+function currentRole() {
+  return dbRoleContext.getRole();
+}
+
 module.exports = {
   init:           init,
   query:          query,
@@ -801,6 +953,8 @@ module.exports = {
   configurePool:  configurePool,
   read:           read,
   write:          write,
+  runAs:          runAs,
+  currentRole:    currentRole,
   adapters: {
     connectAs:    _adaptersConnectAs,
   },

package/lib/middleware/db-role-for.js

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * dbRoleFor middleware — binds a request-time DB role.
+ *
+ * Operators using the search_path-views compliance recipe (see
+ * b.db.declareView and the Compliance Patterns wiki page) declare two
+ * Postgres roles: app_user (full source) and analytics_user (redacted
+ * view). Each role gets its own externalDb backend — same SQL,
+ * different connection pool. dbRoleFor picks the role for the current
+ * request and pushes it into the shared db-role-context AsyncLocalStorage
+ * scope so b.externalDb.query / read / write / transaction auto-route
+ * to the matching backend without any operator threading of the role
+ * through their handler signature.
+ *
+ *   var perms = b.permissions.create({
+ *     roles: {
+ *       admin:    { extends: ["app"],   permissions: ["*:*"] },
+ *       app:      { permissions: ["sessions:*"], dbRole: "app_user" },
+ *       analyst:  { permissions: ["sessions:read"], dbRole: "analytics_user" },
+ *     },
+ *   });
+ *
+ *   router.use(b.middleware.attachUser(...));
+ *   router.use(b.middleware.dbRoleFor({
+ *     permissions: perms,                 // resolves dbRole from req.user.roles
+ *     defaultRole: "app_user",
+ *   }));
+ *
+ *   router.get("/sessions", function (req, res) {
+ *     // No `{ backend: ... }` opt — the framework picked it from req.dbRole.
+ *     b.externalDb.read.query("SELECT * FROM sessions WHERE _id = $1", [sid])
+ *       .then(...);
+ *   });
+ *
+ * Resolution order:
+ *   1. opts.resolve(req)           — operator-supplied custom resolver
+ *   2. opts.permissions.dbRoleFor  — RBAC mapping (when permissions provided)
+ *   3. opts.defaultRole            — fallback string
+ *   4. null                        — no binding (externalDb falls back to default backend)
+ *
+ * Validation at create() time — bad shape throws here, not at the first
+ * request:
+ *   - opts shape (validateOpts allow-list)
+ *   - resolve / responder must be functions if provided
+ *   - permissions must expose dbRoleFor (the b.permissions shape)
+ *   - defaultRole, when provided, must be a SQL-identifier-shaped string
+ *   - missingRoleStatus must be a 100-599 integer
+ *
+ * Runtime validation on resolver output:
+ *   - resolver returns must be string | null | undefined
+ *   - non-empty string return MUST match safeSql.validateIdentifier; a
+ *     malformed identifier from a resolver is a wiring bug (the operator
+ *     plugged in a resolver that returns garbage). Routed through
+ *     next(err) so the request surfaces a clear error instead of silently
+ *     routing to the default backend.
+ *
+ * Failure modes:
+ *   - resolver throws            → 500 propagated via next(err)
+ *   - role required but absent   → respond with missingRoleStatus (default 401)
+ *   - role identifier malformed  → respond with 500 (resolver bug — not a runtime user error)
+ *
+ * Observability event: db.role.bound { value: 1, labels: { role, source } }
+ *   source ∈ "resolver" | "permissions" | "default"
+ *
+ * Audit emission of `db.role.switched` (the cross-request transition
+ * record) lands in v0.6.7 — this middleware focuses on binding the role.
+ */
+var dbRoleContext = require("../db-role-context");
+var lazyRequire = require("../lazy-require");
+var safeSql = require("../safe-sql");
+var validateOpts = require("../validate-opts");
+var { defineClass } = require("../framework-error");
+
+var observability = lazyRequire(function () { return require("../observability"); });
+
+var DbRoleForError = defineClass("DbRoleForError", { alwaysPermanent: true });
+var _err = function (code, message) { return new DbRoleForError(code, message); };
+
+var ALLOWED_OPTS = [
+  "resolve", "permissions", "defaultRole",
+  "requireRole", "missingRoleStatus", "responder",
+];
+
+function _emitEvent(name, value, labels) {
+  try { observability().event(name, value, labels || {}); }
+  catch (_e) { /* hot-path observability sink — drop silent by design */ }
+}
+
+function _validateRoleIdentifier(role, where) {
+  try {
+    safeSql.validateIdentifier(role, { allowReserved: false });
+  } catch (e) {
+    throw _err("db-role-for/bad-role",
+      where + ": role '" + role + "' is not a valid SQL identifier: " +
+      ((e && e.message) || String(e)));
+  }
+}
+
+function _defaultResponder(req, res, status, info) {
+  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify(info));
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, ALLOWED_OPTS, "middleware.dbRoleFor");
+
+  if (opts.resolve !== undefined && typeof opts.resolve !== "function") {
+    throw _err("db-role-for/bad-opt",
+      "middleware.dbRoleFor: resolve must be a function");
+  }
+  if (opts.responder !== undefined && typeof opts.responder !== "function") {
+    throw _err("db-role-for/bad-opt",
+      "middleware.dbRoleFor: responder must be a function");
+  }
+  if (opts.permissions !== undefined && opts.permissions !== null) {
+    if (typeof opts.permissions !== "object" ||
+        typeof opts.permissions.dbRoleFor !== "function") {
+      throw _err("db-role-for/bad-opt",
+        "middleware.dbRoleFor: permissions must be a b.permissions instance " +
+        "(missing dbRoleFor method)");
+    }
+  }
+  if (opts.defaultRole !== undefined && opts.defaultRole !== null) {
+    if (typeof opts.defaultRole !== "string" || opts.defaultRole.length === 0) {
+      throw _err("db-role-for/bad-opt",
+        "middleware.dbRoleFor: defaultRole must be a non-empty string");
+    }
+    _validateRoleIdentifier(opts.defaultRole, "middleware.dbRoleFor: defaultRole");
+  }
+  if (opts.requireRole !== undefined && typeof opts.requireRole !== "boolean") {
+    throw _err("db-role-for/bad-opt",
+      "middleware.dbRoleFor: requireRole must be a boolean");
+  }
+  if (opts.missingRoleStatus !== undefined) {
+    if (typeof opts.missingRoleStatus !== "number" ||
+        !isFinite(opts.missingRoleStatus) ||
+        opts.missingRoleStatus < 100 || opts.missingRoleStatus > 599) {
+      throw _err("db-role-for/bad-opt",
+        "middleware.dbRoleFor: missingRoleStatus must be an HTTP status code (100-599)");
+    }
+  }
+
+  var resolveFn         = opts.resolve || null;
+  var perms             = opts.permissions || null;
+  var defaultRole       = opts.defaultRole || null;
+  var requireRole       = !!opts.requireRole;
+  var missingRoleStatus = opts.missingRoleStatus || 401;
+  var responder         = opts.responder || _defaultResponder;
+
+  return function dbRoleForMiddleware(req, res, next) {
+    var role = null;
+    var source = null;
+
+    if (resolveFn) {
+      var resolved;
+      try { resolved = resolveFn(req); }
+      catch (e) { return next(e); }
+      if (resolved !== undefined && resolved !== null && resolved !== "") {
+        role = resolved;
+        source = "resolver";
+      }
+    }
+
+    if (!role && perms) {
+      // permissions.dbRoleFor walks req.user.roles / req.apiKey.scopes via
+      // the configured resolver and returns the first declared dbRole.
+      var fromPerms;
+      try { fromPerms = perms.dbRoleFor(req); }
+      catch (e) { return next(e); }
+      if (fromPerms) {
+        role = fromPerms;
+        source = "permissions";
+      }
+    }
+
+    if (!role && defaultRole) {
+      role = defaultRole;
+      source = "default";
+    }
+
+    if (!role) {
+      if (requireRole) {
+        _emitEvent("db.role.missing", 1, {});
+        return responder(req, res, missingRoleStatus, {
+          error:  "missing_db_role",
+          status: missingRoleStatus,
+        });
+      }
+      // No binding — let externalDb fall back to its default backend.
+      req.dbRole = null;
+      return next();
+    }
+
+    if (typeof role !== "string") {
+      return next(_err("db-role-for/bad-resolver-return",
+        "middleware.dbRoleFor: resolver returned non-string role: " + typeof role));
+    }
+    // Validate the resolver-supplied identifier at request time — a
+    // malformed identifier is a wiring bug, not a request-shape concern.
+    // Route the throw through next(err) so an operator's errorHandler
+    // reaches it instead of the request hanging.
+    try {
+      _validateRoleIdentifier(role, "middleware.dbRoleFor: resolver/" + source);
+    } catch (e) {
+      return next(e);
+    }
+
+    req.dbRole = role;
+    _emitEvent("db.role.bound", 1, { role: role, source: source });
+    dbRoleContext.runWithRole(role, function () { next(); });
+  };
+}
+
+module.exports = {
+  create:           create,
+  DbRoleForError:   DbRoleForError,
+};

package/lib/middleware/index.js

@@ -33,6 +33,7 @@ module.exports = {
   sse:             require("./sse").create,
   requestLog:      require("./request-log").create,
   apiEncrypt:      require("./api-encrypt"),
+  dbRoleFor:       require("./db-role-for").create,
 
   // Module exports for advanced use (constants, raw factory access)
   _modules: {
@@ -52,5 +53,6 @@ module.exports = {
     sse:             require("./sse"),
     requestLog:      require("./request-log"),
     apiEncrypt:      require("./api-encrypt"),
+    dbRoleFor:       require("./db-role-for"),
   },
 };

package/lib/permissions.js

@@ -47,6 +47,7 @@
 
 var lazyRequire = require("./lazy-require");
 var requestHelpers = require("./request-helpers");
+var safeSql = require("./safe-sql");
 var validateOpts = require("./validate-opts");
 var { PermissionsError } = require("./framework-error");
 
@@ -116,7 +117,7 @@ function _validateScopePattern(scope, ctx) {
 
 function _normalizeRoleEntry(name, entry) {
   if (Array.isArray(entry)) {
-    return { extends: [], permissions: entry.slice() };
+    return { extends: [], permissions: entry.slice(), dbRole: null };
   }
   if (entry && typeof entry === "object") {
     var ext = entry.extends || [];
@@ -127,9 +128,27 @@ function _normalizeRoleEntry(name, entry) {
     if (!Array.isArray(perms)) {
       throw _err("BAD_ROLE", "role '" + name + "': permissions must be an array of scope strings");
     }
-    return { extends: ext.slice(), permissions: perms.slice() };
+    var dbRole = null;
+    if (entry.dbRole !== undefined && entry.dbRole !== null) {
+      if (typeof entry.dbRole !== "string" || entry.dbRole.length === 0) {
+        throw _err("BAD_ROLE",
+          "role '" + name + "': dbRole must be a non-empty string");
+      }
+      // dbRole feeds straight into externalDb backend pick + the
+      // dbRoleFor middleware's identifier check; validate at create()
+      // time so a typo surfaces at boot, not on the first request.
+      try {
+        safeSql.validateIdentifier(entry.dbRole, { allowReserved: false });
+      } catch (e) {
+        throw _err("BAD_ROLE",
+          "role '" + name + "': dbRole '" + entry.dbRole +
+          "' is not a valid SQL identifier: " + ((e && e.message) || String(e)));
+      }
+      dbRole = entry.dbRole;
+    }
+    return { extends: ext.slice(), permissions: perms.slice(), dbRole: dbRole };
   }
-  throw _err("BAD_ROLE", "role '" + name + "' must be an array of scopes or { extends?, permissions }");
+  throw _err("BAD_ROLE", "role '" + name + "' must be an array of scopes or { extends?, permissions, dbRole? }");
 }
 
 function _validateRoles(roles) {
@@ -385,6 +404,44 @@ function create(opts) {
     };
   }
 
+  // dbRoleFor — walk the actor's roles in order and return the first
+  // declared dbRole. Composes with b.middleware.dbRoleFor so a single
+  // RBAC table drives both authorization scopes and request-time DB
+  // role binding.
+  //
+  // The arg can be the request (default resolver pulls actor from
+  // req.user / req.apiKey) OR an actor object directly. Returns null if
+  // no actor is found OR the actor's roles don't include any with a
+  // declared dbRole.
+  //
+  // Lookup order: extends are walked depth-first so a child role that
+  // overrides dbRole takes precedence over its parent. When multiple
+  // top-level roles are listed, the first wins (operators wanting a
+  // priority order should list more-specific roles first).
+  function dbRoleFor(reqOrActor) {
+    var actor = reqOrActor;
+    // Heuristic: a request shape carries headers / url; resolve through
+    // the configured resolver. An actor shape has roles / scopes
+    // directly.
+    if (actor && (actor.headers || actor.url || actor.method)) {
+      actor = resolver(actor);
+    }
+    if (!actor || typeof actor !== "object") return null;
+    var roleNames = Array.isArray(actor.roles) ? actor.roles : null;
+    if (!roleNames || roleNames.length === 0) return null;
+    // Walk the same DFS order expand() uses so the first-seen dbRole
+    // is consistent with how scopes are inherited.
+    var visited = new Set();
+    for (var i = 0; i < roleNames.length; i++) {
+      var name = roleNames[i];
+      if (typeof name !== "string") continue;
+      if (!Object.prototype.hasOwnProperty.call(roleTable, name)) continue;
+      var found = _findDbRole(name, roleTable, visited);
+      if (found) return found;
+    }
+    return null;
+  }
+
   return {
     require:    function (scope)  { return _middleware("single", scope); },
     requireAll: function (scopes) { return _middleware("all",    scopes); },
@@ -393,11 +450,27 @@ function create(opts) {
     checkAll:   checkAll,
     checkAny:   checkAny,
     expand:     expand,
+    dbRoleFor:  dbRoleFor,
     has:        function (name) { return Object.prototype.hasOwnProperty.call(roleTable, name); },
     roles:      Object.freeze(Object.keys(roleTable)),
   };
 }
 
+function _findDbRole(roleName, table, visited) {
+  if (visited.has(roleName)) return null;
+  visited.add(roleName);
+  var spec = table[roleName];
+  if (!spec) return null;
+  // Child overrides parent — check this role's own dbRole first, then
+  // recurse into extends.
+  if (spec.dbRole) return spec.dbRole;
+  for (var i = 0; i < spec.extends.length; i++) {
+    var found = _findDbRole(spec.extends[i], table, visited);
+    if (found) return found;
+  }
+  return null;
+}
+
 // ---- Helpers ----
 
 function _labelize(requested) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",