@blamejs/core 0.6.7 → 0.6.12

package/CHANGELOG.md

@@ -8,6 +8,12 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **0.6.12** (2026-05-02) — `b.safeUrl.parse` now rejects URLs with `user:pass@` userinfo by default (opt in per-call via `allowUserinfo: true`); `b.session.touch({ extendBy })` enforces the same `MAX_TTL_MS` ceiling as `create` / `rotate`; `b.queue.consume({ rateLimit })` rejects negative / zero / `NaN` / `Infinity` / fractional `max`; `b.middleware.requireAuth` no longer treats request `Content-Type: application/json` as a JSON-preference signal (only `Accept` and `X-Requested-With` count); `b.backup.create({ requireFlush: true })` opt-in fails the backup if pre-flush fails instead of producing a stale snapshot; `b.restore.create({ maxPulledBytes, maxPulledFiles })` preflight bounds bundle footprint before and after pull (defaults 4 GiB / 100K files); `b.mail.transports.console({ redactBcc: true })` opt-in prints recipient count instead of addresses; `b.logStream.transports.webhook({ onDrop })` callback fires on overflow + retry-exhausted batch drops. Wiki: admin login wired through `b.auth.lockout` (exponential-backoff after bad-cred attempts) and cookie `Secure` flag now routes through `b.requestHelpers.requestProtocol` with `WIKI_TRUST_PROXY` opt-in instead of trusting raw `x-forwarded-proto`. Wiki README documents the trust model for editable page bodies and the sanitization pattern operators should adopt before expanding the editor surface.
+- **0.6.11** (2026-05-01) — wiki example-execution validator: fixture init no longer reaches across module realms (unblocks the npm-publish workflow's wiki-e2e gate, which `npm install --install-links` copies the framework into the wiki's node_modules — two distinct singletons before this fix)
+- **0.6.10** (2026-05-01) — README / SECURITY / CONTRIBUTING / wiki: removed stale version stamps and an inaccurate vendored-dep list; SECURITY now points at `lib/vendor/MANIFEST.json` for the authoritative vendor list; supported-versions table no longer pins to a specific minor; wiki archive example names the digest variable correctly (was `sha256`, output is SHA3-512 hex)
+- **0.6.9** (2026-05-01) — b.archive.zip().digest() returns a SHA3-512 hex string (was SHA-256); operators reconciling against an external SHA-256 must hash the bytes themselves
+- **0.6.8** (2026-05-01) — wiki primitive-section validator: presence + opts diff + example execution against canonical fixture
+- **0.6.7** (2026-05-01) — db.role.switched audit + per-role metrics + API snapshot baseline
 - **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
@@ -73,7 +79,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
-- **0.3.39** (2026-04-29) — MIGRATING.md generator scans deprecate() calls in lib/
+- **0.3.39** (2026-04-29) — MIGRATING.md generator scans deprecate calls in lib/
 - **0.3.38** (2026-04-29) — LTS-CALENDAR.md publishes the major-cadence + algorithm posture
 - **0.3.37** (2026-04-29) — bundled pure-JS mTLS engine + vendor-update.sh + CHANGELOG + thanks page
 - **0.3.36** (2026-04-29) — prepack guard refuses to publish any path that matches a gitignore rule
@@ -88,15 +94,15 @@ upgrading across more than a few patches at a time.
 - **0.3.27** (2026-04-29) — Dockerfile pre-builds public/dist in deps stage so runtime container boots cleanly under --cap-drop ALL
 - **0.3.26** (2026-04-29) — operator-facing env-var surface, GitHub-side ops docs, contribution standards
 - **0.3.25** (2026-04-29) — env-var surface documented across Dockerfile, docker-compose.prod, DEPLOY.md, README; smoke-test GHCR login fix
-- **0.3.24** (2026-04-29) — CI + release-container workflows brought to hermitstash parity (structured output, multi-arch, cosign, post-publish smoke)
+- **0.3.24** (2026-04-29) — CI + release-container workflows brought (structured output, multi-arch, cosign, post-publish smoke)
 - **0.3.23** (2026-04-29) — _runVault and _runBackup refactored to use b.cliHelpers (sweep complete across the three CLI commands the helper was designed for)
 - **0.3.22** (2026-04-29) — blamejs api-key CLI; b.cliHelpers shared primitive for headless app + reporter shape
 - **0.3.21** (2026-04-29) — blamejs backup CLI: inspect / verify / extract; backup encryption format documented
 - **0.3.20** (2026-04-29) — drop redundant Windows-flaky audit.flush perf assertion
 - **0.3.19** (2026-04-29) — wiki docs for the unwired primitives surface
 - **0.3.18** (2026-04-29) — blamejs vault CLI: seal / unseal / rotate / status
-- **0.3.17** (2026-04-29) — Tier-A validateOpts coverage extended to remaining operator-facing primitives (i18n, bundler, migrations, seeders, template, jobs, cookies, log, mtlsCa, staticServe, handlers, websocket, pqcGate, tracing, metrics — 15 more factories now reject typo'd opts at boot). Coverage is now ~39/lib primitives with the helper; the remaining handful (app-shutdown, chain-writer, dev, error-page, nonce-store, protocol-dispatcher, render, session, pqc-agent) are either internal-only — operators don't construct them directly — or have a single required-key surface where typo guards add no value.
-- **0.3.16** (2026-04-29) — Tier-A config validation, CSRF cookie mode, HTML balance, dynamic Cache-Control, URL canonicalization
+- **0.3.17** (2026-04-29) — validateOpts coverage extended to remaining operator-facing primitives (i18n, bundler, migrations, seeders, template, jobs, cookies, log, mtlsCa, staticServe, handlers, websocket, pqcGate, tracing, metrics — 15 more factories now reject typo'd opts at boot). Coverage is now ~39/lib primitives with the helper; the remaining handful (app-shutdown, chain-writer, dev, error-page, nonce-store, protocol-dispatcher, render, session, pqc-agent) are either internal-only — operators don't construct them directly — or have a single required-key surface where typo guards add no value.
+- **0.3.16** (2026-04-29) — config validation, CSRF cookie mode, HTML balance, dynamic Cache-Control, URL canonicalization
 - **0.3.15** (2026-04-29) — cors: accept Origin: null when Sec-Fetch-Site is same-origin (browsers send opaque Origin: null on form-navigation POSTs from a page whose response sets Referrer-Policy: no-referrer; the Fetch-metadata Sec-Fetch-Site header is the matching disambiguation signal — same-origin or none means accept, anything else stays refused)
 - **0.3.14** (2026-04-29) — Dockerfile hotfix + lint as release gate
 - **0.3.13** (2026-04-29) — CI lint scans + Wolfi container + Trivy two-step + lint cleanup
@@ -133,7 +139,7 @@ upgrading across more than a few patches at a time.
 - **0.2.25** (2026-04-28) — b.slug
 - **0.2.24** (2026-04-28) — b.retry primitive
 - **0.2.23** (2026-04-28) — test helpers consolidate
-- **0.2.22** (2026-04-28) — tier-aware input validation
+- **0.2.22** (2026-04-28) — input validation
 - **0.2.21** (2026-04-28) — defineClass.factory replaces per-module _err wrappers
 - **0.2.20** (2026-04-28) — b.requestHelpers + metrics _normalizeLabelArg
 - **0.2.19** (2026-04-28) — audit.safeEmit replaces per-module _emit wrappers
@@ -195,22 +201,22 @@ upgrading across more than a few patches at a time.
 - **0.1.78** (2026-04-27) — pqc-agent: locked-posture HTTPS agent + http-client refactor — slice 2
 - **0.1.77** (2026-04-27) — pqc-gate: TCP-level PQC enforcement on ClientHello — slice 1
 - **0.1.76** (2026-04-27) — bundler: content-hashed asset pipeline + manifest — complete
-- **0.1.75** (2026-04-27) — dev: file-watch + child-process restart engine — slice 6 ( complete)
+- **0.1.75** (2026-04-27) — dev: file-watch + child-process restart engine — slice 6 (complete)
 - **0.1.74** (2026-04-27) — cli: bin/blamejs + migrate up/down/status — slice 5
 - **0.1.73** (2026-04-27) — migrations: public up/down/status runner — slice 4
 - **0.1.72** (2026-04-27) — cookies: parse/serialize + sealed-value access gate — slice 3
 - **0.1.71** (2026-04-27) — errors-page: rich dev page + safe prod page; middleware shim — slice 2
 - **0.1.70** (2026-04-27) — log: structured JSON logging with request-id correlation — slice 1
-- **0.1.69** (2026-04-27) — scheduler: cron + interval over jobs/queue — slice 5 ( complete)
+- **0.1.69** (2026-04-27) — scheduler: cron + interval over jobs/queue — slice 5 (complete)
 - **0.1.68** (2026-04-27) — mail: generalize http transport, demote resend to thin preset
 - **0.1.67** (2026-04-27) — mail: contract + console/memory/smtp/resend transports — slice 4
 - **0.1.66** (2026-04-26) — jobs (define + enqueue + in-process worker) + createApp wiring — slices 2/3
 - **0.1.65** (2026-04-26) — createApp factory — slice 1
-- **0.1.64** (2026-04-26) — forms + csrfProtect — slice 4 ( complete)
+- **0.1.64** (2026-04-26) — forms + csrfProtect — slice 4 (complete)
 - **0.1.63** (2026-04-26) — staticServe: file serving + ETag + SRI integrity — slice 3
 - **0.1.62** (2026-04-26) — render: HTTP response helpers — slice 2
 - **0.1.61** (2026-04-26) — template engine (eval-free interpreter) — slice 1
-- **0.1.60** (2026-04-26) — auth.jwt with SLH-DSA-SHAKE-256f default — slice 5/5 ( complete)
+- **0.1.60** (2026-04-26) — auth.jwt with SLH-DSA-SHAKE-256f default — slice 5/5 (complete)
 - **0.1.59** (2026-04-26) — middleware.attachUser + middleware.requireAuth — slice 4
 - **0.1.58** (2026-04-26) — auth.passkey (WebAuthn / FIDO2) — slice 3
 - **0.1.57** (2026-04-26) — TOTP defaults match spec (HMAC-SHA512 / 128-byte secret / 8 digits / 30s) + crypto.random truncation fix
@@ -221,7 +227,7 @@ upgrading across more than a few patches at a time.
 - **0.1.52** (2026-04-26) — consent_log integrity parity with audit_log (closes the cluster spec storage move)
 - **0.1.51** (2026-04-26) — queue jobs move to external-db in cluster mode
 - **0.1.50** (2026-04-26) — sessions move to external-db in cluster mode
-- **0.1.49** (2026-04-26) — boot-time vault-key consistency check (closes cluster spec phase 4)
+- **0.1.49** (2026-04-26) — boot-time vault-key consistency check (closes cluster spec)
 - **0.1.48** (2026-04-26) — boot-time audit-tip rollback detection in cluster mode
 - **0.1.47** (2026-04-26) — fix handlers.drain unbounded loop on recursive emit (cluster-mode audit hang)
 - **0.1.46** (2026-04-26) — cluster-mode audit-tip fencing-token guard
@@ -278,7 +284,7 @@ upgrading across more than a few patches at a time.
 - **0.0.18** (2026-04-26) — strip internal-process narrative from framework comments
 - **0.0.17** (2026-04-25) — internal adoption sweep + functional scale helpers
 - **0.0.16** (2026-04-25) — atomic file I/O + safe parsers (XML, CSV)
-- **0.0.15** (2026-04-25) — HTTP middleware: request lifecycle hardening ( begin)
+- **0.0.15** (2026-04-25) — HTTP middleware: request lifecycle hardening (begin)
 - **0.0.14** (2026-04-25) — external DB (Shape B: app-data-only, bring-your-own-client)
 - **0.0.13** (2026-04-25) — log streaming + redaction + bidirectional command channel
 - **0.0.12** (2026-04-25) — queue dispatcher + local SQLite-backed protocol

package/README.md

@@ -17,7 +17,7 @@ The modern Node app is a 1,200-package supply-chain liability with no LTS calend
 
 ## Status
 
-Pre-1.0. Usable end-to-end — operators can build production apps on it today; the surface is still subject to change before 1.0. Recent line is **v0.6.3** ([releases](https://github.com/blamejs/blamejs/releases) · [npm](https://www.npmjs.com/package/@blamejs/core) · [container](https://github.com/blamejs/blamejs/pkgs/container/blamejs-wiki)).
+Pre-1.0. Usable end-to-end — operators can build production apps on it today; the surface is still subject to change before 1.0. The latest release lives on [GitHub](https://github.com/blamejs/blamejs/releases), [npm](https://www.npmjs.com/package/@blamejs/core), and the [container registry](https://github.com/blamejs/blamejs/pkgs/container/blamejs-wiki).
 
 ```js
 var b = require("@blamejs/core");

package/lib/api-key.js

@@ -43,14 +43,14 @@
  * Same dual-storage pattern as sessions — local SQLite in single-node
  * mode, external-db in cluster mode, dispatched via cluster-storage.
  *
- * Validation tiers:
+ * Validation policy:
  *
- *   - apiKey.create opts                    → Tier A (throw)
- *   - registry.issue opts                   → Tier A (throw ApiKeyError)
- *   - registry.rotate(id) on missing/revoked → Tier A (throw)
- *   - registry.verify(token) on any failure → Tier C (return null)
- *   - registry.revoke(id) on missing        → Tier C (return false)
- *   - registry.getById(id) on missing       → Tier C (return null)
+ *   - apiKey.create opts                    → throw at config time
+ *   - registry.issue opts                   → throw ApiKeyError at call site
+ *   - registry.rotate(id) on missing/revoked → throw ApiKeyError at call site
+ *   - registry.verify(token) on any failure → return null (tolerant read)
+ *   - registry.revoke(id) on missing        → return false (tolerant read)
+ *   - registry.getById(id) on missing       → return null (tolerant read)
  */
 
 var crypto = require("./crypto");
@@ -69,7 +69,7 @@ var observability = lazyRequire(function () { return require("./observability");
 
 function _emitEvent(name, value, labels) {
   try { observability().event(name, value, labels || {}); }
-  catch (_e) { /* Tier B: hot-path observability sink */ }
+  catch (_e) { /* hot-path observability sink — drops silent on internal throws */ }
 }
 
 var _err = ApiKeyError.factory;
@@ -127,7 +127,7 @@ var DEFAULTS = Object.freeze({
   hashAlgo:         "shake256",
 });
 
-// ---- Tier-A validation helpers ----
+// ---- Config-time validation helpers (throw on bad input) ----
 
 function _isPositiveInt(n) {
   return typeof n === "number" && isFinite(n) && n >= 1 && Math.floor(n) === n;

package/lib/archive.js

@@ -216,11 +216,11 @@ function zip() {
   }
 
   function digest() {
-    // SHA-256 of the produced archive bytes — useful for operator-side
-    // integrity logging on exported bundles. Not vendor-locked to any
-    // particular hash; SHA-256 is universally recognized for content
-    // addressing.
-    return nodeCrypto.createHash("sha256").update(toBuffer()).digest("hex");
+    // SHA3-512 of the produced archive bytes — useful for operator-side
+    // integrity logging on exported bundles. Matches the framework's
+    // PQC-first hash posture; operators reconciling against an external
+    // SHA-256 can hash the bytes themselves.
+    return nodeCrypto.createHash("sha3-512").update(toBuffer()).digest("hex");
   }
 
   return {

package/lib/audit.js

@@ -711,8 +711,8 @@ function emit(event) {
 // audit outage doesn't crash the request handler. This is that helper,
 // hoisted out so each module can stop redefining it.
 //
-// Tier B (drop-silent): malformed input is dropped without throwing, by
-// design. safeEmit is called from request hot paths where throwing on a
+// Drop-silent on malformed input by design. safeEmit is called from
+// request hot paths where throwing on a
 // missing `action` would mean a malformed audit attempt crashes the
 // request that triggered it — strictly worse than the missing audit
 // row. Operators who need a hard guarantee the event landed should call

package/lib/auth/jwt.js

@@ -247,10 +247,10 @@ async function verify(token, opts) {
     if (typeof opts.clockToleranceSec !== "number" ||
         !isFinite(opts.clockToleranceSec) ||
         opts.clockToleranceSec < 0) {
-      // Tier-A: a negative tolerance over-tightens the window (legit
-      // tokens get rejected as expired or not-yet-valid). A non-finite
-      // value would NaN-poison the comparison. Catch both at config
-      // time rather than producing surprise rejections in production.
+      // Throw at config time: a negative tolerance over-tightens the
+      // window (legit tokens get rejected as expired or not-yet-valid)
+      // and a non-finite value would NaN-poison the comparison. Catch
+      // both here rather than producing surprise rejections in production.
       throw new AuthError("auth-jwt/bad-clock-tolerance",
         "verify: clockToleranceSec must be a non-negative finite number, got " +
         JSON.stringify(opts.clockToleranceSec));

package/lib/backup/index.js

@@ -238,6 +238,13 @@ function create(opts) {
   var flushBeforeBackup = typeof opts.flushBeforeBackup === "function"
     ? opts.flushBeforeBackup
     : (opts.flushBeforeBackup === false ? null : null);
+  // requireFlush — when true, a flush failure FAILS the backup instead
+  // of producing a (potentially stale) snapshot. Operators on
+  // encrypted-at-rest with hard freshness requirements (compliance,
+  // audit, point-in-time recovery) opt in. Default false preserves the
+  // long-standing best-effort posture for operators who care about
+  // backup completing more than freshness.
+  var requireFlush = opts.requireFlush === true;
   // Default: try b.db.flushToDisk if available. Wired this way so the
   // backup primitive doesn't take a hard dependency on b.db (operators
   // running backup against an external db handle still work).
@@ -272,15 +279,24 @@ function create(opts) {
     var stagingDir = path.join(os.tmpdir(),
       "blamejs-backup-staging-" + bundleId.replace(/[:.]/g, "-"));
 
-    // Flush the live DB to disk so the snapshot is current. Best-effort —
-    // a flush failure logs but doesn't fail the whole backup; the bundle
-    // will just snapshot whatever's on disk.
+    // Flush the live DB to disk so the snapshot is current. Default
+    // posture is best-effort — a flush failure logs but doesn't fail
+    // the whole backup. With requireFlush:true the failure aborts the
+    // backup so a stale snapshot never lands in storage.
     if (flushBeforeBackup) {
       try { await flushBeforeBackup(); }
       catch (e) {
+        var flushReason = (e && e.message) || String(e);
         _emitAudit("backup.flush.failure",
-          { bundleId: bundleId, reason: (e && e.message) || String(e) },
-          "warning");
+          { bundleId: bundleId, reason: flushReason },
+          requireFlush ? "failure" : "warning");
+        if (requireFlush) {
+          _emitAudit("backup.failure",
+            { bundleId: bundleId, reason: "flush-required-but-failed: " + flushReason },
+            "failure");
+          throw new BackupError("backup/flush-required-failed",
+            "backup flush required but failed: " + flushReason);
+        }
       }
     }
 

package/lib/break-glass.js

@@ -17,10 +17,10 @@
  *
  * Spec: memory/specs/blamejs-break-glass-spec.md
  *
- * v0.5.0 ships Model A (policy gate) + TOTP factor + Tier-A validation +
- * 14 error codes + audit chain integration. Model B (cryptographic
- * gate via per-row K_row), passkey factor, service-account bypass,
- * and admin tools land in v0.5.1 / v0.5.2 per the phasing plan.
+ * Ships Model A (policy gate) + TOTP factor + config-time input
+ * validation + 14 error codes + audit chain integration. Model B
+ * (cryptographic gate via per-row K_row), passkey factor, service-
+ * account bypass, and admin tools land in subsequent patches.
  *
  * Public API:
  *
@@ -59,8 +59,9 @@ var lockout = lazyRequire(function () { return require("./auth/lockout"); });
 var passkey = lazyRequire(function () { return require("./auth/passkey"); });
 
 // Errors — all 14 codes documented in the spec. `permanent: true`
-// means caller's input is bad (Tier-A); `permanent: false` means
-// transient (factor failed, rate-limited) — caller may retry.
+// means caller's input is bad (config-time / call-site reject);
+// `permanent: false` means transient (factor failed, rate-limited)
+// — caller may retry.
 var BreakGlassError = defineClass("BreakGlassError", { alwaysPermanent: false });
 
 // ---- Defaults (matched to operator-locked decisions) ----

package/lib/cache.js

@@ -51,14 +51,14 @@
  *   { get, set, del, clear, size, close } — operator-supplied custom
  *     backend (Redis, Memcached, …). All methods async.
  *
- * Validation tiers:
+ * Validation policy:
  *
- *   - create() opts                       → Tier A (throw at boot)
- *   - get/set/del/has/wrap key arg type   → Tier A (throw — programming bug)
- *   - set value type                      → C (operator decides what to store)
- *   - per-call ttlMs override             → Tier A (throw — bad ttl is silent footgun)
- *   - audit / observability emit failures → Tier B (drop silent)
- *   - method called after close()         → Tier A (throw BAD_STATE)
+ *   - create() opts                       → throw at boot
+ *   - get/set/del/has/wrap key arg type   → throw at call site (programming bug)
+ *   - set value type                      → tolerant (operator decides what to store)
+ *   - per-call ttlMs override             → throw at call site (bad ttl is silent footgun)
+ *   - audit / observability emit failures → drop silent (hot-path sink)
+ *   - method called after close()         → throw BAD_STATE at call site
  *
  * Security defaults:
  *
@@ -114,7 +114,7 @@ var DEFAULTS = Object.freeze({
   auditClear:              true,
 });
 
-// ---- Tier-A validation helpers ----
+// ---- Config-time validation helpers (throw on bad input) ----
 
 function _isFiniteNonNegative(n) {
   return typeof n === "number" && isFinite(n) && n >= 0;
@@ -669,7 +669,7 @@ function create(opts) {
     try {
       if (operatorObs) operatorObs.event(name, 1, labels || {});
       else observability().event(name, 1, labels || {});
-    } catch (_e) { /* Tier B: hot-path observability sink */ }
+    } catch (_e) { /* hot-path observability sink — drops silent on internal throws */ }
   }
 
   function emitAudit(action, info) {

package/lib/constants.js

@@ -18,10 +18,10 @@ var pkg = require("../package.json");
 // reader sees the unit at the call site (`C.TIME.minutes(45)` instead of
 // adding a new FORTY_FIVE_MIN constant). All return integer milliseconds.
 //
-// Tier A validation: these are config-time helpers. Throw on non-finite
-// or negative input so a typo (`C.TIME.minutes(opts.x)` where opts.x is
-// undefined) surfaces at boot instead of silently becoming `NaN` or `0`
-// and shipping a 0ms timeout into production.
+// Throw on non-finite or negative input — these are config-time helpers,
+// so a typo (`C.TIME.minutes(opts.x)` where opts.x is undefined) should
+// surface at boot instead of silently becoming `NaN` or `0` and shipping
+// a 0ms timeout into production.
 function _validateDuration(unit, n) {
   if (typeof n !== "number" || !isFinite(n) || n < 0) {
     throw new TypeError("C.TIME." + unit + ": expected non-negative finite number, got " +
@@ -42,8 +42,8 @@ var TIME = Object.freeze({
 // (KiB/MiB/GiB), since every existing byte literal in the framework
 // already uses 1024 multiplication.
 //
-// Tier A validation: same rationale as TIME — bad input surfaces at the
-// call site, not as a silent NaN cap that disables size limits.
+// Throw on bad input — same rationale as TIME: bad input surfaces at
+// the call site, not as a silent NaN cap that disables size limits.
 function _validateBytes(unit, n) {
   if (typeof n !== "number" || !isFinite(n) || n < 0) {
     throw new TypeError("C.BYTES." + unit + ": expected non-negative finite number, got " +

package/lib/credential-hash.js

@@ -61,13 +61,13 @@
  *   - Transparent rehash via needsRehash() drains old algos at the
  *     pace of organic verify traffic.
  *
- * Validation tiers:
+ * Validation policy:
  *
- *   - hash() opts (algo, params)         → Tier A (throw)
- *   - hash() secret type / length        → Tier A (throw)
- *   - verify() envelope shape unparsable → Tier C (return false)
- *   - verify() unknown algo ID           → Tier C (return false)
- *   - inspect() bad envelope             → Tier C (return null)
+ *   - hash() opts (algo, params)         → throw at call site
+ *   - hash() secret type / length        → throw at call site
+ *   - verify() envelope shape unparsable → return false (tolerant read)
+ *   - verify() unknown algo ID           → return false (tolerant read)
+ *   - inspect() bad envelope             → return null (tolerant read)
  */
 
 var crypto = require("./crypto");
@@ -79,7 +79,7 @@ var observability = lazyRequire(function () { return require("./observability");
 
 function _emitEvent(name, value, labels) {
   try { observability().event(name, value, labels || {}); }
-  catch (_e) { /* Tier B: hot-path observability sink */ }
+  catch (_e) { /* hot-path observability sink — drops silent on internal throws */ }
 }
 
 // Default SHAKE256 output size for newly-issued credentials. 128
@@ -135,7 +135,7 @@ var ID_TO_NAME = Object.freeze({
   0x02: "argon2id",
 });
 
-// ---- Tier-A validation ----
+// ---- Call-site validation (throw on bad input) ----
 
 function _validateSecret(secret) {
   if (typeof secret !== "string" && !Buffer.isBuffer(secret)) {
@@ -223,7 +223,7 @@ async function hash(secret, opts) {
 }
 
 async function verify(secret, envelope) {
-  // Tier C: any malformed input → false. Lets operators write
+  // Tolerant read: any malformed envelope → false. Lets operators write
   //   if (!await ch.verify(s, row.hash)) return res.status(401);
   // without try/catch ceremony. We still reject obvious caller bugs
   // (non-string-or-Buffer secret) loudly because that signals broken

package/lib/db-declare-view.js

@@ -39,7 +39,7 @@
  * typos surface as clear errors at the migrate command, not as silent
  * empty views or grant-to-nonexistent-role footguns.
  *
- * Tier-A validation at declareView() call time:
+ * Throw at declareView() call time on:
  *   - schema, name, source segments → safeSql.validateIdentifier
  *   - column names in redactColumns / sealedColumns / hashColumns →
  *     safeSql.validateIdentifier
@@ -303,7 +303,7 @@ function declareView(opts) {
   var qSource = safeSql.quoteQualified([spec.source.schema, spec.source.name], "postgres");
 
   async function up(xdb, ctx) {
-    // Tier-A boundary: confirm we're on Postgres before any DDL leaves the process.
+    // Boundary throw: confirm we're on Postgres before any DDL leaves the process.
     if (ctx && ctx.externalDb && ctx.backendName) {
       _ensureBackendIsPostgres(ctx.externalDb, ctx.backendName);
     }

package/lib/external-db-migrate.js

@@ -208,7 +208,7 @@ function _emit(audit, action, outcome, info, reason) {
       metadata: info || {},
       reason:   reason || null,
     });
-  } catch (_e) { /* Tier B: drop-silent */ }
+  } catch (_e) { /* drop-silent — audit emit failure must not crash the migration */ }
 }
 
 // ---- Backend resolution ----

package/lib/http-client.js

@@ -480,8 +480,8 @@ function request(opts) {
     return Promise.reject(_makeError(opts && opts.errorClass, "BAD_ARG", "url is required", true));
   }
 
-  // Validate before/after shapes early — Tier-A throw if the operator
-  // passed something un-callable so the bug surfaces at the call site
+  // Validate before/after shapes early — throw at call site if the
+  // operator passed something un-callable so the bug surfaces here
   // rather than inside the request loop.
   if (opts.before !== undefined) {
     if (!Array.isArray(opts.before) || !opts.before.every(function (f) { return typeof f === "function"; })) {
@@ -896,7 +896,7 @@ function _requestH1(transport, u, opts) {
       var bodyBuf = Buffer.isBuffer(opts.body) ? opts.body : Buffer.from(opts.body, "utf8");
       if (onUploadProgress) {
         // Chunked write so progress reports land before req.end().
-        var CHUNK = 64 * 1024;
+        var CHUNK = C.BYTES.kib(64);
         var off = 0;
         while (off < bodyBuf.length) {
           var slice = bodyBuf.slice(off, Math.min(off + CHUNK, bodyBuf.length));

package/lib/i18n.js

@@ -38,16 +38,16 @@
  *   - {var} interpolation; missing vars render as literal {var} unless
  *     `interpolation.strict: true`.
  *
- * Validation tiers:
+ * Validation policy:
  *
- *   - create() opts                           → Tier A (throw at boot)
- *   - bad locale tag at any boundary          → Tier A (throw)
- *   - t(missingKey)                           → Tier C (return key + obs)
- *   - t() with bad locale override            → Tier A (programming bug)
- *   - plural shape missing 'other'            → Tier A (throw at load)
- *   - interpolation missing var               → Tier C (literal {var})
- *   - format* bad input                       → Tier A
- *   - middleware Accept-Language parse error  → Tier C (defaultLocale)
+ *   - create() opts                           → throw at boot
+ *   - bad locale tag at any boundary          → throw at call site
+ *   - t(missingKey)                           → return key + observability event
+ *   - t() with bad locale override            → throw at call site (programming bug)
+ *   - plural shape missing 'other'            → throw at load time
+ *   - interpolation missing var               → render literal {var}
+ *   - format* bad input                       → throw at call site
+ *   - middleware Accept-Language parse error  → fall back to defaultLocale
  *
  * Security stance: translation values come from operator-controlled
  * files, not user input. {var} interpolation does NOT html-escape;
@@ -97,7 +97,7 @@ var DEFAULTS = Object.freeze({
   RTL_LANGUAGES:    RTL_LANGUAGES,
 });
 
-// ---- Tier-A validation ----
+// ---- Call-site validation (throw on bad input) ----
 
 function _isValidBcp47(tag) {
   if (typeof tag !== "string" || tag.length === 0) return false;
@@ -476,7 +476,7 @@ function create(opts) {
     try {
       if (operatorObs) operatorObs.event(name, 1, labels || {});
       else observability().event(name, 1, labels || {});
-    } catch (_e) { /* Tier B */ }
+    } catch (_e) { /* drop-silent — observability sink must not crash i18n calls */ }
   }
 
   // Cardinal plural-rules instances per locale. `Intl.PluralRules` is
@@ -721,7 +721,7 @@ function create(opts) {
       // Permit setting a non-configured locale (operators may want to
       // experiment), but fall the chain through to the configured ones.
       // Don't throw — i18n.locale is set/observed in many flows; making
-      // it Tier-A would force operators into try/catch around UI setters.
+      // this throw would force operators into try/catch around UI setters.
       _emitObs("i18n.miss.locale", { requested: newLocale, resolved: defaultLocale });
     }
     currentLocale = newLocale;

package/lib/log-stream-webhook.js

@@ -97,6 +97,19 @@ function create(config) {
     errorClass:       LogStreamError,
   });
   var headers = Object.assign({ "Content-Type": cfg.contentType }, _authHeaders(cfg));
+  // onDrop callback: invoked when a batch is dropped, either by buffer
+  // overflow ("overflow") or by retry exhaustion ("retry-exhausted").
+  // Operator wiring this directly (without the framework's dispatcher
+  // wrapping) needs visibility into permanent-drop events; the
+  // dispatcher path emits its own audit, but a sink used in isolation
+  // would otherwise lose drops silently. The callback is invoked
+  // best-effort — a throw inside it is swallowed.
+  var onDrop = typeof cfg.onDrop === "function" ? cfg.onDrop : null;
+  function _emitDrop(reason, batch, err) {
+    if (!onDrop) return;
+    try { onDrop({ reason: reason, batch: batch, error: err || null }); }
+    catch (_e) { /* drop callback is best-effort by design */ }
+  }
   var buffer = [];
   var dropCount = 0;
   var flushTimer = null;
@@ -121,9 +134,13 @@ function create(config) {
           await retryHelper.withRetry(function () {
             return _post(cfg.url, body, headers, cfg.timeoutMs, cfg.allowedProtocols, cfg.allowInternal);
           }, cfg.retry);
-        } catch {
-          // Batch permanently rejected — surface via the dropped counter.
-          // Caller's audit hook recorded the drop already at the dispatcher.
+        } catch (e) {
+          // Batch permanently rejected — surface via dropCount AND the
+          // operator-supplied onDrop callback. The dispatcher path
+          // wraps its own audit hook around emit(); operators using
+          // this sink directly rely on dropCount + onDrop.
+          dropCount += batch.length;
+          _emitDrop("retry-exhausted", batch, e);
           break;
         }
       }
@@ -136,8 +153,9 @@ function create(config) {
   function emit(record) {
     if (closed) return Promise.resolve({ accepted: false, reason: "sink closed" });
     if (buffer.length >= cfg.bufferLimit) {
-      buffer.shift();   // drop oldest
+      var dropped = buffer.shift();   // drop oldest
       dropCount += 1;
+      _emitDrop("overflow", [dropped], null);
     }
     buffer.push(record);
     if (buffer.length >= cfg.batchSize) {

package/lib/mail.js

@@ -246,6 +246,14 @@ function _toArray(v) {
 function consoleTransport(opts) {
   opts = opts || {};
   var stream = opts.stream || process.stderr;
+  // redactBcc: print only the recipient COUNT instead of the addresses.
+  // Default false preserves the dev-visibility purpose of this
+  // transport. Operators piping dev logs into shared / centralized
+  // sinks (Slack, log aggregator, ticket system) opt in to avoid
+  // leaking the BCC list — the property exists precisely so a recipient
+  // doesn't see who else got the message, and that promise breaks the
+  // moment the addresses land in a non-private log.
+  var redactBcc = opts.redactBcc === true;
   return {
     name: "console",
     send: async function (message) {
@@ -255,7 +263,14 @@ function consoleTransport(opts) {
         "[mail.console] Subject: " + (message.subject || ""),
       ];
       if (message.cc)  lines.push("[mail.console] Cc: " + (Array.isArray(message.cc)  ? message.cc.join(", ")  : message.cc));
-      if (message.bcc) lines.push("[mail.console] Bcc: " + (Array.isArray(message.bcc) ? message.bcc.join(", ") : message.bcc));
+      if (message.bcc) {
+        if (redactBcc) {
+          var bccCount = Array.isArray(message.bcc) ? message.bcc.length : 1;
+          lines.push("[mail.console] Bcc: <" + bccCount + " recipient" + (bccCount === 1 ? "" : "s") + " — redacted>");
+        } else {
+          lines.push("[mail.console] Bcc: " + (Array.isArray(message.bcc) ? message.bcc.join(", ") : message.bcc));
+        }
+      }
       var body = message.text || (message.html ? "(html body, " + message.html.length + " bytes)" : "");
       lines.push("");
       lines.push(body);

package/lib/middleware/body-parser.js

@@ -1041,8 +1041,40 @@ async function _parseJsonFromBuf(buf, opts) {
   return parsed;
 }
 
+// raw — convenience wrapper that returns a middleware which buffers
+// the request body as a Buffer regardless of Content-Type. Webhook
+// signature-verification routes use this — the HMAC is computed over
+// the literal body bytes, so JSON-parsing first would change them.
+//
+//   router.post("/hooks/in", b.middleware.bodyParser.raw(), function (req, res) {
+//     verifier.verify(req.headers["x-signature"], req.body);  // req.body is a Buffer
+//   });
+//
+// Accepts the same `raw`-section opts as create() (limit, contentTypes).
+// contentTypes default expands to `["*/*"]` so any Content-Type lands
+// as raw bytes.
+function raw(opts) {
+  opts = opts || {};
+  return create({
+    json:        false,
+    urlencoded:  false,
+    text:        false,
+    multipart:   false,
+    raw: {
+      limit:        opts.limit != null ? opts.limit : DEFAULTS.raw.limit,
+      contentTypes: opts.contentTypes || ["*/*"],
+    },
+  });
+}
+
+// Attach raw onto create so b.middleware.bodyParser.raw() works
+// (middleware/index.js exports the create function as the namespace
+// itself, so static helpers hang off it).
+create.raw = raw;
+
 module.exports = {
   create:           create,
+  raw:              raw,
   BodyParserError:  BodyParserError,
   // Internal helpers exposed for tests + the csrf-protect refactor.
   _contentType:     _contentType,

package/lib/middleware/cors.js

@@ -191,7 +191,7 @@ function create(opts) {
     }
   }
 
-  // Tier A validation on opts.siteOrigin — must parse as http(s) URL.
+  // Throw at create() on bad opts.siteOrigin — must parse as http(s) URL.
   // Accept string OR array of strings.
   var siteOrigins = [];
   if (opts.siteOrigin !== undefined && opts.siteOrigin !== null) {