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

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

@@ -5,6 +5,112 @@ 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
+
+- **SSE backpressure — bounded queue + overflow policy.**
+  `EventStream` (and `SSEBroker`-created streams) now cap the buffered
+  events at `max_queue` (default `1000`) instead of growing without
+  limit when a client stalls. When the buffer fills, `overflow` decides
+  what gives:
+  - `"drop_oldest"` (default) — evict the stalest event, keep the
+    freshest data.
+  - `"drop_newest"` — discard the incoming event, keep the backlog.
+  - `"block"` — apply real backpressure (the producer waits for a slot).
+  `EventStream.dropped_events` counts events lost to overflow for
+  metrics / logs. `max_queue=0` restores the pre-0.91 unbounded
+  behavior. The `close()` sentinel is never dropped or blocked, so a
+  stream can always terminate. `SSEBroker(max_queue=..., overflow=...)`
+  applies the same policy to every stream it opens.
+- **SSE lifecycle helpers — no more hand-rolled `try/finally`.**
+  - `sse_response(..., on_disconnect=...)` runs a cleanup callback
+    (awaited if a coroutine) when the client disconnects or the stream
+    ends — the one place guaranteed to fire — so a bound producer task
+    is cancelled or a channel unregistered without boilerplate.
+  - `EventStream.response(*, on_disconnect=..., status_code=...,
+    headers=...)` wraps `stream()` in an SSE response in one call.
+  - `SSEBroker.response(channel, ...)` bundles the whole per-connection
+    lifecycle: `register` + `sse_response` + `unregister`-on-disconnect.
+    This removes the leak-prone manual wrapper the recipe used to need.
+- **JWT via query string for cookieless clients.**
+  `make_bearer_token_dependency` and `make_jwt_user_dependency` gained a
+  `query_param` argument (e.g. `query_param="access_token"`). Token
+  lookup order becomes header → cookie → query string. This unblocks
+  browser `EventSource` (SSE), whose constructor accepts neither headers
+  nor a body. Documented with a security warning: use short-lived access
+  tokens only, over TLS, and scrub the value from access logs. Prefer a
+  session cookie (`withCredentials`) whenever the client shares the
+  API's origin.
+- **`OverflowPolicy`** is exported from `tempest_fastapi_sdk.sse` and the
+  package root.
+
+### Fixed
+
+- `tempest_fastapi_sdk/sse/__init__.py` re-exports now use the explicit
+  `X as X` alias form required by the repo's re-export convention (was a
+  structural defect flagged by strict type-checkers).
+
 ## [0.90.0] — 2026-07-04
 
 ### Added

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

@@ -55,16 +55,26 @@ without the docs being green.
 
 The SDK currently covers (Sep 2025+, post-v0.31.x):
 
-- **Auth** — JWT/bearer/role/permission/X-Token deps, full
+- **Auth** — JWT/bearer/role/permission/X-Token deps (JWT deps
+  read the token from header → cookie → query string via
+  `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 /
@@ -88,9 +98,14 @@ The SDK currently covers (Sep 2025+, post-v0.31.x):
 - **Pagination** — offset + cursor.
 - **Settings mixins** — every `*Settings` carries
   `title`/`description`/`examples` on every field.
-- **SSE** — `EventStream`, `ServerSentEvent`, `sse_response`, and
-  `SSEBroker` (per-channel fan-out; in-memory single-process, or
-  multi-worker via an injected Redis pub/sub bridge — same call site).
+- **SSE** — `EventStream` (bounded queue + `overflow` backpressure —
+  `drop_oldest`/`drop_newest`/`block`, `dropped_events` counter,
+  `max_queue=0` to disable), `ServerSentEvent`, `sse_response`
+  (`on_disconnect=` cleanup), `EventStream.response`, and `SSEBroker`
+  (per-channel fan-out; `SSEBroker.response(channel)` bundles
+  register + response + unregister-on-disconnect; in-memory
+  single-process, or multi-worker via an injected Redis pub/sub bridge
+  — same call site).
 - **Throttle** — `AttemptThrottle` (any `ThrottleBackend`, e.g.
   `redis.asyncio.Redis`; no in-memory backend bundled).
 - **Base CRUD layers** — `BaseService[Repo, Resp, UpdateT]` and

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.90.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
@@ -200,7 +200,7 @@ Via `pyproject.toml`:
 
 ```toml
 dependencies = [
-    "tempest-fastapi-sdk>=0.90.0",
+    "tempest-fastapi-sdk>=0.91.0",
 ]
 ```
 
@@ -253,12 +253,12 @@ 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.admin` *(extra: `[admin]`)* | `AdminSite`, `AdminModel`, `make_admin_router`, `AdminAuthBackend`, `UserModelAuthBackend`, `AdminAuthError` |
-| `tempest_fastapi_sdk.sse` | `EventStream`, `SSEBroker` (multi-worker fan-out via Redis), `ServerSentEvent`, `sse_response` |
+| `tempest_fastapi_sdk.sse` | `EventStream` (bounded queue + `overflow` backpressure), `SSEBroker` (multi-worker fan-out via Redis, `.response()` lifecycle helper), `ServerSentEvent`, `sse_response` (`on_disconnect=` cleanup) |
 | `tempest_fastapi_sdk.cache` *(extra: `[cache]`)* | `AsyncRedisManager`, `cached` (with `namespace` / `tags`), `CacheInvalidator`, `namespace_registry_key`, `tag_registry_key` |
 | `tempest_fastapi_sdk.flags` | `FeatureFlags`, `FeatureFlagBackend`, `MemoryFeatureFlagBackend`, `EnvFeatureFlagBackend`, `RedisFeatureFlagBackend`, `CompositeFeatureFlagBackend`, `make_flag_dependency`, `coerce_flag` |
 | `tempest_fastapi_sdk.webpush` *(extra: `[webpush]`)* | `WebPushDispatcher`, `WebPushSubscriptionService`, `make_web_push_router`, `WebPushError`, `WebPushGoneError`, `WebPushSubscriptionSchema`, `WebPushKeysSchema`, `WebPushPayloadSchema` |
@@ -2445,7 +2445,7 @@ import asyncio
 
 from fastapi import APIRouter
 
-from tempest_fastapi_sdk import EventStream, sse_response
+from tempest_fastapi_sdk import EventStream
 
 router = APIRouter()
 
@@ -2460,8 +2460,9 @@ async def events() -> "StreamingResponse":  # forward-declared by Starlette
             await asyncio.sleep(1)
         await stream.close()
 
-    asyncio.create_task(producer())
-    return sse_response(stream.stream())
+    task = asyncio.create_task(producer())
+    # on_disconnect cancels the producer when the client drops — no leak.
+    return stream.response(on_disconnect=task.cancel)
 ```
 
 Browser side:
@@ -2473,6 +2474,8 @@ es.addEventListener("counter", (e) => console.log("got", JSON.parse(e.data)));
 
 `heartbeat_seconds` emits a `: keepalive` SSE comment when idle so load-balancers don't close long-lived connections. `ServerSentEvent.data` accepts strings, bytes or any JSON-serializable Python object — non-strings are JSON-encoded automatically. Pass `retry=` to hint the browser at the reconnect delay (milliseconds).
 
+The queue is **bounded** (`max_queue`, default `1000`): a slow client can't grow memory without limit. `overflow` picks the eviction policy — `"drop_oldest"` (default), `"drop_newest"`, or `"block"` (real backpressure); `EventStream.dropped_events` counts the discards. For broadcast, `SSEBroker.response(channel)` bundles `register` + `sse_response` + `unregister`-on-disconnect in one call. Authenticating an `EventSource` (which can't send an `Authorization` header): prefer a session cookie (`make_jwt_user_dependency(..., cookie_name="access_token")` + `withCredentials`); for cookieless clients pass a short-lived access token in the query string with `query_param="access_token"` (over TLS, scrubbed from logs). See the [SSE recipe](https://mauriciobenjamin700.github.io/tempest-fastapi-sdk/recipes/sse/) for the full guide.
+
 ### Web Push notifications recipe
 
 `WebPushDispatcher` wraps the synchronous `pywebpush` library in `asyncio.to_thread` and surfaces the two errors the application cares about: `WebPushGoneError` (HTTP 404/410 — delete the subscription) and `WebPushError` (everything else). Install with `[webpush]`.

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

@@ -91,7 +91,7 @@ Via `pyproject.toml`:
 
 ```toml
 dependencies = [
-    "tempest-fastapi-sdk>=0.90.0",
+    "tempest-fastapi-sdk>=0.91.0",
 ]
 ```
 
@@ -144,12 +144,12 @@ 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.admin` *(extra: `[admin]`)* | `AdminSite`, `AdminModel`, `make_admin_router`, `AdminAuthBackend`, `UserModelAuthBackend`, `AdminAuthError` |
-| `tempest_fastapi_sdk.sse` | `EventStream`, `SSEBroker` (multi-worker fan-out via Redis), `ServerSentEvent`, `sse_response` |
+| `tempest_fastapi_sdk.sse` | `EventStream` (bounded queue + `overflow` backpressure), `SSEBroker` (multi-worker fan-out via Redis, `.response()` lifecycle helper), `ServerSentEvent`, `sse_response` (`on_disconnect=` cleanup) |
 | `tempest_fastapi_sdk.cache` *(extra: `[cache]`)* | `AsyncRedisManager`, `cached` (with `namespace` / `tags`), `CacheInvalidator`, `namespace_registry_key`, `tag_registry_key` |
 | `tempest_fastapi_sdk.flags` | `FeatureFlags`, `FeatureFlagBackend`, `MemoryFeatureFlagBackend`, `EnvFeatureFlagBackend`, `RedisFeatureFlagBackend`, `CompositeFeatureFlagBackend`, `make_flag_dependency`, `coerce_flag` |
 | `tempest_fastapi_sdk.webpush` *(extra: `[webpush]`)* | `WebPushDispatcher`, `WebPushSubscriptionService`, `make_web_push_router`, `WebPushError`, `WebPushGoneError`, `WebPushSubscriptionSchema`, `WebPushKeysSchema`, `WebPushPayloadSchema` |
@@ -2336,7 +2336,7 @@ import asyncio
 
 from fastapi import APIRouter
 
-from tempest_fastapi_sdk import EventStream, sse_response
+from tempest_fastapi_sdk import EventStream
 
 router = APIRouter()
 
@@ -2351,8 +2351,9 @@ async def events() -> "StreamingResponse":  # forward-declared by Starlette
             await asyncio.sleep(1)
         await stream.close()
 
-    asyncio.create_task(producer())
-    return sse_response(stream.stream())
+    task = asyncio.create_task(producer())
+    # on_disconnect cancels the producer when the client drops — no leak.
+    return stream.response(on_disconnect=task.cancel)
 ```
 
 Browser side:
@@ -2364,6 +2365,8 @@ es.addEventListener("counter", (e) => console.log("got", JSON.parse(e.data)));
 
 `heartbeat_seconds` emits a `: keepalive` SSE comment when idle so load-balancers don't close long-lived connections. `ServerSentEvent.data` accepts strings, bytes or any JSON-serializable Python object — non-strings are JSON-encoded automatically. Pass `retry=` to hint the browser at the reconnect delay (milliseconds).
 
+The queue is **bounded** (`max_queue`, default `1000`): a slow client can't grow memory without limit. `overflow` picks the eviction policy — `"drop_oldest"` (default), `"drop_newest"`, or `"block"` (real backpressure); `EventStream.dropped_events` counts the discards. For broadcast, `SSEBroker.response(channel)` bundles `register` + `sse_response` + `unregister`-on-disconnect in one call. Authenticating an `EventSource` (which can't send an `Authorization` header): prefer a session cookie (`make_jwt_user_dependency(..., cookie_name="access_token")` + `withCredentials`); for cookieless clients pass a short-lived access token in the query string with `query_param="access_token"` (over TLS, scrubbed from logs). See the [SSE recipe](https://mauriciobenjamin700.github.io/tempest-fastapi-sdk/recipes/sse/) for the full guide.
+
 ### Web Push notifications recipe
 
 `WebPushDispatcher` wraps the synchronous `pywebpush` library in `asyncio.to_thread` and surfaces the two errors the application cares about: `WebPushGoneError` (HTTP 404/410 — delete the subscription) and `WebPushError` (everything else). Install with `[webpush]`.

{tempest_fastapi_sdk-0.90.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.90.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.90.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.90.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