@bymax-one/nest-core 1.3.1 → 1.3.2

package/CHANGELOG.md

@@ -11,6 +11,115 @@ heading here.
 
 ## [Unreleased]
 
+## [1.3.2] - 2026-08-11
+
+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
+were still listed, the contributed schemas were never referenced by any
+operation, and nothing said which operations needed authentication. Everything
+below is additive — no option changes meaning, no existing document loses an
+entry it had.
+
+**Apply to a derived backend:** bump the dependency. The document improves with
+no code change; the two new options are opt-in.
+
+### Added
+
+- **`openapi.security` and `openapi.operationSecurity`.** A document-level
+  default requirement, plus per-operation overrides keyed `"<METHOD> <path>"`.
+  An empty array marks an operation public, which is the specification's own way
+  of overriding the default — and it matters for generated clients, since an
+  operation with _absent_ security inherits the document default and a client
+  would attach credentials to a public registration endpoint.
+- **The operation key is a documented contract**, with `OpenApiOperationKey` and
+  `OperationSecurityMap` exported as types so a sibling library can ship a
+  plain-data map of its own operations and have it checked at its own compile
+  time, with no runtime coupling. The path is written exactly as documented,
+  **including any global prefix** — `@nestjs/swagger` puts `setGlobalPrefix` into
+  the documented paths, so a library shipping such a map should expose a function
+  taking the prefix rather than a frozen constant.
+- **A key addressing no operation fails the document build**, listing both the
+  keys that missed and the operations that exist. A stale key would otherwise
+  leave a route silently documented as authenticated when it is not, or the
+  reverse. Failing is safe here: the document is only ever built outside
+  production.
+- **A requirement naming an undeclared security scheme fails the same way.** A
+  requirement is a reference, and a reference to nothing produces a document
+  whose security cannot be resolved — a client generator looks the name up in
+  `components.securitySchemes`, finds nothing, and either fails or emits an
+  unauthenticated client. Configuring the requirement and forgetting the scheme
+  is one edit apart. A scheme the document itself declares counts as declared,
+  and marking an operation public names no scheme, so it needs none.
+
+### Fixed
+
+- **A disabled feature's routes are no longer documented.** 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 — while the document still advertised it. The filter reads the same
+  resolved snapshot the guard reads, so the two cannot drift. `@nestjs/swagger`
+  documents paths as the application serves them — the global prefix, and under
+  `enableVersioning({ type: URI })` the version segment that follows it, so
+  `/api/v1/metrics` — and both are **read from the application** rather than
+  inferred from the document. Versioning matters as much as the prefix: without
+  it, every versioned application kept advertising the routes of a feature it
+  had switched off, and its health probes lost the payload schema and the public
+  marking this package contributes. Inference is the trap: an application whose routes all sit under one
+  controller prefix would have that treated as the global one, and a consumer
+  route ending in `/health/live` deleted as though this package owned it. What
+  leaves is also the **operation**, not the path item — a method the consumer
+  mounted on the same path survives, and the path disappears only once nothing
+  is left under it.
+- **The automatic security policy is stated for `GET` alone.** These controllers
+  expose no other method, so a consumer's `POST` on the same path is theirs and
+  no longer inherits a requirement written for ours.
+- **The envelope response follows the envelope feature.** With
+  `envelope.enabled` off, errors are shaped by Nest or by the consumer's own
+  handler, so documenting this package's envelope described a body the
+  deployment never sends. The health response is a separate feature and is
+  unaffected.
+- **A response written as a bare `$ref` is a declaration.** It carries no
+  `content`, so the placeholder rule would have overwritten it — discarding the
+  reference and leaving `$ref` beside sibling keys, which is not a valid
+  response object.
+- **`BymaxMetricsAuth` is reserved while a scrape token is configured.** The
+  name was silently overwritten or silently lost depending on where the other
+  definition came from, and the losing case left the scrape operation pointing
+  at a scheme that is not the bearer token the runtime checks. It now fails the
+  document build with the collision named.
+- **The contributed schemas are referenced by the operations that return them.**
+  They shipped orphaned: `components.schemas` carried the envelope, the health
+  response and the pagination shapes while no operation pointed at any of them,
+  so a generated client had no error type at all. Every operation now carries a
+  `default` response referencing `BymaxErrorEnvelope`, and the health endpoints
+  an explicit `200` referencing `BymaxHealthResponse`. Gated by
+  `includeCoreSchemas`, because referencing a schema that was not contributed
+  would leave a dangling `$ref`.
+- **A response is judged by whether it declares a shape.** `@nestjs/swagger`
+  emits a placeholder `200` with a description and no content for every handler,
+  so a plain "existing always wins" rule would never have written a contributed
+  schema. A response carrying `content` is a real declaration and is untouched;
+  one without it is filled in, keeping any description already written.
+- **The library documents the security of its own three routes.** The health
+  probes are marked public — an orchestrator polls them holding no credential —
+  and the scrape endpoint carries a bearer requirement, with its scheme, exactly
+  when `metrics.authToken` is set. The library owns both the routes and the
+  option, so no consumer should have to restate either.
+
+### Documentation
+
+- The metrics naming rules are framed as an adoption guideline for sibling
+  libraries, with the reason the rules live here: a Prometheus registry is a flat
+  namespace, so two libraries picking the same metric name collide at the
+  _consumer's_ boot, in an application neither library's CI ever assembles. A
+  contributing library is asked to publish its own metric list; this package
+  deliberately keeps no central catalogue.
+- `applyBymaxOpenApi` documents that testing its enabled path under Jest needs
+  `NODE_OPTIONS=--experimental-vm-modules`, because the optional peer is reached
+  through a dynamic `import()`. Only the enabled case fails without it, which is
+  what makes the omission confusing.
+
 ## [1.3.1] - 2026-08-11
 
 A patch fixing a defect that existed only in the published artifact: `applyBymaxOpenApi` threw on
@@ -394,9 +503,10 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.0.1]: https://github.com/bymaxone/nest-core/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/bymaxone/nest-core/releases/tag/v1.0.0
 [1.1.1]: https://github.com/bymaxone/nest-core/compare/v1.1.0...v1.1.1
+[1.3.2]: https://github.com/bymaxone/nest-core/compare/v1.3.1...v1.3.2
 [1.3.1]: https://github.com/bymaxone/nest-core/compare/v1.3.0...v1.3.1
 [1.3.0]: https://github.com/bymaxone/nest-core/compare/v1.2.2...v1.3.0
 [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.1...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.3.2...HEAD

package/README.md

@@ -282,12 +282,102 @@ BymaxCoreModule.forRoot({
 | `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.         |
+| `security`           | `SecurityRequirement[]`   | `[]`          | The requirement every operation carries unless it says otherwise.              |
+| `operationSecurity`  | `OperationSecurityMap`    | `{}`          | Per-operation overrides. An empty array marks that operation public.           |
+| `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
@@ -627,6 +717,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 +795,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 +834,59 @@ 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.
+
+### 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
@@ -966,21 +1149,22 @@ 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. |
+| `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.                                        |
 
 ### `./pagination`
 

package/dist/index.cjs

@@ -17,6 +17,10 @@ var __decorateClass = (decorators, target, key, kind) => {
 };
 var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
 
+// src/route-defaults.ts
+var DEFAULT_HEALTH_PATH = "health";
+var DEFAULT_METRICS_PATH = "metrics";
+
 // src/runtime.environment.ts
 var NON_PRODUCTION_ENVIRONMENTS = /* @__PURE__ */ new Set(["development", "test"]);
 function isProductionRuntime(value = process.env["NODE_ENV"]) {
@@ -27,9 +31,7 @@ function isProductionRuntime(value = process.env["NODE_ENV"]) {
 }
 
 // src/core.options.ts
-var DEFAULT_HEALTH_PATH = "health";
 var DEFAULT_INDICATOR_TIMEOUT_MS = 5e3;
-var DEFAULT_METRICS_PATH = "metrics";
 var DEFAULT_OPENAPI_PATH = "docs";
 var DEFAULT_OPENAPI_JSON_PATH = "docs-json";
 var DEFAULT_OPENAPI_TITLE = "API";
@@ -105,6 +107,11 @@ function resolveOpenApi(raw) {
     // consumer-owned nested objects, and the deep-freeze below would otherwise
     // reach into them.
     securitySchemes: structuredClone(raw?.securitySchemes ?? {}),
+    // Cloned for the same reason as the schemes above: both are consumer-owned
+    // nested structures, and the deep-freeze applied to the snapshot would
+    // otherwise reach into objects the consumer still holds a reference to.
+    security: structuredClone(raw?.security ?? []),
+    operationSecurity: structuredClone(raw?.operationSecurity ?? {}),
     includeCoreSchemas: raw?.includeCoreSchemas ?? true
   };
 }

package/dist/index.d.cts

@@ -68,6 +68,44 @@ interface OpenApiServerDescriptor {
  * so the consumer's declaration reaches the UI unchanged.
  */
 type OpenApiSecurityScheme = Readonly<Record<string, unknown>>;
+/**
+ * One security requirement: scheme name to the scopes it needs, empty for a
+ * scheme that takes none. An operation's requirements are alternatives — any
+ * one of them satisfies it — so an empty *array* of requirements means the
+ * operation needs no authentication at all, which is how the specification
+ * expresses a public route that overrides a document-level default.
+ */
+type OpenApiSecurityRequirement = Readonly<Record<string, readonly string[]>>;
+/** The HTTP methods an OpenAPI path item can carry an operation under. */
+type OpenApiHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE';
+/**
+ * Addresses one operation in the generated document, as `"<METHOD> <path>"`.
+ *
+ * This format is a documented contract, not an implementation detail: a sibling
+ * library may ship a plain-data map of its own operations keyed this way, so a
+ * consumer spreads it into {@link OpenApiOptions.operationSecurity} instead of
+ * restating which of that library's routes are public. Import the type to get
+ * that map checked at the library's own compile time.
+ *
+ * The method is uppercase, one space separates the two parts, and 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 the application sets. That last part is the one that surprises:
+ * `@nestjs/swagger` includes `app.setGlobalPrefix('api')` in the documented
+ * paths, so the key is `'POST /api/auth/login'` in an application that sets one.
+ * A library shipping such a map should therefore expose a *function* taking the
+ * prefix rather than a frozen constant — the call site is the only place that
+ * knows it.
+ *
+ * @example 'GET /users/{id}'
+ * @example 'POST /api/auth/login'
+ */
+type OpenApiOperationKey = `${OpenApiHttpMethod} /${string}`;
+/**
+ * Per-operation security requirements, keyed by {@link OpenApiOperationKey}.
+ * An empty array marks the operation public, overriding any document default.
+ */
+type OperationSecurityMap = Readonly<Record<OpenApiOperationKey, readonly OpenApiSecurityRequirement[]>>;
 /**
  * OpenAPI document configuration.
  *
@@ -96,10 +134,53 @@ interface OpenApiOptions {
     servers?: readonly OpenApiServerDescriptor[];
     /** Security schemes added to the document's components. Default: `{}`. */
     securitySchemes?: Readonly<Record<string, OpenApiSecurityScheme>>;
+    /**
+     * The requirement every operation carries unless it says otherwise, naming
+     * schemes declared in {@link OpenApiOptions.securitySchemes}. Default: `[]`,
+     * which documents nothing and leaves every operation as it was generated.
+     *
+     * Set this when most of the API is authenticated, and mark the exceptions
+     * public through {@link OpenApiOptions.operationSecurity}. An operation that
+     * already declares its own requirement is never overwritten.
+     *
+     * @example [{ cookieAuth: [] }]
+     */
+    security?: readonly OpenApiSecurityRequirement[];
+    /**
+     * Per-operation overrides of {@link OpenApiOptions.security}, keyed by
+     * {@link OpenApiOperationKey}. An empty array marks that operation public.
+     * Default: `{}`.
+     *
+     * A key matching no operation in the generated document is a configuration
+     * error and fails the document build, naming the keys that do 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.
+     *
+     * That check runs only when the document is built. With
+     * {@link OpenApiOptions.enabled} false, or in a production runtime where the
+     * feature is forced off, a stale key is not reported — refusing to boot a
+     * service over a documentation setting it never serves would be the wrong
+     * trade. The cost is that the error waits for an environment that has the
+     * document switched on.
+     *
+     * @example
+     *   {
+     *     'POST /auth/login': [],
+     *     'POST /auth/refresh': [{ refreshCookie: [] }]
+     *   }
+     */
+    operationSecurity?: OperationSecurityMap;
     /**
      * Contribute the schemas this package owns — the error envelope, the health
-     * response, and the pagination shapes — to the document's components.
-     * Default: `true`.
+     * response, and the pagination shapes — to the document's components, and
+     * reference them from the operations that return them: the error envelope as
+     * every operation's `default` response, and the health response on the health
+     * endpoints this package registers. Default: `true`.
+     *
+     * The two halves are one switch because they are one decision. Referencing a
+     * schema this package did not contribute would leave a dangling `$ref`, and a
+     * document that resolves nowhere is worse than one that says less.
      */
     includeCoreSchemas?: boolean;
 }
@@ -221,6 +302,8 @@ interface ResolvedOpenApiOptions {
     version: string;
     servers: readonly OpenApiServerDescriptor[];
     securitySchemes: Readonly<Record<string, OpenApiSecurityScheme>>;
+    security: readonly OpenApiSecurityRequirement[];
+    operationSecurity: OperationSecurityMap;
     includeCoreSchemas: boolean;
 }
 /**
@@ -824,4 +907,4 @@ declare const BYMAX_GATEWAY_TIMEOUT = "BYMAX_GATEWAY_TIMEOUT";
  */
 declare function codeForStatus(status: number): string;
 
-export { BYMAX_BAD_GATEWAY, BYMAX_BAD_REQUEST, BYMAX_CLIENT_ERROR, BYMAX_CONFLICT, BYMAX_CORE_OPTIONS, BYMAX_CORRELATION_PROVIDER, BYMAX_FORBIDDEN, BYMAX_GATEWAY_TIMEOUT, BYMAX_HEALTH_INDICATORS, BYMAX_INTERNAL_ERROR, BYMAX_METRICS_REGISTRY, BYMAX_NOT_FOUND, BYMAX_NOT_IMPLEMENTED, BYMAX_PAYLOAD_TOO_LARGE, BYMAX_SERVICE_UNAVAILABLE, BYMAX_TIMING_SINK, BYMAX_TOO_MANY_REQUESTS, BYMAX_TRACE_CONTEXT, BYMAX_UNAUTHORIZED, BYMAX_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, type BuildErrorEnvelopeInput, BymaxCoreModule, type BymaxCoreModuleOptions, BymaxExceptionFilter, type EnvelopeOptions, type ErrorDetails, type ErrorEnvelope, type FilterErrorContext, type HealthOptions, type ICorrelationIdProvider, type ITimingSink, type ITraceContextProvider, type MetricsOptions, type OpenApiOptions, type OpenApiSecurityScheme, type OpenApiServerDescriptor, type RequestTimingSample, type ResolvedCoreOptions, type TelemetryOptions, TimingInterceptor, type TimingOptions, type TraceContext, buildErrorEnvelope, codeForStatus };
+export { BYMAX_BAD_GATEWAY, BYMAX_BAD_REQUEST, BYMAX_CLIENT_ERROR, BYMAX_CONFLICT, BYMAX_CORE_OPTIONS, BYMAX_CORRELATION_PROVIDER, BYMAX_FORBIDDEN, BYMAX_GATEWAY_TIMEOUT, BYMAX_HEALTH_INDICATORS, BYMAX_INTERNAL_ERROR, BYMAX_METRICS_REGISTRY, BYMAX_NOT_FOUND, BYMAX_NOT_IMPLEMENTED, BYMAX_PAYLOAD_TOO_LARGE, BYMAX_SERVICE_UNAVAILABLE, BYMAX_TIMING_SINK, BYMAX_TOO_MANY_REQUESTS, BYMAX_TRACE_CONTEXT, BYMAX_UNAUTHORIZED, BYMAX_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, type BuildErrorEnvelopeInput, BymaxCoreModule, type BymaxCoreModuleOptions, BymaxExceptionFilter, type EnvelopeOptions, type ErrorDetails, type ErrorEnvelope, type FilterErrorContext, type HealthOptions, type ICorrelationIdProvider, type ITimingSink, type ITraceContextProvider, type MetricsOptions, type OpenApiHttpMethod, type OpenApiOperationKey, type OpenApiOptions, type OpenApiSecurityRequirement, type OpenApiSecurityScheme, type OpenApiServerDescriptor, type OperationSecurityMap, type RequestTimingSample, type ResolvedCoreOptions, type TelemetryOptions, TimingInterceptor, type TimingOptions, type TraceContext, buildErrorEnvelope, codeForStatus };