@blamejs/core 0.8.43 → 0.8.49

package/lib/middleware/openapi-serve.js

@@ -34,6 +34,40 @@ var OpenApiError = defineClass("OpenApiError", { alwaysPermanent: true });
 var openapiYaml   = lazyRequire(function () { return require("../openapi-yaml"); });
 var audit         = lazyRequire(function () { return require("../audit"); });
 
+/**
+ * @primitive b.middleware.openapiServe
+ * @signature b.middleware.openapiServe(opts)
+ * @since     0.1.0
+ * @related   b.middleware.asyncapiServe, b.openapi.create
+ *
+ * Serves an OpenAPI 3.1 document built via `b.openapi.create` at a
+ * configurable JSON + YAML mount point. GET/HEAD only; everything
+ * else falls through. SHA3-512 ETag enables conditional 304. With
+ * `accessControl: "public"` (default) emits
+ * `Access-Control-Allow-Origin: *` so external doc tooling can
+ * fetch; `same-origin` omits the CORS header for internal-only docs.
+ *
+ * @opts
+ *   {
+ *     document:      object,    // builder from b.openapi.create()
+ *     pathJson:      string,    // default "/openapi.json"
+ *     pathYaml:      string,    // default "/openapi.yaml"
+ *     pretty:        boolean,
+ *     cacheControl:  string,    // default "public, max-age=300"
+ *     accessControl: "public"|"same-origin"|{ allowOrigin: string },
+ *     audit:         boolean,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   var doc = b.openapi.create({ title: "api", version: "1.0.0" });
+ *   app.use(b.middleware.openapiServe({
+ *     document:     doc,
+ *     pretty:       true,
+ *     cacheControl: "public, max-age=300",
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/rate-limit.js

@@ -3,20 +3,27 @@
  * Rate-limit middleware — pluggable backend, default in-memory.
  *
  * Per-IP by default; key extractor is configurable (per-user, per-API-key,
- * per-route). Two built-in backends:
+ * per-route). Two built-in backends, two in-memory algorithms:
  *
- *   - 'memory' (default) — token-bucket, in-process. Each key gets
- *     `burst` tokens up front; tokens refill at `refillPerSecond`;
- *     each request costs 1 token. Single-process accuracy only.
+ *   - 'memory' (default) — in-process counter. The `algorithm` opt
+ *     selects the shape:
+ *       'token-bucket' (default) — each key gets `burst` tokens up
+ *         front; tokens refill at `refillPerSecond`; each request
+ *         costs 1 token. Smooths bursty traffic.
+ *       'fixed-window' — per-key counter resets at the start of each
+ *         window (`windowMs`); allow up to `max` per window. Matches
+ *         the cluster backend's algorithm without an SQL hop. Cheaper
+ *         per request than token-bucket; tradeoff is the boundary
+ *         burst at window edges (worst case 2*max in 1*windowMs).
  *
  *   - 'cluster' — fixed-window counter shared across the cluster
  *     via `_blamejs_rate_limit_counters`. Atomic INSERT...ON CONFLICT
  *     increments per key within a window and rolls over when the
  *     window advances. Multi-process / multi-node accurate.
  *
- *     Cluster opt-in switches the algorithm shape from token-bucket
- *     to fixed-window because that's what models cleanly in SQL —
- *     the operator-facing config keys change accordingly.
+ *     Cluster opt-in implies fixed-window because that's what models
+ *     cleanly in SQL — the operator-facing config keys for the
+ *     cluster backend match the fixed-window memory shape.
  *
  * Operators can also pass a custom `{ take, reset }` object as the
  * backend for Redis / Memcached / etc.
@@ -30,15 +37,21 @@
  *     skipPaths:       []                      // string-prefix or regex matchers
  *     scope:           'global' | 'per-route'  (default 'global')
  *     backend:         'memory' (default) | 'cluster' | { take, reset, gc? }
+ *     algorithm:       'token-bucket' (default) | 'fixed-window'
+ *                                              // memory backend only; ignored
+ *                                              // for cluster backend (which is
+ *                                              // always fixed-window) and custom
+ *                                              // backend objects (operator decides)
  *
- *     // Memory-backend tuning (token bucket):
+ *     // Memory backend, token-bucket algorithm:
  *     burst:           60                       // initial token bucket size
  *     refillPerSecond: 10                       // sustained throughput
  *
- *     // Cluster-backend tuning (fixed window):
- *     limit:           60                       // max requests per window
+ *     // Memory backend, fixed-window algorithm + cluster backend:
+ *     max:             60                       // max requests per window (memory only)
+ *     limit:           60                       // alias of `max` (cluster backend uses this name)
  *     windowMs:        C.TIME.minutes(1)        // window duration
- *     pruneIntervalMs: C.TIME.minutes(5)        // how often the leader prunes expired rows
+ *     pruneIntervalMs: C.TIME.minutes(5)        // cluster: how often the leader prunes expired rows
  *   }
  *
  * Audit: every limit hit emits system.ratelimit.block with the key + path.
@@ -74,9 +87,25 @@ function _requirePositiveNumber(name, value) {
   }
 }
 
-// ---- Memory backend (token bucket) ----
+// ---- Memory backend ----
+//
+// `algorithm: "token-bucket"` (default) — smoothed throughput.
+// `algorithm: "fixed-window"` — per-key counter resets at the start of
+//                                each window. Boundary-burst tradeoff
+//                                in exchange for matching the cluster
+//                                backend's shape without an SQL hop.
 
 function _memoryBackend(opts) {
+  var algorithm = opts.algorithm || "token-bucket";
+  if (algorithm !== "token-bucket" && algorithm !== "fixed-window") {
+    throw new Error("middleware.rateLimit: algorithm must be 'token-bucket' or 'fixed-window', got " +
+      JSON.stringify(algorithm));
+  }
+  if (algorithm === "fixed-window") return _memoryFixedWindowBackend(opts);
+  return _memoryTokenBucketBackend(opts);
+}
+
+function _memoryTokenBucketBackend(opts) {
   // Default 1-per-second tokens fully refilled in 1 minute = 60 tokens.
   var burst = opts.burst != null ? opts.burst : C.TIME.minutes(1) / C.TIME.seconds(1);
   var refillPerSecond = opts.refillPerSecond != null ? opts.refillPerSecond : 10;
@@ -138,6 +167,71 @@ function _memoryBackend(opts) {
   return { take: take, reset: reset, close: close };
 }
 
+// Fixed-window in-memory algorithm — per-key counter that resets at the
+// start of each window. Same shape as the cluster backend but without
+// the SQL hop, so single-process apps that want fixed-window semantics
+// (e.g. matching a cluster-backend deploy in dev) avoid setting up a DB.
+function _memoryFixedWindowBackend(opts) {
+  // `max` is the memory-fixed-window operator-facing name. `limit` is
+  // accepted as an alias so a config can switch from the cluster
+  // backend to memory + fixed-window without renaming opts.
+  var max = opts.max != null ? opts.max
+          : opts.limit != null ? opts.limit
+          : C.TIME.minutes(1) / C.TIME.seconds(1);
+  var windowMs = opts.windowMs != null ? opts.windowMs : C.TIME.minutes(1);
+  _requirePositiveNumber("max", max);
+  _requirePositiveNumber("windowMs", windowMs);
+
+  var counters = new Map();
+
+  // Periodic GC of stale counters so the map doesn't grow unbounded.
+  var gcInterval = safeAsync.repeating(function () {
+    var now = Date.now();
+    for (var k of counters.keys()) {
+      var c = counters.get(k);
+      if (c.windowStart + windowMs * 2 < now) counters.delete(k);
+    }
+  }, C.TIME.minutes(5), { name: "rate-limit-fixed-window-gc" });
+
+  // Synchronous take — same hot-path shape as the token-bucket backend
+  // so the middleware doesn't pay a microtask cost when memory-fixed
+  // is selected.
+  function take(key, _cost) {
+    var now = Date.now();
+    var windowStart = Math.floor(now / windowMs) * windowMs;
+    var c = counters.get(key);
+    if (!c || c.windowStart !== windowStart) {
+      c = { windowStart: windowStart, count: 0 };
+      counters.set(key, c);
+    }
+    c.count += 1;
+    if (c.count <= max) {
+      return {
+        allowed:    true,
+        limit:      max,
+        remaining:  Math.max(0, max - c.count),
+        retryAfter: 0,
+      };
+    }
+    var retryMs = (windowStart + windowMs) - now;
+    return {
+      allowed:    false,
+      limit:      max,
+      remaining:  0,
+      retryAfter: Math.max(1, Math.ceil(retryMs / C.TIME.seconds(1))),
+    };
+  }
+
+  function reset(key) { counters.delete(key); }
+
+  function close() {
+    try { gcInterval.stop(); } catch (_e) { /* timer already stopped */ }
+    counters.clear();
+  }
+
+  return { take: take, reset: reset, close: close };
+}
+
 // ---- Cluster backend (fixed-window counter, SQL-backed) ----
 
 function _clusterBackend(opts) {
@@ -241,15 +335,61 @@ function _resolveBackend(opts) {
                   "' (must be 'memory', 'cluster', or { take, reset })");
 }
 
+/**
+ * @primitive b.middleware.rateLimit
+ * @signature b.middleware.rateLimit(req, res, next)
+ * @since     0.1.0
+ * @related   b.middleware.dailyByteQuota, b.middleware.botGuard
+ *
+ * Pluggable-backend rate limiter. Constructed via
+ * `b.middleware.rateLimit(opts)`; the resulting middleware has the
+ * `(req, res, next)` shape shown above. Default `memory` backend offers
+ * `token-bucket` (smooths bursts) and `fixed-window` algorithms;
+ * `cluster` backend uses `_blamejs_rate_limit_counters` for
+ * multi-node accurate fixed-window counts. Operators bring their
+ * own `{ take, reset }` for Redis / Memcached. Per-IP by default;
+ * `keyFn(req)` overrides for per-user / per-API-key / per-route.
+ * Refuses with HTTP 429 + `X-RateLimit-*` headers and emits
+ * `system.ratelimit.block` audit on every hit.
+ *
+ * @opts
+ *   {
+ *     keyFn:           function(req): string,
+ *     statusOnLimit:   number,           // default 429
+ *     bodyOnLimit:     string,           // default "Too Many Requests"
+ *     header:          boolean,          // default true
+ *     skipPaths:       Array<string|RegExp>,
+ *     scope:           "global"|"per-route",
+ *     backend:         "memory"|"cluster"|{ take, reset, gc },
+ *     algorithm:       "token-bucket"|"fixed-window",
+ *     burst:           number,
+ *     refillPerSecond: number,
+ *     max:             number,
+ *     limit:           number,
+ *     windowMs:        number,
+ *     pruneIntervalMs: number,
+ *     trustProxy:      boolean|number,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.rateLimit({
+ *     backend:         "memory",
+ *     algorithm:       "token-bucket",
+ *     burst:           60,
+ *     refillPerSecond: 10,
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
     "keyFn", "statusOnLimit", "bodyOnLimit", "header", "skipPaths", "scope",
-    "backend", "trustProxy",
-    // memory backend
+    "backend", "trustProxy", "algorithm",
+    // memory backend (token-bucket)
     "burst", "refillPerSecond",
-    // cluster backend
-    "limit", "windowMs", "pruneIntervalMs",
+    // memory backend (fixed-window) + cluster backend
+    "max", "limit", "windowMs", "pruneIntervalMs",
   ], "middleware.rateLimit");
   var trustProxy = opts.trustProxy === true || typeof opts.trustProxy === "number"
     ? opts.trustProxy : false;
@@ -353,6 +493,8 @@ function create(opts) {
 module.exports = {
   create:           create,
   // Backends exported for tests + advanced operator wiring.
-  _memoryBackend:   _memoryBackend,
-  _clusterBackend:  _clusterBackend,
+  _memoryBackend:              _memoryBackend,
+  _memoryTokenBucketBackend:   _memoryTokenBucketBackend,
+  _memoryFixedWindowBackend:   _memoryFixedWindowBackend,
+  _clusterBackend:             _clusterBackend,
 };

package/lib/middleware/request-id.js

@@ -1,23 +1,9 @@
 "use strict";
 /**
- * Request-ID middleware. Propagates an existing X-Request-Id header (or
- * trace ID from upstream) when present and well-formed; otherwise
- * generates a fresh 32-hex value. Sets req.requestId AND emits the same
- * value as a response header so downstream services + auditors can
- * correlate.
- *
- * Threading the request ID into audit.record() metadata is what makes
- * the cross-event correlation traceable; apps should pass this through
- * to every audit.record() they call within the request lifecycle.
- *
- * Options:
- *   {
- *     headerName:    'X-Request-Id'
- *     trustUpstream: true         // propagate upstream id if it matches
- *                                 //   the format check; false → always
- *                                 //   generate fresh
- *     formatRegex:   /^[A-Za-z0-9._-]{8,128}$/
- *   }
+ * Request-ID middleware. Propagates an existing X-Request-Id header
+ * when present and well-formed; otherwise generates a fresh 32-hex
+ * value. Sets req.requestId AND emits the same value as a response
+ * header so downstream services + auditors can correlate.
  */
 var C = require("../constants");
 var { generateToken } = require("../crypto");
@@ -30,6 +16,38 @@ var DEFAULT_FORMAT = /^[A-Za-z0-9._-]{8,128}$/;
 // can't drive ReDoS even against a careless operator pattern.
 var MAX_INBOUND_LEN = C.BYTES.bytes(256);
 
+/**
+ * @primitive b.middleware.requestId
+ * @signature b.middleware.requestId(req, res, next)
+ * @since     0.1.0
+ * @related   b.middleware.requestLog, b.middleware.traceLogCorrelation
+ *
+ * Sets a stable correlation id on every request. Constructed via
+ * the factory call `b.middleware.requestId(opts)`; the resulting
+ * middleware has the `(req, res, next)` shape shown above.
+ * Propagates a trusted inbound `X-Request-Id` (or operator-named
+ * header) when it matches the format regex; otherwise generates a
+ * fresh 16-byte hex token. The id lands on `req.requestId` and on
+ * the response header so downstream services + the framework's
+ * audit log can correlate the request across hops. Mount FIRST in
+ * the chain — every later primitive expects `req.requestId` to
+ * be present for log lines and audit-record metadata.
+ *
+ * @opts
+ *   {
+ *     headerName:    string,    // default "X-Request-Id"
+ *     trustUpstream: boolean,   // default true; false → always re-mint
+ *     formatRegex:   RegExp,    // default /^[A-Za-z0-9._-]{8,128}$/
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.requestId({ trustUpstream: true }));
+ *   app.get("/health", function (req, res) {
+ *     res.end(req.requestId);
+ *   });
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/request-log.js

@@ -43,6 +43,43 @@ function _defaultLevel(status) {
   return "info";
 }
 
+/**
+ * @primitive b.middleware.requestLog
+ * @signature b.middleware.requestLog(req, res, next)
+ * @since     0.1.0
+ * @related   b.middleware.requestId, b.middleware.traceLogCorrelation
+ *
+ * HTTP access-log middleware. Constructed via
+ * `b.middleware.requestLog(opts)`; the resulting middleware has the
+ * `(req, res, next)` shape shown above. Emits one structured log entry per
+ * request via the operator-supplied `b.log` instance, capturing
+ * method / path / status / durationMs / bytes / actorIp / userAgent
+ * / requestId. Reads the final status via
+ * `b.requestHelpers.captureResponseStatus` so handlers using any
+ * shape (`writeHead` / `statusCode =` / fluent `status(...).send`)
+ * report correctly. `levelFn(status)` defaults to 5xx=error,
+ * 4xx=warn, else info; pass a string `level` or custom function for
+ * different policies. `trustProxy` gates `X-Forwarded-For`
+ * consumption.
+ *
+ * @opts
+ *   {
+ *     logger:     object,                       // required b.log instance
+ *     skipPaths:  Array<string|RegExp>,
+ *     trustProxy: boolean|number,
+ *     level:      string,
+ *     levelFn:    function(status): string,
+ *     fields:     string[],
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.requestLog({
+ *     logger:    b.log.boot("http"),
+ *     skipPaths: ["/healthz"],
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/require-aal.js

@@ -44,6 +44,35 @@ function _writeUnauthorized(res, requiredBand, actualBand, realm) {
   res.end(body);
 }
 
+/**
+ * @primitive b.middleware.requireAal
+ * @signature b.middleware.requireAal(opts)
+ * @since     0.1.0
+ * @related   b.middleware.requireStepUp, b.middleware.requireAuth
+ *
+ * Gates routes by NIST SP 800-63-4 Authenticator Assurance Level
+ * (AAL1 / AAL2 / AAL3). Reads the actual band from `req.user.aal`
+ * by default; operators with a different shape pass `getAal(req)`.
+ * Refuses below-minimum requests with HTTP 401 +
+ * `WWW-Authenticate: AAL-StepUp realm="<X>", required="<minimum>"`
+ * — the bespoke scheme name signals the frontend to trigger a
+ * step-up flow (re-prompt for TOTP / passkey). Throws at create()
+ * on an invalid `minimum` band. Emits `auth.aal.granted` /
+ * `auth.aal.denied` audit events.
+ *
+ * @opts
+ *   {
+ *     minimum: "AAL1"|"AAL2"|"AAL3",   // required
+ *     getAal:  function(req): string,
+ *     realm:   string,
+ *     audit:   boolean,                // default true
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use("/admin", b.middleware.requireAal({ minimum: "AAL2" }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/require-auth.js

@@ -47,6 +47,38 @@ function _defaultPrefersJson(req) {
   return false;
 }
 
+/**
+ * @primitive b.middleware.requireAuth
+ * @signature b.middleware.requireAuth(req, res, next)
+ * @since     0.1.0
+ * @related   b.middleware.attachUser, b.middleware.bearerAuth, b.middleware.requireAal
+ *
+ * Gates routes that require an authenticated user. Constructed via
+ * `b.middleware.requireAuth(opts)`; the resulting middleware has
+ * the `(req, res, next)` shape shown above. Mount AFTER
+ * `attachUser`; this middleware reads `req.user` and either passes
+ * the request or rejects. JSON-preferring callers (Accept includes
+ * `application/json` or `X-Requested-With: XMLHttpRequest`) get 401
+ * `application/json`; browser-preferring with `redirectTo` get 302
+ * Location; otherwise 401 `text/plain`. The REQUEST Content-Type
+ * is intentionally NOT a signal — what the client SENT is not
+ * what they want BACK. Always emits `auth.required.denied` audit
+ * (method + path + client IP, no body content).
+ *
+ * @opts
+ *   {
+ *     redirectTo:   string,                            // 302 location for browser
+ *     prefersJson:  function(req): boolean,
+ *     errorMessage: string,                            // default "Authentication required."
+ *     audit:        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.requireAuth({ redirectTo: "/login" }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

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

@@ -70,6 +70,47 @@ function _timingSafeStringEqual(a, b) {
   return crypto().timingSafeEqual(Buffer.from(a), Buffer.from(b));
 }
 
+/**
+ * @primitive b.middleware.requireBoundKey
+ * @signature b.middleware.requireBoundKey(opts)
+ * @since     0.1.0
+ * @related   b.middleware.bearerAuth, b.middleware.requireMtls
+ *
+ * Bearer-API-key auth with scope + bound-fields + peer-cert
+ * fingerprint binding. Covers the service-to-service /
+ * partner-webhook / CI-runner case where a stable API key is
+ * registered with `{ scopes, boundFields, peerCertFingerprints }`.
+ * The middleware verifies the inbound `Bearer` token, checks
+ * scopes against `requiredScopes`, pulls each bound field via
+ * the operator-supplied `getBoundField[name](req)` and compares to
+ * the registered value, and (when registered) compares the
+ * peer-cert fingerprint to the allowlist. Fails closed on resolver
+ * error / undefined return. Refuses with HTTP 401/403 + structured
+ * JSON identifying which check failed; audits the api-key id (not
+ * the secret) on every decision.
+ *
+ * @opts
+ *   {
+ *     resolver:                async function(apiKey): { id, scopes, boundFields, peerCertFingerprints } | null,  // required
+ *     requiredScopes:          string[],
+ *     getBoundField:           Record<string, function(req): string|null>,
+ *     tolerateMissingPeerCert: boolean,
+ *     errorMessage:            string,
+ *     auditAction:             string,
+ *     audit:                   object,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.post("/webhook", b.middleware.requireBoundKey({
+ *     resolver: async function (apiKey) {
+ *       if (apiKey === "valid-key") return { id: "k1", scopes: ["webhook.ingest"], boundFields: {} };
+ *       return null;
+ *     },
+ *     requiredScopes: ["webhook.ingest"],
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/require-content-type.js

@@ -39,6 +39,38 @@ function _normalizeAllowed(types) {
   return out;
 }
 
+/**
+ * @primitive b.middleware.requireContentType
+ * @signature b.middleware.requireContentType(allowed, opts)
+ * @since     0.1.0
+ * @related   b.middleware.requireMethods, b.middleware.bodyParser
+ *
+ * Refuses requests with a body (POST/PUT/PATCH by default) whose
+ * `Content-Type` header isn't in the operator-supplied allowlist.
+ * Defends against MIME-type confusion: a route that processes JSON
+ * shouldn't accept `application/x-www-form-urlencoded` even if the
+ * body parses, and vice versa. Refuses with HTTP 415 + `Accept:`
+ * listing the allowed types per RFC 9110 §15.5.16, BEFORE the
+ * body parser runs. Idempotent verbs (GET / HEAD / DELETE /
+ * OPTIONS) bypass by default; operators with rare DELETE-with-body
+ * shapes pass `methods` to override. Throws on empty / non-array
+ * allowlist.
+ *
+ * @opts
+ *   {
+ *     methods: string[],   // override default ["POST", "PUT", "PATCH"]
+ *     audit:   boolean,    // default true
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.post("/api/echo",
+ *     b.middleware.requireContentType(["application/json"]),
+ *     b.middleware.bodyParser({ json: { limit: 1024 } }),
+ *     function (req, res) { res.end(JSON.stringify(req.body)); }
+ *   );
+ */
 function create(allowed, opts) {
   var normalized = _normalizeAllowed(allowed);
   if (!normalized) {

package/lib/middleware/require-methods.js

@@ -22,6 +22,33 @@ var RequireMethodsError = defineClass("RequireMethodsError", { alwaysPermanent:
 
 var observability = lazyRequire(function () { return require("../observability"); });
 
+/**
+ * @primitive b.middleware.requireMethods
+ * @signature b.middleware.requireMethods(allowed, opts)
+ * @since     0.1.0
+ * @related   b.middleware.requireContentType
+ *
+ * Refuses HTTP methods outside the operator-supplied allowlist.
+ * Defends against unexpected verb routing — many CVE-class bugs
+ * trace to a route wired for GET that accidentally accepts arbitrary
+ * verbs (PROPFIND, OPTIONS, custom). Refuses with HTTP 405 +
+ * `Allow:` header listing the allowed methods per RFC 9110 §15.5.6.
+ * Throws at create-time on empty / non-array allowlist or methods
+ * containing whitespace/separator characters.
+ *
+ * @opts
+ *   {
+ *     audit: boolean,   // default true
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use("/api",
+ *     b.middleware.requireMethods(["GET", "POST"]),
+ *     function (req, res) { res.end("ok"); }
+ *   );
+ */
 function create(allowed, opts) {
   if (!Array.isArray(allowed) || allowed.length === 0) {
     throw new RequireMethodsError("require-methods/no-allowlist",

package/lib/middleware/require-mtls.js

@@ -63,6 +63,39 @@ function _normalizeFingerprintEntry(entry) {
   return entry;
 }
 
+/**
+ * @primitive b.middleware.requireMtls
+ * @signature b.middleware.requireMtls(opts)
+ * @since     0.1.0
+ * @related   b.middleware.requireBoundKey, b.middleware.bearerAuth
+ *
+ * Soft-enforcement gate for routes that require an authenticated
+ * client certificate. Refuses with HTTP 401 when no peer cert is
+ * presented, when the TLS layer marks `req.client.authorized ===
+ * false`, when the SHA3-512 fingerprint isn't on the operator
+ * allowlist, or when it appears on the denylist. Allowlist of
+ * null / empty means "any peer cert authorized at the TLS layer
+ * is fine"; non-empty allowlist additionally requires fingerprint
+ * match. Pair with `b.app({ tlsOptions: { requestCert: true, ca:
+ * [...] } })` so the TLS layer captures the client cert.
+ *
+ * @opts
+ *   {
+ *     fingerprintAllowList: string[],
+ *     denyList:             string[],
+ *     onAuthenticated:      function(req, res, next): void,
+ *     auditAction:          string,
+ *     errorMessage:         string,
+ *     audit:                object,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use("/internal", b.middleware.requireMtls({
+ *     fingerprintAllowList: ["AB:CD:EF:01:23:45"],
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/require-step-up.js

@@ -75,6 +75,43 @@ function _writeChallenge(res, challenge, body, statusCode) {
   res.end(json);
 }
 
+/**
+ * @primitive b.middleware.requireStepUp
+ * @signature b.middleware.requireStepUp(opts)
+ * @since     0.1.0
+ * @related   b.middleware.requireAal, b.middleware.bearerAuth
+ *
+ * Gates routes per RFC 9470 OAuth 2.0 Step-Up Authentication
+ * Challenge. Mount AFTER `attachUser` / `bearerAuth` so the
+ * request carries verified token claims. Refuses with HTTP 401 +
+ * `WWW-Authenticate: Bearer error="insufficient_user_authentication",
+ * acr_values="...", max_age="..."`. With `acceptGrant: true`
+ * (default) the middleware first checks for a fresh
+ * `b.auth.stepUp.grant` token in `X-Step-Up-Grant` so a
+ * multi-step flow doesn't re-prompt on every action. Never weakens
+ * defaults to accommodate missing IdP claims — operators configure
+ * the IdP to emit `acr` / `auth_time` / `amr` correctly.
+ *
+ * @opts
+ *   {
+ *     requirement: { acr, acrValues, maxAge, requiredAmr, phishingResistant },  // required
+ *     getClaims:   function(req): object,
+ *     realm:       string,
+ *     acceptGrant: boolean,    // default true
+ *     grantHeader: string,     // default "X-Step-Up-Grant"
+ *     grantScope:  string,
+ *     errorDescription: string,
+ *     audit:       boolean,    // default true
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use("/billing/transfer", b.middleware.requireStepUp({
+ *     requirement: { acr: "high", maxAge: 300 },
+ *     realm:       "billing-api",
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [