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/src/v1/auth/gateway.py

@@ -9,12 +9,16 @@ from supabase import AuthError, create_client
 from core.config.settings import SupabaseSettings, config
 from core.logging import get_logger
 from v1.auth.schemas import (
+    AuthResendCodeResponse,
+    AuthSignupStartResponse,
     AuthTokenResponse,
     AuthUser,
     AuthUserByEmailResponse,
     LoginRequest,
     RefreshRequest,
-    SignupRequest,
+    SignupResendRequest,
+    SignupStartRequest,
+    SignupVerifyRequest,
 )
 from v1.auth.service import AuthServiceGateway
 
@@ -30,22 +34,53 @@ class SupabaseAuthGateway(AuthServiceGateway):
         self._client = create_client(settings.url, settings.anon_key)
         self._admin_client = create_client(settings.url, settings.service_role_key)
 
-    async def signup(self, request: SignupRequest) -> AuthTokenResponse:
+    async def signup_start(
+        self, request: SignupStartRequest
+    ) -> AuthSignupStartResponse:
         payload: dict[str, Any] = {
             "email": request.email,
             "password": request.password,
             "data": {"username": request.username},
         }
+        if request.redirect_to:
+            payload["options"] = {"email_redirect_to": request.redirect_to}
         try:
             sign_up = cast(Any, self._client.auth.sign_up)
-            response = await asyncio.to_thread(sign_up, payload)
-            return _map_auth_response(response, "Authentication failed")
+            await asyncio.to_thread(sign_up, payload)
+            return AuthSignupStartResponse(email=request.email)
         except AuthError as exc:
             logger.warning("Signup failed", error_type=type(exc).__name__)
             raise HTTPException(
-                status_code=401, detail="Authentication failed"
+                status_code=422, detail="Invalid signup request"
             ) from exc
 
+    async def signup_verify(self, request: SignupVerifyRequest) -> AuthTokenResponse:
+        payload: dict[str, Any] = {
+            "type": "signup",
+            "email": request.email,
+            "token": request.token,
+        }
+        try:
+            verify_otp = cast(Any, self._client.auth.verify_otp)
+            response = await asyncio.to_thread(verify_otp, payload)
+            return _map_auth_response(response, "Invalid verification code")
+        except AuthError as exc:
+            logger.warning("Signup verify failed", error_type=type(exc).__name__)
+            raise HTTPException(
+                status_code=401, detail="Invalid verification code"
+            ) from exc
+
+    async def signup_resend(
+        self, request: SignupResendRequest
+    ) -> AuthResendCodeResponse:
+        payload: dict[str, Any] = {"type": "signup", "email": request.email}
+        try:
+            resend = cast(Any, self._client.auth.resend)
+            await asyncio.to_thread(resend, payload)
+        except AuthError as exc:
+            logger.warning("Signup resend failed", error_type=type(exc).__name__)
+        return AuthResendCodeResponse()
+
     async def login(self, request: LoginRequest) -> AuthTokenResponse:
         payload: dict[str, Any] = {"email": request.email, "password": request.password}
         try: