Java/src/main/java/com/company/auth/dto/request/LoginRequest.java

/**
 * Login Request DTO
 * 
 * Data transfer object for user login requests.
 * Contains user credentials and supports encrypted payloads
 * for enhanced security during authentication.
 * 
 * @author David Valera Melendez <david@valera-melendez.de>
 * @since February  2025
 */
package com.company.auth.dto.request;

import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;

/**
 * Request DTO for user authentication
 * 
 * Supports both plain text and encrypted credential submission.
 * The encrypted mode provides additional security for sensitive
 * credential transmission from frontend applications.
 */
@Schema(description = "User login request with email and password")
public class LoginRequest {

    /**
     * User's email address
     * 
     * Primary identifier for user authentication.
     * Must be a valid email format and not blank.
     */
    @Schema(description = "User email address", example = "john.doe@company.com")
    @NotBlank(message = "Email is required")
    @Email(message = "Email must be valid")
    @Size(max = 255, message = "Email must not exceed 255 characters")
    private String email;

    /**
     * User's password (may be encrypted)
     * 
     * Password for authentication. Can be provided as plain text
     * or encrypted using frontend encryption for enhanced security.
     */
    @Schema(description = "User password (plain text or encrypted)", example = "SecurePassword123!")
    @NotBlank(message = "Password is required")
    @Size(min = 8, max = 1000, message = "Password must be between 8 and 1000 characters")
    private String password;

    /**
     * Device fingerprint data for risk assessment
     * 
     * Optional browser fingerprint information used for
     * device trust verification and risk-based authentication.
     */
    @Schema(description = "Browser fingerprint data for device verification")
    private DeviceFingerprintRequest fingerprint;

    /**
     * Flag indicating if credentials are encrypted
     * 
     * When true, the password field contains encrypted data that
     * needs to be decrypted before authentication.
     */
    @Schema(description = "Whether password is encrypted", example = "false")
    private Boolean encrypted = false;

    /**
     * Remember device flag
     * 
     * When true, the device will be registered as trusted after
     * successful authentication (may require 2FA for new devices).
     */
    @Schema(description = "Whether to remember this device", example = "true")
    private Boolean rememberDevice = false;

    /**
     * Default constructor
     */
    public LoginRequest() {}

    /**
     * Constructor with basic credentials
     * 
     * @param email User email
     * @param password User password
     */
    public LoginRequest(String email, String password) {
        this.email = email;
        this.password = password;
    }

    /**
     * Constructor with all fields
     * 
     * @param email User email
     * @param password User password
     * @param fingerprint Device fingerprint
     * @param encrypted Whether password is encrypted
     * @param rememberDevice Whether to remember device
     */
    public LoginRequest(String email, String password, DeviceFingerprintRequest fingerprint,
                       Boolean encrypted, Boolean rememberDevice) {
        this.email = email;
        this.password = password;
        this.fingerprint = fingerprint;
        this.encrypted = encrypted;
        this.rememberDevice = rememberDevice;
    }

    // Getters and Setters

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public DeviceFingerprintRequest getFingerprint() {
        return fingerprint;
    }

    public void setFingerprint(DeviceFingerprintRequest fingerprint) {
        this.fingerprint = fingerprint;
    }

    public Boolean getEncrypted() {
        return encrypted;
    }

    public void setEncrypted(Boolean encrypted) {
        this.encrypted = encrypted;
    }

    public Boolean getRememberDevice() {
        return rememberDevice;
    }

    public void setRememberDevice(Boolean rememberDevice) {
        this.rememberDevice = rememberDevice;
    }

    /**
     * Clears sensitive data from memory
     */
    public void clearSensitiveData() {
        this.password = null;
        if (this.fingerprint != null) {
            // Clear any sensitive fingerprint data if needed
        }
    }

    @Override
    public String toString() {
        return "LoginRequest{" +
                "email='" + email + '\'' +
                ", encrypted=" + encrypted +
                ", rememberDevice=" + rememberDevice +
                ", hasFingerprint=" + (fingerprint != null) +
                '}';
    }
}