feat(auth): switch signup to OTP verification flow

Replace legacy signup with start/verify/resend endpoints, add OTP-focused mail templates and auth rate limits, and align compose/env/runbook for local self-hosted Supabase OTP behavior.

backend/tests/unit/v1/auth/test_auth_models.py

@@ -8,22 +8,34 @@ from v1.auth.schemas import (
     AuthUser,
     LoginRequest,
     RefreshRequest,
-    SignupRequest,
+    SignupStartRequest,
+    SignupVerifyRequest,
+    SignupResendRequest,
 )
 
 
 def test_signup_requires_valid_email() -> None:
     with pytest.raises(ValidationError):
-        SignupRequest(username="demo", email="not-an-email", password="secret123")
+        SignupStartRequest(username="demo", email="not-an-email", password="secret123")
 
 
 def test_signup_requires_username() -> None:
     with pytest.raises(ValidationError):
-        SignupRequest.model_validate(
+        SignupStartRequest.model_validate(
             {"email": "user@example.com", "password": "secret123"}
         )
 
 
+def test_signup_verify_requires_six_digit_token() -> None:
+    with pytest.raises(ValidationError):
+        SignupVerifyRequest(email="user@example.com", token="abc123")
+
+
+def test_signup_resend_requires_valid_email() -> None:
+    with pytest.raises(ValidationError):
+        SignupResendRequest(email="invalid")
+
+
 def test_login_requires_valid_email() -> None:
     with pytest.raises(ValidationError):
         LoginRequest(email="invalid", password="secret123")

backend/tests/unit/v1/auth/test_auth_service.py

@@ -5,11 +5,15 @@ import pytest
 import v1.auth.gateway as auth_gateway_module
 from v1.auth.schemas import (
     AuthTokenResponse,
+    AuthResendCodeResponse,
+    AuthSignupStartResponse,
     AuthUserByEmailResponse,
     AuthUser,
     LoginRequest,
     RefreshRequest,
-    SignupRequest,
+    SignupResendRequest,
+    SignupStartRequest,
+    SignupVerifyRequest,
 )
 from v1.auth.service import AuthService, AuthServiceGateway
 
@@ -18,9 +22,19 @@ class FakeGateway(AuthServiceGateway):
     def __init__(self, response: AuthTokenResponse) -> None:
         self._response = response
 
-    async def signup(self, request: SignupRequest) -> AuthTokenResponse:
+    async def signup_start(
+        self, request: SignupStartRequest
+    ) -> AuthSignupStartResponse:
+        return AuthSignupStartResponse(email=request.email)
+
+    async def signup_verify(self, request: SignupVerifyRequest) -> AuthTokenResponse:
         return self._response
 
+    async def signup_resend(
+        self, request: SignupResendRequest
+    ) -> AuthResendCodeResponse:
+        return AuthResendCodeResponse()
+
     async def login(self, request: LoginRequest) -> AuthTokenResponse:
         return self._response
 
@@ -51,8 +65,16 @@ async def test_signup_maps_response() -> None:
     )
     service = AuthService(gateway=FakeGateway(token_response))
 
-    result = await service.signup(
-        SignupRequest(username="demo", email="user@example.com", password="secret123")
+    start_result = await service.signup_start(
+        SignupStartRequest(
+            username="demo", email="user@example.com", password="secret123"
+        )
+    )
+    assert start_result.status == "pending_verification"
+    assert start_result.email == "user@example.com"
+
+    result = await service.signup_verify(
+        SignupVerifyRequest(email="user@example.com", token="123456")
     )
 
     assert result.access_token == "access"
@@ -64,7 +86,17 @@ class LogoutAssertingGateway(AuthServiceGateway):
     def __init__(self, expected_refresh_token: str) -> None:
         self._expected_refresh_token = expected_refresh_token
 
-    async def signup(self, request: SignupRequest) -> AuthTokenResponse:
+    async def signup_start(
+        self, request: SignupStartRequest
+    ) -> AuthSignupStartResponse:
+        raise NotImplementedError
+
+    async def signup_verify(self, request: SignupVerifyRequest) -> AuthTokenResponse:
+        raise NotImplementedError
+
+    async def signup_resend(
+        self, request: SignupResendRequest
+    ) -> AuthResendCodeResponse:
         raise NotImplementedError
 
     async def login(self, request: LoginRequest) -> AuthTokenResponse:
@@ -104,6 +136,23 @@ async def test_get_user_by_email_forwards_to_gateway() -> None:
     assert result.email == "user@example.com"
 
 
+@pytest.mark.asyncio
+async def test_signup_resend_returns_generic_message() -> None:
+    user = AuthUser(id="user-1", email="user@example.com")
+    token_response = AuthTokenResponse(
+        access_token="access",
+        refresh_token="refresh",
+        expires_in=3600,
+        token_type="bearer",
+        user=user,
+    )
+    service = AuthService(gateway=FakeGateway(token_response))
+
+    result = await service.signup_resend(SignupResendRequest(email="user@example.com"))
+
+    assert result.message == "If the email exists, a verification code has been sent"
+
+
 @pytest.mark.asyncio
 async def test_supabase_signup_passes_username_in_metadata(
     monkeypatch: pytest.MonkeyPatch,
@@ -126,7 +175,7 @@ async def test_supabase_signup_passes_username_in_metadata(
 
             class _Response:
                 user = _User()
-                session = _Session()
+                session = None
 
             return _Response()
 
@@ -136,8 +185,8 @@ async def test_supabase_signup_passes_username_in_metadata(
     monkeypatch.setattr(auth_gateway_module, "create_client", lambda *_: FakeClient())
 
     gateway = auth_gateway_module.SupabaseAuthGateway()
-    await gateway.signup(
-        SignupRequest(
+    await gateway.signup_start(
+        SignupStartRequest(
             username="demo",
             email="user@example.com",
             password="secret123",