@bymax-one/nest-core 1.3.1 → 1.4.0

package/README.md

@@ -75,7 +75,7 @@ never loads its peer, which the release gate asserts against the packed tarball.
 
 ### ⏱️ Observability
 
-- ✅ **Request timing** — one sample per completed request, handed to the sink you register;
+- ✅ **Request timing** — one sample per closed request, rejections included, handed to the sink you register;
   the library stores nothing itself
 - ✅ **Slow-request flag** — samples above `slowRequestThresholdMs` are marked, so a sink can
   branch without re-deriving the threshold
@@ -120,7 +120,7 @@ never loads its peer, which the release gate asserts against the packed tarball.
 
 | Subpath        | Contents                                                                                                                                                                                                                                                            |
 | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `.`            | `BymaxCoreModule`, the error envelope and its code catalog, the timing interceptor, the DI tokens, and every option type                                                                                                                                            |
+| `.`            | `BymaxCoreModule`, the error envelope and its code catalog, the request-timing middleware, the DI tokens, and every option type                                                                                                                                     |
 | `./pagination` | `normalizePageQuery`, `buildPageResult`, `normalizeCursorQuery`, `buildCursorResult`, `encodeCursor`, `decodeCursor` and their types — pure functions, no NestJS provider involved                                                                                  |
 | `./health`     | `IHealthIndicator`, `HealthResponse`, the indicator contracts and the `@BymaxHealthIndicator()` marker, so a package that only implements an indicator does not import the module                                                                                   |
 | `./metrics`    | `IMetricsContributor` and the `@BymaxMetricsContributor()` marker, so a package that only publishes metrics imports neither the module nor its DI tokens. The one subpath whose types name `prom-client`, which anyone implementing the contract already depends on |
@@ -213,7 +213,7 @@ falls back to the documented default. Pass only what you want to change.
 
 | Option                   | Type      | Default | Description                                                                    |
 | ------------------------ | --------- | ------- | ------------------------------------------------------------------------------ |
-| `enabled`                | `boolean` | `true`  | Registers the request-timing interceptor.                                      |
+| `enabled`                | `boolean` | `true`  | Applies the request-timing middleware to every route.                          |
 | `slowRequestThresholdMs` | `number`  | unset   | Samples above this duration are flagged `slow: true`. Absent means never slow. |
 
 ### `health`
@@ -272,22 +272,113 @@ BymaxCoreModule.forRoot({
 
 ### `openapi`
 
-| Option               | Type                      | Default       | Description                                                                    |
-| -------------------- | ------------------------- | ------------- | ------------------------------------------------------------------------------ |
-| `enabled`            | `boolean`                 | `false`       | Builds and serves the document. Ignored in production, where it is always off. |
-| `path`               | `string`                  | `'docs'`      | Route serving the interactive UI.                                              |
-| `jsonPath`           | `string`                  | `'docs-json'` | Route serving the raw JSON document.                                           |
-| `title`              | `string`                  | `'API'`       | Document title.                                                                |
-| `description`        | `string`                  | `''`          | Document description.                                                          |
-| `version`            | `string`                  | `'1.0.0'`     | Document version, independent of the package version.                          |
-| `servers`            | `{ url, description? }[]` | `[]`          | Servers advertised by the document.                                            |
-| `securitySchemes`    | `Record<string, object>`  | `{}`          | Security schemes copied into the document's components.                        |
-| `includeCoreSchemas` | `boolean`                 | `true`        | Contributes this package's own schemas — envelope, health, pagination.         |
+| Option               | Type                                       | Default       | Description                                                                         |
+| -------------------- | ------------------------------------------ | ------------- | ----------------------------------------------------------------------------------- |
+| `enabled`            | `boolean`                                  | `false`       | Builds and serves the document. Ignored in production, where it is always off.      |
+| `path`               | `string`                                   | `'docs'`      | Route serving the interactive UI.                                                   |
+| `jsonPath`           | `string`                                   | `'docs-json'` | Route serving the raw JSON document.                                                |
+| `title`              | `string`                                   | `'API'`       | Document title.                                                                     |
+| `description`        | `string`                                   | `''`          | Document description.                                                               |
+| `version`            | `string`                                   | `'1.0.0'`     | Document version, independent of the package version.                               |
+| `servers`            | `{ url, description? }[]`                  | `[]`          | Servers advertised by the document.                                                 |
+| `securitySchemes`    | `Record<string, object>`                   | `{}`          | Security schemes copied into the document's components.                             |
+| `security`           | `SecurityRequirement[]`                    | `[]`          | The requirement every operation carries unless it says otherwise.                   |
+| `operationSecurity`  | `OperationSecurityMap`                     | `{}`          | Per-operation overrides. An empty array marks that operation public.                |
+| `operationIdFactory` | `(controller, method, version?) => string` | peer default  | Names the operations. Leave unset and nothing an existing client generated changes. |
+| `includeCoreSchemas` | `boolean`                                  | `true`        | Contributes this package's own schemas and references them from the responses.      |
 
 Unlike `health` and `metrics`, this block behaves identically on `forRoot` and
 `forRootAsync`: the document is mounted from the bootstrap helper, after the
 options have resolved, so a custom `path` is honored on both registration paths.
 
+#### Documenting authentication
+
+Set the default on the document and mark the exceptions. `security` names
+schemes declared in `securitySchemes`; `operationSecurity` overrides it for one
+operation, and an **empty array is how the specification says "public"** — which
+matters more than it looks, because an operation with _absent_ security inherits
+the document default, so a generated client would attach credentials to your
+registration endpoint.
+
+```ts
+openapi: {
+  enabled: true,
+  securitySchemes: {
+    cookieAuth: { type: 'apiKey', in: 'cookie', name: 'access_token' },
+    refreshCookie: { type: 'apiKey', in: 'cookie', name: 'refresh_token' }
+  },
+  security: [{ cookieAuth: [] }],
+  operationSecurity: {
+    'POST /auth/login': [],
+    'POST /auth/register': [],
+    'POST /auth/refresh': [{ refreshCookie: [] }]
+  }
+}
+```
+
+An operation that already declares its own requirement — because you decorated
+the handler — is never overwritten, on either path.
+
+#### The operation key is a contract
+
+Keys are `"<METHOD> <path>"`, and the format is documented rather than
+incidental: a sibling library can ship a plain-data map of its own operations
+keyed this way, so you spread it in instead of restating which of its routes are
+public. Import `OperationSecurityMap` to have that map checked at the library's
+own compile time — it is a type-only export, so nothing couples at runtime.
+
+- The method is **uppercase**, separated by exactly one space.
+- The path is written **exactly as it appears in the generated document**:
+  leading slash, OpenAPI template braces (`/users/{id}`), no trailing slash, and
+  **including any global prefix**. `@nestjs/swagger` puts
+  `app.setGlobalPrefix('api')` into the documented paths, so the key becomes
+  `'POST /api/auth/login'` in an application that sets one.
+
+Because of that last point, a library shipping such a map should expose a
+**function taking the prefix**, not a frozen constant — the call site is the only
+place that knows it:
+
+```ts
+// in the library
+export function authOperationSecurity(prefix = ''): OperationSecurityMap { /* … */ }
+
+// in the application
+operationSecurity: { ...authOperationSecurity('api'), ...myOwnOverrides }
+```
+
+A requirement naming a scheme that is not declared **fails the document build**
+too, listing the names that missed and the ones the document defines. A
+requirement is a reference, and a reference to nothing yields a document whose
+security cannot be resolved: a client generator looks the name up, finds
+nothing, and either fails or emits an unauthenticated client.
+
+A key matching no operation **fails the document build**, listing both the keys
+that missed and the operations that exist. Silence would be worse: a route
+renamed out from under a stale key would quietly inherit the document default
+and be documented as authenticated when it is not, or the reverse. Failing is
+safe here in a way it rarely is — the document is only ever built outside
+production, so this can only stop a developer.
+
+One consequence for conditionally-registered routes: the map is static wiring
+while a route may not be. If an operation belongs to a feature you register per
+environment — your own conditional module, or a library feature toggled off
+somewhere — a key naming it fails the boot in whichever docs-enabled environment
+lacks that route. That is the intended loud behavior, so build the map the same
+way you build the modules: assemble it per feature and spread the fragments in,
+rather than writing one flat literal that outlives the routes it names.
+
+That last sentence cuts both ways, and the consequence is worth stating rather
+than discovering. **These checks only run when the document is actually built.**
+With `openapi.enabled` false, or in a production runtime where the feature is
+forced off, nothing validates: a stale key, a renamed route, or a requirement
+naming a scheme you deleted all sit there quietly until someone turns the
+document on. That is deliberate — refusing to boot a production service over a
+documentation setting it never serves would be the wrong trade — but it means
+the errors surface on a developer's machine or in CI, **not** at the moment the
+configuration went wrong. If you gate the document behind an environment flag,
+make sure at least one environment that runs your tests has it on, or these
+checks never fire.
+
 ## 🔑 DI Tokens
 
 Every token is a `Symbol`. `BYMAX_CORRELATION_PROVIDER` and
@@ -353,8 +444,8 @@ throw new BadRequestException({ code: 'INVOICE_OVERDUE', message: 'Invoice is ov
 
 ## ⏱️ Request Timing
 
-One `RequestTimingSample` is delivered per completed request, success or
-error, to whatever implements `ITimingSink`:
+One `RequestTimingSample` is delivered to whatever implements `ITimingSink` for
+**every request the server closes** — not only the ones a handler answered:
 
 ```typescript
 export interface RequestTimingSample {
@@ -366,6 +457,59 @@ export interface RequestTimingSample {
 }
 ```
 
+### Rejected requests are counted too
+
+The recorder is middleware (`BymaxTimingMiddleware`), applied to every route by
+`BymaxCoreModule` when `timing.enabled` is `true`. That placement is the whole
+point. Nest runs **middleware → guards → interceptors → pipes → handler**, so a
+request rejected by a guard never reaches an interceptor, and a request matching
+no route never reaches a controller. A recorder sitting in either place is blind
+to exactly the traffic that matters during an incident:
+
+| What happens                   | Status | Visible to an interceptor | Visible here |
+| ------------------------------ | ------ | ------------------------- | ------------ |
+| Handler answers                | `2xx`  | ✅                        | ✅           |
+| Authentication guard rejects   | `401`  | ❌                        | ✅           |
+| Authorization guard rejects    | `403`  | ❌                        | ✅           |
+| Rate limiter sheds the request | `429`  | ❌                        | ✅           |
+| No route matches               | `404`  | ❌                        | ✅           |
+| Client hangs up mid-request    | —      | ❌                        | ✅           |
+
+A credential-stuffing run is a flood of `401`s, route enumeration is a flood of
+`404`s, and a throttler doing its job is a flood of `429`s. All three used to
+leave the error graph flat.
+
+Requests that matched no route are recorded under the fixed label
+`UNMATCHED_ROUTE` (`<unmatched>`), never the path that was requested. The raw
+path is attacker-controlled, and a metrics label that follows it lets anyone
+mint one time series per probe until the process runs out of memory.
+
+The sample is emitted when the connection closes, so a client that hangs up
+before the response finishes is still counted — that is what a scanner does, and
+`durationMs` covers guards and middleware as well as the handler.
+
+An aborted request keeps whatever status the response held, which is `200` in
+Node unless something settled another one. No sentinel status is introduced:
+that would change the value of `status_code="200"` series that already exist in
+your dashboards, without any change in traffic.
+
+**Express and Fastify behave identically here**, and that is asserted end to
+end on both. It needs saying because the two platforms disagree underneath: Nest
+runs middleware on Fastify through `@fastify/middie`, which hands it the raw
+`IncomingMessage` carrying no route metadata, and `forRoutes('/')` is a mount on
+Express but an exact match on Fastify. The module resolves both for you.
+
+> **One gap remains, and it is Nest's scoping rule, not a setting.** Module
+> middleware is scoped to the global prefix, so with `setGlobalPrefix('api')` a
+> request to `/nope` — outside the prefix entirely — reaches no middleware and
+> is not recorded. Requests to `/api/nope` are recorded normally, under
+> `<unmatched>`, so a scan that probes below your prefix is still visible; only
+> one that probes above it is not. Covering that too is not supported yet: the
+> module has no way to register the recorder outside its own scope, and
+> `BymaxTimingMiddleware` is only provided when `timing` is enabled — at which
+> point the module already applies it, so resolving and re-registering it would
+> double-count. If you need it, open an issue rather than wiring it by hand.
+
 Bind your own sink by providing `BYMAX_TIMING_SINK` from your own module, the
 same override pattern shown below for the correlation provider. This applies on
 the `forRoot` path; on `forRootAsync` the module owns `BYMAX_TIMING_SINK` (the
@@ -627,6 +771,28 @@ conventions are part of the contract:
 - Keep labels bounded. Route templates, never raw paths; status codes, never
   messages. **Never** a tenant, user, or request id — one unbounded label is
   enough to make a scrape endpoint the most expensive route in a service.
+  `tenantId` deserves naming twice: every library in this family is
+  tenant-aware, so it is the first label anyone reaches for and it is unbounded
+  by construction.
+- **Publish the list.** A library that contributes metrics documents them in its
+  own README — name, type, labels. This package deliberately keeps no central
+  catalogue: a list of everyone else's metrics rots the moment a library ships a
+  new one. What it does require is that the list exists somewhere an operator
+  can find it.
+
+**Why these rules live here.** A Prometheus registry is a flat namespace, and
+`prom-client` rejects a duplicate metric name. If two libraries independently
+pick `bymax_operations_total`, the collision surfaces at the **consumer's** boot
+— in an application neither library's CI ever assembles, as a hard failure, in
+front of whoever wired the app. Neither library can test for it. A namespace
+rule is the only thing that prevents it, and it can only be arbitrated by the
+dependency they share, which is this package.
+
+The rules are documentation, not enforcement. This package could inspect the
+registry around each contributor and reject an unprefixed name, but that would
+need a per-contributor prefix on the contract, and it would wrongly reject the
+case that matters most — an **application's own** contributor, which has no
+business being pushed into a `bymax_` namespace.
 
 ## 📘 OpenAPI
 
@@ -683,6 +849,24 @@ 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.
 
+### Testing the enabled path under Jest
+
+`applyBymaxOpenApi` loads `@nestjs/swagger` through a dynamic `import()` — that
+is what keeps the peer optional for everyone who never enables the document —
+and Jest's module registry cannot service a dynamic import without a flag:
+
+```jsonc
+// package.json
+"scripts": {
+  "test:e2e": "NODE_OPTIONS=--experimental-vm-modules jest --config jest.e2e.config.ts"
+}
+```
+
+Without it, only the **enabled** case fails, with `dynamic import callback
+invoked without --experimental-vm-modules`. The disabled and production cases
+never reach the loader and pass either way, which is what makes the omission
+confusing when you meet it.
+
 ### What the library contributes
 
 With `includeCoreSchemas` on, the document carries the contracts this package
@@ -704,6 +888,158 @@ that never enable the feature.
 A contributed entry never overwrites one the document already has: if you
 document your own `BymaxErrorEnvelope`, yours wins.
 
+Contributing the schemas is only half of it — the operations **reference** them,
+which is what a generated client actually reads:
+
+- every operation gains a `default` response pointing at `BymaxErrorEnvelope`,
+  because every error path in this package answers with that envelope. It is
+  attached as `default` rather than guessed per status code: this package knows
+  what an error looks like and does not know which statuses your handler emits.
+  It follows the feature: with `envelope.enabled` off, errors are shaped by Nest
+  or by your own handler, so nothing is documented;
+- the health endpoints gain an explicit `200` pointing at `BymaxHealthResponse`,
+  which this package _does_ know precisely, having registered them itself.
+
+`@nestjs/swagger` emits a placeholder response for every handler — a `200` with
+a description and no content — so "already documented" is judged on whether a
+response declares a **shape**: one carrying `content` — or written as a bare
+`$ref`, which points at a shape declared elsewhere — is yours and is left alone,
+one without either gets filled in while keeping any description you wrote.
+
+Both halves are the same switch. Referencing a schema that was not contributed
+would leave a dangling `$ref`, and a document that resolves nowhere is worse
+than one that says less — so `includeCoreSchemas: false` opts out of both.
+
+### A library can describe its own routes
+
+A library that ships controllers cannot document them itself. Decorating them
+with `@nestjs/swagger` would load that peer in every application importing the
+library, including the ones that never build a document — and a consumer-side
+map keyed by path does not work either, because a library mounted through
+`RouterModule.register` does not know its own final paths: the same route is
+`/auth/login` in one deployment and `/api/v2/identity/login` in another, from one
+build.
+
+So a library marks a provider and returns fragments keyed by **handler
+identity**, which survives every prefix, version and mount point:
+
+```ts
+import { BymaxOpenApiContributor } from '@bymax-one/nest-core/openapi'
+import type { IOpenApiContributor, OpenApiFragment } from '@bymax-one/nest-core/openapi'
+
+@BymaxOpenApiContributor()
+@Injectable()
+export class AuthOpenApi implements IOpenApiContributor {
+  constructor(private readonly options: ResolvedAuthOptions) {}
+
+  contributeOpenApi(): OpenApiFragment {
+    return {
+      // Required, and declared rather than inferred: a fragment crosses a
+      // boundary between independently released packages, where each side
+      // type-checked against its own copy.
+      contractVersion: 1,
+      components: {
+        securitySchemes: {
+          // Derived from resolved options — which is why this cannot be a
+          // static map a consumer writes by hand.
+          authCookie: { type: 'apiKey', in: 'cookie', name: this.options.cookies.accessTokenName },
+          // Declared because the refresh operation below requires it: a
+          // requirement naming an undeclared scheme fails the document build.
+          refreshCookie: {
+            type: 'apiKey',
+            in: 'cookie',
+            name: this.options.cookies.refreshTokenName
+          }
+        }
+      },
+      operations: {
+        'AuthController.login': { security: [] },
+        'AuthController.refresh': { security: [{ refreshCookie: [] }] }
+      }
+    }
+  }
+}
+```
+
+Nothing is wired by the application: enabling the document runs the scan, and a
+library that is never imported contributes nothing.
+
+#### What the merge guarantees
+
+| Rule                  | Behavior                                                                                                                                                                     |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Marked, not shaped    | Only providers carrying the marker are called. A class that merely exposes `contributeOpenApi` is never touched.                                                             |
+| Called once           | While the document is built, after options resolve — so a contributor may derive its contribution from its own configuration.                                                |
+| Stable order          | Contributors run sorted by class name, so two libraries describing the same operation resolve the same way on every boot.                                                    |
+| Data, not mutation    | A contributor returns fragments; this package decides what to write. That is what makes precedence enforceable.                                                              |
+| Named failures        | A marked class that cannot contribute, one that throws, or a fragment addressing a handler the application does not have all fail the document build naming the contributor. |
+| Off with the document | With `openapi.enabled` false, no contributor runs.                                                                                                                           |
+
+**Precedence, weakest first:** what this package infers about its own routes,
+then what a library contributed, then what the consumer configured, and above
+all of them whatever the operation already declared — a decorated handler is the
+consumer speaking directly and is never overwritten. So a deployment can always
+overrule a dependency's description of its own routes through
+`operationSecurity`.
+
+**Operation ids are untouched.** This package installs an operation-id factory
+to learn which handler produced which operation, and delegates the id string —
+to `openapi.operationIdFactory` when you set one, to the format `@nestjs/swagger`
+itself produces otherwise. A client generated from your document before adopting
+this keeps working after.
+
+**The fragment shape is translatable to an OpenAPI Overlay, deliberately.** The
+[Overlay Specification](https://spec.openapis.org/overlay/v1.0.0.html) is the
+OpenAPI Initiative's format for describing changes to a document, and a
+contributor's fragments are that in all but notation: a handler key resolves to
+an operation id, which resolves to a JSONPath target, which is what an overlay
+action addresses. Overlays are not used as the mechanism — their targets are
+paths, which is the one thing a library mounted through `RouterModule.register`
+cannot write, and a JSONPath engine would be a runtime dependency this package
+does not have. But the translation is mechanical, so a tool that emits a
+library's contribution as a standalone overlay can exist the day a pipeline
+wants one. No such tool ships here, and none is promised.
+
+**Deriving the fragments is the library's business, not this package's.** A
+library that wants its schemas to track its own validation decorators should
+generate them in its own build or test suite, where that dependency already
+exists, and commit the result — with a test asserting generated matches
+committed, so drift fails in the repository that caused it. This package takes
+no dependency on any validation library and merges what it is given. An
+application's own DTOs need none of this: `@nestjs/swagger`'s CLI plugin already
+derives them, which is a route a precompiled library does not have.
+
+### The document describes _this_ deployment
+
+A feature you turned off has its routes removed from the document. With
+`metrics: { enabled: false }` the runtime answers `GET /metrics` with a 404
+envelope — on `forRootAsync` the controller is mounted unconditionally and
+guards each request, because route metadata is fixed before the async options
+resolve — so a document still listing the route would describe something this
+deployment does not serve. The filter reads the same resolved snapshot the
+runtime guard reads, which is what keeps the two from drifting.
+
+Your own routes are safe from it. `@nestjs/swagger` documents paths including
+`app.setGlobalPrefix()`, so the match cannot be on equality — but a bare tail
+match would treat `/tenants/{id}/health/live` as this package's probe and delete
+it from your document. What separates the two is that a global prefix prefixes
+_everything_: a tail match counts only when whatever precedes it also precedes
+every other path in the document. `/api/v2` qualifies; `/tenants/{id}` does not,
+because it does not prefix `/invoices`.
+
+This package also documents the security of the three routes it owns, without
+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     |
+
+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.
+
 ## 🧵 Trace correlation
 
 Off by default. Enabled, it reads the span your instrumentation already opened
@@ -778,7 +1114,7 @@ identically.
     │           │               │               │           │
  envelope/    timing/        health/       pagination/   metrics/
     │           │               │               │           │
-APP_FILTER  APP_INTERCEPTOR  liveness +    pure functions  Prometheus
+APP_FILTER  middleware       liveness +    pure functions  Prometheus
     │           │            readiness     on their own    scrape route
     │           │               │           subpath        (opt-in)
     ▼           ▼               ▼               │             │
@@ -813,7 +1149,7 @@ never imported, which is why it can stay an optional peer. The same holds for
 `@nestjs/swagger` and `@opentelemetry/api`: the release gate loads the packed
 tarball and fails if any of the three is reachable with its feature off.
 
-Nothing here holds state across requests. The timing interceptor emits and forgets;
+Nothing here holds state across requests. The timing middleware emits and forgets;
 the health service runs the indicators the app registered and folds their results;
 the pagination helpers are functions of their arguments.
 
@@ -867,6 +1203,26 @@ A slow indicator is converted to `down` by the aggregator rather than hanging th
 and its `timedOutAfterMs` stays in the response either way, because that number is one this
 library chose rather than text an indicator produced.
 
+### A metric an attack cannot be seen in is not a control
+
+Request timing is counted as a security signal, not a performance one. A
+credential-stuffing run is a flood of `401`s, a privilege probe a flood of
+`403`s, route enumeration a flood of `404`s, and a rate limiter doing its job a
+flood of `429`s. None of those reaches a handler, so a recorder placed after the
+guards sees none of them — and an operator watching a flat error graph concludes
+nothing is happening. The recorder is middleware for that reason, and every
+closed request is counted whatever ended it.
+
+### A route label is attacker-controlled input
+
+The label on a timing sample comes from the matched route **template**, and a
+request that matched nothing is recorded under the single constant
+`UNMATCHED_ROUTE` (`<unmatched>`) rather than the path that was asked for.
+Following the path would let anyone mint one Prometheus time series per probe:
+a scan would grow the registry without bound, make the scrape endpoint the most
+expensive route in the service, and end as an out-of-memory kill. The bound is
+why the unmatched case is a fixed string and not a fallback to the URL.
+
 ### Cursors are opaque, not secret
 
 `encodeCursor` produces a token a client can round-trip; it is not encrypted and not
@@ -898,6 +1254,8 @@ most likely to be exposed.
 | Health output       | The response names which indicator is down and nothing more; the reason goes to the logger. `exposeIndicatorErrors` (default `false`) puts it back in the response for debugging |
 | Slow indicators     | Converted to `down` by the aggregator, so a probe cannot hang on one                                                                                                             |
 | Correlation         | Resolved through `BYMAX_CORRELATION_PROVIDER` — the app decides where the id comes from                                                                                          |
+| Request accounting  | Every closed request is counted, including the ones a guard rejected (`401`/`403`/`429`) and the ones that matched no route (`404`), so an attack in progress moves the graph    |
+| Route labels        | Taken from the matched template; an unmatched request records the constant `<unmatched>`, never the requested path, so a scan cannot grow the metric registry without bound      |
 | Pagination cursors  | Opaque, not authenticated; treated as client-supplied input on the way back in                                                                                                   |
 | Metrics             | Opt-in; `prom-client` never imported while it is off                                                                                                                             |
 | OpenAPI             | Opt-in and development-only; refused in production by two independent guards, `@nestjs/swagger` never imported while it is off                                                   |
@@ -916,13 +1274,13 @@ most likely to be exposed.
 ## 🧱 Tech Stack
 
 - **Runtime:** Node.js 24+
-- **Framework:** NestJS 11 (`ConfigurableModuleBuilder`, `APP_FILTER`, `APP_INTERCEPTOR`)
+- **Framework:** NestJS 11 (`ConfigurableModuleBuilder`, `APP_FILTER`, `NestModule.configure`)
 - **Peers:** `@nestjs/common ^11`, `@nestjs/core ^11`, `rxjs ^7`, `reflect-metadata ^0.2`
 - **Optional peers:** `prom-client ^15` when metrics are enabled, `@nestjs/swagger ^11` when
   OpenAPI is enabled, `@opentelemetry/api ^1.9` when trace correlation is enabled — none is
   imported while its feature is off
 - **Build:** tsup — ESM + CJS per subpath, with `.d.ts` _and_ `.d.cts` declarations
-- **Tests:** Jest (unit + e2e over a real Nest application) + Stryker (mutation)
+- **Tests:** Jest (unit + e2e over real Nest applications, Express **and** Fastify) + Stryker (mutation)
 - **TypeScript:** 5.x strict (`noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`), zero `any`
 
 ---
@@ -937,9 +1295,11 @@ installs it, so the suite is held to a bar beyond "the tests pass".
   `break: 95`; every killable survivor was killed by a strengthened test, with no production
   change, and the nine equivalents that no test can kill each carry their reason on the line
   they apply to ([report](./docs/mutation_testing_results.md))
-- ✅ **End-to-end against a real application** — the filter, the interceptor, the health and
-  metrics routes, the served OpenAPI document, discovered indicators, contributed metrics and
-  trace correlation are all exercised through a booted Nest app, not against mocks of it
+- ✅ **End-to-end against real applications, on both platforms** — the filter, the middleware,
+  the health and metrics routes, the served OpenAPI document, discovered indicators,
+  contributed metrics and trace correlation are all exercised through a booted Nest app, not
+  against mocks of it. Timing is asserted on **Express and Fastify**, because the two differ
+  underneath in ways that make a passing Express suite say nothing about Fastify
 - ✅ **Published-artifact gates** — `check:exports` resolves the types the way each module
   system does, `check:runtime` loads every subpath from the packed tarball in ESM and
   CommonJS, and `check:published` compiles this README's snippets against `dist/`
@@ -951,7 +1311,7 @@ installs it, so the suite is held to a bar beyond "the tests pass".
 ```bash
 pnpm test          # unit suite
 pnpm test:cov      # unit suite with the 100% coverage gate
-pnpm test:e2e      # end-to-end against a real Nest application
+pnpm test:e2e      # end-to-end against real Nest applications (Express and Fastify)
 pnpm mutation      # Stryker mutation testing (break: 95)
 pnpm typecheck     # tsc strict check
 pnpm lint          # ESLint
@@ -966,21 +1326,25 @@ in the sections above.
 
 ### `.` (root)
 
-| Export                                                                                                                                                                                                           | Kind      | Description                                                            |
-| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------- |
-| `BymaxCoreModule`                                                                                                                                                                                                | class     | The dynamic module: `forRoot` and `forRootAsync`.                      |
-| `BymaxCoreModuleOptions`, `EnvelopeOptions`, `TimingOptions`, `HealthOptions`, `MetricsOptions`, `TelemetryOptions`, `OpenApiOptions`, `OpenApiServerDescriptor`, `OpenApiSecurityScheme`, `ResolvedCoreOptions` | types     | The options surface and its resolved shape.                            |
-| `BYMAX_CORE_OPTIONS`, `BYMAX_CORRELATION_PROVIDER`, `BYMAX_TIMING_SINK`, `BYMAX_HEALTH_INDICATORS`, `BYMAX_METRICS_REGISTRY`                                                                                     | tokens    | The DI tokens; see the [token table](#-di-tokens).                     |
-| `ICorrelationIdProvider`                                                                                                                                                                                         | type      | The correlation-provider contract.                                     |
-| `ITraceContextProvider`, `TraceContext`                                                                                                                                                                          | types     | The trace-context contract and the identifiers it resolves.            |
-| `BymaxExceptionFilter`                                                                                                                                                                                           | class     | The envelope exception filter.                                         |
-| `FilterErrorContext`                                                                                                                                                                                             | type      | The neutral request context passed to the filter's observability seam. |
-| `buildErrorEnvelope`                                                                                                                                                                                             | function  | Pure builder assembling an `ErrorEnvelope`.                            |
-| `ErrorEnvelope`, `ErrorDetails`, `BuildErrorEnvelopeInput`                                                                                                                                                       | types     | The envelope contract and its builder input.                           |
-| `TimingInterceptor`                                                                                                                                                                                              | class     | The request-timing interceptor.                                        |
-| `ITimingSink`, `RequestTimingSample`                                                                                                                                                                             | types     | The timing-sink contract and its sample shape.                         |
-| `BYMAX_BAD_GATEWAY` … `BYMAX_VALIDATION_FAILED`                                                                                                                                                                  | constants | The full error-code catalog (see [Error envelope](#-error-envelope)).  |
-| `codeForStatus`                                                                                                                                                                                                  | function  | Derives a catalog code from an HTTP status.                            |
+| Export                                                                                                                                                                                                           | Kind      | Description                                                                        |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------- |
+| `BymaxCoreModule`                                                                                                                                                                                                | class     | The dynamic module: `forRoot` and `forRootAsync`.                                  |
+| `BymaxCoreModuleOptions`, `EnvelopeOptions`, `TimingOptions`, `HealthOptions`, `MetricsOptions`, `TelemetryOptions`, `OpenApiOptions`, `OpenApiServerDescriptor`, `OpenApiSecurityScheme`, `ResolvedCoreOptions` | types     | The options surface and its resolved shape.                                        |
+| `OpenApiSecurityRequirement`, `OpenApiHttpMethod`, `OpenApiOperationKey`, `OperationSecurityMap`                                                                                                                 | types     | The operation-key contract a sibling library targets to ship its own security map. |
+| `OpenApiOperationIdFactory`                                                                                                                                                                                      | type      | Names the operations in the generated document.                                    |
+| `BYMAX_CORE_OPTIONS`, `BYMAX_CORRELATION_PROVIDER`, `BYMAX_TIMING_SINK`, `BYMAX_HEALTH_INDICATORS`, `BYMAX_METRICS_REGISTRY`                                                                                     | tokens    | The DI tokens; see the [token table](#-di-tokens).                                 |
+| `ICorrelationIdProvider`                                                                                                                                                                                         | type      | The correlation-provider contract.                                                 |
+| `ITraceContextProvider`, `TraceContext`                                                                                                                                                                          | types     | The trace-context contract and the identifiers it resolves.                        |
+| `BymaxExceptionFilter`                                                                                                                                                                                           | class     | The envelope exception filter.                                                     |
+| `FilterErrorContext`                                                                                                                                                                                             | type      | The neutral request context passed to the filter's observability seam.             |
+| `buildErrorEnvelope`                                                                                                                                                                                             | function  | Pure builder assembling an `ErrorEnvelope`.                                        |
+| `ErrorEnvelope`, `ErrorDetails`, `BuildErrorEnvelopeInput`                                                                                                                                                       | types     | The envelope contract and its builder input.                                       |
+| `BymaxTimingMiddleware`                                                                                                                                                                                          | class     | The request-timing middleware, applied to every route when timing is enabled.      |
+| `UNMATCHED_ROUTE`                                                                                                                                                                                                | constant  | The bounded label recorded when a request matched no route (`<unmatched>`).        |
+| `TimingInterceptor`                                                                                                                                                                                              | class     | Deprecated: superseded by `BymaxTimingMiddleware`, which the module registers.     |
+| `ITimingSink`, `RequestTimingSample`                                                                                                                                                                             | types     | The timing-sink contract and its sample shape.                                     |
+| `BYMAX_BAD_GATEWAY` … `BYMAX_VALIDATION_FAILED`                                                                                                                                                                  | constants | The full error-code catalog (see [Error envelope](#-error-envelope)).              |
+| `codeForStatus`                                                                                                                                                                                                  | function  | Derives a catalog code from an HTTP status.                                        |
 
 ### `./pagination`
 
@@ -1013,20 +1377,26 @@ in the sections above.
 
 ### `./openapi`
 
-| Export                | Kind     | Description                                                       |
-| --------------------- | -------- | ----------------------------------------------------------------- |
-| `applyBymaxOpenApi`   | function | Builds and mounts the document; call it before `app.listen()`.    |
-| `OpenApiMountOutcome` | type     | What the helper did: mounted at a path, or skipped with a reason. |
-| `OpenApiSkipReason`   | type     | Why it was skipped: `'disabled'` or `'production'`.               |
+| Export                                                                                 | Kind                | Description                                                                    |
+| -------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------ |
+| `applyBymaxOpenApi`                                                                    | function            | Builds and mounts the document; call it before `app.listen()`.                 |
+| `OpenApiMountOutcome`                                                                  | type                | What the helper did: mounted at a path, or skipped with a reason.              |
+| `OpenApiSkipReason`                                                                    | type                | Why it was skipped: `'disabled'` or `'production'`.                            |
+| `BymaxOpenApiContributor`, `BYMAX_OPENAPI_CONTRIBUTOR_METADATA`                        | decorator, constant | Marks a provider as describing its own routes, and the metadata key behind it. |
+| `IOpenApiContributor`, `OpenApiFragment`, `OpenApiFragmentObject`, `OpenApiHandlerKey` | types               | The contributor contract and the shape of what it returns.                     |
 
 ## 🧩 Compatibility
 
 - Node.js `>= 24`
 - NestJS `^11`
-- Express and Fastify, through framework-agnostic accessors for path, method,
-  and status. GraphQL and RPC execution contexts are out of scope for the
-  error envelope and the timing interceptor in this release; both pass errors
-  and requests through untouched.
+- Express and Fastify, both covered end to end. The accessors are
+  framework-agnostic for path, method and status, and the module absorbs the
+  two places the platforms genuinely differ: the route mount, and the fact that
+  Nest runs middleware on Fastify through `@fastify/middie`, which strips the
+  route metadata off the object the middleware receives.
+- GraphQL and RPC execution contexts are out of scope for the error envelope and
+  the request timing in this release; both pass errors and requests through
+  untouched.
 
 ## 🤝 Contributing