@blamejs/core 0.13.46 → 0.14.0

package/CHANGELOG.md

@@ -6,6 +6,10 @@ Pre-1.0 the surface is intentionally evolving — every release may
 change something operators depend on. Read each entry before
 upgrading across more than a few patches at a time.
 
+## v0.14.x
+
+- v0.14.0 (2026-05-29) — **Operator-configurable header and field names across SSE, request-id, rate-limit, age-gate, AI-Act disclosure, GraphQL federation, and the HTTP cache.** This release makes operator-facing identifiers that were hardcoded configurable. The framework already let operators rename most names (CSRF cookie/field, cookie parser, i18n header/query/cookie, mTLS CA name, and so on); this closes the remaining gaps so a custom or framework-specific name is never frozen. Every new option defaults to the value emitted today, so upgrading changes no behavior — these are additive knobs. It also fixes a request-id asymmetry (the response header is now written on the same name the inbound id is read from) and wires an SSE proxy-buffering option whose escape hatch was documented but never implemented. **Added:** *Configurable cache-status header on the HTTP client* — The outbound HTTP client annotated every cached response with a hardcoded `x-blamejs-cache: HIT|MISS|STALE|REVALIDATED` header. `b.httpClient.cache.create` now takes `statusHeader` (default "x-blamejs-cache") — pass a custom name (e.g. "x-cache") to rename it, or null/false to suppress it entirely. The decision remains available programmatically on `res.cacheStatus`. · *Configurable rate-limit header names* — `b.middleware.rateLimit` emitted the de-facto `X-RateLimit-Limit` / `X-RateLimit-Remaining` headers (which are not RFC-pinned). It now accepts `headerPrefix` (default "X-RateLimit-") so operators can match the unprefixed IETF-draft `RateLimit-*` names or an upstream gateway's convention; the limit/remaining pair is always built from the same prefix. · *Configurable age-gate and AI-Act disclosure header names* — `b.middleware.ageGate` now takes `privacyPostureHeader` (default "X-Privacy-Posture"; null/false to suppress), and `b.middleware.aiActDisclosure` takes `headerPrefix` (default "AI-Act-") that prefixes the emitted Notice / Article / Policy headers. The EU AI Act mandates the disclosure, not the HTTP spelling, so operators matching a downstream convention can rename these. · *Configurable GraphQL-federation replay-nonce header* — `b.graphqlFederation.guardSdl` read the replay nonce from the Apollo-vendor `x-apollographql-router-nonce` header with no override. It now accepts `nonceHeader` (default unchanged) so an operator fronting the gateway with a non-Apollo router can point the replay check at their own header. · *SSE proxy-buffering opt-out* — `b.sse.create` and `b.middleware.sse` set `X-Accel-Buffering: no` (the nginx hint that disables proxy buffering). They now accept `proxyBuffer` (default true) — pass false when not behind nginx, or when buffering is controlled at the load balancer, to suppress the nginx-specific header. The opt-out was previously referenced in the documentation but not implemented. **Fixed:** *Request-id middleware reflects the configured header name* — `b.log.middleware` read the inbound request id from a configurable `headerName` but always wrote the response on the literal `X-Request-Id`. An operator who set a custom `headerName` (e.g. `X-Correlation-Id`) therefore read from one header and emitted another. The response is now written on the same configured name; the default remains `X-Request-Id`, so deployments that did not set `headerName` are unaffected.
+
 ## v0.13.x
 
 - v0.13.46 (2026-05-29) — **`createApp` now wires the documented security middleware ON by default — CSRF, CSP nonce, cookie parser, fetch-metadata, and body parser.** The README has long described a security middleware stack as "wired by createApp", but createApp only mounted request-ID, security-headers, and bot-guard by default — CSRF protection, the CSP nonce, the threat-aware cookie parser, the fetch-metadata guard, and the body parser were documented but not actually wired. This release closes that gap: createApp now mounts all of them by default, in dependency order (cookies, CSP nonce, fetch-metadata, then body parser, then CSRF last so it can read a body-field token). This is a behavior change — apps built with createApp now enforce CSRF on state-changing requests by default. Each layer is configurable via opts.middleware.<name> (operator cookie and field names flow straight through — nothing is hardcoded) or can be turned off with false, and disabling a security default now emits an app.middleware.disabled audit event. Every layer is idempotent: an operator who also mounts one of these inside opts.routes gets a no-op second mount rather than a double-apply. The default CSRF is a double-submit cookie that auto-skips requests carrying an Authorization header or no cookies at all, which are not CSRF-able, so token-authenticated API clients are not rejected. The README middleware list is now an accurate description of what createApp wires. **Added:** *Idempotent security middleware* — The cookie parser, CSP nonce, fetch-metadata, and CSRF middleware are now idempotent within a request: if one has already run (because createApp wired it and an operator also mounted it), the second instance is a no-op rather than re-parsing, re-generating a nonce, or issuing a second CSRF cookie. This lets an application compose its own middleware order on top of createApp's defaults without double-applying. The body parser already had this behavior. **Changed:** *createApp wires CSRF, CSP nonce, cookie parser, fetch-metadata, and body parser by default (breaking)* — Applications constructed with b.createApp now mount, in order: the threat-aware cookie parser, the CSP nonce generator, the fetch-metadata resource-isolation guard, the body parser (JSON / urlencoded / text / multipart), and CSRF protection — in addition to the request-ID, security-headers, and bot-guard layers already wired. The ordering guarantees CSRF runs after the body parser so a body-field token is available. This is a behavior change: state-changing requests (POST / PUT / DELETE / PATCH) that carry a session cookie are now CSRF-validated by default. Each layer is configured through opts.middleware.<name> (an object passes operator options straight through; cookie and field names are not hardcoded) or disabled with false. Operators who were mounting these middleware themselves inside opts.routes do not need to change anything — the second mount is now a no-op (see idempotency below). · *Default CSRF auto-skips token-authenticated and cookieless requests* — The CSRF middleware gains a skipStateless option (default false; createApp's default wiring sets it true). When on, token validation is skipped for requests that carry an Authorization header or no Cookie header at all — such requests are not CSRF-able, because CSRF abuses a victim's ambient cookie credential and these have none. The token is still issued on safe methods so a later cookie-authenticated browser flow works. Cross-site form CSRF is unaffected: the browser auto-sends the victim's cookies, so an attack request always carries a Cookie header and is validated. · *Disabling a default security middleware is audited* — Passing false for one of the security-on-by-default middleware (for example middleware: { csrf: false }) now emits an app.middleware.disabled audit event naming the middleware, so a weakened posture leaves a trace in the audit chain rather than being silent.

package/lib/graphql-federation.js

@@ -116,6 +116,7 @@ function _readBody(req, errorClass) {
  *   publicSchemaOk:   boolean,                                       // default false — explicit override to publish the SDL
  *   routerToken:      string,                                        // required unless publicSchemaOk; 32+ chars
  *   nonceStore:       { has(nonce): bool, remember(nonce, ttlMs) },  // optional — replay protection
+ *   nonceHeader:      string,                                        // default "x-apollographql-router-nonce" — request header carrying the replay nonce
  *   nonceTtlMs:       number,                                        // default 5 minutes
  *   errorClass:       Function,                                      // default GraphqlFederationError
  *   audit:            boolean,                                       // default true
@@ -141,6 +142,12 @@ function guardSdl(opts) {
   numericBounds.requirePositiveFiniteIntIfPresent(opts.nonceTtlMs, "graphqlFederation.guardSdl: opts.nonceTtlMs", errorClass, "BAD_TTL");
   var nonceTtlMs = opts.nonceTtlMs || C.TIME.minutes(5);
   var auditOn = opts.audit !== false;
+  // The replay nonce is read from the Apollo-router convention header by
+  // default, but `x-apollographql-router-nonce` is a vendor name, not a
+  // spec one — operators fronting the gateway with a different router send
+  // the nonce under their own header. Lowercased to match Node's header keys.
+  var nonceHeader = (typeof opts.nonceHeader === "string" && opts.nonceHeader.length > 0)
+    ? opts.nonceHeader.toLowerCase() : "x-apollographql-router-nonce";
 
   function _emitDenied(req, reason, metadata) {
     if (!auditOn) return;
@@ -190,7 +197,7 @@ function guardSdl(opts) {
         }
 
         if (nonceStore) {
-          var nonce = req.headers && req.headers["x-apollographql-router-nonce"];
+          var nonce = req.headers && req.headers[nonceHeader];
           if (typeof nonce !== "string" || nonce.length < NONCE_MIN_LEN || nonce.length > NONCE_MAX_LEN) {
             _emitDenied(req, "missing nonce", {});
             return _refuse(res, 401, "graphql federation: nonce required");

package/lib/http-client-cache.js

@@ -545,6 +545,7 @@ function memoryStore(opts) {
  *   revalidateInBackground: true,          // s-w-r kicks off background revalidation
  *   audit:                  undefined,     // audit sink with safeEmit({...})
  *   observability:          undefined,     // optional { event, safeEvent }
+ *   statusHeader:           "x-blamejs-cache", // response header carrying the cache decision; null/false to suppress, or a custom name (e.g. "x-cache")
  *
  * @example
  *   var cache = b.httpClient.cache.create({
@@ -585,6 +586,21 @@ function create(opts) {
   var revalidateBackground = opts.revalidateInBackground !== false;  // default true
   var audit               = opts.audit || null;
   var obs                 = opts.observability || null;
+  // statusHeader (default "x-blamejs-cache") names the response header that
+  // carries the cache decision (MISS/HIT/STALE/REVALIDATED). The decision is
+  // also on res.cacheStatus programmatically. Pass null/false to suppress the
+  // header, or a string to rename it (e.g. "x-cache"). Lowercased for the wire.
+  var statusHeader;
+  if (opts.statusHeader === null || opts.statusHeader === false) {
+    statusHeader = null;
+  } else if (opts.statusHeader === undefined) {
+    statusHeader = "x-blamejs-cache";
+  } else if (typeof opts.statusHeader === "string" && opts.statusHeader.length > 0) {
+    statusHeader = opts.statusHeader.toLowerCase();
+  } else {
+    throw _hcErr("httpclient/cache-bad-opts",
+      "cache.create: statusHeader must be a non-empty string, or null/false to suppress");
+  }
 
   function _emit(action, outcome, metadata) {
     if (!audit || typeof audit.safeEmit !== "function") return;
@@ -825,6 +841,7 @@ function create(opts) {
     store:                  store,
     audit:                  audit,
     observability:          obs,
+    statusHeader:           statusHeader,
 
     // ---- Lookup / store / revalidation flow ----
     //

package/lib/http-client.js

@@ -849,9 +849,12 @@ function _cacheEligibleMethod(method) {
 
 // Wrap an outbound headers object with the framework's cache-decision
 // markers. Mutates a copy; never the original.
-function _withCacheHeaders(res, status, ageSeconds) {
+function _withCacheHeaders(res, status, ageSeconds, statusHeader) {
   var headers = Object.assign({}, res.headers || {});
-  headers["x-blamejs-cache"] = status;
+  // statusHeader defaults to "x-blamejs-cache"; the cache instance can rename
+  // it or set it null to suppress (the decision is also on res.cacheStatus).
+  var name = (statusHeader === undefined) ? "x-blamejs-cache" : statusHeader;
+  if (name) headers[name] = status;
   if (typeof ageSeconds === "number" && ageSeconds >= 0) {
     headers["age"] = String(Math.floor(ageSeconds));
   }
@@ -893,7 +896,7 @@ function _runWithCache(opts, maxRedirects, runAfter) {
     catch (_e) { /* drop-silent */ }
     return _doNetwork(null).then(function (boxed) {
       _maybeStore(cache, method, opts.url, requestHeaders, boxed.res);
-      return runAfter(boxed.finalOpts, _withCacheHeaders(boxed.res, "MISS"));
+      return runAfter(boxed.finalOpts, _withCacheHeaders(boxed.res, "MISS", undefined, cache.statusHeader));
     });
   }
 
@@ -907,7 +910,7 @@ function _runWithCache(opts, maxRedirects, runAfter) {
     catch (_e2) { /* drop-silent */ }
     return _doNetwork(null).then(function (boxed) {
       _maybeStore(cache, method, opts.url, requestHeaders, boxed.res);
-      return runAfter(boxed.finalOpts, _withCacheHeaders(boxed.res, "MISS"));
+      return runAfter(boxed.finalOpts, _withCacheHeaders(boxed.res, "MISS", undefined, cache.statusHeader));
     });
   }
 
@@ -923,7 +926,7 @@ function _runWithCache(opts, maxRedirects, runAfter) {
       body:       Buffer.isBuffer(entry.body) ? Buffer.from(entry.body) : entry.body,
       cacheStatus: "HIT",
     };
-    return Promise.resolve(runAfter(opts, _withCacheHeaders(hitRes, "HIT", age)));
+    return Promise.resolve(runAfter(opts, _withCacheHeaders(hitRes, "HIT", age, cache.statusHeader)));
   }
 
   // 4. Stale or must-revalidate. Within stale-while-revalidate or
@@ -957,7 +960,7 @@ function _runWithCache(opts, maxRedirects, runAfter) {
         /* background revalidation best-effort; swallow */
       });
     });
-    return Promise.resolve(runAfter(opts, _withCacheHeaders(staleRes, "STALE", ageStale)));
+    return Promise.resolve(runAfter(opts, _withCacheHeaders(staleRes, "STALE", ageStale, cache.statusHeader)));
   }
 
   // 5. Inline conditional revalidation. Build If-None-Match /
@@ -974,11 +977,11 @@ function _runWithCache(opts, maxRedirects, runAfter) {
                       : (rev.refreshed || entry).body,
         cacheStatus: "REVALIDATED",
       };
-      return runAfter(opts, _withCacheHeaders(revRes, "REVALIDATED", ageRev));
+      return runAfter(opts, _withCacheHeaders(revRes, "REVALIDATED", ageRev, cache.statusHeader));
     }
     if (rev.kind === "fresh-response") {
       _maybeStore(cache, method, opts.url, requestHeaders, rev.res);
-      return runAfter(rev.finalOpts || opts, _withCacheHeaders(rev.res, "MISS"));
+      return runAfter(rev.finalOpts || opts, _withCacheHeaders(rev.res, "MISS", undefined, cache.statusHeader));
     }
     // rev.kind === "error" — try stale-if-error.
     var sieMs = (evaluation.sieWindowMs || 0);
@@ -994,7 +997,7 @@ function _runWithCache(opts, maxRedirects, runAfter) {
         body:       Buffer.isBuffer(entry.body) ? Buffer.from(entry.body) : entry.body,
         cacheStatus: "STALE",
       };
-      return runAfter(opts, _withCacheHeaders(sieRes, "STALE", ageErr));
+      return runAfter(opts, _withCacheHeaders(sieRes, "STALE", ageErr, cache.statusHeader));
     }
     return Promise.reject(rev.error);
   });

package/lib/log.js

@@ -376,7 +376,12 @@ function create(opts) {
 
     function middleware(mwOpts) {
       mwOpts = mwOpts || {};
-      var headerName = (mwOpts.headerName || "x-request-id").toLowerCase();
+      // Read and write the SAME header. The raw form keeps the operator's
+      // casing (or the canonical "X-Request-Id" default) for the response;
+      // the lowercased form matches Node's request-header keys for the read.
+      var rawHeaderName = (typeof mwOpts.headerName === "string" && mwOpts.headerName.length > 0)
+        ? mwOpts.headerName : "X-Request-Id";
+      var headerName = rawHeaderName.toLowerCase();
       var setOnRes   = mwOpts.setHeader !== false;
       var generate   = typeof mwOpts.generate === "function"
         ? mwOpts.generate
@@ -395,7 +400,7 @@ function create(opts) {
         id = safeBuffer.stripCrlf(String(id));
         req.id = id;
         if (setOnRes && typeof res.setHeader === "function") {
-          try { res.setHeader("X-Request-Id", id); } catch (_e) { /* header may be locked */ }
+          try { res.setHeader(rawHeaderName, id); } catch (_e) { /* header may be locked */ }
         }
         runWithRequestId(id, function () { next(); });
       };

package/lib/middleware/age-gate.js

@@ -70,6 +70,7 @@ var AgeGateError = defineClass("AgeGateError", { alwaysPermanent: true });
  *     hasParentalConsent: function(req): boolean,
  *     skipPaths:          string[],
  *     errorMessage:       string,
+ *     privacyPostureHeader: string,                     // default "X-Privacy-Posture"; null/false to suppress
  *     audit:              boolean,                      // default true
  *   }
  *
@@ -87,7 +88,7 @@ function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
     "audit", "getAge", "requireAge", "consentRequired",
-    "hasParentalConsent", "skipPaths", "errorMessage",
+    "hasParentalConsent", "skipPaths", "errorMessage", "privacyPostureHeader",
   ], "middleware.ageGate");
 
   if (typeof opts.getAge !== "function") {
@@ -104,6 +105,17 @@ function create(opts) {
   var auditOn = opts.audit !== false;
   var errorMessage = typeof opts.errorMessage === "string" && opts.errorMessage.length > 0
     ? opts.errorMessage : "service unavailable without parental consent";
+  // privacyPostureHeader (default "X-Privacy-Posture") names the response
+  // header carrying the below-threshold classification. Pass null/false to
+  // suppress it, or a string to rename it for a downstream convention.
+  var privacyPostureHeader;
+  if (opts.privacyPostureHeader === null || opts.privacyPostureHeader === false) {
+    privacyPostureHeader = null;
+  } else if (typeof opts.privacyPostureHeader === "string" && opts.privacyPostureHeader.length > 0) {
+    privacyPostureHeader = opts.privacyPostureHeader;
+  } else {
+    privacyPostureHeader = "X-Privacy-Posture";
+  }
 
   function _shouldSkip(req) {
     if (skipPaths.length === 0) return false;
@@ -148,7 +160,7 @@ function create(opts) {
       if (typeof res.setHeader === "function") {
         res.setHeader("Cache-Control",   "private, no-store");
         res.setHeader("Referrer-Policy", "no-referrer");
-        res.setHeader("X-Privacy-Posture", classification);
+        if (privacyPostureHeader) res.setHeader(privacyPostureHeader, classification);
       }
     }
 

package/lib/middleware/ai-act-disclosure.js

@@ -66,6 +66,7 @@ var audit     = lazyRequire(function () { return require("../audit"); });
  *     mode:         "header"|"html",   // default "header"
  *     lang:         string,            // default "en"
  *     skipHeader:   string,            // default "x-skip-ai-act"
+ *     headerPrefix: string,            // default "AI-Act-" — prefixes the Notice/Article/Policy disclosure headers
  *     audit:        boolean,           // default true
  *   }
  *
@@ -83,7 +84,7 @@ function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
     "kind", "deployerName", "policyUri", "mode",
-    "audit", "lang", "skipHeader",
+    "audit", "lang", "skipHeader", "headerPrefix",
   ], "middleware.aiActDisclosure");
 
   var mode = (opts.mode === "html") ? "html" : "header";
@@ -99,6 +100,12 @@ function create(opts) {
   var skipHeader = (typeof opts.skipHeader === "string" && opts.skipHeader.length > 0)
     ? opts.skipHeader.toLowerCase()
     : "x-skip-ai-act";
+  // headerPrefix (default "AI-Act-") names the emitted disclosure headers as
+  // <prefix>Notice / <prefix>Article / <prefix>Policy. The EU AI Act mandates
+  // the disclosure, not the HTTP spelling — operators matching a downstream
+  // convention pass their own prefix (e.g. "X-AI-").
+  var headerPrefix = (typeof opts.headerPrefix === "string" && opts.headerPrefix.length > 0)
+    ? opts.headerPrefix : "AI-Act-";
 
   return function aiActDisclosureMiddleware(req, res, next) {
     var headers = req.headers || {};
@@ -118,10 +125,10 @@ function create(opts) {
         return origWriteHead.apply(res, arguments);
       }
       var article = _articleFor(opts.kind || "ai-interaction");
-      _setHeader(res, "AI-Act-Notice",  opts.kind || "ai-interaction");
-      _setHeader(res, "AI-Act-Article", article);
+      _setHeader(res, headerPrefix + "Notice",  opts.kind || "ai-interaction");
+      _setHeader(res, headerPrefix + "Article", article);
       if (typeof opts.policyUri === "string" && opts.policyUri.length > 0) {
-        _setHeader(res, "AI-Act-Policy", opts.policyUri);
+        _setHeader(res, headerPrefix + "Policy", opts.policyUri);
       }
       injected = true;
       return origWriteHead.apply(res, arguments);

package/lib/middleware/rate-limit.js

@@ -364,6 +364,7 @@ function _resolveBackend(opts) {
  *     statusOnLimit:   number,           // default 429
  *     bodyOnLimit:     string,           // default "Too Many Requests"
  *     header:          boolean,          // default true
+ *     headerPrefix:    string,           // default "X-RateLimit-" — builds <prefix>Limit / <prefix>Remaining (e.g. "RateLimit-" for the IETF draft names)
  *     skipPaths:       Array<string|RegExp>,
  *     scope:           "global"|"per-route",
  *     backend:         "memory"|"cluster"|{ take, reset },
@@ -390,7 +391,7 @@ function _resolveBackend(opts) {
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
-    "keyFn", "statusOnLimit", "bodyOnLimit", "header", "skipPaths", "scope",
+    "keyFn", "statusOnLimit", "bodyOnLimit", "header", "headerPrefix", "skipPaths", "scope",
     "backend", "trustProxy", "algorithm",
     // memory backend (token-bucket)
     "burst", "refillPerSecond",
@@ -404,6 +405,14 @@ function create(opts) {
   var statusOnLimit = opts.statusOnLimit || 429;
   var bodyOnLimit = opts.bodyOnLimit !== undefined ? opts.bodyOnLimit : "Too Many Requests";
   var emitHeaders = opts.header !== false;
+  // headerPrefix (default "X-RateLimit-") builds the limit/remaining header
+  // names as <prefix>Limit / <prefix>Remaining. The X-RateLimit-* family is a
+  // de-facto convention, not RFC-pinned — operators matching the IETF draft
+  // pass "RateLimit-", or a gateway's own prefix. Kept as a matched pair.
+  var headerPrefix = (typeof opts.headerPrefix === "string" && opts.headerPrefix.length > 0)
+    ? opts.headerPrefix : "X-RateLimit-";
+  var limitHeader = headerPrefix + "Limit";
+  var remainingHeader = headerPrefix + "Remaining";
   var skipPaths = opts.skipPaths || [];
   // Throw at create(): each entry must be a string prefix or a RegExp.
   // Anything else would crash _shouldSkip with TypeError on the first request.
@@ -429,8 +438,8 @@ function create(opts) {
 
   function _writeBlocked(req, res, k, verdict) {
     if (emitHeaders && typeof res.setHeader === "function") {
-      res.setHeader("X-RateLimit-Limit", String(verdict.limit));
-      res.setHeader("X-RateLimit-Remaining", String(verdict.remaining));
+      res.setHeader(limitHeader, String(verdict.limit));
+      res.setHeader(remainingHeader, String(verdict.remaining));
       if (verdict.retryAfter > 0) res.setHeader("Retry-After", String(verdict.retryAfter));
     }
     try {
@@ -459,8 +468,8 @@ function create(opts) {
 
     function _handle(verdict) {
       if (emitHeaders && typeof res.setHeader === "function") {
-        res.setHeader("X-RateLimit-Limit", String(verdict.limit));
-        res.setHeader("X-RateLimit-Remaining", String(verdict.remaining));
+        res.setHeader(limitHeader, String(verdict.limit));
+        res.setHeader(remainingHeader, String(verdict.remaining));
       }
       if (!verdict.allowed) return _writeBlocked(req, res, k, verdict);
       next();

package/lib/middleware/sse.js

@@ -90,6 +90,7 @@ function _formatEvent(msg) {
  *   {
  *     heartbeatMs: number|false,   // default 15000
  *     headers:     object,         // extra response headers
+ *     proxyBuffer: boolean,        // default true — sets X-Accel-Buffering: no; false to suppress
  *   }
  *
  * @example
@@ -105,13 +106,17 @@ function create(handler, opts) {
     throw new Error("middleware.sse: handler must be a function (channel, req) => ...");
   }
   opts = opts || {};
-  validateOpts(opts, ["heartbeatMs", "headers"], "middleware.sse");
+  validateOpts(opts, ["heartbeatMs", "headers", "proxyBuffer"], "middleware.sse");
   var heartbeatMs = opts.heartbeatMs === false ? 0
     : (opts.heartbeatMs != null ? opts.heartbeatMs : DEFAULT_HEARTBEAT_MS);
   if (heartbeatMs !== 0 && (typeof heartbeatMs !== "number" || !isFinite(heartbeatMs) || heartbeatMs <= 0)) {
     throw new Error("middleware.sse: heartbeatMs must be a positive finite number or false");
   }
   var extraHeaders = opts.headers || {};
+  // proxyBuffer (default true) sets `X-Accel-Buffering: no` (the nginx hint
+  // that disables proxy buffering). Pass false when not behind nginx, or
+  // when buffering is controlled at the load balancer, to suppress it.
+  var proxyBuffer = opts.proxyBuffer !== false;
 
   return async function sseMiddleware(req, res) {
     if (typeof res.writeHead !== "function" || typeof res.write !== "function") {
@@ -119,13 +124,14 @@ function create(handler, opts) {
       // unusual. Fail closed rather than silently dropping the handler.
       throw new Error("middleware.sse: res does not support writeHead/write — wire SSE only on HTTP routes");
     }
-    var headers = Object.assign({
-      "Content-Type":     "text/event-stream; charset=utf-8",
-      "Cache-Control":    "no-cache, no-transform",
-      "Connection":       "keep-alive",
-      // Disable nginx response buffering when terminating behind it.
-      "X-Accel-Buffering": "no",
-    }, extraHeaders);
+    var baseHeaders = {
+      "Content-Type":  "text/event-stream; charset=utf-8",
+      "Cache-Control": "no-cache, no-transform",
+      "Connection":    "keep-alive",
+    };
+    // Disable nginx response buffering when terminating behind it.
+    if (proxyBuffer) baseHeaders["X-Accel-Buffering"] = "no";
+    var headers = Object.assign(baseHeaders, extraHeaders);
     // Append Vary: Accept so a proxy doesn't serve a cached non-SSE
     // response on the same URL to a future client.
     res.writeHead(requestHelpers.HTTP_STATUS.OK, headers);

package/lib/sse.js

@@ -27,6 +27,11 @@
  *                        input (default SseError)
  *       audit          — bool, default true. Emit SSE lifecycle audit
  *                        events.
+ *       proxyBuffer    — bool, default true. Sets `X-Accel-Buffering:
+ *                        no` (the nginx hint that disables proxy
+ *                        buffering of the stream). Pass false when not
+ *                        behind nginx, or when buffering is handled at
+ *                        the load balancer, to suppress the header.
  *
  *   channel.send({ event, id, data, retry })
  *     Writes a single SSE event. Each field is validated; LF/CR/NUL
@@ -236,18 +241,20 @@ function create(req, res, opts) {
       JSON.stringify(heartbeatMs) + ")");
   }
   var auditOn = opts.audit !== false;
+  // proxyBuffer (default true) sets `X-Accel-Buffering: no` — the nginx hint
+  // that defeats proxy buffering of the event stream. Operators not behind
+  // nginx, or whose buffering is controlled at the load balancer, pass
+  // proxyBuffer: false to suppress the nginx-specific header.
+  var proxyBuffer = opts.proxyBuffer !== false;
 
   var lastEventId = _readLastEventId(req);
 
   // Headers. text/event-stream is the contract; Cache-Control: no-cache
-  // and Connection: keep-alive (h1) are the operationally required
-  // pair. X-Accel-Buffering: no defeats nginx-style proxy buffering;
-  // operators behind a proxy that doesn't honor this set proxyBuffer:
-  // false on their LB.
+  // and Connection: keep-alive (h1) are the operationally required pair.
   if (typeof res.setHeader === "function") {
     res.setHeader("Content-Type",      "text/event-stream; charset=utf-8");
     res.setHeader("Cache-Control",     "no-cache, no-transform");
-    res.setHeader("X-Accel-Buffering", "no");
+    if (proxyBuffer) res.setHeader("X-Accel-Buffering", "no");
     // Connection: keep-alive only meaningful on h1; h2 streams stay
     // open until either side closes. node:http2 surfaces res.stream
     // (h2 ServerHttp2Stream) where setHeader works the same.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.13.46",
+  "version": "0.14.0",
   "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.5",
-  "serialNumber": "urn:uuid:f993db8e-7dd3-41d0-95bd-33ee9d07ab8f",
+  "serialNumber": "urn:uuid:e6a01e68-c8b4-4c27-b3b5-f1ddf1aad212",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-30T02:44:28.905Z",
+    "timestamp": "2026-05-30T04:02:38.743Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.13.46",
+      "bom-ref": "@blamejs/core@0.14.0",
       "type": "application",
       "name": "blamejs",
-      "version": "0.13.46",
+      "version": "0.14.0",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.13.46",
+      "purl": "pkg:npm/%40blamejs/core@0.14.0",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.13.46",
+      "ref": "@blamejs/core@0.14.0",
       "dependsOn": []
     }
   ]