Two-Factor Authentication (2FA)
Relevant source files
The following files were used as context for generating this wiki page:The email-platform implements two distinct but related Two-Factor Authentication features to enhance security. The primary feature is a standard TOTP (Time-based One-Time Password) system for user accounts, requiring a second factor during login. This uses libraries like otplib on the backend and is managed through the user's settings page.
Additionally, the platform provides a built-in "Authenticator" vault. This is a secure storage for managing third-party 2FA secrets (like for Google, GitHub, etc.) directly within the application, acting as a self-hosted alternative to apps like Google Authenticator.
Sources: services/api/src/routes/auth.ts, services/api/src/routes/authenticator.ts
Account 2FA
This is the standard 2FA mechanism to protect user accounts on this platform. When enabled, after a successful password login, the user must provide a 6-digit code from their authenticator app or one of their backup codes.
Data Model
The User model in the database is extended with several fields to support 2FA functionality. The twoFactorSecret is encrypted before being stored.
Sources: services/api/src/routes/auth.ts:333-336, 422-425
The following diagram shows the 2FA-related fields in the User entity.
2FA Setup and Enablement Flow
The user initiates 2FA setup from the Settings page. The process involves generating a secret, displaying it as a QR code, and verifying a TOTP code to confirm the setup. Upon successful verification, backup codes are generated and presented to the user.
Sources: services/web/src/pages/Settings.tsx:103-143, services/api/src/routes/auth.ts:340-429
This sequence diagram illustrates the 2FA enablement process.
Login Flow with 2FA
When a user with 2FA enabled logs in, the API returns a requires2FA: true flag along with a temporary JWT. The client then presents a screen for the 2FA code. The user can enter either a TOTP code or a backup code.
Sources: services/web/src/pages/Login.tsx:28-50, services/api/src/routes/auth.ts:223-233, 269-338
The sequence diagram below details the login process for a 2FA-enabled user.
2FA Disabling Flow
To disable 2FA, the user must confirm their identity by providing their current password. This is a security measure to prevent unauthorized deactivation.
Sources: services/web/src/pages/Settings.tsx:145-163, services/api/src/routes/auth.ts:432-463
This diagram shows the flow for disabling 2FA.
API Endpoints for Account 2FA
The following endpoints in services/api/src/routes/auth.ts manage the 2FA lifecycle.
| Method | Endpoint | Description | Authentication |
|---|---|---|---|
POST | /auth/2fa/setup | Generates a new TOTP secret and QR code for the user to scan. | JWT Required |
POST | /auth/2fa/enable | Verifies the initial TOTP code and enables 2FA for the account. | JWT Required |
POST | /auth/2fa/disable | Disables 2FA after verifying the user's password. | JWT Required |
POST | /auth/2fa/verify | Verifies a TOTP or backup code during login. | Temporary JWT |
Sources: services/api/src/routes/auth.ts:269-463
Authenticator Vault
This is a separate feature that acts as a self-hosted vault for storing and generating TOTP codes for other services (e.g., Google, GitHub). It is accessible via the "Authenticator" page in the web application. Secrets are encrypted in the database and decrypted on-demand by the API.
Sources: services/api/src/routes/authenticator.ts, services/web/src/pages/Authenticator.tsx
Authenticator Vault Flow
The user can add, view, and delete 2FA accounts within the vault. The frontend polls for accounts and then uses a client-side otplib instance to generate the codes in real-time.
This sequence diagram shows how a user interacts with the Authenticator Vault.
API Endpoints for Authenticator Vault
These endpoints are defined in services/api/src/routes/authenticator.ts.
| Method | Endpoint | Description | Authentication |
|---|---|---|---|
GET | /auth/authenticator/accounts | Lists all 2FA accounts stored by the user. | JWT Required |
POST | /auth/authenticator/accounts | Adds a new 2FA account to the vault. | JWT Required |
DELETE | /auth/authenticator/accounts/:id | Deletes a 2FA account from the vault. | JWT Required |