npm - @blamejs/blamejs-shop - Versions diffs - 0.0.44 - Mend

@blamejs/blamejs-shop 0.0.44

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1220) hide show

package/lib/vendor/blamejs/lib/middleware/speculation-rules.js ADDED Viewed

@@ -0,0 +1,323 @@
+"use strict";
+/**
+ * @module     b.middleware.speculationRules
+ * @nav        HTTP
+ * @title      Speculation Rules
+ * @order      130
+ * @card       W3C Speculation Rules emitter — declares which links the
+ *             user-agent is allowed to prerender or prefetch ahead of
+ *             user navigation. Default emit path is the
+ *             `Speculation-Rules` response header pointing at a
+ *             JSON-served rules document; an opt-in `inline: true`
+ *             mode injects `<script type="speculationrules">` into
+ *             text/html bodies.
+ *
+ * @intro
+ *   Speculation Rules (W3C draft) are the modern replacement for
+ *   `<link rel="prerender">` / `<link rel="prefetch">`. The browser
+ *   reads a JSON document declaring patterns of links the operator
+ *   wants speculatively loaded under varying eagerness levels
+ *   (`immediate`, `eager`, `moderate`, `conservative`) and
+ *   pre-fetches or pre-renders matching anchors as the user hovers /
+ *   scrolls / dwells.
+ *
+ *   Two emit modes:
+ *
+ *   1. `Speculation-Rules` response header — points at a JSON
+ *      document the operator serves elsewhere (typical for shared
+ *      rules across many pages):
+ *
+ *        Speculation-Rules: "/rules/speculation.json"
+ *
+ *      The header form is the framework's default because it keeps
+ *      HTML response bodies clean, lets the rules document be cached
+ *      independently, and avoids touching response bodies (zero risk
+ *      of body-parse / encoding mishaps).
+ *
+ *   2. Inline `<script type="speculationrules">` injection — for
+ *      operators who want per-page rules, the framework can inject
+ *      the JSON into `text/html` responses just before `</head>`
+ *      (or, falling back, before the first `<body>` tag). Opt in
+ *      with `{ inline: true }`.
+ *
+ *   Mount AFTER `securityHeaders` and (when used) `cspNonce`. When
+ *   `inline: true` is set, an operator-supplied nonce on `req` (via
+ *   `cspNonce`) is added to the injected `<script>` tag so a strict
+ *   CSP allows the rules to load.
+ *
+ *     app.use(b.middleware.requestId());
+ *     app.use(b.middleware.securityHeaders());
+ *     app.use(b.middleware.cspNonce({ always: true }));
+ *     app.use(b.middleware.speculationRules({
+ *       rules: {
+ *         prerender: [
+ *           { where: { href_matches: "/articles/*" }, eagerness: "moderate" },
+ *         ],
+ *         prefetch: [
+ *           { where: { href_matches: "/api/*" }, eagerness: "conservative" },
+ *         ],
+ *       },
+ *     }));
+ *
+ *   Both mode shapes validate the rules object at construct time so
+ *   typos surface at boot, never as a silently-ignored speculation
+ *   rule three deploys later.
+ */
+var validateOpts = require("../validate-opts");
+// Per W3C draft + Chromium implementation. `immediate` triggers the
+// speculation as soon as the rules are seen; `conservative` waits
+// for a strong intent signal (mousedown). The framework permits the
+// full set; operators pick per-rule.
+var EAGERNESS_LEVELS = {
+  "immediate":    true,
+  "eager":        true,
+  "moderate":     true,
+  "conservative": true,
+};
+// `prerender` fully renders the destination in a hidden tab —
+// expensive, fast on activation. `prefetch` pulls bytes only — cheap,
+// faster TTFB on activation. Both are arrays of rule objects.
+var ACTION_KEYS = ["prerender", "prefetch"];
+// Header value — when an operator passes a string instead of a rules
+// object, treat it as the URL to a separately-served rules document
+// (the simpler header-form path).
+function _looksLikeRulesUrl(v) {
+  return typeof v === "string" && v.length > 0;
+}
+// CR/LF/NUL screen — flows into the response header value, where
+// header-injection would split into a forged second header.
+var INJECTION_RE = /[\r\n\0]/;
+function _refuseInjection(value, label) {
+  if (typeof value !== "string") return;
+  if (INJECTION_RE.test(value)) {  // allow:regex-no-length-cap — CR/LF/NUL injection check, length bounded by caller
+    throw new TypeError(
+      "middleware.speculationRules: " + label + " contains CR/LF/NUL — refused as a " +
+      "header-injection vector");
+  }
+}
+// Validate the operator-supplied rules object. Returns nothing on
+// success; throws TypeError with an actionable message at config
+// time. Each entry must be a plain object with `where` (object) and
+// `eagerness` (one of EAGERNESS_LEVELS).
+function _validateRules(rules, label) {
+  if (!rules || typeof rules !== "object" || Array.isArray(rules)) {
+    throw new TypeError(label + " must be an object with `prerender` and/or `prefetch` arrays");
+  }
+  var seenAny = false;
+  for (var ki = 0; ki < ACTION_KEYS.length; ki += 1) {
+    var actionKey = ACTION_KEYS[ki];
+    var entries = rules[actionKey];
+    if (entries === undefined) continue;
+    if (!Array.isArray(entries)) {
+      throw new TypeError(label + "." + actionKey + " must be an array of rule objects");
+    }
+    seenAny = true;
+    for (var ei = 0; ei < entries.length; ei += 1) {
+      var rule = entries[ei];
+      if (!rule || typeof rule !== "object" || Array.isArray(rule)) {
+        throw new TypeError(label + "." + actionKey + "[" + ei + "] must be a plain object");
+      }
+      if (!rule.where || typeof rule.where !== "object" || Array.isArray(rule.where)) {
+        throw new TypeError(label + "." + actionKey + "[" + ei +
+          "].where must be a `where` clause object (W3C draft, e.g. { href_matches: \"/path/*\" })");
+      }
+      if (typeof rule.eagerness !== "string" || !EAGERNESS_LEVELS[rule.eagerness]) {
+        throw new TypeError(label + "." + actionKey + "[" + ei +
+          "].eagerness must be one of: " + Object.keys(EAGERNESS_LEVELS).join(", "));
+      }
+    }
+  }
+  if (!seenAny) {
+    throw new TypeError(label + " must declare at least one of `prerender` or `prefetch`");
+  }
+}
+/**
+ * @primitive b.middleware.speculationRules
+ * @signature b.middleware.speculationRules(req, res, next)
+ * @since     0.8.53
+ * @status    stable
+ * @related   b.middleware.cspNonce, b.middleware.securityHeaders
+ *
+ * Builds middleware that emits W3C Speculation Rules so the user-agent
+ * may prerender or prefetch matching links ahead of user navigation.
+ * Two emit paths:
+ *
+ *   - Header form (default): emits `Speculation-Rules: "<url>"` where
+ *     `<url>` points at an operator-served rules document.
+ *   - Inline form (`inline: true`): injects a
+ *     `<script type="speculationrules">{...}</script>` tag into
+ *     `text/html` response bodies just before `</head>` (or fallback
+ *     before `<body>`). When `cspNonce` middleware has populated
+ *     `req.cspNonce`, the injected `<script>` carries that nonce so
+ *     strict CSP allows it.
+ *
+ * The rules object is validated at construct time. Empty / malformed
+ * rules throw with a message naming the offending key.
+ *
+ * @opts
+ *   {
+ *     rules:   object,    // { prerender: [...], prefetch: [...] }
+ *     rulesUrl: string,   // header-mode URL (alternative to rules)
+ *     inline:  boolean,   // default false; inject <script> instead of header
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.speculationRules({
+ *     rules: {
+ *       prerender: [
+ *         { where: { href_matches: "/articles/*" }, eagerness: "moderate" },
+ *       ],
+ *       prefetch: [
+ *         { where: { href_matches: "/api/*" }, eagerness: "conservative" },
+ *       ],
+ *     },
+ *   }));
+ */
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["rules", "rulesUrl", "inline"], "middleware.speculationRules");
+  var inline = !!opts.inline;
+  var rulesUrl = opts.rulesUrl;
+  var rulesObj = opts.rules;
+  // Operators may pass `rules` as a string (URL form) for ergonomics —
+  // route that to rulesUrl so the validation logic below stays
+  // straightforward.
+  if (_looksLikeRulesUrl(rulesObj) && rulesUrl === undefined) {
+    rulesUrl = rulesObj;
+    rulesObj = undefined;
+  }
+  if (inline) {
+    if (!rulesObj) {
+      throw new TypeError(
+        "middleware.speculationRules: opts.rules is required when opts.inline is true " +
+        "(inline mode injects the rules JSON into the response body)");
+    }
+    _validateRules(rulesObj, "middleware.speculationRules: opts.rules");
+  } else {
+    if (rulesObj && rulesUrl !== undefined) {
+      throw new TypeError(
+        "middleware.speculationRules: pass either opts.rules or opts.rulesUrl, not both");
+    }
+    if (!rulesObj && (typeof rulesUrl !== "string" || rulesUrl.length === 0)) {
+      throw new TypeError(
+        "middleware.speculationRules: header mode requires opts.rulesUrl (the URL of " +
+        "an operator-served JSON rules document) or opts.rules (which the framework " +
+        "renders inline). Pass `inline: true` if you want the framework to embed the " +
+        "rules object as a <script type=\"speculationrules\"> tag.");
+    }
+    if (rulesObj) {
+      _validateRules(rulesObj, "middleware.speculationRules: opts.rules");
+    }
+    if (rulesUrl !== undefined) {
+      _refuseInjection(rulesUrl, "opts.rulesUrl");
+    }
+  }
+  // Pre-build the emission payload once.
+  // Header value per W3C draft + RFC 8941 (Structured Field Value
+  // String — quoted, no internal CR/LF). When the operator supplied
+  // `rules` directly in header mode, the framework serializes the
+  // JSON as a data: URL so a single primitive can serve both shapes
+  // without forcing the operator to wire a separate route.
+  var headerValue;
+  if (!inline) {
+    if (rulesUrl) {
+      headerValue = '"' + rulesUrl + '"';
+    } else {
+      var dataUrl = "data:application/speculationrules+json;base64," +
+        Buffer.from(JSON.stringify(rulesObj), "utf8").toString("base64");
+      headerValue = '"' + dataUrl + '"';
+    }
+  }
+  // Pre-built inline JSON. The body is small (rules objects are
+  // typically ~200 bytes); JSON.stringify once and cache.
+  var inlineJson = inline ? JSON.stringify(rulesObj) : null;
+  return function speculationRules(req, res, next) {
+    if (!inline) {
+      if (typeof res.setHeader === "function") {
+        res.setHeader("Speculation-Rules", headerValue);
+      }
+      return next();
+    }
+    // Inline mode — patch res.write / res.end so we inject the
+    // <script> tag into the first text/html response. Same shape as
+    // botDisclose / aiActDisclosure to stay consistent with the
+    // framework's response-rewrite convention.
+    var origWrite = res.write && res.write.bind(res);
+    var origEnd = res.end && res.end.bind(res);
+    var injected = false;
+    function _scriptTag() {
+      var nonceAttr = "";
+      // Operator-supplied per-request nonce flows through cspNonce
+      // middleware. If absent we still emit the script tag (works
+      // under non-strict CSP); under strict CSP without nonce, the
+      // browser refuses — visible to operators via cspReport.
+      if (req && typeof req.cspNonce === "string" && req.cspNonce.length > 0) {
+        nonceAttr = ' nonce="' + req.cspNonce + '"';
+      }
+      return '<script type="speculationrules"' + nonceAttr + '>' + inlineJson + '</script>';
+    }
+    function _maybeInject(chunk) {
+      if (injected) return chunk;
+      var ct = typeof res.getHeader === "function" ? res.getHeader("content-type") : "";
+      if (typeof ct !== "string" || ct.indexOf("text/html") === -1) return chunk;
+      var body = Buffer.isBuffer(chunk) ? chunk.toString("utf8") :
+        (typeof chunk === "string" ? chunk : "");
+      if (body.length === 0) return chunk;
+      var tag = _scriptTag();
+      var headClose = body.search(/<\/head\s*>/i);
+      if (headClose !== -1) {
+        body = body.slice(0, headClose) + tag + body.slice(headClose);
+      } else {
+        var bodyOpen = body.match(/<body[^>]*>/i);
+        if (bodyOpen) {
+          var idx = bodyOpen.index + bodyOpen[0].length;
+          body = body.slice(0, idx) + tag + body.slice(idx);
+        } else {
+          // No <head> or <body> — prepend so the rules at least
+          // reach the parser. This matches the bot-disclose fallback.
+          body = tag + body;
+        }
+      }
+      injected = true;
+      return Buffer.from(body, "utf8");
+    }
+    if (origWrite) {
+      res.write = function (chunk, encoding, cb) {
+        return origWrite(_maybeInject(chunk), encoding, cb);
+      };
+    }
+    if (origEnd) {
+      res.end = function (chunk, encoding, cb) {
+        if (chunk) chunk = _maybeInject(chunk);
+        return origEnd(chunk, encoding, cb);
+      };
+    }
+    return next();
+  };
+}
+module.exports = {
+  create:           create,
+  EAGERNESS_LEVELS: Object.keys(EAGERNESS_LEVELS),
+  ACTION_KEYS:      ACTION_KEYS,
+};

package/lib/vendor/blamejs/lib/middleware/sse.js ADDED Viewed

@@ -0,0 +1,200 @@
+"use strict";
+/**
+ * sse — Server-Sent Events middleware. One-way streaming from server
+ * to browser over a single HTTP response with `Content-Type:
+ * text/event-stream`. Browsers reconnect automatically with the
+ * `Last-Event-ID` header so the operator's handler can resume from
+ * the last delivered event.
+ *
+ * Use case: live dashboards, log tailing, progress updates, real-time
+ * counters. SSE is the right tool when the server pushes and the
+ * client doesn't need to send anything back. For bidirectional, use
+ * `b.websocket`.
+ *
+ *   router.get("/events", b.middleware.sse(async function (channel, req) {
+ *     channel.send({ id: 1, event: "tick", data: { count: 1 } });
+ *     channel.send({ id: 2, event: "tick", data: { count: 2 } });
+ *     // resume support — read req.headers["last-event-id"] and
+ *     // resume from that point.
+ *   }));
+ *
+ * `channel`:
+ *   send({ id?, event?, data, retry? })  — emit one SSE message
+ *   ping(comment?)                       — emit a comment line (keeps
+ *                                          intermediate proxies happy)
+ *   close()                              — end the stream
+ *   onAbort(fn)                          — register cleanup when the
+ *                                          client disconnects (browser
+ *                                          tab close, network drop)
+ *
+ * Heartbeat: the middleware sends a comment line every `heartbeatMs`
+ * (default 15s) automatically so corporate proxies / Heroku-style
+ * idle-timeouts don't kill the stream. Operators with strict
+ * deployments override `heartbeatMs: false` to disable.
+ *
+ * Compression: SSE streams typically should NOT be compressed —
+ * `b.middleware.compression` skips `text/event-stream` by default.
+ */
+var C = require("../constants");
+var requestHelpers = require("../request-helpers");
+var safeBuffer = require("../safe-buffer");
+var sse = require("../sse");
+var validateOpts = require("../validate-opts");
+var DEFAULT_HEARTBEAT_MS = C.TIME.seconds(15);
+// _formatEvent — REFUSES on CRLF/NUL injection in event/id (CVE-2026-
+// 33128 / 29085 / 44217 class). Pre-v0.8.15 this stripped CRLF
+// silently; the strip-instead-of-refuse behavior was the
+// vulnerability. The framework now refuses at the source, returning
+// the operator a clear error code so the caller knows the event was
+// rejected. Validation routes through b.sse.serializeEvent so the
+// middleware surface and the low-level surface share one policy.
+function _formatEvent(msg) {
+  var coerced = msg || {};
+  var dataStr;
+  if (coerced.data === undefined || coerced.data === null) dataStr = "";
+  else if (typeof coerced.data === "string")               dataStr = coerced.data;
+  else                                                      dataStr = JSON.stringify(coerced.data);
+  return sse.serializeEvent({
+    id:    coerced.id !== undefined && coerced.id !== null ? String(coerced.id) : undefined,
+    event: coerced.event !== undefined && coerced.event !== null ? String(coerced.event) : undefined,
+    retry: coerced.retry,
+    data:  dataStr,
+  });
+}
+/**
+ * @primitive b.middleware.sse
+ * @signature b.middleware.sse(handler, opts)
+ * @since     0.1.0
+ * @related   b.sse.serializeEvent, b.middleware.compression
+ *
+ * Server-Sent Events handler — one-way streaming from server to
+ * browser over a single HTTP response with `Content-Type:
+ * text/event-stream`. Browsers reconnect automatically with
+ * `Last-Event-ID` so the operator's handler can resume from the
+ * last delivered event. Refuses CRLF / NUL injection in `event` /
+ * `id` (CVE-2026-33128 / 29085 / 44217 class) — the framework
+ * does NOT silently strip; it returns a structured error.
+ * Heartbeat (default 15s) keeps corporate proxies / Heroku-style
+ * idle-timeouts from killing the stream; pass `heartbeatMs: false`
+ * to disable. SSE streams should NOT be compressed —
+ * `b.middleware.compression` already skips `text/event-stream`.
+ *
+ * The handler receives `(channel, req)`. The channel exposes
+ * `send({ id, event, data, retry })`, `ping(comment)`, `close()`,
+ * `onAbort(fn)`.
+ *
+ * @opts
+ *   {
+ *     heartbeatMs: number|false,   // default 15000
+ *     headers:     object,         // extra response headers
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.get("/events", b.middleware.sse(async function (channel, req) {
+ *     channel.send({ id: 1, event: "tick", data: { count: 1 } });
+ *     channel.close();
+ *   }, { heartbeatMs: 15000 }));
+ */
+function create(handler, opts) {
+  if (typeof handler !== "function") {
+    throw new Error("middleware.sse: handler must be a function (channel, req) => ...");
+  }
+  opts = opts || {};
+  validateOpts(opts, ["heartbeatMs", "headers"], "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 || {};
+  return async function sseMiddleware(req, res) {
+    if (typeof res.writeHead !== "function" || typeof res.write !== "function") {
+      // Not an http.ServerResponse — operator wired this onto something
+      // 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);
+    // 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);
+    requestHelpers.appendVary(res, "Accept");
+    // Initial flush — some proxies hold the headers until first byte.
+    res.write(":\n\n");
+    var closed = false;
+    var heartbeatTimer = null;
+    var abortHandlers = [];
+    function _scheduleHeartbeat() {
+      if (heartbeatMs === 0) return;
+      heartbeatTimer = setTimeout(function () {
+        if (closed) return;
+        try { res.write(": heartbeat\n\n"); } catch (_e) { /* socket closed */ }
+        _scheduleHeartbeat();
+      }, heartbeatMs);
+      if (typeof heartbeatTimer.unref === "function") heartbeatTimer.unref();
+    }
+    _scheduleHeartbeat();
+    var channel = {
+      send: function (msg) {
+        if (closed) return false;
+        try { res.write(_formatEvent(msg || {})); return true; }
+        catch (_e) { return false; }
+      },
+      ping: function (comment) {
+        if (closed) return false;
+        var safe = comment ? safeBuffer.stripCrlf(String(comment), " ") : "ping";
+        try { res.write(": " + safe + "\n\n"); return true; }
+        catch (_e) { return false; }
+      },
+      close: function () {
+        if (closed) return;
+        closed = true;
+        if (heartbeatTimer) { clearTimeout(heartbeatTimer); heartbeatTimer = null; }
+        try { res.end(); } catch (_e) { /* already ended */ }
+      },
+      onAbort: function (fn) {
+        if (typeof fn === "function") abortHandlers.push(fn);
+      },
+      get closed() { return closed; },
+    };
+    function _onClose() {
+      if (closed) return;
+      closed = true;
+      if (heartbeatTimer) { clearTimeout(heartbeatTimer); heartbeatTimer = null; }
+      for (var i = 0; i < abortHandlers.length; i++) {
+        try { abortHandlers[i](); } catch (_e) { /* operator handler error — drop */ }
+      }
+    }
+    res.once("close", _onClose);
+    res.once("error", _onClose);
+    if (req && typeof req.once === "function") req.once("aborted", _onClose);
+    try {
+      await handler(channel, req);
+    } catch (e) {
+      _onClose();
+      try { res.end(); } catch (_ignored) { /* */ }
+      throw e;
+    }
+  };
+}
+module.exports = {
+  create:        create,
+  _formatEvent:  _formatEvent,   // test-only export
+};

package/lib/vendor/blamejs/lib/middleware/trace-log-correlation.js ADDED Viewed

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * trace-log-correlation middleware — wraps the operator's b.log
+ * instance for the request lifetime so every log() / info() / warn()
+ * / error() / debug() call inside the handler auto-includes the
+ * canonical trace_id + span_id (and tenant context from W3C Baggage
+ * when present).
+ *
+ *   var log = b.log.boot("api");
+ *   router.use(b.middleware.tracePropagate());
+ *   router.use(b.middleware.traceLogCorrelation({
+ *     logger:   log,
+ *     reqField: "log",   // attaches as req.log
+ *   }));
+ *
+ *   app.get("/widgets", function (req, res) {
+ *     // req.log is the wrapped logger; every emission carries
+ *     // trace_id + span_id + (optional) baggage attributes
+ *     req.log.info("loading widgets");
+ *     // → { ..., trace_id: "abc...", span_id: "def...",
+ *     //     baggage: { tenant: "acme" } }
+ *   });
+ *
+ * The wrapper is a thin adapter: it does not change log levels,
+ * sinks, or the b.log API surface. Logs pass through to the
+ * wrapped logger with the trace fields injected via the meta-object
+ * second argument.
+ *
+ * When no req.trace is present (unusual — operators typically mount
+ * tracePropagate first), the wrapper is a no-op pass-through; logs
+ * still flow but without correlation fields.
+ */
+var lazyRequire = require("../lazy-require");
+var validateOpts = require("../validate-opts");
+var { defineClass } = require("../framework-error");
+var TraceLogError = defineClass("TraceLogError", { alwaysPermanent: true });
+var observability = lazyRequire(function () { return require("../observability"); });
+var LOG_LEVELS = ["debug", "info", "warn", "error", "fatal"];
+function _baggageToObject(entries) {
+  if (!Array.isArray(entries) || entries.length === 0) return null;
+  var out = Object.create(null);
+  for (var i = 0; i < entries.length; i++) {
+    out[entries[i].key] = entries[i].value;
+  }
+  return out;
+}
+function _wrapLogger(baseLogger, req, opts) {
+  if (!baseLogger || typeof baseLogger !== "object") return baseLogger;
+  var wrapped = Object.create(null);
+  // Preserve any non-level properties the operator put on the
+  // logger (e.g. boot context, child-logger metadata).
+  var keys = Object.keys(baseLogger);
+  for (var i = 0; i < keys.length; i++) {
+    if (LOG_LEVELS.indexOf(keys[i]) === -1) wrapped[keys[i]] = baseLogger[keys[i]];
+  }
+  function _enrichMeta(meta) {
+    var enriched = Object.assign({}, meta || {});
+    if (req && req.trace) {
+      enriched.trace_id = req.trace.traceId;
+      // span_id prefers the active span (set by spanHttpServer) over
+      // the trace context's parentId
+      if (req.span && typeof req.span.spanId === "string") {
+        enriched.span_id = req.span.spanId;
+      } else if (typeof req.trace.parentId === "string") {
+        enriched.span_id = req.trace.parentId;
+      }
+      if (opts.includeBaggage !== false) {
+        var bg = _baggageToObject(req.trace.tracestate);
+        // tracestate is vendor-trace data; baggage is operator data.
+        // Operators usually want baggage in logs, not tracestate.
+        // We don't have a separate req.baggage today; keep this as
+        // the path for when tracePropagate exposes it. For now,
+        // emit the resolved tracestate shape under "trace_state".
+        if (bg) enriched.trace_state = bg;
+      }
+    }
+    return enriched;
+  }
+  // Bind each level on the underlying logger so it emits with the
+  // enriched meta. We don't replace the underlying logger's bound
+  // emitter shape — it still receives meta as the second argument.
+  for (var li = 0; li < LOG_LEVELS.length; li++) {
+    (function (lvl) {
+      if (typeof baseLogger[lvl] !== "function") return;
+      wrapped[lvl] = function (msg, meta) {
+        try { return baseLogger[lvl](msg, _enrichMeta(meta)); }
+        catch (_e) { /* drop-silent — log sink */ }
+      };
+    })(LOG_LEVELS[li]);
+  }
+  // Pass through anything else the logger might expose (boot, child, etc.)
+  if (typeof baseLogger.boot === "function") wrapped.boot = baseLogger.boot.bind(baseLogger);
+  if (typeof baseLogger.child === "function") wrapped.child = baseLogger.child.bind(baseLogger);
+  return wrapped;
+}
+/**
+ * @primitive b.middleware.traceLogCorrelation
+ * @signature b.middleware.traceLogCorrelation(opts)
+ * @since     0.1.0
+ * @related   b.middleware.tracePropagate, b.middleware.spanHttpServer
+ *
+ * Wraps the operator's `b.log` instance for the request lifetime
+ * so every `log() / info() / warn() / error() / debug()` call
+ * inside the handler auto-includes the canonical `trace_id` +
+ * `span_id` (and tenant attributes from W3C Baggage when present).
+ * Thin adapter — does not change levels, sinks, or the API
+ * surface; logs pass through with the trace fields injected via
+ * the meta-object second argument. When `req.trace` isn't set
+ * (operator forgot to mount `tracePropagate` first), the wrapper
+ * is a no-op pass-through.
+ *
+ * @opts
+ *   {
+ *     logger:         object,    // required b.log instance
+ *     reqField:       string,    // default "log" → req.log
+ *     includeBaggage: boolean,   // default true
+ *     audit:          boolean,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.tracePropagate());
+ *   app.use(b.middleware.traceLogCorrelation({
+ *     logger:   b.log.boot("api"),
+ *     reqField: "log",
+ *   }));
+ */
+function create(opts) {
+  validateOpts.requireObject(opts, "middleware.traceLogCorrelation", TraceLogError);
+  validateOpts(opts, [
+    "logger", "reqField", "includeBaggage", "audit",
+  ], "middleware.traceLogCorrelation");
+  if (!opts.logger || typeof opts.logger !== "object") {
+    throw new TraceLogError("trace-log/bad-logger",
+      "middleware.traceLogCorrelation: logger must be a b.log instance");
+  }
+  var reqField = opts.reqField || "log";
+  if (typeof reqField !== "string" || reqField.length === 0) {
+    throw new TraceLogError("trace-log/bad-reqfield",
+      "middleware.traceLogCorrelation: reqField must be a non-empty string");
+  }
+  return function traceLogCorrelationMiddleware(req, res, next) {
+    req[reqField] = _wrapLogger(opts.logger, req, opts);
+    void observability;     // touch lazyRequire so the dep is captured
+    return next();
+  };
+}
+module.exports = {
+  create:        create,
+  TraceLogError: TraceLogError,
+  // exported for tests
+  _wrapLogger:   _wrapLogger,
+  LOG_LEVELS:    LOG_LEVELS,
+};