11.10.2: Centralize token verification and ensure @roles decorators work in IAM-only mode

Author: kaihaase

.claude/commands/create-migration-guide.md

@@ -74,6 +74,8 @@ Always analyze:
 
 Use the template at `migration-guides/TEMPLATE.md` and follow the process in `.claude/rules/migration-guides.md`.
 
+**IMPORTANT: All migration guides MUST be written in English.** This includes all section titles, descriptions, code comments, and explanations. Technical terms and code identifiers remain unchanged.
+
 Required sections:
 1. Overview table
 2. Quick Migration

.claude/rules/migration-guides.md

@@ -78,6 +78,7 @@ Use `migration-guides/TEMPLATE.md` as starting point.
 7. **Module Documentation** - Links to affected module docs (README.md, INTEGRATION-CHECKLIST.md)
 
 **Rules:**
+- **Write ALL content in English** - This includes section titles, descriptions, explanations, and code comments. Technical terms and code identifiers remain unchanged.
 - Do NOT name specific customer projects (except nest-server-starter as reference)
 - Keep information general and pattern-based
 - Include code examples for all changes
@@ -107,6 +108,7 @@ ls src/core/modules/**/INTEGRATION-CHECKLIST.md
 
 ## Guide Quality Checklist
 
+- [ ] **Written entirely in English**
 - [ ] Overview table is complete
 - [ ] Quick migration path provided
 - [ ] All breaking changes documented with before/after

eslint.config.mjs

@@ -10,7 +10,11 @@ const patched = baseConfig.map(config => {
   if (config.rules?.['unused-imports/no-unused-vars']) {
     config.rules['unused-imports/no-unused-vars'] = [
       'warn',
-      {caughtErrors: 'none'},
+      {
+        argsIgnorePattern: '^_',
+        caughtErrors: 'none',
+        varsIgnorePattern: '^_',
+      },
     ];
   }
   return config;

migration-guides/11.9.x-to-11.10.x.md

@@ -5,9 +5,9 @@
 | Category | Details |
 |----------|---------|
 | **Breaking Changes** | 1. `trustedOrigins` now required when Passkey enabled (TypeScript compile-time check) |
-| **New Features** | Logging helpers, improved session lookup, enhanced cookie handling, native Better Auth plugin endpoints |
-| **Bugfixes** | Session token forwarding to Better Auth plugins |
-| **Migration Effort** | Low (~10 minutes) - Only affects projects using Passkey |
+| **New Features** | Logging helpers, improved session lookup, enhanced cookie handling, native Better Auth plugin endpoints, **BetterAuthTokenService**, **registerRolesGuardGlobally** for IAM-only setups |
+| **Bugfixes** | Session token forwarding to Better Auth plugins, **RolesGuard now enforced in IAM-only mode** |
+| **Migration Effort** | Low (~10 minutes) - Affects projects using Passkey or IAM-only setups |
 
 ---
 
@@ -45,6 +45,25 @@ betterAuth: {
 }
 ```
 
+### IAM-only Projects (Security Fix)
+
+If you use the 1-parameter `CoreModule.forRoot(environment)` signature (IAM-only, no Legacy Auth), add `registerRolesGuardGlobally: true`:
+
+```typescript
+// server.module.ts - BEFORE (11.9.x)
+CoreBetterAuthModule.forRoot({
+  config: environment.betterAuth,
+})
+
+// server.module.ts - AFTER (11.10.x)
+CoreBetterAuthModule.forRoot({
+  config: environment.betterAuth,
+  registerRolesGuardGlobally: true,  // IMPORTANT: Ensures @Roles() decorators work
+})
+```
+
+**Why:** Without this option, `@Roles()` decorators are not enforced in IAM-only mode, potentially exposing protected endpoints.
+
 ---
 
 ## What's New in 11.10.x
@@ -138,6 +157,60 @@ Session tokens are now set in multiple cookies to ensure compatibility with Bett
 | `/iam/passkey/delete-passkey` | POST | Delete a passkey |
 | `/iam/passkey/update-passkey` | POST | Update passkey name |
 
+### 6. BetterAuthTokenService
+
+New centralized service for token extraction and user loading in BetterAuth authentication.
+
+**What the service provides:**
+- Token extraction from Authorization header or cookies
+- JWT token verification via BetterAuth
+- Session token verification via database lookup
+- User loading from MongoDB with `hasRole()` capability
+
+**Benefits:**
+- Consolidates token verification logic that was previously duplicated in AuthGuard and RolesGuard
+- Lazy resolution: Guards use `ModuleRef.get()` with `{ strict: false }` for optional dependencies
+- Improved testability and maintainability
+
+```typescript
+import { BetterAuthTokenService } from '@lenne.tech/nest-server';
+
+// In a guard or service
+const { token, source } = this.tokenService.extractTokenFromRequest(request);
+if (token) {
+  const user = await this.tokenService.verifyAndLoadUser(token);
+  if (user) {
+    request.user = user;
+  }
+}
+```
+
+### 7. IAM-only Mode Support (registerRolesGuardGlobally)
+
+New option `registerRolesGuardGlobally` in `CoreBetterAuthModule.forRoot()` for IAM-only setups.
+
+**Problem:**
+In IAM-only setups (CoreModule.forRoot with only 1 parameter), CoreAuthModule is not imported. CoreAuthModule normally registers the RolesGuard globally. Without this global registration, `@Roles()` decorators are not automatically enforced.
+
+**Solution:**
+```typescript
+// server.module.ts - IAM-only Setup
+@Module({
+  imports: [
+    CoreModule.forRoot(environment),  // 1-parameter signature = IAM-only
+    CoreBetterAuthModule.forRoot({
+      config: environment.betterAuth,
+      registerRolesGuardGlobally: true,  // RolesGuard is registered globally
+    }),
+  ],
+})
+export class ServerModule {}
+```
+
+**When to use:**
+- `registerRolesGuardGlobally: true` - For IAM-only setups (1-parameter CoreModule.forRoot)
+- `registerRolesGuardGlobally: false` (default) - For Legacy + IAM setups (3-parameter CoreModule.forRoot)
+
 ---
 
 ## Breaking Changes
@@ -201,6 +274,25 @@ Additionally, new endpoints are available for backup codes.
 
 **No action required** - this is a bugfix that improves 2FA functionality without requiring any code changes.
 
+### RolesGuard Enforcement in IAM-only Mode
+
+**Fixed Issue:** In IAM-only setups (CoreModule.forRoot with 1 parameter), `@Roles()` decorators were not automatically enforced because the RolesGuard was not globally registered.
+
+**Symptom:** Endpoints with `@Roles(RoleEnum.ADMIN)` were accessible without authentication.
+
+**Cause:** CoreAuthModule (which globally registers the RolesGuard) is not imported in IAM-only setups.
+
+**Solution:** Use the new option `registerRolesGuardGlobally: true` in CoreBetterAuthModule.forRoot():
+
+```typescript
+CoreBetterAuthModule.forRoot({
+  config: environment.betterAuth,
+  registerRolesGuardGlobally: true,
+})
+```
+
+**Important:** All IAM-only projects should add this option to ensure `@Roles()` decorators are correctly enforced.
+
 ---
 
 ## Detailed Migration Steps
@@ -238,7 +330,23 @@ await fetch('/iam/two-factor/verify', { body: { code: '123456' } });
 await fetch('/iam/two-factor/verify-totp', { body: { code: '123456' } });
 ```
 
-### Step 4: Verify Build and Tests
+### Step 4: Add registerRolesGuardGlobally (If IAM-only Setup)
+
+If you use the 1-parameter `CoreModule.forRoot(environment)` signature (without Legacy Auth), add the `registerRolesGuardGlobally` option:
+
+```typescript
+// server.module.ts
+CoreBetterAuthModule.forRoot({
+  config: environment.betterAuth,
+  registerRolesGuardGlobally: true,  // Required for IAM-only setups
+})
+```
+
+**How to check if you're IAM-only:**
+- 1-parameter: `CoreModule.forRoot(environment)` → IAM-only, needs `registerRolesGuardGlobally: true`
+- 3-parameter: `CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(...), environment)` → Legacy + IAM, no change needed
+
+### Step 5: Verify Build and Tests
 
 ```bash
 npm run build
@@ -301,6 +409,20 @@ trustedOrigins: ['http://localhost:3001'],  // Include port!
 
 **Solution:** Debug logs are now suppressed in production. Ensure `NODE_ENV` is not set to `production` during development.
 
+### Protected Endpoints Accessible Without Authentication (IAM-only)
+
+**Symptom:** Endpoints with `@Roles(RoleEnum.ADMIN)` are accessible without authentication in IAM-only setups.
+
+**Cause:** RolesGuard is not globally registered when using 1-parameter `CoreModule.forRoot()`.
+
+**Solution:** Add `registerRolesGuardGlobally: true` to CoreBetterAuthModule:
+```typescript
+CoreBetterAuthModule.forRoot({
+  config: environment.betterAuth,
+  registerRolesGuardGlobally: true,
+})
+```
+
 ---
 
 ## Module Documentation
@@ -323,6 +445,9 @@ export { isProduction, maskCookieHeader, maskEmail, maskId, maskSensitive, maskT
 
 // BetterAuth types (updated)
 export { IBetterAuth, IBetterAuthWithPasskey, IBetterAuthWithoutPasskey } from './core/common/interfaces/server-options.interface';
+
+// BetterAuthTokenService (new)
+export { BetterAuthTokenService, TokenExtractionResult } from './core/modules/better-auth/better-auth-token.service';
 ```
 
 ---

package-lock.json

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

package.json

@@ -11,7 +11,7 @@ servers:
 info:
   title: lT Nest Server
   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).
-  version: 11.10.1
+  version: 11.10.2
   contact:
     name: lenne.Tech GmbH
     url: https://lenne.tech

spectaql.yml

@@ -262,6 +262,9 @@ export class CoreModule implements NestModule {
             config: betterAuthConfig === true ? {} : betterAuthConfig || {},
             // Pass JWT secrets for backwards compatibility fallback
             fallbackSecrets: [config.jwt?.secret, config.jwt?.refresh?.secret],
+            // In IAM-only mode, register RolesGuard globally to enforce @Roles() decorators
+            // In Legacy mode (autoRegister), RolesGuard is already registered via CoreAuthModule
+            registerRolesGuardGlobally: isIamOnlyMode,
           }),
         );
       }