Plan: Optional Email + Password Login¶
Overview¶
Status: Implemented (verified on prod 2026-10-09) Author: nguyenhuuca Date: 2026-10-07 Related PRD: PRD-password-login Related ADR: ADR-0018
Verified Facts (exploration 2026-10-07)¶
| Area | Fact |
|---|---|
| Config | app.use-password-less: true (yaml:113) binds to AppProperties.usePasswordless (relaxed binding) — prod is magic-link only |
| Legacy path | UserController.signIn → joinSystem(LoginDto) when not passwordless: auto-registers unknown emails with BCrypt password (no verification) |
| Auth | AuthenticationManager + loadUserByUsername (rejects null password); BCrypt bean bCrypt |
| MFA | MFA_REQUIRED + MFASessionStore session token → POST /user/mfa/verify |
| Rate limit | @RateLimited(permit, windowInSeconds), key IP: or USER: |
| JWT | JwtProvider.generateToken(JwtGenerationDto{payload: UserDetailDto}); filter JWTAuthenticationFilter |
| Settings | UserSettingsServiceImpl.buildDto exposes passwordEnabled; FE SettingsPage shows "Change Password" vs "Manage Sign-in" |
| FE | LoginForm.jsx email-only; ProfileModal tabs User Info / MFA; MFALoginModal reusable; no password input component |
MailService.sendSimpleMail; EmailCacheLimiter daily budget 200 |
Implementation Steps¶
Phase 1 — Data & config (0.5 d) — PW-1¶
- [x] Pre-check on prod: no existing account has a password (owner-confirmed 2026-10-07) → schema-only migration, no data migration
- [ ] Migration
202610070001-users-password-login.sql:password_set_at,failed_login_count,locked_until,credentials_version(ADR-0018) - [ ]
User: new fields with@Builder.Defaultwhere defaulted (seeee6ad36lesson) - [ ]
AppProperties.auth.passwordLoginEnabled(app.auth.password-login-enabled, defaulttrue); remove reads ofusePasswordless(log a deprecation warning if the old key is present) - [ ]
PasswordPolicyutility: length 10..72 bytes (UTF-8), not containing email local part (case-insensitive, ≥ 3 chars), not incommon-passwords.txt(10k, classpath, loaded once into aSet) - [ ] BCrypt encoder strength 12 (check existing bean; keep compatible with existing hashes)
Phase 2 — Login endpoint & lockout (1 d) — PW-2 (after PW-1)¶
- [ ]
POST /user/logininUserController(@RateLimited(permit = 10),@AuditLog),PasswordLoginRequest {@Sensitive email, @Sensitive password} - [ ] Service
PasswordLoginService.login:- flag off → 404
- find user; if null / password null / DEACTIVATED /
locked_until > now→ run a dummy BCrypt match (timing) → throwINVALID_CREDENTIALS - BCrypt match fail →
failed_login_count++; at 5 →locked_until = now + 15m, reset count →INVALID_CREDENTIALS - success → reset count/lock; MFA → existing
MFA_REQUIREDflow; else JWT
- [ ] All failures → identical
401 {"error":{"message":"INVALID_CREDENTIALS"}}viaCustomException(UNAUTHORIZED) - [ ] Remove legacy branch in
UserController.signIn(joinSystem) —/user/join= magic link only; delete/deprecatejoinSystem+toEntity - [ ] Tests: success, wrong password, unknown email, null password, deactivated, locked, 5th failure locks, success resets, MFA path, identical error body for every failure, flag off
Phase 3 — Set / change / remove password (1 d) — PW-3 (after PW-1)¶
- [ ]
PUT /user/password{currentPassword?, newPassword, otp?},DELETE /user/password{currentPassword, otp?}(auth,@RateLimited(permit = 5),@AuditLog, all fields@Sensitive) - [ ] Rules: has password →
currentPasswordmust match (wrong → 400CURRENT_PASSWORD_INVALID, counts toward lockout); MFA enabled → validotp; policy errors → 400 with code (PASSWORD_TOO_SHORT,PASSWORD_TOO_LONG,PASSWORD_CONTAINS_EMAIL,PASSWORD_TOO_COMMON) - [ ] Save hash,
password_set_at,credentials_version++; return new JWT for the current session - [ ] Security email (plain text, Vietnamese) via
MailService.sendSimpleMail; counts against the daily budget but never blocked by the digest's 50% cap (security mail has priority) — if budget exhausted, log warning - [ ]
passwordEnabledper user ingetToken,/user/me,UserSettingsServiceImpl.buildDto; addpasswordLoginAvailable(flag) - [ ] Tests for every rule + email sent + version bump
Phase 4 — Session revocation (0.5 d) — PW-4 (after PW-1; integrates with PW-3)¶
- [ ] JWT claim
cv=credentials_version(inUserDetailDto/JwtProviderpayload) - [ ]
CredentialsVersionCache(Guava,expireAfterWrite 60s,userId → version); evict on change - [ ]
JWTAuthenticationFilter: after verify, iftoken.cv != cache.get(userId)→ 401TOKEN_REVOKED(tokens withoutcvtreated as0for backward compat) - [ ] Tests: old token rejected after change; new token accepted; cache eviction; legacy token without
cv
Phase 5 — Frontend (1.25 d) — PW-5 (contract-first)¶
- [ ]
api/auth.js:login(email, password),setPassword(body),removePassword(body) - [ ]
components/common/PasswordInput.jsx(label, show/hide witharia-pressed,autocompletecurrent-password/new-password) - [ ]
LoginForm.jsx: tabs Link đăng nhập | Mật khẩu (desktop header + mobile popover); password tab only whenpasswordLoginAvailable(from/user/settingscapability or a public config — useGET /user/auth-optionsif needed, else always show and let 404 hide it); generic error text "Email hoặc mật khẩu không đúng"; link "Quên mật khẩu? Gửi link đăng nhập" switches tab and pre-fills email; MFA → existingMFALoginModal - [ ] Settings → Sign-in (
ProfileModalnew tab "Đăng nhập" or SettingsPage section): Set password (new + confirm), Change (current + new + confirm), Remove (current); OTP field whenmfaEnabled; client-side policy hints mirroring server codes; on success store the returned JWT (AuthContext.login) and toast "Đã cập nhật mật khẩu. Các thiết bị khác đã đăng xuất." - [ ] Handle
TOKEN_REVOKEDglobally inclient.js→ logout + message - [ ] Tests: tabs, login success/MFA/error, forgot link, set/change/remove flows, policy messages, revoked-token logout
- [ ]
npm run lint && npx vitest run && npm run build
Phase 6 — Verification & docs (0.25 d) — PW-6¶
- [x] Prod E2E (owner, 2026-10-09): magic link → set password → logout → password login → wrong ×5 → locked (magic link still works) → change password on device A → device B logged out within 60 s → security emails received
- [ ]
/security-auditorreview of the diff - [x] Update
docs/tracking.md, mkdocs nav
Dependency Graph¶
Suggested swarm: one BE builder PW-1 → PW-2 → PW-3 → PW-4 (shared files: UserController, UserServiceImpl, JwtProvider); one FE builder PW-5 in parallel.
Estimate: ≈ 4.5 days (≈ 3 days critical path).
Risks¶
| Risk | Mitigation |
|---|---|
| Breaking magic-link login while removing the legacy branch | Keep /user/join + /user/verify-magic tests green; E2E first step is magic link |
| Filter change rejects all existing JWTs | Missing cv = 0 = default column value |
| BCrypt cost 12 CPU on 1 vCPU | ~250 ms per check; login rate-limited; acceptable |
@Builder defaults forgotten on new User fields |
Explicit @Builder.Default + test asserting defaults |