@blamejs/core 0.6.4 → 0.6.6

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") {
@@ -174,8 +180,21 @@ function init(opts) {
     if (typeof cfg.query !== "function") {
       throw _err("INVALID_CONFIG", "backend '" + name + "' missing query() function", true);
     }
+    // dialect — informational marker so dialect-specific consumers
+    // (e.g. b.db.declareView) can fail-fast at apply time. Defaults to
+    // "postgres" because that's the dominant blamejs externalDb target;
+    // operators on SQLite/MySQL/etc. set this explicitly so downstream
+    // primitives surface NOT_SUPPORTED with a clear message instead of
+    // emitting Postgres-flavored DDL into the wrong dialect.
+    var dialect = (cfg.dialect || "postgres").toLowerCase();
+    if (["postgres", "mysql", "sqlite", "mongodb", "other"].indexOf(dialect) === -1) {
+      throw _err("INVALID_CONFIG",
+        "backend '" + name + "': dialect must be one of " +
+        "'postgres' | 'mysql' | 'sqlite' | 'mongodb' | 'other', got '" + dialect + "'", true);
+    }
     backends[name] = {
       name:            name,
+      dialect:         dialect,
       pool:            new Pool(name, cfg),
       query:           cfg.query,
       ping:            cfg.ping || null,
@@ -195,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;
 }
@@ -219,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 || {};
@@ -239,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;
 }
 
@@ -307,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();
@@ -316,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;
@@ -372,6 +451,7 @@ function listBackends() {
     var b = backends[name];
     return {
       name:            name,
+      dialect:         b.dialect,
       classifications: b.classifications.slice(),
       residencyTag:    b.residencyTag,
       breakerState:    b.breaker.getState(),
@@ -396,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
@@ -580,6 +714,7 @@ function _resetForTest() {
   });
   backends = {};
   defaultBackend = null;
+  dbRoleBackends = {};
   initialized = false;
   audit.reset();
   db.reset();
@@ -777,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,
@@ -787,9 +953,15 @@ module.exports = {
   configurePool:  configurePool,
   read:           read,
   write:          write,
+  runAs:          runAs,
+  currentRole:    currentRole,
   adapters: {
     connectAs:    _adaptersConnectAs,
   },
+  // Migration runner targeting an externalDb backend. Mirrors b.migrations
+  // (which targets local SQLite) but runs against externalDb. Tracking +
+  // lock tables live on the externalDb side. See lib/external-db-migrate.js.
+  migrate:        require("./external-db-migrate"),
   Pool:           Pool,
   _resetForTest:  _resetForTest,
 };

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.4",
+  "version": "0.6.6",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",