@lenne.tech/nest-server 11.12.0 → 11.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.12.0",
+  "version": "11.13.0",
   "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/src/config.env.ts

@@ -125,6 +125,8 @@ const config: { [env: string]: IServerOptions } = {
     },
     automaticObjectIdFiltering: true,
     betterAuth: {
+      // Email verification disabled for test environment (no real mailbox available)
+      emailVerification: false,
       // JWT enabled by default (zero-config)
       jwt: { enabled: true, expiresIn: '15m' },
       // Passkey auto-activated when URLs can be resolved (env: 'local' → localhost defaults)

package/src/core/common/interfaces/server-options.interface.ts

@@ -231,6 +231,128 @@ export interface IAuthRateLimit {
  */
 export type IBetterAuth = IBetterAuthWithoutPasskey | IBetterAuthWithPasskey;
 
+/**
+ * Email verification configuration for Better-Auth
+ *
+ * Controls email verification behavior after sign-up.
+ * When enabled, users receive a verification email and must verify
+ * their email address before certain actions are allowed.
+ *
+ * **Enabled by Default:** Email verification is enabled by default.
+ * Set `emailVerification: false` or `emailVerification: { enabled: false }` to disable.
+ *
+ * Accepts:
+ * - `undefined`: Enabled with defaults (zero-config)
+ * - `true` or `{}`: Enable with defaults (same as undefined)
+ * - `{ locale: 'de', ... }`: Enable with custom settings
+ * - `false` or `{ enabled: false }`: Explicitly disable
+ *
+ * @since 11.13.0
+ *
+ * @example
+ * ```typescript
+ * // Default: Email verification enabled
+ * betterAuth: {}
+ *
+ * // Custom configuration
+ * betterAuth: {
+ *   emailVerification: {
+ *     locale: 'de',
+ *     autoSignInAfterVerification: true,
+ *     expiresIn: 86400, // 24 hours in seconds
+ *   }
+ * }
+ *
+ * // Disable email verification
+ * betterAuth: {
+ *   emailVerification: false,
+ * }
+ * ```
+ */
+export interface IBetterAuthEmailVerificationConfig {
+  /**
+   * Whether to automatically sign in the user after email verification.
+   * @default true
+   */
+  autoSignInAfterVerification?: boolean;
+
+  /**
+   * Brevo template ID for verification emails.
+   * When set and Brevo is configured (config.brevo), verification emails
+   * are sent via Brevo's transactional API instead of SMTP/EJS templates.
+   *
+   * Template variables passed to Brevo:
+   * - `name`: User display name
+   * - `link`: Verification URL
+   * - `appName`: Application name
+   * - `expiresIn`: Formatted expiration time
+   *
+   * @default undefined (uses SMTP/EJS templates)
+   */
+  brevoTemplateId?: number;
+
+  /**
+   * Frontend callback URL for email verification.
+   *
+   * When set, the verification link in the email will point to this URL
+   * with the token as a query parameter (e.g., `{callbackURL}?token=xxx`).
+   * The frontend page should then call the backend verify-email endpoint
+   * to complete verification.
+   *
+   * Supports both absolute URLs and relative paths:
+   * - Absolute: `https://example.com/auth/verify-email`
+   * - Relative: `/auth/verify-email` (resolved against `appUrl`)
+   *
+   * When not set, the verification link points directly to the backend
+   * endpoint which handles verification and redirects.
+   *
+   * @default undefined (backend-handled verification)
+   * @since 11.13.0
+   */
+  callbackURL?: string;
+
+  /**
+   * Whether email verification is enabled.
+   * @default true (enabled by default when BetterAuth is active)
+   */
+  enabled?: boolean;
+
+  /**
+   * Time in seconds until the verification link expires.
+   * @default 86400 (24 hours)
+   */
+  expiresIn?: number;
+
+  /**
+   * Locale for the verification email template.
+   * Used to select the correct language template.
+   * @default 'en'
+   */
+  locale?: string;
+
+  /**
+   * Cooldown in seconds between resend requests for the same email address.
+   * Prevents abuse by limiting how often verification emails can be resent.
+   * Applied per email address in-memory.
+   *
+   * @default 60
+   * @since 11.13.0
+   */
+  resendCooldownSeconds?: number;
+
+  /**
+   * Custom template name for the verification email.
+   * The system looks for templates in this order:
+   * 1. `<template>-<locale>.ejs` in project templates
+   * 2. `<template>.ejs` in project templates
+   * 3. `<template>-<locale>.ejs` in nest-server templates (fallback)
+   * 4. `<template>.ejs` in nest-server templates (fallback)
+   *
+   * @default 'email-verification'
+   */
+  template?: string;
+}
+
 /**
  * JWT plugin configuration for Better-Auth
  *
@@ -426,6 +548,59 @@ export interface IBetterAuthRateLimit {
   windowSeconds?: number;
 }
 
+/**
+ * Sign-up checks configuration for Better-Auth
+ *
+ * Controls which fields are required during sign-up.
+ * This is useful for enforcing terms acceptance, age verification, etc.
+ *
+ * **Enabled by Default:** Sign-up checks are enabled by default with
+ * `requiredFields: ['termsAndPrivacyAccepted']`.
+ *
+ * Accepts:
+ * - `undefined`: Enabled with defaults (`termsAndPrivacyAccepted` required)
+ * - `true` or `{}`: Enable with defaults (same as undefined)
+ * - `{ requiredFields: [...] }`: Enable with custom required fields
+ * - `false` or `{ enabled: false }`: Disable sign-up checks entirely
+ *
+ * @since 11.13.0
+ *
+ * @example
+ * ```typescript
+ * // Default: termsAndPrivacyAccepted is required
+ * betterAuth: {}
+ *
+ * // Custom required fields
+ * betterAuth: {
+ *   signUpChecks: {
+ *     requiredFields: ['termsAndPrivacyAccepted', 'ageConfirmed'],
+ *   }
+ * }
+ *
+ * // Disable sign-up checks (no fields required)
+ * betterAuth: {
+ *   signUpChecks: false,
+ * }
+ * ```
+ */
+export interface IBetterAuthSignUpChecksConfig {
+  /**
+   * Whether sign-up checks are enabled.
+   * @default true (enabled by default when BetterAuth is active)
+   */
+  enabled?: boolean;
+
+  /**
+   * Fields that must be provided and truthy during sign-up.
+   * If a required field is missing or falsy, sign-up will fail.
+   *
+   * @default ['termsAndPrivacyAccepted']
+   *
+   * @example ['termsAndPrivacyAccepted', 'ageConfirmed', 'newsletterOptIn']
+   */
+  requiredFields?: string[];
+}
+
 /**
  * Interface for better-auth social provider configuration
  *
@@ -1498,6 +1673,39 @@ interface IBetterAuthBase {
     enabled?: boolean;
   };
 
+  /**
+   * Email verification configuration.
+   *
+   * **Enabled by Default:** Email verification is enabled by default.
+   * Users receive a verification email after sign-up.
+   *
+   * Accepts:
+   * - `undefined`: Enabled with defaults (zero-config)
+   * - `true` or `{}`: Enable with defaults (same as undefined)
+   * - `{ locale: 'de', ... }`: Enable with custom settings
+   * - `false` or `{ enabled: false }`: Explicitly disable
+   *
+   * @default undefined (enabled by default)
+   * @since 11.13.0
+   *
+   * @example
+   * ```typescript
+   * // Email verification enabled by default - no config needed
+   *
+   * // Custom configuration
+   * betterAuth: {
+   *   emailVerification: {
+   *     locale: 'de',
+   *     autoSignInAfterVerification: true,
+   *   }
+   * }
+   *
+   * // Disable email verification
+   * betterAuth: { emailVerification: false }
+   * ```
+   */
+  emailVerification?: boolean | IBetterAuthEmailVerificationConfig;
+
   /**
    * Whether better-auth is enabled.
    *
@@ -1631,6 +1839,38 @@ interface IBetterAuthBase {
    */
   secret?: string;
 
+  /**
+   * Sign-up checks configuration.
+   *
+   * **Enabled by Default:** Sign-up checks are enabled by default with
+   * `requiredFields: ['termsAndPrivacyAccepted']`.
+   *
+   * Accepts:
+   * - `undefined`: Enabled with defaults (termsAndPrivacyAccepted required)
+   * - `true` or `{}`: Enable with defaults (same as undefined)
+   * - `{ requiredFields: [...] }`: Enable with custom required fields
+   * - `false` or `{ enabled: false }`: Disable sign-up checks entirely
+   *
+   * @default undefined (enabled by default)
+   * @since 11.13.0
+   *
+   * @example
+   * ```typescript
+   * // Default: termsAndPrivacyAccepted is required during sign-up
+   *
+   * // Custom required fields
+   * betterAuth: {
+   *   signUpChecks: {
+   *     requiredFields: ['termsAndPrivacyAccepted', 'ageConfirmed'],
+   *   }
+   * }
+   *
+   * // Disable sign-up checks (no fields required)
+   * betterAuth: { signUpChecks: false }
+   * ```
+   */
+  signUpChecks?: boolean | IBetterAuthSignUpChecksConfig;
+
   /**
    * Social login providers configuration
    * Supports all Better-Auth providers dynamically (google, github, apple, discord, etc.)

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

@@ -58,6 +58,8 @@ GraphQL schema is built from decorators at compile time. The parent class (`Core
 
 **Note:** `@UseGuards(AuthGuard(JWT))` is NOT needed when using `@Roles(S_USER)` or `@Roles(ADMIN)` because `RolesGuard` already extends `AuthGuard(JWT)` internally.
 
+**Sign-Up Validation (v11.13.0+):** The resolver includes `CoreBetterAuthSignUpValidatorService` injection with `@Optional()`. This enables the `termsAndPrivacyAccepted` parameter on the `betterAuthSignUp` mutation.
+
 ---
 
 ### 4. Update UserService (CRITICAL!)
@@ -178,6 +180,103 @@ const config = {
 
 ---
 
+## Email Verification (v11.13.0+)
+
+Email verification is **enabled by default** via Better-Auth's `emailVerification` plugin.
+
+### Default Behavior
+
+- Users receive a verification email after sign-up
+- Email contains a verification link with token
+- After verification, `verifiedAt` is automatically set on the user
+- Templates are provided in German and English
+
+### Configuration
+
+```typescript
+const config = {
+  betterAuth: {
+    // Email verification is enabled by default
+    // To customize:
+    emailVerification: {
+      expiresIn: 86400,           // Token expiration in seconds (default: 24h)
+      template: 'custom-verify',  // Custom template name
+      locale: 'en',               // Template locale (default: 'de')
+    },
+    // To disable:
+    emailVerification: false,
+  },
+};
+```
+
+### Custom Email Templates
+
+Create custom templates in your project's templates directory:
+- `templates/email-verification-de.ejs` - German
+- `templates/email-verification-en.ejs` - English
+
+Available variables: `name`, `link`, `expiresIn`, `appName`
+
+---
+
+## Sign-Up Checks (v11.13.0+)
+
+Sign-up validation is **enabled by default** requiring `termsAndPrivacyAccepted`.
+
+### Default Behavior
+
+- `termsAndPrivacyAccepted: true` is required for sign-up
+- When accepted, `termsAndPrivacyAcceptedAt` is stored in the user record
+- Sign-up fails with error `LTNS_0021` if not accepted
+
+### GraphQL Usage
+
+```graphql
+mutation {
+  betterAuthSignUp(
+    email: "user@example.com"
+    password: "hashedPassword"
+    name: "User Name"
+    termsAndPrivacyAccepted: true  # Required by default
+  ) {
+    success
+    user { id email }
+  }
+}
+```
+
+### Configuration
+
+```typescript
+const config = {
+  betterAuth: {
+    // Sign-up checks are enabled by default
+    // To customize required fields:
+    signUpChecks: {
+      requiredFields: ['termsAndPrivacyAccepted', 'ageConfirmed'],
+    },
+    // To disable all sign-up checks:
+    signUpChecks: false,
+  },
+};
+```
+
+### REST API
+
+For REST sign-up, include `termsAndPrivacyAccepted` in the request body:
+
+```json
+POST /iam/sign-up/email
+{
+  "email": "user@example.com",
+  "password": "hashedPassword",
+  "name": "User Name",
+  "termsAndPrivacyAccepted": true
+}
+```
+
+---
+
 ## Verification Checklist
 
 After integration, verify:
@@ -189,6 +288,16 @@ After integration, verify:
 - [ ] Sign-up via BetterAuth creates user in database with `iamId`
 - [ ] Sign-in via BetterAuth works correctly
 
+### Additional checks for v11.13.0+ features:
+- [ ] Sign-up without `termsAndPrivacyAccepted` returns error `LTNS_0021`
+- [ ] Sign-up with `termsAndPrivacyAccepted: true` succeeds
+- [ ] User record contains `termsAndPrivacyAcceptedAt` timestamp after sign-up
+- [ ] Email verification link is sent after sign-up (check console in local mode)
+- [ ] After clicking verification link, `verifiedAt` is set on user
+- [ ] Passkey login returns user data in response (verify enrichment works)
+- [ ] Passkey login redirects to dashboard after successful authentication
+- [ ] Passkey can be registered, listed, and deleted from security settings
+
 ### Additional checks for Migration scenario:
 - [ ] Sign-in via Legacy Auth works for BetterAuth-created users
 - [ ] Sign-in via BetterAuth works for Legacy-created users
@@ -206,6 +315,8 @@ After integration, verify:
 | 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 |
 | AuthResolver override missing `checkLegacyGraphQLEnabled()` | Legacy endpoint disabling doesn't work (no HTTP 410) | Call `this.checkLegacyGraphQLEnabled('signIn')` in overrides |
+| Missing `signUpValidator` in custom Resolver (v11.13.0+) | Sign-up validation not working | Add `@Optional() signUpValidator?: CoreBetterAuthSignUpValidatorService` to constructor and pass to `super()` |
+| Missing `termsAndPrivacyAccepted` parameter in Resolver (v11.13.0+) | GraphQL error "Unknown argument" | Add `@Args('termsAndPrivacyAccepted', { nullable: true })` to `betterAuthSignUp` method |
 
 ---
 
@@ -361,6 +472,8 @@ Handle passkey authentication with session validation fallback.
 
 **IMPORTANT:** For JWT mode (`cookies: false`), you MUST use the `authenticateWithPasskey()` function from the composable instead of `authClient.signIn.passkey()` directly. This is because JWT mode requires sending a `challengeId` to the server for challenge verification.
 
+**Note on Passkey Login Response (v11.13.0+):** The server enriches the passkey verify-authentication response with user data. Better Auth's passkey plugin only returns `{ session }`, but the server fetches the user from the database and adds it to the response. The composable handles both scenarios (user in response vs. fallback to get-session).
+
 ```typescript
 // login.vue - Passkey login (JWT-compatible)
 // Use authenticateWithPasskey from useBetterAuth composable

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

@@ -48,6 +48,8 @@ const config = {
 - **JWT Tokens** - For API clients and stateless authentication (**enabled by default**)
 - **Two-Factor Authentication (2FA)** - TOTP-based second factor (**enabled by default**)
 - **Passkey/WebAuthn** - Passwordless authentication (**enabled by default**, requires resolvable URLs)
+- **Email Verification** - Verify user email addresses (**enabled by default** since v11.13.0)
+- **Sign-Up Checks** - Validate sign-up requirements like `termsAndPrivacyAccepted` (**enabled by default** since v11.13.0)
 
 ### Core Features
 
@@ -497,6 +499,66 @@ export default {
 
 ## Advanced Configuration
 
+### Email Verification (v11.13.0+)
+
+Email verification is **enabled by default**. Users receive a verification email after sign-up and `verifiedAt` is automatically set when verified.
+
+```typescript
+const config = {
+  betterAuth: {
+    // Email verification is enabled by default
+    // To customize:
+    emailVerification: {
+      expiresIn: 86400,           // Token expiration in seconds (default: 24h)
+      template: 'custom-verify',  // Custom template name
+      locale: 'en',               // Template locale (default: 'de')
+      brevoTemplateId: 42,        // Send via Brevo transactional API (optional)
+    },
+    // To disable:
+    emailVerification: false,
+  },
+};
+```
+
+**Custom Templates:** Create `templates/email-verification-{locale}.ejs` in your project. Available variables: `name`, `link`, `expiresIn`, `appName`.
+
+**Brevo Integration:** When `brevoTemplateId` is set and Brevo is configured (`config.brevo`), verification emails are sent via Brevo's transactional API instead of SMTP/EJS templates. The same template variables (`name`, `link`, `appName`, `expiresIn`) are passed to the Brevo template.
+
+### Sign-Up Checks (v11.13.0+)
+
+Sign-up validation is **enabled by default** requiring `termsAndPrivacyAccepted: true`.
+
+```typescript
+const config = {
+  betterAuth: {
+    // Sign-up checks are enabled by default
+    // To customize required fields:
+    signUpChecks: {
+      requiredFields: ['termsAndPrivacyAccepted', 'ageConfirmed'],
+    },
+    // To disable all sign-up checks:
+    signUpChecks: false,
+  },
+};
+```
+
+When `termsAndPrivacyAccepted: true` is provided, `termsAndPrivacyAcceptedAt` is automatically stored in the user record.
+
+**GraphQL Example:**
+```graphql
+mutation {
+  betterAuthSignUp(
+    email: "user@example.com"
+    password: "hashedPassword"
+    name: "User"
+    termsAndPrivacyAccepted: true  # Required by default
+  ) {
+    success
+    user { id email }
+  }
+}
+```
+
 ### Email/Password Authentication
 
 Email/password authentication is enabled by default. You can disable it if you only want social login:
@@ -939,12 +1001,14 @@ In addition to REST endpoints, Better-Auth provides GraphQL queries and mutation
 
 #### Authentication
 
-| Mutation              | Arguments                    | Return Type          | Description               |
-| --------------------- | ---------------------------- | -------------------- | ------------------------- |
-| `betterAuthSignIn`    | `email`, `password`          | `BetterAuthAuthModel`| Sign in with email/pass   |
-| `betterAuthSignUp`    | `email`, `password`, `name?` | `BetterAuthAuthModel`| Register new account      |
-| `betterAuthSignOut`   | -                            | `Boolean`            | Sign out (requires auth)  |
-| `betterAuthVerify2FA` | `code`                       | `BetterAuthAuthModel`| Verify 2FA code           |
+| Mutation              | Arguments                                    | Return Type          | Description               |
+| --------------------- | -------------------------------------------- | -------------------- | ------------------------- |
+| `betterAuthSignIn`    | `email`, `password`                          | `BetterAuthAuthModel`| Sign in with email/pass   |
+| `betterAuthSignUp`    | `email`, `password`, `name?`, `termsAndPrivacyAccepted?` | `BetterAuthAuthModel`| Register new account      |
+| `betterAuthSignOut`   | -                                            | `Boolean`            | Sign out (requires auth)  |
+| `betterAuthVerify2FA` | `code`                                       | `BetterAuthAuthModel`| Verify 2FA code           |
+
+**Note (v11.13.0+):** `termsAndPrivacyAccepted` is required by default. Set `signUpChecks: false` to disable.
 
 #### 2FA Management (requires authentication)
 
@@ -1054,12 +1118,13 @@ mutation {
   }
 }
 
-# Sign up
+# Sign up (v11.13.0+: termsAndPrivacyAccepted required by default)
 mutation {
   betterAuthSignUp(
     email: "newuser@example.com"
     password: "securePassword123"
     name: "New User"
+    termsAndPrivacyAccepted: true
   ) {
     success
     user {