Product Scope and Requirements - Functional Requirements Traceability
Overview
This section traces the authentication-related functional requirements into the implementation surfaces that realize them in the Bank ASAP application. The visible code centers on registration, login, code verification, code resend, persistence of registered users, and email delivery of verification codes.
The primary runtime path is AuthController → AuthService → EmailService and UserRepository, with User and PendingSignUp carrying the state needed for verification, lockout, and account creation. The controller returns AuthResponse messages for every flow, so the functional scope is expressed as message-driven outcomes rather than distinct response models.
Functional Requirement Traceability Matrix
| Functional behavior | Implementation surfaces | Traceable runtime behavior |
|---|---|---|
| Start sign-up with email, password, and password confirmation | [REDACTED] | signUp validates email format, password rules, and matching passwords before generating a verification code and emailing it. |
| Complete sign-up after code verification | src/main/java/com/bankasap/service/AuthService.java, src/main/java/com/bankasap/model/PendingSignUp.java, src/main/java/com/bankasap/repository/UserRepository.java |
verifySignUp checks for a pending record, checks expiry, compares the code, creates a User, saves it, and removes the pending entry. |
| Resend the sign-up verification code | src/main/java/com/bankasap/service/AuthService.java, src/main/java/com/bankasap/service/EmailService.java |
resendSignUpCode refreshes the stored code and expiry on the existing PendingSignUp entry and sends a new email. |
| Start login and issue a 2FA code | src/main/java/com/bankasap/controller/AuthController.java, src/main/java/com/bankasap/service/AuthService.java, src/main/java/com/bankasap/model/User.java |
login looks up the user, checks lock status, verifies the password, resets failure counters on success, generates a new code, and emails it. |
| Verify the login 2FA code | src/main/java/com/bankasap/service/AuthService.java, src/main/java/com/bankasap/model/User.java |
verifyCode checks that a code exists, checks expiry, compares the supplied code, and clears the code fields on success. |
| Resend the login 2FA code | src/main/java/com/bankasap/service/AuthService.java, src/main/java/com/bankasap/service/EmailService.java |
resendCode generates a new code for the existing user, refreshes the expiry, and sends the email again. |
| Track failed login attempts and lock the account | src/main/java/com/bankasap/model/User.java, src/main/java/com/bankasap/service/AuthService.java |
login increments failedLoginAttempts, sets lockedUntil after repeated failures, and uses isLocked() to block access while the lock is active. |
| Deliver authentication emails | src/main/java/com/bankasap/service/EmailService.java |
sendTwoFactorCode and sendAccountLockedEmail build SimpleMailMessage instances and send them through JavaMailSender. |
| Return a single message payload for every auth endpoint | src/main/java/com/bankasap/controller/AuthController.java, src/main/java/com/bankasap/dto/AuthResponse.java |
Each controller method wraps the service string in AuthResponse.message and returns it with ResponseEntity.ok. |
Auth Controller Traceability
src/main/java/com/bankasap/controller/AuthController.java
AuthController is the HTTP entrypoint for the functional scope. It is mapped at /auth and exposes the sign-up, login, verification, and resend handlers that the requirements document describes. Every handler delegates directly to AuthService and wraps the returned string in AuthResponse.
Handler to Service Mapping
| Handler | Request DTO | Delegates to | Returned payload |
|---|---|---|---|
signUp |
SignUpRequest |
authService.signUp |
AuthResponse.message |
verifySignUp |
VerifySignUpRequest |
authService.verifySignUp |
AuthResponse.message |
resendSignUpCode |
ResendSignUpCodeRequest |
authService.resendSignUpCode |
AuthResponse.message |
login |
LoginRequest |
authService.login |
AuthResponse.message |
verifyCode |
VerifyCodeRequest |
authService.verifyCode |
AuthResponse.message |
resendCode |
ResendCodeRequest |
authService.resendCode |
AuthResponse.message |
Response Shape
The controller always returns a ResponseEntity<AuthResponse> with a single message field. The HTTP status is created with ResponseEntity.ok for the shown handlers, so the observable contract is a message-bearing response body for both success and failure outcomes.
Auth Service Traceability
src/main/java/com/bankasap/service/AuthService.java
AuthService carries the behavior that turns the functional requirements into state changes, validation, code generation, and repository interaction. It depends on EmailService, PasswordEncoder, and UserRepository, and it keeps sign-up state in the in-memory pendingSignUps list.
Constructor Dependencies
| Type | Description |
|---|---|
EmailService |
Sends verification emails for sign-up and login code flows. |
PasswordEncoder |
[REDACTED] |
UserRepository |
Persists new User records and scans existing users. |
Internal State
| Member | Role in the requirement flow |
|---|---|
formatter: DateTimeFormatter |
Formats lock-until timestamps in status messages. |
pendingSignUps: List<PendingSignUp> |
Stores sign-up attempts until the verification code is confirmed. |
Public Methods
| Method | Description |
|---|---|
signUp |
Validates the sign-up request, creates or refreshes a pending sign-up entry, and emails a verification code. |
verifySignUp |
Confirms a sign-up code, persists the new user, and removes the pending entry. |
resendSignUpCode |
Reissues a sign-up code for an existing pending sign-up record. |
login |
Validates credentials, applies lockout rules, generates a login 2FA code, and emails it. |
verifyCode |
Validates the login 2FA code, checks expiry, and clears the code on success. |
resendCode |
Generates and emails a new login 2FA code for an existing user. |
Requirement-Critical Behaviors
signUpchecks for an existing user first, then validates email format and password strength before generating a code.verifySignUpremoves expired pending entries and rejects mismatched codes before creating aUser.resendSignUpCoderefreshes both the code value and the ten-minute expiry.loginusesUser.isLocked()to block locked accounts and incrementsfailedLoginAttemptson password mismatch.verifyCodeclearstwoFactorCodeandtwoFactorCodeExpiresAtafter a successful match.resendCodereuses the existing user record and refreshes the login code window.
State Transitions
pendingSignUps: add onsignUp, remove on successfulverifySignUp, remove on expired verification, update onresendSignUpCode.failedLoginAttempts: reset to0on successful password match, incremented on each mismatch.lockedUntil: set after repeated login failures, cleared on successful password match.twoFactorCodeandtwoFactorCodeExpiresAt: set onloginandresendCode, cleared on successfulverifyCode.
Validation Rules Implemented in Code
- Email validation requires a non-null value, exactly one
@, and at least one.. - Password validation requires length between 8 and 20 characters and the presence of a number, an uppercase letter, a special character, and a letter.
- Generated codes use the character set
ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789and are 10 characters long.
Email Service Traceability
Note:
loginsetslockedUntilwithLocalDateTime.now().plusSeconds(15)but returns the textAccount locked for 15 minutes. The stored lock duration and the returned message do not match. Note: The shownlogin,verifyCode, andresendCodemethods updateUserfields in memory, but the displayed code does not calluserRepository.save(user)after those updates.
src/main/java/com/bankasap/service/EmailService.java
EmailService is the email delivery surface used by the authentication flows. It is initialized with JavaMailSender and sends SimpleMailMessage instances that carry the code or lockout notification text.
Constructor Dependencies
| Type | Description |
|---|---|
JavaMailSender |
Sends the constructed mail messages. |
Public Methods
| Method | Description |
|---|---|
sendTwoFactorCode |
Sends the authentication code email used by sign-up and login flows. |
sendAccountLockedEmail |
Sends the account lock notification email. |
Email Data Flow
sendTwoFactorCodesets the recipient, subject, and text for the 2FA message and sends it throughJavaMailSender.sendAccountLockedEmailprepares a separate lockout notification message and sends it through the same mail sender.AuthService.signUp,AuthService.login,AuthService.resendSignUpCode, andAuthService.resendCodeall route throughsendTwoFactorCode.- The shown auth flow does not invoke
sendAccountLockedEmail.
Email Flow Sequence
sequenceDiagram
participant U as User
participant S as AuthService
participant E as EmailService
participant M as JavaMailSender
U->>S: signUp or login or resendSignUpCode or resendCode
S->>E: sendTwoFactorCode
E->>M: send message
M-->>E: email submitted
E-->>S: completed
User Persistence and State Traceability
Note:
sendAccountLockedEmailexists inEmailService, but no call to it appears in the displayedAuthServiceflows.
src/main/java/com/bankasap/model/User.java
src/main/java/com/bankasap/repository/UserRepository.java
The User entity and UserRepository together carry the persisted state used by the authentication requirements. The entity stores the account identity, password, lockout fields, and 2FA fields, while the repository is the persistence entrypoint used by AuthService.
User State Used by the Requirements
| Field | Role in the functional flow |
|---|---|
email |
Identifies the user for sign-up checks, login, and code lookup. |
password |
[REDACTED] |
failedLoginAttempts |
Counts unsuccessful login attempts. |
lockedUntil |
Controls lockout status through isLocked(). |
twoFactorCode |
Stores the current login verification code. |
twoFactorCodeExpiresAt |
Stores the expiry timestamp for the login verification code. |
Persistence Characteristics
Useris mapped with@Entityand@Table(name="AllUsers").- The primary key uses
@Idwith@GeneratedValue(strategy = GenerationType.IDENTITY). UserRepositoryextendsCrudRepository<User,Long>.AuthService.verifySignUppersists a newUserthroughuserRepository.save(newUser).AuthService.findUserByEmailiterates overuserRepository.findAll()to locate a matching email.
User State Transition Sequence
stateDiagram-v2
[*] --> PendingSignup
PendingSignup --> Registered: verifySignUp
Registered --> LoginAttempted: login
LoginAttempted --> Locked: failedLoginAttempts reaches threshold
LoginAttempted --> 2FACodeIssued: password matches
2FACodeIssued --> Authenticated: verifyCode
2FACodeIssued --> 2FACodeIssued: resendCode
Locked --> Locked: login while isLocked
Authentication Requirement Flow
sequenceDiagram
participant U as User
participant C as AuthController
participant S as AuthService
participant E as EmailService
participant R as UserRepository
participant P as pendingSignUps
alt Sign up flow
U->>C: POST /auth/signup
C->>S: signUp
S->>S: validate email and password
S->>P: add PendingSignUp
S->>E: sendTwoFactorCode
E-->>S: code emailed
S-->>C: Signup verification code sent to email
C-->>U: AuthResponse.message
opt Verify sign up
U->>C: POST /auth/verify-signup
C->>S: verifySignUp
S->>P: findPendingSignUpByEmail
S->>R: save new User
S-->>C: User registered successfully
C-->>U: AuthResponse.message
end
opt Resend sign up code
U->>C: POST /auth/resend-signup-code
C->>S: resendSignUpCode
S->>P: update code and expiry
S->>E: sendTwoFactorCode
E-->>S: code emailed
S-->>C: New signup verification code sent to email
C-->>U: AuthResponse.message
end
else Login flow
U->>C: POST /auth/login
C->>S: login
S->>R: findAll
S->>S: check password and lock state
S->>E: sendTwoFactorCode
E-->>S: code emailed
S-->>C: 2FA code sent to email
C-->>U: AuthResponse.message
opt Verify login code
U->>C: POST /auth/verify-code
C->>S: verifyCode
S->>R: findAll
S->>S: compare code and expiry
S-->>C: Login successful
C-->>U: AuthResponse.message
end
opt Resend login code
U->>C: POST /auth/resend-login-code
C->>S: resendCode
S->>R: findAll
S->>E: sendTwoFactorCode
E-->>S: code emailed
S-->>C: New 2FA code sent to email
C-->>U: AuthResponse.message
end
end
Endpoint Contracts
Sign Up
{
"title": "Sign Up",
"description": "Validates email, password, and confirmPassword, then sends a signup verification code through EmailService.",
"method": "POST",
"baseUrl": "<ServiceBaseUrl>",
"endpoint": "/auth/signup",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"email\": \"[email protected]\",\n \"password\": \"SecurePass1!\",\n \"confirmPassword\": \"SecurePass1!\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"message\": \"Signup verification code sent to email\"\n}"
}
}
}
Verify Sign Up
{
"title": "Verify Sign Up",
"description": "Confirms a pending signup code and persists the new user when the code is valid and unexpired.",
"method": "POST",
"baseUrl": "<ServiceBaseUrl>",
"endpoint": "/auth/verify-signup",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"email\": \"[email protected]\",\n \"code\": \"AB12CD34EF\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"message\": \"User registered successfully\"\n}"
}
}
}
Resend Sign Up Code
{
"title": "Resend Sign Up Code",
"description": "Replaces the pending signup code, refreshes expiry, and sends the new code by email.",
"method": "POST",
"baseUrl": "<ServiceBaseUrl>",
"endpoint": "/auth/resend-signup-code",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"email\": \"[email protected]\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"message\": \"New signup verification code sent to email\"\n}"
}
}
}
Login
{
"title": "Login",
"description": "Checks the stored user record, applies lockout rules, and sends a 2FA code when the password matches.",
"method": "POST",
"baseUrl": "<ServiceBaseUrl>",
"endpoint": "/auth/login",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"email\": \"[email protected]\",\n \"password\": \"SecurePass1!\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"message\": \"2FA code sent to email\"\n}"
}
}
}
Verify Code
{
"title": "Verify Code",
"description": "Validates the login 2FA code and clears the code state when the code is valid and unexpired.",
"method": "POST",
"baseUrl": "<ServiceBaseUrl>",
"endpoint": "/auth/verify-code",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"email\": \"[email protected]\",\n \"code\": \"AB12CD34EF\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"message\": \"Login successful\"\n}"
}
}
}
Resend Login Code
{
"title": "Resend Login Code",
"description": "Generates a new 2FA code for the existing user and sends it by email.",
"method": "POST",
"baseUrl": "<ServiceBaseUrl>",
"endpoint": "/auth/resend-login-code",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"email\": \"[email protected]\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"message\": \"New 2FA code sent to email\"\n}"
}
}
}
Traceability Notes
Note:
findUserByEmailcasts thefindAll()result toList<User>before iterating. The lookup path in the current implementation depends on that conversion succeeding.
AuthControlleris the entrypoint for all documented functional endpoints and mounts them under/auth.- The controller returns
AuthResponsemessages for every operation, so the contract is message-based rather than field-rich. AuthService.signUpandAuthService.verifySignUpusePendingSignUpas the temporary state container for registration beforeUseris created.AuthService.login,AuthService.verifyCode, andAuthService.resendCodeuse theUserentity as the live state holder for failed attempts, lock status, and 2FA data.UserRepositoryis only extended fromCrudRepository<User,Long>; the service performs its own lookup logic on top of it.EmailServicecentralizes the mail payload creation for both signup and login verification codes.