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

pnpm add cca-auth-module

Quick Start

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.

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:

{
  "email": "[email protected]",
  "password": "Password1!"
}

Response:

{
  "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:

{
  "email": "[email protected]",
  "password": "Password1!",
  "adminPassword": "AdminSecret"
}

Response:

{
  "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:

{}

Response:

{
  "success": true,
  "message": "Logged out successfully",
  "data": {
    "auth": {
      "hasAccessToken": false,
      "enabled": false,
      "status": "logged_out",
      "verified": false
    }
  }
}

4) Register

POST /auth/register

Request:

{
  "email": "[email protected]",
  "name": "New User",
  "password": "Password1!",
  "role": "USER",
  "adminPassword": "optional-if-role-admin"
}

Response:

{
  "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:

{
  "refreshToken": "yourRefreshToken"
}

Response:

{
  "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:

{
  "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:

{
  "token": "2faToken"
}

Response:

{
  "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:

{
  "token": "2faVerificationToken"
}

Response:

{
  "success": true,
  "message": "Two-factor authentication verified successfully",
  "data": {
    "token": "accessToken",
    "refreshToken": "refreshToken",
    "user": {
      "id": "userId",
      "email": "[email protected]",
      "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:

{
  "token": "current2faToken"
}

Response:

{
  "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.

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