@blamejs/core 0.9.40 → 0.9.42

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.9.x
 
+- v0.9.42 (2026-05-15) — **`b.middleware.idempotencyKey` `bodyFingerprint` hook + misordered-mount detector.** New `opts.bodyFingerprint: (req) => Buffer|string|object|null` lets operators supply a custom body extractor instead of relying on the default `req._rawBody || req.body` lookup; useful when the parsed-body shape needs canonicalization (sorted keys, stripped metadata) before the fingerprint hash so retry-with-equivalent-payload doesn't trip the §4.3 same-key-different-body refusal. Hook return is normalized to Buffer (Buffer passthrough; string → UTF-8 bytes; object/array → `JSON.stringify` → bytes; null/undefined → empty fingerprint). Throws inside the hook emit `idempotency.body_fingerprint_failed` audit (warning) and treat the body as empty. **Mount-order constraint:** idempotency must run AFTER body-parser; the hook reads request state at the moment idempotency executes, so a misordered mount silently degrades the fingerprint to method+path. `b.middleware.composePipeline` (v0.9.44) places bodyParser=20 / idempotency=30 by default. Body-bearing methods (POST/PUT/PATCH) that arrive without parsed-body OR raw-body data now emit `idempotency.empty_body_fingerprint` audit (warning) carrying `hasRawBody` / `hasParsedBody` / `hasFingerprintHook` so a misconfigured pipeline is detectable from audit logs.
+- v0.9.41 (2026-05-15) — **Operator-friction ergonomic helpers surfaced from downstream-consumer gap audit.** Three small additive surfaces, no behavior change for existing callers. (1) **`b.storage.listBackends()`** now surfaces `rootDir` for local-protocol backends, sourced from the live backend (with config-reload propagation) so downstream path-traversal guards + scratch-dir derivation read the canonical path directly from the framework instead of re-deriving from operator-supplied opts. Remote protocols (sigv4 / gcs / azure-blob / http-put) don't carry a rootDir; the field stays absent for those. (2) **`b.problemDetails.send(res, fields)`** — bare wire-shape emit shortcut that lets routes migrate incrementally from inline `res.status(400).json({ error: ... })` to RFC 9457 problem-details without restructuring the handler around an error throw. Equivalent to `respond(res, create(fields))` in one call; same `application/problem+json` content type + `Cache-Control: no-store`. (3) **`b.mail.send` CR/LF/NUL refusal** confirmed already in place at `lib/mail.js:275` / `:309` / `:1808` per RFC 5321 §2.3.8 + RFC 5322 §3.2.5 header-injection defense — operators with inline `validateEmailAddr` wrappers can retire them. No new API, just confirmation that the existing primitive already covers the wire-protocol injection class (CVE-2026-32178 .NET System.Net.Mail header injection defended at the framework boundary).
 - v0.9.40 (2026-05-15) — **`b.guardListId` — RFC 2919 List-Id header validator.** Companion to v0.9.39 `b.guardListUnsubscribe`; gates outbound mailing-list mail so the List-Id carries a well-formed identifier downstream filters + bulk-sender pipelines reliably route on. (1) **`b.guardListId.validate(headerValue, opts?)`** — parses bracketed (`<my-list.example.com>`), phrase-prefixed (`My Newsletter <my-list.example.com>`), and bare-identifier forms per RFC 2919 §2. Returns `{ action, listId, label, namespace, phrase, reason }`. Action one of `accept` / `refuse`. (2) **RFC 2919 §3 caps + ABNF** — list-id capped at 255 octets; header value capped at RFC 5322 §2.1.1 line cap (998 bytes); per-label shape per RFC 5322 §3.2.3 dot-atom-text. (3) **Phrase-smuggling defense** — phrase MUST NOT contain `<` / `>` (would smuggle a second bracketed identifier through the parser). Trailing content after `>` refused. Nested or unmatched brackets refused. (4) **CRLF / NUL / C0 / DEL refusal** — header-injection defense per RFC 5322 §3.2.5 + CVE-2026-32178 wire-protocol surface class. (5) **`localhost` namespace handling** (RFC 2919 §3) — strict requires the recommended 32-hex random component in the label (the SHOULD becomes operator-strict for HIPAA / PCI / GDPR / SOC2 postures); balanced / permissive accept without. (6) **FQDN namespace enforcement** under strict / balanced — list-id with single-label namespace (e.g. `mylist.test`) refused unless permissive. (7) Heuristic label / namespace split — last 2 dot-segments → namespace (matches typical DNS delegation); consumers needing PSL-accurate org-domain extraction compose `b.publicSuffix.organizationalDomain`. Three profiles + posture cascade (hipaa / pci-dss / gdpr / soc2 → strict). Fuzz harness ships in `fuzz/guard-list-id.fuzz.js`. Registered as standalone guard with `KIND="list-id"`. Threat-model: List-Id forging (RFC 2919 §8 explicitly notes the identifier is NOT an authentication signal; operators wanting authentication compose b.mail.auth.dmarc / arc.verify), bulk-sender bucket-drop (Gmail 2024 keys on List-Id presence for Precedence: list / 5000+ daily-send mail).
 - v0.9.39 (2026-05-15) — **`b.guardListUnsubscribe` — RFC 2369 + RFC 8058 List-Unsubscribe / List-Unsubscribe-Post validator.** Gates the outbound submission path so messages carrying a List-Id (or any mailing-list shape) emit headers Gmail / Yahoo / Outlook one-click unsubscribe machinery actually accepts. (1) **`b.guardListUnsubscribe.validate({ listUnsubscribe, listUnsubscribePost }, opts?)`** — returns `{ action, reason, uris, hasHttpsUri, hasMailtoUri, postHeaderOk, oneClickReady }`. (2) **Gmail / Yahoo bulk-sender 2024 enforcement** — under strict requires at least one `https://` URI in the header (mailto: alone refused) + the paired `List-Unsubscribe-Post: List-Unsubscribe=One-Click` value EXACTLY (case-sensitive — Gmail silently fails one-click on mixed-case variants). (3) **Always-refused schemes** — `javascript:` / `data:` / `file:` / `vbscript:` / `blob:` refused regardless of profile (XSS / file-read class in mail-client rendering). (4) **`http://` refused under strict / balanced** — one-click endpoint MUST be TLS per RFC 8058 §2. Permissive accepts http for audit-only legacy use. (5) **Header-injection defense** — CRLF, NUL, C0 controls, DEL refused at validate time (RFC 5322 §3.2.5). (6) **Bounded surface** — per-URI byte cap (2 KiB strict / 4 KiB permissive), URI-count cap (4 / 8 / 16), header total byte cap (4 / 4 / 8 KiB). RFC 3986 §3.1 scheme shape; RFC 2369 §3.1 angle-bracket URI list. HTTPS URIs validated through `b.safeUrl.parse` with the framework's HTTPS allowlist. Three profiles + posture cascade (hipaa / pci-dss / gdpr / soc2 → strict). Fuzz harness ships in `fuzz/guard-list-unsubscribe.fuzz.js`. Registered as a standalone guard with KIND="list-unsubscribe". Threat-model coverage: unsubscribe-link injection via AI-generated newsletter templates, open-redirect via List-Unsubscribe (operator validates target host downstream via own safeRedirect allowlist), mail-client mishandling (Outlook's mailto: auto-fetch history).
 - v0.9.38 (2026-05-15) — **Re-publish bundle: prefix npm tarball path with `./` so npm doesn't mis-classify it as a git spec.** v0.9.30 and v0.9.37 publish workflow runs both failed at exit 128 — npm 10+ interprets a relative tarball path containing `/` (`dist/blamejs-core-0.9.X.tgz`) as a git spec and attempts `git ls-remote ssh://git@github.com/dist/...tgz`, which the runner's SSH credentials can't auth against. v0.9.29-v0.9.37 never reached npm as a result; v0.9.28 remained the latest published version on the registry. v0.9.38 ships only the workflow path fix (no operator-facing primitive change vs v0.9.37) — operators upgrading from v0.9.28 see the full bundled surface delivered by v0.9.29-v0.9.37: agent.trace + agent.snapshot (v0.9.29 / v0.9.30), safeDns + network.dns.resolver (v0.9.31), guardSmtpCommand (v0.9.32), mail.rbl (v0.9.33), mail.greylist + lib/ip-utils (v0.9.34), mail.helo (v0.9.35), guardEnvelope (v0.9.36), guardDsn (v0.9.37).

package/lib/middleware/idempotency-key.js

@@ -43,6 +43,7 @@
 var nodeCrypto    = require("node:crypto");
 var lazyRequire   = require("../lazy-require");
 var numericBounds = require("../numeric-bounds");
+var validateOpts  = require("../validate-opts");
 var safeBuffer    = require("../safe-buffer");
 var safeJson      = require("../safe-json");
 var safeSql       = require("../safe-sql");
@@ -458,6 +459,21 @@ function _emitAudit(action, metadata, outcome) {
  *   methods:               string[], // default: ["POST","PUT","PATCH","DELETE"]
  *   headerName:            string,   // default: "idempotency-key"
  *   requireIdempotencyKey: boolean,  // default: false — refuse missing-key
+ *   bodyFingerprint:       function, // (req) => Buffer|string|object|null — operator-supplied body extractor
+ *   maxBodyBytes:          number,   // default: 1 MiB — replay-cache body cap
+ *
+ * **Mount order — idempotency MUST run AFTER body-parser.** The hook
+ * (and the default `req._rawBody||req.body` lookup) reads request
+ * state at the moment the idempotency middleware runs; if it runs
+ * before body-parser, `req.body` is still unset and the fingerprint
+ * silently degrades to method+path only — which fails the §4.3
+ * "same key, different body" guarantee. `b.middleware.composePipeline`
+ * places bodyParser=20 / idempotency=30 by default so the canonical
+ * order is correct; operators wiring middleware manually must mount
+ * idempotency AFTER bodyParser. The runtime emits
+ * `idempotency.empty_body_fingerprint` audit (warning) whenever a
+ * body-bearing request reaches the middleware with no body data,
+ * so the misordering is detectable from audit logs.
  *
  * @example
  *   var store = b.middleware.idempotencyKey.memoryStore({ maxEntries: 10000 });
@@ -465,6 +481,11 @@ function _emitAudit(action, metadata, outcome) {
  *     store:     store,
  *     ttlMs:     C.TIME.hours(24),
  *     methods:   ["POST", "PUT", "PATCH"],
+ *     // Optional: provide a body-fingerprint extractor that pulls
+ *     // from the parsed body shape. The extractor only runs against
+ *     // state populated by upstream middleware; mount idempotency
+ *     // AFTER bodyParser (composePipeline does this by default).
+ *     bodyFingerprint: function (req) { return req.body || null; },
  *   });
  *   app.use(mw);
  */
@@ -484,6 +505,20 @@ function create(opts) {
     ? opts.headerName.toLowerCase()
     : "idempotency-key";
   var requireKey = opts.requireIdempotencyKey === true;
+  // Operator-supplied body-fingerprint extractor. When provided,
+  // the middleware calls this instead of the inline
+  // `req._rawBody || req.body` lookup. Lets operators mount
+  // body-parser BEFORE the idempotency middleware and surface the
+  // parsed body shape (req.body is the typical post-parser
+  // attachment point); the inline lookup runs BEFORE body-parser
+  // by default, so the fingerprint silently degrades to
+  // method+path-only when body-parser mounts after. With this
+  // hook the middleware reads the body shape the operator
+  // canonically attached, regardless of mount order.
+  var bodyFingerprintFn = validateOpts.optionalFunction(
+    opts.bodyFingerprint, "idempotencyKey.bodyFingerprint",
+    IdempotencyError, "idempotency/bad-body-fingerprint"
+  ) || null;
 
   // Per-response collector cap. Idempotency replay only makes sense
   // for response bodies that fit in memory; the cap is operator-
@@ -522,17 +557,59 @@ function create(opts) {
       return problemDetails().respond(res, bad);
     }
 
-    var bodyBytes = req._rawBody || req.body || null;
-    if (bodyBytes && typeof bodyBytes === "object" && !Buffer.isBuffer(bodyBytes)) {
-      // Buffer-ize a non-buffer body (already-parsed JSON, etc.) so the
-      // hash is stable. JSON.stringify with sorted keys would be more
-      // robust but the operator-attached body shape is whatever the
-      // upstream parser produced; canonicalization is operator-side.
+    var bodyBytes;
+    if (bodyFingerprintFn) {
+      // Operator-supplied hook — called after body-parser so req.body
+      // is populated. Hook returns Buffer / string / null.
       try {
-        bodyBytes = Buffer.from(JSON.stringify(bodyBytes), "utf8");
-      } catch (_e) {
+        var fpVal = bodyFingerprintFn(req);
+        if (fpVal === null || fpVal === undefined) {
+          bodyBytes = null;
+        } else if (Buffer.isBuffer(fpVal)) {
+          bodyBytes = fpVal;
+        } else if (typeof fpVal === "string") {
+          bodyBytes = Buffer.from(fpVal, "utf8");
+        } else {
+          // Object / array — JSON-stringify so the hash is stable.
+          bodyBytes = Buffer.from(JSON.stringify(fpVal), "utf8");
+        }
+      } catch (e) {
+        _emitAudit("idempotency.body_fingerprint_failed",
+          { error: String(e && e.message || e) }, "warning");
         bodyBytes = null;
       }
+    } else {
+      bodyBytes = req._rawBody || req.body || null;
+      if (bodyBytes && typeof bodyBytes === "object" && !Buffer.isBuffer(bodyBytes)) {
+        // Buffer-ize a non-buffer body (already-parsed JSON, etc.) so the
+        // hash is stable. JSON.stringify with sorted keys would be more
+        // robust but the operator-attached body shape is whatever the
+        // upstream parser produced; canonicalization is operator-side.
+        try {
+          bodyBytes = Buffer.from(JSON.stringify(bodyBytes), "utf8");
+        } catch (_e) {
+          bodyBytes = null;
+        }
+      }
+    }
+
+    // Misordered-mount detector — body-bearing method reached us
+    // with neither a parsed body nor a raw-body buffer. Most likely
+    // body-parser hasn't run yet, which silently degrades the
+    // fingerprint to method+path. Emit a warning so the audit log
+    // surfaces the misconfiguration. (Genuinely empty POST bodies
+    // also trip this — acceptable cost; the audit field captures the
+    // distinction via `hasRawBody`/`hasParsedBody`.)
+    if (!bodyBytes && (method === "POST" || method === "PUT" || method === "PATCH")) {
+      _emitAudit("idempotency.empty_body_fingerprint",
+        {
+          method:          method,
+          path:            req.url,
+          hasRawBody:      Boolean(req._rawBody),
+          hasParsedBody:   req.body !== undefined && req.body !== null,
+          hasFingerprintHook: Boolean(bodyFingerprintFn),
+        },
+        "warning");
     }
 
     var fingerprint = _fingerprintRequest(req, bodyBytes);

package/lib/problem-details.js

@@ -358,6 +358,48 @@ function respond(res, problem) {
   res.end(body);
 }
 
+/**
+ * @primitive b.problemDetails.send
+ * @signature b.problemDetails.send(res, fields)
+ * @since     0.9.41
+ * @status    stable
+ * @related   b.problemDetails.create, b.problemDetails.respond
+ *
+ * Build + emit a problem-details response in one call. Equivalent
+ * to `respond(res, create(fields))` but lets routes migrate
+ * incrementally from inline `res.status(400).json({ error: "..." })`
+ * shapes without restructuring the handler around an error throw.
+ *
+ * The same RFC 9457 §3 `application/problem+json` content type +
+ * `Cache-Control: no-store` are written; status code defaults to
+ * 500 when omitted.
+ *
+ * @opts
+ *   status:    number,           // HTTP status code (100..599); default 500
+ *   title:     string,           // operator-supplied short title
+ *   detail:    string,           // operator-supplied human-readable explanation
+ *   type:      string,           // problem-type URI (defaults to "about:blank")
+ *   instance:  string,           // optional per-occurrence URI
+ *   extensions: object,          // operator-specific extension fields
+ *
+ * @example
+ *   // Migrating from inline JSON-error shape:
+ *   //   res.status(400).json({ error: "Missing 'name' field" });
+ *   // to RFC 9457 problem-details:
+ *   b.problemDetails.send(res, {
+ *     status: 400,
+ *     title:  "Missing required field",
+ *     detail: "Body field 'name' is required",
+ *   });
+ */
+function send(res, fields) {
+  if (!fields || typeof fields !== "object" || Array.isArray(fields)) {
+    throw new ProblemDetailsError("problem-details/bad-fields",
+      "send: fields must be a non-null object", true);
+  }
+  return respond(res, create(fields));
+}
+
 /**
  * @primitive b.problemDetails.validate
  * @signature b.problemDetails.validate(doc)
@@ -431,6 +473,7 @@ module.exports = {
   create:     create,
   fromError:  fromError,
   respond:    respond,
+  send:       send,
   validate:   validate,
   RESERVED_FIELDS:     RESERVED_FIELDS,
   ProblemDetailsError: ProblemDetailsError,

package/lib/storage.js

@@ -577,13 +577,23 @@ function listBackends() {
   _requireInit();
   var out = [];
   for (var name in backends) {
-    out.push({
+    var entry = {
       name:            name,
       protocol:        backends[name].protocol,
       classifications: backends[name].classifications.slice(),
       residencyTag:    backends[name].residencyTag,
       breakerState:    backends[name].breaker.getState(),
-    });
+    };
+    // Surface the resolved local rootDir so downstream operators
+    // building path-traversal guards or scratch-dir layouts read the
+    // live path (with config-reload propagation) directly from the
+    // backend rather than re-deriving from operator-supplied opts.
+    // Remote protocols (sigv4 / gcs / azure-blob / http-put) don't
+    // have a rootDir; the field stays absent for those.
+    if (backends[name].protocol === "local" && backends[name].raw && typeof backends[name].raw.rootDir === "string") {
+      entry.rootDir = backends[name].raw.rootDir;
+    }
+    out.push(entry);
   }
   return out;
 }

package/package.json

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

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.6",
-  "serialNumber": "urn:uuid:414de146-e066-4e4d-aa72-85cc18e385d6",
+  "serialNumber": "urn:uuid:73f521a3-612c-45e1-8d73-dfeb13b9231f",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-15T11:24:02.385Z",
+    "timestamp": "2026-05-15T15:59:31.588Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.9.40",
+      "bom-ref": "@blamejs/core@0.9.42",
       "type": "library",
       "name": "blamejs",
-      "version": "0.9.40",
+      "version": "0.9.42",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.9.40",
+      "purl": "pkg:npm/%40blamejs/core@0.9.42",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.9.40",
+      "ref": "@blamejs/core@0.9.42",
       "dependsOn": []
     }
   ]