@nauth-toolkit/core 0.1.0

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

@@ -0,0 +1,272 @@
+/**
+ * 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

@@ -0,0 +1,112 @@
+/**
+ * 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

@@ -0,0 +1,27 @@
+/**
+ * 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

@@ -0,0 +1,46 @@
+/**
+ * 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

@@ -0,0 +1,80 @@
+/**
+ * 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

@@ -0,0 +1,98 @@
+/**
+ * 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>;
+}