@blamejs/core 0.8.43 → 0.8.49

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

@@ -24,15 +24,9 @@
  *   });
  *   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.
+ * The middleware composes b.network.byteQuota — handlers that already
+ * know the byte cost of an op call b.network.byteQuota.check / record
+ * directly without going through the middleware lifecycle.
  *
  * Failure modes:
  *   - cache backend unreachable → fail-open (count drops, request
@@ -45,6 +39,7 @@
 var C = require("../constants");
 var defineClass = require("../framework-error").defineClass;
 var lazyRequire = require("../lazy-require");
+var networkByteQuota = require("../network-byte-quota");
 var validateOpts = require("../validate-opts");
 
 var audit = lazyRequire(function () { return require("../audit"); });
@@ -53,9 +48,6 @@ var requestHelpers = lazyRequire(function () { return require("../request-helper
 
 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
@@ -64,73 +56,40 @@ 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 });
-    },
-  };
-}
-
+/**
+ * @primitive b.middleware.dailyByteQuota
+ * @signature b.middleware.dailyByteQuota(opts)
+ * @since     0.1.0
+ * @related   b.middleware.rateLimit
+ *
+ * Per-IP rolling 24-hour byte budget. Tracks request + response
+ * bytes per peer key (default: client IP). When a peer exceeds the
+ * configured quota, further requests are refused with HTTP 429 +
+ * `Retry-After`. The window slides per-second — a peer can't reset
+ * by waiting past midnight. Composes `b.network.byteQuota`; handlers
+ * that already know the byte cost of an op can call
+ * `b.network.byteQuota.check`/`record` directly. Fails open (request
+ * proceeds, audit emitted) when the backing cache is unreachable.
+ *
+ * @opts
+ *   {
+ *     bytesPerDay: number,                            // required, positive, finite
+ *     getKey:      function(req): string|null,        // default: req client IP
+ *     cache:       object,                            // null = in-memory single-node
+ *     onExceeded:  function(req, res, info): void,
+ *     skipPaths:   string[],
+ *     now:         function(): number,
+ *     audit:       boolean,                           // default true
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.dailyByteQuota({
+ *     bytesPerDay: b.constants.BYTES.gib(2),
+ *     skipPaths:   ["/healthz"],
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
@@ -149,9 +108,17 @@ function create(opts) {
   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();
+
+  // Compose the standalone primitive — the middleware drives the same
+  // counter store the operator-facing b.network.byteQuota.check /
+  // record API exposes. No parallel byte-counter implementation.
+  var quota = networkByteQuota.create({
+    bytesPerDay: bytesPerDay,
+    cache:       opts.cache || null,
+    audit:       false,                                                                // middleware emits its own per-rejection audits
+    now:         now,
+  });
+  var backend = quota._backend;
 
   function _shouldSkip(req) {
     if (skipPaths.length === 0) return false;
@@ -204,7 +171,7 @@ function create(opts) {
       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))),
+        retryAfterSec:   Math.ceil(C.TIME.hours(1) / C.TIME.seconds(1)),
       };
       if (onExceeded) {
         try { return onExceeded(req, res, info); }
@@ -270,6 +237,7 @@ function create(opts) {
 module.exports = {
   create:                 create,
   DailyByteQuotaError:    DailyByteQuotaError,
-  _memoryBackend:         _memoryBackend,                                                // exported for tests
-  BINS_PER_DAY:           BINS_PER_DAY,
+  BINS_PER_DAY:           networkByteQuota.BINS_PER_DAY,
+  // Backward-compat re-export for tests that mocked the in-process backend.
+  _memoryBackend:         networkByteQuota._memoryBackend,
 };

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

@@ -107,6 +107,46 @@ function _defaultResponder(req, res, status, info) {
   res.end(JSON.stringify(info));
 }
 
+/**
+ * @primitive b.middleware.dbRoleFor
+ * @signature b.middleware.dbRoleFor(opts)
+ * @since     0.1.0
+ * @related   b.middleware.attachUser, b.externalDb.query
+ *
+ * Binds a request-time database role into AsyncLocalStorage so
+ * `b.externalDb.query` / `read` / `write` / `transaction` auto-route
+ * to the matching backend (`app_user`, `analytics_user`, etc.) without
+ * any operator threading of the role through the handler signature.
+ * Resolution order: operator-supplied `resolve(req)` → permissions
+ * RBAC `dbRoleFor` → `defaultRole` → null. Throws at create-time on
+ * bad opts (resolver/responder shape, malformed default-role
+ * identifier, out-of-range missing-role status). Runtime returns
+ * are validated against `safeSql.validateIdentifier` — a garbage
+ * resolver return surfaces as next(err), not silent fallthrough.
+ * Emits `db.role.switched` audit + `db.role.bound` observability.
+ *
+ * @opts
+ *   {
+ *     resolve:           function(req): string|null,
+ *     permissions:       object,           // b.permissions instance
+ *     defaultRole:       string,
+ *     requireRole:       boolean,
+ *     missingRoleStatus: number,           // default 401
+ *     responder:         function(req, res, status, info): void,
+ *     audit:             object,
+ *     auditFailures:     boolean,          // default true
+ *     auditSuccess:      boolean,          // default true
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.attachUser({ userLoader: async function () { return { id: 1 }; } }));
+ *   app.use(b.middleware.dbRoleFor({
+ *     defaultRole: "app_user",
+ *     resolve:     function (req) { return req.user && req.user.dbRole; },
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, ALLOWED_OPTS, "middleware.dbRoleFor");

package/lib/middleware/dpop.js

@@ -117,6 +117,46 @@ function _reconstructHtu(req) {
   return proto + "://" + host + path;
 }
 
+/**
+ * @primitive b.middleware.dpop
+ * @signature b.middleware.dpop(opts)
+ * @since     0.1.0
+ * @related   b.middleware.bearerAuth, b.auth.jwt
+ *
+ * RFC 9449 Demonstrating Proof of Possession (DPoP). Verifies the
+ * `DPoP` header on inbound requests, attaches `req.dpop = { header,
+ * payload, jkt }` for downstream handlers to bind to the access
+ * token's `cnf.jkt` claim, and refuses with HTTP 401 +
+ * `WWW-Authenticate: DPoP error="invalid_dpop_proof"` on any
+ * failure. Replay store enforces single-use proofs within
+ * `iatWindowSec`. Optional server-issued nonce (RFC 9449 §8) with
+ * `requireNonce: true` rotates a current/previous pair lazily so
+ * in-flight clients aren't kicked off at rotation. Algorithm
+ * allowlist defaults to ES256 / EdDSA / ML-DSA-87 (PQC-first).
+ *
+ * @opts
+ *   {
+ *     replayStore:    object,                      // required
+ *     algorithms:     string[],                    // default ES256/EdDSA/ML-DSA-87
+ *     iatWindowSec:   number,                      // default 60
+ *     getAccessToken: function(req): string|null,
+ *     getNonce:       async function(req): string|null,
+ *     getHtu:         function(req): string,
+ *     nonceStore:     object,
+ *     nonceWindowSec: number,
+ *     nonceRotateSec: number,
+ *     requireNonce:   boolean,
+ *     audit:          boolean,                      // default true
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use("/api", b.middleware.dpop({
+ *     replayStore:  b.nonceStore.create({ backend: "memory" }),
+ *     iatWindowSec: 60,
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/error-handler.js

@@ -1,24 +1,47 @@
 "use strict";
 /**
- * Error-handler middleware — thin adapter over lib/errors-page.
+ * Error-handler middleware — thin adapter over lib/error-page.
  *
  * Use this for the standard wiring path (`router.onError(b.middleware.
- * errorHandler())`). Constructs an errors-page handler and forwards
- * the (err, req, res, next) router signature into it. All classification,
- * rendering, content negotiation, dev/prod gating, and audit emission
- * lives in lib/errors-page — this file only wires the middleware
- * convention plus the audit-action override that preserves the
- * 'system.http.error' action name the framework's audit log already
- * uses for HTTP-layer failures.
- *
- * Options forward to errors-page.create with one default override:
- *   auditAction:        "system.http.error"   (vs errors-page default "request.error")
- *
- * Plus a back-compat alias:
- *   exposeStackInDev:   forwards to opts.showStack (true|false)
+ * errorHandler())`). Constructs an error-page handler and forwards
+ * the (err, req, res, next) router signature into it. Classification,
+ * rendering, content negotiation, dev/prod gating, and audit
+ * emission all live in `b.errorPage` — this file only wires the
+ * router middleware convention plus the audit-action override that
+ * preserves the `system.http.error` action name the framework's
+ * audit log already uses for HTTP-layer failures.
  */
 var errorPage = require("../error-page");
 
+/**
+ * @primitive b.middleware.errorHandler
+ * @signature b.middleware.errorHandler(err, req, res, next)
+ * @since     0.1.0
+ * @related   b.errorPage.create
+ *
+ * Thin adapter over `lib/error-page`. Constructed via the factory
+ * call `b.middleware.errorHandler(opts)`; the resulting middleware
+ * has the `(err, req, res, next)` shape shown above. Forwards the
+ * router signature into an errors-page handler.
+ * Classification, rendering, content negotiation, and audit emission
+ * live in `b.errorPage`; this middleware only sets the audit action
+ * to `system.http.error` and defaults to JSON output (page-style
+ * HTML negotiation is reachable via `b.errorPage.create` directly).
+ *
+ * @opts
+ *   {
+ *     auditAction:      string,             // default "system.http.error"
+ *     defaultFormat:    "json"|"html"|"auto",// default "json"
+ *     showStack:        boolean,            // dev-stack exposure
+ *     exposeStackInDev: boolean,            // back-compat alias for showStack
+ *     // ...all other b.errorPage.create opts forward unchanged
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.onError(b.middleware.errorHandler({ showStack: false }));
+ */
 function create(opts) {
   opts = opts || {};
   var pageOpts = Object.assign({}, opts);

package/lib/middleware/fetch-metadata.js

@@ -52,6 +52,45 @@ function _writeReject(res, message) {
   res.end(body);
 }
 
+/**
+ * @primitive b.middleware.fetchMetadata
+ * @signature b.middleware.fetchMetadata(req, res, next)
+ * @since     0.1.0
+ * @related   b.middleware.cors, b.middleware.csrfProtect
+ *
+ * Resource Isolation Policy enforced via Sec-Fetch-Site / -Mode /
+ * -Dest. Constructed via `b.middleware.fetchMetadata(opts)`; the
+ * resulting middleware has the `(req, res, next)` shape shown above. Refuses cross-site requests on state-changing methods
+ * unless the operator allowlists them — second-line defense
+ * alongside CSRF tokens. Same-origin / same-site requests pass
+ * through. Cross-site is refused with HTTP 403 unless `allowedDest`
+ * contains the request's `Sec-Fetch-Dest`. Legacy browsers without
+ * Sec-Fetch-* default to `allowMissing: true` so the gate doesn't
+ * break older clients — the browser-fetch-metadata isolation IS
+ * the value-add; non-browser callers carry their own auth threat
+ * model.
+ *
+ * @opts
+ *   {
+ *     allowSameSite:   boolean,    // default true
+ *     allowCrossSite:  boolean,    // default false
+ *     allowMissing:    boolean,    // default true
+ *     allowedDest:     string[],
+ *     allowedNavigate: boolean,    // default true
+ *     methods:         string[],   // default POST/PUT/DELETE/PATCH
+ *     audit:           boolean,    // default true
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use("/api", b.middleware.fetchMetadata({
+ *     allowSameSite:   true,
+ *     allowCrossSite:  false,
+ *     allowedDest:     ["empty", "document"],
+ *     allowedNavigate: true,
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/flag-context.js

@@ -30,6 +30,40 @@ var FlagError = defineClass("FlagError", { alwaysPermanent: true });
 
 var contextMod = lazyRequire(function () { return require("../flag-evaluation-context"); });
 
+/**
+ * @primitive b.middleware.flagContext
+ * @signature b.middleware.flagContext(opts)
+ * @since     0.1.0
+ * @related   b.flagClient.getBoolean
+ *
+ * Extracts an OpenFeature evaluation context onto `req.flagCtx` so
+ * downstream handlers and multiple flag clients read a consistent
+ * context without re-deriving it per call. The middleware itself
+ * does NOT evaluate flags — pair with `flag.middleware()` for the
+ * request-attached accessor, or pass `req.flagCtx` directly to a
+ * flag client method when several clients with different providers
+ * share the same context. `userKey` (literal) takes precedence over
+ * `userKeyHeader`; `tenantKeyHeader` augments with tenantId; the
+ * operator-supplied `extractAttributes(req)` adds arbitrary fields.
+ *
+ * @opts
+ *   {
+ *     userKey:           string,
+ *     userKeyHeader:     string,
+ *     tenantKeyHeader:   string,
+ *     extractAttributes: function(req): object,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.flagContext({
+ *     userKeyHeader:    "x-user-id",
+ *     extractAttributes: function (req) {
+ *       return { environment: "prod" };
+ *     },
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/gpc.js

@@ -68,6 +68,39 @@ function _emitAudit(audit, action, outcome, metadata) {
   } catch (_e) { /* drop-silent */ }
 }
 
+/**
+ * @primitive b.middleware.gpc
+ * @signature b.middleware.gpc(opts)
+ * @since     0.1.0
+ * @compliance ccpa, modpa
+ * @related   b.middleware.cookies
+ *
+ * Sec-GPC (Global Privacy Control) handler. Reads the `Sec-GPC: 1`
+ * inbound header and sets `req.gpcOptOut = true` for downstream
+ * consumers. Echoes `Sec-GPC-Status: honored` so the UA + auditors
+ * see the acknowledgement. Honoring Sec-GPC is legally required in
+ * California (CCPA/CPRA) and a growing list of US states; operators
+ * who don't process the listed purposes (`sale`, `share`,
+ * `targeted-ads`, `cross-context-behavioral-advertising`,
+ * `profiling`) still emit the acknowledgement so audits trace.
+ * Optional `consent` integration auto-records purpose withdrawal.
+ *
+ * @opts
+ *   {
+ *     mode:         "enforce"|"audit-only",   // default "enforce"
+ *     consent:      object,                    // b.consent instance
+ *     statusHeader: boolean,                   // default true
+ *     audit:        object,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.gpc({ mode: "enforce" }));
+ *   app.get("/api/data", function (req, res) {
+ *     res.end(req.gpcOptOut ? "minimal" : "full");
+ *   });
+ */
 function create(opts) {
   opts = opts || {};
   var mode = opts.mode || "enforce";

package/lib/middleware/headers.js

@@ -159,6 +159,41 @@ function _detectIssues(headers, opts) {
   return issues;
 }
 
+/**
+ * @primitive b.middleware.headers
+ * @signature b.middleware.headers(opts)
+ * @since     0.1.0
+ * @related   b.middleware.cookies, b.middleware.bodyParser
+ *
+ * Inbound HTTP header threat detection. Validates header names
+ * against the RFC 9110 §5.1 token grammar and surfaces CRLF
+ * injection, RFC 9112 §6.1 CL+TE request-smuggling shapes, multiple
+ * `Content-Length` / `Transfer-Encoding` values, oversize header
+ * count / value, and deprecated `X-Forwarded-*` patterns when the
+ * operator hasn't opted into `trustProxy`. In `mode: "enforce"`
+ * (default) high-severity issues refuse with HTTP 400 + `Connection:
+ * close`; `audit-only` and `log-only` pass through but still emit
+ * audits.
+ *
+ * @opts
+ *   {
+ *     mode:           "enforce"|"audit-only"|"log-only",  // default "enforce"
+ *     refuseOnHigh:   boolean,    // default true (enforce only)
+ *     maxHeaderCount: number,     // default 100
+ *     maxValueBytes:  number,     // default 8 KiB
+ *     trustProxy:     boolean,
+ *     audit:          object,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.headers({
+ *     mode:           "enforce",
+ *     maxHeaderCount: 100,
+ *     maxValueBytes:  b.constants.BYTES.kib(8),
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   var mode = opts.mode || "enforce";

package/lib/middleware/health.js

@@ -115,6 +115,52 @@ var TIER_SET = new Set(TIERS);
 
 var DEFAULT_TIMEOUT_MS = C.TIME.seconds(5);
 
+/**
+ * @primitive b.middleware.health
+ * @signature b.middleware.health(req, res, next)
+ * @since     0.1.0
+ * @related   b.middleware.requestId
+ *
+ * Liveness / readiness / startup probe primitive. Constructed via
+ * `b.middleware.health(opts)` returning a controller exposing
+ * `registerCheck`, `markShuttingDown`, and `middleware()`; the
+ * `middleware()` value has the `(req, res, next)` shape shown above. Three tiers, each
+ * its own URL path: `/healthz` (process alive — orchestrator kill
+ * decision), `/readyz` (can serve traffic — LB route decision),
+ * `/startupz` (slow-init complete — Kubernetes startupProbe).
+ * `markShuttingDown()` flips ONLY readiness to 503 so LBs drain
+ * while `/healthz` keeps responding 200 through clean exit.
+ * Detail level defaults to "minimal" (`{ status }` only — no
+ * internal-state leakage); `detailLevel: "detailed"` and
+ * `detailPredicate(req)` gate the full per-check breakdown to
+ * authed endpoints. Per-check `Promise.all` + `withTimeout` so one
+ * stuck check can't block the others. Returns a controller exposing
+ * `registerCheck`, `markShuttingDown`, and `middleware()`.
+ *
+ * @opts
+ *   {
+ *     livenessPath:     string,    // default "/healthz"
+ *     readinessPath:    string,    // default "/readyz"
+ *     startupPath:      string,    // default "/startupz"
+ *     detailLevel:      "minimal"|"detailed",   // default "minimal"
+ *     detailPredicate:  function(req): boolean,
+ *     defaultTimeoutMs: number,    // default 5000
+ *     cacheMs:          number,    // default 0
+ *     includeMeta:      boolean,
+ *     version:          string,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   var hc = b.middleware.health({
+ *     livenessPath:    "/healthz",
+ *     readinessPath:   "/readyz",
+ *     defaultTimeoutMs: 5000,
+ *   });
+ *   hc.registerCheck("db", async function () { return { ok: true }; }, { tier: "readiness" });
+ *   app.use(hc.middleware());
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/host-allowlist.js

@@ -81,6 +81,36 @@ function _matches(entry, actual) {
   return false;
 }
 
+/**
+ * @primitive b.middleware.hostAllowlist
+ * @signature b.middleware.hostAllowlist(opts)
+ * @since     0.1.0
+ * @related   b.middleware.networkAllowlist, b.middleware.cors
+ *
+ * DNS-rebinding defense. Refuses requests whose `Host` header
+ * doesn't match the operator-supplied allowlist. Wildcard-leading
+ * entries (`*.example.com`) match a single label. Entries without
+ * a port match any port. Refuses with HTTP 421 (Misdirected
+ * Request) by default. Operators behind a CDN that rewrites the
+ * Host set `hosts` to the post-rewrite values. Skip entirely for
+ * services that serve arbitrary subdomains by design (anyone-can-
+ * host-the-domain shapes).
+ *
+ * @opts
+ *   {
+ *     hosts:      string[],   // required, non-empty
+ *     denyStatus: number,     // default 421
+ *     denyBody:   string,
+ *     audit:      boolean,    // default true
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.hostAllowlist({
+ *     hosts: ["app.example.com", "*.example.com"],
+ *   }));
+ */
 function create(opts) {
   validateOpts.requireObject(opts, "middleware.hostAllowlist", HostAllowlistError);
   validateOpts(opts, [

package/lib/middleware/network-allowlist.js

@@ -71,6 +71,44 @@ function _validateCidr(cidr) {
   catch (_e) { return false; }
 }
 
+/**
+ * @primitive b.middleware.networkAllowlist
+ * @signature b.middleware.networkAllowlist(req, res, next)
+ * @since     0.1.0
+ * @related   b.middleware.hostAllowlist, b.middleware.requireAuth
+ *
+ * In-process CIDR fence for path-scoped admin gates. Constructed
+ * via `b.middleware.networkAllowlist(opts)`; the resulting
+ * middleware has the `(req, res, next)` shape shown above. Path-based
+ * authorization prevents unauthorized USERS from reaching sensitive
+ * routes; this middleware adds a NETWORK-layer fence so a credential
+ * leak doesn't compromise the gate. Path-scoped — requests outside
+ * the configured prefixes pass through hot-path-cheap. Resolves
+ * client IP via `b.requestHelpers.clientIp` (with `trustProxy`),
+ * checks against the CIDR allowlist via `b.ssrfGuard.cidrContains`,
+ * and refuses misses with HTTP 404 by default (hides the gate from
+ * probes). Throws at create-time on malformed opts.
+ *
+ * @opts
+ *   {
+ *     paths:        string[],   // pathname prefixes, required
+ *     allowedCidrs: string[],   // required
+ *     deniedCidrs:  string[],
+ *     trustProxy:   boolean,    // default false
+ *     denyStatus:   number,     // default 404
+ *     denyBody:     string,     // default "Not Found"
+ *     audit:        object,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.networkAllowlist({
+ *     paths:        ["/admin"],
+ *     allowedCidrs: ["10.0.0.0/8", "::1/128"],
+ *     trustProxy:   true,
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [