11.7.2: Enable BetterAuth session token authentication via MongoDB lookup with correct collection and ObjectId handling

Author: kaihaase

.claude/rules/configurable-features.md

@@ -101,22 +101,129 @@ auth: {
 }
 ```
 
+## Boolean Shorthand Pattern
+
+For simple enable/disable scenarios, support `boolean | object` configuration:
+
+### Rules
+
+1. **`true`**: Feature is **enabled** with all default values
+2. **`false`**: Feature is **disabled**
+3. **`{}`**: Feature is **enabled** with all default values (same as `true`)
+4. **`{ option: value }`**: Feature is **enabled** with custom settings
+5. **`{ enabled: false }`**: Feature is **disabled** (allows pre-configuration)
+6. **`undefined`**: Feature is **disabled** (default)
+
+### Benefits
+
+- **Concise**: `jwt: true` instead of `jwt: {}`
+- **Readable**: Clear intent at a glance
+- **Flexible**: Can still use objects for customization
+
+### Implementation Example
+
+```typescript
+// Interface definition
+interface IBetterAuth {
+  jwt?: boolean | IBetterAuthJwtConfig;
+  twoFactor?: boolean | IBetterAuthTwoFactorConfig;
+  passkey?: boolean | IBetterAuthPasskeyConfig;
+}
+
+interface IBetterAuthJwtConfig {
+  enabled?: boolean;
+  expiresIn?: string;
+}
+
+// Helper functions
+function isPluginEnabled<T extends { enabled?: boolean }>(
+  config: boolean | T | undefined
+): boolean {
+  if (config === undefined) return false;
+  if (typeof config === 'boolean') return config;
+  return config.enabled !== false;
+}
+
+function getPluginConfig<T extends { enabled?: boolean }>(
+  config: boolean | T | undefined
+): T | undefined {
+  if (!isPluginEnabled(config)) return undefined;
+  if (typeof config === 'boolean') return {} as T;
+  return config;
+}
+
+// Usage in build logic
+const jwtConfig = getPluginConfig(config.jwt);
+if (jwtConfig) {
+  plugins.push(jwt({ expirationTime: jwtConfig.expiresIn || '15m' }));
+}
+```
+
+### Usage Examples
+
+```typescript
+// config.env.ts
+
+betterAuth: {
+  // Boolean shorthand - enable with defaults
+  jwt: true,
+  twoFactor: true,
+  passkey: true,
+}
+
+// Equivalent to:
+betterAuth: {
+  jwt: {},
+  twoFactor: {},
+  passkey: {},
+}
+
+// Mixed - some with defaults, some customized
+betterAuth: {
+  jwt: true,                        // Enable with defaults
+  twoFactor: { appName: 'My App' }, // Enable with custom settings
+  passkey: false,                   // Explicitly disabled
+}
+
+// Pre-configured but disabled
+betterAuth: {
+  jwt: { enabled: false, expiresIn: '1h' }, // Ready to enable later
+}
+```
+
 ## Applied Features
 
 This pattern is currently applied to:
 
-| Feature | Config Path | Default Values |
-|---------|-------------|----------------|
-| Legacy Auth Rate Limiting | `auth.rateLimit` | `max: 10`, `windowSeconds: 60` |
-| BetterAuth Rate Limiting | `betterAuth.rateLimit` | `max: 10`, `windowSeconds: 60` |
+| Feature | Config Path | Pattern | Default Values |
+|---------|-------------|---------|----------------|
+| Legacy Auth Rate Limiting | `auth.rateLimit` | Presence Implies Enabled | `max: 10`, `windowSeconds: 60` |
+| BetterAuth Rate Limiting | `betterAuth.rateLimit` | Presence Implies Enabled | `max: 10`, `windowSeconds: 60` |
+| BetterAuth JWT Plugin | `betterAuth.jwt` | Boolean Shorthand | `expiresIn: '15m'` |
+| BetterAuth 2FA Plugin | `betterAuth.twoFactor` | Boolean Shorthand | `appName: 'Nest Server'` |
+| BetterAuth Passkey Plugin | `betterAuth.passkey` | Boolean Shorthand | `rpName: 'Nest Server'` |
 
 ## Checklist for New Configurable Features
 
 When adding a new configurable feature:
 
+### For "Presence Implies Enabled" Pattern:
+
 - [ ] Define interface with `enabled?: boolean` as optional property
 - [ ] Set `enabled: false` in DEFAULT_CONFIG
 - [ ] Implement "presence implies enabled" logic in configure method
 - [ ] Document all default values in interface JSDoc
 - [ ] Add tests for: undefined config, empty object, partial config, explicit disable
+
+### For "Boolean Shorthand" Pattern:
+
+- [ ] Define separate interface for config options (e.g., `IBetterAuthJwtConfig`)
+- [ ] Use union type: `property?: boolean | IPropertyConfig`
+- [ ] Implement `isPluginEnabled()` helper for boolean/object handling
+- [ ] Implement `getPluginConfig()` helper to normalize to object
+- [ ] Add tests for: `true`, `false`, `{}`, `{ option: value }`, `{ enabled: false }`, `undefined`
+
+### For Both Patterns:
+
 - [ ] Update this document with the new feature
+- [ ] Export new interfaces in `src/index.ts` (if needed)

.claude/rules/role-system.md

@@ -72,6 +72,46 @@ The `@Roles()` decorator combined with `RolesGuard` automatically:
 2. Extracts the user from the token
 3. Checks if the user has the required role
 
-**Exception:** `@UseGuards(AuthGuard(...))` is only needed when:
-- Using `@Roles(RoleEnum.S_EVERYONE)` but still needing an authenticated context
-- Implementing custom authentication strategies outside the role system
+### When @UseGuards IS Required
+
+`@UseGuards(AuthGuard(...))` is only needed in these specific cases:
+
+| Case | Example | Reason |
+|------|---------|--------|
+| **Refresh Token** | `@UseGuards(AuthGuard(AuthGuardStrategy.JWT_REFRESH))` | Different strategy than standard JWT |
+| **Custom Strategies** | `@UseGuards(AuthGuard(AuthGuardStrategy.CUSTOM))` | Non-standard authentication flow |
+
+```typescript
+// CORRECT: refreshToken needs JWT_REFRESH strategy (not standard JWT)
+@Mutation(() => CoreAuthModel)
+@Roles(RoleEnum.S_EVERYONE)
+@UseGuards(AuthGuard(AuthGuardStrategy.JWT_REFRESH))  // Required - different strategy!
+async refreshToken(...): Promise<CoreAuthModel> { }
+
+// CORRECT: Standard endpoints - @Roles is sufficient
+@Mutation(() => CoreAuthModel)
+@Roles(RoleEnum.S_USER)  // Handles JWT auth automatically
+async logout(...): Promise<boolean> { }
+
+@Query(() => User)
+@Roles(RoleEnum.ADMIN)  // Handles JWT auth automatically
+async getUser(...): Promise<User> { }
+```
+
+### Common Mistake: Redundant Guards
+
+When reviewing code, watch for this anti-pattern:
+
+```typescript
+// WRONG: Redundant - @Roles(S_USER) already validates JWT
+@Roles(RoleEnum.S_USER)
+@UseGuards(AuthGuard(AuthGuardStrategy.JWT))  // DELETE THIS
+async someMethod() { }
+
+// WRONG: Redundant - @Roles(ADMIN) already validates JWT
+@Roles(RoleEnum.ADMIN)
+@UseGuards(AuthGuard(AuthGuardStrategy.JWT))  // DELETE THIS
+async adminMethod() { }
+```
+
+**Rule of thumb:** If `@Roles()` uses any role OTHER than `S_EVERYONE`, you don't need `@UseGuards(AuthGuard(JWT))`.

.claude/rules/testing.md

@@ -72,8 +72,41 @@ describe('Feature Name', () => {
 });
 ```
 
+## WebSocket/Subscription Tests
+
+When testing GraphQL subscriptions, use `httpServer.listen(0)` instead of `app.listen()`:
+
+```typescript
+// ✅ CORRECT: No startup log, dynamic port
+await app.init();
+const httpServer = app.getHttpServer();
+await new Promise<void>((resolve) => {
+  httpServer.listen(0, '127.0.0.1', () => resolve());
+});
+const port = httpServer.address().port;
+testHelper = new TestHelper(app, `ws://127.0.0.1:${port}/graphql`);
+
+// Cleanup in afterAll
+if (httpServer) {
+  await new Promise<void>((resolve) => httpServer.close(() => resolve()));
+}
+await app.close();
+```
+
+```typescript
+// ❌ WRONG: Produces "Nest application successfully started" log
+await app.init();
+await app.listen(3030);
+```
+
+**Why:**
+- `app.listen()` triggers NestJS startup log → noisy test output
+- Dynamic port (`0`) avoids port conflicts between parallel tests
+- Explicit `httpServer.close()` prevents open handle warnings
+
 ## Common Test Issues
 
 - **Tests timeout**: Ensure MongoDB is running
 - **Open handles**: Use `npm run test:e2e-doh` to debug
 - **Data conflicts**: Use unique identifiers per test
+- **"NestApplication successfully started" log**: Use `httpServer.listen()` instead of `app.listen()`

CLAUDE.md

@@ -121,6 +121,7 @@ See `.claude/rules/versioning.md` for release process.
 5. **Use Module Inheritance Pattern** for core modules
 6. **Document breaking changes** in commits
 7. **Integration Checklists for Core Modules** - Every core module requiring project integration needs `INTEGRATION-CHECKLIST.md` (see `.claude/rules/core-modules.md`)
+8. **Don't add redundant @UseGuards** - `@Roles()` already handles JWT auth (see `.claude/rules/role-system.md`)
 
 ## Migration Guides
 
@@ -137,11 +138,11 @@ Detailed documentation in `.claude/rules/`:
 | File | Content |
 |------|---------|
 | `module-inheritance.md` | Core architectural pattern for extending modules |
-| `role-system.md` | Role system with S_ prefix rules |
+| `role-system.md` | Role system, S_ prefix rules, @Roles vs @UseGuards |
 | `architecture.md` | Detailed code architecture |
 | `testing.md` | Test configuration and best practices |
 | `versioning.md` | Version strategy and release process |
 | `core-modules.md` | Path-scoped rules for `src/core/modules/` incl. Integration Checklist requirements |
 | `module-deprecation.md` | Legacy Auth → BetterAuth migration roadmap |
 | `migration-guides.md` | Process for creating version migration guides |
-| `configurable-features.md` | "Presence implies enabled" pattern for optional features |
+| `configurable-features.md` | Configuration patterns: "Presence implies enabled" and "Boolean shorthand" (`true` / `{}`) |

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.7.1",
+  "version": "11.7.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",
@@ -81,6 +81,7 @@
     "@as-integrations/express5": "1.1.2",
     "@better-auth/passkey": "1.4.8-beta.4",
     "@getbrevo/brevo": "3.0.1",
+    "@lenne.tech/nest-server": "file:lenne.tech-nest-server-11.7.2.tgz",
     "@nestjs/apollo": "13.2.3",
     "@nestjs/common": "11.1.9",
     "@nestjs/core": "11.1.9",

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.7.1
+  version: 11.7.2
   contact:
     name: lenne.Tech GmbH
     url: https://lenne.tech

spectaql.yml

@@ -233,11 +233,17 @@ export class CoreModule implements NestModule {
     // Add BetterAuthModule based on mode
     // IAM-only mode: Always register BetterAuthModule (required for subscription auth)
     // Legacy mode: Only register if autoRegister is explicitly true
-    if (config.betterAuth?.enabled !== false) {
-      if (isIamOnlyMode || config.betterAuth?.autoRegister === true) {
+    // betterAuth can be: boolean | IBetterAuth | undefined
+    const betterAuthConfig = config.betterAuth;
+    const isBetterAuthEnabled =
+      betterAuthConfig === true || (typeof betterAuthConfig === 'object' && betterAuthConfig?.enabled !== false);
+    const isAutoRegister = typeof betterAuthConfig === 'object' && betterAuthConfig?.autoRegister === true;
+
+    if (isBetterAuthEnabled) {
+      if (isIamOnlyMode || isAutoRegister) {
         imports.push(
           BetterAuthModule.forRoot({
-            config: config.betterAuth || {},
+            config: betterAuthConfig === true ? {} : betterAuthConfig || {},
             // Pass JWT secrets for backwards compatibility fallback
             fallbackSecrets: [config.jwt?.secret, config.jwt?.refresh?.secret],
           }),