Email Features (Verification & Password Reset)

Relevant source files

The following files were used as context for generating this wiki page:

• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/mail/AuthenticEMailHandler.java
• API/src/main/java/xyz/xreatlabs/nexauth/api/mail/EmailHandler.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/command/commands/mail/ResetPasswordViaEMailCommand.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/command/commands/mail/VerifyEMailCommand.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/command/commands/mail/ConfirmPasswordReset.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/MessageKeys.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/command/commands/staff/NexAuthCommand.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/database/AuthenticUser.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java

NexAuth includes an optional, but powerful, email system for account management. This feature allows users to associate an email address with their in-game account, which can then be used to reset a forgotten password. This enhances account security and provides a self-service recovery option for players.

The entire email functionality is conditional and will only be enabled if mail.enabled is set to true in the configuration. When disabled, the EmailHandler will not be initialized, and all related commands will be unavailable.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:413-417, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:251-252

Architecture and Core Components

The email system is designed around a core EmailHandler interface and its implementation, which handles the specifics of SMTP communication.

EmailHandler API

The EmailHandler interface defines the contract for all email-sending operations within NexAuth. This abstraction allows for potential future extensions or custom implementations.

Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/mail/EmailHandler.java

The interface specifies four primary methods:

• sendEmail(String email, String subject, String content): A generic method to send any email.
• sendTestMail(String email): Sends a pre-defined test email to verify SMTP configuration.
• sendPasswordResetMail(String email, String token, String username, String ip): Sends an email containing a password reset token.
• sendVerificationMail(String email, String token, String username): Sends an email containing an email verification token.

AuthenticEMailHandler Implementation

The default implementation, AuthenticEMailHandler, uses the org.apache.commons.mail.HtmlEmail library to construct and send HTML emails. It retrieves SMTP server details from the NexAuth configuration and establishes a connection.

The handler dynamically configures the connection security based on the specified port:

• Port 465: Assumes SSL connection (setSslSmtpPort).
• Port 587: Assumes STARTTLS connection (setStartTLSEnabled).
• Other Ports: Defaults to a secure connection with server identity checks.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/mail/AuthenticEMailHandler.java:38-52

The following diagram illustrates the class structure for the email handling components.

Configuration

To use the email features, you must first enable them and configure your SMTP server details in config.yml.

SMTP Settings

These settings are located under the mail section of the configuration file.

Configuration Key	Type	Default Value	Description
mail.enabled	Boolean	false	Enables or disables the entire email feature set.
mail.host	String	"smtp.gmail.com"	The host of the SMTP server.
mail.port	Integer	587	The port of the SMTP server.
mail.username	String	"username"	The username for SMTP authentication.
mail.password	String	"password"	The password for SMTP authentication.
mail.sender	String	"NexAuth Network"	The sender name displayed in the email.
mail.email	String	"email@something.com"	The "From" email address.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:413-455

Email Templates

The subject and content of the verification and password reset emails are fully customizable through messages.conf. They support HTML and placeholders.

Message Key	Description	Default Content Snippet
email-verification-subject	Subject for the email verification message.	Verify your email on %server%
email-verification-content	HTML content for the verification email.	...run the following command in-game: /verifyemail %code%
email-password-reset-subject	Subject for the password reset message.	Reset your password on %server%
email-password-reset-content	HTML content for the password reset email.	...run the following command in-game: /confirmpasswordreset %code%

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/MessageKeys.java:708-751

User Workflows

Email Verification Flow

This flow allows a player to link a recovery email to their account.

1. Initiation: The player executes /setemail <address> <password>. The system verifies their current password.
2. Token Generation: A unique, alphanumeric verification token is generated.
3. Email Dispatch: The AuthenticEMailHandler sends a verification email to the specified address, containing the token.
4. Caching: The token and email address are temporarily stored in the emailConfirmCache against the player's UUID.
5. Confirmation: The player runs /verifyemail <code> in-game with the token from the email.
6. Validation: The system checks the provided token against the one in the cache.
7. Persistence: If the token is valid, the email address is permanently saved to the player's AuthenticUser profile in the database.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/command/commands/mail/VerifyEMailCommand.java:29-45, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/database/AuthenticUser.java:100-105

The sequence diagram below visualizes the email verification process.

Password Reset Flow

Once an email is verified, the player can use it to reset their password.

1. Initiation: The player (who is not logged in) executes /resetpassword.
2. Email Check: The system confirms the player has a verified email address set.
3. Token Generation: A unique, 16-character alphanumeric token is generated.
4. Email Dispatch: A password reset email is sent to the player's registered address, including the token.
5. Caching: The reset token is stored in the passwordResetCache.
6. Confirmation: The player runs /confirmpasswordreset <code> <newPassword> <newPasswordRepeat>.
7. Validation: The system validates the token and confirms that the new passwords match.
8. Update: If valid, the player's password hash is updated in the database.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/command/commands/mail/ResetPasswordViaEMailCommand.java:36-57, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/command/commands/mail/ConfirmPasswordReset.java:25-45, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/util/GeneralUtil.java:152-161

The sequence diagram below visualizes the password reset process.

Commands Summary

The following commands are associated with the email features.

Command	Permission	Description
/setemail <address> <password>	none	Starts the email verification process for the player's account.
/verifyemail <code>	none	Confirms the email verification using the token sent to the email.
/resetpassword	none	Starts the password reset process for a player with a verified email.
/confirmpasswordreset <code> <new> <new>	none	Completes the password reset process with a new password.
/nexauth email test <address>	nexauth.email.test	(Admin) Sends a test email to verify SMTP settings.
/nexauth user emailoff <name>	librepremium.user.emailoff	(Admin) Removes the recovery email from a user's account.
/nexauth user setemail <name> <email>	librepremium.user.setemail	(Admin) Forcibly sets a recovery email for a user, bypassing verification.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/command/CommandProvider.java:101-104, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/command/commands/staff/NexAuthCommand.java:70-79, 323-352