[FORGOT-101] Forgot Password Flow

[mehalyna]

🎯 Story Overview

As a
registered user who has forgotten their password,

I want to
request a password reset by entering my registered email address,

So that I can
receive a secure reset link and regain access to my account.

---

✅ Acceptance Criteria

#	Criteria
1	The “Forgot Password?” screen must include a field for Email and a “Відновити пароль” button.
2	The submit button must be disabled until a valid email is entered.
3	If a valid, registered email is entered, a confirmation message should be shown indicating an email has been sent.
4	If the email is not registered, an error should be displayed: Зазначена електронна адреса не зареєстрована.
5	If the email format is invalid, display: Введіть адресу електронної пошти у форматі name@example.com.
6	The user must be able to return to the login screen via a link: Я згадав свій пароль. Повернутися до входу.
7	Emails sent must include a secure link for resetting the password (expires after a defined period).

---

📲 UI/UX Notes

• The design uses a clean, centered form with proper spacing and one clear call to action.
• Inline error messages appear below the email field for invalid or unregistered addresses.
• Success feedback is given after submission, regardless of whether the email exists (to avoid email enumeration).
• Footer and layout match the login and registration screens for consistency.

---

🔗 Dependencies

• Endpoint for submitting password reset requests
• Backend service to validate email and trigger reset email
• Email service to send reset link
• Secure token handling and expiration logic

---

🧪 Example Screens from UI Mockups

Screen State	Description
🟡 Initial State	Disabled button, no input yet
✅ Valid Email Entered	Button enabled, request sent
❌ Invalid Email Format	Error message shown under field
❌ Unregistered Email	Error: Зазначена електронна адреса не зареєстрована
🔙 Return Link	Link at bottom: Повернутися до входу

---

📄 Error & Info Messages (Ukrainian)

• Invalid format: Введіть адресу електронної пошти у форматі name@example.com
• Unregistered email: Зазначена електронна адреса не зареєстрована
• Success: A non-revealing confirmation that an email has been sent (message may be modal or new screen)

---

📌 Navigation

• Відновити пароль → Triggers reset request to backend
• Повернутися до входу → Redirects back to login screen

🔧 Sub-tasks for FORGOT-101: Forgot Password Flow

🛠 Frontend Implementation

• FORGOT-101-1: Design and implement the "Forgot Password" screen layout
• FORGOT-101-2: Create an input field for entering the user's email address
• FORGOT-101-3: Disable the "Відновити пароль" button until a valid email is entered
• FORGOT-101-4: Add real-time email format validation with inline error messaging
• FORGOT-101-5: Display error: Введіть адресу електронної пошти у форматі name@example.com for invalid formats
• FORGOT-101-6: Add navigation link: Повернутися до входу → redirects to login screen
• FORGOT-101-7: Show appropriate success or failure feedback after submission

---

🔐 Backend Implementation

• FORGOT-101-8: Create API endpoint to receive email and trigger password reset process
• FORGOT-101-9: Verify that the email is registered in the system
• FORGOT-101-10: Return an error: Зазначена електронна адреса не зареєстрована if email is not found
• FORGOT-101-11: Generate secure, time-limited password reset token
• FORGOT-101-12: Send password reset email with unique tokenized link

---

✅ Validation & Error Handling

• FORGOT-101-13: Prevent submission if input is empty or invalid
• FORGOT-101-14: Ensure success message is shown even if email does not exist (for security)
• FORGOT-101-15: Sanitize and validate email input on server side

---

🧪 QA & Testing

• FORGOT-101-16: Write unit tests for frontend email validation logic
• FORGOT-101-17: Test submission flow with:
  • Valid registered email
  • Invalid email format
  • Unregistered email
• FORGOT-101-18: Verify token and email content (link correctness, expiration)
• FORGOT-101-19: Ensure reset link leads to secure password reset screen

---

📄 Documentation

• FORGOT-101-20: Document the password reset API (endpoint, expected request, and response formats)
• FORGOT-101-21: Update user guide or help section with password recovery instructions