tempest-fastapi-sdk 0.321.0__tar.gz → 0.322.0__tar.gz

{tempest_fastapi_sdk-0.321.0 → tempest_fastapi_sdk-0.322.0}/CHANGELOG.md

@@ -7,6 +7,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.322.0] — 2026-10-21
+
+### Added
+
+- `EmailDeliveryException` (`503`, `code="EMAIL_UNAVAILABLE"`, sem
+  `details`), exportada no topo ao lado da `IntegrationDisabledException`,
+  com mensagem no catálogo em pt-BR e en-US. Distingue o e-mail configurado
+  e falhando do e-mail desligado (`INTEGRATION_DISABLED`).
+- Regra de produção do `EmailSettings` (com `EMAIL_ENABLED` ligado):
+  `SMTP_USE_SSL` e `SMTP_USE_TLS` os dois `true`, `SMTP_USE_SSL=true` com
+  `SMTP_PORT=587` e `SMTP_USE_TLS=true` com `SMTP_PORT=465` viram violação,
+  e a mensagem diz o par que a porta pede. Outras portas não são julgadas.
+
+### Changed
+
+- `EmailUtils.send` levanta `EmailDeliveryException` em toda falha de
+  transporte (DNS, conexão recusada ou com timeout, handshake TLS, login
+  negado, mensagem recusada) em vez de deixar escapar o erro do
+  `aiosmtplib` — **quem pega `aiosmtplib.SMTPException` em volta do envio
+  precisa pegar `EmailDeliveryException`**; falha de rede ou TLS encadeia o
+  erro original em `__cause__`, e recusa respondida pelo servidor sai
+  `from None` (a resposta pode citar o endereço, e o handler de
+  `AppException` loga todo 5xx com traceback). Antes de levantar, loga uma vez em `ERROR` com `smtp_host` e
+  `smtp_port` (nunca destinatário nem credencial; recusa respondida pelo
+  servidor vai sem traceback, porque a resposta pode citar o endereço).
+  Erro do chamador (anexo que não existe, `ValueError`) segue com o tipo
+  original. `send_many` levanta a mesma exceção para falha da operação
+  (conexão, login, queda no meio do lote); recusa por destinatário continua
+  no relatório.
+- Rotas do `make_auth_router` com o SMTP falhando: `/signup`,
+  `/email-change/request`, `/email-change/confirm` (aviso ao endereço
+  antigo), `/email-verify/request` e `/email-recovery/request` (depois da
+  senha e do MFA) respondem `503 EMAIL_UNAVAILABLE` em vez de `500`, sem
+  gravar nada — a confirmação de troca mantém o e-mail antigo e o link
+  válido. `/activation/request` e `/password-reset/request` continuam
+  respondendo o `202` de sempre (um `503` só para conta existente seria
+  oráculo de enumeração): a falha é logada e o token só é gravado depois
+  que o e-mail sai, então o link pendente anterior não é invalidado.
+- **Serviço com o modo TLS trocado com a porta deixa de subir em
+  `ENV=production`** (a regra nova acima). Antes de atualizar, confira
+  `SMTP_PORT`/`SMTP_USE_TLS`/`SMTP_USE_SSL`: `587` pede `SMTP_USE_TLS=true`
+  e `SMTP_USE_SSL=false`; `465` pede o contrário.
+- `tempest email test` mostra o erro SMTP encadeado (por exemplo
+  `[SSL: WRONG_VERSION_NUMBER]`) em vez da mensagem genérica do `503`.
+
 ## [0.321.0] — 2026-10-21
 
 ### Added

{tempest_fastapi_sdk-0.321.0 → tempest_fastapi_sdk-0.322.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tempest-fastapi-sdk
-Version: 0.321.0
+Version: 0.322.0
 Summary: Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects.
 Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
 Project-URL: Repository, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
@@ -1693,10 +1693,12 @@ mailer = EmailUtils(
 ```python
 # src/services/password_reset.py
 
+import logging
 from datetime import timedelta
 from uuid import UUID
 
 from tempest_fastapi_sdk import (
+    EmailDeliveryException,
     EmailUtils,
     InvalidTokenException,
     JWTUtils,
@@ -1706,6 +1708,8 @@ from tempest_fastapi_sdk import (
 
 from src.db.repositories import UserRepository
 
+logger: logging.Logger = logging.getLogger(__name__)
+
 
 class PasswordResetService:
     def __init__(
@@ -1722,7 +1726,10 @@ class PasswordResetService:
         """Send a password-reset link to `email`.
 
         Always returns silently — don't reveal whether the email
-        is registered or not (avoids account enumeration).
+        is registered or not (avoids account enumeration). That
+        includes an SMTP failure: `send` raises
+        `EmailDeliveryException` (503), which only a registered
+        address could trigger, so it is logged, not raised.
         """
         user = await self.repo.get_or_none({"email": email})
         if user is None:
@@ -1732,12 +1739,15 @@ class PasswordResetService:
             ttl=timedelta(minutes=15),
         )
         reset_url = f"https://my-app.com/reset-password?token={token}"
-        await self.mailer.send(
-            to=user.email,
-            subject="Reset your password",
-            body=f"Click here to reset your password: {reset_url}",
-            html=f'<p>Click <a href="{reset_url}">here</a> to reset.</p>',
-        )
+        try:
+            await self.mailer.send(
+                to=user.email,
+                subject="Reset your password",
+                body=f"Click here to reset your password: {reset_url}",
+                html=f'<p>Click <a href="{reset_url}">here</a> to reset.</p>',
+            )
+        except EmailDeliveryException:
+            logger.error("Reset link not sent; answer kept the same")
 
     async def consume_reset(
         self,
@@ -2540,7 +2550,7 @@ Each mixin owns its own env-var prefix — pick only the ones the service needs:
 | `WebPushSettings` | `VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY`, `VAPID_SUBJECT`, `WEBPUSH_DEFAULT_TTL_SECONDS` |
 | `StorageSettings` | `STORAGE_ENABLED`, `STORAGE_ENDPOINT`, `STORAGE_ACCESS_KEY`, `STORAGE_SECRET_KEY`, `STORAGE_SECURE`, `STORAGE_REGION`, `STORAGE_DEFAULT_BUCKET`, `STORAGE_PUBLIC_ENDPOINT`, `STORAGE_PUBLIC_SECURE`, `STORAGE_ACCEL_REDIRECT`, `STORAGE_ACCEL_PREFIX` |
 
-**Production guard.** Compose `EnvironmentSettings` and set `ENV=production`: the settings then refuse to build while any composed mixin still holds a development value — SQLite in `DATABASE_URL`, the placeholder `JWT_SECRET`, `"*"` in `CORS_ORIGINS`, an empty `TOKEN_SECRET`, `SERVER_DEBUG` / `SERVER_RELOAD` on, an empty `TASKIQ_BROKER_URL` (the in-memory broker), the `minioadmin` storage keys or `STORAGE_SECURE=false`, a Mailpit/MailHog SMTP host or a placeholder `SMTP_FROM_ADDR` (`noreply@example.com`). Every offending field is listed in one error, by name, never by value. Each mixin declares its own rules in `production_violations()`; override it (calling `super()`) to add a rule of yours or drop one you accepted on purpose. `BaseAppSettings` also sets `hide_input_in_errors=True`, so no validation error echoes the environment. An integration that ships later is switched off instead of faked: `STORAGE_ENABLED`, `EMAIL_ENABLED`, `FIREBASE_ENABLED` or `REVENUECAT_ENABLED` set to `false` skips that mixin's rules, lists it in `settings.disabled_integrations()`, and makes the client built from the same settings (`AsyncMinIOClient(**settings.storage_kwargs())`, `EmailUtils(**settings.email_kwargs())`, `FirebaseAuth(**settings.firebase_kwargs())`) refuse every call with `IntegrationDisabledException` — `503`, `code="INTEGRATION_DISABLED"`.
+**Production guard.** Compose `EnvironmentSettings` and set `ENV=production`: the settings then refuse to build while any composed mixin still holds a development value — SQLite in `DATABASE_URL`, the placeholder `JWT_SECRET`, `"*"` in `CORS_ORIGINS`, an empty `TOKEN_SECRET`, `SERVER_DEBUG` / `SERVER_RELOAD` on, an empty `TASKIQ_BROKER_URL` (the in-memory broker), the `minioadmin` storage keys or `STORAGE_SECURE=false`, a Mailpit/MailHog SMTP host, a placeholder `SMTP_FROM_ADDR` (`noreply@example.com`), or a TLS mode swapped with the port (`SMTP_USE_SSL=true` on `587`, `SMTP_USE_TLS=true` on `465`, or both on). Every offending field is listed in one error, by name, never by value. Each mixin declares its own rules in `production_violations()`; override it (calling `super()`) to add a rule of yours or drop one you accepted on purpose. `BaseAppSettings` also sets `hide_input_in_errors=True`, so no validation error echoes the environment. An integration that ships later is switched off instead of faked: `STORAGE_ENABLED`, `EMAIL_ENABLED`, `FIREBASE_ENABLED` or `REVENUECAT_ENABLED` set to `false` skips that mixin's rules, lists it in `settings.disabled_integrations()`, and makes the client built from the same settings (`AsyncMinIOClient(**settings.storage_kwargs())`, `EmailUtils(**settings.email_kwargs())`, `FirebaseAuth(**settings.firebase_kwargs())`) refuse every call with `IntegrationDisabledException` — `503`, `code="INTEGRATION_DISABLED"`.
 
 **`MinIOSettings` → `StorageSettings`.** The storage mixin speaks to any S3-compatible target, so its variables are now `STORAGE_*`. The old `MINIO_*` names keep working — each field reads `STORAGE_X` first and falls back to `MINIO_X` — and setting both names of a pair to different values refuses to boot instead of silently picking one. `MinIOSettings` stays importable as a deprecated subclass (it emits `DeprecationWarning` and keeps the `settings.MINIO_*` attributes); `minio_kwargs()` returns the same dict as the new `storage_kwargs()`.
 

{tempest_fastapi_sdk-0.321.0 → tempest_fastapi_sdk-0.322.0}/README.md

@@ -1474,10 +1474,12 @@ mailer = EmailUtils(
 ```python
 # src/services/password_reset.py
 
+import logging
 from datetime import timedelta
 from uuid import UUID
 
 from tempest_fastapi_sdk import (
+    EmailDeliveryException,
     EmailUtils,
     InvalidTokenException,
     JWTUtils,
@@ -1487,6 +1489,8 @@ from tempest_fastapi_sdk import (
 
 from src.db.repositories import UserRepository
 
+logger: logging.Logger = logging.getLogger(__name__)
+
 
 class PasswordResetService:
     def __init__(
@@ -1503,7 +1507,10 @@ class PasswordResetService:
         """Send a password-reset link to `email`.
 
         Always returns silently — don't reveal whether the email
-        is registered or not (avoids account enumeration).
+        is registered or not (avoids account enumeration). That
+        includes an SMTP failure: `send` raises
+        `EmailDeliveryException` (503), which only a registered
+        address could trigger, so it is logged, not raised.
         """
         user = await self.repo.get_or_none({"email": email})
         if user is None:
@@ -1513,12 +1520,15 @@ class PasswordResetService:
             ttl=timedelta(minutes=15),
         )
         reset_url = f"https://my-app.com/reset-password?token={token}"
-        await self.mailer.send(
-            to=user.email,
-            subject="Reset your password",
-            body=f"Click here to reset your password: {reset_url}",
-            html=f'<p>Click <a href="{reset_url}">here</a> to reset.</p>',
-        )
+        try:
+            await self.mailer.send(
+                to=user.email,
+                subject="Reset your password",
+                body=f"Click here to reset your password: {reset_url}",
+                html=f'<p>Click <a href="{reset_url}">here</a> to reset.</p>',
+            )
+        except EmailDeliveryException:
+            logger.error("Reset link not sent; answer kept the same")
 
     async def consume_reset(
         self,
@@ -2321,7 +2331,7 @@ Each mixin owns its own env-var prefix — pick only the ones the service needs:
 | `WebPushSettings` | `VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY`, `VAPID_SUBJECT`, `WEBPUSH_DEFAULT_TTL_SECONDS` |
 | `StorageSettings` | `STORAGE_ENABLED`, `STORAGE_ENDPOINT`, `STORAGE_ACCESS_KEY`, `STORAGE_SECRET_KEY`, `STORAGE_SECURE`, `STORAGE_REGION`, `STORAGE_DEFAULT_BUCKET`, `STORAGE_PUBLIC_ENDPOINT`, `STORAGE_PUBLIC_SECURE`, `STORAGE_ACCEL_REDIRECT`, `STORAGE_ACCEL_PREFIX` |
 
-**Production guard.** Compose `EnvironmentSettings` and set `ENV=production`: the settings then refuse to build while any composed mixin still holds a development value — SQLite in `DATABASE_URL`, the placeholder `JWT_SECRET`, `"*"` in `CORS_ORIGINS`, an empty `TOKEN_SECRET`, `SERVER_DEBUG` / `SERVER_RELOAD` on, an empty `TASKIQ_BROKER_URL` (the in-memory broker), the `minioadmin` storage keys or `STORAGE_SECURE=false`, a Mailpit/MailHog SMTP host or a placeholder `SMTP_FROM_ADDR` (`noreply@example.com`). Every offending field is listed in one error, by name, never by value. Each mixin declares its own rules in `production_violations()`; override it (calling `super()`) to add a rule of yours or drop one you accepted on purpose. `BaseAppSettings` also sets `hide_input_in_errors=True`, so no validation error echoes the environment. An integration that ships later is switched off instead of faked: `STORAGE_ENABLED`, `EMAIL_ENABLED`, `FIREBASE_ENABLED` or `REVENUECAT_ENABLED` set to `false` skips that mixin's rules, lists it in `settings.disabled_integrations()`, and makes the client built from the same settings (`AsyncMinIOClient(**settings.storage_kwargs())`, `EmailUtils(**settings.email_kwargs())`, `FirebaseAuth(**settings.firebase_kwargs())`) refuse every call with `IntegrationDisabledException` — `503`, `code="INTEGRATION_DISABLED"`.
+**Production guard.** Compose `EnvironmentSettings` and set `ENV=production`: the settings then refuse to build while any composed mixin still holds a development value — SQLite in `DATABASE_URL`, the placeholder `JWT_SECRET`, `"*"` in `CORS_ORIGINS`, an empty `TOKEN_SECRET`, `SERVER_DEBUG` / `SERVER_RELOAD` on, an empty `TASKIQ_BROKER_URL` (the in-memory broker), the `minioadmin` storage keys or `STORAGE_SECURE=false`, a Mailpit/MailHog SMTP host, a placeholder `SMTP_FROM_ADDR` (`noreply@example.com`), or a TLS mode swapped with the port (`SMTP_USE_SSL=true` on `587`, `SMTP_USE_TLS=true` on `465`, or both on). Every offending field is listed in one error, by name, never by value. Each mixin declares its own rules in `production_violations()`; override it (calling `super()`) to add a rule of yours or drop one you accepted on purpose. `BaseAppSettings` also sets `hide_input_in_errors=True`, so no validation error echoes the environment. An integration that ships later is switched off instead of faked: `STORAGE_ENABLED`, `EMAIL_ENABLED`, `FIREBASE_ENABLED` or `REVENUECAT_ENABLED` set to `false` skips that mixin's rules, lists it in `settings.disabled_integrations()`, and makes the client built from the same settings (`AsyncMinIOClient(**settings.storage_kwargs())`, `EmailUtils(**settings.email_kwargs())`, `FirebaseAuth(**settings.firebase_kwargs())`) refuse every call with `IntegrationDisabledException` — `503`, `code="INTEGRATION_DISABLED"`.
 
 **`MinIOSettings` → `StorageSettings`.** The storage mixin speaks to any S3-compatible target, so its variables are now `STORAGE_*`. The old `MINIO_*` names keep working — each field reads `STORAGE_X` first and falls back to `MINIO_X` — and setting both names of a pair to different values refuses to boot instead of silently picking one. `MinIOSettings` stays importable as a deprecated subclass (it emits `DeprecationWarning` and keeps the `settings.MINIO_*` attributes); `minio_kwargs()` returns the same dict as the new `storage_kwargs()`.
 

{tempest_fastapi_sdk-0.321.0 → tempest_fastapi_sdk-0.322.0}/SHIPPED.md

@@ -3601,3 +3601,19 @@ cadastro pendente comum. Com `AUTH_AUTO_ACTIVATE=true` o cadastro não consulta
   local/reservado ou sem `https` (pula com `EMAIL_ENABLED=false`).
   `is_reserved_domain` é compartilhado com a regra do `SMTP_FROM_ADDR`.
   Testes: `tests/settings/test_auth_link_guard.py`.
+- **SMTP fora do ar vira `503 EMAIL_UNAVAILABLE`, Unreleased** —
+  `EmailUtils.send` e `send_many` traduzem falha de transporte
+  (`aiosmtplib.SMTPException`, `OSError`, timeout, TLS) em
+  `EmailDeliveryException` (`503`, sem `details`, causa encadeada), logando
+  uma vez em `ERROR` só com host e porta. No `make_auth_router`: cadastro,
+  troca/confirmação/verificação de e-mail e recuperação (depois da senha)
+  respondem `503` e o rollback leva tudo; reenvio de ativação e reset de
+  senha respondem o `202` de sempre, logam e não gravam token
+  (`UserAuthService._issue_token_after_mail` manda antes de gravar). Regra de
+  produção do `EmailSettings`: `SMTP_USE_SSL` + `SMTP_USE_TLS`,
+  `SMTP_USE_SSL` na 587, `SMTP_USE_TLS` na 465. Receitas:
+  `docs/recipes/email.md`, `docs/recipes/auth-flow.md` ("SMTP fora do ar").
+  Testes: `tests/utils/test_email.py` (`TestTransportFailure`),
+  `tests/auth/test_email_delivery_failure.py`,
+  `tests/settings/test_integration_flags.py` (`TestEmailTLSModeRule`),
+  `tests/cli/test_email_storage.py`.

{tempest_fastapi_sdk-0.321.0 → tempest_fastapi_sdk-0.322.0}/docs/migration.en.md

@@ -2,6 +2,29 @@
 
 Breaking-change walkthroughs grouped by minor release. Stick to the version that matches what you're upgrading **from**. The release sections are listed newest-first, so on a multi-version jump read and apply them bottom-up.
 
+## 0.322.0 — SMTP failure becomes `503 EMAIL_UNAVAILABLE` and the guard checks TLS × port
+
+`EmailUtils.send` and `send_many` now raise `EmailDeliveryException`
+(`503`, `code="EMAIL_UNAVAILABLE"`) on every transport failure instead of the
+`aiosmtplib` error. With `ENV=production` and e-mail enabled,
+`EmailSettings` refuses a TLS mode that does not match the port.
+
+### What to do
+
+- Code that caught `aiosmtplib.SMTPException` (or `OSError`) around a send:
+  catch `EmailDeliveryException` (exported at the package top level). A
+  network or TLS failure carries the original error in `__cause__`; a refusal
+  answered by the server is raised `from None`.
+- Check `SMTP_PORT`, `SMTP_USE_TLS` and `SMTP_USE_SSL` before deploying to
+  production: `587` needs `SMTP_USE_TLS=true` and `SMTP_USE_SSL=false`;
+  `465` needs `SMTP_USE_SSL=true` and `SMTP_USE_TLS=false`. Both enabled
+  also fails the boot.
+- `make_auth_router` clients: `/signup`, `/email-change/*`,
+  `/email-verify/request` and `/email-recovery/request` may answer
+  `503 EMAIL_UNAVAILABLE` (nothing stored; safe to retry).
+  `/activation/request` and `/password-reset/request` keep their usual
+  `202`.
+
 ## 0.321.0 — `SubjectStorageClient` gains three methods
 
 The `SubjectStorageClient` protocol (the type of `SubjectObjectStorage.client`)

{tempest_fastapi_sdk-0.321.0 → tempest_fastapi_sdk-0.322.0}/docs/migration.md

@@ -2,6 +2,29 @@
 
 Passo a passo das mudanças que quebram compatibilidade, agrupadas por release minor. Siga a versão que casa com aquela **de onde** você está atualizando. As seções estão listadas da mais nova para a mais antiga, então num salto de várias versões leia e aplique-as de baixo para cima.
 
+## 0.322.0 — falha de SMTP vira `503 EMAIL_UNAVAILABLE` e o guard confere TLS × porta
+
+`EmailUtils.send` e `send_many` passam a levantar `EmailDeliveryException`
+(`503`, `code="EMAIL_UNAVAILABLE"`) em toda falha de transporte, no lugar do
+erro do `aiosmtplib`. Com `ENV=production` e o e-mail ligado, o
+`EmailSettings` recusa o modo TLS trocado com a porta.
+
+### O que fazer
+
+- Código que pegava `aiosmtplib.SMTPException` (ou `OSError`) em volta do
+  envio: pegue `EmailDeliveryException` (exportada no topo do pacote). Falha
+  de rede ou TLS traz o erro original em `__cause__`; recusa respondida pelo
+  servidor sai `from None`.
+- Confira `SMTP_PORT`, `SMTP_USE_TLS` e `SMTP_USE_SSL` antes de subir em
+  produção: `587` pede `SMTP_USE_TLS=true` e `SMTP_USE_SSL=false`; `465`
+  pede `SMTP_USE_SSL=true` e `SMTP_USE_TLS=false`. Os dois ligados também
+  derrubam o boot.
+- Cliente do `make_auth_router`: `/signup`, `/email-change/*`,
+  `/email-verify/request` e `/email-recovery/request` podem responder
+  `503 EMAIL_UNAVAILABLE` (nada gravado; pode tentar de novo).
+  `/activation/request` e `/password-reset/request` seguem no `202` de
+  sempre.
+
 ## 0.321.0 — `SubjectStorageClient` ganha três métodos
 
 O protocolo `SubjectStorageClient` (o tipo do `client` do

{tempest_fastapi_sdk-0.321.0 → tempest_fastapi_sdk-0.322.0}/docs/recipes/auth-flow.en.md

@@ -37,6 +37,7 @@ Since v0.31.0 the SDK ships the full local-account lifecycle — email + passwor
 9. **[Email and page language (i18n)](#email-and-page-language-i18n)** — default language, per-user preference and your own translation.
 10. **[Five operating modes](#five-operating-modes)** — production, dev with local SMTP (Mailhog / smtp4dev), dev without SMTP, CI without activation, and **backend-only** (links and pages served directly by the backend).
     - **[Email disabled](#email-disabled)** — `EMAIL_ENABLED=false` in a phased deploy: the routes that would mail a link answer `503` before writing.
+    - **[SMTP server down](#smtp-server-down)** — e-mail configured and failing: `503 EMAIL_UNAVAILABLE` writing nothing, and `202` where the answer must not reveal the account.
 11. **[Token delivery](#token-delivery)** — bearer, cookie or both.
 12. **[Mailhog vs smtp4dev — which to pick for local dev](#mailhog-vs-smtp4dev)** — comparison + copy-paste docker-compose snippets.
 13. **[Customizing email templates](#customizing-templates)** — override `activation.html` and `password_reset.html` + variables exposed to the Jinja2 context.
@@ -2295,6 +2296,140 @@ logout and MFA are unaffected.
     address get the same answer — the switch never becomes an enumeration
     oracle.
 
+## SMTP server down
+
+`EMAIL_ENABLED=false` is choosing to run without e-mail. The opposite case
+is e-mail that is **configured and failing**: the host does not resolve,
+the connection is refused, the TLS handshake breaks (`SMTP_USE_SSL=true`
+on port `587` answers `[SSL: WRONG_VERSION_NUMBER]` on every send), the
+login is rejected. Before, that surfaced as an `aiosmtplib` error and the
+route answered a bare `500`, with the traceback logged as an unhandled
+exception.
+
+Now `EmailUtils.send` turns every transport failure into
+`EmailDeliveryException` — `503`, `code="EMAIL_UNAVAILABLE"`, no
+`details` — and each auth flow decides what to do with it:
+
+```python
+import asyncio
+
+from fastapi import FastAPI
+from httpx import ASGITransport, AsyncClient
+
+from tempest_fastapi_sdk import (
+    AsyncDatabaseManager,
+    AuthSettings,
+    BaseUserModel,
+    EmailSettings,
+    EmailUtils,
+    JWTSettings,
+    UserAuthService,
+    make_auth_router,
+    make_user_token_model,
+    register_exception_handlers,
+)
+
+
+class Settings(EmailSettings, JWTSettings, AuthSettings):
+    """Settings with an SMTP server that does not answer."""
+
+
+class UserModel(BaseUserModel):
+    """The accounts table."""
+
+    __tablename__ = "users"
+
+
+UserTokenModel = make_user_token_model(user_table="users")
+
+settings: Settings = Settings(
+    SMTP_HOST="127.0.0.1",
+    SMTP_PORT=2525,
+    SMTP_TIMEOUT_SECONDS=5.0,
+    AUTH_AUTO_ACTIVATE=False,
+    JWT_SECRET="replace-with-a-real-long-secret-0123456789",
+)
+db: AsyncDatabaseManager = AsyncDatabaseManager("sqlite+aiosqlite:///:memory:")
+auth_service: UserAuthService = UserAuthService(
+    db=db,
+    user_model=UserModel,
+    token_model=UserTokenModel,
+    auth_settings=settings,
+    jwt_settings=settings,
+    email=EmailUtils(**settings.email_kwargs()),
+)
+
+app: FastAPI = FastAPI()
+register_exception_handlers(app)
+app.include_router(make_auth_router(auth_service, session_factory=db.session_dependency))
+
+
+async def main() -> None:
+    """Try a signup with the SMTP server down."""
+    await db.connect()
+    await db.create_tables()
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        response = await client.post(
+            "/auth/signup",
+            json={"email": "ana@acme.com.br", "password": "strong-pass-123"},
+        )
+    print(response.status_code, response.json())
+    await db.disconnect()
+
+
+asyncio.run(main())
+```
+
+```text
+503 {'detail': 'The e-mail server could not be reached; try again later', 'code': 'EMAIL_UNAVAILABLE', 'details': {}}
+```
+
+No row was written: the flush of the account and its token never reached
+the commit, and the request session discarded both. The same address can
+sign up again once the server is back.
+
+### What each route answers
+
+| Route | With SMTP failing | What is stored |
+| --- | --- | --- |
+| `/signup` | `503 EMAIL_UNAVAILABLE` | nothing: no account, no token |
+| `/email-change/request` | `503 EMAIL_UNAVAILABLE` | nothing; an earlier pending link keeps working |
+| `/email-change/confirm` (with `AUTH_EMAIL_CHANGE_NOTIFY_OLD=true`) | `503 EMAIL_UNAVAILABLE` | nothing: the address does not change and the same link confirms later |
+| `/email-verify/request` | `503 EMAIL_UNAVAILABLE` | nothing |
+| `/email-recovery/request` (password and MFA correct) | `503 EMAIL_UNAVAILABLE` | nothing |
+| `/activation/request` | `202`, the same answer as an unknown address | nothing; the earlier link keeps working |
+| `/password-reset/request` | `202`, the same answer as an unknown address | nothing; the earlier link keeps working |
+
+The rule is what the response already reveals. Signup already answers
+`409` for an address in use; e-mail change and verification require a
+login; e-mail recovery reaches the send only after the password (and MFA)
+matched — the same point where a taken `new_email` answers `409`. On
+those routes the `503` tells the caller nothing new.
+
+!!! warning "Reset and activation re-send keep answering `202`"
+    These two routes answer the same for a registered and an unknown
+    address, on purpose. If the send failure became a `503`, it would show
+    up only for accounts that exist — and the route would become an
+    enumeration oracle. So the failure is **logged at `ERROR`** (without
+    the address) and the answer stays `202`. The token is stored only
+    **after** the mail went out, so the failure writes nothing and the
+    earlier pending link is not invalidated.
+
+!!! info "What reaches the log"
+    `EmailUtils` logs once, at `ERROR`, with `smtp_host` and `smtp_port`
+    — never the recipient nor the credential. A network or TLS failure
+    carries the traceback (that is where the diagnosis lives); a refusal
+    the server answered (a `550` for one recipient, say) does not,
+    because the reply text can quote the address. For the same reason,
+    only a network or TLS failure is chained as `__cause__`; a refusal is
+    raised `from None`, so the handler that logs every 5xx has nothing to
+    print.
+
+When you call `UserAuthService` outside `make_auth_router`, the rule is
+the one for any error after a flush: roll the session back before reusing
+it. The router does that on its own, because it never reaches the commit.
+
 ## Token delivery
 
 *(v0.87.0+)*

{tempest_fastapi_sdk-0.321.0 → tempest_fastapi_sdk-0.322.0}/docs/recipes/auth-flow.md

@@ -37,6 +37,7 @@ Desde v0.31.0 o SDK fornece o ciclo completo de conta local — signup com email
 9. **[Idioma dos e-mails e páginas (i18n)](#idioma-dos-e-mails-e-paginas-i18n)** — idioma padrão, preferência por usuário e tradução própria.
 10. **[Cinco modos de operação](#cinco-modos-de-operacao)** — produção, dev com SMTP local (Mailhog / smtp4dev), dev sem SMTP, CI sem ativação e **backend-only** (links e páginas servidas direto pelo backend).
     - **[E-mail desligado](#e-mail-desligado)** — `EMAIL_ENABLED=false` num deploy por partes: as rotas que mandariam link respondem `503` antes de gravar.
+    - **[SMTP fora do ar](#smtp-fora-do-ar)** — e-mail configurado e falhando: `503 EMAIL_UNAVAILABLE` sem gravar nada, e `202` onde a resposta não pode revelar a conta.
 11. **[Entrega de token](#entrega-de-token)** — bearer, cookie ou os dois.
 12. **[Mailhog vs smtp4dev — qual escolher pra dev local](#mailhog-vs-smtp4dev)** — comparativo + receitas docker-compose copy-paste.
 13. **[Customizando os templates de e-mail](#customizando-templates)** — override do `activation.html` e `password_reset.html` + variáveis disponíveis no contexto Jinja2.
@@ -2267,6 +2268,140 @@ refresh, logout e MFA seguem normais.
     recebem a mesma resposta — o interruptor não vira oráculo de
     enumeração.
 
+## SMTP fora do ar
+
+`EMAIL_ENABLED=false` é a escolha de rodar sem e-mail. O caso oposto é o
+e-mail **configurado e falhando**: o host não resolve, a conexão é
+recusada, o handshake TLS quebra (`SMTP_USE_SSL=true` na porta `587`
+responde `[SSL: WRONG_VERSION_NUMBER]` em todo envio), o login é negado.
+Antes, isso subia como erro do `aiosmtplib` e a rota respondia um `500`
+pelado, com o traceback logado como exceção não tratada.
+
+Agora o `EmailUtils.send` traduz toda falha de transporte em
+`EmailDeliveryException` — `503`, `code="EMAIL_UNAVAILABLE"`, sem
+`details` — e cada fluxo de auth decide o que fazer com ela:
+
+```python
+import asyncio
+
+from fastapi import FastAPI
+from httpx import ASGITransport, AsyncClient
+
+from tempest_fastapi_sdk import (
+    AsyncDatabaseManager,
+    AuthSettings,
+    BaseUserModel,
+    EmailSettings,
+    EmailUtils,
+    JWTSettings,
+    UserAuthService,
+    make_auth_router,
+    make_user_token_model,
+    register_exception_handlers,
+)
+
+
+class Settings(EmailSettings, JWTSettings, AuthSettings):
+    """Settings com um SMTP que não atende."""
+
+
+class UserModel(BaseUserModel):
+    """A tabela de contas."""
+
+    __tablename__ = "users"
+
+
+UserTokenModel = make_user_token_model(user_table="users")
+
+settings: Settings = Settings(
+    SMTP_HOST="127.0.0.1",
+    SMTP_PORT=2525,
+    SMTP_TIMEOUT_SECONDS=5.0,
+    AUTH_AUTO_ACTIVATE=False,
+    JWT_SECRET="troque-por-um-segredo-longo-de-verdade-0123456789",
+)
+db: AsyncDatabaseManager = AsyncDatabaseManager("sqlite+aiosqlite:///:memory:")
+auth_service: UserAuthService = UserAuthService(
+    db=db,
+    user_model=UserModel,
+    token_model=UserTokenModel,
+    auth_settings=settings,
+    jwt_settings=settings,
+    email=EmailUtils(**settings.email_kwargs()),
+)
+
+app: FastAPI = FastAPI()
+register_exception_handlers(app)
+app.include_router(make_auth_router(auth_service, session_factory=db.session_dependency))
+
+
+async def main() -> None:
+    """Tenta um cadastro com o SMTP fora do ar."""
+    await db.connect()
+    await db.create_tables()
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        response = await client.post(
+            "/auth/signup",
+            json={"email": "ana@acme.com.br", "password": "senha-forte-123"},
+        )
+    print(response.status_code, response.json())
+    await db.disconnect()
+
+
+asyncio.run(main())
+```
+
+```text
+503 {'detail': 'The e-mail server could not be reached; try again later', 'code': 'EMAIL_UNAVAILABLE', 'details': {}}
+```
+
+Nenhuma linha foi gravada: o `flush` da conta e do token não chegou ao
+`commit`, e a sessão da requisição desfez os dois. O mesmo endereço pode
+se cadastrar de novo quando o servidor voltar.
+
+### O que cada rota responde
+
+| Rota | Com o SMTP falhando | O que fica gravado |
+| --- | --- | --- |
+| `/signup` | `503 EMAIL_UNAVAILABLE` | nada: nem conta, nem token |
+| `/email-change/request` | `503 EMAIL_UNAVAILABLE` | nada; um link pendente anterior continua valendo |
+| `/email-change/confirm` (com `AUTH_EMAIL_CHANGE_NOTIFY_OLD=true`) | `503 EMAIL_UNAVAILABLE` | nada: o e-mail não muda e o mesmo link confirma depois |
+| `/email-verify/request` | `503 EMAIL_UNAVAILABLE` | nada |
+| `/email-recovery/request` (senha e MFA corretos) | `503 EMAIL_UNAVAILABLE` | nada |
+| `/activation/request` | `202`, a mesma resposta de um endereço desconhecido | nada; o link anterior continua valendo |
+| `/password-reset/request` | `202`, a mesma resposta de um endereço desconhecido | nada; o link anterior continua valendo |
+
+O critério é o que a resposta já revela. O cadastro já responde `409`
+para endereço em uso; troca e verificação de e-mail exigem login; a
+recuperação de e-mail só chega ao envio depois que a senha (e o MFA)
+bateram — no mesmo ponto em que um `new_email` em uso responde `409`.
+Nessas rotas o `503` não conta nada que o chamador não soubesse.
+
+!!! warning "Reset e reenvio de ativação continuam respondendo `202`"
+    Essas duas rotas respondem igual para endereço cadastrado e
+    desconhecido, de propósito. Se a falha de envio virasse `503`, ela só
+    apareceria para contas que existem — e a rota viraria oráculo de
+    enumeração. Por isso a falha é **logada em `ERROR`** (sem o endereço)
+    e a resposta continua `202`. O token só é gravado **depois** que o
+    e-mail saiu, então a falha não grava nada e o link pendente anterior
+    não é invalidado.
+
+!!! info "O que vai para o log"
+    O `EmailUtils` loga uma vez, em `ERROR`, com `smtp_host` e
+    `smtp_port` — nunca o destinatário nem a credencial. Falha de rede ou
+    de TLS leva o traceback (é ali que mora o diagnóstico); recusa
+    respondida pelo servidor (`550` para um destinatário, por exemplo)
+    não leva, porque o texto da resposta pode citar o endereço. Pelo
+    mesmo motivo, só a falha de rede ou de TLS fica encadeada em
+    `__cause__`; a recusa sai `from None`, e o handler que loga todo 5xx
+    não tem o que imprimir.
+
+Ao chamar o `UserAuthService` fora do `make_auth_router`, a regra é a de
+qualquer erro depois de um `flush`: faça `rollback` da sessão antes de
+reutilizá-la. O roteador faz isso sozinho, porque nunca chega ao
+`commit`.
+
 ## Entrega de token
 
 *(v0.87.0+)*