cca-auth-module 0.2.1 → 0.2.21

package/README.md

@@ -1,395 +1,385 @@
-# Auth Module Documentation
-
-This module provides endpoints and methods for user authentication, including login, logout, registration, and token refresh operations. It also includes a helper function to verify tokens.
-
-> **Note:** This module expects proper request payloads and uses DTOs (`LoginDTO` and `RegisterDTO`) to enforce data structure. Custom error handling is assumed to be in place.
-
----
-
-## Endpoints
-
-# Auth API Documentation
-
----
-
-## 1. Login
-
-**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
-  }
-}
-```
-
----
-
-## 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
-    }
-  }
-}
-```
-
----
-
-## 6. 2FA Setup
-
-**POST** `/auth/2fa/setup`
-
-### 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"
-  }
-}
-```
-
----
-
-## 7. Enable 2FA
-
-**POST** `/auth/2fa/enable`
-
-### 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"
-  }
-}
-```
-
----
-
-## 8. Verify 2FA
-
-**POST** `/auth/2fa/verify`
-
-### Request Body
-
-```json
-{
-  "userId": "userId",
-  "token": "2faVerificationToken"
-}
-```
-
-### 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": "/"
-  }
-}
-```
-
----
-
-## 9. Disable 2FA
-
-**POST** `/auth/2fa/disable`
-
-### Headers
-
-```
-Authorization: Bearer <accessToken>
-```
-
-### Request Body
-
-```json
-{
-  "token": "current2faToken"
-}
-```
-
-### 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"
-  }
-}
-```
-
----
-
-## Notes
-
-- 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:
-
-```json
-{
-  "success": false,
-  "error": "Error message"
-}
-```
-
----
-
-## License
-
-This module is released under the [MIT License](LICENSE).
-
----
-
-This documentation provides an overview of the available endpoints and helper methods for authentication. For further details on business logic and DTO structures, please refer to the inline comments and source code within the module.
+# CCA Auth Module
+
+Authentication + 2FA module for CCA applications. Provides a controller, use cases, and container wiring for login, registration, refresh, and 2FA flows.
+
+## Features
+
+- Login and admin login
+- Registration with role support
+- Refresh token rotation
+- Two-factor setup, enable, verify, disable
+- Middleware to require completed 2FA
+
+## Installation
+
+```bash
+pnpm add cca-auth-module
+```
+
+## Quick Start
+
+```ts
+import { authConfig, createAuthContainer } from "cca-auth-module";
+
+authConfig(async () => ({
+  accessTokenSecret: process.env.ACCESS_TOKEN_SECRET!,
+  refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET!,
+  accessTokenExpiry: "15m",
+  refreshTokenExpiry: "30d",
+  adminSecretPassword: process.env.ADMIN_SECRET_PASSWORD!,
+  app_name: "MyApp",
+  secretLength: "20",
+  tokenWindow: "1",
+  isDevelopment: false,
+}));
+
+const { authController, requireComplete2FA } = await createAuthContainer(database);
+```
+
+## Configuration
+
+The module reads configuration via `authConfig` and `ConfigSource`.
+
+```ts
+export interface IConfig {
+  accessTokenSecret: string;
+  refreshTokenSecret: string;
+  accessTokenExpiry: string;
+  refreshTokenExpiry: string;
+  adminSecretPassword: string;
+  app_name: string;
+  secretLength: string;
+  tokenWindow: string;
+  isDevelopment: boolean;
+}
+```
+
+## API Endpoints
+
+### 1) Login
+
+**POST** `/auth/login`
+
+Request:
+```json
+{
+  "email": "user@example.com",
+  "password": "Password1!"
+}
+```
+
+Response:
+```json
+{
+  "success": true,
+  "message": "Login successful",
+  "data": {
+    "accessToken": "string",
+    "userId": "string",
+    "expiresAt": 1738166400,
+    "auth": {
+      "hasAccessToken": true,
+      "enabled": false,
+      "status": "pending_verification",
+      "verified": false
+    }
+  },
+  "meta": {
+    "timestamp": "2026-01-29T10:00:00.000Z"
+  }
+}
+```
+
+### 2) Admin Login
+
+**POST** `/auth/admin-login`
+
+Request:
+```json
+{
+  "email": "admin@example.com",
+  "password": "Password1!",
+  "adminPassword": "AdminSecret"
+}
+```
+
+Response:
+```json
+{
+  "success": true,
+  "message": "Admin login successful",
+  "data": {
+    "accessToken": "string",
+    "userId": "string",
+    "expiresAt": 1738166400,
+    "auth": {
+      "hasAccessToken": true,
+      "enabled": true,
+      "status": "pending_verification",
+      "verified": false
+    }
+  }
+}
+```
+
+### 3) Logout
+
+**POST** `/auth/logout`
+
+Headers:
+```
+Authorization: Bearer <accessToken>
+```
+
+Request:
+```json
+{}
+```
+
+Response:
+```json
+{
+  "success": true,
+  "message": "Logged out successfully",
+  "data": {
+    "auth": {
+      "hasAccessToken": false,
+      "enabled": false,
+      "status": "logged_out",
+      "verified": false
+    }
+  }
+}
+```
+
+### 4) Register
+
+**POST** `/auth/register`
+
+Request:
+```json
+{
+  "email": "newuser@example.com",
+  "name": "New User",
+  "password": "Password1!",
+  "role": "USER",
+  "adminPassword": "optional-if-role-admin"
+}
+```
+
+Response:
+```json
+{
+  "success": true,
+  "message": "User registered successfully",
+  "data": {
+    "auth": {
+      "hasAccessToken": false,
+      "enabled": false,
+      "status": "registered",
+      "verified": false
+    }
+  },
+  "meta": {
+    "status": true
+  }
+}
+```
+
+### 5) Refresh Token
+
+**POST** `/auth/refresh-token`
+
+Request:
+```json
+{
+  "refreshToken": "yourRefreshToken"
+}
+```
+
+Response:
+```json
+{
+  "success": true,
+  "message": "Token refreshed successfully",
+  "data": {
+    "accessToken": "newAccessToken",
+    "refreshToken": "newRefreshToken",
+    "auth": {
+      "hasAccessToken": true,
+      "enabled": false,
+      "status": "basic_auth",
+      "verified": false
+    }
+  }
+}
+```
+
+### 6) 2FA Setup
+
+**POST** `/auth/2fa/setup`
+
+Headers:
+```
+Authorization: Bearer <accessToken>
+```
+
+Response:
+```json
+{
+  "success": true,
+  "message": "Two-factor authentication setup initiated",
+  "data": {
+    "qrCode": "data:image/png;base64,...",
+    "auth": {
+      "hasAccessToken": true,
+      "enabled": false,
+      "status": "needs_setup"
+    }
+  },
+  "meta": {
+    "nextStep": "Scan the QR code and enter your first code to verify",
+    "redirectTo": "/2fa-enable"
+  }
+}
+```
+
+### 7) Enable 2FA
+
+**POST** `/auth/2fa/enable`
+
+Headers:
+```
+Authorization: Bearer <accessToken>
+```
+
+Request:
+```json
+{
+  "token": "2faToken"
+}
+```
+
+Response:
+```json
+{
+  "success": true,
+  "message": "Two-factor authentication enabled",
+  "data": {
+    "enabledAt": "2026-01-29T10:00:00.000Z",
+    "auth": {
+      "hasAccessToken": true,
+      "enabled": true,
+      "status": "pending_verification"
+    }
+  },
+  "meta": {
+    "nextStep": "Proceed to verify with a valid 2FA token",
+    "redirectTo": "/verify-2fa"
+  }
+}
+```
+
+### 8) Verify 2FA
+
+**POST** `/auth/2fa/verify`
+
+Headers:
+```
+Authorization: Bearer <accessToken>
+```
+
+Request:
+```json
+{
+  "token": "2faVerificationToken"
+}
+```
+
+Response:
+```json
+{
+  "success": true,
+  "message": "Two-factor authentication verified successfully",
+  "data": {
+    "token": "accessToken",
+    "refreshToken": "refreshToken",
+    "user": {
+      "id": "userId",
+      "email": "user@example.com",
+      "name": "User Name",
+      "role": "USER"
+    },
+    "auth": {
+      "hasAccessToken": true,
+      "enabled": true,
+      "status": "full_auth",
+      "verified": true
+    }
+  },
+  "meta": {
+    "recommendation": "You're fully authenticated",
+    "redirectTo": "/"
+  }
+}
+```
+
+### 9) Disable 2FA
+
+**POST** `/auth/2fa/disable`
+
+Headers:
+```
+Authorization: Bearer <accessToken>
+```
+
+Request:
+```json
+{
+  "token": "current2faToken"
+}
+```
+
+Response:
+```json
+{
+  "success": true,
+  "message": "Two-factor authentication disabled",
+  "data": {
+    "disabledAt": "2026-01-29T10:00:00.000Z",
+    "auth": {
+      "hasAccessToken": true,
+      "enabled": false,
+      "status": "basic_auth",
+      "verified": false
+    }
+  },
+  "meta": {
+    "securityNote": "Account now relies only on password. Re-enable 2FA for better security.",
+    "redirectTo": "/login"
+  }
+}
+```
+
+## Middleware
+
+Use `RequireComplete2FA` to block routes until the user completes 2FA. It expects a JWT with `twoFactorAuthenticated: true`.
+
+```ts
+app.get("/secure", requireComplete2FA.execute, handler);
+```
+
+## Status Codes and Messages
+
+- Status codes are defined in `src/presentation/constants/constants.ts`
+- Error handling uses module errors from `src/utils/Errors.ts`
+
+## Notes
+
+- All token endpoints must be served over HTTPS in production.
+- Refresh tokens are rotated and validated against stored values.
+- Admin registration requires a valid `adminSecretPassword`.
+
+## License
+
+MIT