@blamejs/core 0.7.48 → 0.7.49

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.7.x
 
+- **0.7.49** (2026-05-05) — `b.middleware.headers(opts)` — inbound HTTP header threat-detection middleware. Sits at the top of the request lifecycle. Threat catalog: `header-name-shape` (header name not a valid RFC 9110 §5.1 token); `header-value-control-byte` (CR / LF / NUL inside any header value — header-injection defense in depth on top of Node's rejection); `header-count-cap` (default 100 inbound headers max); `header-value-cap` (default 8 KiB per value); `smuggling-cl-te` (RFC 9112 §6.1 — both Content-Length and Transfer-Encoding present, the canonical CL.TE / TE.CL request-smuggling vector); `smuggling-cl-multi` / `smuggling-te-multi` (multiple values for either header — proxy-desync class); `deprecated-trust-header` (X-Forwarded-For / -Proto / -Host / -Port / X-Real-IP present without operator-supplied `trustProxy: true` opt — operators should adopt RFC 7239 `Forwarded`). On `mode: "enforce"` + `refuseOnHigh` (default), refuses with HTTP 400 + JSON body listing detected high-severity issues; emits one audit row per issue regardless of mode. Complements the existing per-route smuggling defense in `b.middleware.bodyParser` by running the same check at the top of the chain (covers GET / HEAD requests that don't body-parse).
+
 - **0.7.48** (2026-05-05) — `b.cookies.parseSafe(header, opts)` + `b.middleware.cookies(opts)` — inbound cookie-header threat detection. The existing `b.cookies.parse` is lenient (last-write-wins, silent skip on malformed pairs); `parseSafe` returns `{ jar, issues }` and surfaces every detected anomaly: header-cap (oversized Cookie header), header-control-byte (CR / LF / NUL injected through proxy — header-injection prelude class), pair-malformed (missing `=`), pair-empty-name, name-cap (oversized name), value-cap (oversized value), duplicate-name (cookie-tossing class — same name appearing more than once in one Cookie header indicates an attacker-set parent-domain cookie shadowing the legitimate one). The middleware shape (`b.middleware.cookies({ mode, audit, refuseOnHigh })`) wires `parseSafe` into the request lifecycle: populates `req.cookieJar`, emits one audit row per detected issue, and refuses with HTTP 400 on any high-severity issue when `mode: "enforce"` (default). Existing `b.cookies` invariants (RFC 6265bis token grammar enforcement, `__Host-` / `__Secure-` prefix invariants, SameSite=None requires Secure, `Partitioned` / CHIPS attribute support, length caps on serialize-side) remain unchanged — this slice closes the inbound-detection gap.
 
 - **0.7.47** (2026-05-05) — `b.guardMime` — RFC 6838 media-type identifier-safety primitive (KIND="identifier"). Validates user-supplied media type strings destined for Accept-shape comparison, content-type allowlists, and dispatch routing. Threat catalog: shape malformation (missing `/`, bad type/subtype tokens against RFC 6838 §4.2 restricted-name grammar); parameter validation against the RFC 7231 §3.1.1.1 tchar token grammar (token-only or quoted-string per RFC 7230 §3.2.6); wildcard (`type/subtype` with `*`) outside Accept context refuse; vendor tree (`vnd.*`), personal tree (`prs.*`), and unregistered (`x.*` / `x-*`) namespace audit so operators audit those slots; risky-type refuse list covering executable + script-host content types (`application/x-msdownload`, `application/x-bat`, `application/x-msdos-program`, `application/x-sh`, `application/x-csh`, `application/x-perl`, `application/x-python`, `application/javascript`, `application/x-javascript`, `text/javascript`, `text/x-javascript`, `application/x-shockwave-flash`, `application/x-msi`); BIDI / zero-width / control / null-byte universal refuse. `sanitize` lowercases type/subtype while preserving parameter case (multipart boundary tokens etc. are case-significant). Profiles: `strict` (refuse wildcard + risky-type, audit trees + parameters), `balanced` (audit most things, allow vendor tree), `permissive` (universal-refuse class still refused). Postures: `hipaa` / `pci-dss` / `soc2` strict overlay; `gdpr` balanced overlay. Auto-registers into `b.guardAll` as a STANDALONE_GUARD.

package/lib/middleware/headers.js

@@ -0,0 +1,206 @@
+"use strict";
+/**
+ * b.middleware.headers — inbound HTTP header threat detection.
+ *
+ * Sits at the top of the request lifecycle. Validates the inbound
+ * headers against the RFC 9110 §5.1 token grammar and surfaces threat
+ * shapes: CRLF injection, CL+TE request smuggling (RFC 9112 §6.1),
+ * oversized header / count, deprecated trust-header patterns.
+ *
+ * Threat catalog:
+ *   - header-name-shape — header name not a valid RFC 9110 token.
+ *   - header-value-control-byte — CR / LF / NUL inside a header value
+ *     (header-injection defense in depth on top of Node's rejection).
+ *   - header-count-cap — > maxHeaderCount headers (default 100).
+ *   - header-value-cap — single value > maxValueBytes (default 8 KiB).
+ *   - smuggling-cl-te — Content-Length AND Transfer-Encoding both
+ *     present (RFC 9112 §6.1 — CL.TE / TE.CL smuggling shape).
+ *   - smuggling-cl-multi — multiple Content-Length values (proxy-
+ *     desync class).
+ *   - smuggling-te-multi — multiple Transfer-Encoding values.
+ *   - deprecated-trust-header — X-Forwarded-For / X-Forwarded-Proto /
+ *     X-Forwarded-Host present without operator-supplied trustProxy
+ *     opt — the framework warns once that the operator should adopt
+ *     RFC 7239 `Forwarded` or explicit trustProxy.
+ *
+ *   var middleware = b.middleware.headers({
+ *     mode:               "enforce",       // "enforce" | "audit-only" | "log-only"
+ *     audit:              b.audit,
+ *     maxHeaderCount:     100,
+ *     maxValueBytes:      8 * 1024,
+ *     trustProxy:         false,            // whether X-Forwarded-* is allowed
+ *     refuseOnHigh:       true,
+ *   });
+ */
+
+var lazyRequire = require("../lazy-require");
+
+var observability = lazyRequire(function () { return require("../observability"); });
+void observability;
+
+// RFC 9110 §5.1 token grammar — tchar set.
+var TOKEN_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+
+var DEPRECATED_TRUST_HEADERS = Object.freeze([
+  "x-forwarded-for",
+  "x-forwarded-proto",
+  "x-forwarded-host",
+  "x-forwarded-port",
+  "x-real-ip",
+]);
+
+function _emitAudit(audit, action, outcome, metadata) {
+  if (!audit || typeof audit.safeEmit !== "function") return;
+  try {
+    audit.safeEmit({
+      action:   action,
+      actor:    metadata.actor || { kind: "framework", id: "middleware/headers" },
+      outcome:  outcome,
+      metadata: metadata,
+    });
+  } catch (_e) { /* drop-silent — observability sink */ }
+}
+
+function _detectIssues(headers, opts) {
+  var issues = [];
+  if (!headers || typeof headers !== "object") return issues;
+
+  var names = Object.keys(headers);
+
+  if (names.length > opts.maxHeaderCount) {
+    issues.push({
+      kind: "header-count-cap", severity: "high",
+      snippet: "request has " + names.length + " headers, exceeds " +
+               "maxHeaderCount " + opts.maxHeaderCount,
+    });
+  }
+
+  for (var i = 0; i < names.length; i += 1) {
+    var name = names[i];
+    var value = headers[name];
+
+    // Header name shape — Node lowercases names; the original tchar
+    // grammar covers a-z / 0-9 / `!#$%&'*+-.^_`|~`.
+    if (!TOKEN_RE.test(name)) {                                                  // allow:regex-no-length-cap — Node already caps header name length at 8190 chars by default (HTTP/1.1 line cap)
+      issues.push({
+        kind: "header-name-shape", severity: "high",
+        snippet: "header name `" + name + "` is not a valid RFC 9110 " +
+                 "§5.1 token",
+      });
+    }
+
+    var valueArr = Array.isArray(value) ? value : [value];
+    for (var vi = 0; vi < valueArr.length; vi += 1) {
+      var v = valueArr[vi];
+      if (typeof v !== "string") continue;
+      if (Buffer.byteLength(v, "utf8") > opts.maxValueBytes) {
+        issues.push({
+          kind: "header-value-cap", severity: "high", header: name,
+          snippet: "header `" + name + "` value " + v.length +
+                   " bytes exceeds maxValueBytes " + opts.maxValueBytes,
+        });
+        continue;
+      }
+      for (var ci = 0; ci < v.length; ci += 1) {
+        var cc = v.charCodeAt(ci);
+        if (cc === 0x0D || cc === 0x0A || cc === 0x00) {                         // allow:raw-byte-literal — CR / LF / NUL forbidden in header value
+          issues.push({
+            kind: "header-value-control-byte", severity: "high", header: name,
+            snippet: "header `" + name + "` value contains CR / LF / NUL " +
+                     "— header-injection defense in depth",
+          });
+          break;
+        }
+      }
+    }
+  }
+
+  // Smuggling shapes (RFC 9112 §6.1).
+  var clRaw = headers["content-length"];
+  var teRaw = headers["transfer-encoding"];
+  if (clRaw !== undefined && teRaw !== undefined) {
+    issues.push({
+      kind: "smuggling-cl-te", severity: "high",
+      snippet: "both Content-Length and Transfer-Encoding present " +
+               "(RFC 9112 §6.1 — CL.TE / TE.CL request-smuggling vector)",
+    });
+  }
+  if (Array.isArray(clRaw) && clRaw.length > 1) {
+    issues.push({
+      kind: "smuggling-cl-multi", severity: "high",
+      snippet: "multiple Content-Length values — proxy-desync " +
+               "request-smuggling vector",
+    });
+  }
+  if (Array.isArray(teRaw) && teRaw.length > 1) {
+    issues.push({
+      kind: "smuggling-te-multi", severity: "high",
+      snippet: "multiple Transfer-Encoding values — proxy-desync " +
+               "request-smuggling vector",
+    });
+  }
+
+  // Deprecated trust-header pattern.
+  if (!opts.trustProxy) {
+    for (var di = 0; di < DEPRECATED_TRUST_HEADERS.length; di += 1) {
+      var h = DEPRECATED_TRUST_HEADERS[di];
+      if (headers[h] !== undefined) {
+        issues.push({
+          kind: "deprecated-trust-header", severity: "warn", header: h,
+          snippet: "request carries `" + h + "` but trustProxy is " +
+                   "false — adopt RFC 7239 `Forwarded` or set " +
+                   "trustProxy explicitly",
+        });
+      }
+    }
+  }
+
+  return issues;
+}
+
+function create(opts) {
+  opts = opts || {};
+  var mode = opts.mode || "enforce";
+  var refuseOnHigh = opts.refuseOnHigh !== false && mode === "enforce";
+  var audit = opts.audit || null;
+  var resolved = {
+    maxHeaderCount: opts.maxHeaderCount || 100,                                  // allow:raw-byte-literal — header count ceiling
+    maxValueBytes:  opts.maxValueBytes  || 8 * 1024,                             // allow:raw-byte-literal — header value cap (8 KiB)
+    trustProxy:     !!opts.trustProxy,
+  };
+
+  return function headersMiddleware(req, res, next) {
+    var headers = req && req.headers ? req.headers : {};
+    var issues = _detectIssues(headers, resolved);
+    if (issues.length === 0) return next();
+
+    var hasHigh = false;
+    for (var i = 0; i < issues.length; i += 1) {
+      var iss = issues[i];
+      if (iss.severity === "high") hasHigh = true;
+      _emitAudit(audit, "middleware.headers.threat-detected",
+        iss.severity === "high" ? "blocked" : "audit", {
+          kind:    iss.kind,
+          header:  iss.header || null,
+          snippet: iss.snippet,
+          mode:    mode,
+        });
+    }
+
+    if (hasHigh && refuseOnHigh) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "application/json");
+      res.end(JSON.stringify({
+        error:  "header-threat-detected",
+        issues: issues.filter(function (i) { return i.severity === "high"; })
+                      .map(function (i) {
+                        return { kind: i.kind, header: i.header || null };
+                      }),
+      }));
+      return;
+    }
+    return next();
+  };
+}
+
+module.exports = { create: create };

package/lib/middleware/index.js

@@ -29,6 +29,7 @@ var csrfProtect = require("./csrf-protect");
 var dbRoleFor = require("./db-role-for");
 var errorHandler = require("./error-handler");
 var fetchMetadata = require("./fetch-metadata");
+var headers = require("./headers");
 var health = require("./health");
 var networkAllowlist = require("./network-allowlist");
 var rateLimit = require("./rate-limit");
@@ -50,6 +51,7 @@ module.exports = {
   requireAuth:      requireAuth.create,
   csrfProtect:      csrfProtect.create,
   fetchMetadata:    fetchMetadata.create,
+  headers:          headers.create,
   bodyParser:       bodyParser.create,
   health:           health.create,
   compression:      compression.create,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.7.48",
+  "version": "0.7.49",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:3da7281a-182d-463b-a5eb-166309f6fa76",
+  "serialNumber": "urn:uuid:edb0b995-1067-4678-bbbc-7072a4712f7a",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-05T21:55:22.735Z",
+    "timestamp": "2026-05-05T22:04:11.156Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.7.48",
+      "bom-ref": "@blamejs/core@0.7.49",
       "type": "library",
       "name": "blamejs",
-      "version": "0.7.48",
+      "version": "0.7.49",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.7.48",
+      "purl": "pkg:npm/%40blamejs/core@0.7.49",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.7.48",
+      "ref": "@blamejs/core@0.7.49",
       "dependsOn": []
     }
   ]