@lenne.tech/nest-server 11.9.0 → 11.10.0

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

@@ -8,7 +8,7 @@ Integration of the [better-auth](https://better-auth.com) authentication framewo
 // 1. Follow INTEGRATION-CHECKLIST.md to create required files
 // 2. Add to server.module.ts:
 CoreModule.forRoot(envConfig),  // IAM-only (new projects)
-BetterAuthModule.forRoot({ config: envConfig.betterAuth, fallbackSecrets: [envConfig.jwt?.secret] }),
+CoreBetterAuthModule.forRoot({ config: envConfig.betterAuth, fallbackSecrets: [envConfig.jwt?.secret] }),
 
 // 3. Configure in config.env.ts (minimal - JWT enabled by default):
 betterAuth: true  // or betterAuth: {} for same effect
@@ -112,12 +112,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:
@@ -126,7 +126,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!**
@@ -135,10 +135,10 @@ The `BetterAuthUserMapper` enables bidirectional password synchronization:
 **Modify:** `src/server/server.module.ts`
 **Reference:** See ServerModule in reference implementation
 
-Add import and include BetterAuthModule in imports array with `fallbackSecrets`:
+Add import and include CoreBetterAuthModule in imports array with `fallbackSecrets`:
 
 ```typescript
-BetterAuthModule.forRoot({
+CoreBetterAuthModule.forRoot({
   config: envConfig.betterAuth,
   fallbackSecrets: [envConfig.jwt?.secret, envConfig.jwt?.refresh?.secret],
 }),
@@ -216,7 +216,7 @@ Read the security section below for production deployments.
   /iam/session
   /iam/callback/:provider
   ```
-- **Middleware Matching**: `BetterAuthMiddleware` only forwards requests to paths starting with `basePath`
+- **Middleware Matching**: `CoreBetterAuthMiddleware` only forwards requests to paths starting with `basePath`
 
 **Default `/iam`** avoids collisions with existing `/auth` routes from Legacy Auth.
 
@@ -441,7 +441,7 @@ By default (`autoRegister: false`), projects integrate BetterAuth via an **exten
 ```typescript
 // src/server/modules/better-auth/better-auth.module.ts
 import { Module, DynamicModule } from '@nestjs/common';
-import { BetterAuthModule as CoreBetterAuthModule } from '@lenne.tech/nest-server';
+import { CoreBetterAuthModule } from '@lenne.tech/nest-server';
 
 @Module({})
 export class BetterAuthModule {
@@ -723,7 +723,7 @@ Better-Auth is **enabled by default** but requires explicit module integration (
 1. `BetterAuthModule` - Wraps CoreBetterAuthModule with custom resolver/controller
 2. `BetterAuthResolver` - Extends CoreBetterAuthResolver for GraphQL operations
 3. `BetterAuthController` - Extends CoreBetterAuthController for REST endpoints
-4. `UserService` - Inject `BetterAuthUserMapper` for bidirectional auth sync
+4. `UserService` - Inject `CoreBetterAuthUserMapper` for bidirectional auth sync
 
 ### Simple: Auto-Registration
 
@@ -797,20 +797,31 @@ curl -X GET https://api.example.com/iam/token \
 | `/iam/sign-in/social`      | POST   | Initiate social login |
 | `/iam/callback/:provider`  | GET    | OAuth callback        |
 
-### Two-Factor Authentication Endpoints
+### Two-Factor Authentication Endpoints (Native Better Auth)
 
-| Endpoint                  | Method | Description      |
-| ------------------------- | ------ | ---------------- |
-| `/iam/two-factor/enable`  | POST   | Enable 2FA       |
-| `/iam/two-factor/disable` | POST   | Disable 2FA      |
-| `/iam/two-factor/verify`  | POST   | Verify 2FA code  |
+These endpoints are handled by Better Auth's native `twoFactor` plugin:
 
-### Passkey Endpoints
+| Endpoint                            | Method | Description                    |
+| ----------------------------------- | ------ | ------------------------------ |
+| `/iam/two-factor/enable`            | POST   | Enable 2FA, get TOTP URI       |
+| `/iam/two-factor/disable`           | POST   | Disable 2FA                    |
+| `/iam/two-factor/verify-totp`       | POST   | Verify TOTP code               |
+| `/iam/two-factor/generate-backup-codes` | POST | Generate backup codes      |
+| `/iam/two-factor/verify-backup-code`| POST   | Verify backup code             |
 
-| Endpoint                     | Method | Description               |
-| ---------------------------- | ------ | ------------------------- |
-| `/iam/passkey/register`      | POST   | Register new passkey      |
-| `/iam/passkey/authenticate`  | POST   | Authenticate with passkey |
+### Passkey Endpoints (Native Better Auth)
+
+These endpoints are handled by Better Auth's native `passkey` plugin:
+
+| Endpoint                                  | Method | Description                         |
+| ----------------------------------------- | ------ | ----------------------------------- |
+| `/iam/passkey/generate-register-options`  | POST   | Get WebAuthn registration options   |
+| `/iam/passkey/verify-registration`        | POST   | Verify and store passkey            |
+| `/iam/passkey/generate-authenticate-options` | POST | Get WebAuthn authentication options |
+| `/iam/passkey/verify-authentication`      | POST   | Verify passkey authentication       |
+| `/iam/passkey/list-user-passkeys`         | POST   | List user's passkeys                |
+| `/iam/passkey/delete-passkey`             | POST   | Delete a passkey                    |
+| `/iam/passkey/update-passkey`             | POST   | Update passkey name                 |
 
 ## GraphQL API
 
@@ -855,10 +866,10 @@ In addition to REST endpoints, Better-Auth provides GraphQL queries and mutation
 
 ### Response Types
 
-#### BetterAuthAuthModel
+#### CoreBetterAuthAuthModel
 
 ```graphql
-type BetterAuthAuthModel {
+type CoreBetterAuthAuthModel {
   success: Boolean!
   requiresTwoFactor: Boolean
   token: String
@@ -868,10 +879,10 @@ type BetterAuthAuthModel {
 }
 ```
 
-#### BetterAuthFeaturesModel
+#### CoreBetterAuthFeaturesModel
 
 ```graphql
-type BetterAuthFeaturesModel {
+type CoreBetterAuthFeaturesModel {
   enabled: Boolean!
   jwt: Boolean!
   twoFactor: Boolean!
@@ -880,10 +891,10 @@ type BetterAuthFeaturesModel {
 }
 ```
 
-#### BetterAuth2FASetupModel
+#### CoreBetterAuth2FASetupModel
 
 ```graphql
-type BetterAuth2FASetupModel {
+type CoreBetterAuth2FASetupModel {
   success: Boolean!
   totpUri: String
   backupCodes: [String!]
@@ -891,10 +902,10 @@ type BetterAuth2FASetupModel {
 }
 ```
 
-#### BetterAuthPasskeyModel
+#### CoreBetterAuthPasskeyModel
 
 ```graphql
-type BetterAuthPasskeyModel {
+type CoreBetterAuthPasskeyModel {
   id: String!
   name: String
   credentialId: String!
@@ -902,10 +913,10 @@ type BetterAuthPasskeyModel {
 }
 ```
 
-#### BetterAuthPasskeyChallengeModel
+#### CoreBetterAuthPasskeyChallengeModel
 
 ```graphql
-type BetterAuthPasskeyChallengeModel {
+type CoreBetterAuthPasskeyChallengeModel {
   success: Boolean!
   challenge: String
   error: String
@@ -1018,16 +1029,16 @@ mutation {
 }
 ```
 
-## Using BetterAuthService
+## Using CoreBetterAuthService
 
-Inject `BetterAuthService` to access Better-Auth functionality:
+Inject `CoreBetterAuthService` to access Better-Auth functionality:
 
 ```typescript
-import { BetterAuthService } from '@lenne.tech/nest-server';
+import { CoreBetterAuthService } from '@lenne.tech/nest-server';
 
 @Injectable()
 export class MyService {
-  constructor(private readonly betterAuthService: BetterAuthService) {}
+  constructor(private readonly betterAuthService: CoreBetterAuthService) {}
 
   async checkUser(req: Request) {
     // Check if Better-Auth is enabled
@@ -1108,21 +1119,21 @@ async findAllUsers() {
 
 ### How It Works
 
-1. `BetterAuthMiddleware` validates the session on each request
-2. `BetterAuthUserMapper` maps the session user to a user with `hasRole()` capability
+1. `CoreBetterAuthMiddleware` validates the session on each request
+2. `CoreBetterAuthUserMapper` maps the session user to a user with `hasRole()` capability
 3. The mapped user is set to `req.user` for use with guards and decorators
 4. `RolesGuard` and `@Restricted()` work as expected
 
 ## User Mapping
 
-The `BetterAuthUserMapper` handles the conversion between Better-Auth sessions and application users:
+The `CoreBetterAuthUserMapper` handles the conversion between Better-Auth sessions and application users:
 
 ```typescript
-import { BetterAuthUserMapper } from '@lenne.tech/nest-server';
+import { CoreBetterAuthUserMapper } from '@lenne.tech/nest-server';
 
 @Injectable()
 export class MyService {
-  constructor(private readonly userMapper: BetterAuthUserMapper) {}
+  constructor(private readonly userMapper: CoreBetterAuthUserMapper) {}
 
   async mapUser(sessionUser: BetterAuthSessionUser) {
     // Maps session user to application user with roles
@@ -1355,7 +1366,7 @@ When a user resets their password via BetterAuth's native `/iam/reset-password`
 
 ### Automatic Sync (No Configuration Required)
 
-The following sync operations happen automatically when `BetterAuthUserMapper` is injected in `UserService`:
+The following sync operations happen automatically when `CoreBetterAuthUserMapper` is injected in `UserService`:
 
 #### 1. IAM Sign-Up → Legacy
 When a user signs up via BetterAuth (`/iam/sign-up/email`), the password is hashed with bcrypt and stored in `users.password`, enabling Legacy Auth sign-in.
@@ -1434,10 +1445,10 @@ When a user is deleted:
 
 #### Password not syncing to IAM
 
-1. Verify `BetterAuthUserMapper` is injected in `UserService`:
+1. Verify `CoreBetterAuthUserMapper` is injected in `UserService`:
    ```typescript
    constructor(
-     @Optional() private readonly betterAuthUserMapper?: BetterAuthUserMapper,
+     @Optional() private readonly betterAuthUserMapper?: CoreBetterAuthUserMapper,
    ) {
      super(..., { betterAuthUserMapper });
    }
@@ -1464,7 +1475,7 @@ When a user is deleted:
 
 The user needs to sign in via Legacy Auth first with their password. This triggers the automatic migration on first IAM sign-in attempt.
 
-Alternatively, use `BetterAuthUserMapper.migrateAccountToIam()` to migrate the user programmatically:
+Alternatively, use `CoreBetterAuthUserMapper.migrateAccountToIam()` to migrate the user programmatically:
 
 ```typescript
 await betterAuthUserMapper.migrateAccountToIam(email, plainPassword);
@@ -1477,13 +1488,13 @@ To enable bidirectional password reset sync, implement a custom password reset e
 ```typescript
 // src/server/modules/better-auth/better-auth.controller.ts
 import { Body, Controller, Post } from '@nestjs/common';
-import { CoreBetterAuthController, BetterAuthUserMapper, Roles, RoleEnum } from '@lenne.tech/nest-server';
+import { CoreBetterAuthController, CoreBetterAuthUserMapper, Roles, RoleEnum } from '@lenne.tech/nest-server';
 
 @Controller('iam')
 export class BetterAuthController extends CoreBetterAuthController {
   constructor(
     // ... other dependencies
-    private readonly betterAuthUserMapper: BetterAuthUserMapper,
+    private readonly betterAuthUserMapper: CoreBetterAuthUserMapper,
   ) {
     super(...);
   }
@@ -1545,20 +1556,26 @@ This is the recommended approach for projects in migration phase where both auth
 The module provides a `reset()` method for testing:
 
 ```typescript
-import { BetterAuthModule } from '@lenne.tech/nest-server';
+import { CoreBetterAuthModule } from '@lenne.tech/nest-server';
 
 describe('My Tests', () => {
   beforeEach(() => {
     // Reset static state between tests
-    BetterAuthModule.reset();
+    CoreBetterAuthModule.reset();
   });
 
   afterAll(() => {
-    BetterAuthModule.reset();
+    CoreBetterAuthModule.reset();
   });
 });
 ```
 
+## Architecture: Why Custom Controllers?
+
+See **[ARCHITECTURE.md](./ARCHITECTURE.md)** for detailed documentation on why custom controllers are necessary for the hybrid auth system.
+
+---
+
 ## Troubleshooting
 
 ### Better-Auth endpoints return 404
@@ -1658,14 +1675,14 @@ When the rate limit is exceeded, a `429 Too Many Requests` response is returned:
 }
 ```
 
-### Using BetterAuthRateLimiter Programmatically
+### Using CoreBetterAuthRateLimiter Programmatically
 
 ```typescript
-import { BetterAuthRateLimiter } from '@lenne.tech/nest-server';
+import { CoreBetterAuthRateLimiter } from '@lenne.tech/nest-server';
 
 @Injectable()
 export class MyService {
-  constructor(private readonly rateLimiter: BetterAuthRateLimiter) {}
+  constructor(private readonly rateLimiter: CoreBetterAuthRateLimiter) {}
 
   checkCustomLimit(ip: string) {
     // Check rate limit for custom endpoint
@@ -1720,13 +1737,13 @@ Override any method to add custom behavior (e.g., sending welcome emails, analyt
 ```typescript
 // In your BetterAuthResolver (see Step 2 in Integration Guide)
 
-@Mutation(() => BetterAuthAuthModel, { description: 'Sign up via Better-Auth (email/password)' })
+@Mutation(() => CoreBetterAuthAuthModel, { description: 'Sign up via Better-Auth (email/password)' })
 @Roles(RoleEnum.S_EVERYONE)
 override async betterAuthSignUp(
   @Args('email') email: string,
   @Args('password') password: string,
   @Args('name', { nullable: true }) name?: string,
-): Promise<BetterAuthAuthModel> {
+): Promise<CoreBetterAuthAuthModel> {
   // Call original implementation
   const result = await super.betterAuthSignUp(email, password, name);
 
@@ -1777,3 +1794,30 @@ const sessionInfo = this.mapSessionInfo(response.session);
 // Map user to model
 const userModel = this.mapToUserModel(mappedUser);
 ```
+
+---
+
+## Client-Side Integration
+
+For frontend integration with Better-Auth, see the **[Integration Checklist](./INTEGRATION-CHECKLIST.md#client-side-configuration)** which includes:
+
+- Complete auth-client configuration with password hashing
+- 2FA login flow handling (`twoFactorRedirect`)
+- Passkey authentication with `validateSession()` fallback
+- Passkey registration and management
+
+### Quick Reference
+
+| Feature | Client Method | Server Endpoint |
+|---------|---------------|-----------------|
+| Email Sign-In | `authClient.signIn.email()` | `POST /iam/sign-in/email` |
+| Passkey Sign-In | `authClient.signIn.passkey()` | `POST /iam/passkey/verify-authentication` |
+| 2FA Verify | `authClient.twoFactor.verifyTotp()` | `POST /iam/two-factor/verify-totp` |
+| Session Validation | `authClient.$fetch('/session')` | `GET /iam/session` |
+
+### Key Points
+
+1. **Password Hashing**: Always hash passwords with SHA256 client-side before sending
+2. **2FA Redirect**: Check for `twoFactorRedirect: true` in sign-in response
+3. **Passkey Session**: Passkey auth returns session without user - call `validateSession()` to fetch user data
+4. **Credentials**: Use `credentials: 'include'` for cross-origin cookie handling

package/src/core/modules/better-auth/better-auth.config.ts

@@ -135,7 +135,7 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Bett
   const additionalFields = buildUserFields(config);
 
   // Build the base Better-Auth configuration
-  const betterAuthConfig = {
+  const betterAuthConfig: Record<string, unknown> = {
     basePath: config.basePath || '/iam',
     baseURL: config.baseUrl || 'http://localhost:3000',
     database: mongodbAdapter(db),
@@ -147,13 +147,18 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Bett
     plugins,
     secret: config.secret,
     socialProviders,
-    trustedOrigins,
     user: {
       additionalFields,
       modelName: 'users',
     },
   };
 
+  // Only add trustedOrigins if explicitly configured
+  // When undefined, Better-Auth uses its default CORS behavior (allows all origins)
+  if (trustedOrigins) {
+    betterAuthConfig.trustedOrigins = trustedOrigins;
+  }
+
   // Merge with custom options passthrough
   // This allows projects to configure any Better-Auth option not explicitly defined
   const finalConfig = config.options ? { ...betterAuthConfig, ...config.options } : betterAuthConfig;
@@ -205,13 +210,28 @@ function buildPlugins(config: IBetterAuth): BetterAuthPlugin[] {
   // Passkey/WebAuthn Plugin
   const passkeyConfig = getPluginConfig(config.passkey);
   if (passkeyConfig) {
-    plugins.push(
-      passkey({
-        origin: passkeyConfig.origin || 'http://localhost:3000',
-        rpID: passkeyConfig.rpId || 'localhost',
-        rpName: passkeyConfig.rpName || 'Nest Server',
-      }),
-    );
+    // Build passkey options, only including defined values
+    const passkeyOptions: Record<string, unknown> = {
+      origin: passkeyConfig.origin || 'http://localhost:3000',
+      rpID: passkeyConfig.rpId || 'localhost',
+      rpName: passkeyConfig.rpName || 'Nest Server',
+    };
+
+    // Add optional WebAuthn configuration if specified
+    if (passkeyConfig.authenticatorAttachment) {
+      passkeyOptions.authenticatorAttachment = passkeyConfig.authenticatorAttachment;
+    }
+    if (passkeyConfig.residentKey) {
+      passkeyOptions.residentKey = passkeyConfig.residentKey;
+    }
+    if (passkeyConfig.userVerification) {
+      passkeyOptions.userVerification = passkeyConfig.userVerification;
+    }
+    if (passkeyConfig.webAuthnChallengeCookie) {
+      passkeyOptions.webAuthnChallengeCookie = passkeyConfig.webAuthnChallengeCookie;
+    }
+
+    plugins.push(passkey(passkeyOptions));
   }
 
   // Merge custom plugins from configuration
@@ -249,16 +269,33 @@ function buildSocialProviders(config: IBetterAuth): Record<string, SocialProvide
 }
 
 /**
- * Builds the trusted origins array
+ * Builds the trusted origins array for CORS configuration.
+ *
+ * Behavior:
+ * - If trustedOrigins is explicitly configured → use those origins
+ * - If Passkey disabled and baseUrl set → fallback to [baseUrl] (backwards compatible)
+ * - Otherwise → return undefined (allows all origins via Better-Auth's default)
+ *
+ * NOTE: When Passkey is enabled, trustedOrigins MUST be configured because
+ * Passkey uses credentials: 'include' which doesn't work with CORS '*' wildcard.
+ * This is validated in validateConfig() which throws an error if missing.
  */
-function buildTrustedOrigins(config: IBetterAuth): string[] {
+function buildTrustedOrigins(config: IBetterAuth): string[] | undefined {
+  // If trustedOrigins is explicitly configured, use it
   if (config.trustedOrigins?.length) {
     return config.trustedOrigins;
   }
-  if (config.baseUrl) {
+
+  // Backwards-compatible fallback for non-Passkey configs
+  // When Passkey is enabled, validateConfig() will throw an error anyway
+  const isPasskeyEnabled = isPluginEnabled(config.passkey);
+  if (!isPasskeyEnabled && config.baseUrl) {
     return [config.baseUrl];
   }
-  return ['http://localhost:3000'];
+
+  // Otherwise, let Better-Auth handle CORS with its default behavior
+  // This allows all origins for requests without credentials
+  return undefined;
 }
 
 /**
@@ -415,16 +452,16 @@ function validateConfig(config: IBetterAuth, fallbackSecrets?: (string | undefin
   // Log information about secret source
   switch (secretSource) {
     case 'auto-generated':
-      warnings.push('⚠️  BETTER_AUTH: No secret configured - using auto-generated secret.');
-      warnings.push('⚠️  CONSEQUENCE: All user sessions will be invalidated on server restart!');
+      warnings.push('BETTER_AUTH: No secret configured - using auto-generated secret.');
+      warnings.push('CONSEQUENCE: All user sessions will be invalidated on server restart!');
       warnings.push(
-        '💡 FOR PRODUCTION: Set betterAuth.secret in config or provide a valid fallback secret (min 32 chars).',
+        'FOR PRODUCTION: Set betterAuth.secret in config or provide a valid fallback secret (min 32 chars).',
       );
-      warnings.push("💡 Generate with: node -e \"console.log(require('crypto').randomBytes(32).toString('base64'))\"");
+      warnings.push("Generate with: node -e \"console.log(require('crypto').randomBytes(32).toString('base64'))\"");
       break;
     case 'fallback':
       warnings.push(
-        '💡 BETTER_AUTH: Using fallback secret (backwards compatible). Consider setting betterAuth.secret explicitly.',
+        'BETTER_AUTH: Using fallback secret (backwards compatible). Consider setting betterAuth.secret explicitly.',
       );
       break;
     // 'explicit' - no warning needed, explicitly configured
@@ -444,6 +481,17 @@ function validateConfig(config: IBetterAuth, fallbackSecrets?: (string | undefin
     }
   }
 
+  // ERROR if Passkey is enabled but trustedOrigins is not configured
+  // Passkey uses credentials: 'include', which doesn't work with CORS '*' wildcard
+  const isPasskeyEnabled = isPluginEnabled(config.passkey);
+  if (isPasskeyEnabled && !config.trustedOrigins?.length) {
+    errors.push(
+      'PASSKEY CORS: trustedOrigins is REQUIRED when Passkey is enabled. ' +
+        'Passkey uses credentials which requires explicit CORS origins (wildcard "*" is not allowed). ' +
+        'Configure betterAuth.trustedOrigins with your frontend URLs, e.g.: ["http://localhost:3001", "https://app.example.com"]',
+    );
+  }
+
   // Validate passkey origin
   const passkeyConfig = typeof config.passkey === 'object' ? config.passkey : null;
   if (passkeyConfig?.enabled && passkeyConfig.origin && !isValidUrl(passkeyConfig.origin)) {