feat: api key authentication (#291)

Co-authored-by: Elias Schneider <login@eliasschneider.com>
2025-12-17 17:23:30 +03:00 · 2025-03-11 14:16:42 -05:00
parent 74ba8390f4
commit 62915d863a
58 changed files with 2172 additions and 190 deletions
--- a/backend/internal/controller/user_controller.go
+++ b/backend/internal/controller/user_controller.go
@@ -16,30 +16,34 @@ import (
 	"golang.org/x/time/rate"
 )

-func NewUserController(group *gin.RouterGroup, jwtAuthMiddleware *middleware.JwtAuthMiddleware, rateLimitMiddleware *middleware.RateLimitMiddleware, userService *service.UserService, appConfigService *service.AppConfigService) {
+// NewUserController creates a new controller for user management endpoints
+// @Summary User management controller
+// @Description Initializes all user-related API endpoints
+// @Tags Users
+func NewUserController(group *gin.RouterGroup, authMiddleware *middleware.AuthMiddleware, rateLimitMiddleware *middleware.RateLimitMiddleware, userService *service.UserService, appConfigService *service.AppConfigService) {
 	uc := UserController{
 		userService:      userService,
 		appConfigService: appConfigService,
 	}

-	group.GET("/users", jwtAuthMiddleware.Add(true), uc.listUsersHandler)
-	group.GET("/users/me", jwtAuthMiddleware.Add(false), uc.getCurrentUserHandler)
-	group.GET("/users/:id", jwtAuthMiddleware.Add(true), uc.getUserHandler)
-	group.POST("/users", jwtAuthMiddleware.Add(true), uc.createUserHandler)
-	group.PUT("/users/:id", jwtAuthMiddleware.Add(true), uc.updateUserHandler)
-	group.GET("/users/:id/groups", jwtAuthMiddleware.Add(true), uc.getUserGroupsHandler)
-	group.PUT("/users/me", jwtAuthMiddleware.Add(false), uc.updateCurrentUserHandler)
-	group.DELETE("/users/:id", jwtAuthMiddleware.Add(true), uc.deleteUserHandler)
+	group.GET("/users", authMiddleware.Add(), uc.listUsersHandler)
+	group.GET("/users/me", authMiddleware.WithAdminNotRequired().Add(), uc.getCurrentUserHandler)
+	group.GET("/users/:id", authMiddleware.Add(), uc.getUserHandler)
+	group.POST("/users", authMiddleware.Add(), uc.createUserHandler)
+	group.PUT("/users/:id", authMiddleware.Add(), uc.updateUserHandler)
+	group.GET("/users/:id/groups", authMiddleware.Add(), uc.getUserGroupsHandler)
+	group.PUT("/users/me", authMiddleware.WithAdminNotRequired().Add(), uc.updateCurrentUserHandler)
+	group.DELETE("/users/:id", authMiddleware.Add(), uc.deleteUserHandler)

-	group.PUT("/users/:id/user-groups", jwtAuthMiddleware.Add(true), uc.updateUserGroups)
+	group.PUT("/users/:id/user-groups", authMiddleware.Add(), uc.updateUserGroups)

 	group.GET("/users/:id/profile-picture.png", uc.getUserProfilePictureHandler)
-	group.GET("/users/me/profile-picture.png", jwtAuthMiddleware.Add(false), uc.getCurrentUserProfilePictureHandler)
-	group.PUT("/users/:id/profile-picture", jwtAuthMiddleware.Add(true), uc.updateUserProfilePictureHandler)
-	group.PUT("/users/me/profile-picture", jwtAuthMiddleware.Add(false), uc.updateCurrentUserProfilePictureHandler)
+	group.GET("/users/me/profile-picture.png", authMiddleware.WithAdminNotRequired().Add(), uc.getCurrentUserProfilePictureHandler)
+	group.PUT("/users/:id/profile-picture", authMiddleware.Add(), uc.updateUserProfilePictureHandler)
+	group.PUT("/users/me/profile-picture", authMiddleware.WithAdminNotRequired().Add(), uc.updateCurrentUserProfilePictureHandler)

-	group.POST("/users/me/one-time-access-token", jwtAuthMiddleware.Add(false), uc.createOwnOneTimeAccessTokenHandler)
-	group.POST("/users/:id/one-time-access-token", jwtAuthMiddleware.Add(true), uc.createAdminOneTimeAccessTokenHandler)
+	group.POST("/users/me/one-time-access-token", authMiddleware.WithAdminNotRequired().Add(), uc.createOwnOneTimeAccessTokenHandler)
+	group.POST("/users/:id/one-time-access-token", authMiddleware.Add(), uc.createAdminOneTimeAccessTokenHandler)
 	group.POST("/one-time-access-token/:token", rateLimitMiddleware.Add(rate.Every(10*time.Second), 5), uc.exchangeOneTimeAccessTokenHandler)
 	group.POST("/one-time-access-token/setup", uc.getSetupAccessTokenHandler)
 	group.POST("/one-time-access-email", rateLimitMiddleware.Add(rate.Every(10*time.Minute), 3), uc.requestOneTimeAccessEmailHandler)
@@ -50,6 +54,13 @@ type UserController struct {
 	appConfigService *service.AppConfigService
 }

+// getUserGroupsHandler godoc
+// @Summary Get user groups
+// @Description Retrieve all groups a specific user belongs to
+// @Tags Users,User Groups
+// @Param id path string true "User ID"
+// @Success 200 {array} dto.UserGroupDtoWithUsers
+// @Router /users/{id}/groups [get]
 func (uc *UserController) getUserGroupsHandler(c *gin.Context) {
 	userID := c.Param("id")
 	groups, err := uc.userService.GetUserGroups(userID)
@@ -67,6 +78,17 @@ func (uc *UserController) getUserGroupsHandler(c *gin.Context) {
 	c.JSON(http.StatusOK, groupsDto)
 }

+// listUsersHandler godoc
+// @Summary List users
+// @Description Get a paginated list of users with optional search and sorting
+// @Tags Users
+// @Param search query string false "Search term to filter users"
+// @Param page query int false "Page number, starting from 1" default(1)
+// @Param limit query int false "Number of items per page" default(10)
+// @Param sort_column query string false "Column to sort by" default("created_at")
+// @Param sort_direction query string false "Sort direction (asc or desc)" default("desc")
+// @Success 200 {object} dto.Paginated[dto.UserDto]
+// @Router /users [get]
 func (uc *UserController) listUsersHandler(c *gin.Context) {
 	searchTerm := c.Query("search")
 	var sortedPaginationRequest utils.SortedPaginationRequest
@@ -87,12 +109,19 @@ func (uc *UserController) listUsersHandler(c *gin.Context) {
 		return
 	}

-	c.JSON(http.StatusOK, gin.H{
-		"data":       usersDto,
-		"pagination": pagination,
+	c.JSON(http.StatusOK, dto.Paginated[dto.UserDto]{
+		Data:       usersDto,
+		Pagination: pagination,
 	})
 }

+// getUserHandler godoc
+// @Summary Get user by ID
+// @Description Retrieve detailed information about a specific user
+// @Tags Users
+// @Param id path string true "User ID"
+// @Success 200 {object} dto.UserDto
+// @Router /users/{id} [get]
 func (uc *UserController) getUserHandler(c *gin.Context) {
 	user, err := uc.userService.GetUser(c.Param("id"))
 	if err != nil {
@@ -109,6 +138,12 @@ func (uc *UserController) getUserHandler(c *gin.Context) {
 	c.JSON(http.StatusOK, userDto)
 }

+// getCurrentUserHandler godoc
+// @Summary Get current user
+// @Description Retrieve information about the currently authenticated user
+// @Tags Users
+// @Success 200 {object} dto.UserDto
+// @Router /users/me [get]
 func (uc *UserController) getCurrentUserHandler(c *gin.Context) {
 	user, err := uc.userService.GetUser(c.GetString("userID"))
 	if err != nil {
@@ -125,6 +160,13 @@ func (uc *UserController) getCurrentUserHandler(c *gin.Context) {
 	c.JSON(http.StatusOK, userDto)
 }

+// deleteUserHandler godoc
+// @Summary Delete user
+// @Description Delete a specific user by ID
+// @Tags Users
+// @Param id path string true "User ID"
+// @Success 204 "No Content"
+// @Router /users/{id} [delete]
 func (uc *UserController) deleteUserHandler(c *gin.Context) {
 	if err := uc.userService.DeleteUser(c.Param("id")); err != nil {
 		c.Error(err)
@@ -134,6 +176,13 @@ func (uc *UserController) deleteUserHandler(c *gin.Context) {
 	c.Status(http.StatusNoContent)
 }

+// createUserHandler godoc
+// @Summary Create user
+// @Description Create a new user
+// @Tags Users
+// @Param user body dto.UserCreateDto true "User information"
+// @Success 201 {object} dto.UserDto
+// @Router /users [post]
 func (uc *UserController) createUserHandler(c *gin.Context) {
 	var input dto.UserCreateDto
 	if err := c.ShouldBindJSON(&input); err != nil {
@@ -156,10 +205,25 @@ func (uc *UserController) createUserHandler(c *gin.Context) {
 	c.JSON(http.StatusCreated, userDto)
 }

+// updateUserHandler godoc
+// @Summary Update user
+// @Description Update an existing user by ID
+// @Tags Users
+// @Param id path string true "User ID"
+// @Param user body dto.UserCreateDto true "User information"
+// @Success 200 {object} dto.UserDto
+// @Router /users/{id} [put]
 func (uc *UserController) updateUserHandler(c *gin.Context) {
 	uc.updateUser(c, false)
 }

+// updateCurrentUserHandler godoc
+// @Summary Update current user
+// @Description Update the currently authenticated user's information
+// @Tags Users
+// @Param user body dto.UserCreateDto true "User information"
+// @Success 200 {object} dto.UserDto
+// @Router /users/me [put]
 func (uc *UserController) updateCurrentUserHandler(c *gin.Context) {
 	if uc.appConfigService.DbConfig.AllowOwnAccountEdit.Value != "true" {
 		c.Error(&common.AccountEditNotAllowedError{})
@@ -168,6 +232,14 @@ func (uc *UserController) updateCurrentUserHandler(c *gin.Context) {
 	uc.updateUser(c, true)
 }

+// getUserProfilePictureHandler godoc
+// @Summary Get user profile picture
+// @Description Retrieve a specific user's profile picture
+// @Tags Users
+// @Produce image/png
+// @Param id path string true "User ID"
+// @Success 200 {file} binary "PNG image"
+// @Router /users/{id}/profile-picture.png [get]
 func (uc *UserController) getUserProfilePictureHandler(c *gin.Context) {
 	userID := c.Param("id")

@@ -180,6 +252,13 @@ func (uc *UserController) getUserProfilePictureHandler(c *gin.Context) {
 	c.DataFromReader(http.StatusOK, size, "image/png", picture, nil)
 }

+// getCurrentUserProfilePictureHandler godoc
+// @Summary Get current user's profile picture
+// @Description Retrieve the currently authenticated user's profile picture
+// @Tags Users
+// @Produce image/png
+// @Success 200 {file} binary "PNG image"
+// @Router /users/me/profile-picture.png [get]
 func (uc *UserController) getCurrentUserProfilePictureHandler(c *gin.Context) {
 	userID := c.GetString("userID")

@@ -192,6 +271,16 @@ func (uc *UserController) getCurrentUserProfilePictureHandler(c *gin.Context) {
 	c.DataFromReader(http.StatusOK, size, "image/png", picture, nil)
 }

+// updateUserProfilePictureHandler godoc
+// @Summary Update user profile picture
+// @Description Update a specific user's profile picture
+// @Tags Users
+// @Accept multipart/form-data
+// @Produce json
+// @Param id path string true "User ID"
+// @Param file formData file true "Profile picture image file (PNG, JPG, or JPEG)"
+// @Success 204 "No Content"
+// @Router /users/{id}/profile-picture [put]
 func (uc *UserController) updateUserProfilePictureHandler(c *gin.Context) {
 	userID := c.Param("id")
 	fileHeader, err := c.FormFile("file")
@@ -214,6 +303,15 @@ func (uc *UserController) updateUserProfilePictureHandler(c *gin.Context) {
 	c.Status(http.StatusNoContent)
 }

+// updateCurrentUserProfilePictureHandler godoc
+// @Summary Update current user's profile picture
+// @Description Update the currently authenticated user's profile picture
+// @Tags Users
+// @Accept multipart/form-data
+// @Produce json
+// @Param file formData file true "Profile picture image file (PNG, JPG, or JPEG)"
+// @Success 204 "No Content"
+// @Router /users/me/profile-picture [put]
 func (uc *UserController) updateCurrentUserProfilePictureHandler(c *gin.Context) {
 	userID := c.GetString("userID")
 	fileHeader, err := c.FormFile("file")
@@ -255,6 +353,14 @@ func (uc *UserController) createOneTimeAccessTokenHandler(c *gin.Context, own bo
 	c.JSON(http.StatusCreated, gin.H{"token": token})
 }

+// createOwnOneTimeAccessTokenHandler godoc
+// @Summary Create one-time access token for current user
+// @Description Generate a one-time access token for the currently authenticated user
+// @Tags Users
+// @Param id path string true "User ID"
+// @Param body body dto.OneTimeAccessTokenCreateDto true "Token options"
+// @Success 201 {object} object "{ \"token\": \"string\" }"
+// @Router /users/{id}/one-time-access-token [post]
 func (uc *UserController) createOwnOneTimeAccessTokenHandler(c *gin.Context) {
 	uc.createOneTimeAccessTokenHandler(c, true)
 }
@@ -279,6 +385,13 @@ func (uc *UserController) requestOneTimeAccessEmailHandler(c *gin.Context) {
 	c.Status(http.StatusNoContent)
 }

+// exchangeOneTimeAccessTokenHandler godoc
+// @Summary Exchange one-time access token
+// @Description Exchange a one-time access token for a session token
+// @Tags Users
+// @Param token path string true "One-time access token"
+// @Success 200 {object} dto.UserDto
+// @Router /one-time-access-token/{token} [post]
 func (uc *UserController) exchangeOneTimeAccessTokenHandler(c *gin.Context) {
 	user, token, err := uc.userService.ExchangeOneTimeAccessToken(c.Param("token"), c.ClientIP(), c.Request.UserAgent())
 	if err != nil {
@@ -299,6 +412,12 @@ func (uc *UserController) exchangeOneTimeAccessTokenHandler(c *gin.Context) {
 	c.JSON(http.StatusOK, userDto)
 }

+// getSetupAccessTokenHandler godoc
+// @Summary Setup initial admin
+// @Description Generate setup access token for initial admin user configuration
+// @Tags Users
+// @Success 200 {object} dto.UserDto
+// @Router /one-time-access-token/setup [post]
 func (uc *UserController) getSetupAccessTokenHandler(c *gin.Context) {
 	user, token, err := uc.userService.SetupInitialAdmin()
 	if err != nil {
@@ -319,6 +438,37 @@ func (uc *UserController) getSetupAccessTokenHandler(c *gin.Context) {
 	c.JSON(http.StatusOK, userDto)
 }

+// updateUserGroups godoc
+// @Summary Update user groups
+// @Description Update the groups a specific user belongs to
+// @Tags Users
+// @Param id path string true "User ID"
+// @Param groups body dto.UserUpdateUserGroupDto true "User group IDs"
+// @Success 200 {object} dto.UserDto
+// @Router /users/{id}/user-groups [put]
+func (uc *UserController) updateUserGroups(c *gin.Context) {
+	var input dto.UserUpdateUserGroupDto
+	if err := c.ShouldBindJSON(&input); err != nil {
+		c.Error(err)
+		return
+	}
+
+	user, err := uc.userService.UpdateUserGroups(c.Param("id"), input.UserGroupIds)
+	if err != nil {
+		c.Error(err)
+		return
+	}
+
+	var userDto dto.UserDto
+	if err := dto.MapStruct(user, &userDto); err != nil {
+		c.Error(err)
+		return
+	}
+
+	c.JSON(http.StatusOK, userDto)
+}
+
+// updateUser is an internal helper method, not exposed as an API endpoint
 func (uc *UserController) updateUser(c *gin.Context, updateOwnUser bool) {
 	var input dto.UserCreateDto
 	if err := c.ShouldBindJSON(&input); err != nil {
@@ -347,25 +497,3 @@ func (uc *UserController) updateUser(c *gin.Context, updateOwnUser bool) {

 	c.JSON(http.StatusOK, userDto)
 }
-
-func (uc *UserController) updateUserGroups(c *gin.Context) {
-	var input dto.UserUpdateUserGroupDto
-	if err := c.ShouldBindJSON(&input); err != nil {
-		c.Error(err)
-		return
-	}
-
-	user, err := uc.userService.UpdateUserGroups(c.Param("id"), input.UserGroupIds)
-	if err != nil {
-		c.Error(err)
-		return
-	}
-
-	var userDto dto.UserDto
-	if err := dto.MapStruct(user, &userDto); err != nil {
-		c.Error(err)
-		return
-	}
-
-	c.JSON(http.StatusOK, userDto)
-}