@lenne.tech/nest-server 11.42.13 → 11.42.15

package/docs/REQUEST-LIFECYCLE.md

@@ -781,6 +781,14 @@ their public-route shortcut, so the policy holds whichever guard runs first or a
 4. A request that carries a token credential but reaches a guard without a token context (the
    middleware did not run) is refused with 401 rather than treated as anonymous.
 
+A route-level `@UseGuards(AuthGuard(AuthGuardStrategy.JWT | BETTER_AUTH))` (redundant next to
+`@Roles()`, but common — nest-server-starter's `UserController` carries it on six routes) accepts the
+token `CoreApiTokenMiddleware` authenticated instead of re-verifying the `ltt_…` credential, which
+neither Passport nor `BetterAuthTokenService` knows; before 11.42.14 that re-verification answered
+401 on every released route. It calls `enforceApiTokenRoute()` itself, so it never opens a route the
+role guards would refuse, even where it runs without one. `JWT_REFRESH` and project-defined strategies
+never accept a token.
+
 #### System Roles (S_ prefix)
 
 System roles are evaluated at runtime and must **never** be stored in `user.roles`.

package/migration-guides/11.42.13-to-11.42.14.md

@@ -0,0 +1,74 @@
+# Migration Guide: 11.42.13 → 11.42.14
+
+## Overview
+
+| Category             | Details                                                                                                  |
+| -------------------- | -------------------------------------------------------------------------------------------------------- |
+| **Bugfixes**         | A route-level `@UseGuards(AuthGuard(...))` no longer refuses every API token with 401 on a route released via `@ApiTokenScopes()` (§1) |
+| **New Features**     | None                                                                                                     |
+| **Framework API**    | Unchanged — no new exports, no changed signatures                                                        |
+| **Dependencies**     | None for the package (development tooling only)                                                          |
+| **Breaking Changes** | None. Tokens on routes that do not release them are refused exactly as before                            |
+| **Migration Effort** | None. Projects that removed an `AuthGuard` to make tokens work may keep it removed (§1)                   |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick it up with the core update. No code or configuration change is required.
+
+## 1. An explicit `AuthGuard` no longer closes a released route to API tokens
+
+Many projects put `@UseGuards(AuthGuard(AuthGuardStrategy.BETTER_AUTH))` (or `AuthGuard(AuthGuardStrategy.JWT)`) on
+routes next to `@Roles()`. nest-server-starter's `UserController` does so on six routes. The guard is redundant
+there, because `@Roles()` already authenticates, but it was not harmless: it re-verified every request unless the
+user came from Better-Auth, and a user authenticated by an API token does not. So it read the `ltt_…` credential as a
+session or a JWT, failed, and answered **401** — on a route the role guard had just admitted via
+`@ApiTokenScopes()`. Opening such a route for tokens therefore never worked while the guard was on it.
+
+The guard now accepts the token `CoreApiTokenMiddleware` already authenticated, for the `JWT` and `BETTER_AUTH`
+strategies. It applies the same route policy as the role guards (`enforceApiTokenRoute()`: deny by default, scopes,
+tenant binding) itself, so it never admits a token on a route that does not release it — also in a setup where it
+runs without a framework role guard in front of it.
+
+```typescript
+@ApiTokenScopes('read')
+@Get(':id')
+@Roles(RoleEnum.S_USER)
+@UseGuards(AuthGuard(AuthGuardStrategy.BETTER_AUTH)) // 11.42.13: 401 for every token; 11.42.14: works
+async getUser(@CurrentUser() currentUser: User, @Param('id') id: string): Promise<User> { … }
+```
+
+`AuthGuard(AuthGuardStrategy.JWT_REFRESH)`, `RefreshTokenGuard` and project-defined strategies never accept a token.
+
+**What to check:**
+
+- **You removed an `AuthGuard` from a route to make tokens work:** nothing to do. The guard stays redundant next to
+  `@Roles()`; restoring it is optional.
+- **A test expected 401 for a token on a released route that carries an `AuthGuard`:** it now gets the route's
+  answer. A token on a route WITHOUT `@ApiTokenScopes()` is still refused with 403, as before.
+
+## Compatibility Notes
+
+| Pattern | Status |
+| ------- | ------ |
+| Routes with `@Roles()` only | Unchanged |
+| Routes with `@Roles()` + `@UseGuards(AuthGuard(BETTER_AUTH \| JWT))` + `@ApiTokenScopes()` | Tokens now pass (§1) |
+| Routes with `@UseGuards(AuthGuard(...))` but no `@ApiTokenScopes()` | Tokens refused with 403, as before |
+| `refreshToken` / `AuthGuard(JWT_REFRESH)` / custom Passport strategies | Never accept a token, as before |
+| A project guard that extends `AuthGuard(...)` and overrides `handleRequest()` | Compatible; the override also runs for token users |
+
+## Troubleshooting
+
+**A token still gets 401 on a route with an `AuthGuard`**
+Check that the route (or its class) declares `@ApiTokenScopes()` with a scope the token holds — without it, the role
+guard refuses the token with 403 before the `AuthGuard` runs. A 401 means the token itself did not authenticate
+(revoked, expired, wrong prefix); the token middleware answers that before any guard.
+
+## Module Documentation
+
+- [API token module README](../src/core/modules/api-token/README.md) — "Opening a route"
+- [API token integration checklist](../src/core/modules/api-token/INTEGRATION-CHECKLIST.md)
+- [Request lifecycle](../docs/REQUEST-LIFECYCLE.md) — "API tokens (`@ApiTokenScopes`)"

package/migration-guides/11.42.14-to-11.42.15.md

@@ -0,0 +1,117 @@
+# Migration Guide: 11.42.14 → 11.42.15
+
+## Overview
+
+| Category             | Details                                                                                                  |
+| -------------------- | -------------------------------------------------------------------------------------------------------- |
+| **Bugfixes**         | No framework code changes; security release of the runtime dependency `undici` (§3)                     |
+| **New Features**     | None                                                                                                     |
+| **Framework API**    | Unchanged — no new exports, no changed signatures                                                        |
+| **Dependencies**     | `mongoose` 9.10.4 → 9.11.2 and `mongodb` 7.6.0 → 7.7.0 (both `dependencies`, raised together, §1); **`undici` 7.30.0 → 7.30.1 (security release, §3)**; `nodemailer` 10.1.0 → 10.1.2; `@getbrevo/brevo` 6.0.3 → 6.2.0; overrides `@graphql-tools/utils` → 12.0.4, `undici` → 7.30.1, `qs` → 6.16.1 |
+| **Breaking Changes** | None                                                                                                     |
+| **Migration Effort** | Low, but **one step is required**: a project that keeps `mongodb` in `devDependencies` (the starter default) MUST raise it to 7.7.0 — by hand, or with the starter's new update script — or sign-in fails with 401 (§1). Typed `lean()` / `bulkWrite()` code may need a type adjustment (§2) |
+
+## Quick Migration
+
+```bash
+pnpm run update            # starter-based projects: raises every pin the framework raised
+pnpm why mongodb           # must show ONE version: 7.7.0
+```
+
+If `pnpm why mongodb` lists 7.6.0 next to 7.7.0, raise the project's own `mongodb` entry to `7.7.0` (§1). If your
+project has its own `undici` override, raise it to 7.30.1 (§3) — `pnpm audit` does not flag this one yet.
+
+Vendor-mode projects pick up the core with `/lt-dev:backend:update-nest-server-core`; raise `mongoose` and `mongodb`
+in the project's `package.json` to the versions above in the same step.
+
+## 1. mongoose 9.11 and mongodb 7.7 move together
+
+mongoose 9.11.x requires `mongodb ~7.7`, so both are raised in this release. nest-server declares `mongodb` under
+`dependencies`. nest-server-starter keeps it under `devDependencies` — and that pin is **not test-only**: Better-Auth's
+MongoDB adapter (`@better-auth/mongo-adapter`, used by nest-server's IAM module) resolves its `mongodb` peer from the
+project's own `mongodb` entry, in the production image too.
+
+Until this release, `pnpm run update` (the starter's `extras/sync-packages.mjs`) raised a pin only when the framework
+declared it **in the same section**. A project with `mongodb` in `devDependencies` therefore stayed on 7.6.0 while the
+framework's mongoose brought 7.7.0: two driver copies. Where the project's lockfile still holds the older `bson` for
+the old driver (any lockfile not refreshed since bson 7.3), there are two `bson` copies as well. The adapter checks ids
+with `instanceof ObjectId` against ITS driver's bson, the ids come from the framework's — so the check fails, the
+adapter throws `MongoAdapterError: Invalid id value`, and authenticated requests answer **401**. With a single shared
+bson it stays a typing problem in tests (`Db` / `MongoClient` from the test helpers no longer match the project's own
+import). Neither is acceptable, and which one a project gets depends on its lockfile history, so raise the pin.
+
+The starter's update script now raises a package the framework **ships** (`dependencies`) in whichever section the
+project keeps it. A package the framework only develops and tests with (`devDependencies`) still raises only the
+project's own `devDependencies` — never a runtime pin. That keeps the better-auth trio where it belongs: the framework
+holds it as devDependencies (its test versions, with a peer range as the contract), the project holds it as
+dependencies and owns that version, because its api and app must resolve the same better-auth. The rule lives in
+`extras/align-package-versions.mjs`, and nest-server's consumer gate (`pnpm run check:consumer`) applies the identical
+rule before every release.
+
+**What to do:**
+
+- **Your project still has the old `extras/sync-packages.mjs`:** raise `mongodb` to `7.7.0` by hand (also
+  `json-to-graphql-query`, if you keep it in `devDependencies` and it lags), or copy `extras/sync-packages.mjs` and
+  `extras/align-package-versions.mjs` from nest-server-starter. **This step is required** — skipping it breaks sign-in.
+- **Your project has `mongodb` in `dependencies`:** `pnpm run update` already raised it; nothing to do.
+- **Check either way:** `pnpm why mongodb` must list exactly one version.
+
+## 2. mongoose 9.11 type changes
+
+No runtime behaviour your code relies on changed, but two typing changes can surface in a project's own code:
+
+- `lean()` now passes its result type into the query, so a `lean<T>()` result is narrowed to `T`. Code that assigned
+  the result to an incompatible type now gets a compile error instead of a silent mismatch.
+- `UpdateOneModel` / `UpdateManyModel` (`bulkWrite()` operations) are typed like `UpdateQuery`. An update document that
+  was accepted by the looser type may now need its operators spelled out (`$set`, `$push`, …).
+
+Runtime fixes that come along (no action needed): validators on document arrays under nested paths no longer run
+twice, `bulkWrite()` casts array filter values, cursors await driver cleanup on destroy. The mongodb 7.7 driver
+recovers from a failed OIDC token fetch instead of failing every later operation on that client.
+
+## 3. undici 7.30.1 is a security release
+
+undici 7.30.1 fixes four high and four medium advisories (GHSA-qrxm-fqhp-jwvm, GHSA-2m5v-pch6-74hx,
+GHSA-4w7w-5xrc-9h26, GHSA-xjj6-f33q-929c high; GHSA-55wc-3pg8-jfw6, GHSA-f72v-6w45-q472, GHSA-4qv8-2p9j-2685,
+GHSA-9fm3-97px-rjf6 medium). They were published as repository advisories, so **`pnpm audit` does not report them
+yet** — a green audit says nothing about this release. nest-server uses undici at runtime for `outboundFetch()` (the
+SSRF-guarded fetch for user-entered URLs), and one of the fixes concerns function-valued Agent options, which that
+helper's guarded connector is.
+
+**What to do:**
+
+- **Nothing for nest-server's own dependency** — `pnpm run update` raises it.
+- **Your project carries its own `undici` override** (starter-derived projects do, for the
+  `@compodoc/compodoc > cheerio > undici` path): raise key and target together, e.g.
+  `'undici@>=7.0.0 <7.30.0': 7.30.0` → `'undici@>=7.0.0 <7.30.1': 7.30.1`. The old entry would otherwise keep that path
+  on the vulnerable 7.30.0, because cheerio's `^7.19.0` intersects the old key.
+- **Check:** `pnpm why undici` lists only 7.30.1.
+
+Also raised in the same way (no advisory, removes a hold-back): `qs` override `<6.16.0` → `<6.16.1` (6.16.1), and
+`nodemailer` 10.1.2, which strips credentials on a cross-origin redirect.
+
+## Compatibility Notes
+
+| Pattern | Status |
+| ------- | ------ |
+| `mongodb` in `dependencies` of the project | Raised by `pnpm run update` as before |
+| `mongodb` in `devDependencies` of the project (starter default) | Raised only by the new update script — otherwise raise by hand, **required** (§1) |
+| better-auth / `@better-auth/*` in the project's `dependencies` | Never raised from the framework's devDependencies — the project owns that version, as before |
+| `lean<T>()` with an explicit result type | May need a type adjustment (§2) |
+| `bulkWrite()` with typed `updateOne` / `updateMany` operations | May need operators spelled out (§2) |
+| Routes with `@Roles()` + `@UseGuards(AuthGuard(BETTER_AUTH))` | Unchanged. nest-server-starter dropped these redundant guards from its `UserController`; removing them in your project is optional |
+
+## Troubleshooting
+
+**Sign-in or every authenticated request answers 401, the log shows `MongoAdapterError: Invalid id value`**
+Two mongodb (and bson) versions are installed, and Better-Auth's MongoDB adapter uses the project's older one.
+`pnpm why mongodb` shows both; raise the project's own `mongodb` entry to 7.7.0, run `pnpm install`, and rebuild the
+image (§1).
+
+**Type errors around `Db`, `MongoClient` or `Collection` in tests after the update**
+Same cause, same fix: two mongodb versions are installed. Raise the project's own entry to 7.7.0 and run
+`pnpm install`.
+
+## Module Documentation
+
+- [nest-server-starter `extras/align-package-versions.mjs`](https://github.com/lenneTech/nest-server-starter/blob/main/extras/align-package-versions.mjs)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.42.13",
+  "version": "11.42.15",
   "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",
@@ -91,7 +91,7 @@
   "dependencies": {
     "@apollo/server": "5.5.1",
     "@as-integrations/express5": "1.1.2",
-    "@getbrevo/brevo": "6.0.3",
+    "@getbrevo/brevo": "6.2.0",
     "@modelcontextprotocol/sdk": "1.32.1",
     "@nestjs/apollo": "13.4.5",
     "@nestjs/common": "11.2.7",
@@ -125,11 +125,11 @@
     "js-sha256": "1.0.0",
     "json-to-graphql-query": "2.3.0",
     "lodash": "4.18.1",
-    "mongodb": "7.6.0",
-    "mongoose": "9.10.4",
+    "mongodb": "7.7.0",
+    "mongoose": "9.11.2",
     "multer": "2.4.0",
     "node-mailjet": "6.0.11",
-    "nodemailer": "10.1.0",
+    "nodemailer": "10.1.2",
     "passport": "0.7.0",
     "passport-jwt": "4.0.1",
     "reflect-metadata": "0.2.2",
@@ -137,7 +137,7 @@
     "rxjs": "7.8.2",
     "supertest": "7.3.1",
     "ts-morph": "28.0.0",
-    "undici": "7.30.0",
+    "undici": "7.30.1",
     "ws": "8.21.3",
     "yuml-diagram": "1.2.0"
   },
@@ -182,9 +182,9 @@
     }
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "3.1149.0",
-    "@aws-sdk/lib-storage": "3.1149.0",
-    "@aws-sdk/s3-request-presigner": "3.1149.0",
+    "@aws-sdk/client-s3": "3.1152.0",
+    "@aws-sdk/lib-storage": "3.1152.0",
+    "@aws-sdk/s3-request-presigner": "3.1152.0",
     "@better-auth/core": "1.7.7",
     "@better-auth/passkey": "1.7.7",
     "@compodoc/compodoc": "2.0.0",
@@ -192,7 +192,7 @@
     "@nestjs/schematics": "11.1.0",
     "@nestjs/testing": "11.2.7",
     "@swc/cli": "0.8.1",
-    "@swc/core": "1.16.13",
+    "@swc/core": "1.16.18",
     "@tus/s3-store": "2.0.7",
     "@types/compression": "1.8.1",
     "@types/cookie-parser": "1.4.10",
@@ -204,16 +204,16 @@
     "@types/passport": "1.0.17",
     "@vitest/coverage-v8": "4.1.11",
     "better-auth": "1.7.7",
-    "bullmq": "6.3.12",
+    "bullmq": "6.3.15",
     "cross-env": "10.1.0",
     "ioredis": "6.0.0",
     "nodemon": "3.1.14",
     "npm-watch": "0.13.0",
     "otpauth": "9.5.2",
-    "oxfmt": "0.71.0",
-    "oxlint": "1.87.0",
+    "oxfmt": "0.72.0",
+    "oxlint": "1.88.0",
     "rimraf": "6.1.3",
-    "smtp-server": "3.19.21",
+    "smtp-server": "3.19.23",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",
     "tsx": "4.23.15",

package/src/core/modules/api-token/README.md

@@ -60,6 +60,11 @@ What an opened route means per kind:
   membership role. Losing a membership removes the token's access at once — rights are read per
   request, never copied into the token.
 
+An explicit `@UseGuards(AuthGuard(AuthGuardStrategy.BETTER_AUTH))` or `AuthGuard(AuthGuardStrategy.JWT)`
+on the route does not close it to tokens (since 11.42.14; before, it answered 401): it accepts the token
+the middleware authenticated and applies the same route policy. `AuthGuard(JWT_REFRESH)` and custom
+strategies never accept a token.
+
 `request.user`:
 
 - TENANT token: `{ id: <token id>, name, scopes, tenantId, roles: [], hasRole: () => false }`

package/src/core/modules/auth/guards/auth.guard.ts

@@ -6,6 +6,7 @@ import { defaultOptions } from '@nestjs/passport/dist/options.js';
 import { memoize } from '@nestjs/passport/dist/utils/memoize.util.js';
 import passport = require('passport');
 
+import { enforceApiTokenRoute, getApiTokenContext } from '../../api-token/core-api-token.helpers';
 import { BetterAuthTokenService } from '../../better-auth/better-auth-token.service';
 import { BetterAuthenticatedUser } from '../../better-auth/better-auth.types';
 import { CoreBetterAuthService } from '../../better-auth/core-better-auth.service';
@@ -21,6 +22,21 @@ const NO_STRATEGY_ERROR =
   'In order to use "defaultStrategy", please, ensure to import PassportModule in each ' +
   "place where AuthGuard() is being used. Otherwise, passport won't work correctly.";
 
+/**
+ * Strategies that authenticate a person by an access credential. An API token authenticated by
+ * `CoreApiTokenMiddleware` satisfies them; `JWT_REFRESH` and project-defined strategies authenticate
+ * something else (a refresh token, a custom credential), so a token never stands in for those.
+ */
+const API_TOKEN_SATISFIED_STRATEGIES: ReadonlySet<string> = new Set([
+  AuthGuardStrategy.BETTER_AUTH,
+  AuthGuardStrategy.JWT,
+]);
+
+function isSatisfiedByApiToken(strategy: string | string[] | undefined): boolean {
+  const strategies = Array.isArray(strategy) ? strategy : [strategy];
+  return strategies.some((value) => !!value && API_TOKEN_SATISFIED_STRATEGIES.has(value));
+}
+
 /**
  * Interface for auth guard
  */
@@ -61,6 +77,9 @@ const createPassportContext =
  * - If not, validates the token via BetterAuthTokenService (JWT or session token)
  * - Loads the full user from MongoDB with hasRole() capability
  *
+ * API tokens (JWT and BETTER_AUTH only): a token authenticated by CoreApiTokenMiddleware is accepted as is
+ * and the route is decided by enforceApiTokenRoute(), exactly as in the role guards.
+ *
  * Can be removed when pull request is merged:
  * https://github.com/nestjs/passport/pull/66
  */
@@ -118,11 +137,22 @@ function createAuthGuard(type?: AuthGuardStrategy | string | string[]): Type<IAu
 
       const options = { ...defaultOptions, ...this.options };
       const request = this.getRequest(context);
+      const existingUser = request?.[options.property || defaultOptions.property];
+
+      // An API token was already authenticated by CoreApiTokenMiddleware. Neither Passport nor
+      // BetterAuthTokenService knows its credential, so verifying it again here refused every token with
+      // 401 — also on a route that released it via @ApiTokenScopes(). The route is decided here with the
+      // same function the role guards use (deny by default, scopes, tenant binding), so the policy holds
+      // even where this guard runs without a framework role guard in front of it.
+      if (getApiTokenContext(existingUser) && isSatisfiedByApiToken(type || this.options?.defaultStrategy)) {
+        enforceApiTokenRoute({ controllerClass: context.getClass(), handler: context.getHandler(), request });
+        request[options.property || defaultOptions.property] = this.handleRequest(null, existingUser, null, context);
+        return true;
+      }
 
       // Check if user is already authenticated via Better-Auth middleware
       // Only skip Passport for Better-Auth users (marked with _authenticatedViaBetterAuth)
       // This ensures JWT_REFRESH guard still validates refresh tokens properly
-      const existingUser = request?.[options.property || defaultOptions.property];
       if (existingUser && existingUser._authenticatedViaBetterAuth === true) {
         // User is authenticated via Better-Auth - skip Passport authentication
         // Validate through handleRequest to ensure role checks work

package/src/core/modules/better-auth/README.md

@@ -1040,7 +1040,7 @@ better-auth 1.7.0–1.7.2 keyed accounts by `(issuer, accountId)`; 1.7.3 restore
   recognised by shape, so a renamed collection or field is covered. Existing `issuer` values stay;
   they are inert. The backfill marker is deleted, so a rollback to a better-auth that needs the
   issuer runs the backfill again. Log line: `Dropped the unique index "…" on account(issuer,
-accountId)`. A failure is logged at `error` and the boot continues.
+  accountId)`. A failure is logged at `error` and the boot continues.
 - **better-auth 1.7.0–1.7.2: `backfillAccountIssuers()`, described below.** Kept for a project that
   has not raised its better-auth pin yet.
 

package/src/core/modules/hub/README.md

@@ -121,7 +121,7 @@ Every action writes an audit line: `[HUB-ACTION] <action> by user <id>`.
   whose `env` is not `local`/`development`/`test`/`ci`/`e2e`) — it suppresses outgoing mail.
 - **Public-access guard**: `roles: false` (no auth check — public config viewer, logs and destructive
   actions) throws at startup in any **reachable** environment unless `hub.allowPublicAccessInProduction:
-true` is set explicitly. This closes the single most dangerous Hub misconfiguration (a `roles: false`
+  true` is set explicitly. This closes the single most dangerous Hub misconfiguration (a `roles: false`
   copied from a local config into a reachable environment). The reachable check is fail-safe: it treats
   every env name except the known local/test set as reachable, so a custom name (`prod`, `preprod`,
   `staging-2`, …) cannot bypass it. Only acknowledge public access behind a fully-controlled network