@nauth-toolkit/core 0.1.0

package/src/utils/setup/init-services.ts

@@ -0,0 +1,422 @@
+/**
+ * Service Initialization Helper
+ *
+ * Initializes all NAuth services in correct dependency order.
+ * Matches NestJS AuthModule service initialization.
+ */
+
+import { Repository } from 'typeorm';
+// Public API imports
+import {
+  NAuthConfig,
+  NAuthLogger,
+  StorageAdapter,
+  ClientInfoService,
+  RateLimitStorageService,
+  AccountLockoutStorageService,
+  EmailVerificationService,
+  PhoneVerificationService,
+  MFAService,
+  AuthService,
+  SocialAuthService,
+  NAuthException,
+  AuthErrorCode,
+} from '../../index';
+// Internal API imports (for framework adapter use only)
+import {
+  PasswordService,
+  JwtService,
+  SessionService,
+  AuthAuditService, // Internal version with recordEvent()
+  ChallengeService,
+  TrustedDeviceService,
+  AuthFlowContextBuilder,
+  AuthFlowStateMachineService,
+  AuthChallengeHelperService,
+  SocialProviderRegistry,
+  GeoLocationService,
+  RiskDetectionService,
+  RiskScoringService,
+  AdaptiveMFADecisionService,
+} from '../../internal';
+import {
+  BaseUser,
+  BaseSession,
+  BaseLoginAttempt,
+  BaseVerificationToken,
+  BaseSocialAccount,
+  BaseChallengeSession,
+  BaseMFADevice,
+  BaseAuthAudit,
+  BaseTrustedDevice,
+} from '../../entities';
+
+/**
+ * Service container returned by initServices()
+ */
+export interface NAuthServices {
+  // Core services (always available)
+  passwordService: PasswordService;
+  jwtService: JwtService;
+  clientInfoService: ClientInfoService;
+  rateLimitStorageService: RateLimitStorageService;
+  accountLockoutStorageService: AccountLockoutStorageService;
+  sessionService: SessionService;
+  challengeService: ChallengeService;
+  emailVerificationService: EmailVerificationService;
+  authFlowContextBuilder: AuthFlowContextBuilder;
+  authFlowStateMachine: AuthFlowStateMachineService;
+  authChallengeHelperService: AuthChallengeHelperService;
+  authService: AuthService;
+  socialProviderRegistry: SocialProviderRegistry;
+  socialAuthService: SocialAuthService;
+
+  // Conditional services
+  auditService?: AuthAuditService;
+  phoneVerificationService?: PhoneVerificationService;
+  trustedDeviceService?: TrustedDeviceService;
+  mfaService?: MFAService;
+  geoLocationService?: GeoLocationService;
+  riskDetectionService?: RiskDetectionService;
+  riskScoringService?: RiskScoringService;
+  adaptiveMFADecisionService?: AdaptiveMFADecisionService;
+  csrfService?: unknown; // CsrfService (created in createNAuth)
+}
+
+/**
+ * Initialize all services in correct dependency order
+ *
+ * Service initialization order matches NestJS AuthModule:
+ * 1. PasswordService, JwtService (no dependencies)
+ * 2. ClientInfoService (no dependencies)
+ * 3. AuthAuditService (if enabled)
+ * 4. RateLimitStorageService, AccountLockoutStorageService
+ * 5. SessionService
+ * 6. ChallengeService
+ * 7. EmailVerificationService
+ * 8. PhoneVerificationService (if SMS configured)
+ * 9. TrustedDeviceService (if rememberDevices enabled)
+ * 10. AuthFlowContextBuilder, AuthFlowStateMachine
+ * 11. AuthChallengeHelperService
+ * 12. MFAService (if enabled)
+ * 13. AuthService
+ * 14. SocialAuthService
+ * 15. GeoLocationService (if MaxMind configured)
+ * 16. Risk services (if adaptive MFA configured)
+ *
+ * @param config - NAuth configuration
+ * @param repositories - Repository container
+ * @param storageAdapter - Initialized storage adapter
+ * @param logger - Logger instance
+ * @param emailProvider - Email provider instance
+ * @param smsProvider - SMS provider instance (optional)
+ * @returns Service container with all initialized services
+ */
+export function initServices(
+  config: NAuthConfig,
+  repositories: {
+    userRepository: Repository<BaseUser>;
+    sessionRepository: Repository<BaseSession>;
+    loginAttemptRepository: Repository<BaseLoginAttempt>;
+    verificationTokenRepository: Repository<BaseVerificationToken>;
+    socialAccountRepository: Repository<BaseSocialAccount>;
+    challengeSessionRepository: Repository<BaseChallengeSession>;
+    mfaDeviceRepository: Repository<BaseMFADevice>;
+    authAuditRepository: Repository<BaseAuthAudit>;
+    trustedDeviceRepository: Repository<BaseTrustedDevice> | null;
+  },
+  storageAdapter: StorageAdapter,
+  logger: NAuthLogger,
+  emailProvider: unknown,
+  smsProvider?: unknown,
+): NAuthServices {
+  // ============================================================================
+  // 1. Core Services (No Dependencies)
+  // ============================================================================
+
+  const passwordService = new PasswordService(config.password);
+  const jwtService = new JwtService(config.jwt);
+  const clientInfoService = new ClientInfoService();
+
+  // ============================================================================
+  // 2. Audit Service (Conditional)
+  // ============================================================================
+
+  const auditService =
+    config.auditLogs?.enabled !== false
+      ? new AuthAuditService(repositories.authAuditRepository, repositories.userRepository, logger, clientInfoService)
+      : undefined;
+
+  // ============================================================================
+  // 3. Storage Services
+  // ============================================================================
+
+  const rateLimitStorageService = new RateLimitStorageService(storageAdapter);
+  const accountLockoutStorageService = new AccountLockoutStorageService(storageAdapter);
+
+  // ============================================================================
+  // 4. Session Service
+  // ============================================================================
+
+  const sessionService = new SessionService(
+    repositories.sessionRepository,
+    storageAdapter,
+    clientInfoService,
+    config,
+    logger,
+    auditService,
+  );
+
+  // ============================================================================
+  // 5. Challenge Service
+  // ============================================================================
+
+  const challengeService = new ChallengeService(
+    repositories.challengeSessionRepository,
+    clientInfoService,
+    logger,
+    auditService,
+    config, // Pass config for maxAttempts
+  );
+
+  // ============================================================================
+  // 6. Email Provider and Verification Service
+  // ============================================================================
+
+  if (!emailProvider) {
+    throw new NAuthException(
+      AuthErrorCode.VALIDATION_FAILED,
+      'emailProvider is required. Install and configure an email package:\n' +
+        '  yarn add @nauth-toolkit/email-console (for dev)\n' +
+        '  yarn add @nauth-toolkit/email-nodemailer (for production)',
+    );
+  }
+
+  // Validate email provider has required method
+  if (typeof (emailProvider as any).sendVerificationEmail !== 'function') {
+    throw new NAuthException(
+      AuthErrorCode.VALIDATION_FAILED,
+      'emailProvider must implement sendVerificationEmail method',
+    );
+  }
+
+  // Inject logger into email provider if it supports it
+  if (emailProvider && typeof (emailProvider as any).setLogger === 'function') {
+    (emailProvider as any).setLogger(logger);
+  }
+
+  // Inject global variables from email config if provider supports it
+  if (emailProvider && typeof (emailProvider as any).setGlobalVariables === 'function' && config.email) {
+    const globalVars: Record<string, any> = {};
+    // Extract top-level branding fields
+    if (config.email.appName) globalVars.appName = config.email.appName;
+    if (config.email.companyName) globalVars.companyName = config.email.companyName;
+    if (config.email.logoUrl) globalVars.logoUrl = config.email.logoUrl;
+    if (config.email.supportEmail) globalVars.supportEmail = config.email.supportEmail;
+    if (config.email.dashboardUrl) globalVars.dashboardUrl = config.email.dashboardUrl;
+    if (config.email.brandColor) globalVars.brandColor = config.email.brandColor;
+    if (config.email.footerDisclaimer) globalVars.footerDisclaimer = config.email.footerDisclaimer;
+    // Merge with templates.globalVariables (templates.globalVariables takes precedence)
+    const mergedVars = {
+      ...globalVars,
+      ...(config.email.templates?.globalVariables || {}),
+    };
+    (emailProvider as any).setGlobalVariables(mergedVars);
+  }
+
+  const emailVerificationService = new EmailVerificationService(
+    repositories.verificationTokenRepository,
+    repositories.userRepository,
+    emailProvider as any,
+    storageAdapter,
+    config,
+    clientInfoService,
+    logger,
+    auditService,
+  );
+
+  // ============================================================================
+  // 7. SMS Provider and Phone Verification Service (Conditional)
+  // ============================================================================
+
+  let phoneVerificationService: PhoneVerificationService | undefined;
+
+  if (smsProvider) {
+    // Inject logger into SMS provider if it supports it
+    if (smsProvider && typeof (smsProvider as any).setLogger === 'function') {
+      (smsProvider as any).setLogger(logger);
+    }
+
+    phoneVerificationService = new PhoneVerificationService(
+      repositories.verificationTokenRepository,
+      repositories.userRepository,
+      smsProvider as any,
+      storageAdapter,
+      config,
+      clientInfoService,
+      logger,
+      auditService,
+    );
+  }
+
+  // ============================================================================
+  // 8. Trusted Device Service (Conditional)
+  // ============================================================================
+
+  const trustedDeviceService = repositories.trustedDeviceRepository
+    ? new TrustedDeviceService(config, logger, repositories.trustedDeviceRepository)
+    : undefined;
+
+  // ============================================================================
+  // 9. Auth Flow Services
+  // ============================================================================
+
+  const authFlowContextBuilder = new AuthFlowContextBuilder(
+    trustedDeviceService,
+    undefined, // adaptiveMFADecisionService - will be set later
+    clientInfoService,
+    logger,
+  );
+
+  const authFlowStateMachine = new AuthFlowStateMachineService(authFlowContextBuilder, logger);
+
+  const authChallengeHelperService = new AuthChallengeHelperService(
+    challengeService,
+    jwtService,
+    sessionService,
+    repositories.mfaDeviceRepository,
+    logger,
+    authFlowStateMachine,
+    authFlowContextBuilder,
+    clientInfoService,
+    emailVerificationService,
+    phoneVerificationService,
+  );
+
+  // ============================================================================
+  // 10. MFA Service (Conditional)
+  // ============================================================================
+
+  const mfaService = new MFAService(
+    repositories.mfaDeviceRepository,
+    repositories.userRepository,
+    challengeService,
+    config,
+    logger,
+    auditService,
+    clientInfoService,
+  );
+
+  // ============================================================================
+  // 11. Auth Service
+  // ============================================================================
+
+  const authService = new AuthService(
+    repositories.userRepository,
+    repositories.loginAttemptRepository,
+    passwordService,
+    jwtService,
+    sessionService,
+    challengeService,
+    authChallengeHelperService,
+    emailVerificationService,
+    clientInfoService,
+    accountLockoutStorageService,
+    config,
+    logger,
+    auditService,
+    phoneVerificationService,
+    mfaService,
+    repositories.mfaDeviceRepository,
+    trustedDeviceService,
+  );
+
+  // ============================================================================
+  // 12. Social Auth Services
+  // ============================================================================
+
+  const socialProviderRegistry = new SocialProviderRegistry();
+
+  const socialAuthService = new SocialAuthService(
+    socialProviderRegistry,
+    repositories.userRepository,
+    repositories.socialAccountRepository,
+    authService,
+    logger,
+    auditService,
+  );
+
+  // ============================================================================
+  // 13. GeoLocation Service (Conditional)
+  // ============================================================================
+
+  let geoLocationService: GeoLocationService | undefined;
+
+  if (config.geoLocation?.maxMind) {
+    try {
+      // Try to load MaxMind module (optional peer dependency)
+      const maxMindModule = require('@maxmind/geoip2-node');
+      geoLocationService = new GeoLocationService(config, storageAdapter, maxMindModule, logger);
+    } catch {
+      // MaxMind module not installed - service remains undefined
+      logger?.warn?.('MaxMind GeoIP2 module not installed. Geolocation features will be disabled.');
+    }
+  }
+
+  // ============================================================================
+  // 14. Risk Detection and Adaptive MFA Services (Conditional)
+  // ============================================================================
+
+  // Always create risk services (needed for adaptive MFA)
+  const riskDetectionService = new RiskDetectionService(
+    repositories.sessionRepository,
+    repositories.authAuditRepository,
+    config,
+    logger,
+    trustedDeviceService,
+  );
+
+  const riskScoringService = new RiskScoringService(config, logger);
+
+  const adaptiveMFADecisionService = new AdaptiveMFADecisionService(
+    riskDetectionService,
+    riskScoringService,
+    storageAdapter,
+    clientInfoService,
+    config,
+    logger,
+    auditService,
+  );
+
+  // Now inject adaptiveMFADecisionService into authFlowContextBuilder
+  (authFlowContextBuilder as any).adaptiveMFADecisionService = adaptiveMFADecisionService;
+
+  // ============================================================================
+  // Return Service Container
+  // ============================================================================
+
+  return {
+    passwordService,
+    jwtService,
+    clientInfoService,
+    rateLimitStorageService,
+    accountLockoutStorageService,
+    sessionService,
+    challengeService,
+    emailVerificationService,
+    authFlowContextBuilder,
+    authFlowStateMachine,
+    authChallengeHelperService,
+    authService,
+    socialProviderRegistry,
+    socialAuthService,
+    auditService,
+    phoneVerificationService,
+    trustedDeviceService,
+    mfaService,
+    geoLocationService,
+    riskDetectionService,
+    riskScoringService,
+    adaptiveMFADecisionService,
+  };
+}

package/src/utils/setup/init-social.ts

@@ -0,0 +1,189 @@
+/**
+ * Social Authentication Provider Initialization
+ *
+ * Dynamically loads and initializes social auth providers based on configuration.
+ */
+
+// Public API imports
+import {
+  NAuthConfig,
+  NAuthLogger,
+  SocialAuthService,
+  AuthService,
+  ClientInfoService,
+  AuthAuditService,
+  PhoneVerificationService,
+  BaseUser,
+} from '../../index';
+// Internal API imports (for framework adapter use only)
+import {
+  JwtService,
+  SessionService,
+  AuthChallengeHelperService,
+  SocialProviderRegistry,
+  TrustedDeviceService,
+} from '../../internal';
+import { Repository } from 'typeorm';
+
+export interface NAuthSocialProviders {
+  googleAuth?: any;
+  appleAuth?: any;
+  facebookAuth?: any;
+}
+
+/**
+ * Initialize and register social authentication providers
+ *
+ * Dynamically imports social provider packages based on configuration.
+ * Each provider is initialized with all required services and registered
+ * with the SocialAuthService registry.
+ *
+ * @param config - NAuth configuration
+ * @param providerRegistry - Social provider registry (internal)
+ * @param authService - Core authentication service
+ * @param socialAuthService - Social authentication service
+ * @param jwtService - JWT token service
+ * @param sessionService - Session management service
+ * @param challengeHelper - Auth challenge helper service
+ * @param clientInfoService - Client information service
+ * @param logger - Logger instance
+ * @param socialAuthStateStore - Shared state store for OAuth CSRF protection
+ * @param phoneVerificationService - Phone verification service (optional)
+ * @param auditService - Audit logging service (optional)
+ * @param trustedDeviceService - Trusted device service (optional)
+ * @returns Object containing initialized social providers
+ */
+export async function initSocialAuth(
+  config: NAuthConfig,
+  providerRegistry: SocialProviderRegistry,
+  authService: AuthService,
+  socialAuthService: SocialAuthService,
+  jwtService: JwtService,
+  sessionService: SessionService,
+  challengeHelper: AuthChallengeHelperService,
+  clientInfoService: ClientInfoService,
+  logger: NAuthLogger,
+  socialAuthStateStore: Map<string, { timestamp: number; provider: string }>,
+  userRepository: Repository<BaseUser>,
+  phoneVerificationService?: PhoneVerificationService,
+  auditService?: AuthAuditService,
+  trustedDeviceService?: TrustedDeviceService,
+): Promise<NAuthSocialProviders> {
+  const providers: NAuthSocialProviders = {};
+
+  // ============================================================================
+  // Google OAuth Provider
+  // ============================================================================
+  if (config.social?.google?.enabled) {
+    try {
+      // @ts-ignore - Optional peer dependency, may not be installed
+      const { GoogleSocialAuthService, TokenVerifierService } = await import('@nauth-toolkit/social-google');
+
+      // Create token verifier for native mobile token validation
+      const tokenVerifier = new TokenVerifierService(config);
+
+      providers.googleAuth = new GoogleSocialAuthService(
+        config,
+        logger,
+        authService,
+        socialAuthService,
+        jwtService,
+        sessionService,
+        challengeHelper,
+        clientInfoService,
+        socialAuthStateStore,
+        userRepository,
+        phoneVerificationService,
+        auditService,
+        trustedDeviceService,
+        tokenVerifier,
+      );
+
+      // Register with registry
+      providerRegistry.registerProvider(providers.googleAuth);
+      logger?.debug?.('Google OAuth provider initialized');
+    } catch (error) {
+      logger?.warn?.(
+        'Google OAuth provider not available. Install @nauth-toolkit/social-google to enable Google authentication.',
+      );
+    }
+  }
+
+  // ============================================================================
+  // Apple Sign-In Provider
+  // ============================================================================
+  if (config.social?.apple?.enabled) {
+    try {
+      // @ts-ignore - Optional peer dependency, may not be installed
+      const { AppleSocialAuthService, TokenVerifierService } = await import('@nauth-toolkit/social-apple');
+
+      // Create token verifier for native mobile token validation
+      const tokenVerifier = new TokenVerifierService(config);
+
+      providers.appleAuth = new AppleSocialAuthService(
+        config,
+        logger,
+        authService,
+        socialAuthService,
+        jwtService,
+        sessionService,
+        challengeHelper,
+        clientInfoService,
+        socialAuthStateStore,
+        userRepository,
+        phoneVerificationService,
+        auditService,
+        trustedDeviceService,
+        tokenVerifier,
+      );
+
+      // Register with registry
+      providerRegistry.registerProvider(providers.appleAuth);
+      logger?.debug?.('Apple Sign-In provider initialized');
+    } catch (error) {
+      logger?.warn?.(
+        'Apple Sign-In provider not available. Install @nauth-toolkit/social-apple to enable Apple authentication.',
+      );
+    }
+  }
+
+  // ============================================================================
+  // Facebook OAuth Provider
+  // ============================================================================
+  if (config.social?.facebook?.enabled) {
+    try {
+      // @ts-ignore - Optional peer dependency, may not be installed
+      const { FacebookSocialAuthService, TokenVerifierService } = await import('@nauth-toolkit/social-facebook');
+
+      // Create token verifier for native mobile token validation
+      const tokenVerifier = new TokenVerifierService(config);
+
+      providers.facebookAuth = new FacebookSocialAuthService(
+        config,
+        logger,
+        authService,
+        socialAuthService,
+        jwtService,
+        sessionService,
+        challengeHelper,
+        clientInfoService,
+        socialAuthStateStore,
+        userRepository,
+        phoneVerificationService,
+        auditService,
+        trustedDeviceService,
+        tokenVerifier,
+      );
+
+      // Register with registry
+      providerRegistry.registerProvider(providers.facebookAuth);
+      logger?.debug?.('Facebook OAuth provider initialized');
+    } catch (error) {
+      logger?.warn?.(
+        'Facebook OAuth provider not available. Install @nauth-toolkit/social-facebook to enable Facebook authentication.',
+      );
+    }
+  }
+
+  return providers;
+}

package/src/utils/setup/init-storage.ts

@@ -0,0 +1,94 @@
+/**
+ * Storage Adapter Initialization Helper
+ *
+ * Initializes storage adapter with repository injection and proper error handling.
+ */
+
+import { Repository } from 'typeorm';
+import { StorageAdapter, LoggerService, NAuthConfig, NAuthException, AuthErrorCode } from '../../index';
+
+/**
+ * Initialize storage adapter
+ *
+ * Handles:
+ * - Logger injection (if adapter supports it)
+ * - Repository injection (for DatabaseStorageAdapter)
+ * - Adapter initialization
+ * - Fallback to DatabaseStorageAdapter if no adapter provided and repositories available
+ * - Error if no adapter and no repositories (prevents unsafe defaults)
+ *
+ * @param config - NAuth configuration
+ * @param rateLimitRepo - RateLimit repository (nullable)
+ * @param storageLockRepo - StorageLock repository (nullable)
+ * @param logger - Logger instance
+ * @returns Initialized StorageAdapter
+ * @throws {NAuthException} If no adapter provided and DatabaseStorageAdapter cannot be created
+ */
+export async function initStorage(
+  config: NAuthConfig,
+  rateLimitRepo: Repository<any> | null,
+  storageLockRepo: Repository<any> | null,
+  logger: LoggerService,
+): Promise<StorageAdapter> {
+  // If storage adapter explicitly provided, use it
+  if (config.storageAdapter) {
+    const adapter = config.storageAdapter;
+
+    // Inject logger if adapter supports it
+    if (adapter && typeof (adapter as any).setLogger === 'function') {
+      (adapter as any).setLogger(logger);
+    }
+
+    // Inject repositories into DatabaseStorageAdapter if it supports it
+    if (adapter && typeof (adapter as any).setRepositories === 'function') {
+      if (rateLimitRepo && storageLockRepo) {
+        (adapter as any).setRepositories(rateLimitRepo, storageLockRepo);
+      }
+    }
+
+    await adapter.initialize();
+    return adapter;
+  }
+
+  // No storage adapter provided - try to use DatabaseStorageAdapter if repositories available
+  if (rateLimitRepo && storageLockRepo) {
+    try {
+      // Lazy import to avoid bundling if not used
+      // @ts-ignore - Dynamic import of optional peer dependency
+      const { DatabaseStorageAdapter } = await import('@nauth-toolkit/storage-database');
+      const adapter = new DatabaseStorageAdapter(null, null, logger as any);
+      adapter.setRepositories(rateLimitRepo as any, storageLockRepo as any);
+      await adapter.initialize();
+
+      logger?.warn?.(
+        'WARNING: Storage adapter not provided. Using DatabaseStorageAdapter as default. ' +
+          'For production, explicitly configure storageAdapter in your config.',
+      );
+
+      return adapter;
+    } catch (error) {
+      // If DatabaseStorageAdapter import fails, fall through to error
+      logger?.error?.(
+        'Failed to create DatabaseStorageAdapter. Please explicitly configure storageAdapter in your config.',
+        { error },
+      );
+    }
+  }
+
+  // No storage adapter provided and no repositories available - REQUIRE explicit configuration
+  throw new NAuthException(
+    AuthErrorCode.VALIDATION_FAILED,
+    'Storage adapter is REQUIRED for production deployments. ' +
+      'MemoryStorageAdapter is NOT safe for production (data lost on restart, not shared across instances). ' +
+      'Please configure storageAdapter in your NAuthConfig:\n\n' +
+      'Option 1: DatabaseStorageAdapter (recommended if you have a database)\n' +
+      '  import { createDatabaseStorageAdapter } from "@nauth-toolkit/express";\n' +
+      '  storageAdapter: createDatabaseStorageAdapter()\n\n' +
+      'Option 2: RedisStorageAdapter (for high-performance multi-server deployments)\n' +
+      '  import { createRedisStorageAdapter } from "@nauth-toolkit/express";\n' +
+      '  storageAdapter: createRedisStorageAdapter(process.env.REDIS_URL)\n\n' +
+      'Make sure to include storage entities in your DataSource configuration:\n' +
+      '  import { getNAuthStorageEntities } from "@nauth-toolkit/database-typeorm-postgres";\n' +
+      '  entities: [...getNAuthEntities(), ...getNAuthStorageEntities()]',
+  );
+}