@bymax-one/nest-logger 1.2.9 → 1.3.1

package/CHANGELOG.md

@@ -11,6 +11,80 @@ heading here.
 
 ## [Unreleased]
 
+## [1.3.1] - 2026-08-18
+
+### Documentation
+
+- **`excludePaths` says what its defaults do not reach.** The defaults are
+  `[/^\/health$/, /^\/metrics$/]`, and `@bymax-one/nest-core` serves liveness and readiness at
+  `/health/live` and `/health/ready` with no bare `/health` at all — so the default excludes a
+  route that does not exist while logging both probes. A consumer running both measured **8272 of
+  8274** HTTP entries as the liveness probe, at one container healthcheck every ten seconds; at
+  orchestrator volume it is the same shape with more zeros. There is no error and no warning, and
+  the config reads as though it were handled.
+
+  The defaults are **not** widened, and the reason is checkable rather than a preference: both
+  prefixes are configurable there (`DEFAULT_HEALTH_PATH`, `DEFAULT_METRICS_PATH`). A default
+  naming specific subpaths would be less wrong rather than correct, and a prefix pattern would
+  silently swallow a consumer's own `/health/*` route they did want logged. Excluding a path
+  decides which requests vanish from the record, so it stays explicit — the docblock now carries
+  the one-line fix for the stock layout, and it ships in the `.d.ts` where someone wiring the two
+  libraries reads it.
+
+### Internal
+
+- **The last surviving mutant is gone, by deletion rather than annotation.** A `catch` in
+  `report-destination-failure` re-assigned `undefined` to a variable already `undefined` from its
+  declaration, so emptying the block changed no output for any input and no test could kill it. A
+  Stryker directive was tried first and was not honoured at that position. The project scores
+  **100.00** on a cold run: 1515 mutants, 841 killed, zero survivors, 145 documented equivalents.
+
+## [1.3.0] - 2026-08-18
+
+### Fixed
+
+- **A frozen `Error` lost every field, including its own message.** A consumer that freezes its
+  errors — deliberate and documented practice, so nobody mutates an issue list after the throw —
+  hands over properties that are neither writable nor configurable. The redactor's clone inherited
+  those descriptors, and rewriting any key whose walked value is a fresh object (a censored secret,
+  or simply the structural copy the walk makes of a nested array) could not redefine it. That
+  failure reached the fail-closed guard and dropped the **whole** record, so the entry became
+  `_redactionFailed: true` and nothing else — total silent loss on the error that crashed the
+  process, which is the one entry worth logging.
+
+  A frozen error carrying only scalars never showed it, because redefining a property with the same
+  primitive succeeds; it took a nested object to expose it. Reported against 1.2.7 by a consumer and
+  reproduced unchanged on 1.2.9.
+
+  The clone is transient — built, serialized, discarded — so it is now built with relaxed
+  descriptors and the write always lands. **The caller's error is never touched**, and freezing
+  remains the caller's guarantee about the caller's own object.
+
+  A non-configurable secret is now **censored** rather than dropped: same protection, without
+  losing the surrounding fields. The frozen error also keeps its **stack** again — V8 exposes it as
+  an own property bound to the original's internal state, so the clone pins a resolved copy, and on
+  a frozen error that pin was failing silently too. The case that did NOT drop the record was
+  therefore already reaching the sink with its trace erased, which is the same defect wearing a
+  healthy face; a consumer measured that independently. `LOGGER_REDACTION_FAILED` is unchanged for the case it was written
+  for — a record the walk cannot READ, such as a throwing getter or a hostile proxy.
+
+### Documentation
+
+- **The limit of field-based redaction now ships.** A value interpolated into the message has no
+  field name for any strategy to match — not an uncovered one, none — so no configuration closes
+  that gap and the rule is "a value that matters is a field, not text". It was stated only in
+  `docs/OBSERVABILITY-CONTRACT.md`, which is not in `files`: it reached whoever had the repository
+  and nobody who installs from npm. The decision it governs is made at a call site in a derived
+  backend whose only copy of this contract is what the registry delivers, so it is in the README's
+  security model now, beside the case it sharpens — that one covers a secret inside a field's
+  **value**, this one a value with no field at all.
+
+- **The `minLevel` entry below, under 1.2.9, now names the direction of its change.** The behaviour
+  changed in that release and its record stays there; what shipped here is the paragraph explaining
+  what upgrading does. A sink configured with an unrecognised level was silent and starts delivering
+  at the module level, which arrives as a step change in ingestion cost and reads as a noise
+  regression unless the note says which way it moves. Two consumers asked for this independently.
+
 ## [1.2.9] - 2026-08-16
 
 > **`1.2.8` was merged but never published.** The defect below was found in it after the merge and
@@ -33,6 +107,15 @@ heading here.
   `validateOptions` already held `options.level` to that same list; this is the check reaching
   the one place it had not.
 
+  **On upgrade this changes your log volume, upward, and it will not look like a fix.** A sink
+  that was configured with an unrecognised level and was therefore silent starts delivering at
+  the module level the moment you install this version. Read as a graph, that is a step change in
+  ingestion cost arriving with a patch; read correctly, it is entries that were always supposed
+  to be delivered and never were. If you see one, check that destination's `minLevel` before
+  treating it as a regression — the value has to be one of `'trace'`, `'debug'`, `'info'`,
+  `'warn'`, `'error'` or `'fatal'`. `'verbose'` and `'log'` are NestJS level names, not Pino
+  ones, and are the likely culprits for anyone arriving from `LoggerService`.
+
 - **A write returning a thenable that is not `instanceof Promise` no longer takes the synchronous
   path, where its rejection escaped and its entry could be discarded.** `instanceof` is realm-local:
   it answers `false` for a promise built in another realm — a worker, a `vm` context — and for any
@@ -1739,7 +1822,9 @@ published `dist/` is identical — no runtime behaviour changes for consumers.
 - Professional CI suite: `ci.yml`, `bench.yml`, `codeql.yml`, `scorecard.yml`,
   `release.yml`, Dependabot, and issue templates
 
-[Unreleased]: https://github.com/bymaxone/nest-logger/compare/v1.2.9...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-logger/compare/v1.3.1...HEAD
+[1.3.1]: https://github.com/bymaxone/nest-logger/compare/v1.3.0...v1.3.1
+[1.3.0]: https://github.com/bymaxone/nest-logger/compare/v1.2.9...v1.3.0
 [1.2.9]: https://github.com/bymaxone/nest-logger/compare/v1.2.7...v1.2.9
 
 <!-- 1.2.8 has no link: it was merged but never tagged, so there is no v1.2.8 to compare against. See its section above. -->

package/README.md

@@ -1070,6 +1070,28 @@ There is no name rule that reaches the second one, and scanning inside values fo
 
 `redactStrategy` governs **your** payload — the record you log, your child bindings, and the output of any serializer you supply. The built-in `err` serializer is the library's own output and is always name-walked, including under `'paths'`, because `fast-redact`'s four-wildcard ceiling cannot reach the depth a `cause` chain serializes to.
 
+#### A value interpolated into the message has no name to redact
+
+The case above is a secret inside a field's **value**. The sharper version is a value interpolated into the message itself, where there is no field at all:
+
+```ts
+// Both identifiers are now message text: there is no `userId` field and no
+// `familyId` field for any strategy to match, only a string that happens to
+// contain them.
+logger.warn(`reissueTokens: family revoked userId=${userId} familyId=${familyId}`)
+
+// Same facts, as fields. The logKey is yours — `RESERVED_LOG_KEYS` holds the
+// library's own keys, not your domain's — and follows MODULE_ACTION_RESULT:
+// module AUTH, action REUSE, result DETECTED.
+logger.warnStructured('AUTH_REUSE_DETECTED', 'token family revoked after reuse detection', userId, {
+  familyId
+})
+```
+
+Redaction matches names. An interpolated value does not have one — not an uncovered name, none — so there is nothing for any strategy to match, and no configuration you can add will change that. This is not a gap to be closed later: scanning message text for secret-shaped substrings would mean rewriting what you asked to be logged, which is the wrong trade in both directions.
+
+The rule that follows is short: **a value that matters is a field, not text.** A field can be redacted, queried, aggregated and correlated; the same value inside `msg` can only be read by a human who happens to be looking. That applies most to the values you would least like to interpolate — tokens, identifiers, addresses — and it is the one part of this contract the library cannot enforce for you, because the decision is made at the call site.
+
 ### A closed pipe does not kill the process
 
 `node app | head` closes the read end of stdout while the application is still writing. The stream reports that as `EPIPE` **asynchronously**, through its `'error'` event, after `write()` has already returned — so a `try/catch` around the write catches nothing, and because Node attaches no default handler to `process.stdout`, the emit becomes an uncaught exception and the process dies. Measured, not assumed: `0` listeners, no synchronous throw, `UNCAUGHT:EPIPE`, exit 42.

package/dist/server/index.cjs

@@ -1137,7 +1137,6 @@ function safeMinLevel(destination) {
     const read = destination.minLevel;
     resolved = isLogLevel(read) ? read : void 0;
   } catch {
-    resolved = void 0;
   }
   resolvedMinLevels.set(destination, resolved);
   return resolved;
@@ -1224,10 +1223,11 @@ function resolveToJson(value) {
   };
 }
 function cloneError(error) {
-  const clone = Object.create(
-    Object.getPrototypeOf(error),
-    Object.getOwnPropertyDescriptors(error)
-  );
+  const descriptors = Object.getOwnPropertyDescriptors(error);
+  for (const descriptor of Object.values(descriptors)) {
+    descriptor.configurable = true;
+  }
+  const clone = Object.create(Object.getPrototypeOf(error), descriptors);
   const { stack } = error;
   if (typeof stack === "string") {
     Reflect.defineProperty(clone, "stack", { value: stack, enumerable: false });
@@ -1235,11 +1235,8 @@ function cloneError(error) {
   return clone;
 }
 var BUFFER_TO_JSON = Buffer.prototype.toJSON;
-var WRITE_FAILED = new Error();
 function defineOwn(target, key, value) {
-  if (!Reflect.defineProperty(target, key, { value, enumerable: true })) {
-    throw WRITE_FAILED;
-  }
+  Reflect.defineProperty(target, key, { value, enumerable: true });
 }
 function walkArray(value, sensitive, censor, depth2, ancestors) {
   const length = value.length;

package/dist/server/index.d.cts

@@ -260,6 +260,21 @@ interface HttpOptions {
      * 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.
+     *
      * SECURITY: each pattern is `.test()`-ed against the (attacker-controllable)
      * request path on every request. Supply only anchored, linear-time regexes
      * (e.g. `/^\/health$/`); a pattern with catastrophic backtracking would turn a
@@ -639,9 +654,11 @@ type ReservedLogKey = (typeof RESERVED_LOG_KEYS)[keyof typeof RESERVED_LOG_KEYS]
  * costs ~26 % of the entry throughput, measured, and the walk is still ~36x
  * faster than the path expansion it replaced.
  *
- * Any internal failure — including a censor that cannot be written — degrades the
- * whole record to a marked, secret-free envelope rather than crashing the request
- * that produced it.
+ * Any internal failure — a throwing getter, a hostile proxy, a value the walk
+ * cannot READ — degrades the whole record to a marked, secret-free envelope rather
+ * than crashing the request that produced it. Writing the censor is not among those
+ * failures: every copy is built so the write cannot fail, which is why a frozen
+ * error keeps its fields instead of costing the record.
  *
  * @see {@link createNameRedactor}
  */

package/dist/server/index.d.ts

@@ -260,6 +260,21 @@ interface HttpOptions {
      * 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.
+     *
      * SECURITY: each pattern is `.test()`-ed against the (attacker-controllable)
      * request path on every request. Supply only anchored, linear-time regexes
      * (e.g. `/^\/health$/`); a pattern with catastrophic backtracking would turn a
@@ -639,9 +654,11 @@ type ReservedLogKey = (typeof RESERVED_LOG_KEYS)[keyof typeof RESERVED_LOG_KEYS]
  * costs ~26 % of the entry throughput, measured, and the walk is still ~36x
  * faster than the path expansion it replaced.
  *
- * Any internal failure — including a censor that cannot be written — degrades the
- * whole record to a marked, secret-free envelope rather than crashing the request
- * that produced it.
+ * Any internal failure — a throwing getter, a hostile proxy, a value the walk
+ * cannot READ — degrades the whole record to a marked, secret-free envelope rather
+ * than crashing the request that produced it. Writing the censor is not among those
+ * failures: every copy is built so the write cannot fail, which is why a frozen
+ * error keeps its fields instead of costing the record.
  *
  * @see {@link createNameRedactor}
  */

package/dist/server/index.mjs

@@ -1134,7 +1134,6 @@ function safeMinLevel(destination) {
     const read = destination.minLevel;
     resolved = isLogLevel(read) ? read : void 0;
   } catch {
-    resolved = void 0;
   }
   resolvedMinLevels.set(destination, resolved);
   return resolved;
@@ -1221,10 +1220,11 @@ function resolveToJson(value) {
   };
 }
 function cloneError(error) {
-  const clone = Object.create(
-    Object.getPrototypeOf(error),
-    Object.getOwnPropertyDescriptors(error)
-  );
+  const descriptors = Object.getOwnPropertyDescriptors(error);
+  for (const descriptor of Object.values(descriptors)) {
+    descriptor.configurable = true;
+  }
+  const clone = Object.create(Object.getPrototypeOf(error), descriptors);
   const { stack } = error;
   if (typeof stack === "string") {
     Reflect.defineProperty(clone, "stack", { value: stack, enumerable: false });
@@ -1232,11 +1232,8 @@ function cloneError(error) {
   return clone;
 }
 var BUFFER_TO_JSON = Buffer.prototype.toJSON;
-var WRITE_FAILED = new Error();
 function defineOwn(target, key, value) {
-  if (!Reflect.defineProperty(target, key, { value, enumerable: true })) {
-    throw WRITE_FAILED;
-  }
+  Reflect.defineProperty(target, key, { value, enumerable: true });
 }
 function walkArray(value, sensitive, censor, depth2, ancestors) {
   const length = value.length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-logger",
-  "version": "1.2.9",
+  "version": "1.3.1",
   "description": "Structured JSON logging for NestJS based on Pino 10, with optional OpenTelemetry correlation.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",