@bymax-one/nest-core 1.3.2 → 1.5.0

package/CHANGELOG.md

@@ -11,7 +11,186 @@ heading here.
 
 ## [Unreleased]
 
-## [1.3.2] - 2026-08-11
+## [1.5.0] - 2026-08-15
+
+An OpenAPI document could stop requiring credentials without anything saying
+so. Deleting a document-level `security` default — typically alongside the
+per-operation entries a library has taken over describing — leaves every route
+the backend itself owns with no requirement from any source, and the document
+stays valid, no requirement dangles, and the runtime still answers `401`. The
+only observable change is that a client generated from the document stops
+sending credentials.
+
+**Apply to a derived backend:** bump the dependency. No code change is needed.
+If the boot log now names operations, they are the ones a generated client will
+call without credentials — set `openapi.security`, or mark each public with an
+explicit `[]` in `openapi.operationSecurity`.
+
+### Added
+
+- **The document build warns when an operation ends up requiring no credential
+  at all.** Deleting a document-level `security` default — typically alongside
+  the per-operation entries a library has taken over describing — leaves every
+  route the backend itself owns with no requirement from any source. Nothing
+  catches it today: the document is valid, no requirement dangles so
+  `assertSchemesDeclared` is satisfied, the runtime still answers `401` so a
+  status-code probe finds nothing, and a consumer's document test stays green if
+  it asserts only the operations it enumerated. The only observable change is
+  that a client generated from the document sends no credentials.
+  `applyBymaxOpenApi` now emits one warning per build naming the affected
+  operations, capped at ten with a count of the rest.
+
+  It warns and never throws — an API that is public on purpose is legitimate —
+  and the trigger is narrow so the line stays worth reading: only when the
+  document declares no top-level `security`, **and** at least one other
+  operation does state a requirement, **and** the operation is not one of the
+  three this package registers. An explicit `[]` — from `operationSecurity`, a
+  decorator, or a library's fragment — states the intent and stops the report.
+  The known limit is documented rather than closed: a document with nothing
+  explicit anywhere is indistinguishable from an API that is public on purpose,
+  so removing _every_ requirement at once is not warned. Render the document
+  with and without your libraries and diff the operations you mount.
+
+## [1.4.0] - 2026-08-13
+
+HTTP metrics were blind to every request that did not reach a handler. Nest runs
+**middleware → guards → interceptors → pipes → handler**, and the recorder was an
+interceptor, so authentication failures, authorization failures, throttled
+requests and unknown paths were never counted. Measured on a running
+application, three requests — a handler success, a guard rejection, an unknown
+path — produced **one** sample. A deployment could be under a credential-stuffing
+run, a privilege probe or route enumeration with a flat error graph, which makes
+this a security fix rather than an observability improvement.
+
+**Apply to a derived backend:** bump the dependency. No code change is needed.
+Expect new `401`/`403`/`429` series on routes that already existed, a new
+`route="<unmatched>"` series for `404`s, and a **lower success rate** — the
+denominator finally includes the rejections. Existing `status_code="200"` series
+keep their values.
+
+### Security
+
+- **Requests rejected before a handler are now counted.** The recorder moved
+  from `APP_INTERCEPTOR` to middleware (`BymaxTimingMiddleware`), applied to
+  every route when `timing.enabled` is `true`. Nest runs middleware, then
+  guards, then interceptors: a request a guard rejects never reached
+  `intercept()`, and a request matching no route never reached a controller.
+  Measured on a real application, three requests — a handler success, a guard
+  rejection and an unknown path — produced exactly **one** sample. `401`, `403`,
+  `429` and `404` were all invisible, which is to say a deployment could be under
+  a credential-stuffing run, a privilege probe or route enumeration with a flat
+  error graph. All six cases are now counted, and the sample is emitted on the
+  response's `'close'` event rather than `'finish'`, so a client that hangs up
+  mid-request — what a scanner does — is counted too.
+- **The root path is recorded.** On Express the middleware is mounted at `'/'`
+  rather than through a wildcard pattern. The unbraced `'*splat'` skips the root outright,
+  and the braced `'{*splat}'` that Nest 11's migration guide prescribes stops
+  matching the _prefixed_ root once an application calls `setGlobalPrefix` —
+  which production applications almost always do. That was reported as
+  nest#14520 and fixed by nest#14522, whose regression test covers Fastify;
+  measured on `@nestjs/core` 11.1.28 with the Express adapter, the prefixed root
+  still reaches no middleware while the route itself answers `200`. Both
+  patterns were measured against the mount, which matched every path in both
+  configurations. Fastify needs the opposite choice — see the next entry. One
+  limit remains and is documented: module middleware is scoped to the global
+  prefix, so a request outside it entirely reaches no middleware.
+- **Fastify records the same labels as Express**, which the documented support
+  for both platforms had been promising without any test behind it. Nest runs
+  middleware on Fastify through `@fastify/middie`, whose `runMiddie` calls
+  `run(req.raw, reply.raw, next)` and copies only `id`, `hostname`, `protocol`,
+  `ip`, `ips`, `log`, `query` and `body` onto that raw request — never
+  `routeOptions`. The recorder therefore saw no route metadata at all and would
+  have labelled every Fastify request `<unmatched>`, destroying the per-route
+  breakdown and making a scan indistinguishable from ordinary traffic. Worse,
+  `forRoutes('/')` is a mount on Express but an **exact match** on Fastify, so
+  most requests produced no sample whatsoever. The module now selects the mount
+  per adapter and registers an `onRequest` hook on Fastify that carries the
+  resolved template to the recorder. Covered by a new Fastify end-to-end suite.
+- **Unmatched requests record a bounded label.** A request that matched no route
+  is recorded as `<unmatched>` (exported as `UNMATCHED_ROUTE`), never the
+  requested path. The previous raw-URL fallback would have let anyone mint one
+  Prometheus time series per probe, so counting scanner traffic under it would
+  have turned this fix into a memory-exhaustion vector.
+
+### Changed
+
+- **`ITimingSink` implementations now receive more samples**, including requests
+  that never reached a handler. Sinks that assumed "one sample per completed
+  request" should expect "one sample per closed request". The built-in metrics
+  bridge needs no change; a dashboard filtering on `2xx` sees its numbers
+  unchanged and its error rates become correct.
+- **No status is relabelled**, and that is deliberate. A client that hangs up
+  mid-handler was already counted — destroying the socket does not cancel the
+  JavaScript already running, so the handler finished and the interceptor
+  recorded an ordinary `200` — and it still is, once, under the same `200`.
+  Introducing a sentinel status for aborts would rewrite the value of
+  `status_code="200"` series that already exist in every deployment, moving
+  error-rate panels with no change in traffic. Whether an abort deserves its own
+  status is a separate decision from whether the request is counted at all, and
+  this release makes only the second one.
+- **The timing recorder is registered once, not twice.** The middleware
+  **replaced** the interceptor rather than joining it — two recorders would
+  double every rate an alert threshold is tuned against, which is a quieter
+  failure than the one being fixed.
+
+### Deprecated
+
+- **`TimingInterceptor`** is superseded by `BymaxTimingMiddleware` and is no
+  longer registered by `BymaxCoreModule`. It stays exported so an application
+  that wired it by hand keeps compiling; registering it alongside the middleware
+  records a second sample for every request that reaches a handler.
+
+### Added
+
+- **`BymaxTimingMiddleware` and `UNMATCHED_ROUTE`** are exported from the package
+  root.
+- **A library can describe its own routes in a consumer's document.** A provider
+  marked `@BymaxOpenApiContributor()` returns OpenAPI fragments keyed by handler
+  identity — `'AuthController.login'` — and they are merged onto the operations
+  those handlers produced. It exists because the two obvious alternatives do
+  not work: decorating a library's controllers with `@nestjs/swagger` would load
+  that peer in every application importing the library, and a consumer-side map
+  keyed by path cannot be written by a library mounted through
+  `RouterModule.register`, which does not know its own final paths.
+- **`openapi.operationIdFactory`**, plus the exported `OpenApiOperationIdFactory`
+  type. This package now always installs a factory so it can learn which handler
+  produced which operation, and **delegates the id string** — to this option when
+  set, to the format `@nestjs/swagger` itself produces otherwise. Choosing the id
+  instead would have renamed every operation in every published document and
+  broken any client generated from one; a test compares both documents to keep
+  that true if the peer's format ever changes.
+- **The contract types** `IOpenApiContributor`, `OpenApiFragment`,
+  `OpenApiFragmentObject` and `OpenApiHandlerKey`, exported from `./openapi` so a
+  sibling library can target them at its own compile time.
+- **`BYMAX_OPENAPI_CONTRACT_VERSION`**, and a required `contractVersion` on every
+  fragment. A fragment crosses a boundary between independently released
+  packages, and on that boundary compile-time types protect nothing: each side
+  type-checks against its own installed copy, so only the value travelling at
+  runtime can say which shape it is. A revision this package does not speak fails
+  the build naming both. Required rather than inferred from absence, following
+  the pattern Kubernetes objects use for `apiVersion` — an optional discriminator
+  is unambiguous only while exactly one revision exists, which is precisely when
+  nobody checks it.
+
+### Fixed
+
+- **`DiscoveryModule` is imported when only the document is enabled.** It was
+  imported on the synchronous registration path only when readiness discovery or
+  metrics could scan, so an application enabling nothing but OpenAPI had no
+  scanner — and a library's description of its own routes would have been
+  silently dropped.
+
+### Notes
+
+- Deriving fragments from validation decorators is deliberately **not** in this
+  package: it takes no dependency on any validation library. A library that
+  wants its schemas to track its own decorators generates them in its own build,
+  where that dependency already exists, and commits the result with a test
+  asserting generated matches committed — so drift fails in the repository that
+  caused it. An application's own DTOs need none of this; `@nestjs/swagger`'s CLI
+  plugin already derives them, which is the route a precompiled library lacks.
+
+## [1.3.2] - 2026-08-12
 
 A consumer audit of the served document found that it described the library's
 promises rather than the deployment: routes of features that were switched off
@@ -509,4 +688,6 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.2.2]: https://github.com/bymaxone/nest-core/compare/v1.2.1...v1.2.2
 [1.2.1]: https://github.com/bymaxone/nest-core/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/bymaxone/nest-core/compare/v1.1.1...v1.2.0
-[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.3.2...HEAD
+[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
+[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.5.0...HEAD