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

  • signUp checks for an existing user first, then validates email format and password strength before generating a code.
  • verifySignUp removes expired pending entries and rejects mismatched codes before creating a User.
  • resendSignUpCode refreshes both the code value and the ten-minute expiry.
  • login uses User.isLocked() to block locked accounts and increments failedLoginAttempts on password mismatch.
  • verifyCode clears twoFactorCode and twoFactorCodeExpiresAt after a successful match.
  • resendCode reuses the existing user record and refreshes the login code window.

State Transitions

  • pendingSignUps: add on signUp, remove on successful verifySignUp, remove on expired verification, update on resendSignUpCode.
  • failedLoginAttempts: reset to 0 on successful password match, incremented on each mismatch.
  • lockedUntil: set after repeated login failures, cleared on successful password match.
  • twoFactorCode and twoFactorCodeExpiresAt: set on login and resendCode, cleared on successful verifyCode.

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 ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 and are 10 characters long.

Email Service Traceability

Note: login sets lockedUntil with LocalDateTime.now().plusSeconds(15) but returns the text Account locked for 15 minutes. The stored lock duration and the returned message do not match. Note: The shown login, verifyCode, and resendCode methods update User fields in memory, but the displayed code does not call userRepository.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

  • sendTwoFactorCode sets the recipient, subject, and text for the 2FA message and sends it through JavaMailSender.
  • sendAccountLockedEmail prepares a separate lockout notification message and sends it through the same mail sender.
  • AuthService.signUp, AuthService.login, AuthService.resendSignUpCode, and AuthService.resendCode all route through sendTwoFactorCode.
  • 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: sendAccountLockedEmail exists in EmailService, but no call to it appears in the displayed AuthService flows.

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

  • User is mapped with @Entity and @Table(name="AllUsers").
  • The primary key uses @Id with @GeneratedValue(strategy = GenerationType.IDENTITY).
  • UserRepository extends CrudRepository<User,Long>.
  • AuthService.verifySignUp persists a new User through userRepository.save(newUser).
  • AuthService.findUserByEmail iterates over userRepository.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: findUserByEmail casts the findAll() result to List<User> before iterating. The lookup path in the current implementation depends on that conversion succeeding.

  • AuthController is the entrypoint for all documented functional endpoints and mounts them under /auth.
  • The controller returns AuthResponse messages for every operation, so the contract is message-based rather than field-rich.
  • AuthService.signUp and AuthService.verifySignUp use PendingSignUp as the temporary state container for registration before User is created.
  • AuthService.login, AuthService.verifyCode, and AuthService.resendCode use the User entity as the live state holder for failed attempts, lock status, and 2FA data.
  • UserRepository is only extended from CrudRepository<User,Long>; the service performs its own lookup logic on top of it.
  • EmailService centralizes the mail payload creation for both signup and login verification codes.