@lenne.tech/nest-server 11.6.0 → 11.6.2

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

@@ -0,0 +1,483 @@
+import { passkey } from '@better-auth/passkey';
+import { Logger } from '@nestjs/common';
+import { betterAuth, BetterAuthPlugin } from 'better-auth';
+import { mongodbAdapter } from 'better-auth/adapters/mongodb';
+import { jwt, twoFactor } from 'better-auth/plugins';
+import * as crypto from 'crypto';
+
+import { IBetterAuth } from '../../common/interfaces/server-options.interface';
+
+/**
+ * Type for better-auth instance with plugins
+ */
+export type BetterAuthInstance = ReturnType<typeof betterAuth>;
+
+/**
+ * Generates a cryptographically secure random secret.
+ * Used as fallback when no BETTER_AUTH_SECRET is configured.
+ *
+ * NOTE: This secret is generated at server startup, meaning:
+ * - All existing sessions become invalid on server restart
+ * - This is acceptable for development environments
+ * - For production, ALWAYS set BETTER_AUTH_SECRET to maintain sessions across restarts
+ */
+function generateSecureSecret(): string {
+  return crypto.randomBytes(32).toString('base64');
+}
+
+/**
+ * Cached auto-generated secret for the current server instance.
+ * Generated once at module load to ensure consistency within a single run.
+ */
+let cachedAutoGeneratedSecret: null | string = null;
+
+/**
+ * Options for creating a better-auth instance
+ */
+export interface CreateBetterAuthOptions {
+  /**
+   * Better-auth configuration from server options
+   */
+  config: IBetterAuth;
+
+  /**
+   * MongoDB database instance
+   * Note: Uses 'any' type to handle version incompatibilities between
+   * mongoose's bundled mongodb types and the project's mongodb package.
+   * At runtime, this is a mongodb.Db instance.
+   */
+  db: any;
+
+  /**
+   * Fallback secrets to try if no betterAuth.secret is configured.
+   * The array is iterated and the first valid secret (≥32 chars) is used.
+   * If no valid secret is found, an auto-generated secret is used.
+   *
+   * Typical usage: Pass existing secrets from your config (e.g., jwt.secret)
+   * for backwards compatibility.
+   *
+   * @example
+   * ```typescript
+   * fallbackSecrets: [config.jwt?.secret, config.jwt?.refresh?.secret]
+   * ```
+   */
+  fallbackSecrets?: (string | undefined)[];
+}
+
+/**
+ * Better-Auth field type definition
+ * Matches the DBFieldType from better-auth
+ */
+type BetterAuthFieldType = 'boolean' | 'date' | 'json' | 'number' | 'number[]' | 'string' | 'string[]';
+
+/**
+ * Social provider configuration for better-auth
+ */
+interface SocialProviderConfig {
+  clientId: string;
+  clientSecret: string;
+}
+
+/**
+ * User field configuration type for Better-Auth
+ * Matches the DBFieldAttribute structure from better-auth
+ */
+interface UserFieldConfig {
+  defaultValue?: unknown;
+  fieldName?: string;
+  required?: boolean;
+  type: BetterAuthFieldType;
+}
+
+/**
+ * Validation result for configuration
+ */
+interface ValidationResult {
+  errors: string[];
+  valid: boolean;
+  warnings: string[];
+}
+
+/**
+ * Creates a better-auth instance based on configuration
+ *
+ * @param options - Configuration options including betterAuth config and MongoDB connection
+ * @returns Configured better-auth instance or null if not enabled
+ * @throws Error if configuration validation fails
+ */
+export function createBetterAuthInstance(options: CreateBetterAuthOptions): BetterAuthInstance | null {
+  const logger = new Logger('BetterAuthConfig');
+  const { config, db, fallbackSecrets } = options;
+
+  // Return null only if better-auth is explicitly disabled
+  // BetterAuth is enabled by default (zero-config)
+  if (config?.enabled === false) {
+    return null;
+  }
+
+  // Validate configuration (with fallback secrets for backwards compatibility)
+  const validation = validateConfig(config, fallbackSecrets);
+
+  // Log warnings
+  for (const warning of validation.warnings) {
+    logger.warn(warning);
+  }
+
+  // Throw on validation errors
+  if (!validation.valid) {
+    throw new Error(`BetterAuth configuration invalid: ${validation.errors.join('; ')}`);
+  }
+
+  // Build configuration components
+  const plugins = buildPlugins(config);
+  const socialProviders = buildSocialProviders(config);
+  const trustedOrigins = buildTrustedOrigins(config);
+  const additionalFields = buildUserFields(config);
+
+  // Build the base Better-Auth configuration
+  const betterAuthConfig = {
+    basePath: config.basePath || '/iam',
+    baseURL: config.baseUrl || 'http://localhost:3000',
+    database: mongodbAdapter(db),
+    plugins,
+    secret: config.secret,
+    socialProviders,
+    trustedOrigins,
+    user: {
+      additionalFields,
+      modelName: 'users',
+    },
+  };
+
+  // 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;
+
+  // Create and return the better-auth instance
+  // Type assertion needed for maximum flexibility - allows projects to use any Better-Auth option
+
+  return betterAuth(finalConfig as any);
+}
+
+/**
+ * Builds the plugins array based on configuration.
+ * Merges built-in plugins (jwt, twoFactor, passkey) with custom plugins from config.
+ *
+ * Plugins are enabled by default when their configuration block is present.
+ * Set `enabled: false` to explicitly disable a configured plugin.
+ */
+function buildPlugins(config: IBetterAuth): BetterAuthPlugin[] {
+  const plugins: BetterAuthPlugin[] = [];
+
+  // JWT Plugin for API client compatibility
+  // Enabled by default when jwt config is present, unless explicitly disabled
+  if (config.jwt && config.jwt.enabled !== false) {
+    plugins.push(
+      jwt({
+        jwt: {
+          expirationTime: config.jwt.expiresIn || '15m',
+        },
+      }),
+    );
+  }
+
+  // Two-Factor Authentication Plugin
+  // Enabled by default when twoFactor config is present, unless explicitly disabled
+  if (config.twoFactor && config.twoFactor.enabled !== false) {
+    plugins.push(
+      twoFactor({
+        issuer: config.twoFactor.appName || 'Nest Server',
+      }),
+    );
+  }
+
+  // Passkey/WebAuthn Plugin
+  // Enabled by default when passkey config is present, unless explicitly disabled
+  if (config.passkey && config.passkey.enabled !== false) {
+    plugins.push(
+      passkey({
+        origin: config.passkey.origin || 'http://localhost:3000',
+        rpID: config.passkey.rpId || 'localhost',
+        rpName: config.passkey.rpName || 'Nest Server',
+      }),
+    );
+  }
+
+  // Merge custom plugins from configuration
+  // This allows projects to add any Better-Auth plugin without modifying this package
+  if (config.plugins?.length) {
+    plugins.push(...(config.plugins as BetterAuthPlugin[]));
+  }
+
+  return plugins;
+}
+
+/**
+ * Builds the social providers configuration object dynamically.
+ * Iterates over all configured providers and includes those that are enabled
+ * with valid clientId and clientSecret.
+ */
+function buildSocialProviders(config: IBetterAuth): Record<string, SocialProviderConfig> {
+  const socialProvidersConfig: Record<string, SocialProviderConfig> = {};
+
+  // Iterate over all configured social providers dynamically
+  // A provider is enabled by default if it has credentials configured
+  // It can be explicitly disabled by setting enabled: false
+  if (config.socialProviders) {
+    for (const [name, provider] of Object.entries(config.socialProviders)) {
+      if (provider?.clientId && provider?.clientSecret && provider?.enabled !== false) {
+        socialProvidersConfig[name] = {
+          clientId: provider.clientId,
+          clientSecret: provider.clientSecret,
+        };
+      }
+    }
+  }
+
+  return socialProvidersConfig;
+}
+
+/**
+ * Builds the trusted origins array
+ */
+function buildTrustedOrigins(config: IBetterAuth): string[] {
+  if (config.trustedOrigins?.length) {
+    return config.trustedOrigins;
+  }
+  if (config.baseUrl) {
+    return [config.baseUrl];
+  }
+  return ['http://localhost:3000'];
+}
+
+/**
+ * Builds the user additional fields configuration.
+ * Merges core fields (firstName, lastName, etc.) with custom fields from config.
+ * Custom fields override core fields if they have the same key.
+ */
+function buildUserFields(config: IBetterAuth): Record<string, UserFieldConfig> {
+  // Core fields required for nest-server functionality
+  const coreFields: Record<string, UserFieldConfig> = {
+    firstName: {
+      defaultValue: null,
+      fieldName: 'firstName',
+      type: 'string',
+    },
+    iamId: {
+      defaultValue: null,
+      fieldName: 'iamId',
+      type: 'string',
+    },
+    lastName: {
+      defaultValue: null,
+      fieldName: 'lastName',
+      type: 'string',
+    },
+    roles: {
+      defaultValue: [],
+      fieldName: 'roles',
+      type: 'string[]',
+    },
+    twoFactorEnabled: {
+      defaultValue: false,
+      fieldName: 'twoFactorEnabled',
+      type: 'boolean',
+    },
+    verified: {
+      defaultValue: false,
+      fieldName: 'verified',
+      type: 'boolean',
+    },
+  };
+
+  // Merge with custom additional fields from configuration
+  // Custom fields can override core fields or add new ones
+  if (config.additionalUserFields) {
+    for (const [key, field] of Object.entries(config.additionalUserFields)) {
+      coreFields[key] = {
+        defaultValue: field.defaultValue,
+        fieldName: field.fieldName || key,
+        required: field.required,
+        type: field.type,
+      };
+    }
+  }
+
+  return coreFields;
+}
+
+/**
+ * Gets or generates the fallback secret for development.
+ * The secret is cached to ensure consistency during the server's lifetime.
+ */
+function getAutoGeneratedSecret(): string {
+  if (!cachedAutoGeneratedSecret) {
+    cachedAutoGeneratedSecret = generateSecureSecret();
+  }
+  return cachedAutoGeneratedSecret;
+}
+
+/**
+ * Checks if a secret has valid minimum length (32 characters)
+ */
+function isValidSecretLength(secret: string): boolean {
+  return secret && secret.length >= 32;
+}
+
+/**
+ * Validates a URL string
+ */
+function isValidUrl(url: string): boolean {
+  try {
+    new URL(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validates the better-auth configuration and applies fallback secret if needed.
+ * Mutates config.secret if fallback is applied.
+ *
+ * Secret resolution order:
+ * 1. betterAuth.secret (if configured and valid)
+ * 2. First valid secret from fallbackSecrets array (≥32 chars)
+ * 3. Auto-generated secure secret (with warning)
+ *
+ * @param config - Better-auth configuration
+ * @param fallbackSecrets - Optional array of fallback secrets to try
+ */
+function validateConfig(config: IBetterAuth, fallbackSecrets?: (string | undefined)[]): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Track secret source for appropriate messaging
+  let secretSource: 'auto-generated' | 'explicit' | 'fallback' = 'explicit';
+
+  // Resolve secret with fallback chain
+  if (!config.secret || config.secret.trim() === '') {
+    // Try fallback secrets in order
+    const validFallback = fallbackSecrets?.find((secret) => secret && isValidSecretLength(secret));
+
+    if (validFallback) {
+      config.secret = validFallback;
+      secretSource = 'fallback';
+    } else {
+      // Last resort: auto-generate
+      config.secret = getAutoGeneratedSecret();
+      secretSource = 'auto-generated';
+    }
+  }
+
+  // Validate the resolved secret
+  const secretValidation = validateSecret(config.secret);
+  if (!secretValidation.valid) {
+    errors.push(secretValidation.message!);
+  } else if (secretValidation.message) {
+    warnings.push(secretValidation.message);
+  }
+
+  // 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(
+        '💡 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'))\"");
+      break;
+    case 'fallback':
+      warnings.push(
+        '💡 BETTER_AUTH: Using fallback secret (backwards compatible). Consider setting betterAuth.secret explicitly.',
+      );
+      break;
+    // 'explicit' - no warning needed, explicitly configured
+  }
+
+  // Validate baseUrl
+  if (config.baseUrl && !isValidUrl(config.baseUrl)) {
+    errors.push(`Invalid baseUrl format: ${config.baseUrl}`);
+  }
+
+  // Validate trustedOrigins
+  if (config.trustedOrigins) {
+    for (const origin of config.trustedOrigins) {
+      if (!isValidUrl(origin)) {
+        errors.push(`Invalid trustedOrigin format: ${origin}`);
+      }
+    }
+  }
+
+  // Validate passkey origin
+  if (config.passkey?.enabled && config.passkey.origin && !isValidUrl(config.passkey.origin)) {
+    errors.push(`Invalid passkey origin format: ${config.passkey.origin}`);
+  }
+
+  // Validate social providers dynamically
+  // Providers are enabled by default unless explicitly disabled (enabled: false)
+  // We only validate credentials for providers that are not explicitly disabled
+  if (config.socialProviders) {
+    for (const [name, provider] of Object.entries(config.socialProviders)) {
+      // Provider is considered active if: configured AND not explicitly disabled
+      if (provider && provider.enabled !== false) {
+        // Validate that credentials are provided for active providers
+        const hasClientId = !!provider.clientId;
+        const hasClientSecret = !!provider.clientSecret;
+
+        if (hasClientId && hasClientSecret) {
+          // Both credentials present - provider is fully configured
+          continue;
+        } else if (hasClientId || hasClientSecret) {
+          // Only one credential provided - this is an error
+          if (!hasClientId) {
+            errors.push(`Social provider '${name}' is missing clientId`);
+          }
+          if (!hasClientSecret) {
+            errors.push(`Social provider '${name}' is missing clientSecret`);
+          }
+        } else {
+          // No credentials provided but provider is configured and not disabled
+          // This is likely a configuration mistake - warn the user
+          warnings.push(
+            `Social provider '${name}' is configured but missing both clientId and clientSecret. ` +
+              `Set 'enabled: false' to disable it explicitly, or provide credentials to enable it.`,
+          );
+        }
+      }
+    }
+  }
+
+  return {
+    errors,
+    valid: errors.length === 0,
+    warnings,
+  };
+}
+
+/**
+ * Validates the secret strength
+ * Requirements: min 32 chars, should contain mixed characters
+ */
+function validateSecret(secret: string): { message?: string; valid: boolean } {
+  if (!secret || secret.length < 32) {
+    return { message: 'Secret must be at least 32 characters long', valid: false };
+  }
+
+  // Check for character diversity (at least 2 of: lowercase, uppercase, numbers, special)
+  const hasLowercase = /[a-z]/.test(secret);
+  const hasUppercase = /[A-Z]/.test(secret);
+  const hasNumbers = /[0-9]/.test(secret);
+  const hasSpecial = /[^a-zA-Z0-9]/.test(secret);
+  const diversityCount = [hasLowercase, hasUppercase, hasNumbers, hasSpecial].filter(Boolean).length;
+
+  if (diversityCount < 2) {
+    return {
+      message: 'Secret should contain at least 2 different character types (lowercase, uppercase, numbers, special)',
+      valid: true, // Warning only, not an error
+    };
+  }
+
+  return { valid: true };
+}

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

@@ -0,0 +1,111 @@
+import { Injectable, Logger, NestMiddleware } from '@nestjs/common';
+import { NextFunction, Request, Response } from 'express';
+
+import { BetterAuthSessionUser, BetterAuthUserMapper, MappedUser } from './better-auth-user.mapper';
+import { BetterAuthService } from './better-auth.service';
+
+/**
+ * Extended Express Request with Better-Auth session data
+ */
+export interface BetterAuthRequest extends Request {
+  betterAuthSession?: {
+    session: any;
+    user: BetterAuthSessionUser;
+  };
+  betterAuthUser?: BetterAuthSessionUser;
+  user?: MappedUser | Request['user'];
+}
+
+/**
+ * Middleware that processes Better-Auth sessions and maps users
+ *
+ * This middleware:
+ * 1. Checks if Better-Auth is enabled
+ * 2. Validates the session using Better-Auth's API
+ * 3. Maps the Better-Auth user to our User model with hasRole() capability
+ * 4. Attaches the mapped user to req.user for use with our security decorators
+ *
+ * IMPORTANT: This middleware runs BEFORE guards, so the user will be available
+ * for RolesGuard and other security checks.
+ */
+@Injectable()
+export class BetterAuthMiddleware implements NestMiddleware {
+  private readonly logger = new Logger(BetterAuthMiddleware.name);
+
+  constructor(
+    private readonly betterAuthService: BetterAuthService,
+    private readonly userMapper: BetterAuthUserMapper,
+  ) {}
+
+  async use(req: BetterAuthRequest, _res: Response, next: NextFunction) {
+    // Skip if Better-Auth is not enabled
+    if (!this.betterAuthService.isEnabled()) {
+      return next();
+    }
+
+    // Skip if user is already set (e.g., by JWT auth)
+    if (req.user) {
+      return next();
+    }
+
+    try {
+      // Get session from Better-Auth
+      const session = await this.getSession(req);
+
+      if (session?.user) {
+        // Store the original Better-Auth session
+        req.betterAuthSession = session;
+        req.betterAuthUser = session.user;
+
+        // Map the Better-Auth user to our User model with hasRole()
+        const mappedUser = await this.userMapper.mapSessionUser(session.user);
+
+        if (mappedUser) {
+          // Attach the mapped user to the request
+          // This makes it compatible with @CurrentUser() and RolesGuard
+          req.user = mappedUser;
+        }
+      }
+    } catch (error) {
+      // Don't block the request on auth errors
+      // The guards will handle unauthorized access
+      this.logger.debug(`Session validation failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+
+    next();
+  }
+
+  /**
+   * Gets the session from Better-Auth
+   */
+  private async getSession(req: Request): Promise<null | { session: any; user: BetterAuthSessionUser }> {
+    const api = this.betterAuthService.getApi();
+    if (!api) {
+      return null;
+    }
+
+    try {
+      // Convert Express headers to the format Better-Auth expects
+      const headers = new Headers();
+      for (const [key, value] of Object.entries(req.headers)) {
+        if (typeof value === 'string') {
+          headers.set(key, value);
+        } else if (Array.isArray(value)) {
+          headers.set(key, value.join(', '));
+        }
+      }
+
+      // Call Better-Auth's getSession API
+      const response = await api.getSession({ headers });
+
+      if (response && typeof response === 'object' && 'user' in response) {
+        return response as { session: any; user: BetterAuthSessionUser };
+      }
+
+      return null;
+    } catch (error) {
+      this.logger.debug(`getSession error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      return null;
+    }
+  }
+}