@blamejs/core 0.7.47 → 0.7.48

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.7.x
 
+- **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.
 
 - **0.7.46** (2026-05-05) — `b.guardTime` — RFC 3339 / ISO 8601 datetime identifier-safety primitive (KIND="identifier"). Validates user-supplied datetime strings destined for audit timestamps, scheduling, retention windows, query ranges, and cross-system event correlation. Threat catalog: shape malformation against the RFC 3339 §5.6 grammar; year-window overflow (default `[1970, 9999]`); naive datetime (no offset) refuse; non-UTC offset policy (strict requires `Z` / `+00:00`); leap-second `60` field policy (RFC 3339 §5.6 valid but parser-panic prone); excessive fractional precision cap (default 9 digits / nanoseconds); date-only and time-only refuse for full-datetime contexts; structural range violations (month / day-in-month / hour / minute / second); BIDI / zero-width / control / null-byte universal refuse. `sanitize` normalizes a space date/time separator to `T` and uppercases the trailing `z` UTC marker. Profiles: `strict` (refuse all of the above), `balanced` (refuse naive; audit non-UTC + leap + fractional + date/time-only), `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/cookies.js

@@ -342,9 +342,126 @@ function create(opts) {
   };
 }
 
+// parseSafe — threat-detecting inbound-cookie parser. Returns
+// { jar, issues } where every detected anomaly surfaces as an issue
+// instead of being silently dropped (as the lenient parse() does).
+//
+// Threat catalog applied to the inbound Cookie header:
+//   - Oversized header — total bytes exceed maxHeaderBytes (default 8 KiB).
+//   - Oversized pair — name + value exceeds NAME_LENGTH + VALUE_LENGTH cap.
+//   - Duplicate cookie name — RFC 6265 last-write-wins is the browser
+//     behavior, but two pairs with the same name in one Cookie header
+//     usually indicates cookie-tossing (attacker-set parent-domain
+//     cookie shadowing the legitimate one).
+//   - Malformed pair — missing `=` or empty name.
+//   - Forbidden chars in raw header — CR / LF / NUL injected through
+//     a downstream proxy.
+//   - Empty / non-string input — operator-misuse signal.
+//
+// Issue shape: { kind, severity: "high"|"warn", snippet, name? }.
+//
+// Operators wire it through `b.middleware.cookies` (the convenience
+// middleware below) or call directly when they want the issues list
+// without imposing a request lifecycle.
+function parseSafe(cookieHeader, opts) {
+  opts = opts || {};
+  var maxHeaderBytes = opts.maxHeaderBytes || C.BYTES.kib(8);
+  var maxNameBytes   = opts.maxNameBytes   || MAX_NAME_LENGTH;
+  var maxValueBytes  = opts.maxValueBytes  || MAX_VALUE_LENGTH;
+
+  if (typeof cookieHeader !== "string") {
+    return {
+      jar:    {},
+      issues: [{ kind: "bad-input", severity: "high",
+                 snippet: "cookie header is not a string" }],
+    };
+  }
+  if (cookieHeader.length === 0) return { jar: {}, issues: [] };
+
+  var issues = [];
+  var jar = Object.create(null);
+  var seen = Object.create(null);
+
+  if (Buffer.byteLength(cookieHeader, "utf8") > maxHeaderBytes) {
+    issues.push({
+      kind: "header-cap", severity: "high",
+      snippet: "Cookie header " + cookieHeader.length + " bytes exceeds " +
+               "maxHeaderBytes " + maxHeaderBytes,
+    });
+    return { jar: jar, issues: issues };
+  }
+  for (var hi = 0; hi < cookieHeader.length; hi += 1) {
+    var ch = cookieHeader.charCodeAt(hi);
+    if (ch === 0x0D || ch === 0x0A || ch === 0x00) {                             // allow:raw-byte-literal — CR / LF / NUL forbidden in cookie header
+      issues.push({
+        kind: "header-control-byte", severity: "high",
+        snippet: "Cookie header contains CR / LF / NUL — proxy-side " +
+                 "header injection vector",
+      });
+      return { jar: jar, issues: issues };
+    }
+  }
+
+  var pairs = cookieHeader.split(/;\s*/);
+  for (var i = 0; i < pairs.length; i += 1) {
+    var pair = pairs[i];
+    if (!pair) continue;
+    var eq = pair.indexOf("=");
+    if (eq < 0) {
+      issues.push({
+        kind: "pair-malformed", severity: "warn",
+        snippet: "cookie pair " + JSON.stringify(pair) + " missing `=`",
+      });
+      continue;
+    }
+    var k = pair.slice(0, eq).trim();
+    if (!k) {
+      issues.push({
+        kind: "pair-empty-name", severity: "warn",
+        snippet: "cookie pair has empty name",
+      });
+      continue;
+    }
+    var v = pair.slice(eq + 1).trim();
+    if (v.length >= 2 && v.charAt(0) === '"' && v.charAt(v.length - 1) === '"') {
+      v = v.slice(1, -1);
+    }
+    try { v = decodeURIComponent(v); }
+    catch (_e) { /* malformed encoding — keep raw */ }
+
+    if (Buffer.byteLength(k, "utf8") > maxNameBytes) {
+      issues.push({
+        kind: "name-cap", severity: "high", name: k,
+        snippet: "cookie name exceeds maxNameBytes " + maxNameBytes,
+      });
+      continue;
+    }
+    if (Buffer.byteLength(v, "utf8") > maxValueBytes) {
+      issues.push({
+        kind: "value-cap", severity: "high", name: k,
+        snippet: "cookie `" + k + "` value exceeds maxValueBytes " +
+                 maxValueBytes,
+      });
+      continue;
+    }
+    if (seen[k]) {
+      issues.push({
+        kind: "duplicate-name", severity: "high", name: k,
+        snippet: "cookie name `" + k + "` appears more than once — " +
+                 "browser last-write-wins; cookie-tossing class " +
+                 "(parent-domain cookie shadowing the legitimate one)",
+      });
+    }
+    seen[k] = true;
+    jar[k] = v;
+  }
+  return { jar: jar, issues: issues };
+}
+
 module.exports = {
   create:       create,
   parse:        parse,
+  parseSafe:    parseSafe,
   serialize:    serialize,
   CookieError:  CookieError,
 };

package/lib/middleware/cookies.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * b.middleware.cookies — inbound cookie-header threat detection.
+ *
+ * Sits in the request lifecycle and runs `b.cookies.parseSafe` against
+ * the inbound `Cookie` header. Threat detection always-on; the gate
+ * either refuses, audits, or logs the detected anomalies based on the
+ * operator's `mode`.
+ *
+ * Threats surfaced (see lib/cookies.js parseSafe):
+ *   - header-cap        — Cookie header exceeds maxHeaderBytes
+ *   - header-control-byte — CR / LF / NUL injected through proxy
+ *   - pair-malformed    — pair missing `=`
+ *   - pair-empty-name   — empty name
+ *   - name-cap          — cookie name exceeds maxNameBytes
+ *   - value-cap         — cookie value exceeds maxValueBytes
+ *   - duplicate-name    — name appears >1 time (cookie-tossing class)
+ *
+ * Side effects:
+ *   - req.cookieJar  — populated with the parsed jar (overwriteable)
+ *   - audit emission — one row per detected high-severity issue
+ *   - response       — refused requests get HTTP 400 + JSON body
+ *
+ *   var middleware = b.middleware.cookies({
+ *     mode:           "enforce",     // "enforce" | "audit-only" | "log-only"
+ *     audit:          b.audit,
+ *     maxHeaderBytes: 8 * 1024,
+ *     refuseOnHigh:   true,          // 400 if any high-severity issue
+ *   });
+ */
+
+var cookies = require("../cookies");
+var lazyRequire = require("../lazy-require");
+
+var observability = lazyRequire(function () { return require("../observability"); });
+void observability;
+
+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/cookies" },
+      outcome:  outcome,
+      metadata: metadata,
+    });
+  } catch (_e) { /* drop-silent — observability sink */ }
+}
+
+function create(opts) {
+  opts = opts || {};
+  var mode = opts.mode || "enforce";
+  var refuseOnHigh = opts.refuseOnHigh !== false && mode === "enforce";
+  var maxHeaderBytes = opts.maxHeaderBytes;
+  var maxNameBytes = opts.maxNameBytes;
+  var maxValueBytes = opts.maxValueBytes;
+  var audit = opts.audit || null;
+
+  return function cookiesMiddleware(req, res, next) {
+    var header = req && req.headers ? req.headers.cookie : "";
+    var rv = cookies.parseSafe(header || "", {
+      maxHeaderBytes: maxHeaderBytes,
+      maxNameBytes:   maxNameBytes,
+      maxValueBytes:  maxValueBytes,
+    });
+    req.cookieJar = rv.jar;
+
+    if (rv.issues.length === 0) return next();
+
+    var hasHigh = false;
+    for (var i = 0; i < rv.issues.length; i += 1) {
+      var iss = rv.issues[i];
+      if (iss.severity === "high") hasHigh = true;
+      _emitAudit(audit, "middleware.cookies.threat-detected",
+        iss.severity === "high" ? "blocked" : "audit", {
+          kind:    iss.kind,
+          name:    iss.name || null,
+          snippet: iss.snippet,
+          mode:    mode,
+        });
+    }
+
+    if (hasHigh && refuseOnHigh) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "application/json");
+      res.end(JSON.stringify({
+        error:  "cookie-threat-detected",
+        issues: rv.issues.map(function (i) {
+          return { kind: i.kind, severity: i.severity };
+        }),
+      }));
+      return;
+    }
+    return next();
+  };
+}
+
+module.exports = { create: create };

package/lib/middleware/index.js

@@ -22,6 +22,7 @@ var bearerAuth = require("./bearer-auth");
 var bodyParser = require("./body-parser");
 var botGuard = require("./bot-guard");
 var compression = require("./compression");
+var cookies = require("./cookies");
 var cors = require("./cors");
 var cspNonce = require("./csp-nonce");
 var csrfProtect = require("./csrf-protect");
@@ -52,6 +53,7 @@ module.exports = {
   bodyParser:       bodyParser.create,
   health:           health.create,
   compression:      compression.create,
+  cookies:          cookies.create,
   cspNonce:         cspNonce.create,
   sse:              sse.create,
   requestLog:       requestLog.create,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.7.47",
+  "version": "0.7.48",
   "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:49f1481c-f876-4567-878c-2f709b99fd4f",
+  "serialNumber": "urn:uuid:3da7281a-182d-463b-a5eb-166309f6fa76",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-05T21:48:20.338Z",
+    "timestamp": "2026-05-05T21:55:22.735Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.7.47",
+      "bom-ref": "@blamejs/core@0.7.48",
       "type": "library",
       "name": "blamejs",
-      "version": "0.7.47",
+      "version": "0.7.48",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.7.47",
+      "purl": "pkg:npm/%40blamejs/core@0.7.48",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.7.47",
+      "ref": "@blamejs/core@0.7.48",
       "dependsOn": []
     }
   ]