Add 2FA support for admin accounts

[Wilfred007]

What

@otplib/preset-default and qrcode are installed. Implement TOTP-based 2FA for admin login to protect privileged accounts.

Why

Admin accounts have elevated privileges (payroll execution, employee management, org settings). 2FA is essential.

Scope

In scope: Generate TOTP secret, QR code, verify on login, recovery codes
Out of scope: SMS 2FA, hardware keys

Acceptance Criteria

• Admin can enable 2FA from settings
• QR code generated for authenticator app
• Login requires TOTP code when 2FA enabled
• 8 recovery codes generated
• 2FA can be disabled with current TOTP code

Technical Context

• backend/src/services/authService.ts — auth service
• @otplib/preset-default — TOTP library
• qrcode — QR generation

[balisdev]

Hi, I’d like to contribute to this issue by implementing TOTP-based 2FA for admin accounts.

I think this is a valuable security improvement given that admin accounts have access to sensitive functionality such as payroll execution, employee management, and organization settings. I’d approach the implementation with a focus on keeping the existing authentication flow intact while making the 2FA lifecycle secure and straightforward for users.

Proposed implementation

I’d implement the feature primarily within backend/src/services/authService.ts, using the existing dependencies:

• @otplib/preset-default for generating and verifying TOTP codes/secrets.
• qrcode for generating an authenticator-compatible QR code.

The flow I have in mind is:

1. Enable 2FA

   • Generate a cryptographically secure TOTP secret.
   • Create an otpauth:// URI containing the appropriate issuer/account information.
   • Generate a QR code from the URI.
   • Return the QR code/setup information to the admin without immediately considering 2FA enabled.
   • Require the admin to provide a valid TOTP code to confirm setup.

2. Generate recovery codes

   • Generate exactly 8 unpredictable recovery codes during setup.
   • Store only a secure representation of the codes where appropriate, rather than plaintext recovery codes.
   • Ensure each recovery code can only be used once.

3. Admin login

   • Preserve the existing username/password authentication.
   • If 2FA is enabled, require a valid TOTP code before completing authentication.
   • Return an appropriate intermediate/authentication state when a second factor is required rather than treating the password authentication as fully complete.

4. Disable 2FA

   • Require the current valid TOTP code before disabling 2FA.
   • Remove/invalidate the TOTP configuration and recovery codes after successful disablement.

5. Security considerations

   • Avoid logging TOTP secrets, recovery codes, or submitted TOTP values.
   • Use constant-time-safe verification where applicable.
   • Make recovery codes single-use and invalidate them once consumed.
   • Ensure partially completed 2FA setup cannot accidentally enable 2FA.
   • Handle invalid/expired TOTP codes cleanly without exposing unnecessary authentication details.

Acceptance criteria

I would verify the implementation against all of the requested criteria:

• Admin can enable 2FA from settings.
• An authenticator-compatible QR code is generated.
• Login requires a TOTP code when 2FA is enabled.
• Exactly 8 recovery codes are generated.
• 2FA can only be disabled after providing the current TOTP code.

I’d also add/update tests around enabling 2FA, confirming the setup, successful and failed TOTP verification, recovery-code usage, login behavior with 2FA enabled, and disabling 2FA.

I’m happy to work within the existing project conventions and inspect the current auth/settings models and API structure first so the implementation integrates cleanly rather than introducing a parallel authentication flow.

[grantfox-oss]

🦊 GrantFox — @balisdev has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #557)
2. Your PR will be reviewed by the Protocol-Guild maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@balisdev's PR #601 was approved and merged by @Wilfred007.

🏆 @balisdev: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (748 total points). Track your full progress on GrantFox.

👏 Great work, @balisdev! Keep contributing to Protocol-Guild.