tempest-fastapi-sdk 0.91.0__tar.gz → 0.92.0__tar.gz

{tempest_fastapi_sdk-0.91.0 → tempest_fastapi_sdk-0.92.0}/CHANGELOG.md

@@ -5,6 +5,66 @@ All notable changes to **tempest-fastapi-sdk** are listed below.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.92.0] — 2026-07-05
+
+### Added
+
+- **Email change / re-verification / recovery flow** on `UserAuthService`
+  + `make_auth_router`, mirroring the password reset/change surface:
+  - **Change email (authenticated)** — `request_email_change` (verifies
+    the current password, stages the new address, emails a confirmation
+    link to the NEW address) + `confirm_email_change` (consumes the
+    token, flips the email, and — when `AUTH_EMAIL_CHANGE_NOTIFY_OLD`
+    is on — sends a security notice to the OLD address). Routes:
+    `POST /auth/email-change/request` (202) and
+    `POST /auth/email-change/confirm`.
+  - **Re-verify current email** — `request_email_verification` /
+    `confirm_email_verification` (resend a verification link to the
+    current address; confirming marks the account active). Routes:
+    `POST /auth/email-verify/request` (202) and
+    `POST /auth/email-verify/confirm`.
+  - **Recovery (lost mailbox access)** — `request_email_recovery`, an
+    **unauthenticated** entry point that proves identity with the
+    account password **plus a valid MFA code when TOTP is enrolled**,
+    then emails the confirmation link to the new address. Always returns
+    a generic `202` for soft failures (unknown email, wrong password,
+    bad/missing MFA code) so it can't enumerate accounts. Route
+    `POST /auth/email-recovery/request` is **opt-in** via
+    `AUTH_EMAIL_RECOVERY_ENABLED` (off by default).
+  - **Old-email security notice** on a confirmed change, toggled by
+    `AUTH_EMAIL_CHANGE_NOTIFY_OLD` (default `True`).
+  - **Backend HTML pages** (when `AUTH_BACKEND_LINKS=True`):
+    `GET /auth/email-change/{token}` and `GET /auth/email-verify/{token}`
+    render self-contained success/error pages — no frontend needed.
+  - New schemas exported from the package root:
+    `EmailChangeRequestSchema`, `EmailChangeConfirmSchema`,
+    `EmailRecoveryRequestSchema`, `EmailChangeResponseSchema`,
+    `EmailChangeToken`, `EmailVerificationToken`.
+  - New `UserTokenPurpose.EMAIL_CHANGE`; the existing
+    `EMAIL_VERIFICATION` purpose now backs the re-verify flow.
+  - 14 bundled bilingual templates (PT-BR + EN-US): `email_change.html`,
+    `email_verification.html`, `email_changed_notice.html`, plus
+    `email_change_success/error.html` and
+    `email_verification_success/error.html`.
+  - Localized subjects/bodies for the three new emails.
+  - New settings: `AUTH_EMAIL_CHANGE_TTL_SECONDS`,
+    `AUTH_EMAIL_VERIFICATION_TTL_SECONDS`,
+    `AUTH_EMAIL_CHANGE_URL_TEMPLATE`,
+    `AUTH_EMAIL_VERIFICATION_URL_TEMPLATE`, `AUTH_EMAIL_CHANGE_TEMPLATE`,
+    `AUTH_EMAIL_VERIFICATION_TEMPLATE`,
+    `AUTH_EMAIL_CHANGED_NOTICE_TEMPLATE`, `AUTH_EMAIL_CHANGE_NOTIFY_OLD`,
+    `AUTH_EMAIL_RECOVERY_ENABLED`, `AUTH_EMAIL_CHANGE_SUCCESS_TEMPLATE`,
+    `AUTH_EMAIL_CHANGE_ERROR_TEMPLATE`,
+    `AUTH_EMAIL_VERIFICATION_SUCCESS_TEMPLATE`,
+    `AUTH_EMAIL_VERIFICATION_ERROR_TEMPLATE`.
+
+### Changed
+
+- **`BaseUserTokenModel` gains a nullable `payload` column**
+  (`VARCHAR(320)`) carrying flow context — the pending new email for an
+  `EMAIL_CHANGE` token. **Requires a migration** in consuming projects
+  (additive nullable column, safe). See the migration guide.
+
 ## [0.91.0] — 2026-07-05
 
 ### Added

{tempest_fastapi_sdk-0.91.0 → tempest_fastapi_sdk-0.92.0}/CLAUDE.md

@@ -60,13 +60,21 @@ The SDK currently covers (Sep 2025+, post-v0.31.x):
   `query_param=`, for cookieless `EventSource`/SSE clients), full
   bundled flow (`UserAuthService` + `make_auth_router` covering
   signup/activate/login/password-reset), `BaseUserModel` +
-  `BaseUserTokenModel`, OAuth2/OIDC providers
-  (`GoogleOAuthClient`, `GitHubOAuthClient`, `OIDCProvider`),
-  CSRF middleware + `make_csrf_token_dependency`, opt-in
-  DB-backed opaque refresh tokens (`BaseUserRefreshTokenModel`,
-  `make_user_refresh_token_model`, `refresh_token_model=` on
-  `UserAuthService`) with rotation, family-wide reuse detection
-  and `POST /auth/logout` (`LogoutSchema`).
+  `BaseUserTokenModel` (nullable `payload` column carrying flow
+  context), email change/re-verify/recovery
+  (`request_email_change`/`confirm_email_change`,
+  `request_email_verification`/`confirm_email_verification`,
+  `request_email_recovery` — password + MFA-if-enrolled, opt-in
+  `AUTH_EMAIL_RECOVERY_ENABLED`; old-email security notice via
+  `AUTH_EMAIL_CHANGE_NOTIFY_OLD`; `EMAIL_CHANGE` token purpose;
+  JSON + backend HTML pages + bilingual templates), OAuth2/OIDC
+  providers (`GoogleOAuthClient`, `GitHubOAuthClient`,
+  `OIDCProvider`), CSRF middleware + `make_csrf_token_dependency`,
+  opt-in DB-backed opaque refresh tokens
+  (`BaseUserRefreshTokenModel`, `make_user_refresh_token_model`,
+  `refresh_token_model=` on `UserAuthService`) with rotation,
+  family-wide reuse detection and `POST /auth/logout`
+  (`LogoutSchema`).
 - **DB** — `AsyncDatabaseManager`, `BaseRepository[T]` with
   bulk ops (`bulk_create_values`, `bulk_upsert`, `bulk_update`,
   `add_all`, etc.), `AlembicHelper`, `BaseModel`, audit /

{tempest_fastapi_sdk-0.91.0 → tempest_fastapi_sdk-0.92.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.91.0
+Version: 0.92.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
@@ -253,7 +253,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `tempest_fastapi_sdk.exceptions` | `AppException`, `NotFoundException`, `ConflictException`, `ValidationException`, `UnauthorizedException`, `ForbiddenException`, `InvalidTokenException`, `ExpiredTokenException`, `FileTooLargeException`, `InvalidFileTypeException`, `TooManyRequestsException`, i18n (`MessageCatalog`, `default_message_catalog`, `parse_accept_language`, `DEFAULT_LOCALE`) |
 | `tempest_fastapi_sdk.settings` | `BaseAppSettings`, `ServerSettings`, `LogSettings`, `DatabaseSettings`, `RedisSettings`, `RabbitMQSettings`, `JWTSettings`, `CORSSettings`, `EmailSettings`, `UploadSettings`, `TokenSettings`, `WebPushSettings`, `TaskIQSettings`, `MinIOSettings`, `AuthSettings` |
 | `tempest_fastapi_sdk.api` | `register_exception_handlers`, `app_exception_handler`, `apply_cors`, `make_health_router`, `make_logs_router`, `make_prometheus_router`, `make_prometheus_registry`, `PrometheusMiddleware`, `LogSource`, `make_tool_spec_router`, `make_token_dependency`, `make_bearer_token_dependency`, `make_jwt_user_dependency`, `make_role_dependency`, `make_permission_dependency`, `require_x_token`, `run_server`, `RequestIDMiddleware`, `RateLimitMiddleware` (+ `RateLimitStore`/`MemoryRateLimitStore`/`RedisRateLimitStore`/`RateLimitResult` and `key_by_ip`/`key_by_jwt_subject`/`key_by_jwt_claim`/`key_by_header`), `IdempotencyMiddleware`, `MemoryIdempotencyStore`, `RedisIdempotencyStore`, `BodySizeLimitMiddleware`, `CSRFMiddleware`, `make_csrf_token_dependency`, `GracefulShutdownMiddleware`, `WebhookSignatureVerifier`, `RSAWebhookSignatureVerifier`, OAuth2 (`GoogleOAuthClient`, `GitHubOAuthClient`, `OIDCProvider`), `HardenedStaticFiles`, `DEFAULT_STATIC_SECURITY_HEADERS`, `set_cookie`, `clear_cookie`, `SameSite`, `HealthCheck`, `setup_tracing` *(extra: `[otel]`)* |
-| `tempest_fastapi_sdk.auth` *(extra: `[auth]`, opcional `[email]`, `[mfa]`)* | `UserAuthService`, `make_auth_router`, `SignupSchema` / `LoginSchema` / `RefreshSchema` / `PasswordResetRequestSchema` / `PasswordResetConfirmSchema` + responses, `ActivationToken`, `PasswordResetToken`, MFA schemas (`MFAEnrollResponseSchema` / `MFAConfirmSchema` / `MFAVerifySchema` / `MFADisableSchema`), opt-in DB-backed refresh tokens (`BaseUserRefreshTokenModel` / `make_user_refresh_token_model` / `LogoutSchema`) with rotation + reuse detection + `POST /auth/logout`, bilingual emails + backend pages (`AUTH_DEFAULT_LOCALE`, `normalize_locale` / `negotiate_locale`) — signup/activate/login/refresh/logout/reset + TOTP 2FA out of the box |
+| `tempest_fastapi_sdk.auth` *(extra: `[auth]`, opcional `[email]`, `[mfa]`)* | `UserAuthService`, `make_auth_router`, `SignupSchema` / `LoginSchema` / `RefreshSchema` / `PasswordResetRequestSchema` / `PasswordResetConfirmSchema` + responses, `ActivationToken`, `PasswordResetToken`, email change/verify/recovery (`EmailChangeRequestSchema` / `EmailChangeConfirmSchema` / `EmailRecoveryRequestSchema` / `EmailChangeToken` / `EmailVerificationToken`, old-email security notice, opt-in `AUTH_EMAIL_RECOVERY_ENABLED`), MFA schemas (`MFAEnrollResponseSchema` / `MFAConfirmSchema` / `MFAVerifySchema` / `MFADisableSchema`), opt-in DB-backed refresh tokens (`BaseUserRefreshTokenModel` / `make_user_refresh_token_model` / `LogoutSchema`) with rotation + reuse detection + `POST /auth/logout`, bilingual emails + backend pages (`AUTH_DEFAULT_LOCALE`, `normalize_locale` / `negotiate_locale`) — signup/activate/login/refresh/logout/reset + email change/recovery + TOTP 2FA out of the box |
 | `tempest_fastapi_sdk.controllers` | `BaseController` |
 | `tempest_fastapi_sdk.services` | `BaseService` |
 | `tempest_fastapi_sdk.core` | `configure_logging`, `JSONFormatter`, `get_request_id`/`set_request_id`/`clear_request_id`, `request_id_ctx`, `BaseStrEnum`, `BaseIntEnum`, `strict_types`/`typed`/`require_annotations` |

{tempest_fastapi_sdk-0.91.0 → tempest_fastapi_sdk-0.92.0}/README.md

@@ -144,7 +144,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `tempest_fastapi_sdk.exceptions` | `AppException`, `NotFoundException`, `ConflictException`, `ValidationException`, `UnauthorizedException`, `ForbiddenException`, `InvalidTokenException`, `ExpiredTokenException`, `FileTooLargeException`, `InvalidFileTypeException`, `TooManyRequestsException`, i18n (`MessageCatalog`, `default_message_catalog`, `parse_accept_language`, `DEFAULT_LOCALE`) |
 | `tempest_fastapi_sdk.settings` | `BaseAppSettings`, `ServerSettings`, `LogSettings`, `DatabaseSettings`, `RedisSettings`, `RabbitMQSettings`, `JWTSettings`, `CORSSettings`, `EmailSettings`, `UploadSettings`, `TokenSettings`, `WebPushSettings`, `TaskIQSettings`, `MinIOSettings`, `AuthSettings` |
 | `tempest_fastapi_sdk.api` | `register_exception_handlers`, `app_exception_handler`, `apply_cors`, `make_health_router`, `make_logs_router`, `make_prometheus_router`, `make_prometheus_registry`, `PrometheusMiddleware`, `LogSource`, `make_tool_spec_router`, `make_token_dependency`, `make_bearer_token_dependency`, `make_jwt_user_dependency`, `make_role_dependency`, `make_permission_dependency`, `require_x_token`, `run_server`, `RequestIDMiddleware`, `RateLimitMiddleware` (+ `RateLimitStore`/`MemoryRateLimitStore`/`RedisRateLimitStore`/`RateLimitResult` and `key_by_ip`/`key_by_jwt_subject`/`key_by_jwt_claim`/`key_by_header`), `IdempotencyMiddleware`, `MemoryIdempotencyStore`, `RedisIdempotencyStore`, `BodySizeLimitMiddleware`, `CSRFMiddleware`, `make_csrf_token_dependency`, `GracefulShutdownMiddleware`, `WebhookSignatureVerifier`, `RSAWebhookSignatureVerifier`, OAuth2 (`GoogleOAuthClient`, `GitHubOAuthClient`, `OIDCProvider`), `HardenedStaticFiles`, `DEFAULT_STATIC_SECURITY_HEADERS`, `set_cookie`, `clear_cookie`, `SameSite`, `HealthCheck`, `setup_tracing` *(extra: `[otel]`)* |
-| `tempest_fastapi_sdk.auth` *(extra: `[auth]`, opcional `[email]`, `[mfa]`)* | `UserAuthService`, `make_auth_router`, `SignupSchema` / `LoginSchema` / `RefreshSchema` / `PasswordResetRequestSchema` / `PasswordResetConfirmSchema` + responses, `ActivationToken`, `PasswordResetToken`, MFA schemas (`MFAEnrollResponseSchema` / `MFAConfirmSchema` / `MFAVerifySchema` / `MFADisableSchema`), opt-in DB-backed refresh tokens (`BaseUserRefreshTokenModel` / `make_user_refresh_token_model` / `LogoutSchema`) with rotation + reuse detection + `POST /auth/logout`, bilingual emails + backend pages (`AUTH_DEFAULT_LOCALE`, `normalize_locale` / `negotiate_locale`) — signup/activate/login/refresh/logout/reset + TOTP 2FA out of the box |
+| `tempest_fastapi_sdk.auth` *(extra: `[auth]`, opcional `[email]`, `[mfa]`)* | `UserAuthService`, `make_auth_router`, `SignupSchema` / `LoginSchema` / `RefreshSchema` / `PasswordResetRequestSchema` / `PasswordResetConfirmSchema` + responses, `ActivationToken`, `PasswordResetToken`, email change/verify/recovery (`EmailChangeRequestSchema` / `EmailChangeConfirmSchema` / `EmailRecoveryRequestSchema` / `EmailChangeToken` / `EmailVerificationToken`, old-email security notice, opt-in `AUTH_EMAIL_RECOVERY_ENABLED`), MFA schemas (`MFAEnrollResponseSchema` / `MFAConfirmSchema` / `MFAVerifySchema` / `MFADisableSchema`), opt-in DB-backed refresh tokens (`BaseUserRefreshTokenModel` / `make_user_refresh_token_model` / `LogoutSchema`) with rotation + reuse detection + `POST /auth/logout`, bilingual emails + backend pages (`AUTH_DEFAULT_LOCALE`, `normalize_locale` / `negotiate_locale`) — signup/activate/login/refresh/logout/reset + email change/recovery + TOTP 2FA out of the box |
 | `tempest_fastapi_sdk.controllers` | `BaseController` |
 | `tempest_fastapi_sdk.services` | `BaseService` |
 | `tempest_fastapi_sdk.core` | `configure_logging`, `JSONFormatter`, `get_request_id`/`set_request_id`/`clear_request_id`, `request_id_ctx`, `BaseStrEnum`, `BaseIntEnum`, `strict_types`/`typed`/`require_annotations` |

{tempest_fastapi_sdk-0.91.0 → tempest_fastapi_sdk-0.92.0}/docs/migration.en.md

@@ -2,6 +2,36 @@
 
 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.92.0 — `payload` column on the user token
+
+0.92.0 adds the **email change / re-verification / recovery** flow. To carry the pending email until confirmation, `BaseUserTokenModel` gained a new column:
+
+```python
+payload: Mapped[str | None] = mapped_column(String(320), nullable=True, default=None)
+```
+
+Since your `user_tokens` table inherits from `BaseUserTokenModel`, the column shows up on the model automatically — but the database needs a **migration**. It is additive and safe (nullable column, no required default):
+
+```bash
+# generate and apply
+tempest db revision -m "add payload to user_tokens"
+tempest db upgrade
+```
+
+Or by hand:
+
+```sql
+ALTER TABLE user_tokens ADD COLUMN payload VARCHAR(320) NULL;
+```
+
+!!! info "That's it"
+    No renames, no default backfill. Existing flows (activation, password reset) keep writing `payload = NULL`. The new email flow is fully opt-in — recovery (`POST /auth/email-recovery/request`) is only mounted with `AUTH_EMAIL_RECOVERY_ENABLED=True`.
+
+### Verify
+
+- Run the migration before deploying 0.92.0 (the column must exist).
+- If you hand-write `src/db/models/user_token.py` instead of using `make_user_token_model`, the column comes from the abstract base — no need to redeclare, just migrate.
+
 ## 0.63.0 — authenticated user loaded on the request session
 
 Before 0.63.0, `UserAuthService.current_user_dependency()` loaded the authenticated user through `load_user`, which opened its **own** session (via `db.get_session_context()`) and closed it on exit. The `UserModel` handed to the route was therefore **detached**: mutating it and calling `commit`/`refresh` on the request session (the one your repositories use) raised

{tempest_fastapi_sdk-0.91.0 → tempest_fastapi_sdk-0.92.0}/docs/migration.md

@@ -2,6 +2,36 @@
 
 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.92.0 — coluna `payload` no token de usuário
+
+A 0.92.0 adiciona o fluxo de **troca / re-verificação / recuperação de e-mail**. Para carregar o e-mail pendente até a confirmação, `BaseUserTokenModel` ganhou uma coluna nova:
+
+```python
+payload: Mapped[str | None] = mapped_column(String(320), nullable=True, default=None)
+```
+
+Como sua tabela `user_tokens` herda de `BaseUserTokenModel`, a coluna aparece automaticamente no modelo — mas o banco precisa de uma **migration**. É aditiva e segura (coluna anulável, sem default obrigatório):
+
+```bash
+# gere e aplique
+tempest db revision -m "add payload to user_tokens"
+tempest db upgrade
+```
+
+Ou, na mão:
+
+```sql
+ALTER TABLE user_tokens ADD COLUMN payload VARCHAR(320) NULL;
+```
+
+!!! info "Só isso"
+    Nenhuma renomeação, nenhum default backfill. Fluxos existentes (ativação, reset de senha) continuam gravando `payload = NULL`. O novo fluxo de e-mail é totalmente opt-in — a recuperação (`POST /auth/email-recovery/request`) só é montada com `AUTH_EMAIL_RECOVERY_ENABLED=True`.
+
+### Verifique
+
+- Rode a migration antes de subir a 0.92.0 (a coluna precisa existir).
+- Se você escreve `src/db/models/user_token.py` à mão em vez de usar `make_user_token_model`, a coluna vem da base abstrata — não precisa redeclarar, só migrar.
+
 ## 0.63.0 — usuário autenticado carregado na sessão de request
 
 Antes da 0.63.0, `UserAuthService.current_user_dependency()` carregava o usuário autenticado chamando `load_user`, que abria a **própria** sessão (via `db.get_session_context()`) e a fechava ao terminar. O `UserModel` entregue à rota ficava **detached**: mutá-lo e dar `commit`/`refresh` na sessão de request (a dos seus repositories) levantava

{tempest_fastapi_sdk-0.91.0 → tempest_fastapi_sdk-0.92.0}/docs/recipes/auth-flow.en.md

@@ -130,6 +130,11 @@ uv run tempest db upgrade
 | POST | `/auth/password-reset/request` | `PasswordResetRequestSchema` → `PasswordResetResponseSchema` | Always HTTP 202 + generic body. Link via email (A/B) or body (C). |
 | POST | `/auth/password-reset/confirm` | `PasswordResetConfirmSchema` → `LoginResponseSchema` | Consumes token + writes new password + issues JWT pair. |
 | POST | `/auth/password-change` | `PasswordChangeSchema` → `204` | **Authenticated** (bearer token). Change your own password: confirm the current password + write the new one. No email token. |
+| POST | `/auth/email-change/request` *(v0.92.0+)* | `EmailChangeRequestSchema` → `EmailChangeResponseSchema` | **Authenticated.** Confirm the current password + email a confirmation link to the **new** address. Always 202. |
+| POST | `/auth/email-change/confirm` *(v0.92.0+)* | `EmailChangeConfirmSchema` → `EmailChangeResponseSchema` | Consume the token + apply the new email + (optionally) notify the old address. |
+| POST | `/auth/email-verify/request` *(v0.92.0+)* | — → `EmailChangeResponseSchema` | **Authenticated.** Re-send a verification link to the **current** email. |
+| POST | `/auth/email-verify/confirm` *(v0.92.0+)* | `EmailChangeConfirmSchema` → `EmailChangeResponseSchema` | Consume the token + mark the account active. |
+| POST | `/auth/email-recovery/request` *(v0.92.0+, opt-in)* | `EmailRecoveryRequestSchema` → `EmailChangeResponseSchema` | **Unauthenticated.** Recover an account whose mailbox is lost: password (+ MFA if enrolled). Only mounted with `AUTH_EMAIL_RECOVERY_ENABLED=True`. Always 202. |
 | POST | `/auth/refresh` *(v0.65.0+)* | `RefreshSchema` → `LoginResponseSchema` | Exchange a valid **refresh token** for a fresh JWT pair. **No email/password.** Rejects a replayed access token (401) and inactive accounts (403). |
 
 !!! tip "`password-reset/confirm` vs `password-change` — which is which?"
@@ -145,6 +150,50 @@ uv run tempest db upgrade
       `current_password`. No email or reset token involved. Returns
       **204** and the current tokens stay valid.
 
+## Email change, verification and recovery (v0.92.0+)
+
+Mirrors the password flow, but for the account **email**. Three cases:
+
+- **Change email (logged in)** — like `password-change`: the user is
+  logged in, confirms `current_password` and supplies `new_email`. A
+  confirmation link goes to the **new** address; the email only changes
+  once that link is confirmed. On confirmation a security notice is sent
+  to the **old** address (the banks/Google pattern).
+- **Re-verify the current email** — re-send a verification link to the
+  current address (useful when the activation email was lost).
+- **Recovery (lost mailbox access)** — an **unauthenticated** endpoint,
+  opt-in via `AUTH_EMAIL_RECOVERY_ENABLED`. Proves identity with the
+  password **and a valid MFA code when TOTP is enrolled**, then emails the
+  link to the new address.
+
+```python
+# Change email (logged in) — token comes in the body in dev (mode C)
+resp = await client.post(
+    "/auth/email-change/request",
+    json={"new_email": "new@example.com", "current_password": "current-pass"},
+    headers={"Authorization": f"Bearer {access_token}"},
+)
+confirm_url: str | None = resp.json()["confirm_url"]  # None in prod (goes by email)
+
+# ...user opens the link; the front extracts the token and confirms:
+await client.post("/auth/email-change/confirm", json={"token": token})
+```
+
+!!! danger "Recovery is sensitive — enable it deliberately"
+    `POST /auth/email-recovery/request` lets whoever has the password move
+    the account to another email **without** accessing the old mailbox. It
+    is only mounted with `AUTH_EMAIL_RECOVERY_ENABLED=True`. It always
+    answers a generic **202** (no account enumeration) and, when TOTP is
+    enrolled, requires a valid `mfa_code`. Keep
+    `AUTH_EMAIL_CHANGE_NOTIFY_OLD=True` so the old address is always
+    alerted.
+
+!!! info "Where the new email is stored"
+    The pending address travels in the token's `payload` column
+    (`EMAIL_CHANGE`), not on the `UserModel`. Confirmation re-reads the
+    `payload`, re-checks the address is still free (a request→confirm race
+    → **409**) and only then writes it. See the 0.92.0 migration note.
+
 ### Renewing the session with the refresh token
 
 The `access_token` is short-lived by design (`JWT_ACCESS_TTL_SECONDS`,

{tempest_fastapi_sdk-0.91.0 → tempest_fastapi_sdk-0.92.0}/docs/recipes/auth-flow.md

@@ -130,6 +130,11 @@ uv run tempest db upgrade
 | POST | `/auth/password-reset/request` | `PasswordResetRequestSchema` → `PasswordResetResponseSchema` | Sempre HTTP 202 + corpo genérico. Link via e-mail (A/B) ou no body (C). |
 | POST | `/auth/password-reset/confirm` | `PasswordResetConfirmSchema` → `LoginResponseSchema` | Consome token + grava nova senha + emite JWT pair. |
 | POST | `/auth/password-change` | `PasswordChangeSchema` → `204` | **Autenticado** (bearer token). Troca a própria senha: confirma a senha atual + grava a nova. Sem token de e-mail. |
+| POST | `/auth/email-change/request` *(v0.92.0+)* | `EmailChangeRequestSchema` → `EmailChangeResponseSchema` | **Autenticado.** Confirma a senha atual + envia link de confirmação pro **novo** e-mail. Sempre 202. |
+| POST | `/auth/email-change/confirm` *(v0.92.0+)* | `EmailChangeConfirmSchema` → `EmailChangeResponseSchema` | Consome o token + aplica o novo e-mail + (opcional) avisa o e-mail antigo. |
+| POST | `/auth/email-verify/request` *(v0.92.0+)* | — → `EmailChangeResponseSchema` | **Autenticado.** Reenvia link de verificação pro e-mail **atual**. |
+| POST | `/auth/email-verify/confirm` *(v0.92.0+)* | `EmailChangeConfirmSchema` → `EmailChangeResponseSchema` | Consome o token + marca a conta ativa. |
+| POST | `/auth/email-recovery/request` *(v0.92.0+, opt-in)* | `EmailRecoveryRequestSchema` → `EmailChangeResponseSchema` | **Não autenticado.** Recupera conta cujo e-mail se perdeu: senha (+ MFA se inscrito). Só montado com `AUTH_EMAIL_RECOVERY_ENABLED=True`. Sempre 202. |
 | POST | `/auth/refresh` *(v0.65.0+)* | `RefreshSchema` → `LoginResponseSchema` | Troca um **refresh token** válido por um JWT pair novo. **Sem email/senha.** Rejeita access token replayado (401) e conta inativa (403). |
 
 !!! tip "`password-reset/confirm` vs `password-change` — qual é qual?"
@@ -144,6 +149,50 @@ uv run tempest db upgrade
       nem token de reset. Retorna **204** e os tokens atuais continuam
       válidos.
 
+## Troca, verificação e recuperação de e-mail (v0.92.0+)
+
+Espelha o fluxo de senha, mas pro **e-mail** da conta. Três cenários:
+
+- **Trocar e-mail (logado)** — como `password-change`: o usuário está
+  logado, confirma a `current_password` e informa o `new_email`. Um link
+  de confirmação vai pro **novo** endereço; o e-mail só muda quando esse
+  link é confirmado. Ao confirmar, um aviso de segurança vai pro endereço
+  **antigo** (padrão de bancos/Google).
+- **Re-verificar o e-mail atual** — reenvia um link de verificação pro
+  endereço atual (útil quando o e-mail de ativação se perdeu).
+- **Recuperação (perdeu acesso ao e-mail)** — endpoint **não
+  autenticado**, opt-in via `AUTH_EMAIL_RECOVERY_ENABLED`. Prova
+  identidade com a senha **e um código MFA quando o TOTP está inscrito**,
+  e manda o link pro novo endereço.
+
+```python
+# Trocar e-mail (logado) — pega o token no body em dev (modo C)
+resp = await client.post(
+    "/auth/email-change/request",
+    json={"new_email": "nova@example.com", "current_password": "senha-atual"},
+    headers={"Authorization": f"Bearer {access_token}"},
+)
+confirm_url: str | None = resp.json()["confirm_url"]  # None em produção (vai por e-mail)
+
+# ...usuário abre o link; o front extrai o token e confirma:
+await client.post("/auth/email-change/confirm", json={"token": token})
+```
+
+!!! danger "Recuperação é sensível — ligue com cuidado"
+    `POST /auth/email-recovery/request` deixa quem tem a senha mover a
+    conta pra outro e-mail **sem** acessar a caixa antiga. Só é montado
+    com `AUTH_EMAIL_RECOVERY_ENABLED=True`. Sempre responde **202**
+    genérico (não enumera contas) e, se o TOTP estiver inscrito, exige um
+    `mfa_code` válido. Mantenha `AUTH_EMAIL_CHANGE_NOTIFY_OLD=True` pra o
+    endereço antigo sempre ser avisado.
+
+!!! info "Onde o novo e-mail fica guardado"
+    O endereço pendente viaja na coluna `payload` do token
+    (`EMAIL_CHANGE`), não no `UserModel`. A confirmação relê o `payload`,
+    re-checa que o endereço ainda está livre (corrida entre pedido e
+    confirmação → **409**) e só então grava. Veja a nota de migração da
+    0.92.0.
+
 ### Renovando a sessão com o refresh token
 
 O `access_token` é curto por design (`JWT_ACCESS_TTL_SECONDS`, 1 h por

{tempest_fastapi_sdk-0.91.0 → tempest_fastapi_sdk-0.92.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-fastapi-sdk"
-version = "0.91.0"
+version = "0.92.0"
 description = "Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects."
 readme = "README.md"
 requires-python = ">=3.11"

{tempest_fastapi_sdk-0.91.0 → tempest_fastapi_sdk-0.92.0}/tempest_fastapi_sdk/__init__.py

@@ -84,6 +84,12 @@ from tempest_fastapi_sdk.auth import (
     ActivationResponseSchema,
     ActivationToken,
     AuthCookieConfig,
+    EmailChangeConfirmSchema,
+    EmailChangeRequestSchema,
+    EmailChangeResponseSchema,
+    EmailChangeToken,
+    EmailRecoveryRequestSchema,
+    EmailVerificationToken,
     LoginResponseSchema,
     LoginSchema,
     LogoutSchema,
@@ -361,7 +367,7 @@ from tempest_fastapi_sdk.websockets import (
     make_websocket_router,
 )
 
-__version__: str = "0.91.0"
+__version__: str = "0.92.0"
 
 __all__: list[str] = [
     "BASE_COLUMN_ORDER",
@@ -446,8 +452,14 @@ __all__: list[str] = [
     "DestructiveMigrationError",
     "DiskMetrics",
     "DownloadUtils",
+    "EmailChangeConfirmSchema",
+    "EmailChangeRequestSchema",
+    "EmailChangeResponseSchema",
+    "EmailChangeToken",
+    "EmailRecoveryRequestSchema",
     "EmailSettings",
     "EmailUtils",
+    "EmailVerificationToken",
     "EnvFeatureFlagBackend",
     "EventStream",
     "ExpiredTokenException",

{tempest_fastapi_sdk-0.91.0 → tempest_fastapi_sdk-0.92.0}/tempest_fastapi_sdk/auth/__init__.py

@@ -31,6 +31,22 @@ from tempest_fastapi_sdk.auth.schemas import (
     ActivationResponseSchema as ActivationResponseSchema,
 )
 from tempest_fastapi_sdk.auth.schemas import ActivationToken as ActivationToken
+from tempest_fastapi_sdk.auth.schemas import (
+    EmailChangeConfirmSchema as EmailChangeConfirmSchema,
+)
+from tempest_fastapi_sdk.auth.schemas import (
+    EmailChangeRequestSchema as EmailChangeRequestSchema,
+)
+from tempest_fastapi_sdk.auth.schemas import (
+    EmailChangeResponseSchema as EmailChangeResponseSchema,
+)
+from tempest_fastapi_sdk.auth.schemas import EmailChangeToken as EmailChangeToken
+from tempest_fastapi_sdk.auth.schemas import (
+    EmailRecoveryRequestSchema as EmailRecoveryRequestSchema,
+)
+from tempest_fastapi_sdk.auth.schemas import (
+    EmailVerificationToken as EmailVerificationToken,
+)
 from tempest_fastapi_sdk.auth.schemas import (
     LoginResponseSchema as LoginResponseSchema,
 )
@@ -78,6 +94,12 @@ __all__: list[str] = [
     "ActivationResponseSchema",
     "ActivationToken",
     "AuthCookieConfig",
+    "EmailChangeConfirmSchema",
+    "EmailChangeRequestSchema",
+    "EmailChangeResponseSchema",
+    "EmailChangeToken",
+    "EmailRecoveryRequestSchema",
+    "EmailVerificationToken",
     "LoginResponseSchema",
     "LoginSchema",
     "LogoutSchema",

{tempest_fastapi_sdk-0.91.0 → tempest_fastapi_sdk-0.92.0}/tempest_fastapi_sdk/auth/locale.py

@@ -142,12 +142,30 @@ AUTH_EMAIL_MESSAGES: dict[str, dict[str, str]] = {
         "activation_body": "Abra este link para ativar sua conta: {url}",
         "password_reset_subject": "Redefina sua senha",
         "password_reset_body": "Abra este link para redefinir sua senha: {url}",
+        "email_change_subject": "Confirme seu novo e-mail",
+        "email_change_body": "Abra este link para confirmar seu novo e-mail: {url}",
+        "email_verification_subject": "Verifique seu e-mail",
+        "email_verification_body": "Abra este link para verificar seu e-mail: {url}",
+        "email_changed_notice_subject": "Seu e-mail foi alterado",
+        "email_changed_notice_body": (
+            "O e-mail da sua conta foi alterado para {new_email}. "
+            "Se não foi você, fale com o suporte imediatamente."
+        ),
     },
     "en-US": {
         "activation_subject": "Activate your account",
         "activation_body": "Open this link to activate your account: {url}",
         "password_reset_subject": "Reset your password",
         "password_reset_body": "Open this link to reset your password: {url}",
+        "email_change_subject": "Confirm your new email",
+        "email_change_body": "Open this link to confirm your new email: {url}",
+        "email_verification_subject": "Verify your email",
+        "email_verification_body": "Open this link to verify your email: {url}",
+        "email_changed_notice_subject": "Your email was changed",
+        "email_changed_notice_body": (
+            "Your account email was changed to {new_email}. "
+            "If this wasn't you, contact support immediately."
+        ),
     },
 }
 
@@ -186,12 +204,14 @@ def auth_email_message(locale: str, key: str) -> str:
     Args:
         locale (str): A canonical supported locale. Unknown locales fall
             back to :data:`DEFAULT_AUTH_LOCALE`.
-        key (str): One of ``"activation_subject"``, ``"activation_body"``,
-            ``"password_reset_subject"``, ``"password_reset_body"``.
+        key (str): One of the ``*_subject`` / ``*_body`` keys —
+            ``activation``, ``password_reset``, ``email_change``,
+            ``email_verification`` and ``email_changed_notice``.
 
     Returns:
-        str: The localized string. Body strings still contain the
-        ``{url}`` placeholder for the caller to ``.format(...)``.
+        str: The localized string. ``*_body`` strings still contain a
+        placeholder (``{url}``, or ``{new_email}`` for
+        ``email_changed_notice_body``) for the caller to ``.format(...)``.
     """
     table = AUTH_EMAIL_MESSAGES.get(locale, AUTH_EMAIL_MESSAGES[DEFAULT_AUTH_LOCALE])
     return table[key]