cca-auth-module 0.1.86 → 0.1.88

package/README.md

@@ -8,131 +8,380 @@ This module provides endpoints and methods for user authentication, including lo
 
 ## Endpoints
 
-### 1. **Login**
-
-- **URL:** `/auth/login`
-- **Method:** `POST`
-- **Description:** Authenticates a user and returns tokens or authentication data.
-- **Body Parameters:**
-  - `adminPassword` (optional, string): An additional password if admin access is required.
-  - Other properties as defined in `LoginDTO` (e.g., email, password, etc.).
-- **Success Response:**
-  - **Code:** `201 Created`
-  - **Content:** JSON object with authentication result (tokens, user details, etc.).
+# Auth API Documentation
 
 ---
 
-### 2. **Logout**
+## 1. Login
 
-- **URL:** `/auth/logout/:id`
-- **Method:** `POST` or `GET` (typically POST)
-- **Description:** Logs out the user by invalidating the active session or token.
-- **URL Parameters:**
-  - `id` (string): The identifier for the user/session.
-- **Success Response:**
-  - **Code:** `200 OK`
-  - **Content:** JSON message confirming successful logout:
-    ```json
-    { "message": "Logged out successfully" }
-    ```
+**POST** `/auth/login`
+
+### Request Body
+
+```json
+{
+  "email": "user@example.com",
+  "password": "yourPassword"
+}
+```
+
+### Success Response
+
+**Status:** `200 OK`
+
+```json
+{
+  "success": true,
+  "message": "Login successful",
+  "data": {
+    "accessToken": "string",
+    "userId": "string",
+    "expiresAt": "2025-08-06T12:00:00.000Z",
+    "auth": {
+      "hasAccessToken": true,
+      "enable": false,
+      "status": "BASIC_AUTH",
+      "verified": false
+    }
+  },
+  "meta": {
+    "timestamp": "2025-08-06T11:59:59.999Z"
+  }
+}
+```
+
+---
+
+## 2. Admin Login
+
+**POST** `/auth/admin-login`
+
+### Request Body
+
+```json
+{
+  "email": "admin@example.com",
+  "password": "adminPassword",
+  "adminPassword": "superSecretAdminPassword"
+}
+```
+
+### Success Response
+
+**Status:** `201 Created`
+
+```json
+{
+  "success": true,
+  "message": "Admin login successful",
+  "data": {
+    "message": "Admin authenticated",
+    "auth": {
+      "hasAccessToken": true,
+      "enable": false,
+      "status": "BASIC_AUTH",
+      "verified": false
+    }
+  }
+}
+```
+
+---
+
+## 3. Logout
+
+**POST** `/auth/logout`
+
+### Request Body
+
+```json
+{
+  "id": "userId"
+}
+```
+
+### Success Response
+
+**Status:** `200 OK`
+
+```json
+{
+  "success": true,
+  "message": "Logout successful",
+  "data": {
+    "auth": {
+      "hasAccessToken": false,
+      "enable": false,
+      "status": "LOGGED_OUT",
+      "verified": false
+    }
+  }
+}
+```
+
+---
+
+## 4. Register
+
+**POST** `/auth/register`
+
+### Request Body
+
+```json
+{
+  "email": "newuser@example.com",
+  "name": "New User",
+  "password": "userPassword",
+  "role": "user",
+  "adminPassword": "optionalAdminPassword"
+}
+```
+
+### Success Response
+
+**Status:** `200 OK`
+
+```json
+{
+  "success": true,
+  "message": "Registration successful",
+  "data": {
+    "auth": {
+      "hasAccessToken": false,
+      "enable": false,
+      "status": "REGISTERED",
+      "verified": false
+    }
+  },
+  "meta": {
+    "status": true
+  }
+}
+```
 
 ---
 
-### 3. **Register**
-
-- **URL:** `/auth/register`
-- **Method:** `POST`
-- **Description:** Registers a new user.
-- **Body Parameters:**
-  - `email` (string): The user's email.
-  - `name` (string): The user's name.
-  - `password` (string): The user's password.
-  - `role` (string): The role assigned to the user.
-  - `adminPassword` (optional, string): Additional admin password if required.
-- **Success Response:**
-  - **Code:** `201 Created`
-  - **Content:** May return a success message or the created user details.
-- **Note:** The registration endpoint does not directly return a JSON response on success in the given implementation. Consider adding a response message if needed.
+## 5. Refresh Token
+
+**POST** `/auth/refresh-token`
+
+### Request Body
+
+```json
+{
+  "refreshToken": "yourRefreshToken"
+}
+```
+
+### Success Response
+
+**Status:** `200 OK`
+
+```json
+{
+  "success": true,
+  "message": "Token refreshed successfully",
+  "data": {
+    "accessToken": "newAccessToken",
+    "refreshToken": "newRefreshToken",
+    "auth": {
+      "hasAccessToken": true,
+      "enable": false,
+      "status": "BASIC_AUTH",
+      "verified": false
+    }
+  }
+}
+```
 
 ---
 
-### 4. **Refresh Token**
+## 6. 2FA Setup
+
+**POST** `/auth/2fa/setup`
 
-- **URL:** `/auth/refresh-token`
-- **Method:** `POST`
-- **Description:** Generates a new authentication token using a refresh token.
-- **Body Parameters:**
-  - `refreshToken` (string): The refresh token provided to the user.
-- **Success Response:**
-  - **Code:** `200 OK`
-  - **Content:** JSON object containing the new token(s).
+### Headers
+
+```
+Authorization: Bearer <accessToken>
+```
+
+### Request Body
+
+None
+
+### Success Response
+
+**Status:** `200 OK`
+
+```json
+{
+  "success": true,
+  "message": "2FA setup successful",
+  "data": {
+    "qrCode": "data:image/png;base64,...",
+    "auth": {
+      "hasAccessToken": true,
+      "enable": false,
+      "status": "NEEDS_SETUP"
+    }
+  },
+  "meta": {
+    "nextStep": "Scan the QR code and enter your first code to verify",
+    "redirectTo": "/2fa-enable"
+  }
+}
+```
 
 ---
 
-### 5. **Verify Token**
+## 7. Enable 2FA
+
+**POST** `/auth/2fa/enable`
 
-- **Description:** Verifies the validity of a provided token.
-- **Usage:** This is a helper method (not an HTTP endpoint) that accepts a token string and returns the decoded token payload.
-- **Method Signature:**
-  ```typescript
-  verifyToken(token: string): Promise<IDecodedToken>
-  ```
+### Headers
+
+```
+Authorization: Bearer <accessToken>
+```
+
+### Request Body
+
+```json
+{
+  "userId": "userId",
+  "token": "2faToken"
+}
+```
+
+### Success Response
+
+**Status:** `200 OK`
+
+```json
+{
+  "success": true,
+  "message": "2FA enabled successfully",
+  "data": {
+    "isEnabled": true,
+    "enabledAt": "2025-08-06T12:00:00.000Z",
+    "auth": {
+      "hasAccessToken": true,
+      "enable": true,
+      "status": "PENDING_VERIFICATION"
+    }
+  },
+  "meta": {
+    "nextStep": "Proceed to verify with a valid 2FA token",
+    "redirectTo": "/verify-2fa"
+  }
+}
+```
 
 ---
 
-## Usage Example
+## 8. Verify 2FA
 
-Below is an example of integrating the Auth Module into an Express application:
+**POST** `/auth/2fa/verify`
 
-```typescript
-import express from 'express';
-import { AuthController, authConfig, createAuthContainer } from 'path-to-your-auth-module';
-import { ConfigSource } from 'path-to-your-domain-interfaces';
+### Request Body
 
-const app = express();
-app.use(express.json());
+```json
+{
+  "userId": "userId",
+  "token": "2faVerificationToken"
+}
+```
 
-// Configure auth module with your config source
-const configSource: ConfigSource = {
-  accessTokenSecret: process.env.ACCESS_TOKEN_SECRET || 'default-access-secret',
-  refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET || 'default-refresh-secret',
-  accessTokenExpiry: parseInt(process.env.ACCESS_TOKEN_EXPIRY || '3600'),
-  refreshTokenExpiry: parseInt(process.env.REFRESH_TOKEN_EXPIRY || '86400'),
-  adminSecretPassword: process.env.ADMIN_SECRET_PASSWORD || 'default-admin-password'
-};
+### Success Response
+
+**Status:** `200 OK`
+
+```json
+{
+  "success": true,
+  "message": "2FA verification successful",
+  "data": {
+    "token": "accessToken",
+    "refreshToken": "refreshToken",
+    "user": {
+      "id": "userId",
+      "email": "user@example.com",
+      "name": "User Name",
+      "role": "user"
+    },
+    "auth": {
+      "hasAccessToken": true,
+      "enable": true,
+      "status": "FULL_AUTH",
+      "verified": true
+    }
+  },
+  "meta": {
+    "recommendation": "You're fully authenticated",
+    "redirectTo": "/"
+  }
+}
+```
 
-// Initialize auth configuration
-authConfig(configSource);
+---
+
+## 9. Disable 2FA
 
-// Create a container and resolve the AuthController
-const container = createAuthContainer();
-const authController: AuthController = container.resolve(AuthController);
+**POST** `/auth/2fa/disable`
 
-// Define routes for authentication
-app.post('/auth/login', authController.login);
-app.post('/auth/logout/:id', authController.logout);
-app.post('/auth/register', authController.register);
-app.post('/auth/refresh-token', authController.refreshToken);
+### Headers
 
-// Error handling middleware
-app.use((err, req, res, next) => {
-  res.status(500).json({ error: err.message });
-});
+```
+Authorization: Bearer <accessToken>
+```
+
+### Request Body
+
+```json
+{
+  "token": "current2faToken"
+}
+```
 
-app.listen(3000, () => console.log('Server running on port 3000'));
+### Success Response
+
+**Status:** `200 OK`
+
+```json
+{
+  "success": true,
+  "message": "2FA disabled successfully",
+  "data": {
+    "disabledAt": "2025-08-06T12:00:00.000Z",
+    "auth": {
+      "hasAccessToken": true,
+      "enable": false,
+      "status": "BASIC_AUTH",
+      "verified": false
+    }
+  },
+  "meta": {
+    "securityNote": "Account now relies only on password. Re-enable 2FA for better security.",
+    "redirectTo": "/login"
+  }
+}
 ```
 
 ---
 
-## Error Handling
+## Notes
 
-The controller methods throw custom errors such as `ValidationError` and `NotFoundError` when necessary. Ensure your Express application includes error-handling middleware to properly handle these exceptions:
+- All endpoints returning tokens require secure HTTPS connections.
+- 2FA setup, enable, verify, and disable require authentication with a valid access token (sent in the Authorization header).
+- Request bodies use DTOs as defined in the controller (LoginDTO, RegisterDTO, ITwoFactorEnable, ITwoFactorVerify, etc.).
+- Error responses will follow the format:
 
-```typescript
-app.use((err, req, res, next) => {
-  // Optionally log the error here
-  res.status(500).json({ error: err.message });
-});
+```json
+{
+  "success": false,
+  "error": "Error message"
+}
 ```
 
 ---

package/dist/index.js

@@ -741,7 +741,10 @@ var AUTH_STATUS = {
   BASIC_AUTH: "basic_auth",
   NEEDS_SETUP: "needs_setup",
   PENDING_VERIFICATION: "pending_verification",
-  FULL_AUTH: "full_auth"
+  FULL_AUTH: "full_auth",
+  LOGGED_OUT: "logged_out",
+  REGISTERED: "registered",
+  TOKEN_REFRESHED: "token_refreshed"
 };
 var MESSAGES = {
   LOGIN_SUCCESS: "Login successful",
@@ -762,11 +765,20 @@ var _AuthController = class _AuthController {
       try {
         const loginDTO = req.body;
         const result = await this.loginUseCase.execute(loginDTO);
+        const twoFactorEnabled = result.enabled ?? false;
         const loginData = {
           accessToken: result.accessToken,
           userId: result.id,
           expiresAt: result.expiresAt,
-          enabled: result.enabled
+          auth: this.createAuthData(
+            true,
+            // hasAccessToken
+            twoFactorEnabled,
+            // enable (2FA enabled status)
+            twoFactorEnabled ? AUTH_STATUS.PENDING_VERIFICATION : AUTH_STATUS.BASIC_AUTH,
+            false
+            // verified - always false for basic login
+          )
         };
         this.sendResponse(res, HTTP_STATUS.OK, MESSAGES.LOGIN_SUCCESS, loginData);
       } catch (error) {
@@ -780,7 +792,20 @@ var _AuthController = class _AuthController {
           throw new ForbiddenError("Admin password is required");
         }
         const result = await this.adminLoginUseCase.execute(loginDTO, adminPassword);
-        this.sendResponse(res, HTTP_STATUS.CREATED, MESSAGES.ADMIN_LOGIN_SUCCESS, result);
+        const adminLoginData = {
+          message: result,
+          // Assuming result is a string message
+          auth: this.createAuthData(
+            true,
+            // hasAccessToken
+            false,
+            // enable - assuming 2FA not enabled for admin login
+            AUTH_STATUS.BASIC_AUTH,
+            false
+            // verified
+          )
+        };
+        this.sendResponse(res, HTTP_STATUS.CREATED, MESSAGES.ADMIN_LOGIN_SUCCESS, adminLoginData);
       } catch (error) {
         next(error);
       }
@@ -788,7 +813,18 @@ var _AuthController = class _AuthController {
     this.logout = /* @__PURE__ */ __name(async (req, res, next) => {
       try {
         await this.logoutUseCase.execute(req.body.id);
-        this.sendResponse(res, HTTP_STATUS.OK, MESSAGES.LOGOUT_SUCCESS);
+        const logoutData = {
+          auth: this.createAuthData(
+            false,
+            // hasAccessToken - no token after logout
+            false,
+            // enable - 2FA status irrelevant after logout
+            AUTH_STATUS.LOGGED_OUT,
+            false
+            // verified - false after logout
+          )
+        };
+        this.sendResponse(res, HTTP_STATUS.OK, MESSAGES.LOGOUT_SUCCESS, logoutData);
       } catch (error) {
         next(error);
       }
@@ -797,11 +833,22 @@ var _AuthController = class _AuthController {
       try {
         const { email, name, password, role, adminPassword } = req.body;
         await this.registerUseCase.execute(email, name, password, role, adminPassword);
+        const registerData = {
+          auth: this.createAuthData(
+            false,
+            // hasAccessToken - no token after registration
+            false,
+            // enable - 2FA not enabled for new users
+            AUTH_STATUS.REGISTERED,
+            false
+            // verified - false after registration
+          )
+        };
         this.sendResponse(
           res,
           HTTP_STATUS.OK,
           MESSAGES.REGISTER_SUCCESS,
-          null,
+          registerData,
           { status: true }
         );
       } catch (error) {
@@ -812,7 +859,20 @@ var _AuthController = class _AuthController {
       try {
         const { refreshToken } = req.body;
         const result = await this.refreshTokenUseCase.execute(refreshToken);
-        this.sendResponse(res, HTTP_STATUS.OK, MESSAGES.TOKEN_REFRESH_SUCCESS, result);
+        if (!result) {
+          throw new Error("Failed to refresh token");
+        }
+        const refreshData = {
+          accessToken: result.accessToken,
+          refreshToken: result.refreshToken,
+          auth: this.createAuthData(
+            true,
+            false,
+            AUTH_STATUS.BASIC_AUTH,
+            false
+          )
+        };
+        this.sendResponse(res, HTTP_STATUS.OK, MESSAGES.TOKEN_REFRESH_SUCCESS, refreshData);
       } catch (error) {
         next(error);
       }