@lenne.tech/nest-server 11.42.13 → 11.42.14

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.42.13",
+  "version": "11.42.14",
   "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",
@@ -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",

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