feat(auth): add opt-in TOTP two-factor authentication (Phase 1)

[parth0025]

Phase 1 of S1-03: opt-in authenticator-app 2FA for password login. Strictly additive and non-breaking — with 2FA disabled (the default for every existing user) the login flow is unchanged. OAuth logins, sessions, and the JWT mechanism are untouched.

Backend

• Deps: otplib (TOTP) + qrcode (enrollment QR).
• New twoFactor field on the userAuth schema (Mixed object): TOTP secret AES-256-GCM encrypted at rest; recovery codes bcrypt-hashed and single-use.
• Modules/Auth/helpers/twoFactorRules.js — pure, self-contained helpers (TOTP, recovery codes, AES, tempToken). 10 unit tests in tests/twofactor-rules.test.js.
• Modules/Auth/controller/twoFactor.js — status / setup / verify / disable / validate.
• loginSession.js — extracts finalizeSession (the existing session-issuance code, unchanged) and adds the 2FA gate. When twoFactorEnabled, login returns a short-lived tempToken (signed with a SEPARATE secret + twoFactorPending claim) instead of a session; the normal access-token middleware verifies against JWT_SECRET, so it can never accept the tempToken. /2fa/validate exchanges tempToken + code for a real session via the same finalizeSession.
• Routes + middleware allow-list: setup/verify/disable require auth (JWT + companyId); validate is public and rate-limited like login (manageAttempt).
• .env.example: optional TWO_FACTOR_ENC_KEY / TWO_FACTOR_TEMP_SECRET / TWO_FACTOR_ISSUER (derived from JWT_SECRET if unset).

Frontend

• Login.vue — second-step code form (TOTP or recovery code) shown when the API returns twoFactorRequired, reusing the shared proceedAfterAuth post-login flow.
• Settings → Two-Factor Authentication (new view + route + menu): enable (QR + manual key + confirm, then one-time recovery codes with copy/download) and disable.
• Endpoint constants + i18n strings.

Out of scope (Phase 2)

Company-wide enforcement and extending the gate to OAuth logins.

Verification

• 10/10 unit tests pass.
• All touched .vue files compile via @vue/compiler-sfc; JS configs parse; backend module loads with all handlers.
• Manually tested: enroll, login second-step, recovery-code single-use, disable, rate-limit.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 1631c3e3-99b9-49f7-a379-f6023f118826

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/2fa-totp-phase1

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}