Feat: Improve password reset workflow (#42)

* Add security notification email for password changes

When a user changes their password (while logged in), they now
receive a security alert email with details of the change.

Features:
1. Email Templates:
   - password_changed_notification.html - Styled HTML email
   - password_changed_notification.txt - Plain text version
   - Includes timestamp, IP address, and user agent
   - Clear instructions for compromised accounts

2. Email Sending:
   - Async via Celery with synchronous fallback
   - fail_silently=True to not block password change
   - Includes security audit details (IP, timestamp, device)

3. Security Benefits:
   - Users notified of all password changes
   - Helps detect unauthorized access
   - Provides audit trail for security incidents
   - Clear action steps if account compromised

This is a notification (not confirmation) - the password is already
changed. Users can detect and respond to unauthorized changes.

Workflow:
- Password Change: Immediate + notification email (logged in)
- Password Reset: Email with token → change (logged out)

* Add direct password reset link to security notification email

Enhanced the password change notification email with a prominent
"Reset Password Now" button/link for compromised accounts.

Improvements:
1. HTML Email:
   - Added red "Reset Password Now" button (urgent styling)
   - Links directly to password reset page on frontend
   - Reduces friction for users to secure their account
   - Clearer action hierarchy (reset first, then review)

2. Text Email:
   - Added direct reset password URL
   - Clear call-to-action for text-only email clients

3. Context:
   - Added reset_password_url to email context
   - Constructed from FRONTEND_URL setting
   - Points to /reset-password page

Security Benefits:
- One-click access to password reset (fastest response)
- Reduces time window for attackers to cause damage
- Follows industry best practices (GitHub, Google, etc.)
- Makes security response as easy as possible

User Experience:
- If compromised: Click button → immediately start reset
- If authorized: Ignore email → account already secured

* Add frontend password reset pages and routes

- Create PasswordResetRequestPage for email submission
- Create PasswordResetConfirmPage for token-based password reset
- Add routes for /reset-password and /reset-password/confirm
- Add API functions requestPasswordReset and confirmPasswordReset
- Add "Forgot password?" link to login form
- Add CSS styling for all password reset pages

This completes the password reset feature end-to-end, fixing the 404 error
when users click the "Reset Password Now" link in security notification emails.

* Fix password reset email link to go to confirm page

The reset link in the email was pointing to /reset-password instead of
/reset-password/confirm?token=..., preventing users from actually
resetting their password. Now the link correctly goes to the confirm
page where users can enter their new password.

* Add direct password reset link to security notification email

When a password is changed, the security notification email now includes
a direct link to the password reset confirmation page with a pre-generated
token. This allows users whose accounts may be compromised to immediately
reset their password with one click, instead of having to:
1. Click link to request page
2. Enter email
3. Wait for another email
4. Click that link
5. Finally reset password

Now it's just: Click link → Reset password immediately.

* Fix flickering when navigating to password reset pages

The theme was being re-applied even when already correctly set, causing
a brief black flash during page transitions. Now the code checks if the
current theme matches the expected theme before updating, preventing
unnecessary DOM manipulation and eliminating the flickering effect.

* Use React Router Link instead of anchor tags in LoginForm

Replaced <a href> tags with <Link to> components to enable client-side
navigation. This prevents full page reloads that cause flickering when
navigating from login to register or password reset pages.

- "Register here" link now uses Link component
- "Forgot password?" link now uses Link component

This ensures smooth transitions consistent with navbar navigation.

* Refactor password reset pages to match login/register structure

Extracted form logic into separate components to maintain consistency
with existing authentication pages:

- Created PasswordResetRequestForm component in components/auth/
- Created PasswordResetConfirmForm component in components/auth/
- Moved CSS files to components/auth/ with renamed files
- Simplified page files to just render form components

This improves code organization, consistency, and maintainability by
following the established pattern where pages handle routing and forms
handle UI/logic.

* Fix: Lint

* Fix: Lint

* Fix: Add missing migration scripts

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: adrien-berchet

backend/apps/authentication/admin.py

@@ -1,6 +1,7 @@
 from django.contrib import admin
 
 from .models import EmailConfirmation
+from .models import PasswordReset
 from .models import User
 
 
@@ -27,3 +28,23 @@ class EmailConfirmationAdmin(admin.ModelAdmin):
     list_filter = ("confirmation_type", "confirmed_at")
     ordering = ("-created_at",)
     readonly_fields = ("token", "new_email_hash", "created_at", "expires_at", "confirmed_at")
+
+
+@admin.register(PasswordReset)
+class PasswordResetAdmin(admin.ModelAdmin):
+    list_display = (
+        "user",
+        "created_at",
+        "expires_at",
+        "confirmed_at",
+        "is_expired",
+        "ip_address",
+    )
+    search_fields = ("user__email", "user__username", "ip_address")
+    list_filter = ("confirmed_at", "created_at")
+    ordering = ("-created_at",)
+    readonly_fields = ("token", "created_at", "expires_at", "confirmed_at", "ip_address")
+
+    def get_queryset(self, request):
+        """Optimize queryset with select_related."""
+        return super().get_queryset(request).select_related("user")

backend/apps/authentication/migrations/0005_alter_accountlog_operation_passwordreset.py

@@ -0,0 +1,95 @@
+# Generated by Django 4.2.27 on 2025-12-17 19:48
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations
+from django.db import models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("authentication", "0004_alter_emailconfirmation_expires_at_and_more"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="accountlog",
+            name="operation",
+            field=models.CharField(
+                choices=[
+                    ("USERNAME_CHANGED", "Username Changed"),
+                    ("EMAIL_CHANGED", "Email Changed"),
+                    ("PASSWORD_CHANGED", "Password Changed"),
+                    ("PASSWORD_RESET_REQUESTED", "Password Reset Requested"),
+                    ("PASSWORD_RESET_CONFIRMED", "Password Reset Confirmed"),
+                    ("ACCOUNT_DELETED", "Account Deleted"),
+                    ("EMAIL_CHANGE_REQUESTED", "Email Change Requested"),
+                    ("EMAIL_CHANGE_CONFIRMED", "Email Change Confirmed"),
+                    ("EMAIL_CONFIRMED", "Email Confirmed"),
+                    ("CONFIRMATION_EMAIL_RESENT", "Confirmation Email Resent"),
+                ],
+                help_text="Type of account operation",
+                max_length=50,
+            ),
+        ),
+        migrations.CreateModel(
+            name="PasswordReset",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True, primary_key=True, serialize=False, verbose_name="ID"
+                    ),
+                ),
+                (
+                    "token",
+                    models.CharField(
+                        help_text="HMAC-based reset token", max_length=128, unique=True
+                    ),
+                ),
+                (
+                    "created_at",
+                    models.DateTimeField(auto_now_add=True, help_text="Token creation timestamp"),
+                ),
+                (
+                    "expires_at",
+                    models.DateTimeField(
+                        help_text="Token expiration timestamp (created_at + 24 hours)"
+                    ),
+                ),
+                (
+                    "confirmed_at",
+                    models.DateTimeField(
+                        blank=True, help_text="Timestamp when confirmed, NULL if pending", null=True
+                    ),
+                ),
+                (
+                    "ip_address",
+                    models.GenericIPAddressField(
+                        blank=True,
+                        help_text="IP address of the request (for security audit)",
+                        null=True,
+                    ),
+                ),
+                (
+                    "user",
+                    models.ForeignKey(
+                        help_text="User requesting password reset",
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="password_resets",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Password Reset",
+                "verbose_name_plural": "Password Resets",
+                "db_table": "password_resets",
+                "ordering": ["-created_at"],
+                "indexes": [
+                    models.Index(fields=["user"], name="idx_pwd_reset_user"),
+                    models.Index(fields=["token"], name="idx_pwd_reset_token"),
+                ],
+            },
+        ),
+    ]

backend/apps/authentication/models.py

@@ -408,6 +408,71 @@ def __str__(self):
         return f"{status} {self.user} registration"
 
 
+class PasswordReset(models.Model):
+    """
+    Token storage for password reset flow.
+
+    Stores password reset requests until confirmed via token link.
+    Tokens expire after 24 hours for security.
+    """
+
+    user = models.ForeignKey(
+        "User",
+        on_delete=models.CASCADE,
+        related_name="password_resets",
+        help_text="User requesting password reset",
+    )
+
+    token = models.CharField(max_length=128, unique=True, help_text="HMAC-based reset token")
+
+    created_at = models.DateTimeField(auto_now_add=True, help_text="Token creation timestamp")
+
+    expires_at = models.DateTimeField(
+        help_text="Token expiration timestamp (created_at + 24 hours)"
+    )
+
+    confirmed_at = models.DateTimeField(
+        blank=True, null=True, help_text="Timestamp when confirmed, NULL if pending"
+    )
+
+    ip_address = models.GenericIPAddressField(
+        blank=True,
+        null=True,
+        help_text="IP address of the request (for security audit)",
+    )
+
+    class Meta:
+        db_table = "password_resets"
+        verbose_name = "Password Reset"
+        verbose_name_plural = "Password Resets"
+        ordering = ["-created_at"]
+        indexes = [
+            models.Index(fields=["user"], name="idx_pwd_reset_user"),
+            models.Index(fields=["token"], name="idx_pwd_reset_token"),
+        ]
+
+    @property
+    def is_expired(self):
+        """Check if token has expired."""
+        return timezone.now() > self.expires_at
+
+    @property
+    def is_confirmed(self):
+        """Check if password reset has been confirmed."""
+        return self.confirmed_at is not None
+
+    def save(self, *args, **kwargs):
+        """Set expires_at if not already set (24 hours from creation)."""
+        if not self.expires_at:
+            self.expires_at = timezone.now() + timedelta(hours=24)
+
+        super().save(*args, **kwargs)
+
+    def __str__(self):
+        status = "✓" if self.confirmed_at else ("⏰" if not self.is_expired else "❌")
+        return f"{status} Password reset for {self.user}"
+
+
 class AccountLog(models.Model):
     """
     Audit trail for sensitive account operations.
@@ -420,6 +485,8 @@ class AccountLog(models.Model):
         ("USERNAME_CHANGED", "Username Changed"),
         ("EMAIL_CHANGED", "Email Changed"),
         ("PASSWORD_CHANGED", "Password Changed"),
+        ("PASSWORD_RESET_REQUESTED", "Password Reset Requested"),
+        ("PASSWORD_RESET_CONFIRMED", "Password Reset Confirmed"),
         ("ACCOUNT_DELETED", "Account Deleted"),
         ("EMAIL_CHANGE_REQUESTED", "Email Change Requested"),
         ("EMAIL_CHANGE_CONFIRMED", "Email Change Confirmed"),

backend/apps/authentication/serializers.py

@@ -358,3 +358,61 @@ class UsernameValidationSerializer(serializers.Serializer):
     """
 
     username = serializers.CharField(required=False, allow_blank=True)
+
+
+class PasswordResetRequestSerializer(serializers.Serializer):
+    """
+    Password reset request serializer.
+
+    Accepts email address to send password reset link.
+    """
+
+    email = serializers.EmailField(required=True)
+
+    def validate_email(self, value):
+        """
+        Validate email exists in system.
+        """
+        from .models import User
+
+        # Normalize email
+        email_normalized = value.lower().strip()
+        email_hash = User.hash_email(email_normalized)
+
+        try:
+            User.objects.get(email_hash=email_hash)
+        except User.DoesNotExist:
+            # Don't reveal whether email exists (security best practice)
+            # Return success message regardless
+            pass
+
+        return email_normalized
+
+
+class PasswordResetConfirmSerializer(serializers.Serializer):
+    """
+    Password reset confirmation serializer.
+
+    Validates token and new password for password reset.
+    """
+
+    token = serializers.CharField(max_length=128, required=True)
+    new_password = serializers.CharField(
+        write_only=True,
+        required=True,
+        validators=[validate_password],
+        style={"input_type": "password"},
+        min_length=8,
+        help_text="New password (minimum 8 characters, must contain uppercase, lowercase, and numbers)",
+    )
+
+    def validate_new_password(self, value):
+        """
+        Validate new password strength.
+        """
+        # Django's validate_password already runs
+        # Just ensure it meets minimum requirements
+        if len(value) < 8:
+            raise serializers.ValidationError("Password must be at least 8 characters long.")
+
+        return value