@blamejs/core 0.8.6 → 0.8.8

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.8.x
 
+- **0.8.8** (2026-05-07) — `b.middleware.requireBoundKey` + `b.audit.rotateSigningKey` / `reSignAll` + `b.circuitBreaker` top-level surface + `b.htmlBalance.checkSafe` + permissions predicate-shape audit + FIPS 140-3 boundary docs + ESLint pin. **`b.middleware.requireBoundKey`** — Bearer-API-key middleware with three-axis binding: required scopes, bound-field equality (operator pulls values from headers / query / body via `getBoundField` getters; bound-fields registered on the key are checked with constant-time match), and peer-cert fingerprint allowlist (composes with v0.8.4's `b.crypto.hashCertFingerprint` / `isCertRevoked`). Operator-supplied async `resolver(apiKey)` returns the registered record `{ id, scopes, boundFields, peerCertFingerprints }` or `null` when revoked. Refusals carry structured reasons (`no-bearer-token`, `key-unknown-or-revoked`, `missing-scope`, `bound-field-missing`, `bound-field-mismatch`, `peer-cert-required`, `peer-cert-not-pinned`); audit chain captures the keyId + reason on every refusal. **`b.audit.rotateSigningKey`** — operator-callable rotation of the audit-signing keypair. Generates (or accepts BYO) a new keypair, copies the existing sealed file to a timestamped history path so historical signatures remain verifiable, re-seals with the operator's passphrase, and atomic-swaps the in-memory keys. Companion `reSignAll(iter)` walks an operator-supplied async iterable of `{ payload, signature, oldPublicKeyPem }` and re-signs each entry with the new key — the audit module's checkpoint store calls this to re-stamp historical checkpoints after a rotation. **`b.circuitBreaker`** — top-level re-export of `b.retry.CircuitBreaker` so operators discover it alongside `b.retry`; same state machine, same `wrap()` API, ergonomic `create(opts)` factory. **`b.htmlBalance.checkSafe(html, opts)`** — combines structural `balance()` check with a `b.guardHtml.gate` security pass under the same `{ profile, posture }` opt shape used by `b.fileUpload({ contentSafety })` / `b.staticServe({ contentSafety })`. **`b.permissions.policy(scope, predicate)`** — emits `permissions.policy_predicate_shape_warning` audit on register-time when the predicate's `.length < 2` (operators commonly forget the `context` argument and ship a predicate that's always-true on the actor parameter). **`SECURITY.md`** — new "FIPS 140-3 cryptographic boundary" section explaining the dual boundary (Node.js OpenSSL FIPS provider for classical primitives, vendored noble-* implementations for PQ algorithms — the latter implement FIPS-published algorithms but the *implementations themselves* are not CMVP-validated). Operator path for FIPS-mandated environments documented. **CI** — eslint pinned to `10.3.0` across `ci.yml` / `npm-publish.yml` / `release-container.yml`; `eslint@latest` was silently letting new rule additions break the publish gate on releases that had passed the day before. The pin moves on operator-confirmed bumps.
+
+- **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.

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");
@@ -246,6 +247,7 @@ module.exports = {
   storage:          storage,
   objectStore:      objectStore,
   retry:            retry,
+  circuitBreaker:   require("./lib/circuit-breaker"),
   queue:            queue,
   logStream:        logStream,
   redact:           redact,

package/lib/audit-sign.js

@@ -326,6 +326,158 @@ function getPublicKeyFingerprint() { _requireInit(); return keys.fingerprint; }
 function getMode() { return currentMode; }
 function getAlgorithm() { _requireInit(); return keys.algorithm; }
 
+// Re-sign every payload in the operator-supplied iterable using the
+// CURRENT in-memory key. Returns { reSigned: number, skipped: number,
+// errors: number } so the caller (audit module's checkpoint store)
+// can log a summary. Each iteration is wrapped in try/catch — a
+// payload that fails to verify under the OLD key is skipped (already
+// tampered or never signed under the historical key) rather than
+// aborting the whole walk.
+//
+// The iterable yields { payload, signature, oldPublicKeyPem } so the
+// caller's storage layer doesn't need to reach into audit-sign's
+// internal key-history. The caller persists the new signature in
+// place — this primitive returns the new bytes without touching
+// storage.
+async function reSignAll(iter, opts) {
+  _requireInit();
+  opts = opts || {};
+  var summary = { reSigned: 0, skipped: 0, errors: 0 };
+  var onProgress = typeof opts.onProgress === "function" ? opts.onProgress : null;
+  for await (var entry of iter) {
+    try {
+      if (!entry || !entry.payload || !entry.signature) {
+        summary.skipped += 1;
+        continue;
+      }
+      var oldPub = entry.oldPublicKeyPem || keys.publicKey;
+      if (!verify(entry.payload, entry.signature, oldPub)) {
+        summary.skipped += 1;
+        continue;
+      }
+      var newSig = sign(entry.payload);
+      summary.reSigned += 1;
+      if (onProgress) {
+        try { onProgress({ id: entry.id, newSignature: newSig }); }
+        catch (_e) { /* operator hook, drop-silent */ }
+      }
+    } catch (_e) {
+      summary.errors += 1;
+    }
+  }
+  return summary;
+}
+
+// Rotate the in-memory + on-disk keypair. Generates a fresh keypair
+// (or accepts operator-supplied keypair via opts.privateKeyPem +
+// publicKeyPem for the BYO-key case), writes the OLD sealed file
+// to a timestamped history path so historical checkpoints can still
+// be verified, then re-seals with the new keypair.
+//
+// rotation does NOT walk and re-sign existing audit checkpoints —
+// the audit module orchestrates that via reSignAll() above so the
+// per-row storage transactions stay in one place. Operators rotating
+// the audit key in production typically:
+//   1. Read existing audit checkpoints
+//   2. Call rotateSigningKey() — gets new keys live
+//   3. Walk checkpoints through reSignAll()
+//   4. Write back the new signatures atomically
+async function rotateSigningKey(rotOpts) {
+  _requireInit();
+  rotOpts = rotOpts || {};
+  var prevFingerprint = keys.fingerprint;
+  var prevPublicKey = keys.publicKey;
+  var prevAlgorithm = keys.algorithm;
+
+  // Operator may supply the new keypair (BYO; useful for a hardware-
+  // backed signer) or let the framework generate. The algorithm
+  // defaults to the current keypair's algorithm; operators upgrading
+  // the algorithm pass the new alg explicitly.
+  var newAlg;
+  var newPair;
+  if (typeof rotOpts.privateKeyPem === "string" && typeof rotOpts.publicKeyPem === "string") {
+    newAlg  = rotOpts.algorithm || prevAlgorithm;
+    newPair = { publicKey: rotOpts.publicKeyPem, privateKey: rotOpts.privateKeyPem };
+  } else {
+    newAlg = rotOpts.algorithm || prevAlgorithm;
+    newPair = nodeCrypto.generateKeyPairSync(newAlg, {
+      publicKeyEncoding:  { type: "spki",  format: "pem" },
+      privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    });
+  }
+  if (SUPPORTED_SIGNING_ALGS.indexOf(newAlg) === -1) {
+    throw _err("ROTATE_BAD_ALG",
+      "audit-sign.rotateSigningKey: algorithm '" + newAlg + "' is not in SUPPORTED_SIGNING_ALGS");
+  }
+
+  var newFingerprint = _computeFingerprint(newPair.publicKey);
+  if (newFingerprint === prevFingerprint) {
+    throw _err("ROTATE_NOOP",
+      "audit-sign.rotateSigningKey: new keypair has identical fingerprint to the current — refusing to write a no-op rotation");
+  }
+
+  // Move the existing sealed/plaintext file to a timestamped history
+  // path so historical checkpoints can still be verified by readers
+  // that load the old key. We keep the history forever — the file is
+  // small (a few KB) and signed audit checkpoints can be decades old.
+  var iso = new Date().toISOString().replace(/[:.]/g, "-");
+  if (currentMode === "wrapped" && paths && paths.sealed) {
+    var historyPath = paths.sealed + ".history-" + iso + "-" + prevFingerprint.slice(0, 16)                                       /* allow:raw-byte-literal — fingerprint hex truncation count */;
+    try { await atomicFile.copy(paths.sealed, historyPath); }
+    catch (_e) { /* history copy is best-effort; the in-memory rotation still proceeds */ }
+  } else if (currentMode === "plaintext" && paths && paths.plaintext) {
+    var historyPathP = paths.plaintext + ".history-" + iso + "-" + prevFingerprint.slice(0, 16)                                       /* allow:raw-byte-literal — fingerprint hex truncation count */;
+    try { await atomicFile.copy(paths.plaintext, historyPathP); }
+    catch (_e) { /* history copy is best-effort */ }
+  }
+
+  // Persist the new keypair through the same path as boot — sealed
+  // mode re-wraps with the operator's passphrase; plaintext mode
+  // writes JSON. We don't accept a passphrase override here; the
+  // existing in-process passphrase derivation runs again.
+  if (currentMode === "wrapped") {
+    var passphrase = await _getPassphrase("Audit-signing passphrase (rotate): ");
+    try {
+      var sealed = await vaultWrap.wrap(
+        JSON.stringify({ algorithm: newAlg, publicKey: newPair.publicKey, privateKey: newPair.privateKey }, null, 2),
+        passphrase
+      );
+      atomicFile.writeSync(paths.sealed, sealed, { fileMode: 0o600 });
+    } finally { safeBuffer.secureZero(passphrase); }
+  } else if (currentMode === "plaintext") {
+    atomicFile.writeSync(
+      paths.plaintext,
+      JSON.stringify({ algorithm: newAlg, publicKey: newPair.publicKey, privateKey: newPair.privateKey }, null, 2),
+      { fileMode: 0o600 }
+    );
+  }
+
+  // Atomic in-memory swap last (so a write failure above doesn't
+  // leave a half-rotated state where memory has the new key but the
+  // disk has the old one).
+  keys = {
+    publicKey:  newPair.publicKey,
+    privateKey: newPair.privateKey,
+    algorithm:  newAlg,
+    fingerprint: newFingerprint,
+  };
+  log("audit-signing keypair rotated (alg=" + newAlg + ", fp=" + newFingerprint.slice(0, 16) + "...)");                       /* allow:raw-byte-literal — fingerprint hex truncation count */
+
+  return {
+    previousFingerprint: prevFingerprint,
+    previousPublicKey:   prevPublicKey,
+    newFingerprint:      newFingerprint,
+    newPublicKey:        newPair.publicKey,
+    algorithm:           newAlg,
+    rotatedAt:           new Date().toISOString(),
+    historyPath:         (currentMode === "wrapped" && paths && paths.sealed)
+                          ? paths.sealed + ".history-" + iso + "-" + prevFingerprint.slice(0, 16)                                       /* allow:raw-byte-literal — fingerprint hex truncation count */
+                          : (currentMode === "plaintext" && paths && paths.plaintext)
+                            ? paths.plaintext + ".history-" + iso + "-" + prevFingerprint.slice(0, 16)                                       /* allow:raw-byte-literal — fingerprint hex truncation count */
+                            : null,
+  };
+}
+
 function _resetForTest() {
   keys = null;
   initialized = false;
@@ -338,6 +490,8 @@ module.exports = {
   init:                     init,
   sign:                     sign,
   verify:                   verify,
+  rotateSigningKey:         rotateSigningKey,
+  reSignAll:                reSignAll,
   getPublicKey:             getPublicKey,
   getPublicKeyFingerprint:  getPublicKeyFingerprint,
   getMode:                  getMode,

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/circuit-breaker.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * b.circuitBreaker — top-level circuit-breaker primitive.
+ *
+ * Re-exports the CircuitBreaker class previously only reachable as
+ * b.retry.CircuitBreaker, plus a `create(opts)` factory that matches
+ * every other framework primitive's `create()` shape. The
+ * implementation lives in lib/retry.js to keep the retry-classifier
+ * + CircuitBreaker close to each other (they share the
+ * isRetryable / observability emit conventions). This module is the
+ * top-level surface so operators don't have to know that retry
+ * happens to be the home of the circuit-breaker class.
+ *
+ * State machine:
+ *   closed   — normal flow; failures count up to failureThreshold
+ *   open     — fast-fail every call for cooldownMs
+ *   half     — first probe succeeds → close; first probe fails → re-open
+ *
+ *   var cb = b.circuitBreaker.create({
+ *     name:                 "upstream-billing",
+ *     failureThreshold:     5,
+ *     cooldownMs:           b.constants.TIME.seconds(30),
+ *     successThreshold:     2,
+ *     audit:                b.audit,
+ *     onStateChange:        function (event) {
+ *       // event = { name, from, to, at }
+ *       log("breaker " + event.name + " " + event.from + " -> " + event.to);
+ *     },
+ *   });
+ *   await cb.wrap(function () { return upstream.callRiskyOp(); });
+ *
+ * The circuit-breaker is intended for per-target use (one instance
+ * per upstream service); operators sharing a breaker across
+ * unrelated targets defeat the failure-threshold semantic.
+ */
+
+var retry = require("./retry");
+
+// Pass-through factory — operators get the same instance shape as
+// b.retry.CircuitBreaker but with the framework's `create(opts)`
+// vocabulary. The breaker class is unchanged; this is a thin
+// surface re-export so b.circuitBreaker is operator-discoverable
+// alongside b.retry.
+function create(opts) {
+  return new retry.CircuitBreaker(opts || {});
+}
+
+module.exports = {
+  create:         create,
+  CircuitBreaker: retry.CircuitBreaker,
+  // Forward the error class so operators catching breaker rejections
+  // can `instanceof` against the framework's RetryError without
+  // requiring a separate b.retry import.
+  RetryError:     retry.RetryError,
+};

package/lib/html-balance.js

@@ -224,4 +224,41 @@ function check(html) {
   return null;
 }
 
-module.exports = { check: check };
+// Optional content-safety pass for HTML rendered through the framework.
+// Mirrors the same opt shape as b.fileUpload({ contentSafety }) /
+// b.staticServe({ contentSafety }) so operators wiring guards across
+// the stack pass a single { profile, posture } object — the pass-
+// through to b.guardHtml.gate validates the HTML against the same
+// strict / balanced / permissive vocabulary, plus the configured
+// compliance posture.
+//
+//   var safe = b.htmlBalance.checkSafe(html, { profile: "strict" });
+//   if (safe.issues.length) refuseRequest();
+//
+// checkSafe runs balance() first (cheap structural well-formedness),
+// then guardHtml.gate({ profile }) for the security-class checks. The
+// returned shape is { balanceIssue, guardIssues } so callers can
+// distinguish a structural problem from a content-safety reject.
+var lazyRequire = require("./lazy-require");
+var _guardHtml = lazyRequire(function () { return require("./guard-html"); });
+
+function checkSafe(html, opts) {
+  opts = opts || {};
+  var balanceIssue = check(html);
+  var guardIssues = [];
+  if (opts.profile || opts.contentSafety) {
+    var profile = opts.profile || (opts.contentSafety && opts.contentSafety.profile) || "strict";
+    var posture = opts.posture || (opts.contentSafety && opts.contentSafety.posture) || null;
+    var validateOpts = { profile: profile };
+    if (posture) validateOpts.compliancePosture = posture;
+    var rv = _guardHtml().validate(html, validateOpts);
+    if (rv && Array.isArray(rv.issues)) guardIssues = rv.issues;
+  }
+  return {
+    balanceIssue: balanceIssue,
+    guardIssues:  guardIssues,
+    ok:           !balanceIssue && guardIssues.length === 0,
+  };
+}
+
+module.exports = { check: check, checkSafe: checkSafe };

package/lib/middleware/require-bound-key.js

@@ -0,0 +1,249 @@
+"use strict";
+/**
+ * requireBoundKey middleware — Bearer-API-key auth with scope + bound-
+ * fields + cert-fingerprint binding.
+ *
+ * The framework's bearer-auth + dpop + requireMtls cover JWT, DPoP, and
+ * mTLS. requireBoundKey covers the API-key-with-binding case that
+ * shows up on internal service-to-service endpoints, partner API
+ * webhook receivers, and CI runners shipping events to a hosted
+ * blamejs deployment:
+ *
+ *   - Authorization: Bearer <api-key>
+ *   - the API key is registered in an operator-supplied resolver
+ *     with: { scopes: [...], boundFields: { ... }, peerCertFingerprints: [...] }
+ *   - the request must present a peer cert whose fingerprint is in
+ *     peerCertFingerprints (when set)
+ *   - the request must include the boundFields with the registered
+ *     values (e.g. { tenantId: "acme", region: "us-east-1" }) — bound
+ *     fields are pulled from headers / query / body via getter
+ *   - the request must hold one of the operator-required scopes
+ *
+ * Failure mode: 401 / 403 with a structured JSON body identifying
+ * which check failed (operator audit trail). Audits emit
+ * `auth.require_bound_key.allowed` / `auth.require_bound_key.refused`
+ * with the api-key-id (not the secret) + reason metadata.
+ *
+ *   var keys = b.middleware.requireBoundKey({
+ *     resolver: async function (apiKey) {
+ *       // operator-supplied — usually a DB lookup with timing-safe
+ *       // compare. Returns { id, scopes, boundFields, peerCertFingerprints }
+ *       // or null when the key is unknown / revoked.
+ *       return await keyDb.findByKey(apiKey);
+ *     },
+ *     requiredScopes:    ["webhook.ingest"],
+ *     getBoundField:     {
+ *       tenantId: function (req) { return req.headers["x-tenant-id"]; },
+ *       region:   function (req) { return req.query.region; },
+ *     },
+ *     audit:             b.audit,
+ *   });
+ *   router.post("/webhook/ingest", keys, ingestHandler);
+ *
+ * Composition with other middleware:
+ *   - b.middleware.requireMtls runs FIRST (so req.peerCert is set)
+ *   - b.middleware.requireBoundKey reads req.peerCert and cross-checks
+ *
+ * Defaults to fail-closed on every check; resolver throws / returns
+ * undefined → refused with reason "resolver-unavailable".
+ */
+
+var defineClass = require("../framework-error").defineClass;
+var lazyRequire = require("../lazy-require");
+var validateOpts = require("../validate-opts");
+
+var crypto = lazyRequire(function () { return require("../crypto"); });
+var audit  = lazyRequire(function () { return require("../audit"); });
+
+var RequireBoundKeyError = defineClass("RequireBoundKeyError", { alwaysPermanent: true });
+
+function _parseBearer(req) {
+  var h = req.headers && (req.headers.authorization || req.headers.Authorization);
+  if (typeof h !== "string" || h.length === 0) return null;
+  var m = h.match(/^Bearer\s+([\x21-\x7e]+)$/);                                          // RFC 6750 token68
+  return m ? m[1] : null;
+}
+
+function _timingSafeStringEqual(a, b) {
+  if (typeof a !== "string" || typeof b !== "string") return false;
+  if (a.length !== b.length) return false;
+  return crypto().timingSafeEqual(Buffer.from(a), Buffer.from(b));
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "resolver", "requiredScopes", "getBoundField",
+    "audit", "auditAction", "errorMessage",
+    "tolerateMissingPeerCert",
+  ], "middleware.requireBoundKey");
+
+  if (typeof opts.resolver !== "function") {
+    throw new RequireBoundKeyError("require-bound-key/bad-resolver",
+      "middleware.requireBoundKey: opts.resolver must be an async function (apiKey) -> {id, scopes, boundFields, peerCertFingerprints} | null");
+  }
+  var resolver = opts.resolver;
+  var requiredScopes = Array.isArray(opts.requiredScopes) ? opts.requiredScopes.slice() : [];
+  for (var rs = 0; rs < requiredScopes.length; rs++) {
+    if (typeof requiredScopes[rs] !== "string" || requiredScopes[rs].length === 0) {
+      throw new RequireBoundKeyError("require-bound-key/bad-scope",
+        "middleware.requireBoundKey: requiredScopes[" + rs + "] must be a non-empty string");
+    }
+  }
+  var getBoundField = (opts.getBoundField && typeof opts.getBoundField === "object")
+    ? opts.getBoundField : {};
+  var boundFieldNames = Object.keys(getBoundField);
+  for (var bf = 0; bf < boundFieldNames.length; bf++) {
+    if (typeof getBoundField[boundFieldNames[bf]] !== "function") {
+      throw new RequireBoundKeyError("require-bound-key/bad-bound-field-getter",
+        "middleware.requireBoundKey: getBoundField." + boundFieldNames[bf] + " must be a function (req) -> string");
+    }
+  }
+  var auditOn = opts.audit !== false;
+  var actionBase = typeof opts.auditAction === "string" && opts.auditAction.length > 0
+    ? opts.auditAction : "auth.require_bound_key";
+  var errorMessage = typeof opts.errorMessage === "string" && opts.errorMessage.length > 0
+    ? opts.errorMessage : "api key required";
+  // For operator-side fixtures and dev environments without an mTLS
+  // termination layer, allow disabling the peer-cert cross-check
+  // even when peerCertFingerprints is set on the registered key.
+  // Production deployments leave this at default false.
+  var tolerateMissingPeerCert = !!opts.tolerateMissingPeerCert;
+
+  function _emitAudit(outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   actionBase + (outcome === "success" ? ".allowed" : ".refused"),
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+
+  function _refuse(res, status, reason, metadata) {
+    _emitAudit("denied", Object.assign({ reason: reason }, metadata || {}));
+    if (res.writableEnded || typeof res.writeHead !== "function") return;
+    res.writeHead(status, {
+      "Content-Type":     "application/json; charset=utf-8",
+      "WWW-Authenticate": 'Bearer realm="api", error="invalid_request"',
+      "Cache-Control":    "no-store",
+    });
+    res.end(JSON.stringify({ error: errorMessage, reason: reason }));
+  }
+
+  return async function requireBoundKeyMiddleware(req, res, next) {
+    var apiKey = _parseBearer(req);
+    if (!apiKey) return _refuse(res, 401, "no-bearer-token", {});
+
+    var record;
+    try { record = await resolver(apiKey); }
+    catch (e) {
+      return _refuse(res, 503, "resolver-unavailable", {
+        error: (e && e.message) || String(e),
+      });
+    }
+    if (!record || typeof record !== "object") {
+      return _refuse(res, 401, "key-unknown-or-revoked", {});
+    }
+
+    // Required-scope check — operator-supplied requiredScopes must be
+    // a subset of the registered key's scopes.
+    var keyScopes = Array.isArray(record.scopes) ? record.scopes : [];
+    for (var rsi = 0; rsi < requiredScopes.length; rsi++) {
+      if (keyScopes.indexOf(requiredScopes[rsi]) === -1) {
+        return _refuse(res, 403, "missing-scope", {
+          requiredScope: requiredScopes[rsi], keyId: record.id || null,
+        });
+      }
+    }
+
+    // Bound-field check — every key in the registered boundFields map
+    // must be present on the request and match. The operator's
+    // getBoundField extracts each value from headers / query / body.
+    var registered = (record.boundFields && typeof record.boundFields === "object") ? record.boundFields : {};
+    var registeredKeys = Object.keys(registered);
+    for (var bfi = 0; bfi < registeredKeys.length; bfi++) {
+      var fieldName = registeredKeys[bfi];
+      var getter = getBoundField[fieldName];
+      if (!getter) {
+        return _refuse(res, 500, "bound-field-no-getter", {
+          field: fieldName, keyId: record.id || null,
+        });
+      }
+      var presented;
+      try { presented = getter(req); }
+      catch (e) {
+        return _refuse(res, 400, "bound-field-getter-threw", {                            // allow:raw-byte-literal — HTTP 400
+          field: fieldName, error: (e && e.message) || String(e),
+        });
+      }
+      if (typeof presented !== "string" || presented.length === 0) {
+        return _refuse(res, 400, "bound-field-missing", {                                 // allow:raw-byte-literal — HTTP 400
+          field: fieldName, keyId: record.id || null,
+        });
+      }
+      var expected = String(registered[fieldName]);
+      if (!_timingSafeStringEqual(presented, expected)) {
+        return _refuse(res, 403, "bound-field-mismatch", {
+          field: fieldName, keyId: record.id || null,
+        });
+      }
+    }
+
+    // Peer-cert fingerprint check — if the registered key pins peer
+    // certs, the request must come over mTLS with a fingerprint on
+    // the allowlist. b.middleware.requireMtls running upstream
+    // attaches req.peerCert / req.peerFingerprint; we re-derive when
+    // a downstream middleware order leaves them unset.
+    var pinned = Array.isArray(record.peerCertFingerprints) ? record.peerCertFingerprints : [];
+    if (pinned.length > 0) {
+      var fpHex = req.peerFingerprint && req.peerFingerprint.hex;
+      var fpColon = req.peerFingerprint && req.peerFingerprint.colon;
+      if (!fpHex && req.peerCert && req.peerCert.raw) {
+        try {
+          var fp = crypto().hashCertFingerprint(req.peerCert.raw);
+          fpHex = fp.hex; fpColon = fp.colon;
+        } catch (_e) { /* fall through to refused below */ }
+      }
+      if (!fpHex) {
+        if (tolerateMissingPeerCert) {
+          // Audited bypass for dev fixtures.
+          _emitAudit("denied", { reason: "peer-cert-bypass-tolerated", keyId: record.id });
+        } else {
+          return _refuse(res, 401, "peer-cert-required", {
+            keyId: record.id || null,
+          });
+        }
+      } else if (!crypto().isCertRevoked(req.peerCert.raw, pinned)) {
+        // isCertRevoked returns true on MATCH against the deny-list
+        // shape; we use it here as a fingerprint-set membership test
+        // because it does the same constant-time hex/colon comparison
+        // we want for an allow-list. A future refactor can rename to
+        // isCertFingerprintInSet — semantically identical.
+        return _refuse(res, 403, "peer-cert-not-pinned", {
+          fingerprint: fpColon, keyId: record.id || null,
+        });
+      }
+    }
+
+    // All checks passed. Attach the resolved record to req.apiKey for
+    // downstream handlers (without the secret — the resolver returned
+    // a normalized record, the middleware never re-exposes the bearer).
+    req.apiKey = {
+      id:           record.id || null,
+      scopes:       keyScopes.slice(),
+      boundFields:  Object.assign({}, registered),
+    };
+    _emitAudit("success", {
+      keyId:         record.id || null,
+      scopesGranted: keyScopes,
+    });
+    return next();
+  };
+}
+
+module.exports = {
+  create:               create,
+  RequireBoundKeyError: RequireBoundKeyError,
+};

package/lib/permissions.js

@@ -300,6 +300,29 @@ function create(opts) {
     if (policies[scope]) {
       throw _err("DUPLICATE_POLICY", "permissions.policy: '" + scope + "' is already registered");
     }
+    // Predicate-shape sanity check — predicate(actor, context) is the
+    // documented contract. Operator-supplied 0-arg or 1-arg predicates
+    // typically indicate the operator forgot the context parameter
+    // and is silently always-true for any actor (the predicate
+    // returns based on closure state instead of inspecting the
+    // actor / context). Emit a one-time audit warning at register-
+    // time so operator-side tooling sees the misconfiguration.
+    if (predicate.length < 2) {
+      try {
+        if (audit && typeof audit.safeEmit === "function") {
+          audit.safeEmit({
+            action:   "permissions.policy_predicate_shape_warning",
+            outcome:  "warning",
+            metadata: {
+              scope:    scope,
+              arity:    predicate.length,
+              expected: "predicate(actor, context) -> bool",
+              hint:     "predicate has " + predicate.length + " formal arg(s); the framework calls it as predicate(actor, context). Confirm the predicate inspects both args.",
+            },
+          });
+        }
+      } catch (_e) { /* drop-silent — audit is best-effort */ }
+    }
     policies[scope] = predicate;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.8.6",
+  "version": "0.8.8",
   "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:88336eab-78a7-45f2-bc73-faf15cf6bbfb",
+  "serialNumber": "urn:uuid:44e2ace4-98b8-425c-a2f3-bd209fde34f3",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-06T22:51:45.376Z",
+    "timestamp": "2026-05-07T01:56:20.867Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.8.6",
+      "bom-ref": "@blamejs/core@0.8.8",
       "type": "library",
       "name": "blamejs",
-      "version": "0.8.6",
+      "version": "0.8.8",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.8.6",
+      "purl": "pkg:npm/%40blamejs/core@0.8.8",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.8.6",
+      "ref": "@blamejs/core@0.8.8",
       "dependsOn": []
     }
   ]