@bymax-one/nest-core 1.5.2 → 1.5.3

package/CHANGELOG.md

@@ -11,6 +11,101 @@ heading here.
 
 ## [Unreleased]
 
+## [1.5.3] - 2026-08-18
+
+Three findings from a functional and security audit of a derived backend
+running against real Postgres, Redis and MinIO, plus the corrections that
+review found inside those fixes.
+
+The one that reaches a running deployment: an unprotected `/metrics` was
+documented as **requiring a credential**. The endpoint answers anyone when no
+`metrics.authToken` is set — the documented "protected at the edge"
+arrangement — and it inherited the document-level default instead of declaring
+itself public. That is the opposite of what 1.5.0 fixed and the more dangerous
+direction: documenting a guarded route as open fails loudly at the first
+generated client that omits the credential, while documenting an open route as
+guarded fails nowhere and hands the wrong answer to whoever opened the document
+to ask what is exposed.
+
+**Apply to a derived backend:** bump the dependency. Nothing to change in code.
+If you serve a document and leave the scrape endpoint unprotected, re-render it
+and confirm `/metrics` now carries `security: []`. If your page indexes reach
+SQL, `maxOffset` is now available and is opt-in.
+
+### Fixed
+
+- **An unprotected `/metrics` was documented as requiring a credential.** This
+  package writes an explicit `security: []` on its health probes so they do not
+  inherit a document-level default, and did not do the same for the scrape
+  endpoint. With `metrics.authToken` unset — the documented "protected at the
+  edge" arrangement, where the endpoint answers anyone — `GET /metrics` fell
+  through and inherited the default, so a document served by any backend with a
+  default claimed a credential was required for an endpoint serving process
+  metrics to whoever asked.
+
+  Measured on a running derived backend, not reasoned about: no credential →
+  `200` with the full Prometheus body, while the served document said
+  `security: [{ bymaxAuthAccessCookie: [] }]`.
+
+  **One half of the fix is covered by unit tests only, and that is worth saying
+  rather than leaving it to look field-verified.** The reported symptom reaches
+  a deployment through `openapi.security`, and that path was measured. Review
+  then found the same hole on the other path — a document that arrives carrying
+  its own default, whose `openapi.security` is therefore empty — and it is fixed
+  by reading the effective default from the document that will be served. No
+  consumer known to this project reaches that state today, so the only coverage
+  that can be pointed at is this repository's tests — which is a statement about
+  what is known, not a guarantee that nothing else exercises it. The health probes carried the same defect on
+  that path and are fixed by the same change.
+
+  This is the more dangerous of the two ways to describe a route wrongly, and
+  the opposite of what 1.5.0 fixed. Documenting a **guarded** route as open
+  fails loudly — a generated client omits the credential and gets a `401`.
+  Documenting an **open** route as guarded fails nowhere, and hands the wrong
+  answer to whoever opened the document to ask what is exposed.
+
+### Added
+
+- **`maxOffset`, a bound on how far into a dataset a request may start.**
+  `normalizePageQuery` capped the page size through `maxLimit` and bounded the
+  page index only for arithmetic safety, so `?page=1000000000&limit=20` resolved
+  to `OFFSET 19999999980`. Harmless against an in-memory repository and paid in
+  full by an offset-paginated database: twenty bytes of query for a table scan.
+
+  It is **absent by default and deliberately so** — legitimate deep paging
+  exists, and a silent ceiling would change the rows a working query returns.
+  Set it wherever the page index reaches SQL. `0` is a valid bound meaning "the
+  first page only"; any value that is not a non-negative safe integer reads as
+  absent rather than as an invented cap. Clamping matches how `maxLimit` already
+  behaves, and the resolved values come back in `meta`.
+
+### Documentation
+
+- **What the error filter classifies from, and what it cannot.** An error raised
+  before any handler ran becomes a clean `4xx` because the filter recognizes it
+  by **shape** — `expose: true` with a `4xx` status, the convention Node's body
+  pipeline follows — not by class. An error carrying no such marking is a `500`
+  even when a client caused it: a few kilobytes nested thousands of levels deep
+  overflows the stack during validation and surfaces as `RangeError`, well under
+  any size limit.
+
+  That is deliberate. Mapping `RangeError` to a `4xx` would make the filter
+  infer causation from an error class and would be wrong where it matters most —
+  a genuine stack overflow in application code is a `500` that should page
+  someone. Body-shape limits are the application's floor, applied in the one
+  window where the body exists and nothing has walked it yet.
+
+  **Apply to a derived backend:** cap nesting depth **after the body parser and
+  before validation**, so a hostile body is rejected as the `400` it is instead
+  of becoming a `5xx` that pollutes your error rate and writes a stack per
+  request. On Express that means module middleware, not `app.use()` during
+  bootstrap — measured, a middleware registered there runs ahead of Nest's own
+  parser and sees `req.body` as `undefined`, so the guard inspects nothing and
+  protects nothing while reading as present. Walk the parsed body iteratively; a
+  recursive depth check on a hostile payload overflows the stack it exists to
+  protect. The README carries the per-adapter table and a test that proves the
+  floor by behaviour rather than by where it is registered.
+
 ## [1.5.2] - 2026-08-15
 
 The production guard read `NODE_ENV` and nothing else, and treated an unset
@@ -779,4 +874,5 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.5.0]: https://github.com/bymaxone/nest-core/compare/v1.4.0...v1.5.0
 [1.5.1]: https://github.com/bymaxone/nest-core/compare/v1.5.0...v1.5.1
 [1.5.2]: https://github.com/bymaxone/nest-core/compare/v1.5.1...v1.5.2
-[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.5.2...HEAD
+[1.5.3]: https://github.com/bymaxone/nest-core/compare/v1.5.2...v1.5.3
+[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.5.3...HEAD

package/README.md

@@ -576,6 +576,96 @@ import { BadRequestException } from '@nestjs/common'
 throw new BadRequestException({ code: 'INVOICE_OVERDUE', message: 'Invoice is overdue' })
 ```
 
+### What the filter classifies from, and what it cannot
+
+An error raised before any handler ran — a malformed JSON body, a payload over
+the size limit — still becomes a clean `4xx` envelope rather than a 500. The
+filter recognizes those by **shape**, not by class: it honours an error that
+marks itself `expose: true` with a `4xx` status, which is the `http-errors`
+convention Node's body pipeline follows. Nothing in the application failed, so
+it is not routed through the unexpected-error seam either.
+
+**An error that carries no such marking is a 500, including when a client
+caused it.** The clearest case is depth: a body of a few kilobytes nested
+thousands of levels deep overflows the stack during validation and surfaces as
+`RangeError: Maximum call stack size exceeded` — well under any size limit, and
+answered `500 BYMAX_INTERNAL_ERROR`.
+
+That is deliberate, and the alternative is worse. Mapping `RangeError` to a
+`4xx` would make the filter infer causation from an error class, and it would be
+wrong exactly where it matters: a genuine stack overflow in your own code is a
+`500` that should page someone, and relabelling it as a client error would hide
+the failure the `500` exists to surface. By the time the filter sees the error,
+the body that caused it is gone.
+
+**So body-shape limits are the application's floor, not the filter's.** Cap
+nesting depth and the request is rejected as the `400` it is, instead of
+becoming a `5xx` that pollutes your error rate and writes a stack per request.
+
+**Position it after the body parser and before validation** — that window is the
+only place the body exists in a form you can measure and nothing has walked it
+yet. Earlier there is nothing to inspect; later the overflow has already
+happened, which is the failure you are trying to prevent.
+
+**Where that window is depends on the adapter, and the obvious answer is wrong
+on Express.** Measured against a real Nest application:
+
+| Registration point                       | `req.body` when it runs |
+| ---------------------------------------- | ----------------------- |
+| `app.use(...)` in `bootstrap.ts`         | **`undefined`**         |
+| Module middleware, `configure(consumer)` | the parsed body         |
+
+Nest registers its own parser during `app.init()`, so a middleware added with
+`app.use()` before that is mounted _ahead_ of it — a depth guard there inspects
+nothing and silently protects nothing. Register it as module middleware
+instead. On Fastify the ordering differs again, since Nest middleware runs
+through `@fastify/middie` ahead of body parsing; a `preValidation` hook is the
+place to look, and it is worth measuring rather than assuming.
+
+**Registering it in the right place is not enough — the route pattern silently
+skips paths too.** This package hit the same trap with its own timing
+middleware, and the measured behaviour is in `core.module.ts`:
+
+| `forRoutes(...)` | Express        | Fastify          |
+| ---------------- | -------------- | ---------------- |
+| `'*splat'`       | skips the root | —                |
+| `'{*splat}'`     | skips `/api`   | every path       |
+| `'/'`            | every path     | matches `/` only |
+
+So the named-wildcard form every migration guide reaches for leaves `POST /`
+unguarded on Express. A consumer measured exactly that: with `'*path'`, a
+2000-level body to the root returned `404` because the middleware never ran;
+with `'{*path}'`, `400`. If your application mounts nothing at the root, both
+forms answer `4xx` and the status alone cannot tell you which one you have.
+
+**Verify by behaviour, not by wiring — this is the part worth insisting on.**
+Checking where the middleware is registered is what the consumer above did; it
+looked correct, they confirmed it to us, and the guard was inert. Send a body
+nested past your ceiling and require your own rejection:
+
+```ts
+it('refuses a body nested past the ceiling', async () => {
+  const deep = JSON.parse(`${'['.repeat(2000)}${']'.repeat(2000)}`)
+
+  const res = await request(app.getHttpServer()).post('/anything').send({ name: deep })
+
+  // Match your guard's own message, not the status: a validation pipe rejects
+  // this shape with a 400 as well, so a status assertion passes with the floor
+  // removed and proves nothing.
+  expect(res.body.message).toBe('Request body is nested too deeply.')
+})
+```
+
+Use a depth that actually overflows, and assert the guard's own message. A test
+at a depth your DTO validation already rejects passes identically with the guard
+deleted — which is a check that cannot produce a negative result, and the reason
+this defect survived a green suite.
+
+A depth ceiling well above anything a legitimate payload nests and well below
+what exhausts the stack leaves a wide margin: one consumer runs `32`, against
+the ~2000 levels that overflow. Walk the parsed body iteratively — a recursive
+depth check on a hostile payload overflows the stack it was written to protect.
+
 ## ⏱️ Request Timing
 
 One `RequestTimingSample` is delivered to whatever implements `ITimingSink` for
@@ -689,13 +779,36 @@ export class InvoiceController {
 
   @Get()
   async list(@Query() raw: Record<string, unknown>): Promise<PageResult<Invoice>> {
-    const query = normalizePageQuery(raw, { maxLimit: 50 })
+    const query = normalizePageQuery(raw, { maxLimit: 50, maxOffset: 100_000 })
     const { rows, total } = await this.invoices.findPage(query)
     return buildPageResult(rows, total, query)
   }
 }
 ```
 
+#### Bound the offset, not just the page size
+
+`maxLimit` caps how many rows a request reads. `maxOffset` caps how far in it
+starts — and on an offset-paginated database that is the half that costs:
+
+```
+GET /invoices?page=1000000000&limit=20     →  OFFSET 19999999980
+```
+
+Twenty bytes of query, and Postgres walks the table to reach a page that does
+not exist. The page index has a floor of `1` and an arithmetic guard that keeps
+`(page - 1) * limit` an exact integer, but nothing bounds the product itself
+unless you say so.
+
+`maxOffset` is **absent by default and deliberately so**: legitimate deep paging
+exists, and a silent ceiling would change the rows a working query returns. Set
+it wherever the page index reaches SQL and your dataset has a knowable ceiling.
+`0` is a valid bound and means "the first page only".
+
+Clamping matches how `maxLimit` already behaves — the resolved values come back
+in `meta`, so a caller that cares can compare what it asked for against what it
+got.
+
 ### Cursor pagination
 
 ```typescript
@@ -1212,13 +1325,23 @@ being asked:
 | Route                               | Documented as                                           |
 | ----------------------------------- | ------------------------------------------------------- |
 | `GET /health/live`, `/health/ready` | Public (`security: []`), when a document default exists |
-| `GET /metrics`                      | Bearer-protected **iff** `metrics.authToken` is set     |
+| `GET /metrics`, token set           | Bearer-protected                                        |
+| `GET /metrics`, no token            | Public (`security: []`), when a document default exists |
 
 The probes are polled by an orchestrator holding no credential, and the scrape
 endpoint is protected exactly when you configured a token — this package owns
 both the route and the option, so you should not have to restate either. Your
 own `operationSecurity` entry still wins.
 
+The last row matters more than it looks. Without a token the scrape endpoint
+answers anyone, which is the deliberate "protected at the edge" arrangement — and
+an open route must **say** it is open rather than inherit your document default.
+Of the two ways to describe a route wrongly, this is the direction that hides:
+documenting a guarded route as open fails loudly at the first generated client
+that omits the credential and gets a `401`, while documenting an open route as
+guarded fails nowhere at all, and hands the wrong answer to whoever opened the
+document to ask what is exposed.
+
 ## 🧵 Trace correlation
 
 Off by default. Enabled, it reads the span your instrumentation already opened

package/dist/index.cjs

@@ -1397,9 +1397,12 @@ exports.BymaxCoreModule = class BymaxCoreModule extends BymaxCoreModuleBase {
    * it is scoped to, while `'{*splat}'` — the form Nest 11's migration guide
    * prescribes for "all routes" — stops matching the prefixed root once an
    * application calls `setGlobalPrefix`. That was reported as nest#14520 and
-   * fixed by nest#14522, whose regression test covers Fastify; on
-   * `@nestjs/core` 11.1.28 with the Express adapter the prefixed root still
-   * reaches no middleware while resolving to `200`.
+   * fixed by nest#14522, whose regression test covers Fastify; on the Express
+   * adapter the prefixed root still reaches no middleware while resolving to
+   * `200`. Measured on `@nestjs/core` 11.1.28 and re-measured unchanged on
+   * 11.2.1 — a minor release is exactly where this would plausibly have been
+   * fixed, so the version this was last confirmed against is part of the
+   * claim rather than a footnote to it.
    *
    * On Fastify the same `'/'` is an exact match rather than a mount — one of
    * three requests reached the middleware — so the wildcard is the only form

package/dist/index.d.cts

@@ -430,9 +430,12 @@ declare class BymaxCoreModule extends BymaxCoreModuleBase implements NestModule
      * it is scoped to, while `'{*splat}'` — the form Nest 11's migration guide
      * prescribes for "all routes" — stops matching the prefixed root once an
      * application calls `setGlobalPrefix`. That was reported as nest#14520 and
-     * fixed by nest#14522, whose regression test covers Fastify; on
-     * `@nestjs/core` 11.1.28 with the Express adapter the prefixed root still
-     * reaches no middleware while resolving to `200`.
+     * fixed by nest#14522, whose regression test covers Fastify; on the Express
+     * adapter the prefixed root still reaches no middleware while resolving to
+     * `200`. Measured on `@nestjs/core` 11.1.28 and re-measured unchanged on
+     * 11.2.1 — a minor release is exactly where this would plausibly have been
+     * fixed, so the version this was last confirmed against is part of the
+     * claim rather than a footnote to it.
      *
      * On Fastify the same `'/'` is an exact match rather than a mount — one of
      * three requests reached the middleware — so the wildcard is the only form

package/dist/index.d.ts

@@ -430,9 +430,12 @@ declare class BymaxCoreModule extends BymaxCoreModuleBase implements NestModule
      * it is scoped to, while `'{*splat}'` — the form Nest 11's migration guide
      * prescribes for "all routes" — stops matching the prefixed root once an
      * application calls `setGlobalPrefix`. That was reported as nest#14520 and
-     * fixed by nest#14522, whose regression test covers Fastify; on
-     * `@nestjs/core` 11.1.28 with the Express adapter the prefixed root still
-     * reaches no middleware while resolving to `200`.
+     * fixed by nest#14522, whose regression test covers Fastify; on the Express
+     * adapter the prefixed root still reaches no middleware while resolving to
+     * `200`. Measured on `@nestjs/core` 11.1.28 and re-measured unchanged on
+     * 11.2.1 — a minor release is exactly where this would plausibly have been
+     * fixed, so the version this was last confirmed against is part of the
+     * claim rather than a footnote to it.
      *
      * On Fastify the same `'/'` is an exact match rather than a mount — one of
      * three requests reached the middleware — so the wildcard is the only form

package/dist/index.mjs

@@ -1395,9 +1395,12 @@ var BymaxCoreModule = class extends BymaxCoreModuleBase {
    * it is scoped to, while `'{*splat}'` — the form Nest 11's migration guide
    * prescribes for "all routes" — stops matching the prefixed root once an
    * application calls `setGlobalPrefix`. That was reported as nest#14520 and
-   * fixed by nest#14522, whose regression test covers Fastify; on
-   * `@nestjs/core` 11.1.28 with the Express adapter the prefixed root still
-   * reaches no middleware while resolving to `200`.
+   * fixed by nest#14522, whose regression test covers Fastify; on the Express
+   * adapter the prefixed root still reaches no middleware while resolving to
+   * `200`. Measured on `@nestjs/core` 11.1.28 and re-measured unchanged on
+   * 11.2.1 — a minor release is exactly where this would plausibly have been
+   * fixed, so the version this was last confirmed against is part of the
+   * claim rather than a footnote to it.
    *
    * On Fastify the same `'/'` is an exact match rather than a mount — one of
    * three requests reached the middleware — so the wildcard is the only form

package/dist/openapi/index.cjs

@@ -326,7 +326,7 @@ var CORE_PARAMETERS = {
   }
 };
 
-// src/openapi/openapi.document.ts
+// src/openapi/openapi.shape.ts
 var OPERATION_METHODS = [
   "get",
   "post",
@@ -337,21 +337,26 @@ var OPERATION_METHODS = [
   "options",
   "trace"
 ];
-var METRICS_SCHEME_NAME = "BymaxMetricsAuth";
-var ERROR_ENVELOPE_SCHEMA = "BymaxErrorEnvelope";
-var HEALTH_RESPONSE_SCHEMA = "BymaxHealthResponse";
 function asRecord(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return {};
   }
   return value;
 }
-function mergeAbsent(existing, additions) {
-  return { ...additions, ...existing };
-}
 function operationsOf(item) {
   return Object.entries(asRecord(item)).filter(([key]) => OPERATION_METHODS.includes(key));
 }
+function operationKey(method, path) {
+  return `${method.toUpperCase()} ${path}`;
+}
+
+// src/openapi/openapi.document.ts
+var METRICS_SCHEME_NAME = "BymaxMetricsAuth";
+var ERROR_ENVELOPE_SCHEMA = "BymaxErrorEnvelope";
+var HEALTH_RESPONSE_SCHEMA = "BymaxHealthResponse";
+function mergeAbsent(existing, additions) {
+  return { ...additions, ...existing };
+}
 function mergeResponses(existing, additions) {
   const merged = new Map(Object.entries(existing));
   for (const [status, value] of Object.entries(additions)) {
@@ -377,21 +382,24 @@ function withoutDisabledRoutes(paths, options, routes) {
   });
   return Object.fromEntries(kept.filter(([, item]) => item !== void 0));
 }
-function ownRouteSecurity(path, method, options, routes) {
+function inheritsRequirement(document, openapi) {
+  if (document.security === void 0) {
+    return openapi.security.length > 0;
+  }
+  return Array.isArray(document.security) && document.security.length > 0;
+}
+function ownRouteSecurity(path, method, options, routes, inherits) {
   if (method !== "get") {
     return void 0;
   }
   if (options.metrics.authToken !== void 0 && routes.isMetrics(path)) {
     return [{ [METRICS_SCHEME_NAME]: [] }];
   }
-  if (options.openapi.security.length > 0 && routes.isHealth(path)) {
+  if (inherits && (routes.isHealth(path) || routes.isMetrics(path))) {
     return [];
   }
   return void 0;
 }
-function operationKey(method, path) {
-  return `${method.toUpperCase()} ${path}`;
-}
 function coreResponses(path, options, routes) {
   const responses = {};
   if (options.envelope.enabled) {
@@ -425,7 +433,7 @@ function mergeFragment(operation, fragment) {
   }
   return merged;
 }
-function augmentOperation(operation, path, method, options, routes, contributions) {
+function augmentOperation(operation, path, method, options, routes, contributions, inherits) {
   const declaredByDocument = operation["security"] !== void 0;
   let result = { ...operation };
   for (const fragment of fragmentsFor(result["operationId"], contributions)) {
@@ -434,7 +442,7 @@ function augmentOperation(operation, path, method, options, routes, contribution
   if (!declaredByDocument) {
     const override = options.openapi.operationSecurity[operationKey(method, path)];
     const describedByLibrary = result["security"] !== void 0;
-    const security = override ?? (describedByLibrary ? void 0 : ownRouteSecurity(path, method, options, routes));
+    const security = override ?? (describedByLibrary ? void 0 : ownRouteSecurity(path, method, options, routes, inherits));
     if (security !== void 0) {
       result["security"] = security;
     }
@@ -509,12 +517,20 @@ function assertOverridesMatch(paths, openapi) {
     `[BymaxCoreModule] openapi.operationSecurity addresses ${unmatched.length} operation(s) that the document does not contain: ${unmatched.join(", ")}. Keys are "<METHOD> <path>" with the path exactly as documented, including any global prefix. The document contains: ${documented.length === 0 ? "(none)" : documented.join(", ")}.`
   );
 }
-function augmentPaths(paths, options, routes, contributions) {
+function augmentPaths(paths, options, routes, contributions, inherits) {
   return Object.fromEntries(
     Object.entries(paths).map(([path, item]) => {
       const augmented = operationsOf(item).map(([method, operation]) => [
         method,
-        augmentOperation(asRecord(operation), path, method, options, routes, contributions)
+        augmentOperation(
+          asRecord(operation),
+          path,
+          method,
+          options,
+          routes,
+          contributions,
+          inherits
+        )
       ]);
       return [path, { ...asRecord(item), ...Object.fromEntries(augmented) }];
     })
@@ -552,7 +568,15 @@ function augmentDocument(document, options, pathPrefixes = [""], contributions =
   const routes = indexOwnRoutes(options, pathPrefixes);
   const served = withoutDisabledRoutes(asRecord(document.paths), options, routes);
   assertOverridesMatch(served, openapi);
-  const paths = document.paths === void 0 ? {} : { paths: augmentPaths(served, options, routes, contributions) };
+  const paths = document.paths === void 0 ? {} : {
+    paths: augmentPaths(
+      served,
+      options,
+      routes,
+      contributions,
+      inheritsRequirement(document, openapi)
+    )
+  };
   const security = openapi.security.length > 0 && document.security === void 0 ? { security: openapi.security } : {};
   return { ...document, components: Object.fromEntries(merged), ...paths, ...security };
 }

package/dist/openapi/index.mjs

@@ -324,7 +324,7 @@ var CORE_PARAMETERS = {
   }
 };
 
-// src/openapi/openapi.document.ts
+// src/openapi/openapi.shape.ts
 var OPERATION_METHODS = [
   "get",
   "post",
@@ -335,21 +335,26 @@ var OPERATION_METHODS = [
   "options",
   "trace"
 ];
-var METRICS_SCHEME_NAME = "BymaxMetricsAuth";
-var ERROR_ENVELOPE_SCHEMA = "BymaxErrorEnvelope";
-var HEALTH_RESPONSE_SCHEMA = "BymaxHealthResponse";
 function asRecord(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return {};
   }
   return value;
 }
-function mergeAbsent(existing, additions) {
-  return { ...additions, ...existing };
-}
 function operationsOf(item) {
   return Object.entries(asRecord(item)).filter(([key]) => OPERATION_METHODS.includes(key));
 }
+function operationKey(method, path) {
+  return `${method.toUpperCase()} ${path}`;
+}
+
+// src/openapi/openapi.document.ts
+var METRICS_SCHEME_NAME = "BymaxMetricsAuth";
+var ERROR_ENVELOPE_SCHEMA = "BymaxErrorEnvelope";
+var HEALTH_RESPONSE_SCHEMA = "BymaxHealthResponse";
+function mergeAbsent(existing, additions) {
+  return { ...additions, ...existing };
+}
 function mergeResponses(existing, additions) {
   const merged = new Map(Object.entries(existing));
   for (const [status, value] of Object.entries(additions)) {
@@ -375,21 +380,24 @@ function withoutDisabledRoutes(paths, options, routes) {
   });
   return Object.fromEntries(kept.filter(([, item]) => item !== void 0));
 }
-function ownRouteSecurity(path, method, options, routes) {
+function inheritsRequirement(document, openapi) {
+  if (document.security === void 0) {
+    return openapi.security.length > 0;
+  }
+  return Array.isArray(document.security) && document.security.length > 0;
+}
+function ownRouteSecurity(path, method, options, routes, inherits) {
   if (method !== "get") {
     return void 0;
   }
   if (options.metrics.authToken !== void 0 && routes.isMetrics(path)) {
     return [{ [METRICS_SCHEME_NAME]: [] }];
   }
-  if (options.openapi.security.length > 0 && routes.isHealth(path)) {
+  if (inherits && (routes.isHealth(path) || routes.isMetrics(path))) {
     return [];
   }
   return void 0;
 }
-function operationKey(method, path) {
-  return `${method.toUpperCase()} ${path}`;
-}
 function coreResponses(path, options, routes) {
   const responses = {};
   if (options.envelope.enabled) {
@@ -423,7 +431,7 @@ function mergeFragment(operation, fragment) {
   }
   return merged;
 }
-function augmentOperation(operation, path, method, options, routes, contributions) {
+function augmentOperation(operation, path, method, options, routes, contributions, inherits) {
   const declaredByDocument = operation["security"] !== void 0;
   let result = { ...operation };
   for (const fragment of fragmentsFor(result["operationId"], contributions)) {
@@ -432,7 +440,7 @@ function augmentOperation(operation, path, method, options, routes, contribution
   if (!declaredByDocument) {
     const override = options.openapi.operationSecurity[operationKey(method, path)];
     const describedByLibrary = result["security"] !== void 0;
-    const security = override ?? (describedByLibrary ? void 0 : ownRouteSecurity(path, method, options, routes));
+    const security = override ?? (describedByLibrary ? void 0 : ownRouteSecurity(path, method, options, routes, inherits));
     if (security !== void 0) {
       result["security"] = security;
     }
@@ -507,12 +515,20 @@ function assertOverridesMatch(paths, openapi) {
     `[BymaxCoreModule] openapi.operationSecurity addresses ${unmatched.length} operation(s) that the document does not contain: ${unmatched.join(", ")}. Keys are "<METHOD> <path>" with the path exactly as documented, including any global prefix. The document contains: ${documented.length === 0 ? "(none)" : documented.join(", ")}.`
   );
 }
-function augmentPaths(paths, options, routes, contributions) {
+function augmentPaths(paths, options, routes, contributions, inherits) {
   return Object.fromEntries(
     Object.entries(paths).map(([path, item]) => {
       const augmented = operationsOf(item).map(([method, operation]) => [
         method,
-        augmentOperation(asRecord(operation), path, method, options, routes, contributions)
+        augmentOperation(
+          asRecord(operation),
+          path,
+          method,
+          options,
+          routes,
+          contributions,
+          inherits
+        )
       ]);
       return [path, { ...asRecord(item), ...Object.fromEntries(augmented) }];
     })
@@ -550,7 +566,15 @@ function augmentDocument(document, options, pathPrefixes = [""], contributions =
   const routes = indexOwnRoutes(options, pathPrefixes);
   const served = withoutDisabledRoutes(asRecord(document.paths), options, routes);
   assertOverridesMatch(served, openapi);
-  const paths = document.paths === void 0 ? {} : { paths: augmentPaths(served, options, routes, contributions) };
+  const paths = document.paths === void 0 ? {} : {
+    paths: augmentPaths(
+      served,
+      options,
+      routes,
+      contributions,
+      inheritsRequirement(document, openapi)
+    )
+  };
   const security = openapi.security.length > 0 && document.security === void 0 ? { security: openapi.security } : {};
   return { ...document, components: Object.fromEntries(merged), ...paths, ...security };
 }

package/dist/pagination/index.cjs

@@ -19,6 +19,12 @@ function coercePositiveInt(value, fallback) {
 function clampPageToLimit(page, limit) {
   return Math.min(page, Math.floor(Number.MAX_SAFE_INTEGER / limit) + 1);
 }
+function clampPageToOffset(page, limit, maxOffset) {
+  if (maxOffset === void 0 || !Number.isSafeInteger(maxOffset) || maxOffset < 0) {
+    return page;
+  }
+  return Math.min(page, Math.floor(maxOffset / limit) + 1);
+}
 function clampLimit(rawLimit, options) {
   const defaultLimit = coercePositiveInt(options?.defaultLimit, DEFAULT_LIMIT);
   const maxLimit = coercePositiveInt(options?.maxLimit, DEFAULT_MAX_LIMIT);
@@ -29,7 +35,11 @@ function clampLimit(rawLimit, options) {
 function normalizePageQuery(raw, options) {
   const limit = clampLimit(raw.limit, options);
   return {
-    page: clampPageToLimit(coercePositiveInt(raw.page, MINIMUM), limit),
+    page: clampPageToOffset(
+      clampPageToLimit(coercePositiveInt(raw.page, MINIMUM), limit),
+      limit,
+      options?.maxOffset
+    ),
     limit
   };
 }

package/dist/pagination/index.d.cts

@@ -51,14 +51,43 @@ interface PageResult<T> {
  * 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`
- *   (default `100`) overrides.
+ * @param options - Per-call `defaultLimit` (default `20`), `maxLimit` (default
+ *   `100`) and `maxOffset` (absent by default) overrides. `maxLimit` bounds how
+ *   many rows a request reads; `maxOffset` bounds how far in it starts, which is
+ *   the half an offset-paginated database pays for.
  * @returns A clamped, safe query ready to hand to a repository.
  */
+/**
+ * Options for {@link normalizePageQuery}: the shared limit bounds, plus the one
+ * that only means anything to offset pagination.
+ *
+ * Declared here rather than beside the shared bounds so it cannot reach the
+ * cursor normalizer, which takes {@link PaginationLimitOptions} and has no
+ * offset to bound. An option that type-checks on a function that ignores it is
+ * worse than a missing one — it reads as configured and does nothing.
+ */
+interface PageQueryOptions extends PaginationLimitOptions {
+    /**
+     * Hard cap applied to the repository offset the query drives,
+     * `(page - 1) * limit`. Absent by default, which bounds nothing beyond
+     * arithmetic safety.
+     *
+     * `maxLimit` bounds how many rows a request reads; this bounds how far in it
+     * starts, which is the half that costs on an offset-paginated database — a
+     * `SELECT … OFFSET 20000000000` is a twenty-byte request that scans a table.
+     * Set it wherever the page index reaches SQL and the dataset has a knowable
+     * ceiling. There is deliberately no default: legitimate deep paging exists,
+     * and a silent cap would change the rows a working query returns.
+     *
+     * `0` is meaningful and means "the first page only". Any other value that is
+     * not a non-negative safe integer is read as absent.
+     */
+    maxOffset?: number;
+}
 declare function normalizePageQuery(raw: {
     page?: unknown;
     limit?: unknown;
-}, options?: PaginationLimitOptions): PageQuery;
+}, options?: PageQueryOptions): PageQuery;
 /**
  * Assemble a {@link PageResult} from a page of items and the total count.
  *

package/dist/pagination/index.d.ts

@@ -51,14 +51,43 @@ interface PageResult<T> {
  * 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`
- *   (default `100`) overrides.
+ * @param options - Per-call `defaultLimit` (default `20`), `maxLimit` (default
+ *   `100`) and `maxOffset` (absent by default) overrides. `maxLimit` bounds how
+ *   many rows a request reads; `maxOffset` bounds how far in it starts, which is
+ *   the half an offset-paginated database pays for.
  * @returns A clamped, safe query ready to hand to a repository.
  */
+/**
+ * Options for {@link normalizePageQuery}: the shared limit bounds, plus the one
+ * that only means anything to offset pagination.
+ *
+ * Declared here rather than beside the shared bounds so it cannot reach the
+ * cursor normalizer, which takes {@link PaginationLimitOptions} and has no
+ * offset to bound. An option that type-checks on a function that ignores it is
+ * worse than a missing one — it reads as configured and does nothing.
+ */
+interface PageQueryOptions extends PaginationLimitOptions {
+    /**
+     * Hard cap applied to the repository offset the query drives,
+     * `(page - 1) * limit`. Absent by default, which bounds nothing beyond
+     * arithmetic safety.
+     *
+     * `maxLimit` bounds how many rows a request reads; this bounds how far in it
+     * starts, which is the half that costs on an offset-paginated database — a
+     * `SELECT … OFFSET 20000000000` is a twenty-byte request that scans a table.
+     * Set it wherever the page index reaches SQL and the dataset has a knowable
+     * ceiling. There is deliberately no default: legitimate deep paging exists,
+     * and a silent cap would change the rows a working query returns.
+     *
+     * `0` is meaningful and means "the first page only". Any other value that is
+     * not a non-negative safe integer is read as absent.
+     */
+    maxOffset?: number;
+}
 declare function normalizePageQuery(raw: {
     page?: unknown;
     limit?: unknown;
-}, options?: PaginationLimitOptions): PageQuery;
+}, options?: PageQueryOptions): PageQuery;
 /**
  * Assemble a {@link PageResult} from a page of items and the total count.
  *

package/dist/pagination/index.mjs

@@ -17,6 +17,12 @@ function coercePositiveInt(value, fallback) {
 function clampPageToLimit(page, limit) {
   return Math.min(page, Math.floor(Number.MAX_SAFE_INTEGER / limit) + 1);
 }
+function clampPageToOffset(page, limit, maxOffset) {
+  if (maxOffset === void 0 || !Number.isSafeInteger(maxOffset) || maxOffset < 0) {
+    return page;
+  }
+  return Math.min(page, Math.floor(maxOffset / limit) + 1);
+}
 function clampLimit(rawLimit, options) {
   const defaultLimit = coercePositiveInt(options?.defaultLimit, DEFAULT_LIMIT);
   const maxLimit = coercePositiveInt(options?.maxLimit, DEFAULT_MAX_LIMIT);
@@ -27,7 +33,11 @@ function clampLimit(rawLimit, options) {
 function normalizePageQuery(raw, options) {
   const limit = clampLimit(raw.limit, options);
   return {
-    page: clampPageToLimit(coercePositiveInt(raw.page, MINIMUM), limit),
+    page: clampPageToOffset(
+      clampPageToLimit(coercePositiveInt(raw.page, MINIMUM), limit),
+      limit,
+      options?.maxOffset
+    ),
     limit
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-core",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "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",