@bymax-one/nest-core 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -11,6 +11,46 @@ heading here.
 
 ## [Unreleased]
 
+## [1.2.2] - 2026-08-10
+
+Remediation of a local audit's metrics-auth and pagination-bound findings (merged in #62). No
+API changed.
+
+### Fixed
+
+- **Offset-safe page cap.** `normalizePageQuery` resolves the limit first and caps `page` to
+  `floor(MAX_SAFE_INTEGER / limit) + 1`, so a hostile `page` can no longer drive
+  `(page - 1) * limit` past the safe-integer range and lose precision before a repository computes
+  its offset.
+- **The `/metrics` bearer scheme is matched case-insensitively.** An HTTP auth scheme is
+  case-insensitive (RFC 7235) and may be separated from the credential by more than one space or a
+  tab; the check now accepts `bearer`/`BEARER`/mixed case and that whitespace, and anchors the
+  scheme to the start of the header to close a mid-string smuggling path.
+- **A misconfigured scrape token fails closed.** A `metrics.authToken` configured empty or
+  whitespace-only is now rejected at boot instead of being silently treated as unset — which left
+  `/metrics` open. A real token is kept verbatim.
+
+### Documentation
+
+- `metrics.authToken` is documented in the README and the technical specification, including a
+  protected-scrape example.
+
+## [1.2.1] - 2026-08-08
+
+A patch: the envelope fix below changes a response status for a class of client errors, without
+touching the module's API or any option.
+
+### Fixed
+
+- **An error carrying a 4xx status it marked exposable keeps that status, instead of collapsing to 500.** Express's body pipeline throws `http-errors` instances before any handler runs — a payload
+  past the limit is `PayloadTooLargeError` (413), malformed JSON is a `SyntaxError` (400), an
+  unsupported media type is 415. None is a Nest `HttpException`, so each reached the generic
+  500 collapse: a client that sent too large a body, or malformed JSON, was told the server failed,
+  and a monitor counted a 5xx for a request that never entered the application. The filter now reads
+  the `expose: true` flag and the numeric status these carry and honours it — restricted to the 4xx
+  range, because a self-reported 5xx is still a server failure whose account of itself must not
+  surface, so it stays a generic 500.
+
 ## [1.2.0] - 2026-08-08
 
 Both entries change what a caller receives, which is why this is a minor rather than a patch: an
@@ -301,5 +341,7 @@ have regressed from. They are kept because the reasoning is worth having.
 [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
 [1.1.1]: https://github.com/bymaxone/nest-core/compare/v1.1.0...v1.1.1
+[1.2.2]: https://github.com/bymaxone/nest-core/compare/v1.2.1...v1.2.2
+[1.2.1]: https://github.com/bymaxone/nest-core/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/bymaxone/nest-core/compare/v1.1.1...v1.2.0
-[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.2.0...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.2.2...HEAD

package/README.md

@@ -235,18 +235,34 @@ configuration fails fast at the route rather than at boot.
 
 ### `metrics`
 
-| Option                  | Type                     | Default     | Description                                                           |
-| ----------------------- | ------------------------ | ----------- | --------------------------------------------------------------------- |
-| `enabled`               | `boolean`                | `false`     | Registers the metrics controller and the registry.                    |
-| `path`                  | `string`                 | `'metrics'` | Route serving the Prometheus scrape.                                  |
-| `defaultLabels`         | `Record<string, string>` | `{}`        | Static labels attached to every metric.                               |
-| `collectDefaultMetrics` | `boolean`                | `true`      | Collects `prom-client`'s process CPU, memory, and event-loop metrics. |
+| Option                  | Type                     | Default     | Description                                                                                      |
+| ----------------------- | ------------------------ | ----------- | ------------------------------------------------------------------------------------------------ |
+| `enabled`               | `boolean`                | `false`     | Registers the metrics controller and the registry.                                               |
+| `path`                  | `string`                 | `'metrics'` | Route serving the Prometheus scrape.                                                             |
+| `defaultLabels`         | `Record<string, string>` | `{}`        | Static labels attached to every metric.                                                          |
+| `collectDefaultMetrics` | `boolean`                | `true`      | Collects `prom-client`'s process CPU, memory, and event-loop metrics.                            |
+| `authToken`             | `string`                 | _(unset)_   | Bearer required to scrape. Unset leaves the endpoint open; empty/whitespace is rejected at boot. |
 
 As with `health`, `enabled` and `path` register conditionally on `forRoot`. On
 `forRootAsync` the metrics controller is always registered at the default path
 and enforces `enabled` and the default path with a request-time guard, so a
 disabled or custom-path async configuration fails fast at the route.
 
+By default the scrape endpoint is **open** — the exposition publishes the route
+inventory and, with `collectDefaultMetrics`, process internals to any caller. Set
+`authToken` to require `Authorization: Bearer <token>` (the scheme is matched
+case-insensitively; the token is compared in constant time), or protect the route at
+your edge (network policy, ingress auth). A token configured empty or whitespace-only
+is rejected at boot rather than silently ignored, so a mistyped secret fails loud
+instead of leaving the endpoint open:
+
+```ts
+BymaxCoreModule.forRoot({
+  metrics: { enabled: true, authToken: process.env.METRICS_TOKEN }
+})
+// Scrape: curl -H "Authorization: Bearer $METRICS_TOKEN" http://host/metrics
+```
+
 ### `telemetry`
 
 | Option          | Type      | Default | Description                                                                     |

package/dist/index.cjs

@@ -3,6 +3,7 @@
 var common = require('@nestjs/common');
 var core = require('@nestjs/core');
 var rxjs = require('rxjs');
+var crypto = require('crypto');
 
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -62,12 +63,25 @@ function resolveHealth(raw) {
     autoDiscover: raw?.autoDiscover ?? false
   };
 }
+function resolveMetricsAuthToken(raw) {
+  if (raw === void 0) {
+    return void 0;
+  }
+  if (raw.trim() === "") {
+    throw new Error(
+      '[BymaxCoreModule] "metrics.authToken" was configured empty or whitespace-only. Leave it unset to expose an open /metrics endpoint (protected at the edge), or set a non-empty bearer token to require credentialed scrapes.'
+    );
+  }
+  return raw;
+}
 function resolveMetrics(raw) {
+  const authToken = resolveMetricsAuthToken(raw?.authToken);
   return {
     enabled: raw?.enabled ?? false,
     path: raw?.path ?? DEFAULT_METRICS_PATH,
     collectDefaultMetrics: raw?.collectDefaultMetrics ?? true,
-    defaultLabels: { ...raw?.defaultLabels ?? {} }
+    defaultLabels: { ...raw?.defaultLabels ?? {} },
+    ...authToken !== void 0 ? { authToken } : {}
   };
 }
 function cloneServers(raw) {
@@ -310,6 +324,23 @@ function extractExplicitDetails(carrier) {
   const details = carrier.details;
   return typeof details === "object" && details !== null ? details : void 0;
 }
+var CLIENT_ERROR_MIN2 = 400;
+var CLIENT_ERROR_MAX2 = 500;
+function resolveExposedClientError(exception) {
+  if (typeof exception !== "object" || exception === null) {
+    return void 0;
+  }
+  const candidate = exception;
+  if (candidate.expose !== true) {
+    return void 0;
+  }
+  const status = Number.isInteger(candidate.status) ? candidate.status : candidate.statusCode;
+  if (typeof status !== "number" || !Number.isInteger(status) || status < CLIENT_ERROR_MIN2 || status >= CLIENT_ERROR_MAX2) {
+    return void 0;
+  }
+  const message = exception instanceof Error ? exception.message : "";
+  return { status, message: message === "" ? INTERNAL_ERROR_MESSAGE : message };
+}
 function isValidationResponse(response) {
   return typeof response === "object" && response !== null && "message" in response && Array.isArray(response.message);
 }
@@ -424,6 +455,15 @@ exports.BymaxExceptionFilter = class BymaxExceptionFilter {
     if (exception instanceof common.HttpException) {
       return this.mapHttpException(exception, context);
     }
+    const exposed = resolveExposedClientError(exception);
+    if (exposed !== void 0) {
+      return this.toEnvelope(
+        exposed.status,
+        codeForStatus(exposed.status),
+        exposed.message,
+        context
+      );
+    }
     try {
       this.onUnexpectedError(exception, context);
     } catch {
@@ -1050,6 +1090,18 @@ function assertControllerMatchesOptions2(options, registeredPath) {
     );
   }
 }
+function bearerMatches(authorization, expected) {
+  if (typeof authorization !== "string") {
+    return false;
+  }
+  const presented = authorization.replace(/^bearer[ \t]+/i, "");
+  if (presented === authorization) {
+    return false;
+  }
+  const presentedDigest = crypto.createHash("sha256").update(presented).digest();
+  const expectedDigest = crypto.createHash("sha256").update(expected).digest();
+  return crypto.timingSafeEqual(presentedDigest, expectedDigest);
+}
 function createMetricsController(registeredPath) {
   let MetricsController = class {
     /**
@@ -1062,8 +1114,12 @@ function createMetricsController(registeredPath) {
       this.options = options;
       this.adapterHost = adapterHost;
     }
-    async scrape(response) {
+    async scrape(response, request) {
       assertControllerMatchesOptions2(this.options, registeredPath);
+      const { authToken } = this.options.metrics;
+      if (authToken !== void 0 && !bearerMatches(request.headers?.["authorization"], authToken)) {
+        throw new common.UnauthorizedException();
+      }
       const body = await this.registry.metrics();
       this.adapterHost.httpAdapter.setHeader(response, "Content-Type", this.registry.contentType);
       this.adapterHost.httpAdapter.reply(response, body, common.HttpStatus.OK);
@@ -1071,7 +1127,8 @@ function createMetricsController(registeredPath) {
   };
   __decorateClass([
     common.Get(),
-    __decorateParam(0, common.Res())
+    __decorateParam(0, common.Res()),
+    __decorateParam(1, common.Req())
   ], MetricsController.prototype, "scrape", 1);
   MetricsController = __decorateClass([
     common.Controller(registeredPath),

package/dist/index.d.cts

@@ -137,6 +137,18 @@ interface MetricsOptions {
     defaultLabels?: Record<string, string>;
     /** Collect `prom-client` default process metrics. Default: `true`. */
     collectDefaultMetrics?: boolean;
+    /**
+     * A bearer token the scrape endpoint requires. When set, a request must carry
+     * `Authorization: Bearer <token>` matching this value (the scheme is matched
+     * case-insensitively; the token is compared in constant time) or it is refused
+     * with `401`. When unset (the default) the endpoint is open, so a deployment that
+     * exposes `/metrics` beyond a trusted network must either set this or protect the
+     * route at its edge — the exposition otherwise publishes the route inventory and
+     * `collectDefaultMetrics` process internals to any caller. Configuring this empty
+     * or whitespace-only is rejected at boot rather than treated as unset, so a
+     * mistyped secret fails loud instead of silently leaving the endpoint open.
+     */
+    authToken?: string;
 }
 /**
  * Consumer-facing options for `BymaxCoreModule.forRoot` / `forRootAsync`. Every
@@ -179,12 +191,13 @@ interface ResolvedTelemetryOptions {
     enabled: boolean;
     exposeTraceId: boolean;
 }
-/** Fully-resolved metrics options. */
+/** Fully-resolved metrics options. `authToken` stays absent when unset. */
 interface ResolvedMetricsOptions {
     enabled: boolean;
     path: string;
     collectDefaultMetrics: boolean;
     defaultLabels: Record<string, string>;
+    authToken?: string;
 }
 /** Fully-resolved OpenAPI options. */
 interface ResolvedOpenApiOptions {

package/dist/index.d.ts

@@ -137,6 +137,18 @@ interface MetricsOptions {
     defaultLabels?: Record<string, string>;
     /** Collect `prom-client` default process metrics. Default: `true`. */
     collectDefaultMetrics?: boolean;
+    /**
+     * A bearer token the scrape endpoint requires. When set, a request must carry
+     * `Authorization: Bearer <token>` matching this value (the scheme is matched
+     * case-insensitively; the token is compared in constant time) or it is refused
+     * with `401`. When unset (the default) the endpoint is open, so a deployment that
+     * exposes `/metrics` beyond a trusted network must either set this or protect the
+     * route at its edge — the exposition otherwise publishes the route inventory and
+     * `collectDefaultMetrics` process internals to any caller. Configuring this empty
+     * or whitespace-only is rejected at boot rather than treated as unset, so a
+     * mistyped secret fails loud instead of silently leaving the endpoint open.
+     */
+    authToken?: string;
 }
 /**
  * Consumer-facing options for `BymaxCoreModule.forRoot` / `forRootAsync`. Every
@@ -179,12 +191,13 @@ interface ResolvedTelemetryOptions {
     enabled: boolean;
     exposeTraceId: boolean;
 }
-/** Fully-resolved metrics options. */
+/** Fully-resolved metrics options. `authToken` stays absent when unset. */
 interface ResolvedMetricsOptions {
     enabled: boolean;
     path: string;
     collectDefaultMetrics: boolean;
     defaultLabels: Record<string, string>;
+    authToken?: string;
 }
 /** Fully-resolved OpenAPI options. */
 interface ResolvedOpenApiOptions {

package/dist/index.mjs

@@ -1,6 +1,7 @@
-import { Catch, Inject, Optional, Injectable, ConfigurableModuleBuilder, Module, HttpException, Logger, Get, Res, Controller, HttpStatus, NotFoundException } from '@nestjs/common';
+import { Catch, Inject, Optional, Injectable, ConfigurableModuleBuilder, Module, HttpException, Logger, Get, Res, Controller, Req, HttpStatus, UnauthorizedException, NotFoundException } from '@nestjs/common';
 import { HttpAdapterHost, DiscoveryService, Reflector, BaseExceptionFilter, APP_FILTER, APP_INTERCEPTOR, DiscoveryModule } from '@nestjs/core';
 import { tap, catchError, throwError } from 'rxjs';
+import { createHash, timingSafeEqual } from 'crypto';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -60,12 +61,25 @@ function resolveHealth(raw) {
     autoDiscover: raw?.autoDiscover ?? false
   };
 }
+function resolveMetricsAuthToken(raw) {
+  if (raw === void 0) {
+    return void 0;
+  }
+  if (raw.trim() === "") {
+    throw new Error(
+      '[BymaxCoreModule] "metrics.authToken" was configured empty or whitespace-only. Leave it unset to expose an open /metrics endpoint (protected at the edge), or set a non-empty bearer token to require credentialed scrapes.'
+    );
+  }
+  return raw;
+}
 function resolveMetrics(raw) {
+  const authToken = resolveMetricsAuthToken(raw?.authToken);
   return {
     enabled: raw?.enabled ?? false,
     path: raw?.path ?? DEFAULT_METRICS_PATH,
     collectDefaultMetrics: raw?.collectDefaultMetrics ?? true,
-    defaultLabels: { ...raw?.defaultLabels ?? {} }
+    defaultLabels: { ...raw?.defaultLabels ?? {} },
+    ...authToken !== void 0 ? { authToken } : {}
   };
 }
 function cloneServers(raw) {
@@ -308,6 +322,23 @@ function extractExplicitDetails(carrier) {
   const details = carrier.details;
   return typeof details === "object" && details !== null ? details : void 0;
 }
+var CLIENT_ERROR_MIN2 = 400;
+var CLIENT_ERROR_MAX2 = 500;
+function resolveExposedClientError(exception) {
+  if (typeof exception !== "object" || exception === null) {
+    return void 0;
+  }
+  const candidate = exception;
+  if (candidate.expose !== true) {
+    return void 0;
+  }
+  const status = Number.isInteger(candidate.status) ? candidate.status : candidate.statusCode;
+  if (typeof status !== "number" || !Number.isInteger(status) || status < CLIENT_ERROR_MIN2 || status >= CLIENT_ERROR_MAX2) {
+    return void 0;
+  }
+  const message = exception instanceof Error ? exception.message : "";
+  return { status, message: message === "" ? INTERNAL_ERROR_MESSAGE : message };
+}
 function isValidationResponse(response) {
   return typeof response === "object" && response !== null && "message" in response && Array.isArray(response.message);
 }
@@ -422,6 +453,15 @@ var BymaxExceptionFilter = class {
     if (exception instanceof HttpException) {
       return this.mapHttpException(exception, context);
     }
+    const exposed = resolveExposedClientError(exception);
+    if (exposed !== void 0) {
+      return this.toEnvelope(
+        exposed.status,
+        codeForStatus(exposed.status),
+        exposed.message,
+        context
+      );
+    }
     try {
       this.onUnexpectedError(exception, context);
     } catch {
@@ -1048,6 +1088,18 @@ function assertControllerMatchesOptions2(options, registeredPath) {
     );
   }
 }
+function bearerMatches(authorization, expected) {
+  if (typeof authorization !== "string") {
+    return false;
+  }
+  const presented = authorization.replace(/^bearer[ \t]+/i, "");
+  if (presented === authorization) {
+    return false;
+  }
+  const presentedDigest = createHash("sha256").update(presented).digest();
+  const expectedDigest = createHash("sha256").update(expected).digest();
+  return timingSafeEqual(presentedDigest, expectedDigest);
+}
 function createMetricsController(registeredPath) {
   let MetricsController = class {
     /**
@@ -1060,8 +1112,12 @@ function createMetricsController(registeredPath) {
       this.options = options;
       this.adapterHost = adapterHost;
     }
-    async scrape(response) {
+    async scrape(response, request) {
       assertControllerMatchesOptions2(this.options, registeredPath);
+      const { authToken } = this.options.metrics;
+      if (authToken !== void 0 && !bearerMatches(request.headers?.["authorization"], authToken)) {
+        throw new UnauthorizedException();
+      }
       const body = await this.registry.metrics();
       this.adapterHost.httpAdapter.setHeader(response, "Content-Type", this.registry.contentType);
       this.adapterHost.httpAdapter.reply(response, body, HttpStatus.OK);
@@ -1069,7 +1125,8 @@ function createMetricsController(registeredPath) {
   };
   __decorateClass([
     Get(),
-    __decorateParam(0, Res())
+    __decorateParam(0, Res()),
+    __decorateParam(1, Req())
   ], MetricsController.prototype, "scrape", 1);
   MetricsController = __decorateClass([
     Controller(registeredPath),

package/dist/pagination/index.cjs

@@ -14,7 +14,10 @@ function coercePositiveInt(value, fallback) {
   if (!Number.isFinite(coerced) || coerced < MINIMUM) {
     return fallback;
   }
-  return Math.floor(coerced);
+  return Math.min(Math.floor(coerced), Number.MAX_SAFE_INTEGER);
+}
+function clampPageToLimit(page, limit) {
+  return Math.min(page, Math.floor(Number.MAX_SAFE_INTEGER / limit) + 1);
 }
 function clampLimit(rawLimit, options) {
   const defaultLimit = coercePositiveInt(options?.defaultLimit, DEFAULT_LIMIT);
@@ -24,9 +27,10 @@ function clampLimit(rawLimit, options) {
 
 // src/pagination/offset.ts
 function normalizePageQuery(raw, options) {
+  const limit = clampLimit(raw.limit, options);
   return {
-    page: coercePositiveInt(raw.page, MINIMUM),
-    limit: clampLimit(raw.limit, options)
+    page: clampPageToLimit(coercePositiveInt(raw.page, MINIMUM), limit),
+    limit
   };
 }
 function buildPageResult(items, totalItems, query) {

package/dist/pagination/index.d.cts

@@ -44,8 +44,11 @@ interface PageResult<T> {
  * Clamp raw request input into a safe {@link PageQuery}.
  *
  * `page` floors to `1`; `limit` floors to `1` and caps at `maxLimit`. Absent,
- * non-numeric, negative, or zero fields fall back to defaults. Options are
- * per-call and never retained between calls.
+ * non-numeric, negative, or zero fields fall back to defaults. The limit is resolved
+ * first so `page` can be capped relative to it: a page is bounded not only to a safe
+ * integer but to one whose offset `(page - 1) * limit` also stays a safe integer, so a
+ * hostile `page` cannot lose precision before the repository computes its offset.
+ * Options are per-call and never retained between calls.
  *
  * @param raw - The untrusted page and limit values from the request.
  * @param options - Per-call `defaultLimit` (default `20`) and `maxLimit`

package/dist/pagination/index.d.ts

@@ -44,8 +44,11 @@ interface PageResult<T> {
  * Clamp raw request input into a safe {@link PageQuery}.
  *
  * `page` floors to `1`; `limit` floors to `1` and caps at `maxLimit`. Absent,
- * non-numeric, negative, or zero fields fall back to defaults. Options are
- * per-call and never retained between calls.
+ * non-numeric, negative, or zero fields fall back to defaults. The limit is resolved
+ * first so `page` can be capped relative to it: a page is bounded not only to a safe
+ * integer but to one whose offset `(page - 1) * limit` also stays a safe integer, so a
+ * hostile `page` cannot lose precision before the repository computes its offset.
+ * Options are per-call and never retained between calls.
  *
  * @param raw - The untrusted page and limit values from the request.
  * @param options - Per-call `defaultLimit` (default `20`) and `maxLimit`

package/dist/pagination/index.mjs

@@ -12,7 +12,10 @@ function coercePositiveInt(value, fallback) {
   if (!Number.isFinite(coerced) || coerced < MINIMUM) {
     return fallback;
   }
-  return Math.floor(coerced);
+  return Math.min(Math.floor(coerced), Number.MAX_SAFE_INTEGER);
+}
+function clampPageToLimit(page, limit) {
+  return Math.min(page, Math.floor(Number.MAX_SAFE_INTEGER / limit) + 1);
 }
 function clampLimit(rawLimit, options) {
   const defaultLimit = coercePositiveInt(options?.defaultLimit, DEFAULT_LIMIT);
@@ -22,9 +25,10 @@ function clampLimit(rawLimit, options) {
 
 // src/pagination/offset.ts
 function normalizePageQuery(raw, options) {
+  const limit = clampLimit(raw.limit, options);
   return {
-    page: coercePositiveInt(raw.page, MINIMUM),
-    limit: clampLimit(raw.limit, options)
+    page: clampPageToLimit(coercePositiveInt(raw.page, MINIMUM), limit),
+    limit
   };
 }
 function buildPageResult(items, totalItems, query) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-core",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Zero-dependency NestJS 11 application foundation kit: error-envelope exception filter, request-timing interceptor, pagination helpers, health endpoints with indicator discovery, an optional Prometheus metrics endpoint with a contribution contract, OpenAPI documents in development, and OpenTelemetry trace correlation.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",