Merge branch 'main' into shreyanshi_joi

Author: Shreyanshi210205

API_DOCUMENTATION.md

@@ -0,0 +1,229 @@
+# 🔐 RBAC API Documentation
+
+## Authentication Endpoints
+
+### POST /api/auth/register
+Register a new user in the system.
+
+**Request Body:**
+```json
+{
+  "username": "string",
+  "email": "string",
+  "fullname": "string",
+  "password": "string"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "User registered successfully",
+  "user": {
+    "id": "user_id",
+    "username": "username",
+    "email": "email",
+    "role": "User"
+  }
+}
+```
+
+### POST /api/auth/login
+Authenticate user and return access and refresh tokens.
+
+**Request Body:**
+```json
+{
+  "email": "string",
+  "password": "string"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Login successful",
+  "accessToken": "jwt_access_token",
+  "refreshToken": "jwt_refresh_token",
+  "user": {
+    "id": "user_id",
+    "username": "username",
+    "email": "email",
+    "fullname": "fullname",
+    "role": "User"
+  }
+}
+```
+
+### POST /api/auth/refresh
+Refresh access token using refresh token.
+
+**Request Body:**
+```json
+{
+  "refreshToken": "jwt_refresh_token"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Token refreshed successfully",
+  "accessToken": "new_jwt_access_token",
+  "user": {
+    "id": "user_id",
+    "username": "username",
+    "email": "email",
+    "fullname": "fullname",
+    "role": "User"
+  }
+}
+```
+
+### POST /api/auth/logout
+Logout user and invalidate refresh token.
+
+**Request Body:**
+```json
+{
+  "refreshToken": "jwt_refresh_token"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Logged out successfully"
+}
+```
+
+## Role Management Endpoints
+
+### GET /api/roles
+Get all roles (requires authentication).
+
+**Headers:**
+```
+Authorization: Bearer <access_token>
+```
+
+**Response:**
+```json
+[
+  {
+    "_id": "role_id",
+    "name": "Admin",
+    "permissions": [
+      {
+        "_id": "permission_id",
+        "name": "Manage Users",
+        "description": "Admin can manage users"
+      }
+    ]
+  }
+]
+```
+
+### POST /api/roles
+Create a new role (requires authentication).
+
+**Headers:**
+```
+Authorization: Bearer <access_token>
+```
+
+**Request Body:**
+```json
+{
+  "name": "string",
+  "permissions": ["permission_id_1", "permission_id_2"]
+}
+```
+
+## Permission Management Endpoints
+
+### GET /api/permissions
+Get all permissions (requires authentication).
+
+**Headers:**
+```
+Authorization: Bearer <access_token>
+```
+
+### POST /api/permissions
+Create a new permission (requires authentication).
+
+**Headers:**
+```
+Authorization: Bearer <access_token>
+```
+
+**Request Body:**
+```json
+{
+  "name": "string",
+  "description": "string"
+}
+```
+
+## RBAC Test Endpoints
+
+### GET /api/rbac-test/admin-only
+Test endpoint for Admin role only.
+
+**Headers:**
+```
+Authorization: Bearer <access_token>
+```
+
+**Response:**
+```json
+{
+  "message": "Welcome, Admin"
+}
+```
+
+### GET /api/rbac-test/user-only
+Test endpoint for User role only.
+
+**Headers:**
+```
+Authorization: Bearer <access_token>
+```
+
+**Response:**
+```json
+{
+  "message": "Welcome, User"
+}
+```
+
+## Error Responses
+
+All endpoints return consistent error responses:
+
+```json
+{
+  "success": false,
+  "message": "Error description"
+}
+```
+
+Common HTTP status codes:
+- `400` - Bad Request
+- `401` - Unauthorized
+- `403` - Forbidden
+- `404` - Not Found
+- `500` - Internal Server Error
+
+## Security Features
+
+- **JWT Access Tokens**: Short-lived (1 day) for API access
+- **Refresh Tokens**: Long-lived (7 days) for token renewal
+- **Password Hashing**: bcrypt with salt rounds
+- **Role-Based Access Control**: Granular permissions
+- **Token Invalidation**: Secure logout mechanism

README.md

@@ -12,6 +12,7 @@ This project is developed and maintained under **Opcode, IIIT Bhagalpur** 🚀.
 ## 🌟 Features
 
 - ✅ User authentication with **JWT**
+- ✅ **Refresh Token mechanism** for persistent login
 - ✅ Secure password hashing (**bcrypt**)
 - ✅ Role-based access (Admin, User, Moderator, etc.)
 - ✅ Permission-based middleware for fine-grained access
@@ -59,10 +60,19 @@ npm install
 
 ### 3️⃣ Setup Environment
 
-```
+Create a `.env` file in the root directory with the following variables:
+
+```env
+# Server Configuration
 PORT=5000
+
+# Database Configuration
 MONGO_URI=mongodb://localhost:27017/rbac
 JWT_SECRET=your-secret-key
+RESEND_API_KEY=your-resend-api-key
+
+🔑 Note: The RESEND_API_KEY can be obtained by creating an account on Resend Mail
+ and generating an API key.
 ```
 
 ### 4️⃣ Run the Project
@@ -71,6 +81,76 @@ JWT_SECRET=your-secret-key
 npm run dev
 ```
 
+### 5️⃣ Seed the Database
+
+Before using the application, seed the database with default roles and permissions:
+
+```bash
+node src/seed/seedRoles.js
+```
+
+---
+
+## 🔌 API Endpoints
+
+### Authentication Endpoints
+
+| Method | Endpoint | Description | Body |
+|--------|----------|-------------|------|
+| POST | `/api/auth/register` | Register a new user | `{username, email, fullname, password}` |
+| POST | `/api/auth/login` | Login user | `{email, password}` |
+| POST | `/api/auth/refresh` | Refresh access token | `{refreshToken}` |
+| POST | `/api/auth/logout` | Logout user | `{refreshToken}` |
+
+### Role Management Endpoints
+
+| Method | Endpoint | Description | Auth Required |
+|--------|----------|-------------|---------------|
+| GET | `/api/roles` | Get all roles | Yes |
+| POST | `/api/roles` | Create new role | Yes |
+| GET | `/api/roles/:id` | Get role by ID | Yes |
+| PUT | `/api/roles/:id` | Update role | Yes |
+| DELETE | `/api/roles/:id` | Delete role | Yes |
+| PUT | `/api/roles/:id/permissions` | Assign permissions to role | Yes |
+
+### Permission Management Endpoints
+
+| Method | Endpoint | Description | Auth Required |
+|--------|----------|-------------|---------------|
+| GET | `/api/permissions` | Get all permissions | Yes |
+| POST | `/api/permissions` | Create new permission | Yes |
+| GET | `/api/permissions/:id` | Get permission by ID | Yes |
+| PUT | `/api/permissions/:id` | Update permission | Yes |
+| DELETE | `/api/permissions/:id` | Delete permission | Yes |
+
+### RBAC Test Endpoints
+
+| Method | Endpoint | Description | Auth Required |
+|--------|----------|-------------|---------------|
+| GET | `/api/rbac-test/admin-only` | Admin only access | Yes (Admin role) |
+| GET | `/api/rbac-test/user-only` | User only access | Yes (User role) |
+
+---
+
+## 🔄 Authentication Flow
+
+### Login Flow
+1. User sends credentials to `/api/auth/login`
+2. Server validates credentials
+3. Server generates both access token (short-lived) and refresh token (long-lived)
+4. Both tokens are returned to client
+
+### Token Refresh Flow
+1. When access token expires, client sends refresh token to `/api/auth/refresh`
+2. Server validates refresh token
+3. Server generates new access token
+4. New access token is returned to client
+
+### Logout Flow
+1. Client sends refresh token to `/api/auth/logout`
+2. Server invalidates the refresh token in database
+3. Client should discard both tokens
+
 ---
 
 ### 🔄 System Flows