Sequence Diagrams: Password Login¶
- PRD: PRD-password-login
- ADR: 0018-password-login-option
- Spec: — (plan: plan-password-login)
- Status: As-built (2026-10-21)
Notes (code vs PRD):
- "Forgot password" in
PasswordLoginModal.jsxmakes no API call.LoginForm.handleForgotonly closes the modal, copies the typed email into the magic-link form and shows the hint "Press Log in to receive a sign-in link by email". The user then submits the normal magic-link form (POST /user/join). - All base paths below are relative to
/v1/funny-app.
1. Password sign-in (happy path, with and without MFA)¶
A visitor opens the password dialog from the header LoginForm, submits email and password and gets a JWT. If the account has MFA enabled, UserServiceImpl.completeLogin returns MFA_REQUIRED plus a session token instead, and the SPA opens MFALoginModal to finish with POST /user/mfa/verify.
sequenceDiagram
autonumber
actor U as User
participant FE as Browser (LoginForm / PasswordLoginModal / MFALoginModal)
participant API as UserController
participant PL as PasswordLoginServiceImpl
participant LA as LoginAttemptServiceImpl
participant US as UserServiceImpl
participant MS as MFASessionStore
participant DB as PostgreSQL
U->>FE: open login form
FE->>API: GET /v1/funny-app/user/auth-options
API-->>FE: 200 AuthOptionsDto (passwordLoginAvailable)
Note over FE: password button shown only when passwordLoginAvailable is true
U->>FE: enter email and password, submit
FE->>API: POST /v1/funny-app/user/login (RateLimited 10 per IP)
API->>PL: login(PasswordLoginRequest)
PL->>PL: requireEnabled() (app password-login-enabled flag)
PL->>DB: userRepo.findAllByUserName(email)
DB-->>PL: User
PL->>PL: usable check (hash set, not DEACTIVATED, not locked, password at most 72 bytes)
PL->>PL: bCrypt.matches(password, user.password)
opt failed_login_count or locked_until was set
PL->>LA: recordSuccess(userId) (REQUIRES_NEW)
LA->>DB: userRepo.clearLoginFailures(userId)
end
PL->>US: completeLogin(user)
alt user.mfaEnabled is false
US->>US: issueToken(user) (JWT with cv claim = credentialsVersion)
US-->>PL: UserInfoDto (jwt)
PL-->>API: UserInfoDto
API-->>FE: 200 ResultObjectInfo of UserInfoDto
FE->>FE: LoginForm.handleAuthResult then AuthContext.login(jwt, user)
FE-->>U: signed in
else user.mfaEnabled is true
US->>MS: storeSession(sessionToken, userName)
US-->>PL: UserInfoDto (action MFA_REQUIRED, sessionToken, no jwt)
PL-->>API: UserInfoDto
API-->>FE: 200 ResultObjectInfo of UserInfoDto (MFA_REQUIRED)
FE->>FE: LoginForm.handleAuthResult stores user, calls onMfaRequired (AppShell opens MFALoginModal)
U->>FE: enter 6-digit OTP
FE->>API: POST /v1/funny-app/user/mfa/verify (otp, username, sessionToken)
API->>US: verifyMfa(MfaRequest)
US->>MS: getUserId(sessionToken)
MS-->>US: userName or empty
alt unknown or expired sessionToken
US-->>API: CustomException error.auth.sessionExpired
API-->>FE: error ResultErrorInfo (no JWT)
else session found
US->>DB: userRepo.findAllByUserName(userName)
US->>US: requireActive(user)
alt user is DEACTIVATED
US-->>API: CustomException 403 error.account.deactivated
API-->>FE: 403 ResultErrorInfo (no JWT)
else active
US->>US: totp.verify(otp, mfaSecret) (wrong OTP raises error.otp.incorrect)
US-->>API: UserInfoDto (jwt)
API-->>FE: 200 ResultObjectInfo of UserInfoDto
FE->>FE: AuthContext.login(jwt, user)
FE-->>U: signed in
end
end
end
2. Password sign-in failure (generic 401, lockout, rate limit)¶
Every rejection (unknown email, no password set, wrong password, deactivated, locked, over-long password) returns the same 401 INVALID_CREDENTIALS, so callers cannot enumerate accounts. A wrong password increments the failure counter in its own transaction. At 5 failures the account is locked for 15 minutes (magic link still works). The IP rate limit answers 429.
sequenceDiagram
autonumber
actor U as User
participant FE as Browser (PasswordLoginModal.jsx)
participant API as UserController
participant PL as PasswordLoginServiceImpl
participant LA as LoginAttemptServiceImpl
participant DB as PostgreSQL
U->>FE: submit email and password
FE->>API: POST /v1/funny-app/user/login
alt more than 10 requests per minute from the IP
API-->>FE: 429 (RateLimited aspect)
FE-->>U: "rateLimited" message
else within the limit
API->>PL: login(PasswordLoginRequest)
PL->>DB: userRepo.findAllByUserName(email)
DB-->>PL: User or null
alt unknown email, no hash, DEACTIVATED, locked or password not checkable
PL->>PL: burnTime(password) (BCrypt against dummyHash, equal timing)
PL-->>API: CustomException 401 INVALID_CREDENTIALS
else password does not match
PL->>LA: recordFailure(userId) (REQUIRES_NEW)
LA->>DB: userRepo.incrementFailedLoginCount(userId)
LA->>DB: userRepo.findAllById(userId)
opt failedLoginCount reaches MAX_FAILURES (5)
LA->>DB: userRepo.lockAccount(userId, now plus 15 min)
end
PL-->>API: CustomException 401 INVALID_CREDENTIALS
end
API-->>FE: 401 ResultErrorInfo (INVALID_CREDENTIALS)
FE-->>U: "invalidCredentials" (same text for every cause)
end
3. Set or change password (authenticated, MFA aware)¶
A signed-in user sets a first password (no current password needed) or changes an existing one (current password required) in Settings, SignInPanel.jsx. MFA users must also send a 6-digit OTP. Success bumps credentials_version, which revokes every other session, and returns a fresh JWT for the current one. Remove password (DELETE /user/password) follows the same path with removePassword, always requires the current password and sends PASSWORD_REMOVED. If the user has no password, removePassword throws 400 PASSWORD_NOT_SET before any credential check.
sequenceDiagram
autonumber
actor U as User
participant FE as Browser (SignInPanel.jsx)
participant API as UserController
participant PL as PasswordLoginServiceImpl
participant LA as LoginAttemptServiceImpl
participant CV as CredentialsVersionCache
participant US as UserServiceImpl
participant MAIL as MailService
participant DB as PostgreSQL
U->>FE: fill current (if set), new, confirm, OTP (if mfaEnabled)
FE->>FE: client checks (required, confirm match, OTP length 6)
FE->>API: PUT /v1/funny-app/user/password (JWT, RateLimited 5)
API->>PL: setPassword(SetPasswordRequest)
PL->>PL: requireEnabled() and currentUser() (AppUtils.getCurrentUser, userRepo.findAllById)
opt guard fails
PL-->>API: CustomException 404 error.user.notFound (password-login flag off, same guard on POST /user/login)
PL-->>API: CustomException 401 error.auth.tokenInvalid (no current user)
PL-->>API: CustomException 403 error.account.deactivated
end
PL->>PL: PasswordPolicy.validate(newPassword, email)
opt user already has a password
PL->>PL: verifyCurrentPassword(user, currentPassword)
Note over PL,LA: wrong current password calls recordFailure and counts toward lockout
end
opt user.mfaEnabled
PL->>PL: verifyOtpIfMfa() via totp.verify(otp, mfaSecret)
end
PL->>PL: bCrypt.encode(newPassword), set passwordSetAt
PL->>DB: userRepo.save(user) with credentialsVersion plus 1
PL->>CV: evict(userId)
PL->>US: issueToken(user) (new cv claim)
PL->>MAIL: sendSimpleMail(security notice) (sendSecurityEmail, failure only logged)
Note over PL,MAIL: locale from EmailLocaleResolver.forUser. EmailCacheLimiter daily count is incremented after sending, if the budget is exhausted it only logs a warning and still sends
PL-->>API: UserInfoDto (jwt, action PASSWORD_SET or PASSWORD_CHANGED)
API-->>FE: 200 ResultObjectInfo of UserInfoDto
FE->>FE: AuthContext.login(newJwt, user) and patch ['settings'] query
FE-->>U: "passwordUpdated"
alt policy violation
PL-->>API: CustomException 400 PASSWORD_TOO_SHORT, PASSWORD_TOO_LONG, PASSWORD_CONTAINS_EMAIL or PASSWORD_TOO_COMMON
else wrong or uncheckable current password, or account locked
PL-->>API: CustomException 400 CURRENT_PASSWORD_INVALID
else MFA user with missing or wrong OTP
PL-->>API: CustomException 400 OTP_INVALID
end
API-->>FE: 400 ResultErrorInfo (code)
FE-->>U: mapPasswordError() shows translated errCodes text
4. Session revocation after a credential change¶
Tokens carry a cv claim. JWTAuthenticationFilter compares it with CredentialsVersionCache.currentVersion(userId) on every request, so a token issued before a set, change or remove is rejected with 401 TOKEN_REVOKED. The SPA then clears local storage and signs the user out.
sequenceDiagram
autonumber
participant FE2 as Browser (other device, old JWT)
participant F as JWTAuthenticationFilter
participant JP as JwtProvider
participant CV as CredentialsVersionCache
participant DB as PostgreSQL
participant AC as Browser (client.js and AuthContext)
FE2->>F: any protected request with old JWT (cv = n)
F->>JP: verifyToken(token)
JP-->>F: UserDetailDto (credentialsVersion = n)
F->>CV: currentVersion(userId)
alt cached value present
CV-->>F: n plus 1
else cache miss or expired (instances converge within about a minute)
CV->>DB: read credentials_version
DB-->>CV: n plus 1
CV-->>F: n plus 1
end
F-->>FE2: 401 TOKEN_REVOKED
FE2->>AC: client.js removes jwt and user, dispatches AUTH_REVOKED_EVENT
AC-->>FE2: signed out, login form shown