feat: Implement role-based registration restrictions and reorganize Bruno collection

- Add role-based restrictions to POST /api/auth/register endpoint - Only admins can create admin accounts if any admin already exists - First user automatically gets admin role regardless of request - Regular users can only create user accounts, not admin accounts - Unauthenticated users can only create first admin, not subsequent admins - Reorganize Bruno collection into logical subfolders (auth/, admin/, profile/) - Update documentation to reflect new registration restrictions and security rules BREAKING CHANGES: - /api/auth/register now enforces role-based creation restrictions - Bruno collection reorganized with subfolder structure
2026-01-27 14:15:06 -05:00
parent 71584c1b55
commit 481adaa71e
15 changed files with 197 additions and 138 deletions
@@ -0,0 +1,53 @@
+meta {
+  name: Delete Account
+  type: http
+  seq: 4
+}
+
+delete {
+  url: {{base_url}}/api/auth/account
+  body: none
+  auth: inherit
+}
+
+settings {
+  encodeUrl: true
+  timeout: 0
+}
+
+docs {
+  ## Delete Account
+  
+  Permanently deletes user account and all associated data.
+  
+  **Method:** DELETE
+  
+  **Endpoint:** /api/auth/account
+  
+  **Authentication:** Required
+  
+  **Usage:**
+  - **Self-deletion**: DELETE /api/auth/account (no parameters)
+  - **Admin deletion**: DELETE /api/auth/account?user_id={uuid} (admin only)
+  
+  **Query Parameters (Admin only):**
+  - `user_id` (string): UUID of user account to delete
+  
+  **Response:**
+  - `message` (string): Success message
+  
+  **Status Codes:**
+  - 200: Success
+  - 400: Bad Request (invalid user_id or attempting to delete last admin)
+  - 401: Unauthorized
+  - 403: Forbidden (admin access required for user_id parameter)
+  - 404: Not Found (user does not exist)
+  
+  **Protection Rules:**
+  - Regular users can only delete their own account
+  - Admins can delete any account including other users
+  - Cannot delete the last admin account in the system
+  - Admin role required to use user_id parameter
+  
+  **Warning:** This action cannot be undone and will permanently delete all user data including ebooks, ratings, and progress.
+}
@@ -0,0 +1,54 @@
+meta {
+  name: Delete User Account (Admin)
+  type: http
+  seq: 6
+}
+
+delete {
+  url: {{base_url}}/api/auth/account?user_id={{user_id}}
+  body: none
+  auth: inherit
+}
+
+settings {
+  encodeUrl: true
+  timeout: 0
+}
+
+docs {
+  ## Delete User Account (Admin)
+  
+  Allows administrators to delete any user account by specifying user_id parameter.
+  
+  **Method:** DELETE
+  
+  **Endpoint:** /api/auth/account?user_id={user_id}
+  
+  **Authentication:** Required (Admin only)
+  
+  **Query Parameters:**
+  - `user_id` (string, required for admin): UUID of the user account to delete
+  
+  **Usage Examples:**
+  - **Self-deletion**: DELETE /api/auth/account (no user_id parameter)
+  - **Admin deletion**: DELETE /api/auth/account?user_id=550e8400-e29b-41d4-a716-446655440000
+  
+  **Response:**
+  - `message` (string): Success message indicating which account was deleted
+  
+  **Status Codes:**
+  - 200: Success
+  - 400: Bad Request (invalid user_id or attempting to delete last admin)
+  - 401: Unauthorized
+  - 403: Forbidden (admin access required for user_id parameter)
+  - 404: Not Found (user does not exist)
+  
+  **Admin Protection Rules:**
+  - Regular users can only delete their own account (no user_id parameter allowed)
+  - Admins can delete any account including their own
+  - Cannot delete the last admin account in the system
+  - Admin role required to use user_id parameter
+  
+  **Variables:**
+  - `user_id`: Set this to the UUID of the user you want to delete
+}
@@ -0,0 +1,93 @@
+meta {
+  name: List Users
+  type: http
+  seq: 5
+}
+
+get {
+  url: {{base_url}}/api/auth/users
+  body: none
+  auth: inherit
+}
+
+settings {
+  encodeUrl: true
+  timeout: 0
+}
+
+docs {
+  ## List Users
+  
+  Retrieves a list of all users with complete user information.
+  
+  **Method:** GET
+  
+  **Endpoint:** /api/auth/users
+  
+  **Authentication:** Required (Admin only)
+  
+  **Response:** Array of user objects with complete information:
+  - `id` (string): User ID (UUID)
+  - `email` (string): Email address
+  - `username` (string): Username
+  - `first_name` (string): First name (empty if not set)
+  - `last_name` (string): Last name (empty if not set)
+  - `role` (string): User role ("user" or "admin")
+  - `theme` (string): Theme preference (empty if default)
+  - `created_at` (string): Creation timestamp (ISO 8601)
+  - `updated_at` (string): Last update timestamp (ISO 8601)
+  
+  **Status Codes:**
+  - 200: Success
+  - 401: Unauthorized
+  - 403: Forbidden (admin access required)
+  
+  **Features:**
+  - Admin-only endpoint with complete user information
+  - Returns first_name, last_name, role, theme fields
+  - Useful for user management interfaces
+}
+
+get {
+  url: {{base_url}}/api/auth/users
+  body: none
+  auth: inherit
+}
+
+settings {
+  encodeUrl: true
+  timeout: 0
+}
+
+docs {
+  ## List Users (Admin)
+  
+  Retrieves a list of all users with complete user information.
+  
+  **Method:** GET
+  
+   **Endpoint:** /api/auth/users
+  
+  **Authentication:** Required (Admin only)
+  
+  **Response:** Array of user objects with complete information:
+  - `id` (string): User ID (UUID)
+  - `email` (string): Email address
+  - `username` (string): Username
+  - `first_name` (string): First name (empty if not set)
+  - `last_name` (string): Last name (empty if not set)
+  - `role` (string): User role ("user" or "admin")
+  - `theme` (string): Theme preference (empty if default)
+  - `created_at` (string): Creation timestamp (ISO 8601)
+  - `updated_at` (string): Last update timestamp (ISO 8601)
+  
+  **Status Codes:**
+  - 200: Success
+  - 401: Unauthorized
+  - 403: Forbidden (admin access required)
+  
+  **Enhanced Features:**
+  - Now admin-only endpoint (moved from public to protected admin group)
+  - Returns complete user profile information including names and role
+  - Useful for comprehensive admin user management
+}
@@ -0,0 +1,81 @@
+meta {
+  name: Register Admin User
+  type: http
+  seq: 4
+}
+
+post {
+  url: {{base_url}}/api/auth/register
+  body: json
+  auth: inherit
+}
+
+body:json {
+  {
+        "email": "admin@example.com",
+        "username": "admin",
+        "password": "admin123",
+        "first_name": "Admin",
+        "last_name": "User",
+        "role": "admin"
+      }
+}
+
+script:post-response {
+  function onResponse(res) {
+    let data = res.getBody();
+    return bru.setEnvVar("token", data.token, { persist: true });
+  }
+  onResponse(res);
+}
+
+settings {
+  encodeUrl: true
+  timeout: 0
+}
+
+docs {
+  ## Register Admin User
+  
+  Creates a new admin user account with role-based restrictions.
+  
+  **Method:** POST
+  
+  **Endpoint:** /api/auth/register
+  
+   **Request Body:**
+   - `email` (string): Email address
+   - `username` (string): Username
+   - `password` (string): Password
+   - `first_name` (string, optional): First name
+   - `last_name` (string, optional): Last name
+   - `role` (string): Must be "admin"
+  
+  **Response:**
+   - `token` (string): JWT token with admin role
+    - `user` (object): User details
+       - `id` (string): User ID
+       - `email` (string): Email
+       - `username` (string): Username
+   - `theme` (string): User theme preference
+       - `first_name` (string, optional): First name
+       - `last_name` (string, optional): Last name
+       - `role` (string): User role ("admin")
+  
+  **Status Codes:**
+   - 201: Created
+   - 400: Invalid input data
+   - 403: Forbidden - admin creation restrictions apply
+   - 409: User exists
+  
+  **Role Restrictions:**
+   - **First User**: Anyone can create first admin (auto-assigned)
+   - **Existing Admins Present**: Only authenticated admins can create new admin accounts
+   - **Unauthenticated Users**: Cannot create admin accounts if any admin exists
+   - **Security**: Requires admin authentication for subsequent admin creation
+  
+  **Usage Notes:**
+   - Use this request only when specifically creating admin accounts
+   - For regular user creation, use "Register User" request
+   - Admin token will have elevated privileges for administrative operations
+ }