tempest-fastapi-sdk 0.48.0__tar.gz → 0.49.0__tar.gz

{tempest_fastapi_sdk-0.48.0 → tempest_fastapi_sdk-0.49.0}/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.49.0] — 2026-06-12
+
+### Added
+
+- **`UserAuthService.current_user_dependency()` — built-in
+  authenticated-user dependency.** Projects no longer hand-write a
+  `load_user` callable plus a second `JWTUtils` to read the
+  `current_user` from a bearer token. The service now exposes
+  `get_user(subject, session)` (session-explicit), `load_user(subject)`
+  (opens its own session from the `db=` handle), and
+  `current_user_dependency(*, soft=False)` which wraps
+  `make_jwt_user_dependency` with the service's **own** `JWTUtils` and
+  `load_user` — so the token is verified with the same secret it was
+  signed with, eliminating the divergent-secret footgun. Wiring
+  collapses to `get_current_user = auth_service.current_user_dependency()`
+  / `auth_service.current_user_dependency(soft=True)`. Requires the
+  service to be built with `db=` (already an accepted constructor arg).
+  The auth-flow and HTTP recipes now teach this path.
+
 ## [0.48.0] — 2026-06-11
 
 ### Changed

{tempest_fastapi_sdk-0.48.0 → tempest_fastapi_sdk-0.49.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.48.0
+Version: 0.49.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
@@ -1156,6 +1156,16 @@ async def me(current: UserModel = Depends(get_current_user)) -> UserResponseSche
     return UserResponseSchema.model_validate(current)
 ```
 
+> **Using the bundled flow?** If you wire auth with `UserAuthService`
+> (built with `db=`), skip the hand-written `load_user` and the extra
+> `JWTUtils` — the service builds the dependency for you and verifies
+> the token with the same secret it signs with:
+>
+> ```python
+> get_current_user = auth_service.current_user_dependency()
+> get_current_user_or_none = auth_service.current_user_dependency(soft=True)
+> ```
+
 #### Soft auth (optional user)
 
 `get_current_user_or_none` above already uses `soft=True` — it returns `None` instead of raising on a missing or invalid token, so endpoints can work both authenticated and anonymous:

{tempest_fastapi_sdk-0.48.0 → tempest_fastapi_sdk-0.49.0}/README.md

@@ -1054,6 +1054,16 @@ async def me(current: UserModel = Depends(get_current_user)) -> UserResponseSche
     return UserResponseSchema.model_validate(current)
 ```
 
+> **Using the bundled flow?** If you wire auth with `UserAuthService`
+> (built with `db=`), skip the hand-written `load_user` and the extra
+> `JWTUtils` — the service builds the dependency for you and verifies
+> the token with the same secret it signs with:
+>
+> ```python
+> get_current_user = auth_service.current_user_dependency()
+> get_current_user_or_none = auth_service.current_user_dependency(soft=True)
+> ```
+
 #### Soft auth (optional user)
 
 `get_current_user_or_none` above already uses `soft=True` — it returns `None` instead of raising on a missing or invalid token, so endpoints can work both authenticated and anonymous:

{tempest_fastapi_sdk-0.48.0 → tempest_fastapi_sdk-0.49.0}/docs/recipes/auth-flow.en.md

@@ -7,7 +7,7 @@ Since v0.31.0 the SDK ships the full local-account lifecycle — email + passwor
 1. **[Minimum setup](#minimum-setup)** — extras install + wiring four objects (`AsyncDatabaseManager`, `EmailUtils`, `UserAuthService`, `make_auth_router`).
 2. **[Concrete UserTokenModel](#concrete-usertokenmodel)** — `BaseUserTokenModel` is abstract, your project owns the concrete table.
 3. **[Endpoints](#endpoints)** — table of the 5 endpoints + payload + behavior.
-4. **[Settings (`AuthSettings`)](#settings-authsettings)** — `.env` flag by flag.
+4. **[Settings — environment variables](#settings-environment-variables)** — env vars in **six groups** (JWT, password policy, email flow, TTL, URLs/templates, backend pages) — each in a typed table, not one blob.
 5. **[Email anatomy: how link, template and URL fit together](#email-anatomy)** — disambiguates the three concepts that confuse readers the most.
 6. **[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).
 7. **[Mailhog vs smtp4dev — which to pick for local dev](#mailhog-vs-smtp4dev)** — comparison + copy-paste docker-compose snippets.
@@ -53,6 +53,7 @@ emails = EmailUtils(
 )
 
 auth_service = UserAuthService(
+    db=db,                    # required for current_user_dependency (see final section)
     user_model=UserModel,
     token_model=UserTokenModel,
     auth_settings=settings,   # mixes AuthSettings (see section 4)
@@ -131,9 +132,9 @@ uv run tempest db upgrade
 
 ---
 
-## Settings (`AuthSettings`)
+## Settings — environment variables
 
-Mix `AuthSettings` into your `Settings` class:
+Every knob in the flow comes from settings mixins. Mix them into your `Settings` class:
 
 ```python
 # src/core/settings.py
@@ -158,30 +159,99 @@ class Settings(
     pass
 
 
-settings = Settings()
+settings: Settings = Settings()
 ```
 
-Variables (with production-safe defaults):
+!!! info "The attribute name **is** the env var name"
+    Every attribute in the tables below is read from an environment variable of the **same name**, case-sensitive, **no prefix**. `AUTH_PASSWORD_MIN_LENGTH` in `.env` → `settings.AUTH_PASSWORD_MIN_LENGTH`. They all have defaults — you only set what you want to change.
 
-```bash
-# .env — email flow
-AUTH_AUTO_ACTIVATE=false                # true = skip activation, return JWT immediately
-AUTH_RETURN_TOKEN_IN_RESPONSE=false     # true = link in body instead of email
-AUTH_PASSWORD_MIN_LENGTH=12              # fully configurable (1+, e.g. 4); single source of truth
-AUTH_PASSWORD_REQUIRE_COMPLEXITY=false  # true = require lowercase + uppercase + digit + special AND force a floor of 8
+The variables split across **two mixins** and **six concern groups**. They're separated on purpose: a password is not the same thing as an email, and authentication (JWT) is not the same thing as account activation.
 
-# .env — token TTL
-AUTH_ACTIVATION_TTL_SECONDS=604800      # 7 days
-AUTH_PASSWORD_RESET_TTL_SECONDS=3600    # 1 hour
+### Group 1 — Authentication / JWT (`JWTSettings`)
 
-# .env — URLs pointing to YOUR FRONTEND (NOT the backend)
-AUTH_ACTIVATION_URL_TEMPLATE=https://app.example.com/activate?token={token}
-AUTH_PASSWORD_RESET_URL_TEMPLATE=https://app.example.com/reset?token={token}
+Controls the signing and lifetime of the tokens login returns. **It's the same `JWT_SECRET` the `get_current_user` dependency uses to verify** (see [Getting the `current_user`](#getting-the-current_user-from-the-request)).
 
-# .env — Jinja2 filenames inside EmailUtils.template_dir
-AUTH_ACTIVATION_TEMPLATE=activation.html
-AUTH_PASSWORD_RESET_TEMPLATE=password_reset.html
-```
+| Env var | Type | Default | What it does |
+|---------|------|---------|--------------|
+| `JWT_SECRET` | `str` (≥32 bytes) | `change-me-…-32` | HMAC secret that signs the JWT. **Must be overridden in production.** |
+| `JWT_ALGORITHM` | `str` | `HS256` | JOSE algorithm. `HS256`/`HS512` (symmetric secret) or `RS256` (key pair). |
+| `JWT_ACCESS_TTL_SECONDS` | `int` (≥1) | `3600` | **Access token** lifetime (1 h). Short by design — renew via refresh. |
+| `JWT_REFRESH_TTL_SECONDS` | `int` (≥1) | `604800` | **Refresh token** lifetime (7 days). |
+| `JWT_ISSUER` | `str \| None` | `None` | `iss` claim. `None` omits the claim. |
+
+!!! danger "The default `JWT_SECRET` leaks tokens"
+    The default `change-me-change-me-change-me-32` exists only to boot locally. In production, **anyone** with the default can forge a valid JWT. Generate a strong secret (`openssl rand -base64 48`) and inject it via a secret manager — never commit it.
+
+### Group 2 — Password policy (`AuthSettings`)
+
+| Env var | Type | Default | What it does |
+|---------|------|---------|--------------|
+| `AUTH_PASSWORD_MIN_LENGTH` | `int` (≥1) | `12` | Minimum length accepted on signup **and** reset. |
+| `AUTH_PASSWORD_REQUIRE_COMPLEXITY` | `bool` | `false` | `true` = require 1 lowercase + 1 uppercase + 1 digit + 1 special character. |
+
+These two interact — **this is where it usually gets confusing**. The exact rule:
+
+- **`complexity=false` (default):** only length matters. Any password with `≥ AUTH_PASSWORD_MIN_LENGTH` characters passes, with no composition requirement.
+- **`complexity=true`:** on top of the 4 character classes, the **effective** length floor becomes `max(AUTH_PASSWORD_MIN_LENGTH, 8)`. That is, an `AUTH_PASSWORD_MIN_LENGTH` below 8 is **ignored** while complexity is on.
+
+Decision table:
+
+| `MIN_LENGTH` | `REQUIRE_COMPLEXITY` | Password accepted when |
+|--------------|----------------------|------------------------|
+| `12` | `false` | `≥ 12` chars, any composition |
+| `4` | `false` | `≥ 4` chars, any composition (low floor, dev-only) |
+| `4` | `true` | `≥ 8` chars (floor 8 **overrides** the 4) **+** the 4 classes |
+| `16` | `true` | `≥ 16` chars **+** the 4 classes |
+
+!!! warning "The floor is the single source of truth"
+    The request schemas (`SignupSchema`, `PasswordResetConfirmSchema`) impose **no** length bound of their own — they delegate to these two vars. Lowering `AUTH_PASSWORD_MIN_LENGTH` to `4` genuinely relaxes validation on the route too. There is no hidden second limit in the schema "protecting" you.
+
+### Group 3 — Email flow control (`AuthSettings`)
+
+Decide **whether** and **how** the link reaches the user. They map directly to the [five operating modes](#five-operating-modes).
+
+| Env var | Type | Default | What it does |
+|---------|------|---------|--------------|
+| `AUTH_AUTO_ACTIVATE` | `bool` | `false` | `true` = user is born active, skips activation, signup returns the JWT pair directly (Mode D). **Never in production.** |
+| `AUTH_RETURN_TOKEN_IN_RESPONSE` | `bool` | `false` | `true` = activation/reset link goes in the JSON body instead of the email (Mode C). |
+
+### Group 4 — Account token TTL (`AuthSettings`)
+
+Lifetime of the **single-use** tokens (activation / reset) — distinct from the Group 1 JWTs.
+
+| Env var | Type | Default | What it does |
+|---------|------|---------|--------------|
+| `AUTH_ACTIVATION_TTL_SECONDS` | `int` (≥60) | `604800` | Activation token lifetime (7 days). |
+| `AUTH_PASSWORD_RESET_TTL_SECONDS` | `int` (≥60) | `3600` | Reset token lifetime (1 h). Shorter is safer. |
+
+### Group 5 — Email URLs and templates (`AuthSettings`)
+
+| Env var | Type | Default | What it does |
+|---------|------|---------|--------------|
+| `AUTH_ACTIVATION_URL_TEMPLATE` | `str` | `http://localhost:3000/activate?token={token}` | URL that goes in the email; `{token}` is substituted. **Points at the frontend** (except in Mode E). |
+| `AUTH_PASSWORD_RESET_URL_TEMPLATE` | `str` | `http://localhost:3000/reset-password?token={token}` | Same, for reset. |
+| `AUTH_ACTIVATION_TEMPLATE` | `str` | `activation.html` | Jinja2 filename of the activation **email HTML**, resolved against `EmailUtils.template_dir`. |
+| `AUTH_PASSWORD_RESET_TEMPLATE` | `str` | `password_reset.html` | Same, for reset. |
+
+!!! warning "URL template ≠ Jinja2 template"
+    `*_URL_TEMPLATE` is a `.format()` string with `{token}` — it's the **link**. `*_TEMPLATE` is the name of an `.html` file — it's the **email that wraps the link**. Confusing the two is the #1 mistake. Full detail in [Email anatomy](#email-anatomy).
+
+### Group 6 — Backend-rendered pages (Mode E, `AuthSettings`)
+
+Only relevant when `AUTH_BACKEND_LINKS=true`. See [Mode E](#five-operating-modes) for the full flow.
+
+| Env var | Type | Default | What it does |
+|---------|------|---------|--------------|
+| `AUTH_BACKEND_LINKS` | `bool` | `false` | `true` = mounts 3 extra HTML endpoints; the email link points at the **backend**, not the frontend. |
+| `AUTH_LOGIN_URL` | `str \| None` | `None` | Login URL on the "go to login" button of success pages. `None` hides the button. |
+| `AUTH_ACTIVATION_SUCCESS_TEMPLATE` | `str` | `activation_success.html` | Activation OK HTML page. |
+| `AUTH_ACTIVATION_ERROR_TEMPLATE` | `str` | `activation_error.html` | Activation error HTML page. |
+| `AUTH_PASSWORD_RESET_FORM_TEMPLATE` | `str` | `password_reset_form.html` | New-password HTML form. |
+| `AUTH_PASSWORD_RESET_SUCCESS_TEMPLATE` | `str` | `password_reset_success.html` | Reset OK HTML page. |
+| `AUTH_PASSWORD_RESET_ERROR_TEMPLATE` | `str` | `password_reset_error.html` | Reset error HTML page. |
+
+!!! note "MFA / TOTP has its own vars"
+    When `AUTH_MFA_ENABLED=true`, `AuthSettings` also exposes `AUTH_MFA_ISSUER`, `AUTH_MFA_RECOVERY_CODES_COUNT`, `AUTH_MFA_TOKEN_TTL_SECONDS` and `AUTH_MFA_VERIFY_WINDOW`. They're out of scope for this recipe (signup/activate/login/reset) — covered in the MFA recipe.
 
 ---
 
@@ -515,6 +585,104 @@ emails/                            # ← template_dir="emails"
 
 ---
 
+## Getting the `current_user` from the request
+
+`make_auth_router` **issues** the JWT pair (login/activate return `access_token` + `refresh_token`). But what next? When the frontend sends `Authorization: Bearer <access_token>` to **your own** routes, you need a dependency that decodes the token and resolves the user.
+
+Since v0.49.0, `UserAuthService` builds that dependency for you — `current_user_dependency()`. It:
+
+1. Reads `Authorization: Bearer <jwt>` via `HTTPBearer`.
+2. Decodes and verifies the JWT with **the same `JWTUtils` the service signs with** — no second secret to keep in sync.
+3. Pulls the `sub` (user id) from the payload, opens a session from `db=`, and returns the persisted `UserModel`.
+
+### 1. Declare the dependency once
+
+The service already has `user_model`, `JWTUtils` and the session — so you don't write `load_user` by hand. Group both variants in `src/api/dependencies/auth.py`:
+
+```python
+# src/api/dependencies/auth.py
+from src.api.app import auth_service
+
+get_current_user = auth_service.current_user_dependency()
+get_current_user_or_none = auth_service.current_user_dependency(soft=True)
+```
+
+!!! info "Requires `db=` on `UserAuthService`"
+    `current_user_dependency` resolves the user by opening its own session, so the service must have been created with `db=` (the `AsyncDatabaseManager` from [Minimum setup](#minimum-setup)). Because it reuses the internal `self.jwt`, the token is verified with the **same** secret that signed it — the divergent-`JWT_SECRET` footgun is gone.
+
+??? note "No `UserAuthService`? Build the dependency by hand"
+    If your service doesn't use the bundled flow, the `make_jwt_user_dependency` primitive accepts any `JWTUtils` + a one-argument async `user_loader`:
+
+    ```python
+    from uuid import UUID
+
+    from tempest_fastapi_sdk import JWTUtils, make_jwt_user_dependency
+
+    from src.api.app import db
+    from src.core.settings import settings
+    from src.db.models import UserModel
+    from src.db.repositories import UserRepository
+
+    tokens: JWTUtils = JWTUtils(
+        secret=settings.JWT_SECRET,
+        algorithm=settings.JWT_ALGORITHM,
+    )
+
+
+    async def load_user(subject: str) -> UserModel:
+        """Resolve the JWT subject (a UUID string) to the persisted user."""
+        async with db.get_session_context() as session:
+            repo: UserRepository = UserRepository(session)
+            return await repo.get_by_id(UUID(subject))
+
+
+    get_current_user = make_jwt_user_dependency(tokens, load_user)
+    get_current_user_or_none = make_jwt_user_dependency(tokens, load_user, soft=True)
+    ```
+
+    Heads up: here `tokens` **must** use the same `JWT_SECRET` / `JWT_ALGORITHM` as login, otherwise every valid token is rejected.
+
+### 2. Inject it on the route with `Depends`
+
+```python
+# src/api/routers/users.py
+from fastapi import APIRouter, Depends
+
+from src.api.dependencies.auth import get_current_user
+from src.db.models import UserModel
+from src.schemas import UserResponseSchema
+
+router: APIRouter = APIRouter(prefix="/users", tags=["users"])
+
+
+@router.get("/me")
+async def me(current: UserModel = Depends(get_current_user)) -> UserResponseSchema:
+    """Return the user who owns the request's bearer token."""
+    return UserResponseSchema.model_validate(current)
+```
+
+`current` **is** the `UserModel` the service resolved — typed, persisted, ready to use. Missing or invalid token → `401 UnauthorizedException` before the route body runs.
+
+### 3. Optional auth — `soft=True`
+
+For routes that work both authenticated **and** anonymous (e.g. a public feed that personalizes when logged in), use the `soft` variant — it returns `None` instead of raising:
+
+```python
+@router.get("/feed")
+async def feed(
+    current: UserModel | None = Depends(get_current_user_or_none),
+) -> list[PostResponseSchema]:
+    """Public feed; personalizes the ranking when a user is logged in."""
+    if current is None:
+        return await feed_service.public()
+    return await feed_service.personalized(current.id)
+```
+
+!!! tip "Role and permission are the next step"
+    When the route needs a **role** (`admin`) or **permission** (`users:write`) and not just "logged in", swap for `make_role_dependency` / `make_permission_dependency`. See the [HTTP recipe »](http.en.md) — same `JWTUtils`, same `Depends` pattern.
+
+---
+
 ## Next steps
 
 - **[Idempotency »](idempotency.en.md)** — protect `POST /auth/signup` from retries that would duplicate the row.

{tempest_fastapi_sdk-0.48.0 → tempest_fastapi_sdk-0.49.0}/docs/recipes/auth-flow.md

@@ -7,7 +7,7 @@ Desde v0.31.0 o SDK fornece o ciclo completo de conta local — signup com email
 1. **[Setup mínimo](#setup-minimo)** — instalação dos extras + wiring de quatro objetos (`AsyncDatabaseManager`, `EmailUtils`, `UserAuthService`, `make_auth_router`).
 2. **[UserTokenModel concreto](#usertokenmodel-concreto)** — `BaseUserTokenModel` é abstrato, projeto cria a tabela final.
 3. **[Endpoints](#endpoints)** — tabela dos 5 endpoints + payload + comportamento.
-4. **[Settings (`AuthSettings`)](#settings-authsettings)** — `.env` flag a flag.
+4. **[Settings — variáveis de ambiente](#settings-variaveis-de-ambiente)** — env vars em **seis grupos** (JWT, política de senha, fluxo de e-mail, TTL, URLs/templates, páginas backend) — cada uma em tabela tipada, não num blob.
 5. **[Anatomia de um e-mail: como link, template e URL se encaixam](#anatomia-de-um-e-mail)** — desambigua os três conceitos que mais confundem.
 6. **[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).
 7. **[Mailhog vs smtp4dev — qual escolher pra dev local](#mailhog-vs-smtp4dev)** — comparativo + receitas docker-compose copy-paste.
@@ -53,6 +53,7 @@ emails = EmailUtils(
 )
 
 auth_service = UserAuthService(
+    db=db,                    # necessário pra current_user_dependency (ver seção final)
     user_model=UserModel,
     token_model=UserTokenModel,
     auth_settings=settings,   # mistura AuthSettings (ver seção 4)
@@ -131,9 +132,9 @@ uv run tempest db upgrade
 
 ---
 
-## Settings (`AuthSettings`)
+## Settings — variáveis de ambiente
 
-Mixe `AuthSettings` na sua classe `Settings`:
+Toda a config do flow vem de mixins de settings. Mixe-as na sua classe `Settings`:
 
 ```python
 # src/core/settings.py
@@ -158,30 +159,99 @@ class Settings(
     pass
 
 
-settings = Settings()
+settings: Settings = Settings()
 ```
 
-Variáveis (com defaults seguros pra produção):
+!!! info "Nome do atributo **é** o nome da env var"
+    Cada atributo das tabelas abaixo é lido de uma variável de ambiente de **mesmo nome**, case-sensitive, **sem prefixo**. `AUTH_PASSWORD_MIN_LENGTH` no `.env` → `settings.AUTH_PASSWORD_MIN_LENGTH`. Todos têm default — você só seta o que quer mudar.
 
-```bash
-# .env — fluxo de e-mail
-AUTH_AUTO_ACTIVATE=false                # true = pula activation, devolve JWT direto
-AUTH_RETURN_TOKEN_IN_RESPONSE=false     # true = link no body em vez de e-mail
-AUTH_PASSWORD_MIN_LENGTH=12              # totalmente configurável (1+, ex.: 4); fonte única da verdade
-AUTH_PASSWORD_REQUIRE_COMPLEXITY=false  # true = exige minúscula + maiúscula + dígito + especial E força piso de 8
+As variáveis se dividem em **dois mixins** e **seis grupos de concern**. Elas estão separadas de propósito: senha não é a mesma coisa que e-mail, e autenticação (JWT) não é a mesma coisa que ativação de conta.
 
-# .env — TTL dos tokens
-AUTH_ACTIVATION_TTL_SECONDS=604800      # 7 dias
-AUTH_PASSWORD_RESET_TTL_SECONDS=3600    # 1 hora
+### Grupo 1 — Autenticação / JWT (`JWTSettings`)
 
-# .env — URLs apontando para SEU FRONTEND (NÃO o backend)
-AUTH_ACTIVATION_URL_TEMPLATE=https://app.example.com/activate?token={token}
-AUTH_PASSWORD_RESET_URL_TEMPLATE=https://app.example.com/reset?token={token}
+Controla a assinatura e validade dos tokens que o login devolve. **É o mesmo `JWT_SECRET` que a dependency `get_current_user` usa pra validar** (veja [Pegando o `current_user`](#pegando-o-current_user-da-requisicao)).
 
-# .env — nomes dos arquivos Jinja2 dentro do template_dir do EmailUtils
-AUTH_ACTIVATION_TEMPLATE=activation.html
-AUTH_PASSWORD_RESET_TEMPLATE=password_reset.html
-```
+| Env var | Tipo | Default | O que faz |
+|---------|------|---------|-----------|
+| `JWT_SECRET` | `str` (≥32 bytes) | `change-me-…-32` | Segredo HMAC que assina o JWT. **Obrigatório trocar em produção.** |
+| `JWT_ALGORITHM` | `str` | `HS256` | Algoritmo JOSE. `HS256`/`HS512` (segredo simétrico) ou `RS256` (par de chaves). |
+| `JWT_ACCESS_TTL_SECONDS` | `int` (≥1) | `3600` | Validade do **access token** (1 h). Curto por design — renove via refresh. |
+| `JWT_REFRESH_TTL_SECONDS` | `int` (≥1) | `604800` | Validade do **refresh token** (7 dias). |
+| `JWT_ISSUER` | `str \| None` | `None` | Claim `iss`. `None` omite o claim. |
+
+!!! danger "`JWT_SECRET` default vaza tokens"
+    O default `change-me-change-me-change-me-32` existe só pra subir local. Em produção, **qualquer um** com o default consegue forjar um JWT válido. Gere um segredo forte (`openssl rand -base64 48`) e injete por secret manager — nunca commite.
+
+### Grupo 2 — Política de senha (`AuthSettings`)
+
+| Env var | Tipo | Default | O que faz |
+|---------|------|---------|-----------|
+| `AUTH_PASSWORD_MIN_LENGTH` | `int` (≥1) | `12` | Comprimento mínimo aceito no signup **e** no reset. |
+| `AUTH_PASSWORD_REQUIRE_COMPLEXITY` | `bool` | `false` | `true` = exige 1 minúscula + 1 maiúscula + 1 dígito + 1 caractere especial. |
+
+Os dois interagem — **é aqui que costuma confundir**. A regra exata:
+
+- **`complexity=false` (default):** só o comprimento importa. Qualquer senha com `≥ AUTH_PASSWORD_MIN_LENGTH` caracteres passa, sem exigência de composição.
+- **`complexity=true`:** além das 4 classes de caracteres, o piso de comprimento **efetivo** vira `max(AUTH_PASSWORD_MIN_LENGTH, 8)`. Ou seja, um `AUTH_PASSWORD_MIN_LENGTH` abaixo de 8 é **ignorado** enquanto a complexidade está ligada.
+
+Tabela de decisão:
+
+| `MIN_LENGTH` | `REQUIRE_COMPLEXITY` | Senha aceita quando |
+|--------------|---------------------|---------------------|
+| `12` | `false` | `≥ 12` chars, qualquer composição |
+| `4` | `false` | `≥ 4` chars, qualquer composição (piso baixo, dev-only) |
+| `4` | `true` | `≥ 8` chars (piso 8 **sobrescreve** o 4) **+** as 4 classes |
+| `16` | `true` | `≥ 16` chars **+** as 4 classes |
+
+!!! warning "O piso é fonte única da verdade"
+    Os schemas de request (`SignupSchema`, `PasswordResetConfirmSchema`) **não** impõem limite próprio de comprimento — eles delegam pra essas duas vars. Baixar `AUTH_PASSWORD_MIN_LENGTH` pra `4` realmente afrouxa a validação na rota também. Não há um segundo limite escondido no schema "te protegendo".
+
+### Grupo 3 — Controle do fluxo de e-mail (`AuthSettings`)
+
+Decidem **se** e **como** o link chega ao usuário. Mapeiam direto nos [cinco modos de operação](#cinco-modos-de-operacao).
+
+| Env var | Tipo | Default | O que faz |
+|---------|------|---------|-----------|
+| `AUTH_AUTO_ACTIVATE` | `bool` | `false` | `true` = user nasce ativo, pula activation, signup devolve JWT pair direto (Modo D). **Nunca em produção.** |
+| `AUTH_RETURN_TOKEN_IN_RESPONSE` | `bool` | `false` | `true` = link de ativação/reset vai no corpo JSON em vez do e-mail (Modo C). |
+
+### Grupo 4 — TTL dos tokens de conta (`AuthSettings`)
+
+Validade dos tokens **de uso único** (ativação / reset) — distintos dos JWT do grupo 1.
+
+| Env var | Tipo | Default | O que faz |
+|---------|------|---------|-----------|
+| `AUTH_ACTIVATION_TTL_SECONDS` | `int` (≥60) | `604800` | Validade do token de ativação (7 dias). |
+| `AUTH_PASSWORD_RESET_TTL_SECONDS` | `int` (≥60) | `3600` | Validade do token de reset (1 h). Curto é mais seguro. |
+
+### Grupo 5 — URLs e templates de e-mail (`AuthSettings`)
+
+| Env var | Tipo | Default | O que faz |
+|---------|------|---------|-----------|
+| `AUTH_ACTIVATION_URL_TEMPLATE` | `str` | `http://localhost:3000/activate?token={token}` | URL que vai no e-mail; `{token}` é substituído. **Aponta pro frontend** (exceto no Modo E). |
+| `AUTH_PASSWORD_RESET_URL_TEMPLATE` | `str` | `http://localhost:3000/reset-password?token={token}` | Idem, para reset. |
+| `AUTH_ACTIVATION_TEMPLATE` | `str` | `activation.html` | Nome do arquivo Jinja2 do **HTML do e-mail** de ativação, resolvido no `template_dir` do `EmailUtils`. |
+| `AUTH_PASSWORD_RESET_TEMPLATE` | `str` | `password_reset.html` | Idem, para reset. |
+
+!!! warning "URL template ≠ Jinja2 template"
+    `*_URL_TEMPLATE` é uma string `.format()` com `{token}` — é o **link**. `*_TEMPLATE` é o nome de um arquivo `.html` — é o **e-mail que embrulha o link**. Confundir os dois é o erro nº 1. Detalhe completo em [Anatomia de um e-mail](#anatomia-de-um-e-mail).
+
+### Grupo 6 — Páginas renderizadas pelo backend (Modo E, `AuthSettings`)
+
+Só relevantes quando `AUTH_BACKEND_LINKS=true`. Veja o [Modo E](#cinco-modos-de-operacao) para o fluxo completo.
+
+| Env var | Tipo | Default | O que faz |
+|---------|------|---------|-----------|
+| `AUTH_BACKEND_LINKS` | `bool` | `false` | `true` = monta 3 endpoints HTML extras; o link do e-mail aponta pro **backend**, não pro frontend. |
+| `AUTH_LOGIN_URL` | `str \| None` | `None` | URL de login no botão "Ir pro login" das páginas de sucesso. `None` esconde o botão. |
+| `AUTH_ACTIVATION_SUCCESS_TEMPLATE` | `str` | `activation_success.html` | Página HTML de ativação OK. |
+| `AUTH_ACTIVATION_ERROR_TEMPLATE` | `str` | `activation_error.html` | Página HTML de ativação com erro. |
+| `AUTH_PASSWORD_RESET_FORM_TEMPLATE` | `str` | `password_reset_form.html` | Form HTML de nova senha. |
+| `AUTH_PASSWORD_RESET_SUCCESS_TEMPLATE` | `str` | `password_reset_success.html` | Página HTML de reset OK. |
+| `AUTH_PASSWORD_RESET_ERROR_TEMPLATE` | `str` | `password_reset_error.html` | Página HTML de reset com erro. |
+
+!!! note "MFA / TOTP tem suas próprias vars"
+    Quando `AUTH_MFA_ENABLED=true`, o `AuthSettings` ainda expõe `AUTH_MFA_ISSUER`, `AUTH_MFA_RECOVERY_CODES_COUNT`, `AUTH_MFA_TOKEN_TTL_SECONDS` e `AUTH_MFA_VERIFY_WINDOW`. Ficam fora do escopo desta receita (signup/activate/login/reset) — são cobertos na receita de MFA.
 
 ---
 
@@ -515,6 +585,104 @@ emails/                            # ← template_dir="emails"
 
 ---
 
+## Pegando o `current_user` da requisição
+
+`make_auth_router` **emite** o JWT pair (login/activate devolvem `access_token` + `refresh_token`). Mas e depois? Quando o frontend manda `Authorization: Bearer <access_token>` nas **suas próprias** rotas, você precisa de uma dependency que decodifica o token e resolve o usuário.
+
+Desde a v0.49.0, o próprio `UserAuthService` constrói essa dependency — `current_user_dependency()`. Ela:
+
+1. Lê `Authorization: Bearer <jwt>` via `HTTPBearer`.
+2. Decodifica e verifica o JWT com **o mesmo `JWTUtils` que o service usou pra assinar** — sem segundo segredo pra manter sincronizado.
+3. Pega o `sub` (id do usuário) do payload, abre uma sessão a partir do `db=` e devolve o `UserModel` persistido.
+
+### 1. Declare a dependency uma vez
+
+O service já tem `user_model`, `JWTUtils` e a sessão — então não precisa escrever `load_user` à mão. Junte as duas variantes no `src/api/dependencies/auth.py`:
+
+```python
+# src/api/dependencies/auth.py
+from src.api.app import auth_service
+
+get_current_user = auth_service.current_user_dependency()
+get_current_user_or_none = auth_service.current_user_dependency(soft=True)
+```
+
+!!! info "Requer `db=` no `UserAuthService`"
+    `current_user_dependency` resolve o usuário abrindo a própria sessão, então o service precisa ter sido criado com `db=` (o `AsyncDatabaseManager` do [Setup mínimo](#setup-minimo)). Como reusa o `self.jwt` interno, o token é validado com o **mesmo** segredo que assinou — o footgun de `JWT_SECRET` divergente some.
+
+??? note "Sem `UserAuthService`? Monte a dependency na mão"
+    Se o seu serviço não usa o flow bundled, a primitiva `make_jwt_user_dependency` aceita qualquer `JWTUtils` + um `user_loader` async de um argumento:
+
+    ```python
+    from uuid import UUID
+
+    from tempest_fastapi_sdk import JWTUtils, make_jwt_user_dependency
+
+    from src.api.app import db
+    from src.core.settings import settings
+    from src.db.models import UserModel
+    from src.db.repositories import UserRepository
+
+    tokens: JWTUtils = JWTUtils(
+        secret=settings.JWT_SECRET,
+        algorithm=settings.JWT_ALGORITHM,
+    )
+
+
+    async def load_user(subject: str) -> UserModel:
+        """Resolve o subject do JWT (uma string UUID) para o usuário persistido."""
+        async with db.get_session_context() as session:
+            repo: UserRepository = UserRepository(session)
+            return await repo.get_by_id(UUID(subject))
+
+
+    get_current_user = make_jwt_user_dependency(tokens, load_user)
+    get_current_user_or_none = make_jwt_user_dependency(tokens, load_user, soft=True)
+    ```
+
+    Atenção: aqui o `tokens` **precisa** usar o mesmo `JWT_SECRET` / `JWT_ALGORITHM` do login, senão todo token válido é rejeitado.
+
+### 2. Injete na rota com `Depends`
+
+```python
+# src/api/routers/users.py
+from fastapi import APIRouter, Depends
+
+from src.api.dependencies.auth import get_current_user
+from src.db.models import UserModel
+from src.schemas import UserResponseSchema
+
+router: APIRouter = APIRouter(prefix="/users", tags=["users"])
+
+
+@router.get("/me")
+async def me(current: UserModel = Depends(get_current_user)) -> UserResponseSchema:
+    """Devolve o usuário dono do bearer token da requisição."""
+    return UserResponseSchema.model_validate(current)
+```
+
+`current` **é** o `UserModel` que o service resolveu — tipado, persistido, pronto pra uso. Token ausente ou inválido → `401 UnauthorizedException` antes do corpo da rota rodar.
+
+### 3. Auth opcional — `soft=True`
+
+Para rotas que funcionam logado **e** anônimo (ex.: feed público que personaliza se houver login), use a variante `soft` — ela devolve `None` em vez de levantar:
+
+```python
+@router.get("/feed")
+async def feed(
+    current: UserModel | None = Depends(get_current_user_or_none),
+) -> list[PostResponseSchema]:
+    """Feed público; personaliza o ranking quando há usuário logado."""
+    if current is None:
+        return await feed_service.public()
+    return await feed_service.personalized(current.id)
+```
+
+!!! tip "Role e permission são o próximo passo"
+    Quando a rota precisa de **papel** (`admin`) ou **permissão** (`users:write`) e não só "estar logado", troque por `make_role_dependency` / `make_permission_dependency`. Veja a [receita HTTP »](http.md) — mesma `JWTUtils`, mesmo padrão de `Depends`.
+
+---
+
 ## Próximos passos
 
 - **[Idempotência »](idempotency.md)** — proteja `POST /auth/signup` de retentativas que duplicariam linha.

{tempest_fastapi_sdk-0.48.0 → tempest_fastapi_sdk-0.49.0}/docs/recipes/http.en.md

@@ -114,6 +114,9 @@ Four dependency factories live in `tempest_fastapi_sdk.api.dependencies.auth`
 | `make_jwt_user_dependency(tokens, user_loader, soft=False, subject_claim="sub")` | Decode the bearer JWT, await `user_loader(subject)`, return the loaded user. |
 | `make_role_dependency(tokens, ["admin"], require_all=False, roles_claim="roles")` / `make_permission_dependency(tokens, ["users:write"], require_all=True, permissions_claim="permissions")` | Decode the bearer JWT and gate the route on roles / permissions. |
 
+!!! tip "Using the bundled flow? Skip `load_user`"
+    If you wire auth with `UserAuthService` + `make_auth_router`, you don't write `load_user` or instantiate a `JWTUtils` here — call `auth_service.current_user_dependency()` (and `.current_user_dependency(soft=True)`), which reuses the service's internal `JWTUtils`. See the [auth recipe »](auth-flow.en.md#getting-the-current_user-from-the-request). The example below is the manual wiring, for when you're **not** using the service.
+
 ```python
 # src/api/dependencies/auth.py
 from uuid import UUID

{tempest_fastapi_sdk-0.48.0 → tempest_fastapi_sdk-0.49.0}/docs/recipes/http.md

@@ -114,6 +114,9 @@ Quatro factories de dependência vivem em `tempest_fastapi_sdk.api.dependencies.
 | `make_jwt_user_dependency(tokens, user_loader, soft=False, subject_claim="sub")` | Decodifica o bearer JWT, aguarda `user_loader(subject)`, retorna o usuário carregado. |
 | `make_role_dependency(tokens, ["admin"], require_all=False, roles_claim="roles")` / `make_permission_dependency(tokens, ["users:write"], require_all=True, permissions_claim="permissions")` | Decodifica o bearer JWT e controla a rota por roles / permissões. |
 
+!!! tip "Usa o flow bundled? Pule o `load_user`"
+    Se você monta auth com `UserAuthService` + `make_auth_router`, não precisa escrever `load_user` nem instanciar um `JWTUtils` aqui — chame `auth_service.current_user_dependency()` (e `.current_user_dependency(soft=True)`), que reusa o `JWTUtils` interno do service. Veja a [receita de auth »](auth-flow.md#pegando-o-current_user-da-requisicao). O exemplo abaixo é a montagem manual, pra quando você **não** usa o service.
+
 ```python
 # src/api/dependencies/auth.py
 from uuid import UUID

{tempest_fastapi_sdk-0.48.0 → tempest_fastapi_sdk-0.49.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-fastapi-sdk"
-version = "0.48.0"
+version = "0.49.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.48.0 → tempest_fastapi_sdk-0.49.0}/tempest_fastapi_sdk/__init__.py

@@ -250,7 +250,7 @@ from tempest_fastapi_sdk.websockets import (
     make_websocket_router,
 )
 
-__version__: str = "0.48.0"
+__version__: str = "0.49.0"
 
 __all__: list[str] = [
     "BASE_COLUMN_ORDER",