@nauth-toolkit/core 0.1.0 → 0.1.5

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

@@ -1,272 +0,0 @@
-/**
- * Unified Challenge Response DTO with Comprehensive Validation
- *
- * Provides class-validator validation for challenge responses.
- * This is the single source of truth for challenge response validation,
- * used by both NestJS and Express adapters.
- *
- * Security Features:
- * - All string inputs have max length (prevents DoS attacks)
- * - Phone numbers validated against E.164 format
- * - Password strength enforced (8-128 chars)
- * - Conditional validation based on challenge type
- * - Enum validation prevents invalid challenge types
- *
- * @module RespondChallengeDTO
- */
-
-import { IsString, IsEnum, ValidateIf, IsObject, MinLength, MaxLength, Matches, Length, IsUUID } from 'class-validator';
-import { Transform } from 'class-transformer';
-
-/**
- * Challenge type enum for validation
- */
-export enum ChallengeType {
-  VERIFY_EMAIL = 'VERIFY_EMAIL',
-  VERIFY_PHONE = 'VERIFY_PHONE',
-  MFA_REQUIRED = 'MFA_REQUIRED',
-  FORCE_CHANGE_PASSWORD = 'FORCE_CHANGE_PASSWORD',
-  MFA_SETUP_REQUIRED = 'MFA_SETUP_REQUIRED',
-}
-
-/**
- * MFA method enum for validation
- */
-export enum MFAMethodType {
-  SMS = 'sms',
-  EMAIL = 'email',
-  TOTP = 'totp',
-  PASSKEY = 'passkey',
-  BACKUP = 'backup',
-}
-
-/**
- * Unified DTO for responding to authentication challenges
- *
- * Uses conditional validation (@ValidateIf) to validate fields based on challenge type.
- * This ensures proper validation while maintaining a single endpoint for all challenge types.
- *
- * Security:
- * - All strings have max length constraints matching DB limits
- * - Phone numbers validated against E.164 format (prevents SQL injection)
- * - Verification codes validated for length (4-10 chars)
- * - Passwords validated for strength requirements
- * - Session tokens validated as UUID v4 format (prevents injection)
- *
- * @example
- * ```typescript
- * @Controller('auth')
- * export class AuthController {
- *   @Post('respond-challenge')
- *   async respondToChallenge(@Body() dto: RespondChallengeDTO) {
- *     return await this.authService.respondToChallenge(dto);
- *   }
- * }
- * ```
- */
-export class RespondChallengeDTO {
-  /**
-   * Challenge session token (UUID v4)
-   * Always required
-   *
-   * Validation:
-   * - Must be a valid UUID v4 format
-   * - Generated using randomUUID() in challenge service
-   * - Matches DB constraint: varchar(255) but UUID format enforced
-   *
-   * 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;
-
-  /**
-   * Challenge type being responded to
-   * Always required
-   */
-  @IsEnum(ChallengeType, {
-    message:
-      'Challenge type must be one of: VERIFY_EMAIL, VERIFY_PHONE, MFA_REQUIRED, FORCE_CHANGE_PASSWORD, MFA_SETUP_REQUIRED',
-  })
-  type!: ChallengeType;
-
-  // ============================================================================
-  // VERIFY_EMAIL / VERIFY_PHONE / MFA_REQUIRED (code-based)
-  // ============================================================================
-
-  /**
-   * Verification code
-   * Required for:
-   * - VERIFY_EMAIL
-   * - VERIFY_PHONE (when verifying code)
-   * - MFA_REQUIRED (for SMS/Email/TOTP/Backup methods)
-   *
-   * Validation:
-   * - Must be a string
-   * - Length 4-10 characters (covers all code types)
-   * - Alphanumeric only
-   *
-   * Note: NOT trimmed (codes should be exact)
-   */
-  @ValidateIf(
-    (o) =>
-      o.type === ChallengeType.VERIFY_EMAIL ||
-      (o.type === ChallengeType.VERIFY_PHONE && !o.phone) ||
-      (o.type === ChallengeType.MFA_REQUIRED && o.method !== MFAMethodType.PASSKEY),
-  )
-  @IsString({ message: 'Code must be a string' })
-  @Length(4, 10, { message: 'Code must be between 4 and 10 characters' })
-  @Matches(/^[A-Za-z0-9]+$/, { message: 'Code can only contain letters and numbers' })
-  code?: string;
-
-  // ============================================================================
-  // VERIFY_PHONE (phone collection)
-  // ============================================================================
-
-  /**
-   * Phone number in E.164 format
-   * Required for VERIFY_PHONE when collecting phone number (first step)
-   *
-   * Validation:
-   * - Must be a string
-   * - Must match E.164 format: +[country code][number]
-   * - Example: +14155552671
-   * - Max 20 characters (matches DB limit)
-   *
-   * Sanitization:
-   * - Trimmed
-   * - Only digits and leading + allowed
-   */
-  @ValidateIf((o) => o.type === ChallengeType.VERIFY_PHONE && !o.code)
-  @IsString({ message: 'Phone must be a string' })
-  @MaxLength(20, { message: 'Phone number must not exceed 20 characters' })
-  @Matches(/^\+[1-9]\d{1,14}$/, {
-    message: 'Phone must be in E.164 format (e.g., +14155552671)',
-  })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim();
-    }
-    return value;
-  })
-  phone?: string;
-
-  // ============================================================================
-  // FORCE_CHANGE_PASSWORD
-  // ============================================================================
-
-  /**
-   * New password
-   * Required for FORCE_CHANGE_PASSWORD challenge
-   *
-   * Validation:
-   * - Must be a string
-   * - Min 8 characters (security requirement)
-   * - Max 128 characters (prevents DoS via bcrypt)
-   *
-   * Note: NOT trimmed (passwords can have leading/trailing spaces)
-   */
-  @ValidateIf((o) => o.type === ChallengeType.FORCE_CHANGE_PASSWORD)
-  @IsString({ message: 'New password must be a string' })
-  @MinLength(8, { message: 'Password must be at least 8 characters' })
-  @MaxLength(128, { message: 'Password must not exceed 128 characters' })
-  newPassword?: string;
-
-  // ============================================================================
-  // MFA_REQUIRED / MFA_SETUP_REQUIRED
-  // ============================================================================
-
-  /**
-   * MFA method being used or set up
-   * Required for:
-   * - MFA_REQUIRED challenge (method being used for verification)
-   * - MFA_SETUP_REQUIRED challenge (method being set up)
-   *
-   * Validation:
-   * - Must be one of: sms, email, totp, passkey, backup
-   */
-  @ValidateIf((o) => o.type === ChallengeType.MFA_REQUIRED || o.type === ChallengeType.MFA_SETUP_REQUIRED)
-  @IsEnum(MFAMethodType, { message: 'MFA method must be one of: sms, email, totp, passkey, backup' })
-  method?: MFAMethodType;
-
-  /**
-   * Passkey credential
-   * Required for MFA_REQUIRED when method is 'passkey'
-   *
-   * Validation:
-   * - Must be an object
-   * - Contains WebAuthn credential from navigator.credentials.get()
-   */
-  @ValidateIf((o) => o.type === ChallengeType.MFA_REQUIRED && o.method === MFAMethodType.PASSKEY)
-  @IsObject({ message: 'Credential must be an object' })
-  credential?: Record<string, unknown>;
-
-  // ============================================================================
-  // MFA_SETUP_REQUIRED
-  // ============================================================================
-
-  /**
-   * MFA setup data (method-specific)
-   * Required for MFA_SETUP_REQUIRED challenge
-   *
-   * Expected structure by method:
-   * - SMS: { phone: string, code: string }
-   * - Email: { code: string }
-   * - TOTP: { code: string }
-   * - Passkey: { credential: Record<string, unknown> }
-   *
-   * Validation:
-   * - Must be an object
-   * - Structure validated by MFA provider services
-   */
-  @ValidateIf((o) => o.type === ChallengeType.MFA_SETUP_REQUIRED)
-  @IsObject({ message: 'Setup data must be an object' })
-  setupData?: Record<string, unknown>;
-}
-
-/**
- * Helper type guards for challenge response
- *
- * Use these to narrow TypeScript types in your application logic.
- *
- * @example
- * ```typescript
- * if (RespondChallengeValidation.isEmailVerification(dto)) {
- *   // TypeScript knows dto.code is available
- * }
- * ```
- */
-export namespace RespondChallengeValidation {
-  export function isEmailVerification(dto: RespondChallengeDTO): boolean {
-    return dto.type === ChallengeType.VERIFY_EMAIL && !!dto.code;
-  }
-
-  export function isPhoneCollection(dto: RespondChallengeDTO): boolean {
-    return dto.type === ChallengeType.VERIFY_PHONE && !!dto.phone;
-  }
-
-  export function isPhoneVerification(dto: RespondChallengeDTO): boolean {
-    return dto.type === ChallengeType.VERIFY_PHONE && !!dto.code;
-  }
-
-  export function isPasswordChange(dto: RespondChallengeDTO): boolean {
-    return dto.type === ChallengeType.FORCE_CHANGE_PASSWORD && !!dto.newPassword;
-  }
-
-  export function isMFAVerification(dto: RespondChallengeDTO): boolean {
-    return dto.type === ChallengeType.MFA_REQUIRED && !!dto.method;
-  }
-
-  export function isMFASetup(dto: RespondChallengeDTO): boolean {
-    return dto.type === ChallengeType.MFA_SETUP_REQUIRED && !!dto.method && !!dto.setupData;
-  }
-}

package/src/dto/set-mfa-exemption.dto.ts

@@ -1,112 +0,0 @@
-/**
- * DTO for setting MFA exemption
- *
- * Used to grant or revoke a user's exemption from multi-factor authentication requirements.
- * Admin-only operation.
- *
- * @example
- * ```typescript
- * const result = await mfaService.setMFAExemption({
- *   userSub: 'user-uuid',
- *   exempt: true,
- *   reason: 'Business partner requires MFA bypass',
- *   grantedBy: 'admin@example.com'
- * });
- * ```
- */
-
-import { IsUUID, IsBoolean, IsOptional, IsString, MaxLength } from 'class-validator';
-import { Transform } from 'class-transformer';
-
-/**
- * DTO for setting MFA exemption
- */
-export class SetMFAExemptionDTO {
-  /**
-   * User's unique identifier (UUID v4)
-   *
-   * Validation:
-   * - Must be a valid UUID v4 format
-   * - Matches DB constraint: char(36) or uuid
-   *
-   * Sanitization:
-   * - Trimmed
-   * - Lowercased for consistency
-   *
-   * @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;
-
-  /**
-   * Whether to grant exemption (true) or revoke exemption (false)
-   */
-  @IsBoolean({ message: 'Exempt must be a boolean' })
-  exempt!: boolean;
-
-  /**
-   * Optional reason for the exemption status change
-   *
-   * Validation:
-   * - Max 500 characters
-   *
-   * Sanitization:
-   * - Trimmed
-   */
-  @IsOptional()
-  @IsString({ message: 'Reason must be a string' })
-  @MaxLength(500, { message: 'Reason must not exceed 500 characters' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim();
-    }
-    return value;
-  })
-  reason?: string | null;
-
-  /**
-   * Optional identifier of the admin performing this action
-   *
-   * Validation:
-   * - Max 255 characters
-   *
-   * Sanitization:
-   * - Trimmed
-   */
-  @IsOptional()
-  @IsString({ message: 'Granted by must be a string' })
-  @MaxLength(255, { message: 'Granted by must not exceed 255 characters' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim();
-    }
-    return value;
-  })
-  grantedBy?: string | null;
-}
-
-/**
- * Response DTO for setting MFA exemption
- */
-export class SetMFAExemptionResponseDTO {
-  /**
-   * Whether user is exempt from MFA requirements
-   */
-  mfaExempt!: boolean;
-
-  /**
-   * Reason for MFA exemption (if exempt)
-   */
-  mfaExemptReason!: string | null;
-
-  /**
-   * Date when MFA exemption was granted (if exempt)
-   */
-  mfaExemptGrantedAt!: Date | null;
-}

package/src/dto/set-must-change-password-response.dto.ts

@@ -1,27 +0,0 @@
-/**
- * Set Must Change Password Response DTO
- *
- * Response DTO for setting must change password flag.
- * No validators needed - this is generated internally by the library.
- *
- * @example
- * ```typescript
- * await authService.setMustChangePassword({
- *   userId: 'user-uuid'
- * });
- * // Returns: { success: true }
- * ```
- */
-
-/**
- * Response DTO for set must change password
- */
-export class SetMustChangePasswordResponseDTO {
-  /**
-   * Success indicator
-   * Always true on successful flag set
-   *
-   * @example true
-   */
-  success!: boolean;
-}

package/src/dto/set-must-change-password.dto.ts

@@ -1,46 +0,0 @@
-/**
- * Set Must Change Password DTO
- *
- * Request DTO for requiring a user to change their password on next login.
- *
- * Security:
- * - User ID validated (UUID)
- * - Prevents unauthorized password change requirements
- *
- * @example
- * ```typescript
- * await authService.setMustChangePassword({
- *   userId: 'user-uuid'
- * });
- * ```
- */
-
-import { IsUUID } from 'class-validator';
-import { Transform } from 'class-transformer';
-
-/**
- * Request DTO for setting must change password flag
- */
-export class SetMustChangePasswordDTO {
-  /**
-   * User's unique identifier (UUID v4)
-   *
-   * Validation:
-   * - Must be a valid UUID v4 format
-   * - Matches DB constraint: char(36) or uuid
-   *
-   * Sanitization:
-   * - Trimmed
-   * - Lowercased for consistency
-   *
-   * @example "a21b654c-2746-4168-acee-c175083a65cd"
-   */
-  @IsUUID('4', { message: 'User ID must be a valid UUID v4 format' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim().toLowerCase();
-    }
-    return value;
-  })
-  userId!: string;
-}

package/src/dto/set-preferred-method.dto.ts

@@ -1,80 +0,0 @@
-/**
- * DTO for setting preferred MFA method
- *
- * Used to set the preferred MFA method for a user.
- * Updates the user's preferred method and device primary flags.
- *
- * @example
- * ```typescript
- * await mfaService.setPreferredMethod({
- *   userSub: 'user-uuid',
- *   methodType: 'totp'
- * });
- * ```
- */
-
-import { IsEnum, IsString, IsUUID, MaxLength } from 'class-validator';
-import { Transform } from 'class-transformer';
-import { MFAMethod } from '../enums/mfa-method.enum';
-
-/**
- * DTO for setting preferred MFA method
- */
-export class SetPreferredMethodDTO {
-  /**
-   * User's unique identifier (UUID v4)
-   *
-   * Validation:
-   * - Must be a valid UUID v4 format
-   * - Matches DB constraint: char(36) or uuid
-   *
-   * Sanitization:
-   * - Trimmed
-   * - Lowercased for consistency
-   *
-   * @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;
-
-  /**
-   * MFA method type to set as preferred
-   *
-   * Validation:
-   * - Must be one of: totp, sms, email, passkey
-   * - Max 50 characters
-   *
-   * Sanitization:
-   * - Trimmed and lowercased
-   *
-   * @example "totp"
-   */
-  @IsString({ message: 'Method type must be a string' })
-  @IsEnum([MFAMethod.TOTP, MFAMethod.SMS, MFAMethod.EMAIL, MFAMethod.PASSKEY], {
-    message: 'Method type must be one of: totp, sms, email, passkey',
-  })
-  @MaxLength(50, { message: 'Method type must not exceed 50 characters' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim().toLowerCase();
-    }
-    return value;
-  })
-  methodType!: string;
-}
-
-/**
- * Response DTO for setting preferred method
- */
-export class SetPreferredMethodResponseDTO {
-  /**
-   * Success message
-   */
-  message!: string;
-}

package/src/dto/setup-mfa.dto.ts

@@ -1,98 +0,0 @@
-/**
- * DTO for setting up MFA device
- *
- * Used to initiate MFA device setup using the appropriate provider.
- *
- * @example
- * ```typescript
- * const setup = await mfaService.setup({
- *   sub: 'user-uuid',
- *   methodName: 'totp',
- *   setupData: {}
- * });
- * ```
- */
-
-import { IsEnum, IsString, IsUUID, IsOptional, IsObject, MaxLength } from 'class-validator';
-import { Transform } from 'class-transformer';
-import { MFAMethod } from '../enums/mfa-method.enum';
-
-/**
- * DTO for setting up MFA device
- */
-export class SetupMFADTO {
-  /**
-   * User's unique identifier (UUID v4)
-   *
-   * Validation:
-   * - Must be a valid UUID v4 format
-   * - Matches DB constraint: char(36) or uuid
-   *
-   * Sanitization:
-   * - Trimmed
-   * - Lowercased for consistency
-   *
-   * @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;
-  })
-  sub!: string;
-
-  /**
-   * MFA method name
-   *
-   * Validation:
-   * - Must be one of: totp, sms, email, passkey
-   * - Max 50 characters
-   *
-   * Sanitization:
-   * - Trimmed and lowercased
-   *
-   * @example "totp"
-   */
-  @IsString({ message: 'Method name must be a string' })
-  @IsEnum([MFAMethod.TOTP, MFAMethod.SMS, MFAMethod.EMAIL, MFAMethod.PASSKEY], {
-    message: 'Method name must be one of: totp, sms, email, passkey',
-  })
-  @MaxLength(50, { message: 'Method name must not exceed 50 characters' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim().toLowerCase();
-    }
-    return value;
-  })
-  methodName!: string;
-
-  /**
-   * Optional provider-specific setup data
-   *
-   * Validation:
-   * - Must be an object if provided
-   * - Structure validated by MFA provider services
-   *
-   * @example { phoneNumber: '+1234567890' } for SMS
-   */
-  @IsOptional()
-  @IsObject({ message: 'Setup data must be an object' })
-  setupData?: Record<string, unknown>;
-}
-
-/**
- * Response DTO for MFA setup
- */
-export class SetupMFAResponseDTO {
-  /**
-   * Provider-specific setup response
-   *
-   * Structure varies by method:
-   * - TOTP: { secret, qrCode, manualEntryKey }
-   * - SMS: { maskedPhone }
-   * - Passkey: WebAuthn registration options
-   */
-  setupData!: Record<string, unknown>;
-}