feat: mail service

authsession/docs/flows.md

@@ -9,14 +9,14 @@ sequenceDiagram
     participant Auth
     participant Abuse as Resend throttle
     participant User as UserDirectory
-    participant Mail as MailSender
+    participant Mail as Mail Service REST
     participant Challenge as ChallengeStore
     participant Session as SessionStore
     participant Config as ConfigProvider
     participant Projection as Gateway projection publisher
 
-    Client->>Gateway: POST /api/v1/public/auth/send-email-code
-    Gateway->>Auth: POST /api/v1/public/auth/send-email-code
+    Client->>Gateway: POST /api/v1/public/auth/send-email-code + Accept-Language
+    Gateway->>Auth: POST /api/v1/public/auth/send-email-code + Accept-Language
     Auth->>Abuse: check and reserve cooldown
     alt throttled
         Abuse-->>Auth: throttled
@@ -30,8 +30,8 @@ sequenceDiagram
         alt blocked
             Auth->>Challenge: mark delivery_suppressed
         else not blocked
-            Auth->>Mail: SendLoginCode(email, code)
-            Mail-->>Auth: sent / suppressed / failure
+            Auth->>Mail: POST /api/v1/internal/login-code-deliveries + Idempotency-Key=challenge_id
+            Mail-->>Auth: 200 {outcome=sent|suppressed} / 503
             Auth->>Challenge: persist final delivery outcome
         end
         Auth-->>Gateway: 200 {challenge_id}
@@ -40,7 +40,7 @@ sequenceDiagram
     Client->>Gateway: POST /api/v1/public/auth/confirm-email-code
     Gateway->>Auth: POST /api/v1/public/auth/confirm-email-code
     Auth->>Challenge: load and validate challenge
-    Auth->>User: EnsureUserByEmail(email, registration_context)
+    Auth->>User: EnsureUserByEmail(email, stored preferred_language + time_zone)
     User-->>Auth: existing / created / blocked
     Auth->>Config: LoadSessionLimit()
     Auth->>Session: CountActiveByUserID(user_id)
@@ -51,6 +51,13 @@ sequenceDiagram
     Auth-->>Gateway: 200 {device_session_id}
 ```
 
+Auth uses the dedicated trusted `Mail Service` REST route
+`POST /api/v1/internal/login-code-deliveries`.
+It sends the created `challenge_id` as the raw `Idempotency-Key` header
+value.
+For this boundary, `sent` means durable acceptance into the mail-delivery
+pipeline; SMTP completion may still happen later in `Mail Service` workers.
+
 ## Revoke and Block Flow
 
 ```mermaid