Authentication API

Relevant source files - controllers/auth.controller.js - controllers/user.controller.js - middlewares/auth.middleware.js - routes/auth.routes.js

The Authentication API provides endpoints for user registration, session establishment, and termination. It utilizes JSON Web Tokens (JWT) for stateless authentication, bcryptjs for secure password hashing, and MongoDB sessions to ensure atomicity during user creation.

Authentication Endpoints

The system exposes three primary routes under the /api/v1/auth prefix routes/auth.routes.js8-79

Method	Endpoint	Description
POST	/sign-up	Registers a new user and returns a JWT.
POST	/sign-in	Validates credentials and returns a JWT.
POST	/sign-out	Acknowledges session termination (client-side handled).

Sources:routes/auth.routes.js1-81controllers/auth.controller.js1-111

---

Implementation Details

User Sign-Up Flow

The signUp controller implements a robust registration process using MongoDB transactions to ensure data integrity controllers/auth.controller.js7-58

1. Transaction Initialization: A new Mongoose session is started to wrap the creation logic controllers/auth.controller.js8-9
2. Duplicate Check: The system queries the User model by email to prevent duplicate registrations controllers/auth.controller.js14-20
3. Password Hashing: Passwords are salted and hashed using bcrypt.genSalt(10) before storage controllers/auth.controller.js22-23
4. Atomic Creation: The user is created within the session context controllers/auth.controller.js25-36
5. Token Issuance: A JWT is generated containing the userId payload, signed with JWT_SECRETcontrollers/auth.controller.js38-40
6. Commit: The transaction is committed, and the session is closed controllers/auth.controller.js42-43

User Sign-In Flow

The signIn controller validates user identity against stored credentials controllers/auth.controller.js60-95

1. User Retrieval: Fetches the user document by email controllers/auth.controller.js64
2. Credential Validation: Compares the provided plaintext password with the stored hash using bcrypt.compare()controllers/auth.controller.js72
3. Session Generation: Upon successful validation, a new JWT is issued controllers/auth.controller.js80-82

Sign-Out Pattern

Because the API uses stateless JWTs, the signOut controller does not invalidate tokens on the server controllers/auth.controller.js97-106 The responsibility lies with the client to delete the token from local storage or cookies controllers/auth.controller.js99-101

Sources:controllers/auth.controller.js7-111config/env.js5

---

Data Flow and Security Logic

The following diagram illustrates the interaction between the authRouter, the authController, and the security utilities during the signUp process.

Sign-Up Logic Flow

sequenceDiagram
    participant C as "Client"
    participant R as "authRouter"
    participant AC as "authController.signUp"
    participant B as "bcryptjs"
    participant M as "User Model (MongoDB)"
    participant J as "jsonwebtoken"
    C->>R: "POST /api/v1/auth/sign-up"
    R->>AC: "signUp(req, res, next)"
    AC->>M: "User.findOne({ email })"
    M-->>AC: "null (User not found)"
    AC->>B: "genSalt(10) & hash(password)"
    B-->>AC: "hashedPassword"
    AC->>M: "User.create([...], { session })"
    M-->>AC: "newUser Object"
    AC->>J: "sign({ userId }, JWT_SECRET)"
    J-->>AC: "token"
    AC-->>C: "201 Created (token, user)"

Sources:controllers/auth.controller.js7-58routes/auth.routes.js36

---

JWT Authentication Middleware

To protect sensitive routes, the authorize middleware validates the Authorization header middlewares/auth.middleware.js5-35

• Extraction: It expects a Bearer <token> format middlewares/auth.middleware.js9-10
• Verification: Uses jwt.verify with the system's JWT_SECRETmiddlewares/auth.middleware.js17
• Context Population: If valid, it retrieves the user from the database (excluding the password field) and attaches it to req.user for subsequent handlers middlewares/auth.middleware.js19-26

Auth Guard Architecture

[Flowchart Diagram]

Sources:middlewares/auth.middleware.js1-38

---

Request/Response Shapes

POST /api/v1/auth/sign-up

Request Bodyroutes/auth.routes.js17-27

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "securepassword123"
}

Response (201 Created)controllers/auth.controller.js45-52

{
  "success": true,
  "message": "User Created Successfully",
  "data": {
    "token": "eyJhbG...",
    "user": {
      "_id": "67b...",
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

POST /api/v1/auth/sign-in

Request Bodyroutes/auth.routes.js49-56

{
  "email": "john@example.com",
  "password": "securepassword123"
}

Response (200 OK)controllers/auth.controller.js84-91

{
  "success": true,
  "message": "User Signed In Successfully",
  "data": {
    "token": "eyJhbG...",
    "user": {
      "_id": "67b...",
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

Sources:routes/auth.routes.js6-79controllers/auth.controller.js7-111