@bymax-one/nest-core 1.5.1 → 1.5.3

package/CHANGELOG.md

@@ -11,6 +11,143 @@ 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
+variable as production. An application that validates its own `APP_ENV` and
+never sets `NODE_ENV` was therefore classified as production on evidence it
+never gave — the OpenAPI document was refused in a development deployment, with
+no way to answer back. Two independent consumers reported the same split.
+
+**Apply to a derived backend:** nothing to change. A deployment that sets
+`NODE_ENV` behaves exactly as before. If yours validates its own variable
+instead, pass it as `environment` and the document is served where that variable
+says `development` or `test`.
+
+### Added
+
+- **`environment`, for applications that validate their own environment
+  variable.** The production guard read `NODE_ENV` and nothing else, and treated
+  an unset variable as production. An application that parses an `APP_ENV`
+  through its config schema and never sets `NODE_ENV` was therefore classified
+  as production on evidence it never gave — the OpenAPI document was refused in
+  a development deployment, with no way to answer back. Two independent
+  consumers reported the same split between the library's view of the
+  environment and their own validated one.
+
+  A top-level `environment` option is now consulted **where the process declares
+  nothing**: `NODE_ENV` unset, or set to whitespace. `NODE_ENV` wins whenever it
+  says anything at all, so no configured value can make a runtime that named
+  itself production serve the document — asserted in both guards rather than in
+  one. The declaration enters the same fail-closed classification, so an
+  unrecognized name is production like any other: this is a second source for
+  the value, never a second set of rules.
+
+  The narrowing is stated rather than buried. Both guards previously classified
+  from the process alone; now, in the single case where the process says
+  nothing, the snapshot a consumer bound decides the answer, because there is
+  nothing else to decide it with. Replacing a guess with a declaration is not an
+  override, but it is a real change to what the second guard depends on.
+
+  **Apply to a derived backend:** nothing to change. The option is optional and
+  every existing classification is unchanged — a deployment that sets `NODE_ENV`
+  behaves exactly as before.
+
 ## [1.5.1] - 2026-08-15
 
 Documentation only; no source change. The 1.5.0 warning's known-limit note told
@@ -736,4 +873,6 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.4.0]: https://github.com/bymaxone/nest-core/compare/v1.3.2...v1.4.0
 [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
-[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.5.1...HEAD
+[1.5.2]: https://github.com/bymaxone/nest-core/compare/v1.5.1...v1.5.2
+[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

@@ -202,6 +202,20 @@ BymaxCoreModule.forRoot({ isGlobal: false })
 Every block is optional; an omitted block, or an omitted field within it,
 falls back to the documented default. Pass only what you want to change.
 
+### `environment`
+
+The one top-level option rather than a block, because it describes the
+deployment rather than a feature.
+
+| Option        | Type     | Default | Description                                                                           |
+| ------------- | -------- | ------- | ------------------------------------------------------------------------------------- |
+| `environment` | `string` | unset   | The environment this deployment runs in, read only where `NODE_ENV` declares nothing. |
+
+Set it when your application validates its own environment variable and does not
+also set `NODE_ENV`. `NODE_ENV` wins whenever it says anything, so this can never
+serve the OpenAPI document in a runtime that named itself production. Full rules
+and the classification table: [Production is a closed door](#production-is-a-closed-door).
+
 ### `envelope`
 
 | Option            | Type      | Default | Description                                                                                    |
@@ -562,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
@@ -675,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
@@ -959,16 +1086,61 @@ can emit it once and never branch:
 ### Production is a closed door
 
 `NODE_ENV` decides, and the decision is fail-closed: only `development` and
-`test` are non-production. Any other value — including an unset variable —
-is production, and in production the document is never built and never mounted,
-whatever the configuration says. The guard runs twice, independently: the option
-resolver forces the feature off, and the bootstrap helper refuses again without
-trusting that resolution. There is no override.
+`test` are non-production. Any other value is production, and in production the
+document is never built and never mounted, whatever the configuration says. The
+guard runs twice, independently: the option resolver forces the feature off, and
+the bootstrap helper classifies the runtime again without trusting that
+resolution.
+
+**`NODE_ENV` cannot be overridden.** With it set to anything, no option serves
+the document in a runtime it named production.
 
 Enabling it in production is not an error, it is a no-op with a warning naming
 the option that was ignored, so a single configuration can be shared across
 environments.
 
+#### When your application validates its own environment variable
+
+Plenty of applications parse an `APP_ENV` through a config schema and never set
+`NODE_ENV` at all. Those deployments used to be classified as production —
+absence was the only evidence available — so the document was refused in an
+environment that never asked for the refusal, with no way to answer back.
+
+Declare the environment and it is used **where the process declares nothing**:
+
+```typescript
+BymaxCoreModule.forRootAsync({
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    // Your validated value, not a second copy of NODE_ENV.
+    environment: config.get('APP_ENV'),
+    openapi: { enabled: true }
+  })
+})
+```
+
+| `NODE_ENV`      | `environment` | Classified as  |
+| --------------- | ------------- | -------------- |
+| `production`    | `development` | **production** |
+| `development`   | (anything)    | development    |
+| unset, or blank | `development` | development    |
+| unset, or blank | `staging`     | **production** |
+| unset, or blank | unset         | **production** |
+
+Two properties are worth reading off that table. A declaration never overrules a
+process that named its own environment — the first row is the one that matters,
+and it is asserted in both guards rather than in one. And the declaration enters
+the same fail-closed classification, so an unrecognized name is production like
+any other; this is a second **source** for the value, never a second set of
+rules.
+
+The narrowing is deliberate and worth naming rather than burying: in the one
+case where the process declares nothing, the configuration a consumer bound does
+decide the answer, because there is nothing else to decide it with. Replacing a
+guess with a declaration is not the same as allowing an override — but it is a
+real change to what the second guard depends on, and you should know it before
+relying on either.
+
 ### Testing the enabled path under Jest
 
 `applyBymaxOpenApi` loads `@nestjs/swagger` through a dynamic `import()` — that
@@ -1153,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
@@ -1359,9 +1541,11 @@ guard you would apply to any internal endpoint, or keep it off the public listen
 A published document is a map of every route, parameter and error shape an application has —
 useful to a developer, and just as useful to anyone probing the service. So unlike the metrics
 endpoint, it is not left to a guard: it is refused outright whenever the runtime is not
-positively `development` or `test`, in two independent layers, with no option to override.
-An unset `NODE_ENV` counts as production, because the deployment nobody configured is the one
-most likely to be exposed.
+positively `development` or `test`, in two independent layers. **`NODE_ENV` cannot be
+overridden** — with it set to anything, no option serves the document in a runtime it named
+production. A runtime that declares nothing is classified from the application's own
+[`environment`](#environment) when it supplied one, and counts as production otherwise, because
+the deployment nobody configured is the one most likely to be exposed.
 
 ---
 

package/dist/index.cjs

@@ -30,6 +30,13 @@ function isProductionRuntime(value = process.env["NODE_ENV"]) {
   }
   return !NON_PRODUCTION_ENVIRONMENTS.has(value.trim().toLowerCase());
 }
+function runtimeEnvironmentName(declared) {
+  const fromProcess = process.env["NODE_ENV"];
+  if (fromProcess !== void 0 && fromProcess.trim() !== "") {
+    return fromProcess;
+  }
+  return declared;
+}
 
 // src/core.options.ts
 var DEFAULT_INDICATOR_TIMEOUT_MS = 5e3;
@@ -92,9 +99,9 @@ function cloneServers(raw) {
     (server) => server.description === void 0 ? { url: server.url } : { url: server.url, description: server.description }
   );
 }
-function resolveOpenApi(raw) {
+function resolveOpenApi(raw, declaredEnvironment) {
   const requested = raw?.enabled ?? false;
-  const production = isProductionRuntime();
+  const production = isProductionRuntime(runtimeEnvironmentName(declaredEnvironment));
   return {
     enabled: requested && !production,
     suppressedInProduction: requested && production,
@@ -131,8 +138,12 @@ function normalizeCoreOptions(raw) {
     timing: resolveTiming(raw?.timing),
     health: resolveHealth(raw?.health),
     metrics: resolveMetrics(raw?.metrics),
-    openapi: resolveOpenApi(raw?.openapi),
-    telemetry: resolveTelemetry(raw?.telemetry)
+    openapi: resolveOpenApi(raw?.openapi, raw?.environment),
+    telemetry: resolveTelemetry(raw?.telemetry),
+    // Spread rather than assigned so an application that declared nothing has
+    // no `environment` member at all, matching every other optional member on
+    // this snapshot under `exactOptionalPropertyTypes`.
+    ...raw?.environment === void 0 ? {} : { environment: raw.environment }
   });
 }
 normalizeCoreOptions();
@@ -1386,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

@@ -273,6 +273,28 @@ interface BymaxCoreModuleOptions {
     openapi?: OpenApiOptions;
     /** Trace correlation. Default: disabled. */
     telemetry?: TelemetryOptions;
+    /**
+     * The environment this deployment is running in, for the features that must
+     * never exist outside development — today, the OpenAPI document and its UI.
+     *
+     * **`NODE_ENV` always wins.** This is consulted only when the process
+     * declares nothing: `NODE_ENV` unset, or set to whitespace. It cannot make a
+     * runtime that identified itself as production serve the document, and no
+     * value here overrides one there.
+     *
+     * Set it when your application validates its own environment variable — an
+     * `APP_ENV` your config schema parses — and does not also set `NODE_ENV`.
+     * Without it, that deployment is classified as production because absence was
+     * the only evidence available, and the document is refused in an environment
+     * that never asked for the refusal.
+     *
+     * Recognized non-production values are `development` and `test`, compared
+     * case-insensitively and ignoring surrounding whitespace. Anything else,
+     * including an unrecognized name, is production.
+     *
+     * @example 'development'
+     */
+    environment?: string;
 }
 /** Fully-resolved envelope options. */
 interface ResolvedEnvelopeOptions {
@@ -334,9 +356,9 @@ interface ResolvedOpenApiOptions {
 }
 /**
  * The effective, defaults-applied configuration exposed under
- * `BYMAX_CORE_OPTIONS`. Fields with a documented default are always present;
- * the only optional field is `timing.slowRequestThresholdMs`, which has no
- * default and is absent unless the consumer sets it.
+ * `BYMAX_CORE_OPTIONS`. Fields with a documented default are always present.
+ * Two fields have no default and are absent unless the consumer supplies them:
+ * `timing.slowRequestThresholdMs`, and `environment`.
  */
 interface ResolvedCoreOptions {
     envelope: ResolvedEnvelopeOptions;
@@ -345,6 +367,12 @@ interface ResolvedCoreOptions {
     metrics: ResolvedMetricsOptions;
     openapi: ResolvedOpenApiOptions;
     telemetry: ResolvedTelemetryOptions;
+    /**
+     * The environment the application declared, carried through so the bootstrap
+     * helper classifies the runtime from the same two inputs the resolver did.
+     * Absent when the application declared none.
+     */
+    environment?: string;
 }
 
 /** Non-option extras accepted by `forRoot` / `forRootAsync`. */
@@ -402,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

@@ -273,6 +273,28 @@ interface BymaxCoreModuleOptions {
     openapi?: OpenApiOptions;
     /** Trace correlation. Default: disabled. */
     telemetry?: TelemetryOptions;
+    /**
+     * The environment this deployment is running in, for the features that must
+     * never exist outside development — today, the OpenAPI document and its UI.
+     *
+     * **`NODE_ENV` always wins.** This is consulted only when the process
+     * declares nothing: `NODE_ENV` unset, or set to whitespace. It cannot make a
+     * runtime that identified itself as production serve the document, and no
+     * value here overrides one there.
+     *
+     * Set it when your application validates its own environment variable — an
+     * `APP_ENV` your config schema parses — and does not also set `NODE_ENV`.
+     * Without it, that deployment is classified as production because absence was
+     * the only evidence available, and the document is refused in an environment
+     * that never asked for the refusal.
+     *
+     * Recognized non-production values are `development` and `test`, compared
+     * case-insensitively and ignoring surrounding whitespace. Anything else,
+     * including an unrecognized name, is production.
+     *
+     * @example 'development'
+     */
+    environment?: string;
 }
 /** Fully-resolved envelope options. */
 interface ResolvedEnvelopeOptions {
@@ -334,9 +356,9 @@ interface ResolvedOpenApiOptions {
 }
 /**
  * The effective, defaults-applied configuration exposed under
- * `BYMAX_CORE_OPTIONS`. Fields with a documented default are always present;
- * the only optional field is `timing.slowRequestThresholdMs`, which has no
- * default and is absent unless the consumer sets it.
+ * `BYMAX_CORE_OPTIONS`. Fields with a documented default are always present.
+ * Two fields have no default and are absent unless the consumer supplies them:
+ * `timing.slowRequestThresholdMs`, and `environment`.
  */
 interface ResolvedCoreOptions {
     envelope: ResolvedEnvelopeOptions;
@@ -345,6 +367,12 @@ interface ResolvedCoreOptions {
     metrics: ResolvedMetricsOptions;
     openapi: ResolvedOpenApiOptions;
     telemetry: ResolvedTelemetryOptions;
+    /**
+     * The environment the application declared, carried through so the bootstrap
+     * helper classifies the runtime from the same two inputs the resolver did.
+     * Absent when the application declared none.
+     */
+    environment?: string;
 }
 
 /** Non-option extras accepted by `forRoot` / `forRootAsync`. */
@@ -402,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

@@ -28,6 +28,13 @@ function isProductionRuntime(value = process.env["NODE_ENV"]) {
   }
   return !NON_PRODUCTION_ENVIRONMENTS.has(value.trim().toLowerCase());
 }
+function runtimeEnvironmentName(declared) {
+  const fromProcess = process.env["NODE_ENV"];
+  if (fromProcess !== void 0 && fromProcess.trim() !== "") {
+    return fromProcess;
+  }
+  return declared;
+}
 
 // src/core.options.ts
 var DEFAULT_INDICATOR_TIMEOUT_MS = 5e3;
@@ -90,9 +97,9 @@ function cloneServers(raw) {
     (server) => server.description === void 0 ? { url: server.url } : { url: server.url, description: server.description }
   );
 }
-function resolveOpenApi(raw) {
+function resolveOpenApi(raw, declaredEnvironment) {
   const requested = raw?.enabled ?? false;
-  const production = isProductionRuntime();
+  const production = isProductionRuntime(runtimeEnvironmentName(declaredEnvironment));
   return {
     enabled: requested && !production,
     suppressedInProduction: requested && production,
@@ -129,8 +136,12 @@ function normalizeCoreOptions(raw) {
     timing: resolveTiming(raw?.timing),
     health: resolveHealth(raw?.health),
     metrics: resolveMetrics(raw?.metrics),
-    openapi: resolveOpenApi(raw?.openapi),
-    telemetry: resolveTelemetry(raw?.telemetry)
+    openapi: resolveOpenApi(raw?.openapi, raw?.environment),
+    telemetry: resolveTelemetry(raw?.telemetry),
+    // Spread rather than assigned so an application that declared nothing has
+    // no `environment` member at all, matching every other optional member on
+    // this snapshot under `exactOptionalPropertyTypes`.
+    ...raw?.environment === void 0 ? {} : { environment: raw.environment }
   });
 }
 normalizeCoreOptions();
@@ -1384,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

@@ -16,6 +16,13 @@ function isProductionRuntime(value = process.env["NODE_ENV"]) {
   }
   return !NON_PRODUCTION_ENVIRONMENTS.has(value.trim().toLowerCase());
 }
+function runtimeEnvironmentName(declared) {
+  const fromProcess = process.env["NODE_ENV"];
+  if (fromProcess !== void 0 && fromProcess.trim() !== "") {
+    return fromProcess;
+  }
+  return declared;
+}
 
 // src/discovery.ts
 function labelFor(className, token) {
@@ -319,7 +326,7 @@ var CORE_PARAMETERS = {
   }
 };
 
-// src/openapi/openapi.document.ts
+// src/openapi/openapi.shape.ts
 var OPERATION_METHODS = [
   "get",
   "post",
@@ -330,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)) {
@@ -370,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) {
@@ -418,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)) {
@@ -427,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;
     }
@@ -502,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) }];
     })
@@ -545,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 };
 }
@@ -653,7 +684,7 @@ async function applyBymaxOpenApi(app) {
   const logger = new common.Logger("BymaxCoreModule");
   const resolved = resolveCoreOptions(app);
   const options = resolved.openapi;
-  if (isProductionRuntime()) {
+  if (isProductionRuntime(runtimeEnvironmentName(resolved.environment))) {
     if (options.suppressedInProduction || options.enabled) {
       logger.warn(
         'openapi.enabled was requested but the OpenAPI document is never served in production. Set NODE_ENV to "development" or "test" to serve it.'

package/dist/openapi/index.mjs

@@ -14,6 +14,13 @@ function isProductionRuntime(value = process.env["NODE_ENV"]) {
   }
   return !NON_PRODUCTION_ENVIRONMENTS.has(value.trim().toLowerCase());
 }
+function runtimeEnvironmentName(declared) {
+  const fromProcess = process.env["NODE_ENV"];
+  if (fromProcess !== void 0 && fromProcess.trim() !== "") {
+    return fromProcess;
+  }
+  return declared;
+}
 
 // src/discovery.ts
 function labelFor(className, token) {
@@ -317,7 +324,7 @@ var CORE_PARAMETERS = {
   }
 };
 
-// src/openapi/openapi.document.ts
+// src/openapi/openapi.shape.ts
 var OPERATION_METHODS = [
   "get",
   "post",
@@ -328,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)) {
@@ -368,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) {
@@ -416,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)) {
@@ -425,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;
     }
@@ -500,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) }];
     })
@@ -543,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 };
 }
@@ -651,7 +682,7 @@ async function applyBymaxOpenApi(app) {
   const logger = new Logger("BymaxCoreModule");
   const resolved = resolveCoreOptions(app);
   const options = resolved.openapi;
-  if (isProductionRuntime()) {
+  if (isProductionRuntime(runtimeEnvironmentName(resolved.environment))) {
     if (options.suppressedInProduction || options.enabled) {
       logger.warn(
         'openapi.enabled was requested but the OpenAPI document is never served in production. Set NODE_ENV to "development" or "test" to serve it.'

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.1",
+  "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",