@lenne.tech/nest-server 11.42.7 → 11.42.9

package/docs/REQUEST-LIFECYCLE.md

@@ -157,6 +157,7 @@ JWT-based authentication for existing projects:
 | `@CommonError(code)` | Error code registration |
 | `@SkipTenantCheck()` | Opt out of CoreTenantGuard validation on a method (not for tenant-restricted API tokens — they stay bound) |
 | `@ApiTokenScopes(...scopes)` | Open a route/class to API tokens holding one of the scopes; tokens are denied everywhere else |
+| `@ApiMethods(...methods)` | Swagger only (11.42.9): the HTTP methods an `@All()` handler actually serves — `setupSwagger()` documents those instead of all eight. No runtime effect |
 
 ### File Handling
 
@@ -166,7 +167,7 @@ JWT-based authentication for existing projects:
 | **REST Endpoints** | `GET /files/id/:id`, `GET /files/:filename` (core, gated by `file.downloadRoles`, default ADMIN); `POST /files/upload`, `DELETE /files/:id` (project-specific) |
 | **GraphQL Endpoints** | `getFileInfo` (`file.downloadRoles`), `uploadFile` / `uploadFiles` (`file.uploadRoles`), `deleteFile` (`file.deleteRoles`) — all default ADMIN |
 | **File access control** | Roles are the coarse filter; per-file rules go in `CoreFileService.checkRights()` using metadata written at upload time. Cover BOTH the `id` and the `filename` branch — the filename route authorizes on the by-name lookup alone when presigned S3 downloads are on, and `deleteFileByName()` always does. Working reference: `src/server/modules/file/file.service.ts` (with `file.downloadRoles: [S_USER]` in `src/config.env.ts`, so the rule is actually reached). Both file classes carry `@SkipTenantCheck()` — GridFS is not tenant-scoped |
-| **TUS Module** | Resumable uploads via tus.io protocol (creation, termination, expiration), gated by `tus.roles` (default `S_USER`); `OPTIONS` stays public for the CORS preflight. Records owner and, with `multiTenancy` only, the validated tenant at upload creation; a custom service plugs in via `TusModule.forRoot({ service })` |
+| **TUS Module** | Resumable uploads via tus.io protocol (creation, termination, expiration), gated by `tus.roles` (default `S_USER`); `OPTIONS` stays public for the CORS preflight. Records owner and, with `multiTenancy` only, the validated tenant at upload creation; a custom service plugs in via `TusModule.forRoot({ service })`. Configured by `TusModule.forRoot({ config })`, else the server config's `tus` key (11.42.9+). Switched-off `creation` / `termination` answer 501 (enforced by `CoreTusService`, not `@tus/server`); upload URLs follow the path the upload was created at |
 | **GridFS Migration** | Completed TUS uploads auto-migrate to GridFS |
 | **CORS Support** | Automatic CORS headers for browser uploads |
 
@@ -636,6 +637,13 @@ If authentication succeeds, `req.user` is set with the authenticated user (inclu
 > raw-forwarded routes. A forged `POST /iam/update-user {"roles":["admin"]}` is rejected with
 > `FIELD_NOT_ALLOWED` (HTTP 400) at the input-parse stage, before any persistence.
 
+> **Never routed: `/iam/open-api/*` (11.42.9).** nest-server registers Better-Auth's `openAPI()` plugin
+> only so `setupSwagger()` can document Better-Auth's own routes, and marks its endpoints `SERVER_ONLY`:
+> better-call leaves them out of the router, so a forwarded request answers 404 however its path is
+> spelled, while the generator still runs in-process. Deliberately not a path check in the middleware —
+> it would see the path as sent, Better-Auth the one `new URL()` produced (`/iam/./open-api/…`). Only a
+> project that registered `openAPI()` itself in `betterAuth.plugins` gets the routes.
+
 > **"Raw" has one exception since 11.38.0: the password-setting reset routes.**
 > `CoreBetterAuthApiMiddleware.normalizeResetPassword()` rewrites the password field of
 > `/reset-password`, `/email-otp/reset-password` and `/phone-number/reset-password` to its

package/migration-guides/11.42.7-to-11.42.8.md

@@ -0,0 +1,74 @@
+# Migration Guide: 11.42.7 → 11.42.8
+
+## Overview
+
+| Category             | Details                                                                                              |
+| -------------------- | ---------------------------------------------------------------------------------------------------- |
+| **Bugfix**           | `setupSwagger()` enriches every operation an `@All()` route produces, including `SEARCH` (§1)        |
+| **Bugfix**           | The Better-Auth pass-through route no longer appears as `/iam/{path}` in the Swagger document (§2)   |
+| **Dependencies**     | dev: `vite` 8.3.3; override `js-yaml` 5.4.3 (§3)                                                     |
+| **Breaking Changes** | None                                                                                                 |
+| **Migration Effort** | None for most projects. Regenerate a client built from `/api-docs-json` if you keep one (§2)         |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick it up with the core update.
+
+## 1. `SEARCH` operations of `@All()` routes are enriched
+
+For an `@All()` route, `@nestjs/swagger` documents one operation per HTTP method — including
+`SEARCH`, which no OpenAPI version lists as a path-item method. 11.42.7 walked a fixed list of
+methods and skipped it, so that one operation stayed as Swagger built it: no API-token scope line,
+no `security: []` on a public route, no tenant header, and `operationTags` did not reach it — it
+landed in its own tag group next to the regrouped siblings.
+
+The helper now reads the operations from the path item itself, so `SEARCH` (and any other method
+`@nestjs/swagger` emits) is treated like every other operation — in the full document and in the
+API-token view.
+
+Nothing to change in your code. If you assert on the document in tests, a `search` operation of an
+`@All()` route now carries the same `x-api-token-scopes`, description line and tags as its siblings.
+
+## 2. `/iam/{path}` is gone from the document
+
+`CoreBetterAuthController.handlePluginRoutes` (`@All('*path')`) forwards every other `/iam/*` request
+to Better-Auth's own handler. It appeared in Swagger as eight `/iam/{path}` operations without
+parameters or description. It is now `@ApiExcludeEndpoint()`; the route itself is unchanged.
+
+- **Generated clients:** a client generated from `/api-docs-json` (hey-api, openapi-generator, …)
+  loses its `coreBetterAuthControllerHandlePluginRoutes*` functions on the next generation. They
+  could not express any real Better-Auth call, so nothing should depend on them — but regenerate and
+  let the compiler confirm it.
+- **Own controller:** a project controller that **overrides** `handlePluginRoutes` (re-declaring
+  `@All('*path')`) must also re-declare `@ApiExcludeEndpoint()` to keep it out of the document.
+  Decorator metadata belongs to the method, so an override starts without it. A controller that
+  only inherits the method is covered automatically.
+
+## 3. Dependency updates
+
+Maintenance only, nothing to change in your project:
+
+| Package | Old | New | Where |
+| --- | --- | --- | --- |
+| `vite` | 8.3.2 | 8.3.3 | devDependencies (test tooling) |
+| `js-yaml` 5.x | 5.4.2 | 5.4.3 | override target in `pnpm-workspace.yaml` (parser bug fix) |
+
+`mongoose` 9.11.0 / `mongodb` 7.7.0 are deliberately not part of this release: the framework and the
+starter have to raise `mongodb` together, because two driver copies make Better-Auth's Mongo adapter
+reject each other's ids.
+
+## Compatibility Notes
+
+- Both changes only affect the generated Swagger/OpenAPI document. Routing, guards and API-token
+  enforcement are unchanged.
+- The document gets smaller: the framework's own test server goes from 142 to 134 operations.
+
+## References
+
+- Helper: `src/core/common/helpers/swagger.helper.ts` (`operationsOf()`)
+- Controller: `src/core/modules/better-auth/core-better-auth.controller.ts` (`handlePluginRoutes`)
+- Tests: `tests/unit/swagger-helper.spec.ts`

package/migration-guides/11.42.8-to-11.42.9.md

@@ -0,0 +1,186 @@
+# Migration Guide: 11.42.8 → 11.42.9
+
+## Overview
+
+| Category             | Details                                                                                                         |
+| -------------------- | --------------------------------------------------------------------------------------------------------------- |
+| **New Feature**      | `setupSwagger()` documents every HTTP interface the server makes usable — Better-Auth's own routes, `/ai/mcp`, the MCP OAuth endpoints (§1) |
+| **Bugfix**           | …and only those: routes the running configuration makes fail for every caller leave the document (§2)          |
+| **New Feature**      | `@ApiMethods()` — the HTTP methods an `@All()` handler actually serves (§3)                                     |
+| **Bugfix**           | The `tus` key in the server configuration takes effect — it was never read (§5). **Check your `tus` block**     |
+| **Bugfix**           | TUS: upload URLs work below a global prefix and a project route, a `path` naming a new route moves the endpoint, `termination: false` / `creation: false` are enforced, new `relativeLocation` (§5) |
+| **Bugfix**           | `healthCheck.enabled: false` leaves the health check endpoints out (§6)                                         |
+| **Breaking Changes** | None in the API. A `tus` block in `config.env.ts` that did nothing before now applies (§5)                      |
+| **Migration Effort** | Review a `tus` block in `config.env.ts` if you have one (§5.1); a proxy that renames the tus route or relative upload URLs need a look (§5.2). Regenerate a client built from `/api-docs-json` if you keep one (§4) |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick it up with the core update.
+
+## 1. Everything usable is documented
+
+The document is built from the running application, so it follows the server configuration and every
+project module automatically: a module that is registered appears, one that is not stays out. Three
+kinds of interface used to be invisible to `@nestjs/swagger` because they have no Nest handler:
+
+| Interface | Documented since 11.42.9 |
+| --- | --- |
+| Routes Better-Auth serves itself under `/iam` — whatever the configured plugins add (two-factor, passkey, sessions, password change, …), including plugins a project adds via `betterAuth.plugins` | from Better-Auth's own OpenAPI generator, under your Better-Auth controller (§1.1) |
+| `/ai/mcp` (MCP server, `ai.mcp`) | POST/GET/DELETE, with the bearer requirement the endpoint enforces itself |
+| MCP OAuth endpoints (`mountAiMcpOAuth()` in `main.ts`) | exactly the endpoints the call mounted (`/.well-known/…`, `/authorize`, `/token`, `/register`) |
+
+### 1.1 Better-Auth routes
+
+- Documented under your Better-Auth controller: same tags, and `operationTags` receives them with
+  `controller` set to that controller's class name (`handler` is Better-Auth's operation id).
+- Operation ids: `<Controller>_betterAuth_<betterAuthOperationId>`, e.g.
+  `BetterAuthController_betterAuth_changePassword`. Unique and stable across builds.
+- Schemas Better-Auth refers to are added as `BetterAuthUser`, `BetterAuthSession`, … so they cannot
+  collide with your own `User` model; Better-Auth's OpenAPI 3.1 constructs are converted to 3.0.
+- Security: what Better-Auth enforces. A route behind one of its session middlewares (or one of the
+  social-account routes that check the session in their handler) carries the global requirement —
+  bearer or the session cookie; every other route is public (`security: []`): sign-in, password reset,
+  get-session, the two-factor verification steps of a sign-in. Better-Auth's own generator marks every
+  route bearer-only, so this is read from the live instance, not from the generator. Routes of plugins
+  you add yourself (`admin()`, `organization()`, …) always carry the global requirement.
+- With API tokens configured they carry "API tokens: not allowed on this route" and never appear in the
+  API-token view.
+- Under a global prefix or URI versioning Better-Auth's own routes are not reachable (the API
+  middleware does not forward them); they are then not documented, and a warning says why.
+
+**Behind it:** Better-Auth exposes its generator only through its `openAPI()` plugin, so nest-server
+registers that plugin itself (`disableDefaultReference: true`). Its own route,
+`/iam/open-api/generate-schema`, is not part of your API: its endpoints are marked server-only, so
+Better-Auth never routes them and they answer 404, as before this release. If you registered `openAPI()`
+in `betterAuth.plugins` yourself, nothing changes — your registration replaces the internal one.
+
+## 2. Only what can succeed is documented
+
+A route that answers an error to every caller under the running configuration is left out. Each rule
+reads the switch the handler itself reads:
+
+| Configuration | Left out |
+| --- | --- |
+| `auth.legacyEndpoints` keeps REST closed (the default since 11.38.0) | legacy `/auth/signin`, `/auth/signup`, `/auth/logout`, `/auth/refresh-token` (they answer 410) |
+| `betterAuth.emailAndPassword.enabled: false` | `/iam/sign-in/email`, `/iam/sign-up/email` |
+| `betterAuth.emailAndPassword.disableSignUp: true` | `/iam/sign-up/email` |
+| `betterAuth.emailAndPassword.passwordReset: false` | `/iam/request-password-reset`, `/iam/reset-password`, `/iam/reset-password/{token}` |
+| Better-Auth's own options, read from the live instance — so `betterAuth.options` counts too | e.g. POST `/iam/get-session` without `session.deferSessionRefresh`, social routes without a provider, two-factor OTP routes without `otpOptions.sendOTP`, `/iam/delete-user` without `user.deleteUser.enabled`, `/iam/change-email` without `user.changeEmail.enabled`, `/iam/update-session` without session fields that accept input |
+| A Hub panel switched off (`hub.collectors.*`, `hub.mailbox`, `hub.emailPreview`, `hub.db`, `hub.migrations`) | its `*.json` endpoint and actions, which would only answer `{ available: false }` or 400 |
+
+A project controller extending a core controller is covered too — the rules go by the handler, not by
+the class name.
+
+## 3. `@ApiMethods()` for `@All()` handlers
+
+`@nestjs/swagger` documents an `@All()` handler as eight operations (GET … SEARCH), whatever it serves.
+The TUS handlers now declare theirs, so `/tus` shows POST and `/tus/{id}` HEAD/PATCH/DELETE. Use the
+decorator on your own catch-all handlers:
+
+```typescript
+import { ApiMethods } from '@lenne.tech/nest-server';
+
+@All(':id')
+@ApiMethods('get', 'delete')
+async handle(@Req() req: Request, @Res() res: Response) { … }
+```
+
+It affects the document only, never routing.
+
+## 4. Generated clients
+
+A client generated from `/api-docs-json` (hey-api, openapi-generator, …) gains functions for the newly
+documented routes and loses those for routes your configuration switches off (and the eight
+`/iam/{path}` catch-all functions since 11.42.8). Regenerate and let the compiler point at anything that
+used a removed function.
+
+## 5. TUS: the configuration takes effect
+
+### 5.1 The server configuration's `tus` key is read
+
+`TusModule.forRoot()` without a `config` of its own now reads the `tus` key of the server configuration
+(`config.env.ts`, `NSC__TUS__*`) — the zero-config rule `BetterAuthModule.forRoot()` already follows. An
+explicit `TusModule.forRoot({ config })` still wins. **Before this release that key was never read**:
+TUS ran with the defaults whatever it said.
+
+What that means for you, if `config.env.ts` has a `tus` block:
+
+| You set | Before | Now |
+| --- | --- | --- |
+| `tus: false` | TUS enabled anyway | `/tus` is not registered |
+| `allowedTypes` | every type accepted | other types answer 415 at creation |
+| `maxSize` | 50 GB | your limit (413 above it) |
+| `roles` | `[S_USER]` | your roles |
+| `termination`, `creation`, `path`, `expiration`, … | defaults | your values (see 5.2 / 5.3) |
+
+These are the values the block was written to enforce, so this is the behaviour you asked for — but it
+starts on this upgrade. Check that the allowed types cover what your clients upload before you deploy.
+
+### 5.2 `path` and upload URLs
+
+Before this release `path` only changed the URL handed to a client for a new upload (`Location`); the
+endpoint itself always stayed where the controller declared it. Every setup that works today keeps
+working:
+
+| `path` | Since 11.42.9 |
+| --- | --- |
+| unset | The upload URL is built from the path the upload was created at — so resuming now also works below a global prefix, a URI version or a project controller's own route, where it answered 404 before |
+| ends with the controller's route — `'/api/tus'` (global prefix) or `'/files/tus'` (a proxy that strips `/files`) | Unchanged: the controller stays, upload URLs use this path. This was the workaround for the old behaviour and needs no change |
+| a new route — `'/uploads'` | The controller is now mounted there (a project controller too, as `roles` already did). Before, the endpoint stayed at `/tus` while clients were sent to `/uploads/…`, so no upload could ever be resumed |
+
+Like any controller route, a new route sits below the global prefix and the URI version.
+
+Two cases need a look:
+
+- **A proxy that renames the route** (public `/files/upload` forwarded as `/tus`): `path: '/files/upload'`
+  now moves the endpoint. Remove `path` and override `uploadCollectionPath(req)` in your
+  `CoreTusService` subclass to return the public path.
+- **Relative upload URLs.** The framework now builds the upload URL itself, which takes precedence over
+  `@tus/server`'s `relativeLocation`. Use `tus.relativeLocation: true` (new); a `relativeLocation` you
+  pass to the tus server yourself — in a vendored core, for example — is honoured as well.
+
+### 5.3 Switched-off extensions are enforced
+
+`@tus/server` itself ignores the extension flags. Since this release:
+
+| Setting | Effect |
+| --- | --- |
+| `termination: false` | DELETE answers 501, OPTIONS no longer advertises `termination` |
+| `creation: false` | POST answers 501, OPTIONS no longer advertises the creation extensions |
+| `creationWithUpload: false` | a POST carrying data answers 501 |
+
+`checksum` and `concatenation` have no effect: neither built-in store supports them. The boot log now
+lists the extensions the server actually offers.
+
+## 6. `healthCheck.enabled: false`
+
+The flag was declared and ignored: any `healthCheck` object registered `GET /health-check` and the
+`healthCheck` query. `enabled: false` now leaves both out (and out of the Swagger document).
+
+## Compatibility Notes
+
+- The Swagger work changes nothing at runtime. Better-Auth's `openAPI()` plugin is now registered, but
+  kept off the router, so `/iam/open-api/*` answers 404 exactly as before. The runtime changes of this
+  release are the ones in §5 and §6.
+- A `CoreTusService` subclass that overrides `onUploadCreate()` keeps the extension checks of §5.3: they
+  run before the hook, whether or not the override calls `super`.
+- The description of Better-Auth's routes is prepared once at application bootstrap
+  (`CoreBetterAuthService.onApplicationBootstrap()`). A project service extending
+  `CoreBetterAuthService` that overrides `onApplicationBootstrap()` must call `super` to keep it.
+- An explicit `@ApiBearerAuth()` / `@ApiSecurity()` on a route the guards admit to everybody now keeps
+  its security requirement instead of being documented as public.
+
+## References
+
+- Swagger helper: `src/core/common/helpers/swagger.helper.ts`
+- Better-Auth rules: `src/core/modules/better-auth/core-better-auth-openapi.helper.ts`
+- Decorator: `src/core/common/decorators/api-methods.decorator.ts`
+- TUS: `src/core/modules/tus/tus.module.ts`, `src/core/modules/tus/core-tus.service.ts`, `src/core/modules/tus/README.md`
+- Tests: `tests/unit/swagger-helper.spec.ts`, `tests/unit/swagger-availability.spec.ts`,
+  `tests/unit/better-auth-openapi-availability.spec.ts`, `tests/better-auth-openapi.e2e-spec.ts`,
+  `tests/unit/tus-module-config.spec.ts`, `tests/tus-protocol-config.e2e-spec.ts`,
+  `tests/unit/core-module-signatures.spec.ts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.42.7",
+  "version": "11.42.9",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -221,7 +221,7 @@
     "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
     "unplugin-swc": "2.0.0",
-    "vite": "8.3.2",
+    "vite": "8.3.3",
     "vite-plugin-node": "8.0.0",
     "vitest": "4.1.11"
   },

package/src/core/common/decorators/api-methods.decorator.ts

@@ -0,0 +1,25 @@
+import { SetMetadata } from '@nestjs/common';
+
+/** Metadata key of {@link ApiMethods} */
+export const API_METHODS_KEY = 'lt:apiMethods';
+
+/**
+ * Lists the HTTP methods an `@All()` handler actually serves.
+ *
+ * `@nestjs/swagger` documents an `@All()` handler as eight operations (GET, POST, PUT, DELETE, PATCH,
+ * OPTIONS, HEAD, SEARCH), whatever the handler does with them. `setupSwagger()` keeps only the methods
+ * named here, so a catch-all that serves three of them is documented with three.
+ *
+ * @example
+ * ```typescript
+ * @All(':id')
+ * @ApiMethods('head', 'patch', 'delete')
+ * async handleUpload(@Req() req: Request, @Res() res: Response) { … }
+ * ```
+ * @since 11.42.9
+ */
+export const ApiMethods = (...methods: string[]) =>
+  SetMetadata(
+    API_METHODS_KEY,
+    methods.map((method) => method.toLowerCase()),
+  );