merge(develop): user-management, token-management, auth improvements

src/main/java/com/edgareldy/springboottutorial/config/SecurityConfig.java

@@ -73,7 +73,8 @@ public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Excepti
                 .authorizeHttpRequests(authorize -> authorize
                         .requestMatchers(HttpMethod.POST,
                                 "/api/v1/auth/register", "/api/v1/auth/login",
-                                "/api/v1/auth/forgot-password", "/api/v1/auth/reset-password")
+                                "/api/v1/auth/forgot-password", "/api/v1/auth/reset-password",
+                                "/api/v1/auth/refresh-token")
                         .permitAll()
                         .requestMatchers(HttpMethod.GET, "/api/v1/auth/activate")
                         .permitAll()

src/main/java/com/edgareldy/springboottutorial/controller/AuthController.java

@@ -7,9 +7,11 @@
 import com.edgareldy.springboottutorial.dto.auth.ResetPasswordRequest;
 import com.edgareldy.springboottutorial.dto.auth.UserResponse;
 import com.edgareldy.springboottutorial.dto.common.ApiResponse;
+import com.edgareldy.springboottutorial.security.JwtService;
 import com.edgareldy.springboottutorial.service.AuthService;
 import com.edgareldy.springboottutorial.service.UserService;
 import jakarta.validation.Valid;
+import java.util.Map;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
@@ -43,6 +45,16 @@ public class AuthController {
 
     private final AuthService authService;
     private final UserService userService;
+    private final JwtService jwtService;
+
+    @PostMapping("/refresh-token")
+    public ResponseEntity<ApiResponse<AuthResponse>> refreshToken(
+            @RequestHeader("Authorization") String authHeader) {
+        String rawToken = authHeader.startsWith(BEARER_PREFIX)
+                ? authHeader.substring(BEARER_PREFIX.length())
+                : authHeader;
+        return ResponseEntity.ok(ApiResponse.success(authService.refresh(rawToken), "Token refreshed successfully"));
+    }
 
     @PostMapping("/register")
     public ResponseEntity<ApiResponse<UserResponse>> register(@Valid @RequestBody RegisterRequest request) {
@@ -68,6 +80,16 @@ public ResponseEntity<ApiResponse<UserResponse>> me(@AuthenticationPrincipal Use
         return ResponseEntity.ok(ApiResponse.success(authService.me(userDetails.getUsername()), "Profile retrieved successfully"));
     }
 
+    @GetMapping("/token-info")
+    public ResponseEntity<ApiResponse<Map<String, Object>>> tokenInfo(
+            @RequestHeader("Authorization") String authHeader) {
+        String token = authHeader.startsWith(BEARER_PREFIX)
+                ? authHeader.substring(BEARER_PREFIX.length())
+                : authHeader;
+        Map<String, Object> claims = jwtService.extractAllClaims(token);
+        return ResponseEntity.ok(ApiResponse.success(claims, "Token claims retrieved successfully"));
+    }
+
     @GetMapping("/activate")
     public ResponseEntity<ApiResponse<UserResponse>> activate(@RequestParam String token) {
         return ResponseEntity.ok(ApiResponse.success(userService.activate(token), "Account activated successfully"));
@@ -80,8 +102,10 @@ public ResponseEntity<ApiResponse<Void>> forgotPassword(@Valid @RequestBody Forg
     }
 
     @PostMapping("/reset-password")
-    public ResponseEntity<ApiResponse<Void>> resetPassword(@Valid @RequestBody ResetPasswordRequest request) {
-        userService.resetPassword(request.token(), request.newPassword());
+    public ResponseEntity<ApiResponse<Void>> resetPassword(
+            @RequestParam String token,
+            @Valid @RequestBody ResetPasswordRequest request) {
+        userService.resetPassword(token, request.newPassword());
         return ResponseEntity.ok(ApiResponse.success(null, "Password reset successfully"));
     }
 }

src/main/java/com/edgareldy/springboottutorial/controller/UserController.java

@@ -65,6 +65,14 @@ public ResponseEntity<ApiResponse<UserResponse>> assignRoles(
         return ResponseEntity.ok(ApiResponse.success(userService.assignRoles(id, request), "Roles assigned successfully"));
     }
 
+    @DeleteMapping("/{id}/roles/{roleId}")
+    public ResponseEntity<ApiResponse<UserResponse>> removeRole(
+            @PathVariable Long id,
+            @PathVariable Long roleId) {
+        return ResponseEntity.ok(ApiResponse.success(
+                userService.removeRoleFromUser(id, roleId), "Role removed successfully"));
+    }
+
     @DeleteMapping("/{id}")
     public ResponseEntity<ApiResponse<Void>> delete(@PathVariable Long id) {
         userService.delete(id);

src/main/java/com/edgareldy/springboottutorial/dto/auth/AuthResponse.java

@@ -3,24 +3,32 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 /**
- * Payload returned by {@code POST /api/v1/auth/login}: the JWT to send back
- * as a {@code Bearer} token on subsequent requests, plus enough profile
- * information for the client to avoid an extra call to {@code /auth/me}.
- * The JSON contract is snake_case, decoupled from the Java field's own
- * camelCase name via an explicit {@link JsonProperty} annotation.
+ * Payload returned by {@code POST /api/v1/auth/login} and
+ * {@code POST /api/v1/auth/refresh-token}. Fields follow the OAuth 2.0
+ * naming convention: {@code access_token}, {@code token_type},
+ * {@code refresh_token}, and {@code expires_in} (access token lifetime in
+ * seconds). The client uses {@code expires_in} to schedule a proactive
+ * refresh before the access token expires, avoiding a failed request.
+ * {@code username} is omitted since it is already the {@code sub} claim
+ * inside the JWT itself.
  * <p>
  * Created edgar.muhamyangabo on 7/8/26
  * Author : edgar.muhamyangabo
  * Date : 7/8/26
  * Project : spring-boot-tutorial
  */
 public record AuthResponse(
-        String token,
+        @JsonProperty("access_token")
+        String accessToken,
 
         @JsonProperty("token_type")
         String tokenType,
 
-        String username
+        @JsonProperty("refresh_token")
+        String refreshToken,
+
+        @JsonProperty("expires_in")
+        long expiresIn
 ) {
 
     // Overrides the compiler-generated toString(): LoggingAspect logs every
@@ -29,6 +37,7 @@ public record AuthResponse(
     // a live bearer credential, in the application logs.
     @Override
     public String toString() {
-        return "AuthResponse[token=***, tokenType=%s, username=%s]".formatted(tokenType, username);
+        return "AuthResponse[accessToken=***, tokenType=%s, refreshToken=***, expiresIn=%d]"
+                .formatted(tokenType, expiresIn);
     }
 }

src/main/java/com/edgareldy/springboottutorial/dto/auth/ResetPasswordRequest.java

@@ -1,25 +1,33 @@
 package com.edgareldy.springboottutorial.dto.auth;
 
+import com.edgareldy.springboottutorial.validation.password.PasswordsMatch;
+import com.edgareldy.springboottutorial.validation.password.ValidPassword;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import jakarta.validation.constraints.NotBlank;
-import jakarta.validation.constraints.Size;
 
 /**
- * Request body for the POST /auth/reset-password endpoint. Carries the
- * one-time reset token (delivered by email) and the new plain-text password
- * to set after the token is validated and consumed.
+ * Request body for the POST /auth/reset-password endpoint. Carries the new
+ * password and its confirmation; the one-time reset token is passed as a
+ * query parameter so the frontend can forward it directly from the email
+ * link without re-embedding it in a JSON payload.
  * <p>
  * Created edgar.muhamyangabo on 10/30/26
  * Author : edgar.muhamyangabo
  * Date : 10/30/26
  * Project : spring-boot-tutorial
  */
+@PasswordsMatch(passwordField = "newPassword", confirmPasswordField = "confirmPassword",
+        message = "Passwords must match")
 public record ResetPasswordRequest(
-        @NotBlank(message = "Token must not be blank")
-        @JsonProperty("token") String token,
-
         @NotBlank(message = "New password must not be blank")
-        @Size(min = 8, message = "New password must be at least 8 characters")
-        @JsonProperty("new_password") String newPassword
+        @ValidPassword
+        @JsonProperty("new_password") String newPassword,
+
+        @NotBlank(message = "Password confirmation must not be blank")
+        @JsonProperty("confirm_password") String confirmPassword
 ) {
+    @Override
+    public String toString() {
+        return "ResetPasswordRequest[newPassword=***, confirmPassword=***]";
+    }
 }

src/main/java/com/edgareldy/springboottutorial/entity/token/ActivationToken.java

@@ -1,22 +1,15 @@
 package com.edgareldy.springboottutorial.entity.token;
 
-import com.edgareldy.springboottutorial.entity.user.AppUser;
 import jakarta.persistence.Column;
 import jakarta.persistence.Entity;
-import jakarta.persistence.FetchType;
-import jakarta.persistence.GeneratedValue;
-import jakarta.persistence.GenerationType;
-import jakarta.persistence.Id;
-import jakarta.persistence.JoinColumn;
-import jakarta.persistence.ManyToOne;
 import jakarta.persistence.Table;
 import java.time.Instant;
 import lombok.AllArgsConstructor;
-import lombok.Builder;
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
 import lombok.Setter;
+import lombok.experimental.SuperBuilder;
 
 /**
  * JPA entity mapping the {@code activation_tokens} table. Generated by
@@ -34,23 +27,9 @@
 @Setter
 @NoArgsConstructor
 @AllArgsConstructor
-@Builder
-@EqualsAndHashCode(of = "id")
-public class ActivationToken {
-
-    @Id
-    @GeneratedValue(strategy = GenerationType.IDENTITY)
-    private Long id;
-
-    @ManyToOne(fetch = FetchType.LAZY)
-    @JoinColumn(name = "user_id", nullable = false)
-    private AppUser user;
-
-    @Column(name = "token", nullable = false)
-    private String token;
-
-    @Column(name = "created_at", nullable = false)
-    private Instant createdAt;
+@SuperBuilder
+@EqualsAndHashCode(callSuper = true)
+public class ActivationToken extends AuditableToken {
 
     @Column(name = "expires_at")
     private Instant expiresAt;

src/main/java/com/edgareldy/springboottutorial/entity/token/AuditableToken.java

@@ -0,0 +1,51 @@
+package com.edgareldy.springboottutorial.entity.token;
+
+import com.edgareldy.springboottutorial.entity.user.AppUser;
+import jakarta.persistence.Column;
+import jakarta.persistence.FetchType;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.MappedSuperclass;
+import java.time.Instant;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+import lombok.experimental.SuperBuilder;
+
+/**
+ * Common mapped superclass for all token entities (activation, password-reset,
+ * blacklisted JWT, refresh). Centralises the primary key, the owning user
+ * relationship, the raw token string, and the creation timestamp so each
+ * concrete entity only declares the fields that make it specific.
+ * <p>
+ * Created edgar.muhamyangabo on 11/9/26
+ * Author : edgar.muhamyangabo
+ * Date : 11/9/26
+ * Project : spring-boot-tutorial
+ */
+@MappedSuperclass
+@Getter
+@Setter
+@NoArgsConstructor
+@SuperBuilder
+@EqualsAndHashCode(of = "id")
+public abstract class AuditableToken {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "user_id", nullable = false)
+    private AppUser user;
+
+    @Column(name = "token", nullable = false, length = 768)
+    private String token;
+
+    @Column(name = "created_at", nullable = false)
+    private Instant createdAt;
+}

src/main/java/com/edgareldy/springboottutorial/entity/token/BlacklistedToken.java

@@ -1,22 +1,15 @@
 package com.edgareldy.springboottutorial.entity.token;
 
-import com.edgareldy.springboottutorial.entity.user.AppUser;
 import jakarta.persistence.Column;
 import jakarta.persistence.Entity;
-import jakarta.persistence.FetchType;
-import jakarta.persistence.GeneratedValue;
-import jakarta.persistence.GenerationType;
-import jakarta.persistence.Id;
-import jakarta.persistence.JoinColumn;
-import jakarta.persistence.ManyToOne;
 import jakarta.persistence.Table;
 import java.time.Instant;
 import lombok.AllArgsConstructor;
-import lombok.Builder;
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
 import lombok.Setter;
+import lombok.experimental.SuperBuilder;
 
 /**
  * JPA entity mapping the {@code blacklisted_tokens} table. Recorded by
@@ -35,30 +28,16 @@
 @Setter
 @NoArgsConstructor
 @AllArgsConstructor
-@Builder
-@EqualsAndHashCode(of = "id")
-public class BlacklistedToken {
-
-    @Id
-    @GeneratedValue(strategy = GenerationType.IDENTITY)
-    private Long id;
-
-    @ManyToOne(fetch = FetchType.LAZY)
-    @JoinColumn(name = "user_id", nullable = false)
-    private AppUser user;
-
-    @Column(name = "token", nullable = false, length = 768)
-    private String token;
+@SuperBuilder
+@EqualsAndHashCode(callSuper = true)
+public class BlacklistedToken extends AuditableToken {
 
     @Column(name = "jti", nullable = false, unique = true)
     private String jti;
 
     @Column(name = "blacklisted_at")
     private Instant blacklistedAt;
 
-    @Column(name = "created_at", nullable = false)
-    private Instant createdAt;
-
     @Column(name = "expires_at")
     private Instant expiresAt;
 }

src/main/java/com/edgareldy/springboottutorial/entity/token/PasswordResetToken.java

@@ -1,22 +1,15 @@
 package com.edgareldy.springboottutorial.entity.token;
 
-import com.edgareldy.springboottutorial.entity.user.AppUser;
 import jakarta.persistence.Column;
 import jakarta.persistence.Entity;
-import jakarta.persistence.FetchType;
-import jakarta.persistence.GeneratedValue;
-import jakarta.persistence.GenerationType;
-import jakarta.persistence.Id;
-import jakarta.persistence.JoinColumn;
-import jakarta.persistence.ManyToOne;
 import jakarta.persistence.Table;
 import java.time.Instant;
 import lombok.AllArgsConstructor;
-import lombok.Builder;
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
 import lombok.Setter;
+import lombok.experimental.SuperBuilder;
 
 /**
  * JPA entity mapping the {@code password_reset_tokens} table. Generated by
@@ -35,20 +28,9 @@
 @Setter
 @NoArgsConstructor
 @AllArgsConstructor
-@Builder
-@EqualsAndHashCode(of = "id")
-public class PasswordResetToken {
-
-    @Id
-    @GeneratedValue(strategy = GenerationType.IDENTITY)
-    private Long id;
-
-    @ManyToOne(fetch = FetchType.LAZY)
-    @JoinColumn(name = "user_id", nullable = false)
-    private AppUser user;
-
-    @Column(name = "token", nullable = false)
-    private String token;
+@SuperBuilder
+@EqualsAndHashCode(callSuper = true)
+public class PasswordResetToken extends AuditableToken {
 
     @Column(name = "type", nullable = false)
     private String type;