@nauth-toolkit/nestjs 0.1.13 → 0.1.17

package/dist/auth.module.d.ts

@@ -1,10 +1,58 @@
 import { DynamicModule } from '@nestjs/common';
 import { NAuthConfig } from '@nauth-toolkit/core';
+/**
+ * Extended NAuth Configuration (includes optional entities)
+ *
+ * Entities are optional - AuthModule will auto-discover them from DataSource if not provided.
+ * Consumer apps should NOT need to configure entities if they're already in TypeORM.forRoot().
+ */
 export interface NAuthModuleConfig extends NAuthConfig {
+    /**
+     * Optional: TypeORM entities from database package
+     *
+     * **Note:** Entities are optional if already registered in `TypeOrmModule.forRoot()`.
+     * AuthModule will auto-discover entities from DataSource metadata.
+     *
+     * Only provide if you're not using `TypeOrmModule.forRoot()` with entities.
+     *
+     * @example
+     * ```typescript
+     * // PREFERRED - Auto-discovery (entities in TypeORM.forRoot())
+     * TypeOrmModule.forRoot({ entities: getNAuthEntities(), ... })
+     * AuthModule.forRoot({ jwt: {...} }) // entities not needed
+     *
+     * // ALSO VALID - Explicit entities (if not using TypeORM.forRoot())
+     * AuthModule.forRoot({ entities: getNAuthEntities(), jwt: {...} })
+     * ```
+     */
     entities?: Function[];
 }
+/**
+ * Main Authentication Module (v2.0 - Modular)
+ *
+ * Core provides base authentication services.
+ * Features like MFA, social auth, phone verification are in separate packages.
+ */
 export declare class AuthModule {
+    /**
+     * Configure module with static configuration
+     *
+     * @param config - NAuthModuleConfig with entities from database package
+     */
     static forRoot(config: NAuthModuleConfig): DynamicModule;
+    /**
+     * Validate configuration using Zod schema
+     *
+     * Validates all configuration sections and cross-dependencies:
+     * - Email/phone verification requires respective providers
+     * - MFA enforcement modes require specific configurations
+     * - Social providers require credentials when enabled
+     * - JWT algorithm requires appropriate keys
+     * - MaxMind geolocation requires credentials for downloads
+     *
+     * @param config - Configuration to validate
+     * @throws {NAuthException} If validation fails with detailed error messages
+     */
     private static validateConfig;
 }
 //# sourceMappingURL=auth.module.d.ts.map

package/dist/auth.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.module.d.ts","sourceRoot":"","sources":["../src/auth.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,aAAa,EAAU,MAAM,gBAAgB,CAAC;AAK/D,OAAO,EAYL,WAAW,EAoBZ,MAAM,qBAAqB,CAAC;AAsD7B,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IAmBpD,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAC;CACvB;AAQD,qBAEa,UAAU;IAMrB,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,aAAa;IAqqCxD,OAAO,CAAC,MAAM,CAAC,cAAc;CAuB9B"}
+{"version":3,"file":"auth.module.d.ts","sourceRoot":"","sources":["../src/auth.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,aAAa,EAAU,MAAM,gBAAgB,CAAC;AAK/D,OAAO,EAYL,WAAW,EAoBZ,MAAM,qBAAqB,CAAC;AAgD7B;;;;;GAKG;AACH,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAEa,UAAU;IACrB;;;;OAIG;IACH,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,aAAa;IAwpCxD;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;CAuB9B"}

package/dist/auth.module.js

@@ -45,7 +45,9 @@ const common_1 = require("@nestjs/common");
 const core_1 = require("@nestjs/core");
 const typeorm_1 = require("@nestjs/typeorm");
 const typeorm_2 = require("typeorm");
+// Public API imports
 const core_2 = require("@nauth-toolkit/core");
+// Internal API imports (for framework adapter use only)
 const internal_1 = require("@nauth-toolkit/core/internal");
 const client_info_interceptor_1 = require("./interceptors/client-info.interceptor");
 const cookie_token_interceptor_1 = require("./interceptors/cookie-token.interceptor");
@@ -53,27 +55,48 @@ const auth_guard_1 = require("./guards/auth.guard");
 const csrf_guard_1 = require("./guards/csrf.guard");
 const csrf_service_1 = require("./services/csrf.service");
 const migrations_bootstrap_service_1 = require("./services/migrations-bootstrap.service");
+/**
+ * Main Authentication Module (v2.0 - Modular)
+ *
+ * Core provides base authentication services.
+ * Features like MFA, social auth, phone verification are in separate packages.
+ */
 let AuthModule = AuthModule_1 = class AuthModule {
+    /**
+     * Configure module with static configuration
+     *
+     * @param config - NAuthModuleConfig with entities from database package
+     */
     static forRoot(config) {
+        // Validate configuration
         this.validateConfig(config);
+        // Initialize logger wrapper (silent by default if no logger provided)
         const nauthLogger = new core_2.NAuthLogger(config.logger);
+        // Log initialization
         if (nauthLogger.isEnabled()) {
             nauthLogger.log('Initializing nauth-toolkit...');
             nauthLogger.debug(`Table prefix: ${config.tablePrefix || 'nauth_'}`);
             nauthLogger.debug(`JWT algorithm: ${config.jwt.algorithm || 'HS256'}`);
         }
+        // Storage adapter will be initialized in useFactory below
+        // Use config.storageAdapter if provided, otherwise default to MemoryStorageAdapter
+        // Determine entities - use provided or discover from DataSource
         const entities = config.entities || [];
         return {
             module: AuthModule_1,
             imports: [
+                // TypeORM entities - only if provided (otherwise entities from forRoot() are used)
                 ...(entities.length > 0 ? [typeorm_1.TypeOrmModule.forFeature(entities)] : []),
             ],
             providers: [
+                // Auto-run nauth-toolkit migrations on startup (no consumer burden)
                 migrations_bootstrap_service_1.nauthMigrationsBootstrapProvider,
+                // Global interceptor for automatic client info extraction
                 {
                     provide: core_1.APP_INTERCEPTOR,
                     useClass: client_info_interceptor_1.ClientInfoInterceptor,
                 },
+                // Global interceptor for cookie token delivery (no-op in JSON mode)
                 {
                     provide: core_1.APP_INTERCEPTOR,
                     useFactory: (config, jwtService, reflector, csrfService) => {
@@ -83,9 +106,10 @@ let AuthModule = AuthModule_1 = class AuthModule {
                         'NAUTH_CONFIG',
                         internal_1.JwtService,
                         core_1.Reflector,
-                        { token: csrf_service_1.CsrfService, optional: true },
+                        { token: csrf_service_1.CsrfService, optional: true }, // Optional - only available when CSRF is enabled
                     ],
                 },
+                // CSRF Service (always provided, but only used when tokenDelivery.method === 'cookies' or 'hybrid')
                 {
                     provide: csrf_service_1.CsrfService,
                     useFactory: (config) => {
@@ -93,6 +117,7 @@ let AuthModule = AuthModule_1 = class AuthModule {
                     },
                     inject: ['NAUTH_CONFIG'],
                 },
+                // CSRF Guard (conditionally applied when using cookie-based token delivery)
                 ...(config.tokenDelivery?.method === 'cookies' || config.tokenDelivery?.method === 'hybrid'
                     ? [
                         {
@@ -101,23 +126,34 @@ let AuthModule = AuthModule_1 = class AuthModule {
                         },
                     ]
                     : []),
+                // Configuration
                 {
                     provide: 'NAUTH_CONFIG',
                     useValue: config,
                 },
+                // Logger
                 {
                     provide: 'NAUTH_LOGGER',
                     useValue: nauthLogger,
                 },
+                // Storage adapter - use config or default to DatabaseStorageAdapter if repositories available
+                // WARNING: PRODUCTION REQUIREMENT - MemoryStorageAdapter is NOT safe for production
+                // - Data lost on server restart
+                // - NOT shared across multiple server instances
+                // - Rate limiting per-container (not global in multi-container setups)
+                // - Token reuse detection fails in multi-server deployments
                 {
                     provide: 'STORAGE_ADAPTER',
                     useFactory: async (config, logger, rateLimitRepo, storageLockRepo) => {
+                        // If storage adapter is explicitly provided, use it
                         if (config.storageAdapter) {
                             const adapter = config.storageAdapter;
+                            // Inject logger into adapter if it supports setLogger (for factory-created adapters)
                             if (adapter &&
                                 typeof adapter.setLogger === 'function') {
                                 adapter.setLogger(logger);
                             }
+                            // Inject repositories into DatabaseStorageAdapter if it supports setRepositories
                             if (adapter &&
                                 typeof adapter.setRepositories === 'function') {
                                 if (rateLimitRepo && storageLockRepo) {
@@ -127,8 +163,11 @@ let AuthModule = AuthModule_1 = class AuthModule {
                             await adapter.initialize();
                             return adapter;
                         }
+                        // No storage adapter provided - try to use DatabaseStorageAdapter if repositories available
                         if (rateLimitRepo && storageLockRepo) {
+                            // Default to DatabaseStorageAdapter when repositories are available (most apps have a database)
                             try {
+                                // Lazy import to avoid bundling if not used
                                 const { DatabaseStorageAdapter } = await Promise.resolve().then(() => __importStar(require('@nauth-toolkit/storage-database')));
                                 const adapter = new DatabaseStorageAdapter(null, null, logger);
                                 adapter.setRepositories(rateLimitRepo, storageLockRepo);
@@ -138,9 +177,11 @@ let AuthModule = AuthModule_1 = class AuthModule {
                                 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 Error('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' +
@@ -156,51 +197,65 @@ let AuthModule = AuthModule_1 = class AuthModule {
                     },
                     inject: ['NAUTH_CONFIG', 'NAUTH_LOGGER', 'RateLimitRepository', 'StorageLockRepository'],
                 },
+                // Rate Limit Repository (optional - only needed for DatabaseStorageAdapter)
                 {
                     provide: 'RateLimitRepository',
                     useFactory: (dataSource) => {
+                        // Try to find entity from config first
                         const entityFromConfig = entities.find((e) => e.name === 'RateLimit');
                         if (entityFromConfig) {
                             return dataSource.getRepository(entityFromConfig);
                         }
+                        // Try to find by table name in DataSource metadata
                         const metadata = dataSource.entityMetadatas.find((m) => m.tableName === 'nauth_rate_limits');
                         if (metadata) {
                             return dataSource.getRepository(metadata.target);
                         }
+                        // Try to find by class name in metadata
                         const metadataByName = dataSource.entityMetadatas.find((m) => typeof m.target === 'function' && m.target.name === 'RateLimit');
                         if (metadataByName && typeof metadataByName.target === 'function') {
                             return dataSource.getRepository(metadataByName.target);
                         }
+                        // Return null if not found (storage adapter might not be DatabaseStorageAdapter)
                         return null;
                     },
                     inject: [typeorm_2.DataSource],
                 },
+                // Storage Lock Repository (optional - only needed for DatabaseStorageAdapter)
                 {
                     provide: 'StorageLockRepository',
                     useFactory: (dataSource) => {
+                        // Try to find entity from config first
                         const entityFromConfig = entities.find((e) => e.name === 'StorageLock');
                         if (entityFromConfig) {
                             return dataSource.getRepository(entityFromConfig);
                         }
+                        // Try to find by table name in DataSource metadata
                         const metadata = dataSource.entityMetadatas.find((m) => m.tableName === 'nauth_storage_locks');
                         if (metadata) {
                             return dataSource.getRepository(metadata.target);
                         }
+                        // Try to find by class name in metadata
                         const metadataByName = dataSource.entityMetadatas.find((m) => typeof m.target === 'function' && m.target.name === 'StorageLock');
                         if (metadataByName && typeof metadataByName.target === 'function') {
                             return dataSource.getRepository(metadataByName.target);
                         }
+                        // Return null if not found (storage adapter might not be DatabaseStorageAdapter)
                         return null;
                     },
                     inject: [typeorm_2.DataSource],
                 },
+                // Repository Tokens - discover entities from DataSource metadata
+                // This allows entities to be auto-discovered if registered in TypeORM.forRoot()
                 {
                     provide: 'UserRepository',
                     useFactory: (dataSource) => {
+                        // Try to find entity from provided config first
                         const entityFromConfig = entities.find((e) => e.name === 'User');
                         if (entityFromConfig) {
                             return dataSource.getRepository(entityFromConfig);
                         }
+                        // Otherwise, find by table name from DataSource metadata
                         const metadata = dataSource.entityMetadatas.find((m) => m.tableName === 'nauth_users');
                         if (!metadata) {
                             throw new core_2.NAuthException(core_2.AuthErrorCode.VALIDATION_FAILED, 'User entity not found. Register entities in TypeORM.forRoot() or provide in config.entities');
@@ -323,12 +378,14 @@ let AuthModule = AuthModule_1 = class AuthModule {
                         }
                         const metadata = dataSource.entityMetadatas.find((m) => m.tableName === 'nauth_trusted_devices');
                         if (!metadata) {
+                            // Return null if not found (rememberDevice might be disabled)
                             return null;
                         }
                         return dataSource.getRepository(metadata.target);
                     },
                     inject: [typeorm_2.DataSource],
                 },
+                // Services
                 {
                     provide: internal_1.PasswordService,
                     useFactory: () => {
@@ -358,7 +415,7 @@ let AuthModule = AuthModule_1 = class AuthModule {
                         core_2.ClientInfoService,
                         'NAUTH_CONFIG',
                         'NAUTH_LOGGER',
-                        { token: internal_1.AuthAuditService, optional: true },
+                        { token: internal_1.AuthAuditService, optional: true }, // Optional - only available when auditLogs.enabled is true
                     ],
                 },
                 {
@@ -370,9 +427,10 @@ let AuthModule = AuthModule_1 = class AuthModule {
                         'ChallengeSessionRepository',
                         core_2.ClientInfoService,
                         'NAUTH_LOGGER',
-                        { token: internal_1.AuthAuditService, optional: true },
+                        { token: internal_1.AuthAuditService, optional: true }, // Optional - only available when auditLogs.enabled is true
                     ],
                 },
+                // AuthFlowContextBuilder - builds context with pre-computed values
                 {
                     provide: internal_1.AuthFlowContextBuilder,
                     useFactory: (trustedDeviceService, adaptiveMFADecisionService, clientInfoService, logger) => {
@@ -385,6 +443,7 @@ let AuthModule = AuthModule_1 = class AuthModule {
                         { token: 'NAUTH_LOGGER', optional: true },
                     ],
                 },
+                // AuthFlowStateMachineService - evaluates authentication flow states
                 {
                     provide: internal_1.AuthFlowStateMachineService,
                     useFactory: (contextBuilder, logger) => {
@@ -412,7 +471,8 @@ let AuthModule = AuthModule_1 = class AuthModule {
                 },
                 {
                     provide: core_2.AuthService,
-                    useFactory: (userRepository, loginAttemptRepository, passwordService, jwtService, sessionService, challengeService, challengeHelper, emailVerificationService, clientInfoService, accountLockoutStorage, nauthConfig, logger, auditService, phoneVerificationService, mfaService, mfaDeviceRepository, trustedDeviceService, passwordResetService) => {
+                    useFactory: (userRepository, loginAttemptRepository, passwordService, jwtService, sessionService, challengeService, challengeHelper, emailVerificationService, clientInfoService, accountLockoutStorage, nauthConfig, logger, auditService, // Optional - only available when auditLogs.enabled is true
+                    phoneVerificationService, mfaService, mfaDeviceRepository, trustedDeviceService, passwordResetService) => {
                         return new core_2.AuthService(userRepository, loginAttemptRepository, passwordService, jwtService, sessionService, challengeService, challengeHelper, emailVerificationService, clientInfoService, accountLockoutStorage, nauthConfig, logger, auditService, phoneVerificationService, mfaService, mfaDeviceRepository, trustedDeviceService, passwordResetService);
                     },
                     inject: [
@@ -428,9 +488,9 @@ let AuthModule = AuthModule_1 = class AuthModule {
                         core_2.AccountLockoutStorageService,
                         'NAUTH_CONFIG',
                         'NAUTH_LOGGER',
-                        { token: internal_1.AuthAuditService, optional: true },
+                        { token: internal_1.AuthAuditService, optional: true }, // Optional - only available when auditLogs.enabled is true
                         { token: core_2.PhoneVerificationService, optional: true },
-                        { token: core_2.MFAService, optional: true },
+                        { token: core_2.MFAService, optional: true }, // No circular dependency - MFAService no longer depends on AuthService
                         { token: 'MFADeviceRepository', optional: true },
                         { token: internal_1.TrustedDeviceService, optional: true },
                         { token: internal_1.PasswordResetService, optional: true },
@@ -440,17 +500,25 @@ let AuthModule = AuthModule_1 = class AuthModule {
                     provide: internal_1.TrustedDeviceService,
                     useFactory: (config, logger, trustedDeviceRepository) => {
                         if (!trustedDeviceRepository) {
+                            // Return null if repository not available (rememberDevice disabled)
                             return null;
                         }
                         return new internal_1.TrustedDeviceService(config, logger, trustedDeviceRepository);
                     },
                     inject: ['NAUTH_CONFIG', 'NAUTH_LOGGER', { token: 'TrustedDeviceRepository', optional: true }],
                 },
+                // Social Auth State Store - shared Map for CSRF state validation across all providers
                 {
                     provide: 'SOCIAL_AUTH_STATE_STORE',
                     useValue: new Map(),
                 },
+                // Social Provider Registry - internal registry for social providers
+                // Provider modules (GoogleSocialAuthModule, AppleSocialAuthModule, etc.)
+                // will automatically register themselves with this registry via OnModuleInit
                 internal_1.SocialProviderRegistry,
+                // MFA Service - registry for auto-registered MFA providers
+                // Provider modules (TOTPMFAModule, SMSMFAModule, PasskeyMFAModule, etc.)
+                // will automatically register themselves with this service via OnModuleInit
                 {
                     provide: core_2.MFAService,
                     useFactory: (mfaDeviceRepository, userRepository, challengeService, nauthConfig, logger, auditService, clientInfoService) => {
@@ -477,12 +545,21 @@ let AuthModule = AuthModule_1 = class AuthModule {
                         'SocialAccountRepository',
                         core_2.AuthService,
                         'NAUTH_LOGGER',
-                        { token: internal_1.AuthAuditService, optional: true },
+                        { token: internal_1.AuthAuditService, optional: true }, // Optional - only available when auditLogs.enabled is true
                     ],
                 },
                 core_2.ClientInfoService,
+                // Conditionally provide AuthAuditService based on config.auditLogs.enabled
+                // Default to enabled if not specified (backward compatibility)
+                //
+                // Architecture:
+                // - Create ONE instance of InternalAuthAuditService
+                // - Export as InternalAuthAuditService for internal packages (social auth, MFA providers)
+                // - Alias as AuthAuditService for consumer apps (public API with fetch methods only)
+                // This ensures a single instance handles both recording and fetching
                 ...(config.auditLogs?.enabled !== false
                     ? [
+                        // Primary instance: InternalAuthAuditService (has recordEvent + fetch methods)
                         {
                             provide: internal_1.AuthAuditService,
                             useFactory: (auditRepository, userRepository, logger, clientInfoService) => {
@@ -490,6 +567,9 @@ let AuthModule = AuthModule_1 = class AuthModule {
                             },
                             inject: ['AuthAuditRepository', 'UserRepository', 'NAUTH_LOGGER', core_2.ClientInfoService],
                         },
+                        // Alias: AuthAuditService points to the same InternalAuthAuditService instance
+                        // Consumer apps inject AuthAuditService but get the full instance
+                        // TypeScript types prevent them from calling recordEvent() (not in public interface)
                         {
                             provide: core_2.AuthAuditService,
                             useExisting: internal_1.AuthAuditService,
@@ -528,19 +608,25 @@ let AuthModule = AuthModule_1 = class AuthModule {
                         core_2.ClientInfoService,
                         'NAUTH_CONFIG',
                         'NAUTH_LOGGER',
-                        { token: internal_1.AuthAuditService, optional: true },
+                        { token: internal_1.AuthAuditService, optional: true }, // Optional - only available when auditLogs.enabled is true
                     ],
                 },
+                // MaxMind Module (optional - only provided if package is installed and config is present)
+                // Uses dynamic import pattern (no require() - follows NestJS best practices)
                 ...(config.geoLocation?.maxMind
                     ? [
                         {
                             provide: 'MAXMIND_MODULE',
                             useFactory: async () => {
                                 try {
+                                    // Use dynamic import (ES modules) instead of require()
+                                    // This is the proper NestJS way to handle optional peer dependencies
+                                    // Note: Module may not be installed - catch block handles gracefully
                                     const maxMindModule = await Promise.resolve().then(() => __importStar(require('@maxmind/geoip2-node')));
                                     return maxMindModule;
                                 }
                                 catch {
+                                    // Package not installed - return null (service will handle gracefully)
                                     return null;
                                 }
                             },
@@ -552,6 +638,7 @@ let AuthModule = AuthModule_1 = class AuthModule {
                             useValue: null,
                         },
                     ]),
+                // GeoLocation Service (optional - only if MaxMind config provided)
                 ...(config.geoLocation?.maxMind
                     ? [
                         {
@@ -563,6 +650,7 @@ let AuthModule = AuthModule_1 = class AuthModule {
                         },
                     ]
                     : []),
+                // Email Provider (required - must be provided in config or from email package)
                 {
                     provide: 'EMAIL_PROVIDER',
                     useFactory: () => {
@@ -572,21 +660,25 @@ let AuthModule = AuthModule_1 = class AuthModule {
                                 '  yarn add @nauth-toolkit/email-nodemailer (for production)');
                         }
                         const provider = config.emailProvider;
+                        // Validate required methods (core contract)
                         if (typeof provider.sendVerificationEmail !== 'function' ||
                             typeof provider.sendPasswordResetEmail !== 'function' ||
                             typeof provider.sendWelcomeEmail !== 'function') {
                             throw new core_2.NAuthException(core_2.AuthErrorCode.VALIDATION_FAILED, 'emailProvider must implement sendVerificationEmail, sendPasswordResetEmail, and sendWelcomeEmail');
                         }
+                        // Inject logger into provider if it has setLogger method
                         {
                             const maybeLoggerAware = provider;
                             if (typeof maybeLoggerAware.setLogger === 'function') {
                                 maybeLoggerAware.setLogger(nauthLogger);
                             }
                         }
+                        // Inject global variables from email config if provider supports it
                         if (typeof provider
                             .setGlobalVariables === 'function' &&
                             config.email) {
                             const globalVars = {};
+                            // Extract top-level branding fields
                             if (config.email.appName)
                                 globalVars.appName = config.email.appName;
                             if (config.email.companyName)
@@ -601,6 +693,7 @@ let AuthModule = AuthModule_1 = class AuthModule {
                                 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 || {}),
@@ -623,9 +716,10 @@ let AuthModule = AuthModule_1 = class AuthModule {
                         'NAUTH_CONFIG',
                         core_2.ClientInfoService,
                         'NAUTH_LOGGER',
-                        { token: internal_1.AuthAuditService, optional: true },
+                        { token: internal_1.AuthAuditService, optional: true }, // Optional - only available when auditLogs.enabled is true
                     ],
                 },
+                // SMS Provider (optional - only needed if using phone verification)
                 ...(config.smsProvider
                     ? [
                         {
@@ -635,26 +729,36 @@ let AuthModule = AuthModule_1 = class AuthModule {
                                 if (!provider || typeof provider.sendOTP !== 'function') {
                                     throw new core_2.NAuthException(core_2.AuthErrorCode.VALIDATION_FAILED, 'smsProvider must implement sendOTP');
                                 }
+                                // Inject logger into provider if it has setLogger method
                                 {
                                     const maybeLoggerAware = provider;
                                     if (typeof maybeLoggerAware.setLogger === 'function') {
                                         maybeLoggerAware.setLogger(nauthLogger);
                                     }
                                 }
+                                // ============================================================================
+                                // Initialize SMS Template Engine
+                                // ============================================================================
                                 const smsTemplates = config.sms?.templates;
                                 if (smsTemplates) {
+                                    // If user configured templates, the provider must support the template hooks.
+                                    // This avoids silent fallback to hard-coded messages when templates are expected.
                                     if (typeof provider.setTemplateEngine !== 'function') {
                                         throw new core_2.NAuthException(core_2.AuthErrorCode.VALIDATION_FAILED, 'sms.templates is configured, but smsProvider does not support templates. ' +
                                             'Please upgrade your SMS provider package to a version that implements setTemplateEngine().');
                                     }
+                                    // Use provided engine or create new one
                                     const templateEngine = smsTemplates.engine ?? new core_2.SMSTemplateEngineImpl(process.cwd(), nauthLogger);
+                                    // Register custom templates
                                     if (smsTemplates.customTemplates) {
                                         for (const [type, templateDef] of Object.entries(smsTemplates.customTemplates)) {
                                             try {
                                                 if (templateDef.content) {
+                                                    // Inline template
                                                     templateEngine.registerTemplate(type, { content: templateDef.content });
                                                 }
                                                 else if (templateDef.contentPath) {
+                                                    // File-based template
                                                     await templateEngine.registerTemplateFromSources(type, {
                                                         content: { filePath: templateDef.contentPath },
                                                     });
@@ -666,8 +770,11 @@ let AuthModule = AuthModule_1 = class AuthModule {
                                             }
                                         }
                                     }
+                                    // Inject template engine into provider
                                     provider.setTemplateEngine(templateEngine);
+                                    // Set global variables
                                     if (typeof provider.setGlobalVariables === 'function' && smsTemplates.globalVariables) {
+                                        // Extract top-level branding fields from email config (if available)
                                         const globalVars = {};
                                         if (config.email?.appName)
                                             globalVars.appName = config.email.appName;
@@ -675,6 +782,8 @@ let AuthModule = AuthModule_1 = class AuthModule {
                                             globalVars.companyName = config.email.companyName;
                                         if (config.email?.supportEmail)
                                             globalVars.supportEmail = config.email.supportEmail;
+                                        // Merge with sms.templates.globalVariables (sms.templates.globalVariables takes precedence)
+                                        // Filter out non-compatible types from globalVariables
                                         const smsGlobalVars = {};
                                         for (const [key, value] of Object.entries(smsTemplates.globalVariables)) {
                                             if (typeof value === 'string' ||
@@ -706,7 +815,7 @@ let AuthModule = AuthModule_1 = class AuthModule {
                                 'STORAGE_ADAPTER',
                                 'NAUTH_CONFIG',
                                 core_2.ClientInfoService,
-                                { token: internal_1.AuthAuditService, optional: true },
+                                { token: internal_1.AuthAuditService, optional: true }, // Optional - only available when auditLogs.enabled is true
                                 'NAUTH_LOGGER',
                             ],
                         },
@@ -714,7 +823,8 @@ let AuthModule = AuthModule_1 = class AuthModule {
                     : []),
                 {
                     provide: internal_1.PasswordResetService,
-                    useFactory: (verificationTokenRepo, emailProvider, storageAdapter, nauthConfig, clientInfoService, logger, auditService, smsProvider) => {
+                    useFactory: (verificationTokenRepo, emailProvider, storageAdapter, nauthConfig, clientInfoService, logger, auditService, // Optional - only available when auditLogs.enabled is true
+                    smsProvider) => {
                         return new internal_1.PasswordResetService(verificationTokenRepo, emailProvider, storageAdapter, nauthConfig, clientInfoService, logger, auditService, smsProvider);
                     },
                     inject: [
@@ -724,8 +834,8 @@ let AuthModule = AuthModule_1 = class AuthModule {
                         'NAUTH_CONFIG',
                         core_2.ClientInfoService,
                         'NAUTH_LOGGER',
-                        { token: internal_1.AuthAuditService, optional: true },
-                        { token: 'SMS_PROVIDER', optional: true },
+                        { token: internal_1.AuthAuditService, optional: true }, // Optional - only available when auditLogs.enabled is true
+                        { token: 'SMS_PROVIDER', optional: true }, // Optional - only available when smsProvider is configured
                     ],
                 },
                 {
@@ -742,6 +852,7 @@ let AuthModule = AuthModule_1 = class AuthModule {
                     },
                     inject: ['STORAGE_ADAPTER'],
                 },
+                // Guards
                 auth_guard_1.AuthGuard,
                 ...(config.tokenDelivery?.method === 'cookies' || config.tokenDelivery?.method === 'hybrid' ? [csrf_guard_1.CsrfGuard] : []),
             ],
@@ -751,9 +862,14 @@ let AuthModule = AuthModule_1 = class AuthModule {
                 internal_1.JwtService,
                 internal_1.SessionService,
                 internal_1.ChallengeService,
-                internal_1.AuthChallengeHelperService,
-                internal_1.SocialProviderRegistry,
+                internal_1.AuthChallengeHelperService, // Needed by social auth providers
+                internal_1.SocialProviderRegistry, // Needed by social auth provider modules for auto-registration
                 core_2.ClientInfoService,
+                // Audit Services (conditional - only if enabled)
+                // Single instance, exported under two tokens:
+                //   - AuthAuditService (public API) - For consumer apps to fetch audit logs (TypeScript prevents recordEvent)
+                //   - InternalAuthAuditService - For INTERNAL toolkit packages ONLY (social auth, MFA providers)
+                // Consumer apps should inject AuthAuditService, internal packages inject InternalAuthAuditService
                 ...(config.auditLogs?.enabled !== false ? [core_2.AuthAuditService, internal_1.AuthAuditService] : []),
                 auth_guard_1.AuthGuard,
                 ...(config.tokenDelivery?.method === 'cookies' || config.tokenDelivery?.method === 'hybrid'
@@ -765,19 +881,42 @@ let AuthModule = AuthModule_1 = class AuthModule {
                 'EMAIL_PROVIDER',
                 core_2.EmailVerificationService,
                 ...(config.smsProvider ? ['SMS_PROVIDER', core_2.PhoneVerificationService] : []),
-                core_2.SocialAuthService,
-                core_2.MFAService,
+                core_2.SocialAuthService, // Always export - providers register themselves when modules are imported
+                core_2.MFAService, // Always export - MFA providers register themselves when modules are imported
+                // TrustedDeviceService is provided but not exported (used internally by AuthService)
                 'NAUTH_LOGGER',
-                'NAUTH_CONFIG',
-                'SOCIAL_AUTH_STATE_STORE',
+                'NAUTH_CONFIG', // Export config so other modules can access it
+                'SOCIAL_AUTH_STATE_STORE', // Needed by social auth providers for CSRF protection
+                // Repository tokens exported for internal toolkit packages (MFA providers, etc.)
+                // WARNING: These are for INTERNAL toolkit packages ONLY, not consumer apps
+                // Consumer apps should use service methods (AuthService, MFAService, etc.) instead of direct repository access
                 'UserRepository',
                 'MFADeviceRepository',
+                // Note: TypeOrmModule not exported to prevent consumer apps from accessing entities directly
+                // Note: MFA provider services (TOTPMFAProviderService, SMSMFAProviderService, PasskeyMFAProviderService)
+                // are in @nauth-toolkit/mfa-* packages and auto-register with MFAService
+                // These providers need repository access but are internal toolkit packages, not consumer apps
+                // Note: PhoneVerificationService is provided from core when an SMS provider is configured
             ],
         };
     }
+    /**
+     * Validate configuration using Zod schema
+     *
+     * Validates all configuration sections and cross-dependencies:
+     * - Email/phone verification requires respective providers
+     * - MFA enforcement modes require specific configurations
+     * - Social providers require credentials when enabled
+     * - JWT algorithm requires appropriate keys
+     * - MaxMind geolocation requires credentials for downloads
+     *
+     * @param config - Configuration to validate
+     * @throws {NAuthException} If validation fails with detailed error messages
+     */
     static validateConfig(config) {
         const result = core_2.authConfigSchema.safeParse(config);
         if (!result.success) {
+            // Format Zod errors into readable messages
             const errors = result.error.errors
                 .map((err) => {
                 const path = err.path.length > 0 ? err.path.join('.') : 'root';
@@ -787,6 +926,9 @@ let AuthModule = AuthModule_1 = class AuthModule {
             throw new core_2.NAuthException(core_2.AuthErrorCode.VALIDATION_FAILED, `Configuration validation failed:\n\n${errors}\n\n` +
                 'Please check your auth configuration and ensure all required fields are provided.');
         }
+        // Configuration is valid - no need to return anything
+        // TypeScript types ensure type safety at compile time
+        // Zod ensures runtime validation for JavaScript/Express apps
     }
 };
 exports.AuthModule = AuthModule;