@bymax-one/nest-logger 1.4.1 → 1.4.3

package/dist/server/index.cjs

@@ -2,6 +2,7 @@
 
 var common = require('@nestjs/common');
 var core = require('@nestjs/core');
+var util = require('util');
 var rxjs = require('rxjs');
 var pino = require('pino');
 var module$1 = require('module');
@@ -29,7 +30,7 @@ var DEFAULT_HTTP = {
   isEnabled: false,
   shouldCaptureExceptions: true,
   shouldGenerateRequestId: true,
-  excludePaths: [/^\/health$/, /^\/metrics$/],
+  excludePaths: [/^\/health$/, /^\/health\/live$/, /^\/health\/ready$/, /^\/metrics$/],
   tenantIdHeader: "x-tenant-id"
 };
 var DEFAULT_OTEL = {
@@ -114,7 +115,36 @@ var LOG_LEVEL_PRIORITY = Object.freeze([
 ]);
 
 // src/server/config/validate-options.ts
-function validateOptions(options) {
+function reject(path, rule, got) {
+  const received = got === void 0 ? "" : `. Got: ${describeValue(got)}`;
+  throw new Error(`[BymaxLoggerModule] options.${path} ${rule}${received}`);
+}
+function describeValue(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  if (typeof value === "object") return "an object";
+  if (typeof value === "function") return "a function";
+  if (typeof value === "string") return JSON.stringify(value);
+  return String(value);
+}
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isNonEmptyString = (value) => typeof value === "string" && value.length > 0;
+function checkBoolean(path, value) {
+  if (value !== void 0 && typeof value !== "boolean") {
+    reject(path, "must be a boolean", value);
+  }
+}
+function checkNonEmptyString(path, value) {
+  if (value !== void 0 && !isNonEmptyString(value)) {
+    reject(path, "must be a non-empty string", value);
+  }
+}
+function checkGroup(path, value) {
+  if (value === void 0) return void 0;
+  if (!isRecord(value)) reject(path, "must be an object", value);
+  return value;
+}
+function validateCore(options) {
   if (!options.service) {
     throw new Error("[BymaxLoggerModule] options.service is required");
   }
@@ -131,9 +161,15 @@ function validateOptions(options) {
       )}. Got: ${String(options.level)}`
     );
   }
+  const size = options.maxEntrySizeBytes;
+  if (size !== void 0 && !Number.isFinite(size)) {
+    reject("maxEntrySizeBytes", "must be a finite number", size);
+  }
   if (options.maxEntrySizeBytes !== void 0 && options.maxEntrySizeBytes <= 0) {
     throw new Error("[BymaxLoggerModule] options.maxEntrySizeBytes must be > 0");
   }
+}
+function validateClosedSets(options) {
   if (options.redactStrategy !== void 0 && options.redactStrategy !== "names" && options.redactStrategy !== "paths") {
     throw new Error(
       `[BymaxLoggerModule] options.redactStrategy must be 'names' or 'paths'. Got: ${String(
@@ -163,6 +199,109 @@ function validateOptions(options) {
     );
   }
 }
+function validateCustomization(options) {
+  checkBoolean("isGlobal", options.isGlobal);
+  checkBoolean("shouldDisableDefaultRedact", options.shouldDisableDefaultRedact);
+  if (options.redactCensor !== void 0 && typeof options.redactCensor !== "string") {
+    reject("redactCensor", "must be a string", options.redactCensor);
+  }
+  if (options.timestamp !== void 0 && typeof options.timestamp !== "function") {
+    reject("timestamp", "must be a function", options.timestamp);
+  }
+  const paths = options.redactPaths;
+  if (paths !== void 0) {
+    if (!Array.isArray(paths)) reject("redactPaths", "must be an array of strings", paths);
+    paths.forEach((entry, index) => {
+      if (!isNonEmptyString(entry)) {
+        reject(`redactPaths[${String(index)}]`, "must be a non-empty string", entry);
+      }
+    });
+  }
+  const serializers = options.serializers;
+  if (serializers !== void 0) {
+    if (!isRecord(serializers)) reject("serializers", "must be an object", serializers);
+    for (const [key, serializer] of Object.entries(serializers)) {
+      if (typeof serializer !== "function") {
+        reject(`serializers.${key}`, "must be a function", serializer);
+      }
+    }
+  }
+}
+var UNREADABLE = /* @__PURE__ */ Symbol("unreadable");
+function readMember(destination, key) {
+  try {
+    return Reflect.get(destination, key);
+  } catch {
+    return UNREADABLE;
+  }
+}
+function validateDestination(entry, index) {
+  const path = `destinations[${String(index)}]`;
+  if (!isRecord(entry)) {
+    reject(path, "must be an object implementing ILogDestination", entry);
+  }
+  const write = readMember(entry, "write");
+  if (write !== UNREADABLE && typeof write !== "function") {
+    reject(path, "must have a write(payload) method");
+  }
+  const name = readMember(entry, "name");
+  if (name !== UNREADABLE && !isNonEmptyString(name)) {
+    reject(path, "must have a non-empty string name", name);
+  }
+  for (const hook of ["onInit", "onShutdown", "onRegistryReady"]) {
+    const value = readMember(entry, hook);
+    if (value !== UNREADABLE && value !== void 0 && typeof value !== "function") {
+      reject(`${path}.${hook}`, "must be a function", value);
+    }
+  }
+}
+function validateDestinations(options) {
+  const destinations = options.destinations;
+  if (destinations === void 0) return;
+  if (!Array.isArray(destinations)) {
+    reject("destinations", "must be an array of ILogDestination", destinations);
+  }
+  destinations.forEach((entry, index) => validateDestination(entry, index));
+}
+function validateHttp(options) {
+  const http = checkGroup("http", options.http);
+  if (http === void 0) return;
+  checkBoolean("http.isEnabled", http["isEnabled"]);
+  checkBoolean("http.shouldCaptureExceptions", http["shouldCaptureExceptions"]);
+  checkBoolean("http.shouldGenerateRequestId", http["shouldGenerateRequestId"]);
+  const excludePaths = http["excludePaths"];
+  if (excludePaths !== void 0) {
+    if (!Array.isArray(excludePaths)) {
+      reject("http.excludePaths", "must be an array of RegExp", excludePaths);
+    }
+    excludePaths.forEach((pattern, index) => {
+      if (!util.types.isRegExp(pattern)) {
+        reject(`http.excludePaths[${String(index)}]`, "must be a RegExp", pattern);
+      }
+    });
+  }
+  checkNonEmptyString("http.tenantIdHeader", http["tenantIdHeader"]);
+}
+function validateOtel(options) {
+  const otel = checkGroup("otel", options.otel);
+  if (otel === void 0) return;
+  checkBoolean("otel.shouldAutoInjectTraceContext", otel["shouldAutoInjectTraceContext"]);
+  const format = otel["fieldFormat"];
+  if (format !== void 0 && format !== "camelCase" && format !== "snake_case") {
+    reject("otel.fieldFormat", "must be 'camelCase' or 'snake_case'", format);
+  }
+  checkNonEmptyString("otel.traceIdField", otel["traceIdField"]);
+  checkNonEmptyString("otel.spanIdField", otel["spanIdField"]);
+  checkNonEmptyString("otel.traceFlagsField", otel["traceFlagsField"]);
+}
+function validateOptions(options) {
+  validateCore(options);
+  validateClosedSets(options);
+  validateCustomization(options);
+  validateDestinations(options);
+  validateHttp(options);
+  validateOtel(options);
+}
 
 // src/server/constants/injection-tokens.constants.ts
 var LOGGER_OPTIONS_TOKEN = /* @__PURE__ */ Symbol("BYMAX_LOGGER_OPTIONS");
@@ -1609,8 +1748,11 @@ function buildPinoInstance(options, logContext, destinations, health) {
       options.resourceFormat,
       extraServiceFields(options.service)
     ),
-    // Pino requires the timestamp fn to emit the `,"time":"..."` fragment.
-    timestamp: () => `,"time":"${options.timestamp()}"`,
+    // Pino requires the timestamp fn to emit the `,"time":<json>` fragment, and
+    // inserts it into the line verbatim. The value comes from consumer code, so it
+    // is encoded as a JSON string here: a quote, a backslash or a newline in it must
+    // neither break the line nor add fields to it.
+    timestamp: () => `,"time":${JSON.stringify(String(options.timestamp()))}`,
     formatters: {
       // Emit the level as a string label instead of the numeric code — easier
       // for log aggregators. Trace context is injected via `mixin`, never via
@@ -2468,10 +2610,18 @@ var PrettyDevDestination = class {
    * Lazily resolve `pino-pretty` and build the colorized transform that renders
    * each entry to `process.stdout`.
    *
+   * @throws Error When `NODE_ENV` is `production`: this sink is development
+   *   output, so it refuses rather than put ANSI colour into the log stream.
    * @throws Error When `pino-pretty` is not installed — with an actionable
    *   message telling the consumer to install it or drop this destination.
    */
   async onInit() {
+    if (process.env["NODE_ENV"] === "production") {
+      this.initFailed = true;
+      throw new Error(
+        "[PrettyDevDestination] refused in production (NODE_ENV=production): it renders ANSI colour through a main-thread transform. Use DefaultStdoutDestination, or register PrettyDevDestination only outside production."
+      );
+    }
     try {
       const { build } = await import('pino-pretty');
       this.stream = build({
@@ -2598,8 +2748,8 @@ var PrettyDevDestination = class {
       this.flushBuffer(writeRawToStdout);
       return;
     }
-    await new Promise((resolve, reject) => {
-      stream.once("error", reject);
+    await new Promise((resolve, reject2) => {
+      stream.once("error", reject2);
       stream.end(resolve);
     });
   }
@@ -3033,6 +3183,7 @@ exports.InjectLogger = InjectLogger;
 exports.LOGGER_DESTINATIONS_TOKEN = LOGGER_DESTINATIONS_TOKEN;
 exports.LOGGER_OPTIONS_TOKEN = LOGGER_OPTIONS_TOKEN;
 exports.LOGGER_PINO_INSTANCE_TOKEN = LOGGER_PINO_INSTANCE_TOKEN;
+exports.LOGGER_REDACTOR_TOKEN = LOGGER_REDACTOR_TOKEN;
 exports.LOG_CONTEXT_METADATA_KEY = LOG_CONTEXT_METADATA_KEY;
 exports.LOG_CONTEXT_TOKEN = LOG_CONTEXT_TOKEN;
 exports.LOG_KEYS_CONVENTION_REGEX = LOG_KEYS_CONVENTION_REGEX;
@@ -3041,7 +3192,9 @@ exports.LogPerformance = LogPerformance;
 exports.PINO_LEVEL_NAMES = PINO_LEVEL_NAMES;
 exports.PINO_LEVEL_NUMBERS = PINO_LEVEL_NUMBERS;
 exports.PrettyDevDestination = PrettyDevDestination;
+exports.REDACT_COMMON_FIELDS = REDACT_COMMON_FIELDS;
 exports.RESERVED_LOG_KEYS = RESERVED_LOG_KEYS;
 exports.RESERVED_LOG_KEYS_NOT_EMITTED = RESERVED_LOG_KEYS_NOT_EMITTED;
 exports.applyAccessLog = applyAccessLog;
 exports.applyRequestIdMiddleware = applyRequestIdMiddleware;
+exports.isValidTraceId = isValidTraceId;

package/dist/server/index.d.cts

@@ -52,7 +52,9 @@ interface ILogDestination {
     readonly name: string;
     /**
      * Minimum log level this destination accepts. Entries below this level
-     * are not written. Undefined means "accept everything".
+     * are not written. The effective level is the STRICTER of this and the module
+     * `level`, so it can only narrow what the logger emits, never widen it.
+     * Undefined means "every entry the module level lets through".
      */
     readonly minLevel?: LogLevel;
     /**
@@ -64,8 +66,13 @@ interface ILogDestination {
      *   - Buffer and flush periodically (e.g., HTTP batching)
      *   - Return a Promise for async I/O
      *
-     * Errors thrown here are caught by the library; the destination may be
-     * temporarily skipped if it consistently fails.
+     * Errors thrown here, and rejections of a returned promise, are caught by the
+     * library: the entry is dropped for this destination only, and one failure line
+     * is written to stderr per failed entry. There is no retry and no circuit
+     * breaker, so a destination that initialized and keeps failing keeps receiving
+     * entries and keeps being reported; one that needs to back off does so itself.
+     * (A destination whose `onInit()` failed is a different case: it receives no
+     * entries at all.)
      *
      * @param payload — Newline-terminated JSON entry, UTF-8 encoded.
      */
@@ -250,30 +257,35 @@ interface EmittedDeploymentResource {
  * Every field is optional; defaults are applied by `applyDefaults`.
  */
 interface HttpOptions {
-    /** Mount the HTTP interceptor + filter. Default: false. */
+    /**
+     * Mount the HTTP interceptor + filter. Default: false. The filter is registered by
+     * `forRoot` only: `forRootAsync` registers the interceptor and leaves the filter to
+     * the consumer (`{ provide: APP_FILTER, useClass: HttpExceptionFilter }`).
+     */
     isEnabled?: boolean;
-    /** Capture unhandled HTTP exceptions and emit `HTTP_EXCEPTION_UNHANDLED`. Default: true. */
+    /**
+     * Capture unhandled HTTP exceptions and emit `HTTP_EXCEPTION_UNHANDLED`. Default: true.
+     * Read by `forRoot` only; it has no effect on `forRootAsync`, which never registers the
+     * filter.
+     */
     shouldCaptureExceptions?: boolean;
     /** Generate `requestId` when the request header is absent. Default: true. */
     shouldGenerateRequestId?: boolean;
     /**
      * Paths that bypass HTTP logging (health checks, metrics). Defaults:
-     * `/health`, `/metrics`.
-     *
-     * The defaults do NOT cover `@bymax-one/nest-core`, and that is the common case
-     * worth knowing before you rely on them. It serves liveness and readiness at
-     * `/health/live` and `/health/ready`, and no bare `/health` at all, so
-     * `/^\/health$/` excludes a route that does not exist while both probes are
-     * logged. Measured on one deployment: 8272 of 8274 HTTP entries were the
-     * liveness probe. Set `excludePaths` yourself when wiring the two together —
-     * `[/^\/health\/(live|ready)$/, /^\/metrics$/]` matches the stock layout.
-     *
-     * The defaults are not widened to include those subpaths because both prefixes
-     * are CONFIGURABLE there (`DEFAULT_HEALTH_PATH`, `DEFAULT_METRICS_PATH`): any
-     * default naming specific subpaths would be less wrong rather than correct, and
-     * a prefix pattern would silently swallow a consumer's own `/health/*` route
-     * that they did want logged. Excluding a path is a decision about which requests
-     * disappear from the record, so it stays explicit.
+     * `/health`, `/health/live`, `/health/ready`, `/metrics`.
+     *
+     * `/health/live` and `/health/ready` are the liveness and readiness probes of
+     * `@bymax-one/nest-core`, which serves no bare `/health`; left logged, a probe hit
+     * every few seconds drowns the record (measured on one deployment: 8272 of 8274
+     * HTTP entries were the liveness probe). Each default is an exact, anchored path,
+     * not a prefix, so a consumer's own `/health/other` route is still logged.
+     *
+     * The prefixes are CONFIGURABLE in nest-core (`DEFAULT_HEALTH_PATH`,
+     * `DEFAULT_METRICS_PATH`): when they are changed, or when the probes should be
+     * logged, set `excludePaths` yourself. A value REPLACES the defaults rather than
+     * adding to them; `[/^\/health$/, /^\/metrics$/]` excludes only `/health` and
+     * `/metrics`.
      *
      * SECURITY: each pattern is `.test()`-ed against the (attacker-controllable)
      * request path on every request. Supply only anchored, linear-time regexes
@@ -1171,6 +1183,8 @@ declare class PrettyDevDestination implements ILogDestination {
      * Lazily resolve `pino-pretty` and build the colorized transform that renders
      * each entry to `process.stdout`.
      *
+     * @throws Error When `NODE_ENV` is `production`: this sink is development
+     *   output, so it refuses rather than put ANSI colour into the log stream.
      * @throws Error When `pino-pretty` is not installed — with an actionable
      *   message telling the consumer to install it or drop this destination.
      */
@@ -1773,6 +1787,11 @@ declare const LOG_CONTEXT_METADATA_KEY = "bymax_logger:log_context";
  * Set the log-context label for a class. All loggers injected within the class
  * are intended to adopt this label (auto-application requires a wired interceptor).
  *
+ * @deprecated Nothing in this package reads the metadata, so the label is never
+ *   applied: no interceptor is wired. Inject a logger bound to the label with
+ *   `@InjectLogger(PaymentsService.name)` instead. Do not call `setContext()` on
+ *   the shared logger — it is a singleton, so that overwrites the label for every
+ *   other holder.
  * @param name - The context label (typically the class name).
  * @returns A NestJS metadata decorator carrying the label.
  * @example
@@ -1816,9 +1835,31 @@ declare const LOGGER_OPTIONS_TOKEN: unique symbol;
 declare const LOGGER_PINO_INSTANCE_TOKEN: unique symbol;
 /** Injection token for the resolved destinations array (read-only at runtime). */
 declare const LOGGER_DESTINATIONS_TOKEN: unique symbol;
+/**
+ * Injection token for the redaction function backing the DEFAULT PII coverage.
+ *
+ * Exposed as its own provider because `PinoLoggerService.child()` has to apply
+ * it BEFORE handing bindings to Pino: child bindings are pre-serialized into the
+ * instance's `chindings` fragment and never reach `formatters.log`, so the
+ * factory's hook cannot see them.
+ */
+declare const LOGGER_REDACTOR_TOKEN: unique symbol;
 /** Injection token for the per-request AsyncLocalStorage-backed log context. */
 declare const LOG_CONTEXT_TOKEN: unique symbol;
 
+/**
+ * The canonical sensitive-field-name set.
+ *
+ * Under the default `redactStrategy: 'names'` this list IS the redaction
+ * contract: a value is censored when its key name appears here, at any depth.
+ * Under the legacy `'paths'` strategy the same names are expanded to depths 1–4
+ * by {@link depth} to build {@link DEFAULT_REDACT_PATHS}.
+ *
+ * Append-only: a name may be added in a minor release; removing one requires a
+ * major, because a field that silently stopped being redacted is a leak no
+ * consumer would notice.
+ */
+declare const REDACT_COMMON_FIELDS: readonly string[];
 /**
  * The legacy `fast-redact` path expansion of {@link REDACT_COMMON_FIELDS}:
  * every name at the record root plus wildcard depths 1–4, followed by the
@@ -1837,6 +1878,17 @@ declare const LOG_CONTEXT_TOKEN: unique symbol;
  */
 declare const DEFAULT_REDACT_PATHS: readonly string[];
 
+/**
+ * Check whether a trace ID is a valid, non-zero W3C Trace Context value.
+ *
+ * Enforces 32 lowercase hex characters (rejecting non-hex input that could
+ * carry log-injection payloads) and rejects the all-zeros "no trace" sentinel.
+ *
+ * @param traceId - The candidate trace ID.
+ * @returns `true` when the ID is 32 lowercase hex chars and not all zeros.
+ */
+declare function isValidTraceId(traceId: string): boolean;
+
 /**
  * Pino numeric level mapping. Frozen at runtime so destinations and the
  * NestJS bridge can rely on a stable wire-format contract.
@@ -1944,4 +1996,5 @@ interface LogEntry {
  */
 declare const LOG_KEYS_CONVENTION_REGEX: RegExp;
 
-export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, type EmittedDeploymentResource, type EmittedServiceResource, HttpAccessLogMiddleware, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, type IUnexpectedErrorSink, type IncomingHeaders, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type LoggableRequest, type LoggableResponse, type NextHandler, type OtelOptions, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PinoUnexpectedErrorSink, PrettyDevDestination, type PrettyViewOptions, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, type ReservedLogKey, type ResolvedBymaxLoggerModuleOptions, type ResolvedServiceMetadata, type ServiceMetadata, type UnexpectedErrorReport, applyAccessLog, applyRequestIdMiddleware };
+export { BymaxLoggerModule, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, HttpAccessLogMiddleware, HttpExceptionFilter, HttpLoggingInterceptor, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOGGER_REDACTOR_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, LogContextService, LogPerformance, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PinoUnexpectedErrorSink, PrettyDevDestination, REDACT_COMMON_FIELDS, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, applyAccessLog, applyRequestIdMiddleware, isValidTraceId };
+export type { BymaxLoggerModuleAsyncOptions, BymaxLoggerModuleOptions, BymaxLoggerModuleOptionsFactory, EmittedDeploymentResource, EmittedServiceResource, HttpOptions, ILogDestination, IUnexpectedErrorSink, IncomingHeaders, LogContext$1 as LogContextBag, LogEntry, LogLevel, LoggableRequest, LoggableResponse, NextHandler, OtelOptions, PrettyViewOptions, ReservedLogKey, ResolvedBymaxLoggerModuleOptions, ResolvedServiceMetadata, ServiceMetadata, UnexpectedErrorReport };

package/dist/server/index.d.ts

@@ -52,7 +52,9 @@ interface ILogDestination {
     readonly name: string;
     /**
      * Minimum log level this destination accepts. Entries below this level
-     * are not written. Undefined means "accept everything".
+     * are not written. The effective level is the STRICTER of this and the module
+     * `level`, so it can only narrow what the logger emits, never widen it.
+     * Undefined means "every entry the module level lets through".
      */
     readonly minLevel?: LogLevel;
     /**
@@ -64,8 +66,13 @@ interface ILogDestination {
      *   - Buffer and flush periodically (e.g., HTTP batching)
      *   - Return a Promise for async I/O
      *
-     * Errors thrown here are caught by the library; the destination may be
-     * temporarily skipped if it consistently fails.
+     * Errors thrown here, and rejections of a returned promise, are caught by the
+     * library: the entry is dropped for this destination only, and one failure line
+     * is written to stderr per failed entry. There is no retry and no circuit
+     * breaker, so a destination that initialized and keeps failing keeps receiving
+     * entries and keeps being reported; one that needs to back off does so itself.
+     * (A destination whose `onInit()` failed is a different case: it receives no
+     * entries at all.)
      *
      * @param payload — Newline-terminated JSON entry, UTF-8 encoded.
      */
@@ -250,30 +257,35 @@ interface EmittedDeploymentResource {
  * Every field is optional; defaults are applied by `applyDefaults`.
  */
 interface HttpOptions {
-    /** Mount the HTTP interceptor + filter. Default: false. */
+    /**
+     * Mount the HTTP interceptor + filter. Default: false. The filter is registered by
+     * `forRoot` only: `forRootAsync` registers the interceptor and leaves the filter to
+     * the consumer (`{ provide: APP_FILTER, useClass: HttpExceptionFilter }`).
+     */
     isEnabled?: boolean;
-    /** Capture unhandled HTTP exceptions and emit `HTTP_EXCEPTION_UNHANDLED`. Default: true. */
+    /**
+     * Capture unhandled HTTP exceptions and emit `HTTP_EXCEPTION_UNHANDLED`. Default: true.
+     * Read by `forRoot` only; it has no effect on `forRootAsync`, which never registers the
+     * filter.
+     */
     shouldCaptureExceptions?: boolean;
     /** Generate `requestId` when the request header is absent. Default: true. */
     shouldGenerateRequestId?: boolean;
     /**
      * Paths that bypass HTTP logging (health checks, metrics). Defaults:
-     * `/health`, `/metrics`.
-     *
-     * The defaults do NOT cover `@bymax-one/nest-core`, and that is the common case
-     * worth knowing before you rely on them. It serves liveness and readiness at
-     * `/health/live` and `/health/ready`, and no bare `/health` at all, so
-     * `/^\/health$/` excludes a route that does not exist while both probes are
-     * logged. Measured on one deployment: 8272 of 8274 HTTP entries were the
-     * liveness probe. Set `excludePaths` yourself when wiring the two together —
-     * `[/^\/health\/(live|ready)$/, /^\/metrics$/]` matches the stock layout.
-     *
-     * The defaults are not widened to include those subpaths because both prefixes
-     * are CONFIGURABLE there (`DEFAULT_HEALTH_PATH`, `DEFAULT_METRICS_PATH`): any
-     * default naming specific subpaths would be less wrong rather than correct, and
-     * a prefix pattern would silently swallow a consumer's own `/health/*` route
-     * that they did want logged. Excluding a path is a decision about which requests
-     * disappear from the record, so it stays explicit.
+     * `/health`, `/health/live`, `/health/ready`, `/metrics`.
+     *
+     * `/health/live` and `/health/ready` are the liveness and readiness probes of
+     * `@bymax-one/nest-core`, which serves no bare `/health`; left logged, a probe hit
+     * every few seconds drowns the record (measured on one deployment: 8272 of 8274
+     * HTTP entries were the liveness probe). Each default is an exact, anchored path,
+     * not a prefix, so a consumer's own `/health/other` route is still logged.
+     *
+     * The prefixes are CONFIGURABLE in nest-core (`DEFAULT_HEALTH_PATH`,
+     * `DEFAULT_METRICS_PATH`): when they are changed, or when the probes should be
+     * logged, set `excludePaths` yourself. A value REPLACES the defaults rather than
+     * adding to them; `[/^\/health$/, /^\/metrics$/]` excludes only `/health` and
+     * `/metrics`.
      *
      * SECURITY: each pattern is `.test()`-ed against the (attacker-controllable)
      * request path on every request. Supply only anchored, linear-time regexes
@@ -1171,6 +1183,8 @@ declare class PrettyDevDestination implements ILogDestination {
      * Lazily resolve `pino-pretty` and build the colorized transform that renders
      * each entry to `process.stdout`.
      *
+     * @throws Error When `NODE_ENV` is `production`: this sink is development
+     *   output, so it refuses rather than put ANSI colour into the log stream.
      * @throws Error When `pino-pretty` is not installed — with an actionable
      *   message telling the consumer to install it or drop this destination.
      */
@@ -1773,6 +1787,11 @@ declare const LOG_CONTEXT_METADATA_KEY = "bymax_logger:log_context";
  * Set the log-context label for a class. All loggers injected within the class
  * are intended to adopt this label (auto-application requires a wired interceptor).
  *
+ * @deprecated Nothing in this package reads the metadata, so the label is never
+ *   applied: no interceptor is wired. Inject a logger bound to the label with
+ *   `@InjectLogger(PaymentsService.name)` instead. Do not call `setContext()` on
+ *   the shared logger — it is a singleton, so that overwrites the label for every
+ *   other holder.
  * @param name - The context label (typically the class name).
  * @returns A NestJS metadata decorator carrying the label.
  * @example
@@ -1816,9 +1835,31 @@ declare const LOGGER_OPTIONS_TOKEN: unique symbol;
 declare const LOGGER_PINO_INSTANCE_TOKEN: unique symbol;
 /** Injection token for the resolved destinations array (read-only at runtime). */
 declare const LOGGER_DESTINATIONS_TOKEN: unique symbol;
+/**
+ * Injection token for the redaction function backing the DEFAULT PII coverage.
+ *
+ * Exposed as its own provider because `PinoLoggerService.child()` has to apply
+ * it BEFORE handing bindings to Pino: child bindings are pre-serialized into the
+ * instance's `chindings` fragment and never reach `formatters.log`, so the
+ * factory's hook cannot see them.
+ */
+declare const LOGGER_REDACTOR_TOKEN: unique symbol;
 /** Injection token for the per-request AsyncLocalStorage-backed log context. */
 declare const LOG_CONTEXT_TOKEN: unique symbol;
 
+/**
+ * The canonical sensitive-field-name set.
+ *
+ * Under the default `redactStrategy: 'names'` this list IS the redaction
+ * contract: a value is censored when its key name appears here, at any depth.
+ * Under the legacy `'paths'` strategy the same names are expanded to depths 1–4
+ * by {@link depth} to build {@link DEFAULT_REDACT_PATHS}.
+ *
+ * Append-only: a name may be added in a minor release; removing one requires a
+ * major, because a field that silently stopped being redacted is a leak no
+ * consumer would notice.
+ */
+declare const REDACT_COMMON_FIELDS: readonly string[];
 /**
  * The legacy `fast-redact` path expansion of {@link REDACT_COMMON_FIELDS}:
  * every name at the record root plus wildcard depths 1–4, followed by the
@@ -1837,6 +1878,17 @@ declare const LOG_CONTEXT_TOKEN: unique symbol;
  */
 declare const DEFAULT_REDACT_PATHS: readonly string[];
 
+/**
+ * Check whether a trace ID is a valid, non-zero W3C Trace Context value.
+ *
+ * Enforces 32 lowercase hex characters (rejecting non-hex input that could
+ * carry log-injection payloads) and rejects the all-zeros "no trace" sentinel.
+ *
+ * @param traceId - The candidate trace ID.
+ * @returns `true` when the ID is 32 lowercase hex chars and not all zeros.
+ */
+declare function isValidTraceId(traceId: string): boolean;
+
 /**
  * Pino numeric level mapping. Frozen at runtime so destinations and the
  * NestJS bridge can rely on a stable wire-format contract.
@@ -1944,4 +1996,5 @@ interface LogEntry {
  */
 declare const LOG_KEYS_CONVENTION_REGEX: RegExp;
 
-export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, type EmittedDeploymentResource, type EmittedServiceResource, HttpAccessLogMiddleware, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, type IUnexpectedErrorSink, type IncomingHeaders, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type LoggableRequest, type LoggableResponse, type NextHandler, type OtelOptions, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PinoUnexpectedErrorSink, PrettyDevDestination, type PrettyViewOptions, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, type ReservedLogKey, type ResolvedBymaxLoggerModuleOptions, type ResolvedServiceMetadata, type ServiceMetadata, type UnexpectedErrorReport, applyAccessLog, applyRequestIdMiddleware };
+export { BymaxLoggerModule, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, HttpAccessLogMiddleware, HttpExceptionFilter, HttpLoggingInterceptor, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOGGER_REDACTOR_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, LogContextService, LogPerformance, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PinoUnexpectedErrorSink, PrettyDevDestination, REDACT_COMMON_FIELDS, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, applyAccessLog, applyRequestIdMiddleware, isValidTraceId };
+export type { BymaxLoggerModuleAsyncOptions, BymaxLoggerModuleOptions, BymaxLoggerModuleOptionsFactory, EmittedDeploymentResource, EmittedServiceResource, HttpOptions, ILogDestination, IUnexpectedErrorSink, IncomingHeaders, LogContext$1 as LogContextBag, LogEntry, LogLevel, LoggableRequest, LoggableResponse, NextHandler, OtelOptions, PrettyViewOptions, ReservedLogKey, ResolvedBymaxLoggerModuleOptions, ResolvedServiceMetadata, ServiceMetadata, UnexpectedErrorReport };