cca-auth-module

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

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.).

---

2. Logout

• 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:

    { "message": "Logged out successfully" }

---

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.

---

4. Refresh Token

• 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).

---

5. Verify Token

• 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:

  verifyToken(token: string): Promise<IDecodedToken>

---

Usage Example

Below is an example of integrating the Auth Module into an Express application:

import express from 'express';
import { AuthController, authConfig, createAuthContainer } from 'path-to-your-auth-module';
import { ConfigSource } from 'path-to-your-domain-interfaces';

const app = express();
app.use(express.json());

// 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'
};

// Initialize auth configuration
authConfig(configSource);

// Create a container and resolve the AuthController
const container = createAuthContainer();
const authController: AuthController = container.resolve(AuthController);

// 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);

// Error handling middleware
app.use((err, req, res, next) => {
  res.status(500).json({ error: err.message });
});

app.listen(3000, () => console.log('Server running on port 3000'));

---

Error Handling

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:

app.use((err, req, res, next) => {
  // Optionally log the error here
  res.status(500).json({ error: err.message });
});

---

License

This module is released under the MIT 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.