@blamejs/core 0.8.5 → 0.8.7

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.8.x
 
+- **0.8.7** (2026-05-06) — `b.auth.accessLock` — three-mode access-lock primitive for stop-the-world / read-only / role-restricted operator interventions. `"open"` is normal operation; `"read-only"` refuses non-idempotent methods (POST/PUT/PATCH/DELETE) with 503 + Retry-After while letting GET/HEAD/OPTIONS pass; `"locked"` refuses everything except an operator-supplied `passthroughPaths` allowlist (status / health / unlock endpoint). Operators flip modes during incident response, schema-migration windows, or break-glass review via `lock.set("locked", { actor, reason })`; the transition emits `auth.access_lock.mode_changed` audit + metric. `unlockRoles: ["sre", ...]` lets a privileged role bypass all three modes via `getRole(req)` so a break-glass operator can always reach the unlock endpoint to flip back. The boot-time mode emits `auth.access_lock.boot` so the audit chain captures the deploy posture.
+
+- **0.8.6** (2026-05-06) — New primitives: `b.middleware.dailyByteQuota` + `b.appShutdown` extensions. **`b.middleware.dailyByteQuota`** — per-IP rolling 24-hour byte budget (24 hourly bins, slides per-second so a peer can't reset by waiting past midnight). Memory backend single-node by default; `opts.cache` wires `b.cache` for cluster-shared accounting. Refuses with 429 + `Retry-After` when peers exceed the quota; emits `middleware.daily_byte_quota.refused` audit + `middleware.daily_byte_quota.refused` metric. Inbound + outbound bytes counted (header bytes + content-length + outbound write/end byte counts). Fail-open on cache backend errors with audited reason — a flaky cache no longer takes the framework down. **`b.appShutdown` extensions** — `onUncaught` hook fires on `uncaughtException` / `unhandledRejection`; default is graceful-shutdown with exitCode=1, operators can wire a hook for relay to PagerDuty / observability before exit. `opts.signals` now accepts a custom signal list (defaults to `["SIGTERM","SIGINT"]`); operators add `SIGUSR2` (nodemon restart), `SIGHUP` (terminal disconnect), `SIGQUIT` (`kill -3`) without subclassing. `b.appShutdown.pidLock(lockPath)` — single-instance file lock that writes `process.pid`, refuses to acquire when another live process holds the lock, reaps stale lock files (PID gone), and releases on shutdown. **`b.observability.otlpExporter`** — new `system.observability.otlp_exporter.post_failed` audit emission distinguishes timeout / abort from generic network failure (operators can route timeout-rooted exporter degradation to a different alert channel). `stats()` now reports `droppedTotal` (queue overflow + export failed) and emits a `dropped_total` metric on every call so dashboards chart the running drop count. **`b.auth.oauth.fetchUserInfo`** — refuses on OIDC IdPs unless the caller threads `ufiOpts.idTokenSub` (the verified `sub` claim from `exchangeCode`'s `id_token`); cross-checks userinfo `sub === idTokenSub` to defend against token-substitution where a hostile IdP returns a different user's profile. Non-OIDC OAuth 2.0 deployments mis-flagged as `isOidc` opt out via `{ skipSubCheck: true }` with audited reason.
+
 - **0.8.5** (2026-05-06) — Vendor-currency CI gate + `b.middleware.requireMtls` primitive. **Vendor-currency check** — `scripts/check-vendor-currency.js` + new CI job in `ci.yml` assert every npm-mapped vendored bundle in `lib/vendor/MANIFEST.json` matches the latest published version on the npm registry. Per-component check on meta-bundles (e.g. `peculiar-pki` → `@peculiar/x509` + `pkijs`). Master-branch corpus entries (`SecLists`) are checked against the GitHub Commits API for the bundled file's path on the source repo's default branch — if the upstream has commits newer than the manifest's `bundledAt` date, the gate fails. Registry errors stay advisory unless `BLAMEJS_VENDOR_CURRENCY_STRICT=1`. Operators run locally with `npm run check:vendor-currency`. **`b.middleware.requireMtls`** — new soft-enforcement middleware that rejects requests without an authenticated client certificate. Composes with `b.crypto.hashCertFingerprint` / `isCertRevoked` (added in v0.8.4) so operators pass `fingerprintAllowList: [...]` and `denyList: [...]` and the middleware does the constant-time match. `req.peerCert` + `req.peerFingerprint` are attached for downstream handlers. Audits `mtls.required.allowed` / `mtls.required.refused` with reason metadata.
 
 - **0.8.4** (2026-05-06) — Supply-chain scanner findings + outbound HTTP posture + npm-publish unblock. **Outbound network surface** — `b.observability.otlpExporter` no longer defaults to `globalThis.fetch`; the default transport is now `b.httpClient` (`node:https` through the framework's PQC-hybrid agent + cert-pinning + SSRF guard). The prior default leaked an outbound network surface that supply-chain scanners flagged because it sat outside the framework's TLS posture; operators on fetch-only edge runtimes still override via `opts.fetchImpl`. **Dev-mode child-process isolation** — `b.dev.create()` now lazy-requires `child_process` (was top-level — flagged on every install regardless of whether `b.dev` was used) and refuses to construct when `NODE_ENV=production` unless the operator passes `opts.allowProduction:true` with an audited reason. A misconfigured production deploy that accidentally wires the dev-mode restart loop now crashes loudly at boot rather than spawning shells on every save. **Outbound posture additions** — `b.httpClient.request` adds `responseMode: "always-resolve"` (every response resolves with `{statusCode, headers, body}` regardless of HTTP status) plus `onRedirect({from, to, hop, headersStripped, statusCode, method})` hook (operators can throw to abort or rewrite the redirect chain). `b.wsClient.connect` adds `urlFor(attempt)` and `tlsOptsFor(attempt)` per-dial overrides for between-reconnect URL / TLS rotation; the new URL is re-validated through `ssrfGuard` so a hostile upstream can't redirect a reconnecting client at a private address. `b.wsClient` swallows post-`close()` `ECONNRESET` / `EPIPE` so a clean shutdown doesn't surface a noisy unhandled-error event. `b.pqcAgent.create({ ecdhCurve })` accepts a caller-supplied stricter list — operators can drop a group from the framework default but cannot widen with non-PQ groups (the prior hardcoded value blocked legitimate per-deployment narrowing). **Crypto helpers** — `b.crypto.hashCertFingerprint(pem|der)` returns `{ hex, colon }` SHA3-512 digests and `b.crypto.isCertRevoked(pemOrDer, denyList)` does a constant-time match. **Scheduler surface** — `b.scheduler.register(name, intervalMs, fn)` shorthand for the every-N-ms registration shape; `b.scheduler.getStatus()` returns an aggregate health surface for probes / dashboards (started flag, isLeader, per-task list, totals). **npm-publish unblock** — `test/layer-0-primitives/sd-jwt-vc.test.js` was asserting `DEFAULT_ALG === "ES256"` after v0.8.1 flipped the default to `ML-DSA-87`; the assertion now matches the lib (and `DEFAULT_HASH_ALG` for `sha3-512`). v0.8.1 / v0.8.2 / v0.8.3 all failed the npm-publish gate on this single test; this release re-enables the publish workflow.

package/index.js

@@ -144,6 +144,7 @@ var auth = {
   stepUp:     require("./lib/auth/step-up"),
   acr:        require("./lib/auth/acr-vocabulary"),
   authTime:   require("./lib/auth/auth-time-tracker"),
+  accessLock: require("./lib/auth/access-lock"),
 };
 var template = require("./lib/template");
 var render = require("./lib/render");

package/lib/app-shutdown.js

@@ -239,21 +239,65 @@ function create(opts) {
     };
   }
 
+  // Operator-supplied uncaught-exception / unhandled-rejection hook.
+  // Default behaviour mirrors Node's: log + initiate graceful shutdown.
+  // Operators wire a custom hook to relay to PagerDuty / observability /
+  // crash-reporters before the process exits. A sync-throw in the hook
+  // is caught and logged but does NOT prevent the shutdown.
+  var onUncaught = typeof opts.onUncaught === "function" ? opts.onUncaught : null;
+  var uncaughtHandler = null;
+  var unhandledRejHandler = null;
+
+  // Operator-supplied set of signals that initiate shutdown. Defaults
+  // to ["SIGTERM", "SIGINT"]. SIGUSR2 (nodemon's restart signal),
+  // SIGHUP (terminal disconnect), SIGQUIT (graceful from kill -3) are
+  // common operator requests. Each signal still routes through the
+  // same _signalCallback so the shutdown semantics are identical.
+  var operatorSignals = Array.isArray(opts.signals) && opts.signals.length > 0
+    ? opts.signals.slice() : ["SIGTERM", "SIGINT"];
+
+  function _installUncaught() {
+    if (uncaughtHandler || unhandledRejHandler) return;
+    uncaughtHandler = function (err, origin) {
+      log.error("uncaught " + (origin || "exception") + ": " + ((err && err.message) || String(err)));
+      if (onUncaught) {
+        try { onUncaught(err, origin); }
+        catch (e) { log.error("onUncaught hook threw: " + ((e && e.message) || String(e))); }
+      }
+      shutdown().finally(function () { process.exitCode = process.exitCode || 1; });
+    };
+    unhandledRejHandler = function (reason) {
+      uncaughtHandler(reason instanceof Error ? reason : new Error(String(reason)), "unhandledRejection");
+    };
+    process.on("uncaughtException", uncaughtHandler);
+    process.on("unhandledRejection", unhandledRejHandler);
+  }
+  function _uninstallUncaught() {
+    if (uncaughtHandler) { process.removeListener("uncaughtException", uncaughtHandler); uncaughtHandler = null; }
+    if (unhandledRejHandler) { process.removeListener("unhandledRejection", unhandledRejHandler); unhandledRejHandler = null; }
+  }
+
   function installSignals() {
     if (signalsInstalled) return;
     signalsInstalled = true;
-    signalHandlers.SIGTERM = _signalCallback("SIGTERM");
-    signalHandlers.SIGINT  = _signalCallback("SIGINT");
-    process.on("SIGTERM", signalHandlers.SIGTERM);
-    process.on("SIGINT",  signalHandlers.SIGINT);
+    for (var si = 0; si < operatorSignals.length; si++) {
+      var sig = operatorSignals[si];
+      if (typeof sig !== "string" || sig.length === 0) continue;
+      signalHandlers[sig] = _signalCallback(sig);
+      process.on(sig, signalHandlers[sig]);
+    }
+    if (onUncaught || opts.installUncaught === true) _installUncaught();
   }
 
   function uninstallSignals() {
     if (!signalsInstalled) return;
-    process.removeListener("SIGTERM", signalHandlers.SIGTERM);
-    process.removeListener("SIGINT",  signalHandlers.SIGINT);
+    var keys = Object.keys(signalHandlers);
+    for (var ki = 0; ki < keys.length; ki++) {
+      process.removeListener(keys[ki], signalHandlers[keys[ki]]);
+    }
     signalsInstalled = false;
     signalHandlers = {};
+    _uninstallUncaught();
   }
 
   if (installSignalHandlers) installSignals();
@@ -377,9 +421,101 @@ function standardPhases(components) {
   return phases;
 }
 
+// pidLock — single-instance file lock for processes that must run
+// exactly once on a host. Writes process.pid to lockPath atomically
+// (open+lock+write) and refuses to acquire if another live process
+// already holds it. Stale lock files (PID gone or different exe) are
+// reaped automatically. The lock is released on shutdown via an
+// addPhase, so operators wire it like:
+//
+//   var pidLock = b.appShutdown.pidLock("/var/run/blamejs.pid");
+//   pidLock.acquire();                       // throws if locked elsewhere
+//   appShutdownInstance.addPhase({ name: "pidLock", run: pidLock.release });
+//
+// On Windows the underlying flock() call is unavailable; the pidLock
+// falls back to "open with exclusive create" semantics (O_EXCL via
+// fs.openSync) which gives the same single-instance guarantee but
+// without the cross-process advisory lock — the lock file presence
+// IS the lock.
+var nodeFs   = require("fs");
+var nodePath = require("path");
+
+function pidLock(lockPath) {
+  if (typeof lockPath !== "string" || lockPath.length === 0) {
+    throw new AppShutdownError("app-shutdown/bad-pidlock-path",
+      "pidLock(lockPath): lockPath must be a non-empty string (absolute path recommended)");
+  }
+  var fd = null;
+  var ownsLock = false;
+
+  function _isLivePid(pid) {
+    if (!pid || pid <= 0) return false;
+    try { process.kill(pid, 0); return true; }                                            // signal 0 = existence-check
+    catch (e) { return e.code === "EPERM"; }                                              // EPERM means process exists, just no rights
+  }
+
+  function _readExisting() {
+    try {
+      var raw = nodeFs.readFileSync(lockPath, "utf8");
+      var pid = parseInt(String(raw).trim(), 10);
+      return isFinite(pid) && pid > 0 ? pid : null;
+    } catch (_e) { return null; }
+  }
+
+  function acquire() {
+    if (ownsLock) return;
+    nodeFs.mkdirSync(nodePath.dirname(lockPath), { recursive: true });
+    var existing = _readExisting();
+    if (existing && _isLivePid(existing) && existing !== process.pid) {
+      throw new AppShutdownError("app-shutdown/pidlock-held",
+        "pidLock: '" + lockPath + "' already held by live PID " + existing);
+    }
+    if (existing) {
+      // Stale lock — owner is dead. Reap.
+      try { nodeFs.unlinkSync(lockPath); } catch (_e) { /* race: someone else reaped it */ }
+    }
+    try {
+      fd = nodeFs.openSync(lockPath, nodeFs.constants.O_WRONLY | nodeFs.constants.O_CREAT | nodeFs.constants.O_EXCL, 0o600);
+    } catch (e) {
+      if (e.code === "EEXIST") {
+        // Race: another process took the lock between our reap and create.
+        var winner = _readExisting();
+        throw new AppShutdownError("app-shutdown/pidlock-held",
+          "pidLock: '" + lockPath + "' acquired by PID " + (winner || "<unknown>") + " between read and write");
+      }
+      throw new AppShutdownError("app-shutdown/pidlock-open-failed",
+        "pidLock: failed to open '" + lockPath + "': " + e.message);
+    }
+    nodeFs.writeSync(fd, String(process.pid) + "\n");
+    nodeFs.fsyncSync(fd);
+    ownsLock = true;
+  }
+
+  function release() {
+    if (!ownsLock) return;
+    try { nodeFs.closeSync(fd); } catch (_e) { /* best-effort close */ }
+    fd = null;
+    try {
+      var current = _readExisting();
+      if (current === process.pid) nodeFs.unlinkSync(lockPath);
+    } catch (_e) { /* lock already gone — fine */ }
+    ownsLock = false;
+  }
+
+  function held() { return ownsLock; }
+
+  return {
+    acquire: acquire,
+    release: release,
+    held:    held,
+    path:    lockPath,
+  };
+}
+
 module.exports = {
   create:            create,
   standardPhases:    standardPhases,
+  pidLock:           pidLock,
   AppShutdownError:  AppShutdownError,
   DEFAULT_GRACE_MS:  DEFAULT_GRACE_MS,
 };

package/lib/auth/access-lock.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * b.auth.accessLock — three-mode access-lock primitive for stop-the-
+ * world / read-only / role-restricted operator interventions.
+ *
+ * Operators flip the framework's serving posture between modes during
+ * incident response, schema migration windows, security investigations,
+ * and break-glass review:
+ *
+ *   "open"      — normal operation; every request reaches its handler
+ *   "read-only" — refuses non-idempotent methods (POST/PUT/PATCH/DELETE)
+ *                 with 503; GET/HEAD/OPTIONS pass
+ *   "locked"    — refuses every request with 503 except a small set of
+ *                 operator-specified pass-through paths (status, health,
+ *                 break-glass-unlock); useful during schema migrations or
+ *                 a hard maintenance window
+ *
+ * Mode flips audit + emit a metric so dashboards see the transition.
+ * The operator-supplied unlockRoles allows a privileged role
+ * (configured via b.permissions) to bypass all three modes — the
+ * break-glass operator can always reach the unlock endpoint to flip
+ * back to "open". Without unlockRoles, "locked" is genuinely closed
+ * and the operator has to redeploy with an opts.startMode override
+ * to recover.
+ *
+ *   var lock = b.auth.accessLock.create({
+ *     startMode:    "open",
+ *     unlockRoles:  ["sre", "security-incident-response"],
+ *     passthroughPaths: ["/healthz", "/readyz", "/admin/access-lock"],
+ *     audit:        b.audit,
+ *     getRole:      function (req) { return req.user && req.user.role; },
+ *   });
+ *
+ *   router.use(lock.middleware());
+ *   router.post("/admin/access-lock/:mode", function (req, res) {
+ *     await lock.set(req.params.mode, { actor: req.user.id, reason: req.body.reason });
+ *     res.json({ mode: lock.mode() });
+ *   });
+ */
+
+var defineClass = require("../framework-error").defineClass;
+var lazyRequire = require("../lazy-require");
+var validateOpts = require("../validate-opts");
+
+var audit = lazyRequire(function () { return require("../audit"); });
+var observability = lazyRequire(function () { return require("../observability"); });
+
+var AccessLockError = defineClass("AccessLockError", { alwaysPermanent: true });
+
+var VALID_MODES = Object.freeze({ open: 1, "read-only": 1, locked: 1 });
+var SAFE_METHODS = Object.freeze({ GET: 1, HEAD: 1, OPTIONS: 1 });
+
+function _normalizeMode(mode) {
+  if (typeof mode !== "string") return null;
+  var m = mode.toLowerCase();
+  return VALID_MODES[m] ? m : null;
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "startMode", "unlockRoles", "passthroughPaths",
+    "audit", "getRole", "errorMessage",
+  ], "auth.accessLock");
+
+  var startMode = _normalizeMode(opts.startMode || "open");
+  if (!startMode) {
+    throw new AccessLockError("auth-access-lock/bad-mode",
+      "auth.accessLock: opts.startMode must be one of " + Object.keys(VALID_MODES).join(", "));
+  }
+  var unlockRoles = Array.isArray(opts.unlockRoles) ? opts.unlockRoles.slice() : [];
+  for (var ri = 0; ri < unlockRoles.length; ri++) {
+    if (typeof unlockRoles[ri] !== "string" || unlockRoles[ri].length === 0) {
+      throw new AccessLockError("auth-access-lock/bad-role",
+        "auth.accessLock: unlockRoles[" + ri + "] must be a non-empty string");
+    }
+  }
+  var passthroughPaths = Array.isArray(opts.passthroughPaths)
+    ? opts.passthroughPaths.slice() : [];
+  var auditOn = opts.audit !== false;
+  var getRole = typeof opts.getRole === "function" ? opts.getRole : null;
+  var errorMessage = typeof opts.errorMessage === "string" && opts.errorMessage.length > 0
+    ? opts.errorMessage : "service in restricted access mode";
+
+  var currentMode = startMode;
+  var modeSetAt   = Date.now();
+  var modeSetBy   = "boot";
+  var modeReason  = "initial mode at boot";
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   "auth.access_lock." + action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent — audit is best-effort */ }
+  }
+  function _emitMetric(verb, n, labels) {
+    try { observability().safeEvent("auth.access_lock." + verb, n || 1, labels || {}); }
+    catch (_e) { /* drop-silent */ }
+  }
+
+  function _isPassthrough(req) {
+    if (passthroughPaths.length === 0) return false;
+    var p = req.url || "";
+    var qpos = p.indexOf("?");
+    if (qpos !== -1) p = p.slice(0, qpos);
+    for (var i = 0; i < passthroughPaths.length; i++) {
+      var entry = passthroughPaths[i];
+      if (typeof entry === "string" && (p === entry || p.indexOf(entry + "/") === 0)) return true;
+      if (entry instanceof RegExp && entry.test(p)) return true;
+    }
+    return false;
+  }
+
+  function _hasUnlockRole(req) {
+    if (!getRole || unlockRoles.length === 0) return false;
+    var role;
+    try { role = getRole(req); }
+    catch (_e) { return false; }
+    if (!role) return false;
+    if (typeof role === "string") return unlockRoles.indexOf(role) !== -1;
+    if (Array.isArray(role)) {
+      for (var i = 0; i < role.length; i++) {
+        if (unlockRoles.indexOf(role[i]) !== -1) return true;
+      }
+    }
+    return false;
+  }
+
+  function set(mode, info) {
+    var next = _normalizeMode(mode);
+    if (!next) {
+      throw new AccessLockError("auth-access-lock/bad-mode",
+        "auth.accessLock.set: mode must be one of " + Object.keys(VALID_MODES).join(", "));
+    }
+    if (next === currentMode) return { mode: currentMode, changed: false };
+    var prev = currentMode;
+    info = info || {};
+    currentMode = next;
+    modeSetAt = Date.now();
+    modeSetBy = typeof info.actor === "string" ? info.actor : "unspecified";
+    modeReason = typeof info.reason === "string" ? info.reason : "";
+    _emitAudit("mode_changed", "success", {
+      from:   prev,
+      to:     next,
+      actor:  modeSetBy,
+      reason: modeReason,
+    });
+    _emitMetric("mode_changed", 1, { from: prev, to: next });
+    return { mode: currentMode, changed: true, from: prev };
+  }
+
+  function mode() { return currentMode; }
+  function status() {
+    return {
+      mode:      currentMode,
+      since:     modeSetAt,
+      setBy:     modeSetBy,
+      reason:    modeReason,
+      passthroughPaths: passthroughPaths.slice(),
+      unlockRoles:      unlockRoles.slice(),
+    };
+  }
+
+  function _refuse(res, reason) {
+    if (!res.writableEnded && typeof res.writeHead === "function") {
+      res.writeHead(503, {
+        "Content-Type":  "application/json; charset=utf-8",
+        "Retry-After":   "60",
+        "Cache-Control": "no-store",
+      });
+      res.end(JSON.stringify({ error: errorMessage, mode: currentMode, reason: reason }));
+    }
+  }
+
+  function middleware() {
+    return function accessLockMiddleware(req, res, next) {
+      // open — fast path, no checks.
+      if (currentMode === "open") return next();
+      // passthrough paths bypass all modes (status / health / unlock endpoint).
+      if (_isPassthrough(req)) return next();
+      // unlockRoles bypass all modes.
+      if (_hasUnlockRole(req)) return next();
+      if (currentMode === "read-only") {
+        var method = (req.method || "GET").toUpperCase();
+        if (SAFE_METHODS[method]) return next();
+        _emitAudit("refused", "denied", { mode: currentMode, method: method, path: req.url });
+        _emitMetric("refused", 1, { mode: currentMode, reason: "non-safe-method" });
+        return _refuse(res, "non-safe-method-in-read-only");
+      }
+      // locked — refuse everything that wasn't passthrough / unlockRole.
+      _emitAudit("refused", "denied", { mode: currentMode, method: req.method, path: req.url });
+      _emitMetric("refused", 1, { mode: currentMode, reason: "locked" });
+      return _refuse(res, "locked");
+    };
+  }
+
+  // Initial-mode audit fires once at create-time so operators see the
+  // boot-time posture in the audit chain (confirms the deploy started
+  // in the expected mode).
+  _emitAudit("boot", "success", { mode: currentMode });
+  _emitMetric("boot", 1, { mode: currentMode });
+
+  return {
+    middleware:       middleware,
+    set:              set,
+    mode:             mode,
+    status:           status,
+    VALID_MODES:      Object.keys(VALID_MODES),
+  };
+}
+
+module.exports = {
+  create:          create,
+  AccessLockError: AccessLockError,
+  VALID_MODES:     Object.keys(VALID_MODES),
+};

package/lib/auth/oauth.js

@@ -526,19 +526,45 @@ function create(opts) {
     return await _normalizeTokens(tokens, { skipNonceCheck: true });
   }
 
-  async function fetchUserInfo(accessToken) {
+  // OIDC requires fetchUserInfo to be called AFTER the id_token has
+  // been verified and its sub claim is known — otherwise the
+  // userinfo response can't be cross-checked against the id_token's
+  // sub, and a hostile IdP could swap the userinfo for a different
+  // user. RFC 7662 §3 doesn't mandate the cross-check but every OIDC
+  // conformance suite requires it. We refuse to call userinfo when
+  // isOidc=true unless the caller threaded the verified idTokenSub
+  // (or explicitly opted out via skipSubCheck for a non-OIDC OAuth
+  // 2.0 server presented as isOidc=false).
+  async function fetchUserInfo(accessToken, ufiOpts) {
+    ufiOpts = ufiOpts || {};
     if (!accessToken) {
       throw new OAuthError("auth-oauth/no-access-token",
         "fetchUserInfo: access token is required");
     }
+    if (isOidc && ufiOpts.idTokenSub === undefined && ufiOpts.skipSubCheck !== true) {
+      throw new OAuthError("auth-oauth/userinfo-no-id-token-sub",
+        "fetchUserInfo: OIDC providers require ufiOpts.idTokenSub " +
+        "(the verified sub claim from the id_token returned by " +
+        "exchangeCode) so the userinfo response can be cross-checked. " +
+        "Pass { idTokenSub: tokens.idToken.payload.sub } or, for non-" +
+        "OIDC OAuth 2.0 deployments mis-flagged as isOidc, opt out " +
+        "explicitly with { skipSubCheck: true } and an audited reason.");
+    }
     var endpoint = await _resolveEndpoint("userinfoEndpoint");
-    return await _fetchJson(endpoint, {
+    var profile = await _fetchJson(endpoint, {
       headers: {
         "Authorization": "Bearer " + accessToken,
         "Accept":        "application/json",
         "User-Agent":    "blamejs",
       },
     });
+    if (isOidc && ufiOpts.idTokenSub !== undefined && profile && profile.sub !== ufiOpts.idTokenSub) {
+      throw new OAuthError("auth-oauth/userinfo-sub-mismatch",
+        "fetchUserInfo: userinfo.sub (" + profile.sub + ") does not match " +
+        "the id_token sub (" + ufiOpts.idTokenSub + ") — possible token " +
+        "substitution attack");
+    }
+    return profile;
   }
 
   async function revokeToken(token, ropts) {

package/lib/middleware/daily-byte-quota.js

@@ -0,0 +1,275 @@
+"use strict";
+/**
+ * dailyByteQuota middleware — per-IP rolling 24-hour byte budget.
+ *
+ * Tracks request + response bytes per peer IP across a rolling 24-hour
+ * window. When a peer exceeds the operator-configured quota, further
+ * requests are rejected with 429 + Retry-After. The window slides per-
+ * second so a peer that hammers the framework for 23 hours and 59
+ * minutes can't reset by waiting an instant past midnight.
+ *
+ *   var quota = b.middleware.dailyByteQuota({
+ *     bytesPerDay:    b.constants.BYTES.gib(2),  // 2 GiB / IP / day
+ *     getKey:         function (req) {
+ *       // default: req.ip — operator overrides for tenant-id / api-key
+ *       return req.ip;
+ *     },
+ *     cache:          null,                       // single-node memory by default
+ *     audit:          b.audit,
+ *     onExceeded:     function (req, res, info) {
+ *       res.setHeader("Retry-After", info.retryAfterSec);
+ *       res.statusCode = 429;
+ *       res.end(JSON.stringify({ error: "quota-exceeded", info: info }));
+ *     },
+ *   });
+ *   router.use(quota);
+ *
+ * The middleware fires twice per request:
+ *   - On entry: peek the running counter, refuse if already past quota
+ *   - On res.end / res.write: account both directions of byte transfer
+ *
+ * Single-node memory backend uses a Map<ip, { bins: Uint32Array(24),
+ * windowStartHour: number }>. Each bin holds bytes for one rolling hour;
+ * sweeping happens on every account() call so cold storage doesn't grow
+ * unbounded. Cluster-aware operators wire opts.cache (b.cache instance)
+ * and the same pattern runs in the shared backend.
+ *
+ * Failure modes:
+ *   - cache backend unreachable → fail-open (count drops, request
+ *     proceeds), audit emitted to operator alerting; the alternative
+ *     fail-closed would let a flaky cache take down the framework
+ *   - peer key resolution returns null → request bypasses the quota
+ *     (operator's getKey decided this IP is out-of-scope)
+ */
+
+var C = require("../constants");
+var defineClass = require("../framework-error").defineClass;
+var lazyRequire = require("../lazy-require");
+var validateOpts = require("../validate-opts");
+
+var audit = lazyRequire(function () { return require("../audit"); });
+var observability = lazyRequire(function () { return require("../observability"); });
+var requestHelpers = lazyRequire(function () { return require("../request-helpers"); });
+
+var DailyByteQuotaError = defineClass("DailyByteQuotaError", { alwaysPermanent: true });
+
+var BINS_PER_DAY = 24;                                                                  // allow:raw-byte-literal — 24 hours in a day
+var BIN_MS = C.TIME.hours(1);
+
+// Default getKey — req.ip OR the trusted-proxy-resolved peer address
+// when the operator wired b.middleware.requestId or similar earlier in
+// the chain. We don't try to be clever here: req.ip is the canonical
+// shape every other middleware reads.
+function _defaultGetKey(req) {
+  return requestHelpers().clientIp(req, { trustProxy: false });
+}
+
+function _hourBin(nowMs) { return Math.floor(nowMs / BIN_MS); }
+function _newEntry() { return { bins: new Array(BINS_PER_DAY).fill(0), startHour: 0 }; }
+
+// Shared sliding-window helper — both backends call this so the
+// per-bin shift / zero / total math lives in one place. Returns the
+// (possibly mutated) entry; caller persists if the entry is shared
+// state (cache backend writes back).
+function _slideAndSum(entry, nowHour) {
+  if (entry.startHour === 0) entry.startHour = nowHour - (BINS_PER_DAY - 1);
+  var advance = nowHour - (entry.startHour + (BINS_PER_DAY - 1));
+  var moved = false;
+  if (advance > 0) {
+    moved = true;
+    if (advance >= BINS_PER_DAY) {
+      for (var i = 0; i < BINS_PER_DAY; i++) entry.bins[i] = 0;
+    } else {
+      for (var j = 0; j < BINS_PER_DAY - advance; j++) entry.bins[j] = entry.bins[j + advance];
+      for (var k = BINS_PER_DAY - advance; k < BINS_PER_DAY; k++) entry.bins[k] = 0;
+    }
+    entry.startHour = nowHour - (BINS_PER_DAY - 1);
+  }
+  var total = 0;
+  for (var t = 0; t < BINS_PER_DAY; t++) total += entry.bins[t];
+  return { entry: entry, total: total, moved: moved };
+}
+
+function _memoryBackend() {
+  var store = new Map();
+  function _get(key) {
+    var entry = store.get(key);
+    if (!entry) { entry = _newEntry(); store.set(key, entry); }
+    return entry;
+  }
+  return {
+    async total(key, nowMs) {
+      return _slideAndSum(_get(key), _hourBin(nowMs)).total;
+    },
+    async account(key, bytes, nowMs) {
+      var slid = _slideAndSum(_get(key), _hourBin(nowMs));
+      slid.entry.bins[BINS_PER_DAY - 1] += bytes;
+    },
+    _resetForTest: function () { store.clear(); },
+  };
+}
+
+function _cacheBackend(cache) {
+  function _key(k) { return "dailyByteQuota:" + k; }
+  async function _read(key) {
+    var raw = await cache.get(_key(key));
+    return raw && typeof raw === "object" && Array.isArray(raw.bins) ? raw : _newEntry();
+  }
+  return {
+    async total(key, nowMs) {
+      var entry = await _read(key);
+      var slid = _slideAndSum(entry, _hourBin(nowMs));
+      if (slid.moved) await cache.set(_key(key), slid.entry, { ttlMs: BIN_MS * BINS_PER_DAY });
+      return slid.total;
+    },
+    async account(key, bytes, nowMs) {
+      var entry = await _read(key);
+      var slid = _slideAndSum(entry, _hourBin(nowMs));
+      slid.entry.bins[BINS_PER_DAY - 1] += bytes;
+      await cache.set(_key(key), slid.entry, { ttlMs: BIN_MS * BINS_PER_DAY });
+    },
+  };
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "bytesPerDay", "cache", "getKey", "audit",
+    "onExceeded", "skipPaths", "now",
+  ], "middleware.dailyByteQuota");
+
+  if (typeof opts.bytesPerDay !== "number" || !isFinite(opts.bytesPerDay) || opts.bytesPerDay <= 0) {
+    throw new DailyByteQuotaError("daily-byte-quota/bad-quota",
+      "middleware.dailyByteQuota: opts.bytesPerDay must be a positive finite number; " +
+      "use b.constants.BYTES.gib(N) / mib(N) for readable values");
+  }
+  var bytesPerDay = opts.bytesPerDay;
+  var getKey = typeof opts.getKey === "function" ? opts.getKey : _defaultGetKey;
+  var auditOn = opts.audit !== false;
+  var onExceeded = typeof opts.onExceeded === "function" ? opts.onExceeded : null;
+  var skipPaths = Array.isArray(opts.skipPaths) ? opts.skipPaths.slice() : [];
+  var now = typeof opts.now === "function" ? opts.now : function () { return Date.now(); };
+  var backend = opts.cache && typeof opts.cache.get === "function"
+    ? _cacheBackend(opts.cache)
+    : _memoryBackend();
+
+  function _shouldSkip(req) {
+    if (skipPaths.length === 0) return false;
+    var p = req.url || req.originalUrl || "";
+    var qpos = p.indexOf("?");
+    if (qpos !== -1) p = p.slice(0, qpos);
+    for (var i = 0; i < skipPaths.length; i++) {
+      if (typeof skipPaths[i] === "string" && p === skipPaths[i]) return true;
+      if (skipPaths[i] instanceof RegExp && skipPaths[i].test(p)) return true;
+    }
+    return false;
+  }
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   "middleware.daily_byte_quota." + action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent — audit is best-effort */ }
+  }
+
+  function _emitMetric(verb, n, labels) {
+    try { observability().safeEvent("middleware.daily_byte_quota." + verb, n || 1, labels || {}); }
+    catch (_e) { /* drop-silent */ }
+  }
+
+  return async function dailyByteQuotaMiddleware(req, res, next) {
+    if (_shouldSkip(req)) return next();
+    var key;
+    try { key = getKey(req); }
+    catch (e) {
+      _emitAudit("get_key_failed", "failure", { error: (e && e.message) || String(e) });
+      return next();                                                                     // fail-open on operator-supplied key resolution
+    }
+    if (!key) return next();
+
+    var nowMs = now();
+    var total;
+    try { total = await backend.total(key, nowMs); }
+    catch (e) {
+      _emitAudit("backend_error", "failure", { phase: "total", error: (e && e.message) || String(e) });
+      return next();                                                                     // fail-open on cache miss
+    }
+    if (total >= bytesPerDay) {
+      _emitMetric("refused", 1, { reason: "quota-exceeded" });
+      _emitAudit("refused", "denied", { key: key, total: total, quota: bytesPerDay });
+      var info = {
+        quota:           bytesPerDay,
+        total:           total,
+        retryAfterSec:   Math.max(C.TIME.seconds(1) / C.TIME.seconds(1) | 0, Math.ceil(BIN_MS / C.TIME.seconds(1))),
+      };
+      if (onExceeded) {
+        try { return onExceeded(req, res, info); }
+        catch (e) { _emitAudit("on_exceeded_threw", "failure", { error: (e && e.message) || String(e) }); }
+      }
+      if (!res.writableEnded) {
+        res.writeHead(429, {
+          "Content-Type":  "application/json; charset=utf-8",
+          "Retry-After":   String(info.retryAfterSec),
+          "Cache-Control": "no-store",
+        });
+        res.end(JSON.stringify({ error: "quota-exceeded", quota: bytesPerDay, total: total }));
+      }
+      return;
+    }
+
+    // Account both inbound + outbound bytes. Inbound is roughly the
+    // header bytes (we don't proxy the body buffer to count). Outbound
+    // is observed via writableLength as res.write / res.end fire.
+    var inboundBytes = 0;
+    if (req.headers && typeof req.headers === "object") {
+      // Approximate: each header line is "Name: Value\r\n". Sum the
+      // string lengths; the actual byte count differs only on multi-
+      // byte UTF-8, which is uncommon in standard headers.
+      var keys = Object.keys(req.headers);
+      for (var hi = 0; hi < keys.length; hi++) {
+        var v = req.headers[keys[hi]];
+        inboundBytes += keys[hi].length + 2 + (typeof v === "string" ? v.length : 0) + 2;        // allow:raw-byte-literal — ": " + "\r\n" overhead
+      }
+    }
+    if (req.headers && req.headers["content-length"]) {
+      var clen = parseInt(req.headers["content-length"], 10);
+      if (isFinite(clen) && clen > 0) inboundBytes += clen;
+    }
+
+    // Patch res.write / res.end to account outbound bytes.
+    var outboundBytes = 0;
+    var origWrite = res.write.bind(res);
+    var origEnd = res.end.bind(res);
+    res.write = function (chunk, encoding, cb) {
+      if (chunk) {
+        outboundBytes += Buffer.isBuffer(chunk) ? chunk.length :
+          Buffer.byteLength(chunk, typeof encoding === "string" ? encoding : "utf8");
+      }
+      return origWrite(chunk, encoding, cb);
+    };
+    res.end = function (chunk, encoding, cb) {
+      if (chunk) {
+        outboundBytes += Buffer.isBuffer(chunk) ? chunk.length :
+          Buffer.byteLength(chunk, typeof encoding === "string" ? encoding : "utf8");
+      }
+      // Account on response end so a slow long-poll doesn't block the
+      // accounting until the client drops.
+      backend.account(key, inboundBytes + outboundBytes, now())
+        .catch(function (e) { _emitAudit("backend_error", "failure", { phase: "account", error: (e && e.message) || String(e) }); });
+      return origEnd(chunk, encoding, cb);
+    };
+
+    return next();
+  };
+}
+
+module.exports = {
+  create:                 create,
+  DailyByteQuotaError:    DailyByteQuotaError,
+  _memoryBackend:         _memoryBackend,                                                // exported for tests
+  BINS_PER_DAY:           BINS_PER_DAY,
+};

package/lib/middleware/index.js

@@ -29,6 +29,7 @@ var botGuard = require("./bot-guard");
 var compression = require("./compression");
 var cookies = require("./cookies");
 var cors = require("./cors");
+var dailyByteQuota = require("./daily-byte-quota");
 var cspNonce = require("./csp-nonce");
 var csrfProtect = require("./csrf-protect");
 var dbRoleFor = require("./db-role-for");
@@ -64,6 +65,7 @@ module.exports = {
   errorHandler:     errorHandler.create,
   botGuard:         botGuard.create,
   cors:             cors.create,
+  dailyByteQuota:   dailyByteQuota.create,
   rateLimit:        rateLimit.create,
   attachUser:       attachUser.create,
   bearerAuth:       bearerAuth.create,
@@ -108,6 +110,7 @@ module.exports = {
     errorHandler:     errorHandler,
     botGuard:         botGuard,
     cors:             cors,
+    dailyByteQuota:   dailyByteQuota,
     rateLimit:        rateLimit,
     attachUser:       attachUser,
     bearerAuth:       bearerAuth,

package/lib/observability-otlp-exporter.js

@@ -41,6 +41,7 @@ var { defineClass } = require("./framework-error");
 var OtlpExporterError = defineClass("OtlpExporterError", { alwaysPermanent: true });
 
 var observability = lazyRequire(function () { return require("./observability"); });
+var audit         = lazyRequire(function () { return require("./audit"); });
 var httpClient    = lazyRequire(function () { return require("./http-client"); });
 
 // Default OTLP transport — uses the framework's own b.httpClient
@@ -251,10 +252,21 @@ function create(opts) {
   var inFlight = false;
   var stopping = false;
 
+  var auditOn = opts.audit !== false;
   function _emitMetric(verb, n, labels) {
     try { observability().safeEvent("otlp.exporter." + verb, n || 1, labels || {}); }
     catch (_e) { /* drop-silent */ }
   }
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   "system.observability.otlp_exporter." + action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent — audit is best-effort, never crashes the exporter */ }
+  }
 
   function queue_(span) {
     if (stopping) { droppedExportFailed += 1; return; }
@@ -302,7 +314,19 @@ function create(opts) {
       }
       return { ok: false, status: status, retryable: retryable };
     } catch (e) {
-      // Network error / abort
+      // Network error / abort. AbortController abort surfaces with
+      // name=AbortError; tag the audit so operators can distinguish
+      // a genuine network drop from "we timed out reaching the
+      // collector". Both are retryable but the audit metadata helps
+      // root-cause when collector latency is the issue.
+      var abortReason = e && (e.name === "AbortError" || /aborted|timeout/i.test(e.message || ""));
+      _emitAudit("post_failed", "failure", {
+        attempt:    attempt,
+        retryable:  attempt < maxAttempts,
+        reason:     abortReason ? "timeout" : "network",
+        error:      (e && e.message) || String(e),
+      });
+      if (abortReason) _emitMetric("export_timeout", 1, { attempt: String(attempt) });
       if (attempt < maxAttempts) {
         await _sleep(_backoffMs(attempt));
         return await _post(payload, attempt + 1);
@@ -354,10 +378,22 @@ function create(opts) {
   }
 
   function stats() {
+    var totalDropped = droppedQueueOverflow + droppedExportFailed;
+    // Operator-facing dropped-count metric — fires every stats() call
+    // so dashboards / probes that scrape stats can chart the running
+    // total even when individual drop sites already emit per-event
+    // metrics. The metric is monotonic for the lifetime of the
+    // exporter; a process restart resets it (intended).
+    _emitMetric("dropped_total", 0, {
+      queue_overflow: String(droppedQueueOverflow),
+      export_failed:  String(droppedExportFailed),
+      total:          String(totalDropped),
+    });
     return {
       queueLength:           queue.length,
       droppedQueueOverflow:  droppedQueueOverflow,
       droppedExportFailed:   droppedExportFailed,
+      droppedTotal:          totalDropped,
     };
   }
 

package/package.json

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

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:1f60d33c-fc3b-4da1-a753-bb1c98de9968",
+  "serialNumber": "urn:uuid:c89193b4-c13d-4dd9-882f-4581a77a92d9",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-06T22:33:10.715Z",
+    "timestamp": "2026-05-07T01:02:55.563Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.8.5",
+      "bom-ref": "@blamejs/core@0.8.7",
       "type": "library",
       "name": "blamejs",
-      "version": "0.8.5",
+      "version": "0.8.7",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.8.5",
+      "purl": "pkg:npm/%40blamejs/core@0.8.7",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.8.5",
+      "ref": "@blamejs/core@0.8.7",
       "dependsOn": []
     }
   ]