@blamejs/core 0.8.43 → 0.8.49

package/lib/middleware/body-parser.js

@@ -114,6 +114,7 @@ var path = require("path");
 var nodeCrypto = require("node:crypto");
 var atomicFile = require("../atomic-file");
 var crypto = require("../crypto");
+var lazyRequire = require("../lazy-require");
 var requestHelpers = require("../request-helpers");
 var safeBuffer = require("../safe-buffer");
 var safeJson = require("../safe-json");
@@ -121,6 +122,34 @@ var validateOpts = require("../validate-opts");
 var C = require("../constants");
 var { defineClass } = require("../framework-error");
 
+var auditFwk = lazyRequire(function () { return require("../audit"); });
+
+// Node's HTTP parser surfaces malformed chunked-transfer-encoding via a
+// stable family of HPE_* codes. RFC 9112 §7.1 — when a server rejects a
+// chunked decode the connection MUST close so a downstream proxy can't
+// reuse the socket with the next request's body bytes still pending.
+// HPE_INVALID_CHUNK_SIZE / HPE_CHUNK_EXTENSIONS_OVERFLOW (Node 24+) /
+// HPE_INVALID_TRANSFER_ENCODING / HPE_INVALID_EOF_STATE (chunk truncated)
+// all land here. The framework's Connection: close + audit emit closes
+// the smuggling-adjacent socket-reuse path that bare 400-only handling
+// leaves open.
+var CHUNKED_MALFORMED_CODES = new Set([
+  "HPE_INVALID_CHUNK_SIZE",
+  "HPE_INVALID_TRANSFER_ENCODING",
+  "HPE_INVALID_EOF_STATE",
+  "HPE_INVALID_CONSTANT",
+  "HPE_CHUNK_EXTENSIONS_OVERFLOW",
+  "HPE_UNEXPECTED_CONTENT_LENGTH",
+  "ERR_HTTP_INVALID_CHUNK",
+]);
+function _isChunkedMalformed(e) {
+  if (!e) return false;
+  if (typeof e.code === "string" && CHUNKED_MALFORMED_CODES.has(e.code)) return true;
+  if (typeof e.code === "string" && e.code.indexOf("HPE_") === 0 &&
+      typeof e.message === "string" && /chunk/i.test(e.message)) return true;
+  return false;
+}
+
 var HTTP_STATUS = requestHelpers.HTTP_STATUS;
 var BodyParserError = defineClass("BodyParserError", { withStatusCode: true });
 
@@ -1098,6 +1127,46 @@ async function _parseMultipart(req, opts, ctParams) {
 
 // ---- main middleware factory ----
 
+/**
+ * @primitive b.middleware.bodyParser
+ * @signature b.middleware.bodyParser(req, res, next)
+ * @since     0.1.0
+ * @related   b.middleware.bodyParser.raw, b.parsers.json, b.parsers.multipart
+ *
+ * Buffers and parses request bodies based on Content-Type.
+ * Constructed via `b.middleware.bodyParser(opts)`; the resulting
+ * middleware has the `(req, res, next)` shape shown above. Five
+ * sub-parsers ship: JSON (via `safe-json` — POISONED_KEYS stripped,
+ * depth + size caps), urlencoded, text, raw octet-stream, and
+ * multipart/form-data. Multipart streams file parts to a tmp dir
+ * with per-file + total-request size caps, filename sanitization,
+ * SHA3-512 hashing during streaming, and tmp-file cleanup on
+ * response end. Defends against RFC 9112 §6.1 request smuggling
+ * before any body bytes are read. Each sub-parser can be disabled
+ * by passing `false` in its slot.
+ *
+ * @opts
+ *   {
+ *     json:        false | { limit, strict, charset, parseHook, contentTypes },
+ *     urlencoded:  false | { limit, arrayLimit, contentTypes },
+ *     text:        false | { limit, charset, contentTypes },
+ *     raw:         false | { limit, contentTypes },
+ *     multipart:   false | {
+ *       tmpDir, fileSize, totalSize, fileCount, fieldCount, fieldSize,
+ *       mimeAllowlist, fileFilter, fields, audit, contentTypes,
+ *     },
+ *     keepRawBody: boolean,    // expose req.bodyRaw for webhook signing
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.bodyParser({
+ *     json:       { limit: b.constants.BYTES.mib(1) },
+ *     urlencoded: { limit: b.constants.BYTES.mib(1) },
+ *     multipart:  false,
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
@@ -1191,6 +1260,52 @@ function create(opts) {
         "body-parser/unsupported-content-type"
       );
     } catch (e) {
+      // RFC 9112 §7.1 — a server that rejects a chunked-decoded body
+      // MUST close the connection so the upstream proxy cannot reuse
+      // the socket with the next request's bytes still in flight. The
+      // smuggling-shape pre-flight at top of the request already
+      // catches the static TE/CL conflict cases; this catch handles
+      // mid-stream parser failure (HPE_INVALID_CHUNK_SIZE etc. surfaced
+      // by Node's HTTP parser as the body bytes arrive). Set
+      // Connection: close + audit + 400.
+      if (_isChunkedMalformed(e)) {
+        // CVE-2026-33870 — chunked-encoding extension smuggling. When
+        // Node's parser surfaces HPE_CHUNK_EXTENSIONS_OVERFLOW the
+        // chunk-extension parameters exceeded llhttp's cap; the
+        // framework emits a distinct audit action so operators can
+        // alert on extension-smuggling specifically. RFC 9112 §7.1.1
+        // chunk-ext is `; chunk-ext-name [= chunk-ext-val]` per chunk;
+        // multi-`;` and `;param=value` shapes reach this code path
+        // when the operator sets a tighter
+        // `--max-http-header-size` / per-chunk extension cap.
+        var chunkAction = (e && e.code === "HPE_CHUNK_EXTENSIONS_OVERFLOW")
+          ? "http.chunked.extension.refused"
+          : "http.chunked.malformed.refused";
+        try {
+          auditFwk().safeEmit({
+            action:  chunkAction,
+            outcome: "denied",
+            metadata: {
+              code:    e.code || null,
+              message: (e && e.message) ? String(e.message).slice(0, 256) : "",                                  // allow:raw-byte-literal — diagnostic-message clamp characters, not bytes
+            },
+          });
+        } catch (_e) { /* audit best-effort */ }
+        if (!res.headersSent) {
+          var malformedBody = JSON.stringify({
+            error: "malformed chunked transfer-encoding (RFC 9112 §7.1 — connection closed)",
+            code:  "http/chunked-malformed",
+          });
+          res.writeHead(HTTP_STATUS.BAD_REQUEST, {
+            "Content-Type":   "application/json; charset=utf-8",
+            "Content-Length": Buffer.byteLength(malformedBody),
+            "Connection":     "close",
+          });
+          res.end(malformedBody);
+        }
+        try { req.destroy(); } catch (_e) { /* socket already closed */ }
+        return;
+      }
       var status = (e && typeof e.statusCode === "number") ? e.statusCode : HTTP_STATUS.BAD_REQUEST;
       var code   = (e && typeof e.code === "string") ? e.code : "body-parser/error";
       var message = (e && e.message) ? e.message : String(e);
@@ -1238,6 +1353,36 @@ async function _parseJsonFromBuf(buf, opts) {
 // Accepts the same `raw`-section opts as create() (limit, contentTypes).
 // contentTypes default expands to `["*/*"]` so any Content-Type lands
 // as raw bytes.
+
+/**
+ * @primitive b.middleware.bodyParser.raw
+ * @signature b.middleware.bodyParser.raw(opts)
+ * @since     0.1.0
+ * @related   b.middleware.bodyParser
+ *
+ * Convenience factory that mounts only the raw-bytes sub-parser of
+ * `bodyParser`. Sets `req.body` to a Buffer regardless of
+ * `Content-Type`. Use on webhook-signature routes where the HMAC is
+ * computed over the literal body bytes — JSON-parsing first would
+ * change them. The `contentTypes` default expands to `["*\/*"]` so
+ * any inbound type is captured.
+ *
+ * @opts
+ *   {
+ *     limit:        number,    // default ~10 MiB
+ *     contentTypes: string[],  // default ["*\/*"]
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.post("/hooks/in", b.middleware.bodyParser.raw({
+ *     limit: b.constants.BYTES.mib(1),
+ *   }), function (req, res) {
+ *     // req.body is a Buffer of the raw request bytes
+ *     res.end(String(req.body.length));
+ *   });
+ */
 function raw(opts) {
   opts = opts || {};
   return create({
@@ -1257,10 +1402,95 @@ function raw(opts) {
 // itself, so static helpers hang off it).
 create.raw = raw;
 
+// ---- Standalone async parsers ----
+//
+// `parseJsonStandalone(req, opts)` and `parseMultipartStandalone(req, opts)`
+// are the same parsing pipelines the middleware uses, exposed for handlers
+// that lazy-parse — code that decides parser shape from a route flag, or
+// bypasses the middleware for streaming endpoints. The middleware composes
+// these so there's no parallel pipeline to drift.
+//
+// Throws BodyParserError on caps / malformed shapes — operator handles in
+// a try/catch around `await b.parsers.json(req, ...)` /
+// `await b.parsers.multipart(req, ...)`. Validation tier is config-time
+// (throw at create on bad opts) + observable (throw on bad input — the
+// handler is awaiting the call, not a request lifecycle hook).
+
+function _resolveStandaloneJsonOpts(opts) {
+  opts = opts || {};
+  var maxBytes = (opts.maxBytes !== undefined) ? opts.maxBytes : DEFAULTS.json.limit;
+  validateOpts.optionalPositiveFinite(maxBytes, "parsers.json: opts.maxBytes",
+    BodyParserError, "body-parser/bad-max-bytes");
+  var strict = (opts.strict !== undefined) ? !!opts.strict : DEFAULTS.json.strict;
+  var charset = (typeof opts.charset === "string") ? opts.charset : DEFAULTS.json.charset;
+  return {
+    limit:     maxBytes,
+    strict:    strict,
+    charset:   charset,
+    parseHook: (typeof opts.parseHook === "function") ? opts.parseHook : undefined,
+  };
+}
+
+function _resolveStandaloneMultipartOpts(opts, ct) {
+  opts = opts || {};
+  var resolved = Object.assign({}, DEFAULTS.multipart);
+  validateOpts.optionalPositiveFinite(opts.maxBytes, "parsers.multipart: opts.maxBytes",
+    BodyParserError, "body-parser/bad-max-bytes");
+  if (opts.maxBytes !== undefined) {
+    resolved.totalSize = opts.maxBytes;
+    // Per-file cap clamps to maxBytes so a single field can't exceed the
+    // request total — operator opts in to a smaller fileSize via opts.fileSize.
+    if (resolved.fileSize > opts.maxBytes) resolved.fileSize = opts.maxBytes;
+  }
+  if (opts.maxFiles !== undefined) {
+    var mf = opts.maxFiles;
+    var mfBad = typeof mf !== "number" || !isFinite(mf) || mf <= 0 || Math.floor(mf) !== mf;
+    if (mfBad) {
+      throw new BodyParserError("body-parser/bad-max-files",
+        "parsers.multipart: opts.maxFiles must be a positive integer",
+        true, HTTP_STATUS.BAD_REQUEST);
+    }
+    resolved.fileCount = mf;
+  }
+  // Pass-through overrides for the multipart-specific knobs the middleware
+  // accepts. parsers.multipart is a thin wrapper, not a feature subset.
+  ["tmpDir", "fileSize", "fieldCount", "fieldSize", "mimeAllowlist",
+   "fileFilter", "fields", "audit"].forEach(function (k) {
+    if (opts[k] !== undefined) resolved[k] = opts[k];
+  });
+  // ct is the parsed Content-Type; required for the boundary parameter.
+  if (!ct || typeof ct.type !== "string" || ct.type !== "multipart/form-data") {
+    throw new BodyParserError("body-parser/standalone-not-multipart",
+      "parsers.multipart: request Content-Type must be multipart/form-data, got " +
+      JSON.stringify(ct ? ct.type : null),
+      true, HTTP_STATUS.BAD_REQUEST);
+  }
+  return resolved;
+}
+
+async function parseJsonStandalone(req, opts) {
+  var resolved = _resolveStandaloneJsonOpts(opts);
+  return _parseJson(req, resolved);
+}
+
+async function parseMultipartStandalone(req, opts) {
+  var ct = _contentType(req);
+  var resolved = _resolveStandaloneMultipartOpts(opts, ct);
+  // Returns { fields, files, filesRejected } — same shape the middleware
+  // attaches to req. Handlers that already-accepted the upload wire
+  // cleanup themselves (move file off tmp / unlink).
+  return _parseMultipart(req, resolved, ct.params);
+}
+
 module.exports = {
   create:           create,
   raw:              raw,
   BodyParserError:  BodyParserError,
+  // Standalone async helpers — surfaced via b.parsers.{json,multipart}.
+  // The middleware composes these so the request-handling pipeline and
+  // the operator-callable surface share one parsing path.
+  parseJson:        parseJsonStandalone,
+  parseMultipart:   parseMultipartStandalone,
   // Internal helpers exposed for tests + the csrf-protect refactor.
   _contentType:     _contentType,
   _hasBody:         _hasBody,

package/lib/middleware/bot-disclose.js

@@ -41,6 +41,40 @@ var DEFAULT_BANNER_HTML = '<div role="status" data-bot-disclosure="true" ' +
   'For California users: this disclosure is provided per Cal. Bus. &amp; Prof. Code §17941.' +
   '</div>';
 
+/**
+ * @primitive b.middleware.botDisclose
+ * @signature b.middleware.botDisclose(opts)
+ * @since     0.1.0
+ * @related   b.middleware.aiActDisclosure, b.middleware.botGuard
+ *
+ * California SB 1001 bot-disclosure (Cal. Bus. & Prof. Code §17941):
+ * automated conversation surfaces (LLM chat / IVR / SMS) used to
+ * incentivize sales or influence elections must disclose their
+ * non-human nature. Injects a disclosure banner into HTML responses,
+ * sets `X-Bot-Disclosure` for API consumers, and emits an audit
+ * event for every conversation-initiating request. Operator-supplied
+ * `bannerHtml` / `bannerJson` carry custom branding while the
+ * default copy meets the §17941(a) "clear, conspicuous, reasonably
+ * designed" bar.
+ *
+ * @opts
+ *   {
+ *     mountPaths:  string[],         // null = apply to all routes
+ *     bannerHtml:  string,
+ *     bannerJson:  object,
+ *     headerName:  string,           // default "X-Bot-Disclosure"
+ *     auditAction: string,           // default "middleware.bot_disclose"
+ *     audit:       boolean,          // default true
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.botDisclose({
+ *     mountPaths: ["/chat", "/api/chat"],
+ *     bannerJson: { _bot: true, disclosure: "automated-assistant" },
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/bot-guard.js

@@ -77,6 +77,45 @@ function _xffIpFor(trustProxy) {
   };
 }
 
+/**
+ * @primitive b.middleware.botGuard
+ * @signature b.middleware.botGuard(req, res, next)
+ * @since     0.1.0
+ * @related   b.middleware.fetchMetadata, b.middleware.botDisclose
+ *
+ * Cheap fingerprint-based detection of obviously-non-browser requests.
+ * Constructed via `b.middleware.botGuard(opts)`; the resulting
+ * middleware has the `(req, res, next)` shape shown above.
+ * Combines three heuristics: missing `Accept-Language`, missing
+ * `Sec-Fetch-Mode` (HTML routes), and User-Agent regex match against
+ * a default list (curl / wget / python-requests / axios / etc.). Not
+ * a substitute for proper authentication — catches drive-by scrapers
+ * and low-effort bots. In `mode: "block"` (default) the request is
+ * refused; in `mode: "tag"` `req.suspectedBot = true` is set and the
+ * request continues so the application can rate-limit suspected bots
+ * separately. Every decision is audited.
+ *
+ * @opts
+ *   {
+ *     mode:          "block"|"tag",     // default "block"
+ *     onlyForHtml:   boolean,           // default true
+ *     allowedAgents: RegExp[],          // override matches
+ *     blockedAgents: RegExp[],          // append to defaults
+ *     skipPaths:     string[],
+ *     statusOnBlock: number,            // default 403
+ *     bodyOnBlock:   string,
+ *     trustProxy:    boolean|number,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.botGuard({
+ *     mode:        "tag",
+ *     skipPaths:   ["/healthz"],
+ *     onlyForHtml: true,
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/compression.js

@@ -225,6 +225,43 @@ function _appendVary(existing, token) {
   return parts.join(", ");
 }
 
+/**
+ * @primitive b.middleware.compression
+ * @signature b.middleware.compression(req, res, next)
+ * @since     0.1.0
+ * @related   b.middleware.sse
+ *
+ * Brotli + gzip response compression. Constructed via
+ * `b.middleware.compression(opts)`; the resulting middleware has
+ * the `(req, res, next)` shape shown above. Intercepts the response stream
+ * and pipes it through `node:zlib`'s transform when the client
+ * supports it. Brotli is preferred (better ratio for text), gzip is
+ * the fallback. Skips small responses (below `threshold`),
+ * already-encoded responses, 204/304 status codes, server-sent
+ * events streams (chunked compression breaks SSE framing), and
+ * Content-Types outside the allowlist (image/* / video/* / archives
+ * are already entropy-dense). Operators with custom skip logic wire
+ * a `filter(req, res)` predicate.
+ *
+ * @opts
+ *   {
+ *     threshold:     number,            // default 1024 bytes
+ *     encodings:     string[],          // default ["br", "gzip"]
+ *     contentTypes:  string[],          // allowlist of MIME types
+ *     gzipLevel:     number,            // 1..9, default 6
+ *     brotliQuality: number,            // 0..11, default 4
+ *     filter:        function(req, res): boolean,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.compression({
+ *     threshold:    1024,
+ *     encodings:    ["br", "gzip"],
+ *     contentTypes: ["text/*", "application/json"],
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/cookies.js

@@ -47,6 +47,38 @@ function _emitAudit(audit, action, outcome, metadata) {
   } catch (_e) { /* drop-silent — observability sink */ }
 }
 
+/**
+ * @primitive b.middleware.cookies
+ * @signature b.middleware.cookies(opts)
+ * @since     0.1.0
+ * @related   b.cookies.parseSafe, b.middleware.csrfProtect
+ *
+ * Inbound `Cookie` header threat detection. Runs every request through
+ * `b.cookies.parseSafe` and surfaces header-cap / control-byte /
+ * malformed-pair / empty-name / name-cap / value-cap / duplicate-name
+ * (cookie-tossing) issues. Sets `req.cookieJar` to the parsed jar.
+ * In `mode: "enforce"` (default) high-severity issues refuse the
+ * request with HTTP 400 + JSON body; `audit-only` and `log-only`
+ * modes pass through but still emit audits.
+ *
+ * @opts
+ *   {
+ *     mode:           "enforce"|"audit-only"|"log-only",  // default "enforce"
+ *     refuseOnHigh:   boolean,    // default true (only meaningful in enforce)
+ *     maxHeaderBytes: number,
+ *     maxNameBytes:   number,
+ *     maxValueBytes:  number,
+ *     audit:          object,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.cookies({
+ *     mode:           "enforce",
+ *     maxHeaderBytes: b.constants.BYTES.kib(8),
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   var mode = opts.mode || "enforce";

package/lib/middleware/cors.js

@@ -156,6 +156,46 @@ function _isSameOrigin(req, originHeader, configuredSiteOrigins, trustProxy, str
   return reqOrigin !== null && reqOrigin === canonOrigin;
 }
 
+/**
+ * @primitive b.middleware.cors
+ * @signature b.middleware.cors(req, res, next)
+ * @since     0.1.0
+ * @related   b.middleware.csrfProtect, b.middleware.fetchMetadata
+ *
+ * Cross-Origin Resource Sharing handler. Constructed via
+ * `b.middleware.cors(opts)`; the resulting middleware has the
+ * `(req, res, next)` shape shown above. Allowlist matches strings
+ * (canonicalized) and RegExp entries. Handles preflights,
+ * `Access-Control-Allow-*` response headers, and
+ * `strictNullOrigin: true` (default) refuses `Origin: null` even
+ * with `Sec-Fetch-Site: same-origin` since non-browser callers can
+ * forge that header. `siteOrigin` declares the framework's own
+ * origin(s) for same-origin shortcuts. Throws at create() on
+ * unparseable origin entries — operators catch typos at boot.
+ *
+ * @opts
+ *   {
+ *     origins:          Array<string|RegExp>,
+ *     siteOrigin:       string|string[],
+ *     methods:          string[],   // default GET,POST,PUT,PATCH,DELETE,HEAD,OPTIONS
+ *     headers:          string[],   // default Content-Type,Authorization,X-Request-Id
+ *     exposeHeaders:    string[],   // default X-Request-Id
+ *     credentials:      boolean,
+ *     maxAgeSeconds:    number,     // default 600
+ *     refuseUnknown:    boolean,    // default true
+ *     strictNullOrigin: boolean,    // default true
+ *     trustProxy:       boolean|number,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.cors({
+ *     origins:    ["https://app.example.com", /\.example\.com$/],
+ *     siteOrigin: "https://example.com",
+ *     methods:    ["GET", "POST"],
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
 

package/lib/middleware/csp-nonce.js

@@ -224,6 +224,46 @@ function _injectNonce(cspHeader, nonce, directives, strictDynamic) {
   return _serializeCsp(parts);
 }
 
+/**
+ * @primitive b.middleware.cspNonce
+ * @signature b.middleware.cspNonce(req, res, next)
+ * @since     0.1.0
+ * @related   b.middleware.securityHeaders, b.middleware.cspReport
+ *
+ * Per-request CSP nonce + render integration. Constructed via
+ * `b.middleware.cspNonce(opts)`; the resulting middleware has the
+ * `(req, res, next)` shape shown above. Generates a fresh
+ * random nonce (16 bytes / 22 chars base64 by default), attaches it
+ * to `req.cspNonce` and `res.locals.cspNonce` (auto-merged into
+ * template data), and patches the existing Content-Security-Policy
+ * header to append `'nonce-XYZ'` to the configured directives
+ * (default: script-src + style-src). With `strictDynamic: true`,
+ * appends `'strict-dynamic'` so nonced scripts can load dependencies
+ * without origin allowlisting (recommended for SPA hydration). Mount
+ * after `securityHeaders`. Below-16-byte nonces are refused at
+ * config time.
+ *
+ * @opts
+ *   {
+ *     directives:    string[],   // default ["script-src", "style-src"]
+ *     nonceBytes:    number,     // default 16; minimum 16
+ *     strictDynamic: boolean,
+ *     headerName:    string,     // default "Content-Security-Policy"
+ *     property:      string,     // default "cspNonce"
+ *     always:        boolean,
+ *     placeholder:   string,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.securityHeaders());
+ *   app.use(b.middleware.cspNonce({
+ *     directives:    ["script-src", "style-src"],
+ *     nonceBytes:    16,
+ *     strictDynamic: true,
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/csp-report.js

@@ -82,6 +82,40 @@ function _normalizeOne(reportLike) {
   return null;
 }
 
+/**
+ * @primitive b.middleware.cspReport
+ * @signature b.middleware.cspReport(req, res, next)
+ * @since     0.1.0
+ * @related   b.middleware.cspNonce, b.middleware.securityHeaders
+ *
+ * Reporting-API endpoint for CSP / COEP / COOP / Permissions-Policy
+ * violations. Constructed via `b.middleware.cspReport(opts)`; the
+ * resulting middleware has the `(req, res, next)` shape shown above. Accepts `application/reports+json` (modern) and the
+ * legacy `application/csp-report` body shapes. Refuses non-POST
+ * (HTTP 405), oversized bodies (HTTP 413, default 64 KiB cap), and
+ * non-JSON (HTTP 400). Each report is normalized to a uniform shape
+ * (`type`, `url`, `body.{documentURL, blockedURL, effectiveDirective,
+ * sample, sourceFile, lineNumber}`), audited with action
+ * `csp.violation`, and forwarded to the operator's `onReport`
+ * callback for metrics or alerting.
+ *
+ * @opts
+ *   {
+ *     onReport: function(report): void,
+ *     maxBytes: number,    // default 64 KiB
+ *     audit:    boolean,   // default true
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.post("/csp-report", b.middleware.cspReport({
+ *     maxBytes: b.constants.BYTES.kib(64),
+ *     onReport: function (report) {
+ *       console.log("csp violation", report.body.effectiveDirective);
+ *     },
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, ["audit", "onReport", "maxBytes"], "middleware.cspReport");

package/lib/middleware/csrf-protect.js

@@ -226,6 +226,49 @@ function _writeReject(res, message) {
   }
 }
 
+/**
+ * @primitive b.middleware.csrfProtect
+ * @signature b.middleware.csrfProtect(req, res, next)
+ * @since     0.1.0
+ * @related   b.middleware.cors, b.middleware.fetchMetadata
+ *
+ * Issues CSRF tokens to safe-method requests and rejects state-
+ * changing requests whose submitted token doesn't match. Constructed
+ * via `b.middleware.csrfProtect(opts)`; the resulting middleware
+ * has the `(req, res, next)` shape shown above. Two
+ * storage modes (mutually exclusive, exactly one required):
+ * (a) cookie-stored double-submit (default — `__Host-csrf` over
+ * HTTPS, SameSite=Lax) where the framework issues + reads the
+ * cookie; (b) operator-supplied `tokenLookup(req)` for session-
+ * stored tokens. Submitted-token sources: header (default
+ * `X-CSRF-Token`) then body field (default `_csrf`). Refuses with
+ * HTTP 403 + audits `auth.csrf.denied` on mismatch. Mount AFTER
+ * `attachUser` (session lookup) and `bodyParser` (form-field read).
+ *
+ * @opts
+ *   {
+ *     cookie:                 boolean | { name, sameSite, secure, path, httpOnly },
+ *     tokenLookup:            function(req): string|null,
+ *     fieldName:              string,    // default "_csrf"
+ *     headerName:             string,    // default "X-CSRF-Token"
+ *     methods:                string[],  // default POST/PUT/DELETE/PATCH
+ *     checkOrigin:            boolean,
+ *     allowedOrigins:         string[],
+ *     requireOrigin:          boolean,
+ *     requireJsonContentType: boolean,
+ *     trustProxy:             boolean|number,
+ *     audit:                  boolean,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.csrfProtect({
+ *     cookie:        true,
+ *     checkOrigin:   true,
+ *     requireOrigin: true,
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};