@blamejs/core 0.8.43 → 0.8.50

package/lib/log.js

@@ -1,62 +1,57 @@
 "use strict";
 /**
- * log — structured JSON application logger with request-id correlation.
+ * @module b.log
+ * @featured true
+ * @nav    Observability
+ * @title  Log
  *
- * Distinct concern from lib/logger.js: logger.js is the framework's
- * own boot/operational chatter to console with `[blamejs:<name>] `
- * prefix (humans watching `npm start`). lib/log.js is the app-level
- * structured logger meant to be ingested by a log aggregator.
+ * @intro
+ *   Structured JSON application logger meant to be ingested by a log
+ *   aggregator. Each emitted line is a single JSON object terminated
+ *   with `\n`; the log level is encoded as the string field `level`,
+ *   not as console color. Distinct from `b.log.boot` — that path is
+ *   framework-internal startup chatter to the TTY (humans watching
+ *   `npm start`); `create()` is what apps wire into their request
+ *   lifecycle.
  *
- * Each line is one JSON object on a single line, terminated with `\n`.
- * Levels: debug (0) < info (1) < warn (2) < error (3) < fatal (4).
- * Default routing: debug / info / warn → stdout; error / fatal → stderr.
- * Multi-sink config (`sinks: [...]`) takes full control of routing.
+ *   Levels: debug (0) < info (1) < warn (2) < error (3) < fatal (4).
+ *   Default routing: debug / info / warn → stdout; error / fatal →
+ *   stderr. Multi-sink config (`sinks: [...]`) takes full control of
+ *   routing — each sink gets every line at-or-above its own per-sink
+ *   level, useful when the operator wants debug to a file but warn+
+ *   to stderr.
  *
- *   var log = b.log.create({
- *     level:   "info",            // env LOG_LEVEL > opts.level > "info"
- *     base:    { service: "myapp", version: "1.2.3" },
- *     redact:  true,              // run extras through lib/redact
- *   });
- *
- *   // Multi-sink: each sink gets every line at-or-above its own level.
- *   // Default (no `sinks` opt) splits info-and-below to stdout and
- *   // warn-and-up to stderr — same as before.
- *   var log = b.log.create({
- *     level: "debug",
- *     sinks: [
- *       { stream: process.stdout,                              level: "info"  },
- *       { stream: fs.createWriteStream("./logs/debug.log"),    level: "debug" },
- *       { stream: fs.createWriteStream("./logs/errors.log"),   level: "error" },
- *     ],
- *   });
- *   // sinks: [...] is mutually exclusive with destination/errorDestination.
+ *   Redact-aware: `extras` passed to `.info(msg, extras)` flow through
+ *   `b.redact` by default, so password / token / cardNumber-shaped
+ *   keys never reach the log line. Operators opt out with
+ *   `redact: false` only when the logger sits behind a downstream
+ *   redactor.
  *
- *   log.info("user logged in", { userId: "u-1" });
- *   log.error("payment failed", { orderId, err: e.message });
+ *   Request correlation rides on Node's AsyncLocalStorage. The
+ *   middleware allocates a `requestId` (or honors an inbound
+ *   `X-Request-Id` header) and binds it for the entire async chain;
+ *   every `log.info` inside the request automatically picks up the
+ *   id without the caller threading it explicitly. OpenTelemetry
+ *   trace correlation rides the same channel — `runWithContext`
+ *   merges arbitrary fields (tenantId, traceId) into the bound store.
  *
- *   // Child with bound context
- *   var authLog = log.bind({ component: "auth" });
- *   authLog.info("password verified", { userId: "u-1" });
+ *   Child loggers via `log.bind({ component: "auth" })` carry the
+ *   bound fields into every emitted line; chains compose, so an
+ *   auth-handler logger can bind its own `userId` on top.
  *
- *   // Request correlation via AsyncLocalStorage (Node async context)
- *   await log.runWithRequestId("req-abc", async function () {
- *     log.info("inside request");   // → ..., "requestId": "req-abc"
- *   });
+ *   Field merge order (last wins): base context → bound chain → ALS
+ *   store → caller's extras → core fields (timestamp / level /
+ *   message). Extras that try to clobber a core field are dropped
+ *   and the line carries `_overwriteAttempt: true` so misconfig is
+ *   visible.
  *
- *   // Router middleware that allocates a requestId and binds it for
- *   // the entire request async chain
- *   r.use(log.middleware());
+ *   Trojan-Source defense (CVE-2021-42574) is baked in: Unicode
+ *   bidi / format controls in messages are escaped to `\uXXXX`
+ *   literals before they reach the wire so a hostile message can't
+ *   re-order the visible line in a TTY / syslog reader.
  *
- * Field merge order (last wins):
- *   1. base context from create()
- *   2. bound context from bind() (each ancestor up the chain)
- *   3. requestId from ALS (if set)
- *   4. extra arg from .info(msg, extra)
- *   5. core fields: timestamp, level, message
- *
- * Core fields cannot be overwritten by extras — log.info("hi", { level: "X" })
- * keeps level: "info" in the emitted line, with an _overwriteAttempt
- * flag if the operator tried to clobber.
+ * @card
+ *   Structured JSON application logger meant to be ingested by a log aggregator.
  */
 
 var { AsyncLocalStorage } = require("node:async_hooks");
@@ -197,6 +192,46 @@ function _resolveSinks(opts) {
   ];
 }
 
+/**
+ * @primitive b.log.create
+ * @signature b.log.create(opts)
+ * @since     0.1.70
+ * @status    stable
+ * @related   b.log.boot, b.log.makeViaOrFallback, b.redact.redact
+ *
+ * Build a structured JSON logger instance. Returns an object with
+ * `.debug` / `.info` / `.warn` / `.error` / `.fatal` emitters, plus
+ * `.bind(extra)` for child loggers, `.middleware()` for router-side
+ * request-id binding, `.runWithRequestId(id, fn)` /
+ * `.runWithContext(ctx, fn)` for ad-hoc AsyncLocalStorage scopes,
+ * and `.setLevel` / `.getLevel` / `.isLevelEnabled` for runtime
+ * level control. Level resolution is `LOG_LEVEL` env > `opts.level`
+ * > `"info"`.
+ *
+ * @opts
+ *   level:            "info",                      // string or 0-4
+ *   base:             { service: "myapp" },        // merged into every line
+ *   redact:           true,                        // run extras through b.redact
+ *   sinks: [
+ *     { stream: process.stdout, level: "info" },
+ *     { stream: fs.createWriteStream("./errors.log"), level: "error" },
+ *   ],
+ *   destination:      process.stdout,              // legacy single-sink
+ *   errorDestination: process.stderr,              // legacy two-sink split
+ *   format:           "json",
+ *   clock:            function () { return new Date(); }, // test seam
+ *
+ * @example
+ *   var log = b.log.create({
+ *     level: "info",
+ *     base:  { service: "myapp", version: "1.2.3" },
+ *   });
+ *   log.info("user logged in", { userId: "u-1" });
+ *   var authLog = log.bind({ component: "auth" });
+ *   authLog.warn("rate-limited", { ip: "203.0.113.7" });
+ *   // → {"timestamp":"...","level":"info","message":"user logged in",
+ *   //    "service":"myapp","version":"1.2.3","userId":"u-1"}
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
@@ -386,23 +421,30 @@ function create(opts) {
   return _makeInstance([]);
 }
 
-// ---- Boot logger ----
-//
-// Framework-internal modules emit human-readable startup chatter
-// during boot ("[blamejs:db] ready", "[blamejs:vault] WARNING: …"),
-// distinct from the structured app-level logger above. The boot
-// channel is TTY-aware:
-//
-//   - stdout is a TTY     → "[blamejs:<name>] <message>" line
-//   - stdout is piped     → JSON line { timestamp, level, message,
-//                                       component: <name>, boot: true }
-//
-// This keeps `npm start` readable for humans while letting log
-// aggregators ingest boot chatter as structured records.
-//
-// Returned object is a callable (info path) plus .info / .warn /
-// .error / .prefix members so calls like `log("ready")` and
-// `log.warn("…")` both work.
+/**
+ * @primitive b.log.boot
+ * @signature b.log.boot(name)
+ * @since     0.7.0
+ * @status    stable
+ * @related   b.log.create, b.log.makeViaOrFallback
+ *
+ * Framework-internal boot logger for human-readable startup chatter
+ * (`[blamejs:db] ready`, `[blamejs:vault] WARNING: ...`). TTY-aware:
+ * when stdout is a terminal it emits a prefixed line; when stdout is
+ * piped it emits a one-line JSON object so log aggregators can ingest
+ * boot chatter as structured records. The returned value is a
+ * callable (info path) plus `.debug` / `.info` / `.warn` / `.error` /
+ * `.prefix` members so `log("ready")` and `log.warn("...")` both
+ * work.
+ *
+ * @example
+ *   var log = b.log.boot("db");
+ *   log("ready");
+ *   log.warn("connection slow");
+ *   // → "[blamejs:db] ready"   (TTY)
+ *   // → {"timestamp":"...","level":"info","message":"ready",
+ *   //    "component":"db","boot":true}  (piped)
+ */
 function boot(name) {
   if (typeof name !== "string" || name.length === 0) {
     throw new LogError("log/bad-name", "log.boot(name) requires a non-empty name");
@@ -456,20 +498,27 @@ function boot(name) {
   return info;
 }
 
-// makeViaOrFallback — closure factory for operator-log routing. Used by
-// bundler / dev / error-page / pqc-gate (and similar primitives) that
-// accept opts.log but must keep emitting through a per-module fallback
-// when the operator didn't pass one. Replaces the per-file
-// `function _logVia(log, level, message, fields) { if (log && typeof
-// log[level] === "function") { try { log[level](message, fields); }
-// catch ... } return; } ... fallback;` boilerplate.
-//
-//   var _logVia = log.makeViaOrFallback(opts.log, log.boot("bundler"));
-//   _logVia("error", "build-failed", { reason: "..." });
-//
-// The operator log call is best-effort: a misbehaving log[level] swallows
-// internally rather than crash the caller. Fallback is invoked only when
-// the operator log is absent or doesn't expose the requested level.
+/**
+ * @primitive b.log.makeViaOrFallback
+ * @signature b.log.makeViaOrFallback(operatorLog, fallbackLog)
+ * @since     0.7.30
+ * @status    stable
+ * @related   b.log.create, b.log.boot
+ *
+ * Closure factory for operator-log routing. Used by primitives
+ * (bundler, dev server, error-page renderer, pqc-gate, ...) that
+ * accept `opts.log` but must keep emitting through a per-module
+ * fallback when the operator didn't pass one. The operator log call
+ * is best-effort — a misbehaving `log[level]` is swallowed rather
+ * than crashing the caller. Fallback fires only when the operator
+ * log is absent or doesn't expose the requested level.
+ *
+ * @example
+ *   var fallback = b.log.boot("bundler");
+ *   var via = b.log.makeViaOrFallback(null, fallback);
+ *   via("error", "build-failed", { reason: "missing entrypoint" });
+ *   // → "[blamejs:bundler] build-failed {\"reason\":\"missing entrypoint\"}"
+ */
 function makeViaOrFallback(operatorLog, fallbackLog) {
   return function (level, message, fields) {
     if (operatorLog && typeof operatorLog[level] === "function") {
@@ -514,14 +563,63 @@ function _bootMinLevel() {
   return LEVELS[raw] != null ? LEVELS[raw] : LEVELS.info;
 }
 
+/**
+ * @primitive b.log.getRequestId
+ * @signature b.log.getRequestId()
+ * @since     0.1.70
+ * @status    stable
+ * @related   b.log.runWithRequestId, b.log.create
+ *
+ * Read the current AsyncLocalStorage-bound request id, or `null`
+ * when called outside a `runWithRequestId` / middleware-wrapped
+ * scope. The module-level helper exists for code paths that don't
+ * have a logger instance handy but still need to read the
+ * request-correlation token (e.g. an external SDK callback that
+ * must include the id in a remote span).
+ *
+ * @example
+ *   await b.log.runWithRequestId("req-abc", async function () {
+ *     var id = b.log.getRequestId();
+ *     // → "req-abc"
+ *   });
+ */
+function getRequestId() {
+  var s = _getStore();
+  return s ? s.requestId : null;
+}
+
+/**
+ * @primitive b.log.runWithRequestId
+ * @signature b.log.runWithRequestId(id, fn)
+ * @since     0.1.70
+ * @status    stable
+ * @related   b.log.getRequestId, b.log.create
+ *
+ * Run `fn` inside an AsyncLocalStorage scope where
+ * `b.log.getRequestId()` returns `id`. Every `b.log.create`-built
+ * logger inside the scope automatically picks up the id on each
+ * emitted line. Returns whatever `fn` returns (including a Promise);
+ * the binding propagates through `await` boundaries via Node's
+ * async-context plumbing.
+ *
+ * @example
+ *   var result = await b.log.runWithRequestId("req-abc", async function () {
+ *     return b.log.getRequestId();
+ *   });
+ *   // → "req-abc"
+ */
+function runWithRequestId(id, fn) {
+  return _als.run({ requestId: id || null, _extra: {} }, fn);
+}
+
 module.exports = {
-  create:           create,
-  boot:             boot,
+  create:            create,
+  boot:              boot,
   makeViaOrFallback: makeViaOrFallback,
-  LEVELS:           LEVELS,
-  LogError:         LogError,
+  LEVELS:            LEVELS,
+  LogError:          LogError,
   // Module-level helpers for code paths that don't have a logger
   // instance handy but still need to read ALS state.
-  getRequestId:     function () { var s = _getStore(); return s ? s.requestId : null; },
-  runWithRequestId: function (id, fn) { return _als.run({ requestId: id || null, _extra: {} }, fn); },
+  getRequestId:      getRequestId,
+  runWithRequestId:  runWithRequestId,
 };

package/lib/mail-bounce.js

@@ -1,66 +1,39 @@
 "use strict";
 /**
- * mail-bounce — vendor-shaped intake for outbound-mail bounces /
- * complaints / delivery callbacks.
+ * @module b.mailBounce
+ * @nav    Communication
+ * @title  Mail Bounce
  *
- * Outbound mail can come back as:
- *   - a hard or soft bounce (delivery failure)
- *   - a spam / abuse complaint
- *   - a delivered confirmation
- *   - a list-unsubscribe complaint
+ * @intro
+ *   Inbound mail bounce-handler — parse the vendor's webhook DSN /
+ *   complaint / delivery payload, normalize it into one event shape,
+ *   classify hard vs soft bounces, and feed an operator-supplied
+ *   suppression-list hook.
  *
- * Vendors (Postmark, SES via SNS, Resend) ship these as HTTP webhooks
- * with payload shapes that all carry the same information dressed up
- * differently. This module owns the translation: each vendor parser
- * normalizes its payload into one shape so operators don't write
- * vendor-specific reconciliation code per environment.
+ *   Outbound mail comes back as a hard bounce (permanent — invalid
+ *   address), a soft bounce (transient — mailbox full, greylisted), a
+ *   spam / abuse complaint, a delivery confirmation, or a list-
+ *   unsubscribe. Vendors (Postmark, AWS SES via SNS, Resend) ship the
+ *   same information dressed up in three different JSON shapes. This
+ *   module owns the translation so operators write a single
+ *   reconciliation path regardless of vendor.
  *
- * Public API:
+ *   `b.mailBounce.parse` is the pure synchronous parser; it returns the
+ *   normalized event `{ vendor, type, subType, recipient, messageId,
+ *   reason, timestamp, raw }`. `b.mailBounce.handler` wires that
+ *   parser into an Express-style middleware that buffers the body,
+ *   runs an operator `verify` hook (HMAC, Basic Auth, SNS-Signature),
+ *   emits a `system.mail.bounce` audit row, and calls the operator's
+ *   `onBounce(event)` so the suppression list can be updated before
+ *   the 200 response goes back.
  *
- *   mailBounce.parse(payload, { vendor })
- *     Pure synchronous parser. Returns the normalized event:
- *       {
- *         vendor:    "postmark" | "ses" | "resend",
- *         type:      "bounce" | "complaint" | "delivery",
- *         subType:   "hard" | "soft" | "abuse" | ... | null,
- *         recipient: "user@example.com",
- *         messageId: "<framework-emitted Message-ID>" | null,
- *         reason:    "smtp 550 ..." | null,
- *         timestamp: "2026-04-28T..." (ISO 8601),
- *         raw:       <input payload, untouched>,
- *       }
+ *   Generic RFC 3464 DSN is intentionally NOT a built-in vendor —
+ *   parsing arbitrary MTA reports needs a full email parser the
+ *   framework does not vendor for this surface. Operators with raw
+ *   DSN inflow supply `{ parser }` to plug a custom normalizer.
  *
- *   mailBounce.handler({ vendor, verify?, onBounce?, audit?, ... })
- *     Returns an Express-style middleware (req, res). Buffers + parses
- *     the request body, calls verify(req, body) if supplied, runs the
- *     parser, emits system.mail.bounce, calls onBounce(event), and
- *     responds 200. Validation errors land as 400 with a JSON error.
- *     Verification failures land as 401.
- *
- * Operator example (Postmark):
- *
- *   var bounce = b.mailBounce.handler({
- *     vendor:   "postmark",
- *     verify:   function (req) {
- *       // Postmark recommends Basic Auth on the webhook URL.
- *       return req.headers.authorization === expectedBasic;
- *     },
- *     onBounce: function (event) {
- *       // Mark the recipient as bounced in your data store.
- *       return repo.users.markBounced(event.recipient, event.subType);
- *     },
- *   });
- *   r.post("/webhooks/postmark", bounce);
- *
- * Audit: every parsed bounce/complaint/delivery emits one
- * `system.mail.bounce` row carrying the normalized fields. Audit is on
- * by default and disabled per-instance via { audit: false }.
- *
- * Generic DSN (RFC 3464 multipart/report) is intentionally NOT included
- * as a built-in vendor: parsing arbitrary email-back-from-MTA reports
- * needs a full email parser, which the framework does not vendor for
- * this surface. Operators with raw DSN inflow plug a custom parser via
- * the { vendor: 'custom', parser } shape (see _customParser below).
+ * @card
+ *   Inbound mail bounce-handler — parse the vendor's webhook DSN / complaint / delivery payload, normalize it into one event shape, classify hard vs soft bounces, and feed an operator-supplied suppression-list hook.
  */
 
 var lazyRequire = require("./lazy-require");
@@ -368,6 +341,43 @@ var VENDORS = {
   resend:   _parseResend,
 };
 
+/**
+ * @primitive b.mailBounce.parse
+ * @signature b.mailBounce.parse(payload, opts)
+ * @since     0.5.0
+ * @status    stable
+ * @related   b.mailBounce.handler
+ *
+ * Pure synchronous parser. Routes `payload` through the chosen vendor
+ * parser (built-ins: `postmark`, `ses`, `resend`) and returns the
+ * normalized event. Operators with bespoke vendors supply
+ * `opts.parser` — a function `(payload) -> normalizedEvent` that the
+ * framework runs and then validates so a misbehaving custom parser
+ * cannot emit malformed audit rows.
+ *
+ * Throws `MailBounceError` (HTTP 400) on missing / unknown vendor,
+ * empty payload, or payload missing the required vendor-specific
+ * fields. Never mutates `payload` — the original is preserved on
+ * `event.raw` for downstream re-parsing.
+ *
+ * @opts
+ *   vendor: "postmark" | "ses" | "resend",       // required when `parser` is absent
+ *   parser: function (payload): normalizedEvent, // alternative to `vendor`
+ *
+ * @example
+ *   var event = b.mailBounce.parse({
+ *     RecordType:  "Bounce",
+ *     Type:        "HardBounce",
+ *     Email:       "user@example.com",
+ *     MessageID:   "abc-123",
+ *     Description: "550 No such mailbox",
+ *     BouncedAt:   "2026-04-28T10:00:00Z",
+ *   }, { vendor: "postmark" });
+ *   event.type;      // → "bounce"
+ *   event.subType;   // → "hard"
+ *   event.recipient; // → "user@example.com"
+ *   event.timestamp; // → "2026-04-28T10:00:00Z"
+ */
 function parse(payload, opts) {
   opts = opts || {};
   if (typeof opts.parser === "function") {
@@ -387,12 +397,47 @@ function parse(payload, opts) {
   return fn(payload);
 }
 
-// ---- Webhook handler middleware ----
-//
-// Buffers the request body (JSON), runs verify() if supplied, parses
-// via the configured vendor / custom parser, emits the audit event,
-// invokes onBounce, and responds 200. Errors map to 400 (bad payload),
-// 401 (verify rejected), 413 (body too large), 500 (onBounce threw).
+/**
+ * @primitive b.mailBounce.handler
+ * @signature b.mailBounce.handler(opts)
+ * @since     0.5.0
+ * @status    stable
+ * @related   b.mailBounce.parse, b.audit.safeEmit
+ *
+ * Returns an Express-style `(req, res)` middleware that buffers the
+ * inbound webhook body (capped at `maxBytes`), runs `verify(req, body,
+ * raw)` if supplied, parses via the configured vendor (or custom
+ * `parser`), emits one `system.mail.bounce` audit row, calls
+ * `onBounce(event)`, and responds 200. Failures map to 400 (bad
+ * payload), 401 (verify rejected), 413 (body too large), 500
+ * (`onBounce` threw).
+ *
+ * `audit` defaults to ON; pass `audit: false` to suppress the
+ * `system.mail.bounce` row when the operator already records the
+ * normalized event in their own data store.
+ *
+ * @opts
+ *   vendor:   "postmark" | "ses" | "resend",
+ *   parser:   function (payload): normalizedEvent,    // alternative to `vendor`
+ *   verify:   function (req, body, raw): boolean,     // optional authenticity gate
+ *   onBounce: function (event): Promise|void,         // operator suppression hook
+ *   audit:    boolean,                                 // default: true
+ *   maxBytes: number,                                  // body cap; default 256 KiB
+ *
+ * @example
+ *   var bounce = b.mailBounce.handler({
+ *     vendor:   "postmark",
+ *     verify:   function (req) {
+ *       return req.headers.authorization === "Basic c2VjcmV0";
+ *     },
+ *     onBounce: function (event) {
+ *       suppressionList[event.recipient] = event.subType;
+ *     },
+ *     maxBytes: b.constants.BYTES.kib(64),
+ *   });
+ *   typeof bounce; // → "function"
+ *   bounce.length; // → 2
+ */
 function handler(opts) {
   opts = opts || {};
   var vendor = opts.vendor;