fix: add CSRF tokens and convert account recovery to POST

Use double-submit CSRF cookies on state-changing requests, show a
confirmation form for account recovery, and keep auth cookies at
SameSite=strict after email promotion.

Author: chriscarrollsmith

.env.example

@@ -26,6 +26,9 @@ DB_NAME=
 # Domain for production (used by Caddy for TLS)
 DOMAIN=
 
+# Set to 0 to disable CSRF checks (not recommended in production)
+# CSRF_ENABLED=1
+
 # Resend
 RESEND_API_KEY=
 EMAIL_FROM=

exceptions/http_exceptions.py

@@ -246,3 +246,10 @@ def __init__(
             status_code=500,  # Internal Server Error
             detail=detail,
         )
+
+
+class CsrfError(HTTPException):
+    """Raised when CSRF validation fails."""
+
+    def __init__(self):
+        super().__init__(status_code=403, detail="CSRF validation failed")

main.py

@@ -21,6 +21,15 @@
     require_unauthenticated_client,
 )
 from utils.core.auth import refresh_token_is_persistent, set_auth_cookies
+from utils.core.csrf import (
+    CSRF_COOKIE_NAME,
+    UNSAFE_HTTP_METHODS,
+    csrf_enabled,
+    extract_submitted_csrf_token,
+    generate_csrf_token,
+    set_csrf_cookie,
+    validate_csrf_token,
+)
 from utils.core.htmx import (
     is_htmx_request,
     toast_response,
@@ -30,6 +39,7 @@
 from exceptions.http_exceptions import (
     AlreadyAuthenticatedError,
     AuthenticationError,
+    CsrfError,
     PasswordValidationError,
     CredentialsError,
     RateLimitError,
@@ -73,6 +83,22 @@ async def flash_cookie_middleware(request: Request, call_next):
     return response
 
 
+@app.middleware("http")
+async def csrf_middleware(request: Request, call_next):
+    token = request.cookies.get(CSRF_COOKIE_NAME) or generate_csrf_token()
+    request.state.csrf_token = token
+
+    if csrf_enabled() and request.method in UNSAFE_HTTP_METHODS:
+        submitted = await extract_submitted_csrf_token(request)
+        if not validate_csrf_token(request, submitted):
+            return await csrf_error_handler(request, CsrfError())
+
+    response = await call_next(request)
+    if request.cookies.get(CSRF_COOKIE_NAME) != token:
+        set_csrf_cookie(response, token)
+    return response
+
+
 # --- Include Routers ---
 
 
@@ -137,6 +163,25 @@ async def rate_limit_error_handler(request: Request, exc: RateLimitError):
     return response
 
 
+@app.exception_handler(CsrfError)
+async def csrf_error_handler(request: Request, exc: CsrfError):
+    if is_htmx_request(request):
+        return toast_response(
+            request,
+            templates,
+            exc.detail,
+            level="danger",
+            status_code=403,
+        )
+    user = await get_user_from_request(request)
+    return templates.TemplateResponse(
+        request,
+        "errors/error.html",
+        {"status_code": 403, "detail": exc.detail, "errors": None, "user": user},
+        status_code=403,
+    )
+
+
 # Handle CredentialsError (invalid email/password) with toast for HTMX
 @app.exception_handler(CredentialsError)
 async def credentials_exception_handler(request: Request, exc: CredentialsError):

routers/core/account.py

@@ -765,9 +765,28 @@ async def reset_password(
 
 
 @router.get("/recover")
-async def recover_account(
+async def recover_account_confirm(
+    request: Request,
     token: str = Query(...),
     session: Session = Depends(get_session),
+):
+    """Show a confirmation form before performing account recovery."""
+    account, recovery_token = get_account_from_recovery_token(token, session)
+
+    if not account or not recovery_token:
+        raise CredentialsError(message="Invalid or expired recovery token")
+
+    return templates.TemplateResponse(
+        request,
+        "account/recover_confirm.html",
+        {"token": token, "user": None},
+    )
+
+
+@router.post("/recover")
+async def recover_account(
+    token: str = Form(...),
+    session: Session = Depends(get_session),
 ):
     """
     Recover an account using a recovery token sent via email.
@@ -1023,7 +1042,6 @@ async def promote_email(
         access_token,
         refresh_token,
         persistent=False,
-        samesite="lax",
     )
     return response
 

static/js/app.js

@@ -16,6 +16,13 @@ document.body.addEventListener('htmx:configRequest', function() {
     }
 }, { once: true });
 
+document.body.addEventListener('htmx:configRequest', function(event) {
+    var meta = document.querySelector('meta[name="csrf-token"]');
+    if (meta && meta.content) {
+        event.detail.headers['X-CSRF-Token'] = meta.content;
+    }
+});
+
 
 // When a modal closes, reset any create-* form it contains so reopening it
 // starts blank. ui.js dispatches 'hidden.bs.modal' when a modal is hidden.

templates/account/forgot_password.html

@@ -1,5 +1,6 @@
 {% extends "account/auth_base.html" %}
 
+
 {% block title %}Forgot Password{% endblock %}
 
 {% block auth_header %}Forgot Password{% endblock %}
@@ -10,6 +11,7 @@
     <form method="POST" action="{{ url_for('forgot_password') }}"
           hx-post="{{ url_for('forgot_password') }}" hx-swap="none"
           class="needs-validation" novalidate>
+          {% include 'base/partials/csrf_field.html' %}
         <!-- Email Input -->
         <div class="mb-3">
             <label for="email" class="form-label">Email</label>

templates/account/login.html

@@ -1,5 +1,6 @@
 {% extends "account/auth_base.html" %}
 
+
 {% set show_warning_only = user and invitation_token_warning %}
 {% set warning_heading = "Invitation link expired" if invitation_token_warning == 'expired' else "Invitation link invalid" %}
 
@@ -27,6 +28,7 @@
     <form method="POST" action="{{ url_for('login') }}"
           hx-post="{{ url_for('login') }}" hx-swap="none"
           class="needs-validation" novalidate>
+          {% include 'base/partials/csrf_field.html' %}
         {# Add hidden input for invitation token if present #}
         {% if invitation_token %}
         <input type="hidden" name="invitation_token" value="{{ invitation_token }}">

templates/account/recover_confirm.html

@@ -0,0 +1,16 @@
+{% extends "account/auth_base.html" %}
+
+
+{% block auth_header %}Recover Your Account{% endblock %}
+
+{% block auth_content %}
+<p class="mb-4">
+    Use this page to restore your account email and sign out all active sessions.
+    You will be asked to set a new password after confirming.
+</p>
+<form action="{{ url_for('recover_account') }}" method="post">
+    {% include 'base/partials/csrf_field.html' %}
+    <input type="hidden" name="token" value="{{ token }}">
+    <button type="submit" class="btn btn-primary w-100">Recover account</button>
+</form>
+{% endblock %}

templates/account/register.html

@@ -1,5 +1,6 @@
 {% extends "account/auth_base.html" %}
 
+
 {% set show_warning_only = user and invitation_token_warning %}
 {% set warning_heading = "Invitation link expired" if invitation_token_warning == 'expired' else "Invitation link invalid" %}
 
@@ -27,6 +28,7 @@
     <form method="POST" action="{{ url_for('register') }}"
           hx-post="{{ url_for('register') }}" hx-swap="none"
           class="needs-validation" novalidate>
+          {% include 'base/partials/csrf_field.html' %}
         {# Add hidden input for invitation token if present #}
         {% if invitation_token %}
         <input type="hidden" name="invitation_token" value="{{ invitation_token }}">

templates/account/reset_password.html

@@ -1,5 +1,6 @@
 {% extends "account/auth_base.html" %}
 
+
 {% block title %}Reset Password{% endblock %}
 
 {% block auth_header %}Reset Password{% endblock %}
@@ -9,6 +10,7 @@
     <form method="POST" action="{{ url_for('reset_password') }}"
           hx-post="{{ url_for('reset_password') }}" hx-swap="none"
           class="needs-validation" novalidate>
+          {% include 'base/partials/csrf_field.html' %}
         <!-- Hidden Email Input -->
         <input type="hidden" name="email" value="{{ email }}">