feature: add user activation endpoints (#86)

* feature: add user activation endpoints

* styleci

* add 403 docs

---------

Co-authored-by: Crypta Eve <crypta@crypta.tech>

Author: recursivetree

src/Http/Controllers/Api/v2/UserController.php

@@ -166,6 +166,7 @@ public function getConfiguredScopes(): JsonResponse
             ),
             new OA\Response(response: 400, description: 'Bad request'),
             new OA\Response(response: 401, description: 'Unauthorized'),
+            new OA\Response(response: 403, description: 'Forbidden'),
         ]
     )]
     public function postNewUser(NewUser $request): JsonResponse|UserResource
@@ -211,6 +212,7 @@ public function postNewUser(NewUser $request): JsonResponse|UserResource
             new OA\Response(response: 200, description: 'Successful operation'),
             new OA\Response(response: 400, description: 'Bad request'),
             new OA\Response(response: 401, description: 'Unauthorized'),
+            new OA\Response(response: 403, description: 'Forbidden'),
         ]
     )]
     public function deleteUser(int $user_id): JsonResponse
@@ -225,4 +227,74 @@ public function deleteUser(int $user_id): JsonResponse
 
         return response()->json();
     }
+
+    #[OA\Post(
+        path: '/api/v2/users/{user_id}/activate',
+        description: 'Activates a user',
+        summary: 'Activates a deactivated SeAT user. Returns successfully if already activated.',
+        security: [
+            [
+                'ApiKeyAuth' => [],
+            ],
+        ],
+        tags: [
+            'Users',
+        ],
+        parameters: [
+            new OA\Parameter(name: 'user_id', description: 'A SeAT User ID', in: 'path', required: true, schema: new OA\Schema(type: 'integer')),
+        ],
+        responses: [
+            new OA\Response(response: 200, description: 'Successful operation'),
+            new OA\Response(response: 400, description: 'Bad request'),
+            new OA\Response(response: 401, description: 'Unauthorized'),
+            new OA\Response(response: 403, description: 'Forbidden'),
+        ]
+    )]
+    public function postActivateUser(int $user_id): JsonResponse
+    {
+        $user = User::findOrFail($user_id);
+
+        if ($user->name == 'admin')
+            return response()->json('You cannot modify this user.', 403);
+
+        $user->active = true;
+        $user->save();
+
+        return response()->json();
+    }
+
+    #[OA\Post(
+        path: '/api/v2/users/{user_id}/deactivate',
+        description: 'Deactivates a user',
+        summary: 'Deactivates a SeAT user. Returns successfully if already deactivated.',
+        security: [
+            [
+                'ApiKeyAuth' => [],
+            ],
+        ],
+        tags: [
+            'Users',
+        ],
+        parameters: [
+            new OA\Parameter(name: 'user_id', description: 'A SeAT User ID', in: 'path', required: true, schema: new OA\Schema(type: 'integer')),
+        ],
+        responses: [
+            new OA\Response(response: 200, description: 'Successful operation'),
+            new OA\Response(response: 400, description: 'Bad request'),
+            new OA\Response(response: 401, description: 'Unauthorized'),
+            new OA\Response(response: 403, description: 'Forbidden'),
+        ]
+    )]
+    public function postDeactivateUser(int $user_id): JsonResponse
+    {
+        $user = User::findOrFail($user_id);
+
+        if ($user->name == 'admin')
+            return response()->json('You cannot modify this user.', 403);
+
+        $user->active = false;
+        $user->save();
+
+        return response()->json();
+    }
 }

src/Http/routes.php

@@ -68,6 +68,9 @@
                 Route::get('/')->uses('UserController@getUsers');
                 Route::get('/{user_id}')->uses('UserController@show')->where(['user_id' => '[0-9]+']);
 
+                Route::post('/{user_id}/activate')->uses('UserController@postActivateUser');
+                Route::post('/{user_id}/deactivate')->uses('UserController@postDeactivateUser');
+
                 Route::get('/configured-scopes')->uses('UserController@getConfiguredScopes');
             });