@lenne.tech/nest-server 11.6.1 → 11.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.6.1",
+  "version": "11.6.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",
@@ -77,6 +77,8 @@
     "node": ">= 20"
   },
   "dependencies": {
+    "@apollo/server": "4.12.2",
+    "@better-auth/passkey": "1.4.7",
     "@getbrevo/brevo": "3.0.1",
     "@nestjs/apollo": "13.1.0",
     "@nestjs/common": "11.1.9",
@@ -89,8 +91,11 @@
     "@nestjs/schedule": "6.1.0",
     "@nestjs/swagger": "11.2.3",
     "@nestjs/terminus": "11.0.0",
+    "@nestjs/websockets": "11.1.9",
+    "@thallesp/nestjs-better-auth": "2.2.0",
     "apollo-server-core": "3.13.0",
     "bcrypt": "6.0.0",
+    "better-auth": "1.4.7",
     "class-transformer": "0.5.1",
     "class-validator": "0.14.3",
     "compression": "1.8.1",
@@ -174,6 +179,9 @@
       "flat": "5.0.2",
       "mime": "2.6.0"
     },
+    "better-auth": {
+      "mongodb": "7.0.0"
+    },
     "ts-morph": "27.0.2"
   },
   "jest": {

package/src/config.env.ts

@@ -15,6 +15,54 @@ const config: { [env: string]: IServerOptions } = {
   // ===========================================================================
   development: {
     automaticObjectIdFiltering: true,
+    betterAuth: {
+      basePath: '/iam',
+      baseUrl: 'http://localhost:3000',
+      // enabled: true by default - set false to explicitly disable
+      jwt: {
+        enabled: true,
+        expiresIn: '15m',
+      },
+      legacyPassword: {
+        enabled: true,
+      },
+      passkey: {
+        enabled: false,
+        origin: 'http://localhost:3000',
+        rpId: 'localhost',
+        rpName: 'Nest Server Development',
+      },
+      rateLimit: {
+        enabled: true,
+        max: 20,
+        message: 'Too many requests, please try again later.',
+        skipEndpoints: ['/session', '/callback'],
+        strictEndpoints: ['/sign-in', '/sign-up', '/forgot-password', '/reset-password'],
+        windowSeconds: 60,
+      },
+      secret: 'BETTER_AUTH_SECRET_DEV_32_CHARS_MIN',
+      socialProviders: {
+        apple: {
+          clientId: process.env.SOCIAL_APPLE_CLIENT_ID || '',
+          clientSecret: process.env.SOCIAL_APPLE_CLIENT_SECRET || '',
+          enabled: false,
+        },
+        github: {
+          clientId: process.env.SOCIAL_GITHUB_CLIENT_ID || '',
+          clientSecret: process.env.SOCIAL_GITHUB_CLIENT_SECRET || '',
+          enabled: false,
+        },
+        google: {
+          clientId: process.env.SOCIAL_GOOGLE_CLIENT_ID || '',
+          clientSecret: process.env.SOCIAL_GOOGLE_CLIENT_SECRET || '',
+          enabled: false,
+        },
+      },
+      twoFactor: {
+        appName: 'Nest Server Development',
+        enabled: false,
+      },
+    },
     compression: true,
     cookies: false,
     email: {
@@ -114,10 +162,58 @@ const config: { [env: string]: IServerOptions } = {
   },
 
   // ===========================================================================
-  // Development environment
+  // Local environment
   // ===========================================================================
   local: {
     automaticObjectIdFiltering: true,
+    betterAuth: {
+      basePath: '/iam',
+      baseUrl: 'http://localhost:3000',
+      // enabled: true by default - set false to explicitly disable
+      jwt: {
+        enabled: true,
+        expiresIn: '15m',
+      },
+      legacyPassword: {
+        enabled: true,
+      },
+      passkey: {
+        enabled: false,
+        origin: 'http://localhost:3000',
+        rpId: 'localhost',
+        rpName: 'Nest Server Local',
+      },
+      rateLimit: {
+        enabled: true,
+        max: 20,
+        message: 'Too many requests, please try again later.',
+        skipEndpoints: ['/session', '/callback'],
+        strictEndpoints: ['/sign-in', '/sign-up', '/forgot-password', '/reset-password'],
+        windowSeconds: 60,
+      },
+      secret: 'BETTER_AUTH_SECRET_LOCAL_32_CHARS_M',
+      socialProviders: {
+        apple: {
+          clientId: process.env.SOCIAL_APPLE_CLIENT_ID || '',
+          clientSecret: process.env.SOCIAL_APPLE_CLIENT_SECRET || '',
+          enabled: false,
+        },
+        github: {
+          clientId: process.env.SOCIAL_GITHUB_CLIENT_ID || '',
+          clientSecret: process.env.SOCIAL_GITHUB_CLIENT_SECRET || '',
+          enabled: false,
+        },
+        google: {
+          clientId: process.env.SOCIAL_GOOGLE_CLIENT_ID || '',
+          clientSecret: process.env.SOCIAL_GOOGLE_CLIENT_SECRET || '',
+          enabled: false,
+        },
+      },
+      twoFactor: {
+        appName: 'Nest Server Local',
+        enabled: false,
+      },
+    },
     compression: true,
     cookies: false,
     cronJobs: {
@@ -232,6 +328,57 @@ const config: { [env: string]: IServerOptions } = {
   // ===========================================================================
   production: {
     automaticObjectIdFiltering: true,
+    betterAuth: {
+      basePath: '/iam',
+      baseUrl: process.env.BETTER_AUTH_URL || 'https://example.com',
+      // enabled: true by default - set false to explicitly disable
+      jwt: {
+        enabled: true,
+        expiresIn: '15m',
+      },
+      legacyPassword: {
+        enabled: true,
+      },
+      passkey: {
+        enabled: false,
+        origin: process.env.BETTER_AUTH_URL || 'https://example.com',
+        rpId: process.env.PASSKEY_RP_ID || 'example.com',
+        rpName: process.env.PASSKEY_RP_NAME || 'Nest Server Production',
+      },
+      rateLimit: {
+        enabled: process.env.RATE_LIMIT_ENABLED !== 'false',
+        max: parseInt(process.env.RATE_LIMIT_MAX || '10', 10),
+        message: process.env.RATE_LIMIT_MESSAGE || 'Too many requests, please try again later.',
+        skipEndpoints: ['/session', '/callback'],
+        strictEndpoints: ['/sign-in', '/sign-up', '/forgot-password', '/reset-password'],
+        windowSeconds: parseInt(process.env.RATE_LIMIT_WINDOW_SECONDS || '60', 10),
+      },
+      // IMPORTANT: Set BETTER_AUTH_SECRET in production!
+      // Without it, an insecure default is used which allows session forgery.
+      // Generate with: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
+      secret: process.env.BETTER_AUTH_SECRET,
+      socialProviders: {
+        apple: {
+          clientId: process.env.SOCIAL_APPLE_CLIENT_ID || '',
+          clientSecret: process.env.SOCIAL_APPLE_CLIENT_SECRET || '',
+          enabled: !!process.env.SOCIAL_APPLE_CLIENT_ID,
+        },
+        github: {
+          clientId: process.env.SOCIAL_GITHUB_CLIENT_ID || '',
+          clientSecret: process.env.SOCIAL_GITHUB_CLIENT_SECRET || '',
+          enabled: !!process.env.SOCIAL_GITHUB_CLIENT_ID,
+        },
+        google: {
+          clientId: process.env.SOCIAL_GOOGLE_CLIENT_ID || '',
+          clientSecret: process.env.SOCIAL_GOOGLE_CLIENT_SECRET || '',
+          enabled: !!process.env.SOCIAL_GOOGLE_CLIENT_ID,
+        },
+      },
+      twoFactor: {
+        appName: process.env.TWO_FACTOR_APP_NAME || 'Nest Server',
+        enabled: process.env.TWO_FACTOR_ENABLED === 'true',
+      },
+    },
     compression: true,
     cookies: false,
     email: {

package/src/core/common/decorators/restricted.decorator.ts

@@ -61,7 +61,7 @@ export const getRestricted = (object: unknown, propertyKey?: string): Restricted
  */
 export const checkRestricted = (
   data: any,
-  user: { hasRole: (roles: string[]) => boolean; id: any; verified?: any; verifiedAt?: any },
+  user: { emailVerified?: any; hasRole: (roles: string[]) => boolean; id: any; verified?: any; verifiedAt?: any },
   options: {
     allowCreatorOfParent?: boolean;
     checkObjectItself?: boolean;
@@ -163,7 +163,7 @@ export const checkRestricted = (
         (roles.includes(RoleEnum.S_CREATOR) &&
           (('createdBy' in data && equalIds(data.createdBy, user)) ||
             (config.allowCreatorOfParent && !('createdBy' in data) && config.isCreatorOfParent))) ||
-        (roles.includes(RoleEnum.S_VERIFIED) && (user?.verified || user?.verifiedAt))
+        (roles.includes(RoleEnum.S_VERIFIED) && (user?.verified || user?.verifiedAt || user?.emailVerified))
       ) {
         valid = true;
       }

package/src/core/common/helpers/input.helper.ts

@@ -209,7 +209,7 @@ export function assignPlain(target: Record<any, any>, ...args: Record<any, any>[
  */
 export async function check(
   value: any,
-  user: { hasRole: (roles: string[]) => boolean; id: any; verified?: any; verifiedAt?: any },
+  user: { emailVerified?: any; hasRole: (roles: string[]) => boolean; id: any; verified?: any; verifiedAt?: any },
   options?: {
     allowCreatorOfParent?: boolean;
     dbObject?: any;
@@ -264,7 +264,7 @@ export async function check(
             !('createdBy' in config.dbObject) &&
             config.isCreatorOfParent))) ||
       // check if the is verified
-      (roles.includes(RoleEnum.S_VERIFIED) && (user?.verified || user?.verifiedAt))
+      (roles.includes(RoleEnum.S_VERIFIED) && (user?.verified || user?.verifiedAt || user?.emailVerified))
     ) {
       valid = true;
     }

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

@@ -16,6 +16,324 @@ import { CronJobConfigWithTimeZone } from './cron-job-config-with-time-zone.inte
 import { CronJobConfigWithUtcOffset } from './cron-job-config-with-utc-offset.interface';
 import { MailjetOptions } from './mailjet-options.interface';
 
+/**
+ * Better-Auth field type definition
+ * Matches the DBFieldType from better-auth
+ */
+export type BetterAuthFieldType = 'boolean' | 'date' | 'json' | 'number' | 'number[]' | 'string' | 'string[]';
+
+/**
+ * Interface for better-auth configuration
+ */
+export interface IBetterAuth {
+  /**
+   * Additional user fields beyond the core fields (firstName, lastName, etc.)
+   * These fields will be merged with the default user fields.
+   * @see https://www.better-auth.com/docs/concepts/users-accounts#additional-fields
+   * @example
+   * ```typescript
+   * additionalUserFields: {
+   *   phoneNumber: { type: 'string', defaultValue: null },
+   *   department: { type: 'string', required: true },
+   *   preferences: { type: 'string', defaultValue: '{}' },
+   * }
+   * ```
+   */
+  additionalUserFields?: Record<string, IBetterAuthUserField>;
+
+  /**
+   * Base path for better-auth endpoints
+   * default: '/iam'
+   */
+  basePath?: string;
+
+  /**
+   * Base URL of the application
+   * e.g. 'http://localhost:3000'
+   */
+  baseUrl?: string;
+
+  /**
+   * Whether better-auth is enabled.
+   * BetterAuth is enabled by default (zero-config philosophy).
+   * Set to false to explicitly disable it.
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * JWT plugin configuration for API clients.
+   * Enabled by default when this config block is present.
+   * Set `enabled: false` to explicitly disable.
+   */
+  jwt?: {
+    /**
+     * Whether JWT plugin is enabled.
+     * @default true (when jwt config block is present)
+     */
+    enabled?: boolean;
+
+    /**
+     * JWT expiration time
+     * @default '15m'
+     */
+    expiresIn?: string;
+  };
+
+  /**
+   * Legacy password handling configuration.
+   * Used during migration from old auth system.
+   * Enabled by default when this config block is present.
+   * Set `enabled: false` to explicitly disable.
+   */
+  legacyPassword?: {
+    /**
+     * Whether legacy password handling is enabled.
+     * @default true (when legacyPassword config block is present)
+     */
+    enabled?: boolean;
+  };
+
+  /**
+   * Advanced Better-Auth options passthrough.
+   * These options are passed directly to Better-Auth, allowing full customization.
+   * Use this for any Better-Auth options not explicitly defined in this interface.
+   * @see https://www.better-auth.com/docs/reference/options
+   * @example
+   * ```typescript
+   * options: {
+   *   emailAndPassword: {
+   *     enabled: true,
+   *     requireEmailVerification: true,
+   *     sendResetPassword: async ({ user, url }) => { ... },
+   *   },
+   *   account: {
+   *     accountLinking: { enabled: true },
+   *   },
+   *   session: {
+   *     expiresIn: 60 * 60 * 24 * 7, // 7 days
+   *     updateAge: 60 * 60 * 24, // 1 day
+   *   },
+   *   advanced: {
+   *     cookiePrefix: 'my-app',
+   *     useSecureCookies: true,
+   *   },
+   * }
+   * ```
+   */
+  options?: Record<string, unknown>;
+
+  /**
+   * Passkey/WebAuthn configuration.
+   * Enabled by default when this config block is present.
+   * Set `enabled: false` to explicitly disable.
+   */
+  passkey?: {
+    /**
+     * Whether passkey authentication is enabled.
+     * @default true (when passkey config block is present)
+     */
+    enabled?: boolean;
+
+    /**
+     * Origin URL for WebAuthn
+     * e.g. 'http://localhost:3000'
+     */
+    origin?: string;
+
+    /**
+     * Relying Party ID (usually the domain)
+     * e.g. 'localhost' or 'example.com'
+     */
+    rpId?: string;
+
+    /**
+     * Relying Party Name (displayed to users)
+     * e.g. 'My Application'
+     */
+    rpName?: string;
+  };
+
+  /**
+   * Additional Better-Auth plugins to include.
+   * These will be merged with the built-in plugins (jwt, twoFactor, passkey).
+   * @see https://www.better-auth.com/docs/plugins
+   * @example
+   * ```typescript
+   * import { organization } from 'better-auth/plugins';
+   * import { magicLink } from 'better-auth/plugins';
+   *
+   * plugins: [
+   *   organization({ ... }),
+   *   magicLink({ ... }),
+   * ]
+   * ```
+   */
+  plugins?: unknown[];
+
+  /**
+   * Rate limiting configuration for Better-Auth endpoints
+   * Protects against brute-force attacks
+   */
+  rateLimit?: IBetterAuthRateLimit;
+
+  /**
+   * Secret for better-auth (min 32 characters)
+   * Used for session encryption
+   */
+  secret?: string;
+
+  /**
+   * Social login providers configuration
+   * Supports all Better-Auth providers dynamically (google, github, apple, discord, etc.)
+   *
+   * **Enabled by default:** Providers are automatically enabled when credentials
+   * are configured. Set `enabled: false` to explicitly disable a provider.
+   *
+   * @see https://www.better-auth.com/docs/authentication/social-sign-in
+   * @example
+   * ```typescript
+   * socialProviders: {
+   *   // These providers are enabled (no need for enabled: true)
+   *   google: { clientId: '...', clientSecret: '...' },
+   *   github: { clientId: '...', clientSecret: '...' },
+   *   // This provider is explicitly disabled
+   *   discord: { clientId: '...', clientSecret: '...', enabled: false },
+   * }
+   * ```
+   */
+  socialProviders?: Record<string, IBetterAuthSocialProvider>;
+
+  /**
+   * Trusted origins for CORS and OAuth callbacks
+   * If not specified, defaults to [baseUrl]
+   * e.g. ['https://example.com', 'https://app.example.com']
+   */
+  trustedOrigins?: string[];
+
+  /**
+   * Two-factor authentication configuration.
+   * Enabled by default when this config block is present.
+   * Set `enabled: false` to explicitly disable.
+   */
+  twoFactor?: {
+    /**
+     * App name shown in authenticator apps
+     * e.g. 'My Application'
+     */
+    appName?: string;
+
+    /**
+     * Whether 2FA is enabled.
+     * @default true (when twoFactor config block is present)
+     */
+    enabled?: boolean;
+  };
+}
+
+/**
+ * Interface for Better-Auth rate limiting configuration
+ */
+export interface IBetterAuthRateLimit {
+  /**
+   * Whether rate limiting is enabled
+   * default: false
+   */
+  enabled?: boolean;
+
+  /**
+   * Maximum number of requests within the time window
+   * default: 10
+   */
+  max?: number;
+
+  /**
+   * Custom message when rate limit is exceeded
+   * default: 'Too many requests, please try again later.'
+   */
+  message?: string;
+
+  /**
+   * Endpoints to skip rate limiting entirely
+   * e.g., ['/iam/session'] for session checks
+   */
+  skipEndpoints?: string[];
+
+  /**
+   * Endpoints to apply stricter rate limiting (e.g., sign-in, sign-up)
+   * These endpoints will have half the max requests
+   */
+  strictEndpoints?: string[];
+
+  /**
+   * Time window in seconds
+   * default: 60 (1 minute)
+   */
+  windowSeconds?: number;
+}
+
+/**
+ * Interface for better-auth social provider configuration
+ *
+ * **Enabled by default:** A social provider is automatically enabled when
+ * both `clientId` and `clientSecret` are provided. You only need to set
+ * `enabled: false` to explicitly disable a configured provider.
+ *
+ * @example
+ * ```typescript
+ * // Provider is enabled (has credentials, no explicit enabled flag needed)
+ * google: { clientId: '...', clientSecret: '...' }
+ *
+ * // Provider is explicitly disabled despite having credentials
+ * github: { clientId: '...', clientSecret: '...', enabled: false }
+ * ```
+ */
+export interface IBetterAuthSocialProvider {
+  /**
+   * OAuth client ID
+   */
+  clientId: string;
+
+  /**
+   * OAuth client secret
+   */
+  clientSecret: string;
+
+  /**
+   * Whether this provider is enabled.
+   * Defaults to true when clientId and clientSecret are provided.
+   * Set to false to explicitly disable this provider.
+   * @default true (when credentials are configured)
+   */
+  enabled?: boolean;
+}
+
+/**
+ * Interface for additional user fields in Better-Auth
+ * @see https://www.better-auth.com/docs/concepts/users-accounts#additional-fields
+ */
+export interface IBetterAuthUserField {
+  /**
+   * Default value for the field
+   */
+  defaultValue?: unknown;
+
+  /**
+   * Database field name (if different from key)
+   */
+  fieldName?: string;
+
+  /**
+   * Whether this field is required
+   */
+  required?: boolean;
+
+  /**
+   * Field type
+   */
+  type: BetterAuthFieldType;
+}
+
 /**
  * Interface for JWT configuration (main and refresh)
  */
@@ -71,6 +389,12 @@ export interface IServerOptions {
    */
   automaticObjectIdFiltering?: boolean;
 
+  /**
+   * Configuration for better-auth authentication framework
+   * See: https://better-auth.com
+   */
+  betterAuth?: IBetterAuth;
+
   /**
    * Configuration for Brevo
    * See: https://developers.brevo.com/
@@ -324,29 +648,29 @@ export interface IServerOptions {
    * Hint: The secrets of the different environments should be different, otherwise a JWT can be used in different
    * environments, which can lead to security vulnerabilities.
    */
-  jwt?: IJwt & JwtModuleOptions &
-    {
-    /**
-     * Configuration for refresh Token (JWT)
-     * Hint: The secret of the JWT and the Refresh Token should be different, otherwise a new RefreshToken can also be
-     * requested with the JWT, which can lead to a security vulnerability.
-     */
-    refresh?: IJwt & {
+  jwt?: IJwt &
+    JwtModuleOptions & {
       /**
-       * Whether renewal of the refresh token is permitted
-       * If falsy (default): during refresh only a new token, the refresh token retains its original term
-       * If true: during refresh not only a new token but also a new refresh token is created
+       * Configuration for refresh Token (JWT)
+       * Hint: The secret of the JWT and the Refresh Token should be different, otherwise a new RefreshToken can also be
+       * requested with the JWT, which can lead to a security vulnerability.
        */
-      renewal?: boolean;
-    };
+      refresh?: IJwt & {
+        /**
+         * Whether renewal of the refresh token is permitted
+         * If falsy (default): during refresh only a new token, the refresh token retains its original term
+         * If true: during refresh not only a new token but also a new refresh token is created
+         */
+        renewal?: boolean;
+      };
 
-    /**
-     * Time period in milliseconds
-     * in which the same token ID is used so that all parallel token refresh requests of a device can be generated.
-     * default: 0 (every token includes a new token ID, all parallel token refresh requests must be prevented by the client or processed accordingly)
-     */
-    sameTokenIdPeriod?: number;
-  };
+      /**
+       * Time period in milliseconds
+       * in which the same token ID is used so that all parallel token refresh requests of a device can be generated.
+       * default: 0 (every token includes a new token ID, all parallel token refresh requests must be prevented by the client or processed accordingly)
+       */
+      sameTokenIdPeriod?: number;
+    };
 
   /**
    * Load local configuration

package/src/core/modules/auth/auth-guard-strategy.enum.ts

@@ -1,4 +1,5 @@
 export enum AuthGuardStrategy {
+  BETTER_AUTH = 'better-auth',
   JWT = 'jwt',
   JWT_REFRESH = 'jwt-refresh',
 }

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

@@ -13,9 +13,9 @@ import { InvalidTokenException } from '../exceptions/invalid-token.exception';
 /**
  * Missing strategy error
  */
-const NO_STRATEGY_ERROR
-  = 'In order to use "defaultStrategy", please, ensure to import PassportModule in each '
-  + 'place where AuthGuard() is being used. Otherwise, passport won\'t work correctly.';
+const NO_STRATEGY_ERROR =
+  'In order to use "defaultStrategy", please, ensure to import PassportModule in each ' +
+  "place where AuthGuard() is being used. Otherwise, passport won't work correctly.";
 
 /**
  * Interface for auth guard
@@ -38,7 +38,7 @@ const createPassportContext = (request, response) => (type, options, callback: (
       } catch (err) {
         reject(err);
       }
-    })(request, response, err => (err ? reject(err) : resolve)),
+    })(request, response, (err) => (err ? reject(err) : resolve)),
   );
 
 /**
@@ -70,8 +70,22 @@ function createAuthGuard(type?: AuthGuardStrategy | string | string[]): Type<IAu
       }
 
       const options = { ...defaultOptions, ...this.options };
-      const response = context?.switchToHttp()?.getResponse();
       const request = this.getRequest(context);
+
+      // Check if user is already authenticated via Better-Auth middleware
+      // Only skip Passport for Better-Auth users (marked with _authenticatedViaBetterAuth)
+      // This ensures JWT_REFRESH guard still validates refresh tokens properly
+      const existingUser = request?.[options.property || defaultOptions.property];
+      if (existingUser && existingUser._authenticatedViaBetterAuth === true) {
+        // User is authenticated via Better-Auth - skip Passport authentication
+        // Validate through handleRequest to ensure role checks work
+        const validatedUser = this.handleRequest(null, existingUser, null, context);
+        request[options.property || defaultOptions.property] = validatedUser;
+        return true;
+      }
+
+      // Proceed with Passport authentication
+      const response = context?.switchToHttp()?.getResponse();
       const passportFn = createPassportContext(request, response);
       const user = await passportFn(type || this.options.defaultStrategy, options, (err, currentUser, info) =>
         this.handleRequest(err, currentUser, info, context),
@@ -101,7 +115,7 @@ function createAuthGuard(type?: AuthGuardStrategy | string | string[]): Type<IAu
      */
     async logIn<TRequest extends { logIn: (...params) => any } = any>(request: TRequest) {
       const user = request[this.options.property || defaultOptions.property];
-      await new Promise<void>((resolve, reject) => request.logIn(user, err => (err ? reject(err) : resolve())));
+      await new Promise<void>((resolve, reject) => request.logIn(user, (err) => (err ? reject(err) : resolve())));
     }
 
     /**