Feat/be 13 two factor authentication

[warisu]

Summary

Implements Time-based One-Time Password (TOTP) two-factor authentication (2FA) to strengthen account security. Users can now configure an authenticator application, enable or disable 2FA, and complete login using a secondary verification step when 2FA is enabled.

Changes

User Entity & Persistence

• Added twoFactorSecret field to the User entity.
• Added support for encrypted storage of TOTP secrets at rest.
• Added migration for 2FA-related user fields.
• Extended user persistence layer to support 2FA configuration state.

Two-Factor Authentication

• Implemented POST /auth/2fa/setup to generate TOTP secrets and QR codes for authenticator apps.
• Implemented POST /auth/2fa/enable to verify initial TOTP setup and activate 2FA.
• Implemented POST /auth/2fa/disable to securely disable 2FA after code verification.
• Implemented POST /auth/2fa/authenticate to complete the second authentication step and issue access tokens.
• Added backup code generation for account recovery scenarios.

Authentication Flow

• Updated login flow to support conditional 2FA authentication.

• Users with 2FA enabled now receive:

  {
    "requiresTwoFactor": true,
    "tempToken": "..."
  }

  instead of immediate access and refresh tokens.

• Added temporary authentication token generation and validation.

• Added final token exchange flow after successful TOTP verification.

Security

• Added TOTP secret encryption and decryption utilities.
• Added validation for all 2FA-related DTOs.
• Added verification safeguards for invalid, expired, or malformed authentication codes.
• Restricted sensitive fields from default entity selection.

Testing

• Added unit tests for TOTP generation and verification.
• Added authentication flow tests covering 2FA-enabled and non-2FA-enabled users.
• Added endpoint tests for setup, enable, disable, and authenticate operations.
• Verified login behavior for both standard and 2FA-protected accounts.

Acceptance Criteria Covered

• Added encrypted twoFactorSecret field to User entity
• Implemented POST /auth/2fa/setup
• Implemented POST /auth/2fa/enable
• Implemented POST /auth/2fa/disable
• Implemented POST /auth/2fa/authenticate
• Updated POST /auth/login to support 2FA challenge flow
• Added QR code generation for authenticator apps
• Added backup code generation and return on enable

Related Issue

Closes #886
Closes #878

[vercel]

@warisu is attempting to deploy a commit to the naijabuz's projects Team on Vercel.

A member of the Team first needs to authorize it.