@nauth-toolkit/core 0.1.0 → 0.1.3

package/src/bootstrap.ts

@@ -1,374 +0,0 @@
-/**
- * NAuth Bootstrap
- *
- * Entry point for initializing NAuth with platform adapters.
- *
- * **Usage:**
- * ```typescript
- * import { NAuth, ExpressAdapter } from '@nauth-toolkit/core';
- *
- * const nauth = await NAuth.create({
- *   config: authConfig,
- *   dataSource: dataSource,
- *   adapter: new ExpressAdapter(),
- * });
- *
- * // Mount middleware
- * app.use(nauth.middleware.clientInfo);
- * app.use(nauth.middleware.csrf);
- * app.use(nauth.middleware.auth);
- * app.use(nauth.middleware.tokenDelivery);
- *
- * // Protected routes
- * app.get('/profile', nauth.helpers.requireAuth(), (req, res) => {
- *   const user = nauth.helpers.getCurrentUser();
- *   res.json({ user });
- * });
- * ```
- */
-
-import { DataSource } from 'typeorm';
-import { NAuthConfig } from './interfaces/config.interface';
-import { NAuthLogger } from './utils/nauth-logger';
-import { NAuthException } from './exceptions/nauth.exception';
-import { AuthErrorCode } from './enums/error-codes.enum';
-import { NAuthAdapter, NAuthRequest, NAuthResponse } from './platform/interfaces';
-import { ExpressAdapter } from './adapters/express.adapter';
-import { ContextStorage } from './utils/context-storage';
-
-// Handlers
-import { ClientInfoHandler } from './handlers/client-info.handler';
-import { AuthHandler } from './handlers/auth.handler';
-import { TokenDeliveryHandler } from './handlers/token-delivery.handler';
-import { CsrfHandler } from './handlers/csrf.handler';
-import { CsrfService } from './services/csrf.service';
-
-// Setup Helpers
-import { getRepositories } from './utils/setup/get-repositories';
-import { initStorage } from './utils/setup/init-storage';
-import { initServices, NAuthServices } from './utils/setup/init-services';
-import { registerMFAProviders } from './utils/setup/register-mfa';
-import { initSocialAuth, NAuthSocialProviders } from './utils/setup/init-social';
-import { runNAuthMigrationsOnStartup } from './utils/setup/run-nauth-migrations';
-import { AuthFlowContextBuilder, AuthFlowStateMachineService } from './internal';
-import { ClientInfo } from './interfaces/client-info.interface';
-import { IUser } from './interfaces/entities.interface';
-
-// ============================================================================
-// Types
-// ============================================================================
-
-/**
- * Options for NAuth initialization
- */
-export interface NAuthOptions {
-  /** NAuth configuration */
-  config: NAuthConfig;
-
-  /** TypeORM DataSource */
-  dataSource: DataSource;
-
-  /**
-   * Platform adapter (Express, Fastify, etc.)
-   * @default ExpressAdapter
-   */
-  adapter?: NAuthAdapter;
-}
-
-/**
- * NAuth instance returned by NAuth.create()
- *
- * Contains services, middleware, and helpers for authentication.
- *
- * @typeParam TMiddleware - Type for middleware (framework-specific)
- * @typeParam THelper - Type for route helpers (framework-specific)
- */
-export interface NAuthInstance<TMiddleware = unknown, THelper = unknown>
-  extends Omit<NAuthServices, 'challengeService' | 'authChallengeHelperService'>, NAuthSocialProviders {
-  /** Framework-specific middleware/hooks */
-  middleware: {
-    /** Client info extraction (MUST BE FIRST) */
-    clientInfo: TMiddleware;
-    /** JWT authentication */
-    auth: TMiddleware;
-    /** CSRF protection */
-    csrf: TMiddleware;
-    /** Token delivery (response interceptor) */
-    tokenDelivery: TMiddleware;
-  };
-
-  /** Route helpers */
-  helpers: {
-    /** Mark route as public (bypasses CSRF) */
-    public: () => THelper;
-    /** Require authentication (with optional CSRF bypass) */
-    requireAuth: (options?: { csrf?: boolean }) => THelper;
-    /** Optional authentication marker */
-    optionalAuth: () => THelper;
-    /** Override token delivery mode */
-    tokenDelivery: (mode: 'json' | 'cookies') => THelper;
-    /** Get current authenticated user */
-    getCurrentUser: () => IUser | undefined;
-    /** Get current session ID */
-    getCurrentSession: () => string | number | undefined;
-    /** Get client info */
-    getClientInfo: () => ClientInfo | undefined;
-  };
-
-  /** The adapter being used */
-  adapter: NAuthAdapter;
-
-  /** Configuration */
-  config: NAuthConfig;
-
-  /** Logger instance */
-  logger: NAuthLogger;
-
-  /** CSRF service (if enabled) */
-  csrfService?: CsrfService;
-}
-
-// ============================================================================
-// NAuth Bootstrap Class
-// ============================================================================
-
-/**
- * NAuth Bootstrap
- *
- * Main entry point for initializing NAuth.
- */
-export class NAuth {
-  /**
-   * Create NAuth instance
-   *
-   * @param options - Configuration options
-   * @returns Initialized NAuth instance
-   *
-   * @example
-   * ```typescript
-   * const nauth = await NAuth.create({
-   *   config: authConfig,
-   *   dataSource: dataSource,
-   *   adapter: new ExpressAdapter(),
-   * });
-   * ```
-   */
-  static async create(options: NAuthOptions): Promise<NAuthInstance> {
-    const { config, dataSource } = options;
-    const adapter = options.adapter || new ExpressAdapter();
-
-    const logger = new NAuthLogger(config.logger);
-    logger.log(`Initializing NAuth with ${adapter.name}...`);
-
-    // ========================================================================
-    // 0. Run database migrations (adapter-owned, auto-run, no consumer burden)
-    // ========================================================================
-    await runNAuthMigrationsOnStartup(config, dataSource, logger);
-
-    // ========================================================================
-    // 1. Initialize Repositories & Storage
-    // ========================================================================
-    const repos = getRepositories(dataSource);
-    const storage = await initStorage(config, repos.rateLimitRepository, repos.storageLockRepository, logger);
-
-    // ========================================================================
-    // 2. Initialize Services
-    // ========================================================================
-    const emailProvider = config.emailProvider;
-    const smsProvider = config.smsProvider;
-    const services: NAuthServices = initServices(config, repos, storage, logger, emailProvider, smsProvider);
-
-    // ========================================================================
-    // 3. Initialize Auth Flow State Machine
-    // ========================================================================
-    const contextBuilder = new AuthFlowContextBuilder(
-      services.trustedDeviceService,
-      services.adaptiveMFADecisionService,
-      services.clientInfoService,
-      logger,
-    );
-    const stateMachine = new AuthFlowStateMachineService(contextBuilder, logger);
-
-    if (services.authChallengeHelperService) {
-      (services.authChallengeHelperService as unknown as Record<string, unknown>).stateMachine = stateMachine;
-      (services.authChallengeHelperService as unknown as Record<string, unknown>).contextBuilder = contextBuilder;
-    } else {
-      throw new NAuthException(AuthErrorCode.INTERNAL_ERROR, 'AuthChallengeHelperService not initialized.');
-    }
-
-    // ========================================================================
-    // 4. Register MFA & Social Providers
-    // ========================================================================
-    const socialAuthStateStore = new Map<string, { timestamp: number; provider: string }>();
-
-    if (config.mfa?.enabled && services.mfaService) {
-      await registerMFAProviders(
-        config,
-        services.mfaService,
-        repos.mfaDeviceRepository!,
-        repos.userRepository,
-        logger,
-        services.passwordService,
-        services.emailVerificationService,
-        services.phoneVerificationService,
-        services.challengeService,
-        services.auditService,
-        services.clientInfoService,
-      );
-    }
-
-    const socialProviders: NAuthSocialProviders = await initSocialAuth(
-      config,
-      services.socialProviderRegistry,
-      services.authService,
-      services.socialAuthService,
-      services.jwtService,
-      services.sessionService,
-      services.authChallengeHelperService,
-      services.clientInfoService,
-      logger,
-      socialAuthStateStore,
-      repos.userRepository,
-      services.phoneVerificationService,
-      services.auditService,
-      services.trustedDeviceService,
-    );
-
-    // ========================================================================
-    // 5. Create Handlers
-    // ========================================================================
-    const clientInfoHandler = new ClientInfoHandler(services.clientInfoService, services.geoLocationService, logger);
-
-    const authHandler = new AuthHandler(
-      services.jwtService,
-      services.sessionService,
-      repos.userRepository,
-      config,
-      logger,
-    );
-
-    const tokenDeliveryHandler = new TokenDeliveryHandler(config, logger);
-
-    // CSRF service (only for cookies/hybrid delivery)
-    const csrfService =
-      config.tokenDelivery?.method === 'cookies' || config.tokenDelivery?.method === 'hybrid'
-        ? new CsrfService(config)
-        : undefined;
-
-    const csrfHandler = csrfService ? new CsrfHandler(csrfService, config, logger) : null;
-
-    // ========================================================================
-    // 6. Register Middleware with Adapter
-    // ========================================================================
-    const middleware = {
-      // ClientInfo MUST be first - initializes context
-      clientInfo: adapter.registerMiddleware('clientInfo', clientInfoHandler.handle.bind(clientInfoHandler), {
-        initializesContext: true,
-      }),
-
-      // Auth handler
-      auth: adapter.registerMiddleware('auth', authHandler.handle.bind(authHandler)),
-
-      // CSRF handler (no-op if disabled)
-      csrf: csrfHandler
-        ? adapter.registerMiddleware('csrf', csrfHandler.handle.bind(csrfHandler))
-        : adapter.registerMiddleware('noop', async (_req: NAuthRequest, _res: NAuthResponse, next: () => void) => {
-            await next();
-          }),
-
-      // Token delivery (response interceptor)
-      tokenDelivery: adapter.registerResponseInterceptor(
-        tokenDeliveryHandler.handleResponse.bind(tokenDeliveryHandler),
-      ),
-    };
-
-    // ========================================================================
-    // 7. Create Helpers
-    // ========================================================================
-    const helpers = {
-      /**
-       * Mark route as public - bypasses CSRF validation
-       */
-      public: () =>
-        adapter.registerMiddleware('public', (req: NAuthRequest, _res: NAuthResponse, next: () => void) => {
-          req.attributes.nauthPublic = true;
-          return next();
-        }),
-
-      /**
-       * Require authentication
-       *
-       * @param options.csrf - Set to false to bypass CSRF check (e.g., for logout)
-       */
-      requireAuth: (options?: { csrf?: boolean }) =>
-        adapter.registerMiddleware('requireAuth', (req: NAuthRequest, res: NAuthResponse, next: () => void) => {
-          // Enforce deferred CSRF check (unless disabled)
-          if (options?.csrf !== false && req.attributes.nauthCsrfError) {
-            throw req.attributes.nauthCsrfError;
-          }
-
-          // Enforce authentication
-          if (!req.attributes.user) {
-            res.status(401).json({
-              statusCode: 401,
-              error: 'Unauthorized',
-              message: 'Authentication required',
-              code: 'AUTH_REQUIRED',
-            });
-            return;
-          }
-
-          return next();
-        }),
-
-      /**
-       * Optional authentication marker
-       *
-       * Auth middleware already does optional auth by default.
-       * This helper is a semantic marker for documentation purposes.
-       */
-      optionalAuth: () =>
-        adapter.registerMiddleware('optionalAuth', (_req: NAuthRequest, _res: NAuthResponse, next: () => void) => {
-          return next();
-        }),
-
-      /**
-       * Override token delivery mode for this route
-       */
-      tokenDelivery: (mode: 'json' | 'cookies') =>
-        adapter.registerMiddleware(
-          'tokenDeliveryConfig',
-          (req: NAuthRequest, _res: NAuthResponse, next: () => void) => {
-            req.attributes.nauthTokenDelivery = mode;
-            return next();
-          },
-        ),
-
-      // Context helpers (read from ContextStorage)
-      getCurrentUser: () => ContextStorage.get<IUser>('CURRENT_USER'),
-      getCurrentSession: () => ContextStorage.get<string | number>('CURRENT_SESSION'),
-      getClientInfo: () => ContextStorage.get<ClientInfo>('CLIENT_INFO'),
-    };
-
-    // ========================================================================
-    // 8. Build and Return Instance
-    // ========================================================================
-
-    // Exclude internal services from public API
-    const { challengeService, authChallengeHelperService, ...publicServices } = services;
-
-    logger.log(`NAuth initialized successfully with ${adapter.name}`);
-
-    return {
-      ...publicServices,
-      ...socialProviders,
-      middleware,
-      helpers,
-      adapter,
-      config,
-      logger,
-      socialAuthService: services.socialAuthService,
-      csrfService,
-    };
-  }
-}

package/src/dto/auth-challenge.dto.ts

@@ -1,231 +0,0 @@
-import { IsEnum, IsUUID, IsObject } from 'class-validator';
-import { Transform } from 'class-transformer';
-
-/**
- * Authentication Challenge Types
- *
- * Represents different challenges that must be completed before
- * a user can gain full access to the system. This is similar to
- * AWS Cognito's challenge system.
- *
- * @example
- * ```typescript
- * // After login, check for challenges
- * const result = await authService.login(credentials);
- * if (result.challengeName) {
- *   // User must complete challenge before accessing system
- *   console.log('Challenge required:', result.challengeName);
- * }
- * ```
- */
-export enum AuthChallenge {
-  /**
-   * Email verification required
-   * User must verify their email address before proceeding
-   */
-  VERIFY_EMAIL = 'VERIFY_EMAIL',
-
-  /**
-   * Phone verification required
-   * User must verify their phone number before proceeding
-   */
-  VERIFY_PHONE = 'VERIFY_PHONE',
-
-  /**
-   * Multi-factor authentication required
-   * User must complete MFA verification (TOTP, SMS, etc.)
-   * This challenge is used when user already has MFA enabled and needs to verify
-   */
-  MFA_REQUIRED = 'MFA_REQUIRED',
-
-  /**
-   * MFA setup required
-   * User must set up multi-factor authentication before being allowed to login.
-   * This occurs when enforcement is 'REQUIRED' and grace period has expired or is disabled.
-   */
-  MFA_SETUP_REQUIRED = 'MFA_SETUP_REQUIRED',
-
-  /**
-   * Password change required
-   * User must change their password before proceeding
-   * (e.g., admin-forced password reset, expired password)
-   */
-  FORCE_CHANGE_PASSWORD = 'FORCE_CHANGE_PASSWORD',
-}
-
-/**
- * Challenge Response DTO
- *
- * Used when a user's authentication is incomplete due to pending challenges.
- * Contains minimal information about the user and what challenges they must complete.
- *
- * Note: This is primarily a response DTO, but validation is included for completeness.
- *
- * @example
- * ```typescript
- * // Login response with challenge
- * {
- *   challengeName: 'VERIFY_EMAIL',
- *   session: 'a21b654c-2746-4168-acee-c175083a65cd',
- *   challengeParameters: {
- *     email: 'user@example.com',
- *     codeDeliveryDestination: 'u***@example.com'
- *   },
- *   userSub: 'a21b654c-2746-4168-acee-c175083a65cd'
- * }
- * ```
- */
-export class AuthChallengeResponseDTO {
-  /**
-   * The challenge that must be completed
-   *
-   * Validation:
-   * - Must be a valid AuthChallenge enum value
-   */
-  @IsEnum(AuthChallenge, {
-    message: 'Challenge name must be a valid AuthChallenge enum value',
-  })
-  challengeName!: AuthChallenge;
-
-  /**
-   * Temporary session identifier for challenge completion (UUID v4)
-   * This is NOT a full JWT token - only used for challenge verification
-   *
-   * Validation:
-   * - Must be a valid UUID v4 format
-   * - Generated using randomUUID() in challenge service
-   *
-   * @example "a21b654c-2746-4168-acee-c175083a65cd"
-   */
-  @IsUUID('4', { message: 'Session token must be a valid UUID v4 format' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim().toLowerCase();
-    }
-    return value;
-  })
-  session!: string;
-
-  /**
-   * Challenge-specific parameters
-   * Contains information needed to complete the challenge
-   *
-   * Validation:
-   * - Must be an object
-   *
-   * @example
-   * ```typescript
-   * // For VERIFY_EMAIL
-   * {
-   *   email: 'user@example.com',
-   *   codeDeliveryDestination: 'u***@example.com'
-   * }
-   *
-   * // For VERIFY_PHONE
-   * {
-   *   phone: '+1234567890',
-   *   codeDeliveryDestination: '***-***-7890'
-   * }
-   * ```
-   */
-  @IsObject({ message: 'Challenge parameters must be an object' })
-  challengeParameters!: Record<string, unknown>;
-
-  /**
-   * User's unique identifier (UUID v4)
-   * Provided so the client knows which user is completing challenges
-   *
-   * Validation:
-   * - Must be a valid UUID v4 format
-   * - Matches DB constraint: char(36) or uuid
-   *
-   * @example "a21b654c-2746-4168-acee-c175083a65cd"
-   */
-  @IsUUID('4', { message: 'User sub must be a valid UUID v4 format' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim().toLowerCase();
-    }
-    return value;
-  })
-  userSub!: string;
-}
-
-/**
- * Challenge Completion Request DTO
- *
- * Used to submit a response to an authentication challenge.
- *
- * Note: This is a legacy DTO. The codebase now uses RespondChallengeDTO for the unified API.
- * This DTO is kept for backwards compatibility.
- *
- * Security:
- * - Session token validated as UUID v4 format
- * - Challenge name validated against enum
- * - Challenge responses validated as object
- *
- * @example
- * ```typescript
- * // Verify email challenge
- * const request: ChallengeResponseRequestDTO = {
- *   session: 'a21b654c-2746-4168-acee-c175083a65cd',
- *   challengeName: 'VERIFY_EMAIL',
- *   challengeResponses: {
- *     code: '123456'
- *   }
- * };
- * ```
- */
-export class ChallengeResponseRequestDTO {
-  /**
-   * Temporary session from initial auth response (UUID v4)
-   *
-   * Validation:
-   * - Must be a valid UUID v4 format
-   * - Generated using randomUUID() in challenge service
-   *
-   * Sanitization:
-   * - Trimmed
-   * - Lowercased for consistency
-   *
-   * @example "a21b654c-2746-4168-acee-c175083a65cd"
-   */
-  @IsUUID('4', { message: 'Session token must be a valid UUID v4 format' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim().toLowerCase();
-    }
-    return value;
-  })
-  session!: string;
-
-  /**
-   * The challenge being responded to
-   *
-   * Validation:
-   * - Must be a valid AuthChallenge enum value
-   */
-  @IsEnum(AuthChallenge, {
-    message: 'Challenge name must be a valid AuthChallenge enum value',
-  })
-  challengeName!: AuthChallenge;
-
-  /**
-   * Challenge-specific responses
-   *
-   * Validation:
-   * - Must be an object
-   * - Structure validated in service layer based on challenge type
-   *
-   * @example
-   * ```typescript
-   * // For VERIFY_EMAIL or VERIFY_PHONE
-   * { code: '123456' }
-   *
-   * // For FORCE_CHANGE_PASSWORD
-   * { newPassword: 'NewSecure123!' }
-   * ```
-   */
-  @IsObject({ message: 'Challenge responses must be an object' })
-  challengeResponses!: Record<string, unknown>;
-}