Merge pull request #4 from kavinda-100/develop

Develop

Author: kavinda-100

README.md

@@ -13,7 +13,8 @@ A production-ready Task Management REST API built with **Rust**, **Axum**, and *
 
 - 🏗️ **Clean Architecture** – Organized into Models, Controllers, Services, Routes, and Middleware
 - 🔄 **API Versioning** – `/api/v1` ready
-- 🔒 **Google OAuth + JWT Auth** – Secure authentication system
+- 🔐 **JWT Cookie Authentication (Implemented)** – Register, login, logout, and protected `me` endpoint
+- 🔒 **Google OAuth (Planned/Partial)** – User model and login checks are ready for OAuth users
 - 🗃️ **Database Migrations** – SQLx-powered migrations for PostgreSQL
 - ⚡ **Async/Await** – Powered by Tokio runtime for high-performance APIs
 - 📝 **Full CRUD** – Tasks, Projects, Users, Workspaces
@@ -40,7 +41,120 @@ A production-ready Task Management REST API built with **Rust**, **Axum**, and *
 
 ---
 
-## 📁 Project Structure (coming soon)
+## 📁 Project Structure (Current)
+
+```bash
+src/
+├── controllers/
+│   ├── auth_controller.rs      # register/login/logout/me handlers
+│   └── root_controller.rs      # health check
+├── dtos/
+│   └── auth_dto.rs             # request validation + auth response DTO
+├── middleware/
+│   └── auth.rs                 # JWT cookie auth extractor for protected routes
+├── routes/
+│   ├── auth_routes.rs          # /api/v1/auth/* route definitions
+│   └── mod.rs                  # route composition + static file fallback
+├── utils/
+│   ├── response.rs             # ApiResponse<T> success wrapper
+│   ├── api_error.rs            # ApiError enum -> HTTP error responses
+│   ├── jwt.rs                  # token generation and verification
+│   ├── hash.rs                 # Argon2 password hash + verify
+│   └── mod.rs                  # utility exports + validation error formatter
+├── db/
+│   └── mod.rs                  # DB pool + automatic SQLx migrations at startup
+└── main.rs                     # app bootstrap, middleware layers, state wiring
+```
+
+## 🔐 Auth Module (Implemented So Far)
+
+Base path: `/api/v1/auth`
+
+- `POST /register`
+    - Validates payload (`name`, `email`, `password`, `confirm_password`)
+    - Checks duplicate email
+    - Hashes password with Argon2
+    - Creates user in PostgreSQL
+    - Generates JWT and stores it in an HTTP-only cookie named `token`
+    - Returns normalized `ApiResponse<AuthUserResponse>`
+
+- `POST /login`
+    - Validates payload
+    - Finds user by email
+    - Blocks password login for Google-only users (`google_id` present)
+    - Verifies password against Argon2 hash
+    - Generates JWT and updates `token` cookie
+    - Returns normalized `ApiResponse<AuthUserResponse>`
+
+- `POST /logout`
+    - Clears auth cookie (`token`)
+    - Returns normalized `ApiResponse<()>`
+
+- `GET /me`
+    - Protected route using `AuthUser` extractor (`src/middleware/auth.rs`)
+    - Reads and verifies JWT from cookie
+    - Loads user from DB
+    - Returns current authenticated user profile in `ApiResponse<AuthUserResponse>`
+
+## 🧰 `src/utils` Folder and Use Cases
+
+This project is educational, so the utility layer is intentionally explicit and reusable for future modules (tasks, projects, workspaces).
+
+| File                     | What it does                                                                                                                         | Why it matters for future features                            |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
+| `src/utils/response.rs`  | Defines `ApiResponse<T>` with `success`, `status_code`, `message`, `data`                                                            | Gives every endpoint a predictable success payload shape      |
+| `src/utils/api_error.rs` | Defines `ApiError` (`BadRequest`, `Unauthorized`, `NotFound`, `Conflict`, `InternalServerError`) and converts it into HTTP responses | Centralizes error-to-status mapping so controllers stay clean |
+| `src/utils/jwt.rs`       | Generates and verifies JWT claims (`sub`, `exp`)                                                                                     | Reusable token logic for any protected resource               |
+| `src/utils/hash.rs`      | Hashes passwords (Argon2 + random salt) and verifies passwords                                                                       | Security best practice reusable for account/password features |
+| `src/utils/mod.rs`       | Exports utility modules and formats validator errors into readable strings                                                           | Keeps validation messages user-friendly and consistent        |
+
+## 🔄 How Response + Error + JWT Work Together
+
+1. **Request enters route** (`src/routes/auth_routes.rs`) and is handled by `auth_controller`.
+2. **DTO validation runs** (`validator` crate in `src/dtos/auth_dto.rs`).
+3. **If validation fails**, controller maps errors using `format_validation_errors(...)` and returns `ApiError::BadRequest(...)`.
+4. **If business/database logic fails**, controller returns another `ApiError` variant.
+5. **`ApiError` implements `IntoResponse`**, so Axum converts it into a standardized HTTP error payload.
+6. **If success**, controller returns `Json(ApiResponse<T>)` from `src/utils/response.rs`.
+7. **For protected routes**, `AuthUser` middleware extractor in `src/middleware/auth.rs` reads `token` from cookies, verifies JWT using `utils/jwt.rs`, fetches the user from DB, and injects authenticated `User` into the handler.
+
+## 📦 Response Format (Current)
+
+Success shape:
+
+```json
+{
+	"success": true,
+	"status_code": 200,
+	"message": "User logged in successfully",
+	"data": {
+		"id": "uuid",
+		"email": "user@example.com",
+		"name": "User"
+	}
+}
+```
+
+Error shape:
+
+```json
+{
+	"success": false,
+	"status_code": 400,
+	"message": "email: Invalid email format, password: Password must be between 6 and 12 characters",
+	"data": null
+}
+```
+
+## 🍪 JWT Cookie Behavior
+
+- Cookie name: `token`
+- `HttpOnly`: enabled (protects token from client-side JS access)
+- `SameSite`: `Lax`
+- `Secure`: enabled when `DEV_MODE != development`
+- Signing secret: `JWT_SECRET` from environment
+
+This makes auth state server-trusted and easy to consume from browser clients.
 
 ## database migrations
 

public/table.js

@@ -18,6 +18,13 @@ const endpoints = [
 		description: 'Login with email and password',
 		status: 'active',
 	},
+	,
+	{
+		endpoint: '/api/v1/auth/logout',
+		method: 'POST',
+		description: 'Logout the current user',
+		status: 'active',
+	},
 	{
 		endpoint: '/api/v1/auth/google',
 		method: 'GET',

src/controllers/auth_controller.rs

@@ -5,8 +5,11 @@ use validator::Validate;
 use crate::{
     config::AppState,
     dtos::auth_dto::{AuthUserResponse, LoginUserDto, RegisterUserDto},
+    middleware::auth::AuthUser,
     models::User,
     utils::{
+        api_error::ApiError,
+        format_validation_errors,
         hash::{hash_password, verify_password},
         jwt::generate_jwt,
         response::ApiResponse,
@@ -23,43 +26,37 @@ pub async fn register_user(
     State(state): State<AppState>,
     cookies: Cookies,
     Json(payload): Json<RegisterUserDto>,
-) -> Result<Json<ApiResponse<AuthUserResponse>>, StatusCode> {
+) -> Result<Json<ApiResponse<AuthUserResponse>>, ApiError> {
     // logging the registration attempt with the email (but not the password)
     tracing::info!("Attempting to register user with email: {}", payload.email);
 
     // Validate the input payload
-    payload.validate().map_err(|_| StatusCode::BAD_REQUEST)?;
+    payload.validate().map_err(|e| {
+        let error_messages = format_validation_errors(&e);
+        tracing::error!("Validation errors: {}", error_messages);
+        ApiError::BadRequest(error_messages)
+    })?;
 
     // comparing password and confirm_password
     if payload.password != payload.confirm_password {
-        return Ok(Json(ApiResponse::new(
-            false,
-            StatusCode::BAD_REQUEST,
-            "Passwords do not match",
-            None,
-        )));
+        return Err(ApiError::BadRequest("Passwords do not match".into()));
     }
 
     // Check if the email is already registered
     let existing_user = sqlx::query_as::<_, User>("SELECT * FROM users WHERE email = $1")
         .bind(&payload.email)
         .fetch_optional(&state.db)
         .await
-        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;
+        .map_err(|_| ApiError::InternalServerError("Failed to fetch user".into()))?;
 
     // If the email is already registered, return a conflict error
     if existing_user.is_some() {
-        return Ok(Json(ApiResponse::new(
-            false,
-            StatusCode::CONFLICT,
-            "User is already registered",
-            None,
-        )));
+        return Err(ApiError::Conflict("User is already registered".into()));
     }
 
     // Hash the password
-    let hashed_password =
-        hash_password(&payload.password).map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;
+    let hashed_password = hash_password(&payload.password)
+        .map_err(|_| ApiError::InternalServerError("Failed to hash password".into()))?;
 
     // Store the user in the database and return the created user
     let user = sqlx::query_as::<_, User>(
@@ -70,11 +67,11 @@ pub async fn register_user(
     .bind(&hashed_password)
     .fetch_one(&state.db)
     .await
-    .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;
+    .map_err(|_| ApiError::InternalServerError("Failed to create user".into()))?;
 
     // Generate a JWT token for the user
     let token = generate_jwt(user.id, &state.env_config.jwt_secret)
-        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;
+        .map_err(|_| ApiError::InternalServerError("Failed to generate JWT token".into()))?;
 
     // Set the JWT token as an HTTP-only cookie
     cookies.add(
@@ -112,41 +109,35 @@ pub async fn login_user(
     State(state): State<AppState>,
     cookies: Cookies,
     Json(payload): Json<LoginUserDto>,
-) -> Result<Json<ApiResponse<AuthUserResponse>>, StatusCode> {
+) -> Result<Json<ApiResponse<AuthUserResponse>>, ApiError> {
     // logging the login attempt with the email (but not the password)
     tracing::info!("Attempting to login user with email: {}", payload.email);
 
     // Validate the input payload
-    payload.validate().map_err(|_| StatusCode::BAD_REQUEST)?;
+    payload.validate().map_err(|e| {
+        let error_messages = format_validation_errors(&e);
+        tracing::error!("Validation errors: {}", error_messages);
+        ApiError::BadRequest(error_messages)
+    })?;
 
     // Check if the user exists in the database
     let user = sqlx::query_as::<_, User>("SELECT * FROM users WHERE email = $1")
         .bind(&payload.email)
         .fetch_optional(&state.db)
         .await
-        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;
+        .map_err(|_| ApiError::InternalServerError("Failed to fetch user".into()))?;
 
     // If the user does not exist, return an unauthorized error
     let user = match user {
         Some(user) => user,
         None => {
-            return Ok(Json(ApiResponse::new(
-                false,
-                StatusCode::UNAUTHORIZED,
-                "User does not exist",
-                None,
-            )));
+            return Err(ApiError::NotFound("User does not exist".into()));
         }
     };
 
     // check if the user has a google_id, if so, they should not be able to login with email and password
     if user.google_id.is_some() {
-        return Ok(Json(ApiResponse::new(
-            false,
-            StatusCode::UNAUTHORIZED,
-            "Please login with Google",
-            None,
-        )));
+        return Err(ApiError::Unauthorized("Please login with google".into()));
     }
 
     // check if the user has a password_hash, if not, they should not be able to login with email and password
@@ -157,30 +148,20 @@ pub async fn login_user(
                 "User with email {} does not have a password hash",
                 payload.email
             );
-            return Ok(Json(ApiResponse::new(
-                false,
-                StatusCode::UNAUTHORIZED,
-                "Invalid Credentials",
-                None,
-            )));
+            return Err(ApiError::NotFound("Password not found".into()));
         }
     };
 
     // Verify the password
     let password_valid = verify_password(&payload.password, password_hash);
     // If the password is incorrect, return an unauthorized error
     if !password_valid {
-        return Ok(Json(ApiResponse::new(
-            false,
-            StatusCode::UNAUTHORIZED,
-            "Invalid Credentials",
-            None,
-        )));
+        return Err(ApiError::Unauthorized("Invalid Credentials".into()));
     }
 
     // Generate a JWT token for the user
     let token = generate_jwt(user.id, &state.env_config.jwt_secret)
-        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;
+        .map_err(|_| ApiError::InternalServerError("Failed to generate JWT token".into()))?;
 
     // Set the JWT token as an HTTP-only cookie
     cookies.add(
@@ -213,7 +194,7 @@ pub async fn login_user(
  * Logs out the current user by removing the JWT token cookie. Returns a JSON response indicating that the user has been logged out successfully.
  * Path: POST /api/v1/auth/logout
  */
-pub async fn logout_user(cookies: Cookies) -> Result<Json<ApiResponse<()>>, StatusCode> {
+pub async fn logout_user(cookies: Cookies) -> Result<Json<ApiResponse<()>>, ApiError> {
     // logging the logout attempt
     tracing::info!("Attempting to logout user");
 
@@ -234,3 +215,26 @@ pub async fn logout_user(cookies: Cookies) -> Result<Json<ApiResponse<()>>, Stat
         None,
     )))
 }
+
+/**
+ * Retrieves the authenticated user's information. Requires the user to be authenticated with a valid JWT token in the cookies. Returns a JSON response with the user's information if authentication is successful, or an appropriate error message if authentication fails.
+ * Path: GET /api/v1/auth/me
+ */
+pub async fn get_me(
+    AuthUser(user): AuthUser,
+) -> Result<Json<ApiResponse<AuthUserResponse>>, ApiError> {
+    Ok(Json(ApiResponse::new(
+        true,
+        StatusCode::OK,
+        "Authenticated user",
+        Some(AuthUserResponse {
+            id: user.id,
+            email: user.email,
+            name: user.name,
+            google_id: user.google_id,
+            avatar_url: user.avatar_url,
+            created_at: user.created_at,
+            updated_at: user.updated_at,
+        }),
+    )))
+}

src/dtos/auth_dto.rs

@@ -5,25 +5,39 @@ use validator::Validate;
 
 #[derive(Debug, Deserialize, Validate)]
 pub struct RegisterUserDto {
-    #[validate(length(min = 1))]
+    #[validate(length(min = 1, message = "Name cannot be empty"))]
     pub name: String,
 
-    #[validate(email)]
+    #[validate(
+        email(message = "Invalid email format"),
+        length(min = 1, message = "Email cannot be empty")
+    )]
     pub email: String,
 
-    #[validate(length(min = 6, max = 12))]
+    #[validate(length(
+        min = 6,
+        max = 12,
+        message = "Password must be between 6 and 12 characters"
+    ))]
     pub password: String,
 
-    #[validate(length(min = 6, max = 12))]
+    #[validate(must_match(other = "password", message = "Passwords do not match"))]
     pub confirm_password: String,
 }
 
 #[derive(Debug, Deserialize, Validate)]
 pub struct LoginUserDto {
-    #[validate(email)]
+    #[validate(
+        email(message = "Invalid email format"),
+        length(min = 1, message = "Email cannot be empty")
+    )]
     pub email: String,
 
-    #[validate(length(min = 6, max = 12))]
+    #[validate(length(
+        min = 6,
+        max = 12,
+        message = "Password must be between 6 and 12 characters"
+    ))]
     pub password: String,
 }