cca-auth-module 0.1.87 → 0.1.89

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/domain/interfaces/ApiResponse.d.ts

@@ -12,7 +12,7 @@ export interface ApiResponse<T = any> {
 }
 export interface AuthData {
     hasAccessToken: boolean;
-    enable: boolean;
+    enabled: boolean;
     verified?: boolean;
     status: string;
 }

package/dist/index.js

@@ -770,7 +770,6 @@ var _AuthController = class _AuthController {
           accessToken: result.accessToken,
           userId: result.id,
           expiresAt: result.expiresAt,
-          enabled: twoFactorEnabled,
           auth: this.createAuthData(
             true,
             // hasAccessToken
@@ -795,15 +794,11 @@ var _AuthController = class _AuthController {
         const result = await this.adminLoginUseCase.execute(loginDTO, adminPassword);
         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);
@@ -817,12 +812,9 @@ var _AuthController = class _AuthController {
         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);
@@ -837,12 +829,9 @@ var _AuthController = class _AuthController {
         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(
@@ -902,7 +891,6 @@ var _AuthController = class _AuthController {
         const dto = { ...req.body, userId: req.auth?.id };
         await this.twoFactorEnableUseCase.execute(dto);
         const enableData = {
-          isEnabled: true,
           enabledAt: (/* @__PURE__ */ new Date()).toISOString(),
           auth: this.createAuthData(true, true, AUTH_STATUS.PENDING_VERIFICATION)
         };
@@ -978,10 +966,10 @@ var _AuthController = class _AuthController {
       }
     };
   }
-  createAuthData(hasAccessToken, enable, status, verified) {
+  createAuthData(hasAccessToken, enabled, status, verified) {
     return {
       hasAccessToken,
-      enable,
+      enabled,
       status,
       ...verified !== void 0 && { verified }
     };