chore: tidy swagger comments;

feat: password reset models;
feat: verification code validator

backend/internal/controllers/auth.go

@@ -54,8 +54,9 @@ func NewAuthController(_log *zap.Logger, as services.AuthService) AuthController
 // @Tags Auth
 // @Accept json
 // @Produce json
-// @Param request body models.LoginRequest true "desc"
-// @Success 200 {object} models.LoginResponse "desc"
+// @Param request body models.LoginRequest true " "
+// @Success 200 {object} models.LoginResponse " "
+// @Failure 403 "Invalid login credentials" 
 // @Router /auth/login [post]
 func (a *authControllerImpl) Login(c *gin.Context) {
 	request, ok := utils.GetRequest[models.LoginRequest](c)
@@ -83,25 +84,35 @@ func (a *authControllerImpl) Login(c *gin.Context) {
 // @Tags Auth
 // @Accept json
 // @Produce json
+// @Param request body models.PasswordResetBeginRequest true " "
 // @Router /auth/passwordResetBegin [post]
+// @Success 200 "Reset code sent to the email if it is attached to an account"
+// @Failure 429 "Too many recent requests for this email"
 func (a *authControllerImpl) PasswordResetBegin(c *gin.Context) {
 	c.Status(http.StatusNotImplemented)
 }
 
-// @Summary Complete password reset with email code and provide 2FA code or backup code if needed
+// @Summary Complete password reset via email code
 // @Tags Auth
 // @Accept json
 // @Produce json
+// @Param request body models.PasswordResetCompleteRequest true " "
 // @Router /auth/passwordResetComplete [post]
+// @Success 200 {object} models.PasswordResetCompleteResponse " "
+// @Success 403 "Wrong verification code or username"
 func (a *authControllerImpl) PasswordResetComplete(c *gin.Context) {
 	c.Status(http.StatusNotImplemented)
 }
 
+
 // @Summary Receive new tokens via refresh token
 // @Tags Auth
 // @Accept json
 // @Produce json
+// @Param request body models.RefreshRequest true " "
 // @Router /auth/refresh [post]
+// @Success 200 {object} models.RefreshResponse " "
+// @Failure 401 "Invalid refresh token"
 func (a *authControllerImpl) Refresh(c *gin.Context) {
 	c.Status(http.StatusNotImplemented)
 }
@@ -110,9 +121,10 @@ func (a *authControllerImpl) Refresh(c *gin.Context) {
 // @Tags Auth
 // @Accept json
 // @Produce json
-// @Param request body models.RegistrationBeginRequest true "desc"
+// @Param request body models.RegistrationBeginRequest true " "
 // @Success 200 "Account is created and awaiting verification"
-// @Success 409 "Username or email is already taken"
+// @Failure 409 "Username or email is already taken"
+// @Failure 429 "Too many recent registration attempts for this email"
 // @Router /auth/registrationBegin [post]
 func (a *authControllerImpl) RegistrationBegin(c *gin.Context) {
 
@@ -141,8 +153,9 @@ func (a *authControllerImpl) RegistrationBegin(c *gin.Context) {
 // @Tags Auth
 // @Accept json
 // @Produce json
-// @Param request body models.RegistrationCompleteRequest true "desc"
-// @Success 200 {object} models.RegistrationCompleteResponse "desc"
+// @Param request body models.RegistrationCompleteRequest true " "
+// @Success 200 {object} models.RegistrationCompleteResponse " "
+// @Failure 403 "Invalid email or verification code"
 // @Router /auth/registrationComplete [post]
 func (a *authControllerImpl) RegistrationComplete(c *gin.Context) {
 	request, ok := utils.GetRequest[models.RegistrationCompleteRequest](c)
@@ -172,6 +185,6 @@ func (a *authControllerImpl) RegisterRoutes(group *gin.RouterGroup) {
 	group.POST("/registrationComplete", middleware.RequestMiddleware[models.RegistrationCompleteRequest](enums.GuestRole), a.RegistrationComplete)
 	group.POST("/login", middleware.RequestMiddleware[models.LoginRequest](enums.GuestRole), a.Login)
 	group.POST("/refresh", middleware.RequestMiddleware[models.RegistrationBeginRequest](enums.UserRole), a.Refresh)
-	group.POST("/passwordResetBegin", middleware.RequestMiddleware[models.RegistrationBeginRequest](enums.GuestRole), a.PasswordResetBegin)
+	group.POST("/passwordResetBegin", middleware.RequestMiddleware[models.PasswordResetBeginRequest](enums.GuestRole), a.PasswordResetBegin)
 	group.POST("/passwordResetComplete", middleware.RequestMiddleware[models.RegistrationBeginRequest](enums.GuestRole), a.PasswordResetComplete)
 }

backend/internal/models/auth.go

@@ -30,7 +30,7 @@ type RegistrationBeginRequest struct {
 
 type RegistrationCompleteRequest struct {
 	Username 					string  `json:"username" binding:"required" validate:"username"`
-	VerificationCode	string  `json:"verification_code" binding:"required"`
+	VerificationCode	string  `json:"verification_code" binding:"required" validate:"verification_code=reg"`
 	Name							string  `json:"name" binding:"required" validate:"name"`
 	Birthday					*string `json:"birthday"`
 }
@@ -57,3 +57,18 @@ type RefreshRequest struct {
 type RefreshResponse struct {
 	Tokens
 }
+
+type PasswordResetBeginRequest struct {
+	Email	string `json:"email" binding:"required,email"`
+}
+
+type PasswordResetCompleteRequest struct {
+	Email		 					string  `json:"email" binding:"required,email"`
+	VerificationCode  string  `json:"verification_code" binding:"required" validate:"verification_code=reset"`
+	NewPassword				string  `json:"password" binding:"required" validate:"password"`
+	LogOutAccounts		bool		`json:"log_out_accounts"`
+}
+
+type PasswordResetCompleteResponse struct {
+	Tokens
+}

backend/internal/validation/custom.go

@@ -19,6 +19,7 @@ package validation
 
 import (
 	"easywish/config"
+	"fmt"
 	"regexp"
 
 	"github.com/go-playground/validator/v10"
@@ -76,6 +77,25 @@ func GetCustomHandlers() []CustomValidatorHandler {
 
 				return true
 		}},
+
+		{
+			FieldName: "verification_code",
+			Function: func(fl validator.FieldLevel) bool {
+				codeType := fl.Param()
+				code := fl.Field().String()
+				
+				if codeType == "reg" {
+					return regexp.MustCompile(`[\d]{6,6}`).MatchString(code)
+				}
+
+				if codeType == "reset" {
+					return regexp.MustCompile(
+						`^[{(]?([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})[})]?$`,
+					).MatchString(code)
+				}
+
+				panic(fmt.Sprintf("'%s' is not a valid verification code type", codeType))
+		}},
 		
 	}