@blamejs/core 0.6.6 → 0.6.7

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **0.6.6** (2026-05-01) — request-time DB role binding + Postgres RLS migrations
 - **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

package/README.md

@@ -41,10 +41,10 @@ var b = require("@blamejs/core");
 
 The framework bundles the surface a typical Node app reaches for. Every primitive listed is callable today; nothing is a stub.
 
-- **Data layer** — SQLite with sealed-by-default columns (`b.db`), migrations, seeders, atomic-file writes; S3 / R2 / B2 / GCS / Azure object store with multipart upload + SSE + bucket ops (`b.storage`, `b.objectStore`); durable queue with priority + cron + flows (`b.queue`, `b.jobs`); cluster-shared cache (`b.cache`).
-- **Identity & access** — passwords (Argon2id), passkeys (WebAuthn), TOTP, JWT (PQ-default), OAuth, sessions, brute-force lockout (`b.auth.*`, `b.session`); RBAC (`b.permissions`); API keys with rotation (`b.apiKey`); break-glass column gates with second-factor + audit (`b.breakGlass`).
+- **Data layer** — SQLite with sealed-by-default columns (`b.db`), migrations, seeders, atomic-file writes; bring-your-own external Postgres / MySQL / etc. with pool tuning + role-aware connect + read-replica routing (`b.externalDb`); declarative role-narrowed views and Postgres row-level-security migrations (`b.db.declareView`, `b.db.declareRowPolicy`); S3 / R2 / B2 / GCS / Azure object store with multipart upload + SSE + bucket ops (`b.storage`, `b.objectStore`); durable queue with priority + cron + flows (`b.queue`, `b.jobs`); cluster-shared cache (`b.cache`).
+- **Identity & access** — passwords (Argon2id), passkeys (WebAuthn), TOTP, JWT (PQ-default), OAuth, sessions, brute-force lockout (`b.auth.*`, `b.session`); RBAC with optional per-role DB binding (`b.permissions`, role-spec `dbRole` field); API keys with rotation (`b.apiKey`); break-glass column gates with second-factor + audit (`b.breakGlass`).
 - **Crypto** — envelope-versioned PQC at rest (ML-KEM-1024 + P-384 hybrid, XChaCha20-Poly1305, SHAKE256), vault sealing, field-level crypto, signed webhooks (SLH-DSA-SHAKE-256f), ECIES API encryption (`b.crypto`, `b.vault`, `b.webhook`); pure-JS mTLS CA, PQC TLS gates inbound + outbound (`b.mtlsCa`, `b.pqcGate`, `b.pqcAgent`).
-- **HTTP** — router with schema-validated routes + OpenAPI publication; full middleware stack (CSRF, CORS, rate-limit, security headers, CSP nonce, body parser, compression, SSE, request log) wired by `createApp`; HTTP/1.1 + HTTP/2 outbound client with SSRF gate, redirects, multipart, interceptors, progress, encrypted cookie jar (`b.httpClient`, `b.ssrfGuard`, `b.safeUrl`).
+- **HTTP** — router with schema-validated routes + OpenAPI publication; full middleware stack (CSRF, CORS, rate-limit, security headers, CSP nonce, body parser, compression, SSE, request log, request-time DB role binding via `b.middleware.dbRoleFor`) wired by `createApp`; HTTP/1.1 + HTTP/2 outbound client with SSRF gate, redirects, multipart, interceptors, progress, encrypted cookie jar (`b.httpClient`, `b.ssrfGuard`, `b.safeUrl`).
 - **Defensive parsers** — `b.safeJson`, `b.safeBuffer`, `b.safeSql`, `b.safeSchema`, `b.parsers` (XML / TOML / YAML / .env), `b.config` (schema-validated env).
 - **Communication** — WebSockets with channel/room fan-out across cluster replicas (`b.websocket`, `b.websocketChannels`); mail with multipart + attachments + DKIM + calendar invites + bounce intake (`b.mail`, `b.mailBounce`); generic notification dispatcher with operator-supplied transports (`b.notify`).
 - **Observability** — tamper-evident audit chain with SLH-DSA-signed checkpoints, metrics, tracing (OTel pass-through when wired), PII redaction, log-stream sinks, OTLP/HTTP-JSON exporter for any OTel-compatible backend (`b.audit`, `b.metrics`, `b.tracing`, `b.redact`, `b.logStream`, `b.otelExport`).

package/lib/audit.js

@@ -203,6 +203,8 @@ var FRAMEWORK_NAMESPACES = [
   "backup",     // b.backup
   "breakglass", // b.breakGlass — column-policy / row-enforcement step-up auth (audit namespace lowercased per the validator's `namespace.verb` rule, same convention as b.apiKey → apikey.*)
   "cache",      // b.cache
+  "db",         // b.db / b.middleware.dbRoleFor / b.externalDb.runAs
+                //   (role-switching, RLS-shaped events)
   "dkim",       // b.mail.dkim (DKIM-Signature generation events)
   "mail",       // b.mail (b.mail-bounce uses "system.mail.*")
   "notify",     // b.notify

package/lib/external-db.js

@@ -58,8 +58,14 @@ var safeAsync = require("./safe-async");
 var safeSql = require("./safe-sql");
 var { ExternalDbError } = require("./framework-error");
 
-var audit = lazyRequire(function () { return require("./audit"); });
-var db    = lazyRequire(function () { return require("./db"); });
+var audit         = lazyRequire(function () { return require("./audit"); });
+var db            = lazyRequire(function () { return require("./db"); });
+var observability = lazyRequire(function () { return require("./observability"); });
+
+function _emitMetric(name, value, labels) {
+  try { observability().event(name, value, labels || {}); }
+  catch (_e) { /* hot-path observability sink — drop silent by design */ }
+}
 
 var _err = ExternalDbError.factory;
 
@@ -104,13 +110,21 @@ class Pool {
         throw e;
       }
     }
-    // At max — wait for a release
-    return new Promise((function (self) {
-      return function (resolve, reject) {
-        var entry = { resolve: resolve, reject: reject };
-        self.waiters.push(entry);
-      };
-    })(this));
+    // At max — wait for a release. The waiter's clock starts now;
+    // when release() resolves the waiter we emit the wait duration so
+    // operators can see backpressure on the pool.
+    var self = this;
+    var waitStartedAt = Date.now();
+    return new Promise(function (resolve, reject) {
+      self.waiters.push({
+        resolve: function (client) {
+          _emitMetric("externaldb.pool.acquire_wait", Date.now() - waitStartedAt,
+            { backend: self.name });
+          resolve(client);
+        },
+        reject:  reject,
+      });
+    });
   }
 
   release(client) {
@@ -318,6 +332,7 @@ async function query(sql, params, opts) {
   _requireInit();
   opts = opts || {};
   var b = _pickBackend(opts);
+  var role = dbRoleContext.getRole();
 
   var t0 = Date.now();
   try {
@@ -344,9 +359,11 @@ async function query(sql, params, opts) {
       });
     }, b.retryConfig);
 
+    var durationMs = Date.now() - t0;
     _emit("system.externaldb.query", "success", {
       backend:        b.name,
-      durationMs:     Date.now() - t0,
+      role:           role,
+      durationMs:     durationMs,
       classification: opts.classification || null,
       rowCount:       result && result.rowCount,
       // SQL is NOT logged by default — may contain sensitive literal values
@@ -355,14 +372,33 @@ async function query(sql, params, opts) {
       // field-crypto on the audit row).
       sql:            opts.includeSqlInAudit ? sql : null,
     });
+    _emitMetric("externaldb.query.success", 1,
+      { backend: b.name, role: role || "(none)" });
+    _emitMetric("externaldb.query.duration_ms", durationMs,
+      { backend: b.name, role: role || "(none)" });
     return result;
   } catch (e) {
+    var failureMs = Date.now() - t0;
     _emit("system.externaldb.query", "failure", {
       backend:        b.name,
-      durationMs:     Date.now() - t0,
+      role:           role,
+      durationMs:     failureMs,
       classification: opts.classification || null,
       errorCode:      e.code || null,
     }, (e && e.message) || String(e));
+    _emitMetric("externaldb.query.failure", 1,
+      { backend: b.name, role: role || "(none)", errorCode: e.code || "(none)" });
+    // 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
+    // operator's role-views recipe relies on this signal: a row of
+    // db.role.denied means a request-time role attempted something its
+    // grant or RLS policy forbids — the highest-signal compliance event
+    // the externalDb layer can emit.
+    if (e && e.code === "42501") {
+      _emitMetric("db.role.denied", 1,
+        { backend: b.name, role: role || "(none)" });
+    }
     throw e;
   }
 }
@@ -372,6 +408,7 @@ async function transaction(fn, opts) {
   if (typeof fn !== "function") throw _err("INVALID_FN", "transaction requires a function", true);
   opts = opts || {};
   var b = _pickBackend(opts);
+  var role = dbRoleContext.getRole();
 
   // sessionGucs — per-transaction `SET LOCAL "name" = value` plumbing.
   // Each name validates as a SQL identifier (Postgres GUC names follow
@@ -398,16 +435,30 @@ async function transaction(fn, opts) {
       var result = await fn(txClient);
       await b.commit(client);
       committed = true;
+      var durationMs = Date.now() - t0;
       _emit("system.externaldb.transaction", "success", {
-        backend: b.name, durationMs: Date.now() - t0, classification: opts.classification || null,
+        backend: b.name, role: role, durationMs: durationMs,
+        classification: opts.classification || null,
       });
+      _emitMetric("externaldb.transaction.success", 1,
+        { backend: b.name, role: role || "(none)" });
+      _emitMetric("externaldb.transaction.duration_ms", durationMs,
+        { backend: b.name, role: role || "(none)" });
       return result;
     } catch (e) {
       try { if (!committed) await b.rollback(client); } catch (_e) { /* best effort */ }
+      var failureMs = Date.now() - t0;
       _emit("system.externaldb.transaction", "failure", {
-        backend: b.name, durationMs: Date.now() - t0, classification: opts.classification || null,
+        backend: b.name, role: role, durationMs: failureMs,
+        classification: opts.classification || null,
         errorCode: e.code || null,
       }, (e && e.message) || String(e));
+      _emitMetric("externaldb.transaction.failure", 1,
+        { backend: b.name, role: role || "(none)", errorCode: e.code || "(none)" });
+      if (e && e.code === "42501") {
+        _emitMetric("db.role.denied", 1,
+          { backend: b.name, role: role || "(none)" });
+      }
       throw e;
     } finally {
       b.pool.release(client);
@@ -651,6 +702,7 @@ async function _readQuery(sql, params, opts) {
     throw _err("ALL_REPLICAS_UNHEALTHY",
       "backend '" + b.name + "': all replicas unhealthy and fallback disabled", true);
   }
+  var role = dbRoleContext.getRole();
   var t0 = Date.now();
   try {
     var client = await replica.pool.acquire();
@@ -658,12 +710,18 @@ async function _readQuery(sql, params, opts) {
       var res = await replica.query(client, sql, params || []);
       replica.pool.release(client);
       replica.consecutiveFailures = 0;
+      var durationMs = Date.now() - t0;
       _emit("system.externaldb.read", "success", {
         backend:    b.name,
+        role:       role,
         replicaIdx: replica.index,
-        durationMs: Date.now() - t0,
+        durationMs: durationMs,
         rowCount:   res && res.rowCount,
       });
+      _emitMetric("externaldb.read.success", 1,
+        { backend: b.name, role: role || "(none)", replicaIdx: replica.index });
+      _emitMetric("externaldb.read.duration_ms", durationMs,
+        { backend: b.name, role: role || "(none)", replicaIdx: replica.index });
       return res;
     } catch (e) {
       // Connection-shape errors mark unhealthy + destroy.
@@ -681,10 +739,17 @@ async function _readQuery(sql, params, opts) {
   } catch (e) {
     _emit("system.externaldb.read", "failure", {
       backend:    b.name,
+      role:       role,
       replicaIdx: replica.index,
       durationMs: Date.now() - t0,
       errorCode:  e.code || null,
     }, (e && e.message) || String(e));
+    _emitMetric("externaldb.read.failure", 1,
+      { backend: b.name, role: role || "(none)", errorCode: e.code || "(none)" });
+    if (e && e.code === "42501") {
+      _emitMetric("db.role.denied", 1,
+        { backend: b.name, role: role || "(none)" });
+    }
     // Fallback to primary on a failed replica read when allowed.
     if (b.replicaFallbackToPrimary) {
       return query(sql, params, opts);
@@ -936,6 +1001,27 @@ function runAs(role, fn) {
     }
     safeSql.validateIdentifier(role, { allowReserved: false });
   }
+  // Audit the role transition. runAs has no req, so the actor 5 W's
+  // come from whatever the caller has bound on the audit-context ALS
+  // (log.js requestId, plus any request-bound actor that was set in
+  // an outer scope). Same audit shape as the dbRoleFor middleware
+  // path — forensic walkers can reconstruct the role timeline whether
+  // the binding came from request middleware or a job runner.
+  var previousRole = dbRoleContext.getRole();
+  var newRole = role || null;
+  if (previousRole !== newRole) {
+    audit().safeEmit({
+      action:   "db.role.switched",
+      actor:    {},
+      resource: { kind: "db.role", id: newRole || "(none)" },
+      outcome:  "success",
+      metadata: {
+        previousRole: previousRole,
+        newRole:      newRole,
+        source:       "runAs",
+      },
+    });
+  }
   return dbRoleContext.runWithRole(role || null, fn);
 }
 

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

@@ -62,15 +62,23 @@
  * 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.
+ * Audit emission: db.role.switched is recorded once per request when a
+ * role binds. The audit row carries the actor 5 W's via
+ * requestHelpers.extractActorContext and metadata { previousRole,
+ * newRole, source }. Defaults align with the framework's "the
+ * authorization decision IS the audit-worthy event" stance — both
+ * auditFailures and auditSuccess default true. The audit sink can be
+ * pinned via opts.audit (any object exposing safeEmit), defaults to
+ * the framework's b.audit.
  */
 var dbRoleContext = require("../db-role-context");
 var lazyRequire = require("../lazy-require");
+var requestHelpers = require("../request-helpers");
 var safeSql = require("../safe-sql");
 var validateOpts = require("../validate-opts");
 var { defineClass } = require("../framework-error");
 
+var audit        = lazyRequire(function () { return require("../audit"); });
 var observability = lazyRequire(function () { return require("../observability"); });
 
 var DbRoleForError = defineClass("DbRoleForError", { alwaysPermanent: true });
@@ -79,6 +87,7 @@ var _err = function (code, message) { return new DbRoleForError(code, message);
 var ALLOWED_OPTS = [
   "resolve", "permissions", "defaultRole",
   "requireRole", "missingRoleStatus", "responder",
+  "audit", "auditFailures", "auditSuccess",
 ];
 
 function _emitEvent(name, value, labels) {
@@ -140,6 +149,20 @@ function create(opts) {
         "middleware.dbRoleFor: missingRoleStatus must be an HTTP status code (100-599)");
     }
   }
+  if (opts.audit !== undefined && opts.audit !== null) {
+    if (typeof opts.audit !== "object" || typeof opts.audit.safeEmit !== "function") {
+      throw _err("db-role-for/bad-opt",
+        "middleware.dbRoleFor: audit must be a b.audit-shaped object (safeEmit fn)");
+    }
+  }
+  if (opts.auditFailures !== undefined && typeof opts.auditFailures !== "boolean") {
+    throw _err("db-role-for/bad-opt",
+      "middleware.dbRoleFor: auditFailures must be a boolean");
+  }
+  if (opts.auditSuccess !== undefined && typeof opts.auditSuccess !== "boolean") {
+    throw _err("db-role-for/bad-opt",
+      "middleware.dbRoleFor: auditSuccess must be a boolean");
+  }
 
   var resolveFn         = opts.resolve || null;
   var perms             = opts.permissions || null;
@@ -147,6 +170,14 @@ function create(opts) {
   var requireRole       = !!opts.requireRole;
   var missingRoleStatus = opts.missingRoleStatus || 401;
   var responder         = opts.responder || _defaultResponder;
+  // Audit defaults match permissions: the role-binding decision IS the
+  // audit-worthy act. Operators with extreme volume opt out via
+  // auditSuccess: false; failures stay on regardless. The audit sink
+  // defaults to the framework's b.audit; operators with multiple audit
+  // chains pass their own (matches captureAudit's shape).
+  var auditSink         = opts.audit || null;
+  var auditFailures     = (opts.auditFailures === undefined) ? true : opts.auditFailures;
+  var auditSuccess      = (opts.auditSuccess  === undefined) ? true : opts.auditSuccess;
 
   return function dbRoleForMiddleware(req, res, next) {
     var role = null;
@@ -182,6 +213,15 @@ function create(opts) {
     if (!role) {
       if (requireRole) {
         _emitEvent("db.role.missing", 1, {});
+        if (auditFailures) {
+          _auditSwitch(auditSink, req, {
+            previousRole: dbRoleContext.getRole(),
+            newRole:      null,
+            source:       "middleware",
+            outcome:      "failure",
+            reason:       "no-role",
+          });
+        }
         return responder(req, res, missingRoleStatus, {
           error:  "missing_db_role",
           status: missingRoleStatus,
@@ -206,12 +246,46 @@ function create(opts) {
       return next(e);
     }
 
+    var previousRole = dbRoleContext.getRole();
     req.dbRole = role;
     _emitEvent("db.role.bound", 1, { role: role, source: source });
+    if (auditSuccess) {
+      _auditSwitch(auditSink, req, {
+        previousRole: previousRole,
+        newRole:      role,
+        source:       "middleware",
+        outcome:      "success",
+      });
+    }
     dbRoleContext.runWithRole(role, function () { next(); });
   };
 }
 
+// Emit the db.role.switched audit row. Fire-and-forget — the audit
+// handler's own try/catch keeps a momentary outage from breaking the
+// request. The actor 5 W's come from extractActorContext (req-driven);
+// metadata carries the previous + new role + binding source so a
+// forensic walker can reconstruct "which role read which row when."
+// The sink defaults to the framework's b.audit when the operator
+// didn't pass an explicit instance.
+function _auditSwitch(sink, req, info) {
+  try {
+    var emitter = sink || audit();
+    emitter.safeEmit({
+      action:   "db.role.switched",
+      actor:    requestHelpers.extractActorContext(req),
+      resource: { kind: "db.role", id: info.newRole || "(none)" },
+      outcome:  info.outcome || "success",
+      reason:   info.reason || null,
+      metadata: {
+        previousRole: info.previousRole || null,
+        newRole:      info.newRole || null,
+        source:       info.source,
+      },
+    });
+  } catch (_e) { /* audit best-effort */ }
+}
+
 module.exports = {
   create:           create,
   DbRoleForError:   DbRoleForError,

package/package.json

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