Add backend email verification (#226)

* feat(auth): add InvalidActivationTokenException handling

Introduce `InvalidActivationTokenException` to provide a custom exception for handling invalid or expired activation tokens. Extend the `ErrorCode` enum with `INVALID_ACTIVATION_TOKEN` to support this exception with a unique error code.

* feat(auth): add method to find activation token by value

Introduce `findByToken` method in `UserActivationTokenRepository` to enable retrieval of activation tokens by their string value. This enhances query capabilities for token-based operations.

* feat(auth): add email verification via activation token

Introduce `verifyEmail` method in `UserActivationServiceImpl` to handle email verification using activation tokens. Validate tokens for existence and expiration, update user status to `ACTIVATED`, and remove used tokens. Add logging for successful activations and handle edge cases such as already activated accounts.

* feat(auth): add email verification endpoint in controller

Introduce `verifyEmail` GET endpoint in `UserActivationController` to handle user account activation via an email-provided activation token. Annotate with OpenAPI documentation, validate input tokens, and handle exceptions for invalid or already activated accounts.

* feat(security): allow public access to user activation verification endpoint

Add `/api/v1/user-activation/verify` to permitted paths in `SecurityConfig`. This enables unauthenticated users to verify their accounts via activation tokens.

* style(auth): remove unnecessary blank line in UserActivationServiceImpl

Remove redundant blank line in `activateUser` method to improve code readability and adhere to consistent formatting.

Author: MarynaHuz

src/main/java/com/itasocialacademy/oitassist/auth/controller/UserActivationController.java

@@ -1,23 +1,28 @@
 package com.itasocialacademy.oitassist.auth.controller;
 
 import com.itasocialacademy.oitassist.auth.dto.request.ResendVerificationMailRequest;
+import com.itasocialacademy.oitassist.auth.exceptions.InvalidActivationTokenException;
 import com.itasocialacademy.oitassist.user.exceptions.ActivationTokenSendingTimeoutException;
 import com.itasocialacademy.oitassist.auth.service.interfaces.UserActivationService;
 import com.itasocialacademy.oitassist.core.web.ErrorResponse;
 import com.itasocialacademy.oitassist.auth.exceptions.UserAlreadyActivatedException;
 import com.itasocialacademy.oitassist.user.exceptions.UserNotFoundException;
 import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.media.Content;
 import io.swagger.v3.oas.annotations.media.Schema;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
+import jakarta.validation.constraints.NotBlank;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.HttpStatus;
+import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.ResponseStatus;
 import org.springframework.web.bind.annotation.RestController;
 
@@ -33,6 +38,41 @@
 public class UserActivationController {
     private final UserActivationService userActivationService;
 
+    /**
+     * Activates a user account by activation token.
+     *
+     * @param token activation token sent by email
+     * @throws InvalidActivationTokenException if the token is invalid or expired
+     * @throws UserAlreadyActivatedException   if the account is already activated
+     */
+    @GetMapping("/verify")
+    @ResponseStatus(HttpStatus.OK)
+    @Operation(
+        summary = "Verify user email",
+        description = "Activates a user account using the activation token from the email link.")
+    @ApiResponses(value = {
+        @ApiResponse(
+            responseCode = "200",
+            description = "User account successfully activated"),
+        @ApiResponse(
+            responseCode = "400",
+            description = "Activation token is invalid or expired",
+            content = @Content(
+                mediaType = "application/json",
+                schema = @Schema(implementation = ErrorResponse.class))),
+        @ApiResponse(
+            responseCode = "409",
+            description = "User account is already activated",
+            content = @Content(
+                mediaType = "application/json",
+                schema = @Schema(implementation = ErrorResponse.class)))
+    })
+    public void verifyEmail(
+        @Parameter(description = "Activation token from email link",
+            required = true) @RequestParam @NotBlank String token) {
+        userActivationService.verifyEmail(token);
+    }
+
     /**
      * Resends an activation email to a user whose account is not yet activated.
      *

src/main/java/com/itasocialacademy/oitassist/auth/dao/repository/UserActivationTokenRepository.java

@@ -1,9 +1,11 @@
 package com.itasocialacademy.oitassist.auth.dao.repository;
 
 import com.itasocialacademy.oitassist.user.dao.model.UserActivationToken;
+import java.util.Optional;
 import org.springframework.data.jpa.repository.JpaRepository;
 import org.springframework.stereotype.Repository;
 
 @Repository
 public interface UserActivationTokenRepository extends JpaRepository<UserActivationToken, Long> {
+    Optional<UserActivationToken> findByToken(String token);
 }

src/main/java/com/itasocialacademy/oitassist/auth/exceptions/InvalidActivationTokenException.java

@@ -0,0 +1,10 @@
+package com.itasocialacademy.oitassist.auth.exceptions;
+
+import com.itasocialacademy.oitassist.core.enums.ErrorCode;
+import com.itasocialacademy.oitassist.core.exceptions.BusinessException;
+
+public class InvalidActivationTokenException extends BusinessException {
+    public InvalidActivationTokenException() {
+        super("Activation token is invalid or expired", ErrorCode.INVALID_ACTIVATION_TOKEN);
+    }
+}

src/main/java/com/itasocialacademy/oitassist/auth/service/UserActivationServiceImpl.java

@@ -1,6 +1,8 @@
 package com.itasocialacademy.oitassist.auth.service;
 
+import com.itasocialacademy.oitassist.auth.dao.repository.UserActivationTokenRepository;
 import com.itasocialacademy.oitassist.auth.dto.event.ActivationAccountEvent;
+import com.itasocialacademy.oitassist.auth.exceptions.InvalidActivationTokenException;
 import com.itasocialacademy.oitassist.auth.exceptions.UserAlreadyActivatedException;
 import com.itasocialacademy.oitassist.auth.service.interfaces.UserActivationService;
 import com.itasocialacademy.oitassist.user.dao.enums.UserStatus;
@@ -9,17 +11,51 @@
 import com.itasocialacademy.oitassist.user.dao.repository.UserRepository;
 import com.itasocialacademy.oitassist.user.exceptions.UserNotFoundException;
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.context.ApplicationEventPublisher;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 import java.time.Duration;
 
+@Slf4j
 @Service
 @RequiredArgsConstructor
 public class UserActivationServiceImpl implements UserActivationService {
     private final UserRepository userRepository;
+    private final UserActivationTokenRepository tokenRepository;
     private final ApplicationEventPublisher eventPublisher;
 
+    /**
+     * {@inheritDoc}
+     *
+     * <p>
+     * Looks up the token, validates it is not expired, sets the user status to
+     * {@code ACTIVATED}, and deletes the token so it cannot be reused.
+     * </p>
+     */
+    @Override
+    @Transactional
+    public void verifyEmail(String token) {
+        UserActivationToken activationToken = tokenRepository.findByToken(token)
+            .orElseThrow(InvalidActivationTokenException::new);
+
+        if (activationToken.isExpired()) {
+            throw new InvalidActivationTokenException();
+        }
+
+        User user = activationToken.getUser();
+
+        if (user.getUserStatus() == UserStatus.ACTIVATED) {
+            throw new UserAlreadyActivatedException();
+        }
+
+        user.setUserStatus(UserStatus.ACTIVATED);
+        user.setUserActivationToken(null);
+        userRepository.save(user);
+
+        log.info("User account activated for email={}", user.getEmail());
+    }
+
     /**
      * {@inheritDoc}
      *

src/main/java/com/itasocialacademy/oitassist/auth/service/interfaces/UserActivationService.java

@@ -1,5 +1,6 @@
 package com.itasocialacademy.oitassist.auth.service.interfaces;
 
+import com.itasocialacademy.oitassist.auth.exceptions.InvalidActivationTokenException;
 import com.itasocialacademy.oitassist.auth.exceptions.UserAlreadyActivatedException;
 import com.itasocialacademy.oitassist.user.exceptions.ActivationTokenSendingTimeoutException;
 import com.itasocialacademy.oitassist.user.exceptions.UserNotFoundException;
@@ -41,4 +42,16 @@ public interface UserActivationService {
      *                                       activated
      */
     void initializeActivation(String email, String firstName);
+
+    /**
+     * Verifies a user's email address using the activation token from the email
+     * link. If the token is valid and not expired, the user's status is updated to
+     * {@code ACTIVATED} and the token is removed.
+     *
+     * @param token the activation token sent to the user's email
+     * @throws InvalidActivationTokenException if the token does not exist or has
+     *                                         expired
+     * @throws UserAlreadyActivatedException   if the account is already activated
+     */
+    void verifyEmail(String token);
 }

src/main/java/com/itasocialacademy/oitassist/core/enums/ErrorCode.java

@@ -26,6 +26,7 @@ public enum ErrorCode {
     INVALID_FILE_PATH(ErrorCategory.TECHNICAL),
     COMMON_VALIDATION_FAILED(ErrorCategory.VALIDATION),
     FILE_VALIDATION_FAILED(ErrorCategory.VALIDATION),
+    INVALID_ACTIVATION_TOKEN(ErrorCategory.VALIDATION),
 
     TOKEN_EXPIRE(ErrorCategory.AUTHENTICATION),
     UNSUPPORTED_TOKEN(ErrorCategory.AUTHENTICATION),

src/main/java/com/itasocialacademy/oitassist/security/config/SecurityConfig.java

@@ -66,7 +66,8 @@ public SecurityFilterChain configure(HttpSecurity http) {
                     "/api/v1/security/refresh")
                 .permitAll()
                 .requestMatchers(HttpMethod.GET,
-                    "/api/v1/news/**")
+                    "/api/v1/news/**",
+                    "/api/v1/user-activation/verify")
                 .permitAll()
                 .requestMatchers(
                     "/actuator/health/**",