@bymax-one/nest-core 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -11,6 +11,41 @@ heading here.
 
 ## [Unreleased]
 
+## [1.0.1] - 2026-08-04
+
+**Behaviour change on the readiness endpoint.** A failing indicator's message no
+longer appears in the HTTP response by default; it goes to the logger instead.
+
+### Security
+
+- **The readiness response no longer publishes an indicator's failure message.**
+  `GET /health/ready` returned `details.error` carrying the rejecting indicator's
+  `Error#message`. That endpoint is typically unauthenticated and reachable by
+  whatever probes it — and an indicator rarely authors its own failure text: it
+  writes `await this.redis.ping()` and lets the driver's error propagate. Driver
+  errors carry hosts, ports and, for a connection string, credentials. An
+  indicator failing with `connection refused: postgres://user:PASSWORD@db:5432`
+  served that string to anyone who could reach the probe.
+
+  A failing check is now `{ name, status: 'down' }` and nothing more. The message
+  is written to Nest's `Logger` instead, so the diagnostic survives in a channel
+  that already has access control rather than being lost.
+
+  `health.exposeIndicatorErrors` (default `false`) puts it back in the response
+  for local debugging — the same shape, and the same warning, as
+  `envelope.exposeInternals`. The library made opposite choices about the same
+  risk in two places; they now agree.
+
+  `timedOutAfterMs` is unaffected: that number is one this library chose, not text
+  an indicator produced.
+
+### Changed
+
+- **The Health and Security Model sections describe the split**, and the
+  configuration table documents the new option. The previous text said an
+  indicator "cannot leak more than it already chose to put in a message", which
+  assigned a choice the indicator's author usually never makes.
+
 ## [1.0.0] - 2026-08-03
 
 First published release. Everything below ships in it.
@@ -73,5 +108,6 @@ have regressed from. They are kept because the reasoning is worth having.
   cleanly and silently. Corrected before the first publish, so no released version
   ever carried the permissive range. No runtime behaviour changed.
 
+[1.0.1]: https://github.com/bymaxone/nest-core/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/bymaxone/nest-core/releases/tag/v1.0.0
 [Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.0.0...HEAD

package/README.md

@@ -199,11 +199,12 @@ falls back to the documented default. Pass only what you want to change.
 
 ### `health`
 
-| Option               | Type      | Default    | Description                                            |
-| -------------------- | --------- | ---------- | ------------------------------------------------------ |
-| `enabled`            | `boolean` | `true`     | Registers the health controller.                       |
-| `path`               | `string`  | `'health'` | Route prefix: `GET /<path>/live`, `GET /<path>/ready`. |
-| `indicatorTimeoutMs` | `number`  | `5000`     | Per-indicator timeout before a check reports down.     |
+| Option                  | Type      | Default    | Description                                                                                                             |
+| ----------------------- | --------- | ---------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `enabled`               | `boolean` | `true`     | Registers the health controller.                                                                                        |
+| `path`                  | `string`  | `'health'` | Route prefix: `GET /<path>/live`, `GET /<path>/ready`.                                                                  |
+| `indicatorTimeoutMs`    | `number`  | `5000`     | Per-indicator timeout before a check reports down.                                                                      |
+| `exposeIndicatorErrors` | `boolean` | `false`    | Includes the failing indicator's message in the response under `details.error`. Never enable in production — see below. |
 
 On `forRoot`, `enabled` and `path` are applied at module-definition time: a
 disabled feature registers no controller, and a custom `path` mounts the routes.
@@ -391,6 +392,12 @@ Liveness always replies `200` with an empty checks array; readiness runs
 every registered indicator concurrently and replies `200` only when every
 indicator reports `up`, `503` otherwise, naming every check either way.
 
+A failing indicator is named but not quoted: the response says which check is
+down, and the reason goes to the logger. See
+[the security model](#-security-model) for why, and
+`health.exposeIndicatorErrors` if you want the message in the response while
+debugging locally.
+
 ```json
 { "status": "ok", "checks": [{ "name": "redis", "status": "up" }] }
 ```
@@ -558,12 +565,28 @@ original message and stack are captured for your logger, not for the response.
 `envelope.exposeInternals` puts them in the body and exists for local debugging — its own
 documentation says never to enable it in production, and it defaults to `false`.
 
-### Health output is bounded by construction
+### The readiness response names the failure, it does not describe it
+
+A failing indicator produces `{ name, status: 'down' }` and nothing else. The reason goes
+to the logger.
+
+That split is deliberate. Readiness is usually unauthenticated and reachable by whatever
+probes it, and an indicator rarely authors its own failure text — it writes
+`await this.redis.ping()` and lets the driver's error propagate. Driver errors carry hosts,
+ports, and in the case of a connection string, credentials. Putting that text in the
+response publishes it to everyone who can reach the endpoint; putting it in the log keeps
+it where access is already controlled, without losing the diagnostic.
+
+`health.exposeIndicatorErrors` puts the message back in the response for local debugging.
+It defaults to `false`, and its documentation says the same thing `envelope.exposeInternals`
+does: never enable it in production. The two options are the same decision, made the same
+way, about the same risk.
 
-An indicator that rejects is folded into a `down` entry from its top-level `Error#message`
-only — never the raw error, its stack, or a nested cause — and the message is truncated. An
-indicator cannot leak more than it already chose to put in a message, and a slow one is
-converted to `down` by the aggregator rather than hanging the probe.
+What reaches the log is bounded the same way it always was: the top-level `Error#message`
+only — never the raw error, its stack, or a nested cause — truncated at 300 characters.
+A slow indicator is converted to `down` by the aggregator rather than hanging the probe,
+and its `timedOutAfterMs` stays in the response either way, because that number is one this
+library chose rather than text an indicator produced.
 
 ### Cursors are opaque, not secret
 
@@ -580,16 +603,16 @@ guard you would apply to any internal endpoint, or keep it off the public listen
 
 ## 🛡️ Security Table
 
-| Layer              | Implementation                                                                                                             |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
-| Error responses    | One shape for everything; unknown errors become a generic 500                                                              |
-| Internals          | Message and stack captured for logging, in the body only under `exposeInternals` (default `false`)                         |
-| Health output      | Top-level `Error#message` only, truncated; no raw error, stack or cause                                                    |
-| Slow indicators    | Converted to `down` by the aggregator, so a probe cannot hang on one                                                       |
-| Correlation        | Resolved through `BYMAX_CORRELATION_PROVIDER` — the app decides where the id comes from                                    |
-| Pagination cursors | Opaque, not authenticated; treated as client-supplied input on the way back in                                             |
-| Metrics            | Opt-in; `prom-client` never imported while it is off                                                                       |
-| Supply chain       | `dependencies: {}`; third-party Actions pinned by commit SHA (org-internal reusables by tag); CodeQL and OpenSSF Scorecard |
+| Layer              | Implementation                                                                                                                                                                   |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Error responses    | One shape for everything; unknown errors become a generic 500                                                                                                                    |
+| Internals          | Message and stack captured for logging, in the body only under `exposeInternals` (default `false`)                                                                               |
+| Health output      | The response names which indicator is down and nothing more; the reason goes to the logger. `exposeIndicatorErrors` (default `false`) puts it back in the response for debugging |
+| Slow indicators    | Converted to `down` by the aggregator, so a probe cannot hang on one                                                                                                             |
+| Correlation        | Resolved through `BYMAX_CORRELATION_PROVIDER` — the app decides where the id comes from                                                                                          |
+| Pagination cursors | Opaque, not authenticated; treated as client-supplied input on the way back in                                                                                                   |
+| Metrics            | Opt-in; `prom-client` never imported while it is off                                                                                                                             |
+| Supply chain       | `dependencies: {}`; third-party Actions pinned by commit SHA (org-internal reusables by tag); CodeQL and OpenSSF Scorecard                                                       |
 
 > [!IMPORTANT]
 > **`exposeInternals` is a debugging switch, not a verbosity setting.** With it on,

package/dist/index.cjs

@@ -44,6 +44,7 @@ function resolveHealth(raw) {
   return {
     enabled: raw?.enabled ?? true,
     path: raw?.path ?? DEFAULT_HEALTH_PATH,
+    exposeIndicatorErrors: raw?.exposeIndicatorErrors ?? false,
     indicatorTimeoutMs: raw?.indicatorTimeoutMs ?? DEFAULT_INDICATOR_TIMEOUT_MS
   };
 }
@@ -529,18 +530,18 @@ function summarizeRejection(reason) {
   }
   return `${message.slice(0, MAX_ERROR_MESSAGE_LENGTH - TRUNCATION_ELLIPSIS.length)}${TRUNCATION_ELLIPSIS}`;
 }
-async function runIndicator(indicator, timeoutMs) {
+async function runIndicator(indicator, timeoutMs, exposeErrors, logger) {
   let timer;
   const timedOut = new Promise((resolve) => {
     timer = setTimeout(() => {
       resolve({ name: indicator.name, status: "down", details: { timedOutAfterMs: timeoutMs } });
     }, timeoutMs);
   });
-  const checked = Promise.resolve().then(() => indicator.check()).then((result) => ({ ...result, name: indicator.name })).catch((reason) => ({
-    name: indicator.name,
-    status: "down",
-    details: { error: summarizeRejection(reason) }
-  }));
+  const checked = Promise.resolve().then(() => indicator.check()).then((result) => ({ ...result, name: indicator.name })).catch((reason) => {
+    const message = summarizeRejection(reason);
+    logger.warn(`Health indicator "${indicator.name}" reported down: ${message}`);
+    return exposeErrors ? { name: indicator.name, status: "down", details: { error: message } } : { name: indicator.name, status: "down" };
+  });
   try {
     return await Promise.race([checked, timedOut]);
   } finally {
@@ -559,6 +560,12 @@ var HealthService = class {
   constructor(indicators = [], options) {
     this.indicators = indicators;
     this.options = options;
+    /**
+     * Nest's own logger, scoped to this class. The failure reason of a `down`
+     * indicator is written here rather than into the HTTP response, so the
+     * diagnostic survives without being served to whoever can reach the probe.
+     */
+    this.logger = new common.Logger(HealthService.name);
   }
   /**
    * Liveness check: the process is up and able to respond. Runs no
@@ -578,8 +585,11 @@ var HealthService = class {
    */
   async checkReadiness() {
     const timeoutMs = this.options.health.indicatorTimeoutMs;
+    const exposeErrors = this.options.health.exposeIndicatorErrors;
     const checks = await Promise.all(
-      this.indicators.map((indicator) => runIndicator(indicator, timeoutMs))
+      this.indicators.map(
+        (indicator) => runIndicator(indicator, timeoutMs, exposeErrors, this.logger)
+      )
     );
     const status = checks.every((check) => check.status === "up") ? "ok" : "error";
     return { status, checks };

package/dist/index.d.cts

@@ -35,6 +35,18 @@ interface HealthOptions {
     path?: string;
     /** Per-indicator timeout before a check is reported as down. Default: `5000`. */
     indicatorTimeoutMs?: number;
+    /**
+     * Include the failing indicator's message in the readiness response under
+     * `details.error`. Never enable in production. Default: `false`.
+     *
+     * Readiness is typically unauthenticated and reachable by whatever probes it,
+     * and an indicator usually does not author its own failure message — it lets a
+     * driver's error propagate, and driver errors carry hosts, ports and sometimes
+     * credentials. With this off, the response names which indicator is down and
+     * nothing else; the message goes to the logger, where access is already
+     * controlled.
+     */
+    exposeIndicatorErrors?: boolean;
 }
 /** Prometheus metrics endpoint configuration. */
 interface MetricsOptions {
@@ -76,6 +88,7 @@ interface ResolvedHealthOptions {
     enabled: boolean;
     path: string;
     indicatorTimeoutMs: number;
+    exposeIndicatorErrors: boolean;
 }
 /** Fully-resolved metrics options. */
 interface ResolvedMetricsOptions {

package/dist/index.d.ts

@@ -35,6 +35,18 @@ interface HealthOptions {
     path?: string;
     /** Per-indicator timeout before a check is reported as down. Default: `5000`. */
     indicatorTimeoutMs?: number;
+    /**
+     * Include the failing indicator's message in the readiness response under
+     * `details.error`. Never enable in production. Default: `false`.
+     *
+     * Readiness is typically unauthenticated and reachable by whatever probes it,
+     * and an indicator usually does not author its own failure message — it lets a
+     * driver's error propagate, and driver errors carry hosts, ports and sometimes
+     * credentials. With this off, the response names which indicator is down and
+     * nothing else; the message goes to the logger, where access is already
+     * controlled.
+     */
+    exposeIndicatorErrors?: boolean;
 }
 /** Prometheus metrics endpoint configuration. */
 interface MetricsOptions {
@@ -76,6 +88,7 @@ interface ResolvedHealthOptions {
     enabled: boolean;
     path: string;
     indicatorTimeoutMs: number;
+    exposeIndicatorErrors: boolean;
 }
 /** Fully-resolved metrics options. */
 interface ResolvedMetricsOptions {

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { Catch, Inject, Optional, Injectable, ConfigurableModuleBuilder, Module, HttpException, Get, Res, Controller, HttpStatus } from '@nestjs/common';
+import { Catch, Inject, Optional, Injectable, ConfigurableModuleBuilder, Module, HttpException, Logger, Get, Res, Controller, HttpStatus } from '@nestjs/common';
 import { HttpAdapterHost, BaseExceptionFilter, APP_FILTER, APP_INTERCEPTOR } from '@nestjs/core';
 import { tap, catchError, throwError } from 'rxjs';
 
@@ -42,6 +42,7 @@ function resolveHealth(raw) {
   return {
     enabled: raw?.enabled ?? true,
     path: raw?.path ?? DEFAULT_HEALTH_PATH,
+    exposeIndicatorErrors: raw?.exposeIndicatorErrors ?? false,
     indicatorTimeoutMs: raw?.indicatorTimeoutMs ?? DEFAULT_INDICATOR_TIMEOUT_MS
   };
 }
@@ -527,18 +528,18 @@ function summarizeRejection(reason) {
   }
   return `${message.slice(0, MAX_ERROR_MESSAGE_LENGTH - TRUNCATION_ELLIPSIS.length)}${TRUNCATION_ELLIPSIS}`;
 }
-async function runIndicator(indicator, timeoutMs) {
+async function runIndicator(indicator, timeoutMs, exposeErrors, logger) {
   let timer;
   const timedOut = new Promise((resolve) => {
     timer = setTimeout(() => {
       resolve({ name: indicator.name, status: "down", details: { timedOutAfterMs: timeoutMs } });
     }, timeoutMs);
   });
-  const checked = Promise.resolve().then(() => indicator.check()).then((result) => ({ ...result, name: indicator.name })).catch((reason) => ({
-    name: indicator.name,
-    status: "down",
-    details: { error: summarizeRejection(reason) }
-  }));
+  const checked = Promise.resolve().then(() => indicator.check()).then((result) => ({ ...result, name: indicator.name })).catch((reason) => {
+    const message = summarizeRejection(reason);
+    logger.warn(`Health indicator "${indicator.name}" reported down: ${message}`);
+    return exposeErrors ? { name: indicator.name, status: "down", details: { error: message } } : { name: indicator.name, status: "down" };
+  });
   try {
     return await Promise.race([checked, timedOut]);
   } finally {
@@ -557,6 +558,12 @@ var HealthService = class {
   constructor(indicators = [], options) {
     this.indicators = indicators;
     this.options = options;
+    /**
+     * Nest's own logger, scoped to this class. The failure reason of a `down`
+     * indicator is written here rather than into the HTTP response, so the
+     * diagnostic survives without being served to whoever can reach the probe.
+     */
+    this.logger = new Logger(HealthService.name);
   }
   /**
    * Liveness check: the process is up and able to respond. Runs no
@@ -576,8 +583,11 @@ var HealthService = class {
    */
   async checkReadiness() {
     const timeoutMs = this.options.health.indicatorTimeoutMs;
+    const exposeErrors = this.options.health.exposeIndicatorErrors;
     const checks = await Promise.all(
-      this.indicators.map((indicator) => runIndicator(indicator, timeoutMs))
+      this.indicators.map(
+        (indicator) => runIndicator(indicator, timeoutMs, exposeErrors, this.logger)
+      )
     );
     const status = checks.every((check) => check.status === "up") ? "ok" : "error";
     return { status, checks };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-core",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Zero-dependency NestJS 11 application foundation kit: error-envelope exception filter, request-timing interceptor, pagination helpers, health endpoints, and an optional Prometheus metrics endpoint.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
@@ -55,6 +55,29 @@
     },
     "./package.json": "./package.json"
   },
+  "scripts": {
+    "build": "pnpm clean && tsup",
+    "check:exports": "attw --pack . --profile strict",
+    "check:published": "node scripts/check-published-surface.mjs",
+    "check:runtime": "node scripts/check-consumer-runtime.mjs",
+    "clean": "node -e \"const fs=require('node:fs');for(const d of ['dist','coverage'])fs.rmSync(d,{recursive:true,force:true})\"",
+    "dogfood": "node scripts/dogfood-smoke-test.mjs",
+    "lint": "eslint --no-error-on-unmatched-pattern src scripts test",
+    "lint:fix": "eslint --no-error-on-unmatched-pattern src scripts test --fix",
+    "mutation": "stryker run",
+    "mutation:dry-run": "stryker run --dryRunOnly",
+    "mutation:incremental": "stryker run --incremental",
+    "prepare": "husky",
+    "prepublishOnly": "pnpm clean && pnpm typecheck && pnpm lint && pnpm test:cov:all && pnpm build && pnpm size && pnpm check:published",
+    "release": "npm publish --provenance --access public",
+    "size": "node scripts/check-size.mjs",
+    "test": "jest",
+    "test:cov": "jest --coverage",
+    "test:cov:all": "jest --config jest.coverage.config.ts --coverage",
+    "test:e2e": "jest --config jest.e2e.config.ts",
+    "test:watch": "jest --watch",
+    "typecheck": "tsc --noEmit"
+  },
   "lint-staged": {
     "*.{ts,tsx,js,mjs,cjs}": [
       "eslint --fix",
@@ -126,6 +149,7 @@
     "metrics",
     "typescript"
   ],
+  "packageManager": "pnpm@10.8.1",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -134,6 +158,16 @@
     "provenance": true,
     "registry": "https://registry.npmjs.org/"
   },
+  "pnpm": {
+    "overrides": {
+      "brace-expansion@1": "^1.1.18",
+      "brace-expansion@2": "^2.1.4",
+      "brace-expansion@5": "^5.0.9",
+      "esbuild": "^0.28.1",
+      "fast-uri": "^3.1.5",
+      "qs": "^6.15.2"
+    }
+  },
   "module": "./dist/index.mjs",
   "typesVersions": {
     "*": {
@@ -144,26 +178,5 @@
         "./dist/health/index.d.cts"
       ]
     }
-  },
-  "scripts": {
-    "build": "pnpm clean && tsup",
-    "check:exports": "attw --pack . --profile strict",
-    "check:published": "node scripts/check-published-surface.mjs",
-    "check:runtime": "node scripts/check-consumer-runtime.mjs",
-    "clean": "node -e \"const fs=require('node:fs');for(const d of ['dist','coverage'])fs.rmSync(d,{recursive:true,force:true})\"",
-    "dogfood": "node scripts/dogfood-smoke-test.mjs",
-    "lint": "eslint --no-error-on-unmatched-pattern src scripts test",
-    "lint:fix": "eslint --no-error-on-unmatched-pattern src scripts test --fix",
-    "mutation": "stryker run",
-    "mutation:dry-run": "stryker run --dryRunOnly",
-    "mutation:incremental": "stryker run --incremental",
-    "release": "npm publish --provenance --access public",
-    "size": "node scripts/check-size.mjs",
-    "test": "jest",
-    "test:cov": "jest --coverage",
-    "test:cov:all": "jest --config jest.coverage.config.ts --coverage",
-    "test:e2e": "jest --config jest.e2e.config.ts",
-    "test:watch": "jest --watch",
-    "typecheck": "tsc --noEmit"
   }
-}
+}