@lenne.tech/nest-server 11.9.0 → 11.10.1

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

@@ -6,7 +6,7 @@ import { Connection, Types } from 'mongoose';
 import { firstValueFrom, isObservable } from 'rxjs';
 
 import { RoleEnum } from '../../../common/enums/role.enum';
-import { BetterAuthService } from '../../better-auth/better-auth.service';
+import { CoreBetterAuthService } from '../../better-auth/core-better-auth.service';
 import { ErrorCode } from '../../error-code';
 import { AuthGuardStrategy } from '../auth-guard-strategy.enum';
 import { ExpiredTokenException } from '../exceptions/expired-token.exception';
@@ -36,7 +36,7 @@ import { AuthGuard } from './auth.guard';
 @Injectable()
 export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
   private readonly logger = new Logger(RolesGuard.name);
-  private betterAuthService: BetterAuthService | null = null;
+  private betterAuthService: CoreBetterAuthService | null = null;
   private mongoConnection: Connection | null = null;
   private servicesResolved = false;
 
@@ -59,7 +59,7 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
     }
 
     try {
-      this.betterAuthService = this.moduleRef.get(BetterAuthService, { strict: false });
+      this.betterAuthService = this.moduleRef.get(CoreBetterAuthService, { strict: false });
     } catch {
       // BetterAuth not available - that's fine, we'll use Legacy JWT only
     }
@@ -168,6 +168,47 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
         token = authHeader.substring(7);
       }
 
+      // If no token in header, try cookies (for REST endpoints)
+      if (!token) {
+        let cookies: Record<string, string> | undefined;
+
+        // Try GraphQL context first
+        try {
+          const gqlContext = GqlExecutionContext.create(context);
+          const ctx = gqlContext.getContext();
+          if (ctx?.req?.cookies) {
+            cookies = ctx.req.cookies;
+          }
+        } catch {
+          // GraphQL context not available
+        }
+
+        // Fallback to HTTP context
+        if (!cookies) {
+          try {
+            const httpRequest = context.switchToHttp().getRequest();
+            if (httpRequest?.cookies) {
+              cookies = httpRequest.cookies;
+            }
+          } catch {
+            // HTTP context not available
+          }
+        }
+
+        // Extract session token from cookies (try multiple cookie names)
+        if (cookies) {
+          // Get the basePath for cookie name (e.g., 'iam' -> 'iam.session_token')
+          const basePath = this.betterAuthService.getBasePath?.()?.replace(/^\//, '').replace(/\//g, '.') || 'iam';
+          const basePathCookie = `${basePath}.session_token`;
+
+          token =
+            cookies[basePathCookie] ||
+            cookies['better-auth.session_token'] ||
+            cookies['token'] ||
+            undefined;
+        }
+      }
+
       if (!token) {
         return null;
       }

package/src/core/modules/auth/services/core-auth.service.ts

@@ -15,8 +15,8 @@ import { getStringIds } from '../../../common/helpers/db.helper';
 import { prepareServiceOptions } from '../../../common/helpers/service.helper';
 import { ServiceOptions } from '../../../common/interfaces/service-options.interface';
 import { ConfigService } from '../../../common/services/config.service';
-import { BetterAuthUserMapper } from '../../better-auth/better-auth-user.mapper';
-import { BetterAuthService } from '../../better-auth/better-auth.service';
+import { CoreBetterAuthUserMapper } from '../../better-auth/core-better-auth-user.mapper';
+import { CoreBetterAuthService } from '../../better-auth/core-better-auth.service';
 import { ErrorCode } from '../../error-code';
 import { CoreAuthModel } from '../core-auth.model';
 import { CoreAuthSignInInput } from '../inputs/core-auth-sign-in.input';
@@ -63,8 +63,8 @@ export class CoreAuthService {
     protected readonly userService: CoreAuthUserService,
     protected readonly jwtService: JwtService,
     protected readonly configService: ConfigService,
-    @Optional() protected readonly betterAuthService?: BetterAuthService,
-    @Optional() protected readonly betterAuthUserMapper?: BetterAuthUserMapper,
+    @Optional() protected readonly betterAuthService?: CoreBetterAuthService,
+    @Optional() protected readonly betterAuthUserMapper?: CoreBetterAuthUserMapper,
   ) {}
 
   /**

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

@@ -0,0 +1,102 @@
+# Architecture: Why Custom Controllers?
+
+The `CoreBetterAuthController` implements custom endpoints instead of directly using native Better-Auth endpoints. This is **necessary** for the nest-server hybrid auth system.
+
+## 1. Hybrid-Auth-System (Legacy + Better-Auth)
+
+The nest-server supports bidirectional authentication:
+- **Legacy Auth → Better-Auth**: Users created via Legacy Auth can sign in via Better-Auth
+- **Better-Auth → Legacy Auth**: Users created via Better-Auth can sign in via Legacy Auth
+
+This requires custom logic that cannot be implemented via Better-Auth hooks alone.
+
+## 2. Why Not Better-Auth Hooks?
+
+Better-Auth hooks have fundamental limitations that prevent full implementation of our requirements:
+
+| Requirement | Hook Support | Reason |
+|-------------|--------------|--------|
+| Legacy user migration | ⚠️ Partial | Requires global DB access outside NestJS DI |
+| Password sync to Legacy | ❌ No | **After-hooks don't have access to plaintext password** |
+| Custom response format | ❌ No | **Hooks cannot modify HTTP response** |
+| Multi-cookie setting | ❌ No | **Hooks cannot set cookies** |
+| User mapping with roles | ❌ No | Requires NestJS Dependency Injection |
+| Session token injection | ❌ No | Before-hooks cannot inject tokens into requests |
+
+## 3. Hook Limitations Explained
+
+### After-Hooks Cannot Change Response
+
+```typescript
+// ❌ This does NOT work - return value is ignored
+hooks: {
+  after: createAuthMiddleware(async (ctx) => {
+    ctx.response.body.customField = 'value'; // Ignored!
+    return { response: modifiedResponse }; // Also ignored!
+  }),
+}
+```
+
+### After-Hooks Don't Have Plaintext Password
+
+```typescript
+// ❌ Cannot sync password because it's already hashed
+hooks: {
+  after: [
+    {
+      matcher: (ctx) => ctx.path === '/sign-up/email',
+      handler: async (ctx) => {
+        // ctx.body.password is ALREADY HASHED at this point
+        // We cannot call syncPasswordToLegacy() without plaintext!
+      },
+    },
+  ],
+}
+```
+
+### Hooks Don't Have NestJS DI Access
+
+```typescript
+// ❌ Hooks are configured in betterAuth(), not in NestJS context
+export const auth = betterAuth({
+  hooks: {
+    // No access to NestJS services here!
+    // this.userService, this.emailService, etc. are unavailable
+  },
+});
+```
+
+## 4. What Custom Endpoints Do
+
+| Endpoint | Custom Logic | Why Required |
+|----------|--------------|--------------|
+| `/sign-in/email` | Legacy migration, PW normalization, 2FA handling | Migration needs plaintext password |
+| `/sign-up/email` | PW normalization, Legacy sync, User linking | Sync needs plaintext password |
+| `/sign-out` | Multi-cookie clearing | Response modification |
+| `/session` | User mapping with roles | NestJS service access |
+| Plugin routes | Session token injection | Request modification |
+
+## 5. Native Handler Where Possible
+
+Despite custom endpoints, we use Better-Auth's native handler where appropriate:
+- **Plugin routes** (Passkey, 2FA, OAuth) → `authInstance.handler()`
+- **2FA verification flow** → Native handler for correct cookie setting
+- **Passkey authentication** → Native WebAuthn handling
+
+## 6. Alternative Approaches Considered
+
+| Approach | Evaluation |
+|----------|------------|
+| **Full Hook Approach** | ❌ Not feasible - missing plaintext password, no response modification |
+| **Hybrid with Global DB** | ⚠️ Possible but anti-pattern - bypasses NestJS DI, harder to test |
+| **Custom Controller (current)** | ✅ Best balance - NestJS DI access, testable, maintainable |
+
+## Conclusion
+
+The custom controller architecture is **necessary complexity**, not unnecessary overhead. It enables:
+- ✅ Legacy Auth compatibility
+- ✅ Bidirectional password synchronization
+- ✅ Multi-cookie support
+- ✅ Custom user mapping with roles
+- ✅ Proper 2FA cookie handling
+- ✅ Full NestJS Dependency Injection access

package/src/core/modules/better-auth/INTEGRATION-CHECKLIST.md

@@ -68,12 +68,12 @@ GraphQL schema is built from decorators at compile time. The parent class (`Core
 
 1. Add import:
    ```typescript
-   import { BetterAuthUserMapper } from '@lenne.tech/nest-server';
+   import { CoreBetterAuthUserMapper } from '@lenne.tech/nest-server';
    ```
 
 2. Add constructor parameter:
    ```typescript
-   @Optional() private readonly betterAuthUserMapper?: BetterAuthUserMapper,
+   @Optional() private readonly betterAuthUserMapper?: CoreBetterAuthUserMapper,
    ```
 
 3. Pass to super() via options object:
@@ -82,7 +82,7 @@ GraphQL schema is built from decorators at compile time. The parent class (`Core
    ```
 
 **WHY is this critical?**
-The `BetterAuthUserMapper` enables bidirectional password synchronization:
+The `CoreBetterAuthUserMapper` enables bidirectional password synchronization:
 - User signs up via BetterAuth → password synced to Legacy Auth (bcrypt hash)
 - User changes password → synced between both systems
 - **Without this, users can only authenticate via ONE system!**
@@ -189,7 +189,7 @@ After integration, verify:
 | Mistake | Symptom | Fix |
 |---------|---------|-----|
 | Forgot to re-declare decorators in Resolver | GraphQL endpoints missing (404) | Copy resolver from reference, keep ALL decorators |
-| Forgot `BetterAuthUserMapper` in UserService | Auth systems not synced, users can't cross-authenticate | Add `@Optional()` parameter and pass to super() |
+| Forgot `CoreBetterAuthUserMapper` in UserService | Auth systems not synced, users can't cross-authenticate | Add `@Optional()` parameter and pass to super() |
 | Missing `fallbackSecrets` in ServerModule | Session issues without explicit secret | Add `fallbackSecrets: [envConfig.jwt?.secret, ...]` |
 | Wrong `basePath` in config | 404 on BetterAuth endpoints | Ensure basePath matches controller (default: `/iam`) |
 | Using wrong CoreModule signature | Build errors or missing features | New projects: 1-parameter, Existing: 3-parameter |
@@ -223,29 +223,298 @@ Clients must be configured to use the correct base path and hash passwords:
 
 ```typescript
 // auth-client.ts (e.g., for Nuxt/Vue)
+import { passkeyClient } from '@better-auth/passkey/client';
+import { twoFactorClient } from 'better-auth/client/plugins';
 import { createAuthClient } from 'better-auth/vue';
 import { sha256 } from '~/utils/crypto';
 
 const baseClient = createAuthClient({
   baseURL: import.meta.env.VITE_API_URL,
   basePath: '/iam',  // Must match server config
-  plugins: [...],
+  fetchOptions: {
+    credentials: 'include', // Required for cross-origin cookie handling
+  },
+  plugins: [
+    twoFactorClient({
+      onTwoFactorRedirect() {
+        navigateTo('/auth/2fa');
+      },
+    }),
+    passkeyClient(),
+  ],
 });
 
 // Wrap signIn/signUp to hash passwords before sending
 export const authClient = {
   ...baseClient,
+  useSession: baseClient.useSession,
+  passkey: (baseClient as any).passkey,
   signIn: {
     ...baseClient.signIn,
-    email: async (params) => {
+    email: async (params, options?) => {
+      const hashedPassword = await sha256(params.password);
+      return baseClient.signIn.email({ ...params, password: hashedPassword }, options);
+    },
+    // Passkey sign-in (pass through to plugin)
+    passkey: (baseClient.signIn as any).passkey,
+  },
+  signUp: {
+    ...baseClient.signUp,
+    email: async (params, options?) => {
+      const hashedPassword = await sha256(params.password);
+      return baseClient.signUp.email({ ...params, password: hashedPassword }, options);
+    },
+  },
+  twoFactor: {
+    ...(baseClient as any).twoFactor,
+    enable: async (params, options?) => {
+      const hashedPassword = await sha256(params.password);
+      return (baseClient as any).twoFactor.enable({ password: hashedPassword }, options);
+    },
+    disable: async (params, options?) => {
       const hashedPassword = await sha256(params.password);
-      return baseClient.signIn.email({ ...params, password: hashedPassword });
+      return (baseClient as any).twoFactor.disable({ password: hashedPassword }, options);
     },
+    verifyTotp: (baseClient as any).twoFactor.verifyTotp,
+    verifyBackupCode: (baseClient as any).twoFactor.verifyBackupCode,
   },
-  // ... same for signUp, resetPassword, etc.
 };
 ```
 
+### 2FA Login Flow (Client-Side)
+
+Handle the `twoFactorRedirect` response when signing in:
+
+```typescript
+// login.vue - Handle 2FA redirect
+async function onSubmit(email: string, password: string) {
+  const result = await authClient.signIn.email({ email, password });
+
+  // Check for error
+  if (result.error) {
+    showError(result.error.message);
+    return;
+  }
+
+  // Check if 2FA is required
+  if (result.data?.twoFactorRedirect) {
+    // User has 2FA enabled - redirect to verification page
+    await navigateTo('/auth/2fa');
+    return;
+  }
+
+  // Login successful
+  if (result.data?.user) {
+    setUser(result.data.user);
+    await navigateTo('/app');
+  }
+}
+```
+
+```typescript
+// 2fa.vue - Verify TOTP code
+async function verifyCode(code: string) {
+  const result = await authClient.twoFactor.verifyTotp({
+    code,
+    trustDevice: trustDeviceCheckbox.value,
+  });
+
+  if (result.error) {
+    showError(result.error.message || 'Invalid code');
+    return;
+  }
+
+  // 2FA verification successful
+  const userData = result.data?.user;
+  if (userData) {
+    setUser(userData);
+  } else {
+    // Fallback: validate session to get user data
+    await validateSession();
+  }
+
+  await navigateTo('/app');
+}
+
+// Alternative: Use backup code
+async function useBackupCode(code: string) {
+  const result = await authClient.twoFactor.verifyBackupCode({ code });
+  // Handle same as verifyTotp...
+}
+```
+
+### Passkey Login Flow (Client-Side)
+
+Handle passkey authentication with session validation fallback:
+
+```typescript
+// login.vue - Passkey login
+async function onPasskeyLogin() {
+  try {
+    // Use official Better Auth passkey sign-in
+    const result = await authClient.signIn.passkey();
+
+    if (result.error) {
+      showError(result.error.message || 'Passkey authentication failed');
+      return;
+    }
+
+    // Update auth state with user data if available
+    if (result.data?.user) {
+      setUser(result.data.user);
+    } else if (result.data?.session) {
+      // IMPORTANT: Passkey auth returns session without user
+      // Fetch user data via session validation
+      await validateSession();
+    }
+
+    await navigateTo('/app');
+  } catch (err) {
+    // Handle WebAuthn-specific errors
+    if (err instanceof Error && err.name === 'NotAllowedError') {
+      showError('Passkey authentication was cancelled');
+      return;
+    }
+    showError(err instanceof Error ? err.message : 'Passkey login failed');
+  }
+}
+
+// Helper: Validate session and fetch user data
+async function validateSession() {
+  const sessionResult = await authClient.$fetch('/session');
+  if (sessionResult.user) {
+    setUser(sessionResult.user);
+    return true;
+  }
+  return false;
+}
+```
+
+### Passkey Registration (Client-Side)
+
+Register a new passkey for an authenticated user:
+
+```typescript
+// settings.vue - Register new passkey
+async function registerPasskey() {
+  try {
+    // This calls generate-register-options → verify-registration
+    const result = await authClient.passkey.addPasskey({
+      name: 'My Device',  // Optional: passkey name
+    });
+
+    if (result.error) {
+      showError(result.error.message);
+      return;
+    }
+
+    showSuccess('Passkey registered successfully!');
+    // Refresh passkey list
+    await loadPasskeys();
+  } catch (err) {
+    if (err instanceof Error && err.name === 'NotAllowedError') {
+      showError('Passkey registration was cancelled');
+      return;
+    }
+    showError('Failed to register passkey');
+  }
+}
+
+// List user's passkeys
+async function loadPasskeys() {
+  const result = await authClient.passkey.listUserPasskeys();
+  if (!result.error) {
+    passkeys.value = result.data || [];
+  }
+}
+
+// Delete a passkey
+async function deletePasskey(passkeyId: string) {
+  const result = await authClient.passkey.deletePasskey({ id: passkeyId });
+  if (!result.error) {
+    await loadPasskeys();
+  }
+}
+```
+
+---
+
+## Better-Auth Hooks: Limitations & Warnings
+
+### Why nest-server Uses Custom Controllers
+
+nest-server implements custom REST endpoints instead of relying solely on Better-Auth hooks. This is **by design** due to fundamental hook limitations.
+
+### Hook Limitations Summary
+
+| Limitation | Impact |
+|------------|--------|
+| **After-hooks cannot access plaintext password** | Cannot sync password to Legacy Auth after sign-up |
+| **Hooks cannot modify HTTP response** | Cannot customize response format or add custom fields |
+| **Hooks cannot set cookies** | Cannot implement multi-cookie auth strategy |
+| **No NestJS Dependency Injection** | Cannot access services like UserService, EmailService |
+| **Before-hooks cannot inject tokens** | Cannot add session tokens to request headers |
+
+### What You CAN Do with Hooks
+
+Better-Auth hooks are suitable for:
+- ✅ Logging and analytics (side effects only)
+- ✅ Sending notifications after events
+- ✅ Simple validation in before-hooks
+- ✅ Database writes using global connection (not recommended)
+
+### What You CANNOT Do with Hooks
+
+Do NOT try to implement these via hooks:
+- ❌ Password synchronization between auth systems
+- ❌ Custom response formats
+- ❌ Setting authentication cookies
+- ❌ User role mapping
+- ❌ Legacy auth migration
+
+### Recommended Approach
+
+If you need custom authentication logic:
+
+1. **Extend the Controller** - Override methods in `BetterAuthController`
+2. **Use NestJS Services** - Inject services via constructor
+3. **Call super()** - Reuse base implementation where possible
+
+```typescript
+// Correct: Custom logic via controller extension
+@Controller('iam')
+export class BetterAuthController extends CoreBetterAuthController {
+  constructor(
+    betterAuthService: CoreBetterAuthService,
+    userMapper: CoreBetterAuthUserMapper,
+    configService: ConfigService,
+    private readonly analyticsService: AnalyticsService, // Custom service
+  ) {
+    super(betterAuthService, userMapper, configService);
+  }
+
+  @Post('sign-up/email')
+  @Roles(RoleEnum.S_EVERYONE)
+  override async signUp(
+    @Res({ passthrough: true }) res: Response,
+    @Body() input: CoreBetterAuthSignUpInput,
+  ): Promise<CoreBetterAuthResponse> {
+    const result = await super.signUp(res, input);
+
+    // Custom logic with full NestJS DI access
+    if (result.success) {
+      await this.analyticsService.trackSignUp(result.user.id);
+    }
+
+    return result;
+  }
+}
+```
+
+### Further Reading
+
+See README.md section "Architecture: Why Custom Controllers?" for detailed explanation.
+
 ---
 
 ## Detailed Documentation