schn33fuchs/ticketsystem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases 2 Wiki Activity

Documentation

Browse Source
This commit is contained in:
schn33fuchs
2026-06-07 11:56:16 +02:00
parent 177e959bbd
commit 8fd35f3e82
18 changed files with 677 additions and 166 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/src/handlers/auth.rs
+52 -55
View File
@@ -22,11 +22,12 @@ use crate::{
/// Registers a new user in the system.
///
/// Creates a new user account with the provided credentials. The password is hashed using Argon2
/// before being stored. Only administrators can create new users.
/// Creates a new [`User`] account with the provided [`UserCreateScheme`] credentials.
/// The password is hashed using Argon2 before being stored. Only administrators can create new users.
///
/// # Arguments
/// - `request`: User creation details including first/last name, username, admin flag, and password
/// - `State(data)`: Application state containing [`AppState`] for database access
/// - `request`: [`UserCreateScheme`] containing user details including first/last name, username, admin flag, and password
///
/// # Returns
/// - `200 OK` on successful user creation
@@ -34,12 +35,7 @@ use crate::{
/// - `500 Internal Server Error` if database insertion fails
///
/// # Password Hashing
/// Uses Argon2 with a cryptographically secure random salt:
/// ```ignore
/// let argon = Argon2::default();
/// let salt = SaltString::generate(&mut OsRng);
/// let hashed_pwd = argon.hash_password(password.as_bytes(), &salt)?;
/// ```
/// Uses Argon2 with a cryptographically secure random salt.
pub async fn create_user(
State(data): State<Arc<AppState>>,
Json(request): Json<UserCreateScheme>,
@@ -106,27 +102,23 @@ pub async fn create_user(
/// Authenticates a user and creates a JWT token for session management.
///
/// Verifies the provided username and password against stored credentials using Argon2 verification.
/// On successful authentication, generates a JWT token and sets it as an HTTP-only cookie.
/// On successful authentication, generates and encodes a [`Claims`](crate::models::Claims) token via [`encode_token`](`crate::cookie::jwt::encode_token`) and sets it as an HTTP-only cookie.
/// The token is valid for 1 hour.
///
/// # Arguments
/// - `request`: Login credentials (username, password)
/// - `State(data)`: Application state containing [`AppState`] for database access
/// - `request`: [`LoginScheme`] containing login credentials (username, password)
///
/// # Returns
/// - `200 OK` with JSON containing token and filtered user info
/// - `200 OK` with JSON containing token and filtered [`FilteredUser`] info
/// - `400 Bad Request` if username not found or password invalid
/// - `500 Internal Server Error` if database query fails
///
/// # Security Features
/// - HTTP-only cookie prevents JavaScript access
/// - SameSite=Lax protects against CSRF attacks
/// - Password verification uses Argon2:
/// ```ignore
/// let valid_pwd = Argon2::default()
/// .verify_password(&request.pwd.as_bytes(), &pwd_hash.unwrap())
/// .is_ok();
/// ```
/// - JWT token includes user ID and expiration timestamp
/// - Password verification uses Argon2 with stored [`User`] hash
/// - JWT token includes user ID and expiration timestamp via [`Claims`](crate::models::Claims) encoded by [`encode_token`](`crate::cookie::jwt::encode_token`)
///
/// # Example Response
/// ```json
@@ -195,7 +187,7 @@ pub async fn login(
///
/// Sets the authentication cookie to expire immediately (max_age = -1 hour) which causes
/// the browser to discard it. This effectively logs the user out without requiring server-side
/// session invalidation.
/// session invalidation. The cookie no longer contains a valid [`Claims`](crate::models::Claims) token.
///
/// # Returns
/// Always returns `200 OK` with success message and an expired cookie header
@@ -227,11 +219,11 @@ pub async fn logout() -> Result<impl IntoResponse, (StatusCode, Json<serde_json:
/// Retrieves the currently authenticated user's information.
///
/// Uses the user data embedded in the JWT token (via middleware).
/// Uses the [`FilteredUser`] data embedded in the JWT token (via middleware).
/// Useful for frontends to display logged-in user info or verify authentication.
///
/// # Returns
/// - `200 OK` with user data (excluding password)
/// - `200 OK` with [`FilteredUser`] data (excluding password)
/// - Automatically returns `401 Unauthorized` if not authenticated (middleware)
///
/// # Example Response
@@ -264,11 +256,12 @@ pub async fn get_current_user(
/// Deletes a user account from the system.
///
/// Only admins can delete users. The user account and all associated data is removed.
/// Only admins can delete users (enforced by middleware). The [`User`] account and all associated data is removed.
/// Note: Tickets created by deleted users will have NULL user_id references.
///
/// # Arguments
/// - `id`: User ID to delete
/// - `Path(id)`: [`User`] ID to delete, extracted from URL path
/// - `State(data)`: Application state containing [`AppState`] for database access
///
/// # Returns
/// - `204 No Content` on successful deletion
@@ -302,11 +295,14 @@ pub async fn delete_user(
/// Retrieves all users in the system.
///
/// Only admins can call this endpoint. Returns all users sorted alphabetically by last name.
/// Password hashes are not included in the response.
/// Only admins can call this endpoint (enforced by middleware). Returns all [`User`] records converted to [`FilteredUser`]
/// and sorted alphabetically by last name. Password hashes are not included in the response.
///
/// # Arguments
/// - `State(data)`: Application state containing [`AppState`] for database access
///
/// # Returns
/// - `200 OK` with array of FilteredUser objects
/// - `200 OK` with array of [`FilteredUser`] objects
/// - `500 Internal Server Error` if database query fails
///
/// # Example Response
@@ -352,15 +348,15 @@ pub async fn get_users(
/// Retrieves a single user's details by their ID.
///
/// This endpoint allows fetching a specific user's information. It returns a `FilteredUser`
/// object, ensuring sensitive data like password hashes are not exposed.
/// This endpoint allows fetching a specific [`User`]'s information. It returns a [`FilteredUser`]
/// object (converted via [`filter_user`]), ensuring sensitive data like password hashes are not exposed.
///
/// # Arguments
/// - `Path(id)`: The ID of the user to retrieve, extracted from the URL path.
/// - `State(data)`: Application state containing `AppState` for database access.
/// - `Path(id)`: The ID of the [`User`] to retrieve, extracted from the URL path.
/// - `State(data)`: Application state containing [`AppState`] for database access.
///
/// # Returns
/// - `200 OK` with a `FilteredUser` JSON object if the user is found.
/// - `200 OK` with a [`FilteredUser`] JSON object if the user is found.
/// - `404 Not Found` if a user with the given ID does not exist.
/// - `500 Internal Server Error` if a database query error occurs.
///
@@ -396,23 +392,24 @@ pub async fn get_user_by_id(
/// Updates an existing user's information.
///
/// This endpoint allows administrators to modify a user's `first_name`, `last_name`,
/// This endpoint allows administrators to modify a [`User`]'s `first_name`, `last_name`,
/// `username`, `is_admin` status, and optionally their password. If `new_pwd` in the
/// request body is an empty string, the user's password remains unchanged.
///
/// # Arguments
/// - `Path(id)`: The ID of the user to update, extracted from the URL path.
/// - `State(data)`: Application state containing `AppState` for database access.
/// - `Json(body)`: `UserUpdateScheme` containing the fields to update.
/// - `Path(id)`: The ID of the [`User`] to update, extracted from the URL path.
/// - `State(data)`: Application state containing [`AppState`] for database access.
/// - `Json(body)`: [`UserUpdateScheme`] containing the fields to update.
///
/// # Returns
/// - `200 OK` with the `FilteredUser` object of the updated user.
/// - `200 OK` with the [`FilteredUser`] object of the updated user (converted via [`filter_user`]).
/// - `404 Not Found` if a user with the given ID does not exist.
/// - `500 Internal Server Error` if a database query or password hashing error occurs.
///
/// # Security Note
/// - Passwords are hashed using Argon2 before storage.
/// - This endpoint typically requires admin privileges (enforced by middleware).
/// - This endpoint requires admin privileges (enforced by middleware via
/// [`validate_admin`](crate::cookie::validation::validate_admin)).
pub async fn update_user(
Path(id): Path<i16>,
State(data): State<Arc<AppState>>,
@@ -482,7 +479,10 @@ pub async fn update_user(
/// Checks if any administrator user exists in the system.
///
/// This endpoint is used during initialization to determine if the setup page should be displayed.
/// It counts all users with `is_admin = true` in the database.
/// It counts all [`User`] records with `is_admin = true` in the database.
///
/// # Arguments
/// - `State(data)`: Application state containing [`AppState`] for database access
///
/// # Returns
/// - `200 OK` with JSON: `{"has_admin": bool}` - Whether at least one admin exists
@@ -512,28 +512,24 @@ pub async fn check_admin_exists(
/// Creates the initial administrator account for a fresh system.
///
/// This function handles the one-time setup of the first admin user. It checks that no admin exists
/// before allowing creation. This endpoint is only functional when the system has no administrators.
/// This function handles the one-time setup of the first admin [`User`]. It checks that no admin exists
/// before allowing creation via database count. This endpoint is only functional when the system has no administrators.
/// Once created, subsequent admin registrations must go through the normal `create_user` endpoint
/// with proper authorization.
///
/// # Arguments
/// - `request`: User creation details (first_name, last_name, username, password)
/// - `State(data)`: Application state containing [`AppState`] for database access
/// - `request`: [`UserCreateScheme`] containing user creation details (first_name, last_name, username, password)
///
/// # Returns
/// - `200 OK` with success message if admin account created
/// - `400 Bad Request` if:
/// - Admin already exists
/// - Admin already exists (checked via admin count)
/// - Username or password is empty
/// - `500 Internal Server Error` if database insertion fails
///
/// # Security Note
/// The password is hashed using Argon2 with a random salt before storage:
/// ```ignore
/// let argon = Argon2::default();
/// let salt = SaltString::generate(&mut OsRng);
/// let hashed_pwd = argon.hash_password(request.pwd.as_bytes(), &salt)?;
/// ```
/// The password is hashed using Argon2 with a random salt before storage.
pub async fn setup_initial_admin(
State(data): State<Arc<AppState>>,
Json(request): Json<UserCreateScheme>,
@@ -598,17 +594,18 @@ pub async fn setup_initial_admin(
}
}
/// Converts a User with sensitive data into a FilteredUser safe for API responses.
/// Converts a [`User`] with sensitive data into a [`FilteredUser`] safe for API responses.
///
/// This function removes password hashes and other sensitive information before
/// returning user data to clients. Always use this helper instead of directly
/// serializing User objects.
/// returning [`User`] data to clients. Always use this helper instead of directly
/// serializing [`User`] objects.
/// Used by all authentication endpoints to ensure passwords are never exposed.
///
/// # Arguments
/// - `user`: Reference to the internal User struct containing password hash
/// - `user`: Reference to the internal [`User`] struct containing password hash
///
/// # Returns
/// FilteredUser with only safe-to-share information:
/// [`FilteredUser`] with only safe-to-share information:
/// - `id`: User ID
/// - `first_name`, `last_name`: User name
/// - `username`: Login username
@@ -621,7 +618,7 @@ pub async fn setup_initial_admin(
/// # Example
/// ```ignore
/// let user = get_user_from_db(1).await?;
/// let safe_user = filter_user(&user);
/// let safe_user = filter_user(&user); // Convert User to FilteredUser
/// // safe_user can be safely serialized and sent to client
/// ```
pub fn filter_user(user: &User) -> FilteredUser {
backend/src/handlers/ticket.rs
+25 -16
View File
@@ -16,12 +16,14 @@ use crate::{
/// Creates a new support ticket.
///
/// Associates the ticket with the authenticated user and sets the current timestamp.
/// Associates the ticket with the authenticated [`FilteredUser`] and sets the current timestamp.
/// Converts the [`TicketCreateScheme`] request into a database record.
/// Tickets are automatically created with "open" status.
///
/// # Arguments
/// - `user`: Authenticated user (extracted from JWT token)
/// - `body`: Ticket details (category, subject, description, room)
/// - `Extension(user)`: Authenticated [`FilteredUser`] (extracted from JWT token via middleware)
/// - `State(data)`: Application state containing [`AppState`] for database access
/// - `Json(body)`: [`TicketCreateScheme`] containing ticket details (category, subject, description, room)
///
/// # Returns
/// - `200 OK` on successful creation
@@ -60,10 +62,11 @@ pub async fn create_ticket(
/// Deletes a ticket by ID.
///
/// Only admins can delete tickets. Marks the ticket as deleted or removes from database.
/// Only admins can delete tickets (enforced by middleware). Removes the [`TicketResponse`] and associated data from the database.
///
/// # Arguments
/// - `id`: Ticket ID to delete
/// - `Path(id)`: Ticket ID to delete, extracted from URL path
/// - `State(data)`: Application state containing [`AppState`] for database access
///
/// # Returns
/// - `204 No Content` on successful deletion
@@ -97,15 +100,18 @@ pub async fn delete_ticket(
/// Retrieves all non-archived tickets.
///
/// Returns a list of all active tickets with user information denormalized for easier rendering.
/// Tickets are ordered by creation date (newest first).
/// Returns a list of all active [`TicketResponse`] objects with user information denormalized for easier rendering.
/// Tickets are ordered by creation date (newest first). Joins with [`User`](crate::models::User) table to include creator information.
///
/// # Arguments
/// - `State(data)`: Application state containing [`AppState`] for database access
///
/// # Filtering
/// - Excludes tickets with status "Archived"
/// - Uses LEFT JOIN to include creator information
/// - Uses LEFT JOIN to include creator information from [`User`](crate::models::User)
///
/// # Returns
/// - `200 OK` with array of TicketResponse objects
/// - `200 OK` with array of [`TicketResponse`] objects
/// - `500 Internal Server Error` if database query fails
///
/// # Example Response
@@ -169,12 +175,14 @@ pub async fn get_tickets(
/// Retrieves a specific ticket by ID.
///
/// Includes full ticket details and denormalized user information (creator name).
/// Returns a [`TicketResponse`] with all metadata by joining with [`User`](crate::models::User) table.
///
/// # Arguments
/// - `id`: Ticket ID to retrieve
/// - `Path(id)`: Ticket ID to retrieve, extracted from URL path
/// - `State(data)`: Application state containing [`AppState`] for database access
///
/// # Returns
/// - `200 OK` with TicketResponse object
/// - `200 OK` with [`TicketResponse`] object
/// - `404 Not Found` if ticket doesn't exist
/// - `500 Internal Server Error` if database error occurs
///
@@ -242,15 +250,16 @@ pub async fn get_ticket_by_id(
/// Updates a ticket's status.
///
/// Only admins can update ticket status. This is typically used to transition tickets
/// through their lifecycle (open → in_progress → resolved → archived).
/// Only admins can update ticket status (enforced by middleware). Applies [`TicketUpdateScheme`] to modify the [`TicketResponse`].
/// This is typically used to transition tickets through their lifecycle (open → in_progress → resolved → archived).
///
/// # Arguments
/// - `id`: Ticket ID to update
/// - `body`: Update payload containing new status
/// - `Path(id)`: Ticket ID to update, extracted from URL path
/// - `State(data)`: Application state containing [`AppState`] for database access
/// - `Json(body)`: [`TicketUpdateScheme`] update payload containing new status
///
/// # Returns
/// - `200 OK` with updated TicketResponse
/// - `200 OK` with updated [`TicketResponse`]
/// - `500 Internal Server Error` if ticket not found or database error
///
/// # Typical Status Flow